docks-kit 0.22.12 → 0.22.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/AGENTS.md +95 -81
  2. package/README.md +7 -7
  3. package/cli/docs/command-guards.md +7 -3
  4. package/cli/docs/flags.md +59 -9
  5. package/cli/docs/install.md +2 -2
  6. package/cli/docs/omp-context.md +14 -8
  7. package/cli/docs/omp-models.md +1 -1
  8. package/cli/docs/overview.md +1 -1
  9. package/cli/docs/platforms.md +4 -2
  10. package/cli/docs/plugins.md +8 -5
  11. package/cli/docs/sync-layers.md +29 -15
  12. package/cli/docs/toolchain.md +24 -14
  13. package/cli/src/argv.ts +7 -4
  14. package/cli/src/argvValidate.ts +2 -16
  15. package/cli/src/commands/docs.ts +1 -1
  16. package/cli/src/commands/omp.ts +56 -15
  17. package/cli/src/commands/sync.ts +6 -6
  18. package/cli/src/commands/tidy.ts +83 -26
  19. package/cli/src/engine-native/DESIGN.md +93 -56
  20. package/cli/src/engine-native/atomicWrite.ts +168 -8
  21. package/cli/src/engine-native/codexConfig.ts +2 -6
  22. package/cli/src/engine-native/codexPlugins.ts +1 -1
  23. package/cli/src/engine-native/codexSync.ts +137 -26
  24. package/cli/src/engine-native/codexToml.ts +4 -86
  25. package/cli/src/engine-native/deps.ts +51 -51
  26. package/cli/src/engine-native/exec.ts +3 -0
  27. package/cli/src/engine-native/index.ts +1 -1
  28. package/cli/src/engine-native/kitLock.ts +121 -0
  29. package/cli/src/engine-native/modes.ts +49 -31
  30. package/cli/src/engine-native/ompChild.ts +26 -0
  31. package/cli/src/engine-native/ompFastMode.ts +14 -7
  32. package/cli/src/engine-native/ompFileDeploy.ts +12 -6
  33. package/cli/src/engine-native/ompMarketplace.ts +25 -18
  34. package/cli/src/engine-native/ompPlugins.ts +39 -18
  35. package/cli/src/engine-native/ompRemovals.ts +51 -23
  36. package/cli/src/engine-native/ompSync.ts +78 -38
  37. package/cli/src/engine-native/os/targets.ts +16 -4
  38. package/cli/src/engine-native/os/types.ts +1 -1
  39. package/cli/src/engine-native/parseArgs.ts +27 -17
  40. package/cli/src/engine-native/processes.ts +16 -0
  41. package/cli/src/engine-native/scratch.ts +18 -0
  42. package/cli/src/engine-native/skillsInstall.ts +27 -2
  43. package/cli/src/engine-native/skillsPrune.ts +51 -49
  44. package/cli/src/engine-native/skillsRecords.ts +138 -0
  45. package/cli/src/engine-native/skillsSync.ts +16 -13
  46. package/cli/src/engine-native/syncDispatch.ts +186 -4
  47. package/cli/src/engine-native/tidy.ts +102 -119
  48. package/cli/src/engine-native/tomlLines.ts +92 -0
  49. package/cli/src/generated/sotPayload.ts +5 -5
  50. package/cli/src/main.ts +5 -30
  51. package/cli/src/manifests.ts +24 -4
  52. package/package.json +2 -2
  53. package/cli/src/engine-native/tidyLock.ts +0 -163
@@ -3,7 +3,8 @@
3
3
  * avoid a TOML library because reformatting user configs would be a behavior
4
4
  * change. Guard order, message strings, and backup behavior are golden-tested.
5
5
  */
6
- import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
6
+ import { createHash } from "node:crypto";
7
+ import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
7
8
 
8
9
  import { resolveEffort } from "../efforts";
9
10
  import {
@@ -13,6 +14,7 @@ import {
13
14
  payloadText,
14
15
  type PayloadPath,
15
16
  } from "../payload";
17
+ import { replaceFile, replaceTextIfChanged } from "./atomicWrite";
16
18
  import { syncConfig } from "./codexConfig";
17
19
  import { removeRetiredImportedHooks } from "./codexHooks";
18
20
  import { codexHome } from "./codexPaths";
@@ -61,7 +63,12 @@ export async function codexSync(ctx: Ctx): Promise<void> {
61
63
  removeRetiredImportedHooks(ctx, codexDir);
62
64
  syncCodexModel(ctx, ctx.codexModel, deployedBefore);
63
65
  syncCodexEffort(ctx, ctx.codexEffort, deployedBefore);
64
- syncRules(ctx, payloadPaths("SoT/.codex/rules/"), p(codexDir, "rules"));
66
+ syncRules(
67
+ ctx,
68
+ payloadPaths("SoT/.codex/rules/"),
69
+ p(codexDir, "rules"),
70
+ p(codexDir, ".kit-managed-rules"),
71
+ );
65
72
  syncAgentsMd(ctx, payloadText("SoT/.codex/AGENTS.md"), p(codexDir, "AGENTS.md"));
66
73
  const unresolvedMarketplace = syncMarketplace(
67
74
  ctx,
@@ -151,36 +158,140 @@ function bwrapDetectPmInstallCmd(ctx: Ctx): string {
151
158
 
152
159
  // ------------------------------------------------------- rules + agents ----
153
160
 
154
- function syncRules(ctx: Ctx, sotRules: ReadonlyArray<PayloadPath>, userRulesDir: string): void {
155
- const { change, echo, verbose } = ctx.services.logger;
156
- const firstRule = sotRules[0];
157
- if (firstRule === undefined) return;
158
- const firstDisplay = payloadDisplayPath(firstRule);
159
- const sotRulesDir = firstDisplay.slice(0, firstDisplay.lastIndexOf("/"));
161
+ /** One `<sha256> <file name>` line of the rules manifest, the `sha256sum` format. */
162
+ const RULES_RECORD = /^([0-9a-f]{64}) {2}([^/\\]+\.rules)$/;
160
163
 
161
- if (ctx.dryRun) {
162
- echo(`[dry-run] cp ${sotRulesDir}/*.rules -> ${userRulesDir}/`);
163
- return;
164
+ function sha256Hex(bytes: Uint8Array): string {
165
+ return createHash("sha256").update(bytes).digest("hex");
166
+ }
167
+
168
+ /**
169
+ * The rules files that syncs wrote: file name to the sha256 hashes of the kit
170
+ * bytes recorded for it, in manifest order. A sync that stopped after its
171
+ * write-ahead can leave two lines, so two hashes, for one name.
172
+ */
173
+ function readRulesRecords(manifestFile: string): Map<string, Set<string>> {
174
+ const records = new Map<string, Set<string>>();
175
+ if (!existsSync(manifestFile)) return records;
176
+ for (const line of readFileSync(manifestFile, "utf8").split("\n")) {
177
+ const record = RULES_RECORD.exec(line);
178
+ if (record === null) continue;
179
+ const name = record[2]!;
180
+ const hashes = records.get(name) ?? new Set<string>();
181
+ hashes.add(record[1]!);
182
+ records.set(name, hashes);
164
183
  }
184
+ return records;
185
+ }
186
+
187
+ /**
188
+ * Replaces the manifest with one `<sha256> <name>` line per recorded hash,
189
+ * sorted by name. A name keeps the order of its hashes. Writes no manifest
190
+ * when there is no record and no manifest.
191
+ */
192
+ function writeRulesManifest(
193
+ manifestFile: string,
194
+ records: ReadonlyMap<string, ReadonlySet<string>>,
195
+ ): void {
196
+ const manifest = [...records]
197
+ .sort(([left], [right]) => compareCodepoints(left, right))
198
+ .flatMap(([name, hashes]) => [...hashes].map((hash) => `${hash} ${name}\n`))
199
+ .join("");
200
+ if (manifest !== "" || existsSync(manifestFile)) replaceTextIfChanged(manifestFile, manifest);
201
+ }
165
202
 
166
- mkdirSync(userRulesDir, { recursive: true });
167
- let sawRules = false;
168
- let rulesChanged = false;
203
+ /**
204
+ * Deploys the SoT rules files and records each one in `manifestFile`. Codex
205
+ * applies every `*.rules` file in `rules/`, so a file that the SoT dropped
206
+ * keeps its old rules active. Each sync therefore removes a recorded file
207
+ * that the SoT no longer ships while its bytes have one of the hashes recorded
208
+ * for its name. An edited file stays, keeps its records, and gets a warning on
209
+ * each sync. Sync deploys each name that the SoT ships over an existing file,
210
+ * recorded or not. It backs up a file that differs to `<name>.bak`. It then
211
+ * replaces it through a temporary file and a rename, so an interrupted write
212
+ * keeps the previous file. Codex does not load the `*.tmp` file. Cleanup
213
+ * never reads or removes a file that the SoT does not ship and no sync
214
+ * recorded, such as the `default.rules` file of Codex.
215
+ *
216
+ * Record ahead: before the deploy, sync writes the manifest with the recorded
217
+ * hashes of each name plus the kit hash of each shipped name. So a sync that
218
+ * stops after a deploy leaves a record of the bytes it wrote. A name whose kit
219
+ * bytes change then has two lines. Every recorded hash is a hash of kit
220
+ * bytes, so no record lets cleanup remove bytes that the user wrote. After the
221
+ * deploy, sync writes one line per shipped name, and a kept name keeps its
222
+ * hashes. Both writes go through a temporary file and a rename, so an
223
+ * interrupted write keeps the previous manifest.
224
+ */
225
+ export function syncRules(
226
+ ctx: Ctx,
227
+ sotRules: ReadonlyArray<PayloadPath>,
228
+ userRulesDir: string,
229
+ manifestFile: string,
230
+ ): void {
231
+ const { change, echo, verbose, warn } = ctx.services.logger;
169
232
  const ruleFiles = sotRules.filter((path) => path.endsWith(".rules")).sort(compareCodepoints);
170
- for (const ruleFile of ruleFiles) {
171
- sawRules = true;
172
- const userRuleFile = p(userRulesDir, ruleFile.slice(ruleFile.lastIndexOf("/") + 1));
173
- const content = payloadBytes(ruleFile);
174
- const identical = existsSync(userRuleFile) && readFileSync(userRuleFile).equals(content);
175
- if (identical) continue;
176
- if (existsSync(userRuleFile)) copyFileSync(userRuleFile, `${userRuleFile}.bak`);
177
- writeFileSync(userRuleFile, content);
178
- rulesChanged = true;
233
+ const fileName = (path: string): string => path.slice(path.lastIndexOf("/") + 1);
234
+ const shippedNames = new Set(ruleFiles.map(fileName));
235
+ const recorded = readRulesRecords(manifestFile);
236
+ const nextRecords = new Map<string, ReadonlySet<string>>();
237
+ const firstRule = sotRules[0];
238
+
239
+ if (ctx.dryRun) {
240
+ if (firstRule !== undefined) {
241
+ const firstDisplay = payloadDisplayPath(firstRule);
242
+ const sotRulesDir = firstDisplay.slice(0, firstDisplay.lastIndexOf("/"));
243
+ echo(`[dry-run] cp ${sotRulesDir}/*.rules -> ${userRulesDir}/`);
244
+ }
245
+ } else if (firstRule !== undefined) {
246
+ mkdirSync(userRulesDir, { recursive: true });
247
+ const deploys = ruleFiles.map((ruleFile) => {
248
+ const content = payloadBytes(ruleFile);
249
+ return { name: fileName(ruleFile), content, hash: sha256Hex(content) };
250
+ });
251
+ const ahead = new Map(recorded);
252
+ for (const { name, hash } of deploys) {
253
+ ahead.set(name, new Set([...(recorded.get(name) ?? []), hash]));
254
+ nextRecords.set(name, new Set([hash]));
255
+ }
256
+ writeRulesManifest(manifestFile, ahead);
257
+
258
+ let rulesChanged = false;
259
+ for (const { name, content } of deploys) {
260
+ const userRuleFile = p(userRulesDir, name);
261
+ const identical = existsSync(userRuleFile) && readFileSync(userRuleFile).equals(content);
262
+ if (identical) continue;
263
+ if (existsSync(userRuleFile)) copyFileSync(userRuleFile, `${userRuleFile}.bak`);
264
+ replaceFile(userRuleFile, content);
265
+ rulesChanged = true;
266
+ }
267
+ if (rulesChanged) {
268
+ change("Codex rules synced");
269
+ ctx.nextStepTriggers.codexRestart = true;
270
+ } else if (ruleFiles.length > 0) verbose("Codex rules already in sync");
179
271
  }
180
- if (rulesChanged) {
181
- change("Codex rules synced");
272
+
273
+ for (const [name, recordedHashes] of recorded) {
274
+ if (shippedNames.has(name)) continue;
275
+ const file = p(userRulesDir, name);
276
+ if (!existsSync(file)) continue;
277
+ if (!recordedHashes.has(sha256Hex(readFileSync(file)))) {
278
+ warn(
279
+ `Codex rules: kept ${file}: the SoT no longer ships it, and it differs from the kit copy. Review it and delete it if you do not need its rules.`,
280
+ );
281
+ nextRecords.set(name, recordedHashes);
282
+ continue;
283
+ }
284
+ if (ctx.dryRun) {
285
+ echo(`[dry-run] remove ${file}`);
286
+ continue;
287
+ }
288
+ rmSync(file, { force: true });
289
+ change(`Codex rules: removed ${file}; the SoT no longer ships it`);
182
290
  ctx.nextStepTriggers.codexRestart = true;
183
- } else if (sawRules) verbose("Codex rules already in sync");
291
+ }
292
+ if (ctx.dryRun) return;
293
+
294
+ writeRulesManifest(manifestFile, nextRecords);
184
295
  }
185
296
 
186
297
  function syncAgentsMd(ctx: Ctx, sotAgentsMdText: string, userAgentsMd: string): void {
@@ -13,92 +13,7 @@ import { replaceFile } from "./atomicWrite";
13
13
  import { codexHome } from "./codexPaths";
14
14
  import type { Ctx } from "./index";
15
15
  import type { SettingEdit } from "./sharedTypes";
16
-
17
- export function isTomlHeaderLine(line: string): boolean {
18
- return /^[ \t]*\[/.test(line);
19
- }
20
-
21
- /** Offset just past the quoted string that starts at `start`, or the line end when it stays open. */
22
- function skipQuoted(line: string, start: number): number {
23
- const quote = line[start];
24
- let offset = start + 1;
25
- while (offset < line.length) {
26
- if (quote === '"' && line[offset] === "\\") {
27
- offset += 2;
28
- continue;
29
- }
30
- if (line[offset] === quote) return offset + 1;
31
- offset++;
32
- }
33
- return offset;
34
- }
35
-
36
- /** Offset of the `=` that ends the key on a key line, or undefined for other lines. */
37
- function keyValueSeparator(line: string): number | undefined {
38
- if (/^[ \t]*($|#|\[)/.test(line)) return undefined;
39
- let offset = 0;
40
- while (offset < line.length) {
41
- const char = line[offset]!;
42
- if (char === "=") return offset;
43
- offset = char === '"' || char === "'" ? skipQuoted(line, offset) : offset + 1;
44
- }
45
- return undefined;
46
- }
47
-
48
- /**
49
- * Mark each line that continues a value opened on an earlier line: the body of
50
- * a `"""` or `'''` string, or the rest of an array or inline table that spans
51
- * lines. A marked line is never a table header or a key line.
52
- */
53
- export function tomlContinuationLines(lines: ReadonlyArray<string>): Array<boolean> {
54
- const continuation: Array<boolean> = [];
55
- let openString: string | undefined;
56
- let depth = 0;
57
- const scanValue = (line: string, start: number): void => {
58
- let offset = start;
59
- while (offset < line.length) {
60
- if (openString !== undefined) {
61
- if (openString === '"""' && line[offset] === "\\") {
62
- offset += 2;
63
- } else if (line.startsWith(openString, offset)) {
64
- // A closing delimiter can carry up to two extra quotes of string content.
65
- let end = offset + 3;
66
- while (end < offset + 5 && line[end] === openString[0]) end++;
67
- offset = end;
68
- openString = undefined;
69
- } else {
70
- offset++;
71
- }
72
- continue;
73
- }
74
- const char = line[offset]!;
75
- if (char === "#") return;
76
- if (line.startsWith('"""', offset) || line.startsWith("'''", offset)) {
77
- openString = line.slice(offset, offset + 3);
78
- offset += 3;
79
- continue;
80
- }
81
- if (char === '"' || char === "'") {
82
- offset = skipQuoted(line, offset);
83
- continue;
84
- }
85
- if (char === "[" || char === "{") depth++;
86
- else if ((char === "]" || char === "}") && depth > 0) depth--;
87
- offset++;
88
- }
89
- };
90
- for (const line of lines) {
91
- if (openString !== undefined || depth > 0) {
92
- continuation.push(true);
93
- scanValue(line, 0);
94
- continue;
95
- }
96
- continuation.push(false);
97
- const separator = keyValueSeparator(line);
98
- if (separator !== undefined) scanValue(line, separator + 1);
99
- }
100
- return continuation;
101
- }
16
+ import { isTomlHeaderLine, tomlContinuationLines } from "./tomlLines";
102
17
 
103
18
  export function replaceTopLevelSetting(content: string, key: string, replacement: string): string {
104
19
  // A leading BOM would hide the first key or header from the line patterns.
@@ -375,6 +290,9 @@ function mergeTableSettingsText(sotConfigText: string, userConfigText: string):
375
290
  else trailingComments = [];
376
291
  }
377
292
  if (skip) keepTrailingComments();
293
+ // The blank lines before a removed last block would otherwise stay in
294
+ // `kept`, and each sync would add one more blank line before the table.
295
+ while (kept.length > 0 && /^[ \t]*$/.test(kept[kept.length - 1]!)) kept.pop();
378
296
  merged = `${kept.join("\n")}\n\n${tableBlock}\n`;
379
297
  }
380
298
  return merged;
@@ -4,8 +4,8 @@
4
4
  *
5
5
  * Ownership split: SoT/toolchain.json + toolchain.ts keep version floors, pin
6
6
  * policy, and the doctor report, while bun.ts bunBootstrap owns the one managed
7
- * install; this registry owns WHICH external tools exist, whether they are
8
- * required, and the one-line command that installs a missing one.
7
+ * install; this registry owns WHICH external tools exist and the one-line
8
+ * command that installs a missing one.
9
9
  */
10
10
  import { isAbsolute } from "node:path";
11
11
 
@@ -13,6 +13,8 @@ import { capture, captureWithin, commandExists, p, which, type CaptureOutcome }
13
13
  import { engineHome } from "./harnesses";
14
14
  import { isObject, parseJson } from "./jq";
15
15
  import { hostOs, platformName, rawPlatform } from "./os";
16
+ import type { Invocation } from "./os/types";
17
+ import { field } from "./toolchain";
16
18
 
17
19
  export type ToolId =
18
20
  | "git"
@@ -37,9 +39,6 @@ export type ToolId =
37
39
  | "pacman"
38
40
  | "zypper";
39
41
 
40
- /** required = the engine aborts when missing; optional = warn + degrade. */
41
- export type Requirement = "required" | "optional";
42
-
43
42
  export type ProbeResult =
44
43
  | { readonly state: "present"; readonly path?: string }
45
44
  | { readonly state: "missing" };
@@ -69,7 +68,6 @@ export const VERSION_PROBE_LIMIT_MS = 60_000;
69
68
 
70
69
  export interface DependencySpec {
71
70
  readonly id: ToolId;
72
- readonly requirement: Requirement;
73
71
  readonly versionArgs: ReadonlyArray<string>;
74
72
  /** Platform-correct one-line install command (param injectable for tests). */
75
73
  readonly installHint: (platform?: NodeJS.Platform) => string;
@@ -89,18 +87,43 @@ interface SpecOptions {
89
87
 
90
88
  const spec = (
91
89
  id: ToolId,
92
- requirement: Requirement,
93
90
  installHint: (platform?: NodeJS.Platform) => string,
94
91
  options: SpecOptions = {},
95
92
  ): DependencySpec => ({
96
93
  id,
97
- requirement,
98
94
  versionArgs: options.versionArgs ?? ["--version"],
99
95
  installHint,
100
96
  resolve: options.resolve,
101
97
  version: options.version,
102
98
  });
103
99
 
100
+ /** One shell word. Double quotes keep a `$tmp` or `$env:TEMP` reference live in sh and PowerShell. */
101
+ function shellWord(word: string): string {
102
+ return /^[\w./:=@+-]+$/.test(word) ? word : `"${word}"`;
103
+ }
104
+
105
+ function commandLine({ command, args }: Invocation): string {
106
+ return [command, ...args].map(shellWord).join(" ");
107
+ }
108
+
109
+ /**
110
+ * The pinned installer that `bun.ts runBunBootstrap` runs, as one
111
+ * download-then-run command line. The script is saved before it runs, so a
112
+ * truncated download never runs as a partial script.
113
+ */
114
+ function bunInstallHint(pf: NodeJS.Platform = rawPlatform()): string {
115
+ const host = hostOs(platformName(pf));
116
+ const pin = field("bun", "verified");
117
+ if (host.id === "windows") {
118
+ const { download, run } = host.bunInstaller(pin, "$env:TEMP");
119
+ // Windows PowerShell 5.1 resolves a bare `curl` to its Invoke-WebRequest alias.
120
+ const downloadLine = commandLine({ ...download, command: `${download.command}.exe` });
121
+ return `${downloadLine}; if ($LASTEXITCODE -eq 0) { ${commandLine(run)} }`;
122
+ }
123
+ const { download, run } = host.bunInstaller(pin, "$tmp");
124
+ return `tmp=$(mktemp -d) && ${commandLine(download)} && ${commandLine(run)}`;
125
+ }
126
+
104
127
  // Presence is the injected executor's verdict; `which` only resolves WHERE the
105
128
  // tool is, which on Windows is the `.cmd`/`.exe` candidate rather than the name.
106
129
  const pathProbe =
@@ -169,35 +192,22 @@ const versionNpmGlobal =
169
192
  export const defaultProbeExecutor: ProbeExecutor = { commandExists, capture, captureWithin, which };
170
193
 
171
194
  export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
172
- git: spec("git", "optional", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("git")),
173
- jq: spec("jq", "optional", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("jq")),
174
- curl: spec("curl", "optional", (pf = rawPlatform()) =>
175
- hostOs(platformName(pf)).installHint("curl"),
176
- ),
177
- node: spec(
178
- "node",
179
- "optional",
180
- () => "install Node.js via https://nodejs.org (or your package manager)",
181
- ),
195
+ git: spec("git", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("git")),
196
+ jq: spec("jq", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("jq")),
197
+ 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)"),
182
199
  npm: spec(
183
200
  "npm",
184
- "optional",
185
201
  () => "ships with Node.js — install via https://nodejs.org (or your package manager)",
186
202
  ),
187
203
  npx: spec(
188
204
  "npx",
189
- "optional",
190
205
  () => "ships with Node.js — install via https://nodejs.org (or your package manager)",
191
206
  ),
192
- claude: spec("claude", "optional", (pf = rawPlatform()) =>
193
- hostOs(platformName(pf)).installHint("claude"),
194
- ),
195
- codex: spec("codex", "optional", (pf = rawPlatform()) =>
196
- hostOs(platformName(pf)).installHint("codex"),
197
- ),
207
+ claude: spec("claude", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("claude")),
208
+ codex: spec("codex", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("codex")),
198
209
  omp: spec(
199
210
  "omp",
200
- "optional",
201
211
  () =>
202
212
  "install omp from https://github.com/can1357/oh-my-pi (an existing install updates with `omp update`, or through the tool that manages it, such as Tern)",
203
213
  {
@@ -205,7 +215,7 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
205
215
  (await exec.capture("omp", ["--version"])).trim().replace(/^omp[/v]/, ""),
206
216
  },
207
217
  ),
208
- bun: spec("bun", "optional", () => "curl -fsSL https://bun.sh/install | bash", {
218
+ bun: spec("bun", bunInstallHint, {
209
219
  resolve: resolveBun,
210
220
  version: async (exec) => {
211
221
  const bun = findBun(exec);
@@ -213,43 +223,33 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
213
223
  return await exec.capture(bun.command, ["--version"]);
214
224
  },
215
225
  }),
216
- bwrap: spec(
217
- "bwrap",
218
- "optional",
219
- () => "sudo apt install -y bubblewrap (or dnf/pacman/zypper equivalent)",
220
- ),
221
- ffplay: spec(
222
- "ffplay",
223
- "optional",
224
- (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("ffplay"),
225
- {
226
- versionArgs: ["-version"],
227
- resolve: pathProbe("ffplay"),
228
- },
229
- ),
230
- intelephense: spec("intelephense", "optional", () => "npm install -g intelephense", {
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", {
231
232
  resolve: pathProbe("intelephense"),
232
233
  version: versionNpmGlobal("intelephense"),
233
234
  }),
234
235
  "typescript-language-server": spec(
235
236
  "typescript-language-server",
236
- "optional",
237
237
  () => "npm install -g typescript-language-server typescript",
238
238
  {
239
239
  resolve: pathProbe("typescript-language-server"),
240
240
  },
241
241
  ),
242
- tsc: spec("tsc", "optional", () => "npm install -g typescript", {
242
+ tsc: spec("tsc", () => "npm install -g typescript", {
243
243
  resolve: pathProbe("tsc"),
244
244
  }),
245
- "rust-analyzer": spec("rust-analyzer", "optional", () => "rustup component add rust-analyzer", {
245
+ "rust-analyzer": spec("rust-analyzer", () => "rustup component add rust-analyzer", {
246
246
  resolve: pathProbe("rust-analyzer"),
247
247
  }),
248
- rustup: spec("rustup", "optional", () => "install the Rust toolchain from https://rustup.rs"),
249
- "apt-get": spec("apt-get", "optional", () => "install apt via your Linux distribution"),
250
- dnf: spec("dnf", "optional", () => "install dnf via your Linux distribution"),
251
- pacman: spec("pacman", "optional", () => "install pacman via your Linux distribution"),
252
- zypper: spec("zypper", "optional", () => "install zypper via your Linux distribution"),
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
253
  };
254
254
 
255
255
  export function resolveDependency(
@@ -95,6 +95,8 @@ export interface AsyncProcessOptions {
95
95
  readonly stdio?: SpawnOptions["stdio"];
96
96
  /** Working directory for the child; the parent's when absent. */
97
97
  readonly cwd?: string;
98
+ /** Environment of the child; the parent's when absent. */
99
+ readonly env?: NodeJS.ProcessEnv;
98
100
  /** Host whose executable resolution and argv shaping apply; tests inject it. */
99
101
  readonly host?: HostOs;
100
102
  /**
@@ -133,6 +135,7 @@ export function spawnProcess(
133
135
  child = spawn(invocation.command, [...invocation.args], {
134
136
  stdio: options.stdio ?? ["ignore", "pipe", "ignore"],
135
137
  ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
138
+ ...(options.env !== undefined ? { env: options.env } : {}),
136
139
  // A bounded child leads its own process group on POSIX, so a timeout
137
140
  // can end the processes that it started too (see killProcessTree).
138
141
  ...(options.timeoutMs !== undefined && !WINDOWS_PROCESS ? { detached: true } : {}),
@@ -2,7 +2,7 @@
2
2
  * EngineNative — the supported sync/model/toolchain engine.
3
3
  *
4
4
  * Golden suites drive it through main.ts's harness-private `native-raw`
5
- * channel, which bypasses @effect/cli so tests see the internal argv
5
+ * channel, which bypasses effect/cli so tests see the internal argv
6
6
  * vocabulary directly.
7
7
  *
8
8
  * Split: run context lives in `engineCtx.ts`, scheduling in
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Kit locks: an SQLite `BEGIN IMMEDIATE` transaction on a dedicated database
3
+ * file. Only `node:` imports, so that a test child process can load this
4
+ * module alone.
5
+ *
6
+ * - The lock is the RESERVED lock of the transaction. At most one connection,
7
+ * in any process, holds it.
8
+ * - `BEGIN IMMEDIATE` takes RESERVED with no wait for other readers. With
9
+ * `BEGIN EXCLUSIVE`, two racers that each hold SHARED can both fail.
10
+ * - The OS releases the lock when the holder process ends for any reason. A
11
+ * paused holder keeps it.
12
+ * - The database stays in rollback journal mode. Never set WAL on a lock file.
13
+ * - A module-level set keeps each open connection, so that the garbage
14
+ * collector cannot close a lock that a caller dropped.
15
+ * - Only this module opens a lock file. Each run takes each lock once.
16
+ */
17
+ import { chmodSync, mkdirSync } from "node:fs";
18
+ import { dirname } from "node:path";
19
+ import { DatabaseSync } from "node:sqlite";
20
+ import { setTimeout as sleepMs } from "node:timers/promises";
21
+
22
+ /** The default time between two tries. */
23
+ const POLL_MS = 50;
24
+ /** SQLite primary result code SQLITE_BUSY: another connection holds a conflicting lock. */
25
+ const SQLITE_BUSY = 5;
26
+
27
+ export interface KitLockOptions {
28
+ /** Try until `now()` passes the start plus `waitMs`. 0 tries once, with no sleep. */
29
+ readonly waitMs: number;
30
+ /** The time between two tries. */
31
+ readonly pollMs?: number;
32
+ /** The clock in ms; `Date.now` by default. */
33
+ readonly now?: () => number;
34
+ /** The wait between two tries. */
35
+ readonly sleep?: (ms: number) => Promise<void>;
36
+ /**
37
+ * True by default: make the lock directory and set its mode to 0700. False
38
+ * for a lock in a folder that the caller made, so the folder keeps its mode.
39
+ */
40
+ readonly privateDirectory?: boolean;
41
+ }
42
+
43
+ /** A held lock. Give it to `releaseKitLock` exactly once. */
44
+ export interface KitLock {
45
+ readonly path: string;
46
+ readonly connection: DatabaseSync;
47
+ }
48
+
49
+ export type KitLockResult =
50
+ | { readonly kind: "acquired"; readonly lock: KitLock }
51
+ | { readonly kind: "held" };
52
+
53
+ /** The connection of each held lock. The garbage collector cannot close a connection in this set. */
54
+ const heldConnections = new Set<DatabaseSync>();
55
+
56
+ /** True for an SQLite error with the primary result code SQLITE_BUSY. */
57
+ function isBusy(cause: unknown): boolean {
58
+ if (typeof cause !== "object" || cause === null || !("errcode" in cause)) return false;
59
+ return typeof cause.errcode === "number" && (cause.errcode & 0xff) === SQLITE_BUSY;
60
+ }
61
+
62
+ /** Start the write transaction. False when another connection holds the lock. */
63
+ function tryBegin(connection: DatabaseSync): boolean {
64
+ try {
65
+ connection.exec("BEGIN IMMEDIATE");
66
+ return true;
67
+ } catch (cause) {
68
+ if (isBusy(cause)) return false;
69
+ throw cause;
70
+ }
71
+ }
72
+
73
+ /**
74
+ * Take the lock at `path`. Make its directory with mode 0700 when necessary,
75
+ * unless `privateDirectory` is false. Return `held` when another connection,
76
+ * in this process or in another process, keeps the lock past the wait bound.
77
+ */
78
+ export async function acquireKitLock(
79
+ path: string,
80
+ options: KitLockOptions,
81
+ ): Promise<KitLockResult> {
82
+ const now = options.now ?? Date.now;
83
+ const sleep = options.sleep ?? ((ms: number) => sleepMs(ms));
84
+ const pollMs = options.pollMs ?? POLL_MS;
85
+ const deadline = now() + options.waitMs;
86
+
87
+ if (options.privateDirectory !== false) {
88
+ const directory = dirname(path);
89
+ mkdirSync(directory, { recursive: true, mode: 0o700 });
90
+ chmodSync(directory, 0o700);
91
+ }
92
+ const connection = new DatabaseSync(path);
93
+ try {
94
+ // A busy lock must fail at once; this loop does the wait.
95
+ connection.exec("PRAGMA busy_timeout = 0");
96
+ for (;;) {
97
+ if (tryBegin(connection)) {
98
+ heldConnections.add(connection);
99
+ return { kind: "acquired", lock: { path, connection } };
100
+ }
101
+ const remaining = deadline - now();
102
+ if (remaining <= 0) break;
103
+ await sleep(Math.min(pollMs, remaining));
104
+ }
105
+ } catch (cause) {
106
+ connection.close();
107
+ throw cause;
108
+ }
109
+ connection.close();
110
+ return { kind: "held" };
111
+ }
112
+
113
+ /** Release the lock: end the transaction and close the connection. */
114
+ export function releaseKitLock(lock: KitLock): void {
115
+ heldConnections.delete(lock.connection);
116
+ try {
117
+ lock.connection.exec("ROLLBACK");
118
+ } finally {
119
+ lock.connection.close();
120
+ }
121
+ }