docks-kit 0.23.0 → 0.24.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 (52) hide show
  1. package/AGENTS.md +19 -20
  2. package/README.md +12 -22
  3. package/cli/docs/command-guards.md +5 -3
  4. package/cli/docs/flags.md +11 -29
  5. package/cli/docs/install.md +1 -1
  6. package/cli/docs/omp-context.md +79 -7
  7. package/cli/docs/omp-models.md +18 -12
  8. package/cli/docs/overview.md +5 -8
  9. package/cli/docs/sync-layers.md +12 -11
  10. package/cli/docs/toolchain.md +4 -4
  11. package/cli/src/argv.ts +0 -4
  12. package/cli/src/argvValidate.ts +2 -9
  13. package/cli/src/commands/docs.ts +2 -2
  14. package/cli/src/commands/omp.ts +1 -1
  15. package/cli/src/commands/scratch.ts +1 -1
  16. package/cli/src/commands/sync.ts +3 -24
  17. package/cli/src/commands/tidy.ts +1 -1
  18. package/cli/src/engine-native/DESIGN.md +21 -31
  19. package/cli/src/engine-native/deps.ts +2 -7
  20. package/cli/src/engine-native/engineCtx.ts +3 -28
  21. package/cli/src/engine-native/index.ts +2 -2
  22. package/cli/src/engine-native/kitDb.ts +21 -37
  23. package/cli/src/engine-native/ompFastMode.ts +1 -1
  24. package/cli/src/engine-native/ompOverlay.ts +1 -1
  25. package/cli/src/engine-native/ompRemovals.ts +24 -3
  26. package/cli/src/engine-native/ompSession.ts +67 -0
  27. package/cli/src/engine-native/ompSync.ts +1 -1
  28. package/cli/src/engine-native/os/posix.ts +0 -1
  29. package/cli/src/engine-native/os/types.ts +0 -4
  30. package/cli/src/engine-native/os/windows.ts +0 -1
  31. package/cli/src/engine-native/parseArgs.ts +1 -61
  32. package/cli/src/engine-native/parseHelp.ts +1 -6
  33. package/cli/src/engine-native/scratch.ts +1 -1
  34. package/cli/src/engine-native/sharedTypes.d.ts +1 -1
  35. package/cli/src/engine-native/syncConcurrency.ts +3 -3
  36. package/cli/src/engine-native/syncDispatch.ts +26 -92
  37. package/cli/src/engine-native/toolchain.ts +1 -5
  38. package/cli/src/generated/sotPayload.ts +6 -8
  39. package/cli/src/main.ts +3 -7
  40. package/package.json +2 -2
  41. package/cli/src/checklistPrompt.ts +0 -464
  42. package/cli/src/commands/harnesses.ts +0 -77
  43. package/cli/src/commands/skills.ts +0 -40
  44. package/cli/src/engine-native/harnesses.ts +0 -138
  45. package/cli/src/engine-native/skillsInstall.ts +0 -135
  46. package/cli/src/engine-native/skillsLinks.ts +0 -216
  47. package/cli/src/engine-native/skillsManifest.ts +0 -36
  48. package/cli/src/engine-native/skillsPrune.ts +0 -117
  49. package/cli/src/engine-native/skillsRecords.ts +0 -138
  50. package/cli/src/engine-native/skillsSync.ts +0 -57
  51. package/cli/src/manifests.ts +0 -53
  52. package/cli/src/terminalCells.ts +0 -191
@@ -5,8 +5,6 @@
5
5
  */
6
6
 
7
7
  export type PlatformName = "linux" | "darwin" | "windows" | "unknown";
8
- /** Directory-link mechanisms, tried in order before the copy fallback. */
9
- export type DirectoryLinkKind = "symlink" | "junction";
10
8
  /** Tools whose install command differs per host OS. */
11
9
  export type HintedTool = "git" | "jq" | "curl";
12
10
 
@@ -29,8 +27,6 @@ export interface HostOs {
29
27
  readonly id: PlatformName;
30
28
  /** `SoT/toolchain.json` `os` field this host matches; "" matches every row. */
31
29
  readonly toolchainOs: string;
32
- /** Directory-link mechanisms tried in order before `skillsLinks.ts linkOrCopy` copies. */
33
- readonly directoryLinkKinds: ReadonlyArray<DirectoryLinkKind>;
34
30
  /** One-line install command for a tool whose package differs per OS. */
35
31
  readonly installHint: (tool: HintedTool) => string;
36
32
  /** Filename suffixes tried in order when resolving a bare tool name on PATH. */
@@ -92,7 +92,6 @@ function commandShimInvocation(executablePath: string, args: ReadonlyArray<strin
92
92
  export const windows: HostOs = {
93
93
  id: "windows",
94
94
  toolchainOs: "windows",
95
- directoryLinkKinds: ["symlink", "junction"],
96
95
  executableSuffixes: [".exe", ".cmd", ".bat", ""],
97
96
  invoke: (executablePath, args) =>
98
97
  /\.(?:cmd|bat)$/i.test(executablePath)
@@ -1,84 +1,26 @@
1
1
  /**
2
- * EngineNative flag layer: target selection and the argv dispatch loop.
2
+ * EngineNative flag layer: the argv dispatch loop of `docks-kit sync`.
3
3
  * Help text and the early-exit error live in parseHelp.ts (re-exported here
4
4
  * so existing `from "./parseArgs"` imports keep working).
5
5
  */
6
6
  import type { Ctx } from "./index";
7
- import { DEFAULT_SELECTION, readHarnessSelection, type Harness } from "./harnesses";
8
7
  import { ExitError, printUsage } from "./parseHelp";
9
8
 
10
9
  export { ExitError } from "./parseHelp";
11
10
 
12
- type TargetFlag = "syncAgents" | "syncOmp";
13
-
14
- const TARGET_FLAGS = {
15
- agents: "syncAgents",
16
- omp: "syncOmp",
17
- } satisfies Record<Harness, TargetFlag>;
18
-
19
- /**
20
- * The rename hint for each retired sync flag. The engine prints it here, and
21
- * the public CLI layer (`argvValidate.ts`) rejects the same flag with the same
22
- * text, so the two paths cannot drift.
23
- */
24
- export const LEGACY_FLAG_HINTS = {
25
- "--agents": "--agents was renamed: pass the target as a word, e.g. 'sync agents'",
26
- "--omp": "--omp was renamed: pass the target as a word, e.g. 'sync omp'",
27
- "--remove-plugins": "--remove-plugins was renamed to --prune",
28
- } as const satisfies Record<string, string>;
29
-
30
- type LegacyFlag = keyof typeof LEGACY_FLAG_HINTS;
31
-
32
- /** Own-key check, so a word such as `constructor` never reads an Object prototype member. */
33
- export const isLegacyFlag = (flag: string): flag is LegacyFlag =>
34
- Object.hasOwn(LEGACY_FLAG_HINTS, flag);
35
-
36
- function selectTarget(ctx: Ctx, target: Harness): void {
37
- ctx[TARGET_FLAGS[target]] = true;
38
- ctx.targetFilterSet = true;
39
- }
40
-
41
- function applySelection(ctx: Ctx, selection: ReadonlyArray<Harness>): void {
42
- ctx.syncAgents = selection.includes("agents");
43
- ctx.syncOmp = selection.includes("omp");
44
- }
45
-
46
- function applyDefaultSelection(ctx: Ctx): void {
47
- if (ctx.targetFilterSet) return;
48
-
49
- const storedSelection = readHarnessSelection(ctx.home);
50
- applySelection(ctx, storedSelection ?? DEFAULT_SELECTION);
51
- if (storedSelection !== undefined || !ctx.interactive) return;
52
-
53
- ctx.services.logger.echo(`No harness selection stored; syncing ${DEFAULT_SELECTION.join(", ")}`);
54
- ctx.services.logger.echo("Choose harnesses with: docks-kit harnesses");
55
- }
56
-
57
11
  export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
58
12
  const { err } = ctx.services.logger;
59
13
  for (const arg of args) {
60
14
  switch (arg) {
61
- case "agents":
62
- case "omp":
63
- selectTarget(ctx, arg);
64
- continue;
65
15
  case "--dry-run":
66
16
  ctx.dryRun = true;
67
17
  continue;
68
18
  case "--skip-plugin-refresh":
69
19
  ctx.skipPluginRefresh = true;
70
20
  continue;
71
- case "--prune":
72
- ctx.prune = true;
73
- continue;
74
21
  case "--verbose":
75
22
  ctx.verbose = true;
76
23
  continue;
77
- case "--agents":
78
- case "--omp":
79
- case "--remove-plugins":
80
- err(LEGACY_FLAG_HINTS[arg]);
81
- throw new ExitError(2);
82
24
  case "-h":
83
25
  case "--help":
84
26
  printUsage(ctx);
@@ -88,6 +30,4 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
88
30
  throw new ExitError(2);
89
31
  }
90
32
  }
91
-
92
- applyDefaultSelection(ctx);
93
33
  }
@@ -15,15 +15,10 @@ export class ExitError extends Error {
15
15
  export function printUsage(ctx: Ctx): void {
16
16
  const { echo } = ctx.services.logger;
17
17
  const argv0 = "docks-kit sync";
18
- echo(`Usage: ${argv0} [agents] [omp] [flags]`);
19
- echo("");
20
- echo("Targets (positional; default: this machine's harness selection)");
21
- echo(" agents sync universal agent skills");
22
- echo(" omp sync the Oh My Pi SoT");
18
+ echo(`Usage: ${argv0} [flags]`);
23
19
  echo("");
24
20
  echo("Global flags");
25
21
  echo(" --dry-run preview without applying");
26
- echo(" --prune remove kit-managed universal skills not in SoT/.agents/skills.txt");
27
22
  echo(" --skip-plugin-refresh install missing plugins but skip refresh-only updates");
28
23
  echo(
29
24
  " --verbose also print no-op confirmations (already in sync, up to date, left as-is)",
@@ -35,7 +35,7 @@ export function syncLockPath(home: string): string {
35
35
  }
36
36
 
37
37
  /**
38
- * The `kitLock.ts` lock inside an agents or omp folder that a sync
38
+ * The `kitLock.ts` lock inside an omp folder that a sync
39
39
  * writes. Syncs of different homes that share the folder all take it.
40
40
  */
41
41
  export function folderSyncLockPath(folder: string): string {
@@ -9,7 +9,7 @@ import type { Json } from "./jq";
9
9
  export type JsonObject = { [key: string]: Json };
10
10
 
11
11
  /**
12
- * omp session model (moved from harnesses.ts, which re-exports it so existing
12
+ * omp session model (moved from ompSession.ts, which re-exports it so existing
13
13
  * import paths keep working).
14
14
  */
15
15
  export interface OmpSessionModel {
@@ -1,7 +1,7 @@
1
1
  /**
2
- * EngineNative sync scheduling: the bounded-concurrency runner. Split from
3
- * index.ts, which re-exports the public surface so existing import paths keep
4
- * working.
2
+ * EngineNative bounded-concurrency runner, which tidy and the tidy report use
3
+ * for their parallel probes. index.ts re-exports it so existing import paths
4
+ * keep working.
5
5
  */
6
6
 
7
7
  export type SyncConcurrency = 1 | 2 | 3;
@@ -1,11 +1,10 @@
1
1
  /**
2
- * EngineNative pipeline dispatch: select the requested harness pipelines,
3
- * run them under the concurrency cap, then print the summary and advice.
4
- * Split from index.ts; the `sync`/`toolchain` entry routing still lives
5
- * there.
2
+ * EngineNative sync dispatch: take the sync and folder locks, run the omp
3
+ * pipeline, then print the summary and advice. Split from index.ts; the
4
+ * `sync`/`toolchain` entry routing still lives there.
6
5
  */
7
6
  import { existsSync, mkdirSync, realpathSync } from "node:fs";
8
- import { basename, dirname, join, resolve } from "node:path";
7
+ import { basename, dirname, join } from "node:path";
9
8
 
10
9
  import type { Ctx } from "./index";
11
10
  import { compareCodepoints } from "./jq";
@@ -18,10 +17,8 @@ import {
18
17
  type OmpState,
19
18
  type OmpWriteFolders,
20
19
  } from "./ompSync";
21
- import { skillsNextSteps, skillsSummary, skillsSync, type SkillsState } from "./skillsSync";
22
20
  import { ExitError, parseArgs } from "./parseArgs";
23
21
  import { folderSyncLockPath, syncLockPath } from "./scratch";
24
- import { runBounded, type SyncConcurrency, type SyncTask } from "./syncConcurrency";
25
22
 
26
23
  /** The default time that a sync waits for another sync to release the sync lock. */
27
24
  export const SYNC_LOCK_WAIT_MS = 120_000;
@@ -48,9 +45,8 @@ function syncLockWaitMs(err: ErrorSink): number {
48
45
 
49
46
  /**
50
47
  * The tokens that skip the sync lock. `-h` and `--help` make `parseArgs`
51
- * print the usage or an error and exit before it reads `kit.db`. A
52
- * `--dry-run` sync writes no kit file except a `kit.db` migration, which
53
- * `kitDb.ts` makes safe for parallel runs.
48
+ * print the usage or an error and exit before the sync writes a file. A
49
+ * `--dry-run` sync writes no kit file.
54
50
  */
55
51
  const UNLOCKED_TOKENS: Record<string, true> = { "--dry-run": true, "-h": true, "--help": true };
56
52
 
@@ -133,8 +129,8 @@ export function folderLockPaths(folders: ReadonlyArray<string>): Array<string> {
133
129
 
134
130
  /**
135
131
  * Run `body` under the folder lock of each folder in `folders`. Take it after
136
- * the sync lock. Syncs of different homes can share an agents or omp
137
- * folder, and their home locks differ. A missing folder is created under the
132
+ * the sync lock. Syncs of different homes can share an omp folder, and
133
+ * their home locks differ. A missing folder is created under the
138
134
  * locks of its ancestors in the set. A dry run takes no folder lock and
139
135
  * creates nothing.
140
136
  */
@@ -164,113 +160,51 @@ export async function withHomeAndFolderLocks(
164
160
  }
165
161
 
166
162
  /**
167
- * Run a sync. The sync lock comes first: `parseArgs` reads the harness
168
- * selection from `kit.db`, and that read can migrate `kit.db` and rename a
169
- * legacy `state.json`. The folder locks come after `parseArgs` selects the
170
- * targets.
163
+ * Run a sync. The sync lock comes first, then the folder locks of the omp
164
+ * folders, which `runSync` resolves after `parseArgs` reads the flags.
171
165
  */
172
166
  export async function engineSync(ctx: Ctx, args: ReadonlyArray<string>): Promise<number> {
173
167
  return await withSyncLock(ctx, args, () => runSync(ctx, args));
174
168
  }
175
169
 
176
170
  async function runSync(ctx: Ctx, args: ReadonlyArray<string>): Promise<number> {
177
- const { err } = ctx.services.logger;
178
171
  parseArgs(ctx, args);
179
- const configuredConcurrency = process.env["DOCKS_KIT_SYNC_CONCURRENCY"];
180
- if (configuredConcurrency === undefined || configuredConcurrency === "") {
181
- ctx.syncConcurrency = 3;
182
- } else if (
183
- configuredConcurrency === "1" ||
184
- configuredConcurrency === "2" ||
185
- configuredConcurrency === "3"
186
- ) {
187
- ctx.syncConcurrency = Number(configuredConcurrency) as SyncConcurrency;
188
- } else {
189
- err("DOCKS_KIT_SYNC_CONCURRENCY must be 1, 2, or 3");
190
- throw new ExitError(2);
191
- }
192
-
193
- // The folders that hold ownership records or omp files. A writing pipeline
194
- // creates its folders anyway, so `withFolderLocks` creates each missing one
195
- // under the locks of its ancestors in the set. The omp folders are resolved
196
- // once, here: the omp pipeline and its omp children use these paths, so a
197
- // data root that appears after the locks cannot move them.
198
- const omp = ctx.syncOmp ? ompWriteFolders(ctx) : undefined;
199
- const folders = [
200
- ...(ctx.syncAgents ? [resolve(ctx.agentsDir)] : []),
201
- ...(omp === undefined ? [] : [omp.paths.agentDir, omp.intercomDir, omp.paths.dataRoot]),
202
- ];
203
- return await withFolderLocks(ctx, folders, () => runPipelines(ctx, omp));
172
+ // The folders that hold omp files. A writing sync creates its folders
173
+ // anyway, so `withFolderLocks` creates each missing one under the locks of
174
+ // its ancestors in the set. The omp folders are resolved once, here: the
175
+ // omp pipeline and its omp children use these paths, so a data root that
176
+ // appears after the locks cannot move them.
177
+ const omp = ompWriteFolders(ctx);
178
+ const folders = [omp.paths.agentDir, omp.intercomDir, omp.paths.dataRoot];
179
+ return await withFolderLocks(ctx, folders, () => runPipeline(ctx, omp));
204
180
  }
205
181
 
206
- /** Run the selected pipelines. `omp` holds the omp folders when omp is selected. */
207
- async function runPipelines(ctx: Ctx, omp: OmpWriteFolders | undefined): Promise<number> {
182
+ /** Run the omp pipeline in the omp folders `omp`, then print the summary and advice. */
183
+ async function runPipeline(ctx: Ctx, omp: OmpWriteFolders): Promise<number> {
208
184
  const { acquireTerminal, echo } = ctx.services.logger;
209
185
 
210
- type PipelineResult =
211
- | { readonly kind: "skills"; readonly state: SkillsState }
212
- | { readonly kind: "omp"; readonly state: OmpState };
213
- interface SelectedPipeline {
214
- readonly name: string;
215
- readonly run: SyncTask<PipelineResult>;
216
- }
217
-
218
- const selected: Array<SelectedPipeline> = [];
219
- if (ctx.syncAgents) {
220
- selected.push({
221
- name: "skills",
222
- run: async () => ({ kind: "skills", state: await skillsSync(ctx) }),
223
- });
224
- }
225
- if (omp !== undefined) {
226
- selected.push({
227
- name: "omp",
228
- run: async () => ({ kind: "omp", state: await ompSync(ctx, omp) }),
229
- });
230
- }
231
-
232
- const remaining = new Set(selected.map(({ name }) => name));
233
- const lease = acquireTerminal(`Syncing ${[...remaining].join(", ")}...`);
186
+ const lease = acquireTerminal("Syncing omp...");
234
187
  ctx.terminalLease = lease;
235
- const tasks = selected.map(({ name, run }): SyncTask<PipelineResult> => async () => {
236
- try {
237
- return await run();
238
- } finally {
239
- remaining.delete(name);
240
- if (remaining.size > 0) lease.update(`Syncing ${[...remaining].join(", ")}...`);
241
- }
242
- });
243
- let results: Array<PipelineResult>;
188
+ let ompState: OmpState;
244
189
  try {
245
190
  try {
246
- results = await runBounded(tasks, ctx.syncConcurrency);
191
+ ompState = await ompSync(ctx, omp);
247
192
  } finally {
248
193
  lease.release();
249
194
  ctx.terminalLease = undefined;
250
195
  }
251
196
  } catch (error) {
252
- // A rejected pipeline skips the summary. Print the failures that the other pipelines recorded.
197
+ // A rejected pipeline skips the summary. Print the failures that it recorded before it stopped.
253
198
  printFailures(ctx);
254
199
  throw error;
255
200
  }
256
201
 
257
- let skillsState: SkillsState | undefined;
258
- let ompState: OmpState | undefined;
259
- for (const result of results) {
260
- if (result.kind === "skills") skillsState = result.state;
261
- else ompState = result.state;
262
- }
263
-
264
202
  echo("");
265
203
  echo("--- Sync complete ---");
266
204
  echo(`Repo: ${ctx.repoDir}`);
267
- if (skillsState !== undefined) skillsSummary(ctx, skillsState);
268
- if (ompState !== undefined) ompSummary(ctx, ompState);
205
+ ompSummary(ctx, ompState);
269
206
 
270
- const advice = [
271
- ...(skillsState !== undefined ? skillsNextSteps(ctx) : []),
272
- ...(ompState !== undefined ? ompNextSteps(ctx) : []),
273
- ];
207
+ const advice = ompNextSteps(ctx);
274
208
  if (advice.length > 0) {
275
209
  echo("");
276
210
  for (const line of advice) echo(line);
@@ -59,8 +59,6 @@ export async function installedVersion(ctx: Ctx, tool: ToolId): Promise<string>
59
59
  switch (tool) {
60
60
  case "git":
61
61
  return firstLineField(await version(), 2);
62
- case "node":
63
- return (await version()).replace(/^v/, "");
64
62
  case "jq":
65
63
  return (await version()).replace(/^jq-/, "");
66
64
  case "curl":
@@ -93,9 +91,7 @@ export async function report(ctx: Ctx): Promise<void> {
93
91
  const dash = (v: string): string => (v !== "" ? v : "-");
94
92
  if (kind === "pin") {
95
93
  const via = field(tool, "via");
96
- echo(
97
- row([tool, kind, `(${via !== "" ? via : "npx"})`, dash(floor), dash(verified), "pinned"]),
98
- );
94
+ echo(row([tool, kind, `(${via})`, dash(floor), dash(verified), "pinned"]));
99
95
  continue;
100
96
  }
101
97
  let installed: string;