docks-kit 0.20.5 → 0.20.8

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 (72) hide show
  1. package/AGENTS.md +19 -17
  2. package/README.md +17 -6
  3. package/cli/docs/command-guards.md +269 -0
  4. package/cli/docs/install.md +23 -12
  5. package/cli/docs/models.md +3 -2
  6. package/cli/docs/modifiers.md +4 -3
  7. package/cli/docs/omp-context.md +9 -2
  8. package/cli/docs/omp-models.md +61 -31
  9. package/cli/docs/plugins.md +12 -7
  10. package/cli/docs/sync-layers.md +26 -9
  11. package/cli/docs/toolchain.md +7 -4
  12. package/cli/src/argv.ts +2 -0
  13. package/cli/src/argvSurface.ts +23 -0
  14. package/cli/src/argvValidate.ts +3 -3
  15. package/cli/src/commands/docs.ts +6 -1
  16. package/cli/src/commands/harnesses.ts +15 -4
  17. package/cli/src/commands/omp.ts +92 -41
  18. package/cli/src/commands/status.ts +15 -0
  19. package/cli/src/commands/sync.ts +6 -6
  20. package/cli/src/commands/toolchain.ts +8 -2
  21. package/cli/src/commands/update.ts +51 -10
  22. package/cli/src/engine-native/DESIGN.md +56 -35
  23. package/cli/src/engine-native/atomicWrite.ts +64 -0
  24. package/cli/src/engine-native/claudeLsp.ts +9 -2
  25. package/cli/src/engine-native/claudeOptionalPlugins.ts +19 -6
  26. package/cli/src/engine-native/claudePluginPasses.ts +77 -21
  27. package/cli/src/engine-native/claudeRemovals.ts +245 -57
  28. package/cli/src/engine-native/claudeRetired.ts +1 -1
  29. package/cli/src/engine-native/claudeSettings.ts +46 -19
  30. package/cli/src/engine-native/claudeSettingsModifiers.ts +3 -3
  31. package/cli/src/engine-native/claudeSync.ts +18 -16
  32. package/cli/src/engine-native/codexConfig.ts +72 -12
  33. package/cli/src/engine-native/codexHooks.ts +3 -3
  34. package/cli/src/engine-native/codexPaths.ts +14 -0
  35. package/cli/src/engine-native/codexPlugins.ts +48 -23
  36. package/cli/src/engine-native/codexStatus.ts +2 -1
  37. package/cli/src/engine-native/codexSync.ts +33 -7
  38. package/cli/src/engine-native/codexToml.ts +161 -35
  39. package/cli/src/engine-native/deps.ts +4 -9
  40. package/cli/src/engine-native/engineCtx.ts +42 -14
  41. package/cli/src/engine-native/exec.ts +28 -1
  42. package/cli/src/engine-native/harnesses.ts +32 -8
  43. package/cli/src/engine-native/index.ts +6 -1
  44. package/cli/src/engine-native/kitDb.ts +12 -6
  45. package/cli/src/engine-native/liveModels.ts +2 -1
  46. package/cli/src/engine-native/models.ts +6 -3
  47. package/cli/src/engine-native/modes.ts +15 -10
  48. package/cli/src/engine-native/ompFileDeploy.ts +3 -4
  49. package/cli/src/engine-native/ompMarketplace.ts +9 -7
  50. package/cli/src/engine-native/ompOverlay.ts +39 -13
  51. package/cli/src/engine-native/ompPaths.ts +20 -9
  52. package/cli/src/engine-native/ompPlugins.ts +16 -15
  53. package/cli/src/engine-native/ompSync.ts +11 -6
  54. package/cli/src/engine-native/ompYaml.ts +91 -6
  55. package/cli/src/engine-native/os/darwin.ts +2 -0
  56. package/cli/src/engine-native/os/linux.ts +1 -0
  57. package/cli/src/engine-native/os/posix.ts +17 -5
  58. package/cli/src/engine-native/os/types.ts +2 -2
  59. package/cli/src/engine-native/os/windows.ts +24 -16
  60. package/cli/src/engine-native/skillsInstall.ts +10 -5
  61. package/cli/src/engine-native/skillsLinks.ts +14 -1
  62. package/cli/src/engine-native/skillsManifest.ts +20 -0
  63. package/cli/src/engine-native/skillsPrune.ts +33 -26
  64. package/cli/src/engine-native/skillsSync.ts +6 -3
  65. package/cli/src/engine-native/syncDispatch.ts +32 -18
  66. package/cli/src/engine.ts +29 -3
  67. package/cli/src/generated/sotPayload.ts +14 -14
  68. package/cli/src/main.ts +10 -3
  69. package/cli/src/manifests.ts +29 -11
  70. package/docks-kit +6 -3
  71. package/docks-kit.ps1 +22 -11
  72. package/package.json +1 -1
@@ -1,13 +1,13 @@
1
1
  /**
2
2
  * EngineNative universal-skill install pass (`npx skills@<pin> add`) with
3
3
  * Claude symlink healing. Split from skillsSync.ts; the orchestration still
4
- * lives there. The prune pass (skillsPrune.ts) shares `skillsCli`.
4
+ * lives there.
5
5
  */
6
6
  import { p, spawnProcess } from "./exec";
7
7
  import type { Ctx } from "./index";
8
8
  import { ExitError } from "./parseArgs";
9
9
  import { healClaudeSymlink, isDir } from "./skillsLinks";
10
- import { normalizeManifest } from "./skillsManifest";
10
+ import { normalizeManifest, skillBase } from "./skillsManifest";
11
11
  import { field } from "./toolchain";
12
12
 
13
13
  export interface SkillsState {
@@ -15,7 +15,7 @@ export interface SkillsState {
15
15
  }
16
16
 
17
17
  /** skills::_skills_cli — the pinned npx package spec. */
18
- export function skillsCli(ctx: Ctx): string {
18
+ function skillsCli(ctx: Ctx): string {
19
19
  const version = field("skills-cli", "verified");
20
20
  if (version !== "") return `skills@${version}`;
21
21
  ctx.services.logger.err(
@@ -46,7 +46,7 @@ export async function syncUniversal(
46
46
  let healed = 0;
47
47
 
48
48
  for (const slug of normalizeManifest(manifest)) {
49
- const base = slug.slice(slug.lastIndexOf("/") + 1);
49
+ const base = skillBase(slug);
50
50
 
51
51
  if (ctx.dryRun) {
52
52
  if (isDir(p(skillsDir, base))) {
@@ -75,6 +75,11 @@ export async function syncUniversal(
75
75
  clearProgress();
76
76
  if (res.error === undefined && res.exitCode === 0) {
77
77
  added++;
78
+ if (!isDir(p(skillsDir, base))) {
79
+ warn(
80
+ `Installed skill name differs from slug ${slug}; declare it as <owner>/<repo>@<skill-name>`,
81
+ );
82
+ }
78
83
  } else {
79
84
  warn(`Failed to install universal skill: ${slug}`);
80
85
  failed++;
@@ -99,7 +104,7 @@ export async function syncUniversal(
99
104
  }
100
105
  if (failed > 0) {
101
106
  warn(
102
- `${failed} skill install(s) failed — re-run sync or install manually with: npx skills add <slug> -g -y -a claude-code codex`,
107
+ `${failed} skill install(s) failed — re-run sync or install manually with: npx --yes ${skillsCli(ctx)} add <slug> -g -y -a claude-code codex`,
103
108
  );
104
109
  }
105
110
  }
@@ -10,6 +10,7 @@ import {
10
10
  lstatSync,
11
11
  mkdirSync,
12
12
  readlinkSync,
13
+ realpathSync,
13
14
  rmSync,
14
15
  statSync,
15
16
  symlinkSync,
@@ -47,7 +48,7 @@ export function healClaudeSymlink(ctx: Ctx, skillsDir: string, base: string): bo
47
48
  const linkStat = lstat(claudeLink);
48
49
  if (linkStat?.isSymbolicLink() === true) {
49
50
  const current = safeReadlink(claudeLink);
50
- if (current === relTarget) return false;
51
+ if (current === relTarget || pointsAt(claudeLink, canonical)) return false;
51
52
  if (ctx.dryRun) {
52
53
  echo(
53
54
  `[dry-run] would replace stale Claude symlink: ~/.claude/skills/${base} -> ${current} (correct: ${relTarget})`,
@@ -134,6 +135,18 @@ function safeReadlink(path: string): string {
134
135
  }
135
136
  }
136
137
 
138
+ /**
139
+ * True when `link` resolves to `target`. A junction stores an absolute target,
140
+ * so the link text never equals the relative form that a symlink uses.
141
+ */
142
+ function pointsAt(link: string, target: string): boolean {
143
+ try {
144
+ return realpathSync.native(link) === realpathSync.native(target);
145
+ } catch {
146
+ return false;
147
+ }
148
+ }
149
+
137
150
  /** Remove a symlink without touching a real directory. */
138
151
  export function removeLink(path: string): boolean {
139
152
  try {
@@ -14,3 +14,23 @@ export function normalizeManifest(content: string): Array<string> {
14
14
  }
15
15
  return out;
16
16
  }
17
+
18
+ /**
19
+ * The directory the skills CLI installs for a manifest slug. The CLI names a
20
+ * skill directory after the skill. It reads `@<skill>` only in the
21
+ * `<owner>/<repo>@<skill>` form (skills@1.7.0 parseSource), so an `@` in a local
22
+ * path or URL stays part of the name. Any other slug means one skill named after
23
+ * its last path segment. The name goes through the CLI's `sanitizeName` rule.
24
+ */
25
+ export function skillBase(slug: string): string {
26
+ const selector = /^[^/]+\/[^/@]+@(.+)$/.exec(slug)?.[1];
27
+ const nativeForm = !slug.includes(":") && !slug.startsWith(".") && !slug.startsWith("/");
28
+ const name =
29
+ selector !== undefined && nativeForm ? selector : slug.slice(slug.lastIndexOf("/") + 1);
30
+ const sanitized = name
31
+ .toLowerCase()
32
+ .replace(/[^a-z0-9._]+/g, "-")
33
+ .replace(/^[.-]+|[.-]+$/g, "")
34
+ .slice(0, 255);
35
+ return sanitized === "" ? "unnamed-skill" : sanitized;
36
+ }
@@ -2,27 +2,35 @@
2
2
  * EngineNative kit-managed skill prune (`--prune` reconcile against the
3
3
  * snapshot) and snapshot write. Split from skillsSync.ts; the orchestration
4
4
  * still lives there.
5
+ *
6
+ * The prune deletes only what the kit created: the canonical skill directory
7
+ * and the kit-managed Claude entry. It does not call `skills remove`, because
8
+ * that command deletes the same-named directory of every known agent.
5
9
  */
6
- import { existsSync, mkdirSync, readFileSync } from "node:fs";
7
- import { p, spawnProcess, writeTextIfChanged } from "./exec";
10
+ import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
11
+ import { p, writeTextIfChanged } from "./exec";
8
12
  import type { Ctx } from "./index";
9
13
  import { compareCodepoints } from "./jq";
10
- import { skillsCli } from "./skillsInstall";
11
14
  import { isKitOwnedCopy, lstat, removeKitOwnedCopy, removeLink } from "./skillsLinks";
12
- import { normalizeManifest } from "./skillsManifest";
15
+ import { normalizeManifest, skillBase } from "./skillsManifest";
13
16
 
14
17
  // ----------------------------------------------------- prune + snapshot ----
15
18
 
16
- function readSlugs(file: string): Array<string> {
19
+ export function readSlugs(file: string): Array<string> {
17
20
  return existsSync(file) ? normalizeManifest(readFileSync(file, "utf8")) : [];
18
21
  }
19
22
 
20
- export async function reconcileRemovals(
21
- ctx: Ctx,
22
- manifest: string,
23
- snapshot: string,
24
- ): Promise<Array<string>> {
25
- const { change, clearProgress, echo, progress, warn } = ctx.services.logger;
23
+ function removeCanonical(path: string): boolean {
24
+ try {
25
+ rmSync(path, { recursive: true, force: true });
26
+ return true;
27
+ } catch {
28
+ return lstat(path) === undefined;
29
+ }
30
+ }
31
+
32
+ export function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): Array<string> {
33
+ const { change, echo, warn } = ctx.services.logger;
26
34
  if (!existsSync(snapshot)) {
27
35
  if (ctx.dryRun) {
28
36
  echo(
@@ -33,14 +41,18 @@ export async function reconcileRemovals(
33
41
  }
34
42
 
35
43
  const current = normalizeManifest(manifest);
36
- const currentBases = new Set(current.map((slug) => slug.slice(slug.lastIndexOf("/") + 1)));
44
+ const currentBases = new Set(current.map(skillBase));
37
45
  let removed = 0;
38
46
  let failed = 0;
39
47
  const failedSlugs: Array<string> = [];
40
48
  for (const slug of readSlugs(snapshot)) {
41
49
  if (current.includes(slug)) continue;
42
- const base = slug.slice(slug.lastIndexOf("/") + 1);
50
+ const base = skillBase(slug);
43
51
  if (currentBases.has(base)) continue;
52
+ const canonical = p(ctx.agentsDir, "skills", base);
53
+ // The skills CLI installs a canonical skill as a real directory that holds SKILL.md.
54
+ const installedCanonical =
55
+ lstat(canonical)?.isDirectory() === true && existsSync(p(canonical, "SKILL.md"));
44
56
  const claudeEntry = p(ctx.home, ".claude", "skills", base);
45
57
  const managedClaudeEntry =
46
58
  lstat(claudeEntry)?.isSymbolicLink() === true || isKitOwnedCopy(claudeEntry);
@@ -51,16 +63,7 @@ export async function reconcileRemovals(
51
63
  }
52
64
  continue;
53
65
  }
54
- progress(`Removing universal skill ${base}...`);
55
- const res = await spawnProcess(
56
- "npx",
57
- ["--yes", skillsCli(ctx), "remove", "--global", base, "-y"],
58
- {
59
- stdio: "ignore",
60
- },
61
- );
62
- clearProgress();
63
- if (res.error !== undefined || res.exitCode !== 0) {
66
+ if (installedCanonical && !removeCanonical(canonical)) {
64
67
  warn(`Failed to remove kit-managed skill: ${base}`);
65
68
  failed++;
66
69
  failedSlugs.push(slug);
@@ -87,21 +90,25 @@ export async function reconcileRemovals(
87
90
  }
88
91
  if (failed > 0)
89
92
  warn(
90
- `${failed} skill remove(s) failed — re-run with --prune or run: npx skills remove --global <name> -y`,
93
+ `${failed} skill remove(s) failed — re-run with --prune, or delete ~/.agents/skills/<name> and the ~/.claude/skills/<name> link manually`,
91
94
  );
92
95
  return failedSlugs;
93
96
  }
94
97
 
98
+ /**
99
+ * Writes the declared slugs plus `retainedSlugs`. A slug leaves the snapshot
100
+ * only after a successful --prune removes it.
101
+ */
95
102
  export function updateSnapshot(
96
103
  ctx: Ctx,
97
104
  manifest: string,
98
105
  snapshot: string,
99
- failedRemovals: ReadonlyArray<string>,
106
+ retainedSlugs: ReadonlyArray<string>,
100
107
  ): void {
101
108
  if (ctx.dryRun) return;
102
109
 
103
110
  mkdirSync(ctx.agentsDir, { recursive: true });
104
- const sorted = [...new Set([...normalizeManifest(manifest), ...failedRemovals])].sort(
111
+ const sorted = [...new Set([...normalizeManifest(manifest), ...retainedSlugs])].sort(
105
112
  compareCodepoints,
106
113
  );
107
114
  writeTextIfChanged(snapshot, sorted.length > 0 ? `${sorted.join("\n")}\n` : "");
@@ -14,7 +14,7 @@ import { payloadText } from "../payload";
14
14
  import { p } from "./exec";
15
15
  import type { Ctx } from "./index";
16
16
  import { syncUniversal, type SkillsState } from "./skillsInstall";
17
- import { reconcileRemovals, updateSnapshot } from "./skillsPrune";
17
+ import { readSlugs, reconcileRemovals, updateSnapshot } from "./skillsPrune";
18
18
 
19
19
  export type { SkillsState } from "./skillsInstall";
20
20
  export { COPY_MARKER, linkOrCopy, type LinkOutcome } from "./skillsLinks";
@@ -29,8 +29,11 @@ export async function skillsSync(ctx: Ctx): Promise<SkillsState> {
29
29
  if (!ctx.dryRun) mkdirSync(skillsDir, { recursive: true });
30
30
 
31
31
  await syncUniversal(ctx, state, skillsDir, manifest);
32
- const failedRemovals = ctx.prune ? await reconcileRemovals(ctx, manifest, snapshot) : [];
33
- updateSnapshot(ctx, manifest, snapshot, failedRemovals);
32
+ // A tracked slug leaves the snapshot only after a successful --prune removes it.
33
+ const retainedSlugs = ctx.prune
34
+ ? reconcileRemovals(ctx, manifest, snapshot)
35
+ : readSlugs(snapshot);
36
+ updateSnapshot(ctx, manifest, snapshot, retainedSlugs);
34
37
  return state;
35
38
  }
36
39
 
@@ -6,6 +6,7 @@
6
6
  */
7
7
  import { payloadText } from "../payload";
8
8
  import { claudeNextSteps, claudeSummary, claudeSync, type ClaudeRuntimeState } from "./claudeSync";
9
+ import { preflightClaudeSettings } from "./claudeSettings";
9
10
  import { codexNextSteps, codexSummary, codexSync } from "./codexSync";
10
11
  import type { Ctx } from "./index";
11
12
  import { ompNextSteps, ompSummary, ompSync, type OmpState } from "./ompSync";
@@ -35,6 +36,8 @@ export async function engineSync(ctx: Ctx, args: ReadonlyArray<string>): Promise
35
36
  err("DOCKS_KIT_SYNC_CONCURRENCY must be 1, 2, or 3");
36
37
  throw new ExitError(2);
37
38
  }
39
+ // An abort-class check runs before any pipeline starts, so the abort stops the whole sync.
40
+ preflightClaudeSettings(ctx);
38
41
 
39
42
  type PipelineResult =
40
43
  | { readonly kind: "claude"; readonly runtime: ClaudeRuntimeState }
@@ -86,20 +89,26 @@ export async function engineSync(ctx: Ctx, args: ReadonlyArray<string>): Promise
86
89
  const remaining = new Set(selected.map(({ name }) => name));
87
90
  const lease = acquireTerminal(`Syncing ${[...remaining].join(", ")}...`);
88
91
  ctx.terminalLease = lease;
92
+ const tasks = selected.map(({ name, run }): SyncTask<PipelineResult> => async () => {
93
+ try {
94
+ return await run();
95
+ } finally {
96
+ remaining.delete(name);
97
+ if (remaining.size > 0) lease.update(`Syncing ${[...remaining].join(", ")}...`);
98
+ }
99
+ });
89
100
  let results: Array<PipelineResult>;
90
101
  try {
91
- const tasks = selected.map(({ name, run }): SyncTask<PipelineResult> => async () => {
92
- try {
93
- return await run();
94
- } finally {
95
- remaining.delete(name);
96
- if (remaining.size > 0) lease.update(`Syncing ${[...remaining].join(", ")}...`);
97
- }
98
- });
99
- results = await runBounded(tasks, ctx.syncConcurrency);
100
- } finally {
101
- lease.release();
102
- ctx.terminalLease = undefined;
102
+ try {
103
+ results = await runBounded(tasks, ctx.syncConcurrency);
104
+ } finally {
105
+ lease.release();
106
+ ctx.terminalLease = undefined;
107
+ }
108
+ } catch (error) {
109
+ // A rejected pipeline skips the summary. Print the failures that the other pipelines recorded.
110
+ printFailures(ctx);
111
+ throw error;
103
112
  }
104
113
 
105
114
  const claudeRan = ctx.syncClaude;
@@ -131,11 +140,16 @@ export async function engineSync(ctx: Ctx, args: ReadonlyArray<string>): Promise
131
140
  echo("");
132
141
  for (const line of advice) echo(line);
133
142
  }
134
- if (ctx.failures.length > 0) {
135
- echo("");
136
- echo("--- Failures ---");
137
- for (const failure of ctx.failures) echo(`- ${failure}`);
138
- return 1;
139
- }
143
+ if (printFailures(ctx)) return 1;
140
144
  return 0;
141
145
  }
146
+
147
+ /** Print the `--- Failures ---` ledger. Returns true when the ledger has entries. */
148
+ function printFailures(ctx: Ctx): boolean {
149
+ const { echo } = ctx.services.logger;
150
+ if (ctx.failures.length === 0) return false;
151
+ echo("");
152
+ echo("--- Failures ---");
153
+ for (const failure of ctx.failures) echo(`- ${failure}`);
154
+ return true;
155
+ }
package/cli/src/engine.ts CHANGED
@@ -2,6 +2,7 @@ import { CliError } from "effect/unstable/cli";
2
2
  import { Console, Effect } from "effect";
3
3
  import { spawnSync } from "node:child_process";
4
4
  import { runEngineNative } from "./engine-native";
5
+ import { ENV_GLOBAL_KEYS } from "./engine-native/engineCtx";
5
6
  import { ExitError } from "./engine-native/parseArgs";
6
7
  import { makeEngineServices } from "./engine-native/services";
7
8
  import { targetForHost } from "./engine-native/os/targets";
@@ -57,7 +58,7 @@ export const engine = (args: ReadonlyArray<string>) =>
57
58
  const deps = yield* DependencyManagerService;
58
59
  const platform = yield* PlatformService;
59
60
  const code = yield* Effect.tryPromise({
60
- try: () => runEngineNative(args, { logger, deps, platform }),
61
+ try: () => runEngineNative(args, { logger, deps, platform }, { envGlobals: false }),
61
62
  catch: (error) =>
62
63
  new CliError.UserError({
63
64
  cause: error,
@@ -69,6 +70,27 @@ export const engine = (args: ReadonlyArray<string>) =>
69
70
  }
70
71
  });
71
72
 
73
+ // The capture child must not inherit the env globals or a caller's channel
74
+ // selection in any spelling.
75
+ const CAPTURE_DROPPED_KEYS: ReadonlyArray<string> = [...ENV_GLOBAL_KEYS, "DOCKS_KIT_ENGINE"];
76
+
77
+ /**
78
+ * Build the capture child environment. Windows environment names are
79
+ * case-insensitive, so a key such as `claude_compact_window` also matches
80
+ * there. POSIX names stay case-sensitive.
81
+ */
82
+ const captureChildEnv = (): NodeJS.ProcessEnv => {
83
+ const foldCase = process.platform === "win32";
84
+ const env: NodeJS.ProcessEnv = {};
85
+ for (const [name, value] of Object.entries(process.env)) {
86
+ if (value === undefined) continue;
87
+ if (CAPTURE_DROPPED_KEYS.includes(foldCase ? name.toUpperCase() : name)) continue;
88
+ env[name] = value;
89
+ }
90
+ env["DOCKS_KIT_ENGINE"] = "native-capture";
91
+ return env;
92
+ };
93
+
72
94
  /** Run the engine capturing stdout (engine logs/warns go to stderr and pass through). */
73
95
  export const engineCapture = (args: ReadonlyArray<string>) =>
74
96
  Effect.gen(function* () {
@@ -76,14 +98,18 @@ export const engineCapture = (args: ReadonlyArray<string>) =>
76
98
  if (bashEngineRequested()) {
77
99
  return yield* bail(bashRemovedMessage, 2);
78
100
  }
101
+ // The child runs the native-capture channel, which ignores env globals even
102
+ // when Bun reloads them from a project `.env`. The child environment also
103
+ // omits them, so a captured public command behaves like an in-process one.
104
+ const childEnv = captureChildEnv();
79
105
  const res = yield* Effect.sync(() =>
80
- // Child process (raw channel): runEngineNative writes straight to
106
+ // Child process (capture channel): runEngineNative writes straight to
81
107
  // process.stdout, so in-process capture is not possible.
82
108
  spawnSync(
83
109
  process.execPath,
84
110
  compiled ? [...args] : [`${kitHome()}/cli/src/main.ts`, ...args],
85
111
  {
86
- env: { ...process.env, DOCKS_KIT_ENGINE: "native-raw" },
112
+ env: childEnv,
87
113
  encoding: "utf8",
88
114
  stdio: ["ignore", "pipe", "inherit"],
89
115
  },