AGENTS.md

1# tools/AGENTS.md
2 
3Follow the root `AGENTS.md` first. This file only records module-level boundaries for `tools/`.
4 
5## Active tools
6 
7- `tools/dev` provides `@open-design/tools-dev` and the `tools-dev` bin. It is the only currently active local development lifecycle control plane.
8- `pnpm tools-dev` manages daemon -> web -> desktop.
9- `pnpm tools-dev run web` runs foreground daemon + web for the Playwright webServer flow.
10- `pnpm tools-dev inspect desktop ...` inspects the desktop runtime through sidecar IPC.
11- `tools/pack` provides `@open-design/tools-pack` and the `tools-pack` bin. The active slice is packaged artifact build/install/start/stop/logs/uninstall/cleanup/list/reset plus beta release artifact preparation for mac and Windows lanes, plus a Linux AppImage lane with optional containerized builds.
12- `tools/serve` provides `@open-design/tools-serve` and the `tools-serve` bin. It owns local fixture services such as `tools-serve start updater`.
13- `tools/release` provides `@open-design/tools-release` and the `tools-release` bin. It owns release metadata, storage publishing, release reports, and notification-facing file/data contracts; artifact build, cache, installer, payload, and smoke work stays in `tools/pack`.
14 
15## Retired tools
16 
17- `tools/pr` / `@open-design/tools-pr` / `pnpm tools-pr` has been retired from this repository. Maintainer PR-duty workflows now live outside the product workspace in `PerishCode/duty`; do not restore an Open Design-local PR-duty tool without a new explicit maintainer decision.
18 
19## Packaging scope
20 
21- Keep `tools-pack` focused on packaging/runtime control, release artifact preparation, and the packaged-updater acceptance harness. The updater product surface and launcher handoff live in `apps/desktop` and `apps/packaged`; do not duplicate that application logic in the tool.
22- Pack-specific Electron builder resources belong under `tools/pack/resources/`; do not reference app/docs/download assets directly from pack logic.
23- Namespace controls packaged data/log/runtime/cache paths. Ports are transient transport details and must not participate in path decisions.
24- There is no root `pnpm build` aggregate. Use package-scoped builds for source packages and `pnpm tools-pack ...` for packaged artifact build/install/release flows.
25 
26## Orchestration boundary
27 
28- Tool tests live in each tool's `tests/` directory, sibling to `src/`; keep `src/` source-only and do not add new `*.test.ts` or `*.test.tsx` files under `src/`.
29- Orchestration layers must consume primitives from `@open-design/sidecar-proto`, `@open-design/sidecar`, and `@open-design/platform`.
30- Do not hand-build `--od-stamp-*` args, process-scan regexes, runtime tokens, process roles, or duplicate namespace/source args in `tools/dev`, future `tools/pack`, or packaged launchers.
31- Port flags are authoritative inputs: `--daemon-port` and `--web-port`. Internal env vars are `OD_PORT` and `OD_WEB_PORT`; do not introduce `NEXT_PORT`.
32 
33## Common tools commands
34 
35```bash
36pnpm --filter @open-design/tools-dev typecheck
37pnpm --filter @open-design/tools-dev build
38pnpm --filter @open-design/tools-pack typecheck
39pnpm --filter @open-design/tools-pack build
40pnpm --filter @open-design/tools-serve typecheck
41pnpm --filter @open-design/tools-serve build
42pnpm --filter @open-design/tools-release typecheck
43pnpm --filter @open-design/tools-release build
44pnpm --filter @open-design/tools-release test
45pnpm tools-dev status --json
46pnpm tools-dev logs --json
47pnpm tools-dev check
48pnpm tools-pack mac build --to all
49pnpm tools-pack mac install
50pnpm tools-pack mac cleanup
51pnpm tools-pack win build --to nsis
52pnpm tools-pack win install
53pnpm tools-pack win inspect --expr "document.title"
54pnpm tools-pack win cleanup
55pnpm tools-pack linux build --to appimage
56pnpm tools-pack linux install
57pnpm tools-pack linux install --headless
58pnpm tools-pack linux start --headless
59pnpm tools-pack linux stop --headless
60pnpm tools-pack linux build --containerized
61pnpm tools-serve start updater
62```
63