@cbartens/bkit 5.3.0 → 5.5.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 (186) hide show
  1. package/.bkit/README.md +20 -7
  2. package/.bkit/core/.agents/docs.md +1 -1
  3. package/.bkit/core/.agents/rules.md +14 -9
  4. package/.bkit/core/.bkit/README.md +19 -6
  5. package/.bkit/core/.bkit/cloud.md +77 -46
  6. package/.bkit/core/.bkit/comparison.md +3 -3
  7. package/.bkit/core/.bkit/install.md +21 -18
  8. package/.bkit/core/.bkit/lite.md +6 -6
  9. package/.bkit/core/.bkit/pipeline.md +6 -3
  10. package/.bkit/core/.bkit/prompts.md +14 -10
  11. package/.bkit/core/.bkit/providers.md +7 -7
  12. package/.bkit/core/.bkit/templates.md +46 -10
  13. package/.bkit/core/.bkit/trackers.md +92 -38
  14. package/.bkit/core/.bkit/workflows.md +140 -116
  15. package/.bkit/core/AGENTS.md +2 -2
  16. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  17. package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
  18. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  19. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  20. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  22. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +2 -2
  23. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  25. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  26. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  27. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  28. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  30. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  31. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
  33. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  35. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  36. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  38. package/.bkit/core/docs/templates/bkit-audit-issues.md +25 -8
  39. package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
  40. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  41. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  43. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
  44. package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
  45. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  46. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  47. package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
  48. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
  50. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  51. package/.bkit/core/engine/checks/after/auth.ts +88 -45
  52. package/.bkit/core/engine/checks/after/github.ts +18 -5
  53. package/.bkit/core/engine/checks/after/index.ts +1 -1
  54. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  55. package/.bkit/core/engine/checks/before/env.ts +28 -18
  56. package/.bkit/core/engine/checks/before/mcp.ts +4 -2
  57. package/.bkit/core/engine/checks/status-holes.ts +0 -1
  58. package/.bkit/core/engine/checks/tips/catalogue.ts +31 -2
  59. package/.bkit/core/engine/checks/tips/index.ts +49 -27
  60. package/.bkit/core/engine/cli.ts +27 -18
  61. package/.bkit/core/engine/commands/ci/ci.ts +107 -0
  62. package/.bkit/core/engine/commands/comply.ts +25 -16
  63. package/.bkit/core/engine/commands/install/install.ts +11 -4
  64. package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
  65. package/.bkit/core/engine/commands/land.ts +156 -0
  66. package/.bkit/core/engine/commands/lib.ts +10 -8
  67. package/.bkit/core/engine/commands/registry.ts +2 -0
  68. package/.bkit/core/engine/commands/tips.ts +7 -3
  69. package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
  70. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  71. package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
  72. package/.bkit/core/engine/commands/workflow/issues.ts +106 -42
  73. package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
  74. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  75. package/.bkit/core/engine/commands/workflow/prs.ts +14 -3
  76. package/.bkit/core/engine/commands/workflow/repo.ts +6 -0
  77. package/.bkit/core/engine/commands/workflow/roadmap.ts +53 -54
  78. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  79. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  80. package/.bkit/core/engine/commands/workflow/steps.ts +26 -17
  81. package/.bkit/core/engine/commands/workflow/workflows.ts +442 -269
  82. package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
  83. package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
  84. package/.bkit/core/engine/install/manifest.ts +31 -10
  85. package/.bkit/core/engine/install/modules/cloud.ts +3 -1
  86. package/.bkit/core/engine/install/modules/core.ts +97 -4
  87. package/.bkit/core/engine/install/modules/opencode.ts +5 -0
  88. package/.bkit/core/engine/install/placeholders.ts +13 -17
  89. package/.bkit/core/engine/install/write.ts +37 -1
  90. package/.bkit/core/engine/render/trackers.ts +35 -23
  91. package/.bkit/core/engine/shared/egress.ts +6 -0
  92. package/.bkit/core/engine/shared/settings.ts +96 -1
  93. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  94. package/.bkit/core/hooks/guardrails-tiers.js +1 -1
  95. package/.bkit/core/prompts/bkit-audit-generate.md +80 -7
  96. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  97. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  98. package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
  99. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  100. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  101. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
  102. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  103. package/.bkit/core/prompts/bkit-design-generate.md +2 -1
  104. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  105. package/.bkit/core/prompts/bkit-utility-update-decisions.md +4 -2
  106. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +4 -2
  107. package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
  108. package/.bkit/core/prompts/bkit-utility-update-failures.md +4 -2
  109. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +4 -2
  110. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +12 -5
  111. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
  112. package/.bkit/core/workflows/bkit-auto.md +19 -6
  113. package/.bkit/core/workflows/bkit-build.md +64 -22
  114. package/.bkit/core/workflows/bkit-debug.md +72 -28
  115. package/.bkit/core/workflows/bkit-design.md +101 -37
  116. package/.bkit/core/workflows/bkit-plan.md +82 -31
  117. package/.bkit/core/workflows/bkit-ship.md +127 -108
  118. package/.bkit/shared/.bkit/.env.example +8 -0
  119. package/.bkit/shared/.claude/bkit-cloud.md +12 -12
  120. package/.bkit/shared/.claude/settings.json +4 -1
  121. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  122. package/.bkit/shared/.cursor/mcp.json +11 -4
  123. package/.bkit/shared/.mcp.json +11 -4
  124. package/.bkit/shared/.opencode/opencode.json +2 -0
  125. package/.bkit/shared/docs/deployments.md +44 -29
  126. package/.bkit/shared/docs/security.md +1 -1
  127. package/.bkit/shared/docs/testing.md +3 -3
  128. package/.bkit/shared/gitignore +1 -2
  129. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
  130. package/.bkit/templates/.github/renovate.json5 +1 -1
  131. package/.bkit/templates/.github/workflows/bkit-ci.yml +29 -56
  132. package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
  133. package/.bkit/templates/.husky/pre-commit +10 -4
  134. package/.bkit/templates/.husky/pre-push +69 -12
  135. package/.bkit/templates/.lintstagedrc.json +5 -1
  136. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +138 -0
  137. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +181 -0
  138. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  139. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  140. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
  141. package/CHANGELOG.md +85 -1
  142. package/README.md +102 -100
  143. package/dist/checks/after/auth.js +81 -45
  144. package/dist/checks/after/github.js +17 -5
  145. package/dist/checks/after/index.js +1 -1
  146. package/dist/checks/after/tools.js +1 -1
  147. package/dist/checks/before/env.js +24 -17
  148. package/dist/checks/before/mcp.js +4 -2
  149. package/dist/checks/status-holes.js +0 -1
  150. package/dist/checks/tips/catalogue.js +28 -2
  151. package/dist/checks/tips/index.js +44 -28
  152. package/dist/cli.js +27 -19
  153. package/dist/commands/ci/ci.js +100 -0
  154. package/dist/commands/comply.js +20 -13
  155. package/dist/commands/install/install.js +10 -4
  156. package/dist/commands/install/uninstall.js +42 -0
  157. package/dist/commands/land.js +129 -0
  158. package/dist/commands/lib.js +9 -6
  159. package/dist/commands/registry.js +2 -0
  160. package/dist/commands/tips.js +7 -3
  161. package/dist/commands/workflow/branches.js +300 -243
  162. package/dist/commands/workflow/disk.js +452 -0
  163. package/dist/commands/workflow/fids.js +22 -15
  164. package/dist/commands/workflow/issues.js +90 -41
  165. package/dist/commands/workflow/ledgers.js +26 -11
  166. package/dist/commands/workflow/locks.js +35 -130
  167. package/dist/commands/workflow/prs.js +8 -3
  168. package/dist/commands/workflow/repo.js +5 -0
  169. package/dist/commands/workflow/roadmap.js +52 -57
  170. package/dist/commands/workflow/runtime.js +3 -2
  171. package/dist/commands/workflow/status.js +32 -12
  172. package/dist/commands/workflow/steps.js +20 -13
  173. package/dist/commands/workflow/workflows.js +397 -251
  174. package/dist/commands/workflow/workstreams.js +3 -2
  175. package/dist/commands/workflow/worktrees.js +11 -1
  176. package/dist/install/manifest.js +30 -10
  177. package/dist/install/modules/cloud.js +3 -1
  178. package/dist/install/modules/core.js +95 -5
  179. package/dist/install/modules/opencode.js +6 -0
  180. package/dist/install/placeholders.js +13 -19
  181. package/dist/install/write.js +26 -2
  182. package/dist/render/trackers.js +34 -20
  183. package/dist/shared/egress.js +6 -0
  184. package/dist/shared/settings.js +44 -0
  185. package/dist/shared/timeouts.js +8 -7
  186. package/package.json +11 -2
@@ -2,16 +2,21 @@
2
2
  # bkit pre-push. Example. Copy into the repo and own it.
3
3
  # bkit install does not write this file and does not overwrite a copy.
4
4
  #
5
- # FAST deterministic gates only: the `bkit:gate` script (typecheck + unit tests +
6
- # format:check + prose + the enforcing slop gate) plus the bkit drift gate (no
7
- # Docker/network) — the full deterministic mirror of CI. Heavier tiers run in CI, NOT
8
- # here: integration + E2E -> bkit-tests (gated on web_affected / run_e2e); @live ->
9
- # bkit-tests-live; "did the planned tiers run?" -> bkit-tests-check. See bkit-ci.yml § FULL
10
- # CI SCAFFOLD REFERENCE — keep slow/network/deploy checks OUT. Turbo monorepos: scope
11
- # tests inside the `bkit:gate*` scripts with
12
- # `--filter="...[origin/<default>]"`; never add integration/E2E/@live.
5
+ # Deterministic gates: `bkit:gate:static-unit-integration` when package.json declares it,
6
+ # else `bkit:gate:static-unit` (typecheck + lint + format:check + prose + the enforcing slop
7
+ # gate + unit tests, then the integration tier), plus the bkit drift gate. Integration runs
8
+ # here, never on commit: it may start local services (a database in Docker), never reach a
9
+ # deployed one. E2E -> bkit-tests (gated on web_affected / run_e2e); @live -> bkit-tests-live;
10
+ # "did the planned tiers run?" -> bkit-tests-check. See bkit-ci.yml § FULL CI SCAFFOLD
11
+ # REFERENCE — keep deployed-URL/network/deploy checks OUT. Turbo monorepos: scope tests inside
12
+ # the `bkit:gate*` scripts with `--filter="...[origin/<default>]"`; never add E2E/@live.
13
13
  #
14
- # Revert-branch bypass: on a revert branch the suite is skipped; lint + typecheck still run.
14
+ # Revert-branch bypass: on a revert branch the unit and integration tiers are skipped; lint +
15
+ # typecheck still run.
16
+ #
17
+ # Min push: every changed file matches `bkit.minPushPaths` (package.json; default plan logs,
18
+ # ledgers) → `bkit:gate:min` replaces the full gate; MIN_PUSH=1 for repo extras. Files decide,
19
+ # never `[skip ci]`.
15
20
  set -e
16
21
 
17
22
  # ── delete-only push: nothing leaves this machine, so there is nothing to gate ──
@@ -21,10 +26,13 @@ set -e
21
26
  # mixing a delete with a real update still gates, and so does an empty ref list. Reading
22
27
  # stdin here is safe: every later command redirects from /dev/null. `[ -t 0 ]` keeps a
23
28
  # hand-run hook from hanging. The loop also sets PUSH_DEV_SHA (commit pushed to dev) for
24
- # repo extras that gate only dev pushes (e.g. scripts/graphify/bkit-graph-pre-push.sh).
29
+ # repo extras that gate only dev pushes (e.g. scripts/graphify/bkit-graph-pre-push.sh),
30
+ # PUSH_SHAS (every pushed commit) and PUSH_SHARED_SHAS (those pushed to dev / main).
25
31
  PUSH_SAW_REF=0
26
32
  PUSH_HAS_COMMITS=0
27
33
  PUSH_DEV_SHA=""
34
+ PUSH_SHAS=""
35
+ PUSH_SHARED_SHAS=""
28
36
  if [ ! -t 0 ]; then
29
37
  while read -r _push_local_ref push_local_sha push_remote_ref _push_remote_sha; do
30
38
  [ -n "$push_local_sha" ] || continue
@@ -32,7 +40,11 @@ if [ ! -t 0 ]; then
32
40
  case "$push_local_sha" in
33
41
  *[!0]*)
34
42
  PUSH_HAS_COMMITS=1
43
+ PUSH_SHAS="$PUSH_SHAS $push_local_sha"
35
44
  [ "$push_remote_ref" = "refs/heads/dev" ] && PUSH_DEV_SHA="$push_local_sha"
45
+ case "$push_remote_ref" in
46
+ refs/heads/dev|refs/heads/main) PUSH_SHARED_SHAS="$PUSH_SHARED_SHAS $push_local_sha" ;;
47
+ esac
36
48
  ;;
37
49
  esac
38
50
  done
@@ -78,6 +90,34 @@ case "$BRANCH" in
78
90
  ;;
79
91
  esac
80
92
 
93
+ # Min push: `bkit ci min-push` exits 0 only when every file changed since each pushed
94
+ # commit left origin/dev (else origin/main) matches `bkit.minPushPaths`. Anything else
95
+ # (code, no files, unreadable range, no refs) → MIN_PUSH=0, full gate: a skip on no
96
+ # evidence reads as a pass.
97
+ MIN_PUSH=0
98
+ if [ -n "$PUSH_SHAS" ]; then
99
+ MIN_PUSH_REFS=""
100
+ for push_sha in $PUSH_SHAS; do MIN_PUSH_REFS="$MIN_PUSH_REFS --ref=$push_sha"; done
101
+ # shellcheck disable=SC2086 # hex SHAs only: word-splitting is the point
102
+ if pnpm -s bkit ci min-push $MIN_PUSH_REFS < /dev/null > /dev/null; then
103
+ MIN_PUSH=1
104
+ fi
105
+ fi
106
+
107
+ # CI-suppressor guard on dev / main: a skip-CI token on a push's LAST commit skips CI for the
108
+ # whole push, so code would land untested. Blocked unless a min push. Feature branches keep
109
+ # the open-PR guard above (workflows push `[skip ci]` code heads mid-run).
110
+ for push_sha in $PUSH_SHARED_SHAS; do
111
+ if pnpm -s bkit ci skip-token --ref="$push_sha" < /dev/null > /dev/null; then
112
+ if [ "$MIN_PUSH" != "1" ] &&
113
+ ! pnpm -s bkit ci min-push --ref="$push_sha" < /dev/null > /dev/null; then
114
+ echo "[pre-push] BLOCKED: $push_sha carries a CI-suppressing token and changes files outside bkit.minPushPaths — that code would land on dev / main with no CI run." >&2
115
+ echo "[pre-push] Add a clean trigger commit and re-push: git commit --allow-empty -m \"chore: trigger CI\" && git push" >&2
116
+ exit 1
117
+ fi
118
+ fi
119
+ done
120
+
81
121
  # tmp/ prune — deletes files under tmp/ untouched for 7+ days. Not a gate: a failed
82
122
  # prune warns and the push goes on. Skipped until scripts/cleanup/ holds the script.
83
123
  if [ -f scripts/cleanup/bkit-tmp-prune.mjs ]; then
@@ -88,10 +128,16 @@ fi
88
128
  # WHAT each gate runs lives in package.json, not here — the same `bkit:gate*` scripts
89
129
  # the bkit agent workflows and prompts dispatch through. Edit the scripts, not this
90
130
  # hook. Repo-specific extras go BELOW this block.
91
- # Revert path drops the suite only: prose and slop:delta still run.
92
- if [ "$IS_REVERT" = "1" ]; then
131
+ # Min push: `bkit:gate:min` only. Revert path drops the suite only: prose
132
+ # and slop:delta still run. Otherwise the deepest push gate package.json declares.
133
+ if [ "$MIN_PUSH" = "1" ]; then
134
+ echo "[pre-push] min push — bkit:gate:min instead of the full gate" >&2
135
+ pnpm bkit:gate:min < /dev/null
136
+ elif [ "$IS_REVERT" = "1" ]; then
93
137
  echo "[pre-push] revert branch/commit detected — skipping the test suite"
94
138
  pnpm bkit:gate:static < /dev/null
139
+ elif grep -q '"bkit:gate:static-unit-integration"[[:space:]]*:' package.json 2>/dev/null; then
140
+ pnpm bkit:gate:static-unit-integration < /dev/null
95
141
  else
96
142
  pnpm bkit:gate:static-unit < /dev/null
97
143
  fi
@@ -101,3 +147,14 @@ fi
101
147
  # Outside the gate scripts: it validates the bkit install, not your source.
102
148
  # Fix: `pnpm bkit install`, stage the regenerated files, commit, push.
103
149
  pnpm bkit check < /dev/null
150
+
151
+ # Repo extras go here, above the disk prune. Slow ones (Docker, database, build) skip a
152
+ # min push:
153
+ # if [ "$MIN_PUSH" != "1" ]; then pnpm <slow-script> < /dev/null; fi
154
+
155
+ # disk prune — keep this block last, so it runs only once every gate above passed. Starts
156
+ # your max cleanup steps (`bkit disk prune`, .bkit/templates.md § Disk prune) in the
157
+ # background, at most once a day, or hourly while free disk is under bkit.disk.minFreeGb;
158
+ # with no step files it does nothing. Not a gate: a failure warns and the push goes on.
159
+ pnpm -s bkit disk prune --mode=max --auto < /dev/null > /dev/null ||
160
+ echo "[pre-push] WARN: disk prune failed; push continues" >&2
@@ -1,3 +1,7 @@
1
1
  {
2
- "*": "prettier --write --ignore-unknown"
2
+ "docs/{plans,audits}/**/*.md": [
3
+ "node scripts/prettier/bkit-insert-ignore.mjs",
4
+ "prettier --write --ignore-unknown"
5
+ ],
6
+ "!(docs/{plans,audits}/**/*.md)": "prettier --write --ignore-unknown"
3
7
  }
@@ -0,0 +1,138 @@
1
+ #!/usr/bin/env node
2
+ // Example. Copy into scripts/ci/lanes/ and own it. bkit install does not write this file
3
+ // and does not overwrite a copy.
4
+ /**
5
+ * check-tree-cache.mjs — whether a pull request lane may skip its suite.
6
+ *
7
+ * A pull request lane skips when the files it would test are exactly the files a push run
8
+ * already tested green. "The files" is the git tree of the checked-out commit (for a pull
9
+ * request, GitHub's merge preview). A push run tests its head commit's tree, so a green push
10
+ * run whose head has the same tree proved this lane — provided that run's job of the same name
11
+ * concluded `success` (a `[skip ci]` or `run_level=none` push concludes green with every lane
12
+ * skipped, which proves nothing).
13
+ *
14
+ * Push and dispatch runs never skip: the run on a push to dev or the default branch is the
15
+ * record of what that branch holds, so it always runs the suite. `[force build]` /
16
+ * `[force cache]` in the pull request title skip nothing either.
17
+ *
18
+ * Usage: node scripts/ci/lanes/check-tree-cache.mjs >> "$GITHUB_OUTPUT"
19
+ * (env: GH_TOKEN, REPO, EVENT_NAME, JOB, PR_TITLE; optional WORKFLOW_FILE)
20
+ * Output: `skip=true` or `skip=false` on stdout; the reason on stderr. Exit 0 always — every
21
+ * failure (gh, git, unparseable output) resolves to `skip=false`, which runs the suite.
22
+ */
23
+
24
+ import { spawnSync } from "node:child_process";
25
+ import { pathToFileURL } from "node:url";
26
+
27
+ /** The workflow whose runs count. Set WORKFLOW_FILE if your CI file has another name. */
28
+ export const WORKFLOW_FILE = process.env.WORKFLOW_FILE || "bkit-ci.yml";
29
+
30
+ /** How far back the run lookup reaches. */
31
+ export const LOOKBACK_DAYS = 7;
32
+
33
+ /** At most this many tree-matching runs have their jobs read before giving up. */
34
+ export const MAX_JOB_LOOKUPS = 3;
35
+
36
+ const FORCE_MARKERS = ["[force build]", "[force cache]"];
37
+
38
+ /**
39
+ * Pure decision. `runs` are green push runs (`{ id, run_number, tree }`); `jobConclusion(id)`
40
+ * returns the conclusion of this lane's job in run `id` ("" when unknown).
41
+ */
42
+ export function decideTreeSkip({ eventName, title, headTree, runs, jobConclusion }) {
43
+ if (eventName !== "pull_request") {
44
+ return { skip: false, reason: `${eventName || "unknown"} event — only a pull request skips` };
45
+ }
46
+ const marker = FORCE_MARKERS.find((m) => (title ?? "").includes(m));
47
+ if (marker) return { skip: false, reason: `${marker} in the title` };
48
+ if (!headTree) return { skip: false, reason: "no tree for HEAD" };
49
+ const matches = (runs ?? [])
50
+ .filter((r) => r?.tree === headTree && Number.isFinite(r?.id))
51
+ .sort((a, b) => (b.run_number ?? 0) - (a.run_number ?? 0))
52
+ .slice(0, MAX_JOB_LOOKUPS);
53
+ for (const run of matches) {
54
+ const conclusion = jobConclusion(run.id);
55
+ if (conclusion === "success") {
56
+ return { skip: true, reason: `tree ${headTree} passed in push run ${run.id}` };
57
+ }
58
+ }
59
+ return {
60
+ skip: false,
61
+ reason: matches.length
62
+ ? `tree ${headTree} matched ${matches.length} push run(s), none with this job green`
63
+ : `no green push run in ${LOOKBACK_DAYS} days has tree ${headTree}`,
64
+ };
65
+ }
66
+
67
+ /** Runs `gh`; never throws. `ok` false carries the reason (spawn error or first stderr line). */
68
+ function gh(args) {
69
+ const { status, stdout, stderr, error } = spawnSync("gh", args, {
70
+ encoding: "utf8",
71
+ stdio: ["ignore", "pipe", "pipe"],
72
+ });
73
+ if (error || status !== 0) {
74
+ return { ok: false, out: "", reason: error ? error.message : String(stderr).split("\n")[0] };
75
+ }
76
+ return { ok: true, out: stdout, reason: "" };
77
+ }
78
+
79
+ function greenPushRuns(repo, now = new Date()) {
80
+ const since = new Date(now.getTime() - LOOKBACK_DAYS * 86_400_000).toISOString().slice(0, 10);
81
+ const path =
82
+ `repos/${repo}/actions/workflows/${WORKFLOW_FILE}/runs` +
83
+ `?event=push&status=success&created=${encodeURIComponent(`>=${since}`)}&per_page=100`;
84
+ const res = gh([
85
+ "api",
86
+ path,
87
+ "--jq",
88
+ "[.workflow_runs[] | {id, run_number, tree: .head_commit.tree_id}]",
89
+ ]);
90
+ // No run list is not fatal: main() turns this into skip=false, which runs the suite.
91
+ if (!res.ok) throw new Error(`could not list ${WORKFLOW_FILE} runs (${res.reason})`);
92
+ return JSON.parse(res.out || "[]");
93
+ }
94
+
95
+ function jobConclusionIn(repo, job) {
96
+ return (runId) => {
97
+ const res = gh([
98
+ "api",
99
+ `repos/${repo}/actions/runs/${runId}/jobs?per_page=100`,
100
+ "--jq",
101
+ `[.jobs[] | select(.name == ${JSON.stringify(job)}) | .conclusion] | first // ""`,
102
+ ]);
103
+ // An unreadable job list proves nothing about this lane, so the run does not count.
104
+ if (!res.ok) {
105
+ console.error(`[check-tree-cache] could not read jobs of run ${runId} (${res.reason})`);
106
+ return "";
107
+ }
108
+ return res.out.trim();
109
+ };
110
+ }
111
+
112
+ function headTree() {
113
+ const { status, stdout } = spawnSync("git", ["rev-parse", "HEAD^{tree}"], {
114
+ encoding: "utf8",
115
+ stdio: ["ignore", "pipe", "ignore"],
116
+ });
117
+ return status === 0 ? stdout.trim() : "";
118
+ }
119
+
120
+ export function main(env) {
121
+ let result;
122
+ try {
123
+ const isPr = env.EVENT_NAME === "pull_request";
124
+ result = decideTreeSkip({
125
+ eventName: env.EVENT_NAME,
126
+ title: env.PR_TITLE,
127
+ headTree: isPr ? headTree() : "",
128
+ runs: isPr ? greenPushRuns(env.REPO) : [],
129
+ jobConclusion: jobConclusionIn(env.REPO, env.JOB),
130
+ });
131
+ } catch (err) {
132
+ result = { skip: false, reason: `lookup failed (${err.message}) — running the suite` };
133
+ }
134
+ console.error(`[check-tree-cache] skip=${result.skip} — ${result.reason}`);
135
+ process.stdout.write(`skip=${result.skip}\n`);
136
+ }
137
+
138
+ if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) main(process.env);
@@ -0,0 +1,181 @@
1
+ #!/usr/bin/env node
2
+ // Example. Copy into scripts/ci/lanes/ and own it. bkit install does not write this file
3
+ // and does not overwrite a copy.
4
+ /**
5
+ * check-tree-cache.test.mjs — unit tests for the pull request tree cache.
6
+ *
7
+ * Pure Node, no runner: `node scripts/ci/lanes/check-tree-cache.test.mjs`.
8
+ * Exit: 0 = all tests passed, 1 = at least one test failed.
9
+ */
10
+
11
+ import { spawnSync } from "node:child_process";
12
+ import fs from "node:fs";
13
+ import os from "node:os";
14
+ import path from "node:path";
15
+ import { fileURLToPath } from "node:url";
16
+ import { decideTreeSkip } from "./check-tree-cache.mjs";
17
+
18
+ const SCRIPT = fileURLToPath(new URL("./check-tree-cache.mjs", import.meta.url));
19
+
20
+ /** Run the script with fake `gh` / `git` binaries first on PATH. */
21
+ function runWithFakes({ gh, git, eventName = "pull_request", title = "feat: x" }) {
22
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tree-cache-"));
23
+ try {
24
+ fs.writeFileSync(path.join(dir, "gh"), `#!/bin/sh\n${gh}\n`, { mode: 0o755 });
25
+ fs.writeFileSync(path.join(dir, "git"), `#!/bin/sh\n${git}\n`, { mode: 0o755 });
26
+ const r = spawnSync(process.execPath, [SCRIPT], {
27
+ encoding: "utf8",
28
+ env: {
29
+ ...process.env,
30
+ PATH: `${dir}${path.delimiter}${process.env.PATH}`,
31
+ REPO: "o/r",
32
+ EVENT_NAME: eventName,
33
+ JOB: "bkit-tests-unit",
34
+ PR_TITLE: title,
35
+ },
36
+ });
37
+ return { status: r.status, stdout: r.stdout.trim(), stderr: r.stderr };
38
+ } finally {
39
+ fs.rmSync(dir, { recursive: true, force: true });
40
+ }
41
+ }
42
+
43
+ let passed = 0;
44
+ let failed = 0;
45
+
46
+ function test(name, fn) {
47
+ try {
48
+ fn();
49
+ passed++;
50
+ console.log(` ok ${name}`);
51
+ } catch (err) {
52
+ failed++;
53
+ console.log(` FAIL ${name} — ${err.message}`);
54
+ }
55
+ }
56
+
57
+ function assert(cond, message) {
58
+ if (!cond) throw new Error(message);
59
+ }
60
+
61
+ const TREE = "t".repeat(40);
62
+ const OTHER = "o".repeat(40);
63
+ const green = () => "success";
64
+ const base = { eventName: "pull_request", title: "feat: x", headTree: TREE };
65
+
66
+ test("a pull request whose files a green push run tested skips", () => {
67
+ const r = decideTreeSkip({
68
+ ...base,
69
+ runs: [{ id: 7, run_number: 3, tree: TREE }],
70
+ jobConclusion: green,
71
+ });
72
+ assert(r.skip === true, r.reason);
73
+ });
74
+
75
+ test("a push run never skips, even with the same files green", () => {
76
+ for (const eventName of ["push", "workflow_dispatch"]) {
77
+ const r = decideTreeSkip({
78
+ ...base,
79
+ eventName,
80
+ runs: [{ id: 7, run_number: 3, tree: TREE }],
81
+ jobConclusion: green,
82
+ });
83
+ assert(r.skip === false, `${eventName}: ${r.reason}`);
84
+ }
85
+ });
86
+
87
+ test("[force build] / [force cache] in the title run the suite", () => {
88
+ for (const title of ["feat: x [force build]", "[force cache] feat: x"]) {
89
+ const r = decideTreeSkip({
90
+ ...base,
91
+ title,
92
+ runs: [{ id: 7, run_number: 3, tree: TREE }],
93
+ jobConclusion: green,
94
+ });
95
+ assert(r.skip === false, `${title}: ${r.reason}`);
96
+ }
97
+ });
98
+
99
+ test("other files → no skip", () => {
100
+ const r = decideTreeSkip({
101
+ ...base,
102
+ runs: [{ id: 7, run_number: 3, tree: OTHER }],
103
+ jobConclusion: green,
104
+ });
105
+ assert(r.skip === false, r.reason);
106
+ });
107
+
108
+ test("same files, but that run skipped this lane ([skip ci] / run_level=none) → no skip", () => {
109
+ const r = decideTreeSkip({
110
+ ...base,
111
+ runs: [{ id: 7, run_number: 3, tree: TREE }],
112
+ jobConclusion: () => "skipped",
113
+ });
114
+ assert(r.skip === false, r.reason);
115
+ });
116
+
117
+ test("a later matching run with the lane green is found past one that skipped it", () => {
118
+ const seen = [];
119
+ const r = decideTreeSkip({
120
+ ...base,
121
+ runs: [
122
+ { id: 1, run_number: 1, tree: TREE },
123
+ { id: 2, run_number: 2, tree: TREE },
124
+ ],
125
+ jobConclusion: (id) => {
126
+ seen.push(id);
127
+ return id === 1 ? "success" : "skipped";
128
+ },
129
+ });
130
+ assert(r.skip === true, r.reason);
131
+ assert(seen.join(",") === "2,1", `newest first, got ${seen}`);
132
+ });
133
+
134
+ test("no tree for HEAD → no skip", () => {
135
+ const r = decideTreeSkip({
136
+ ...base,
137
+ headTree: "",
138
+ runs: [{ id: 7, run_number: 3, tree: "" }],
139
+ jobConclusion: green,
140
+ });
141
+ assert(r.skip === false, r.reason);
142
+ });
143
+
144
+ const RUNS = `echo '[{"id":7,"run_number":3,"tree":"${TREE}"}]'`;
145
+ const GH_OK = `case "$2" in *jobs*) echo success ;; *) ${RUNS} ;; esac`;
146
+
147
+ test("end to end: matching green push run prints skip=true", () => {
148
+ const r = runWithFakes({ gh: GH_OK, git: `echo ${TREE}` });
149
+ assert(r.status === 0 && r.stdout === "skip=true", JSON.stringify(r));
150
+ });
151
+
152
+ test("end to end: a push event prints skip=false without calling gh", () => {
153
+ const r = runWithFakes({ gh: "exit 9", git: `echo ${TREE}`, eventName: "push" });
154
+ assert(r.status === 0 && r.stdout === "skip=false", JSON.stringify(r));
155
+ });
156
+
157
+ test("a gh failure exits 0 with skip=false", () => {
158
+ const r = runWithFakes({ gh: "exit 4", git: `echo ${TREE}` });
159
+ assert(r.status === 0 && r.stdout === "skip=false", JSON.stringify(r));
160
+ });
161
+
162
+ test("unparseable gh output exits 0 with skip=false", () => {
163
+ const r = runWithFakes({ gh: "echo 'not json'", git: `echo ${TREE}` });
164
+ assert(r.status === 0 && r.stdout === "skip=false", JSON.stringify(r));
165
+ });
166
+
167
+ test("a failed job lookup does not count the run: skip=false", () => {
168
+ const r = runWithFakes({
169
+ gh: `case "$2" in *jobs*) echo boom >&2; exit 1 ;; *) ${RUNS} ;; esac`,
170
+ git: `echo ${TREE}`,
171
+ });
172
+ assert(r.status === 0 && r.stdout === "skip=false", JSON.stringify(r));
173
+ });
174
+
175
+ test("a git failure exits 0 with skip=false", () => {
176
+ const r = runWithFakes({ gh: GH_OK, git: "exit 128" });
177
+ assert(r.status === 0 && r.stdout === "skip=false", JSON.stringify(r));
178
+ });
179
+
180
+ console.log(`\n${passed} passed, ${failed} failed`);
181
+ process.exit(failed > 0 ? 1 : 0);
@@ -0,0 +1,197 @@
1
+ // Example. Copy to ~/.config/bkit/disk-prune.mjs (`$XDG_CONFIG_HOME/bkit/` when set) and own
2
+ // it. bkit install does not write this file and does not overwrite a copy.
3
+ /**
4
+ * disk-prune.mjs — this machine's cleanup steps for `bkit disk prune`: tools every repo on
5
+ * the machine shares (Docker, the pnpm store, Xcode, Gradle, simulators). bkit deletes
6
+ * nothing itself: it runs only the steps listed here and in each checkout's
7
+ * `scripts/cleanup/bkit-disk-prune.mjs`.
8
+ *
9
+ * Steps run from the home folder, one at a time, with the same shape as the checkout file:
10
+ * `name`, `mode` ("min" | "max"; `max` runs the `min` steps too), `run` (shell command or
11
+ * function), optional `skip` and `paths` (what `--dry-run` sizes: the most the step can free;
12
+ * leave it out when that misleads). A step whose tool is not installed skips itself.
13
+ *
14
+ * Keep a step only when what it deletes comes back by itself. Deliberately left out — add
15
+ * them yourself only if you accept the cost:
16
+ * - Docker named volumes (`docker volume prune -a`): local databases live there
17
+ * - whole runtimes or SDKs (Xcode, Android system images, iOS simulator runtimes, Node
18
+ * versions): gigabytes to download and a manual step to reinstall
19
+ * - deleting the whole pnpm store: `node_modules` hard-link into it, so it frees nothing
20
+ * while any checkout is installed; `pnpm store prune` frees what can be freed
21
+ */
22
+
23
+ import { spawnSync } from "node:child_process";
24
+ import os from "node:os";
25
+
26
+ /** True when `tool` is on PATH. */
27
+ const has = (tool) => spawnSync("sh", ["-c", `command -v ${tool}`]).status === 0;
28
+ /** True when a process whose full command line matches `pattern` is running. */
29
+ const running = (pattern) => spawnSync("pgrep", ["-f", pattern]).status === 0;
30
+ const missing = (tool) => !has(tool) && `${tool} is not installed`;
31
+ const dockerDown = () =>
32
+ missing("docker") ||
33
+ (spawnSync("docker", ["info"], { stdio: "ignore" }).status !== 0 && "Docker is not running");
34
+ const notMac = () => os.platform() !== "darwin" && "not macOS";
35
+
36
+ /** Docker's major version; 0 when unreadable. */
37
+ function dockerMajor() {
38
+ const r = spawnSync("docker", ["version", "--format", "{{.Server.Version}}"], {
39
+ encoding: "utf8",
40
+ });
41
+ return r.status === 0 ? Number(r.stdout.split(".")[0]) || 0 : 0;
42
+ }
43
+
44
+ // Name the simulators and emulators you can do without; empty = none deleted. Booted or
45
+ // running ones are skipped. Find names with `xcrun simctl list devices` and
46
+ // `emulator -list-avds`.
47
+ const SIMULATORS = [];
48
+ const EMULATORS = [];
49
+
50
+ export default [
51
+ // --- min: stale, cheap ---------------------------------------------------
52
+ {
53
+ // Comes back: the next `docker build` or `docker pull`.
54
+ name: "Docker dangling images",
55
+ mode: "min",
56
+ skip: dockerDown,
57
+ run: "docker image prune -f",
58
+ },
59
+ {
60
+ // Comes back: the next `docker build`, slower once.
61
+ name: "Docker build cache older than 7 days",
62
+ mode: "min",
63
+ skip: dockerDown,
64
+ run: "docker builder prune -f --filter until=168h",
65
+ },
66
+ {
67
+ // Comes back: never needed — no container uses them. Docker 23+ prunes only anonymous
68
+ // volumes; older Docker would also take named volumes, so the step skips there.
69
+ name: "Docker anonymous volumes",
70
+ mode: "min",
71
+ skip: () => dockerDown() || (dockerMajor() < 23 && "Docker older than 23 prunes named volumes"),
72
+ run: "docker volume prune -f",
73
+ },
74
+ {
75
+ // Comes back: the next `pnpm install` that needs a removed package. No `paths`: the
76
+ // store's size is far more than a prune frees.
77
+ name: "pnpm store packages no project uses",
78
+ mode: "min",
79
+ skip: () =>
80
+ missing("pnpm") || (running("pnpm (install|i|add|update)( |$)") && "pnpm is installing"),
81
+ run: "pnpm store prune",
82
+ },
83
+ {
84
+ // Comes back: never needed — these simulators belong to runtimes no longer installed.
85
+ name: "iOS simulators whose runtime is gone",
86
+ mode: "min",
87
+ skip: () => notMac() || missing("xcrun"),
88
+ run: "xcrun simctl delete unavailable",
89
+ },
90
+ {
91
+ // Comes back: the next `npm install` that needs a removed entry.
92
+ name: "npm cache: drop corrupt and unused entries",
93
+ mode: "min",
94
+ paths: ["~/.npm/_cacache"],
95
+ skip: () => missing("npm"),
96
+ run: "npm cache verify",
97
+ },
98
+
99
+ // --- max: everything that comes back by itself -------------------------
100
+ {
101
+ // Comes back: the next `docker pull` or `docker build`. Containers you have stopped
102
+ // keep their images; `supabase stop` removes its containers, so its images go too and
103
+ // `supabase start` pulls them again.
104
+ name: "Docker images no container uses",
105
+ mode: "max",
106
+ skip: dockerDown,
107
+ run: "docker image prune -a -f",
108
+ },
109
+ {
110
+ // Comes back: the next `docker build`, slower once.
111
+ name: "All of the Docker build cache",
112
+ mode: "max",
113
+ skip: dockerDown,
114
+ run: "docker builder prune -a -f",
115
+ },
116
+ {
117
+ // Comes back: the next Xcode build, slower once.
118
+ name: "Xcode DerivedData",
119
+ mode: "max",
120
+ paths: ["~/Library/Developer/Xcode/DerivedData"],
121
+ skip: () => notMac() || (running("xcodebuild") && "xcodebuild is running"),
122
+ run: 'rm -rf "$HOME/Library/Developer/Xcode/DerivedData"',
123
+ },
124
+ {
125
+ // Comes back: the next Gradle build downloads and rebuilds what it needs.
126
+ name: "Gradle caches",
127
+ mode: "max",
128
+ paths: ["~/.gradle/caches"],
129
+ skip: () => running("GradleDaemon") && "a Gradle daemon is running (`gradle --stop`)",
130
+ run: 'rm -rf "$HOME/.gradle/caches"',
131
+ },
132
+ {
133
+ // Comes back: an emulator cold-boots once, then saves a fresh snapshot.
134
+ name: "Android emulator snapshots",
135
+ mode: "max",
136
+ paths: ["~/.android/avd/*.avd/snapshots"],
137
+ skip: () => running("qemu-system") && "an Android emulator is running",
138
+ run: 'rm -rf "$HOME"/.android/avd/*.avd/snapshots',
139
+ },
140
+ {
141
+ // Comes back: recreate with `xcrun simctl create` (or Xcode → Devices) when needed.
142
+ name: "iOS simulators named in SIMULATORS",
143
+ mode: "max",
144
+ skip: () => notMac() || missing("xcrun") || (SIMULATORS.length === 0 && "SIMULATORS is empty"),
145
+ run: ({ log }) => {
146
+ const booted = spawnSync("xcrun", ["simctl", "list", "devices", "booted"], {
147
+ encoding: "utf8",
148
+ }).stdout;
149
+ for (const name of SIMULATORS) {
150
+ if (booted.includes(`${name} (`)) {
151
+ log(`kept ${name}: booted`);
152
+ continue;
153
+ }
154
+ const r = spawnSync("xcrun", ["simctl", "delete", name], { encoding: "utf8" });
155
+ log(`${name}: ${r.status === 0 ? "deleted" : "not deleted"}`);
156
+ }
157
+ },
158
+ },
159
+ {
160
+ // Comes back: recreate with `avdmanager create avd` (or Android Studio) when needed.
161
+ name: "Android emulators named in EMULATORS",
162
+ mode: "max",
163
+ skip: () => missing("avdmanager") || (EMULATORS.length === 0 && "EMULATORS is empty"),
164
+ run: ({ log }) => {
165
+ for (const name of EMULATORS) {
166
+ if (running(`-avd ${name}( |$)`)) {
167
+ log(`kept ${name}: running`);
168
+ continue;
169
+ }
170
+ const r = spawnSync("avdmanager", ["delete", "avd", "-n", name], { encoding: "utf8" });
171
+ log(`${name}: ${r.status === 0 ? "deleted" : "not deleted"}`);
172
+ }
173
+ },
174
+ },
175
+ {
176
+ // Comes back: the next `npm install` / `npx` downloads what it needs.
177
+ name: "All of the npm cache",
178
+ mode: "max",
179
+ paths: ["~/.npm/_cacache"],
180
+ skip: () => missing("npm"),
181
+ run: "npm cache clean --force",
182
+ },
183
+ {
184
+ // Comes back: the next `uv` / `uvx` run downloads what it needs.
185
+ name: "uv cache",
186
+ mode: "max",
187
+ skip: () => missing("uv"),
188
+ run: "uv cache clean",
189
+ },
190
+ {
191
+ // Comes back: Homebrew downloads again only to reinstall or upgrade.
192
+ name: "Homebrew downloads and old versions",
193
+ mode: "max",
194
+ skip: () => missing("brew"),
195
+ run: "brew cleanup --prune=all",
196
+ },
197
+ ];