docks-kit 0.25.0 → 0.27.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 +12 -10
- package/README.md +40 -30
- package/cli/dist/docks-kit.js +24701 -0
- package/cli/docs/command-guards.md +8 -5
- package/cli/docs/install.md +41 -32
- package/cli/docs/omp-context.md +1 -1
- package/cli/docs/omp-models.md +1 -1
- package/cli/docs/overview.md +3 -3
- package/cli/docs/platforms.md +8 -8
- package/cli/src/agentDocs/agentFirstCheck.ts +786 -0
- package/cli/src/agentDocs/bridgeCheck.ts +226 -0
- package/cli/src/agentDocs/commands.ts +63 -0
- package/cli/src/agentDocs/prTemplate.ts +211 -0
- package/cli/src/agentDocs/services.ts +202 -0
- package/cli/src/agentDocs/shared.ts +730 -0
- package/cli/src/agentDocs/verifySkill.ts +136 -0
- package/cli/src/argv.ts +25 -1
- package/cli/src/commands/agentDocs.ts +29 -0
- package/cli/src/commands/plan.ts +29 -0
- package/cli/src/commands/skill.ts +29 -0
- package/cli/src/commands/update.ts +90 -66
- package/cli/src/engine-native/DESIGN.md +10 -9
- package/cli/src/engine-native/os/targets.ts +6 -19
- package/cli/src/engine.ts +0 -6
- package/cli/src/generated/sotPayload.ts +51 -79
- package/cli/src/kitHome.ts +7 -10
- package/cli/src/main.ts +12 -4
- package/cli/src/plan/bytes.ts +110 -0
- package/cli/src/plan/checkout.ts +379 -0
- package/cli/src/plan/commands.ts +1192 -0
- package/cli/src/plan/github.ts +816 -0
- package/cli/src/plan/records.ts +623 -0
- package/cli/src/plan/repository.ts +53 -0
- package/cli/src/plan/reviews.ts +292 -0
- package/cli/src/plan/services.ts +256 -0
- package/cli/src/plan/types.ts +164 -0
- package/cli/src/skills/commands.ts +142 -0
- package/cli/src/skills/config.json +30 -0
- package/cli/src/skills/files.ts +74 -0
- package/cli/src/skills/frontmatter.ts +148 -0
- package/cli/src/skills/guard.ts +366 -0
- package/cli/src/skills/kitGate.ts +406 -0
- package/cli/src/skills/rubric.ts +143 -0
- package/docks-kit +9 -40
- package/docks-kit.ps1 +10 -61
- package/package.json +10 -8
|
@@ -10,7 +10,7 @@ The policy keeps only deny rules. Where omp's critical-command check acts,
|
|
|
10
10
|
the form is denied. omp also denies a `$` or a backtick after `git push`,
|
|
11
11
|
because the agent can always write the ref literally.
|
|
12
12
|
|
|
13
|
-
By owner decision (0.22.8, #126), the kit ships no omp
|
|
13
|
+
By owner decision (0.22.8, DocksDocks/public#126), the kit ships no omp
|
|
14
14
|
prompt rule. The kit's `bash.patterns` holds only deny rules and the `trash *`
|
|
15
15
|
allow. Under omp's default `tools.approvalMode: yolo`, omp runs every
|
|
16
16
|
command that no deny matches without a question, in the main session and in
|
|
@@ -295,8 +295,8 @@ Write each new condition by these rules:
|
|
|
295
295
|
- Make each scan one frozen walk that stops at its first event and at the
|
|
296
296
|
next command start.
|
|
297
297
|
- Never put a group loop inside a lookaround over text of unbounded length.
|
|
298
|
-
- Run `bunx vitest run cli/test/unit/ompTriggerRules.test.ts`.
|
|
299
|
-
shape guard and the Bun backstop.
|
|
298
|
+
- Run `bunx vitest run cli/test/unit/ompTriggerRules.test.ts cli/test/unit/ompTriggerBackstop.test.ts`.
|
|
299
|
+
The first file runs the shape guard, and the second runs the Bun backstop.
|
|
300
300
|
- When you rewrite a condition, run the old and the new condition on each
|
|
301
301
|
buffer of the test table, and make sure that both give the same result.
|
|
302
302
|
|
|
@@ -314,8 +314,11 @@ must start with the forward key prefix, and this rejects the leading
|
|
|
314
314
|
lookbehind that froze omp. No `|` can stand outside every group, because the
|
|
315
315
|
alternative after it needs no key prefix. The shape guard cannot prove
|
|
316
316
|
linear time. The backstop tests the measured input families for linear
|
|
317
|
-
time:
|
|
318
|
-
the unit tests run on
|
|
317
|
+
time: `cli/test/unit/ompTriggerBackstop.test.ts` runs
|
|
318
|
+
`cli/test/lib/ompTriggerBackstop.ts` under Bun, because the unit tests run on
|
|
319
|
+
V8, which does not show the JavaScriptCore cost. That file is a Vitest project
|
|
320
|
+
of its own, which starts after every other unit file has ended, because the
|
|
321
|
+
backstop uses every core (DocksDocks/docks-kit#187). A
|
|
319
322
|
condition can still backtrack on a run that no generator holds, so a new
|
|
320
323
|
condition needs a new family when its shape is new. The backstop has these
|
|
321
324
|
checks:
|
package/cli/docs/install.md
CHANGED
|
@@ -1,21 +1,37 @@
|
|
|
1
1
|
# Installing docks-kit
|
|
2
2
|
|
|
3
3
|
Supported hosts are Linux x64/arm64, macOS arm64, and Windows x64.
|
|
4
|
-
Hosts outside this matrix fail before a launcher
|
|
4
|
+
Hosts outside this matrix fail before a launcher runs the Bun source.
|
|
5
5
|
|
|
6
6
|
## 1. Repo checkout (development / current users)
|
|
7
7
|
|
|
8
8
|
```
|
|
9
|
-
git clone https://github.com/DocksDocks/
|
|
10
|
-
cd ~/projects/
|
|
9
|
+
git clone https://github.com/DocksDocks/docks-kit.git ~/projects/docks-kit
|
|
10
|
+
cd ~/projects/docks-kit
|
|
11
11
|
./docks-kit sync
|
|
12
12
|
```
|
|
13
13
|
|
|
14
14
|
POSIX hosts use `./docks-kit`. Windows uses `.\docks-kit.ps1`. Each
|
|
15
|
-
launcher
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
15
|
+
launcher runs the checkout source with Bun and auto-installs Bun plus
|
|
16
|
+
`node_modules` when needed. A launcher never runs a file in `cli/dist/`.
|
|
17
|
+
|
|
18
|
+
### Move a checkout of DocksDocks/public
|
|
19
|
+
|
|
20
|
+
The kit moved from DocksDocks/public to DocksDocks/docks-kit. To move a
|
|
21
|
+
checkout of DocksDocks/public, run these commands from the checkout's root:
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
git remote set-url origin https://github.com/DocksDocks/docks-kit.git
|
|
25
|
+
./docks-kit update # Linux and macOS
|
|
26
|
+
.\docks-kit.ps1 update # Windows
|
|
27
|
+
./docks-kit sync # Linux and macOS
|
|
28
|
+
.\docks-kit.ps1 sync # Windows
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
The update pulls from DocksDocks/docks-kit and chains a sync that deploys the
|
|
32
|
+
skills with their new report target. The explicit sync covers an older
|
|
33
|
+
checkout whose launcher still runs a binary from `cli/dist/`, because that
|
|
34
|
+
binary does not chain the sync. A global npm install needs nothing.
|
|
19
35
|
|
|
20
36
|
## 2. Global via Bun
|
|
21
37
|
|
|
@@ -26,16 +42,20 @@ docks-kit sync
|
|
|
26
42
|
bunx docks-kit toolchain check
|
|
27
43
|
```
|
|
28
44
|
|
|
29
|
-
The npm package
|
|
30
|
-
|
|
45
|
+
The npm package runs one minified JavaScript bundle of the CLI and its generated
|
|
46
|
+
in-memory payload (`cli/dist/docks-kit.js`) — releases are versioned config
|
|
47
|
+
snapshots without publishing the authoring `SoT/` tree. Identifiers stay
|
|
48
|
+
unminified, so a stack trace keeps its names; the source map is a GitHub
|
|
49
|
+
release asset (`docks-kit.js.map`), matched by the bundle's `//# debugId=` line.
|
|
31
50
|
Kit-home resolution remains available for checkout/package update behavior and
|
|
32
51
|
display paths, but sync reads do not depend on it.
|
|
33
52
|
|
|
34
|
-
### Bun 1.4.
|
|
53
|
+
### Bun 1.4.5 install output
|
|
35
54
|
|
|
36
|
-
|
|
37
|
-
holds nine packages, and no package in it has an install script
|
|
38
|
-
untrusted`
|
|
55
|
+
An install of the package completes with no blocked postinstall. The graph
|
|
56
|
+
holds nine packages, and no package in it has an install script: `bun pm
|
|
57
|
+
untrusted` in the consumer folder (`bun pm -g untrusted` after a global
|
|
58
|
+
install) reports zero untrusted dependencies with scripts. Neither
|
|
39
59
|
`@parcel/watcher` nor `esbuild` is in the consumer graph.
|
|
40
60
|
|
|
41
61
|
The install prints no peer dependency warning. The root pins `effect`,
|
|
@@ -49,19 +69,19 @@ a copy that lags behind the pinned release.
|
|
|
49
69
|
## 3. curl installer (POSIX)
|
|
50
70
|
|
|
51
71
|
```
|
|
52
|
-
tmp="$(mktemp)" && curl -fsSL https://raw.githubusercontent.com/DocksDocks/
|
|
72
|
+
tmp="$(mktemp)" && curl -fsSL https://raw.githubusercontent.com/DocksDocks/docks-kit/main/install.sh -o "$tmp" && bash "$tmp"; rc=$?; rm -f "$tmp"; (exit "$rc")
|
|
53
73
|
```
|
|
54
74
|
|
|
55
75
|
Download-then-run, never `curl | bash` — stream truncation has bitten this
|
|
56
76
|
kit before. The installer bootstraps Bun when absent, runs
|
|
57
|
-
`bun add -g docks-kit@latest`, and links the
|
|
77
|
+
`bun add -g docks-kit@latest`, and links the CLI and Bun into `~/.local/bin`.
|
|
58
78
|
This installer serves the two POSIX platforms. Windows uses the PowerShell
|
|
59
79
|
installer below.
|
|
60
80
|
|
|
61
81
|
## 4. PowerShell installer (Windows)
|
|
62
82
|
|
|
63
83
|
```powershell
|
|
64
|
-
Invoke-WebRequest https://raw.githubusercontent.com/DocksDocks/
|
|
84
|
+
Invoke-WebRequest https://raw.githubusercontent.com/DocksDocks/docks-kit/main/install.ps1 -OutFile "$env:TEMP\docks-kit-install.ps1"
|
|
65
85
|
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP\docks-kit-install.ps1"
|
|
66
86
|
Remove-Item "$env:TEMP\docks-kit-install.ps1"
|
|
67
87
|
```
|
|
@@ -91,14 +111,11 @@ docks-kit update --no-sync # update only
|
|
|
91
111
|
directory whose `package.json` has the name `docks-kit`. An invalid value
|
|
92
112
|
causes an error instead of a fallback.
|
|
93
113
|
2. The CLI uses the nearest kit root at or above its own module directory.
|
|
94
|
-
3. Next, the CLI uses the nearest kit root at or above the
|
|
95
|
-
the executable. A standalone binary inside `<checkout>/cli/dist` therefore
|
|
96
|
-
resolves to the checkout.
|
|
97
|
-
4. Next, the CLI uses the nearest kit root at or above the current working
|
|
114
|
+
3. Next, the CLI uses the nearest kit root at or above the current working
|
|
98
115
|
directory, but only as a fallback.
|
|
99
|
-
|
|
116
|
+
4. Otherwise, the CLI uses the directory that holds the executable.
|
|
100
117
|
|
|
101
|
-
|
|
118
|
+
Source 2 identifies the installation that is running. A globally installed
|
|
102
119
|
`docks-kit` updates the global package even when you run it from inside a
|
|
103
120
|
docks-kit checkout. `DOCKS_KIT_HOME` lets you target a specific checkout on
|
|
104
121
|
purpose.
|
|
@@ -112,8 +129,6 @@ plain flag-less `docks-kit sync`. It also refreshes plugins, even when the kit
|
|
|
112
129
|
is already current: it moves `pi-intercom` to its pinned version. Pass
|
|
113
130
|
`--no-sync`, then run `docks-kit sync --skip-plugin-refresh` to keep a present
|
|
114
131
|
`pi-intercom` at its installed version.
|
|
115
|
-
A compiled binary inside a checkout updates the checkout; on the next invocation
|
|
116
|
-
the launcher bypasses that now-stale binary and uses updated source until rebuilt.
|
|
117
132
|
Every `docks-kit sync` except `--dry-run` also does a best-effort behind-upstream
|
|
118
133
|
check and nudges when the checkout is stale (silent offline / detached / no git).
|
|
119
134
|
|
|
@@ -151,20 +166,14 @@ npm install -g docks-kit@latest
|
|
|
151
166
|
|
|
152
167
|
Verified on Bun 1.4.2 and npm 11, each in a clean HOME.
|
|
153
168
|
|
|
154
|
-
## No-Bun recovery
|
|
155
|
-
|
|
156
|
-
No Bun or constrained sandbox: download the platform release binary from GitHub
|
|
157
|
-
Releases and run it directly. No checkout or `DOCKS_KIT_HOME` is required for
|
|
158
|
-
sync/config reads.
|
|
159
|
-
|
|
160
169
|
## Prerequisites
|
|
161
170
|
|
|
162
|
-
- Bun for
|
|
171
|
+
- Bun for every install: the checkout launchers and the npm package both run on Bun
|
|
163
172
|
- npm for an npm-installed kit
|
|
164
173
|
- jq is optional doctor/test tooling; sync has no jq runtime dependency
|
|
165
174
|
- curl is needed only to download Bun's upstream installer when Bun is absent:
|
|
166
175
|
by the POSIX `docks-kit` launcher, by the POSIX `install.sh`, and by sync's
|
|
167
|
-
Bun bootstrap on every host
|
|
176
|
+
Bun bootstrap on every host
|
|
168
177
|
(`docks-kit toolchain ensure bun` too). `docks-kit.ps1` and `install.ps1`
|
|
169
178
|
download Bun's installer with Invoke-WebRequest. An already-present Bun needs
|
|
170
179
|
no curl.
|
package/cli/docs/omp-context.md
CHANGED
|
@@ -124,7 +124,7 @@ keys carries a kit value that differs from the default omp already applies.
|
|
|
124
124
|
|
|
125
125
|
## omp 19.0.0 tools and returned overrides
|
|
126
126
|
|
|
127
|
-
The owner made these decisions on 2026-11-19 (#184). They apply from 0.24.0.
|
|
127
|
+
The owner made these decisions on 2026-11-19 (DocksDocks/public#184). They apply from 0.24.0.
|
|
128
128
|
|
|
129
129
|
### Tools that the kit turns on
|
|
130
130
|
|
package/cli/docs/omp-models.md
CHANGED
|
@@ -523,7 +523,7 @@ At `high`, Sol produces about 19% more tokens per second than Terra. At
|
|
|
523
523
|
`xhigh`, the gain is about 24%. Sol also has the lower TTFT and end-to-end
|
|
524
524
|
time at both levels.
|
|
525
525
|
|
|
526
|
-
The `reviewer` role stays on GPT-6.1 Terra `high`. The #130 benchmark chose
|
|
526
|
+
The `reviewer` role stays on GPT-6.1 Terra `high`. The DocksDocks/public#130 benchmark chose
|
|
527
527
|
Terra by escaped defects, not by speed. omp 18.22.2 lists no GPT-6.2 Terra. A
|
|
528
528
|
move of the reviewer to GPT-6.2 Sol needs a new benchmark.
|
|
529
529
|
|
package/cli/docs/overview.md
CHANGED
|
@@ -11,10 +11,10 @@ AI-assisted dev environment on every machine.
|
|
|
11
11
|
|-------|------|
|
|
12
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 |
|
|
13
13
|
| `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
|
|
14
|
-
| `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in
|
|
14
|
+
| `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in the npm bundle |
|
|
15
15
|
| `cli/src/engine-native/` | EngineNative mutation logic for sync/toolchain and the `docks-kit omp` session overlay |
|
|
16
16
|
| `cli/` | This CLI (Effect 4 on Bun) plus bundled docs |
|
|
17
|
-
| `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers:
|
|
17
|
+
| `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers: host check → Bun-from-source, with Bun auto-install |
|
|
18
18
|
|
|
19
19
|
## Design rules
|
|
20
20
|
|
|
@@ -24,7 +24,7 @@ AI-assisted dev environment on every machine.
|
|
|
24
24
|
summary; `--verbose` / `-v` also prints the no-op confirmations.
|
|
25
25
|
- **Additive by default**: user-only keys and plugins survive a plain sync.
|
|
26
26
|
- **Engine/CLI split**: the CLI adds UX (typed flags, pickers, docs, JSON);
|
|
27
|
-
EngineNative owns mutation.
|
|
27
|
+
EngineNative owns mutation. Every install runs on Bun.
|
|
28
28
|
- **Authoring/runtime split**: changes begin in `SoT/`; build/prepack freshness
|
|
29
29
|
checks keep the generated in-memory payload byte-identical for every runtime.
|
|
30
30
|
|
package/cli/docs/platforms.md
CHANGED
|
@@ -3,16 +3,16 @@
|
|
|
3
3
|
The supported host matrix is exact: Linux on x64 and arm64, macOS on arm64,
|
|
4
4
|
and Windows on x64.
|
|
5
5
|
|
|
6
|
-
| Platform | Architecture |
|
|
7
|
-
|
|
8
|
-
| Linux | x64 |
|
|
9
|
-
| Linux | arm64 |
|
|
10
|
-
| macOS | arm64 |
|
|
11
|
-
| Windows | x64 |
|
|
6
|
+
| Platform | Architecture | Sync engine |
|
|
7
|
+
|----------|--------------|-------------|
|
|
8
|
+
| Linux | x64 | EngineNative (TS) |
|
|
9
|
+
| Linux | arm64 | EngineNative (TS) |
|
|
10
|
+
| macOS | arm64 | EngineNative (TS) |
|
|
11
|
+
| Windows | x64 | EngineNative (TS) |
|
|
12
12
|
|
|
13
13
|
POSIX hosts use the `docks-kit` launcher. Windows uses `docks-kit.ps1`.
|
|
14
|
-
Hosts outside this table fail before either launcher
|
|
15
|
-
|
|
14
|
+
Hosts outside this table fail before either launcher runs the Bun source.
|
|
15
|
+
The POSIX launcher and `install.sh` read the architecture of the
|
|
16
16
|
shell with `uname -m`. On an Apple silicon Mac, a shell that runs under
|
|
17
17
|
Rosetta reports `x86_64` and gets the unsupported-host message, so run
|
|
18
18
|
docks-kit from a native arm64 shell.
|