@cbartens/bkit 0.0.0-stage → 5.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (375) hide show
  1. package/.bkit/README.md +417 -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 +417 -0
  8. package/.bkit/core/.bkit/cloud.md +493 -0
  9. package/.bkit/core/.bkit/comparison.md +321 -0
  10. package/.bkit/core/.bkit/install.md +401 -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 +470 -0
  15. package/.bkit/core/.bkit/trackers.md +95 -0
  16. package/.bkit/core/.bkit/workflows.md +1550 -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 +149 -0
  65. package/.bkit/core/engine/checks/after/ci-yml.ts +701 -0
  66. package/.bkit/core/engine/checks/after/github.ts +424 -0
  67. package/.bkit/core/engine/checks/after/index.ts +530 -0
  68. package/.bkit/core/engine/checks/after/managed.ts +217 -0
  69. package/.bkit/core/engine/checks/after/suppression.ts +53 -0
  70. package/.bkit/core/engine/checks/after/tools.ts +427 -0
  71. package/.bkit/core/engine/checks/before/context-fetch.ts +429 -0
  72. package/.bkit/core/engine/checks/before/env.ts +187 -0
  73. package/.bkit/core/engine/checks/before/files.ts +204 -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 +867 -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 +254 -0
  86. package/.bkit/core/engine/commands/install/install.ts +550 -0
  87. package/.bkit/core/engine/commands/install/uninstall.ts +995 -0
  88. package/.bkit/core/engine/commands/install/upgrade.ts +1037 -0
  89. package/.bkit/core/engine/commands/launch.ts +139 -0
  90. package/.bkit/core/engine/commands/lib.ts +495 -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 +924 -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 +173 -0
  118. package/.bkit/core/engine/install/modules/codex.ts +219 -0
  119. package/.bkit/core/engine/install/modules/core.ts +620 -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/payload-links.ts +150 -0
  124. package/.bkit/core/engine/install/placeholders.ts +108 -0
  125. package/.bkit/core/engine/install/template-copies.ts +119 -0
  126. package/.bkit/core/engine/install/version-file.ts +284 -0
  127. package/.bkit/core/engine/install/write.ts +467 -0
  128. package/.bkit/core/engine/ledgers/clamp-log.ts +32 -0
  129. package/.bkit/core/engine/ledgers/status.ts +213 -0
  130. package/.bkit/core/engine/ledgers/telemetry.ts +1143 -0
  131. package/.bkit/core/engine/render/hosts.ts +372 -0
  132. package/.bkit/core/engine/render/models.ts +323 -0
  133. package/.bkit/core/engine/render/parts.ts +38 -0
  134. package/.bkit/core/engine/render/trackers.ts +170 -0
  135. package/.bkit/core/engine/shared/egress.ts +345 -0
  136. package/.bkit/core/engine/shared/json.ts +16 -0
  137. package/.bkit/core/engine/shared/log-prefix.ts +9 -0
  138. package/.bkit/core/engine/shared/package-json.ts +29 -0
  139. package/.bkit/core/engine/shared/package-manager.ts +38 -0
  140. package/.bkit/core/engine/shared/package-roots.ts +163 -0
  141. package/.bkit/core/engine/shared/protected-paths.ts +164 -0
  142. package/.bkit/core/engine/shared/settings.ts +72 -0
  143. package/.bkit/core/engine/shared/timeouts.ts +20 -0
  144. package/.bkit/core/engine/tools/wording.ts +748 -0
  145. package/.bkit/core/hooks/gateguard-edit-payload.js +18 -0
  146. package/.bkit/core/hooks/gateguard-engine.js +193 -0
  147. package/.bkit/core/hooks/guardrails-shell.js +154 -0
  148. package/.bkit/core/hooks/guardrails-tiers.js +68 -0
  149. package/.bkit/core/hooks/preflight-linear.sh +73 -0
  150. package/.bkit/core/prompts/bkit-audit-generate.md +66 -0
  151. package/.bkit/core/prompts/bkit-build-challenge-1.md +79 -0
  152. package/.bkit/core/prompts/bkit-build-challenge-2.md +81 -0
  153. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +68 -0
  154. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +70 -0
  155. package/.bkit/core/prompts/bkit-build-challenge-tests.md +73 -0
  156. package/.bkit/core/prompts/bkit-build-install-skills.md +67 -0
  157. package/.bkit/core/prompts/bkit-build-plan-current.md +75 -0
  158. package/.bkit/core/prompts/bkit-build-plan-execute.md +72 -0
  159. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +73 -0
  160. package/.bkit/core/prompts/bkit-build-plan-verify.md +88 -0
  161. package/.bkit/core/prompts/bkit-build-summary.md +93 -0
  162. package/.bkit/core/prompts/bkit-debug-abort-handover.md +90 -0
  163. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +151 -0
  164. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +78 -0
  165. package/.bkit/core/prompts/bkit-debug-failure-soak.md +73 -0
  166. package/.bkit/core/prompts/bkit-debug-summary.md +95 -0
  167. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +72 -0
  168. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +72 -0
  169. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +75 -0
  170. package/.bkit/core/prompts/bkit-design-generate.md +110 -0
  171. package/.bkit/core/prompts/bkit-design-organise.md +85 -0
  172. package/.bkit/core/prompts/bkit-design-review-1.md +121 -0
  173. package/.bkit/core/prompts/bkit-design-review-2.md +111 -0
  174. package/.bkit/core/prompts/bkit-design-spike.md +97 -0
  175. package/.bkit/core/prompts/bkit-design-summary.md +106 -0
  176. package/.bkit/core/prompts/bkit-design-update.md +66 -0
  177. package/.bkit/core/prompts/bkit-plan-complexity-check.md +66 -0
  178. package/.bkit/core/prompts/bkit-plan-complexity-split.md +87 -0
  179. package/.bkit/core/prompts/bkit-plan-generate.md +74 -0
  180. package/.bkit/core/prompts/bkit-plan-review-1.md +90 -0
  181. package/.bkit/core/prompts/bkit-plan-review-2.md +80 -0
  182. package/.bkit/core/prompts/bkit-plan-review-3.md +92 -0
  183. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +84 -0
  184. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +84 -0
  185. package/.bkit/core/prompts/bkit-plan-summary.md +106 -0
  186. package/.bkit/core/prompts/bkit-plan-update.md +68 -0
  187. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +90 -0
  188. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +94 -0
  189. package/.bkit/core/prompts/bkit-ship-summary.md +77 -0
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +71 -0
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +91 -0
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +75 -0
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +76 -0
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +61 -0
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +76 -0
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +75 -0
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +82 -0
  198. package/.bkit/core/workflows/bkit-auto.md +121 -0
  199. package/.bkit/core/workflows/bkit-build.md +802 -0
  200. package/.bkit/core/workflows/bkit-debug.md +649 -0
  201. package/.bkit/core/workflows/bkit-design.md +495 -0
  202. package/.bkit/core/workflows/bkit-plan.md +510 -0
  203. package/.bkit/core/workflows/bkit-ship.md +650 -0
  204. package/.bkit/shared/.bkit/.env.example +86 -0
  205. package/.bkit/shared/.claude/bkit-cloud.md +117 -0
  206. package/.bkit/shared/.claude/settings.json +88 -0
  207. package/.bkit/shared/.codex/hooks.json +26 -0
  208. package/.bkit/shared/.cursor/bkit-cloud.md +84 -0
  209. package/.bkit/shared/.cursor/hooks.json +26 -0
  210. package/.bkit/shared/.cursor/mcp.json +15 -0
  211. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +12 -0
  212. package/.bkit/shared/.gitattributes +37 -0
  213. package/.bkit/shared/.mcp.json +16 -0
  214. package/.bkit/shared/.opencode/opencode.json +62 -0
  215. package/.bkit/shared/CLAUDE.md +11 -0
  216. package/.bkit/shared/LICENSE.md +22 -0
  217. package/.bkit/shared/docs/architecture.md +19 -0
  218. package/.bkit/shared/docs/data-schema.md +19 -0
  219. package/.bkit/shared/docs/deployments.md +433 -0
  220. package/.bkit/shared/docs/design.md +39 -0
  221. package/.bkit/shared/docs/noise.md +19 -0
  222. package/.bkit/shared/docs/observability.md +25 -0
  223. package/.bkit/shared/docs/security.md +42 -0
  224. package/.bkit/shared/docs/setup.md +30 -0
  225. package/.bkit/shared/docs/technology.md +18 -0
  226. package/.bkit/shared/docs/testing.md +413 -0
  227. package/.bkit/shared/gitignore +97 -0
  228. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +187 -0
  229. package/.bkit/templates/.cursor/Dockerfile +68 -0
  230. package/.bkit/templates/.cursor/environment.json +6 -0
  231. package/.bkit/templates/.cursor/settings.json +11 -0
  232. package/.bkit/templates/.envrc +7 -0
  233. package/.bkit/templates/.github/dependabot.yml +52 -0
  234. package/.bkit/templates/.github/renovate.json5 +224 -0
  235. package/.bkit/templates/.github/workflows/bkit-ci.yml +1062 -0
  236. package/.bkit/templates/.github/workflows/bkit-cloud.yml +564 -0
  237. package/.bkit/templates/.github/workflows/bkit-renovate.yml +102 -0
  238. package/.bkit/templates/.graphifyignore +108 -0
  239. package/.bkit/templates/.husky/pre-commit +16 -0
  240. package/.bkit/templates/.husky/pre-push +91 -0
  241. package/.bkit/templates/.lintstagedrc.json +3 -0
  242. package/.bkit/templates/.prettierignore +41 -0
  243. package/.bkit/templates/.serena/project.yml +243 -0
  244. package/.bkit/templates/.vale/styles/House/Filler.yml +11 -0
  245. package/.bkit/templates/.vale/styles/House/Hedging.yml +12 -0
  246. package/.bkit/templates/.vale/styles/House/LLMSlop.yml +13 -0
  247. package/.bkit/templates/.vale/styles/House/Verbose.yml +12 -0
  248. package/.bkit/templates/.vale.ini +67 -0
  249. package/.bkit/templates/LICENSE.md +22 -0
  250. package/.bkit/templates/context/bkit-cloudrun.md +84 -0
  251. package/.bkit/templates/context/bkit-expo.md +186 -0
  252. package/.bkit/templates/context/bkit-github.md +79 -0
  253. package/.bkit/templates/context/bkit-inngest.md +45 -0
  254. package/.bkit/templates/context/bkit-maestro.md +76 -0
  255. package/.bkit/templates/context/bkit-playwright.md +62 -0
  256. package/.bkit/templates/context/bkit-resend.md +36 -0
  257. package/.bkit/templates/context/bkit-sentry.md +65 -0
  258. package/.bkit/templates/context/bkit-serena.md +33 -0
  259. package/.bkit/templates/context/bkit-stripe.md +36 -0
  260. package/.bkit/templates/context/bkit-supabase.md +59 -0
  261. package/.bkit/templates/context/bkit-tavily.md +49 -0
  262. package/.bkit/templates/context/bkit-vercel.md +64 -0
  263. package/.bkit/templates/docs/capabilities.md +72 -0
  264. package/.bkit/templates/scripts/ci/accepted-divergences.json +21 -0
  265. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +152 -0
  266. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +130 -0
  267. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +98 -0
  268. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +86 -0
  269. package/.bkit/templates/scripts/graphify/bkit-graph-drift-rules.json +23 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +208 -0
  271. package/.bkit/templates/scripts/graphify/bkit-graph-eager-rules.json +35 -0
  272. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +236 -0
  273. package/.bkit/templates/scripts/graphify/bkit-graph-external-rules.json +17 -0
  274. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +290 -0
  275. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +19 -0
  276. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +120 -0
  277. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +232 -0
  278. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +36 -0
  279. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +927 -0
  280. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +351 -0
  281. package/.bkit/templates/scripts/launchd/ai.bkit.launchd.plist +26 -0
  282. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +53 -0
  283. package/.bkit/templates/scripts/launchd/launchd.env.example +13 -0
  284. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +275 -0
  285. package/.bkit/templates/scripts/secrets/bkit-secrets.config.mjs +66 -0
  286. package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +785 -0
  287. package/.bkit/templates/scripts/serena/bkit-serena-mcp.sh +30 -0
  288. package/.bkit/templates/scripts/serena/bkit-serena.mcp.json +9 -0
  289. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +286 -0
  290. package/.bkit/templates/slop-scan.config.json +120 -0
  291. package/CHANGELOG.md +1503 -0
  292. package/LICENSE.md +161 -0
  293. package/README.md +184 -2
  294. package/dist/checks/after/auth.js +140 -0
  295. package/dist/checks/after/ci-yml.js +681 -0
  296. package/dist/checks/after/github.js +400 -0
  297. package/dist/checks/after/index.js +431 -0
  298. package/dist/checks/after/managed.js +187 -0
  299. package/dist/checks/after/suppression.js +39 -0
  300. package/dist/checks/after/tools.js +351 -0
  301. package/dist/checks/before/context-fetch.js +426 -0
  302. package/dist/checks/before/env.js +163 -0
  303. package/dist/checks/before/files.js +187 -0
  304. package/dist/checks/before/index.js +162 -0
  305. package/dist/checks/before/mcp.js +111 -0
  306. package/dist/checks/before/repo.js +71 -0
  307. package/dist/checks/before/version.js +60 -0
  308. package/dist/checks/status-holes.js +393 -0
  309. package/dist/cli.js +688 -0
  310. package/dist/commands/analysis.js +325 -0
  311. package/dist/commands/ci/ci.js +438 -0
  312. package/dist/commands/comply.js +310 -0
  313. package/dist/commands/harvest.js +354 -0
  314. package/dist/commands/install/check.js +61 -0
  315. package/dist/commands/install/doctor.js +209 -0
  316. package/dist/commands/install/install.js +475 -0
  317. package/dist/commands/install/uninstall.js +839 -0
  318. package/dist/commands/install/upgrade.js +782 -0
  319. package/dist/commands/launch.js +118 -0
  320. package/dist/commands/lib.js +363 -0
  321. package/dist/commands/registry.js +50 -0
  322. package/dist/commands/setup/setup.js +158 -0
  323. package/dist/commands/telemetry.js +29 -0
  324. package/dist/commands/workflow/branches.js +1265 -0
  325. package/dist/commands/workflow/context.js +846 -0
  326. package/dist/commands/workflow/counters.js +227 -0
  327. package/dist/commands/workflow/fids.js +224 -0
  328. package/dist/commands/workflow/issues.js +585 -0
  329. package/dist/commands/workflow/ledgers.js +472 -0
  330. package/dist/commands/workflow/locks.js +364 -0
  331. package/dist/commands/workflow/prs.js +904 -0
  332. package/dist/commands/workflow/repo.js +199 -0
  333. package/dist/commands/workflow/roadmap.js +495 -0
  334. package/dist/commands/workflow/runs.js +1717 -0
  335. package/dist/commands/workflow/runtime.js +257 -0
  336. package/dist/commands/workflow/skills.js +110 -0
  337. package/dist/commands/workflow/status.js +392 -0
  338. package/dist/commands/workflow/steps.js +1093 -0
  339. package/dist/commands/workflow/tests.js +144 -0
  340. package/dist/commands/workflow/workflows.js +1342 -0
  341. package/dist/commands/workflow/workstreams.js +141 -0
  342. package/dist/commands/workflow/worktrees.js +473 -0
  343. package/dist/install/cloud-env.js +818 -0
  344. package/dist/install/managed-block.js +182 -0
  345. package/dist/install/manifest.js +376 -0
  346. package/dist/install/modules/claude.js +288 -0
  347. package/dist/install/modules/cloud.js +151 -0
  348. package/dist/install/modules/codex.js +193 -0
  349. package/dist/install/modules/core.js +531 -0
  350. package/dist/install/modules/cursor.js +186 -0
  351. package/dist/install/modules/index.js +152 -0
  352. package/dist/install/modules/opencode.js +504 -0
  353. package/dist/install/payload-links.js +119 -0
  354. package/dist/install/placeholders.js +87 -0
  355. package/dist/install/template-copies.js +106 -0
  356. package/dist/install/version-file.js +204 -0
  357. package/dist/install/write.js +342 -0
  358. package/dist/ledgers/clamp-log.js +27 -0
  359. package/dist/ledgers/status.js +156 -0
  360. package/dist/ledgers/telemetry.js +637 -0
  361. package/dist/render/hosts.js +339 -0
  362. package/dist/render/models.js +288 -0
  363. package/dist/render/parts.js +33 -0
  364. package/dist/render/trackers.js +135 -0
  365. package/dist/shared/egress.js +299 -0
  366. package/dist/shared/json.js +16 -0
  367. package/dist/shared/log-prefix.js +7 -0
  368. package/dist/shared/package-json.js +22 -0
  369. package/dist/shared/package-manager.js +32 -0
  370. package/dist/shared/package-roots.js +145 -0
  371. package/dist/shared/protected-paths.js +153 -0
  372. package/dist/shared/settings.js +44 -0
  373. package/dist/shared/timeouts.js +19 -0
  374. package/dist/tools/wording.js +680 -0
  375. package/package.json +101 -4
@@ -0,0 +1,675 @@
1
+ // bkit issues text|labels|comment — tracker payloads, prepared but never sent.
2
+ //
3
+ // The tracker calls stay in the workflows, through MCP: a workflow touches only
4
+ // its own issue, and only through the tracker's MCP server. These verbs do the
5
+ // arithmetic the workflows stated as prose — which comments count as human input,
6
+ // which labels a transition adds and drops, the board update, and the exact text
7
+ // of every `###### bkit:generated` comment — so no step re-derives it by hand.
8
+
9
+ import * as fs from "node:fs";
10
+ import * as path from "node:path";
11
+
12
+ import {
13
+ CommandError,
14
+ EXIT,
15
+ parseJson,
16
+ repoRoot,
17
+ type CommandSpec,
18
+ type RunContext,
19
+ } from "../lib.js";
20
+ import { readBkitConfig } from "../../shared/settings.js";
21
+ import { str } from "./status.js";
22
+
23
+ /** Exit code: an input file is missing or not in the expected shape. */
24
+ export const EXIT_BAD_INPUT = 3;
25
+
26
+ function readInput(cwd: string, file: string, flag: string): string {
27
+ const abs = path.resolve(cwd, file);
28
+ if (!fs.existsSync(abs))
29
+ throw new CommandError(EXIT_BAD_INPUT, `--${flag} ${file} does not exist`);
30
+ return fs.readFileSync(abs, "utf-8");
31
+ }
32
+
33
+ // ---------------------------------------------------------------------------
34
+ // text
35
+ // ---------------------------------------------------------------------------
36
+
37
+ /** First line of every comment bkit posts; such comments are never workflow input. */
38
+ export const GENERATED_MARKER = "###### bkit:generated";
39
+ /** A human writes this as a whole line to discard everything above it. */
40
+ export const CUT_MARKER = "###### bkit:ignore-earlier";
41
+ // Whole line only: naming the token inline is prose, not a live marker.
42
+ const CUT_LINE = /^[ \t]*###### bkit:ignore-earlier[ \t]*\r?$/;
43
+
44
+ export interface IssueComment {
45
+ body: string;
46
+ createdAt?: string;
47
+ }
48
+
49
+ export const isGenerated = (body: string): boolean =>
50
+ (body.replace(/^\s+/, "").split(/\r?\n/, 1)[0] ?? "").trim() === GENERATED_MARKER;
51
+
52
+ /** Keep only what follows the LAST whole-line cut marker; the marker itself goes too. */
53
+ export function cutEarlier(text: string): { text: string; cut: boolean } {
54
+ const lines = text.split("\n");
55
+ let last = -1;
56
+ lines.forEach((line, i) => {
57
+ if (CUT_LINE.test(line)) last = i;
58
+ });
59
+ if (last === -1) return { text, cut: false };
60
+ return {
61
+ text: lines
62
+ .slice(last + 1)
63
+ .join("\n")
64
+ .replace(/^\s*\n/, ""),
65
+ cut: true,
66
+ };
67
+ }
68
+
69
+ /**
70
+ * Comments as an MCP read returns them: a bare array, or one wrapped under
71
+ * `comments` / `nodes`; each a string or an object with `body` and an optional
72
+ * `created_at` (GitHub) / `createdAt` (Linear).
73
+ */
74
+ export function parseComments(raw: unknown): IssueComment[] | null {
75
+ const wrapped = raw as { comments?: unknown; nodes?: unknown } | null;
76
+ const list = Array.isArray(raw)
77
+ ? raw
78
+ : Array.isArray(wrapped?.comments)
79
+ ? wrapped.comments
80
+ : Array.isArray(wrapped?.nodes)
81
+ ? wrapped.nodes
82
+ : null;
83
+ if (list === null) return null;
84
+ const out: IssueComment[] = [];
85
+ for (const item of list as unknown[]) {
86
+ if (typeof item === "string") {
87
+ out.push({ body: item });
88
+ continue;
89
+ }
90
+ const obj = (item ?? {}) as Record<string, unknown>;
91
+ if (typeof obj.body !== "string") return null;
92
+ const at = obj.created_at ?? obj.createdAt;
93
+ out.push({ body: obj.body, createdAt: typeof at === "string" ? at : undefined });
94
+ }
95
+ return out;
96
+ }
97
+
98
+ /**
99
+ * Oldest first. The cut means "drop everything above the last marker", so a
100
+ * newest-first stream would keep the superseded text and drop the current one.
101
+ * Sorted only when every comment has a timestamp; otherwise the given order stands.
102
+ */
103
+ export function sortOldestFirst(comments: IssueComment[]): {
104
+ comments: IssueComment[];
105
+ sorted: boolean;
106
+ } {
107
+ const times = comments.map((c) => (c.createdAt === undefined ? NaN : Date.parse(c.createdAt)));
108
+ if (times.some((t) => Number.isNaN(t))) return { comments, sorted: false };
109
+ const order = comments.map((c, i) => ({ c, t: times[i]!, i }));
110
+ order.sort((a, b) => a.t - b.t || a.i - b.i);
111
+ return { comments: order.map((o) => o.c), sorted: true };
112
+ }
113
+
114
+ export function issueText(description: string, comments: IssueComment[]) {
115
+ const human = comments.filter((c) => !isGenerated(c.body));
116
+ const joined = [description, ...human.map((c) => c.body)]
117
+ .map((s) => s.trim())
118
+ .filter((s) => s !== "")
119
+ .join("\n\n");
120
+ const { text, cut } = cutEarlier(joined);
121
+ return { text, kept: human.length, dropped: comments.length - human.length, cut };
122
+ }
123
+
124
+ function textVerb(ctx: RunContext): number {
125
+ const descFile = str(ctx.flags.descriptionFile);
126
+ const commentsFile = str(ctx.flags.commentsFile);
127
+ if (descFile === undefined && commentsFile === undefined) {
128
+ throw new CommandError(EXIT.USAGE, "give --description-file, --comments-file, or both");
129
+ }
130
+ const description =
131
+ descFile === undefined ? "" : readInput(ctx.cwd, descFile, "description-file");
132
+ let comments: IssueComment[] = [];
133
+ if (commentsFile !== undefined) {
134
+ const parsed = parseJson(readInput(ctx.cwd, commentsFile, "comments-file"));
135
+ const list = parsed.ok ? parseComments(parsed.value) : null;
136
+ if (list === null) {
137
+ throw new CommandError(
138
+ EXIT_BAD_INPUT,
139
+ `--comments-file ${commentsFile} is not a JSON list of comments with a string body`,
140
+ );
141
+ }
142
+ const sorted = sortOldestFirst(list);
143
+ if (!sorted.sorted && list.length > 1) {
144
+ ctx.log("comments carry no timestamps — keeping the given order (must be oldest first)");
145
+ }
146
+ comments = sorted.comments;
147
+ }
148
+ ctx.emit(issueText(description, comments));
149
+ return EXIT.OK;
150
+ }
151
+
152
+ // ---------------------------------------------------------------------------
153
+ // labels
154
+ // ---------------------------------------------------------------------------
155
+
156
+ /** Mutually exclusive: setting one drops the others. */
157
+ export const PHASE_LABELS = ["bkit:design", "bkit:plan", "bkit:build", "bkit:ship", "bkit:merged"];
158
+
159
+ /** The issue label that opts a feature into CI auto-routing. */
160
+ export const AUTO_LABEL = "bkit:auto";
161
+ /** Commit-subject suffix the CI auto-route gate matches; carried only while the issue has `AUTO_LABEL`. */
162
+ export const AUTO_ROUTE_SUFFIX = " bkit [auto route]";
163
+
164
+ export interface LabelTransition {
165
+ phase?: string;
166
+ failed?: boolean;
167
+ debug?: boolean;
168
+ }
169
+
170
+ export function transitionLabels(current: string[], t: LabelTransition) {
171
+ const have = [...new Set(current)];
172
+ const remove = new Set<string>();
173
+ const add: string[] = [];
174
+ const want = (label: string, on: boolean) => {
175
+ if (on && !have.includes(label)) add.push(label);
176
+ if (!on && have.includes(label)) remove.add(label);
177
+ };
178
+ if (t.phase !== undefined) {
179
+ const label = `bkit:${t.phase}`;
180
+ for (const l of have) if (PHASE_LABELS.includes(l) && l !== label) remove.add(l);
181
+ want(label, true);
182
+ }
183
+ if (t.failed !== undefined) want("bkit:failed", t.failed);
184
+ if (t.debug !== undefined) want("bkit:debug", t.debug);
185
+ return {
186
+ add,
187
+ remove: [...remove],
188
+ labels: [...have.filter((l) => !remove.has(l)), ...add],
189
+ };
190
+ }
191
+
192
+ /**
193
+ * Linear's issue state for the same transition, as the workflows set it: a
194
+ * shipped, failed or debugged issue waits on a human ("In Review"); a phase
195
+ * starting is "In Progress". Null when the transition sets no state.
196
+ */
197
+ export function linearState(t: LabelTransition, board: string | undefined): string | null {
198
+ if (t.phase === "merged" || t.failed === true || t.debug === true) return "In Review";
199
+ if (t.phase !== undefined) return "In Progress";
200
+ if (board === "review") return "In Review";
201
+ if (board === "progress") return "In Progress";
202
+ return null;
203
+ }
204
+
205
+ const ON_OFF: Record<string, boolean> = { on: true, off: false };
206
+
207
+ function onOff(v: unknown, flag: string): boolean | undefined {
208
+ if (v === undefined) return undefined;
209
+ const b = ON_OFF[String(v)];
210
+ if (b === undefined) throw new CommandError(EXIT.USAGE, `--${flag} must be on or off`);
211
+ return b;
212
+ }
213
+
214
+ const BOARD_OPTION: Record<string, string> = {
215
+ progress: "progressOptionId",
216
+ review: "reviewOptionId",
217
+ };
218
+
219
+ /**
220
+ * The three `projects_write` / `projects_list` payloads that move an issue on the
221
+ * Projects v2 board, from `bkit.githubProject`. Payload keys are the MCP tools'
222
+ * own argument names. The workflow fills `item_id` on `updateItem` from the
223
+ * `listItems` entry whose issue number matches.
224
+ */
225
+ function boardPayload(
226
+ ctx: RunContext,
227
+ status: string,
228
+ ): { board: Record<string, unknown> | null; boardSkipped: string | null } {
229
+ const root = repoRoot(ctx.cwd);
230
+ const tracker = readBkitConfig(root).issueTracker;
231
+ if (tracker !== "github") {
232
+ if (tracker === "linear") ctx.log("Board status carried by issue state — no separate update.");
233
+ return { board: null, boardSkipped: `tracker-${tracker}` };
234
+ }
235
+ const gp = readBkitConfig(root).githubProject;
236
+ if (gp === false) return { board: null, boardSkipped: "opted-out" };
237
+ const cfg = gp ?? {};
238
+ const owner = cfg.owner;
239
+ const number = Number(cfg.number);
240
+ if (typeof owner !== "string" || owner === "" || !Number.isInteger(number) || number <= 0) {
241
+ ctx.log("GitHub project not configured in package.json");
242
+ return { board: null, boardSkipped: "not-configured" };
243
+ }
244
+ // projects_write rejects anything but the numeric field id (a `PVTSSF_…` node id
245
+ // included), so a wrong value is a skip with a reason, not a silent no-op.
246
+ const raw = cfg.statusFieldId;
247
+ const fieldId = typeof raw === "number" ? raw : /^[0-9]+$/.test(String(raw)) ? Number(raw) : NaN;
248
+ if (!Number.isInteger(fieldId)) {
249
+ ctx.log(`bkit.githubProject.statusFieldId "${String(raw)}" is not the numeric Status field id`);
250
+ return { board: null, boardSkipped: "status-field-id-not-number" };
251
+ }
252
+ const option = cfg[BOARD_OPTION[status]!];
253
+ if (typeof option !== "string" || option === "") {
254
+ ctx.log(`bkit.githubProject.${BOARD_OPTION[status]!} is not set`);
255
+ return { board: null, boardSkipped: "option-id-missing" };
256
+ }
257
+ const issue = String(ctx.flags.issue ?? "").replace(/^#/, "");
258
+ const ownerRepo = String(ctx.flags.ownerRepo ?? "");
259
+ const [itemOwner, itemRepo, extra] = ownerRepo.split("/");
260
+ if (!/^[0-9]+$/.test(issue) || !itemOwner || !itemRepo || extra !== undefined) {
261
+ throw new CommandError(
262
+ EXIT.USAGE,
263
+ "--board needs --issue=<number> and --owner-repo=<owner>/<repo>",
264
+ );
265
+ }
266
+ const project = { owner, owner_type: "org", project_number: number };
267
+ return {
268
+ board: {
269
+ addItem: {
270
+ method: "add_project_item",
271
+ ...project,
272
+ item_type: "issue",
273
+ item_owner: itemOwner,
274
+ item_repo: itemRepo,
275
+ issue_number: Number(issue),
276
+ },
277
+ listItems: { method: "list_project_items", ...project, query: issue },
278
+ updateItem: {
279
+ method: "update_project_item",
280
+ ...project,
281
+ updated_field: { id: fieldId, value: option },
282
+ },
283
+ },
284
+ boardSkipped: null,
285
+ };
286
+ }
287
+
288
+ function labelsVerb(ctx: RunContext): number {
289
+ const phase = str(ctx.flags.phase);
290
+ if (phase !== undefined && !PHASE_LABELS.includes(`bkit:${phase}`)) {
291
+ throw new CommandError(EXIT.USAGE, "--phase must be design, plan, build, ship, or merged");
292
+ }
293
+ let failed = onOff(ctx.flags.failed, "failed");
294
+ const debug = onOff(ctx.flags.debug, "debug");
295
+ // A merged issue must not keep a stale Failure Path marker.
296
+ if (phase === "merged") {
297
+ if (failed === true)
298
+ throw new CommandError(EXIT.USAGE, "--phase=merged clears bkit:failed; drop --failed=on");
299
+ failed = false;
300
+ }
301
+ const board = str(ctx.flags.board);
302
+ if (board !== undefined && BOARD_OPTION[board] === undefined) {
303
+ throw new CommandError(EXIT.USAGE, "--board must be progress or review");
304
+ }
305
+ const t: LabelTransition = { phase, failed, debug };
306
+ const { add, remove, labels } = transitionLabels(
307
+ (ctx.flags.label as string[] | undefined) ?? [],
308
+ t,
309
+ );
310
+ const { board: payload, boardSkipped } =
311
+ board === undefined ? { board: null, boardSkipped: null } : boardPayload(ctx, board);
312
+ ctx.emit({
313
+ add,
314
+ remove,
315
+ labels,
316
+ changed: add.length + remove.length > 0,
317
+ autoRouteSuffix: labels.includes(AUTO_LABEL) ? AUTO_ROUTE_SUFFIX : "",
318
+ linearState: linearState(t, board),
319
+ board: payload,
320
+ boardSkipped,
321
+ });
322
+ return EXIT.OK;
323
+ }
324
+
325
+ // ---------------------------------------------------------------------------
326
+ // comment
327
+ // ---------------------------------------------------------------------------
328
+
329
+ const WORKFLOW_HEADINGS: Record<string, string> = {
330
+ design: "Design Workflow",
331
+ plan: "Plan Workflow",
332
+ build: "Build Workflow",
333
+ debug: "Debug Workflow",
334
+ ship: "Ship Workflow",
335
+ auto: "bkit Auto",
336
+ };
337
+
338
+ /** Named header fields and their label; any other goes through `--field=Name=value`. */
339
+ const FIELD_LABELS: Record<string, string> = {
340
+ verdict: "Verdict",
341
+ failures: "Failures",
342
+ scope: "Scope",
343
+ subPlan: "Sub-plan",
344
+ attempt: "Attempt",
345
+ strategy: "Strategy",
346
+ };
347
+
348
+ /**
349
+ * ` - Name: value` fields in the order the flags were given — the templates order
350
+ * them differently step to step (Strategy before or after Attempt), and each
351
+ * template's order is kept. Relies on parseFlags filling its result in argv order.
352
+ */
353
+ function headerFields(ctx: RunContext): Array<[string, string]> {
354
+ const out: Array<[string, string]> = [];
355
+ for (const key of Object.keys(ctx.flags)) {
356
+ if (key === "field") {
357
+ for (const f of ctx.flags.field as string[]) {
358
+ const eq = f.indexOf("=");
359
+ if (eq <= 0) throw new CommandError(EXIT.USAGE, `--field "${f}" must be Name=value`);
360
+ out.push([f.slice(0, eq), f.slice(eq + 1)]);
361
+ }
362
+ } else if (key === "subPlan") {
363
+ const count = str(ctx.flags.subPlanCount);
364
+ out.push([
365
+ "Sub-plan",
366
+ `${String(ctx.flags.subPlan)}${count === undefined ? "" : `/${count}`}`,
367
+ ]);
368
+ } else if (FIELD_LABELS[key] !== undefined) {
369
+ out.push([FIELD_LABELS[key], String(ctx.flags[key])]);
370
+ }
371
+ }
372
+ return out;
373
+ }
374
+
375
+ const tail = (text: string, n: number) => text.replace(/\n+$/, "").split("\n").slice(-n).join("\n");
376
+
377
+ /** A fence longer than any backtick run inside, so captured output cannot close it. */
378
+ function fenced(text: string): string {
379
+ const longest = Math.max(0, ...(text.match(/`+/g) ?? []).map((m) => m.length));
380
+ const fence = "`".repeat(Math.max(3, longest + 1));
381
+ return `${fence}text\n${text}\n${fence}`;
382
+ }
383
+
384
+ /** Everything one `###### bkit:generated` comment is built from. */
385
+ export interface CommentInput {
386
+ kind?: "step" | "failure" | "handover";
387
+ /** With `workflowHeading`: Step 1 puts `## <Workflow>` above the step. */
388
+ workflow?: string;
389
+ workflowHeading?: boolean;
390
+ stepNumber?: string;
391
+ stepTitle?: string;
392
+ /** ` - Name: value` header fields, in order. */
393
+ fields?: Array<[string, string]>;
394
+ subStep?: string;
395
+ /** Failure: the error text, or a file holding it. */
396
+ error?: string;
397
+ errorFile?: string;
398
+ stderrFile?: string;
399
+ ownerRepo?: string;
400
+ tree?: string;
401
+ prNumber?: string;
402
+ prUrl?: string;
403
+ runId?: string;
404
+ /** Repo paths linked at `ref` (default `tree`). */
405
+ artifacts?: string[];
406
+ ref?: string;
407
+ lines?: string[];
408
+ bodyFile?: string;
409
+ /** `Title=path`: a `#### Title` heading and the file's content. */
410
+ sections?: string[];
411
+ }
412
+
413
+ function links(o: CommentInput): string[] {
414
+ const artifacts = o.artifacts ?? [];
415
+ const wantsLinks = o.tree ?? o.prNumber ?? o.runId ?? artifacts[0];
416
+ if (wantsLinks === undefined) return [];
417
+ const ownerRepo = o.ownerRepo;
418
+ if (ownerRepo === undefined || !/^[^/\s]+\/[^/\s]+$/.test(ownerRepo)) {
419
+ throw new CommandError(EXIT.USAGE, "links need --owner-repo=<owner>/<repo>");
420
+ }
421
+ const gh = `https://github.com/${ownerRepo}`;
422
+ const out: string[] = [];
423
+ if (o.tree !== undefined) out.push(`[${ownerRepo}/tree/${o.tree}](${gh}/tree/${o.tree})`);
424
+ if (o.prNumber !== undefined) {
425
+ out.push(`[${ownerRepo}/pull/${o.prNumber}](${o.prUrl ?? `${gh}/pull/${o.prNumber}`})`);
426
+ }
427
+ if (o.runId !== undefined)
428
+ out.push(`[${ownerRepo}/actions/run/${o.runId}](${gh}/actions/runs/${o.runId})`);
429
+ if (artifacts.length) {
430
+ const ref = o.ref ?? o.tree;
431
+ if (ref === undefined) throw new CommandError(EXIT.USAGE, "--artifact needs --ref (or --tree)");
432
+ for (const a of artifacts)
433
+ out.push(`[${path.basename(a)}](${gh}/blob/${ref}/${a.replace(/^\/+/, "")})`);
434
+ }
435
+ return out;
436
+ }
437
+
438
+ const KINDS = ["step", "failure", "handover"];
439
+
440
+ /** The exact comment body; files (`bodyFile`, `sections`, `stderrFile`, `errorFile`) resolve against `cwd`. */
441
+ export function buildComment(cwd: string, o: CommentInput): string {
442
+ const kind = o.kind ?? "step";
443
+ if (!KINDS.includes(kind))
444
+ throw new CommandError(EXIT.USAGE, `--kind must be ${KINDS.join(", ")}`);
445
+ const lines = [GENERATED_MARKER];
446
+
447
+ if (o.workflowHeading === true) {
448
+ const heading = WORKFLOW_HEADINGS[o.workflow ?? ""];
449
+ if (heading === undefined) {
450
+ throw new CommandError(
451
+ EXIT.USAGE,
452
+ `--workflow-heading needs --workflow=${Object.keys(WORKFLOW_HEADINGS).join("|")}`,
453
+ );
454
+ }
455
+ lines.push(`## ${heading}`);
456
+ }
457
+
458
+ const number = o.stepNumber;
459
+ const title = o.stepTitle;
460
+ if (number !== undefined && !/^[0-9]+[a-z]?$/.test(number)) {
461
+ throw new CommandError(EXIT.USAGE, `--step-number "${number}" is not a step number`);
462
+ }
463
+
464
+ if (kind === "step") {
465
+ if (number === undefined || title === undefined) {
466
+ throw new CommandError(EXIT.USAGE, "--kind=step needs --step-number and --step-title");
467
+ }
468
+ lines.push(
469
+ [`### Step ${number} — ${title}`, ...(o.fields ?? []).map(([k, v]) => `${k}: ${v}`)].join(
470
+ " - ",
471
+ ),
472
+ );
473
+ } else if (kind === "failure") {
474
+ const error =
475
+ o.errorFile !== undefined
476
+ ? readInput(cwd, o.errorFile, "error-file").replace(/\n+$/, "")
477
+ : o.error;
478
+ if (number === undefined || title === undefined || error === undefined) {
479
+ throw new CommandError(
480
+ EXIT.USAGE,
481
+ "--kind=failure needs --step-number, --step-title and --error (or --error-file)",
482
+ );
483
+ }
484
+ lines.push("### Workflow Failure");
485
+ lines.push(
486
+ `Step: ${number} — ${title}${o.subStep === undefined ? "" : `; Sub-step: ${o.subStep}`}`,
487
+ );
488
+ lines.push(`Error: ${error}`);
489
+ if (o.stderrFile !== undefined) {
490
+ const captured = tail(readInput(cwd, o.stderrFile, "stderr-file"), 20);
491
+ if (captured.trim() !== "") lines.push("Stderr:", fenced(captured));
492
+ }
493
+ } else {
494
+ lines.push("### Workflow Handover");
495
+ }
496
+
497
+ lines.push(...links(o));
498
+ lines.push(...(o.lines ?? []));
499
+ if (o.bodyFile !== undefined)
500
+ lines.push(readInput(cwd, o.bodyFile, "body-file").replace(/\n+$/, ""));
501
+ for (const s of o.sections ?? []) {
502
+ const eq = s.indexOf("=");
503
+ if (eq <= 0) throw new CommandError(EXIT.USAGE, `--section "${s}" must be Title=path`);
504
+ lines.push(`#### ${s.slice(0, eq)}`);
505
+ lines.push(readInput(cwd, s.slice(eq + 1), "section").replace(/\n+$/, ""));
506
+ }
507
+
508
+ // A whole-line cut marker copied in from an artifact would fire on the next
509
+ // run's issue text; inline, it is only a mention.
510
+ return lines
511
+ .join("\n")
512
+ .split("\n")
513
+ .map((l) => (CUT_LINE.test(l) ? `\`${CUT_MARKER}\`` : l))
514
+ .join("\n");
515
+ }
516
+
517
+ /** `bkit issues comment`'s flags as a `CommentInput`. */
518
+ export function commentBody(ctx: RunContext): string {
519
+ const kind = str(ctx.flags.kind) ?? "step";
520
+ if (ctx.flags.subPlanCount !== undefined && ctx.flags.subPlan === undefined) {
521
+ throw new CommandError(EXIT.USAGE, "--sub-plan-count needs --sub-plan");
522
+ }
523
+ return buildComment(ctx.cwd, {
524
+ kind: kind as CommentInput["kind"],
525
+ workflow: str(ctx.flags.workflow),
526
+ workflowHeading: ctx.flags.workflowHeading === true,
527
+ stepNumber: str(ctx.flags.stepNumber),
528
+ stepTitle: str(ctx.flags.stepTitle),
529
+ fields: kind === "step" ? headerFields(ctx) : [],
530
+ subStep: str(ctx.flags.subStep),
531
+ error: str(ctx.flags.error),
532
+ errorFile: str(ctx.flags.errorFile),
533
+ stderrFile: str(ctx.flags.stderrFile),
534
+ ownerRepo: str(ctx.flags.ownerRepo),
535
+ tree: str(ctx.flags.tree),
536
+ prNumber: str(ctx.flags.prNumber),
537
+ prUrl: str(ctx.flags.prUrl),
538
+ runId: str(ctx.flags.runId),
539
+ artifacts: (ctx.flags.artifact as string[] | undefined) ?? [],
540
+ ref: str(ctx.flags.ref),
541
+ lines: (ctx.flags.line as string[] | undefined) ?? [],
542
+ bodyFile: str(ctx.flags.bodyFile),
543
+ sections: (ctx.flags.section as string[] | undefined) ?? [],
544
+ });
545
+ }
546
+
547
+ // ---------------------------------------------------------------------------
548
+ // Command
549
+ // ---------------------------------------------------------------------------
550
+
551
+ export const issuesCommand: CommandSpec = {
552
+ noun: "issues",
553
+ summary: "Prepare tracker payloads (issue text, label transitions, comments); MCP sends them.",
554
+ verbs: {
555
+ text: {
556
+ summary: "ISSUE_TEXT: description + human comments, after the bkit:ignore-earlier cut.",
557
+ flags: [
558
+ { name: "description-file", type: "string", help: "file holding the issue description" },
559
+ {
560
+ name: "comments-file",
561
+ type: "string",
562
+ help: "JSON comments as the MCP read returned them (array, or {comments: [...]})",
563
+ },
564
+ ],
565
+ output: {
566
+ text: "the joined, filtered, cut issue text",
567
+ kept: "comments kept",
568
+ dropped: "bkit:generated comments dropped",
569
+ cut: "whether a whole-line bkit:ignore-earlier marker cut the text",
570
+ },
571
+ exitCodes: { [EXIT_BAD_INPUT]: "an input file is missing or not a list of comments" },
572
+ run: textVerb,
573
+ },
574
+ labels: {
575
+ summary: "Label arithmetic for a transition, the Linear state, and the board payload.",
576
+ flags: [
577
+ { name: "label", type: "string", repeatable: true, help: "a label the issue carries now" },
578
+ {
579
+ name: "phase",
580
+ type: "string",
581
+ help: "set this phase: design | plan | build | ship | merged",
582
+ },
583
+ { name: "failed", type: "string", help: "bkit:failed on | off (merged implies off)" },
584
+ { name: "debug", type: "string", help: "bkit:debug on | off" },
585
+ {
586
+ name: "board",
587
+ type: "string",
588
+ help: "also move the Projects v2 item: progress | review",
589
+ },
590
+ { name: "issue", type: "string", help: "issue number (with --board)" },
591
+ { name: "owner-repo", type: "string", help: "<owner>/<repo> of the issue (with --board)" },
592
+ ],
593
+ output: {
594
+ add: "labels to add",
595
+ remove: "labels to remove",
596
+ labels: "the full label set to write",
597
+ changed: "whether add or remove is non-empty",
598
+ autoRouteSuffix: `"${AUTO_ROUTE_SUFFIX}" when the label set carries ${AUTO_LABEL}, else ""`,
599
+ linearState: "Linear issue state for this transition, or null",
600
+ board: "projects payloads {addItem, listItems, updateItem}, or null",
601
+ boardSkipped:
602
+ "why board is null with --board: opted-out | not-configured | tracker-<name> | …",
603
+ },
604
+ run: labelsVerb,
605
+ },
606
+ comment: {
607
+ summary: "The exact body of a ###### bkit:generated step, failure, or handover comment.",
608
+ flags: [
609
+ { name: "kind", type: "string", help: "step (default) | failure | handover" },
610
+ { name: "step-number", type: "string", help: "step number in the heading" },
611
+ { name: "step-title", type: "string", help: "step title in the heading, e.g. Plan Verify" },
612
+ { name: "workflow", type: "string", help: "design | plan | build | debug | ship | auto" },
613
+ {
614
+ name: "workflow-heading",
615
+ type: "boolean",
616
+ help: "Step 1: put `## <Workflow>` above the step",
617
+ },
618
+ { name: "verdict", type: "string", help: "header field Verdict" },
619
+ { name: "failures", type: "string", help: "header field Failures" },
620
+ { name: "scope", type: "string", help: "header field Scope" },
621
+ { name: "sub-plan", type: "string", help: "header field Sub-plan (x of x/y)" },
622
+ { name: "sub-plan-count", type: "string", help: "y of Sub-plan x/y" },
623
+ { name: "attempt", type: "string", help: "header field Attempt" },
624
+ { name: "strategy", type: "string", help: "header field Strategy" },
625
+ {
626
+ name: "field",
627
+ type: "string",
628
+ repeatable: true,
629
+ help: "any other header field as Name=value; fields render in flag order",
630
+ },
631
+ { name: "owner-repo", type: "string", help: "<owner>/<repo>, for links" },
632
+ { name: "tree", type: "string", help: "link the tree of this ref" },
633
+ { name: "pr-number", type: "string", help: "link this PR" },
634
+ { name: "pr-url", type: "string", help: "PR URL (default: built from --owner-repo)" },
635
+ { name: "run-id", type: "string", help: "link this Actions run" },
636
+ {
637
+ name: "artifact",
638
+ type: "string",
639
+ repeatable: true,
640
+ help: "link this repo path at --ref",
641
+ },
642
+ { name: "ref", type: "string", help: "ref the --artifact links point at (default --tree)" },
643
+ { name: "line", type: "string", repeatable: true, help: "a raw line after the links" },
644
+ { name: "body-file", type: "string", help: "file appended verbatim (summary, handover)" },
645
+ {
646
+ name: "section",
647
+ type: "string",
648
+ repeatable: true,
649
+ help: "Title=path: a `#### Title` heading and the file's content",
650
+ },
651
+ { name: "sub-step", type: "string", help: "failure: the sub-step that failed" },
652
+ { name: "error", type: "string", help: "failure: the error message or tool response" },
653
+ {
654
+ name: "error-file",
655
+ type: "string",
656
+ help: "failure: file holding the error message (instead of --error)",
657
+ },
658
+ {
659
+ name: "stderr-file",
660
+ type: "string",
661
+ help: "failure: captured stderr (last 20 lines kept)",
662
+ },
663
+ ],
664
+ output: { comment: "the comment body" },
665
+ exitCodes: {
666
+ [EXIT_BAD_INPUT]:
667
+ "a --body-file / --section / --stderr-file / --error-file file is missing",
668
+ },
669
+ run: (ctx) => {
670
+ ctx.emit({ comment: commentBody(ctx) });
671
+ return EXIT.OK;
672
+ },
673
+ },
674
+ },
675
+ };