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.
- package/AGENTS.md +35 -81
- package/README.md +31 -58
- package/cli/docs/command-guards.md +231 -197
- package/cli/docs/flags.md +25 -55
- package/cli/docs/install.md +2 -3
- package/cli/docs/omp-context.md +5 -5
- package/cli/docs/omp-models.md +249 -48
- package/cli/docs/overview.md +4 -12
- package/cli/docs/platforms.md +2 -2
- package/cli/docs/sync-layers.md +10 -57
- package/cli/docs/toolchain.md +9 -78
- package/cli/src/argv.ts +0 -8
- package/cli/src/argvValidate.ts +2 -46
- package/cli/src/commands/docs.ts +2 -14
- package/cli/src/commands/harnesses.ts +6 -9
- package/cli/src/commands/sync.ts +5 -99
- package/cli/src/commands/toolchain.ts +4 -12
- package/cli/src/engine-native/DESIGN.md +67 -88
- package/cli/src/engine-native/deps.ts +6 -86
- package/cli/src/engine-native/engineCtx.ts +7 -76
- package/cli/src/engine-native/exec.ts +1 -18
- package/cli/src/engine-native/harnesses.ts +6 -6
- package/cli/src/engine-native/index.ts +4 -6
- package/cli/src/engine-native/jq.ts +4 -37
- package/cli/src/engine-native/modes.ts +3 -132
- package/cli/src/engine-native/ompRemovals.ts +14 -0
- package/cli/src/engine-native/os/darwin.ts +0 -4
- package/cli/src/engine-native/os/index.ts +1 -2
- package/cli/src/engine-native/os/linux.ts +0 -3
- package/cli/src/engine-native/os/posix.ts +2 -46
- package/cli/src/engine-native/os/types.ts +1 -32
- package/cli/src/engine-native/os/windows.ts +0 -49
- package/cli/src/engine-native/parseArgs.ts +11 -124
- package/cli/src/engine-native/parseHelp.ts +5 -40
- package/cli/src/engine-native/scratch.ts +1 -1
- package/cli/src/engine-native/services.ts +1 -2
- package/cli/src/engine-native/sharedTypes.d.ts +0 -40
- package/cli/src/engine-native/skillsSync.ts +1 -1
- package/cli/src/engine-native/syncConcurrency.ts +3 -15
- package/cli/src/engine-native/syncDispatch.ts +10 -57
- package/cli/src/engine-native/toolchain.ts +5 -40
- package/cli/src/engine.ts +0 -75
- package/cli/src/generated/sotPayload.ts +14 -41
- package/cli/src/main.ts +7 -19
- package/cli/src/manifests.ts +1 -93
- package/cli/src/payload.ts +2 -8
- package/cli/tsconfig.json +1 -3
- package/package.json +3 -5
- package/cli/docs/models.md +0 -58
- package/cli/docs/modifiers.md +0 -52
- package/cli/docs/plugins.md +0 -70
- package/cli/src/commands/model.ts +0 -68
- package/cli/src/commands/models.ts +0 -75
- package/cli/src/commands/plugins.ts +0 -35
- package/cli/src/commands/status.ts +0 -206
- package/cli/src/efforts.ts +0 -89
- package/cli/src/engine-native/claudeLsp.ts +0 -301
- package/cli/src/engine-native/claudeOptionalPlugins.ts +0 -126
- package/cli/src/engine-native/claudePluginPasses.ts +0 -426
- package/cli/src/engine-native/claudeRemovals.ts +0 -383
- package/cli/src/engine-native/claudeRetired.ts +0 -165
- package/cli/src/engine-native/claudeRuntime.ts +0 -157
- package/cli/src/engine-native/claudeSettings.ts +0 -201
- package/cli/src/engine-native/claudeSettingsModifiers.ts +0 -115
- package/cli/src/engine-native/claudeSync.ts +0 -312
- package/cli/src/engine-native/codexConfig.ts +0 -214
- package/cli/src/engine-native/codexHooks.ts +0 -91
- package/cli/src/engine-native/codexPaths.ts +0 -14
- package/cli/src/engine-native/codexPlugins.ts +0 -315
- package/cli/src/engine-native/codexStatus.ts +0 -25
- package/cli/src/engine-native/codexSync.ts +0 -314
- package/cli/src/engine-native/codexToml.ts +0 -303
- package/cli/src/engine-native/liveModels.ts +0 -264
- package/cli/src/engine-native/models.ts +0 -101
- package/cli/src/engine-native/parseModifiers.ts +0 -225
- package/cli/src/engine-native/settings.ts +0 -42
- 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 [
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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;
|
package/cli/src/manifests.ts
CHANGED
|
@@ -1,102 +1,10 @@
|
|
|
1
|
-
import { existsSync, lstatSync,
|
|
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;
|
package/cli/src/payload.ts
CHANGED
|
@@ -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:
|
|
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", "
|
|
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.
|
|
4
|
-
"description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for
|
|
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:
|
|
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",
|
package/cli/docs/models.md
DELETED
|
@@ -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.
|
package/cli/docs/modifiers.md
DELETED
|
@@ -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.
|
package/cli/docs/plugins.md
DELETED
|
@@ -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)."));
|