@fabrika/installation-init 0.0.1

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@fabrika/installation-init",
+	"version": "0.0.1",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/fabrika-platform.git",
+		"directory": "packages/installation-init"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"!src/**/__tests__/**"
+	],
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	}
+}

package/src/environment.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+
+import { ok, step, warn } from './log'
+import { capture, run } from './shell'
+
+/** A harmless cwd anchor — `gh` ignores cwd when `--repo` is given. */
+const ANCHOR = process.cwd()
+
+export interface EnvironmentConfig {
+	repo: string
+	environment: string
+	/** Secret name → value (written via `gh secret set`). */
+	secrets: Record<string, string>
+	/** Variable name → value (written via `gh variable set`). */
+	vars: Record<string, string>
+}
+
+/** Create the GitHub Environment and populate its secrets + variables. */
+export async function configureEnvironment(config: EnvironmentConfig): 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.`)
+
+	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 })
+		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 })
+		ok(`variable ${name} set`)
+	}
+}
+
+/** Trigger the platform workflow (the real deploy runs in GitHub Actions). */
+export async function triggerPlatformWorkflow(repo: string): Promise<void> {
+	await run({ command: 'gh', args: ['workflow', 'run', 'platform.yml', '--repo', repo], cwd: ANCHOR })
+}

package/src/gh.ts

@@ -0,0 +1,24 @@
+/**
+ * `gh` CLI helpers. The CLI shells out to `gh` for everything GitHub-side (repo create, secrets, the
+ * deploy trigger) rather than re-implementing the REST API + libsodium secret encryption — `gh` already
+ * does the encryption for `secret set`. These are the small probes shared across scaffold + environment.
+ */
+
+import { probe } from './shell'
+
+/** The repo root — a harmless cwd anchor for `gh` shell-outs (gh ignores cwd when `--repo` is given). */
+const ANCHOR = process.cwd()
+
+/** Is the `gh` CLI available + authenticated? `gh auth status` exits non-zero when not logged in. */
+export async function hasGhCli(): Promise<boolean> {
+	try {
+		return (await probe({ command: 'gh', args: ['auth', 'status'], cwd: ANCHOR })) === 0
+	} catch {
+		return false
+	}
+}
+
+/** Does `<org>/<repo>` exist and is it visible to the current `gh` login? */
+export async function ghRepoExists(repo: string): Promise<boolean> {
+	return (await probe({ command: 'gh', args: ['repo', 'view', repo, '--json', 'nameWithOwner'], cwd: ANCHOR })) === 0
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { configureEnvironment, type EnvironmentConfig, triggerPlatformWorkflow } from './environment'
+export { ghRepoExists, hasGhCli } from './gh'
+export { action, detail, fail, info, ok, step, url, warn } from './log'
+export { confirm, required, retry, secret, secretOrEnv, select, text } from './prompt'
+export {
+	INITIAL_SCAFFOLD_COMMIT_MESSAGE,
+	REFRESH_SCAFFOLD_COMMIT_MESSAGE,
+	scaffoldSidecarRepository,
+	type SidecarScaffoldInput,
+	type SidecarScaffoldResult,
+} from './scaffold'
+export { capture, probe, run, type ShellStep } from './shell'

package/src/log.ts

@@ -0,0 +1,81 @@
+/**
+ * Console formatting for the fabrika CLI — a thin, consistent presentation layer over the orchestration
+ * in the other modules. Every line the operator sees during `init` flows through here.
+ *
+ * HARD RULE (see the worker CLAUDE.md): this module NEVER prints a secret VALUE. Callers may pass
+ * secret NAMES, counts, or "✓ set" confirmations — never the bytes of a token / key / PEM / webhook
+ * secret. There is deliberately no helper here that takes a secret value, so a careless caller can't
+ * accidentally route one through formatting.
+ */
+
+const BOLD = '\x1b[1m'
+const DIM = '\x1b[2m'
+const RESET = '\x1b[0m'
+const GREEN = '\x1b[32m'
+const YELLOW = '\x1b[33m'
+const RED = '\x1b[31m'
+const CYAN = '\x1b[36m'
+
+let stepNo = 0
+
+/** A numbered, bold section heading — the spine of the CLI's progress. Resets nothing else. */
+export function step(title: string): void {
+	stepNo += 1
+	console.log(`\n${BOLD}${CYAN}[${stepNo}] ${title}${RESET}`)
+}
+
+/** A plain informational line, slightly indented under the current step. */
+export function info(message: string): void {
+	console.log(`    ${message}`)
+}
+
+/** A dim, secondary detail line (context the operator usually skims). */
+export function detail(message: string): void {
+	console.log(`    ${DIM}${message}${RESET}`)
+}
+
+/** A success line (green ✓). */
+export function ok(message: string): void {
+	console.log(`    ${GREEN}✓${RESET} ${message}`)
+}
+
+/** A non-fatal warning (yellow ⚠) — the CLI keeps going. */
+export function warn(message: string): void {
+	console.log(`    ${YELLOW}⚠${RESET} ${message}`)
+}
+
+/** A failure line (red ✗). Does NOT exit — the caller decides whether to throw. */
+export function fail(message: string): void {
+	console.log(`    ${RED}✗${RESET} ${message}`)
+}
+
+/**
+ * A boxed OPERATOR ACTION — something the human must do out-of-band (open a URL, log in, click
+ * "create", paste a value back). These are the hand-off points the whole bring-up is built around, so
+ * they are visually loud and never scroll past unnoticed.
+ */
+export function action(title: string, lines: string[]): void {
+	const width = Math.max(title.length, ...lines.map((l) => stripAnsi(l).length)) + 4
+	const bar = '─'.repeat(width)
+	console.log(`\n${YELLOW}┌${bar}┐${RESET}`)
+	console.log(`${YELLOW}│${RESET}  ${BOLD}${title}${RESET}${' '.repeat(width - title.length - 2)}${YELLOW}│${RESET}`)
+	if (lines.length > 0) {
+		console.log(`${YELLOW}├${bar}┤${RESET}`)
+		for (const line of lines) {
+			const visibleLen = stripAnsi(line).length
+			console.log(`${YELLOW}│${RESET}  ${line}${' '.repeat(width - visibleLen - 2)}${YELLOW}│${RESET}`)
+		}
+	}
+	console.log(`${YELLOW}└${bar}┘${RESET}`)
+}
+
+/** Render a URL prominently (cyan, underlined) — operators copy these by eye. */
+export function url(value: string): string {
+	return `${CYAN}\x1b[4m${value}${RESET}`
+}
+
+/** Strip ANSI escape codes so box-drawing can measure the VISIBLE width of a line. */
+function stripAnsi(value: string): string {
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: matching ANSI escape sequences by design.
+	return value.replace(/\x1b\[[0-9;]*m/g, '')
+}

package/src/prompt.ts

@@ -0,0 +1,197 @@
+/**
+ * Interactive prompts for the fabrika CLI, over `node:readline/promises` on the real TTY.
+ *
+ * `secret()` is the security-critical one: it reads a value WITHOUT echoing it to the terminal (no
+ * keystrokes, no final value), so a token/key pasted at the prompt never lands in scrollback or a
+ * screen-share. Every other prompt echoes normally. None of these functions ever log the value they
+ * return — the caller routes secrets into a child-process env, never back through `log.ts`.
+ */
+
+import { createInterface, type Interface } from 'node:readline/promises'
+import { fail, info } from './log'
+
+/** A free-text prompt. Returns the trimmed answer, or `fallback` when the operator just hits enter. */
+export async function text(question: string, fallback?: string): Promise<string> {
+	const rl = openReadline()
+	try {
+		const suffix = fallback !== undefined && fallback !== '' ? ` [${fallback}]` : ''
+		const answer = stripTerminalCruft(await rl.question(`${question}${suffix}: `)).trim()
+		if (answer === '' && fallback !== undefined) {
+			return fallback
+		}
+		return answer
+	} finally {
+		rl.close()
+	}
+}
+
+/**
+ * A required free-text prompt: re-asks until the operator gives a non-empty answer (or a fallback is
+ * supplied and accepted). Used for values the CLI cannot proceed without.
+ */
+export async function required(question: string, fallback?: string): Promise<string> {
+	for (;;) {
+		const value = await text(question, fallback)
+		if (value !== '') {
+			return value
+		}
+		console.log('    (a value is required)')
+	}
+}
+
+/**
+ * A HIDDEN-ECHO prompt for secret values. Keystrokes are not echoed and the final value is not
+ * printed — the line is consumed silently. The captured value is run through `stripTerminalCruft` to
+ * remove bracketed-paste markers / escape sequences some terminals inject around a paste (which would
+ * otherwise corrupt a pasted token), then returned. The value is NEVER logged by this module.
+ */
+export async function secret(question: string): Promise<string> {
+	process.stdout.write(`${question}: `)
+	const rl = openReadline()
+	// While reading, intercept the output stream so readline's own echo of the typed characters is
+	// suppressed — only the newline at the end is allowed through, to move the cursor down.
+	const muted = muteOutput()
+	try {
+		const answer = await rl.question('')
+		return stripTerminalCruft(answer)
+	} finally {
+		muted.restore()
+		rl.close()
+		// readline swallowed the echoed newline while muted; emit one so the next line starts fresh.
+		process.stdout.write('\n')
+	}
+}
+
+/**
+ * Strip terminal control cruft from a captured answer: bracketed-paste markers (`ESC[200~`/`ESC[201~`),
+ * any CSI/OSC escape sequence, and stray control characters. A real token / key / id / domain / email
+ * never contains these, so removing them is safe — and it fixes two real cases on an interactive TTY:
+ *  - a paste arriving with bracketed-paste markers embedded; and
+ *  - a terminal's OSC 10/11 color-query RESPONSE leaking into a later prompt. Some CLIs (notably `gh`,
+ *    via Go's termenv) query the background color with `ESC]11;?`; the terminal correctly replies with
+ *    `ESC]11;rgb:RRRR/GGGG/BBBB`, but that reply can land in the next readline read. In `terminal:true`
+ *    mode readline's keypress parser eats the `ESC]`, leaving the bare `11;rgb:…` payload in the line —
+ *    so we strip both the full escape sequence AND that bare leftover.
+ */
+function stripTerminalCruft(value: string): string {
+	return (
+		value
+			// Full OSC sequences: ESC ] … (BEL or ST). e.g. an OSC 10/11 dynamic-color response.
+			// biome-ignore lint/suspicious/noControlCharactersInRegex: matching terminal escape bytes by design.
+			.replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '')
+			// Bare OSC 10/11 color responses whose ESC introducer readline's keypress parser ate
+			// (`1X;rgb:RRRR/GGGG/BBBB`, optional leading `]`). Never appears in a real entered value.
+			.replace(/\]?1[0-9];rgb:[0-9a-fA-F]{1,4}(?:\/[0-9a-fA-F]{1,4}){2}/g, '')
+			// CSI sequences (bracketed-paste markers, cursor-position responses ESC[N;MR, SGR, …).
+			// biome-ignore lint/suspicious/noControlCharactersInRegex: matching terminal escape bytes by design.
+			.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '')
+			// Any stray C0/C1 control char + DEL.
+			// biome-ignore lint/suspicious/noControlCharactersInRegex: matching terminal control bytes by design.
+			.replace(/[\x00-\x1f\x7f]/g, '')
+	)
+}
+
+/**
+ * Read a secret from the environment (escape hatch / CI path) OR, failing that, the hidden prompt. If
+ * `process.env[envName]` is set, its trimmed value is used and we log ONLY that the env var was the
+ * source (never the value) — so an operator can pre-set e.g. `CLOUDFLARE_API_TOKEN=… bunx …` and
+ * skip the interactive capture entirely (useful when the hidden prompt misbehaves on a given terminal).
+ * Otherwise it falls back to `secret()`. The result is always trimmed.
+ */
+export async function secretOrEnv(envName: string, question: string): Promise<string> {
+	const fromEnv = process.env[envName]
+	if (fromEnv !== undefined && fromEnv.trim() !== '') {
+		info(`Using ${envName} from the environment (not prompting).`)
+		return fromEnv.trim()
+	}
+	return (await secret(question)).trim()
+}
+
+/** A yes/no confirmation. Defaults to `defaultYes` on an empty answer. */
+export async function confirm(question: string, defaultYes = false): Promise<boolean> {
+	const rl = openReadline()
+	try {
+		const hint = defaultYes ? 'Y/n' : 'y/N'
+		const answer = stripTerminalCruft(await rl.question(`${question} [${hint}]: `)).trim().toLowerCase()
+		if (answer === '') {
+			return defaultYes
+		}
+		return answer === 'y' || answer === 'yes'
+	} finally {
+		rl.close()
+	}
+}
+
+/**
+ * Run an async action that VALIDATES input (verify a token, resolve a path). On a thrown error, show
+ * the message and re-ask — so a typo'd or rejected value re-prompts in place instead of crashing the
+ * whole CLI and losing every value already entered. Declining the retry re-throws, so the caller's
+ * top-level handler still aborts cleanly. The `action` must itself re-read its inputs (do the
+ * `secret()`/`text()` prompt INSIDE it) so a retry actually asks again.
+ */
+export async function retry<T>(label: string, action: () => Promise<T>): Promise<T> {
+	for (;;) {
+		try {
+			return await action()
+		} catch (error) {
+			fail(error instanceof Error ? error.message : String(error))
+			if (!(await confirm(`${label} — try again?`, true))) {
+				throw error instanceof Error ? error : new Error(String(error))
+			}
+		}
+	}
+}
+
+/**
+ * A single-choice menu. Prints the numbered options and returns the chosen value. Re-asks on an
+ * out-of-range answer. With exactly one option it returns it without prompting.
+ */
+export async function select<T>(question: string, options: { label: string; value: T }[]): Promise<T> {
+	if (options.length === 0) {
+		throw new Error('select(): no options to choose from')
+	}
+	const only = options[0]
+	if (options.length === 1 && only !== undefined) {
+		return only.value
+	}
+	console.log(question)
+	options.forEach((opt, i) => {
+		console.log(`    ${i + 1}) ${opt.label}`)
+	})
+	const rl = openReadline()
+	try {
+		for (;;) {
+			const answer = stripTerminalCruft(await rl.question('    choose [1]: ')).trim()
+			const index = answer === '' ? 0 : Number.parseInt(answer, 10) - 1
+			const chosen = options[index]
+			if (chosen !== undefined) {
+				return chosen.value
+			}
+			console.log(`    (enter a number between 1 and ${options.length})`)
+		}
+	} finally {
+		rl.close()
+	}
+}
+
+/** Open a fresh readline interface bound to the process stdio. */
+function openReadline(): Interface {
+	return createInterface({ input: process.stdin, output: process.stdout, terminal: true })
+}
+
+/**
+ * Temporarily replace `process.stdout.write` so nothing readline echoes during a secret read reaches
+ * the terminal. Returns a `restore()` that puts the original back. We only mute stdout (where the
+ * echo goes); stderr is untouched so a crash still surfaces.
+ */
+function muteOutput(): { restore: () => void } {
+	const original = process.stdout.write.bind(process.stdout)
+	// Swallow everything written while muted. Typed characters and the echoed value go nowhere.
+	const muted: typeof process.stdout.write = () => true
+	process.stdout.write = muted
+	return {
+		restore: () => {
+			process.stdout.write = original
+		},
+	}
+}

package/src/scaffold.ts

@@ -0,0 +1,95 @@
+/**
+ * The mechanics of a sidecar repository: ensure `<owner>/<name>` exists on GitHub, materialize the
+ * files the CLI owns, commit and push. Idempotent, and the same on every provider:
+ *   - repo absent  → create a fresh local checkout, commit the scaffold, `gh repo create … --source --push`,
+ *   - repo present → clone it (if not already local), refresh the CLI-owned files, commit + push on drift.
+ *
+ * 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.
+ */
+
+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'
+
+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]'
+
+export interface SidecarScaffoldInput {
+	/** The sidecar repository, e.g. `contember/fabrika-zerops-test`. */
+	readonly repo: string
+	/** Local directory to check the repository out into. */
+	readonly dir: string
+	/** Every path the scaffold stages — CLI-owned files plus any operator-owned, write-once pin. */
+	readonly files: readonly string[]
+	/** Write the scaffold into an existing directory. Called for a fresh creation and for a refresh alike. */
+	materialize(dir: string): Promise<void>
+}
+
+/** Result of scaffolding: the local checkout dir + whether the repository was freshly created. */
+export interface SidecarScaffoldResult {
+	readonly dir: string
+	readonly created: boolean
+}
+
+/** 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
+}
+
+/**
+ * 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> {
+	step(`Scaffold the sidecar repository (${input.repo})`)
+	if (!(await 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)
+}
+
+/** Repository already exists: clone if needed, refresh CLI-owned files, commit + push on drift. */
+async function updateExisting(input: SidecarScaffoldInput): 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() })
+	} 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))) {
+		ok('Sidecar repository already up to date (no scaffold drift).')
+		return { dir, created: false }
+	}
+	await run({ command: 'git', args: ['commit', '-m', REFRESH_SCAFFOLD_COMMIT_MESSAGE], cwd: dir })
+	await run({ command: 'git', args: ['push'], cwd: dir })
+	ok('Sidecar repository scaffold updated + pushed.')
+	return { dir, created: false }
+}
+
+/** Repository does not exist: build a local checkout, commit the scaffold, create + push in one `gh` call. */
+async function createFresh(input: SidecarScaffoldInput): 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 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 })
+	detail(`Creating ${repo} (private) and pushing`)
+	await 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 }
+}

package/src/shell.ts

@@ -0,0 +1,97 @@
+/**
+ * Shell-out helpers for the CLI, over `Bun.spawn`. Every orchestrated step (git, gh, the deploy
+ * trigger) goes through here so the rules are enforced in ONE place:
+ *   - argv is passed verbatim (no shell) — nothing interpolated can be a metacharacter,
+ *   - the child gets ONLY `process.env` + the explicit `env` the step needs,
+ *   - on a non-zero exit we throw a SHORT message naming the command — never the child env, never a
+ *     secret value, never the raw error object (which could carry a token-bearing URL).
+ */
+
+/** A child step to run: the command + args, its cwd, and the extra env it needs (merged over process.env). */
+export interface ShellStep {
+	command: string
+	args: string[]
+	cwd: string
+	/** Extra env vars for this child only. Secret VALUES live here and nowhere else. */
+	env?: Record<string, string>
+	/** Optional stdin written to the child (used for `gh secret set`, which reads the value from stdin). */
+	stdin?: string
+}
+
+/**
+ * Run a step, STREAMING its stdout/stderr to this terminal so the operator watches the underlying
+ * tool live (git/gh print progress). Throws on a non-zero exit. The thrown message names the command
+ * + exit code only.
+ */
+export async function run(step: ShellStep): Promise<void> {
+	// stdout/stderr are PIPED (not the inherited TTY) and streamed back here. A child that probes the
+	// terminal — notably `gh`, which queries the background color with `ESC]11;?` (Go's termenv) on a
+	// TTY stdout — sees a NON-tty output and SKIPS the probe, so its query/response can't leak into a
+	// later interactive prompt (readline would otherwise read the stray `…;rgb:…` reply). The operator
+	// still watches output live; a child may drop ANSI colors since it no longer detects a TTY.
+	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) : 'inherit',
+		stdout: 'pipe',
+		stderr: 'pipe',
+	})
+	await Promise.all([
+		pump(proc.stdout, (chunk) => void process.stdout.write(chunk)),
+		pump(proc.stderr, (chunk) => void process.stderr.write(chunk)),
+	])
+	const exitCode = await proc.exited
+	if (exitCode !== 0) {
+		throw new Error(`\`${step.command} ${step.args.join(' ')}\` failed (exit ${exitCode}).`)
+	}
+}
+
+/** Stream a child pipe to a sink, chunk by chunk, until it closes (a live tee that exposes no TTY). */
+async function pump(src: ReadableStream<Uint8Array>, write: (chunk: Uint8Array) => void): Promise<void> {
+	const reader = src.getReader()
+	try {
+		for (;;) {
+			const { done, value } = await reader.read()
+			if (done) {
+				return
+			}
+			if (value !== undefined) {
+				write(value)
+			}
+		}
+	} finally {
+		reader.releaseLock()
+	}
+}
+
+/**
+ * Run a step and CAPTURE its stdout (returned), while streaming stderr to this terminal. Used when we
+ * need to parse a tool's output (e.g. `gh repo view`). Throws on a non-zero exit; the captured stdout
+ * is NOT echoed by this helper.
+ */
+export async function capture(step: ShellStep): Promise<string> {
+	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: 'inherit',
+	})
+	const stdout = await new Response(proc.stdout).text()
+	const exitCode = await proc.exited
+	if (exitCode !== 0) {
+		throw new Error(`\`${step.command} ${step.args.join(' ')}\` failed (exit ${exitCode}).`)
+	}
+	return stdout
+}
+
+/** Run a step quietly: no stdout/stderr to the terminal, returns the exit code. For existence probes. */
+export async function probe(step: ShellStep): Promise<number> {
+	const proc = Bun.spawn([step.command, ...step.args], {
+		cwd: step.cwd,
+		env: { ...process.env, ...step.env },
+		stdout: 'ignore',
+		stderr: 'ignore',
+	})
+	return proc.exited
+}