diffing 0.3.0 → 0.4.1

package/README.md

@@ -121,6 +121,7 @@ Full keyboard-driven navigation with vim-like motions and a modal status bar:
 | `n` | Toggle line numbers |
 | `i` | Cycle diff indicators |
 | `I` | Cycle inline diff type |
+| `Cmd+Shift+P` | Toggle preview mode in comments |
 
 ### File Navigation & UI
 | Key | Action |
@@ -268,7 +269,8 @@ diffing url                          # Retrieve the active server base URL
 diffing plan submit <file> [--title T] [--model M] [--id <id>] [--wait]   # Submit/resubmit a plan; prints its id
 diffing plan await [--timeout N]     # Block until the human approves/rejects/requests-changes; outputs the verdict XML
 diffing plan list [--json]           # List submitted plans with their verdicts
-diffing plan show [<id>] [--json]    # Show one plan as <plan-review> XML (latest if omitted)
+diffing plan show [<id>] [--json] [--version N]   # Show one plan as <plan-review> XML (latest if omitted; use --version to read a historical body)
+diffing plan versions <id> [--json]  # List every submitted version of a plan, oldest-first (current marked with `*`)
 diffing plan reply <commentId> --body "..."   # Reply to an inline plan comment
 diffing plan resolve <commentId>     # Mark a plan comment resolved
 ```
@@ -286,7 +288,7 @@ If your agent supports MCP (such as Cursor, Claude Desktop, or Gemini), configur
   }
 }
 ```
-Exposes tools directly to your agent for both review flows — diff review: `await_review`, `list_comments`, `reply_to_comment`, `resolve_comment`; and plan review: `submit_plan`, `await_plan_review`, `list_plans`, `get_plan`, `reply_to_plan_comment`, `resolve_plan_comment`.
+Exposes tools directly to your agent for both review flows — diff review: `await_review`, `list_comments`, `reply_to_comment`, `resolve_comment`; and plan review: `submit_plan`, `await_plan_review`, `list_plans`, `get_plan`, `get_plan_versions`, `get_plan_version`, `reply_to_plan_comment`, `resolve_plan_comment`.
 
 ### C. Agent Skills
 You can install diffing skills directly into your AI coding assistant:
@@ -336,6 +338,13 @@ releases" handoff, applied *before* any code is written.
 - **Three-way verdict** — Approve / Request changes / Reject, GitHub-style, with
   an optional overall comment. Resubmitting a revised plan (same id) bumps the
   version and re-opens it for review.
+- **Browse plan versions** — every submitted body is kept on disk, oldest-first.
+  A version dropdown next to the `v{n}` chip switches the viewer to any past
+  version; comments are filtered to those anchored to the version you're
+  reading; a "viewing v{N} of v{M}" banner makes the historical context obvious.
+  Available from the CLI (`diffing plan versions <id>`, `diffing plan show <id> --version N`),
+  MCP (`get_plan_versions`, `get_plan_version`), and the HTTP API
+  (`GET /api/plans/:id/versions`, `GET /api/plans/:id/versions/:n`).
 - **Live "Plans" badge** — the diff toolbar shows a badge counting plans awaiting
   your review, with a green dot when an agent is connected and waiting.
 - **Same channels everywhere** — drive it from the CLI (`diffing plan …`), the

package/dist/cli-agent-B4hU6Xay.mjs

@@ -0,0 +1,499 @@
+import { a as formatComments, n as readServerLock, t as isLockAlive } from "./server-lock-D73NKKbn.mjs";
+import { n as formatPlanReview } from "./plan-format-mSDtsPcC.mjs";
+import { parseArgs } from "node:util";
+import { readFile } from "node:fs/promises";
+//#region src/cli-agent.ts
+/**
+* Agent-facing `diffing` subcommands. These make the user→agent handoff
+* port-agnostic: each resolves the running server via the per-repo lockfile
+* (`server.json`) so any agent with a shell — or a human — can drive the loop
+* without being told a port.
+*
+*   diffing await-review   block until the human clicks "Send to agent"
+*   diffing reply <id>     post an agent reply to a comment
+*   diffing resolve <id>   mark a comment resolved
+*   diffing comments       dump the current comments (XML or JSON)
+*/
+const EXIT_OK = 0;
+const EXIT_AWAIT_TIMEOUT = 2;
+const EXIT_NO_SERVER = 3;
+const EXIT_NOT_FOUND = 4;
+const EXIT_USAGE = 5;
+/** Resolve the running server's base URL from the lockfile, or exit cleanly. */
+function baseUrl() {
+	const lock = readServerLock();
+	if (!lock || !isLockAlive(lock)) {
+		console.error("No diffing server running for this repo. Start one with `diffing`.");
+		process.exit(EXIT_NO_SERVER);
+	}
+	return `http://${lock.host === "0.0.0.0" || lock.host === "::" ? "127.0.0.1" : lock.host}:${lock.port}`;
+}
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(chunk);
+	return Buffer.concat(chunks).toString("utf-8");
+}
+async function awaitReview(args) {
+	const { values } = parseArgs({
+		args,
+		options: {
+			timeout: {
+				type: "string",
+				short: "t"
+			},
+			since: { type: "string" }
+		},
+		allowPositionals: false
+	});
+	const totalBudgetMs = (values.timeout ? Number(values.timeout) : 570) * 1e3;
+	const base = baseUrl();
+	let sinceRound = 0;
+	try {
+		sinceRound = (await fetch(`${base}/api/review/status`).then((r) => r.json())).round ?? 0;
+	} catch {}
+	const deadline = Date.now() + totalBudgetMs;
+	while (Date.now() < deadline) {
+		let res;
+		try {
+			res = await fetch(`${base}/api/review/await?timeoutMs=25000&sinceRound=${sinceRound}`, { signal: AbortSignal.timeout(3e4) });
+		} catch (err) {
+			if (err?.name === "TimeoutError") continue;
+			console.error(`Failed to reach diffing server: ${err?.message ?? err}`);
+			return EXIT_NO_SERVER;
+		}
+		const result = await res.json();
+		if (result.status === "released") {
+			process.stdout.write(result.payload.commentXml + "\n");
+			console.error(`DIFFING_REVIEW_ROUND=${result.payload.round}`);
+			return EXIT_OK;
+		}
+		sinceRound = result.round ?? sinceRound;
+	}
+	console.error("DIFFING_AWAIT_TIMEOUT");
+	console.error("No review sent within the timeout. Run `diffing await-review` again to keep waiting.");
+	return EXIT_AWAIT_TIMEOUT;
+}
+async function reply(args) {
+	const { values, positionals } = parseArgs({
+		args,
+		options: {
+			body: {
+				type: "string",
+				short: "b"
+			},
+			model: {
+				type: "string",
+				short: "m"
+			}
+		},
+		allowPositionals: true
+	});
+	const commentId = positionals[0];
+	if (!commentId) {
+		console.error("Usage: diffing reply <commentId> --body <text> [--model <name>]");
+		return EXIT_USAGE;
+	}
+	let body = values.body;
+	if (body === "-" || body === void 0) body = (await readStdin()).trim();
+	if (!body) {
+		console.error("A reply body is required (--body <text> or pipe via stdin).");
+		return EXIT_USAGE;
+	}
+	const res = await fetch(`${baseUrl()}/api/comments/${commentId}/replies`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			body,
+			role: "agent",
+			model: values.model
+		})
+	});
+	if (res.status === 404) {
+		console.error(`Comment ${commentId} not found.`);
+		return EXIT_NOT_FOUND;
+	}
+	if (!res.ok) {
+		console.error(`Failed to reply: HTTP ${res.status}`);
+		return 1;
+	}
+	console.error(`Replied to ${commentId}.`);
+	return EXIT_OK;
+}
+async function resolve(args) {
+	const { positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {}
+	});
+	const commentId = positionals[0];
+	if (!commentId) {
+		console.error("Usage: diffing resolve <commentId>");
+		return EXIT_USAGE;
+	}
+	const res = await fetch(`${baseUrl()}/api/comments/${commentId}`, {
+		method: "PUT",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ status: "resolved" })
+	});
+	if (res.status === 404) {
+		console.error(`Comment ${commentId} not found.`);
+		return EXIT_NOT_FOUND;
+	}
+	if (!res.ok) {
+		console.error(`Failed to resolve: HTTP ${res.status}`);
+		return 1;
+	}
+	console.error(`Resolved ${commentId}.`);
+	return EXIT_OK;
+}
+async function url() {
+	process.stdout.write(baseUrl() + "\n");
+	return EXIT_OK;
+}
+async function comments(args) {
+	const { values } = parseArgs({
+		args,
+		options: {
+			open: { type: "boolean" },
+			json: { type: "boolean" }
+		},
+		allowPositionals: false
+	});
+	const all = await fetch(`${baseUrl()}/api/comments`).then((r) => r.json());
+	const selected = values.open ? all.filter((c) => c.status === "open") : all;
+	if (values.json) process.stdout.write(JSON.stringify(selected, null, 2) + "\n");
+	else process.stdout.write(formatComments(selected) + "\n");
+	return EXIT_OK;
+}
+/** Derive a human title from a plan's first heading or non-empty line. */
+function deriveTitle(body) {
+	for (const raw of body.split("\n")) {
+		const line = raw.trim();
+		if (!line) continue;
+		const heading = /^#{1,6}\s+(.*)$/.exec(line);
+		return (heading ? heading[1] : line).slice(0, 120);
+	}
+	return "Untitled plan";
+}
+/** Long-poll the plan-review handoff until a decision arrives or time runs out. */
+async function pollPlanDecision(base, totalBudgetMs, seedSince) {
+	let sinceRound = seedSince ?? 0;
+	if (seedSince === void 0) try {
+		sinceRound = (await fetch(`${base}/api/plan-review/status`).then((r) => r.json())).round ?? 0;
+	} catch {}
+	const deadline = Date.now() + totalBudgetMs;
+	while (Date.now() < deadline) {
+		let res;
+		try {
+			res = await fetch(`${base}/api/plan-review/await?timeoutMs=25000&sinceRound=${sinceRound}`, { signal: AbortSignal.timeout(3e4) });
+		} catch (err) {
+			if (err?.name === "TimeoutError") continue;
+			console.error(`Failed to reach diffing server: ${err?.message ?? err}`);
+			return EXIT_NO_SERVER;
+		}
+		const result = await res.json();
+		if (result.status === "released") {
+			process.stdout.write(result.payload.reviewXml + "\n");
+			console.error(`DIFFING_PLAN_DECISION=${result.payload.decision}`);
+			console.error(`DIFFING_PLAN_ROUND=${result.payload.round}`);
+			return EXIT_OK;
+		}
+		sinceRound = result.round ?? sinceRound;
+	}
+	console.error("DIFFING_PLAN_AWAIT_TIMEOUT");
+	console.error("No plan decision within the timeout. Run `diffing plan await` again to keep waiting.");
+	return EXIT_AWAIT_TIMEOUT;
+}
+async function planSubmit(args) {
+	const { values, positionals } = parseArgs({
+		args,
+		options: {
+			title: { type: "string" },
+			source: {
+				type: "string",
+				short: "s"
+			},
+			model: {
+				type: "string",
+				short: "m"
+			},
+			id: { type: "string" },
+			wait: {
+				type: "boolean",
+				short: "w"
+			},
+			timeout: {
+				type: "string",
+				short: "t"
+			}
+		},
+		allowPositionals: true
+	});
+	const file = positionals[0];
+	let body;
+	if (!file || file === "-") body = await readStdin();
+	else try {
+		body = await readFile(file, "utf-8");
+	} catch (err) {
+		console.error(`Failed to read plan file ${file}: ${err?.message ?? err}`);
+		return EXIT_USAGE;
+	}
+	body = body.replace(/\r\n/g, "\n");
+	if (!body.trim()) {
+		console.error("A plan body is required (pass a markdown file path or pipe via stdin).");
+		return EXIT_USAGE;
+	}
+	const title = values.title || deriveTitle(body);
+	const base = baseUrl();
+	let sinceRound = 0;
+	if (values.wait) try {
+		sinceRound = (await fetch(`${base}/api/plan-review/status`).then((r) => r.json())).round ?? 0;
+	} catch {}
+	const res = await fetch(`${base}/api/plans`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			id: values.id,
+			title,
+			body,
+			source: values.source,
+			model: values.model
+		})
+	});
+	if (!res.ok) {
+		console.error(`Failed to submit plan: HTTP ${res.status}`);
+		return 1;
+	}
+	const plan = await res.json();
+	console.error(`Submitted plan ${plan.id} (v${plan.version}) — review at ${base}/plan/${plan.id}`);
+	if (!values.wait) {
+		process.stdout.write(plan.id + "\n");
+		return EXIT_OK;
+	}
+	return pollPlanDecision(base, (values.timeout ? Number(values.timeout) : 570) * 1e3, sinceRound);
+}
+async function planAwait(args) {
+	const { values } = parseArgs({
+		args,
+		options: { timeout: {
+			type: "string",
+			short: "t"
+		} },
+		allowPositionals: false
+	});
+	const totalBudgetMs = (values.timeout ? Number(values.timeout) : 570) * 1e3;
+	return pollPlanDecision(baseUrl(), totalBudgetMs);
+}
+async function planList(args) {
+	const { values } = parseArgs({
+		args,
+		options: { json: { type: "boolean" } },
+		allowPositionals: false
+	});
+	const all = await fetch(`${baseUrl()}/api/plans`).then((r) => r.json());
+	if (values.json) {
+		process.stdout.write(JSON.stringify(all, null, 2) + "\n");
+		return EXIT_OK;
+	}
+	if (all.length === 0) {
+		console.error("No plans submitted yet.");
+		return EXIT_OK;
+	}
+	for (const p of all) {
+		const open = (p.comments ?? []).filter((c) => c.status === "open").length;
+		process.stdout.write(`${p.id}\t[${p.decision}]\tv${p.version}\t${open} open comment(s)\t${p.title}\n`);
+	}
+	return EXIT_OK;
+}
+async function planShow(args) {
+	const { values, positionals } = parseArgs({
+		args,
+		options: {
+			json: { type: "boolean" },
+			version: { type: "string" }
+		},
+		allowPositionals: true
+	});
+	const base = baseUrl();
+	let planId = positionals[0];
+	if (!planId) {
+		const all = await fetch(`${base}/api/plans`).then((r) => r.json());
+		if (all.length === 0) {
+			console.error("No plans submitted yet.");
+			return EXIT_NOT_FOUND;
+		}
+		planId = all[all.length - 1].id;
+	}
+	const res = await fetch(`${base}/api/plans/${planId}`);
+	if (res.status === 404) {
+		console.error(`Plan ${planId} not found.`);
+		return EXIT_NOT_FOUND;
+	}
+	const plan = await res.json();
+	const requestedVersion = values.version !== void 0 ? Number(values.version) : void 0;
+	if (requestedVersion !== void 0 && (!Number.isFinite(requestedVersion) || requestedVersion < 1)) {
+		console.error(`--version must be a positive integer.`);
+		return EXIT_USAGE;
+	}
+	if (requestedVersion !== void 0 && requestedVersion !== plan.version) {
+		if (!(plan.versions ?? []).find((v) => v.version === requestedVersion)) {
+			console.error(`Version ${requestedVersion} not found for plan ${planId} (current: v${plan.version}).`);
+			return EXIT_NOT_FOUND;
+		}
+	}
+	if (values.json) process.stdout.write(JSON.stringify(plan, null, 2) + "\n");
+	else process.stdout.write(formatPlanReview(plan, { viewingVersion: requestedVersion }) + "\n");
+	return EXIT_OK;
+}
+async function planVersions(args) {
+	const { values, positionals } = parseArgs({
+		args,
+		options: { json: { type: "boolean" } },
+		allowPositionals: true
+	});
+	const base = baseUrl();
+	let planId = positionals[0];
+	if (!planId) {
+		console.error("Usage: diffing plan versions <id> [--json]");
+		return EXIT_USAGE;
+	}
+	const planRes = await fetch(`${base}/api/plans/${planId}`);
+	if (planRes.status === 404) {
+		console.error(`Plan ${planId} not found.`);
+		return EXIT_NOT_FOUND;
+	}
+	const plan = await planRes.json();
+	const versions = plan.versions ?? [];
+	if (values.json) {
+		process.stdout.write(JSON.stringify(versions, null, 2) + "\n");
+		return EXIT_OK;
+	}
+	if (versions.length === 0) {
+		console.error("This plan has no recorded versions.");
+		return EXIT_OK;
+	}
+	for (const v of versions) {
+		const marker = v.version === plan.version ? "*" : " ";
+		const date = new Date(v.createdAt).toISOString().slice(0, 16).replace("T", " ");
+		process.stdout.write(`${marker} v${v.version}\t${date}\t${v.title}\n`);
+	}
+	return EXIT_OK;
+}
+/** Locate which plan owns a given comment id (comment ids are globally unique). */
+async function findCommentPlan(base, commentId) {
+	return (await fetch(`${base}/api/plans`).then((r) => r.json())).find((p) => (p.comments ?? []).some((c) => c.id === commentId)) ?? null;
+}
+async function planReply(args) {
+	const { values, positionals } = parseArgs({
+		args,
+		options: {
+			body: {
+				type: "string",
+				short: "b"
+			},
+			model: {
+				type: "string",
+				short: "m"
+			}
+		},
+		allowPositionals: true
+	});
+	const commentId = positionals[0];
+	if (!commentId) {
+		console.error("Usage: diffing plan reply <commentId> --body <text> [--model <name>]");
+		return EXIT_USAGE;
+	}
+	let body = values.body;
+	if (body === "-" || body === void 0) body = (await readStdin()).trim();
+	if (!body) {
+		console.error("A reply body is required (--body <text> or pipe via stdin).");
+		return EXIT_USAGE;
+	}
+	const base = baseUrl();
+	const plan = await findCommentPlan(base, commentId);
+	if (!plan) {
+		console.error(`Plan comment ${commentId} not found.`);
+		return EXIT_NOT_FOUND;
+	}
+	const res = await fetch(`${base}/api/plans/${plan.id}/comments/${commentId}/replies`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			body,
+			role: "agent",
+			model: values.model
+		})
+	});
+	if (!res.ok) {
+		console.error(`Failed to reply: HTTP ${res.status}`);
+		return 1;
+	}
+	console.error(`Replied to plan comment ${commentId}.`);
+	return EXIT_OK;
+}
+async function planResolve(args) {
+	const { positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: {}
+	});
+	const commentId = positionals[0];
+	if (!commentId) {
+		console.error("Usage: diffing plan resolve <commentId>");
+		return EXIT_USAGE;
+	}
+	const base = baseUrl();
+	const plan = await findCommentPlan(base, commentId);
+	if (!plan) {
+		console.error(`Plan comment ${commentId} not found.`);
+		return EXIT_NOT_FOUND;
+	}
+	const res = await fetch(`${base}/api/plans/${plan.id}/comments/${commentId}`, {
+		method: "PUT",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ status: "resolved" })
+	});
+	if (!res.ok) {
+		console.error(`Failed to resolve: HTTP ${res.status}`);
+		return 1;
+	}
+	console.error(`Resolved plan comment ${commentId}.`);
+	return EXIT_OK;
+}
+async function plan(args) {
+	const action = args[0];
+	const rest = args.slice(1);
+	switch (action) {
+		case "submit": return planSubmit(rest);
+		case "await": return planAwait(rest);
+		case "list": return planList(rest);
+		case "show": return planShow(rest);
+		case "versions": return planVersions(rest);
+		case "reply": return planReply(rest);
+		case "resolve": return planResolve(rest);
+		default:
+			console.error("Usage: diffing plan <submit|await|list|show|versions|reply|resolve> [...]");
+			return EXIT_USAGE;
+	}
+}
+async function runSubcommand(name, args) {
+	switch (name) {
+		case "await-review": return awaitReview(args);
+		case "reply": return reply(args);
+		case "resolve": return resolve(args);
+		case "comments": return comments(args);
+		case "url": return url();
+		case "plan": return plan(args);
+		case "update":
+			const { runUpdateCommand } = await import("./update-check-DAPFCqpF.mjs");
+			return runUpdateCommand();
+		case "gh":
+			const { runGhSubcommand } = await import("./cli-gh-abs-IJrz.mjs");
+			return runGhSubcommand(args);
+		default:
+			console.error(`Unknown subcommand: ${name}`);
+			return EXIT_USAGE;
+	}
+}
+//#endregion
+export { runSubcommand };