docks-kit 0.20.6 → 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 +18 -16
  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 +43 -19
  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 +37 -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
package/cli/src/main.ts CHANGED
@@ -74,16 +74,23 @@ const bareVersionFormatter: CliOutput.Formatter = {
74
74
  formatVersion: (_name, version) => `${version}\n`,
75
75
  };
76
76
 
77
- // Harness-private raw channel:
77
+ // Harness-private raw channels:
78
78
  // `DOCKS_KIT_ENGINE=native-raw` bypasses effect/unstable/cli and hands the raw engine
79
79
  // argv to EngineNative so golden tests drive the internal vocabulary directly.
80
+ // Only this channel honors the unprefixed env globals (DRY_RUN, PRUNE, and so on).
81
+ // `DOCKS_KIT_ENGINE=native-capture` is the engine.ts engineCapture child. It takes
82
+ // the same raw argv but ignores the env globals. Bun can reload those globals from
83
+ // a project `.env` file, so removing them from the child environment is not enough.
80
84
  // PUBLIC engine execution lives at the engine.ts seam after the CLI has
81
85
  // parsed/normalized pickers, --flag value forms, and non-engine commands.
82
- if (process.env["DOCKS_KIT_ENGINE"] === "native-raw") {
86
+ const rawChannel = process.env["DOCKS_KIT_ENGINE"];
87
+ if (rawChannel === "native-raw" || rawChannel === "native-capture") {
83
88
  const rawArgs = process.argv.slice(2);
84
89
  const rawOperation = rawArgs.join(" ") || "default";
85
90
  try {
86
- process.exit(await runEngineNative(rawArgs));
91
+ process.exit(
92
+ await runEngineNative(rawArgs, undefined, { envGlobals: rawChannel === "native-raw" }),
93
+ );
87
94
  } catch (error) {
88
95
  let detail = "unknown error";
89
96
  if (error instanceof Error && error.message !== "") detail = error.message;
@@ -1,12 +1,14 @@
1
1
  import { existsSync, lstatSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
2
- import { homedir } from "node:os";
3
2
  import { dirname, join, resolve } from "node:path";
4
3
  import { pluginUserScopeInstalled } from "./engine-native/claudePluginPasses";
4
+ import { codexHome } from "./engine-native/codexPaths";
5
+ import { engineHome } from "./engine-native/harnesses";
6
+ import { isObject, readJsonFile } from "./engine-native/jq";
7
+ import type { JsonObject } from "./engine-native/sharedTypes";
8
+ import { skillBase } from "./engine-native/skillsManifest";
5
9
  import { COPY_MARKER } from "./engine-native/skillsSync";
6
10
  import { payloadText } from "./payload";
7
11
 
8
- export { homedir };
9
-
10
12
  export type Tool = "claude" | "codex";
11
13
 
12
14
  const readJson = (path: string): any => JSON.parse(readFileSync(path, "utf8"));
@@ -16,7 +18,7 @@ const readJsonText = (text: string): any => JSON.parse(text);
16
18
  export const sotClaudeSettings = (): any => readJsonText(payloadText("SoT/.claude/settings.json"));
17
19
 
18
20
  export const deployedClaudeSettings = (): any | undefined => {
19
- const p = join(homedir(), ".claude", "settings.json");
21
+ const p = join(engineHome(), ".claude", "settings.json");
20
22
  return existsSync(p) ? readJson(p) : undefined;
21
23
  };
22
24
 
@@ -38,7 +40,25 @@ export const sotCodexModel = (): string | undefined =>
38
40
  topLevelTomlString(payloadText("SoT/.codex/config.toml"), "model");
39
41
 
40
42
  export const deployedCodexModel = (): string | undefined =>
41
- tomlModel(join(homedir(), ".codex", "config.toml"));
43
+ tomlModel(join(codexHome(engineHome()), "config.toml"));
44
+
45
+ const installedPluginsPath = (): string =>
46
+ join(engineHome(), ".claude", "plugins", "installed_plugins.json");
47
+
48
+ /** Read the user-scope plugin records; a missing or malformed file yields `undefined`. */
49
+ const readInstalledPlugins = (path: string): JsonObject | undefined => {
50
+ const doc = readJsonFile(path);
51
+ if (doc === undefined || !isObject(doc)) return undefined;
52
+ const plugins = doc["plugins"];
53
+ return plugins !== undefined && isObject(plugins) ? plugins : undefined;
54
+ };
55
+
56
+ /** State of ~/.claude/plugins/installed_plugins.json: missing, an object with object `plugins`, or not. */
57
+ export const installedPluginsState = (): "absent" | "valid" | "malformed" => {
58
+ const path = installedPluginsPath();
59
+ if (!existsSync(path)) return "absent";
60
+ return readInstalledPlugins(path) === undefined ? "malformed" : "valid";
61
+ };
42
62
 
43
63
  /** Installed plugins (user scope) vs SoT enabledPlugins tri-state. */
44
64
  export const pluginsView = (): Array<{
@@ -47,10 +67,8 @@ export const pluginsView = (): Array<{
47
67
  installed: boolean;
48
68
  }> => {
49
69
  const sot: Record<string, boolean> = sotClaudeSettings().enabledPlugins ?? {};
50
- const installedPath = join(homedir(), ".claude", "plugins", "installed_plugins.json");
51
- const installed: Record<string, unknown> = existsSync(installedPath)
52
- ? (readJson(installedPath).plugins ?? {})
53
- : {};
70
+ const installedPath = installedPluginsPath();
71
+ const installed: Record<string, unknown> = readInstalledPlugins(installedPath) ?? {};
54
72
  const names = new Set([...Object.keys(sot), ...Object.keys(installed)]);
55
73
  return [...names].sort().map((plugin) => ({
56
74
  plugin,
@@ -71,8 +89,8 @@ export const skillsView = (): Array<{
71
89
  .split("\n")
72
90
  .map((l) => l.replace(/#.*$/, "").trim())
73
91
  .filter((l) => l.length > 0)
74
- .map((slug) => slug.split("/").pop() as string);
75
- const home = homedir();
92
+ .map(skillBase);
93
+ const home = engineHome();
76
94
  const skillsDir = join(home, ".agents", "skills");
77
95
  const installed = existsSync(skillsDir)
78
96
  ? readdirSync(skillsDir, { withFileTypes: true })
package/docks-kit CHANGED
@@ -40,10 +40,13 @@ if [[ -x "$REPO_DIR/cli/dist/$KIT_BIN" ]]; then
40
40
  # A matching version does not prove matching content. Unreleased work does
41
41
  # not move package.json, so a binary compiled before it still reports the
42
42
  # checkout version and would silently shadow the source it predates.
43
+ # The binary also embeds the cli/docs topics, so scan both trees.
43
44
  NEWER_SOURCE=""
44
- if [[ -d "$REPO_DIR/cli/src" ]]; then
45
- NEWER_SOURCE="$(find "$REPO_DIR/cli/src" -type f -newer "$REPO_DIR/cli/dist/$KIT_BIN" -print -quit 2>/dev/null || true)"
46
- fi
45
+ for scan_dir in "$REPO_DIR/cli/src" "$REPO_DIR/cli/docs"; do
46
+ if [[ -z "$NEWER_SOURCE" && -d "$scan_dir" ]]; then
47
+ NEWER_SOURCE="$(find "$scan_dir" -type f -newer "$REPO_DIR/cli/dist/$KIT_BIN" -print -quit 2>/dev/null || true)"
48
+ fi
49
+ done
47
50
  if [[ -z "$NEWER_SOURCE" ]]; then
48
51
  exec "$REPO_DIR/cli/dist/$KIT_BIN" "$@"
49
52
  fi
package/docks-kit.ps1 CHANGED
@@ -1,4 +1,4 @@
1
- # docks-kit.ps1 — Windows launcher. Resolution order:
1
+ # docks-kit.ps1 - Windows launcher. Resolution order:
2
2
  # 1. version-matching compiled binary in cli/dist/ (bun build --compile output)
3
3
  # 2. Bun from source (auto-installs Bun + node_modules when missing)
4
4
  # No-Bun recovery path: download a release binary for your platform.
@@ -59,11 +59,15 @@ if (Test-Path -LiteralPath $KitPath -PathType Leaf) {
59
59
  # A matching version does not prove matching content. Unreleased work does
60
60
  # not move package.json, so a binary compiled before it still reports the
61
61
  # checkout version and would silently shadow the source it predates.
62
+ # The binary also embeds the cli/docs topics, so scan both trees.
62
63
  $NewerSource = $null
63
- $SrcDir = Join-Path $RepoDir 'cli\src'
64
- if (Test-Path -LiteralPath $SrcDir -PathType Container) {
64
+ $ScanDirs = @(
65
+ @((Join-Path $RepoDir 'cli\src'), (Join-Path $RepoDir 'cli\docs')) |
66
+ Where-Object { Test-Path -LiteralPath $_ -PathType Container }
67
+ )
68
+ if ($ScanDirs.Count -gt 0) {
65
69
  $BinWritten = (Get-Item -LiteralPath $KitPath).LastWriteTimeUtc
66
- $NewerSource = Get-ChildItem -LiteralPath $SrcDir -Recurse -File -ErrorAction SilentlyContinue |
70
+ $NewerSource = Get-ChildItem -LiteralPath $ScanDirs -Recurse -File -ErrorAction SilentlyContinue |
67
71
  Where-Object { $_.LastWriteTimeUtc -gt $BinWritten } |
68
72
  Select-Object -First 1
69
73
  }
@@ -72,11 +76,11 @@ if (Test-Path -LiteralPath $KitPath -PathType Leaf) {
72
76
  exit $LASTEXITCODE
73
77
  }
74
78
  $NewerRelative = $NewerSource.FullName.Substring($RepoDir.Length).TrimStart('\', '/')
75
- [Console]::Error.WriteLine("[docks-kit] ignoring cli/dist/$KitBin; $NewerRelative is newer than the binary — running from source; run 'bun run build:binaries' to refresh it or delete it")
79
+ [Console]::Error.WriteLine("[docks-kit] ignoring cli/dist/$KitBin; $NewerRelative is newer than the binary - running from source; run 'bun run build:binaries' to refresh it or delete it")
76
80
  } else {
77
81
  $DisplayedBinVersion = if ([string]::IsNullOrEmpty($BinVersion)) { '<unknown>' } else { $BinVersion }
78
82
  $DisplayedCheckoutVersion = if ([string]::IsNullOrEmpty($CheckoutVersion)) { '<unknown>' } else { $CheckoutVersion }
79
- [Console]::Error.WriteLine("[docks-kit] ignoring stale cli/dist/$KitBin $DisplayedBinVersion; checkout is $DisplayedCheckoutVersion — running from source; run 'bun run build:binaries' to refresh it or delete it")
83
+ [Console]::Error.WriteLine("[docks-kit] ignoring stale cli/dist/$KitBin $DisplayedBinVersion; checkout is $DisplayedCheckoutVersion - running from source; run 'bun run build:binaries' to refresh it or delete it")
80
84
  }
81
85
  }
82
86
 
@@ -103,7 +107,7 @@ function Find-Bun {
103
107
 
104
108
  $Bun = Find-Bun
105
109
  if ($null -eq $Bun) {
106
- [Console]::Error.WriteLine('[docks-kit] Bun not found — installing (download-then-run)...')
110
+ [Console]::Error.WriteLine('[docks-kit] Bun not found - installing (download-then-run)...')
107
111
  $TempInstaller = Join-Path ([IO.Path]::GetTempPath()) "bun-install-$([Guid]::NewGuid().ToString('N')).ps1"
108
112
  try {
109
113
  Invoke-WebRequest -Uri 'https://bun.sh/install.ps1' -OutFile $TempInstaller -UseBasicParsing
@@ -123,7 +127,7 @@ if ($null -eq $Bun) {
123
127
  }
124
128
  }
125
129
 
126
- # Sentinel is a real dependency dir, not bare node_modules\ — a failed or
130
+ # Sentinel is a real dependency dir, not bare node_modules\ - a failed or
127
131
  # partial install leaves node_modules\ present and would suppress the repair.
128
132
  if (-not (Test-Path -LiteralPath (Join-Path $RepoDir 'node_modules\effect') -PathType Container)) {
129
133
  $DetectedBunVersion = ''
@@ -153,15 +157,22 @@ if (-not (Test-Path -LiteralPath (Join-Path $RepoDir 'node_modules\effect') -Pat
153
157
  exit 1
154
158
  }
155
159
  [Console]::Error.WriteLine('[docks-kit] Installing CLI dependencies (bun install --frozen-lockfile)...')
160
+ # Windows PowerShell 5.1 turns redirected native stderr lines into errors,
161
+ # and the 'Stop' preference makes them terminate the script. The exit code
162
+ # decides success, so scope a 'Continue' preference to the native call.
163
+ $PreviousPreference = $ErrorActionPreference
164
+ $ErrorActionPreference = 'Continue'
156
165
  Push-Location $RepoDir
157
166
  try {
158
167
  & $Bun install --frozen-lockfile *> $null
159
- if ($LASTEXITCODE -ne 0) {
160
- exit $LASTEXITCODE
161
- }
168
+ $InstallExit = $LASTEXITCODE
162
169
  } finally {
170
+ $ErrorActionPreference = $PreviousPreference
163
171
  Pop-Location
164
172
  }
173
+ if ($InstallExit -ne 0) {
174
+ exit $InstallExit
175
+ }
165
176
  }
166
177
 
167
178
  & $Bun (Join-Path $RepoDir 'cli\src\main.ts') @args
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "docks-kit",
3
- "version": "0.20.6",
3
+ "version": "0.20.8",
4
4
  "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
5
5
  "type": "module",
6
6
  "license": "MIT",