diffing 0.17.0 → 0.18.0

package/dist/mockup-format-CM3ivHHX.mjs

@@ -0,0 +1,322 @@
+const MOCKUP_MAX_SCREEN_BYTES = Math.floor(1.5 * 1024 * 1024);
+const MOCKUP_SCREEN_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+function isMockupViewport(value) {
+	return value === "desktop" || value === "tablet" || value === "mobile";
+}
+function normalizeMockupViewport(value) {
+	return isMockupViewport(value) ? value : "desktop";
+}
+/** Effective viewport of a comment; legacy comments (no viewport) anchor on desktop. */
+function commentViewport(comment) {
+	return comment.viewport ?? "desktop";
+}
+function defaultScreenLabel(id) {
+	if (id === "main") return "Main";
+	return id.split(/[-_]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function slugifyScreenId(raw) {
+	const slug = raw.trim().toLowerCase().replace(/\.html?$/i, "").replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+	if (!MOCKUP_SCREEN_ID_RE.test(slug)) return null;
+	return slug;
+}
+function normalizeSubmitScreens(input) {
+	const hasHtml = typeof input.html === "string" && input.html.length > 0;
+	const hasScreens = Array.isArray(input.screens) && input.screens.length > 0;
+	if (hasHtml && hasScreens) return {
+		ok: false,
+		error: "Provide either html or screens, not both"
+	};
+	const raw = hasScreens ? input.screens : hasHtml ? [{
+		id: "main",
+		label: "Main",
+		html: input.html
+	}] : [];
+	if (raw.length === 0) return {
+		ok: false,
+		error: "A mockup html body or screens[] is required"
+	};
+	if (raw.length > 12) return {
+		ok: false,
+		error: `At most 12 screens are allowed`
+	};
+	const seen = /* @__PURE__ */ new Set();
+	const screens = [];
+	for (const item of raw) {
+		if (typeof item.html !== "string" || !item.html.trim()) return {
+			ok: false,
+			error: "Each screen needs a non-empty html body"
+		};
+		if (Buffer.byteLength(item.html, "utf8") > 1572864) return {
+			ok: false,
+			error: `Each screen must be ≤ ${MOCKUP_MAX_SCREEN_BYTES} bytes`
+		};
+		const id = item.id ? slugifyScreenId(item.id) : slugifyScreenId("main");
+		if (!id) return {
+			ok: false,
+			error: `Invalid screen id "${item.id ?? ""}"`
+		};
+		if (seen.has(id)) return {
+			ok: false,
+			error: `Duplicate screen id "${id}"`
+		};
+		seen.add(id);
+		const label = typeof item.label === "string" && item.label.trim() ? item.label.trim() : defaultScreenLabel(id);
+		screens.push({
+			id,
+			label,
+			html: item.html.replace(/\r\n/g, "\n")
+		});
+	}
+	return {
+		ok: true,
+		screens
+	};
+}
+//#endregion
+//#region src/lib/plan-format.ts
+/**
+* Serialize a reviewed plan into the `<plan-review>` XML envelope handed back to
+* a waiting agent. The diff-review counterpart is {@link formatComments}; this
+* keeps the two handoffs structurally consistent so an agent learns one shape.
+*
+* Shared by the server's `/api/plan-review/await` handoff, the `diffing plan`
+* CLI, and the MCP server so every channel emits byte-identical output.
+*/
+function escapeAttr$1(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+/** Human-readable guidance the agent should act on, derived from the verdict. */
+function decisionSummary(decision) {
+	switch (decision) {
+		case "approved": return "The reviewer APPROVED this plan. Proceed with implementation exactly as described, taking any inline comments into account.";
+		case "rejected": return "The reviewer REJECTED this plan. Do NOT proceed. Reconsider the approach based on the comments; only continue once a new plan is approved.";
+		case "changes-requested": return "The reviewer REQUESTED CHANGES. Revise the plan to address every open comment below, then resubmit the updated plan for re-review (do not start implementation yet).";
+		case "comment-only": return "The reviewer chose COMMENT-ONLY mode. You MUST NOT edit any files or implement the plan. Only reply to the comments below — answer questions, provide clarification, or discuss. The decision comment (if present) is your prompt for this chat.";
+		default: return "This plan has not been decided yet. Wait for the reviewer to approve, reject, or request changes.";
+	}
+}
+/**
+* Resolve the line label for a plan comment: `plan` for whole-plan notes,
+* `12-15` for a multi-line selection, otherwise the single line number.
+*/
+function lineLabel(comment) {
+	if (comment.lineNumber === 0) return "plan";
+	if (comment.startLineNumber && comment.startLineNumber !== comment.lineNumber) return `${comment.startLineNumber}-${comment.lineNumber}`;
+	return `${comment.lineNumber}`;
+}
+function formatPlanReview(plan, options = {}) {
+	const { viewingVersion, mode } = options;
+	const isHistorical = viewingVersion !== void 0 && viewingVersion !== plan.version;
+	const versions = plan.versions ?? [];
+	const historical = isHistorical && versions.length > 0 ? versions.find((v) => v.version === viewingVersion) : void 0;
+	const bodyToRender = historical ? historical.body : plan.body;
+	const titleToRender = historical ? historical.title : plan.title;
+	const visibleComments = isHistorical ? (plan.comments ?? []).filter((c) => c.createdAtPlanVersion === viewingVersion) : plan.comments ?? [];
+	const modeAttr = mode && mode !== "standard" ? ` mode="${mode}"` : "";
+	const lines = [];
+	lines.push("<plan-review>");
+	lines.push("  <instructions>");
+	lines.push("    You are an AI coding assistant receiving a human review of a plan you submitted.");
+	if (mode === "comment-only") lines.push("    ⚠️ COMMENT-ONLY MODE: You MUST NOT edit any files or implement the plan. Your only task is to reply to the comments below — answer questions, provide clarification, or discuss. The decision comment (if present) is your prompt for this chat.");
+	else {
+		lines.push("    - The \"decision\" attribute is the headline verdict: \"approved\", \"rejected\", \"changes-requested\", \"comment-only\", or \"pending\".");
+		lines.push("    - <decision-summary> tells you, in plain language, what to do next based on that verdict.");
+		lines.push("    - <decision-comment> is the reviewer's overall note (may be absent).");
+		lines.push("    - <plan-body> is the exact markdown of the plan being reviewed. Inline comments target lines within it.");
+		lines.push("    - Each <comment> targets a line (\"line=42\"), a range (\"line=12-15\"), or the whole plan (\"line=plan\").");
+		lines.push("      \"section\" names the nearest markdown heading for context. Only address comments with status=\"open\".");
+		lines.push("    - <context> is structured: <quote> is the exact text the human highlighted (when present);");
+		lines.push("      <source line=\"N\" end-line=\"M\"> is the full plan source line(s). Prefer <quote> when deciding what they meant.");
+		lines.push("    - Optional severity=\"blocking|nit|question|praise\" on <comment>: treat blocking as must-fix,");
+		lines.push("      nit as optional polish, question as needing an answer, praise as positive note (no action required).");
+		lines.push("");
+		lines.push("    HOW TO RESPOND:");
+		lines.push("    - If approved: proceed with the work.");
+		lines.push("    - If changes-requested: revise the plan and resubmit it for another review round.");
+		lines.push("    - If rejected: stop and rethink; do not implement.");
+		lines.push("    - If comment-only: do NOT implement; only reply to comments.");
+		lines.push("    Prefer the diffing CLI or MCP (port-agnostic, no copy-paste):");
+		lines.push("      diffing plan reply <comment-id> --body \"...\" --model \"<your-model-name>\"");
+		lines.push("      diffing plan resolve <comment-id>");
+		lines.push("      diffing plan submit <revised-plan.md> --id <plan-id>   # resubmit a new version for re-review");
+		lines.push("    (Or the equivalent MCP tools: reply_to_plan_comment, resolve_plan_comment, submit_plan.)");
+	}
+	lines.push("  </instructions>");
+	const decidedAttr = plan.decidedAt ? ` decided-at="${new Date(plan.decidedAt).toISOString()}"` : "";
+	const viewingAttr = isHistorical ? ` viewing-version="${viewingVersion}"` : "";
+	lines.push(`  <plan id="${escapeAttr$1(plan.id)}" title="${escapeAttr$1(titleToRender)}" version="${plan.version}" decision="${plan.decision}"${decidedAttr}${viewingAttr}${modeAttr}>`);
+	lines.push(`    <decision-summary><![CDATA[${decisionSummary(plan.decision)}]]></decision-summary>`);
+	const trimmedDecisionComment = plan.decisionComment?.trim();
+	if (trimmedDecisionComment) lines.push(`    <decision-comment><![CDATA[${trimmedDecisionComment}]]></decision-comment>`);
+	if (isHistorical) lines.push(`    <viewing-version-info><![CDATA[Reviewing historical version ${viewingVersion} of ${plan.version}. Comments are filtered to those anchored to v${viewingVersion}.]]></viewing-version-info>`);
+	lines.push(`    <plan-body><![CDATA[${bodyToRender}]]></plan-body>`);
+	if (visibleComments.length > 0) {
+		lines.push("    <comments>");
+		for (const comment of visibleComments) {
+			const sectionAttr = comment.sectionTitle ? ` section="${escapeAttr$1(comment.sectionTitle)}"` : "";
+			const isoDate = new Date(comment.createdAt).toISOString();
+			const versionAttr = ` plan-version="${comment.createdAtPlanVersion ?? plan.version}"`;
+			const severityAttr = comment.severity && comment.severity !== "none" ? ` severity="${comment.severity}"` : "";
+			lines.push(`      <comment id="${escapeAttr$1(comment.id)}" line="${lineLabel(comment)}"${sectionAttr} status="${comment.status}"${severityAttr} created-at="${isoDate}"${versionAttr}>`);
+			if (comment.lineNumber !== 0 && (comment.lineContent || comment.selectedQuote)) {
+				const start = comment.startLineNumber && comment.startLineNumber !== comment.lineNumber ? comment.startLineNumber : comment.lineNumber;
+				const end = comment.lineNumber;
+				const endAttr = end !== start ? ` end-line="${end}"` : "";
+				lines.push(`        <context line="${start}"${endAttr}>`);
+				if (comment.selectedQuote?.trim()) lines.push(`          <quote><![CDATA[${comment.selectedQuote.trim()}]]></quote>`);
+				if (comment.lineContent) lines.push(`          <source line="${start}"${endAttr}><![CDATA[${comment.lineContent}]]></source>`);
+				lines.push("        </context>");
+			}
+			lines.push(`        <body><![CDATA[${comment.body}]]></body>`);
+			if (comment.replies && comment.replies.length > 0) {
+				lines.push("        <replies>");
+				for (const reply of comment.replies) {
+					const replyIsoDate = new Date(reply.createdAt).toISOString();
+					const roleAttr = reply.role ? ` role="${reply.role}"` : " role=\"agent\"";
+					const modelAttr = reply.model ? ` model="${escapeAttr$1(reply.model)}"` : "";
+					lines.push(`          <reply id="${escapeAttr$1(reply.id)}" created-at="${replyIsoDate}"${roleAttr}${modelAttr}>`);
+					lines.push(`            <![CDATA[${reply.body}]]>`);
+					lines.push("          </reply>");
+				}
+				lines.push("        </replies>");
+			}
+			lines.push("      </comment>");
+		}
+		lines.push("    </comments>");
+	}
+	lines.push("  </plan>");
+	lines.push("</plan-review>");
+	return lines.join("\n");
+}
+/**
+* Find the nearest markdown ATX heading at or above a 1-based line, so a comment
+* can record which section of the plan it belongs to. Returns the heading text
+* without the leading `#`s, or undefined when the line precedes any heading.
+*/
+function sectionTitleForLine(body, lineNumber) {
+	if (lineNumber < 1) return void 0;
+	const lines = body.split("\n");
+	const end = Math.min(lineNumber, lines.length);
+	for (let i = end - 1; i >= 0; i--) {
+		const match = /^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$/.exec(lines[i]);
+		if (match) return match[2].trim();
+	}
+}
+/**
+* Snapshot the plan text spanned by a 1-based, inclusive [start, end] line
+* range, used as the `lineContent` anchor when a comment is created without one
+* (e.g. posted by an agent over the API).
+*/
+function extractPlanLines(body, startLine, endLine) {
+	if (startLine < 1) return "";
+	const lines = body.split("\n");
+	const from = Math.max(1, startLine);
+	const to = Math.min(endLine, lines.length);
+	if (to < from) return "";
+	return lines.slice(from - 1, to).join("\n");
+}
+//#endregion
+//#region src/lib/mockup-format.ts
+function escapeAttr(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function mockupDecisionSummary(decision) {
+	return decisionSummary(decision).replaceAll("plan", "mockup").replaceAll("Plan", "Mockup").replaceAll("PLAN", "MOCKUP");
+}
+function formatMockupReview(mockup, options = {}) {
+	const { viewingVersion, mode, focusedScreen, focusedViewport, instructions } = options;
+	const isHistorical = viewingVersion !== void 0 && viewingVersion !== mockup.version;
+	const versions = mockup.versions ?? [];
+	const historical = isHistorical && versions.length > 0 ? versions.find((v) => v.version === viewingVersion) : void 0;
+	const titleToRender = historical ? historical.title : mockup.title;
+	const screensToRender = historical ? historical.screens : mockup.screens;
+	const commentVersion = viewingVersion ?? mockup.version;
+	const visibleComments = (mockup.comments ?? []).filter((comment) => comment.status === "open" && comment.createdAtMockupVersion === commentVersion && (!focusedScreen || comment.screenId === focusedScreen) && (!focusedViewport || commentViewport(comment) === focusedViewport));
+	const modeAttr = mode && mode !== "standard" ? ` mode="${mode}"` : "";
+	const screenAttr = focusedScreen ? ` screen="${escapeAttr(focusedScreen)}"` : "";
+	const viewportAttr = focusedViewport ? ` viewport="${focusedViewport}"` : "";
+	const lines = [];
+	lines.push("<mockup-review>");
+	if (instructions || mode === "comment-only") {
+		lines.push("  <instructions>");
+		if (instructions) {
+			lines.push("    You are an AI coding assistant receiving a human review of an HTML mockup you submitted.");
+			if (mode === "comment-only") lines.push("    ⚠️ COMMENT-ONLY MODE: You MUST NOT edit any files or implement the mockup. Your only task is to reply to the comments below.");
+			else {
+				lines.push("    - The \"decision\" attribute is the headline verdict: \"approved\", \"rejected\", \"changes-requested\", \"comment-only\", or \"pending\".");
+				lines.push("    - <decision-summary> tells you what to do next.");
+				lines.push("    - Each <comment> has kind=\"section|block|point\" and screen=\"<id>\".");
+				lines.push("      Locate the spot from <html> (clicked node) and <context-html> (section/parent).");
+				lines.push("      selector= is a CSS path to that node. target= is the data-diffing section when present.");
+				lines.push("      Do NOT rely on x/y/rect — those change across screens and viewports.");
+				lines.push("    - Only address comments with status=\"open\".");
+				lines.push("    - Optional severity=\"blocking|nit|question|praise\".");
+				lines.push("");
+				lines.push("    HOW TO RESPOND:");
+				lines.push("    - If approved: implement the mockup.");
+				lines.push("    - If changes-requested: revise the mockup and resubmit the same id.");
+				lines.push("    - If rejected: stop and rethink; do not implement.");
+				lines.push("    - If comment-only: do NOT implement; only reply to comments.");
+				lines.push("    Prefer the diffing CLI or MCP:");
+				lines.push("      diffing mockup reply <comment-id> --body \"...\" --model \"<your-model-name>\"");
+				lines.push("      diffing mockup resolve <comment-id>");
+				lines.push("      diffing mockup submit <file-or-dir> --id <mockup-id>");
+			}
+		} else if (mode === "comment-only") lines.push("    COMMENT-ONLY MODE: reply to the comments below; do NOT edit files or implement the mockup.");
+		lines.push("  </instructions>");
+	}
+	const decidedAttr = mockup.decidedAt ? ` decided-at="${new Date(mockup.decidedAt).toISOString()}"` : "";
+	const viewingAttr = isHistorical ? ` viewing-version="${viewingVersion}"` : "";
+	const screenIds = (screensToRender ?? []).map((s) => s.id).join(",");
+	lines.push(`  <mockup id="${escapeAttr(mockup.id)}" title="${escapeAttr(titleToRender)}" version="${mockup.version}" screens="${escapeAttr(screenIds)}" decision="${mockup.decision}"${decidedAttr}${viewingAttr}${modeAttr}${screenAttr}${viewportAttr}>`);
+	lines.push(`    <decision-summary><![CDATA[${mockupDecisionSummary(mockup.decision)}]]></decision-summary>`);
+	const trimmedDecisionComment = mockup.decisionComment?.trim();
+	if (trimmedDecisionComment) lines.push(`    <decision-comment><![CDATA[${trimmedDecisionComment}]]></decision-comment>`);
+	if (visibleComments.length > 0) {
+		lines.push("    <comments>");
+		for (const comment of visibleComments) lines.push(formatComment(comment, mockup.version, Boolean(instructions)));
+		lines.push("    </comments>");
+	}
+	lines.push("  </mockup>");
+	lines.push("</mockup-review>");
+	return lines.join("\n");
+}
+function formatComment(comment, fallbackVersion, includeContext) {
+	const isoDate = new Date(comment.createdAt).toISOString();
+	const versionAttr = ` mockup-version="${comment.createdAtMockupVersion ?? fallbackVersion}"`;
+	const viewportAttr = ` viewport="${commentViewport(comment)}"`;
+	const severityAttr = comment.severity && comment.severity !== "none" ? ` severity="${comment.severity}"` : "";
+	const targetAttr = comment.target ? ` target="${escapeAttr(comment.target)}"` : "";
+	const selectorAttr = comment.selector ? ` selector="${escapeAttr(comment.selector)}"` : "";
+	const fingerprintAttr = comment.fingerprint ? ` fingerprint="${escapeAttr(comment.fingerprint)}"` : "";
+	const xAttr = comment.x !== void 0 ? ` x="${comment.x}%"` : "";
+	const yAttr = comment.y !== void 0 ? ` y="${comment.y}%"` : "";
+	const sectionXAttr = comment.sectionX !== void 0 ? ` section-x="${comment.sectionX}%"` : "";
+	const sectionYAttr = comment.sectionY !== void 0 ? ` section-y="${comment.sectionY}%"` : "";
+	const parts = [];
+	parts.push(`      <comment id="${escapeAttr(comment.id)}" kind="${comment.kind}" screen="${escapeAttr(comment.screenId)}"${targetAttr}${selectorAttr}${fingerprintAttr}${xAttr}${yAttr}${sectionXAttr}${sectionYAttr} status="${comment.status}"${severityAttr} created-at="${isoDate}"${versionAttr}${viewportAttr}>`);
+	if (includeContext && (comment.html?.trim() || comment.contextHtml?.trim() || comment.snapshot?.trim())) {
+		parts.push("        <location>");
+		if (comment.html?.trim()) parts.push(`          <html><![CDATA[${comment.html.trim()}]]></html>`);
+		if (comment.contextHtml?.trim()) parts.push(`          <context-html><![CDATA[${comment.contextHtml.trim()}]]></context-html>`);
+		if (comment.snapshot?.trim()) parts.push(`          <snapshot><![CDATA[${comment.snapshot.trim()}]]></snapshot>`);
+		parts.push("        </location>");
+	}
+	parts.push(`        <body><![CDATA[${comment.body}]]></body>`);
+	if (comment.replies && comment.replies.length > 0) {
+		parts.push("        <replies>");
+		for (const reply of comment.replies) {
+			const replyIsoDate = new Date(reply.createdAt).toISOString();
+			const roleAttr = reply.role ? ` role="${reply.role}"` : " role=\"agent\"";
+			const modelAttr = reply.model ? ` model="${escapeAttr(reply.model)}"` : "";
+			parts.push(`          <reply id="${escapeAttr(reply.id)}" created-at="${replyIsoDate}"${roleAttr}${modelAttr}>`);
+			parts.push(`            <![CDATA[${reply.body}]]>`);
+			parts.push("          </reply>");
+		}
+		parts.push("        </replies>");
+	}
+	parts.push("      </comment>");
+	return parts.join("\n");
+}
+//#endregion
+export { MOCKUP_MAX_SCREEN_BYTES as a, defaultScreenLabel as c, normalizeSubmitScreens as d, slugifyScreenId as f, sectionTitleForLine as i, isMockupViewport as l, extractPlanLines as n, MOCKUP_SCREEN_ID_RE as o, formatPlanReview as r, commentViewport as s, formatMockupReview as t, normalizeMockupViewport as u };

package/dist/{review-export-GW4KNsGN.mjs → review-export-DoST2oPt.mjs}

@@ -1,4 +1,4 @@
-import { n as reviewDecisionSummary } from "./comment-format-B85NHZnG.mjs";
+import { n as reviewDecisionSummary } from "./comment-format-D4mCqr7T.mjs";
 //#region src/lib/review-export.ts
 /**
 * Export a review as human-readable Markdown (clipboard / download / CLI).