@sanurb/ringi 0.2.0 → 0.2.1

package/dist/cli.mjs

@@ -0,0 +1,1741 @@
+#!/usr/bin/env node
+import { a as GitService, c as CommentService, f as ReviewNotFound, i as ReviewService, n as ExportService, o as getDiffSummary, r as TodoService, s as parseDiff, t as CoreLive, u as TodoNotFound } from "./runtime.mjs";
+import { exec, execFileSync, fork } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import * as Schema from "effect/Schema";
+import * as Either from "effect/Either";
+import { writeFile } from "node:fs/promises";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as ConfigProvider from "effect/ConfigProvider";
+//#region src/cli/config.ts
+var CliConfig = class extends Context.Tag("@ringi/CliConfig")() {};
+/**
+* Wraps a concrete {@link CliConfigShape} in a layer for the Effect runtime.
+*/
+const CliConfigLive = (config) => Layer.succeed(CliConfig, config);
+//#endregion
+//#region src/cli/contracts.ts
+const ExitCode = {
+	AuthFailure: 5,
+	ResourceNotFound: 3,
+	RuntimeFailure: 1,
+	StateUnavailable: 4,
+	Success: 0,
+	UsageError: 2
+};
+const success = (command, result, nextActions = []) => ({
+	command,
+	next_actions: nextActions,
+	ok: true,
+	result
+});
+const failure = (command, error, fix, nextActions = []) => ({
+	command,
+	error,
+	fix,
+	next_actions: nextActions,
+	ok: false
+});
+/**
+* Carries an exit code and optional operator-facing details so callers can
+* present a short message without losing the underlying reason.
+*/
+var CliFailure = class extends Schema.TaggedError()("CliFailure", {
+	details: Schema.optional(Schema.String),
+	exitCode: Schema.Number,
+	message: Schema.String
+}) {};
+//#endregion
+//#region src/cli/commands.ts
+const formatTable = (headers, rows) => {
+	const widths = headers.map((header, index) => {
+		const cellWidths = rows.map((row) => row[index]?.length ?? 0);
+		return Math.max(header.length, ...cellWidths);
+	});
+	const renderRow = (row) => row.map((cell, index) => cell.padEnd(widths.at(index) ?? 0)).join("  ").trimEnd();
+	return [
+		renderRow(headers),
+		renderRow(widths.map((width) => "-".repeat(width))),
+		...rows.map(renderRow)
+	].join("\n");
+};
+const renderReviewList = (reviews) => {
+	if (reviews.length === 0) return "No reviews found.";
+	return formatTable([
+		"ID",
+		"STATUS",
+		"SOURCE",
+		"FILES",
+		"CREATED"
+	], reviews.map((review) => [
+		review.id,
+		review.status,
+		review.sourceType,
+		String(review.fileCount),
+		review.createdAt
+	]));
+};
+const renderReviewShow = (input) => {
+	const { comments, review, todos } = input;
+	const lines = [
+		`Review ${review.id}`,
+		`Status: ${review.status}`,
+		`Source: ${review.sourceType}${review.sourceRef ? ` (${review.sourceRef})` : ""}`,
+		`Created: ${review.createdAt}`,
+		`Files: ${review.summary.totalFiles}`,
+		`Diff: +${review.summary.totalAdditions} / -${review.summary.totalDeletions}`
+	];
+	if (review.files.length > 0) {
+		lines.push("", "Files:");
+		for (const file of review.files) lines.push(`- ${file.status.toUpperCase()} ${file.filePath} (+${file.additions} -${file.deletions})`);
+	}
+	if (comments && comments.length > 0) {
+		lines.push("", "Comments:");
+		for (const comment of comments) {
+			const location = `${comment.filePath}:${comment.lineNumber ?? "-"}`;
+			const state = comment.resolved ? "resolved" : "open";
+			lines.push(`- [${state}] ${location} ${comment.content}`);
+		}
+	}
+	if (todos && todos.length > 0) {
+		lines.push("", "Todos:");
+		for (const todo of todos) {
+			const marker = todo.completed ? "x" : " ";
+			lines.push(`- [${marker}] (${todo.position + 1}) ${todo.content}`);
+		}
+	}
+	return lines.join("\n");
+};
+const renderTodoList = (todos) => {
+	if (todos.length === 0) return "No todos found.";
+	return todos.map((todo) => `- [${todo.completed ? "x" : " "}] (${todo.position + 1}) ${todo.content}`).join("\n");
+};
+const renderSourceList = (input) => {
+	const lines = [
+		`Repository: ${input.repo.name}`,
+		`Path: ${input.repo.path}`,
+		`Current branch: ${input.repo.branch}`,
+		`Staged files: ${input.stagedFiles.length}`
+	];
+	if (input.stagedFiles.length > 0) {
+		lines.push("", "Staged:");
+		for (const file of input.stagedFiles) lines.push(`- ${file.status} ${file.path}`);
+	}
+	if (input.branches.length > 0) {
+		lines.push("", "Branches:");
+		for (const branch of input.branches.slice(0, 10)) lines.push(`- ${branch.current ? "*" : " "} ${branch.name}`);
+	}
+	if (input.commits.length > 0) {
+		lines.push("", "Recent commits:");
+		for (const commit of input.commits.slice(0, 5)) lines.push(`- ${commit.hash.slice(0, 8)} ${commit.message} (${commit.author})`);
+	}
+	return lines.join("\n");
+};
+/**
+* Resolves the special "last" selector before show/export handlers ask the
+* shared services for a concrete review id.
+*/
+const resolveReviewSelector = Effect.fn("CLI.resolveReviewSelector")(function* resolveReviewSelector(selector) {
+	if (selector !== "last") return selector;
+	const cliConfig = yield* CliConfig;
+	const [review] = (yield* (yield* ReviewService).list({
+		page: 1,
+		pageSize: 1,
+		repositoryPath: cliConfig.repoRoot
+	})).reviews;
+	if (!review) return yield* new CliFailure({
+		exitCode: ExitCode.ResourceNotFound,
+		message: "No review sessions exist for this repository yet."
+	});
+	return review.id;
+});
+/**
+* Mutating CLI commands stay server-backed so they share the same write path as
+* the other clients instead of growing a second local-only behavior surface.
+*/
+const requireServerMode = (label) => Effect.fail(new CliFailure({
+	details: "Start 'ringi serve' and retry the command.",
+	exitCode: ExitCode.StateUnavailable,
+	message: `${label} requires a running local Ringi server. Standalone local writes are intentionally unsupported.`
+}));
+const diffSourceStrategies = {
+	branch: (git, command) => git.getBranchDiff(command.branch ?? ""),
+	commits: (git, command) => git.getCommitDiff((command.commits ?? "").split(",").map((item) => item.trim()).filter(Boolean)),
+	staged: (git) => git.getStagedDiff
+};
+const runReviewList = Effect.fn("CLI.reviewList")(function* runReviewList(command) {
+	const reviewService = yield* ReviewService;
+	const cliConfig = yield* CliConfig;
+	const result = yield* reviewService.list({
+		page: command.page,
+		pageSize: command.limit,
+		repositoryPath: cliConfig.repoRoot,
+		sourceType: command.source,
+		status: command.status
+	});
+	const nextActions = [];
+	for (const review of result.reviews.slice(0, 3)) nextActions.push({
+		command: `ringi review show ${review.id} --comments --todos`,
+		description: `Inspect review ${review.id} (${review.status})`
+	});
+	if (result.reviews.length > 0) nextActions.push({
+		command: "ringi review show <id> [--comments] [--todos]",
+		description: "Show full review details",
+		params: { id: {
+			description: "Review ID or 'last'",
+			required: true
+		} }
+	});
+	nextActions.push({
+		command: "ringi review create [--source <source>]",
+		description: "Create a new review session",
+		params: { source: {
+			default: "staged",
+			enum: [
+				"staged",
+				"branch",
+				"commits"
+			]
+		} }
+	});
+	return {
+		data: result,
+		human: renderReviewList(result.reviews),
+		nextActions
+	};
+});
+const runReviewShow = Effect.fn("CLI.reviewShow")(function* runReviewShow(command) {
+	const reviewService = yield* ReviewService;
+	const todoService = yield* TodoService;
+	const commentService = yield* CommentService;
+	const reviewId = yield* resolveReviewSelector(command.id);
+	const review = yield* reviewService.getById(reviewId);
+	const data = {
+		comments: command.comments ? yield* commentService.getByReview(reviewId) : void 0,
+		review,
+		todos: command.todos ? (yield* todoService.list({ reviewId })).data : void 0
+	};
+	const nextActions = [
+		{
+			command: `ringi review export ${reviewId}`,
+			description: "Export this review as markdown"
+		},
+		{
+			command: `ringi review show ${reviewId} --comments --todos`,
+			description: "Show with comments and todos"
+		},
+		{
+			command: "ringi todo list [--review <review-id>] [--status <status>]",
+			description: "List todos for this review",
+			params: {
+				"review-id": { value: reviewId },
+				status: {
+					default: "pending",
+					enum: [
+						"pending",
+						"done",
+						"all"
+					]
+				}
+			}
+		},
+		{
+			command: "ringi review list",
+			description: "Back to review list"
+		}
+	];
+	return {
+		data,
+		human: renderReviewShow(data),
+		nextActions
+	};
+});
+const runReviewExport = Effect.fn("CLI.reviewExport")(function* runReviewExport(command) {
+	if (command.noResolved || command.noSnippets) yield* new CliFailure({
+		exitCode: ExitCode.UsageError,
+		message: "--no-resolved and --no-snippets are documented, but the shared export service does not support adapter-level filtering yet."
+	});
+	const exportService = yield* ExportService;
+	const cliConfig = yield* CliConfig;
+	const reviewId = yield* resolveReviewSelector(command.id);
+	const markdown = yield* exportService.exportReview(reviewId);
+	const outputPath = command.outputPath ? resolve(cliConfig.cwd, command.outputPath) : void 0;
+	if (outputPath) yield* Effect.tryPromise({
+		catch: (error) => new CliFailure({
+			exitCode: ExitCode.RuntimeFailure,
+			message: `Failed to write export to ${outputPath}: ${String(error)}`
+		}),
+		try: () => writeFile(outputPath, markdown, "utf8")
+	});
+	const shouldPrintMarkdown = command.stdout || !outputPath;
+	const data = {
+		markdown,
+		outputPath: outputPath ?? null,
+		reviewId
+	};
+	const nextActions = [{
+		command: `ringi review show ${reviewId}`,
+		description: "View the exported review"
+	}, {
+		command: "ringi review list",
+		description: "Back to review list"
+	}];
+	return {
+		data,
+		human: shouldPrintMarkdown ? markdown : `Exported review ${reviewId} to ${outputPath}.`,
+		nextActions
+	};
+});
+const runSourceList = Effect.fn("CLI.sourceList")(function* runSourceList() {
+	const gitService = yield* GitService;
+	const repo = yield* gitService.getRepositoryInfo;
+	const stagedFiles = yield* gitService.getStagedFiles;
+	const data = {
+		branches: yield* gitService.getBranches,
+		commits: (yield* gitService.getCommits({
+			limit: 10,
+			offset: 0
+		})).commits,
+		repo,
+		stagedFiles
+	};
+	return {
+		data,
+		human: renderSourceList(data),
+		nextActions: [
+			{
+				command: "ringi source diff <source> [--stat]",
+				description: "View diff for a source",
+				params: { source: { enum: [
+					"staged",
+					"branch",
+					"commits"
+				] } }
+			},
+			{
+				command: "ringi review create [--source <source>]",
+				description: "Create a review from a source",
+				params: { source: {
+					default: "staged",
+					enum: [
+						"staged",
+						"branch",
+						"commits"
+					]
+				} }
+			},
+			{
+				command: "ringi review list",
+				description: "List existing reviews"
+			}
+		]
+	};
+});
+const runSourceDiff = Effect.fn("CLI.sourceDiff")(function* runSourceDiff(command) {
+	const gitService = yield* GitService;
+	const strategy = diffSourceStrategies[command.source];
+	if (!strategy) return yield* new CliFailure({
+		exitCode: ExitCode.UsageError,
+		message: "Unsupported review source."
+	});
+	const diffText = yield* strategy(gitService, command);
+	if (!diffText.trim()) yield* new CliFailure({
+		exitCode: ExitCode.RuntimeFailure,
+		message: "No diff available for the requested source."
+	});
+	const files = parseDiff(diffText);
+	const data = {
+		diff: diffText,
+		source: command.source,
+		summary: getDiffSummary(files)
+	};
+	const nextActions = [{
+		command: `ringi review create --source ${command.source}`,
+		description: `Create a review from this ${command.source} diff`
+	}, {
+		command: "ringi source list",
+		description: "List repository sources"
+	}];
+	return {
+		data,
+		human: command.stat ? [
+			`Source: ${command.source}`,
+			`Files: ${data.summary.totalFiles}`,
+			`Additions: ${data.summary.totalAdditions}`,
+			`Deletions: ${data.summary.totalDeletions}`
+		].join("\n") : diffText,
+		nextActions
+	};
+});
+const runReviewStatus = Effect.fn("CLI.reviewStatus")(function* runReviewStatus(command) {
+	const reviewService = yield* ReviewService;
+	const todoService = yield* TodoService;
+	const commentService = yield* CommentService;
+	const gitService = yield* GitService;
+	const cliConfig = yield* CliConfig;
+	const repo = yield* gitService.getRepositoryInfo;
+	const stagedFiles = yield* gitService.getStagedFiles;
+	let reviewId;
+	if (command.reviewId) reviewId = yield* resolveReviewSelector(command.reviewId);
+	const reviews = yield* reviewService.list({
+		page: 1,
+		pageSize: 1,
+		repositoryPath: cliConfig.repoRoot,
+		sourceType: command.source
+	});
+	const latestReview = reviewId ? yield* reviewService.getById(reviewId) : reviews.reviews[0];
+	let commentStats;
+	let todoStats;
+	if (latestReview) {
+		commentStats = yield* commentService.getStats(latestReview.id);
+		todoStats = yield* todoService.getStats();
+	}
+	const data = {
+		commentStats: commentStats ?? null,
+		repository: {
+			branch: repo.branch,
+			name: repo.name,
+			path: repo.path,
+			stagedFileCount: stagedFiles.length
+		},
+		review: latestReview ? {
+			createdAt: latestReview.createdAt,
+			id: latestReview.id,
+			sourceType: latestReview.sourceType,
+			status: latestReview.status
+		} : null,
+		todoStats: todoStats ?? null
+	};
+	const lines = [
+		`Repository: ${repo.name}`,
+		`Branch: ${repo.branch}`,
+		`Staged files: ${stagedFiles.length}`
+	];
+	if (latestReview) {
+		lines.push("", `Review: ${latestReview.id}`, `Status: ${latestReview.status}`, `Source: ${latestReview.sourceType}`);
+		if (commentStats) lines.push(`Comments: ${commentStats.unresolved ?? 0} unresolved / ${commentStats.total} total`);
+		if (todoStats) lines.push(`Todos: ${todoStats.pending} pending / ${todoStats.total} total`);
+	} else lines.push("", "No review sessions found.");
+	const nextActions = [];
+	if (latestReview) nextActions.push({
+		command: `ringi review show ${latestReview.id} --comments --todos`,
+		description: "Inspect the latest review"
+	}, {
+		command: `ringi review export ${latestReview.id}`,
+		description: "Export the latest review"
+	});
+	nextActions.push({
+		command: "ringi review create [--source <source>]",
+		description: "Create a new review session",
+		params: { source: {
+			default: "staged",
+			enum: [
+				"staged",
+				"branch",
+				"commits"
+			]
+		} }
+	});
+	return {
+		data,
+		human: lines.join("\n"),
+		nextActions
+	};
+});
+const runTodoList = Effect.fn("CLI.todoList")(function* runTodoList(command) {
+	const result = yield* (yield* TodoService).list({
+		completed: command.status === "all" ? void 0 : command.status === "done",
+		limit: command.limit,
+		offset: command.offset,
+		reviewId: command.reviewId
+	});
+	const nextActions = [];
+	if (command.reviewId) nextActions.push({
+		command: `ringi review show ${command.reviewId}`,
+		description: "View the associated review"
+	});
+	nextActions.push({
+		command: "ringi todo add --text <text> [--review <review-id>]",
+		description: "Add a new todo",
+		params: { text: {
+			description: "Todo text",
+			required: true
+		} }
+	}, {
+		command: "ringi review list",
+		description: "List reviews"
+	});
+	return {
+		data: result,
+		human: renderTodoList(result.data),
+		nextActions
+	};
+});
+/**
+* Data-driven command registry. Each command kind maps to its handler.
+* Adding a new command means adding one entry — no switch duplication.
+*/
+const COMMAND_HANDLERS = {
+	"data-migrate": () => requireServerMode("ringi data migrate"),
+	"data-reset": () => requireServerMode("ringi data reset"),
+	doctor: () => Effect.succeed({
+		data: {
+			checks: [],
+			ok: true
+		},
+		human: "ringi doctor: not yet implemented.",
+		nextActions: []
+	}),
+	events: () => requireServerMode("ringi events"),
+	mcp: () => Effect.fail(new CliFailure({
+		exitCode: ExitCode.UsageError,
+		message: "ringi mcp is a runtime command. Use it directly, not through the command dispatcher."
+	})),
+	"review-create": () => requireServerMode("ringi review create"),
+	"review-export": (c) => runReviewExport(c),
+	"review-list": (c) => runReviewList(c),
+	"review-resolve": () => requireServerMode("ringi review resolve"),
+	"review-show": (c) => runReviewShow(c),
+	"review-status": (c) => runReviewStatus(c),
+	serve: () => Effect.fail(new CliFailure({
+		exitCode: ExitCode.UsageError,
+		message: "ringi serve is a runtime command. Use it directly, not through the command dispatcher."
+	})),
+	"source-diff": (c) => runSourceDiff(c),
+	"source-list": () => runSourceList(),
+	"todo-add": () => requireServerMode("ringi todo add"),
+	"todo-clear": () => requireServerMode("ringi todo clear"),
+	"todo-done": () => requireServerMode("ringi todo done"),
+	"todo-list": (c) => runTodoList(c),
+	"todo-move": () => requireServerMode("ringi todo move"),
+	"todo-remove": () => requireServerMode("ringi todo remove"),
+	"todo-undone": () => requireServerMode("ringi todo undone")
+};
+/** Human-readable command label for the JSON envelope `command` field. */
+const COMMAND_LABELS = {
+	"data-migrate": "ringi data migrate",
+	"data-reset": "ringi data reset",
+	doctor: "ringi doctor",
+	events: "ringi events",
+	mcp: "ringi mcp",
+	"review-create": "ringi review create",
+	"review-export": "ringi review export",
+	"review-list": "ringi review list",
+	"review-resolve": "ringi review resolve",
+	"review-show": "ringi review show",
+	"review-status": "ringi review status",
+	serve: "ringi serve",
+	"source-diff": "ringi source diff",
+	"source-list": "ringi source list",
+	"todo-add": "ringi todo add",
+	"todo-clear": "ringi todo clear",
+	"todo-done": "ringi todo done",
+	"todo-list": "ringi todo list",
+	"todo-move": "ringi todo move",
+	"todo-remove": "ringi todo remove",
+	"todo-undone": "ringi todo undone"
+};
+const commandLabel = (command) => COMMAND_LABELS[command.kind] ?? `ringi ${command.kind}`;
+const runCommand = (command) => {
+	const handler = COMMAND_HANDLERS[command.kind];
+	if (!handler) return Effect.fail(new CliFailure({
+		exitCode: ExitCode.UsageError,
+		message: `No executable handler exists for ${command.kind}.`
+	}));
+	return handler(command);
+};
+//#endregion
+//#region src/cli/parser.ts
+const REVIEW_SOURCES = new Set([
+	"branch",
+	"commits",
+	"staged"
+]);
+const REVIEW_STATUSES = new Set([
+	"approved",
+	"changes_requested",
+	"in_progress"
+]);
+const TODO_STATUSES = new Set([
+	"all",
+	"done",
+	"pending"
+]);
+const usageError = (message) => new CliFailure({
+	exitCode: ExitCode.UsageError,
+	message
+});
+/**
+* Consumes the next token as a flag value, advancing the cursor by 2.
+* Rejects another flag in the value slot so typos fail fast.
+*/
+const requireValue = (state, flag) => {
+	const value = state.tokens[state.index + 1];
+	if (!value || value.startsWith("-")) return Option.some(usageError(`Missing value for ${flag}.`));
+	state.index += 2;
+	return Option.none();
+};
+/** Peek at the value that {@link requireValue} would consume. */
+const peekValue = (state) => state.tokens[state.index + 1] ?? "";
+const decodePositiveInt = (raw, flag) => {
+	const value = Number.parseInt(raw, 10);
+	if (!Number.isInteger(value) || value < 0) return Either.left(usageError(`${flag} must be a non-negative integer.`));
+	return Either.right(value);
+};
+const decodeEnum = (raw, valid, label) => {
+	if (!valid.has(raw)) return Either.left(usageError(`Invalid ${label}: ${raw}.`));
+	return Either.right(raw);
+};
+/** Boolean flag: sets a key to `true`, advances cursor by 1. */
+const boolFlag = (key) => (state, acc) => {
+	acc[key] = true;
+	state.index += 1;
+	return Option.none();
+};
+/** String flag: consumes next token, assigns to key. */
+const stringFlag = (key) => (state, acc) => {
+	const flag = state.tokens[state.index] ?? "";
+	const value = peekValue(state);
+	const error = requireValue(state, flag);
+	if (Option.isSome(error)) return error;
+	acc[key] = value;
+	return Option.none();
+};
+/** Positive integer flag with an optional minimum (exclusive). */
+const positiveIntFlag = (key, opts) => (state, acc) => {
+	const flag = state.tokens[state.index] ?? "";
+	const raw = peekValue(state);
+	const error = requireValue(state, flag);
+	if (Option.isSome(error)) return error;
+	const decoded = decodePositiveInt(raw, flag);
+	if (Either.isLeft(decoded)) return Option.some(decoded.left);
+	if (opts?.min !== void 0 && decoded.right <= opts.min) return Option.some(usageError(`${flag} must be greater than ${opts.min}.`));
+	acc[key] = decoded.right;
+	return Option.none();
+};
+/** Enum flag: consumes next token, validates membership, assigns to key. */
+const enumFlag = (key, valid, label) => (state, acc) => {
+	const flag = state.tokens[state.index] ?? "";
+	const raw = peekValue(state);
+	const error = requireValue(state, flag);
+	if (Option.isSome(error)) return error;
+	const decoded = decodeEnum(raw, valid, label);
+	if (Either.isLeft(decoded)) return Option.some(decoded.left);
+	acc[key] = decoded.right;
+	return Option.none();
+};
+const createDefaultOptions = () => ({
+	color: true,
+	dbPath: void 0,
+	help: false,
+	json: false,
+	quiet: false,
+	repo: void 0,
+	verbose: false,
+	version: false
+});
+/**
+* Global flags are accepted before or after subcommands because wrappers often
+* prepend them without preserving the CLI's preferred ordering.
+*/
+const GLOBAL_FLAG_HANDLERS = {
+	"--db-path": stringFlag("dbPath"),
+	"--help": boolFlag("help"),
+	"--json": boolFlag("json"),
+	"--no-color": (state, acc) => {
+		acc.color = false;
+		state.index += 1;
+		return Option.none();
+	},
+	"--quiet": boolFlag("quiet"),
+	"--repo": stringFlag("repo"),
+	"--verbose": boolFlag("verbose"),
+	"--version": boolFlag("version")
+};
+const maybeParseGlobalFlag = (state) => {
+	const token = state.tokens[state.index];
+	if (!token) return false;
+	const handler = GLOBAL_FLAG_HANDLERS[token];
+	if (!handler) return false;
+	handler(state, state.options);
+	return true;
+};
+/**
+* Consumes all remaining tokens in {@link state} by dispatching to the matching
+* handler in {@link handlers}. Global flags are tried first. Unknown flags
+* produce a usage error naming the {@link commandLabel}.
+*/
+const runFlagLoop = (state, acc, handlers, commandLabel) => {
+	while (state.index < state.tokens.length) {
+		if (maybeParseGlobalFlag(state)) continue;
+		const token = state.tokens[state.index] ?? "";
+		const handler = handlers[token];
+		if (!handler) return Option.some(usageError(`Unknown flag for ${commandLabel}: ${token}.`));
+		const error = handler(state, acc);
+		if (Option.isSome(error)) return error;
+	}
+	return Option.none();
+};
+const REVIEW_LIST_FLAGS = {
+	"--limit": positiveIntFlag("limit", { min: 0 }),
+	"--page": positiveIntFlag("page", { min: 0 }),
+	"--source": enumFlag("source", REVIEW_SOURCES, "review source"),
+	"--status": enumFlag("status", REVIEW_STATUSES, "review status")
+};
+const parseReviewList = (state) => {
+	const acc = {
+		limit: 20,
+		page: 1,
+		source: void 0,
+		status: void 0
+	};
+	const error = runFlagLoop(state, acc, REVIEW_LIST_FLAGS, "review list");
+	if (Option.isSome(error)) return Either.left(error.value);
+	return Either.right({
+		kind: "review-list",
+		...acc
+	});
+};
+const REVIEW_SHOW_FLAGS = {
+	"--comments": boolFlag("comments"),
+	"--todos": boolFlag("todos")
+};
+const parseReviewShow = (state) => {
+	const id = state.tokens[state.index];
+	if (!id) return Either.left(usageError("review show requires <id|last>."));
+	state.index += 1;
+	const acc = {
+		comments: false,
+		todos: false
+	};
+	const error = runFlagLoop(state, acc, REVIEW_SHOW_FLAGS, "review show");
+	if (Option.isSome(error)) return Either.left(error.value);
+	return Either.right({
+		id,
+		kind: "review-show",
+		...acc
+	});
+};
+const REVIEW_EXPORT_FLAGS = {
+	"--no-resolved": boolFlag("noResolved"),
+	"--no-snippets": boolFlag("noSnippets"),
+	"--output": stringFlag("outputPath"),
+	"--stdout": boolFlag("stdout")
+};
+const parseReviewExport = (state) => {
+	const id = state.tokens[state.index];
+	if (!id) return Either.left(usageError("review export requires <id|last>."));
+	state.index += 1;
+	const acc = {
+		noResolved: false,
+		noSnippets: false,
+		outputPath: void 0,
+		stdout: false
+	};
+	const error = runFlagLoop(state, acc, REVIEW_EXPORT_FLAGS, "review export");
+	if (Option.isSome(error)) return Either.left(error.value);
+	return Either.right({
+		id,
+		kind: "review-export",
+		...acc
+	});
+};
+const REVIEW_CREATE_FLAGS = {
+	"--branch": stringFlag("branch"),
+	"--commits": stringFlag("commits"),
+	"--source": enumFlag("source", REVIEW_SOURCES, "review source"),
+	"--title": stringFlag("title")
+};
+const validateReviewCreate = (acc) => {
+	if (acc.source === "branch" && !acc.branch) return Option.some(usageError("review create --source branch requires --branch."));
+	if (acc.source === "commits" && !acc.commits) return Option.some(usageError("review create --source commits requires --commits."));
+	if (acc.source === "staged" && (acc.branch || acc.commits)) return Option.some(usageError("review create --source staged does not accept --branch or --commits."));
+	return Option.none();
+};
+const parseReviewCreate = (state) => {
+	const acc = {
+		branch: void 0,
+		commits: void 0,
+		source: "staged",
+		title: void 0
+	};
+	const error = runFlagLoop(state, acc, REVIEW_CREATE_FLAGS, "review create");
+	if (Option.isSome(error)) return Either.left(error.value);
+	const validationError = validateReviewCreate(acc);
+	if (Option.isSome(validationError)) return Either.left(validationError.value);
+	return Either.right({
+		kind: "review-create",
+		...acc
+	});
+};
+const SOURCE_DIFF_FLAGS = {
+	"--branch": stringFlag("branch"),
+	"--commits": stringFlag("commits"),
+	"--stat": boolFlag("stat")
+};
+const validateSourceDiff = (source, acc) => {
+	if (source === "branch" && !acc.branch) return Option.some(usageError("source diff branch requires --branch."));
+	if (source === "commits" && !acc.commits) return Option.some(usageError("source diff commits requires --commits."));
+	return Option.none();
+};
+const parseSourceDiff = (state) => {
+	const source = state.tokens[state.index];
+	if (!source || !REVIEW_SOURCES.has(source)) return Either.left(usageError("source diff requires <staged|branch|commits>."));
+	state.index += 1;
+	const acc = {
+		branch: void 0,
+		commits: void 0,
+		stat: false
+	};
+	const error = runFlagLoop(state, acc, SOURCE_DIFF_FLAGS, "source diff");
+	if (Option.isSome(error)) return Either.left(error.value);
+	const validationError = validateSourceDiff(source, acc);
+	if (Option.isSome(validationError)) return Either.left(validationError.value);
+	return Either.right({
+		kind: "source-diff",
+		source,
+		...acc
+	});
+};
+const TODO_LIST_FLAGS = {
+	"--limit": positiveIntFlag("limit"),
+	"--offset": positiveIntFlag("offset"),
+	"--review": stringFlag("reviewId"),
+	"--status": enumFlag("status", TODO_STATUSES, "todo status")
+};
+const parseTodoList = (state) => {
+	const acc = {
+		limit: void 0,
+		offset: 0,
+		reviewId: void 0,
+		status: "pending"
+	};
+	const error = runFlagLoop(state, acc, TODO_LIST_FLAGS, "todo list");
+	if (Option.isSome(error)) return Either.left(error.value);
+	return Either.right({
+		kind: "todo-list",
+		...acc
+	});
+};
+/**
+* Factory for commands that take exactly one positional `<id>` and no
+* command-specific flags (only globals). Avoids duplication for done/undone.
+*/
+const positionalIdParser = (kind, label) => (state) => {
+	const id = state.tokens[state.index];
+	if (!id) return Either.left(usageError(`${label} requires <id>.`));
+	state.index += 1;
+	while (state.index < state.tokens.length) if (!maybeParseGlobalFlag(state)) return Either.left(usageError(`Unknown flag for ${label}: ${state.tokens[state.index]}.`));
+	return Either.right({
+		id,
+		kind
+	});
+};
+const parseTodoDone = positionalIdParser("todo-done", "todo done");
+const parseTodoUndone = positionalIdParser("todo-undone", "todo undone");
+const TODO_MOVE_FLAGS = { "--position": positiveIntFlag("position") };
+const parseTodoMove = (state) => {
+	const id = state.tokens[state.index];
+	if (!id) return Either.left(usageError("todo move requires <id>."));
+	state.index += 1;
+	const acc = { position: void 0 };
+	const error = runFlagLoop(state, acc, TODO_MOVE_FLAGS, "todo move");
+	if (Option.isSome(error)) return Either.left(error.value);
+	if (acc.position === void 0) return Either.left(usageError("todo move requires --position."));
+	return Either.right({
+		id,
+		kind: "todo-move",
+		position: acc.position
+	});
+};
+const TODO_REMOVE_FLAGS = { "--yes": boolFlag("yes") };
+const parseTodoRemove = (state) => {
+	const id = state.tokens[state.index];
+	if (!id) return Either.left(usageError("todo remove requires <id>."));
+	state.index += 1;
+	const acc = { yes: false };
+	const error = runFlagLoop(state, acc, TODO_REMOVE_FLAGS, "todo remove");
+	if (Option.isSome(error)) return Either.left(error.value);
+	return Either.right({
+		id,
+		kind: "todo-remove",
+		...acc
+	});
+};
+const TODO_CLEAR_FLAGS = {
+	"--all": boolFlag("all"),
+	"--done-only": boolFlag("doneOnly"),
+	"--review": stringFlag("reviewId"),
+	"--yes": boolFlag("yes")
+};
+const parseTodoClear = (state) => {
+	const acc = {
+		all: false,
+		doneOnly: true,
+		reviewId: void 0,
+		yes: false
+	};
+	const error = runFlagLoop(state, acc, TODO_CLEAR_FLAGS, "todo clear");
+	if (Option.isSome(error)) return Either.left(error.value);
+	return Either.right({
+		kind: "todo-clear",
+		...acc
+	});
+};
+const REVIEW_STATUS_FLAGS = {
+	"--review": stringFlag("reviewId"),
+	"--source": enumFlag("source", REVIEW_SOURCES, "review source")
+};
+const parseReviewStatus = (state) => {
+	const acc = {
+		reviewId: void 0,
+		source: void 0
+	};
+	const error = runFlagLoop(state, acc, REVIEW_STATUS_FLAGS, "review status");
+	if (Option.isSome(error)) return Either.left(error.value);
+	return Either.right({
+		kind: "review-status",
+		...acc
+	});
+};
+const REVIEW_RESOLVE_FLAGS = {
+	"--all-comments": boolFlag("allComments"),
+	"--yes": boolFlag("yes")
+};
+const parseReviewResolve = (state) => {
+	const id = state.tokens[state.index];
+	if (!id) return Either.left(usageError("review resolve requires <id|last>."));
+	state.index += 1;
+	const acc = {
+		allComments: true,
+		yes: false
+	};
+	const error = runFlagLoop(state, acc, REVIEW_RESOLVE_FLAGS, "review resolve");
+	if (Option.isSome(error)) return Either.left(error.value);
+	return Either.right({
+		id,
+		kind: "review-resolve",
+		...acc
+	});
+};
+const TODO_ADD_FLAGS = {
+	"--position": positiveIntFlag("position"),
+	"--review": stringFlag("reviewId"),
+	"--text": stringFlag("text")
+};
+const parseTodoAdd = (state) => {
+	const acc = {
+		position: void 0,
+		reviewId: void 0,
+		text: ""
+	};
+	const error = runFlagLoop(state, acc, TODO_ADD_FLAGS, "todo add");
+	if (Option.isSome(error)) return Either.left(error.value);
+	if (!acc.text.trim()) return Either.left(usageError("todo add requires --text."));
+	return Either.right({
+		kind: "todo-add",
+		...acc
+	});
+};
+const SERVE_FLAGS = {
+	"--auth": boolFlag("auth"),
+	"--cert": stringFlag("cert"),
+	"--host": stringFlag("host"),
+	"--https": boolFlag("https"),
+	"--key": stringFlag("key"),
+	"--no-open": boolFlag("noOpen"),
+	"--password": stringFlag("password"),
+	"--port": positiveIntFlag("port", { min: 0 }),
+	"--username": stringFlag("username")
+};
+const parseServe = (state) => {
+	const acc = {
+		auth: false,
+		cert: void 0,
+		host: "127.0.0.1",
+		https: false,
+		key: void 0,
+		noOpen: false,
+		password: void 0,
+		port: 3e3,
+		username: void 0
+	};
+	const error = runFlagLoop(state, acc, SERVE_FLAGS, "serve");
+	if (Option.isSome(error)) return Either.left(error.value);
+	return Either.right({
+		kind: "serve",
+		...acc
+	});
+};
+const MCP_LOG_LEVELS = new Set([
+	"debug",
+	"error",
+	"info",
+	"silent"
+]);
+const MCP_FLAGS = {
+	"--log-level": enumFlag("logLevel", MCP_LOG_LEVELS, "log level"),
+	"--readonly": boolFlag("readonly")
+};
+const parseMcp = (state) => {
+	const acc = {
+		logLevel: "error",
+		readonly: false
+	};
+	const error = runFlagLoop(state, acc, MCP_FLAGS, "mcp");
+	if (Option.isSome(error)) return Either.left(error.value);
+	return Either.right({
+		kind: "mcp",
+		...acc
+	});
+};
+const EVENT_TYPES = new Set([
+	"comments",
+	"files",
+	"reviews",
+	"todos"
+]);
+const EVENTS_FLAGS = {
+	"--since": positiveIntFlag("since"),
+	"--type": enumFlag("type", EVENT_TYPES, "event type")
+};
+const parseEvents = (state) => {
+	const acc = {
+		since: void 0,
+		type: void 0
+	};
+	const error = runFlagLoop(state, acc, EVENTS_FLAGS, "events");
+	if (Option.isSome(error)) return Either.left(error.value);
+	return Either.right({
+		kind: "events",
+		...acc
+	});
+};
+const DATA_RESET_FLAGS = {
+	"--keep-exports": boolFlag("keepExports"),
+	"--yes": boolFlag("yes")
+};
+const parseDataReset = (state) => {
+	const acc = {
+		keepExports: false,
+		yes: false
+	};
+	const error = runFlagLoop(state, acc, DATA_RESET_FLAGS, "data reset");
+	if (Option.isSome(error)) return Either.left(error.value);
+	return Either.right({
+		kind: "data-reset",
+		...acc
+	});
+};
+const ensureNoExtraArgs = (state, label) => {
+	if (state.index < state.tokens.length) return Option.some(usageError(`Unexpected argument for ${label}: ${state.tokens[state.index]}.`));
+	return Option.none();
+};
+/** Review verb parsers keyed by verb name. */
+const REVIEW_VERB_PARSERS = {
+	create: parseReviewCreate,
+	export: parseReviewExport,
+	list: parseReviewList,
+	resolve: parseReviewResolve,
+	show: parseReviewShow,
+	status: parseReviewStatus
+};
+/** Todo verb parsers keyed by verb name. */
+const TODO_VERB_PARSERS = {
+	add: parseTodoAdd,
+	clear: parseTodoClear,
+	done: parseTodoDone,
+	list: parseTodoList,
+	move: parseTodoMove,
+	remove: parseTodoRemove,
+	undone: parseTodoUndone
+};
+/** Subcommand family parsers keyed by family name. */
+/** Data verb parsers keyed by verb name. */
+const DATA_VERB_PARSERS = {
+	migrate: (state) => {
+		const error = ensureNoExtraArgs(state, "data migrate");
+		if (Option.isSome(error)) return Either.left(error.value);
+		return Either.right({ kind: "data-migrate" });
+	},
+	reset: parseDataReset
+};
+/** Subcommand family parsers keyed by family name. */
+const FAMILY_PARSERS = {
+	data: (state) => {
+		const verb = state.tokens[state.index];
+		if (!verb) return Either.right({
+			kind: "help",
+			topic: ["data"]
+		});
+		state.index += 1;
+		const parser = DATA_VERB_PARSERS[verb];
+		if (!parser) return Either.left(usageError(`Unknown data command: ${verb}.`));
+		return parser(state);
+	},
+	doctor: (state) => {
+		const error = ensureNoExtraArgs(state, "doctor");
+		if (Option.isSome(error)) return Either.left(error.value);
+		return Either.right({ kind: "doctor" });
+	},
+	events: parseEvents,
+	export: parseReviewExport,
+	mcp: parseMcp,
+	review: (state) => {
+		const verb = state.tokens[state.index];
+		if (!verb) return Either.right({
+			kind: "help",
+			topic: ["review"]
+		});
+		state.index += 1;
+		const parser = REVIEW_VERB_PARSERS[verb];
+		if (!parser) return Either.left(usageError(`Unknown review command: ${verb}.`));
+		return parser(state);
+	},
+	serve: parseServe,
+	source: (state) => {
+		const verb = state.tokens[state.index];
+		if (!verb) return Either.right({
+			kind: "help",
+			topic: ["source"]
+		});
+		state.index += 1;
+		if (verb === "list") {
+			const error = ensureNoExtraArgs(state, "source list");
+			if (Option.isSome(error)) return Either.left(error.value);
+			return Either.right({ kind: "source-list" });
+		}
+		if (verb === "diff") return parseSourceDiff(state);
+		return Either.left(usageError(`Unknown source command: ${verb}.`));
+	},
+	todo: (state) => {
+		const verb = state.tokens[state.index];
+		if (!verb) return Either.right({
+			kind: "help",
+			topic: ["todo"]
+		});
+		state.index += 1;
+		const parser = TODO_VERB_PARSERS[verb];
+		if (!parser) return Either.left(usageError(`Unknown todo command: ${verb}.`));
+		return parser(state);
+	}
+};
+/**
+* Strips any leading globals with {@link maybeParseGlobalFlag} before dispatching
+* into a command family so `--help` and `--version` behave consistently.
+*/
+const parseWithState = (state) => {
+	while (state.index < state.tokens.length && maybeParseGlobalFlag(state));
+	if (state.options.version) return Either.right({ kind: "version" });
+	if (state.index >= state.tokens.length) return Either.right({
+		kind: "help",
+		topic: []
+	});
+	const first = state.tokens[state.index];
+	if (!first) return Either.right({
+		kind: "help",
+		topic: []
+	});
+	if (first === "help") {
+		const topic = state.tokens.slice(state.index + 1);
+		state.index = state.tokens.length;
+		return Either.right({
+			kind: "help",
+			topic
+		});
+	}
+	if (state.options.help) return Either.right({
+		kind: "help",
+		topic: state.tokens.slice(state.index)
+	});
+	state.index += 1;
+	const familyParser = FAMILY_PARSERS[first];
+	if (!familyParser) return Either.left(usageError(`Unknown command: ${first}.`));
+	return familyParser(state);
+};
+const parseCliArgs = (argv) => {
+	const options = createDefaultOptions();
+	const result = parseWithState({
+		index: 0,
+		options,
+		tokens: argv
+	});
+	if (Either.isLeft(result)) return Either.left(result.left);
+	return Either.right({
+		command: result.right,
+		options
+	});
+};
+//#endregion
+//#region src/cli/runtime.ts
+/**
+* Resolves the repository root up front so every later git and database path is
+* anchored to the same directory, even when the user invoked the CLI elsewhere.
+*
+* NOTE: This uses execFileSync intentionally — it runs once at CLI startup
+* before the Effect runtime is constructed, so there is no fiber to block.
+* Moving this into the Effect runtime would create a circular dependency
+* (config → git → config).
+*/
+const resolveRepositoryRoot = (repoOverride) => {
+	const cwd = repoOverride ? resolve(repoOverride) : process.cwd();
+	try {
+		return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+			cwd,
+			encoding: "utf8"
+		}).trim();
+	} catch {
+		return new CliFailure({
+			exitCode: ExitCode.StateUnavailable,
+			message: repoOverride ? `Path ${cwd} is not a Git repository. Use --repo <path> with a valid repository root.` : `Could not resolve a Git repository from ${cwd}. Use --repo <path> with a valid repository root.`
+		});
+	}
+};
+const resolveDbPath = (repoRoot, dbPathOverride) => dbPathOverride ? resolve(dbPathOverride) : resolve(repoRoot, ".ringi/reviews.db");
+const commandNeedsRepository = (command) => command.kind !== "help" && command.kind !== "version" && command.kind !== "mcp" && command.kind !== "serve";
+const commandNeedsDatabase = (command) => command.kind === "review-list" || command.kind === "review-show" || command.kind === "review-export" || command.kind === "review-status" || command.kind === "todo-list" || command.kind === "doctor";
+const commandUsesCoreRuntime = (command) => command.kind === "review-list" || command.kind === "review-show" || command.kind === "review-export" || command.kind === "review-status" || command.kind === "todo-list" || command.kind === "review-create" || command.kind === "todo-add" || command.kind === "doctor";
+const resolveCliConfig = (args) => {
+	const repoRootResult = resolveRepositoryRoot(args.repo);
+	if (repoRootResult instanceof CliFailure) return repoRootResult;
+	return {
+		color: args.color,
+		cwd: process.cwd(),
+		dbPath: resolveDbPath(repoRootResult, args.dbPath),
+		outputMode: "human",
+		quiet: args.quiet,
+		repoRoot: repoRootResult,
+		verbose: args.verbose
+	};
+};
+/**
+* Read-only commands still depend on initialized local state because the shared
+* services use the same database-backed storage as the other clients.
+*/
+const ensureLocalStateAvailable = (config) => {
+	if (!existsSync(config.dbPath)) return new CliFailure({
+		exitCode: ExitCode.StateUnavailable,
+		message: `Local state is missing at ${config.dbPath}. Run 'ringi data migrate' or start 'ringi serve' once to initialize local state.`
+	});
+};
+const makeConfigLayer = (config) => Layer.setConfigProvider(ConfigProvider.fromMap(new Map([["DB_PATH", config.dbPath], ["REPOSITORY_PATH", config.repoRoot]])));
+const createCoreCliRuntime = (config) => ManagedRuntime.make(Layer.mergeAll(CoreLive, CliConfigLive(config)).pipe(Layer.provideMerge(makeConfigLayer(config))));
+const createGitCliRuntime = (config) => ManagedRuntime.make(Layer.mergeAll(GitService.Default, CliConfigLive(config)).pipe(Layer.provideMerge(makeConfigLayer(config))));
+/**
+* Centralizes runtime selection. Returns either valid resources or a CliFailure.
+* Returns null for help/version commands that don't need a runtime.
+*/
+const createCliRuntimeResources = (command, args) => {
+	if (!commandNeedsRepository(command)) return null;
+	const configResult = resolveCliConfig(args);
+	if (configResult instanceof CliFailure) return configResult;
+	if (commandNeedsDatabase(command)) {
+		const stateError = ensureLocalStateAvailable(configResult);
+		if (stateError) return stateError;
+	}
+	return {
+		config: configResult,
+		runtime: commandUsesCoreRuntime(command) ? createCoreCliRuntime(configResult) : createGitCliRuntime(configResult)
+	};
+};
+//#endregion
+//#region src/cli/main.ts
+const CLI_VERSION = "0.2.1";
+const COMMAND_TREE = {
+	commands: [
+		{
+			description: "List review sessions",
+			name: "review list",
+			usage: "ringi review list [--status <status>] [--source <type>] [--limit <n>] [--page <n>]"
+		},
+		{
+			description: "Show review details",
+			name: "review show",
+			usage: "ringi review show <id|last> [--comments] [--todos]"
+		},
+		{
+			description: "Create a review session",
+			name: "review create",
+			usage: "ringi review create [--source <staged|branch|commits>] [--branch <name>] [--commits <range>]"
+		},
+		{
+			description: "Export review as markdown",
+			name: "review export",
+			usage: "ringi review export <id|last> [--output <path>] [--stdout]"
+		},
+		{
+			description: "Resolve a review session",
+			name: "review resolve",
+			usage: "ringi review resolve <id|last> [--all-comments] [--yes]"
+		},
+		{
+			description: "Show repository and review status",
+			name: "review status",
+			usage: "ringi review status [--review <id|last>] [--source <type>]"
+		},
+		{
+			description: "List repository sources",
+			name: "source list",
+			usage: "ringi source list"
+		},
+		{
+			description: "Show diff for a source",
+			name: "source diff",
+			usage: "ringi source diff <staged|branch|commits> [--branch <name>] [--commits <range>] [--stat]"
+		},
+		{
+			description: "List todo items",
+			name: "todo list",
+			usage: "ringi todo list [--review <id>] [--status <pending|done|all>] [--limit <n>] [--offset <n>]"
+		},
+		{
+			description: "Add a todo item",
+			name: "todo add",
+			usage: "ringi todo add --text <text> [--review <id>] [--position <n>]"
+		},
+		{
+			description: "Mark a todo as done",
+			name: "todo done",
+			usage: "ringi todo done <id>"
+		},
+		{
+			description: "Reopen a completed todo",
+			name: "todo undone",
+			usage: "ringi todo undone <id>"
+		},
+		{
+			description: "Move a todo to a position",
+			name: "todo move",
+			usage: "ringi todo move <id> --position <n>"
+		},
+		{
+			description: "Remove a todo",
+			name: "todo remove",
+			usage: "ringi todo remove <id> [--yes]"
+		},
+		{
+			description: "Clear completed todos",
+			name: "todo clear",
+			usage: "ringi todo clear [--review <id>] [--done-only] [--all] [--yes]"
+		},
+		{
+			description: "Start the local Ringi server",
+			name: "serve",
+			usage: "ringi serve [--host <host>] [--port <port>] [--https] [--auth] [--no-open]"
+		},
+		{
+			description: "Start the MCP stdio server",
+			name: "mcp",
+			usage: "ringi mcp [--readonly] [--log-level <level>]"
+		},
+		{
+			description: "Run local diagnostics",
+			name: "doctor",
+			usage: "ringi doctor"
+		},
+		{
+			description: "Tail server events",
+			name: "events",
+			usage: "ringi events [--type <reviews|comments|todos|files>]"
+		},
+		{
+			description: "Run database migrations",
+			name: "data migrate",
+			usage: "ringi data migrate"
+		},
+		{
+			description: "Reset local data",
+			name: "data reset",
+			usage: "ringi data reset [--yes] [--keep-exports]"
+		}
+	],
+	description: "ringi — local-first code review CLI",
+	version: CLI_VERSION
+};
+const ROOT_NEXT_ACTIONS = [
+	{
+		command: "ringi review list [--status <status>] [--source <type>]",
+		description: "List review sessions",
+		params: {
+			source: { enum: [
+				"staged",
+				"branch",
+				"commits"
+			] },
+			status: { enum: [
+				"in_progress",
+				"approved",
+				"changes_requested"
+			] }
+		}
+	},
+	{
+		command: "ringi source list",
+		description: "List repository sources"
+	},
+	{
+		command: "ringi review create [--source <source>]",
+		description: "Create a new review session",
+		params: { source: {
+			default: "staged",
+			enum: [
+				"staged",
+				"branch",
+				"commits"
+			]
+		} }
+	},
+	{
+		command: "ringi todo list [--status <status>]",
+		description: "List todos",
+		params: { status: {
+			default: "pending",
+			enum: [
+				"pending",
+				"done",
+				"all"
+			]
+		} }
+	},
+	{
+		command: "ringi review status",
+		description: "Show repository and review status"
+	}
+];
+const ROOT_HELP = `ringi — local-first review CLI
+
+Usage:
+  ringi [global options] <command>
+
+Global options:
+  --json            Emit structured JSON envelope to stdout
+  --repo <path>     Use a specific Git repository root
+  --db-path <path>  Override the SQLite database path
+  --quiet           Suppress human-readable success output
+  --verbose         Include stack traces on failures
+  --no-color        Disable ANSI color output
+  --help            Show help
+  --version         Show version
+
+Commands:
+  review list [--status <status>] [--source <type>] [--limit <n>] [--page <n>]
+  review show <id|last> [--comments] [--todos]
+  review create [--source <staged|branch|commits>] [--branch <name>] [--commits <range>]
+  review export <id|last> [--output <path>] [--stdout]
+  review resolve <id|last> [--all-comments] [--yes]
+  review status [--review <id|last>] [--source <type>]
+  source list
+  source diff <staged|branch|commits> [--branch <name>] [--commits <range>] [--stat]
+  todo list [--review <id>] [--status <pending|done|all>] [--limit <n>] [--offset <n>]
+  todo add --text <text> [--review <id>]
+  todo done <id>
+  todo undone <id>
+  todo move <id> --position <n>
+  todo remove <id> [--yes]
+  todo clear [--review <id>] [--done-only] [--all] [--yes]
+  export <id|last> [--output <path>] [--stdout]
+`;
+const HELP_TOPICS = {
+	data: `ringi data
+
+Usage:
+  ringi data migrate
+  ringi data reset [--yes] [--keep-exports]
+`,
+	review: `ringi review
+
+Usage:
+  ringi review list [--status <status>] [--source <type>] [--limit <n>] [--page <n>]
+  ringi review show <id|last> [--comments] [--todos]
+  ringi review create [--source <staged|branch|commits>] [--branch <name>] [--commits <range>]
+  ringi review export <id|last> [--output <path>] [--stdout]
+  ringi review resolve <id|last> [--all-comments] [--yes]
+  ringi review status [--review <id|last>] [--source <type>]
+`,
+	source: `ringi source
+
+Usage:
+  ringi source list
+  ringi source diff <staged|branch|commits> [--branch <name>] [--commits <range>] [--stat]
+`,
+	todo: `ringi todo
+
+Usage:
+  ringi todo list [--review <id>] [--status <pending|done|all>] [--limit <n>] [--offset <n>]
+  ringi todo add --text <text> [--review <id>] [--position <n>]
+  ringi todo done <id>
+  ringi todo undone <id>
+  ringi todo move <id> --position <n>
+  ringi todo remove <id> [--yes]
+  ringi todo clear [--review <id>] [--done-only] [--all] [--yes]
+`
+};
+const renderHelp = (command) => {
+	if (command.kind !== "help") return ROOT_HELP;
+	const [topic] = command.topic;
+	return (topic && HELP_TOPICS[topic]) ?? ROOT_HELP;
+};
+const writeJson = (payload) => {
+	process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+};
+const writeHuman = (text) => {
+	if (text && text.length > 0) process.stdout.write(`${text}\n`);
+};
+/** Maps exit codes to error categories and retryable status. */
+const EXIT_CODE_META = {
+	[ExitCode.AuthFailure]: {
+		category: "auth",
+		code: "AUTH_FAILURE",
+		retryable: false
+	},
+	[ExitCode.ResourceNotFound]: {
+		category: "not_found",
+		code: "RESOURCE_NOT_FOUND",
+		retryable: false
+	},
+	[ExitCode.RuntimeFailure]: {
+		category: "server",
+		code: "RUNTIME_FAILURE",
+		retryable: true
+	},
+	[ExitCode.StateUnavailable]: {
+		category: "config",
+		code: "STATE_UNAVAILABLE",
+		retryable: false
+	},
+	[ExitCode.UsageError]: {
+		category: "validation",
+		code: "USAGE_ERROR",
+		retryable: false
+	}
+};
+const mapFailure = (error) => {
+	if (error instanceof CliFailure) {
+		const meta = EXIT_CODE_META[error.exitCode] ?? {
+			category: "server",
+			code: "UNKNOWN",
+			retryable: false
+		};
+		return {
+			category: meta.category,
+			code: meta.code,
+			exitCode: error.exitCode,
+			message: error.message,
+			retryable: meta.retryable,
+			verbose: error.details
+		};
+	}
+	if (error instanceof ReviewNotFound || error instanceof TodoNotFound) return {
+		category: "not_found",
+		code: "RESOURCE_NOT_FOUND",
+		exitCode: ExitCode.ResourceNotFound,
+		message: error.message,
+		retryable: false,
+		verbose: error.stack
+	};
+	if (error instanceof Error) return {
+		category: "server",
+		code: "RUNTIME_FAILURE",
+		exitCode: ExitCode.RuntimeFailure,
+		message: error.message,
+		retryable: true,
+		verbose: error.stack
+	};
+	return {
+		category: "server",
+		code: "UNKNOWN_FAILURE",
+		exitCode: ExitCode.RuntimeFailure,
+		message: "Unknown CLI failure.",
+		retryable: false
+	};
+};
+/** Actionable fix guidance based on error category. */
+const FIX_GUIDANCE = {
+	auth: "Check authentication credentials or run 'ringi serve --auth' with valid credentials.",
+	config: "Run 'ringi serve' once to initialize local state, or check --repo and --db-path flags.",
+	conflict: "Resolve the conflict and retry the operation.",
+	connection: "Ensure the Ringi server is running: ringi serve",
+	not_found: "Verify the resource ID. Use 'ringi review list' or 'ringi todo list' to find valid IDs.",
+	server: "Retry the command. If the error persists, check 'ringi serve' logs.",
+	validation: "Check command usage with 'ringi --help'. Verify flag names and values."
+};
+/** Build recovery next_actions based on error category. */
+const errorNextActions = (commandStr, normalized) => {
+	const actions = [];
+	if (normalized.retryable) actions.push({
+		command: commandStr,
+		description: "Retry the failed command"
+	});
+	if (normalized.category === "config" || normalized.category === "connection") actions.push({
+		command: "ringi serve",
+		description: "Start the local Ringi server"
+	});
+	if (normalized.category === "not_found") actions.push({
+		command: "ringi review list",
+		description: "List available reviews"
+	}, {
+		command: "ringi todo list",
+		description: "List available todos"
+	});
+	if (normalized.category === "validation") actions.push({
+		command: `${commandStr.split(" ").slice(0, 3).join(" ")} --help`,
+		description: "Show command usage"
+	});
+	return actions;
+};
+/** Build a full error envelope from a normalized failure. */
+const buildErrorEnvelope = (commandStr, normalized) => {
+	return failure(commandStr, {
+		category: normalized.category,
+		code: normalized.code,
+		message: normalized.message,
+		retryable: normalized.retryable,
+		type: `ringi://errors/${normalized.code}`
+	}, normalized.verbose ?? FIX_GUIDANCE[normalized.category], errorNextActions(commandStr, normalized));
+};
+const installSignalHandlers = (dispose) => {
+	const shutdown = async () => {
+		await dispose();
+		process.exit(ExitCode.RuntimeFailure);
+	};
+	process.once("SIGINT", shutdown);
+	process.once("SIGTERM", shutdown);
+	return () => {
+		process.off("SIGINT", shutdown);
+		process.off("SIGTERM", shutdown);
+	};
+};
+/**
+* Resolves the built Nitro server entry point. Returns the absolute path to
+* `.output/server/index.mjs` relative to the package root (the directory
+* containing this CLI entry point after bundling).
+*/
+const resolveServerEntry = () => {
+	const candidates = [resolve(process.cwd(), ".output", "server", "index.mjs")];
+	if (import.meta.dirname) candidates.push(resolve(import.meta.dirname, "..", ".output", "server", "index.mjs"));
+	return candidates.find((candidate) => existsSync(candidate));
+};
+const runServe = (command) => {
+	const serverEntry = resolveServerEntry();
+	if (!serverEntry) {
+		process.stderr.write("No built server found. Run 'pnpm build' first, then retry 'ringi serve'.\n");
+		process.exit(ExitCode.RuntimeFailure);
+	}
+	const env = {
+		...process.env,
+		NITRO_HOST: command.host,
+		NITRO_PORT: String(command.port)
+	};
+	if (command.https && command.cert && command.key) {
+		env.NITRO_SSL_CERT = command.cert;
+		env.NITRO_SSL_KEY = command.key;
+	}
+	const url = `${command.https ? "https" : "http"}://${command.host === "0.0.0.0" ? "localhost" : command.host}:${command.port}`;
+	process.stderr.write(`ringi server starting on ${url}\n`);
+	const child = fork(serverEntry, [], {
+		env,
+		execArgv: [],
+		stdio: "inherit"
+	});
+	if (!command.noOpen) setTimeout(() => {
+		let openCmd = "xdg-open";
+		if (process.platform === "darwin") openCmd = "open";
+		else if (process.platform === "win32") openCmd = "start";
+		exec(`${openCmd} ${url}`, () => {});
+	}, 1500);
+	const shutdown = () => {
+		child.kill("SIGTERM");
+	};
+	process.once("SIGINT", shutdown);
+	process.once("SIGTERM", shutdown);
+	child.on("exit", (code) => {
+		process.off("SIGINT", shutdown);
+		process.off("SIGTERM", shutdown);
+		process.exit(code ?? ExitCode.Success);
+	});
+};
+/** Single path for all CLI error exits. */
+const failAndExit = (opts) => {
+	const normalized = mapFailure(opts.error);
+	if (opts.json) writeJson(buildErrorEnvelope(opts.cmdStr, normalized));
+	process.stderr.write(`${normalized.message}\n`);
+	if (opts.verbose && normalized.verbose) process.stderr.write(`${normalized.verbose}\n`);
+	return process.exit(normalized.exitCode);
+};
+const main = async () => {
+	const argv = process.argv.slice(2);
+	const parseResult = parseCliArgs(argv);
+	if (Either.isLeft(parseResult)) return failAndExit({
+		cmdStr: "ringi",
+		error: parseResult.left,
+		json: argv.includes("--json"),
+		verbose: false
+	});
+	const { command, options } = parseResult.right;
+	if (command.kind === "help") {
+		if (options.json) writeJson(success("ringi", COMMAND_TREE, ROOT_NEXT_ACTIONS));
+		else writeHuman(renderHelp(command));
+		process.exit(ExitCode.Success);
+	}
+	if (command.kind === "version") {
+		if (options.json) writeJson(success("ringi --version", { version: CLI_VERSION }));
+		else writeHuman(CLI_VERSION);
+		process.exit(ExitCode.Success);
+	}
+	if (command.kind === "serve") {
+		runServe(command);
+		return;
+	}
+	const runtimeResources = createCliRuntimeResources(command, {
+		color: options.color,
+		dbPath: options.dbPath,
+		quiet: options.quiet,
+		repo: options.repo,
+		verbose: options.verbose
+	});
+	if (runtimeResources === null) process.exit(ExitCode.Success);
+	const cmdStr = commandLabel(command);
+	if (runtimeResources instanceof CliFailure) return failAndExit({
+		cmdStr,
+		error: runtimeResources,
+		json: options.json,
+		verbose: options.verbose
+	});
+	const removeSignalHandlers = installSignalHandlers(() => runtimeResources.runtime.dispose());
+	try {
+		const output = await runtimeResources.runtime.runPromise(runCommand(command));
+		if (options.json) writeJson(success(cmdStr, output.data, output.nextActions ?? []));
+		else if (!options.quiet) writeHuman(output.human);
+		await runtimeResources.runtime.dispose();
+		removeSignalHandlers();
+		process.exit(ExitCode.Success);
+	} catch (error) {
+		await runtimeResources.runtime.dispose();
+		removeSignalHandlers();
+		failAndExit({
+			cmdStr,
+			error,
+			json: options.json,
+			verbose: options.verbose
+		});
+	}
+};
+try {
+	await main();
+} catch (error) {
+	failAndExit({
+		cmdStr: "ringi",
+		error,
+		json: process.argv.slice(2).includes("--json"),
+		verbose: false
+	});
+}
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.mjs.map