diffing 0.4.1 → 0.5.1

package/README.md

@@ -276,7 +276,9 @@ diffing plan resolve <commentId>     # Mark a plan comment resolved
 ```
 
 ### B. Model Context Protocol (MCP) Server
-If your agent supports MCP (such as Cursor, Claude Desktop, or Gemini), configure `diffing` as a stdio-based MCP server. No ports need to be configured:
+If your agent supports MCP, configure `diffing` as a stdio server. The MCP is
+self-describing and can start or reuse the loopback review server, so an
+MCP-only agent does not need to know a port or fall back to raw HTTP:
 
 ```json
 {
@@ -288,18 +290,50 @@ 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`, `get_plan_versions`, `get_plan_version`, `reply_to_plan_comment`, `resolve_plan_comment`.
+
+Global/desktop clients that do not launch MCP from the workspace should bind it
+to one repository explicitly:
+
+```json
+{
+  "mcpServers": {
+    "diffing": {
+      "command": "diffing",
+      "args": ["mcp", "--repo", "/absolute/path/to/repository"]
+    }
+  }
+}
+```
+
+Run `diffing mcp --help` for setup details. The server initialization
+instructions tell an unfamiliar model what to do next, and every tool returns
+both readable text and structured content.
+
+- Session: `review_session_status`, `start_review_session`
+- Local review: `get_diff`, `create_comment`, `await_review`, `list_comments`, `reply_to_comment`, `resolve_comment`
+- Plan review: `submit_plan`, `await_plan_review`, `list_plans`, `get_plan`, `get_plan_versions`, `get_plan_version`, `reply_to_plan_comment`, `resolve_plan_comment`
+
+Clients that expose MCP prompts can use `review_local_changes` and
+`submit_plan_for_review`; clients that expose resources can read
+`diffing://agent-guide`. Essential guidance is also present in initialization
+instructions and tool descriptions because prompt/resource support varies.
 
 ### C. Agent Skills
 You can install diffing skills directly into your AI coding assistant:
 ```bash
 npx skills add ahmedragab20/diffing
 ```
-Provides commands to coordinate reviews:
-1. **`/diffing-start-review`** — Launches the review server.
-2. **`/diffing-finish-review`** — Blocks the agent using `await-review` until comments are sent, then applies requested edits.
-3. **`/diffing-review`** — Combined launch-and-wait flow.
-4. **`/diffing-plan-review`** — Submit a markdown plan, block until the human approves/rejects/requests changes, then proceed or revise.
+Installs five portable, natural-language-triggered workflows:
+
+1. **`diffing`** — Detects MCP/CLI/offline capabilities and routes the request.
+2. **`diffing-start-review`** — Starts or reuses the review session and returns its URL.
+3. **`diffing-finish-review`** — Waits for human feedback, applies clear requests, and synchronizes replies/resolutions live.
+4. **`diffing-review`** — Inspects the full local diff and posts actionable inline findings.
+5. **`diffing-plan-review`** — Gates implementation on a reviewed plan and deterministic verdict handling.
+
+The skills prefer native MCP tools, fall back to the port-agnostic CLI, and can
+still interpret pasted self-describing XML. The installable `skills/` copies and
+repo-local `.agents/skills/` copies are contract-tested to remain identical.
 
 ### Send Review Popover
 A GitHub-style "finish your review" popover with inline editing of each comment, an optional general/overall comment, and a visual indicator when an agent is waiting. The **"Copy comments"** toolbar button serializes all comments to the XML spec and copies them to the clipboard.

package/dist/cli-agent-BatQgghr.mjs

@@ -0,0 +1,499 @@
+import { i as readServerLock, r as isLockAlive, s as formatComments } from "./server-lock-C_wPtEsH.mjs";
+import { n as formatPlanReview } from "./plan-format-B6nbAw_c.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-CXeSZANo.mjs");
+			return runUpdateCommand();
+		case "gh":
+			const { runGhSubcommand } = await import("./cli-gh-DiT8BWwu.mjs");
+			return runGhSubcommand(args);
+		default:
+			console.error(`Unknown subcommand: ${name}`);
+			return EXIT_USAGE;
+	}
+}
+//#endregion
+export { runSubcommand };