# Development

## Toolchain

- Node.js 22.19+
- npm
- TypeScript
- Node's built-in test runner
- Prettier
- Pi 0.80 extension APIs
- Rust stable (only for the optional `tui/` delegation viewer)

Install dependencies:

```sh
npm install
```

## Commands

```sh
npm run build          # compile extension source into dist/
npm run check          # strict TypeScript check without emission
npm run format         # format source and docs
npm run format:check   # verify formatting
npm test               # build, then run offline-safe tests
npm run verify         # check + formatting + tests
npm run package:check  # build, pack, globally install, and smoke test
npm run release:preflight # prove the exact runner pin exists in npm
npm pack --dry-run     # inspect distributable contents
```

The delegation viewer is a separate Cargo crate and is not part of the npm package:

```sh
cd tui
cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test
cargo build --release                      # bin/arc-pi-monitor tui picks up target/release
cargo install --path .                     # or put arc-pi-monitor-tui on PATH
./target/release/arc-pi-monitor-tui --stdin < fixtures/live.ndjson   # offline replay
```

Tests use fake Pi, runner, Cursor Agent, and Claude Code executables. They must never invoke a paid worker, run a real provider login/status command, touch credential stores, mutate GitHub, or require backend credentials.

## Source layout

- `extensions/arc-orchestrator/index.ts` — Pi registration and user-facing tool/commands.
- `extensions/arc-orchestrator/contract.ts` — validation, labels, task text, runner argv.
- `extensions/arc-orchestrator/routes.ts` — supported route/mode matrix.
- `extensions/arc-orchestrator/process.ts` — bounded runner process execution and cancellation.
- `extensions/arc-orchestrator/provider-auth.ts` — vendor CLI specs, shell-free process execution, and redacted auth classification.
- `extensions/arc-orchestrator/session-runs.ts` — per-session run registry schema and lifecycle writes.
- `extensions/arc-session-monitor/` — snapshot/watch library, budgets, `/arc-monitor`, `arc_monitor_status`.
- `extensions/arc-background-terminals/` — session-scoped process manager, bounded output/spill runtime, `arc_terminal_*` tools, and `/arc-terminals` UI.
- `extensions/arc-subagents/` — isolated in-process child-session manager, bounded result/follow-up lifecycle, `subagent_*` tools, and `/subagents` status UI.
- `CONTEXT.md` and `docs/adr/` — canonical domain language and durable architecture decisions.
- `bin/arc-pi` — isolated Pi launcher (`monitor` forwarder included).
- `bin/arc-pi-monitor` — operator/outer-agent session monitor CLI (`status`, `watch`, and the `tui` forwarder).
- `tui/` — Rust/ratatui delegation viewer. `src/stream.rs` parses the monitor NDJSON, `src/model.rs` derives the phase DAG and routing rungs, `src/app.rs` holds the timeline ring buffer and keymap, `src/theme.rs` loads Pi theme JSON, and `src/ui/` renders header, graph, background lane, inspector, and footer. `fixtures/*.ndjson` are replayable sessions.
- `bin/arc-orchestrator` — external runner resolver.
- `scripts/setup.mjs` — idempotent installation into an ARC Pi agent directory.
- `defaults/` — settings and parent policy merged by setup.
- `skills/` and `prompts/` — progressively loaded ARC guidance.
- `dist/` — generated test/build artifact; Pi loads the TypeScript source directly.
- `test/` — unit and integration-style tests using local fakes.
- `test/arc-background-terminals.test.mjs` — offline process, output, lifecycle, limit, follow-up, cleanup, and non-TUI coverage for background terminals.
- `test/arc-subagents.test.mjs` — offline child-session fakes covering concurrency, tool/resource isolation, bounded lifecycle timeouts, late cleanup, cancellation races, normalized output, delivery/trimming, cwd validation, and shutdown cleanup.

## Changing runner routes

Treat the external runner as the source of truth. Before changing `routes.ts`:

1. inspect `arc-orchestrator routes --json` and its documentation;
2. update route selection and exact argv tests together;
3. verify access assumptions, especially Composer read-only limitations;
4. update `docs/orchestration.md` and the copied skill/prompt if policy changed;
5. run the complete verification suite.

## Changing Pi APIs

Read the installed Pi `docs/extensions.md`, `docs/packages.md`, and `docs/settings.md` for the target version. Keep Pi-provided packages in `peerDependencies` and development versions in `devDependencies`. Use TypeBox schemas and `StringEnum` from `@earendil-works/pi-ai` for cross-provider enum compatibility.

## Packaging

`@andysolomon/arc-pi` is a public package with an exact production dependency on the tested ARC runner. Keep that dependency exact and release the runner first; `npm run release:preflight` blocks publication when the pinned runner is absent. `npm run package:check` verifies the tarball allowlist, absence of lifecycle home mutation, external-cwd runner execution, first-launch setup, and deliberate bundled-runner migration.

The release workflow runs full verification, tarball inspection, registry preflight, semantic-release, and post-release Git tag/npm parity checks. The first publication uses the `NPM_TOKEN` repository secret; after the package exists, configure npm trusted publishing for `.github/workflows/release.yml` and remove the token.

Do not add `node_modules`, local ARC state, credentials, tests, implementation plans, or the development-only `.agents`/`.claude` directories to the package.

### Runner-first release train

1. Release and verify `@andysolomon/arc-orchestrator` on npm.
2. Update ARC Pi's production dependency and lockfile to that exact version.
3. Run `npm run verify`, `npm run package:check`, and `npm run release:preflight`.
4. Push the reviewed candidate to the release branch `next`; semantic-release publishes a prerelease only under npm's `next` dist-tag.
5. Install that exact prerelease into isolated Linux and macOS profiles and complete manual QA.
6. Merge the ARC Pi release change only after the runner and canary are publicly installable.
7. Confirm the stable GitHub tag, npm version, `latest` dist-tag, and an isolated global installation.

If the runner publishes but ARC Pi fails, leave the runner available, fix ARC Pi, and retry its release; never point ARC Pi at an unpublished version. If a published version is defective, publish a corrected version and use `npm deprecate` with migration guidance rather than unpublishing a dependency that existing lockfiles may reference.