rungate 0.8.25 → 0.8.27

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.
@@ -0,0 +1,252 @@
1
+ /**
2
+ * `.github/workflows/specs-placed.yml`, generated — SC-2780, ADR-018 Decision 1.
3
+ *
4
+ * A push to main that changes `specs/` runs every opted-in family through the
5
+ * engine with no command typed by hand: milestones from each family's
6
+ * placement table, each open issue moved into the phase its criteria hold,
7
+ * the phase-order links, the queue label, and the board's Criteria column.
8
+ *
9
+ * ## The families are read at RUN time, from the specs
10
+ *
11
+ * `rungate plan-issues --families` prints the opted-in families, one
12
+ * `<prefix><TAB><spec>` line each. It is the same reading `plan-issues
13
+ * --place` takes, so the loop and the placement never disagree about which
14
+ * specs are on the board, and a newly opted-in spec needs no re-scaffold.
15
+ * A spec whose `board:` block or placement table cannot be read makes that
16
+ * command refuse, so the run goes red by name instead of skipping the spec.
17
+ *
18
+ * ## The order is the one each step needs
19
+ *
20
+ * plan-spec per family, so every phase has its milestone
21
+ * plan-issues --place, so issues sit in the phase their criteria hold
22
+ * plan-deps per family, so the links follow the issues' NEW milestones
23
+ * board-mirror --queue-label, because a milestone set by GITHUB_TOKEN
24
+ * fires no `milestoned` event, so phase-order.yml never sees it
25
+ * board-mirror the Criteria column on the board
26
+ *
27
+ * Placing before `plan-deps` is ADR-019 Decision 2: #1722's links follow its
28
+ * move into Phase 10 in the same run.
29
+ *
30
+ * ## It never writes while an earlier ADR placement is running
31
+ *
32
+ * One merge often changes both `specs/` and an ADR, which fires this and
33
+ * `adr-accepted.yml` together, and both write milestones and links (ADR-018,
34
+ * "Not decided here"). A shared `concurrency:` group would serialise them
35
+ * but cancels whatever is pending behind the running run. A cancelled
36
+ * `adr-accepted` run is an accepted ADR whose plan is never placed, with
37
+ * nothing saying so. So this workflow keeps a group of its own, which only
38
+ * cancels its own pending runs, and each of those re-reads the whole tree.
39
+ * Its first step then waits until no `adr-accepted` run created before it is
40
+ * still unfinished.
41
+ *
42
+ * ## It calls the published CLI
43
+ *
44
+ * Like every generated workflow it runs `bunx rungate@<version>`, so the
45
+ * commands it calls must be in a published release before this file is
46
+ * (`docs/guides/RELEASING.md`, "A command a generated workflow calls ships
47
+ * BEFORE the workflow that calls it"). `--families` and `--place` shipped in
48
+ * 0.8.26.
49
+ */
50
+
51
+ import { ADR_ACCEPTED_WORKFLOW_FILE } from "./adr-accepted-workflow";
52
+
53
+ /** The file this module generates, under `.github/workflows/`. */
54
+ export const SPECS_PLACED_WORKFLOW_FILE = "specs-placed.yml";
55
+
56
+ /** The one job in it. */
57
+ export const SPECS_PLACED_JOB = "run-the-engine";
58
+
59
+ /**
60
+ * Every command the job calls, in run order. Each must be registered in
61
+ * `lib/cli-commands.ts`, or the workflow calls a command `bin/rungate.ts`
62
+ * refuses (#675's defect).
63
+ */
64
+ export const SPECS_PLACED_COMMANDS = ["plan-issues", "plan-spec", "plan-deps", "board-mirror"] as const;
65
+
66
+ /** Its own group: it cancels only its own pending runs, each of which re-reads the tree. */
67
+ export const SPECS_PLACED_GROUP = "specs-placed";
68
+
69
+ /** How long the first step waits for an earlier ADR placement, in 20-second polls. */
70
+ export const WAIT_POLLS = 90;
71
+
72
+ export interface SpecsPlacedWorkflowOptions {
73
+ /** The `runs-on:` value, already JSON-quoted by the caller. */
74
+ runsOn: string;
75
+ /** The pinned `actions/checkout` reference. */
76
+ checkout: string;
77
+ /** The pinned `oven-sh/setup-bun` reference. */
78
+ setupBun: string;
79
+ /** The `with:` body of that step, at ten spaces — the project's single bun declaration (#622). */
80
+ setupBunWith: string;
81
+ /** The step's `env:` block, from `setupBunEnv` (#2039). */
82
+ setupBunEnv: string;
83
+ /** The published harness version every step runs through `bunx`. */
84
+ version: string;
85
+ }
86
+
87
+ /**
88
+ * The wait step's script. The GitHub API lists the ADR workflow's runs; any
89
+ * not yet `completed` and created before this run is waited for. Runs created
90
+ * AFTER this one are not, so the two workflows can never wait on each other.
91
+ * Every page is read: the list is newest-first, so an earlier run still going
92
+ * falls off page one once 100 newer runs exist. A list it cannot read fails
93
+ * the step, through `pipefail`, rather than reading as "none unfinished".
94
+ */
95
+ export function buildWaitScript(): string {
96
+ return `set -euo pipefail
97
+ mine=$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" --jq .created_at)
98
+ for poll in $(seq 1 ${WAIT_POLLS}); do
99
+ earlier=$(gh api --paginate "repos/$GITHUB_REPOSITORY/actions/workflows/${ADR_ACCEPTED_WORKFLOW_FILE}/runs?per_page=100" --jq ".workflow_runs[] | select(.status != \\"completed\\" and .created_at < \\"$mine\\") | .id" | paste -sd ' ' -)
100
+ if [ -z "$earlier" ]; then
101
+ echo "No earlier ${ADR_ACCEPTED_WORKFLOW_FILE} run is unfinished; going ahead."
102
+ exit 0
103
+ fi
104
+ echo "Waiting for ${ADR_ACCEPTED_WORKFLOW_FILE} run(s) $earlier to finish (poll $poll of ${WAIT_POLLS})."
105
+ sleep 20
106
+ done
107
+ echo "::error::${ADR_ACCEPTED_WORKFLOW_FILE} run(s) $earlier are still unfinished after $((${WAIT_POLLS} * 20 / 60)) minutes, so this run wrote nothing rather than write the board beside them. Re-run it once they finish."
108
+ exit 1`;
109
+ }
110
+
111
+ /**
112
+ * A loop over the families file, one command per family. It reads the file on
113
+ * descriptor 3, so a command inside the loop that reads standard input cannot
114
+ * swallow the families after it. One family's refusal does not stop the next;
115
+ * the step exits red at the end, naming every family that refused.
116
+ */
117
+ export function buildFamilyLoop(version: string, command: (cli: string) => string, what: string): string {
118
+ const cli = `bunx rungate@${version}`;
119
+ return `set -uo pipefail
120
+ refused=""
121
+ while IFS=$'\\t' read -r prefix spec <&3; do
122
+ [ -n "$prefix" ] || continue
123
+ echo "== $prefix ($spec)"
124
+ if ! ${command(cli)}; then
125
+ refused="$refused [$prefix]"
126
+ fi
127
+ done 3< families.tsv
128
+ if [ -n "$refused" ]; then
129
+ echo "::error::${what} refused for$refused. Every other family was still run."
130
+ exit 1
131
+ fi`;
132
+ }
133
+
134
+ /** The whole `specs-placed.yml` body. */
135
+ export function buildSpecsPlacedWorkflow(opts: SpecsPlacedWorkflowOptions): string {
136
+ const cli = `bunx rungate@${opts.version}`;
137
+ const indent = (script: string) => script.split("\n").map(l => (l === "" ? "" : ` ${l}`)).join("\n");
138
+ const milestones = buildFamilyLoop(
139
+ opts.version,
140
+ c => `${c} plan-spec "$spec" --repo "$GITHUB_REPOSITORY" --prefix "$prefix" --write`,
141
+ "plan-spec",
142
+ );
143
+ const links = buildFamilyLoop(
144
+ opts.version,
145
+ c => `${c} plan-deps --repo "$GITHUB_REPOSITORY" --milestone-prefix "$prefix" --write`,
146
+ "plan-deps",
147
+ );
148
+
149
+ return `# Managed by rungate — do not edit. Opt a spec in with
150
+ # board: { scope: active, prefix: <Name> } in its frontmatter and give it a
151
+ # placement table; nothing here names a spec.
152
+ #
153
+ # SC-2780 (ADR-018 Decision 1): a push to main that changes specs/ runs every
154
+ # opted-in family through the engine, with no command typed by hand.
155
+ #
156
+ # plan-issues --families which specs are on the board, read at run time
157
+ # plan-spec each family's milestones
158
+ # plan-issues --place each open issue into the phase its criteria hold
159
+ # plan-deps each family's phase-order links, after the moves
160
+ # board-mirror the queue label, then the Criteria column
161
+ #
162
+ # Every command is idempotent, so a re-run writes only what is missing.
163
+ #
164
+ # CREDENTIALS, SPLIT BY STEP. Issue, milestone, label and link writes use the
165
+ # job's own GITHUB_TOKEN. RUNGATE_PROJECT_TOKEN reaches only the board step.
166
+ name: Specs changed — run every opted-in family through the engine
167
+
168
+ on:
169
+ push:
170
+ branches: [main]
171
+ paths: ["specs/**"]
172
+
173
+ permissions:
174
+ contents: read
175
+ # Milestones, issues, labels and blocked-by links.
176
+ issues: write
177
+ # The wait step lists adr-accepted.yml's runs.
178
+ actions: read
179
+
180
+ # Its own group, never adr-accepted's: a shared group cancels the run pending
181
+ # behind the running one, and a cancelled adr-accepted run is a plan that is
182
+ # never placed. The wait step below keeps the two from writing at once.
183
+ concurrency:
184
+ group: ${SPECS_PLACED_GROUP}
185
+ cancel-in-progress: false
186
+
187
+ jobs:
188
+ ${SPECS_PLACED_JOB}:
189
+ runs-on: ${opts.runsOn}
190
+ steps:
191
+ - name: Wait for an earlier ADR placement to finish
192
+ env:
193
+ GH_TOKEN: \${{ github.token }}
194
+ run: |
195
+ ${indent(buildWaitScript())}
196
+
197
+ - uses: ${opts.checkout}
198
+ - uses: ${opts.setupBun}
199
+ with:
200
+ ${opts.setupBunWith}
201
+ ${opts.setupBunEnv}
202
+ # No token: the package is fetched before any step that holds one.
203
+ - id: families
204
+ name: Which specs are on the board?
205
+ run: |
206
+ ${cli} plan-issues --families > families.tsv
207
+ echo "Opted-in families:"
208
+ cat families.tsv
209
+ if [ -s families.tsv ]; then echo "any=true" >> "$GITHUB_OUTPUT"; else echo "any=false" >> "$GITHUB_OUTPUT"; fi
210
+
211
+ - name: Milestones from each family's placement table
212
+ if: steps.families.outputs.any == 'true'
213
+ env:
214
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
215
+ run: |
216
+ ${indent(milestones)}
217
+
218
+ - name: Each open issue into the phase its criteria hold
219
+ if: steps.families.outputs.any == 'true'
220
+ env:
221
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
222
+ run: ${cli} plan-issues --place --repo "$GITHUB_REPOSITORY" --write
223
+
224
+ # \`!cancelled()\`: each of these reads the whole tracker and writes only
225
+ # what is missing, so it never depends on an earlier step succeeding
226
+ # (#2239). The run is still red when one of those failed.
227
+ - name: Phase-order links for each family
228
+ if: \${{ !cancelled() && steps.families.outputs.any == 'true' }}
229
+ env:
230
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
231
+ run: |
232
+ ${indent(links)}
233
+
234
+ - name: Queue label on every opted-in family's phase issue
235
+ if: \${{ !cancelled() && steps.families.outputs.any == 'true' }}
236
+ env:
237
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
238
+ run: ${cli} board-mirror --queue-label --repo "$GITHUB_REPOSITORY" --write
239
+
240
+ - name: Criteria column on the board
241
+ if: \${{ !cancelled() && steps.families.outputs.any == 'true' }}
242
+ env:
243
+ GITHUB_TOKEN: \${{ secrets.RUNGATE_PROJECT_TOKEN }}
244
+ PROJECT_ID: \${{ vars.RUNGATE_PROJECT_ID }}
245
+ run: |
246
+ if [ -z "$PROJECT_ID" ]; then
247
+ echo "::error::UNMEASURED — RUNGATE_PROJECT_ID is not set, so there is no board to write."
248
+ exit 1
249
+ fi
250
+ ${cli} board-mirror --project "$PROJECT_ID" --write
251
+ `;
252
+ }
@@ -49,6 +49,7 @@ import {
49
49
  buildAiReviewUnmeasuredWorkflow,
50
50
  } from "./ai-review-unmeasured-workflow";
51
51
  import { buildAdrAcceptedWorkflow } from "./adr-accepted-workflow";
52
+ import { buildSpecsPlacedWorkflow } from "./specs-placed-workflow";
52
53
  import { buildClosingReferencesWorkflow } from "./closing-references-workflow";
53
54
  import { buildIntakeWorkflow } from "./intake-workflow";
54
55
  import { buildBoardReadyWorkflow } from "./board-ready-workflow";
@@ -2908,6 +2909,16 @@ function revocationActions(label: string, revoked: readonly RevokedSubKey[]): st
2908
2909
  const topLevel = r.section.split(".")[0];
2909
2910
  const keep =
2910
2911
  `Name \`${topLevel}\` in \`ci.workflowOverrides\` to keep it, and re-scaffold.`;
2912
+ // #2292: an authored path brought to the generator's value is not a
2913
+ // withdrawal, and calling it one would tell the consumer something was
2914
+ // taken away when something was written.
2915
+ if (r.reason === "asserted") {
2916
+ return (
2917
+ `REWRITTEN: ${label} now declares \`${r.section}: ${r.key}\` as this version of the ` +
2918
+ `generator writes it — the harness authors that path, so a stale or hand-set value ` +
2919
+ `there is replaced on every scaffold. ${keep}`
2920
+ );
2921
+ }
2911
2922
  return r.reason === "authored"
2912
2923
  ? `REVOKED: ${label} no longer declares \`${r.section}: ${r.key}\` — the harness ` +
2913
2924
  `authors that path and this version of the generator does not emit it, so the ` +
@@ -4380,6 +4391,8 @@ ${setupBunEnv(" ")}
4380
4391
  : `permissions:\n contents: read\n # Mint the OIDC token Workload Identity Federation exchanges (#631).\n id-token: write\n # Count this pull request's previous AI Review runs — the round budget (#1168).\n actions: read\n${ledgerPermission}`;
4381
4392
 
4382
4393
  const aiReviewYml = `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
4394
+ # The trigger types under on.pull_request are the harness's and are rewritten
4395
+ # on every scaffold; add your own triggers or jobs alongside (#2292).
4383
4396
  #
4384
4397
  ${buildOutcomesHeader(vertex)}#
4385
4398
  # This job is deliberately unconditional. A job skipped by a condition reports
@@ -4492,6 +4505,18 @@ ${buildAuthDetectStep(vertex)}${buildReviewRunStep(
4492
4505
  milestonePrefix: boardInputs.milestonePrefix,
4493
4506
  });
4494
4507
 
4508
+ // SC-2780, ADR-018 Decision 1: a push to main that changes specs/ runs
4509
+ // every opted-in family through the engine. The families are read at run
4510
+ // time by the published CLI, so nothing here names a spec.
4511
+ const specsPlacedYml = buildSpecsPlacedWorkflow({
4512
+ runsOn,
4513
+ checkout: actionRef("actions/checkout"),
4514
+ setupBun: actionRef("oven-sh/setup-bun"),
4515
+ setupBunWith: bunStep,
4516
+ setupBunEnv: setupBunEnv(" "),
4517
+ version: harnessVersion(),
4518
+ });
4519
+
4495
4520
  // #2045, ADR-014 row 2: the closing-references check, generated so a
4496
4521
  // consumer gets ADR-013 rule 9 step 4 and this repository's copy is the
4497
4522
  // generated one. It calls the published CLI, at the generating version.
@@ -4555,7 +4580,7 @@ ${buildAuthDetectStep(vertex)}${buildReviewRunStep(
4555
4580
  // lib/conformity.ts reads back, and the two are held together by
4556
4581
  // test/ai-review-workflow.test.ts AC-1, which looks for the constant's
4557
4582
  // filename in what this loop actually wrote.
4558
- for (const [name, content] of [["ci.yml", ciYml], ["gates.yml", gatesYml], ["ai-review.yml", aiReviewYml], ["ai-review-unmeasured.yml", aiReviewUnmeasuredYml], ["adr-accepted.yml", adrAcceptedYml], ["closing-references.yml", closingReferencesYml], ["board-ready.yml", boardReadyYml], ["board-intake.yml", boardIntakeYml], ["intake.yml", intakeYml]] as const) {
4583
+ for (const [name, content] of [["ci.yml", ciYml], ["gates.yml", gatesYml], ["ai-review.yml", aiReviewYml], ["ai-review-unmeasured.yml", aiReviewUnmeasuredYml], ["adr-accepted.yml", adrAcceptedYml], ["closing-references.yml", closingReferencesYml], ["board-ready.yml", boardReadyYml], ["board-intake.yml", boardIntakeYml], ["intake.yml", intakeYml], ["specs-placed.yml", specsPlacedYml]] as const) {
4559
4584
  const label = `.github/workflows/${name}`;
4560
4585
  try {
4561
4586
  // Keyed by FILE, and the lookup is here because this loop is the only