rungate 0.8.16 → 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 +1 -1
- package/lib/branch-protection.ts +11 -3
- package/lib/cli-commands.ts +11 -2
- package/lib/generators/agents-md.ts +27 -4
- package/lib/github.ts +9 -0
- package/lib/scaffold/adr-accepted-workflow.ts +219 -0
- package/lib/scaffold/board-ready-workflow.ts +248 -0
- package/lib/scaffold/closing-references-workflow.ts +168 -0
- package/lib/scaffold/human-steps.ts +260 -0
- package/lib/scaffold/owned-files.ts +47 -0
- package/lib/scaffold/process-files.ts +67 -0
- package/lib/scaffold/process-rules.ts +142 -0
- package/lib/scaffold/steps.ts +221 -4
- package/lib/scaffold/write-steps.ts +52 -2
- package/package.json +2 -1
- package/scripts/board-id.ts +58 -0
- package/scripts/board-ready.ts +30 -7
- package/scripts/scaffold-project.ts +10 -1
- package/templates/board-defaults.json +3 -0
- package/templates/process/adr-template.md +67 -0
- package/templates/process/dry-run.md +89 -0
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `.github/workflows/closing-references.yml`, generated — #2045, ADR-014 row 2,
|
|
3
|
+
* SC-2743.
|
|
4
|
+
*
|
|
5
|
+
* The check refuses a pull request whose closing keyword GitHub will never
|
|
6
|
+
* act on, or that closes no issue, or whose issue has not answered the
|
|
7
|
+
* criterion question (ADR-013 rule 9 step 4). It was hand-written and
|
|
8
|
+
* NOT-OWNED on the reasoning that it was this repository's policy about its
|
|
9
|
+
* own pull request bodies. Rule 9 made it every consumer's policy, so the
|
|
10
|
+
* scaffold now writes it, and this repository's copy is the generated one
|
|
11
|
+
* (ADR-014 decision 1): the bytes here are the bytes a consumer gets.
|
|
12
|
+
*
|
|
13
|
+
* ## It calls the published CLI
|
|
14
|
+
*
|
|
15
|
+
* A consumer has `node_modules/rungate`, not `scripts/` (ADR-014 decision 2),
|
|
16
|
+
* so the step runs `bunx rungate@<version> audit-closing-references`. The
|
|
17
|
+
* version is the generating one, the same reading every other `bunx` pin
|
|
18
|
+
* takes, so a tree ahead of npm emits a command the registry cannot satisfy
|
|
19
|
+
* until the release ships. `docs/guides/RELEASING.md` is the sequence.
|
|
20
|
+
*
|
|
21
|
+
* ## It runs in a merge queue too, and reads a real pull request there
|
|
22
|
+
*
|
|
23
|
+
* A required check with no `merge_group` trigger hangs a queue
|
|
24
|
+
* (`test/merge-group-trigger.test.ts`). A queue run has no pull request in
|
|
25
|
+
* its payload, but its ref names one — `gh-readonly-queue/<base>/pr-<N>-<sha>`
|
|
26
|
+
* — so the step reads that pull request rather than reporting a reading it
|
|
27
|
+
* did not take. A ref naming none is UNMEASURED and red.
|
|
28
|
+
*/
|
|
29
|
+
|
|
30
|
+
/** The file this module generates, under `.github/workflows/`. */
|
|
31
|
+
export const CLOSING_REFERENCES_WORKFLOW_FILE = "closing-references.yml";
|
|
32
|
+
|
|
33
|
+
/** The one job in it, which is also the required status context's name. */
|
|
34
|
+
export const CLOSING_REFERENCES_JOB = "closing-references";
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* The CLI command the step runs. `lib/cli-commands.ts` must register it, or
|
|
38
|
+
* the workflow calls a command `bin/rungate.ts` refuses (#675's defect).
|
|
39
|
+
*/
|
|
40
|
+
export const CLOSING_REFERENCES_COMMAND = "audit-closing-references";
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* ONE query, with each issue body on the `closingIssuesReferences` node GitHub
|
|
44
|
+
* returned (SC-2737). `files` is the diff the session-record exemption is
|
|
45
|
+
* decided from; `totalCount` travels with the issues and the commits so the
|
|
46
|
+
* command can refuse a list that was cut short.
|
|
47
|
+
*/
|
|
48
|
+
const QUERY_LINES = [
|
|
49
|
+
"query($owner: String!, $name: String!, $number: Int!) {",
|
|
50
|
+
"repository(owner: $owner, name: $name) { pullRequest(number: $number) {",
|
|
51
|
+
"number body",
|
|
52
|
+
"files(first: 100) { nodes { path } }",
|
|
53
|
+
"closingIssuesReferences(first: 100) { totalCount",
|
|
54
|
+
"nodes { number title body repository { name owner { login } } } }",
|
|
55
|
+
"commits(first: 250) { totalCount nodes { commit { oid message } } }",
|
|
56
|
+
"} } }",
|
|
57
|
+
];
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* The step's `run:` body. Exported so `test/closing-references-workflow.test.ts`
|
|
61
|
+
* executes THIS text against a stub `gh` and `bunx`, rather than a paraphrase.
|
|
62
|
+
*
|
|
63
|
+
* `pipefail` because `run:` is `bash -e`, which takes a pipeline's status from
|
|
64
|
+
* its LAST command: a failed query would hand the command an empty stdin and
|
|
65
|
+
* the step's status would be the command's. No `|| true` and no
|
|
66
|
+
* `2>/dev/null` for the same reason.
|
|
67
|
+
*/
|
|
68
|
+
export function buildClosingReferencesScript(version: string): string {
|
|
69
|
+
return `set -o pipefail
|
|
70
|
+
# A pull request run carries its number. A merge-queue run does not, but its
|
|
71
|
+
# ref names the pull request: gh-readonly-queue/<base>/pr-<N>-<sha>.
|
|
72
|
+
number="\${PR:-}"
|
|
73
|
+
if [ -z "$number" ]; then
|
|
74
|
+
number=$(printf '%s' "\${QUEUE_REF:-}" | sed -n 's|^.*/pr-\\([0-9][0-9]*\\)-[0-9a-f][0-9a-f]*$|\\1|p')
|
|
75
|
+
fi
|
|
76
|
+
if [ -z "$number" ]; then
|
|
77
|
+
echo "::error::UNMEASURED — this run carries no pull request number and its ref (\${QUEUE_REF:-none}) names none, so there is no pull request body to check. Nothing was read."
|
|
78
|
+
exit 1
|
|
79
|
+
fi
|
|
80
|
+
# GitHub's answer is the input: the command never computes its own idea of
|
|
81
|
+
# whether an issue is linked. --repo because a bare number is not an identity.
|
|
82
|
+
gh api graphql -f query="$QUERY" \\
|
|
83
|
+
-f owner="\${GITHUB_REPOSITORY%/*}" -f name="\${GITHUB_REPOSITORY#*/}" -F number="$number" \\
|
|
84
|
+
--jq '.data.repository.pullRequest | {number, body, files: .files.nodes, closingIssuesReferences: .closingIssuesReferences.nodes, closingIssuesTotal: .closingIssuesReferences.totalCount, commits: [.commits.nodes[].commit | {sha: .oid, message}], commitsTotal: .commits.totalCount}' \\
|
|
85
|
+
| bunx rungate@${version} ${CLOSING_REFERENCES_COMMAND} --repo "$GITHUB_REPOSITORY"
|
|
86
|
+
`;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
export interface ClosingReferencesWorkflowOptions {
|
|
90
|
+
/** The `runs-on:` value, already JSON-quoted by the caller. */
|
|
91
|
+
runsOn: string;
|
|
92
|
+
/** The pinned `actions/checkout` reference. */
|
|
93
|
+
checkout: string;
|
|
94
|
+
/** The pinned `oven-sh/setup-bun` reference. */
|
|
95
|
+
setupBun: string;
|
|
96
|
+
/** The `with:` body of that step, at ten spaces — the project's single bun declaration (#622). */
|
|
97
|
+
setupBunWith: string;
|
|
98
|
+
/** The step's `env:` block, from `setupBunEnv` (#2039). */
|
|
99
|
+
setupBunEnv: string;
|
|
100
|
+
/** The published harness version the step runs through `bunx`. */
|
|
101
|
+
version: string;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* The whole `closing-references.yml` body.
|
|
106
|
+
*
|
|
107
|
+
* It checks out the pull request's tree because the command reads `specs/`
|
|
108
|
+
* for its fourth refusal (a closed issue naming a criterion the tree leaves
|
|
109
|
+
* unticked). The trigger is `pull_request`, never `pull_request_target`, and
|
|
110
|
+
* every permission is read-only, so a fork's code runs with no write token.
|
|
111
|
+
*/
|
|
112
|
+
export function buildClosingReferencesWorkflow(opts: ClosingReferencesWorkflowOptions): string {
|
|
113
|
+
const indent = (text: string, pad: string) =>
|
|
114
|
+
text
|
|
115
|
+
.trimEnd()
|
|
116
|
+
.split("\n")
|
|
117
|
+
.map(line => (line === "" ? "" : `${pad}${line}`))
|
|
118
|
+
.join("\n");
|
|
119
|
+
|
|
120
|
+
return `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
|
|
121
|
+
#
|
|
122
|
+
# A closing keyword GitHub cannot see, and a pull request that closes no issue
|
|
123
|
+
# (#1362, ADR-013 rule 9 step 4). Generated since #2045: rule 9 is every
|
|
124
|
+
# consumer's policy, so the scaffold writes this file and this repository's
|
|
125
|
+
# copy is the generated one.
|
|
126
|
+
#
|
|
127
|
+
# RUNGATE_REQUIRE_CLOSING_REF turns the last two refusals on when it is the
|
|
128
|
+
# string \`true\`, and at no other value; otherwise they are a warning
|
|
129
|
+
# annotation. Make \`${CLOSING_REFERENCES_JOB}\` a required check to enforce it.
|
|
130
|
+
name: Closing references
|
|
131
|
+
|
|
132
|
+
on:
|
|
133
|
+
# \`edited\` is ADR-013 decision 4: adding "Fixes #N" to the description is
|
|
134
|
+
# the remedy the refusal prints, so editing the body re-runs it.
|
|
135
|
+
pull_request:
|
|
136
|
+
types: [opened, synchronize, reopened, edited]
|
|
137
|
+
# A required check must report in a merge queue or the queue waits for it
|
|
138
|
+
# forever. The queue run reads the pull request its ref names.
|
|
139
|
+
merge_group:
|
|
140
|
+
|
|
141
|
+
permissions:
|
|
142
|
+
contents: read
|
|
143
|
+
# \`closingIssuesReferences\` resolves through the GraphQL API and reads the
|
|
144
|
+
# linked ISSUES, not just the pull request, so both are needed.
|
|
145
|
+
pull-requests: read
|
|
146
|
+
issues: read
|
|
147
|
+
|
|
148
|
+
jobs:
|
|
149
|
+
${CLOSING_REFERENCES_JOB}:
|
|
150
|
+
runs-on: ${opts.runsOn}
|
|
151
|
+
steps:
|
|
152
|
+
- uses: ${opts.checkout}
|
|
153
|
+
- uses: ${opts.setupBun}
|
|
154
|
+
with:
|
|
155
|
+
${opts.setupBunWith}
|
|
156
|
+
${opts.setupBunEnv}
|
|
157
|
+
- name: A closing keyword GitHub cannot see, and a pull request that closes no issue
|
|
158
|
+
env:
|
|
159
|
+
GH_TOKEN: \${{ github.token }}
|
|
160
|
+
PR: \${{ github.event.pull_request.number }}
|
|
161
|
+
QUEUE_REF: \${{ github.event.merge_group.head_ref }}
|
|
162
|
+
RUNGATE_REQUIRE_CLOSING_REF: \${{ vars.RUNGATE_REQUIRE_CLOSING_REF }}
|
|
163
|
+
QUERY: >-
|
|
164
|
+
${indent(QUERY_LINES.join("\n"), " ")}
|
|
165
|
+
run: |
|
|
166
|
+
${indent(buildClosingReferencesScript(opts.version), " ")}
|
|
167
|
+
`;
|
|
168
|
+
}
|
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The human steps a scaffold cannot take, printed as one command each —
|
|
3
|
+
* #2051, ADR-014 row 6, SC-2749.
|
|
4
|
+
*
|
|
5
|
+
* The scaffold writes files. Three things the process needs are settings on
|
|
6
|
+
* GitHub that only a person with the right access can make, and nothing told
|
|
7
|
+
* a consumer they were owed:
|
|
8
|
+
*
|
|
9
|
+
* 1. the `RUNGATE_PROJECT_TOKEN` secret — every board step refuses without it;
|
|
10
|
+
* 2. the `RUNGATE_REQUIRE_CLOSING_REF` variable set to `true` — without it
|
|
11
|
+
* `closing-references` warns instead of refusing;
|
|
12
|
+
* 3. every process check that runs on pull requests but is not REQUIRED on
|
|
13
|
+
* the default branch — a check nobody requires blocks nothing.
|
|
14
|
+
*
|
|
15
|
+
* Each is read where the API allows it. A reading that could not be taken is
|
|
16
|
+
* printed `UNMEASURED` with why, never folded into "nothing owed", and the
|
|
17
|
+
* all-clear names what it measured rather than saying "done".
|
|
18
|
+
*/
|
|
19
|
+
import { spawnSync } from "child_process";
|
|
20
|
+
import { readFileSync, statSync } from "fs";
|
|
21
|
+
import { join } from "path";
|
|
22
|
+
|
|
23
|
+
import { createGitHubClient, parseOwnerRepo } from "../github";
|
|
24
|
+
import { githubProtectionProbe, jobContextNames, type ProtectionFacts, type ProtectionProbe } from "../branch-protection";
|
|
25
|
+
import { parseRemoteSlug } from "../verified-push";
|
|
26
|
+
|
|
27
|
+
export type Reading<T> = { kind: "READ"; value: T } | { kind: "UNMEASURED"; why: string };
|
|
28
|
+
|
|
29
|
+
export const PROJECT_TOKEN_SECRET = "RUNGATE_PROJECT_TOKEN";
|
|
30
|
+
export const REQUIRE_CLOSING_REF_VARIABLE = "RUNGATE_REQUIRE_CLOSING_REF";
|
|
31
|
+
|
|
32
|
+
/** The process workflows whose jobs report a status on pull requests (ADR-014 decision 6's scope). */
|
|
33
|
+
export const PROCESS_CHECK_WORKFLOWS = ["closing-references.yml"] as const;
|
|
34
|
+
|
|
35
|
+
export interface HumanStepReadings {
|
|
36
|
+
/** `owner/name`, or null when the origin remote names no GitHub repository. */
|
|
37
|
+
slug: string | null;
|
|
38
|
+
secretPresent: Reading<boolean>;
|
|
39
|
+
/** The variable's value, or null when it is not set. */
|
|
40
|
+
requireClosingRef: Reading<string | null>;
|
|
41
|
+
/** The default branch, its required status checks, and which protection state it is in. */
|
|
42
|
+
protection: Reading<{ branch: string; contexts: string[]; statusChecks: NonNullable<ProtectionFacts["statusChecks"]> }>;
|
|
43
|
+
/** Job names of the process checks this tree's workflows define. */
|
|
44
|
+
processChecks: string[];
|
|
45
|
+
/** Process workflows present but unreadable, each with why (#2161). */
|
|
46
|
+
unreadableWorkflows: string[];
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** One line per step owed or unread, then a line saying what was measured. Pure. */
|
|
50
|
+
export function humanSteps(r: HumanStepReadings): string[] {
|
|
51
|
+
const unreadWorkflows = r.unreadableWorkflows.map(why => `UNMEASURED: process checks — ${why}`);
|
|
52
|
+
if (r.slug === null) {
|
|
53
|
+
return [
|
|
54
|
+
"UNMEASURED: human steps — the origin remote names no GitHub repository, so the project token, " +
|
|
55
|
+
`${REQUIRE_CLOSING_REF_VARIABLE} and the required checks were not read.`,
|
|
56
|
+
// Read from the tree, not from GitHub, so it is owed whatever the remote is.
|
|
57
|
+
...unreadWorkflows,
|
|
58
|
+
];
|
|
59
|
+
}
|
|
60
|
+
const out: string[] = [];
|
|
61
|
+
const measured: string[] = [];
|
|
62
|
+
if (r.secretPresent.kind === "UNMEASURED") out.push(`UNMEASURED: ${PROJECT_TOKEN_SECRET} — ${r.secretPresent.why}`);
|
|
63
|
+
else if (!r.secretPresent.value) {
|
|
64
|
+
out.push(
|
|
65
|
+
`OWED: gh secret set ${PROJECT_TOKEN_SECRET} -R ${r.slug} # a token that can write the project board; every board step refuses without it`,
|
|
66
|
+
);
|
|
67
|
+
} else measured.push(`${PROJECT_TOKEN_SECRET} is set`);
|
|
68
|
+
|
|
69
|
+
if (r.requireClosingRef.kind === "UNMEASURED") {
|
|
70
|
+
out.push(`UNMEASURED: ${REQUIRE_CLOSING_REF_VARIABLE} — ${r.requireClosingRef.why}`);
|
|
71
|
+
} else if (r.requireClosingRef.value !== "true") {
|
|
72
|
+
out.push(
|
|
73
|
+
`OWED: gh variable set ${REQUIRE_CLOSING_REF_VARIABLE} -R ${r.slug} --body true # closing-references refuses instead of warning`,
|
|
74
|
+
);
|
|
75
|
+
} else measured.push(`${REQUIRE_CLOSING_REF_VARIABLE} is true`);
|
|
76
|
+
|
|
77
|
+
out.push(...unreadWorkflows);
|
|
78
|
+
|
|
79
|
+
if (r.processChecks.length > 0) {
|
|
80
|
+
if (r.protection.kind === "UNMEASURED") {
|
|
81
|
+
out.push(`UNMEASURED: required checks (${r.processChecks.join(", ")}) — ${r.protection.why}`);
|
|
82
|
+
} else {
|
|
83
|
+
const { branch, contexts, statusChecks } = r.protection.value;
|
|
84
|
+
const missing = r.processChecks.filter(c => !contexts.includes(c));
|
|
85
|
+
if (missing.length > 0 && statusChecks === "required-checks") {
|
|
86
|
+
for (const check of missing) {
|
|
87
|
+
out.push(
|
|
88
|
+
`OWED: gh api -X POST repos/${r.slug}/branches/${branch}/protection/required_status_checks/contexts ` +
|
|
89
|
+
`-f 'contexts[]=${check}' # ${check} runs on every pull request and blocks nothing until it is required`,
|
|
90
|
+
);
|
|
91
|
+
}
|
|
92
|
+
} else if (missing.length > 0 && statusChecks === "unprotected") {
|
|
93
|
+
// PUT replaces the whole rule, which is safe only because there is no
|
|
94
|
+
// rule yet: it protects the branch and requires the missing checks.
|
|
95
|
+
const body = {
|
|
96
|
+
required_status_checks: { strict: false, contexts: missing },
|
|
97
|
+
enforce_admins: null,
|
|
98
|
+
required_pull_request_reviews: null,
|
|
99
|
+
restrictions: null,
|
|
100
|
+
};
|
|
101
|
+
out.push(
|
|
102
|
+
`OWED: gh api -X PUT repos/${r.slug}/branches/${branch}/protection --input - <<<'${JSON.stringify(body)}'` +
|
|
103
|
+
` # ${branch} is unprotected; this protects it and requires ${missing.join(", ")}, nothing else`,
|
|
104
|
+
);
|
|
105
|
+
} else if (missing.length > 0) {
|
|
106
|
+
// Protected with no required checks: the POST above 404s here and a
|
|
107
|
+
// PUT would replace the rule's other settings, so no single call is safe.
|
|
108
|
+
out.push(
|
|
109
|
+
`OWED: require ${missing.join(", ")} on ${branch} — in the repository's Settings → Branches, edit the rule ` +
|
|
110
|
+
`for ${branch}, turn on "Require status checks to pass" and add ${missing.join(", ")}` +
|
|
111
|
+
` # no single API call adds a check here without replacing the rest of the rule`,
|
|
112
|
+
);
|
|
113
|
+
}
|
|
114
|
+
const required = r.processChecks.filter(c => contexts.includes(c));
|
|
115
|
+
if (required.length > 0) measured.push(`${required.join(", ")} required on ${branch}`);
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
if (out.length === 0) out.push(`Human steps: none owed — measured: ${measured.join("; ")}.`);
|
|
120
|
+
return out;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* The job names of the process checks present in `root`'s workflows, and the
|
|
125
|
+
* workflows that are present but could not be read (#2161). A directory, a
|
|
126
|
+
* permission error or a file removed between the two calls throws on read;
|
|
127
|
+
* that is a reading not taken, never a crash and never "nothing owed".
|
|
128
|
+
*/
|
|
129
|
+
export function processChecksIn(root: string): { checks: string[]; unreadable: string[] } {
|
|
130
|
+
const checks: string[] = [];
|
|
131
|
+
const unreadable: string[] = [];
|
|
132
|
+
for (const file of PROCESS_CHECK_WORKFLOWS) {
|
|
133
|
+
const rel = `.github/workflows/${file}`;
|
|
134
|
+
const p = join(root, ".github", "workflows", file);
|
|
135
|
+
// The stat decides absence, and only its ENOENT counts: existsSync also
|
|
136
|
+
// answers false for an untraversable directory (round 2 of PR #2162).
|
|
137
|
+
// The read gets its own try, so a file removed after the stat is a reading
|
|
138
|
+
// not taken rather than an absent workflow (round 3).
|
|
139
|
+
try {
|
|
140
|
+
statSync(p);
|
|
141
|
+
} catch (e) {
|
|
142
|
+
if ((e as NodeJS.ErrnoException)?.code === "ENOENT") continue;
|
|
143
|
+
unreadable.push(`${rel} could not be read (${(e as Error).message})`);
|
|
144
|
+
continue;
|
|
145
|
+
}
|
|
146
|
+
try {
|
|
147
|
+
checks.push(...jobContextNames(readFileSync(p, "utf-8")));
|
|
148
|
+
} catch (e) {
|
|
149
|
+
unreadable.push(`${rel} could not be read (${(e as Error).message})`);
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
return { checks, unreadable };
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* `owner/name` when `url` is a github.com remote, else `null` (#2161).
|
|
157
|
+
*
|
|
158
|
+
* The GitHub client only ever talks to github.com (`lib/github.ts` refuses
|
|
159
|
+
* any other API host), so a remote on another forge has no settings this
|
|
160
|
+
* module can read. `parseRemoteSlug` deliberately ignores the host, because
|
|
161
|
+
* repo identity is its question; which forge to ask is this one's.
|
|
162
|
+
*/
|
|
163
|
+
export function githubSlugOf(url: string): string | null {
|
|
164
|
+
const trimmed = url.trim();
|
|
165
|
+
if (!trimmed) return null;
|
|
166
|
+
let host: string | null = null;
|
|
167
|
+
if (/^[a-z+]+:\/\//i.test(trimmed)) {
|
|
168
|
+
try {
|
|
169
|
+
host = new URL(trimmed).hostname;
|
|
170
|
+
} catch {
|
|
171
|
+
return null; // not a URL at all, so it names no GitHub repository
|
|
172
|
+
}
|
|
173
|
+
} else {
|
|
174
|
+
host = trimmed.match(/^(?:[^@/]+@)?([^:/]+):/)?.[1] ?? null;
|
|
175
|
+
}
|
|
176
|
+
return host?.toLowerCase() === "github.com" ? parseRemoteSlug(trimmed) : null;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/** The configured `origin` url of `root`, or "" when there is none. */
|
|
180
|
+
function originUrl(root: string): string {
|
|
181
|
+
const r = spawnSync("git", ["config", "--get", "remote.origin.url"], { cwd: root, encoding: "utf-8", timeout: 5000 });
|
|
182
|
+
return r.status === 0 ? r.stdout : "";
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
export interface HumanStepProbes {
|
|
186
|
+
slug: (root: string) => string | null;
|
|
187
|
+
secret: (slug: string) => Promise<Reading<boolean>>;
|
|
188
|
+
variable: (slug: string) => Promise<Reading<string | null>>;
|
|
189
|
+
protection: ProtectionProbe;
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/** The same bound the protection probe puts on each GET: a hung socket is UNMEASURED, never a hung scaffold. */
|
|
193
|
+
export const PROBE_TIMEOUT_MS = 15_000;
|
|
194
|
+
|
|
195
|
+
/** `p`, or a rejection naming `what` after `ms`. The rejection carries no status, so it reads UNMEASURED. */
|
|
196
|
+
export function timed<T>(p: Promise<T>, what: string, ms: number = PROBE_TIMEOUT_MS): Promise<T> {
|
|
197
|
+
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
198
|
+
const deadline = new Promise<never>((_, reject) => {
|
|
199
|
+
timer = setTimeout(() => reject(new Error(`${what} did not answer within ${ms}ms`)), ms);
|
|
200
|
+
timer.unref?.();
|
|
201
|
+
});
|
|
202
|
+
return Promise.race([p, deadline]).finally(() => clearTimeout(timer));
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
const status = (e: unknown) => (e as { status?: unknown })?.status;
|
|
206
|
+
const why = (e: unknown) => `${typeof status(e) === "number" ? `HTTP ${status(e)}: ` : ""}${(e as Error)?.message ?? e}`;
|
|
207
|
+
|
|
208
|
+
/** The live reads: two GETs here, three in the protection probe. No writes. */
|
|
209
|
+
export const LIVE_PROBES: HumanStepProbes = {
|
|
210
|
+
slug: root => githubSlugOf(originUrl(root)),
|
|
211
|
+
secret: async slug => {
|
|
212
|
+
try {
|
|
213
|
+
const { owner, repo } = parseOwnerRepo(slug);
|
|
214
|
+
await timed(
|
|
215
|
+
createGitHubClient().rest.actions.getRepoSecret({ owner, repo, secret_name: PROJECT_TOKEN_SECRET }),
|
|
216
|
+
`GET the ${PROJECT_TOKEN_SECRET} secret`,
|
|
217
|
+
);
|
|
218
|
+
return { kind: "READ", value: true };
|
|
219
|
+
} catch (e) {
|
|
220
|
+
// 404 is the documented answer for an absent secret; anything else —
|
|
221
|
+
// no credential, 403 for a token without admin — is not a reading.
|
|
222
|
+
return status(e) === 404 ? { kind: "READ", value: false } : { kind: "UNMEASURED", why: why(e) };
|
|
223
|
+
}
|
|
224
|
+
},
|
|
225
|
+
variable: async slug => {
|
|
226
|
+
try {
|
|
227
|
+
const { owner, repo } = parseOwnerRepo(slug);
|
|
228
|
+
const r = await timed(
|
|
229
|
+
createGitHubClient().rest.actions.getRepoVariable({ owner, repo, name: REQUIRE_CLOSING_REF_VARIABLE }),
|
|
230
|
+
`GET the ${REQUIRE_CLOSING_REF_VARIABLE} variable`,
|
|
231
|
+
);
|
|
232
|
+
return { kind: "READ", value: String(r.data?.value ?? "") };
|
|
233
|
+
} catch (e) {
|
|
234
|
+
return status(e) === 404 ? { kind: "READ", value: null } : { kind: "UNMEASURED", why: why(e) };
|
|
235
|
+
}
|
|
236
|
+
},
|
|
237
|
+
protection: githubProtectionProbe,
|
|
238
|
+
};
|
|
239
|
+
|
|
240
|
+
/** Read everything {@link humanSteps} needs for `root`. */
|
|
241
|
+
export async function readHumanSteps(root: string, probes: HumanStepProbes = LIVE_PROBES): Promise<HumanStepReadings> {
|
|
242
|
+
const slug = probes.slug(root);
|
|
243
|
+
const { checks: processChecks, unreadable: unreadableWorkflows } = processChecksIn(root);
|
|
244
|
+
if (slug === null) {
|
|
245
|
+
const none = { kind: "UNMEASURED", why: "no repository" } as const;
|
|
246
|
+
return { slug, secretPresent: none, requireClosingRef: none, protection: none, processChecks, unreadableWorkflows };
|
|
247
|
+
}
|
|
248
|
+
const [secretPresent, requireClosingRef, facts] = await Promise.all([
|
|
249
|
+
probes.secret(slug),
|
|
250
|
+
probes.variable(slug),
|
|
251
|
+
probes.protection(slug),
|
|
252
|
+
]);
|
|
253
|
+
const protection: HumanStepReadings["protection"] =
|
|
254
|
+
facts.unreadable || facts.branch === null
|
|
255
|
+
? { kind: "UNMEASURED", why: facts.unreadable ?? "the default branch could not be read" }
|
|
256
|
+
: facts.statusChecks === undefined
|
|
257
|
+
? { kind: "UNMEASURED", why: "the protection probe did not say whether the branch is protected" }
|
|
258
|
+
: { kind: "READ", value: { branch: facts.branch, contexts: facts.contexts, statusChecks: facts.statusChecks } };
|
|
259
|
+
return { slug, secretPresent, requireClosingRef, protection, processChecks, unreadableWorkflows };
|
|
260
|
+
}
|
|
@@ -170,6 +170,36 @@ export const OWNED_FILES: OwnedFile[] = [
|
|
|
170
170
|
customize: "Set `ci.runner` in `.claude/rungate/config.json`; add your own jobs alongside the generated `record-unmeasured` job",
|
|
171
171
|
avoid: "Don't edit the generated `record-unmeasured` job, and don't give it a `merge_group` trigger — it reports no status to the pull request and cannot be a required check",
|
|
172
172
|
},
|
|
173
|
+
{
|
|
174
|
+
// #2046, ADR-014 row 3. Hand-written and caller-owned until ADR-013
|
|
175
|
+
// rule 9 made placing an accepted plan every consumer's step; declared
|
|
176
|
+
// the moment the generator learned to write it, for #631's reason above.
|
|
177
|
+
path: ".github/workflows/adr-accepted.yml",
|
|
178
|
+
strategy: "job-preserving",
|
|
179
|
+
servedBy: "writeManagedFile (lib/scaffold/steps.ts) via mergeManagedWorkflow — the harness owns named jobs, not the file",
|
|
180
|
+
customize: "Set `board.engineSpec` and `board.milestonePrefix` in `.claude/rungate/config.json` and re-scaffold; add your own jobs alongside the generated `place-the-plan` job",
|
|
181
|
+
avoid: "Don't edit the generated `place-the-plan` job",
|
|
182
|
+
},
|
|
183
|
+
{
|
|
184
|
+
// #2045, ADR-014 row 2. Hand-written and NOT-OWNED until ADR-013 rule 9
|
|
185
|
+
// made the check every consumer's policy; declared the moment the
|
|
186
|
+
// generator learned to write it, for #631's reason above.
|
|
187
|
+
path: ".github/workflows/closing-references.yml",
|
|
188
|
+
strategy: "job-preserving",
|
|
189
|
+
servedBy: "writeManagedFile (lib/scaffold/steps.ts) via mergeManagedWorkflow — the harness owns named jobs, not the file",
|
|
190
|
+
customize: "Variable `RUNGATE_REQUIRE_CLOSING_REF=true` refuses rather than warns; add your own jobs alongside the generated `closing-references` job",
|
|
191
|
+
avoid: "Don't edit the generated `closing-references` job",
|
|
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
|
+
},
|
|
173
203
|
{
|
|
174
204
|
// `regenerate` until #655, and the declaration was never consulted:
|
|
175
205
|
// `generateAgentBriefsStep` called `writeFileSync` directly, so the row
|
|
@@ -183,6 +213,23 @@ export const OWNED_FILES: OwnedFile[] = [
|
|
|
183
213
|
avoid: "Don't hand-edit the generated sections — a re-scaffold rewrites them without reporting it",
|
|
184
214
|
sections: BRIEF_CONSTRAINTS_SECTION,
|
|
185
215
|
},
|
|
216
|
+
{
|
|
217
|
+
// #2048, ADR-014 row 5: step 2's command. A provenance file like a rule,
|
|
218
|
+
// because a consumer may tailor it; a hand edit is preserved and reported.
|
|
219
|
+
path: ".claude/commands/dry-run.md",
|
|
220
|
+
strategy: "provenance",
|
|
221
|
+
servedBy: "writeProcessFiles (lib/scaffold/write-steps.ts) via decideRuleWrite — the rule-provenance decision",
|
|
222
|
+
customize: "Edit freely — a hand-edited command is preserved and reported",
|
|
223
|
+
avoid: "Don't delete its `generated-sha` marker, or edits stop surviving",
|
|
224
|
+
},
|
|
225
|
+
{
|
|
226
|
+
// #2048, ADR-014 row 5: step 2's template. Regenerated with no marker,
|
|
227
|
+
// because every ADR is copied from it and a marker would travel into each.
|
|
228
|
+
path: "docs/adr/TEMPLATE.md",
|
|
229
|
+
strategy: "regenerate",
|
|
230
|
+
customize: "Copy it to docs/adr/ADR-<n>-<slug>.md and edit the copy",
|
|
231
|
+
avoid: "Don't edit the template itself — a re-scaffold rewrites it",
|
|
232
|
+
},
|
|
186
233
|
{
|
|
187
234
|
path: ".claude/rules/*.md",
|
|
188
235
|
strategy: "provenance",
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The dry-run command and the ADR template, written by the scaffold — #2048,
|
|
3
|
+
* ADR-014 row 5, SC-2746.
|
|
4
|
+
*
|
|
5
|
+
* Step 2 of the four-step process is "an ADR from `docs/adr/TEMPLATE.md` …
|
|
6
|
+
* `/dry-run` until the owner agrees", and a consumer had neither file: the
|
|
7
|
+
* scaffold created `docs/adr/` empty and installed no `.claude/commands/`.
|
|
8
|
+
* Both are rendered from `templates/process/`, and this repository's copies
|
|
9
|
+
* are the rendered ones.
|
|
10
|
+
*
|
|
11
|
+
* Two differences between a consumer's copy and ours, both in the command:
|
|
12
|
+
*
|
|
13
|
+
* - **The CLI.** `bunx rungate <command>` in a consumer, `bun bin/rungate.ts`
|
|
14
|
+
* here — the switch `commands-routing.md` already makes.
|
|
15
|
+
* - **What Ready holds now.** This repository reads it with
|
|
16
|
+
* `scripts/work-status.ts`, which is not a published command; a consumer
|
|
17
|
+
* reads it with `board-ready --top-up` and no `--write`, which changes
|
|
18
|
+
* nothing and prints what a top-up would move.
|
|
19
|
+
*/
|
|
20
|
+
import { existsSync, readFileSync } from "fs";
|
|
21
|
+
import { join } from "path";
|
|
22
|
+
|
|
23
|
+
export const DRY_RUN_COMMAND_PATH = ".claude/commands/dry-run.md";
|
|
24
|
+
export const ADR_TEMPLATE_PATH = "docs/adr/TEMPLATE.md";
|
|
25
|
+
|
|
26
|
+
/** Where the two sources ship. `templates/` is in `package.json` `files[]`. */
|
|
27
|
+
export const PROCESS_TEMPLATES_DIR = join(import.meta.dir, "..", "..", "templates", "process");
|
|
28
|
+
|
|
29
|
+
const TOKEN = 'env -u GH_TOKEN GITHUB_TOKEN="$(env -u GH_TOKEN gh auth token)"';
|
|
30
|
+
|
|
31
|
+
const READY_NOW = {
|
|
32
|
+
harness: ` - what Ready holds now: \`${TOKEN} bun scripts/work-status.ts\` (START HERE section only)`,
|
|
33
|
+
consumer:
|
|
34
|
+
" - what Ready holds now, and what a top-up would move into it (read-only as written): " +
|
|
35
|
+
'`env -u GH_TOKEN BOARD_PROJECT_TOKEN="$(env -u GH_TOKEN gh auth token)" bunx rungate board-ready ' +
|
|
36
|
+
"--repo <owner/name> --project <board id> --actor \"$(env -u GH_TOKEN gh api user -q .login)\" --top-up`",
|
|
37
|
+
};
|
|
38
|
+
|
|
39
|
+
/** A rendered process file, or why it could not be. */
|
|
40
|
+
export type ProcessFile = { path: string; content: string } | { path: string; content: null; why: string };
|
|
41
|
+
|
|
42
|
+
function source(name: string, dir: string): string | null {
|
|
43
|
+
const p = join(dir, name);
|
|
44
|
+
return existsSync(p) ? readFileSync(p, "utf-8") : null;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** Both files, rendered for this repository (`harness`) or a consumer. */
|
|
48
|
+
export function processFiles(harness: boolean, dir: string = PROCESS_TEMPLATES_DIR): ProcessFile[] {
|
|
49
|
+
const missing = (path: string, name: string): ProcessFile => ({
|
|
50
|
+
path,
|
|
51
|
+
content: null,
|
|
52
|
+
why: `templates/process/${name} is missing from this rungate installation`,
|
|
53
|
+
});
|
|
54
|
+
const command = source("dry-run.md", dir);
|
|
55
|
+
const template = source("adr-template.md", dir);
|
|
56
|
+
return [
|
|
57
|
+
command === null
|
|
58
|
+
? missing(DRY_RUN_COMMAND_PATH, "dry-run.md")
|
|
59
|
+
: {
|
|
60
|
+
path: DRY_RUN_COMMAND_PATH,
|
|
61
|
+
content: command
|
|
62
|
+
.replaceAll("{{CLI}}", harness ? "bun bin/rungate.ts" : "bunx rungate")
|
|
63
|
+
.replace("{{READY_NOW}}", harness ? READY_NOW.harness : READY_NOW.consumer),
|
|
64
|
+
},
|
|
65
|
+
template === null ? missing(ADR_TEMPLATE_PATH, "adr-template.md") : { path: ADR_TEMPLATE_PATH, content: template },
|
|
66
|
+
];
|
|
67
|
+
}
|