docks-kit 0.22.28 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/AGENTS.md +42 -89
  2. package/README.md +35 -72
  3. package/cli/docs/command-guards.md +233 -197
  4. package/cli/docs/flags.md +17 -65
  5. package/cli/docs/install.md +2 -3
  6. package/cli/docs/omp-context.md +79 -7
  7. package/cli/docs/omp-models.md +27 -12
  8. package/cli/docs/overview.md +7 -18
  9. package/cli/docs/platforms.md +2 -2
  10. package/cli/docs/sync-layers.md +14 -60
  11. package/cli/docs/toolchain.md +12 -81
  12. package/cli/src/argv.ts +0 -12
  13. package/cli/src/argvValidate.ts +3 -54
  14. package/cli/src/commands/docs.ts +3 -15
  15. package/cli/src/commands/omp.ts +1 -1
  16. package/cli/src/commands/scratch.ts +1 -1
  17. package/cli/src/commands/sync.ts +5 -120
  18. package/cli/src/commands/tidy.ts +1 -1
  19. package/cli/src/commands/toolchain.ts +4 -12
  20. package/cli/src/engine-native/DESIGN.md +69 -100
  21. package/cli/src/engine-native/deps.ts +7 -92
  22. package/cli/src/engine-native/engineCtx.ts +9 -103
  23. package/cli/src/engine-native/exec.ts +1 -18
  24. package/cli/src/engine-native/index.ts +6 -8
  25. package/cli/src/engine-native/jq.ts +4 -37
  26. package/cli/src/engine-native/kitDb.ts +21 -37
  27. package/cli/src/engine-native/modes.ts +3 -132
  28. package/cli/src/engine-native/ompFastMode.ts +1 -1
  29. package/cli/src/engine-native/ompOverlay.ts +1 -1
  30. package/cli/src/engine-native/ompRemovals.ts +24 -3
  31. package/cli/src/engine-native/ompSession.ts +67 -0
  32. package/cli/src/engine-native/ompSync.ts +1 -1
  33. package/cli/src/engine-native/os/darwin.ts +0 -4
  34. package/cli/src/engine-native/os/index.ts +1 -2
  35. package/cli/src/engine-native/os/linux.ts +0 -3
  36. package/cli/src/engine-native/os/posix.ts +2 -47
  37. package/cli/src/engine-native/os/types.ts +1 -36
  38. package/cli/src/engine-native/os/windows.ts +0 -50
  39. package/cli/src/engine-native/parseArgs.ts +7 -180
  40. package/cli/src/engine-native/parseHelp.ts +4 -44
  41. package/cli/src/engine-native/scratch.ts +1 -1
  42. package/cli/src/engine-native/services.ts +1 -2
  43. package/cli/src/engine-native/sharedTypes.d.ts +1 -41
  44. package/cli/src/engine-native/syncConcurrency.ts +3 -15
  45. package/cli/src/engine-native/syncDispatch.ts +30 -143
  46. package/cli/src/engine-native/toolchain.ts +6 -45
  47. package/cli/src/engine.ts +0 -75
  48. package/cli/src/generated/sotPayload.ts +14 -43
  49. package/cli/src/main.ts +8 -24
  50. package/cli/src/payload.ts +2 -8
  51. package/cli/tsconfig.json +1 -3
  52. package/package.json +3 -5
  53. package/cli/docs/models.md +0 -58
  54. package/cli/docs/modifiers.md +0 -52
  55. package/cli/docs/plugins.md +0 -70
  56. package/cli/src/checklistPrompt.ts +0 -464
  57. package/cli/src/commands/harnesses.ts +0 -80
  58. package/cli/src/commands/model.ts +0 -68
  59. package/cli/src/commands/models.ts +0 -75
  60. package/cli/src/commands/plugins.ts +0 -35
  61. package/cli/src/commands/skills.ts +0 -40
  62. package/cli/src/commands/status.ts +0 -206
  63. package/cli/src/efforts.ts +0 -89
  64. package/cli/src/engine-native/claudeLsp.ts +0 -301
  65. package/cli/src/engine-native/claudeOptionalPlugins.ts +0 -126
  66. package/cli/src/engine-native/claudePluginPasses.ts +0 -426
  67. package/cli/src/engine-native/claudeRemovals.ts +0 -383
  68. package/cli/src/engine-native/claudeRetired.ts +0 -165
  69. package/cli/src/engine-native/claudeRuntime.ts +0 -157
  70. package/cli/src/engine-native/claudeSettings.ts +0 -201
  71. package/cli/src/engine-native/claudeSettingsModifiers.ts +0 -115
  72. package/cli/src/engine-native/claudeSync.ts +0 -312
  73. package/cli/src/engine-native/codexConfig.ts +0 -214
  74. package/cli/src/engine-native/codexHooks.ts +0 -91
  75. package/cli/src/engine-native/codexPaths.ts +0 -14
  76. package/cli/src/engine-native/codexPlugins.ts +0 -315
  77. package/cli/src/engine-native/codexStatus.ts +0 -25
  78. package/cli/src/engine-native/codexSync.ts +0 -314
  79. package/cli/src/engine-native/codexToml.ts +0 -303
  80. package/cli/src/engine-native/harnesses.ts +0 -138
  81. package/cli/src/engine-native/liveModels.ts +0 -264
  82. package/cli/src/engine-native/models.ts +0 -101
  83. package/cli/src/engine-native/parseModifiers.ts +0 -225
  84. package/cli/src/engine-native/settings.ts +0 -42
  85. package/cli/src/engine-native/skillsInstall.ts +0 -135
  86. package/cli/src/engine-native/skillsLinks.ts +0 -216
  87. package/cli/src/engine-native/skillsManifest.ts +0 -36
  88. package/cli/src/engine-native/skillsPrune.ts +0 -117
  89. package/cli/src/engine-native/skillsRecords.ts +0 -138
  90. package/cli/src/engine-native/skillsSync.ts +0 -57
  91. package/cli/src/engine-native/tomlLines.ts +0 -92
  92. package/cli/src/manifests.ts +0 -145
  93. package/cli/src/terminalCells.ts +0 -191
@@ -1,30 +1,28 @@
1
1
  # EngineNative Design
2
2
 
3
3
  EngineNative is the only supported sync engine. It lives in
4
- `cli/src/engine-native/`. The `sync`, `model`, `toolchain`, and `status`
5
- commands invoke it through `cli/src/engine.ts` and pass normalized argv to
6
- that seam. Other commands, such as `omp`, `harnesses`, `models`, `update`,
7
- `scratch`, and `tidy`, import engine-native modules directly. The former
4
+ `cli/src/engine-native/`. The `sync` and `toolchain` commands invoke it
5
+ through `cli/src/engine.ts` and pass normalized argv to that seam. Other
6
+ commands, such as `omp`, `update`, `scratch`, and
7
+ `tidy`, import engine-native modules directly. The former
8
8
  shell engine was removed after the `bash-engine-final` tag.
9
9
  `DOCKS_KIT_ENGINE=bash` is now an explicit removed-engine diagnostic and exits
10
10
  2 with the recovery tag message.
11
11
 
12
12
  ## Selection Contract
13
13
 
14
- - The public `sync`, `model`, and `toolchain` commands route through
15
- `engine(args)` after `effect/cli` (the CLI module inside `effect` 4) parses
16
- pickers, target words, and flag spellings.
17
- - `engineCapture(args)` re-spawns the CLI on the `native-capture` channel to
18
- capture stdout. `status` uses it to read the `toolchain check` report.
14
+ - The public `sync` and `toolchain` commands route through `engine(args)`
15
+ after `effect/cli` (the CLI module inside `effect` 4) parses pickers and flag
16
+ spellings. `sync` takes no positional argument, so `effect/cli` refuses a
17
+ word such as `omp` with `Unexpected positional argument` and exit 1.
19
18
  - Other public commands call engine-native modules directly, for example
20
19
  `tidy.ts` `planTidy` and `applyTidy`, `scratch.ts` `createScratchDir`, and
21
- `harnesses.ts` `readHarnessSelection`.
20
+ `ompSession.ts` `readOmpSessionModel`.
22
21
  - `DOCKS_KIT_ENGINE=native-raw` is harness-private: it bypasses `effect/cli`
23
22
  and hands argv directly to EngineNative so tests can exercise the internal
24
23
  engine vocabulary.
25
- - `DOCKS_KIT_ENGINE=native-capture` is the `engineCapture` child channel. It
26
- also takes raw argv, but `main.ts` runs it with `{ envGlobals: false }`, so
27
- it ignores the env globals.
24
+ - `main.ts` runs the native-raw channel with `{ envGlobals: true }`; it is the
25
+ only channel that honors the env globals.
28
26
 
29
27
  ## Behavior Contract
30
28
 
@@ -37,24 +35,18 @@ shell engine was removed after the `bash-engine-final` tag.
37
35
  - **Prove-red stays red.** The golden suites compare live native output to a
38
36
  mismatched golden under `--prove-red` and must exit non-zero after printing
39
37
  `prove-red OK`.
40
- - **Step ordering is load-bearing.** The Claude pipeline resolves Bun, prepares
41
- materialized settings, writes runtime assets, commits settings, then performs
42
- readiness-gated legacy cleanup. Modifiers run after the base commit, removals
43
- before plugins, and LSP checks after plugin state.
44
- - **Pipeline concurrency is bounded.** Selected Claude, Codex, skills, and omp
45
- pipelines run through one input-ordered pool (`syncConcurrency.ts`
46
- `runBounded`). The production default cap is 3. When all four pipelines are
47
- selected, omp starts only after an earlier pipeline settles. After the first
48
- rejection, started pipelines drain and queued pipelines never start.
49
- `DOCKS_KIT_SYNC_CONCURRENCY=1` restores serial execution for golden tests
50
- and debugging (`2` allows two-way overlap). A populated skills manifest with
51
- the `claude` and `agents` targets selected forces serial execution
52
- (`syncConcurrencyForManifest`). Each individual pipeline remains serial, and
53
- summaries keep the Claude, Codex, skills, omp order.
54
- - **External CLIs stay external.** `claude`, `codex`, `npx`, `npm`, `bun`,
55
- `curl`, and platform package managers are spawned with argv arrays,
56
- not shell command strings except where an external installer contract
57
- requires a script interpreter.
38
+ - **Step ordering is load-bearing.** The omp pipeline resolves Bun, deploys
39
+ the whole files, merges `config.yml` and runs the retired-key removals on
40
+ the merged result, merges `models.yml` and runs its removals, writes the
41
+ intercom configuration, materializes the kit plugin, and only then runs the
42
+ marketplace and plugin passes, because the plugin pass links the kit plugin
43
+ directory.
44
+ - **One pipeline.** Sync runs only the omp pipeline, which is serial.
45
+ `syncConcurrency.ts` `runBounded` stays for the parallel probes of `tidy`
46
+ and the tidy report.
47
+ - **External CLIs stay external.** `omp`, `npm`, `bun`, and `curl` are
48
+ spawned with argv arrays, not shell command strings except where an external
49
+ installer contract requires a script interpreter.
58
50
  - **Backups precede mutation.** Deployed settings/config files write `.bak`
59
51
  backups before replacement.
60
52
  - **Runtime payload is in memory.** `SoT/` remains the reviewed authoring tree;
@@ -77,10 +69,10 @@ warnings, and the summary. Status-quo confirmations exist but are opt-in.
77
69
  | `change(msg)` | stderr | shown | shown | `[ok]` green (`\x1b[1;32m`) — ONLY after an operation actually mutated |
78
70
  | `verbose(msg)` | stderr | hidden | shown | `[ok]` green — no-op confirmations ("already …", "present", "up to date", "left as-is"), skips |
79
71
  | `progress(msg)` | stderr | interactive only | interactive only | dim, transient single-line status with no newline |
80
- | `echo(line)` | stdout | shown | shown | bare — dry-run report lines, `status --json`, summary block, usage text |
72
+ | `echo(line)` | stdout | shown | shown | bare — dry-run report lines, summary block, usage text |
81
73
 
82
74
  - stdout is data, stderr is logs — only `echo` writes to stdout, and every
83
- log emitter writes to stderr (`engineCapture` depends on it).
75
+ log emitter writes to stderr.
84
76
  - **Dry-run is a complete inspection report**: `[dry-run]` lines use `echo`
85
77
  and print unfiltered at every verbosity.
86
78
  - Prefixes and ANSI codes are stable golden surface; the level controls
@@ -114,26 +106,22 @@ Exactly one deduplicated warn per requested missing tool per run, uniform shape:
114
106
  `[warn] <tool> not installed — <platform-correct install command>`, sourced
115
107
  from the dependency registry (`deps.ts`). jq and curl are optional report rows:
116
108
  jq has no runtime consumer, while curl warns only when a requested Bun
117
- bootstrap needs an installer download. A missing Bun defers Claude runtime
118
- migration without deleting working legacy hooks or statusline files.
109
+ bootstrap needs an installer download.
119
110
 
120
111
  ### Summary and next steps
121
112
 
122
- `model` and `toolchain` modes have no separate summary block by design —
123
- their stdout IS the deliverable (`deployed:`/`SoT:` + catalog lines for
124
- `model`; the report table for `toolchain check`), so nothing prints after
125
- it. The schema below applies to `sync` only.
113
+ `toolchain` modes have no separate summary block by design — their stdout IS
114
+ the deliverable (the report table for `toolchain check`), so nothing prints
115
+ after it. The schema below applies to `sync` only.
126
116
 
127
- The `--- Sync complete ---` block (stdout, `echo`) prints after the selected
128
- pipelines settle, also on dry-run. When a pipeline rejects, `syncDispatch.ts`
117
+ The `--- Sync complete ---` block (stdout, `echo`) prints after the omp
118
+ pipeline settles, also on dry-run. When the pipeline rejects, `syncDispatch.ts`
129
119
  `engineSync` skips the block and prints only the `--- Failures ---` ledger.
130
- The block starts with a `Repo:` line and adds the inventory lines of each
131
- selected target: `Claude:`/`Hooks:`/`Plugins:`, `Codex:`/`Codex plugins:`,
132
- `Skills:`, and `omp:`/`omp plugins:`. Dry-run leaves out the `Hooks:`,
133
- `Plugins:`, `Codex plugins:`, and `omp plugins:` lines. Next-step advice
134
- lines print only when their trigger changed this run (plugins changed →
135
- `/reload-plugins` line; hooks/env changed → restart line; skills changed →
136
- discovery line) or under `--verbose`.
120
+ The block starts with a `Repo:` line and adds the `omp:` and `omp plugins:`
121
+ inventory lines. Dry-run leaves out the `omp plugins:` line. Next-step advice
122
+ lines print only when their trigger changed this run (an omp plugin upgraded
123
+ → `/reload-plugins` line; omp files changed → restart line) or under
124
+ `--verbose`.
137
125
 
138
126
  ### Platform seam
139
127
 
@@ -142,7 +130,7 @@ holds the engine's host-detection `process.platform` read and keeps platform
142
130
  normalization injectable for tests. These direct reads remain:
143
131
 
144
132
  - the POSIX-only `chmod` guard in `kitDb.ts`;
145
- - the default `platform` argument of `harnesses.ts` `engineHome`;
133
+ - the default `platform` argument of `ompSession.ts` `engineHome`;
146
134
  - `exec.ts` `WINDOWS_PROCESS`;
147
135
  - `tidy.ts` `listProcesses`;
148
136
  - `tidyReport.ts` `memorySection`, `processSection`, `trashSection`,
@@ -166,13 +154,13 @@ on the host directly.
166
154
 
167
155
  ### Verbosity plumbing
168
156
 
169
- `--verbose` / `-v` on the public `sync`, `model`, and `toolchain` commands
170
- selects verbose output. On the harness-private raw channel,
157
+ `--verbose` / `-v` on the public `sync` and `toolchain` commands selects
158
+ verbose output. On the harness-private raw channel,
171
159
  `DOCKS_KIT_VERBOSE=1` also selects it. Only the raw channel honors the
172
- unprefixed `Ctx` env globals (`engineCtx.ts` `ENV_GLOBAL_KEYS`, with the
173
- `${VAR:-default}` contract). `main.ts` passes `{ envGlobals: true }` to
160
+ unprefixed `Ctx` env globals (`engineCtx.ts makeCtx` reads `DRY_RUN` and
161
+ `DOCKS_KIT_VERBOSE`). `main.ts` passes `{ envGlobals: true }` to
174
162
  `runEngineNative` only on that channel. The public `engine()` seam ignores
175
- these variables, and `engineCapture` removes them from the child environment.
163
+ these variables.
176
164
  The default service factory returns a raw Logger. `runEngineNative` wraps the
177
165
  default or injected Logger with explicit delegates and owns the sole
178
166
  `ctx.verbose` gate.
@@ -181,36 +169,24 @@ active logger binding.
181
169
 
182
170
  ## Module Map
183
171
 
184
- | Module | Owns |
185
- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
186
- | `parseArgs.ts` | engine usage, target selection, argv dispatch loop, legacy rename hints; re-exports the `parseHelp.ts` help text and early-exit error |
187
- | `parseModifiers.ts` | deploy-time modifier metadata, scalar modifier setters, compact-window and opt-in plugin parsing, modifier and model flag validation |
188
- | `index.ts` | entry routing (`model`/`toolchain`/`sync`) and the run-scoped verbosity gate |
189
- | `engineCtx.ts` | `Ctx` shape and `makeCtx`; the unprefixed env globals (`ENV_GLOBAL_KEYS`) apply only on the native-raw channel |
190
- | `syncDispatch.ts` | pipeline selection, pool dispatch, run summary, next-step blocks, and the `--- Failures ---` ledger |
191
- | `syncConcurrency.ts` | input-ordered bounded pool (`runBounded`) and the manifest-driven serial rule (`syncConcurrencyForManifest`) |
192
- | `../payload.ts` | generated text/byte payload reads and presentation-only source labels |
193
- | `claudeSync.ts` | Claude pipeline orchestration and summary: Bun bootstrap, prepared settings transaction, runtime assets, deploy-time modifiers, `~/.claude.json`, readiness-gated removed artifacts; `claudePluginPasses.ts`, `claudeOptionalPlugins.ts`, and `claudeLsp.ts` own the plugin, optional-plugin, and LSP binary passes |
194
- | `bun.ts` | per-run memoized Bun resolution/bootstrap shared by the Claude runtime and direct toolchain ensure |
195
- | `claudeRuntime.ts` | sentinel validation, absolute runtime paths, no-cutover settings projection, and per-host statusline and failure-hook command materialization |
196
- | `settings.ts` | pure Claude settings merge/reconcile semantics and permission-array union |
197
- | `claudeSettings.ts` | Claude settings preflight, prepare/commit transaction, dry-run description, and the compact-window and permissive modifiers |
198
- | `claudeSettingsModifiers.ts` | atomic top-level Claude settings modifiers (model, effort, advisor) and the direct `model claude` write path |
199
- | `claudeRemovals.ts` | force-prune of retired Claude artifacts and the `claudeRetired.ts` permission inventory without `--reconcile` |
200
- | `codexSync.ts` | Codex pipeline orchestration: bubblewrap check, rules, AGENTS.md; `codexConfig.ts` `syncConfig` owns the config merge, `codexHooks.ts` the retired-hook prune, `codexPlugins.ts` the personal marketplace and plugin refresh, and `codexStatus.ts` the summary |
201
- | `codexToml.ts` | line-based top-level TOML replacement and deployed Codex model modifier |
202
- | `tomlLines.ts` | import-free TOML line grammar (header lines, key separators, value continuation lines) shared by `codexToml.ts`, `codexConfig.ts`, `codexPlugins.ts`, and `../manifests.ts` |
203
- | `skillsSync.ts` | universal-skill pipeline orchestration; `skillsManifest.ts` parses the manifest, `skillsInstall.ts` owns the install pass, `skillsLinks.ts` the ordered symlink/junction/copy fallback and Claude entry healing, and `skillsPrune.ts` the prune and managed-skill snapshot |
204
- | `ompSync.ts` | omp pipeline orchestration and summary; `ompFileDeploy.ts`, `ompMarketplace.ts`, `ompPlugins.ts`, and `ompRemovals.ts` own the file, marketplace, plugin, and retired-key passes; `ompPaths.ts` resolves roots; `ompYaml.ts` merges YAML |
205
- | `toolchain.ts` | tool presence/version probes, verified-version floor reporting, report table |
206
- | `modes.ts` | direct `model` and `toolchain` modes |
207
- | `models.ts` | model catalog listing and validation |
208
- | `jq.ts` | JSON helpers that preserve jq-style merge/order/stringify behavior where the deployed file contract needs it |
209
- | `exec.ts` | slash-stable path helpers, host-aware PATH probes and invocation, capture/spawn wrappers, and change-detecting write/copy helpers |
210
- | `logger.ts` | Logger shape + stable raw stdout/stderr sink factory; the run-scoped verbosity gate lives in `index.ts` |
211
- | `deps.ts` | external-tool registry: identity, presence probe, supported-host install hints; the Bun hint renders the pinned download-then-run installer of the host (`HostOs.bunInstaller`) |
212
- | `os/` | host reader, injected platform normalization, and per-OS `HostOs` fact modules |
213
- | `services.ts` | shared raw-Logger + DependencyManager + Platform factory; `makeDependencyManager` owns the per-manager missing-tool dedup, and callers supply the current run Logger to `warnMissing`; wrapped in Effect Layers at `cli/src/services.ts`, with the run-scoped Logger gate applied only by `runEngineNative` |
172
+ | Module | Owns |
173
+ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
174
+ | `parseArgs.ts` | engine usage and the argv dispatch loop; re-exports the `parseHelp.ts` help text and early-exit error |
175
+ | `index.ts` | entry routing (`toolchain`/`sync`) and the run-scoped verbosity gate |
176
+ | `engineCtx.ts` | `Ctx` shape and `makeCtx`; the unprefixed env globals apply only on the native-raw channel |
177
+ | `syncDispatch.ts` | sync and folder locks, the omp pipeline call, run summary, next-step blocks, and the `--- Failures ---` ledger |
178
+ | `syncConcurrency.ts` | input-ordered bounded pool (`runBounded`) for the tidy probes |
179
+ | `../payload.ts` | generated text payload reads and presentation-only source labels |
180
+ | `bun.ts` | per-run memoized Bun resolution/bootstrap shared by the omp pipeline and direct toolchain ensure |
181
+ | `ompSync.ts` | omp pipeline orchestration and summary; `ompFileDeploy.ts`, `ompMarketplace.ts`, `ompPlugins.ts`, and `ompRemovals.ts` own the file, marketplace, plugin, and retired-key passes; `ompPaths.ts` resolves roots; `ompYaml.ts` merges YAML |
182
+ | `toolchain.ts` | tool presence/version probes, verified-version floor reporting, report table |
183
+ | `modes.ts` | direct `toolchain` mode |
184
+ | `jq.ts` | the `Json` value type, object narrowing, jq-compatible codepoint ordering, and a parse that yields `undefined` instead of throwing |
185
+ | `exec.ts` | slash-stable path helpers, host-aware PATH probes and invocation, capture/spawn wrappers, and change-detecting write/copy helpers |
186
+ | `logger.ts` | Logger shape + stable raw stdout/stderr sink factory; the run-scoped verbosity gate lives in `index.ts` |
187
+ | `deps.ts` | external-tool registry: identity, presence probe, supported-host install hints; the Bun hint renders the pinned download-then-run installer of the host (`HostOs.bunInstaller`) |
188
+ | `os/` | host reader, injected platform normalization, and per-OS `HostOs` fact modules |
189
+ | `services.ts` | shared raw-Logger + DependencyManager + Platform factory; `makeDependencyManager` owns the per-manager missing-tool dedup, and callers supply the current run Logger to `warnMissing`; wrapped in Effect Layers at `cli/src/services.ts`, with the run-scoped Logger gate applied only by `runEngineNative` |
214
190
 
215
191
  ## Platform Support
216
192
 
@@ -218,13 +194,6 @@ active logger binding.
218
194
  x64.
219
195
  - Unsupported hosts fail before launcher fallback, dependency probes, downloads,
220
196
  settings writes, or sync work.
221
- - Claude runtime settings use absolute Bun/script paths and materialize
222
- statusline and failure-hook commands through the selected `HostOs`.
223
- - Directory linking is capability-driven. The host module supplies only the
224
- order while the runtime decides the outcome: symlink, then a Windows junction
225
- with an absolute target, then a recursive copy. Copies carry a kit marker so
226
- later sync can heal them back to a real link and prune can reclaim them
227
- without touching user-owned directories.
228
197
 
229
198
  ## Tests
230
199
 
@@ -233,15 +202,16 @@ active logger binding.
233
202
  - `bun run golden:dryrun` compares live native dry-run output to
234
203
  `cli/test/goldens/dryrun.json`.
235
204
  - `bun run golden:mutation` compares live native mutation snapshots, argv logs,
236
- output, and TOML invariants to `cli/test/goldens/mutation.json`.
205
+ output, and the channel and migration invariants to
206
+ `cli/test/goldens/mutation.json`.
237
207
  - `.github/workflows/parity.yml` runs its portable lane on `ubuntu-24.04` and
238
- `macos-26`: typecheck, unit tests, host-specific runtime command checks, and
239
- compilation and execution of the native host artifact. On `windows-2025`,
240
- two unit-test shards and a runtime job (generated-payload check, typecheck,
241
- runtime commands, native artifact) run in parallel. The check
242
- `portable (windows-2025)` passes only when all three pass. The
243
- Linux-canonical snapshot lane stays on Ubuntu and runs both golden suites
244
- plus their prove-red checks.
208
+ `macos-26`: generated-payload check, typecheck, unit tests, a clean-room
209
+ package install smoke, and compilation and execution of the native host
210
+ artifact. On `windows-2025`, two unit-test shards and the
211
+ `portable-windows-checks` job (generated-payload check, typecheck, native
212
+ artifact) run in parallel. The check `portable (windows-2025)` passes only
213
+ when all three pass. The Linux-canonical snapshot lane stays on Ubuntu and
214
+ runs both golden suites plus their prove-red checks.
245
215
  - `.github/workflows/release-cli.yml` publishes four binaries (Linux x64 and
246
216
  arm64, macOS arm64, Windows x64), plus `SHA256SUMS` and the npm package.
247
217
 
@@ -249,5 +219,4 @@ active logger binding.
249
219
 
250
220
  - Reintroducing the removed shell engine as a supported fallback. Fix forward in
251
221
  EngineNative; recover historical source only from `bash-engine-final`.
252
- - Adding a compiled runner or CLI hook subcommand for Claude's Bun runtime.
253
222
  - Adding new sync features while changing the engine contract.
@@ -10,34 +10,12 @@
10
10
  import { isAbsolute } from "node:path";
11
11
 
12
12
  import { capture, captureWithin, commandExists, p, which, type CaptureOutcome } from "./exec";
13
- import { engineHome } from "./harnesses";
14
- import { isObject, parseJson } from "./jq";
13
+ import { engineHome } from "./ompSession";
15
14
  import { hostOs, platformName, rawPlatform } from "./os";
16
15
  import type { Invocation } from "./os/types";
17
16
  import { field } from "./toolchain";
18
17
 
19
- export type ToolId =
20
- | "git"
21
- | "jq"
22
- | "curl"
23
- | "node"
24
- | "npm"
25
- | "npx"
26
- | "claude"
27
- | "codex"
28
- | "omp"
29
- | "bun"
30
- | "bwrap"
31
- | "ffplay"
32
- | "intelephense"
33
- | "typescript-language-server"
34
- | "tsc"
35
- | "rust-analyzer"
36
- | "rustup"
37
- | "apt-get"
38
- | "dnf"
39
- | "pacman"
40
- | "zypper";
18
+ export type ToolId = "git" | "jq" | "curl" | "npm" | "omp" | "bun";
41
19
 
42
20
  export type ProbeResult =
43
21
  | { readonly state: "present"; readonly path?: string }
@@ -62,7 +40,8 @@ export type VersionReading =
62
40
 
63
41
  /**
64
42
  * The longest wait for a `<tool> --version` answer. A cold rust-analyzer start
65
- * took 20 s on a macOS runner (#114), so the limit must let that pass.
43
+ * once took 20 s on a macOS runner (#114), so the limit leaves room for slow
44
+ * first starts.
66
45
  */
67
46
  export const VERSION_PROBE_LIMIT_MS = 60_000;
68
47
 
@@ -80,7 +59,6 @@ export interface DependencySpec {
80
59
  }
81
60
 
82
61
  interface SpecOptions {
83
- readonly versionArgs?: ReadonlyArray<string>;
84
62
  readonly resolve?: (exec: ProbeExecutor, platform: NodeJS.Platform) => ProbeResult;
85
63
  readonly version?: (exec: ProbeExecutor) => Promise<string>;
86
64
  }
@@ -91,7 +69,7 @@ const spec = (
91
69
  options: SpecOptions = {},
92
70
  ): DependencySpec => ({
93
71
  id,
94
- versionArgs: options.versionArgs ?? ["--version"],
72
+ versionArgs: ["--version"],
95
73
  installHint,
96
74
  resolve: options.resolve,
97
75
  version: options.version,
@@ -135,9 +113,9 @@ const pathProbe =
135
113
  };
136
114
 
137
115
  /**
138
- * The resolved path gets persisted into global direct-exec hooks, so a
116
+ * Callers run the resolved path outside the sync working directory, so a
139
117
  * relative `which` hit (relative PATH entry, relative BUN_INSTALL) would
140
- * break outside the sync working directory.
118
+ * break there.
141
119
  */
142
120
  const findBun = (exec: ProbeExecutor): { command: string; path: string } | undefined => {
143
121
  const onPath = exec.which("bun");
@@ -160,52 +138,16 @@ const resolveBun = (exec: ProbeExecutor): ProbeResult => {
160
138
  return bun === undefined ? { state: "missing" } : { state: "present", path: bun.path };
161
139
  };
162
140
 
163
- const npmGlobalCache = new WeakMap<ProbeExecutor, Promise<{ [k: string]: string }>>();
164
-
165
- /** npm-global package name → version, from `npm ls -g`; memoized per executor. */
166
- export const npmGlobalVersions = (exec: ProbeExecutor): Promise<{ [k: string]: string }> => {
167
- const hit = npmGlobalCache.get(exec);
168
- if (hit !== undefined) return hit;
169
- const pending = (async (): Promise<{ [k: string]: string }> => {
170
- const out: { [k: string]: string } = {};
171
- if (exec.commandExists("npm")) {
172
- const doc = parseJson(await exec.capture("npm", ["ls", "-g", "--depth=0", "--json"]));
173
- const deps =
174
- doc !== undefined && isObject(doc) && isObject(doc["dependencies"])
175
- ? doc["dependencies"]
176
- : {};
177
- for (const [name, value] of Object.entries(deps)) {
178
- if (isObject(value) && typeof value["version"] === "string") out[name] = value["version"];
179
- }
180
- }
181
- return out;
182
- })();
183
- npmGlobalCache.set(exec, pending);
184
- return pending;
185
- };
186
-
187
- const versionNpmGlobal =
188
- (pkg: string) =>
189
- async (exec: ProbeExecutor): Promise<string> =>
190
- (await npmGlobalVersions(exec))[pkg] ?? "";
191
-
192
141
  export const defaultProbeExecutor: ProbeExecutor = { commandExists, capture, captureWithin, which };
193
142
 
194
143
  export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
195
144
  git: spec("git", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("git")),
196
145
  jq: spec("jq", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("jq")),
197
146
  curl: spec("curl", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("curl")),
198
- node: spec("node", () => "install Node.js via https://nodejs.org (or your package manager)"),
199
147
  npm: spec(
200
148
  "npm",
201
149
  () => "ships with Node.js — install via https://nodejs.org (or your package manager)",
202
150
  ),
203
- npx: spec(
204
- "npx",
205
- () => "ships with Node.js — install via https://nodejs.org (or your package manager)",
206
- ),
207
- claude: spec("claude", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("claude")),
208
- codex: spec("codex", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("codex")),
209
151
  omp: spec(
210
152
  "omp",
211
153
  () =>
@@ -223,33 +165,6 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
223
165
  return await exec.capture(bun.command, ["--version"]);
224
166
  },
225
167
  }),
226
- bwrap: spec("bwrap", () => "sudo apt install -y bubblewrap (or dnf/pacman/zypper equivalent)"),
227
- ffplay: spec("ffplay", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("ffplay"), {
228
- versionArgs: ["-version"],
229
- resolve: pathProbe("ffplay"),
230
- }),
231
- intelephense: spec("intelephense", () => "npm install -g intelephense", {
232
- resolve: pathProbe("intelephense"),
233
- version: versionNpmGlobal("intelephense"),
234
- }),
235
- "typescript-language-server": spec(
236
- "typescript-language-server",
237
- () => "npm install -g typescript-language-server typescript",
238
- {
239
- resolve: pathProbe("typescript-language-server"),
240
- },
241
- ),
242
- tsc: spec("tsc", () => "npm install -g typescript", {
243
- resolve: pathProbe("tsc"),
244
- }),
245
- "rust-analyzer": spec("rust-analyzer", () => "rustup component add rust-analyzer", {
246
- resolve: pathProbe("rust-analyzer"),
247
- }),
248
- rustup: spec("rustup", () => "install the Rust toolchain from https://rustup.rs"),
249
- "apt-get": spec("apt-get", () => "install apt via your Linux distribution"),
250
- dnf: spec("dnf", () => "install dnf via your Linux distribution"),
251
- pacman: spec("pacman", () => "install pacman via your Linux distribution"),
252
- zypper: spec("zypper", () => "install zypper via your Linux distribution"),
253
168
  };
254
169
 
255
170
  export function resolveDependency(
@@ -3,62 +3,24 @@
3
3
  * the environment. Split from index.ts, which re-exports the public surface
4
4
  * so existing import paths keep working.
5
5
  */
6
- import { p } from "./exec";
7
- import { engineHome } from "./harnesses";
6
+ import { engineHome } from "./ompSession";
8
7
  import type { TerminalLease } from "./logger";
9
8
  import type { BunRuntimeState } from "./bun";
10
9
  import { kitHome } from "../kitHome";
11
- import { ExitError, parseClaudePlugin, parseCompactWindow } from "./parseArgs";
12
10
  import type { EngineServices } from "./services";
13
- import type { SyncConcurrency } from "./syncConcurrency";
14
-
15
- export type ModifierFlag =
16
- | "--claude-model"
17
- | "--claude-effort"
18
- | "--claude-advisor"
19
- | "--claude-compact-window"
20
- | "--claude-permissive"
21
- | "--claude-plugin"
22
- | "--codex-model"
23
- | "--codex-effort";
24
11
 
25
12
  export interface Ctx {
26
13
  readonly repoDir: string;
27
14
  readonly home: string;
28
- readonly agentsDir: string;
29
- readonly interactive: boolean;
30
15
  dryRun: boolean;
31
16
  verbose: boolean;
32
- skipBubblewrap: boolean;
33
17
  skipPluginRefresh?: boolean;
34
- reconcile: boolean;
35
- prune: boolean;
36
- claudeCompactWindow: string;
37
- claudePermissive: boolean;
38
- claudePlugins: Array<string>;
39
- claudeModel: string;
40
- claudeEffort: string;
41
- claudeAdvisor: string;
42
- codexModel: string;
43
- codexEffort: string;
44
- /** Distinguishes an explicitly empty modifier from an option that was not supplied. */
45
- modifierFlags?: Set<ModifierFlag>;
46
18
  /** Injected capability seam (logger/deps/platform) — see services.ts. */
47
19
  readonly services: EngineServices;
48
- syncConcurrency: SyncConcurrency;
49
20
  terminalLease?: TerminalLease;
50
21
  bunRuntime?: Promise<BunRuntimeState>;
51
- targetFilterSet: boolean;
52
- syncClaude: boolean;
53
- syncCodex: boolean;
54
- syncAgents: boolean;
55
- syncOmp: boolean;
56
22
  /** Per-run next-step triggers (Output Policy): advice prints only when its trigger changed or --verbose. */
57
23
  readonly nextStepTriggers: {
58
- claudePlugins: boolean;
59
- claudeRestart: boolean;
60
- codexRestart: boolean;
61
- skillsRestart: boolean;
62
24
  ompRestart: boolean;
63
25
  /** A marketplace plugin upgrade changed a version, so running omp sessions lost its folder. */
64
26
  ompPluginUpgraded: boolean;
@@ -67,88 +29,32 @@ export interface Ctx {
67
29
  readonly failures: Array<string>;
68
30
  }
69
31
 
70
- /**
71
- * Unprefixed env globals that seed `Ctx` with the historical ${VAR:-default}
72
- * contract. Only the harness-private native-raw channel honors them; the
73
- * public CLI takes the same behavior from flags.
74
- */
75
- export const ENV_GLOBAL_KEYS = [
76
- "DRY_RUN",
77
- "DOCKS_KIT_VERBOSE",
78
- "SKIP_BUBBLEWRAP",
79
- "RECONCILE",
80
- "PRUNE",
81
- "CLAUDE_PERMISSIVE",
82
- "CLAUDE_MODEL",
83
- "CODEX_MODEL",
84
- "CLAUDE_PLUGINS",
85
- "CLAUDE_COMPACT_WINDOW",
86
- "AGENTS_DIR",
87
- ] as const;
88
-
89
32
  export interface CtxOptions {
90
- /** True only on the native-raw channel: read ENV_GLOBAL_KEYS from the environment. */
33
+ /**
34
+ * True only on the harness-private native-raw channel: seed `Ctx` from the
35
+ * unprefixed env globals DRY_RUN and DOCKS_KIT_VERBOSE
36
+ * (the historical ${VAR:-default} contract). The public CLI takes the same
37
+ * behavior from flags.
38
+ */
91
39
  readonly envGlobals: boolean;
92
40
  }
93
41
 
94
42
  /**
95
- * Build the run context. HOME and DOCKS_KIT_INTERACTIVE apply on every path;
96
- * ENV_GLOBAL_KEYS apply only when `options.envGlobals` is true.
43
+ * Build the run context. HOME applies on every path;
44
+ * the env globals apply only when `options.envGlobals` is true.
97
45
  */
98
46
  export function makeCtx(services: EngineServices, options: CtxOptions): Ctx {
99
47
  const env = process.env;
100
48
  const home = engineHome(env);
101
49
  const globals: NodeJS.ProcessEnv = options.envGlobals ? env : {};
102
- const compactWindowSource = globals["CLAUDE_COMPACT_WINDOW"] ?? "";
103
- const claudeCompactWindow =
104
- compactWindowSource === "" ? "" : parseCompactWindow(compactWindowSource);
105
- if (claudeCompactWindow === undefined) {
106
- services.logger.err("CLAUDE_COMPACT_WINDOW expects a token count (e.g. 680000 or 680k)");
107
- throw new ExitError(2);
108
- }
109
- const claudePlugins = (globals["CLAUDE_PLUGINS"] ?? "")
110
- .split(" ")
111
- .filter((plugin) => plugin !== "")
112
- .map((plugin) => parseClaudePlugin(plugin, services.logger.err));
113
50
  return {
114
51
  repoDir: kitHome(),
115
52
  home,
116
- agentsDir:
117
- globals["AGENTS_DIR"] !== undefined && globals["AGENTS_DIR"] !== ""
118
- ? globals["AGENTS_DIR"]
119
- : p(home, ".agents"),
120
- interactive:
121
- env["DOCKS_KIT_INTERACTIVE"] === "1" ||
122
- (env["DOCKS_KIT_INTERACTIVE"] !== "0" &&
123
- process.stdout.isTTY === true &&
124
- process.stdin.isTTY === true),
125
53
  dryRun: globals["DRY_RUN"] === "1",
126
54
  verbose: globals["DOCKS_KIT_VERBOSE"] === "1",
127
- skipBubblewrap: globals["SKIP_BUBBLEWRAP"] === "1",
128
55
  skipPluginRefresh: false,
129
- reconcile: globals["RECONCILE"] === "1",
130
- prune: globals["PRUNE"] === "1",
131
- claudeCompactWindow,
132
- claudePermissive: globals["CLAUDE_PERMISSIVE"] === "1",
133
- claudePlugins,
134
- claudeModel: globals["CLAUDE_MODEL"] ?? "",
135
- claudeEffort: "",
136
- claudeAdvisor: "",
137
- codexModel: globals["CODEX_MODEL"] ?? "",
138
- codexEffort: "",
139
- modifierFlags: new Set(),
140
- syncConcurrency: 3,
141
56
  services,
142
- targetFilterSet: false,
143
- syncClaude: false,
144
- syncCodex: false,
145
- syncAgents: false,
146
- syncOmp: false,
147
57
  nextStepTriggers: {
148
- claudePlugins: false,
149
- claudeRestart: false,
150
- codexRestart: false,
151
- skillsRestart: false,
152
58
  ompRestart: false,
153
59
  ompPluginUpgraded: false,
154
60
  },
@@ -12,7 +12,7 @@ import {
12
12
  type SpawnSyncOptionsWithStringEncoding,
13
13
  type SpawnSyncReturns,
14
14
  } from "node:child_process";
15
- import { accessSync, constants, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
15
+ import { accessSync, constants, statSync } from "node:fs";
16
16
  import { delimiter, extname, isAbsolute, join } from "node:path";
17
17
  import { hostOs, type HostOs, type Invocation } from "./os";
18
18
 
@@ -344,20 +344,3 @@ function isExecutable(
344
344
  return false;
345
345
  }
346
346
  }
347
-
348
- // Change-detection primitives (Output Policy in DESIGN.md): operations report
349
- // changed:boolean so unchanged repeat runs log at verbose instead of [ok].
350
-
351
- /** Write only when the content differs; returns whether a write happened. */
352
- export function writeTextIfChanged(path: string, content: string): boolean {
353
- if (existsSync(path) && readFileSync(path, "utf8") === content) return false;
354
- writeFileSync(path, content);
355
- return true;
356
- }
357
-
358
- export function writeBytesIfChanged(path: string, content: Uint8Array): boolean {
359
- const bytes = Buffer.from(content);
360
- if (existsSync(path) && readFileSync(path).equals(bytes)) return false;
361
- writeFileSync(path, bytes);
362
- return true;
363
- }