@cbartens/bkit 6.0.0 → 6.1.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/.bkit/README.md +154 -151
- package/.bkit/core/.agents/context.md +95 -29
- package/.bkit/core/.agents/docs.md +17 -15
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
- package/.bkit/core/.agents/rules.md +108 -107
- package/.bkit/core/.agents/skills.md +63 -15
- package/.bkit/core/.bkit/README.md +154 -151
- package/.bkit/core/.bkit/authoring.md +714 -84
- package/.bkit/core/.bkit/cli.md +407 -0
- package/.bkit/core/.bkit/cloud.md +281 -193
- package/.bkit/core/.bkit/comparison.md +43 -41
- package/.bkit/core/.bkit/install.md +154 -84
- package/.bkit/core/.bkit/jsonl.md +193 -130
- package/.bkit/core/.bkit/pipeline.md +114 -114
- package/.bkit/core/.bkit/prompts.md +272 -165
- package/.bkit/core/.bkit/providers.md +457 -271
- package/.bkit/core/.bkit/router.md +69 -0
- package/.bkit/core/.bkit/templates.md +529 -256
- package/.bkit/core/.bkit/trackers.md +80 -52
- package/.bkit/core/.bkit/workflows.md +589 -504
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
- package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
- package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
- package/.bkit/core/AGENTS.md +5 -73
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
- package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
- package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
- package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
- package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
- package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
- package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
- package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
- package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
- package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
- package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
- package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
- package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
- package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
- package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
- package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
- package/.bkit/core/docs/templates/bkit-plan.md +138 -132
- package/.bkit/core/engine/checks/after/auth.ts +40 -37
- package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
- package/.bkit/core/engine/checks/after/index.ts +12 -2
- package/.bkit/core/engine/checks/after/tools.ts +80 -33
- package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
- package/.bkit/core/engine/checks/before/env.ts +1 -1
- package/.bkit/core/engine/checks/before/index.ts +7 -0
- package/.bkit/core/engine/checks/before/repo.ts +40 -0
- package/.bkit/core/engine/checks/status-holes.ts +916 -123
- package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
- package/.bkit/core/engine/checks/tips/detect.ts +32 -0
- package/.bkit/core/engine/checks/tips/index.ts +47 -6
- package/.bkit/core/engine/cli.ts +238 -84
- package/.bkit/core/engine/commands/analysis.ts +128 -76
- package/.bkit/core/engine/commands/ci/ci.ts +363 -29
- package/.bkit/core/engine/commands/ci/pins.ts +172 -0
- package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
- package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
- package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
- package/.bkit/core/engine/commands/land.ts +126 -11
- package/.bkit/core/engine/commands/lib.ts +303 -6
- package/.bkit/core/engine/commands/registry.ts +6 -2
- package/.bkit/core/engine/commands/setup/setup.ts +1 -0
- package/.bkit/core/engine/commands/stats.ts +91 -35
- package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
- package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
- package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
- package/.bkit/core/engine/commands/workflow/context.ts +433 -55
- package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
- package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
- package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
- package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
- package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
- package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
- package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
- package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
- package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
- package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
- package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
- package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
- package/.bkit/core/engine/commands/workflow/status.ts +200 -17
- package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
- package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
- package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
- package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
- package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
- package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
- package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
- package/.bkit/core/engine/install/cloud-env.ts +251 -121
- package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
- package/.bkit/core/engine/install/manifest.ts +60 -12
- package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
- package/.bkit/core/engine/install/modules/cloud.ts +3 -3
- package/.bkit/core/engine/install/modules/codex.ts +15 -2
- package/.bkit/core/engine/install/modules/core.ts +956 -52
- package/.bkit/core/engine/install/modules/cursor.ts +6 -6
- package/.bkit/core/engine/install/modules/opencode.ts +16 -4
- package/.bkit/core/engine/install/template-notes.ts +130 -0
- package/.bkit/core/engine/install/version-file.ts +3 -2
- package/.bkit/core/engine/install/write.ts +5 -0
- package/.bkit/core/engine/ledgers/compact.ts +124 -0
- package/.bkit/core/engine/ledgers/journal.ts +291 -0
- package/.bkit/core/engine/ledgers/status.ts +160 -9
- package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
- package/.bkit/core/engine/render/hosts.ts +114 -14
- package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
- package/.bkit/core/engine/shared/dep-updater.ts +60 -0
- package/.bkit/core/engine/shared/egress.ts +1 -1
- package/.bkit/core/engine/shared/package-manager.ts +9 -0
- package/.bkit/core/engine/shared/settings.ts +92 -17
- package/.bkit/core/engine/shared/timeouts.ts +2 -0
- package/.bkit/core/engine/tools/cli-doc.ts +111 -0
- package/.bkit/core/engine/tools/grammar-density.ts +1 -1
- package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
- package/.bkit/core/engine/tools/instructions.ts +94 -43
- package/.bkit/core/hooks/antigravity-hook.js +25 -10
- package/.bkit/core/hooks/gateguard-engine.js +53 -29
- package/.bkit/core/hooks/guardrails-shell.js +4 -4
- package/.bkit/core/hooks/guardrails-tiers.js +3 -3
- package/.bkit/core/hooks/preflight-linear.sh +9 -9
- package/.bkit/core/hooks/preflight-rules.sh +8 -0
- package/.bkit/core/hooks/readguard-engine.js +29 -10
- package/.bkit/core/hooks/session-rules-advisory.js +61 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
- package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
- package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
- package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
- package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
- package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
- package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
- package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
- package/.bkit/core/prompts/bkit-design-generate.md +68 -52
- package/.bkit/core/prompts/bkit-design-organise.md +73 -35
- package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
- package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
- package/.bkit/core/prompts/bkit-design-spike.md +54 -47
- package/.bkit/core/prompts/bkit-design-update.md +42 -31
- package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
- package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
- package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
- package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
- package/.bkit/core/prompts/bkit-plan-update.md +70 -52
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
- package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
- package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
- package/.bkit/core/workflows/bkit-auto.md +53 -30
- package/.bkit/core/workflows/bkit-build.md +635 -304
- package/.bkit/core/workflows/bkit-debug.md +301 -148
- package/.bkit/core/workflows/bkit-design.md +167 -95
- package/.bkit/core/workflows/bkit-plan.md +172 -84
- package/.bkit/core/workflows/bkit-ship.md +299 -152
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
- package/.bkit/shared/.claude/bkit-cloud.md +12 -10
- package/.bkit/shared/.claude/settings.json +3 -0
- package/.bkit/shared/.codex/bkit-cloud.md +98 -0
- package/.bkit/shared/.codex/hooks.json +20 -0
- package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
- package/.bkit/shared/.opencode/opencode.json +1 -1
- package/.bkit/shared/CLAUDE.md +5 -1
- package/.bkit/shared/GEMINI.md +4 -1
- package/.bkit/shared/docs/architecture.md +4 -7
- package/.bkit/shared/docs/data-schema.md +4 -7
- package/.bkit/shared/docs/deployments.md +239 -166
- package/.bkit/shared/docs/design.md +11 -12
- package/.bkit/shared/docs/noise.md +8 -7
- package/.bkit/shared/docs/observability.md +5 -8
- package/.bkit/shared/docs/security.md +35 -17
- package/.bkit/shared/docs/setup.md +29 -18
- package/.bkit/shared/docs/technology.md +3 -6
- package/.bkit/shared/docs/testing.md +282 -176
- package/.bkit/shared/gitignore +6 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
- package/.bkit/templates/.cursor/Dockerfile +12 -8
- package/.bkit/templates/.cursor/environment.json +1 -1
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
- package/.bkit/templates/.github/renovate.json5 +34 -6
- package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
- package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
- package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
- package/.bkit/templates/.husky/pre-commit +2 -2
- package/.bkit/templates/.husky/pre-push +95 -35
- package/.bkit/templates/.prettierignore +6 -7
- package/.bkit/templates/.vale.ini +27 -27
- package/.bkit/templates/context/bkit-cloudrun.md +23 -15
- package/.bkit/templates/context/bkit-expo.md +70 -52
- package/.bkit/templates/context/bkit-github.md +93 -56
- package/.bkit/templates/context/bkit-inngest.md +21 -15
- package/.bkit/templates/context/bkit-maestro.md +22 -16
- package/.bkit/templates/context/bkit-playwright.md +23 -17
- package/.bkit/templates/context/bkit-resend.md +12 -10
- package/.bkit/templates/context/bkit-sentry.md +30 -20
- package/.bkit/templates/context/bkit-serena.md +8 -7
- package/.bkit/templates/context/bkit-stripe.md +14 -13
- package/.bkit/templates/context/bkit-supabase.md +16 -13
- package/.bkit/templates/context/bkit-tavily.md +14 -11
- package/.bkit/templates/context/bkit-vercel.md +27 -18
- package/.bkit/templates/docs/capabilities.md +15 -14
- package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
- package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
- package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
- package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
- package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
- package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
- package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
- package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
- package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
- package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
- package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
- package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
- package/.bkit/templates/slop-scan.config.json +9 -2
- package/CHANGELOG.md +119 -0
- package/README.md +250 -76
- package/dist/checks/after/auth.js +36 -33
- package/dist/checks/after/ci-yml.js +52 -2
- package/dist/checks/after/index.js +12 -4
- package/dist/checks/after/tools.js +73 -33
- package/dist/checks/before/context-fetch.js +218 -33
- package/dist/checks/before/env.js +1 -1
- package/dist/checks/before/index.js +6 -2
- package/dist/checks/before/repo.js +35 -1
- package/dist/checks/status-holes.js +739 -114
- package/dist/checks/tips/catalogue.js +59 -17
- package/dist/checks/tips/detect.js +30 -0
- package/dist/checks/tips/index.js +48 -6
- package/dist/cli.js +222 -84
- package/dist/commands/analysis.js +77 -53
- package/dist/commands/ci/ci.js +302 -25
- package/dist/commands/ci/pins.js +142 -0
- package/dist/commands/ci/push-gate.js +194 -0
- package/dist/commands/install/uninstall.js +23 -27
- package/dist/commands/install/upgrade.js +21 -11
- package/dist/commands/land.js +126 -10
- package/dist/commands/lib.js +244 -5
- package/dist/commands/registry.js +6 -2
- package/dist/commands/setup/setup.js +1 -0
- package/dist/commands/stats.js +69 -30
- package/dist/commands/workflow/branches.js +1232 -111
- package/dist/commands/workflow/challenge.js +90 -37
- package/dist/commands/workflow/completeness.js +97 -0
- package/dist/commands/workflow/context.js +371 -51
- package/dist/commands/workflow/counters.js +206 -40
- package/dist/commands/workflow/decisions.js +60 -17
- package/dist/commands/workflow/disk.js +213 -55
- package/dist/commands/workflow/fids.js +18 -1
- package/dist/commands/workflow/issues.js +6 -0
- package/dist/commands/workflow/ledgers.js +372 -21
- package/dist/commands/workflow/locks.js +2 -0
- package/dist/commands/workflow/plan-blocks.js +78 -14
- package/dist/commands/workflow/plans.js +205 -0
- package/dist/commands/workflow/prs.js +12 -3
- package/dist/commands/workflow/repo.js +6 -0
- package/dist/commands/workflow/roadmap.js +50 -17
- package/dist/commands/workflow/run-facts.js +23 -28
- package/dist/commands/workflow/runs.js +530 -33
- package/dist/commands/workflow/runtime.js +3 -0
- package/dist/commands/workflow/skills.js +1 -0
- package/dist/commands/workflow/status.js +166 -19
- package/dist/commands/workflow/step-table.js +61 -29
- package/dist/commands/workflow/steps.js +542 -26
- package/dist/commands/workflow/summary-findings.js +117 -0
- package/dist/commands/workflow/summary.js +154 -41
- package/dist/commands/workflow/tasks.js +378 -0
- package/dist/commands/workflow/test-blocks.js +231 -0
- package/dist/commands/workflow/tests-changed.js +172 -0
- package/dist/commands/workflow/tests.js +1013 -321
- package/dist/commands/workflow/workflows.js +191 -38
- package/dist/commands/workflow/worktrees.js +310 -42
- package/dist/install/cloud-env.js +233 -99
- package/dist/install/context-ci-workflow.js +85 -0
- package/dist/install/manifest.js +57 -12
- package/dist/install/modules/antigravity.js +3 -2
- package/dist/install/modules/cloud.js +3 -3
- package/dist/install/modules/codex.js +12 -2
- package/dist/install/modules/core.js +851 -53
- package/dist/install/modules/cursor.js +6 -6
- package/dist/install/modules/opencode.js +11 -5
- package/dist/install/template-notes.js +116 -0
- package/dist/install/version-file.js +3 -2
- package/dist/ledgers/compact.js +87 -0
- package/dist/ledgers/journal.js +233 -0
- package/dist/ledgers/status.js +115 -5
- package/dist/ledgers/telemetry.js +121 -17
- package/dist/render/hosts.js +100 -14
- package/dist/shared/bkit-latest.js +26 -4
- package/dist/shared/dep-updater.js +49 -0
- package/dist/shared/egress.js +1 -1
- package/dist/shared/package-manager.js +6 -0
- package/dist/shared/settings.js +59 -10
- package/dist/shared/timeouts.js +2 -0
- package/dist/tools/cli-doc.js +97 -0
- package/dist/tools/grammar-density.js +1 -1
- package/dist/tools/instructions-sources.js +15 -16
- package/dist/tools/instructions.js +83 -39
- package/package.json +58 -42
- package/.bkit/core/.bkit/lite.md +0 -73
- package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
- package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
- package/dist/commands/workflow/workstreams.js +0 -149
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
- /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
- /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
- /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
- /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
|
@@ -3,18 +3,17 @@
|
|
|
3
3
|
{{BKIT_MANAGED_MARKER}}
|
|
4
4
|
|
|
5
5
|
> [!CAUTION]
|
|
6
|
-
> **Purpose:** Every template bkit ships
|
|
6
|
+
> **Purpose:** Every template bkit ships but never installs: what each one does, where to copy it, and how to install the tool behind it.
|
|
7
7
|
>
|
|
8
8
|
> **Rules:**
|
|
9
9
|
>
|
|
10
|
-
> -
|
|
11
|
-
> -
|
|
12
|
-
> -
|
|
13
|
-
> - Adapt app roots, workspace package scope, rules JSON. Examples use `apps/web`, `apps/mobile`, `packages/api`, `@scope`.
|
|
10
|
+
> - Follow `.bkit/authoring.md` § All Agent-Read Files and § Docs when you edit this file.
|
|
11
|
+
> - `bkit install` and `bkit upgrade` never write these files and never overwrite a copy, with one exception: they rewrite an adopted copy where bkit's exact shipped old text matches (the brand migrations, `docs/migrations.md`), never otherwise.
|
|
12
|
+
> - Adapt the app roots, the workspace package scope and the rules JSON. The examples use `apps/web`, `apps/mobile`, `packages/api` and `@scope`.
|
|
14
13
|
|
|
15
14
|
## What each template is for
|
|
16
15
|
|
|
17
|
-
|
|
16
|
+
The adoption order is the `bkit tips` order. The machine lock has no tip, so adopt it when test gates or local services need to run one at a time across checkouts. The health check has no tip either: the `bkit-stub-health` advisory raises it while your CI copy keeps that stub. The sections below give each template's install steps and traps.
|
|
18
17
|
|
|
19
18
|
<!-- prettier-ignore -->
|
|
20
19
|
| Template | What it's for | Skip it and |
|
|
@@ -22,6 +21,7 @@ Adoption order = `bkit tips` order. Local stack lock has no tip (nothing in a re
|
|
|
22
21
|
| direnv | Loads `.bkit/.env` tokens whenever the project opens. | Saved tokens never load; every sign-in fails while the file looks right. |
|
|
23
22
|
| Serena | Agents look code up like an editor ("where is this defined, what uses it?"). Read-only. | Agents grep and read whole files: more accidental changes, more correction rounds, higher token cost. |
|
|
24
23
|
| CI workflow + CI scripts | Runs every check on GitHub on every change; one capstone check gates merge; `/bkit-ship` waits for it. | "Shipped" means merged, not checked. |
|
|
24
|
+
| Health check | After CI promotes a release, probes production's health URL. | A release that went live broken stays unnoticed until a user reports it. |
|
|
25
25
|
| Git hooks (Husky) | Same checks locally on commit and push, in seconds. | Failures surface minutes later in CI, after the agent moved on. |
|
|
26
26
|
| Prettier ignore list | One formatting baseline; stops Prettier reformatting bkit's managed files. | Reviews fill with spacing noise; every bkit upgrade shows false changes. |
|
|
27
27
|
| slop-scan | Flags net-new junk code AI tends to write (filler, dead code, type escapes). | Junk passes skim review and piles up. |
|
|
@@ -38,7 +38,7 @@ Adoption order = `bkit tips` order. Local stack lock has no tip (nothing in a re
|
|
|
38
38
|
| Prettier tables | One edited cell = one changed row in the diff. | A one-word table edit diffs as the whole table. |
|
|
39
39
|
| tmp/ prune | Each push deletes scratch files agents left in `tmp/` untouched for a week. | `tmp/` keeps growing; old logs and scratch files are never cleared. |
|
|
40
40
|
| Disk prune | Your own cleanup steps (build caches, Docker, simulators) run on commit, on push, and before a worktree is made on a low disk. bkit deletes nothing itself. | Caches fill the disk until no worktree can be made; every workflow stops. |
|
|
41
|
-
|
|
|
41
|
+
| Machine lock | Named locks run one gate at a time across repositories; the unnamed lock protects local services every worktree shares. A second run waits and names the holder. | Test gates compete for CPU, or a reset stops the stack under another worktree's test run. |
|
|
42
42
|
| Cursor editor + cloud agent | Format-on-save, recommended extensions, Cursor cloud-agent image. | Cursor edits miss project formatting; no Cursor cloud agent. |
|
|
43
43
|
| Launchd GUI env | macOS apps opened from the Dock get the same tokens as the terminal. | Dock-launched editors start signed out. |
|
|
44
44
|
|
|
@@ -48,12 +48,13 @@ Adoption order = `bkit tips` order. Local stack lock has no tip (nothing in a re
|
|
|
48
48
|
| Tool | Copy from | To | Output you commit |
|
|
49
49
|
| --- | --- | --- | --- |
|
|
50
50
|
| CI workflow | `.bkit/templates/.github/workflows/bkit-ci.yml` | `.github/workflows/bkit-ci.yml` | that file |
|
|
51
|
-
| CI scripts | `.bkit/templates/scripts/ci/` | `scripts/ci/` | the scripts you adopt (`lanes/resolve-push-base.mjs` + `.test.mjs`, CI's push base, also run by pre-push; `check-accepted-divergences.mjs` + `accepted-divergences.json`; `check-dependency-audit.mjs` + `accepted-advisories.json
|
|
51
|
+
| CI scripts | `.bkit/templates/scripts/ci/` | `scripts/ci/` | the scripts you adopt (`lanes/bkit-resolve-push-base.mjs` + `.test.mjs`, CI's push base, also run by pre-push; `bkit-check-accepted-divergences.mjs` + `bkit-accepted-divergences.json`; `bkit-check-dependency-audit.mjs` + `bkit-accepted-advisories.json`, also run by pre-push). `bkit-check-capstone.mjs` + `bkit-check-capstone.test.mjs` are required with `bkit-ci.yml`, not optional |
|
|
52
|
+
| Health check | `.bkit/templates/.github/workflows/bkit-health.yml` | `.github/workflows/bkit-health.yml` | that file |
|
|
52
53
|
| Cloud-agent workflow | `.bkit/templates/.github/workflows/bkit-cloud.yml` | `.github/workflows/bkit-cloud.yml` | that file |
|
|
53
54
|
| Git hooks (Husky) | `.bkit/templates/.husky/pre-commit`, `.bkit/templates/.husky/pre-push` | `.husky/pre-commit`, `.husky/pre-push` | both files |
|
|
54
55
|
| Prettier ignore list | `.bkit/templates/.prettierignore` | `.prettierignore` | that file |
|
|
55
56
|
| lint-staged | `.bkit/templates/.lintstagedrc.json` | `.lintstagedrc.json` | that file |
|
|
56
|
-
| Vale | `.bkit/templates/.vale.ini`, `.bkit/templates/.vale/styles/
|
|
57
|
+
| Vale | `.bkit/templates/.vale.ini`, `.bkit/templates/.vale/styles/Bkit/` | `.vale.ini`, `.vale/styles/Bkit/` | `.vale.ini` + the four Bkit styles |
|
|
57
58
|
| slop-scan | `.bkit/templates/slop-scan.config.json`, `.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs` | `slop-scan.config.json`, `scripts/slop/bkit-slop-type-suppression.mjs` | both files |
|
|
58
59
|
| Oxlint | `.bkit/templates/.oxlintrc.json` | `.oxlintrc.json` | that file |
|
|
59
60
|
| direnv | `.bkit/templates/.envrc` | `.envrc` | that file |
|
|
@@ -70,89 +71,101 @@ Adoption order = `bkit tips` order. Local stack lock has no tip (nothing in a re
|
|
|
70
71
|
| Prettier tables | `.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs` | `scripts/prettier/` | that file |
|
|
71
72
|
| tmp/ prune | `.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs` | `scripts/cleanup/` | that file |
|
|
72
73
|
| Disk prune | `.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs`, `bkit-disk-prune.machine.mjs` | `scripts/cleanup/bkit-disk-prune.mjs`, `~/.config/bkit/disk-prune.mjs` | `scripts/cleanup/bkit-disk-prune.mjs` only |
|
|
73
|
-
|
|
|
74
|
+
| Machine lock | `.bkit/templates/scripts/ci/bkit-machine-lock.sh` | `scripts/ci/` | that file |
|
|
75
|
+
| Local test sleep prevention | `.bkit/templates/scripts/ci/bkit-test-awake.mjs`, `bkit-test-awake.test.mjs` | `scripts/ci/` | both files |
|
|
74
76
|
| Context-fetch blocks | `.bkit/templates/context/bkit-<provider>.md` | below `<!-- bkit:end -->` in `.agents/context.md` | the blocks you use |
|
|
75
77
|
| Cloud SessionStart hook | `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` | `.claude/hooks/bkit-cloud-bootstrap.sh` | that file |
|
|
76
78
|
|
|
77
|
-
Placeholders
|
|
79
|
+
Placeholders: the copies keep them raw, so replace each one in your copy:
|
|
78
80
|
|
|
79
81
|
<!-- prettier-ignore -->
|
|
80
82
|
| Placeholder | In | Put | Typical value |
|
|
81
83
|
| --- | --- | --- | --- |
|
|
82
|
-
| `{{DEFAULT_BRANCH}}` | `bkit-ci.yml` (`on.push` / `on.pull_request` branches; stub comments), `bkit-trivy.yml` (`on.push` / `on.pull_request` branches) | your production branch | `origin/HEAD` unless it is `dev`, else `main` |
|
|
84
|
+
| `{{DEFAULT_BRANCH}}` | `bkit-ci.yml` (`on.push` / `on.pull_request` branches; stub comments), `bkit-trivy.yml` (`on.push` / `on.pull_request` branches), `bkit-health.yml` (`on.workflow_run` branches) | your production branch | `origin/HEAD` unless it is `dev`, else `main` |
|
|
85
|
+
| `{{PRODUCTION_URL}}` | `bkit-health.yml` (`env.PRODUCTION_URL`) | the origin production serves | `https://example.com` |
|
|
83
86
|
| `{{NODE_VERSION}}` | `bkit-ci.yml` (`actions/setup-node` `node-version`, both lanes) | your Node major, or swap the line for `node-version-file: .nvmrc` | `.nvmrc`, then `engines.node`, then `22` |
|
|
84
87
|
| `{{CLOUD_RUNNER}}` | `bkit-cloud.yml` (`runs-on`, all three jobs) | a runner label | `ubuntu-latest` |
|
|
85
|
-
| `{{SCRIPT_PATH}}` | `
|
|
86
|
-
| `{{ENV_FILE}}` | `
|
|
88
|
+
| `{{SCRIPT_PATH}}` | `bkit-launchd.plist` (`ProgramArguments`) | absolute path to the loader script, outside a TCC-protected folder (see § Launchd GUI environment) | `/Users/<you>/.config/bkit/bkit-launchd-env.sh` |
|
|
89
|
+
| `{{ENV_FILE}}` | `bkit-launchd.plist` (`ProgramArguments`, `WatchPaths`) | absolute path to your env file | `/Users/<you>/.config/bkit/launchd.env` |
|
|
87
90
|
|
|
88
91
|
- `bkit install` / `bkit upgrade` refresh `.bkit/templates/` to the package's templates, unsubstituted. `bkit check` fails on a stale copy. `bkit uninstall` removes the folder, never an adopted copy.
|
|
89
|
-
- **What changed on upgrade.** `bkit upgrade` lists changed
|
|
90
|
-
- Repo gates that scan the whole repo (prettier, Vale, slop-scan, eslint, tsc)
|
|
91
|
-
- Templates are written in Node unless the tool they wrap already needs another runtime (graphify and Serena: Python
|
|
92
|
-
- `bkit.dependencies.updater
|
|
93
|
-
- No
|
|
92
|
+
- **What changed on upgrade.** `bkit upgrade` lists the changed, added and removed template paths. For each one you adopted, run `diff .bkit/templates/<path> <path>`, and merge what you want. The placeholder lines differ by design. `git diff .bkit/templates` in the upgrade commit shows the package change.
|
|
93
|
+
- Repo gates that scan the whole repo (prettier, Vale, slop-scan, eslint, tsc) must ignore `.bkit/templates/`. The `.prettierignore`, `.vale.ini`, `slop-scan.config.json` and `.oxlintrc.json` templates already do. Check that your adopted copy does too.
|
|
94
|
+
- Templates are written in Node unless the tool they wrap already needs another runtime (graphify and Serena: Python and shell launchers; git hooks: POSIX `sh`; local stack lock: bash and perl, because shell runners source it).
|
|
95
|
+
- `bkit.dependencies.updater` names the adopted updater (`"renovate"` / `"dependabot"`). Install fills it from the config present. `"none"` skips the install-time absence advisory. `bkit check` blocks when the setting and the configs disagree.
|
|
96
|
+
- No template has a manifest key. `docs/templates/bkit-audit-adoption.md` lists every template on each run, as adopted and wired, or as not adopted with the reason.
|
|
94
97
|
|
|
95
98
|
## Context-fetch blocks — `.agents/context.md`
|
|
96
99
|
|
|
97
|
-
`/bkit-debug` runs every `context-fetch` block below `<!-- bkit:end -->` in `.agents/context.md
|
|
100
|
+
`/bkit-debug` runs every `context-fetch` block below `<!-- bkit:end -->` in `.agents/context.md`, and cloud setup runs every `context-fetch:provision` block there. Each provider has one file, which holds:
|
|
101
|
+
|
|
102
|
+
- its fetch blocks, one per context, of which you copy one or more
|
|
103
|
+
- each fetch block's provision block (stack CLI only)
|
|
104
|
+
- the `allowed-domains` it needs beyond bkit's derived egress set
|
|
105
|
+
- its `mcp-servers` names
|
|
106
|
+
|
|
107
|
+
The block rules (markers, contexts, self-skip, output bounds) are in the managed block of `.agents/context.md`. Each fetch block bounds its own output at the source, with a window, a severity / level filter, a row / line cap, a page cap or a per-lane tail, because everything it prints is written into an artifact that an agent then reads. A block that bounds nothing downloads a whole-run dump, and only the post-hoc clamp catches it (`bkit check` advises, `context-fetch-unbounded`).
|
|
108
|
+
|
|
109
|
+
For selected CI, `context fetch --ci-selection-file` supplies the four `BKIT_CI_*` identity inputs listed below and validates the `bkit-ci-evidence` receipt defined in `.agents/context.md`. The receipt follows complete metadata, job and log reads; empty, partial or mismatched evidence stays unchecked. An unpinned block discovers its own source. Consumer-owned blocks remain unchanged on upgrade; Debug adapts a temporary script for the selected identity.
|
|
98
110
|
|
|
99
111
|
<!-- prettier-ignore -->
|
|
100
112
|
| File | Fits | `context=` | Fetches | Secret / non-secret env | Domains | CLI (provision) |
|
|
101
113
|
| --- | --- | --- | --- | --- | --- | --- |
|
|
102
|
-
| `github.md` | GitHub Actions | `ci`, `diff` | `ci`:
|
|
103
|
-
| `playwright.md` | Playwright on GitHub Actions | `e2e` | failing run's report artifact, failing specs first; inlined files, lines and binary paths capped | `GH_TOKEN` / `E2E_ARTIFACT`, `E2E_JOB_RE`, `E2E_MAX_FILES`, `E2E_MAX_LINES`, `E2E_MAX_BIN` | — | `gh` (base tool) |
|
|
104
|
-
| `maestro.md` | Maestro iOS and Android lanes on GitHub Actions | `e2e` | every failed Maestro job's log, sliced to the result steps, each slice tail-bounded | `GH_TOKEN` / `MAESTRO_JOB_RE`, `MAESTRO_STEPS`, `MAESTRO_LOG_TAIL` | — | `gh` (base tool) |
|
|
105
|
-
| `tavily.md` | any | `web` | web search for upstream causes (untrusted output) | `BKIT_TAVILY_API_KEY` / `QUERY` | — | — |
|
|
106
|
-
| `sentry.md` | Sentry | `runtime` | unresolved issues seen in a window (organization issues endpoint), optional environment; trace / window recipes; detector-header strip | `SENTRY_AUTH_TOKEN` / `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_HOST`, `SENTRY_SINCE`, `SENTRY_ENV`, `SENTRY_N` | `sentry.io` | — |
|
|
107
|
-
| `vercel.md` | Vercel | `runtime` | serverless + edge error / fatal logs in a window, paged past the CLI's 50-line cap, all branches (`--no-branch`) | `VERCEL_TOKEN` / `VERCEL_SCOPE`, `VERCEL_ENV`, `SINCE`, `UNTIL`, `VERCEL_MAX_PAGES` | `vercel.com` | `vercel` (yes) |
|
|
108
|
-
| `supabase.md` | hosted Supabase | `runtime` | Postgres `ERROR` / `FATAL` / `PANIC` counts per hour, severity, SQLSTATE and role; one call per day of window | `SUPABASE_ACCESS_TOKEN` / `SUPABASE_PROJECT_ID`, `SINCE_ISO`, `UNTIL_ISO` | `supabase.com` | — |
|
|
109
|
-
| `stripe.md` | Stripe | `runtime` | failure / dispute / refund events, filtered by type and window at the source, paged; events whose webhook delivery failed | `STRIPE_SECRET_KEY` / `STRIPE_SINCE_S`, `STRIPE_MAX_PAGES` | `stripe.com` | — |
|
|
110
|
-
| `resend.md` | Resend | `runtime` | bounced / complained / failed / delayed sends, paged back to the window start | `RESEND_API_KEY` / `SINCE_ISO`, `RESEND_MAX_PAGES` | `resend.com` | — |
|
|
111
|
-
| `inngest.md` | Inngest Cloud | `runtime` | `inngest/function.failed` events in a window, paged; error class only, never error text | `INNGEST_SIGNING_KEY` / `INNGEST_ENV` (required with a branch key), `SINCE_ISO`, `UNTIL_ISO`, `INNGEST_N`, `INNGEST_MAX_PAGES` | `inngest.com` | — |
|
|
112
|
-
| `cloudrun.md` | Google Cloud Run | `runtime` | container errors + memory-limit kills; service account only when the gcloud login cannot mint a token | `GCP_CLIENT_EMAIL`, `GCP_PRIVATE_KEY` (headless) / `GCP_PROJECT_ID`, `GCP_SERVICE`, `GCP_FILTER` | `googleapis.com`, `google.com` | `gcloud` (yes) |
|
|
113
|
-
| `expo.md` | Expo EAS Build + EAS Workflows (Maestro) | `runtime`, `e2e` | `runtime`: newest 50 builds' status + errored-build log lines (capped per build); `e2e`: recent and FAILURE run lists, failed jobs' per-flow exceptions, JUnit (capped), screenshots, Maestro commands, hierarchy dumps, XCUITest + JS console | `EXPO_TOKEN` / `EXPO_APP_DIR`, `EAS_PLATFORM`, `EAS_PROFILE`, `EAS_N`, `EAS_LOG_N` (`runtime`); `EAS_WF_FILE`, `EAS_WF_N`, `EAS_WF_FAIL_N`, `EAS_JUNIT_N` (`e2e`) | `expo.dev`, `googleapis.com` (`runtime`), `eascdn.net` (`e2e`) | `eas` (yes) |
|
|
114
|
-
| `serena.md` | Serena MCP server | — | nothing: provision only, installs `serena` in cloud | — | — | `uv` (yes) |
|
|
115
|
-
|
|
116
|
-
MCP names
|
|
117
|
-
|
|
118
|
-
Placeholders
|
|
114
|
+
| `bkit-github.md` | GitHub Actions | `ci`, `diff` | `ci`: exact selected run/attempt, complete identity receipt and bounded logs for every failed job; `diff`: selected failing commit against an ancestral same-workflow green baseline | `GH_TOKEN` / `CI_LOG_TAIL`; optional `BKIT_CI_RUN_ID`, `BKIT_CI_RUN_ATTEMPT`, `BKIT_CI_REPO`, `BKIT_CI_HEAD_SHA`; configured `bkit.testing.ciWorkflow`; `BASELINE_BRANCH`, `BASELINE_WORKFLOW`, `DIFF_STAT_N` (`diff`) | — | `gh` (base tool) |
|
|
115
|
+
| `bkit-playwright.md` | Playwright on GitHub Actions | `e2e` | failing run's report artifact, failing specs first; inlined files, lines and binary paths capped | `GH_TOKEN` / `E2E_ARTIFACT`, `E2E_JOB_RE`, `E2E_MAX_FILES`, `E2E_MAX_LINES`, `E2E_MAX_BIN` | — | `gh` (base tool) |
|
|
116
|
+
| `bkit-maestro.md` | Maestro iOS and Android lanes on GitHub Actions | `e2e` | every failed Maestro job's log, sliced to the result steps, each slice tail-bounded | `GH_TOKEN` / `MAESTRO_JOB_RE`, `MAESTRO_STEPS`, `MAESTRO_LOG_TAIL` | — | `gh` (base tool) |
|
|
117
|
+
| `bkit-tavily.md` | any | `web` | web search for upstream causes (untrusted output) | `BKIT_TAVILY_API_KEY` / `QUERY` | — | — |
|
|
118
|
+
| `bkit-sentry.md` | Sentry | `runtime` | unresolved issues seen in a window (organization issues endpoint), optional environment; trace / window recipes; detector-header strip | `SENTRY_AUTH_TOKEN` / `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_HOST`, `SENTRY_SINCE`, `SENTRY_ENV`, `SENTRY_N` | `sentry.io` | — |
|
|
119
|
+
| `bkit-vercel.md` | Vercel | `runtime` | serverless + edge error / fatal logs in a window, paged past the CLI's 50-line cap, all branches (`--no-branch`) | `VERCEL_TOKEN` / `VERCEL_SCOPE`, `VERCEL_ENV`, `SINCE`, `UNTIL`, `VERCEL_MAX_PAGES` | `vercel.com` | `vercel` (yes) |
|
|
120
|
+
| `bkit-supabase.md` | hosted Supabase | `runtime` | Postgres `ERROR` / `FATAL` / `PANIC` counts per hour, severity, SQLSTATE and role; one call per day of window | `SUPABASE_ACCESS_TOKEN` / `SUPABASE_PROJECT_ID`, `SINCE_ISO`, `UNTIL_ISO` | `supabase.com` | — |
|
|
121
|
+
| `bkit-stripe.md` | Stripe | `runtime` | failure / dispute / refund events, filtered by type and window at the source, paged; events whose webhook delivery failed | `STRIPE_SECRET_KEY` / `STRIPE_SINCE_S`, `STRIPE_MAX_PAGES` | `stripe.com` | — |
|
|
122
|
+
| `bkit-resend.md` | Resend | `runtime` | bounced / complained / failed / delayed sends, paged back to the window start | `RESEND_API_KEY` / `SINCE_ISO`, `RESEND_MAX_PAGES` | `resend.com` | — |
|
|
123
|
+
| `bkit-inngest.md` | Inngest Cloud | `runtime` | `inngest/function.failed` events in a window, paged; error class only, never error text | `INNGEST_SIGNING_KEY` / `INNGEST_ENV` (required with a branch key), `SINCE_ISO`, `UNTIL_ISO`, `INNGEST_N`, `INNGEST_MAX_PAGES` | `inngest.com` | — |
|
|
124
|
+
| `bkit-cloudrun.md` | Google Cloud Run | `runtime` | container errors + memory-limit kills; service account only when the gcloud login cannot mint a token | `GCP_CLIENT_EMAIL`, `GCP_PRIVATE_KEY` (headless) / `GCP_PROJECT_ID`, `GCP_SERVICE`, `GCP_FILTER` | `googleapis.com`, `google.com` | `gcloud` (yes) |
|
|
125
|
+
| `bkit-expo.md` | Expo EAS Build + EAS Workflows (Maestro) | `runtime`, `e2e` | `runtime`: newest 50 builds' status + errored-build log lines (capped per build); `e2e`: recent and FAILURE run lists, failed jobs' per-flow exceptions, JUnit (capped), screenshots, Maestro commands, hierarchy dumps, XCUITest + JS console | `EXPO_TOKEN` / `EXPO_APP_DIR`, `EAS_PLATFORM`, `EAS_PROFILE`, `EAS_N`, `EAS_LOG_N` (`runtime`); `EAS_WF_FILE`, `EAS_WF_N`, `EAS_WF_FAIL_N`, `EAS_JUNIT_N` (`e2e`) | `expo.dev`, `googleapis.com` (`runtime`), `eascdn.net` (`e2e`) | `eas` (yes) |
|
|
126
|
+
| `bkit-serena.md` | Serena MCP server | — | nothing: provision only, installs `serena` in cloud | — | — | `uv` (yes) |
|
|
127
|
+
|
|
128
|
+
The MCP names these files list are `sentry` / `Sentry`, `vercel` / `Vercel`, `supabase` / `Supabase`, `inngest` and `serena`. Every tool on a listed server runs without a prompt, writes included, so list only servers you trust with that.
|
|
129
|
+
|
|
130
|
+
Placeholders: each one sits on a commented assignment line or an env default in the block. Replace it in your copy:
|
|
119
131
|
|
|
120
132
|
<!-- prettier-ignore -->
|
|
121
133
|
| Placeholder | In | Put |
|
|
122
134
|
| --- | --- | --- |
|
|
123
|
-
| `your-team-slug` | `vercel.md` (`VERCEL_SCOPE`) | Vercel team slug |
|
|
124
|
-
| `your-project-ref` | `supabase.md` (`SUPABASE_PROJECT_ID`) | project ref of the environment whose logs you want |
|
|
125
|
-
| `your-org-slug`, `your-project-slug` | `sentry.md` (`SENTRY_ORG`, `SENTRY_PROJECT`) | Sentry slugs |
|
|
126
|
-
| `de.sentry.io` (commented) | `sentry.md` (`SENTRY_HOST`) | uncomment for an EU-region org; default `sentry.io` |
|
|
127
|
-
| `your-gcp-project-id`, `your-service-name` | `cloudrun.md` (`GCP_PROJECT_ID`, `GCP_SERVICE`) | GCP project id; optional service name |
|
|
128
|
-
| `^your-e2e-job-name$` | `playwright.md` (`E2E_JOB_RE`) | anchored job name of that lane only |
|
|
129
|
-
| `^your-maestro-e2e-job-name$`, `Your per-flow results step\|Your failure classification step` | `maestro.md` (`MAESTRO_JOB_RE`, `MAESTRO_STEPS`) | anchored regex matching the Maestro lanes' job names; `\|`-separated names of the steps that print results |
|
|
130
|
-
| `dev`, `bkit-ci.yml` | `github.md` `context=diff` (`BASELINE_BRANCH`, `BASELINE_WORKFLOW`) | trunk branch, CI workflow file |
|
|
131
|
-
| `apps/mobile` | `expo.md`, both blocks (`EXPO_APP_DIR`) | the EAS-linked app folder |
|
|
132
|
-
| `serena-agent==1.7.0` | `serena.md` | the Serena version you run locally |
|
|
135
|
+
| `your-team-slug` | `bkit-vercel.md` (`VERCEL_SCOPE`) | Vercel team slug |
|
|
136
|
+
| `your-project-ref` | `bkit-supabase.md` (`SUPABASE_PROJECT_ID`) | project ref of the environment whose logs you want |
|
|
137
|
+
| `your-org-slug`, `your-project-slug` | `bkit-sentry.md` (`SENTRY_ORG`, `SENTRY_PROJECT`) | Sentry slugs |
|
|
138
|
+
| `de.sentry.io` (commented) | `bkit-sentry.md` (`SENTRY_HOST`) | uncomment for an EU-region org; default `sentry.io` |
|
|
139
|
+
| `your-gcp-project-id`, `your-service-name` | `bkit-cloudrun.md` (`GCP_PROJECT_ID`, `GCP_SERVICE`) | GCP project id; optional service name |
|
|
140
|
+
| `^your-e2e-job-name$` | `bkit-playwright.md` (`E2E_JOB_RE`) | anchored job name of that lane only |
|
|
141
|
+
| `^your-maestro-e2e-job-name$`, `Your per-flow results step\|Your failure classification step` | `bkit-maestro.md` (`MAESTRO_JOB_RE`, `MAESTRO_STEPS`) | anchored regex matching the Maestro lanes' job names; `\|`-separated names of the steps that print results |
|
|
142
|
+
| `dev`, `bkit-ci.yml` | `bkit-github.md` `context=diff` (`BASELINE_BRANCH`, `BASELINE_WORKFLOW`) | trunk branch, CI workflow file |
|
|
143
|
+
| `apps/mobile` | `bkit-expo.md`, both blocks (`EXPO_APP_DIR`) | the EAS-linked app folder |
|
|
144
|
+
| `serena-agent==1.7.0` | `bkit-serena.md` | the Serena version you run locally |
|
|
133
145
|
|
|
134
146
|
Adopt:
|
|
135
147
|
|
|
136
|
-
1. Copy the file's blocks below `<!-- bkit:end -->` in `.agents/context.md`: each fetch block you want, its provision block, its `allowed-domains` and `mcp-servers` blocks
|
|
148
|
+
1. Copy the file's blocks below `<!-- bkit:end -->` in `.agents/context.md`: each fetch block you want, its provision block, and its `allowed-domains` and `mcp-servers` blocks. Several blocks of each kind merge.
|
|
137
149
|
2. Replace the placeholders. Commit non-secret selectors inline so cloud agents inherit them.
|
|
138
150
|
3. Set the secret env vars locally (app env via `.envrc`, not `.bkit/.env`) and in each cloud dashboard (`.bkit/cloud.md`).
|
|
139
|
-
4. `bkit install
|
|
151
|
+
4. Run `bkit install`. The provision recipes reach `.claude/bkit-cloud.md`'s setup script and `.codex/bkit-cloud.md`'s install script (`.cursor/environment.json` `install` and the Claude session hook run them through `bkit context provision`). The domains reach the cloud allowlist and the local fetch permissions, and the MCP names reach every host's allow rules.
|
|
140
152
|
|
|
141
|
-
-
|
|
142
|
-
-
|
|
143
|
-
-
|
|
144
|
-
-
|
|
153
|
+
- **If** credentials are missing, or the block hits an API / auth error → it self-skips with `exit 0` and `[context-fetch:<name>] skipped — …` on stderr. `/bkit-debug` narrates that as not checked, never as clean.
|
|
154
|
+
- `TRUNCATED` on stdout means the page cap or a failed later page stopped the read. Raise the block's `*_MAX_PAGES` knob.
|
|
155
|
+
- The `# Customise:` note in the runtime and EAS blocks suggests a positive control: run the block once over a window that holds a known event. Nothing back means the reader is broken, not that the source is clean.
|
|
156
|
+
- `bkit check` advisories point at these files: `context-fetch-missing`, `context-fetch-context-missing`, `context-fetch-source-not-enabled`, `context-fetch-provision-missing`, `context-fetch-unbounded`.
|
|
157
|
+
- For another backend, author a block in the same shape. The rules are in the managed block of `.agents/context.md`.
|
|
145
158
|
|
|
146
159
|
## Gate tool scripts — `package.json`
|
|
147
160
|
|
|
148
|
-
bkit seeds only the `bkit:gate:*` / `bkit:deps:*` names
|
|
161
|
+
bkit seeds only the `bkit:gate:*` / `bkit:deps:*` names, and adds each one only if it is missing. The tool scripts their defaults chain are yours, and `gate-missing-called-scripts` names any that are missing.
|
|
149
162
|
|
|
150
163
|
<!-- prettier-ignore -->
|
|
151
164
|
| Gate (default) | Chains | Needs |
|
|
152
165
|
| --- | --- | --- |
|
|
153
166
|
| `bkit:gate:format` | `pnpm lint-staged` | lint-staged devDep + `.lintstagedrc.json` + prettier |
|
|
154
|
-
| `bkit:gate:min` | `format:check`, `lint:prose`, `slop:delta` | the scripts below + any test reading a min-push file |
|
|
155
|
-
| `bkit:gate:static` | `typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta` | the scripts below |
|
|
167
|
+
| `bkit:gate:min` | `format:check`, `bkit:lint:prose`, `bkit:slop:delta` | the scripts below + any test reading a min-push file |
|
|
168
|
+
| `bkit:gate:static` | `typecheck`, `lint`, `format:check`, `bkit:lint:prose`, `bkit:slop:delta` | the scripts below |
|
|
156
169
|
| `bkit:gate:static-unit` | `bkit:gate:static` + `test` | a `test` script |
|
|
157
170
|
| `bkit:gate:install-static-unit-build` | `pnpm install --frozen-lockfile` + `bkit:gate:static-unit` + `build` | a `build` script |
|
|
158
171
|
|
|
@@ -161,9 +174,9 @@ bkit seeds only the `bkit:gate:*` / `bkit:deps:*` names (add-if-missing). The to
|
|
|
161
174
|
"typecheck": "tsc --noEmit",
|
|
162
175
|
"lint": "oxlint -c .oxlintrc.json --type-aware --deny-warnings",
|
|
163
176
|
"format:check": "prettier --check .",
|
|
164
|
-
"lint:prose": "bkit ci prose",
|
|
177
|
+
"bkit:lint:prose": "bkit ci prose",
|
|
165
178
|
"lint:slop": "slop-scan scan .",
|
|
166
|
-
"slop:delta": "bkit ci slop",
|
|
179
|
+
"bkit:slop:delta": "bkit ci slop",
|
|
167
180
|
"prepare": "husky"
|
|
168
181
|
}
|
|
169
182
|
```
|
|
@@ -172,36 +185,109 @@ bkit seeds only the `bkit:gate:*` / `bkit:deps:*` names (add-if-missing). The to
|
|
|
172
185
|
pnpm add -D prettier@^3.5.3 slop-scan@^0.3.0 lint-staged@^17.0.0 husky@^9.1.7
|
|
173
186
|
```
|
|
174
187
|
|
|
175
|
-
- `lint` must exist
|
|
176
|
-
-
|
|
177
|
-
-
|
|
178
|
-
-
|
|
179
|
-
-
|
|
180
|
-
- `bkit:
|
|
188
|
+
- `lint` must exist. Without it, `pnpm lint` falls through to any `lint` binary on `PATH`, and the gate goes green through the wrong program.
|
|
189
|
+
- The value above runs the Oxlint test rules (§ Oxlint) and fails on any hit. It needs `oxlint` and `oxlint-tsgolint`, and fails loudly without them.
|
|
190
|
+
- **If** you have your own linter → chain both: `<your linter> && oxlint -c .oxlintrc.json --type-aware --deny-warnings`.
|
|
191
|
+
- **If** there is no `tsconfig.json` → use `"typecheck": "echo \"[bkit] typecheck: no tsconfig.json — skipping\" >&2"`.
|
|
192
|
+
- `bkit:slop:delta` runs `bkit ci slop` (the bkit devDep is on `PATH` through the package script). CI passes the base sha as its one bare argument.
|
|
193
|
+
- `bkit:lint:prose` runs `bkit ci prose`: Vale over every `*.md` outside `node_modules/`. Narrow it with the repeatable `--glob=<pattern>` (`*`, `**`, `?`, relative to the repo root), for example `bkit ci prose --glob='docs/*.md' --glob='.agents/*.md'`.
|
|
194
|
+
- **If** the stack is not Node → point each gate at your own commands, and keep the gate names.
|
|
195
|
+
- `bkit:test:file` runs one test file and writes a JUnit report to `$BKIT_TEST_REPORT`. bkit appends the file's repo-relative path. `/bkit-build` reads the report for test-first. It is not seeded, and `test-file-script-missing` fires until it is declared.
|
|
196
|
+
- Vitest: `"bkit:test:file": "vitest run --reporter=default --reporter=junit --outputFile.junit=\"$BKIT_TEST_REPORT\""`.
|
|
197
|
+
- Call the runner directly, not through a caching task runner.
|
|
198
|
+
- `bkit:lint:file` lints one test file with the static gate's rules, and exits 0 when clean. bkit appends the path. `bkit tests red` runs it on each planned test file before running the file, and records a `lint` gap for the file's tests while it fails. It is not seeded, and `lint-file-script-missing` fires once `bkit:test:file` is declared without it.
|
|
199
|
+
- ESLint: `"bkit:lint:file": "eslint --max-warnings=0"`.
|
|
200
|
+
- Ruff: `"bkit:lint:file": "ruff check"`.
|
|
201
|
+
- `bkit:gate:changed` checks only the files an agent step changed: the tests that import them, the tests that name their paths, and static checks on them; exit 0 when clean. `bkit tests changed` appends the repo-relative paths and never calls it with none. It is not seeded, and `gate-changed-script-missing` fires until it is declared; undeclared, agents run the whole `bkit:gate:static` / `bkit:gate:static-unit` instead.
|
|
202
|
+
- Vitest + ESLint: a script running `vitest related --run "$@" && eslint --max-warnings=0 --no-error-on-unmatched-pattern "$@"`, plus a text search of the test files for each path.
|
|
203
|
+
|
|
204
|
+
## Local test sleep prevention
|
|
205
|
+
|
|
206
|
+
Copy `.bkit/templates/scripts/ci/bkit-test-awake.mjs` and its adjacent test into `scripts/ci/`. Install its command-launching dependency with `pnpm add -D cross-spawn@7.0.6`; it handles Windows package-command shims and argument escaping. Prefix each local test script, including individual-file runners, with `node scripts/ci/bkit-test-awake.mjs`. Wrap a complete command chain with `--shell` and one double-quoted command string. Leave CI calling the same scripts.
|
|
207
|
+
|
|
208
|
+
```json
|
|
209
|
+
{
|
|
210
|
+
"bkit:test:unit": "node scripts/ci/bkit-test-awake.mjs vitest run",
|
|
211
|
+
"bkit:test:file": "node scripts/ci/bkit-test-awake.mjs vitest run",
|
|
212
|
+
"bkit:gate:static-unit": "node scripts/ci/bkit-test-awake.mjs --shell \"pnpm bkit:gate:static && pnpm bkit:test:unit\""
|
|
213
|
+
}
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Keep each script's existing runner flags and report settings when adding the prefix. Run the wrapper's tests with `node --test scripts/ci/bkit-test-awake.test.mjs`. For a direct runner invocation, use `node scripts/ci/bkit-test-awake.mjs pnpm exec vitest run path/to/example.test.ts`.
|
|
217
|
+
|
|
218
|
+
On macOS, the wrapper holds `caffeinate -is -w` against its own process and releases it when the command exits. It forwards cancellation to the command and retains the caller's process group so external hard timeouts still reach the tests. Linux and Windows do not require `caffeinate`. Test timeouts are unchanged. Keep the lid open; `docs/testing.md` § Local test sleep prevention describes the limits.
|
|
219
|
+
|
|
220
|
+
`bkit tests` already protects the commands it launches using the packaged wrapper. Adopt this template for direct scripts and hooks. Existing consumer-owned scripts are not rewritten on upgrade.
|
|
181
221
|
|
|
182
222
|
## CI workflow — `bkit-ci.yml`
|
|
183
223
|
|
|
184
|
-
|
|
224
|
+
The parallel lanes `bkit-tests-static` (typecheck, lint, prettier, Vale, slop, actionlint, `bkit check`, pinned checksums) and `bkit-tests-unit` are joined by the `bkit-tests-check` capstone. The file also carries the commented full CI scaffold reference for the other tiers. Reference: https://docs.github.com/en/actions.
|
|
225
|
+
|
|
226
|
+
Workflows care about it:
|
|
227
|
+
|
|
228
|
+
- `/bkit-ship` waits on its runs, and merges only when the `bkit.testing.ciCapstone` job (default `bkit-tests-check`) is present and green at the head.
|
|
229
|
+
- `bkit setup protect-main` makes that job the required check.
|
|
230
|
+
- `bkit-cloud.yml` triggers on a workflow named `bkit-ci`.
|
|
231
|
+
- `bkit install` reads your copy for advisories (`bkit-stub-*`, `ci-yml-missing-actionlint`, `ci-yml-capstone-contract-drift`).
|
|
185
232
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
-
|
|
233
|
+
Setup:
|
|
234
|
+
|
|
235
|
+
- Install: nothing beyond the gate tool scripts above, a `test` script, and `packageManager` in `package.json`. `pnpm/action-setup` reads it, so do not add `with: version:`.
|
|
236
|
+
- Adapt: `{{DEFAULT_BRANCH}}`, `{{NODE_VERSION}}`.
|
|
237
|
+
- **If** the repo is not Node → replace the Node / pnpm setup, install and check steps with your stack's.
|
|
238
|
+
- Capstone: `bkit-tests-check` `needs:` every lane, and runs on `!cancelled()`, never `always()`.
|
|
239
|
+
- Each lane you adopt from the reference goes into its `needs:` and its assert. Otherwise that lane's failure cannot red the merge.
|
|
240
|
+
- Its assert is `scripts/ci/bkit-check-capstone.mjs`. Copy it and `bkit-check-capstone.test.mjs` from `.bkit/templates/scripts/ci/` with the workflow. The script is required: when the file is missing, the step reds with a copy-the-script message, and it never skips.
|
|
241
|
+
- The script reds on a lane that did not succeed, a lane that ran when the plan said skip, a lane that succeeded with 0 tests or a non-numeric count, and a plan that does not parse.
|
|
242
|
+
- It reads each lane's executed-test count once the lane writes one. The `Run Unit Tests` step comment shows the vitest form. `EMPTY_COUNT: warn` makes an unreported count a warning, and a count of 0 a failure.
|
|
243
|
+
- Each lane you adopt goes into `LANES` and its `<LANE>_RESULT` / `<LANE>_RAN` variables.
|
|
244
|
+
- **If** you rename the job → set `bkit.testing.ciCapstone`.
|
|
189
245
|
- Adopt a scaffold lane only when its tier exists (`docs/testing.md`). Each `# bkit-stub:<id> —` header raises an install advisory until you enable or delete that stub.
|
|
190
|
-
- Keep the `name: bkit-ci` line, or rename `workflows: [bkit-ci]` in `bkit-cloud.yml` and set `bkit.testing.ciWorkflow` to the new file name.
|
|
191
|
-
- Keep `fetch-depth: 0` on the static lane
|
|
246
|
+
- Keep the `name: bkit-ci` line, or rename `workflows: [bkit-ci]` in `bkit-cloud.yml` and `bkit-health.yml` and set `bkit.testing.ciWorkflow` to the new file name.
|
|
247
|
+
- Keep `fetch-depth: 0` on the static lane, because `bkit:slop:delta` checks the PR base out as a worktree.
|
|
248
|
+
- **If** CI script copies are named without the `bkit-` prefix (`check-capstone.mjs`, `accepted-advisories.json`, …) → the `bkit check` advisory `ci-scripts-old-names` lists each rename.
|
|
249
|
+
- Rename a file and its paths in `.github/workflows/*.yml`, `.husky/pre-push` and `scripts/ci/` in one commit, because the `Check Dependency Audit` step is guarded by `hashFiles` and skips silently when only the file moved.
|
|
250
|
+
|
|
251
|
+
## Health check — `bkit-health.yml`
|
|
252
|
+
|
|
253
|
+
It probes production after every finished `bkit-ci` run on the default branch, green or red, because `bkit-tests-deploy` promotes before the E2E and `@live` lanes run, so a red run can still have put a release live. The `bkit-health-promoted` job asks the host which commit production serves. The `bkit-health` job probes the health URL only when that commit is the run's own, and shows as skipped otherwise. It is not a required check. It fits a deploy that `bkit-ci` promotes. When the host deploys on its own after merge, trigger on `deployment_status` instead (`docs/deployments.md` § Smoke trigger plumbing).
|
|
254
|
+
|
|
255
|
+
- Install: the secrets `VERCEL_TOKEN` and `VERCEL_TEAM_ID`, the same ones the CI scaffold's Vercel lanes read.
|
|
256
|
+
- **If** you use another host → replace `Did This Run Promote?` with a call to its API that prints the commit production serves.
|
|
257
|
+
- Adapt: `{{DEFAULT_BRANCH}}`, `{{PRODUCTION_URL}}`, and `HEALTH_PATH` (default `/api/health`).
|
|
258
|
+
- The promote check fails when the host's answer cannot be read, because a skipped probe would look green.
|
|
259
|
+
- The probe retries for up to 240 seconds, because a release the host reports as live can still be warming up.
|
|
260
|
+
- The probe checks only for a 200. Check the body your endpoint returns too, so an error page that answers 200 fails.
|
|
261
|
+
- More probes (a curl script over key routes, a small tagged browser suite) go in as further steps of the `bkit-health` job. A step that runs a repo script needs `actions/checkout` with `ref: ${{ github.event.workflow_run.head_sha }}` first.
|
|
262
|
+
- One health workflow per repo: keep any other post-deploy probe as a step here, not as a second workflow.
|
|
192
263
|
|
|
193
264
|
## Cloud-agent workflow — `bkit-cloud.yml`
|
|
194
265
|
|
|
195
|
-
|
|
266
|
+
A post-CI router that runs bkit workflows:
|
|
267
|
+
|
|
268
|
+
- CI pass on `feat/**` → `/bkit-ship`, fail → `/bkit-debug`.
|
|
269
|
+
- Failed `dev` CI → `/bkit-debug {FID}`.
|
|
270
|
+
- `workflow_dispatch` runs any phase.
|
|
271
|
+
|
|
272
|
+
A `context` job resolves the phase and argument once. Then two runner jobs follow, each skipped without its secret: `claude` (`claude-code-action`, https://github.com/anthropics/claude-code-action) and `opencode` (`opencode run`, https://opencode.ai/docs/github/). `bkit install --auto=claude|opencode` points at this file. The full recipe is in `.bkit/cloud.md` § Post-CI auto-routing.
|
|
196
273
|
|
|
197
274
|
- Install: `bkit install --auto=claude` (points at the `.claude/hooks/bkit-cloud-bootstrap.sh` template) or `--auto=opencode` (needs `--opencode=<provider>` first). Both need `--tracker=github`.
|
|
198
|
-
- Secrets
|
|
275
|
+
- Secrets for `claude`: `ANTHROPIC_API_KEY`, or keyless with the `ANTHROPIC_FEDERATION_RULE_ID` and `ANTHROPIC_ORGANIZATION_ID` repo variables, plus the Claude GitHub App (`/install-github-app`).
|
|
276
|
+
- Secrets for `opencode`: `OPENCODE_PROVIDER_KEY`.
|
|
277
|
+
- Repo Actions permissions: read and write, with PR creation allowed.
|
|
199
278
|
- Adapt: `{{CLOUD_RUNNER}}` in all three jobs.
|
|
200
|
-
- Traps:
|
|
279
|
+
- Traps:
|
|
280
|
+
- The file runs bkit by command name, so a changed invocation reaches you only as a changed template path on `bkit upgrade`. Diff it on every upgrade.
|
|
281
|
+
- The OpenCode install version is a plain argument. The `# renovate:` comment above it lets the example `renovate.json5` bump it.
|
|
282
|
+
- Keep the file out of the updater's `ignorePaths` so action pins refresh.
|
|
201
283
|
|
|
202
284
|
## Git hooks — Husky
|
|
203
285
|
|
|
204
|
-
`pre-commit` runs `bkit:gate:format
|
|
286
|
+
`pre-commit` runs `bkit:gate:format`. `pre-push` runs `bkit check` first, so a drifted install fails in seconds. Then it runs `bkit:gate:static-unit-integration` when package.json declares it, else `bkit:gate:static-unit` (`bkit:gate:static` on revert branches / commits; `bkit:gate:min` on a min push). It also runs the CI-suppressing-token guards, the dependency audit (§ Dependency audit) and the `tmp/` prune (§ tmp/ prune). Each hook ends by starting the disk prune (§ Disk prune).
|
|
287
|
+
|
|
288
|
+
Pre-push re-runs itself once with all its output copied to `tmp/pre-push.log`, which is rewritten on each push. It prints that path first and last, with the exit code. `--no-verify` and a checkout without husky (a linked worktree) write no log.
|
|
289
|
+
|
|
290
|
+
Workflows care because they commit and push without `--no-verify`, so a failing hook stops a workflow. The throwaway `.worktrees/_land-{FID}` checkout runs its selected gate explicitly before pushing, with hooks disabled (§ One landing routine in `.bkit/workflows.md`). Reference: https://typicode.github.io/husky/.
|
|
205
291
|
|
|
206
292
|
```bash
|
|
207
293
|
pnpm add -D husky@^9.1.7 # plus "prepare": "husky" (§ Gate tool scripts)
|
|
@@ -210,13 +296,35 @@ chmod +x .husky/pre-commit .husky/pre-push
|
|
|
210
296
|
|
|
211
297
|
- `.gitignore`: `.husky/_` (bkit's `.gitignore` block already lists it).
|
|
212
298
|
- Adapt: repo-only checks go below the bkit lines in each hook. What a gate runs belongs in the `bkit:gate:*` script, not the hook.
|
|
213
|
-
- Min push:
|
|
214
|
-
-
|
|
215
|
-
-
|
|
216
|
-
-
|
|
217
|
-
-
|
|
218
|
-
-
|
|
219
|
-
-
|
|
299
|
+
- Min push:
|
|
300
|
+
- **If** every file changed since each pushed commit left `origin/dev` (else `origin/main`) is one bkit writes or one `bkit.testing.minPushPaths` adds → `bkit:gate:min` replaces the full gate, and `MIN_PUSH=1`.
|
|
301
|
+
- The hook passes each remote-old and pushed-new commit as `bkit ci min-push --update=<old>:<new>`. A fast-forward bookkeeping increment also qualifies when a successful local full-gate receipt covers an ancestor of the old commit and every change since that checked commit is allowed.
|
|
302
|
+
- `bkit ci push-gate --gate=<script>` runs the selected consumer script. A successful deepest full push gate records its clean, unchanged commit and script definitions in the repository's Git metadata. A failed or interrupted full check prevents reuse of earlier evidence until a later full check succeeds. Minimum and revert gates create no full-gate evidence. Receipts are local; a new clone starts without them.
|
|
303
|
+
- What bkit writes = ship's `--scope=pr` allow-list (`.bkit/workflows.md` § `/bkit-ship` — 14 steps) plus `docs/plans/**`.
|
|
304
|
+
- The setting takes `package.json` globs: `*` matches one folder and `**` any depth. The default is `[]`, which leaves what bkit writes alone, because the setting only adds to it.
|
|
305
|
+
- `bkit ci min-push` decides from files, never from `[skip ci]`, because that is a typed label and GitHub reads the last commit only.
|
|
306
|
+
- Empty trigger commits need checked-ancestor evidence. Missing evidence, unreadable ranges, rewritten history, or any outgoing ref carrying new code keeps the full gate. A new branch can still qualify from its complete bookkeeping-only branch diff.
|
|
307
|
+
- Min-push paths: list only files that no code, build or test reads.
|
|
308
|
+
- Never list `docs/**`, because a doc can be test input.
|
|
309
|
+
- **If** a test reads a ledger → put that test into `bkit:gate:min`.
|
|
310
|
+
- `[skip ci]` guards:
|
|
311
|
+
- On a feature branch, the push is blocked only while a PR is open, because workflows push `[skip ci]` code heads mid-run.
|
|
312
|
+
- With a PR open, `bkit ci bookkeeping-push --from=<remote head>` lets the push through when every file changed since the head the remote holds is on ship's `--scope=pr` allow-list. Such a push adds nothing that CI has not tested at that head.
|
|
313
|
+
- A rewritten head or a code file still blocks.
|
|
314
|
+
- On `dev` / `main`, the skip-CI check uses the complete branch diff, independently of local gate receipts. Code cannot skip CI merely because its local gate passed.
|
|
315
|
+
- Slop base:
|
|
316
|
+
- **If** the push is to `dev` **and** `scripts/ci/lanes/bkit-resolve-push-base.mjs` is copied → the hook runs it with `--local --branch=dev --head=<pushed sha>`, and exports `SLOP_BASE_REF` as CI's push base. That base is the head of the last green CI push run on `dev`, else `origin/dev`. The hook prints the base and its source.
|
|
317
|
+
- Pre-push and CI slop then share a base, so a finding that an earlier red push landed fails locally too.
|
|
318
|
+
- **If** the run lookup fails (`gh` missing, logged out) → the hook prints a loud `WARNING`, uses the base `origin/dev`, and the push goes on.
|
|
319
|
+
- **If** the branch is another branch, or there is no copy → `bkit ci slop` uses its merge-base default.
|
|
320
|
+
- A repo-owned pre-push check that diffs against CI's base (migration immutability) reads `SLOP_BASE_REF` when it is set.
|
|
321
|
+
- **If** the repo has slow extras (Docker, database, build) → wrap them in `if [ "$MIN_PUSH" != "1" ]; then … fi`.
|
|
322
|
+
- Traps:
|
|
323
|
+
- Hooks run on every workflow commit. Keep pre-commit to seconds, and keep pre-push to deterministic checks that reach no deployed service.
|
|
324
|
+
- Integration runs at pre-push once `bkit:gate:static-unit-integration` is declared. A local database in Docker is fine. E2E and `@live` belong in CI.
|
|
325
|
+
- Run each check once:
|
|
326
|
+
- Put nothing in `bkit:gate:format` that the push gate runs again (`gate-commit-repeats-push` advisory).
|
|
327
|
+
- `pnpm test` (the unit tier) must match no `*.integration.test.*` file. A unit config with no integration exclude runs those tests in the unit gate and again in the integration gate.
|
|
220
328
|
|
|
221
329
|
## Prettier — `.prettierignore` first
|
|
222
330
|
|
|
@@ -224,7 +332,7 @@ chmod +x .husky/pre-commit .husky/pre-push
|
|
|
224
332
|
pnpm add -D prettier@^3.5.3
|
|
225
333
|
```
|
|
226
334
|
|
|
227
|
-
1. Copy `.prettierignore` before the first `prettier --write`. bkit writes `.claude/`, `.cursor/`, `.opencode/`, `.mcp.json`, `.bkit/.env.example
|
|
335
|
+
1. Copy `.prettierignore` before the first `prettier --write`. bkit writes `.claude/`, `.cursor/`, `.opencode/`, `.mcp.json`, `.bkit/.env.example` and `docs/roadmap.md` in its own layout, so prettier reformatting them fights the next `bkit install` (`bkit check` drift).
|
|
228
336
|
2. Add `format:check` (§ Gate tool scripts). Reference: https://prettier.io/docs/install.
|
|
229
337
|
|
|
230
338
|
- Keep the `.bkit/templates/` line.
|
|
@@ -232,34 +340,39 @@ pnpm add -D prettier@^3.5.3
|
|
|
232
340
|
|
|
233
341
|
## lint-staged — `.lintstagedrc.json`
|
|
234
342
|
|
|
235
|
-
|
|
343
|
+
It runs prettier over staged files. `bkit:gate:format` (the pre-commit hook) calls it. Reference: https://github.com/lint-staged/lint-staged.
|
|
236
344
|
|
|
237
345
|
```bash
|
|
238
346
|
pnpm add -D lint-staged@^17.0.0 prettier@^3.5.3
|
|
239
347
|
```
|
|
240
348
|
|
|
241
|
-
- Staged `docs/plans/**/*.md`
|
|
242
|
-
-
|
|
243
|
-
-
|
|
349
|
+
- Staged `docs/plans/**/*.md` and `docs/audits/**/*.md` (design, plan, audit docs) run `scripts/prettier/bkit-insert-ignore.mjs` before prettier, so committed tables carry `<!-- prettier-ignore -->` and `| --- |` separators.
|
|
350
|
+
- This needs § Prettier tables copied. Without it, commits that touch those files fail.
|
|
351
|
+
- Globs must not overlap, because lint-staged runs entries concurrently, so two entries that write one file race. The second entry negates the first.
|
|
352
|
+
- Adapt: add per-glob commands (eslint `--fix`, etc.), and keep them seconds-fast.
|
|
244
353
|
|
|
245
|
-
## Vale — prose lint, with
|
|
354
|
+
## Vale — prose lint, with Bkit styles
|
|
246
355
|
|
|
247
|
-
`lint:prose` (`bkit ci prose`, in `bkit:gate:static`) runs Vale with the `write-good` package and bkit's
|
|
356
|
+
`bkit:lint:prose` (`bkit ci prose`, in `bkit:gate:static`) runs Vale with the `write-good` package and bkit's Bkit styles (`Filler`, `Hedging`, `LLMSlop`, `Verbose`) on `.agents/**`. Workflows reach Vale only through the gate. Reference: https://vale.sh/docs/install.
|
|
248
357
|
|
|
249
358
|
```bash
|
|
250
359
|
brew install vale
|
|
251
360
|
vale sync
|
|
252
361
|
```
|
|
253
362
|
|
|
254
|
-
- Copy `.vale.ini` and all four `.vale/styles/
|
|
255
|
-
- `.gitignore`: `.vale/styles/write-good
|
|
256
|
-
- CI: the `bkit-ci.yml` template installs a pinned Vale and runs `vale sync`.
|
|
257
|
-
-
|
|
258
|
-
-
|
|
363
|
+
- Copy `.vale.ini` and all four `.vale/styles/Bkit/*.yml`.
|
|
364
|
+
- `.gitignore`: `.vale/styles/write-good`. `vale sync` downloads it, and the Bkit styles stay tracked.
|
|
365
|
+
- CI: the `bkit-ci.yml` template installs a pinned Vale and runs `vale sync`.
|
|
366
|
+
- Cursor: the `Dockerfile` template installs it.
|
|
367
|
+
- Adapt: add `[glob]` scope blocks for your own docs. Turn rules off per path, not globally.
|
|
368
|
+
- Traps:
|
|
369
|
+
- **If** Vale is not on `PATH` → `bkit:lint:prose` fails, so a push from a machine without Vale stops at pre-push. Install Vale there.
|
|
370
|
+
- A missing `write-good` is copied from the main worktree, else `vale sync` runs. When both fail, `bkit:lint:prose` fails.
|
|
371
|
+
- Keep the `.bkit/templates/**` block, which turns rules off for the copies.
|
|
259
372
|
|
|
260
373
|
## slop-scan — `slop-scan.config.json`
|
|
261
374
|
|
|
262
|
-
`lint:slop` reports
|
|
375
|
+
`lint:slop` reports. `bkit:slop:delta` (`bkit ci slop`, in `bkit:gate:static`) fails on net-new findings against the base. The base is `--base` / the bare argument, else `$SLOP_BASE_REF`, else the merge-base with `origin/dev` (else `origin/main`). CI passes its planner base, and pre-push on a `dev` push exports the same base as `SLOP_BASE_REF` (§ Git hooks), so both compare against the last green CI push run. On failure it logs each net-new / worsened finding (`path:line`, rule, message; line shifts dropped) and emits them as `findings`. Reference: https://github.com/benvinegar/slop-scan.
|
|
263
376
|
|
|
264
377
|
```bash
|
|
265
378
|
pnpm add -D slop-scan@^0.3.0
|
|
@@ -267,13 +380,16 @@ mkdir -p scripts/slop
|
|
|
267
380
|
cp .bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs scripts/slop/
|
|
268
381
|
```
|
|
269
382
|
|
|
270
|
-
- The plugin is a template
|
|
271
|
-
-
|
|
272
|
-
-
|
|
383
|
+
- The plugin is a template. Copy `scripts/slop/bkit-slop-type-suppression.mjs`, and point the config's `plugins` entry at it (`boundary/type-suppression`, `boundary/gate-suppression`).
|
|
384
|
+
- **If** you use no plugin → drop the `plugins` entry and both `boundary/*` rules.
|
|
385
|
+
- Adapt: add `ignores` for generated / vendored trees. Use per-file `overrides` with a reason, never a rule disabled repo-wide.
|
|
386
|
+
- Traps:
|
|
387
|
+
- Keep `**/.bkit/templates/**` in `ignores`, or the copied `.mjs` / `.py` files count as net-new slop on the upgrade commit.
|
|
388
|
+
- Nothing imports the copied plugin, so a reachability scanner (knip, ts-prune, vulture) reads it as dead. Register it as an entry point. Where `scripts/` is its own scanner workspace, register it there, not in the root workspace.
|
|
273
389
|
|
|
274
390
|
## Oxlint — test-file lint, `.oxlintrc.json`
|
|
275
391
|
|
|
276
|
-
|
|
392
|
+
It fails `lint` on a test that cannot fail. Oxlint (a fast linter) runs five rules on test files only, with all other checks off. It fits JS / TS repos with Vitest or Jest. Reference: https://oxc.rs/docs/guide/usage/linter.html.
|
|
277
393
|
|
|
278
394
|
```bash
|
|
279
395
|
pnpm add -D oxlint@^1.87.0 oxlint-tsgolint@^7.0.2004
|
|
@@ -286,109 +402,159 @@ Set `lint` to the value in § Gate tool scripts.
|
|
|
286
402
|
| Rule | Fails on |
|
|
287
403
|
| --- | --- |
|
|
288
404
|
| `vitest/expect-expect` | A test with no assertion. |
|
|
289
|
-
| `vitest/no-conditional-in-test` | `if`, `?:`, `&&`, `??` or
|
|
405
|
+
| `vitest/no-conditional-in-test` | `if`, `?:`, `&&`, `??` or `\|\|` inside a test: the branch under test may never run. |
|
|
290
406
|
| `vitest/no-conditional-expect` | An `expect` inside a branch or `catch`: it may never run. |
|
|
291
407
|
| `vitest/valid-expect` (`maxArgs: 2`) | `expect(x)` with no matcher; more than a value and a message. |
|
|
292
408
|
| `typescript/no-floating-promises` | A promise nobody awaits: the test ends before its assertion runs. |
|
|
293
409
|
|
|
294
|
-
- Scope: `**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}
|
|
295
|
-
- `ignorePatterns` skips `.bkit/templates/` and `scripts/ci/**/*.test.mjs
|
|
296
|
-
- Keep `--type-aware
|
|
297
|
-
-
|
|
298
|
-
-
|
|
299
|
-
-
|
|
300
|
-
-
|
|
301
|
-
-
|
|
410
|
+
- Scope: `**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}`. Source files are not linted. The `vitest/` rules read Jest-style `describe` / `it` / `expect` too.
|
|
411
|
+
- `ignorePatterns` skips `.bkit/templates/` and `scripts/ci/**/*.test.mjs`, because CI script tests run on plain Node with their own `test()` helper, which the rules misread.
|
|
412
|
+
- Keep `--type-aware`. Without it, `typescript/no-floating-promises` never runs, and the gate stays green.
|
|
413
|
+
- `oxlint-tsgolint` (a peer of `oxlint`) bundles its own TypeScript engine, so there is no `typescript` dependency. The tested pair is `oxlint` 1.87.0 and `oxlint-tsgolint` 7.0.2004.
|
|
414
|
+
- With no path argument, it lints the working directory. Narrow it (`oxlint … src`).
|
|
415
|
+
- **If** tests sit outside the root `tsconfig.json` → add `--tsconfig <file>`.
|
|
416
|
+
- Adapt: the `files` glob, and `assertFunctionNames` on `expect-expect` (default `expect`) when your own helper asserts, for example `["expect", "expectHttpError"]`. Turn a rule off per file in `overrides`, never repo-wide.
|
|
417
|
+
- **If** you have an existing suite → expect many hits. Fix each one in its test:
|
|
418
|
+
- one `it` per case (`it.each` for tables)
|
|
419
|
+
- `await expect(…).rejects` in place of `try` / `catch`
|
|
420
|
+
- `await` on every promise
|
|
421
|
+
- no baseline file, no disable comment, no `.skip`
|
|
422
|
+
- ESLint is not used because typescript-eslint's type-aware rules need TypeScript `<6.1`.
|
|
423
|
+
- **If** the repo is not JS → keep its own linter and its test-lint rules (for example `flake8-pytest-style`). `lint` stays yours.
|
|
302
424
|
- `bkit tips` suggests it (tip `test-lint`) when `package.json` lists `vitest` or `jest` and the repo has no Oxlint config, no `oxlint` dependency and no ESLint config naming a test plugin.
|
|
303
425
|
|
|
304
426
|
## direnv — `.envrc`
|
|
305
427
|
|
|
306
|
-
|
|
428
|
+
It loads `.bkit/.env` on `cd`, so local sessions see `BKIT_GH_TOKEN` and the tracker keys. bkit reads your `.envrc` (its `dotenv*` and `unset` lines, never executed) to fill the env blocks of `.claude/bkit-cloud.md` / `.codex/bkit-cloud.md` / `.cursor/bkit-cloud.md`. Preflight's direnv advisories key on it. Reference: https://direnv.net/docs/installation.html.
|
|
307
429
|
|
|
308
430
|
```bash
|
|
309
431
|
brew install direnv # then add the shell hook from the link
|
|
310
432
|
direnv allow
|
|
311
433
|
```
|
|
312
434
|
|
|
313
|
-
- Adapt: one `dotenv_if_exists <path>` line per extra env file
|
|
435
|
+
- Adapt: add one `dotenv_if_exists <path>` line per extra env file.
|
|
436
|
+
- `unset` the keys that must stay out of the shell. They are dropped from the cloud env blocks too.
|
|
314
437
|
|
|
315
438
|
## Launchd GUI environment — tokens for Dock-launched apps
|
|
316
439
|
|
|
317
|
-
Dock/Spotlight launches start under `launchd`, which never runs the login shell or direnv
|
|
440
|
+
Dock / Spotlight launches start under `launchd`, which never runs the login shell or direnv, so GUI apps (OpenCode desktop, Cursor) start without `BKIT_*`, and provider calls fail on authentication. The template set pairs a loader script with a machine-local env file. The LaunchAgent runs the loader at login, and again on every write to that file.
|
|
318
441
|
|
|
319
442
|
<!-- prettier-ignore -->
|
|
320
443
|
| File | Copy from | To | Commit |
|
|
321
444
|
| --- | --- | --- | --- |
|
|
322
445
|
| Loader | `.bkit/templates/scripts/launchd/bkit-launchd-env.sh` | `scripts/launchd/bkit-launchd-env.sh` | that file |
|
|
323
|
-
| LaunchAgent | `.bkit/templates/scripts/launchd/
|
|
324
|
-
| Tokens | `.bkit/templates/scripts/launchd/launchd.env.example` | `~/.config/bkit/launchd.env` | never (machine-local) |
|
|
446
|
+
| LaunchAgent | `.bkit/templates/scripts/launchd/bkit-launchd.plist` | `~/Library/LaunchAgents/ai.bkit.launchd.plist` | never (machine-local) |
|
|
447
|
+
| Tokens | `.bkit/templates/scripts/launchd/bkit-launchd.env.example` | `~/.config/bkit/launchd.env` | never (machine-local) |
|
|
325
448
|
|
|
326
449
|
```bash
|
|
327
450
|
cp .bkit/templates/scripts/launchd/bkit-launchd-env.sh scripts/launchd/
|
|
328
451
|
chmod +x scripts/launchd/bkit-launchd-env.sh
|
|
329
452
|
mkdir -p ~/.config/bkit
|
|
330
|
-
cp .bkit/templates/scripts/launchd/launchd.env.example ~/.config/bkit/launchd.env
|
|
453
|
+
cp .bkit/templates/scripts/launchd/bkit-launchd.env.example ~/.config/bkit/launchd.env
|
|
331
454
|
chmod 600 ~/.config/bkit/launchd.env # tokens stay owner-only
|
|
332
455
|
# fill in the tokens, then place the agent:
|
|
333
|
-
cp .bkit/templates/scripts/launchd/
|
|
456
|
+
cp .bkit/templates/scripts/launchd/bkit-launchd.plist ~/Library/LaunchAgents/ai.bkit.launchd.plist
|
|
334
457
|
# replace {{SCRIPT_PATH}} and {{ENV_FILE}} with absolute paths in the copied plist
|
|
335
458
|
launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist 2>/dev/null || true
|
|
336
459
|
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist
|
|
337
460
|
launchctl getenv BKIT_OPENROUTER_API_KEY # bootstrap proof
|
|
338
461
|
```
|
|
339
462
|
|
|
340
|
-
- `WatchPaths` re-runs the loader on every env-file write
|
|
341
|
-
-
|
|
342
|
-
-
|
|
343
|
-
-
|
|
344
|
-
-
|
|
345
|
-
-
|
|
346
|
-
-
|
|
347
|
-
-
|
|
348
|
-
-
|
|
463
|
+
- `WatchPaths` re-runs the loader on every env-file write, so no re-bootstrap is needed.
|
|
464
|
+
- To rotate a token, edit the value.
|
|
465
|
+
- To revoke a token, delete the line or empty the value (`KEY=""`).
|
|
466
|
+
- The loader loads `BKIT_*` keys only, and logs the others as skipped. An empty value runs `launchctl unsetenv`.
|
|
467
|
+
- Loaded key names are recorded in `.launchd-loaded-keys` next to the env file (mode 600; `BKIT_LAUNCHD_STATE` overrides the path). A recorded key that is missing from the env file is unset on the next run.
|
|
468
|
+
- One failing key is logged and skipped. The rest still load, and the loader exits 1. A failed unset stays recorded and retries on the next run.
|
|
469
|
+
- The log `~/Library/Logs/bkit-launchd.log` records key names only, never values. `BKIT_LAUNCHD_LOG` and `BKIT_LAUNCHD_ENV` override the log and env-file defaults.
|
|
470
|
+
- The loader self-skips (a log line and `exit 0`) when the env file is absent or `launchctl` is off `PATH` (Linux CI).
|
|
471
|
+
- launchd cannot exec a loader under `~/Documents`, `~/Desktop` or `~/Downloads`, because macOS TCC denies it. `/tmp/bkit-launchd.log` then reads `Operation not permitted`.
|
|
472
|
+
- **If** the repo sits under one of those → keep the adopted copy in git, but place the loader that launchd runs at `~/.config/bkit/bkit-launchd-env.sh` (or another unprotected path), and point `{{SCRIPT_PATH}}` there.
|
|
473
|
+
- Env-file rules:
|
|
474
|
+
- Blank lines and `#` comments are ignored.
|
|
475
|
+
- The `export ` prefix is optional.
|
|
476
|
+
- A key must match `[A-Za-z0-9_]`.
|
|
477
|
+
- Matching surrounding quotes are stripped from the value.
|
|
478
|
+
- `launchctl setenv` reaches apps launched after the load. A running app keeps its environment until relaunch, for set and unset alike.
|
|
479
|
+
- **Exposure:** `launchctl setenv` makes every loaded token visible to every app started in the login session, not only the app that needs it. Load only tokens you accept that for. Prefer `bkit cursor` / `bkit opencode` (per-process env) where possible.
|
|
349
480
|
- Remove: `launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist`.
|
|
350
481
|
|
|
351
482
|
## Cursor — `settings.json`, `environment.json`, `Dockerfile`
|
|
352
483
|
|
|
353
|
-
|
|
484
|
+
These are the editor defaults (`settings.json`: prettier format-on-save, extension recommendations) and the Cursor Cloud Agent image (`environment.json` → `Dockerfile` + per-snapshot `install`). Cloud agents run bkit workflows. `bkit install --auto=cursor` (needs `--tracker=linear`) points at the two cloud files. Reference: https://cursor.com/docs/cloud-agent/setup.
|
|
354
485
|
|
|
355
|
-
- `Dockerfile`: the `bkit toolchain` section installs what bkit's workflows use (git, jq, python3, pinned and sha256-checked gh and Vale, corepack-pinned pnpm). Node 24 is installed outside it from a sha256-checked nodejs.org tarball. Adapt `FROM`, the Node version and repo extras outside the toolchain section.
|
|
486
|
+
- `Dockerfile`: the `bkit toolchain` section installs what bkit's workflows use (git, jq, python3, pinned and sha256-checked gh and Vale, corepack-pinned pnpm). Node 24 is installed outside it from a sha256-checked nodejs.org tarball. Adapt `FROM`, the Node version and the repo extras outside the toolchain section.
|
|
356
487
|
- `environment.json` `install`: `pnpm install --frozen-lockfile`, then `vale sync` when `.vale.ini` exists.
|
|
357
488
|
- Secrets: Cloud Agents dashboard → Runtime Secrets (`.bkit/cloud.md`).
|
|
358
|
-
- Traps:
|
|
489
|
+
- Traps:
|
|
490
|
+
- The corepack pnpm pin must match `packageManager`.
|
|
491
|
+
- Keep the `bkit toolchain` section as shipped, so the template diff on upgrade stays readable.
|
|
359
492
|
|
|
360
493
|
## Dependabot and Renovate
|
|
361
494
|
|
|
362
|
-
|
|
495
|
+
Each one opens dependency PRs. No bkit workflow reads either. Pick one, and copy only its files. Reference: Dependabot https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference; Renovate https://docs.renovatebot.com/, self-hosted action https://github.com/renovatebot/github-action.
|
|
363
496
|
|
|
364
|
-
Dependabot
|
|
497
|
+
Dependabot: commit `.github/dependabot.yml` on the default branch, then enable alerts and security updates:
|
|
365
498
|
|
|
366
499
|
```bash
|
|
367
500
|
gh api -X PUT 'repos/{owner}/{repo}/vulnerability-alerts'
|
|
368
501
|
gh api -X PUT 'repos/{owner}/{repo}/automated-security-fixes'
|
|
369
502
|
```
|
|
370
503
|
|
|
371
|
-
Renovate (Mend)
|
|
504
|
+
Renovate (Mend): commit `.github/renovate.json5` on the default branch, then install the App at https://github.com/apps/renovate in the GitHub UI. There is no `gh` equivalent.
|
|
505
|
+
|
|
506
|
+
Renovate (self-hosted): also copy `bkit-renovate.yml`, then set its platform token. Use a fine-grained PAT for one owner, and a classic one across owners. The permissions are in `docs/deployments.md` § Dependency updaters.
|
|
372
507
|
|
|
373
508
|
```bash
|
|
374
509
|
gh secret set BKIT_GH_TOKEN
|
|
375
510
|
```
|
|
376
511
|
|
|
377
|
-
-
|
|
378
|
-
-
|
|
379
|
-
-
|
|
380
|
-
- `
|
|
381
|
-
-
|
|
382
|
-
-
|
|
383
|
-
-
|
|
512
|
+
- The examples ignore `.bkit/templates/**`, `.agents/skills/**` (bkit rewrites them), `docs/plans/**` and the `tests` / `__fixtures__` trees. Your copied workflows (`bkit-ci.yml`, `bkit-cloud.yml`) stay in scope so their pins refresh.
|
|
513
|
+
- The examples extend `config:best-practices`:
|
|
514
|
+
- Major bumps wait for a tick on the Dependency Dashboard (`dependencyDashboardApproval`).
|
|
515
|
+
- `lockFileMaintenance` runs monthly.
|
|
516
|
+
- PRs rebase only on conflict.
|
|
517
|
+
- A `# renovate: datasource=<ds> depName=<name>` comment above a pinned CLI version (Dockerfile, `bkit-cloud.md`, workflows) lets the example `customManagers` entry bump it.
|
|
518
|
+
- For checksum-paired pins (Vale, gh, jq, Node, actionlint), update the sha256 by hand in the same PR. `Check Pinned Checksums` in `bkit-ci.yml` (`bkit ci pins`) fails the PR until the Dockerfile's hashes match.
|
|
519
|
+
- `bkit-renovate.yml` pins `renovate-version` to an exact release. The same kind of `# renovate:` comment keeps it current.
|
|
520
|
+
- `enabled: false` on a Renovate package rule does not stop digest pinning. Use `ignorePaths` to keep Renovate off a file.
|
|
521
|
+
- Land the config on the default branch before the bot runs. The examples set `baseBranchPatterns: ["dev"]`.
|
|
522
|
+
- The App install, the self-hosted token, the private-package host rule and CVE handling are in `docs/deployments.md` § Dependency updaters.
|
|
523
|
+
|
|
524
|
+
## Dependency audit — known-vulnerable dependencies fail the push
|
|
525
|
+
|
|
526
|
+
A library with a published security advisory can sit in the lockfile for months, because the updater only offers a fix, and nothing fails the check when one is missing. This gate stops a known high or critical advisory on the machine, at the push, before it reaches a remote run. It is optional, and the files are yours once copied. Reference: https://docs.npmjs.com/cli/v10/commands/npm-audit.
|
|
527
|
+
|
|
528
|
+
```bash
|
|
529
|
+
mkdir -p scripts/ci
|
|
530
|
+
cp .bkit/templates/scripts/ci/bkit-check-dependency-audit.mjs \
|
|
531
|
+
.bkit/templates/scripts/ci/bkit-check-dependency-audit.test.mjs \
|
|
532
|
+
.bkit/templates/scripts/ci/bkit-accepted-advisories.json scripts/ci/
|
|
533
|
+
```
|
|
534
|
+
|
|
535
|
+
- Wiring:
|
|
536
|
+
- The `Dependency audit` block in the `.husky/pre-push` template runs it above the gates. The block is skipped while `scripts/ci/bkit-check-dependency-audit.mjs` is absent.
|
|
537
|
+
- **If** your hook lacks the block → paste it above the gates.
|
|
538
|
+
- The `Check Dependency Audit` step (`bkit-tests-static`) self-skips until the script is copied.
|
|
539
|
+
- Recommendation: adopt it, and an advisory is seen at the first push, not at the first remote run. It reads the advisory registry that the push already needs, so the network is no extra requirement.
|
|
540
|
+
- Acceptances:
|
|
541
|
+
- A row in `scripts/ci/bkit-accepted-advisories.json` needs `advisory`, `reason` and a `YYYY-MM-DD` `expires`.
|
|
542
|
+
- The expiry may not run past the severity's `blocking` days (default critical 7, high 30).
|
|
543
|
+
- A row that the audit no longer reports fails.
|
|
544
|
+
- Upgrade before accepting: `pnpm update -r <pkg>`.
|
|
545
|
+
- It fails closed: a blocking advisory, an unusable answer or an unreachable registry stops the push. It never passes on no answer.
|
|
546
|
+
- `--unreachable=warn` relaxes only the unreachable case, to one warning, and the push goes on. It is for a caller that leaves the check to CI. The shipped hook and the CI step both use the default `fail`.
|
|
547
|
+
- A registry that answered badly (401, 500, a missing endpoint) is a failure, not "unreachable".
|
|
548
|
+
- The audit runs with pnpm's fetch retries off, so a refused or unresolved registry fails in under a second instead of hanging the push. A slow, working registry is never cut off.
|
|
549
|
+
- Once it is adopted, the Trivy scan skips `pnpm-lock.yaml`, so accept pnpm advisories here only (§ Trivy).
|
|
384
550
|
|
|
385
551
|
## Trivy — vulnerability, config and secret scan
|
|
386
552
|
|
|
387
|
-
|
|
553
|
+
It fails CI on a HIGH or CRITICAL finding: a vulnerable package in any lockfile Trivy reads (npm, pnpm, yarn, pip, poetry, uv, Go, Cargo, Maven, …), a risky setting in a Dockerfile / Terraform / Kubernetes / Helm file, or a secret in a tracked file. It runs on push, on pull request and daily. Reference: https://trivy.dev/docs/latest/.
|
|
388
554
|
|
|
389
|
-
Copy `bkit-trivy.yml`, replace `{{DEFAULT_BRANCH}}`, commit.
|
|
555
|
+
Copy `bkit-trivy.yml`, replace `{{DEFAULT_BRANCH}}`, and commit. It needs no secret, token or App. It blocks merges only once the `trivy` check is required in branch protection.
|
|
390
556
|
|
|
391
|
-
Accept a finding in `.trivyignore.yaml` at the repo root
|
|
557
|
+
Accept a finding in `.trivyignore.yaml` at the repo root, which is read only when present:
|
|
392
558
|
|
|
393
559
|
```yaml
|
|
394
560
|
vulnerabilities:
|
|
@@ -403,34 +569,39 @@ misconfigurations:
|
|
|
403
569
|
expired_at: 2026-11-18
|
|
404
570
|
```
|
|
405
571
|
|
|
406
|
-
- Past `expired_at
|
|
407
|
-
- `scripts/ci/check-dependency-audit.mjs` adopted → the scan skips `pnpm-lock.yaml
|
|
408
|
-
- Keep `--include-dev-deps
|
|
409
|
-
-
|
|
410
|
-
-
|
|
411
|
-
-
|
|
572
|
+
- Past `expired_at`, the finding fails again. Keep it within the fix-time policy (`docs/deployments.md` § Dependency updaters).
|
|
573
|
+
- **If** `scripts/ci/bkit-check-dependency-audit.mjs` is adopted → the scan skips `pnpm-lock.yaml`. Accept pnpm advisories in `bkit-accepted-advisories.json` only.
|
|
574
|
+
- Keep `--include-dev-deps`. Without it, Trivy drops npm / yarn / pnpm dev dependencies, and a dev-tooling lockfile scans zero packages and passes.
|
|
575
|
+
- The pin is the image tag plus its `sha256:` digest, and Renovate bumps both.
|
|
576
|
+
- Never use `aquasecurity/trivy-action` or `setup-trivy` by tag, because those tags are known to have pointed at a credential stealer. Never use releases 0.69.4-0.69.6.
|
|
577
|
+
- The `.cursor/Dockerfile` template runs as root, which raises `DS-0002`. Add a non-root `USER` or accept it.
|
|
578
|
+
- It reads Dockerfiles, not built images.
|
|
579
|
+
- **If** an image you build has OS packages → add a step after your build that runs the same pinned image with `image <your-image-ref>`.
|
|
412
580
|
- Results print in the job log. Security-tab upload (SARIF) is free on public repos only.
|
|
413
581
|
|
|
414
582
|
## Serena — symbol lookup
|
|
415
583
|
|
|
416
|
-
|
|
584
|
+
A local language server, wired as an MCP server, which agents use. It does not rewrite `CLAUDE.md` / `.claude/settings.json`. Reference: https://github.com/oraios/serena.
|
|
417
585
|
|
|
418
586
|
```bash
|
|
419
587
|
brew install uv
|
|
420
588
|
uv tool install -p 3.13 serena-agent
|
|
421
589
|
```
|
|
422
590
|
|
|
423
|
-
PyPI name `serena-agent`, CLI `serena`. PyPI `serena` is an unrelated package.
|
|
424
|
-
|
|
425
|
-
- Set `project_name
|
|
426
|
-
-
|
|
427
|
-
-
|
|
428
|
-
-
|
|
429
|
-
-
|
|
430
|
-
-
|
|
431
|
-
-
|
|
432
|
-
-
|
|
433
|
-
-
|
|
591
|
+
The PyPI name is `serena-agent`, and the CLI is `serena`. PyPI `serena` is an unrelated package.
|
|
592
|
+
|
|
593
|
+
- Set `project_name` and `typescript_version` in `.serena/project.yml`. `typescript_version` must match `package.json`, not Serena's bundled compiler.
|
|
594
|
+
- **If** TypeScript is >= 7 → it ships no `tsserver`, so the language server fails to start (`Could not find a valid TypeScript installation`). Set `"5.9.3"`, Serena's bundled version and the last one with `tsserver`.
|
|
595
|
+
- Trust the project: add its path to `trusted_project_path_patterns` in `~/.serena/serena_config.yml`.
|
|
596
|
+
- **If** the project is untrusted → Serena ignores all of `ls_specific_settings` (`typescript_version`, indexing waits), with only a log `WARNING`. Lookups still answer on the bundled defaults.
|
|
597
|
+
- Adapt `ignored_paths` to the repo. Index the code a change touches. Skip committed build output and byte-copied payloads, because each indexed copy answers every reference twice.
|
|
598
|
+
- `.mcp.json` (Claude) calls `scripts/serena/bkit-serena-mcp.sh`, which finds the binary when a GUI app has no login-shell `PATH`.
|
|
599
|
+
- Codex: in `.codex/config.toml`, add `[mcp_servers.serena]` with `command` set to the absolute path to `serena` and `args = ["start-mcp-server", "--context", "codex", "--project-from-cwd"]`. bkit writes no `.codex/config.toml`.
|
|
600
|
+
- Cursor's `.cursor/mcp.json` cannot use that wrapper. Point `command` at `${HOME}/.local/bin/serena`, and pass `--context ide`.
|
|
601
|
+
- OpenCode: in `.opencode/opencode.json`, set `mcp.serena` to `{ "type": "local", "command": ["<absolute path to serena>", "start-mcp-server", "--context", "ide", "--project-from-cwd"] }`. `bkit upgrade` keeps custom `mcp` entries.
|
|
602
|
+
- List `serena` in the `.agents/context.md` `mcp-servers` block, so every host runs its tools without a prompt, because workflow subagents cannot answer one.
|
|
603
|
+
- bkit code-reading subagents carry `mcp__serena__*` in `tools:`.
|
|
604
|
+
- **If** Serena is not wired → Claude drops the entry, and the agent runs on text search.
|
|
434
605
|
|
|
435
606
|
`.gitignore`:
|
|
436
607
|
|
|
@@ -439,53 +610,62 @@ PyPI name `serena-agent`, CLI `serena`. PyPI `serena` is an unrelated package.
|
|
|
439
610
|
!.serena/project.yml
|
|
440
611
|
```
|
|
441
612
|
|
|
442
|
-
- Keep `read_only: true`, `added_modes: ["no-memories"]
|
|
443
|
-
-
|
|
444
|
-
- Serena
|
|
445
|
-
-
|
|
446
|
-
-
|
|
613
|
+
- Keep `read_only: true`, `added_modes: ["no-memories"]` and the full `excluded_tools` list from the example, so Serena stays lookup-only for agents.
|
|
614
|
+
- The list excludes every tool that writes files / memories / project config, runs code or commands, or opens a browser.
|
|
615
|
+
- Serena edits bypass the Edit / Write hooks.
|
|
616
|
+
- Removing an entry hands that tool to every bkit agent.
|
|
617
|
+
- `--context codex` still lists the excluded tools, but refuses each call (`not active`).
|
|
618
|
+
- Serena line numbers are 0-based. Add 1 before citing `file:line`.
|
|
619
|
+
- A small or empty answer for an exported symbol means the query did not resolve, not "nothing uses it". Corroborate it with text search.
|
|
620
|
+
- pnpm monorepo: cross-package references need `composite` + `references` in the TypeScript project graph before the language server follows them.
|
|
447
621
|
|
|
448
622
|
## Issue forms — `.github/ISSUE_TEMPLATE/`
|
|
449
623
|
|
|
450
|
-
Issues are the first input every workflow reads.
|
|
624
|
+
Issues are the first input every workflow reads. There is one form per way work starts, and each form's intro names its next command. The section names, syntax and machine-read lines are in `.bkit/trackers.md` § Issue shapes. The forms are for the GitHub tracker only, because Linear and Jira have their own templates. Reference: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms.
|
|
451
625
|
|
|
452
626
|
<!-- prettier-ignore -->
|
|
453
627
|
| Form | Use when | Next step | Asks for |
|
|
454
628
|
| --- | --- | --- | --- |
|
|
455
629
|
| `bkit-idea.yml` | How it should work is still open | `/bkit-design #N` | problem, outcome, success criteria, constraints and non-goals, decisions already made, open questions |
|
|
456
|
-
| `bkit-change.yml` | What to build and "done" are known | `/bkit-plan #N`, or `/bkit-build #N`
|
|
630
|
+
| `bkit-change.yml` | What to build and "done" are known | `/bkit-plan #N`, or `/bkit-build #N` with no plan | the plan in short: narrative, success criteria, edge cases, test matrix, tasks with `DONE WHEN` + `TEST FIRST` as task group and task blocks showing every plan task field (`CREATE` / `READ` / `UPDATE` / `DELETE`, `DEPENDS ON`, `DONE WHEN`, `TEST FIRST`, `TEST EXCEPTION`), breaking changes and names, out of scope |
|
|
457
631
|
| `bkit-bug.yml` | Something does not work | a test or CI run already fails → `/bkit-debug #N`; nothing fails yet → `/bkit-debug #N [repro]` | failing test or CI run, what happened, what should, repro steps, how often, affected area, where and when, evidence |
|
|
458
632
|
|
|
459
|
-
- Every form ends with References. The change form shows the lines workflows read: `**Parent design:**` and `**Audit reports:**` (plan), the blocked-by block (build). Other references are not fetched
|
|
460
|
-
- A change issue is the plan's source when no design or audit report exists
|
|
461
|
-
-
|
|
462
|
-
-
|
|
463
|
-
-
|
|
464
|
-
-
|
|
633
|
+
- Every form ends with References. The change form shows the lines workflows read: `**Parent design:**` and `**Audit reports:**` (plan), and the blocked-by block (build). Other references are not fetched. Write exact paths, ledger `key`s and `#N — title`.
|
|
634
|
+
- A change issue is the plan's source when no design or audit report exists. Its narrative, success criteria, edge cases, test rows and tasks carry over verbatim.
|
|
635
|
+
- `/bkit-build` with no plan first writes `{FID}-plan.md` from them (`@bkit-build-plan-convert`). Then it builds the tasks, and checks that each `TEST FIRST` test failed before its code.
|
|
636
|
+
- An existing `{FID}-plan.md` wins, and the issue text is not read.
|
|
637
|
+
- Nothing ticks the boxes.
|
|
638
|
+
- Debug commits to the branch it runs on, so start it on the branch the fix lands on.
|
|
639
|
+
- Copy the folder and commit it on the default branch, because GitHub reads forms from there only. Blank issues stay enabled.
|
|
640
|
+
- `labels:` applies `enhancement` / `bug` only when the repo has them. Missing labels are skipped, never created.
|
|
641
|
+
- Never add `bkit:*` labels, because workflows own them.
|
|
642
|
+
- **If** the repo has existing forms → copy only the `bkit-*` files you want. The names never collide.
|
|
465
643
|
|
|
466
644
|
## graphify — map
|
|
467
645
|
|
|
468
|
-
|
|
646
|
+
graphify runs on demand only. It is not an installed skill or git hook. graphify ships an MCP server (`graphify-mcp`, stdio default). That server stays unwired, because its answers come from the `graph.json` snapshot, and build / debug agents invalidate the graph faster than it rebuilds. Serena, which has no index to go stale, owns the agent surface.
|
|
647
|
+
|
|
648
|
+
Two gates keep `docs/capabilities.md` current on dev: the pre-push block below, which blocks a stale push to dev or to a branch with an open PR into dev, and a self-skipping CI step on every push. Agents read `docs/capabilities.md`. Audit templates that need the graph build it via `scripts/graphify/bkit-graphify.sh`. The tracked outputs are `docs/capabilities.md` and any copies of its packages diagram (below). The Mermaid views are `docs/graphify-out/reports/graph-packages.mmd` and `graph-modules.mmd`. Reference: https://github.com/Graphify-Labs/graphify.
|
|
469
649
|
|
|
470
650
|
```bash
|
|
471
651
|
uv tool install "$(bash scripts/graphify/bkit-graphify.sh spec)"
|
|
472
652
|
```
|
|
473
653
|
|
|
474
|
-
PyPI name `graphifyy`, CLI `graphify`. `[sql]` adds `.sql` files to corpus. One pinned release builds and judges the register: `GRAPHIFY_SPEC` in `bkit-graphify.sh` (`spec` prints it
|
|
654
|
+
The PyPI name is `graphifyy`, and the CLI is `graphify`. `[sql]` adds `.sql` files to the corpus. One pinned release builds and judges the register: `GRAPHIFY_SPEC` in `bkit-graphify.sh` (`spec` prints it, and CI installs it). Another release draws different edges, so `check`, `check-at`, `rollup`, `register` and `refresh` refuse it. Renovate bumps the pin (the shipped `customManagers` scans `scripts/graphify/bkit-graphify.sh`). Refresh the register in the same change.
|
|
475
655
|
|
|
476
656
|
`package.json` scripts:
|
|
477
657
|
|
|
478
658
|
```json
|
|
479
659
|
{
|
|
480
|
-
"graph": "bash scripts/graphify/bkit-graphify.sh build",
|
|
481
|
-
"graph:check": "bash scripts/graphify/bkit-graphify.sh check",
|
|
482
|
-
"graph:clean": "bash scripts/graphify/bkit-graphify.sh clean",
|
|
483
|
-
"graph:graphml": "bash scripts/graphify/bkit-graphify.sh graphml",
|
|
484
|
-
"graph:refresh": "bash scripts/graphify/bkit-graphify.sh refresh",
|
|
485
|
-
"graph:rollup": "bash scripts/graphify/bkit-graphify.sh rollup",
|
|
486
|
-
"graph:scoped": "bash scripts/graphify/bkit-graphify.sh scoped",
|
|
487
|
-
"graph:tree": "bash scripts/graphify/bkit-graphify.sh tree",
|
|
488
|
-
"graph:update": "bash scripts/graphify/bkit-graphify.sh update"
|
|
660
|
+
"bkit:graph": "bash scripts/graphify/bkit-graphify.sh build",
|
|
661
|
+
"bkit:graph:check": "bash scripts/graphify/bkit-graphify.sh check",
|
|
662
|
+
"bkit:graph:clean": "bash scripts/graphify/bkit-graphify.sh clean",
|
|
663
|
+
"bkit:graph:graphml": "bash scripts/graphify/bkit-graphify.sh graphml",
|
|
664
|
+
"bkit:graph:refresh": "bash scripts/graphify/bkit-graphify.sh refresh",
|
|
665
|
+
"bkit:graph:rollup": "bash scripts/graphify/bkit-graphify.sh rollup",
|
|
666
|
+
"bkit:graph:scoped": "bash scripts/graphify/bkit-graphify.sh scoped",
|
|
667
|
+
"bkit:graph:tree": "bash scripts/graphify/bkit-graphify.sh tree",
|
|
668
|
+
"bkit:graph:update": "bash scripts/graphify/bkit-graphify.sh update"
|
|
489
669
|
}
|
|
490
670
|
```
|
|
491
671
|
|
|
@@ -501,43 +681,76 @@ export GRAPHIFY_OUT=docs/graphify-out
|
|
|
501
681
|
graphify-out/
|
|
502
682
|
```
|
|
503
683
|
|
|
504
|
-
- Copy `scripts/graphify/bkit-graph-pre-push.sh
|
|
505
|
-
-
|
|
506
|
-
-
|
|
684
|
+
- Copy `scripts/graphify/bkit-graph-pre-push.sh`. The `.husky/pre-push` template runs it above the gates, so a stale register blocks in ~30s, not after the full gate. It is skipped while the script is absent, and on a min push.
|
|
685
|
+
- **If** your hook lacks the `Capability register` block → paste it from the template, above the gates.
|
|
686
|
+
- It checks wherever CI's `Check Capability Register` would fail: a push to dev, and a push of a branch that has an open PR into dev (`gh pr list --head <branch> --base dev --state open`). It runs `check-at` on the pushed commit in a throwaway checkout, and blocks the push on a mismatch. Uncommitted edits, a concurrent session's included, cannot change the answer.
|
|
687
|
+
- **If** graphify is not installed → it prints a loud "NOT checked" warning, and the push goes on. CI still checks.
|
|
688
|
+
- **If** `gh` is not installed on a branch push, or its `pr list` call fails (offline, not signed in) → it prints the same "NOT checked" warning, because whether the branch has an open PR is unknown, and the push goes on. A lookup that cannot answer is never read as "no PR".
|
|
689
|
+
- On a branch with no open PR, it prints a warn-only staleness note.
|
|
690
|
+
- It reads `PUSH_DEV_SHA`, `BRANCH` and `PUSH_BRANCH_SHA` from the bkit pre-push template's stdin loop. **If** your hook copy is older → re-copy that loop and the `Capability register` call from `.bkit/templates/.husky/pre-push`. Until you do, the script checks the checked-out branch at `HEAD`.
|
|
691
|
+
- `.github/workflows/bkit-ci.yml` ships `Check Capability Register`. It installs the `spec` release and runs the pinned `check-at HEAD`, and a stale register fails CI. It self-skips without `scripts/graphify/bkit-graphify.sh`.
|
|
692
|
+
- It runs on every push and pull request, on the checked-out commit. On a PR, that is GitHub's test merge into the base, so a branch behind its base syncs, refreshes and commits to clear a red.
|
|
693
|
+
- graphify's MCP server is opt-in. Install `graphifyy[mcp]` (`mcp` + `starlette`; the HTTP transport also needs `uvicorn`), and pass the graph path explicitly, because `graphify-mcp` defaults to `graphify-out/graph.json`, not the pinned `docs/graphify-out/graph.json`. Snapshot-dated answers suit audit / orientation, never build or debug.
|
|
507
694
|
- `.graphifyignore` merges `.gitignore`.
|
|
508
|
-
- Keep `package.json` in corpus
|
|
509
|
-
- Keep `tsconfig.json` out
|
|
510
|
-
- Always run `scripts/graphify/bkit-graphify.sh
|
|
695
|
+
- Keep `package.json` in the corpus. Excluding it drops the workspace `name` fields that graphify resolves package imports with, and the graph still looks complete.
|
|
696
|
+
- Keep `tsconfig.json` out, because graphify reads `paths` regardless.
|
|
697
|
+
- Always run `scripts/graphify/bkit-graphify.sh`, which passes `--code-only` and `--no-label` and unsets API keys. There is no persistent LLM-off setting.
|
|
511
698
|
|
|
512
699
|
<!-- prettier-ignore -->
|
|
513
700
|
| Command | Does |
|
|
514
701
|
| --- | --- |
|
|
515
|
-
| `pnpm graph` | Extract + cluster. Local. No API key. |
|
|
516
|
-
| `pnpm graph:clean` | Same, after deleting `docs/graphify-out/`. Required after any tsconfig `paths` change. `--force` does not invalidate the module-resolution cache. |
|
|
517
|
-
| `pnpm graph:update` | Re-extract changed files, then recluster. |
|
|
518
|
-
| `pnpm graph:rollup` | Package and module views, plus `docs/capabilities.md
|
|
519
|
-
| `pnpm graph:check` | Rebuild and fail if `docs/capabilities.md` is not what this tree produces. Reads uncommitted edits. Shipped as a self-skipping CI step (push
|
|
702
|
+
| `pnpm bkit:graph` | Extract + cluster. Local. No API key. |
|
|
703
|
+
| `pnpm bkit:graph:clean` | Same, after deleting `docs/graphify-out/`. Required after any tsconfig `paths` change. `--force` does not invalidate the module-resolution cache. |
|
|
704
|
+
| `pnpm bkit:graph:update` | Re-extract changed files, then recluster. |
|
|
705
|
+
| `pnpm bkit:graph:rollup` | Package and module views, plus `docs/capabilities.md` and its diagram copies. |
|
|
706
|
+
| `pnpm bkit:graph:check` | Rebuild and fail if `docs/capabilities.md` is not what this tree produces, or a diagram copy differs from it. Reads uncommitted edits. Shipped as a self-skipping CI step (every push and pull request; on a PR, GitHub's test merge into the base); enabled in bkit's own CI. |
|
|
520
707
|
| `bash scripts/graphify/bkit-graphify.sh check-at <rev>` | `check` in a throwaway checkout of `<rev>` (default HEAD); pre-push gate runs it on the commit pushed to dev. |
|
|
521
|
-
| `pnpm graph:refresh` | Rebuild register in a throwaway checkout of
|
|
522
|
-
| `pnpm graph:scoped [path]` | One subtree. Default `apps/web/src`. |
|
|
523
|
-
| `pnpm graph:graphml` | Opt-in GraphML for Gephi / yEd. |
|
|
708
|
+
| `pnpm bkit:graph:refresh` | Rebuild register in a throwaway checkout of the staged files (the index) → copy over `docs/capabilities.md` → rewrite the diagram copies. Stage the change first, so a run before its commit builds the new state. Fixes a red gate; commit result. |
|
|
709
|
+
| `pnpm bkit:graph:scoped [path]` | One subtree. Default `apps/web/src`. |
|
|
710
|
+
| `pnpm bkit:graph:graphml` | Opt-in GraphML for Gephi / yEd. |
|
|
711
|
+
|
|
712
|
+
- `docs/graphify-out/` holds the raw `graph.json`, and `docs/graphify-out/reports/` holds the derived views.
|
|
713
|
+
- Copy `.bkit/templates/docs/capabilities.md` → `docs/capabilities.md` before the first rollup, because the Overrides block must exist. `pnpm bkit:graph:rollup` rewrites it after that.
|
|
714
|
+
- To add a capability, add a rule in `bkit-graph-drift-rules.json`: lane, owner module, one literal marker. The shipped rules JSON has one example row. Replace it.
|
|
715
|
+
- The marker is a literal that only the owner should contain (a host, a header, a marker string). Never use the owner's exported function name, because every legitimate caller then reads as `bypassed`.
|
|
716
|
+
|
|
717
|
+
`MMD_MIN_WEIGHT` (default 12, set in `bkit-graphify.sh`) drops light edges from the Mermaid views (`.mmd` files and the diagrams in `docs/capabilities.md`).
|
|
524
718
|
|
|
525
|
-
-
|
|
526
|
-
-
|
|
527
|
-
- Add capability → rule in `bkit-graph-drift-rules.json`: lane, owner module, one literal marker. Shipped rules JSON = one example row; replace it.
|
|
528
|
-
- Marker = a literal only the owner should contain (a host, a header, a marker string) — never the owner's exported function name: every legitimate caller then reads as `bypassed`.
|
|
719
|
+
- **If** the repo has one module per file → edges are thinner, so lower the default in your copy.
|
|
720
|
+
- An env override changes `docs/capabilities.md` per shell, and fails `pnpm bkit:graph:check`.
|
|
529
721
|
|
|
530
|
-
|
|
722
|
+
To show the packages diagram in another doc, such as your `README.md`, copy `scripts/graphify/bkit-graph-embed.py`:
|
|
723
|
+
|
|
724
|
+
- Put one `<!-- graph:packages:start -->` and one `<!-- graph:packages:end -->` line in the doc, where the diagram goes.
|
|
725
|
+
- Add the doc's path to `GRAPH_EMBED_DOCS` in `bkit-graphify.sh`. Separate several paths with spaces.
|
|
726
|
+
- `rollup`, `register` and `refresh` rewrite the block from `docs/capabilities.md`, so commit the doc with the register.
|
|
727
|
+
- `check` fails when a copy differs from the register, so the pre-push block and CI gate the copies too.
|
|
728
|
+
- **If** a listed doc lacks exactly one marker pair → the run exits 2.
|
|
729
|
+
|
|
730
|
+
Iterate in mermaid.live, and render the internal-architecture diagram locally:
|
|
531
731
|
|
|
532
732
|
```bash
|
|
533
733
|
npx -y @mermaid-js/mermaid-cli -i docs/graphify-out/reports/graph-packages.mmd -o tmp/graph-packages.svg
|
|
534
734
|
```
|
|
535
735
|
|
|
536
|
-
- `bkit-graph-repair.py` runs between extract and cluster
|
|
537
|
-
-
|
|
538
|
-
- `bkit-graph-
|
|
539
|
-
-
|
|
540
|
-
-
|
|
736
|
+
- `bkit-graph-repair.py` runs between extract and cluster. It restores `.js` specifiers that point at `.tsx` files, and workspace subpaths through an `exports` map.
|
|
737
|
+
- A bare `graphify update` drops that injection, and `pnpm bkit:graph:update` restores it.
|
|
738
|
+
- `bkit-graph-eager.py` and `bkit-graphify-rollup.py` re-derive those imports from source, and warn with the count that graph.json lacks.
|
|
739
|
+
- Two files that import each other keep one link after clustering, so that pair never reads as missing.
|
|
740
|
+
- `bkit-graph-surface.py` is the route layer. It assumes `apps/web` / `apps/mobile` page routes, `packages/api/src/v1.ts` and the workspace scope `@scope/services/`.
|
|
741
|
+
- Replace `@scope` and the route globs, or the section stays empty.
|
|
742
|
+
- Route reachability runs only when `scripts/ci/guards/assert-routes-reachable.mjs` exists. Otherwise it is skipped.
|
|
743
|
+
- `bkit-graph-imports.py` picks `react-native` vs `default` export conditions from the importer path (`apps/mobile` vs `apps/web`). Change the prefixes if your app roots differ.
|
|
744
|
+
- Source roots are hard-coded for an `apps/` + `packages/` monorepo:
|
|
745
|
+
- `ROOTS` in `bkit-graph-drift.py` (the files the drift rules scan)
|
|
746
|
+
- `ROOTS` in `bkit-graph-eager.py` and `DEFAULT_ROOTS` in `bkit-graph-imports.py` (the files those passes walk)
|
|
747
|
+
- `by_package` / `by_module` in `bkit-graphify-rollup.py` (the diagram boxes)
|
|
748
|
+
- **If** the repo has another layout → adapt all five. Otherwise capabilities read `gap`, and the diagrams come out empty.
|
|
749
|
+
- **If** the repo has one flat source folder → `by_module` gives one node per file.
|
|
750
|
+
- **If** the repo is a single package → have `by_package` return its top-level source folders, so each package box is one part of the codebase.
|
|
751
|
+
- The packages diagram groups package boxes by their parent folder and gives each group one colour, so the keys `by_package` returns decide the groups.
|
|
752
|
+
- **If** there are no web routes, or no imports between top-level folders → the route and package diagrams stay empty. That is the answer, not a fault.
|
|
753
|
+
- The extract warning `had syntax errors and may be partially extracted` can fire on valid code. The symbols after that line are then missing from the graph, so treat that file as unmapped.
|
|
541
754
|
|
|
542
755
|
Do not run:
|
|
543
756
|
|
|
@@ -548,21 +761,33 @@ Do not run:
|
|
|
548
761
|
| `graphify install --project` | Writes a skill. `/bkit-ship` removes skills not named in `.agents/skills.md`. |
|
|
549
762
|
| `graphify hook install` | Rebuilds on every commit. bkit commits many times per workflow run. |
|
|
550
763
|
|
|
551
|
-
-
|
|
552
|
-
- Ignore rules are load-bearing
|
|
764
|
+
- A code-graph answer confirms what is present. It does not prove what is absent, and a missing edge looks like a real gap.
|
|
765
|
+
- Ignore rules are load-bearing. A noise-only pattern can drop edges the tool needs, and the output still looks plausible, so re-measure after changing `.graphifyignore`.
|
|
553
766
|
|
|
554
767
|
## Secrets sync — one source, every store
|
|
555
768
|
|
|
556
|
-
|
|
769
|
+
The local gitignored env files are the source of truth. `bkit-secrets.mjs sync` makes every store match, and `drift` proves it. It needs Node >= 20 plus the CLI of each store used (`gh`, `eas`, `gcloud`). Vercel, Supabase and Cursor go through their REST APIs.
|
|
557
770
|
|
|
558
|
-
- Copy both files. Edit `bkit-secrets.config.mjs` only
|
|
559
|
-
-
|
|
560
|
-
-
|
|
771
|
+
- Copy both files. Edit `bkit-secrets.config.mjs` only. `bkit-secrets.mjs` stays byte-identical across repos.
|
|
772
|
+
- The config has one row per secret, naming every store that holds a copy: `DATABASE_URL: ["vercel", "gcp"]`. The options per row are:
|
|
773
|
+
- `from`: the env key differs from the store name
|
|
774
|
+
- `derive`: `"${APP_URL}/path"`
|
|
775
|
+
- `manual`: copies no API reaches
|
|
776
|
+
- `"eas:secret"`: a per-store option
|
|
777
|
+
- Delete unused entries under `stores`. A store that no row names is skipped.
|
|
561
778
|
- `.gitignore`: `scripts/secrets/bkit-secrets-state.json`.
|
|
562
|
-
- `.bkit/.env` overlay
|
|
563
|
-
- Cursor store:
|
|
564
|
-
-
|
|
565
|
-
-
|
|
779
|
+
- The `.bkit/.env` overlay holds agent / bkit tooling secrets only. App and stack credentials stay in the app env files.
|
|
780
|
+
- Cursor store:
|
|
781
|
+
- The option `environment` (name) or `environmentId` picks the Cloud Agents environment (ids from `GET /v1/environments`).
|
|
782
|
+
- The token is `CURSOR_API_KEY` (or `BKIT_CURSOR_API_KEY`).
|
|
783
|
+
- Secrets are write-only. `NAME: "cursor:environment_variable"` writes a non-secret env var instead of a Runtime Secret.
|
|
784
|
+
- `build_secret` names exist only in the dashboard. They are never written or deleted.
|
|
785
|
+
- Cursor rows: list only the names the cloud workflow needs.
|
|
786
|
+
- The minimal set is `BKIT_GH_TOKEN`, plus `BKIT_LINEAR_API_KEY` on Linear setups. `VERCEL_TOKEN` / `SUPABASE_ACCESS_TOKEN` are optional, for when the workflow reaches those stores.
|
|
787
|
+
- A first sync against a populated environment deletes every live name that is not listed, so the `--dry-run` rule below the command table applies to it too.
|
|
788
|
+
- API errors surface with their code: `feature_unavailable` (the environments API is not enabled for the key), `key_not_supported` (`grok_` keys), `secret_name_ambiguous` (one name, several repo-scoped versions; pre-checked, so remove the extra versions in the dashboard).
|
|
789
|
+
- Team-scope 403s (`team_admin_required`) do not apply, because the adapter uses environment scope only.
|
|
790
|
+
- **If** you need a custom store → no upstream change is needed: `type: "custom"` + `module` loads a repo-local adapter (see below).
|
|
566
791
|
|
|
567
792
|
<!-- prettier-ignore -->
|
|
568
793
|
| Command (`node scripts/secrets/bkit-secrets.mjs …`) | Does |
|
|
@@ -573,7 +798,7 @@ Local gitignored env files = source of truth; `bkit-secrets.mjs sync` makes ever
|
|
|
573
798
|
| `check [file]` | Local only: sources, env file vs example (exit 2 on a missing required key), every copy of every secret. |
|
|
574
799
|
| `--store <name>` | Narrow `sync` / `drift` / `list` to one store. Every run covers both environments; no per-environment option. |
|
|
575
800
|
|
|
576
|
-
`sync` deletes every live name not listed for that store
|
|
801
|
+
`sync` deletes every live name that is not listed for that store, so ALWAYS run `--dry-run` before every sync. When no listed key resolves to a value, the deletes for that store are skipped.
|
|
577
802
|
|
|
578
803
|
How `drift` proves a value without printing it:
|
|
579
804
|
|
|
@@ -585,16 +810,17 @@ How `drift` proves a value without printing it:
|
|
|
585
810
|
| EAS (plaintext / sensitive) | `env:list --include-sensitive` | SHA-256 of live value vs source |
|
|
586
811
|
| GitHub Actions, Supabase, Cursor, Vercel sensitive, EAS `secret` | write-only | state-file fingerprint vs source (`not-pushed`); store's last-updated time after recorded push (`changed-elsewhere`) |
|
|
587
812
|
|
|
588
|
-
-
|
|
589
|
-
- `bkit-secrets-state.json`
|
|
590
|
-
-
|
|
591
|
-
-
|
|
813
|
+
- **If** no push is recorded → the result is `unverified`, never `ok`. The first sync records one.
|
|
814
|
+
- `bkit-secrets-state.json` holds fingerprints and times only, per machine.
|
|
815
|
+
- **If** a push came from another machine or by hand → the result is `changed-elsewhere` until the next sync here.
|
|
816
|
+
- `manual` copies are listed on every `check` / `drift`. Update them by hand on rotation.
|
|
817
|
+
- Vercel: branch-scoped preview vars are left alone. An entry shared across environments is split before a write.
|
|
592
818
|
|
|
593
|
-
|
|
819
|
+
A new store type goes in as an entry in `STORES` of the template's `bkit-secrets.mjs` (`open` → `list` / `write` / `remove`; the contract is above it), never in a copy only. A repo-local store needs no upstream change: `type: "custom"` + `module: "./stores/x.mjs"` (resolved against `scripts/secrets/`) loads a module whose default export carries `label` + `open` (optional `perEnv`, `protects`, `setOptions`). The engine validates the adapter at load, and its `open()` handle at run.
|
|
594
820
|
|
|
595
821
|
## Prettier tables — keep table diffs to the changed row
|
|
596
822
|
|
|
597
|
-
Prettier aligns markdown tables with no config toggle
|
|
823
|
+
Prettier aligns markdown tables with no config toggle, so one edited cell re-pads every row. `bkit-insert-ignore.mjs` puts `<!-- prettier-ignore -->` directly above each table head (no blank line between), strips cell padding, and normalises separators to `---`. It is idempotent. It needs Node >= 20 and no dependencies.
|
|
598
824
|
|
|
599
825
|
<!-- prettier-ignore -->
|
|
600
826
|
| Command | Does |
|
|
@@ -602,30 +828,39 @@ Prettier aligns markdown tables with no config toggle; one edited cell re-pads e
|
|
|
602
828
|
| `node scripts/prettier/bkit-insert-ignore.mjs` | Rewrite `.agents/`, `docs/`, `README.md` (or the paths given). |
|
|
603
829
|
| `node scripts/prettier/bkit-insert-ignore.mjs --check` | Write nothing; exit 1 if any file would change. Gate form. |
|
|
604
830
|
|
|
605
|
-
- Walks skip `skills/` trees (vendored), `docs/audits
|
|
606
|
-
-
|
|
607
|
-
- A pipe inside an inline-code span is escaped to `\|` only when that restores the separator's column count
|
|
608
|
-
-
|
|
831
|
+
- Walks skip `skills/` trees (vendored), and `docs/audits/` and `docs/plans/` (records, kept as written). A file named on the command line is always processed. New and edited records get it at commit, because § lint-staged names each staged file.
|
|
832
|
+
- It skips tables inside ``` / ~~~ fences, tables inside multi-line `<!-- -->` comments, and tables already wrapped. A comment opens on a line starting with `<!--`, and runs to the first line holding `-->`. A one-line comment hides nothing.
|
|
833
|
+
- A pipe inside an inline-code span is escaped to `\|` only when that restores the separator's column count. An existing `\|` stays literal.
|
|
834
|
+
- It exits 1 on damage it cannot repair, with or without `--check`:
|
|
835
|
+
- `truncated-row`: more cells than the separator, and GFM drops the overflow.
|
|
836
|
+
- `unrendered-table`: the header count != the separator count, and GFM renders raw text.
|
|
837
|
+
- A bare pipe in cell prose is indistinguishable from a delimiter. Escape it as `\|` by hand.
|
|
838
|
+
- Under `docs/audits/` and `docs/plans/`, the same damage prints as a `WARN` and exits 0, because records hold text quoted from elsewhere (issue comments, CI logs) that nobody can fix in place.
|
|
609
839
|
|
|
610
840
|
## tmp/ prune — old scratch files
|
|
611
841
|
|
|
612
|
-
Each push deletes scratch files agents left in `tmp/` untouched for a week, then the folders that leaves empty. Node >= 20
|
|
842
|
+
Each push deletes scratch files that agents left in `tmp/` untouched for a week, then the folders that leaves empty. It needs Node >= 20 and no dependencies.
|
|
613
843
|
|
|
614
844
|
```bash
|
|
615
845
|
mkdir -p scripts/cleanup
|
|
616
846
|
cp .bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs scripts/cleanup/
|
|
617
847
|
```
|
|
618
848
|
|
|
619
|
-
- Wiring:
|
|
620
|
-
-
|
|
621
|
-
-
|
|
622
|
-
-
|
|
623
|
-
-
|
|
849
|
+
- Wiring:
|
|
850
|
+
- The `tmp/ prune` block in the `.husky/pre-push` template runs it with `--days=7`, ahead of the gates. The block is skipped while `scripts/cleanup/bkit-tmp-prune.mjs` is absent.
|
|
851
|
+
- **If** your `.husky/pre-push` lacks the block → paste it above the gates.
|
|
852
|
+
- It is not a gate: a failed prune prints a warning, and the push goes on.
|
|
853
|
+
- `--days=<n>` (n >= 1, default 7).
|
|
854
|
+
- Exit codes: 0 means swept or no `tmp/`; 1 means an entry could not be removed (each one named on stderr); 2 means bad arguments.
|
|
855
|
+
- Scope: `tmp/` at the top of the checkout the cwd sits in. Each worktree prunes its own, and `tmp/` itself stays.
|
|
856
|
+
- Age is the file mtime.
|
|
857
|
+
- Symlinks are never followed. A symlinked `tmp/` is skipped. A symlink inside is removed by its own age, and its target is untouched.
|
|
858
|
+
- A folder goes only when it is empty **and** either the sweep emptied it or its own mtime is past the cutoff, so a folder that another process just made stays.
|
|
624
859
|
- Hand run: `node scripts/cleanup/bkit-tmp-prune.mjs`. Files to keep belong outside `tmp/`.
|
|
625
860
|
|
|
626
861
|
## Disk prune — cleanup steps you own
|
|
627
862
|
|
|
628
|
-
`bkit disk prune` runs only steps you list
|
|
863
|
+
`bkit disk prune` runs only the steps you list, and bkit itself deletes nothing. With no step file, nothing runs.
|
|
629
864
|
|
|
630
865
|
```bash
|
|
631
866
|
mkdir -p scripts/cleanup ~/.config/bkit
|
|
@@ -639,34 +874,72 @@ cp .bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs ~/.config/bkit/di
|
|
|
639
874
|
| `scripts/cleanup/bkit-disk-prune.mjs` | this checkout: build caches, leftover agent worktrees | checkout top, first | yes |
|
|
640
875
|
| `~/.config/bkit/disk-prune.mjs` (`$XDG_CONFIG_HOME/bkit/` when set) | shared tools: Docker, pnpm store, Xcode, Gradle, simulators | home folder | never |
|
|
641
876
|
|
|
642
|
-
- Step list, default-exported: `{ name, mode, run, skip?, paths? }`.
|
|
643
|
-
-
|
|
644
|
-
-
|
|
645
|
-
-
|
|
646
|
-
-
|
|
647
|
-
-
|
|
648
|
-
-
|
|
649
|
-
-
|
|
650
|
-
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
877
|
+
- Step list, default-exported: `{ name, mode, run, skip?, paths? }`.
|
|
878
|
+
- `min` steps are stale and cheap. `max` covers all that comes back by itself, plus every `min` step.
|
|
879
|
+
- `run` / `skip`: a shell command or a `({ cwd, log, note })` function. When `skip` exits 0 or returns a reason, the step is skipped.
|
|
880
|
+
- `paths`: what `--dry-run` sizes, which is the most the step can free.
|
|
881
|
+
- Notes: `note(text)` records something found and left for a person.
|
|
882
|
+
- Each sweep replaces its checkout's notes.
|
|
883
|
+
- `bkit tips` prints them first (from a worktree, the main checkout's too), so every workflow close surfaces them.
|
|
884
|
+
- With no sweep for 7 days, they are dropped.
|
|
885
|
+
- The example worktree step removes a `.worktrees/*` only when nothing is lost: it is clean, and every commit is on a remote or at a merged pull request's head (`gh`; squash merges). It removes it via `bkit worktrees remove`, or plain `git worktree remove` when no workflow made it.
|
|
886
|
+
- Branches stay.
|
|
887
|
+
- It keeps a locked worktree, or one committed to in 2 days, and notes the rest.
|
|
888
|
+
- Adapt: keep a step only when what it deletes comes back by itself. These are left out on purpose: named Docker volumes (local databases), runtimes and SDKs, and the whole pnpm store (`node_modules` hard-link into it).
|
|
889
|
+
- Wiring: it is the last block of each Husky template.
|
|
890
|
+
- `pre-commit` → `--mode=min --auto`.
|
|
891
|
+
- `pre-push` → `--mode=max --auto`, after every gate (workflow pushes too).
|
|
892
|
+
- **If** the block is missing → paste it at the end of yours.
|
|
893
|
+
- `--auto`: runs detached, and always exits 0.
|
|
894
|
+
- Each mode runs at most once a day: the machine file's steps once per machine, the repo file's steps once per checkout, so another repo's sweep never uses up this checkout's day.
|
|
895
|
+
- `max` runs at most hourly while free disk < `bkit.workflows.minFreeGb` (`package.json`, GB, default 40), on the same split.
|
|
896
|
+
- Log: `~/.cache/bkit/disk-prune.log` (`$XDG_CACHE_HOME/bkit/` when set).
|
|
897
|
+
- Worktrees:
|
|
898
|
+
- **If** `bkit worktrees setup` creates or resumes a worktree under `bkit.workflows.minFreeGb` → it runs the `max` steps and waits.
|
|
899
|
+
- **If** free disk is still under → it exits 12, and nothing is created. stderr lists what the `max` steps still cover.
|
|
900
|
+
- With no step file, there is no check.
|
|
901
|
+
- One sweep runs per machine at a time (`disk-prune.lock` beside the log).
|
|
902
|
+
- The sweep `--auto` starts and the worktree check wait for a running sweep to end, so their turn is never lost.
|
|
903
|
+
- A hand run stops while another sweep runs, unless it passes `--wait`.
|
|
904
|
+
- A failed step is logged, and the next one runs.
|
|
905
|
+
- In CI / cloud, nothing runs.
|
|
906
|
+
- Hand run: `pnpm bkit disk prune --mode=max --dry-run` prints each step and its `paths` size. Without `--dry-run`, it runs now. `--scope=repo` or `--scope=machine` runs only that file's steps. Exit 1 means a step failed or a step file did not load.
|
|
907
|
+
|
|
908
|
+
## Machine lock
|
|
909
|
+
|
|
910
|
+
The machine lock queues test gates across repositories and protects shared local services across worktrees. Copy the script and wire it into the commands that need the lock. An unwired repository takes no lock. The script requires Bash 3.2+ and `/usr/bin/perl`.
|
|
655
911
|
|
|
656
912
|
```bash
|
|
657
913
|
mkdir -p scripts/ci
|
|
658
|
-
cp .bkit/templates/scripts/ci/bkit-
|
|
914
|
+
cp .bkit/templates/scripts/ci/bkit-machine-lock.sh scripts/ci/
|
|
659
915
|
```
|
|
660
916
|
|
|
661
917
|
<!-- prettier-ignore -->
|
|
662
918
|
| Wire into | How | Holds the lock |
|
|
663
919
|
| --- | --- | --- |
|
|
664
|
-
| `package.json`
|
|
665
|
-
|
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
-
|
|
670
|
-
-
|
|
671
|
-
-
|
|
672
|
-
-
|
|
920
|
+
| every test-running `bkit:gate:*` script in `package.json` | `"bash scripts/ci/bkit-machine-lock.sh run --lock tests -- <gate command>"` | for the whole gate, across repositories on this machine |
|
|
921
|
+
| a gate that chains commands | `"bkit:gate:static-unit": "bash scripts/ci/bkit-machine-lock.sh run --lock tests -- sh -c 'pnpm bkit:gate:static && pnpm test'"` | for the complete chain |
|
|
922
|
+
| `package.json` scripts that start / reset / stop the stack | `"db:reset": "bash scripts/ci/bkit-machine-lock.sh run db:reset -- <reset command>"` | for the command; its exit status passes on |
|
|
923
|
+
| local runners that test against the stack | `. scripts/ci/bkit-machine-lock.sh`, then `take_local_stack_lock "<who>"` before the first stack command; non-zero → exit | until the runner exits or calls `release_local_stack_lock` |
|
|
924
|
+
|
|
925
|
+
- API (all functions are safe under `set -e`):
|
|
926
|
+
- `take_local_stack_lock "<who>" [name]` waits; every refusal returns 1.
|
|
927
|
+
- `try_local_stack_lock "<who>" [name]` returns 1 at once while busy.
|
|
928
|
+
- `release_local_stack_lock [name]` frees the lock early.
|
|
929
|
+
- `local_stack_lock_holder [name]` prints the holder, or every holder of `tests` slots.
|
|
930
|
+
- `local_stack_lock_file [name]` prints the lock file path.
|
|
931
|
+
- `run ["<who>"] [--lock <name>] -- <command> [args…]` passes the command's exit status on. Exit 2 means usage, 73 means the lock could not be taken (including lock order), and 75 means the wait gave up. Omit `<who>` to use `LOCAL_STACK_LOCK_WHO`, else `npm_lifecycle_event`, else `run`.
|
|
932
|
+
- Named locks use `~/.cache/bkit/machine-lock/<name>.lock`, with no repository prefix. The holder line identifies the caller's checkout. A child inherits `LOCAL_STACK_LOCK_OWNER_<key>` and reuses only that named lock while its owner is alive.
|
|
933
|
+
- The `tests` lock has `BKIT_TEST_SLOTS` slots (whole number >= 1, default 1; an invalid value falls back to 1 with one note). Slot 1 uses `tests.lock`; later slots use `tests.<k>.lock`. The waiting note names every holder.
|
|
934
|
+
- Taking `tests` exports `BKIT_TEST_WORKERS` = max(1, floor(cores / slots) - 1). Pass it to your runner, for example `vitest run --maxWorkers="$BKIT_TEST_WORKERS"` inside the wrapped command. Cores come from `getconf _NPROCESSORS_ONLN`, else `nproc`, else `sysctl -n hw.ncpu`, else 1.
|
|
935
|
+
- Take locks in this order: `tests`, other named locks, then the unnamed stack lock. A request for `tests` while this shell or a live parent holds another lock is refused. A request for a named lock while holding the stack lock is also refused.
|
|
936
|
+
- The unnamed stack lock keeps `~/.cache/bkit/local-stack-lock/<stack>.lock` and `LOCAL_STACK_LOCK_OWNER` / `LOCAL_STACK_LOCK_PID`. A consumer's adopted copy keeps working and excludes this copy on the same stack.
|
|
937
|
+
- `<stack>` is `BKIT_LOCAL_STACK`, else the main checkout's folder name, so every worktree finds the same lock.
|
|
938
|
+
- A throwaway stack with its own names and ports sets its own `BKIT_LOCAL_STACK`.
|
|
939
|
+
- Outside a git checkout with no `BKIT_LOCAL_STACK`, the functions refuse with exit 1; `run` exits 73.
|
|
940
|
+
- Lock paths use `$XDG_CACHE_HOME/bkit/` when set. A small Perl process holds the file lock and exits within a second of its caller, however the caller ends.
|
|
941
|
+
- Wait: `LOCAL_STACK_LOCK_WAIT_S` when set, else 60 seconds without a TTY, else 3600 seconds. Waiting notes name the budget and holders once a minute; the give-up line names the holder again.
|
|
942
|
+
- A named release records held seconds by checkout in `<name>.last`, with one tab-separated line per checkout. A waiting note and give-up line name the current holder's `last run took <N>m<N>s`, or `no earlier run`.
|
|
943
|
+
- `CI=true` / `CI=1` makes every lock a no-op.
|
|
944
|
+
- `bkit tests run` and `bkit tests changed` pass `--lock-wait-s` and their run name to a wrapped gate; a tests-lock give-up of this run maps 75 → 81 with `lockHolder`, and a tests-lock refusal maps 73 → 4. A lock wait writes no `test-run` status row. Light runs (`red`, `green`, `bkit:test:file`) take no tests lock. Nested wraps reuse their live parent's tests lock. See `docs/testing.md` § Tests lock for host wait budgets.
|
|
945
|
+
- Fix hints and docs name the locked scripts, never the raw command (`supabase db reset`, `docker compose down`), because the raw command skips the lock. See `.agents/rules.md` § Shared local stack.
|