@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.
Files changed (373) hide show
  1. package/.bkit/README.md +421 -0
  2. package/.bkit/core/.agents/context.md +95 -0
  3. package/.bkit/core/.agents/docs.md +62 -0
  4. package/.bkit/core/.agents/rules.md +147 -0
  5. package/.bkit/core/.agents/skills.md +43 -0
  6. package/.bkit/core/.bkit/LICENSE.md +151 -0
  7. package/.bkit/core/.bkit/README.md +421 -0
  8. package/.bkit/core/.bkit/cloud.md +502 -0
  9. package/.bkit/core/.bkit/comparison.md +318 -0
  10. package/.bkit/core/.bkit/install.md +496 -0
  11. package/.bkit/core/.bkit/jsonl.md +497 -0
  12. package/.bkit/core/.bkit/prompts.md +474 -0
  13. package/.bkit/core/.bkit/providers.md +598 -0
  14. package/.bkit/core/.bkit/templates.md +471 -0
  15. package/.bkit/core/.bkit/trackers.md +95 -0
  16. package/.bkit/core/.bkit/workflows.md +1546 -0
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +82 -0
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +93 -0
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +74 -0
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +115 -0
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +135 -0
  22. package/.bkit/core/.cursor/hooks/bkit-gateguard.cjs +111 -0
  23. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +169 -0
  24. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +63 -0
  25. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +225 -0
  26. package/.bkit/core/AGENTS.md +77 -0
  27. package/.bkit/core/LICENSE.md +149 -0
  28. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +272 -0
  29. package/.bkit/core/docs/templates/bkit-audit-adoption.md +223 -0
  30. package/.bkit/core/docs/templates/bkit-audit-agents.md +230 -0
  31. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +227 -0
  32. package/.bkit/core/docs/templates/bkit-audit-analytics.md +266 -0
  33. package/.bkit/core/docs/templates/bkit-audit-annotations.md +230 -0
  34. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +270 -0
  35. package/.bkit/core/docs/templates/bkit-audit-app-store.md +254 -0
  36. package/.bkit/core/docs/templates/bkit-audit-architecture.md +221 -0
  37. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +241 -0
  38. package/.bkit/core/docs/templates/bkit-audit-config.md +230 -0
  39. package/.bkit/core/docs/templates/bkit-audit-cost.md +218 -0
  40. package/.bkit/core/docs/templates/bkit-audit-coverage.md +221 -0
  41. package/.bkit/core/docs/templates/bkit-audit-database.md +229 -0
  42. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +251 -0
  43. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +283 -0
  44. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +268 -0
  45. package/.bkit/core/docs/templates/bkit-audit-documentation.md +280 -0
  46. package/.bkit/core/docs/templates/bkit-audit-duplication.md +253 -0
  47. package/.bkit/core/docs/templates/bkit-audit-failures.md +259 -0
  48. package/.bkit/core/docs/templates/bkit-audit-flakes.md +237 -0
  49. package/.bkit/core/docs/templates/bkit-audit-gates.md +250 -0
  50. package/.bkit/core/docs/templates/bkit-audit-issues.md +273 -0
  51. package/.bkit/core/docs/templates/bkit-audit-llm.md +239 -0
  52. package/.bkit/core/docs/templates/bkit-audit-logs.md +266 -0
  53. package/.bkit/core/docs/templates/bkit-audit-models.md +210 -0
  54. package/.bkit/core/docs/templates/bkit-audit-privacy.md +211 -0
  55. package/.bkit/core/docs/templates/bkit-audit-prompts.md +216 -0
  56. package/.bkit/core/docs/templates/bkit-audit-red-team.md +220 -0
  57. package/.bkit/core/docs/templates/bkit-audit-reliability.md +222 -0
  58. package/.bkit/core/docs/templates/bkit-audit-repo.md +224 -0
  59. package/.bkit/core/docs/templates/bkit-audit-security.md +274 -0
  60. package/.bkit/core/docs/templates/bkit-audit-slop.md +200 -0
  61. package/.bkit/core/docs/templates/bkit-audit-testing.md +270 -0
  62. package/.bkit/core/docs/templates/bkit-audit-usability.md +237 -0
  63. package/.bkit/core/docs/templates/bkit-plan.md +476 -0
  64. package/.bkit/core/engine/checks/after/auth.ts +247 -0
  65. package/.bkit/core/engine/checks/after/ci-yml.ts +739 -0
  66. package/.bkit/core/engine/checks/after/github.ts +424 -0
  67. package/.bkit/core/engine/checks/after/index.ts +556 -0
  68. package/.bkit/core/engine/checks/after/managed.ts +217 -0
  69. package/.bkit/core/engine/checks/after/tools.ts +427 -0
  70. package/.bkit/core/engine/checks/after/vercel.ts +101 -0
  71. package/.bkit/core/engine/checks/before/context-fetch.ts +429 -0
  72. package/.bkit/core/engine/checks/before/env.ts +201 -0
  73. package/.bkit/core/engine/checks/before/files.ts +202 -0
  74. package/.bkit/core/engine/checks/before/index.ts +206 -0
  75. package/.bkit/core/engine/checks/before/mcp.ts +127 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +77 -0
  77. package/.bkit/core/engine/checks/before/version.ts +67 -0
  78. package/.bkit/core/engine/checks/status-holes.ts +479 -0
  79. package/.bkit/core/engine/cli.ts +871 -0
  80. package/.bkit/core/engine/commands/analysis.ts +550 -0
  81. package/.bkit/core/engine/commands/ci/ci.ts +483 -0
  82. package/.bkit/core/engine/commands/comply.ts +415 -0
  83. package/.bkit/core/engine/commands/harvest.ts +459 -0
  84. package/.bkit/core/engine/commands/install/check.ts +70 -0
  85. package/.bkit/core/engine/commands/install/doctor.ts +247 -0
  86. package/.bkit/core/engine/commands/install/install.ts +528 -0
  87. package/.bkit/core/engine/commands/install/uninstall.ts +972 -0
  88. package/.bkit/core/engine/commands/install/upgrade.ts +1026 -0
  89. package/.bkit/core/engine/commands/launch.ts +139 -0
  90. package/.bkit/core/engine/commands/lib.ts +494 -0
  91. package/.bkit/core/engine/commands/registry.ts +53 -0
  92. package/.bkit/core/engine/commands/setup/setup.ts +184 -0
  93. package/.bkit/core/engine/commands/telemetry.ts +32 -0
  94. package/.bkit/core/engine/commands/workflow/branches.ts +1514 -0
  95. package/.bkit/core/engine/commands/workflow/context.ts +961 -0
  96. package/.bkit/core/engine/commands/workflow/counters.ts +268 -0
  97. package/.bkit/core/engine/commands/workflow/fids.ts +243 -0
  98. package/.bkit/core/engine/commands/workflow/issues.ts +675 -0
  99. package/.bkit/core/engine/commands/workflow/ledgers.ts +575 -0
  100. package/.bkit/core/engine/commands/workflow/locks.ts +478 -0
  101. package/.bkit/core/engine/commands/workflow/prs.ts +1087 -0
  102. package/.bkit/core/engine/commands/workflow/repo.ts +220 -0
  103. package/.bkit/core/engine/commands/workflow/roadmap.ts +576 -0
  104. package/.bkit/core/engine/commands/workflow/runs.ts +2140 -0
  105. package/.bkit/core/engine/commands/workflow/runtime.ts +300 -0
  106. package/.bkit/core/engine/commands/workflow/skills.ts +118 -0
  107. package/.bkit/core/engine/commands/workflow/status.ts +455 -0
  108. package/.bkit/core/engine/commands/workflow/steps.ts +1300 -0
  109. package/.bkit/core/engine/commands/workflow/tests.ts +161 -0
  110. package/.bkit/core/engine/commands/workflow/workflows.ts +1573 -0
  111. package/.bkit/core/engine/commands/workflow/workstreams.ts +164 -0
  112. package/.bkit/core/engine/commands/workflow/worktrees.ts +534 -0
  113. package/.bkit/core/engine/install/cloud-env.ts +925 -0
  114. package/.bkit/core/engine/install/managed-block.ts +212 -0
  115. package/.bkit/core/engine/install/manifest.ts +448 -0
  116. package/.bkit/core/engine/install/modules/claude.ts +362 -0
  117. package/.bkit/core/engine/install/modules/cloud.ts +174 -0
  118. package/.bkit/core/engine/install/modules/codex.ts +219 -0
  119. package/.bkit/core/engine/install/modules/core.ts +600 -0
  120. package/.bkit/core/engine/install/modules/cursor.ts +231 -0
  121. package/.bkit/core/engine/install/modules/index.ts +242 -0
  122. package/.bkit/core/engine/install/modules/opencode.ts +573 -0
  123. package/.bkit/core/engine/install/placeholders.ts +108 -0
  124. package/.bkit/core/engine/install/template-copies.ts +119 -0
  125. package/.bkit/core/engine/install/version-file.ts +284 -0
  126. package/.bkit/core/engine/install/write.ts +467 -0
  127. package/.bkit/core/engine/ledgers/clamp-log.ts +32 -0
  128. package/.bkit/core/engine/ledgers/status.ts +213 -0
  129. package/.bkit/core/engine/ledgers/telemetry.ts +1143 -0
  130. package/.bkit/core/engine/render/hosts.ts +372 -0
  131. package/.bkit/core/engine/render/models.ts +323 -0
  132. package/.bkit/core/engine/render/parts.ts +38 -0
  133. package/.bkit/core/engine/render/trackers.ts +170 -0
  134. package/.bkit/core/engine/shared/egress.ts +345 -0
  135. package/.bkit/core/engine/shared/json.ts +16 -0
  136. package/.bkit/core/engine/shared/log-prefix.ts +9 -0
  137. package/.bkit/core/engine/shared/package-json.ts +29 -0
  138. package/.bkit/core/engine/shared/package-manager.ts +38 -0
  139. package/.bkit/core/engine/shared/package-roots.ts +163 -0
  140. package/.bkit/core/engine/shared/protected-paths.ts +164 -0
  141. package/.bkit/core/engine/shared/settings.ts +72 -0
  142. package/.bkit/core/engine/shared/timeouts.ts +20 -0
  143. package/.bkit/core/engine/tools/wording.ts +748 -0
  144. package/.bkit/core/hooks/gateguard-edit-payload.js +18 -0
  145. package/.bkit/core/hooks/gateguard-engine.js +193 -0
  146. package/.bkit/core/hooks/guardrails-shell.js +154 -0
  147. package/.bkit/core/hooks/guardrails-tiers.js +68 -0
  148. package/.bkit/core/hooks/preflight-linear.sh +73 -0
  149. package/.bkit/core/prompts/bkit-audit-generate.md +66 -0
  150. package/.bkit/core/prompts/bkit-build-challenge-1.md +79 -0
  151. package/.bkit/core/prompts/bkit-build-challenge-2.md +81 -0
  152. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +68 -0
  153. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +70 -0
  154. package/.bkit/core/prompts/bkit-build-challenge-tests.md +73 -0
  155. package/.bkit/core/prompts/bkit-build-install-skills.md +67 -0
  156. package/.bkit/core/prompts/bkit-build-plan-current.md +75 -0
  157. package/.bkit/core/prompts/bkit-build-plan-execute.md +72 -0
  158. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +73 -0
  159. package/.bkit/core/prompts/bkit-build-plan-verify.md +88 -0
  160. package/.bkit/core/prompts/bkit-build-summary.md +93 -0
  161. package/.bkit/core/prompts/bkit-debug-abort-handover.md +90 -0
  162. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +151 -0
  163. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +78 -0
  164. package/.bkit/core/prompts/bkit-debug-failure-soak.md +73 -0
  165. package/.bkit/core/prompts/bkit-debug-summary.md +95 -0
  166. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +72 -0
  167. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +72 -0
  168. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +75 -0
  169. package/.bkit/core/prompts/bkit-design-generate.md +110 -0
  170. package/.bkit/core/prompts/bkit-design-organise.md +85 -0
  171. package/.bkit/core/prompts/bkit-design-review-1.md +121 -0
  172. package/.bkit/core/prompts/bkit-design-review-2.md +111 -0
  173. package/.bkit/core/prompts/bkit-design-spike.md +97 -0
  174. package/.bkit/core/prompts/bkit-design-summary.md +106 -0
  175. package/.bkit/core/prompts/bkit-design-update.md +66 -0
  176. package/.bkit/core/prompts/bkit-plan-complexity-check.md +66 -0
  177. package/.bkit/core/prompts/bkit-plan-complexity-split.md +87 -0
  178. package/.bkit/core/prompts/bkit-plan-generate.md +74 -0
  179. package/.bkit/core/prompts/bkit-plan-review-1.md +90 -0
  180. package/.bkit/core/prompts/bkit-plan-review-2.md +80 -0
  181. package/.bkit/core/prompts/bkit-plan-review-3.md +92 -0
  182. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +84 -0
  183. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +84 -0
  184. package/.bkit/core/prompts/bkit-plan-summary.md +106 -0
  185. package/.bkit/core/prompts/bkit-plan-update.md +68 -0
  186. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +90 -0
  187. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +94 -0
  188. package/.bkit/core/prompts/bkit-ship-summary.md +77 -0
  189. package/.bkit/core/prompts/bkit-ship-update-docs.md +71 -0
  190. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +91 -0
  191. package/.bkit/core/prompts/bkit-utility-update-decisions.md +75 -0
  192. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +76 -0
  193. package/.bkit/core/prompts/bkit-utility-update-documentation.md +61 -0
  194. package/.bkit/core/prompts/bkit-utility-update-failures.md +76 -0
  195. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +75 -0
  196. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +82 -0
  197. package/.bkit/core/workflows/bkit-auto.md +121 -0
  198. package/.bkit/core/workflows/bkit-build.md +802 -0
  199. package/.bkit/core/workflows/bkit-debug.md +642 -0
  200. package/.bkit/core/workflows/bkit-design.md +495 -0
  201. package/.bkit/core/workflows/bkit-plan.md +510 -0
  202. package/.bkit/core/workflows/bkit-ship.md +650 -0
  203. package/.bkit/shared/.bkit/.env.example +108 -0
  204. package/.bkit/shared/.claude/bkit-cloud.md +117 -0
  205. package/.bkit/shared/.claude/settings.json +88 -0
  206. package/.bkit/shared/.codex/hooks.json +26 -0
  207. package/.bkit/shared/.cursor/bkit-cloud.md +84 -0
  208. package/.bkit/shared/.cursor/hooks.json +26 -0
  209. package/.bkit/shared/.cursor/mcp.json +15 -0
  210. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +12 -0
  211. package/.bkit/shared/.gitattributes +37 -0
  212. package/.bkit/shared/.mcp.json +16 -0
  213. package/.bkit/shared/.opencode/opencode.json +62 -0
  214. package/.bkit/shared/CLAUDE.md +11 -0
  215. package/.bkit/shared/LICENSE.md +22 -0
  216. package/.bkit/shared/docs/architecture.md +19 -0
  217. package/.bkit/shared/docs/data-schema.md +19 -0
  218. package/.bkit/shared/docs/deployments.md +438 -0
  219. package/.bkit/shared/docs/design.md +39 -0
  220. package/.bkit/shared/docs/noise.md +19 -0
  221. package/.bkit/shared/docs/observability.md +25 -0
  222. package/.bkit/shared/docs/security.md +42 -0
  223. package/.bkit/shared/docs/setup.md +30 -0
  224. package/.bkit/shared/docs/technology.md +18 -0
  225. package/.bkit/shared/docs/testing.md +413 -0
  226. package/.bkit/shared/gitignore +92 -0
  227. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +192 -0
  228. package/.bkit/templates/.cursor/Dockerfile +68 -0
  229. package/.bkit/templates/.cursor/environment.json +6 -0
  230. package/.bkit/templates/.cursor/settings.json +11 -0
  231. package/.bkit/templates/.envrc +7 -0
  232. package/.bkit/templates/.github/dependabot.yml +52 -0
  233. package/.bkit/templates/.github/renovate.json5 +239 -0
  234. package/.bkit/templates/.github/workflows/bkit-ci.yml +1082 -0
  235. package/.bkit/templates/.github/workflows/bkit-cloud.yml +566 -0
  236. package/.bkit/templates/.github/workflows/bkit-renovate.yml +107 -0
  237. package/.bkit/templates/.graphifyignore +108 -0
  238. package/.bkit/templates/.husky/pre-commit +16 -0
  239. package/.bkit/templates/.husky/pre-push +91 -0
  240. package/.bkit/templates/.lintstagedrc.json +3 -0
  241. package/.bkit/templates/.prettierignore +41 -0
  242. package/.bkit/templates/.serena/project.yml +243 -0
  243. package/.bkit/templates/.vale/styles/House/Filler.yml +11 -0
  244. package/.bkit/templates/.vale/styles/House/Hedging.yml +12 -0
  245. package/.bkit/templates/.vale/styles/House/LLMSlop.yml +13 -0
  246. package/.bkit/templates/.vale/styles/House/Verbose.yml +12 -0
  247. package/.bkit/templates/.vale.ini +67 -0
  248. package/.bkit/templates/LICENSE.md +22 -0
  249. package/.bkit/templates/context/bkit-cloudrun.md +84 -0
  250. package/.bkit/templates/context/bkit-expo.md +186 -0
  251. package/.bkit/templates/context/bkit-github.md +79 -0
  252. package/.bkit/templates/context/bkit-inngest.md +45 -0
  253. package/.bkit/templates/context/bkit-maestro.md +76 -0
  254. package/.bkit/templates/context/bkit-playwright.md +62 -0
  255. package/.bkit/templates/context/bkit-resend.md +36 -0
  256. package/.bkit/templates/context/bkit-sentry.md +65 -0
  257. package/.bkit/templates/context/bkit-serena.md +33 -0
  258. package/.bkit/templates/context/bkit-stripe.md +36 -0
  259. package/.bkit/templates/context/bkit-supabase.md +59 -0
  260. package/.bkit/templates/context/bkit-tavily.md +49 -0
  261. package/.bkit/templates/context/bkit-vercel.md +64 -0
  262. package/.bkit/templates/docs/capabilities.md +72 -0
  263. package/.bkit/templates/scripts/ci/accepted-divergences.json +21 -0
  264. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +152 -0
  265. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +130 -0
  266. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +98 -0
  267. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +86 -0
  268. package/.bkit/templates/scripts/graphify/bkit-graph-drift-rules.json +23 -0
  269. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +208 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-eager-rules.json +35 -0
  271. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +236 -0
  272. package/.bkit/templates/scripts/graphify/bkit-graph-external-rules.json +17 -0
  273. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +290 -0
  274. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +19 -0
  275. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +120 -0
  276. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +232 -0
  277. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +36 -0
  278. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +927 -0
  279. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +351 -0
  280. package/.bkit/templates/scripts/launchd/ai.bkit.launchd.plist +26 -0
  281. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +53 -0
  282. package/.bkit/templates/scripts/launchd/launchd.env.example +13 -0
  283. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +275 -0
  284. package/.bkit/templates/scripts/secrets/bkit-secrets.config.mjs +66 -0
  285. package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +785 -0
  286. package/.bkit/templates/scripts/serena/bkit-serena-mcp.sh +30 -0
  287. package/.bkit/templates/scripts/serena/bkit-serena.mcp.json +9 -0
  288. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +286 -0
  289. package/.bkit/templates/slop-scan.config.json +120 -0
  290. package/CHANGELOG.md +1486 -0
  291. package/LICENSE.md +161 -0
  292. package/README.md +185 -2
  293. package/dist/checks/after/auth.js +232 -0
  294. package/dist/checks/after/ci-yml.js +718 -0
  295. package/dist/checks/after/github.js +400 -0
  296. package/dist/checks/after/index.js +447 -0
  297. package/dist/checks/after/managed.js +187 -0
  298. package/dist/checks/after/tools.js +351 -0
  299. package/dist/checks/after/vercel.js +102 -0
  300. package/dist/checks/before/context-fetch.js +426 -0
  301. package/dist/checks/before/env.js +173 -0
  302. package/dist/checks/before/files.js +185 -0
  303. package/dist/checks/before/index.js +162 -0
  304. package/dist/checks/before/mcp.js +111 -0
  305. package/dist/checks/before/repo.js +71 -0
  306. package/dist/checks/before/version.js +60 -0
  307. package/dist/checks/status-holes.js +393 -0
  308. package/dist/cli.js +692 -0
  309. package/dist/commands/analysis.js +325 -0
  310. package/dist/commands/ci/ci.js +438 -0
  311. package/dist/commands/comply.js +310 -0
  312. package/dist/commands/harvest.js +354 -0
  313. package/dist/commands/install/check.js +61 -0
  314. package/dist/commands/install/doctor.js +207 -0
  315. package/dist/commands/install/install.js +461 -0
  316. package/dist/commands/install/uninstall.js +815 -0
  317. package/dist/commands/install/upgrade.js +771 -0
  318. package/dist/commands/launch.js +118 -0
  319. package/dist/commands/lib.js +362 -0
  320. package/dist/commands/registry.js +50 -0
  321. package/dist/commands/setup/setup.js +158 -0
  322. package/dist/commands/telemetry.js +29 -0
  323. package/dist/commands/workflow/branches.js +1265 -0
  324. package/dist/commands/workflow/context.js +846 -0
  325. package/dist/commands/workflow/counters.js +227 -0
  326. package/dist/commands/workflow/fids.js +224 -0
  327. package/dist/commands/workflow/issues.js +585 -0
  328. package/dist/commands/workflow/ledgers.js +472 -0
  329. package/dist/commands/workflow/locks.js +364 -0
  330. package/dist/commands/workflow/prs.js +904 -0
  331. package/dist/commands/workflow/repo.js +199 -0
  332. package/dist/commands/workflow/roadmap.js +495 -0
  333. package/dist/commands/workflow/runs.js +1717 -0
  334. package/dist/commands/workflow/runtime.js +257 -0
  335. package/dist/commands/workflow/skills.js +110 -0
  336. package/dist/commands/workflow/status.js +392 -0
  337. package/dist/commands/workflow/steps.js +1093 -0
  338. package/dist/commands/workflow/tests.js +144 -0
  339. package/dist/commands/workflow/workflows.js +1342 -0
  340. package/dist/commands/workflow/workstreams.js +141 -0
  341. package/dist/commands/workflow/worktrees.js +473 -0
  342. package/dist/install/cloud-env.js +819 -0
  343. package/dist/install/managed-block.js +182 -0
  344. package/dist/install/manifest.js +376 -0
  345. package/dist/install/modules/claude.js +288 -0
  346. package/dist/install/modules/cloud.js +152 -0
  347. package/dist/install/modules/codex.js +193 -0
  348. package/dist/install/modules/core.js +511 -0
  349. package/dist/install/modules/cursor.js +186 -0
  350. package/dist/install/modules/index.js +152 -0
  351. package/dist/install/modules/opencode.js +504 -0
  352. package/dist/install/placeholders.js +87 -0
  353. package/dist/install/template-copies.js +106 -0
  354. package/dist/install/version-file.js +204 -0
  355. package/dist/install/write.js +342 -0
  356. package/dist/ledgers/clamp-log.js +27 -0
  357. package/dist/ledgers/status.js +156 -0
  358. package/dist/ledgers/telemetry.js +637 -0
  359. package/dist/render/hosts.js +339 -0
  360. package/dist/render/models.js +288 -0
  361. package/dist/render/parts.js +33 -0
  362. package/dist/render/trackers.js +135 -0
  363. package/dist/shared/egress.js +299 -0
  364. package/dist/shared/json.js +16 -0
  365. package/dist/shared/log-prefix.js +7 -0
  366. package/dist/shared/package-json.js +22 -0
  367. package/dist/shared/package-manager.js +32 -0
  368. package/dist/shared/package-roots.js +145 -0
  369. package/dist/shared/protected-paths.js +153 -0
  370. package/dist/shared/settings.js +44 -0
  371. package/dist/shared/timeouts.js +19 -0
  372. package/dist/tools/wording.js +680 -0
  373. package/package.json +101 -4
@@ -0,0 +1,1082 @@
1
+ # Example. Copy into the repo and own it.
2
+ # bkit install does not write this file and does not overwrite a copy.
3
+ # The job-level `env:` of bkit-tests-static is where the `[verbose ci]` commit marker is
4
+ # read; keep it if you want verbose-CI support.
5
+ name: bkit-ci
6
+
7
+ on:
8
+ workflow_dispatch:
9
+ push:
10
+ branches: [{{DEFAULT_BRANCH}}, dev]
11
+ pull_request:
12
+ branches: [{{DEFAULT_BRANCH}}, dev]
13
+
14
+ permissions:
15
+ actions: read
16
+ contents: read
17
+
18
+ # One run per branch or pull request. A newer run cancels the older one on every event
19
+ # except the default branch, which QUEUES: that run promotes the deployment, and cancelling
20
+ # it mid-promote could leave production split across two releases. A pull request
21
+ # keys on its number; a push or dispatch keys on the ref, so a PR and a push to dev still
22
+ # overlap. A shared resource those two runs both touch is serialised by the tenant lease
23
+ # (bkit-tests-reset), not by this group. A workflow_run observer sees the latest run on that
24
+ # ref only. A push plans against the last green run on the branch, not github.event.before,
25
+ # so a cancelled run's changes stay in scope.
26
+ # See docs/deployments.md § "One run per branch or pull request".
27
+ concurrency:
28
+ group: ci-${{ github.workflow }}-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || github.ref }}
29
+ cancel-in-progress: ${{ github.ref != 'refs/heads/{{DEFAULT_BRANCH}}' }}
30
+
31
+ jobs:
32
+ # ── bkit-tests-static ────────────────────────────────────────────────────
33
+ # Static-analysis lane: typecheck, format, prose lint, slop, actionlint,
34
+ # bkit check. Runs on a CLEAN tree (no test artifacts). Parallel sibling of
35
+ # bkit-tests-unit — wall-clock = MAX(lane).
36
+ bkit-tests-static:
37
+ runs-on: ubuntu-latest
38
+ # [verbose ci] marker — escalates CI log detail for one run. Composes freely with
39
+ # [force build] / [force full] / [force cache] / [skip ci] (independent contains() per marker).
40
+ # Markers are bare substrings — bkit-emitted commits prepend `bkit ` for attribution
41
+ # (e.g. `bkit [verbose ci]`); substring match honours both forms.
42
+ # See docs/deployments.md § "Commit-message force tags" for where to put the marker
43
+ # (PR title for feature-branch pushes vs commit message for direct dev/main pushes)
44
+ # and docs/testing.md § "CI verbosity" for the full knob list.
45
+ #
46
+ # BKIT_GH_TOKEN_INSTALL is declared at the job level so $BKIT_GH_TOKEN_INSTALL is available to the
47
+ # install step's `pnpm config set` (the REQUIRED GH Packages auth — pnpm >=10.34.3
48
+ # 401s on a project-.npmrc ${BKIT_GH_TOKEN_INSTALL} env-substitution) and to any later
49
+ # pnpm/npx invocation. The committed project .npmrc carries ONLY the @cbartens
50
+ # registry mapping; `pnpm config set` writes the shell-expanded literal token into
51
+ # pnpm's user-level config before install (works across pnpm 10.x/11.x). The install
52
+ # step also keeps its own env: block.
53
+ #
54
+ # NODE_OPTIONS is set HERE, in static YAML, and must NEVER be written to $GITHUB_ENV.
55
+ # The runner blocklists NODE_OPTIONS for the $GITHUB_ENV / set-env workflow command:
56
+ # the write is REJECTED with
57
+ # ##[error]Can't store NODE_OPTIONS output parameter using '$GITHUB_ENV' command.
58
+ # while the step's conclusion stays `success`. The marker test is spelled out, not
59
+ # `env.VERBOSE_CI`: the `env` context is NOT available to a job-level `env:` value. A
60
+ # step with its own `env:` block REPLACES this value rather than merging, so such a
61
+ # step must restate the flags. See docs/testing.md § "CI verbosity".
62
+ env:
63
+ TURBO_LOG_LEVEL: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && 'full' || 'errors-only' }}
64
+ VERBOSE_CI: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && '1' || '' }}
65
+ NODE_OPTIONS: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && '--trace-warnings --trace-deprecation' || '' }}
66
+ BKIT_GH_TOKEN_INSTALL: ${{ secrets.BKIT_GH_TOKEN_INSTALL }}
67
+ steps:
68
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
69
+ with:
70
+ # Full history so slop:delta can materialise the PR base ref as a worktree.
71
+ fetch-depth: 0
72
+
73
+ # Node/TS toolchain region. On a non-Node repo, replace these steps with your
74
+ # stack's setup / install commands (and the typecheck / lint / test steps below with
75
+ # its own). Replace `{{NODE_VERSION}}` with your Node major (`.bkit/templates.md`).
76
+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
77
+ with:
78
+ node-version: {{NODE_VERSION}}
79
+
80
+ # Pnpm version is resolved from the consumer's package.json#packageManager (single SoT).
81
+ # Do NOT add `with: version:` here — pnpm/action-setup errors when both are set.
82
+ - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
83
+
84
+ # Under [verbose ci]: propagate DEBUG to all subsequent steps via $GITHUB_ENV. Note
85
+ # that steps with their own `env:` block override $GITHUB_ENV — those steps must
86
+ # inline it in their env: declaration to stay verbose-aware. NODE_OPTIONS is NOT
87
+ # set here; the runner rejects that write while reporting success.
88
+ # See the job-level `env:` block above.
89
+ - name: Configure Verbose CI
90
+ if: env.VERBOSE_CI == '1'
91
+ run: |
92
+ echo "🔊 [verbose ci] marker active — escalating log detail"
93
+ echo "DEBUG=vercel:*,supabase:*" >> "$GITHUB_ENV"
94
+
95
+ # [force build] / [force cache] run the suite even when this SHA already has a green run.
96
+ - name: Check SHA Cache
97
+ id: cache
98
+ env:
99
+ GH_TOKEN: ${{ github.token }}
100
+ # User-controlled text (PR title) arrives via env: (runtime expansion,
101
+ # injection-safe) — never inlined into the run: body.
102
+ PR_TITLE: ${{ github.event.pull_request.title }}
103
+ EVENT_NAME: ${{ github.event_name }}
104
+ run: |
105
+ if [ "$EVENT_NAME" = "pull_request" ]; then
106
+ MSG="$PR_TITLE"
107
+ else
108
+ MSG=$(git log -1 --pretty=%B "$GITHUB_SHA" 2>/dev/null || echo "")
109
+ fi
110
+ case "$MSG" in
111
+ *"[force build]"*|*"[force cache]"*)
112
+ echo "skip=false" >> "$GITHUB_OUTPUT"
113
+ echo "::notice::force marker present — ignoring SHA cache."
114
+ exit 0 ;;
115
+ esac
116
+ SINCE=$(date -u -d '7 days ago' +%FT%TZ 2>/dev/null || date -u -v -7d +%FT%TZ)
117
+ PRIOR=$(gh run list \
118
+ --repo "$GITHUB_REPOSITORY" \
119
+ --workflow "$GITHUB_WORKFLOW" \
120
+ --status success \
121
+ --limit 50 \
122
+ --json headSha,createdAt \
123
+ --jq "[.[] | select(.headSha == \"$GITHUB_SHA\") | select(.createdAt > \"$SINCE\")] | length" \
124
+ 2>/dev/null || echo 0)
125
+ if [ "${PRIOR:-0}" -gt 0 ]; then
126
+ echo "skip=true" >> "$GITHUB_OUTPUT"
127
+ echo "::notice::SHA $GITHUB_SHA has $PRIOR prior green run(s) since $SINCE — skipping suite."
128
+ else
129
+ echo "skip=false" >> "$GITHUB_OUTPUT"
130
+ fi
131
+
132
+ - name: Detect Direct Push
133
+ if: steps.cache.outputs.skip != 'true'
134
+ id: detect
135
+ env:
136
+ GH_TOKEN: ${{ github.token }}
137
+ # User-controlled text (PR title) arrives via env: (runtime expansion,
138
+ # injection-safe) — never inlined into the run: body.
139
+ PR_TITLE: ${{ github.event.pull_request.title }}
140
+ EVENT_NAME: ${{ github.event_name }}
141
+ REF: ${{ github.ref }}
142
+ run: |
143
+ if [ "$EVENT_NAME" = "pull_request" ]; then
144
+ MSG="$PR_TITLE"
145
+ else
146
+ MSG=$(git log -1 --pretty=%B "$GITHUB_SHA" 2>/dev/null || echo "")
147
+ fi
148
+ case "$MSG" in *"[force cache]"*) echo "turbo_force=1" >> "$GITHUB_OUTPUT" ;; esac
149
+ case "$MSG" in *"[force build]"*) echo "should_force_build=true" >> "$GITHUB_OUTPUT" ;; esac
150
+ case "$MSG" in *"[force full]"*) echo "should_run_full=true" >> "$GITHUB_OUTPUT" ;; esac
151
+ if [ "$EVENT_NAME" = "push" ] && [ "$REF" = "refs/heads/dev" ]; then
152
+ PR_NUMBER=$(gh pr list --repo "$GITHUB_REPOSITORY" --search "$GITHUB_SHA" --state merged --json number --jq '.[0].number // ""' 2>/dev/null || echo "")
153
+ if [ -z "$PR_NUMBER" ]; then
154
+ echo "turbo_force=1" >> "$GITHUB_OUTPUT"
155
+ fi
156
+ fi
157
+
158
+ # Promotion-lag reminder (non-blocking). Renovate reads its config
159
+ # ONLY from the default branch, and scheduled / default-branch-triggered Actions run the
160
+ # default branch's copy of each workflow — so a renovate.json5 or .github/workflows/ edit
161
+ # that lands on dev but is never promoted runs STALE for everyone until a dev -> default
162
+ # branch PR lands. CI on dev validates the code; nothing otherwise checks it reached the
163
+ # default branch. Warns (never fails) on dev pushes when those consumed-from-default-branch
164
+ # surfaces differ — keyed ONLY on those surfaces, so ordinary app-code dev pushes stay
165
+ # quiet. The default branch is read at runtime, so this step is identical for every repo.
166
+ # Safe to keep in any repo: it only runs on dev pushes and self-skips when the default
167
+ # branch is dev/unset, so it never fires where the dev -> default-branch flow does not apply.
168
+ # See docs/deployments.md § "Promotion-lag warning".
169
+ - name: Check Default Branch Lags Dev
170
+ if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
171
+ env:
172
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
173
+ run: |
174
+ if [ -z "$DEFAULT_BRANCH" ] || [ "$DEFAULT_BRANCH" = "dev" ]; then
175
+ echo "::notice::promotion-lag check skipped (default branch is '$DEFAULT_BRANCH')"
176
+ exit 0
177
+ fi
178
+ if ! git fetch --no-tags --quiet origin "+refs/heads/$DEFAULT_BRANCH:refs/remotes/origin/$DEFAULT_BRANCH" 2>/dev/null; then
179
+ echo "::notice::promotion-lag check skipped — could not fetch $DEFAULT_BRANCH"
180
+ exit 0
181
+ fi
182
+ SURFACES=(.github/renovate.json5 .github/renovate.json .github/workflows)
183
+ STALE=$(git diff --name-only "origin/$DEFAULT_BRANCH" HEAD -- "${SURFACES[@]}" 2>/dev/null || true)
184
+ if [ -z "$STALE" ]; then
185
+ echo "consumed-from-$DEFAULT_BRANCH surfaces match $DEFAULT_BRANCH — nothing stale to promote."
186
+ exit 0
187
+ fi
188
+ BEHIND=$(git rev-list --count "origin/$DEFAULT_BRANCH..HEAD" 2>/dev/null || echo "?")
189
+ {
190
+ echo "### WARNING: $DEFAULT_BRANCH is serving stale consumed surfaces"
191
+ echo ""
192
+ echo "\`$DEFAULT_BRANCH\` is **$BEHIND commit(s)** behind \`dev\`, and these files — which Renovate and scheduled / default-branch Actions read LIVE from \`$DEFAULT_BRANCH\` — differ from \`dev\`:"
193
+ echo ""
194
+ printf '%s\n' "$STALE" | sed 's/^/- /'
195
+ echo ""
196
+ echo "They run the **$DEFAULT_BRANCH** version until promoted. Open a \`dev\` -> \`$DEFAULT_BRANCH\` PR to apply them."
197
+ } >> "$GITHUB_STEP_SUMMARY"
198
+ echo "::warning::$DEFAULT_BRANCH is $BEHIND commit(s) behind dev and consumed-from-$DEFAULT_BRANCH surfaces (Renovate config / workflows) differ — they run STALE until you promote dev -> $DEFAULT_BRANCH. See the run summary."
199
+
200
+ # bkit-stub:migrations-immutable — Block edits to an already-merged migration. The if: below is the
201
+ # pre-planner shape (pull_request only). Once bkit-tests-scope exists, run this on every event
202
+ # against the planner base. deployments.md § One run. To enable: uncomment and delete this header.
203
+ # - name: Assert Migrations Immutable
204
+ # if: github.event_name == 'pull_request' && steps.cache.outputs.skip != 'true'
205
+ # run: |
206
+ # git fetch origin "${{ github.base_ref }}" --depth=50 2>/dev/null || true
207
+ # CHANGED=$(git diff --name-only "origin/${{ github.base_ref }}..HEAD" -- supabase/migrations/ 2>/dev/null || true)
208
+ # EXIT=0
209
+ # for f in $CHANGED; do
210
+ # if git rev-parse "origin/${{ github.base_ref }}:$f" >/dev/null 2>&1; then
211
+ # echo "::error file=$f::Migration already exists on ${{ github.base_ref }} — migrations are immutable after merge"
212
+ # EXIT=1
213
+ # fi
214
+ # done
215
+ # exit $EXIT
216
+
217
+ - name: Install Dependencies
218
+ if: steps.cache.outputs.skip != 'true'
219
+ # Write the GH Packages auth token into pnpm's user-level config before install
220
+ # (REQUIRED — pnpm >=10.34.3 401s on a project-.npmrc ${BKIT_GH_TOKEN_INSTALL} ref).
221
+ run: |
222
+ pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"
223
+ pnpm install --frozen-lockfile
224
+ env:
225
+ BKIT_GH_TOKEN_INSTALL: ${{ secrets.BKIT_GH_TOKEN_INSTALL }}
226
+
227
+ # Static checks first — they read the source tree and must scan it CLEAN.
228
+ # Vitest/build run AFTER (below): they write coverage, dist/, and other
229
+ # artifacts that would otherwise pollute the Slop Scan and bkit check inputs.
230
+ # Keep this group (typecheck → prettier → vale → slop → bkit check) ahead of
231
+ # the test/build group if you reorder.
232
+ - name: Run Typecheck
233
+ if: steps.cache.outputs.skip != 'true'
234
+ env:
235
+ TURBO_FORCE: ${{ steps.detect.outputs.turbo_force }}
236
+ run: pnpm typecheck
237
+
238
+ - name: Run Prettier
239
+ if: steps.cache.outputs.skip != 'true'
240
+ env:
241
+ TURBO_FORCE: ${{ steps.detect.outputs.turbo_force }}
242
+ run: pnpm format:check
243
+
244
+ # vale is not on the runner and .vale/styles/ is gitignored, so without this step
245
+ # `pnpm lint:prose` guard-skips (write-good missing) and the prose gate is silently
246
+ # dead. Pinned tarball + `vale sync` (else E100: write-good missing).
247
+ - name: Install Vale
248
+ if: steps.cache.outputs.skip != 'true'
249
+ env:
250
+ VALE_VERSION: "3.9.1"
251
+ # sha256 of vale_${VALE_VERSION}_Linux_64-bit.tar.gz (from the release's checksums.txt).
252
+ # Bump alongside VALE_VERSION; verified before extract so a tampered/CDN-swapped tarball fails closed.
253
+ VALE_SHA256: "fbc2eb47d0b8c50220ed1a2c5c611fbe0904ed567d638143d482016a18fd2db0"
254
+ run: |
255
+ curl -fsSL --retry 3 --retry-all-errors "https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz" -o "$RUNNER_TEMP/vale.tar.gz"
256
+ echo "${VALE_SHA256} $RUNNER_TEMP/vale.tar.gz" | sha256sum -c -
257
+ tar -xzf "$RUNNER_TEMP/vale.tar.gz" -C "$RUNNER_TEMP" vale
258
+ echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
259
+ # vale sync pulls styles (write-good) from GitHub — retry to survive a transient CDN/network blip.
260
+ for i in 1 2 3; do
261
+ "$RUNNER_TEMP/vale" sync && break
262
+ [ "$i" = 3 ] && { echo "::error::vale sync failed after 3 attempts"; exit 1; }
263
+ echo "::warning::vale sync attempt $i failed — retrying in 5s"; sleep 5
264
+ done
265
+
266
+ - name: Run Vale Prose Lint
267
+ if: steps.cache.outputs.skip != 'true'
268
+ run: pnpm lint:prose
269
+
270
+ - name: Run Slop Scan
271
+ if: steps.cache.outputs.skip != 'true'
272
+ run: pnpm lint:slop
273
+
274
+ # The ENFORCING slop gate (lint:slop above is an advisory full-scan that never fails).
275
+ # PR-only: materialises the PR base as a worktree and fails on findings this PR ADDS or
276
+ # WORSENS vs base. Needs fetch-depth: 0 (set on checkout) so the base SHA is present.
277
+ - name: Run Slop Delta
278
+ if: steps.cache.outputs.skip != 'true' && github.event_name == 'pull_request'
279
+ env:
280
+ BASE_SHA: ${{ github.event.pull_request.base.sha }}
281
+ run: pnpm slop:delta "$BASE_SHA"
282
+
283
+ # actionlint validates .github/workflows/* with GitHub-Actions-aware rules
284
+ # (${{ }} expression syntax, shellcheck on run: blocks). A YAML linter accepts
285
+ # workflows that are valid YAML but invalid GHA; actionlint catches that class.
286
+ - name: Run actionlint
287
+ if: steps.cache.outputs.skip != 'true'
288
+ run: |
289
+ # Script pinned to the v1.7.12 commit SHA (the git tag is mutable/forgeable); the binary version
290
+ # is pinned separately via the 1.7.12 arg passed to the script below.
291
+ curl -sSfL --retry 3 --retry-all-errors https://raw.githubusercontent.com/rhysd/actionlint/914e7df21a07ef503a81201c76d2b11c789d3fca/scripts/download-actionlint.bash -o "$RUNNER_TEMP/download-actionlint.bash"
292
+ # download-actionlint.bash fetches the binary from GitHub releases — retry to survive a transient CDN/network blip.
293
+ for i in 1 2 3; do
294
+ bash "$RUNNER_TEMP/download-actionlint.bash" 1.7.12 "$RUNNER_TEMP" && break
295
+ [ "$i" = 3 ] && { echo "::error::actionlint download failed after 3 attempts"; exit 1; }
296
+ echo "::warning::actionlint download attempt $i failed — retrying in 5s"; sleep 5
297
+ done
298
+ "$RUNNER_TEMP/actionlint" -color
299
+
300
+ - name: Run bkit Check
301
+ if: steps.cache.outputs.skip != 'true'
302
+ run: pnpm bkit check
303
+
304
+ # ── bkit-tests-unit ───────────────────────────────────────────────────────
305
+ # Unit lane. Parallel sibling of bkit-tests-static. Integration, E2E, deploy-await,
306
+ # and remote db push move out of this job when you adopt the scaffold below.
307
+ bkit-tests-unit:
308
+ runs-on: ubuntu-latest
309
+ # bkit-tests-check reads both: cache_skip (a SHA-cache short-circuit asserts no count)
310
+ # and tests_ran (the executed-test count the Run Unit Tests step writes).
311
+ outputs:
312
+ cache_skip: ${{ steps.cache.outputs.skip }}
313
+ tests_ran: ${{ steps.unit.outputs.ran }}
314
+ # Env vars duplicated from bkit-tests-static's job-level `env:`.
315
+ # See the comment above that `env:` in bkit-tests-static — NODE_OPTIONS is a
316
+ # static YAML key here and never a $GITHUB_ENV write.
317
+ env:
318
+ TURBO_LOG_LEVEL: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && 'full' || 'errors-only' }}
319
+ VERBOSE_CI: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && '1' || '' }}
320
+ NODE_OPTIONS: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && '--trace-warnings --trace-deprecation' || '' }}
321
+ BKIT_GH_TOKEN_INSTALL: ${{ secrets.BKIT_GH_TOKEN_INSTALL }}
322
+ steps:
323
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
324
+ with:
325
+ # Full history needed for E2E / supabase stubs when enabled.
326
+ fetch-depth: 0
327
+
328
+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
329
+ with:
330
+ node-version: {{NODE_VERSION}}
331
+
332
+ - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
333
+
334
+ # NODE_OPTIONS is a job-level `env:` key above, never a $GITHUB_ENV write — the runner
335
+ # rejects that write and still reports success. See bkit-tests-static's block comment.
336
+ - name: Configure Verbose CI
337
+ if: env.VERBOSE_CI == '1'
338
+ run: |
339
+ echo "🔊 [verbose ci] marker active — escalating log detail"
340
+ echo "DEBUG=vercel:*,supabase:*" >> "$GITHUB_ENV"
341
+
342
+ # [force build] / [force cache] run the suite even when this SHA already has a green run.
343
+ - name: Check SHA Cache
344
+ id: cache
345
+ env:
346
+ GH_TOKEN: ${{ github.token }}
347
+ # User-controlled text (PR title) arrives via env: (runtime expansion,
348
+ # injection-safe) — never inlined into the run: body.
349
+ PR_TITLE: ${{ github.event.pull_request.title }}
350
+ EVENT_NAME: ${{ github.event_name }}
351
+ run: |
352
+ if [ "$EVENT_NAME" = "pull_request" ]; then
353
+ MSG="$PR_TITLE"
354
+ else
355
+ MSG=$(git log -1 --pretty=%B "$GITHUB_SHA" 2>/dev/null || echo "")
356
+ fi
357
+ case "$MSG" in
358
+ *"[force build]"*|*"[force cache]"*)
359
+ echo "skip=false" >> "$GITHUB_OUTPUT"
360
+ echo "::notice::force marker present — ignoring SHA cache."
361
+ exit 0 ;;
362
+ esac
363
+ SINCE=$(date -u -d '7 days ago' +%FT%TZ 2>/dev/null || date -u -v -7d +%FT%TZ)
364
+ PRIOR=$(gh run list \
365
+ --repo "$GITHUB_REPOSITORY" \
366
+ --workflow "$GITHUB_WORKFLOW" \
367
+ --status success \
368
+ --limit 50 \
369
+ --json headSha,createdAt \
370
+ --jq "[.[] | select(.headSha == \"$GITHUB_SHA\") | select(.createdAt > \"$SINCE\")] | length" \
371
+ 2>/dev/null || echo 0)
372
+ if [ "${PRIOR:-0}" -gt 0 ]; then
373
+ echo "skip=true" >> "$GITHUB_OUTPUT"
374
+ echo "::notice::SHA $GITHUB_SHA has $PRIOR prior green run(s) since $SINCE — skipping suite."
375
+ else
376
+ echo "skip=false" >> "$GITHUB_OUTPUT"
377
+ fi
378
+
379
+ - name: Detect Direct Push
380
+ if: steps.cache.outputs.skip != 'true'
381
+ id: detect
382
+ env:
383
+ GH_TOKEN: ${{ github.token }}
384
+ # User-controlled text (PR title) arrives via env: (runtime expansion,
385
+ # injection-safe) — never inlined into the run: body.
386
+ PR_TITLE: ${{ github.event.pull_request.title }}
387
+ EVENT_NAME: ${{ github.event_name }}
388
+ REF: ${{ github.ref }}
389
+ run: |
390
+ if [ "$EVENT_NAME" = "pull_request" ]; then
391
+ MSG="$PR_TITLE"
392
+ else
393
+ MSG=$(git log -1 --pretty=%B "$GITHUB_SHA" 2>/dev/null || echo "")
394
+ fi
395
+ case "$MSG" in *"[force cache]"*) echo "turbo_force=1" >> "$GITHUB_OUTPUT" ;; esac
396
+ case "$MSG" in *"[force build]"*) echo "should_force_build=true" >> "$GITHUB_OUTPUT" ;; esac
397
+ case "$MSG" in *"[force full]"*) echo "should_run_full=true" >> "$GITHUB_OUTPUT" ;; esac
398
+ if [ "$EVENT_NAME" = "push" ] && [ "$REF" = "refs/heads/dev" ]; then
399
+ PR_NUMBER=$(gh pr list --repo "$GITHUB_REPOSITORY" --search "$GITHUB_SHA" --state merged --json number --jq '.[0].number // ""' 2>/dev/null || echo "")
400
+ if [ -z "$PR_NUMBER" ]; then
401
+ echo "turbo_force=1" >> "$GITHUB_OUTPUT"
402
+ fi
403
+ fi
404
+
405
+ # bkit-stub:auto-force-e2e — Auto-trigger the full lane (E2E etc.) for PRs touching sensitive paths. Orthogonal to the [force full] marker (sets needs_e2e, OR'd with should_run_full at the e2e gate). To enable: uncomment the step below and delete this stub header.
406
+ # - name: Auto Force E2E for Sensitive Paths
407
+ # if: github.event_name == 'pull_request' && steps.cache.outputs.skip != 'true'
408
+ # id: e2e-paths
409
+ # run: |
410
+ # git fetch origin "${{ github.base_ref }}" --depth=1 2>/dev/null || true
411
+ # CHANGED=$(git diff --name-only "origin/${{ github.base_ref }}..HEAD" 2>/dev/null || echo "")
412
+ # PATTERNS=('auth/' 'migrations/' 'supabase/migrations/' 'payment/' 'api/' 'server/')
413
+ # for f in $CHANGED; do
414
+ # for p in "${PATTERNS[@]}"; do
415
+ # case "$f" in *"$p"*) echo "needs_e2e=true" >> "$GITHUB_OUTPUT"; exit 0 ;; esac
416
+ # done
417
+ # done
418
+
419
+ - name: Install Dependencies
420
+ if: steps.cache.outputs.skip != 'true'
421
+ run: |
422
+ pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"
423
+ pnpm install --frozen-lockfile
424
+ env:
425
+ BKIT_GH_TOKEN_INSTALL: ${{ secrets.BKIT_GH_TOKEN_INSTALL }}
426
+
427
+ # bkit-stub:supabase-migrate — REMOTE `db push` belongs in `bkit-tests-migration`, NOT here
428
+ # and NOT in `bkit-tests-e2e-web`. Prefer the migration-lane stub below
429
+ # (always-on; replay plan-/path-gated; push on every push to dev/main; e2e/live `needs:` it).
430
+ # Leaving the push inside e2e while live runs parallel to e2e is the PGRST202 race: @live can
431
+ # hit a shared remote whose new RPCs/schema the push has not applied yet. To enable the
432
+ # legacy single-job shape only (no migration lane yet): uncomment below, set SUPABASE_*
433
+ # secrets, delete this stub header — then migrate the step into bkit-tests-migration ASAP.
434
+ # - name: Apply Supabase Migrations to Dev
435
+ # if: github.event_name == 'push' && github.ref == 'refs/heads/dev' && steps.cache.outputs.skip != 'true'
436
+ # env:
437
+ # SUPABASE_ACCESS_TOKEN: ${{ secrets.SUPABASE_ACCESS_TOKEN }}
438
+ # SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DEV_DB_PASSWORD }}
439
+ # SUPABASE_PROJECT_REF: ${{ secrets.SUPABASE_DEV_PROJECT_REF }}
440
+ # run: |
441
+ # pnpm dlx supabase link --project-ref "$SUPABASE_PROJECT_REF"
442
+ # pnpm dlx supabase db push --linked --include-all
443
+ #
444
+ # BUILD-vs-MIGRATION RACE (latent until your first build-time DB read): if your host auto-deploys
445
+ # on this same push, its build runs UNORDERED vs this migrate step and a build-time DB read can
446
+ # ERROR the first deploy (PG 42P01/42703/42704/3F000; a redeploy of the SAME sha self-heals).
447
+ # Fix: serialise migrate -> deploy. Full mechanism + fix options: docs/deployments.md § Build-vs-migration race.
448
+
449
+ # bkit-stub:test-db — Assert schema-invariant DB checks (e.g. "every public table has RLS enabled, no hardcoded list") so they aren't app-defined. Two co-equal routes — pick by DEPLOY TOPOLOGY, not by whether you can run pgTAP locally:
450
+ # * pgTAP (this step) — fast, hermetic, offline; runs supabase/tests/*.sql against a CI-LOCAL fixture built from supabase/migrations. Caveat: that fixture can differ from prod — a migration that doesn't reproduce the live schema leaves this GREEN while prod RLS is broken. Best when there is NO deploy/@live tier, or for pure-logic DB unit tests.
451
+ # * @live catalog-RPC (JOB 3) — validates the REAL deployed schema in bkit-tests-live-web. Recommended default once you have a deploy + @live tier (RLS/tenancy especially: a passing fixture check is not evidence prod is locked down).
452
+ # To enable pgTAP: uncomment, add pgTAP files under supabase/tests/, delete this stub header.
453
+ # - name: Run DB Tests (pgTAP)
454
+ # if: steps.cache.outputs.skip != 'true'
455
+ # run: pnpm dlx supabase db test # spins up the local DB and runs supabase/tests/*.sql via pg_prove
456
+ # @live route: a SECURITY DEFINER, service_role-only catalog RPC (e.g. public.rls_coverage_gaps()) called over
457
+ # REST — direct port-5432 from CI runners is IPv4-flaky. Home: bkit-tests-live-web. docs/testing.md § Schema-invariant DB checks.
458
+
459
+ # bkit-stub:test-presence — Warn on packages with a test script but zero *.test.ts files. To enable: uncomment the step below and delete this stub header.
460
+ # - name: Check Test Presence
461
+ # if: steps.cache.outputs.skip != 'true'
462
+ # run: |
463
+ # for pkg in $(jq -r '.workspaces // [] | .[]' package.json 2>/dev/null) $(ls -d packages/*/ apps/*/ 2>/dev/null); do
464
+ # [ -f "$pkg/package.json" ] || continue
465
+ # if jq -e '.scripts.test' "$pkg/package.json" >/dev/null 2>&1; then
466
+ # COUNT=$(find "$pkg" -path '*/node_modules' -prune -o \( -name '*.test.ts' -o -name '*.test.tsx' -o -name '*.spec.ts' -o -name '*.spec.tsx' \) -print 2>/dev/null | wc -l)
467
+ # [ "$COUNT" -eq 0 ] && echo "::warning::$pkg declares a test script but has zero *.test.ts files"
468
+ # fi
469
+ # done
470
+
471
+ - name: Run Unit Tests
472
+ id: unit
473
+ if: steps.cache.outputs.skip != 'true'
474
+ env:
475
+ TURBO_FORCE: ${{ steps.detect.outputs.turbo_force }}
476
+ # Write the executed-test count as the step output `ran` so bkit-tests-check can
477
+ # prove tests ran. vitest: run with `--reporter=default --reporter=json
478
+ # --outputFile="$RUNNER_TEMP/unit.json"`, then
479
+ # `echo "ran=$(jq '[.numPassedTests, .numFailedTests] | add' "$RUNNER_TEMP/unit.json")" >> "$GITHUB_OUTPUT"`.
480
+ run: pnpm test
481
+
482
+ - name: Run Integration Tests
483
+ if: steps.cache.outputs.skip != 'true'
484
+ env:
485
+ TURBO_FORCE: ${{ steps.detect.outputs.turbo_force }}
486
+ run: |
487
+ if jq -e '.scripts["test:integration"]' package.json >/dev/null 2>&1; then
488
+ pnpm turbo run test:integration --continue
489
+ else
490
+ echo "::warning::test:integration script not found in package.json — skipping integration tests"
491
+ fi
492
+
493
+ # bkit-stub:coverage — Report vitest coverage on PRs via davelosert/vitest-coverage-report-action (free, runs entirely inside Actions with GITHUB_TOKEN — no third-party service, safe for private repos). Report-only by default: nothing fails the build until YOU set a threshold. PER-TIER: unit and integration are measured and commented SEPARATELY (a single merged number lets integration mask a hollow unit suite). To enable: make the edits below, uncomment the two steps, and delete this stub header.
494
+ # 1. devDep + config. Add `@vitest/coverage-v8` (pin to your vitest major) and a coverage block in vitest.config:
495
+ # coverage: {
496
+ # provider: 'v8',
497
+ # reporter: ['text', 'json-summary', 'json'], # json-summary + json are REQUIRED — the action reads
498
+ # reportOnFailure: true, # coverage/coverage-summary.json AND coverage-final.json
499
+ # }
500
+ # 2. TWO coverage runs into SEPARATE dirs (one merged run cannot produce two honest numbers — coverage is a union,
501
+ # so a line covered only by integration reads as covered and hides a missing unit test):
502
+ # unit: vitest run --coverage --coverage.reportsDirectory=coverage/unit --exclude '**/*.integration.test.ts'
503
+ # integration: vitest run --coverage --coverage.reportsDirectory=coverage/integration <your integration selection>
504
+ # Wire these into the "Run Unit Tests" step(s) above (or your test / test:integration scripts). Separate dirs
505
+ # also avoid the clobber a second same-dir --coverage run would cause (last-writer-wins, not a merge).
506
+ # 3. Thresholds (opt-in) live PER TIER, never merged:
507
+ # UNIT = the gate. Set coverage.thresholds.branches in the config your UNIT run uses (branches is the
508
+ # meaningful floor; line/statement % overstates confidence). Set it to your CURRENT coverage and
509
+ # ratchet up. Example: --coverage.thresholds.branches=70. vitest coverage is per-RUN (root config),
510
+ # NOT per-project — `projects` does NOT scope it, and a `thresholds` block in vitest.config reds BOTH
511
+ # runs. Pass the floor as a CLI flag on the UNIT run only (it cannot leak to integration); reach for a
512
+ # second vitest.<tier>.config.ts (run with -c) only if the per-run flags get unwieldy.
513
+ # INTEGRATION = REPORT-ONLY, no threshold. Gate integration on EXECUTION (the capstone's integration_ran > 0),
514
+ # not a %: a whole-repo integration % is denominator-noise (it covers boundaries/flows, not pure logic,
515
+ # and rarely drives every branch). For a real integration %, add --coverage.include='src/server/**'
516
+ # (a CLI flag on the integration run, same idiom as --exclude above) to scope it to the integration
517
+ # surface THEN set a floor, or ratchet from current — never a picked number. See docs/testing.md § Coverage on PRs.
518
+ # 4. JOB-LEVEL permissions on bkit-tests-unit. Job-level REPLACES the workflow-level block (not additive), and the
519
+ # Check SHA Cache step calls `gh run list`, so you MUST re-include actions: read or the cache step breaks:
520
+ # permissions:
521
+ # actions: read
522
+ # contents: read
523
+ # pull-requests: write # required to post/update the sticky PR coverage comments
524
+ # SEPARATE LANES: this stub wires both reports into bkit-tests-unit (the combined starter). If you run
525
+ # integration as its OWN lane (bkit-tests-integration — the shape bkit's own CI + consumer repos run; see the
526
+ # FULL CI SCAFFOLD REFERENCE below), move the integration coverage run + its Report step + a pull-requests: write
527
+ # permissions block into THAT lane instead. Each lane posts its own comment; the distinct name: keeps them apart.
528
+ # Fork PRs: GITHUB_TOKEN is read-only for PRs from a fork, so the steps fail — the head.repo == repo guard in the
529
+ # if: below skips them there (or adopt the action's workflow_run two-workflow pattern to support forks).
530
+ # Monorepo: set working-directory so the action finds the right report. Base-branch delta (up/down vs the default
531
+ # branch) needs the base's coverage-summary.json — see the action's json-summary-compare-path input (optional).
532
+ # The action is SHA-pinned to a commit (# vX.Y.Z comment) per best practice; your updater (Renovate/Dependabot,
533
+ # github-actions ecosystem) keeps the pin current — refresh the SHA if you enable this on a newer release.
534
+ # A distinct name: keys each sticky comment so the two do not collide.
535
+ # - name: Report Unit Coverage on PR
536
+ # if: steps.cache.outputs.skip != 'true' && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
537
+ # uses: davelosert/vitest-coverage-report-action@8b157684c6a6b259b97d45e72b44242865c0f6a5 # v2.12.2
538
+ # with:
539
+ # name: unit
540
+ # json-summary-path: coverage/unit/coverage-summary.json
541
+ # json-final-path: coverage/unit/coverage-final.json
542
+ # file-coverage-mode: changes # per-file table limited to files changed in the PR
543
+ # github-token: ${{ secrets.GITHUB_TOKEN }}
544
+ # - name: Report Integration Coverage on PR
545
+ # # hashFiles guard: skip cleanly when the repo has no integration tier (no coverage/integration report produced).
546
+ # if: steps.cache.outputs.skip != 'true' && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && hashFiles('coverage/integration/coverage-summary.json') != ''
547
+ # uses: davelosert/vitest-coverage-report-action@8b157684c6a6b259b97d45e72b44242865c0f6a5 # v2.12.2
548
+ # with:
549
+ # name: integration
550
+ # json-summary-path: coverage/integration/coverage-summary.json
551
+ # json-final-path: coverage/integration/coverage-final.json
552
+ # file-coverage-mode: changes
553
+ # github-token: ${{ secrets.GITHUB_TOKEN }}
554
+
555
+ # bkit-stub:vercel-await — Pre-split only: the host already built a preview and this step looks it up by SHA.
556
+ # Once bkit-tests-build-web publishes deployment_url, E2E reads TEST_URL from that output and this stub stays off.
557
+ # To enable the pre-split shape: uncomment, set the host secrets, delete this header.
558
+ # - name: Await Vercel Preview
559
+ # if: github.event_name == 'pull_request' && steps.cache.outputs.skip != 'true'
560
+ # id: vercel
561
+ # env:
562
+ # VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
563
+ # VERCEL_TEAM_ID: ${{ secrets.VERCEL_TEAM_ID }}
564
+ # VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
565
+ # run: |
566
+ # for i in $(seq 1 60); do
567
+ # URL=$(curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
568
+ # "https://api.vercel.com/v6/deployments?projectId=$VERCEL_PROJECT_ID&teamId=$VERCEL_TEAM_ID&meta-githubCommitSha=$GITHUB_SHA&state=READY&limit=1" \
569
+ # | jq -r '.deployments[0].url // empty')
570
+ # if [ -n "$URL" ]; then
571
+ # echo "target_url=https://$URL" >> "$GITHUB_OUTPUT"
572
+ # exit 0
573
+ # fi
574
+ # sleep 10
575
+ # done
576
+ # echo "::error::Vercel preview did not reach READY within 10 minutes"
577
+ # exit 1
578
+ #
579
+ # MIGRATION-COUPLED PRs: a preview deploy hits the SHARED dev DB, blind to a PR's unmerged migration,
580
+ # so a PR that adds+uses a column in one PR 500s pre-merge ([force full] won't help). Run feature->dev
581
+ # PR E2E against a LOCAL DB carrying this PR's migrations; keep preview E2E for pushes. Gate on head
582
+ # ref, not a flag. Full write-up: docs/testing.md § "E2E on PRs".
583
+
584
+ # bkit-stub:e2e — Run E2E gated on should_run_full ([force full] commit-tag/PR-title) or needs_e2e (auto-force-e2e). To enable: uncomment the step below and delete this stub header.
585
+ # Under bkit [verbose ci]: your test:e2e script reads VERBOSE_CI (in the job env) and
586
+ # appends --trace=on to its own `playwright test` call, so Playwright writes per-test
587
+ # trace.zip (snapshots + network + console + source) — the canonical e2e debug artifact.
588
+ # Recommended test:e2e form (package.json):
589
+ # TRACE=; [ "$VERBOSE_CI" = "1" ] && TRACE=--trace=on; playwright test $TRACE
590
+ # Do NOT pass --trace=on via a turbo / pnpm `-- --trace=on` passthrough: both append
591
+ # passthrough args to the script STRING, breaking any test:e2e that ends in a bash
592
+ # construct (fi / done / esac). Call test:e2e plainly and let it read VERBOSE_CI.
593
+ # `--video` and `--screenshot` are NOT Playwright CLI flags — they're `use:` keys in
594
+ # playwright.config.ts. Enabling standalone video / screenshot files requires editing
595
+ # the config (out of scope for this stub). Trace's snapshot timeline covers the
596
+ # dominant diagnose use case. Never pass --reporter=line — let playwright.config.ts's
597
+ # reporter chain run unmodified, otherwise verbose traces are written but no reporter
598
+ # surfaces them.
599
+ # - name: Run E2E Tests
600
+ # id: e2e
601
+ # if: (steps.detect.outputs.should_run_full == 'true' || steps.e2e-paths.outputs.needs_e2e == 'true') && steps.cache.outputs.skip != 'true'
602
+ # env:
603
+ # TARGET_URL: ${{ steps.vercel.outputs.target_url || 'http://localhost:3000' }}
604
+ # run: |
605
+ # pnpm test:e2e
606
+ #
607
+ # E2E PARITY: the full e2e suite runs on both pull_request and push — the PR runs the same spec
608
+ # set as the push. Scale a slow suite by sharding (parallel lanes). PR and push differ only by DB
609
+ # target (migration-coupled PRs) and push-only tiers (@live). See docs/testing.md § "E2E on PRs".
610
+
611
+ # bkit-stub:e2e-coverage — Report Playwright E2E code-coverage on PRs, free and entirely inside Actions (no third-party service, private-repo safe), consistent with bkit-stub:coverage above. Report-only by default. Unlike vitest there is NO --coverage flag: Playwright is black-box and does not instrument your source, so you wire a 3-part pipeline (collect -> report -> comment). To enable: build the pipeline below, uncomment the report step, delete this stub header.
612
+ # 1. COLLECT coverage during the E2E run — pick ONE route:
613
+ # a. Istanbul instrumented build (cross-browser): add `vite-plugin-istanbul` so the app under test exposes
614
+ # window.__coverage__, then scrape it in a Playwright fixture (afterEach/teardown) and pass it to Monocart.
615
+ # Works on all browsers. Ref: mxschmitt/playwright-test-coverage.
616
+ # b. V8 API (Chromium-only): page.coverage.startJSCoverage()/stopJSCoverage() in a fixture; needs source maps
617
+ # to map back to source. Ref: @bgotink/playwright-coverage.
618
+ # 2. REPORT with Monocart (`monocart-coverage-reports`, wired via the `monocart-reporter` Playwright custom
619
+ # reporter or the library directly). It ingests EITHER V8 or Istanbul input (auto-converts V8 -> Istanbul) and
620
+ # emits the SAME two Istanbul-format files the davelosert action reads, so no new commenter is needed:
621
+ # outputDir: 'coverage/e2e'
622
+ # reports: ['json-summary', 'json', 'lcov'] # json-summary is load-bearing; json enables file-coverage-mode: changes
623
+ # 3. COMMENT by reusing davelosert/vitest-coverage-report-action@v2 (same action as bkit-stub:coverage) pointed at
624
+ # coverage/e2e, with a DISTINCT name: e2e so its sticky comment does not collide with the unit/integration ones.
625
+ # If Monocart's coverage-final.json is not accepted for file-coverage-mode: changes, drop to file-coverage-mode:
626
+ # all, or comment via a cobertura commenter (irongut/CodeCoverageSummary on Monocart's `cobertura` report).
627
+ # REPORT-ONLY — ship NO threshold. A whole-app E2E % is denominator-noise (E2E exercises user flows, not every
628
+ # branch), so gate the tier on the E2E step succeeding, NOT on a number. For a real E2E %, scope Monocart's
629
+ # entryFilter/sourceFilter to the surface E2E is meant to cover, THEN ratchet from current — never a picked number.
630
+ # See docs/testing.md § E2E coverage on PRs.
631
+ # Permissions/forks/pin: this step runs in the SAME bkit-tests-unit job as bkit-stub:coverage, so it REUSES that
632
+ # stub's job-level permissions block (pull-requests: write + actions: read + contents: read) — if you enable
633
+ # e2e-coverage WITHOUT the unit/integration coverage, add that same job-level block or the comment cannot post.
634
+ # The head.repo == repo guard skips fork PRs (read-only GITHUB_TOKEN); the action is SHA-pinned to a commit
635
+ # (# vX.Y.Z comment) per best practice, kept current by your updater (Renovate/Dependabot).
636
+ # - name: Report E2E Coverage on PR
637
+ # # Same gate as Run E2E Tests (coverage exists only if E2E ran); hashFiles skips repos that produced no E2E report.
638
+ # if: (steps.detect.outputs.should_run_full == 'true' || steps.e2e-paths.outputs.needs_e2e == 'true') && steps.cache.outputs.skip != 'true' && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && hashFiles('coverage/e2e/coverage-summary.json') != ''
639
+ # uses: davelosert/vitest-coverage-report-action@8b157684c6a6b259b97d45e72b44242865c0f6a5 # v2.12.2
640
+ # with:
641
+ # name: e2e
642
+ # json-summary-path: coverage/e2e/coverage-summary.json
643
+ # json-final-path: coverage/e2e/coverage-final.json
644
+ # file-coverage-mode: changes
645
+ # github-token: ${{ secrets.GITHUB_TOKEN }}
646
+
647
+ # bkit-stub:e2e-artifacts — Upload Playwright report + per-test traces after E2E runs so /bkit-debug can fetch them. To enable: uncomment the step below and delete this stub header.
648
+ # `if: always()` captures both failure AND job-timeout cancel: Playwright's HTML reporter
649
+ # only finalises `playwright-report/index.html` at suite onEnd, but per-test trace.zip files
650
+ # in `test-results/` write incrementally and survive mid-suite SIGTERM. Without `always()`,
651
+ # cancelled runs lose all per-test traces. Under bkit [verbose ci]: per-test trace.zip lands in
652
+ # test-results/; sharded runs additionally write blob-report/ intermediate.
653
+ # - name: Upload Playwright Artifacts
654
+ # if: always()
655
+ # uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
656
+ # with:
657
+ # name: playwright-report
658
+ # path: |
659
+ # playwright-report/
660
+ # test-results/
661
+ # blob-report/
662
+ # retention-days: 14
663
+ # if-no-files-found: ignore
664
+
665
+ # ── bkit-tests-check ──────────────────────────────────────────────────────
666
+ # Capstone and sole branch-protection required check. `bkit runs gate` (/bkit-ship) merges
667
+ # only when this job is present and green at the head; `bkit setup protect-main` requires
668
+ # it. Its name is `package.json` `bkit.capstoneJob` (default bkit-tests-check).
669
+ # needs: every lane — a lane missing here cannot red the capstone. if: !cancelled(), never
670
+ # always(): a concurrency cancel must not stamp a failure. Each lane must succeed; a failed,
671
+ # skipped or cancelled lane reds it. A lane that writes an executed-test count must have run
672
+ # more than 0 tests. Each lane you adopt from the reference below joins needs: and the assert.
673
+ bkit-tests-check:
674
+ needs: [bkit-tests-static, bkit-tests-unit]
675
+ if: ${{ !cancelled() }}
676
+ runs-on: ubuntu-latest
677
+ timeout-minutes: 2
678
+ steps:
679
+ - name: Assert Lanes Passed
680
+ env:
681
+ STATIC_RESULT: ${{ needs.bkit-tests-static.result }}
682
+ UNIT_RESULT: ${{ needs.bkit-tests-unit.result }}
683
+ UNIT_RAN: ${{ needs.bkit-tests-unit.outputs.tests_ran }}
684
+ UNIT_CACHE_SKIP: ${{ needs.bkit-tests-unit.outputs.cache_skip }}
685
+ run: |
686
+ FAIL=0
687
+ if [ "$STATIC_RESULT" != "success" ]; then
688
+ echo "::error::bkit-tests-static result=$STATIC_RESULT (expected success)"
689
+ FAIL=1
690
+ fi
691
+ if [ "$UNIT_RESULT" != "success" ]; then
692
+ echo "::error::bkit-tests-unit result=$UNIT_RESULT (expected success)"
693
+ FAIL=1
694
+ fi
695
+ # NON-HOLLOW: a real run (not a SHA-cache short-circuit) of a lane that writes a count
696
+ # must have executed >0 tests. An empty count is a lane that writes none yet.
697
+ if [ "$UNIT_RESULT" = "success" ] && [ "$UNIT_CACHE_SKIP" != "true" ]; then
698
+ case "$UNIT_RAN" in
699
+ '')
700
+ echo "::warning::bkit-tests-unit writes no executed-test count — green does not prove tests ran (see its Run Unit Tests step)." ;;
701
+ *[!0-9]*)
702
+ echo "::error::bkit-tests-unit executed-test count is non-numeric ('$UNIT_RAN')."
703
+ FAIL=1 ;;
704
+ 0)
705
+ echo "::error::bkit-tests-unit succeeded but executed 0 tests — vacuous green."
706
+ FAIL=1 ;;
707
+ esac
708
+ fi
709
+ if [ "$FAIL" = "1" ]; then
710
+ echo "::error::bkit-tests-check FAILED — see above."
711
+ exit 1
712
+ fi
713
+ echo "✅ bkit-tests-check passed (static=$STATIC_RESULT, unit=$UNIT_RESULT, unit tests executed=${UNIT_RAN:-unreported})."
714
+
715
+ # bkit-stub:smoke — Post-CI smoke triggered by workflow_run on {{DEFAULT_BRANCH}}. To enable: copy the YAML below into .github/workflows/smoke.yml (separate file — workflow_run cannot share a file with push/pull_request) and delete this stub header.
716
+ # name: Smoke
717
+ # on:
718
+ # workflow_run:
719
+ # workflows: ["CI"]
720
+ # types: [completed]
721
+ # branches: [{{DEFAULT_BRANCH}}]
722
+ # jobs:
723
+ # smoke:
724
+ # if: github.event.workflow_run.conclusion == 'success'
725
+ # runs-on: ubuntu-latest
726
+ # steps:
727
+ # - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
728
+ # - run: ./scripts/ci/smoke-test.sh
729
+
730
+ # =============================================================================
731
+ # FULL CI SCAFFOLD REFERENCE — job graph, needs, if, step names. This is the target.
732
+ # The jobs above are the any-repo starter. A starter stub still inside bkit-tests-unit
733
+ # (e2e, vercel-await, supabase-migrate, immutability pull_request-only) is the pre-split
734
+ # shape — follow this reference when you add the lane. Adopt order: docs/testing.md
735
+ # § CI test tiers. Concurrency, push base, run levels, promotion, markers: docs/deployments.md.
736
+ # Order: static checks before env pull; build-web publishes the URL before E2E; capstone last.
737
+ # Tags: [U] in the starter above; [M]onorepo [D]eploy [E]2E [DB] opt-in.
738
+ # Tool names (turbo, Vercel, Supabase, Playwright) are examples.
739
+ #
740
+ # green == validated. testing.md § Validated means executed.
741
+ # Expression cap: a comment inside `run: |` counts toward 21,000 chars; a # comment does not.
742
+ # Long logic → a script. deployments.md § Workflow-file limits.
743
+ #
744
+ # ORDER + gating (needs: + result guards). Each TIER is its own parallel LANE (job) — the proven
745
+ # shape bkit's own bkit-ci.yml (bkit-tests-static/unit/integration) and consumer repos run;
746
+ # NOT steps in one monolithic tests job. Bring a lane to life only if that tier applies to your repo.
747
+ #
748
+ # The graph is FLAT AND WIDE for static/unit/build/integration: scope fans out, capstone joins.
749
+ # ONE deliberate exception: when the migration lane owns the shared-remote
750
+ # `db push`, `bkit-tests-e2e-web` and `bkit-tests-live-web` `needs:` that lane so they cannot hit a schema
751
+ # the push has not applied yet (and a from-empty replay failure cannot reach remote). Do NOT add
752
+ # edges from live/e2e back onto static/unit/build — those remain the expensive wall-clock trap.
753
+ #
754
+ # bkit-tests-scope ─┬─ bkit-tests-static
755
+ # always-on, ├─ bkit-tests-unit
756
+ # never skips ├─ bkit-tests-build-web ───────────────────┐
757
+ # (~15s) ├─ bkit-tests-integration │
758
+ # ├─ bkit-tests-build-ios │
759
+ # ├─ bkit-tests-build-android │
760
+ # └─ bkit-tests-migration ─┬─→ bkit-tests-deploy (push to {{DEFAULT_BRANCH}} only; promotes)
761
+ # always-on │ │ (own concurrency group; not required)
762
+ # (replay plan-/path- │ ▼
763
+ # gated; remote push └─→ bkit-tests-reset ──┬─→ bkit-tests-e2e-web
764
+ # on every push to (lease + ├─→ bkit-tests-live-web
765
+ # dev/main; on the known state)├─→ bkit-tests-e2e-ios
766
+ # default branch waits └─→ bkit-tests-e2e-android
767
+ # for the basic lanes)
768
+ # │
769
+ # ▼
770
+ # bkit-tests-cleanup (always(); releases the lease)
771
+ # │
772
+ # ▼
773
+ # bkit-tests-check (needs: scope + ALL lanes, deploy included; if: !cancelled())
774
+ #
775
+ # Suffix rule: a lane takes a platform suffix when that tier exists for more than one
776
+ # platform. static / unit / integration / migration stay bare. build and e2e are
777
+ # -web / -ios / -android. @live is -web — device flows are the e2e lanes, not a second live lane.
778
+ # Adopt only the lanes this repo has. A missing optional lane is not a gap.
779
+ #
780
+ # static/unit/integration/build-*: needs:[bkit-tests-scope]; if: run_level != 'none'
781
+ # bkit-tests-migration: needs:[bkit-tests-scope]; NO job-level if: (always-on)
782
+ # bkit-tests-deploy: needs:[bkit-tests-migration, bkit-tests-build-web];
783
+ # push to {{DEFAULT_BRANCH}} only; own `concurrency:` group
784
+ # bkit-tests-reset: needs:[scope, migration]; if: tenant_target != ''
785
+ # e2e-web / live-web / e2e-ios / e2e-android:
786
+ # needs:[scope, migration, deploy, reset, <build lane>];
787
+ # if: !cancelled() && scope==success && <own gate>
788
+ # && migration != 'failure' && deploy != 'failure'
789
+ # && reset != 'failure'
790
+ # (!= 'failure' — not == 'success' — so a cancelled/skipped
791
+ # migration, deploy or reset does not cascade-skip the lane)
792
+ #
793
+ # Do not gate bkit-tests-live-web behind static/unit/integration/e2e. Measure the pole first.
794
+ # deployments.md § Parallel test lanes.
795
+ #
796
+ # `bkit install` / `bkit check` raises an advisory per `# bkit-stub:` below. Delete the header to dismiss.
797
+ #
798
+ # === JOB 1 — planner (always-on) ===
799
+ # bkit-stub:bkit-tests-scope — emits the bkit-test-plan JSON. WHEN: CI has >1 run-type (PR/
800
+ # dev-push/release) or any skippable tier. Single-package repo: drop the [M] steps; the
801
+ # plan comes from markers and the event alone.
802
+ # bkit-tests-scope: runs-on: ubuntu-latest; timeout-minutes: 2; outputs: { plan: ${{ steps.scope.outputs.plan }} }
803
+ # steps:
804
+ # - name: Checkout Repository # [M] fetch-depth: 0 (turbo diffs need the base commit)
805
+ # - name: Install Turbo # [M] npm i -g turbo@<ver> (bare, ~10-15s; no pnpm install)
806
+ # - name: Resolve Base Ref # [M] push base = the branch's last green run; shipped:
807
+ # # scripts/ci/lanes/resolve-push-base.mjs (falls back to github.event.before). deployments.md
808
+ # # § One run per branch or pull request.
809
+ # bkit-stub:affected-graph — [M] turbo changed-packages. Stdout ≠ stderr. deployments.md § turbo `//`.
810
+ # - name: Detect Affected Packages # [M] sets web_affected / global_dep_changed
811
+ # - name: Read Markers # [U] one parse; lanes read plan.markers_present. deployments.md § Commit-message force tags.
812
+ # - name: Decide Run # [U] Layer 1 (whether): [skip ci] or affected-empty -> run_level=none
813
+ # - name: Decide Run Level # [U] force-build / PR / dispatch / push to default -> full.
814
+ # # push to dev from a merged PR -> partial. Direct dev push (no PR) -> full. api-error/403 -> full.
815
+ # # deployments.md § Run-level decision matrix. Needs pull-requests: read.
816
+ # - name: Decide Run Live & E2E # [D/E] web_affected_eff = web_affected || [force full] (emit as plan.web_affected — drives integration/e2e/@live + the capstone uniformly).
817
+ # # run_e2e = run_level==full && web_affected_eff. run_live = push dev/main && web_affected_eff (@live stays PUSH-ONLY — real LLM/email side effects; a docs-only/empty [force full] push reaches it via web_affected_eff, NOT off a PR/dispatch).
818
+ # # run_migration: true when migration/seed/seed-generator paths changed (or workflow_dispatch / no-usable-base → run-to-be-safe). Orthogonal to run_level — a run_level=none run can still need replay. Emits into the plan so migration-lane heavy steps gate per-step (job stays always-on).
819
+ # - name: Decide Release Mirror # [U] OPTIONAL — one CI run per dev commit. mirror_push_run = pull_request
820
+ # # && head.repo.full_name == github.repository && head_ref == 'dev' && base_ref == the default branch
821
+ # # (head_ref via env:, injection-safe). True → LAST word in the plan: run_level=none, run_e2e/run_live/
822
+ # # run_migration/web_affected=false, so every lane skips (migration lane included — it is always-on, so
823
+ # # its replay steps must read run_migration) and the capstone copies the dev push run's verdict (JOB 4).
824
+ # # The release PR head IS the dev tip that push run is testing; re-testing it doubles the slowest run.
825
+ # # PRECONDITIONS — mirroring copies whatever the push run validated, so adopt only when:
826
+ # # (1) a dev push resolves run_level=full — drop the merged-PR → partial arm above (a partial push run
827
+ # # has no E2E, and the release PR would inherit that);
828
+ # # (2) a push run's diff base is the head of the LAST GREEN push run on the branch, not
829
+ # # github.event.before — else a red run followed by an unrelated commit plans a green run that
830
+ # # never re-tests what the red one broke, and the mirror copies that green;
831
+ # # (3) promotion hangs off the push to the default branch (bkit-tests-deploy, JOB 5), never off
832
+ # # the PR check — the mirror is a merge gate, the default-branch push run is the release gate.
833
+ # # Fork PRs and every other head/base pair keep the normal plan. Field is REQUIRED in the plan (false
834
+ # # when off) so the capstone can read it. See docs/deployments.md § "One CI run per dev commit".
835
+ # - name: Generate Test Plan # [U] id: scope. jq has()/!=null, never `//`. deployments.md § One run.
836
+ # - name: Upload Test Plan # [U] plan-table -> $GITHUB_STEP_SUMMARY (if: !cancelled())
837
+ # - name: Write Cancellation Notice # [U] if: cancelled() — note instead of a blank summary
838
+ #
839
+ # === JOB 2: one job per tier. Distribute the steps below. Each lane: own checkout + setup + install. ===
840
+ # static/unit/integration/build-*: needs:[bkit-tests-scope]; if: run_level != 'none'; timeout-minutes: 20
841
+ # Emit <tier>_ran from the runner summary. Capstone asserts >0. testing.md § Validated means executed.
842
+ # deployments.md § Parallel test lanes.
843
+ # env: [D] scope TURBO_TOKEN/VERCEL_*/SUPABASE_* here (least-privilege); KEEP the verbose-CI job-level `env:` from the starter's bkit-tests-static.
844
+ # steps:
845
+ # - name: Checkout Repository # [U] fetch-depth: 0 only if running slop-scan delta
846
+ # - name: Fetch Base Branch # [M/PR] if: pull_request — base for --filter/diffs
847
+ # - name: Assert Migrations Immutable # [DB] EVERY event, against the planner's base (PR base, or a
848
+ # # push's last green run). Fail if an already-merged migration was edited (write a new one).
849
+ # - name: Materialise Base Worktree # same base, for slop-delta; loud-fail if it resolves to HEAD
850
+ # - name: Setup pnpm # [U]
851
+ # - name: Setup Node # [U] node-version: {{NODE_VERSION}}, cache: pnpm
852
+ # - name: Configure Verbose CI # [U] NODE_OPTIONS is job-level env, never $GITHUB_ENV. testing.md § CI verbosity.
853
+ # - name: Install Dependencies # [U] pnpm install --frozen-lockfile
854
+ # - name: Install Vale # [U] pinned tarball + `vale sync` (else E100: write-good missing)
855
+ # - name: Run Lint # [U] static checks FAIL-FAST before env pull; PRs scope --filter=...[origin/<base>]
856
+ # - name: Run Typecheck # [U]
857
+ # - name: Run Prettier # [U] CI-side format gate (hook-bypass net)
858
+ # - name: Run Vale Prose Lint # [U] same root lint:prose pre-push runs (local==CI)
859
+ # - name: Run Slop Scan (full) # [U] advisory baseline
860
+ # - name: Run Slop Scan (delta) # every event, against the planner base. deployments.md § One run.
861
+ # - name: Tear Down Base Worktree # if: always()
862
+ # - name: Run bkit Check # [U] drift gate (same as pre-push); catches --no-verify/web-edit/cloud drift
863
+ # - name: Check Accepted Divergences # [U] node scripts/ci/check-accepted-divergences.mjs — every event-keyed step is registered; stale rows fail too. testing.md § Accepted divergences.
864
+ # - name: Pull Vercel Env Vars # [D] preview vs prod env by branch; set CI_ENV_FILE; FAIL-FAST if critical secrets empty
865
+ # - name: Assert Environment Shape # [D] env-shape checker (e.g. env-check.sh)
866
+ # # Resolve URL and remote db push are NOT steps in this catalogue.
867
+ # # URL: bkit-tests-build-web publishes deployment_url. db push: bkit-tests-migration.
868
+ # # Race if the host still auto-deploys: deployments.md § Build-vs-migration race.
869
+ # bkit-stub:test-db — [DB] schema invariants ("every public table has RLS" etc., not app-defined). Two co-equal
870
+ # # routes by deploy topology: pgTAP (`supabase db test` over supabase/tests/*.sql) against a CI-LOCAL fixture
871
+ # # — fast/offline but can pass while prod drifts; OR a service_role-only catalog RPC from the @live tier
872
+ # # against the REAL deployed schema in bkit-tests-live-web — the stronger check once you have a deploy.
873
+ # # docs/testing.md § Schema-invariant DB checks.
874
+ # - name: Run DB Tests (pgTAP) # [DB] if: schema invariants matter; runs supabase/tests/*.sql
875
+ # - name: Run Unit Tests # [U] the one tier every repo has (source CI_ENV_FILE if needed)
876
+ # - name: Report Coverage on PR # [U/PR] bkit-stub:coverage — davelosert/vitest-coverage-report-action posts a per-tier coverage comment (distinct name: unit|integration|e2e). With SEPARATE lanes each posts from its OWN lane: unit-cov here (gated on branches), integration-cov in bkit-tests-integration (report-only, gate-on-execution), e2e-cov in bkit-tests-e2e-web (bkit-stub:e2e-coverage, Monocart). Each lane needs job-level pull-requests: write + the json-summary/json reporters.
877
+ # - name: Build All Packages # moves to bkit-tests-build-web. Not this catalogue.
878
+ # - name: Run Integration Tests # moves to bkit-tests-integration. Not this catalogue.
879
+ # - name: Check Stale Test Data # [DB] continue-on-error. Lives in the lane that touches the shared resource.
880
+ # # E2E, await, and upload move to bkit-tests-e2e-web. testing.md § E2E on PRs.
881
+ #
882
+ # Design is not a lane. testing.md § Design assertions. docs/design.md § Machine-checked reference.
883
+ #
884
+ # === JOB 2a — integration lane (distribute JOB 2's integration steps into their OWN job) ===
885
+ # bkit-stub:bkit-tests-integration — [D] the integration tier as its OWN parallel lane (job), not a
886
+ # step in bkit-tests-unit. WHEN: you have *.integration.test.ts (multi-module wiring / real infra
887
+ # boundaries). Mirrors bkit's own bkit-tests-integration lane + consumer repos. Self-contained
888
+ # (own checkout/setup/install); gate heavy steps on web_affected; emit integration_ran; the
889
+ # bkit-stub:coverage integration report (report-only, name: integration) posts from HERE, not bkit-tests-unit.
890
+ # bkit-tests-integration: needs:[bkit-tests-scope]; if: run_level != 'none'; timeout-minutes: 20
891
+ # # own job-level permissions: { actions: read, contents: read, pull-requests: write } for the coverage comment.
892
+ # steps: Checkout / Setup pnpm+Node / Install → Build (if needed) → Run Integration Tests
893
+ # (id: vitest; --continue so one failure doesn't mask the rest; --reporter=json → integration_ran) →
894
+ # Report Integration Coverage on PR (davelosert, name: integration). Step detail: JOB 2 catalogue above.
895
+ #
896
+ # === JOB 2d — web build lane ===
897
+ # bkit-stub:bkit-tests-build-web — [D] the web build as its OWN lane. WHEN: a later lane tests this
898
+ # commit's deployment, or a compile break should report on its own. The suffix is required once
899
+ # ios / android build lanes exist; use it even if you only have web, so the name does not move later.
900
+ # Two shapes, pick one:
901
+ # (a) Compile. Checkout / setup / install → build the workspace. TIME-TO-SIGNAL: a compile break
902
+ # reds here instead of inside a longer lane. Emits no *_ran count.
903
+ # (b) Host deployment gate (e.g. Vercel). Do not compile. Create this SHA's deployment, poll it
904
+ # to ready, publish deployment_url + deployment_id. On the default branch the deployment stays
905
+ # UN-promoted until bkit-tests-deploy (JOB 5). A guard fails if the production alias already
906
+ # serves this run's new deployment id.
907
+ # bkit-tests-build-web: needs:[bkit-tests-scope]; if: run_level != 'none'; timeout-minutes: 20
908
+ # Fold into bkit-tests-check's needs:.
909
+ #
910
+ # === JOB 2c — web E2E lane ===
911
+ # bkit-stub:bkit-tests-e2e-web — [E] browser E2E as its OWN lane. WHEN: you have a browser suite and
912
+ # a deploy or a local stack to hit. e.g. Playwright. Self-contained. Gate on run_e2e && web_affected.
913
+ # Emit e2e_ran. Coverage comment (bkit-stub:e2e-coverage) posts from HERE.
914
+ # Do NOT put remote db push in this lane — that lives in bkit-tests-migration.
915
+ # A feature → dev PR runs against a local stack with this PR's migrations. Every other event tests
916
+ # the deployment bkit-tests-build-web published. Same outcome rules on every machine: retries, traces,
917
+ # flake handling. A pass on retry is a failure. The target comes from TEST_URL alone. No spec is
918
+ # filtered by tag.
919
+ # bkit-tests-e2e-web:
920
+ # needs: [bkit-tests-scope, bkit-tests-migration, bkit-tests-reset, bkit-tests-build-web]
921
+ # if: >-
922
+ # ${{ !cancelled()
923
+ # && needs.bkit-tests-scope.result == 'success'
924
+ # && fromJSON(needs.bkit-tests-scope.outputs.plan).run_e2e
925
+ # && needs.bkit-tests-migration.result != 'failure'
926
+ # && needs.bkit-tests-reset.result != 'failure'
927
+ # && needs.bkit-tests-build-web.result != 'failure' }}
928
+ # timeout-minutes: 30
929
+ # # own job-level permissions block (same three) for the coverage comment.
930
+ # steps: Checkout / Setup / Install → Run E2E Tests (TEST_URL from bkit-tests-build-web;
931
+ # do not also run bkit-stub:vercel-await) → Report E2E Coverage → Upload report (if: always()).
932
+ # Fan-out: testing.md § Concurrent invocations. Shared identity and per-request cost: deployments.md § Parallel test lanes.
933
+ #
934
+ # === JOB 2e — shared resource: reset first, clean up last ===
935
+ # bkit-stub:bkit-tests-reset — [D/DB] WHEN: 2+ lanes use ONE long-lived resource (demo tenant, seeded
936
+ # account, fixture bucket). Prefer provisioning a fresh resource per run (testing.md § Provision
937
+ # backing services fresh) and DROP both jobs below. When the resource is shared:
938
+ # bkit-tests-reset runs AFTER scope + migration, BEFORE any lane that uses the resource. It takes
939
+ # a lease, then puts the resource in its known state. Every such lane needs: it and does not start
940
+ # if it failed. The planner names at most one target ("" | preview | production). Two targets is a
941
+ # planner failure, not a matrix. Production is legal only on the default branch. An empty target
942
+ # skips both jobs. The lease is what makes an overlapping PR and dev push safe: a run uses the
943
+ # resource only between its reset and its cleanup. The laptop runner calls the same commands.
944
+ # bkit-tests-reset:
945
+ # needs: [bkit-tests-scope, bkit-tests-migration]
946
+ # if: !cancelled() && scope==success && migration != 'failure' && plan.tenant_target != ''
947
+ # timeout-minutes: 160 # covers the lease wait
948
+ # bkit-stub:bkit-tests-cleanup — the other half. Runs LAST, if: always(), after every lane that used
949
+ # the resource. Puts it back and releases the lease, including when a lane failed or this run was
950
+ # cancelled. Does not touch a resource another run holds. When this run's reset never took the lease,
951
+ # finish quietly — the reset job is already red.
952
+ # bkit-tests-cleanup:
953
+ # needs: [bkit-tests-scope, bkit-tests-reset, <every tenant lane>]
954
+ # if: always() && scope==success && reset != 'skipped' && plan.tenant_target != ''
955
+ # timeout-minutes: 15
956
+ # Capstone reds when a planned reset skipped, or when reset or cleanup failed. Neither job emits a
957
+ # *_ran count. Exempt both BY NAME from any guard that treats every bkit-tests-* job as a counting lane.
958
+ # Job names do not grow a matrix suffix.
959
+ #
960
+ # === JOB 2b — migration lane (always-on ordering + provisioning) ===
961
+ # bkit-stub:bkit-tests-migration — [DB] always-on. No job-level if:. Replay + remote push.
962
+ # testing.md § Provision backing services fresh. Capstone asserts success whenever scope succeeded.
963
+ # bkit-tests-migration: needs:[bkit-tests-scope]; timeout-minutes: 15
964
+ # # NO job-level if:. Optional env: RUN_MIGRATION: ${{ fromJSON(...plan).run_migration }}
965
+ # steps:
966
+ # - name: Checkout Repository # fetch-depth: 0 when using in-job Detect
967
+ # - name: Detect Migration/Seed Changes # OPTIONAL if planner emits run_migration; else id: detect
968
+ # # relevant=true/false. dispatch + no-usable-base => run-to-be-safe; PR => vs origin/<base>;
969
+ # # push => vs the planner's base (last green run), over migrations/ + seed + seed-generator paths.
970
+ # - name: Install Supabase CLI # [DB] if: RUN_MIGRATION || push-to-dev/main — needed by BOTH paths
971
+ # - name: Provision Ephemeral DB # [DB] if: RUN_MIGRATION / relevant — e.g. supabase start --exclude …
972
+ # - name: Replay Migrations From Empty # [DB] if: RUN_MIGRATION / relevant — e.g. supabase db reset --local
973
+ # - name: Assert Seed Fixture Loaded # [DB] if: RUN_MIGRATION / relevant — known seed row must exist
974
+ # - name: Apply Remote Migrations # [DB] if: push to dev/main — UN-gated by run_migration
975
+ # # (self-heals a remote left behind by an earlier failed run). AFTER replay steps so a
976
+ # # from-empty failure never reaches shared remote. e.g. link + db push --linked --include-all
977
+ # # (resolve project ref via vercel env pull or SUPABASE_* secrets — same pattern as drift checks).
978
+ # - name: Tear Down # if: always() && (RUN_MIGRATION / relevant) — push-only runs never started Docker
979
+ #
980
+ # === JOB 2f — device build + device E2E (optional; drop the platforms you do not ship) ===
981
+ # Same rule on a PR, a dev push, a default-branch push, and a dispatch. These are NOT post-merge
982
+ # canaries: a change that affects the device app, a native dependency change, or a platform marker
983
+ # runs the build and the device flows, and a red lane reds bkit-tests-check. @live stays push-only.
984
+ # e.g. EAS for the build, Maestro for the flows. A dispatch input (default false) is how a human
985
+ # forces a fresh native build; a marker cannot, because markers are inert on workflow_dispatch.
986
+ # bkit-stub:bkit-tests-build-ios — needs:[bkit-tests-scope]; if: plan.run_native_ios
987
+ # bkit-stub:bkit-tests-build-android — needs:[bkit-tests-scope]; if: plan.run_native_android
988
+ # bkit-stub:bkit-tests-e2e-ios — needs: [bkit-tests-scope, bkit-tests-migration, bkit-tests-reset, bkit-tests-build-ios, bkit-tests-build-web].
989
+ # if: !cancelled() && scope==success && build-ios==success && migration != 'failure'
990
+ # && reset != 'failure' && build-web != 'failure' && plan.run_native_ios
991
+ # bkit-stub:bkit-tests-e2e-android — same shape, android tokens.
992
+ # `!cancelled()` switches off GitHub's default skip-on-failed-needs, so name each needs.result
993
+ # in the if:. A build lane that succeeds without a build id (quota exhausted, reuse) still lets
994
+ # the e2e job start; the flow steps inside gate on the id. Emit native_e2e_ran (flows that reached
995
+ # a verdict). Fold all four into bkit-tests-check's needs:.
996
+ #
997
+ # === JOB 2g — logging probe (a step, not a lane) ===
998
+ # bkit-stub:logging-probe — WHEN: a runtime can emit a log and an API can read it back. Inside each
999
+ # such lane (bkit-tests-e2e-web, bkit-tests-live-web, bkit-tests-e2e-ios, bkit-tests-e2e-android),
1000
+ # one step emits a single marked event and a later step asks the tracker whether that marker arrived.
1001
+ # e.g. Sentry. Skip the check when this run did not execute the probe. A missing marker reds the lane.
1002
+ # DROP if you have no error tracker.
1003
+ #
1004
+ # === JOB 3 — @live canary (web) ===
1005
+ # bkit-stub:bkit-tests-live-web — push-only @live vs the DEPLOYED url. WHEN: you have a deploy.
1006
+ # DROP if no deploy (bkit does). The -web suffix matches the build/e2e suffix rule.
1007
+ # /bkit-ship still filters a job named bkit-tests-live. This lane's name does not match that filter,
1008
+ # so a planned @live failure is fatal through the capstone, not an advisory.
1009
+ # bkit-tests-live-web:
1010
+ # needs: [bkit-tests-scope, bkit-tests-migration, bkit-tests-reset, bkit-tests-build-web]
1011
+ # if: >-
1012
+ # ${{ !cancelled()
1013
+ # && needs.bkit-tests-scope.result == 'success'
1014
+ # && fromJSON(needs.bkit-tests-scope.outputs.plan).run_live
1015
+ # && needs.bkit-tests-migration.result != 'failure'
1016
+ # && needs.bkit-tests-reset.result != 'failure'
1017
+ # && needs.bkit-tests-build-web.result != 'failure' }}
1018
+ # timeout-minutes: 15
1019
+ # # needs: scope + migration + reset + build-web. Not static/unit/integration/e2e.
1020
+ # # deployments.md § Parallel test lanes.
1021
+ # steps:
1022
+ # - name: Checkout Repository / Setup pnpm / Setup Node / Configure Verbose CI / Install Dependencies # [U] same setup chain as bkit-tests
1023
+ # - name: Pull Vercel Env Vars # [D] same branch-conditional env pull
1024
+ # - name: Run Live Tests # emit live_ran. testing.md § Validated means executed, § Schema-invariant DB checks.
1025
+ #
1026
+ # === JOB 4 — capstone (makes green == validated) ===
1027
+ # The starter bkit-tests-check above grows into this as lanes land. THE sole branch-protection
1028
+ # required check. ~seconds; needs no checkout UNTIL you extract the gate (below).
1029
+ # bkit-tests-check: needs:[bkit-tests-scope,bkit-tests-static,bkit-tests-unit,bkit-tests-build-web,bkit-tests-integration,bkit-tests-e2e-web,bkit-tests-migration,bkit-tests-live-web,bkit-tests-build-ios,bkit-tests-e2e-ios,bkit-tests-build-android,bkit-tests-e2e-android,bkit-tests-reset,bkit-tests-cleanup]; if: ${{ !cancelled() }}; timeout-minutes: 2 (mirror mode: see Mirror Push Run)
1030
+ # # needs: EVERY lane you actually have — a lane missing from needs: is a lane whose failure
1031
+ # # cannot red the capstone, which is the hollow-green this job exists to prevent.
1032
+ # # !cancelled() not always(): a concurrency cancel must not stamp a failure.
1033
+ # steps:
1034
+ # - name: Mirror Push Run # OPTIONAL (Decide Release Mirror in JOB 1). if: plan.mirror_push_run. Runs BEFORE
1035
+ # # the assert below; NEITHER continue-on-error. Needs a checkout and installed dependencies (it runs bkit) — ungated.
1036
+ # # run: pnpm bkit runs mirror --head="$PR_HEAD_SHA" --branch=dev --max-minutes=170
1037
+ # # (PR_HEAD_SHA: github.event.pull_request.head.sha via env:; GH_TOKEN: github.token — needs actions: read.)
1038
+ # # Waits for the dev push run at the PR head and passes only when that run's capstone passed; reds when it
1039
+ # # failed, was cancelled, its capstone is absent/skipped, or no push run appears within 10 min (a [skip ci]
1040
+ # # tip dispatches none). Every lane is skipped in this mode, so the assert below accepts the plan and this
1041
+ # # step IS the verdict — never `run_level=none` alone: a skipped required check can read as passed on the PR.
1042
+ # # Raise the job timeout ONLY in this mode, null-safe for a planner that failed before emitting a plan:
1043
+ # # timeout-minutes: ${{ needs.bkit-tests-scope.outputs.plan && fromJSON(needs.bkit-tests-scope.outputs.plan).mirror_push_run && 180 || 5 }}
1044
+ # # (180 > the command's --max-minutes 170 > your slowest push run, so a timeout names its cause.)
1045
+ # # A red push run re-run to green does NOT update the PR: re-run this job afterwards.
1046
+ # - name: Assert Test Plan Followed # script, not a heredoc. testing.md § Validated means executed.
1047
+ # # scope==success always. run_level!=none => static+unit+build-web success.
1048
+ # # web_affected => integration success. run_e2e && web_affected => e2e-web success.
1049
+ # # run_live => live-web success. plan.run_native_<platform> => that build + e2e success.
1050
+ # # planned reset skipped, or reset/cleanup failed => red. A skipped or failed deploy on a
1051
+ # # default-branch push => red. run_level==none ([skip ci]; release mirror) asserts nothing —
1052
+ # # in mirror mode Mirror Push Run above owns the verdict.
1053
+ # # migration==success whenever scope succeeded.
1054
+ # # Declared + planned tier: <tier>_ran > 0. No entrypoint: assert nothing. Cache hit is not zero.
1055
+ # # Protect bkit-tests-check, not bkit-tests-scope.
1056
+ #
1057
+ # === JOB 5 — promote the release, then the tenant lanes test it ===
1058
+ # bkit-stub:bkit-tests-deploy — WHEN: the host can create a deployment without promoting it (e.g. Vercel).
1059
+ # needs: [bkit-tests-migration, bkit-tests-build-web]. Push to {{DEFAULT_BRANCH}} only. NOT a required check.
1060
+ # Own `concurrency:` group (`cancel-in-progress: false`), so two releases never overlap; the workflow-level
1061
+ # block queues on {{DEFAULT_BRANCH}} too. Runs BEFORE the E2E / @live lanes: each of those needs: it and
1062
+ # refuses unless production serves this run's build (by deployment id). Promotes the EXACT deployment_id
1063
+ # bkit-tests-build-web published. Does not look the deployment up again by SHA. A 409 is success only when
1064
+ # the body says this id is already current production. A red job means the release did not happen; the
1065
+ # previous deployment stays live. On a default-branch push the capstone needs: it, so a skipped or failed
1066
+ # deploy reds bkit-tests-check.
1067
+ # The host must not auto-build the default branch, and any "hold promotion until a check passes"
1068
+ # setting (e.g. Vercel Deployment Checks) stays empty — this job is the promotion.
1069
+ #
1070
+ # === JOB 6 — health (separate workflow) ===
1071
+ # bkit-stub:health — copy into .github/workflows/health.yml. workflow_run cannot share a file with
1072
+ # push / pull_request. WHEN: you have a live URL to smoke after CI. Trigger on CI completed, default
1073
+ # branch only, if the CI run succeeded. Then hit the health URL of the deployment this SHA promoted.
1074
+ # e.g. poll the host until that deployment is ready, then GET /health. Not a required check.
1075
+ # DROP if you have no deployed health URL.
1076
+ #
1077
+ # COMPOSES WITH bkit-cloud.yml: it routes on workflow_run.conclusion (success->ship, failure->debug);
1078
+ # a red bkit-tests-check turns the whole run red, so the router reads the capstone for free. See .bkit/cloud.md.
1079
+ #
1080
+ # THE RULE (even with no CI): green != ran != validated. Confirm a FULL run of the touched tiers before
1081
+ # trusting green — direct dev pushes auto-escalate to full, but a green capstone on a LIGHT run is not full validation.
1082
+ # =============================================================================