oma-coding-agent 1.1.4

package/src/cli/extension-flags.ts

@@ -0,0 +1,48 @@
+import { type Args, parseArgs } from "./args";
+
+/**
+ * Minimal extension-runner surface needed to resolve CLI flag values. The real
+ * `ExtensionRunner` satisfies this structurally; depending only on the surface
+ * keeps this module free of the heavier runner/session imports and unit-testable
+ * with a fake.
+ */
+export interface ExtensionFlagSink {
+	getFlags(): Map<string, { type: "boolean" | "string" }>;
+	setFlagValue(name: string, value: boolean | string): void;
+}
+
+/**
+ * Resolve extension-registered CLI flags from `rawArgs` once the flag set is
+ * known, push the resolved values onto the sink, and return the parsed
+ * {@link Args} (whose `messages` and `fileArgs` now reflect those flags).
+ *
+ * The startup parse runs before extensions load, so it cannot recognise their
+ * flags: a string flag's value (`--spawn-peer reviewer` or `--spawn-peer=reviewer`)
+ * is otherwise left in `messages` and leaks into the initial prompt. Re-parsing
+ * here — through the *same* {@link parseArgs} the startup pass uses, now seeded
+ * with the registered flags — consumes every flag form (`--flag`, `--flag value`,
+ * `--flag=value`).
+ *
+ * {@link parseArgs} lets a registered flag shadow a same-named built-in, so even
+ * a built-in-colliding flag (e.g. plan-mode's boolean `--plan`, which would
+ * otherwise hit the built-in plan-model branch) is parsed with the extension's
+ * semantics and surfaces in `unknownFlags` — without consuming the following
+ * message or overwriting the built-in field. No built-in name list to maintain.
+ *
+ * Returns `null` when there is no sink or no registered extension flags, in
+ * which case the caller keeps its original startup parse (an extension-aware
+ * re-parse would be identical anyway).
+ */
+export function applyExtensionFlags(runner: ExtensionFlagSink | undefined, rawArgs: string[]): Args | null {
+	const extensionFlags = runner?.getFlags();
+	if (!runner || !extensionFlags || extensionFlags.size === 0) {
+		return null;
+	}
+	const parsed = parseArgs(rawArgs, extensionFlags);
+	// `parseArgs` only records registered extension flags in `unknownFlags`, so
+	// every entry here is a flag this runner owns that was actually passed.
+	for (const [name, value] of parsed.unknownFlags) {
+		runner.setFlagValue(name, value);
+	}
+	return parsed;
+}

package/src/cli/file-processor.ts

@@ -0,0 +1,133 @@
+/**
+ * Process @file CLI arguments into text, document content, and image attachments
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ImageContent } from "@oh-my-pi/pi-ai";
+import { getProjectDir, isEnoent, readImageMetadata } from "@oh-my-pi/pi-utils";
+import chalk from "chalk";
+import { resolveReadPath } from "../tools/path-utils";
+import { formatBytes } from "../tools/render-utils";
+import { formatDimensionNote, resizeImage } from "../utils/image-resize";
+import { convertFileWithMarkit } from "../utils/markit";
+
+// Keep CLI startup responsive and avoid OOM when users pass huge files.
+// If a file exceeds these limits, we include it as a path-only <file/> block.
+const MAX_CLI_TEXT_BYTES = 5 * 1024 * 1024; // 5MB
+const MAX_CLI_IMAGE_BYTES = 25 * 1024 * 1024; // 25MB
+const CONVERTIBLE_EXTENSIONS = new Set([".pdf", ".doc", ".docx", ".ppt", ".pptx", ".xls", ".xlsx", ".rtf", ".epub"]);
+
+export interface ProcessedFiles {
+	text: string;
+	images: ImageContent[];
+}
+
+export interface ProcessFileOptions {
+	/** Whether to auto-resize images to 2000x2000 max. Default: true */
+	autoResizeImages?: boolean;
+}
+
+/** Process @file arguments into text, document content, and image attachments */
+export async function processFileArguments(fileArgs: string[], options?: ProcessFileOptions): Promise<ProcessedFiles> {
+	const autoResizeImages = options?.autoResizeImages ?? true;
+	let text = "";
+	const images: ImageContent[] = [];
+
+	for (const fileArg of fileArgs) {
+		// Expand and resolve path (handles ~ expansion and macOS screenshot Unicode spaces)
+		const absolutePath = path.resolve(resolveReadPath(fileArg, getProjectDir()));
+
+		const stat = fs.statSync(absolutePath, { throwIfNoEntry: false });
+		if (!stat) {
+			console.error(chalk.red(`Error: File not found: ${absolutePath}`));
+			process.exit(1);
+		}
+
+		const imageMetadata = await readImageMetadata(absolutePath);
+		const mimeType = imageMetadata?.mimeType;
+		const ext = path.extname(absolutePath).toLowerCase();
+		const maxBytes = mimeType ? MAX_CLI_IMAGE_BYTES : MAX_CLI_TEXT_BYTES;
+		if (stat.size > maxBytes) {
+			console.error(
+				chalk.yellow(`Warning: Skipping file contents (too large: ${formatBytes(stat.size)}): ${absolutePath}`),
+			);
+			text += `<file name="${absolutePath}">(skipped: too large, ${formatBytes(stat.size)})</file>\n`;
+			continue;
+		}
+
+		// Read file, handling not-found gracefully
+		let buffer: Uint8Array;
+		try {
+			buffer = await Bun.file(absolutePath).bytes();
+		} catch (err) {
+			if (isEnoent(err)) {
+				console.error(chalk.red(`Error: File not found: ${absolutePath}`));
+				process.exit(1);
+			}
+			throw err;
+		}
+		if (buffer.length === 0) {
+			continue;
+		}
+
+		if (mimeType) {
+			// Handle image file
+			const base64Content = buffer.toBase64();
+			let attachment: ImageContent;
+			let dimensionNote: string | undefined;
+
+			if (autoResizeImages) {
+				try {
+					const resized = await resizeImage({ type: "image", data: base64Content, mimeType });
+					dimensionNote = formatDimensionNote(resized);
+					attachment = {
+						type: "image",
+						mimeType: resized.mimeType,
+						data: resized.data,
+					};
+				} catch {
+					// Fall back to original image on resize failure
+					attachment = {
+						type: "image",
+						mimeType,
+						data: base64Content,
+					};
+				}
+			} else {
+				attachment = {
+					type: "image",
+					mimeType,
+					data: base64Content,
+				};
+			}
+
+			images.push(attachment);
+
+			// Add text reference to image with optional dimension note
+			if (dimensionNote) {
+				text += `<file name="${absolutePath}">${dimensionNote}</file>\n`;
+			} else {
+				text += `<file name="${absolutePath}"></file>\n`;
+			}
+		} else if (CONVERTIBLE_EXTENSIONS.has(ext)) {
+			const result = await convertFileWithMarkit(absolutePath);
+			if (result.ok) {
+				text += `<file name="${absolutePath}">\n${result.content}\n</file>\n`;
+			} else {
+				text += `<file name="${absolutePath}">[Cannot read ${ext} file: ${result.error || "conversion failed"}]</file>\n`;
+			}
+		} else {
+			// Handle text file
+			try {
+				const content = new TextDecoder().decode(buffer);
+				text += `<file name="${absolutePath}">\n${content}\n</file>\n`;
+			} catch (error: unknown) {
+				const message = error instanceof Error ? error.message : String(error);
+				console.error(chalk.red(`Error: Could not read file ${absolutePath}: ${message}`));
+				process.exit(1);
+			}
+		}
+	}
+
+	return { text, images };
+}

package/src/cli/flag-tables.ts

@@ -0,0 +1,280 @@
+/**
+ * Single source of truth for argv flag classification, shared by:
+ *   - `parseArgs` in `./args.ts` (the launch-time CLI parser)
+ *   - `extractProfileFlags` in `./profile-bootstrap.ts` (the early
+ *     `--profile` / `--alias` pre-parser)
+ *
+ * `parseArgs` dispatches string-valued flags by looking up their setter in
+ * {@link STRING_SETTERS}. Optional-value flags use {@link OPTIONAL_FLAGS} so
+ * per-flag quirks (currently empty-string rejection for `--resume`) live here
+ * instead of being hard-coded in the dispatch loop.
+ *
+ * The bootstrap doesn't dispatch — it only needs to know which flags consume
+ * a value — so it consults {@link STRING_VALUE_FLAGS} and
+ * {@link OPTIONAL_VALUE_FLAGS}, both derived from `Object.keys(...)` on the
+ * setter/config records below.
+ *
+ * The deliberate consequence: a string-valued flag exists in this CLI surface
+ * iff it has an entry here. Adding a new string-valued flag means adding a
+ * setter/config entry in this file; both `args.ts` and the bootstrap pick it
+ * up automatically, so the two cannot drift out of sync.
+ *
+ * IMPORT RULE: this module MUST NOT import any runtime value from
+ * `@oh-my-pi/pi-utils` (or anything that transitively does). That package's
+ * `env.ts` eagerly loads `.env` files from `getAgentDir()` during module
+ * initialization, which would race the profile bootstrap. Type-only imports
+ * are erased at runtime and are therefore safe.
+ *
+ * If a setter needs runtime dependencies (logging, validators, lookup
+ * tables), they're passed in through {@link ParseDeps} and `args.ts` wires the
+ * real implementations at the dispatch site.
+ */
+
+import type { Effort } from "@oh-my-pi/pi-ai";
+import type { Args } from "./args";
+
+/**
+ * Runtime dependencies injected into setters that need to validate input or
+ * warn about bad values. `args.ts` constructs one object at module load and
+ * passes it to each {@link STRING_SETTERS} call.
+ *
+ * Keeping these out of the setter closures means this module stays free of
+ * runtime imports from `@oh-my-pi/pi-utils`, which is the whole reason it can
+ * be safely imported by `profile-bootstrap.ts` before `setProfile` runs.
+ */
+export interface ParseDeps {
+	logger: { warn: (message: string, meta?: Record<string, unknown>) => void };
+	parseEffort: (value: string | null | undefined) => Effort | undefined;
+	builtinToolNames: readonly string[];
+	thinkingEfforts: readonly string[];
+}
+
+export type StringSetter = (result: Args, value: string, deps: ParseDeps) => void;
+
+/**
+ * Setter for a flag that may or may not consume the next argv token.
+ * Receives `undefined` for the bare form (`--resume` with no value, etc.).
+ */
+export type OptionalSetter = (result: Args, value: string | undefined) => void;
+
+/**
+ * Per-flag optional-value consumption policy.
+ *
+ * Every optional flag always rejects tokens that start with `-` — that shared
+ * rule lives in the dispatch site. These booleans capture the *additional*
+ * per-flag quirks:
+ *
+ * - `rejectEmpty`: treat `""` like “no value provided”. Needed for
+ *   `--resume` / `-r` / `--session`. Without it, an empty string
+ *   gets consumed as the session prefix and downstream resolution can match
+ *   every session.
+ */
+export interface OptionalFlagConfig {
+	set: OptionalSetter;
+	rejectEmpty?: boolean;
+}
+
+// Shared setters for flags that alias the same field.
+const setExtension: StringSetter = (result, value) => {
+	result.extensions = result.extensions ?? [];
+	result.extensions.push(value);
+};
+
+const setResume: OptionalSetter = (result, value) => {
+	result.resume = value !== undefined ? value : true;
+};
+
+/**
+ * Setters for flags with string values. Most built-ins consume the next argv
+ * token even when it starts with `-`; flags listed in
+ * {@link EXTENSION_SHADOWABLE_STRING_FLAGS} use extension-style consumption so
+ * a registered boolean extension can shadow them before profile bootstrap.
+ */
+export const STRING_SETTERS: Record<string, StringSetter> = {
+	"--cwd": (result, value) => {
+		result.cwd = value;
+	},
+	"--config": (result, value) => {
+		result.config = [...(result.config ?? []), value];
+	},
+	"--mode": (result, value) => {
+		if (value === "text" || value === "json" || value === "rpc" || value === "acp" || value === "rpc-ui") {
+			result.mode = value;
+		}
+	},
+	"--fork": (result, value) => {
+		result.fork = value;
+	},
+	"--provider": (result, value) => {
+		result.provider = value;
+	},
+	"--model": (result, value) => {
+		result.model = value;
+	},
+	"--smol": (result, value) => {
+		result.smol = value;
+	},
+	"--slow": (result, value) => {
+		result.slow = value;
+	},
+	"--plan": (result, value) => {
+		result.plan = value;
+	},
+	"--max-time": (result, value, deps) => {
+		const seconds = Number(value);
+		if (Number.isFinite(seconds) && seconds > 0) {
+			result.maxTime = seconds;
+		} else {
+			deps.logger.warn("Invalid seconds passed to --max-time", { value });
+		}
+	},
+	"--api-key": (result, value) => {
+		result.apiKey = value;
+	},
+	"--system-prompt": (result, value) => {
+		result.systemPrompt = value;
+	},
+	"--append-system-prompt": (result, value) => {
+		result.appendSystemPrompt = value;
+	},
+	"--provider-session-id": (result, value) => {
+		result.providerSessionId = value;
+	},
+	"--session-dir": (result, value) => {
+		result.sessionDir = value;
+	},
+	"--models": (result, value) => {
+		result.models = value.split(",").map(s => s.trim());
+	},
+	"--tools": (result, value, deps) => {
+		const names = value
+			.split(",")
+			.map(s => s.trim().toLowerCase())
+			.filter(Boolean);
+		const valid: string[] = [];
+		for (const name of names) {
+			if (deps.builtinToolNames.includes(name)) {
+				valid.push(name);
+			} else {
+				deps.logger.warn("Unknown tool passed to --tools", {
+					tool: name,
+					validTools: deps.builtinToolNames,
+				});
+			}
+		}
+		result.tools = valid;
+	},
+	"--thinking": (result, value, deps) => {
+		const thinking = deps.parseEffort(value);
+		if (thinking !== undefined) {
+			result.thinking = thinking;
+		} else {
+			deps.logger.warn("Invalid thinking level passed to --thinking", {
+				level: value,
+				validThinkingLevels: deps.thinkingEfforts,
+			});
+		}
+	},
+	"--export": (result, value) => {
+		result.export = value;
+	},
+	"--hook": (result, value) => {
+		result.hooks = result.hooks ?? [];
+		result.hooks.push(value);
+	},
+	"--extension": setExtension,
+	"-e": setExtension,
+	"--plugin-dir": (result, value) => {
+		result.pluginDirs = result.pluginDirs ?? [];
+		result.pluginDirs.push(value);
+	},
+	"--skills": (result, value) => {
+		result.skills = value.split(",").map(s => s.trim());
+	},
+	"--approval-mode": (result, value, deps) => {
+		if (value === "always-ask" || value === "write" || value === "yolo") {
+			result.approvalMode = value;
+		} else {
+			deps.logger.warn("Invalid value passed to --approval-mode", {
+				value,
+				validValues: ["always-ask", "write", "yolo"],
+			});
+		}
+	},
+};
+
+/**
+ * Optional-value flags. Setters receive `undefined` for the bare form.
+ *
+ * The dispatch in `args.ts` applies the shared "doesn't start with `-`"
+ * check for every flag, then consults the per-flag booleans below for the
+ * remaining quirks.
+ */
+export const OPTIONAL_FLAGS: Record<string, OptionalFlagConfig> = {
+	"--resume": { set: setResume, rejectEmpty: true },
+	"-r": { set: setResume, rejectEmpty: true },
+	"--session": { set: setResume, rejectEmpty: true },
+};
+
+/**
+ * Derived from {@link STRING_SETTERS}. A flag is in this set if and only if
+ * it has a setter — by construction, drift between "the bootstrap thinks
+ * this flag accepts a value" and "the launch parser can set one" is
+ * structurally impossible.
+ */
+export const STRING_VALUE_FLAGS: ReadonlySet<string> = new Set(Object.keys(STRING_SETTERS));
+
+/**
+ * Built-in string flags known to be shadowed by bundled/common boolean
+ * extensions before extension metadata is available. They still accept a
+ * value-like successor for the built-in form (`--plan opus`), but a
+ * flag-looking successor remains a fresh flag (`--plan --profile work`).
+ */
+export const EXTENSION_SHADOWABLE_STRING_FLAGS: ReadonlySet<string> = new Set(["--plan"]);
+
+/**
+ * Derived from {@link OPTIONAL_FLAGS}. Same single-source contract as
+ * {@link STRING_VALUE_FLAGS}.
+ */
+export const OPTIONAL_VALUE_FLAGS: ReadonlySet<string> = new Set(Object.keys(OPTIONAL_FLAGS));
+
+/**
+ * Internal marker inserted by the profile bootstrap when removing `--profile`
+ * or `--alias` would otherwise make the following value-like token become the
+ * value of a preceding optional/extension flag. `parseArgs` ignores it, but its
+ * flag-looking shape preserves argv boundaries during the second parse.
+ */
+export const PROFILE_BOOTSTRAP_BOUNDARY_ARG = "--omp-profile-boundary";
+
+/**
+ * Long-form launch flags that take NO value (booleans). The bootstrap pre-parser
+ * needs this to tell a known value-less flag (whose successor is a fresh
+ * argument — `omp --print --profile work` still selects a profile) apart from an
+ * UNKNOWN long option that might be an extension string flag consuming the next
+ * token as its value (so the bootstrap must not steal that token as a global
+ * `--profile`/`--alias`). MUST mirror the value-less flag arms of `parseArgs`
+ * in `./args.ts`: adding a new boolean launch flag there means adding it here,
+ * or `--<newflag> --profile X` stops selecting a profile. Short aliases
+ * (`-h`/`-v`/`-c`/`-p`) are intentionally omitted — the protection rule only
+ * fires for `--`-prefixed tokens.
+ */
+export const VALUELESS_FLAGS: ReadonlySet<string> = new Set([
+	"--help",
+	"--version",
+	"--allow-home",
+	"--continue",
+	"--no-session",
+	"--no-tools",
+	"--no-lsp",
+	"--no-pty",
+	"--hide-thinking",
+	"--advisor",
+	"--print",
+	"--print-thoughts",
+	"--no-extensions",
+	"--no-skills",
+	"--no-rules",
+	"--no-title",
+	"--auto-approve",
+	"--yolo",
+]);

package/src/cli/gallery-cli.ts

@@ -0,0 +1,231 @@
+/**
+ * `omp gallery` — render every built-in tool's renderer across its lifecycle.
+ *
+ * For each tool with a registered renderer, the gallery drives a real
+ * {@link ToolExecutionComponent} through four states — streaming arguments,
+ * arguments complete (in progress), success, and failure — and prints the
+ * rendered output to stdout. It exists for visual QA of tool renderers without
+ * having to provoke each state through a live agent session.
+ */
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import type { TUI } from "@oh-my-pi/pi-tui";
+import { getProjectDir } from "@oh-my-pi/pi-utils";
+import { Settings } from "../config/settings";
+import { ToolExecutionComponent } from "../modes/components/tool-execution";
+import { initTheme, theme } from "../modes/theme/theme";
+import { toolRenderers } from "../tools/renderers";
+import { type GalleryFixture, type GalleryResult, galleryFixtures } from "./gallery-fixtures";
+import { captureGalleryScreenshots } from "./gallery-screenshot";
+
+/** Lifecycle states the gallery renders, in display order. */
+export const GALLERY_STATES = ["streaming", "progress", "success", "error"] as const;
+export type GalleryState = (typeof GALLERY_STATES)[number];
+
+const STATE_LABELS: Record<GalleryState, string> = {
+	streaming: "streaming args",
+	progress: "in progress",
+	success: "done",
+	error: "failed",
+};
+
+export interface GalleryCommandArgs {
+	/** Render width in columns (defaults to terminal width, clamped). */
+	width?: number;
+	/** Restrict to a single tool name. */
+	tool?: string;
+	/** Restrict to specific lifecycle states. */
+	states?: GalleryState[];
+	/** Render the expanded variant of each renderer. */
+	expanded?: boolean;
+	/** Strip ANSI styling from the output (useful when redirecting to a file). */
+	plain?: boolean;
+	/** Capture the rendered gallery as PNG screenshot(s) via VHS instead of printing ANSI. */
+	screenshot?: boolean;
+	/** Screenshot output path (single image) or base path (suffixed when split across images). */
+	out?: string;
+	/** Font family for screenshots (must be installed; Nerd Font recommended for icon glyphs). */
+	font?: string;
+	/** Font size in points for screenshots. */
+	fontSize?: number;
+}
+
+/** One tool's rendered lifecycle, as ANSI lines: a leading blank, the section rule, then each state. */
+export interface GallerySection {
+	heading: string;
+	lines: string[];
+}
+
+const GENERIC_ERROR: GalleryResult = {
+	content: [{ type: "text", text: "Error: operation failed" }],
+	isError: true,
+};
+
+/**
+ * Build the fake `AgentTool` the component needs for its label, edit mode, and —
+ * for `customRendered` fixtures — the renderer functions that route it through
+ * the same custom-tool branch production uses (see {@link GalleryFixture}).
+ */
+function fakeToolFor(name: string, fixture: GalleryFixture | undefined): AgentTool | undefined {
+	if (!fixture?.label && !fixture?.editMode && !fixture?.customRendered) return undefined;
+	const tool: Record<string, unknown> = { name, label: fixture.label ?? name, mode: fixture.editMode };
+	if (fixture.customRendered) {
+		const renderer = toolRenderers[fixture.renderer ?? name] as
+			| { renderCall?: unknown; renderResult?: unknown; mergeCallAndResult?: unknown; inline?: unknown }
+			| undefined;
+		if (renderer) {
+			tool.renderCall = renderer.renderCall;
+			tool.renderResult = renderer.renderResult;
+			tool.mergeCallAndResult = renderer.mergeCallAndResult;
+			tool.inline = renderer.inline;
+		}
+	}
+	return tool as unknown as AgentTool;
+}
+
+/** The curated fixture for a tool, or a generic one for registry tools lacking sample data. */
+export function resolveFixture(name: string): GalleryFixture {
+	return (
+		galleryFixtures[name] ??
+		({
+			args: { note: `sample ${name} call` },
+			result: { content: [{ type: "text", text: `${name} completed` }] },
+		} satisfies GalleryFixture)
+	);
+}
+
+/**
+ * Render a single tool/state pair to lines. Builds a fresh component, drives it
+ * to the requested state, settles any async edit preview, then snapshots the
+ * render and stops all animation timers.
+ */
+export async function renderGalleryState(
+	name: string,
+	fixture: GalleryFixture,
+	state: GalleryState,
+	width: number,
+	expanded = false,
+): Promise<readonly string[]> {
+	if (fixture.renderState) {
+		return await fixture.renderState(state, width, expanded);
+	}
+
+	const tool = fakeToolFor(name, fixture);
+	const streamingArgs = state === "streaming" ? (fixture.streamingArgs ?? fixture.args) : fixture.args;
+	// The component only calls `requestRender`/`requestComponentRender` (via
+	// its loader) during a static render; `imageBudget` is consulted solely
+	// when images render, which the gallery disables. A cast avoids
+	// constructing a real terminal.
+	const ui = { requestRender() {}, requestComponentRender() {} } as unknown as TUI;
+	const component = new ToolExecutionComponent(name, streamingArgs, { showImages: false }, tool, ui, getProjectDir());
+	component.setExpanded(expanded);
+
+	if (state !== "streaming") {
+		component.setArgsComplete();
+	}
+	if (state === "success") {
+		component.updateResult(fixture.result, false);
+	} else if (state === "error") {
+		component.updateResult(fixture.errorResult ?? GENERIC_ERROR, false);
+	}
+
+	// Edit-like renderers compute their diff preview off the render path; wait
+	// for it to settle so the snapshot is deterministic instead of racing a tick.
+	await component.whenPreviewSettled();
+
+	const lines = component.render(width);
+	component.stopAnimation();
+	return lines;
+}
+
+function resolveWidth(requested: number | undefined): number {
+	const fallback = process.stdout.columns ?? 100;
+	const width = requested ?? fallback;
+	return Math.max(40, Math.min(200, width));
+}
+
+function sectionRule(label: string, width: number): string {
+	const prefix = `── ${label} `;
+	const fill = Math.max(0, width - prefix.length);
+	return theme.fg("accent", theme.bold(`${prefix}${"─".repeat(fill)}`));
+}
+
+/**
+ * Render each requested tool's lifecycle into ANSI section blocks. The block
+ * layout (leading blank, section rule, then a blank + dim label + body per
+ * state) is shared by the stdout and screenshot paths so both stay identical.
+ */
+async function renderGallerySections(
+	names: string[],
+	states: GalleryState[],
+	width: number,
+	expanded: boolean,
+): Promise<GallerySection[]> {
+	const sections: GallerySection[] = [];
+	for (const name of names) {
+		const fixture = resolveFixture(name);
+		const heading = fixture.label && fixture.label !== name ? `${name} — ${fixture.label}` : name;
+		const lines: string[] = ["", sectionRule(heading, width)];
+		for (const state of states) {
+			lines.push("", theme.fg("dim", `  · ${STATE_LABELS[state]}`));
+			try {
+				for (const line of await renderGalleryState(name, fixture, state, width, expanded)) lines.push(line);
+			} catch (err) {
+				lines.push(theme.fg("error", `  render failed: ${String(err)}`));
+			}
+		}
+		sections.push({ heading, lines });
+	}
+	return sections;
+}
+
+/**
+ * Render the gallery. Iterates the renderer registry (or a single tool),
+ * printing each requested lifecycle state under a labeled section — or, with
+ * `screenshot`, capturing the rendered output as PNG(s) via VHS.
+ */
+export async function runGalleryCommand(args: GalleryCommandArgs): Promise<void> {
+	const settingsInstance = await Settings.init();
+	// Screenshots must carry exact theme RGB regardless of how the invoking
+	// terminal advertises its color support, so force truecolor before the theme
+	// (and therefore every SGR escape it emits) is built.
+	if (args.screenshot) process.env.COLORTERM = "truecolor";
+	await initTheme(
+		false,
+		settingsInstance.get("symbolPreset"),
+		settingsInstance.get("colorBlindMode"),
+		settingsInstance.get("theme.dark"),
+		settingsInstance.get("theme.light"),
+	);
+
+	const width = resolveWidth(args.width);
+	const expanded = args.expanded ?? false;
+	const states = args.states && args.states.length > 0 ? args.states : [...GALLERY_STATES];
+
+	// Renderer-registry tools plus fixture-only tools (no dedicated renderer,
+	// e.g. `report_tool_issue` / custom extension tools) so the gallery covers
+	// the generic fallback + custom-tool branches too.
+	const allNames = Array.from(new Set([...Object.keys(toolRenderers), ...Object.keys(galleryFixtures)])).sort();
+	const names = args.tool ? allNames.filter(name => name === args.tool) : allNames;
+	if (args.tool && names.length === 0) {
+		process.stdout.write(`Unknown tool '${args.tool}'. Known tools: ${allNames.join(", ")}\n`);
+		return;
+	}
+
+	const sections = await renderGallerySections(names, states, width, expanded);
+
+	if (args.screenshot) {
+		const paths = await captureGalleryScreenshots(sections, {
+			width,
+			font: args.font,
+			fontSize: args.fontSize,
+			out: args.out,
+		});
+		process.stdout.write(`${paths.join("\n")}\n`);
+		return;
+	}
+
+	const lines = sections.flatMap(section => section.lines);
+	lines.push("");
+	const text = lines.map(line => (args.plain ? Bun.stripANSI(line) : line)).join("\n");
+	process.stdout.write(`${text}\n`);
+}