@fabrika/installation-init 0.0.26 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/installation-init",
-	"version": "0.0.26",
+	"version": "0.3.1",
 	"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"
+		"zod": "^3.25.76",
+		"@fabrika/app": "^0.3.1",
+		"@fabrika/iam-contract": "^0.3.1"
 	}
 }

package/src/environment.ts

@@ -2,11 +2,24 @@
  * 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 { z } from 'zod'
+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 +31,130 @@ 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 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:
+ * 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 {}
+	}
+	const protection = protectionSchema.safeParse(parsed)
+	if (!protection.success) return {}
+	const merged: { reviewers?: EnvironmentReviewer[]; wait_timer?: number } = {}
+	for (const rule of protection.data.protection_rules) {
+		const timer = waitTimerSchema.safeParse(rule)
+		if (timer.success) {
+			merged.wait_timer = timer.data.wait_timer
+		}
+		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
+		}
+	}
+	return merged
 }
 
 /** Trigger the platform workflow (the real deploy runs in GitHub Actions). */

package/src/index.ts

@@ -9,25 +9,35 @@ export {
 	type IamAdminClient,
 	type IamAdminConnection,
 } from './admin'
-export { configureEnvironment, type EnvironmentConfig, 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'
+	configureEnvironment,
+	type EnvironmentConfig,
+	type EnvironmentEffects,
+	type ExistingEnvironmentProtection,
+	existingEnvironmentProtection,
+	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 {
+	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 }
+}

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;')