agent-js: Instructions file for Codex

agent-js

You are running in a container. Make all changes to /agent-js at the root of the filesystem.

This is a Node.js project. Only Node.js APIs should be used. Use node for running and testing, and pnpm as the package manager.

Development

After every change, run linting, types, tests, and formatting:

pnpm run lint
pnpm run types
pnpm run test
pnpm run format

Or all at once:

pnpm run ci

Guidelines

• Never add comments
• Minimize diffs — only change what's necessary
• All changes must have test coverage
• Prefer assert.deepStrictEqual over multiple individual field assertions — check the whole object in one call
• Never use content: result.content in deepStrictEqual assertions — it's a tautology. Inline the actual expected value
• Never use assert.ok(result.includes(...)) — assert on the whole string with assert.equal or assert.strictEqual
• Only use === and !==; never use ==, !=, or truthy/falsy coercions like if (obj) or if (!obj). Use ! only on boolean expressions
• For string assertions with newlines: use template literals when the string contains any newline that is not a single trailing one. If it's just a single trailing newline, use "...\n" instead
• For fs, import fsDeps directly from deps.ts. In tests, use setupFakeDeps() from test-helpers.ts to mock all fs methods, processEnv, and processStdout globally. Use testFs._files / testFs._dirs / testFs._globResults to set up fixture state. Import testFs and setupFakeDeps from ./test-helpers.ts.
• processEnv.get and processStdout.write are also in deps.ts and mocked by setupFakeDeps(). Use testProcessEnv._set(key, value) for env vars. Override processStdout.write with an additional mock.method(processStdout, "write", ...) if you need to capture output.
• Pure utility functions do not need deps — import and call them directly in tests.

fs mocking example

Production code:

import { fsDeps } from "./deps.ts";

export function readConfig() {
  if (fsDeps.existsSync("config.json") === false) return null;
  return JSON.parse(fsDeps.readFileSync("config.json").toString());
}