rungate 0.8.17 → 0.8.19

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.
package/gates/.gate-salt CHANGED
@@ -1 +1 @@
1
- 59ff9d2ffba3c61eb5cb8df8a3d5dcb4ca20c72e578589fd317a5ecac368d2c2
1
+ 1267e343f5b54c7a006014564da4b6b404022b6f2934457d083b0f37734afe18
@@ -274,6 +274,14 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
274
274
  "[--top-up] [--moving-issue <n>] [--actor <login>] [--write] (at least one of --closed-issue, --top-up; " +
275
275
  "--project defaults to board.id in the rungate config)",
276
276
  },
277
+ // #2173. For a generated workflow that works in shell (`board-intake.yml`,
278
+ // #2166) and so cannot read the config through the loader itself. No
279
+ // `projectRootFlag`: it reads `process.cwd()`, which the child inherits.
280
+ "board-id": {
281
+ script: "scripts/board-id.ts",
282
+ summary: "Print the board's node id from config",
283
+ usage: "rungate board-id [--project-root <dir>] (UNMEASURED and exit 2 when the config names no board)",
284
+ },
277
285
  // Reads a `gh pr view`-shaped payload on stdin, which the dispatcher passes
278
286
  // through (`stdio: "inherit"`), or `--fixture` offline.
279
287
  "audit-closing-references": {
@@ -435,9 +435,8 @@ description: Every command the rungate CLI exposes in this project, generated fr
435
435
 
436
436
  ## Command Routing
437
437
 
438
- Generated from the CLI's own command registry, so it cannot list a subset.
439
- Run one as \`${cliPrefix} <command>\`.
440
- \`${cliPrefix} --help\` prints each command's own arguments.
438
+ Generated from the CLI's command registry. Run one as
439
+ \`${cliPrefix} <command>\`; \`--help\` prints its arguments.
441
440
 
442
441
  ${commandRoutingTable()}
443
442
  `,
@@ -0,0 +1,248 @@
1
+ /**
2
+ * `.github/workflows/board-ready.yml`, generated — #2047, ADR-014 row 4,
3
+ * half of SC-2745 (`board-intake.yml` is #2166's).
4
+ *
5
+ * It keeps the board's Ready lane full from the events the repository
6
+ * already emits (#1744): a close fans out to what that close freed, and the
7
+ * other `issues:` types top the lane up from every open issue (#1842). It was
8
+ * hand-written and caller-owned while it ran `bun scripts/board-ready.ts`
9
+ * from this checkout. A consumer has no `scripts/` (ADR-014 decision 2), so
10
+ * the scaffold now writes it and this repository's copy is the generated one.
11
+ *
12
+ * ## It names no board
13
+ *
14
+ * The step passes no `--project`. `rungate board-ready` reads `board.id`
15
+ * from the checked-out tree's rungate config since #2165, so the board's
16
+ * identity lives in one place a consumer already edits, and no generated
17
+ * workflow carries a project id or URL (SC-2745). That is why the job still
18
+ * checks the tree out: the config is the input.
19
+ *
20
+ * ## What is kept from the hand-written file, and why each piece is load-bearing
21
+ *
22
+ * Every property below is asserted in `test/board-ready-fanout.test.ts`, so
23
+ * the record of WHY lives here, beside the bytes, and the generated YAML
24
+ * carries one line each.
25
+ *
26
+ * - **No schedule (BR-12).** A cron is the thing #1744 exists to remove.
27
+ * - **The trust gate runs first and needs no checkout.** `issues:` events on
28
+ * a public repository are triggerable by anyone, and the job holds a
29
+ * board-writing PAT. The gate authorises the repository OWNER without an
30
+ * API call (BR-34: dispatch `42074926758` refused the owner because the
31
+ * PAT could not read the permission endpoint), then asks
32
+ * `collaborators/{actor}/permission` for anyone else. A permission nobody
33
+ * could read refuses. `WRITING_PERMISSIONS` in `lib/board-ready-fanout.ts`
34
+ * is the decider; BR-33 holds this `case` to the same set.
35
+ * - **The secret is `RUNGATE_PROJECT_TOKEN`, the env var
36
+ * `BOARD_PROJECT_TOKEN` (BR-13).** An absent secret is the empty string
37
+ * with no error, so a wrong name made the gate authorise nothing and go
38
+ * green (run `41950972882`).
39
+ * - **One run at a time, never cancelling the running one.** Occupancy is
40
+ * read once and written later, so two overlapping runs over-fill Ready.
41
+ * Every mode is a pure function of live state, so a dropped PENDING run
42
+ * loses nothing.
43
+ * - **No `continue-on-error` (BR-20).** It swallowed every failure into a
44
+ * green run.
45
+ * - **Every input reaches the script through `env:` (BR-16), and the
46
+ * argument list is an array with every expansion quoted (BR-54).** A
47
+ * dispatch `issue: "7 --write"` once word-split into a real write.
48
+ * - **`assigned` names the moving issue (BR-51, #1905); a close runs both
49
+ * sources (#1917).**
50
+ */
51
+
52
+ /** The file this module generates, under `.github/workflows/`. */
53
+ export const BOARD_READY_WORKFLOW_FILE = "board-ready.yml";
54
+
55
+ /** The one job in it. */
56
+ export const BOARD_READY_JOB = "move-freed-issues-to-ready";
57
+
58
+ /**
59
+ * The CLI command the step runs. `lib/cli-commands.ts` must register it, or
60
+ * the workflow calls a command `bin/rungate.ts` refuses (#675's defect).
61
+ */
62
+ export const BOARD_READY_COMMAND = "board-ready";
63
+
64
+ /**
65
+ * The trust gate's `run:` body. It needs only `gh`, which the runner has,
66
+ * so an untrusted trigger is refused before any checkout or install.
67
+ */
68
+ export function buildBoardReadyGateScript(): string {
69
+ return `if [ -z "$GH_TOKEN" ]; then
70
+ echo "::warning::UNMEASURED — BOARD_PROJECT_TOKEN is not set, so the acting identity could not be authorised and nothing was read. This run is UNMEASURED, not clean."
71
+ echo "trusted=false" >> "$GITHUB_OUTPUT"
72
+ exit 0
73
+ fi
74
+ # The owner may move its own board, with no API call and no token scope (BR-34).
75
+ if [ "$ACTOR" = "$OWNER" ]; then
76
+ echo "trusted=true" >> "$GITHUB_OUTPUT"
77
+ exit 0
78
+ fi
79
+ # A read that failed is "" and refuses with the rest — a permission we could
80
+ # not read is not a permission we were granted.
81
+ perm=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$ACTOR/permission" --jq .permission 2>/dev/null) || perm=""
82
+ case "$perm" in
83
+ admin|maintain|write)
84
+ echo "trusted=true" >> "$GITHUB_OUTPUT"
85
+ ;;
86
+ *)
87
+ echo "::warning::refusing to run: $ACTOR has permission \\"\${perm:-UNMEASURED}\\" on $GITHUB_REPOSITORY, and this job holds a board-writing credential."
88
+ echo "trusted=false" >> "$GITHUB_OUTPUT"
89
+ ;;
90
+ esac
91
+ `;
92
+ }
93
+
94
+ /**
95
+ * The fill step's `run:` body. Exported so a test can read THIS text rather
96
+ * than a paraphrase. No `--project`: the board is `board.id` in the config
97
+ * the checkout brought (#2165).
98
+ */
99
+ export function buildBoardReadyScript(version: string): string {
100
+ return `# An array, and every expansion quoted, so no input can become a flag (BR-54).
101
+ args=(--repo "$GITHUB_REPOSITORY" --actor "$ACTOR")
102
+ case "$MODE" in
103
+ closed)
104
+ case "$ISSUE" in
105
+ '' | *[!0-9]*)
106
+ echo "::warning::UNMEASURED — mode 'closed' needs a plain issue NUMBER and got \\"$ISSUE\\". Nothing was read."
107
+ exit 1
108
+ ;;
109
+ esac
110
+ # Both sources: a close frees a slot even when it blocked nothing (#1917).
111
+ args+=(--closed-issue "$ISSUE" --top-up)
112
+ ;;
113
+ assigned)
114
+ # board-flow moves this card out of Ready on the same event (#1905).
115
+ args+=(--top-up --moving-issue "$ISSUE")
116
+ ;;
117
+ top-up | unassigned | opened | reopened | milestoned | demilestoned | labeled | unlabeled)
118
+ args+=(--top-up)
119
+ ;;
120
+ *)
121
+ echo "::warning::UNMEASURED — unrecognised mode \\"$MODE\\", so no candidate source was chosen. Nothing was read."
122
+ exit 1
123
+ ;;
124
+ esac
125
+ if [ -n "$WRITE" ]; then
126
+ args+=(--write)
127
+ fi
128
+ echo "mode=$MODE, args=\${args[*]}"
129
+ # A tree with no board.id is UNMEASURED, an annotation and not a red run
130
+ # (.claude/rules/config-access.md). Only that refusal is: every other exit stands.
131
+ err="$RUNNER_TEMP/board-ready.stderr"
132
+ code=0
133
+ bunx rungate@${version} ${BOARD_READY_COMMAND} "\${args[@]}" 2>"$err" || code=$?
134
+ cat "$err" >&2
135
+ if [ "$code" -eq 2 ] && grep -q '^${NO_BOARD_REFUSAL}' "$err"; then
136
+ echo "::warning::UNMEASURED — no board.id in the rungate config, so there is no board to read. Set board.id and this runs."
137
+ exit 0
138
+ fi
139
+ exit "$code"
140
+ `;
141
+ }
142
+
143
+ /**
144
+ * How `rungate board-ready` begins its one refusal for a tree with no board
145
+ * (#2165). The fill step turns exactly that refusal into an annotation, so a
146
+ * consumer who sets the token before `board.id` gets a warning on each issue
147
+ * event and not a red run. `test/board-ready-fanout.test.ts` holds this to
148
+ * the script's own text, so the two cannot drift apart.
149
+ */
150
+ export const NO_BOARD_REFUSAL = "UNMEASURED: no board";
151
+
152
+ export interface BoardReadyWorkflowOptions {
153
+ /** The `runs-on:` value, already JSON-quoted by the caller. */
154
+ runsOn: string;
155
+ /** The pinned `actions/checkout` reference. */
156
+ checkout: string;
157
+ /** The pinned `oven-sh/setup-bun` reference. */
158
+ setupBun: string;
159
+ /** The `with:` body of that step, at ten spaces — the project's single bun declaration (#622). */
160
+ setupBunWith: string;
161
+ /** The step's `env:` block, from `setupBunEnv` (#2039). */
162
+ setupBunEnv: string;
163
+ /** The published harness version the step runs through `bunx`. */
164
+ version: string;
165
+ }
166
+
167
+ /** The whole `board-ready.yml` body. */
168
+ export function buildBoardReadyWorkflow(opts: BoardReadyWorkflowOptions): string {
169
+ const indent = (text: string, pad: string) =>
170
+ text
171
+ .trimEnd()
172
+ .split("\n")
173
+ .map(line => (line === "" ? "" : `${pad}${line}`))
174
+ .join("\n");
175
+
176
+ return `# Managed by rungate — do not edit. The board is board.id in .claude/rungate/config.json.
177
+ #
178
+ # Keeps the board's Ready lane full from the events the repository already
179
+ # emits (#1744). A close fans out to what it freed; the other issue events top
180
+ # the lane up from every open issue (#1842). No schedule: every trigger is an
181
+ # event a person caused. Generated since #2047, and it names no project id —
182
+ # \`rungate ${BOARD_READY_COMMAND}\` reads board.id from the checked-out config.
183
+ #
184
+ # Needs the RUNGATE_PROJECT_TOKEN secret: a token that can write the project
185
+ # board, which GITHUB_TOKEN cannot.
186
+ name: Board — keep Ready full from the events the repo already emits
187
+
188
+ on:
189
+ issues:
190
+ types: [closed, assigned, unassigned, opened, reopened, milestoned, demilestoned, labeled, unlabeled]
191
+ workflow_dispatch:
192
+ inputs:
193
+ mode:
194
+ description: "closed = fan out from \`issue\`; top-up = consider every open issue"
195
+ type: choice
196
+ default: closed
197
+ options: [closed, "top-up"]
198
+ issue:
199
+ description: "Issue number to fan out from (mode: closed only)"
200
+ required: false
201
+ type: string
202
+ write:
203
+ description: "Perform the moves (default: report only)"
204
+ type: boolean
205
+ default: false
206
+
207
+ permissions:
208
+ contents: read
209
+
210
+ # One run at a time: occupancy is read once and written later, so overlapping
211
+ # runs over-fill Ready. Never cancel the running one — it can be mid-write.
212
+ concurrency:
213
+ group: board-ready
214
+ cancel-in-progress: false
215
+
216
+ jobs:
217
+ ${BOARD_READY_JOB}:
218
+ runs-on: ${opts.runsOn}
219
+ steps:
220
+ # Before any checkout: an untrusted trigger is refused with only gh.
221
+ - id: gate
222
+ name: May the acting identity move the board?
223
+ env:
224
+ GH_TOKEN: \${{ secrets.RUNGATE_PROJECT_TOKEN }}
225
+ ACTOR: \${{ github.actor }}
226
+ OWNER: \${{ github.repository_owner }}
227
+ run: |
228
+ ${indent(buildBoardReadyGateScript(), " ")}
229
+ # The checkout is the config the command reads the board from.
230
+ - if: steps.gate.outputs.trusted == 'true'
231
+ uses: ${opts.checkout}
232
+ - if: steps.gate.outputs.trusted == 'true'
233
+ uses: ${opts.setupBun}
234
+ with:
235
+ ${opts.setupBunWith}
236
+ ${opts.setupBunEnv}
237
+ - name: Fill Ready from whatever this event changed
238
+ if: steps.gate.outputs.trusted == 'true'
239
+ env:
240
+ BOARD_PROJECT_TOKEN: \${{ secrets.RUNGATE_PROJECT_TOKEN }}
241
+ ISSUE: \${{ github.event.issue.number || inputs.issue }}
242
+ WRITE: \${{ (github.event_name == 'issues' || inputs.write) && '--write' || '' }}
243
+ MODE: \${{ github.event.action || inputs.mode }}
244
+ ACTOR: \${{ github.actor }}
245
+ run: |
246
+ ${indent(buildBoardReadyScript(opts.version), " ")}
247
+ `;
248
+ }
@@ -187,9 +187,19 @@ export const OWNED_FILES: OwnedFile[] = [
187
187
  path: ".github/workflows/closing-references.yml",
188
188
  strategy: "job-preserving",
189
189
  servedBy: "writeManagedFile (lib/scaffold/steps.ts) via mergeManagedWorkflow — the harness owns named jobs, not the file",
190
- customize: "Set the `RUNGATE_REQUIRE_CLOSING_REF` variable to `true` to refuse, not warn, and require the check; add your own jobs alongside the generated `closing-references` job",
190
+ customize: "Variable `RUNGATE_REQUIRE_CLOSING_REF=true` refuses rather than warns; add your own jobs alongside the generated `closing-references` job",
191
191
  avoid: "Don't edit the generated `closing-references` job",
192
192
  },
193
+ {
194
+ // #2047, ADR-014 row 4. Hand-written and caller-owned while it ran this
195
+ // checkout's script; a consumer has no scripts/, so the generator writes
196
+ // it, for #631's reason above. It names no board (#2165).
197
+ path: ".github/workflows/board-ready.yml",
198
+ strategy: "job-preserving",
199
+ servedBy: "writeManagedFile (lib/scaffold/steps.ts) via mergeManagedWorkflow — the harness owns named jobs, not the file",
200
+ customize: "Set `board.id` in config and secret `RUNGATE_PROJECT_TOKEN`; add your own jobs alongside the generated `move-freed-issues-to-ready` job",
201
+ avoid: "Don't edit the generated `move-freed-issues-to-ready` job",
202
+ },
193
203
  {
194
204
  // `regenerate` until #655, and the declaration was never consulted:
195
205
  // `generateAgentBriefsStep` called `writeFileSync` directly, so the row
@@ -50,6 +50,7 @@ import {
50
50
  } from "./ai-review-unmeasured-workflow";
51
51
  import { buildAdrAcceptedWorkflow } from "./adr-accepted-workflow";
52
52
  import { buildClosingReferencesWorkflow } from "./closing-references-workflow";
53
+ import { buildBoardReadyWorkflow } from "./board-ready-workflow";
53
54
  import { CI_SUITE_FETCH_DEPTH, baseRefFetchDepth } from "../ci-history-depth";
54
55
  import { CLAUDE_CODE_ACTION } from "../claude-code-action";
55
56
  import { GOOGLE_AUTH_ACTION } from "../google-auth-action";
@@ -4501,6 +4502,18 @@ ${buildAuthDetectStep(vertex)}${buildReviewRunStep(
4501
4502
  version: harnessVersion(),
4502
4503
  });
4503
4504
 
4505
+ // #2047, ADR-014 row 4: Ready kept full from the events the repository
4506
+ // already emits. It names no board: the published CLI reads board.id from
4507
+ // the checked-out config (#2165), so no generated workflow carries an id.
4508
+ const boardReadyYml = buildBoardReadyWorkflow({
4509
+ runsOn,
4510
+ checkout: actionRef("actions/checkout"),
4511
+ setupBun: actionRef("oven-sh/setup-bun"),
4512
+ setupBunWith: bunStep,
4513
+ setupBunEnv: setupBunEnv(" "),
4514
+ version: harnessVersion(),
4515
+ });
4516
+
4504
4517
  // Not `writeFileSync`. The harness owns the `test` and `gates` jobs; it does
4505
4518
  // not own the file, and a consumer's own jobs have to survive the update
4506
4519
  // that re-scaffolding IS. A refusal is recorded rather than thrown so that
@@ -4516,7 +4529,7 @@ ${buildAuthDetectStep(vertex)}${buildReviewRunStep(
4516
4529
  // lib/conformity.ts reads back, and the two are held together by
4517
4530
  // test/ai-review-workflow.test.ts AC-1, which looks for the constant's
4518
4531
  // filename in what this loop actually wrote.
4519
- 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]] as const) {
4532
+ 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]] as const) {
4520
4533
  const label = `.github/workflows/${name}`;
4521
4534
  try {
4522
4535
  // Keyed by FILE, and the lookup is here because this loop is the only
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.8.17",
3
+ "version": "0.8.19",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
6
  "repository": {
@@ -35,6 +35,7 @@
35
35
  "scripts/plan-deps.ts",
36
36
  "scripts/plan-issues.ts",
37
37
  "scripts/board-ready.ts",
38
+ "scripts/board-id.ts",
38
39
  "scripts/audit-closing-references.ts",
39
40
  "scripts/create-spec.ts",
40
41
  "scripts/create-success.ts",
@@ -0,0 +1,58 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * `rungate board-id [--project-root <dir>]` — the board's node id, from
4
+ * `board.id` in the project's rungate config (#2173).
5
+ *
6
+ * For a workflow that does its work in shell rather than through a rungate
7
+ * command: `board-intake.yml` (#2166) runs `gh api graphql` and needs the
8
+ * board's id, and a generated workflow must name none (SC-2745). Reading the
9
+ * config with `jq` in YAML would build a config path outside
10
+ * `lib/config-loader.ts` and see only one of the two layouts
11
+ * (`.claude/rules/config-access.md`), so the read goes through
12
+ * `readBoardProjectId`, the reader `board-ready`, `work-status` and
13
+ * `status-view` already use.
14
+ *
15
+ * Prints the id and nothing else, so `PROJECT_ID=$(bunx rungate@X board-id)`
16
+ * is the whole of a caller's parsing. A config with no `board.id`, or no
17
+ * config, is UNMEASURED on stderr and `EXIT_REFUSED` — never an empty line
18
+ * and exit 0, which a caller would carry into every query as a blank id.
19
+ * A malformed config throws, as the loader does: a corrupt config is not a
20
+ * missing board.
21
+ *
22
+ * Relative imports are `../lib/` only: `test/board-id.test.ts` rewrites
23
+ * them to absolute paths to run a mutant from a temp directory.
24
+ */
25
+ import { resolve } from "path";
26
+ import { readBoardProjectId } from "../lib/config-readers";
27
+
28
+ /** The one non-zero exit for a reading not taken. Assigned once; the test mutates it. */
29
+ export const EXIT_REFUSED = 2;
30
+
31
+ export function main(argv: readonly string[]): number {
32
+ let rootArg: string | undefined;
33
+ for (let i = 0; i < argv.length; i++) {
34
+ const a = argv[i];
35
+ if (a === "--project-root") {
36
+ const next = argv[i + 1];
37
+ if (next === undefined || next.startsWith("--")) {
38
+ console.error("UNMEASURED: --project-root needs a directory after it. Nothing was read.");
39
+ return EXIT_REFUSED;
40
+ }
41
+ rootArg = next;
42
+ i++;
43
+ } else {
44
+ console.error(`UNMEASURED: unknown argument ${JSON.stringify(a)}. Usage: rungate board-id [--project-root <dir>]. Nothing was read.`);
45
+ return EXIT_REFUSED;
46
+ }
47
+ }
48
+ const root = resolve(rootArg ?? process.cwd());
49
+ const id = readBoardProjectId(root);
50
+ if (id === null) {
51
+ console.error(`UNMEASURED: no board — set board.id in the rungate config under ${root}. Nothing was printed.`);
52
+ return EXIT_REFUSED;
53
+ }
54
+ console.log(id);
55
+ return 0;
56
+ }
57
+
58
+ if (import.meta.main) process.exitCode = main(process.argv.slice(2));