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/docs/overview.md
CHANGED
|
@@ -9,14 +9,11 @@ AI-assisted dev environment on every machine.
|
|
|
9
9
|
|
|
10
10
|
| Piece | Role |
|
|
11
11
|
|-------|------|
|
|
12
|
-
| `SoT/.claude/` | Claude Code config (settings template, Bun runtime programs, CLAUDE.md) |
|
|
13
|
-
| `SoT/.codex/` | Codex config (config.toml, rules, AGENTS.md, marketplace) |
|
|
14
12
|
| `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
|
|
15
13
|
| `SoT/.omp/` | omp config deployed to `~/.omp/agent/` (AGENTS.md, config.yml, models.yml, mcp.json) plus `intercom.json` for pi intercom, plus the `plugin/` tree, deployed to `~/.docks-kit/omp-plugin` and linked as the `docks-kit-omp` omp plugin |
|
|
16
|
-
| `SoT/models.json` | Curated Claude and Codex aliases, notes, and offline fallback for the live model lists (see `docks-kit docs models`) |
|
|
17
14
|
| `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
|
|
18
15
|
| `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
|
|
19
|
-
| `cli/src/engine-native/` | EngineNative mutation logic for sync/
|
|
16
|
+
| `cli/src/engine-native/` | EngineNative mutation logic for sync/toolchain and the `docks-kit omp` session overlay |
|
|
20
17
|
| `cli/` | This CLI (Effect 4 on Bun) plus bundled docs |
|
|
21
18
|
| `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers: version-matching compiled binary → Bun-from-source, with Bun auto-install |
|
|
22
19
|
|
|
@@ -27,20 +24,15 @@ AI-assisted dev environment on every machine.
|
|
|
27
24
|
(with a platform-correct install command when a tool is missing), and the
|
|
28
25
|
summary; `--verbose` / `-v` also prints the no-op confirmations.
|
|
29
26
|
- **Additive by default**: user-only keys/plugins/skills survive a plain sync.
|
|
30
|
-
|
|
31
|
-
`--prune
|
|
32
|
-
- **Deploy-time modifiers** mutate deployed config only — the SoT never
|
|
33
|
-
changes, and a later flag-less sync reverts them (`docks-kit docs modifiers`).
|
|
27
|
+
Removing kit-managed universal skills that left the SoT is explicit:
|
|
28
|
+
`--prune`.
|
|
34
29
|
- **Engine/CLI split**: the CLI adds UX (typed flags, pickers, docs, JSON);
|
|
35
30
|
EngineNative owns mutation. No-Bun recovery is a platform release binary.
|
|
36
31
|
- **Authoring/runtime split**: changes begin in `SoT/`; build/prepack freshness
|
|
37
32
|
checks keep the generated in-memory payload byte-identical for every runtime.
|
|
38
|
-
- **Native Claude runtime**: three dependency-free Bun `.mjs` programs own the
|
|
39
|
-
statusline, SessionStart, and Notification. Quotas come only from native
|
|
40
|
-
`rate_limits`; missing Bun defers cutover without deleting legacy fallbacks.
|
|
41
33
|
|
|
42
34
|
## Where to go next
|
|
43
35
|
|
|
44
36
|
- `docks-kit docs sync-layers` — what a sync actually touches
|
|
45
37
|
- `docks-kit docs flags` — full flag reference + old→new renames
|
|
46
|
-
- `docks-kit
|
|
38
|
+
- `docks-kit toolchain` — doctor view of this machine's external tools
|
package/cli/docs/platforms.md
CHANGED
|
@@ -18,7 +18,7 @@ Rosetta reports `x86_64` and gets the unsupported-host message, so run
|
|
|
18
18
|
docks-kit from a native arm64 shell.
|
|
19
19
|
|
|
20
20
|
EngineNative is the only supported engine on supported hosts.
|
|
21
|
-
When `DOCKS_KIT_ENGINE=bash` is set, the commands that run the engine (`sync
|
|
22
|
-
|
|
21
|
+
When `DOCKS_KIT_ENGINE=bash` is set, the commands that run the engine (`sync`
|
|
22
|
+
and `toolchain`) exit 2 with the removed-engine message. The
|
|
23
23
|
message points at the `bash-engine-final` tag for historical recovery. Other
|
|
24
24
|
commands ignore the variable.
|
package/cli/docs/sync-layers.md
CHANGED
|
@@ -1,59 +1,13 @@
|
|
|
1
1
|
# Sync layers
|
|
2
2
|
|
|
3
|
-
`docks-kit sync [
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
`docks-kit harnesses` changes it.
|
|
7
|
-
|
|
8
|
-
## claude (→ ~/.claude, ~/.claude.json, shell rc)
|
|
9
|
-
|
|
10
|
-
Order matters — runtime readiness and settings form one transaction:
|
|
11
|
-
|
|
12
|
-
1. Resolve/bootstrap pinned Bun, materialize the sentinel settings template,
|
|
13
|
-
and prepare the merged settings bytes without mutation. If Bun remains
|
|
14
|
-
unavailable, omit only the new runtime pointers and preserve legacy ones.
|
|
15
|
-
2. When ready, write `bin/statusline.mjs`, `bin/session-start.mjs`,
|
|
16
|
-
`bin/notify.mjs`, and `notification.mp3`; deploy CLAUDE.md; atomically commit
|
|
17
|
-
settings.
|
|
18
|
-
3. **settings.json merge semantics** — additive: SoT keys win, permissions arrays are
|
|
19
|
-
unioned, user-only keys survive. `--reconcile` replaces permissions arrays
|
|
20
|
-
wholesale instead.
|
|
21
|
-
4. **Removed-artifact pruning** — prune old shell assets, the Stop hook, stale
|
|
22
|
-
kit-owned settings, retired kit-owned plugin enablement, and every
|
|
23
|
-
manifest-listed kit-owned `~/.local/bin` command. A flag-less sync removes
|
|
24
|
-
`advisorModel`; an explicit advisor state excludes only that key so the
|
|
25
|
-
modifier owns it.
|
|
26
|
-
5. **Deploy-time modifiers** (`--claude-compact-window`, `--claude-permissive`,
|
|
27
|
-
`--claude-model`, `--claude-effort`, `--claude-advisor`) — deployed file only.
|
|
28
|
-
6. ~/.claude.json (showTurnDuration, user-scoped MCP servers) and connector env
|
|
29
|
-
export.
|
|
30
|
-
7. **Plugins** — seven idempotent passes via the `claude plugin` CLI
|
|
31
|
-
(marketplaces → install → update → [--prune: uninstall/remove] → re-assert
|
|
32
|
-
SoT enabled-state). Optional opt-ins via `--claude-plugin=<name>`.
|
|
33
|
-
8. LSP server binaries (npm globals plus the rust-analyzer rustup component).
|
|
34
|
-
|
|
35
|
-
The statusline reads Claude's native `rate_limits`. There is no OAuth request,
|
|
36
|
-
usage cache, jq/curl runtime dependency, or Stop fetch hook.
|
|
37
|
-
|
|
38
|
-
## codex (→ Codex home, ~/.agents/plugins)
|
|
39
|
-
|
|
40
|
-
bubblewrap bootstrap (Linux): when `bwrap` is missing, sync runs
|
|
41
|
-
`sudo apt-get|dnf|pacman|zypper install bubblewrap` (a sudo prompt may appear)
|
|
42
|
-
and then probes unprivileged user namespaces; `--skip-bubblewrap` only warns,
|
|
43
|
-
and `--dry-run` only prints the step. Then config.toml merge (top-level keys
|
|
44
|
-
replaced per-key, [table] blocks replaced wholesale, user-only keys/tables
|
|
45
|
-
preserved, and retired kit-owned `[plugins."<id>"]` tables stripped),
|
|
46
|
-
`--codex-model` then `--codex-effort` modifiers, rules, AGENTS.md, personal
|
|
47
|
-
marketplace file, and `codex plugin add` refresh.
|
|
48
|
-
|
|
49
|
-
The Codex home is `$CODEX_HOME` when that variable is set and not empty, else
|
|
50
|
-
`~/.codex`. Like Codex, the kit resolves a relative `CODEX_HOME` against the
|
|
51
|
-
current directory. Every kit read or write of Codex state uses this directory.
|
|
3
|
+
`docks-kit sync [agents] [omp]` — targets are positional words; no target
|
|
4
|
+
means this machine's harness selection in `~/.docks-kit/kit.db`. The default
|
|
5
|
+
is `agents omp`, and `docks-kit harnesses` changes it.
|
|
52
6
|
|
|
53
7
|
## agents (→ ~/.agents/skills, ~/.claude/skills symlinks)
|
|
54
8
|
|
|
55
|
-
`npx skills add` per missing manifest slug,
|
|
56
|
-
kit-
|
|
9
|
+
`npx skills add` per missing manifest slug, `~/.claude/skills` symlink
|
|
10
|
+
healing, and the kit-owned record that `--prune` removes against.
|
|
57
11
|
|
|
58
12
|
## omp (→ resolved agent dir, intercom root)
|
|
59
13
|
|
|
@@ -64,8 +18,8 @@ deployed-only keys survive; config.yml also drops stale slash-bearing
|
|
|
64
18
|
config.yml `bash.patterns`: the merge keeps user rules and groups all rules as
|
|
65
19
|
kit deny, user deny, user prompt, kit prompt (the kit ships none since 0.22.8),
|
|
66
20
|
other user rules, and kit allow, so no allow loosens a deny or a prompt (see
|
|
67
|
-
`docks-kit docs command-guards`). After each merge, every sync (no
|
|
68
|
-
|
|
21
|
+
`docks-kit docs command-guards`). After each merge, every sync (no flag
|
|
22
|
+
needed) force-prunes the `ompRemovals.ts` retired-key inventory:
|
|
69
23
|
the retired kit `bash.patterns` rules in `OMP_RETIRED_BASH_RULES` (exact
|
|
70
24
|
`match` and `approval` pairs, including the 492 former kit prompt rules
|
|
71
25
|
retired in 0.22.8), config.yml keys whose deployed value still equals the value the kit used to
|
|
@@ -164,8 +118,7 @@ into `<agent directory>/intercom`. Otherwise it goes into
|
|
|
164
118
|
`$PI_CODING_AGENT_DIR/intercom` when that variable is set, else
|
|
165
119
|
`~/.pi/agent/intercom`.
|
|
166
120
|
|
|
167
|
-
##
|
|
121
|
+
## Prune flag
|
|
168
122
|
|
|
169
|
-
- `--
|
|
170
|
-
|
|
171
|
-
- Combine for a full reset to the SoT's kit-managed scope.
|
|
123
|
+
- `--prune` — the universal skills that `~/.agents/.kit-owned-skills` names
|
|
124
|
+
and SoT no longer lists are removed.
|
package/cli/docs/toolchain.md
CHANGED
|
@@ -19,7 +19,7 @@ Their generated Bun floor is intentionally separate from the generated `verified
|
|
|
19
19
|
|
|
20
20
|
- **bun** — policy `present`: installed from the pinned `verified` release and
|
|
21
21
|
never auto-upgraded. `bun.ts` `bunBootstrap` owns one per-engine-run memo
|
|
22
|
-
shared by the
|
|
22
|
+
shared by the omp pipeline and direct `toolchain ensure bun` on every
|
|
23
23
|
supported host. The POSIX modules download `install.sh` with curl and run it
|
|
24
24
|
with Bash. The Windows module downloads `install.ps1` with curl and runs it
|
|
25
25
|
through `powershell.exe`. When Bun is already present, `toolchain ensure bun`
|
|
@@ -29,84 +29,17 @@ jq and curl are `check` rows, not global prerequisites. jq is not consumed by
|
|
|
29
29
|
normal sync. curl is checked only when a requested Bun bootstrap must download
|
|
30
30
|
an installer. An already-present Bun skips that download on every host.
|
|
31
31
|
|
|
32
|
-
## Node floor
|
|
33
|
-
|
|
34
|
-
`node` stays a `check` row and now carries a floor of 22.22.2. The floor comes
|
|
35
|
-
from `typescript-language-server` 6's `engines` field. The kit installs that
|
|
36
|
-
server as an npm global for the `typescript-lsp` plugin, so an older Node runs
|
|
37
|
-
a server its own manifest rejects. `docks-kit toolchain check` prints
|
|
38
|
-
`below-floor` for a Node older than 22.22.2. The sync pass reads the same
|
|
39
|
-
floor: it skips the `typescript-language-server` install on such a host, warns
|
|
40
|
-
with the host Node version, and installs the other language servers.
|
|
41
|
-
`docks-kit toolchain upgrade` also reads the floor: it skips the
|
|
42
|
-
`typescript-language-server` upgrade on such a host and warns. Nothing else
|
|
43
|
-
consults the floor, so a host below it still runs every other kit operation.
|
|
44
|
-
|
|
45
|
-
## rust-analyzer: no floor, no pin
|
|
46
|
-
|
|
47
|
-
`rust-analyzer` is a `check` row with no floor and no `verified` pin. The kit
|
|
48
|
-
installs the component with `rustup component add rust-analyzer` for the
|
|
49
|
-
`rust-analyzer-lsp` plugin, so the version follows the host Rust toolchain. A
|
|
50
|
-
pin would claim control the kit does not have, the stance `bubblewrap` already
|
|
51
|
-
takes for a tool the kit does not publish. `docks-kit toolchain check` reports
|
|
52
|
-
the installed version and judges nothing.
|
|
53
|
-
|
|
54
|
-
## Language-server upgrades
|
|
55
|
-
|
|
56
|
-
`claudeLsp.ts syncLspServers` installs `intelephense`, `typescript-language-server`,
|
|
57
|
-
`typescript`, and `rust-analyzer` only when the binary is missing. It never
|
|
58
|
-
upgrades a server that is already present. A `verified` bump therefore reaches
|
|
59
|
-
a fresh host immediately and leaves an existing install alone.
|
|
60
|
-
|
|
61
|
-
The rustup channel follows the same rule. Sync adds the component only when the
|
|
62
|
-
`rust-analyzer` binary is missing or is a rustup proxy that cannot run because
|
|
63
|
-
the component is not installed. When `rust-analyzer --version` does not answer
|
|
64
|
-
within 60 s, sync warns, stops the probe, and does not add the component on that
|
|
65
|
-
run. `rustup update` is the user's remedy for an old component.
|
|
66
|
-
|
|
67
|
-
A server below its `floor` shows as `below-floor` in `docks-kit toolchain check`.
|
|
68
|
-
A server at or above its floor but below its `verified` pin shows as `ok`.
|
|
69
|
-
To move every npm server that is below its `verified` pin to that pin, run:
|
|
70
|
-
|
|
71
|
-
```bash
|
|
72
|
-
docks-kit toolchain upgrade --dry-run # print the npm command
|
|
73
|
-
docks-kit toolchain upgrade # run it
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
`toolchain upgrade` (`claudeLsp.ts upgradeLspServers`) reads `npm ls -g` to see
|
|
77
|
-
which of `intelephense`, `typescript-language-server`, and `typescript` npm
|
|
78
|
-
owns. It runs one `npm install -g` command that names every npm-owned package
|
|
79
|
-
below its pin as `<pkg>@<verified>`. A package already at or above its pin
|
|
80
|
-
stays as it is. It leaves
|
|
81
|
-
these alone and warns:
|
|
82
|
-
|
|
83
|
-
- A binary on PATH that npm does not own. It came from another installer, so
|
|
84
|
-
upgrade it with that installer.
|
|
85
|
-
- `typescript-language-server` when Node is older than the `node` floor.
|
|
86
|
-
|
|
87
|
-
When the PATH copy of an npm-owned server is outside `npm prefix -g`, it warns
|
|
88
|
-
that the upgrade changes only the npm copy. The check follows links and
|
|
89
|
-
accepts only a file inside the package directory
|
|
90
|
-
(`<prefix>/lib/node_modules/<pkg>` on POSIX), so a link from another PATH
|
|
91
|
-
directory into it counts as the npm copy, while a distro binary under a
|
|
92
|
-
`/usr` prefix does not. On Windows, a shim in `<prefix>` counts. A package that is not installed
|
|
93
|
-
stays missing, because `sync claude` owns first installs. A failed npm call
|
|
94
|
-
exits 1. After the install, it reads `npm ls -g` again and exits 1 when a
|
|
95
|
-
package is not at its pin.
|
|
96
|
-
|
|
97
32
|
## Supply-chain stance
|
|
98
33
|
|
|
99
34
|
Every kit-driven package install from npm, npx, GitHub releases, or
|
|
100
35
|
`omp install` is pinned to a `SoT/toolchain.json` `verified` version — never
|
|
101
36
|
floating `@latest` (the npm-worm / Shai-Hulud attack surface). That includes
|
|
102
37
|
the `npx skills@<verified>` invocations on agents sync and the release workflow
|
|
103
|
-
(actions pinned to commit SHAs, exact bun/npm versions).
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
surface, a new marketplace or plugin source included, needs a manifest pin
|
|
109
|
-
first.
|
|
38
|
+
(actions pinned to commit SHAs, exact bun/npm versions). The existing omp
|
|
39
|
+
marketplace plugins have no manifest pin: sync installs and refreshes them at
|
|
40
|
+
the version that their marketplace publishes (see `sync-layers`). Any new
|
|
41
|
+
install surface, a new marketplace or plugin source included, needs a
|
|
42
|
+
manifest pin first.
|
|
110
43
|
|
|
111
44
|
The kit's own package is the single exemption from the `@latest` ban. `install.sh` and `install.ps1`
|
|
112
45
|
end with `bun add -g docks-kit@latest` because a global installer that pinned
|
|
@@ -117,17 +50,15 @@ manifest's `verified` version.
|
|
|
117
50
|
## Commands
|
|
118
51
|
|
|
119
52
|
```text
|
|
120
|
-
docks-kit toolchain check # doctor table
|
|
53
|
+
docks-kit toolchain check # doctor table
|
|
121
54
|
docks-kit toolchain ensure bun # ensure the only managed tool
|
|
122
55
|
docks-kit toolchain ensure bun --dry-run # preview the Bun install
|
|
123
56
|
docks-kit toolchain outdated [--refresh] # verified pins vs newest upstream release
|
|
124
|
-
docks-kit toolchain upgrade [--dry-run] # npm LSP servers below verified -> verified
|
|
125
57
|
```
|
|
126
58
|
|
|
127
59
|
`docks-kit toolchain outdated` reads each tool's optional `upstream` entry in
|
|
128
|
-
`SoT/toolchain.json`. An `npm` entry reads the registry `latest` tag.
|
|
129
|
-
`
|
|
130
|
-
on 6.x. A `github` entry reads the latest release tag and strips `tagPrefix`.
|
|
60
|
+
`SoT/toolchain.json`. An `npm` entry reads the registry `latest` tag. A
|
|
61
|
+
`github` entry reads the latest release tag and strips `tagPrefix`.
|
|
131
62
|
Set `GITHUB_TOKEN` or `GH_TOKEN` to raise the GitHub rate limit. Successful
|
|
132
63
|
lookups cache for 24 hours in `~/.docks-kit/kit.db`; `--refresh` bypasses the
|
|
133
64
|
cache. The report never installs anything and never edits a pin. A failed
|
package/cli/src/argv.ts
CHANGED
|
@@ -1,11 +1,7 @@
|
|
|
1
1
|
import { GlobalFlag } from "effect/cli";
|
|
2
2
|
import { docsCommand } from "./commands/docs";
|
|
3
3
|
import { harnessesCommand } from "./commands/harnesses";
|
|
4
|
-
import { modelCommand } from "./commands/model";
|
|
5
|
-
import { modelsCommand } from "./commands/models";
|
|
6
|
-
import { pluginsCommand } from "./commands/plugins";
|
|
7
4
|
import { skillsCommand } from "./commands/skills";
|
|
8
|
-
import { statusCommand } from "./commands/status";
|
|
9
5
|
import { syncCommand } from "./commands/sync";
|
|
10
6
|
import { toolchainCommand } from "./commands/toolchain";
|
|
11
7
|
import { updateCommand } from "./commands/update";
|
|
@@ -34,11 +30,7 @@ export const COMMANDS = [
|
|
|
34
30
|
syncCommand,
|
|
35
31
|
harnessesCommand,
|
|
36
32
|
updateCommand,
|
|
37
|
-
modelCommand,
|
|
38
|
-
modelsCommand,
|
|
39
33
|
toolchainCommand,
|
|
40
|
-
statusCommand,
|
|
41
|
-
pluginsCommand,
|
|
42
34
|
skillsCommand,
|
|
43
35
|
docsCommand,
|
|
44
36
|
ompCommand,
|
package/cli/src/argvValidate.ts
CHANGED
|
@@ -1,48 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Per-command validation for the Effect CLI layer: legacy-flag hints,
|
|
3
|
-
* unknown-command/flag detection, boolean-value and duplicate rejection
|
|
4
|
-
*
|
|
5
|
-
* the grammar machinery stays in argvSurface.ts.
|
|
3
|
+
* unknown-command/flag detection, and boolean-value and duplicate rejection.
|
|
4
|
+
* Operates on scanned flags so the grammar machinery stays in argvSurface.ts.
|
|
6
5
|
*/
|
|
7
6
|
|
|
8
|
-
import { KNOWN_CLAUDE_OPTIN_PLUGINS } from "./engine-native/parseModifiers";
|
|
9
7
|
import { isLegacyFlag, LEGACY_FLAG_HINTS } from "./engine-native/parseArgs";
|
|
10
|
-
import { modelCatalog } from "./engine-native/models";
|
|
11
|
-
import { advisorCatalog, advisorFlagGrammar, effortCatalog, effortFlagGrammar } from "./efforts";
|
|
12
|
-
import type { Tool } from "./manifests";
|
|
13
8
|
import type { ArgvSurfaces, FlagSurface, ScannedFlag } from "./argvSurface";
|
|
14
9
|
|
|
15
|
-
const modelCatalogHint = (tool: Tool): string => {
|
|
16
|
-
const catalog = modelCatalog(tool);
|
|
17
|
-
const list = catalog.models
|
|
18
|
-
.map((model) => ` ${model.id}${model.note !== undefined ? ` — ${model.note}` : ""}`)
|
|
19
|
-
.join("\n");
|
|
20
|
-
return `Available ${tool} models (kit-verified ${catalog.verified} — SoT/models.json):\n${list}`;
|
|
21
|
-
};
|
|
22
|
-
|
|
23
|
-
const missingModifierValue = (flag: string): string | undefined => {
|
|
24
|
-
switch (flag) {
|
|
25
|
-
case "--claude-model":
|
|
26
|
-
case "--codex-model": {
|
|
27
|
-
const tool: Tool = flag === "--claude-model" ? "claude" : "codex";
|
|
28
|
-
return `${modelCatalogHint(tool)}\n${flag} requires a value: ${flag}=<model>`;
|
|
29
|
-
}
|
|
30
|
-
case "--claude-effort":
|
|
31
|
-
case "--codex-effort": {
|
|
32
|
-
const tool: Tool = flag === "--claude-effort" ? "claude" : "codex";
|
|
33
|
-
return `${effortCatalog(tool)}\n${flag} requires a value: ${effortFlagGrammar(tool)}`;
|
|
34
|
-
}
|
|
35
|
-
case "--claude-advisor":
|
|
36
|
-
return `${advisorCatalog()}\n${flag} requires a value: ${advisorFlagGrammar()}`;
|
|
37
|
-
case "--claude-compact-window":
|
|
38
|
-
return `${flag} requires a value: ${flag}=<tokens> (e.g. 680k)`;
|
|
39
|
-
case "--claude-plugin":
|
|
40
|
-
return `${flag} requires a value: ${flag}=<${KNOWN_CLAUDE_OPTIN_PLUGINS.join("|")}>`;
|
|
41
|
-
default:
|
|
42
|
-
return undefined;
|
|
43
|
-
}
|
|
44
|
-
};
|
|
45
|
-
|
|
46
10
|
/**
|
|
47
11
|
* Run the validation checks in diagnostic order. Returns the reject message
|
|
48
12
|
* for the first failure, or undefined when the scanned flags are valid.
|
|
@@ -96,13 +60,5 @@ export const validateScannedArgv = (
|
|
|
96
60
|
seen.add(name);
|
|
97
61
|
}
|
|
98
62
|
|
|
99
|
-
if (subcommand === "sync") {
|
|
100
|
-
for (const flag of flags) {
|
|
101
|
-
if (flag.hasValue) continue;
|
|
102
|
-
const message = missingModifierValue(flag.name);
|
|
103
|
-
if (message !== undefined) return message;
|
|
104
|
-
}
|
|
105
|
-
}
|
|
106
|
-
|
|
107
63
|
return undefined;
|
|
108
64
|
};
|
package/cli/src/commands/docs.ts
CHANGED
|
@@ -3,10 +3,7 @@ import { Console, Effect, Option } from "effect";
|
|
|
3
3
|
import { bail } from "../engine";
|
|
4
4
|
import overview from "../../docs/overview.md" with { type: "text" };
|
|
5
5
|
import flags from "../../docs/flags.md" with { type: "text" };
|
|
6
|
-
import modifiers from "../../docs/modifiers.md" with { type: "text" };
|
|
7
|
-
import models from "../../docs/models.md" with { type: "text" };
|
|
8
6
|
import toolchain from "../../docs/toolchain.md" with { type: "text" };
|
|
9
|
-
import plugins from "../../docs/plugins.md" with { type: "text" };
|
|
10
7
|
import syncLayers from "../../docs/sync-layers.md" with { type: "text" };
|
|
11
8
|
import install from "../../docs/install.md" with { type: "text" };
|
|
12
9
|
import platforms from "../../docs/platforms.md" with { type: "text" };
|
|
@@ -17,23 +14,14 @@ import commandGuards from "../../docs/command-guards.md" with { type: "text" };
|
|
|
17
14
|
const TOPICS: Record<string, { summary: string; body: string }> = {
|
|
18
15
|
overview: { summary: "What docks-kit is and how the pieces fit", body: overview },
|
|
19
16
|
"sync-layers": {
|
|
20
|
-
summary: "The
|
|
17
|
+
summary: "The two sync targets (agents, omp) and additive-by-default semantics",
|
|
21
18
|
body: syncLayers,
|
|
22
19
|
},
|
|
23
20
|
flags: { summary: "Full flag reference incl. the old→new rename table", body: flags },
|
|
24
|
-
modifiers: {
|
|
25
|
-
summary: "Deploy-time modifiers and the flag-less-sync-reverts contract",
|
|
26
|
-
body: modifiers,
|
|
27
|
-
},
|
|
28
|
-
models: {
|
|
29
|
-
summary: "Live model lists, the curated overlay, validation, model get/set",
|
|
30
|
-
body: models,
|
|
31
|
-
},
|
|
32
21
|
toolchain: {
|
|
33
22
|
summary: "Verified-version floors, the doctor table, and the upstream outdated report",
|
|
34
23
|
body: toolchain,
|
|
35
24
|
},
|
|
36
|
-
plugins: { summary: "enabledPlugins tri-state + optional plugin opt-ins", body: plugins },
|
|
37
25
|
install: {
|
|
38
26
|
summary: "Install paths: repo checkout, bun add -g, POSIX/Windows installers",
|
|
39
27
|
body: install,
|
|
@@ -51,7 +39,7 @@ const TOPICS: Record<string, { summary: string; body: string }> = {
|
|
|
51
39
|
body: ompContext,
|
|
52
40
|
},
|
|
53
41
|
"command-guards": {
|
|
54
|
-
summary: "Deny
|
|
42
|
+
summary: "Deny and allow rules for destructive shell commands in omp",
|
|
55
43
|
body: commandGuards,
|
|
56
44
|
},
|
|
57
45
|
};
|
|
@@ -3,9 +3,9 @@ import { Console, Effect } from "effect";
|
|
|
3
3
|
import { checklistPrompt } from "../checklistPrompt";
|
|
4
4
|
import { bail } from "../engine";
|
|
5
5
|
import {
|
|
6
|
+
DEFAULT_SELECTION,
|
|
6
7
|
engineHome,
|
|
7
8
|
HARNESSES,
|
|
8
|
-
LEGACY_SELECTION,
|
|
9
9
|
loadHarnessSelection,
|
|
10
10
|
writeHarnessSelection,
|
|
11
11
|
type Harness,
|
|
@@ -13,8 +13,6 @@ import {
|
|
|
13
13
|
import { kitDbFile } from "../engine-native/kitDb";
|
|
14
14
|
|
|
15
15
|
const DESCRIPTIONS: Record<Harness, string> = {
|
|
16
|
-
claude: "Claude Code user configuration",
|
|
17
|
-
codex: "Codex user configuration",
|
|
18
16
|
agents: "Universal agent skills",
|
|
19
17
|
omp: "Oh My Pi user configuration",
|
|
20
18
|
};
|
|
@@ -27,12 +25,12 @@ export const harnessesCommand = Command.make("harnesses", {}, () =>
|
|
|
27
25
|
return yield* bail(`Cannot read ${kitDbFile(home)}: ${loaded.reason}`, 1);
|
|
28
26
|
}
|
|
29
27
|
const stored = loaded.kind === "stored" ? loaded.selection : undefined;
|
|
30
|
-
const selection = stored ??
|
|
28
|
+
const selection = stored ?? DEFAULT_SELECTION;
|
|
31
29
|
const names = selection.join(", ");
|
|
32
30
|
|
|
33
31
|
if (stored === undefined) {
|
|
34
32
|
yield* Console.log(
|
|
35
|
-
`Harness selection: ${names} (no selection is stored yet; the
|
|
33
|
+
`Harness selection: ${names} (no selection is stored yet; the default applies)`,
|
|
36
34
|
);
|
|
37
35
|
} else {
|
|
38
36
|
yield* Console.log(`Harness selection: ${names}`);
|
|
@@ -51,10 +49,9 @@ export const harnessesCommand = Command.make("harnesses", {}, () =>
|
|
|
51
49
|
value: harness,
|
|
52
50
|
label: harness,
|
|
53
51
|
description: DESCRIPTIONS[harness],
|
|
54
|
-
// With no stored selection, pre-tick
|
|
55
|
-
//
|
|
56
|
-
|
|
57
|
-
checked: (stored ?? HARNESSES).includes(harness),
|
|
52
|
+
// With no stored selection, pre-tick the default selection that a
|
|
53
|
+
// flag-less sync uses until this picker saves a selection.
|
|
54
|
+
checked: selection.includes(harness),
|
|
58
55
|
})),
|
|
59
56
|
emptySelectionError: "Tick at least one harness.",
|
|
60
57
|
});
|
package/cli/src/commands/sync.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { Argument, Command, Flag } from "effect/cli";
|
|
2
|
-
import { Effect
|
|
2
|
+
import { Effect } from "effect";
|
|
3
3
|
import { existsSync } from "node:fs";
|
|
4
4
|
import { join } from "node:path";
|
|
5
5
|
import { bail, engine } from "../engine";
|
|
@@ -35,12 +35,10 @@ export const updateNudge = (logger: Logger): void => {
|
|
|
35
35
|
}
|
|
36
36
|
};
|
|
37
37
|
|
|
38
|
-
const VALID_TARGETS = ["
|
|
38
|
+
const VALID_TARGETS = ["agents", "omp"];
|
|
39
39
|
|
|
40
40
|
const targets: Argument.Argument<ReadonlyArray<string>> = Argument.String("target").pipe(
|
|
41
|
-
Argument.withDescription(
|
|
42
|
-
"Sync targets: claude, codex, agents, omp (default: selected harnesses)",
|
|
43
|
-
),
|
|
41
|
+
Argument.withDescription("Sync targets: agents, omp (default: selected harnesses)"),
|
|
44
42
|
Argument.variadic(),
|
|
45
43
|
);
|
|
46
44
|
|
|
@@ -48,20 +46,8 @@ const dryRun = Flag.Boolean("dry-run").pipe(
|
|
|
48
46
|
Flag.withDescription("Preview without applying"),
|
|
49
47
|
Flag.withDefault(false),
|
|
50
48
|
);
|
|
51
|
-
const reconcile = Flag.Boolean("reconcile").pipe(
|
|
52
|
-
Flag.withDescription(
|
|
53
|
-
"Reconcile kit-owned settings with SoT (SoT keys win; user-only keys preserved; permissions arrays replaced)",
|
|
54
|
-
),
|
|
55
|
-
Flag.withDefault(false),
|
|
56
|
-
);
|
|
57
49
|
const prune = Flag.Boolean("prune").pipe(
|
|
58
|
-
Flag.withDescription(
|
|
59
|
-
"Uninstall kit-managed installs not in SoT (plugins, marketplaces, universal skills)",
|
|
60
|
-
),
|
|
61
|
-
Flag.withDefault(false),
|
|
62
|
-
);
|
|
63
|
-
const skipBubblewrap = Flag.Boolean("skip-bubblewrap").pipe(
|
|
64
|
-
Flag.withDescription("Skip optional bubblewrap bootstrap (Codex Linux sandbox)"),
|
|
50
|
+
Flag.withDescription("Remove kit-managed universal skills not in SoT/.agents/skills.txt"),
|
|
65
51
|
Flag.withDefault(false),
|
|
66
52
|
);
|
|
67
53
|
const skipPluginRefresh = Flag.Boolean("skip-plugin-refresh").pipe(
|
|
@@ -75,71 +61,15 @@ const verbose = Flag.Boolean("verbose").pipe(
|
|
|
75
61
|
Flag.withDescription("Also print no-op confirmations (already in sync, up to date, left as-is)"),
|
|
76
62
|
Flag.withDefault(false),
|
|
77
63
|
);
|
|
78
|
-
const claudeModel = Flag.String("claude-model").pipe(
|
|
79
|
-
Flag.withDescription(
|
|
80
|
-
"Deploy-time modifier: set deployed Claude model (see `docks-kit models claude`)",
|
|
81
|
-
),
|
|
82
|
-
Flag.optional,
|
|
83
|
-
);
|
|
84
|
-
const claudeEffort = Flag.String("claude-effort").pipe(
|
|
85
|
-
Flag.withDescription(
|
|
86
|
-
"Deploy-time modifier: set Claude effortLevel (bare flag shows valid levels)",
|
|
87
|
-
),
|
|
88
|
-
Flag.optional,
|
|
89
|
-
);
|
|
90
|
-
const claudeAdvisor = Flag.String("claude-advisor").pipe(
|
|
91
|
-
Flag.withDescription("Deploy-time modifier: set Claude advisor on/off/default"),
|
|
92
|
-
Flag.optional,
|
|
93
|
-
);
|
|
94
|
-
const claudeCompactWindow = Flag.String("claude-compact-window").pipe(
|
|
95
|
-
Flag.withDescription(
|
|
96
|
-
"Deploy-time modifier: set deployed autocompact window in tokens (e.g. 680000 or 680k)",
|
|
97
|
-
),
|
|
98
|
-
Flag.optional,
|
|
99
|
-
);
|
|
100
|
-
const claudePermissive = Flag.Boolean("claude-permissive").pipe(
|
|
101
|
-
Flag.withDescription(
|
|
102
|
-
"Deploy-time modifier: empty permissions.ask/deny in deployed settings (sandboxes)",
|
|
103
|
-
),
|
|
104
|
-
Flag.withDefault(false),
|
|
105
|
-
);
|
|
106
|
-
const claudePlugin = Flag.String("claude-plugin").pipe(
|
|
107
|
-
Flag.withDescription(
|
|
108
|
-
"Sticky opt-in plugin(s); repeatable and/or comma-separated (known: supabase, n8n)",
|
|
109
|
-
),
|
|
110
|
-
Flag.atLeast(0),
|
|
111
|
-
);
|
|
112
|
-
const codexModel = Flag.String("codex-model").pipe(
|
|
113
|
-
Flag.withDescription(
|
|
114
|
-
"Deploy-time modifier: set deployed Codex model (see `docks-kit models codex`)",
|
|
115
|
-
),
|
|
116
|
-
Flag.optional,
|
|
117
|
-
);
|
|
118
|
-
const codexEffort = Flag.String("codex-effort").pipe(
|
|
119
|
-
Flag.withDescription(
|
|
120
|
-
"Deploy-time modifier: set Codex model_reasoning_effort (bare flag shows valid levels)",
|
|
121
|
-
),
|
|
122
|
-
Flag.optional,
|
|
123
|
-
);
|
|
124
64
|
|
|
125
65
|
export const syncCommand = Command.make(
|
|
126
66
|
"sync",
|
|
127
67
|
{
|
|
128
68
|
targets,
|
|
129
69
|
dryRun,
|
|
130
|
-
reconcile,
|
|
131
70
|
prune,
|
|
132
|
-
skipBubblewrap,
|
|
133
71
|
skipPluginRefresh,
|
|
134
72
|
verbose,
|
|
135
|
-
claudeModel,
|
|
136
|
-
claudeEffort,
|
|
137
|
-
claudeAdvisor,
|
|
138
|
-
claudeCompactWindow,
|
|
139
|
-
claudePermissive,
|
|
140
|
-
claudePlugin,
|
|
141
|
-
codexModel,
|
|
142
|
-
codexEffort,
|
|
143
73
|
},
|
|
144
74
|
(config) =>
|
|
145
75
|
Effect.gen(function* () {
|
|
@@ -152,29 +82,9 @@ export const syncCommand = Command.make(
|
|
|
152
82
|
|
|
153
83
|
const args: Array<string> = ["sync", ...config.targets];
|
|
154
84
|
if (config.dryRun) args.push("--dry-run");
|
|
155
|
-
if (config.reconcile) args.push("--reconcile");
|
|
156
85
|
if (config.prune) args.push("--prune");
|
|
157
|
-
if (config.skipBubblewrap) args.push("--skip-bubblewrap");
|
|
158
86
|
if (config.skipPluginRefresh) args.push("--skip-plugin-refresh");
|
|
159
87
|
if (config.verbose) args.push("--verbose");
|
|
160
|
-
if (config.claudePermissive) args.push("--claude-permissive");
|
|
161
|
-
Option.map(config.claudeModel, (m) => args.push(`--claude-model=${m}`));
|
|
162
|
-
Option.map(config.claudeEffort, (level) => args.push(`--claude-effort=${level}`));
|
|
163
|
-
Option.map(config.claudeAdvisor, (state) => args.push(`--claude-advisor=${state}`));
|
|
164
|
-
Option.map(config.claudeCompactWindow, (w) => args.push(`--claude-compact-window=${w}`));
|
|
165
|
-
Option.map(config.codexModel, (m) => args.push(`--codex-model=${m}`));
|
|
166
|
-
Option.map(config.codexEffort, (level) => args.push(`--codex-effort=${level}`));
|
|
167
|
-
for (const occurrence of config.claudePlugin) {
|
|
168
|
-
const names = occurrence
|
|
169
|
-
.split(",")
|
|
170
|
-
.map((p) => p.trim())
|
|
171
|
-
.filter((p) => p.length > 0);
|
|
172
|
-
if (names.length === 0) {
|
|
173
|
-
args.push("--claude-plugin=");
|
|
174
|
-
continue;
|
|
175
|
-
}
|
|
176
|
-
for (const name of names) args.push(`--claude-plugin=${name}`);
|
|
177
|
-
}
|
|
178
88
|
|
|
179
89
|
// Not on --dry-run: the nudge's git fetch writes FETCH_HEAD/remote
|
|
180
90
|
// refs, and a preview command must not mutate the checkout.
|
|
@@ -184,8 +94,4 @@ export const syncCommand = Command.make(
|
|
|
184
94
|
}
|
|
185
95
|
yield* engine(args);
|
|
186
96
|
}),
|
|
187
|
-
).pipe(
|
|
188
|
-
Command.withDescription(
|
|
189
|
-
"Deploy the SoT to this machine with EngineNative. Deploy-time modifiers touch deployed config only; a later flag-less sync reverts them to SoT.",
|
|
190
|
-
),
|
|
191
|
-
);
|
|
97
|
+
).pipe(Command.withDescription("Deploy the SoT to this machine with EngineNative."));
|
|
@@ -5,7 +5,7 @@ import { bail, engine } from "../engine";
|
|
|
5
5
|
const MANAGED = ["bun"];
|
|
6
6
|
|
|
7
7
|
const op = Argument.String("op").pipe(
|
|
8
|
-
Argument.withDescription("check (default) | ensure <tool> | outdated
|
|
8
|
+
Argument.withDescription("check (default) | ensure <tool> | outdated"),
|
|
9
9
|
Argument.optional,
|
|
10
10
|
);
|
|
11
11
|
const tool = Argument.String("tool").pipe(
|
|
@@ -22,7 +22,7 @@ const refresh = Flag.Boolean("refresh").pipe(
|
|
|
22
22
|
Flag.withDefault(false),
|
|
23
23
|
);
|
|
24
24
|
const dryRun = Flag.Boolean("dry-run").pipe(
|
|
25
|
-
Flag.withDescription("ensure
|
|
25
|
+
Flag.withDescription("ensure: preview without installing"),
|
|
26
26
|
Flag.withDefault(false),
|
|
27
27
|
);
|
|
28
28
|
|
|
@@ -59,22 +59,14 @@ export const toolchainCommand = Command.make(
|
|
|
59
59
|
...words,
|
|
60
60
|
...(config.refresh ? ["--refresh"] : []),
|
|
61
61
|
]);
|
|
62
|
-
case "upgrade":
|
|
63
|
-
return yield* engine([
|
|
64
|
-
"toolchain",
|
|
65
|
-
"upgrade",
|
|
66
|
-
...words,
|
|
67
|
-
...flags,
|
|
68
|
-
...(config.dryRun ? ["--dry-run"] : []),
|
|
69
|
-
]);
|
|
70
62
|
default:
|
|
71
63
|
return yield* bail(
|
|
72
|
-
`Unknown toolchain op '${operation}' (valid: check, ensure, outdated
|
|
64
|
+
`Unknown toolchain op '${operation}' (valid: check, ensure, outdated)`,
|
|
73
65
|
);
|
|
74
66
|
}
|
|
75
67
|
}),
|
|
76
68
|
).pipe(
|
|
77
69
|
Command.withDescription(
|
|
78
|
-
"Verified-version floors for external tools (SoT/toolchain.json): check prints the doctor table; ensure installs one managed tool when it is missing; outdated compares verified pins with the newest upstream release (network, report only)
|
|
70
|
+
"Verified-version floors for external tools (SoT/toolchain.json): check prints the doctor table; ensure installs one managed tool when it is missing; outdated compares verified pins with the newest upstream release (network, report only).",
|
|
79
71
|
),
|
|
80
72
|
);
|