docks-kit 0.22.2 → 0.22.4

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.
@@ -80,8 +80,11 @@ marketplace row counts as installed only when its `scope` is `user`, so a repeat
80
80
  run is a no-op and a project-only row still installs. When just the legacy
81
81
  config-root registry lists `docks`, omp copies it forward itself: the sync runs
82
82
  `marketplace update`, or the read-only `marketplace list` under
83
- `--skip-plugin-refresh`, which keeps installs but fetches nothing. A dry run
84
- invokes no omp subcommand.
83
+ `--skip-plugin-refresh`, which keeps installs but fetches nothing. After a
84
+ plugin operation, the sync reads the inventory again and prints one line that
85
+ names each plugin with its version change, for example
86
+ `omp plugins synced: docks@docks 0.21.1 -> 0.22.0, pi-intercom 0.14.0 (new), docks-kit-omp linked`.
87
+ A dry run invokes no omp subcommand.
85
88
 
86
89
  Paths mirror upstream `dirs.ts` `DirResolver`, resolved from the environment
87
90
  plus directory probes, so a dry run still runs no omp subcommand. The agent
@@ -58,8 +58,9 @@ a fresh host immediately and leaves an existing install alone.
58
58
 
59
59
  The rustup channel follows the same rule. Sync adds the component only when the
60
60
  `rust-analyzer` binary is missing or is a rustup proxy that cannot run because
61
- the component is not installed. `rustup update` is the user's remedy for an old
62
- component.
61
+ the component is not installed. When `rust-analyzer --version` does not answer
62
+ within 60 s, sync warns, stops the probe, and does not add the component on that
63
+ run. `rustup update` is the user's remedy for an old component.
63
64
 
64
65
  A lagging server shows as `below-floor` in `docks-kit toolchain check`. To move
65
66
  the npm servers to their `verified` pins, run:
@@ -5,7 +5,12 @@
5
5
  * server binaries, so this pass installs the missing ones. Message strings
6
6
  * and spawned argv are part of the contract.
7
7
  */
8
- import { defaultProbeExecutor, npmGlobalVersions, type ToolId } from "./deps";
8
+ import {
9
+ defaultProbeExecutor,
10
+ npmGlobalVersions,
11
+ VERSION_PROBE_LIMIT_MS,
12
+ type ToolId,
13
+ } from "./deps";
9
14
  import { realpathSync } from "node:fs";
10
15
  import { capture, spawnProcess } from "./exec";
11
16
  import type { Ctx } from "./index";
@@ -97,6 +102,26 @@ async function installRustAnalyzer(ctx: Ctx): Promise<void> {
97
102
  }
98
103
  }
99
104
 
105
+ /**
106
+ * rustup links a rust-analyzer proxy into ~/.cargo/bin even when the
107
+ * component is not installed, and that proxy reports no version. With rustup
108
+ * present, a PATH hit without a version counts as missing. A probe that does
109
+ * not answer in time tells nothing about the component, and the install would
110
+ * wait on the same rustup, so that hit does not count as missing.
111
+ */
112
+ async function rustAnalyzerMissing(ctx: Ctx, rustupPresent: boolean): Promise<boolean> {
113
+ if (ctx.services.deps.probe("rust-analyzer").state === "missing") return true;
114
+ if (!rustupPresent) return false;
115
+ const reading = await ctx.services.deps.versionReading("rust-analyzer");
116
+ if (reading.kind === "timed-out") {
117
+ ctx.services.logger.warn(
118
+ `rust-analyzer --version did not answer within ${VERSION_PROBE_LIMIT_MS / 1000} s; skipped the rust-analyzer install check. Run rust-analyzer --version to see what it waits for, then re-run sync.`,
119
+ );
120
+ return false;
121
+ }
122
+ return reading.value === "";
123
+ }
124
+
100
125
  export async function syncLspServers(ctx: Ctx): Promise<void> {
101
126
  const { echo, verbose, warn } = ctx.services.logger;
102
127
  const sot = parseJson(payloadText("SoT/.claude/settings.json"));
@@ -117,13 +142,7 @@ export async function syncLspServers(ctx: Ctx): Promise<void> {
117
142
  hasTs && ctx.services.deps.probe("typescript-language-server").state === "missing";
118
143
  const tscMissing = hasTs && ctx.services.deps.probe("tsc").state === "missing";
119
144
  const rustupPresent = ctx.services.deps.probe("rustup").state === "present";
120
- // rustup links a rust-analyzer proxy into ~/.cargo/bin even when the
121
- // component is not installed, and that proxy reports no version. With
122
- // rustup present, a PATH hit without a version counts as missing.
123
- const rustMissing =
124
- hasRust &&
125
- (ctx.services.deps.probe("rust-analyzer").state === "missing" ||
126
- (rustupPresent && (await ctx.services.deps.version("rust-analyzer")) === ""));
145
+ const rustMissing = hasRust && (await rustAnalyzerMissing(ctx, rustupPresent));
127
146
  // A host without rustup does no Rust work, so the plugin has nothing to
128
147
  // serve there. Installing is impossible and warning every sync would name no
129
148
  // action the user wants, so that host is not counted as missing a tool.
@@ -9,7 +9,7 @@
9
9
  */
10
10
  import { isAbsolute } from "node:path";
11
11
 
12
- import { capture, commandExists, p, which } from "./exec";
12
+ import { capture, captureWithin, commandExists, p, which, type CaptureOutcome } from "./exec";
13
13
  import { engineHome } from "./harnesses";
14
14
  import { isObject, parseJson } from "./jq";
15
15
  import { hostOs, platformName, rawPlatform } from "./os";
@@ -47,9 +47,26 @@ export type ProbeResult =
47
47
  export interface ProbeExecutor {
48
48
  readonly commandExists: (name: string) => boolean;
49
49
  readonly capture: (cmd: string, args: ReadonlyArray<string>) => Promise<string>;
50
+ /** `capture` with a time limit. Without it, a version probe has no limit. */
51
+ readonly captureWithin?: (
52
+ cmd: string,
53
+ args: ReadonlyArray<string>,
54
+ timeoutMs: number,
55
+ ) => Promise<CaptureOutcome>;
50
56
  readonly which: (name: string) => string;
51
57
  }
52
58
 
59
+ /** The version text ("" when the tool is absent or prints none), or no answer in time. */
60
+ export type VersionReading =
61
+ | { readonly kind: "version"; readonly value: string }
62
+ | { readonly kind: "timed-out" };
63
+
64
+ /**
65
+ * The longest wait for a `<tool> --version` answer. A cold rust-analyzer start
66
+ * took 20 s on a macOS runner (#114), so the limit must let that pass.
67
+ */
68
+ export const VERSION_PROBE_LIMIT_MS = 60_000;
69
+
53
70
  export interface DependencySpec {
54
71
  readonly id: ToolId;
55
72
  readonly requirement: Requirement;
@@ -57,6 +74,10 @@ export interface DependencySpec {
57
74
  /** Platform-correct one-line install command (param injectable for tests). */
58
75
  readonly installHint: (platform?: NodeJS.Platform) => string;
59
76
  readonly resolve?: (exec: ProbeExecutor, platform: NodeJS.Platform) => ProbeResult;
77
+ /**
78
+ * Reads the version in a different way than `<id> <versionArgs>`. This
79
+ * reader has no time limit.
80
+ */
60
81
  readonly version?: (exec: ProbeExecutor) => Promise<string>;
61
82
  }
62
83
 
@@ -90,15 +111,6 @@ const pathProbe =
90
111
  return path === "" ? { state: "present" } : { state: "present", path };
91
112
  };
92
113
 
93
- const versionProbe =
94
- (
95
- id: string,
96
- versionArgs: ReadonlyArray<string> = ["--version"],
97
- parse: (out: string) => string = (out) => out,
98
- ): ((exec: ProbeExecutor) => Promise<string>) =>
99
- async (exec) =>
100
- parse(await exec.capture(id, versionArgs));
101
-
102
114
  /**
103
115
  * The resolved path gets persisted into global direct-exec hooks, so a
104
116
  * relative `which` hit (relative PATH entry, relative BUN_INSTALL) would
@@ -154,33 +166,18 @@ const versionNpmGlobal =
154
166
  async (exec: ProbeExecutor): Promise<string> =>
155
167
  (await npmGlobalVersions(exec))[pkg] ?? "";
156
168
 
157
- export const defaultProbeExecutor: ProbeExecutor = { commandExists, capture, which };
169
+ export const defaultProbeExecutor: ProbeExecutor = { commandExists, capture, captureWithin, which };
158
170
 
159
171
  export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
160
- git: spec(
161
- "git",
162
- "optional",
163
- (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("git"),
164
- { version: versionProbe("git") },
165
- ),
166
- jq: spec("jq", "optional", (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("jq"), {
167
- version: versionProbe("jq"),
168
- }),
169
- curl: spec(
170
- "curl",
171
- "optional",
172
- (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("curl"),
173
- {
174
- version: versionProbe("curl"),
175
- },
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
176
  ),
177
177
  node: spec(
178
178
  "node",
179
179
  "optional",
180
180
  () => "install Node.js via https://nodejs.org (or your package manager)",
181
- {
182
- version: versionProbe("node"),
183
- },
184
181
  ),
185
182
  npm: spec(
186
183
  "npm",
@@ -192,24 +189,21 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
192
189
  "optional",
193
190
  () => "ships with Node.js — install via https://nodejs.org (or your package manager)",
194
191
  ),
195
- claude: spec(
196
- "claude",
197
- "optional",
198
- (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("claude"),
199
- { version: versionProbe("claude") },
192
+ claude: spec("claude", "optional", (pf = rawPlatform()) =>
193
+ hostOs(platformName(pf)).installHint("claude"),
200
194
  ),
201
- codex: spec(
202
- "codex",
203
- "optional",
204
- (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("codex"),
205
- { version: versionProbe("codex") },
195
+ codex: spec("codex", "optional", (pf = rawPlatform()) =>
196
+ hostOs(platformName(pf)).installHint("codex"),
206
197
  ),
207
198
  omp: spec(
208
199
  "omp",
209
200
  "optional",
210
201
  () =>
211
202
  "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)",
212
- { version: versionProbe("omp", ["--version"], (out) => out.trim().replace(/^omp[/v]/, "")) },
203
+ {
204
+ version: async (exec) =>
205
+ (await exec.capture("omp", ["--version"])).trim().replace(/^omp[/v]/, ""),
206
+ },
213
207
  ),
214
208
  bun: spec("bun", "optional", () => "curl -fsSL https://bun.sh/install | bash", {
215
209
  resolve: resolveBun,
@@ -223,9 +217,6 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
223
217
  "bwrap",
224
218
  "optional",
225
219
  () => "sudo apt install -y bubblewrap (or dnf/pacman/zypper equivalent)",
226
- {
227
- version: versionProbe("bwrap"),
228
- },
229
220
  ),
230
221
  ffplay: spec(
231
222
  "ffplay",
@@ -233,7 +224,6 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
233
224
  (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("ffplay"),
234
225
  {
235
226
  versionArgs: ["-version"],
236
- version: versionProbe("ffplay", ["-version"]),
237
227
  resolve: pathProbe("ffplay"),
238
228
  },
239
229
  ),
@@ -247,20 +237,15 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
247
237
  () => "npm install -g typescript-language-server typescript",
248
238
  {
249
239
  resolve: pathProbe("typescript-language-server"),
250
- version: versionProbe("typescript-language-server"),
251
240
  },
252
241
  ),
253
242
  tsc: spec("tsc", "optional", () => "npm install -g typescript", {
254
243
  resolve: pathProbe("tsc"),
255
- version: versionProbe("tsc"),
256
244
  }),
257
245
  "rust-analyzer": spec("rust-analyzer", "optional", () => "rustup component add rust-analyzer", {
258
246
  resolve: pathProbe("rust-analyzer"),
259
- version: versionProbe("rust-analyzer"),
260
- }),
261
- rustup: spec("rustup", "optional", () => "install the Rust toolchain from https://rustup.rs", {
262
- version: versionProbe("rustup"),
263
247
  }),
248
+ rustup: spec("rustup", "optional", () => "install the Rust toolchain from https://rustup.rs"),
264
249
  "apt-get": spec("apt-get", "optional", () => "install apt via your Linux distribution"),
265
250
  dnf: spec("dnf", "optional", () => "install dnf via your Linux distribution"),
266
251
  pacman: spec("pacman", "optional", () => "install pacman via your Linux distribution"),
@@ -275,14 +260,43 @@ export function resolveDependency(
275
260
  return (specification.resolve ?? pathProbe(specification.id))(exec, platform);
276
261
  }
277
262
 
263
+ /**
264
+ * Reads the version with `<id> <versionArgs>` under `VERSION_PROBE_LIMIT_MS`,
265
+ * or with the spec's own `version` reader. An executor without
266
+ * `captureWithin` reads without a limit and never reports `timed-out`.
267
+ */
268
+ export async function resolveVersionReading(
269
+ specification: DependencySpec,
270
+ exec: ProbeExecutor,
271
+ ): Promise<VersionReading> {
272
+ if (resolveDependency(specification, exec).state !== "present") {
273
+ return { kind: "version", value: "" };
274
+ }
275
+ if (specification.version !== undefined) {
276
+ return { kind: "version", value: await specification.version(exec) };
277
+ }
278
+ if (exec.captureWithin === undefined) {
279
+ return {
280
+ kind: "version",
281
+ value: await exec.capture(specification.id, specification.versionArgs),
282
+ };
283
+ }
284
+ const outcome = await exec.captureWithin(
285
+ specification.id,
286
+ specification.versionArgs,
287
+ VERSION_PROBE_LIMIT_MS,
288
+ );
289
+ if (outcome.kind === "timed-out") return outcome;
290
+ return { kind: "version", value: outcome.kind === "output" ? outcome.stdout : "" };
291
+ }
292
+
293
+ /** `resolveVersionReading` as text: a probe that timed out reads as no version. */
278
294
  export async function resolveVersion(
279
295
  specification: DependencySpec,
280
296
  exec: ProbeExecutor,
281
297
  ): Promise<string> {
282
- if (resolveDependency(specification, exec).state !== "present") return "";
283
- return await (specification.version ?? versionProbe(specification.id, specification.versionArgs))(
284
- exec,
285
- );
298
+ const reading = await resolveVersionReading(specification, exec);
299
+ return reading.kind === "version" ? reading.value : "";
286
300
  }
287
301
 
288
302
  export async function resolvePath(
@@ -70,6 +70,8 @@ export interface AsyncProcessResult {
70
70
  readonly stdout: string;
71
71
  readonly stderr: string;
72
72
  readonly error?: Error;
73
+ /** Set when `timeoutMs` expired before the child closed; the output is partial. */
74
+ readonly timedOut?: true;
73
75
  }
74
76
 
75
77
  /**
@@ -95,6 +97,11 @@ export interface AsyncProcessOptions {
95
97
  readonly cwd?: string;
96
98
  /** Host whose executable resolution and argv shaping apply; tests inject it. */
97
99
  readonly host?: HostOs;
100
+ /**
101
+ * Kill the child and resolve with `timedOut` when it does not close within
102
+ * this many milliseconds. No limit when absent.
103
+ */
104
+ readonly timeoutMs?: number;
98
105
  }
99
106
 
100
107
  export function spawnProcess(
@@ -126,6 +133,9 @@ export function spawnProcess(
126
133
  child = spawn(invocation.command, [...invocation.args], {
127
134
  stdio: options.stdio ?? ["ignore", "pipe", "ignore"],
128
135
  ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
136
+ // A bounded child leads its own process group on POSIX, so a timeout
137
+ // can end the processes that it started too (see killProcessTree).
138
+ ...(options.timeoutMs !== undefined && !WINDOWS_PROCESS ? { detached: true } : {}),
129
139
  windowsVerbatimArguments: invocation.windowsVerbatimArguments,
130
140
  });
131
141
  } catch (cause) {
@@ -158,18 +168,111 @@ export function spawnProcess(
158
168
  child.once("error", (cause) => {
159
169
  error ??= cause;
160
170
  });
171
+ if (options.timeoutMs !== undefined) trackBoundedChild(child);
172
+ const timer =
173
+ options.timeoutMs === undefined
174
+ ? undefined
175
+ : setTimeout(() => {
176
+ // A version proxy, such as rustup, runs the real tool as its own
177
+ // child, so end the whole process tree, not only the direct child.
178
+ // A process that holds the pipes could still keep them open, and
179
+ // "close" waits for the pipes. Close our ends and unref the child,
180
+ // so neither this promise nor the event loop waits for it.
181
+ killProcessTree(child);
182
+ boundedChildren.delete(child);
183
+ child.stdout?.destroy();
184
+ child.stderr?.destroy();
185
+ child.unref();
186
+ resolve({ exitCode: null, stdout, stderr, timedOut: true });
187
+ }, options.timeoutMs);
161
188
  child.once("close", (exitCode) => {
189
+ clearTimeout(timer);
190
+ boundedChildren.delete(child);
162
191
  resolve({ exitCode, stdout, stderr, ...(error !== undefined ? { error } : {}) });
163
192
  });
164
193
  return promise;
165
194
  }
166
195
 
196
+ /**
197
+ * The kill strategy follows the real platform, not the injected `host`: the
198
+ * host only shapes command resolution and argv.
199
+ */
200
+ const WINDOWS_PROCESS = process.platform === "win32";
201
+
202
+ /**
203
+ * Bounded children that still run. On POSIX they lead their own process
204
+ * groups, so a terminal Ctrl-C does not reach them; when the CLI exits first,
205
+ * the exit handler ends their groups.
206
+ */
207
+ const boundedChildren = new Set<ChildProcess>();
208
+ let exitHandlerInstalled = false;
209
+
210
+ function trackBoundedChild(child: ChildProcess): void {
211
+ boundedChildren.add(child);
212
+ if (exitHandlerInstalled) return;
213
+ exitHandlerInstalled = true;
214
+ process.once("exit", () => {
215
+ for (const running of boundedChildren) killProcessTree(running);
216
+ });
217
+ }
218
+
219
+ /**
220
+ * Ends `child` and every process it started. On POSIX the child leads its own
221
+ * process group (`detached`), so a signal to the negative pid reaches the
222
+ * group; the group id stays reserved while any member runs, so it cannot name
223
+ * an unrelated process. On Windows, `taskkill /T` ends the process tree; its
224
+ * absolute path keeps CreateProcess from finding a `taskkill` in the current
225
+ * directory. A child that already exited is skipped there, because Windows can
226
+ * give its pid to an unrelated process.
227
+ */
228
+ function killProcessTree(child: ChildProcess): void {
229
+ const pid = child.pid;
230
+ if (pid === undefined) return;
231
+ if (WINDOWS_PROCESS) {
232
+ if (child.exitCode !== null || child.signalCode !== null) return;
233
+ const taskkill = `${process.env["SystemRoot"] ?? "C:\\Windows"}\\System32\\taskkill.exe`;
234
+ spawnSync(taskkill, ["/pid", String(pid), "/T", "/F"], {
235
+ stdio: "ignore",
236
+ windowsHide: true,
237
+ });
238
+ return;
239
+ }
240
+ try {
241
+ process.kill(-pid, "SIGKILL");
242
+ } catch {
243
+ // The group is already gone; kill the child in case it left the group.
244
+ child.kill("SIGKILL");
245
+ }
246
+ }
247
+
167
248
  export async function capture(cmd: string, args: ReadonlyArray<string>): Promise<string> {
168
249
  const res = await spawnProcess(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
169
250
  if (res.error !== undefined || res.exitCode !== 0) return "";
170
251
  return res.stdout.replace(/[\r\n]+$/, "");
171
252
  }
172
253
 
254
+ /** The result of `captureWithin`: the output, a failure, or no answer in time. */
255
+ export type CaptureOutcome =
256
+ | { readonly kind: "output"; readonly stdout: string }
257
+ | { readonly kind: "failed" }
258
+ | { readonly kind: "timed-out" };
259
+
260
+ /**
261
+ * `capture` with a time limit. A command that does not close within
262
+ * `timeoutMs` is killed and reported as `timed-out`, not as an empty output,
263
+ * so the caller can tell "no answer" from "no version".
264
+ */
265
+ export async function captureWithin(
266
+ cmd: string,
267
+ args: ReadonlyArray<string>,
268
+ timeoutMs: number,
269
+ ): Promise<CaptureOutcome> {
270
+ const res = await spawnProcess(cmd, args, { stdio: ["ignore", "pipe", "ignore"], timeoutMs });
271
+ if (res.timedOut === true) return { kind: "timed-out" };
272
+ if (res.error !== undefined || res.exitCode !== 0) return { kind: "failed" };
273
+ return { kind: "output", stdout: res.stdout.replace(/[\r\n]+$/, "") };
274
+ }
275
+
173
276
  /**
174
277
  * Splits a Windows PATH on semicolons outside double quotes, then removes one
175
278
  * enclosing quote pair from each entry. cmd.exe and libuv read PATH this way.
@@ -21,6 +21,7 @@ import { GENERATED_PACKAGE_VERSION } from "../generated/sotPayload";
21
21
  import { payloadBytes, payloadDisplayPath, payloadPaths } from "../payload";
22
22
  import { p } from "./exec";
23
23
  import type { Ctx } from "./index";
24
+ import { isObject, parseJson } from "./jq";
24
25
  import { ensureDirectory } from "./ompFileDeploy";
25
26
 
26
27
  export const KIT_PLUGIN_NAME = "docks-kit-omp";
@@ -51,6 +52,14 @@ function pruneStale(directory: string, targets: ReadonlySet<string>): boolean {
51
52
  return changed;
52
53
  }
53
54
 
55
+ /** The `version` of the deployed manifest, or undefined when it is absent or does not parse. */
56
+ function deployedVersion(manifestPath: string): string | undefined {
57
+ if (!existsSync(manifestPath)) return undefined;
58
+ const manifest = parseJson(readFileSync(manifestPath, "utf8"));
59
+ if (manifest === undefined || !isObject(manifest)) return undefined;
60
+ return typeof manifest["version"] === "string" ? manifest["version"] : undefined;
61
+ }
62
+
54
63
  export function syncKitPlugin(ctx: Ctx): void {
55
64
  const { change, echo, verbose } = ctx.services.logger;
56
65
  const pluginDir = kitPluginDir(ctx.home);
@@ -66,6 +75,7 @@ export function syncKitPlugin(ctx: Ctx): void {
66
75
  return;
67
76
  }
68
77
 
78
+ const before = deployedVersion(p(pluginDir, "package.json"));
69
79
  let changed = false;
70
80
  for (const { source, target } of files) {
71
81
  let content = payloadBytes(source);
@@ -86,7 +96,11 @@ export function syncKitPlugin(ctx: Ctx): void {
86
96
  }
87
97
 
88
98
  if (changed) {
89
- change("omp kit plugin files synced");
99
+ change(
100
+ before === undefined || before === GENERATED_PACKAGE_VERSION
101
+ ? "omp kit plugin files synced"
102
+ : `omp kit plugin files synced (${KIT_PLUGIN_NAME} ${before} -> ${GENERATED_PACKAGE_VERSION})`,
103
+ );
90
104
  ctx.nextStepTriggers.ompRestart = true;
91
105
  } else {
92
106
  verbose("omp kit plugin files already in sync");
@@ -24,10 +24,34 @@ interface InstalledNpmPlugin {
24
24
  }
25
25
 
26
26
  interface InstalledPlugins {
27
- readonly marketplace: Set<string>;
27
+ /** Each user-scope marketplace plugin id, with its version when the row reports one. */
28
+ readonly marketplace: Map<string, string | undefined>;
28
29
  readonly npm: Map<string, InstalledNpmPlugin>;
29
30
  }
30
31
 
32
+ /** One successful plugin operation, named in the sync summary line. */
33
+ type PluginOperation =
34
+ | {
35
+ readonly kind: "marketplace" | "npm";
36
+ readonly id: string;
37
+ /**
38
+ * Whether the inventory listed the plugin before the operation, or
39
+ * undefined when that inventory could not be read.
40
+ */
41
+ readonly present: boolean | undefined;
42
+ readonly before: string | undefined;
43
+ }
44
+ | { readonly kind: "link"; readonly id: string };
45
+
46
+ /** The version of the first entry that reports one; a marketplace row has no top-level version. */
47
+ function marketplaceEntryVersion(entries: unknown): string | undefined {
48
+ if (!Array.isArray(entries)) return undefined;
49
+ for (const entry of entries) {
50
+ if (isObject(entry) && typeof entry["version"] === "string") return entry["version"];
51
+ }
52
+ return undefined;
53
+ }
54
+
31
55
  async function installedPluginIdsFromCli(): Promise<InstalledPlugins | undefined> {
32
56
  const result = await spawnProcess("omp", ["plugin", "list", "--json"], {
33
57
  stdio: ["ignore", "pipe", "ignore"],
@@ -50,10 +74,10 @@ async function installedPluginIdsFromCli(): Promise<InstalledPlugins | undefined
50
74
  // per scope holding the plugin, so a match found only in a `project` row
51
75
  // means the user scope is empty and `upgrade --scope user` would fail; only a
52
76
  // `user` row counts as installed for this pipeline.
53
- const marketplace = new Set<string>();
77
+ const marketplace = new Map<string, string | undefined>();
54
78
  for (const row of value["marketplace"]) {
55
79
  if (!isObject(row) || typeof row["id"] !== "string" || row["scope"] !== "user") continue;
56
- marketplace.add(row["id"]);
80
+ marketplace.set(row["id"], marketplaceEntryVersion(row["entries"]));
57
81
  }
58
82
 
59
83
  const npm = new Map<string, InstalledNpmPlugin>();
@@ -66,6 +90,26 @@ async function installedPluginIdsFromCli(): Promise<InstalledPlugins | undefined
66
90
  return { marketplace, npm };
67
91
  }
68
92
 
93
+ /**
94
+ * Names one operation with its version change. `after` is the inventory read
95
+ * after all operations; when it does not give a version, only the id remains.
96
+ */
97
+ function describeOperation(
98
+ operation: PluginOperation,
99
+ after: InstalledPlugins | undefined,
100
+ ): string {
101
+ if (operation.kind === "link") return `${operation.id} linked`;
102
+ const version =
103
+ operation.kind === "marketplace"
104
+ ? after?.marketplace.get(operation.id)
105
+ : after?.npm.get(operation.id)?.version;
106
+ if (version === undefined) return operation.id;
107
+ if (operation.present === false) return `${operation.id} ${version} (new)`;
108
+ if (operation.before === undefined) return `${operation.id} ${version}`;
109
+ if (operation.before === version) return `${operation.id} ${version} (current)`;
110
+ return `${operation.id} ${operation.before} -> ${version}`;
111
+ }
112
+
69
113
  async function runPluginCommand(
70
114
  ctx: Ctx,
71
115
  plugin: string,
@@ -143,7 +187,7 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
143
187
  : MARKETPLACE_PLUGIN_IDS.filter((pluginId) => installed.marketplace.has(pluginId)).length +
144
188
  (piIntercomPin !== "" && installed.npm.has("pi-intercom") ? 1 : 0) +
145
189
  (installed.npm.has(KIT_PLUGIN_NAME) ? 1 : 0);
146
- let operationsSucceeded = 0;
190
+ const operations: Array<PluginOperation> = [];
147
191
 
148
192
  for (const pluginId of MARKETPLACE_PLUGIN_IDS) {
149
193
  const present = installed?.marketplace.has(pluginId) === true;
@@ -156,7 +200,12 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
156
200
  ? ["plugin", "upgrade", "--scope", "user", pluginId]
157
201
  : ["plugin", "install", "--scope", "user", pluginId];
158
202
  if (await runPluginCommand(ctx, pluginId, args)) {
159
- operationsSucceeded++;
203
+ operations.push({
204
+ kind: "marketplace",
205
+ id: pluginId,
206
+ present: installed === undefined ? undefined : present,
207
+ before: installed?.marketplace.get(pluginId),
208
+ });
160
209
  if (!present) pluginsInstalled++;
161
210
  }
162
211
  }
@@ -175,7 +224,12 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
175
224
  ? ["install", "--force", `pi-intercom@${piIntercomPin}`]
176
225
  : ["install", `pi-intercom@${piIntercomPin}`];
177
226
  if (await runPluginCommand(ctx, "pi-intercom", args)) {
178
- operationsSucceeded++;
227
+ operations.push({
228
+ kind: "npm",
229
+ id: "pi-intercom",
230
+ present: installed === undefined ? undefined : present,
231
+ before: installedVersion,
232
+ });
179
233
  if (!present) pluginsInstalled++;
180
234
  }
181
235
  }
@@ -189,12 +243,17 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
189
243
  if (linkedTarget !== undefined && linkedTarget === realPath(kitDir)) {
190
244
  verbose(`omp kit plugin ${KIT_PLUGIN_NAME} already linked`);
191
245
  } else if (await runPluginCommand(ctx, KIT_PLUGIN_NAME, ["plugin", "link", kitDir])) {
192
- operationsSucceeded++;
246
+ operations.push({ kind: "link", id: KIT_PLUGIN_NAME });
193
247
  if (installed?.npm.has(KIT_PLUGIN_NAME) !== true) pluginsInstalled++;
194
248
  }
195
249
 
196
- if (operationsSucceeded > 0) {
197
- change(`omp plugins synced (plugins: ~${operationsSucceeded})`);
250
+ if (operations.length > 0) {
251
+ // A second inventory read gives the versions that the operations left.
252
+ progress("Reading omp plugin versions...");
253
+ const after = await installedPluginIdsFromCli();
254
+ clearProgress();
255
+ const items = operations.map((operation) => describeOperation(operation, after));
256
+ change(`omp plugins synced: ${items.join(", ")}`);
198
257
  ctx.nextStepTriggers.ompRestart = true;
199
258
  } else {
200
259
  verbose("omp plugins already in sync");
@@ -11,10 +11,12 @@ import {
11
11
  resolveDependency,
12
12
  resolvePath,
13
13
  resolveVersion,
14
+ resolveVersionReading,
14
15
  type DependencySpec,
15
16
  type ProbeExecutor,
16
17
  type ProbeResult,
17
18
  type ToolId,
19
+ type VersionReading,
18
20
  } from "./deps";
19
21
  import { makeLogger, type Logger, type LoggerSinks } from "./logger";
20
22
  import { platformName, rawPlatform, type PlatformName } from "./os";
@@ -25,6 +27,8 @@ export interface DependencyManager {
25
27
  readonly spec: (id: ToolId) => DependencySpec;
26
28
  readonly probe: (id: ToolId) => ProbeResult;
27
29
  readonly version: (id: ToolId) => Promise<string>;
30
+ /** Like `version`, but keeps a probe that did not answer in time apart from no version. */
31
+ readonly versionReading: (id: ToolId) => Promise<VersionReading>;
28
32
  readonly path: (id: ToolId) => Promise<string>;
29
33
  readonly warnMissing: (id: ToolId, logger: Logger, context?: string) => void;
30
34
  }
@@ -63,6 +67,7 @@ export const makeDependencyManager = (
63
67
  },
64
68
  probe: (id) => resolveDependency(DEPENDENCIES[id], exec, platform.raw()),
65
69
  version: (id) => resolveVersion(DEPENDENCIES[id], exec),
70
+ versionReading: (id) => resolveVersionReading(DEPENDENCIES[id], exec),
66
71
  path: (id) => resolvePath(DEPENDENCIES[id], exec, platform.raw()),
67
72
  warnMissing: (id, logger, context) => {
68
73
  if (warned.has(id)) return;
@@ -1,7 +1,7 @@
1
1
  // Generated by cli/scripts/generate-sot-payload.ts. DO NOT EDIT.
2
2
  // Edit SoT/, notification.mp3, or package.json, then run: bun cli/scripts/generate-sot-payload.ts
3
3
 
4
- export const GENERATED_PACKAGE_VERSION = "0.22.2"
4
+ export const GENERATED_PACKAGE_VERSION = "0.22.4"
5
5
 
6
6
  export const GENERATED_PAYLOAD_TEXT = {
7
7
  "SoT/.agents/skills.txt": "# Universal AI-agent skill manifest intentionally empty.\n# Global skill discovery is opt-in: add one slug per installed skill: <owner>/<repo>@<skill-name> (or a path to one skill directory).\n# EngineNative ignores comments and blank lines.\n",
package/cli/src/main.ts CHANGED
@@ -95,6 +95,11 @@ const rawChannel = process.env["DOCKS_KIT_ENGINE"];
95
95
  if (rawChannel === "native-raw" || rawChannel === "native-capture") {
96
96
  const rawArgs = process.argv.slice(2);
97
97
  const rawOperation = rawArgs.join(" ") || "default";
98
+ // The raw channels bypass BunRuntime.runMain, which turns a signal into
99
+ // process.exit. Without a handler a signal ends the process without the
100
+ // `exit` event, and exec.ts then cannot end its bounded probes.
101
+ process.once("SIGINT", () => process.exit(130));
102
+ process.once("SIGTERM", () => process.exit(143));
98
103
  try {
99
104
  process.exit(
100
105
  await runEngineNative(rawArgs, undefined, { envGlobals: rawChannel === "native-raw" }),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "docks-kit",
3
- "version": "0.22.2",
3
+ "version": "0.22.4",
4
4
  "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
5
5
  "type": "module",
6
6
  "license": "MIT",