@nairon-ai/aegis 0.2.0 → 0.4.0

package/src/cli/commands/init.ts

@@ -57,9 +57,9 @@ This directory configures Aegis for this repository.
 ## First Run
 
 \`\`\`bash
-npx @nairon-ai/aegis setup
-npx @nairon-ai/aegis pickup --dry-run
-npx @nairon-ai/aegis deploy
+npx --yes @nairon-ai/aegis@latest setup
+npx --yes @nairon-ai/aegis@latest pickup --dry-run
+npx --yes @nairon-ai/aegis@latest deploy
 \`\`\`
 
 For the first test, use:
@@ -86,6 +86,14 @@ Telegram: https://YOUR_WORKER.workers.dev/webhook/telegram
 \`\`\`
 
 Keep \`.aegis/.env\` out of git.
+
+## Disconnect
+
+\`\`\`bash
+npx --yes @nairon-ai/aegis@latest disconnect
+\`\`\`
+
+This prints the checklist for removing the Worker, GitHub access, webhooks, and local config.
 `;
 
 export const initCommand = defineCommand({
@@ -102,11 +110,12 @@ export function runInit(): void {
 	writeIfMissing(resolve(PROJECT_AEGIS_DIR, "README.md"), README);
 	consola.success("Created .aegis/");
 	consola.log("\nNext:");
-	consola.log("  1. npx @nairon-ai/aegis setup");
+	consola.log("  1. npx --yes @nairon-ai/aegis@latest setup");
 	consola.log("  2. create GitHub labels: bug, ready to implement");
 	consola.log("  3. create a tiny test bug issue");
-	consola.log("  4. npx @nairon-ai/aegis pickup --dry-run");
-	consola.log("  5. npx @nairon-ai/aegis deploy");
+	consola.log("  4. npx --yes @nairon-ai/aegis@latest pickup --dry-run");
+	consola.log("  5. npx --yes @nairon-ai/aegis@latest deploy");
+	consola.log("  Later: npx --yes @nairon-ai/aegis@latest disconnect");
 	consola.log("");
 }
 

package/src/cli/commands/setup.ts

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import { defineCommand } from "citty";
 import { consola } from "consola";
 import type { AegisCliConfig } from "../../shared/types.js";
+import { runGitHubAppFlow } from "../github-app-flow.js";
 import { resolveEnvFileForWrite } from "../paths.js";
 import { detectSetupState, printState, saveConfig } from "../state.js";
 
@@ -32,63 +33,101 @@ export async function runSetupWizard(): Promise<void> {
 	consola.log("\nNext:");
 	consola.log("  1. Create labels in the monitored repo: bug, ready to implement");
 	consola.log("  2. Create a test GitHub issue with both labels");
-	consola.log("  3. npx @nairon-ai/aegis pickup --dry-run");
-	consola.log("  4. npx @nairon-ai/aegis deploy");
+	consola.log("  3. npx --yes @nairon-ai/aegis@latest pickup --dry-run");
+	consola.log("  4. npx --yes @nairon-ai/aegis@latest deploy");
 	consola.log("  5. Add GitHub/Linear/Telegram webhook URLs after deploy");
+	consola.log("  Later: npx --yes @nairon-ai/aegis@latest disconnect");
 	consola.log("");
 }
 
 async function setupRepo(config: AegisCliConfig): Promise<void> {
-	config.monitoredRepo = await promptText(
-		"GitHub repo to monitor (owner/repo):",
-		config.monitoredRepo,
+	printStep("Step 1: choose the GitHub repo Aegis should fix", [
+		"This is your product repo, not the Aegis repo.",
+		"Paste the GitHub URL from your browser, or type owner/repo.",
+		"Example: https://github.com/KeyLead-Team/keylead",
+	]);
+	config.monitoredRepo = normalizeGitHubRepo(
+		await promptText("Repo to monitor:", config.monitoredRepo),
 	);
-	config.baseBranch = await promptText("Base branch:", config.baseBranch ?? "main");
+
+	printStep("Step 2: choose the base branch", [
+		"This is the branch Aegis will open PRs against.",
+		"Most repos use main. If your repo uses master, develop, or staging, enter that.",
+	]);
+	config.baseBranch = await promptText("Base branch:", config.baseBranch ?? detectCurrentBranch());
 }
 
 async function setupGitHub(config: AegisCliConfig): Promise<void> {
-	consola.log("\nGitHub access");
-	consola.info(
-		"For the first test, a fine-grained token is fastest. For shared/team use, use a GitHub App.",
-	);
+	printStep("Step 3: give Aegis GitHub access", [
+		"Aegis needs permission to read issues, create branches, push fixes, and open PRs.",
+		"If you are unsure, choose the one-click GitHub App. It opens GitHub in your browser and avoids manual tokens.",
+		"Use a GitHub token only if you already know how to create fine-grained tokens.",
+	]);
 	const method = (await consola.prompt("Auth method:", {
 		type: "select",
 		options: [
-			{ label: "GitHub App (recommended)", value: "app" },
-			{ label: "GitHub token (simpler local testing)", value: "token" },
+			{ label: "One-click GitHub App (recommended)", value: "app-flow" },
+			{ label: "GitHub token (quick local test)", value: "token" },
+			{ label: "Paste existing GitHub App credentials", value: "app-manual" },
 		],
 	})) as string;
 
 	if (method === "token") {
-		config.githubToken = await promptText(
-			"GitHub token with contents/issues/PR read-write access:",
-			config.githubToken,
-		);
-	} else {
-		config.githubAppId = await promptText("GitHub App ID:", config.githubAppId);
-		const keyPath = await promptText("Path to GitHub App private key .pem:", undefined);
-		if (keyPath) {
-			const resolved = resolve(keyPath.replace(/^~/, process.env.HOME ?? "~"));
-			if (existsSync(resolved)) {
-				config.githubAppPrivateKey = Buffer.from(readFileSync(resolved, "utf-8")).toString(
-					"base64",
-				);
-				consola.success("Loaded private key");
-			} else {
-				consola.warn(`File not found: ${resolved}`);
-			}
+		printStep("Create a fine-grained GitHub token", [
+			"Open: https://github.com/settings/personal-access-tokens/new",
+			"Token name: Aegis",
+			"Repository access: Only select repositories, then choose the repo from Step 1.",
+			"Repository permissions: Contents read/write, Issues read/write, Pull requests read/write.",
+			"Metadata stays read-only automatically.",
+			"Click Generate token, then paste the token here. It usually starts with github_pat_.",
+			"Keep it secret. Aegis saves it to .aegis/.env, which should not be committed.",
+		]);
+		config.githubToken = await promptText("Paste GitHub token:", config.githubToken);
+		config.githubAppId = undefined;
+		config.githubAppPrivateKey = undefined;
+		config.githubInstallationId = undefined;
+	} else if (method === "app-flow") {
+		if (!config.monitoredRepo) {
+			consola.warn("Set the monitored repo first.");
+			return;
 		}
-		if (!config.githubAppPrivateKey) {
-			config.githubAppPrivateKey = Buffer.from(
-				await promptText("Paste GitHub App private key PEM:", config.githubAppPrivateKey),
-			).toString("base64");
+		printStep("Create the GitHub App in your browser", [
+			"Aegis will open a local setup page.",
+			"Click Create GitHub App.",
+			"Then click Install and choose Only select repositories.",
+			"Select the repo from Step 1, then approve the install.",
+			"When GitHub sends you back, this CLI saves the credentials automatically.",
+		]);
+		try {
+			const app = await runGitHubAppFlow({
+				monitoredRepo: config.monitoredRepo,
+				workerUrl: config.workerUrl,
+			});
+			config.githubAppId = app.appId;
+			config.githubAppPrivateKey = Buffer.from(app.privateKey, "utf-8").toString("base64");
+			config.githubInstallationId = app.installationId;
+			config.githubWebhookSecret = app.webhookSecret;
+			config.githubToken = undefined;
+			consola.success("Saved GitHub App credentials from GitHub.");
+		} catch (error) {
+			consola.warn(error instanceof Error ? error.message : String(error));
+			consola.info("Falling back to manual GitHub App credentials.");
+			await setupGitHubAppManual(config);
 		}
-		config.githubInstallationId = await promptText(
-			"GitHub App installation ID:",
-			config.githubInstallationId,
-		);
+	} else {
+		await setupGitHubAppManual(config);
+	}
+
+	if (config.githubWebhookSecret) {
+		consola.info("GitHub webhook secret is already configured.");
+		return;
 	}
 
+	printStep("GitHub webhook secret", [
+		"This protects webhook calls from GitHub after you deploy.",
+		"Choose yes and Aegis will generate a random secret for you.",
+		"You do not need to remember it; it is saved in .aegis/.env.",
+	]);
 	const generateSecret = (await consola.prompt("Generate a GitHub webhook secret?", {
 		type: "confirm",
 		initial: !config.githubWebhookSecret,
@@ -101,14 +140,56 @@ async function setupGitHub(config: AegisCliConfig): Promise<void> {
 	}
 }
 
+async function setupGitHubAppManual(config: AegisCliConfig): Promise<void> {
+	printStep("Paste existing GitHub App credentials", [
+		"Use this only if you already created a GitHub App manually.",
+		"You need the App ID, the private key .pem file, and the installation ID.",
+		"If that sounds unfamiliar, cancel and rerun setup with the one-click GitHub App option.",
+	]);
+	config.githubAppId = await promptText("GitHub App ID:", config.githubAppId);
+	const keyPath = await promptText("Path to GitHub App private key .pem:", undefined);
+	if (keyPath) {
+		const resolved = resolve(keyPath.replace(/^~/, process.env.HOME ?? "~"));
+		if (existsSync(resolved)) {
+			config.githubAppPrivateKey = Buffer.from(readFileSync(resolved, "utf-8")).toString("base64");
+			consola.success("Loaded private key");
+		} else {
+			consola.warn(`File not found: ${resolved}`);
+		}
+	}
+	if (!config.githubAppPrivateKey) {
+		config.githubAppPrivateKey = Buffer.from(
+			await promptText("Paste GitHub App private key PEM:", config.githubAppPrivateKey),
+		).toString("base64");
+	}
+	config.githubInstallationId = await promptText(
+		"GitHub App installation ID:",
+		config.githubInstallationId,
+	);
+	config.githubToken = undefined;
+}
+
 async function setupLinear(config: AegisCliConfig): Promise<void> {
+	printStep("Step 4: optional Linear connection", [
+		"Use this only if your team tracks bugs in Linear.",
+		"If you only use GitHub Issues, choose no.",
+		"You can rerun setup later to add Linear.",
+	]);
 	const enable = (await consola.prompt("Connect Linear too?", {
 		type: "confirm",
 		initial: Boolean(config.linearApiKey),
 	})) as boolean;
 	if (!enable) return;
 
+	printStep("Linear API key", [
+		"Open Linear settings, create a personal API key, then paste it here.",
+		"Aegis uses it to read ready bug tickets and comment with status updates.",
+	]);
 	config.linearApiKey = await promptText("Linear API key:", config.linearApiKey);
+	printStep("Linear webhook secret", [
+		"This protects Linear webhook calls after deploy.",
+		"Choose yes and Aegis will generate one.",
+	]);
 	const generateSecret = (await consola.prompt("Generate a Linear webhook signing secret?", {
 		type: "confirm",
 		initial: !config.linearWebhookSecret,
@@ -116,11 +197,19 @@ async function setupLinear(config: AegisCliConfig): Promise<void> {
 	config.linearWebhookSecret = generateSecret
 		? crypto.randomUUID()
 		: await promptText("Linear webhook signing secret:", config.linearWebhookSecret);
+	printStep("Linear team/project", [
+		"Team ID is required so Aegis knows which Linear team to watch.",
+		"Project ID is optional. Leave it blank to watch the whole team.",
+	]);
 	config.linearTeamId = await promptText("Linear team ID:", config.linearTeamId);
 	config.linearProjectId = await promptText(
 		"Linear project ID (optional):",
 		config.linearProjectId,
 	);
+	printStep("Linear statuses and labels", [
+		"These names must match your Linear workflow.",
+		"If your team uses the default names, press Enter through these prompts.",
+	]);
 	config.linearReadyStatus = await promptText(
 		"Linear ready status name:",
 		config.linearReadyStatus ?? "Ready to Implement",
@@ -141,11 +230,21 @@ async function setupLinear(config: AegisCliConfig): Promise<void> {
 }
 
 async function setupAutomation(config: AegisCliConfig): Promise<void> {
+	printStep("Step 5: GitHub labels Aegis should watch", [
+		"Aegis only picks up open issues with both labels.",
+		"Default labels are bug and ready to implement.",
+		"Create these labels in GitHub after setup if they do not exist yet.",
+	]);
 	config.readyLabel = await promptText(
 		"GitHub ready label:",
 		config.readyLabel ?? "ready to implement",
 	);
 	config.bugLabel = await promptText("GitHub bug label:", config.bugLabel ?? "bug");
+	printStep("Step 6: automation mode", [
+		"Choose plan-first for the first real use.",
+		"Plan-first means Aegis investigates and asks for approval before changing code.",
+		"Auto-low-risk is for later, after you trust the workflow.",
+	]);
 	config.automationMode = (await consola.prompt("Automation mode:", {
 		type: "select",
 		options: [
@@ -154,14 +253,25 @@ async function setupAutomation(config: AegisCliConfig): Promise<void> {
 		],
 		initial: config.automationMode ?? "plan-first",
 	})) as AegisCliConfig["automationMode"];
+	printStep("Step 7: AI model", [
+		"Use the default unless you know you want a different Flue-supported model.",
+		"You also need the matching provider API key.",
+	]);
 	config.agentModel = await promptText("Flue model:", config.agentModel ?? "openai/gpt-5.1");
-	config.openaiApiKey = await promptText(
-		"OpenAI API key (if using an OpenAI model):",
-		config.openaiApiKey,
-	);
+	printStep("OpenAI API key", [
+		"Paste your OpenAI API key if using an openai/... model.",
+		"It is stored in .aegis/.env and later copied to Cloudflare secrets during deploy.",
+		"Leave blank only if you configured a different model provider yourself.",
+	]);
+	config.openaiApiKey = await promptText("OpenAI API key:", config.openaiApiKey);
 }
 
 async function setupProductionContext(config: AegisCliConfig): Promise<void> {
+	printStep("Step 8: production context", [
+		"Start with Minimal. It uses only issue text and repo code.",
+		"Production context lets Aegis inspect read-only database data and Vercel logs.",
+		"Do not choose Production until the basic dry-run works.",
+	]);
 	const profile = (await consola.prompt("Context profile:", {
 		type: "select",
 		options: [
@@ -173,7 +283,10 @@ async function setupProductionContext(config: AegisCliConfig): Promise<void> {
 	config.contextProfile = profile;
 	if (profile !== "production") return;
 
-	consola.warn("Use a read-only DB user or replica. Do not give Aegis write access.");
+	printStep("Production context details", [
+		"Use a read-only DB user or read replica. Do not give Aegis write access.",
+		"All fields here are optional. Leave unknown fields blank.",
+	]);
 	config.databaseUrl = await promptText("Read-only DATABASE_URL (optional):", config.databaseUrl);
 	config.vercelToken = await promptText("Vercel API token (optional):", config.vercelToken);
 	config.vercelProjectId = await promptText(
@@ -184,14 +297,27 @@ async function setupProductionContext(config: AegisCliConfig): Promise<void> {
 }
 
 async function setupTelegram(config: AegisCliConfig): Promise<void> {
+	printStep("Step 9: optional Telegram approval pings", [
+		"Use this if you want Aegis to message you when it needs approval.",
+		"For the first local dry-run, choose no.",
+		"You can rerun setup later to add Telegram.",
+	]);
 	const enable = (await consola.prompt("Enable Telegram approval pings?", {
 		type: "confirm",
 		initial: Boolean(config.telegramBotToken),
 	})) as boolean;
 	if (!enable) return;
 
+	printStep("Telegram bot", [
+		"Create a bot with BotFather, paste the bot token, then paste your chat ID.",
+		"Aegis will send short approval summaries to that chat.",
+	]);
 	config.telegramBotToken = await promptText("Telegram bot token:", config.telegramBotToken);
 	config.telegramChatId = await promptText("Telegram chat ID:", config.telegramChatId);
+	printStep("Telegram webhook secret", [
+		"This protects Telegram webhook calls after deploy.",
+		"Choose yes and Aegis will generate one.",
+	]);
 	const generateSecret = (await consola.prompt("Generate a Telegram webhook secret?", {
 		type: "confirm",
 		initial: !config.telegramWebhookSecret,
@@ -202,6 +328,11 @@ async function setupTelegram(config: AegisCliConfig): Promise<void> {
 }
 
 async function setupWorker(config: AegisCliConfig): Promise<void> {
+	printStep("Step 10: Worker URL", [
+		"Leave this blank before your first deploy.",
+		"After deploy, Aegis saves the Worker URL automatically.",
+		"If you are rerunning setup after deploy, paste the workers.dev URL here.",
+	]);
 	config.workerUrl = await promptText(
 		"Deployed Worker URL (can fill after first deploy):",
 		config.workerUrl,
@@ -215,3 +346,35 @@ async function promptText(message: string, initial: string | undefined): Promise
 	})) as string;
 	return value?.trim() ?? "";
 }
+
+function normalizeGitHubRepo(input: string): string {
+	const value = input
+		.trim()
+		.replace(/\.git$/, "")
+		.replace(/\/$/, "");
+	const urlMatch = value.match(/github\.com[:/]([^/\s]+)\/([^/\s]+)$/i);
+	if (urlMatch) return `${urlMatch[1]}/${urlMatch[2]}`;
+	const shorthandMatch = value.match(/^([^/\s]+)\/([^/\s]+)$/);
+	if (shorthandMatch) return `${shorthandMatch[1]}/${shorthandMatch[2]}`;
+	return value;
+}
+
+function detectCurrentBranch(): string {
+	try {
+		const branch = readFileSync(".git/HEAD", "utf-8").trim();
+		if (branch.startsWith("ref: refs/heads/")) {
+			return branch.replace("ref: refs/heads/", "");
+		}
+	} catch {
+		// Ignore and fall back to the normal default.
+	}
+	return "main";
+}
+
+function printStep(title: string, lines: string[]): void {
+	consola.log(`\n${title}`);
+	for (const line of lines) {
+		consola.log(`  - ${line}`);
+	}
+	consola.log("");
+}

package/src/cli/github-app-flow.ts

@@ -0,0 +1,248 @@
+import { spawn } from "node:child_process";
+import { randomBytes, randomUUID } from "node:crypto";
+import { type ServerResponse, createServer } from "node:http";
+import { consola } from "consola";
+import {
+	type ManifestResult,
+	exchangeManifestCode,
+	generateManifest,
+	getManifestCreationUrl,
+} from "../github/manifest.js";
+
+export type GitHubAppFlowResult = ManifestResult & {
+	installationId: string;
+};
+
+type OwnerType = "Organization" | "User";
+
+export async function runGitHubAppFlow(options: {
+	monitoredRepo: string;
+	workerUrl?: string;
+}): Promise<GitHubAppFlowResult> {
+	const [owner, repo] = options.monitoredRepo.split("/");
+	if (!owner || !repo) {
+		throw new Error("GitHub App setup needs MONITORED_REPO in owner/repo format.");
+	}
+
+	const ownerType = await detectOwnerType(owner);
+	const state = randomUUID();
+	const appName = buildAppName(owner, repo);
+	let createdApp: ManifestResult | undefined;
+
+	const result = await new Promise<GitHubAppFlowResult>((resolve, reject) => {
+		const server = createServer(async (request, response) => {
+			try {
+				const host = request.headers.host;
+				if (!host) {
+					writeText(response, 400, "Missing Host header.");
+					return;
+				}
+				const currentUrl = new URL(request.url ?? "/", `http://${host}`);
+				const baseUrl = `http://${host}`;
+
+				if (currentUrl.pathname === "/") {
+					const manifest = generateManifest({
+						appName,
+						redirectUrl: `${baseUrl}/callback`,
+						setupUrl: `${baseUrl}/installed`,
+						webhookUrl: options.workerUrl
+							? `${options.workerUrl.replace(/\/$/, "")}/webhook/github`
+							: "https://example.com/aegis/webhook/github",
+						webhookActive: Boolean(options.workerUrl),
+					});
+					writeHtml(
+						response,
+						renderManifestForm({
+							actionUrl: getManifestCreationUrl(
+								ownerType === "Organization" ? owner : undefined,
+								state,
+							),
+							manifest,
+							owner,
+							repo,
+							appName,
+							webhookActive: Boolean(options.workerUrl),
+						}),
+					);
+					return;
+				}
+
+				if (currentUrl.pathname === "/callback") {
+					if (currentUrl.searchParams.get("state") !== state) {
+						writeText(response, 400, "State mismatch. Close this tab and rerun aegis setup.");
+						return;
+					}
+					const code = currentUrl.searchParams.get("code");
+					if (!code) {
+						writeText(response, 400, "Missing GitHub manifest code.");
+						return;
+					}
+					createdApp = await exchangeManifestCode(code);
+					const installUrl = `${createdApp.htmlUrl}/installations/new`;
+					consola.success(`Created GitHub App: ${createdApp.appName}`);
+					consola.info(`Install it on ${options.monitoredRepo}: ${installUrl}`);
+					writeHtml(response, renderInstallPage(installUrl, options.monitoredRepo));
+					return;
+				}
+
+				if (currentUrl.pathname === "/installed") {
+					const installationId = currentUrl.searchParams.get("installation_id");
+					if (!installationId || !createdApp) {
+						writeText(
+							response,
+							400,
+							"Install callback was missing installation_id. Copy the installation ID from the GitHub URL and rerun setup.",
+						);
+						return;
+					}
+					writeHtml(response, renderDonePage());
+					resolve({ ...createdApp, installationId });
+					setTimeout(() => server.close(), 250);
+					return;
+				}
+
+				writeText(response, 404, "Not found.");
+			} catch (error) {
+				reject(error);
+				writeText(response, 500, error instanceof Error ? error.message : String(error));
+				setTimeout(() => server.close(), 250);
+			}
+		});
+
+		server.on("error", reject);
+		server.listen(0, "127.0.0.1", () => {
+			const address = server.address();
+			if (!address || typeof address === "string") {
+				reject(new Error("Could not start local GitHub App setup server."));
+				return;
+			}
+			const url = `http://127.0.0.1:${address.port}/`;
+			consola.info("Opening GitHub App setup in your browser.");
+			consola.info("Click Create GitHub App, then Install, then select only the monitored repo.");
+			consola.info(`If the browser does not open, paste this URL:\n${url}`);
+			openBrowser(url);
+		});
+	});
+
+	return result;
+}
+
+async function detectOwnerType(owner: string): Promise<OwnerType> {
+	try {
+		const response = await fetch(`https://api.github.com/users/${owner}`, {
+			headers: {
+				Accept: "application/vnd.github+json",
+				"X-GitHub-Api-Version": "2022-11-28",
+			},
+		});
+		if (!response.ok) return "Organization";
+		const data = (await response.json()) as { type?: string };
+		return data.type === "User" ? "User" : "Organization";
+	} catch {
+		return "Organization";
+	}
+}
+
+function buildAppName(owner: string, repo: string): string {
+	const suffix = randomBytes(2).toString("hex");
+	return `aegis-${owner}-${repo}-${suffix}`
+		.toLowerCase()
+		.replace(/[^a-z0-9-]/g, "-")
+		.replace(/-+/g, "-")
+		.slice(0, 34);
+}
+
+function openBrowser(url: string): void {
+	const command =
+		process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+	const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+	const child = spawn(command, args, { detached: true, stdio: "ignore" });
+	child.unref();
+}
+
+function renderManifestForm(options: {
+	actionUrl: string;
+	manifest: Record<string, unknown>;
+	owner: string;
+	repo: string;
+	appName: string;
+	webhookActive: boolean;
+}): string {
+	return page(
+		"Create Aegis GitHub App",
+		`
+			<h1>Create Aegis GitHub App</h1>
+			<p>This will create a private GitHub App for <strong>${escapeHtml(options.owner)}/${escapeHtml(
+				options.repo,
+			)}</strong>.</p>
+			<ul>
+				<li>Permissions: contents, issues, pull requests</li>
+				<li>Events: issues, issue comments, pull requests</li>
+				<li>App name: ${escapeHtml(options.appName)}</li>
+				<li>Webhook: ${options.webhookActive ? "enabled" : "disabled until deploy"}</li>
+			</ul>
+			<form action="${escapeHtml(options.actionUrl)}" method="post">
+				<input type="hidden" name="manifest" value="${escapeHtml(JSON.stringify(options.manifest))}">
+				<button type="submit">Create GitHub App</button>
+			</form>
+		`,
+	);
+}
+
+function renderInstallPage(installUrl: string, repo: string): string {
+	return page(
+		"Install Aegis GitHub App",
+		`
+			<h1>GitHub App created</h1>
+			<p>Now install it on <strong>${escapeHtml(repo)}</strong>. Choose <strong>Only select repositories</strong> and pick that repo.</p>
+			<p><a class="button" href="${escapeHtml(installUrl)}">Install GitHub App</a></p>
+		`,
+	);
+}
+
+function renderDonePage(): string {
+	return page(
+		"Aegis GitHub App Connected",
+		`
+			<h1>Aegis is connected</h1>
+			<p>You can close this tab and return to your terminal.</p>
+		`,
+	);
+}
+
+function page(title: string, body: string): string {
+	return `<!doctype html>
+<html lang="en">
+<head>
+	<meta charset="utf-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1">
+	<title>${escapeHtml(title)}</title>
+	<style>
+		body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; max-width: 680px; margin: 64px auto; padding: 0 24px; color: #111827; line-height: 1.5; }
+		h1 { font-size: 28px; margin-bottom: 12px; }
+		button, .button { display: inline-block; border: 0; border-radius: 6px; background: #166534; color: white; padding: 10px 14px; font: inherit; text-decoration: none; cursor: pointer; }
+		ul { padding-left: 22px; }
+	</style>
+</head>
+<body>${body}</body>
+</html>`;
+}
+
+function writeHtml(response: ServerResponse, html: string): void {
+	response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+	response.end(html);
+}
+
+function writeText(response: ServerResponse, status: number, text: string): void {
+	response.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
+	response.end(text);
+}
+
+function escapeHtml(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#39;");
+}