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 +7 -5
- package/README.md +17 -27
- package/cli/dist/docks-kit.js +54 -41
- package/cli/docs/command-guards.md +7 -4
- package/cli/docs/install.md +18 -29
- package/cli/docs/overview.md +3 -3
- package/cli/docs/platforms.md +8 -8
- package/cli/src/commands/update.ts +4 -39
- 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 +3 -3
- package/cli/src/kitHome.ts +7 -10
- package/cli/src/main.ts +0 -1
- package/cli/src/plan/checkout.ts +69 -31
- package/docks-kit +9 -40
- package/docks-kit.ps1 +10 -61
- package/package.json +4 -5
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
|
|
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.
|
|
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:
|
|
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
|
|
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.
|
|
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
|
|
23
|
-
|
|
24
|
-
|
|
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
|
-
|
|
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
|
|
41
|
-
|
|
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
|
|
57
|
-
with their new report target
|
|
58
|
-
|
|
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
|
|
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 (
|
|
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
|
|
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*`
|
|
175
|
-
|
|
176
|
-
|
|
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
|