docks-kit 0.22.13 → 0.22.22

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 (57) hide show
  1. package/AGENTS.md +97 -83
  2. package/README.md +7 -7
  3. package/cli/docs/command-guards.md +12 -7
  4. package/cli/docs/flags.md +59 -9
  5. package/cli/docs/install.md +2 -2
  6. package/cli/docs/omp-context.md +27 -17
  7. package/cli/docs/omp-models.md +91 -70
  8. package/cli/docs/overview.md +1 -1
  9. package/cli/docs/platforms.md +4 -2
  10. package/cli/docs/plugins.md +8 -5
  11. package/cli/docs/sync-layers.md +6 -4
  12. package/cli/docs/toolchain.md +24 -14
  13. package/cli/src/argv.ts +7 -4
  14. package/cli/src/argvValidate.ts +2 -16
  15. package/cli/src/commands/docs.ts +1 -1
  16. package/cli/src/commands/omp.ts +81 -88
  17. package/cli/src/commands/sync.ts +6 -6
  18. package/cli/src/commands/tidy.ts +83 -26
  19. package/cli/src/engine-native/DESIGN.md +93 -56
  20. package/cli/src/engine-native/atomicWrite.ts +168 -8
  21. package/cli/src/engine-native/codexConfig.ts +2 -6
  22. package/cli/src/engine-native/codexPlugins.ts +1 -1
  23. package/cli/src/engine-native/codexSync.ts +137 -26
  24. package/cli/src/engine-native/codexToml.ts +4 -86
  25. package/cli/src/engine-native/deps.ts +51 -51
  26. package/cli/src/engine-native/exec.ts +3 -0
  27. package/cli/src/engine-native/harnesses.ts +5 -11
  28. package/cli/src/engine-native/index.ts +1 -1
  29. package/cli/src/engine-native/kitDb.ts +7 -7
  30. package/cli/src/engine-native/kitLock.ts +121 -0
  31. package/cli/src/engine-native/modes.ts +49 -31
  32. package/cli/src/engine-native/ompChild.ts +26 -0
  33. package/cli/src/engine-native/ompFastMode.ts +14 -7
  34. package/cli/src/engine-native/ompFileDeploy.ts +12 -6
  35. package/cli/src/engine-native/ompMarketplace.ts +25 -18
  36. package/cli/src/engine-native/ompOverlay.ts +23 -69
  37. package/cli/src/engine-native/ompPlugins.ts +23 -14
  38. package/cli/src/engine-native/ompRemovals.ts +97 -30
  39. package/cli/src/engine-native/ompSync.ts +66 -32
  40. package/cli/src/engine-native/os/targets.ts +16 -4
  41. package/cli/src/engine-native/os/types.ts +1 -1
  42. package/cli/src/engine-native/parseArgs.ts +27 -17
  43. package/cli/src/engine-native/processes.ts +16 -0
  44. package/cli/src/engine-native/scratch.ts +18 -0
  45. package/cli/src/engine-native/sharedTypes.d.ts +0 -2
  46. package/cli/src/engine-native/skillsInstall.ts +27 -2
  47. package/cli/src/engine-native/skillsPrune.ts +51 -49
  48. package/cli/src/engine-native/skillsRecords.ts +138 -0
  49. package/cli/src/engine-native/skillsSync.ts +16 -13
  50. package/cli/src/engine-native/syncDispatch.ts +186 -4
  51. package/cli/src/engine-native/tidy.ts +102 -119
  52. package/cli/src/engine-native/tomlLines.ts +92 -0
  53. package/cli/src/generated/sotPayload.ts +5 -5
  54. package/cli/src/main.ts +5 -30
  55. package/cli/src/manifests.ts +24 -4
  56. package/package.json +2 -2
  57. package/cli/src/engine-native/tidyLock.ts +0 -163
@@ -2,8 +2,9 @@
2
2
  * Safe sweep of agent leftovers. `planTidy` lists what can go: merged idle
3
3
  * linked worktrees and their containers, containers of gone or idle agent
4
4
  * directories, orphaned processes in agent directories, and idle scratch
5
- * entries. `applyTidy` performs a plan under a lock file. Each check fails
6
- * closed: a candidate that a check cannot prove safe stays, with its reason.
5
+ * entries. `applyTidy` performs a plan; its caller holds the tidy lock. Each
6
+ * check fails closed: a candidate that a check cannot prove safe stays, with
7
+ * its reason.
7
8
  */
8
9
  import {
9
10
  appendFileSync,
@@ -20,9 +21,9 @@ import { basename, dirname, isAbsolute, join, relative, resolve } from "node:pat
20
21
 
21
22
  import { spawnProcess, type AsyncProcessResult } from "./exec";
22
23
  import { ensureDirectory } from "./ompFileDeploy";
24
+ import { processExited } from "./processes";
23
25
  import { isSameOrInside, kitCacheDir, removeTemporaryPath } from "./scratch";
24
26
  import { runBounded } from "./syncConcurrency";
25
- import { acquireTidyLock, releaseTidyLock } from "./tidyLock";
26
27
 
27
28
  export const HOUR_MS = 3_600_000;
28
29
  export const DAY_MS = 24 * HOUR_MS;
@@ -51,10 +52,6 @@ export function agentWorktreeRoot(home: string, env: NodeJS.ProcessEnv): string
51
52
  return join(dataHome, "agent-worktrees");
52
53
  }
53
54
 
54
- export function tidyLockPath(home: string): string {
55
- return join(kitCacheDir(home), "tidy.lock");
56
- }
57
-
58
55
  export function tidyLogPath(home: string): string {
59
56
  return join(kitCacheDir(home), "tidy.log");
60
57
  }
@@ -324,12 +321,7 @@ async function darwinProcesses(uid: number): Promise<ReadonlyArray<ProcessRow> |
324
321
  return resolveProcessCwds(rows, (pid) => {
325
322
  const cwd = cwds.get(pid);
326
323
  if (cwd !== undefined) return { kind: "cwd", path: cwd };
327
- try {
328
- process.kill(pid, 0);
329
- } catch (cause) {
330
- if (errorCode(cause) === "ESRCH") return { kind: "exited" };
331
- }
332
- return { kind: "unreadable" };
324
+ return processExited(pid) ? { kind: "exited" } : { kind: "unreadable" };
333
325
  });
334
326
  }
335
327
 
@@ -1162,135 +1154,126 @@ async function removeProjectNetworks(
1162
1154
  }
1163
1155
 
1164
1156
  /**
1165
- * Perform a plan under the tidy lock. Order: stop processes, remove worktrees
1166
- * (their containers first), prune each touched repository, stop containers,
1167
- * remove containers, remove scratch entries. Never `git worktree remove --force`.
1168
- * Every Docker call uses the endpoint that the plan verified.
1157
+ * Perform a plan. The caller holds the tidy lock from before `planTidy`. Order:
1158
+ * stop processes, remove worktrees (their containers first), prune each
1159
+ * touched repository, stop containers, remove containers, remove scratch
1160
+ * entries. Never `git worktree remove --force`. Every Docker call uses the
1161
+ * endpoint that the plan verified.
1169
1162
  */
1170
1163
  export async function applyTidy(
1171
1164
  plan: TidyPlan,
1172
1165
  inputs: TidyInputs,
1173
1166
  host: TidyHost,
1174
1167
  ): Promise<{
1175
- readonly locked: boolean;
1176
1168
  readonly failures: number;
1177
1169
  readonly lines: ReadonlyArray<string>;
1178
1170
  }> {
1179
1171
  ensureDirectory(kitCacheDir(inputs.home));
1180
- const lockPath = tidyLockPath(inputs.home);
1181
- const lock = acquireTidyLock(lockPath, host.now());
1182
- if (lock === undefined) {
1183
- return { locked: true, failures: 0, lines: [`another docks-kit tidy run holds ${lockPath}`] };
1184
- }
1185
- try {
1186
- const lines: Array<string> = [];
1187
- let failures = 0;
1188
- const done = (outcome: "removed" | "stopped", subject: string): void => {
1189
- lines.push(`${outcome} ${subject}`);
1190
- };
1191
- const failed = (subject: string, detail: string): void => {
1192
- failures += 1;
1193
- lines.push(`failed ${subject}: ${detail}`);
1194
- };
1195
- const byKind = <K extends TidyAction["kind"]>(kind: K) =>
1196
- plan.actions.filter(
1197
- (action): action is Extract<TidyAction, { kind: K }> => action.kind === kind,
1198
- );
1199
-
1200
- for (const action of byKind("stop-process")) {
1201
- const subject = actionSubject(action);
1202
- try {
1203
- process.kill(action.pid, "SIGTERM");
1204
- done("stopped", subject);
1205
- } catch (cause) {
1206
- if (errorCode(cause) === "ESRCH") done("stopped", subject);
1207
- else failed(subject, errorMessage(cause));
1208
- }
1209
- }
1210
- // A container action without a verified local endpoint fails and changes nothing.
1211
- const runDocker = localDocker(host, plan.docker);
1212
- const noDocker =
1213
- plan.docker.kind === "missing" ? "docker unavailable" : notLocalMessage(plan.docker.endpoint);
1214
-
1215
- const touched = new Set<string>();
1216
- for (const action of byKind("remove-worktree")) {
1217
- const subject = actionSubject(action);
1218
- if (action.containerIds.length > 0) {
1219
- if (runDocker === undefined) {
1220
- failed(subject, noDocker);
1221
- continue;
1222
- }
1223
- const removed = await runDocker(["rm", "--force", "--volumes", ...action.containerIds]);
1224
- if (removed.code !== 0) {
1225
- failed(subject, `docker rm: ${firstLine(removed)}`);
1226
- continue;
1227
- }
1228
- await removeProjectNetworks(action.projects, runDocker);
1229
- }
1230
- touched.add(action.repo);
1231
- const result = await host.git(["-C", action.repo, "worktree", "remove", "--", action.path]);
1232
- if (result.code === 0) done("removed", subject);
1233
- else failed(subject, firstLine(result));
1234
- }
1235
- for (const repo of touched) {
1236
- const result = await host.git(["-C", repo, "worktree", "prune"]);
1237
- if (result.code !== 0) failed(`worktree prune in ${repo}`, firstLine(result));
1238
- }
1172
+ const lines: Array<string> = [];
1173
+ let failures = 0;
1174
+ const done = (outcome: "removed" | "stopped", subject: string): void => {
1175
+ lines.push(`${outcome} ${subject}`);
1176
+ };
1177
+ const failed = (subject: string, detail: string): void => {
1178
+ failures += 1;
1179
+ lines.push(`failed ${subject}: ${detail}`);
1180
+ };
1181
+ const byKind = <K extends TidyAction["kind"]>(kind: K) =>
1182
+ plan.actions.filter(
1183
+ (action): action is Extract<TidyAction, { kind: K }> => action.kind === kind,
1184
+ );
1239
1185
 
1240
- for (const action of byKind("stop-containers")) {
1241
- if (runDocker === undefined) {
1242
- failed(actionSubject(action), noDocker);
1243
- continue;
1244
- }
1245
- const result = await runDocker(["stop", ...action.ids]);
1246
- if (result.code === 0) done("stopped", actionSubject(action));
1247
- else failed(actionSubject(action), firstLine(result));
1186
+ for (const action of byKind("stop-process")) {
1187
+ const subject = actionSubject(action);
1188
+ try {
1189
+ process.kill(action.pid, "SIGTERM");
1190
+ done("stopped", subject);
1191
+ } catch (cause) {
1192
+ if (errorCode(cause) === "ESRCH") done("stopped", subject);
1193
+ else failed(subject, errorMessage(cause));
1248
1194
  }
1249
-
1250
- for (const action of byKind("remove-containers")) {
1195
+ }
1196
+ // A container action without a verified local endpoint fails and changes nothing.
1197
+ const runDocker = localDocker(host, plan.docker);
1198
+ const noDocker =
1199
+ plan.docker.kind === "missing" ? "docker unavailable" : notLocalMessage(plan.docker.endpoint);
1200
+
1201
+ const touched = new Set<string>();
1202
+ for (const action of byKind("remove-worktree")) {
1203
+ const subject = actionSubject(action);
1204
+ if (action.containerIds.length > 0) {
1251
1205
  if (runDocker === undefined) {
1252
- failed(actionSubject(action), noDocker);
1206
+ failed(subject, noDocker);
1253
1207
  continue;
1254
1208
  }
1255
- const result = await runDocker(["rm", "--force", "--volumes", ...action.ids]);
1256
- if (result.code !== 0) {
1257
- failed(actionSubject(action), firstLine(result));
1209
+ const removed = await runDocker(["rm", "--force", "--volumes", ...action.containerIds]);
1210
+ if (removed.code !== 0) {
1211
+ failed(subject, `docker rm: ${firstLine(removed)}`);
1258
1212
  continue;
1259
1213
  }
1260
- await removeProjectNetworks(action.project === "" ? [] : [action.project], runDocker);
1261
- done("removed", actionSubject(action));
1214
+ await removeProjectNetworks(action.projects, runDocker);
1262
1215
  }
1216
+ touched.add(action.repo);
1217
+ const result = await host.git(["-C", action.repo, "worktree", "remove", "--", action.path]);
1218
+ if (result.code === 0) done("removed", subject);
1219
+ else failed(subject, firstLine(result));
1220
+ }
1221
+ for (const repo of touched) {
1222
+ const result = await host.git(["-C", repo, "worktree", "prune"]);
1223
+ if (result.code !== 0) failed(`worktree prune in ${repo}`, firstLine(result));
1224
+ }
1263
1225
 
1264
- const scratch = agentRoots(inputs).scratchRoot;
1265
- for (const action of byKind("remove-scratch")) {
1266
- const subject = actionSubject(action);
1267
- if (scratch === undefined) {
1268
- failed(subject, "the scratch root is refused");
1269
- continue;
1270
- }
1271
- let activity: number | undefined;
1272
- try {
1273
- activity = entryActivity(action.path);
1274
- } catch (cause) {
1275
- lines.push(`kept ${subject}: ${errorMessage(cause)}`);
1276
- continue;
1277
- }
1278
- if (activity !== undefined && host.now() - activity < SCRATCH_IDLE_MS) {
1279
- lines.push(`kept ${subject}: active ${hours(host.now() - activity)} h ago`);
1280
- continue;
1281
- }
1282
- const outcome = removeTemporaryPath(action.path, [scratch], inputs.home);
1283
- if (outcome.kind === "removed") done("removed", subject);
1284
- else failed(subject, outcome.reason);
1226
+ for (const action of byKind("stop-containers")) {
1227
+ if (runDocker === undefined) {
1228
+ failed(actionSubject(action), noDocker);
1229
+ continue;
1285
1230
  }
1231
+ const result = await runDocker(["stop", ...action.ids]);
1232
+ if (result.code === 0) done("stopped", actionSubject(action));
1233
+ else failed(actionSubject(action), firstLine(result));
1234
+ }
1286
1235
 
1236
+ for (const action of byKind("remove-containers")) {
1237
+ if (runDocker === undefined) {
1238
+ failed(actionSubject(action), noDocker);
1239
+ continue;
1240
+ }
1241
+ const result = await runDocker(["rm", "--force", "--volumes", ...action.ids]);
1242
+ if (result.code !== 0) {
1243
+ failed(actionSubject(action), firstLine(result));
1244
+ continue;
1245
+ }
1246
+ await removeProjectNetworks(action.project === "" ? [] : [action.project], runDocker);
1247
+ done("removed", actionSubject(action));
1248
+ }
1249
+
1250
+ const scratch = agentRoots(inputs).scratchRoot;
1251
+ for (const action of byKind("remove-scratch")) {
1252
+ const subject = actionSubject(action);
1253
+ if (scratch === undefined) {
1254
+ failed(subject, "the scratch root is refused");
1255
+ continue;
1256
+ }
1257
+ let activity: number | undefined;
1287
1258
  try {
1288
- appendLog(tidyLogPath(inputs.home), lines, host.now());
1259
+ activity = entryActivity(action.path);
1289
1260
  } catch (cause) {
1290
- failed(`log ${tidyLogPath(inputs.home)}`, errorMessage(cause));
1261
+ lines.push(`kept ${subject}: ${errorMessage(cause)}`);
1262
+ continue;
1263
+ }
1264
+ if (activity !== undefined && host.now() - activity < SCRATCH_IDLE_MS) {
1265
+ lines.push(`kept ${subject}: active ${hours(host.now() - activity)} h ago`);
1266
+ continue;
1291
1267
  }
1292
- return { locked: false, failures, lines };
1293
- } finally {
1294
- releaseTidyLock(lock);
1268
+ const outcome = removeTemporaryPath(action.path, [scratch], inputs.home);
1269
+ if (outcome.kind === "removed") done("removed", subject);
1270
+ else failed(subject, outcome.reason);
1271
+ }
1272
+
1273
+ try {
1274
+ appendLog(tidyLogPath(inputs.home), lines, host.now());
1275
+ } catch (cause) {
1276
+ failed(`log ${tidyLogPath(inputs.home)}`, errorMessage(cause));
1295
1277
  }
1278
+ return { failures, lines };
1296
1279
  }
@@ -0,0 +1,92 @@
1
+ /**
2
+ * The line grammar of the line-based TOML passes: table header lines, key
3
+ * lines, and the lines that continue a value from an earlier line. The module
4
+ * imports nothing, so `manifests.ts` can read a Codex config without a runtime
5
+ * cycle through `codexToml.ts` and `efforts.ts`.
6
+ */
7
+
8
+ export function isTomlHeaderLine(line: string): boolean {
9
+ return /^[ \t]*\[/.test(line);
10
+ }
11
+
12
+ /** Offset just past the quoted string that starts at `start`, or the line end when it stays open. */
13
+ function skipQuoted(line: string, start: number): number {
14
+ const quote = line[start];
15
+ let offset = start + 1;
16
+ while (offset < line.length) {
17
+ if (quote === '"' && line[offset] === "\\") {
18
+ offset += 2;
19
+ continue;
20
+ }
21
+ if (line[offset] === quote) return offset + 1;
22
+ offset++;
23
+ }
24
+ return offset;
25
+ }
26
+
27
+ /** Offset of the `=` that ends the key on a key line, or undefined for other lines. */
28
+ export function keyValueSeparator(line: string): number | undefined {
29
+ if (/^[ \t]*($|#|\[)/.test(line)) return undefined;
30
+ let offset = 0;
31
+ while (offset < line.length) {
32
+ const char = line[offset]!;
33
+ if (char === "=") return offset;
34
+ offset = char === '"' || char === "'" ? skipQuoted(line, offset) : offset + 1;
35
+ }
36
+ return undefined;
37
+ }
38
+
39
+ /**
40
+ * Mark each line that continues a value opened on an earlier line: the body of
41
+ * a `"""` or `'''` string, or the rest of an array or inline table that spans
42
+ * lines. A marked line is never a table header or a key line.
43
+ */
44
+ export function tomlContinuationLines(lines: ReadonlyArray<string>): Array<boolean> {
45
+ const continuation: Array<boolean> = [];
46
+ let openString: string | undefined;
47
+ let depth = 0;
48
+ const scanValue = (line: string, start: number): void => {
49
+ let offset = start;
50
+ while (offset < line.length) {
51
+ if (openString !== undefined) {
52
+ if (openString === '"""' && line[offset] === "\\") {
53
+ offset += 2;
54
+ } else if (line.startsWith(openString, offset)) {
55
+ // A closing delimiter can carry up to two extra quotes of string content.
56
+ let end = offset + 3;
57
+ while (end < offset + 5 && line[end] === openString[0]) end++;
58
+ offset = end;
59
+ openString = undefined;
60
+ } else {
61
+ offset++;
62
+ }
63
+ continue;
64
+ }
65
+ const char = line[offset]!;
66
+ if (char === "#") return;
67
+ if (line.startsWith('"""', offset) || line.startsWith("'''", offset)) {
68
+ openString = line.slice(offset, offset + 3);
69
+ offset += 3;
70
+ continue;
71
+ }
72
+ if (char === '"' || char === "'") {
73
+ offset = skipQuoted(line, offset);
74
+ continue;
75
+ }
76
+ if (char === "[" || char === "{") depth++;
77
+ else if ((char === "]" || char === "}") && depth > 0) depth--;
78
+ offset++;
79
+ }
80
+ };
81
+ for (const line of lines) {
82
+ if (openString !== undefined || depth > 0) {
83
+ continuation.push(true);
84
+ scanValue(line, 0);
85
+ continue;
86
+ }
87
+ continuation.push(false);
88
+ const separator = keyValueSeparator(line);
89
+ if (separator !== undefined) scanValue(line, separator + 1);
90
+ }
91
+ return continuation;
92
+ }