# @smithers-orchestrator/vcs — src

The VCS layer for Smithers: jj/git binary resolution, the Effect-based jj
command runner with workspace/snapshot operations, repo-root discovery, and the
synchronous tooling preflight used by `smithers doctor`.

- `resolveJjBinary.js` — resolves the `jj` to spawn: `SMITHERS_JJ_PATH` override
  → bundled `@smithers-orchestrator/jj-<platform>` package → bare `"jj"` on PATH.
- `resolveGitBinary.js` — same for `git` (override → PATH; git is never bundled).
- `jj.js` — `runJj` plus the operations built on it: pointer capture/revert,
  workspace add/list/close, `captureWorkspaceSnapshot`, `isJjRepo`. Effect-land;
  requires a `CommandExecutor` (callers typically provide `BunContext.layer`).
- `find-root.js` — `findVcsRoot` walks up to the nearest `.jj`/`.git`, preferring
  `.jj` so colocated repos use jj semantics.
- `vcsToolingStatus.js` — plain synchronous `--version` probes for doctor/run
  preflights; no Effect involved.
- The `*.ts` files are type-only sidecars. The jj/workspace ones
  (`RunJjOptions.ts`, `RunJjResult.ts`, `Workspace*.ts`, `JjRevertResult.ts`)
  are re-exported via the tool-managed `// @smithers-type-exports-begin` block
  in `jj.js`; `ResolvedBinary.ts` reaches the public types through JSDoc
  `import()` references in `resolveJjBinary.js`, `resolveGitBinary.js`, and
  `vcsToolingStatus.js`.
- `index.js` is the public barrel; the package export map also exposes each
  `src/*.js` file directly (`./*`).

Gotchas:

- `runJj` never fails: spawn errors normalize to exit 127 and probe timeouts to
  124 (see `withJjTimeout`, bounded by `JJ_PROBE_TIMEOUT_MS`), so agent paths
  degrade instead of throwing.
- `src/index.d.ts` is generated by `pnpm build` (`tsup --dts-only`) — never
  hand-edit it.
