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.
Files changed (46) hide show
  1. package/AGENTS.md +12 -10
  2. package/README.md +40 -30
  3. package/cli/dist/docks-kit.js +24701 -0
  4. package/cli/docs/command-guards.md +8 -5
  5. package/cli/docs/install.md +41 -32
  6. package/cli/docs/omp-context.md +1 -1
  7. package/cli/docs/omp-models.md +1 -1
  8. package/cli/docs/overview.md +3 -3
  9. package/cli/docs/platforms.md +8 -8
  10. package/cli/src/agentDocs/agentFirstCheck.ts +786 -0
  11. package/cli/src/agentDocs/bridgeCheck.ts +226 -0
  12. package/cli/src/agentDocs/commands.ts +63 -0
  13. package/cli/src/agentDocs/prTemplate.ts +211 -0
  14. package/cli/src/agentDocs/services.ts +202 -0
  15. package/cli/src/agentDocs/shared.ts +730 -0
  16. package/cli/src/agentDocs/verifySkill.ts +136 -0
  17. package/cli/src/argv.ts +25 -1
  18. package/cli/src/commands/agentDocs.ts +29 -0
  19. package/cli/src/commands/plan.ts +29 -0
  20. package/cli/src/commands/skill.ts +29 -0
  21. package/cli/src/commands/update.ts +90 -66
  22. package/cli/src/engine-native/DESIGN.md +10 -9
  23. package/cli/src/engine-native/os/targets.ts +6 -19
  24. package/cli/src/engine.ts +0 -6
  25. package/cli/src/generated/sotPayload.ts +51 -79
  26. package/cli/src/kitHome.ts +7 -10
  27. package/cli/src/main.ts +12 -4
  28. package/cli/src/plan/bytes.ts +110 -0
  29. package/cli/src/plan/checkout.ts +379 -0
  30. package/cli/src/plan/commands.ts +1192 -0
  31. package/cli/src/plan/github.ts +816 -0
  32. package/cli/src/plan/records.ts +623 -0
  33. package/cli/src/plan/repository.ts +53 -0
  34. package/cli/src/plan/reviews.ts +292 -0
  35. package/cli/src/plan/services.ts +256 -0
  36. package/cli/src/plan/types.ts +164 -0
  37. package/cli/src/skills/commands.ts +142 -0
  38. package/cli/src/skills/config.json +30 -0
  39. package/cli/src/skills/files.ts +74 -0
  40. package/cli/src/skills/frontmatter.ts +148 -0
  41. package/cli/src/skills/guard.ts +366 -0
  42. package/cli/src/skills/kitGate.ts +406 -0
  43. package/cli/src/skills/rubric.ts +143 -0
  44. package/docks-kit +9 -40
  45. package/docks-kit.ps1 +10 -61
  46. 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`. It runs the
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: the test runs `cli/test/lib/ompTriggerBackstop.ts` under Bun, because
318
- the unit tests run on V8, which does not show the JavaScriptCore cost. A
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:
@@ -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 can fall back to Bun source.
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/public.git ~/projects/public
10
- cd ~/projects/public
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 prefers a compiled binary in `cli/dist/` only when its reported
16
- version matches `package.json`. It then falls back to Bun-from-source and
17
- auto-installs Bun plus `node_modules` when needed. Each launcher reports and
18
- bypasses an ignored stale build.
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 bundles the CLI and its generated in-memory payload — releases
30
- are versioned config snapshots without publishing the authoring `SoT/` tree.
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.4 install output
53
+ ### Bun 1.4.5 install output
35
54
 
36
- A supported global install completes with no blocked postinstall. The graph
37
- holds nine packages, and no package in it has an install script. `bun pm -g
38
- untrusted` reports zero untrusted dependencies with scripts. Neither
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/public/main/install.sh -o "$tmp" && bash "$tmp"; rc=$?; rm -f "$tmp"; (exit "$rc")
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 binary into `~/.local/bin`.
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/public/main/install.ps1 -OutFile "$env:TEMP\docks-kit-install.ps1"
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 directory that holds
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
- 5. Otherwise, the CLI uses the directory that holds the executable.
116
+ 4. Otherwise, the CLI uses the directory that holds the executable.
100
117
 
101
- Sources 2 and 3 identify the installation that is running. A globally installed
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 source/global installs; release binaries embed the runtime
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, release binaries included
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.
@@ -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
 
@@ -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
 
@@ -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 standalone/npm execution |
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: version-matching compiled binary → Bun-from-source, with Bun auto-install |
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. No-Bun recovery is a platform release binary.
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
 
@@ -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 | docks-kit binary | Sync engine |
7
- |----------|--------------|------------------|-------------|
8
- | Linux | x64 | `docks-kit-linux-x64` | EngineNative (TS) |
9
- | Linux | arm64 | `docks-kit-linux-arm64` | EngineNative (TS) |
10
- | macOS | arm64 | `docks-kit-darwin-arm64` | EngineNative (TS) |
11
- | Windows | x64 | `docks-kit-windows-x64.exe` | EngineNative (TS) |
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 can fall back to Bun
15
- source. The POSIX launcher and `install.sh` read the architecture of the
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.