@1aboveio/engineering-skills 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (233) hide show
  1. package/README.md +28 -2
  2. package/package.json +33 -4
  3. package/skills/better-review/LICENSE +3 -0
  4. package/skills/better-review/SKILL.md +249 -0
  5. package/skills/better-review/agents/openai.yaml +9 -0
  6. package/skills/better-review/references/domain-hazards.md +53 -0
  7. package/skills/better-review/references/passes.md +147 -0
  8. package/skills/better-review/references/result.md +151 -0
  9. package/skills/better-review/release-check.mjs +93 -0
  10. package/skills/better-review/scripts/pr-context.mjs +212 -0
  11. package/skills/better-review/scripts/pr-context.test.mjs +168 -0
  12. package/skills/better-review/scripts/rereview-scope.mjs +503 -0
  13. package/skills/better-review/scripts/rereview-scope.test.mjs +587 -0
  14. package/skills/better-review/scripts/scan-diff.mjs +365 -0
  15. package/skills/better-review/scripts/scan-diff.test.mjs +414 -0
  16. package/skills/better-review/scripts/vendor-sync.test.mjs +96 -0
  17. package/skills/e2e-test/LICENSE +3 -0
  18. package/skills/e2e-test/SKILL.md +98 -0
  19. package/skills/e2e-test/assets/ci-gates.cloudbuild.yaml +24 -0
  20. package/skills/e2e-test/references/authoring/auth-flows.md +159 -0
  21. package/skills/e2e-test/references/authoring/playwright-config.md +73 -0
  22. package/skills/e2e-test/references/authoring/playwright-patterns.md +144 -0
  23. package/skills/e2e-test/references/ci-integration.md +25 -0
  24. package/skills/e2e-test/references/ci-playwright-container.md +290 -0
  25. package/skills/e2e-test/references/presentation-sweep.md +104 -0
  26. package/skills/e2e-test/references/reviewing.md +41 -0
  27. package/skills/e2e-test/references/route-manifest.md +51 -0
  28. package/skills/e2e-test/release-check.mjs +93 -0
  29. package/skills/e2e-test/scripts/detect-routes-nextjs.mjs +200 -0
  30. package/skills/e2e-test/scripts/presentation-checks.mjs +171 -0
  31. package/skills/e2e-test/scripts/presentation-checks.test.mjs +106 -0
  32. package/skills/e2e-test/scripts/presentation-perceivability.mjs +179 -0
  33. package/skills/e2e-test/scripts/presentation-perceivability.test.mjs +117 -0
  34. package/skills/e2e-test/scripts/presentation-reachability.mjs +154 -0
  35. package/skills/e2e-test/scripts/presentation-reachability.test.mjs +69 -0
  36. package/skills/e2e-test/scripts/presentation-render-health.mjs +141 -0
  37. package/skills/e2e-test/scripts/presentation-render-health.test.mjs +98 -0
  38. package/skills/e2e-test/scripts/presentation-sweep.mjs +147 -0
  39. package/skills/e2e-test/scripts/presentation-sweep.test.mjs +71 -0
  40. package/skills/e2e-test/scripts/presentation-temporal.mjs +127 -0
  41. package/skills/e2e-test/scripts/presentation-temporal.test.mjs +59 -0
  42. package/skills/e2e-test/scripts/project-route-manifest.mjs +82 -0
  43. package/skills/e2e-test/scripts/project-route-manifest.test.mjs +76 -0
  44. package/skills/e2e-test/scripts/validate-manifest.mjs +106 -0
  45. package/skills/engineering-runtime/LICENSE +3 -0
  46. package/skills/engineering-runtime/SKILL.md +11 -0
  47. package/skills/engineering-runtime/agents/openai.yaml +6 -0
  48. package/skills/engineering-runtime/coherence/workflow.json +597 -0
  49. package/skills/engineering-runtime/engineering-runtime.test.mjs +68 -0
  50. package/skills/engineering-runtime/release-check.mjs +93 -0
  51. package/skills/engineering-runtime/scripts/exact-head-artifact.mjs +131 -0
  52. package/skills/engineering-runtime/scripts/head-check-set.mjs +398 -0
  53. package/skills/engineering-runtime/scripts/invocation-policy.mjs +187 -0
  54. package/skills/engineering-runtime/scripts/invocation-policy.test.mjs +95 -0
  55. package/skills/engineering-runtime/scripts/main-module.mjs +79 -0
  56. package/skills/engineering-runtime/scripts/main-module.test.mjs +288 -0
  57. package/skills/engineering-runtime/scripts/mergify-yaml.mjs +11 -0
  58. package/skills/engineering-runtime/scripts/package-lock.json +43 -0
  59. package/skills/engineering-runtime/scripts/package.json +10 -0
  60. package/skills/engineering-runtime/scripts/required-check-plan.mjs +223 -0
  61. package/skills/engineering-runtime/scripts/required-check-plan.test.mjs +96 -0
  62. package/skills/engineering-runtime/scripts/review-completion.mjs +56 -0
  63. package/skills/engineering-runtime/scripts/workflow-coherence.mjs +595 -0
  64. package/skills/engineering-runtime/scripts/workflow-policy.mjs +189 -0
  65. package/skills/engineering-runtime/scripts/yaml-mapping.mjs +18 -0
  66. package/skills/ensure-coverage/LICENSE +3 -0
  67. package/skills/ensure-coverage/SKILL.md +129 -0
  68. package/skills/ensure-coverage/references/breadth/coverage-ledger.md +92 -0
  69. package/skills/ensure-coverage/references/breadth/inventory-contract.md +85 -0
  70. package/skills/ensure-coverage/references/breadth/surface-baseline.md +44 -0
  71. package/skills/ensure-coverage/references/breadth/surface-discovery.md +16 -0
  72. package/skills/ensure-coverage/references/depth/characterization.md +68 -0
  73. package/skills/ensure-coverage/references/depth/coverage.config.example.json +19 -0
  74. package/skills/ensure-coverage/references/depth/grading.md +35 -0
  75. package/skills/ensure-coverage/references/depth/mock-policy.md +57 -0
  76. package/skills/ensure-coverage/references/depth/test-smells.md +39 -0
  77. package/skills/ensure-coverage/references/enforcement/ci-contract.md +44 -0
  78. package/skills/ensure-coverage/references/examples/coverage-ledger.md +110 -0
  79. package/skills/ensure-coverage/references/examples/refund-flow.md +35 -0
  80. package/skills/ensure-coverage/references/presentation/axis.md +64 -0
  81. package/skills/ensure-coverage/references/process/audit-mode.md +27 -0
  82. package/skills/ensure-coverage/references/process/output-template.md +139 -0
  83. package/skills/ensure-coverage/references/process/test-strategy.md +56 -0
  84. package/skills/ensure-coverage/release-check.mjs +93 -0
  85. package/skills/ensure-coverage/schemas/coverage-config.schema.json +67 -0
  86. package/skills/ensure-coverage/schemas/coverage-file.schema.json +140 -0
  87. package/skills/ensure-coverage/scripts/README.md +99 -0
  88. package/skills/ensure-coverage/scripts/adapters/nextjs-inventory.mjs +182 -0
  89. package/skills/ensure-coverage/scripts/adapters/nextjs-inventory.test.mjs +96 -0
  90. package/skills/ensure-coverage/scripts/check-quarantine-expiry.mjs +105 -0
  91. package/skills/ensure-coverage/scripts/check-quarantine-expiry.test.mjs +47 -0
  92. package/skills/ensure-coverage/scripts/ci-audit.mjs +137 -0
  93. package/skills/ensure-coverage/scripts/ci-audit.test.mjs +86 -0
  94. package/skills/ensure-coverage/scripts/coverage-ledger.mjs +674 -0
  95. package/skills/ensure-coverage/scripts/coverage-ledger.test.mjs +447 -0
  96. package/skills/ensure-coverage/scripts/design-parity.mjs +591 -0
  97. package/skills/ensure-coverage/scripts/design-parity.test.mjs +552 -0
  98. package/skills/ensure-coverage/scripts/lint-tests.mjs +282 -0
  99. package/skills/ensure-coverage/scripts/lint-tests.test.mjs +289 -0
  100. package/skills/ensure-coverage/scripts/mock-policy-config.mjs +176 -0
  101. package/skills/ensure-coverage/scripts/mock-policy-config.test.mjs +119 -0
  102. package/skills/ensure-coverage/scripts/package.json +19 -0
  103. package/skills/golden-path/LICENSE +3 -0
  104. package/skills/golden-path/SKILL.md +230 -0
  105. package/skills/golden-path/agents/openai.yaml +3 -0
  106. package/skills/golden-path/assets/golden-paths.example.json +57 -0
  107. package/skills/golden-path/references/contract.md +239 -0
  108. package/skills/golden-path/references/migration.md +111 -0
  109. package/skills/golden-path/release-check.mjs +93 -0
  110. package/skills/golden-path/scripts/golden-path-core.mjs +1779 -0
  111. package/skills/golden-path/scripts/golden-path.mjs +6 -0
  112. package/skills/golden-path/scripts/golden-path.test.mjs +1457 -0
  113. package/skills/harness-runtime/LICENSE +3 -0
  114. package/skills/harness-runtime/SKILL.md +19 -0
  115. package/skills/harness-runtime/agents/openai.yaml +6 -0
  116. package/skills/harness-runtime/bin/discover-models.mjs +4 -0
  117. package/skills/harness-runtime/bin/model-catalog.mjs +4 -0
  118. package/skills/harness-runtime/contracts.md +15 -0
  119. package/skills/harness-runtime/discover-models.mjs +392 -0
  120. package/skills/harness-runtime/discover-models.test.mjs +363 -0
  121. package/skills/harness-runtime/fixtures/native-question-schemas.json +33 -0
  122. package/skills/harness-runtime/fixtures/question-responses.json +54 -0
  123. package/skills/harness-runtime/harness-runtime.test.mjs +967 -0
  124. package/skills/harness-runtime/index.mjs +767 -0
  125. package/skills/harness-runtime/model-catalog-seed.test.mjs +829 -0
  126. package/skills/harness-runtime/model-catalog.mjs +787 -0
  127. package/skills/harness-runtime/model-catalog.test.mjs +366 -0
  128. package/skills/harness-runtime/native-question-contracts.md +37 -0
  129. package/skills/harness-runtime/references/model-catalog-seed.json +408 -0
  130. package/skills/harness-runtime/references/model-catalog.md +57 -0
  131. package/skills/harness-runtime/release-check.mjs +93 -0
  132. package/skills/resolve-issues/LICENSE +3 -0
  133. package/skills/resolve-issues/SKILL.md +250 -0
  134. package/skills/resolve-issues/agents/openai.yaml +9 -0
  135. package/skills/resolve-issues/plugin-hooks.json +17 -0
  136. package/skills/resolve-issues/references/canary.md +28 -0
  137. package/skills/resolve-issues/references/ci.md +105 -0
  138. package/skills/resolve-issues/references/done.md +25 -0
  139. package/skills/resolve-issues/references/dropbox.md +90 -0
  140. package/skills/resolve-issues/references/expire.md +318 -0
  141. package/skills/resolve-issues/references/exploration.md +202 -0
  142. package/skills/resolve-issues/references/implementation.md +303 -0
  143. package/skills/resolve-issues/references/preflight.md +445 -0
  144. package/skills/resolve-issues/references/review.md +228 -0
  145. package/skills/resolve-issues/references/shared-modules.md +44 -0
  146. package/skills/resolve-issues/references/task-plan.md +264 -0
  147. package/skills/resolve-issues/release-check.mjs +93 -0
  148. package/skills/resolve-issues/scripts/cleanup-runs.mjs +364 -0
  149. package/skills/resolve-issues/scripts/cleanup-runs.test.mjs +280 -0
  150. package/skills/resolve-issues/scripts/discover-models.mjs +9 -0
  151. package/skills/resolve-issues/scripts/dropbox.mjs +473 -0
  152. package/skills/resolve-issues/scripts/dropbox.test.mjs +346 -0
  153. package/skills/resolve-issues/scripts/findings-reuse.mjs +98 -0
  154. package/skills/resolve-issues/scripts/findings-reuse.test.mjs +88 -0
  155. package/skills/resolve-issues/scripts/github-reviews.mjs +384 -0
  156. package/skills/resolve-issues/scripts/github-reviews.test.mjs +264 -0
  157. package/skills/resolve-issues/scripts/install-hooks.mjs +135 -0
  158. package/skills/resolve-issues/scripts/install-hooks.test.mjs +79 -0
  159. package/skills/resolve-issues/scripts/issue-tree.mjs +162 -0
  160. package/skills/resolve-issues/scripts/issue-tree.test.mjs +107 -0
  161. package/skills/resolve-issues/scripts/manual-invocation.test.mjs +14 -0
  162. package/skills/resolve-issues/scripts/model-catalog.mjs +9 -0
  163. package/skills/resolve-issues/scripts/next-actions-capacity.test.mjs +149 -0
  164. package/skills/resolve-issues/scripts/next-actions.mjs +856 -0
  165. package/skills/resolve-issues/scripts/next-actions.test.mjs +915 -0
  166. package/skills/resolve-issues/scripts/plan-sync.mjs +269 -0
  167. package/skills/resolve-issues/scripts/plan-sync.test.mjs +156 -0
  168. package/skills/resolve-issues/scripts/preflight-models.mjs +736 -0
  169. package/skills/resolve-issues/scripts/preflight-models.test.mjs +448 -0
  170. package/skills/resolve-issues/scripts/ready-check.mjs +185 -0
  171. package/skills/resolve-issues/scripts/ready-check.test.mjs +217 -0
  172. package/skills/resolve-issues/scripts/rehydrate.mjs +98 -0
  173. package/skills/resolve-issues/scripts/rehydrate.test.mjs +91 -0
  174. package/skills/resolve-issues/scripts/review-verdict.mjs +509 -0
  175. package/skills/resolve-issues/scripts/review-verdict.test.mjs +1060 -0
  176. package/skills/resolve-issues/scripts/size-check.mjs +492 -0
  177. package/skills/resolve-issues/scripts/size-check.test.mjs +458 -0
  178. package/skills/resolve-release/LICENSE +3 -0
  179. package/skills/resolve-release/SKILL.md +215 -0
  180. package/skills/resolve-release/agents/openai.yaml +8 -0
  181. package/skills/resolve-release/flows/cloud-run-canary.md +13 -0
  182. package/skills/resolve-release/flows/cloud-run.md +7 -0
  183. package/skills/resolve-release/flows/root-tag-npm.md +13 -0
  184. package/skills/resolve-release/flows/workspace-npm.md +22 -0
  185. package/skills/resolve-release/references/canary.md +51 -0
  186. package/skills/resolve-release/references/candidate.md +41 -0
  187. package/skills/resolve-release/references/cut.md +131 -0
  188. package/skills/resolve-release/references/dark-launch.md +66 -0
  189. package/skills/resolve-release/references/flows.md +150 -0
  190. package/skills/resolve-release/references/preflight.md +154 -0
  191. package/skills/resolve-release/references/prepared-metadata.md +260 -0
  192. package/skills/resolve-release/references/promotion.md +82 -0
  193. package/skills/resolve-release/references/publish.md +232 -0
  194. package/skills/resolve-release/references/workspace-npm.md +103 -0
  195. package/skills/resolve-release/release-check.mjs +93 -0
  196. package/skills/resolve-release/scripts/apply.mjs +212 -0
  197. package/skills/resolve-release/scripts/apply.test.mjs +99 -0
  198. package/skills/resolve-release/scripts/dark-flags.mjs +134 -0
  199. package/skills/resolve-release/scripts/dark-flags.test.mjs +100 -0
  200. package/skills/resolve-release/scripts/flow.mjs +500 -0
  201. package/skills/resolve-release/scripts/flow.test.mjs +340 -0
  202. package/skills/resolve-release/scripts/green-head.mjs +231 -0
  203. package/skills/resolve-release/scripts/green-head.test.mjs +101 -0
  204. package/skills/resolve-release/scripts/npm-version-absence.mjs +138 -0
  205. package/skills/resolve-release/scripts/npm-version-absence.test.mjs +426 -0
  206. package/skills/resolve-release/scripts/plan-npm.test.mjs +659 -0
  207. package/skills/resolve-release/scripts/plan-toml-boundary.test.mjs +317 -0
  208. package/skills/resolve-release/scripts/plan-uv.test.mjs +291 -0
  209. package/skills/resolve-release/scripts/plan.mjs +806 -0
  210. package/skills/resolve-release/scripts/plan.test.mjs +428 -0
  211. package/skills/rush-issues/LICENSE +3 -0
  212. package/skills/rush-issues/SKILL.md +58 -0
  213. package/skills/rush-issues/agents/openai.yaml +8 -0
  214. package/skills/rush-issues/rehydrate.mjs +10 -0
  215. package/skills/rush-issues/release-check.mjs +93 -0
  216. package/skills/rush-release/LICENSE +3 -0
  217. package/skills/rush-release/SKILL.md +35 -0
  218. package/skills/rush-release/agents/openai.yaml +8 -0
  219. package/skills/rush-release/release-check.mjs +93 -0
  220. package/skills/test-quality/LICENSE +3 -0
  221. package/skills/test-quality/SKILL.md +79 -0
  222. package/skills/test-quality/references/audit.md +80 -0
  223. package/skills/test-quality/references/lint.md +24 -0
  224. package/skills/test-quality/references/principles.md +143 -0
  225. package/skills/test-quality/references/testing-conventions.md +9 -0
  226. package/skills/test-quality/release-check.mjs +93 -0
  227. package/skills/test-quality/scripts/lint-tests.mjs +574 -0
  228. package/skills/test-quality/scripts/lint-tests.test.mjs +591 -0
  229. package/skills/test-quality/scripts/mock-policy-config.mjs +176 -0
  230. package/skills/test-quality/scripts/mock-policy-config.test.mjs +119 -0
  231. package/skills/test-quality/scripts/persist-conventions-core.mjs +116 -0
  232. package/skills/test-quality/scripts/persist-conventions.mjs +17 -0
  233. package/skills/test-quality/scripts/persist-conventions.test.mjs +104 -0
@@ -0,0 +1,340 @@
1
+ import { test } from 'node:test'
2
+ import assert from 'node:assert/strict'
3
+ import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
4
+ import { tmpdir } from 'node:os'
5
+ import { join } from 'node:path'
6
+ import { spawnSync } from 'node:child_process'
7
+ import { listPredefined, loadFlow, renderFlow, resolveChoices, validateFlow } from './flow.mjs'
8
+
9
+ const SCRIPT = join(import.meta.dirname, 'flow.mjs')
10
+
11
+ // The variation pi-better-harness releases with: package-scoped dispatch publishing, no traffic.
12
+ const WORKSPACE_FLOW = `---
13
+ route: workspace-npm
14
+ publisher:
15
+ workflow: publish.yml
16
+ input: package
17
+ ownsTags: true
18
+ packages:
19
+ exclude: [pi-better-read-aloud, navigator, sandbox-core]
20
+ publishLast: [pi-better-harness]
21
+ changelog: package-scoped
22
+ registry: https://registry.npmjs.org/
23
+ ask:
24
+ - id: bundle-bump
25
+ question: Should pi-better-harness bundle the new component versions?
26
+ options: [yes, no]
27
+ exposure: n/a
28
+ dark: n/a
29
+ ---
30
+
31
+ # Release flow
32
+
33
+ ## before-cut
34
+
35
+ - \`npm run verify\`
36
+ - \`npm publish --dry-run -w <workspace> --registry=<registry>\` for each package
37
+
38
+ ## after-publish
39
+
40
+ - \`npm view <pkg> version --registry=<registry>\` prints the planned version
41
+ - \`pi install npm:<pkg>\` succeeds
42
+
43
+ ## hand-back-if
44
+
45
+ - a planned package has never been published on npm
46
+ (a first publish needs a human npm login)
47
+ `
48
+
49
+ const CANARY_FLOW = `---
50
+ route: cloud-run
51
+ exposure: canary
52
+ canary:
53
+ steps: [10, 50]
54
+ holdMinutes: 15
55
+ healthCheck: npm run release:health -- --url {candidateUrl}
56
+ dark: on
57
+ flagRegistry: config/flags.json
58
+ required: [canary]
59
+ ---
60
+ `
61
+
62
+ const flow = (text) => {
63
+ const result = validateFlow(text)
64
+ assert.deepEqual(result.errors, [])
65
+ return result
66
+ }
67
+
68
+ function run(cwd, args, input) {
69
+ return spawnSync('node', [SCRIPT, ...args], { cwd, encoding: 'utf8', input })
70
+ }
71
+
72
+ function project(text) {
73
+ const cwd = mkdtempSync(join(tmpdir(), 'resolve-release-flow-'))
74
+ if (text !== undefined) {
75
+ mkdirSync(join(cwd, '.release'))
76
+ writeFileSync(join(cwd, '.release', 'flow.md'), text)
77
+ }
78
+ return cwd
79
+ }
80
+
81
+ test('a workspace-npm flow fills slots and lists its steps per stage', () => {
82
+ const result = flow(WORKSPACE_FLOW)
83
+ assert.equal(result.settings.route, 'workspace-npm')
84
+ assert.deepEqual(result.settings.packages.publishLast, ['pi-better-harness'])
85
+ assert.equal(result.steps['before-cut'].length, 2)
86
+ assert.deepEqual(result.steps['hand-back-if'], ['a planned package has never been published on npm (a first publish needs a human npm login)'])
87
+ assert.match(result.sha256, /^[0-9a-f]{64}$/)
88
+ assert.notEqual(validateFlow(`${WORKSPACE_FLOW}\n`).sha256, result.sha256, 'any byte change is a different flow')
89
+ })
90
+
91
+ test('a flow cannot reshape the skeleton, the invocation policy, or invent slots', () => {
92
+ const cases = [
93
+ ['---\ntrunk: develop\n---\n', /release skeleton/],
94
+ ['---\ndisable-model-invocation: false\n---\n', /manual-only/],
95
+ ['---\nconfirm: true\n---\n', /release skeleton/],
96
+ ['---\nrolloutSpeed: fast\n---\n', /unknown setting "rolloutSpeed"/],
97
+ ['---\nroute: gitflow\n---\n', /route must be one of/],
98
+ ['---\n---\n## deploy-first\n- x\n', /unknown section "## deploy-first"/],
99
+ ['---\n---\n## before-cut\nrun the checks\n', /only "- " steps/],
100
+ ['# no frontmatter\n', /starts with a --- frontmatter/],
101
+ ['---\nroute: workspace-npm\nexposure: canary\ncanary: {steps: [10], holdMinutes: 5, healthCheck: x}\n---\n', /only to route cloud-run/],
102
+ ['---\nexposure: canary\n---\n', /needs a canary block/],
103
+ ['---\ncanary: {steps: [50, 10], holdMinutes: 5, healthCheck: x}\n---\n', /strictly increase/],
104
+ ['---\ncanary: {steps: [10, 100], holdMinutes: 5, healthCheck: x}\n---\n', /between 1 and 99/],
105
+ ['---\ndark: on\n---\n', /dark on needs flagRegistry/],
106
+ ['---\nrequired: [canary]\n---\n', /required canary needs exposure canary/],
107
+ ['---\nrequired: [speed]\n---\n', /required lists only canary/],
108
+ ['---\nask:\n - {id: exposure, question: Q}\n---\n', /built-in choice/],
109
+ ['---\nask:\n - {id: tier, question: Q, options: [a, b], default: c}\n---\n', /default must be one of its options/],
110
+ ['---\nregistry: http://registry.npmjs.org/\n---\n', /https:\/\//],
111
+ ['---\npackages: {exclude: [a]}\nroute: root-tag\n---\n', /only to route workspace-npm/],
112
+ ]
113
+ for (const [text, pattern] of cases) {
114
+ const result = validateFlow(text)
115
+ assert.equal(result.valid, false, text)
116
+ assert.ok(result.errors.some((error) => pattern.test(error)), `${text}\n→ ${result.errors.join('; ')}`)
117
+ }
118
+ })
119
+
120
+ test('shortcut mode with no flow is the unchanged rush-release: full, off, no questions', () => {
121
+ const result = resolveChoices({ mode: 'shortcut' })
122
+ assert.deepEqual(result.choices, { exposure: 'full', dark: 'off', canary: null, flagRegistry: null, ask: {} })
123
+ assert.deepEqual(result.questions, [])
124
+ assert.deepEqual(result.refusals, [])
125
+ })
126
+
127
+ test('shortcut mode never asks: flow defaults answer, and anything it cannot answer refuses', () => {
128
+ const withDefault = flow(WORKSPACE_FLOW.replace('options: [yes, no]', 'options: [yes, no]\n default: no'))
129
+ const answered = resolveChoices({ mode: 'shortcut', flow: withDefault })
130
+ assert.deepEqual(answered.choices.ask, { 'bundle-bump': 'no' })
131
+ assert.equal(answered.choices.exposure, 'n/a')
132
+ assert.deepEqual(answered.questions, [])
133
+ assert.deepEqual(answered.refusals, [])
134
+
135
+ const noDefault = resolveChoices({ mode: 'shortcut', flow: flow(WORKSPACE_FLOW) })
136
+ assert.match(noDefault.refusals.join('\n'), /no default; rush-release never asks/)
137
+
138
+ const required = resolveChoices({ mode: 'shortcut', flow: flow(CANARY_FLOW) })
139
+ assert.match(required.refusals.join('\n'), /requires canary; rush-release cannot provide it/)
140
+ assert.equal(required.choices.exposure, 'full', 'the shortcut never takes the flow canary')
141
+
142
+ const option = resolveChoices({ mode: 'shortcut', invocation: { exposure: 'canary' } })
143
+ assert.match(option.refusals.join('\n'), /accepts no exposure option; use \/resolve-release/)
144
+ })
145
+
146
+ test('full mode asks exposure and dark, suggesting what the repository declares', () => {
147
+ const bare = resolveChoices({ mode: 'full' })
148
+ assert.deepEqual(bare.questions.map((q) => [q.id, q.default]), [['exposure', 'full'], ['dark', 'off']])
149
+ const hinted = resolveChoices({ mode: 'full', repo: { canary: true, flagRegistry: true } })
150
+ assert.deepEqual(hinted.questions.map((q) => [q.id, q.default]), [['exposure', 'canary'], ['dark', 'on']])
151
+ })
152
+
153
+ test('full mode asks canary details only once canary is chosen, then resolves', () => {
154
+ const chosen = resolveChoices({ mode: 'full', answers: { exposure: 'canary', dark: 'off' }, invocation: { healthCheck: 'npm run health' } })
155
+ assert.deepEqual(chosen.questions.map((q) => q.id), ['canarySteps', 'holdMinutes'])
156
+ const done = resolveChoices({
157
+ mode: 'full',
158
+ answers: { exposure: 'canary', dark: 'off', canarySteps: '5,25,50', holdMinutes: '10' },
159
+ invocation: { healthCheck: 'npm run health' },
160
+ })
161
+ assert.deepEqual(done.questions, [])
162
+ assert.deepEqual(done.refusals, [])
163
+ assert.deepEqual(done.choices.canary, { steps: [5, 25, 50], holdMinutes: 10, healthCheck: 'npm run health' })
164
+
165
+ const noHealth = resolveChoices({ mode: 'full', answers: { exposure: 'canary', dark: 'off', canarySteps: '10', holdMinutes: '5' } })
166
+ assert.match(noHealth.refusals.join('\n'), /repository-declared health check/)
167
+ })
168
+
169
+ test('precedence: invocation over flow over preflight answer', () => {
170
+ const canaryFlow = flow(CANARY_FLOW.replace('required: [canary]\n', ''))
171
+ const fromFlow = resolveChoices({ mode: 'full', flow: canaryFlow, answers: { exposure: 'full', dark: 'off' } })
172
+ assert.equal(fromFlow.choices.exposure, 'canary')
173
+ assert.equal(fromFlow.sources.exposure, 'flow')
174
+ assert.equal(fromFlow.choices.dark, 'on')
175
+ assert.equal(fromFlow.choices.flagRegistry, 'config/flags.json')
176
+ assert.deepEqual(fromFlow.questions, [])
177
+
178
+ const overridden = resolveChoices({ mode: 'full', flow: canaryFlow, invocation: { exposure: 'full', dark: 'off' } })
179
+ assert.equal(overridden.choices.exposure, 'full')
180
+ assert.equal(overridden.sources.exposure, 'invocation')
181
+ assert.equal(overridden.choices.canary, null)
182
+
183
+ const requiredFlow = resolveChoices({ mode: 'full', flow: flow(CANARY_FLOW), invocation: { exposure: 'full' } })
184
+ assert.match(requiredFlow.refusals.join('\n'), /requires canary exposure/)
185
+
186
+ const notApplicable = resolveChoices({ mode: 'full', flow: flow(WORKSPACE_FLOW), invocation: { exposure: 'canary' } })
187
+ assert.match(notApplicable.refusals.join('\n'), /marks exposure n\/a/)
188
+ })
189
+
190
+ test('full mode asks flow questions and checks answers against their options', () => {
191
+ const asked = resolveChoices({ mode: 'full', flow: flow(WORKSPACE_FLOW) })
192
+ assert.deepEqual(asked.questions.map((q) => q.id), ['bundle-bump'])
193
+ const answered = resolveChoices({ mode: 'full', flow: flow(WORKSPACE_FLOW), answers: { 'bundle-bump': 'yes' } })
194
+ assert.deepEqual(answered.choices.ask, { 'bundle-bump': 'yes' })
195
+ const wrong = resolveChoices({ mode: 'full', flow: flow(WORKSPACE_FLOW), answers: { 'bundle-bump': 'maybe' } })
196
+ assert.match(wrong.refusals.join('\n'), /bundle-bump must be one of yes, no/)
197
+ })
198
+
199
+ test('the CLI exit code says resolved, questions pending, refused, or invalid', () => {
200
+ assert.equal(run(project(), ['resolve', '--mode', 'shortcut', '--json']).status, 0)
201
+ const pending = run(project(), ['resolve', '--mode', 'full', '--json'])
202
+ assert.equal(pending.status, 4)
203
+ assert.equal(JSON.parse(pending.stdout).flow, null)
204
+ assert.equal(run(project(CANARY_FLOW), ['resolve', '--mode', 'shortcut']).status, 3)
205
+ const invalid = run(project('---\ntrunk: develop\n---\n'), ['resolve', '--mode', 'shortcut'])
206
+ assert.equal(invalid.status, 1)
207
+ assert.match(invalid.stdout, /release skeleton/)
208
+ const resolved = run(project(CANARY_FLOW), ['resolve', '--mode', 'full', '--json'])
209
+ assert.equal(resolved.status, 0, resolved.stdout)
210
+ assert.equal(JSON.parse(resolved.stdout).flow.sha256, validateFlow(CANARY_FLOW).sha256)
211
+ assert.equal(run(project(), ['validate']).stdout.trim(), 'no project flow at .release/flow.md')
212
+ assert.equal(run(project(), ['resolve']).status, 2)
213
+ })
214
+
215
+ test('saving a flow records the choices and keeps every existing slot and step', () => {
216
+ const cwd = project(WORKSPACE_FLOW.replace('exposure: n/a\ndark: n/a\n', ''))
217
+ const existing = loadFlow('.release/flow.md', { cwd })
218
+ const text = renderFlow({ choices: { exposure: 'full', dark: 'off', canary: null, flagRegistry: null, ask: { 'bundle-bump': 'yes' } } }, existing)
219
+ const saved = flow(text)
220
+ assert.equal(saved.settings.exposure, 'full')
221
+ assert.equal(saved.settings.dark, 'off')
222
+ assert.equal(saved.settings.route, 'workspace-npm')
223
+ assert.deepEqual(saved.steps, existing.steps)
224
+ assert.doesNotMatch(text, /bundle-bump: yes/, 'per-release answers are asked again, not saved')
225
+
226
+ const piped = run(cwd, ['render'], JSON.stringify({ choices: { exposure: 'full', dark: 'off' } }))
227
+ assert.equal(piped.status, 0, piped.stderr)
228
+ assert.equal(validateFlow(piped.stdout).valid, true)
229
+ })
230
+
231
+ // The project half of a flow that starts from the skill's predefined workspace-npm flow.
232
+ const EXTENDING_FLOW = `---
233
+ extends: workspace-npm
234
+ publisher: { workflow: publish.yml, input: package, ownsTags: true }
235
+ packages:
236
+ exclude: [pi-better-read-aloud]
237
+ publishLast: [pi-better-harness]
238
+ ask:
239
+ - id: bundle-bump
240
+ question: Should pi-better-harness bundle the new component versions?
241
+ options: [yes, no]
242
+ ---
243
+
244
+ ## after-publish
245
+ - \`pi install npm:<pkg>\` succeeds
246
+ `
247
+
248
+ function predefinedDir(files) {
249
+ const dir = mkdtempSync(join(tmpdir(), 'resolve-release-flows-'))
250
+ for (const [name, text] of Object.entries(files)) writeFileSync(join(dir, `${name}.md`), text)
251
+ return dir
252
+ }
253
+
254
+ test('every predefined flow the skill ships is valid and describes itself', () => {
255
+ const flows = listPredefined()
256
+ assert.deepEqual(flows.map((flow) => flow.name), ['cloud-run', 'cloud-run-canary', 'root-tag-npm', 'workspace-npm'])
257
+ for (const flow of flows) {
258
+ assert.deepEqual(flow.errors, [], flow.name)
259
+ assert.ok(flow.description.length > 20, flow.name)
260
+ }
261
+ const listed = run(project(), ['list', '--json'])
262
+ assert.equal(listed.status, 0)
263
+ assert.equal(JSON.parse(listed.stdout).length, 4)
264
+ })
265
+
266
+ test('a project flow extends a predefined one: slots merge, base steps run first', () => {
267
+ const flow = loadFlow('.release/flow.md', { cwd: project(EXTENDING_FLOW) })
268
+ assert.deepEqual(flow.errors, [])
269
+ assert.equal(flow.base, 'workspace-npm')
270
+ assert.equal(flow.settings.route, 'workspace-npm', 'from the predefined flow')
271
+ assert.equal(flow.settings.registry, 'https://registry.npmjs.org/', 'from the predefined flow')
272
+ assert.equal(flow.settings.publisher.workflow, 'publish.yml', 'from the project')
273
+ assert.equal('extends' in flow.settings, false)
274
+ assert.equal(flow.steps['after-publish'].length, 2)
275
+ assert.match(flow.steps['after-publish'][0], /npm view/)
276
+ assert.match(flow.steps['after-publish'][1], /pi install/)
277
+ assert.equal(flow.steps['hand-back-if'].length, 1)
278
+ assert.equal(resolveChoices({ mode: 'shortcut', flow }).choices.exposure, 'n/a')
279
+ })
280
+
281
+ test('the effective hash covers both files, so a skill update to the base is a different flow', () => {
282
+ const cwd = project('---\nextends: base\nregistry: https://r.example/\n---\n')
283
+ const before = loadFlow('.release/flow.md', { cwd, dir: predefinedDir({ base: '---\ndescription: base flow for tests\n---\n' }) })
284
+ const after = loadFlow('.release/flow.md', { cwd, dir: predefinedDir({ base: '---\ndescription: base flow for tests, changed\n---\n' }) })
285
+ assert.equal(before.valid, true, before.errors.join('; '))
286
+ assert.notEqual(before.sha256, after.sha256)
287
+ })
288
+
289
+ test('extends must name a shipped flow, and a predefined flow cannot extend', () => {
290
+ const unknown = loadFlow('.release/flow.md', { cwd: project('---\nextends: gitflow\n---\n') })
291
+ assert.equal(unknown.valid, false)
292
+ assert.match(unknown.errors.join('\n'), /no predefined flow "gitflow"; available: cloud-run, cloud-run-canary/)
293
+ const dir = predefinedDir({ chained: '---\nextends: cloud-run\n---\n' })
294
+ assert.match(listPredefined(dir)[0].errors.join('\n'), /cannot extend another flow/)
295
+ })
296
+
297
+ test('cross-field rules apply to the merged flow', () => {
298
+ const canary = loadFlow('.release/flow.md', { cwd: project('---\nextends: cloud-run-canary\ncanary: { healthCheck: npm run health }\n---\n') })
299
+ assert.deepEqual(canary.errors, [])
300
+ assert.deepEqual(canary.settings.canary, { steps: [10, 50], holdMinutes: 15, healthCheck: 'npm run health' })
301
+ const full = resolveChoices({ mode: 'full', flow: canary, answers: { dark: 'off' } })
302
+ assert.deepEqual(full.refusals, [])
303
+ assert.equal(full.choices.canary.healthCheck, 'npm run health')
304
+
305
+ const noHealth = loadFlow('.release/flow.md', { cwd: project('---\nextends: cloud-run-canary\n---\n') })
306
+ assert.equal(noHealth.valid, true, 'the health check is a resolve-time requirement')
307
+ assert.match(resolveChoices({ mode: 'full', flow: noHealth, answers: { dark: 'off' } }).refusals.join('\n'), /health check/)
308
+
309
+ const mismatch = loadFlow('.release/flow.md', { cwd: project('---\nextends: root-tag-npm\nexposure: canary\ncanary: { steps: [10], holdMinutes: 5 }\n---\n') })
310
+ assert.equal(mismatch.valid, false)
311
+ assert.match(mismatch.errors.join('\n'), /\.release\/flow\.md \+ root-tag-npm: canary exposure applies only to route cloud-run/)
312
+ })
313
+
314
+ test('--flow picks a predefined flow only when the project has none', () => {
315
+ const picked = loadFlow('.release/flow.md', { cwd: project(), name: 'cloud-run-canary' })
316
+ assert.equal(picked.valid, true)
317
+ assert.equal(picked.path, null)
318
+ assert.equal(picked.base, 'cloud-run-canary')
319
+ const shortcut = resolveChoices({ mode: 'shortcut', flow: picked })
320
+ assert.equal(shortcut.choices.exposure, 'full', 'the shortcut never takes a canary it was not required to')
321
+ assert.deepEqual(shortcut.refusals, [])
322
+
323
+ const clash = run(project(EXTENDING_FLOW), ['validate', '--flow', 'cloud-run'])
324
+ assert.equal(clash.status, 1)
325
+ assert.match(clash.stdout, /project flow wins/)
326
+ assert.equal(run(project(), ['resolve', '--mode', 'full', '--flow', 'nope']).status, 1)
327
+ })
328
+
329
+ test('saving a flow that extends keeps only the project half', () => {
330
+ const cwd = project(EXTENDING_FLOW)
331
+ const text = renderFlow({ choices: { exposure: 'n/a', dark: 'off' } }, loadFlow('.release/flow.md', { cwd }))
332
+ assert.match(text, /^extends: workspace-npm$/m)
333
+ assert.doesNotMatch(text, /registry:/, 'base slots stay in the skill')
334
+ assert.equal((text.match(/npm view/g) || []).length, 0, 'base steps are not copied')
335
+ assert.match(text, /pi install/)
336
+ const fromPredefined = renderFlow({ choices: { exposure: 'canary', dark: 'off', canary: { steps: [10, 50], holdMinutes: 15, healthCheck: 'npm run health' } } },
337
+ loadFlow('.release/flow.md', { cwd: project(), name: 'cloud-run-canary' }))
338
+ assert.match(fromPredefined, /^extends: cloud-run-canary$/m)
339
+ assert.equal(loadFlow('.release/flow.md', { cwd: project(fromPredefined) }).valid, true)
340
+ })
@@ -0,0 +1,231 @@
1
+ #!/usr/bin/env node
2
+ // Newest first-parent SHA on trunk whose required CI is already green.
3
+ //
4
+ // Usage:
5
+ // node green-head.mjs [--trunk main] [--max 50] [--json]
6
+ //
7
+ // Exit: 0 found · 1 no green head / inspect failed · 2 usage
8
+ import { spawnSync } from 'node:child_process'
9
+ import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
10
+
11
+ export const DEFAULT_TRUNK = 'main'
12
+ export const DEFAULT_MAX = 50
13
+ const PASSING = new Set(['success', 'neutral', 'skipped'])
14
+ const FAILING = new Set(['failure', 'failed', 'error', 'timed_out', 'cancelled', 'action_required', 'stale', 'startup_failure'])
15
+
16
+ export function parseGithubRemote(url) {
17
+ const raw = String(url || '').trim()
18
+ const ssh = raw.match(/^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/)
19
+ if (ssh) return { owner: ssh[1], repo: ssh[2] }
20
+ const https = raw.match(/^https:\/\/github\.com\/([^/]+)\/(.+?)(?:\.git)?$/)
21
+ if (https) return { owner: https[1], repo: https[2] }
22
+ const sshUrl = raw.match(/^ssh:\/\/git@github\.com\/([^/]+)\/(.+?)(?:\.git)?$/)
23
+ if (sshUrl) return { owner: sshUrl[1], repo: sshUrl[2] }
24
+ return null
25
+ }
26
+
27
+ export function runGit(args, { cwd, allowFail = false } = {}) {
28
+ const result = spawnSync('git', args, { encoding: 'utf8', cwd })
29
+ if (result.status !== 0 && !allowFail) {
30
+ const err = new Error(result.stderr.trim() || `git ${args.join(' ')} failed`)
31
+ err.exitCode = 1
32
+ throw err
33
+ }
34
+ return result
35
+ }
36
+
37
+ export function ghApi(path, { cwd, paginate = false } = {}) {
38
+ const args = ['api', path]
39
+ if (paginate) args.push('--paginate', '--slurp')
40
+ const result = spawnSync('gh', args, { encoding: 'utf8', cwd })
41
+ if (result.status !== 0) {
42
+ const err = new Error(result.stderr.trim() || `gh api ${path} failed`)
43
+ err.exitCode = 1
44
+ err.status = result.status
45
+ throw err
46
+ }
47
+ return result.stdout ? JSON.parse(result.stdout) : null
48
+ }
49
+
50
+ export function requiredContexts(protection) {
51
+ if (!protection || typeof protection !== 'object') return []
52
+ const checks = protection.required_status_checks
53
+ if (!checks) return []
54
+ const names = []
55
+ for (const context of checks.contexts || []) names.push(String(context))
56
+ for (const check of checks.checks || []) {
57
+ if (check && check.context) names.push(String(check.context))
58
+ }
59
+ return [...new Set(names)]
60
+ }
61
+
62
+ function conclusionOf(run) {
63
+ return String(run?.conclusion || run?.status || '').toLowerCase()
64
+ }
65
+
66
+ export function inspectGreen({ status, checkRuns, required }) {
67
+ const runs = Array.isArray(checkRuns)
68
+ ? checkRuns.flatMap((page) => Array.isArray(page?.check_runs) ? page.check_runs : [page])
69
+ : checkRuns?.check_runs || []
70
+ const statuses = Array.isArray(status?.statuses) ? status.statuses : []
71
+ const state = String(status?.state || '').toLowerCase()
72
+ const byName = new Map()
73
+ for (const run of runs) {
74
+ const name = String(run.name || run.context || '')
75
+ if (name && !byName.has(name)) byName.set(name, run)
76
+ }
77
+
78
+ if (required.length > 0) {
79
+ const missing = []
80
+ const pending = []
81
+ const failed = []
82
+ for (const name of required) {
83
+ const run = byName.get(name)
84
+ const statusContext = statuses.find((item) => item.context === name)
85
+ const token = run ? conclusionOf(run) : String(statusContext?.state || '').toLowerCase()
86
+ if (!token) missing.push(name)
87
+ else if (token === 'pending' || token === 'queued' || token === 'in_progress') pending.push(name)
88
+ else if (FAILING.has(token)) failed.push(name)
89
+ else if (!PASSING.has(token) && token !== 'success') failed.push(name)
90
+ }
91
+ const green = missing.length === 0 && pending.length === 0 && failed.length === 0
92
+ return { green, missing, pending, failed, required: true }
93
+ }
94
+
95
+ const failedStatuses = statuses.filter((item) => FAILING.has(String(item?.state || '').toLowerCase()))
96
+ const pendingStatuses = statuses.filter((item) => ['pending', 'queued', 'in_progress', ''].includes(String(item?.state || '').toLowerCase()))
97
+ const passingStatuses = statuses.filter((item) => PASSING.has(String(item?.state || '').toLowerCase()))
98
+ if (state === 'failure' || state === 'error' || failedStatuses.length > 0) {
99
+ return { green: false, missing: [], pending: [], failed: ['combined-status'], required: false }
100
+ }
101
+ const pendingRuns = runs.filter((run) => {
102
+ const token = conclusionOf(run)
103
+ return token === 'pending' || token === 'queued' || token === 'in_progress' || token === ''
104
+ })
105
+ const failedRuns = runs.filter((run) => FAILING.has(conclusionOf(run)))
106
+ const passingRuns = runs.filter((run) => PASSING.has(conclusionOf(run)))
107
+ if (failedRuns.length > 0) {
108
+ return { green: false, missing: [], pending: [], failed: failedRuns.map((run) => run.name), required: false }
109
+ }
110
+ if (pendingRuns.length > 0 || pendingStatuses.length > 0) {
111
+ return {
112
+ green: false,
113
+ missing: [],
114
+ pending: [
115
+ ...pendingRuns.map((run) => run.name || 'check-run'),
116
+ ...pendingStatuses.map((item) => item.context || 'status-context'),
117
+ ],
118
+ failed: [],
119
+ required: false,
120
+ }
121
+ }
122
+ if (state === 'success' || passingRuns.length > 0 || passingStatuses.length > 0) {
123
+ return { green: true, missing: [], pending: [], failed: [], required: false }
124
+ }
125
+ return { green: false, missing: ['no-checks'], pending: [], failed: [], required: false }
126
+ }
127
+
128
+ export function pickGreenHead(shas, inspect) {
129
+ for (const sha of shas) {
130
+ const verdict = inspect(sha)
131
+ if (verdict.green) return { sha, verdict }
132
+ }
133
+ return null
134
+ }
135
+
136
+ function loadProtection(owner, repo, trunk, api) {
137
+ try {
138
+ return api(`repos/${owner}/${repo}/branches/${trunk}/protection`)
139
+ } catch (error) {
140
+ if (/HTTP 404|Not Found|no required/i.test(error.message)) return null
141
+ throw error
142
+ }
143
+ }
144
+
145
+ export function findGreenHead({
146
+ trunk = DEFAULT_TRUNK,
147
+ max = DEFAULT_MAX,
148
+ cwd,
149
+ git = runGit,
150
+ api = (path, options = {}) => ghApi(path, { cwd, ...options }),
151
+ } = {}) {
152
+ git(['fetch', 'origin', trunk], { cwd })
153
+ const remote = parseGithubRemote(git(['remote', 'get-url', 'origin'], { cwd }).stdout)
154
+ if (!remote) {
155
+ const err = new Error('origin is not a GitHub remote')
156
+ err.exitCode = 1
157
+ throw err
158
+ }
159
+ const log = git(['log', `origin/${trunk}`, '--first-parent', '-n', String(max), '--format=%H'], { cwd })
160
+ const shas = log.stdout.split('\n').map((line) => line.trim()).filter(Boolean)
161
+ if (shas.length === 0) {
162
+ const err = new Error(`no commits on origin/${trunk}`)
163
+ err.exitCode = 1
164
+ throw err
165
+ }
166
+ const protection = loadProtection(remote.owner, remote.repo, trunk, api)
167
+ const required = requiredContexts(protection)
168
+ const inspect = (sha) => {
169
+ const status = api(`repos/${remote.owner}/${remote.repo}/commits/${sha}/status`)
170
+ const checks = api(`repos/${remote.owner}/${remote.repo}/commits/${sha}/check-runs?per_page=100`, { paginate: true })
171
+ return inspectGreen({ status, checkRuns: checks, required })
172
+ }
173
+ const picked = pickGreenHead(shas, inspect)
174
+ if (!picked) {
175
+ const err = new Error('no-green-head')
176
+ err.exitCode = 1
177
+ throw err
178
+ }
179
+ return {
180
+ trunk,
181
+ owner: remote.owner,
182
+ repo: remote.repo,
183
+ tipSha: shas[0],
184
+ candidateSha: picked.sha,
185
+ walked: shas.indexOf(picked.sha) + 1,
186
+ requiredChecks: required,
187
+ verdict: picked.verdict,
188
+ }
189
+ }
190
+
191
+ function parseArgs(argv) {
192
+ const opts = { trunk: DEFAULT_TRUNK, max: DEFAULT_MAX, json: false }
193
+ for (let i = 0; i < argv.length; i += 1) {
194
+ const arg = argv[i]
195
+ if (arg === '--json') opts.json = true
196
+ else if (arg === '--trunk') opts.trunk = argv[++i]
197
+ else if (arg === '--max') opts.max = Number(argv[++i])
198
+ else if (arg === '--help' || arg === '-h') opts.help = true
199
+ else {
200
+ const err = new Error(`unknown argument: ${arg}`)
201
+ err.exitCode = 2
202
+ throw err
203
+ }
204
+ }
205
+ if (!opts.trunk || !Number.isInteger(opts.max) || opts.max < 1) {
206
+ const err = new Error('usage: green-head.mjs [--trunk main] [--max 50] [--json]')
207
+ err.exitCode = 2
208
+ throw err
209
+ }
210
+ return opts
211
+ }
212
+
213
+ export function main(argv = process.argv.slice(2)) {
214
+ const opts = parseArgs(argv)
215
+ if (opts.help) {
216
+ process.stdout.write('green-head.mjs [--trunk main] [--max 50] [--json]\n')
217
+ return 0
218
+ }
219
+ const result = findGreenHead({ trunk: opts.trunk, max: opts.max })
220
+ process.stdout.write(opts.json ? `${JSON.stringify(result, null, 2)}\n` : `${result.candidateSha}\n`)
221
+ return 0
222
+ }
223
+
224
+ if (isMainModule(import.meta.url)) {
225
+ try {
226
+ process.exitCode = main()
227
+ } catch (error) {
228
+ process.stderr.write(`${error.message}\n`)
229
+ process.exitCode = error.exitCode || 1
230
+ }
231
+ }
@@ -0,0 +1,101 @@
1
+ import { test } from 'node:test'
2
+ import assert from 'node:assert/strict'
3
+ import {
4
+ findGreenHead,
5
+ inspectGreen,
6
+ parseGithubRemote,
7
+ pickGreenHead,
8
+ requiredContexts,
9
+ } from './green-head.mjs'
10
+
11
+ test('parses GitHub remotes', () => {
12
+ assert.deepEqual(parseGithubRemote('git@github.com:acme/app.git'), { owner: 'acme', repo: 'app' })
13
+ assert.deepEqual(parseGithubRemote('https://github.com/acme/app.git'), { owner: 'acme', repo: 'app' })
14
+ assert.equal(parseGithubRemote('git@gitlab.com:acme/app.git'), null)
15
+ })
16
+
17
+ test('required contexts union both protection shapes', () => {
18
+ assert.deepEqual(
19
+ requiredContexts({
20
+ required_status_checks: {
21
+ contexts: ['build'],
22
+ checks: [{ context: 'test' }, { context: 'build' }],
23
+ },
24
+ }),
25
+ ['build', 'test'],
26
+ )
27
+ })
28
+
29
+ test('required checks must all pass; pending is not green', () => {
30
+ const required = ['build', 'test']
31
+ const pending = inspectGreen({
32
+ status: { state: 'pending', statuses: [] },
33
+ checkRuns: { check_runs: [{ name: 'build', conclusion: 'success' }, { name: 'test', status: 'in_progress' }] },
34
+ required,
35
+ })
36
+ assert.equal(pending.green, false)
37
+ assert.deepEqual(pending.pending, ['test'])
38
+
39
+ const green = inspectGreen({
40
+ status: { state: 'success', statuses: [] },
41
+ checkRuns: { check_runs: [{ name: 'build', conclusion: 'success' }, { name: 'test', conclusion: 'skipped' }] },
42
+ required,
43
+ })
44
+ assert.equal(green.green, true)
45
+ })
46
+
47
+ test('without required checks, no CI is not green and failures refuse', () => {
48
+ assert.equal(inspectGreen({ status: { state: 'pending' }, checkRuns: { check_runs: [] }, required: [] }).green, false)
49
+ assert.equal(inspectGreen({
50
+ status: { state: 'success' },
51
+ checkRuns: { check_runs: [{ name: 'build', conclusion: 'failure' }] },
52
+ required: [],
53
+ }).green, false)
54
+ assert.equal(inspectGreen({
55
+ status: { state: 'pending', statuses: [] },
56
+ checkRuns: { check_runs: [{ name: 'build', conclusion: 'success' }] },
57
+ required: [],
58
+ }).green, true, 'check-run-only repositories must not be blocked by an empty combined Status API')
59
+
60
+ const pagedFailure = inspectGreen({
61
+ status: { state: 'pending', statuses: [] },
62
+ checkRuns: [
63
+ { check_runs: [{ name: 'build', conclusion: 'success' }] },
64
+ { check_runs: [{ name: 'late-page', conclusion: 'failure' }] },
65
+ ],
66
+ required: [],
67
+ })
68
+ assert.equal(pagedFailure.green, false)
69
+ assert.deepEqual(pagedFailure.failed, ['late-page'])
70
+ })
71
+
72
+ test('findGreenHead requests every check-run page', () => {
73
+ const calls = []
74
+ const git = (args) => {
75
+ if (args[0] === 'fetch') return { status: 0, stdout: '', stderr: '' }
76
+ if (args[0] === 'remote') return { status: 0, stdout: 'https://github.com/acme/app.git\n', stderr: '' }
77
+ if (args[0] === 'log') return { status: 0, stdout: `${'a'.repeat(40)}\n`, stderr: '' }
78
+ throw new Error(`unexpected git call: ${args.join(' ')}`)
79
+ }
80
+ const api = (path, options = {}) => {
81
+ calls.push({ path, options })
82
+ if (path.endsWith('/protection')) return null
83
+ if (path.endsWith('/status')) return { state: 'pending', statuses: [] }
84
+ if (path.includes('/check-runs')) return [{ check_runs: [{ name: 'build', conclusion: 'success' }] }]
85
+ throw new Error(`unexpected API call: ${path}`)
86
+ }
87
+
88
+ const result = findGreenHead({ cwd: '.', git, api })
89
+ assert.equal(result.candidateSha, 'a'.repeat(40))
90
+ assert.deepEqual(
91
+ calls.find((call) => call.path.includes('/check-runs'))?.options,
92
+ { paginate: true },
93
+ )
94
+ })
95
+
96
+ test('picker returns the newest green SHA and stops', () => {
97
+ const shas = ['tip-red', 'green', 'older-green']
98
+ const inspect = (sha) => ({ green: sha !== 'tip-red' })
99
+ assert.deepEqual(pickGreenHead(shas, inspect), { sha: 'green', verdict: { green: true } })
100
+ assert.equal(pickGreenHead(['red'], () => ({ green: false })), null)
101
+ })