@sanurb/ringi 0.3.1 → 0.3.3

package/dist/cli.mjs

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
-import { a as ReviewService, c as ReviewFileRepo, d as parseDiff, f as CommentService, g as ReviewNotFound, i as TodoService, l as serializeHunks, m as TodoNotFound, n as GhService, o as GitService, r as ExportService, s as ReviewRepo, t as CoreLive, u as getDiffSummary } from "./runtime.mjs";
+import { c as getDiffSummary, h as serializeHunks, i as TodoService, l as parseDiff, m as ReviewFileRepo, n as GhService, o as ReviewService, p as ReviewRepo, r as ExportService, s as GitService, t as CoreLive, u as CommentService } from "./runtime.mjs";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import * as Effect from "effect/Effect";
+import { Argument, Command, Flag, GlobalFlag } from "effect/unstable/cli";
 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 Result from "effect/Result";
 import { writeFile } from "node:fs/promises";
-import { ServiceMap } from "effect";
-import * as Effect from "effect/Effect";
+import { resolve } from "node:path";
 import * as Layer from "effect/Layer";
+import { ServiceMap } from "effect";
 import * as Option from "effect/Option";
-import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as Schema from "effect/Schema";
 import * as ConfigProvider from "effect/ConfigProvider";
 //#region ../../packages/core/src/services/pr-preflight.ts
 var PreflightFailure = class extends Schema.TaggedErrorClass()("PreflightFailure", {
@@ -238,13 +238,6 @@ var InvalidPrUrl = class extends Schema.TaggedErrorClass()("InvalidPrUrl", {
 	url: Schema.String
 }) {};
 /**
-* Quick heuristic: does this string look like a PR URL?
-*
-* Used by the CLI parser to distinguish `review <url>` from `review <verb>`.
-* No ambiguity: no review verb starts with `http`.
-*/
-const looksLikePrUrl = (s) => /^https?:\/\/[^/]+\/[^/]+\/[^/]+\/pull\/\d+/.test(s);
-/**
 * Parses a GitHub PR URL into structured components.
 *
 * Supports:
@@ -291,14 +284,13 @@ const parsePrUrl = Effect.fn("parsePrUrl")(function* (raw) {
 	};
 });
 //#endregion
-//#region src/cli/config.ts
-var CliConfig = class extends ServiceMap.Service()("@ringi/CliConfig") {};
+//#region src/cli/cli-errors.ts
 /**
-* Wraps a concrete {@link CliConfigShape} in a layer for the Effect runtime.
+* Typed CLI errors.
+*
+* All CLI errors use `Schema.TaggedErrorClass` so they flow through Effect's
+* typed error channels.
 */
-const CliConfigLive = (config) => Layer.succeed(CliConfig, CliConfig.of(config));
-//#endregion
-//#region src/cli/contracts.ts
 const ExitCode = {
 	AuthFailure: 5,
 	ResourceNotFound: 3,
@@ -307,19 +299,6 @@ const ExitCode = {
 	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.
@@ -330,96 +309,99 @@ var CliFailure = class extends Schema.TaggedErrorClass()("CliFailure", {
 	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");
+//#region src/cli/config.ts
+var CliConfig = class extends ServiceMap.Service()("@ringi/CliConfig") {};
+/**
+* Wraps a concrete {@link CliConfigShape} in a layer for the Effect runtime.
+*/
+const CliConfigLive = (config) => Layer.succeed(CliConfig, CliConfig.of(config));
+//#endregion
+//#region src/cli/output.ts
+const successEnvelope = (command, result, nextActions = []) => ({
+	command,
+	next_actions: nextActions,
+	ok: true,
+	result
+});
+const writeJson = (payload) => {
+	process.stdout.write(`${JSON.stringify(payload, null, 2)}\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 writeHuman = (text) => {
+	if (text && text.length > 0) process.stdout.write(`${text}\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})`);
+//#endregion
+//#region src/cli/commands.ts
+/**
+* Ringi CLI command definitions using `effect/unstable/cli`.
+*
+* Each command is a typed `Command.make(name, config, handler)` with its flags
+* and arguments declared via `Flag` and `Argument`. The framework handles
+* parsing, help generation, shell completions, and version display.
+*
+* Command handlers produce `CommandOutput<T>` and emit output via the
+* `--json` global flag setting.
+*/
+const JsonSetting = GlobalFlag.setting("json")({ flag: Flag.boolean("json").pipe(Flag.withDescription("Emit structured JSON envelope to stdout"), Flag.withDefault(false)) });
+const QuietSetting = GlobalFlag.setting("quiet")({ flag: Flag.boolean("quiet").pipe(Flag.withDescription("Suppress human-readable success output"), Flag.withDefault(false)) });
+const RepoSetting = GlobalFlag.setting("repo")({ flag: Flag.string("repo").pipe(Flag.withDescription("Use a specific Git repository root"), Flag.optional) });
+const DbPathSetting = GlobalFlag.setting("db-path")({ flag: Flag.string("db-path").pipe(Flag.withDescription("Override the SQLite database path"), Flag.optional) });
+const emitOutput = (commandLabel, output) => Effect.gen(function* () {
+	const jsonMode = yield* JsonSetting;
+	const quietMode = yield* QuietSetting;
+	if (jsonMode) writeJson(successEnvelope(commandLabel, output.data, output.nextActions ?? []));
+	else if (!quietMode) writeHuman(output.human);
+});
+const resolveRepositoryRoot = (repoOverride) => {
+	const cwd = Option.isSome(repoOverride) ? resolve(repoOverride.value) : process.cwd();
+	try {
+		return Effect.succeed(execFileSync("git", ["rev-parse", "--show-toplevel"], {
+			cwd,
+			encoding: "utf8"
+		}).trim());
+	} catch {
+		return Effect.fail(new CliFailure({
+			exitCode: ExitCode.StateUnavailable,
+			message: Option.isSome(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.`
+		}));
 	}
-	return lines.join("\n");
 };
+const resolveDbPath = (repoRoot, dbPathOverride) => Option.isSome(dbPathOverride) ? resolve(dbPathOverride.value) : resolve(repoRoot, ".ringi/reviews.db");
+const makeCliConfigLayer = Effect.gen(function* () {
+	const repoOpt = yield* RepoSetting;
+	const dbPathOpt = yield* DbPathSetting;
+	const repoRoot = yield* resolveRepositoryRoot(repoOpt);
+	const dbPath = resolveDbPath(repoRoot, dbPathOpt);
+	const config = {
+		color: true,
+		cwd: process.cwd(),
+		dbPath,
+		outputMode: "human",
+		quiet: false,
+		repoRoot,
+		verbose: false
+	};
+	return Layer.mergeAll(CliConfigLive(config), ConfigProvider.layer(ConfigProvider.fromUnknown({
+		DB_PATH: dbPath,
+		REPOSITORY_PATH: repoRoot
+	})));
+});
+const ensureDatabaseExists = Effect.gen(function* () {
+	const cliConfig = yield* CliConfig;
+	if (!existsSync(cliConfig.dbPath)) yield* new CliFailure({
+		exitCode: ExitCode.StateUnavailable,
+		message: `Local state is missing at ${cliConfig.dbPath}. Run 'ringi data migrate' or start 'ringi serve' once to initialize local state.`
+	});
+});
 /**
-* Resolves the special "last" selector before show/export handlers ask the
-* shared services for a concrete review id.
+* Provides CoreLive + CliConfig to a command's handler.
+* Constructs the layer from the global flags (--repo, --db-path).
 */
-const resolveReviewSelector = Effect.fn("CLI.resolveReviewSelector")(function* resolveReviewSelector(selector) {
+const provideCoreLayer = (self) => Command.provide(self, () => Layer.unwrap(makeCliConfigLayer.pipe(Effect.map((configLayer) => Layer.mergeAll(CoreLive, configLayer).pipe(Layer.provideMerge(configLayer))))));
+/**
+* Provides only GitService + CliConfig (lighter for git-only commands).
+*/
+const provideGitLayer = (self) => Command.provide(self, () => Layer.unwrap(makeCliConfigLayer.pipe(Effect.map((configLayer) => Layer.mergeAll(GitService.Default, configLayer).pipe(Layer.provideMerge(configLayer))))));
+const resolveReviewSelector = Effect.fn("CLI.resolveReviewSelector")(function* (selector) {
 	if (selector !== "last") return selector;
 	const cliConfig = yield* CliConfig;
 	const [review] = (yield* (yield* ReviewService).list({
@@ -433,29 +415,47 @@ const resolveReviewSelector = Effect.fn("CLI.resolveReviewSelector")(function* r
 	});
 	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 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 runReviewList = Effect.fn("CLI.reviewList")(function* runReviewList(command) {
+const reviewList = Command.make("list", {
+	status: Flag.choice("status", [
+		"in_progress",
+		"approved",
+		"changes_requested"
+	]).pipe(Flag.withDescription("Filter by review status"), Flag.optional),
+	source: Flag.choice("source", [
+		"staged",
+		"branch",
+		"commits",
+		"pull_request"
+	]).pipe(Flag.withDescription("Filter by source type"), Flag.optional),
+	limit: Flag.integer("limit").pipe(Flag.withDefault(20), Flag.withDescription("Number of results per page")),
+	page: Flag.integer("page").pipe(Flag.withDefault(1), Flag.withDescription("Page number"))
+}, (config) => Effect.gen(function* () {
+	yield* ensureDatabaseExists;
 	const reviewService = yield* ReviewService;
 	const cliConfig = yield* CliConfig;
 	const result = yield* reviewService.list({
-		page: command.page,
-		pageSize: command.limit,
+		page: config.page,
+		pageSize: config.limit,
 		repositoryPath: cliConfig.repoRoot,
-		sourceType: command.source,
-		status: command.status
+		sourceType: Option.getOrUndefined(config.source),
+		status: Option.getOrUndefined(config.status)
 	});
 	const nextActions = [];
 	for (const review of result.reviews.slice(0, 3)) nextActions.push({
@@ -463,87 +463,106 @@ const runReviewList = Effect.fn("CLI.reviewList")(function* runReviewList(comman
 		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
-		} }
+		command: "ringi review show <id> --comments --todos",
+		description: "Show full review details"
 	});
 	nextActions.push({
-		command: "ringi review create [--source <source>]",
-		description: "Create a new review session",
-		params: { source: {
-			default: "staged",
-			enum: [
-				"staged",
-				"branch",
-				"commits"
-			]
-		} }
+		command: "ringi review create --source <source>",
+		description: "Create a new review session"
 	});
-	return {
+	yield* emitOutput("ringi review list", {
 		data: result,
-		human: renderReviewList(result.reviews),
+		human: result.reviews.length === 0 ? "No reviews found." : formatTable([
+			"ID",
+			"STATUS",
+			"SOURCE",
+			"FILES",
+			"CREATED"
+		], result.reviews.map((r) => [
+			r.id,
+			r.status,
+			r.sourceType,
+			String(r.fileCount),
+			r.createdAt
+		])),
 		nextActions
-	};
-});
-const runReviewShow = Effect.fn("CLI.reviewShow")(function* runReviewShow(command) {
+	});
+})).pipe(Command.withDescription("List review sessions"));
+const reviewShow = Command.make("show", {
+	id: Argument.string("id"),
+	comments: Flag.boolean("comments").pipe(Flag.withDefault(false), Flag.withDescription("Include comments")),
+	todos: Flag.boolean("todos").pipe(Flag.withDefault(false), Flag.withDescription("Include todos"))
+}, (config) => Effect.gen(function* () {
+	yield* ensureDatabaseExists;
 	const reviewService = yield* ReviewService;
 	const todoService = yield* TodoService;
 	const commentService = yield* CommentService;
-	const reviewId = yield* resolveReviewSelector(command.id);
+	const reviewId = yield* resolveReviewSelector(config.id);
 	const review = yield* reviewService.getById(reviewId);
+	const comments = config.comments ? yield* commentService.getByReview(reviewId) : void 0;
+	const todos = config.todos ? (yield* todoService.list({ reviewId })).data : void 0;
 	const data = {
-		comments: command.comments ? yield* commentService.getByReview(reviewId) : void 0,
+		comments,
 		review,
-		todos: command.todos ? (yield* todoService.list({ reviewId })).data : void 0
+		todos
 	};
-	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"
-		}
+	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}`
 	];
-	return {
+	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}`);
+		}
+	}
+	yield* emitOutput("ringi review show", {
 		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."
+		human: lines.join("\n"),
+		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 review list",
+				description: "Back to review list"
+			}
+		]
 	});
+})).pipe(Command.withDescription("Show review details"));
+const reviewExport = Command.make("export", {
+	id: Argument.string("id"),
+	output: Flag.string("output").pipe(Flag.withDescription("Output file path"), Flag.optional),
+	stdout: Flag.boolean("stdout").pipe(Flag.withDefault(false), Flag.withDescription("Print to stdout instead of a file"))
+}, (config) => Effect.gen(function* () {
+	yield* ensureDatabaseExists;
 	const exportService = yield* ExportService;
 	const cliConfig = yield* CliConfig;
-	const reviewId = yield* resolveReviewSelector(command.id);
+	const reviewId = yield* resolveReviewSelector(config.id);
 	const markdown = yield* exportService.exportReview(reviewId);
-	const outputPath = command.outputPath ? resolve(cliConfig.cwd, command.outputPath) : void 0;
+	const outputPath = Option.isSome(config.output) ? resolve(cliConfig.cwd, config.output.value) : void 0;
 	if (outputPath) yield* Effect.tryPromise({
 		catch: (error) => new CliFailure({
 			exitCode: ExitCode.RuntimeFailure,
@@ -551,107 +570,49 @@ const runReviewExport = Effect.fn("CLI.reviewExport")(function* runReviewExport(
 		}),
 		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,
+	const shouldPrintMarkdown = config.stdout || !outputPath;
+	yield* emitOutput("ringi review export", {
+		data: {
+			markdown,
+			outputPath: outputPath ?? null,
+			reviewId
+		},
 		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."
+		nextActions: [{
+			command: `ringi review show ${reviewId}`,
+			description: "View the exported review"
+		}, {
+			command: "ringi review list",
+			description: "Back to review list"
+		}]
 	});
-	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) {
+})).pipe(Command.withDescription("Export review as markdown"));
+const reviewCreate = Command.make("create", {
+	source: Flag.choice("source", [
+		"staged",
+		"branch",
+		"commits",
+		"pull_request"
+	]).pipe(Flag.withDefault("staged"), Flag.withDescription("Review source type")),
+	branch: Flag.string("branch").pipe(Flag.withDescription("Branch name for branch source"), Flag.optional),
+	commits: Flag.string("commits").pipe(Flag.withDescription("Commit range for commits source"), Flag.optional),
+	title: Flag.string("title").pipe(Flag.withDescription("Review title"), Flag.optional)
+}, (_config) => requireServerMode("ringi review create")).pipe(Command.withDescription("Create a review session"));
+const reviewResolve = Command.make("resolve", {
+	id: Argument.string("id"),
+	allComments: Flag.boolean("all-comments").pipe(Flag.withDefault(true), Flag.withDescription("Resolve all comments")),
+	yes: Flag.boolean("yes").pipe(Flag.withDefault(false), Flag.withDescription("Skip confirmation prompt"))
+}, (_config) => requireServerMode("ringi review resolve")).pipe(Command.withDescription("Resolve a review session"));
+const reviewStatus = Command.make("status", {
+	reviewId: Flag.string("review").pipe(Flag.withDescription("Review ID or 'last'"), Flag.optional),
+	source: Flag.choice("source", [
+		"staged",
+		"branch",
+		"commits",
+		"pull_request"
+	]).pipe(Flag.withDescription("Filter by source type"), Flag.optional)
+}, (config) => Effect.gen(function* () {
+	yield* ensureDatabaseExists;
 	const reviewService = yield* ReviewService;
 	const todoService = yield* TodoService;
 	const commentService = yield* CommentService;
@@ -660,12 +621,12 @@ const runReviewStatus = Effect.fn("CLI.reviewStatus")(function* runReviewStatus(
 	const repo = yield* gitService.getRepositoryInfo;
 	const stagedFiles = yield* gitService.getStagedFiles;
 	let reviewId;
-	if (command.reviewId) reviewId = yield* resolveReviewSelector(command.reviewId);
+	if (Option.isSome(config.reviewId)) reviewId = yield* resolveReviewSelector(config.reviewId.value);
 	const reviews = yield* reviewService.list({
 		page: 1,
 		pageSize: 1,
 		repositoryPath: cliConfig.repoRoot,
-		sourceType: command.source
+		sourceType: Option.getOrUndefined(config.source)
 	});
 	const latestReview = reviewId ? yield* reviewService.getById(reviewId) : reviews.reviews[0];
 	let commentStats;
@@ -709,64 +670,32 @@ const runReviewStatus = Effect.fn("CLI.reviewStatus")(function* runReviewStatus(
 		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"
-			]
-		} }
+		command: "ringi review create --source <source>",
+		description: "Create a new review session"
 	});
-	return {
+	yield* emitOutput("ringi review status", {
 		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
-	};
-});
-const runReviewPr = Effect.fn("CLI.reviewPr")(function* runReviewPr(command) {
-	const target = yield* parsePrUrl(command.prUrl).pipe(Effect.mapError((e) => new CliFailure({
+})).pipe(Command.withDescription("Show repository and review status"));
+const reviewPr = Command.make("pr", {
+	prUrl: Argument.string("pr-url"),
+	port: Flag.integer("port").pipe(Flag.withDefault(3e3), Flag.withDescription("Local server port")),
+	noOpen: Flag.boolean("no-open").pipe(Flag.withDefault(false), Flag.withDescription("Skip opening the browser")),
+	forceRefresh: Flag.boolean("force-refresh").pipe(Flag.withDefault(false), Flag.withDescription("Re-fetch PR data with latest changes"))
+}, (config) => Effect.gen(function* () {
+	const target = yield* parsePrUrl(config.prUrl).pipe(Effect.mapError((e) => new CliFailure({
 		exitCode: ExitCode.UsageError,
 		message: e.message
 	})));
 	const preflight = yield* runPreflight(target).pipe(Effect.mapError((e) => new CliFailure({
-		exitCode: e.exitCode,
+		exitCode: e.exitCode ?? ExitCode.RuntimeFailure,
 		message: e.message
 	})));
 	if (preflight.affinityWarning) yield* Effect.logWarning(preflight.affinityWarning);
 	let session;
-	if (command.forceRefresh) {
+	if (config.forceRefresh) {
 		const reviewService = yield* ReviewService;
 		const sourceRef = prSourceRef(target);
 		const cliConfig = yield* CliConfig;
@@ -795,17 +724,9 @@ const runReviewPr = Effect.fn("CLI.reviewPr")(function* runReviewPr(command) {
 		message: e.message
 	})));
 	if (session.staleWarning) yield* Effect.logWarning(session.staleWarning);
-	const serverUrl = `http://localhost:${command.port}`;
+	const serverUrl = `http://localhost:${config.port}`;
 	const reviewUrl = `${serverUrl}/review/${session.reviewId}`;
-	const data = {
-		isResumed: session.isResumed,
-		isStale: session.isStale,
-		prNumber: target.prNumber,
-		prUrl: target.url,
-		reviewId: session.reviewId,
-		reviewUrl
-	};
-	const statusLabel = session.isResumed ? command.forceRefresh ? "(refreshed)" : "(resumed)" : "(new)";
+	const statusLabel = session.isResumed ? config.forceRefresh ? "(refreshed)" : "(resumed)" : "(new)";
 	const humanLines = [
 		`PR #${target.prNumber}: ${preflight.metadata.title}`,
 		`Review: ${session.reviewId} ${statusLabel}`,
@@ -816,8 +737,14 @@ const runReviewPr = Effect.fn("CLI.reviewPr")(function* runReviewPr(command) {
 		`Server: ${serverUrl}`,
 		`Review: ${reviewUrl}`
 	];
-	if (preflight.metadata.isDraft) humanLines.splice(1, 0, "⚠ Draft PR");
-	if (preflight.metadata.state === "CLOSED" || preflight.metadata.state === "MERGED") humanLines.splice(1, 0, `⚠ This PR is ${preflight.metadata.state}`);
+	const data = {
+		isResumed: session.isResumed,
+		isStale: session.isStale,
+		prNumber: target.prNumber,
+		prUrl: target.url,
+		reviewId: session.reviewId,
+		reviewUrl
+	};
 	const nextActions = [{
 		command: `ringi review show ${session.reviewId} --comments --todos`,
 		description: "Inspect review details"
@@ -825,1181 +752,186 @@ const runReviewPr = Effect.fn("CLI.reviewPr")(function* runReviewPr(command) {
 		command: `ringi review export ${session.reviewId}`,
 		description: "Export review as markdown"
 	}];
-	if (session.isStale) nextActions.unshift({
-		command: `ringi review ${command.prUrl} --force-refresh`,
-		description: "Re-fetch PR data with latest changes"
-	});
-	return {
+	yield* emitOutput("ringi review pr", {
 		data,
 		human: humanLines.join("\n"),
 		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-pr": (c) => runReviewPr(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-pr": "ringi review <pr-url>",
-	"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",
-	"pull_request",
-	"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 Result.fail(usageError(`${flag} must be a non-negative integer.`));
-	return Result.succeed(value);
-};
-const decodeEnum = (raw, valid, label) => {
-	if (!valid.has(raw)) return Result.fail(usageError(`Invalid ${label}: ${raw}.`));
-	return Result.succeed(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 (Result.isFailure(decoded)) return Option.some(decoded.failure);
-	if (opts?.min !== void 0 && decoded.success <= opts.min) return Option.some(usageError(`${flag} must be greater than ${opts.min}.`));
-	acc[key] = decoded.success;
-	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 (Result.isFailure(decoded)) return Option.some(decoded.failure);
-	acc[key] = decoded.success;
-	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 Result.fail(error.value);
-	return Result.succeed({
-		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 Result.fail(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 Result.fail(error.value);
-	return Result.succeed({
-		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 Result.fail(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 Result.fail(error.value);
-	return Result.succeed({
-		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 Result.fail(error.value);
-	const validationError = validateReviewCreate(acc);
-	if (Option.isSome(validationError)) return Result.fail(validationError.value);
-	return Result.succeed({
-		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 Result.fail(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 Result.fail(error.value);
-	const validationError = validateSourceDiff(source, acc);
-	if (Option.isSome(validationError)) return Result.fail(validationError.value);
-	return Result.succeed({
-		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 Result.fail(error.value);
-	return Result.succeed({
-		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 Result.fail(usageError(`${label} requires <id>.`));
-	state.index += 1;
-	while (state.index < state.tokens.length) if (!maybeParseGlobalFlag(state)) return Result.fail(usageError(`Unknown flag for ${label}: ${state.tokens[state.index]}.`));
-	return Result.succeed({
-		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 Result.fail(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 Result.fail(error.value);
-	if (acc.position === void 0) return Result.fail(usageError("todo move requires --position."));
-	return Result.succeed({
-		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 Result.fail(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 Result.fail(error.value);
-	return Result.succeed({
-		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 Result.fail(error.value);
-	return Result.succeed({
-		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 Result.fail(error.value);
-	return Result.succeed({
-		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 Result.fail(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 Result.fail(error.value);
-	return Result.succeed({
-		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 Result.fail(error.value);
-	if (!acc.text.trim()) return Result.fail(usageError("todo add requires --text."));
-	return Result.succeed({
-		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 Result.fail(error.value);
-	return Result.succeed({
-		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 Result.fail(error.value);
-	return Result.succeed({
-		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 Result.fail(error.value);
-	return Result.succeed({
-		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 Result.fail(error.value);
-	return Result.succeed({
-		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
-};
-const REVIEW_PR_FLAGS = {
-	"--force-refresh": boolFlag("forceRefresh"),
-	"--no-open": boolFlag("noOpen"),
-	"--port": positiveIntFlag("port", { min: 0 })
-};
-const parseReviewPr = (state, prUrl) => {
-	const acc = {
-		forceRefresh: false,
-		noOpen: false,
-		port: 3e3
+})).pipe(Command.withDescription("Create or resume a PR review"));
+const review = Command.make("review").pipe(Command.withDescription("Review management commands"), Command.withSubcommands([
+	reviewList,
+	reviewShow,
+	reviewExport,
+	reviewCreate,
+	reviewResolve,
+	reviewStatus,
+	reviewPr
+]));
+const sourceList = Command.make("list", {}, () => Effect.gen(function* () {
+	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
 	};
-	const error = runFlagLoop(state, acc, REVIEW_PR_FLAGS, "review <pr-url>");
-	if (Option.isSome(error)) return Result.fail(error.value);
-	return Result.succeed({
-		kind: "review-pr",
-		prUrl,
-		...acc
-	});
-};
-/** 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 Result.fail(error.value);
-		return Result.succeed({ 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 Result.succeed({
-			kind: "help",
-			topic: ["data"]
-		});
-		state.index += 1;
-		const parser = DATA_VERB_PARSERS[verb];
-		if (!parser) return Result.fail(usageError(`Unknown data command: ${verb}.`));
-		return parser(state);
-	},
-	doctor: (state) => {
-		const error = ensureNoExtraArgs(state, "doctor");
-		if (Option.isSome(error)) return Result.fail(error.value);
-		return Result.succeed({ kind: "doctor" });
-	},
-	events: parseEvents,
-	export: parseReviewExport,
-	mcp: parseMcp,
-	review: (state) => {
-		const verb = state.tokens[state.index];
-		if (!verb) return Result.succeed({
-			kind: "help",
-			topic: ["review"]
-		});
-		if (looksLikePrUrl(verb)) {
-			state.index += 1;
-			return parseReviewPr(state, verb);
-		}
-		state.index += 1;
-		const parser = REVIEW_VERB_PARSERS[verb];
-		if (!parser) return Result.fail(usageError(`Unknown review command: ${verb}.`));
-		return parser(state);
-	},
-	serve: parseServe,
-	source: (state) => {
-		const verb = state.tokens[state.index];
-		if (!verb) return Result.succeed({
-			kind: "help",
-			topic: ["source"]
-		});
-		state.index += 1;
-		if (verb === "list") {
-			const error = ensureNoExtraArgs(state, "source list");
-			if (Option.isSome(error)) return Result.fail(error.value);
-			return Result.succeed({ kind: "source-list" });
-		}
-		if (verb === "diff") return parseSourceDiff(state);
-		return Result.fail(usageError(`Unknown source command: ${verb}.`));
-	},
-	todo: (state) => {
-		const verb = state.tokens[state.index];
-		if (!verb) return Result.succeed({
-			kind: "help",
-			topic: ["todo"]
-		});
-		state.index += 1;
-		const parser = TODO_VERB_PARSERS[verb];
-		if (!parser) return Result.fail(usageError(`Unknown todo command: ${verb}.`));
-		return parser(state);
+	const lines = [
+		`Repository: ${data.repo.name}`,
+		`Path: ${data.repo.path}`,
+		`Current branch: ${data.repo.branch}`,
+		`Staged files: ${data.stagedFiles.length}`
+	];
+	if (data.stagedFiles.length > 0) {
+		lines.push("", "Staged:");
+		for (const file of data.stagedFiles) lines.push(`- ${file.status} ${file.path}`);
 	}
-};
-/**
-* 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 Result.succeed({ kind: "version" });
-	if (state.index >= state.tokens.length) return Result.succeed({
-		kind: "help",
-		topic: []
-	});
-	const first = state.tokens[state.index];
-	if (!first) return Result.succeed({
-		kind: "help",
-		topic: []
-	});
-	if (first === "help") {
-		const topic = state.tokens.slice(state.index + 1);
-		state.index = state.tokens.length;
-		return Result.succeed({
-			kind: "help",
-			topic
-		});
+	if (data.branches.length > 0) {
+		lines.push("", "Branches:");
+		for (const branch of data.branches.slice(0, 10)) lines.push(`- ${branch.current ? "*" : " "} ${branch.name}`);
 	}
-	if (state.options.help) return Result.succeed({
-		kind: "help",
-		topic: state.tokens.slice(state.index)
+	if (data.commits.length > 0) {
+		lines.push("", "Recent commits:");
+		for (const commit of data.commits.slice(0, 5)) lines.push(`- ${commit.hash.slice(0, 8)} ${commit.message} (${commit.author})`);
+	}
+	yield* emitOutput("ringi source list", {
+		data,
+		human: lines.join("\n"),
+		nextActions: [
+			{
+				command: "ringi source diff <source> --stat",
+				description: "View diff for a source"
+			},
+			{
+				command: "ringi review create --source <source>",
+				description: "Create a review from a source"
+			},
+			{
+				command: "ringi review list",
+				description: "List existing reviews"
+			}
+		]
 	});
-	state.index += 1;
-	const familyParser = FAMILY_PARSERS[first];
-	if (!familyParser) return Result.fail(usageError(`Unknown command: ${first}.`));
-	return familyParser(state);
+})).pipe(Command.withDescription("List repository sources"));
+const diffStrategies = {
+	branch: (git, branch) => git.getBranchDiff(branch ?? ""),
+	commits: (git, _branch, commits) => git.getCommitDiff((commits ?? "").split(",").map((i) => i.trim()).filter(Boolean)),
+	staged: (git) => git.getStagedDiff
 };
-const parseCliArgs = (argv) => {
-	const options = createDefaultOptions();
-	const result = parseWithState({
-		index: 0,
-		options,
-		tokens: argv
+const sourceDiff = Command.make("diff", {
+	source: Argument.choice("source", [
+		"staged",
+		"branch",
+		"commits"
+	]),
+	branch: Flag.string("branch").pipe(Flag.withDescription("Branch name"), Flag.optional),
+	commits: Flag.string("commits").pipe(Flag.withDescription("Commit range"), Flag.optional),
+	stat: Flag.boolean("stat").pipe(Flag.withDefault(false), Flag.withDescription("Show stats only"))
+}, (config) => Effect.gen(function* () {
+	const gitService = yield* GitService;
+	const strategy = diffStrategies[config.source];
+	if (!strategy) yield* new CliFailure({
+		exitCode: ExitCode.UsageError,
+		message: "Unsupported review source."
 	});
-	if (Result.isFailure(result)) return Result.fail(result.failure);
-	return Result.succeed({
-		command: result.success,
-		options
+	const diffText = yield* strategy(gitService, Option.getOrUndefined(config.branch), Option.getOrUndefined(config.commits));
+	if (!diffText.trim()) yield* new CliFailure({
+		exitCode: ExitCode.RuntimeFailure,
+		message: "No diff available for the requested source."
 	});
-};
-//#endregion
-//#region src/cli/runtime.ts
-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";
-/**
-* Commands that need the database to already exist. `review-pr` is NOT here
-* because it auto-initializes `.ringi/` (like `serve` does).
-*/
-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-pr" || 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
+	const files = parseDiff(diffText);
+	const data = {
+		diff: diffText,
+		source: config.source,
+		summary: getDiffSummary(files)
 	};
-};
-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.`
+	yield* emitOutput("ringi source diff", {
+		data,
+		human: config.stat ? [
+			`Source: ${config.source}`,
+			`Files: ${data.summary.totalFiles}`,
+			`Additions: ${data.summary.totalAdditions}`,
+			`Deletions: ${data.summary.totalDeletions}`
+		].join("\n") : diffText,
+		nextActions: [{
+			command: `ringi review create --source ${config.source}`,
+			description: `Create a review from this ${config.source} diff`
+		}, {
+			command: "ringi source list",
+			description: "List repository sources"
+		}]
 	});
-};
-const makeConfigLayer = (config) => ConfigProvider.layer(ConfigProvider.fromUnknown({
-	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))));
-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.3.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"
+})).pipe(Command.withDescription("Show diff for a source"));
+const source = Command.make("source").pipe(Command.withDescription("Source management commands"), Command.withSubcommands([sourceList, sourceDiff]));
+const todoList = Command.make("list", {
+	reviewId: Flag.string("review").pipe(Flag.withDescription("Filter by review ID"), Flag.optional),
+	status: Flag.choice("status", [
+		"pending",
+		"done",
+		"all"
+	]).pipe(Flag.withDefault("pending"), Flag.withDescription("Filter by status")),
+	limit: Flag.integer("limit").pipe(Flag.withDescription("Max results"), Flag.optional),
+	offset: Flag.integer("offset").pipe(Flag.withDefault(0), Flag.withDescription("Results offset"))
+}, (config) => Effect.gen(function* () {
+	yield* ensureDatabaseExists;
+	const result = yield* (yield* TodoService).list({
+		completed: config.status === "all" ? void 0 : config.status === "done",
+		limit: Option.getOrUndefined(config.limit),
+		offset: config.offset,
+		reviewId: Option.getOrUndefined(config.reviewId)
 	});
-	if (normalized.category === "config" || normalized.category === "connection") actions.push({
-		command: "ringi serve",
-		description: "Start the local Ringi server"
+	const nextActions = [];
+	if (Option.isSome(config.reviewId)) nextActions.push({
+		command: `ringi review show ${config.reviewId.value}`,
+		description: "View the associated review"
 	});
-	if (normalized.category === "not_found") actions.push({
-		command: "ringi review list",
-		description: "List available reviews"
+	nextActions.push({
+		command: "ringi todo add --text <text>",
+		description: "Add a new todo"
 	}, {
-		command: "ringi todo list",
-		description: "List available todos"
+		command: "ringi review list",
+		description: "List reviews"
 	});
-	if (normalized.category === "validation") actions.push({
-		command: `${commandStr.split(" ").slice(0, 3).join(" ")} --help`,
-		description: "Show command usage"
+	yield* emitOutput("ringi todo list", {
+		data: result,
+		human: result.data.length === 0 ? "No todos found." : result.data.map((todo) => `- [${todo.completed ? "x" : " "}] (${todo.position + 1}) ${todo.content}`).join("\n"),
+		nextActions
 	});
-	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.
-*
-* Lookup order (first match wins):
-* 1. **Packaged location** — `<pkg-root>/server/server/index.mjs`
-*    The published npm package includes `server/` at the package root, which
-*    contains `server/index.mjs` (the Nitro entry) and `public/` (static
-*    assets). From the bundled CLI at `dist/cli.mjs`, the package root is
-*    `import.meta.dirname/..`.
-* 2. **Monorepo development** — `apps/web/.output/server/index.mjs`
-*    During local development the web build output lives inside the web
-*    workspace. We resolve it relative to the CLI package root.
-* 3. **CWD fallback** — `.output/server/index.mjs` relative to the current
-*    working directory, for running the server in a standalone checkout.
-*/
+})).pipe(Command.withDescription("List todo items"));
+const todoAdd = Command.make("add", {
+	text: Flag.string("text").pipe(Flag.withDescription("Todo text")),
+	reviewId: Flag.string("review").pipe(Flag.withDescription("Associate with review"), Flag.optional),
+	position: Flag.integer("position").pipe(Flag.withDescription("Insert position"), Flag.optional)
+}, (_config) => requireServerMode("ringi todo add")).pipe(Command.withDescription("Add a todo item"));
+const todoDone = Command.make("done", { id: Argument.string("id") }, (_config) => requireServerMode("ringi todo done")).pipe(Command.withDescription("Mark a todo as done"));
+const todoUndone = Command.make("undone", { id: Argument.string("id") }, (_config) => requireServerMode("ringi todo undone")).pipe(Command.withDescription("Reopen a completed todo"));
+const todoMove = Command.make("move", {
+	id: Argument.string("id"),
+	position: Flag.integer("position").pipe(Flag.withDescription("Target position"))
+}, (_config) => requireServerMode("ringi todo move")).pipe(Command.withDescription("Move a todo to a position"));
+const todoRemove = Command.make("remove", {
+	id: Argument.string("id"),
+	yes: Flag.boolean("yes").pipe(Flag.withDefault(false), Flag.withDescription("Skip confirmation"))
+}, (_config) => requireServerMode("ringi todo remove")).pipe(Command.withDescription("Remove a todo"));
+const todoClear = Command.make("clear", {
+	reviewId: Flag.string("review").pipe(Flag.withDescription("Scope to review"), Flag.optional),
+	doneOnly: Flag.boolean("done-only").pipe(Flag.withDefault(true), Flag.withDescription("Clear only completed")),
+	all: Flag.boolean("all").pipe(Flag.withDefault(false), Flag.withDescription("Clear all todos")),
+	yes: Flag.boolean("yes").pipe(Flag.withDefault(false), Flag.withDescription("Skip confirmation"))
+}, (_config) => requireServerMode("ringi todo clear")).pipe(Command.withDescription("Clear completed todos"));
+const todo = Command.make("todo").pipe(Command.withDescription("Todo management commands"), Command.withSubcommands([
+	todoList,
+	todoAdd,
+	todoDone,
+	todoUndone,
+	todoMove,
+	todoRemove,
+	todoClear
+]));
 const resolveServerEntry = () => {
 	const candidates = [];
 	if (import.meta.dirname) {
@@ -2010,122 +942,126 @@ const resolveServerEntry = () => {
 	candidates.push(resolve(process.cwd(), ".output", "server", "index.mjs"));
 	return candidates.find((candidate) => existsSync(candidate));
 };
-const runServe = (command) => {
+const serve = Command.make("serve", {
+	host: Flag.string("host").pipe(Flag.withDefault("127.0.0.1"), Flag.withDescription("Bind host")),
+	port: Flag.integer("port").pipe(Flag.withDefault(3e3), Flag.withDescription("Port number")),
+	https: Flag.boolean("https").pipe(Flag.withDefault(false), Flag.withDescription("Enable HTTPS")),
+	cert: Flag.string("cert").pipe(Flag.withDescription("SSL certificate path"), Flag.optional),
+	key: Flag.string("key").pipe(Flag.withDescription("SSL key path"), Flag.optional),
+	auth: Flag.boolean("auth").pipe(Flag.withDefault(false), Flag.withDescription("Enable authentication")),
+	noOpen: Flag.boolean("no-open").pipe(Flag.withDefault(false), Flag.withDescription("Don't open browser"))
+}, (config) => Effect.callback((resume) => {
 	const serverEntry = resolveServerEntry();
 	if (!serverEntry) {
 		const hint = import.meta.dirname && !import.meta.dirname.includes("apps/cli/") ? "The installed package is missing its server assets. Try reinstalling: npm install -g @sanurb/ringi" : "Run 'pnpm build' at the monorepo root, then 'pnpm --filter @sanurb/ringi build:server' to copy the server assets.";
-		process.stderr.write(`No built server found.\n${hint}\n`);
-		process.exit(ExitCode.RuntimeFailure);
+		resume(Effect.fail(new CliFailure({
+			exitCode: ExitCode.RuntimeFailure,
+			message: `No built server found.\n${hint}`
+		})));
+		return;
 	}
 	const env = {
 		...process.env,
-		NITRO_HOST: command.host,
-		NITRO_PORT: String(command.port)
+		NITRO_HOST: config.host,
+		NITRO_PORT: String(config.port)
 	};
-	if (command.https && command.cert && command.key) {
-		env.NITRO_SSL_CERT = command.cert;
-		env.NITRO_SSL_KEY = command.key;
+	if (config.https && Option.isSome(config.cert) && Option.isSome(config.key)) {
+		env.NITRO_SSL_CERT = config.cert.value;
+		env.NITRO_SSL_KEY = config.key.value;
 	}
-	const url = `${command.https ? "https" : "http"}://${command.host === "0.0.0.0" ? "localhost" : command.host}:${command.port}`;
+	const url = `${config.https ? "https" : "http"}://${config.host === "0.0.0.0" ? "localhost" : config.host}:${config.port}`;
 	process.stderr.write(`ringi server starting on ${url}\n`);
 	const child = fork(serverEntry, [], {
 		env,
 		execArgv: [],
 		stdio: "inherit"
 	});
-	if (!command.noOpen) setTimeout(() => {
+	if (!config.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");
-	};
+	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 (Result.isFailure(parseResult)) return failAndExit({
-		cmdStr: "ringi",
-		error: parseResult.failure,
-		json: argv.includes("--json"),
-		verbose: false
-	});
-	const { command, options } = parseResult.success;
-	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
+		if (code === 0) resume(Effect.void);
+		else resume(Effect.fail(new CliFailure({
+			exitCode: ExitCode.RuntimeFailure,
+			message: `Server exited with code ${code}`
+		})));
 	});
-	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
+})).pipe(Command.withDescription("Start the local Ringi server"));
+const mcp = Command.make("mcp", {
+	readonly: Flag.boolean("readonly").pipe(Flag.withDefault(false), Flag.withDescription("Read-only mode")),
+	logLevel: Flag.choice("log-level", [
+		"debug",
+		"info",
+		"error",
+		"silent"
+	]).pipe(Flag.withDefault("error"), Flag.withDescription("MCP log level"))
+}, (_config) => Effect.fail(new CliFailure({
+	exitCode: ExitCode.UsageError,
+	message: "ringi mcp is a runtime command. Use the MCP server entry point directly."
+}))).pipe(Command.withDescription("Start the MCP stdio server"));
+const doctor = Command.make("doctor", {}, () => Effect.gen(function* () {
+	yield* emitOutput("ringi doctor", {
+		data: {
+			checks: [],
+			ok: true
+		},
+		human: "ringi doctor: not yet implemented.",
+		nextActions: []
 	});
-}
+})).pipe(Command.withDescription("Run local diagnostics"));
+const events = Command.make("events", { type: Flag.choice("type", [
+	"reviews",
+	"comments",
+	"todos",
+	"files"
+]).pipe(Flag.withDescription("Filter event type"), Flag.optional) }, (_config) => requireServerMode("ringi events")).pipe(Command.withDescription("Tail server events"));
+const dataMigrate = Command.make("migrate", {}, () => requireServerMode("ringi data migrate")).pipe(Command.withDescription("Run database migrations"));
+const dataReset = Command.make("reset", {
+	yes: Flag.boolean("yes").pipe(Flag.withDefault(false), Flag.withDescription("Skip confirmation")),
+	keepExports: Flag.boolean("keep-exports").pipe(Flag.withDefault(false), Flag.withDescription("Preserve export files"))
+}, (_config) => requireServerMode("ringi data reset")).pipe(Command.withDescription("Reset local data"));
+const data = Command.make("data").pipe(Command.withDescription("Data management commands"), Command.withSubcommands([dataMigrate, dataReset]));
+const reviewWithCore = provideCoreLayer(review);
+const sourceWithGit = provideGitLayer(source);
+const todoWithCore = provideCoreLayer(todo);
+const doctorWithCore = provideCoreLayer(doctor);
+const ringiCommand = Command.make("ringi").pipe(Command.withDescription("ringi — local-first code review CLI"), Command.withGlobalFlags([
+	JsonSetting,
+	QuietSetting,
+	RepoSetting,
+	DbPathSetting
+]), Command.withSubcommands([
+	reviewWithCore,
+	sourceWithGit,
+	todoWithCore,
+	serve,
+	mcp,
+	doctorWithCore,
+	events,
+	data
+]));
+//#endregion
+//#region src/cli/main.ts
+/**
+* Ringi CLI entrypoint.
+*
+* Uses `effect/unstable/cli` for command parsing, help generation, shell
+* completions, and version display. Each command is defined as a typed
+* `Command` with its own flags/arguments and handler.
+*
+* The old hand-rolled parser, imperative main loop, and manual help text
+* are replaced by the Effect CLI framework.
+*/
+const program = Command.run(ringiCommand, { version: "0.3.3" }).pipe(Effect.provide(NodeServices.layer));
+NodeRuntime.runMain(program);
 //#endregion
 export {};