@ipul-labs/forge 1.13.0

package/server/forge/routes.js

@@ -0,0 +1,1012 @@
+/**
+ * server/forge/routes.js
+ *
+ * Express router for /api/forge/*.
+ *
+ * Required env vars:
+ *   FORGE_TOKEN           — dashboard password
+ *   FORGE_GITLAB_PROJECT  — GitLab project path, e.g. "ipul/web-app"
+ *   GITLAB_TOKEN          — GitLab personal access token
+ *
+ * Multi-repo support
+ * ──────────────────
+ * Every endpoint accepts an optional `repo` param (primary, where the issue
+ * lives) and `secondaryRepos` param (additional repos that can participate in
+ * a full-stack fix). `secondaryRepos` may be sent as a comma-separated string
+ * in the query string, or as a JSON array in a POST body.
+ */
+
+import { Router } from "express";
+
+import * as configStore from "./core/configStore.js";
+import { listDeployments } from "./core/k8s.js";
+import { ForgeAgent } from "./core/ForgeAgent.js";
+import { probeQuota } from "./core/quotaClient.js";
+import { validate as runValidation } from "./core/validator.js";
+import { createProvider } from "./core/providers/index.js";
+import * as jobStore from "./core/jobs.js";
+
+const router = Router();
+
+// ─── Auth middleware ──────────────────────────────────────────────────────────
+
+function requireAuth(req, res, next) {
+	const token = process.env.FORGE_TOKEN;
+
+	if (!token) {
+		return res.status(503).json({
+			error: "Forge is not configured. Set FORGE_TOKEN env var.",
+		});
+	}
+
+	const auth = req.headers.authorization ?? `Bearer ${req.query.token ?? ""}`;
+
+	if (!auth?.startsWith("Bearer ")) {
+		return res.status(401).json({ error: "Missing Authorization header." });
+	}
+
+	if (auth.slice(7) !== token) {
+		return res.status(403).json({ error: "Invalid token." });
+	}
+
+	next();
+}
+
+// ─── Error handler ────────────────────────────────────────────────────────────
+
+function handleError(res, error, operation) {
+	const msg = error?.message ?? "Unknown error";
+	console.error(`[forge] ${operation} failed:`, msg);
+	const upstream = /^(?:GitLab|GitHub) (\d{3}) on /.exec(msg);
+	const status = error?.status ?? (upstream ? Number(upstream[1]) : 500);
+	res.status(status).json({ error: msg, operation });
+}
+
+// ─── Repo helpers ─────────────────────────────────────────────────────────────
+
+function getAvailableRepos() {
+	// Precedence: persisted config → env vars → empty.
+	const fromConfig = configStore.get().repos;
+	if (fromConfig.length > 0) return fromConfig;
+
+	const raw = process.env.FORGE_REPOS ?? process.env.FORGE_GITLAB_PROJECT ?? "";
+	return raw
+		.split(",")
+		.map((s) => s.trim())
+		.filter(Boolean)
+		.map((path) => ({ id: path, label: path.split("/").pop() }));
+}
+
+function parseRepo(req) {
+	const repos = getAvailableRepos();
+	const requested = req.query.repo ?? req.body?.repo ?? null;
+	if (!requested) return repos[0]?.id ?? process.env.FORGE_GITLAB_PROJECT;
+	const match = repos.find((r) => r.id === requested);
+	return match?.id ?? repos[0]?.id ?? process.env.FORGE_GITLAB_PROJECT;
+}
+
+/**
+ * Normalises `secondaryRepos` from either a query string (comma-separated) or
+ * a JSON body array, validating each entry against the configured repo list.
+ * The primary repo is always filtered out.
+ */
+function parseSecondaryRepos(req, primary) {
+	const repos = getAvailableRepos();
+	const valid = new Set(repos.map((r) => r.id));
+
+	let raw = req.body?.secondaryRepos ?? req.query.secondaryRepos ?? null;
+	if (!raw) return [];
+
+	let list;
+	if (Array.isArray(raw)) {
+		list = raw;
+	} else if (typeof raw === "string") {
+		list = raw.split(",");
+	} else {
+		return [];
+	}
+
+	return list
+		.map((s) => (typeof s === "string" ? s.trim() : ""))
+		.filter((s) => s && s !== primary && valid.has(s));
+}
+
+// ─── Status ───────────────────────────────────────────────────────────────────
+
+const MODEL_RATES = {
+	"claude-opus-4-7":           { input: 15,   output: 75  },
+	"claude-sonnet-4-6":         { input: 3,    output: 15  },
+	"claude-haiku-4-5-20251001": { input: 0.80, output: 4   },
+};
+
+const FALLBACK_MODELS = [
+	{ id: "claude-opus-4-7",           label: "Claude Opus 4.7",   provider: "claude" },
+	{ id: "claude-sonnet-4-6",         label: "Claude Sonnet 4.6", provider: "claude" },
+	{ id: "claude-haiku-4-5-20251001", label: "Claude Haiku 4.5",  provider: "claude" },
+];
+
+async function fetchAnthropicModels() {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), 5_000);
+	try {
+		const res = await fetch("https://api.anthropic.com/v1/models?limit=100", {
+			headers: {
+				"x-api-key": process.env.ANTHROPIC_API_KEY,
+				"anthropic-version": "2023-06-01",
+			},
+			signal: controller.signal,
+		});
+		if (!res.ok) throw new Error(`Anthropic models API ${res.status}`);
+		const { data } = await res.json();
+		return data
+			.filter((m) => m.type === "model" && m.id.startsWith("claude-"))
+			.map((m) => ({
+				id: m.id,
+				label: m.display_name,
+				provider: "claude",
+				...(MODEL_RATES[m.id] ? { rates: MODEL_RATES[m.id] } : {}),
+			}));
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+
+router.get("/status", requireAuth, async (_req, res) => {
+	let models = FALLBACK_MODELS.map((m) => ({
+		...m,
+		...(MODEL_RATES[m.id] ? { rates: MODEL_RATES[m.id] } : {}),
+	}));
+
+	try {
+		if (process.env.ANTHROPIC_API_KEY) {
+			models = await fetchAnthropicModels();
+		}
+	} catch (e) {
+		console.warn("[forge] fetchAnthropicModels failed, using fallback:", e?.message);
+	}
+
+	const repos = getAvailableRepos();
+	const agents = [
+		{ id: "claude", label: "Claude", configured: true },
+		{
+			id: "openclaw",
+			label: "OpenClaw",
+			configured: Boolean(process.env.OPENCLAW_GATEWAY_URL),
+		},
+	];
+
+	res.json({
+		ok: true,
+		project: process.env.FORGE_GITLAB_PROJECT ?? null,
+		repos,
+		supportsMultiRepo: repos.length > 1,
+		hasGitlabToken: Boolean(process.env.GITLAB_TOKEN),
+		defaultModel: process.env.FORGE_MODEL ?? "claude-sonnet-4-6",
+		models,
+		agents,
+		defaultAgent: process.env.OPENCLAW_GATEWAY_URL ? "openclaw" : "claude",
+		hasApiKey: Boolean(process.env.ANTHROPIC_API_KEY),
+		// Test-deploy URL template stored in configStore.defaults — editable
+		// from Settings → Defaults. Supports "{branch}" / "{slug}" placeholders
+		// for ephemeral per-branch deploys. Empty string means "no link".
+		testDeployUrlTemplate: configStore.get().defaults?.testDeployUrlTemplate || null,
+	});
+});
+
+router.use(requireAuth);
+
+// ─── Config ───────────────────────────────────────────────────────────────────
+
+router.get("/config", (_req, res) => {
+	res.json(configStore.getPublic());
+});
+
+router.put("/config", async (req, res) => {
+	try {
+		await configStore.patch(req.body ?? {});
+		res.json(configStore.getPublic());
+	} catch (err) {
+		handleError(res, err, "updating config");
+	}
+});
+
+// ─── Issues ───────────────────────────────────────────────────────────────────
+
+router.get("/issues", async (req, res) => {
+	try {
+		const provider = createProvider(parseRepo(req));
+		const [issues, forgeBranches, mergedLinks] = await Promise.all([
+			provider.listOpenIssues(),
+			provider.listBranchesByPrefix("forge/issue-").catch(() => []),
+			provider.listRecentMergedMRIssueLinks(50).catch(() => []),
+		]);
+		// Map issue iid → most specific forge branch name. There may be several
+		// (old analyses that never merged), so prefer one with a slug suffix.
+		const branchByIid = new Map();
+		for (const name of forgeBranches) {
+			const m = name.match(/^forge\/issue-(\d+)(?:-|$)/);
+			if (!m) continue;
+			const iid = Number(m[1]);
+			const hasSlug = name.length > `forge/issue-${iid}`.length;
+			const existing = branchByIid.get(iid);
+			if (!existing || (!/-/.test(existing.slice(`forge/issue-${iid}`.length)) && hasSlug)) {
+				branchByIid.set(iid, name);
+			}
+		}
+		// Map issue iid → most-recent merged MR that claims to close it.
+		// Primary signal: closing keywords in the MR description.
+		const fixByIid = new Map();
+		for (const link of mergedLinks) {
+			for (const iid of link.closedIssueIids) {
+				const prior = fixByIid.get(iid);
+				if (!prior || (link.mergedAt ?? "") > (prior.mergedAt ?? "")) {
+					fixByIid.set(iid, { mrIid: link.mrIid, webUrl: link.webUrl, mergedAt: link.mergedAt });
+				}
+			}
+		}
+		// Fallback signal: merged MRs whose source branch encodes the issue iid
+		// (`forge/issue-<iid>[-slug]`). Catches MRs that merged without a
+		// closing keyword in the description — e.g. manually opened MRs on a
+		// Forge branch. Only fills gaps; the keyword match above wins on
+		// conflicts since it's a stronger signal (the MR explicitly says so).
+		for (const link of mergedLinks) {
+			const m = link.sourceBranch?.match(/^forge\/issue-(\d+)(?:-|$)/);
+			if (!m) continue;
+			const iid = Number(m[1]);
+			if (fixByIid.has(iid)) continue;
+			fixByIid.set(iid, { mrIid: link.mrIid, webUrl: link.webUrl, mergedAt: link.mergedAt });
+		}
+		// Only compare branches we actually care about — issues shown in the list.
+		const compareTargets = issues
+			.map((i) => ({ iid: i.iid, branch: branchByIid.get(i.iid) }))
+			.filter((e) => e.branch);
+		const compareResults = await Promise.all(
+			compareTargets.map((e) =>
+				provider.compareRefs("main", e.branch).catch(() => null),
+			),
+		);
+		const aheadByIid = new Map();
+		compareTargets.forEach((e, idx) => {
+			aheadByIid.set(e.iid, compareResults[idx]?.aheadCount ?? null);
+		});
+		const enriched = issues.map((i) => {
+			const out = { ...i };
+			const b = branchByIid.get(i.iid);
+			if (b) {
+				out.forgeBranch = b;
+				if (aheadByIid.has(i.iid)) out.branchAhead = aheadByIid.get(i.iid);
+			}
+			const fix = fixByIid.get(i.iid);
+			if (fix) out.likelyFixedByMr = { iid: fix.mrIid, webUrl: fix.webUrl };
+			return out;
+		});
+		res.json({ issues: enriched });
+	} catch (error) {
+		handleError(res, error, "listOpenIssues");
+	}
+});
+
+router.post("/issues", async (req, res) => {
+	const { title, description = "" } = req.body;
+	if (!title?.trim()) {
+		return res.status(400).json({ error: "title is required." });
+	}
+	try {
+		const issue = await createProvider(parseRepo(req)).createIssue(title.trim(), description.trim());
+		res.json({ issue });
+	} catch (error) {
+		handleError(res, error, "createIssue");
+	}
+});
+
+router.put("/issues/:iid", async (req, res) => {
+	const { title, description = "" } = req.body;
+	if (!title?.trim()) {
+		return res.status(400).json({ error: "title is required." });
+	}
+	try {
+		const issue = await createProvider(parseRepo(req)).updateIssue(
+			Number(req.params.iid),
+			{ title: title.trim(), description: description.trim() },
+		);
+		res.json({ issue });
+	} catch (error) {
+		handleError(res, error, "updateIssue");
+	}
+});
+
+router.post("/issues/:iid/close", async (req, res) => {
+	try {
+		const iid = Number(req.params.iid);
+		const provider = createProvider(parseRepo(req));
+
+		// Refuse if there's an open Forge MR — the user should merge or close the
+		// MR first. The frontend surfaces this message verbatim.
+		const openMrs = await provider.listForgeMRsForIssue(iid).catch(() => []);
+		if (openMrs.length > 0) {
+			const mr = openMrs[0];
+			return res.status(409).json({
+				error: `Cannot close: active MR !${mr.iid} is still open. Merge or close it first.`,
+				openMr: { iid: mr.iid, web_url: mr.web_url, title: mr.title },
+			});
+		}
+
+		// Stop any ephemeral environments attached to forge branches for this
+		// issue BEFORE deleting branches — on most providers deleting the
+		// branch orphans the environment rather than tearing it down. Each
+		// stop is best-effort (already-stopped envs 4xx).
+		const branches = await provider.listBranchesByPrefix(`forge/issue-${iid}-`).catch(() => []);
+		const baseBranch = `forge/issue-${iid}`;
+		const all = [...branches, baseBranch];
+		const envs = (
+			await Promise.all(
+				all.map((b) => provider.listEnvironmentsForBranch(b).catch(() => [])),
+			)
+		).flat();
+		await Promise.all(
+			envs.map((e) => provider.stopEnvironment(e.id).catch(() => {})),
+		);
+
+		// Now delete the branches. Also best-effort.
+		await Promise.all(
+			all.map((b) => provider.deleteBranch(b).catch(() => {})),
+		);
+
+		const issue = await provider.closeIssue(iid);
+		res.json({ issue, stoppedEnvironments: envs.length });
+	} catch (error) {
+		handleError(res, error, "closeIssue");
+	}
+});
+
+router.get("/issues/:iid", async (req, res) => {
+	try {
+		const issue = await createProvider(parseRepo(req)).getIssue(Number(req.params.iid));
+		res.json({ issue });
+	} catch (error) {
+		handleError(res, error, "getIssue");
+	}
+});
+
+// ─── Open Forge MRs ───────────────────────────────────────────────────────────
+
+router.get("/mrs", async (req, res) => {
+	try {
+		const rawState = typeof req.query.state === "string" ? req.query.state : "open";
+		const state = ["open", "merged", "closed"].includes(rawState) ? rawState : "open";
+		const mrs = await createProvider(parseRepo(req)).listAllForgeMRs(state);
+		res.json({
+			mrs: mrs.map((mr) => ({
+				iid: mr.iid,
+				title: mr.title,
+				web_url: mr.web_url,
+				source_branch: mr.source_branch,
+				target_branch: mr.target_branch,
+				state: mr.state,
+				created_at: mr.created_at,
+				merged_at: mr.merged_at ?? null,
+				author: { name: mr.author?.name ?? "unknown" },
+				has_conflicts: mr.has_conflicts ?? false,
+				merge_status: mr.merge_status ?? "unchecked",
+				pipeline: mr.head_pipeline
+					? { status: mr.head_pipeline.status, web_url: mr.head_pipeline.web_url }
+					: null,
+			})),
+		});
+	} catch (error) {
+		handleError(res, error, "listAllForgeMRs");
+	}
+});
+
+// ─── MR detection ─────────────────────────────────────────────────────────────
+
+router.get("/issues/:iid/mr", async (req, res) => {
+	try {
+		const mrs = await createProvider(parseRepo(req)).listForgeMRsForIssue(Number(req.params.iid));
+		const latest = mrs[0] ?? null;
+		res.json({
+			mr: latest
+				? { iid: latest.iid, web_url: latest.web_url, title: latest.title, branchName: latest.source_branch }
+				: null,
+		});
+	} catch (error) {
+		handleError(res, error, "listForgeMRsForIssue");
+	}
+});
+
+router.get("/issues/:iid/merged-mrs", async (req, res) => {
+	try {
+		const provider = createProvider(parseRepo(req));
+		const mrs = await provider.listMergedForgeMRsForIssue(Number(req.params.iid));
+
+		// Attach the post-merge pipeline (the one that ran on the merge commit)
+		// to each MR so the UI can render pass/fail badges.
+		const enriched = await Promise.all(
+			mrs.map(async (mr) => {
+				let pipeline = null;
+				if (mr.merge_commit_sha) {
+					try {
+						const pipelines = await provider.getPipelinesBySha(mr.merge_commit_sha);
+						const latest = pipelines[0];
+						if (latest) {
+							pipeline = { id: latest.id, status: latest.status, web_url: latest.web_url };
+						}
+					} catch {
+						// Non-fatal — pipelines can 404 for older merges.
+					}
+				}
+				return {
+					iid: mr.iid,
+					web_url: mr.web_url,
+					title: mr.title,
+					merged_at: mr.merged_at,
+					branchName: mr.source_branch,
+					merge_commit_sha: mr.merge_commit_sha,
+					pipeline,
+				};
+			}),
+		);
+		res.json({ mrs: enriched });
+	} catch (error) {
+		handleError(res, error, "listMergedForgeMRsForIssue");
+	}
+});
+
+router.get("/mr/:mrIid/detail", async (req, res) => {
+	try {
+		const mr = await createProvider(parseRepo(req)).getMR(Number(req.params.mrIid));
+		res.json({
+			iid: mr.iid,
+			title: mr.title,
+			web_url: mr.web_url,
+			source_branch: mr.source_branch,
+			target_branch: mr.target_branch,
+			state: mr.state,
+			has_conflicts: mr.has_conflicts ?? false,
+			rebase_in_progress: mr.rebase_in_progress ?? false,
+			merge_status: mr.merge_status ?? "unchecked",
+			detailed_merge_status: mr.detailed_merge_status ?? null,
+			merge_when_pipeline_succeeds: mr.merge_when_pipeline_succeeds ?? false,
+			draft: mr.draft ?? false,
+		});
+	} catch (error) {
+		handleError(res, error, "getMR");
+	}
+});
+
+router.post("/mr/:mrIid/rebase", async (req, res) => {
+	try {
+		const provider = createProvider(parseRepo(req));
+		if (!provider.supportsRebase) {
+			return res.status(422).json({ error: `${provider.name} does not support server-side rebase.` });
+		}
+		await provider.rebaseMR(Number(req.params.mrIid));
+		res.json({ ok: true });
+	} catch (error) {
+		handleError(res, error, "rebaseMR");
+	}
+});
+
+router.get("/mr/:mrIid/diffs", async (req, res) => {
+	try {
+		const diffs = await createProvider(parseRepo(req)).getMRDiffs(Number(req.params.mrIid));
+		res.json({ diffs });
+	} catch (error) {
+		handleError(res, error, "getMRDiffs");
+	}
+});
+
+router.post("/mr/:mrIid/auto-merge", async (req, res) => {
+	try {
+		const provider = createProvider(parseRepo(req));
+		await provider.setAutoMergeMR(Number(req.params.mrIid));
+		res.json({ ok: true });
+	} catch (error) {
+		handleError(res, error, "setAutoMergeMR");
+	}
+});
+
+router.post("/mr/:mrIid/cancel-auto-merge", async (req, res) => {
+	try {
+		const provider = createProvider(parseRepo(req));
+		await provider.cancelAutoMergeMR(Number(req.params.mrIid));
+		res.json({ ok: true });
+	} catch (error) {
+		handleError(res, error, "cancelAutoMergeMR");
+	}
+});
+
+router.post("/mr/:mrIid/merge", async (req, res) => {
+	try {
+		const provider = createProvider(parseRepo(req));
+		await provider.mergeMR(Number(req.params.mrIid));
+		res.json({ ok: true });
+	} catch (error) {
+		handleError(res, error, "mergeMR");
+	}
+});
+
+router.post("/mr/:mrIid/close", async (req, res) => {
+	try {
+		const provider = createProvider(parseRepo(req));
+		await provider.closeMR(Number(req.params.mrIid));
+		res.json({ ok: true });
+	} catch (error) {
+		handleError(res, error, "closeMR");
+	}
+});
+
+router.post("/mr/:mrIid/reopen", async (req, res) => {
+	try {
+		const provider = createProvider(parseRepo(req));
+		await provider.reopenMR(Number(req.params.mrIid));
+		res.json({ ok: true });
+	} catch (error) {
+		handleError(res, error, "reopenMR");
+	}
+});
+
+router.post("/mr/:mrIid/draft", async (req, res) => {
+	try {
+		const draft = Boolean(req.body?.draft);
+		const provider = createProvider(parseRepo(req));
+		await provider.setMRDraft(Number(req.params.mrIid), draft);
+		res.json({ ok: true });
+	} catch (error) {
+		handleError(res, error, "setMRDraft");
+	}
+});
+
+// ─── Analysis (SSE) ───────────────────────────────────────────────────────────
+// The job is kicked off synchronously and runs to completion regardless of
+// whether a client is listening. The client opens /jobs/:jobId/stream to
+// attach (or reattach after a reload).
+
+router.post("/issues/:iid/analyze", (req, res) => {
+	const { iid } = req.params;
+	const primary = parseRepo(req);
+	const secondaryProjects = parseSecondaryRepos(req, primary);
+	const agent = new ForgeAgent({
+		project: primary,
+		secondaryProjects,
+		agent: req.body.agent || "claude",
+	});
+	const kind = ["fresh", "new", "update", "retry"].includes(req.body.kind)
+		? req.body.kind
+		: "fresh";
+
+	const jobId = jobStore.createJob("analyze", (send, signal) =>
+		agent.analyzeIssue(
+			Number(iid),
+			send,
+			req.body.model || undefined,
+			undefined,
+			req.body.prompt || undefined,
+			kind,
+			{ signal },
+		),
+	);
+	res.json({ jobId });
+});
+
+// ─── Refine ───────────────────────────────────────────────────────────────────
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+router.post("/issues/:iid/refine", (req, res) => {
+	const { iid } = req.params;
+	const { feedback, previousChanges, ciContext, validationState, claudeSessionId } = req.body;
+
+	if (!feedback?.trim() && !ciContext?.trim()) {
+		return res.status(400).json({ error: "feedback or ciContext is required." });
+	}
+	if (!Array.isArray(previousChanges)) {
+		return res.status(400).json({ error: "previousChanges must be an array." });
+	}
+
+	// Only forward a syntactically valid UUID — anything else becomes an
+	// unrecognized --resume arg that the CLI would reject with an error we'd
+	// have to parse. Safer to drop it silently and let ForgeAgent mint a fresh
+	// session (the user-visible outcome is just "no resume this turn").
+	const safeSessionId = typeof claudeSessionId === "string" && UUID_RE.test(claudeSessionId)
+		? claudeSessionId
+		: undefined;
+
+	const primary = parseRepo(req);
+	const agent = new ForgeAgent({
+		project: primary,
+		secondaryProjects: parseSecondaryRepos(req, primary),
+		agent: req.body.agent || "claude",
+	});
+
+	const jobId = jobStore.createJob("refine", (send, signal) =>
+		agent.refineIssue(
+			Number(iid),
+			previousChanges,
+			feedback?.trim() ?? "",
+			send,
+			undefined,
+			ciContext?.trim(),
+			validationState ?? null,
+			safeSessionId,
+			{ signal },
+		),
+	);
+	res.json({ jobId });
+});
+
+router.post("/issues/:iid/ci-fix", (req, res) => {
+	const { iid } = req.params;
+	const { ciContext, model } = req.body;
+
+	if (!ciContext?.trim()) {
+		return res.status(400).json({ error: "ciContext is required." });
+	}
+
+	const primary = parseRepo(req);
+	const agent = new ForgeAgent({
+		project: primary,
+		secondaryProjects: parseSecondaryRepos(req, primary),
+		agent: req.body.agent || "claude",
+	});
+
+	const jobId = jobStore.createJob("ci-fix", (send, signal) =>
+		agent.ciFixIssue(Number(iid), ciContext.trim(), send, model, { signal }),
+	);
+	res.json({ jobId });
+});
+
+router.get("/jobs/:jobId/trace", async (req, res) => {
+	try {
+		const trace = await createProvider(parseRepo(req)).getJobTrace(Number(req.params.jobId));
+		res.json({ trace });
+	} catch (error) {
+		handleError(res, error, "getJobTrace");
+	}
+});
+
+// Snapshot a job's current status — used by the client on mount to decide
+// whether to reattach (running), hydrate from localStorage (done), or clear
+// a stale sessionStorage key (404).
+router.get("/jobs/:jobId", (req, res) => {
+	const snap = jobStore.snapshot(req.params.jobId);
+	if (!snap) return res.status(404).json({ error: "Job not found." });
+	res.json(snap);
+});
+
+router.get("/jobs/:jobId/stream", (req, res) => {
+	const jobId = req.params.jobId;
+	if (!jobStore.getJob(jobId)) {
+		return res.status(404).json({ error: "Job not found." });
+	}
+
+	res.setHeader("Content-Type", "text/event-stream");
+	res.setHeader("Cache-Control", "no-cache");
+	res.setHeader("Connection", "keep-alive");
+	res.flushHeaders();
+
+	let unsubscribe = () => {};
+	const write = (event) => {
+		if (res.writableEnded) return;
+		res.write(`data: ${JSON.stringify(event)}\n\n`);
+		if (event.type === "done" || event.type === "error" || event.type === "cancelled") {
+			unsubscribe();
+			res.end();
+		}
+	};
+
+	const sub = jobStore.subscribe(jobId, write);
+	if (!sub) {
+		if (!res.writableEnded) res.end();
+		return;
+	}
+	unsubscribe = sub;
+
+	req.on("close", () => {
+		unsubscribe();
+		if (!res.writableEnded) res.end();
+	});
+});
+
+router.post("/jobs/:jobId/cancel", (req, res) => {
+	const { jobId } = req.params;
+	if (!jobStore.getJob(jobId)) {
+		return res.status(404).json({ error: "Job not found." });
+	}
+	const cancelled = jobStore.cancelJob(jobId);
+	res.json({ cancelled });
+});
+
+// ─── Apply fix ────────────────────────────────────────────────────────────────
+
+// ─── Validate ─────────────────────────────────────────────────────────────────
+// Pre-flight check: overlay the proposed changes on a cached clone of the
+// target repo, run lint/typecheck/test, and report results. Nothing is pushed
+// to GitLab — this is a sandbox check to prevent CI errors.
+
+router.post("/validate", (req, res) => {
+	const { analysis } = req.body;
+	if (!analysis?.changes?.length) {
+		return res.status(400).json({ error: "analysis with changes is required." });
+	}
+	// Take the user's *current* repo selection — analysis.repos is a stale
+	// snapshot from when the analysis ran (the user may have toggled
+	// secondaries on/off since then).
+	const primary = parseRepo(req);
+	const secondaryRepos = parseSecondaryRepos(req, primary);
+	const repos = [primary, ...secondaryRepos].filter(Boolean);
+	const enrichedAnalysis = repos.length ? { ...analysis, repos } : analysis;
+
+	const jobId = jobStore.createJob(
+		"validate",
+		(send) => runValidation(enrichedAnalysis, send),
+		{ idPrefix: "val" },
+	);
+	res.json({ jobId });
+});
+
+router.post("/apply", async (req, res) => {
+	const { analysis } = req.body;
+
+	if (!analysis?.issue || !analysis?.changes?.length) {
+		return res.status(400).json({ error: "Invalid or missing analysis payload." });
+	}
+
+	try {
+		const primary = parseRepo(req);
+		const secondaryProjects = parseSecondaryRepos(req, primary);
+		const agent = new ForgeAgent({ project: primary, secondaryProjects });
+		const result = await agent.applyFix(analysis);
+		res.json(result);
+	} catch (error) {
+		handleError(res, error, "applyFix");
+	}
+});
+
+router.post("/commit-to-branch", async (req, res) => {
+	const { branchName, analysis, repo: changeRepo } = req.body;
+
+	if (!branchName?.trim()) {
+		return res.status(400).json({ error: "branchName is required." });
+	}
+	if (!analysis?.issue || !analysis?.changes?.length) {
+		return res.status(400).json({ error: "Invalid or missing analysis payload." });
+	}
+
+	try {
+		const primary = parseRepo(req);
+		const secondaryProjects = parseSecondaryRepos(req, primary);
+		const agent = new ForgeAgent({ project: primary, secondaryProjects });
+		const targetRepo = changeRepo && [primary, ...secondaryProjects].includes(changeRepo)
+			? changeRepo
+			: primary;
+		const result = await agent.commitToBranch(branchName.trim(), analysis, targetRepo);
+		res.json(result);
+	} catch (error) {
+		handleError(res, error, "commitToBranch");
+	}
+});
+
+router.post("/promote-branch", async (req, res) => {
+	const { branchName, repo: targetRepo, issueIid } = req.body;
+
+	if (!branchName?.trim()) {
+		return res.status(400).json({ error: "branchName is required." });
+	}
+	if (!Number.isFinite(Number(issueIid))) {
+		return res.status(400).json({ error: "issueIid is required." });
+	}
+
+	try {
+		const primary = parseRepo(req);
+		const secondaryProjects = parseSecondaryRepos(req, primary);
+		const agent = new ForgeAgent({ project: primary, secondaryProjects });
+		const result = await agent.promoteBranchToMR(
+			branchName.trim(),
+			targetRepo || primary,
+			Number(issueIid),
+		);
+		res.json(result);
+	} catch (error) {
+		handleError(res, error, "promoteBranchToMR");
+	}
+});
+
+router.post("/deploy-branch", async (req, res) => {
+	const { analysis } = req.body;
+
+	if (!analysis?.issue || !analysis?.changes?.length) {
+		return res.status(400).json({ error: "Invalid or missing analysis payload." });
+	}
+
+	try {
+		const primary = parseRepo(req);
+		const secondaryProjects = parseSecondaryRepos(req, primary);
+		const agent = new ForgeAgent({ project: primary, secondaryProjects });
+		const result = await agent.deployBranch(analysis);
+		res.json(result);
+	} catch (error) {
+		handleError(res, error, "deployBranch");
+	}
+});
+
+// ─── Pipeline status ──────────────────────────────────────────────────────────
+
+router.get("/mr/:mrIid/pipeline", async (req, res) => {
+	try {
+		const provider = createProvider(parseRepo(req));
+		const pipelines = await provider.getMRPipelines(Number(req.params.mrIid));
+
+		if (!pipelines.length) {
+			return res.json({ pipeline: null, jobs: [] });
+		}
+
+		const latest = pipelines[0];
+		const [pipeline, jobs] = await Promise.all([
+			provider.getPipeline(latest.id),
+			provider.getPipelineJobs(latest.id),
+		]);
+
+		res.json({ pipeline, jobs });
+	} catch (error) {
+		handleError(res, error, "getPipelineStatus");
+	}
+});
+
+// Returns the latest branch pipeline (and its jobs) for any ref.
+// Used by Deploy-to-Test, which creates a branch with no MR, so MR-scoped
+// pipeline lookups don't apply.
+router.get("/branch-pipeline", async (req, res) => {
+	try {
+		const branch = req.query.branch;
+		if (!branch) return res.status(400).json({ error: "branch is required" });
+		const provider = createProvider(parseRepo(req));
+		const pipelines = await provider.getPipelinesByRef(branch);
+		if (!pipelines.length) return res.json({ pipeline: null, jobs: [] });
+		const [pipeline, jobs] = await Promise.all([
+			provider.getPipeline(pipelines[0].id),
+			provider.getPipelineJobs(pipelines[0].id),
+		]);
+		res.json({ pipeline, jobs });
+	} catch (error) {
+		handleError(res, error, "getBranchPipeline");
+	}
+});
+
+// Lists Forge branches for an issue that aren't yet tied to an open or merged
+// MR — i.e. Deploy-to-Test branches. Each entry carries the latest pipeline
+// summary so the UI can surface CI status without a separate round-trip.
+router.get("/issues/:iid/deploy-branches", async (req, res) => {
+	try {
+		const iid = Number(req.params.iid);
+		const provider = createProvider(parseRepo(req));
+		const [branches, openMrs, mergedMrs] = await Promise.all([
+			provider.listBranchesByPrefix(`forge/issue-${iid}-`),
+			provider.listForgeMRsForIssue(iid),
+			provider.listMergedForgeMRsForIssue(iid),
+		]);
+		const mrBranches = new Set(
+			[...openMrs, ...mergedMrs].map((m) => m.source_branch).filter(Boolean),
+		);
+		const deployOnly = branches.filter((b) => !mrBranches.has(b));
+
+		const enriched = await Promise.all(
+			deployOnly.map(async (branchName) => {
+				try {
+					const pipelines = await provider.getPipelinesByRef(branchName);
+					const latest = pipelines[0] ?? null;
+					return {
+						branchName,
+						pipeline: latest
+							? { id: latest.id, status: latest.status, web_url: latest.web_url, created_at: latest.created_at }
+							: null,
+					};
+				} catch {
+					return { branchName, pipeline: null };
+				}
+			}),
+		);
+		// Newest first — branch names end in a timestamp so lexicographic = chronological.
+		enriched.sort((a, b) => b.branchName.localeCompare(a.branchName));
+		res.json({ branches: enriched });
+	} catch (error) {
+		handleError(res, error, "listDeployBranches");
+	}
+});
+
+// Ephemeral environments (review apps) attached to any forge/issue-:iid-*
+// branch. Returns a flat list — each entry carries the branch it's tied to
+// so the UI can colocate it with its pipeline.
+router.get("/issues/:iid/environments", async (req, res) => {
+	try {
+		const iid = Number(req.params.iid);
+		const provider = createProvider(parseRepo(req));
+		const branches = await provider.listBranchesByPrefix(`forge/issue-${iid}-`).catch(() => []);
+		const all = [...branches, `forge/issue-${iid}`];
+		const envsByBranch = await Promise.all(
+			all.map(async (branch) => {
+				const envs = await provider.listEnvironmentsForBranch(branch).catch(() => []);
+				return envs.map((e) => ({ ...e, branchName: branch }));
+			}),
+		);
+		res.json({ environments: envsByBranch.flat() });
+	} catch (error) {
+		handleError(res, error, "listEnvironments");
+	}
+});
+
+router.get("/issues/:iid/post-merge-pipeline", async (req, res) => {
+	try {
+		const provider = createProvider(parseRepo(req));
+		const mrs = await provider.listMergedForgeMRsForIssue(Number(req.params.iid));
+		if (!mrs.length) return res.json({ pipeline: null, jobs: [] });
+
+		const latestMr = await provider.getMR(mrs[0].iid);
+		const sha = latestMr.merge_commit_sha;
+		if (!sha) return res.json({ pipeline: null, jobs: [] });
+
+		const pipelines = await provider.getPipelinesBySha(sha);
+		if (!pipelines.length) return res.json({ pipeline: null, jobs: [] });
+
+		const [pipeline, jobs] = await Promise.all([
+			provider.getPipeline(pipelines[0].id),
+			provider.getPipelineJobs(pipelines[0].id),
+		]);
+		res.json({ pipeline, jobs });
+	} catch (error) {
+		handleError(res, error, "getPostMergePipeline");
+	}
+});
+
+// ─── Resolution check ─────────────────────────────────────────────────────────
+
+router.post("/issues/:iid/resolution-check", async (req, res) => {
+	try {
+		const primary = parseRepo(req);
+		const secondaryProjects = parseSecondaryRepos(req, primary);
+		const provider = createProvider(primary);
+		const mrs = await provider.listMergedForgeMRsForIssue(Number(req.params.iid));
+		if (!mrs.length) {
+			return res.status(404).json({ error: "No merged MR found for this issue." });
+		}
+		const agent = new ForgeAgent({ project: primary, secondaryProjects, agent: req.body.agent || "claude" });
+		const result = await agent.checkResolution(Number(req.params.iid), mrs[0].iid, primary);
+		res.json(result);
+	} catch (error) {
+		handleError(res, error, "checkResolution");
+	}
+});
+
+// ─── Rollout status ───────────────────────────────────────────────────────────
+
+router.get("/rollout", async (_req, res) => {
+	try {
+		const deployments = await listDeployments("test");
+		res.json({ deployments });
+	} catch (error) {
+		handleError(res, error, "rollout");
+	}
+});
+
+// ─── Quota probe ──────────────────────────────────────────────────────────────
+// User-triggered: hits the Anthropic Messages API once with a 1-token request
+// just to read `anthropic-ratelimit-*` response headers. All real Forge work
+// still runs through the `claude` CLI (subscription).
+
+router.get("/quota", async (_req, res) => {
+	try {
+		const result = await probeQuota();
+		res.json(result);
+	} catch (error) {
+		// Propagate the Anthropic status code if the probe itself failed,
+		// but still return whatever rate-limit headers came back.
+		const status = error?.status ?? 500;
+		res.status(status).json({
+			error: error?.message ?? "Quota probe failed",
+			rateLimit: error?.rateLimit ?? null,
+			operation: "quota",
+		});
+	}
+});
+
+export default router;