docks-kit 0.23.0 → 0.25.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 +22 -138
- package/README.md +38 -23
- package/cli/docs/command-guards.md +5 -3
- package/cli/docs/flags.md +11 -29
- package/cli/docs/install.md +5 -4
- package/cli/docs/omp-context.md +79 -7
- package/cli/docs/omp-models.md +22 -15
- package/cli/docs/overview.md +5 -8
- package/cli/docs/sync-layers.md +55 -83
- package/cli/docs/toolchain.md +7 -8
- package/cli/src/argv.ts +0 -4
- package/cli/src/argvValidate.ts +2 -9
- package/cli/src/commands/docs.ts +2 -2
- package/cli/src/commands/omp.ts +1 -1
- package/cli/src/commands/scratch.ts +1 -1
- package/cli/src/commands/sync.ts +3 -24
- package/cli/src/commands/tidy.ts +1 -1
- package/cli/src/commands/update.ts +3 -3
- package/cli/src/engine-native/DESIGN.md +24 -35
- package/cli/src/engine-native/deps.ts +2 -7
- package/cli/src/engine-native/engineCtx.ts +3 -31
- package/cli/src/engine-native/failures.ts +2 -2
- package/cli/src/engine-native/index.ts +2 -2
- package/cli/src/engine-native/kitDb.ts +21 -37
- package/cli/src/engine-native/ompChild.ts +1 -1
- package/cli/src/engine-native/ompFastMode.ts +1 -1
- package/cli/src/engine-native/ompKitPlugin.ts +7 -16
- package/cli/src/engine-native/ompOverlay.ts +1 -1
- package/cli/src/engine-native/ompPlugins.ts +205 -221
- package/cli/src/engine-native/ompRemovals.ts +24 -3
- package/cli/src/engine-native/ompSession.ts +67 -0
- package/cli/src/engine-native/ompSync.ts +6 -15
- package/cli/src/engine-native/os/posix.ts +0 -1
- package/cli/src/engine-native/os/types.ts +0 -4
- package/cli/src/engine-native/os/windows.ts +0 -1
- package/cli/src/engine-native/parseArgs.ts +1 -61
- package/cli/src/engine-native/parseHelp.ts +1 -6
- package/cli/src/engine-native/scratch.ts +1 -1
- package/cli/src/engine-native/sharedTypes.d.ts +1 -1
- package/cli/src/engine-native/syncConcurrency.ts +3 -3
- package/cli/src/engine-native/syncDispatch.ts +26 -92
- package/cli/src/engine-native/toolchain.ts +1 -5
- package/cli/src/generated/sotPayload.ts +339 -17
- package/cli/src/main.ts +3 -7
- package/cli/tsconfig.json +1 -0
- package/package.json +2 -2
- package/cli/src/checklistPrompt.ts +0 -464
- package/cli/src/commands/harnesses.ts +0 -77
- package/cli/src/commands/skills.ts +0 -40
- package/cli/src/engine-native/harnesses.ts +0 -138
- package/cli/src/engine-native/ompMarketplace.ts +0 -140
- package/cli/src/engine-native/skillsInstall.ts +0 -135
- package/cli/src/engine-native/skillsLinks.ts +0 -216
- package/cli/src/engine-native/skillsManifest.ts +0 -36
- package/cli/src/engine-native/skillsPrune.ts +0 -117
- package/cli/src/engine-native/skillsRecords.ts +0 -138
- package/cli/src/engine-native/skillsSync.ts +0 -57
- package/cli/src/manifests.ts +0 -53
- package/cli/src/terminalCells.ts +0 -191
package/cli/docs/omp-context.md
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
# omp context and compaction
|
|
2
2
|
|
|
3
3
|
This topic records why `SoT/.omp/config.yml` ships no compaction threshold,
|
|
4
|
-
and what omp's reserve-based default computes on each model lane.
|
|
4
|
+
and what omp's reserve-based default computes on each model lane. It also
|
|
5
|
+
records the omp 19.0.0 tools that the kit turns on and the kit overrides that
|
|
6
|
+
0.24.0 returned to the omp defaults.
|
|
5
7
|
|
|
6
8
|
## How omp resolves the trigger
|
|
7
9
|
|
|
@@ -100,13 +102,13 @@ No current role model has a window below 272,000, so the hazard was latent
|
|
|
100
102
|
rather than live. Not pinning removes it entirely, including for any future
|
|
101
103
|
model with a smaller window.
|
|
102
104
|
|
|
103
|
-
## Idle compaction is
|
|
105
|
+
## Idle compaction is off
|
|
104
106
|
|
|
105
|
-
`SoT/.omp/config.yml`
|
|
106
|
-
`false`
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
107
|
+
Up to 0.23.0, `SoT/.omp/config.yml` set `compaction.idleEnabled: true`. In
|
|
108
|
+
0.24.0 the owner returned the key to the omp default `false` (omp 18.4.4
|
|
109
|
+
through 19.0.0). Sync prunes a deployed `true` that the kit shipped, so idle
|
|
110
|
+
compaction is off. With the default threshold settings, only the
|
|
111
|
+
reserve-based trigger starts a compaction.
|
|
110
112
|
|
|
111
113
|
## Related settings left at their omp defaults
|
|
112
114
|
|
|
@@ -119,3 +121,73 @@ key turns idle compaction off on fresh installs.
|
|
|
119
121
|
|
|
120
122
|
Every row records a decision to leave the omp default in place. None of these
|
|
121
123
|
keys carries a kit value that differs from the default omp already applies.
|
|
124
|
+
|
|
125
|
+
## omp 19.0.0 tools and returned overrides
|
|
126
|
+
|
|
127
|
+
The owner made these decisions on 2026-11-19 (#184). They apply from 0.24.0.
|
|
128
|
+
|
|
129
|
+
### Tools that the kit turns on
|
|
130
|
+
|
|
131
|
+
- `astGrep.enabled: true` gives the `ast_grep` tool. It searches code by its
|
|
132
|
+
syntax tree (AST), on the local disk only.
|
|
133
|
+
- `checkpoint.enabled: true` gives the `checkpoint` and `rewind` tools.
|
|
134
|
+
`checkpoint` marks the start of an investigation. `rewind` replaces the
|
|
135
|
+
transcript after that mark with a short report. It restores no file, git
|
|
136
|
+
state, artifact, or process, and a rule line in `SoT/.omp/AGENTS.md` says
|
|
137
|
+
so. A subagent gets the two tools only when its tool list asks for one of
|
|
138
|
+
them.
|
|
139
|
+
|
|
140
|
+
The memory backend (`memory.backend: off`), `autolearn.enabled`, and
|
|
141
|
+
`prewalk.enabled` stay off. All three are off by default, so the SoT has no
|
|
142
|
+
key for them. Every other omp 19.0.0 feature keeps its omp default, for
|
|
143
|
+
example context notes, `security_scan`, `task.crossInstance`,
|
|
144
|
+
`mcp.evalNamespaces`, and cache warming. The advisor stays removed (0.22.22).
|
|
145
|
+
|
|
146
|
+
### Overrides returned to the omp defaults
|
|
147
|
+
|
|
148
|
+
The SoT no longer ships these 18 keys. `ompRemovals.ts OMP_RETIRED_VALUES`
|
|
149
|
+
records each key with its old kit value. Sync prunes a deployed key only
|
|
150
|
+
while it holds that value, so a value that you changed stays.
|
|
151
|
+
|
|
152
|
+
| Key | Old kit value | omp 19.0.0 default |
|
|
153
|
+
|---|---|---|
|
|
154
|
+
| `task.maxConcurrency` | `16` | `32` |
|
|
155
|
+
| `task.maxEffort` | `xhigh` | `max` |
|
|
156
|
+
| `task.maxRuntimeMs` | `3600000` | `0` |
|
|
157
|
+
| `task.agentIdleTtlMs` | `120000` | `420000` |
|
|
158
|
+
| `task.enableLsp` | `true` | `false` |
|
|
159
|
+
| `task.eager` | `always` | `default` |
|
|
160
|
+
| `task.showResolvedModelBadge` | `true` | `false` |
|
|
161
|
+
| `find.enabled` | `true` | `auto` |
|
|
162
|
+
| `providers.webSearchTimeoutSeconds` | `30` | `60` |
|
|
163
|
+
| `browser.idleCloseSec` | `600` | `1800` |
|
|
164
|
+
| `steeringMode` | `all` | `one-at-a-time` |
|
|
165
|
+
| `doubleEscapeAction` | `tree` | `rewind` |
|
|
166
|
+
| `features.unexpectedStopDetection` | `smart` | `mechanical` |
|
|
167
|
+
| `compaction.idleEnabled` | `true` | `false` |
|
|
168
|
+
| `compaction.handoffSaveToDisk` | `true` | `false` |
|
|
169
|
+
| `commands.enableOpencodeProject` | `false` | `true` |
|
|
170
|
+
| `statusLine.compactThinkingLevel` | `false` | `true` |
|
|
171
|
+
| `github.enabled` | `true` | `false` |
|
|
172
|
+
|
|
173
|
+
Sync cannot tell the old kit value from the same value that you set again.
|
|
174
|
+
It prunes both on every sync. To keep an old kit value, set it in a project
|
|
175
|
+
configuration or in a `PI_CONFIG_FILES` file, which sync does not write.
|
|
176
|
+
|
|
177
|
+
The `github` tool is off by default. Its `pr_push` operation runs git
|
|
178
|
+
directly, so the `bash.patterns` guards do not see it. The `issue://` and
|
|
179
|
+
`pr://` read schemes do not need the tool. omp reads them through its GitHub
|
|
180
|
+
cache and `gh` (`omp://tools/read.md`, `omp://tools/github.md`), so they still
|
|
181
|
+
work with `github.enabled: false`. The plan-lifecycle work reads issues with
|
|
182
|
+
`gh` in bash, so the change does not affect it.
|
|
183
|
+
|
|
184
|
+
### Overrides that stay
|
|
185
|
+
|
|
186
|
+
- `branchSummary.enabled: true`.
|
|
187
|
+
- `dev.autoqa: false` with `dev.autoqaConsent: denied`.
|
|
188
|
+
- `codexResets.autoRedeem5h: "no"` and `codexResets.autoRedeemWeekly: "no"`.
|
|
189
|
+
- `startup.quiet: true`.
|
|
190
|
+
- `display.showTokenUsage: true`.
|
|
191
|
+
- The model roles, `cycleOrder`, `retry.fallbackChains`, `modelTags`, the
|
|
192
|
+
reviewer overrides in `task.agentModelOverrides` and
|
|
193
|
+
`task.agentServiceTierOverrides`, and the `bash.patterns` guards.
|
package/cli/docs/omp-models.md
CHANGED
|
@@ -128,14 +128,15 @@ What omp's settings catalog establishes about these roles:
|
|
|
128
128
|
model for every reviewer. `task.agentServiceTierOverrides` sets the same four
|
|
129
129
|
agents to `inherit`, so they take the live tier of the main session for each
|
|
130
130
|
provider. "OpenAI fast mode" below describes how that tier changes. The bundled
|
|
131
|
-
`reviewer` and `security-reviewer` agents ship with omp, and the
|
|
132
|
-
`
|
|
131
|
+
`reviewer` and `security-reviewer` agents ship with omp, and the kit plugin
|
|
132
|
+
`docks-kit-omp` ships `code-reviewer` and `plan-reviewer`.
|
|
133
133
|
`retry.fallbackChains.reviewer` holds `anthropic/claude-opus-5-5:high`, and
|
|
134
134
|
`retry.fallbackChains.task` holds `openai-codex/gpt-6.2-sol:high`; both are
|
|
135
135
|
cross-vendor fallbacks.
|
|
136
136
|
|
|
137
137
|
The review benchmark of DocksDocks/public#130 ran on 2026-11-05. It used 24
|
|
138
|
-
held-out cases of the
|
|
138
|
+
held-out cases of the `review-benchmark` skill, 2 runs each. The cases came
|
|
139
|
+
from DocksDocks/docks, the source repository of that skill at the time.
|
|
139
140
|
It compared `gpt-6.1-sol` and `gpt-6.1-terra` at `high`, each on the `default`
|
|
140
141
|
and `priority` tiers. The user set the effort `high`; the benchmark chose the
|
|
141
142
|
model. `gpt-6.1-terra` on `default` let the fewest known defects escape (34.90
|
|
@@ -656,13 +657,15 @@ keeps a block that the user edited.
|
|
|
656
657
|
not onto level names: `lo` selects the lowest level, `med` the lower middle,
|
|
657
658
|
and `hi` the highest (`resolveTaskEffortLevel` in omp's
|
|
658
659
|
`packages/tui/src/thinking.ts`, omp 18.8.5). Then omp caps the result at
|
|
659
|
-
`task.maxEffort`.
|
|
660
|
-
`
|
|
661
|
-
despite the `:high` role suffix. On
|
|
662
|
-
18.16.0 with the field off had no
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
660
|
+
`task.maxEffort`. Up to 0.23.0 the kit set that cap to `xhigh`. On the
|
|
661
|
+
`low, medium, high, xhigh, max` ladder, `hi` then gave `xhigh`, so many
|
|
662
|
+
`task` spawns ran Opus 5.5 xhigh despite the `:high` role suffix. On
|
|
663
|
+
2026-11-05, a fresh `omp -p` run on omp 18.16.0 with the field off had no
|
|
664
|
+
`effort` field, and its `task` child recorded
|
|
665
|
+
`resolvedModel: anthropic/claude-opus-5-5:high`.
|
|
666
|
+
- Since 0.24.0 the kit sets no `task.maxEffort`, so the cap is omp's default
|
|
667
|
+
`max`. With `task.enableEffort` off, the cap applies only to a per-call
|
|
668
|
+
`model` with a `:level` suffix.
|
|
666
669
|
- In the deployed config, `scout` and `sonic` run GPT-6 Luna `medium`. The
|
|
667
670
|
four reviewer agents resolve `@reviewer` and run GPT-6.1 Terra `high` on the
|
|
668
671
|
live tier of the main session. A `docks-kit omp` free session replaces
|
|
@@ -702,9 +705,10 @@ web-search provider order therefore applies, and that order includes the paid
|
|
|
702
705
|
deployed retry chain, such as a `plan`, `slow`, or `designer` chain, therefore
|
|
703
706
|
stays in the merged config. A retry of the free model does not reach such a
|
|
704
707
|
chain, because omp uses the empty chain keyed by the free model first.
|
|
705
|
-
The overlay also sets `defaultThinkingLevel` and `task.maxEffort
|
|
706
|
-
a model that publishes no thinking ladder,
|
|
707
|
-
deployed or
|
|
708
|
+
The overlay also sets `defaultThinkingLevel` and `task.maxEffort` to the
|
|
709
|
+
session level. For a model that publishes no thinking ladder, the overlay
|
|
710
|
+
omits both keys. A value in the deployed config then applies, or else the omp
|
|
711
|
+
default, which is `max` for `task.maxEffort`.
|
|
708
712
|
|
|
709
713
|
The launcher renders a run overlay to
|
|
710
714
|
`~/.cache/docks-kit/omp-free-<model>-<digest>.yml` at mode 0600 and passes it
|
|
@@ -800,7 +804,7 @@ bare selectors with no `:level` suffix, because an invented level makes omp
|
|
|
800
804
|
fail when the session starts.
|
|
801
805
|
|
|
802
806
|
The choice persists per machine in `~/.docks-kit/kit.db` (table
|
|
803
|
-
`omp_session`)
|
|
807
|
+
`omp_session`). It survives across sessions. It is never
|
|
804
808
|
committed. `--model <selector>` records one selector and derives the level
|
|
805
809
|
from the catalog row. `--pick` opens an interactive wizard.
|
|
806
810
|
|
|
@@ -915,4 +919,7 @@ on normal processing, use `docks-kit omp --fast` and a new session, not
|
|
|
915
919
|
- Update the capture date in the same commit as any number.
|
|
916
920
|
- Verify Astra ladder changes in `SoT/.omp/models.yml` through the model
|
|
917
921
|
switcher and in-session thinking control.
|
|
918
|
-
-
|
|
922
|
+
- The kit leaves `task.maxEffort` and `task.enableEffort` at omp's defaults,
|
|
923
|
+
`max` and `false`. After an omp update, check both in
|
|
924
|
+
`omp config list --json`. Verify a kit change to either key with a fresh
|
|
925
|
+
`omp -p` spawn per bundled agent.
|
package/cli/docs/overview.md
CHANGED
|
@@ -1,15 +1,14 @@
|
|
|
1
1
|
# docks-kit overview
|
|
2
2
|
|
|
3
|
-
docks-kit is a portable configuration kit for AI coding agents.
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
docks-kit is a portable configuration kit for AI coding agents. Its Single
|
|
4
|
+
Source of Truth (SoT) directory `SoT/.omp/` deploys to the user-config location
|
|
5
|
+
of Oh My Pi (`omp`). Clone once, sync everywhere, and get a consistent
|
|
6
6
|
AI-assisted dev environment on every machine.
|
|
7
7
|
|
|
8
8
|
## Pieces
|
|
9
9
|
|
|
10
10
|
| Piece | Role |
|
|
11
11
|
|-------|------|
|
|
12
|
-
| `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
|
|
13
12
|
| `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 |
|
|
14
13
|
| `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
|
|
15
14
|
| `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
|
|
@@ -23,9 +22,7 @@ AI-assisted dev environment on every machine.
|
|
|
23
22
|
- **Quiet on no-ops**: by default a re-run prints only real changes, warnings
|
|
24
23
|
(with a platform-correct install command when a tool is missing), and the
|
|
25
24
|
summary; `--verbose` / `-v` also prints the no-op confirmations.
|
|
26
|
-
- **Additive by default**: user-only keys
|
|
27
|
-
Removing kit-managed universal skills that left the SoT is explicit:
|
|
28
|
-
`--prune`.
|
|
25
|
+
- **Additive by default**: user-only keys and plugins survive a plain sync.
|
|
29
26
|
- **Engine/CLI split**: the CLI adds UX (typed flags, pickers, docs, JSON);
|
|
30
27
|
EngineNative owns mutation. No-Bun recovery is a platform release binary.
|
|
31
28
|
- **Authoring/runtime split**: changes begin in `SoT/`; build/prepack freshness
|
|
@@ -34,5 +31,5 @@ AI-assisted dev environment on every machine.
|
|
|
34
31
|
## Where to go next
|
|
35
32
|
|
|
36
33
|
- `docks-kit docs sync-layers` — what a sync actually touches
|
|
37
|
-
- `docks-kit docs flags` — full flag reference
|
|
34
|
+
- `docks-kit docs flags` — full flag reference
|
|
38
35
|
- `docks-kit toolchain` — doctor view of this machine's external tools
|
package/cli/docs/sync-layers.md
CHANGED
|
@@ -1,13 +1,12 @@
|
|
|
1
1
|
# Sync layers
|
|
2
2
|
|
|
3
|
-
`docks-kit sync
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
healing, and the kit-owned record that `--prune` removes against.
|
|
3
|
+
`docks-kit sync` deploys the omp SoT. It takes no positional target. Sync
|
|
4
|
+
writes no `.agents` or `.claude` folder of its own; omp's folders follow
|
|
5
|
+
`PI_CONFIG_DIR`, `PI_CODING_AGENT_DIR`, and `XDG_DATA_HOME`, so an override
|
|
6
|
+
that points into one of those folders makes omp's files go there. omp uses
|
|
7
|
+
`XDG_DATA_HOME` only on Linux and macOS, only while `PI_CODING_AGENT_DIR`
|
|
8
|
+
does not move the agent folder, and only after the omp folder under it
|
|
9
|
+
exists. Sync also writes the kit plugin to `~/.docks-kit/omp-plugin`.
|
|
11
10
|
|
|
12
11
|
## omp (→ resolved agent dir, intercom root)
|
|
13
12
|
|
|
@@ -26,83 +25,53 @@ retired in 0.22.8), config.yml keys whose deployed value still equals the value
|
|
|
26
25
|
ship, `providers.webSearchOrder` at any value, and the retired
|
|
27
26
|
`providers.anthropic.modelOverrides.claude-opus-5-5` block in models.yml while
|
|
28
27
|
it still matches the shipped block.
|
|
29
|
-
Directories are mode 0700 and files mode 0600. Then the
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
`SoT/toolchain.json` pin
|
|
33
|
-
marketplace row counts as installed only when its `scope` is `user`, so a repeat
|
|
34
|
-
run is a no-op and a project-only row still installs. When just the legacy
|
|
35
|
-
config-root registry lists `docks`, omp copies it forward itself: the sync runs
|
|
36
|
-
`marketplace update`, or the read-only `marketplace list` under
|
|
37
|
-
`--skip-plugin-refresh`, which keeps installs but fetches nothing. After a
|
|
38
|
-
plugin operation, the sync reads the inventory again and prints one line that
|
|
39
|
-
names each plugin with its version change, for example
|
|
40
|
-
`omp plugins synced: docks@docks 0.21.1 -> 0.22.0, pi-intercom 0.14.0 (new), docks-kit-omp linked`.
|
|
41
|
-
|
|
42
|
-
omp deletes the previous plugin folder on `omp plugin upgrade`. A running omp
|
|
43
|
-
session then loses the plugin agents of that folder. A test on omp 18.16.0
|
|
44
|
-
showed that `/reload-plugins` brings the agents back, and that `skill://`
|
|
45
|
-
resolves to the new folder (#139). The omp marketplace docs still ask for a
|
|
46
|
-
restart for hooks, extension modules, and non-MCP tools. For each marketplace
|
|
47
|
-
upgrade that changed the version, the sync prints a warning, for example
|
|
48
|
-
`omp plugin docks@docks 0.21.1 -> 0.22.0: running omp sessions lose its plugin agents until they run /reload-plugins and read its skills again through skill:// (restart omp instead when the plugin ships hooks, extension modules, or non-MCP tools).`
|
|
49
|
-
The next step then says
|
|
50
|
-
`Run /reload-plugins in each running omp session, then read each plugin skill again through skill://. Restart omp instead when an upgraded plugin ships hooks, extension modules, or non-MCP tools.`
|
|
51
|
-
A version-changing upgrade does not set the restart trigger. Each other plugin
|
|
52
|
-
operation sets it: an install, a reinstall at the same version, an npm install,
|
|
53
|
-
or a link. A changed kit plugin file or omp config file also sets it. The
|
|
54
|
-
restart next step `Restart omp to load any refreshed plugins, skills, or tools.`
|
|
55
|
-
then prints next to the upgrade rule.
|
|
56
|
-
|
|
57
|
-
The sync also writes one event file for each such upgrade into the upgrade log
|
|
58
|
-
`~/.cache/docks-kit/omp-plugin-upgrades/` (folder 0700, files 0600). The file
|
|
59
|
-
name is `<finishedAt ms>-<random>.json`, and the file holds
|
|
60
|
-
`{"version":1,"id":"<id>","before":"<v>","after":"<v>","finishedAt":"<ISO time>"}`.
|
|
61
|
-
`finishedAt` is the time just after the upgrade command returned. Each sync
|
|
62
|
-
writes only new files, through a temporary name and a rename, so concurrent
|
|
63
|
-
syncs keep all events. Then it removes the oldest files beyond the newest 100.
|
|
28
|
+
Directories are mode 0700 and files mode 0600. Then the plugin pass reads the
|
|
29
|
+
inventory from `omp plugin list --json`, tries to retire the former marketplace
|
|
30
|
+
plugins (user-scope installs only; see below), installs `pi-intercom` at its
|
|
31
|
+
`SoT/toolchain.json` pin, and links the kit plugin `docks-kit-omp`.
|
|
64
32
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
`
|
|
68
|
-
Each
|
|
69
|
-
the
|
|
70
|
-
|
|
33
|
+
The kit plugin now ships the docks and plan-lifecycle skills, the
|
|
34
|
+
`code-reviewer` and `plan-reviewer` agents, and the `verify-gate` and
|
|
35
|
+
`context-tree-nudge` extensions. So sync installs no plugin from the `docks`
|
|
36
|
+
marketplace. Each real sync tries to retire the former marketplace plugins.
|
|
37
|
+
When the inventory cannot be read, it warns and skips this step; a later sync
|
|
38
|
+
tries again. Otherwise:
|
|
71
39
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
40
|
+
- For each of `docks@docks` and `plan-lifecycle@docks` with a `scope: "user"`
|
|
41
|
+
inventory row, it runs `omp plugin uninstall --scope user <id>`.
|
|
42
|
+
- For each `scope: "project"` row of these ids, it changes nothing in that
|
|
43
|
+
project and warns
|
|
44
|
+
`omp plugin <id> is installed at project scope and docks-kit no longer ships it; run from that project: omp plugin uninstall --scope project <id>`.
|
|
45
|
+
- When no user uninstall failed, it runs `omp plugin marketplace remove docks`
|
|
46
|
+
if the active registry (`<data root>/marketplaces.json`) lists `docks`, or
|
|
47
|
+
if no active registry exists and the legacy config-root registry lists it.
|
|
48
|
+
omp copies the legacy registry forward only when no active registry exists,
|
|
49
|
+
so a legacy entry beside an active registry is stale and starts no command.
|
|
50
|
+
- A failed uninstall or removal goes to the failure ledger with the manual
|
|
51
|
+
command, for example
|
|
52
|
+
`omp plugin operation failed for docks@docks: <detail>; run manually: omp plugin uninstall --scope user docks@docks`.
|
|
53
|
+
- When the inventory cannot be read, the sync warns
|
|
54
|
+
`omp plugin inventory unavailable — retirement of the docks marketplace plugins skipped until the next sync; pi-intercom and the kit plugin take the full refresh path`.
|
|
55
|
+
- The sync removes the folder `~/.cache/docks-kit/omp-plugin-upgrades/` of the
|
|
56
|
+
retired plugin upgrade log when it exists.
|
|
78
57
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
did not get before. The reminder names each plugin with its version change. It
|
|
83
|
-
says that the plugin agents of the session may fail. It tells the agent to ask
|
|
84
|
-
the user to run `/reload-plugins`. It then tells the agent to read each plugin
|
|
85
|
-
skill again through `skill://` before it runs a skill script. It asks for a
|
|
86
|
-
restart instead when an upgraded plugin ships hooks, extension modules, or
|
|
87
|
-
non-MCP tools. A folder or file that the extension cannot read gives no
|
|
88
|
-
reminder for that tool result. The next tool result reads it again.
|
|
89
|
-
These limits apply:
|
|
58
|
+
`--skip-plugin-refresh` does not skip the retirement or the kit plugin link. It
|
|
59
|
+
only keeps a present `pi-intercom` at its installed version. A repeat run after
|
|
60
|
+
a successful retirement runs no uninstall and no removal.
|
|
90
61
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
folder. For this reason, the reminder says "may".
|
|
100
|
-
- An omp process that started during the upgrade can get a reminder that it
|
|
101
|
-
does not need. A reload or a restart is harmless.
|
|
102
|
-
- The log keeps the newest 100 events. A session that stays idle through more
|
|
103
|
-
than 100 later upgrades loses the oldest ones.
|
|
62
|
+
After a plugin operation, the sync prints one line that names each operation,
|
|
63
|
+
for example
|
|
64
|
+
`omp plugins synced: docks@docks uninstalled, plan-lifecycle@docks uninstalled, docks marketplace removed, pi-intercom 0.14.0 (new), docks-kit-omp linked`.
|
|
65
|
+
Each uninstall sets the restart next step
|
|
66
|
+
`Restart omp to load any refreshed plugins, skills, or tools.`, because the
|
|
67
|
+
retired plugins ship extensions, and omp loads extensions only at startup. An
|
|
68
|
+
npm install, a link, and a changed kit plugin file or omp config file also set
|
|
69
|
+
it.
|
|
104
70
|
|
|
105
|
-
A dry run invokes no omp subcommand
|
|
71
|
+
A dry run invokes no omp subcommand. It prints
|
|
72
|
+
`[dry-run] omp plugin uninstall --scope user docks@docks` and the same line
|
|
73
|
+
for `plan-lifecycle@docks`, and
|
|
74
|
+
`[dry-run] omp plugin marketplace remove docks` when a registry lists `docks`.
|
|
106
75
|
|
|
107
76
|
Paths mirror upstream `dirs.ts` `DirResolver`, resolved from the environment
|
|
108
77
|
plus directory probes, so a dry run still runs no omp subcommand. The agent
|
|
@@ -118,7 +87,10 @@ into `<agent directory>/intercom`. Otherwise it goes into
|
|
|
118
87
|
`$PI_CODING_AGENT_DIR/intercom` when that variable is set, else
|
|
119
88
|
`~/.pi/agent/intercom`.
|
|
120
89
|
|
|
121
|
-
##
|
|
90
|
+
## Additive by default
|
|
122
91
|
|
|
123
|
-
|
|
124
|
-
|
|
92
|
+
Sync has no removal flag. A key, plugin, or file that only the user added
|
|
93
|
+
stays. Three passes remove kit content on every sync: the `ompRemovals.ts`
|
|
94
|
+
retired-key inventory above, the kit plugin pass, which removes stale files
|
|
95
|
+
from the kit-owned `~/.docks-kit/omp-plugin`, and the retirement of the former
|
|
96
|
+
marketplace plugins above, which earlier kit versions installed.
|
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 a package that the kit installs through another tool
|
|
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, such as `omp install` for `pi-intercom`; the required `via` field names that tool in the doctor table) |
|
|
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 |
|
|
@@ -31,15 +31,14 @@ an installer. An already-present Bun skips that download on every host.
|
|
|
31
31
|
|
|
32
32
|
## Supply-chain stance
|
|
33
33
|
|
|
34
|
-
Every kit-driven package install from npm,
|
|
34
|
+
Every kit-driven package install from npm, GitHub releases, or
|
|
35
35
|
`omp install` is pinned to a `SoT/toolchain.json` `verified` version — never
|
|
36
36
|
floating `@latest` (the npm-worm / Shai-Hulud attack surface). That includes
|
|
37
|
-
the
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
manifest pin first.
|
|
37
|
+
the release workflow (actions pinned to commit SHAs, exact bun/npm versions).
|
|
38
|
+
The kit installs no omp marketplace plugin: the kit plugin ships from this
|
|
39
|
+
repository, and sync tries to retire the user-scope installs of the former `docks` marketplace plugins (see
|
|
40
|
+
`sync-layers`). Any new install surface, a new marketplace or plugin source
|
|
41
|
+
included, needs a manifest pin first.
|
|
43
42
|
|
|
44
43
|
The kit's own package is the single exemption from the `@latest` ban. `install.sh` and `install.ps1`
|
|
45
44
|
end with `bun add -g docks-kit@latest` because a global installer that pinned
|
package/cli/src/argv.ts
CHANGED
|
@@ -1,7 +1,5 @@
|
|
|
1
1
|
import { GlobalFlag } from "effect/cli";
|
|
2
2
|
import { docsCommand } from "./commands/docs";
|
|
3
|
-
import { harnessesCommand } from "./commands/harnesses";
|
|
4
|
-
import { skillsCommand } from "./commands/skills";
|
|
5
3
|
import { syncCommand } from "./commands/sync";
|
|
6
4
|
import { toolchainCommand } from "./commands/toolchain";
|
|
7
5
|
import { updateCommand } from "./commands/update";
|
|
@@ -28,10 +26,8 @@ export type ArgvOutcome =
|
|
|
28
26
|
*/
|
|
29
27
|
export const COMMANDS = [
|
|
30
28
|
syncCommand,
|
|
31
|
-
harnessesCommand,
|
|
32
29
|
updateCommand,
|
|
33
30
|
toolchainCommand,
|
|
34
|
-
skillsCommand,
|
|
35
31
|
docsCommand,
|
|
36
32
|
ompCommand,
|
|
37
33
|
scratchCommand,
|
package/cli/src/argvValidate.ts
CHANGED
|
@@ -1,10 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Per-command validation for the Effect CLI layer:
|
|
3
|
-
*
|
|
2
|
+
* Per-command validation for the Effect CLI layer: unknown-command/flag
|
|
3
|
+
* detection, and boolean-value and duplicate rejection.
|
|
4
4
|
* Operates on scanned flags so the grammar machinery stays in argvSurface.ts.
|
|
5
5
|
*/
|
|
6
6
|
|
|
7
|
-
import { isLegacyFlag, LEGACY_FLAG_HINTS } from "./engine-native/parseArgs";
|
|
8
7
|
import type { ArgvSurfaces, FlagSurface, ScannedFlag } from "./argvSurface";
|
|
9
8
|
|
|
10
9
|
/**
|
|
@@ -25,12 +24,6 @@ export const validateScannedArgv = (
|
|
|
25
24
|
return `unknown command '${subcommand}'`;
|
|
26
25
|
}
|
|
27
26
|
|
|
28
|
-
if (subcommand === "sync") {
|
|
29
|
-
for (const flag of flags) {
|
|
30
|
-
if (isLegacyFlag(flag.name)) return LEGACY_FLAG_HINTS[flag.name];
|
|
31
|
-
}
|
|
32
|
-
}
|
|
33
|
-
|
|
34
27
|
// Effect 4 expands clustered shorts, but the kit declares no clusterable alias
|
|
35
28
|
// pair, so refusing a cluster as one unknown flag is the conservative direction.
|
|
36
29
|
for (const flag of flags) {
|
package/cli/src/commands/docs.ts
CHANGED
|
@@ -14,10 +14,10 @@ import commandGuards from "../../docs/command-guards.md" with { type: "text" };
|
|
|
14
14
|
const TOPICS: Record<string, { summary: string; body: string }> = {
|
|
15
15
|
overview: { summary: "What docks-kit is and how the pieces fit", body: overview },
|
|
16
16
|
"sync-layers": {
|
|
17
|
-
summary: "
|
|
17
|
+
summary: "How sync deploys the omp SoT, and its additive-by-default semantics",
|
|
18
18
|
body: syncLayers,
|
|
19
19
|
},
|
|
20
|
-
flags: { summary: "Full flag reference
|
|
20
|
+
flags: { summary: "Full flag reference", body: flags },
|
|
21
21
|
toolchain: {
|
|
22
22
|
summary: "Verified-version floors, the doctor table, and the upstream outdated report",
|
|
23
23
|
body: toolchain,
|
package/cli/src/commands/omp.ts
CHANGED
|
@@ -4,7 +4,7 @@ import { Argument, Command } from "effect/cli";
|
|
|
4
4
|
import { Console, Effect } from "effect";
|
|
5
5
|
|
|
6
6
|
import { bail } from "../engine";
|
|
7
|
-
import { engineHome } from "../engine-native/
|
|
7
|
+
import { engineHome } from "../engine-native/ompSession";
|
|
8
8
|
import {
|
|
9
9
|
allowedRemovalRoots,
|
|
10
10
|
createScratchDir,
|
package/cli/src/commands/sync.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { Command, Flag } from "effect/cli";
|
|
2
2
|
import { Effect } from "effect";
|
|
3
3
|
import { existsSync } from "node:fs";
|
|
4
4
|
import { join } from "node:path";
|
|
5
|
-
import {
|
|
5
|
+
import { engine } from "../engine";
|
|
6
6
|
import { spawnHost } from "../engine-native/exec";
|
|
7
7
|
import type { Logger } from "../engine-native/logger";
|
|
8
8
|
import { kitHome } from "../kitHome";
|
|
@@ -35,21 +35,10 @@ export const updateNudge = (logger: Logger): void => {
|
|
|
35
35
|
}
|
|
36
36
|
};
|
|
37
37
|
|
|
38
|
-
const VALID_TARGETS = ["agents", "omp"];
|
|
39
|
-
|
|
40
|
-
const targets: Argument.Argument<ReadonlyArray<string>> = Argument.String("target").pipe(
|
|
41
|
-
Argument.withDescription("Sync targets: agents, omp (default: selected harnesses)"),
|
|
42
|
-
Argument.variadic(),
|
|
43
|
-
);
|
|
44
|
-
|
|
45
38
|
const dryRun = Flag.Boolean("dry-run").pipe(
|
|
46
39
|
Flag.withDescription("Preview without applying"),
|
|
47
40
|
Flag.withDefault(false),
|
|
48
41
|
);
|
|
49
|
-
const prune = Flag.Boolean("prune").pipe(
|
|
50
|
-
Flag.withDescription("Remove kit-managed universal skills not in SoT/.agents/skills.txt"),
|
|
51
|
-
Flag.withDefault(false),
|
|
52
|
-
);
|
|
53
42
|
const skipPluginRefresh = Flag.Boolean("skip-plugin-refresh").pipe(
|
|
54
43
|
Flag.withDescription(
|
|
55
44
|
"Install missing plugins but skip refresh-only updates for existing plugins",
|
|
@@ -65,24 +54,14 @@ const verbose = Flag.Boolean("verbose").pipe(
|
|
|
65
54
|
export const syncCommand = Command.make(
|
|
66
55
|
"sync",
|
|
67
56
|
{
|
|
68
|
-
targets,
|
|
69
57
|
dryRun,
|
|
70
|
-
prune,
|
|
71
58
|
skipPluginRefresh,
|
|
72
59
|
verbose,
|
|
73
60
|
},
|
|
74
61
|
(config) =>
|
|
75
62
|
Effect.gen(function* () {
|
|
76
|
-
const
|
|
77
|
-
if (bad.length > 0) {
|
|
78
|
-
return yield* bail(
|
|
79
|
-
`Unknown sync target(s): ${bad.join(", ")} (valid: ${VALID_TARGETS.join(", ")})`,
|
|
80
|
-
);
|
|
81
|
-
}
|
|
82
|
-
|
|
83
|
-
const args: Array<string> = ["sync", ...config.targets];
|
|
63
|
+
const args: Array<string> = ["sync"];
|
|
84
64
|
if (config.dryRun) args.push("--dry-run");
|
|
85
|
-
if (config.prune) args.push("--prune");
|
|
86
65
|
if (config.skipPluginRefresh) args.push("--skip-plugin-refresh");
|
|
87
66
|
if (config.verbose) args.push("--verbose");
|
|
88
67
|
|
package/cli/src/commands/tidy.ts
CHANGED
|
@@ -4,7 +4,7 @@ import { Command, Flag } from "effect/cli";
|
|
|
4
4
|
import { Console, Effect, Option } from "effect";
|
|
5
5
|
|
|
6
6
|
import { bail } from "../engine";
|
|
7
|
-
import { engineHome } from "../engine-native/
|
|
7
|
+
import { engineHome } from "../engine-native/ompSession";
|
|
8
8
|
import { acquireKitLock, releaseKitLock } from "../engine-native/kitLock";
|
|
9
9
|
import { scratchRoot, tidyApplyLockPath } from "../engine-native/scratch";
|
|
10
10
|
import {
|
|
@@ -202,8 +202,8 @@ const updateCheckout = (home: string, skipSync: boolean) =>
|
|
|
202
202
|
if (!pull.ok) return yield* bail(`git pull --ff-only failed (diverged history?):\n${pull.out}`);
|
|
203
203
|
const after = git(home, ["rev-parse", "HEAD"]).out;
|
|
204
204
|
|
|
205
|
-
// A current kit still syncs: the
|
|
206
|
-
//
|
|
205
|
+
// A current kit still syncs: the sync repairs drift of the deployed files
|
|
206
|
+
// and plugins, for example a pi-intercom install that left its pin.
|
|
207
207
|
const changed = before !== after;
|
|
208
208
|
if (changed) {
|
|
209
209
|
const count = git(home, ["rev-list", "--count", `${before}..${after}`]).out;
|
|
@@ -312,6 +312,6 @@ export const updateCommand = Command.make("update", { noSync }, (config) =>
|
|
|
312
312
|
}),
|
|
313
313
|
).pipe(
|
|
314
314
|
Command.withDescription(
|
|
315
|
-
"Self-update the kit: autodetects the install (git checkout -> ff-only pull; bun/npm global -> @latest), then chains a flag-less sync that also refreshes
|
|
315
|
+
"Self-update the kit: autodetects the install (git checkout -> ff-only pull; bun/npm global -> @latest), then chains a flag-less sync that also refreshes plugins, even when the kit was already current (--no-sync to skip).",
|
|
316
316
|
),
|
|
317
317
|
);
|