@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
@@ -2,15 +2,233 @@
2
2
  // Example. Copy into scripts/ci/ and own it. bkit install does not write this file.
3
3
  // Usage: node scripts/ci/bkit-test-awake.mjs command [args...]
4
4
  // Chains: node scripts/ci/bkit-test-awake.mjs --shell 'first && second'
5
+ // Hold limit: node scripts/ci/bkit-test-awake.mjs --hold-s N [--grace-s G] [--stopped-file P] [--pass-fds 3,4] -- command [args...]
5
6
 
6
- import { spawn } from "node:child_process";
7
- import spawnCommand from "cross-spawn";
7
+ import { spawn, spawnSync } from "node:child_process";
8
8
  import { once } from "node:events";
9
+ import { existsSync, statSync, writeFile } from "node:fs";
9
10
  import { constants } from "node:os";
11
+ import { join } from "node:path";
12
+ import { setTimeout as delay } from "node:timers/promises";
10
13
  import { pathToFileURL } from "node:url";
11
14
 
12
- /** Run a command with a macOS sleep assertion owned by this process. */
13
- export async function runAwake(command, args, platform = process.platform) {
15
+ /** The first executable `ps` on PATH, else /bin/ps. */
16
+ function psBinary() {
17
+ for (const dir of (process.env.PATH ?? "").split(":")) {
18
+ const candidate = join(dir || ".", "ps");
19
+ const stat = statSync(candidate, { throwIfNoEntry: false });
20
+ if (stat?.isFile() && (stat.mode & 0o111) !== 0) return candidate;
21
+ }
22
+ return "/bin/ps";
23
+ }
24
+
25
+ function processTable() {
26
+ const result = spawnSync(
27
+ psBinary(),
28
+ ["-A", "-o", "pid=", "-o", "ppid=", "-o", "stat=", "-o", "lstart="],
29
+ {
30
+ encoding: "utf8",
31
+ timeout: 1000,
32
+ env: { ...process.env, LC_ALL: "C" },
33
+ },
34
+ );
35
+ if (result.error || result.status !== 0) return null;
36
+ const processes = new Map();
37
+ for (const row of result.stdout.split("\n")) {
38
+ const match = row.trim().match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/);
39
+ if (!match || match[3].startsWith("Z")) continue;
40
+ processes.set(Number(match[1]), { parent: Number(match[2]), started: match[4] });
41
+ }
42
+ return processes;
43
+ }
44
+
45
+ function collectDescendants(processes, tracked) {
46
+ let added;
47
+ do {
48
+ added = false;
49
+ for (const [pid, entry] of processes) {
50
+ if (!tracked.has(pid) && tracked.has(entry.parent) && pid !== process.pid) {
51
+ tracked.set(pid, entry);
52
+ added = true;
53
+ }
54
+ }
55
+ } while (added);
56
+ }
57
+
58
+ /** Whether `pid` still runs; a signal it cannot receive from us counts as running. */
59
+ function alive(pid) {
60
+ try {
61
+ process.kill(pid, 0);
62
+ return true;
63
+ } catch (error) {
64
+ return error.code !== "ESRCH";
65
+ }
66
+ }
67
+
68
+ /** Signal `pid`; a process that already exited is not an error. */
69
+ function signalPid(pid, signal) {
70
+ try {
71
+ process.kill(pid, signal);
72
+ } catch (error) {
73
+ if (error.code !== "ESRCH")
74
+ console.error(`bkit-test-awake: could not signal command ${pid}: ${error.message}`);
75
+ }
76
+ }
77
+
78
+ /**
79
+ * True when this process is in its terminal's foreground group: a Ctrl-C there already reached
80
+ * the command, so passing INT on would deliver it twice.
81
+ */
82
+ function inTerminalForeground() {
83
+ const result = spawnSync(psBinary(), ["-o", "tpgid=", "-o", "pgid=", "-p", String(process.pid)], {
84
+ encoding: "utf8",
85
+ timeout: 1000,
86
+ });
87
+ const [tpgid, pgid] = (result.stdout ?? "").trim().split(/\s+/).map(Number);
88
+ return result.status === 0 && tpgid > 0 && tpgid === pgid;
89
+ }
90
+
91
+ /** Send `signal` through a shell chain and wait for its descendants; a null signal only waits. */
92
+ async function cancelShell(child, signal) {
93
+ let processes = processTable();
94
+ const root = processes?.get(child.pid);
95
+ if (!root) {
96
+ if (!processes)
97
+ console.error("bkit-test-awake: could not inspect shell commands; waiting for completion");
98
+ if (signal) child.kill(signal);
99
+ return;
100
+ }
101
+ const tracked = new Map([[child.pid, root]]);
102
+ collectDescendants(processes, tracked);
103
+ const signalled = new Set();
104
+ const signalProcess = (pid, entry) => {
105
+ const identity = `${pid}:${entry.started}`;
106
+ if (signalled.has(identity)) return;
107
+ signalled.add(identity);
108
+ if (signal) signalPid(pid, signal);
109
+ };
110
+ // Live command owners retain responsibility for their descendants and locks.
111
+ for (const [pid, entry] of tracked) {
112
+ if (pid === child.pid || entry.parent === child.pid) signalProcess(pid, entry);
113
+ }
114
+ let inspectionReported = false;
115
+ while (tracked.size > 0) {
116
+ await delay(50);
117
+ processes = processTable();
118
+ if (!processes) {
119
+ if (!inspectionReported)
120
+ console.error(
121
+ "bkit-test-awake: waiting to inspect cancelled commands before releasing the assertion",
122
+ );
123
+ inspectionReported = true;
124
+ continue;
125
+ }
126
+ for (const [pid, entry] of tracked) {
127
+ const current = processes.get(pid);
128
+ if (current?.started !== entry.started) tracked.delete(pid);
129
+ else tracked.set(pid, current);
130
+ }
131
+ collectDescendants(processes, tracked);
132
+ // An exited intermediary can leave a worker behind; cancel that orphan root.
133
+ for (const [pid, entry] of tracked) {
134
+ if (entry.parent === child.pid || !tracked.has(entry.parent)) signalProcess(pid, entry);
135
+ }
136
+ }
137
+ }
138
+
139
+ /**
140
+ * Stop `child` and every process started under it once `holdS` seconds pass: one TERM to each,
141
+ * then KILL to those left after `graceS`. The tree is recorded every second, so a process whose
142
+ * parent exited is still stopped; each is recorded with its start time, so a reused pid is never
143
+ * signalled. Without a ps that lists start times, only the command itself can be stopped.
144
+ * `stoppedFile`, when set, is created as the stop starts. Resolves true when it stopped the
145
+ * command, false when the command finished first.
146
+ */
147
+ async function holdLimit(child, closing, { holdS, graceS, stoppedFile }, state) {
148
+ let closed = false;
149
+ closing.then(() => (closed = true));
150
+ const pause = (ms) => Promise.race([delay(ms, undefined, { ref: false }), closing]);
151
+ const first = processTable();
152
+ const tree = first !== null;
153
+ if (!tree)
154
+ console.error(
155
+ "bkit-test-awake: ps with lstart is not available (procps on Linux), so the --hold-s limit can stop only the command itself, not the processes started under it",
156
+ );
157
+ // The command's start time is null when it was already gone from the first table.
158
+ const tracked = new Map([[child.pid, first?.get(child.pid) ?? null]]);
159
+ const refresh = () => {
160
+ if (!tree) {
161
+ for (const pid of tracked.keys()) if (!alive(pid)) tracked.delete(pid);
162
+ return;
163
+ }
164
+ const processes = processTable();
165
+ if (!processes) return;
166
+ for (const [pid, entry] of tracked) {
167
+ const current = processes.get(pid);
168
+ if (!current || (entry && current.started !== entry.started)) tracked.delete(pid);
169
+ else tracked.set(pid, current);
170
+ }
171
+ collectDescendants(processes, tracked);
172
+ };
173
+ const end = Date.now() + holdS * 1000;
174
+ while (!closed && Date.now() < end) {
175
+ refresh();
176
+ await pause(Math.min(1000, Math.max(0, end - Date.now())));
177
+ }
178
+ if (closed) return false;
179
+ refresh();
180
+ if (!tracked.has(child.pid) || !alive(child.pid)) return false;
181
+ state.stopping = true;
182
+ // The stop goes ahead without the file; the caller then reads the 124 as the command's own.
183
+ if (stoppedFile)
184
+ writeFile(stoppedFile, "", (error) => {
185
+ if (error) console.error(`bkit-test-awake: could not write ${stoppedFile}: ${error.message}`);
186
+ });
187
+ // Each process gets one TERM, so a second one never cuts short its own shutdown.
188
+ const termed = new Set();
189
+ const term = () => {
190
+ for (const [pid, entry] of tracked) {
191
+ const identity = `${pid}:${entry?.started}`;
192
+ if (termed.has(identity)) continue;
193
+ termed.add(identity);
194
+ signalPid(pid, "SIGTERM");
195
+ }
196
+ };
197
+ term();
198
+ const killAt = Date.now() + graceS * 1000;
199
+ while (tracked.size > 0 && Date.now() < killAt) {
200
+ await delay(100);
201
+ refresh();
202
+ term();
203
+ }
204
+ for (let round = 0; round < 20 && tracked.size > 0; round++) {
205
+ for (const pid of tracked.keys()) signalPid(pid, "SIGKILL");
206
+ await delay(100);
207
+ refresh();
208
+ }
209
+ return true;
210
+ }
211
+
212
+ /**
213
+ * Run a command with a macOS sleep assertion owned by this process. With `hold`, the command is
214
+ * stopped once `hold.holdS` seconds pass (see `holdLimit`) and the result is 124, and the
215
+ * descriptors in `hold.fds` are handed to the command too. `foreground` says whether this process
216
+ * is in its terminal's foreground group.
217
+ */
218
+ export async function runAwake(
219
+ command,
220
+ args,
221
+ platform = process.platform,
222
+ hold = null,
223
+ foreground = inTerminalForeground,
224
+ ) {
225
+ const shell = command === "--shell" && platform !== "win32";
226
+ if (command === "--shell") {
227
+ command = shell ? "/bin/sh" : process.env.ComSpec || "cmd.exe";
228
+ args = shell
229
+ ? ["-c", `trap 'exit 130' INT\ntrap 'exit 143' TERM\ntrap 'exit 129' HUP\n${args[0]}`]
230
+ : ["/d", "/s", "/c", args[0]];
231
+ }
14
232
  let assertion;
15
233
  if (platform === "darwin") {
16
234
  assertion = spawn("/usr/bin/caffeinate", ["-is", "-w", String(process.pid)], {
@@ -25,24 +243,51 @@ export async function runAwake(command, args, platform = process.platform) {
25
243
  }
26
244
  }
27
245
 
28
- const child = spawnCommand(command, args, {
29
- stdio: "inherit",
30
- });
31
- const forward = (signal) => {
32
- if (!child.pid) return;
33
- try {
34
- child.kill(signal);
35
- } catch (error) {
36
- if (error.code !== "ESRCH") throw error;
37
- }
38
- };
39
- const handlers = ["SIGINT", "SIGTERM", "SIGHUP"].map((signal) => {
40
- const handler = () => forward(signal);
41
- process.on(signal, handler);
42
- return [signal, handler];
43
- });
246
+ // cross-spawn handles Windows command shims and argument escaping; elsewhere it is spawn.
247
+ const spawnCommand = platform === "win32" ? (await import("cross-spawn")).default : spawn;
248
+ // Descriptors above 2 reach the command only when listed in `hold.fds`, each at its own number.
249
+ const fds = hold?.fds ?? [];
250
+ const extra = Array.from({ length: Math.max(2, ...fds) - 2 }, (_, i) =>
251
+ fds.includes(i + 3) ? i + 3 : "ignore",
252
+ );
253
+ let handlers = [];
44
254
  try {
255
+ let child;
256
+ const state = { stopping: false };
257
+ let cleanup;
258
+ const forward = (signal) => {
259
+ if (!child?.pid || state.stopping) return;
260
+ // A Ctrl-C at the terminal already reached the command, so it is not sent again; a shell
261
+ // chain is still waited for.
262
+ const resend = !(signal === "SIGINT" && platform !== "win32" && foreground());
263
+ if (shell) {
264
+ cleanup ??= cancelShell(child, resend ? signal : null);
265
+ return;
266
+ }
267
+ if (!resend) return;
268
+ try {
269
+ child.kill(signal);
270
+ } catch (error) {
271
+ if (error.code !== "ESRCH") throw error;
272
+ }
273
+ };
274
+ // The handlers go in before the command starts: a signal without one ends this process and
275
+ // leaves the command running. A handler runs only once the command has started.
276
+ handlers = ["SIGINT", "SIGTERM", "SIGHUP"].map((signal) => {
277
+ const handler = () => forward(signal);
278
+ process.on(signal, handler);
279
+ return [signal, handler];
280
+ });
281
+ child = spawnCommand(command, args, {
282
+ stdio: ["inherit", "inherit", "inherit", ...extra],
283
+ });
284
+ const held =
285
+ hold && child.pid
286
+ ? holdLimit(child, new Promise((resolve) => child.on("close", resolve)), hold, state)
287
+ : Promise.resolve(false);
45
288
  const [code, signal] = await once(child, "close");
289
+ await cleanup;
290
+ if (await held) return 124;
46
291
  return code ?? 128 + (constants.signals[signal] ?? 1);
47
292
  } catch (error) {
48
293
  const reason = error.code === "ENOENT" ? "not found on PATH" : "could not run";
@@ -58,18 +303,59 @@ export async function runAwake(command, args, platform = process.platform) {
58
303
  }
59
304
  }
60
305
 
306
+ /**
307
+ * `--hold-s N [--grace-s G] [--stopped-file P] [--pass-fds A,B] [--]` off the front of argv: the
308
+ * limits, the file to create when the limit stops the command, the open descriptors above 2 to
309
+ * hand the command, and the rest; null when a value is invalid.
310
+ */
311
+ function holdOptions(argv) {
312
+ const whole = (value, min) =>
313
+ /^\d+$/.test(value ?? "") && Number(value) >= min ? Number(value) : null;
314
+ const holdS = whole(argv[1], 1);
315
+ let rest = argv.slice(2);
316
+ let graceS = 10;
317
+ if (rest[0] === "--grace-s") {
318
+ graceS = whole(rest[1], 0);
319
+ rest = rest.slice(2);
320
+ }
321
+ let stoppedFile = null;
322
+ if (rest[0] === "--stopped-file") {
323
+ stoppedFile = rest[1] || null;
324
+ if (!stoppedFile) return null;
325
+ rest = rest.slice(2);
326
+ }
327
+ let fds = [];
328
+ if (rest[0] === "--pass-fds") {
329
+ fds = (rest[1] ?? "")
330
+ .split(",")
331
+ .filter(Boolean)
332
+ .map((fd) => whole(fd, 3));
333
+ rest = rest.slice(2);
334
+ }
335
+ if (rest[0] === "--") rest = rest.slice(1);
336
+ if (holdS === null || graceS === null) return null;
337
+ if (fds.some((fd) => fd === null || !existsSync(`/dev/fd/${fd}`))) return null;
338
+ return { hold: { holdS, graceS, stoppedFile, fds }, rest };
339
+ }
340
+
61
341
  if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
62
- const [command, ...args] = process.argv.slice(2);
342
+ let argv = process.argv.slice(2);
343
+ let hold = null;
344
+ if (argv[0] === "--hold-s") {
345
+ const options = holdOptions(argv);
346
+ if (!options) {
347
+ console.error(
348
+ "bkit-test-awake: --hold-s needs a whole number of seconds of at least 1, --grace-s one of at least 0, --stopped-file a path, and --pass-fds open descriptor numbers of at least 3",
349
+ );
350
+ process.exit(2);
351
+ }
352
+ ({ hold, rest: argv } = options);
353
+ }
354
+ const [command, ...args] = argv;
63
355
  if (!command || (command === "--shell" && args.length !== 1)) {
64
356
  console.error("bkit-test-awake: name a command, or --shell followed by one command string");
65
357
  process.exitCode = 2;
66
- } else if (command === "--shell") {
67
- const windows = process.platform === "win32";
68
- process.exitCode = await runAwake(
69
- windows ? process.env.ComSpec || "cmd.exe" : "/bin/sh",
70
- windows ? ["/d", "/s", "/c", args[0]] : ["-c", args[0]],
71
- );
72
358
  } else {
73
- process.exitCode = await runAwake(command, args);
359
+ process.exitCode = await runAwake(command, args, process.platform, hold);
74
360
  }
75
361
  }