@sanurb/ringi 0.2.1 → 0.3.1

package/dist/cli.mjs

@@ -1,23 +1,302 @@
 #!/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 { 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 { 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 * as Result from "effect/Result";
 import { writeFile } from "node:fs/promises";
+import { ServiceMap } from "effect";
 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 Option from "effect/Option";
 import * as ManagedRuntime from "effect/ManagedRuntime";
 import * as ConfigProvider from "effect/ConfigProvider";
+//#region ../../packages/core/src/services/pr-preflight.ts
+var PreflightFailure = class extends Schema.TaggedErrorClass()("PreflightFailure", {
+	exitCode: Schema.Number,
+	message: Schema.String,
+	phase: Schema.String
+}) {};
+/**
+* Extract repository name from a git remote URL.
+*
+* Handles:
+* - SSH:   `git@github.com:owner/repo.git`
+* - HTTPS: `https://github.com/owner/repo.git`
+* - HTTPS: `https://github.com/owner/repo`
+*/
+const extractRepoNameFromRemote = (remote) => {
+	return remote.match(/[/:]([^/]+?)(?:\.git)?$/)?.[1] ?? null;
+};
+/**
+* Runs the strict fail-fast preflight sequence for a PR review:
+*
+* 1. Verify `gh` installed
+* 2. Verify `gh` auth for target host
+* 3. Verify local git repository
+* 4. Check repository affinity (warn if mismatch, fail if no repo)
+* 5. Fetch PR metadata and validate it has changed files
+* 6. Fetch PR diff
+*/
+const runPreflight = Effect.fn("PrPreflight.run")(function* (target) {
+	const gh = yield* GhService;
+	const git = yield* GitService;
+	yield* gh.ensureInstalled.pipe(Effect.mapError((e) => new PreflightFailure({
+		exitCode: 1,
+		message: e.message,
+		phase: "gh_install"
+	})));
+	yield* gh.ensureAuthenticated(target.host).pipe(Effect.mapError((e) => new PreflightFailure({
+		exitCode: 5,
+		message: e.message,
+		phase: "gh_auth"
+	})));
+	const localRepoPath = yield* git.getRepositoryPath.pipe(Effect.mapError(() => new PreflightFailure({
+		exitCode: 4,
+		message: "Not inside a git repository. Navigate to a repo or use --repo.",
+		phase: "repo_discovery"
+	})));
+	const repoInfo = yield* git.getRepositoryInfo.pipe(Effect.mapError(() => new PreflightFailure({
+		exitCode: 1,
+		message: "Could not read repository info.",
+		phase: "repo_info"
+	})));
+	let affinityMatch = false;
+	let affinityWarning = null;
+	if (repoInfo.remote) if (extractRepoNameFromRemote(repoInfo.remote)?.toLowerCase() === target.repo.toLowerCase()) affinityMatch = true;
+	else affinityWarning = `PR is from ${target.nwoRef} but local remote points to ${repoInfo.remote}. Review will be stored in ${localRepoPath}/.ringi/`;
+	else affinityWarning = `Local repository has no remote configured. Review will be stored in ${localRepoPath}/.ringi/`;
+	const metadata = yield* gh.fetchPrMetadata(target).pipe(Effect.mapError((e) => new PreflightFailure({
+		exitCode: 1,
+		message: `PR not accessible: ${e.message}`,
+		phase: "pr_fetch"
+	})));
+	if (metadata.changedFiles === 0) return yield* new PreflightFailure({
+		exitCode: 1,
+		message: `PR #${target.prNumber} has no changed files.`,
+		phase: "pr_validation"
+	});
+	const diff = yield* gh.fetchPrDiff(target).pipe(Effect.mapError((e) => new PreflightFailure({
+		exitCode: 1,
+		message: `Failed to fetch PR diff: ${e.message}`,
+		phase: "diff_fetch"
+	})));
+	if (!diff.trim()) return yield* new PreflightFailure({
+		exitCode: 1,
+		message: `PR #${target.prNumber} returned an empty diff.`,
+		phase: "diff_fetch"
+	});
+	return {
+		affinityMatch,
+		affinityWarning,
+		diff,
+		localRepoPath,
+		metadata,
+		target
+	};
+});
+//#endregion
+//#region ../../packages/core/src/services/pr-session.ts
+var PrSessionError = class extends Schema.TaggedErrorClass()("PrSessionError", {
+	code: Schema.String,
+	message: Schema.String
+}) {};
+/** Canonical source_ref for a PR: `host/owner/repo#number`. */
+const prSourceRef = (target) => `${target.host}/${target.owner}/${target.repo}#${target.prNumber}`;
+const parseStoredManifest = (raw) => {
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return {};
+	}
+};
+/**
+* Creates a new PR review session or resumes an existing non-terminal one.
+*
+* Resume logic:
+* - Looks for an existing review with `source_type = "pull_request"` and
+*   matching `source_ref`.
+* - If found and non-terminal (`in_progress` or `changes_requested`):
+*   resumes, checking for upstream drift via head OID comparison.
+* - If found but terminal (`approved`): creates a new session.
+* - If not found: creates a new session.
+*
+* New sessions persist the full diff as hunks in `review_files`, making
+* the review fully offline-resumable after initial fetch.
+*/
+const createOrResumePrSession = Effect.fn("PrSession.createOrResume")(function* (preflight) {
+	const gh = yield* GhService;
+	const repo = yield* ReviewRepo;
+	const fileRepo = yield* ReviewFileRepo;
+	const { target, metadata, diff } = preflight;
+	const sourceRef = prSourceRef(target);
+	const resumable = (yield* repo.findAll({
+		repositoryPath: preflight.localRepoPath,
+		sourceType: "pull_request",
+		pageSize: 100
+	})).data.find((r) => r.sourceRef === sourceRef && r.status !== "approved");
+	if (resumable) {
+		const currentHeadOid = yield* gh.fetchPrHeadOid(target).pipe(Effect.catch((e) => Effect.logDebug(`Could not fetch current head OID for drift check: ${e.message}`).pipe(Effect.as(metadata.headRefOid))));
+		const storedHeadOid = parseStoredManifest(resumable.snapshotData).headOidAtFetch ?? "";
+		const isStale = storedHeadOid !== "" && storedHeadOid !== currentHeadOid;
+		return {
+			isResumed: true,
+			isStale,
+			reviewId: resumable.id,
+			staleWarning: isStale ? `PR head has changed (${storedHeadOid.slice(0, 7)} → ${currentHeadOid.slice(0, 7)}). Review data reflects the previous version. Use --force-refresh to re-fetch.` : null
+		};
+	}
+	const files = parseDiff(diff);
+	if (files.length === 0) return yield* new PrSessionError({
+		code: "NO_CHANGES",
+		message: `PR #${target.prNumber} diff parsed to zero files.`
+	});
+	const reviewId = crypto.randomUUID();
+	const snapshotData = JSON.stringify({
+		diffByteSize: Buffer.byteLength(diff, "utf8"),
+		fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		headOidAtFetch: metadata.headRefOid,
+		metadata,
+		source: "pull_request",
+		target,
+		version: 1
+	});
+	const fileInputs = files.map((f) => ({
+		additions: f.additions,
+		deletions: f.deletions,
+		filePath: f.newPath,
+		hunksData: serializeHunks(f.hunks),
+		oldPath: f.oldPath !== f.newPath ? f.oldPath : null,
+		reviewId,
+		status: f.status
+	}));
+	yield* repo.create({
+		baseRef: metadata.baseRefOid,
+		id: reviewId,
+		repositoryPath: preflight.localRepoPath,
+		snapshotData,
+		sourceRef,
+		sourceType: "pull_request",
+		status: "in_progress"
+	});
+	yield* fileRepo.createBulk(fileInputs);
+	return {
+		isResumed: false,
+		isStale: false,
+		reviewId,
+		staleWarning: null
+	};
+});
+/**
+* Re-fetches PR data for an existing session and updates stored diff/metadata.
+* Existing annotations are preserved (re-anchoring is a v1.1 feature).
+*/
+const forceRefreshPrSession = Effect.fn("PrSession.forceRefresh")(function* (reviewId, target) {
+	const gh = yield* GhService;
+	const repo = yield* ReviewRepo;
+	const fileRepo = yield* ReviewFileRepo;
+	if (!(yield* repo.findById(reviewId))) return yield* new PrSessionError({
+		code: "NOT_FOUND",
+		message: `Review session ${reviewId} not found.`
+	});
+	const metadata = yield* gh.fetchPrMetadata(target);
+	const diff = yield* gh.fetchPrDiff(target);
+	const files = parseDiff(diff);
+	const snapshotData = JSON.stringify({
+		diffByteSize: Buffer.byteLength(diff, "utf8"),
+		fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		headOidAtFetch: metadata.headRefOid,
+		metadata,
+		source: "pull_request",
+		target,
+		version: 1
+	});
+	yield* repo.updateSnapshotData(reviewId, snapshotData);
+	yield* fileRepo.deleteByReview(reviewId);
+	const fileInputs = files.map((f) => ({
+		additions: f.additions,
+		deletions: f.deletions,
+		filePath: f.newPath,
+		hunksData: serializeHunks(f.hunks),
+		oldPath: f.oldPath !== f.newPath ? f.oldPath : null,
+		reviewId,
+		status: f.status
+	}));
+	yield* fileRepo.createBulk(fileInputs);
+	return {
+		filesUpdated: files.length,
+		headOid: metadata.headRefOid,
+		reviewId,
+		summary: getDiffSummary(files)
+	};
+});
+//#endregion
+//#region ../../packages/core/src/services/pr-url.ts
+var InvalidPrUrl = class extends Schema.TaggedErrorClass()("InvalidPrUrl", {
+	message: Schema.String,
+	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:
+* - `https://github.com/owner/repo/pull/42`
+* - `https://github.com/owner/repo/pull/42/files`
+* - `https://github.com/owner/repo/pull/42/commits`
+* - `https://ghe.corp.com/owner/repo/pull/42`
+* - `http://...` (for GHE behind VPN)
+*
+* Does NOT support:
+* - SSH URLs, API URLs, short references like `owner/repo#42`
+*/
+const parsePrUrl = Effect.fn("parsePrUrl")(function* (raw) {
+	const url = yield* Effect.try({
+		catch: () => new InvalidPrUrl({
+			message: "Not a valid URL. Expected: https://github.com/<owner>/<repo>/pull/<number>",
+			url: raw
+		}),
+		try: () => new URL(raw)
+	});
+	if (url.protocol !== "https:" && url.protocol !== "http:") return yield* new InvalidPrUrl({
+		message: `Unsupported protocol: ${url.protocol}. Expected https:// or http://`,
+		url: raw
+	});
+	const segments = url.pathname.split("/").filter(Boolean);
+	if (segments.length < 4 || segments[2] !== "pull") return yield* new InvalidPrUrl({
+		message: "URL path must match /<owner>/<repo>/pull/<number>",
+		url: raw
+	});
+	const owner = segments[0];
+	const repo = segments[1];
+	const prNumber = Number.parseInt(segments[3], 10);
+	if (!Number.isFinite(prNumber) || prNumber <= 0) return yield* new InvalidPrUrl({
+		message: `Invalid PR number: ${segments[3]}`,
+		url: raw
+	});
+	return {
+		host: url.host,
+		nwoRef: `${owner}/${repo}`,
+		owner,
+		prNumber,
+		repo,
+		url: `${url.protocol}//${url.host}/${owner}/${repo}/pull/${prNumber}`
+	};
+});
+//#endregion
 //#region src/cli/config.ts
-var CliConfig = class extends Context.Tag("@ringi/CliConfig")() {};
+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, config);
+const CliConfigLive = (config) => Layer.succeed(CliConfig, CliConfig.of(config));
 //#endregion
 //#region src/cli/contracts.ts
 const ExitCode = {
@@ -45,8 +324,8 @@ const failure = (command, error, fix, nextActions = []) => ({
 * 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),
+var CliFailure = class extends Schema.TaggedErrorClass()("CliFailure", {
+	details: Schema.String.pipe(Schema.optionalKey),
 	exitCode: Schema.Number,
 	message: Schema.String
 }) {};
@@ -476,6 +755,86 @@ const runTodoList = Effect.fn("CLI.todoList")(function* runTodoList(command) {
 		nextActions
 	};
 });
+const runReviewPr = Effect.fn("CLI.reviewPr")(function* runReviewPr(command) {
+	const target = yield* parsePrUrl(command.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,
+		message: e.message
+	})));
+	if (preflight.affinityWarning) yield* Effect.logWarning(preflight.affinityWarning);
+	let session;
+	if (command.forceRefresh) {
+		const reviewService = yield* ReviewService;
+		const sourceRef = prSourceRef(target);
+		const cliConfig = yield* CliConfig;
+		const resumable = (yield* reviewService.list({
+			repositoryPath: cliConfig.repoRoot,
+			sourceType: "pull_request",
+			pageSize: 100
+		})).reviews.find((r) => r.sourceRef === sourceRef && r.status !== "approved");
+		if (resumable) {
+			yield* forceRefreshPrSession(resumable.id, target).pipe(Effect.mapError((e) => new CliFailure({
+				exitCode: ExitCode.RuntimeFailure,
+				message: e.message
+			})));
+			session = {
+				isResumed: true,
+				isStale: false,
+				reviewId: resumable.id,
+				staleWarning: null
+			};
+		} else session = yield* createOrResumePrSession(preflight).pipe(Effect.mapError((e) => new CliFailure({
+			exitCode: ExitCode.RuntimeFailure,
+			message: e.message
+		})));
+	} else session = yield* createOrResumePrSession(preflight).pipe(Effect.mapError((e) => new CliFailure({
+		exitCode: ExitCode.RuntimeFailure,
+		message: e.message
+	})));
+	if (session.staleWarning) yield* Effect.logWarning(session.staleWarning);
+	const serverUrl = `http://localhost:${command.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 humanLines = [
+		`PR #${target.prNumber}: ${preflight.metadata.title}`,
+		`Review: ${session.reviewId} ${statusLabel}`,
+		`Author: ${preflight.metadata.author.login}`,
+		`Branch: ${preflight.metadata.headRefName} → ${preflight.metadata.baseRefName}`,
+		`Files: ${preflight.metadata.changedFiles} (+${preflight.metadata.additions} -${preflight.metadata.deletions})`,
+		"",
+		`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 nextActions = [{
+		command: `ringi review show ${session.reviewId} --comments --todos`,
+		description: "Inspect review details"
+	}, {
+		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 {
+		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.
@@ -499,6 +858,7 @@ const COMMAND_HANDLERS = {
 	"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),
@@ -526,6 +886,7 @@ const COMMAND_LABELS = {
 	"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",
@@ -554,6 +915,7 @@ const runCommand = (command) => {
 const REVIEW_SOURCES = new Set([
 	"branch",
 	"commits",
+	"pull_request",
 	"staged"
 ]);
 const REVIEW_STATUSES = new Set([
@@ -584,12 +946,12 @@ const requireValue = (state, flag) => {
 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);
+	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 Either.left(usageError(`Invalid ${label}: ${raw}.`));
-	return Either.right(raw);
+	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) => {
@@ -613,9 +975,9 @@ const positiveIntFlag = (key, opts) => (state, acc) => {
 	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;
+	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. */
@@ -625,8 +987,8 @@ const enumFlag = (key, valid, label) => (state, acc) => {
 	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;
+	if (Result.isFailure(decoded)) return Option.some(decoded.failure);
+	acc[key] = decoded.success;
 	return Option.none();
 };
 const createDefaultOptions = () => ({
@@ -695,8 +1057,8 @@ const parseReviewList = (state) => {
 		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({
+	if (Option.isSome(error)) return Result.fail(error.value);
+	return Result.succeed({
 		kind: "review-list",
 		...acc
 	});
@@ -707,15 +1069,15 @@ const REVIEW_SHOW_FLAGS = {
 };
 const parseReviewShow = (state) => {
 	const id = state.tokens[state.index];
-	if (!id) return Either.left(usageError("review show requires <id|last>."));
+	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 Either.left(error.value);
-	return Either.right({
+	if (Option.isSome(error)) return Result.fail(error.value);
+	return Result.succeed({
 		id,
 		kind: "review-show",
 		...acc
@@ -729,7 +1091,7 @@ const REVIEW_EXPORT_FLAGS = {
 };
 const parseReviewExport = (state) => {
 	const id = state.tokens[state.index];
-	if (!id) return Either.left(usageError("review export requires <id|last>."));
+	if (!id) return Result.fail(usageError("review export requires <id|last>."));
 	state.index += 1;
 	const acc = {
 		noResolved: false,
@@ -738,8 +1100,8 @@ const parseReviewExport = (state) => {
 		stdout: false
 	};
 	const error = runFlagLoop(state, acc, REVIEW_EXPORT_FLAGS, "review export");
-	if (Option.isSome(error)) return Either.left(error.value);
-	return Either.right({
+	if (Option.isSome(error)) return Result.fail(error.value);
+	return Result.succeed({
 		id,
 		kind: "review-export",
 		...acc
@@ -765,10 +1127,10 @@ const parseReviewCreate = (state) => {
 		title: void 0
 	};
 	const error = runFlagLoop(state, acc, REVIEW_CREATE_FLAGS, "review create");
-	if (Option.isSome(error)) return Either.left(error.value);
+	if (Option.isSome(error)) return Result.fail(error.value);
 	const validationError = validateReviewCreate(acc);
-	if (Option.isSome(validationError)) return Either.left(validationError.value);
-	return Either.right({
+	if (Option.isSome(validationError)) return Result.fail(validationError.value);
+	return Result.succeed({
 		kind: "review-create",
 		...acc
 	});
@@ -785,7 +1147,7 @@ const validateSourceDiff = (source, acc) => {
 };
 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>."));
+	if (!source || !REVIEW_SOURCES.has(source)) return Result.fail(usageError("source diff requires <staged|branch|commits>."));
 	state.index += 1;
 	const acc = {
 		branch: void 0,
@@ -793,10 +1155,10 @@ const parseSourceDiff = (state) => {
 		stat: false
 	};
 	const error = runFlagLoop(state, acc, SOURCE_DIFF_FLAGS, "source diff");
-	if (Option.isSome(error)) return Either.left(error.value);
+	if (Option.isSome(error)) return Result.fail(error.value);
 	const validationError = validateSourceDiff(source, acc);
-	if (Option.isSome(validationError)) return Either.left(validationError.value);
-	return Either.right({
+	if (Option.isSome(validationError)) return Result.fail(validationError.value);
+	return Result.succeed({
 		kind: "source-diff",
 		source,
 		...acc
@@ -816,8 +1178,8 @@ const parseTodoList = (state) => {
 		status: "pending"
 	};
 	const error = runFlagLoop(state, acc, TODO_LIST_FLAGS, "todo list");
-	if (Option.isSome(error)) return Either.left(error.value);
-	return Either.right({
+	if (Option.isSome(error)) return Result.fail(error.value);
+	return Result.succeed({
 		kind: "todo-list",
 		...acc
 	});
@@ -828,10 +1190,10 @@ const parseTodoList = (state) => {
 */
 const positionalIdParser = (kind, label) => (state) => {
 	const id = state.tokens[state.index];
-	if (!id) return Either.left(usageError(`${label} requires <id>.`));
+	if (!id) return Result.fail(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({
+	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
 	});
@@ -841,13 +1203,13 @@ 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>."));
+	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 Either.left(error.value);
-	if (acc.position === void 0) return Either.left(usageError("todo move requires --position."));
-	return Either.right({
+	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
@@ -856,12 +1218,12 @@ const parseTodoMove = (state) => {
 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>."));
+	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 Either.left(error.value);
-	return Either.right({
+	if (Option.isSome(error)) return Result.fail(error.value);
+	return Result.succeed({
 		id,
 		kind: "todo-remove",
 		...acc
@@ -881,8 +1243,8 @@ const parseTodoClear = (state) => {
 		yes: false
 	};
 	const error = runFlagLoop(state, acc, TODO_CLEAR_FLAGS, "todo clear");
-	if (Option.isSome(error)) return Either.left(error.value);
-	return Either.right({
+	if (Option.isSome(error)) return Result.fail(error.value);
+	return Result.succeed({
 		kind: "todo-clear",
 		...acc
 	});
@@ -897,8 +1259,8 @@ const parseReviewStatus = (state) => {
 		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({
+	if (Option.isSome(error)) return Result.fail(error.value);
+	return Result.succeed({
 		kind: "review-status",
 		...acc
 	});
@@ -909,15 +1271,15 @@ const REVIEW_RESOLVE_FLAGS = {
 };
 const parseReviewResolve = (state) => {
 	const id = state.tokens[state.index];
-	if (!id) return Either.left(usageError("review resolve requires <id|last>."));
+	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 Either.left(error.value);
-	return Either.right({
+	if (Option.isSome(error)) return Result.fail(error.value);
+	return Result.succeed({
 		id,
 		kind: "review-resolve",
 		...acc
@@ -935,9 +1297,9 @@ const parseTodoAdd = (state) => {
 		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({
+	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
 	});
@@ -966,8 +1328,8 @@ const parseServe = (state) => {
 		username: void 0
 	};
 	const error = runFlagLoop(state, acc, SERVE_FLAGS, "serve");
-	if (Option.isSome(error)) return Either.left(error.value);
-	return Either.right({
+	if (Option.isSome(error)) return Result.fail(error.value);
+	return Result.succeed({
 		kind: "serve",
 		...acc
 	});
@@ -988,8 +1350,8 @@ const parseMcp = (state) => {
 		readonly: false
 	};
 	const error = runFlagLoop(state, acc, MCP_FLAGS, "mcp");
-	if (Option.isSome(error)) return Either.left(error.value);
-	return Either.right({
+	if (Option.isSome(error)) return Result.fail(error.value);
+	return Result.succeed({
 		kind: "mcp",
 		...acc
 	});
@@ -1010,8 +1372,8 @@ const parseEvents = (state) => {
 		type: void 0
 	};
 	const error = runFlagLoop(state, acc, EVENTS_FLAGS, "events");
-	if (Option.isSome(error)) return Either.left(error.value);
-	return Either.right({
+	if (Option.isSome(error)) return Result.fail(error.value);
+	return Result.succeed({
 		kind: "events",
 		...acc
 	});
@@ -1026,8 +1388,8 @@ const parseDataReset = (state) => {
 		yes: false
 	};
 	const error = runFlagLoop(state, acc, DATA_RESET_FLAGS, "data reset");
-	if (Option.isSome(error)) return Either.left(error.value);
-	return Either.right({
+	if (Option.isSome(error)) return Result.fail(error.value);
+	return Result.succeed({
 		kind: "data-reset",
 		...acc
 	});
@@ -1055,13 +1417,32 @@ const TODO_VERB_PARSERS = {
 	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
+	};
+	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 Either.left(error.value);
-		return Either.right({ kind: "data-migrate" });
+		if (Option.isSome(error)) return Result.fail(error.value);
+		return Result.succeed({ kind: "data-migrate" });
 	},
 	reset: parseDataReset
 };
@@ -1069,59 +1450,63 @@ const DATA_VERB_PARSERS = {
 const FAMILY_PARSERS = {
 	data: (state) => {
 		const verb = state.tokens[state.index];
-		if (!verb) return Either.right({
+		if (!verb) return Result.succeed({
 			kind: "help",
 			topic: ["data"]
 		});
 		state.index += 1;
 		const parser = DATA_VERB_PARSERS[verb];
-		if (!parser) return Either.left(usageError(`Unknown data command: ${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 Either.left(error.value);
-		return Either.right({ kind: "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 Either.right({
+		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 Either.left(usageError(`Unknown review command: ${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 Either.right({
+		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 Either.left(error.value);
-			return Either.right({ kind: "source-list" });
+			if (Option.isSome(error)) return Result.fail(error.value);
+			return Result.succeed({ kind: "source-list" });
 		}
 		if (verb === "diff") return parseSourceDiff(state);
-		return Either.left(usageError(`Unknown source command: ${verb}.`));
+		return Result.fail(usageError(`Unknown source command: ${verb}.`));
 	},
 	todo: (state) => {
 		const verb = state.tokens[state.index];
-		if (!verb) return Either.right({
+		if (!verb) return Result.succeed({
 			kind: "help",
 			topic: ["todo"]
 		});
 		state.index += 1;
 		const parser = TODO_VERB_PARSERS[verb];
-		if (!parser) return Either.left(usageError(`Unknown todo command: ${verb}.`));
+		if (!parser) return Result.fail(usageError(`Unknown todo command: ${verb}.`));
 		return parser(state);
 	}
 };
@@ -1131,31 +1516,31 @@ const FAMILY_PARSERS = {
 */
 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({
+	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 Either.right({
+	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 Either.right({
+		return Result.succeed({
 			kind: "help",
 			topic
 		});
 	}
-	if (state.options.help) return Either.right({
+	if (state.options.help) return Result.succeed({
 		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}.`));
+	if (!familyParser) return Result.fail(usageError(`Unknown command: ${first}.`));
 	return familyParser(state);
 };
 const parseCliArgs = (argv) => {
@@ -1165,23 +1550,14 @@ const parseCliArgs = (argv) => {
 		options,
 		tokens: argv
 	});
-	if (Either.isLeft(result)) return Either.left(result.left);
-	return Either.right({
-		command: result.right,
+	if (Result.isFailure(result)) return Result.fail(result.failure);
+	return Result.succeed({
+		command: result.success,
 		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 {
@@ -1198,8 +1574,12 @@ const resolveRepositoryRoot = (repoOverride) => {
 };
 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-status" || command.kind === "todo-list" || command.kind === "review-create" || command.kind === "todo-add" || 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;
@@ -1213,23 +1593,18 @@ const resolveCliConfig = (args) => {
 		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 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))));
-/**
-* 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);
@@ -1245,7 +1620,7 @@ const createCliRuntimeResources = (command, args) => {
 };
 //#endregion
 //#region src/cli/main.ts
-const CLI_VERSION = "0.2.1";
+const CLI_VERSION = "0.3.1";
 const COMMAND_TREE = {
 	commands: [
 		{
@@ -1611,19 +1986,35 @@ const installSignalHandlers = (dispose) => {
 	};
 };
 /**
-* 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).
+* 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.
 */
 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"));
+	const candidates = [];
+	if (import.meta.dirname) {
+		const pkgRoot = resolve(import.meta.dirname, "..");
+		candidates.push(resolve(pkgRoot, "server", "server", "index.mjs"));
+		candidates.push(resolve(pkgRoot, "..", "web", ".output", "server", "index.mjs"));
+	}
+	candidates.push(resolve(process.cwd(), ".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");
+		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);
 	}
 	const env = {
@@ -1670,13 +2061,13 @@ const failAndExit = (opts) => {
 const main = async () => {
 	const argv = process.argv.slice(2);
 	const parseResult = parseCliArgs(argv);
-	if (Either.isLeft(parseResult)) return failAndExit({
+	if (Result.isFailure(parseResult)) return failAndExit({
 		cmdStr: "ringi",
-		error: parseResult.left,
+		error: parseResult.failure,
 		json: argv.includes("--json"),
 		verbose: false
 	});
-	const { command, options } = parseResult.right;
+	const { command, options } = parseResult.success;
 	if (command.kind === "help") {
 		if (options.json) writeJson(success("ringi", COMMAND_TREE, ROOT_NEXT_ACTIONS));
 		else writeHuman(renderHelp(command));