CLAUDE.md for Node.js

# CLAUDE.md

Project memory for Claude Code in this Node.js repository. Read it before editing. Other agents can follow the same rules.

## Stack

This repository is a TypeScript program on Node.js. Use ESM if the package already does, and prefer `node:` imports for built-in modules. The default test runner, when one is needed, is node:test.

## Layout

- Source lives in `src/`. Tests sit next to the code or in `test/`, matching the repo.
- The package entry and exports field are the public API. Do not add a second entrypoint casually.
- Scripts stay in `package.json`. Do not document a command the package does not define.

## Commands

- Dev: `npm run dev`
- Typecheck: `npx tsc --noEmit`
- Tests: `npm test`
- Lint: `npm run lint`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Import Node built-ins with the `node:` prefix.
- Keep the module system the package already uses. Do not mix require and import in new files.
- Parse untrusted input at the edge. The rest of the code should see typed values.
- If there is no test runner yet and tests are requested, use node:test with node:assert.
- Async functions return promises. Do not wrap them in a manual Promise constructor.
- Do not add a framework, ORM, or validator that is not already a dependency.

## Testing

Add or update tests when behavior changes.

Use the existing runner. If the repo has none, add a node:test file for the behavior you changed.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Throw an Error, or return a Result-style value if the file already does. Include the operation that failed.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not swallow a rejected promise with an empty catch.
- Do not read `process.env` in dozens of files. Read it once at the boundary.
- Do not change the published export map unless the task is the public API.
- Do not add `@ts-ignore` to get past a type you can name.

## Done when

- The requested behavior works.
- `npx tsc --noEmit` passes for the project, and `npm test` passes when tests exist.
- The diff stays inside the task.
- You list anything you could not run.