diff --git a/bin/gstack-doctor-components.sh b/bin/gstack-doctor-components.sh index c67312474..ed561a833 100644 --- a/bin/gstack-doctor-components.sh +++ b/bin/gstack-doctor-components.sh @@ -373,6 +373,9 @@ gstack_result_anchor() { FETCH_VIOLATION) printf '%s' 'fetch-violation' ;; FETCH_RERUN_BLOCKED) printf '%s' 'fetch-rerun-blocked' ;; FETCH_RERUN_SPENT) printf '%s' 'fetch-rerun-spent' ;; + PUSH_REFUSED) printf '%s' 'push-refused' ;; + PUSH_REJECTED) printf '%s' 'push-rejected' ;; + PUSH_GIT_FAILED) printf '%s' 'push-git-failed' ;; APPROVAL_RECORD_INVALID) printf '%s' 'approval-record-invalid' ;; APPROVAL_RECORD_SECRET) printf '%s' 'approval-record-secret' ;; APPROVAL_RECORD_NO_BRANCH) printf '%s' 'approval-record-no-branch' ;; diff --git a/changelog.d/ship-push-prints-one-stable-line-gst-3053.md b/changelog.d/ship-push-prints-one-stable-line-gst-3053.md new file mode 100644 index 000000000..4a694dd9d --- /dev/null +++ b/changelog.d/ship-push-prints-one-stable-line-gst-3053.md @@ -0,0 +1 @@ +- **/ship's push step now always ends with one line that says whether it pushed (GST-3053).** `gstack-ship-release push` (Step 17) finishes with exactly one of `PUSH: pushed remote=origin ref= head=`, `PUSH: already_pushed remote=origin ref= head=` or `PUSH: failed reason=PUSH_REFUSED|PUSH_REJECTED|PUSH_GIT_FAILED`, so a script or eval grader can tell that /ship pushed by matching that line instead of looking for a `git push` call. Exit status is unchanged. Each reason code has a troubleshooting entry, and the format is documented in docs/unattended.md#push-line. An eval had graded 48 real /ship pushes as "no push" because it searched for the git command. The line's shape changed. The old `PUSH: ALREADY_PUSHED ` and `PUSH: pushed to origin/` lines are gone, so update anything that matched them. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 103cbb718..9fa1bc80b 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -5788,6 +5788,40 @@ origin cannot be reached, from its local stable ref and release tags. **Fix.** Run `git fetch origin --tags` in the gstack checkout, or point `GSTACK_STABLE_REPO` at a gstack checkout that has the tags, then rerun. + +### `PUSH_REFUSED` + +**Meaning.** `gstack-ship-release push` stopped before `git push` ran and +ended with `PUSH: failed reason=PUSH_REFUSED`: a usage error, HEAD on another +branch than Step 1 saved, the unanswered one-time pre-push offer, open gate +findings on a ready PR, sealed output, the early secrets scan, the pre-push +guards, or a never-pushed branch name that is not plain words. Nothing was +pushed. [The push line](unattended.md#push-line). + +**Fix.** Follow the `STOP:` line printed just above it, then rerun +`gstack-ship-release push`. + + +### `PUSH_REJECTED` + +**Meaning.** `git push` was rejected: the remote branch has commits this +branch lacks (non-fast-forward), or the remote refused the update. Nothing +was pushed. + +**Fix.** Fetch and inspect the remote, merge it under Step 3's conflict +rules, run Steps 5-16 again, then rerun push. Never force-push. + + +### `PUSH_GIT_FAILED` + +**Meaning.** `git ls-remote` could not read the remote branch, or +`git push` failed for a reason other than a rejection: authentication, a +pre-push hook or the network. Nothing was pushed. + +**Fix.** Repair the cause git printed in the `STOP:` line, repeat Step 16 +(even when the content is unchanged), then rerun push. Never bypass a failed +guard. + ### `QUEUE_NOT_READY` diff --git a/docs/unattended.md b/docs/unattended.md index 68c4da48d..64feaca8e 100644 --- a/docs/unattended.md +++ b/docs/unattended.md @@ -167,6 +167,33 @@ generated tests), the parent pushes those commits itself, then reruns the receipt write, the body post and `result` at the pushed head: a receipt for an unpushed head is `QUEUE_RECEIPT_STALE` to the queue. + +### The push line: `PUSH:` + +Step 17's `gstack-ship-release push` (early or final) always ends with exactly +one line saying whether the branch reached the remote, so a parent, a report or +an outside probe can tell that `/ship` pushed without looking for a +`git push` call: + +``` +PUSH: pushed remote=origin ref= head= +PUSH: already_pushed remote=origin ref= head= +PUSH: failed reason= +``` + +`pushed` means this run's `git push` updated the branch; `already_pushed` +means the remote branch already pointed at HEAD, so nothing was sent. `failed` +means nothing was pushed, with one of three codes: +[`PUSH_REFUSED`](troubleshooting.md#push-refused) (a check stopped it before +`git push` ran), [`PUSH_REJECTED`](troubleshooting.md#push-rejected) +(non-fast-forward, or the remote refused the update) and +[`PUSH_GIT_FAILED`](troubleshooting.md#push-git-failed) (git could not read +the remote, or `git push` failed on authentication, a hook or the network). +The line is the last one printed, after any `STOP:` or `NEXT:` line, on +stdout (stderr for a usage error), and the exit status keeps its meaning: 0 +for `pushed` and `already_pushed`, 3 for a stop, 2 for a usage error. Match +`^PUSH: (pushed|already_pushed) ` for "this run's branch is on the remote". + ### The review loop's counters The receipt's `review_loop` object, written from `gstack-review-scope summary diff --git a/lib/result-codes-release.ts b/lib/result-codes-release.ts index 1ff6ce0f2..54a4ced8f 100644 --- a/lib/result-codes-release.ts +++ b/lib/result-codes-release.ts @@ -607,4 +607,20 @@ export const RELEASE_RESULT_CODES = { summary: 'the stage\'s one rerun fetched too, so the pass stopped with its readers quarantined, resuming it starts no later stage and returns no reader output, and verify refuses', fix: 'deal with the printed paths, find out why readers keep fetching, then start a fresh pass under a new --pass and --out; a third attempt is never automatic', }, + // GST-3053: gstack-ship-release push's last line, `PUSH: failed reason=` (docs/unattended.md#push-line). + PUSH_REFUSED: { + anchor: 'push-refused', + summary: 'gstack-ship-release push stopped before git push ran (a usage error, the wrong branch, the unanswered pre-push offer, open gate findings on a ready PR, sealed output, the secrets scan, the pre-push guards or a branch name that is not plain words), so nothing was pushed', + fix: 'follow the STOP: line above it, then rerun gstack-ship-release push', + }, + PUSH_REJECTED: { + anchor: 'push-rejected', + summary: 'git push was rejected: the remote branch has commits this branch lacks (non-fast-forward) or the remote refused the update, so nothing was pushed', + fix: 'fetch and merge the remote under Step 3\'s conflict rules, run Steps 5-16 again, then rerun push; never force-push', + }, + PUSH_GIT_FAILED: { + anchor: 'push-git-failed', + summary: 'git could not read the remote branch or git push failed for another reason (authentication, a pre-push hook or the network), so nothing was pushed', + fix: 'repair the cause git printed in the STOP: line, repeat Step 16, then rerun push; never bypass a guard', + }, } as const satisfies Record; diff --git a/lib/ship-release.ts b/lib/ship-release.ts index 7f36f8b34..d29664446 100644 --- a/lib/ship-release.ts +++ b/lib/ship-release.ts @@ -737,7 +737,7 @@ export async function accept(argv: readonly string[], cwd: string): Promise path.resolve(cwd, git(cwd, ['rev-parse', '--git-path', `gstack/${name}`]).stdout.trim() || `.git/gstack/${name}`); const tree = git(cwd, ['rev-parse', 'HEAD^{tree}']).stdout.trim(); const out = gitPath('pregate-guards.json'); @@ -752,7 +752,7 @@ function prepushGuards(cwd: string, branch: string, base: string | undefined): { let res: { status?: string; verdict?: string; tree?: string; code?: string; detail?: string; fix?: string; checks?: { id: string; status: string; detail?: string; fix?: string }[] } = {}; try { res = JSON.parse(pg.stdout.trim().split('\n').pop() ?? ''); } catch { /* unreadable: stops below */ } const heads = res.status === 'refused' && res.code === 'POLICY_SOURCE_UNAVAILABLE' ? git(cwd, ['ls-remote', '--heads', 'origin'], 120_000) : null; - if (heads && heads.status !== 0) return { line: 'GUARDS: not run (origin unreachable)', stop: `cannot verify the remote branch (${firstLine(heads.stderr)}): restore access before pushing` }; + if (heads && heads.status !== 0) return { line: 'GUARDS: not run (origin unreachable)', stop: `cannot verify the remote branch (${firstLine(heads.stderr)}): restore access before pushing`, code: 'PUSH_GIT_FAILED' }; if (heads && heads.stdout.split('\n').every(l => !l.trim() || l.trim().endsWith(`\trefs/heads/${branch}`))) return { line: `GUARDS: not run (origin has no branch but ${branch}, so no base to read guards from)` }; if (res.status === 'refused') return { line: `GUARDS: refused ${res.code}`, stop: `the pre-push guards could not run (${res.detail}; fix: ${res.fix}): repair it, then rerun push` }; const bad = (res.checks ?? []).filter(c => c.status !== 'pass' && c.status !== 'warn').map(c => `${c.id}: ${c.fix ?? c.detail ?? c.status}`).join('; '); @@ -764,60 +764,70 @@ function prepushGuards(cwd: string, branch: string, base: string | undefined): { return { line, stop: `the pre-push guards did not pass (${bad || firstLine(pg.stderr || pg.stdout)}): fix it, commit, then rerun push` }; } +/** Every push run's last line (docs/unattended.md#push-line): outside observers match it instead of a git push call. */ +export type PushFailure = 'PUSH_REFUSED' | 'PUSH_REJECTED' | 'PUSH_GIT_FAILED'; +export const pushFailedLine = (code: PushFailure) => `PUSH: failed reason=${code}`; + export function push(argv: readonly string[], cwd: string): Report { - const { flag, has } = flagReader(argv); const r = new Report(); + return r.add(pushOnce(argv, cwd, r)); +} + +function pushOnce(argv: readonly string[], cwd: string, r: Report): string { + const { flag, has } = flagReader(argv); + const refuse = (what: string, code: PushFailure = 'PUSH_REFUSED') => { r.stop(what); return pushFailedLine(code); }; const branch = git(cwd, ['branch', '--show-current']).stdout.trim(); - if (!branch) return r.stop('detached HEAD: push needs the feature branch'); - if (branch !== flag('--branch')) return r.stop(`HEAD is on ${branch}, not the branch Step 1 saved (${flag('--branch')}): check out the saved branch, then rerun push`); + if (!branch) return refuse('detached HEAD: push needs the feature branch'); + if (branch !== flag('--branch')) return refuse(`HEAD is on ${branch}, not the branch Step 1 saved (${flag('--branch')}): check out the saved branch, then rerun push`); const guard = bin(cwd, 'gstack-config', ['get', 'redact_prepush_hook'], 30_000).stdout.trim() || 'false'; const prompted = fs.existsSync(path.join(resolveStateRoot(process.env), '.redact-prepush-prompted')); const deferred = guard !== 'true' && !prompted && process.env.GSTACK_SESSION_KIND === 'unattended'; r.add(`REDACT_PREPUSH: ${guard} prompted=${prompted ? 'yes' : 'no'}${deferred ? ' deferred=unattended' : ''}`); - if (guard !== 'true' && !prompted && !deferred) return r.stop('Step 17\'s one-time pre-push guard offer is unanswered: run the guard block and ask it, then rerun push'); + if (guard !== 'true' && !prompted && !deferred) return refuse('Step 17\'s one-time pre-push guard offer is unanswered: run the guard block and ask it, then rerun push'); const gateOpen = Number(flag('--gate-open') ?? '0'); if (gateOpen > 0) { - if (!hostedOrigin(cwd)) return r.stop('open-PR lookup unavailable: origin is a local path, not a hosted remote gh can map; it must succeed before pushing open gate findings'); + if (!hostedOrigin(cwd)) return refuse('open-PR lookup unavailable: origin is a local path, not a hosted remote gh can map; it must succeed before pushing open gate findings'); const pr = gh(cwd, ['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number,isDraft', '--jq', '[.[] | select(.isDraft | not) | .number] | first // empty']); - if (pr.status !== 0) return r.stop(`open-PR lookup failed (${firstLine(pr.stderr)}): it must succeed before pushing open gate findings`); - if (pr.stdout.trim() && !has('--gate-open-approved')) return r.stop(`${gateOpen} open gate finding(s) and ready PR #${pr.stdout.trim()}: spawned/headless sessions stop here; otherwise ask (resolve now, or publish with the banner and rerun with --gate-open-approved)`); + if (pr.status !== 0) return refuse(`open-PR lookup failed (${firstLine(pr.stderr)}): it must succeed before pushing open gate findings`); + if (pr.stdout.trim() && !has('--gate-open-approved')) return refuse(`${gateOpen} open gate finding(s) and ready PR #${pr.stdout.trim()}: spawned/headless sessions stop here; otherwise ask (resolve now, or publish with the banner and rerun with --gate-open-approved)`); } const sealed = bin(cwd, 'gstack-pregate', ['sealed'], 120_000); r.add(`SEALED: ${sealed.status === 0 ? 'clear' : sealed.status === 1 ? 'refused' : `not checked (exit ${sealed.status})`}`); - if (sealed.status === 1) return r.stop(`sealed output would be published: ${firstLine(sealed.stderr)}; remove it from the commits, then repeat Step 16`); - if (sealed.status !== 0) return r.stop(`the sealed-output guard did not run (exit ${sealed.status}: ${firstLine(sealed.stderr || sealed.stdout)}); repair it, then rerun push`); + if (sealed.status === 1) return refuse(`sealed output would be published: ${firstLine(sealed.stderr)}; remove it from the commits, then repeat Step 16`); + if (sealed.status !== 0) return refuse(`the sealed-output guard did not run (exit ${sealed.status}: ${firstLine(sealed.stderr || sealed.stdout)}); repair it, then rerun push`); if (has('--early')) { const out = path.resolve(cwd, git(cwd, ['rev-parse', '--git-path', 'gstack/pregate-early-push.json']).stdout.trim() || '.git/gstack/pregate-early-push.json'); const scan = bin(cwd, 'gstack-pregate', ['--stage', 'preflight', '--only', 'secrets', '--out', out, ...(flag('--base') ? ['--base', flag('--base')!] : [])], 600_000); const verdict = /^PREGATE: (.+?) tree=/m.exec(scan.stdout + scan.stderr)?.[1] ?? `unreadable (exit ${scan.status})`; r.add(`SECRETS: ${verdict} (early push)`); - if (scan.status !== 0 || !/^(pass|warn)/.test(verdict)) return r.stop(`the secrets scan did not pass before the early push (${firstLine(scan.stderr) || verdict}): remove the finding from the commits, then rerun push --early`); + if (scan.status !== 0 || !/^(pass|warn)/.test(verdict)) return refuse(`the secrets scan did not pass before the early push (${firstLine(scan.stderr) || verdict}): remove the finding from the commits, then rerun push --early`); } const guards = prepushGuards(cwd, branch, flag('--base')); r.add(guards.line); - if (guards.stop) return r.stop(guards.stop); + if (guards.stop) return refuse(guards.stop, guards.code); const local = git(cwd, ['rev-parse', 'HEAD']).stdout.trim(); const remote = git(cwd, ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], 120_000); - if (remote.status !== 0) return r.stop(`cannot verify the remote branch (${firstLine(remote.stderr)}): restore access before pushing`); - if (remote.stdout.split(/\s/)[0] === local) return r.add(`PUSH: ALREADY_PUSHED ${local.slice(0, 12)}`).next('Step 18'); + if (remote.status !== 0) return refuse(`cannot verify the remote branch (${firstLine(remote.stderr)}): restore access before pushing`, 'PUSH_GIT_FAILED'); + if (remote.stdout.split(/\s/)[0] === local) { r.next('Step 18'); return `PUSH: already_pushed remote=origin ref=${branch} head=${local}`; } let plain: PlainFinding[] = []; try { if (!remote.stdout.trim()) plain = checkBranch(branch, loadPlainTitlePolicy(git(cwd, ['rev-parse', '--show-toplevel']).stdout.trim())); } - catch (e: any) { return r.stop(`.gstack/plain-titles.json is invalid (${e.message}): fix it, then rerun push`); } - if (plain.length) return r.add(`BRANCH: refused ${plain.map(f => `"${f.match}"`).join(', ')}`).stop(`the branch name ${branch} is not plain words (docs/ship-policy.md#plain-titles): rename it with git branch -m [-], then rerun push --branch `); + catch (e: any) { return refuse(`.gstack/plain-titles.json is invalid (${e.message}): fix it, then rerun push`); } + if (plain.length) { r.add(`BRANCH: refused ${plain.map(f => `"${f.match}"`).join(', ')}`); return refuse(`the branch name ${branch} is not plain words (docs/ship-policy.md#plain-titles): rename it with git branch -m [-], then rerun push --branch `); } const p = git(cwd, ['push', '-u', 'origin', branch], 600_000); if (p.status !== 0) { const nff = /non-fast-forward|fetch first|rejected/.test(p.stderr); - return r.stop(nff ? 'non-fast-forward: fetch and merge the remote under Step 3\'s conflict rules, run Steps 5-16, then push again; never force-push' - : `push failed (${firstLine(p.stderr)}): repair the auth, hook or network cause, repeat Step 16, then push; never bypass a guard`); + return nff ? refuse('non-fast-forward: fetch and merge the remote under Step 3\'s conflict rules, run Steps 5-16, then push again; never force-push', 'PUSH_REJECTED') + : refuse(`push failed (${firstLine(p.stderr)}): repair the auth, hook or network cause, repeat Step 16, then push; never bypass a guard`, 'PUSH_GIT_FAILED'); } - return r.add(`PUSH: pushed ${local.slice(0, 12)} to origin/${branch}`).next('Step 18'); + r.next('Step 18'); + return `PUSH: pushed remote=origin ref=${branch} head=${local}`; } export async function release(argv: readonly string[], cwd: string): Promise<{ text: string; exit: number }> { const [cmd, ...rest] = argv; const { flag, has } = flagReader(rest); if (!cmd || cmd === '--help' || cmd === '-h' || has('--help')) return { text: RELEASE_HELP + '\n', exit: cmd ? 0 : 2 }; - const usage = (m: string) => ({ text: `gstack-ship-release: ${m}\n`, exit: 2 }); + const usage = (m: string) => ({ text: `gstack-ship-release: ${m}\n${cmd === 'push' ? `${pushFailedLine('PUSH_REFUSED')}\n` : ''}`, exit: 2 }); if (cmd !== 'push' && !flag('--base')) return usage(`${cmd} needs --base `); if (cmd === 'push' && !flag('--branch')) return usage('push needs --branch '); if (cmd === 'accept' && !(lanes(rest) as unknown[]).length) return usage('accept needs at least one --lane