docks-kit 0.26.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 CHANGED
@@ -10,7 +10,7 @@ Portable configuration kit for AI coding agents. The kit manages one coding harn
10
10
 
11
11
  omp uses this `AGENTS.md` file plus the omp SoT under `SoT/.omp/`.
12
12
 
13
- docks-kit runtime and standalone binary support covers Linux x64/arm64, macOS arm64, and Windows x64. Hosts outside this matrix fail before either launcher can fall back to Bun source.
13
+ docks-kit host support covers Linux x64/arm64, macOS arm64, and Windows x64. Hosts outside this matrix fail before either launcher runs the Bun source.
14
14
 
15
15
  ## Context tree
16
16
 
@@ -26,19 +26,19 @@ Per-folder conventions live in nested `AGENTS.md` nodes. An agent can load only
26
26
 
27
27
  | Path | Purpose |
28
28
  |------|---------|
29
- | `docks-kit` / `docks-kit.ps1` | POSIX and Windows CLI launchers. On supported hosts, each runs the matching binary in `cli/dist/` only when its `--version` matches `package.json` and no file under `cli/src/` or `cli/docs/` is newer than the binary. Otherwise it runs Bun-from-source and auto-installs Bun plus `node_modules`, and the mismatch or newer-source warning names the rebuild remedy. A launcher never deletes a binary: on a host without Bun it is the only remaining recovery path. Hosts outside the support matrix fail before source fallback. The standalone platform release binary provides no-Bun recovery. |
29
+ | `docks-kit` / `docks-kit.ps1` | POSIX and Windows CLI launchers. Each rejects a host outside the support matrix, then runs the checkout source with Bun and auto-installs Bun plus `node_modules` when they are missing. A launcher never runs a file in `cli/dist/`. |
30
30
  | `.oxlintrc.json` / `bunfig.toml` | Mechanical lint (correctness, suspicious, eqeqeq, no-var, prefer-const, no-unused) and the `bun fmt` code format settings (`[fmt]`) |
31
31
  | `cli/` | Effect 4 CLI + bundled docs topics |
32
32
  | `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative; optional `upstream` source read by `docks-kit toolchain outdated`) |
33
33
  | `SoT/.omp/` | Kit-owned omp SoT: `AGENTS.md`, `config.yml`, `models.yml`, `mcp.json`, `intercom.json`, and the kit plugin source `plugin/` |
34
34
  | `install.sh` / `install.ps1` | POSIX and Windows global installers. Each installer stops on a host outside the support matrix before it downloads anything. |
35
- | `.github/workflows/release-cli.yml` | `cli-v*` release: four binaries (Linux x64 and arm64, macOS arm64, Windows x64), plus `SHA256SUMS`, the bundle's source map `docks-kit.js.map`, and npm publish |
35
+ | `.github/workflows/release-cli.yml` | `cli-v*` release: attaches the bundle's source map `docks-kit.js.map` to the GitHub release and publishes the npm package with provenance |
36
36
  | `README.md` | Front door |
37
37
  | `package.json` / `bun.lock` | npm package: `bin` = `cli/dist/docks-kit.js`, a minified bundle of the CLI and the generated in-memory SoT payload that `prepack` builds (`bun run build:bundle`); `cli/src` ships too, for the checkout launchers |
38
38
  | `docs/PLAN.md` | Plan pointer and project plan rules. The plan record is a GitHub issue; no plan markdown is tracked. `docs/AGENTS.md` routes to it. |
39
39
  | `AGENTS.md` | This file — tool-agnostic instructions |
40
40
 
41
- Module map for `cli/` (engine axes, commands, kit store, test fixtures, and the release-binary build `bun run build:binaries`): `cli/AGENTS.md`.
41
+ Module map for `cli/` (engine axes, commands, kit store, test fixtures, and the build scripts): `cli/AGENTS.md`.
42
42
 
43
43
  SoT notes (the shared prompt authorization, the omp deploy targets, the config and model merges, the retired inventories, the role map, the kit plugin sync, and the cleanup scope): `cli/AGENTS.md` (`### SoT notes`).
44
44
 
@@ -67,12 +67,14 @@ SoT notes (the shared prompt authorization, the omp deploy targets, the config a
67
67
  - **Exemption: the kit's own package.** `install.sh` and `install.ps1` end with `bun add -g docks-kit@latest`, because a global installer that pinned itself would install a fixed old kit forever, and pinning it to `package.json` would request an unpublished version between the release-prep commit and the npm publish. The `@latest` exemption covers `docks-kit` alone. Both installers still pin the Bun installer they download to the manifest's verified version. `cli/test/unit/hostTargets.test.ts` asserts that pin in all four launcher and installer scripts, and `cli/test/unit/install.test.ts` proves `install.sh` passes it to the Bun installer. Any new install surface, a new marketplace or plugin source included, needs a manifest pin first.
68
68
  ## Testing
69
69
 
70
- Run `bun run check` before and after each change: oxlint, `lint:effect` (Effect rules through `effect-tsgo diagnostics --strict`), `bun fmt --check`, `bun check`, the generated-payload check (`check:generated`), unit tests, and both golden suites. Scripts: `lint`, `lint:effect`, `format:check`, `typecheck`, `check:generated`, `test:unit`, `test:integration` (goldens), `test`, `format`; CI runs `check` on pushes to `main` and on pull requests with Bun 1.4.4. Prove-red modes must exit non-zero after detecting planted mismatches. The golden writer emits two-space JSON that `bun fmt` re-serializes, so run `bun run format` after `--update-goldens` or `format:check` fails. For Effect diagnostics in the editor, set the TypeScript language server command to `node_modules/.bin/effect-tsgo tsc --lsp --stdio`. Keep the `@effect/language-service` plugin entry in `cli/tsconfig.json`: without it, `lint:effect` checks no file and passes. Also verify user-facing changes via `./docks-kit sync --dry-run` and `bun run smoke:native`.
70
+ Run `bun run check` before and after each change: oxlint, `lint:effect` (Effect rules through `effect-tsgo diagnostics --strict`), `bun fmt --check`, `bun check`, the generated-payload check (`check:generated`), unit tests, and both golden suites. Scripts: `lint`, `lint:effect`, `format:check`, `typecheck`, `check:generated`, `test:unit`, `test:integration` (goldens), `test`, `format`; CI runs `check` on pushes to `main` and on pull requests with Bun 1.4.5. Prove-red modes must exit non-zero after detecting planted mismatches. The golden writer emits two-space JSON that `bun fmt` re-serializes, so run `bun run format` after `--update-goldens` or `format:check` fails. For Effect diagnostics in the editor, set the TypeScript language server command to `node_modules/.bin/effect-tsgo tsc --lsp --stdio`. Keep the `@effect/language-service` plugin entry in `cli/tsconfig.json`: without it, `lint:effect` checks no file and passes. Also verify user-facing changes via `./docks-kit sync --dry-run` and `bun run smoke:package`.
71
71
 
72
72
  Use direct acceptance and focused regressions while iterating, then run the full unit/golden gate once at the pre-commit or release boundary. Reuse still-matching evidence; a later relevant edit invalidates only the affected rung and final gate, not every prior check.
73
73
 
74
74
  Spawning-suite bundle and `DOCKS_KIT_TEST_CLI_ENTRY`: `cli/AGENTS.md`.
75
75
 
76
+ `test:unit` also runs the vitest project `review-benchmark` on Linux only, because its `keys.mjs` needs GNU tar and one test needs the util-linux `script` command. It needs `git`, `gpg`, GNU tar, and full history with `origin/main`; run `git fetch --unshallow` in a shallow clone. Its fixtures are real omp transcripts: after a raise of the omp `verified` pin in `SoT/toolchain.json`, capture new fixtures as `.agents/skills/review-benchmark/SKILL.md` says. `test:unit:portable` runs the `unit` and `backstop` projects only; the `portable` CI job and the release gate `test:ci` use it, because their checkouts are shallow and the `check` job already runs the suite.
77
+
76
78
  ## Landing changes
77
79
 
78
80
  Open a pull request when the change can alter what CI proves: `cli/`, `SoT/`, `.github/`, the launchers, the installers, `package.json`, `bun.lock`. Wait for every reported check to finish, then ask before merge. A failed or cancelled check blocks the merge. Push direct to `main` only for prose: root Markdown and code comments.
package/README.md CHANGED
@@ -19,26 +19,18 @@ cd ~/projects/docks-kit
19
19
  ```
20
20
 
21
21
  POSIX hosts use the `./docks-kit` launcher on Linux x64 and arm64 and on macOS
22
- arm64. Windows uses `.\docks-kit.ps1` on x64. Each launcher prefers the matching compiled
23
- binary in `cli/dist/` only when its version matches the checkout. Otherwise it
24
- runs from source via Bun and auto-installs Bun plus dependencies when needed.
25
- Hosts outside this matrix fail immediately and never fall back to Bun source.
26
- Stale ignored build artifacts cannot mask newer checkout code.
22
+ arm64. Windows uses `.\docks-kit.ps1` on x64. Each launcher runs the checkout
23
+ source with Bun and auto-installs Bun plus dependencies when needed. Hosts
24
+ outside this matrix fail immediately and never reach the Bun source.
27
25
 
28
26
  Other install paths include global `bun add -g docks-kit`, the POSIX curl
29
27
  installer, and the Windows PowerShell installer. See `./docks-kit docs install`.
30
28
 
31
- **No-Bun recovery path**:
32
-
33
- Download the platform release binary from GitHub Releases and run it directly.
34
- The executable carries the generated sync payload; no checkout or adjacent
35
- `SoT/` directory is required.
36
-
37
- Source and global installs require Bun. An npm-global install needs npm.
29
+ Every install requires Bun. An npm-global install needs npm.
38
30
  `jq` is optional doctor/test tooling. `curl` is needed only to download Bun's
39
31
  upstream installer when Bun is absent: by the POSIX launcher and installer, and
40
- by sync's Bun bootstrap, which a release binary can also run. The Windows
41
- launcher and installer use Invoke-WebRequest.
32
+ by sync's Bun bootstrap. The Windows launcher and installer use
33
+ Invoke-WebRequest.
42
34
 
43
35
  ### Move a checkout of DocksDocks/public
44
36
 
@@ -53,9 +45,10 @@ git remote set-url origin https://github.com/DocksDocks/docks-kit.git
53
45
  .\docks-kit.ps1 sync # Windows
54
46
  ```
55
47
 
56
- The update pulls from DocksDocks/docks-kit. The sync then deploys the skills
57
- with their new report target: a launcher that runs a fresh compiled binary
58
- skips the sync that the update chains. A global npm install needs nothing.
48
+ The update pulls from DocksDocks/docks-kit and chains a sync that deploys the
49
+ skills with their new report target. The explicit sync covers an older
50
+ checkout whose launcher still runs a binary from `cli/dist/`, because that
51
+ binary does not chain the sync. A global npm install needs nothing.
59
52
 
60
53
  ## CLI
61
54
 
@@ -151,17 +144,17 @@ Report a problem with a skill, an agent, or the kit in
151
144
  | `SoT/.omp/` | omp SoT (AGENTS.md, config.yml, models.yml, mcp.json, intercom.json, and the `plugin/` source of `docks-kit-omp`) |
152
145
  | `SoT/toolchain.json` | Verified-version floors |
153
146
  | `cli/src/engine-native/` | EngineNative sync/toolchain implementation |
154
- | `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by standalone and npm installs |
147
+ | `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by npm installs |
155
148
  | `cli/` | docks-kit CLI (Effect 4 on Bun) + bundled docs topics |
156
- | `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers (binary → Bun-from-source) |
149
+ | `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers (Bun-from-source) |
157
150
  | `install.sh` / `install.ps1` | POSIX and Windows global installers |
158
151
  | `docs/PLAN.md` | Plan pointer and project plan rules; plans are GitHub issues |
159
152
  | `AGENTS.md` | Agent-facing engineering rules |
160
153
 
161
154
  ## Platform support
162
155
 
163
- | Platform | Architecture | docks-kit binary | Sync engine |
164
- |----------|--------------|------------------|-------------|
156
+ | Platform | Architecture | docks-kit CLI | Sync engine |
157
+ |----------|--------------|---------------|-------------|
165
158
  | Linux | x64 | ✅ | ✅ native |
166
159
  | Linux | arm64 | ✅ | ✅ native |
167
160
  | macOS | arm64 | ✅ | ✅ native |
@@ -171,12 +164,9 @@ Details: `docks-kit docs platforms`.
171
164
 
172
165
  ## Releases
173
166
 
174
- Tagging `cli-v*` builds four standalone binaries: `docks-kit-linux-x64`,
175
- `docks-kit-linux-arm64`, `docks-kit-darwin-arm64`, and
176
- `docks-kit-windows-x64.exe`. The workflow attaches them plus `SHA256SUMS` and the
177
- bundle's source map `docks-kit.js.map` to the GitHub release. npm publishes the
178
- exact package tarball through trusted publishing with OIDC provenance.
179
- Published binaries, checksums, and release notes are available on
167
+ Tagging `cli-v*` attaches the bundle's source map `docks-kit.js.map` to the
168
+ GitHub release. npm publishes the exact package tarball through trusted
169
+ publishing with OIDC provenance. Source maps and release notes are available on
180
170
  [GitHub Releases](https://github.com/DocksDocks/docks-kit/releases).
181
171
  Each `docks-kit` npm release runs one minified JavaScript bundle of the CLI and
182
172
  its generated payload (`cli/dist/docks-kit.js`), so releases are versioned config