@fabrika/installation-init 0.0.26 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/installation-init",
-	"version": "0.0.26",
+	"version": "0.2.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -26,8 +26,8 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/app": "^0.0.26",
-		"@fabrika/github-app": "^0.0.26",
-		"@fabrika/iam-contract": "^0.0.26"
+		"@fabrika/app": "^0.2.0",
+		"@fabrika/github-app": "^0.2.0",
+		"@fabrika/iam-contract": "^0.2.0"
 	}
 }

package/src/environment.ts

@@ -2,11 +2,23 @@
  * Write the collected configuration into the base repo's GitHub **Environment** (not repo-level), so the
  * platform pipeline reads it per-environment. Secret VALUES go to `gh secret set --env` over STDIN (gh does
  * the libsodium encryption; the value never hits argv or a log line); non-secret values go to
- * `gh variable set --env --body`. The environment itself is created (idempotent PUT) first.
+ * `gh variable set --env --body`. The environment itself is created (idempotent PUT) first, carrying the
+ * deployment-branch policy that is the only thing an Environment buys over a repository secret — a policy
+ * that restricts nothing until `main` itself carries a branch-protection rule.
  */
 
-import { ok, step, warn } from './log'
-import { capture, run } from './shell'
+import { detail, ok, step, warn } from './log'
+import {
+	DEPLOYMENT_BRANCH_POLICY,
+	environmentPolicyCommand,
+	environmentReviewerCommand,
+	type GhAttempt,
+	ghHttpStatus,
+	isPlanLimited,
+	type ProtectionOutcome,
+	unavailableReason,
+} from './protection'
+import { attempt, run, type ShellAttempt, type ShellStep } from './shell'
 
 /** A harmless cwd anchor — `gh` ignores cwd when `--repo` is given. */
 const ANCHOR = process.cwd()
@@ -18,29 +30,125 @@ export interface EnvironmentConfig {
 	secrets: Record<string, string>
 	/** Variable name → value (written via `gh variable set`). */
 	vars: Record<string, string>
+	/**
+	 * Told once whether only a protected branch may use this Environment's secrets, so a provider's
+	 * closing summary can restate it. A callback rather than a return value: both providers already
+	 * bind this function through a `Promise<void>` collaborator.
+	 */
+	onProtection?(outcome: ProtectionOutcome): void
 }
 
+/** The child processes `configureEnvironment` drives. Replaced wholesale in tests. */
+export interface EnvironmentEffects {
+	attempt: GhAttempt
+	run(step: ShellStep): Promise<void>
+}
+
+const defaultEnvironmentEffects: EnvironmentEffects = { attempt, run }
+
 /** Create the GitHub Environment and populate its secrets + variables. */
-export async function configureEnvironment(config: EnvironmentConfig): Promise<void> {
+export async function configureEnvironment(
+	config: EnvironmentConfig,
+	effects: EnvironmentEffects = defaultEnvironmentEffects,
+): Promise<void> {
 	const { repo, environment, secrets, vars } = config
 	step(`Configure the ${environment} GitHub Environment on ${repo}`)
 
-	// Idempotent create (PUT returns the env object on stdout — captured + discarded, never logged).
-	await capture({ command: 'gh', args: ['api', '-X', 'PUT', `repos/${repo}/environments/${environment}`], cwd: ANCHOR })
-	ok(`Environment ${environment} ready.`)
+	// Never `onProtection?.(await …)`: optional-call short-circuiting would skip creating the environment.
+	const protection = await createEnvironment(repo, environment, effects.attempt)
+	config.onProtection?.(protection)
 
 	for (const [name, value] of Object.entries(secrets)) {
 		if (value === '') {
 			warn(`Skipping secret ${name} — no value (the workflow will fail without it; set it manually).`)
 			continue
 		}
-		await run({ command: 'gh', args: ['secret', 'set', name, '--repo', repo, '--env', environment], cwd: ANCHOR, stdin: value })
+		await effects.run({ command: 'gh', args: ['secret', 'set', name, '--repo', repo, '--env', environment], cwd: ANCHOR, stdin: value })
 		ok(`secret ${name} set`)
 	}
 	for (const [name, value] of Object.entries(vars)) {
-		await run({ command: 'gh', args: ['variable', 'set', name, '--repo', repo, '--env', environment, '--body', value], cwd: ANCHOR })
+		await effects.run({ command: 'gh', args: ['variable', 'set', name, '--repo', repo, '--env', environment, '--body', value], cwd: ANCHOR })
 		ok(`variable ${name} set`)
 	}
+	detail(`Recommended hardening — require your own approval before a deploy: ${environmentReviewerCommand(repo, environment)}`)
+}
+
+/**
+ * Idempotent create, carrying the deployment-branch policy MERGED over whatever protection rules the
+ * environment already has — a PUT replaces the whole object, so a reviewer or wait timer the operator
+ * added by hand would otherwise be dropped by the next `init`. A plan that does not offer protection
+ * rules refuses the body, so the environment is then created WITHOUT it rather than not at all; any
+ * other failure is a real error and is rethrown. Stdout is captured and discarded, never logged.
+ */
+async function createEnvironment(repo: string, environment: string, gh: GhAttempt): Promise<ProtectionOutcome> {
+	const command = environmentPolicyCommand(repo, environment)
+	const path = `repos/${repo}/environments/${environment}`
+	const existing = await gh({ command: 'gh', args: ['api', path], cwd: ANCHOR })
+	if (existing.exitCode !== 0 && ghHttpStatus(existing) !== 404) {
+		warn(`Could not read ${environment}'s existing protection rules — a reviewer or wait timer set by hand may be reset by this write.`)
+	}
+	const body = JSON.stringify({ ...existingEnvironmentProtection(existing), deployment_branch_policy: DEPLOYMENT_BRANCH_POLICY })
+	const withPolicy = await gh({ command: 'gh', args: ['api', '-X', 'PUT', path, '--input', '-'], cwd: ANCHOR, stdin: body })
+	if (withPolicy.exitCode === 0) {
+		ok(`Environment ${environment} ready — deployment-branch policy set (it restricts nothing until main carries a protection rule).`)
+		return { applied: true, command }
+	}
+	if (!isPlanLimited(withPolicy)) {
+		throw new Error(`\`gh api -X PUT ${path}\` failed (${unavailableReason(withPolicy)}).`)
+	}
+	const reason = unavailableReason(withPolicy)
+	const plain = await gh({ command: 'gh', args: ['api', '-X', 'PUT', path], cwd: ANCHOR })
+	if (plain.exitCode !== 0) {
+		throw new Error(`\`gh api -X PUT ${path}\` failed (${unavailableReason(plain)}).`)
+	}
+	warn(`Environment ${environment} has NO deployment-branch policy (${reason}) — any branch that can run the workflow can read its secrets.`)
+	detail(`Apply it later: ${command}`)
+	return { applied: false, reason, command }
+}
+
+/** One reviewer in a PUT body: GitHub's GET nests the id under `reviewer`, its PUT wants it flat. */
+interface EnvironmentReviewer {
+	readonly type: string
+	readonly id: number
+}
+
+/** The protection rules a PUT must carry forward, read off `gh api repos/…/environments/<name>`. */
+export interface ExistingEnvironmentProtection {
+	readonly reviewers?: readonly EnvironmentReviewer[]
+	readonly wait_timer?: number
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null
+
+/**
+ * Translate a GET's `protection_rules` into the shape a PUT takes. Anything unrecognised is dropped:
+ * a body GitHub rejects would cost the deployment-branch policy, which is what this write is for.
+ */
+export function existingEnvironmentProtection(result: ShellAttempt): ExistingEnvironmentProtection {
+	if (result.exitCode !== 0) return {}
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(result.stdout)
+	} catch {
+		return {}
+	}
+	if (!isRecord(parsed) || !Array.isArray(parsed['protection_rules'])) return {}
+	const merged: { reviewers?: EnvironmentReviewer[]; wait_timer?: number } = {}
+	for (const rule of parsed['protection_rules']) {
+		if (!isRecord(rule)) continue
+		if (rule['type'] === 'wait_timer' && typeof rule['wait_timer'] === 'number') {
+			merged.wait_timer = rule['wait_timer']
+		}
+		if (rule['type'] === 'required_reviewers' && Array.isArray(rule['reviewers'])) {
+			const reviewers = rule['reviewers'].flatMap((entry: unknown): EnvironmentReviewer[] => {
+				if (!isRecord(entry) || typeof entry['type'] !== 'string' || !isRecord(entry['reviewer'])) return []
+				const id = entry['reviewer']['id']
+				return typeof id === 'number' ? [{ type: entry['type'], id }] : []
+			})
+			if (reviewers.length > 0) merged.reviewers = reviewers
+		}
+	}
+	return merged
 }
 
 /** Trigger the platform workflow (the real deploy runs in GitHub Actions). */

package/src/index.ts

@@ -9,7 +9,14 @@ export {
 	type IamAdminClient,
 	type IamAdminConnection,
 } from './admin'
-export { configureEnvironment, type EnvironmentConfig, triggerPlatformWorkflow } from './environment'
+export {
+	configureEnvironment,
+	type EnvironmentConfig,
+	type EnvironmentEffects,
+	type ExistingEnvironmentProtection,
+	existingEnvironmentProtection,
+	triggerPlatformWorkflow,
+} from './environment'
 export { ghRepoExists, hasGhCli } from './gh'
 export {
 	buildGitHubAppManifest,
@@ -23,11 +30,24 @@ export {
 } from './github-app-manifest'
 export { action, detail, fail, info, ok, step, url, warn } from './log'
 export { confirm, required, retry, secret, secretOrEnv, select, text } from './prompt'
+export {
+	branchProtectionCommand,
+	DEPLOYMENT_BRANCH_POLICY,
+	environmentPolicyCommand,
+	environmentReviewerCommand,
+	type GhAttempt,
+	isPlanLimited,
+	PLAN_LIMITED,
+	probeSidecarBranchProtection,
+	type ProtectionOutcome,
+	protectSidecarBranch,
+} from './protection'
 export {
 	INITIAL_SCAFFOLD_COMMIT_MESSAGE,
 	REFRESH_SCAFFOLD_COMMIT_MESSAGE,
 	scaffoldSidecarRepository,
+	type SidecarScaffoldEffects,
 	type SidecarScaffoldInput,
 	type SidecarScaffoldResult,
 } from './scaffold'
-export { capture, probe, run, type ShellStep } from './shell'
+export { attempt, capture, probe, run, type ShellAttempt, type ShellStep } from './shell'

package/src/protection.ts

@@ -0,0 +1,125 @@
+/**
+ * Harden the sidecar repository the operator owns. It holds the installation's entire credential set,
+ * so a push to `main` must not be able to rewrite the pipeline that reads them. ADR-0025 leaves the
+ * repository operator-owned; this only stops it from being weaker than the account it controls.
+ *
+ * GitHub Free offers neither rule on a PRIVATE repository, so a refusal is REPORTED, never fatal: the
+ * operator is told what is unprotected and the exact command that applies it later. Every body travels
+ * over stdin (`gh api --input -`), never on argv.
+ *
+ * An Environment's `protected_branches` policy is only as strong as the branch rule it points at: with no
+ * protection rule on `main`, the policy admits `main` and restricts nothing. The two are reported together
+ * for that reason.
+ */
+
+import { detail, ok, warn } from './log'
+import { attempt, type ShellAttempt, type ShellStep } from './shell'
+
+/** A harmless cwd anchor — `gh` resolves the repository from the API path, not from cwd. */
+const ANCHOR = process.cwd()
+
+/** No force pushes, no deletions, admins included. No required review: `platform upgrade` pushes to `main`. */
+export const BRANCH_PROTECTION_BODY = JSON.stringify({
+	required_status_checks: null,
+	enforce_admins: true,
+	required_pull_request_reviews: null,
+	restrictions: null,
+	allow_force_pushes: false,
+	allow_deletions: false,
+})
+
+/** Only a protected branch may use the Environment's secrets — and only where such a rule exists. */
+export const DEPLOYMENT_BRANCH_POLICY = { protected_branches: true, custom_branch_policies: false } as const
+
+/** The same policy as a standalone PUT body, for the command an operator runs by hand. */
+export const DEPLOYMENT_BRANCH_POLICY_BODY = JSON.stringify({ deployment_branch_policy: DEPLOYMENT_BRANCH_POLICY })
+
+/** Whether one hardening rule is in place, plus the command that applies it when it is not. */
+export interface ProtectionOutcome {
+	readonly applied: boolean
+	/** One short, printable line saying why it is not applied. Absent when it is. */
+	readonly reason?: string
+	/** The `gh api` invocation that applies this rule later. */
+	readonly command: string
+}
+
+/** Run a `gh` step whose failure is an ANSWER rather than an error. The seam tests drive. */
+export type GhAttempt = (step: ShellStep) => Promise<ShellAttempt>
+
+export const branchProtectionCommand = (repo: string): string =>
+	`printf '%s' '${BRANCH_PROTECTION_BODY}' | gh api -X PUT repos/${repo}/branches/main/protection --input -`
+
+export const environmentPolicyCommand = (repo: string, environment: string): string =>
+	`printf '%s' '${DEPLOYMENT_BRANCH_POLICY_BODY}' | gh api -X PUT repos/${repo}/environments/${environment} --input -`
+
+/** Recommended, never applied by us: an approval click per deploy is the operator's call. */
+export const environmentReviewerCommand = (repo: string, environment: string): string => {
+	const body = '{"reviewers":[{"type":"User","id":%s}],"deployment_branch_policy":{"protected_branches":true,"custom_branch_policies":false}}'
+	return `printf '${body}' "$(gh api user --jq .id)" | gh api -X PUT repos/${repo}/environments/${environment} --input -`
+}
+
+/** The HTTP status `gh` names in its error line (`gh: … (HTTP 403)`), when it names one. */
+export const ghHttpStatus = (result: ShellAttempt): number | undefined => {
+	const status = /\(HTTP (\d{3})\)/.exec(result.stderr)?.[1]
+	return status === undefined ? undefined : Number(status)
+}
+
+/**
+ * The three statuses GitHub answers when a plan does not offer a protection rule. A 422 can also mean a
+ * malformed request, so this is a heuristic — it decides only whether we DEGRADE or give up, never
+ * whether something is safe.
+ */
+export const PLAN_LIMITED: ReadonlySet<number> = new Set([403, 404, 422])
+
+/** True when GitHub's answer is one this code is willing to continue without the rule on. */
+export const isPlanLimited = (result: ShellAttempt): boolean => {
+	const status = ghHttpStatus(result)
+	return status !== undefined && PLAN_LIMITED.has(status)
+}
+
+/** One printable line for a refusal — the plan limit when GitHub named one, the exit code otherwise. */
+export const unavailableReason = (result: ShellAttempt): string => {
+	const status = ghHttpStatus(result)
+	if (isPlanLimited(result)) {
+		return `HTTP ${String(status)} — not offered on this plan for a private repository`
+	}
+	return `\`gh\` exited ${result.exitCode}${status === undefined ? '' : ` (HTTP ${status})`}`
+}
+
+/** Protect `main` on the sidecar. Reports what is unprotected and never throws. */
+export async function protectSidecarBranch(repo: string, gh: GhAttempt = attempt): Promise<ProtectionOutcome> {
+	const command = branchProtectionCommand(repo)
+	const result = await gh({
+		command: 'gh',
+		args: ['api', '-X', 'PUT', `repos/${repo}/branches/main/protection`, '--input', '-'],
+		cwd: ANCHOR,
+		stdin: BRANCH_PROTECTION_BODY,
+	})
+	if (result.exitCode === 0) {
+		ok('Branch protection on main: no force pushes, no deletions, enforced for admins.')
+		return { applied: true, command }
+	}
+	const reason = unavailableReason(result)
+	warn(`main is UNPROTECTED on ${repo} (${reason}) — nothing stops a force-push or a branch delete on main.`)
+	detail(`Apply it later: ${command}`)
+	return { applied: false, reason, command }
+}
+
+/**
+ * Read-only: does `main` already carry a protection rule? For a repository this run did NOT create — a
+ * PUT there would replace whatever the operator configured, so the existing rules are reported, never
+ * overwritten. A 404 is GitHub's answer for "no protection rule", which is exactly what we warn about.
+ */
+export async function probeSidecarBranchProtection(repo: string, gh: GhAttempt = attempt): Promise<ProtectionOutcome> {
+	const command = branchProtectionCommand(repo)
+	const result = await gh({ command: 'gh', args: ['api', `repos/${repo}/branches/main/protection`], cwd: ANCHOR })
+	if (result.exitCode === 0) {
+		ok('Branch protection on main: already configured (left as the operator set it).')
+		return { applied: true, command }
+	}
+	const status = ghHttpStatus(result)
+	const reason = status === 404 ? 'HTTP 404 — no protection rule on main' : unavailableReason(result)
+	warn(`main is UNPROTECTED on ${repo} (${reason}) — nothing stops a force-push or a branch delete on main.`)
+	detail(`Apply it later: ${command}`)
+	return { applied: false, reason, command }
+}

package/src/scaffold.ts

@@ -7,13 +7,18 @@
  * WHAT the files are is the provider's answer, not this module's — `materialize` writes them and `files`
  * lists everything the scaffold ever stages. Scaffold commits carry `[skip ci]`, so a push here cannot
  * deploy anything before `init` has written the GitHub Environment the pipeline reads.
+ *
+ * A freshly created repository is protected before anything else is written to it. An EXISTING one is
+ * only PROBED, never PUT to: its protection is whatever its operator chose, and a blind PUT would replace
+ * stricter rules with ours. Either way the outcome is reported, so an unprotected sidecar is never silent.
  */
 
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { ghRepoExists, hasGhCli } from './gh'
 import { detail, ok, step } from './log'
-import { probe, run } from './shell'
+import { probeSidecarBranchProtection, type ProtectionOutcome, protectSidecarBranch } from './protection'
+import { probe, run, type ShellStep } from './shell'
 
 export const INITIAL_SCAFFOLD_COMMIT_MESSAGE = 'chore: initial fabrika platform scaffold [skip ci]'
 export const REFRESH_SCAFFOLD_COMMIT_MESSAGE = 'chore: refresh fabrika platform scaffold [skip ci]'
@@ -33,63 +38,87 @@ export interface SidecarScaffoldInput {
 export interface SidecarScaffoldResult {
 	readonly dir: string
 	readonly created: boolean
+	/** Applied for a repository this run created, probed read-only for one that already existed. */
+	readonly branchProtection?: ProtectionOutcome
+}
+
+/** The child processes and GitHub calls the scaffold drives. Replaced wholesale in tests. */
+export interface SidecarScaffoldEffects {
+	hasGhCli(): Promise<boolean>
+	repositoryExists(repo: string): Promise<boolean>
+	run(step: ShellStep): Promise<void>
+	probe(step: ShellStep): Promise<number>
+	protect(repo: string): Promise<ProtectionOutcome>
+	probeProtection(repo: string): Promise<ProtectionOutcome>
+}
+
+const defaultScaffoldEffects: SidecarScaffoldEffects = {
+	hasGhCli,
+	repositoryExists: ghRepoExists,
+	run,
+	probe,
+	protect: (repo) => protectSidecarBranch(repo),
+	probeProtection: (repo) => probeSidecarBranchProtection(repo),
 }
 
 /** True when the staged tree has changes to commit (`git diff --cached --quiet` exits 1 on drift). */
-async function hasStagedChanges(dir: string): Promise<boolean> {
-	return (await probe({ command: 'git', args: ['diff', '--cached', '--quiet'], cwd: dir })) !== 0
+async function hasStagedChanges(effects: SidecarScaffoldEffects, dir: string): Promise<boolean> {
+	return (await effects.probe({ command: 'git', args: ['diff', '--cached', '--quiet'], cwd: dir })) !== 0
 }
 
 /**
  * Ensure the sidecar repository exists and carries the current scaffold. Returns the local checkout.
  * Requires `gh` authenticated with rights to create/administer the repository.
  */
-export async function scaffoldSidecarRepository(input: SidecarScaffoldInput): Promise<SidecarScaffoldResult> {
+export async function scaffoldSidecarRepository(
+	input: SidecarScaffoldInput,
+	effects: SidecarScaffoldEffects = defaultScaffoldEffects,
+): Promise<SidecarScaffoldResult> {
 	step(`Scaffold the sidecar repository (${input.repo})`)
-	if (!(await hasGhCli())) {
+	if (!(await effects.hasGhCli())) {
 		throw new Error('`gh` (GitHub CLI) is required — install it and run `gh auth login`.')
 	}
-	return (await ghRepoExists(input.repo)) ? updateExisting(input) : createFresh(input)
+	return (await effects.repositoryExists(input.repo)) ? updateExisting(input, effects) : createFresh(input, effects)
 }
 
 /** Repository already exists: clone if needed, refresh CLI-owned files, commit + push on drift. */
-async function updateExisting(input: SidecarScaffoldInput): Promise<SidecarScaffoldResult> {
+async function updateExisting(input: SidecarScaffoldInput, effects: SidecarScaffoldEffects): Promise<SidecarScaffoldResult> {
 	const { repo, dir } = input
 	if (!existsSync(resolve(dir, '.git'))) {
 		detail(`Cloning ${repo} → ${dir}`)
-		await run({ command: 'gh', args: ['repo', 'clone', repo, dir], cwd: process.cwd() })
+		await effects.run({ command: 'gh', args: ['repo', 'clone', repo, dir], cwd: process.cwd() })
 	} else {
 		detail(`Reusing existing checkout at ${dir}`)
 	}
 	await input.materialize(dir)
-	await run({ command: 'git', args: ['add', ...input.files], cwd: dir })
-	if (!(await hasStagedChanges(dir))) {
+	await effects.run({ command: 'git', args: ['add', ...input.files], cwd: dir })
+	if (!(await hasStagedChanges(effects, dir))) {
 		ok('Sidecar repository already up to date (no scaffold drift).')
-		return { dir, created: false }
+		return { dir, created: false, branchProtection: await effects.probeProtection(repo) }
 	}
-	await run({ command: 'git', args: ['commit', '-m', REFRESH_SCAFFOLD_COMMIT_MESSAGE], cwd: dir })
-	await run({ command: 'git', args: ['push'], cwd: dir })
+	await effects.run({ command: 'git', args: ['commit', '-m', REFRESH_SCAFFOLD_COMMIT_MESSAGE], cwd: dir })
+	await effects.run({ command: 'git', args: ['push'], cwd: dir })
 	ok('Sidecar repository scaffold updated + pushed.')
-	return { dir, created: false }
+	return { dir, created: false, branchProtection: await effects.probeProtection(repo) }
 }
 
 /** Repository does not exist: build a local checkout, commit the scaffold, create + push in one `gh` call. */
-async function createFresh(input: SidecarScaffoldInput): Promise<SidecarScaffoldResult> {
+async function createFresh(input: SidecarScaffoldInput, effects: SidecarScaffoldEffects): Promise<SidecarScaffoldResult> {
 	const { repo, dir } = input
 	if (existsSync(resolve(dir, '.git'))) {
 		throw new Error(`${dir} is already a git repo but ${repo} does not exist on GitHub — resolve the mismatch by hand.`)
 	}
 	detail(`Creating a fresh checkout at ${dir}`)
-	await run({ command: 'git', args: ['init', '-b', 'main', dir], cwd: process.cwd() })
+	await effects.run({ command: 'git', args: ['init', '-b', 'main', dir], cwd: process.cwd() })
 	await input.materialize(dir)
-	await run({ command: 'git', args: ['add', ...input.files], cwd: dir })
-	await run({ command: 'git', args: ['commit', '-m', INITIAL_SCAFFOLD_COMMIT_MESSAGE], cwd: dir })
+	await effects.run({ command: 'git', args: ['add', ...input.files], cwd: dir })
+	await effects.run({ command: 'git', args: ['commit', '-m', INITIAL_SCAFFOLD_COMMIT_MESSAGE], cwd: dir })
 	detail(`Creating ${repo} (private) and pushing`)
-	await run({
+	await effects.run({
 		command: 'gh',
 		args: ['repo', 'create', repo, '--private', '--source', dir, '--remote', 'origin', '--push'],
 		cwd: process.cwd(),
 	})
 	ok(`Sidecar repository ${repo} created + pushed.`)
-	return { dir, created: true }
+	return { dir, created: true, branchProtection: await effects.protect(repo) }
 }

package/src/shell.ts

@@ -106,3 +106,26 @@ export async function probe(step: ShellStep): Promise<number> {
 	})
 	return proc.exited
 }
+
+/** What a step that is allowed to fail reported: its exit code plus everything it wrote. */
+export interface ShellAttempt {
+	readonly exitCode: number
+	readonly stdout: string
+	readonly stderr: string
+}
+
+/**
+ * Run a step WITHOUT throwing, capturing both pipes. For a call whose failure is an ANSWER rather than
+ * an error — a `gh api` PUT that GitHub refuses because the plan does not offer the feature.
+ */
+export async function attempt(step: ShellStep): Promise<ShellAttempt> {
+	const proc = Bun.spawn([step.command, ...step.args], {
+		cwd: step.cwd,
+		env: { ...process.env, ...step.env },
+		stdin: step.stdin !== undefined ? new TextEncoder().encode(step.stdin) : 'ignore',
+		stdout: 'pipe',
+		stderr: 'pipe',
+	})
+	const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()])
+	return { exitCode: await proc.exited, stdout, stderr }
+}