Skip to content

Latest commit

 

History

History
51 lines (40 loc) · 3.88 KB

AGENTS.md

File metadata and controls

51 lines (40 loc) · 3.88 KB

Agent Instructions

Package Manager

  • Use pnpm (pnpm install) on Node 24 (.node-version).
  • Install agent skills with pnpm skills:install (agents.toml).

Commands

Task Command
Test file pnpm exec vitest run packages/service/tests/recording.test.ts
Test case pnpm exec vitest run packages/service/tests/recording.test.ts -t "…"
Lint file pnpm exec oxlint --deny-warnings packages/service/src/server.ts
Format pnpm format
Typecheck pnpm typecheck
Deployed shape pnpm exec vitest run packages/service/tests/deployed.test.ts
Unused code/deps pnpm knip
Everything (CI) pnpm check

External References

Need File
Usage, config, recordings, control API README.md
Service access, limits, and deploy "Service" and "Deploy" in README.md
Public types packages/roach/src/types.ts
Map of source files "Files" in README.md
Sentry queries and cache hit rate TELEMETRY.md

Key Conventions

  • The repository is a pnpm workspace. The root is private and has only the tools. packages/roach is the npm package @sentry/roach: the client, the vitest integration, and the action. packages/service is the private @sentry/roach-service: the service and the proxy. Put a shared dependency version in the catalog of pnpm-workspace.yaml, and refer to it as catalog:.
  • Use Node built-ins and the openssl command. @sentry/roach has no runtime dependencies. @sentry/node is the only one of @sentry/roach-service, and only packages/service/src/service.ts imports it. The service imports @sentry/roach by package name (workspace:*), never by a relative path. @sentry/roach never imports the service. packages/roach/tests/package.test.ts fails when an export or the action loads a package that is not a Node built-in or vitest, or when a file in packages/roach/src/ is not used.
  • deploy/gcp/ is the production setup (Terraform). Change it in the same change when the service config (RoachServiceConfig) changes. The Image workflow runs terraform fmt -check and terraform validate on it.
  • Node runs both packages as TypeScript with type stripping. Use only erasable syntax, and import local files with the .ts extension.
  • Use functions and plain objects, not classes.
  • Start each source file with a comment that says what the file owns. Give each export a short JSDoc.
  • Update README.md in the same change when behavior, config, or the control API changes.
  • Test through a real proxy and a local upstream server in packages/service/tests/. Start them with startTestService() and startUpstream() of tests/harness.ts. Wrap a tight timing limit in budget(), so that it allows for coverage, unless coverage barely slows that check. Do not mock modules. Do not reach the internet.
  • The proxy decrypts HTTPS. Never write a credential: every recording goes through packages/service/src/secrets.ts.
  • The upstream host always comes from allow, never from the client.
  • Write docs in ASD-STE100 English: common words, active voice, short sentences.

Commit Attribution

AI commits MUST include:

Co-Authored-By: (the agent's name and attribution byline)