docks-kit 0.24.0 → 0.26.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 (49) hide show
  1. package/AGENTS.md +21 -136
  2. package/README.md +54 -9
  3. package/cli/dist/docks-kit.js +24688 -0
  4. package/cli/docs/command-guards.md +1 -1
  5. package/cli/docs/install.md +30 -9
  6. package/cli/docs/omp-context.md +1 -1
  7. package/cli/docs/omp-models.md +5 -4
  8. package/cli/docs/sync-layers.md +46 -75
  9. package/cli/docs/toolchain.md +4 -5
  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 -31
  22. package/cli/src/engine-native/DESIGN.md +5 -6
  23. package/cli/src/engine-native/engineCtx.ts +0 -3
  24. package/cli/src/engine-native/failures.ts +2 -2
  25. package/cli/src/engine-native/ompChild.ts +1 -1
  26. package/cli/src/engine-native/ompKitPlugin.ts +7 -16
  27. package/cli/src/engine-native/ompPlugins.ts +205 -221
  28. package/cli/src/engine-native/ompSync.ts +5 -14
  29. package/cli/src/generated/sotPayload.ts +308 -12
  30. package/cli/src/main.ts +12 -3
  31. package/cli/src/plan/bytes.ts +110 -0
  32. package/cli/src/plan/checkout.ts +341 -0
  33. package/cli/src/plan/commands.ts +1192 -0
  34. package/cli/src/plan/github.ts +816 -0
  35. package/cli/src/plan/records.ts +623 -0
  36. package/cli/src/plan/repository.ts +53 -0
  37. package/cli/src/plan/reviews.ts +292 -0
  38. package/cli/src/plan/services.ts +256 -0
  39. package/cli/src/plan/types.ts +164 -0
  40. package/cli/src/skills/commands.ts +142 -0
  41. package/cli/src/skills/config.json +30 -0
  42. package/cli/src/skills/files.ts +74 -0
  43. package/cli/src/skills/frontmatter.ts +148 -0
  44. package/cli/src/skills/guard.ts +366 -0
  45. package/cli/src/skills/kitGate.ts +406 -0
  46. package/cli/src/skills/rubric.ts +143 -0
  47. package/cli/tsconfig.json +1 -0
  48. package/package.json +7 -4
  49. package/cli/src/engine-native/ompMarketplace.ts +0 -140
@@ -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,6 +1,8 @@
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";
5
+ import { join } from "node:path";
4
6
  import { bail, compiled } from "../engine";
5
7
  import { kitHome } from "../kitHome";
6
8
  import { DEPENDENCIES, defaultProbeExecutor, resolvePath } from "../engine-native/deps";
@@ -12,8 +14,19 @@ const noSync = Flag.Boolean("no-sync").pipe(
12
14
  Flag.withDefault(false),
13
15
  );
14
16
 
15
- const git = (home: string, args: Array<string>): { ok: boolean; out: string } => {
16
- const res = spawnHost("git", ["-C", home, ...args]);
17
+ /** The host spawn of an update. Tests pass a recorder to observe the children. */
18
+ type UpdateSpawn = (
19
+ command: string,
20
+ args: ReadonlyArray<string>,
21
+ overrides?: SpawnSyncOptions,
22
+ ) => SpawnSyncReturns<string>;
23
+
24
+ const git = (
25
+ spawn: UpdateSpawn,
26
+ home: string,
27
+ args: Array<string>,
28
+ ): { ok: boolean; out: string } => {
29
+ const res = spawn("git", ["-C", home, ...args]);
17
30
  return {
18
31
  ok: res.error === undefined && res.status === 0,
19
32
  out: `${res.stdout ?? ""}${res.stderr ?? ""}`.trim(),
@@ -22,13 +35,49 @@ const git = (home: string, args: Array<string>): { ok: boolean; out: string } =>
22
35
 
23
36
  /** Spawn the freshly-updated code — the running process still has the old
24
37
  * version loaded, so the chained sync must be a new process. */
25
- const chainSync = (argv0: string, args: Array<string>): Effect.Effect<void> =>
38
+ const chainSync = (spawn: UpdateSpawn, args: Array<string>): Effect.Effect<void> =>
26
39
  Effect.sync(() => {
27
- const res = spawnHost(argv0, args, { stdio: "inherit" });
40
+ const res = spawn(process.execPath, args, { stdio: "inherit" });
28
41
  if (res.error !== undefined || res.status !== 0) process.exit(res.status ?? 1);
29
42
  });
30
43
 
31
- export const updateSyncArgs = (home: string): Array<string> => [p(home, "cli/src/main.ts"), "sync"];
44
+ type PackageBinEntry =
45
+ | { readonly ok: true; readonly entry: string }
46
+ | { readonly ok: false; readonly diagnostic: string };
47
+
48
+ /** The file that the installed package's `bin` names. The chained sync runs
49
+ * it, not a fixed path, because `@latest` can be a release that predates the
50
+ * bundle and still names `cli/src/main.ts`. The host's `join` builds the
51
+ * spawned path, so a Windows home gets one separator style. */
52
+ const packageBinEntry = (home: string): PackageBinEntry => {
53
+ const manifestPath = join(home, "package.json");
54
+ let doc: unknown;
55
+ try {
56
+ doc = JSON.parse(readFileSync(manifestPath, "utf8"));
57
+ } catch {
58
+ doc = undefined;
59
+ }
60
+ const bin = doc !== null && typeof doc === "object" && "bin" in doc ? doc.bin : undefined;
61
+ const named =
62
+ typeof bin === "string"
63
+ ? bin
64
+ : bin !== null && typeof bin === "object" && "docks-kit" in bin
65
+ ? bin["docks-kit"]
66
+ : undefined;
67
+ if (typeof named !== "string" || named === "") {
68
+ return {
69
+ ok: false,
70
+ diagnostic: `global package update completed, but ${manifestPath} names no docks-kit bin`,
71
+ };
72
+ }
73
+ const entry = join(home, named);
74
+ return existsSync(entry)
75
+ ? { ok: true, entry }
76
+ : {
77
+ ok: false,
78
+ diagnostic: `global package update completed, but the docks-kit bin ${entry} named by ${manifestPath} does not exist`,
79
+ };
80
+ };
32
81
 
33
82
  const readPackageVersion = (home: string): string => {
34
83
  try {
@@ -50,14 +99,16 @@ interface PackageRootCapture {
50
99
 
51
100
  type CapturePackageRoot = (command: string, args: ReadonlyArray<string>) => PackageRootCapture;
52
101
 
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 }),
102
+ const capturePackageRoot =
103
+ (spawn: UpdateSpawn): CapturePackageRoot =>
104
+ (command, args) => {
105
+ const res = spawn(command, args);
106
+ return {
107
+ status: res.status,
108
+ stdout: res.stdout ?? "",
109
+ ...(res.error === undefined ? {} : { error: res.error }),
110
+ };
59
111
  };
60
- };
61
112
 
62
113
  /**
63
114
  * The comparison key of a host path. Windows reports paths with backslashes
@@ -100,7 +151,7 @@ export type GlobalPackageHome =
100
151
 
101
152
  export const resolveGlobalPackageHome = (
102
153
  manager: PackageManager,
103
- capture: CapturePackageRoot = capturePackageRoot,
154
+ capture: CapturePackageRoot = capturePackageRoot(spawnHost),
104
155
  ): GlobalPackageHome => {
105
156
  const commandArgs = manager === "bun" ? ["pm", "-g", "ls"] : ["root", "-g"];
106
157
  const result = capture(manager, commandArgs);
@@ -179,43 +230,48 @@ export const updateBunCommand = async (
179
230
  : { ok: true, command: resolved };
180
231
  };
181
232
 
182
- const updateCheckout = (home: string, skipSync: boolean) =>
233
+ export const updateCheckout = (home: string, skipSync: boolean, spawn: UpdateSpawn = spawnHost) =>
183
234
  Effect.gen(function* () {
184
- if (spawnHost("git", ["--version"], { stdio: "ignore" }).status !== 0) {
235
+ if (spawn("git", ["--version"], { stdio: "ignore" }).status !== 0) {
185
236
  return yield* bail("git not found - cannot update the kit checkout");
186
237
  }
187
- const dirty = git(home, ["status", "--porcelain"]);
238
+ const dirty = git(spawn, home, ["status", "--porcelain"]);
188
239
  if (!dirty.ok) return yield* bail(`git status failed in ${home}: ${dirty.out}`);
189
240
  if (dirty.out !== "") {
190
241
  return yield* bail(
191
242
  `kit checkout ${home} has local changes - commit or stash them, then re-run docks-kit update`,
192
243
  );
193
244
  }
194
- const upstream = git(home, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
245
+ const upstream = git(spawn, home, [
246
+ "rev-parse",
247
+ "--abbrev-ref",
248
+ "--symbolic-full-name",
249
+ "@{u}",
250
+ ]);
195
251
  if (!upstream.ok) {
196
252
  return yield* bail(
197
253
  "current branch has no upstream - set one (git branch --set-upstream-to) or update manually",
198
254
  );
199
255
  }
200
- const before = git(home, ["rev-parse", "HEAD"]).out;
201
- const pull = git(home, ["pull", "--ff-only"]);
256
+ const before = git(spawn, home, ["rev-parse", "HEAD"]).out;
257
+ const pull = git(spawn, home, ["pull", "--ff-only"]);
202
258
  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;
259
+ const after = git(spawn, home, ["rev-parse", "HEAD"]).out;
204
260
 
205
- // A current kit still syncs: the plugin passes deliver marketplace and
206
- // plugin updates that move independently of the kit's own version.
261
+ // A current kit still syncs: the sync repairs drift of the deployed files
262
+ // and plugins, for example a pi-intercom install that left its pin.
207
263
  const changed = before !== after;
208
264
  if (changed) {
209
- const count = git(home, ["rev-list", "--count", `${before}..${after}`]).out;
265
+ const count = git(spawn, home, ["rev-list", "--count", `${before}..${after}`]).out;
210
266
  yield* Console.log(
211
267
  `Updated ${before.slice(0, 7)}..${after.slice(0, 7)} (${count} commit(s) from ${upstream.out}).`,
212
268
  );
213
269
 
214
- const touched = git(home, ["diff", "--name-only", before, after]).out.split("\n");
270
+ const touched = git(spawn, home, ["diff", "--name-only", before, after]).out.split("\n");
215
271
  if (touched.includes("bun.lock") || touched.includes("package.json")) {
216
272
  const bun = yield* Effect.promise(() => updateBunCommand(compiled, process.execPath, home));
217
273
  if (!bun.ok) return yield* bail(bun.diagnostic, 1);
218
- const res = spawnHost(bun.command, ["install", "--frozen-lockfile"], {
274
+ const res = spawn(bun.command, ["install", "--frozen-lockfile"], {
219
275
  cwd: home,
220
276
  stdio: "inherit",
221
277
  });
@@ -248,16 +304,17 @@ const updateCheckout = (home: string, skipSync: boolean) =>
248
304
  ? "Kit updated - running sync with the new version..."
249
305
  : "Syncing to deliver plugin and config updates...",
250
306
  );
251
- return yield* chainSync(process.execPath, updateSyncArgs(home));
307
+ // The source, also when the checkout holds a stale ignored bundle.
308
+ return yield* chainSync(spawn, [join(home, "cli", "src", "main.ts"), "sync"]);
252
309
  });
253
310
 
254
- const updatePackage = (home: string, skipSync: boolean) =>
311
+ export const updatePackage = (home: string, skipSync: boolean, spawn: UpdateSpawn = spawnHost) =>
255
312
  Effect.gen(function* () {
256
313
  const manager = packageManagerForHome(home);
257
314
  const beforeVersion = readPackageVersion(home);
258
315
  const updateArgs =
259
316
  manager === "bun" ? ["add", "-g", "docks-kit@latest"] : ["install", "-g", "docks-kit@latest"];
260
- const res = spawnHost(manager, updateArgs, { stdio: "inherit" });
317
+ const res = spawn(manager, updateArgs, { stdio: "inherit" });
261
318
  if (res.error !== undefined || res.status !== 0) {
262
319
  return yield* bail(
263
320
  `global package update failed (${manager === "bun" ? "bun add -g" : "npm install -g"} docks-kit@latest)`,
@@ -265,7 +322,7 @@ const updatePackage = (home: string, skipSync: boolean) =>
265
322
  );
266
323
  }
267
324
 
268
- const updated = resolveGlobalPackageHome(manager);
325
+ const updated = resolveGlobalPackageHome(manager, capturePackageRoot(spawn));
269
326
  if (!updated.ok) {
270
327
  return yield* bail(
271
328
  `global package update completed, but the updated package root could not be resolved: ${updated.diagnostic}`,
@@ -289,12 +346,14 @@ const updatePackage = (home: string, skipSync: boolean) =>
289
346
  return yield* Console.log(
290
347
  result.alreadyCurrent ? "Run: docks-kit sync" : "Kit updated. Run: docks-kit sync",
291
348
  );
349
+ const bin = packageBinEntry(updated.home);
350
+ if (!bin.ok) return yield* bail(bin.diagnostic, 1);
292
351
  yield* Console.log(
293
352
  result.alreadyCurrent
294
353
  ? "Syncing to deliver plugin and config updates..."
295
354
  : "Kit updated - running sync with the new version...",
296
355
  );
297
- return yield* chainSync(process.execPath, updateSyncArgs(updated.home));
356
+ return yield* chainSync(spawn, [bin.entry, "sync"]);
298
357
  });
299
358
 
300
359
  export const updateCommand = Command.make("update", { noSync }, (config) =>
@@ -312,6 +371,6 @@ export const updateCommand = Command.make("update", { noSync }, (config) =>
312
371
  }),
313
372
  ).pipe(
314
373
  Command.withDescription(
315
- "Self-update the kit: autodetects the install (git checkout -> ff-only pull; bun/npm global -> @latest), then chains a flag-less sync that also refreshes plugin marketplaces and plugins, even when the kit was already current (--no-sync to skip).",
374
+ "Self-update the kit: autodetects the install (git checkout -> ff-only pull; bun/npm global -> @latest), then chains a flag-less sync that also refreshes plugins, even when the kit was already current (--no-sync to skip).",
316
375
  ),
317
376
  );
@@ -39,8 +39,7 @@ shell engine was removed after the `bash-engine-final` tag.
39
39
  the whole files, merges `config.yml` and runs the retired-key removals on
40
40
  the merged result, merges `models.yml` and runs its removals, writes the
41
41
  intercom configuration, materializes the kit plugin, and only then runs the
42
- marketplace and plugin passes, because the plugin pass links the kit plugin
43
- directory.
42
+ plugin pass, because the plugin pass links the kit plugin directory.
44
43
  - **One pipeline.** Sync runs only the omp pipeline, which is serial.
45
44
  `syncConcurrency.ts` `runBounded` stays for the parallel probes of `tidy`
46
45
  and the tidy report.
@@ -119,9 +118,9 @@ pipeline settles, also on dry-run. When the pipeline rejects, `syncDispatch.ts`
119
118
  `engineSync` skips the block and prints only the `--- Failures ---` ledger.
120
119
  The block starts with a `Repo:` line and adds the `omp:` and `omp plugins:`
121
120
  inventory lines. Dry-run leaves out the `omp plugins:` line. Next-step advice
122
- lines print only when their trigger changed this run (an omp plugin upgraded
123
- → `/reload-plugins` line; omp files changed → restart line) or under
124
- `--verbose`.
121
+ lines print only when their trigger changed this run (an omp plugin operation,
122
+ such as the uninstall of a retired marketplace plugin, or a changed omp file →
123
+ restart line) or under `--verbose`.
125
124
 
126
125
  ### Platform seam
127
126
 
@@ -178,7 +177,7 @@ active logger binding.
178
177
  | `syncConcurrency.ts` | input-ordered bounded pool (`runBounded`) for the tidy probes |
179
178
  | `../payload.ts` | generated text payload reads and presentation-only source labels |
180
179
  | `bun.ts` | per-run memoized Bun resolution/bootstrap shared by the omp pipeline and direct toolchain ensure |
181
- | `ompSync.ts` | omp pipeline orchestration and summary; `ompFileDeploy.ts`, `ompMarketplace.ts`, `ompPlugins.ts`, and `ompRemovals.ts` own the file, marketplace, plugin, and retired-key passes; `ompPaths.ts` resolves roots; `ompYaml.ts` merges YAML |
180
+ | `ompSync.ts` | omp pipeline orchestration and summary; `ompFileDeploy.ts`, `ompPlugins.ts`, and `ompRemovals.ts` own the file, plugin (with the marketplace-plugin retirement), and retired-key passes; `ompPaths.ts` resolves roots; `ompYaml.ts` merges YAML |
182
181
  | `toolchain.ts` | tool presence/version probes, verified-version floor reporting, report table |
183
182
  | `modes.ts` | direct `toolchain` mode |
184
183
  | `jq.ts` | the `Json` value type, object narrowing, jq-compatible codepoint ordering, and a parse that yields `undefined` instead of throwing |
@@ -22,8 +22,6 @@ export interface Ctx {
22
22
  /** Per-run next-step triggers (Output Policy): advice prints only when its trigger changed or --verbose. */
23
23
  readonly nextStepTriggers: {
24
24
  ompRestart: boolean;
25
- /** A marketplace plugin upgrade changed a version, so running omp sessions lost its folder. */
26
- ompPluginUpgraded: boolean;
27
25
  };
28
26
  /** Harness-CLI operations that failed this run; a non-empty list fails the sync. */
29
27
  readonly failures: Array<string>;
@@ -56,7 +54,6 @@ export function makeCtx(services: EngineServices, options: CtxOptions): Ctx {
56
54
  services,
57
55
  nextStepTriggers: {
58
56
  ompRestart: false,
59
- ompPluginUpgraded: false,
60
57
  },
61
58
  failures: [],
62
59
  };
@@ -1,6 +1,6 @@
1
1
  /**
2
- * Failure ledger for harness-CLI operations. A kit-managed marketplace or
3
- * plugin command that exits non-zero is recorded here so engineSync can list
2
+ * Failure ledger for harness-CLI operations. A kit-managed plugin or
3
+ * marketplace command that exits non-zero is recorded here so engineSync can list
4
4
  * it and exit non-zero instead of reporting a clean sync.
5
5
  */
6
6
  import type { Ctx } from "./index";
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * The `omp` child processes of a sync. Every `omp` command that the
3
- * marketplace and plugin passes run starts through `spawnOmp`, so each child
3
+ * plugin pass runs starts through `spawnOmp`, so each child
4
4
  * writes into the data root that the sync locked.
5
5
  */
6
6
  import { spawnProcess, type AsyncProcessOptions, type AsyncProcessResult } from "./exec";
@@ -6,19 +6,11 @@
6
6
  * the payload no longer lists. Split from ompSync.ts; the orchestration still
7
7
  * lives there.
8
8
  */
9
- import {
10
- chmodSync,
11
- existsSync,
12
- lstatSync,
13
- readFileSync,
14
- readdirSync,
15
- rmdirSync,
16
- unlinkSync,
17
- writeFileSync,
18
- } from "node:fs";
9
+ import { existsSync, lstatSync, readFileSync, readdirSync, rmdirSync, unlinkSync } from "node:fs";
19
10
 
20
11
  import { GENERATED_PACKAGE_VERSION } from "../generated/sotPayload";
21
- import { payloadBytes, payloadDisplayPath, payloadPaths } from "../payload";
12
+ import { payloadBytes, payloadPaths } from "../payload";
13
+ import { replaceFile } from "./atomicWrite";
22
14
  import { p } from "./exec";
23
15
  import type { Ctx } from "./index";
24
16
  import { isObject, parseJson } from "./jq";
@@ -69,9 +61,8 @@ export function syncKitPlugin(ctx: Ctx): void {
69
61
  }));
70
62
 
71
63
  if (ctx.dryRun) {
72
- for (const { source, target } of files) {
73
- echo(`[dry-run] cp ${payloadDisplayPath(source)} -> ${target}`);
74
- }
64
+ // One line for the folder: a line per file would grow with each plugin file.
65
+ echo(`[dry-run] sync embedded:${SOURCE_PREFIX} -> ${pluginDir}`);
75
66
  return;
76
67
  }
77
68
 
@@ -87,8 +78,8 @@ export function syncKitPlugin(ctx: Ctx): void {
87
78
  }
88
79
  ensureDirectory(target.slice(0, target.lastIndexOf("/")));
89
80
  if (existsSync(target) && readFileSync(target).equals(content)) continue;
90
- writeFileSync(target, content, { mode: 0o600 });
91
- chmodSync(target, 0o600);
81
+ // A rename, so a session that reads the file during a sync sees the old or the new file.
82
+ replaceFile(target, content, { mode: 0o600 });
92
83
  changed = true;
93
84
  }
94
85
  if (existsSync(pluginDir)) {