@cbartens/bkit 5.5.1 → 6.1.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 (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -2,18 +2,18 @@
2
2
  // Example. Copy into scripts/ci/ and own it. bkit install does not write this file
3
3
  // and does not overwrite a copy.
4
4
  /**
5
- * check-capstone.test.mjs — unit tests for the capstone gate.
5
+ * bkit-check-capstone.test.mjs — unit tests for the capstone gate.
6
6
  *
7
- * Pure Node, no runner: `node scripts/ci/check-capstone.test.mjs`.
7
+ * Pure Node, no runner: `node scripts/ci/bkit-check-capstone.test.mjs`.
8
8
  * Exit: 0 = all tests passed, 1 = at least one test failed.
9
9
  */
10
10
 
11
11
  import { spawnSync } from "node:child_process";
12
12
  import path from "node:path";
13
13
  import { fileURLToPath } from "node:url";
14
- import { checkCapstone } from "./check-capstone.mjs";
14
+ import { checkCapstone } from "./bkit-check-capstone.mjs";
15
15
 
16
- const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), "check-capstone.mjs");
16
+ const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), "bkit-check-capstone.mjs");
17
17
 
18
18
  let passed = 0;
19
19
  let failed = 0;
@@ -2,7 +2,7 @@
2
2
  // Example. Copy into scripts/ci/ and own it. bkit install does not write this file
3
3
  // and does not overwrite a copy.
4
4
  /**
5
- * check-dependency-audit.mjs — the dependency-audit gate.
5
+ * bkit-check-dependency-audit.mjs — the dependency-audit gate.
6
6
  *
7
7
  * Runs `pnpm audit --json` and reds when a blocking advisory (by default high or critical)
8
8
  * reaches the lockfile without an acceptance in the registry. An acceptance is a row naming
@@ -19,8 +19,13 @@
19
19
  * Reads pnpm's report shape (`advisories`: id → { github_advisory_id, severity, module_name,
20
20
  * patched_versions, findings }). Another package manager → adapt `blockingFindings()`.
21
21
  *
22
- * Usage: node scripts/ci/check-dependency-audit.mjs [--registry=<file>] [--report=<file>]
22
+ * Usage: node scripts/ci/bkit-check-dependency-audit.mjs [--registry=<file>] [--report=<file>]
23
+ * [--unreachable=fail|warn]
23
24
  * --report reads a saved `pnpm audit --json` instead of running the audit.
25
+ * --unreachable (default fail) is what the LIVE audit does when the registry cannot
26
+ * be reached at all: `fail` stops the run (CI's choice), `warn` prints one warning
27
+ * and passes (a local hook that leaves the check to CI). A registry that answered
28
+ * badly (401, 500, a missing endpoint) is never "unreachable": its answer stands.
24
29
  * Exit: 0 = every blocking advisory accepted and every row live, 1 = drift or no report.
25
30
  */
26
31
 
@@ -33,8 +38,32 @@ import { parseArgs } from "node:util";
33
38
  /** Severity → the most days an acceptance may run. Severities not listed never block. */
34
39
  export const DEFAULT_BLOCKING = { critical: 7, high: 30 };
35
40
 
41
+ /**
42
+ * Error codes that mean the registry could not be reached at all — no DNS answer, a
43
+ * refused or reset connection, no route. A reachable registry that answers *badly*
44
+ * (`ERR_PNPM_AUDIT_BAD_RESPONSE` on a 401/500, `ERR_PNPM_AUDIT_ENDPOINT_NOT_EXISTS`) is
45
+ * not one of these: it answered, so its answer stands.
46
+ */
47
+ export const UNREACHABLE_CODES = new Set([
48
+ "ENOTFOUND",
49
+ "EAI_AGAIN",
50
+ "ETIMEDOUT",
51
+ "ECONNREFUSED",
52
+ "ECONNRESET",
53
+ "ECONNABORTED",
54
+ "EHOSTUNREACH",
55
+ "ENETUNREACH",
56
+ "EPIPE",
57
+ ]);
58
+
36
59
  const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
37
60
  const DAY_MS = 24 * 60 * 60 * 1000;
61
+ /**
62
+ * Pure backstop so a hung process cannot stall a push forever. A refused or unresolved
63
+ * registry returns in well under a second (`fetch-retries=0` below); this only catches a
64
+ * black hole, and stays generous so a slow legitimate registry is never cut off.
65
+ */
66
+ const AUDIT_TIMEOUT_MS = 180_000;
38
67
 
39
68
  /** `YYYY-MM-DD` of a Date, in UTC. */
40
69
  export function isoDay(date) {
@@ -111,43 +140,99 @@ export function checkAcceptances(findings, registry, today) {
111
140
  }
112
141
 
113
142
  /**
114
- * Run `pnpm audit --json`, retrying when it prints no report (a registry blip).
115
- * pnpm exits 1 whenever it finds an advisory, so the exit code is not the signal; the report is.
116
- * @returns {object | null} the parsed report, or null after three attempts.
143
+ * Classify what a `pnpm audit --json` run printed. `--json` writes either the report or an
144
+ * `{ "error": { "code": … } }` object to stdout.
145
+ * @returns {{status:"ok", report:object}
146
+ * | {status:"unreachable", code:string}
147
+ * | {status:"failed", detail:string}}
148
+ */
149
+ export function classifyAuditOutput(stdout) {
150
+ let parsed;
151
+ try {
152
+ parsed = JSON.parse(stdout);
153
+ } catch {
154
+ return { status: "failed", detail: "not JSON" };
155
+ }
156
+ if (parsed && typeof parsed.advisories === "object") return { status: "ok", report: parsed };
157
+ const code = parsed?.error?.code;
158
+ if (typeof code === "string" && UNREACHABLE_CODES.has(code)) {
159
+ return { status: "unreachable", code };
160
+ }
161
+ return { status: "failed", detail: typeof code === "string" ? `error ${code}` : "no advisories" };
162
+ }
163
+
164
+ /**
165
+ * Run `pnpm audit --json`. pnpm exits 1 whenever it finds an advisory, so the exit code is
166
+ * not the signal; the report is. `fetch-retries=0` makes an unreachable registry fail in
167
+ * under a second instead of hanging through pnpm's retry backoff. A *reachable* failure (a
168
+ * registry blip) is retried; an unreachable registry returns at once.
169
+ * @returns {ReturnType<typeof classifyAuditOutput>}
117
170
  */
118
171
  function runAudit() {
119
172
  for (let attempt = 1; attempt <= 3; attempt++) {
120
173
  const res = spawnSync("pnpm", ["audit", "--json"], {
121
174
  encoding: "utf-8",
122
175
  maxBuffer: 64 * 1024 * 1024,
176
+ timeout: AUDIT_TIMEOUT_MS,
177
+ killSignal: "SIGKILL",
178
+ env: { ...process.env, npm_config_fetch_retries: "0" },
123
179
  });
124
- let parseError = "";
125
- try {
126
- const report = JSON.parse(res.stdout);
127
- if (report && typeof report.advisories === "object") return report;
128
- } catch (err) {
129
- parseError = `not JSON (${err.message}): `;
130
- }
180
+ if (res.error?.code === "ETIMEDOUT") return { status: "unreachable", code: "ETIMEDOUT" };
181
+ const outcome = classifyAuditOutput(res.stdout ?? "");
182
+ if (outcome.status !== "failed") return outcome;
131
183
  const tail = (res.stderr || res.stdout || "").trim().split("\n").slice(-3).join(" | ");
132
- const detail = parseError + tail;
133
- console.error(`::warning::dependency-audit: attempt ${attempt} printed no report — ${detail}`);
184
+ console.error(
185
+ `::warning::dependency-audit: attempt ${attempt} printed no report — ${outcome.detail}; ${tail}`,
186
+ );
134
187
  }
135
- return null;
188
+ return { status: "failed", detail: "no report after 3 attempts" };
136
189
  }
137
190
 
138
191
  function main(argv) {
139
192
  const { values } = parseArgs({
140
193
  args: argv,
141
- options: { registry: { type: "string" }, report: { type: "string" } },
194
+ options: {
195
+ registry: { type: "string" },
196
+ report: { type: "string" },
197
+ unreachable: { type: "string" },
198
+ },
142
199
  strict: false,
143
200
  });
144
- const registryPath = values.registry ?? path.join("scripts", "ci", "accepted-advisories.json");
201
+ const registryPath =
202
+ values.registry ?? path.join("scripts", "ci", "bkit-accepted-advisories.json");
145
203
  const reportPath = values.report ?? null;
204
+ const unreachable = values.unreachable ?? "fail";
205
+ if (unreachable !== "fail" && unreachable !== "warn") {
206
+ console.error(
207
+ `::error::dependency-audit: --unreachable takes fail or warn, not ${unreachable}`,
208
+ );
209
+ process.exit(1);
210
+ }
146
211
 
147
212
  const registry = fs.existsSync(registryPath)
148
213
  ? JSON.parse(fs.readFileSync(registryPath, "utf-8"))
149
214
  : { accepted: [] };
150
- const report = reportPath ? JSON.parse(fs.readFileSync(reportPath, "utf-8")) : runAudit();
215
+
216
+ let report;
217
+ if (reportPath) {
218
+ // A saved report is the offline replay; only the live audit is ever "unreachable".
219
+ report = JSON.parse(fs.readFileSync(reportPath, "utf-8"));
220
+ } else {
221
+ const outcome = runAudit();
222
+ if (outcome.status === "unreachable") {
223
+ if (unreachable === "warn") {
224
+ console.error(
225
+ `::warning::dependency-audit: registry unreachable (${outcome.code}) — NOT checked; CI re-checks this push`,
226
+ );
227
+ process.exit(0);
228
+ }
229
+ console.error(
230
+ `::error::dependency-audit: registry unreachable (${outcome.code}) — failing closed`,
231
+ );
232
+ process.exit(1);
233
+ }
234
+ report = outcome.report;
235
+ }
151
236
  if (!report || typeof report.advisories !== "object") {
152
237
  console.error("::error::dependency-audit: the audit printed no report — failing closed");
153
238
  process.exit(1);
@@ -2,13 +2,17 @@
2
2
  // Example. Copy into scripts/ci/ and own it. bkit install does not write this file
3
3
  // and does not overwrite a copy.
4
4
  /**
5
- * check-dependency-audit.test.mjs — unit tests for the dependency-audit gate.
5
+ * bkit-check-dependency-audit.test.mjs — unit tests for the dependency-audit gate.
6
6
  *
7
- * Pure Node, no runner: `node scripts/ci/check-dependency-audit.test.mjs`.
7
+ * Pure Node, no runner: `node scripts/ci/bkit-check-dependency-audit.test.mjs`.
8
8
  * Exit: 0 = all tests passed, 1 = at least one test failed.
9
9
  */
10
10
 
11
- import { blockingFindings, checkAcceptances } from "./check-dependency-audit.mjs";
11
+ import {
12
+ blockingFindings,
13
+ checkAcceptances,
14
+ classifyAuditOutput,
15
+ } from "./bkit-check-dependency-audit.mjs";
12
16
 
13
17
  let passed = 0;
14
18
  let failed = 0;
@@ -123,5 +127,29 @@ test("a report with no advisories has nothing to block", () => {
123
127
  assert(blockingFindings({ advisories: {} }).length === 0, "found something");
124
128
  });
125
129
 
130
+ test("classifies a report as ok", () => {
131
+ const r = classifyAuditOutput(JSON.stringify({ advisories: {} }));
132
+ assert(r.status === "ok", `got ${r.status}`);
133
+ });
134
+
135
+ test("classifies an unreachable registry by its network code", () => {
136
+ const r = classifyAuditOutput(
137
+ JSON.stringify({ error: { code: "ENOTFOUND", message: "getaddrinfo ENOTFOUND" } }),
138
+ );
139
+ assert(r.status === "unreachable" && r.code === "ENOTFOUND", JSON.stringify(r));
140
+ });
141
+
142
+ test("a registry that answered badly is a failure, not unreachable", () => {
143
+ for (const code of ["ERR_PNPM_AUDIT_BAD_RESPONSE", "ERR_PNPM_AUDIT_ENDPOINT_NOT_EXISTS"]) {
144
+ const r = classifyAuditOutput(JSON.stringify({ error: { code, message: code } }));
145
+ assert(r.status === "failed", `${code} → ${r.status}`);
146
+ }
147
+ });
148
+
149
+ test("empty or non-JSON output is a failure", () => {
150
+ assert(classifyAuditOutput("").status === "failed", "empty");
151
+ assert(classifyAuditOutput("not json").status === "failed", "not json");
152
+ });
153
+
126
154
  console.log(`\n${passed} passed, ${failed} failed`);
127
155
  process.exit(failed ? 1 : 0);
@@ -0,0 +1,387 @@
1
+ #!/bin/bash
2
+ # Example. Copy into scripts/ci/ and own it.
3
+ # bkit install does not write this file and does not overwrite a copy.
4
+ #
5
+ # bkit-machine-lock.sh — machine-wide named locks and the checkout's shared stack lock.
6
+ #
7
+ # . scripts/ci/bkit-machine-lock.sh
8
+ # take_local_stack_lock "<who>" [name] # waits, returns 1 on refusal
9
+ # try_local_stack_lock "<who>" [name] # returns 1 immediately while busy
10
+ # release_local_stack_lock [name] # optional; caller exit also frees the lock
11
+ # local_stack_lock_holder [name]
12
+ # local_stack_lock_file [name]
13
+ #
14
+ # package.json: wrap test gates with
15
+ # bash scripts/ci/bkit-machine-lock.sh run --lock tests -- <gate command> [args…]
16
+ # run ["<who>"] [--lock <name>] -- <command> exits with the command's status:
17
+ # 2 usage, 73 the lock could not be taken, 75 the wait gave up.
18
+ # The run name defaults to LOCAL_STACK_LOCK_WHO, npm_lifecycle_event, then run.
19
+ # TERM, INT and HUP defer cancellation until the foreground command ends, keeping
20
+ # its lock held throughout; the wrapper then returns the signal's exit status.
21
+ #
22
+ # Named locks live in ${XDG_CACHE_HOME:-$HOME/.cache}/bkit/machine-lock/ with no
23
+ # repository prefix. The unnamed stack lock keeps its local-stack-lock/ path and
24
+ # LOCAL_STACK_LOCK_OWNER / LOCAL_STACK_LOCK_PID names, so adopted copies still work.
25
+ # Named owners use LOCAL_STACK_LOCK_OWNER_<key> and LOCAL_STACK_LOCK_PID_<key>.
26
+ # Each holder records its checkout, process id and start time.
27
+ #
28
+ # Take locks in this order: tests, other named locks, then the unnamed stack lock.
29
+ # A child reuses only the named or unnamed lock its live parent holds.
30
+ # BKIT_TEST_SLOTS sets the tests slots (whole number >= 1, default 1). Taking tests
31
+ # exports BKIT_TEST_WORKERS=max(1, floor(cores / slots) - 1) for the runner to use.
32
+ # LOCAL_STACK_LOCK_WAIT_S caps the wait; otherwise it is 60s without a TTY, 3600s
33
+ # with a TTY. Named releases save each checkout's held seconds in <name>.last.
34
+ # Waiting notes name every holder and that checkout's last run. CI=true / CI=1 is a no-op.
35
+ # A Perl flock holder exits within a second of its caller; killed callers leave no stale lock.
36
+ # Requires Bash 3.2+ and /usr/bin/perl.
37
+
38
+ _LOCAL_STACK_LOCK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
39
+ _LOCAL_STACK_LOCK_ROOT="$(git -C "$_LOCAL_STACK_LOCK_DIR" rev-parse --show-toplevel 2>/dev/null || echo "$_LOCAL_STACK_LOCK_DIR")"
40
+ LOCAL_STACK_LOCK_PID="${LOCAL_STACK_LOCK_PID:-}"
41
+ _LOCAL_STACK_LOCK_EXIT=73
42
+
43
+ # The stack's name: BKIT_LOCAL_STACK, else the main checkout's folder name, the same from every
44
+ # worktree. Characters outside A-Z a-z 0-9 . _ - become _.
45
+ local_stack_lock_name() {
46
+ _lsl_name="${BKIT_LOCAL_STACK:-}"
47
+ if [ -z "$_lsl_name" ]; then
48
+ _lsl_common="$(git -C "$_LOCAL_STACK_LOCK_DIR" rev-parse --path-format=absolute --git-common-dir 2>/dev/null)" || return 1
49
+ [ -n "$_lsl_common" ] || return 1
50
+ case "$(basename "$_lsl_common")" in
51
+ .git) _lsl_name="$(basename "$(dirname "$_lsl_common")")" ;;
52
+ *) _lsl_name="$(basename "$_lsl_common" .git)" ;;
53
+ esac
54
+ fi
55
+ printf '%s\n' "$_lsl_name" | LC_ALL=C tr -c 'A-Za-z0-9._\n-' '_'
56
+ }
57
+
58
+ # A named lock has one machine-wide path; the unnamed path remains stack-scoped.
59
+ local_stack_lock_file() {
60
+ local _lsl_stack
61
+ if [ -n "${1:-}" ]; then
62
+ _lsl_stack="$(printf '%s' "$1" | LC_ALL=C tr -c 'A-Za-z0-9._-' '_')"
63
+ echo "${XDG_CACHE_HOME:-$HOME/.cache}/bkit/machine-lock/${_lsl_stack}.lock"
64
+ else
65
+ _lsl_stack="$(local_stack_lock_name)" || return 1
66
+ echo "${XDG_CACHE_HOME:-$HOME/.cache}/bkit/local-stack-lock/${_lsl_stack}.lock"
67
+ fi
68
+ }
69
+
70
+ # "<who> — <checkout> (pid N, since HH:MM:SS)" for the run holding the lock.
71
+ local_stack_lock_holder() {
72
+ local _lsl_held _lsl_slot
73
+ _lsl_held="$(local_stack_lock_file "${1:-}")" || return 0
74
+ if [ -f "${_lsl_held}.holder" ]; then
75
+ cat "${_lsl_held}.holder"
76
+ fi
77
+ if [ "${1:-}" = tests ]; then
78
+ for _lsl_slot in "${_lsl_held%.lock}".[0-9]*.lock.holder; do
79
+ [ -f "$_lsl_slot" ] && cat "$_lsl_slot"
80
+ done
81
+ fi
82
+ return 0
83
+ }
84
+
85
+ _local_stack_lock_slots() {
86
+ _lsl_slots="${BKIT_TEST_SLOTS-1}"
87
+ case "$_lsl_slots" in
88
+ *[!0-9]*|"") _lsl_slots=0 ;;
89
+ *) _lsl_slots=$((10#$_lsl_slots)) ;;
90
+ esac
91
+ if [ "$_lsl_slots" -lt 1 ]; then
92
+ if [ "${_LOCAL_STACK_LOCK_SLOTS_NOTED:-}" != 1 ]; then
93
+ echo "[machine-lock] invalid BKIT_TEST_SLOTS; using 1 slot" >&2
94
+ _LOCAL_STACK_LOCK_SLOTS_NOTED=1
95
+ fi
96
+ _lsl_slots=1
97
+ fi
98
+ }
99
+
100
+ _local_stack_lock_workers() {
101
+ local _lsl_cores="" _lsl_probe
102
+ for _lsl_probe in getconf nproc sysctl; do
103
+ case "$_lsl_probe" in
104
+ getconf) _lsl_cores="$(getconf _NPROCESSORS_ONLN 2>/dev/null)" || continue ;;
105
+ nproc) _lsl_cores="$(nproc 2>/dev/null)" || continue ;;
106
+ sysctl) _lsl_cores="$(sysctl -n hw.ncpu 2>/dev/null)" || continue ;;
107
+ esac
108
+ case "$_lsl_cores" in *[!0-9]*|""|0) continue ;; esac
109
+ break
110
+ done
111
+ case "$_lsl_cores" in *[!0-9]*|""|0) _lsl_cores=1 ;; esac
112
+ BKIT_TEST_WORKERS=$((_lsl_cores / _lsl_slots - 1))
113
+ [ "$BKIT_TEST_WORKERS" -ge 1 ] || BKIT_TEST_WORKERS=1
114
+ export BKIT_TEST_WORKERS
115
+ }
116
+
117
+ _local_stack_lock_vars() {
118
+ local _lsl_key
119
+ _lsl_key="$(printf '%s' "${1:-}" | LC_ALL=C tr -c 'A-Za-z0-9._-' '_')"
120
+ _lsl_key="${_lsl_key//_/__}"
121
+ _lsl_key="${_lsl_key//-/_h}"
122
+ _lsl_key="${_lsl_key//./_d}"
123
+ _lsl_pid_var="LOCAL_STACK_LOCK_PID"
124
+ _lsl_owner_var="LOCAL_STACK_LOCK_OWNER"
125
+ _lsl_name_var="LOCAL_STACK_LOCK_NAME"
126
+ if [ -n "${1:-}" ]; then
127
+ _lsl_pid_var="${_lsl_pid_var}_${_lsl_key}"
128
+ _lsl_owner_var="${_lsl_owner_var}_${_lsl_key}"
129
+ _lsl_name_var="${_lsl_name_var}_${_lsl_key}"
130
+ fi
131
+ }
132
+
133
+ _local_stack_lock() {
134
+ local _lsl_mode="$1" _lsl_who="$2" _lsl_name="${3:-}"
135
+ local _lsl_pid_var _lsl_owner_var _lsl_name_var _lsl_owner _lsl_existing
136
+ local _lsl_file _lsl_label _lsl_fifo _lsl_pid _lsl_reply _lsl_checkout
137
+ local _lsl_slots=1 _lsl_wait _lsl_var _lsl_held_name _lsl_held_name_var
138
+ _LOCAL_STACK_LOCK_EXIT=73
139
+ _local_stack_lock_vars "$_lsl_name"
140
+ _lsl_owner="${!_lsl_owner_var:-}"
141
+ _lsl_existing="${!_lsl_pid_var:-}"
142
+ if [ "${CI:-}" = "true" ] || [ "${CI:-}" = "1" ]; then return 0; fi
143
+ if [ "$_lsl_name" = tests ]; then
144
+ _local_stack_lock_slots
145
+ _local_stack_lock_workers
146
+ fi
147
+ if [ -n "$_lsl_owner" ] && kill -0 "$_lsl_owner" 2>/dev/null; then return 0; fi
148
+ if [ -n "$_lsl_existing" ] && kill -0 "$_lsl_existing" 2>/dev/null; then return 0; fi
149
+ if [ -n "$_lsl_name" ]; then
150
+ for _lsl_var in ${!LOCAL_STACK_LOCK_OWNER*}; do
151
+ _lsl_owner="${!_lsl_var:-}"
152
+ [ -n "$_lsl_owner" ] && kill -0 "$_lsl_owner" 2>/dev/null || continue
153
+ if [ "$_lsl_var" = LOCAL_STACK_LOCK_OWNER ] || [ "$_lsl_name" = tests ]; then
154
+ _lsl_held_name_var="${_lsl_var/OWNER/NAME}"
155
+ _lsl_held_name="${!_lsl_held_name_var:-the unnamed stack lock}"
156
+ echo "[machine-lock] ❌ cannot take $_lsl_name while holding $_lsl_held_name: lock order is tests, other named locks, then the unnamed stack lock" >&2
157
+ return 1
158
+ fi
159
+ done
160
+ fi
161
+ if [ "${LOCAL_STACK_LOCK_WAIT_S+x}" = x ]; then
162
+ _lsl_wait="$LOCAL_STACK_LOCK_WAIT_S"
163
+ elif [ -t 0 ]; then
164
+ _lsl_wait=3600
165
+ else
166
+ _lsl_wait=60
167
+ fi
168
+
169
+ if ! _lsl_file="$(local_stack_lock_file "$_lsl_name")"; then
170
+ echo "[machine-lock] ❌ cannot name the local stack: run inside a git checkout, or set BKIT_LOCAL_STACK" >&2
171
+ return 1
172
+ fi
173
+ _lsl_label="the local stack $(basename "$_lsl_file" .lock)"
174
+ _lsl_checkout="$_LOCAL_STACK_LOCK_ROOT"
175
+ if [ -n "$_lsl_name" ]; then
176
+ _lsl_label="$_lsl_name"
177
+ _lsl_checkout="$(git -C "$PWD" rev-parse --show-toplevel 2>/dev/null || printf '%s' "$PWD")"
178
+ fi
179
+ if [ ! -x /usr/bin/perl ]; then
180
+ echo "[machine-lock] ❌ could not take the lock for $_lsl_label: /usr/bin/perl not found" >&2
181
+ return 1
182
+ fi
183
+ if ! mkdir -p "$(dirname "$_lsl_file")"; then
184
+ echo "[machine-lock] ❌ could not take the lock for $_lsl_label: cannot create $(dirname "$_lsl_file")" >&2
185
+ return 1
186
+ fi
187
+ _lsl_fifo="$(mktemp -u "${TMPDIR:-/tmp}/local-stack-lock.XXXXXX")"
188
+ mkfifo "$_lsl_fifo" || return 1
189
+
190
+ # The holder answers on the fifo once: ok, busy <holder>, timeout <holder> or error <why>.
191
+ /usr/bin/perl -e '
192
+ use strict;
193
+ use Fcntl qw(:flock);
194
+ use File::Glob qw(bsd_glob);
195
+ use POSIX qw(strftime);
196
+ my ($file, $owner, $who, $checkout, $fifo, $wait_s, $mode, $label, $slots, $name) = @ARGV;
197
+ # The caller is the parent of this process. When it exits, this process goes to init (or a
198
+ # subreaper) at once, while `kill 0` would still find it until whoever started it reaps it.
199
+ my $parent = getppid();
200
+ my $caller_alive = sub { getppid() == $parent };
201
+ open(my $out, ">", $fifo) or exit 1;
202
+ $out->autoflush(1);
203
+ my $stem = $file; $stem =~ s/\.lock$//;
204
+ my $history = "$stem.last";
205
+ my $holder = sub {
206
+ my @files = ("$file.holder");
207
+ push @files, grep { /^\Q$stem\E\.\d+\.lock\.holder$/ } bsd_glob("$stem.*.lock.holder") if $name eq "tests";
208
+ my @holders;
209
+ for my $held (@files) {
210
+ open(my $h, "<", $held) or next;
211
+ my $line = <$h>; close $h;
212
+ next unless defined $line;
213
+ chomp $line;
214
+ if (length $name) {
215
+ my ($held_checkout) = $line =~ / — (.*) \(pid /;
216
+ my $duration;
217
+ if (defined $held_checkout && open(my $last, "<", $history)) {
218
+ while (my $row = <$last>) {
219
+ chomp $row;
220
+ my ($path, $seconds) = split /\t/, $row, 2;
221
+ $duration = $seconds if $path eq $held_checkout && defined $seconds && $seconds =~ /^\d+$/;
222
+ }
223
+ close $last;
224
+ }
225
+ $line .= defined $duration ? ", last run took " . int($duration / 60) . "m" . ($duration % 60) . "s" : ", no earlier run";
226
+ }
227
+ push @holders, $line;
228
+ }
229
+ return @holders ? join("; ", @holders) : "another run";
230
+ };
231
+ my ($lock, $held_file);
232
+ my $start = time;
233
+ my $next_note = 0;
234
+ while (1) {
235
+ for my $slot (1 .. $slots) {
236
+ my $candidate = $slot == 1 ? $file : "$stem.$slot.lock";
237
+ open(my $next, ">>", $candidate) or do { print $out "error cannot open $candidate: $!\n"; exit 1 };
238
+ if (flock($next, LOCK_EX | LOCK_NB)) { $lock = $next; $held_file = $candidate; last }
239
+ close $next;
240
+ }
241
+ last if defined $lock;
242
+ exit 0 unless $caller_alive->();
243
+ if ($mode eq "try") { print $out "busy " . $holder->() . "\n"; exit 0 }
244
+ if (time - $start >= $wait_s) { print $out "timeout " . $holder->() . "\n"; exit 0 }
245
+ if (time >= $next_note) {
246
+ my $m = int((time - $start) / 60);
247
+ my $so_far = $m ? " (still, $m min so far)" : "";
248
+ print STDERR "[machine-lock] ⏳ $who is waiting for $label$so_far (up to ${wait_s}s): in use by " . $holder->() . "\n";
249
+ $next_note = time + 60;
250
+ }
251
+ select(undef, undef, undef, 0.1);
252
+ }
253
+ my $stopping = 0;
254
+ $SIG{TERM} = $SIG{INT} = $SIG{HUP} = sub { $stopping = 1 };
255
+ my $held_since = time;
256
+ if (open(my $h, ">", "$held_file.holder")) {
257
+ print $h "$who — $checkout (pid $owner, since " . strftime("%H:%M:%S", localtime) . ")\n";
258
+ close $h;
259
+ }
260
+ print $out "ok\n";
261
+ close $out;
262
+ select(undef, undef, undef, 0.1) while !$stopping && $caller_alive->();
263
+ if (length $name) {
264
+ # Serialize history updates across slots; the portable shell replaces just this checkout row.
265
+ my $history_lock;
266
+ if (open($history_lock, ">>", "$history.lock") && flock($history_lock, LOCK_EX)) {
267
+ my $pattern = $checkout; $pattern =~ s/([.\[\]\\*^\$])/\\$1/g;
268
+ $pattern = "^$pattern\t";
269
+ my $status = system("bash", "-c", q{
270
+ history="$1"; pattern="$2"; checkout="$3"; held="$4"
271
+ tmp=$(mktemp "$history.XXXXXX") || exit 1
272
+ if [ -f "$history" ]; then
273
+ grep -v "$pattern" "$history" >"$tmp"
274
+ code=$?
275
+ if [ "$code" -gt 1 ]; then rm -f "$tmp"; exit 1; fi
276
+ fi
277
+ printf "%s\t%s\n" "$checkout" "$held" >>"$tmp" && mv "$tmp" "$history"
278
+ }, "machine-lock-history", $history, $pattern, $checkout, time - $held_since);
279
+ print STDERR "[machine-lock] could not record $name held time in $history\n" if $status;
280
+ close $history_lock;
281
+ } else { print STDERR "[machine-lock] could not lock $history for held-time history: $!\n" }
282
+ }
283
+ unlink "$held_file.holder";
284
+ ' "$_lsl_file" "$$" "$_lsl_who" "$_lsl_checkout" "$_lsl_fifo" "$_lsl_wait" "$_lsl_mode" "$_lsl_label" "$_lsl_slots" "$_lsl_name" </dev/null >/dev/null &
285
+ _lsl_pid=$!
286
+ # The fifo is opened read-write, so the read never blocks on a holder that died before it
287
+ # answered (a failed fork under load, a killed perl): the loop stops once it is gone.
288
+ _lsl_reply="$(
289
+ exec 3<>"$_lsl_fifo"
290
+ while :; do
291
+ if IFS= read -r -t 1 _lsl_line <&3; then
292
+ printf '%s' "$_lsl_line"
293
+ break
294
+ fi
295
+ if ! kill -0 "$_lsl_pid" 2>/dev/null; then
296
+ # The holder may have answered and exited between the read timing out and this check.
297
+ if IFS= read -r -t 1 _lsl_line <&3; then printf '%s' "$_lsl_line"; fi
298
+ break
299
+ fi
300
+ done
301
+ )" || true
302
+ rm -f "$_lsl_fifo"
303
+
304
+ case "$_lsl_reply" in
305
+ ok)
306
+ printf -v "$_lsl_pid_var" '%s' "$_lsl_pid"
307
+ printf -v "$_lsl_owner_var" '%s' "$$"
308
+ export "$_lsl_owner_var"
309
+ printf -v "$_lsl_name_var" '%s' "${_lsl_name:-the unnamed stack lock}"
310
+ export "$_lsl_name_var"
311
+ return 0
312
+ ;;
313
+ busy\ *)
314
+ _LOCAL_STACK_LOCK_EXIT=75
315
+ echo "[machine-lock] $_lsl_label is in use by ${_lsl_reply#busy }" >&2
316
+ ;;
317
+ timeout\ *)
318
+ _LOCAL_STACK_LOCK_EXIT=75
319
+ echo "[machine-lock] ❌ $_lsl_who gave up after ${_lsl_wait}s waiting for $_lsl_label, in use by ${_lsl_reply#timeout }" >&2
320
+ echo "[machine-lock] Let that run finish, or stop it. LOCAL_STACK_LOCK_WAIT_S sets how long to wait." >&2
321
+ ;;
322
+ "")
323
+ echo "[machine-lock] ❌ could not take the lock for $_lsl_label: the perl process holding it stopped before it answered" >&2
324
+ ;;
325
+ *)
326
+ echo "[machine-lock] ❌ could not take the lock for $_lsl_label: ${_lsl_reply#error }" >&2
327
+ ;;
328
+ esac
329
+ wait "$_lsl_pid" 2>/dev/null || true
330
+ return 1
331
+ }
332
+
333
+ take_local_stack_lock() { _local_stack_lock wait "$1" "${2:-}"; }
334
+ try_local_stack_lock() { _local_stack_lock try "$1" "${2:-}"; }
335
+
336
+ release_local_stack_lock() {
337
+ local _lsl_pid_var _lsl_owner_var _lsl_name_var _lsl_release_pid
338
+ _local_stack_lock_vars "${1:-}"
339
+ _lsl_release_pid="${!_lsl_pid_var:-}"
340
+ [ -n "$_lsl_release_pid" ] || return 0
341
+ kill "$_lsl_release_pid" 2>/dev/null || true
342
+ wait "$_lsl_release_pid" 2>/dev/null || true
343
+ printf -v "$_lsl_pid_var" '%s' ""
344
+ unset "$_lsl_owner_var"
345
+ unset "$_lsl_name_var"
346
+ return 0
347
+ }
348
+
349
+ if [ "${BASH_SOURCE[0]}" = "$0" ]; then
350
+ _lsl_run_usage() {
351
+ echo 'usage: bash scripts/ci/bkit-machine-lock.sh run ["<who>"] [--lock <name>] -- <command> [args…]' >&2
352
+ exit 2
353
+ }
354
+ [ "${1:-}" = run ] || _lsl_run_usage
355
+ shift
356
+ _lsl_run_who="${LOCAL_STACK_LOCK_WHO:-${npm_lifecycle_event:-run}}"
357
+ _lsl_run_name=""
358
+ case "${1:-}" in
359
+ --lock|--) ;;
360
+ "") _lsl_run_usage ;;
361
+ *) _lsl_run_who="$1"; shift ;;
362
+ esac
363
+ if [ "${1:-}" = --lock ]; then
364
+ [ -n "${2:-}" ] && [ "$2" != -- ] || _lsl_run_usage
365
+ _lsl_run_name="$2"
366
+ shift 2
367
+ fi
368
+ [ "${1:-}" = -- ] || _lsl_run_usage
369
+ shift
370
+ [ "$#" -gt 0 ] || _lsl_run_usage
371
+ take_local_stack_lock "$_lsl_run_who" "$_lsl_run_name" || exit "$_LOCAL_STACK_LOCK_EXIT"
372
+ _lsl_run_signal_status=0
373
+ _lsl_run_cancel() {
374
+ _lsl_run_signal_status="$1"
375
+ echo "[machine-lock] cancellation requested; waiting for $_lsl_run_who to finish before releasing its lock" >&2
376
+ }
377
+ # Bash runs these traps after its foreground command ends. Keeping this owner
378
+ # alive also keeps the Perl holder alive while that command finishes naturally.
379
+ trap '_lsl_run_cancel 143' TERM
380
+ trap '_lsl_run_cancel 130' INT
381
+ trap '_lsl_run_cancel 129' HUP
382
+ "$@"
383
+ _lsl_run_status=$?
384
+ release_local_stack_lock "$_lsl_run_name"
385
+ [ "$_lsl_run_signal_status" -eq 0 ] || _lsl_run_status="$_lsl_run_signal_status"
386
+ exit "$_lsl_run_status"
387
+ fi