docks-kit 0.22.25 → 0.23.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 (77) hide show
  1. package/AGENTS.md +35 -81
  2. package/README.md +31 -58
  3. package/cli/docs/command-guards.md +231 -197
  4. package/cli/docs/flags.md +25 -55
  5. package/cli/docs/install.md +2 -3
  6. package/cli/docs/omp-context.md +5 -5
  7. package/cli/docs/omp-models.md +249 -48
  8. package/cli/docs/overview.md +4 -12
  9. package/cli/docs/platforms.md +2 -2
  10. package/cli/docs/sync-layers.md +10 -57
  11. package/cli/docs/toolchain.md +9 -78
  12. package/cli/src/argv.ts +0 -8
  13. package/cli/src/argvValidate.ts +2 -46
  14. package/cli/src/commands/docs.ts +2 -14
  15. package/cli/src/commands/harnesses.ts +6 -9
  16. package/cli/src/commands/sync.ts +5 -99
  17. package/cli/src/commands/toolchain.ts +4 -12
  18. package/cli/src/engine-native/DESIGN.md +67 -88
  19. package/cli/src/engine-native/deps.ts +6 -86
  20. package/cli/src/engine-native/engineCtx.ts +7 -76
  21. package/cli/src/engine-native/exec.ts +1 -18
  22. package/cli/src/engine-native/harnesses.ts +6 -6
  23. package/cli/src/engine-native/index.ts +4 -6
  24. package/cli/src/engine-native/jq.ts +4 -37
  25. package/cli/src/engine-native/modes.ts +3 -132
  26. package/cli/src/engine-native/ompRemovals.ts +14 -0
  27. package/cli/src/engine-native/os/darwin.ts +0 -4
  28. package/cli/src/engine-native/os/index.ts +1 -2
  29. package/cli/src/engine-native/os/linux.ts +0 -3
  30. package/cli/src/engine-native/os/posix.ts +2 -46
  31. package/cli/src/engine-native/os/types.ts +1 -32
  32. package/cli/src/engine-native/os/windows.ts +0 -49
  33. package/cli/src/engine-native/parseArgs.ts +11 -124
  34. package/cli/src/engine-native/parseHelp.ts +5 -40
  35. package/cli/src/engine-native/scratch.ts +1 -1
  36. package/cli/src/engine-native/services.ts +1 -2
  37. package/cli/src/engine-native/sharedTypes.d.ts +0 -40
  38. package/cli/src/engine-native/skillsSync.ts +1 -1
  39. package/cli/src/engine-native/syncConcurrency.ts +3 -15
  40. package/cli/src/engine-native/syncDispatch.ts +10 -57
  41. package/cli/src/engine-native/toolchain.ts +5 -40
  42. package/cli/src/engine.ts +0 -75
  43. package/cli/src/generated/sotPayload.ts +14 -41
  44. package/cli/src/main.ts +7 -19
  45. package/cli/src/manifests.ts +1 -93
  46. package/cli/src/payload.ts +2 -8
  47. package/cli/tsconfig.json +1 -3
  48. package/package.json +3 -5
  49. package/cli/docs/models.md +0 -58
  50. package/cli/docs/modifiers.md +0 -52
  51. package/cli/docs/plugins.md +0 -70
  52. package/cli/src/commands/model.ts +0 -68
  53. package/cli/src/commands/models.ts +0 -75
  54. package/cli/src/commands/plugins.ts +0 -35
  55. package/cli/src/commands/status.ts +0 -206
  56. package/cli/src/efforts.ts +0 -89
  57. package/cli/src/engine-native/claudeLsp.ts +0 -301
  58. package/cli/src/engine-native/claudeOptionalPlugins.ts +0 -126
  59. package/cli/src/engine-native/claudePluginPasses.ts +0 -426
  60. package/cli/src/engine-native/claudeRemovals.ts +0 -383
  61. package/cli/src/engine-native/claudeRetired.ts +0 -165
  62. package/cli/src/engine-native/claudeRuntime.ts +0 -157
  63. package/cli/src/engine-native/claudeSettings.ts +0 -201
  64. package/cli/src/engine-native/claudeSettingsModifiers.ts +0 -115
  65. package/cli/src/engine-native/claudeSync.ts +0 -312
  66. package/cli/src/engine-native/codexConfig.ts +0 -214
  67. package/cli/src/engine-native/codexHooks.ts +0 -91
  68. package/cli/src/engine-native/codexPaths.ts +0 -14
  69. package/cli/src/engine-native/codexPlugins.ts +0 -315
  70. package/cli/src/engine-native/codexStatus.ts +0 -25
  71. package/cli/src/engine-native/codexSync.ts +0 -314
  72. package/cli/src/engine-native/codexToml.ts +0 -303
  73. package/cli/src/engine-native/liveModels.ts +0 -264
  74. package/cli/src/engine-native/models.ts +0 -101
  75. package/cli/src/engine-native/parseModifiers.ts +0 -225
  76. package/cli/src/engine-native/settings.ts +0 -42
  77. package/cli/src/engine-native/tomlLines.ts +0 -92
@@ -1,30 +1,27 @@
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`, `harnesses`, `update`, `skills`, `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, target
16
+ words, and flag spellings.
19
17
  - Other public commands call engine-native modules directly, for example
20
18
  `tidy.ts` `planTidy` and `applyTidy`, `scratch.ts` `createScratchDir`, and
21
19
  `harnesses.ts` `readHarnessSelection`.
22
20
  - `DOCKS_KIT_ENGINE=native-raw` is harness-private: it bypasses `effect/cli`
23
21
  and hands argv directly to EngineNative so tests can exercise the internal
24
22
  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.
23
+ - `main.ts` runs the native-raw channel with `{ envGlobals: true }`; it is the
24
+ only channel that honors the env globals.
28
25
 
29
26
  ## Behavior Contract
30
27
 
@@ -37,24 +34,22 @@ shell engine was removed after the `bash-engine-final` tag.
37
34
  - **Prove-red stays red.** The golden suites compare live native output to a
38
35
  mismatched golden under `--prove-red` and must exit non-zero after printing
39
36
  `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
37
+ - **Step ordering is load-bearing.** The omp pipeline resolves Bun, deploys
38
+ the whole files, merges `config.yml` and runs the retired-key removals on
39
+ the merged result, merges `models.yml` and runs its removals, writes the
40
+ intercom configuration, materializes the kit plugin, and only then runs the
41
+ marketplace and plugin passes, because the plugin pass links the kit plugin
42
+ directory.
43
+ - **Pipeline concurrency is bounded.** The selected skills and omp pipelines
44
+ run through one input-ordered pool (`syncConcurrency.ts` `runBounded`). The
45
+ production default cap is 3, so both pipelines run at once. After the first
48
46
  rejection, started pipelines drain and queued pipelines never start.
49
47
  `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.
48
+ and debugging. Each individual pipeline remains serial, and summaries keep
49
+ the skills, omp order.
50
+ - **External CLIs stay external.** `omp`, `npx`, `npm`, `bun`, and `curl` are
51
+ spawned with argv arrays, not shell command strings except where an external
52
+ installer contract requires a script interpreter.
58
53
  - **Backups precede mutation.** Deployed settings/config files write `.bak`
59
54
  backups before replacement.
60
55
  - **Runtime payload is in memory.** `SoT/` remains the reviewed authoring tree;
@@ -77,10 +72,10 @@ warnings, and the summary. Status-quo confirmations exist but are opt-in.
77
72
  | `change(msg)` | stderr | shown | shown | `[ok]` green (`\x1b[1;32m`) — ONLY after an operation actually mutated |
78
73
  | `verbose(msg)` | stderr | hidden | shown | `[ok]` green — no-op confirmations ("already …", "present", "up to date", "left as-is"), skips |
79
74
  | `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 |
75
+ | `echo(line)` | stdout | shown | shown | bare — dry-run report lines, summary block, usage text |
81
76
 
82
77
  - stdout is data, stderr is logs — only `echo` writes to stdout, and every
83
- log emitter writes to stderr (`engineCapture` depends on it).
78
+ log emitter writes to stderr.
84
79
  - **Dry-run is a complete inspection report**: `[dry-run]` lines use `echo`
85
80
  and print unfiltered at every verbosity.
86
81
  - Prefixes and ANSI codes are stable golden surface; the level controls
@@ -114,26 +109,23 @@ Exactly one deduplicated warn per requested missing tool per run, uniform shape:
114
109
  `[warn] <tool> not installed — <platform-correct install command>`, sourced
115
110
  from the dependency registry (`deps.ts`). jq and curl are optional report rows:
116
111
  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.
112
+ bootstrap needs an installer download.
119
113
 
120
114
  ### Summary and next steps
121
115
 
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.
116
+ `toolchain` modes have no separate summary block by design — their stdout IS
117
+ the deliverable (the report table for `toolchain check`), so nothing prints
118
+ after it. The schema below applies to `sync` only.
126
119
 
127
120
  The `--- Sync complete ---` block (stdout, `echo`) prints after the selected
128
121
  pipelines settle, also on dry-run. When a pipeline rejects, `syncDispatch.ts`
129
122
  `engineSync` skips the block and prints only the `--- Failures ---` ledger.
130
123
  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`.
124
+ selected target: `Skills:` and `omp:`/`omp plugins:`. Dry-run leaves out the
125
+ `omp plugins:` line. Next-step advice lines print only when their trigger
126
+ changed this run (an omp plugin upgraded → `/reload-plugins` line; omp files
127
+ changed → restart line; skills changed → discovery line) or under
128
+ `--verbose`.
137
129
 
138
130
  ### Platform seam
139
131
 
@@ -166,13 +158,13 @@ on the host directly.
166
158
 
167
159
  ### Verbosity plumbing
168
160
 
169
- `--verbose` / `-v` on the public `sync`, `model`, and `toolchain` commands
170
- selects verbose output. On the harness-private raw channel,
161
+ `--verbose` / `-v` on the public `sync` and `toolchain` commands selects
162
+ verbose output. On the harness-private raw channel,
171
163
  `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
164
+ unprefixed `Ctx` env globals (`engineCtx.ts makeCtx` reads `DRY_RUN`,
165
+ `DOCKS_KIT_VERBOSE`, `PRUNE`, and `AGENTS_DIR`). `main.ts` passes `{ envGlobals: true }` to
174
166
  `runEngineNative` only on that channel. The public `engine()` seam ignores
175
- these variables, and `engineCapture` removes them from the child environment.
167
+ these variables.
176
168
  The default service factory returns a raw Logger. `runEngineNative` wraps the
177
169
  default or injected Logger with explicit delegates and owns the sole
178
170
  `ctx.verbose` gate.
@@ -181,36 +173,25 @@ active logger binding.
181
173
 
182
174
  ## Module Map
183
175
 
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` |
176
+ | Module | Owns |
177
+ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
178
+ | `parseArgs.ts` | engine usage, target selection, argv dispatch loop, legacy rename hints; re-exports the `parseHelp.ts` help text and early-exit error |
179
+ | `index.ts` | entry routing (`toolchain`/`sync`) and the run-scoped verbosity gate |
180
+ | `engineCtx.ts` | `Ctx` shape and `makeCtx`; the unprefixed env globals apply only on the native-raw channel |
181
+ | `syncDispatch.ts` | pipeline selection, pool dispatch, run summary, next-step blocks, and the `--- Failures ---` ledger |
182
+ | `syncConcurrency.ts` | input-ordered bounded pool (`runBounded`) |
183
+ | `../payload.ts` | generated text payload reads and presentation-only source labels |
184
+ | `bun.ts` | per-run memoized Bun resolution/bootstrap shared by the omp pipeline and direct toolchain ensure |
185
+ | `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/skills` entry healing, and `skillsPrune.ts` the prune and managed-skill snapshot |
186
+ | `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 |
187
+ | `toolchain.ts` | tool presence/version probes, verified-version floor reporting, report table |
188
+ | `modes.ts` | direct `toolchain` mode |
189
+ | `jq.ts` | the `Json` value type, object narrowing, jq-compatible codepoint ordering, and a parse that yields `undefined` instead of throwing |
190
+ | `exec.ts` | slash-stable path helpers, host-aware PATH probes and invocation, capture/spawn wrappers, and change-detecting write/copy helpers |
191
+ | `logger.ts` | Logger shape + stable raw stdout/stderr sink factory; the run-scoped verbosity gate lives in `index.ts` |
192
+ | `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`) |
193
+ | `os/` | host reader, injected platform normalization, and per-OS `HostOs` fact modules |
194
+ | `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
195
 
215
196
  ## Platform Support
216
197
 
@@ -218,8 +199,6 @@ active logger binding.
218
199
  x64.
219
200
  - Unsupported hosts fail before launcher fallback, dependency probes, downloads,
220
201
  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
202
  - Directory linking is capability-driven. The host module supplies only the
224
203
  order while the runtime decides the outcome: symlink, then a Windows junction
225
204
  with an absolute target, then a recursive copy. Copies carry a kit marker so
@@ -233,15 +212,16 @@ active logger binding.
233
212
  - `bun run golden:dryrun` compares live native dry-run output to
234
213
  `cli/test/goldens/dryrun.json`.
235
214
  - `bun run golden:mutation` compares live native mutation snapshots, argv logs,
236
- output, and TOML invariants to `cli/test/goldens/mutation.json`.
215
+ output, and the channel and migration invariants to
216
+ `cli/test/goldens/mutation.json`.
237
217
  - `.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.
218
+ `macos-26`: generated-payload check, typecheck, unit tests, a clean-room
219
+ package install smoke, and compilation and execution of the native host
220
+ artifact. On `windows-2025`, two unit-test shards and the
221
+ `portable-windows-checks` job (generated-payload check, typecheck, native
222
+ artifact) run in parallel. The check `portable (windows-2025)` passes only
223
+ when all three pass. The Linux-canonical snapshot lane stays on Ubuntu and
224
+ runs both golden suites plus their prove-red checks.
245
225
  - `.github/workflows/release-cli.yml` publishes four binaries (Linux x64 and
246
226
  arm64, macOS arm64, Windows x64), plus `SHA256SUMS` and the npm package.
247
227
 
@@ -249,5 +229,4 @@ active logger binding.
249
229
 
250
230
  - Reintroducing the removed shell engine as a supported fallback. Fix forward in
251
231
  EngineNative; recover historical source only from `bash-engine-final`.
252
- - Adding a compiled runner or CLI hook subcommand for Claude's Bun runtime.
253
232
  - Adding new sync features while changing the engine contract.
@@ -11,33 +11,11 @@ import { isAbsolute } from "node:path";
11
11
 
12
12
  import { capture, captureWithin, commandExists, p, which, type CaptureOutcome } from "./exec";
13
13
  import { engineHome } from "./harnesses";
14
- import { isObject, parseJson } from "./jq";
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" | "node" | "npm" | "npx" | "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,35 +138,6 @@ 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> = {
@@ -204,8 +153,6 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
204
153
  "npx",
205
154
  () => "ships with Node.js — install via https://nodejs.org (or your package manager)",
206
155
  ),
207
- claude: spec("claude", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("claude")),
208
- codex: spec("codex", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("codex")),
209
156
  omp: spec(
210
157
  "omp",
211
158
  () =>
@@ -223,33 +170,6 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
223
170
  return await exec.capture(bun.command, ["--version"]);
224
171
  },
225
172
  }),
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
173
  };
254
174
 
255
175
  export function resolveDependency(
@@ -8,20 +8,9 @@ import { engineHome } from "./harnesses";
8
8
  import type { TerminalLease } from "./logger";
9
9
  import type { BunRuntimeState } from "./bun";
10
10
  import { kitHome } from "../kitHome";
11
- import { ExitError, parseClaudePlugin, parseCompactWindow } from "./parseArgs";
12
11
  import type { EngineServices } from "./services";
13
12
  import type { SyncConcurrency } from "./syncConcurrency";
14
13
 
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
-
25
14
  export interface Ctx {
26
15
  readonly repoDir: string;
27
16
  readonly home: string;
@@ -29,35 +18,18 @@ export interface Ctx {
29
18
  readonly interactive: boolean;
30
19
  dryRun: boolean;
31
20
  verbose: boolean;
32
- skipBubblewrap: boolean;
33
21
  skipPluginRefresh?: boolean;
34
- reconcile: boolean;
35
22
  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
23
  /** Injected capability seam (logger/deps/platform) — see services.ts. */
47
24
  readonly services: EngineServices;
48
25
  syncConcurrency: SyncConcurrency;
49
26
  terminalLease?: TerminalLease;
50
27
  bunRuntime?: Promise<BunRuntimeState>;
51
28
  targetFilterSet: boolean;
52
- syncClaude: boolean;
53
- syncCodex: boolean;
54
29
  syncAgents: boolean;
55
30
  syncOmp: boolean;
56
31
  /** Per-run next-step triggers (Output Policy): advice prints only when its trigger changed or --verbose. */
57
32
  readonly nextStepTriggers: {
58
- claudePlugins: boolean;
59
- claudeRestart: boolean;
60
- codexRestart: boolean;
61
33
  skillsRestart: boolean;
62
34
  ompRestart: boolean;
63
35
  /** A marketplace plugin upgrade changed a version, so running omp sessions lost its folder. */
@@ -67,49 +39,24 @@ export interface Ctx {
67
39
  readonly failures: Array<string>;
68
40
  }
69
41
 
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
42
  export interface CtxOptions {
90
- /** True only on the native-raw channel: read ENV_GLOBAL_KEYS from the environment. */
43
+ /**
44
+ * True only on the harness-private native-raw channel: seed `Ctx` from the
45
+ * unprefixed env globals DRY_RUN, DOCKS_KIT_VERBOSE, PRUNE, and AGENTS_DIR
46
+ * (the historical ${VAR:-default} contract). The public CLI takes the same
47
+ * behavior from flags.
48
+ */
91
49
  readonly envGlobals: boolean;
92
50
  }
93
51
 
94
52
  /**
95
53
  * Build the run context. HOME and DOCKS_KIT_INTERACTIVE apply on every path;
96
- * ENV_GLOBAL_KEYS apply only when `options.envGlobals` is true.
54
+ * the env globals apply only when `options.envGlobals` is true.
97
55
  */
98
56
  export function makeCtx(services: EngineServices, options: CtxOptions): Ctx {
99
57
  const env = process.env;
100
58
  const home = engineHome(env);
101
59
  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
60
  return {
114
61
  repoDir: kitHome(),
115
62
  home,
@@ -124,30 +71,14 @@ export function makeCtx(services: EngineServices, options: CtxOptions): Ctx {
124
71
  process.stdin.isTTY === true),
125
72
  dryRun: globals["DRY_RUN"] === "1",
126
73
  verbose: globals["DOCKS_KIT_VERBOSE"] === "1",
127
- skipBubblewrap: globals["SKIP_BUBBLEWRAP"] === "1",
128
74
  skipPluginRefresh: false,
129
- reconcile: globals["RECONCILE"] === "1",
130
75
  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
76
  syncConcurrency: 3,
141
77
  services,
142
78
  targetFilterSet: false,
143
- syncClaude: false,
144
- syncCodex: false,
145
79
  syncAgents: false,
146
80
  syncOmp: false,
147
81
  nextStepTriggers: {
148
- claudePlugins: false,
149
- claudeRestart: false,
150
- codexRestart: false,
151
82
  skillsRestart: false,
152
83
  ompRestart: false,
153
84
  ompPluginUpgraded: false,
@@ -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
- }
@@ -1,17 +1,17 @@
1
1
  /**
2
2
  * Per-machine harness selection and omp session model, stored in ~/.docks-kit/kit.db (kitDb.ts).
3
- * The selection keeps the omp harness opt-in. A missing or unreadable store is
4
- * represented by undefined so callers resolve it to LEGACY_SELECTION.
3
+ * A missing or unreadable store is represented by undefined so callers
4
+ * resolve it to DEFAULT_SELECTION.
5
5
  */
6
6
  import { homedir } from "node:os";
7
7
 
8
8
  import { inTransaction, isNonBlankString, nonBlankOrNull, withKitDb } from "./kitDb";
9
9
  import type { OmpSessionModel } from "./sharedTypes";
10
10
 
11
- export type Harness = "claude" | "codex" | "agents" | "omp";
11
+ export type Harness = "agents" | "omp";
12
12
 
13
- export const HARNESSES: ReadonlyArray<Harness> = ["claude", "codex", "agents", "omp"];
14
- export const LEGACY_SELECTION: ReadonlyArray<Harness> = ["claude", "codex", "agents"];
13
+ export const HARNESSES: ReadonlyArray<Harness> = ["agents", "omp"];
14
+ export const DEFAULT_SELECTION: ReadonlyArray<Harness> = ["agents", "omp"];
15
15
 
16
16
  export type { OmpSessionModel };
17
17
 
@@ -21,7 +21,7 @@ export const DEFAULT_OMP_SESSION_MODEL: OmpSessionModel = {
21
21
  };
22
22
 
23
23
  function isHarness(value: unknown): value is Harness {
24
- return value === "claude" || value === "codex" || value === "agents" || value === "omp";
24
+ return value === "agents" || value === "omp";
25
25
  }
26
26
 
27
27
  function normalizeHarnesses(selection: ReadonlyArray<unknown>): Array<Harness> {