Skip to content

AGENTS.md

Latest commit

 

History

History
80 lines (50 loc) · 2.99 KB

AGENTS.md

File metadata and controls

80 lines (50 loc) · 2.99 KB
Raw

AGENTS.md

Project Context

This repository is differ-next, the source for the public npm package @differ/next.

The package provides Next.js runtime instrumentation primitives for Differ-managed apps. It owns only runtime/client code and the public integration surface that emits structured fault envelopes to Differ-reserved same-origin endpoints.

Generated integration tooling outside this repository is responsible for installing @differ/next, creating Next.js file-convention shims, wiring error boundaries, and adding semantic handled-failure reporting to app code.

Server-side Differ systems receive and process the emitted envelopes. Keep their implementation details out of this repository.

Repository Boundaries

Do not add secrets, private API keys, or private Differ implementation details.

Do not require customer authors to manually configure Sentry-style DSNs. Prefer same-origin reserved endpoints such as /__differ/faults/client and /__differ/faults/server.

Do not implement server-side processing or customer-app integration logic in this package.

The browser package reports observations, not root-cause conclusions. Keep wording, payload fields, and exported APIs aligned with that boundary.

Keep client payloads privacy-bounded:

  • no cookies
  • no auth headers
  • no localStorage dumps
  • no sessionStorage dumps
  • no request bodies by default
  • bounded messages and stacks
  • optional bounded Differ runtime identity only as a validated dusr_<uuid> id and "human" / "agent" client type

Keep the package small, stable, and boring. It should be easy for generated integration code to consume.

Public API Rules

Build public, documented entrypoints.

Treat every exported type as API. Avoid casual renames, field reshaping, or broad exports from internal modules.

Package exports should remain explicit. Prefer adding named entrypoints over exposing internals.

Examples should stay minimal and Next.js-oriented.

Documentation Covenant

Keep docs/generated-integration-manual.md current with the package behavior. Update it in the same change when modifying:

  • public exports or entrypoints
  • generated shim examples
  • default reserved endpoints
  • envelope kind values or payload shape
  • client, server, proxy, or transport behavior
  • privacy, redaction, bounding, dedupe, or rate-limit behavior
  • e2e fixture coverage or target-app validation expectations
  • known Next.js runtime constraints

Testing Expectations

Add focused tests for runtime behavior, especially:

  • envelope shaping
  • redaction and bounding
  • dedupe
  • transport behavior

Prefer small deterministic tests over framework-heavy fixtures unless the behavior truly requires Next.js runtime coverage.

Run the documentation sync check before publishing-facing changes:

npm run check:docs

Development Notes

Use the boring TypeScript library toolchain already in this repo. Avoid adding frameworks unless they are necessary for package-level behavior.

Build output belongs in dist/. Source belongs in src/.