@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
|
@@ -546,22 +546,29 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
|
|
|
546
546
|
"{BKIT}" branches push --mode=feature --require-ci >/dev/null
|
|
547
547
|
```
|
|
548
548
|
Hold the close's `parentSha` as `{CLOSE_PARENT}`.
|
|
549
|
-
3.
|
|
549
|
+
3. Probe live PR state (`{PR_OPEN}` = 0 with no probe when `BRANCH` = `dev` **or** `main`):
|
|
550
550
|
```bash
|
|
551
|
-
"{BKIT}"
|
|
552
|
-
"{BKIT}" prs transport-row --file="{STATUS}" --kind=close --shape=push --sha={CLOSE_PARENT} --scan --cross-check=gh
|
|
551
|
+
"{BKIT}" prs probe --head="{BRANCH}" --base=dev
|
|
553
552
|
```
|
|
553
|
+
- **If** exit 0 → `{PR_OPEN}` = 1; hold `number` as `{PR_NUMBER}`, `url` as `{PR_URL}`.
|
|
554
|
+
- **If** exit 1 → `{PR_OPEN}` = 0.
|
|
555
|
+
- **If** exit 80 → `list_pull_requests` (head `{BRANCH}`, base `dev`, state open) → found → `{PR_OPEN}` = 1 with its `number` / `url`; none → `{PR_OPEN}` = 0; record via `"{BKIT}" prs transport-row --file="{STATUS}" --kind=fallback --asserted-by=<re-read>`.
|
|
556
|
+
- **Else** → **Failure Path**.
|
|
557
|
+
- **If** `{PR_OPEN}` = 0 → record the close row and audit the landed commit; `{LIVE_SKIPPED}` = `--field="testsLiveSkipped=No live tests ran, runtime-only defects not gated (not declared or opted out)."` when `TEST_SCOPE` lacks `live`, else empty:
|
|
558
|
+
```bash
|
|
559
|
+
"{BKIT}" steps done --file="{STATUS}" --workflow=debug --step=debug-close-workflow --parent-sha={CLOSE_PARENT} {LIVE_SKIPPED} --commit=none >/dev/null || exit 1
|
|
560
|
+
"{BKIT}" prs transport-row --file="{STATUS}" --kind=close --shape=push --sha={CLOSE_PARENT} --scan --cross-check=gh
|
|
561
|
+
```
|
|
554
562
|
4. Set `TRIGGER_PR`:
|
|
555
563
|
- **If** `BRANCH` = `dev` **or** `main` → push to trigger branch (CI fires) → `TRIGGER_PR` = 0.
|
|
556
|
-
- **If** `
|
|
557
|
-
- **
|
|
558
|
-
|
|
559
|
-
5. **If** `TRIGGER_PR` = 1 → create PR (body names `docs/plans/{YYYYMM}/{FID}-plan.md` if present):
|
|
564
|
+
- **If** `{PR_OPEN}` = 1 → the close push fires `pull_request` → `TRIGGER_PR` = 0.
|
|
565
|
+
- **Else** → `TRIGGER_PR` = 1.
|
|
566
|
+
5. **If** `TRIGGER_PR` = 1 → create or adopt the PR (body names `docs/plans/{YYYYMM}/{FID}-plan.md` if present); `--existing=reuse` adopts a PR that appeared since sub-step 3:
|
|
560
567
|
```bash
|
|
561
|
-
"{BKIT}" prs open --fid={FID} --title="feat({FID}): debug-remediated" --issue="{ISSUE_ID}" --plan=docs/plans/{YYYYMM}/{FID}-plan.md
|
|
568
|
+
"{BKIT}" prs open --fid={FID} --title="feat({FID}): debug-remediated" --issue="{ISSUE_ID}" --existing=reuse --plan=docs/plans/{YYYYMM}/{FID}-plan.md
|
|
562
569
|
```
|
|
563
570
|
Route:
|
|
564
|
-
- **If** exit 0 → hold `number` as `{PR_NUMBER}`, `url` as `{PR_URL}
|
|
571
|
+
- **If** exit 0 → hold `number` as `{PR_NUMBER}`, `url` as `{PR_URL}` (created, or the adopted PR).
|
|
565
572
|
- **If** exit 80 → `create_pull_request` with the printed `title` / `body` / `base` / `head` → its number as `{PR_NUMBER}`, URL as `{PR_URL}`.
|
|
566
573
|
- **Else** → **Failure Path**.
|
|
567
574
|
6. **If** `TRIGGER_PR` = 1 → commit and push the CI-triggering head (`{LABEL_FLAGS}` = one `--label=<name>` per re-read `LABELS` entry):
|
|
@@ -570,7 +577,7 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
|
|
|
570
577
|
git add -A && git commit --allow-empty -m "chore({FID}): create-pr bkit [verbose ci]${AUTO_ROUTE_SUFFIX}" || exit 1
|
|
571
578
|
"{BKIT}" branches push --mode=feature --require-ci
|
|
572
579
|
```
|
|
573
|
-
7. **Run only if** `
|
|
580
|
+
7. **Run only if** `{PR_OPEN}` = 1 **or** `TRIGGER_PR` = 1 — CI-Dispatch Gate on the pushed head; it records `{DISPATCH_ROW}`, cross-checks the transport and records the close transport. `{DISPATCH_ROW}` = `--step=debug-close-workflow {LIVE_SKIPPED}` when `{PR_OPEN}` = 1, `--step=debug-create-pr --artifact={PR_URL}` after a created PR; `{LABEL_FLAGS}` as in sub-step 6:
|
|
574
581
|
```bash
|
|
575
582
|
"{BKIT}" runs dispatch --pr={PR_NUMBER} --fid={FID} {LABEL_FLAGS} --file="{STATUS}" --workflow=debug {DISPATCH_ROW} {CI_REENTRY}
|
|
576
583
|
```
|
|
@@ -617,7 +624,7 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
|
|
|
617
624
|
"{BKIT}" steps gate --file="{STATUS}" --workflow=debug --step=debug-close-workflow
|
|
618
625
|
```
|
|
619
626
|
|
|
620
|
-
- [ ] Mechanical checks passed (`steps gate` exit 0: `debug-close-workflow` row, with `testsLiveSkipped` if no live test, `ciDispatch`
|
|
627
|
+
- [ ] Mechanical checks passed (`steps gate` exit 0: `debug-close-workflow` row, with `testsLiveSkipped` if no live test, `ciDispatch` on every feature-branch close)
|
|
621
628
|
- [ ] PR title `[verbose ci]` stripped (if `PUSH_MODE` = PR)
|
|
622
629
|
|
|
623
630
|
<!-- bkit:tracker true start -->
|
|
@@ -628,7 +635,7 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
|
|
|
628
635
|
|
|
629
636
|
- [ ] No-leak Assertion passed (no `[DEBUG-OBSERVE]` lines survive)
|
|
630
637
|
- [ ] Close committed and pushed (`workflows close` committed telemetry on `feat/{FID}`; `branches push --require-ci` exit 0)
|
|
631
|
-
- [ ]
|
|
638
|
+
- [ ] `TRIGGER_PR` set from the live `prs probe` (`{PR_OPEN}`), not Step-1 `PUSH_MODE`; if a PR was created or adopted: `PR_URL`, `PR_NUMBER` held, step `debug-create-pr` recorded with the PR URL and `ciDispatch`, changes pushed
|
|
632
639
|
- [ ] CI-Dispatch gate ran (`runs dispatch` exit 0, close transport recorded)
|
|
633
640
|
- [ ] Final return displayed (`debug-summary.md` content verbatim)
|
|
634
641
|
|
|
@@ -7,55 +7,62 @@
|
|
|
7
7
|
#
|
|
8
8
|
# Cloud sessions (Claude on the web, Cursor Background Agents) set the SAME
|
|
9
9
|
# variable names in their respective dashboards — never in this file.
|
|
10
|
-
|
|
11
|
-
#
|
|
12
|
-
#
|
|
13
|
-
#
|
|
14
|
-
#
|
|
15
|
-
# tokens
|
|
16
|
-
#
|
|
17
|
-
#
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
# BKIT_GH_TOKEN_INSTALL — GitHub classic PAT with `read:packages` scope. Used by pnpm
|
|
21
|
-
# to authenticate to the GitHub Packages npm registry (npm.pkg.github.com) for
|
|
22
|
-
# @cbartens/* packages. Fine-grained PATs are rejected by GitHub Packages
|
|
23
|
-
# (HTTP 403) — must be classic.
|
|
24
|
-
# Generate at: https://github.com/settings/tokens (Tokens (classic) → Generate)
|
|
25
|
-
# The project .npmrc carries ONLY the @cbartens registry mapping; the auth token
|
|
26
|
-
# is written into pnpm's user-level config via `pnpm config set` (CI step, local
|
|
27
|
-
# once, Vercel installCommand) — version-proof across pnpm 10.x/11.x. pnpm >=10.34.3
|
|
28
|
-
# 401s on a project-.npmrc ${BKIT_GH_TOKEN_INSTALL} env-substitution. See KN-CORE-7.
|
|
29
|
-
BKIT_GH_TOKEN_INSTALL=
|
|
10
|
+
#
|
|
11
|
+
# Keep ~/.config/bkit/launchd.env in sync. GUI/daemon apps (the opencode desktop
|
|
12
|
+
# app, Cursor launched from the Dock, and opencode's background service) do not
|
|
13
|
+
# inherit direnv's exports — they read what `ai.bkit.launchd` publishes to launchd
|
|
14
|
+
# from that file (see .bkit/providers.md § macOS GUI-isolation). It DUPLICATES
|
|
15
|
+
# these tokens and does not track this file, so after ROTATING a value here you
|
|
16
|
+
# must re-sync launchd.env or the app keeps the stale one — e.g. a revoked
|
|
17
|
+
# BKIT_GH_TOKEN makes the GitHub MCP 401 and opencode offers an OAuth "sign in"
|
|
18
|
+
# that then fails with "dynamic auth not supported". Then restart long-lived
|
|
19
|
+
# consumers: opencode snapshots its env at launch, so `opencode service restart`.
|
|
30
20
|
|
|
31
21
|
# Optional examples — not required bkit tooling. Listed so direnv has a name to
|
|
32
22
|
# load if you use that surface; leave blank otherwise.
|
|
33
23
|
|
|
34
|
-
# BKIT_GH_TOKEN — the general-purpose bkit GitHub token
|
|
35
|
-
#
|
|
24
|
+
# BKIT_GH_TOKEN — the general-purpose bkit GitHub token. One token for every GitHub
|
|
25
|
+
# *API* operation bkit tooling performs:
|
|
36
26
|
# - the GitHub MCP server (api.githubcopilot.com/mcp/) via the Authorization header
|
|
37
|
-
# in .mcp.json / .cursor/mcp.json;
|
|
27
|
+
# in .mcp.json / .cursor/mcp.json / .opencode/opencode.json;
|
|
38
28
|
# - self-hosted Renovate's PLATFORM auth (repo Actions secret) when you copy
|
|
39
29
|
# the example `.github/workflows/bkit-renovate.yml` — opens PRs,
|
|
40
30
|
# pushes renovate/* branches, edits workflow SHAs, maintains the dashboard issue.
|
|
41
|
-
#
|
|
31
|
+
#
|
|
32
|
+
# Token TYPE — choose by how many repos / owners bkit touches:
|
|
33
|
+
# - ONE repo, or every repo under ONE owner (a single user, or a single org) →
|
|
34
|
+
# FINE-GRAINED PAT (resource owner = that user or org). Preferred — repo-scoped
|
|
35
|
+
# blast radius + mandatory expiry. Permissions below.
|
|
36
|
+
# - MORE THAN ONE repo across DIFFERENT owners (two or more orgs, or a user + an org) →
|
|
37
|
+
# CLASSIC PAT. A fine-grained PAT is limited to a SINGLE resource owner and cannot
|
|
38
|
+
# span organizations, so it cannot cover this case. Classic reaches every repo your
|
|
39
|
+
# user can access — keep the expiry short; an org may block classic PATs (403), and
|
|
40
|
+
# SAML SSO orgs need the token authorized per org (authorization expires; re-authorize).
|
|
41
|
+
#
|
|
42
|
+
# FINE-GRAINED PAT — Repository permissions (as labelled in the token UI; scope to the
|
|
42
43
|
# repos you work on): Contents: Read and write · Pull requests: Read and write · Issues:
|
|
43
44
|
# Read and write · Workflows: Read and write · Commit statuses: Read and write (Renovate
|
|
44
45
|
# reads a commit's CI state to open the PR + posts its own stability checks; without it it
|
|
45
46
|
# creates the renovate/* branch but 403s on /commits/{sha}/statuses and never opens the PR)
|
|
46
47
|
# · Dependabot alerts: Read (GitHub's vulnerability feed, for security-fix PRs) · Metadata:
|
|
47
|
-
# Read-only. (Actions: Read for the MCP server's run-status queries.)
|
|
48
|
-
#
|
|
49
|
-
#
|
|
50
|
-
#
|
|
51
|
-
#
|
|
52
|
-
#
|
|
53
|
-
#
|
|
54
|
-
#
|
|
55
|
-
#
|
|
56
|
-
#
|
|
57
|
-
# the
|
|
58
|
-
#
|
|
48
|
+
# Read-only. (Actions: Read for the MCP server's run-status queries.) Add Organization
|
|
49
|
+
# Projects: Read and write only for board sync (org-owned boards; shown under the token's
|
|
50
|
+
# Organizations tab, not Repository permissions). There is NO "Checks" permission on
|
|
51
|
+
# fine-grained PATs — check-run writes are App-only, so a PAT-based Renovate uses commit
|
|
52
|
+
# statuses instead.
|
|
53
|
+
# CLASSIC PAT — scopes: `repo` (issues / PRs / contents / commit statuses) · `workflow`
|
|
54
|
+
# · `read:org` · `project` (board sync) · `security_events` (Dependabot / code-scanning
|
|
55
|
+
# feed) · optional `user:email` (Renovate commit authorship on a personal account). There
|
|
56
|
+
# is no separate Checks scope on classic either — commit statuses come via `repo`.
|
|
57
|
+
# Self-hosted Renovate commit authorship: on a PERSONAL-account fine-grained token also add
|
|
58
|
+
# the Account permission "Email addresses: Read" so commits use your verified email.
|
|
59
|
+
# ORG-owned tokens have NO Email-addresses permission — instead set the repo variable
|
|
60
|
+
# RENOVATE_GIT_AUTHOR (Settings -> Secrets and variables -> Actions -> Variables), e.g.
|
|
61
|
+
# `Renovate Bot <renovate@your-domain>` (classic equivalent: the `user:email` scope).
|
|
62
|
+
# This is a WRITE token — do NOT put it on read-only surfaces (Vercel env / project
|
|
63
|
+
# .npmrc).
|
|
64
|
+
# Generate at: https://github.com/settings/personal-access-tokens (fine-grained)
|
|
65
|
+
# https://github.com/settings/tokens (classic)
|
|
59
66
|
BKIT_GH_TOKEN=
|
|
60
67
|
|
|
61
68
|
# BKIT_LINEAR_API_KEY — Linear personal API key. Used by the Linear MCP server
|
|
@@ -112,6 +112,6 @@ Your `/bkit-*` skills and bkit subagents load automatically from the committed
|
|
|
112
112
|
|
|
113
113
|
---
|
|
114
114
|
|
|
115
|
-
`BKIT_GH_TOKEN` fine-grained
|
|
115
|
+
`BKIT_GH_TOKEN` PAT permissions (fine-grained vs classic), the `gh auth login --with-token`
|
|
116
116
|
step, MCP OAuth flow, and the one-environment-per-repo rationale all live in
|
|
117
117
|
`.bkit/cloud.md` § Claude Code on the web.
|
|
@@ -43,8 +43,8 @@ Add **each** line below as a secret (Name = the key, Value = the value). Set the
|
|
|
43
43
|
|
|
44
44
|
- `LINEAR_ISSUE_ID` (Linear tracker) / `GITHUB_ISSUE_ID` (GitHub tracker) are injected
|
|
45
45
|
**per session** by the Cursor integration — do **not** add them here.
|
|
46
|
-
- `BKIT_GH_TOKEN` fine-grained
|
|
47
|
-
§ BKIT_GH_TOKEN permissions (identical scope to the Claude side).
|
|
46
|
+
- `BKIT_GH_TOKEN` PAT permissions (fine-grained for one owner, classic across owners) are documented in `.bkit/cloud.md`
|
|
47
|
+
§ `BKIT_GH_TOKEN` — token permissions (identical scope to the Claude side).
|
|
48
48
|
- Secrets are encrypted at rest and in transit and scoped to the environment.
|
|
49
49
|
|
|
50
50
|
## 3 · Toolchain (in-repo — nothing to paste)
|
|
@@ -212,11 +212,13 @@ Ships in the `bkit-ci.yml` template as the `Check Default Branch Lags Dev` step;
|
|
|
212
212
|
|
|
213
213
|
### One CI run per dev commit (release PR mirrors the `dev` push run)
|
|
214
214
|
|
|
215
|
-
Optional. A same-repo `dev
|
|
215
|
+
Optional. A same-repo promotion PR into the default branch — head `dev`, or a `release/*` branch cut at the `dev` tip — has the same head the `dev` push run already tests, so a full PR run repeats the slowest run in the repo. Mirror mode runs it once.
|
|
216
216
|
|
|
217
|
-
- **Planner** (`Decide Release Mirror`, `bkit-tests-scope`): `pull_request` + head repo == this repo +
|
|
217
|
+
- **Planner** (`Decide Release Mirror`, `bkit-tests-scope`): `pull_request` + head repo == this repo + base == default branch + `head_ref` is a promotion branch (`dev`, or `release/*`) → `mirror_push_run=true`, `run_level=none`, `run_e2e` / `run_live` / `run_migration` / `web_affected=false`. Every lane skips. Field is required in the plan (`false` otherwise). Fork PRs and every other head / base pair keep the normal plan.
|
|
218
218
|
- **Capstone** (`Mirror Push Run`, `bkit-tests-check`, before `Assert Test Plan Followed`): `bkit runs mirror --head <PR head sha> --branch dev --max-minutes 170`. Waits for the `dev` push run at that SHA (each poll is `bkit runs gate --event push`) and passes only when its capstone passed. The step runs bkit, so the job needs a checkout and installed dependencies, both ungated. Neither step `continue-on-error`.
|
|
219
219
|
- **Never skip the PR's required check instead.** A skipped required check can read as passed on the PR while the push run is red.
|
|
220
|
+
- **`release/*` resolves the push run by SHA.** A `release/*` head with no green `dev` push run (extra commits past the `dev` tip) fails the mirror red (exit `3`) — safe, not silent.
|
|
221
|
+
- **bkit's own CI adopts this.** `Decide Release Mirror` accepts `dev` and `release/*`; `Decide Run Level` has no merged-PR → `light` arm, so every `dev` push resolves `full` (precondition 1); the capstone's `Mirror Push Run` runs `bkit runs mirror --head="$PR_HEAD_SHA" --branch=dev --max-minutes=170`.
|
|
220
222
|
|
|
221
223
|
<!-- prettier-ignore -->
|
|
222
224
|
| Push run at PR head | PR `bkit-tests-check` | `bkit runs mirror` exit |
|
|
@@ -267,7 +269,7 @@ Undocumented, and invisible to the toolchain, because the file stays valid YAML,
|
|
|
267
269
|
|
|
268
270
|
**Docs-only-diff precondition:** the `dev`-trigger path routes every post-merge CI failure to `/bkit-debug`. This is only correct for docs-only diffs if the consumer's `bkit-ci.yml` deploy-await step treats a host-cancelled build as skip, not red (skip e2e, stay green; e.g. Vercel `CANCELED`), but if a consumer reds on a host-cancelled build, every docs-only squash-merge to `dev` false-dispatches `/bkit-debug` and burns loop-cap budget. Verify this per consumer before relying on the `dev` trigger.
|
|
269
271
|
|
|
270
|
-
**Consumer-repo acceptance note:** the full happy-path loop (squash-merge → post-merge CI → `workflow_run` → `/bkit-debug` dispatch → fix PR → re-merge) is only exercisable on consumer repos with `bkit-cloud.yml` installed and its dispatch secrets wired (see
|
|
272
|
+
**Consumer-repo acceptance note:** the full happy-path loop (squash-merge → post-merge CI → `workflow_run` → `/bkit-debug` dispatch → fix PR → re-merge) is only exercisable on consumer repos with `bkit-cloud.yml` installed and its dispatch secrets wired (see the cloud-agent auth surfaces in `docs/security.md`). A consumer without `bkit-cloud.yml` installed, or without CI running on `push: branches: [dev]`, never emits the `workflow_run` event this trigger depends on, so the feature degrades to a silent no-op, not a failure.
|
|
271
273
|
|
|
272
274
|
## Ship gate + bookkeeping
|
|
273
275
|
|
|
@@ -387,7 +389,7 @@ Use one. Both open PRs for the same packages. `bkit.depUpdater: "none"` skips th
|
|
|
387
389
|
|
|
388
390
|
**Renovate, self-hosted.** Copy the workflow example. Suspend the Mend App for this repo (Settings → Applications → Renovate → Configure → remove this repo) or both open `renovate/*` PRs. The cron wakes the bot daily; `renovate.json5` `schedule` still gates normal PRs. Do not narrow the cron to weekly, because `osvVulnerabilityAlerts` PRs need the daily wake.
|
|
389
391
|
|
|
390
|
-
Platform auth is a repo secret `BKIT_GH_TOKEN`, never `GITHUB_TOKEN` (those PRs do not trigger CI, so required checks and automerge never fire).
|
|
392
|
+
Platform auth is a repo secret `BKIT_GH_TOKEN`, never `GITHUB_TOKEN` (those PRs do not trigger CI, so required checks and automerge never fire). Use a **fine-grained** PAT when this repo is the only owner-scope bkit touches; use a **classic** PAT when the same token must cover more than one owner — fine-grained PATs cannot span organizations. Fine-grained permissions for this repo:
|
|
391
393
|
|
|
392
394
|
<!-- prettier-ignore -->
|
|
393
395
|
| Repository permission | Access |
|
|
@@ -400,12 +402,7 @@ Platform auth is a repo secret `BKIT_GH_TOKEN`, never `GITHUB_TOKEN` (those PRs
|
|
|
400
402
|
| Dependabot alerts | Read |
|
|
401
403
|
| Metadata | Read-only |
|
|
402
404
|
|
|
403
|
-
`Commit statuses: Read and write` is what opens the PR. Without it Renovate creates the branch and 403s on commit status. There is no separate Checks permission on a fine-grained PAT.
|
|
404
|
-
|
|
405
|
-
**Private package.** `@cbartens/bkit` is on `npm.pkg.github.com`. Lockfile regen resolves it for every bump. Without a read token, regen 401s and CI fails `pnpm install --frozen-lockfile`.
|
|
406
|
-
|
|
407
|
-
- Mend: add `BKIT_GH_TOKEN_INSTALL` as a Mend repository secret and tick "used during the scan as an environment variable". Uncomment the `hostRules` `token` line in `renovate.json5`.
|
|
408
|
-
- Self-hosted: leave that line commented. The example workflow sets `RENOVATE_HOST_RULES` from the Actions secret. An uncommented Mend-style line adds an empty-token rule and 401s.
|
|
405
|
+
`Commit statuses: Read and write` is what opens the PR. Without it Renovate creates the branch and 403s on commit status. There is no separate Checks permission on a fine-grained PAT. Classic equivalent: scopes `repo`, `workflow`, `security_events` (plus `user:email` for commit authorship). Org-owned tokens cannot read the owner email; set the Actions variable `RENOVATE_GIT_AUTHOR` (for example `Renovate Bot <renovate@your-domain>`).
|
|
409
406
|
|
|
410
407
|
**pnpm 11 on Mend's runner.** A large graph can OOM during `pnpm update --lockfile-only`. The example sets `minimumReleaseAge: "1 day"` and caps `PNPM_WORKERS`. To clear the per-install gate, set `minimumReleaseAge: 0` in `pnpm-workspace.yaml`. Deleting the key does not: pnpm 11 defaults it to 1440. Self-hosted on `ubuntu-latest` has the memory; the freshness setting is still yours to keep or drop.
|
|
411
408
|
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
|
|
18
18
|
## Supply-Chain (GitHub Actions)
|
|
19
19
|
|
|
20
|
-
Action SHA-pinning and the dependency-update pipeline (Renovate / Dependabot,
|
|
20
|
+
Action SHA-pinning and the dependency-update pipeline (Renovate / Dependabot, CVE handling) are CI/CD pipeline rules → canonical home `deployments.md` § Dependency updaters; this section keeps only the security invariant.
|
|
21
21
|
|
|
22
22
|
**Token isolation:** Renovate PRs use a restricted `GITHUB_TOKEN` with no access to the cloud lane's model-auth secrets (`secrets.ANTHROPIC_API_KEY` / `secrets.OPENCODE_PROVIDER_KEY`) — `bkit-cloud.yml` will not dispatch on them by design. A compromised dependency PR cannot reach agent API credentials.
|
|
23
23
|
|
package/.bkit/shared/gitignore
CHANGED
|
@@ -89,4 +89,9 @@ playwright/.auth/
|
|
|
89
89
|
# Local MCP / agent secrets — never commit
|
|
90
90
|
.bkit/.env
|
|
91
91
|
|
|
92
|
+
# Payload view links — `bkit install` / `upgrade` symlink these into
|
|
93
|
+
# node_modules/@cbartens/bkit; they dangle on a fresh clone or in CI, so never commit.
|
|
94
|
+
.bkit/core
|
|
95
|
+
.bkit/shared
|
|
96
|
+
|
|
92
97
|
# <!-- bkit:end -->
|
|
@@ -55,11 +55,6 @@ if [ "${CLAUDE_CODE_REMOTE:-}" = "true" ] && command -v jq >/dev/null 2>&1; then
|
|
|
55
55
|
fi
|
|
56
56
|
|
|
57
57
|
if [ -f pnpm-lock.yaml ] && command -v pnpm >/dev/null 2>&1; then
|
|
58
|
-
# Writes the GH Packages auth token into pnpm's user-level config before install,
|
|
59
|
-
# alongside the project .npmrc auth token line.
|
|
60
|
-
if [ -n "${BKIT_GH_TOKEN_INSTALL:-}" ]; then
|
|
61
|
-
pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL" || log "pnpm config set failed (non-blocking)"
|
|
62
|
-
fi
|
|
63
58
|
log "pnpm install --frozen-lockfile"
|
|
64
59
|
pnpm install --frozen-lockfile --prefer-offline || log "pnpm install failed (non-blocking)"
|
|
65
60
|
fi
|
|
@@ -51,7 +51,7 @@ RUN cd /tmp \
|
|
|
51
51
|
&& rm -f "vale_${VALE_VERSION}_Linux_64-bit.tar.gz"
|
|
52
52
|
|
|
53
53
|
# pnpm — corepack-pinned to match `packageManager` in package.json.
|
|
54
|
-
RUN corepack enable && corepack prepare pnpm@10.34.
|
|
54
|
+
RUN corepack enable && corepack prepare pnpm@10.34.4 --activate
|
|
55
55
|
|
|
56
56
|
# --- Consumer extensions ---------------------------------------------------
|
|
57
57
|
# Add per-repo install steps here. Uncomment / adapt as needed:
|
|
@@ -2,5 +2,5 @@
|
|
|
2
2
|
"build": {
|
|
3
3
|
"dockerfile": "Dockerfile"
|
|
4
4
|
},
|
|
5
|
-
"install": "pnpm
|
|
5
|
+
"install": "pnpm install --frozen-lockfile && ([ ! -f .vale.ini ] || vale sync)"
|
|
6
6
|
}
|
|
@@ -88,21 +88,6 @@
|
|
|
88
88
|
".agents/skills/**",
|
|
89
89
|
],
|
|
90
90
|
|
|
91
|
-
// Private-registry read auth for `@cbartens/bkit` on npm.pkg.github.com.
|
|
92
|
-
// Renovate resolves the whole workspace to regenerate the lockfile and needs
|
|
93
|
-
// a read token for this host to do so.
|
|
94
|
-
// Mend: uncomment `token` and add BKIT_GH_TOKEN_INSTALL as a Mend repository
|
|
95
|
-
// secret with "used during the scan as an environment variable" ticked.
|
|
96
|
-
// Self-hosted: leave `token` commented; the example workflow injects
|
|
97
|
-
// RENOVATE_HOST_RULES from the Actions secret instead. Do not commit a literal token.
|
|
98
|
-
// hostRules: [
|
|
99
|
-
// {
|
|
100
|
-
// matchHost: "npm.pkg.github.com",
|
|
101
|
-
// hostType: "npm",
|
|
102
|
-
// token: "{{ secrets.BKIT_GH_TOKEN_INSTALL }}",
|
|
103
|
-
// },
|
|
104
|
-
// ],
|
|
105
|
-
|
|
106
91
|
// Caps on open and hourly PRs.
|
|
107
92
|
prConcurrentLimit: 10,
|
|
108
93
|
prHourlyLimit: 4,
|
|
@@ -43,14 +43,6 @@ jobs:
|
|
|
43
43
|
# (PR title for feature-branch pushes vs commit message for direct dev/main pushes)
|
|
44
44
|
# and docs/testing.md § "CI verbosity" for the full knob list.
|
|
45
45
|
#
|
|
46
|
-
# BKIT_GH_TOKEN_INSTALL is declared at the job level so $BKIT_GH_TOKEN_INSTALL is available to the
|
|
47
|
-
# install step's `pnpm config set` (the REQUIRED GH Packages auth — pnpm >=10.34.3
|
|
48
|
-
# 401s on a project-.npmrc ${BKIT_GH_TOKEN_INSTALL} env-substitution) and to any later
|
|
49
|
-
# pnpm/npx invocation. The committed project .npmrc carries ONLY the @cbartens
|
|
50
|
-
# registry mapping; `pnpm config set` writes the shell-expanded literal token into
|
|
51
|
-
# pnpm's user-level config before install (works across pnpm 10.x/11.x). The install
|
|
52
|
-
# step also keeps its own env: block.
|
|
53
|
-
#
|
|
54
46
|
# NODE_OPTIONS is set HERE, in static YAML, and must NEVER be written to $GITHUB_ENV.
|
|
55
47
|
# The runner blocklists NODE_OPTIONS for the $GITHUB_ENV / set-env workflow command:
|
|
56
48
|
# the write is REJECTED with
|
|
@@ -63,7 +55,6 @@ jobs:
|
|
|
63
55
|
TURBO_LOG_LEVEL: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && 'full' || 'errors-only' }}
|
|
64
56
|
VERBOSE_CI: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && '1' || '' }}
|
|
65
57
|
NODE_OPTIONS: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && '--trace-warnings --trace-deprecation' || '' }}
|
|
66
|
-
BKIT_GH_TOKEN_INSTALL: ${{ secrets.BKIT_GH_TOKEN_INSTALL }}
|
|
67
58
|
steps:
|
|
68
59
|
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
69
60
|
with:
|
|
@@ -216,13 +207,7 @@ jobs:
|
|
|
216
207
|
|
|
217
208
|
- name: Install Dependencies
|
|
218
209
|
if: steps.cache.outputs.skip != 'true'
|
|
219
|
-
|
|
220
|
-
# (REQUIRED — pnpm >=10.34.3 401s on a project-.npmrc ${BKIT_GH_TOKEN_INSTALL} ref).
|
|
221
|
-
run: |
|
|
222
|
-
pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"
|
|
223
|
-
pnpm install --frozen-lockfile
|
|
224
|
-
env:
|
|
225
|
-
BKIT_GH_TOKEN_INSTALL: ${{ secrets.BKIT_GH_TOKEN_INSTALL }}
|
|
210
|
+
run: pnpm install --frozen-lockfile
|
|
226
211
|
|
|
227
212
|
# Static checks first — they read the source tree and must scan it CLEAN.
|
|
228
213
|
# Vitest/build run AFTER (below): they write coverage, dist/, and other
|
|
@@ -318,7 +303,6 @@ jobs:
|
|
|
318
303
|
TURBO_LOG_LEVEL: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && 'full' || 'errors-only' }}
|
|
319
304
|
VERBOSE_CI: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && '1' || '' }}
|
|
320
305
|
NODE_OPTIONS: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && '--trace-warnings --trace-deprecation' || '' }}
|
|
321
|
-
BKIT_GH_TOKEN_INSTALL: ${{ secrets.BKIT_GH_TOKEN_INSTALL }}
|
|
322
306
|
steps:
|
|
323
307
|
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
324
308
|
with:
|
|
@@ -418,11 +402,7 @@ jobs:
|
|
|
418
402
|
|
|
419
403
|
- name: Install Dependencies
|
|
420
404
|
if: steps.cache.outputs.skip != 'true'
|
|
421
|
-
run:
|
|
422
|
-
pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"
|
|
423
|
-
pnpm install --frozen-lockfile
|
|
424
|
-
env:
|
|
425
|
-
BKIT_GH_TOKEN_INSTALL: ${{ secrets.BKIT_GH_TOKEN_INSTALL }}
|
|
405
|
+
run: pnpm install --frozen-lockfile
|
|
426
406
|
|
|
427
407
|
# bkit-stub:supabase-migrate — REMOTE `db push` belongs in `bkit-tests-migration`, NOT here
|
|
428
408
|
# and NOT in `bkit-tests-e2e-web`. Prefer the migration-lane stub below
|
|
@@ -817,8 +797,11 @@ jobs:
|
|
|
817
797
|
# # run_e2e = run_level==full && web_affected_eff. run_live = push dev/main && web_affected_eff (@live stays PUSH-ONLY — real LLM/email side effects; a docs-only/empty [force full] push reaches it via web_affected_eff, NOT off a PR/dispatch).
|
|
818
798
|
# # run_migration: true when migration/seed/seed-generator paths changed (or workflow_dispatch / no-usable-base → run-to-be-safe). Orthogonal to run_level — a run_level=none run can still need replay. Emits into the plan so migration-lane heavy steps gate per-step (job stays always-on).
|
|
819
799
|
# - name: Decide Release Mirror # [U] OPTIONAL — one CI run per dev commit. mirror_push_run = pull_request
|
|
820
|
-
# # && head.repo.full_name == github.repository &&
|
|
821
|
-
# #
|
|
800
|
+
# # && head.repo.full_name == github.repository && base_ref == the default branch && head_ref is a
|
|
801
|
+
# # promotion branch — 'dev', or 'release/*' when the repo promotes via a release branch (bkit's own
|
|
802
|
+
# # does: main only moves via a release/* → main PR). head_ref via env:, injection-safe. The capstone's
|
|
803
|
+
# # bkit runs mirror resolves the push run BY SHA, so a release/* head with no green dev push run fails
|
|
804
|
+
# # red (exit 3), never silently passes. True → LAST word in the plan: run_level=none, run_e2e/run_live/
|
|
822
805
|
# # run_migration/web_affected=false, so every lane skips (migration lane included — it is always-on, so
|
|
823
806
|
# # its replay steps must read run_migration) and the capstone copies the dev push run's verdict (JOB 4).
|
|
824
807
|
# # The release PR head IS the dev tip that push run is testing; re-testing it doubles the slowest run.
|
|
@@ -154,7 +154,6 @@ jobs:
|
|
|
154
154
|
ref: dev
|
|
155
155
|
fetch-depth: 0
|
|
156
156
|
# The auto-provided GITHUB_TOKEN inherits the `permissions:` block above.
|
|
157
|
-
# Do not swap in BKIT_GH_TOKEN_INSTALL — it has no access to the consumer repo.
|
|
158
157
|
token: ${{ github.token }}
|
|
159
158
|
|
|
160
159
|
- name: Configure git user
|
|
@@ -470,7 +469,6 @@ jobs:
|
|
|
470
469
|
ref: dev
|
|
471
470
|
fetch-depth: 0
|
|
472
471
|
# The auto-provided GITHUB_TOKEN inherits the `permissions:` block above.
|
|
473
|
-
# Do not swap in BKIT_GH_TOKEN_INSTALL — it has no access to the consumer repo.
|
|
474
472
|
token: ${{ github.token }}
|
|
475
473
|
|
|
476
474
|
# Installs the vale binary for bkit-cloud-bootstrap.sh's `vale sync` and the dispatched
|
|
@@ -36,7 +36,7 @@ on:
|
|
|
36
36
|
- cron: "17 6 * * *"
|
|
37
37
|
|
|
38
38
|
# Least privilege: Renovate authenticates EVERY GitHub operation with BKIT_GH_TOKEN
|
|
39
|
-
# below (a fine-grained PAT or App token — NOT GITHUB_TOKEN). The job GITHUB_TOKEN
|
|
39
|
+
# below (a fine-grained or classic PAT, or an App token — NOT GITHUB_TOKEN). The job GITHUB_TOKEN
|
|
40
40
|
# needs no write scope.
|
|
41
41
|
permissions:
|
|
42
42
|
contents: read
|
|
@@ -67,13 +67,15 @@ jobs:
|
|
|
67
67
|
# then set `token: ${{ steps.app-token.outputs.token }}` below.
|
|
68
68
|
- uses: renovatebot/github-action@dd5302ec17783b2fc721b19ae7209b57b1587765 # v46.1.17
|
|
69
69
|
with:
|
|
70
|
-
#
|
|
70
|
+
# PAT secret (default). FINE-GRAINED repository permissions (this repo):
|
|
71
71
|
# Contents: Read and write · Pull requests: Read and write ·
|
|
72
72
|
# Workflows: Read and write (the github-actions manager edits
|
|
73
73
|
# .github/workflows/* SHAs) · Issues: Read and write (Dependency Dashboard) ·
|
|
74
74
|
# Dependabot alerts: Read (GitHub's vulnerability feed) · Metadata: Read-only.
|
|
75
|
-
#
|
|
76
|
-
#
|
|
75
|
+
# CLASSIC alternative — when one token must span owners (fine-grained PATs cannot):
|
|
76
|
+
# scopes `repo` · `workflow` · `security_events` (+ `user:email` for authorship).
|
|
77
|
+
# (Personal-account fine-grained tokens only: Account permission "Email addresses: Read"
|
|
78
|
+
# lets Renovate use your verified email as the git author — org-owned tokens have no
|
|
77
79
|
# such permission, so set RENOVATE_GIT_AUTHOR below instead.)
|
|
78
80
|
token: ${{ secrets.BKIT_GH_TOKEN }}
|
|
79
81
|
env:
|
|
@@ -82,7 +84,7 @@ jobs:
|
|
|
82
84
|
RENOVATE_AUTODISCOVER: "false"
|
|
83
85
|
RENOVATE_PLATFORM: github
|
|
84
86
|
# Commit author for Renovate's branches. Optional but recommended on ORG repos:
|
|
85
|
-
# org-owned
|
|
87
|
+
# org-owned tokens cannot grant "Email addresses", so Renovate can't
|
|
86
88
|
# read your email and falls back to the Mend bot author (Unverified commits).
|
|
87
89
|
# Set the repo variable RENOVATE_GIT_AUTHOR (Settings -> Secrets and variables ->
|
|
88
90
|
# Actions -> Variables), e.g. `Renovate Bot <renovate@your-domain>`. Leave the
|
|
@@ -95,11 +97,6 @@ jobs:
|
|
|
95
97
|
# allowedEnv") and Renovate does nothing. Mend allows these via its safeEnv
|
|
96
98
|
# preset; self-hosted must set it explicitly. Glob covers any future PNPM_* var.
|
|
97
99
|
RENOVATE_ALLOWED_ENV: "PNPM_*"
|
|
98
|
-
# Private-registry read auth for the restricted @cbartens/bkit package.
|
|
99
|
-
# Leave the hostRules token line in renovate.json5 commented. BKIT_GH_TOKEN_INSTALL
|
|
100
|
-
# (read:packages) is a repo Actions secret. See docs/deployments.md § Dependency updaters.
|
|
101
|
-
RENOVATE_HOST_RULES: >-
|
|
102
|
-
[{"matchHost":"npm.pkg.github.com","hostType":"npm","token":"${{ secrets.BKIT_GH_TOKEN_INSTALL }}"}]
|
|
103
100
|
LOG_LEVEL: ${{ inputs.logLevel || 'info' }}
|
|
104
101
|
RENOVATE_DRY_RUN: ${{ inputs.dryRun || 'null' }}
|
|
105
102
|
# This env block declares NO ANTHROPIC_API_KEY / BKIT_LINEAR_API_KEY
|