docks-kit 0.22.28 → 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 +31 -77
- 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-models.md +9 -0
- 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/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 +12 -39
- 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
package/cli/src/commands/sync.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { Argument, Command, Flag } from "effect/cli";
|
|
2
|
-
import { Effect
|
|
2
|
+
import { Effect } from "effect";
|
|
3
3
|
import { existsSync } from "node:fs";
|
|
4
4
|
import { join } from "node:path";
|
|
5
5
|
import { bail, engine } from "../engine";
|
|
@@ -35,12 +35,10 @@ export const updateNudge = (logger: Logger): void => {
|
|
|
35
35
|
}
|
|
36
36
|
};
|
|
37
37
|
|
|
38
|
-
const VALID_TARGETS = ["
|
|
38
|
+
const VALID_TARGETS = ["agents", "omp"];
|
|
39
39
|
|
|
40
40
|
const targets: Argument.Argument<ReadonlyArray<string>> = Argument.String("target").pipe(
|
|
41
|
-
Argument.withDescription(
|
|
42
|
-
"Sync targets: claude, codex, agents, omp (default: selected harnesses)",
|
|
43
|
-
),
|
|
41
|
+
Argument.withDescription("Sync targets: agents, omp (default: selected harnesses)"),
|
|
44
42
|
Argument.variadic(),
|
|
45
43
|
);
|
|
46
44
|
|
|
@@ -48,20 +46,8 @@ const dryRun = Flag.Boolean("dry-run").pipe(
|
|
|
48
46
|
Flag.withDescription("Preview without applying"),
|
|
49
47
|
Flag.withDefault(false),
|
|
50
48
|
);
|
|
51
|
-
const reconcile = Flag.Boolean("reconcile").pipe(
|
|
52
|
-
Flag.withDescription(
|
|
53
|
-
"Reconcile kit-owned settings with SoT (SoT keys win; user-only keys preserved; permissions arrays replaced)",
|
|
54
|
-
),
|
|
55
|
-
Flag.withDefault(false),
|
|
56
|
-
);
|
|
57
49
|
const prune = Flag.Boolean("prune").pipe(
|
|
58
|
-
Flag.withDescription(
|
|
59
|
-
"Uninstall kit-managed installs not in SoT (plugins, marketplaces, universal skills)",
|
|
60
|
-
),
|
|
61
|
-
Flag.withDefault(false),
|
|
62
|
-
);
|
|
63
|
-
const skipBubblewrap = Flag.Boolean("skip-bubblewrap").pipe(
|
|
64
|
-
Flag.withDescription("Skip optional bubblewrap bootstrap (Codex Linux sandbox)"),
|
|
50
|
+
Flag.withDescription("Remove kit-managed universal skills not in SoT/.agents/skills.txt"),
|
|
65
51
|
Flag.withDefault(false),
|
|
66
52
|
);
|
|
67
53
|
const skipPluginRefresh = Flag.Boolean("skip-plugin-refresh").pipe(
|
|
@@ -75,71 +61,15 @@ const verbose = Flag.Boolean("verbose").pipe(
|
|
|
75
61
|
Flag.withDescription("Also print no-op confirmations (already in sync, up to date, left as-is)"),
|
|
76
62
|
Flag.withDefault(false),
|
|
77
63
|
);
|
|
78
|
-
const claudeModel = Flag.String("claude-model").pipe(
|
|
79
|
-
Flag.withDescription(
|
|
80
|
-
"Deploy-time modifier: set deployed Claude model (see `docks-kit models claude`)",
|
|
81
|
-
),
|
|
82
|
-
Flag.optional,
|
|
83
|
-
);
|
|
84
|
-
const claudeEffort = Flag.String("claude-effort").pipe(
|
|
85
|
-
Flag.withDescription(
|
|
86
|
-
"Deploy-time modifier: set Claude effortLevel (bare flag shows valid levels)",
|
|
87
|
-
),
|
|
88
|
-
Flag.optional,
|
|
89
|
-
);
|
|
90
|
-
const claudeAdvisor = Flag.String("claude-advisor").pipe(
|
|
91
|
-
Flag.withDescription("Deploy-time modifier: set Claude advisor on/off/default"),
|
|
92
|
-
Flag.optional,
|
|
93
|
-
);
|
|
94
|
-
const claudeCompactWindow = Flag.String("claude-compact-window").pipe(
|
|
95
|
-
Flag.withDescription(
|
|
96
|
-
"Deploy-time modifier: set deployed autocompact window in tokens (e.g. 680000 or 680k)",
|
|
97
|
-
),
|
|
98
|
-
Flag.optional,
|
|
99
|
-
);
|
|
100
|
-
const claudePermissive = Flag.Boolean("claude-permissive").pipe(
|
|
101
|
-
Flag.withDescription(
|
|
102
|
-
"Deploy-time modifier: empty permissions.ask/deny in deployed settings (sandboxes)",
|
|
103
|
-
),
|
|
104
|
-
Flag.withDefault(false),
|
|
105
|
-
);
|
|
106
|
-
const claudePlugin = Flag.String("claude-plugin").pipe(
|
|
107
|
-
Flag.withDescription(
|
|
108
|
-
"Sticky opt-in plugin(s); repeatable and/or comma-separated (known: supabase, n8n)",
|
|
109
|
-
),
|
|
110
|
-
Flag.atLeast(0),
|
|
111
|
-
);
|
|
112
|
-
const codexModel = Flag.String("codex-model").pipe(
|
|
113
|
-
Flag.withDescription(
|
|
114
|
-
"Deploy-time modifier: set deployed Codex model (see `docks-kit models codex`)",
|
|
115
|
-
),
|
|
116
|
-
Flag.optional,
|
|
117
|
-
);
|
|
118
|
-
const codexEffort = Flag.String("codex-effort").pipe(
|
|
119
|
-
Flag.withDescription(
|
|
120
|
-
"Deploy-time modifier: set Codex model_reasoning_effort (bare flag shows valid levels)",
|
|
121
|
-
),
|
|
122
|
-
Flag.optional,
|
|
123
|
-
);
|
|
124
64
|
|
|
125
65
|
export const syncCommand = Command.make(
|
|
126
66
|
"sync",
|
|
127
67
|
{
|
|
128
68
|
targets,
|
|
129
69
|
dryRun,
|
|
130
|
-
reconcile,
|
|
131
70
|
prune,
|
|
132
|
-
skipBubblewrap,
|
|
133
71
|
skipPluginRefresh,
|
|
134
72
|
verbose,
|
|
135
|
-
claudeModel,
|
|
136
|
-
claudeEffort,
|
|
137
|
-
claudeAdvisor,
|
|
138
|
-
claudeCompactWindow,
|
|
139
|
-
claudePermissive,
|
|
140
|
-
claudePlugin,
|
|
141
|
-
codexModel,
|
|
142
|
-
codexEffort,
|
|
143
73
|
},
|
|
144
74
|
(config) =>
|
|
145
75
|
Effect.gen(function* () {
|
|
@@ -152,29 +82,9 @@ export const syncCommand = Command.make(
|
|
|
152
82
|
|
|
153
83
|
const args: Array<string> = ["sync", ...config.targets];
|
|
154
84
|
if (config.dryRun) args.push("--dry-run");
|
|
155
|
-
if (config.reconcile) args.push("--reconcile");
|
|
156
85
|
if (config.prune) args.push("--prune");
|
|
157
|
-
if (config.skipBubblewrap) args.push("--skip-bubblewrap");
|
|
158
86
|
if (config.skipPluginRefresh) args.push("--skip-plugin-refresh");
|
|
159
87
|
if (config.verbose) args.push("--verbose");
|
|
160
|
-
if (config.claudePermissive) args.push("--claude-permissive");
|
|
161
|
-
Option.map(config.claudeModel, (m) => args.push(`--claude-model=${m}`));
|
|
162
|
-
Option.map(config.claudeEffort, (level) => args.push(`--claude-effort=${level}`));
|
|
163
|
-
Option.map(config.claudeAdvisor, (state) => args.push(`--claude-advisor=${state}`));
|
|
164
|
-
Option.map(config.claudeCompactWindow, (w) => args.push(`--claude-compact-window=${w}`));
|
|
165
|
-
Option.map(config.codexModel, (m) => args.push(`--codex-model=${m}`));
|
|
166
|
-
Option.map(config.codexEffort, (level) => args.push(`--codex-effort=${level}`));
|
|
167
|
-
for (const occurrence of config.claudePlugin) {
|
|
168
|
-
const names = occurrence
|
|
169
|
-
.split(",")
|
|
170
|
-
.map((p) => p.trim())
|
|
171
|
-
.filter((p) => p.length > 0);
|
|
172
|
-
if (names.length === 0) {
|
|
173
|
-
args.push("--claude-plugin=");
|
|
174
|
-
continue;
|
|
175
|
-
}
|
|
176
|
-
for (const name of names) args.push(`--claude-plugin=${name}`);
|
|
177
|
-
}
|
|
178
88
|
|
|
179
89
|
// Not on --dry-run: the nudge's git fetch writes FETCH_HEAD/remote
|
|
180
90
|
// refs, and a preview command must not mutate the checkout.
|
|
@@ -184,8 +94,4 @@ export const syncCommand = Command.make(
|
|
|
184
94
|
}
|
|
185
95
|
yield* engine(args);
|
|
186
96
|
}),
|
|
187
|
-
).pipe(
|
|
188
|
-
Command.withDescription(
|
|
189
|
-
"Deploy the SoT to this machine with EngineNative. Deploy-time modifiers touch deployed config only; a later flag-less sync reverts them to SoT.",
|
|
190
|
-
),
|
|
191
|
-
);
|
|
97
|
+
).pipe(Command.withDescription("Deploy the SoT to this machine with EngineNative."));
|
|
@@ -5,7 +5,7 @@ import { bail, engine } from "../engine";
|
|
|
5
5
|
const MANAGED = ["bun"];
|
|
6
6
|
|
|
7
7
|
const op = Argument.String("op").pipe(
|
|
8
|
-
Argument.withDescription("check (default) | ensure <tool> | outdated
|
|
8
|
+
Argument.withDescription("check (default) | ensure <tool> | outdated"),
|
|
9
9
|
Argument.optional,
|
|
10
10
|
);
|
|
11
11
|
const tool = Argument.String("tool").pipe(
|
|
@@ -22,7 +22,7 @@ const refresh = Flag.Boolean("refresh").pipe(
|
|
|
22
22
|
Flag.withDefault(false),
|
|
23
23
|
);
|
|
24
24
|
const dryRun = Flag.Boolean("dry-run").pipe(
|
|
25
|
-
Flag.withDescription("ensure
|
|
25
|
+
Flag.withDescription("ensure: preview without installing"),
|
|
26
26
|
Flag.withDefault(false),
|
|
27
27
|
);
|
|
28
28
|
|
|
@@ -59,22 +59,14 @@ export const toolchainCommand = Command.make(
|
|
|
59
59
|
...words,
|
|
60
60
|
...(config.refresh ? ["--refresh"] : []),
|
|
61
61
|
]);
|
|
62
|
-
case "upgrade":
|
|
63
|
-
return yield* engine([
|
|
64
|
-
"toolchain",
|
|
65
|
-
"upgrade",
|
|
66
|
-
...words,
|
|
67
|
-
...flags,
|
|
68
|
-
...(config.dryRun ? ["--dry-run"] : []),
|
|
69
|
-
]);
|
|
70
62
|
default:
|
|
71
63
|
return yield* bail(
|
|
72
|
-
`Unknown toolchain op '${operation}' (valid: check, ensure, outdated
|
|
64
|
+
`Unknown toolchain op '${operation}' (valid: check, ensure, outdated)`,
|
|
73
65
|
);
|
|
74
66
|
}
|
|
75
67
|
}),
|
|
76
68
|
).pipe(
|
|
77
69
|
Command.withDescription(
|
|
78
|
-
"Verified-version floors for external tools (SoT/toolchain.json): check prints the doctor table; ensure installs one managed tool when it is missing; outdated compares verified pins with the newest upstream release (network, report only)
|
|
70
|
+
"Verified-version floors for external tools (SoT/toolchain.json): check prints the doctor table; ensure installs one managed tool when it is missing; outdated compares verified pins with the newest upstream release (network, report only).",
|
|
79
71
|
),
|
|
80
72
|
);
|
|
@@ -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(
|