docks-kit 0.25.0 → 0.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/AGENTS.md +12 -10
  2. package/README.md +40 -30
  3. package/cli/dist/docks-kit.js +24701 -0
  4. package/cli/docs/command-guards.md +8 -5
  5. package/cli/docs/install.md +41 -32
  6. package/cli/docs/omp-context.md +1 -1
  7. package/cli/docs/omp-models.md +1 -1
  8. package/cli/docs/overview.md +3 -3
  9. package/cli/docs/platforms.md +8 -8
  10. package/cli/src/agentDocs/agentFirstCheck.ts +786 -0
  11. package/cli/src/agentDocs/bridgeCheck.ts +226 -0
  12. package/cli/src/agentDocs/commands.ts +63 -0
  13. package/cli/src/agentDocs/prTemplate.ts +211 -0
  14. package/cli/src/agentDocs/services.ts +202 -0
  15. package/cli/src/agentDocs/shared.ts +730 -0
  16. package/cli/src/agentDocs/verifySkill.ts +136 -0
  17. package/cli/src/argv.ts +25 -1
  18. package/cli/src/commands/agentDocs.ts +29 -0
  19. package/cli/src/commands/plan.ts +29 -0
  20. package/cli/src/commands/skill.ts +29 -0
  21. package/cli/src/commands/update.ts +90 -66
  22. package/cli/src/engine-native/DESIGN.md +10 -9
  23. package/cli/src/engine-native/os/targets.ts +6 -19
  24. package/cli/src/engine.ts +0 -6
  25. package/cli/src/generated/sotPayload.ts +51 -79
  26. package/cli/src/kitHome.ts +7 -10
  27. package/cli/src/main.ts +12 -4
  28. package/cli/src/plan/bytes.ts +110 -0
  29. package/cli/src/plan/checkout.ts +379 -0
  30. package/cli/src/plan/commands.ts +1192 -0
  31. package/cli/src/plan/github.ts +816 -0
  32. package/cli/src/plan/records.ts +623 -0
  33. package/cli/src/plan/repository.ts +53 -0
  34. package/cli/src/plan/reviews.ts +292 -0
  35. package/cli/src/plan/services.ts +256 -0
  36. package/cli/src/plan/types.ts +164 -0
  37. package/cli/src/skills/commands.ts +142 -0
  38. package/cli/src/skills/config.json +30 -0
  39. package/cli/src/skills/files.ts +74 -0
  40. package/cli/src/skills/frontmatter.ts +148 -0
  41. package/cli/src/skills/guard.ts +366 -0
  42. package/cli/src/skills/kitGate.ts +406 -0
  43. package/cli/src/skills/rubric.ts +143 -0
  44. package/docks-kit +9 -40
  45. package/docks-kit.ps1 +10 -61
  46. package/package.json +10 -8
@@ -0,0 +1,136 @@
1
+ /**
2
+ * `docks-kit agent-docs verify-skill detect | write-gate <path>... | entry-gate`: check the project `verify` skill and
3
+ * guard each write that creates it. The skill lives at `.agents/skills/verify/SKILL.md`. The steps and the meaning of
4
+ * each line live in the plan-workspace reference `verify-skill-template.md`. Run it from the repository root.
5
+ *
6
+ * Output lines:
7
+ * detect `verify skill: present` or `verify skill: missing`; one `verify unverified: <n>:<line>` line for
8
+ * each line of the skill that holds `not observed:`; `ERROR verify skill check failed: cannot read
9
+ * <file>` when the skill cannot be read.
10
+ * write-gate one `target occupied: <path> ...` line for each path that must not be written: a symlink, a path
11
+ * that holds a `..` segment, or a path whose nearest existing folder cannot be entered or resolves
12
+ * outside the current folder. Nothing for a writable path.
13
+ * entry-gate `target occupied: .agents/skills/verify exists` when an entry is there, a dangling symlink included.
14
+ *
15
+ * Exit status: 2 after an ERROR line, 1 for a usage error, otherwise 0. `target occupied` lines do not change the
16
+ * status.
17
+ */
18
+ import path from "node:path";
19
+
20
+ import { Effect } from "effect";
21
+
22
+ import { UsageError } from "./shared";
23
+ import { AgentDocsFiles, errorDetail, printLines, writeStderr } from "./services";
24
+
25
+ const USAGE = "usage: docks-kit agent-docs verify-skill detect | write-gate <path>... | entry-gate";
26
+ const SKILL_DIR = ".agents/skills/verify";
27
+ const SKILL_FILE = `${SKILL_DIR}/SKILL.md`;
28
+ const UNVERIFIED_MARK = "not observed:";
29
+
30
+ /** The detect lines; on `ok: false`, `lines` still holds every line, the ERROR line included. */
31
+ export interface VerifySkillResult {
32
+ readonly ok: boolean;
33
+ readonly lines: ReadonlyArray<string>;
34
+ }
35
+
36
+ /** The detect lines for the current folder. On `ok: false`, the cause is on stderr. */
37
+ export const verifySkillLines = Effect.fn("verifySkill.lines")(function* () {
38
+ const files = yield* AgentDocsFiles;
39
+ const lines: Array<string> = [];
40
+ let ok = true;
41
+ if ((yield* files.stat(SKILL_FILE)) === "file") {
42
+ lines.push("verify skill: present");
43
+ const text = yield* files
44
+ .readFile(SKILL_FILE, "utf8")
45
+ .pipe(
46
+ Effect.catchTag("FileError", (error) =>
47
+ writeStderr(
48
+ `verify-skill: cannot read ${SKILL_FILE} (${errorDetail(error)}); make it readable and run detect again\n`,
49
+ ).pipe(Effect.as(null)),
50
+ ),
51
+ );
52
+ if (text === null) {
53
+ lines.push(`ERROR verify skill check failed: cannot read ${SKILL_FILE}`);
54
+ ok = false;
55
+ } else {
56
+ // `grep -n` numbers lines from 1 and ends the last line at the end of the file.
57
+ text
58
+ .replace(/\n$/u, "")
59
+ .split("\n")
60
+ .forEach((line, index) => {
61
+ if (line.includes(UNVERIFIED_MARK)) lines.push(`verify unverified: ${index + 1}:${line}`);
62
+ });
63
+ }
64
+ } else {
65
+ lines.push("verify skill: missing");
66
+ }
67
+ const result: VerifySkillResult = { ok, lines };
68
+ return result;
69
+ });
70
+
71
+ /** The folder that `cd` would enter for `target`: its nearest existing ancestor folder. */
72
+ const nearestFolder = Effect.fn("verifySkill.nearestFolder")(function* (target: string) {
73
+ const files = yield* AgentDocsFiles;
74
+ let folder = path.dirname(target);
75
+ while ((yield* files.stat(folder)) !== "directory") {
76
+ const parent = path.dirname(folder);
77
+ if (parent === folder) break;
78
+ folder = parent;
79
+ }
80
+ return folder;
81
+ });
82
+
83
+ /**
84
+ * The refusal for one path that a step wants to write, or null when the write may go on. A write must never go
85
+ * through a symlink or land outside the repository.
86
+ */
87
+ const refusal = Effect.fn("verifySkill.refusal")(function* (root: string, target: string) {
88
+ const files = yield* AgentDocsFiles;
89
+ if (yield* files.isSymlink(target)) return `target occupied: ${target} is a symlink`;
90
+ // The kernel resolves `link/..` to the parent of the link target, while path.dirname and the nearest-folder search
91
+ // remove `..` as text. No path with `..` passes, so both agree.
92
+ if (target.split("/").includes("..")) return `target occupied: ${target} holds a .. segment`;
93
+ const folder = yield* nearestFolder(target);
94
+ // `cd` needs search permission on the folder; realpath alone does not check it. The native realpath resolves each
95
+ // part as the kernel does; the JavaScript one removes `..` as text before it follows a symlink.
96
+ const resolved = yield* files.canSearch(folder).pipe(
97
+ Effect.andThen(files.realPathNative(folder)),
98
+ Effect.catchTag("FileError", () => Effect.succeed(null)),
99
+ );
100
+ if (resolved === null) return `target occupied: cannot resolve the folder of ${target}`;
101
+ if (!`${resolved}/`.startsWith(`${root}/`))
102
+ return `target occupied: ${target} resolves outside the repository`;
103
+ return null;
104
+ });
105
+
106
+ const writeGateLines = Effect.fn("verifySkill.writeGateLines")(function* (
107
+ targets: ReadonlyArray<string>,
108
+ ) {
109
+ const files = yield* AgentDocsFiles;
110
+ // The working folder is the physical path, as `pwd -P` prints it.
111
+ const root = yield* files.workingFolder;
112
+ const lines: Array<string> = [];
113
+ for (const target of targets) {
114
+ const line = yield* refusal(root, target);
115
+ if (line !== null) lines.push(line);
116
+ }
117
+ return lines;
118
+ });
119
+
120
+ /** Run `verify-skill <args>` and return its exit status; a usage error fails with UsageError. */
121
+ export const runVerifySkill = Effect.fn("verifySkill.run")(function* (args: ReadonlyArray<string>) {
122
+ const files = yield* AgentDocsFiles;
123
+ const [command, ...rest] = args;
124
+ let result: VerifySkillResult;
125
+ if (command === "detect" && rest.length === 0) result = yield* verifySkillLines();
126
+ else if (command === "write-gate" && rest.length > 0)
127
+ result = { ok: true, lines: yield* writeGateLines(rest) };
128
+ else if (command === "entry-gate" && rest.length === 0)
129
+ result = {
130
+ ok: true,
131
+ lines: (yield* files.entryExists(SKILL_DIR)) ? [`target occupied: ${SKILL_DIR} exists`] : [],
132
+ };
133
+ else return yield* new UsageError({ usage: USAGE });
134
+ yield* printLines(result.lines);
135
+ return result.ok ? 0 : 2;
136
+ });
package/cli/src/argv.ts CHANGED
@@ -6,6 +6,9 @@ import { updateCommand } from "./commands/update";
6
6
  import { ompCommand } from "./commands/omp";
7
7
  import { scratchCommand } from "./commands/scratch";
8
8
  import { tidyCommand } from "./commands/tidy";
9
+ import { planCommand } from "./commands/plan";
10
+ import { agentDocsCommand } from "./commands/agentDocs";
11
+ import { skillCommand } from "./commands/skill";
9
12
  import {
10
13
  buildSurfaces,
11
14
  normalizeArgv,
@@ -32,6 +35,9 @@ export const COMMANDS = [
32
35
  ompCommand,
33
36
  scratchCommand,
34
37
  tidyCommand,
38
+ planCommand,
39
+ agentDocsCommand,
40
+ skillCommand,
35
41
  ] as const;
36
42
 
37
43
  const SURFACES: ArgvSurfaces = buildSurfaces(COMMANDS, GlobalFlag.BuiltIns);
@@ -46,9 +52,27 @@ const reject = (message: string): ArgvOutcome => ({
46
52
  export const subcommandName = (args: ReadonlyArray<string>): string | undefined =>
47
53
  scanSubcommandName(args, SURFACES);
48
54
 
55
+ // `docks-kit plan`, `docks-kit agent-docs`, and `docks-kit skill` pass every later word to their dispatcher, which
56
+ // parses them as the former scripts did, so a `--` after the command word keeps Effect from reading them as flags or
57
+ // adding its own refusal.
58
+ const RAW_PASSTHROUGH: ReadonlySet<string> = new Set(["plan", "agent-docs", "skill"]);
59
+
60
+ const spliceRawBoundary = (args: ReadonlyArray<string>, word: string): ReadonlyArray<string> => {
61
+ const index = args.findIndex(
62
+ (token, at) => token === word && subcommandName(args.slice(0, at + 1)) === word,
63
+ );
64
+ return [...args.slice(0, index + 1), "--", ...args.slice(index + 1)];
65
+ };
66
+
67
+ const passthroughBoundary = (args: ReadonlyArray<string>): ReadonlyArray<string> => {
68
+ const word = subcommandName(args);
69
+ if (word === "omp") return spliceOmpBoundary(args, SURFACES);
70
+ return word !== undefined && RAW_PASSTHROUGH.has(word) ? spliceRawBoundary(args, word) : args;
71
+ };
72
+
49
73
  /** Validate the argument list, then hand back the arguments Effect 4 should parse. */
50
74
  export const prepareArgv = (args: ReadonlyArray<string>): ArgvOutcome => {
51
- const boundaryArgs = subcommandName(args) === "omp" ? spliceOmpBoundary(args, SURFACES) : args;
75
+ const boundaryArgs = passthroughBoundary(args);
52
76
  const subcommand = subcommandName(boundaryArgs);
53
77
  const commandSurface =
54
78
  subcommand === undefined ? undefined : SURFACES.commandSurfaces.get(subcommand);
@@ -0,0 +1,29 @@
1
+ import { Argument, Command } from "effect/cli";
2
+ import { Effect } from "effect";
3
+
4
+ import { runAgentDocs } from "../agentDocs/commands";
5
+ import { AgentDocsServicesLive } from "../agentDocs/services";
6
+
7
+ // `argv.ts` puts a `--` after the `agent-docs` word, so every later word reaches the agent-docs dispatcher as it was
8
+ // given, and each helper refuses an unknown argument with its own usage line.
9
+ const args: Argument.Argument<ReadonlyArray<string>> = Argument.String("args").pipe(
10
+ Argument.withDescription(
11
+ "pr-template detect|gate, verify-skill detect|write-gate <path>...|entry-gate, agent-first detect|check|convert-agent <path>, bridge-check audit|verify [--expect <path>]...",
12
+ ),
13
+ Argument.variadic(),
14
+ );
15
+
16
+ export const agentDocsCommand = Command.make("agent-docs", { args }, (config) =>
17
+ runAgentDocs(config.args).pipe(
18
+ Effect.flatMap((code) =>
19
+ Effect.sync(() => {
20
+ process.exitCode = code;
21
+ }),
22
+ ),
23
+ Effect.provide(AgentDocsServicesLive),
24
+ ),
25
+ ).pipe(
26
+ Command.withDescription(
27
+ "Agent-doc checks of the agent-first-setup, claude-md-migration, and plan-workspace skills: pull-request templates, the verify skill, the agent-first check, and the CLAUDE.md bridge check.",
28
+ ),
29
+ );
@@ -0,0 +1,29 @@
1
+ import { Argument, Command } from "effect/cli";
2
+ import { Effect } from "effect";
3
+
4
+ import { runPlan } from "../plan/commands";
5
+ import { PlanServicesLive } from "../plan/services";
6
+
7
+ // `argv.ts` puts a `--` after the `plan` word, so every later word reaches the plan dispatcher as it was given, and
8
+ // the dispatcher refuses an unknown argument with the words of the plan contract.
9
+ const args: Argument.Argument<ReadonlyArray<string>> = Argument.String("args").pipe(
10
+ Argument.withDescription(
11
+ "new|show|export|edit|status|step|list|archive|retire|reopen|base-blob|checkout-state and their arguments",
12
+ ),
13
+ Argument.variadic(),
14
+ );
15
+
16
+ export const planCommand = Command.make("plan", { args }, (config) =>
17
+ runPlan(config.args).pipe(
18
+ Effect.flatMap((code) =>
19
+ Effect.sync(() => {
20
+ process.exitCode = code;
21
+ }),
22
+ ),
23
+ Effect.provide(PlanServicesLive),
24
+ ),
25
+ ).pipe(
26
+ Command.withDescription(
27
+ "Plan lifecycle helper of the plan-manager skill: GitHub plan issues, plan exports and edits, and checkout snapshots.",
28
+ ),
29
+ );
@@ -0,0 +1,29 @@
1
+ import { Argument, Command } from "effect/cli";
2
+ import { Effect } from "effect";
3
+
4
+ import { runSkill } from "../skills/commands";
5
+ import { SkillFiles } from "../skills/files";
6
+
7
+ // `argv.ts` puts a `--` after the `skill` word, so every later word reaches the skill dispatcher as it was given, and
8
+ // the dispatcher answers a word it does not know with its own usage line.
9
+ const args: Argument.Argument<ReadonlyArray<string>> = Argument.String("args").pipe(
10
+ Argument.withDescription(
11
+ "guard [--strict] <skill-dir|skills-root>..., score [--per-file] [skills-root] (default .agents/skills)",
12
+ ),
13
+ Argument.variadic(),
14
+ );
15
+
16
+ export const skillCommand = Command.make("skill", { args }, (config) =>
17
+ runSkill(config.args).pipe(
18
+ Effect.flatMap((code) =>
19
+ Effect.sync(() => {
20
+ process.exitCode = code;
21
+ }),
22
+ ),
23
+ Effect.provide(SkillFiles.layer),
24
+ ),
25
+ ).pipe(
26
+ Command.withDescription(
27
+ "SKILL.md checks of the write-skill and skill-maintenance skills: the portable validator and the 16-point docks rubric score.",
28
+ ),
29
+ );
@@ -1,9 +1,10 @@
1
1
  import { Command, Flag } from "effect/cli";
2
2
  import { Console, Effect } from "effect";
3
+ import type { SpawnSyncOptions, SpawnSyncReturns } from "node:child_process";
3
4
  import { existsSync, readFileSync } from "node:fs";
4
- import { bail, compiled } from "../engine";
5
+ import { join } from "node:path";
6
+ import { bail } from "../engine";
5
7
  import { kitHome } from "../kitHome";
6
- import { DEPENDENCIES, defaultProbeExecutor, resolvePath } from "../engine-native/deps";
7
8
  import { p, spawnHost } from "../engine-native/exec";
8
9
  import { hostOs, type HostOs } from "../engine-native/os";
9
10
 
@@ -12,8 +13,19 @@ const noSync = Flag.Boolean("no-sync").pipe(
12
13
  Flag.withDefault(false),
13
14
  );
14
15
 
15
- const git = (home: string, args: Array<string>): { ok: boolean; out: string } => {
16
- const res = spawnHost("git", ["-C", home, ...args]);
16
+ /** The host spawn of an update. Tests pass a recorder to observe the children. */
17
+ type UpdateSpawn = (
18
+ command: string,
19
+ args: ReadonlyArray<string>,
20
+ overrides?: SpawnSyncOptions,
21
+ ) => SpawnSyncReturns<string>;
22
+
23
+ const git = (
24
+ spawn: UpdateSpawn,
25
+ home: string,
26
+ args: Array<string>,
27
+ ): { ok: boolean; out: string } => {
28
+ const res = spawn("git", ["-C", home, ...args]);
17
29
  return {
18
30
  ok: res.error === undefined && res.status === 0,
19
31
  out: `${res.stdout ?? ""}${res.stderr ?? ""}`.trim(),
@@ -22,13 +34,49 @@ const git = (home: string, args: Array<string>): { ok: boolean; out: string } =>
22
34
 
23
35
  /** Spawn the freshly-updated code — the running process still has the old
24
36
  * version loaded, so the chained sync must be a new process. */
25
- const chainSync = (argv0: string, args: Array<string>): Effect.Effect<void> =>
37
+ const chainSync = (spawn: UpdateSpawn, args: Array<string>): Effect.Effect<void> =>
26
38
  Effect.sync(() => {
27
- const res = spawnHost(argv0, args, { stdio: "inherit" });
39
+ const res = spawn(process.execPath, args, { stdio: "inherit" });
28
40
  if (res.error !== undefined || res.status !== 0) process.exit(res.status ?? 1);
29
41
  });
30
42
 
31
- export const updateSyncArgs = (home: string): Array<string> => [p(home, "cli/src/main.ts"), "sync"];
43
+ type PackageBinEntry =
44
+ | { readonly ok: true; readonly entry: string }
45
+ | { readonly ok: false; readonly diagnostic: string };
46
+
47
+ /** The file that the installed package's `bin` names. The chained sync runs
48
+ * it, not a fixed path, because `@latest` can be a release that predates the
49
+ * bundle and still names `cli/src/main.ts`. The host's `join` builds the
50
+ * spawned path, so a Windows home gets one separator style. */
51
+ const packageBinEntry = (home: string): PackageBinEntry => {
52
+ const manifestPath = join(home, "package.json");
53
+ let doc: unknown;
54
+ try {
55
+ doc = JSON.parse(readFileSync(manifestPath, "utf8"));
56
+ } catch {
57
+ doc = undefined;
58
+ }
59
+ const bin = doc !== null && typeof doc === "object" && "bin" in doc ? doc.bin : undefined;
60
+ const named =
61
+ typeof bin === "string"
62
+ ? bin
63
+ : bin !== null && typeof bin === "object" && "docks-kit" in bin
64
+ ? bin["docks-kit"]
65
+ : undefined;
66
+ if (typeof named !== "string" || named === "") {
67
+ return {
68
+ ok: false,
69
+ diagnostic: `global package update completed, but ${manifestPath} names no docks-kit bin`,
70
+ };
71
+ }
72
+ const entry = join(home, named);
73
+ return existsSync(entry)
74
+ ? { ok: true, entry }
75
+ : {
76
+ ok: false,
77
+ diagnostic: `global package update completed, but the docks-kit bin ${entry} named by ${manifestPath} does not exist`,
78
+ };
79
+ };
32
80
 
33
81
  const readPackageVersion = (home: string): string => {
34
82
  try {
@@ -50,14 +98,16 @@ interface PackageRootCapture {
50
98
 
51
99
  type CapturePackageRoot = (command: string, args: ReadonlyArray<string>) => PackageRootCapture;
52
100
 
53
- const capturePackageRoot: CapturePackageRoot = (command, args) => {
54
- const res = spawnHost(command, args);
55
- return {
56
- status: res.status,
57
- stdout: res.stdout ?? "",
58
- ...(res.error === undefined ? {} : { error: res.error }),
101
+ const capturePackageRoot =
102
+ (spawn: UpdateSpawn): CapturePackageRoot =>
103
+ (command, args) => {
104
+ const res = spawn(command, args);
105
+ return {
106
+ status: res.status,
107
+ stdout: res.stdout ?? "",
108
+ ...(res.error === undefined ? {} : { error: res.error }),
109
+ };
59
110
  };
60
- };
61
111
 
62
112
  /**
63
113
  * The comparison key of a host path. Windows reports paths with backslashes
@@ -100,7 +150,7 @@ export type GlobalPackageHome =
100
150
 
101
151
  export const resolveGlobalPackageHome = (
102
152
  manager: PackageManager,
103
- capture: CapturePackageRoot = capturePackageRoot,
153
+ capture: CapturePackageRoot = capturePackageRoot(spawnHost),
104
154
  ): GlobalPackageHome => {
105
155
  const commandArgs = manager === "bun" ? ["pm", "-g", "ls"] : ["root", "-g"];
106
156
  const result = capture(manager, commandArgs);
@@ -153,69 +203,47 @@ export const packageUpdateResult = (
153
203
  return { alreadyCurrent: false, message: `Updated ${before} -> ${after}.` };
154
204
  };
155
205
 
156
- export type UpdateBunCommand =
157
- | { readonly ok: true; readonly command: string }
158
- | { readonly ok: false; readonly diagnostic: string };
159
-
160
- /**
161
- * The Bun that reinstalls checkout dependencies. The source path always runs
162
- * under Bun, and the launcher may have picked a Bun that is not on PATH, so it
163
- * reuses `execPath`. A compiled binary resolves Bun like the dependency probe:
164
- * PATH, then $BUN_INSTALL/bin, then ~/.bun/bin.
165
- */
166
- export const updateBunCommand = async (
167
- isCompiled: boolean,
168
- execPath: string,
169
- home: string,
170
- resolveBun: () => Promise<string> = () => resolvePath(DEPENDENCIES.bun, defaultProbeExecutor),
171
- ): Promise<UpdateBunCommand> => {
172
- if (!isCompiled) return { ok: true, command: execPath };
173
- const resolved = await resolveBun();
174
- return resolved === ""
175
- ? {
176
- ok: false,
177
- diagnostic: `dependencies changed but Bun was not found - run 'bun install --frozen-lockfile' in ${home}, then docks-kit sync`,
178
- }
179
- : { ok: true, command: resolved };
180
- };
181
-
182
- const updateCheckout = (home: string, skipSync: boolean) =>
206
+ export const updateCheckout = (home: string, skipSync: boolean, spawn: UpdateSpawn = spawnHost) =>
183
207
  Effect.gen(function* () {
184
- if (spawnHost("git", ["--version"], { stdio: "ignore" }).status !== 0) {
208
+ if (spawn("git", ["--version"], { stdio: "ignore" }).status !== 0) {
185
209
  return yield* bail("git not found - cannot update the kit checkout");
186
210
  }
187
- const dirty = git(home, ["status", "--porcelain"]);
211
+ const dirty = git(spawn, home, ["status", "--porcelain"]);
188
212
  if (!dirty.ok) return yield* bail(`git status failed in ${home}: ${dirty.out}`);
189
213
  if (dirty.out !== "") {
190
214
  return yield* bail(
191
215
  `kit checkout ${home} has local changes - commit or stash them, then re-run docks-kit update`,
192
216
  );
193
217
  }
194
- const upstream = git(home, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
218
+ const upstream = git(spawn, home, [
219
+ "rev-parse",
220
+ "--abbrev-ref",
221
+ "--symbolic-full-name",
222
+ "@{u}",
223
+ ]);
195
224
  if (!upstream.ok) {
196
225
  return yield* bail(
197
226
  "current branch has no upstream - set one (git branch --set-upstream-to) or update manually",
198
227
  );
199
228
  }
200
- const before = git(home, ["rev-parse", "HEAD"]).out;
201
- const pull = git(home, ["pull", "--ff-only"]);
229
+ const before = git(spawn, home, ["rev-parse", "HEAD"]).out;
230
+ const pull = git(spawn, home, ["pull", "--ff-only"]);
202
231
  if (!pull.ok) return yield* bail(`git pull --ff-only failed (diverged history?):\n${pull.out}`);
203
- const after = git(home, ["rev-parse", "HEAD"]).out;
232
+ const after = git(spawn, home, ["rev-parse", "HEAD"]).out;
204
233
 
205
234
  // A current kit still syncs: the sync repairs drift of the deployed files
206
235
  // and plugins, for example a pi-intercom install that left its pin.
207
236
  const changed = before !== after;
208
237
  if (changed) {
209
- const count = git(home, ["rev-list", "--count", `${before}..${after}`]).out;
238
+ const count = git(spawn, home, ["rev-list", "--count", `${before}..${after}`]).out;
210
239
  yield* Console.log(
211
240
  `Updated ${before.slice(0, 7)}..${after.slice(0, 7)} (${count} commit(s) from ${upstream.out}).`,
212
241
  );
213
242
 
214
- const touched = git(home, ["diff", "--name-only", before, after]).out.split("\n");
243
+ const touched = git(spawn, home, ["diff", "--name-only", before, after]).out.split("\n");
215
244
  if (touched.includes("bun.lock") || touched.includes("package.json")) {
216
- const bun = yield* Effect.promise(() => updateBunCommand(compiled, process.execPath, home));
217
- if (!bun.ok) return yield* bail(bun.diagnostic, 1);
218
- const res = spawnHost(bun.command, ["install", "--frozen-lockfile"], {
245
+ // The launcher may run a Bun that is not on PATH, so reuse the running one.
246
+ const res = spawn(process.execPath, ["install", "--frozen-lockfile"], {
219
247
  cwd: home,
220
248
  stdio: "inherit",
221
249
  });
@@ -232,13 +260,6 @@ const updateCheckout = (home: string, skipSync: boolean) =>
232
260
  );
233
261
  }
234
262
 
235
- if (compiled) {
236
- return yield* Console.log(
237
- changed
238
- ? "This compiled binary still runs the previous version - the checkout launcher will use updated source next time. Run: ./docks-kit sync (rebuild with bash cli/build-binaries.sh to restore the binary fast path)."
239
- : "This compiled binary cannot chain the sync. Run: ./docks-kit sync",
240
- );
241
- }
242
263
  if (skipSync)
243
264
  return yield* Console.log(
244
265
  changed ? "Kit updated. Run: docks-kit sync" : "Run: docks-kit sync",
@@ -248,16 +269,17 @@ const updateCheckout = (home: string, skipSync: boolean) =>
248
269
  ? "Kit updated - running sync with the new version..."
249
270
  : "Syncing to deliver plugin and config updates...",
250
271
  );
251
- return yield* chainSync(process.execPath, updateSyncArgs(home));
272
+ // The source, also when the checkout holds a stale ignored bundle.
273
+ return yield* chainSync(spawn, [join(home, "cli", "src", "main.ts"), "sync"]);
252
274
  });
253
275
 
254
- const updatePackage = (home: string, skipSync: boolean) =>
276
+ export const updatePackage = (home: string, skipSync: boolean, spawn: UpdateSpawn = spawnHost) =>
255
277
  Effect.gen(function* () {
256
278
  const manager = packageManagerForHome(home);
257
279
  const beforeVersion = readPackageVersion(home);
258
280
  const updateArgs =
259
281
  manager === "bun" ? ["add", "-g", "docks-kit@latest"] : ["install", "-g", "docks-kit@latest"];
260
- const res = spawnHost(manager, updateArgs, { stdio: "inherit" });
282
+ const res = spawn(manager, updateArgs, { stdio: "inherit" });
261
283
  if (res.error !== undefined || res.status !== 0) {
262
284
  return yield* bail(
263
285
  `global package update failed (${manager === "bun" ? "bun add -g" : "npm install -g"} docks-kit@latest)`,
@@ -265,7 +287,7 @@ const updatePackage = (home: string, skipSync: boolean) =>
265
287
  );
266
288
  }
267
289
 
268
- const updated = resolveGlobalPackageHome(manager);
290
+ const updated = resolveGlobalPackageHome(manager, capturePackageRoot(spawn));
269
291
  if (!updated.ok) {
270
292
  return yield* bail(
271
293
  `global package update completed, but the updated package root could not be resolved: ${updated.diagnostic}`,
@@ -289,12 +311,14 @@ const updatePackage = (home: string, skipSync: boolean) =>
289
311
  return yield* Console.log(
290
312
  result.alreadyCurrent ? "Run: docks-kit sync" : "Kit updated. Run: docks-kit sync",
291
313
  );
314
+ const bin = packageBinEntry(updated.home);
315
+ if (!bin.ok) return yield* bail(bin.diagnostic, 1);
292
316
  yield* Console.log(
293
317
  result.alreadyCurrent
294
318
  ? "Syncing to deliver plugin and config updates..."
295
319
  : "Kit updated - running sync with the new version...",
296
320
  );
297
- return yield* chainSync(process.execPath, updateSyncArgs(updated.home));
321
+ return yield* chainSync(spawn, [bin.entry, "sync"]);
298
322
  });
299
323
 
300
324
  export const updateCommand = Command.make("update", { noSync }, (config) =>
@@ -307,7 +331,7 @@ export const updateCommand = Command.make("update", { noSync }, (config) =>
307
331
  return yield* updatePackage(home, config.noSync);
308
332
  }
309
333
  return yield* bail(
310
- `kit home ${home} is neither a git checkout nor a global package install - update it the way it was installed (e.g. download the latest release binary)`,
334
+ `kit home ${home} is neither a git checkout nor a global package install - reinstall the kit as a git checkout or with 'bun add -g docks-kit'`,
311
335
  );
312
336
  }),
313
337
  ).pipe(
@@ -204,15 +204,16 @@ active logger binding.
204
204
  output, and the channel and migration invariants to
205
205
  `cli/test/goldens/mutation.json`.
206
206
  - `.github/workflows/parity.yml` runs its portable lane on `ubuntu-24.04` and
207
- `macos-26`: generated-payload check, typecheck, unit tests, a clean-room
208
- package install smoke, and compilation and execution of the native host
209
- artifact. On `windows-2025`, two unit-test shards and the
210
- `portable-windows-checks` job (generated-payload check, typecheck, native
211
- artifact) run in parallel. The check `portable (windows-2025)` passes only
212
- when all three pass. The Linux-canonical snapshot lane stays on Ubuntu and
213
- runs both golden suites plus their prove-red checks.
214
- - `.github/workflows/release-cli.yml` publishes four binaries (Linux x64 and
215
- arm64, macOS arm64, Windows x64), plus `SHA256SUMS` and the npm package.
207
+ `macos-26`: generated-payload check, typecheck, unit tests, and a clean-room
208
+ package install smoke. On `windows-2025`, two unit-test shards and the
209
+ `portable-windows-checks` job (generated-payload check, typecheck, and a
210
+ global install that runs the bundle) run in parallel. The check
211
+ `portable (windows-2025)` passes only when all three pass. The
212
+ Linux-canonical snapshot lane stays on Ubuntu and runs both golden suites
213
+ plus their prove-red checks.
214
+ - `.github/workflows/release-cli.yml` attaches the bundle's source map
215
+ `docks-kit.js.map` to the GitHub release and publishes the npm package with
216
+ provenance.
216
217
 
217
218
  ## Non-Goals
218
219
 
@@ -1,16 +1,9 @@
1
1
  /**
2
- * Host-to-artifact map (Platform seam in DESIGN.md). The two launchers select
3
- * a compiled binary from this table, `cli/build-binaries.sh` builds its
4
- * targets, and `release-cli.yml` publishes its artifacts. Each of these files
5
- * lists the names by hand, so `cli/test/unit/hostTargets.test.ts` checks them
6
- * against this table:
7
- * - the artifact names and `uname` keys in the Bash launcher `docks-kit`;
8
- * - the artifact name and processor architecture in `docks-kit.ps1`;
9
- * - the default `TARGETS` list of `cli/build-binaries.sh`;
10
- * - the four artifact names in each of the two lists of
11
- * `.github/workflows/release-cli.yml`: the `with.path` list of the
12
- * `actions/upload-artifact` step in job `build`, and the `for asset in`
13
- * list of the `gh release upload` step in job `github-release`.
2
+ * Host support map (Platform seam in DESIGN.md). Each of the two launchers
3
+ * checks the host by hand before it runs Bun from source, so
4
+ * `cli/test/unit/hostTargets.test.ts` checks them against this table:
5
+ * - the `uname` keys in the Bash launcher `docks-kit`;
6
+ * - the processor architecture in `docks-kit.ps1`.
14
7
  * The same test also checks two facts outside this table: the generated Bun
15
8
  * pin in the two launchers and the two installers equals the
16
9
  * `SoT/toolchain.json` pin, and `docks-kit.ps1` and `install.ps1` hold only
@@ -30,10 +23,6 @@ export interface HostTarget {
30
23
  readonly id: TargetId;
31
24
  readonly platform: PlatformName;
32
25
  readonly arch: TargetArch;
33
- /** `bun build --compile --target=` value. */
34
- readonly bunTarget: string;
35
- /** Compiled binary file name, including the Windows `.exe` suffix. */
36
- readonly artifact: string;
37
26
  /** `uname -s`-`uname -m` keys the Bash launcher matches; empty on Windows. */
38
27
  readonly unameKeys: ReadonlyArray<string>;
39
28
  /**
@@ -54,8 +43,6 @@ const target = (
54
43
  id,
55
44
  platform,
56
45
  arch,
57
- bunTarget: `bun-${id}`,
58
- artifact: platform === "windows" ? `docks-kit-${id}.exe` : `docks-kit-${id}`,
59
46
  unameKeys,
60
47
  processorArchitectures,
61
48
  });
@@ -71,7 +58,7 @@ function targetFor(platform: PlatformName, arch: string): HostTarget | undefined
71
58
  return HOST_TARGETS.find((t) => t.platform === platform && t.arch === arch);
72
59
  }
73
60
 
74
- /** Resolve the artifact for a raw Node platform/arch pair. */
61
+ /** Resolve the supported host target for a raw Node platform/arch pair. */
75
62
  export function targetForHost(platform: NodeJS.Platform, arch: string): HostTarget | undefined {
76
63
  return targetFor(platformName(platform), arch);
77
64
  }
package/cli/src/engine.ts CHANGED
@@ -21,12 +21,6 @@ const requireSupportedHost = () => {
21
21
  );
22
22
  };
23
23
 
24
- // In a compiled executable process.execPath IS the CLI, so a re-spawn must
25
- // not pass main.ts. Guarded because the unit suite imports this module under
26
- // Node, where the `Bun` global is absent; only a Bun-hosted standalone
27
- // executable can be compiled, so absence means false.
28
- export const compiled: boolean = typeof Bun !== "undefined" && Bun.isStandaloneExecutable === true;
29
-
30
24
  const failureMessage = (error: unknown): string => {
31
25
  if (error instanceof Error && error.message !== "") return error.message;
32
26
  return typeof error === "string" && error !== "" ? error : "unknown error";