docks-kit 0.22.25 → 0.23.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 (77) hide show
  1. package/AGENTS.md +35 -81
  2. package/README.md +31 -58
  3. package/cli/docs/command-guards.md +231 -197
  4. package/cli/docs/flags.md +25 -55
  5. package/cli/docs/install.md +2 -3
  6. package/cli/docs/omp-context.md +5 -5
  7. package/cli/docs/omp-models.md +249 -48
  8. package/cli/docs/overview.md +4 -12
  9. package/cli/docs/platforms.md +2 -2
  10. package/cli/docs/sync-layers.md +10 -57
  11. package/cli/docs/toolchain.md +9 -78
  12. package/cli/src/argv.ts +0 -8
  13. package/cli/src/argvValidate.ts +2 -46
  14. package/cli/src/commands/docs.ts +2 -14
  15. package/cli/src/commands/harnesses.ts +6 -9
  16. package/cli/src/commands/sync.ts +5 -99
  17. package/cli/src/commands/toolchain.ts +4 -12
  18. package/cli/src/engine-native/DESIGN.md +67 -88
  19. package/cli/src/engine-native/deps.ts +6 -86
  20. package/cli/src/engine-native/engineCtx.ts +7 -76
  21. package/cli/src/engine-native/exec.ts +1 -18
  22. package/cli/src/engine-native/harnesses.ts +6 -6
  23. package/cli/src/engine-native/index.ts +4 -6
  24. package/cli/src/engine-native/jq.ts +4 -37
  25. package/cli/src/engine-native/modes.ts +3 -132
  26. package/cli/src/engine-native/ompRemovals.ts +14 -0
  27. package/cli/src/engine-native/os/darwin.ts +0 -4
  28. package/cli/src/engine-native/os/index.ts +1 -2
  29. package/cli/src/engine-native/os/linux.ts +0 -3
  30. package/cli/src/engine-native/os/posix.ts +2 -46
  31. package/cli/src/engine-native/os/types.ts +1 -32
  32. package/cli/src/engine-native/os/windows.ts +0 -49
  33. package/cli/src/engine-native/parseArgs.ts +11 -124
  34. package/cli/src/engine-native/parseHelp.ts +5 -40
  35. package/cli/src/engine-native/scratch.ts +1 -1
  36. package/cli/src/engine-native/services.ts +1 -2
  37. package/cli/src/engine-native/sharedTypes.d.ts +0 -40
  38. package/cli/src/engine-native/skillsSync.ts +1 -1
  39. package/cli/src/engine-native/syncConcurrency.ts +3 -15
  40. package/cli/src/engine-native/syncDispatch.ts +10 -57
  41. package/cli/src/engine-native/toolchain.ts +5 -40
  42. package/cli/src/engine.ts +0 -75
  43. package/cli/src/generated/sotPayload.ts +14 -41
  44. package/cli/src/main.ts +7 -19
  45. package/cli/src/manifests.ts +1 -93
  46. package/cli/src/payload.ts +2 -8
  47. package/cli/tsconfig.json +1 -3
  48. package/package.json +3 -5
  49. package/cli/docs/models.md +0 -58
  50. package/cli/docs/modifiers.md +0 -52
  51. package/cli/docs/plugins.md +0 -70
  52. package/cli/src/commands/model.ts +0 -68
  53. package/cli/src/commands/models.ts +0 -75
  54. package/cli/src/commands/plugins.ts +0 -35
  55. package/cli/src/commands/status.ts +0 -206
  56. package/cli/src/efforts.ts +0 -89
  57. package/cli/src/engine-native/claudeLsp.ts +0 -301
  58. package/cli/src/engine-native/claudeOptionalPlugins.ts +0 -126
  59. package/cli/src/engine-native/claudePluginPasses.ts +0 -426
  60. package/cli/src/engine-native/claudeRemovals.ts +0 -383
  61. package/cli/src/engine-native/claudeRetired.ts +0 -165
  62. package/cli/src/engine-native/claudeRuntime.ts +0 -157
  63. package/cli/src/engine-native/claudeSettings.ts +0 -201
  64. package/cli/src/engine-native/claudeSettingsModifiers.ts +0 -115
  65. package/cli/src/engine-native/claudeSync.ts +0 -312
  66. package/cli/src/engine-native/codexConfig.ts +0 -214
  67. package/cli/src/engine-native/codexHooks.ts +0 -91
  68. package/cli/src/engine-native/codexPaths.ts +0 -14
  69. package/cli/src/engine-native/codexPlugins.ts +0 -315
  70. package/cli/src/engine-native/codexStatus.ts +0 -25
  71. package/cli/src/engine-native/codexSync.ts +0 -314
  72. package/cli/src/engine-native/codexToml.ts +0 -303
  73. package/cli/src/engine-native/liveModels.ts +0 -264
  74. package/cli/src/engine-native/models.ts +0 -101
  75. package/cli/src/engine-native/parseModifiers.ts +0 -225
  76. package/cli/src/engine-native/settings.ts +0 -42
  77. package/cli/src/engine-native/tomlLines.ts +0 -92
package/cli/src/main.ts CHANGED
@@ -12,7 +12,7 @@ const root = Command.make("docks-kit", {}, () =>
12
12
  yield* Console.log("docks-kit — portable AI coding agent config kit");
13
13
  yield* Console.log("");
14
14
  yield* Console.log(
15
- " docks-kit sync [claude|codex|agents|omp] deploy the SoT to this machine",
15
+ " docks-kit sync [agents|omp] deploy the SoT to this machine",
16
16
  );
17
17
  yield* Console.log(
18
18
  " docks-kit harnesses choose the flag-less sync selection",
@@ -20,13 +20,7 @@ const root = Command.make("docks-kit", {}, () =>
20
20
  yield* Console.log(
21
21
  " docks-kit update [--no-sync] self-update the kit, then sync",
22
22
  );
23
- yield* Console.log(" docks-kit model <claude|codex> [value] get/set the deployed model");
24
- yield* Console.log(" docks-kit models [tool] [--refresh] live model lists per harness");
25
- yield* Console.log(
26
- " docks-kit toolchain [check|ensure|outdated|upgrade] verified-version floors",
27
- );
28
- yield* Console.log(" docks-kit status deployed-vs-SoT doctor view");
29
- yield* Console.log(" docks-kit plugins list plugin tri-state");
23
+ yield* Console.log(" docks-kit toolchain [check|ensure|outdated] verified-version floors");
30
24
  yield* Console.log(" docks-kit skills list universal skills");
31
25
  yield* Console.log(" docks-kit docs [topic] self-documentation");
32
26
  yield* Console.log(" docks-kit omp [--model|--pick] [...] free-model omp session");
@@ -44,7 +38,7 @@ const root = Command.make("docks-kit", {}, () =>
44
38
  }),
45
39
  ).pipe(
46
40
  Command.withDescription(
47
- "Portable AI coding agent config kit — SoT sync engine + helpers for Claude Code, Codex, and universal agent skills.",
41
+ "Portable AI coding agent config kit — SoT sync engine + helpers for Oh My Pi and universal agent skills.",
48
42
  ),
49
43
  Command.withSubcommands(COMMANDS),
50
44
  );
@@ -57,28 +51,22 @@ const bareVersionFormatter: CliOutput.Formatter = {
57
51
  formatVersion: (_name, version) => `${version}\n`,
58
52
  };
59
53
 
60
- // Harness-private raw channels:
54
+ // Harness-private raw channel:
61
55
  // `DOCKS_KIT_ENGINE=native-raw` bypasses effect/cli and hands the raw engine
62
56
  // argv to EngineNative so golden tests drive the internal vocabulary directly.
63
57
  // Only this channel honors the unprefixed env globals (DRY_RUN, PRUNE, and so on).
64
- // `DOCKS_KIT_ENGINE=native-capture` is the engine.ts engineCapture child. It takes
65
- // the same raw argv but ignores the env globals. Bun can reload those globals from
66
- // a project `.env` file, so removing them from the child environment is not enough.
67
58
  // PUBLIC engine execution lives at the engine.ts seam after the CLI has
68
59
  // parsed/normalized pickers, --flag value forms, and non-engine commands.
69
- const rawChannel = process.env["DOCKS_KIT_ENGINE"];
70
- if (rawChannel === "native-raw" || rawChannel === "native-capture") {
60
+ if (process.env["DOCKS_KIT_ENGINE"] === "native-raw") {
71
61
  const rawArgs = process.argv.slice(2);
72
62
  const rawOperation = rawArgs.join(" ") || "default";
73
- // The raw channels bypass BunRuntime.runMain, which turns a signal into
63
+ // The raw channel bypasses BunRuntime.runMain, which turns a signal into
74
64
  // process.exit. Without a handler a signal ends the process without the
75
65
  // `exit` event, and exec.ts then cannot end its bounded probes.
76
66
  process.once("SIGINT", () => process.exit(130));
77
67
  process.once("SIGTERM", () => process.exit(143));
78
68
  try {
79
- process.exit(
80
- await runEngineNative(rawArgs, undefined, { envGlobals: rawChannel === "native-raw" }),
81
- );
69
+ process.exit(await runEngineNative(rawArgs, undefined, { envGlobals: true }));
82
70
  } catch (error) {
83
71
  let detail = "unknown error";
84
72
  if (error instanceof Error && error.message !== "") detail = error.message;
@@ -1,102 +1,10 @@
1
- import { existsSync, lstatSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
1
+ import { existsSync, lstatSync, readdirSync, readlinkSync } from "node:fs";
2
2
  import { dirname, join, resolve } from "node:path";
3
- import { pluginUserScopeInstalled } from "./engine-native/claudePluginPasses";
4
- import { codexHome } from "./engine-native/codexPaths";
5
3
  import { engineHome } from "./engine-native/harnesses";
6
- import { isObject, readJsonFile } from "./engine-native/jq";
7
- import type { JsonObject } from "./engine-native/sharedTypes";
8
4
  import { skillBase } from "./engine-native/skillsManifest";
9
5
  import { COPY_MARKER } from "./engine-native/skillsSync";
10
- import {
11
- isTomlHeaderLine,
12
- keyValueSeparator,
13
- tomlContinuationLines,
14
- } from "./engine-native/tomlLines";
15
6
  import { payloadText } from "./payload";
16
7
 
17
- export type Tool = "claude" | "codex";
18
-
19
- const readJson = (path: string): any => JSON.parse(readFileSync(path, "utf8"));
20
- const readJsonText = (text: string): any => JSON.parse(text);
21
-
22
- /** SoT settings (claude) — model/effort/env for drift display. */
23
- export const sotClaudeSettings = (): any => readJsonText(payloadText("SoT/.claude/settings.json"));
24
-
25
- export const deployedClaudeSettings = (): any | undefined => {
26
- const p = join(engineHome(), ".claude", "settings.json");
27
- return existsSync(p) ? readJson(p) : undefined;
28
- };
29
-
30
- /** The name of a bare, `"…"`, or `'…'` key; undefined for a dotted or escaped key. */
31
- function tomlKeyName(keyText: string): string | undefined {
32
- const key = keyText.trim().match(/^(?:([A-Za-z0-9_-]+)|"([^"\\]*)"|'([^']*)')$/);
33
- return key?.[1] ?? key?.[2] ?? key?.[3];
34
- }
35
-
36
- /**
37
- * The string value of a top-level key. Lines that continue a multi-line value
38
- * are skipped, and the scan stops at the first table header.
39
- */
40
- export function topLevelTomlString(text: string, setting: string): string | undefined {
41
- const lines = text.split(/\r?\n/);
42
- const continuation = tomlContinuationLines(lines);
43
- for (const [index, line] of lines.entries()) {
44
- if (continuation[index] === true) continue;
45
- if (isTomlHeaderLine(line)) return undefined;
46
- const separator = keyValueSeparator(line);
47
- if (separator === undefined || tomlKeyName(line.slice(0, separator)) !== setting) continue;
48
- const value = line.slice(separator + 1).match(/^\s*(?:"([^"]+)"|'([^']*)')/);
49
- if (value !== null) return value[1] ?? value[2];
50
- }
51
- return undefined;
52
- }
53
-
54
- const tomlModel = (path: string): string | undefined => {
55
- if (!existsSync(path)) return undefined;
56
- return topLevelTomlString(readFileSync(path, "utf8"), "model");
57
- };
58
-
59
- export const sotCodexModel = (): string | undefined =>
60
- topLevelTomlString(payloadText("SoT/.codex/config.toml"), "model");
61
-
62
- export const deployedCodexModel = (): string | undefined =>
63
- tomlModel(join(codexHome(engineHome()), "config.toml"));
64
-
65
- const installedPluginsPath = (): string =>
66
- join(engineHome(), ".claude", "plugins", "installed_plugins.json");
67
-
68
- /** Read the user-scope plugin records; a missing or malformed file yields `undefined`. */
69
- const readInstalledPlugins = (path: string): JsonObject | undefined => {
70
- const doc = readJsonFile(path);
71
- if (doc === undefined || !isObject(doc)) return undefined;
72
- const plugins = doc["plugins"];
73
- return plugins !== undefined && isObject(plugins) ? plugins : undefined;
74
- };
75
-
76
- /** State of ~/.claude/plugins/installed_plugins.json: missing, an object with object `plugins`, or not. */
77
- export const installedPluginsState = (): "absent" | "valid" | "malformed" => {
78
- const path = installedPluginsPath();
79
- if (!existsSync(path)) return "absent";
80
- return readInstalledPlugins(path) === undefined ? "malformed" : "valid";
81
- };
82
-
83
- /** Installed plugins (user scope) vs SoT enabledPlugins tri-state. */
84
- export const pluginsView = (): Array<{
85
- plugin: string;
86
- sot: "true" | "false" | "absent";
87
- installed: boolean;
88
- }> => {
89
- const sot: Record<string, boolean> = sotClaudeSettings().enabledPlugins ?? {};
90
- const installedPath = installedPluginsPath();
91
- const installed: Record<string, unknown> = readInstalledPlugins(installedPath) ?? {};
92
- const names = new Set([...Object.keys(sot), ...Object.keys(installed)]);
93
- return [...names].sort().map((plugin) => ({
94
- plugin,
95
- sot: plugin in sot ? (sot[plugin] ? "true" : "false") : "absent",
96
- installed: pluginUserScopeInstalled(installedPath, plugin),
97
- }));
98
- };
99
-
100
8
  /** Universal skills: SoT manifest slugs vs ~/.agents/skills contents. */
101
9
  export const skillsView = (): Array<{
102
10
  skill: string;
@@ -1,18 +1,12 @@
1
- import {
2
- GENERATED_PAYLOAD_BASE64,
3
- GENERATED_PAYLOAD_PATHS,
4
- GENERATED_PAYLOAD_TEXT,
5
- } from "./generated/sotPayload";
1
+ import { GENERATED_PAYLOAD_PATHS, GENERATED_PAYLOAD_TEXT } from "./generated/sotPayload";
6
2
 
7
3
  export type PayloadPath = (typeof GENERATED_PAYLOAD_PATHS)[number];
8
- type TextPayloadPath = Exclude<PayloadPath, "notification.mp3">;
9
4
 
10
- export function payloadText(path: TextPayloadPath): string {
5
+ export function payloadText(path: PayloadPath): string {
11
6
  return GENERATED_PAYLOAD_TEXT[path];
12
7
  }
13
8
 
14
9
  export function payloadBytes(path: PayloadPath): Buffer {
15
- if (path === "notification.mp3") return Buffer.from(GENERATED_PAYLOAD_BASE64[path], "base64");
16
10
  return Buffer.from(payloadText(path));
17
11
  }
18
12
 
package/cli/tsconfig.json CHANGED
@@ -6,8 +6,6 @@
6
6
  "types": ["bun"],
7
7
  "strict": true,
8
8
  "noEmit": true,
9
- "allowJs": true,
10
- "checkJs": true,
11
9
  "allowImportingTsExtensions": true,
12
10
  "skipLibCheck": true,
13
11
  "forceConsistentCasingInFileNames": true,
@@ -26,5 +24,5 @@
26
24
  }
27
25
  ]
28
26
  },
29
- "include": ["src/**/*.ts", "src/**/*.d.ts", "test/**/*.ts", "scripts/**/*.ts", "test/statusline-runtime-smoke.mjs", "../SoT/.claude/bin/*.mjs", "../SoT/.omp/plugin/extensions/*.ts"]
27
+ "include": ["src/**/*.ts", "src/**/*.d.ts", "test/**/*.ts", "scripts/**/*.ts", "../SoT/.omp/plugin/extensions/*.ts"]
30
28
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "docks-kit",
3
- "version": "0.22.25",
4
- "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
3
+ "version": "0.23.0",
4
+ "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Oh My Pi and universal agent skills",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "os": [
@@ -35,9 +35,7 @@
35
35
  "golden:dryrun": "bun cli/test/golden-dryrun.ts",
36
36
  "golden:mutation": "bun cli/test/golden-mutation.ts",
37
37
  "test:unit": "vitest run",
38
- "test:runtime:posix": "bun cli/test/statusline-runtime-smoke.mjs posix",
39
- "test:runtime:windows": "bun cli/test/statusline-runtime-smoke.mjs windows",
40
- "test:ci": "bun run check:generated && bun run --parallel typecheck test:unit golden:dryrun golden:mutation format:check && bun run test:runtime:posix",
38
+ "test:ci": "bun run check:generated && bun run --parallel typecheck test:unit golden:dryrun golden:mutation format:check",
41
39
  "test:integration": "bun run --parallel golden:dryrun golden:mutation",
42
40
  "test": "bun run --parallel test:unit test:integration",
43
41
  "lint": "oxlint",
@@ -1,58 +0,0 @@
1
- # Models
2
-
3
- `SoT/models.json` supplies aliases and notes for Claude and Codex. For each
4
- enabled harness, `docks-kit models` and the picker list live model IDs when
5
- available. Claude uses the Claude Code login to query the Anthropic models API
6
- and caches the result for six hours in `~/.docks-kit/kit.db`; Codex reads
7
- `models_cache.json` in the Codex home (`$CODEX_HOME` when set, else
8
- `~/.codex`); omp runs `omp models --json`. The kit never needs omp to list
9
- Claude models.
10
-
11
- Live lists retain the curated aliases and notes, but omit curated IDs absent
12
- from the live source. A disabled harness, missing login/cache, or unavailable
13
- source falls back to the curated IDs. omp has no curated fallback models.
14
- The `verified` field is the curated section date, not the live fetch date.
15
- Bare model flags without a value print the curated list without a network call.
16
-
17
- ## Validation rules
18
-
19
- - **Claude**: catalog aliases (`best`, `opus`, `fable`, `sonnet`, `haiku`,
20
- `default`) and full IDs validate silently; any other `claude-*` ID is
21
- accepted with a warning (new models outrun the catalog); everything else
22
- exits 2 with the catalog printed.
23
- - **Codex**: hard charset gate `^[A-Za-z0-9._-]+$` (also blocks TOML-quote
24
- injection — the value lands inside a quoted config.toml string); catalog
25
- misses warn but apply.
26
-
27
- ## The `best` alias and `default` pseudo-value
28
-
29
- - `best` resolves to Fable 5.1 where the org has access, latest Opus
30
- otherwise. It needs Claude Code >= 2.1.257. Claude apps gateway sessions
31
- still resolve `best` and `fable` to Fable 5. The kit SoT pins the `opus`
32
- alias directly rather than `best` or a full id, so the deployed model is
33
- unambiguous. Its `minimumVersion` of 2.1.280 ensures Claude Code can resolve
34
- that alias to Opus 5.5, the default Opus from that release. The former
35
- 2.1.219 floor capped the alias at Opus 5. The kit keeps the alias because it
36
- tracks the next Opus release without a kit change and stays portable across
37
- every provider that carries a different newest Opus. The floor also subsumes
38
- the older `best`/Fable 5.1 requirement of 2.1.257.
39
- - `default` is an engine pseudo-value: it DELETES the deployed `model` key so
40
- the account default applies. It never reaches the settings file as a value.
41
-
42
- ## Commands
43
-
44
- ```
45
- docks-kit models # enabled Claude, Codex, and omp catalogs
46
- docks-kit models claude --json # source, fetch date, and fallback reason
47
- docks-kit models claude --refresh # bypass the six-hour Anthropic cache
48
- docks-kit model claude # current deployed + live list + picker (TTY)
49
- docks-kit model claude opus # per-machine override from the Opus SoT
50
- docks-kit sync claude --claude-model=opus # same, as part of a sync
51
- ```
52
-
53
- ## Advisor pairing note (Claude)
54
-
55
- The SoT ships `model: opus` with advisor off (`advisorModel` unset).
56
- Advisor is a per-machine opt-in: `docks-kit sync claude --claude-advisor=on`
57
- writes `advisorModel: opus`; `off` and `default` delete the key. The advisor
58
- then runs the same Opus 5.5 the main session uses.
@@ -1,52 +0,0 @@
1
- # Deploy-time modifiers
2
-
3
- Modifiers change the **deployed** config for a specific machine profile —
4
- the SoT is never touched. They all share one contract:
5
-
6
- > A later flag-less sync reverts the modifier: the settings merge (Claude)
7
- > and the config.toml merge (Codex) re-assert SoT values for kit-owned keys.
8
- > Re-pass the flag on machines that should keep the override. Claude Code has
9
- > no user-scope local settings file; a per-project Claude override belongs in
10
- > that checkout's `.claude/settings.local.json`, which sync never reads or
11
- > writes.
12
-
13
- Claude's embedded SoT is `model: opus`, `effortLevel: high`, with advisor
14
- off (`advisorModel` unset). Codex's embedded normal and plan reasoning effort is
15
- `high`.
16
-
17
- | Modifier | Deployed change | Typical use |
18
- |----------|-----------------|-------------|
19
- | `--claude-model=<m>` | `.model` in ~/.claude/settings.json (`default` deletes the key) | Override one machine while the SoT retains `opus` |
20
- | `--claude-effort=<level>` | `.effortLevel` in ~/.claude/settings.json (`default` writes `high`) | Tune persisted Claude effort per machine; valid `low`, `medium`, `high`, `xhigh` |
21
- | `--claude-advisor=<state>` | `on` sets `.advisorModel = "opus"`; `off`/`default` remove it | Enable Claude advisor only on machines that need it |
22
- | `--claude-compact-window=<n>` | `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Disposable containers running long autonomous work (e.g. `680k`) — not host machines |
23
- | `--claude-permissive` | `permissions.ask = []`, `permissions.deny = []` | Sandboxes/containers where prompts stall unattended work. Never on a host — the deny list is the safety floor |
24
- | `--codex-model=<m>` | top-level `model = "…"` in ~/.codex/config.toml | Same as claude-model, for Codex |
25
- | `--codex-effort=<level>` | top-level `model_reasoning_effort = "…"` (`default` writes `high`) | Tune Codex effort per machine; valid `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra` (model-dependent) |
26
-
27
- Bare effort/advisor flags print their verified catalog and exit 2. Invalid
28
- values do the same with a clear error. Passing a tool-specific modifier without
29
- selecting that positional target warns and ignores it.
30
-
31
- A flag-less Claude sync also removes the formerly kit-owned `advisorModel`
32
- from machines synced before advisor became opt-in. Any explicit advisor state
33
- owns that key for the run: `on` writes `opus`; `off` and `default` delete it.
34
- Codex has no advisor modifier because its documented config has no advisor
35
- setting; `review_model` applies only to `/review`.
36
-
37
- ## Standalone get/set (no full sync)
38
-
39
- ```
40
- docks-kit model claude # show deployed + SoT + catalog (+ TTY picker)
41
- docks-kit model claude opus # set deployed model
42
- docks-kit model claude default # delete the key (account default applies)
43
- docks-kit model codex gpt-5.5 # codex flavor
44
- ```
45
-
46
- The set path calls the same engine functions as the sync flags —
47
- one implementation, two entry points.
48
-
49
- ## Sticky opt-ins are NOT modifiers
50
-
51
- `--claude-plugin=<name>` installs+enables an optional plugin and it STAYS
52
- (the SoT has no key to revert against). Only `--prune` removes it.
@@ -1,70 +0,0 @@
1
- # Plugins: the enabledPlugins tri-state
2
-
3
- `SoT/.claude/settings.json` → `enabledPlugins` values carry three meanings:
4
-
5
- | Value | Meaning | `--prune` |
6
- |-------|---------|-----------|
7
- | `true` | Installed + enabled in every project | keeps installed |
8
- | `false` | Installed + globally disabled; a project's `.claude/settings.json` can flip it to `true` per-repo | keeps installed |
9
- | key absent | Not installed | uninstalls if present |
10
-
11
- The user-scope key MUST stay present (as `false`) for per-project
12
- re-enablement to work — Claude Code ignores project-level entries whose key
13
- is absent from user settings.
14
-
15
- ## Sync passes (idempotent, via the `claude plugin` CLI)
16
-
17
- 1. Add SoT marketplaces not yet known, plus `anthropics/claude-plugins-official`
18
- when a kit plugin needs it and Claude Code has not registered it yet
19
- 2. Install SoT-declared plugins missing at user scope, refreshing each
20
- plugin's source marketplace once first
21
- 3. Refresh the remaining kit-owned marketplaces (skipped by
22
- `--skip-plugin-refresh`)
23
- 4. Update the kit-owned installed plugins (skipped by `--skip-plugin-refresh`)
24
- 5. (`--prune` only) uninstall user-scope plugins that are neither
25
- SoT-declared nor opted in on this run
26
- 6. (`--prune` only) remove marketplaces no kit-owned plugin needs
27
- (`claude-plugins-official` and marketplaces behind project- or local-scope
28
- installs are never removed)
29
- 7. Re-assert SoT enabled-state (undoes install's enable side effect on
30
- false-keyed plugins)
31
-
32
- Every `claude plugin` command runs from the system temp directory, so a sync
33
- started inside a project never edits that project's `.claude` settings.
34
-
35
- ## Failed operations fail the sync
36
-
37
- A marketplace or plugin command that exits non-zero is warned in place AND
38
- recorded, then listed under a `--- Failures ---` block after the summary; the
39
- sync exits 1. A stale plugin therefore no longer looks like a clean sync.
40
-
41
- Not a failure: a missing harness CLI, missing git, and a missing LSP, Bun, or
42
- `pi-intercom` pin in `SoT/toolchain.json`. Those stay warn-and-skip with exit
43
- 0, so a host without Claude, Codex, or omp installed still syncs its deployed
44
- config cleanly. A missing `skills-cli` pin is different: when `npx` is
45
- available and `SoT/.agents/skills.txt` names a skill that is not installed yet,
46
- the agents sync stops with exit 1, in a dry run too. An unavailable plugin
47
- inventory warns without a ledger row and falls back to the full refresh, whose
48
- failed commands are recorded.
49
-
50
- ## Optional opt-ins
51
-
52
- Situational plugins are kept OUT of the SoT and opted in per machine:
53
-
54
- ```
55
- docks-kit sync claude --claude-plugin=supabase
56
- docks-kit sync claude --claude-plugin=supabase,n8n
57
- ```
58
-
59
- Opt-ins are STICKY: with no SoT key to revert against, a later flag-less
60
- sync leaves them alone; only `--prune` uninstalls them.
61
-
62
- Caveat (supabase): its bundled MCP server's OAuth is account-global — the
63
- opt-in only fits while every repo on the machine shares one Supabase account;
64
- otherwise pin a per-repo .mcp.json instead.
65
-
66
- ## Inspect
67
-
68
- ```
69
- docks-kit plugins list [--json]
70
- ```
@@ -1,68 +0,0 @@
1
- import { Argument, Command, Flag, Prompt } from "effect/cli";
2
- import { Effect, Option } from "effect";
3
- import { bail, engine } from "../engine";
4
- import { engineHome } from "../engine-native/harnesses";
5
- import { defaultLiveInputs, resolveCatalog } from "../engine-native/liveModels";
6
- import type { Tool } from "../manifests";
7
-
8
- const tool = Argument.String("tool").pipe(Argument.withDescription("Which tool: claude | codex"));
9
- const value = Argument.String("value").pipe(
10
- Argument.withDescription("Model to set (omit to view current + pick interactively on a TTY)"),
11
- Argument.optional,
12
- );
13
- const dryRun = Flag.Boolean("dry-run").pipe(
14
- Flag.withDescription("Preview without applying"),
15
- Flag.withDefault(false),
16
- );
17
- const verbose = Flag.Boolean("verbose").pipe(
18
- Flag.withAlias("v"),
19
- Flag.withDescription("Also print no-op confirmations (already in sync, up to date)"),
20
- Flag.withDefault(false),
21
- );
22
-
23
- const KEEP = "__keep__";
24
-
25
- export const modelCommand = Command.make("model", { tool, value, dryRun, verbose }, (config) =>
26
- Effect.gen(function* () {
27
- if (config.tool !== "claude" && config.tool !== "codex") {
28
- return yield* bail(`Unknown tool '${config.tool}' (valid: claude, codex)`);
29
- }
30
- const t = config.tool as Tool;
31
- const dry = [...(config.dryRun ? ["--dry-run"] : []), ...(config.verbose ? ["--verbose"] : [])];
32
-
33
- if (Option.isSome(config.value)) {
34
- if (config.value.value.trim() === "") {
35
- return yield* bail("Model value must not be empty or blank");
36
- }
37
- return yield* engine(["model", t, config.value.value, ...dry]);
38
- }
39
-
40
- // No value: show current (engine prints deployed + SoT + catalog) …
41
- yield* engine(["model", t, ...(config.verbose ? ["--verbose"] : [])]);
42
-
43
- // … and offer an interactive picker when attached to a terminal.
44
- if (!process.stdin.isTTY || !process.stdout.isTTY) return;
45
-
46
- const catalog = yield* Effect.promise(() =>
47
- resolveCatalog(t, defaultLiveInputs(engineHome(process.env))),
48
- );
49
- const chosen = yield* Prompt.Select({
50
- message: `Set the deployed ${t} model (deployed config only; a flag-less sync reverts to SoT)`,
51
- choices: [
52
- { title: "(keep current)", value: KEEP },
53
- ...catalog.models.map((m) => ({
54
- title: m.id,
55
- value: m.id,
56
- description: m.note ?? "",
57
- })),
58
- ],
59
- });
60
- if (chosen !== KEEP) {
61
- yield* engine(["model", t, chosen, ...dry]);
62
- }
63
- }),
64
- ).pipe(
65
- Command.withDescription(
66
- "Get or set the DEPLOYED model for one tool without a full sync (deploy-time modifier semantics: SoT untouched; flag-less sync reverts).",
67
- ),
68
- );
@@ -1,75 +0,0 @@
1
- import { Argument, Command, Flag } from "effect/cli";
2
- import { Console, Effect, Option } from "effect";
3
- import { bail } from "../engine";
4
- import { engineHome, LEGACY_SELECTION, readHarnessSelection } from "../engine-native/harnesses";
5
- import { defaultLiveInputs, resolveCatalog } from "../engine-native/liveModels";
6
- import type { CatalogTool, ResolvedCatalog } from "../engine-native/sharedTypes";
7
-
8
- const tool = Argument.String("tool").pipe(
9
- Argument.withDescription("claude | codex | omp (omit for enabled harnesses)"),
10
- Argument.optional,
11
- );
12
- const json = Flag.Boolean("json").pipe(
13
- Flag.withDescription("Machine-readable output"),
14
- Flag.withDefault(false),
15
- );
16
- const refresh = Flag.Boolean("refresh").pipe(
17
- Flag.withDescription("Bypass the kit cache (~/.docks-kit/kit.db) and fetch live lists again"),
18
- Flag.withDefault(false),
19
- );
20
-
21
- function isCatalogTool(value: string): value is CatalogTool {
22
- return value === "claude" || value === "codex" || value === "omp";
23
- }
24
-
25
- const renderTool = (t: CatalogTool, catalog: ResolvedCatalog) =>
26
- Effect.gen(function* () {
27
- yield* Console.log(
28
- catalog.source === "curated"
29
- ? `${t} models (kit-verified ${catalog.verified}):`
30
- : `${t} models (live — ${catalog.source}, fetched ${catalog.fetchedAt ?? "?"}):`,
31
- );
32
- if (catalog.fallbackReason !== undefined) {
33
- yield* Console.log(` (live list unavailable: ${catalog.fallbackReason})`);
34
- }
35
- for (const m of catalog.models) {
36
- yield* Console.log(` ${m.id.padEnd(28)} ${m.kind.padEnd(6)} ${m.note ?? ""}`);
37
- }
38
- if (t === "claude") {
39
- yield* Console.log(
40
- " (full claude-* model IDs outside the catalog are accepted with a warning)",
41
- );
42
- } else if (t === "codex") {
43
- yield* Console.log(" (well-formed IDs outside the catalog are accepted with a warning)");
44
- }
45
- yield* Console.log("");
46
- });
47
-
48
- export const modelsCommand = Command.make("models", { tool, json, refresh }, (config) =>
49
- Effect.gen(function* () {
50
- const requested = Option.getOrUndefined(config.tool);
51
- if (requested !== undefined && !isCatalogTool(requested)) {
52
- return yield* bail(`Unknown tool '${requested}' (valid: claude, codex, omp)`);
53
- }
54
- const home = engineHome(process.env);
55
- const tools: ReadonlyArray<CatalogTool> =
56
- requested !== undefined
57
- ? [requested]
58
- : (readHarnessSelection(home) ?? LEGACY_SELECTION).filter(isCatalogTool);
59
- const inputs = defaultLiveInputs(home, config.refresh);
60
- const out: Partial<Record<CatalogTool, ResolvedCatalog>> = {};
61
- for (const t of tools) {
62
- const catalog = yield* Effect.promise(() => resolveCatalog(t, inputs));
63
- if (config.json) {
64
- out[t] = catalog;
65
- } else {
66
- yield* renderTool(t, catalog);
67
- }
68
- }
69
- if (config.json) yield* Console.log(JSON.stringify(out, null, 2));
70
- }),
71
- ).pipe(
72
- Command.withDescription(
73
- "List models per enabled harness: live from each harness's login or cache, with SoT/models.json aliases and notes as overlay and offline fallback.",
74
- ),
75
- );
@@ -1,35 +0,0 @@
1
- import { Argument, Command, Flag } from "effect/cli";
2
- import { Console, Effect, Option } from "effect";
3
- import { bail } from "../engine";
4
- import { pluginsView } from "../manifests";
5
-
6
- const action = Argument.String("action").pipe(
7
- Argument.withDescription("list (default)"),
8
- Argument.optional,
9
- );
10
- const json = Flag.Boolean("json").pipe(
11
- Flag.withDescription("Machine-readable output"),
12
- Flag.withDefault(false),
13
- );
14
-
15
- export const pluginsCommand = Command.make("plugins", { action, json }, (config) =>
16
- Effect.gen(function* () {
17
- const act = Option.getOrElse(config.action, () => "list");
18
- if (act !== "list") {
19
- return yield* bail(
20
- `Unknown plugins action '${act}' (valid: list). Install/removal runs through sync: --claude-plugin=<name> opts in, --prune reconciles.`,
21
- );
22
- }
23
- const view = pluginsView();
24
- if (config.json) {
25
- return yield* Console.log(JSON.stringify(view, null, 2));
26
- }
27
- yield* Console.log(
28
- "SoT tri-state: true = enabled everywhere, false = installed-but-disabled (per-project enable), absent = not kit-managed\n",
29
- );
30
- yield* Console.log(`${"PLUGIN".padEnd(44)} ${"SOT".padEnd(7)} INSTALLED`);
31
- for (const p of view) {
32
- yield* Console.log(`${p.plugin.padEnd(44)} ${p.sot.padEnd(7)} ${p.installed ? "yes" : "no"}`);
33
- }
34
- }),
35
- ).pipe(Command.withDescription("Installed plugins vs SoT enabledPlugins tri-state (read-only)."));