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.
- package/AGENTS.md +42 -89
- package/README.md +35 -72
- package/cli/docs/command-guards.md +233 -197
- package/cli/docs/flags.md +17 -65
- package/cli/docs/install.md +2 -3
- package/cli/docs/omp-context.md +79 -7
- package/cli/docs/omp-models.md +27 -12
- package/cli/docs/overview.md +7 -18
- package/cli/docs/platforms.md +2 -2
- package/cli/docs/sync-layers.md +14 -60
- package/cli/docs/toolchain.md +12 -81
- package/cli/src/argv.ts +0 -12
- package/cli/src/argvValidate.ts +3 -54
- package/cli/src/commands/docs.ts +3 -15
- package/cli/src/commands/omp.ts +1 -1
- package/cli/src/commands/scratch.ts +1 -1
- package/cli/src/commands/sync.ts +5 -120
- package/cli/src/commands/tidy.ts +1 -1
- package/cli/src/commands/toolchain.ts +4 -12
- package/cli/src/engine-native/DESIGN.md +69 -100
- package/cli/src/engine-native/deps.ts +7 -92
- package/cli/src/engine-native/engineCtx.ts +9 -103
- package/cli/src/engine-native/exec.ts +1 -18
- package/cli/src/engine-native/index.ts +6 -8
- package/cli/src/engine-native/jq.ts +4 -37
- package/cli/src/engine-native/kitDb.ts +21 -37
- package/cli/src/engine-native/modes.ts +3 -132
- package/cli/src/engine-native/ompFastMode.ts +1 -1
- package/cli/src/engine-native/ompOverlay.ts +1 -1
- package/cli/src/engine-native/ompRemovals.ts +24 -3
- package/cli/src/engine-native/ompSession.ts +67 -0
- package/cli/src/engine-native/ompSync.ts +1 -1
- package/cli/src/engine-native/os/darwin.ts +0 -4
- package/cli/src/engine-native/os/index.ts +1 -2
- package/cli/src/engine-native/os/linux.ts +0 -3
- package/cli/src/engine-native/os/posix.ts +2 -47
- package/cli/src/engine-native/os/types.ts +1 -36
- package/cli/src/engine-native/os/windows.ts +0 -50
- package/cli/src/engine-native/parseArgs.ts +7 -180
- package/cli/src/engine-native/parseHelp.ts +4 -44
- package/cli/src/engine-native/scratch.ts +1 -1
- package/cli/src/engine-native/services.ts +1 -2
- package/cli/src/engine-native/sharedTypes.d.ts +1 -41
- package/cli/src/engine-native/syncConcurrency.ts +3 -15
- package/cli/src/engine-native/syncDispatch.ts +30 -143
- package/cli/src/engine-native/toolchain.ts +6 -45
- package/cli/src/engine.ts +0 -75
- package/cli/src/generated/sotPayload.ts +14 -43
- package/cli/src/main.ts +8 -24
- package/cli/src/payload.ts +2 -8
- package/cli/tsconfig.json +1 -3
- package/package.json +3 -5
- package/cli/docs/models.md +0 -58
- package/cli/docs/modifiers.md +0 -52
- package/cli/docs/plugins.md +0 -70
- package/cli/src/checklistPrompt.ts +0 -464
- package/cli/src/commands/harnesses.ts +0 -80
- package/cli/src/commands/model.ts +0 -68
- package/cli/src/commands/models.ts +0 -75
- package/cli/src/commands/plugins.ts +0 -35
- package/cli/src/commands/skills.ts +0 -40
- package/cli/src/commands/status.ts +0 -206
- package/cli/src/efforts.ts +0 -89
- package/cli/src/engine-native/claudeLsp.ts +0 -301
- package/cli/src/engine-native/claudeOptionalPlugins.ts +0 -126
- package/cli/src/engine-native/claudePluginPasses.ts +0 -426
- package/cli/src/engine-native/claudeRemovals.ts +0 -383
- package/cli/src/engine-native/claudeRetired.ts +0 -165
- package/cli/src/engine-native/claudeRuntime.ts +0 -157
- package/cli/src/engine-native/claudeSettings.ts +0 -201
- package/cli/src/engine-native/claudeSettingsModifiers.ts +0 -115
- package/cli/src/engine-native/claudeSync.ts +0 -312
- package/cli/src/engine-native/codexConfig.ts +0 -214
- package/cli/src/engine-native/codexHooks.ts +0 -91
- package/cli/src/engine-native/codexPaths.ts +0 -14
- package/cli/src/engine-native/codexPlugins.ts +0 -315
- package/cli/src/engine-native/codexStatus.ts +0 -25
- package/cli/src/engine-native/codexSync.ts +0 -314
- package/cli/src/engine-native/codexToml.ts +0 -303
- package/cli/src/engine-native/harnesses.ts +0 -138
- package/cli/src/engine-native/liveModels.ts +0 -264
- package/cli/src/engine-native/models.ts +0 -101
- package/cli/src/engine-native/parseModifiers.ts +0 -225
- package/cli/src/engine-native/settings.ts +0 -42
- package/cli/src/engine-native/skillsInstall.ts +0 -135
- package/cli/src/engine-native/skillsLinks.ts +0 -216
- package/cli/src/engine-native/skillsManifest.ts +0 -36
- package/cli/src/engine-native/skillsPrune.ts +0 -117
- package/cli/src/engine-native/skillsRecords.ts +0 -138
- package/cli/src/engine-native/skillsSync.ts +0 -57
- package/cli/src/engine-native/tomlLines.ts +0 -92
- package/cli/src/manifests.ts +0 -145
- 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
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
`
|
|
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
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
-
`
|
|
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
|
-
- `
|
|
26
|
-
|
|
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
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
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,
|
|
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
|
|
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.
|
|
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
|
-
`
|
|
123
|
-
|
|
124
|
-
|
|
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
|
|
128
|
-
|
|
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
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
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 `
|
|
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
|
|
170
|
-
|
|
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` `
|
|
173
|
-
|
|
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
|
|
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
|
|
185
|
-
|
|
|
186
|
-
| `parseArgs.ts`
|
|
187
|
-
| `
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
| `
|
|
191
|
-
|
|
|
192
|
-
|
|
|
193
|
-
| `
|
|
194
|
-
| `
|
|
195
|
-
| `
|
|
196
|
-
| `
|
|
197
|
-
| `
|
|
198
|
-
| `
|
|
199
|
-
| `
|
|
200
|
-
| `
|
|
201
|
-
| `
|
|
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
|
|
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,
|
|
239
|
-
compilation and execution of the native host
|
|
240
|
-
two unit-test shards and
|
|
241
|
-
|
|
242
|
-
`portable (windows-2025)` passes only
|
|
243
|
-
Linux-canonical snapshot lane stays on Ubuntu and
|
|
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 "./
|
|
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
|
|
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:
|
|
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
|
-
*
|
|
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
|
|
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 {
|
|
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
|
-
/**
|
|
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
|
|
96
|
-
*
|
|
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,
|
|
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
|
-
}
|