docks-kit 0.22.28 → 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 (93) hide show
  1. package/AGENTS.md +42 -89
  2. package/README.md +35 -72
  3. package/cli/docs/command-guards.md +233 -197
  4. package/cli/docs/flags.md +17 -65
  5. package/cli/docs/install.md +2 -3
  6. package/cli/docs/omp-context.md +79 -7
  7. package/cli/docs/omp-models.md +27 -12
  8. package/cli/docs/overview.md +7 -18
  9. package/cli/docs/platforms.md +2 -2
  10. package/cli/docs/sync-layers.md +14 -60
  11. package/cli/docs/toolchain.md +12 -81
  12. package/cli/src/argv.ts +0 -12
  13. package/cli/src/argvValidate.ts +3 -54
  14. package/cli/src/commands/docs.ts +3 -15
  15. package/cli/src/commands/omp.ts +1 -1
  16. package/cli/src/commands/scratch.ts +1 -1
  17. package/cli/src/commands/sync.ts +5 -120
  18. package/cli/src/commands/tidy.ts +1 -1
  19. package/cli/src/commands/toolchain.ts +4 -12
  20. package/cli/src/engine-native/DESIGN.md +69 -100
  21. package/cli/src/engine-native/deps.ts +7 -92
  22. package/cli/src/engine-native/engineCtx.ts +9 -103
  23. package/cli/src/engine-native/exec.ts +1 -18
  24. package/cli/src/engine-native/index.ts +6 -8
  25. package/cli/src/engine-native/jq.ts +4 -37
  26. package/cli/src/engine-native/kitDb.ts +21 -37
  27. package/cli/src/engine-native/modes.ts +3 -132
  28. package/cli/src/engine-native/ompFastMode.ts +1 -1
  29. package/cli/src/engine-native/ompOverlay.ts +1 -1
  30. package/cli/src/engine-native/ompRemovals.ts +24 -3
  31. package/cli/src/engine-native/ompSession.ts +67 -0
  32. package/cli/src/engine-native/ompSync.ts +1 -1
  33. package/cli/src/engine-native/os/darwin.ts +0 -4
  34. package/cli/src/engine-native/os/index.ts +1 -2
  35. package/cli/src/engine-native/os/linux.ts +0 -3
  36. package/cli/src/engine-native/os/posix.ts +2 -47
  37. package/cli/src/engine-native/os/types.ts +1 -36
  38. package/cli/src/engine-native/os/windows.ts +0 -50
  39. package/cli/src/engine-native/parseArgs.ts +7 -180
  40. package/cli/src/engine-native/parseHelp.ts +4 -44
  41. package/cli/src/engine-native/scratch.ts +1 -1
  42. package/cli/src/engine-native/services.ts +1 -2
  43. package/cli/src/engine-native/sharedTypes.d.ts +1 -41
  44. package/cli/src/engine-native/syncConcurrency.ts +3 -15
  45. package/cli/src/engine-native/syncDispatch.ts +30 -143
  46. package/cli/src/engine-native/toolchain.ts +6 -45
  47. package/cli/src/engine.ts +0 -75
  48. package/cli/src/generated/sotPayload.ts +14 -43
  49. package/cli/src/main.ts +8 -24
  50. package/cli/src/payload.ts +2 -8
  51. package/cli/tsconfig.json +1 -3
  52. package/package.json +3 -5
  53. package/cli/docs/models.md +0 -58
  54. package/cli/docs/modifiers.md +0 -52
  55. package/cli/docs/plugins.md +0 -70
  56. package/cli/src/checklistPrompt.ts +0 -464
  57. package/cli/src/commands/harnesses.ts +0 -80
  58. package/cli/src/commands/model.ts +0 -68
  59. package/cli/src/commands/models.ts +0 -75
  60. package/cli/src/commands/plugins.ts +0 -35
  61. package/cli/src/commands/skills.ts +0 -40
  62. package/cli/src/commands/status.ts +0 -206
  63. package/cli/src/efforts.ts +0 -89
  64. package/cli/src/engine-native/claudeLsp.ts +0 -301
  65. package/cli/src/engine-native/claudeOptionalPlugins.ts +0 -126
  66. package/cli/src/engine-native/claudePluginPasses.ts +0 -426
  67. package/cli/src/engine-native/claudeRemovals.ts +0 -383
  68. package/cli/src/engine-native/claudeRetired.ts +0 -165
  69. package/cli/src/engine-native/claudeRuntime.ts +0 -157
  70. package/cli/src/engine-native/claudeSettings.ts +0 -201
  71. package/cli/src/engine-native/claudeSettingsModifiers.ts +0 -115
  72. package/cli/src/engine-native/claudeSync.ts +0 -312
  73. package/cli/src/engine-native/codexConfig.ts +0 -214
  74. package/cli/src/engine-native/codexHooks.ts +0 -91
  75. package/cli/src/engine-native/codexPaths.ts +0 -14
  76. package/cli/src/engine-native/codexPlugins.ts +0 -315
  77. package/cli/src/engine-native/codexStatus.ts +0 -25
  78. package/cli/src/engine-native/codexSync.ts +0 -314
  79. package/cli/src/engine-native/codexToml.ts +0 -303
  80. package/cli/src/engine-native/harnesses.ts +0 -138
  81. package/cli/src/engine-native/liveModels.ts +0 -264
  82. package/cli/src/engine-native/models.ts +0 -101
  83. package/cli/src/engine-native/parseModifiers.ts +0 -225
  84. package/cli/src/engine-native/settings.ts +0 -42
  85. package/cli/src/engine-native/skillsInstall.ts +0 -135
  86. package/cli/src/engine-native/skillsLinks.ts +0 -216
  87. package/cli/src/engine-native/skillsManifest.ts +0 -36
  88. package/cli/src/engine-native/skillsPrune.ts +0 -117
  89. package/cli/src/engine-native/skillsRecords.ts +0 -138
  90. package/cli/src/engine-native/skillsSync.ts +0 -57
  91. package/cli/src/engine-native/tomlLines.ts +0 -92
  92. package/cli/src/manifests.ts +0 -145
  93. package/cli/src/terminalCells.ts +0 -191
package/cli/src/argv.ts CHANGED
@@ -1,11 +1,5 @@
1
1
  import { GlobalFlag } from "effect/cli";
2
2
  import { docsCommand } from "./commands/docs";
3
- import { harnessesCommand } from "./commands/harnesses";
4
- import { modelCommand } from "./commands/model";
5
- import { modelsCommand } from "./commands/models";
6
- import { pluginsCommand } from "./commands/plugins";
7
- import { skillsCommand } from "./commands/skills";
8
- import { statusCommand } from "./commands/status";
9
3
  import { syncCommand } from "./commands/sync";
10
4
  import { toolchainCommand } from "./commands/toolchain";
11
5
  import { updateCommand } from "./commands/update";
@@ -32,14 +26,8 @@ export type ArgvOutcome =
32
26
  */
33
27
  export const COMMANDS = [
34
28
  syncCommand,
35
- harnessesCommand,
36
29
  updateCommand,
37
- modelCommand,
38
- modelsCommand,
39
30
  toolchainCommand,
40
- statusCommand,
41
- pluginsCommand,
42
- skillsCommand,
43
31
  docsCommand,
44
32
  ompCommand,
45
33
  scratchCommand,
@@ -1,48 +1,11 @@
1
1
  /**
2
- * Per-command validation for the Effect CLI layer: legacy-flag hints,
3
- * unknown-command/flag detection, boolean-value and duplicate rejection, and
4
- * the sync modifiers' missing-value diagnostics. Operates on scanned flags so
5
- * the grammar machinery stays in argvSurface.ts.
2
+ * Per-command validation for the Effect CLI layer: unknown-command/flag
3
+ * detection, and boolean-value and duplicate rejection.
4
+ * Operates on scanned flags so the grammar machinery stays in argvSurface.ts.
6
5
  */
7
6
 
8
- import { KNOWN_CLAUDE_OPTIN_PLUGINS } from "./engine-native/parseModifiers";
9
- import { isLegacyFlag, LEGACY_FLAG_HINTS } from "./engine-native/parseArgs";
10
- import { modelCatalog } from "./engine-native/models";
11
- import { advisorCatalog, advisorFlagGrammar, effortCatalog, effortFlagGrammar } from "./efforts";
12
- import type { Tool } from "./manifests";
13
7
  import type { ArgvSurfaces, FlagSurface, ScannedFlag } from "./argvSurface";
14
8
 
15
- const modelCatalogHint = (tool: Tool): string => {
16
- const catalog = modelCatalog(tool);
17
- const list = catalog.models
18
- .map((model) => ` ${model.id}${model.note !== undefined ? ` — ${model.note}` : ""}`)
19
- .join("\n");
20
- return `Available ${tool} models (kit-verified ${catalog.verified} — SoT/models.json):\n${list}`;
21
- };
22
-
23
- const missingModifierValue = (flag: string): string | undefined => {
24
- switch (flag) {
25
- case "--claude-model":
26
- case "--codex-model": {
27
- const tool: Tool = flag === "--claude-model" ? "claude" : "codex";
28
- return `${modelCatalogHint(tool)}\n${flag} requires a value: ${flag}=<model>`;
29
- }
30
- case "--claude-effort":
31
- case "--codex-effort": {
32
- const tool: Tool = flag === "--claude-effort" ? "claude" : "codex";
33
- return `${effortCatalog(tool)}\n${flag} requires a value: ${effortFlagGrammar(tool)}`;
34
- }
35
- case "--claude-advisor":
36
- return `${advisorCatalog()}\n${flag} requires a value: ${advisorFlagGrammar()}`;
37
- case "--claude-compact-window":
38
- return `${flag} requires a value: ${flag}=<tokens> (e.g. 680k)`;
39
- case "--claude-plugin":
40
- return `${flag} requires a value: ${flag}=<${KNOWN_CLAUDE_OPTIN_PLUGINS.join("|")}>`;
41
- default:
42
- return undefined;
43
- }
44
- };
45
-
46
9
  /**
47
10
  * Run the validation checks in diagnostic order. Returns the reject message
48
11
  * for the first failure, or undefined when the scanned flags are valid.
@@ -61,12 +24,6 @@ export const validateScannedArgv = (
61
24
  return `unknown command '${subcommand}'`;
62
25
  }
63
26
 
64
- if (subcommand === "sync") {
65
- for (const flag of flags) {
66
- if (isLegacyFlag(flag.name)) return LEGACY_FLAG_HINTS[flag.name];
67
- }
68
- }
69
-
70
27
  // Effect 4 expands clustered shorts, but the kit declares no clusterable alias
71
28
  // pair, so refusing a cluster as one unknown flag is the conservative direction.
72
29
  for (const flag of flags) {
@@ -96,13 +53,5 @@ export const validateScannedArgv = (
96
53
  seen.add(name);
97
54
  }
98
55
 
99
- if (subcommand === "sync") {
100
- for (const flag of flags) {
101
- if (flag.hasValue) continue;
102
- const message = missingModifierValue(flag.name);
103
- if (message !== undefined) return message;
104
- }
105
- }
106
-
107
56
  return undefined;
108
57
  };
@@ -3,10 +3,7 @@ import { Console, Effect, Option } from "effect";
3
3
  import { bail } from "../engine";
4
4
  import overview from "../../docs/overview.md" with { type: "text" };
5
5
  import flags from "../../docs/flags.md" with { type: "text" };
6
- import modifiers from "../../docs/modifiers.md" with { type: "text" };
7
- import models from "../../docs/models.md" with { type: "text" };
8
6
  import toolchain from "../../docs/toolchain.md" with { type: "text" };
9
- import plugins from "../../docs/plugins.md" with { type: "text" };
10
7
  import syncLayers from "../../docs/sync-layers.md" with { type: "text" };
11
8
  import install from "../../docs/install.md" with { type: "text" };
12
9
  import platforms from "../../docs/platforms.md" with { type: "text" };
@@ -17,23 +14,14 @@ import commandGuards from "../../docs/command-guards.md" with { type: "text" };
17
14
  const TOPICS: Record<string, { summary: string; body: string }> = {
18
15
  overview: { summary: "What docks-kit is and how the pieces fit", body: overview },
19
16
  "sync-layers": {
20
- summary: "The four sync targets (claude, codex, agents, omp) and additive-by-default semantics",
17
+ summary: "How sync deploys the omp SoT, and its additive-by-default semantics",
21
18
  body: syncLayers,
22
19
  },
23
- flags: { summary: "Full flag reference incl. the old→new rename table", body: flags },
24
- modifiers: {
25
- summary: "Deploy-time modifiers and the flag-less-sync-reverts contract",
26
- body: modifiers,
27
- },
28
- models: {
29
- summary: "Live model lists, the curated overlay, validation, model get/set",
30
- body: models,
31
- },
20
+ flags: { summary: "Full flag reference", body: flags },
32
21
  toolchain: {
33
22
  summary: "Verified-version floors, the doctor table, and the upstream outdated report",
34
23
  body: toolchain,
35
24
  },
36
- plugins: { summary: "enabledPlugins tri-state + optional plugin opt-ins", body: plugins },
37
25
  install: {
38
26
  summary: "Install paths: repo checkout, bun add -g, POSIX/Windows installers",
39
27
  body: install,
@@ -51,7 +39,7 @@ const TOPICS: Record<string, { summary: string; body: string }> = {
51
39
  body: ompContext,
52
40
  },
53
41
  "command-guards": {
54
- summary: "Deny, ask, and allow tiers for destructive shell commands in omp, Claude, and Codex",
42
+ summary: "Deny and allow rules for destructive shell commands in omp",
55
43
  body: commandGuards,
56
44
  },
57
45
  };
@@ -10,7 +10,7 @@ import {
10
10
  readOmpSessionModel,
11
11
  writeOmpSessionModel,
12
12
  type OmpSessionModel,
13
- } from "../engine-native/harnesses";
13
+ } from "../engine-native/ompSession";
14
14
  import {
15
15
  buildOmpArgs,
16
16
  ladderCeiling,
@@ -4,7 +4,7 @@ import { Argument, Command } from "effect/cli";
4
4
  import { Console, Effect } from "effect";
5
5
 
6
6
  import { bail } from "../engine";
7
- import { engineHome } from "../engine-native/harnesses";
7
+ import { engineHome } from "../engine-native/ompSession";
8
8
  import {
9
9
  allowedRemovalRoots,
10
10
  createScratchDir,
@@ -1,8 +1,8 @@
1
- import { Argument, Command, Flag } from "effect/cli";
2
- import { Effect, Option } from "effect";
1
+ import { Command, Flag } from "effect/cli";
2
+ import { Effect } from "effect";
3
3
  import { existsSync } from "node:fs";
4
4
  import { join } from "node:path";
5
- import { bail, engine } from "../engine";
5
+ import { engine } from "../engine";
6
6
  import { spawnHost } from "../engine-native/exec";
7
7
  import type { Logger } from "../engine-native/logger";
8
8
  import { kitHome } from "../kitHome";
@@ -35,35 +35,10 @@ export const updateNudge = (logger: Logger): void => {
35
35
  }
36
36
  };
37
37
 
38
- const VALID_TARGETS = ["claude", "codex", "agents", "omp"];
39
-
40
- const targets: Argument.Argument<ReadonlyArray<string>> = Argument.String("target").pipe(
41
- Argument.withDescription(
42
- "Sync targets: claude, codex, agents, omp (default: selected harnesses)",
43
- ),
44
- Argument.variadic(),
45
- );
46
-
47
38
  const dryRun = Flag.Boolean("dry-run").pipe(
48
39
  Flag.withDescription("Preview without applying"),
49
40
  Flag.withDefault(false),
50
41
  );
51
- const reconcile = Flag.Boolean("reconcile").pipe(
52
- Flag.withDescription(
53
- "Reconcile kit-owned settings with SoT (SoT keys win; user-only keys preserved; permissions arrays replaced)",
54
- ),
55
- Flag.withDefault(false),
56
- );
57
- const prune = Flag.Boolean("prune").pipe(
58
- Flag.withDescription(
59
- "Uninstall kit-managed installs not in SoT (plugins, marketplaces, universal skills)",
60
- ),
61
- Flag.withDefault(false),
62
- );
63
- const skipBubblewrap = Flag.Boolean("skip-bubblewrap").pipe(
64
- Flag.withDescription("Skip optional bubblewrap bootstrap (Codex Linux sandbox)"),
65
- Flag.withDefault(false),
66
- );
67
42
  const skipPluginRefresh = Flag.Boolean("skip-plugin-refresh").pipe(
68
43
  Flag.withDescription(
69
44
  "Install missing plugins but skip refresh-only updates for existing plugins",
@@ -75,106 +50,20 @@ const verbose = Flag.Boolean("verbose").pipe(
75
50
  Flag.withDescription("Also print no-op confirmations (already in sync, up to date, left as-is)"),
76
51
  Flag.withDefault(false),
77
52
  );
78
- const claudeModel = Flag.String("claude-model").pipe(
79
- Flag.withDescription(
80
- "Deploy-time modifier: set deployed Claude model (see `docks-kit models claude`)",
81
- ),
82
- Flag.optional,
83
- );
84
- const claudeEffort = Flag.String("claude-effort").pipe(
85
- Flag.withDescription(
86
- "Deploy-time modifier: set Claude effortLevel (bare flag shows valid levels)",
87
- ),
88
- Flag.optional,
89
- );
90
- const claudeAdvisor = Flag.String("claude-advisor").pipe(
91
- Flag.withDescription("Deploy-time modifier: set Claude advisor on/off/default"),
92
- Flag.optional,
93
- );
94
- const claudeCompactWindow = Flag.String("claude-compact-window").pipe(
95
- Flag.withDescription(
96
- "Deploy-time modifier: set deployed autocompact window in tokens (e.g. 680000 or 680k)",
97
- ),
98
- Flag.optional,
99
- );
100
- const claudePermissive = Flag.Boolean("claude-permissive").pipe(
101
- Flag.withDescription(
102
- "Deploy-time modifier: empty permissions.ask/deny in deployed settings (sandboxes)",
103
- ),
104
- Flag.withDefault(false),
105
- );
106
- const claudePlugin = Flag.String("claude-plugin").pipe(
107
- Flag.withDescription(
108
- "Sticky opt-in plugin(s); repeatable and/or comma-separated (known: supabase, n8n)",
109
- ),
110
- Flag.atLeast(0),
111
- );
112
- const codexModel = Flag.String("codex-model").pipe(
113
- Flag.withDescription(
114
- "Deploy-time modifier: set deployed Codex model (see `docks-kit models codex`)",
115
- ),
116
- Flag.optional,
117
- );
118
- const codexEffort = Flag.String("codex-effort").pipe(
119
- Flag.withDescription(
120
- "Deploy-time modifier: set Codex model_reasoning_effort (bare flag shows valid levels)",
121
- ),
122
- Flag.optional,
123
- );
124
53
 
125
54
  export const syncCommand = Command.make(
126
55
  "sync",
127
56
  {
128
- targets,
129
57
  dryRun,
130
- reconcile,
131
- prune,
132
- skipBubblewrap,
133
58
  skipPluginRefresh,
134
59
  verbose,
135
- claudeModel,
136
- claudeEffort,
137
- claudeAdvisor,
138
- claudeCompactWindow,
139
- claudePermissive,
140
- claudePlugin,
141
- codexModel,
142
- codexEffort,
143
60
  },
144
61
  (config) =>
145
62
  Effect.gen(function* () {
146
- const bad = config.targets.filter((t) => !VALID_TARGETS.includes(t));
147
- if (bad.length > 0) {
148
- return yield* bail(
149
- `Unknown sync target(s): ${bad.join(", ")} (valid: ${VALID_TARGETS.join(", ")})`,
150
- );
151
- }
152
-
153
- const args: Array<string> = ["sync", ...config.targets];
63
+ const args: Array<string> = ["sync"];
154
64
  if (config.dryRun) args.push("--dry-run");
155
- if (config.reconcile) args.push("--reconcile");
156
- if (config.prune) args.push("--prune");
157
- if (config.skipBubblewrap) args.push("--skip-bubblewrap");
158
65
  if (config.skipPluginRefresh) args.push("--skip-plugin-refresh");
159
66
  if (config.verbose) args.push("--verbose");
160
- if (config.claudePermissive) args.push("--claude-permissive");
161
- Option.map(config.claudeModel, (m) => args.push(`--claude-model=${m}`));
162
- Option.map(config.claudeEffort, (level) => args.push(`--claude-effort=${level}`));
163
- Option.map(config.claudeAdvisor, (state) => args.push(`--claude-advisor=${state}`));
164
- Option.map(config.claudeCompactWindow, (w) => args.push(`--claude-compact-window=${w}`));
165
- Option.map(config.codexModel, (m) => args.push(`--codex-model=${m}`));
166
- Option.map(config.codexEffort, (level) => args.push(`--codex-effort=${level}`));
167
- for (const occurrence of config.claudePlugin) {
168
- const names = occurrence
169
- .split(",")
170
- .map((p) => p.trim())
171
- .filter((p) => p.length > 0);
172
- if (names.length === 0) {
173
- args.push("--claude-plugin=");
174
- continue;
175
- }
176
- for (const name of names) args.push(`--claude-plugin=${name}`);
177
- }
178
67
 
179
68
  // Not on --dry-run: the nudge's git fetch writes FETCH_HEAD/remote
180
69
  // refs, and a preview command must not mutate the checkout.
@@ -184,8 +73,4 @@ export const syncCommand = Command.make(
184
73
  }
185
74
  yield* engine(args);
186
75
  }),
187
- ).pipe(
188
- Command.withDescription(
189
- "Deploy the SoT to this machine with EngineNative. Deploy-time modifiers touch deployed config only; a later flag-less sync reverts them to SoT.",
190
- ),
191
- );
76
+ ).pipe(Command.withDescription("Deploy the SoT to this machine with EngineNative."));
@@ -4,7 +4,7 @@ import { Command, Flag } from "effect/cli";
4
4
  import { Console, Effect, Option } from "effect";
5
5
 
6
6
  import { bail } from "../engine";
7
- import { engineHome } from "../engine-native/harnesses";
7
+ import { engineHome } from "../engine-native/ompSession";
8
8
  import { acquireKitLock, releaseKitLock } from "../engine-native/kitLock";
9
9
  import { scratchRoot, tidyApplyLockPath } from "../engine-native/scratch";
10
10
  import {
@@ -5,7 +5,7 @@ import { bail, engine } from "../engine";
5
5
  const MANAGED = ["bun"];
6
6
 
7
7
  const op = Argument.String("op").pipe(
8
- Argument.withDescription("check (default) | ensure <tool> | outdated | upgrade"),
8
+ Argument.withDescription("check (default) | ensure <tool> | outdated"),
9
9
  Argument.optional,
10
10
  );
11
11
  const tool = Argument.String("tool").pipe(
@@ -22,7 +22,7 @@ const refresh = Flag.Boolean("refresh").pipe(
22
22
  Flag.withDefault(false),
23
23
  );
24
24
  const dryRun = Flag.Boolean("dry-run").pipe(
25
- Flag.withDescription("ensure/upgrade: preview without installing or running npm"),
25
+ Flag.withDescription("ensure: preview without installing"),
26
26
  Flag.withDefault(false),
27
27
  );
28
28
 
@@ -59,22 +59,14 @@ export const toolchainCommand = Command.make(
59
59
  ...words,
60
60
  ...(config.refresh ? ["--refresh"] : []),
61
61
  ]);
62
- case "upgrade":
63
- return yield* engine([
64
- "toolchain",
65
- "upgrade",
66
- ...words,
67
- ...flags,
68
- ...(config.dryRun ? ["--dry-run"] : []),
69
- ]);
70
62
  default:
71
63
  return yield* bail(
72
- `Unknown toolchain op '${operation}' (valid: check, ensure, outdated, upgrade)`,
64
+ `Unknown toolchain op '${operation}' (valid: check, ensure, outdated)`,
73
65
  );
74
66
  }
75
67
  }),
76
68
  ).pipe(
77
69
  Command.withDescription(
78
- "Verified-version floors for external tools (SoT/toolchain.json): check prints the doctor table; ensure installs one managed tool when it is missing; outdated compares verified pins with the newest upstream release (network, report only); upgrade moves npm-installed LSP servers below their verified pin to that pin.",
70
+ "Verified-version floors for external tools (SoT/toolchain.json): check prints the doctor table; ensure installs one managed tool when it is missing; outdated compares verified pins with the newest upstream release (network, report only).",
79
71
  ),
80
72
  );