@parity-app/cli 0.1.0 → 0.3.0

package/dist/client-Cf66-n3R.mjs

@@ -0,0 +1,724 @@
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { readFileSync, readdirSync, realpathSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+/** Reads a registry entry's text, or nothing when it isn't one. A file from before the registry stands for its copy. */
+function readCopyEntry(text) {
+	if (text === void 0) return void 0;
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return;
+	}
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const fields = new Map(Object.entries(value));
+	const [version, url, token, app, pid, startedAt] = [
+		"version",
+		"url",
+		"token",
+		"app",
+		"pid",
+		"startedAt"
+	].map((key) => fields.get(key));
+	if (typeof url !== "string" || typeof token !== "string") return void 0;
+	const number = (field) => typeof field === "number" ? field : void 0;
+	return {
+		version: number(version) ?? 0,
+		url,
+		token,
+		app: number(app) ?? number(pid) ?? 0,
+		startedAt: number(startedAt) ?? 0
+	};
+}
+/**
+* A project folder as routing compares it: forward slashes, no trailing slash, and on Windows (a drive letter or a
+* share) without case, since `C:\Work` and `c:/work` are the same folder there.
+*/
+function normalizeRoot(path) {
+	const windows = /^(?:[A-Za-z]:|[\\/]{2})/.test(path);
+	let normal = windows ? path.replaceAll("\\", "/") : path;
+	normal = normal.replace(/(?<!^)\/{2,}/g, "/");
+	if (normal.length > 1 && !/^[A-Za-z]:\/$/.test(normal)) normal = normal.replace(/\/+$/, "");
+	return windows ? normal.toLowerCase() : normal;
+}
+/** The tab a reference names: its id, then its project folder, then its name. */
+function matchTab(tabs, reference) {
+	const root = normalizeRoot(reference);
+	return tabs.find((tab) => tab.id === reference) ?? tabs.find((tab) => normalizeRoot(tab.root) === root) ?? tabs.find((tab) => tab.name === reference);
+}
+/**
+* The open project a folder is in: the deepest one whose folder holds it, so a nested project wins over its parent.
+* `real` gives a folder's real path, so a project reached through a link, as macOS's `/var` is `/private/var`, still
+* holds a folder inside it however each was named; routing itself reads no files, so the caller passes it.
+*/
+function projectFor(folder, tabs, real = (path) => path) {
+	const inside = normalizeRoot(real(folder));
+	let best;
+	for (const tab of tabs) {
+		const root = normalizeRoot(real(tab.root));
+		if ((inside === root || inside.startsWith(root.endsWith("/") ? root : `${root}/`)) && (!best || root.length > normalizeRoot(real(best.root)).length)) best = tab;
+	}
+	return best;
+}
+/**
+* Where an agent's call goes. A tab reference goes to the copy that has that project open; `active` to the active tab
+* of the copy the person used last. Without one, a call goes to the project the agent's folder is in when it's open,
+* and to `active` when it isn't. A project open in two copies goes to the one that has been running longest, which is
+* the person's own app more often than a copy a session started after it. `open` goes to a copy that has the project
+* already, and otherwise to the one the person used last.
+*/
+function route(copies, request) {
+	const open = openTabs(copies);
+	if (copies.length === 0) return {
+		kind: "none",
+		code: "not_running",
+		message: "Parity isn't running. Start the app, then try again.",
+		open
+	};
+	if (request.kind === "open") return {
+		kind: "copy",
+		copy: holdersOf(copies, request.root)[0]?.copy ?? lastUsed(copies)
+	};
+	const reference = request.tab?.trim();
+	if (reference && reference !== "active") {
+		const holding = holdersOf(copies, reference);
+		if (holding[0]) return {
+			kind: "copy",
+			copy: holding[0].copy,
+			tab: holding[0].tab
+		};
+		const ids = open.map((tab) => tab.id);
+		return {
+			kind: "none",
+			code: "unknown_tab",
+			message: `No open tab matches "${reference}". Tabs: ${ids.length ? ids.join(", ") : "none"}`,
+			open
+		};
+	}
+	if (!reference) {
+		const project = projectFor(request.folder, open, request.real);
+		if (project) {
+			const holding = holdersOf(copies, project.root);
+			if (holding[0]) return {
+				kind: "copy",
+				copy: holding[0].copy,
+				tab: holding[0].tab
+			};
+		}
+	}
+	const looking = [...copies].sort(byLastUsed).find((copy) => copy.report.tabs.some((tab) => tab.active));
+	const tab = looking?.report.tabs.find((candidate) => candidate.active);
+	if (looking && tab) return {
+		kind: "copy",
+		copy: looking,
+		tab
+	};
+	return {
+		kind: "none",
+		code: "unknown_tab",
+		message: "No project is open in Parity",
+		open
+	};
+}
+/**
+* Every copy's tabs as one list, one entry per project: from the copy its calls go to, and active only for the tab
+* `active` names.
+*/
+function openTabs(copies) {
+	const shown = [...copies].sort(byLastUsed).find((copy) => copy.report.tabs.some((tab) => tab.active))?.report.tabs.find((tab) => tab.active);
+	const tabs = /* @__PURE__ */ new Map();
+	for (const copy of [...copies].sort(byAge)) for (const tab of copy.report.tabs) {
+		const key = normalizeRoot(tab.root);
+		if (tabs.has(key)) continue;
+		tabs.set(key, {
+			...tab,
+			active: !!shown && normalizeRoot(shown.root) === key
+		});
+	}
+	return [...tabs.values()];
+}
+/** The copies that have a project open, oldest first, with the tab they have it in. */
+function holdersOf(copies, reference) {
+	return [...copies].sort(byAge).flatMap((copy) => {
+		const tab = matchTab(copy.report.tabs, reference);
+		return tab ? [{
+			copy,
+			tab
+		}] : [];
+	});
+}
+function lastUsed(copies) {
+	return [...copies].sort(byLastUsed)[0];
+}
+/** The copy focused last first; one that can't say, or a tie, goes to the one that has been running longest. */
+function byLastUsed(a, b) {
+	return (b.report.focusedAt ?? 0) - (a.report.focusedAt ?? 0) || byAge(a, b);
+}
+/** The copy running longest first, then by process, so the order never depends on how the registry was listed. */
+function byAge(a, b) {
+	return a.entry.startedAt - b.entry.startedAt || a.entry.app - b.entry.app;
+}
+// ../agent/src/registry.ts
+/** The registry these settings name: `PARITY_AGENT_FILE`, else `PARITY_AGENT_DIR`, else `~/.parity/agents`. */
+function agentRegistry(env, home) {
+	if (env.PARITY_AGENT_FILE) return {
+		kind: "file",
+		path: env.PARITY_AGENT_FILE
+	};
+	return {
+		kind: "folder",
+		path: env.PARITY_AGENT_DIR || join(home, ".parity", "agents")
+	};
+}
+/** The file before the registry, where an app from before it says how to reach it. */
+function legacyAgentFile(home) {
+	return join(home, ".parity", "agent.json");
+}
+/** Where a copy's own entry goes. */
+function entryPath(registry, app) {
+	return registry.kind === "file" ? registry.path : join(registry.path, `${app}.json`);
+}
+/** Removes an entry the CLI found for a copy that isn't running. */
+function removeStaleEntry(registry, entry) {
+	if (registry.kind === "folder") rmSync(entryPath(registry, entry.app), { force: true });
+}
+/**
+* Every entry the registry has, with the file before the registry when an older app wrote it, so a CLI reaches an app
+* from before the registry too.
+*/
+function readEntries(registry, home) {
+	if (registry.kind === "file") {
+		const entry = readCopyEntry(readText(registry.path));
+		return entry ? [entry] : [];
+	}
+	let names = [];
+	try {
+		names = readdirSync(registry.path).filter((name) => /^\d+\.json$/.test(name));
+	} catch {}
+	const entries = names.flatMap((name) => {
+		const entry = readCopyEntry(readText(join(registry.path, name)));
+		return entry ? [entry] : [];
+	});
+	const legacy = readCopyEntry(readText(legacyAgentFile(home)));
+	if (legacy && !entries.some((entry) => entry.url === legacy.url)) entries.push(legacy);
+	return entries;
+}
+/** Whether a process is still running. One the person's account can't signal still is. */
+function isRunning(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error instanceof Error && "code" in error && error.code === "EPERM";
+	}
+}
+function readText(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return;
+	}
+}
+// ../core/src/errors.ts
+/**
+* Why an agent's call failed, as a stable code it can act on without reading the message. The CLI and MCP publish
+* these; the app throws them where it knows the cause.
+*/
+const errorCodes = [
+	"invalid_input",
+	"not_running",
+	"not_answering",
+	"unknown_tab",
+	"tab_not_ready",
+	"unknown_design",
+	"unknown_node",
+	"ambiguous_reference",
+	"unknown_state",
+	"unknown_mode",
+	"unknown_viewport",
+	"unknown_component",
+	"unknown_icon_set",
+	"unknown_edit_id",
+	"conflict",
+	"execution_failed",
+	"app_error"
+];
+/** An error with a stable code, the field it's about and what to use instead. */
+var CodedError = class extends Error {
+	details;
+	constructor(message, details) {
+		super(message);
+		this.name = "CodedError";
+		this.details = {
+			...details,
+			retryable: details.retryable ?? false
+		};
+	}
+};
+/** An unknown reference, naming the valid ones closest to what was asked for, up to `alternativeLimit`. */
+function unknownReference(code, message, reference, candidates, field) {
+	return new CodedError(message, {
+		code,
+		...field === void 0 ? {} : { field },
+		alternatives: closest(reference, candidates)
+	});
+}
+/**
+* Candidates sharing text with the reference first, ignoring case, then the rest by how few single-character edits
+* away they are, so a typo's intended id makes the cut; ties keep their own order. All of them when they fit.
+*/
+function closest(reference, candidates, limit = 20) {
+	const unique = [...new Set(candidates)];
+	if (unique.length <= limit) return unique;
+	const wanted = reference.toLowerCase();
+	const ranked = unique.map((candidate, index) => {
+		const lower = candidate.toLowerCase();
+		const near = wanted.length > 0 && (lower.includes(wanted) || wanted.includes(lower));
+		return {
+			candidate,
+			index,
+			near: near ? 0 : 1,
+			distance: near ? 0 : editDistance(wanted, lower)
+		};
+	});
+	ranked.sort((a, b) => a.near - b.near || a.distance - b.distance || a.index - b.index);
+	return ranked.slice(0, limit).map(({ candidate }) => candidate);
+}
+/** How many single-character insertions, deletions or substitutions turn one string into the other. */
+function editDistance(a, b) {
+	let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+	for (let i = 1; i <= a.length; i++) {
+		const row = [i];
+		for (let j = 1; j <= b.length; j++) row[j] = Math.min(previous[j] + 1, row[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+		previous = row;
+	}
+	return previous[b.length];
+}
+/** A thrown value's details, when it carries them. */
+function errorDetails(error) {
+	return error instanceof CodedError ? error.details : void 0;
+}
+/** Details that came from another process, checked before they're trusted. Anything malformed reads as none. */
+function readErrorDetails(value) {
+	if (!value || typeof value !== "object") return void 0;
+	const code = "code" in value ? value.code : void 0;
+	const known = errorCodes.find((candidate) => candidate === code);
+	if (!known) return void 0;
+	const retryable = "retryable" in value && value.retryable === true;
+	const field = "field" in value && typeof value.field === "string" && value.field ? value.field : void 0;
+	const alternatives = "alternatives" in value && Array.isArray(value.alternatives) ? value.alternatives.filter((item) => typeof item === "string").slice(0, 20) : void 0;
+	return {
+		code: known,
+		retryable,
+		...field === void 0 ? {} : { field },
+		...alternatives === void 0 ? {} : { alternatives }
+	};
+}
+// src/caller.ts
+/** Declared caller names are displayed verbatim apart from surrounding whitespace. */
+function declaredName(value) {
+	return typeof value === "string" ? value.trim() || void 0 : void 0;
+}
+/** Reserve the session suffix inside the desktop boundary's 80-character caller-id limit. */
+function sessionCallerId(name, session) {
+	return `${name.slice(0, 71)}#${session.slice(0, 8)}`;
+}
+/** MCP supplies its own identity in initialize; prefer its display title over its protocol name. */
+function mcpCallerName(clientInfo) {
+	return declaredName(clientInfo?.title) ?? declaredName(clientInfo?.name) ?? "Agent";
+}
+/** CLI callers opt in to attribution explicitly; ambient tool configuration is not identity. */
+function cliCallerName(env) {
+	return declaredName(env.PARITY_AGENT_NAME) ?? "Terminal";
+}
+// src/client.ts
+/**
+* Where running copies of the app say how to reach them: `~/.parity/agents`, or the one file `PARITY_AGENT_FILE` names
+* for a copy kept apart from the person's.
+*/
+const registry = agentRegistry(process.env, homedir());
+let caller = cliCallerName(process.env);
+/** Tells callers with the same name apart. A terminal's calls are separate processes, so they share their name. */
+const explicitCallerId = process.env.PARITY_AGENT_ID?.trim() || void 0;
+let callerId = explicitCallerId;
+/**
+* Names who's calling in later calls, so the canvas can say who's at work. The MCP server learns the name from its
+* client, and is one session: its calls share an id, apart from any other session of the same agent.
+*/
+function setCaller(name, session = false) {
+	caller = name ?? caller;
+	callerId = session ? sessionCallerId(caller, randomUUID()) : explicitCallerId;
+}
+/**
+* Calls the running Parity app: the copy that has the call's project open, with the exact tab it chose, by the rules
+* in `@parity-app/agent/routing`. Fails with a clear message, and a code, when no copy is running, none has the
+* project, or the call fails: the app's own code when it gives one.
+*/
+async function call(method, params = {}, routing = "tab") {
+	const copies = await runningCopies();
+	if (routing === "copies") return openTabs(copies);
+	const target = route(copies, routing === "open" ? {
+		kind: "open",
+		root: String(params.root)
+	} : {
+		kind: "tab",
+		...typeof params.tab === "string" ? { tab: params.tab } : {},
+		folder: process.cwd(),
+		real
+	});
+	if (target.kind === "none") {
+		if (target.code === "not_running") throw new CodedError(target.message, {
+			code: target.code,
+			retryable: true
+		});
+		const ids = target.open.map((tab) => tab.id);
+		throw unknownReference("unknown_tab", target.message, typeof params.tab === "string" ? params.tab : "", ids, "tab");
+	}
+	return send(target.copy.entry, method, target.tab ? {
+		...params,
+		tab: target.tab.id
+	} : params);
+}
+/** A folder's real path, through any link, or the folder as named when it can't be read. */
+function real(path) {
+	try {
+		return realpathSync.native(path);
+	} catch {
+		return path;
+	}
+}
+/** Every copy that answers, with what it has open. An entry whose copy has quit is removed on the way. */
+async function runningCopies() {
+	const entries = readEntries(registry, homedir());
+	const newer = entries.find((entry) => entry.version > 1);
+	if (newer) throw new CodedError(`The Parity at ${newer.url} is newer than this CLI. Update @parity-app/cli, then try again.`, {
+		code: "not_running",
+		retryable: false
+	});
+	const copies = (await Promise.all(entries.map(async (entry) => {
+		const report = await reportOf(entry);
+		if (!report && !isRunning(entry.app)) removeStaleEntry(registry, entry);
+		return report ? [{
+			entry,
+			report
+		}] : [];
+	}))).flat();
+	if (entries.length > 0 && copies.length === 0) throw new CodedError(`Parity isn't answering at ${entries.map((entry) => entry.url).join(", ")}. Is the app still running?`, {
+		code: "not_answering",
+		retryable: true
+	});
+	if (copies.length === 0) throw new CodedError(`Parity isn't running (nothing in ${registry.path}). Start the app, then try again.`, {
+		code: "not_running",
+		retryable: true
+	});
+	return copies;
+}
+/** What a copy has open and when it was last used; just its tabs from an app too old to say more. */
+async function reportOf(entry) {
+	try {
+		return await send(entry, "copy", {}, 5e3);
+	} catch (error) {
+		if (!(error instanceof CodedError) || error.details.code !== "app_error") return void 0;
+		try {
+			return { tabs: await send(entry, "tabs", {}, 5e3) };
+		} catch {
+			return;
+		}
+	}
+}
+async function send(entry, method, params, timeout) {
+	let response;
+	try {
+		response = await fetch(`${entry.url}/rpc`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				authorization: `Bearer ${entry.token}`
+			},
+			body: JSON.stringify({
+				method,
+				params,
+				agent: caller,
+				agentId: callerId
+			}),
+			...timeout === void 0 ? {} : { signal: AbortSignal.timeout(timeout) }
+		});
+	} catch {
+		throw new CodedError(`Parity isn't answering at ${entry.url}. Is the app still running?`, {
+			code: "not_answering",
+			retryable: true
+		});
+	}
+	const body = await response.json();
+	if (body.error !== void 0) throw new CodedError(body.error, readErrorDetails(body.details) ?? { code: "app_error" });
+	return body.result;
+}
+/** A readable account of an exec call, for terminals and for agents. */
+function describeExec(result) {
+	const lines = [];
+	if (result.ok) lines.push(result.applied ? "Done. The changes are on the canvas as one undoable step." : "Done. Nothing changed.");
+	else {
+		const error = result.error;
+		lines.push(`Failed, nothing changed: ${error?.message ?? "unknown error"}`);
+		if (error?.retryable) lines.push("Nothing in the request was wrong; run it again.");
+		if (error?.editId) lines.push(`Fix it by retrying with editId "${error.editId}" and edits ({find, replace}) to the snippet.`);
+	}
+	if (result.output.length > 0) lines.push("", "Output:", ...result.output);
+	const created = Object.entries(result.created);
+	if (created.length > 0) lines.push("", "Created:", ...created.map(([name, id]) => `  ${name} = ${id}`));
+	if (result.warnings.length > 0) lines.push("", "Warnings (fix these next):", ...result.warnings.map((warning) => `  ${warning}`));
+	if (result.screenshots.length > 0) lines.push("", "Screenshots:", ...result.screenshots.map((shot) => `  ${shot.design} / ${shot.state} / ${shot.mode}: ${shot.path}`));
+	return lines.join("\n");
+}
+/** Where a tab's edits stand: the revision, what's applied and undoable, what's on disk, and what failed to write. */
+function describeStatus(result) {
+	const { tab, revision, unsaved, undo, redo, save, errors } = result;
+	const steps = (count) => count === 1 ? "1 step" : `${count} steps`;
+	const lines = [`${tab.name} is at revision ${revision}.`];
+	if (unsaved.length === 0) lines.push("Everything applied is saved.");
+	else {
+		const how = result.autosave ? "Automatic saving is on, so they save themselves." : "They wait for the person to save; agents can't.";
+		lines.push(`${unsaved.length === 1 ? "1 file isn't" : `${unsaved.length} files aren't`} saved. ${how}`);
+		for (const file of unsaved) {
+			const parts = [];
+			if (file.designs) {
+				const { added, changed, removed } = file.designs;
+				if (added.length > 0) parts.push(`added ${added.join(", ")}`);
+				if (changed.length > 0) parts.push(`changed ${changed.join(", ")}`);
+				if (removed.length > 0) parts.push(`removed ${removed.join(", ")}`);
+			}
+			if (file.modes) parts.push("changed the modes");
+			if (file.tokens?.length) parts.push(`token values ${file.tokens.join(", ")}`);
+			if (file.more) parts.push(`and ${file.more} more`);
+			lines.push(`  ${file.path}${parts.length > 0 ? `: ${parts.join("; ")}` : ""}`);
+		}
+	}
+	if (save.status === "saving") lines.push("Saving now.");
+	if (errors.length > 0) lines.push("", "Failed to write:", ...errors.map((entry) => `  ${entry.path}: ${entry.error}`));
+	lines.push("", `Undo has ${steps(undo.count)}${undo.labels?.length ? `: ${undo.labels.join(", ")}` : ""}.`);
+	if (redo.count > 0) lines.push(`Redo has ${steps(redo.count)}${redo.labels?.length ? `: ${redo.labels.join(", ")}` : ""}.`);
+	return lines.join("\n");
+}
+/**
+* The project's viewports (what Responsive takes), its other variables, its modes (what renders take) and what each
+* design's board shows, with a named design's frames.
+*/
+function describeModes(result) {
+	const { variables, viewports, modes, designs } = result;
+	const lines = ["Viewports, the ids Responsive(node, viewport, patch) takes:", ...viewports.map((viewport) => `  ${viewport.id}: ${viewport.width} wide, in a window ${viewport.height} tall (${viewport.name})`)];
+	const others = variables.filter((variable) => variable.kind !== "viewport");
+	if (others.length > 0) {
+		lines.push("", "Other variables:");
+		for (const variable of others) {
+			const options = variable.options.map((option) => {
+				const effects = [...option.className ? [`class ${option.className}`] : [], ...Object.entries(option.attributes ?? {}).map(([name, value]) => `${name}="${value}"`)];
+				return effects.length > 0 ? `${option.id} (${effects.join(", ")})` : option.id;
+			});
+			lines.push(`  ${variable.id} (${variable.kind}): ${options.join(", ")}`);
+		}
+	}
+	lines.push("", "Modes, the ids screenshots and checks take, primary first:");
+	for (const mode of modes) {
+		const values = Object.entries(mode.values).map(([variable, option]) => `${variable} ${option}`).join(", ");
+		lines.push(`  ${mode.id}${mode.primary ? " (primary)" : ""}: ${values}; ${mode.width} by ${mode.height}`);
+	}
+	lines.push("", designs.length === 1 ? "Design:" : "Designs:");
+	for (const design of designs) {
+		const states = design.states.length > 1 ? `every state (${design.states.join(", ")})` : `state ${design.state}`;
+		const beside = design.beside.length > 0 ? `, beside it ${design.beside.join(", ")}` : "";
+		lines.push(`  ${design.id} (${design.name}): ${states}; main mode ${design.main}${beside}`);
+		for (const frame of design.frames ?? []) {
+			const size = frame.height === void 0 ? `${frame.width} wide, growing` : `${frame.width} by ${frame.height}`;
+			lines.push(`    ${frame.mode}: ${size}, in a ${frame.window.width} by ${frame.window.height} window`);
+		}
+	}
+	return lines.join("\n");
+}
+const impactOrder = [
+	"critical",
+	"serious",
+	"moderate",
+	"minor"
+];
+/**
+* A readable account of an accessibility check: each rule broken, worst first, with the layers that break it, the
+* frames they break it in and what's wrong. Alike layers, such as the rows of a list, share a line.
+*/
+function describeAccessibility(result) {
+	const { design, findings, frames } = result;
+	const checked = `${design.name} (${design.id}), ${frames === 1 ? "1 frame" : `${frames} frames`}`;
+	const rules = /* @__PURE__ */ new Map();
+	for (const finding of findings) rules.set(finding.rule, [...rules.get(finding.rule) ?? [], finding]);
+	const lines = [rules.size === 0 ? `No issues found in ${checked}, with axe-core against WCAG 2.2 AA.` : `${rules.size === 1 ? "1 rule" : `${rules.size} rules`} broken in ${checked}, with axe-core against WCAG 2.2 AA.`];
+	const groups = [...rules.values()].sort((a, b) => impactOrder.indexOf(a[0].impact) - impactOrder.indexOf(b[0].impact));
+	for (const group of groups) {
+		const { impact, rule, help, helpUrl } = group[0];
+		lines.push("", `${impact}: ${help} (${rule})`);
+		const byLayer = /* @__PURE__ */ new Map();
+		for (const finding of group) {
+			const key = `${finding.node ?? ""}\n${finding.detail}`;
+			const layer = byLayer.get(key) ?? {
+				name: finding.name ?? "The design",
+				nodes: finding.node ? [finding.node] : [],
+				detail: finding.detail,
+				frames: []
+			};
+			layer.frames.push({
+				state: finding.state,
+				mode: finding.mode
+			});
+			byLayer.set(key, layer);
+		}
+		const alike = /* @__PURE__ */ new Map();
+		for (const layer of byLayer.values()) {
+			const same = JSON.stringify([
+				layer.name,
+				layer.detail,
+				layer.frames
+			]);
+			const existing = alike.get(same);
+			if (existing) existing.nodes.push(...layer.nodes);
+			else alike.set(same, layer);
+		}
+		for (const layer of alike.values()) {
+			const where = layer.frames.length === frames && frames > 1 ? "every frame" : frameList(layer.frames);
+			const ids = layer.nodes.length > 0 ? ` (${layer.nodes.join(", ")})` : "";
+			lines.push(`  ${layer.name}${ids}, in ${where}: ${layer.detail}`);
+		}
+		lines.push(`  How to fix it: ${helpUrl}`);
+	}
+	if (result.warnings.length > 0) lines.push("", "Warnings:", ...result.warnings.map((warning) => `  ${warning}`));
+	lines.push("", "Automated checks find some issues, not all. Try the design with a keyboard and a screen reader too.");
+	return lines.join("\n");
+}
+/** A readable account of the layout problems in a design's frames, each once with the frames it's in. */
+function describeProblems(result) {
+	const { design, problems, frames } = result;
+	const checked = `${design.name} (${design.id}), ${frames === 1 ? "1 frame" : `${frames} frames`}`;
+	const grouped = /* @__PURE__ */ new Map();
+	for (const { problem, node, state, mode } of problems) {
+		const key = `${node ?? ""}\n${problem}`;
+		const entry = grouped.get(key) ?? {
+			problem,
+			...node ? { node } : {},
+			frames: []
+		};
+		entry.frames.push({
+			state,
+			mode
+		});
+		grouped.set(key, entry);
+	}
+	const count = grouped.size === 1 ? "1 problem" : `${grouped.size} problems`;
+	const lines = [grouped.size === 0 ? `No problems found in ${checked}.` : `${count} in ${checked}:`];
+	for (const { problem, node, frames: where } of grouped.values()) {
+		const every = where.length === frames && frames > 1 ? "every frame" : frameList(where);
+		lines.push(`  ${node ? `${node}: ` : ""}${problem}, in ${every}`);
+	}
+	if (result.warnings.length > 0) lines.push("", "Warnings:", ...result.warnings.map((warning) => `  ${warning}`));
+	return lines.join("\n");
+}
+/** Tokens by category, each with its value in every theme that sets one. */
+function describeTokens({ tokens, total, truncated }) {
+	if (tokens.length === 0) return "No tokens match.";
+	const lines = [`${`${total === 1 ? "1 token" : `${total} tokens`}${truncated ? `, the first ${tokens.length} shown` : ""}`}. Name them in styles without "--".`];
+	if (truncated) lines.push("Narrow them with category, source or search, or raise limit, to see the rest.");
+	const categories = /* @__PURE__ */ new Map();
+	for (const token of tokens) {
+		const key = `${token.category}, ${token.source}`;
+		categories.set(key, [...categories.get(key) ?? [], token]);
+	}
+	for (const [category, list] of categories) {
+		lines.push("", `${category}:`);
+		for (const token of list) {
+			const values = Object.entries(token.values).sort(([a], [b]) => first("default", a, b)).map(([theme, value]) => `${theme} ${value}`);
+			lines.push(`  ${token.name}: ${values.join(", ")}`);
+		}
+	}
+	return lines.join("\n");
+}
+/**
+* The project's own components, then each library's, then the icon libraries, then the exports left out and why, the
+* components failing to draw and why, and what the person corrected by hand.
+*/
+function describeComponents({ components, iconLibraries = [], leftOut = [], drawn = 0, failing = [], corrections = {} }) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const component of components) {
+		const slash = component.indexOf("/");
+		const group = slash > 0 ? component.slice(0, slash) : "";
+		groups.set(group, [...groups.get(group) ?? [], slash > 0 ? component.slice(slash + 1) : component]);
+	}
+	const lines = [];
+	for (const [group, names] of [...groups].sort(([a], [b]) => first("", a, b))) lines.push(group ? `${group}, as ${group}/Name:` : "The project's own:", `  ${names.join(", ")}`, "");
+	if (iconLibraries.length > 0) lines.push(`Icons: ${iconLibraries.map((library) => `${library}, as ${library}/Name`).join("; ")}`, "");
+	if (leftOut.length > 0) {
+		lines.push("Not components:");
+		for (const entry of leftOut) lines.push(`  ${entry.name}, in ${entry.path}: ${entry.undecided ? "can't tell, " : ""}${entry.reason}`);
+		lines.push("");
+	}
+	if (failing.length > 0) {
+		lines.push(`Failing to draw on the canvas, ${failing.length} of ${failing.length + drawn} drawn so far:`);
+		for (const entry of failing) lines.push(`  ${entry.id}: ${entry.reason}`);
+		lines.push("");
+	}
+	const { include = [] } = corrections;
+	if (include.length > 0) {
+		const name = (ref) => ref.export === "default" ? "the default export" : ref.export;
+		lines.push("Corrected by hand in the project file:");
+		for (const ref of include) lines.push(`  listed: ${name(ref)}, in ${ref.path}`);
+	}
+	return lines.join("\n").trimEnd();
+}
+/** A component's props, with each variant's options and default. */
+function describeProps(result) {
+	if (!result.known) return `${result.component}'s props haven't been read from its source yet. Try again in a moment.`;
+	const imported = result.import && result.import !== result.path ? `, imported from "${result.import}"` : "";
+	const lines = [`${result.component}, from ${result.path}${imported}:`];
+	for (const prop of result.props) {
+		const options = prop.options ? `: ${prop.options.map((option) => JSON.stringify(option)).join(", ")}` : "";
+		const fallback = prop.default === void 0 ? "" : `, default ${JSON.stringify(prop.default)}`;
+		lines.push(`  ${prop.name} (${prop.kind}${prop.required ? ", required" : ""})${options}${fallback}`);
+	}
+	if (result.props.length === 0) lines.push("  No props of its own. --all lists the attributes it passes on.");
+	return lines.join("\n");
+}
+/** Frames as state and mode ids, naming a mode once when they share it: "default, error in desktop-light". */
+function frameList(frames) {
+	const modes = [...new Set(frames.map((frame) => frame.mode))];
+	if (modes.length === 1) return `${frames.map((frame) => frame.state).join(", ")} in ${modes[0]}`;
+	return frames.map((frame) => `${frame.state} in ${frame.mode}`).join(", ");
+}
+/** A readable account of what a project's code wrote to the console, oldest first, with where each came from. */
+function describeConsole(result) {
+	const { tab, entries, total, truncated } = result;
+	if (entries.length === 0) return `${tab.name}'s code hasn't written anything to the console.`;
+	const count = total === 1 ? "1 message" : `${total} messages`;
+	const shown = truncated ? `, the newest ${entries.length} shown` : "";
+	const lines = [`${count} from ${tab.name}'s code${shown}, oldest first:`];
+	for (const entry of entries) {
+		const time = new Date(entry.last).toLocaleTimeString([], { hour12: false });
+		const repeats = entry.count > 1 ? ` (${entry.count} times)` : "";
+		const [first = "", ...rest] = entry.text.split("\n");
+		lines.push("", `${time} ${entry.level}${repeats}: ${first}`, ...rest.map((line) => `  ${line}`));
+		const offscreen = entry.where === "offscreen" ? ", in an offscreen render" : "";
+		lines.push(`  at ${scriptPath(entry.source)}:${entry.line}${offscreen}`);
+	}
+	return lines.join("\n");
+}
+/** Compares two names alphabetically, with `name` before every other. */
+function first(name, a, b) {
+	if (a === name) return -1;
+	if (b === name) return 1;
+	return a.localeCompare(b);
+}
+/** A script's path on its server, without the cache-busting query Vite adds. */
+function scriptPath(url) {
+	try {
+		return new URL(url).pathname;
+	} catch {
+		return url || "an unknown script";
+	}
+}
+export { errorDetails as _, describeExec as a, describeProps as c, registry as d, setCaller as f, errorCodes as g, closest as h, describeConsole as i, describeStatus as l, CodedError as m, describeAccessibility as n, describeModes as o, mcpCallerName as p, describeComponents as r, describeProblems as s, call as t, describeTokens as u, readErrorDetails as v, unknownReference as y };