@ipul-labs/forge 1.13.0

package/bin/cli/ship.js

@@ -0,0 +1,762 @@
+/**
+ * `forge-agent ship <iid>` — the headline command.
+ *
+ * Walks an issue from "open ticket" all the way to "deployed in production"
+ * with a yes/no Confirm gate at every state-changing step. Each phase calls
+ * the same underlying ForgeAgent / provider / validator code that the
+ * standalone subcommands use; this orchestrator just sequences them and
+ * keeps the user oriented.
+ *
+ * The flow:
+ *
+ *   start
+ *     → analyzing      (or load cached if session.phase=ANALYZED+)
+ *     → review         (render proposal)
+ *     → accept-gate    (yes / no=abort / refine=loop with feedback)
+ *     → refining       (back to review)
+ *     → validating     (auto unless --skip-validate)
+ *     → apply-gate     (yes / no=abort)
+ *     → applying
+ *     → watching-ci
+ *     → ci-failed | ci-fix-gate | ci-fixing → watching-ci
+ *     → merge-gate     (yes / no=abort; --auto arms auto-merge instead)
+ *     → merging
+ *     → watching-deploy
+ *     → close-gate     (yes / no=skip)
+ *     → closing
+ *     → done | aborted | error
+ *
+ * `--yes` (or FORGE_YES=1) bypasses every gate. Resumable: re-running
+ * `ship <iid>` reads session.phase and starts from the next gate.
+ */
+
+import path from "node:path";
+import React, { useEffect, useState } from "react";
+import Spinner from "ink-spinner";
+import TextInput from "ink-text-input";
+import { h, Box, Text, useApp, runApp, Confirm } from "./ink.js";
+import { canonicalRepoId, getFlag, projectRoot, resolveRepoSet } from "./utils.js";
+import {
+	PHASES,
+	appendEvent,
+	readAnalysis,
+	readState,
+	resolveSessionTarget,
+	setHead,
+	updateState,
+	writeAnalysis,
+} from "./sessionStore.js";
+
+const POLL_MS = 5000;
+const TERMINAL_PIPELINE = new Set([
+	"success",
+	"failed",
+	"canceled",
+	"skipped",
+	"manual",
+]);
+
+function StepLine({ status, label, detail }) {
+	let glyph;
+	let color;
+	if (status === "running") {
+		glyph = h`<${Spinner} type="dots"/>`;
+		color = "cyan";
+	} else if (status === "ok") {
+		glyph = "✓";
+		color = "green";
+	} else if (status === "fail") {
+		glyph = "✘";
+		color = "red";
+	} else if (status === "skip") {
+		glyph = "○";
+		color = "gray";
+	} else {
+		glyph = "·";
+		color = undefined;
+	}
+	return h`<${Box}>
+		<${Text} color=${color}>${typeof glyph === "string" ? glyph : glyph}</>
+		<${Text}> ${label}</>
+		${detail ? h`<${Text} dimColor>  ${detail}</>` : null}
+	</>`;
+}
+
+function FeedbackInput({ onSubmit }) {
+	const [v, setV] = useState("");
+	return h`<${Box} flexDirection="column">
+		<${Box}>
+			<${Text} color="cyan">? </>
+			<${Text}>What feedback should the model address?</>
+		</>
+		<${Box} marginLeft=${2}>
+			<${TextInput}
+				value=${v}
+				onChange=${setV}
+				onSubmit=${(text) => {
+					const t = text.trim();
+					if (!t) return;
+					onSubmit(t);
+				}} />
+		</>
+	</>`;
+}
+
+function ProposalSummary({ analysis }) {
+	const changes = analysis?.changes ?? [];
+	return h`<${Box} flexDirection="column">
+		<${Text} dimColor>${"────────── proposal ──────────"}</>
+		<${Box}><${Text} color="yellow">Issue:  </><${Text}>#${analysis.issue?.iid}: ${analysis.issue?.title ?? ""}</></>
+		${analysis.mrTitle
+			? h`<${Box}><${Text} color="yellow">MR:     </><${Text}>${analysis.mrTitle}</></>`
+			: null}
+		<${Box}><${Text} color="yellow">Changes:</><${Text}>${` ${changes.length} file(s) across ${new Set(changes.map((c) => c.repo)).size} repo(s)`}</></>
+		${changes.map((c, i) =>
+			h`<${Text} key=${i} dimColor>${`  ${c.action.padEnd(7)} ${c.repo}:${c.file}`}</>`,
+		)}
+		<${Text} dimColor>${"  (full diff: forge-agent show " + (analysis.issue?.iid ?? "") + ")"}</>
+	</>`;
+}
+
+function ShipView({ iid, primary, secondaries, bypassYes, autoMerge, skipValidate, onDone }) {
+	const { exit } = useApp();
+	const [phase, setPhase] = useState("init"); // see header for phase list
+	const [steps, setSteps] = useState([]); // visible step trace
+	const [analysis, setAnalysis] = useState(null);
+	const [sessionState, setSessionState] = useState(null);
+	const [pipeline, setPipeline] = useState(null);
+	const [jobs, setJobs] = useState([]);
+	const [error, setError] = useState(null);
+	const [feedback, setFeedback] = useState(null);
+
+	const repo = primary;
+
+	const pushStep = (label, detail) =>
+		setSteps((s) => [...s, { label, detail, status: "running" }]);
+	const finishStep = (label, status, detail) =>
+		setSteps((s) =>
+			s.map((row, i) =>
+				i === s.length - 1 && row.label === label
+					? { ...row, status, detail: detail ?? row.detail }
+					: row,
+			),
+		);
+
+	useEffect(() => {
+		if (phase === "done" || phase === "aborted" || phase === "error") {
+			onDone({ phase, error });
+			exit();
+		}
+	}, [phase]);
+
+	// === init: load or start fresh ===
+	useEffect(() => {
+		if (phase !== "init") return;
+		(async () => {
+			const state = (await readState(repo, iid).catch(() => null)) ?? null;
+			setSessionState(state);
+			const cached = await readAnalysis(repo, iid).catch(() => null);
+			if (cached && state?.phase) {
+				setAnalysis(cached);
+				// Resume at the right place. We always re-render the proposal so
+				// the user can see what's about to happen.
+				if (
+					state.phase === PHASES.ANALYZED ||
+					state.phase === PHASES.REFINED
+				) {
+					setPhase("review");
+					return;
+				}
+				if (state.phase === PHASES.VALIDATED) {
+					setPhase("review"); // still want accept gate before apply
+					return;
+				}
+				if (state.phase === PHASES.APPLIED) {
+					setPipeline(null);
+					setPhase("watching-ci");
+					return;
+				}
+				if (state.phase === PHASES.MERGED) {
+					setPhase("watching-deploy");
+					return;
+				}
+				if (state.phase === PHASES.RESOLVED) {
+					setPhase("close-gate");
+					return;
+				}
+				if (state.phase === PHASES.CLOSED) {
+					pushStep("Session already closed", undefined);
+					setPhase("done");
+					return;
+				}
+			}
+			setPhase("analyzing");
+		})();
+	}, [phase]);
+
+	// === analyzing ===
+	useEffect(() => {
+		if (phase !== "analyzing") return;
+		let cancelled = false;
+		pushStep("Analyzing issue", `#${iid}`);
+		(async () => {
+			try {
+				const { ForgeAgent } = await import(
+					path.join(projectRoot, "server/forge/core/ForgeAgent.js")
+				);
+				const agent = new ForgeAgent({
+					project: primary,
+					secondaryProjects: secondaries,
+				});
+				let final = null;
+				const events = [];
+				const onEvent = (evt) => {
+					events.push(evt);
+					if (evt.type === "result") final = evt.data;
+				};
+				await agent.analyzeIssue(iid, onEvent, undefined, undefined, undefined, "fresh");
+				if (cancelled) return;
+				if (!final) throw new Error("analyze produced no result");
+				await writeAnalysis(repo, iid, final);
+				await updateState(repo, iid, {
+					primary,
+					secondaries,
+					phase: PHASES.ANALYZED,
+					lastError: null,
+				});
+				await setHead(repo, iid);
+				for (const e of events) {
+					await appendEvent(repo, iid, e).catch(() => {});
+				}
+				setAnalysis(final);
+				finishStep("Analyzing issue", "ok", `${final.changes?.length ?? 0} change(s) proposed`);
+				setPhase("review");
+			} catch (err) {
+				if (cancelled) return;
+				finishStep("Analyzing issue", "fail", err.message ?? String(err));
+				setError(err);
+				setPhase("error");
+			}
+		})();
+		return () => {
+			cancelled = true;
+		};
+	}, [phase]);
+
+	// === refining ===
+	useEffect(() => {
+		if (phase !== "refining" || !feedback) return;
+		let cancelled = false;
+		pushStep("Refining with feedback", feedback);
+		(async () => {
+			try {
+				const { ForgeAgent } = await import(
+					path.join(projectRoot, "server/forge/core/ForgeAgent.js")
+				);
+				const agent = new ForgeAgent({
+					project: primary,
+					secondaryProjects: secondaries,
+				});
+				let final = null;
+				const onEvent = (evt) => {
+					if (evt.type === "result") final = evt.data;
+				};
+				await agent.refineIssue(
+					iid,
+					analysis.changes,
+					feedback,
+					onEvent,
+					undefined,
+				);
+				if (cancelled) return;
+				if (!final) throw new Error("refine produced no result");
+				await writeAnalysis(repo, iid, final);
+				await updateState(repo, iid, {
+					phase: PHASES.REFINED,
+					lastFeedback: feedback,
+					lastError: null,
+				});
+				setAnalysis(final);
+				setFeedback(null);
+				finishStep("Refining with feedback", "ok", `${final.changes?.length ?? 0} change(s)`);
+				setPhase("review");
+			} catch (err) {
+				if (cancelled) return;
+				finishStep("Refining with feedback", "fail", err.message ?? String(err));
+				setError(err);
+				setPhase("error");
+			}
+		})();
+		return () => {
+			cancelled = true;
+		};
+	}, [phase, feedback]);
+
+	// === validating ===
+	useEffect(() => {
+		if (phase !== "validating") return;
+		let cancelled = false;
+		pushStep("Validating proposal", "lint / typecheck / test");
+		(async () => {
+			try {
+				const { validate } = await import(
+					path.join(projectRoot, "server/forge/core/validator.js")
+				);
+				const res = await validate(analysis, () => {});
+				if (cancelled) return;
+				if (!res.allPassed) {
+					finishStep("Validating proposal", "fail", "see: forge-agent validate");
+					setError(new Error("validation failed"));
+					setPhase("error");
+					return;
+				}
+				await updateState(repo, iid, {
+					phase: PHASES.VALIDATED,
+					validation: { passed: true, checkedAt: new Date().toISOString() },
+				});
+				finishStep("Validating proposal", "ok", "all checks passed");
+				setPhase("apply-gate");
+			} catch (err) {
+				if (cancelled) return;
+				finishStep("Validating proposal", "fail", err.message ?? String(err));
+				setError(err);
+				setPhase("error");
+			}
+		})();
+		return () => {
+			cancelled = true;
+		};
+	}, [phase]);
+
+	// === applying ===
+	useEffect(() => {
+		if (phase !== "applying") return;
+		let cancelled = false;
+		pushStep("Opening MR", "branch + commit + create MR");
+		(async () => {
+			try {
+				const { ForgeAgent } = await import(
+					path.join(projectRoot, "server/forge/core/ForgeAgent.js")
+				);
+				const agent = new ForgeAgent({
+					project: primary,
+					secondaryProjects: secondaries,
+				});
+				const result = await agent.applyFix(analysis);
+				if (cancelled) return;
+				const primaryApp =
+					result.applications?.find(
+						(a) => canonicalRepoId(a.repo) === canonicalRepoId(primary),
+					) ?? result.applications?.[0];
+				await updateState(repo, iid, {
+					phase: PHASES.APPLIED,
+					branch: primaryApp?.branchName ?? null,
+					mrIid: primaryApp?.mr?.iid ?? null,
+					mrUrl: primaryApp?.mr?.web_url ?? null,
+					applications: result.applications ?? [],
+					lastError: null,
+				});
+				finishStep(
+					"Opening MR",
+					"ok",
+					primaryApp?.mr?.web_url
+						? `${primaryApp.mr.web_url}`
+						: primaryApp?.branchName
+							? `branch ${primaryApp.branchName}`
+							: "applied",
+				);
+				setSessionState((s) => ({
+					...(s ?? {}),
+					branch: primaryApp?.branchName,
+					mrIid: primaryApp?.mr?.iid,
+				}));
+				setPhase("watching-ci");
+			} catch (err) {
+				if (cancelled) return;
+				finishStep("Opening MR", "fail", err.message ?? String(err));
+				setError(err);
+				setPhase("error");
+			}
+		})();
+		return () => {
+			cancelled = true;
+		};
+	}, [phase]);
+
+	// === watching-ci ===
+	useEffect(() => {
+		if (phase !== "watching-ci") return;
+		let cancelled = false;
+		pushStep("Watching CI pipeline", "polling every 5s");
+		let timer;
+		(async () => {
+			try {
+				const state = await readState(repo, iid);
+				if (!state?.mrIid) throw new Error("session has no mrIid; cannot watch");
+				const { createProvider } = await import(
+					path.join(projectRoot, "server/forge/core/providers/index.js")
+				);
+				const provider = createProvider(primary);
+				const poll = async () => {
+					if (cancelled) return;
+					try {
+						const pipelines = await provider.getMRPipelines(state.mrIid);
+						if (pipelines?.length) {
+							const latest = pipelines[0];
+							const [pipe, list] = await Promise.all([
+								provider.getPipeline(latest.id),
+								provider.getPipelineJobs(latest.id),
+							]);
+							if (cancelled) return;
+							setPipeline(pipe);
+							setJobs(list);
+							if (TERMINAL_PIPELINE.has(pipe.status)) {
+								await updateState(repo, iid, {
+									lastPipelineStatus: pipe.status,
+									lastPipelineUrl: pipe.web_url,
+								});
+								if (pipe.status === "success") {
+									finishStep("Watching CI pipeline", "ok", `${pipe.status}`);
+									setPhase("merge-gate");
+								} else {
+									finishStep("Watching CI pipeline", "fail", `${pipe.status}`);
+									setPhase("ci-fix-gate");
+								}
+								return;
+							}
+						}
+					} catch (err) {
+						// transient — keep polling
+						setError(err);
+					}
+					timer = setTimeout(poll, POLL_MS);
+				};
+				await poll();
+			} catch (err) {
+				if (cancelled) return;
+				finishStep("Watching CI pipeline", "fail", err.message ?? String(err));
+				setError(err);
+				setPhase("error");
+			}
+		})();
+		return () => {
+			cancelled = true;
+			if (timer) clearTimeout(timer);
+		};
+	}, [phase]);
+
+	// === ci-fixing ===
+	useEffect(() => {
+		if (phase !== "ci-fixing") return;
+		let cancelled = false;
+		pushStep("CI fix", "re-analyzing with failure logs");
+		(async () => {
+			try {
+				const state = await readState(repo, iid);
+				const { createProvider } = await import(
+					path.join(projectRoot, "server/forge/core/providers/index.js")
+				);
+				const provider = createProvider(primary);
+				const pipelines = await provider.getMRPipelines(state.mrIid);
+				const latest = pipelines?.[0];
+				if (!latest) throw new Error("no pipeline to inspect");
+				const allJobs = await provider.getPipelineJobs(latest.id);
+				const failed = allJobs.filter((j) => j.status === "failed");
+				if (!failed.length) throw new Error("no failed jobs to fix");
+				const traces = await Promise.all(
+					failed.map(async (j) => {
+						const trace = await provider.getJobTrace(j.id).catch(() => "");
+						const tail = trace.split("\n").slice(-150).join("\n");
+						return `### ${j.stage}/${j.name}\n\n\`\`\`\n${tail}\n\`\`\``;
+					}),
+				);
+				const ciContext = traces.join("\n\n");
+
+				const { ForgeAgent } = await import(
+					path.join(projectRoot, "server/forge/core/ForgeAgent.js")
+				);
+				const agent = new ForgeAgent({
+					project: primary,
+					secondaryProjects: secondaries,
+				});
+				let final = null;
+				const onEvent = (evt) => {
+					if (evt.type === "result") final = evt.data;
+				};
+				await agent.ciFixIssue(iid, ciContext, onEvent);
+				if (cancelled) return;
+				if (!final) throw new Error("ci-fix produced no result");
+				await agent.commitToBranch(state.branch, final, primary);
+				await writeAnalysis(repo, iid, final);
+				await updateState(repo, iid, { phase: PHASES.APPLIED, lastError: null });
+				finishStep("CI fix", "ok", `pushed to ${state.branch}`);
+				setPipeline(null);
+				setJobs([]);
+				setPhase("watching-ci");
+			} catch (err) {
+				if (cancelled) return;
+				finishStep("CI fix", "fail", err.message ?? String(err));
+				setError(err);
+				setPhase("error");
+			}
+		})();
+		return () => {
+			cancelled = true;
+		};
+	}, [phase]);
+
+	// === merging ===
+	useEffect(() => {
+		if (phase !== "merging") return;
+		let cancelled = false;
+		pushStep(autoMerge ? "Arming auto-merge" : "Merging MR", undefined);
+		(async () => {
+			try {
+				const state = await readState(repo, iid);
+				const { createProvider } = await import(
+					path.join(projectRoot, "server/forge/core/providers/index.js")
+				);
+				const provider = createProvider(primary);
+				if (autoMerge) {
+					if (typeof provider.setAutoMergeMR !== "function")
+						throw new Error("provider does not support auto-merge");
+					await provider.setAutoMergeMR(state.mrIid);
+				} else {
+					await provider.mergeMR(state.mrIid);
+				}
+				if (cancelled) return;
+				await updateState(repo, iid, {
+					phase: PHASES.MERGED,
+					mergedAt: new Date().toISOString(),
+					autoMergeArmed: !!autoMerge,
+				});
+				finishStep(
+					autoMerge ? "Arming auto-merge" : "Merging MR",
+					"ok",
+					autoMerge ? "armed" : "merged",
+				);
+				if (autoMerge) {
+					// auto-merge means we don't know exactly when it lands; stop here
+					setPhase("done");
+				} else {
+					setPhase("watching-deploy");
+				}
+			} catch (err) {
+				if (cancelled) return;
+				finishStep(
+					autoMerge ? "Arming auto-merge" : "Merging MR",
+					"fail",
+					err.message ?? String(err),
+				);
+				setError(err);
+				setPhase("error");
+			}
+		})();
+		return () => {
+			cancelled = true;
+		};
+	}, [phase]);
+
+	// === watching-deploy: poll the post-merge pipeline (target branch) ===
+	useEffect(() => {
+		if (phase !== "watching-deploy") return;
+		let cancelled = false;
+		pushStep("Watching deploy pipeline", "post-merge");
+		let timer;
+		(async () => {
+			try {
+				const { createProvider } = await import(
+					path.join(projectRoot, "server/forge/core/providers/index.js")
+				);
+				const provider = createProvider(primary);
+				const target =
+					process.env.GITLAB_BASE_BRANCH ??
+					process.env.GITHUB_BASE_BRANCH ??
+					"main";
+				const poll = async () => {
+					if (cancelled) return;
+					try {
+						const pipelines = await provider.getPipelinesByRef(target);
+						if (pipelines?.length) {
+							const latest = pipelines[0];
+							const pipe = await provider.getPipeline(latest.id);
+							if (cancelled) return;
+							setPipeline(pipe);
+							if (TERMINAL_PIPELINE.has(pipe.status)) {
+								await updateState(repo, iid, {
+									deployStatus: pipe.status,
+									deployedAt: new Date().toISOString(),
+								});
+								finishStep(
+									"Watching deploy pipeline",
+									pipe.status === "success" ? "ok" : "fail",
+									pipe.status,
+								);
+								setPhase(pipe.status === "success" ? "close-gate" : "error");
+								if (pipe.status !== "success") {
+									setError(new Error(`deploy pipeline ${pipe.status}`));
+								}
+								return;
+							}
+						}
+					} catch (err) {
+						setError(err);
+					}
+					timer = setTimeout(poll, POLL_MS);
+				};
+				await poll();
+			} catch (err) {
+				if (cancelled) return;
+				finishStep("Watching deploy pipeline", "fail", err.message ?? String(err));
+				setError(err);
+				setPhase("error");
+			}
+		})();
+		return () => {
+			cancelled = true;
+			if (timer) clearTimeout(timer);
+		};
+	}, [phase]);
+
+	// === closing ===
+	useEffect(() => {
+		if (phase !== "closing") return;
+		let cancelled = false;
+		pushStep("Closing issue", `#${iid}`);
+		(async () => {
+			try {
+				const { createProvider } = await import(
+					path.join(projectRoot, "server/forge/core/providers/index.js")
+				);
+				const provider = createProvider(primary);
+				await provider.closeIssue(iid);
+				if (cancelled) return;
+				await updateState(repo, iid, {
+					phase: PHASES.CLOSED,
+					closedAt: new Date().toISOString(),
+				});
+				finishStep("Closing issue", "ok");
+				setPhase("done");
+			} catch (err) {
+				if (cancelled) return;
+				finishStep("Closing issue", "fail", err.message ?? String(err));
+				setError(err);
+				setPhase("error");
+			}
+		})();
+		return () => {
+			cancelled = true;
+		};
+	}, [phase]);
+
+	// ─── Render ─────────────────────────────────────────────────────────────
+
+	const stepsRender = h`<${Box} flexDirection="column">
+		${steps.map((s, i) => h`<${StepLine} key=${i} ...${s} />`)}
+	</>`;
+
+	const pipelineRender = pipeline
+		? h`<${Box} marginTop=${1}>
+			<${Text} dimColor>Pipeline </>
+			<${Text} dimColor>#${pipeline.id} </>
+			<${Text} color=${pipeline.status === "success" ? "green" : pipeline.status === "failed" ? "red" : "cyan"}>${pipeline.status}</>
+			${pipeline.web_url ? h`<${Text} dimColor>  ${pipeline.web_url}</>` : null}
+		</>`
+		: null;
+
+	let gate = null;
+	if (phase === "review") {
+		gate = h`<${Box} flexDirection="column" marginTop=${1}>
+			${analysis ? h`<${ProposalSummary} analysis=${analysis} />` : null}
+			<${Box} marginTop=${1}><${Text} dimColor>${"Use 'no' to abort, 'yes' to continue (run `forge-agent refine` separately to iterate)."}</></>
+			<${Confirm}
+				message="Accept this fix and continue toward production?"
+				bypassYes=${bypassYes}
+				onSelect=${(yes) => setPhase(yes ? (skipValidate ? "apply-gate" : "validating") : "aborted")} />
+		</>`;
+	} else if (phase === "apply-gate") {
+		gate = h`<${Confirm}
+			message="Apply changes (open MR)?"
+			bypassYes=${bypassYes}
+			onSelect=${(yes) => setPhase(yes ? "applying" : "aborted")} />`;
+	} else if (phase === "ci-fix-gate") {
+		gate = h`<${Confirm}
+			message="CI failed. Re-analyse with failure logs and push a fix?"
+			bypassYes=${bypassYes}
+			onSelect=${(yes) => setPhase(yes ? "ci-fixing" : "aborted")} />`;
+	} else if (phase === "merge-gate") {
+		gate = h`<${Confirm}
+			message=${autoMerge ? "Arm auto-merge?" : "Merge MR to main?"}
+			bypassYes=${bypassYes}
+			onSelect=${(yes) => setPhase(yes ? "merging" : "aborted")} />`;
+	} else if (phase === "close-gate") {
+		gate = h`<${Confirm}
+			message=${`Close issue #${iid}?`}
+			bypassYes=${bypassYes}
+			onSelect=${(yes) => setPhase(yes ? "closing" : "done")} />`;
+	}
+
+	let footer = null;
+	if (phase === "done") {
+		footer = h`<${Box} marginTop=${1}>
+			<${Text} color="green">${`✓ Ship complete for #${iid}.`}</>
+		</>`;
+	} else if (phase === "aborted") {
+		footer = h`<${Box} marginTop=${1}>
+			<${Text} dimColor>${`Aborted. Resume with: forge-agent ship ${iid}`}</>
+		</>`;
+	} else if (phase === "error") {
+		footer = h`<${Box} marginTop=${1}>
+			<${Text} color="red">${`✘ ${error?.message ?? String(error)}`}</>
+			<${Text} dimColor>${`  (resume with: forge-agent ship ${iid})`}</>
+		</>`;
+	}
+
+	return h`<${Box} flexDirection="column">
+		<${Box}>
+			<${Text} bold>forge-agent ship </>
+			<${Text} color="yellow">#${iid}</>
+			<${Text} dimColor>${`  (${primary}${secondaries.length ? ` + ${secondaries.length} secondaries` : ""})`}</>
+		</>
+		${stepsRender}
+		${pipelineRender}
+		${gate}
+		${footer}
+	</>`;
+}
+
+export async function cmdShip(argv) {
+	const iid = Number(argv[1]);
+	if (!Number.isInteger(iid) || iid <= 0) {
+		console.error("Usage: forge-agent ship <iid> [options]");
+		process.exit(1);
+	}
+
+	const { primary, secondaries } = await resolveRepoSet(argv);
+	if (!primary) {
+		console.error(
+			"No repo. Pass --repo <group/repo>, set FORGE_GITLAB_PROJECT, or run `forge-agent init`.",
+		);
+		process.exit(1);
+	}
+
+	const bypassYes = argv.includes("--yes") || process.env.FORGE_YES === "1";
+	const autoMerge = argv.includes("--auto");
+	const skipValidate = argv.includes("--skip-validate");
+
+	let outcome = { phase: null };
+	await runApp(
+		h`<${ShipView}
+			iid=${iid}
+			primary=${primary}
+			secondaries=${secondaries}
+			bypassYes=${bypassYes}
+			autoMerge=${autoMerge}
+			skipValidate=${skipValidate}
+			onDone=${(o) => (outcome = o)} />`,
+	);
+
+	if (outcome.phase === "done") return;
+	if (outcome.phase === "aborted") process.exit(0);
+	process.exit(2);
+}