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.
- package/AGENTS.md +35 -81
- package/README.md +31 -58
- package/cli/docs/command-guards.md +231 -197
- package/cli/docs/flags.md +25 -55
- package/cli/docs/install.md +2 -3
- package/cli/docs/omp-context.md +5 -5
- package/cli/docs/omp-models.md +249 -48
- package/cli/docs/overview.md +4 -12
- package/cli/docs/platforms.md +2 -2
- package/cli/docs/sync-layers.md +10 -57
- package/cli/docs/toolchain.md +9 -78
- package/cli/src/argv.ts +0 -8
- package/cli/src/argvValidate.ts +2 -46
- package/cli/src/commands/docs.ts +2 -14
- package/cli/src/commands/harnesses.ts +6 -9
- package/cli/src/commands/sync.ts +5 -99
- package/cli/src/commands/toolchain.ts +4 -12
- package/cli/src/engine-native/DESIGN.md +67 -88
- package/cli/src/engine-native/deps.ts +6 -86
- package/cli/src/engine-native/engineCtx.ts +7 -76
- package/cli/src/engine-native/exec.ts +1 -18
- package/cli/src/engine-native/harnesses.ts +6 -6
- package/cli/src/engine-native/index.ts +4 -6
- package/cli/src/engine-native/jq.ts +4 -37
- package/cli/src/engine-native/modes.ts +3 -132
- package/cli/src/engine-native/ompRemovals.ts +14 -0
- 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 -46
- package/cli/src/engine-native/os/types.ts +1 -32
- package/cli/src/engine-native/os/windows.ts +0 -49
- package/cli/src/engine-native/parseArgs.ts +11 -124
- package/cli/src/engine-native/parseHelp.ts +5 -40
- 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 +0 -40
- package/cli/src/engine-native/skillsSync.ts +1 -1
- package/cli/src/engine-native/syncConcurrency.ts +3 -15
- package/cli/src/engine-native/syncDispatch.ts +10 -57
- package/cli/src/engine-native/toolchain.ts +5 -40
- package/cli/src/engine.ts +0 -75
- package/cli/src/generated/sotPayload.ts +14 -41
- package/cli/src/main.ts +7 -19
- package/cli/src/manifests.ts +1 -93
- 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/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/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/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/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
|
|
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`, `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
|
|
15
|
-
|
|
16
|
-
|
|
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
|
-
- `
|
|
26
|
-
|
|
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
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
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
|
|
51
|
-
the
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
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,
|
|
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
|
|
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.
|
|
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
|
-
`
|
|
123
|
-
|
|
124
|
-
|
|
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: `
|
|
132
|
-
`
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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
|
|
170
|
-
|
|
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` `
|
|
173
|
-
|
|
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
|
|
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
|
|
185
|
-
|
|
|
186
|
-
| `parseArgs.ts`
|
|
187
|
-
| `
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
| `
|
|
191
|
-
|
|
|
192
|
-
|
|
|
193
|
-
| `
|
|
194
|
-
| `
|
|
195
|
-
| `
|
|
196
|
-
| `
|
|
197
|
-
| `
|
|
198
|
-
| `
|
|
199
|
-
| `
|
|
200
|
-
| `
|
|
201
|
-
| `
|
|
202
|
-
| `
|
|
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
|
|
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,
|
|
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.
|
|
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
|
|
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,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
|
-
/**
|
|
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
|
-
*
|
|
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,
|
|
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
|
-
*
|
|
4
|
-
*
|
|
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 = "
|
|
11
|
+
export type Harness = "agents" | "omp";
|
|
12
12
|
|
|
13
|
-
export const HARNESSES: ReadonlyArray<Harness> = ["
|
|
14
|
-
export const
|
|
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 === "
|
|
24
|
+
return value === "agents" || value === "omp";
|
|
25
25
|
}
|
|
26
26
|
|
|
27
27
|
function normalizeHarnesses(selection: ReadonlyArray<unknown>): Array<Harness> {
|