@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,471 @@
|
|
|
1
|
+
# Templates — copy and own
|
|
2
|
+
|
|
3
|
+
{{BKIT_MANAGED_MARKER}}
|
|
4
|
+
|
|
5
|
+
> [!CAUTION]
|
|
6
|
+
> **Purpose:** Every template bkit ships and never installs — what each does, where to copy it, how to install the tool behind it.
|
|
7
|
+
>
|
|
8
|
+
> **Rules:**
|
|
9
|
+
>
|
|
10
|
+
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
11
|
+
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
12
|
+
> - `bkit install` and `bkit upgrade` never write these files and never overwrite a copy.
|
|
13
|
+
> - Adapt app roots, workspace package scope, rules JSON. Examples use `apps/web`, `apps/mobile`, `packages/api`, `@scope`.
|
|
14
|
+
|
|
15
|
+
## Contract
|
|
16
|
+
|
|
17
|
+
<!-- prettier-ignore -->
|
|
18
|
+
| Tool | Copy from | To | Output you commit |
|
|
19
|
+
| --- | --- | --- | --- |
|
|
20
|
+
| CI workflow | `.bkit/templates/.github/workflows/bkit-ci.yml` | `.github/workflows/bkit-ci.yml` | that file |
|
|
21
|
+
| CI scripts | `.bkit/templates/scripts/ci/` | `scripts/ci/` | the scripts you adopt (`lanes/resolve-push-base.mjs`; `check-accepted-divergences.mjs` + `accepted-divergences.json`) |
|
|
22
|
+
| Cloud-agent workflow | `.bkit/templates/.github/workflows/bkit-cloud.yml` | `.github/workflows/bkit-cloud.yml` | that file |
|
|
23
|
+
| Git hooks (Husky) | `.bkit/templates/.husky/pre-commit`, `.bkit/templates/.husky/pre-push` | `.husky/pre-commit`, `.husky/pre-push` | both files |
|
|
24
|
+
| Prettier ignore list | `.bkit/templates/.prettierignore` | `.prettierignore` | that file |
|
|
25
|
+
| lint-staged | `.bkit/templates/.lintstagedrc.json` | `.lintstagedrc.json` | that file |
|
|
26
|
+
| Vale | `.bkit/templates/.vale.ini`, `.bkit/templates/.vale/styles/House/` | `.vale.ini`, `.vale/styles/House/` | `.vale.ini` + the four House styles |
|
|
27
|
+
| slop-scan | `.bkit/templates/slop-scan.config.json`, `.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs` | `slop-scan.config.json`, `scripts/slop/bkit-slop-type-suppression.mjs` | both files |
|
|
28
|
+
| direnv | `.bkit/templates/.envrc` | `.envrc` | that file |
|
|
29
|
+
| Launchd GUI env | `.bkit/templates/scripts/launchd/` | `scripts/launchd/bkit-launchd-env.sh`, `~/Library/LaunchAgents/ai.bkit.launchd.plist`, `~/.config/bkit/launchd.env` | `scripts/launchd/bkit-launchd-env.sh` only |
|
|
30
|
+
| Cursor editor + cloud agent | `.bkit/templates/.cursor/settings.json`, `environment.json`, `Dockerfile` | same paths under `.cursor/` | the files you use |
|
|
31
|
+
| Renovate rules | `.bkit/templates/.github/renovate.json5` | `.github/renovate.json5` | that file |
|
|
32
|
+
| Renovate self-hosted runner | `.bkit/templates/.github/workflows/bkit-renovate.yml` | `.github/workflows/bkit-renovate.yml` | that file |
|
|
33
|
+
| Dependabot | `.bkit/templates/.github/dependabot.yml` | `.github/dependabot.yml` | that file |
|
|
34
|
+
| Serena | `.bkit/templates/scripts/serena/`, `.bkit/templates/.serena/project.yml` | `scripts/serena/`, `.serena/project.yml`, merge `bkit-serena.mcp.json` into `.mcp.json` | `project.yml` only |
|
|
35
|
+
| graphify | `.bkit/templates/scripts/graphify/`, `.bkit/templates/.graphifyignore`, `.bkit/templates/docs/capabilities.md` | same paths at the repo root | `docs/capabilities.md` |
|
|
36
|
+
| Secrets sync | `.bkit/templates/scripts/secrets/` | `scripts/secrets/` | both files; never `bkit-secrets-state.json` |
|
|
37
|
+
| Prettier tables | `.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs` | `scripts/prettier/` | that file |
|
|
38
|
+
| Context-fetch blocks | `.bkit/templates/context/bkit-<provider>.md` | below `<!-- bkit:end -->` in `.agents/context.md` | the blocks you use |
|
|
39
|
+
| Cloud SessionStart hook | `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` | `.claude/hooks/bkit-cloud-bootstrap.sh` | that file |
|
|
40
|
+
| Licence | `.bkit/templates/LICENSE.md` | — | read it; the copies in `.bkit/templates/` are MIT-0 |
|
|
41
|
+
|
|
42
|
+
Placeholders. Copies keep them raw; replace each in your copy:
|
|
43
|
+
|
|
44
|
+
<!-- prettier-ignore -->
|
|
45
|
+
| Placeholder | In | Put | Typical value |
|
|
46
|
+
| --- | --- | --- | --- |
|
|
47
|
+
| `{{DEFAULT_BRANCH}}` | `bkit-ci.yml` (`on.push` / `on.pull_request` branches; stub comments) | your default branch | `origin/HEAD`, else `main` |
|
|
48
|
+
| `{{NODE_VERSION}}` | `bkit-ci.yml` (`actions/setup-node` `node-version`, both lanes) | your Node major, or swap the line for `node-version-file: .nvmrc` | `.nvmrc`, then `engines.node`, then `22` |
|
|
49
|
+
| `{{CLOUD_RUNNER}}` | `bkit-cloud.yml` (`runs-on`, all three jobs) | a runner label | `ubuntu-latest` |
|
|
50
|
+
| `{{SCRIPT_PATH}}` | `ai.bkit.launchd.plist` (`ProgramArguments`) | absolute path to the loader script, outside a TCC-protected folder (see § Launchd GUI environment) | `/path/to/repo/scripts/launchd/bkit-launchd-env.sh` |
|
|
51
|
+
| `{{ENV_FILE}}` | `ai.bkit.launchd.plist` (`ProgramArguments`, `WatchPaths`) | absolute path to your env file | `/Users/<you>/.config/bkit/launchd.env` |
|
|
52
|
+
|
|
53
|
+
- `bkit install` / `bkit upgrade` refresh `.bkit/templates/` to the package's templates, unsubstituted. `bkit check` fails on a stale copy. `bkit uninstall` removes the folder, never an adopted copy.
|
|
54
|
+
- **What changed on upgrade.** `bkit upgrade` lists changed / added / removed template paths. For each one you adopted: `diff .bkit/templates/<path> <path>`, merge what you want (placeholder lines differ by design). `git diff .bkit/templates` in the upgrade commit = the package change.
|
|
55
|
+
- Repo gates that scan the whole repo (prettier, Vale, slop-scan, eslint, tsc) → ignore `.bkit/templates/`. The `.prettierignore`, `.vale.ini` and `slop-scan.config.json` templates already do; check your adopted copy does too.
|
|
56
|
+
- Templates are written in Node unless the tool they wrap already needs another runtime (graphify and Serena: Python + shell launchers; git hooks: POSIX `sh`).
|
|
57
|
+
- `bkit.depUpdater: "none"` → skips install-time absence advisory for updaters.
|
|
58
|
+
- No manifest key for any template. `docs/templates/bkit-audit-adoption.md` lists every template each run: adopted and wired, or not adopted and why.
|
|
59
|
+
|
|
60
|
+
## Context-fetch blocks — `.agents/context.md`
|
|
61
|
+
|
|
62
|
+
`/bkit-debug` runs every `context-fetch` block below `<!-- bkit:end -->` in `.agents/context.md`; cloud setup runs every `context-fetch:provision` block there. One file per provider holds its fetch blocks (one per context; copy one or more), each fetch block's provision block (stack CLI only), the `allowed-domains` it needs beyond bkit's derived egress set, and its `mcp-servers` names. Block rules (markers, contexts, self-skip, output bounds) → the managed block of `.agents/context.md`.
|
|
63
|
+
|
|
64
|
+
<!-- prettier-ignore -->
|
|
65
|
+
| File | Fits | `context=` | Fetches | Secret / non-secret env | Domains | CLI (provision) |
|
|
66
|
+
| --- | --- | --- | --- | --- | --- | --- |
|
|
67
|
+
| `github.md` | GitHub Actions | `ci`, `diff` | `ci`: failing run: failed jobs / steps, `::error` annotations, failed-step logs; `diff`: `git diff --stat` since the last green CI run on trunk | `GH_TOKEN` / `BASELINE_BRANCH`, `BASELINE_WORKFLOW` (`diff`) | — | `gh` (base tool) |
|
|
68
|
+
| `playwright.md` | Playwright on GitHub Actions | `e2e` | failing run's report artifact, failing specs first | `GH_TOKEN` / `E2E_ARTIFACT`, `E2E_JOB_RE` | — | `gh` (base tool) |
|
|
69
|
+
| `maestro.md` | Maestro iOS and Android lanes on GitHub Actions | `e2e` | every failed Maestro job's full log, sliced to the result steps | `GH_TOKEN` / `MAESTRO_JOB_RE`, `MAESTRO_STEPS` | — | `gh` (base tool) |
|
|
70
|
+
| `tavily.md` | any | `web` | web search for upstream causes (untrusted output) | `BKIT_TAVILY_API_KEY` / `QUERY` | — | — |
|
|
71
|
+
| `sentry.md` | Sentry | `runtime` | unresolved issues, last 24 h; trace / window recipes | `SENTRY_AUTH_TOKEN` / `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_HOST` | `sentry.io` | — |
|
|
72
|
+
| `vercel.md` | Vercel | `runtime` | serverless + edge error / fatal logs in a window | `VERCEL_TOKEN` / `VERCEL_SCOPE`, `VERCEL_ENV` | `vercel.com` | `vercel` (yes) |
|
|
73
|
+
| `supabase.md` | hosted Supabase | `runtime` | Postgres `ERROR` / `FATAL` / `PANIC` lines | `SUPABASE_ACCESS_TOKEN` / `SUPABASE_PROJECT_ID` | `supabase.com` | — |
|
|
74
|
+
| `stripe.md` | Stripe | `runtime` | failure / dispute / refund events | `STRIPE_SECRET_KEY` / — | `stripe.com` | — |
|
|
75
|
+
| `resend.md` | Resend | `runtime` | bounced / complained / failed / delayed sends | `RESEND_API_KEY` / — | `resend.com` | — |
|
|
76
|
+
| `inngest.md` | Inngest Cloud | `runtime` | `inngest/function.failed` events | `INNGEST_SIGNING_KEY` / — | `inngest.com` | — |
|
|
77
|
+
| `cloudrun.md` | Google Cloud Run | `runtime` | container errors + memory-limit kills | `GCP_CLIENT_EMAIL`, `GCP_PRIVATE_KEY` (headless) / `GCP_PROJECT_ID`, `GCP_SERVICE` | `googleapis.com`, `google.com` | `gcloud` (yes) |
|
|
78
|
+
| `expo.md` | Expo EAS Build + EAS Workflows (Maestro) | `runtime`, `e2e` | `runtime`: build status + errored-build log lines; `e2e`: per-flow exceptions, JUnit, screenshots, Maestro commands, hierarchy dumps, XCUITest + JS console | `EXPO_TOKEN` / `EXPO_APP_DIR` | `expo.dev`, `googleapis.com` (`runtime`), `eascdn.net` (`e2e`) | `eas` (yes) |
|
|
79
|
+
| `serena.md` | Serena MCP server | — | nothing: provision only, installs `serena` in cloud | — | — | `uv` (yes) |
|
|
80
|
+
|
|
81
|
+
MCP names listed: `sentry` / `Sentry`, `vercel` / `Vercel`, `supabase` / `Supabase`, `inngest`, `serena`. Every tool on a listed server runs without a prompt, writes included — list only servers you trust with that.
|
|
82
|
+
|
|
83
|
+
Placeholders. Each sits on a commented assignment line or an env default in the block; replace it in your copy:
|
|
84
|
+
|
|
85
|
+
<!-- prettier-ignore -->
|
|
86
|
+
| Placeholder | In | Put |
|
|
87
|
+
| --- | --- | --- |
|
|
88
|
+
| `your-team-slug` | `vercel.md` (`VERCEL_SCOPE`) | Vercel team slug |
|
|
89
|
+
| `your-project-ref` | `supabase.md` (`SUPABASE_PROJECT_ID`) | project ref of the environment whose logs you want |
|
|
90
|
+
| `your-org-slug`, `your-project-slug` | `sentry.md` (`SENTRY_ORG`, `SENTRY_PROJECT`) | Sentry slugs |
|
|
91
|
+
| `de.sentry.io` (commented) | `sentry.md` (`SENTRY_HOST`) | uncomment for an EU-region org; default `sentry.io` |
|
|
92
|
+
| `your-gcp-project-id`, `your-service-name` | `cloudrun.md` (`GCP_PROJECT_ID`, `GCP_SERVICE`) | GCP project id; optional service name |
|
|
93
|
+
| `^your-e2e-job-name$` | `playwright.md` (`E2E_JOB_RE`) | anchored job name of that lane only |
|
|
94
|
+
| `^your-maestro-e2e-job-name$`, `Your per-flow results step\|Your failure classification step` | `maestro.md` (`MAESTRO_JOB_RE`, `MAESTRO_STEPS`) | anchored regex matching the Maestro lanes' job names; `\|`-separated names of the steps that print results |
|
|
95
|
+
| `dev`, `bkit-ci.yml` | `github.md` `context=diff` (`BASELINE_BRANCH`, `BASELINE_WORKFLOW`) | trunk branch, CI workflow file |
|
|
96
|
+
| `apps/mobile` | `expo.md`, both blocks (`EXPO_APP_DIR`) | the EAS-linked app folder |
|
|
97
|
+
| `serena-agent==1.7.0` | `serena.md` | the Serena version you run locally |
|
|
98
|
+
|
|
99
|
+
Adopt:
|
|
100
|
+
|
|
101
|
+
1. Copy the file's blocks below `<!-- bkit:end -->` in `.agents/context.md`: each fetch block you want, its provision block, its `allowed-domains` and `mcp-servers` blocks (several of each merge).
|
|
102
|
+
2. Replace the placeholders. Commit non-secret selectors inline so cloud agents inherit them.
|
|
103
|
+
3. Set the secret env vars locally (app env via `.envrc`, not `.bkit/.env`) and in each cloud dashboard (`.bkit/cloud.md`).
|
|
104
|
+
4. `bkit install` → the provision recipes reach `.claude/bkit-cloud.md`'s setup script, the domains reach the cloud allowlist and local fetch permissions, the MCP names reach every host's allow rules.
|
|
105
|
+
|
|
106
|
+
- Without credentials each block self-skips: `exit 0` plus `[context-fetch:<name>] skipped — …` on stderr. `/bkit-debug` narrates that as not checked, never as clean.
|
|
107
|
+
- `bkit check` advisories point at these files: `context-fetch-missing`, `context-fetch-context-missing`, `context-fetch-source-not-enabled`, `context-fetch-provision-missing`.
|
|
108
|
+
- Another backend → author a block in the same shape (rules in the managed block of `.agents/context.md`).
|
|
109
|
+
|
|
110
|
+
## Gate tool scripts — `package.json`
|
|
111
|
+
|
|
112
|
+
bkit seeds only the `bkit:gate:*` / `bkit:deps:*` names (add-if-missing). The tool scripts their defaults chain are yours; `gate-missing-called-scripts` names any that are missing.
|
|
113
|
+
|
|
114
|
+
<!-- prettier-ignore -->
|
|
115
|
+
| Gate (default) | Chains | Needs |
|
|
116
|
+
| --- | --- | --- |
|
|
117
|
+
| `bkit:gate:format` | `pnpm lint-staged` | lint-staged devDep + `.lintstagedrc.json` + prettier |
|
|
118
|
+
| `bkit:gate:static` | `typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta` | the scripts below |
|
|
119
|
+
| `bkit:gate:static-unit` | `bkit:gate:static` + `test` | a `test` script |
|
|
120
|
+
| `bkit:gate:install-static-unit-build` | `pnpm install --frozen-lockfile` + `bkit:gate:static-unit` + `build` | a `build` script |
|
|
121
|
+
|
|
122
|
+
```json
|
|
123
|
+
{
|
|
124
|
+
"typecheck": "tsc --noEmit",
|
|
125
|
+
"lint": "bash -c 'if [ -f eslint.config.js ] || [ -f eslint.config.mjs ] || [ -f .eslintrc.json ]; then npx eslint .; else echo \"[bkit] no eslint config - skipping lint (bkit typechecks with tsc and scans with slop-scan)\"; fi'",
|
|
126
|
+
"format:check": "prettier --check .",
|
|
127
|
+
"lint:prose": "bkit ci prose",
|
|
128
|
+
"lint:slop": "slop-scan scan .",
|
|
129
|
+
"slop:delta": "bkit ci slop",
|
|
130
|
+
"prepare": "husky"
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
pnpm add -D prettier@^3.5.3 slop-scan@^0.3.0 lint-staged@^17.0.0 husky@^9.1.7
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
- `lint` must exist: with no `lint` script, `pnpm lint` falls through to any `lint` binary on `PATH` and the gate goes green through the wrong program. No eslint config → the value above prints a skip line.
|
|
139
|
+
- No `tsconfig.json` → `"typecheck": "echo \"[bkit] typecheck: no tsconfig.json — skipping\" >&2"`.
|
|
140
|
+
- `slop:delta` runs `bkit ci slop` (bkit devDep on `PATH` through the package script). CI passes the base sha as its one bare argument.
|
|
141
|
+
- `lint:prose` runs `bkit ci prose`: Vale over every `*.md` outside `node_modules/`. Narrow it with repeatable `--glob=<pattern>` (`*`, `**`, `?`, relative to the repo root), e.g. `bkit ci prose --glob='docs/*.md' --glob='.agents/*.md'`.
|
|
142
|
+
- Non-Node stack → point each gate at your own commands; keep the gate names.
|
|
143
|
+
|
|
144
|
+
## CI workflow — `bkit-ci.yml`
|
|
145
|
+
|
|
146
|
+
Parallel lanes `bkit-tests-static` (typecheck, prettier, Vale, slop, actionlint, `bkit check`) and `bkit-tests-unit`, joined by the `bkit-tests-check` capstone, plus the commented full CI scaffold reference for the other tiers. Workflows care: `/bkit-ship` waits on its runs and merges only when the `bkit.capstoneJob` job (default `bkit-tests-check`) is present and green at the head; `bkit setup protect-main` makes that job the required check; `bkit-cloud.yml` triggers on a workflow named `bkit-ci`. `bkit install` reads your copy for advisories (`ci-yml-missing-token-env`, `bkit-stub-*`, `ci-yml-missing-actionlint`, `ci-yml-capstone-contract-drift`). Reference: https://docs.github.com/en/actions.
|
|
147
|
+
|
|
148
|
+
- Install: nothing beyond the gate tool scripts above, a `test` script, and `packageManager` in `package.json` (`pnpm/action-setup` reads it; do not add `with: version:`).
|
|
149
|
+
- Secrets: `BKIT_GH_TOKEN_INSTALL` (`read:packages`) → `docs/deployments.md` § Consumer CI auth.
|
|
150
|
+
- Adapt: `{{DEFAULT_BRANCH}}`, `{{NODE_VERSION}}`. Non-Node repo → replace the Node / pnpm setup, install and check steps with your stack's.
|
|
151
|
+
- Capstone: `bkit-tests-check` `needs:` every lane and runs on `!cancelled()`, never `always()`. Each lane you adopt from the reference goes into its `needs:` and its assert, or that lane's failure cannot red the merge. It asserts each lane's executed-test count once the lane writes one (the `Run Unit Tests` step comment shows the vitest form); an unreported count is a warning, a count of 0 a failure. Renaming the job → set `bkit.capstoneJob`.
|
|
152
|
+
- Adopt a scaffold lane only when its tier exists (`docs/testing.md`). Each `# bkit-stub:<id> —` header raises an install advisory until you enable or delete that stub.
|
|
153
|
+
- Keep the `name: bkit-ci` line, or rename `workflows: [bkit-ci]` in `bkit-cloud.yml` and set `bkit.ciWorkflow` to the new file name.
|
|
154
|
+
- Keep `fetch-depth: 0` on the static lane: `slop:delta` checks the PR base out as a worktree.
|
|
155
|
+
|
|
156
|
+
## Cloud-agent workflow — `bkit-cloud.yml`
|
|
157
|
+
|
|
158
|
+
Post-CI router: CI pass on `feat/**` → `/bkit-ship`, fail → `/bkit-debug`; failed `dev` CI → `/bkit-debug {FID}`; `workflow_dispatch` runs any phase. A `context` job resolves phase + arg once, then two runner jobs, each skipped without its secret: `claude` (`claude-code-action`, https://github.com/anthropics/claude-code-action) and `opencode` (`opencode run`, https://opencode.ai/docs/github/). Runs bkit workflows; `bkit install --auto=claude|opencode` points at it. Full recipe: `.bkit/cloud.md` § Post-CI auto-routing.
|
|
159
|
+
|
|
160
|
+
- Install: `bkit install --auto=claude` (points at the `.claude/hooks/bkit-cloud-bootstrap.sh` template) or `--auto=opencode` (needs `--opencode=<provider>` first). Both need `--tracker=github`.
|
|
161
|
+
- Secrets: `ANTHROPIC_API_KEY` + the Claude GitHub App (`/install-github-app`) for `claude`; `OPENCODE_PROVIDER_KEY` for `opencode`. Repo Actions permissions: read and write, PR creation allowed.
|
|
162
|
+
- Adapt: `{{CLOUD_RUNNER}}` in all three jobs.
|
|
163
|
+
- Traps: the file runs bkit by command name, so a changed invocation reaches you only as a changed template path on `bkit upgrade` — diff it on every upgrade. The opencode install version is a plain argument no updater bumps. Keep the file out of updater `ignorePaths` so action pins refresh.
|
|
164
|
+
|
|
165
|
+
## Git hooks — Husky
|
|
166
|
+
|
|
167
|
+
`pre-commit` runs `bkit:gate:format`; `pre-push` runs `bkit:gate:static-unit` (`bkit:gate:static` on revert branches / commits), then `bkit check`, plus a CI-suppressing-token guard. Workflows care: they commit and push without `--no-verify`, so a failing hook stops a workflow. Reference: https://typicode.github.io/husky/.
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
pnpm add -D husky@^9.1.7 # plus "prepare": "husky" (§ Gate tool scripts)
|
|
171
|
+
chmod +x .husky/pre-commit .husky/pre-push
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
- `.gitignore`: `.husky/_` (bkit's `.gitignore` block already lists it).
|
|
175
|
+
- Adapt: repo-only checks go below the bkit lines in each hook. What a gate runs belongs in the `bkit:gate:*` script, not the hook.
|
|
176
|
+
- Traps: hooks run on every workflow commit; keep them to seconds (pre-commit) and deterministic, offline checks (pre-push). Integration, E2E and `@live` belong in CI.
|
|
177
|
+
|
|
178
|
+
## Prettier — `.prettierignore` first
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
pnpm add -D prettier@^3.5.3
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
1. Copy `.prettierignore` before the first `prettier --write`. bkit writes `.claude/`, `.cursor/`, `.opencode/`, `.mcp.json`, `.bkit/.env.example`, `docs/roadmap.md` in its own layout; prettier reformatting them fights the next `bkit install` (`bkit check` drift).
|
|
185
|
+
2. Add `format:check` (§ Gate tool scripts). Reference: https://prettier.io/docs/install.
|
|
186
|
+
|
|
187
|
+
- Keep the `.bkit/templates/` line.
|
|
188
|
+
|
|
189
|
+
## lint-staged — `.lintstagedrc.json`
|
|
190
|
+
|
|
191
|
+
Runs prettier over staged files. `bkit:gate:format` (the pre-commit hook) calls it. Reference: https://github.com/lint-staged/lint-staged.
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
pnpm add -D lint-staged@^17.0.0 prettier@^3.5.3
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
- Adapt: add per-glob commands (eslint `--fix`, etc.) — keep them seconds-fast.
|
|
198
|
+
|
|
199
|
+
## Vale — prose lint, with House styles
|
|
200
|
+
|
|
201
|
+
`lint:prose` (`bkit ci prose`, in `bkit:gate:static`) runs Vale with the `write-good` package and bkit's House styles (`Filler`, `Hedging`, `LLMSlop`, `Verbose`) on `.agents/**`. Workflows reach Vale only through the gate. Reference: https://vale.sh/docs/install.
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
brew install vale
|
|
205
|
+
vale sync
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
- Copy `.vale.ini` and all four `.vale/styles/House/*.yml`.
|
|
209
|
+
- `.gitignore`: `.vale/styles/write-good` (`vale sync` downloads it; the House styles stay tracked).
|
|
210
|
+
- CI: the `bkit-ci.yml` template installs a pinned Vale and runs `vale sync`. Cursor: the `Dockerfile` template installs it.
|
|
211
|
+
- Adapt: add `[glob]` scope blocks for your own docs; turn rules off per path, not globally.
|
|
212
|
+
- Traps: no Vale on `PATH` → `lint:prose` prints a skip line and the prose gate is not enforcing. A missing `write-good` is copied from the main worktree, else `vale sync` runs; when both fail it prints a loud skip warning. Keep the `.bkit/templates/**` block (rules off for the copies).
|
|
213
|
+
|
|
214
|
+
## slop-scan — `slop-scan.config.json`
|
|
215
|
+
|
|
216
|
+
`lint:slop` reports; `slop:delta` (`bkit ci slop`, in `bkit:gate:static`) fails on net-new findings against the base. Reference: https://github.com/benvinegar/slop-scan.
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
pnpm add -D slop-scan@^0.3.0
|
|
220
|
+
mkdir -p scripts/slop
|
|
221
|
+
cp .bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs scripts/slop/
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
- The plugin is a template: copy `scripts/slop/bkit-slop-type-suppression.mjs` and point the config's `plugins` entry at it (`boundary/type-suppression`, `boundary/gate-suppression`). No plugin → drop the `plugins` entry and both `boundary/*` rules.
|
|
225
|
+
- Adapt: `ignores` for generated / vendored trees; per-file `overrides` with a reason, never a rule disabled repo-wide.
|
|
226
|
+
- Traps: keep `**/.bkit/templates/**` in `ignores`, or copied `.mjs` / `.py` count as net-new slop on the upgrade commit.
|
|
227
|
+
|
|
228
|
+
## direnv — `.envrc`
|
|
229
|
+
|
|
230
|
+
Loads `.bkit/.env` on `cd`, so local sessions see `BKIT_GH_TOKEN`, `BKIT_GH_TOKEN_INSTALL`, tracker keys. bkit reads your `.envrc` (its `dotenv*` and `unset` lines, never executed) to fill the env blocks of `.claude/bkit-cloud.md` / `.cursor/bkit-cloud.md`; preflight's direnv advisories key on it. Reference: https://direnv.net/docs/installation.html.
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
brew install direnv # then add the shell hook from the link
|
|
234
|
+
direnv allow
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
- Adapt: one `dotenv_if_exists <path>` line per extra env file; `unset` keys that must stay out of the shell (they are dropped from the cloud env blocks too).
|
|
238
|
+
|
|
239
|
+
## Launchd GUI environment — tokens for Dock-launched apps
|
|
240
|
+
|
|
241
|
+
Dock/Spotlight launches start under `launchd`, which never runs the login shell or direnv → GUI apps (opencode desktop, Cursor) start without `BKIT_*` and provider calls fail on authentication. The template set pairs a loader script with a machine-local env file; the LaunchAgent runs the loader at login and again on every write to that file.
|
|
242
|
+
|
|
243
|
+
<!-- prettier-ignore -->
|
|
244
|
+
| File | Copy from | To | Commit |
|
|
245
|
+
| --- | --- | --- | --- |
|
|
246
|
+
| Loader | `.bkit/templates/scripts/launchd/bkit-launchd-env.sh` | `scripts/launchd/bkit-launchd-env.sh` | that file |
|
|
247
|
+
| LaunchAgent | `.bkit/templates/scripts/launchd/ai.bkit.launchd.plist` | `~/Library/LaunchAgents/ai.bkit.launchd.plist` | never (machine-local) |
|
|
248
|
+
| Tokens | `.bkit/templates/scripts/launchd/launchd.env.example` | `~/.config/bkit/launchd.env` | never (machine-local) |
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
cp .bkit/templates/scripts/launchd/bkit-launchd-env.sh scripts/launchd/
|
|
252
|
+
chmod +x scripts/launchd/bkit-launchd-env.sh
|
|
253
|
+
mkdir -p ~/.config/bkit
|
|
254
|
+
cp .bkit/templates/scripts/launchd/launchd.env.example ~/.config/bkit/launchd.env
|
|
255
|
+
chmod 600 ~/.config/bkit/launchd.env # tokens stay owner-only
|
|
256
|
+
# fill in the tokens, then place the agent:
|
|
257
|
+
cp .bkit/templates/scripts/launchd/ai.bkit.launchd.plist ~/Library/LaunchAgents/
|
|
258
|
+
# replace {{SCRIPT_PATH}} and {{ENV_FILE}} with absolute paths in the copied plist
|
|
259
|
+
launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist 2>/dev/null || true
|
|
260
|
+
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist
|
|
261
|
+
launchctl getenv BKIT_OPENROUTER_API_KEY # bootstrap proof
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
- `WatchPaths` re-runs the loader on every env-file write → rotate a token by editing the file, no re-bootstrap.
|
|
265
|
+
- Log `~/Library/Logs/bkit-launchd.log` records key names only, never values. `BKIT_LAUNCHD_LOG` and `BKIT_LAUNCHD_ENV` override the log and env-file defaults.
|
|
266
|
+
- Loader self-skips (log line + `exit 0`) when the env file is absent or `launchctl` is off `PATH` (Linux CI).
|
|
267
|
+
- launchd cannot exec a loader under `~/Documents`, `~/Desktop` or `~/Downloads`: macOS TCC denies it and `/tmp/bkit-launchd.log` reads `Operation not permitted`. Repo under one of those → keep the adopted copy in git but place the loader launchd runs at `~/.config/bkit/bkit-launchd-env.sh` (or another unprotected path) and point `{{SCRIPT_PATH}}` there.
|
|
268
|
+
- Env-file rules: blank lines and `#` comments ignored; optional `export ` prefix; key must match `[A-Za-z0-9_]`; matching surrounding quotes stripped from the value.
|
|
269
|
+
- `launchctl setenv` reaches apps launched after the load; a running app keeps its environment until relaunch.
|
|
270
|
+
- Remove: `launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist`.
|
|
271
|
+
|
|
272
|
+
## Cursor — `settings.json`, `environment.json`, `Dockerfile`
|
|
273
|
+
|
|
274
|
+
Editor defaults (`settings.json`: prettier format-on-save, extension recommendations) and the Cursor Cloud Agent image (`environment.json` → `Dockerfile` + per-snapshot `install`). Cloud agents run bkit workflows; `bkit install --auto=cursor` (needs `--tracker=linear`) points at the two cloud files. Reference: https://cursor.com/docs/cloud-agent/setup.
|
|
275
|
+
|
|
276
|
+
- `Dockerfile`: the `bkit toolchain` section installs what bkit's workflows use (git, jq, python3, gh, pinned Vale, corepack-pinned pnpm). Adapt `FROM`, the Node major and repo extras outside it.
|
|
277
|
+
- `environment.json` `install`: writes the `BKIT_GH_TOKEN_INSTALL` auth line, `pnpm install --frozen-lockfile`, `vale sync` when `.vale.ini` exists.
|
|
278
|
+
- Secrets: Cloud Agents dashboard → Runtime Secrets (`.bkit/cloud.md`).
|
|
279
|
+
- Traps: the corepack pnpm pin must match `packageManager`. Keep the `bkit toolchain` section as shipped so the template diff on upgrade stays readable.
|
|
280
|
+
|
|
281
|
+
## Dependabot and Renovate
|
|
282
|
+
|
|
283
|
+
Opens dependency PRs. No bkit workflow reads either. Pick one; copy only its files. Reference: Dependabot https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference; Renovate https://docs.renovatebot.com/, self-hosted action https://github.com/renovatebot/github-action.
|
|
284
|
+
|
|
285
|
+
Dependabot — commit `.github/dependabot.yml` on the default branch, then enable alerts and security updates:
|
|
286
|
+
|
|
287
|
+
```bash
|
|
288
|
+
gh api -X PUT 'repos/{owner}/{repo}/vulnerability-alerts'
|
|
289
|
+
gh api -X PUT 'repos/{owner}/{repo}/automated-security-fixes'
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
Renovate (Mend) — commit `.github/renovate.json5` on the default branch, then install the App at https://github.com/apps/renovate (GitHub UI only; no `gh` equivalent). Renovate (self-hosted) — also copy `bkit-renovate.yml`, then set its platform token (fine-grained PAT; permissions → `docs/deployments.md` § Dependency updaters):
|
|
293
|
+
|
|
294
|
+
```bash
|
|
295
|
+
gh secret set BKIT_GH_TOKEN
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
- Examples ignore `.bkit/templates/**` and `.agents/skills/**` (bkit rewrites them). Your copied workflows (`bkit-ci.yml`, `bkit-cloud.yml`) stay in scope so their pins refresh.
|
|
299
|
+
- `enabled: false` on a Renovate package rule does not stop digest pinning; use `ignorePaths` to keep Renovate off a file.
|
|
300
|
+
- Land config on default branch before bot runs. Examples set `baseBranchPatterns: ["dev"]`.
|
|
301
|
+
- App install, self-hosted token, private-package host rule, CVE handling → `docs/deployments.md` § Dependency updaters.
|
|
302
|
+
|
|
303
|
+
## Serena — symbol lookup
|
|
304
|
+
|
|
305
|
+
Local language server, wired as MCP server; agents use it. Does not rewrite `CLAUDE.md` / `.claude/settings.json`. Reference: https://github.com/oraios/serena.
|
|
306
|
+
|
|
307
|
+
```bash
|
|
308
|
+
brew install uv
|
|
309
|
+
uv tool install -p 3.13 serena-agent
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
PyPI name `serena-agent`, CLI `serena`. PyPI `serena` is an unrelated package.
|
|
313
|
+
|
|
314
|
+
- Set `project_name`, `typescript_version` in `.serena/project.yml`. `typescript_version` must match `package.json`, not Serena's bundled compiler. TypeScript >= 7 ships no `tsserver` → language server fails to start (`Could not find a valid TypeScript installation`) → set `"5.9.3"` (Serena's bundled, last with `tsserver`).
|
|
315
|
+
- Trust the project: add its path to `trusted_project_path_patterns` in `~/.serena/serena_config.yml`. Untrusted → Serena ignores all of `ls_specific_settings` (`typescript_version`, indexing waits) with only a log `WARNING`; lookups still answer on bundled defaults.
|
|
316
|
+
- Adapt `ignored_paths` to the repo: index the code a change touches, skip committed build output and byte-copied payloads (each indexed copy answers every reference twice).
|
|
317
|
+
- `.mcp.json` (Claude Code) calls `scripts/serena/bkit-serena-mcp.sh` → finds binary when GUI app has no login-shell `PATH`.
|
|
318
|
+
- Cursor's `.cursor/mcp.json` cannot use that wrapper → point `command` at `${HOME}/.local/bin/serena`, pass `--context ide`.
|
|
319
|
+
- Codex: `.codex/config.toml` → `[mcp_servers.serena]`, `command` = absolute path to `serena`, `args = ["start-mcp-server", "--context", "codex", "--project-from-cwd"]`. bkit writes no `.codex/config.toml`.
|
|
320
|
+
- OpenCode: `.opencode/opencode.json` → `mcp.serena` = `{ "type": "local", "command": ["<absolute path to serena>", "start-mcp-server", "--context", "ide", "--project-from-cwd"] }`. `bkit upgrade` keeps custom `mcp` entries.
|
|
321
|
+
- List `serena` in `.agents/context.md` `mcp-servers` block → every host runs its tools without a prompt; workflow subagents cannot answer one.
|
|
322
|
+
- bkit code-reading subagents carry `mcp__serena__*` in `tools:`. Serena not wired → Claude Code drops the entry; agent runs on text search.
|
|
323
|
+
|
|
324
|
+
`.gitignore`:
|
|
325
|
+
|
|
326
|
+
```
|
|
327
|
+
.serena/*
|
|
328
|
+
!.serena/project.yml
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
- Keep `read_only: true`, `added_modes: ["no-memories"]`, and the full `excluded_tools` list from example → Serena stays lookup-only for agents. List excludes every tool that writes files / memories / project config, runs code or commands, or opens a browser. Serena edits bypass Edit / Write hooks. Removing an entry hands that tool to every bkit agent.
|
|
332
|
+
- `--context codex` still lists excluded tools but refuses each call (`not active`).
|
|
333
|
+
- Serena line numbers are 0-based → add 1 before citing `file:line`.
|
|
334
|
+
- Small / empty answer for an exported symbol = query did not resolve, not "nothing uses it" → corroborate with text search.
|
|
335
|
+
- pnpm monorepo: cross-package references need `composite` + `references` in TypeScript project graph before language server follows them.
|
|
336
|
+
|
|
337
|
+
## graphify — map
|
|
338
|
+
|
|
339
|
+
On-demand only — not an MCP server, installed skill, CI job, or git hook. Agents read `docs/capabilities.md`; audit templates that need the graph build it via `scripts/graphify/bkit-graphify.sh`. Only tracked output: `docs/capabilities.md`. Mermaid views: `docs/graphify-out/reports/graph-packages.mmd`, `graph-modules.mmd`. Reference: https://github.com/Graphify-Labs/graphify.
|
|
340
|
+
|
|
341
|
+
```bash
|
|
342
|
+
uv tool install "graphifyy[sql]"
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
PyPI name `graphifyy`, CLI `graphify`. `[sql]` adds `.sql` files to corpus.
|
|
346
|
+
|
|
347
|
+
`package.json` scripts:
|
|
348
|
+
|
|
349
|
+
```json
|
|
350
|
+
{
|
|
351
|
+
"graph": "bash scripts/graphify/bkit-graphify.sh build",
|
|
352
|
+
"graph:check": "bash scripts/graphify/bkit-graphify.sh check",
|
|
353
|
+
"graph:clean": "bash scripts/graphify/bkit-graphify.sh clean",
|
|
354
|
+
"graph:graphml": "bash scripts/graphify/bkit-graphify.sh graphml",
|
|
355
|
+
"graph:rollup": "bash scripts/graphify/bkit-graphify.sh rollup",
|
|
356
|
+
"graph:scoped": "bash scripts/graphify/bkit-graphify.sh scoped",
|
|
357
|
+
"graph:tree": "bash scripts/graphify/bkit-graphify.sh tree",
|
|
358
|
+
"graph:update": "bash scripts/graphify/bkit-graphify.sh update"
|
|
359
|
+
}
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
`.envrc`:
|
|
363
|
+
|
|
364
|
+
```
|
|
365
|
+
export GRAPHIFY_OUT=docs/graphify-out
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
`.gitignore` (no leading slash):
|
|
369
|
+
|
|
370
|
+
```
|
|
371
|
+
graphify-out/
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
- Paste `scripts/graphify/bkit-graph-pre-push.sh` at the end of your `.husky/pre-push`, below the bkit lines. Warn-only: does not run graphify, does not block push.
|
|
375
|
+
- `.graphifyignore` merges `.gitignore`.
|
|
376
|
+
- Keep `package.json` in corpus — excluding it drops workspace `name` fields graphify resolves package imports with; graph still looks complete.
|
|
377
|
+
- Keep `tsconfig.json` out; graphify reads `paths` regardless.
|
|
378
|
+
- Always run `scripts/graphify/bkit-graphify.sh` — passes `--code-only`, `--no-label`, unsets API keys. No persistent LLM-off setting.
|
|
379
|
+
|
|
380
|
+
<!-- prettier-ignore -->
|
|
381
|
+
| Command | Does |
|
|
382
|
+
| --- | --- |
|
|
383
|
+
| `pnpm graph` | Extract + cluster. Local. No API key. |
|
|
384
|
+
| `pnpm graph:clean` | Same, after deleting `docs/graphify-out/`. Required after any tsconfig `paths` change. `--force` does not invalidate the module-resolution cache. |
|
|
385
|
+
| `pnpm graph:update` | Re-extract changed files, then recluster. |
|
|
386
|
+
| `pnpm graph:rollup` | Package and module views, plus `docs/capabilities.md`. |
|
|
387
|
+
| `pnpm graph:check` | Rebuild and fail if `docs/capabilities.md` is not what this tree produces. Run from a clean checkout before the dev → main PR. |
|
|
388
|
+
| `pnpm graph:scoped [path]` | One subtree. Default `apps/web/src`. |
|
|
389
|
+
| `pnpm graph:graphml` | Opt-in GraphML for Gephi / yEd. |
|
|
390
|
+
|
|
391
|
+
- `docs/graphify-out/` = raw `graph.json`; `docs/graphify-out/reports/` = derived views.
|
|
392
|
+
- Copy `.bkit/templates/docs/capabilities.md` → `docs/capabilities.md` before first rollup (Overrides block must exist) → `pnpm graph:rollup` rewrites it after.
|
|
393
|
+
- Add capability → rule in `bkit-graph-drift-rules.json`: lane, owner module, one literal marker. Shipped rules JSON = one example row; replace it.
|
|
394
|
+
- Marker = a literal only the owner should contain (a host, a header, a marker string) — never the owner's exported function name: every legitimate caller then reads as `bypassed`.
|
|
395
|
+
|
|
396
|
+
`MMD_MIN_WEIGHT` (default 12, set in `bkit-graphify.sh`) drops light edges from the Mermaid views (`.mmd` files and the diagrams in `docs/capabilities.md`). One module per file → thinner edges → lower the default in your copy; an env override changes `docs/capabilities.md` per shell and fails `pnpm graph:check`. Iterate in mermaid.live; render internal-architecture diagram locally:
|
|
397
|
+
|
|
398
|
+
```bash
|
|
399
|
+
npx -y @mermaid-js/mermaid-cli -i docs/graphify-out/reports/graph-packages.mmd -o tmp/graph-packages.svg
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
- `bkit-graph-repair.py` runs between extract and cluster: restores `.js` specifiers pointing at `.tsx` files and workspace subpaths through an `exports` map. Bare `graphify update` drops that injection; `pnpm graph:update` restores it.
|
|
403
|
+
- `bkit-graph-surface.py` = route layer. Assumes `apps/web` / `apps/mobile` page routes, `packages/api/src/v1.ts`, workspace scope `@scope/services/`. Replace `@scope` and route globs or section stays empty. Route reachability runs only when `scripts/ci/guards/assert-routes-reachable.mjs` exists; else skipped.
|
|
404
|
+
- `bkit-graph-imports.py` picks `react-native` vs `default` export conditions from importer path (`apps/mobile` vs `apps/web`). Change prefixes if app roots differ.
|
|
405
|
+
- Source roots are hard-coded for an `apps/` + `packages/` monorepo: `ROOTS` in `bkit-graph-drift.py` (files the drift rules scan), `ROOTS` in `bkit-graph-eager.py` and `DEFAULT_ROOTS` in `bkit-graph-imports.py` (files those passes walk), `by_package` / `by_module` in `bkit-graphify-rollup.py` (diagram boxes). Other layout → adapt all five, else capabilities read `gap` and diagrams come out empty. One flat source folder → `by_module` = one node per file. No web routes / no imports between top-level folders → route and package diagrams stay empty; that is the answer, not a fault.
|
|
406
|
+
- Extract warning `had syntax errors and may be partially extracted` can fire on valid code → symbols after that line are missing from the graph; treat that file as unmapped.
|
|
407
|
+
|
|
408
|
+
Do not run:
|
|
409
|
+
|
|
410
|
+
<!-- prettier-ignore -->
|
|
411
|
+
| Command | Effect |
|
|
412
|
+
| --- | --- |
|
|
413
|
+
| `graphify claude install` | Writes `CLAUDE.md` and `.claude/settings.json`. Next `bkit install` clobbers both. |
|
|
414
|
+
| `graphify install --project` | Writes a skill. `/bkit-ship` removes skills not named in `.agents/skills.md`. |
|
|
415
|
+
| `graphify hook install` | Rebuilds on every commit. bkit commits many times per workflow run. |
|
|
416
|
+
|
|
417
|
+
- Code-graph answer confirms what is present; does not prove what is absent. Missing edge looks like a real gap.
|
|
418
|
+
- Ignore rules are load-bearing: a noise-only pattern can drop edges the tool needs; output still looks plausible → re-measure after changing `.graphifyignore`.
|
|
419
|
+
|
|
420
|
+
## Secrets sync — one source, every store
|
|
421
|
+
|
|
422
|
+
Local gitignored env files = source of truth; `bkit-secrets.mjs sync` makes every store match, `drift` proves it. Needs Node >= 20 plus the CLI of each store used (`gh`, `eas`, `gcloud`); Vercel and Supabase go through their REST APIs.
|
|
423
|
+
|
|
424
|
+
- Copy both files. Edit `bkit-secrets.config.mjs` only; `bkit-secrets.mjs` stays byte-identical across repos.
|
|
425
|
+
- Config = one row per secret naming every store holding a copy: `DATABASE_URL: ["vercel", "gcp"]`. Options per row: `from` (env key differs from store name), `derive` (`"${APP_URL}/path"`), `manual` (copies no API reaches), `"eas:secret"` (per-store option).
|
|
426
|
+
- Delete unused entries under `stores`; a store no row names is skipped.
|
|
427
|
+
- `.gitignore`: `scripts/secrets/bkit-secrets-state.json`.
|
|
428
|
+
- `.bkit/.env` overlay → agent / bkit tooling secrets only; app and stack credentials stay in app env files.
|
|
429
|
+
|
|
430
|
+
<!-- prettier-ignore -->
|
|
431
|
+
| Command (`node scripts/secrets/bkit-secrets.mjs …`) | Does |
|
|
432
|
+
| --- | --- |
|
|
433
|
+
| `sync --dry-run` | Writes and deletes it would make; no value printed. |
|
|
434
|
+
| `sync` | Writes values that differ or cannot be proven equal; deletes names not listed for a store, or empty in source. |
|
|
435
|
+
| `drift` | Read-only. Per store and environment: `missing`, `extra`, `differs`, `not-pushed`, `changed-elsewhere`. Exit 2 on drift. |
|
|
436
|
+
| `check [file]` | Local only: sources, env file vs example (exit 2 on a missing required key), every copy of every secret. |
|
|
437
|
+
| `--store <name>` | Narrow `sync` / `drift` / `list` to one store. Every run covers both environments; no per-environment option. |
|
|
438
|
+
|
|
439
|
+
`sync` deletes every live name not listed for that store → `--dry-run` before every sync. No listed key resolving to a value skips deletes for that store.
|
|
440
|
+
|
|
441
|
+
How `drift` proves a value without printing it:
|
|
442
|
+
|
|
443
|
+
<!-- prettier-ignore -->
|
|
444
|
+
| Store | Read back | Proof |
|
|
445
|
+
| --- | --- | --- |
|
|
446
|
+
| Vercel (encrypted / plain) | per-variable API read (the list endpoint stays encrypted) | SHA-256 of live value vs source |
|
|
447
|
+
| GCP Secret Manager | latest version | SHA-256 of live value vs source |
|
|
448
|
+
| EAS (plaintext / sensitive) | `env:list --include-sensitive` | SHA-256 of live value vs source |
|
|
449
|
+
| GitHub Actions, Supabase, Vercel sensitive, EAS `secret` | write-only | state-file fingerprint vs source (`not-pushed`); store's last-updated time after recorded push (`changed-elsewhere`) |
|
|
450
|
+
|
|
451
|
+
- No recorded push → `unverified`, never `ok`. First sync records one.
|
|
452
|
+
- `bkit-secrets-state.json` = fingerprints + times only, per machine. Push from another machine or by hand → `changed-elsewhere` until next sync here.
|
|
453
|
+
- `manual` copies listed on every `check` / `drift`; update by hand on rotation.
|
|
454
|
+
- Vercel: branch-scoped preview vars left alone; an entry shared across environments is split before a write.
|
|
455
|
+
|
|
456
|
+
New store type → entry in `STORES` of the template's `bkit-secrets.mjs` (`open` → `list` / `write` / `remove`; contract above it), never in a copy only.
|
|
457
|
+
|
|
458
|
+
## Prettier tables — keep table diffs to the changed row
|
|
459
|
+
|
|
460
|
+
Prettier aligns markdown tables with no config toggle; one edited cell re-pads every row. `bkit-insert-ignore.mjs` puts `<!-- prettier-ignore -->` directly above each table head (no blank line between), strips cell padding, normalises separators to `---`. Idempotent. Node >= 20, no dependencies.
|
|
461
|
+
|
|
462
|
+
<!-- prettier-ignore -->
|
|
463
|
+
| Command | Does |
|
|
464
|
+
| --- | --- |
|
|
465
|
+
| `node scripts/prettier/bkit-insert-ignore.mjs` | Rewrite `.agents/`, `docs/`, `README.md` (or the paths given). |
|
|
466
|
+
| `node scripts/prettier/bkit-insert-ignore.mjs --check` | Write nothing; exit 1 if any file would change. Gate form. |
|
|
467
|
+
|
|
468
|
+
- Walks skip `skills/` trees (vendored), `docs/audits/`, `docs/plans/` (records, kept as written). A file named on the command line is always processed.
|
|
469
|
+
- Skips tables inside ``` / ~~~ fences and tables already wrapped.
|
|
470
|
+
- A pipe inside an inline-code span is escaped to `\|` only when that restores the separator's column count; an existing `\|` stays literal.
|
|
471
|
+
- Exit 1 on damage it cannot repair, with or without `--check`: `truncated-row` (more cells than the separator; GFM drops the overflow) and `unrendered-table` (header ≠ separator count; GFM renders raw text). A bare pipe in cell prose is indistinguishable from a delimiter → escape it as `\|` by hand.
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Trackers
|
|
2
|
+
|
|
3
|
+
{{BKIT_MANAGED_MARKER}}
|
|
4
|
+
|
|
5
|
+
> [!CAUTION]
|
|
6
|
+
> **Purpose:** Reference for inline tracker-block model in `.bkit/core/workflows/bkit-*.md` and `.bkit/core/prompts/bkit-*.md`. **Not consumed by installer** — no `trackers.md` substitution. Per-tracker call bodies (`github` / `linear` / `none`) live INLINE at each workflow call site; this file documents marker contract + cross-cutting per-tracker conventions only.
|
|
7
|
+
>
|
|
8
|
+
> **Rules:**
|
|
9
|
+
>
|
|
10
|
+
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
11
|
+
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
12
|
+
> - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another. Label semantics live in `.bkit/workflows.md` § Tracker Integration; this file is the marker contract + operational per-tracker reference.
|
|
13
|
+
> - Ships to consumers: describe the current setup only. NEVER an internal identifier (tracker issue number, ledger key, review-finding id) and NEVER project history — decisions belong in `docs/decisions.jsonl`, incidents in `docs/knowledge.jsonl`.
|
|
14
|
+
> - Three trackers: `github` (default), `linear` (opt-in), `none` (no tracker wired).
|
|
15
|
+
> - New tracker (Jira, etc.): add enum to `.bkit/core/engine/install/manifest.ts`; document MCP under `mcpServers.<name>` in `.bkit/shared/.mcp.json` and `.bkit/shared/.cursor/mcp.json`; add `<!-- bkit:tracker <name> -->` block alongside `github`/`linear` at every call site (extend pair resolver in `.bkit/core/engine/render/trackers.ts`). No `none` marker — no-tracker content is `false`.
|
|
16
|
+
|
|
17
|
+
## Marker contract
|
|
18
|
+
|
|
19
|
+
Workflow and prompt sources carry wired tracker variants inline. Installer reads `bkit.issueTracker` from consumer manifest, resolves markers when mirroring `.bkit/core/workflows/bkit-*.md` to every host's commands / skills and `.bkit/core/prompts/bkit-*.md` to every host's agents (`.bkit/core/engine/render/trackers.ts`). Mirrors clean — no markers survive.
|
|
20
|
+
|
|
21
|
+
Prompt frontmatter `tools:` lists: every marker must be a YAML comment (` # <!-- bkit:tracker github start -->`) — a bare `<!--` line is invalid YAML; installer strips the `# ` with the marker. A pair inside the YAML list must end with a `false` block, and every block (incl. `false`) must hold at least one list item — the `none` stub and an empty block both break the YAML. `bkit-utility-update-roadmap` carries `- Bash` in all three blocks for this.
|
|
22
|
+
|
|
23
|
+
### Per-tracker pair (`github` / `linear`)
|
|
24
|
+
|
|
25
|
+
Every call site = consecutive `github` → `linear` pair, optionally trailing `false` block (substantive no-tracker rendering). Without `false`, no-tracker rendering = generic message at resolution time.
|
|
26
|
+
|
|
27
|
+
```text
|
|
28
|
+
<!-- bkit:tracker github start -->
|
|
29
|
+
mcp__github__… call
|
|
30
|
+
<!-- bkit:tracker github end -->
|
|
31
|
+
<!-- bkit:tracker linear start -->
|
|
32
|
+
mcp__linear__… call
|
|
33
|
+
<!-- bkit:tracker linear end -->
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Resolution: `github` → github block; `linear` → linear block; `none` → pair's trailing `false` block if present, else **`_No tracker connected, skip step._`**. List-number prefix (`3. `) before pair preserved on kept block / stub. Lone `github` or `linear` (no partner) = orphan.
|
|
37
|
+
|
|
38
|
+
### Conditional blocks (`bkit:tracker true` / `bkit:tracker false`)
|
|
39
|
+
|
|
40
|
+
Boolean tracker-presence gates for tracker-agnostic content. only no-tracker markers — no `none` marker.
|
|
41
|
+
|
|
42
|
+
- `<!-- bkit:tracker true start/end -->` — kept when tracker connected (`github` or `linear`); **removed entirely under `none`** (no stub). Shared content e.g. comment `{BODY}` fence identical for github/linear.
|
|
43
|
+
- `<!-- bkit:tracker false start/end -->` — kept only under `none`; removed when wired. Substantive no-tracker behaviour (`issue-id-extraction`, `fid-format`, `pr-body-marker`, `pr-body-metadata`). `false` directly after `github`/`linear` pair = pair's `none` rendering; standalone `false` resolved on its own.
|
|
44
|
+
|
|
45
|
+
```text
|
|
46
|
+
<!-- bkit:tracker true start -->
|
|
47
|
+
… shared content (kept when wired; removed under none) …
|
|
48
|
+
<!-- bkit:tracker true end -->
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Conditionals resolved after pair pass — pair nested inside kept `true` resolves first. Removed block consumes leading newline + indentation (no blank gap). Unbalanced `start`/`end` = orphan.
|
|
52
|
+
|
|
53
|
+
**Numbered-step rule:** never wrap numbered list item's NUMBER inside `true` block — under `none` whole item vanishes → numbering gap (`1, 6, 7`). Numbered step with tracker-only body: keep `N.` outside markers; pair `true` body with trailing `false` stub. Put `false` on same line as `true end`, single leading space before stub → inline (`N. _stub_`) not dangling continuation:
|
|
54
|
+
|
|
55
|
+
```text
|
|
56
|
+
N. <!-- bkit:tracker true start -->
|
|
57
|
+
… tracker-only body (github/linear pairs allowed inside) …
|
|
58
|
+
<!-- bkit:tracker true end --><!-- bkit:tracker false start --> _No tracker connected, skip step._<!-- bkit:tracker false end -->
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Renders `N. <body>` when wired, `N. _No tracker connected, skip step._` under `none` — number survives, one line. Bare-`true` "removed, no stub" form = **checklist `- [ ]` gate items** (vanishing correct — stub bullet = noise).
|
|
62
|
+
|
|
63
|
+
## Interaction catalog
|
|
64
|
+
|
|
65
|
+
Per-tracker call sites referenced across `.bkit/workflows.md` by these names. Each = inline `github`/`linear` pair; authoritative bodies inline in workflows. `none` column: most sites collapse to generic `_No tracker connected, skip step._`; few carry substantive trailing `false` block (shown) for no-tracker function.
|
|
66
|
+
|
|
67
|
+
<!-- prettier-ignore -->
|
|
68
|
+
| Interaction | Purpose | github | linear | none |
|
|
69
|
+
| --- | --- | --- | --- | --- |
|
|
70
|
+
| `rule-block` | CAUTION-block tracker/labels/comments rules | rules prose | rules prose | "not configured" stub |
|
|
71
|
+
| `issue-id-extraction` | Step 1 `ISSUE_ID` resolution. No match → stop. Never creates an issue | session prompt scan; no match → stop | session prompt scan; no match → stop | scan session prompt; else `ISSUE_ID=""` |
|
|
72
|
+
| `fid-format` | FID slug regex assertion | `^[0-9]+-[a-z0-9-]+$` | `^[a-z]+-[0-9]+-[a-z0-9-]+$` | no strict assert |
|
|
73
|
+
| `issue-read` | Read state + labels + body + comments | `issue_read` `get` / `get_comments` | `get_issue` / `list_comments` | skip (vars empty) |
|
|
74
|
+
| `issue-scan` | Bounded related-issue scan at design/plan/debug entry — writes each hit's body + comments under a `## #{number} — {title} ({state})` heading to a file (advisory, top 10, never gates); broad keyword search in title+body, all states | `search_issues` for ranking only + per-hit `issue_read` `get` / `get_comments` | `list_issues` + per-hit `list_comments` | skip stub (no scan) |
|
|
75
|
+
| `issue-update-phase` | Step 1: set phase label + active state | `issue_write` labels | `save_issue` state+labels | skip |
|
|
76
|
+
| `issue-update-review` | phase Close hand-off (non-terminal) | no-op (label carries) | `save_issue` In Review | skip |
|
|
77
|
+
| `issue-update-failed` | Failure Path additive `bkit:failed` | `issue_write` labels | `save_issue` In Review | skip |
|
|
78
|
+
| `issue-update-debug` | `/bkit-debug` Step 1 additive `bkit:debug` | `issue_write` labels | `save_issue` In Review | skip |
|
|
79
|
+
| `issue-update-merged` | Ship terminal — `bkit:merged` + In Review (issue left open; human closes) | `issue_write` `bkit:merged` (no close) | `save_issue` In Review | skip |
|
|
80
|
+
| `issue-update-status` | Projects v2 board status (best-effort) | `projects_write` add/update item | no-op (state carries) | skip |
|
|
81
|
+
| `comment-post-step` | new comment per workflow step | `add_issue_comment` | `save_comment` | skip |
|
|
82
|
+
| `issue-blockers-check` | Gate on open blockers | parse body marker → read states | `get_issue` relations | skip |
|
|
83
|
+
| `kill-switch-check` | Terminate if `bkit:auto` absent | label check | label check | inactive |
|
|
84
|
+
| `pr-body-metadata` | Parse PR-body issue/FID marker | `pull_request_read` + parse | same (GitHub PR) | FID-only, no fail-closed |
|
|
85
|
+
| `pr-body-marker` | Literal PR-body marker line | `<!-- bkit:issue=#{ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:issue={ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:fid={FID} -->` |
|
|
86
|
+
|
|
87
|
+
Phase-label set + additive-label semantics: `.bkit/workflows.md` § Tracker Integration.
|
|
88
|
+
|
|
89
|
+
## github — Projects v2 board (optional)
|
|
90
|
+
|
|
91
|
+
`issue-update-status` reads `package.json` `bkit.githubProject` = `{ owner (org login), number, statusFieldId, progressOptionId, reviewOptionId, doneOptionId }` (non-secret, committed). Absent → board sync skipped (best-effort, never gates). Discover ids once: `gh api /orgs/{owner}/projectsV2/{number}/fields --jq '.[] | select(.name=="Status")'` (Status field numeric `id` → `statusFieldId`; each option raw `id` → option id, e.g. `47fc9ee4`; `PVTSSF_…` node id from `gh project field-list` is not field id — `projects_write` rejects it). Requires `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) + `BKIT_GH_TOKEN` org Projects R/W. Org-owned boards only — fine-grained PATs cannot reach user-owned projects. `value` = single-select **option id**, not option name. Failure → retry once after 5s, then continue. `doneOptionId` is **reserved and never written** — ship terminal sets `reviewOptionId`, and a human moves the item to Done on acceptance (§ `issue-update-merged` in `.bkit/workflows.md`).
|
|
92
|
+
|
|
93
|
+
## linear — notes
|
|
94
|
+
|
|
95
|
+
Linear `ISSUE_ID`s carry team prefix (e.g. `TEAM-123`) — FID inherits (`team-123-slug`). GitHub FIDs numeric-only (`123-slug`). Cross-provider scripts must tolerate both shapes. `LINEAR_TEAM` = `bkit.linearTeam` from manifest. No separate project board — issue state (`In Progress` / `In Review` / `Done`) carries status → `issue-update-status` no-op.
|