@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,500 @@
1
+ #!/usr/bin/env node
2
+ // Release flows: predefined flows shipped in ../flows/, and a project's own .release/flow.md,
3
+ // which may `extends:` one of them. Validate the effective flow, resolve the release choices,
4
+ // render a project flow.
5
+ //
6
+ // Usage:
7
+ // node flow.mjs list [--json]
8
+ // node flow.mjs validate [--file .release/flow.md] [--flow <predefined>] [--json]
9
+ // node flow.mjs resolve --mode full|shortcut [--file .release/flow.md] [--flow <predefined>] [--json]
10
+ // [--exposure full|canary] [--canary-steps 10,50] [--hold-minutes 15]
11
+ // [--health-check <cmd>] [--dark on|off] [--flag-registry <path>]
12
+ // [--answer <id>=<value>]... [--repo-canary] [--repo-flag-registry]
13
+ // node flow.mjs render [--file .release/flow.md] [--flow <predefined>] < resolved.json
14
+ //
15
+ // Exit: 0 ok/resolved · 1 invalid flow · 2 usage · 3 refused · 4 questions pending
16
+ import { createHash } from 'node:crypto'
17
+ import { existsSync, readdirSync, readFileSync } from 'node:fs'
18
+ import { dirname, join, resolve } from 'node:path'
19
+ import { fileURLToPath } from 'node:url'
20
+ import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
21
+ import { dumpYamlMapping, parseYamlMapping } from '../../engineering-runtime/scripts/yaml-mapping.mjs'
22
+
23
+ export const DEFAULT_FLOW_PATH = '.release/flow.md'
24
+ export const PREDEFINED_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'flows')
25
+ const FLOW_NAME = /^[a-z0-9][a-z0-9-]*$/
26
+ export const ROUTES = ['root-tag', 'workspace-npm', 'cloud-run']
27
+ export const STEP_SECTIONS = ['before-cut', 'after-merge', 'before-exposure', 'after-publish', 'after-live', 'hand-back-if']
28
+ const SETTING_KEYS = ['extends', 'description', 'route', 'publisher', 'packages', 'changelog', 'registry', 'ask', 'exposure', 'canary', 'dark', 'flagRegistry', 'required']
29
+ // Keys that would reshape the release rather than fill a slot of it. Named so the refusal says why.
30
+ const SKELETON_KEYS = new Set([
31
+ 'trunk', 'branch', 'releaseBranch', 'stages', 'skip', 'skipStages', 'confirm', 'confirmPlan',
32
+ 'invocation', 'autoInvoke', 'disable-model-invocation', 'allow_implicit_invocation',
33
+ ])
34
+ const CHOICE_IDS = new Set(['exposure', 'dark', 'canarySteps', 'holdMinutes'])
35
+ const ASK_ID = /^[a-z][A-Za-z0-9-]*$/
36
+
37
+ const isMapping = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
38
+ const isText = (value) => typeof value === 'string' && value.trim() !== ''
39
+ const isTextList = (value) => Array.isArray(value) && value.every(isText)
40
+
41
+ function normalizeSwitch(value) {
42
+ if (value === true) return 'on'
43
+ if (value === false) return 'off'
44
+ return value
45
+ }
46
+
47
+ export function splitFlow(text) {
48
+ const source = String(text ?? '').replace(/\r\n/g, '\n')
49
+ const match = /^---\n(?:([\s\S]*?)\n)?---(?:\n|$)/.exec(source)
50
+ if (!match) return { frontmatter: null, body: source }
51
+ return { frontmatter: match[1] ?? '', body: source.slice(match[0].length) }
52
+ }
53
+
54
+ export function parseSteps(body) {
55
+ const steps = {}
56
+ const errors = []
57
+ let current = null
58
+ for (const line of String(body).split('\n')) {
59
+ const heading = /^##\s+(.+?)\s*$/.exec(line)
60
+ if (heading) {
61
+ const name = heading[1].trim()
62
+ if (!STEP_SECTIONS.includes(name)) {
63
+ errors.push(`unknown section "## ${name}"; allowed: ${STEP_SECTIONS.join(', ')}`)
64
+ current = null
65
+ continue
66
+ }
67
+ if (steps[name]) errors.push(`section "## ${name}" appears twice`)
68
+ steps[name] = steps[name] || []
69
+ current = name
70
+ continue
71
+ }
72
+ if (!current || line.trim() === '') continue
73
+ const bullet = /^[-*]\s+(.+)$/.exec(line)
74
+ if (bullet) steps[current].push(bullet[1].trim())
75
+ else if (/^\s+\S/.test(line) && steps[current].length) {
76
+ steps[current][steps[current].length - 1] += ` ${line.trim()}`
77
+ } else errors.push(`section "## ${current}" holds only "- " steps; found: ${line.trim()}`)
78
+ }
79
+ return { steps, errors }
80
+ }
81
+
82
+ function validateSettings(settings, { predefined = false, partial = false } = {}) {
83
+ const errors = []
84
+ if (settings.extends !== undefined) {
85
+ if (predefined) errors.push('a predefined flow cannot extend another flow')
86
+ else if (!isText(settings.extends) || !FLOW_NAME.test(settings.extends)) errors.push('extends must name a predefined flow')
87
+ }
88
+ if (settings.description !== undefined && !isText(settings.description)) errors.push('description must be text')
89
+ for (const key of Object.keys(settings)) {
90
+ if (SKELETON_KEYS.has(key)) errors.push(`"${key}" would change the release skeleton or manual-only invocation; a flow only fills slots`)
91
+ else if (!SETTING_KEYS.includes(key)) errors.push(`unknown setting "${key}"; allowed: ${SETTING_KEYS.join(', ')}`)
92
+ }
93
+ const { route, exposure, canary, flagRegistry, required } = settings
94
+ const dark = normalizeSwitch(settings.dark)
95
+ if (route !== undefined && !ROUTES.includes(route)) errors.push(`route must be one of ${ROUTES.join(', ')}`)
96
+ if (settings.publisher !== undefined) {
97
+ if (!isMapping(settings.publisher)) errors.push('publisher must be a mapping')
98
+ else for (const [key, value] of Object.entries(settings.publisher)) {
99
+ if (!['string', 'boolean', 'number'].includes(typeof value)) errors.push(`publisher.${key} must be a scalar`)
100
+ }
101
+ }
102
+ if (settings.packages !== undefined) {
103
+ if (!isMapping(settings.packages)) errors.push('packages must be a mapping')
104
+ else {
105
+ for (const key of Object.keys(settings.packages)) {
106
+ if (!['exclude', 'publishLast'].includes(key)) errors.push(`unknown packages.${key}; allowed: exclude, publishLast`)
107
+ else if (!isTextList(settings.packages[key])) errors.push(`packages.${key} must be a list of package names`)
108
+ }
109
+ if (route !== undefined && route !== 'workspace-npm') errors.push('packages applies only to route workspace-npm')
110
+ }
111
+ }
112
+ if (settings.changelog !== undefined && !['root', 'package-scoped'].includes(settings.changelog)) {
113
+ errors.push('changelog must be root or package-scoped')
114
+ }
115
+ if (settings.registry !== undefined && !(isText(settings.registry) && /^https:\/\//.test(settings.registry))) {
116
+ errors.push('registry must be an https:// URL')
117
+ }
118
+ if (settings.ask !== undefined) {
119
+ if (!Array.isArray(settings.ask)) errors.push('ask must be a list')
120
+ else {
121
+ const seen = new Set()
122
+ settings.ask.forEach((item, index) => {
123
+ const where = `ask[${index}]`
124
+ if (!isMapping(item)) return errors.push(`${where} must be a mapping with id and question`)
125
+ for (const key of Object.keys(item)) {
126
+ if (!['id', 'question', 'options', 'default'].includes(key)) errors.push(`unknown ${where}.${key}`)
127
+ }
128
+ if (!isText(item.id) || !ASK_ID.test(item.id)) errors.push(`${where}.id must match ${ASK_ID}`)
129
+ else if (CHOICE_IDS.has(item.id)) errors.push(`${where}.id "${item.id}" is a built-in choice; set it directly`)
130
+ else if (seen.has(item.id)) errors.push(`${where}.id "${item.id}" is repeated`)
131
+ else seen.add(item.id)
132
+ if (!isText(item.question)) errors.push(`${where}.question must be text`)
133
+ if (item.options !== undefined && !(isTextList(item.options) && item.options.length >= 2)) {
134
+ errors.push(`${where}.options must list at least two choices`)
135
+ }
136
+ if (item.default !== undefined) {
137
+ if (!isText(item.default)) errors.push(`${where}.default must be text`)
138
+ else if (item.options && !item.options.includes(item.default)) errors.push(`${where}.default must be one of its options`)
139
+ }
140
+ })
141
+ }
142
+ }
143
+ if (exposure !== undefined && !['full', 'canary', 'n/a'].includes(exposure)) errors.push('exposure must be full, canary or n/a')
144
+ if (canary !== undefined) {
145
+ if (!isMapping(canary)) errors.push('canary must be a mapping')
146
+ else {
147
+ for (const key of Object.keys(canary)) {
148
+ if (!['steps', 'holdMinutes', 'healthCheck'].includes(key)) errors.push(`unknown canary.${key}`)
149
+ }
150
+ // A project half may set only some canary keys; the merged flow must have them all.
151
+ const stepError = partial && canary.steps === undefined ? null : canarySteps(canary.steps).error
152
+ if (stepError) errors.push(`canary.steps ${stepError}`)
153
+ if (!(partial && canary.holdMinutes === undefined) && !(Number.isInteger(canary.holdMinutes) && canary.holdMinutes > 0)) {
154
+ errors.push('canary.holdMinutes must be a positive integer')
155
+ }
156
+ // Optional here so a predefined flow can declare steps; the project supplies the command,
157
+ // and resolving a canary without one is a refusal.
158
+ if (canary.healthCheck !== undefined && !isText(canary.healthCheck)) errors.push('canary.healthCheck must be the repository command that judges each hold')
159
+ }
160
+ }
161
+ if (exposure === 'canary' && canary === undefined) errors.push('exposure canary needs a canary block (steps, holdMinutes)')
162
+ if ((exposure === 'canary' || canary !== undefined) && route !== undefined && route !== 'cloud-run') {
163
+ errors.push('canary exposure applies only to route cloud-run')
164
+ }
165
+ if (dark !== undefined && !['on', 'off', 'n/a'].includes(dark)) errors.push('dark must be on, off or n/a')
166
+ if (flagRegistry !== undefined && !isText(flagRegistry)) errors.push('flagRegistry must be a repository path')
167
+ if (dark === 'on' && !isText(flagRegistry)) errors.push('dark on needs flagRegistry')
168
+ if (required !== undefined) {
169
+ if (!isTextList(required) || required.some((item) => !['canary', 'dark'].includes(item))) {
170
+ errors.push('required lists only canary and/or dark')
171
+ } else {
172
+ if (required.includes('canary') && exposure !== 'canary') errors.push('required canary needs exposure canary')
173
+ if (required.includes('dark') && dark !== 'on') errors.push('required dark needs dark on')
174
+ }
175
+ }
176
+ return errors
177
+ }
178
+
179
+ export function validateFlow(text, { predefined = false, partial = false } = {}) {
180
+ const sha256 = createHash('sha256').update(String(text ?? '')).digest('hex')
181
+ const { frontmatter, body } = splitFlow(text)
182
+ if (frontmatter === null) {
183
+ return { valid: false, errors: ['a flow starts with a --- frontmatter block of settings'], sha256, settings: null, steps: {} }
184
+ }
185
+ let settings
186
+ try {
187
+ settings = frontmatter.trim() === '' ? {} : parseYamlMapping(frontmatter, 'flow frontmatter')
188
+ } catch (error) {
189
+ return { valid: false, errors: [error.message], sha256, settings: null, steps: {} }
190
+ }
191
+ const { steps, errors: stepErrors } = parseSteps(body)
192
+ const errors = [...(partial ? validateSlots(settings) : validateSettings(settings, { predefined })), ...stepErrors]
193
+ if (settings.dark !== undefined) settings = { ...settings, dark: normalizeSwitch(settings.dark) }
194
+ return { valid: errors.length === 0, errors, sha256, settings, steps }
195
+ }
196
+
197
+ // A project flow that extends a predefined one is checked slot by slot on its own, then as a
198
+ // whole once merged, because a cross-field rule (canary needs cloud-run) can span both files.
199
+ function validateSlots(settings) {
200
+ const errors = validateSettings(settings, { partial: true })
201
+ const crossField = [/^exposure canary needs/, /only to route/, /^dark on needs/, /^required (canary|dark) needs/]
202
+ return errors.filter((error) => !crossField.some((pattern) => pattern.test(error)))
203
+ }
204
+
205
+ export function listPredefined(dir = PREDEFINED_DIR) {
206
+ if (!existsSync(dir)) return []
207
+ return readdirSync(dir)
208
+ .filter((name) => name.endsWith('.md'))
209
+ .map((file) => file.slice(0, -3))
210
+ .sort()
211
+ .map((name) => {
212
+ const file = `${name}.md`
213
+ const flow = validateFlow(readFileSync(join(dir, file), 'utf8'), { predefined: true })
214
+ return { name, description: flow.settings?.description || '', valid: flow.valid, errors: flow.errors }
215
+ })
216
+ }
217
+
218
+ export function loadPredefined(name, dir = PREDEFINED_DIR) {
219
+ const path = join(dir, `${name}.md`)
220
+ if (!FLOW_NAME.test(String(name)) || !existsSync(path)) {
221
+ const known = listPredefined(dir).map((flow) => flow.name).join(', ')
222
+ return { valid: false, errors: [`no predefined flow "${name}"; available: ${known}`], text: '' }
223
+ }
224
+ const text = readFileSync(path, 'utf8')
225
+ return { name, text, ...validateFlow(text, { predefined: true }) }
226
+ }
227
+
228
+ const MERGED_MAPPINGS = ['publisher', 'packages', 'canary']
229
+
230
+ // Project settings override the base; mapping slots merge key by key; ask items merge by id.
231
+ // Steps append: the base flow's steps at a point run first, then the project's.
232
+ export function mergeFlows(base, own) {
233
+ const settings = { ...base.settings }
234
+ for (const [key, value] of Object.entries(own.settings)) {
235
+ if (key === 'extends') continue
236
+ if (MERGED_MAPPINGS.includes(key) && isMapping(value) && isMapping(settings[key])) settings[key] = { ...settings[key], ...value }
237
+ else if (key === 'ask' && Array.isArray(value) && Array.isArray(settings.ask)) {
238
+ const ids = new Set(value.map((item) => item?.id))
239
+ settings.ask = [...settings.ask.filter((item) => !ids.has(item.id)), ...value]
240
+ } else settings[key] = value
241
+ }
242
+ const steps = {}
243
+ for (const name of STEP_SECTIONS) {
244
+ const merged = [...(base.steps[name] || []), ...(own.steps[name] || [])]
245
+ if (merged.length) steps[name] = merged
246
+ }
247
+ return { settings, steps }
248
+ }
249
+
250
+ function declaresExtends(text) {
251
+ const { frontmatter } = splitFlow(text)
252
+ if (!frontmatter) return false
253
+ try {
254
+ return parseYamlMapping(frontmatter).extends !== undefined
255
+ } catch {
256
+ return false
257
+ }
258
+ }
259
+
260
+ const digest = (...parts) => createHash('sha256').update(parts.join('\0')).digest('hex')
261
+
262
+ // The effective flow: the project's own file (optionally extending a predefined flow), or a
263
+ // predefined flow named at invocation when the project has none. Neither: no flow.
264
+ export function loadFlow(file = DEFAULT_FLOW_PATH, { cwd = process.cwd(), name = null, dir = PREDEFINED_DIR } = {}) {
265
+ const path = resolve(cwd, file)
266
+ const hasProject = existsSync(path)
267
+ const invalid = (errors, extra = {}) => ({ present: true, valid: false, errors, settings: null, steps: {}, ...extra })
268
+ if (!hasProject && !name) return { present: false, path: file }
269
+ if (hasProject && name) {
270
+ return invalid([`${file} exists; the project flow wins, so name a predefined flow in its extends instead of --flow`], { path: file })
271
+ }
272
+ if (!hasProject) {
273
+ const base = loadPredefined(name, dir)
274
+ if (!base.valid) return invalid(base.errors, { path: null, base: name })
275
+ return { present: true, valid: true, errors: [], path: null, base: name, own: null, settings: base.settings, steps: base.steps, sha256: digest(`flow:${name}`, base.text) }
276
+ }
277
+ const text = readFileSync(path, 'utf8')
278
+ const own = validateFlow(text, { partial: declaresExtends(text) })
279
+ if (!own.valid) return invalid(own.errors, { path: file })
280
+ if (!own.settings.extends) {
281
+ return { present: true, valid: true, errors: [], path: file, base: null, own: { settings: own.settings, steps: own.steps }, settings: own.settings, steps: own.steps, sha256: own.sha256 }
282
+ }
283
+ const base = loadPredefined(own.settings.extends, dir)
284
+ if (!base.valid) return invalid(base.errors, { path: file, base: own.settings.extends })
285
+ const merged = mergeFlows(base, own)
286
+ const errors = validateSettings(merged.settings)
287
+ if (errors.length) return invalid(errors.map((error) => `${file} + ${own.settings.extends}: ${error}`), { path: file, base: own.settings.extends })
288
+ return {
289
+ present: true, valid: true, errors: [], path: file, base: own.settings.extends,
290
+ own: { settings: own.settings, steps: own.steps }, ...merged,
291
+ sha256: digest(`flow:${own.settings.extends}`, base.text, text),
292
+ }
293
+ }
294
+
295
+ export function canarySteps(value) {
296
+ const steps = typeof value === 'string' ? value.split(',').map((part) => Number(part.trim())) : value
297
+ if (!Array.isArray(steps) || steps.length === 0) return { error: 'must list at least one percentage' }
298
+ if (!steps.every((step) => Number.isInteger(step) && step > 0 && step < 100)) {
299
+ return { error: 'must be whole percentages between 1 and 99 (100% is the final shift)' }
300
+ }
301
+ if (steps.some((step, index) => index > 0 && step <= steps[index - 1])) return { error: 'must strictly increase' }
302
+ return { steps }
303
+ }
304
+
305
+ // Precedence: invocation option > release flow > preflight answer/question. Shortcut mode
306
+ // (rush-release) asks nothing: exposure full, dark off, flow questions take their defaults.
307
+ export function resolveChoices({ mode, flow = null, invocation = {}, answers = {}, repo = {} } = {}) {
308
+ if (!['full', 'shortcut'].includes(mode)) throw usage('--mode must be full or shortcut')
309
+ const settings = flow?.settings || {}
310
+ const required = settings.required || []
311
+ const choices = { exposure: null, dark: null, canary: null, flagRegistry: null, ask: {} }
312
+ const sources = {}
313
+ const questions = []
314
+ const refusals = []
315
+ const set = (key, value, source) => { choices[key] = value; sources[key] = source }
316
+
317
+ if (mode === 'shortcut') {
318
+ const passed = ['exposure', 'dark', 'canarySteps', 'holdMinutes'].filter((key) => invocation[key] !== undefined)
319
+ if (passed.length) refusals.push(`rush-release takes the shortcut (exposure full, dark off) and accepts no ${passed.join('/')} option; use /resolve-release`)
320
+ for (const item of required) refusals.push(`the release flow requires ${item}; rush-release cannot provide it, use /resolve-release`)
321
+ set('exposure', settings.exposure === 'n/a' ? 'n/a' : 'full', 'shortcut')
322
+ set('dark', settings.dark === 'n/a' ? 'n/a' : 'off', 'shortcut')
323
+ for (const item of settings.ask || []) {
324
+ if (item.default !== undefined) { choices.ask[item.id] = item.default; sources[`ask.${item.id}`] = 'flow-default' }
325
+ else refusals.push(`the release flow asks "${item.question}" with no default; rush-release never asks, use /resolve-release`)
326
+ }
327
+ return { mode, choices, sources, questions, refusals }
328
+ }
329
+
330
+ const pick = (key) => {
331
+ if (invocation[key] !== undefined) return [invocation[key], 'invocation']
332
+ if (settings[key] !== undefined) return [settings[key], 'flow']
333
+ if (answers[key] !== undefined) return [answers[key], 'answer']
334
+ return [undefined, null]
335
+ }
336
+
337
+ const [exposure, exposureSource] = pick('exposure')
338
+ if (exposure === undefined) {
339
+ const suggested = repo.canary || settings.canary ? 'canary' : 'full'
340
+ questions.push({ id: 'exposure', question: 'How should users move to the new version?', options: ['full', 'canary'], default: suggested })
341
+ } else if (!['full', 'canary', 'n/a'].includes(exposure)) refusals.push(`exposure must be full or canary, got ${exposure}`)
342
+ else if (exposure !== 'n/a' && settings.exposure === 'n/a') refusals.push('the release flow marks exposure n/a (no traffic to split)')
343
+ else set('exposure', exposure, exposureSource)
344
+
345
+ if (choices.exposure === 'canary') {
346
+ const fromFlow = settings.canary || {}
347
+ const stepsValue = invocation.canarySteps ?? fromFlow.steps ?? answers.canarySteps
348
+ const holdValue = invocation.holdMinutes ?? fromFlow.holdMinutes ?? answers.holdMinutes
349
+ const healthCheck = invocation.healthCheck ?? fromFlow.healthCheck
350
+ let steps = null
351
+ if (stepsValue === undefined) questions.push({ id: 'canarySteps', question: 'Which traffic percentages before 100%?', default: '10,50' })
352
+ else {
353
+ const parsed = canarySteps(stepsValue)
354
+ if (parsed.error) refusals.push(`canary steps ${parsed.error}`)
355
+ else steps = parsed.steps
356
+ }
357
+ const hold = holdValue === undefined ? undefined : Number(holdValue)
358
+ if (holdValue === undefined) questions.push({ id: 'holdMinutes', question: 'How many minutes to hold at each step?', default: '15' })
359
+ else if (!(Number.isInteger(hold) && hold > 0)) refusals.push('hold minutes must be a positive integer')
360
+ if (!isText(healthCheck)) refusals.push('canary needs a repository-declared health check (flow canary.healthCheck or --health-check)')
361
+ if (steps && Number.isInteger(hold) && hold > 0 && isText(healthCheck)) {
362
+ set('canary', { steps, holdMinutes: hold, healthCheck }, invocation.canarySteps !== undefined ? 'invocation' : fromFlow.steps ? 'flow' : 'answer')
363
+ }
364
+ }
365
+
366
+ const [darkRaw, darkSource] = pick('dark')
367
+ const dark = normalizeSwitch(darkRaw)
368
+ const flagRegistry = invocation.flagRegistry ?? settings.flagRegistry
369
+ if (dark === undefined) {
370
+ questions.push({ id: 'dark', question: 'Check that features shipping behind flags stay switched off?', options: ['on', 'off'], default: flagRegistry || repo.flagRegistry ? 'on' : 'off' })
371
+ } else if (!['on', 'off', 'n/a'].includes(dark)) refusals.push(`dark must be on or off, got ${dark}`)
372
+ else if (dark !== 'n/a' && settings.dark === 'n/a') refusals.push('the release flow marks dark launch n/a')
373
+ else {
374
+ set('dark', dark, darkSource)
375
+ if (dark === 'on') {
376
+ if (isText(flagRegistry)) set('flagRegistry', flagRegistry, invocation.flagRegistry ? 'invocation' : 'flow')
377
+ else refusals.push('dark launch needs a flag registry (flow flagRegistry or --flag-registry)')
378
+ }
379
+ }
380
+ for (const item of required) {
381
+ if (item === 'canary' && choices.exposure && choices.exposure !== 'canary') refusals.push('the release flow requires canary exposure')
382
+ if (item === 'dark' && choices.dark && choices.dark !== 'on') refusals.push('the release flow requires dark launch on')
383
+ }
384
+
385
+ for (const item of settings.ask || []) {
386
+ if (answers[item.id] !== undefined) {
387
+ if (item.options && !item.options.includes(answers[item.id])) refusals.push(`${item.id} must be one of ${item.options.join(', ')}`)
388
+ else { choices.ask[item.id] = answers[item.id]; sources[`ask.${item.id}`] = 'answer' }
389
+ } else questions.push({ id: item.id, question: item.question, ...(item.options ? { options: item.options } : {}), ...(item.default !== undefined ? { default: item.default } : {}) })
390
+ }
391
+ return { mode, choices, sources, questions, refusals }
392
+ }
393
+
394
+ // The saved flow keeps every existing slot and step and records this run's exposure and dark
395
+ // choices. Per-release answers (ask items) are not saved: they are asked again next time.
396
+ export function renderFlow({ choices }, existing = null) {
397
+ const settings = existing?.own ? { ...existing.own.settings } : {}
398
+ if (existing?.base) settings.extends = existing.base
399
+ if (choices.exposure && choices.exposure !== 'n/a') settings.exposure = choices.exposure
400
+ if (choices.canary) settings.canary = { ...choices.canary }
401
+ if (choices.dark && choices.dark !== 'n/a') settings.dark = choices.dark
402
+ if (choices.flagRegistry) settings.flagRegistry = choices.flagRegistry
403
+ const lines = ['---', dumpYamlMapping(settings).trimEnd(), '---', '', '# Release flow', '']
404
+ for (const name of STEP_SECTIONS) {
405
+ const steps = existing?.own?.steps?.[name]
406
+ if (!steps?.length) continue
407
+ lines.push(`## ${name}`, '', ...steps.map((step) => `- ${step}`), '')
408
+ }
409
+ const text = `${lines.join('\n').trimEnd()}\n`
410
+ const check = validateFlow(text, { partial: Boolean(settings.extends) })
411
+ if (!check.valid) throw new Error(`rendered flow is invalid: ${check.errors.join('; ')}`)
412
+ return text
413
+ }
414
+
415
+ function usage(message) {
416
+ const err = new Error(message)
417
+ err.exitCode = 2
418
+ return err
419
+ }
420
+
421
+ function parseArgs(argv) {
422
+ const [command, ...rest] = argv
423
+ const opts = { command, file: DEFAULT_FLOW_PATH, json: false, invocation: {}, answers: {}, repo: {} }
424
+ const value = (i, name) => {
425
+ if (rest[i] === undefined) throw usage(`${name} needs a value`)
426
+ return rest[i]
427
+ }
428
+ for (let i = 0; i < rest.length; i += 1) {
429
+ const arg = rest[i]
430
+ if (arg === '--json') opts.json = true
431
+ else if (arg === '--file') opts.file = value(++i, arg)
432
+ else if (arg === '--flow') opts.flow = value(++i, arg)
433
+ else if (arg === '--mode') opts.mode = value(++i, arg)
434
+ else if (arg === '--exposure') opts.invocation.exposure = value(++i, arg)
435
+ else if (arg === '--canary-steps') opts.invocation.canarySteps = value(++i, arg)
436
+ else if (arg === '--hold-minutes') opts.invocation.holdMinutes = value(++i, arg)
437
+ else if (arg === '--health-check') opts.invocation.healthCheck = value(++i, arg)
438
+ else if (arg === '--dark') opts.invocation.dark = value(++i, arg)
439
+ else if (arg === '--flag-registry') opts.invocation.flagRegistry = value(++i, arg)
440
+ else if (arg === '--repo-canary') opts.repo.canary = true
441
+ else if (arg === '--repo-flag-registry') opts.repo.flagRegistry = true
442
+ else if (arg === '--answer') {
443
+ const pair = value(++i, arg)
444
+ const eq = pair.indexOf('=')
445
+ if (eq < 1) throw usage('--answer takes <id>=<value>')
446
+ opts.answers[pair.slice(0, eq)] = pair.slice(eq + 1)
447
+ } else throw usage(`unknown argument: ${arg}`)
448
+ }
449
+ if (!['list', 'validate', 'resolve', 'render'].includes(command)) throw usage('usage: flow.mjs list|validate|resolve|render [options]')
450
+ if (command === 'resolve' && !opts.mode) throw usage('resolve needs --mode full|shortcut')
451
+ return opts
452
+ }
453
+
454
+ function write(opts, value, text) {
455
+ process.stdout.write(opts.json ? `${JSON.stringify(value, null, 2)}\n` : `${text}\n`)
456
+ }
457
+
458
+ export function main(argv = process.argv.slice(2), { cwd = process.cwd(), stdin = () => readFileSync(0, 'utf8') } = {}) {
459
+ const opts = parseArgs(argv)
460
+ if (opts.command === 'list') {
461
+ const flows = listPredefined()
462
+ write(opts, flows, flows.map((flow) => `${flow.name}: ${flow.description}`).join('\n'))
463
+ return flows.every((flow) => flow.valid) ? 0 : 1
464
+ }
465
+ const flow = loadFlow(opts.file, { cwd, name: opts.flow || null })
466
+ if (flow.present && !flow.valid) {
467
+ write(opts, flow, `invalid flow ${flow.path || flow.base}:\n- ${flow.errors.join('\n- ')}`)
468
+ return 1
469
+ }
470
+ if (opts.command === 'validate') {
471
+ const label = [flow.path, flow.base && `extends ${flow.base}`].filter(Boolean).join(' ')
472
+ write(opts, flow, flow.present ? `${label || flow.base} valid (sha256 ${flow.sha256})` : `no project flow at ${flow.path}`)
473
+ return 0
474
+ }
475
+ if (opts.command === 'render') {
476
+ process.stdout.write(renderFlow(JSON.parse(stdin()), flow.present ? flow : null))
477
+ return 0
478
+ }
479
+ const result = {
480
+ flow: flow.present ? { path: flow.path, base: flow.base, sha256: flow.sha256, steps: flow.steps, settings: flow.settings } : null,
481
+ ...resolveChoices({ mode: opts.mode, flow: flow.present ? flow : null, invocation: opts.invocation, answers: opts.answers, repo: opts.repo }),
482
+ }
483
+ const summary = result.refusals.length
484
+ ? `refused:\n- ${result.refusals.join('\n- ')}`
485
+ : result.questions.length
486
+ ? `ask:\n${result.questions.map((q) => `- ${q.id}: ${q.question}${q.options ? ` [${q.options.join('|')}]` : ''}${q.default !== undefined ? ` (default ${q.default})` : ''}`).join('\n')}`
487
+ : `resolved: exposure ${result.choices.exposure}, dark ${result.choices.dark}`
488
+ write(opts, result, summary)
489
+ if (result.refusals.length) return 3
490
+ return result.questions.length ? 4 : 0
491
+ }
492
+
493
+ if (isMainModule(import.meta.url)) {
494
+ try {
495
+ process.exitCode = main()
496
+ } catch (error) {
497
+ process.stderr.write(`${error.message}\n`)
498
+ process.exitCode = error.exitCode || 1
499
+ }
500
+ }