@cbartens/bkit 5.4.0 → 5.5.1

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 (125) hide show
  1. package/.bkit/README.md +19 -7
  2. package/.bkit/core/.agents/rules.md +24 -9
  3. package/.bkit/core/.bkit/README.md +18 -6
  4. package/.bkit/core/.bkit/cloud.md +46 -15
  5. package/.bkit/core/.bkit/comparison.md +2 -2
  6. package/.bkit/core/.bkit/install.md +19 -18
  7. package/.bkit/core/.bkit/pipeline.md +3 -1
  8. package/.bkit/core/.bkit/prompts.md +38 -20
  9. package/.bkit/core/.bkit/providers.md +6 -6
  10. package/.bkit/core/.bkit/templates.md +44 -13
  11. package/.bkit/core/.bkit/trackers.md +99 -35
  12. package/.bkit/core/.bkit/workflows.md +50 -45
  13. package/.bkit/core/AGENTS.md +2 -2
  14. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  15. package/.bkit/core/docs/templates/bkit-audit-issues.md +22 -6
  16. package/.bkit/core/engine/checks/after/auth.ts +88 -45
  17. package/.bkit/core/engine/checks/after/ci-yml.ts +0 -1
  18. package/.bkit/core/engine/checks/after/github.ts +42 -78
  19. package/.bkit/core/engine/checks/after/index.ts +1 -6
  20. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  21. package/.bkit/core/engine/checks/before/env.ts +28 -18
  22. package/.bkit/core/engine/checks/before/mcp.ts +4 -2
  23. package/.bkit/core/engine/checks/tips/catalogue.ts +15 -2
  24. package/.bkit/core/engine/checks/tips/index.ts +5 -2
  25. package/.bkit/core/engine/cli.ts +7 -5
  26. package/.bkit/core/engine/commands/ci/ci.ts +107 -0
  27. package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
  28. package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
  29. package/.bkit/core/engine/commands/workflow/issues.ts +61 -63
  30. package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
  31. package/.bkit/core/engine/commands/workflow/prs.ts +3 -1
  32. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  33. package/.bkit/core/engine/commands/workflow/roadmap.ts +5 -1
  34. package/.bkit/core/engine/commands/workflow/steps.ts +2 -2
  35. package/.bkit/core/engine/commands/workflow/workflows.ts +9 -4
  36. package/.bkit/core/engine/commands/workflow/worktrees.ts +91 -14
  37. package/.bkit/core/engine/install/manifest.ts +31 -10
  38. package/.bkit/core/engine/install/modules/cloud.ts +3 -1
  39. package/.bkit/core/engine/install/modules/core.ts +153 -4
  40. package/.bkit/core/engine/install/modules/opencode.ts +5 -0
  41. package/.bkit/core/engine/install/write.ts +37 -1
  42. package/.bkit/core/engine/render/trackers.ts +35 -23
  43. package/.bkit/core/engine/shared/egress.ts +6 -0
  44. package/.bkit/core/engine/shared/settings.ts +130 -11
  45. package/.bkit/core/hooks/guardrails-tiers.js +1 -1
  46. package/.bkit/core/prompts/bkit-audit-generate.md +42 -12
  47. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  48. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  49. package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
  50. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  51. package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -0
  52. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  53. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
  54. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  55. package/.bkit/core/prompts/bkit-design-generate.md +4 -1
  56. package/.bkit/core/prompts/bkit-plan-generate.md +5 -3
  57. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  58. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  59. package/.bkit/core/prompts/bkit-utility-update-decisions.md +3 -1
  60. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +3 -1
  61. package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
  62. package/.bkit/core/prompts/bkit-utility-update-failures.md +3 -1
  63. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +3 -1
  64. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +9 -2
  65. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
  66. package/.bkit/core/workflows/bkit-auto.md +19 -6
  67. package/.bkit/core/workflows/bkit-build.md +59 -17
  68. package/.bkit/core/workflows/bkit-debug.md +64 -20
  69. package/.bkit/core/workflows/bkit-design.md +83 -28
  70. package/.bkit/core/workflows/bkit-plan.md +61 -20
  71. package/.bkit/core/workflows/bkit-ship.md +48 -18
  72. package/.bkit/shared/.bkit/.env.example +8 -0
  73. package/.bkit/shared/.claude/settings.json +3 -1
  74. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  75. package/.bkit/shared/.cursor/mcp.json +11 -4
  76. package/.bkit/shared/.mcp.json +11 -4
  77. package/.bkit/shared/.opencode/opencode.json +2 -0
  78. package/.bkit/shared/docs/deployments.md +6 -7
  79. package/.bkit/shared/docs/security.md +1 -1
  80. package/.bkit/shared/docs/testing.md +13 -5
  81. package/.bkit/templates/.github/renovate.json5 +1 -1
  82. package/.bkit/templates/.github/workflows/bkit-ci.yml +21 -115
  83. package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
  84. package/.bkit/templates/.husky/pre-commit +4 -4
  85. package/.bkit/templates/.husky/pre-push +107 -18
  86. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  87. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  88. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  89. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  90. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  91. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  92. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
  93. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  94. package/CHANGELOG.md +67 -1
  95. package/README.md +16 -6
  96. package/dist/checks/after/auth.js +81 -45
  97. package/dist/checks/after/ci-yml.js +0 -1
  98. package/dist/checks/after/github.js +41 -76
  99. package/dist/checks/after/index.js +2 -7
  100. package/dist/checks/after/tools.js +1 -1
  101. package/dist/checks/before/env.js +24 -17
  102. package/dist/checks/before/mcp.js +4 -2
  103. package/dist/checks/tips/catalogue.js +14 -2
  104. package/dist/checks/tips/index.js +4 -2
  105. package/dist/cli.js +7 -5
  106. package/dist/commands/ci/ci.js +100 -0
  107. package/dist/commands/install/uninstall.js +42 -0
  108. package/dist/commands/workflow/fids.js +22 -15
  109. package/dist/commands/workflow/issues.js +53 -61
  110. package/dist/commands/workflow/ledgers.js +26 -11
  111. package/dist/commands/workflow/prs.js +3 -1
  112. package/dist/commands/workflow/repo.js +6 -0
  113. package/dist/commands/workflow/roadmap.js +3 -1
  114. package/dist/commands/workflow/steps.js +2 -2
  115. package/dist/commands/workflow/workflows.js +9 -4
  116. package/dist/commands/workflow/worktrees.js +74 -13
  117. package/dist/install/manifest.js +30 -10
  118. package/dist/install/modules/cloud.js +3 -1
  119. package/dist/install/modules/core.js +157 -5
  120. package/dist/install/modules/opencode.js +6 -0
  121. package/dist/install/write.js +26 -2
  122. package/dist/render/trackers.js +34 -20
  123. package/dist/shared/egress.js +6 -0
  124. package/dist/shared/settings.js +59 -7
  125. package/package.json +14 -3
@@ -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,79 @@ 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
+
121
+ # Fast blocking checks run BEFORE the gates: each reads only git and the tree, so a failure
122
+ # stops the push in seconds instead of after the full gate. Paste fast repo extras that can
123
+ # block (seconds to ~30s, needing nothing the gates build) here too. Slow extras go below
124
+ # the gates.
125
+ #
126
+ # bkit mirror-drift gate — fails if `.agents/*` was edited without `bkit install`
127
+ # regenerating the `.claude/*`/`.cursor/*` mirrors (same check CI runs).
128
+ # Outside the gate scripts: it validates the bkit install, not your source.
129
+ # Fix: `pnpm bkit install`, stage the regenerated files, commit, push.
130
+ pnpm bkit check < /dev/null
131
+
132
+ # Slop base on a dev push — the commit CI's slop scan compares against: the head of the last
133
+ # green CI push run on dev, else origin/dev (scripts/ci/lanes/resolve-push-base.mjs, the
134
+ # script CI's planner runs, in local mode). Exported as SLOP_BASE_REF, which `bkit ci slop`
135
+ # reads, so a finding a red push already landed on dev fails here as it does in CI. Other
136
+ # branches keep the merge-base default. Skipped until scripts/ci/lanes/ holds the script.
137
+ if [ -n "$PUSH_DEV_SHA" ] && [ -f scripts/ci/lanes/resolve-push-base.mjs ]; then
138
+ PUSH_BASE_SOURCE_FILE=$(mktemp)
139
+ CI_PUSH_BASE=$(SOURCE_FILE="$PUSH_BASE_SOURCE_FILE" node scripts/ci/lanes/resolve-push-base.mjs \
140
+ --local --branch=dev --head="$PUSH_DEV_SHA" < /dev/null || echo "")
141
+ CI_PUSH_BASE_SOURCE=$(cat "$PUSH_BASE_SOURCE_FILE" 2>/dev/null || echo "unknown")
142
+ rm -f "$PUSH_BASE_SOURCE_FILE"
143
+ case "$CI_PUSH_BASE_SOURCE" in
144
+ *failed*)
145
+ echo "[pre-push] WARNING: could not read CI's last green run on dev (reason above)." >&2
146
+ echo "[pre-push] Slop compares against origin/dev, not CI's base: a finding an earlier red" >&2
147
+ echo "[pre-push] push landed passes here and still reds CI. Fix gh (gh auth status), push again." >&2
148
+ ;;
149
+ esac
150
+ if [ -n "$CI_PUSH_BASE" ]; then
151
+ export SLOP_BASE_REF="$CI_PUSH_BASE"
152
+ echo "[pre-push] slop base: $CI_PUSH_BASE ($CI_PUSH_BASE_SOURCE) — the base CI uses" >&2
153
+ else
154
+ echo "[pre-push] WARNING: no slop base resolved ($CI_PUSH_BASE_SOURCE) — slop uses its merge-base default" >&2
155
+ fi
156
+ fi
157
+
158
+ # Capability register (graphify, .bkit/templates.md § graphify) — blocks a push to dev when
159
+ # docs/capabilities.md is not what the pushed commit builds (~30s); warn-only on other
160
+ # branches. Skipped until scripts/graphify/ holds the script, and on a min push: it changes
161
+ # no source the register is built from.
162
+ if [ "$MIN_PUSH" != "1" ] && [ -f scripts/graphify/bkit-graph-pre-push.sh ]; then
163
+ PUSH_DEV_SHA="$PUSH_DEV_SHA" IS_REVERT="$IS_REVERT" bash scripts/graphify/bkit-graph-pre-push.sh < /dev/null
164
+ fi
165
+
81
166
  # tmp/ prune — deletes files under tmp/ untouched for 7+ days. Not a gate: a failed
82
167
  # prune warns and the push goes on. Skipped until scripts/cleanup/ holds the script.
83
168
  if [ -f scripts/cleanup/bkit-tmp-prune.mjs ]; then
@@ -87,20 +172,24 @@ fi
87
172
 
88
173
  # WHAT each gate runs lives in package.json, not here — the same `bkit:gate*` scripts
89
174
  # the bkit agent workflows and prompts dispatch through. Edit the scripts, not this
90
- # 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
175
+ # hook. Fast repo extras go ABOVE, with `bkit check`; slow ones BELOW.
176
+ # Min push: `bkit:gate:min` only. Revert path drops the suite only: prose
177
+ # and slop:delta still run. Otherwise the deepest push gate package.json declares.
178
+ if [ "$MIN_PUSH" = "1" ]; then
179
+ echo "[pre-push] min push — bkit:gate:min instead of the full gate" >&2
180
+ pnpm bkit:gate:min < /dev/null
181
+ elif [ "$IS_REVERT" = "1" ]; then
93
182
  echo "[pre-push] revert branch/commit detected — skipping the test suite"
94
183
  pnpm bkit:gate:static < /dev/null
184
+ elif grep -q '"bkit:gate:static-unit-integration"[[:space:]]*:' package.json 2>/dev/null; then
185
+ pnpm bkit:gate:static-unit-integration < /dev/null
95
186
  else
96
187
  pnpm bkit:gate:static-unit < /dev/null
97
188
  fi
98
189
 
99
- # bkit mirror-drift gate — fails fast if `.agents/*` was edited without `bkit install`
100
- # regenerating the `.claude/*`/`.cursor/*` mirrors (same check CI runs).
101
- # Outside the gate scripts: it validates the bkit install, not your source.
102
- # Fix: `pnpm bkit install`, stage the regenerated files, commit, push.
103
- pnpm bkit check < /dev/null
190
+ # Slow repo extras go here, above the disk prune. Ones that need Docker, a database or a
191
+ # build skip a min push:
192
+ # if [ "$MIN_PUSH" != "1" ]; then pnpm <slow-script> < /dev/null; fi
104
193
 
105
194
  # disk prune — keep this block last, so it runs only once every gate above passed. Starts
106
195
  # your max cleanup steps (`bkit disk prune`, .bkit/templates.md § Disk prune) in the
@@ -0,0 +1,194 @@
1
+ #!/bin/bash
2
+ # Example. Copy into scripts/ci/ and own it.
3
+ # bkit install does not write this file and does not overwrite a copy.
4
+ #
5
+ # bkit-local-stack-lock.sh — one run at a time on a local stack every checkout shares.
6
+ #
7
+ # . scripts/ci/bkit-local-stack-lock.sh
8
+ # take_local_stack_lock "<who>" || exit 1 # waits while another run holds it
9
+ # try_local_stack_lock "<who>" # returns 1 at once while another run holds it
10
+ # release_local_stack_lock # optional: the lock frees itself when the caller exits
11
+ #
12
+ # bash scripts/ci/bkit-local-stack-lock.sh run "<who>" -- <command> [args…] # package.json
13
+ #
14
+ # WHY. Agents work in several worktrees of one repo at once, and every worktree talks to the
15
+ # SAME local services: a Docker database, an emulator, anything whose container names and ports
16
+ # come from the repo's config. Nothing stops two worktrees using them at once, so a database
17
+ # reset from one wipes the data under a test run in another, and a dev server that stops "its"
18
+ # stack on exit stops it under someone else's run. Both show up as test failures nobody caused.
19
+ # A run that starts, resets or stops the stack, or tests against it, takes this lock first; a
20
+ # second run waits and says who it is waiting for.
21
+ #
22
+ # Wiring:
23
+ # - package.json: wrap each script that starts, resets or stops the stack, e.g.
24
+ # "db:reset": "bash scripts/ci/bkit-local-stack-lock.sh run db:reset -- <your reset command>"
25
+ # - local runners that test against the stack: source this file and call take_local_stack_lock
26
+ # before the first command that touches the stack.
27
+ # - fix hints and docs name those scripts, never the raw command, which skips the lock.
28
+ #
29
+ # The lock is named after the stack: BKIT_LOCAL_STACK when set, otherwise the folder name of the
30
+ # repo's main checkout, so every worktree of one repo finds the same lock. A throwaway stack with
31
+ # names and ports of its own sets BKIT_LOCAL_STACK to its own name and never waits on the shared
32
+ # one. The lock file sits outside the checkout: ~/.cache/bkit/local-stack-lock/<name>.lock
33
+ # ($XDG_CACHE_HOME when set). A small perl process holds it (flock) and exits within a second of
34
+ # the caller exiting, however the caller ends (its parent changes), so a killed run cannot leave
35
+ # a stale lock behind. perl by its full path, so a PATH shim cannot stand in for it.
36
+ #
37
+ # A runner started by a runner that holds the lock (LOCAL_STACK_LOCK_OWNER, exported on success)
38
+ # does not wait on its own parent. Safe under a caller's `set -e`. CI (CI=true or CI=1): no-op,
39
+ # as a CI runner has one job and its own Docker. LOCAL_STACK_LOCK_WAIT_S (default 3600) caps
40
+ # the wait. Needs bash and /usr/bin/perl (macOS and Linux ship both).
41
+
42
+ _LOCAL_STACK_LOCK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
43
+ _LOCAL_STACK_LOCK_ROOT="$(git -C "$_LOCAL_STACK_LOCK_DIR" rev-parse --show-toplevel 2>/dev/null || echo "$_LOCAL_STACK_LOCK_DIR")"
44
+ LOCAL_STACK_LOCK_PID=""
45
+
46
+ # The stack's name: BKIT_LOCAL_STACK, else the main checkout's folder name, the same from every
47
+ # worktree. Characters outside A-Z a-z 0-9 . _ - become _.
48
+ local_stack_lock_name() {
49
+ _lsl_name="${BKIT_LOCAL_STACK:-}"
50
+ if [ -z "$_lsl_name" ]; then
51
+ _lsl_common="$(git -C "$_LOCAL_STACK_LOCK_DIR" rev-parse --path-format=absolute --git-common-dir 2>/dev/null)" || return 1
52
+ [ -n "$_lsl_common" ] || return 1
53
+ case "$(basename "$_lsl_common")" in
54
+ .git) _lsl_name="$(basename "$(dirname "$_lsl_common")")" ;;
55
+ *) _lsl_name="$(basename "$_lsl_common" .git)" ;;
56
+ esac
57
+ fi
58
+ printf '%s\n' "$_lsl_name" | LC_ALL=C tr -c 'A-Za-z0-9._\n-' '_'
59
+ }
60
+
61
+ # The lock file for the stack this checkout uses.
62
+ local_stack_lock_file() {
63
+ _lsl_stack="$(local_stack_lock_name)" || return 1
64
+ echo "${XDG_CACHE_HOME:-$HOME/.cache}/bkit/local-stack-lock/${_lsl_stack}.lock"
65
+ }
66
+
67
+ # "<who> — <checkout> (pid N, since HH:MM:SS)" for the run holding the lock, or nothing.
68
+ local_stack_lock_holder() {
69
+ _lsl_held="$(local_stack_lock_file)" || return 0
70
+ cat "${_lsl_held}.holder" 2>/dev/null
71
+ return 0
72
+ }
73
+
74
+ _local_stack_lock() {
75
+ _lsl_mode="$1"
76
+ _lsl_who="$2"
77
+ if [ "${CI:-}" = "true" ] || [ "${CI:-}" = "1" ]; then return 0; fi
78
+ if [ -n "${LOCAL_STACK_LOCK_OWNER:-}" ] && kill -0 "$LOCAL_STACK_LOCK_OWNER" 2>/dev/null; then return 0; fi
79
+ if [ -n "$LOCAL_STACK_LOCK_PID" ] && kill -0 "$LOCAL_STACK_LOCK_PID" 2>/dev/null; then return 0; fi
80
+
81
+ if ! _lsl_file="$(local_stack_lock_file)"; then
82
+ echo "[local-stack-lock] ❌ cannot name the local stack: run inside a git checkout, or set BKIT_LOCAL_STACK" >&2
83
+ return 1
84
+ fi
85
+ _lsl_label="$(basename "$_lsl_file" .lock)"
86
+ if [ ! -x /usr/bin/perl ]; then
87
+ echo "[local-stack-lock] ❌ could not take the lock for the local stack $_lsl_label: /usr/bin/perl not found" >&2
88
+ return 1
89
+ fi
90
+ mkdir -p "$(dirname "$_lsl_file")" || return 1
91
+ _lsl_fifo="$(mktemp -u "${TMPDIR:-/tmp}/local-stack-lock.XXXXXX")"
92
+ mkfifo "$_lsl_fifo" || return 1
93
+
94
+ # The holder answers on the fifo once: ok, busy <holder>, timeout <holder> or error <why>.
95
+ /usr/bin/perl -e '
96
+ use strict;
97
+ use Fcntl qw(:flock);
98
+ use POSIX qw(strftime);
99
+ my ($file, $owner, $who, $checkout, $fifo, $wait_s, $mode, $label) = @ARGV;
100
+ # The caller is the parent of this process. When it exits, this process goes to init (or a
101
+ # subreaper) at once, while `kill 0` would still find it until whoever started it reaps it.
102
+ my $parent = getppid();
103
+ my $caller_alive = sub { getppid() == $parent };
104
+ open(my $out, ">", $fifo) or exit 1;
105
+ $out->autoflush(1);
106
+ my $holder = sub { open(my $h, "<", "$file.holder") or return "another run"; my $l = <$h>; chomp $l; $l };
107
+ my $lock;
108
+ open($lock, ">>", $file) or do { print $out "error cannot open $file: $!\n"; exit 1 };
109
+ my $start = time;
110
+ my $next_note = 0;
111
+ until (flock($lock, LOCK_EX | LOCK_NB)) {
112
+ exit 0 unless $caller_alive->();
113
+ if ($mode eq "try") { print $out "busy " . $holder->() . "\n"; exit 0 }
114
+ if (time - $start >= $wait_s) { print $out "timeout " . $holder->() . "\n"; exit 0 }
115
+ if (time >= $next_note) {
116
+ my $m = int((time - $start) / 60);
117
+ my $so_far = $m ? " (still, $m min so far)" : "";
118
+ print STDERR "[local-stack-lock] ⏳ $who is waiting for the local stack $label$so_far: in use by " . $holder->() . "\n";
119
+ $next_note = time + 60;
120
+ }
121
+ sleep 1;
122
+ }
123
+ $SIG{TERM} = $SIG{INT} = $SIG{HUP} = sub { unlink "$file.holder"; exit 0 };
124
+ if (open(my $h, ">", "$file.holder")) {
125
+ print $h "$who — $checkout (pid $owner, since " . strftime("%H:%M:%S", localtime) . ")\n";
126
+ close $h;
127
+ }
128
+ print $out "ok\n";
129
+ close $out;
130
+ sleep 1 while $caller_alive->();
131
+ unlink "$file.holder";
132
+ ' "$_lsl_file" "$$" "$_lsl_who" "$_LOCAL_STACK_LOCK_ROOT" "$_lsl_fifo" "${LOCAL_STACK_LOCK_WAIT_S:-3600}" "$_lsl_mode" "$_lsl_label" </dev/null >/dev/null &
133
+ _lsl_pid=$!
134
+ # The fifo is opened read-write, so the read never blocks on a holder that died before it
135
+ # answered (a failed fork under load, a killed perl): the loop stops once it is gone.
136
+ _lsl_reply="$(
137
+ exec 3<>"$_lsl_fifo"
138
+ while :; do
139
+ if IFS= read -r -t 1 _lsl_line <&3; then
140
+ printf '%s' "$_lsl_line"
141
+ break
142
+ fi
143
+ kill -0 "$_lsl_pid" 2>/dev/null || break
144
+ done
145
+ )" || true
146
+ rm -f "$_lsl_fifo"
147
+
148
+ case "$_lsl_reply" in
149
+ ok)
150
+ LOCAL_STACK_LOCK_PID="$_lsl_pid"
151
+ export LOCAL_STACK_LOCK_OWNER="$$"
152
+ return 0
153
+ ;;
154
+ busy\ *)
155
+ echo "[local-stack-lock] the local stack $_lsl_label is in use by ${_lsl_reply#busy }" >&2
156
+ ;;
157
+ timeout\ *)
158
+ echo "[local-stack-lock] ❌ $_lsl_who gave up after ${LOCAL_STACK_LOCK_WAIT_S:-3600}s waiting for the local stack $_lsl_label, in use by ${_lsl_reply#timeout }" >&2
159
+ echo "[local-stack-lock] Let that run finish, or stop it. LOCAL_STACK_LOCK_WAIT_S sets how long to wait." >&2
160
+ ;;
161
+ "")
162
+ echo "[local-stack-lock] ❌ could not take the lock for the local stack $_lsl_label: the perl process holding it stopped before it answered" >&2
163
+ ;;
164
+ *)
165
+ echo "[local-stack-lock] ❌ could not take the lock for the local stack $_lsl_label: ${_lsl_reply#error }" >&2
166
+ ;;
167
+ esac
168
+ wait "$_lsl_pid" 2>/dev/null || true
169
+ return 1
170
+ }
171
+
172
+ take_local_stack_lock() { _local_stack_lock wait "$1"; }
173
+ try_local_stack_lock() { _local_stack_lock try "$1"; }
174
+
175
+ release_local_stack_lock() {
176
+ [ -n "$LOCAL_STACK_LOCK_PID" ] || return 0
177
+ kill "$LOCAL_STACK_LOCK_PID" 2>/dev/null || true
178
+ wait "$LOCAL_STACK_LOCK_PID" 2>/dev/null || true
179
+ LOCAL_STACK_LOCK_PID=""
180
+ unset LOCAL_STACK_LOCK_OWNER
181
+ return 0
182
+ }
183
+
184
+ if [ "${BASH_SOURCE[0]}" = "$0" ]; then
185
+ if [ "${1:-}" != "run" ] || [ -z "${2:-}" ]; then
186
+ echo "usage: bash scripts/ci/bkit-local-stack-lock.sh run \"<who>\" -- <command> [args…]" >&2
187
+ exit 2
188
+ fi
189
+ _lsl_run_who="$2"
190
+ shift 2
191
+ [ "${1:-}" = "--" ] && shift
192
+ take_local_stack_lock "$_lsl_run_who" || exit 1
193
+ "$@"
194
+ fi
@@ -12,8 +12,7 @@
12
12
  * - the plan does not parse (not JSON, not an object, or no `run_level`),
13
13
  * - the planner job (`SCOPE_RESULT`) did not succeed,
14
14
  * - no lane is named, or a lane's result was never wired in.
15
- * It asserts nothing for a lane that `<LANE>_CACHE_SKIP=true` marks as proven on a cached
16
- * SHA, and nothing about a skipped lane when `run_level` is `none`.
15
+ * It asserts nothing about a skipped lane when `run_level` is `none`.
17
16
  *
18
17
  * Environment:
19
18
  * LANES comma-separated lane names, e.g. `static,unit`. The job named
@@ -23,7 +22,6 @@
23
22
  * <LANE>_RAN `needs.<job>.outputs.tests_ran`. Setting the variable (even empty)
24
23
  * makes the lane counted: it must report a number above 0. A lane
25
24
  * with no such variable is not count-checked.
26
- * <LANE>_CACHE_SKIP `needs.<job>.outputs.cache_skip`; `true` skips the count check.
27
25
  * PLAN optional planner JSON (`needs.bkit-tests-scope.outputs.plan`). Unset
28
26
  * means every listed lane is expected to run. Set, it must parse and
29
27
  * carry a `run_level`; `none` expects every lane to be skipped.
@@ -128,7 +126,7 @@ export function checkCapstone(env) {
128
126
 
129
127
  const ranKey = `${prefix}_RAN`;
130
128
  const counted = Object.hasOwn(env, ranKey);
131
- if (!counted || env[`${prefix}_CACHE_SKIP`] === "true") {
129
+ if (!counted) {
132
130
  parts.push(`${lane}=${result}`);
133
131
  continue;
134
132
  }
@@ -39,7 +39,6 @@ const base = (extra = {}) => ({
39
39
  STATIC_RESULT: "success",
40
40
  UNIT_RESULT: "success",
41
41
  UNIT_RAN: "12",
42
- UNIT_CACHE_SKIP: "",
43
42
  ...extra,
44
43
  });
45
44
 
@@ -51,10 +50,8 @@ const planned = (extra = {}) => ({
51
50
  STATIC_RESULT: "success",
52
51
  UNIT_RESULT: "success",
53
52
  UNIT_RAN: "12",
54
- UNIT_CACHE_SKIP: "false",
55
53
  INTEGRATION_RESULT: "success",
56
54
  INTEGRATION_RAN: "4",
57
- INTEGRATION_CACHE_SKIP: "false",
58
55
  ...extra,
59
56
  });
60
57
 
@@ -64,10 +61,8 @@ const skipPlan = (extra = {}) =>
64
61
  STATIC_RESULT: "skipped",
65
62
  UNIT_RESULT: "skipped",
66
63
  UNIT_RAN: "",
67
- UNIT_CACHE_SKIP: "",
68
64
  INTEGRATION_RESULT: "skipped",
69
65
  INTEGRATION_RAN: "",
70
- INTEGRATION_CACHE_SKIP: "",
71
66
  ...extra,
72
67
  });
73
68
 
@@ -215,19 +210,9 @@ test("an unparseable plan never lets a skipped lane pass as 'nothing planned'",
215
210
 
216
211
  // ── the exemptions ──────────────────────────────────────────────────────────
217
212
 
218
- test("cache_skip=true asserts no count", () => {
219
- greens(base({ UNIT_CACHE_SKIP: "true", UNIT_RAN: "" }));
220
- greens(base({ UNIT_CACHE_SKIP: "true", UNIT_RAN: "0" }));
221
- greens(planned({ INTEGRATION_CACHE_SKIP: "true", INTEGRATION_RAN: "0" }));
222
- });
223
-
224
- test("cache_skip=true does not excuse a failed lane", () => {
225
- reds(base({ UNIT_RESULT: "failure", UNIT_CACHE_SKIP: "true" }), "result=failure");
226
- });
227
-
228
- test("only the exact string 'true' is a cache skip", () => {
229
- reds(base({ UNIT_CACHE_SKIP: "yes", UNIT_RAN: "0" }), "0 tests");
230
- reds(base({ UNIT_CACHE_SKIP: "TRUE", UNIT_RAN: "0" }), "0 tests");
213
+ test("a <LANE>_CACHE_SKIP variable excuses no count", () => {
214
+ reds(base({ UNIT_CACHE_SKIP: "true", UNIT_RAN: "0" }), "0 tests");
215
+ reds(planned({ INTEGRATION_CACHE_SKIP: "true", INTEGRATION_RAN: "0" }), "0 tests");
231
216
  });
232
217
 
233
218
  test("EMPTY_COUNT=warn turns an unreported count into a warning, not a failure", () => {
@@ -262,12 +247,8 @@ test("a hyphenated lane reads <LANE>_ variables with underscores", () => {
262
247
  LANES: "e2e-web",
263
248
  E2E_WEB_RESULT: "success",
264
249
  E2E_WEB_RAN: "3",
265
- E2E_WEB_CACHE_SKIP: "",
266
250
  });
267
- reds(
268
- { LANES: "e2e-web", E2E_WEB_RESULT: "success", E2E_WEB_RAN: "0", E2E_WEB_CACHE_SKIP: "" },
269
- "bkit-tests-e2e-web",
270
- );
251
+ reds({ LANES: "e2e-web", E2E_WEB_RESULT: "success", E2E_WEB_RAN: "0" }, "bkit-tests-e2e-web");
271
252
  });
272
253
 
273
254
  test("lane names tolerate spaces around the commas", () => {
@@ -12,10 +12,19 @@
12
12
  * is not an ancestor of HEAD (a force-push rewrote the branch), the base falls back to
13
13
  * `event.before`.
14
14
  *
15
+ * Local mode gives the pre-push hook the same base, so a local slop scan compares against the
16
+ * commit CI's does: the repo comes from `git remote get-url origin`, `origin/<branch>` stands
17
+ * in for `event.before`, and ancestry is tested against the pushed commit (`--head`), which is
18
+ * not always the checked-out one. gh uses its own login.
19
+ *
15
20
  * Usage: node scripts/ci/lanes/resolve-push-base.mjs
16
21
  * (env: GH_TOKEN, REPO, BRANCH, BEFORE_SHA, WORKFLOW_FILE; optional SOURCE_FILE)
17
- * Output: the base SHA on stdout; the chosen source (`last-green-run`, `event-before`, ...) on
18
- * stderr, and in SOURCE_FILE when that env var names a file. Exit 0 always — every
22
+ * node scripts/ci/lanes/resolve-push-base.mjs --local --branch=dev --head=<pushed sha>
23
+ * (env: optional WORKFLOW_FILE, SOURCE_FILE)
24
+ * Output: the base SHA on stdout; the chosen source (`last-green-run`, `event-before`, ...;
25
+ * `origin/<branch>` in place of `event-before` in local mode) on stderr, and in
26
+ * SOURCE_FILE when that env var names a file. A source ending `(run lookup failed)` or
27
+ * `(resolver failed)` means the run list could not be read. Exit 0 always — every
19
28
  * failure (gh, git, unparseable output) falls back to `event.before`, itself a valid base.
20
29
  */
21
30
 
@@ -26,15 +35,42 @@ import { pathToFileURL } from "node:url";
26
35
  /** The workflow whose runs establish the base. Set WORKFLOW_FILE if your CI file has another name. */
27
36
  export const WORKFLOW_FILE = process.env.WORKFLOW_FILE || "bkit-ci.yml";
28
37
 
29
- /** Pure decision. `isAncestor(sha)` answers whether `sha` is an ancestor of HEAD. */
30
- export function choosePushBase({ lastGreenSha, beforeSha, isAncestor }) {
38
+ /**
39
+ * Pure decision. `isAncestor(sha)` answers whether `sha` is an ancestor of the pushed commit.
40
+ * `fallback` names the before-sha in the source (`event-before`, or `origin/<branch>` locally);
41
+ * `lookupFailed` marks a run list that could not be read.
42
+ */
43
+ export function choosePushBase({
44
+ lastGreenSha,
45
+ beforeSha,
46
+ isAncestor,
47
+ fallback = "event-before",
48
+ lookupFailed = false,
49
+ }) {
31
50
  if (lastGreenSha && isAncestor(lastGreenSha)) {
32
51
  return { base: lastGreenSha, source: "last-green-run" };
33
52
  }
34
- return {
35
- base: beforeSha ?? "",
36
- source: lastGreenSha ? "event-before (last green run is not an ancestor)" : "event-before",
37
- };
53
+ let source = fallback;
54
+ if (lookupFailed) source = `${fallback} (run lookup failed)`;
55
+ else if (lastGreenSha) source = `${fallback} (last green run is not an ancestor)`;
56
+ return { base: beforeSha ?? "", source };
57
+ }
58
+
59
+ /** `owner/repo` from a GitHub remote URL (https, ssh, scp-style), or "" when it has no such path. */
60
+ export function repoFromRemoteUrl(url) {
61
+ const match = /[/:]([^/:\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(String(url ?? "").trim());
62
+ return match ? `${match[1]}/${match[2]}` : "";
63
+ }
64
+
65
+ /** `--local`, `--branch=`, `--head=` from argv; anything else is ignored. */
66
+ export function parseArgs(argv) {
67
+ const args = { local: false, branch: "", head: "" };
68
+ for (const arg of argv) {
69
+ if (arg === "--local") args.local = true;
70
+ else if (arg.startsWith("--branch=")) args.branch = arg.slice("--branch=".length);
71
+ else if (arg.startsWith("--head=")) args.head = arg.slice("--head=".length);
72
+ }
73
+ return args;
38
74
  }
39
75
 
40
76
  /** How far back the run lookup reaches. A green run older than this falls back to event.before. */
@@ -53,7 +89,8 @@ export function newestRunSha(runs) {
53
89
  return newest ? newest.head_sha : "";
54
90
  }
55
91
 
56
- function lastGreenPushSha(repo, branch, now = new Date()) {
92
+ /** `{ sha, failed }`: the newest green push run's head, and whether the run list was unreadable. */
93
+ function lastGreenPushSha(repo, branch, fallbackName, now = new Date()) {
57
94
  const since = new Date(now.getTime() - LOOKBACK_DAYS * 86_400_000).toISOString().slice(0, 10);
58
95
  const path =
59
96
  `repos/${repo}/actions/workflows/${WORKFLOW_FILE}/runs` +
@@ -69,17 +106,17 @@ function lastGreenPushSha(repo, branch, now = new Date()) {
69
106
  if (error || status !== 0) {
70
107
  const reason = error ? error.message : String(stderr).split("\n")[0];
71
108
  console.error(
72
- `[resolve-push-base] could not list ${WORKFLOW_FILE} runs (${reason}) — using event.before`,
109
+ `[resolve-push-base] could not list ${WORKFLOW_FILE} runs (${reason}) — using ${fallbackName}`,
73
110
  );
74
- return "";
111
+ return { sha: "", failed: true };
75
112
  }
76
113
  // Unparseable output throws; main() catches it and falls back to event.before.
77
- return newestRunSha(JSON.parse(stdout || "[]"));
114
+ return { sha: newestRunSha(JSON.parse(stdout || "[]")), failed: false };
78
115
  }
79
116
 
80
- /** True only when `sha` is an ancestor of HEAD; any git failure is "not an ancestor" (logged). */
81
- function isAncestorOfHead(sha) {
82
- const { status, error } = spawnSync("git", ["merge-base", "--is-ancestor", sha, "HEAD"], {
117
+ /** True only when `sha` is an ancestor of `head`; any git failure is "not an ancestor" (logged). */
118
+ function isAncestorOf(sha, head, fallbackName) {
119
+ const { status, error } = spawnSync("git", ["merge-base", "--is-ancestor", sha, head], {
83
120
  stdio: "ignore",
84
121
  });
85
122
  // 0 = ancestor. 1 = not an ancestor. 128 = the SHA is not in this clone (a force-push dropped
@@ -88,22 +125,64 @@ function isAncestorOfHead(sha) {
88
125
  if (!error && (status === 1 || status === 128)) return false;
89
126
  const reason = error ? error.message : `git exited ${status}`;
90
127
  console.error(
91
- `[resolve-push-base] cannot test ancestry of ${sha} (${reason}) — using event.before`,
128
+ `[resolve-push-base] cannot test ancestry of ${sha} (${reason}) — using ${fallbackName}`,
92
129
  );
93
130
  return false;
94
131
  }
95
132
 
96
- export function main(env) {
133
+ /** stdout of a git command, or "" when it fails. */
134
+ function gitOut(args) {
135
+ const { status, stdout, error } = spawnSync("git", args, {
136
+ encoding: "utf8",
137
+ stdio: ["ignore", "pipe", "ignore"],
138
+ });
139
+ return !error && status === 0 ? stdout.trim() : "";
140
+ }
141
+
142
+ /**
143
+ * The resolver's inputs. CI: env vars, ancestry against HEAD. Local (`--local`): repo from
144
+ * origin's URL, before-sha from `origin/<branch>`, ancestry against `--head`.
145
+ */
146
+ export function resolveInputs(env, argv) {
147
+ const args = parseArgs(argv);
148
+ if (!args.local) {
149
+ return {
150
+ repo: env.REPO,
151
+ branch: env.BRANCH,
152
+ beforeSha: env.BEFORE_SHA,
153
+ head: "HEAD",
154
+ fallback: "event-before",
155
+ fallbackName: "event.before",
156
+ };
157
+ }
158
+ const branch = args.branch || "dev";
159
+ return {
160
+ repo: repoFromRemoteUrl(gitOut(["remote", "get-url", "origin"])),
161
+ branch,
162
+ beforeSha: gitOut(["rev-parse", "--verify", "--quiet", `origin/${branch}^{commit}`]),
163
+ head: args.head || "HEAD",
164
+ fallback: `origin/${branch}`,
165
+ fallbackName: `origin/${branch}`,
166
+ };
167
+ }
168
+
169
+ export function main(env, argv = []) {
170
+ const input = resolveInputs(env, argv);
97
171
  let result;
98
172
  try {
173
+ const lastGreen = lastGreenPushSha(input.repo, input.branch, input.fallbackName);
99
174
  result = choosePushBase({
100
- lastGreenSha: lastGreenPushSha(env.REPO, env.BRANCH),
101
- beforeSha: env.BEFORE_SHA,
102
- isAncestor: isAncestorOfHead,
175
+ lastGreenSha: lastGreen.sha,
176
+ beforeSha: input.beforeSha,
177
+ isAncestor: (sha) => isAncestorOf(sha, input.head, input.fallbackName),
178
+ fallback: input.fallback,
179
+ lookupFailed: lastGreen.failed,
103
180
  });
104
181
  } catch (err) {
105
- console.error(`[resolve-push-base] unexpected failure (${err.message}) — using event.before`);
106
- result = { base: env.BEFORE_SHA ?? "", source: "event-before (resolver failed)" };
182
+ console.error(
183
+ `[resolve-push-base] unexpected failure (${err.message}) — using ${input.fallbackName}`,
184
+ );
185
+ result = { base: input.beforeSha ?? "", source: `${input.fallback} (resolver failed)` };
107
186
  }
108
187
  const { base, source } = result;
109
188
  console.error(`[resolve-push-base] base=${base || "(none)"} source=${source}`);
@@ -116,4 +195,6 @@ export function main(env) {
116
195
  }
117
196
  }
118
197
 
119
- if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) main(process.env);
198
+ if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
199
+ main(process.env, process.argv.slice(2));
200
+ }