- Use pnpm (
pnpm install) on Node 24 (.node-version). - Install agent skills with
pnpm skills:install(agents.toml).
| 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 |
| 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 |
- The repository is a pnpm workspace. The root is private and has only the tools.
packages/roachis the npm package@sentry/roach: the client, the vitest integration, and the action.packages/serviceis the private@sentry/roach-service: the service and the proxy. Put a shared dependency version in the catalog ofpnpm-workspace.yaml, and refer to it ascatalog:. - Use Node built-ins and the
opensslcommand.@sentry/roachhas no runtime dependencies.@sentry/nodeis the only one of@sentry/roach-service, and onlypackages/service/src/service.tsimports it. The service imports@sentry/roachby package name (workspace:*), never by a relative path.@sentry/roachnever imports the service.packages/roach/tests/package.test.tsfails when an export or the action loads a package that is not a Node built-in or vitest, or when a file inpackages/roach/src/is not used. deploy/gcp/is the production setup (Terraform). Change it in the same change when the service config (RoachServiceConfig) changes. TheImageworkflow runsterraform fmt -checkandterraform validateon it.- Node runs both packages as TypeScript with type stripping. Use only erasable syntax, and import local files with the
.tsextension. - 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.mdin 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 withstartTestService()andstartUpstream()oftests/harness.ts. Wrap a tight timing limit inbudget(), 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.
AI commits MUST include:
Co-Authored-By: (the agent's name and attribution byline)