@cbartens/bkit 0.0.0-stage → 5.0.1
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 +417 -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 +417 -0
- package/.bkit/core/.bkit/cloud.md +493 -0
- package/.bkit/core/.bkit/comparison.md +321 -0
- package/.bkit/core/.bkit/install.md +401 -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 +470 -0
- package/.bkit/core/.bkit/trackers.md +95 -0
- package/.bkit/core/.bkit/workflows.md +1550 -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 +149 -0
- package/.bkit/core/engine/checks/after/ci-yml.ts +701 -0
- package/.bkit/core/engine/checks/after/github.ts +424 -0
- package/.bkit/core/engine/checks/after/index.ts +530 -0
- package/.bkit/core/engine/checks/after/managed.ts +217 -0
- package/.bkit/core/engine/checks/after/suppression.ts +53 -0
- package/.bkit/core/engine/checks/after/tools.ts +427 -0
- package/.bkit/core/engine/checks/before/context-fetch.ts +429 -0
- package/.bkit/core/engine/checks/before/env.ts +187 -0
- package/.bkit/core/engine/checks/before/files.ts +204 -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 +867 -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 +254 -0
- package/.bkit/core/engine/commands/install/install.ts +550 -0
- package/.bkit/core/engine/commands/install/uninstall.ts +995 -0
- package/.bkit/core/engine/commands/install/upgrade.ts +1037 -0
- package/.bkit/core/engine/commands/launch.ts +139 -0
- package/.bkit/core/engine/commands/lib.ts +495 -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 +924 -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 +173 -0
- package/.bkit/core/engine/install/modules/codex.ts +219 -0
- package/.bkit/core/engine/install/modules/core.ts +620 -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/payload-links.ts +150 -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 +649 -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 +86 -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 +433 -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 +97 -0
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +187 -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 +224 -0
- package/.bkit/templates/.github/workflows/bkit-ci.yml +1062 -0
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +564 -0
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +102 -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 +1503 -0
- package/LICENSE.md +161 -0
- package/README.md +184 -2
- package/dist/checks/after/auth.js +140 -0
- package/dist/checks/after/ci-yml.js +681 -0
- package/dist/checks/after/github.js +400 -0
- package/dist/checks/after/index.js +431 -0
- package/dist/checks/after/managed.js +187 -0
- package/dist/checks/after/suppression.js +39 -0
- package/dist/checks/after/tools.js +351 -0
- package/dist/checks/before/context-fetch.js +426 -0
- package/dist/checks/before/env.js +163 -0
- package/dist/checks/before/files.js +187 -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 +688 -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 +209 -0
- package/dist/commands/install/install.js +475 -0
- package/dist/commands/install/uninstall.js +839 -0
- package/dist/commands/install/upgrade.js +782 -0
- package/dist/commands/launch.js +118 -0
- package/dist/commands/lib.js +363 -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 +818 -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 +151 -0
- package/dist/install/modules/codex.js +193 -0
- package/dist/install/modules/core.js +531 -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/payload-links.js +119 -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,476 @@
|
|
|
1
|
+
<!-- Note: Plans live at `docs/plans/{YYYYMM}/{FID}-plan.md` (canonical month bucket). `{YYYYMM}` = creation month, set once by the first workflow run for `{FID}`. Logs sit at `docs/plans/{YYYYMM}/logs/{FID}/` and are delete-eligible. The canonical copy is also stamped with a `bkit:anchor` block recording its base commit; never hand-author or edit it. `@bkit-plan-generate` fills this template. -->
|
|
2
|
+
|
|
3
|
+
<!-- bkit:start -->
|
|
4
|
+
|
|
5
|
+
{{BKIT_MANAGED_MARKER}}
|
|
6
|
+
|
|
7
|
+
# [Plan Title] Implementation Plan
|
|
8
|
+
|
|
9
|
+
> [!CAUTION]
|
|
10
|
+
> **Purpose:** Implementation plan — pre-flight, gates, runbook, verification, rollback.
|
|
11
|
+
>
|
|
12
|
+
> **Rules:**
|
|
13
|
+
>
|
|
14
|
+
> - Any tools mentioned below are examples only; swap for actual tools in final output; drop inapplicable.
|
|
15
|
+
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
16
|
+
> - Read `.agents/docs.md` → load docs for workflow / step / task; skip missing; cite docs inline where required.
|
|
17
|
+
> - Read this document once at session start; do not trust session memory; do not re-read on every loop iteration.
|
|
18
|
+
> - Source of truth: literal `[x]` vs `[ ]` checkboxes in this document; `[ ]` means not DONE regardless of context.
|
|
19
|
+
|
|
20
|
+
## Context & Goals
|
|
21
|
+
|
|
22
|
+
[High-level overview of problem/feature and why it is necessary; initially set to `PENDING`.]
|
|
23
|
+
|
|
24
|
+
> Success criteria once in `Acceptance Scenario → Success Criteria`; each runbook task has own `Done when`. Do not restate success list here.
|
|
25
|
+
|
|
26
|
+
**Related Issues:**
|
|
27
|
+
|
|
28
|
+
- [Issue references from plan input (linked/referenced in issue text). Tracker refs only (e.g. `#N — title (state)`); not full content. Dedupe/scope-awareness; not scope mandate. None → `None`. Workflow fetch-context step runs fresh tracker search for reviewers, not this section.]
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## 👤 ⚠️ Acceptance Scenario
|
|
33
|
+
|
|
34
|
+
> [!CAUTION]
|
|
35
|
+
> **🛑 HUMAN must READ and CONFIRM this SECTION.**
|
|
36
|
+
> Testable feature contract — implementation, tests, verification derive from what you confirm here. Wrong here → wrong downstream.
|
|
37
|
+
>
|
|
38
|
+
> **You only need 👤-marked sections** (Acceptance Scenario, Breaking Changes, Open Questions & Assumptions). Agent handles rest.
|
|
39
|
+
|
|
40
|
+
### Spec
|
|
41
|
+
|
|
42
|
+
> [!IMPORTANT]
|
|
43
|
+
> What good looks like; canonical for the plan phase. Subagents (plan generate, plan review, plan summary) must follow this spec. No plan subagent restates rules; this section = single source of truth for the plan.
|
|
44
|
+
|
|
45
|
+
- **Narrative:** 1–2 sentences, user POV (not system POV). User action + what they get back. Design → verbatim. Audits only (`docs/audits/`) → user/operator impact from in-scope findings. Neither, or design lacks `## Acceptance Scenario` → both fields = `⚠️ MISSING: no design doc and no audit report — human must provide before plan proceeds`; never fabricate; Gate 1 blocked until human fills.
|
|
46
|
+
- **Success Criteria:** <=5 bullets, measurable / testable. Outcomes (e.g. "user sees their event in the list within 2s"), not steps (e.g. "call API, render component"). Design count ≠ 5 → smallest set proving feature. Design → verbatim. Audits only → one bullet per in-scope finding id from `Expected`; no 5-bullet cap.
|
|
47
|
+
- **Process Sketch:** Design → plan inherits/refines. same happy-path (`Concrete Example`) + branches (`Edge Cases`) as `WHEN X → THEN Y` (3–7 lines); reuse exact examples, do not invent. Outcomes, not steps.
|
|
48
|
+
- **Key Edge Cases:** Design → plan inherits. Concurrency, conflicts, failures, cross-feature — not trivial validation (plan adds that).
|
|
49
|
+
- **Edge Cases:** Plan phase — design Key Edge Cases verbatim + validation / error / boundary cases.
|
|
50
|
+
- **Concrete Example:** Plan phase only. Role, starting state, numbered steps, observable outcome. One scenario, not a list.
|
|
51
|
+
- **Derived Test Matrix:** Plan phase only. One row per testable behaviour → exactly one `Agent Execution Runbook` task. No row without a target file. In-scope audit behaviour → one row.
|
|
52
|
+
|
|
53
|
+
### Narrative
|
|
54
|
+
|
|
55
|
+
> Inherited from design; do not rewrite.
|
|
56
|
+
|
|
57
|
+
[Copied verbatim from `{FID}-design.md` § Acceptance Scenario → Narrative. No design → per Spec above; initially set to `PENDING`.]
|
|
58
|
+
|
|
59
|
+
### Success Criteria
|
|
60
|
+
|
|
61
|
+
> Inherited from design; do not rewrite.
|
|
62
|
+
|
|
63
|
+
[Copied verbatim from `{FID}-design.md` § Acceptance Scenario → Success Criteria. No design → per Spec above; initially set to `PENDING`.]
|
|
64
|
+
|
|
65
|
+
### Process Sketch
|
|
66
|
+
|
|
67
|
+
> Inherited from design; plan may refine. `Concrete Example` (happy path) + `Edge Cases` (branches) as `WHEN X → THEN Y`, not prose — same examples. Do not invent new examples. Sense-check top-level process HERE without prose below. Outcomes, not implementation steps.
|
|
68
|
+
|
|
69
|
+
- **WHEN** [trigger / user action] **→ THEN** [observable outcome]
|
|
70
|
+
- **WHEN** [next step] **→ THEN** [outcome]
|
|
71
|
+
- **IF** [edge case / failure — mirrors an Edge Cases row] **→ THEN** [handling]
|
|
72
|
+
|
|
73
|
+
_notation, e.g._ **WHEN** a user submits the form with a valid file **→ THEN** it is queued and a receipt shown; **IF** the file is malformed **→ THEN** it is rejected inline and nothing is queued.
|
|
74
|
+
|
|
75
|
+
### Concrete Example
|
|
76
|
+
|
|
77
|
+
> Plan expands from design.
|
|
78
|
+
|
|
79
|
+
**Setup:** [User role, existing state, context]
|
|
80
|
+
|
|
81
|
+
**Steps:**
|
|
82
|
+
|
|
83
|
+
1. User [does X] → System [responds with Y]
|
|
84
|
+
2. User [does X] → System [responds with Y]
|
|
85
|
+
3. …
|
|
86
|
+
|
|
87
|
+
**Outcome:** [End state the user sees that proves success]
|
|
88
|
+
|
|
89
|
+
### Edge Cases
|
|
90
|
+
|
|
91
|
+
> Plan expands from design's Key Edge Cases.
|
|
92
|
+
|
|
93
|
+
<!-- prettier-ignore -->
|
|
94
|
+
| Scenario | Expected Behavior |
|
|
95
|
+
| --- | --- |
|
|
96
|
+
| [Inherited from design Key Edge Cases and plan-added cases] | [Specific behavior] |
|
|
97
|
+
| [e.g., concurrent edit from another device] | [e.g., last-write-wins, no crash] |
|
|
98
|
+
|
|
99
|
+
### Derived Test Matrix
|
|
100
|
+
|
|
101
|
+
> Each row → one Agent Execution Runbook task. Assign tier(s) via **tier-selection rubric** in `docs/testing.md` (behaviour may need more than one). Boundary rows use that doc's rigor — reach real boundary, assert ground-truth signal, `@live` for external / deployed boundaries; do not restate those rules here.
|
|
102
|
+
>
|
|
103
|
+
> **Discrimination (no false-green):** assertion MUST hit the **affected** surface and FAIL if behaviour broken — not transport status (200/201), not proxy surfaces, never mock away the boundary under test.
|
|
104
|
+
|
|
105
|
+
**Tier Key** — use these exact tier names in the `Type` column (they must match `docs/testing.md`); pick the **lowest tier that actually exercises** the behaviour (a behaviour may need several):
|
|
106
|
+
|
|
107
|
+
<!-- prettier-ignore -->
|
|
108
|
+
| Tier | Use for | Example behaviour |
|
|
109
|
+
| --- | --- | --- |
|
|
110
|
+
| **Static** | every change — type / lint / format / prose / drift (global gate, not a per-feature row) | `tsc`, lint, and `bkit check` pass on the changed files |
|
|
111
|
+
| **Unit** | pure function / single module, no I/O | service parses a payload correctly |
|
|
112
|
+
| **Integration** | crosses a LOCAL stateful boundary (own DB / API), no mocks at the boundary, fresh instance | API endpoint enforces tenant isolation against a fresh local instance |
|
|
113
|
+
| **@live (golden)** | crosses an EXTERNAL / DEPLOYED boundary (3rd-party API, model, payment, deployed schema, RLS) — reach it, assert a ground-truth signal | a real 3rd-party API returns content and a boundary-only identity |
|
|
114
|
+
| **E2E** | user-visible UI flow / DOM state | user creates an event and sees it in the list |
|
|
115
|
+
| **fresh-DB replay** | new / changed migration or seed (`bkit-tests-migration`) | migration replays from empty and the seed loads |
|
|
116
|
+
| **Smoke** | post-deploy health of a deployed surface (global observability gate) | deployed health route returns 200 |
|
|
117
|
+
|
|
118
|
+
One row per behaviour (copy the tier name from the key above verbatim into `Type`):
|
|
119
|
+
|
|
120
|
+
<!-- prettier-ignore -->
|
|
121
|
+
| Test description | Type | Target file |
|
|
122
|
+
| --- | --- | --- |
|
|
123
|
+
| [e.g., Happy path: user creates event, sees it in list] | E2E | [e.g. `apps/web/e2e/[feature].spec.ts`] |
|
|
124
|
+
| [e.g., Service correctly parses payload] | Unit | [e.g. `packages/[pkg]/[module].test.ts`] |
|
|
125
|
+
| [e.g., API endpoint enforces tenant isolation] | Integration | [e.g. `packages/api/[feature].integration.test.ts`] |
|
|
126
|
+
| [e.g., Real 3rd-party API returns expected shape and a boundary-only identity — not "did not throw"] | @live (golden) | [e.g. `packages/[pkg]/[feature].live.test.ts`] |
|
|
127
|
+
| [e.g., New migration replays from empty and seed loads] | fresh-DB replay | [e.g. `supabase/migrations/*`] (replayed by `bkit-tests-migration`) |
|
|
128
|
+
|
|
129
|
+
### 👤 ✅ Human Confirmation
|
|
130
|
+
|
|
131
|
+
- [ ] **Acceptance Scenario confirmed:** I have reviewed the Narrative, Success Criteria, Process Sketch, Concrete Example, Edge Cases, and Derived Test Matrix above. They correctly describe what "done" looks like.
|
|
132
|
+
|
|
133
|
+
> [!CAUTION]
|
|
134
|
+
> **Agent:** Do not pass Gate 1 until this checkbox is `[x]`.
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## 👤 ⚠️ Breaking Changes & Naming Review
|
|
139
|
+
|
|
140
|
+
> [!CAUTION]
|
|
141
|
+
> **🛑 HUMAN must READ and CONFIRM this SECTION.**
|
|
142
|
+
> Review proposed names and breaking changes below.
|
|
143
|
+
|
|
144
|
+
[Proposed names: pages, files, DB tables, routes, API contracts. Breaking changes, DB structure diffs, global layout changes. Use IMPORTANT/WARNING/CAUTION alerts. If none, write "None"; initially set to `PENDING`.]
|
|
145
|
+
|
|
146
|
+
### 👤 ✅ Human Confirmation
|
|
147
|
+
|
|
148
|
+
- [ ] **Breaking Changes confirmed:** I have reviewed all breaking changes and naming decisions above.
|
|
149
|
+
|
|
150
|
+
> [!CAUTION]
|
|
151
|
+
> **Agent:** Do not pass Gate 1 until this checkbox is `[x]`.
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## 👤 ⚠️ Open Questions & Assumptions
|
|
156
|
+
|
|
157
|
+
> [!CAUTION]
|
|
158
|
+
> **🛑 HUMAN must READ and CONFIRM this SECTION.**
|
|
159
|
+
> Unknowns + assumptions this plan relies on. Unresolved question = risk; wrong assumption breaks downstream. If none, write "None".
|
|
160
|
+
> **Never a bare question.** Each carries 2-3 options, a recommendation, and default if unanswered — human must decide from the page alone. Canonical plan shape.
|
|
161
|
+
> Design → carry its options / recommendation forward where already answered.
|
|
162
|
+
|
|
163
|
+
- **Assumption:** [what the plan takes as given] → [what breaks if it's wrong]
|
|
164
|
+
- **Open Question:** [decision needed] → [who / how to resolve]
|
|
165
|
+
- **Options:** A — [option, trade-off] · B — [option, trade-off] · C — [option, trade-off, optional]
|
|
166
|
+
- **Recommended:** [A] — [why, 1 line]
|
|
167
|
+
- **Default if unanswered:** [what the agent proceeds with]
|
|
168
|
+
|
|
169
|
+
### 👤 ✅ Human Confirmation
|
|
170
|
+
|
|
171
|
+
- [ ] **Open Questions & Assumptions confirmed:** I have resolved or explicitly accepted every open question and assumption above.
|
|
172
|
+
|
|
173
|
+
> [!CAUTION]
|
|
174
|
+
> **Agent:** Do not pass Gate 1 until this checkbox is `[x]`.
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## Alternative Approaches & Recommendations
|
|
179
|
+
|
|
180
|
+
[Document rejected paths and why. List future phase recommendations; initially set to `PENDING`.]
|
|
181
|
+
|
|
182
|
+
**Selection Rule:** pick the approach with the best quality-of-end-state, not the smallest diff / lowest cost-of-change. In-scope work = complete or explicitly moved to `Out of Scope` — no 90% solutions or silent shortcuts.
|
|
183
|
+
|
|
184
|
+
## Out of Scope
|
|
185
|
+
|
|
186
|
+
[Features / fixes excluded to prevent scope creep. Every exclusion is `Exempt` per the rule below, with a reason and a home. If none, write "None"; initially set to `PENDING`.]
|
|
187
|
+
|
|
188
|
+
<!-- prettier-ignore -->
|
|
189
|
+
| Excluded item | Why `Exempt` | Where it belongs |
|
|
190
|
+
| --- | --- | --- |
|
|
191
|
+
| [feature/fix] | [why genuinely-additive] | [design non-goal / follow-up #N / future phase] |
|
|
192
|
+
|
|
193
|
+
> [!CAUTION]
|
|
194
|
+
> **Default = in-scope.** `Exempt` only if genuinely-additive — not required by `Success Criteria`, `Acceptance Scenario` / `Derived Test Matrix` row, or design (non-goals excepted). Required items → runbook task, never deferral; parking here = `Blocking` deferral → plan review / scope-check pulls back. Mirror each `Exempt` row in `docs/deferrals.jsonl`. Audit `LOW` → `Exempt` rows here.
|
|
195
|
+
|
|
196
|
+
## Suggested Scope Expansion
|
|
197
|
+
|
|
198
|
+
[Prior work overlapping this plan's surfaces — related open issues, `docs/deferrals.jsonl` deferrals, `docs/failures.jsonl` failures, audit findings the input did not name — surfaced as candidate expansions for the human. Fold `docs/deferrals.jsonl` and `docs/failures.jsonl` ledgers by `key`, highest `ts` wins → read only winning rows where `status` is not `CLOSED`; never read any other rows. If none, write "None"; initially set to `PENDING`.]
|
|
199
|
+
|
|
200
|
+
<!-- prettier-ignore -->
|
|
201
|
+
| Candidate | Source | Overlaps | Recommendation |
|
|
202
|
+
| --- | --- | --- | --- |
|
|
203
|
+
| [what it is] | [`#N` / `docs/deferrals.jsonl` / `docs/failures.jsonl` / audit finding id] | [surface / task it touches] | [fold in / keep deferred / needs design decision] |
|
|
204
|
+
|
|
205
|
+
> [!CAUTION]
|
|
206
|
+
> **Candidates, not scope.** Human review only — not runbook tasks, must not expand scope. Fold in only on design scope or explicit human decision → becomes task, leaves list.
|
|
207
|
+
|
|
208
|
+
## Security & Privacy
|
|
209
|
+
|
|
210
|
+
> Reference: `docs/security.md`. Check all that apply; skip inapplicable rows.
|
|
211
|
+
|
|
212
|
+
- [ ] **New API Route** — auth guard applied (e.g. a `requireMember`-style check)? Rate-limited if auth-adjacent?
|
|
213
|
+
- [ ] **New DB Table/Column** — row / tenant access policy deny-by-default (e.g. RLS)? Tenant-scoped (e.g. via a membership join)?
|
|
214
|
+
- [ ] **Role-Gated Mutation** — role checked at the API layer (not data-layer policy alone)?
|
|
215
|
+
- [ ] **User Input** — validated by a schema (e.g. Zod) with `parse()` called in the handler?
|
|
216
|
+
- [ ] **PII** — absent from logs? Audit/CDC trigger updated if a new column lands on a monitored table?
|
|
217
|
+
- [ ] **Redirect URL** — validated against an allow-list?
|
|
218
|
+
- [ ] **Webhook** — signature verified? Secret declared in the env schema?
|
|
219
|
+
- [ ] **New Secret/Env Var** — added to the env schema? Stored in the project's secret manager (e.g. GCP Secret Manager / Vercel env)?
|
|
220
|
+
|
|
221
|
+
_If none apply: "None — no new routes, DB writes, secrets, or user input."_
|
|
222
|
+
|
|
223
|
+
## Pre-Flight / Dependencies
|
|
224
|
+
|
|
225
|
+
**CRITICAL:** Check off all core items. Check conditional items only when applicable. Abort if anything required is missing.
|
|
226
|
+
|
|
227
|
+
### Core
|
|
228
|
+
|
|
229
|
+
Always verify.
|
|
230
|
+
|
|
231
|
+
- [ ] **Package Management:** Required packages declared; dependency manifest + lockfile in sync (e.g. `package.json` + `pnpm-lock.yaml`, `pyproject.toml` + `uv.lock`).
|
|
232
|
+
- [ ] **Dependency Versions:** Run `pnpm bkit:deps:outdated`; spot-check toolchain + stack CLI versions (e.g. `npx tsc --version`, `pnpm --version`, `npx supabase --version`). Flag outdated deps that may silently block implementation — infra errors often = CLI vs backend version mismatch.
|
|
233
|
+
- [ ] **Existing-Solution Search (reuse over duplicate):** per capability, three sweeps → `Reuse Inventory`: in-repo (text search for names / strings / near-miss helpers / sibling modules; symbol references via language server when configured; `docs/capabilities.md` when present), dependency (`{framework} {capability} built-in`), ecosystem (`{problem} best practice {current year}`). Empty language-server / capability-map result = inconclusive — absence needs text search. Unrecorded = unsearched. Drives `[MODIFY]` vs `[NEW]`.
|
|
234
|
+
- [ ] **User Context:** Verify read / write access to required files. Request missing user information up front.
|
|
235
|
+
- [ ] **Project Context:** Fold `docs/knowledge.jsonl` and `docs/decisions.jsonl` each by `key`, highest `ts` wins → read only winning rows where `status` is `ACTIVE` or absent; never read any other rows. Check for relevant patterns, decisions, gotchas.
|
|
236
|
+
- [ ] **Testing & Quality:** Ensure testing strategy aligns with `docs/testing.md`.
|
|
237
|
+
- [ ] **Prerequisite Plans:** List `docs/plans/...` plans that must be fully executed and verified before this one.
|
|
238
|
+
|
|
239
|
+
### Conditional
|
|
240
|
+
|
|
241
|
+
Verify only when applicable.
|
|
242
|
+
|
|
243
|
+
- [ ] **Secrets & Env Vars:** New API keys or third-party credentials → verify the project's secret store (e.g. GCP Secret Manager, Vercel env vars) and any service-account / IAM roles.
|
|
244
|
+
- [ ] **Schema State:** Any DB reads or writes → confirm exact database state against `docs/data-schema.md` before finalizing data-access logic.
|
|
245
|
+
- [ ] **Architecture & UI:** New files / routes / UI → `docs/architecture.md` topology; UI/mobile → `docs/design.md`; consult named reference repos.
|
|
246
|
+
- [ ] **Observability:** New logs / audit tables / traces → align with `docs/observability.md` (e.g. structured logger calls, correlation IDs, CDC / OTel).
|
|
247
|
+
- [ ] **Notifications:** Alerts / toasts → notifications doc via `.agents/docs.md` for tier (e.g. 1=inline, 2=toast, 3=bell).
|
|
248
|
+
|
|
249
|
+
### 🔒 Gate 1: Prerequisites Check
|
|
250
|
+
|
|
251
|
+
**CRITICAL AI AGENT INSTRUCTION:** 🛑 CHECKPOINT — `[x]` all applicable boxes above. **do not stop for user permission.** Proceed to `Data Schema Integration`.
|
|
252
|
+
|
|
253
|
+
- [ ] **Acceptance Scenario confirmed:** Human confirmed `👤 Acceptance Scenario` section (checkbox is `[x]`).
|
|
254
|
+
- [ ] **Breaking Changes confirmed:** Human confirmed `⚠️ Breaking Changes & Naming Review` section (checkbox is `[x]`).
|
|
255
|
+
- [ ] **Open Questions confirmed:** Human confirmed `👤 Open Questions & Assumptions` section (checkbox is `[x]`).
|
|
256
|
+
- [ ] **Security & Privacy checked:** All applicable `Security & Privacy` rows verified (or "None" justified).
|
|
257
|
+
- [ ] **Reuse Inventory complete:** every capability has a row with non-empty `Search performed` + `Decision`; every `NEW` cites an allowed reason.
|
|
258
|
+
- [ ] **Gate 1 - Verified:** All Core items checked. All applicable Conditional items checked.
|
|
259
|
+
|
|
260
|
+
## Data Schema Integration
|
|
261
|
+
|
|
262
|
+
[Define how this feature interacts with the existing database schema and what changes are required; initially set to `PENDING`.]
|
|
263
|
+
|
|
264
|
+
**Invariant Conformance:** Multi-store or privileged writes → every mutation path maintains every store a read surface depends on, under a compatible privilege, with the returned error actually checked (never swallowed). If a write can fail on privilege/constraint, the plan says how that failure surfaces — not a silent 200.
|
|
265
|
+
|
|
266
|
+
### Data Schema Usage
|
|
267
|
+
|
|
268
|
+
[List all existing `docs/data-schema.md` tables and fields that this feature will read from (Input) or write to (Output); initially set to `PENDING`. e.g.,
|
|
269
|
+
|
|
270
|
+
- **Input (Read):** `users.id`, `items.title`
|
|
271
|
+
- **Output (Write):** `items.status`, `job_audits.log`]
|
|
272
|
+
If no existing fields are used, explicitly state "None".
|
|
273
|
+
|
|
274
|
+
### Data Schema Changes
|
|
275
|
+
|
|
276
|
+
[List any new tables, new fields, or modifications to existing fields that need to be recorded in `docs/data-schema.md`; initially set to `PENDING`. e.g.,
|
|
277
|
+
|
|
278
|
+
- **ADD:** `items.new_field` (type: text)
|
|
279
|
+
- **MODIFY:** `users.role` (added enum value)]
|
|
280
|
+
If no schema changes are required, explicitly state "None".
|
|
281
|
+
|
|
282
|
+
## Reuse Inventory
|
|
283
|
+
|
|
284
|
+
[One row per capability plan introduces, including those search cleared as absent. Author before `Architecture & Component Changes`. No capability → no rows; "None" never substitutes for searching. Design `Reuse & Prior Art` verdicts = starting point; every row still records its own `Search performed`; initially set to `PENDING`.]
|
|
285
|
+
|
|
286
|
+
<!-- prettier-ignore -->
|
|
287
|
+
| Capability | Search performed | Existing candidates | Decision | Justification |
|
|
288
|
+
| --- | --- | --- | --- | --- |
|
|
289
|
+
| [what the plan must do] | `grep -rn "..."`; references to `{symbol}`; `docs/capabilities.md`; `{framework} {capability} built-in` | `path/to/existing` — covers [X], missing [Y] | EXTEND | [what changes in it to close the gap] |
|
|
290
|
+
| [capability] | [exact commands / queries run] | None — [what was searched] | new | [reason (a)/(b)/(c)] |
|
|
291
|
+
|
|
292
|
+
> [!CAUTION]
|
|
293
|
+
> **Default = `EXTEND`.** `NEW` only allowed for:
|
|
294
|
+
> (a) no candidate — `Search performed` shows the commands establishing absence;
|
|
295
|
+
> (b) extending breaks the candidate's contract or callers — name both;
|
|
296
|
+
> (c) candidate is a `Supersession Inventory` `DELETE` — replacement, not duplicate.
|
|
297
|
+
>
|
|
298
|
+
> never accept cleaner-fresh / messy-existing / close-but-different as a `NEW` reason — messy candidate → extend and clean it, in scope. Empty `Search performed` = UNSEARCHED, not `NEW`-eligible.
|
|
299
|
+
>
|
|
300
|
+
> Each `EXTEND` row must land as `[MODIFY] path/to/existing` in `Architecture & Component Changes` and a task in `Agent Execution Runbook`; each `NEW` row as `[NEW]` carrying the same reason. `[NEW]` with no row = unjustified.
|
|
301
|
+
|
|
302
|
+
## Architecture & Component Changes
|
|
303
|
+
|
|
304
|
+
[Group files logically (DB, API, Backend, Frontend, Cron, Observability). Separate by headers; initially set to `PENDING`.]
|
|
305
|
+
**CRITICAL:** Justify new file locations per `docs/architecture.md` topology.
|
|
306
|
+
**CRITICAL:** Prefer `[MODIFY]` over `[NEW]`. Every `[NEW]` must trace to a `Reuse Inventory` `NEW` row and carry its reason — no parallel reimplementation. Superseded → `Supersession Inventory` as `DELETE`.
|
|
307
|
+
**CRITICAL:** Frontend/Mobile → adhere to `docs/design.md`.
|
|
308
|
+
**CRITICAL:** Verify `[MODIFY]` files exist (else `[NEW]`). Before changing exported symbol/signature/contract: find callers/importers/schemas/consumers (language-server references when configured + text search), list blast radius.
|
|
309
|
+
**CRITICAL:** Include backend actions for new schema validations (e.g. Zod `schema.parse`).
|
|
310
|
+
**CRITICAL:** NEVER weaken gate to pass: no type-system escapes (e.g. TS `as any` / `as unknown as` / `@ts-ignore`, Python `# type: ignore`), linter disables (e.g. `eslint-disable`, `//nolint`), test skips (e.g. `.skip`, `xfail`), deleted assertions, empty `catch` / error-swallowing, mocking-away unit under test. Fix root causes; per-file opt-out needs explicit human sign-off.
|
|
311
|
+
**CRITICAL:** Auto-capture (e.g. log drains / CDC) does not replace explicit logging — log edge cases escaping auto-capture with the project's structured logger (e.g. `console.error("[Context] Message", payload)`). See `docs/observability.md` for naming, severity, correlation IDs, label taxonomy.
|
|
312
|
+
|
|
313
|
+
### Database Migrations
|
|
314
|
+
|
|
315
|
+
[Define new tables / columns / access policies (e.g. RLS) with your migration tool (e.g. `db:diff`). **NEVER apply to shared remotes by hand** (e.g. `db push` to Dev/Main) — CI's migration lane applies them; see `docs/deployments.md` § Applying migrations at deploy time; initially set to `PENDING`.]
|
|
316
|
+
|
|
317
|
+
> [!WARNING]
|
|
318
|
+
> **If adding/removing columns on CDC/audit-monitored tables (e.g. `users` and the other tenant tables your project monitors):**
|
|
319
|
+
>
|
|
320
|
+
> 1. Update the monitored-column allow-list in the schema-assurance test (e.g. a `knownSafeColumns` list).
|
|
321
|
+
> 2. If a column contains PII → update the audit trigger to scrub it.
|
|
322
|
+
> 3. See `docs/data-schema.md` for the full checklist.
|
|
323
|
+
|
|
324
|
+
### [Component Area 1]
|
|
325
|
+
|
|
326
|
+
[Summary of component changes; initially set to `PENDING`.]
|
|
327
|
+
|
|
328
|
+
#### [MODIFY] `path/to/file.ext`
|
|
329
|
+
|
|
330
|
+
- **Existence Check:** [Verify file exists first.]
|
|
331
|
+
- [Detail logic, schema, or API contracts.]
|
|
332
|
+
|
|
333
|
+
#### [new] `path/to/file.ext`
|
|
334
|
+
|
|
335
|
+
- **Reuse Check:** [`Reuse Inventory` row + reason (a)/(b)/(c) — why no existing artifact can be evolved.]
|
|
336
|
+
- [Detail purpose, access policies (e.g. RLS), input validation (e.g. Zod), naming.]
|
|
337
|
+
|
|
338
|
+
#### [DELETE] `path/to/file.ext`
|
|
339
|
+
|
|
340
|
+
- [Reason]
|
|
341
|
+
|
|
342
|
+
### Cron Jobs & Scheduled Tasks
|
|
343
|
+
|
|
344
|
+
[Define scheduled tasks (e.g. Vercel cron, pg_cron, Inngest). Record them in the project's cron/scheduled-jobs doc if it has one (resolve via `.agents/docs.md`); initially set to `PENDING`.]
|
|
345
|
+
|
|
346
|
+
## Supersession Inventory
|
|
347
|
+
|
|
348
|
+
[Existing artifacts the new code replaces — shared triggers/routes, redundant exports, etc. If plan adds without replacing, write "None"; initially set to `PENDING`.]
|
|
349
|
+
|
|
350
|
+
<!-- prettier-ignore -->
|
|
351
|
+
| Existing artifact | Replaced by | Decision | Justification |
|
|
352
|
+
| --- | --- | --- | --- |
|
|
353
|
+
| `path/to/old-thing` | `path/to/new-thing` | DELETE | [reason] |
|
|
354
|
+
|
|
355
|
+
> [!CAUTION]
|
|
356
|
+
> **Default = `DELETE`.** `RETAIN-WITH-REASON` only allowed for:
|
|
357
|
+
> (a) external contract — atomic migration impossible (third-party callers, public API);
|
|
358
|
+
> (b) staged rollout with kill-date and follow-up issue link.
|
|
359
|
+
>
|
|
360
|
+
> never accept `@deprecated` and still exported as a resolution. Each `DELETE` row must be mirrored as `[DELETE] path/to/file` in `Architecture & Component Changes` and as a removal task in `Agent Execution Runbook`.
|
|
361
|
+
|
|
362
|
+
## Documentation Updates
|
|
363
|
+
|
|
364
|
+
> Docs this change touches only; delete rest. Core below; others via `.agents/docs.md`. Code-change treatment — rewrite prose, no lazy bullet appends.
|
|
365
|
+
|
|
366
|
+
<!-- prettier-ignore -->
|
|
367
|
+
| Doc | Change required |
|
|
368
|
+
| --- | --- |
|
|
369
|
+
| `docs/knowledge.jsonl` | [learnings, gotchas] |
|
|
370
|
+
| `docs/decisions.jsonl` | [architecture decisions] |
|
|
371
|
+
| `docs/architecture.md` | [topology / component changes] |
|
|
372
|
+
| `docs/technology.md` | [frameworks, libraries, conventions] |
|
|
373
|
+
| `docs/data-schema.md` | [new tables / columns] |
|
|
374
|
+
| `docs/design.md` | [palette, typography, components] |
|
|
375
|
+
| `docs/testing.md` | [new test files / patterns] |
|
|
376
|
+
| `docs/observability.md` | [new log names / spans] |
|
|
377
|
+
|
|
378
|
+
_Delete rows with no change; add a row per other affected doc (resolve via `.agents/docs.md`)._
|
|
379
|
+
|
|
380
|
+
## Rollback Strategy
|
|
381
|
+
|
|
382
|
+
<!-- prettier-ignore -->
|
|
383
|
+
| Axis | Action | Notes |
|
|
384
|
+
| --- | --- | --- |
|
|
385
|
+
| **DB** | [Corrective migration that undoes the change; safe if additive-only] | merged migrations are immutable — ship the corrective migration through CI's migration lane; dev full reset → `docs/deployments.md` § Dev rollback runbook |
|
|
386
|
+
| **Code** | [Git revert SHA or feature flag to disable] | `git revert {COMMIT}` |
|
|
387
|
+
| **Risk window** | [Gap between DB migration merge and code deploy] | [e.g., "~2 min Vercel build — migration must be additive"] |
|
|
388
|
+
|
|
389
|
+
_No DB changes: "Code-only — `git revert` sufficient."_
|
|
390
|
+
|
|
391
|
+
## Agent Execution Runbook
|
|
392
|
+
|
|
393
|
+
[Chronological, step-by-step checklist guiding implementation. **MANDATORY**; initially set to `PENDING`.]
|
|
394
|
+
|
|
395
|
+
> [!IMPORTANT]
|
|
396
|
+
> **Continuous Execution:** Run runbook autonomously; no user permission at Gates; `[x]` as you go.
|
|
397
|
+
> **Step Isolation:** Finish task (verify + checkbox) before next.
|
|
398
|
+
> **Integration Shape:** may suggest PR / commit / sequencing — advisory, never a gate; one PR for all tasks always OK. Do not specify merge method.
|
|
399
|
+
|
|
400
|
+
**Implementation Tasks (Examples):**
|
|
401
|
+
|
|
402
|
+
> Every task MUST include `**Done when:**` — terse, testable, codebase-verifiable (file exists / signature matches / test passes / behaviour observable). Plan-verify asserts before `[x]`. No task without `Done when:`. One task per in-scope audit finding id; group only on one shared root cause in report — every id still named.
|
|
403
|
+
>
|
|
404
|
+
> **Tests ship with their task.** Task adding / changing logic → names its own unit tests in `Done when`, matrix row or not; tests it breaks → fixed in same task. never defer task tests to later tasks to avoid splits that leave untested code and drop coverage gates.
|
|
405
|
+
>
|
|
406
|
+
> **Build order and test source.** Order tasks by build dependency (schema → API → UI). Behaviour tests only from `Derived Test Matrix` rows — do not invent. Boundary-crossing tasks (DB / API / model / network / migration) carry paired non-mock `Done when` tests; pure-function tasks exempt from pairing, not from unit tests.
|
|
407
|
+
|
|
408
|
+
- [ ] **Task 1:** [e.g., Create DB migration (`npx supabase db diff`)]. **Done when:** [e.g., `supabase/migrations/{timestamp}_add_items_status.sql` exists; `npx supabase db push --local` applies cleanly].
|
|
409
|
+
- [ ] **Task 2:** [e.g., Implement backend API action `action.ts`]. **Done when:** [e.g., `packages/api/src/items/setStatus.ts` exports `setStatus` with Zod-validated input; unit test `packages/api/src/items/setStatus.test.ts` covers each status transition; integration test in `packages/api/items.integration.test.ts` passes].
|
|
410
|
+
- [ ] **Task 3:** [e.g., Update React component `page.tsx`]. **Done when:** [e.g., `apps/web/app/items/page.tsx` renders status badge; Playwright spec `apps/web/e2e/items.spec.ts` confirms user-visible state].
|
|
411
|
+
|
|
412
|
+
### 🔒 Gate 2: Code Implementation Check
|
|
413
|
+
|
|
414
|
+
**CRITICAL AI AGENT INSTRUCTION:** 🛑 CHECKPOINT — `[x]` all boxes below. **do not stop for user permission.** Proceed to `Testing & Documentation`.
|
|
415
|
+
|
|
416
|
+
- [ ] **No bolt-on / no gate-weakening:** every `[NEW]` traces to a `Reuse Inventory` `NEW` row and its search still holds — reusable artifact found mid-build → add a row, fold code into it; every `EXTEND` landed as a modification of the named artifact, not a parallel file. No type-system escapes (e.g. TS `as any` / `as unknown as` / `@ts-ignore`, Python `# type: ignore`), linter disables (e.g. `eslint-disable`, `//nolint`), test skips (e.g. `.skip`, `xfail`), empty `catch` / error-swallowing introduced to make a gate pass.
|
|
417
|
+
- [ ] **Gate 2 - Verified:** Every checkbox above independently verified and checked off against the plan.
|
|
418
|
+
|
|
419
|
+
> [!IMPORTANT]
|
|
420
|
+
> **Testing Strategy** (see `docs/testing.md`):
|
|
421
|
+
>
|
|
422
|
+
> - **Backend / pipeline logic** — test at the unit/integration tier (e.g. Vitest), not through a browser. Mock HTTP and assert against the real datastore natively.
|
|
423
|
+
> - **End-to-end integration** — core data paths need at least 1 integration test firing the real API against a local DB _without_ ORM/DB mocking.
|
|
424
|
+
> - **UI E2E (browser or device) for UI only** (e.g. Playwright) — don't drive a UI for non-visual logic.
|
|
425
|
+
>
|
|
426
|
+
> **UI E2E Conventions** — test-auth + data-factory per `docs/testing.md`: shared `setup` logs in once, reuses auth state (sign-in / sign-up / account-deletion tests opt out); typed factories with per-test overrides, not inline strings.
|
|
427
|
+
|
|
428
|
+
**Mandatory Tasks (Testing & Documentation):**
|
|
429
|
+
|
|
430
|
+
- [ ] **Verify test coverage against Derived Test Matrix:** Each `Acceptance Scenario → Derived Test Matrix` row → one runbook task whose `Done when` carries its test; gaps → add to that task, not here.
|
|
431
|
+
- [ ] **Sweep existing tests:** Each task fixed the tests it broke; full suite green per `docs/testing.md`. Fix only what tasks missed.
|
|
432
|
+
- [ ] **Sweep new tests:** Each task's `Done when` tests exist and pass per Testing Strategy; add only what tasks missed — not where tests are first written. Reuse data factories + auth conventions (above) for UI E2E tests.
|
|
433
|
+
- [ ] **Verify observability:** Observable per `docs/observability.md` — errors logged via the project's structured logger (e.g. `console.error("[Context] Message", payload)`), correlation IDs through pipeline, audit coverage on monitored tables where the project has it (e.g. audit / CDC triggers); update doc for new log names / labels / tracing scopes.
|
|
434
|
+
- [ ] **Update documentation:** Integrate logic/schemas into affected docs — `docs/architecture.md`, `docs/data-schema.md`, `docs/knowledge.jsonl`, `docs/decisions.jsonl`, others via `.agents/docs.md`. Rewrite ground-truth prose; do not append lazy bullet points.
|
|
435
|
+
|
|
436
|
+
### 🔒 Gate 3: Testing & Documentation Check
|
|
437
|
+
|
|
438
|
+
**CRITICAL AI AGENT INSTRUCTION:** 🛑 CHECKPOINT — `[x]` all boxes below. **do not stop for user permission.** Proceed to `Verification Plan`.
|
|
439
|
+
|
|
440
|
+
- [ ] **Docs updated:** Every row in `Documentation Updates` completed. `.agents/docs.md` still accurate.
|
|
441
|
+
- [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
|
|
442
|
+
|
|
443
|
+
## Verification Plan
|
|
444
|
+
|
|
445
|
+
> [!IMPORTANT]
|
|
446
|
+
> **Advisory build-phase checks, not merge gates.** Only `Agent Execution Runbook` `Done when` lines gate merge; nothing here does. Do not write "before merge" on untickable boxes — CI/human-only preconditions (lane RUN, deployed state, operator step) unenforceable. Work that MUST block merge → runbook task + codebase-verifiable `Done when`; lane that must run → CI config, not plan prose.
|
|
447
|
+
|
|
448
|
+
### Automated Tests
|
|
449
|
+
|
|
450
|
+
- [ ] **Full Local Gate Suite:** Full local gates — deepest declared `bkit:gate:*` script up to integration (`pnpm bkit:gate:static-unit-integration`, else `pnpm bkit:gate:static-unit`; e.g. typecheck, lint, `format:check`, prose, `slop:delta`, unit, in-process integration) + `bkit check`. Do not weaken gates (anti-suppression CRITICAL under Architecture & Component Changes).
|
|
451
|
+
- [ ] **Test Synchronization:** [List existing E2E tests (e.g. Playwright) to update synchronously to prevent CI failures.]
|
|
452
|
+
- [ ] **Build Configuration:** [Keep new test-only files (mocks, test configs) out of the production build (e.g. `tsconfig.json` `exclude`).]
|
|
453
|
+
- [ ] **[Test Type] (`path/to/test.spec.ts`):** [Describe flows/unit/E2E additions. Note data hygiene needs.]
|
|
454
|
+
- [ ] **Apply local migrations:** New migrations → apply locally (e.g. `npx supabase db push --local`); else integration tests fail on stale schema.
|
|
455
|
+
- [ ] **Run all tests:** Local unit + integration (e.g. `pnpm test`, `pnpm test:integration`); fix failures before Gate 4.
|
|
456
|
+
|
|
457
|
+
> [!IMPORTANT]
|
|
458
|
+
> **No Architectural Downgrades:** Build / compiler / test errors during verification → never hot-fix or anti-pattern; follow `docs/architecture.md` + named reference repos. Halt if stuck.
|
|
459
|
+
|
|
460
|
+
### 🔒 Gate 4: Automated Verification Check
|
|
461
|
+
|
|
462
|
+
**CRITICAL AI AGENT INSTRUCTION:** 🛑 CHECKPOINT — `[x]` all boxes below. **do not stop for user permission.** Proceed to `Manual Verification`.
|
|
463
|
+
|
|
464
|
+
- [ ] **Gate 4 - Verified:** Every checkbox in Automated Tests independently verified and checked off. Explicit proof (test outputs, CLI results, API responses) gathered.
|
|
465
|
+
|
|
466
|
+
### 👤 Manual Verification
|
|
467
|
+
|
|
468
|
+
> [!CAUTION]
|
|
469
|
+
> **Owner-run acceptance checks — advisory only.** Run during build wherever a CLI can (Dashboard Ban below). An unticked box blocks nothing: not the merge, not plan approval. This is not a Gate 1 human-confirmation section.
|
|
470
|
+
|
|
471
|
+
> [!WARNING]
|
|
472
|
+
> **Dashboard Ban:** Proactively use local CLIs (e.g. `gh`, `vercel`, `npx supabase`) to verify CI/CD pipelines instead of asking users to check dashboards.
|
|
473
|
+
|
|
474
|
+
- [ ] **Step 1:** [Instructions for agent/user to verify feature end-to-end via CLI/DB.]
|
|
475
|
+
|
|
476
|
+
<!-- bkit:end -->
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
// checks/after/auth.ts — credentials: the GitHub-MCP token, GitHub repo secrets (incl.
|
|
2
|
+
// the cloud router's), and the cloud-dashboard secrets checklist.
|
|
3
|
+
|
|
4
|
+
import * as fs from "node:fs";
|
|
5
|
+
import * as path from "node:path";
|
|
6
|
+
import { execSync } from "node:child_process";
|
|
7
|
+
import type { PreflightFinding } from "../before/index.js";
|
|
8
|
+
import { readConsumerCloudAgents } from "./github.js";
|
|
9
|
+
|
|
10
|
+
// ---------------------------------------------------------------------------
|
|
11
|
+
// Token-surface detectors
|
|
12
|
+
// ---------------------------------------------------------------------------
|
|
13
|
+
|
|
14
|
+
export type TokenPresence = "present" | "missing" | "empty" | "unknown";
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Detect whether BKIT_GH_TOKEN is set in the shell environment. Distinguishes
|
|
18
|
+
* empty from unset so action text can guide the user precisely. Never reads the
|
|
19
|
+
* token value beyond truthiness. BKIT_GH_TOKEN authenticates the GitHub MCP
|
|
20
|
+
* server (`Authorization: Bearer ${BKIT_GH_TOKEN}` in .mcp.json), which powers
|
|
21
|
+
* the entire tracker + PR + Projects MCP surface.
|
|
22
|
+
*/
|
|
23
|
+
export function detectShellGhMcpToken(): TokenPresence {
|
|
24
|
+
if (process.env.BKIT_GH_TOKEN === undefined) return "missing";
|
|
25
|
+
if (process.env.BKIT_GH_TOKEN === "") return "empty";
|
|
26
|
+
return "present";
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* True when a `github` MCP server is configured in `.mcp.json` or
|
|
31
|
+
* `.cursor/mcp.json` — i.e. BKIT_GH_TOKEN is actually consumed for MCP auth. Used to
|
|
32
|
+
* gate the BKIT_GH_TOKEN shell advisory so it never fires in repos that use bkit for
|
|
33
|
+
* CI only (no agent workflows / MCP servers).
|
|
34
|
+
*/
|
|
35
|
+
export function hasGithubMcpServer(cwd: string): boolean {
|
|
36
|
+
for (const rel of [".mcp.json", path.join(".cursor", "mcp.json")]) {
|
|
37
|
+
const p = path.join(cwd, rel);
|
|
38
|
+
if (!fs.existsSync(p)) continue;
|
|
39
|
+
try {
|
|
40
|
+
const cfg = JSON.parse(fs.readFileSync(p, "utf-8")) as Record<string, unknown>;
|
|
41
|
+
const servers = cfg.mcpServers as Record<string, unknown> | undefined;
|
|
42
|
+
if (servers?.github) return true;
|
|
43
|
+
} catch {
|
|
44
|
+
// Malformed config — ignore; a JSON-drift advisory covers that separately.
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
return false;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Detect whether a named secret is set on the consumer's GitHub repo.
|
|
52
|
+
* Returns "present" | "missing" | "unknown".
|
|
53
|
+
* "unknown" if gh CLI unavailable, unauthenticated, or not a GitHub repo.
|
|
54
|
+
*/
|
|
55
|
+
export function detectGhSecret(secretName: string): TokenPresence {
|
|
56
|
+
try {
|
|
57
|
+
const out = execSync(`gh secret list --json name -q '.[].name'`, {
|
|
58
|
+
encoding: "utf-8",
|
|
59
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
60
|
+
timeout: 5000,
|
|
61
|
+
});
|
|
62
|
+
const names = out
|
|
63
|
+
.split("\n")
|
|
64
|
+
.map((s) => s.trim())
|
|
65
|
+
.filter(Boolean);
|
|
66
|
+
return names.includes(secretName) ? "present" : "missing";
|
|
67
|
+
} catch {
|
|
68
|
+
return "unknown";
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Build the consolidated "three locations to sync secrets" advisory. Fires when
|
|
74
|
+
* the consumer's repo has bkit-cloud.yml installed OR a
|
|
75
|
+
* .claude/ or .cursor/ install present — both indicate cloud-side agent use,
|
|
76
|
+
* which means the same three secrets need to be set in three places (GitHub
|
|
77
|
+
* Actions, Cursor Settings online, Claude app web).
|
|
78
|
+
*
|
|
79
|
+
* Returns null when none of the three trigger paths exist.
|
|
80
|
+
*/
|
|
81
|
+
export function buildCloudDashboardsAdvisory(cwd: string): PreflightFinding | null {
|
|
82
|
+
const hasRouter = fs.existsSync(path.join(cwd, ".github", "workflows", "bkit-cloud.yml"));
|
|
83
|
+
const hasClaude = fs.existsSync(path.join(cwd, ".claude"));
|
|
84
|
+
const hasCursor = fs.existsSync(path.join(cwd, ".cursor"));
|
|
85
|
+
if (!hasRouter && !hasClaude && !hasCursor) return null;
|
|
86
|
+
|
|
87
|
+
// cloud=claude path (bkit-cloud.yml): GitHub-tracker only, ANTHROPIC_API_KEY only.
|
|
88
|
+
// cloud=cursor path (.cursor/): BKIT_LINEAR_API_KEY for Cursor dashboard.
|
|
89
|
+
// Distinguish by recorded variant; fall back to presence-based detection.
|
|
90
|
+
const recordedVariant = readConsumerCloudAgents(cwd);
|
|
91
|
+
const isCursorCloud = recordedVariant === "cursor" || (!hasRouter && hasCursor);
|
|
92
|
+
|
|
93
|
+
const secretList = isCursorCloud ? "`BKIT_LINEAR_API_KEY`" : "`ANTHROPIC_API_KEY`";
|
|
94
|
+
const ghSetLines = isCursorCloud
|
|
95
|
+
? " gh secret set BKIT_LINEAR_API_KEY --body='<value>'\n\n" +
|
|
96
|
+
" Verify: `gh secret list | grep -E 'BKIT_LINEAR_API_KEY'`\n\n"
|
|
97
|
+
: " gh secret set ANTHROPIC_API_KEY --body='<value>'\n\n" +
|
|
98
|
+
" Verify: `gh secret list | grep -E 'ANTHROPIC_API_KEY'`\n\n";
|
|
99
|
+
const vendorNote = isCursorCloud
|
|
100
|
+
? "BKIT_LINEAR_API_KEY is read from the Linear dashboard (https://linear.app/settings/api)."
|
|
101
|
+
: "ANTHROPIC_API_KEY is read from the Anthropic dashboard (https://console.anthropic.com/settings/keys); `.bkit/.env` holds the same value as BKIT_ANTHROPIC_API_KEY. The Claude GitHub App (`/install-github-app`) is also required for `cloud=claude`.";
|
|
102
|
+
return {
|
|
103
|
+
id: "cloud-secrets-three-locations",
|
|
104
|
+
severity: "advisory",
|
|
105
|
+
detect: `The secrets used by bkit's cloud integration (${secretList}) must also be set in the relevant cloud dashboards. Bkit cannot verify dashboard state — surface the checklist so you don't ship a half-configured cloud setup.`,
|
|
106
|
+
action:
|
|
107
|
+
"Set each secret in the required locations:\n\n" +
|
|
108
|
+
"1. **GitHub Actions** (used by bkit-cloud.yml and your own workflows):\n" +
|
|
109
|
+
ghSetLines +
|
|
110
|
+
"2. **Cursor Cloud Agents** (used by Cursor's cloud agent runner): open `https://cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab. Add each secret as a **Runtime Secret** (loaded as an env var, redacted from the agent's transcript). Cursor reads `.cursor/Dockerfile` + `.cursor/environment.json` from the repo but secrets come from this dashboard only; the resolved paste-ready values are in `.cursor/bkit-cloud.md` (gitignored).\n\n" +
|
|
111
|
+
"3. **Claude Code (web)** (used by Claude.ai's cloud agent runner): open `https://claude.ai/code` → Settings → Setup → Environment Variables. Add each secret. Claude reads its setup script from the dashboard, NOT from the repo, so changes here do not require a commit.\n\n" +
|
|
112
|
+
"**Context-fetch (`/bkit-debug` in the cloud):** if you run the debug workflow in these cloud agents, the observability creds your `.agents/context.md` context-fetch blocks use (e.g. `VERCEL_TOKEN`, `SUPABASE_ACCESS_TOKEN`) must ALSO be set in the same dashboards above — non-interactively, since headless agents cannot `vercel login`. These are operator/observability READ creds, not app-runtime secrets. Commit the non-secret selectors (team scope / project ref / `--environment`) in your copied block so they need no dashboard entry. The CLIs those blocks call install automatically in the cloud from each block's `context-fetch:provision` sibling — no manual setup.\n\n" +
|
|
113
|
+
"Same VALUE in all places. " +
|
|
114
|
+
vendorNote,
|
|
115
|
+
};
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Detect whether the GitHub Actions secrets `bkit-cloud.yml` needs are set.
|
|
120
|
+
* Only fires when `.github/workflows/bkit-cloud.yml` exists. `ANTHROPIC_API_KEY` is
|
|
121
|
+
* always required (claude-code-action) for the cloud=claude path. The workflow is
|
|
122
|
+
* GitHub-tracker only — no `BKIT_LINEAR_API_KEY` dependency. Returns one finding per
|
|
123
|
+
* missing secret.
|
|
124
|
+
*/
|
|
125
|
+
export function detectCiRouterSecrets(cwd: string): PreflightFinding[] {
|
|
126
|
+
const findings: PreflightFinding[] = [];
|
|
127
|
+
const routerPath = path.join(cwd, ".github", "workflows", "bkit-cloud.yml");
|
|
128
|
+
if (!fs.existsSync(routerPath)) return findings;
|
|
129
|
+
// bkit-cloud.yml is cloud=claude / GitHub-tracker only — ANTHROPIC_API_KEY (GHA secret
|
|
130
|
+
// name claude-code-action reads). Local `.bkit/.env` stores the same value as
|
|
131
|
+
// BKIT_ANTHROPIC_API_KEY. No BKIT_LINEAR_API_KEY dependency.
|
|
132
|
+
const required = ["ANTHROPIC_API_KEY"];
|
|
133
|
+
for (const name of required) {
|
|
134
|
+
const status = detectGhSecret(name);
|
|
135
|
+
if (status === "missing") {
|
|
136
|
+
findings.push({
|
|
137
|
+
id: `${name.toLowerCase().replace(/_/g, "-")}-secret-missing`,
|
|
138
|
+
severity: "advisory",
|
|
139
|
+
detect: `gh secret list confirms ${name} secret is NOT set on this GitHub repo.`,
|
|
140
|
+
action:
|
|
141
|
+
`\`.github/workflows/bkit-cloud.yml\` requires ${name} to invoke its Claude Code action. Without it, the workflow exits no-op.\n\nSet the secret:\n\n` +
|
|
142
|
+
` gh secret set ${name} --body='<paste-value-here>'\n\n` +
|
|
143
|
+
`Then verify: \`gh secret list | grep ${name}\`. The workflow itself does not need redeploying — secrets are read at run time.`,
|
|
144
|
+
});
|
|
145
|
+
}
|
|
146
|
+
// "unknown" → silent skip (CLI absent / unauthenticated).
|
|
147
|
+
}
|
|
148
|
+
return findings;
|
|
149
|
+
}
|