@cbartens/bkit 5.0.0 → 5.0.2
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/.bkit/README.md +12 -16
- package/.bkit/core/.agents/rules.md +57 -57
- package/.bkit/core/.bkit/README.md +11 -15
- package/.bkit/core/.bkit/cloud.md +22 -30
- package/.bkit/core/.bkit/comparison.md +36 -28
- package/.bkit/core/.bkit/install.md +55 -150
- package/.bkit/core/.bkit/jsonl.md +5 -5
- package/.bkit/core/.bkit/providers.md +6 -3
- package/.bkit/core/.bkit/templates.md +9 -7
- package/.bkit/core/.bkit/trackers.md +1 -1
- package/.bkit/core/.bkit/workflows.md +7 -3
- package/.bkit/core/engine/checks/after/auth.ts +16 -114
- package/.bkit/core/engine/checks/after/ci-yml.ts +36 -74
- package/.bkit/core/engine/checks/after/github.ts +1 -1
- package/.bkit/core/engine/checks/after/index.ts +158 -184
- package/.bkit/core/engine/checks/after/suppression.ts +53 -0
- package/.bkit/core/engine/checks/before/env.ts +5 -19
- package/.bkit/core/engine/checks/before/files.ts +2 -0
- package/.bkit/core/engine/cli.ts +4 -8
- package/.bkit/core/engine/commands/install/doctor.ts +9 -2
- package/.bkit/core/engine/commands/install/install.ts +24 -2
- package/.bkit/core/engine/commands/install/uninstall.ts +56 -1
- package/.bkit/core/engine/commands/install/upgrade.ts +14 -3
- package/.bkit/core/engine/commands/lib.ts +4 -3
- package/.bkit/core/engine/install/cloud-env.ts +4 -2
- package/.bkit/core/engine/install/modules/cloud.ts +3 -4
- package/.bkit/core/engine/install/modules/core.ts +33 -13
- package/.bkit/core/engine/install/modules/opencode.ts +34 -13
- package/.bkit/core/engine/install/payload-links.ts +150 -0
- package/.bkit/core/engine/install/template-copies.ts +1 -1
- package/.bkit/core/engine/shared/egress.ts +1 -1
- package/.bkit/core/workflows/bkit-debug.md +19 -12
- package/.bkit/shared/.bkit/.env.example +43 -36
- package/.bkit/shared/.claude/bkit-cloud.md +1 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
- package/.bkit/shared/.opencode/opencode.json +3 -1
- package/.bkit/shared/docs/deployments.md +7 -10
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/gitignore +5 -0
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +0 -5
- package/.bkit/templates/.cursor/Dockerfile +1 -1
- package/.bkit/templates/.cursor/environment.json +1 -1
- package/.bkit/templates/.github/renovate.json5 +0 -15
- package/.bkit/templates/.github/workflows/bkit-ci.yml +7 -24
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +0 -2
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +7 -10
- package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +125 -12
- package/CHANGELOG.md +37 -0
- package/README.md +96 -38
- package/dist/checks/after/auth.js +16 -108
- package/dist/checks/after/ci-yml.js +30 -67
- package/dist/checks/after/github.js +1 -1
- package/dist/checks/after/index.js +138 -154
- package/dist/checks/after/suppression.js +39 -0
- package/dist/checks/before/env.js +5 -15
- package/dist/checks/before/files.js +2 -0
- package/dist/cli.js +4 -8
- package/dist/commands/install/doctor.js +4 -2
- package/dist/commands/install/install.js +16 -2
- package/dist/commands/install/uninstall.js +45 -1
- package/dist/commands/install/upgrade.js +14 -3
- package/dist/commands/lib.js +4 -3
- package/dist/install/cloud-env.js +4 -2
- package/dist/install/modules/cloud.js +3 -4
- package/dist/install/modules/core.js +33 -13
- package/dist/install/modules/opencode.js +34 -14
- package/dist/install/payload-links.js +119 -0
- package/dist/install/template-copies.js +1 -1
- package/dist/shared/egress.js +1 -1
- package/package.json +25 -3
- package/.bkit/core/engine/checks/after/vercel.ts +0 -101
- package/dist/checks/after/vercel.js +0 -102
|
@@ -14,9 +14,9 @@
|
|
|
14
14
|
|
|
15
15
|
## What this is
|
|
16
16
|
|
|
17
|
-
bkit turns a single coding-agent request into gated, peer-reviewed engineering. Five commands — `/bkit-design` → `/bkit-plan` → `/bkit-build` → `/bkit-debug` → `/bkit-ship` — each fans out to specialised single-purpose subagents. Many run parallel under different _lenses_ (bug review vs security review) → independent review before human sees output.
|
|
17
|
+
bkit turns a single coding-agent request into gated, peer-reviewed engineering. Five commands — `/bkit-design` → `/bkit-plan` → `/bkit-build` → `/bkit-debug` → `/bkit-ship` — each fans out to specialised single-purpose subagents (48 in total, phases + audit + utilities). Many run parallel under different _lenses_ (bug review vs security review) → independent review before human sees output. Same pipeline on four hosts: Claude Code, Cursor, Codex, opencode.
|
|
18
18
|
|
|
19
|
-
Beside those commands,
|
|
19
|
+
Beside those commands, 35 read-only audit templates live at `docs/templates/bkit-audit-*.md`. `@bkit-audit-generate` runs one and writes `docs/audits/{YYYYMM}/{slug}.md`. `/bkit-plan` takes a design, one or more of those reports, or both.
|
|
20
20
|
|
|
21
21
|
Part 1: every phase subagent in execution order, then the main audit templates. Part 2: bkit vs Gulli agentic patterns. Full audit catalogue: `.bkit/prompts.md` § Audit (Ad-hoc).
|
|
22
22
|
|
|
@@ -33,7 +33,7 @@ Each phase lists subagents in execution order. "Parallel" = same-time run, merge
|
|
|
33
33
|
│ workflow_run on feat/** → ship (CI green) / debug (CI red) │
|
|
34
34
|
│ workflow_dispatch → any phase (ship|debug|design|plan|build) │
|
|
35
35
|
│ Dispatches the matching /bkit-* skill — runs unattended in cloud │
|
|
36
|
-
│ (Claude Code on the web / Cursor
|
|
36
|
+
│ (Claude Code on the web / Cursor cloud agents / opencode). │
|
|
37
37
|
│ Opt-in: `bkit install --auto=claude|cursor|opencode`. See `.bkit/cloud.md`. │
|
|
38
38
|
└────────────────────────────────────────────────────────────────────────┘
|
|
39
39
|
│
|
|
@@ -45,10 +45,12 @@ Each phase lists subagents in execution order. "Parallel" = same-time run, merge
|
|
|
45
45
|
• pragmatic • optimal-tradeoff • risk / pre-mortem
|
|
46
46
|
3. generate design (synthesise across lenses + related issues)
|
|
47
47
|
4. review × 2 (parallel, cross-tier models)
|
|
48
|
-
• feasibility (web) •
|
|
49
|
-
5.
|
|
50
|
-
|
|
51
|
-
|
|
48
|
+
• feasibility (web) • operability (failure modes, observability, on-call)
|
|
49
|
+
5. spike (only if review flags load-bearing unknowns:
|
|
50
|
+
throwaway probe code, confined to the run's log folder)
|
|
51
|
+
6. update design (fold reviews + spike back in)
|
|
52
|
+
7. organise (decompose into workstreams + DAG)
|
|
53
|
+
8. summary (tracker-facing)
|
|
52
54
|
|
|
53
55
|
/bkit-plan ───── output: detailed plan ───────────────────────────────────────
|
|
54
56
|
1. generate plan
|
|
@@ -66,21 +68,22 @@ Each phase lists subagents in execution order. "Parallel" = same-time run, merge
|
|
|
66
68
|
9. summary (tracker-facing)
|
|
67
69
|
|
|
68
70
|
/bkit-build ─── output: code, PR to dev, CI takes over ──────────────────────
|
|
69
|
-
1.
|
|
70
|
-
2.
|
|
71
|
-
3.
|
|
71
|
+
1. plan-current (plan still executable against code landed since it was written?)
|
|
72
|
+
2. install-skills
|
|
73
|
+
3. execute build (producer — implement tasks)
|
|
74
|
+
4. verify build (critic — verify each task; tick only on confirmed artifacts)
|
|
72
75
|
↶ producer-critic loop, capped 3 attempts
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
+
5. gaps-remediate (fix verifier gaps, re-verify)
|
|
77
|
+
6. verify build (holistic second pass across whole plan)
|
|
78
|
+
7. challenge × 2 (parallel, distinct lenses, no sibling reads)
|
|
76
79
|
• bug-hunting • security
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
80
|
+
8. challenge-reconcile (merge findings, severity + verdict max-wins)
|
|
81
|
+
9. challenge-remediate (classify-gate: architectural → FAIL; else fix + test)
|
|
82
|
+
10. challenge-tests (edge-case tests for changed files)
|
|
83
|
+
11. run tests (local tier: lint + typecheck + unit + slop:delta + bkit check;
|
|
81
84
|
no integration / e2e / @live — those run in CI)
|
|
82
85
|
↳ on test failure → /bkit-debug (debug-failure-diagnose + remediate)
|
|
83
|
-
|
|
86
|
+
12. summary (tracker-facing + PR link)
|
|
84
87
|
→ PR opened; CI runs the full multi-tier scaffold (see "CI test scaffold" below)
|
|
85
88
|
|
|
86
89
|
/bkit-debug ─── side-rail, invoked on test/CI failure ────────────────────────
|
|
@@ -148,8 +151,9 @@ Output: reviewed design (`docs/plans/{YYYYMM}/{FID}-design.md`). Hard stop for h
|
|
|
148
151
|
| `bkit-design-brainstorm-ideate-3` | Risk / pre-mortem | Same task, failure-mode lens. Opus, high effort. |
|
|
149
152
|
| `bkit-design-generate` | Synthesiser | Merges three brainstorms into one design. xhigh effort. Merges across lenses rather than collapsing to consensus. |
|
|
150
153
|
| `bkit-design-review-1` | Feasibility (web) | Adversarial review with live web search; checks ecosystem feasibility per capability. Opus, high. |
|
|
151
|
-
| `bkit-design-review-2` |
|
|
152
|
-
| `bkit-design-
|
|
154
|
+
| `bkit-design-review-2` | Operability (cross-tier) | Parallel review on a different model tier: failure modes, observability, on-call ergonomics. |
|
|
155
|
+
| `bkit-design-spike` | Probe unknowns | Only when a review flags load-bearing unknowns: settles them with throwaway probe code, confined to the run's log folder. |
|
|
156
|
+
| `bkit-design-update` | Apply review | Folds both reviews (and the spike, if run) back into the design. |
|
|
153
157
|
| `bkit-design-organise` | Structure | Cleans and organises the final design doc. High effort. |
|
|
154
158
|
| `bkit-design-summary` | Summarise | Writes the tracker-facing summary (capped, scannable). |
|
|
155
159
|
|
|
@@ -179,6 +183,7 @@ Output: PR to `dev`. Heaviest phase — most steps verify rather than produce. C
|
|
|
179
183
|
<!-- prettier-ignore -->
|
|
180
184
|
| Subagent | Lens / focus | What it does |
|
|
181
185
|
| --- | --- | --- |
|
|
186
|
+
| `bkit-build-plan-current` | Plan freshness | Judges whether changes landed since the plan was written leave it executable; findings feed execute. |
|
|
182
187
|
| `bkit-build-install-skills` | Setup | Installs the skills the plan needs for this build. |
|
|
183
188
|
| `bkit-build-plan-execute` | Producer | Implements the plan tasks. L-tier; iterates edit → lint/typecheck/test → edit. |
|
|
184
189
|
| `bkit-build-plan-verify` | Critic | Verifies each task against the plan; ticks boxes only on confirmed artifacts. Producer-critic loop, capped at 3 attempts. |
|
|
@@ -197,6 +202,8 @@ Output: PR to `dev`. Heaviest phase — most steps verify rather than produce. C
|
|
|
197
202
|
|
|
198
203
|
Output: remediated commit on feature branch. Two modes — normal (diagnose → remediate localisable failure) and soak (one accumulating-context instrument-or-fix loop for non-localisable / runtime-only failures). Normal escalates to soak when diagnose can't localise, or normal loop exhausts three strategies; observation logging (`[DEBUG-OBSERVE]`) inside soak, stripped before fix ships.
|
|
199
204
|
|
|
205
|
+
**Context fetch.** Per failed attempt, `/bkit-debug` runs each `context-fetch` bash block below `<!-- bkit:end -->` in `.agents/context.md` — failing CI logs, the diff since the last green run, end-to-end reports, runtime errors (Sentry, Vercel, Supabase, Stripe and more) and web search (Tavily) — writing one artifact per context and narrating `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` before fetching. Fail-soft and block-driven: bkit hardcodes no CI host, workflow filename or test framework, and a context with no block is never read as a clean result.
|
|
206
|
+
|
|
200
207
|
**Normal mode**
|
|
201
208
|
|
|
202
209
|
<!-- prettier-ignore -->
|
|
@@ -247,7 +254,7 @@ No command and no phase label. One subagent, one template per run.
|
|
|
247
254
|
|
|
248
255
|
`/bkit-plan` reads a design doc, one or more reports, or both. The invocation names which findings are in scope. The rest of each report stays context.
|
|
249
256
|
|
|
250
|
-
|
|
257
|
+
35 templates. Main ones:
|
|
251
258
|
|
|
252
259
|
<!-- prettier-ignore -->
|
|
253
260
|
| Template | Title | What it does |
|
|
@@ -271,7 +278,7 @@ Full catalogue: `.bkit/prompts.md` § Audit (Ad-hoc).
|
|
|
271
278
|
|
|
272
279
|
Benchmark: Antonio Gulli's _Agentic Design Patterns: A Hands-On Guide to Building Intelligent Systems_. Practitioner catalogue of agentic-AI patterns. Table maps all 21 named patterns + Context Engineering against bkit.
|
|
273
280
|
|
|
274
|
-
22 patterns assessed:
|
|
281
|
+
22 patterns assessed: 13 fully implemented, 7 partial (scoped to code-shipping), 2 intentionally N/A. No foundational patterns missing.
|
|
275
282
|
|
|
276
283
|
<!-- prettier-ignore -->
|
|
277
284
|
| Pattern (Gulli) | bkit status | Where / note |
|
|
@@ -282,18 +289,18 @@ Benchmark: Antonio Gulli's _Agentic Design Patterns: A Hands-On Guide to Buildin
|
|
|
282
289
|
| Reflection (producer-critic) | Already does | Build execute → verify → remediate loop; plan and design generate → review → update. |
|
|
283
290
|
| Tool Use | Already does | Per-role minimum-capability tool allowlists — stricter than the book's additive model. |
|
|
284
291
|
| Planning | Already does | `/bkit-plan` is a first-class artifact with a template and durable checkbox state. |
|
|
285
|
-
| Multi-Agent Collaboration | Already does |
|
|
292
|
+
| Multi-Agent Collaboration | Already does | 48 subagents, orchestrator-as-coordinator; subagents are leaves (no nested orchestration). |
|
|
286
293
|
| Model Context Protocol (MCP) | Already does | Tracker MCP held at the workflow layer only — cleaner separation than the book's examples. |
|
|
287
294
|
| Exception Handling & Recovery | Already does | Universal failure path, bounded retries (3), 3600s timeouts, runaway-turn caps, human handover. |
|
|
288
295
|
| Human-in-the-Loop | Already does | Mandatory hard stops after design / plan / ship; "recommend, do not decide." |
|
|
289
296
|
| Resource-Aware Optimization | Already does | Effort-to-model tiering with explicit per-agent pins. |
|
|
290
|
-
| Context Engineering | Already does | Phase doc-matrix, lazy-load, output caps, stubbed-output pattern. |
|
|
297
|
+
| Context Engineering | Already does | Phase doc-matrix, lazy-load, output caps, stubbed-output pattern; consumer `context-fetch` blocks add CI, diff, e2e, runtime and web signal in debug. |
|
|
291
298
|
| Memory Management | Partial | Filesystem and grep episodic memory (`status.jsonl`, knowledge / decisions). No vector retrieval, by scale choice. |
|
|
292
299
|
| Learning & Adaptation | Partial | `friction.jsonl` drives human-reviewed prompt edits; entries carry confidence, scope, and last-confirmed fields. No auto prompt-tuning — deliberate, to keep humans in the loop. |
|
|
293
|
-
| Goal Setting & Monitoring |
|
|
300
|
+
| Goal Setting & Monitoring | Already does | Issue = goal, phase labels = state, verdicts = criteria. Per-task `Done when:` in the plan template; verifier ticks only on confirmed artifacts; deferred-sweep FAILs merge on any unplanned gap; `stats.jsonl` tracks every run. |
|
|
294
301
|
| Knowledge Retrieval (RAG) | Partial | Deterministic doc-matrix retrieval plus web search in design review. No embedding RAG (Grep wins at repo scale). |
|
|
295
302
|
| Reasoning Techniques | Partial | Extended thinking (CoT) plus parallel-pair-reconcile (a form of self-consistency). No formal ToT or ReAct trace. |
|
|
296
|
-
| Guardrails / Safety | Partial | Tool sandbox, destructive-git bans, locks, verdict checks, and an advisory edit-investigation plus gate-config hook (GateGuard). No output validators
|
|
303
|
+
| Guardrails / Safety | Partial | Tool sandbox, destructive-git bans, locks, verdict checks, and an advisory edit-investigation plus gate-config hook (GateGuard). `bkit steps finish` validates each step's verdict and artifacts structurally. No content-level output validators (e.g. safety classifiers). |
|
|
297
304
|
| Evaluation & Monitoring | Partial | `friction` / `knowledge` logs, CI gates, and a catalog-parity drift check. No automated regression-fixture eval harness yet. |
|
|
298
305
|
| Exploration & Discovery | Partial | Divergent brainstorm triplet plus feasibility search. No temperature-spread or vote-of-K. |
|
|
299
306
|
| Inter-Agent Communication (A2A) | N/A by design | Agents communicate only via filesystem artifacts — deliberate, to preserve leaf-only and resume guarantees. |
|
|
@@ -305,13 +312,14 @@ Benchmark: Antonio Gulli's _Agentic Design Patterns: A Hands-On Guide to Buildin
|
|
|
305
312
|
- **Cross-model diversity where breadth beats depth.** Design brainstorm, design review, plan scope-check groups pair Opus + Sonnet (Grok + Composer on Cursor) → two reasoners review same work. Depth-sensitive lenses (plan review, build challenge) stay on top tier.
|
|
306
313
|
- **Resume-from-state as single source of truth.** `status.jsonl` makes every run inspectable and restartable; book treats this only obliquely under memory.
|
|
307
314
|
- **Human-in-the-loop as non-negotiable.** Hard stops after design / plan / ship; book treats HITL as one option.
|
|
315
|
+
- **Fail-soft external context in debug.** Provider-agnostic `context-fetch` blocks (CI logs, diff, e2e, runtime, web) feed `/bkit-debug`; each self-skips to a narrated `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` state, so a context with no block is never read as a clean result.
|
|
308
316
|
- **Explicit per-agent model pins.** Immune to session-default drift.
|
|
309
|
-
- **Provider- and host-portable execution.** Per-agent pins → `bkit install --opencode=<provider>`
|
|
317
|
+
- **Provider- and host-portable execution.** Per-agent pins → `bkit install --codex` / `--opencode=<provider>` add Codex and opencode hosts alongside Claude/Cursor — harness unchanged; inference backend moves. Same five-phase gated parallel pipeline on four providers (OpenRouter, Ollama, opencode Zen + Go gateways). Curated per-agent pins; models mirror Claude tier by default, CoT reasoners swapped for convergent-reasoning agents (debug/risk). See `.bkit/providers.md` § Hosts + Providers.
|
|
310
318
|
- **Cross-host/provider continuity.** State in `status.jsonl`, plan/design docs under `docs/plans/`, tracker issue — not vendor session. Every host renders from same `.bkit/` source → phase or resumed run moves across IDE/provider mid-feature with identical gates, hooks, per-agent pins: exhaust Claude weekly limit or free-tier quota → continue on another host, no re-setup. Single-vendor frameworks tie run to starting session.
|
|
311
319
|
|
|
312
320
|
### Known gaps, scoped as opportunities
|
|
313
321
|
|
|
314
|
-
Most partials = deliberate scope.
|
|
322
|
+
Most partials = deliberate scope. Two remain: automated eval harness with regression fixtures for closed friction items; optional self-consistency vote (quorum-of-N) for high-stakes reviews. Neither requires leaf-agent architecture change.
|
|
315
323
|
|
|
316
324
|
---
|
|
317
325
|
|
|
@@ -2,19 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
{{BKIT_MANAGED_MARKER}}
|
|
4
4
|
|
|
5
|
-
First-time install and
|
|
5
|
+
First-time install and upgrade, install lifecycle, uninstall and recovery. Ships in the package at `node_modules/@cbartens/bkit/.bkit/core/.bkit/install.md` and is mirrored into the consumer repo at `.bkit/install.md`. Ongoing ops and triggering workflows: `.bkit/README.md`.
|
|
6
6
|
|
|
7
7
|
> [!IMPORTANT]
|
|
8
|
-
>
|
|
9
|
-
>
|
|
10
|
-
> 1. **Local shell** — pick one of two flows (see § Local env setup for details):
|
|
11
|
-
> - **(A) Quick:** `export BKIT_GH_TOKEN_INSTALL=<classic PAT>` in `~/.zshrc` or `~/.bashrc`. Works immediately, single-step. Same token leaks into every shell.
|
|
12
|
-
> - **(B) direnv + `.bkit/.env` (recommended for daily use):** `brew install direnv` once per machine, then `.bkit/.env` (gitignored, scaffolded by `bkit install`) auto-loads on `cd`. Tokens scoped to the repo, not your whole shell. Note: `.bkit/.env` only exists _after_ `bkit install` runs, so for the first install you need either (A) or a one-off `export` in the current shell.
|
|
13
|
-
> 2. **`.npmrc` at repo root** — registry mapping only; token goes in pnpm user-level config via `pnpm config set` — see § Consumer CI auth below
|
|
14
|
-
> 3. **GitHub Actions repo secret** — `gh secret set BKIT_GH_TOKEN_INSTALL --body=<token>` per consumer repo
|
|
15
|
-
> 4. **Vercel env vars** (if applicable) — `vercel env add BKIT_GH_TOKEN_INSTALL preview/production`
|
|
16
|
-
>
|
|
17
|
-
> **Use a classic PAT, not fine-grained.** GitHub Packages npm registry currently rejects fine-grained PATs with HTTP 403 even when `Packages: read` is granted (verified 2026-05). Until GitHub fixes this, classic with `read:packages` scope is the only working option.
|
|
8
|
+
> **bkit installs from npmjs.** `@cbartens/bkit` is public on `https://registry.npmjs.org`; `pnpm add -D @cbartens/bkit` resolves with no registry mapping, PAT, or CI/Vercel env.
|
|
18
9
|
|
|
19
10
|
## Quick install / upgrade — paste into your AI
|
|
20
11
|
|
|
@@ -22,50 +13,33 @@ Two paste blocks below — **install** (first time) and **upgrade** (already on
|
|
|
22
13
|
|
|
23
14
|
### Install — first time
|
|
24
15
|
|
|
25
|
-
|
|
16
|
+
No token or registry setup is needed — `@cbartens/bkit` is public on npmjs. Copy the block below into Claude Code / Cursor / Codex / opencode.
|
|
26
17
|
|
|
27
18
|
````text
|
|
28
19
|
Install the latest `@cbartens/bkit` in this repo and finish setup.
|
|
29
|
-
1.
|
|
30
|
-
2.
|
|
20
|
+
1. `@cbartens/bkit` is public on npmjs — no registry mapping, no PAT, no env. Confirmed.
|
|
21
|
+
2. Install and seed hosts in one Bash call (`bkit install` requires named modules — core implicit; pick the hosts this repo uses from `--claude --cursor --codex --opencode=<provider>`; if `bkit` not on PATH use `pnpm bkit`):
|
|
31
22
|
```bash
|
|
32
|
-
|
|
33
|
-
```
|
|
34
|
-
Verify without leaking: `echo "len=${#BKIT_GH_TOKEN_INSTALL}"`.
|
|
35
|
-
3. Ensure root `.npmrc` has registry mapping only (token NOT stored here — pnpm >=10.34.3 401s on project-`.npmrc` `${BKIT_GH_TOKEN_INSTALL}` substitution):
|
|
36
|
-
```
|
|
37
|
-
@cbartens:registry=https://npm.pkg.github.com
|
|
38
|
-
```
|
|
39
|
-
Then auth + install + seed hosts in one Bash call (`bkit install` requires named modules — core implicit; if `bkit` not on PATH use `pnpm bkit`):
|
|
40
|
-
```bash
|
|
41
|
-
set -a; source <ENV-FILE-PATH>; set +a; \
|
|
42
|
-
pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL" && \
|
|
43
|
-
pnpm add -D @cbartens/bkit@latest && \
|
|
23
|
+
pnpm add -D @cbartens/bkit@latest && \
|
|
44
24
|
bkit install --claude --cursor
|
|
45
25
|
```
|
|
46
26
|
Writes `.agents/`, `.claude/`, `.cursor/` and the `bkit:gate:*` `package.json` scripts, and copies the templates (CI workflow, hooks, tool configs) into `.bkit/templates/` without applying them. `.bkit/templates.md` lists each template plus the tool scripts and devDeps the gates chain.
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
27
|
+
3. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why.
|
|
28
|
+
4. Read `.bkit/templates.md`, then compare each template in `.bkit/templates/` (CI workflows, git hooks, lint and Vale configs, Cursor config, dependency updaters, etc.) with this repo. bkit never applies templates, so adoption is your job: adopt unless adoption would break existing functionality. For any template not adopted, state which and why.
|
|
29
|
+
5. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons).
|
|
50
30
|
````
|
|
51
31
|
|
|
52
32
|
### Upgrade — already installed
|
|
53
33
|
|
|
54
|
-
Same paste block ships in `.bkit/README.md` (mirrored into consumer repos on install — keep both in sync when editing). Copy when the repo already has `@cbartens/bkit`. Prefer `bkit upgrade --latest` (bumps the package **and** resyncs managed files) — do **not** only `pnpm add`.
|
|
34
|
+
Same paste block ships in `.bkit/README.md` (mirrored into consumer repos on install — keep both in sync when editing). Copy when the repo already has `@cbartens/bkit`. Prefer `bkit upgrade --latest` (bumps the package **and** resyncs managed files) — do **not** only `pnpm add`.
|
|
55
35
|
|
|
56
36
|
````text
|
|
57
37
|
Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resync.
|
|
58
|
-
1.
|
|
59
|
-
```bash
|
|
60
|
-
set -a; source <ENV-FILE-PATH> 2>/dev/null; set +a; \
|
|
61
|
-
pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL" && \
|
|
62
|
-
bkit upgrade --latest
|
|
63
|
-
```
|
|
64
|
-
If token already exported (direnv / shell profile), skip `source`:
|
|
38
|
+
1. Bump and resync in one step (no token — npmjs is public). If `bkit` is not on PATH, use `pnpm bkit`:
|
|
65
39
|
```bash
|
|
66
40
|
bkit upgrade --latest
|
|
67
41
|
```
|
|
68
|
-
|
|
42
|
+
Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
|
|
69
43
|
2. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why.
|
|
70
44
|
3. Read the template changes `bkit upgrade` printed (or `git diff .bkit/templates`), then `.bkit/templates.md`. bkit never applies templates, so adoption is your job: adopt each change unless it would break existing functionality. For any change not adopted, state which and why.
|
|
71
45
|
4. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons).
|
|
@@ -73,29 +47,25 @@ Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resyn
|
|
|
73
47
|
|
|
74
48
|
## Install
|
|
75
49
|
|
|
76
|
-
bkit is
|
|
50
|
+
bkit is published publicly on **npmjs** (`https://registry.npmjs.org`). Add to a consumer repo:
|
|
77
51
|
|
|
78
52
|
```bash
|
|
79
|
-
pnpm add -D @cbartens/bkit
|
|
53
|
+
pnpm add -D @cbartens/bkit
|
|
80
54
|
```
|
|
81
55
|
|
|
82
56
|
### Adding a new consumer — checklist
|
|
83
57
|
|
|
84
|
-
Run these in order on a brand-new consumer repo.
|
|
58
|
+
Run these in order on a brand-new consumer repo.
|
|
85
59
|
|
|
86
60
|
<!-- prettier-ignore -->
|
|
87
61
|
| # | Step | Detail |
|
|
88
62
|
| --- | --- | --- |
|
|
89
|
-
| 1 |
|
|
90
|
-
| 2 |
|
|
91
|
-
| 3 |
|
|
92
|
-
| 4 |
|
|
93
|
-
| 5 | Run `bkit install --claude --cursor` to seed both hosts (writes `.bkit/.env.example`; `.envrc` is a template in `.bkit/templates/`) | [§ Install](#install) (this section) |
|
|
94
|
-
| 5a | Set up direnv + `.bkit/.env` so every subsequent shell auto-loads `BKIT_GH_TOKEN_INSTALL`, `BKIT_GH_TOKEN`, `BKIT_LINEAR_API_KEY` | [§ Local env setup](#local-env-setup) |
|
|
95
|
-
| 6 | If deploying to Vercel: add `BKIT_GH_TOKEN_INSTALL` to Vercel env vars | [§ Consumer Vercel auth](#consumer-vercel-auth) |
|
|
96
|
-
| 7 | Push to a feature branch and verify CI runs green | — |
|
|
63
|
+
| 1 | `pnpm add -D @cbartens/bkit` — no token, no registry mapping | this section |
|
|
64
|
+
| 2 | Run `bkit install --claude --cursor` to seed both hosts (writes `.bkit/.env.example`; `.envrc` is a template in `.bkit/templates/`) | this section |
|
|
65
|
+
| 3 | Set up direnv + `.bkit/.env` for `BKIT_GH_TOKEN` (GitHub MCP) and `BKIT_LINEAR_API_KEY` — no registry token | [§ Local env setup](#local-env-setup) |
|
|
66
|
+
| 4 | Push to a feature branch and verify CI runs green | — |
|
|
97
67
|
|
|
98
|
-
|
|
68
|
+
No CI step, secret, `.npmrc` mapping or Vercel env is needed — CI reaches npmjs anonymously.
|
|
99
69
|
|
|
100
70
|
### Then in the consumer repo
|
|
101
71
|
|
|
@@ -133,18 +103,26 @@ bkit check
|
|
|
133
103
|
|
|
134
104
|
**Opt-in flags:** `--tracker=github|linear`, `--auto=claude|cursor` (cloud agents), `--opencode=<provider>` (additive opencode execution host — `openrouter`, `ollama`, `opencode-zen`, `opencode-go`). Dependency updaters: copy an example and own it. See [§ Optional post-install decisions](#optional-post-install-decisions).
|
|
135
105
|
|
|
106
|
+
### Payload view links — `.bkit/core` + `.bkit/shared`
|
|
107
|
+
|
|
108
|
+
Install and upgrade create two **relative symlinks** into the installed package, so the payload sources (workflows, prompts, hooks) are browsable in-repo: `.bkit/core` → `../node_modules/@cbartens/bkit/.bkit/core`, same shape for `shared`. Views, not copies — always the installed version, zero drift. Rules:
|
|
109
|
+
|
|
110
|
+
- Both paths sit in the `.gitignore` managed block — they dangle on a fresh clone or in CI (no `node_modules`); `bkit install` / `upgrade` recreates them.
|
|
111
|
+
- The `bkit` binary reads its payload from the package regardless; the links are browse-only. Editors resolve them to the `node_modules/…` paths.
|
|
112
|
+
- A real directory at either path is never clobbered (advisory `payload-link-real-dir`) — remove it yourself and re-run install to get the link. A platform that refuses symlinks (Windows without Developer Mode) falls back to a junction, then to advisory `payload-link-failed` — never a failure.
|
|
113
|
+
- `bkit uninstall` removes the links (symlinks only — consumer content stays).
|
|
114
|
+
|
|
136
115
|
> **⚠️ Moving bkit versions: use `bkit upgrade --latest` (or `--to=<version>`).** Bumps `@cbartens/bkit` **and** resyncs `.agents/` payload + `.bkit/version` pin in one atomic step — two can never drift apart. Bare `pnpm add @cbartens/bkit` (or Renovate/Dependabot bump) only refreshes `package.json` + lockfile — does **not** resync; skipping resync reds CI on `bkit check` drift gate. If you bump package separately, run `bkit upgrade` afterward and commit resync alongside version bump in same PR.
|
|
137
116
|
|
|
138
117
|
### Local env setup
|
|
139
118
|
|
|
140
|
-
Two flows — pick one. Both
|
|
119
|
+
Two flows — pick one. Both put `BKIT_GH_TOKEN` in shell for the GitHub MCP server; Linear repos also need `BKIT_LINEAR_API_KEY`. Use `gh auth login` for CLI.
|
|
141
120
|
|
|
142
121
|
#### Flow A — Shell export (quickest, no extra deps)
|
|
143
122
|
|
|
144
123
|
```bash
|
|
145
124
|
# Add to ~/.zshrc (or ~/.bashrc)
|
|
146
|
-
export
|
|
147
|
-
export BKIT_GH_TOKEN=<fine-grained PAT> # GitHub MCP
|
|
125
|
+
export BKIT_GH_TOKEN=<PAT — fine-grained (one owner) or classic (multiple owners)> # GitHub MCP
|
|
148
126
|
export BKIT_LINEAR_API_KEY=<Linear personal API key> # Linear MCP + preflight
|
|
149
127
|
|
|
150
128
|
# Reload
|
|
@@ -169,7 +147,7 @@ echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && source ~/.zshrc
|
|
|
169
147
|
# 3. One-time per consumer repo (after `bkit install`)
|
|
170
148
|
cp .bkit/templates/.envrc .envrc # unless you already have one
|
|
171
149
|
cp .bkit/.env.example .bkit/.env
|
|
172
|
-
# Edit .bkit/.env: set
|
|
150
|
+
# Edit .bkit/.env: set BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY
|
|
173
151
|
direnv allow # trust the .envrc
|
|
174
152
|
|
|
175
153
|
# 4. Verify
|
|
@@ -181,16 +159,6 @@ After step 4, restart open Claude Code / Cursor sessions in this repo so new env
|
|
|
181
159
|
|
|
182
160
|
`.bkit/.env` gitignored — never commit. Cloud sessions (Claude Code on the web, Cursor Background Agents): set same names in respective online dashboards; see `.bkit/cloud.md` § Environment variables. `bkit install` / `bkit check` advisories detect missing direnv, blank required keys, un-allowed `.envrc` — follow whichever fires.
|
|
183
161
|
|
|
184
|
-
#### One-time per machine — register the GH Packages token with pnpm
|
|
185
|
-
|
|
186
|
-
After either flow makes `BKIT_GH_TOKEN_INSTALL` available in shell, write into pnpm user-level auth config so local `pnpm install` resolves `@cbartens/bkit`:
|
|
187
|
-
|
|
188
|
-
```bash
|
|
189
|
-
pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
pnpm >=10.34.3 does not authenticate project-`.npmrc` `${BKIT_GH_TOKEN_INSTALL}` env-substitution (401s on download) — user-level step required; committed `.npmrc` carries only registry mapping. `pnpm config set` writes `~/.npmrc` on pnpm 10.x and `~/.config/pnpm/auth.ini` on pnpm 11.x (whichever pnpm reads) — same command across pnpm versions.
|
|
193
|
-
|
|
194
162
|
## Cloud agent environments (Claude Code on the web + Cursor Background Agents)
|
|
195
163
|
|
|
196
164
|
bkit ships repo-side scaffolding for both cloud agents. Opt-in `bkit install --auto=claude` writes no file; the per-session install hook (`.claude/hooks/bkit-cloud-bootstrap.sh`), the phase-routed `.github/workflows/bkit-cloud.yml` and the Cursor cloud image files (`.cursor/Dockerfile`, `.cursor/environment.json`) are templates in `.bkit/templates/` that you copy and own. (`.cursor/hooks.json` — Linear preflight wiring — ships with `--cursor`, not `--auto`.) Install without `--auto` ships zero cloud footprint. **Online-dashboard** half (Claude env in `claude.ai/code`, Cursor env vars in `Cursor → Settings → Background Agents`) configured once per machine / account.
|
|
@@ -225,77 +193,6 @@ In this example, `hooks.SessionStart` is bkit-declared scope (from template). `h
|
|
|
225
193
|
- `bkit check` surfaces `tier2-json-drift` advisory when `deepContains` fails and **exits 1** (CI drift gate); writes nothing — consumer reviews and re-runs `bkit install` to reconverge.
|
|
226
194
|
- `.cursor/hooks.json` uses Cursor v1 keyed-object schema: `{"version": 1, "hooks": {"sessionStart": [...], "sessionStop": [...]}}`.
|
|
227
195
|
|
|
228
|
-
## Consumer CI auth
|
|
229
|
-
|
|
230
|
-
bkit resolves from **GitHub Packages npm registry**. Authentication requires:
|
|
231
|
-
|
|
232
|
-
1. **Create a classic PAT** on GitHub with `read:packages` scope:
|
|
233
|
-
- GitHub Settings → Developer settings → Personal access tokens → **Tokens (classic)** → Scope: `read:packages`
|
|
234
|
-
- Copy the generated token
|
|
235
|
-
|
|
236
|
-
> **⚠️ Use a classic PAT, not fine-grained.** GitHub Packages npm registry currently rejects fine-grained PATs with HTTP 403, even when `Packages: read` is granted. Confirmed against `npm.pkg.github.com` 2026-05-06. If/when GitHub fixes this, fine-grained PATs will become preferred (narrower scope); for now classic is the only working option.
|
|
237
|
-
|
|
238
|
-
2. **Add the secret** to your consumer repo:
|
|
239
|
-
- GitHub repo → Settings → Secrets and variables → Actions → New repository secret
|
|
240
|
-
- Name: `BKIT_GH_TOKEN_INSTALL`
|
|
241
|
-
- Value: paste the PAT
|
|
242
|
-
|
|
243
|
-
3. **Add `.npmrc`** at your repo root (committed, no secrets) — registry mapping ONLY. Auth token **not** stored here:
|
|
244
|
-
|
|
245
|
-
```
|
|
246
|
-
@cbartens:registry=https://npm.pkg.github.com
|
|
247
|
-
```
|
|
248
|
-
|
|
249
|
-
4. The `bkit-ci.yml` template's install step writes token into pnpm user-level config before install (copy it from `.bkit/templates/.github/workflows/bkit-ci.yml`, or add the step to your own workflow):
|
|
250
|
-
|
|
251
|
-
```yaml
|
|
252
|
-
- name: Install Dependencies
|
|
253
|
-
run: |
|
|
254
|
-
pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"
|
|
255
|
-
pnpm install --frozen-lockfile
|
|
256
|
-
env:
|
|
257
|
-
BKIT_GH_TOKEN_INSTALL: ${{ secrets.BKIT_GH_TOKEN_INSTALL }}
|
|
258
|
-
```
|
|
259
|
-
|
|
260
|
-
> **⚠️ Why `pnpm config set`, not `.npmrc`:** pnpm >=10.34.3 does not authenticate project-`.npmrc` `${BKIT_GH_TOKEN_INSTALL}` env-substitution — `pnpm install` 401s on `@cbartens/bkit` download (`ERR_PNPM_FETCH_401`) even when token set. `pnpm config set` writes token to pnpm user-level config (`~/.npmrc` on pnpm 10.x, `~/.config/pnpm/auth.ini` on pnpm 11.x). Leftover `_authToken` line in project `.npmrc` must be **removed** — 401s and, by config precedence (project > user), shadows user-level token. Note: `pnpm view @cbartens/bkit` (metadata) may still resolve with broken setup — verify with real `pnpm install`, not `view`.
|
|
261
|
-
|
|
262
|
-
### Agent access to `BKIT_GH_TOKEN_INSTALL`
|
|
263
|
-
|
|
264
|
-
If permission rules block direct reads of `.env*` files (e.g. `Read(./.env*)`, `Bash(grep ... .env*)` denied), token still cannot be read — but **can** be exported into child process for duration of single command. Use in single Bash tool call:
|
|
265
|
-
|
|
266
|
-
```bash
|
|
267
|
-
set -a; source apps/web/.env.preview 2>/dev/null; set +a; <command that needs the token>
|
|
268
|
-
```
|
|
269
|
-
|
|
270
|
-
- `source` is shell builtin, not file I/O — agent permission layer (gates `Read` / `grep` / `cat`) does not see it. Token text never enters agent context.
|
|
271
|
-
- `<command>` (e.g. `pnpm view @cbartens/bkit`, `bkit check`) inherits `BKIT_GH_TOKEN_INSTALL` via environment.
|
|
272
|
-
- Verify token loaded **without leaking value**: `echo "len=${#BKIT_GH_TOKEN_INSTALL}"`.
|
|
273
|
-
|
|
274
|
-
**Caveat:** shell state does not persist between separate Bash tool calls. `source` and consuming command must run in **same** invocation — chain with `;` or `&&`. When directing another agent, name file path explicitly (e.g. _"source `apps/web/.env.preview` in-line; registry needs `BKIT_GH_TOKEN_INSTALL`"_).
|
|
275
|
-
|
|
276
|
-
## Consumer Vercel auth
|
|
277
|
-
|
|
278
|
-
Vercel runs own `pnpm install` in fresh build container — cannot run pre-install shell step. pnpm >=10.34.3 does not authenticate project-`.npmrc` `${BKIT_GH_TOKEN_INSTALL}` env-substitution, so set token via one-line `installCommand` writing pnpm user-level config before install.
|
|
279
|
-
|
|
280
|
-
1. **Add `BKIT_GH_TOKEN_INSTALL` to Vercel env vars** for each environment that builds (preview + production at minimum):
|
|
281
|
-
|
|
282
|
-
```bash
|
|
283
|
-
vercel env add BKIT_GH_TOKEN_INSTALL preview
|
|
284
|
-
vercel env add BKIT_GH_TOKEN_INSTALL production
|
|
285
|
-
```
|
|
286
|
-
|
|
287
|
-
Or via web: Vercel project → Settings → Environment Variables. Token value = same PAT as GitHub Actions secret (scope: `read:packages`).
|
|
288
|
-
|
|
289
|
-
2. **Set `installCommand` in `vercel.json`** so token reaches pnpm user-level auth config before install (remove any pre-existing git-shim `installCommand`):
|
|
290
|
-
|
|
291
|
-
```json
|
|
292
|
-
{
|
|
293
|
-
"installCommand": "pnpm config set //npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL && pnpm install"
|
|
294
|
-
}
|
|
295
|
-
```
|
|
296
|
-
|
|
297
|
-
3. **Trigger redeploy** (push commit) and watch Vercel build log for `pnpm install` resolving `@cbartens/bkit` from `npm.pkg.github.com`.
|
|
298
|
-
|
|
299
196
|
## Install lifecycle
|
|
300
197
|
|
|
301
198
|
`bkit install` runs three phases in sequence:
|
|
@@ -318,20 +215,12 @@ Module dispatch writes managed files.
|
|
|
318
215
|
|
|
319
216
|
**Phase 3 — Post-install (re-detect + unified output)**
|
|
320
217
|
|
|
321
|
-
After writes, bkit re-runs
|
|
218
|
+
After writes, bkit re-runs credential and environment checks — some only accurate post-install (e.g. the `bkit:gate:*` scripts core just seeded into `package.json`). The table also lists the module advisories that render in the same checklist.
|
|
322
219
|
|
|
323
220
|
<!-- prettier-ignore -->
|
|
324
221
|
| `id` | When |
|
|
325
222
|
| --- | --- |
|
|
326
|
-
| `gh-bkit-token-unset-shell` / `gh-bkit-token-empty-shell` | `BKIT_GH_TOKEN_INSTALL` unset (or set but empty) in shell |
|
|
327
|
-
| `npmrc-missing-gh-packages` | `.npmrc` exists but lacks the `@cbartens` registry mapping |
|
|
328
|
-
| `npmrc-authtoken-line` | `.npmrc` carries a `//npm.pkg.github.com/:_authToken=…` line (401s on pnpm >=10.34.3; move it to pnpm user-level config) |
|
|
329
|
-
| `gh-bkit-token-secret-missing` | `gh secret list` confirms secret absent |
|
|
330
|
-
| `gh-bkit-token-secret-unknown` | `gh` CLI unavailable/unauthenticated |
|
|
331
223
|
| `gh-mcp-token-unset-shell` / `gh-mcp-token-empty-shell` | `BKIT_GH_TOKEN` (GitHub MCP auth) unset/empty in shell while a `github` MCP server is configured — the whole tracker/PR/board MCP surface fails to connect. Suppressed in CI. |
|
|
332
|
-
| `vercel-env-missing-preview` | `vercel.json` detected; token absent in preview |
|
|
333
|
-
| `vercel-env-missing-production` | `vercel.json` detected; token absent in production |
|
|
334
|
-
| `ci-yml-missing-token-env` | bkit-ci.yml install step lacks the `pnpm config set` auth step and/or the `BKIT_GH_TOKEN_INSTALL` env mapping |
|
|
335
224
|
| `tracker-setup-none` / `-github` / `-linear` | Optional post-install decision — which issue tracker is wired (`bkit.issueTracker`). `none` nudges `bkit install --tracker=…`. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
336
225
|
| `github-project-board-sync-unconfigured` | GitHub tracker active but Projects v2 board sync is half-configured (`bkit.githubProject` absent and/or `.mcp.json` lacks the `projects` toolset) — sync silently no-ops. Silence with `bkit.githubProject: false`. |
|
|
337
226
|
| `github-project-status-field-id-format` | `bkit.githubProject` is configured but `statusFieldId` holds a GraphQL node id (`PVTSSF_…`) or non-number — `projects_write` needs the numeric field id, so board sync silently no-ops. Re-derive via `gh api /orgs/<org>/projectsV2/<number>/fields`. |
|
|
@@ -360,9 +249,25 @@ interface PreflightFinding {
|
|
|
360
249
|
}
|
|
361
250
|
```
|
|
362
251
|
|
|
363
|
-
Findings
|
|
252
|
+
Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` lines. The console banner and the `.bkit/advisories.md` artifact render the same text — copy either into a coding assistant to apply fixes in sequence.
|
|
253
|
+
|
|
254
|
+
**Dismissing an advisory (per package).** A detector can be right in general and still fire where the condition is deliberately not applicable — a rule-linter whose test titles mention `@live`, an integration lane mocked by design. Opt the owning package out in its `package.json`:
|
|
364
255
|
|
|
365
|
-
|
|
256
|
+
```json
|
|
257
|
+
{
|
|
258
|
+
"bkit": {
|
|
259
|
+
"ignoreAdvisories": ["tagged-tests-no-ci-home"]
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
<!-- prettier-ignore -->
|
|
265
|
+
| Rule | Behaviour |
|
|
266
|
+
| --- | --- |
|
|
267
|
+
| Scope | Per package, read from the **owning** package's `package.json` — the package holding the test file for `tagged-tests-no-ci-home`, the repo root for `test-integration-env-not-asserted` (the only manifest it reads). A sibling package with a real finding stays flagged. |
|
|
268
|
+
| Severity | Advisory only. A `blocker` is never suppressible, whatever the manifest says. |
|
|
269
|
+
| Visibility | The console banner and `.bkit/advisories.md` carry one suppressed-advisory line per dismissal (`N advisory` / `N advisories`), so a stale opt-out cannot hide a finding silently. |
|
|
270
|
+
| Coverage | Wired for `tagged-tests-no-ci-home` and `test-integration-env-not-asserted`. No other advisory is suppressible; an id matching no advisory is ignored. |
|
|
366
271
|
|
|
367
272
|
## Optional post-install decisions
|
|
368
273
|
|
|
@@ -404,7 +309,7 @@ Tracker and cloud agents reverse by re-running install with the other flag. Upda
|
|
|
404
309
|
|
|
405
310
|
## Doctor
|
|
406
311
|
|
|
407
|
-
`bkit doctor` is **diagnostic verb** — runs Phase 1 preflight + Phase 3
|
|
312
|
+
`bkit doctor` is **diagnostic verb** — runs Phase 1 preflight + Phase 3 credential detectors, exits 0. Changes no managed file; like `bkit check` regenerates `.bkit/advisories.md` artifact (creates `.bkit/` if absent — repo that never installed bkit gains that one file).
|
|
408
313
|
|
|
409
314
|
```bash
|
|
410
315
|
# Diagnose drift without running install
|
|
@@ -413,7 +318,7 @@ bkit doctor
|
|
|
413
318
|
|
|
414
319
|
Use `bkit doctor` to:
|
|
415
320
|
|
|
416
|
-
- Check
|
|
321
|
+
- Check `BKIT_GH_TOKEN` presence in shell (GitHub MCP auth) and the cloud-router (`ANTHROPIC_API_KEY`) repo secret.
|
|
417
322
|
- Surface `bkit-version-pin-stale` advisory (installed version ahead of `.bkit/version`).
|
|
418
323
|
- Preview all advisories `bkit install` would show post-install, without triggering writes.
|
|
419
324
|
- Verify environment ready before `bkit install` on new machine.
|
|
@@ -422,7 +327,7 @@ Use `bkit doctor` to:
|
|
|
422
327
|
|
|
423
328
|
## Uninstall
|
|
424
329
|
|
|
425
|
-
`bkit uninstall` surgically removes bkit-managed content while preserving consumer customisations.
|
|
330
|
+
`bkit uninstall` surgically removes bkit-managed content while preserving consumer customisations. The `.bkit/core` / `.bkit/shared` payload view links go with a full/core uninstall (symlinks only — a real directory at either path is consumer content and stays).
|
|
426
331
|
|
|
427
332
|
```bash
|
|
428
333
|
# Uninstall EVERYTHING — all modules, including the cloud add-on if present.
|
|
@@ -468,7 +373,7 @@ Bare uninstall removes bkit-managed files and strips bkit-managed blocks, but **
|
|
|
468
373
|
|
|
469
374
|
## Phase 3 exit-1 and recovery
|
|
470
375
|
|
|
471
|
-
When `bkit install` detects **blocker-severity** finding in Phase 3 (e.g. `
|
|
376
|
+
When `bkit install` detects **blocker-severity** finding in Phase 3 (e.g. `owned-hook-missing` — a bkit-owned hook file is gone, so the guard or setup step it holds does not run), exits 1 and prints single-line recovery command:
|
|
472
377
|
|
|
473
378
|
```
|
|
474
379
|
[bkit-install] 1 Phase 3 blocker(s) detected. Recovery:
|
|
@@ -466,11 +466,11 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
466
466
|
"step": "plan-generate",
|
|
467
467
|
"subagent": "bkit-plan-generate",
|
|
468
468
|
"model": "claude-opus-4-8",
|
|
469
|
-
"key": "bkit-distribution-via-
|
|
470
|
-
"summary": "
|
|
471
|
-
"description": "
|
|
472
|
-
"rationale": "
|
|
473
|
-
"alternatives": "
|
|
469
|
+
"key": "bkit-distribution-via-npmjs",
|
|
470
|
+
"summary": "publish @cbartens/bkit publicly on npmjs",
|
|
471
|
+
"description": "publish @cbartens/bkit publicly on npmjs; consumers install with no registry mapping, PAT, or CI/Vercel env",
|
|
472
|
+
"rationale": "public install needs no registry mapping or token; release.yml publishes from CI via npm OIDC trusted publishing",
|
|
473
|
+
"alternatives": "private registry with a read token, git-dependency install, Releases tarball, vendor per-consumer",
|
|
474
474
|
"status": "ACTIVE",
|
|
475
475
|
"references": ["ISSUE-138", "ISSUE-130", "package.json", ".github/workflows/release.yml"]
|
|
476
476
|
}
|
|
@@ -68,6 +68,8 @@ New host — row above + `run<Host>Module` (`.bkit/core/engine/install/modules/<
|
|
|
68
68
|
|
|
69
69
|
**Root cause:** macOS GUI apps (Dock/Finder/Spotlight) run under `launchd` — **do not** inherit login-shell env. `direnv` exports from `.bkit/.env` stay shell-only. Token placeholders (`${BKIT_GH_TOKEN}` in `.cursor/mcp.json`, `{env:BKIT_OPENCODE_API_KEY}` in `.opencode/opencode.json`) resolve empty → MCP auth failures.
|
|
70
70
|
|
|
71
|
+
**Shared service env (opencode):** `{env:…}` in `.opencode/opencode.json` resolves in OpenCode's background service — machine-global, one per user, env fixed at service start. Repo-local direnv `.env` is invisible (one repo's `apps/web/.env.local` never reaches another); service env = union of every repo's MCP tokens. Add / rotate a token → source it, then `opencode service restart`.
|
|
72
|
+
|
|
71
73
|
**Fix — launcher verbs:** `bkit cursor` / `bkit opencode` exec app binary with `.bkit/.env` merged into child env. Dynamic, per-repo, zero global state.
|
|
72
74
|
|
|
73
75
|
```
|
|
@@ -297,7 +299,7 @@ Advisory hook, on all four hosts (Claude Code, Cursor, Codex, opencode). Claude
|
|
|
297
299
|
| --- | --- | --- | --- |
|
|
298
300
|
| File / secrets | `.claude/settings.json` → `permissions.{allow,deny,ask}` (`Read(./**/*.pem)` deny; `.env` variants ask; `.env.example` allow) | `.cursor/hooks/bkit-guardrails.cjs` via `preToolUse` (`Read\|TabRead`) — same deny/ask policy | `.opencode/opencode.json` → `permission.read` map |
|
|
299
301
|
| Shell / destructive | `permissions.deny` / `ask` on force-push (not `--force-with-lease`), `rm -rf /*`, publish, destructive git/gh, etc. Shell `curl` / `wget` are not gated here — `permissions` cannot match a URL host, so only the `WebFetch` TOOL is allowlisted | `.cursor/hooks/bkit-guardrails.cjs` via `beforeShellExecution` — same deny/ask policy | `permission.bash` deny/ask map (same rules) |
|
|
300
|
-
| Network fetch | `WebSearch` + tooling `WebFetch(domain:…)`; install/upgrade enriches from the shipped egress registry union consumer `allowed-domains` in `.agents/context.md` (stack hosts never shipped), recording what it wrote so it can later prune it | `curl`/`wget` ask unless host ∈ `.cursor/allowlist.json` (tooling ∪ consumer domains) | `websearch` allow
|
|
302
|
+
| Network fetch | `WebSearch` + tooling `WebFetch(domain:…)`; install/upgrade enriches from the shipped egress registry union consumer `allowed-domains` in `.agents/context.md` (stack hosts never shipped), recording what it wrote so it can later prune it | `curl`/`wget` ask unless host ∈ `.cursor/allowlist.json` (tooling ∪ consumer domains) | `websearch` allow; `webfetch` URL map (`"*": ask` → `*{domain}*: allow`) for the fetch tool **and** `curl *`/`wget *` ask → `curl *{domain}*`/`wget *{domain}*` allow for shell, from the same allowlist (baked into `opencode.json`) |
|
|
301
303
|
| Granularity | Per-tool glob | Hook script (project-scoped, failClosed) | Per-path / per-command glob in `permission` |
|
|
302
304
|
| Modes | `defaultMode: default \| acceptEdits \| plan \| bypassPermissions` | Implicit per-mode (Composer / Agent / Background) | `opencode --auto` + permission defaults |
|
|
303
305
|
| MCP server config | `.mcp.json` at repo root (`mcpServers.<name>.url`) | `.cursor/mcp.json` (same `mcpServers.<name>.url` shape) | `.opencode/opencode.json` → `mcp` |
|
|
@@ -306,7 +308,7 @@ Advisory hook, on all four hosts (Claude Code, Cursor, Codex, opencode). Claude
|
|
|
306
308
|
|
|
307
309
|
**Install behaviour:** template drops, host-specific encoding of the **same** shared policy. No single canonical JSON — three native forms kept in lockstep. Machine-local paths stay out of templates.
|
|
308
310
|
|
|
309
|
-
### Network allowlist — one source,
|
|
311
|
+
### Network allowlist — one source, four hosts
|
|
310
312
|
|
|
311
313
|
**Source of truth:** bkit's own hosts come from the egress registry (`.bkit/core/engine/shared/egress.ts`) and must never be re-declared. Stack domains come from consumer `.agents/context.md` → `<!-- allowed-domains:start -->` **after** `<!-- bkit:end -->` (apex domains). Never ship Vercel/Supabase/Sentry/etc. into every consumer.
|
|
312
314
|
|
|
@@ -316,8 +318,9 @@ Advisory hook, on all four hosts (Claude Code, Cursor, Codex, opencode). Claude
|
|
|
316
318
|
| Host | Where the allowlist lives | Why that shape |
|
|
317
319
|
| --- | --- | --- |
|
|
318
320
|
| **Claude** | `.claude/settings.json` `WebFetch(domain:…)` allow rules; shell fetches host-checked by `.claude/hooks/bkit-guardrails.cjs` (advisory) | Claude has a first-class settings permission model. No separate allowlist file. Shell `curl` is not domain-gated at all — Claude rules match a command prefix, not a URL host, so `curl` runs under `Bash(*)` with `deny` + the auto-mode classifier as backstops. Prefer `WebFetch` for allowlisted hosts; context-fetch uses `curl` / CLI under `Bash(*)`. |
|
|
319
|
-
| **OpenCode** | Baked into `.opencode/opencode.json`
|
|
321
|
+
| **OpenCode** | Baked into `.opencode/opencode.json`: `permission.webfetch` URL map (`"*": "ask"` then `*{domain}*: allow`) for the fetch tool, and `permission.bash` `curl *`/`wget *` **ask** then `curl *{domain}*`/`wget *{domain}*` **allow** for shell fetch (last-match-wins on both) | Both fetch surfaces are domain-gated, so an allowlisted host does not prompt whichever path the agent takes. `webfetch` matches the resource against the requested URL, `bash` against the command string. No separate allowlist file. |
|
|
320
322
|
| **Cursor** | Generated `.cursor/allowlist.json` read at **runtime** by `.cursor/hooks/bkit-guardrails.cjs` | Cursor has no project settings equivalent to Claude `permissions` / OpenCode `permission` for curl host globs. Parity is a **hook** (`beforeShellExecution`): ask on `curl`/`wget` unless the command contains a host from the allowlist. The JSON is Cursor-only by design (IDE-scoped artifact under `.cursor/`, not `.bkit/`). |
|
|
323
|
+
| **Codex** | Reads the same `.cursor/allowlist.json` at runtime via `.codex/hooks/bkit-guardrails.cjs` | Codex has no project-level permission file. The hook host-parses `curl`/`wget` and emits an advisory `ask` — Codex cannot prompt, so the allowlist informs rather than enforces. |
|
|
321
324
|
|
|
322
325
|
**Do not hand-edit** `.cursor/allowlist.json` — regenerate via install/upgrade after changing `allowed-domains`. Missing file ⇒ the hook resolves no hosts and every host reads as unknown; there is deliberately no list embedded in the hook, because a second copy drifts from the registry silently.
|
|
323
326
|
|