@cbartens/bkit 0.0.0-stage → 5.0.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 +421 -0
- package/.bkit/core/.agents/context.md +95 -0
- package/.bkit/core/.agents/docs.md +62 -0
- package/.bkit/core/.agents/rules.md +147 -0
- package/.bkit/core/.agents/skills.md +43 -0
- package/.bkit/core/.bkit/LICENSE.md +151 -0
- package/.bkit/core/.bkit/README.md +421 -0
- package/.bkit/core/.bkit/cloud.md +502 -0
- package/.bkit/core/.bkit/comparison.md +318 -0
- package/.bkit/core/.bkit/install.md +496 -0
- package/.bkit/core/.bkit/jsonl.md +497 -0
- package/.bkit/core/.bkit/prompts.md +474 -0
- package/.bkit/core/.bkit/providers.md +598 -0
- package/.bkit/core/.bkit/templates.md +471 -0
- package/.bkit/core/.bkit/trackers.md +95 -0
- package/.bkit/core/.bkit/workflows.md +1546 -0
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +82 -0
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +93 -0
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +74 -0
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +115 -0
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +135 -0
- package/.bkit/core/.cursor/hooks/bkit-gateguard.cjs +111 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +169 -0
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +63 -0
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +225 -0
- package/.bkit/core/AGENTS.md +77 -0
- package/.bkit/core/LICENSE.md +149 -0
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +272 -0
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +223 -0
- package/.bkit/core/docs/templates/bkit-audit-agents.md +230 -0
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +227 -0
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +266 -0
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +230 -0
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +270 -0
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +254 -0
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +221 -0
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +241 -0
- package/.bkit/core/docs/templates/bkit-audit-config.md +230 -0
- package/.bkit/core/docs/templates/bkit-audit-cost.md +218 -0
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +221 -0
- package/.bkit/core/docs/templates/bkit-audit-database.md +229 -0
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +251 -0
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +283 -0
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +268 -0
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +280 -0
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +253 -0
- package/.bkit/core/docs/templates/bkit-audit-failures.md +259 -0
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +237 -0
- package/.bkit/core/docs/templates/bkit-audit-gates.md +250 -0
- package/.bkit/core/docs/templates/bkit-audit-issues.md +273 -0
- package/.bkit/core/docs/templates/bkit-audit-llm.md +239 -0
- package/.bkit/core/docs/templates/bkit-audit-logs.md +266 -0
- package/.bkit/core/docs/templates/bkit-audit-models.md +210 -0
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +211 -0
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +216 -0
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +220 -0
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +222 -0
- package/.bkit/core/docs/templates/bkit-audit-repo.md +224 -0
- package/.bkit/core/docs/templates/bkit-audit-security.md +274 -0
- package/.bkit/core/docs/templates/bkit-audit-slop.md +200 -0
- package/.bkit/core/docs/templates/bkit-audit-testing.md +270 -0
- package/.bkit/core/docs/templates/bkit-audit-usability.md +237 -0
- package/.bkit/core/docs/templates/bkit-plan.md +476 -0
- package/.bkit/core/engine/checks/after/auth.ts +247 -0
- package/.bkit/core/engine/checks/after/ci-yml.ts +739 -0
- package/.bkit/core/engine/checks/after/github.ts +424 -0
- package/.bkit/core/engine/checks/after/index.ts +556 -0
- package/.bkit/core/engine/checks/after/managed.ts +217 -0
- package/.bkit/core/engine/checks/after/tools.ts +427 -0
- package/.bkit/core/engine/checks/after/vercel.ts +101 -0
- package/.bkit/core/engine/checks/before/context-fetch.ts +429 -0
- package/.bkit/core/engine/checks/before/env.ts +201 -0
- package/.bkit/core/engine/checks/before/files.ts +202 -0
- package/.bkit/core/engine/checks/before/index.ts +206 -0
- package/.bkit/core/engine/checks/before/mcp.ts +127 -0
- package/.bkit/core/engine/checks/before/repo.ts +77 -0
- package/.bkit/core/engine/checks/before/version.ts +67 -0
- package/.bkit/core/engine/checks/status-holes.ts +479 -0
- package/.bkit/core/engine/cli.ts +871 -0
- package/.bkit/core/engine/commands/analysis.ts +550 -0
- package/.bkit/core/engine/commands/ci/ci.ts +483 -0
- package/.bkit/core/engine/commands/comply.ts +415 -0
- package/.bkit/core/engine/commands/harvest.ts +459 -0
- package/.bkit/core/engine/commands/install/check.ts +70 -0
- package/.bkit/core/engine/commands/install/doctor.ts +247 -0
- package/.bkit/core/engine/commands/install/install.ts +528 -0
- package/.bkit/core/engine/commands/install/uninstall.ts +972 -0
- package/.bkit/core/engine/commands/install/upgrade.ts +1026 -0
- package/.bkit/core/engine/commands/launch.ts +139 -0
- package/.bkit/core/engine/commands/lib.ts +494 -0
- package/.bkit/core/engine/commands/registry.ts +53 -0
- package/.bkit/core/engine/commands/setup/setup.ts +184 -0
- package/.bkit/core/engine/commands/telemetry.ts +32 -0
- package/.bkit/core/engine/commands/workflow/branches.ts +1514 -0
- package/.bkit/core/engine/commands/workflow/context.ts +961 -0
- package/.bkit/core/engine/commands/workflow/counters.ts +268 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +243 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +675 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +575 -0
- package/.bkit/core/engine/commands/workflow/locks.ts +478 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +1087 -0
- package/.bkit/core/engine/commands/workflow/repo.ts +220 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +576 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +2140 -0
- package/.bkit/core/engine/commands/workflow/runtime.ts +300 -0
- package/.bkit/core/engine/commands/workflow/skills.ts +118 -0
- package/.bkit/core/engine/commands/workflow/status.ts +455 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +1300 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +161 -0
- package/.bkit/core/engine/commands/workflow/workflows.ts +1573 -0
- package/.bkit/core/engine/commands/workflow/workstreams.ts +164 -0
- package/.bkit/core/engine/commands/workflow/worktrees.ts +534 -0
- package/.bkit/core/engine/install/cloud-env.ts +925 -0
- package/.bkit/core/engine/install/managed-block.ts +212 -0
- package/.bkit/core/engine/install/manifest.ts +448 -0
- package/.bkit/core/engine/install/modules/claude.ts +362 -0
- package/.bkit/core/engine/install/modules/cloud.ts +174 -0
- package/.bkit/core/engine/install/modules/codex.ts +219 -0
- package/.bkit/core/engine/install/modules/core.ts +600 -0
- package/.bkit/core/engine/install/modules/cursor.ts +231 -0
- package/.bkit/core/engine/install/modules/index.ts +242 -0
- package/.bkit/core/engine/install/modules/opencode.ts +573 -0
- package/.bkit/core/engine/install/placeholders.ts +108 -0
- package/.bkit/core/engine/install/template-copies.ts +119 -0
- package/.bkit/core/engine/install/version-file.ts +284 -0
- package/.bkit/core/engine/install/write.ts +467 -0
- package/.bkit/core/engine/ledgers/clamp-log.ts +32 -0
- package/.bkit/core/engine/ledgers/status.ts +213 -0
- package/.bkit/core/engine/ledgers/telemetry.ts +1143 -0
- package/.bkit/core/engine/render/hosts.ts +372 -0
- package/.bkit/core/engine/render/models.ts +323 -0
- package/.bkit/core/engine/render/parts.ts +38 -0
- package/.bkit/core/engine/render/trackers.ts +170 -0
- package/.bkit/core/engine/shared/egress.ts +345 -0
- package/.bkit/core/engine/shared/json.ts +16 -0
- package/.bkit/core/engine/shared/log-prefix.ts +9 -0
- package/.bkit/core/engine/shared/package-json.ts +29 -0
- package/.bkit/core/engine/shared/package-manager.ts +38 -0
- package/.bkit/core/engine/shared/package-roots.ts +163 -0
- package/.bkit/core/engine/shared/protected-paths.ts +164 -0
- package/.bkit/core/engine/shared/settings.ts +72 -0
- package/.bkit/core/engine/shared/timeouts.ts +20 -0
- package/.bkit/core/engine/tools/wording.ts +748 -0
- package/.bkit/core/hooks/gateguard-edit-payload.js +18 -0
- package/.bkit/core/hooks/gateguard-engine.js +193 -0
- package/.bkit/core/hooks/guardrails-shell.js +154 -0
- package/.bkit/core/hooks/guardrails-tiers.js +68 -0
- package/.bkit/core/hooks/preflight-linear.sh +73 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +66 -0
- package/.bkit/core/prompts/bkit-build-challenge-1.md +79 -0
- package/.bkit/core/prompts/bkit-build-challenge-2.md +81 -0
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +68 -0
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +70 -0
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +73 -0
- package/.bkit/core/prompts/bkit-build-install-skills.md +67 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +75 -0
- package/.bkit/core/prompts/bkit-build-plan-execute.md +72 -0
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +73 -0
- package/.bkit/core/prompts/bkit-build-plan-verify.md +88 -0
- package/.bkit/core/prompts/bkit-build-summary.md +93 -0
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +90 -0
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +151 -0
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +78 -0
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +73 -0
- package/.bkit/core/prompts/bkit-debug-summary.md +95 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +72 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +72 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +75 -0
- package/.bkit/core/prompts/bkit-design-generate.md +110 -0
- package/.bkit/core/prompts/bkit-design-organise.md +85 -0
- package/.bkit/core/prompts/bkit-design-review-1.md +121 -0
- package/.bkit/core/prompts/bkit-design-review-2.md +111 -0
- package/.bkit/core/prompts/bkit-design-spike.md +97 -0
- package/.bkit/core/prompts/bkit-design-summary.md +106 -0
- package/.bkit/core/prompts/bkit-design-update.md +66 -0
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +66 -0
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +87 -0
- package/.bkit/core/prompts/bkit-plan-generate.md +74 -0
- package/.bkit/core/prompts/bkit-plan-review-1.md +90 -0
- package/.bkit/core/prompts/bkit-plan-review-2.md +80 -0
- package/.bkit/core/prompts/bkit-plan-review-3.md +92 -0
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +84 -0
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +84 -0
- package/.bkit/core/prompts/bkit-plan-summary.md +106 -0
- package/.bkit/core/prompts/bkit-plan-update.md +68 -0
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +90 -0
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +94 -0
- package/.bkit/core/prompts/bkit-ship-summary.md +77 -0
- package/.bkit/core/prompts/bkit-ship-update-docs.md +71 -0
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +91 -0
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +75 -0
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +76 -0
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +61 -0
- package/.bkit/core/prompts/bkit-utility-update-failures.md +76 -0
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +75 -0
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +82 -0
- package/.bkit/core/workflows/bkit-auto.md +121 -0
- package/.bkit/core/workflows/bkit-build.md +802 -0
- package/.bkit/core/workflows/bkit-debug.md +642 -0
- package/.bkit/core/workflows/bkit-design.md +495 -0
- package/.bkit/core/workflows/bkit-plan.md +510 -0
- package/.bkit/core/workflows/bkit-ship.md +650 -0
- package/.bkit/shared/.bkit/.env.example +108 -0
- package/.bkit/shared/.claude/bkit-cloud.md +117 -0
- package/.bkit/shared/.claude/settings.json +88 -0
- package/.bkit/shared/.codex/hooks.json +26 -0
- package/.bkit/shared/.cursor/bkit-cloud.md +84 -0
- package/.bkit/shared/.cursor/hooks.json +26 -0
- package/.bkit/shared/.cursor/mcp.json +15 -0
- package/.bkit/shared/.cursor/rules/bkit-rules.mdc +12 -0
- package/.bkit/shared/.gitattributes +37 -0
- package/.bkit/shared/.mcp.json +16 -0
- package/.bkit/shared/.opencode/opencode.json +62 -0
- package/.bkit/shared/CLAUDE.md +11 -0
- package/.bkit/shared/LICENSE.md +22 -0
- package/.bkit/shared/docs/architecture.md +19 -0
- package/.bkit/shared/docs/data-schema.md +19 -0
- package/.bkit/shared/docs/deployments.md +438 -0
- package/.bkit/shared/docs/design.md +39 -0
- package/.bkit/shared/docs/noise.md +19 -0
- package/.bkit/shared/docs/observability.md +25 -0
- package/.bkit/shared/docs/security.md +42 -0
- package/.bkit/shared/docs/setup.md +30 -0
- package/.bkit/shared/docs/technology.md +18 -0
- package/.bkit/shared/docs/testing.md +413 -0
- package/.bkit/shared/gitignore +92 -0
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +192 -0
- package/.bkit/templates/.cursor/Dockerfile +68 -0
- package/.bkit/templates/.cursor/environment.json +6 -0
- package/.bkit/templates/.cursor/settings.json +11 -0
- package/.bkit/templates/.envrc +7 -0
- package/.bkit/templates/.github/dependabot.yml +52 -0
- package/.bkit/templates/.github/renovate.json5 +239 -0
- package/.bkit/templates/.github/workflows/bkit-ci.yml +1082 -0
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +566 -0
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +107 -0
- package/.bkit/templates/.graphifyignore +108 -0
- package/.bkit/templates/.husky/pre-commit +16 -0
- package/.bkit/templates/.husky/pre-push +91 -0
- package/.bkit/templates/.lintstagedrc.json +3 -0
- package/.bkit/templates/.prettierignore +41 -0
- package/.bkit/templates/.serena/project.yml +243 -0
- package/.bkit/templates/.vale/styles/House/Filler.yml +11 -0
- package/.bkit/templates/.vale/styles/House/Hedging.yml +12 -0
- package/.bkit/templates/.vale/styles/House/LLMSlop.yml +13 -0
- package/.bkit/templates/.vale/styles/House/Verbose.yml +12 -0
- package/.bkit/templates/.vale.ini +67 -0
- package/.bkit/templates/LICENSE.md +22 -0
- package/.bkit/templates/context/bkit-cloudrun.md +84 -0
- package/.bkit/templates/context/bkit-expo.md +186 -0
- package/.bkit/templates/context/bkit-github.md +79 -0
- package/.bkit/templates/context/bkit-inngest.md +45 -0
- package/.bkit/templates/context/bkit-maestro.md +76 -0
- package/.bkit/templates/context/bkit-playwright.md +62 -0
- package/.bkit/templates/context/bkit-resend.md +36 -0
- package/.bkit/templates/context/bkit-sentry.md +65 -0
- package/.bkit/templates/context/bkit-serena.md +33 -0
- package/.bkit/templates/context/bkit-stripe.md +36 -0
- package/.bkit/templates/context/bkit-supabase.md +59 -0
- package/.bkit/templates/context/bkit-tavily.md +49 -0
- package/.bkit/templates/context/bkit-vercel.md +64 -0
- package/.bkit/templates/docs/capabilities.md +72 -0
- package/.bkit/templates/scripts/ci/accepted-divergences.json +21 -0
- package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +152 -0
- package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +130 -0
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +98 -0
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +86 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-drift-rules.json +23 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +208 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-eager-rules.json +35 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +236 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-external-rules.json +17 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +290 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +19 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +120 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +232 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +36 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +927 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +351 -0
- package/.bkit/templates/scripts/launchd/ai.bkit.launchd.plist +26 -0
- package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +53 -0
- package/.bkit/templates/scripts/launchd/launchd.env.example +13 -0
- package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +275 -0
- package/.bkit/templates/scripts/secrets/bkit-secrets.config.mjs +66 -0
- package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +785 -0
- package/.bkit/templates/scripts/serena/bkit-serena-mcp.sh +30 -0
- package/.bkit/templates/scripts/serena/bkit-serena.mcp.json +9 -0
- package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +286 -0
- package/.bkit/templates/slop-scan.config.json +120 -0
- package/CHANGELOG.md +1486 -0
- package/LICENSE.md +161 -0
- package/README.md +185 -2
- package/dist/checks/after/auth.js +232 -0
- package/dist/checks/after/ci-yml.js +718 -0
- package/dist/checks/after/github.js +400 -0
- package/dist/checks/after/index.js +447 -0
- package/dist/checks/after/managed.js +187 -0
- package/dist/checks/after/tools.js +351 -0
- package/dist/checks/after/vercel.js +102 -0
- package/dist/checks/before/context-fetch.js +426 -0
- package/dist/checks/before/env.js +173 -0
- package/dist/checks/before/files.js +185 -0
- package/dist/checks/before/index.js +162 -0
- package/dist/checks/before/mcp.js +111 -0
- package/dist/checks/before/repo.js +71 -0
- package/dist/checks/before/version.js +60 -0
- package/dist/checks/status-holes.js +393 -0
- package/dist/cli.js +692 -0
- package/dist/commands/analysis.js +325 -0
- package/dist/commands/ci/ci.js +438 -0
- package/dist/commands/comply.js +310 -0
- package/dist/commands/harvest.js +354 -0
- package/dist/commands/install/check.js +61 -0
- package/dist/commands/install/doctor.js +207 -0
- package/dist/commands/install/install.js +461 -0
- package/dist/commands/install/uninstall.js +815 -0
- package/dist/commands/install/upgrade.js +771 -0
- package/dist/commands/launch.js +118 -0
- package/dist/commands/lib.js +362 -0
- package/dist/commands/registry.js +50 -0
- package/dist/commands/setup/setup.js +158 -0
- package/dist/commands/telemetry.js +29 -0
- package/dist/commands/workflow/branches.js +1265 -0
- package/dist/commands/workflow/context.js +846 -0
- package/dist/commands/workflow/counters.js +227 -0
- package/dist/commands/workflow/fids.js +224 -0
- package/dist/commands/workflow/issues.js +585 -0
- package/dist/commands/workflow/ledgers.js +472 -0
- package/dist/commands/workflow/locks.js +364 -0
- package/dist/commands/workflow/prs.js +904 -0
- package/dist/commands/workflow/repo.js +199 -0
- package/dist/commands/workflow/roadmap.js +495 -0
- package/dist/commands/workflow/runs.js +1717 -0
- package/dist/commands/workflow/runtime.js +257 -0
- package/dist/commands/workflow/skills.js +110 -0
- package/dist/commands/workflow/status.js +392 -0
- package/dist/commands/workflow/steps.js +1093 -0
- package/dist/commands/workflow/tests.js +144 -0
- package/dist/commands/workflow/workflows.js +1342 -0
- package/dist/commands/workflow/workstreams.js +141 -0
- package/dist/commands/workflow/worktrees.js +473 -0
- package/dist/install/cloud-env.js +819 -0
- package/dist/install/managed-block.js +182 -0
- package/dist/install/manifest.js +376 -0
- package/dist/install/modules/claude.js +288 -0
- package/dist/install/modules/cloud.js +152 -0
- package/dist/install/modules/codex.js +193 -0
- package/dist/install/modules/core.js +511 -0
- package/dist/install/modules/cursor.js +186 -0
- package/dist/install/modules/index.js +152 -0
- package/dist/install/modules/opencode.js +504 -0
- package/dist/install/placeholders.js +87 -0
- package/dist/install/template-copies.js +106 -0
- package/dist/install/version-file.js +204 -0
- package/dist/install/write.js +342 -0
- package/dist/ledgers/clamp-log.js +27 -0
- package/dist/ledgers/status.js +156 -0
- package/dist/ledgers/telemetry.js +637 -0
- package/dist/render/hosts.js +339 -0
- package/dist/render/models.js +288 -0
- package/dist/render/parts.js +33 -0
- package/dist/render/trackers.js +135 -0
- package/dist/shared/egress.js +299 -0
- package/dist/shared/json.js +16 -0
- package/dist/shared/log-prefix.js +7 -0
- package/dist/shared/package-json.js +22 -0
- package/dist/shared/package-manager.js +32 -0
- package/dist/shared/package-roots.js +145 -0
- package/dist/shared/protected-paths.js +153 -0
- package/dist/shared/settings.js +44 -0
- package/dist/shared/timeouts.js +19 -0
- package/dist/tools/wording.js +680 -0
- package/package.json +101 -4
|
@@ -0,0 +1,496 @@
|
|
|
1
|
+
# Install, upgrade, and operate bkit
|
|
2
|
+
|
|
3
|
+
{{BKIT_MANAGED_MARKER}}
|
|
4
|
+
|
|
5
|
+
First-time install and auth, upgrade, CI and Vercel auth, install lifecycle, uninstall and recovery. Ships in the package at `node_modules/@cbartens/bkit/.bkit/core/.bkit/install.md` and is mirrored into the consumer repo at `.bkit/install.md`. Ongoing ops and triggering workflows: `.bkit/README.md`.
|
|
6
|
+
|
|
7
|
+
> [!IMPORTANT]
|
|
8
|
+
> **`BKIT_GH_TOKEN_INSTALL` is required everywhere bkit installs.** Without it, `pnpm install` fails with an opaque 401 (or the silent-ignore-then-fall-back-to-npmjs footgun → 404). Set it in **all four** places before running `pnpm add -D @cbartens/bkit`:
|
|
9
|
+
>
|
|
10
|
+
> 1. **Local shell** — pick one of two flows (see § Local env setup for details):
|
|
11
|
+
> - **(A) Quick:** `export BKIT_GH_TOKEN_INSTALL=<classic PAT>` in `~/.zshrc` or `~/.bashrc`. Works immediately, single-step. Same token leaks into every shell.
|
|
12
|
+
> - **(B) direnv + `.bkit/.env` (recommended for daily use):** `brew install direnv` once per machine, then `.bkit/.env` (gitignored, scaffolded by `bkit install`) auto-loads on `cd`. Tokens scoped to the repo, not your whole shell. Note: `.bkit/.env` only exists _after_ `bkit install` runs, so for the first install you need either (A) or a one-off `export` in the current shell.
|
|
13
|
+
> 2. **`.npmrc` at repo root** — registry mapping only; token goes in pnpm user-level config via `pnpm config set` — see § Consumer CI auth below
|
|
14
|
+
> 3. **GitHub Actions repo secret** — `gh secret set BKIT_GH_TOKEN_INSTALL --body=<token>` per consumer repo
|
|
15
|
+
> 4. **Vercel env vars** (if applicable) — `vercel env add BKIT_GH_TOKEN_INSTALL preview/production`
|
|
16
|
+
>
|
|
17
|
+
> **Use a classic PAT, not fine-grained.** GitHub Packages npm registry currently rejects fine-grained PATs with HTTP 403 even when `Packages: read` is granted (verified 2026-05). Until GitHub fixes this, classic with `read:packages` scope is the only working option.
|
|
18
|
+
|
|
19
|
+
## Quick install / upgrade — paste into your AI
|
|
20
|
+
|
|
21
|
+
Two paste blocks below — **install** (first time) and **upgrade** (already on bkit). Both end the same way: apply advisories, reconcile templates, verify with `bkit check`.
|
|
22
|
+
|
|
23
|
+
### Install — first time
|
|
24
|
+
|
|
25
|
+
After creating a classic GitHub PAT with `read:packages` scope ([Tokens (classic)](https://github.com/settings/tokens)) and saving it as `BKIT_GH_TOKEN_INSTALL=<token>` in a local env file in this repo (e.g. `.env.local`, `apps/web/.env.preview`), copy the block below into Claude Code / Cursor / any coding agent. Replace `<ENV-FILE-PATH>` with your env file's path.
|
|
26
|
+
|
|
27
|
+
````text
|
|
28
|
+
Install the latest `@cbartens/bkit` in this repo and finish setup.
|
|
29
|
+
1. I've created a classic GitHub PAT with `read:packages` scope and saved it as `BKIT_GH_TOKEN_INSTALL=<token>` in `<ENV-FILE-PATH>` (e.g. `.env.local` or `apps/web/.env.preview`). Confirmed.
|
|
30
|
+
2. Access `BKIT_GH_TOKEN_INSTALL` without leaking it into context: `source` is a shell builtin (not file I/O) — permission gates on `Read`/`grep`/`cat` do NOT see it. Pattern (same Bash invocation — shell state does NOT persist between tool calls):
|
|
31
|
+
```bash
|
|
32
|
+
set -a; source <ENV-FILE-PATH> 2>/dev/null; set +a; <command that needs the token>
|
|
33
|
+
```
|
|
34
|
+
Verify without leaking: `echo "len=${#BKIT_GH_TOKEN_INSTALL}"`.
|
|
35
|
+
3. Ensure root `.npmrc` has registry mapping only (token NOT stored here — pnpm >=10.34.3 401s on project-`.npmrc` `${BKIT_GH_TOKEN_INSTALL}` substitution):
|
|
36
|
+
```
|
|
37
|
+
@cbartens:registry=https://npm.pkg.github.com
|
|
38
|
+
```
|
|
39
|
+
Then auth + install + seed hosts in one Bash call (`bkit install` requires named modules — core implicit; if `bkit` not on PATH use `pnpm bkit`):
|
|
40
|
+
```bash
|
|
41
|
+
set -a; source <ENV-FILE-PATH>; set +a; \
|
|
42
|
+
pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL" && \
|
|
43
|
+
pnpm add -D @cbartens/bkit@latest && \
|
|
44
|
+
bkit install --claude --cursor
|
|
45
|
+
```
|
|
46
|
+
Writes `.agents/`, `.claude/`, `.cursor/` and the `bkit:gate:*` `package.json` scripts, and copies the templates (CI workflow, hooks, tool configs) into `.bkit/templates/` without applying them. `.bkit/templates.md` lists each template plus the tool scripts and devDeps the gates chain.
|
|
47
|
+
4. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why.
|
|
48
|
+
5. Read `.bkit/templates.md`, then compare each template in `.bkit/templates/` (CI workflows, git hooks, lint and Vale configs, Cursor config, dependency updaters, etc.) with this repo. bkit never applies templates, so adoption is your job: adopt unless adoption would break existing functionality. For any template not adopted, state which and why.
|
|
49
|
+
6. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons).
|
|
50
|
+
````
|
|
51
|
+
|
|
52
|
+
### Upgrade — already installed
|
|
53
|
+
|
|
54
|
+
Same paste block ships in `.bkit/README.md` (mirrored into consumer repos on install — keep both in sync when editing). Copy when the repo already has `@cbartens/bkit`. Prefer `bkit upgrade --latest` (bumps the package **and** resyncs managed files) — do **not** only `pnpm add`. Replace `<ENV-FILE-PATH>` if the token is not already loaded in the shell (direnv / `.bkit/.env`).
|
|
55
|
+
|
|
56
|
+
````text
|
|
57
|
+
Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resync.
|
|
58
|
+
1. Ensure `BKIT_GH_TOKEN_INSTALL` is available for the GitHub Packages bump. If not already in the environment, load without leaking (`source` is a shell builtin — not file I/O). `source` and the command MUST be the SAME Bash invocation:
|
|
59
|
+
```bash
|
|
60
|
+
set -a; source <ENV-FILE-PATH> 2>/dev/null; set +a; \
|
|
61
|
+
pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL" && \
|
|
62
|
+
bkit upgrade --latest
|
|
63
|
+
```
|
|
64
|
+
If token already exported (direnv / shell profile), skip `source`:
|
|
65
|
+
```bash
|
|
66
|
+
bkit upgrade --latest
|
|
67
|
+
```
|
|
68
|
+
If `bkit` not on PATH: `pnpm bkit upgrade --latest`. Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
|
|
69
|
+
2. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why.
|
|
70
|
+
3. Read the template changes `bkit upgrade` printed (or `git diff .bkit/templates`), then `.bkit/templates.md`. bkit never applies templates, so adoption is your job: adopt each change unless it would break existing functionality. For any change not adopted, state which and why.
|
|
71
|
+
4. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons).
|
|
72
|
+
````
|
|
73
|
+
|
|
74
|
+
## Install
|
|
75
|
+
|
|
76
|
+
bkit is distributed via **GitHub Packages npm registry** (`https://npm.pkg.github.com`). Add to a consumer repo:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
pnpm add -D @cbartens/bkit@^4.0.0
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### Adding a new consumer — checklist
|
|
83
|
+
|
|
84
|
+
Run these in order on a brand-new consumer repo. Each step links to its detail section below.
|
|
85
|
+
|
|
86
|
+
<!-- prettier-ignore -->
|
|
87
|
+
| # | Step | Detail |
|
|
88
|
+
| --- | --- | --- |
|
|
89
|
+
| 1 | Create a classic PAT with `read:packages` (fine-grained PATs are rejected by GitHub Packages) | [§ Consumer CI auth](#consumer-ci-auth) step 1 |
|
|
90
|
+
| 2 | Add `BKIT_GH_TOKEN_INSTALL` repo secret | [§ Consumer CI auth](#consumer-ci-auth) step 2 |
|
|
91
|
+
| 3 | Commit `.npmrc` at repo root (registry mapping only; token goes in pnpm user-level config) | [§ Consumer CI auth](#consumer-ci-auth) step 3 |
|
|
92
|
+
| 4 | Export `BKIT_GH_TOKEN_INSTALL` for the `pnpm add` step (one-off — `export BKIT_GH_TOKEN_INSTALL=<classic PAT>` in this shell only), then run `pnpm add -D @cbartens/bkit` | [§ Install](#install) (this section) |
|
|
93
|
+
| 5 | Run `bkit install --claude --cursor` to seed both hosts (writes `.bkit/.env.example`; `.envrc` is a template in `.bkit/templates/`) | [§ Install](#install) (this section) |
|
|
94
|
+
| 5a | Set up direnv + `.bkit/.env` so every subsequent shell auto-loads `BKIT_GH_TOKEN_INSTALL`, `BKIT_GH_TOKEN`, `BKIT_LINEAR_API_KEY` | [§ Local env setup](#local-env-setup) |
|
|
95
|
+
| 6 | If deploying to Vercel: add `BKIT_GH_TOKEN_INSTALL` to Vercel env vars | [§ Consumer Vercel auth](#consumer-vercel-auth) |
|
|
96
|
+
| 7 | Push to a feature branch and verify CI runs green | — |
|
|
97
|
+
|
|
98
|
+
The `.github/workflows/bkit-ci.yml` template's install step writes token into pnpm user-level config (`pnpm config set …`) before `pnpm install` and carries `BKIT_GH_TOKEN_INSTALL` env block — only thing CI needs to authenticate `@cbartens/bkit` is `BKIT_GH_TOKEN_INSTALL` secret from step 2. No cross-org `uses:` reference; `bkit` stays private without affecting consumer auth.
|
|
99
|
+
|
|
100
|
+
### Then in the consumer repo
|
|
101
|
+
|
|
102
|
+
`bkit install` requires you to name modules (at least one) — bare `bkit install` errors. Core (stack-agnostic foundation) always implicit. Re-run / `bkit upgrade` after package updates. Use `bkit check` as CI drift gate.
|
|
103
|
+
|
|
104
|
+
> **Shell alias (add once to `~/.zshrc` or `~/.bashrc`, then `source ~/.zshrc`)**
|
|
105
|
+
>
|
|
106
|
+
> ```bash
|
|
107
|
+
> alias bkit='pnpm bkit'
|
|
108
|
+
> ```
|
|
109
|
+
>
|
|
110
|
+
> Type `bkit <verb>` from anywhere in repo. Without alias, prefix with `pnpm`: `pnpm bkit install --claude`. `bkit doctor` emits advisory if alias not detected.
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
# Name the host(s) + stack you want — core is implicit. Hosts compose.
|
|
114
|
+
bkit install --claude # .claude/** + CLAUDE.md + core
|
|
115
|
+
bkit install --cursor # .cursor/** + core
|
|
116
|
+
bkit install --codex # Codex CLI host + core
|
|
117
|
+
bkit install --opencode=opencode-go # additive opencode host (opencode-native gateway) + core
|
|
118
|
+
|
|
119
|
+
# A bare install errors — name at least one module:
|
|
120
|
+
bkit install # ✗ error: requires ≥1 module flag
|
|
121
|
+
|
|
122
|
+
# Ongoing sync — re-render everything installed at the CURRENT version (offline)
|
|
123
|
+
bkit upgrade
|
|
124
|
+
|
|
125
|
+
# Move to a newer bkit in ONE step — bumps @cbartens/bkit, then re-renders + re-pins
|
|
126
|
+
bkit upgrade --latest # newest published; or --to=<version> to pin one
|
|
127
|
+
|
|
128
|
+
# Drift detection — drift-checks everything installed; exits non-zero on drift (CI gate)
|
|
129
|
+
bkit check
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
**Module flags** (composable; symmetric install ↔ uninstall): `--claude` `--cursor` `--codex` `--opencode=<provider>`. The CI workflow, the Vale config, the tool configs, the git hooks, the slop-scan type-suppression plugin (`scripts/slop/bkit-slop-type-suppression.mjs`), and the tool `package.json` scripts and devDeps are templates you copy from `.bkit/templates/` (`.bkit/templates.md`). Core, implicit on every install, seeds the `bkit:gate:*` / `bkit:deps:*` scripts every workflow runs (add-if-missing; a name already present is never touched); point their values at your stack, see `.bkit/README.md` § Required tools. Any other module flag is an unknown-flag error.
|
|
133
|
+
|
|
134
|
+
**Opt-in flags:** `--tracker=github|linear`, `--auto=claude|cursor` (cloud agents), `--opencode=<provider>` (additive opencode execution host — `openrouter`, `ollama`, `opencode-zen`, `opencode-go`). Dependency updaters: copy an example and own it. See [§ Optional post-install decisions](#optional-post-install-decisions).
|
|
135
|
+
|
|
136
|
+
> **⚠️ Moving bkit versions: use `bkit upgrade --latest` (or `--to=<version>`).** Bumps `@cbartens/bkit` **and** resyncs `.agents/` payload + `.bkit/version` pin in one atomic step — two can never drift apart. Bare `pnpm add @cbartens/bkit` (or Renovate/Dependabot bump) only refreshes `package.json` + lockfile — does **not** resync; skipping resync reds CI on `bkit check` drift gate. If you bump package separately, run `bkit upgrade` afterward and commit resync alongside version bump in same PR.
|
|
137
|
+
|
|
138
|
+
### Local env setup
|
|
139
|
+
|
|
140
|
+
Two flows — pick one. Both end with `BKIT_GH_TOKEN_INSTALL` and `BKIT_GH_TOKEN` in shell for pnpm and GitHub MCP. Linear repos also need `BKIT_LINEAR_API_KEY`. Use `gh auth login` for CLI.
|
|
141
|
+
|
|
142
|
+
#### Flow A — Shell export (quickest, no extra deps)
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
# Add to ~/.zshrc (or ~/.bashrc)
|
|
146
|
+
export BKIT_GH_TOKEN_INSTALL=<classic PAT, read:packages> # pnpm → npm.pkg.github.com
|
|
147
|
+
export BKIT_GH_TOKEN=<fine-grained PAT> # GitHub MCP
|
|
148
|
+
export BKIT_LINEAR_API_KEY=<Linear personal API key> # Linear MCP + preflight
|
|
149
|
+
|
|
150
|
+
# Reload
|
|
151
|
+
source ~/.zshrc # or: source ~/.bashrc
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Pros: one step, no install. Cons: tokens in every shell on machine; no per-repo scoping.
|
|
155
|
+
|
|
156
|
+
#### Flow B — direnv + `.bkit/.env` (recommended for daily use)
|
|
157
|
+
|
|
158
|
+
`bkit install` writes `.bkit/.env.example` (placeholders + permission notes; bkit owns it and overwrites edits — real values go in `.bkit/.env`). `.envrc` (`dotenv_if_exists .bkit/.env`) is a template: copy it from `.bkit/templates/.envrc`. direnv loads `.bkit/.env` on `cd`, unloads on leave — tokens scoped to repo.
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
# 1. One-time per machine — install direnv
|
|
162
|
+
brew install direnv # macOS
|
|
163
|
+
# Linux / other: https://direnv.net/docs/installation.html
|
|
164
|
+
|
|
165
|
+
# 2. One-time per machine — add the shell hook, then reload
|
|
166
|
+
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc && source ~/.zshrc
|
|
167
|
+
# bash: echo 'eval "$(direnv hook bash)"' >> ~/.bashrc && source ~/.bashrc
|
|
168
|
+
|
|
169
|
+
# 3. One-time per consumer repo (after `bkit install`)
|
|
170
|
+
cp .bkit/templates/.envrc .envrc # unless you already have one
|
|
171
|
+
cp .bkit/.env.example .bkit/.env
|
|
172
|
+
# Edit .bkit/.env: set BKIT_GH_TOKEN_INSTALL, BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY
|
|
173
|
+
direnv allow # trust the .envrc
|
|
174
|
+
|
|
175
|
+
# 4. Verify
|
|
176
|
+
echo "len=${#BKIT_GH_TOKEN}" # non-zero → MCP token loaded
|
|
177
|
+
gh auth status # gh CLI uses keyring, not BKIT_GH_TOKEN
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
After step 4, restart open Claude Code / Cursor sessions in this repo so new env reaches MCP servers.
|
|
181
|
+
|
|
182
|
+
`.bkit/.env` gitignored — never commit. Cloud sessions (Claude Code on the web, Cursor Background Agents): set same names in respective online dashboards; see `.bkit/cloud.md` § Environment variables. `bkit install` / `bkit check` advisories detect missing direnv, blank required keys, un-allowed `.envrc` — follow whichever fires.
|
|
183
|
+
|
|
184
|
+
#### One-time per machine — register the GH Packages token with pnpm
|
|
185
|
+
|
|
186
|
+
After either flow makes `BKIT_GH_TOKEN_INSTALL` available in shell, write into pnpm user-level auth config so local `pnpm install` resolves `@cbartens/bkit`:
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
pnpm >=10.34.3 does not authenticate project-`.npmrc` `${BKIT_GH_TOKEN_INSTALL}` env-substitution (401s on download) — user-level step required; committed `.npmrc` carries only registry mapping. `pnpm config set` writes `~/.npmrc` on pnpm 10.x and `~/.config/pnpm/auth.ini` on pnpm 11.x (whichever pnpm reads) — same command across pnpm versions.
|
|
193
|
+
|
|
194
|
+
## Cloud agent environments (Claude Code on the web + Cursor Background Agents)
|
|
195
|
+
|
|
196
|
+
bkit ships repo-side scaffolding for both cloud agents. Opt-in `bkit install --auto=claude` writes no file; the per-session install hook (`.claude/hooks/bkit-cloud-bootstrap.sh`), the phase-routed `.github/workflows/bkit-cloud.yml` and the Cursor cloud image files (`.cursor/Dockerfile`, `.cursor/environment.json`) are templates in `.bkit/templates/` that you copy and own. (`.cursor/hooks.json` — Linear preflight wiring — ships with `--cursor`, not `--auto`.) Install without `--auto` ships zero cloud footprint. **Online-dashboard** half (Claude env in `claude.ai/code`, Cursor env vars in `Cursor → Settings → Background Agents`) configured once per machine / account.
|
|
197
|
+
|
|
198
|
+
For **post-CI auto-routing** (ship-vs-debug after CI), bkit ships a single `.github/workflows/bkit-cloud.yml` template with TWO runtime-gated dispatch jobs — **claude** job (`claude-code-action`, runs when the `ANTHROPIC_API_KEY` repo secret is set) and **opencode** job (`opencode run` CLI, runs when `OPENCODE_PROVIDER_KEY` set) — plus `/bkit-auto` slash command both clouds invoke from single source (Cursor wires via dashboard trigger; no GHA on Cursor side). `bkit install --auto=opencode` requires `tracker=github`.
|
|
199
|
+
|
|
200
|
+
Full recipe + paste-in setup script + env-var inventory + Cursor dashboard config + consumer customisation patterns: `.bkit/cloud.md`. Host-delta matrix: `.bkit/providers.md` § Runtime environment.
|
|
201
|
+
|
|
202
|
+
## JSON ownership model — deep-containment
|
|
203
|
+
|
|
204
|
+
`.claude/settings.json` and `.cursor/hooks.json` managed via **deep-containment**. bkit declares scope (full template JSON tree) that must be present as subset of consumer document. Consumer-added keys outside template tree survive every `bkit install` byte-identically — no special key or wrapper required.
|
|
205
|
+
|
|
206
|
+
```json
|
|
207
|
+
// .claude/settings.json
|
|
208
|
+
{
|
|
209
|
+
"hooks": {
|
|
210
|
+
"SessionStart": [
|
|
211
|
+
{ "hooks": [{ "type": "command", "command": "bash .claude/hooks/bkit-preflight.sh" }] }
|
|
212
|
+
],
|
|
213
|
+
"Stop": [{ "hooks": [{ "type": "command", "command": "postflight.sh" }] }]
|
|
214
|
+
},
|
|
215
|
+
"failClosed": true
|
|
216
|
+
}
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
In this example, `hooks.SessionStart` is bkit-declared scope (from template). `hooks.Stop` and `failClosed` are consumer-added — bkit never touches them.
|
|
220
|
+
|
|
221
|
+
**Rules:**
|
|
222
|
+
|
|
223
|
+
- Consumer keys outside template tree survive every `bkit install` byte-identically.
|
|
224
|
+
- `bkit install` uses `deepContains(template, consumer)` — every template leaf present. On drift, deep-merges template-wins; consumer-only siblings preserved.
|
|
225
|
+
- `bkit check` surfaces `tier2-json-drift` advisory when `deepContains` fails and **exits 1** (CI drift gate); writes nothing — consumer reviews and re-runs `bkit install` to reconverge.
|
|
226
|
+
- `.cursor/hooks.json` uses Cursor v1 keyed-object schema: `{"version": 1, "hooks": {"sessionStart": [...], "sessionStop": [...]}}`.
|
|
227
|
+
|
|
228
|
+
## Consumer CI auth
|
|
229
|
+
|
|
230
|
+
bkit resolves from **GitHub Packages npm registry**. Authentication requires:
|
|
231
|
+
|
|
232
|
+
1. **Create a classic PAT** on GitHub with `read:packages` scope:
|
|
233
|
+
- GitHub Settings → Developer settings → Personal access tokens → **Tokens (classic)** → Scope: `read:packages`
|
|
234
|
+
- Copy the generated token
|
|
235
|
+
|
|
236
|
+
> **⚠️ Use a classic PAT, not fine-grained.** GitHub Packages npm registry currently rejects fine-grained PATs with HTTP 403, even when `Packages: read` is granted. Confirmed against `npm.pkg.github.com` 2026-05-06. If/when GitHub fixes this, fine-grained PATs will become preferred (narrower scope); for now classic is the only working option.
|
|
237
|
+
|
|
238
|
+
2. **Add the secret** to your consumer repo:
|
|
239
|
+
- GitHub repo → Settings → Secrets and variables → Actions → New repository secret
|
|
240
|
+
- Name: `BKIT_GH_TOKEN_INSTALL`
|
|
241
|
+
- Value: paste the PAT
|
|
242
|
+
|
|
243
|
+
3. **Add `.npmrc`** at your repo root (committed, no secrets) — registry mapping ONLY. Auth token **not** stored here:
|
|
244
|
+
|
|
245
|
+
```
|
|
246
|
+
@cbartens:registry=https://npm.pkg.github.com
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
4. The `bkit-ci.yml` template's install step writes token into pnpm user-level config before install (copy it from `.bkit/templates/.github/workflows/bkit-ci.yml`, or add the step to your own workflow):
|
|
250
|
+
|
|
251
|
+
```yaml
|
|
252
|
+
- name: Install Dependencies
|
|
253
|
+
run: |
|
|
254
|
+
pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"
|
|
255
|
+
pnpm install --frozen-lockfile
|
|
256
|
+
env:
|
|
257
|
+
BKIT_GH_TOKEN_INSTALL: ${{ secrets.BKIT_GH_TOKEN_INSTALL }}
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
> **⚠️ Why `pnpm config set`, not `.npmrc`:** pnpm >=10.34.3 does not authenticate project-`.npmrc` `${BKIT_GH_TOKEN_INSTALL}` env-substitution — `pnpm install` 401s on `@cbartens/bkit` download (`ERR_PNPM_FETCH_401`) even when token set. `pnpm config set` writes token to pnpm user-level config (`~/.npmrc` on pnpm 10.x, `~/.config/pnpm/auth.ini` on pnpm 11.x). Leftover `_authToken` line in project `.npmrc` must be **removed** — 401s and, by config precedence (project > user), shadows user-level token. Note: `pnpm view @cbartens/bkit` (metadata) may still resolve with broken setup — verify with real `pnpm install`, not `view`.
|
|
261
|
+
|
|
262
|
+
### Agent access to `BKIT_GH_TOKEN_INSTALL`
|
|
263
|
+
|
|
264
|
+
If permission rules block direct reads of `.env*` files (e.g. `Read(./.env*)`, `Bash(grep ... .env*)` denied), token still cannot be read — but **can** be exported into child process for duration of single command. Use in single Bash tool call:
|
|
265
|
+
|
|
266
|
+
```bash
|
|
267
|
+
set -a; source apps/web/.env.preview 2>/dev/null; set +a; <command that needs the token>
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
- `source` is shell builtin, not file I/O — agent permission layer (gates `Read` / `grep` / `cat`) does not see it. Token text never enters agent context.
|
|
271
|
+
- `<command>` (e.g. `pnpm view @cbartens/bkit`, `bkit check`) inherits `BKIT_GH_TOKEN_INSTALL` via environment.
|
|
272
|
+
- Verify token loaded **without leaking value**: `echo "len=${#BKIT_GH_TOKEN_INSTALL}"`.
|
|
273
|
+
|
|
274
|
+
**Caveat:** shell state does not persist between separate Bash tool calls. `source` and consuming command must run in **same** invocation — chain with `;` or `&&`. When directing another agent, name file path explicitly (e.g. _"source `apps/web/.env.preview` in-line; registry needs `BKIT_GH_TOKEN_INSTALL`"_).
|
|
275
|
+
|
|
276
|
+
## Consumer Vercel auth
|
|
277
|
+
|
|
278
|
+
Vercel runs own `pnpm install` in fresh build container — cannot run pre-install shell step. pnpm >=10.34.3 does not authenticate project-`.npmrc` `${BKIT_GH_TOKEN_INSTALL}` env-substitution, so set token via one-line `installCommand` writing pnpm user-level config before install.
|
|
279
|
+
|
|
280
|
+
1. **Add `BKIT_GH_TOKEN_INSTALL` to Vercel env vars** for each environment that builds (preview + production at minimum):
|
|
281
|
+
|
|
282
|
+
```bash
|
|
283
|
+
vercel env add BKIT_GH_TOKEN_INSTALL preview
|
|
284
|
+
vercel env add BKIT_GH_TOKEN_INSTALL production
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
Or via web: Vercel project → Settings → Environment Variables. Token value = same PAT as GitHub Actions secret (scope: `read:packages`).
|
|
288
|
+
|
|
289
|
+
2. **Set `installCommand` in `vercel.json`** so token reaches pnpm user-level auth config before install (remove any pre-existing git-shim `installCommand`):
|
|
290
|
+
|
|
291
|
+
```json
|
|
292
|
+
{
|
|
293
|
+
"installCommand": "pnpm config set //npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL && pnpm install"
|
|
294
|
+
}
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
3. **Trigger redeploy** (push commit) and watch Vercel build log for `pnpm install` resolving `@cbartens/bkit` from `npm.pkg.github.com`.
|
|
298
|
+
|
|
299
|
+
## Install lifecycle
|
|
300
|
+
|
|
301
|
+
`bkit install` runs three phases in sequence:
|
|
302
|
+
|
|
303
|
+
**Phase 1 — Preflight (read-only, before any writes)**
|
|
304
|
+
|
|
305
|
+
bkit checks preconditions and known advisory patterns before touching any file. Blocker fires → install exits 1 immediately with formatted `[blocker]` line and zero writes. Advisories accumulated for Phase 3.
|
|
306
|
+
|
|
307
|
+
<!-- prettier-ignore -->
|
|
308
|
+
| Severity | When |
|
|
309
|
+
| --- | --- |
|
|
310
|
+
| Blocker | `package.json` absent or unparseable JSON |
|
|
311
|
+
| Blocker | core install requested but `.git/` absent (not a git repository) |
|
|
312
|
+
| Advisory | On-disk `.bkit/version` major > installing major (downgrade) |
|
|
313
|
+
| Advisory | `node_modules/@cbartens/bkit` version > `.bkit/version` (stale pin) |
|
|
314
|
+
|
|
315
|
+
**Phase 2 — Install**
|
|
316
|
+
|
|
317
|
+
Module dispatch writes managed files.
|
|
318
|
+
|
|
319
|
+
**Phase 3 — Post-install (re-detect + unified output)**
|
|
320
|
+
|
|
321
|
+
After writes, bkit re-runs token-surface and environment checks — some only accurate post-install (e.g. the `bkit:gate:*` scripts core just seeded into `package.json`). The table also lists the module advisories that render in the same checklist.
|
|
322
|
+
|
|
323
|
+
<!-- prettier-ignore -->
|
|
324
|
+
| `id` | When |
|
|
325
|
+
| --- | --- |
|
|
326
|
+
| `gh-bkit-token-unset-shell` / `gh-bkit-token-empty-shell` | `BKIT_GH_TOKEN_INSTALL` unset (or set but empty) in shell |
|
|
327
|
+
| `npmrc-missing-gh-packages` | `.npmrc` exists but lacks the `@cbartens` registry mapping |
|
|
328
|
+
| `npmrc-authtoken-line` | `.npmrc` carries a `//npm.pkg.github.com/:_authToken=…` line (401s on pnpm >=10.34.3; move it to pnpm user-level config) |
|
|
329
|
+
| `gh-bkit-token-secret-missing` | `gh secret list` confirms secret absent |
|
|
330
|
+
| `gh-bkit-token-secret-unknown` | `gh` CLI unavailable/unauthenticated |
|
|
331
|
+
| `gh-mcp-token-unset-shell` / `gh-mcp-token-empty-shell` | `BKIT_GH_TOKEN` (GitHub MCP auth) unset/empty in shell while a `github` MCP server is configured — the whole tracker/PR/board MCP surface fails to connect. Suppressed in CI. |
|
|
332
|
+
| `vercel-env-missing-preview` | `vercel.json` detected; token absent in preview |
|
|
333
|
+
| `vercel-env-missing-production` | `vercel.json` detected; token absent in production |
|
|
334
|
+
| `ci-yml-missing-token-env` | bkit-ci.yml install step lacks the `pnpm config set` auth step and/or the `BKIT_GH_TOKEN_INSTALL` env mapping |
|
|
335
|
+
| `tracker-setup-none` / `-github` / `-linear` | Optional post-install decision — which issue tracker is wired (`bkit.issueTracker`). `none` nudges `bkit install --tracker=…`. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
336
|
+
| `github-project-board-sync-unconfigured` | GitHub tracker active but Projects v2 board sync is half-configured (`bkit.githubProject` absent and/or `.mcp.json` lacks the `projects` toolset) — sync silently no-ops. Silence with `bkit.githubProject: false`. |
|
|
337
|
+
| `github-project-status-field-id-format` | `bkit.githubProject` is configured but `statusFieldId` holds a GraphQL node id (`PVTSSF_…`) or non-number — `projects_write` needs the numeric field id, so board sync silently no-ops. Re-derive via `gh api /orgs/<org>/projectsV2/<number>/fields`. |
|
|
338
|
+
| `dep-updater-absent` | No Renovate or Dependabot config. Copy one example and own it. `bkit.depUpdater: "none"` silences this. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
339
|
+
| `dep-updater-both` | Both updater configs are present. Keep one. |
|
|
340
|
+
| `cloud-router-none` / `cloud-router` | Optional post-install decision — post-CI auto-routing (`bkit.cloudAgents`). `none` (undecided) nudges `bkit install --auto=<variant>`; `cloud-router` is informational once `bkit-cloud.yml` is present. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
341
|
+
| `actions-write-permissions-missing` | `bkit-cloud.yml` present but repo Actions permissions are read-only / PR creation disabled — `actions/checkout` + `gh pr create` 403. Repo-level check; org policy can override. |
|
|
342
|
+
| `opencode-setup` | opencode host installed (`--opencode=<provider>`) — names the provider key to set (e.g. `BKIT_OPENROUTER_API_KEY`; `BKIT_OPENCODE_API_KEY` for `opencode-zen` / `opencode-go`), confirms the pre-seeded base URL, and notes all four providers ship curated per-agent pins (re-pin via `.bkit/prompts.md` § Model Overrides). Verify with `bkit doctor` + `bkit status`. |
|
|
343
|
+
| `vale-package-not-synced` | vale on PATH but `.vale/styles/write-good/` absent |
|
|
344
|
+
| `gate-missing-called-scripts` | A `bkit:gate:*` script still at bkit's default chains a script `package.json` does not declare (e.g. `typecheck`, `format:check`, `test`). Add it (`.bkit/templates.md` lists the tool scripts and devDeps) or rewrite the gate. |
|
|
345
|
+
| `gate-noop` | A `bkit:gate:*` script is empty or cannot fail (`true`, `:`, `exit 0`, `echo …`), so every agent run and push passes it. Warn-only, at install and `bkit check`, on every branch. Point it at real checks, or delete it and run `bkit upgrade` to restore bkit's default. |
|
|
346
|
+
| `gate-tier-not-wired` | `package.json` declares a deeper test tier (`test:integration`, `test:e2e`, `test:live`) that no `bkit:gate:*` script runs; the advisory prints the gate line to add. |
|
|
347
|
+
|
|
348
|
+
Phase 1 and Phase 3 findings merged and deduplicated by `id` (Phase 3 wins on conflict — re-detection more accurate post-write). Zero findings → no banner.
|
|
349
|
+
|
|
350
|
+
**`bkit check` (dry-run)** runs Phase 1 and Phase 3 (read-only) — same advisory set as `bkit install` minus writes. Changes no managed file (regenerates `.bkit/advisories.md` artifact) and **exits 1 when any managed-file write would occur** in installed module — Tier-2 JSON deep-containment or markered-block drift, whole-file byte-equal mismatch, **host agent/command mirror content drift** (would-write / orphan delete), or when any file bkit writes (rendered agents / commands / skills, managed blocks, owned whole files) carries a stale managed-version marker (`bkit-managed-stale`). Gate covers the **installed** module set ({core, claude, cursor, codex} plus **opencode**, each detected by sentinel files). A missing `bkit:gate:*` name counts as a write. opencode gated: `.opencode/opencode.json` (provider block + tracker-filtered mcp + permission sandbox) and `bkit-gateguard.js` drift fail `check` — render inputs fall back to installed provider (`package.json` `bkit.opencodeProvider`, authoritative for `opencode-zen` / `opencode-go`; all installed providers tracked in `bkit.opencodeProviders: string[]`) and recorded tracker, so clean install across providers checks green (no false drift). Remaining **opt-in** module (cloud) is not drift-gated. A missing bkit-owned hook file also fails `check`, one line per file naming it and the `bkit install` flag that restores it: the hook files of every installed host (`.claude/hooks/*`, `.cursor/hooks/*`, `.codex/hooks/*`, `.opencode/plugin/bkit-gateguard.js`) — the hook commands skip a missing file (`test -f … || true`), so without this the guard would be off with no signal. Updater configs are not bkit files, so `bkit check` does not report them. Phase 3 stays read-only through read-only detector paths, not by being skipped.
|
|
351
|
+
|
|
352
|
+
**`PreflightFinding` shape** — stable contract for downstream tooling:
|
|
353
|
+
|
|
354
|
+
```typescript
|
|
355
|
+
interface PreflightFinding {
|
|
356
|
+
id: string; // stable kebab-case identifier
|
|
357
|
+
severity: "blocker" | "advisory";
|
|
358
|
+
detect: string; // one-line description of the detected condition
|
|
359
|
+
action: string; // AI-pasteable fix instruction
|
|
360
|
+
}
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
Findings rendered as `--- i/N [severity] id ---` with `DETECT:` and `ACTION:` sections — copy-paste whole banner into coding assistant to apply fixes in sequence.
|
|
364
|
+
|
|
365
|
+
For four-surface token sweep, see [§ Consumer CI auth](#consumer-ci-auth).
|
|
366
|
+
|
|
367
|
+
## Optional post-install decisions
|
|
368
|
+
|
|
369
|
+
Two capabilities **opt-in** — never wired by plain host/tooling install. Default install never enables them; post-install advisory banner nudges you to choose, once. Each recorded in `package.json` (`bkit.issueTracker`, `bkit.cloudAgents`) so the nudge knows whether you've decided or deliberately opted out.
|
|
370
|
+
|
|
371
|
+
<!-- prettier-ignore -->
|
|
372
|
+
| Decision | Default | Opt-in command | Advisory when unset |
|
|
373
|
+
| --- | --- | --- | --- |
|
|
374
|
+
| **Issue tracker** | `none` (workflows run; tracker calls are no-ops) | `bkit install --tracker=github` (browser OAuth, no PAT) or `--tracker=linear` (`BKIT_LINEAR_API_KEY`) | `tracker-setup-none` |
|
|
375
|
+
| **Cloud agents** | none (zero cloud footprint) | `bkit install --auto=claude\|cursor\|opencode` — records the choice and points at the copy-and-own templates: `.claude/hooks/bkit-cloud-bootstrap.sh` (claude), the `bkit-cloud.yml` (claude + opencode jobs, secret-gated) and the Cursor Dockerfile/environment.json | `cloud-router-none` |
|
|
376
|
+
|
|
377
|
+
**Dependency updater.** Copy one example and own it.
|
|
378
|
+
|
|
379
|
+
<!-- prettier-ignore -->
|
|
380
|
+
| Updater | Copy from |
|
|
381
|
+
| --- | --- |
|
|
382
|
+
| Renovate rules | `.bkit/templates/.github/renovate.json5` |
|
|
383
|
+
| Renovate self-hosted runner | `.bkit/templates/.github/workflows/bkit-renovate.yml` |
|
|
384
|
+
| Dependabot | `.bkit/templates/.github/dependabot.yml` |
|
|
385
|
+
|
|
386
|
+
Use one. `bkit.depUpdater: "none"` skips the install-time absence advisory. Setup: `docs/deployments.md` § Dependency updaters.
|
|
387
|
+
|
|
388
|
+
**All templates.** Copy and own, never installed. Catalog and install steps: `.bkit/templates.md`.
|
|
389
|
+
|
|
390
|
+
**Why opt-in, not part of a default install:**
|
|
391
|
+
|
|
392
|
+
- **Tracker** wires real credentials and MCP servers into workflows — consumer must choose provider; bkit can't guess.
|
|
393
|
+
- **Cloud agents** run through the phase-routed `bkit-cloud.yml` template (auto-dispatches bkit-ship on CI pass, bkit-debug on CI fail; design/plan/build via `workflow_dispatch`) plus cloud env scaffolding (`.claude/hooks/bkit-cloud-bootstrap.sh`, and the `.cursor/Dockerfile` + `.cursor/environment.json` templates). Workflow carries claude job and opencode job, each runtime-gated on provider secret — inert without key: claude needs `BKIT_ANTHROPIC_API_KEY` (+ Claude GitHub App), opencode needs `OPENCODE_PROVIDER_KEY`. Both need GitHub Actions write permissions, GitHub tracker, and (Cursor half) dashboard trigger — tracker itself opt-in. Env scaffolding inert until Claude/Cursor cloud env wired in dashboard. Autonomous routing by default, wired to unconfigured tracker, is wrong default — install without `--auto` ships zero cloud footprint.
|
|
394
|
+
|
|
395
|
+
**How to decide:**
|
|
396
|
+
|
|
397
|
+
1. Run `bkit install --claude --cursor` (or whichever modules you want). Post-install banner lists `tracker-setup-none`, `dep-updater-absent`, `cloud-router-none` if undecided.
|
|
398
|
+
2. Pick tracker: `bkit install --tracker=github` (or `linear`). Persisted to `bkit.issueTracker`; future installs preserve (switching free).
|
|
399
|
+
3. Copy one updater example (table above). Land Renovate config on the default branch before installing the App.
|
|
400
|
+
4. Enable cloud agents: `bkit install --auto=claude|cursor|opencode`. Persisted to `bkit.cloudAgents`; install prints secrets + permissions + dashboard checklist (`bkit-auto-setup`). Shipped `bkit-cloud.yml` carries claude job (`ANTHROPIC_API_KEY` repo secret) and opencode job (`OPENCODE_PROVIDER_KEY`), each runtime-gated.
|
|
401
|
+
5. **To opt out and silence the nudge**, set the field to `"none"` in `package.json` (`bkit.issueTracker` / `bkit.depUpdater` / `bkit.cloudAgents`). Advisory stays quiet.
|
|
402
|
+
|
|
403
|
+
Tracker and cloud agents reverse by re-running install with the other flag. Updater files stay until you delete them.
|
|
404
|
+
|
|
405
|
+
## Doctor
|
|
406
|
+
|
|
407
|
+
`bkit doctor` is **diagnostic verb** — runs Phase 1 preflight + Phase 3 token-surface detectors, exits 0. Changes no managed file; like `bkit check` regenerates `.bkit/advisories.md` artifact (creates `.bkit/` if absent — repo that never installed bkit gains that one file).
|
|
408
|
+
|
|
409
|
+
```bash
|
|
410
|
+
# Diagnose drift without running install
|
|
411
|
+
bkit doctor
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
Use `bkit doctor` to:
|
|
415
|
+
|
|
416
|
+
- Check whether `BKIT_GH_TOKEN_INSTALL` is set in shell and on GitHub repo.
|
|
417
|
+
- Surface `bkit-version-pin-stale` advisory (installed version ahead of `.bkit/version`).
|
|
418
|
+
- Preview all advisories `bkit install` would show post-install, without triggering writes.
|
|
419
|
+
- Verify environment ready before `bkit install` on new machine.
|
|
420
|
+
- Detect macOS GUI-isolation (`bkit cursor` / `bkit opencode`): see `.bkit/providers.md` § macOS GUI-isolation.
|
|
421
|
+
`bkit doctor` always exits 0. Advisories found → printed in same checklist banner format as `bkit install`. None found → prints `[bkit-doctor] No advisories found.`
|
|
422
|
+
|
|
423
|
+
## Uninstall
|
|
424
|
+
|
|
425
|
+
`bkit uninstall` surgically removes bkit-managed content while preserving consumer customisations.
|
|
426
|
+
|
|
427
|
+
```bash
|
|
428
|
+
# Uninstall EVERYTHING — all modules, including the cloud add-on if present.
|
|
429
|
+
# The inverse of install is asymmetric: a full *install* skips cloud, a full
|
|
430
|
+
# *uninstall* removes it. Your copies of templates (bkit-ci.yml, hooks, tool configs,
|
|
431
|
+
# updater configs) and every package.json script and devDep (the bkit:gate:* names
|
|
432
|
+
# included) are left in place; only the `bkit` install-state block is removed.
|
|
433
|
+
bkit uninstall
|
|
434
|
+
|
|
435
|
+
# Preview what would be removed (no writes)
|
|
436
|
+
bkit uninstall --dry-run
|
|
437
|
+
|
|
438
|
+
# Uninstall specific modules (targeted — leaves core + the other modules intact)
|
|
439
|
+
bkit uninstall --claude # removes the claude host only
|
|
440
|
+
bkit uninstall --auto # clears the cloudAgents key (cloud files are copy-and-own)
|
|
441
|
+
|
|
442
|
+
# Force-delete byte-equal-text files even if consumer modified them
|
|
443
|
+
bkit uninstall --force
|
|
444
|
+
|
|
445
|
+
# Delete ALL bkit files regardless of consumer modifications (confirm prompt)
|
|
446
|
+
bkit uninstall --nuke
|
|
447
|
+
# Skip interactive confirm:
|
|
448
|
+
bkit uninstall --nuke --yes
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
### Format semantics during uninstall
|
|
452
|
+
|
|
453
|
+
<!-- prettier-ignore -->
|
|
454
|
+
| Format | Behaviour |
|
|
455
|
+
| --- | --- |
|
|
456
|
+
| `fully-managed` | Always deleted (bkit owns 100% of the file). |
|
|
457
|
+
| `markered-text` | bkit block stripped; consumer content above/below preserved. File deleted if only whitespace remains — or, for a bkit-seeded markdown file (`AGENTS.md`/`CLAUDE.md`), if only its `# Title` heading husk remains. |
|
|
458
|
+
| `byte-equal-text` | Deleted only if current hash matches the hash `.bkit/version` recorded when bkit last wrote it (`canonicalHashes`). Consumer modifications → preserved. |
|
|
459
|
+
| `json` | bkit's keys stripped; consumer keys preserved. `.mcp.json` / `.cursor/mcp.json`: only bkit's tracker entry is removed, and only while it still equals the template. File deleted when nothing is left. |
|
|
460
|
+
|
|
461
|
+
### Idempotency
|
|
462
|
+
|
|
463
|
+
Running `bkit uninstall` twice is safe — subsequent runs skip absent files and produce zero writes.
|
|
464
|
+
|
|
465
|
+
### What a full uninstall preserves
|
|
466
|
+
|
|
467
|
+
Bare uninstall removes bkit-managed files and strips bkit-managed blocks, but **not** guaranteed zero-footprint wipe. `docs/`: bkit's block (managed marker included) is stripped from every installed `docs/*.md` — a file holding nothing else is deleted — and the owned `docs/templates/bkit-*.md` are deleted. Deliberately leaves: everything outside `bkit:start` / `bkit:end` in `docs/*.md`, `.agents/context.md`, `.agents/skills.md` and the other managed-block files; your own files in `docs/` and `docs/templates/`; every file you copied from `.bkit/templates/`; any owned whole-file the consumer modified (hash mismatch → preserved); generated artefacts not manifest-tracked (`.bkit/advisories.md`, `.bkit/friction.jsonl`). Use `--nuke` to force-remove every manifest-listed bkit file regardless of consumer modifications; generated artefacts still yours to delete by hand.
|
|
468
|
+
|
|
469
|
+
## Phase 3 exit-1 and recovery
|
|
470
|
+
|
|
471
|
+
When `bkit install` detects **blocker-severity** finding in Phase 3 (e.g. `bkit-ci.yml` missing `BKIT_GH_TOKEN_INSTALL` env mapping with `.npmrc` referencing token), exits 1 and prints single-line recovery command:
|
|
472
|
+
|
|
473
|
+
```
|
|
474
|
+
[bkit-install] 1 Phase 3 blocker(s) detected. Recovery:
|
|
475
|
+
bkit uninstall <flags> && <fix the issue> && bkit install <flags>
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
Advisories (non-blockers) informational only — do not trigger exit-1.
|
|
479
|
+
|
|
480
|
+
### --auto-revert
|
|
481
|
+
|
|
482
|
+
Add `--auto-revert` to `bkit install` to automatically run `bkit uninstall` in-process when Phase 3 blocker fires:
|
|
483
|
+
|
|
484
|
+
```bash
|
|
485
|
+
bkit install --auto-revert
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
Useful in CI scripts to guarantee clean state on failure.
|
|
489
|
+
|
|
490
|
+
## Install staging directory
|
|
491
|
+
|
|
492
|
+
`bkit install` renders derived files (e.g. `.opencode/opencode.json`) into `.bkit-staging/` scratch directory before merging into consumer destinations. Scratch directory cleaned up after every run — success and failure alike — never persists in committed consumer repo state.
|
|
493
|
+
|
|
494
|
+
**Not a cross-module transaction.** Modules write directly to destinations — `bkit install` not atomic across modules: failure partway (e.g. hand-broken `.claude/settings.json` makes JSON merge throw) leaves earlier-module files written and `.bkit/version` unpinned. Error surfaced, not swallowed.
|
|
495
|
+
|
|
496
|
+
**Recovery is re-run.** `bkit install` idempotent — fix offending file and re-run to complete. `bkit uninstall` removes whatever was written.
|