@fabrika/installation-init 0.2.0 → 0.3.2

package/package.json

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

package/src/checkout.ts

@@ -0,0 +1,45 @@
+import { existsSync, realpathSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+
+/** `--checkout=<dir>`: where `platform init` keeps the sidecar repository's local checkout. */
+export const CHECKOUT_FLAG = '--checkout'
+
+/** `dir` with every symlink in its existing part resolved, so a link into a repository is seen as inside it. */
+const physicalPath = (dir: string): string => {
+	let existing = dir
+	while (!existsSync(existing)) {
+		const parent = dirname(existing)
+		if (parent === existing) return dir
+		existing = parent
+	}
+	return join(realpathSync(existing), relative(existing, dir))
+}
+
+/** The git work tree that encloses `dir`, not counting `dir` being a checkout itself. */
+const enclosingRepository = (dir: string): string | undefined => {
+	let current = dirname(physicalPath(dir))
+	while (true) {
+		if (existsSync(resolve(current, '.git'))) return current
+		const parent = dirname(current)
+		if (parent === current) return undefined
+		current = parent
+	}
+}
+
+/**
+ * The sidecar checkout directory: `--checkout`, or `defaultName` in the working directory.
+ *
+ * Refused inside another repository, where it would sit as an untracked nested repository that a
+ * blanket `git add` records as a gitlink.
+ */
+export const sidecarCheckoutDir = (explicit: string | undefined, defaultName: string, cwd: string = process.cwd()): string => {
+	const dir = resolve(cwd, explicit ?? defaultName)
+	const repository = enclosingRepository(dir)
+	if (repository !== undefined) {
+		throw new Error(
+			`the sidecar checkout ${dir} would sit inside the git repository at ${repository}. `
+				+ `Pass ${CHECKOUT_FLAG}=<dir> outside it, or run init from a directory that is not in a repository`,
+		)
+	}
+	return dir
+}

package/src/confirmations.ts

@@ -0,0 +1,44 @@
+import { confirm as promptConfirm } from './prompt'
+
+/** The one question `install` and `init` ask. Injected so a flow can be exercised without a TTY. */
+export interface Confirmations {
+	confirm(question: string, defaultYes?: boolean): Promise<boolean>
+}
+
+/**
+ * The one way a confirming command runs with nobody watching it.
+ *
+ * Every confirmation defaults to yes, so a pipe carrying blank lines would answer all of them with
+ * nobody reading what they agree to — which is why saying yes unattended is a FLAG and never an
+ * inference: it makes the choice explicit, and it puts it in the shell history of whoever ran it.
+ */
+export const UNATTENDED_FLAG = '--yes'
+
+/**
+ * How a command's confirmations are answered — and the refusal when nothing can answer them.
+ *
+ * Unattended, each question is still printed with the answer it was given, so the run leaves the same
+ * record of what was agreed to that an interactive one does.
+ */
+export const confirmations = (
+	unattended: boolean,
+	stdin: { readonly isTTY?: boolean },
+	announce: (line: string) => void,
+	whatItDoes: string,
+): Confirmations => {
+	if (unattended) {
+		return {
+			confirm: (question) => {
+				announce(`${question} yes (${UNATTENDED_FLAG})`)
+				return Promise.resolve(true)
+			},
+		}
+	}
+	if (stdin.isTTY !== true) {
+		throw new Error(
+			`stdin is not a terminal, so nobody is here to confirm what this command does — it ${whatItDoes}. `
+				+ `Run it from a terminal, or pass \`${UNATTENDED_FLAG}\` to answer every confirmation yes unattended`,
+		)
+	}
+	return { confirm: (question, defaultYes) => promptConfirm(question, defaultYes) }
+}

package/src/environment.ts

@@ -7,6 +7,7 @@
  * that restricts nothing until `main` itself carries a branch-protection rule.
  */
 
+import { z } from 'zod'
 import { detail, ok, step, warn } from './log'
 import {
 	DEPLOYMENT_BRANCH_POLICY,
@@ -118,7 +119,11 @@ export interface ExistingEnvironmentProtection {
 	readonly wait_timer?: number
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null
+const protectionSchema = z.object({ protection_rules: z.array(z.unknown()) })
+const waitTimerSchema = z.object({ type: z.literal('wait_timer'), wait_timer: z.number() })
+const reviewersSchema = z.object({ type: z.literal('required_reviewers'), reviewers: z.array(z.unknown()) })
+const reviewerSchema = z.object({ type: z.string(), reviewer: z.object({ id: z.number() }) })
+	.transform(({ type, reviewer }) => ({ type, id: reviewer.id }))
 
 /**
  * Translate a GET's `protection_rules` into the shape a PUT takes. Anything unrecognised is dropped:
@@ -132,18 +137,19 @@ export function existingEnvironmentProtection(result: ShellAttempt): ExistingEnv
 	} catch {
 		return {}
 	}
-	if (!isRecord(parsed) || !Array.isArray(parsed['protection_rules'])) return {}
+	const protection = protectionSchema.safeParse(parsed)
+	if (!protection.success) 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']
+	for (const rule of protection.data.protection_rules) {
+		const timer = waitTimerSchema.safeParse(rule)
+		if (timer.success) {
+			merged.wait_timer = timer.data.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 }] : []
+		const required = reviewersSchema.safeParse(rule)
+		if (required.success) {
+			const reviewers = required.data.reviewers.flatMap((entry): EnvironmentReviewer[] => {
+				const reviewer = reviewerSchema.safeParse(entry)
+				return reviewer.success ? [reviewer.data] : []
 			})
 			if (reviewers.length > 0) merged.reviewers = reviewers
 		}

package/src/index.ts

@@ -9,6 +9,8 @@ export {
 	type IamAdminClient,
 	type IamAdminConnection,
 } from './admin'
+export { CHECKOUT_FLAG, sidecarCheckoutDir } from './checkout'
+export { type Confirmations, confirmations, UNATTENDED_FLAG } from './confirmations'
 export {
 	configureEnvironment,
 	type EnvironmentConfig,
@@ -18,18 +20,9 @@ export {
 	triggerPlatformWorkflow,
 } from './environment'
 export { ghRepoExists, hasGhCli } from './gh'
-export {
-	buildGitHubAppManifest,
-	type CreatedGitHubApp,
-	createGitHubAppViaManifest,
-	exchangeGitHubAppManifestCode,
-	githubAppInstallationUrl,
-	type GitHubAppManifestFetch,
-	type GitHubAppManifestInput,
-	type GitHubAppManifestRuntime,
-} 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 { type CommandEnv, describeArgument, readEnv, readFlag, requiredSetting, setting, shellWord } from './options'
+export { confirm } from './prompt'
 export {
 	branchProtectionCommand,
 	DEPLOYMENT_BRANCH_POLICY,

package/src/options.ts

@@ -0,0 +1,35 @@
+// The reading rules every `fabrika platform … --provider=zerops` parser shares: a flag beats the
+// environment variable beside it, a blank value is an absent one, and a flag given twice is refused.
+
+export type CommandEnv = Record<string, string | undefined>
+
+export const readFlag = (argv: readonly string[], name: string): string | undefined => {
+	const prefix = `${name}=`
+	const matches = argv.filter((arg) => arg.startsWith(prefix))
+	if (matches.length > 1) {
+		throw new Error(`${name} was given more than once`)
+	}
+	const value = matches[0]?.slice(prefix.length)
+	return value === undefined || value.trim() === '' ? undefined : value.trim()
+}
+
+export const readEnv = (env: CommandEnv, name: string): string | undefined => {
+	const value = env[name]
+	return value === undefined || value.trim() === '' ? undefined : value.trim()
+}
+
+export const setting = (argv: readonly string[], env: CommandEnv, flag: string, variable: string): string | undefined =>
+	readFlag(argv, flag) ?? readEnv(env, variable)
+
+export const requiredSetting = (value: string | undefined, flag: string, variable: string): string => {
+	if (value === undefined) {
+		throw new Error(`${flag}=<value> or ${variable} is required`)
+	}
+	return value
+}
+
+/** How a refusal names an argument: a flag by its name only, never its value, which may be a pasted credential. */
+export const describeArgument = (arg: string): string => arg.startsWith('-') ? `\`${arg.split('=')[0]}\`` : 'a positional argument'
+
+/** One argument as a POSIX shell reads it back unchanged, for the rerun command a declined step prints. */
+export const shellWord = (arg: string): string => /^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`

package/src/prompt.ts

@@ -1,69 +1,23 @@
 /**
- * Interactive prompts for the fabrika CLI, over `node:readline/promises`.
+ * The one interactive question the fabrika CLI asks: a yes/no confirmation before a step that leaves
+ * the operator's machine. Every other input is a flag or an environment variable, and a run with no
+ * terminal answers confirmations with `--yes` (`confirmations.ts`), so this reads a TTY only.
  *
- * `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`.
- *
- * ── Why stdin is read two different ways ──────────────────────────────────────────────────────────
- *
- * A PIPED stdin is read by ONE reader for the whole command. Closing a readline discards whatever it
- * has already buffered, so a fresh interface per question swallows every answer after the first and
- * the command stops on question 2 — which is what made `platform init` undrivable without a PTY.
- *
- * A TTY keeps a fresh interface per question, closed afterwards. A persistent one holds the terminal
- * in raw mode (`-icanon -echo`, measured) between questions, and `init` spawns `git` and `gh` between
- * them — a child inheriting a raw terminal echoes nothing and stair-steps its output.
+ * A fresh interface per question, closed afterwards: a persistent one holds the terminal in raw mode
+ * (`-icanon -echo`, measured) between questions, and init spawns `git` and `gh` between them — a child
+ * inheriting a raw terminal echoes nothing and stair-steps its output.
  */
 
-import { createInterface, type Interface } from 'node:readline/promises'
-import type { Readable, Writable } from 'node:stream'
-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 suffix = fallback !== undefined && fallback !== '' ? ` [${fallback}]` : ''
-	const answer = stripTerminalCruft(await ask(`${question}${suffix}: `)).trim()
-	if (answer === '' && fallback !== undefined) {
-		return fallback
-	}
-	return answer
-}
-
-/**
- * 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)')
-	}
-}
+import { createInterface } from 'node:readline/promises'
 
-/**
- * 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}: `)
-	// 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 ask('', question)
-		return stripTerminalCruft(answer)
-	} finally {
-		muted.restore()
-		// readline swallowed the echoed newline while muted; emit one so the next line starts fresh.
-		process.stdout.write('\n')
+/** A yes/no confirmation. Defaults to `defaultYes` on an empty answer. */
+export async function confirm(question: string, defaultYes = false): Promise<boolean> {
+	const hint = defaultYes ? 'Y/n' : 'y/N'
+	const answer = stripTerminalCruft(await ask(`${question} [${hint}]: `)).trim().toLowerCase()
+	if (answer === '') {
+		return defaultYes
 	}
+	return answer === 'y' || answer === 'yes'
 }
 
 /**
@@ -95,207 +49,14 @@ function stripTerminalCruft(value: string): string {
 	)
 }
 
-/**
- * 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 hint = defaultYes ? 'Y/n' : 'y/N'
-	const answer = stripTerminalCruft(await ask(`${question} [${hint}]: `)).trim().toLowerCase()
-	if (answer === '') {
-		return defaultYes
-	}
-	return answer === 'y' || answer === 'yes'
-}
-
-/**
- * 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}`)
-	})
-	for (;;) {
-		const answer = stripTerminalCruft(await ask('    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})`)
-	}
-}
-
-/** One command's reader over a stdin nobody is typing at. */
-export interface PipedPrompt {
-	/**
-	 * Write `query`, then take the next line — from what is already buffered, or from what arrives.
-	 * `label` names the question in a failure; `secret()` needs it because its own query is empty.
-	 */
-	ask(query: string, label?: string): Promise<string>
-}
-
-/**
- * A reader that OWNS the stream for the whole command, so several answers piped at once survive.
- *
- * The interface stays open, and every line it emits is queued whether or not a question is waiting for
- * it — that queue is the fix. It idles paused between questions so a finished command still exits, and
- * a stream that ends or faults raises instead of hanging forever on a question nothing will answer.
- *
- * Exported for tests, which drive it over an in-memory stream; the CLI has exactly one, over stdin.
- */
-export const pipedPrompt = (input: Readable, output: Writable): PipedPrompt => {
-	const rl = createInterface({ input, output, terminal: false })
-	const buffered: string[] = []
-	let waiting: (() => void) | undefined
-	let delivered: string | undefined
-	let ended = false
-	let failure: Error | undefined
-	const settle = (line: string | undefined): void => {
-		const pending = waiting
-		waiting = undefined
-		delivered = line
-		pending?.()
-	}
-	rl.on('line', (line: string) => {
-		if (waiting === undefined) {
-			buffered.push(line)
-			return
-		}
-		rl.pause()
-		settle(line)
-	})
-	rl.on('close', () => {
-		ended = true
-		settle(undefined)
-	})
-	// A read fault (EIO on a closed pty, a broken pipe) settles the pending question too. Without this
-	// the promise nothing will ever resolve is the whole command's last act. BOTH objects are listened
-	// to: readline re-emits the input's error, and an `error` nobody listens for on the interface is an
-	// uncaught exception rather than a failed prompt.
-	const faulted = (error: Error): void => {
-		if (failure !== undefined) {
-			return
-		}
-		ended = true
-		failure = new Error(`stdin could not be read: ${error.message}`)
-		settle(undefined)
-	}
-	rl.on('error', faulted)
-	input.on('error', faulted)
-	return {
-		ask: async (query: string, label?: string): Promise<string> => {
-			const named = label ?? query
-			const ready = buffered.shift()
-			if (ready !== undefined) {
-				output.write(query)
-				// Nothing echoes an answer that came off a pipe, so close the line here: a scripted run's
-				// transcript reads one question per line, like the terminal one it stands in for.
-				output.write('\n')
-				return ready
-			}
-			if (ended) {
-				throw failure ?? unanswered(named)
-			}
-			if (waiting !== undefined) {
-				// One stream, one queue, one reader: two overlapping questions would race for the same line.
-				throw new Error('pipedPrompt: a question is already waiting')
-			}
-			rl.setPrompt(query)
-			rl.prompt()
-			await new Promise<void>((resolve) => {
-				waiting = resolve
-			})
-			const line = delivered
-			delivered = undefined
-			if (line === undefined) {
-				throw failure ?? unanswered(named)
-			}
-			output.write('\n')
-			return line
-		},
-	}
-}
-
-const unanswered = (label: string): Error => {
-	const prompt = label.trim().replace(/:$/, '')
-	return new Error(
-		`stdin ended before ${prompt === '' ? 'a prompt' : `\`${prompt}\``} was answered — a piped run must supply one line per question`,
-	)
-}
-
-/** The one piped reader this command has. Created on the first question, never closed by hand. */
-let piped: PipedPrompt | undefined
-
-/** Ask one question, on whichever stdin this command was given. `label` names it in a failure. */
-async function ask(query: string, label?: string): Promise<string> {
-	if (process.stdin.isTTY === true) {
-		const rl: Interface = createInterface({ input: process.stdin, output: process.stdout, terminal: true })
-		try {
-			return await rl.question(query)
-		} finally {
-			rl.close()
-		}
+async function ask(query: string): Promise<string> {
+	if (process.stdin.isTTY !== true) {
+		throw new Error('a confirmation needs a terminal; pass --yes to answer every confirmation unattended')
 	}
-	piped ??= pipedPrompt(process.stdin, process.stdout)
-	return piped.ask(query, label)
-}
-
-/**
- * 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
-		},
+	const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true })
+	try {
+		return await rl.question(query)
+	} finally {
+		rl.close()
 	}
 }

package/src/shell.ts

@@ -22,9 +22,7 @@ export interface ShellStep {
  * What a streaming child gets on stdin.
  *
  * A TTY child may INHERIT it — `git` and `gh` prompt on their own, and a terminal is shared by turns.
- * A piped stdin may not: `prompt.ts` gives one reader the whole stream for the command's life, and a
- * child inheriting it between two questions consumes the answers nobody has read yet, so the next
- * prompt dies on a line the child ate. `capture` has always used `'ignore'` for the same reason.
+ * Without a terminal nobody can answer a child's question, so it gets none and fails instead of waiting.
  */
 export const childStdin = (step: ShellStep, isTty: boolean = process.stdin.isTTY === true): Uint8Array | 'inherit' | 'ignore' =>
 	step.stdin !== undefined ? new TextEncoder().encode(step.stdin) : isTty ? 'inherit' : 'ignore'

package/src/github-app-manifest.ts

@@ -1,196 +0,0 @@
-import {
-	buildGitHubAppManifest,
-	type CreatedGitHubApp,
-	exchangeGitHubAppManifestCode as exchangeSharedGitHubAppManifestCode,
-	type GitHubAppFetch,
-	type GitHubAppManifestInput,
-} from '@fabrika/github-app'
-import { randomBytes } from 'node:crypto'
-import { action, detail, info, ok, url } from './log'
-
-export { buildGitHubAppManifest }
-export type { CreatedGitHubApp, GitHubAppManifestInput }
-export type GitHubAppManifestFetch = GitHubAppFetch
-
-export interface GitHubAppManifestRuntime {
-	readonly fetch?: GitHubAppManifestFetch
-	readonly callbackTimeoutMs?: number
-	readonly persistenceTimeoutMs?: number
-	/** Receives the loopback entry point after the server starts. Useful to launch or test the browser handoff. */
-	readonly onLocalUrl?: (localUrl: string) => void
-	/** Persist the one-time credentials before the browser or caller is told creation succeeded. */
-	readonly onCreated?: (app: CreatedGitHubApp, signal: AbortSignal) => Promise<void>
-}
-
-const DEFAULT_CALLBACK_TIMEOUT_MS = 5 * 60 * 1000
-const MAX_CALLBACK_TIMEOUT_MS = 60 * 60 * 1000
-const DEFAULT_PERSISTENCE_TIMEOUT_MS = 30 * 1000
-const MAX_PERSISTENCE_TIMEOUT_MS = 5 * 60 * 1000
-const APP_SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,98}[a-z0-9])?$/
-
-/** Backward-compatible positional wrapper around the runtime-neutral GitHub App exchange. */
-export const exchangeGitHubAppManifestCode = (
-	code: string,
-	fetchImplementation?: GitHubAppManifestFetch,
-	timeoutMs?: number,
-): Promise<CreatedGitHubApp> =>
-	exchangeSharedGitHubAppManifestCode(code, {
-		...(fetchImplementation === undefined ? {} : { fetch: fetchImplementation }),
-		...(timeoutMs === undefined ? {} : { timeoutMs }),
-	})
-
-const persistCreatedApp = async (
-	app: CreatedGitHubApp,
-	onCreated: GitHubAppManifestRuntime['onCreated'],
-	timeoutMs: number,
-): Promise<void> => {
-	if (onCreated === undefined) return
-	const controller = new AbortController()
-	let rejectTimeout: (error: Error) => void
-	const timeout = new Promise<never>((_resolve, reject) => {
-		rejectTimeout = reject
-	})
-	const timer = setTimeout(() => {
-		rejectTimeout(new Error('GitHub App credential persistence timed out'))
-		controller.abort()
-	}, timeoutMs)
-	try {
-		await Promise.race([onCreated(app, controller.signal), timeout])
-		if (controller.signal.aborted) throw new Error('GitHub App credential persistence timed out')
-	} catch {
-		throw new Error('GitHub App credential persistence failed')
-	} finally {
-		clearTimeout(timer)
-	}
-}
-
-/** Run GitHub's browser manifest handshake on a loopback-only callback server. */
-export async function createGitHubAppViaManifest(
-	input: GitHubAppManifestInput,
-	runtime: GitHubAppManifestRuntime = {},
-): Promise<CreatedGitHubApp> {
-	const callbackTimeoutMs = runtime.callbackTimeoutMs ?? DEFAULT_CALLBACK_TIMEOUT_MS
-	if (!Number.isSafeInteger(callbackTimeoutMs) || callbackTimeoutMs <= 0 || callbackTimeoutMs > MAX_CALLBACK_TIMEOUT_MS) {
-		throw new Error('GitHub App manifest callback timeout is invalid')
-	}
-	const persistenceTimeoutMs = runtime.persistenceTimeoutMs ?? DEFAULT_PERSISTENCE_TIMEOUT_MS
-	if (!Number.isSafeInteger(persistenceTimeoutMs) || persistenceTimeoutMs <= 0 || persistenceTimeoutMs > MAX_PERSISTENCE_TIMEOUT_MS) {
-		throw new Error('GitHub App credential persistence timeout is invalid')
-	}
-	const state = randomBytes(16).toString('hex')
-	const manifest = buildGitHubAppManifest(input)
-	let resolveApp: (app: CreatedGitHubApp) => void
-	let rejectApp: (error: Error) => void
-	const appPromise = new Promise<CreatedGitHubApp>((resolve, reject) => {
-		resolveApp = resolve
-		rejectApp = reject
-	})
-	let callbackStarted = false
-	let callbackTimer: ReturnType<typeof setTimeout> | undefined
-	const server = Bun.serve({
-		hostname: '127.0.0.1',
-		port: 0,
-		fetch: () => new Response('starting', { status: 503 }),
-	})
-	const localUrl = `http://127.0.0.1:${server.port}/`
-	const fullManifest = { ...manifest, redirect_url: `${localUrl}callback` }
-	try {
-		server.reload({
-			fetch: async (request: Request): Promise<Response> => {
-				const requestUrl = new URL(request.url)
-				if (request.headers.get('host') !== `127.0.0.1:${server.port}` || requestUrl.origin !== localUrl.slice(0, -1)) {
-					return new Response('not found', { status: 404 })
-				}
-				if (request.method === 'GET' && requestUrl.pathname === '/') {
-					return new Response(renderFormPage(input.organization, fullManifest, state), {
-						headers: { 'content-type': 'text/html; charset=utf-8' },
-					})
-				}
-				if (request.method === 'GET' && requestUrl.pathname === '/callback') {
-					if (requestUrl.searchParams.get('state') !== state) {
-						return new Response(renderErrorPage(), { status: 400, headers: { 'content-type': 'text/html; charset=utf-8' } })
-					}
-					const code = requestUrl.searchParams.get('code')
-					if (callbackStarted || code === null || code === '') {
-						return new Response(renderErrorPage(), { status: 409, headers: { 'content-type': 'text/html; charset=utf-8' } })
-					}
-					callbackStarted = true
-					if (callbackTimer !== undefined) clearTimeout(callbackTimer)
-					try {
-						const app = await exchangeGitHubAppManifestCode(code, runtime.fetch)
-						await persistCreatedApp(app, runtime.onCreated, persistenceTimeoutMs)
-						resolveApp(app)
-						return new Response(renderDonePage(), { headers: { 'content-type': 'text/html; charset=utf-8' } })
-					} catch {
-						rejectApp(new Error('GitHub App manifest callback failed'))
-						return new Response(renderErrorPage(), { status: 400, headers: { 'content-type': 'text/html; charset=utf-8' } })
-					}
-				}
-				return new Response('not found', { status: 404 })
-			},
-		})
-		const timeout = new Promise<never>((_resolve, reject) => {
-			callbackTimer = setTimeout(() => reject(new Error('Timed out waiting for the GitHub App manifest callback')), callbackTimeoutMs)
-		})
-		runtime.onLocalUrl?.(localUrl)
-		action('OPERATOR ACTION — create the GitHub App', [
-			`1. Open: ${url(localUrl)}`,
-			'2. Review the preconfigured GitHub App and click Create GitHub App.',
-			'3. Return here after GitHub redirects the browser back to this machine.',
-		])
-		info('Waiting for the GitHub App manifest callback…')
-		const app = await Promise.race([appPromise, timeout])
-		ok(`GitHub App created: ${app.slug} (id ${app.id})`)
-		detail(`App settings: ${app.htmlUrl}`)
-		// Let Bun flush the callback page before the loopback server disappears.
-		await Bun.sleep(25)
-		return app
-	} catch (error) {
-		// The callback failure page needs the same flush window as the success page.
-		await Bun.sleep(25)
-		throw error
-	} finally {
-		if (callbackTimer !== undefined) clearTimeout(callbackTimer)
-		server.stop(true)
-	}
-}
-
-export const githubAppInstallationUrl = (slug: string): string => {
-	if (!APP_SLUG_PATTERN.test(slug)) throw new Error('GitHub App slug is invalid')
-	return `https://github.com/apps/${slug}/installations/new`
-}
-
-const renderFormPage = (organization: string, manifest: Readonly<Record<string, unknown>>, state: string): string => {
-	const githubUrl = `https://github.com/organizations/${encodeURIComponent(organization)}/settings/apps/new?state=${encodeURIComponent(state)}`
-	const manifestJson = htmlEscape(JSON.stringify(manifest))
-	return `<!doctype html>
-<html><head><meta charset="utf-8"><title>Create Fabrika GitHub App</title></head>
-<body style="font-family: system-ui; max-width: 40rem; margin: 4rem auto; text-align: center;">
-	<h1>Creating the Fabrika GitHub App…</h1>
-	<p>Submitting the manifest to GitHub. If nothing happens, click the button below.</p>
-	<form id="manifest-form" method="post" action="${htmlEscape(githubUrl)}">
-		<input type="hidden" name="manifest" value="${manifestJson}">
-		<button type="submit">Continue to GitHub</button>
-	</form>
-	<script>document.getElementById('manifest-form').submit()</script>
-</body></html>`
-}
-
-const renderDonePage = (): string =>
-	`<!doctype html>
-<html><head><meta charset="utf-8"><title>Done</title></head>
-<body style="font-family: system-ui; max-width: 40rem; margin: 4rem auto; text-align: center;">
-	<h1>&#10003; GitHub App created</h1>
-	<p>Return to your terminal to install the App on the selected repositories.</p>
-</body></html>`
-
-const renderErrorPage = (): string =>
-	`<!doctype html>
-<html><head><meta charset="utf-8"><title>Error</title></head>
-<body style="font-family: system-ui; max-width: 40rem; margin: 4rem auto; text-align: center;">
-	<h1>&#10007; GitHub App setup failed</h1>
-	<p>Return to your terminal for a detail-free error.</p>
-</body></html>`
-
-const htmlEscape = (value: string): string =>
-	value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&#39;')