mirror of
https://github.com/mvschwarz/openrig.git
synced 2026-11-07 05:56:21 -10:00
Mike Schwarz
fcaf1f8ee8
Refreshes `docs/reference/getting-started.md`, `agent-startup-guide.md`, `help.md`, `developing.md`, `worktree-builds.md` and `non-interruptive-mode.md` against main. Corrects a `rig seat set-permissions` example that didn't resolve, the startup layer order (culture before rig), the documented `resources.hooks`, which validation now refuses, and a known problem fixed in 0.6.5. Adds the recovery path after a startup gate (`rig seat continue`, the startup attention line), Claude's bypass warning and `--non-interruptive`, `builtin:auto`, the readiness window and startup proof, and `npm ci` plus build for development. Commands checked against a help capture of `a350c59b`. Part of the 0.6.6 developer documentation refresh. Text only.
46 lines
2.6 KiB
Markdown
46 lines
2.6 KiB
Markdown
# Worktree builds: use a per-worktree install, never a symlinked `node_modules`
|
|
|
|
**Filed as** build friction (a TS2688 `@types/node` failure). **Grounded as** something worse:
|
|
the symlink shortcut that avoids the install produces builds and typechecks that silently
|
|
consume ANOTHER tree's source — a false-green generator, not an inconvenience.
|
|
|
|
## What actually happens
|
|
|
|
A per-worktree install creates `node_modules/@openrig/<pkg>` as a RELATIVE symlink
|
|
(`-> ../../packages/<pkg>`). Relative links resolve against the directory they live in, so:
|
|
|
|
| setup | `@openrig/daemon` resolves to | verdict |
|
|
|---|---|---|
|
|
| per-worktree install (`npm ci`) | that worktree's `packages/daemon` | correct |
|
|
| `ln -s <primary>/node_modules node_modules` | **the PRIMARY tree's** `packages/daemon` | **cross-tree** |
|
|
|
|
Verified by discriminator, not by inference: with a symlinked `node_modules`, a deliberate type
|
|
error introduced in the WORKTREE's `packages/daemon` is seen by that package's own `tsc` and NOT
|
|
seen by `packages/cli`'s `tsc`, which exits 0 — because it type-checked the primary tree's daemon.
|
|
A worktree can therefore report green against code it does not contain.
|
|
|
|
## Rules
|
|
|
|
1. **Run `npm ci` in each worktree** so workspace packages resolve to the
|
|
worktree's own source. It installs the locked versions without rewriting
|
|
`package-lock.json`. Then run `npm run build`, as CI does before the package suites.
|
|
2. **Never symlink `node_modules` from the primary checkout.** It appears to work — builds pass,
|
|
typechecks pass — which is exactly the danger.
|
|
3. **`npx tsc` with no `node_modules` installs an unrelated `tsc` package** and prints
|
|
"This is not the tsc command you are looking for". That message means *no install*, not a
|
|
TypeScript error.
|
|
4. **Build `@openrig/daemon` before typechecking `@openrig/cli` or `@openrig/tui`** in a fresh worktree:
|
|
cli imports `@openrig/daemon/crash-cart` etc. and tui imports `@openrig/daemon/attention`, which resolve
|
|
to daemon's `dist`. `npm run lint` does this build first. Absent dist reads as
|
|
TS2307 "Cannot find module" plus a cascade of implicit-any — a provisioning artifact, not a
|
|
code defect.
|
|
|
|
Some cli imports don't depend on `node_modules` at all: `packages/cli/tsconfig.json` maps a few daemon
|
|
subpaths (`crash-cart` among them) straight to the worktree's own `../daemon/dist`. The others resolve through
|
|
`node_modules`, so the rules above still hold.
|
|
|
|
## Self-check before trusting any worktree build
|
|
|
|
[ "$(readlink -f packages/daemon)" = "$(readlink -f node_modules/@openrig/daemon)" ] \
|
|
|| echo "CROSS-TREE: this worktree resolves @openrig/* into another tree"
|