@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
@@ -7,17 +7,22 @@
7
7
  // folder). Each exports a list of steps; `max` also runs every `min` step. No file → nothing
8
8
  // runs, and worktree setup checks nothing.
9
9
  //
10
- // `--auto` is the hooks' entry: a mode runs at most once a day per machine, and `max` at
11
- // most once an hour while free disk is under `bkit.disk.minFreeGb`; the sweep then runs
12
- // detached and logs to the bkit cache folder, so the hook does not wait. `bkit worktrees
13
- // setup` calls `ensureDiskSpace` before it mints. A lock in the cache folder keeps one sweep
14
- // at a time across every repo. CI and cloud sessions run nothing.
10
+ // `--auto` is the hooks' entry: a mode runs at most once a day, and `max` at most once an
11
+ // hour while free disk is under `bkit.workflows.minFreeGb`. The machine file's steps keep one
12
+ // limit for the whole machine; each checkout's repo steps keep their own, so a sweep another
13
+ // repo started never uses up this checkout's day. The sweep then runs detached, only for the
14
+ // files that are due, and logs to the bkit cache folder, so the hook does not wait. `bkit
15
+ // worktrees setup` calls `ensureDiskSpace` before it mints. A lock in the cache folder keeps
16
+ // one sweep at a time across every repo; the detached sweep and the worktree check wait for
17
+ // their turn, so a day already counted is never lost to a running sweep. A hand run stops
18
+ // unless it passes `--wait`. CI and cloud sessions run nothing.
15
19
  //
16
20
  // A step calls `note()` for what it found but would not delete on its own (a worktree with
17
21
  // uncommitted files, say). Each sweep replaces its checkout's notes in the cache folder;
18
22
  // `bkit tips` lists them first, so the workflow that prints its tips surfaces them.
19
23
 
20
24
  import { spawn, spawnSync } from "node:child_process";
25
+ import { createHash } from "node:crypto";
21
26
  import * as fs from "node:fs";
22
27
  import * as os from "node:os";
23
28
  import * as path from "node:path";
@@ -26,6 +31,7 @@ import { pathToFileURL } from "node:url";
26
31
  import { isCloudOrCi } from "../../checks/before/env.js";
27
32
  import { readJsonFile } from "../../shared/json.js";
28
33
  import { readBkitConfig } from "../../shared/settings.js";
34
+ import { TIMEOUTS } from "../../shared/timeouts.js";
29
35
  import { CommandError, EXIT, git, type CommandSpec } from "../lib.js";
30
36
  import { tryCreate } from "./locks.js";
31
37
 
@@ -34,12 +40,16 @@ const MODES: readonly string[] = ["min", "max"];
34
40
 
35
41
  export const REPO_STEPS = "scripts/cleanup/bkit-disk-prune.mjs";
36
42
  const TEMPLATES = ".bkit/templates/scripts/cleanup/";
37
- const SETTING = "bkit.disk.minFreeGb";
43
+ const SETTING = "bkit.workflows.minFreeGb";
38
44
 
39
45
  const HOUR_MS = 60 * 60 * 1000;
40
46
  const DAY_MS = 24 * HOUR_MS;
41
47
  /** A lock this old, or whose process is gone, belongs to a sweep that died. */
42
48
  const LOCK_STALE_MS = HOUR_MS;
49
+ /** How often a running sweep renews its lock, so a long sweep is never taken for a dead one. */
50
+ const LOCK_RENEW_MS = 10 * 60 * 1000;
51
+ /** How often a waiting sweep tries the lock again. */
52
+ const LOCK_POLL_MS = 5_000;
43
53
  const GB = 1e9;
44
54
 
45
55
  const configDir = () =>
@@ -49,10 +59,21 @@ const cacheDir = () =>
49
59
  export const machineStepsPath = () => path.join(configDir(), "disk-prune.mjs");
50
60
  export const sweepLogPath = () => path.join(cacheDir(), "disk-prune.log");
51
61
  const lockPath = () => path.join(cacheDir(), "disk-prune.lock");
52
- const stampPath = (name: string) => path.join(cacheDir(), `disk-prune-${name}.stamp`);
62
+ /** One stamp per limit: the machine file's under `machine`, a checkout's repo file's under its top. */
63
+ const stampPath = (key: string, name: string) =>
64
+ path.join(
65
+ cacheDir(),
66
+ key === MACHINE
67
+ ? `disk-prune-${name}.stamp`
68
+ : `disk-prune-${name}-${createHash("sha256").update(key).digest("hex").slice(0, 12)}.stamp`,
69
+ );
70
+ /** A checkout's stamps this old belong to a checkout no hook has run in since (a removed worktree). */
71
+ const STAMP_STALE_MS = 7 * DAY_MS;
72
+ const REPO_STAMP = /^disk-prune-[a-z]+-[0-9a-f]{12}\.stamp$/;
53
73
  const notesPath = () => path.join(cacheDir(), "disk-prune-notes.json");
54
74
  /** Notes older than this are dropped: no sweep has run there since. */
55
75
  const NOTES_STALE_MS = 7 * DAY_MS;
76
+ const MACHINE = "machine";
56
77
 
57
78
  const gb = (bytes: number | null) => (bytes === null ? "?" : `${(bytes / GB).toFixed(1)} GB`);
58
79
  const errorText = (err: unknown) => (err instanceof Error ? err.message : String(err));
@@ -81,7 +102,8 @@ export interface Step {
81
102
  paths?: string[];
82
103
  }
83
104
 
84
- type Scope = "repo" | "machine";
105
+ export type Scope = "repo" | "machine";
106
+ const SCOPES: readonly string[] = ["repo", "machine"];
85
107
 
86
108
  interface StepFile {
87
109
  scope: Scope;
@@ -94,15 +116,21 @@ interface StepFile {
94
116
 
95
117
  const checkoutTop = (cwd: string) => git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
96
118
 
97
- /** The step files that exist for `cwd`, repo first. */
98
- function stepFilePaths(cwd: string): { scope: Scope; file: string; cwd: string }[] {
119
+ /** The step files that exist for `cwd`, repo first; only `scopes`' files when given. */
120
+ function stepFilePaths(
121
+ cwd: string,
122
+ scopes?: readonly Scope[],
123
+ ): { scope: Scope; file: string; cwd: string }[] {
99
124
  const top = checkoutTop(cwd);
100
125
  return [
101
126
  { scope: "repo" as const, file: path.join(top, REPO_STEPS), cwd: top },
102
127
  { scope: "machine" as const, file: machineStepsPath(), cwd: os.homedir() },
103
- ].filter((f) => fs.existsSync(f.file));
128
+ ].filter((f) => (scopes === undefined || scopes.includes(f.scope)) && fs.existsSync(f.file));
104
129
  }
105
130
 
131
+ /** Whose limits a step file counts against: the machine's, or its checkout's. */
132
+ const stampKey = (f: { scope: Scope; cwd: string }) => (f.scope === "machine" ? MACHINE : f.cwd);
133
+
106
134
  const isAction = (v: unknown) => typeof v === "string" || typeof v === "function";
107
135
 
108
136
  function stepProblem(step: unknown): string | null {
@@ -167,14 +195,22 @@ function sizeOf(patterns: string[], cwd: string): number | null {
167
195
  .reduce((sum, line) => sum + Number(line.split(/\s/)[0] ?? 0) * 1024, 0);
168
196
  }
169
197
 
170
- function due(name: string, everyMs: number, now: number): boolean {
171
- const st = fs.statSync(stampPath(name), { throwIfNoEntry: false });
198
+ function due(key: string, name: string, everyMs: number, now: number): boolean {
199
+ const st = fs.statSync(stampPath(key, name), { throwIfNoEntry: false });
172
200
  return st === undefined || now - st.mtimeMs >= everyMs;
173
201
  }
174
202
 
175
- function touch(...names: string[]): void {
203
+ /** Stamp `names` for `key`, and drop checkout stamps no hook has renewed in 7 days. */
204
+ function touch(key: string, ...names: string[]): void {
176
205
  fs.mkdirSync(cacheDir(), { recursive: true });
177
- for (const name of names) fs.writeFileSync(stampPath(name), `${new Date().toISOString()}\n`);
206
+ for (const name of names) fs.writeFileSync(stampPath(key, name), `${new Date().toISOString()}\n`);
207
+ for (const entry of fs.readdirSync(cacheDir())) {
208
+ if (!REPO_STAMP.test(entry)) continue;
209
+ const file = path.join(cacheDir(), entry);
210
+ const st = fs.statSync(file, { throwIfNoEntry: false });
211
+ if (st !== undefined && Date.now() - st.mtimeMs >= STAMP_STALE_MS)
212
+ fs.rmSync(file, { force: true });
213
+ }
178
214
  }
179
215
 
180
216
  function pidAlive(pid: number): boolean {
@@ -186,24 +222,80 @@ function pidAlive(pid: number): boolean {
186
222
  }
187
223
  }
188
224
 
189
- /** Take the sweep lock; a dead or hour-old holder's lock is replaced. False when held. */
225
+ /**
226
+ * Take the sweep lock; a lock whose holder is gone, or that no holder renewed for an hour, is
227
+ * replaced. False when held. The stale lock is renamed aside before it is removed, so a lock
228
+ * another sweep took after this one's check is put back, never deleted.
229
+ */
190
230
  function takeLock(): boolean {
191
231
  const file = lockPath();
192
232
  const line = `${new Date().toISOString()} ${process.pid}`;
193
233
  if (tryCreate(file, line)) return true;
194
234
  const st = fs.statSync(file, { throwIfNoEntry: false });
195
- const holder = st === undefined ? "" : fs.readFileSync(file, "utf-8");
235
+ if (st === undefined) return tryCreate(file, line);
236
+ const holder = fs.readFileSync(file, "utf-8");
196
237
  const pid = Number(holder.split(/\s+/)[1]);
197
- const live = st !== undefined && Date.now() - st.mtimeMs < LOCK_STALE_MS;
238
+ const live = Date.now() - st.mtimeMs < LOCK_STALE_MS;
198
239
  if (live && Number.isInteger(pid) && pid > 0 && pidAlive(pid)) return false;
199
- fs.rmSync(file, { force: true });
240
+ const aside = `${file}.${process.pid}.${Date.now()}.stale`;
241
+ try {
242
+ fs.renameSync(file, aside);
243
+ } catch (err) {
244
+ if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
245
+ return tryCreate(file, line);
246
+ }
247
+ const taken = fs.readFileSync(aside, "utf-8");
248
+ if (taken !== holder) {
249
+ restoreLock(aside, file);
250
+ return false;
251
+ }
252
+ fs.rmSync(aside, { force: true });
200
253
  return tryCreate(file, line);
201
254
  }
202
255
 
256
+ /** Put a lock renamed aside back at `file`, unless a third sweep has taken `file` since. */
257
+ function restoreLock(aside: string, file: string): void {
258
+ try {
259
+ fs.linkSync(aside, file);
260
+ } catch (err) {
261
+ if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
262
+ }
263
+ fs.rmSync(aside, { force: true });
264
+ }
265
+
266
+ /**
267
+ * Take the sweep lock, waiting while another sweep holds it. False only when it is still held
268
+ * after `maxWaitMs` (default `LOCK_STALE_MS`): a sweep that long renews its lock, so `takeLock`
269
+ * never replaces it.
270
+ */
271
+ async function waitForLock(
272
+ pollMs: number,
273
+ log: (m: string) => void,
274
+ maxWaitMs: number = LOCK_STALE_MS + pollMs,
275
+ ): Promise<boolean> {
276
+ if (takeLock()) return true;
277
+ log(`another sweep is running (${lockPath()}) — waiting for it to end`);
278
+ const deadline = Date.now() + maxWaitMs;
279
+ while (Date.now() < deadline) {
280
+ await new Promise((resolve) => setTimeout(resolve, pollMs));
281
+ if (takeLock()) return true;
282
+ }
283
+ return false;
284
+ }
285
+
286
+ const holdsLock = (file: string) =>
287
+ fs.existsSync(file) && fs.readFileSync(file, "utf-8").split(/\s+/)[1] === String(process.pid);
288
+
289
+ /** Mark this sweep's lock as live; another process's lock is left alone. */
290
+ function renewLock(): void {
291
+ const file = lockPath();
292
+ const now = new Date();
293
+ if (holdsLock(file)) fs.utimesSync(file, now, now);
294
+ }
295
+
203
296
  function releaseLock(): void {
204
297
  const file = lockPath();
205
- const pid = fs.existsSync(file) ? fs.readFileSync(file, "utf-8").split(/\s+/)[1] : undefined;
206
- if (pid === String(process.pid)) fs.rmSync(file, { force: true });
298
+ if (holdsLock(file)) fs.rmSync(file, { force: true });
207
299
  }
208
300
 
209
301
  // ---------------------------------------------------------------------------
@@ -234,17 +326,38 @@ export interface SweepResult {
234
326
  freeAfter: number | null;
235
327
  }
236
328
 
237
- function shell(command: string, cwd: string, log: (m: string) => void) {
238
- const r = spawnSync("sh", ["-c", command], { cwd, encoding: "utf-8", maxBuffer: 1 << 26 });
239
- const out = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim();
240
- if (out !== "") for (const line of out.split("\n").slice(-20)) log(` ${line}`);
241
- return r.error ? 127 : (r.status ?? 1);
329
+ /**
330
+ * Run a step's shell command and log its last 20 output lines. Spawned, not run in step: the
331
+ * lock renewal timer has to fire while a long command runs.
332
+ */
333
+ function shell(command: string, cwd: string, log: (m: string) => void): Promise<number> {
334
+ return new Promise((resolve) => {
335
+ const child = spawn("sh", ["-c", command], { cwd, stdio: ["ignore", "pipe", "pipe"] });
336
+ let out = "";
337
+ const keep = (chunk: Buffer) => {
338
+ out = `${out}${chunk.toString()}`.slice(-(1 << 16));
339
+ };
340
+ child.stdout.on("data", keep);
341
+ child.stderr.on("data", keep);
342
+ let settled = false;
343
+ const finish = (status: number) => {
344
+ if (settled) return;
345
+ settled = true;
346
+ const text = out.trim();
347
+ if (text !== "") for (const line of text.split("\n").slice(-20)) log(` ${line}`);
348
+ resolve(status);
349
+ };
350
+ child.on("error", () => finish(127));
351
+ child.on("close", (status) => finish(status ?? 1));
352
+ });
242
353
  }
243
354
 
244
355
  async function skipReason(step: Step, ctx: StepContext): Promise<string | null> {
245
356
  if (step.skip === undefined) return null;
246
357
  if (typeof step.skip === "string") {
247
- return shell(step.skip, ctx.cwd, ctx.log) === 0 ? `skip check passed: ${step.skip}` : null;
358
+ return (await shell(step.skip, ctx.cwd, ctx.log)) === 0
359
+ ? `skip check passed: ${step.skip}`
360
+ : null;
248
361
  }
249
362
  const answer = await step.skip(ctx);
250
363
  if (!answer) return null;
@@ -259,7 +372,7 @@ async function runStep(
259
372
  const reason = await skipReason(step, ctx);
260
373
  if (reason !== null) return { outcome: "skipped", detail: reason };
261
374
  if (typeof step.run === "string") {
262
- const status = shell(step.run, ctx.cwd, ctx.log);
375
+ const status = await shell(step.run, ctx.cwd, ctx.log);
263
376
  if (status !== 0) return { outcome: "failed", detail: `exit ${status}` };
264
377
  } else {
265
378
  await step.run(ctx);
@@ -271,13 +384,22 @@ async function runStep(
271
384
  }
272
385
 
273
386
  /**
274
- * Run the `mode` steps from every step file for `cwd`, one at a time, repo file first.
275
- * `dryRun` runs nothing and sizes each step's paths instead.
387
+ * Run the `mode` steps from every step file for `cwd` (only `scopes`' files when given), one
388
+ * at a time, repo file first. `dryRun` runs nothing and sizes each step's paths instead.
389
+ * While another sweep runs, `wait` waits for it to end; without it the sweep stops.
276
390
  */
277
391
  export async function sweep(opts: {
278
392
  cwd: string;
279
393
  mode: Mode;
280
394
  dryRun: boolean;
395
+ scopes?: readonly Scope[];
396
+ wait?: boolean;
397
+ /** How often a waiting sweep tries the lock again; tests shorten it. */
398
+ pollMs?: number;
399
+ /** Longest wait for the lock with `wait`; default a full stale lock age. */
400
+ maxWaitMs?: number;
401
+ /** How often a running sweep renews its lock; tests shorten it. */
402
+ renewMs?: number;
281
403
  log: (m: string) => void;
282
404
  }): Promise<SweepResult> {
283
405
  const result: SweepResult = {
@@ -289,7 +411,7 @@ export async function sweep(opts: {
289
411
  freeAfter: null,
290
412
  };
291
413
  if (isCloudOrCi()) return { ...result, reason: "ci" };
292
- const files = await Promise.all(stepFilePaths(opts.cwd).map(loadStepFile));
414
+ const files = await Promise.all(stepFilePaths(opts.cwd, opts.scopes).map(loadStepFile));
293
415
  result.files = files.map((f) => ({
294
416
  scope: f.scope,
295
417
  file: f.file,
@@ -321,10 +443,15 @@ export async function sweep(opts: {
321
443
  }
322
444
  return result;
323
445
  }
324
- if (!takeLock()) {
446
+ const locked = opts.wait
447
+ ? !(await waitForLock(opts.pollMs ?? LOCK_POLL_MS, opts.log, opts.maxWaitMs))
448
+ : !takeLock();
449
+ if (locked) {
325
450
  opts.log(`another sweep is running (${lockPath()})`);
326
451
  return { ...result, reason: "locked" };
327
452
  }
453
+ const renewal = setInterval(renewLock, opts.renewMs ?? LOCK_RENEW_MS);
454
+ renewal.unref();
328
455
  try {
329
456
  result.freeBefore = freeBytes(opts.cwd);
330
457
  opts.log(`${new Date().toISOString()} ${opts.mode} sweep, ${gb(result.freeBefore)} free`);
@@ -343,6 +470,7 @@ export async function sweep(opts: {
343
470
  opts.log(`${gb(result.freeBefore)} → ${gb(result.freeAfter)} free`);
344
471
  saveNotes(checkoutTop(opts.cwd), result.notes);
345
472
  } finally {
473
+ clearInterval(renewal);
346
474
  releaseLock();
347
475
  }
348
476
  return result;
@@ -407,13 +535,22 @@ export function formatNotes(notes: readonly string[]): string {
407
535
  // Scheduling (hooks) and the worktree check
408
536
  // ---------------------------------------------------------------------------
409
537
 
410
- /** Start `bkit disk prune --mode=<mode>` detached, its output appended to the sweep log. */
411
- function spawnDetached(mode: Mode, cwd: string): void {
538
+ /**
539
+ * The `bkit` arguments of the sweep `--auto` starts: the due `scopes` only, and waiting for
540
+ * a running sweep to end, so a hook that fires mid-sweep still gets its turn.
541
+ */
542
+ export function detachedArgs(mode: Mode, scopes: readonly Scope[]): string[] {
543
+ const only = scopes.length === 1 ? [`--scope=${scopes[0]}`] : [];
544
+ return ["disk", "prune", `--mode=${mode}`, ...only, "--wait"];
545
+ }
546
+
547
+ /** Start the `--auto` sweep detached, its output appended to the sweep log. */
548
+ function spawnDetached(mode: Mode, cwd: string, scopes: readonly Scope[]): void {
412
549
  fs.mkdirSync(cacheDir(), { recursive: true });
413
550
  const fd = fs.openSync(sweepLogPath(), "a");
414
551
  const child = spawn(
415
552
  process.execPath,
416
- [...process.execArgv, process.argv[1]!, "disk", "prune", `--mode=${mode}`],
553
+ [...process.execArgv, process.argv[1]!, ...detachedArgs(mode, scopes)],
417
554
  { cwd, detached: true, stdio: ["ignore", fd, fd] },
418
555
  );
419
556
  child.unref();
@@ -428,57 +565,77 @@ export interface Schedule {
428
565
  }
429
566
 
430
567
  /**
431
- * `--auto`: start a detached sweep when one is due. Under `minFreeGb` free → `max`, at
432
- * most hourly; else `mode`, at most daily. A `max` run also counts as that day's `min`.
568
+ * `--auto`: start a detached sweep of the step files that are due. Under `minFreeGb` free →
569
+ * `max`, at most hourly; else `mode`, at most daily. A `max` run also counts as that day's
570
+ * `min`. The machine file is due by the machine's stamps, the repo file by its checkout's.
433
571
  */
434
572
  export function schedule(opts: {
435
573
  cwd: string;
436
574
  mode: Mode;
437
575
  minFreeGb: number;
438
576
  now?: number;
439
- start?: (mode: Mode, cwd: string) => void;
577
+ start?: (mode: Mode, cwd: string, scopes: readonly Scope[]) => void;
440
578
  }): Schedule {
441
579
  if (isCloudOrCi()) return { started: null, reason: "ci" };
442
- if (stepFilePaths(opts.cwd).length === 0) return { started: null, reason: "no-steps" };
580
+ const files = stepFilePaths(opts.cwd);
581
+ if (files.length === 0) return { started: null, reason: "no-steps" };
443
582
  const now = opts.now ?? Date.now();
444
583
  const start = opts.start ?? spawnDetached;
445
584
  const free = freeBytes(opts.cwd);
446
- if (free !== null && free < opts.minFreeGb * GB) {
447
- if (!due("low", HOUR_MS, now)) return { started: null, reason: "not-due" };
448
- touch("low", "max", "min");
449
- start("max", opts.cwd);
450
- return { started: "max", reason: "low-disk" };
451
- }
452
- if (!due(opts.mode, DAY_MS, now)) return { started: null, reason: "not-due" };
453
- touch(...(opts.mode === "max" ? ["max", "min"] : ["min"]));
454
- start(opts.mode, opts.cwd);
455
- return { started: opts.mode, reason: "due" };
585
+ const low = free !== null && free < opts.minFreeGb * GB;
586
+ const mode = low ? "max" : opts.mode;
587
+ const dueFiles = files.filter((f) =>
588
+ low ? due(stampKey(f), "low", HOUR_MS, now) : due(stampKey(f), mode, DAY_MS, now),
589
+ );
590
+ if (dueFiles.length === 0) return { started: null, reason: "not-due" };
591
+ const names = low ? ["low", "max", "min"] : mode === "max" ? ["max", "min"] : ["min"];
592
+ for (const f of dueFiles) touch(stampKey(f), ...names);
593
+ start(
594
+ mode,
595
+ opts.cwd,
596
+ dueFiles.map((f) => f.scope),
597
+ );
598
+ return { started: mode, reason: low ? "low-disk" : "due" };
456
599
  }
457
600
 
458
601
  /**
459
602
  * Before worktree setup mints: under `minFreeGb` free with step files present, run the
460
- * `max` steps and check again. Null = carry on; else why the worktree must not be made.
603
+ * `max` steps (waiting for a running sweep to end first) and check again. Null = carry on;
604
+ * else why the worktree must not be made.
461
605
  */
462
606
  export async function ensureDiskSpace(opts: {
463
607
  cwd: string;
464
608
  minFreeGb: number;
465
609
  log: (m: string) => void;
610
+ /** How often to try the sweep lock again while another sweep runs; tests shorten it. */
611
+ pollMs?: number;
612
+ /** Longest wait for a running sweep; default `TIMEOUTS.DISK_SETUP_SWEEP_WAIT_S`. */
613
+ maxWaitMs?: number;
466
614
  }): Promise<string | null> {
467
- if (isCloudOrCi() || stepFilePaths(opts.cwd).length === 0) return null;
615
+ const files = isCloudOrCi() ? [] : stepFilePaths(opts.cwd);
616
+ if (files.length === 0) return null;
468
617
  const min = opts.minFreeGb * GB;
469
618
  const before = freeBytes(opts.cwd);
470
619
  if (before === null || before >= min) return null;
471
620
  opts.log(
472
621
  `${gb(before)} free, under ${SETTING} (${opts.minFreeGb} GB) — running your max cleanup steps`,
473
622
  );
474
- touch("low", "max", "min");
475
- const ran = await sweep({ cwd: opts.cwd, mode: "max", dryRun: false, log: opts.log });
623
+ for (const f of files) touch(stampKey(f), "low", "max", "min");
624
+ const ran = await sweep({
625
+ cwd: opts.cwd,
626
+ mode: "max",
627
+ dryRun: false,
628
+ wait: true,
629
+ pollMs: opts.pollMs,
630
+ maxWaitMs: opts.maxWaitMs ?? TIMEOUTS.DISK_SETUP_SWEEP_WAIT_S * 1000,
631
+ log: opts.log,
632
+ });
476
633
  const after = freeBytes(opts.cwd);
477
634
  if (after === null || after >= min) return null;
478
635
  opts.log("what your max steps still cover:");
479
636
  await sweep({ cwd: opts.cwd, mode: "max", dryRun: true, log: opts.log });
480
637
  const locked =
481
- ran.reason === "locked" ? " (another sweep was running — re-run once it ends)" : "";
638
+ ran.reason === "locked" ? " (another sweep still holds the lock — re-run once it ends)" : "";
482
639
  return `${gb(after)} free after your max cleanup steps, still under ${SETTING} (${opts.minFreeGb} GB)${locked} — free space by hand or add steps (.bkit/templates.md § Disk prune), then re-run`;
483
640
  }
484
641
 
@@ -492,6 +649,7 @@ export const diskCommand: CommandSpec = {
492
649
  verbs: {
493
650
  prune: {
494
651
  summary: `Run the min or max steps from ${REPO_STEPS} and ~/.config/bkit/disk-prune.mjs.`,
652
+ use: "by-hand",
495
653
  flags: [
496
654
  {
497
655
  name: "mode",
@@ -504,10 +662,20 @@ export const diskCommand: CommandSpec = {
504
662
  type: "boolean",
505
663
  help: "run nothing; list each step with the size of its paths",
506
664
  },
665
+ {
666
+ name: "scope",
667
+ type: "string",
668
+ help: "repo or machine: run only that file's steps (default: both)",
669
+ },
670
+ {
671
+ name: "wait",
672
+ type: "boolean",
673
+ help: "while another sweep runs, wait for it to end instead of stopping (the sweep --auto starts always waits)",
674
+ },
507
675
  {
508
676
  name: "auto",
509
677
  type: "boolean",
510
- help: `for hooks: run detached, at most once a day per mode; max at most hourly while free disk is under ${SETTING}`,
678
+ help: `for hooks: run detached, at most once a day per mode (machine steps once per machine, repo steps once per checkout); max at most hourly while free disk is under ${SETTING}`,
511
679
  },
512
680
  ],
513
681
  output: {
@@ -525,8 +693,15 @@ export const diskCommand: CommandSpec = {
525
693
  const mode = String(ctx.flags.mode);
526
694
  if (!MODES.includes(mode)) throw new CommandError(EXIT.USAGE, "--mode must be min or max");
527
695
  const dryRun = ctx.flags.dryRun === true;
696
+ const scope = ctx.flags.scope === undefined ? undefined : String(ctx.flags.scope);
697
+ if (scope !== undefined && !SCOPES.includes(scope))
698
+ throw new CommandError(EXIT.USAGE, "--scope must be repo or machine");
699
+ const scopes = scope === undefined ? undefined : [scope as Scope];
528
700
  if (ctx.flags.auto === true) {
529
701
  if (dryRun) throw new CommandError(EXIT.USAGE, "give --auto or --dry-run, not both");
702
+ if (scopes) throw new CommandError(EXIT.USAGE, "give --auto or --scope, not both");
703
+ if (ctx.flags.wait === true)
704
+ throw new CommandError(EXIT.USAGE, "give --auto or --wait, not both");
530
705
  const plan = schedule({
531
706
  cwd: ctx.cwd,
532
707
  mode: mode as Mode,
@@ -545,7 +720,14 @@ export const diskCommand: CommandSpec = {
545
720
  });
546
721
  return EXIT.OK;
547
722
  }
548
- const r = await sweep({ cwd: ctx.cwd, mode: mode as Mode, dryRun, log: ctx.log });
723
+ const r = await sweep({
724
+ cwd: ctx.cwd,
725
+ mode: mode as Mode,
726
+ dryRun,
727
+ scopes,
728
+ wait: ctx.flags.wait === true,
729
+ log: ctx.log,
730
+ });
549
731
  ctx.emit({ mode, started: null, ...r });
550
732
  const failed =
551
733
  r.files.some((f) => f.error !== null) || r.steps.some((s) => s.outcome === "failed");