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
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` 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
- | `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` with the generated in-memory SoT payload |
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.
@@ -87,8 +89,8 @@ Project-skill authoring rules (scope, canonical layout, vendored `unslop`, citat
87
89
 
88
90
  ## Kit plugin content
89
91
 
90
- `SoT/.omp/plugin/` holds skills at `skills/<name>/SKILL.md`, task agents at `agents/<name>.md`, and the extensions that `package.json` `omp.extensions` names. It ships the 32 docks and plan-lifecycle skills, the `workspace-hygiene` skill, the `code-reviewer` and `plan-reviewer` agents, the `hygiene`, `verify-gate`, and `context-tree-nudge` extensions, the trigger rules in `rules/`, and the `/cleanup` command. A skill reports a problem in DocksDocks/public. `bun run check` checks this content with four tests in `cli/test/unit/plugin/`: `skills.test.ts` (layout and name, frontmatter, report section, shared copies, references, durable anchors, transform guard, trigger collisions, score floor), `contentHash.test.ts`, `agents.test.ts` (agent rules, score floor), and `extensions.test.ts` (each entry imports and has a default function export).
91
- After a skill edit, run `bun cli/scripts/skill-content-hash.ts --write` to refresh its `metadata.content_hash` and `metadata.updated`; `--check` names each stale skill. The check code and its data (floors, report section, shared-copy groups, transform list) are in `cli/scripts/pluginContent/`.
92
+ `SoT/.omp/plugin/` holds skills at `skills/<name>/SKILL.md`, task agents at `agents/<name>.md`, and the extensions that `package.json` `omp.extensions` names. It ships the 32 docks and plan-lifecycle skills, the `workspace-hygiene` skill, the `code-reviewer` and `plan-reviewer` agents, the `hygiene`, `verify-gate`, and `context-tree-nudge` extensions, the trigger rules in `rules/`, and the `/cleanup` command. A skill reports a problem in DocksDocks/docks-kit. `bun run check` checks this content with four tests in `cli/test/unit/plugin/`: `skills.test.ts` (layout and name, frontmatter, report section, shared copies, references, durable anchors, transform guard, trigger collisions, score floor), `contentHash.test.ts`, `agents.test.ts` (agent rules, score floor), and `extensions.test.ts` (each entry imports and has a default function export).
93
+ After a skill edit, run `bun cli/scripts/skill-content-hash.ts --write` to refresh its `metadata.content_hash` and `metadata.updated`; `--check` names each stale skill. The skill checks, the 16-point rubric, and the check data in `config.json` (floors, report section, shared-copy groups, transform list) are in `cli/src/skills/`, which `docks-kit skill guard` and `docks-kit skill score` also use; the agent, reference, trigger, extension, and content-hash checks are in `cli/scripts/pluginContent/`.
92
94
 
93
95
  ## Plans
94
96
 
@@ -102,8 +104,8 @@ Per the agents.md open standard, place an `AGENTS.md` inside any subdirectory th
102
104
 
103
105
  ```bash
104
106
  # Clone and sync the kit
105
- git clone <this-repo> ~/projects/public
106
- cd ~/projects/public
107
+ git clone <this-repo> ~/projects/docks-kit
108
+ cd ~/projects/docks-kit
107
109
  ./docks-kit sync --dry-run # preview before applying
108
110
  ./docks-kit sync # deploy the omp SoT (additive)
109
111
  ./docks-kit toolchain check # verify installed tools against SoT/toolchain.json floors
package/README.md CHANGED
@@ -11,34 +11,44 @@ Supported harness: **Oh My Pi (`omp`)**.
11
11
  ## Quick start
12
12
 
13
13
  ```bash
14
- git clone https://github.com/DocksDocks/public.git ~/projects/public
15
- cd ~/projects/public
14
+ git clone https://github.com/DocksDocks/docks-kit.git ~/projects/docks-kit
15
+ cd ~/projects/docks-kit
16
16
  ./docks-kit sync # deploy the omp SoT
17
17
  ./docks-kit sync --dry-run # preview the sync without a write
18
18
  ./docks-kit toolchain # doctor view: verified-version floors for external tools
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.
34
+
35
+ ### Move a checkout of DocksDocks/public
36
+
37
+ The kit moved from DocksDocks/public to DocksDocks/docks-kit. To move a
38
+ checkout of DocksDocks/public, run these commands from the checkout's root:
39
+
40
+ ```
41
+ git remote set-url origin https://github.com/DocksDocks/docks-kit.git
42
+ ./docks-kit update # Linux and macOS
43
+ .\docks-kit.ps1 update # Windows
44
+ ./docks-kit sync # Linux and macOS
45
+ .\docks-kit.ps1 sync # Windows
46
+ ```
47
+
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.
42
52
 
43
53
  ## CLI
44
54
 
@@ -125,7 +135,7 @@ marketplace when no uninstall failed and it can read the marketplace registry.
125
135
  It only warns about a project-scope install, with the manual command. When a
126
136
  read fails, sync warns and skips that step, and a later sync tries again.
127
137
  Report a problem with a skill, an agent, or the kit in
128
- [DocksDocks/public](https://github.com/DocksDocks/public/issues).
138
+ [DocksDocks/docks-kit](https://github.com/DocksDocks/docks-kit/issues).
129
139
 
130
140
  ## Repository map
131
141
 
@@ -134,17 +144,17 @@ Report a problem with a skill, an agent, or the kit in
134
144
  | `SoT/.omp/` | omp SoT (AGENTS.md, config.yml, models.yml, mcp.json, intercom.json, and the `plugin/` source of `docks-kit-omp`) |
135
145
  | `SoT/toolchain.json` | Verified-version floors |
136
146
  | `cli/src/engine-native/` | EngineNative sync/toolchain implementation |
137
- | `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 |
138
148
  | `cli/` | docks-kit CLI (Effect 4 on Bun) + bundled docs topics |
139
- | `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) |
140
150
  | `install.sh` / `install.ps1` | POSIX and Windows global installers |
141
151
  | `docs/PLAN.md` | Plan pointer and project plan rules; plans are GitHub issues |
142
152
  | `AGENTS.md` | Agent-facing engineering rules |
143
153
 
144
154
  ## Platform support
145
155
 
146
- | Platform | Architecture | docks-kit binary | Sync engine |
147
- |----------|--------------|------------------|-------------|
156
+ | Platform | Architecture | docks-kit CLI | Sync engine |
157
+ |----------|--------------|---------------|-------------|
148
158
  | Linux | x64 | ✅ | ✅ native |
149
159
  | Linux | arm64 | ✅ | ✅ native |
150
160
  | macOS | arm64 | ✅ | ✅ native |
@@ -154,15 +164,15 @@ Details: `docks-kit docs platforms`.
154
164
 
155
165
  ## Releases
156
166
 
157
- Tagging `cli-v*` builds four standalone binaries: `docks-kit-linux-x64`,
158
- `docks-kit-linux-arm64`, `docks-kit-darwin-arm64`, and
159
- `docks-kit-windows-x64.exe`. The workflow attaches them plus `SHA256SUMS` to the GitHub
160
- release. npm publishes the exact package tarball through trusted publishing
161
- with OIDC provenance.
162
- Published binaries, checksums, and release notes are available on
163
- [GitHub Releases](https://github.com/DocksDocks/public/releases).
164
- Each `docks-kit` npm release bundles the CLI + generated payload, so releases
165
- are versioned config snapshots without shipping the authoring `SoT/` tree.
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
170
+ [GitHub Releases](https://github.com/DocksDocks/docks-kit/releases).
171
+ Each `docks-kit` npm release runs one minified JavaScript bundle of the CLI and
172
+ its generated payload (`cli/dist/docks-kit.js`), so releases are versioned config
173
+ snapshots without shipping the authoring `SoT/` tree. The package does not ship
174
+ the source map; the bundle's last line `//# debugId=<hex>` matches the map of
175
+ the same release.
166
176
 
167
177
  ## Deeper docs
168
178