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/main.ts CHANGED
@@ -12,22 +12,12 @@ 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",
16
- );
17
- yield* Console.log(
18
- " docks-kit harnesses choose the flag-less sync selection",
15
+ " docks-kit sync [--dry-run] deploy the SoT to this machine",
19
16
  );
20
17
  yield* Console.log(
21
18
  " docks-kit update [--no-sync] self-update the kit, then sync",
22
19
  );
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");
30
- yield* Console.log(" docks-kit skills list universal skills");
20
+ yield* Console.log(" docks-kit toolchain [check|ensure|outdated] verified-version floors");
31
21
  yield* Console.log(" docks-kit docs [topic] self-documentation");
32
22
  yield* Console.log(" docks-kit omp [--model|--pick] [...] free-model omp session");
33
23
  yield* Console.log(
@@ -44,7 +34,7 @@ const root = Command.make("docks-kit", {}, () =>
44
34
  }),
45
35
  ).pipe(
46
36
  Command.withDescription(
47
- "Portable AI coding agent config kit — SoT sync engine + helpers for Claude Code, Codex, and universal agent skills.",
37
+ "Portable AI coding agent config kit — SoT sync engine + helpers for Oh My Pi.",
48
38
  ),
49
39
  Command.withSubcommands(COMMANDS),
50
40
  );
@@ -57,28 +47,22 @@ const bareVersionFormatter: CliOutput.Formatter = {
57
47
  formatVersion: (_name, version) => `${version}\n`,
58
48
  };
59
49
 
60
- // Harness-private raw channels:
50
+ // Harness-private raw channel:
61
51
  // `DOCKS_KIT_ENGINE=native-raw` bypasses effect/cli and hands the raw engine
62
52
  // argv to EngineNative so golden tests drive the internal vocabulary directly.
63
- // 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.
53
+ // Only this channel honors the unprefixed env globals DRY_RUN and DOCKS_KIT_VERBOSE.
67
54
  // PUBLIC engine execution lives at the engine.ts seam after the CLI has
68
55
  // 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") {
56
+ if (process.env["DOCKS_KIT_ENGINE"] === "native-raw") {
71
57
  const rawArgs = process.argv.slice(2);
72
58
  const rawOperation = rawArgs.join(" ") || "default";
73
- // The raw channels bypass BunRuntime.runMain, which turns a signal into
59
+ // The raw channel bypasses BunRuntime.runMain, which turns a signal into
74
60
  // process.exit. Without a handler a signal ends the process without the
75
61
  // `exit` event, and exec.ts then cannot end its bounded probes.
76
62
  process.once("SIGINT", () => process.exit(130));
77
63
  process.once("SIGTERM", () => process.exit(143));
78
64
  try {
79
- process.exit(
80
- await runEngineNative(rawArgs, undefined, { envGlobals: rawChannel === "native-raw" }),
81
- );
65
+ process.exit(await runEngineNative(rawArgs, undefined, { envGlobals: true }));
82
66
  } catch (error) {
83
67
  let detail = "unknown error";
84
68
  if (error instanceof Error && error.message !== "") detail = error.message;
@@ -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.28",
4
- "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
3
+ "version": "0.24.0",
4
+ "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Oh My Pi",
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
- ```