@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,269 @@
1
+ #!/usr/bin/env node
2
+ // Keep a run's task plan in step with its spec's GitHub issue tree, the only record of
3
+ // scope. Every open issue under the spec with no open sub-issue is a unit; an issue with an
4
+ // open sub-issue is a container; a closed issue is done. Order comes from native
5
+ // `blockedBy` links.
6
+ //
7
+ // plan-sync.mjs --run <run dir> [--live] [--json] [--exit-actions]
8
+ // plan-sync.mjs --find-run --runs <runs dir> --issue <owner/name#123> [--json] [--exit-actions]
9
+ //
10
+ // --live fetches the tree (issue-tree.mjs, one GraphQL query plus follow-ups) and, when the
11
+ // fetch is complete, saves it as <run>/issue-tree.json. Without --live it diffs the plan
12
+ // against that saved snapshot and makes no GitHub call. Actions:
13
+ //
14
+ // add-unit an open leaf issue under the spec that the plan does not know
15
+ // set-deps a unit lacks a dependency its own issue's blockedBy names
16
+ // move-link an issue with open sub-issues is blocked by an open issue: GitHub shows
17
+ // it holding every sub-issue, but the run never inherits it, so move it
18
+ // onto the sub-issues that use what the blocker builds
19
+ // drop-unit a unit's issue was closed, gained open sub-issues, or left the tree
20
+ // blocked-outside a unit waits on an open issue outside the spec's tree
21
+ //
22
+ // The plan knows an issue when a unit (any status), an `excluded` entry, or `merged` (merged
23
+ // by an earlier run) names it. set-deps only adds: dependencies the explorer recorded
24
+ // stay. A partial or failed fetch never drops a unit or changes dependencies; a failed one
25
+ // falls back to the snapshot. A plan whose spec is not a GitHub issue has nothing to sync.
26
+ //
27
+ // --find-run prints the newest run directory whose spec or saved tree contains the issue, so
28
+ // a new invocation resumes the spec's run instead of starting a second one.
29
+ //
30
+ // Exit 0 whenever it ran and answered: actions due or not, no tree available (`missingTree`),
31
+ // a run found or not; the outcome is in the output (--json: `actions`, `missingTree`, and for
32
+ // --find-run `found` and `dir`). Exit 2 only when it could not run (bad arguments, unreadable plan).
33
+ // With --find-run and no run found, plain output is empty on stdout (a note goes to stderr).
34
+ // --exit-actions restores the old exit codes for one release (deprecated): 1 when actions are due
35
+ // or no run was found, 2 when no tree is available.
36
+
37
+ import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
38
+ import { join } from 'node:path'
39
+
40
+ import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
41
+ import { fetchTree, keyOf } from './issue-tree.mjs'
42
+ import { parseIssueRef } from './ready-check.mjs'
43
+
44
+ export const SNAPSHOT = 'issue-tree.json'
45
+ const DONE = new Set(['succeeded', 'cancelled'])
46
+
47
+ export class PlanSyncError extends Error {}
48
+
49
+ const unitsOf = (plan) => (Array.isArray(plan?.units) ? plan.units : plan?.issues) ?? []
50
+
51
+ // The spec's root issue, or null for a local or pasted spec.
52
+ export function specRef(plan) {
53
+ for (const value of [plan?.specLocator, plan?.spec, plan?.specUrl]) {
54
+ if (typeof value !== 'string') continue
55
+ try { return parseIssueRef(value) } catch { /* not an issue reference */ }
56
+ }
57
+ return null
58
+ }
59
+
60
+ // The issue a unit or excluded entry names, as "owner/name#n", or null.
61
+ function issueKey(entry, repo) {
62
+ for (const value of [entry?.issue, entry?.ref, entry?.id]) {
63
+ if (value === undefined || value === null) continue
64
+ try {
65
+ const ref = parseIssueRef(String(value), repo)
66
+ return keyOf(ref.repo, ref.number)
67
+ } catch { /* not an issue reference */ }
68
+ }
69
+ return null
70
+ }
71
+
72
+ const idFor = (key, repo) => (key.startsWith(`${repo}#`) ? key.slice(repo.length + 1) : key)
73
+
74
+ // The unit ids of the plan's `excluded` issues (release gates, human-only environment work,
75
+ // empty rollups): a unit that depends on one waits for a human, never for the run.
76
+ export function excludedIds(plan) {
77
+ const repo = specRef(plan)?.repo ?? null
78
+ const ids = new Set()
79
+ for (const e of plan?.excluded ?? []) {
80
+ const key = issueKey(e, repo)
81
+ const raw = e?.issue ?? e?.id
82
+ if (key) ids.add(repo ? idFor(key, repo) : key)
83
+ else if (raw !== undefined && raw !== null) ids.add(String(raw).replace(/^#/, ''))
84
+ }
85
+ return ids
86
+ }
87
+
88
+ export function classify(tree) {
89
+ const kind = {}
90
+ for (const node of Object.values(tree.nodes)) {
91
+ if (node.state !== 'open') { kind[node.key] = 'closed'; continue }
92
+ const open = (node.children ?? []).filter((k) => tree.nodes[k]?.state === 'open')
93
+ kind[node.key] = open.length ? 'container' : 'unit'
94
+ }
95
+ return kind
96
+ }
97
+
98
+ // Diff the plan against the tree. `partial` suppresses every removal and dependency change.
99
+ export function planSync(plan, tree) {
100
+ const root = specRef(plan)
101
+ if (!root) return { synced: false, actions: [] }
102
+ const repo = root.repo
103
+ const partial = !tree.complete
104
+ const kind = classify(tree)
105
+ const nodes = tree.nodes
106
+ const units = unitsOf(plan)
107
+ const byKey = new Map()
108
+ for (const u of units) { const key = issueKey(u, repo); if (key) byKey.set(key, u) }
109
+ const known = new Set(byKey.keys())
110
+ for (const e of plan.excluded ?? []) { const key = issueKey(e, repo); if (key) known.add(key) }
111
+ for (const id of plan.merged ?? []) { const key = issueKey({ id }, repo); if (key) known.add(key) }
112
+
113
+ const leavesUnder = (key, seen = new Set()) => {
114
+ if (seen.has(key)) return []
115
+ seen.add(key)
116
+ if (kind[key] === 'unit') return [key]
117
+ if (kind[key] !== 'container') return []
118
+ return (nodes[key].children ?? []).flatMap((k) => leavesUnder(k, seen))
119
+ }
120
+ // A unit waits on its own issue's blockers only. A container's link is never inherited:
121
+ // move-link asks for it on the sub-issues that actually wait.
122
+ const blockers = (key) => nodes[key]?.blockedBy ?? []
123
+ const wants = (key) => {
124
+ const deps = new Set()
125
+ const outside = []
126
+ for (const b of blockers(key)) {
127
+ if (b.state !== 'open') continue
128
+ if (nodes[b.key]) for (const leaf of leavesUnder(b.key)) { if (leaf !== key) deps.add(idFor(leaf, repo)) }
129
+ else outside.push(b.key)
130
+ }
131
+ return { deps: [...deps].sort(), outside }
132
+ }
133
+
134
+ const actions = []
135
+ const add = (action, unit, detail, extra = {}) => actions.push({ action, unit, detail, ...extra })
136
+ for (const [key, k] of Object.entries(kind)) {
137
+ if (k !== 'unit' || known.has(key)) continue
138
+ const node = nodes[key]
139
+ const { deps } = wants(key)
140
+ const id = idFor(key, repo)
141
+ const rollup = (node.children ?? []).length > 0
142
+ add('add-unit', id, `add unit ${id} for ${key} "${node.title}"${deps.length ? ` with dependsOn [${deps.join(', ')}]` : ''}: fetch its issue into the run, continue the explorer for it, rerun the size check${rollup ? '; every sub-issue is closed, so the explorer records what is left or that nothing is (then hand back "close it")' : ''}`, { issue: key, dependsOn: deps })
143
+ }
144
+ for (const [key, u] of byKey) {
145
+ if (DONE.has(u.status)) continue
146
+ const id = String(u.id)
147
+ const k = kind[key]
148
+ if (k === undefined) {
149
+ if (!partial) add('drop-unit', id, `unit ${id}'s issue ${key} is no longer under ${tree.root}: cancel the unit, or put the issue back in the tree`, { issue: key })
150
+ continue
151
+ }
152
+ if (k === 'closed') { add('drop-unit', id, `unit ${id}'s issue ${key} was closed on GitHub: set succeeded if its PR merged, else cancelled`, { issue: key }); continue }
153
+ if (k === 'container') {
154
+ const open = (nodes[key].children ?? []).filter((c) => nodes[c]?.state === 'open').map((c) => idFor(c, repo))
155
+ if (!partial) add('drop-unit', id, `unit ${id}'s issue ${key} now has open sub-issues (${open.join(', ')}): they are the units; cancel ${id} and keep its workspace`, { issue: key })
156
+ continue
157
+ }
158
+ const { deps, outside } = wants(key)
159
+ if (!partial) {
160
+ const have = new Set((u.dependsOn ?? []).map(String))
161
+ const missing = deps.filter((d) => !have.has(d))
162
+ if (missing.length) add('set-deps', id, `unit ${id} waits on ${missing.join(', ')} (blockedBy on GitHub): add ${missing.length === 1 ? 'it' : 'them'} to its dependsOn`, { issue: key, dependsOn: [...have, ...missing] })
163
+ }
164
+ for (const o of outside) add('blocked-outside', id, `unit ${id} is blocked by open ${o}, outside ${tree.root}: make it a sub-issue of an issue in the tree, or remove the link`, { issue: key, blocker: o })
165
+ }
166
+ for (const [key, k] of Object.entries(kind)) {
167
+ if (k !== 'container' || key === tree.root) continue
168
+ const open = (nodes[key].blockedBy ?? []).filter((b) => b.state === 'open').map((b) => b.key)
169
+ if (!open.length) continue
170
+ const children = (nodes[key].children ?? []).filter((c) => nodes[c]?.state === 'open').map((c) => idFor(c, repo))
171
+ add('move-link', idFor(key, repo), `${key} has ${children.length} open sub-issues (${children.join(', ')}) and is blocked by ${open.join(', ')}; the run does not inherit a link on it: add blocked_by on each sub-issue that uses what the blocker builds, remove the link from ${key}, drop the blocker from the dependsOn of sub-issues that do not use it, and rerun next-actions.mjs with --sync so the saved tree sees the move`, { issue: key, blockers: open })
172
+ }
173
+ const order = ['drop-unit', 'add-unit', 'set-deps', 'move-link', 'blocked-outside']
174
+ actions.sort((a, b) => order.indexOf(a.action) - order.indexOf(b.action) || String(a.unit).localeCompare(String(b.unit)))
175
+ return { synced: true, partial, actions }
176
+ }
177
+
178
+ const readJson = (path) => { try { return JSON.parse(readFileSync(path, 'utf8')) } catch { return null } }
179
+
180
+ // Sync a run directory: fetch when `live`, else (or when the fetch fails) use the snapshot.
181
+ export function syncRun(runDir, { live = false, fetch = fetchTree, now = () => new Date() } = {}) {
182
+ const plan = readJson(join(runDir, 'task-plan.json'))
183
+ if (!plan) throw new PlanSyncError(`cannot read ${join(runDir, 'task-plan.json')}`)
184
+ const root = specRef(plan)
185
+ if (!root) return { source: 'none', synced: false, actions: [] }
186
+ const snapshotPath = join(runDir, SNAPSHOT)
187
+ let tree = null
188
+ let source = 'snapshot'
189
+ let fetchError = null
190
+ if (live) {
191
+ const fetched = fetch(root)
192
+ if (fetched.complete) {
193
+ tree = { ...fetched, fetchedAt: now().toISOString() }
194
+ writeFileSync(snapshotPath, `${JSON.stringify(tree, null, 2)}\n`)
195
+ source = 'live'
196
+ } else if (Object.keys(fetched.nodes).length && fetched.nodes[fetched.root]?.children) {
197
+ tree = fetched
198
+ source = 'live-partial'
199
+ fetchError = fetched.errors
200
+ } else {
201
+ fetchError = fetched.errors
202
+ }
203
+ }
204
+ if (!tree) tree = readJson(snapshotPath)
205
+ if (!tree) return { source: 'none', synced: false, fetchError, actions: [], missingTree: true }
206
+ const result = planSync(plan, tree)
207
+ return { source, fetchedAt: tree.fetchedAt ?? null, fetchError, ...result }
208
+ }
209
+
210
+ // The newest run whose spec is the issue, or whose saved tree contains it.
211
+ export function findRun(runsDir, ref) {
212
+ const key = keyOf(ref.repo, ref.number)
213
+ let best = null
214
+ let names = []
215
+ try { names = readdirSync(runsDir) } catch { return null }
216
+ for (const name of names) {
217
+ const dir = join(runsDir, name)
218
+ const planPath = join(dir, 'task-plan.json')
219
+ if (!existsSync(planPath)) continue
220
+ const plan = readJson(planPath)
221
+ const spec = specRef(plan)
222
+ const tree = readJson(join(dir, SNAPSHOT))
223
+ const match = (spec && keyOf(spec.repo, spec.number) === key) || Boolean(tree?.nodes?.[key])
224
+ if (!match) continue
225
+ const mtime = statSync(planPath).mtimeMs
226
+ if (!best || mtime > best.mtime) best = { dir, mtime }
227
+ }
228
+ return best?.dir ?? null
229
+ }
230
+
231
+ export function parseCliArgs(argv) {
232
+ const opts = { live: false, json: false, findRun: false }
233
+ for (let i = 0; i < argv.length; i++) {
234
+ const flag = argv[i]
235
+ if (flag === '--live') opts.live = true
236
+ else if (flag === '--json') opts.json = true
237
+ else if (flag === '--find-run') opts.findRun = true
238
+ else if (flag === '--exit-actions') opts.exitActions = true
239
+ else if (['--run', '--runs', '--issue'].includes(flag) && argv[i + 1] !== undefined) opts[flag.slice(2)] = argv[++i]
240
+ else throw new PlanSyncError('usage: plan-sync.mjs --run <run dir> [--live] [--json] [--exit-actions] | --find-run --runs <runs dir> --issue <owner/name#123> [--json] [--exit-actions]; exit 0 when it ran (the outcome is in the output), 2 on error')
241
+ }
242
+ if (opts.findRun ? !(opts.runs && opts.issue) : !opts.run) throw new PlanSyncError('usage: plan-sync.mjs --run <run dir> [--live] [--json] [--exit-actions] | --find-run --runs <runs dir> --issue <owner/name#123> [--json] [--exit-actions]; exit 0 when it ran (the outcome is in the output), 2 on error')
243
+ return opts
244
+ }
245
+
246
+ if (isMainModule(import.meta.url)) {
247
+ try {
248
+ const opts = parseCliArgs(process.argv.slice(2))
249
+ if (opts.findRun) {
250
+ const dir = findRun(opts.runs, parseIssueRef(opts.issue))
251
+ if (opts.json) console.log(JSON.stringify({ found: Boolean(dir), dir }, null, 2))
252
+ else if (dir) console.log(dir)
253
+ else process.stderr.write(`plan-sync: no run under ${opts.runs} for ${opts.issue}\n`)
254
+ process.exitCode = opts.exitActions && !dir ? 1 : 0
255
+ } else {
256
+ const result = syncRun(opts.run, { live: opts.live })
257
+ if (opts.json) console.log(JSON.stringify(result, null, 2))
258
+ else {
259
+ for (const a of result.actions) process.stdout.write(`${a.action.padEnd(17)}${a.detail}\n`)
260
+ if (result.fetchError) process.stdout.write(`fetch failed, ${result.source === 'live-partial' ? 'partial tree used' : 'saved snapshot used'}: ${result.fetchError.map((e) => `${e.key}: ${e.error}`).join('; ')}\n`)
261
+ process.stdout.write(result.synced ? `tree ${result.source}${result.fetchedAt ? ` ${result.fetchedAt}` : ''}; ${result.actions.length} due\n` : result.missingTree ? 'no issue tree available (no saved snapshot and no successful fetch): rerun with --live\n' : 'no issue tree to sync\n')
262
+ }
263
+ process.exitCode = opts.exitActions ? (result.missingTree ? 2 : result.actions.length ? 1 : 0) : 0
264
+ }
265
+ } catch (error) {
266
+ process.stderr.write(`plan-sync: ${error.message}\n`)
267
+ process.exitCode = 2
268
+ }
269
+ }
@@ -0,0 +1,156 @@
1
+ import { test } from 'node:test'
2
+ import assert from 'node:assert/strict'
3
+ import { spawnSync } from 'node:child_process'
4
+ import { mkdirSync, mkdtempSync, readFileSync, utimesSync, writeFileSync } from 'node:fs'
5
+ import { tmpdir } from 'node:os'
6
+ import { dirname, join } from 'node:path'
7
+ import { fileURLToPath } from 'node:url'
8
+
9
+ import { SNAPSHOT, classify, findRun, parseCliArgs, PlanSyncError, planSync, syncRun } from './plan-sync.mjs'
10
+
11
+ const script = join(dirname(fileURLToPath(import.meta.url)), 'plan-sync.mjs')
12
+
13
+ // A tree in issue-tree.mjs's shape from { "n": { state, children: [n], blockedBy: [n] } } in o/r.
14
+ function tree(spec, issues, { complete = true } = {}) {
15
+ const nodes = {}
16
+ const key = (n) => (String(n).includes('#') ? String(n) : `o/r#${n}`)
17
+ for (const [n, i] of Object.entries(issues)) {
18
+ nodes[key(n)] = { key: key(n), repo: 'o/r', number: Number(n), title: `t${n}`, state: i.state ?? 'open', labels: [], blockedBy: (i.blockedBy ?? []).map((b) => ({ key: key(b), state: issues[b]?.state ?? i.blockerState ?? 'open' })), children: (i.children ?? []).map(key), parent: null }
19
+ }
20
+ for (const node of Object.values(nodes)) for (const c of node.children) if (nodes[c]) nodes[c].parent = node.key
21
+ return { root: key(spec), complete, errors: complete ? [] : [{ key: key(spec), error: 'HTTP 502' }], nodes }
22
+ }
23
+ const plan = (units, extra = {}) => ({ spec: 'o/r#1', units, ...extra })
24
+ const actionsOf = (result) => result.actions.map((a) => `${a.action} ${a.unit}`)
25
+
26
+ test('a held issue whose filed prerequisite closed stays a unit, and a new open issue is added', () => {
27
+ // fmm #1343: its prerequisite #1659 was filed under it and closed; the old check dropped #1343.
28
+ const t = tree(1, { 1: { children: [1343, 1142, 1700] }, 1343: { children: [1659] }, 1659: { state: 'closed' }, 1142: { blockedBy: [1343] }, 1700: {} })
29
+ assert.equal(classify(t)['o/r#1343'], 'unit')
30
+ const result = planSync(plan([{ id: '1343', status: 'blocked' }, { id: '1142', status: 'pending', dependsOn: ['1343'] }]), t)
31
+ assert.deepEqual(actionsOf(result), ['add-unit 1700'])
32
+ })
33
+
34
+ test('add-unit carries blockedBy, expanding a blocking container into its open leaves', () => {
35
+ const t = tree(1, { 1: { children: [2, 5] }, 2: { children: [3, 4] }, 3: {}, 4: { state: 'closed' }, 5: { blockedBy: [2] } })
36
+ const result = planSync(plan([{ id: '3', status: 'pending' }]), t)
37
+ assert.deepEqual(result.actions.map((a) => [a.action, a.unit, a.dependsOn]), [['add-unit', '5', ['3']]])
38
+ })
39
+
40
+ test('a container\'s link is never inherited: move-link asks for it on the sub-issues that wait', () => {
41
+ // A link on a split issue fanned out to all five of its slices, though two used the blocker.
42
+ const t = tree(1, { 1: { children: [2, 9] }, 2: { children: [3, 4], blockedBy: [9] }, 3: {}, 4: {}, 9: {} })
43
+ const result = planSync(plan([{ id: '3', status: 'pending', dependsOn: ['7'] }, { id: '4', status: 'pending' }, { id: '9', status: 'pending' }]), t)
44
+ assert.deepEqual(result.actions.map((a) => [a.action, a.unit]), [['move-link', '2']])
45
+ assert.match(result.actions[0].detail, /o\/r#2 has 2 open sub-issues \(3, 4\) and is blocked by o\/r#9/)
46
+ const moved = tree(1, { 1: { children: [2, 9] }, 2: { children: [3, 4] }, 3: { blockedBy: [9] }, 4: {}, 9: {} })
47
+ const after = planSync(plan([{ id: '3', status: 'pending', dependsOn: ['7'] }, { id: '4', status: 'pending' }, { id: '9', status: 'pending' }]), moved)
48
+ assert.deepEqual(after.actions.map((a) => [a.action, a.unit, a.dependsOn]), [['set-deps', '3', ['7', '9']]], 'only the linked sub-issue waits; set-deps keeps the explorer-recorded 7')
49
+ const done = tree(1, { 1: { children: [2, 9] }, 2: { children: [3], blockedBy: [9] }, 3: {}, 9: { state: 'closed' } })
50
+ assert.deepEqual(planSync(plan([{ id: '3', status: 'pending' }]), done).actions, [], 'a closed blocker needs no move')
51
+ })
52
+
53
+ test('closed, split, and moved-out issues drop their units; done units are left alone', () => {
54
+ const t = tree(1, { 1: { children: [2, 3, 5] }, 2: { state: 'closed' }, 3: { children: [4] }, 4: {}, 5: { state: 'closed' } })
55
+ const result = planSync(plan([
56
+ { id: '2', status: 'in-flight' }, { id: '3', status: 'pending' }, { id: '4', status: 'pending' },
57
+ { id: '5', status: 'succeeded' }, { id: '8', status: 'pending' },
58
+ ]), t)
59
+ assert.deepEqual(actionsOf(result), ['drop-unit 2', 'drop-unit 3', 'drop-unit 8'])
60
+ })
61
+
62
+ test('a partial tree never drops a unit or changes dependencies', () => {
63
+ const t = tree(1, { 1: { children: [3, 5] }, 3: { blockedBy: [5] }, 5: {} }, { complete: false })
64
+ const result = planSync(plan([{ id: '3', status: 'pending' }, { id: '8', status: 'pending' }]), t)
65
+ assert.equal(result.partial, true)
66
+ assert.deepEqual(actionsOf(result), ['add-unit 5'])
67
+ })
68
+
69
+ test('an open blocker outside the tree is reported; a closed one is satisfied', () => {
70
+ const t = tree(1, { 1: { children: [3, 4] }, 3: { blockedBy: ['x/y#9'] }, 4: { blockedBy: ['x/y#10'], blockerState: 'closed' } })
71
+ const result = planSync(plan([{ id: '3', status: 'pending' }, { id: '4', status: 'pending' }]), t)
72
+ assert.deepEqual(result.actions.map((a) => [a.action, a.unit, a.blocker]), [['blocked-outside', '3', 'x/y#9']])
73
+ })
74
+
75
+ test('excluded issues and earlier merges are known; every other open leaf joins the run; a local spec has nothing to sync', () => {
76
+ const t = tree(1, { 1: { children: [2, 3, 4, 5] }, 2: {}, 3: {}, 4: {}, 5: {} })
77
+ const result = planSync(plan([{ id: '2', status: 'pending' }], { excluded: [{ issue: 'o/r#3', reason: 'release gate' }], merged: ['4'] }), t)
78
+ assert.deepEqual(result.actions.map((a) => `${a.action} ${a.unit}`), ['add-unit 5'], 'no wave keeps an open issue out of the run')
79
+ assert.equal(planSync({ spec: 'docs/spec.md', units: [{ id: 'one' }] }, t).synced, false)
80
+ })
81
+
82
+ function runDir(planBody, snapshot) {
83
+ const dir = mkdtempSync(join(tmpdir(), 'plan-sync-'))
84
+ writeFileSync(join(dir, 'task-plan.json'), JSON.stringify(planBody))
85
+ if (snapshot) writeFileSync(join(dir, SNAPSHOT), JSON.stringify(snapshot))
86
+ return dir
87
+ }
88
+
89
+ test('a live sync saves a complete tree; a failed fetch falls back to the snapshot and saves nothing', () => {
90
+ const saved = tree(1, { 1: { children: [2] }, 2: {} })
91
+ const dir = runDir(plan([{ id: '2', status: 'pending' }]), saved)
92
+ const fresh = tree(1, { 1: { children: [2, 3] }, 2: {}, 3: {} })
93
+ const live = syncRun(dir, { live: true, fetch: () => fresh, now: () => new Date('2026-10-12T00:00:00Z') })
94
+ assert.equal(live.source, 'live')
95
+ assert.deepEqual(actionsOf(live), ['add-unit 3'])
96
+ assert.equal(JSON.parse(readFileSync(join(dir, SNAPSHOT), 'utf8')).fetchedAt, '2026-10-12T00:00:00.000Z')
97
+ const down = syncRun(dir, { live: true, fetch: () => ({ root: 'o/r#1', complete: false, errors: [{ key: 'o/r#1', error: 'HTTP 502' }], nodes: {} }) })
98
+ assert.equal(down.source, 'snapshot')
99
+ assert.match(down.fetchError[0].error, /502/)
100
+ assert.deepEqual(actionsOf(down), ['add-unit 3'])
101
+ const offline = syncRun(dir, { fetch: () => { throw new Error('no call without --live') } })
102
+ assert.equal(offline.source, 'snapshot')
103
+ })
104
+
105
+ test('find-run picks the newest run whose spec or saved tree holds the issue', () => {
106
+ const runs = mkdtempSync(join(tmpdir(), 'plan-sync-runs-'))
107
+ const make = (name, body, snap, mtime) => {
108
+ mkdirSync(join(runs, name))
109
+ writeFileSync(join(runs, name, 'task-plan.json'), JSON.stringify(body))
110
+ if (snap) writeFileSync(join(runs, name, SNAPSHOT), JSON.stringify(snap))
111
+ utimesSync(join(runs, name, 'task-plan.json'), mtime, mtime)
112
+ }
113
+ make('old', plan([]), null, 1000)
114
+ make('followup', { spec: 'o/r#1512', units: [] }, tree(1512, { 1512: { children: [1343] }, 1343: {} }), 2000)
115
+ make('other', { spec: 'o/r#9', units: [] }, null, 3000)
116
+ assert.equal(findRun(runs, { repo: 'o/r', number: 1 }), join(runs, 'old'))
117
+ assert.equal(findRun(runs, { repo: 'o/r', number: 1343 }), join(runs, 'followup'))
118
+ assert.equal(findRun(runs, { repo: 'o/r', number: 77 }), null)
119
+ })
120
+
121
+ test('CLI exits 0 with or without actions and without a tree, 2 on bad input; --exit-actions restores the old codes', () => {
122
+ const dir = runDir(plan([{ id: '2', status: 'pending' }]), tree(1, { 1: { children: [2, 3] }, 2: {}, 3: {} }))
123
+ const due = spawnSync(process.execPath, [script, '--run', dir], { encoding: 'utf8' })
124
+ assert.equal(due.status, 0, due.stderr)
125
+ assert.match(due.stdout, /^add-unit +add unit 3/m)
126
+ assert.equal(JSON.parse(spawnSync(process.execPath, [script, '--run', dir, '--json'], { encoding: 'utf8' }).stdout).actions[0].action, 'add-unit')
127
+ assert.equal(spawnSync(process.execPath, [script, '--run', dir, '--exit-actions'], { encoding: 'utf8' }).status, 1)
128
+ const inSync = runDir(plan([{ id: '2', status: 'pending' }]), tree(1, { 1: { children: [2] }, 2: {} }))
129
+ assert.equal(spawnSync(process.execPath, [script, '--run', inSync], { encoding: 'utf8' }).status, 0)
130
+ assert.equal(spawnSync(process.execPath, [script, '--run', inSync, '--exit-actions'], { encoding: 'utf8' }).status, 0)
131
+ const noTree = runDir(plan([]))
132
+ const missing = spawnSync(process.execPath, [script, '--run', noTree], { encoding: 'utf8' })
133
+ assert.equal(missing.status, 0, missing.stderr)
134
+ assert.match(missing.stdout, /no issue tree available/)
135
+ assert.equal(JSON.parse(spawnSync(process.execPath, [script, '--run', noTree, '--json'], { encoding: 'utf8' }).stdout).missingTree, true)
136
+ assert.equal(spawnSync(process.execPath, [script, '--run', noTree, '--exit-actions'], { encoding: 'utf8' }).status, 2)
137
+ assert.equal(spawnSync(process.execPath, [script, '--run', join(noTree, 'nope')], { encoding: 'utf8' }).status, 2)
138
+ assert.equal(spawnSync(process.execPath, [script], { encoding: 'utf8' }).status, 2)
139
+ assert.throws(() => parseCliArgs(['--find-run', '--runs', 'x']), PlanSyncError)
140
+ })
141
+
142
+ test('--find-run exits 0 whether or not a run is found; --json and --exit-actions say which', () => {
143
+ const runs = mkdtempSync(join(tmpdir(), 'plan-sync-find-'))
144
+ const empty = (...extra) => spawnSync(process.execPath, [script, '--find-run', '--runs', runs, '--issue', 'o/r#77', ...extra], { encoding: 'utf8' })
145
+ const none = empty()
146
+ assert.equal(none.status, 0, none.stderr)
147
+ assert.equal(none.stdout, '', 'nothing on stdout when no run is found')
148
+ assert.deepEqual(JSON.parse(empty('--json').stdout), { found: false, dir: null })
149
+ assert.equal(empty('--exit-actions').status, 1)
150
+ mkdirSync(join(runs, 'one'))
151
+ writeFileSync(join(runs, 'one', 'task-plan.json'), JSON.stringify(plan([], { spec: 'o/r#77' })))
152
+ const found = empty('--json')
153
+ assert.equal(found.status, 0, found.stderr)
154
+ assert.deepEqual(JSON.parse(found.stdout), { found: true, dir: join(runs, 'one') })
155
+ assert.equal(empty('--exit-actions').status, 0)
156
+ })