@cbartens/bkit 6.1.0 → 6.2.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 (317) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +43 -33
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +99 -36
  15. package/.bkit/core/.bkit/templates.md +167 -37
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +161 -37
  64. package/.bkit/core/engine/checks/after/index.ts +18 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +124 -19
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/doctor.ts +5 -5
  76. package/.bkit/core/engine/commands/install/install.ts +28 -25
  77. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  78. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  79. package/.bkit/core/engine/commands/land.ts +2 -3
  80. package/.bkit/core/engine/commands/lib.ts +394 -39
  81. package/.bkit/core/engine/commands/registry.ts +1 -1
  82. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  83. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  84. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  85. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  86. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  87. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  88. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  89. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  90. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  91. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  92. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  93. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  94. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  95. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  96. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  97. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  98. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  99. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  100. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  101. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  102. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  103. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  104. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  105. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  106. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  107. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  108. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  109. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  110. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  111. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  112. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  113. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  114. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  115. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  116. package/.bkit/core/engine/install/managed-block.ts +105 -0
  117. package/.bkit/core/engine/install/manifest.ts +7 -1
  118. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  119. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  120. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  121. package/.bkit/core/engine/install/modules/core.ts +202 -26
  122. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  123. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  124. package/.bkit/core/engine/install/project-docs.ts +650 -0
  125. package/.bkit/core/engine/install/template-copies.ts +58 -5
  126. package/.bkit/core/engine/install/write.ts +128 -7
  127. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  128. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  129. package/.bkit/core/engine/ledgers/status.ts +604 -8
  130. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  131. package/.bkit/core/engine/render/trackers.ts +46 -11
  132. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  133. package/.bkit/core/engine/shared/settings.ts +12 -1
  134. package/.bkit/core/engine/shared/text.ts +14 -0
  135. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  136. package/.bkit/core/engine/tools/instructions.ts +116 -20
  137. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  138. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  139. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  140. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  141. package/.bkit/core/hooks/guardrails-read.js +3 -3
  142. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  143. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  144. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  145. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  146. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  147. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  148. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  149. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  150. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  151. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  152. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  153. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  154. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  155. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  156. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  157. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  158. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  159. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  162. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  163. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  164. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  165. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  166. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  167. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  168. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  169. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  170. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  172. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  173. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  174. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  175. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  176. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  177. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  178. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  179. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  180. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  181. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  182. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  183. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  184. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  185. package/.bkit/core/workflows/bkit-auto.md +23 -11
  186. package/.bkit/core/workflows/bkit-build.md +331 -100
  187. package/.bkit/core/workflows/bkit-debug.md +135 -64
  188. package/.bkit/core/workflows/bkit-design.md +58 -32
  189. package/.bkit/core/workflows/bkit-plan.md +73 -45
  190. package/.bkit/core/workflows/bkit-ship.md +233 -167
  191. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  192. package/.bkit/shared/.bkit/.env.example +5 -0
  193. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  194. package/.bkit/shared/.claude/settings.json +5 -1
  195. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  196. package/.bkit/shared/.cursor/hooks.json +1 -1
  197. package/.bkit/shared/.opencode/opencode.json +11 -2
  198. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  199. package/.bkit/templates/.cursor/Dockerfile +7 -7
  200. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  201. package/.bkit/templates/.github/dependabot.yml +5 -0
  202. package/.bkit/templates/.github/renovate.json5 +5 -3
  203. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  204. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  205. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  206. package/.bkit/templates/.husky/pre-push +123 -6
  207. package/.bkit/templates/context/bkit-serena.md +1 -1
  208. package/.bkit/templates/context/bkit-vercel.md +103 -59
  209. package/.bkit/templates/docs/architecture.md +98 -0
  210. package/.bkit/templates/docs/capabilities.md +33 -37
  211. package/.bkit/templates/docs/components.md +142 -0
  212. package/.bkit/templates/docs/data-schema.md +87 -0
  213. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  214. package/.bkit/templates/docs/design.md +117 -0
  215. package/.bkit/templates/docs/noise.md +54 -0
  216. package/.bkit/templates/docs/observability.md +99 -0
  217. package/.bkit/templates/docs/security.md +137 -0
  218. package/.bkit/templates/docs/setup.md +93 -0
  219. package/.bkit/templates/docs/technology.md +70 -0
  220. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  221. package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
  222. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  223. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
  224. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
  225. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  226. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
  227. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  228. package/.bkit/templates/slop-scan.config.json +2 -0
  229. package/CHANGELOG.md +79 -0
  230. package/DETAILS.md +661 -0
  231. package/README.md +73 -604
  232. package/dist/checks/after/auth.js +114 -46
  233. package/dist/checks/after/github.js +138 -35
  234. package/dist/checks/after/index.js +16 -4
  235. package/dist/checks/after/tools.js +224 -1
  236. package/dist/checks/before/files.js +59 -1
  237. package/dist/checks/before/index.js +7 -1
  238. package/dist/checks/status-holes.js +20 -21
  239. package/dist/checks/tips/catalogue.js +99 -10
  240. package/dist/checks/tips/detect.js +35 -3
  241. package/dist/checks/tips/index.js +1 -1
  242. package/dist/cli.js +13 -13
  243. package/dist/commands/ci/ci.js +113 -20
  244. package/dist/commands/ci/push-gate.js +79 -44
  245. package/dist/commands/install/doctor.js +5 -5
  246. package/dist/commands/install/install.js +23 -22
  247. package/dist/commands/install/uninstall.js +36 -30
  248. package/dist/commands/install/upgrade.js +10 -2
  249. package/dist/commands/land.js +2 -3
  250. package/dist/commands/lib.js +323 -25
  251. package/dist/commands/workflow/branches.js +312 -72
  252. package/dist/commands/workflow/challenge.js +66 -13
  253. package/dist/commands/workflow/context.js +46 -10
  254. package/dist/commands/workflow/counters.js +231 -23
  255. package/dist/commands/workflow/decisions.js +221 -106
  256. package/dist/commands/workflow/disk.js +2 -1
  257. package/dist/commands/workflow/feature-base.js +60 -0
  258. package/dist/commands/workflow/issues.js +243 -15
  259. package/dist/commands/workflow/junit.js +137 -0
  260. package/dist/commands/workflow/ledgers.js +726 -112
  261. package/dist/commands/workflow/locks.js +150 -29
  262. package/dist/commands/workflow/loops.js +67 -0
  263. package/dist/commands/workflow/open-decision.js +199 -0
  264. package/dist/commands/workflow/plan-blocks.js +6 -0
  265. package/dist/commands/workflow/plans.js +1 -1
  266. package/dist/commands/workflow/prs.js +272 -16
  267. package/dist/commands/workflow/repo.js +1 -1
  268. package/dist/commands/workflow/run-facts.js +6 -0
  269. package/dist/commands/workflow/runs.js +747 -155
  270. package/dist/commands/workflow/runtime.js +8 -4
  271. package/dist/commands/workflow/status.js +259 -13
  272. package/dist/commands/workflow/step-table.js +41 -15
  273. package/dist/commands/workflow/steps.js +530 -26
  274. package/dist/commands/workflow/summary-findings.js +1 -1
  275. package/dist/commands/workflow/summary.js +289 -8
  276. package/dist/commands/workflow/tasks.js +294 -27
  277. package/dist/commands/workflow/tests-base.js +266 -0
  278. package/dist/commands/workflow/tests-changed.js +130 -56
  279. package/dist/commands/workflow/tests-jump.js +77 -0
  280. package/dist/commands/workflow/tests.js +608 -131
  281. package/dist/commands/workflow/tracker.js +920 -112
  282. package/dist/commands/workflow/workflows.js +80 -59
  283. package/dist/commands/workflow/worktrees.js +387 -58
  284. package/dist/install/cloud-env.js +32 -10
  285. package/dist/install/managed-block.js +101 -0
  286. package/dist/install/manifest.js +7 -1
  287. package/dist/install/modules/claude.js +6 -2
  288. package/dist/install/modules/cloud.js +73 -86
  289. package/dist/install/modules/codex.js +9 -2
  290. package/dist/install/modules/core.js +190 -27
  291. package/dist/install/modules/opencode.js +18 -23
  292. package/dist/install/network-allowlist.js +8 -3
  293. package/dist/install/project-docs.js +551 -0
  294. package/dist/install/template-copies.js +55 -5
  295. package/dist/install/write.js +117 -5
  296. package/dist/ledgers/journal.js +10 -8
  297. package/dist/ledgers/migrate.js +20 -9
  298. package/dist/ledgers/status.js +461 -8
  299. package/dist/ledgers/telemetry.js +71 -13
  300. package/dist/render/trackers.js +21 -12
  301. package/dist/shared/package-manager.js +7 -2
  302. package/dist/shared/settings.js +8 -0
  303. package/dist/shared/text.js +13 -0
  304. package/dist/tools/instructions-sources.js +1 -0
  305. package/dist/tools/instructions.js +97 -24
  306. package/package.json +23 -15
  307. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  308. package/.bkit/shared/docs/architecture.md +0 -16
  309. package/.bkit/shared/docs/data-schema.md +0 -16
  310. package/.bkit/shared/docs/design.md +0 -38
  311. package/.bkit/shared/docs/noise.md +0 -20
  312. package/.bkit/shared/docs/observability.md +0 -22
  313. package/.bkit/shared/docs/security.md +0 -62
  314. package/.bkit/shared/docs/setup.md +0 -52
  315. package/.bkit/shared/docs/technology.md +0 -15
  316. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  317. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -6,7 +6,7 @@
6
6
  #
7
7
  # . scripts/ci/bkit-machine-lock.sh
8
8
  # take_local_stack_lock "<who>" [name] # waits, returns 1 on refusal
9
- # try_local_stack_lock "<who>" [name] # returns 1 immediately while busy
9
+ # try_local_stack_lock "<who>" [name] # returns 1 immediately while busy or runs wait in line
10
10
  # release_local_stack_lock [name] # optional; caller exit also frees the lock
11
11
  # local_stack_lock_holder [name]
12
12
  # local_stack_lock_file [name]
@@ -14,10 +14,38 @@
14
14
  # package.json: wrap test gates with
15
15
  # bash scripts/ci/bkit-machine-lock.sh run --lock tests -- <gate command> [args…]
16
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.
17
+ # 2 usage, 73 the lock could not be taken, 75 the wait gave up, 124 the hold limit stopped it.
18
+ # A run that took the tests lock holds it at most LOCAL_STACK_LOCK_HOLD_S seconds (whole number
19
+ # >= 1, default 3600; an invalid value falls back with one note). Its command runs under
20
+ # bkit-test-awake.mjs --hold-s beside this script, so such a run needs node on PATH and that file
21
+ # as the current template, and exits 73 without them. At the limit it sends TERM to the
22
+ # command and every process started under it, KILL to those still running after
23
+ # LOCAL_STACK_LOCK_HOLD_GRACE_S seconds (default 10), frees the lock, prints a [machine-lock]
24
+ # line naming the holder, the time held and the limit, and exits 124. Other locks, a run that
25
+ # reuses its live parent's lock, and CI have no limit. Under the limit the command must be a
26
+ # program on PATH; wrap shell code in sh -c '…'. The processes under the command are found with
27
+ # ps (procps on Linux); without a ps that prints lstart, one note says the limit stops only the
28
+ # command itself. A process whose parent exits within a second of starting it may survive the
29
+ # stop; it does not hold the lock, but it may keep the caller's output pipe open. If
30
+ # bkit-test-awake.mjs itself is killed, the run frees the lock and exits with its status while
31
+ # the command may still be running.
32
+ # With LOCAL_STACK_LOCK_STATUS_FILE set, a 73, 75 or 124 also writes that file (a temp file beside
33
+ # it, then a rename) as three LF-ended lines: lock=<name>, outcome=refused, gave-up or held-too-long,
34
+ # and holder=<each holder's "who — checkout (pid N, since HH:MM:SS)" note, joined by "; "; for
35
+ # held-too-long, the stopped run's own note>. Read the
36
+ # outcome from this file and the exit code, never from the printed lines. run unsets the variable
37
+ # for its command, so a nested wrapper never writes the file.
18
38
  # 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.
39
+ # bash scripts/ci/bkit-machine-lock.sh slots # prints "slots=N workers=N" for this run, exit 0
40
+ # bash scripts/ci/bkit-machine-lock.sh queue [--lock <name>]
41
+ # prints one "<who> — <checkout>" line per waiting run and held place, in queue order, exit 0
42
+ # bash scripts/ci/bkit-machine-lock.sh jump [--lock <name>] <who> [<checkout>]
43
+ # moves that run to the front: exit 0 printing its line, 1 none matches, 3 several match
44
+ # (printing them); queue and jump default to the tests lock.
45
+ # TERM, INT and HUP that reach a run holding its own tests lock are passed on to the command (INT
46
+ # only when the run does not have the terminal, since Ctrl-C reaches the command directly); the
47
+ # lock stays held until the command ends, and the wrapper then returns the signal's exit status.
48
+ # Any other run defers them until its command ends.
21
49
  #
22
50
  # Named locks live in ${XDG_CACHE_HOME:-$HOME/.cache}/bkit/machine-lock/ with no
23
51
  # repository prefix. The unnamed stack lock keeps its local-stack-lock/ path and
@@ -27,18 +55,34 @@
27
55
  #
28
56
  # Take locks in this order: tests, other named locks, then the unnamed stack lock.
29
57
  # 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.
58
+ # The tests slots default, for a local run only, to 2 with 8 or more cores, else 1; any other
59
+ # runtime defaults to 1. A run is not local when BKIT_RUNTIME is set to anything but LOCAL; with
60
+ # BKIT_RUNTIME unset, when .bkit/.runtime-cursor exists in the main checkout or CLAUDE_CODE_REMOTE
61
+ # is set to anything but empty, false, FALSE, False, 0, no or NO. BKIT_TEST_SLOTS (whole number
62
+ # >= 1) overrides. Taking tests exports BKIT_TEST_WORKERS=max(1, floor(cores / slots) - 1) for the
63
+ # runner to use.
32
64
  # LOCAL_STACK_LOCK_WAIT_S caps the wait; otherwise it is 60s without a TTY, 3600s
33
65
  # 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.
66
+ # Waiting notes name every holder, that checkout's last run and the run's place in line.
67
+ # CI=true / CI=1 is a no-op.
68
+ # Waiters are served in the order they started waiting: each keeps a ticket in a <name>.queue/
69
+ # folder beside its lock file, flock-held while it waits. The ticket's first line is
70
+ # "<who> — <checkout>" and its second line slots=N, the slots the waiter asks for. A waiter may take
71
+ # slot k only while no live ticket ahead of it asks for k or more slots, so equal asks keep arrival
72
+ # order and a 1-slot waiter ahead never blocks slot 2; a ticket with no slots= line asks for every
73
+ # slot. A ticket of a dead waiter is skipped and removed. A waiter that gives up leaves its
74
+ # ticket as <ticket>.held for 120s, so the same run asking again keeps its place in line.
75
+ # A <ms>.jump marker in the queue (written by jump) moves the waiter whose line it names to
76
+ # the front, newest marker first; the holder keeps the lock. The waiter's own markers go when it takes the lock.
35
77
  # 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.
78
+ # Requires Bash 3.2+ and /usr/bin/perl; a run holding its own tests lock also needs node and
79
+ # bkit-test-awake.mjs beside this script.
37
80
 
38
81
  _LOCAL_STACK_LOCK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
39
82
  _LOCAL_STACK_LOCK_ROOT="$(git -C "$_LOCAL_STACK_LOCK_DIR" rev-parse --show-toplevel 2>/dev/null || echo "$_LOCAL_STACK_LOCK_DIR")"
40
83
  LOCAL_STACK_LOCK_PID="${LOCAL_STACK_LOCK_PID:-}"
41
84
  _LOCAL_STACK_LOCK_EXIT=73
85
+ _LOCAL_STACK_LOCK_HOLDER=""
42
86
 
43
87
  # The stack's name: BKIT_LOCAL_STACK, else the main checkout's folder name, the same from every
44
88
  # worktree. Characters outside A-Z a-z 0-9 . _ - become _.
@@ -82,23 +126,9 @@ local_stack_lock_holder() {
82
126
  return 0
83
127
  }
84
128
 
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
129
+ _local_stack_lock_cores() {
130
+ local _lsl_probe
131
+ _lsl_cores=""
102
132
  for _lsl_probe in getconf nproc sysctl; do
103
133
  case "$_lsl_probe" in
104
134
  getconf) _lsl_cores="$(getconf _NPROCESSORS_ONLN 2>/dev/null)" || continue ;;
@@ -109,6 +139,46 @@ _local_stack_lock_workers() {
109
139
  break
110
140
  done
111
141
  case "$_lsl_cores" in *[!0-9]*|""|0) _lsl_cores=1 ;; esac
142
+ }
143
+
144
+ # Whether this run is local, read in the order bkit's runtime detection reads it: a set
145
+ # BKIT_RUNTIME decides alone; else the Cursor marker in the main checkout means not local; else
146
+ # CLAUDE_CODE_REMOTE set to anything but an empty or false value means not local.
147
+ _local_stack_lock_local() {
148
+ local _lsl_common
149
+ if [ -n "${BKIT_RUNTIME:-}" ]; then
150
+ if [ "$BKIT_RUNTIME" = LOCAL ]; then return 0; fi
151
+ return 1
152
+ fi
153
+ _lsl_common="$(git -C "$PWD" rev-parse --path-format=absolute --git-common-dir 2>/dev/null)" || _lsl_common=""
154
+ if [ -n "$_lsl_common" ] && [ -e "$(dirname "$_lsl_common")/.bkit/.runtime-cursor" ]; then
155
+ return 1
156
+ fi
157
+ case "${CLAUDE_CODE_REMOTE:-}" in
158
+ ""|false|FALSE|False|0|no|NO) return 0 ;;
159
+ esac
160
+ return 1
161
+ }
162
+
163
+ _local_stack_lock_slots() {
164
+ local _lsl_default=1
165
+ if [ "${BKIT_TEST_SLOTS+x}" = x ]; then
166
+ _lsl_slots="$BKIT_TEST_SLOTS"
167
+ case "$_lsl_slots" in
168
+ *[!0-9]*|"") _lsl_slots=0 ;;
169
+ *) _lsl_slots=$((10#$_lsl_slots)) ;;
170
+ esac
171
+ if [ "$_lsl_slots" -ge 1 ]; then return 0; fi
172
+ fi
173
+ if [ "$_lsl_cores" -ge 8 ] && _local_stack_lock_local; then _lsl_default=2; fi
174
+ if [ "${BKIT_TEST_SLOTS+x}" = x ] && [ "${_LOCAL_STACK_LOCK_SLOTS_NOTED:-}" != 1 ]; then
175
+ echo "[machine-lock] invalid BKIT_TEST_SLOTS; using $_lsl_default slot(s)" >&2
176
+ _LOCAL_STACK_LOCK_SLOTS_NOTED=1
177
+ fi
178
+ _lsl_slots="$_lsl_default"
179
+ }
180
+
181
+ _local_stack_lock_workers() {
112
182
  BKIT_TEST_WORKERS=$((_lsl_cores / _lsl_slots - 1))
113
183
  [ "$BKIT_TEST_WORKERS" -ge 1 ] || BKIT_TEST_WORKERS=1
114
184
  export BKIT_TEST_WORKERS
@@ -130,76 +200,21 @@ _local_stack_lock_vars() {
130
200
  fi
131
201
  }
132
202
 
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 '
203
+ # The perl helper every lock take starts in the background, and the queue and jump subcommands
204
+ # run on their own. It execs, so a background helper is the perl process itself and its parent is
205
+ # the caller it watches.
206
+ _local_stack_lock_helper() {
207
+ exec /usr/bin/perl -e '
192
208
  use strict;
193
209
  use Fcntl qw(:flock);
194
210
  use File::Glob qw(bsd_glob);
195
211
  use POSIX qw(strftime);
212
+ use Time::HiRes qw(clock_gettime CLOCK_MONOTONIC);
196
213
  my ($file, $owner, $who, $checkout, $fifo, $wait_s, $mode, $label, $slots, $name) = @ARGV;
197
214
  # The caller is the parent of this process. When it exits, this process goes to init (or a
198
215
  # subreaper) at once, while `kill 0` would still find it until whoever started it reaps it.
199
216
  my $parent = getppid();
200
217
  my $caller_alive = sub { getppid() == $parent };
201
- open(my $out, ">", $fifo) or exit 1;
202
- $out->autoflush(1);
203
218
  my $stem = $file; $stem =~ s/\.lock$//;
204
219
  my $history = "$stem.last";
205
220
  my $holder = sub {
@@ -228,11 +243,161 @@ _local_stack_lock() {
228
243
  }
229
244
  return @holders ? join("; ", @holders) : "another run";
230
245
  };
246
+ my $queue = "$stem.queue";
247
+ my ($ticket, $ticket_fh);
248
+ END { unlink $ticket if defined $ticket }
249
+ $SIG{TERM} = sub { exit 0 };
250
+ for my $sig (qw(INT HUP)) { $SIG{$sig} = sub { exit 0 } unless defined $SIG{$sig} && $SIG{$sig} eq "IGNORE" }
251
+ my $ordinal = sub {
252
+ my $n = shift;
253
+ my $suffix = ($n % 100 >= 11 && $n % 100 <= 13) ? "th" : (qw(th st nd rd th th th th th th))[$n % 10];
254
+ return "$n$suffix";
255
+ };
256
+ # Live tickets and held places sorted by arrival, except that an entry whose line a <ms>.jump
257
+ # marker names goes first (newest marker first); dead tickets (flock can be taken), held places
258
+ # older than 120s and markers naming no live ticket or held place are removed; every other name
259
+ # is left alone. Each entry is [seconds, microseconds, pid, ours, line, slots asked, held].
260
+ # Keeps the sorted entries in @order and returns (our place, live tickets, the most slots a
261
+ # live ticket ahead of ours asks for, 0 with none ahead). A ticket with no slots= line asks for
262
+ # every slot.
263
+ my $every = 1e9;
264
+ my @order;
265
+ my $first_line = sub {
266
+ my $path = shift;
267
+ open(my $fh, "<", $path) or return undef;
268
+ my $first = <$fh>; close $fh;
269
+ return undef unless defined $first;
270
+ chomp $first;
271
+ return $first;
272
+ };
273
+ my $scan = sub {
274
+ my (@live, @markers, %known);
275
+ @order = ();
276
+ opendir(my $dir, $queue) or return (0, 0, 0);
277
+ for my $entry (readdir $dir) {
278
+ if ($entry =~ /^(\d+)\.(\d{6})-(\d+)$/) {
279
+ my ($s, $us, $pid) = ($1, $2, $3);
280
+ if (defined $ticket && $entry eq (split m{/}, $ticket)[-1]) { push @live, [$s, $us, $pid, 1, $first_line->("$queue/$entry"), $slots, 0]; next }
281
+ if (open(my $t, "<", "$queue/$entry")) {
282
+ if (flock($t, LOCK_EX | LOCK_NB)) { unlink "$queue/$entry" } else {
283
+ my $first = <$t>;
284
+ my $second = <$t>;
285
+ if (defined $first) { chomp $first }
286
+ my $asks = defined $second && $second =~ /^slots=([1-9]\d*)$/ ? $1 : $every;
287
+ push @live, [$s, $us, $pid, 0, $first, $asks, 0];
288
+ }
289
+ close $t;
290
+ }
291
+ } elsif ($entry =~ /^(\d+)\.(\d{6})-(\d+)\.held$/) {
292
+ my ($s, $us, $pid) = ($1, $2, $3);
293
+ my $mtime = (stat "$queue/$entry")[9];
294
+ if (defined $mtime && time - $mtime > 120) { unlink "$queue/$entry" }
295
+ else {
296
+ my $first = $first_line->("$queue/$entry");
297
+ if (defined $first) { $known{$first} = 1; push @live, [$s, $us, $pid, 0, $first, 0, 1] }
298
+ }
299
+ } elsif ($entry =~ /^(\d+)\.jump$/) {
300
+ push @markers, [$1, $entry, $first_line->("$queue/$entry")];
301
+ }
302
+ }
303
+ closedir $dir;
304
+ $known{$_->[4]} = 1 for grep { defined $_->[4] } @live;
305
+ my %front;
306
+ for my $m (@markers) {
307
+ if (!defined $m->[2] || !$known{$m->[2]}) { unlink "$queue/$m->[1]"; next }
308
+ $front{$m->[2]} = $m->[0] if !defined $front{$m->[2]} || $m->[0] > $front{$m->[2]};
309
+ }
310
+ my $rank = sub { my $f = defined $_[0][4] ? $front{$_[0][4]} : undef; return $f };
311
+ @live = sort {
312
+ my ($fa, $fb) = ($rank->($a), $rank->($b));
313
+ (defined $fa ? 0 : 1) <=> (defined $fb ? 0 : 1)
314
+ || (defined $fa ? $fb <=> $fa : 0)
315
+ || $a->[0] <=> $b->[0] || $a->[1] <=> $b->[1] || $a->[2] <=> $b->[2]
316
+ } @live;
317
+ @order = @live;
318
+ my ($place, $count, $ahead) = (0, 0, 0);
319
+ for my $e (@live) {
320
+ next if $e->[6];
321
+ $count++;
322
+ if ($e->[3]) { $place = $count }
323
+ elsif (!$place && $e->[5] > $ahead) { $ahead = $e->[5] }
324
+ }
325
+ return ($place, $count, $ahead);
326
+ };
327
+ # queue prints the line of each live ticket and held place in queue order. jump writes a
328
+ # <ms>.jump marker naming the one line of run $who (and checkout $checkout, when given): exit 0
329
+ # printing that line, 1 when none matches, 3 when several do (printing them).
330
+ if ($mode eq "queue" || $mode eq "jump") {
331
+ $scan->();
332
+ my (@lines, %seen);
333
+ for my $e (@order) { push @lines, $e->[4] if defined $e->[4] && !$seen{$e->[4]}++ }
334
+ if ($mode eq "queue") { print "$_\n" for @lines; exit 0 }
335
+ my @matches = grep { index($_, "$who — ") == 0 && ($checkout eq "" || $_ eq "$who — $checkout") } @lines;
336
+ exit 1 unless @matches;
337
+ if (@matches > 1) { print "$_\n" for @matches; exit 3 }
338
+ my $temp = "$queue/.jump.$$.tmp";
339
+ my $marker = "$queue/" . int(Time::HiRes::time() * 1000) . ".jump";
340
+ my $m;
341
+ unless (open($m, ">", $temp) && print($m "$matches[0]\n") && close($m) && rename($temp, $marker)) {
342
+ my $why = $!;
343
+ unlink $temp;
344
+ print STDERR "[machine-lock] ❌ cannot write a jump marker in $queue: $why\n";
345
+ exit 73;
346
+ }
347
+ print "$matches[0]\n";
348
+ exit 0;
349
+ }
350
+ open(my $out, ">", $fifo) or exit 1;
351
+ $out->autoflush(1);
352
+ if ($mode ne "try") {
353
+ unless (mkdir($queue) || -d $queue) { print $out "error cannot create $queue: $!\n"; exit 1 }
354
+ my $line = "$who — $checkout";
355
+ # A held place of this run, left by an earlier give-up under 120s ago, keeps its time.
356
+ my ($time, $held_name);
357
+ if (opendir(my $dir, $queue)) {
358
+ for my $entry (sort readdir $dir) {
359
+ next unless $entry =~ /^(\d+\.\d{6})-\d+\.held$/;
360
+ my $mtime = (stat "$queue/$entry")[9];
361
+ next unless defined $mtime && time - $mtime <= 120;
362
+ open(my $h, "<", "$queue/$entry") or next;
363
+ my $first = <$h>; close $h;
364
+ next unless defined $first;
365
+ chomp $first;
366
+ next unless $first eq $line;
367
+ ($time, $held_name) = ($1, $entry);
368
+ last;
369
+ }
370
+ closedir $dir;
371
+ }
372
+ $time = sprintf("%.6f", clock_gettime(CLOCK_MONOTONIC)) unless defined $time;
373
+ my $temp = "$queue/.$$.tmp";
374
+ open($ticket_fh, ">", $temp) or do { print $out "error cannot write a ticket in $queue: $!\n"; exit 1 };
375
+ flock($ticket_fh, LOCK_EX);
376
+ $ticket_fh->autoflush(1);
377
+ # The second line is the slots this run asks for; readers of the first line ignore it.
378
+ print $ticket_fh "$line\nslots=$slots\n";
379
+ my $name_of_ticket = "$time-$$";
380
+ unless (rename($temp, "$queue/$name_of_ticket")) {
381
+ my $why = $!;
382
+ unlink $temp;
383
+ print $out "error cannot write a ticket in $queue: $why\n";
384
+ exit 1;
385
+ }
386
+ $ticket = "$queue/$name_of_ticket";
387
+ unlink "$queue/$held_name" if defined $held_name;
388
+ }
231
389
  my ($lock, $held_file);
232
390
  my $start = time;
233
391
  my $next_note = 0;
234
392
  while (1) {
235
- for my $slot (1 .. $slots) {
393
+ my ($place, $waiting, $ahead) = $scan->();
394
+ if ($mode eq "try") {
395
+ if ($waiting) { print $out "busy " . $holder->() . "; $waiting waiting in line\n"; exit 0 }
396
+ }
397
+ # A waiter may take slot k only while no live ticket ahead of it asks for k or more slots,
398
+ # so a 1-slot waiter ahead never blocks slot 2 and equal asks keep arrival order.
399
+ my $first_slot = $mode eq "try" ? 1 : $ahead + 1;
400
+ for my $slot ($first_slot .. $slots) {
236
401
  my $candidate = $slot == 1 ? $file : "$stem.$slot.lock";
237
402
  open(my $next, ">>", $candidate) or do { print $out "error cannot open $candidate: $!\n"; exit 1 };
238
403
  if (flock($next, LOCK_EX | LOCK_NB)) { $lock = $next; $held_file = $candidate; last }
@@ -241,15 +406,33 @@ _local_stack_lock() {
241
406
  last if defined $lock;
242
407
  exit 0 unless $caller_alive->();
243
408
  if ($mode eq "try") { print $out "busy " . $holder->() . "\n"; exit 0 }
244
- if (time - $start >= $wait_s) { print $out "timeout " . $holder->() . "\n"; exit 0 }
409
+ if (time - $start >= $wait_s) {
410
+ # Keep the place for 120s: the same run asking again takes it back.
411
+ my $kept = "$ticket.held";
412
+ utime(time, time, $ticket);
413
+ if (rename($ticket, $kept)) { $ticket = undef }
414
+ print $out "timeout " . $holder->() . "\n";
415
+ exit 0;
416
+ }
245
417
  if (time >= $next_note) {
246
418
  my $m = int((time - $start) / 60);
247
419
  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";
420
+ my $in_line = $place ? ", " . $ordinal->($place) . " in line" : "";
421
+ print STDERR "[machine-lock] ⏳ $who is waiting for $label$so_far (up to ${wait_s}s)$in_line: in use by " . $holder->() . "\n";
249
422
  $next_note = time + 60;
250
423
  }
251
424
  select(undef, undef, undef, 0.1);
252
425
  }
426
+ if (defined $ticket) { unlink $ticket; $ticket = undef }
427
+ if ($mode ne "try" && opendir(my $mdir, $queue)) {
428
+ my $mine = "$who — $checkout";
429
+ for my $entry (readdir $mdir) {
430
+ next unless $entry =~ /^\d+\.jump$/;
431
+ my $first = $first_line->("$queue/$entry");
432
+ unlink "$queue/$entry" if defined $first && $first eq $mine;
433
+ }
434
+ closedir $mdir;
435
+ }
253
436
  my $stopping = 0;
254
437
  $SIG{TERM} = $SIG{INT} = $SIG{HUP} = sub { $stopping = 1 };
255
438
  my $held_since = time;
@@ -281,20 +464,86 @@ _local_stack_lock() {
281
464
  } else { print STDERR "[machine-lock] could not lock $history for held-time history: $!\n" }
282
465
  }
283
466
  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 &
467
+ ' "$@"
468
+ }
469
+
470
+ _local_stack_lock() {
471
+ local _lsl_mode="$1" _lsl_who="$2" _lsl_name="${3:-}"
472
+ local _lsl_pid_var _lsl_owner_var _lsl_name_var _lsl_owner _lsl_existing
473
+ local _lsl_file _lsl_label _lsl_fifo _lsl_pid _lsl_reply _lsl_checkout
474
+ local _lsl_slots=1 _lsl_cores=1 _lsl_wait _lsl_var _lsl_held_name _lsl_held_name_var
475
+ _LOCAL_STACK_LOCK_EXIT=73
476
+ _LOCAL_STACK_LOCK_HOLDER=""
477
+ _local_stack_lock_vars "$_lsl_name"
478
+ _lsl_owner="${!_lsl_owner_var:-}"
479
+ _lsl_existing="${!_lsl_pid_var:-}"
480
+ if [ "${CI:-}" = "true" ] || [ "${CI:-}" = "1" ]; then return 0; fi
481
+ if [ "$_lsl_name" = tests ]; then
482
+ _local_stack_lock_cores
483
+ _local_stack_lock_slots
484
+ _local_stack_lock_workers
485
+ fi
486
+ if [ -n "$_lsl_owner" ] && kill -0 "$_lsl_owner" 2>/dev/null; then return 0; fi
487
+ if [ -n "$_lsl_existing" ] && kill -0 "$_lsl_existing" 2>/dev/null; then return 0; fi
488
+ if [ -n "$_lsl_name" ]; then
489
+ for _lsl_var in ${!LOCAL_STACK_LOCK_OWNER*}; do
490
+ _lsl_owner="${!_lsl_var:-}"
491
+ [ -n "$_lsl_owner" ] && kill -0 "$_lsl_owner" 2>/dev/null || continue
492
+ if [ "$_lsl_var" = LOCAL_STACK_LOCK_OWNER ] || [ "$_lsl_name" = tests ]; then
493
+ _lsl_held_name_var="${_lsl_var/OWNER/NAME}"
494
+ _lsl_held_name="${!_lsl_held_name_var:-the unnamed stack lock}"
495
+ 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
496
+ return 1
497
+ fi
498
+ done
499
+ fi
500
+ if [ "${LOCAL_STACK_LOCK_WAIT_S+x}" = x ]; then
501
+ _lsl_wait="$LOCAL_STACK_LOCK_WAIT_S"
502
+ elif [ -t 0 ]; then
503
+ _lsl_wait=3600
504
+ else
505
+ _lsl_wait=60
506
+ fi
507
+
508
+ if ! _lsl_file="$(local_stack_lock_file "$_lsl_name")"; then
509
+ echo "[machine-lock] ❌ cannot name the local stack: run inside a git checkout, or set BKIT_LOCAL_STACK" >&2
510
+ return 1
511
+ fi
512
+ _lsl_label="the local stack $(basename "$_lsl_file" .lock)"
513
+ _lsl_checkout="$_LOCAL_STACK_LOCK_ROOT"
514
+ if [ -n "$_lsl_name" ]; then
515
+ _lsl_label="$_lsl_name"
516
+ _lsl_checkout="$(git -C "$PWD" rev-parse --show-toplevel 2>/dev/null || printf '%s' "$PWD")"
517
+ fi
518
+ if [ ! -x /usr/bin/perl ]; then
519
+ echo "[machine-lock] ❌ could not take the lock for $_lsl_label: /usr/bin/perl not found" >&2
520
+ return 1
521
+ fi
522
+ if ! mkdir -p "$(dirname "$_lsl_file")"; then
523
+ echo "[machine-lock] ❌ could not take the lock for $_lsl_label: cannot create $(dirname "$_lsl_file")" >&2
524
+ return 1
525
+ fi
526
+ _lsl_fifo="$(mktemp -u "${TMPDIR:-/tmp}/local-stack-lock.XXXXXX")"
527
+ mkfifo "$_lsl_fifo" || return 1
528
+
529
+ # The holder answers on the fifo once: ok, busy <holder>, timeout <holder> or error <why>.
530
+ _local_stack_lock_helper \
531
+ "$_lsl_file" "$$" "$_lsl_who" "$_lsl_checkout" "$_lsl_fifo" "$_lsl_wait" "$_lsl_mode" "$_lsl_label" "$_lsl_slots" "$_lsl_name" </dev/null >/dev/null &
285
532
  _lsl_pid=$!
286
533
  # The fifo is opened read-write, so the read never blocks on a holder that died before it
287
534
  # answered (a failed fork under load, a killed perl): the loop stops once it is gone.
288
535
  _lsl_reply="$(
289
536
  exec 3<>"$_lsl_fifo"
537
+ _lsl_partial=""
290
538
  while :; do
291
539
  if IFS= read -r -t 1 _lsl_line <&3; then
292
- printf '%s' "$_lsl_line"
540
+ printf '%s' "$_lsl_partial$_lsl_line"
293
541
  break
294
542
  fi
543
+ _lsl_partial="$_lsl_partial$_lsl_line"
295
544
  if ! kill -0 "$_lsl_pid" 2>/dev/null; then
296
545
  # 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
546
+ if IFS= read -r -t 1 _lsl_line <&3; then printf '%s' "$_lsl_partial$_lsl_line"; fi
298
547
  break
299
548
  fi
300
549
  done
@@ -312,10 +561,12 @@ _local_stack_lock() {
312
561
  ;;
313
562
  busy\ *)
314
563
  _LOCAL_STACK_LOCK_EXIT=75
564
+ _LOCAL_STACK_LOCK_HOLDER="${_lsl_reply#busy }"
315
565
  echo "[machine-lock] $_lsl_label is in use by ${_lsl_reply#busy }" >&2
316
566
  ;;
317
567
  timeout\ *)
318
568
  _LOCAL_STACK_LOCK_EXIT=75
569
+ _LOCAL_STACK_LOCK_HOLDER="${_lsl_reply#timeout }"
319
570
  echo "[machine-lock] ❌ $_lsl_who gave up after ${_lsl_wait}s waiting for $_lsl_label, in use by ${_lsl_reply#timeout }" >&2
320
571
  echo "[machine-lock] Let that run finish, or stop it. LOCAL_STACK_LOCK_WAIT_S sets how long to wait." >&2
321
572
  ;;
@@ -326,6 +577,7 @@ _local_stack_lock() {
326
577
  echo "[machine-lock] ❌ could not take the lock for $_lsl_label: ${_lsl_reply#error }" >&2
327
578
  ;;
328
579
  esac
580
+ kill "$_lsl_pid" 2>/dev/null || true
329
581
  wait "$_lsl_pid" 2>/dev/null || true
330
582
  return 1
331
583
  }
@@ -349,12 +601,51 @@ release_local_stack_lock() {
349
601
  if [ "${BASH_SOURCE[0]}" = "$0" ]; then
350
602
  _lsl_run_usage() {
351
603
  echo 'usage: bash scripts/ci/bkit-machine-lock.sh run ["<who>"] [--lock <name>] -- <command> [args…]' >&2
604
+ echo ' bash scripts/ci/bkit-machine-lock.sh slots' >&2
605
+ echo ' bash scripts/ci/bkit-machine-lock.sh queue [--lock <name>]' >&2
606
+ echo ' bash scripts/ci/bkit-machine-lock.sh jump [--lock <name>] <who> [<checkout>]' >&2
352
607
  exit 2
353
608
  }
354
- [ "${1:-}" = run ] || _lsl_run_usage
609
+ case "${1:-}" in
610
+ run) ;;
611
+ queue|jump)
612
+ _lsl_sub="$1"
613
+ _lsl_sub_name=tests
614
+ shift
615
+ if [ "${1:-}" = --lock ]; then
616
+ [ -n "${2:-}" ] || _lsl_run_usage
617
+ _lsl_sub_name="$2"
618
+ shift 2
619
+ fi
620
+ if [ "$_lsl_sub" = queue ]; then
621
+ [ "$#" -eq 0 ] || _lsl_run_usage
622
+ else
623
+ [ -n "${1:-}" ] && [ "$#" -le 2 ] || _lsl_run_usage
624
+ fi
625
+ if [ ! -x /usr/bin/perl ]; then
626
+ echo "[machine-lock] ❌ cannot read the $_lsl_sub_name queue: /usr/bin/perl not found" >&2
627
+ exit 73
628
+ fi
629
+ _lsl_sub_file="$(local_stack_lock_file "$_lsl_sub_name")" || exit 73
630
+ _local_stack_lock_helper \
631
+ "$_lsl_sub_file" "" "${1:-}" "${2:-}" "" 0 "$_lsl_sub" "$_lsl_sub_name" 1 "$_lsl_sub_name" </dev/null
632
+ ;;
633
+ slots)
634
+ [ "$#" -eq 1 ] || _lsl_run_usage
635
+ _local_stack_lock_cores
636
+ _local_stack_lock_slots
637
+ _local_stack_lock_workers
638
+ printf 'slots=%s workers=%s\n' "$_lsl_slots" "$BKIT_TEST_WORKERS"
639
+ exit 0
640
+ ;;
641
+ *) _lsl_run_usage ;;
642
+ esac
355
643
  shift
356
644
  _lsl_run_who="${LOCAL_STACK_LOCK_WHO:-${npm_lifecycle_event:-run}}"
357
645
  _lsl_run_name=""
646
+ _lsl_run_status_file="${LOCAL_STACK_LOCK_STATUS_FILE:-}"
647
+ # The file belongs to this wrapper only: a nested wrapper for another lock never writes it.
648
+ unset LOCAL_STACK_LOCK_STATUS_FILE
358
649
  case "${1:-}" in
359
650
  --lock|--) ;;
360
651
  "") _lsl_run_usage ;;
@@ -368,19 +659,136 @@ if [ "${BASH_SOURCE[0]}" = "$0" ]; then
368
659
  [ "${1:-}" = -- ] || _lsl_run_usage
369
660
  shift
370
661
  [ "$#" -gt 0 ] || _lsl_run_usage
371
- take_local_stack_lock "$_lsl_run_who" "$_lsl_run_name" || exit "$_LOCAL_STACK_LOCK_EXIT"
662
+ # Three LF-ended lines, written beside the file and renamed into place, so a reader never
663
+ # sees half a file.
664
+ _lsl_run_write_status() {
665
+ local _lsl_holds="$_LOCAL_STACK_LOCK_HOLDER" _lsl_tmp
666
+ [ -n "$_lsl_run_status_file" ] || return 0
667
+ [ -n "$_lsl_holds" ] || _lsl_holds="$(local_stack_lock_holder "$_lsl_run_name" 2>/dev/null)"
668
+ _lsl_holds="${_lsl_holds//$'\n'/; }"
669
+ _lsl_tmp="$_lsl_run_status_file.$$.tmp"
670
+ if { printf 'lock=%s\noutcome=%s\nholder=%s\n' "$_lsl_run_name" "$1" "$_lsl_holds" >"$_lsl_tmp"; } 2>/dev/null &&
671
+ mv -f "$_lsl_tmp" "$_lsl_run_status_file" 2>/dev/null; then
672
+ return 0
673
+ fi
674
+ rm -f "$_lsl_tmp"
675
+ echo "[machine-lock] could not write the status file $_lsl_run_status_file" >&2
676
+ }
677
+ if ! take_local_stack_lock "$_lsl_run_who" "$_lsl_run_name"; then
678
+ case "$_LOCAL_STACK_LOCK_EXIT" in
679
+ 75) _lsl_run_write_status gave-up ;;
680
+ 73) _lsl_run_write_status refused ;;
681
+ esac
682
+ exit "$_LOCAL_STACK_LOCK_EXIT"
683
+ fi
684
+ _lsl_run_started=$SECONDS
372
685
  _lsl_run_signal_status=0
686
+ _lsl_run_cmd_pid=""
687
+ _lsl_run_stopped=""
688
+ # With a background command (a run holding its own tests lock), TERM, INT and HUP are passed on to it;
689
+ # INT is not when this run has the terminal, since Ctrl-C reaches the command directly. A
690
+ # signal once the hold-limit stop has started is not passed on: the stop is under way.
373
691
  _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
692
+ _lsl_run_signal_status="$2"
693
+ if [ -z "$_lsl_run_cmd_pid" ]; then
694
+ echo "[machine-lock] cancellation requested; waiting for $_lsl_run_who to finish before releasing its lock" >&2
695
+ return 0
696
+ fi
697
+ [ -z "$_lsl_run_stopped" ] || [ ! -e "$_lsl_run_stopped" ] || return 0
698
+ if [ "$1" = INT ] && /usr/bin/perl -e 'use POSIX (); open(my $t, "<", "/dev/tty") or exit 1; exit(POSIX::tcgetpgrp(fileno $t) == getpgrp() ? 0 : 1)' 2>/dev/null; then
699
+ return 0
700
+ fi
701
+ kill -"$1" "$_lsl_run_cmd_pid" 2>/dev/null || true
702
+ echo "[machine-lock] passed $1 on to $_lsl_run_who; waiting for it to finish before releasing its lock" >&2
703
+ }
704
+ _local_stack_lock_vars "$_lsl_run_name"
705
+ if [ "$_lsl_run_name" != tests ] || [ "${!_lsl_owner_var:-}" != "$$" ]; then
706
+ # Another lock, or no lock taken here (CI, or a live parent's lock reused): no hold limit.
707
+ # Bash runs these traps after its foreground command ends.
708
+ trap '_lsl_run_cancel TERM 143' TERM
709
+ trap '_lsl_run_cancel INT 130' INT
710
+ trap '_lsl_run_cancel HUP 129' HUP
711
+ "$@"
712
+ _lsl_run_status=$?
713
+ release_local_stack_lock "$_lsl_run_name"
714
+ [ "$_lsl_run_signal_status" -eq 0 ] || _lsl_run_status="$_lsl_run_signal_status"
715
+ exit "$_lsl_run_status"
716
+ fi
717
+ # A whole number >= min, else the default with one note.
718
+ _lsl_run_seconds() {
719
+ _lsl_run_value="$3"
720
+ case "${!1:-}" in
721
+ "") return 0 ;;
722
+ *[!0-9]*) ;;
723
+ *) if [ "$((10#${!1}))" -ge "$2" ]; then _lsl_run_value="$((10#${!1}))"; return 0; fi ;;
724
+ esac
725
+ echo "[machine-lock] invalid $1 \"${!1}\"; using $3" >&2
376
726
  }
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=$?
727
+ _lsl_run_seconds LOCAL_STACK_LOCK_HOLD_S 1 3600
728
+ _lsl_run_limit="$_lsl_run_value"
729
+ _lsl_run_seconds LOCAL_STACK_LOCK_HOLD_GRACE_S 0 10
730
+ _lsl_run_grace="$_lsl_run_value"
731
+ # The command runs under bkit-test-awake.mjs beside this script. At the limit it stops the
732
+ # command and every process started under it (TERM, then KILL after the grace period) and
733
+ # exits 124; see its --hold-s.
734
+ _lsl_run_awake="$_LOCAL_STACK_LOCK_DIR/bkit-test-awake.mjs"
735
+ # A copy without --hold-s would take --hold-s for the command's name.
736
+ if ! command -v node >/dev/null 2>&1 || [ ! -f "$_lsl_run_awake" ] || ! grep -q -- '--hold-s' "$_lsl_run_awake"; then
737
+ release_local_stack_lock "$_lsl_run_name"
738
+ echo "[machine-lock] ❌ cannot run $_lsl_run_who under the tests-lock hold limit: it needs node on PATH and $_lsl_run_awake as the current .bkit/templates/scripts/ci/bkit-test-awake.mjs, with --hold-s" >&2
739
+ _LOCAL_STACK_LOCK_HOLDER="$_lsl_run_who"
740
+ _lsl_run_write_status refused
741
+ exit 73
742
+ fi
743
+ # bkit-test-awake.mjs creates this file as it starts the stop at the limit; only then is 124 a
744
+ # hold-limit stop.
745
+ _lsl_run_stop_dir="$(mktemp -d "${TMPDIR:-/tmp}/local-stack-lock-run.XXXXXX")" || {
746
+ release_local_stack_lock "$_lsl_run_name"
747
+ echo "[machine-lock] ❌ cannot run $_lsl_run_who under the tests-lock hold limit: no temporary folder in ${TMPDIR:-/tmp}" >&2
748
+ _LOCAL_STACK_LOCK_HOLDER="$_lsl_run_who"
749
+ _lsl_run_write_status refused
750
+ exit 73
751
+ }
752
+ _lsl_run_stopped="$_lsl_run_stop_dir/stopped"
753
+ trap 'rm -rf "$_lsl_run_stop_dir"' EXIT
754
+ # Signals ignored on entry stay ignored for the command; bkit-test-awake.mjs would otherwise
755
+ # start it with every signal at its default.
756
+ _lsl_run_ignored="$(/usr/bin/perl -e 'print join(" ", grep { ($SIG{$_} || "") eq "IGNORE" } qw(INT QUIT))')"
757
+ # Descriptors above 2 the caller left open reach the command too (a caller may hold a pipe
758
+ # there to learn when the command ends); bkit-test-awake.mjs passes on only those it is told.
759
+ _lsl_run_fds="$(/usr/bin/perl -e 'print join(",", grep { open(my $f, "+<&=", $_) || open($f, "<&=", $_) || open($f, ">&=", $_) } 3..63)')"
760
+ trap '_lsl_run_cancel TERM 143' TERM
761
+ trap '_lsl_run_cancel INT 130' INT
762
+ trap '_lsl_run_cancel HUP 129' HUP
763
+ # The command stays in the caller's process group and keeps the caller's stdin, so it reads the
764
+ # terminal and gets Ctrl-C as a foreground command would. Bash runs a trap only while it waits,
765
+ # so the command runs in the background and a signal to this run is passed on at once.
766
+ node "$_lsl_run_awake" --hold-s "$_lsl_run_limit" --grace-s "$_lsl_run_grace" --stopped-file "$_lsl_run_stopped" --pass-fds "$_lsl_run_fds" -- /usr/bin/perl -e '
767
+ my %ignore = map { $_ => 1 } split " ", shift @ARGV;
768
+ $SIG{$_} = "IGNORE" for grep { $ignore{$_} } qw(INT QUIT);
769
+ exec { $ARGV[0] } @ARGV;
770
+ print STDERR "[machine-lock] cannot run $ARGV[0]: $! (a shell function or builtin cannot be run; wrap it in sh -c)\n";
771
+ exit($!{ENOENT} ? 127 : 126);
772
+ ' "$_lsl_run_ignored" "$@" <&0 &
773
+ _lsl_run_cmd_pid=$!
774
+ while :; do
775
+ # Quiet: bash would otherwise print a "Killed" job notice for a stopped command.
776
+ wait "$_lsl_run_cmd_pid" 2>/dev/null
777
+ _lsl_run_status=$?
778
+ # A trapped signal ends wait early with a status above 128 while the command still runs.
779
+ if [ "$_lsl_run_status" -gt 128 ] && kill -0 "$_lsl_run_cmd_pid" 2>/dev/null; then continue; fi
780
+ break
781
+ done
782
+ # 124 is a hold-limit stop only when bkit-test-awake.mjs says so; otherwise it is the command's own.
783
+ _lsl_run_held=$((SECONDS - _lsl_run_started))
784
+ if [ "$_lsl_run_status" -eq 124 ] && [ -e "$_lsl_run_stopped" ]; then
785
+ _lsl_run_note="$(local_stack_lock_holder "$_lsl_run_name" | grep -F "(pid $$, " | head -n 1)"
786
+ release_local_stack_lock "$_lsl_run_name"
787
+ echo "[machine-lock] ❌ ${_lsl_run_note:-$_lsl_run_who} reached the LOCAL_STACK_LOCK_HOLD_S limit of ${_lsl_run_limit}s on the tests lock (held ${_lsl_run_held}s); stopped the command and freed the lock" >&2
788
+ _LOCAL_STACK_LOCK_HOLDER="${_lsl_run_note:-$_lsl_run_who}"
789
+ _lsl_run_write_status held-too-long
790
+ exit 124
791
+ fi
384
792
  release_local_stack_lock "$_lsl_run_name"
385
793
  [ "$_lsl_run_signal_status" -eq 0 ] || _lsl_run_status="$_lsl_run_signal_status"
386
794
  exit "$_lsl_run_status"