docks-kit 0.22.13 → 0.22.20
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 +94 -80
- package/README.md +7 -7
- package/cli/docs/command-guards.md +7 -3
- package/cli/docs/flags.md +59 -9
- package/cli/docs/install.md +2 -2
- package/cli/docs/omp-context.md +14 -8
- package/cli/docs/omp-models.md +1 -1
- package/cli/docs/overview.md +1 -1
- package/cli/docs/platforms.md +4 -2
- package/cli/docs/plugins.md +8 -5
- package/cli/docs/sync-layers.md +6 -4
- package/cli/docs/toolchain.md +24 -14
- package/cli/src/argv.ts +7 -4
- package/cli/src/argvValidate.ts +2 -16
- package/cli/src/commands/docs.ts +1 -1
- package/cli/src/commands/omp.ts +56 -15
- package/cli/src/commands/sync.ts +6 -6
- package/cli/src/commands/tidy.ts +83 -26
- package/cli/src/engine-native/DESIGN.md +93 -56
- package/cli/src/engine-native/atomicWrite.ts +168 -8
- package/cli/src/engine-native/codexConfig.ts +2 -6
- package/cli/src/engine-native/codexPlugins.ts +1 -1
- package/cli/src/engine-native/codexSync.ts +137 -26
- package/cli/src/engine-native/codexToml.ts +4 -86
- package/cli/src/engine-native/deps.ts +51 -51
- package/cli/src/engine-native/exec.ts +3 -0
- package/cli/src/engine-native/index.ts +1 -1
- package/cli/src/engine-native/kitLock.ts +121 -0
- package/cli/src/engine-native/modes.ts +49 -31
- package/cli/src/engine-native/ompChild.ts +26 -0
- package/cli/src/engine-native/ompFastMode.ts +14 -7
- package/cli/src/engine-native/ompFileDeploy.ts +12 -6
- package/cli/src/engine-native/ompMarketplace.ts +25 -18
- package/cli/src/engine-native/ompPlugins.ts +23 -14
- package/cli/src/engine-native/ompRemovals.ts +51 -23
- package/cli/src/engine-native/ompSync.ts +66 -32
- package/cli/src/engine-native/os/targets.ts +16 -4
- package/cli/src/engine-native/os/types.ts +1 -1
- package/cli/src/engine-native/parseArgs.ts +27 -17
- package/cli/src/engine-native/processes.ts +16 -0
- package/cli/src/engine-native/scratch.ts +18 -0
- package/cli/src/engine-native/skillsInstall.ts +27 -2
- package/cli/src/engine-native/skillsPrune.ts +51 -49
- package/cli/src/engine-native/skillsRecords.ts +138 -0
- package/cli/src/engine-native/skillsSync.ts +16 -13
- package/cli/src/engine-native/syncDispatch.ts +186 -4
- package/cli/src/engine-native/tidy.ts +102 -119
- package/cli/src/engine-native/tomlLines.ts +92 -0
- package/cli/src/generated/sotPayload.ts +4 -4
- package/cli/src/main.ts +5 -30
- package/cli/src/manifests.ts +24 -4
- package/package.json +2 -2
- package/cli/src/engine-native/tidyLock.ts +0 -163
package/cli/docs/flags.md
CHANGED
|
@@ -26,11 +26,11 @@ Escape leaves it unchanged.
|
|
|
26
26
|
|
|
27
27
|
| Flag | Effect |
|
|
28
28
|
|------|--------|
|
|
29
|
-
| `--dry-run` | Preview without applying |
|
|
29
|
+
| `--dry-run` | Preview without applying; takes no sync lock and no folder lock |
|
|
30
30
|
| `--reconcile` | Settings layer reconciled toward SoT (SoT keys win; user-only keys preserved; permissions arrays replaced) |
|
|
31
|
-
| `--prune` | Uninstall kit-managed installs not in SoT: plugins, marketplaces, universal skills |
|
|
31
|
+
| `--prune` | Uninstall kit-managed installs not in SoT: plugins, marketplaces, and the universal skills that `~/.agents/.kit-owned-skills` names |
|
|
32
32
|
| `--skip-bubblewrap` | Skip optional bubblewrap bootstrap (Codex Linux sandbox) |
|
|
33
|
-
| `--skip-plugin-refresh` | Install missing Claude
|
|
33
|
+
| `--skip-plugin-refresh` | Install missing Claude, Codex, and omp plugins but skip refresh-only updates |
|
|
34
34
|
| `--verbose` / `-v` | Also print no-op confirmations (already in sync, up to date, left as-is); accepted on `sync`, `model`, and `toolchain` |
|
|
35
35
|
|
|
36
36
|
## Environment overrides
|
|
@@ -38,6 +38,54 @@ Escape leaves it unchanged.
|
|
|
38
38
|
| Variable | Effect |
|
|
39
39
|
|----------|--------|
|
|
40
40
|
| `DOCKS_KIT_SYNC_CONCURRENCY=1\|2\|3` | Maximum selected sync pipelines running at once. Default `3`; use `1` for serial golden/debug execution. Invalid values fail `sync` with exit 2 but do not affect `model` or `toolchain`. |
|
|
41
|
+
| `DOCKS_KIT_SYNC_LOCK_WAIT_MS=<ms>` | Time that `sync`, a `model` write, and `omp --fast` wait for another sync to release a sync lock. A non-negative safe integer in milliseconds (at most `9007199254740991`); unset or empty means `120000` (120 s). Any other value prints `DOCKS_KIT_SYNC_LOCK_WAIT_MS must be a non-negative safe integer` and exits 2. |
|
|
42
|
+
|
|
43
|
+
## Sync lock
|
|
44
|
+
|
|
45
|
+
`sync` and `model <tool> <value>` hold the lock
|
|
46
|
+
`~/.cache/docks-kit/sync-lock.db` while they run, so two runs never write the
|
|
47
|
+
same files at once.
|
|
48
|
+
|
|
49
|
+
- A run waits up to 120 s for another run to release the lock
|
|
50
|
+
(`DOCKS_KIT_SYNC_LOCK_WAIT_MS` changes the wait). It then prints
|
|
51
|
+
`another docks-kit sync holds <path>; run sync again after it ends` and
|
|
52
|
+
exits 1 with no change.
|
|
53
|
+
- Two homes can share a Codex folder (`CODEX_HOME`), an agents folder
|
|
54
|
+
(`AGENTS_DIR`), or an omp folder (`PI_CODING_AGENT_DIR`, `PI_CONFIG_DIR`,
|
|
55
|
+
`XDG_DATA_HOME`, or a symlink). So a writing sync also holds
|
|
56
|
+
`.docks-kit-sync-lock.db` inside each such folder that it writes. For `codex`
|
|
57
|
+
this is the Codex folder, and for `agents` the agents folder. For `omp` it is
|
|
58
|
+
the omp agent folder, the intercom folder, and the omp data root. A
|
|
59
|
+
`model codex <value>` write holds the Codex folder lock too. The held line
|
|
60
|
+
then names that lock file.
|
|
61
|
+
- A writing sync creates a missing folder of this set just before it takes the
|
|
62
|
+
lock of that folder, after the locks of its ancestors in the set. Each folder
|
|
63
|
+
that it creates gets mode 0700. The lock step does not change the mode of an
|
|
64
|
+
existing folder. The omp pipeline then sets mode 0700 on the omp agent folder
|
|
65
|
+
and the intercom folder.
|
|
66
|
+
- A sync finds the omp folders once, before it takes the locks. The omp
|
|
67
|
+
pipeline and each `omp` command that it starts use these folders. When the
|
|
68
|
+
locked data root is the omp config root, each `omp` command starts without
|
|
69
|
+
`XDG_DATA_HOME`. So a `$XDG_DATA_HOME/omp` folder that appears during the
|
|
70
|
+
sync does not move the plugin data to a folder without a lock. A later
|
|
71
|
+
`omp` uses that new folder, so the sync then prints
|
|
72
|
+
`omp data root moved to <root> during the sync; run docks-kit sync again`
|
|
73
|
+
and exits 1. The next sync locks the new folder and installs the plugins
|
|
74
|
+
there.
|
|
75
|
+
- The locks cover the folder that the kit writes into, not the target of a
|
|
76
|
+
symlinked file. Two homes whose `config.yml` (or another deployed file) links
|
|
77
|
+
to one shared file can still overwrite the merge of each other.
|
|
78
|
+
- `docks-kit omp --fast` checks `config.yml` before it takes a lock. When the
|
|
79
|
+
file is missing, it exits 2 and creates no omp folder. Otherwise it holds the
|
|
80
|
+
sync lock and the omp agent folder lock while it rewrites `config.yml`. The
|
|
81
|
+
wait and the held line are those of a sync.
|
|
82
|
+
- A run with `--dry-run`, `-h`, or `--help` takes no lock. A dry run through
|
|
83
|
+
the `DRY_RUN=1` env global of the private `native-raw` engine channel takes
|
|
84
|
+
no lock either. `model <tool>` without a value only reads, so it takes no
|
|
85
|
+
lock.
|
|
86
|
+
- The lock goes when the run ends, also when the process is killed.
|
|
87
|
+
- A held lock also delays the error of an invalid argument until the wait
|
|
88
|
+
ends.
|
|
41
89
|
|
|
42
90
|
## Per-tool flags
|
|
43
91
|
|
|
@@ -60,7 +108,7 @@ ignored with a warning; Claude modifiers never touch Codex config and vice versa
|
|
|
60
108
|
|
|
61
109
|
| Flag | Effect |
|
|
62
110
|
|------|--------|
|
|
63
|
-
| `--model <selector>` | Session model for this run and later runs; rejected unless the live catalog reports zero input and output cost
|
|
111
|
+
| `--model <selector>` | Session model for this run and later runs; rejected unless the live catalog reports zero input and output cost with `pricingStatus` `free` or `unknown`; recorded in `~/.docks-kit/kit.db` (table `omp_session`) |
|
|
64
112
|
| `--pick` | Interactive picker over free catalog models; records the choice the same way |
|
|
65
113
|
| `--fast` | Toggle `tier.openai` between `priority` and `none` in the deployed `~/.omp/agent/config.yml`, print the change, and exit; the same tier omp's `/fast on` selects for OpenAI and Codex models |
|
|
66
114
|
|
|
@@ -77,10 +125,11 @@ The launcher rejects a forwarded `--config`, `--model`, `--smol`, `--slow`,
|
|
|
77
125
|
in the `--flag value` and the `--flag=value` form and also after a `--`. It
|
|
78
126
|
exits with code 2 before omp starts. The error names the flag and the
|
|
79
127
|
recoveries: `--model <selector>` before the other arguments or `--pick` for a
|
|
80
|
-
free model, `omp` directly for a paid model
|
|
81
|
-
config file. The launcher sets
|
|
82
|
-
`PI_PLAN_MODEL` to the free role values,
|
|
83
|
-
that it replaces, and appends the overlay
|
|
128
|
+
free model, and `omp` directly for a paid model. For a forwarded `--config`, it
|
|
129
|
+
also names `PI_CONFIG_FILES` for another config file. The launcher sets
|
|
130
|
+
`PI_SMOL_MODEL`, `PI_SLOW_MODEL`, and `PI_PLAN_MODEL` to the free role values,
|
|
131
|
+
warns once for each exported value that it replaces, and appends the overlay
|
|
132
|
+
to `PI_CONFIG_FILES`. See
|
|
84
133
|
[omp-models.md](omp-models.md#free-session-launcher-docks-kit-omp) for the
|
|
85
134
|
full policy and the paths that stay outside the launcher.
|
|
86
135
|
|
|
@@ -105,7 +154,7 @@ forwarded `--model` stops the launcher with exit 2, also behind `--`.
|
|
|
105
154
|
| `scratch new <label>` | Create a private directory (mode 0700) `~/.cache/docks-kit/scratch/<label>-XXXXXX` and print its path; the label matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$` |
|
|
106
155
|
| `scratch remove <path>...` | Remove each path whose real path is strictly inside the scratch root, the system temporary directory, or `/var/tmp`; print `removed <path>` or `refused <path>: <reason>`; exit 1 when any path is refused |
|
|
107
156
|
| `tidy` | List the safe leftover actions (`remove`, `stop`) and the kept candidates (`keep`) with reasons; change nothing |
|
|
108
|
-
| `tidy --apply` |
|
|
157
|
+
| `tidy --apply` | Take the lock `~/.cache/docks-kit/tidy-lock.db`, then plan, perform those actions, and append the outcomes to `~/.cache/docks-kit/tidy.log`; exit 1 when an action fails. When another run holds the lock, print only `another docks-kit tidy run holds <path>`, with no plan and no report, and exit 0. A dry run (`tidy` without `--apply`) and the `--report` sections take no lock |
|
|
109
158
|
| `tidy --repo <path>` | Take the worktree candidates only from that repository, at any location |
|
|
110
159
|
| `tidy --report` | After the plan, print read-only sections on memory, temporary directories, processes, Docker, caches, Trash, git, agent histories, scheduled jobs, and global installs |
|
|
111
160
|
|
|
@@ -121,3 +170,4 @@ Old flags exit with a rename hint — there is no compat behavior.
|
|
|
121
170
|
| `--680k` | `--claude-compact-window=680k` |
|
|
122
171
|
| `--permissive` | `--claude-permissive` |
|
|
123
172
|
| `--supabase` / `--n8n` | `--claude-plugin=supabase` / `--claude-plugin=n8n` |
|
|
173
|
+
| `--skip-rtk` | `--skip-bubblewrap` |
|
package/cli/docs/install.md
CHANGED
|
@@ -113,8 +113,8 @@ installed plugins even when the kit is already current. Pass `--no-sync`, then
|
|
|
113
113
|
run `docks-kit sync --skip-plugin-refresh` to skip the refresh-only work.
|
|
114
114
|
A compiled binary inside a checkout updates the checkout; on the next invocation
|
|
115
115
|
the launcher bypasses that now-stale binary and uses updated source until rebuilt.
|
|
116
|
-
Every `docks-kit sync` also does a best-effort behind-upstream
|
|
117
|
-
nudges when the checkout is stale (silent offline / detached / no git).
|
|
116
|
+
Every `docks-kit sync` except `--dry-run` also does a best-effort behind-upstream
|
|
117
|
+
check and nudges when the checkout is stale (silent offline / detached / no git).
|
|
118
118
|
|
|
119
119
|
## Recovering a broken global install
|
|
120
120
|
|
package/cli/docs/omp-context.md
CHANGED
|
@@ -9,8 +9,10 @@ threshold, and what omp's reserve-based default computes on each model lane.
|
|
|
9
9
|
`packages/agent/src/compaction/compaction.ts` selects the trigger from three
|
|
10
10
|
branches, in priority order.
|
|
11
11
|
|
|
12
|
-
1. A positive `compaction.thresholdTokens` wins.
|
|
13
|
-
|
|
12
|
+
1. A positive `compaction.thresholdTokens` wins. A value below the window is
|
|
13
|
+
exact. For a value at or above the window, the behavior depends on the omp
|
|
14
|
+
release. omp 18.4.4 through 18.8.7 clamps the value to `contextWindow - 1`.
|
|
15
|
+
omp 18.8.8 and later fall back to the reserve-based budget of branch 3.
|
|
14
16
|
2. Otherwise a positive `compaction.thresholdPercent` applies. omp clamps the
|
|
15
17
|
percent to the range 1 through 99 and computes
|
|
16
18
|
`floor(contextWindow * percent / 100)`.
|
|
@@ -31,10 +33,11 @@ constant.
|
|
|
31
33
|
|
|
32
34
|
| Lane | Window | Reserve | Threshold | Percent of window |
|
|
33
35
|
|---|---:|---:|---:|---:|
|
|
34
|
-
| `openai-codex
|
|
36
|
+
| `openai-codex/gpt-6-astra`, `openai-codex/gpt-6-luna` | 272,000 | 40,800 | 231,200 | 85.0% |
|
|
37
|
+
| `openai-codex/gpt-6.1-sol`, `openai-codex/gpt-6.1-terra` | 500,000 | 75,000 | 425,000 | 85.0% |
|
|
35
38
|
| `anthropic/*` | 1,000,000 | 150,000 | 850,000 | 85.0% |
|
|
36
39
|
|
|
37
|
-
|
|
40
|
+
Every lane compacts at the same fraction of its own window. The absolute
|
|
38
41
|
trigger differs only because the windows differ.
|
|
39
42
|
|
|
40
43
|
## Why the kit no longer pins 231200
|
|
@@ -81,10 +84,13 @@ The command must print `-1`.
|
|
|
81
84
|
|
|
82
85
|
## The clamp hazard a fixed pin carries
|
|
83
86
|
|
|
84
|
-
|
|
85
|
-
model whose window is below the pinned
|
|
86
|
-
token, so omp compacts only once the
|
|
87
|
-
|
|
87
|
+
In omp 18.4.4 through 18.8.7, the fixed-token branch clamps the pinned value
|
|
88
|
+
to `contextWindow - 1`. On any model whose window is at or below the pinned
|
|
89
|
+
value, the reserve collapses to one token, so omp compacts only once the
|
|
90
|
+
context is already full. omp 18.8.8 and later fall back to the reserve-based
|
|
91
|
+
budget for such a pin, so this collapse does not occur there. The kit floor is
|
|
92
|
+
omp 18.4.4, so a supported host can still have the clamp. The reserve-based
|
|
93
|
+
default always leaves at least 15% of the window free.
|
|
88
94
|
|
|
89
95
|
No current role model has a window below 272,000, so the hazard was latent
|
|
90
96
|
rather than live. Not pinning removes it entirely, including for any future
|
package/cli/docs/omp-models.md
CHANGED
|
@@ -346,7 +346,7 @@ has measured both at the other levels.
|
|
|
346
346
|
### GPT-5.6 Sol (OpenAI) - previous generation
|
|
347
347
|
|
|
348
348
|
The role map no longer uses GPT-5.6 Sol. This table stays as the measured
|
|
349
|
-
baseline for the
|
|
349
|
+
baseline for the GPT-6.1 Sol `task` retry fallback.
|
|
350
350
|
|
|
351
351
|
| Level | Index | Cost/task | Tokens/task | Index tokens | Speed t/s | TTFT s | TB 4.0 |
|
|
352
352
|
|---|---:|---:|---:|---:|---:|---:|---:|
|
package/cli/docs/overview.md
CHANGED
|
@@ -12,7 +12,7 @@ AI-assisted dev environment on every machine.
|
|
|
12
12
|
| `SoT/.claude/` | Claude Code config (settings template, Bun runtime programs, CLAUDE.md) |
|
|
13
13
|
| `SoT/.codex/` | Codex config (config.toml, rules, AGENTS.md, marketplace) |
|
|
14
14
|
| `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
|
|
15
|
-
| `SoT/.omp/` | omp config deployed to `~/.omp/agent/` (AGENTS.md, config.yml, models.yml, mcp.json) plus `intercom.json` for pi intercom |
|
|
15
|
+
| `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
16
|
| `SoT/models.json` | Curated Claude and Codex aliases, notes, and offline fallback for the live model lists (see `docks-kit docs models`) |
|
|
17
17
|
| `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
|
|
18
18
|
| `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
|
package/cli/docs/platforms.md
CHANGED
|
@@ -18,5 +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
|
-
`DOCKS_KIT_ENGINE=bash`
|
|
22
|
-
`
|
|
21
|
+
When `DOCKS_KIT_ENGINE=bash` is set, the commands that run the engine (`sync`,
|
|
22
|
+
`model`, `toolchain`, `status`) exit 2 with the removed-engine message. The
|
|
23
|
+
message points at the `bash-engine-final` tag for historical recovery. Other
|
|
24
|
+
commands ignore the variable.
|
package/cli/docs/plugins.md
CHANGED
|
@@ -38,11 +38,14 @@ A marketplace or plugin command that exits non-zero is warned in place AND
|
|
|
38
38
|
recorded, then listed under a `--- Failures ---` block after the summary; the
|
|
39
39
|
sync exits 1. A stale plugin therefore no longer looks like a clean sync.
|
|
40
40
|
|
|
41
|
-
Not a failure: a missing harness CLI, missing git, and a missing
|
|
42
|
-
`SoT/toolchain.json
|
|
43
|
-
without Claude, Codex, or omp installed still syncs its deployed
|
|
44
|
-
cleanly.
|
|
45
|
-
|
|
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.
|
|
46
49
|
|
|
47
50
|
## Optional opt-ins
|
|
48
51
|
|
package/cli/docs/sync-layers.md
CHANGED
|
@@ -70,8 +70,8 @@ the retired kit `bash.patterns` rules in `OMP_RETIRED_BASH_RULES` (exact
|
|
|
70
70
|
`match` and `approval` pairs, including the 492 former kit prompt rules
|
|
71
71
|
retired in 0.22.8), config.yml keys whose deployed value still equals the value the kit used to
|
|
72
72
|
ship, `providers.webSearchOrder` at any value, and the retired
|
|
73
|
-
`anthropic.modelOverrides.claude-opus-5-5` block in models.yml while
|
|
74
|
-
matches the shipped block.
|
|
73
|
+
`providers.anthropic.modelOverrides.claude-opus-5-5` block in models.yml while
|
|
74
|
+
it still matches the shipped block.
|
|
75
75
|
Directories are mode 0700 and files mode 0600. Then the `docks` marketplace is
|
|
76
76
|
registered, `docks@docks` and `plan-lifecycle@docks` are installed or upgraded
|
|
77
77
|
through `omp plugin`, and `pi-intercom` is installed at its
|
|
@@ -159,8 +159,10 @@ directory is `<config root>/agent`, where the config root is
|
|
|
159
159
|
directory never moves under XDG. Only the data root that holds
|
|
160
160
|
`marketplaces.json` does: on Linux and macOS, with no agent-dir override
|
|
161
161
|
active, an existing `$XDG_DATA_HOME/omp` (or `$XDG_DATA_HOME/omp/profiles/<name>`
|
|
162
|
-
for a named profile) is adopted.
|
|
163
|
-
|
|
162
|
+
for a named profile) is adopted. Under a named profile, the intercom file goes
|
|
163
|
+
into `<agent directory>/intercom`. Otherwise it goes into
|
|
164
|
+
`$PI_CODING_AGENT_DIR/intercom` when that variable is set, else
|
|
165
|
+
`~/.pi/agent/intercom`.
|
|
164
166
|
|
|
165
167
|
## Reconcile flags
|
|
166
168
|
|
package/cli/docs/toolchain.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
| Field | Meaning |
|
|
6
6
|
|-------|---------|
|
|
7
|
-
| `kind` | `check` (doctor visibility) / `managed` (kit-managed install) / `pin` (no binary — a version pin for
|
|
7
|
+
| `kind` | `check` (doctor visibility) / `managed` (kit-managed install) / `pin` (no binary — a version pin for a package that the kit installs through another tool: `npx` for `skills-cli`, `omp install` for `pi-intercom`; the optional `via` field names that tool in the doctor table, and the default is `npx`) |
|
|
8
8
|
| `policy` | Installation policy; `present` installs when missing and never upgrades |
|
|
9
9
|
| `floor` | Minimum acceptable version shown in the doctor table |
|
|
10
10
|
| `verified` | Last kit-tested version and the exact pin for kit-driven installs |
|
|
@@ -37,8 +37,10 @@ server as an npm global for the `typescript-lsp` plugin, so an older Node runs
|
|
|
37
37
|
a server its own manifest rejects. `docks-kit toolchain check` prints
|
|
38
38
|
`below-floor` for a Node older than 22.22.2. The sync pass reads the same
|
|
39
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
|
-
|
|
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.
|
|
42
44
|
|
|
43
45
|
## rust-analyzer: no floor, no pin
|
|
44
46
|
|
|
@@ -62,8 +64,9 @@ the component is not installed. When `rust-analyzer --version` does not answer
|
|
|
62
64
|
within 60 s, sync warns, stops the probe, and does not add the component on that
|
|
63
65
|
run. `rustup update` is the user's remedy for an old component.
|
|
64
66
|
|
|
65
|
-
A
|
|
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:
|
|
67
70
|
|
|
68
71
|
```bash
|
|
69
72
|
docks-kit toolchain upgrade --dry-run # print the npm command
|
|
@@ -72,8 +75,9 @@ docks-kit toolchain upgrade # run it
|
|
|
72
75
|
|
|
73
76
|
`toolchain upgrade` (`claudeLsp.ts upgradeLspServers`) reads `npm ls -g` to see
|
|
74
77
|
which of `intelephense`, `typescript-language-server`, and `typescript` npm
|
|
75
|
-
owns. It runs one `npm install -g
|
|
76
|
-
below its pin
|
|
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
|
|
77
81
|
these alone and warns:
|
|
78
82
|
|
|
79
83
|
- A binary on PATH that npm does not own. It came from another installer, so
|
|
@@ -92,13 +96,19 @@ package is not at its pin.
|
|
|
92
96
|
|
|
93
97
|
## Supply-chain stance
|
|
94
98
|
|
|
95
|
-
Every kit-driven install
|
|
96
|
-
`SoT/toolchain.json` `verified` version — never
|
|
97
|
-
npm-worm / Shai-Hulud attack surface). That includes
|
|
98
|
-
`npx skills@<verified>` invocations on agents sync and the release workflow
|
|
99
|
-
(actions pinned to commit SHAs, exact bun/npm versions).
|
|
100
|
-
|
|
101
|
-
|
|
99
|
+
Every kit-driven package install from npm, npx, GitHub releases, or
|
|
100
|
+
`omp install` is pinned to a `SoT/toolchain.json` `verified` version — never
|
|
101
|
+
floating `@latest` (the npm-worm / Shai-Hulud attack surface). That includes
|
|
102
|
+
the `npx skills@<verified>` invocations on agents sync and the release workflow
|
|
103
|
+
(actions pinned to commit SHAs, exact bun/npm versions). Two installs follow
|
|
104
|
+
the host toolchain and have no pin: `rust-analyzer` (rustup) and `bubblewrap`
|
|
105
|
+
(distro package manager). The existing Claude Code, Codex, and omp marketplace
|
|
106
|
+
plugins have no manifest pin either: sync installs and refreshes them at the
|
|
107
|
+
version that their marketplace publishes (see `plugins`). Any new install
|
|
108
|
+
surface, a new marketplace or plugin source included, needs a manifest pin
|
|
109
|
+
first.
|
|
110
|
+
|
|
111
|
+
The kit's own package is the single exemption from the `@latest` ban. `install.sh` and `install.ps1`
|
|
102
112
|
end with `bun add -g docks-kit@latest` because a global installer that pinned
|
|
103
113
|
itself would install a fixed old kit forever. The exemption covers `docks-kit`
|
|
104
114
|
alone; both installers still pin the Bun installer they download to the
|
package/cli/src/argv.ts
CHANGED
|
@@ -19,7 +19,6 @@ import {
|
|
|
19
19
|
spliceOmpBoundary,
|
|
20
20
|
subcommandName as scanSubcommandName,
|
|
21
21
|
type ArgvSurfaces,
|
|
22
|
-
type CommandValue,
|
|
23
22
|
} from "./argvSurface";
|
|
24
23
|
import { validateScannedArgv } from "./argvValidate";
|
|
25
24
|
|
|
@@ -27,13 +26,17 @@ export type ArgvOutcome =
|
|
|
27
26
|
| { readonly kind: "reject"; readonly message: string; readonly exitCode: number }
|
|
28
27
|
| { readonly kind: "accept"; readonly args: ReadonlyArray<string> };
|
|
29
28
|
|
|
30
|
-
|
|
29
|
+
/**
|
|
30
|
+
* The one subcommand list. `main.ts` registers it with Effect, and the argv
|
|
31
|
+
* surfaces below accept the same words. The order is the `--help` order.
|
|
32
|
+
*/
|
|
33
|
+
export const COMMANDS = [
|
|
31
34
|
syncCommand,
|
|
32
35
|
harnessesCommand,
|
|
33
36
|
updateCommand,
|
|
34
37
|
modelCommand,
|
|
35
|
-
toolchainCommand,
|
|
36
38
|
modelsCommand,
|
|
39
|
+
toolchainCommand,
|
|
37
40
|
statusCommand,
|
|
38
41
|
pluginsCommand,
|
|
39
42
|
skillsCommand,
|
|
@@ -41,7 +44,7 @@ const COMMANDS: ReadonlyArray<CommandValue> = [
|
|
|
41
44
|
ompCommand,
|
|
42
45
|
scratchCommand,
|
|
43
46
|
tidyCommand,
|
|
44
|
-
];
|
|
47
|
+
] as const;
|
|
45
48
|
|
|
46
49
|
const SURFACES: ArgvSurfaces = buildSurfaces(COMMANDS, GlobalFlag.BuiltIns);
|
|
47
50
|
|
package/cli/src/argvValidate.ts
CHANGED
|
@@ -6,25 +6,12 @@
|
|
|
6
6
|
*/
|
|
7
7
|
|
|
8
8
|
import { KNOWN_CLAUDE_OPTIN_PLUGINS } from "./engine-native/parseModifiers";
|
|
9
|
+
import { isLegacyFlag, LEGACY_FLAG_HINTS } from "./engine-native/parseArgs";
|
|
9
10
|
import { modelCatalog } from "./engine-native/models";
|
|
10
11
|
import { advisorCatalog, advisorFlagGrammar, effortCatalog, effortFlagGrammar } from "./efforts";
|
|
11
12
|
import type { Tool } from "./manifests";
|
|
12
13
|
import type { ArgvSurfaces, FlagSurface, ScannedFlag } from "./argvSurface";
|
|
13
14
|
|
|
14
|
-
const LEGACY_HINTS: Readonly<Record<string, string>> = {
|
|
15
|
-
"--force": "--force was renamed to --reconcile",
|
|
16
|
-
"--remove-plugins":
|
|
17
|
-
"--remove-plugins was renamed to --prune (it also removes marketplaces + kit-managed skills)",
|
|
18
|
-
"--680k": "--680k was renamed to --claude-compact-window=680k",
|
|
19
|
-
"--permissive": "--permissive was renamed to --claude-permissive",
|
|
20
|
-
"--supabase": "--supabase was renamed to --claude-plugin=supabase",
|
|
21
|
-
"--n8n": "--n8n was renamed to --claude-plugin=n8n",
|
|
22
|
-
"--skip-rtk": "--skip-rtk was renamed to --skip-bubblewrap",
|
|
23
|
-
"--claude": "--claude was renamed: pass the target as a word, e.g. 'sync claude'",
|
|
24
|
-
"--codex": "--codex was renamed: pass the target as a word, e.g. 'sync codex'",
|
|
25
|
-
"--agents": "--agents was renamed: pass the target as a word, e.g. 'sync agents'",
|
|
26
|
-
};
|
|
27
|
-
|
|
28
15
|
const modelCatalogHint = (tool: Tool): string => {
|
|
29
16
|
const catalog = modelCatalog(tool);
|
|
30
17
|
const list = catalog.models
|
|
@@ -76,8 +63,7 @@ export const validateScannedArgv = (
|
|
|
76
63
|
|
|
77
64
|
if (subcommand === "sync") {
|
|
78
65
|
for (const flag of flags) {
|
|
79
|
-
|
|
80
|
-
if (hint !== undefined) return hint;
|
|
66
|
+
if (isLegacyFlag(flag.name)) return LEGACY_FLAG_HINTS[flag.name];
|
|
81
67
|
}
|
|
82
68
|
}
|
|
83
69
|
|
package/cli/src/commands/docs.ts
CHANGED
|
@@ -17,7 +17,7 @@ import commandGuards from "../../docs/command-guards.md" with { type: "text" };
|
|
|
17
17
|
const TOPICS: Record<string, { summary: string; body: string }> = {
|
|
18
18
|
overview: { summary: "What docks-kit is and how the pieces fit", body: overview },
|
|
19
19
|
"sync-layers": {
|
|
20
|
-
summary: "The
|
|
20
|
+
summary: "The four sync targets (claude, codex, agents, omp) and additive-by-default semantics",
|
|
21
21
|
body: syncLayers,
|
|
22
22
|
},
|
|
23
23
|
flags: { summary: "Full flag reference incl. the old→new rename table", body: flags },
|
package/cli/src/commands/omp.ts
CHANGED
|
@@ -23,8 +23,15 @@ import {
|
|
|
23
23
|
renderFreeOverlay,
|
|
24
24
|
type CatalogModel,
|
|
25
25
|
} from "../engine-native/ompOverlay";
|
|
26
|
-
import {
|
|
26
|
+
import {
|
|
27
|
+
FAST_ON_TIER,
|
|
28
|
+
requireDeployedConfig,
|
|
29
|
+
toggleDeployedOpenAiFast,
|
|
30
|
+
type FastToggle,
|
|
31
|
+
} from "../engine-native/ompFastMode";
|
|
27
32
|
import { ompPaths } from "../engine-native/ompPaths";
|
|
33
|
+
import { ExitError } from "../engine-native/parseArgs";
|
|
34
|
+
import { withHomeAndFolderLocks } from "../engine-native/syncDispatch";
|
|
28
35
|
|
|
29
36
|
const model = Flag.String("model").pipe(
|
|
30
37
|
Flag.withDescription("Free model selector to use and remember for omp sessions"),
|
|
@@ -251,6 +258,49 @@ const pickLevels = (catalogModel: CatalogModel) =>
|
|
|
251
258
|
return { thinking, advisorThinking };
|
|
252
259
|
});
|
|
253
260
|
|
|
261
|
+
/**
|
|
262
|
+
* Toggle fast mode under the sync lock of `home` and the folder lock of the
|
|
263
|
+
* omp agent folder, with the wait and the held line of a sync. A sync also
|
|
264
|
+
* merges `config.yml` there. Return 0 after the toggle, 1 for a held lock,
|
|
265
|
+
* and 2 for a failed toggle or an invalid wait bound.
|
|
266
|
+
*/
|
|
267
|
+
async function toggleFastUnderLocks(home: string, agentDir: string): Promise<number> {
|
|
268
|
+
const configPath = p(agentDir, "config.yml");
|
|
269
|
+
const err = (line: string) => console.error(line);
|
|
270
|
+
// Check config.yml before any lock. A missing file ends the run before the
|
|
271
|
+
// lock step can create the agent folder, and a folder that a sync creates
|
|
272
|
+
// during the home lock wait is never toggled without its folder lock.
|
|
273
|
+
try {
|
|
274
|
+
requireDeployedConfig(configPath);
|
|
275
|
+
} catch (error) {
|
|
276
|
+
err(error instanceof Error ? error.message : String(error));
|
|
277
|
+
return 2;
|
|
278
|
+
}
|
|
279
|
+
try {
|
|
280
|
+
return await withHomeAndFolderLocks(home, [agentDir], err, async () => {
|
|
281
|
+
let toggle: FastToggle;
|
|
282
|
+
try {
|
|
283
|
+
toggle = toggleDeployedOpenAiFast(configPath);
|
|
284
|
+
} catch (error) {
|
|
285
|
+
err(error instanceof Error ? error.message : String(error));
|
|
286
|
+
return 2;
|
|
287
|
+
}
|
|
288
|
+
const state = toggle.next === FAST_ON_TIER ? "ON" : "OFF";
|
|
289
|
+
console.log(
|
|
290
|
+
`omp fast mode ${state} for OpenAI/Codex models: tier.openai ${toggle.previous} -> ${toggle.next} in ${configPath}`,
|
|
291
|
+
);
|
|
292
|
+
console.log(
|
|
293
|
+
"New omp sessions use it; in a running session, use /fast on|off or restart omp.",
|
|
294
|
+
);
|
|
295
|
+
return 0;
|
|
296
|
+
});
|
|
297
|
+
} catch (error) {
|
|
298
|
+
// An invalid DOCKS_KIT_SYNC_LOCK_WAIT_MS prints its error line, then throws ExitError(2).
|
|
299
|
+
if (error instanceof ExitError) return error.code;
|
|
300
|
+
throw error;
|
|
301
|
+
}
|
|
302
|
+
}
|
|
303
|
+
|
|
254
304
|
export const ompCommand = Command.make("omp", { model, pick, fast, args }, (config) =>
|
|
255
305
|
Effect.gen(function* () {
|
|
256
306
|
// Check the forwarded arguments before omp, the catalog, or kit.db, so a
|
|
@@ -266,22 +316,13 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
|
|
|
266
316
|
if (Option.isSome(config.model) || config.pick || config.args.length > 0) {
|
|
267
317
|
return yield* bail("--fast toggles fast mode and exits; pass it alone");
|
|
268
318
|
}
|
|
269
|
-
const
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
);
|
|
274
|
-
const toggle = yield* Effect.try({
|
|
275
|
-
try: () => toggleDeployedOpenAiFast(configPath),
|
|
319
|
+
const home = engineHome(process.env);
|
|
320
|
+
const agentDir = ompPaths({ home, env: process.env, platform: process.platform }).agentDir;
|
|
321
|
+
const code = yield* Effect.tryPromise({
|
|
322
|
+
try: () => toggleFastUnderLocks(home, agentDir),
|
|
276
323
|
catch: (error) => (error instanceof Error ? error.message : String(error)),
|
|
277
324
|
}).pipe(Effect.catch((message) => bail(message)));
|
|
278
|
-
|
|
279
|
-
yield* Console.log(
|
|
280
|
-
`omp fast mode ${state} for OpenAI/Codex models: tier.openai ${toggle.previous} -> ${toggle.next} in ${configPath}`,
|
|
281
|
-
);
|
|
282
|
-
yield* Console.log(
|
|
283
|
-
"New omp sessions use it; in a running session, use /fast on|off or restart omp.",
|
|
284
|
-
);
|
|
325
|
+
if (code !== 0) return yield* Effect.sync(() => process.exit(code));
|
|
285
326
|
return;
|
|
286
327
|
}
|
|
287
328
|
|
package/cli/src/commands/sync.ts
CHANGED
|
@@ -1,27 +1,27 @@
|
|
|
1
1
|
import { Argument, Command, Flag } from "effect/cli";
|
|
2
2
|
import { Effect, Option } from "effect";
|
|
3
|
-
import { spawnSync } from "node:child_process";
|
|
4
3
|
import { existsSync } from "node:fs";
|
|
5
4
|
import { join } from "node:path";
|
|
6
5
|
import { bail, engine } from "../engine";
|
|
6
|
+
import { spawnHost } from "../engine-native/exec";
|
|
7
7
|
import type { Logger } from "../engine-native/logger";
|
|
8
8
|
import { kitHome } from "../kitHome";
|
|
9
9
|
import { LoggerService } from "../services";
|
|
10
10
|
|
|
11
11
|
/** Best-effort update autodetection: nudge (never block, never fail) when
|
|
12
12
|
* the kit checkout is behind its upstream. Silent on detached HEADs, no
|
|
13
|
-
* upstream, no network, no git.
|
|
14
|
-
|
|
13
|
+
* upstream, no network, no git. git starts through spawnHost, so a Windows
|
|
14
|
+
* host never runs a `git.exe` from the current directory. */
|
|
15
|
+
export const updateNudge = (logger: Logger): void => {
|
|
15
16
|
try {
|
|
16
17
|
const home = kitHome();
|
|
17
18
|
if (!existsSync(join(home, ".git"))) return;
|
|
18
19
|
if (
|
|
19
|
-
|
|
20
|
+
spawnHost("git", ["-C", home, "fetch", "--quiet"], { stdio: "ignore", timeout: 4000 })
|
|
20
21
|
.status !== 0
|
|
21
22
|
)
|
|
22
23
|
return;
|
|
23
|
-
const res =
|
|
24
|
-
encoding: "utf8",
|
|
24
|
+
const res = spawnHost("git", ["-C", home, "rev-list", "--count", "HEAD..@{u}"], {
|
|
25
25
|
stdio: ["ignore", "pipe", "ignore"],
|
|
26
26
|
});
|
|
27
27
|
const behind = (res.stdout ?? "").trim();
|