@parity-app/cli 0.0.0 → 0.2.0

package/dist/bin.mjs

@@ -1,9 +1,283 @@
 #!/usr/bin/env node
-import { a as describeConsole, c as describeProps, d as mcpCallerName, i as describeComponents, l as describeTokens, n as call, o as describeExec, r as describeAccessibility, s as describeProblems, u as setCaller } from "./client-DsTLQ2lT.mjs";
+import { _ as errorDetails, a as describeExec, c as describeProps, f as setCaller, g as errorCodes, h as closest, i as describeConsole, l as describeStatus, m as CodedError, n as describeAccessibility, o as describeModes, p as mcpCallerName, r as describeComponents, s as describeProblems, t as call, u as describeTokens, v as readErrorDetails } from "./client-Cf66-n3R.mjs";
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { dirname, join, normalize, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { createInterface } from "node:readline";
+// src/errors.ts
+/** A request field that isn't valid, rejected before anything reaches the app. */
+function invalidInput(field, message) {
+	return new CodedError(message, {
+		code: "invalid_input",
+		...field ? { field } : {}
+	});
+}
+/**
+* A thrown value as an operation error. Invalid input always points at the request; a field the app names becomes a
+* path only when the operation has that input: an unknown design inside a snippet has no `design` input to point at.
+*/
+function operationError(error, fields) {
+	const message = error instanceof Error ? error.message : String(error);
+	const details = errorDetails(error) ?? {
+		code: "app_error",
+		retryable: false
+	};
+	const field = details.field;
+	const known = field !== void 0 && (details.code === "invalid_input" || !fields || fields.includes(field.split("/")[0]));
+	return {
+		code: details.code,
+		message,
+		retryable: details.retryable,
+		...known ? { path: `/${field}` } : {},
+		...details.alternatives?.length ? { alternatives: details.alternatives } : {}
+	};
+}
+/** Renames the top-level field a path points at, for an adapter whose names differ from the contract's. */
+function renamePath(error, names) {
+	if (!error.path) return error;
+	const [, first = "", ...rest] = error.path.split("/");
+	if (!Object.hasOwn(names, first)) return error;
+	return {
+		...error,
+		path: [
+			"",
+			names[first],
+			...rest
+		].join("/")
+	};
+}
+/** The error's schema. What each field means is in the CLI's README and the skill, to keep every tool's schema small. */
+const operationErrorSchema = {
+	type: "object",
+	properties: {
+		code: {
+			type: "string",
+			enum: [...errorCodes]
+		},
+		message: { type: "string" },
+		retryable: { type: "boolean" },
+		path: { type: "string" },
+		alternatives: {
+			type: "array",
+			items: { type: "string" }
+		},
+		editId: { type: "string" }
+	},
+	required: [
+		"code",
+		"message",
+		"retryable"
+	]
+};
+// src/execute.ts
+/** The same request fields in both adapters' paths, before MCP renames label and code. */
+const executeFields = [
+	"tab",
+	"label",
+	"code",
+	"editId",
+	"edits"
+];
+/** A reply as the canonical result: the failure's message, code and retry id together in one error. */
+function execResponse(reply, fields = executeFields) {
+	const { error, details, editId, ...rest } = reply;
+	if (reply.ok || error === void 0) return rest;
+	const coded = readErrorDetails(details);
+	const failure = operationError(coded ? new CodedError(error, coded) : new CodedError(error, { code: "execution_failed" }), fields);
+	return {
+		...rest,
+		error: {
+			...failure,
+			...editId ? { editId } : {}
+		}
+	};
+}
+/** The result as structured data: everything but image data, which MCP sends as image blocks. */
+function structuredExec(result) {
+	return {
+		...result,
+		screenshots: result.screenshots.map(({ png: _png, ...shot }) => shot)
+	};
+}
+/** Execute's and screenshot's structured result. */
+const execOutputSchema = {
+	type: "object",
+	properties: {
+		ok: { type: "boolean" },
+		applied: {
+			type: "boolean",
+			description: "Changes landed on the canvas as one undoable step."
+		},
+		output: {
+			type: "array",
+			items: { type: "string" },
+			description: "Lines from Print."
+		},
+		warnings: {
+			type: "array",
+			items: { type: "string" }
+		},
+		created: {
+			type: "object",
+			additionalProperties: { type: "string" },
+			description: "Names of designs and nodes created, mapped to their ids."
+		},
+		screenshots: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					path: {
+						type: "string",
+						description: "Where the PNG was saved."
+					},
+					design: { type: "string" },
+					state: { type: "string" },
+					mode: { type: "string" }
+				},
+				required: [
+					"path",
+					"design",
+					"state",
+					"mode"
+				]
+			}
+		},
+		error: operationErrorSchema
+	},
+	required: [
+		"ok",
+		"applied",
+		"output",
+		"warnings",
+		"created",
+		"screenshots"
+	]
+};
+const defaultLabel = "Edit designs";
+/** What every call's tab field says, the same in the CLI's help, MCP tools and the skill (PAR-514). */
+const tabDescription = "Tab id, project root or name, or \"active\" for what the person is looking at. Defaults to the open project the current folder is in, else \"active\".";
+/** Canonical properties, also used by MCP discovery after renaming label and code. */
+const executeProperties = {
+	tab: {
+		type: "string",
+		minLength: 1,
+		description: tabDescription
+	},
+	label: {
+		type: "string",
+		minLength: 1,
+		default: defaultLabel,
+		description: "Shown while it runs. Prefer 3 to 8 words, e.g. \"Add pricing tiers\"."
+	},
+	code: {
+		type: "string",
+		minLength: 1,
+		description: "The snippet. Omit when retrying with editId."
+	},
+	editId: {
+		type: "string",
+		minLength: 1,
+		description: "The failed call's editId, to retry with edits."
+	},
+	edits: {
+		type: "array",
+		description: "Exact find and replace edits to the failed snippet, applied in order.",
+		items: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				find: {
+					type: "string",
+					minLength: 1
+				},
+				replace: { type: "string" },
+				all: { type: "boolean" }
+			},
+			required: ["find", "replace"]
+		}
+	}
+};
+function optionalText(value, field) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "string" || !value.trim()) throw invalidInput(field, `${field} must be a nonblank string`);
+	return value;
+}
+function edit(value, index) {
+	const at = `edits/${index}`;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw invalidInput(at, "Each edit must be an object");
+	if (!("find" in value) || typeof value.find !== "string" || !value.find.length) throw invalidInput(`${at}/find`, "Each edit needs a nonempty find string");
+	if (!("replace" in value) || typeof value.replace !== "string") throw invalidInput(`${at}/replace`, "Each edit needs a replace string");
+	if ("all" in value && typeof value.all !== "boolean") throw invalidInput(`${at}/all`, "Edit all must be a boolean");
+	const unknown = Object.keys(value).find((key) => ![
+		"find",
+		"replace",
+		"all"
+	].includes(key));
+	if (unknown) throw invalidInput(`${at}/${unknown}`, "Unknown edit field");
+	return {
+		find: value.find,
+		replace: value.replace,
+		..."all" in value && typeof value.all === "boolean" ? { all: value.all } : {}
+	};
+}
+/** Validate once, before either transport sends a request to the desktop. Never rewrite snippet or patch text. */
+function executeRequest(input) {
+	const tab = optionalText(input.tab, "tab");
+	const label = optionalText(input.label, "label") ?? defaultLabel;
+	const code = optionalText(input.code, "code");
+	const editId = optionalText(input.editId, "editId");
+	if (!code && !editId) throw invalidInput("code", "Nothing to run: pass a snippet, or an editId with edits");
+	if (code !== void 0 && editId !== void 0) throw invalidInput("editId", "Pass a snippet or an editId, not both");
+	if (input.edits !== void 0 && !Array.isArray(input.edits)) throw invalidInput("edits", "edits must be an array");
+	if (input.edits !== void 0 && !editId) throw invalidInput("edits", "edits requires an editId");
+	const edits = Array.isArray(input.edits) ? input.edits.map(edit) : void 0;
+	return {
+		label,
+		...tab === void 0 ? {} : { tab },
+		...code === void 0 ? {} : { code },
+		...editId === void 0 ? {} : {
+			editId,
+			edits: edits ?? []
+		}
+	};
+}
+/** Execution failures have the same meaning for CLI exits and MCP tool errors. */
+function executionFailed(result) {
+	return !result.ok;
+}
+/** One handler for both adapters. Caller identity stays in the transport's connection context. */
+const executeOperation = {
+	failed: executionFailed,
+	fields: executeFields,
+	outputSchema: execOutputSchema,
+	structured: structuredExec,
+	/** Discovery uses the same contract, with just the two historical MCP field aliases. */
+	inputSchema(names = {
+		label: "label",
+		code: "code"
+	}) {
+		const { label, code, ...rest } = executeProperties;
+		return {
+			type: "object",
+			properties: {
+				...rest,
+				[names.label]: label,
+				[names.code]: code
+			},
+			oneOf: [{
+				required: [names.code],
+				not: { anyOf: [{ required: ["editId"] }, { required: ["edits"] }] }
+			}, {
+				required: ["editId"],
+				not: { required: [names.code] }
+			}]
+		};
+	},
+	async run(input, send) {
+		return execResponse(await send("exec", { ...executeRequest(input) }));
+	}
+};
 // src/check.ts
 /**
 * `parity lib check <library>`: inserts every component of a registry library file into the running app, once on its
@@ -13,8 +287,8 @@ import { createInterface } from "node:readline";
 */
 async function runCheck(library, options) {
 	if (!library) throw new Error("parity lib check <library> [--tab t] [--mode m]");
-	const { applyLibraryEdits, componentNode, generateId, librarySource, parseLibraryEdits, withLibraryContext } = await import("./src-WcAfq6g1.mjs");
-	const { registryDir, registryEntries } = await import("./src-C8DCd2a1.mjs");
+	const { applyLibraryEdits, componentNode, generateId, librarySource, parseLibraryEdits, withLibraryContext } = await import("./src-BRgxMRtE.mjs");
+	const { registryDir, registryEntries } = await import("./src-BOUQtcWB.mjs");
 	const entry = (await registryEntries()).find((item) => item.manifest.id === library);
 	if (!entry) throw new Error(`The registry has no library "${library}"`);
 	let manifest = entry.manifest;
@@ -25,18 +299,18 @@ async function runCheck(library, options) {
 	const list = manifest.components?.list ?? {};
 	const names = Object.keys(list).filter((name) => list[name].visual !== false);
 	const id = (name) => `${library}/${name}`;
-	const sources = Object.fromEntries(names.map((name) => [id(name), {
+	const sources = Object.fromEntries(Object.keys(list).map((name) => [id(name), {
 		...librarySource(library, name, list[name], library),
 		declaration: ""
 	}]));
 	const mode = options.mode ?? "desktop-light";
 	const exec = async (label, code) => {
-		const result = await call("exec", {
+		const result = await executeOperation.run({
 			tab: options.tab,
 			label,
 			code
-		});
-		if (!result.ok) throw new Error(result.error ?? `${label} failed`);
+		}, call);
+		if (executeOperation.failed(result)) throw new Error(result.error?.message ?? `${label} failed`);
 		const line = result.output.find((item) => item.startsWith("{") || item.startsWith("["));
 		if (!line) throw new Error(`${label} printed nothing`);
 		return line;
@@ -142,8 +416,8 @@ function describeCheck(report) {
 * because it reads the project's files and its own copy of TypeScript.
 */
 async function runLib(packageName, options) {
-	const { appManifestPath, generateLibrary, manifestText, mergeManifest, reviseLibrary } = await import("./src-rlZNC2MU.mjs");
-	const { covers, registryDir, registryEntries } = await import("./src-C8DCd2a1.mjs");
+	const { appManifestPath, generateLibrary, manifestText, mergeManifest, reviseLibrary } = await import("./src-CcWc-KsX.mjs");
+	const { covers, registryDir, registryEntries } = await import("./src-BOUQtcWB.mjs");
 	const spec = packageName === void 0 ? void 0 : packageSpec(packageName);
 	let root = resolve(options.root ?? ".");
 	if (spec && (spec.version !== void 0 || options.registry && !options.root)) {
@@ -154,7 +428,7 @@ async function runLib(packageName, options) {
 		console.error(`Installing ${spec.name} ${version} on its own…`);
 		root = await installedVersion(spec.name, version);
 	}
-	const { parseLibraryEdits } = await import("./src-rlZNC2MU.mjs");
+	const { parseLibraryEdits } = await import("./src-CcWc-KsX.mjs");
 	const trialEdits = options.edits ? parseLibraryEdits(JSON.parse(await readFile(resolve(options.edits), "utf8"))) : void 0;
 	const recordedId = options.registry && spec ? options.id ?? (await registryEntries()).find((entry) => entry.manifest.package?.name === spec.name)?.manifest.id : void 0;
 	const appErrors = recordedId ? await readAppErrors(registryDir(), recordedId) : void 0;
@@ -304,17 +578,693 @@ function describeReport(report) {
 	for (const note of report.notes) lines.push(`Note: ${note}`);
 	return lines.join("\n");
 }
+// src/operations.ts
+function text$1(description, required = false, fallback) {
+	return {
+		schema: {
+			type: "string",
+			minLength: 1,
+			pattern: "\\S",
+			description,
+			...fallback === void 0 ? {} : { default: fallback }
+		},
+		required,
+		read(value, name) {
+			if (value === void 0 && !required) return fallback;
+			if (typeof value !== "string" || !value.trim()) throw invalidInput(name, `${name} must be a nonblank string`);
+			return value;
+		}
+	};
+}
+function boolean(description) {
+	return {
+		schema: {
+			type: "boolean",
+			default: false,
+			description
+		},
+		read(value, name) {
+			if (value === void 0) return false;
+			if (typeof value !== "boolean") throw invalidInput(name, `${name} must be a boolean`);
+			return value;
+		}
+	};
+}
+function selector(description, fallback) {
+	const item = {
+		type: "string",
+		minLength: 1,
+		pattern: "\\S"
+	};
+	return {
+		schema: {
+			oneOf: [item, {
+				type: "array",
+				minItems: 1,
+				items: item
+			}],
+			description,
+			...fallback ? { default: fallback } : {}
+		},
+		read(value, name) {
+			if (value === void 0) return fallback;
+			if (typeof value === "string" && value.trim()) return value;
+			if (Array.isArray(value) && value.length && value.every((item) => typeof item === "string" && item.trim())) return value.length === 1 ? value[0] : value;
+			throw invalidInput(name, `${name} must be a nonblank string or a nonempty list of nonblank strings`);
+		}
+	};
+}
+/** How many items a list read returns at most: a default that keeps a reply small, and a ceiling. */
+function limit(description, fallback, most) {
+	return {
+		schema: {
+			type: "integer",
+			minimum: 1,
+			maximum: most,
+			default: fallback,
+			description
+		},
+		read(value, name) {
+			if (value === void 0) return fallback;
+			if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > most) throw invalidInput(name, `${name} must be a whole number from 1 to ${most}`);
+			return value;
+		}
+	};
+}
+const tab = text$1(tabDescription);
+const design = text$1("Design id or name.", true);
+const scale = {
+	schema: {
+		type: "number",
+		minimum: .25,
+		maximum: 3,
+		default: 1,
+		description: "Pixel density."
+	},
+	read(value) {
+		if (value === void 0) return 1;
+		if (typeof value !== "number" || !Number.isFinite(value) || value < .25 || value > 3) throw invalidInput("scale", "scale must be a finite number from 0.25 to 3");
+		return value;
+	}
+};
+const rootText = text$1("Absolute project folder path.", true);
+const absoluteRoot = /^(?:\/|[A-Za-z]:[\\/]|\\\\)/;
+const root$1 = {
+	...rootText,
+	schema: {
+		...rootText.schema,
+		pattern: absoluteRoot.source
+	},
+	read(value) {
+		const path = rootText.read(value, "root");
+		if (typeof path !== "string" || !absoluteRoot.test(path)) throw invalidInput("root", "root must be an absolute project folder path");
+		return path;
+	}
+};
+function fieldsContract(fields) {
+	return {
+		inputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: Object.fromEntries(Object.entries(fields).map(([key, field]) => [key, field.schema])),
+			required: Object.entries(fields).filter(([, field]) => field.required).map(([key]) => key)
+		},
+		request(input) {
+			if (!input || typeof input !== "object" || Array.isArray(input)) throw invalidInput(void 0, "Operation input must be an object");
+			for (const key of Object.keys(input)) if (!Object.hasOwn(fields, key)) throw invalidInput(key, `Unknown input field ${key}`);
+			const result = {};
+			for (const [key, field] of Object.entries(fields)) {
+				const value = field.read(input[key], key);
+				if (value !== void 0) result[key] = value;
+			}
+			return result;
+		}
+	};
+}
+/** An operation whose canonical result is built from the app's reply, given the validated request. */
+function mapped(method, fields, outputSchema, result, options = {}) {
+	const contract = fieldsContract(fields);
+	const routing = routingFor(fields);
+	return {
+		inputSchema: contract.inputSchema,
+		outputSchema,
+		fields: Object.keys(fields),
+		routing,
+		async run(input, send) {
+			const request = contract.request(input);
+			return result(await send(method, request, routing), request);
+		},
+		failed: options.failed ?? (() => false),
+		structured: options.structured ?? ((value) => Object.fromEntries(Object.entries(value)))
+	};
+}
+/** Which copy a call goes to, from its fields: see `Operation.routing`. */
+function routingFor(fields) {
+	if ("tab" in fields) return "tab";
+	if ("root" in fields) return "open";
+	return "copies";
+}
+/** An operation whose canonical result is the app's reply. */
+function operation(method, fields, outputSchema, options = {}) {
+	return mapped(method, fields, outputSchema, (reply) => reply, options);
+}
+/** The first `count` items, with how many there were, so a reply says when it left some out. */
+function bounded(items, count, keep = "first") {
+	const kept = keep === "first" ? items.slice(0, count) : items.slice(Math.max(0, items.length - count));
+	return {
+		items: kept,
+		total: items.length,
+		truncated: kept.length < items.length
+	};
+}
+const string = { type: "string" };
+const strings = {
+	type: "array",
+	items: string
+};
+const integer = { type: "integer" };
+const boolean_ = { type: "boolean" };
+function object(properties, optional = []) {
+	return {
+		type: "object",
+		properties,
+		required: Object.keys(properties).filter((key) => !optional.includes(key))
+	};
+}
+const ref = object({
+	id: string,
+	name: string
+});
+const tabSchema = object({
+	id: string,
+	name: string,
+	root: string,
+	active: boolean_,
+	status: {
+		type: "string",
+		enum: [
+			"loading",
+			"ready",
+			"error"
+		]
+	},
+	error: string,
+	designs: {
+		...integer,
+		description: "How many designs the project has."
+	}
+}, ["error"]);
+const frameSchema = {
+	state: string,
+	mode: string
+};
+const designSchema = object({
+	id: string,
+	name: string,
+	kind: string,
+	file: string,
+	x: { type: "number" },
+	y: { type: "number" },
+	width: { type: "number" },
+	height: { type: "number" },
+	states: {
+		type: "array",
+		items: ref
+	},
+	showing: object({
+		state: string,
+		mode: string,
+		beside: strings
+	}),
+	nodes: integer
+}, ["width", "height"]);
+const stateSchema = object({
+	tab: tabSchema,
+	selection: object({
+		design: string,
+		node: string,
+		mode: string
+	}, [
+		"design",
+		"node",
+		"mode"
+	]),
+	designs: {
+		type: "array",
+		items: designSchema
+	},
+	overlaps: {
+		type: "array",
+		items: object({
+			designs: strings,
+			names: strings
+		})
+	},
+	modes: {
+		type: "array",
+		items: object({
+			id: string,
+			name: string,
+			width: { type: "number" },
+			primary: boolean_
+		})
+	},
+	components: strings,
+	tokens: object({
+		count: integer,
+		semantic: strings,
+		themeCategories: strings
+	}),
+	viewport: { type: "object" },
+	detection: { type: "object" }
+}, ["viewport", "detection"]);
+const truncation = {
+	total: {
+		...integer,
+		description: "How many there were before the limit."
+	},
+	truncated: {
+		...boolean_,
+		description: "Some were left out; narrow the read or raise limit."
+	}
+};
+const tokensSchema = object({
+	tokens: {
+		type: "array",
+		items: object({
+			name: string,
+			category: string,
+			source: string,
+			values: {
+				type: "object",
+				additionalProperties: string,
+				description: "Value per theme."
+			}
+		})
+	},
+	...truncation
+});
+const consoleSchema = object({
+	tab: ref,
+	entries: {
+		type: "array",
+		items: object({
+			level: {
+				type: "string",
+				enum: [
+					"info",
+					"warning",
+					"error",
+					"debug"
+				]
+			},
+			text: string,
+			source: string,
+			line: integer,
+			where: {
+				type: "string",
+				enum: ["canvas", "offscreen"]
+			},
+			count: integer,
+			first: { type: "number" },
+			last: { type: "number" }
+		})
+	},
+	...truncation
+});
+const problemsSchema = object({
+	tab: ref,
+	design: ref,
+	problems: {
+		type: "array",
+		items: object({
+			...frameSchema,
+			problem: string,
+			node: string
+		}, ["node"])
+	},
+	frames: integer,
+	warnings: strings
+});
+const accessibilitySchema = object({
+	tab: ref,
+	design: ref,
+	findings: {
+		type: "array",
+		items: object({
+			...frameSchema,
+			rule: string,
+			impact: {
+				type: "string",
+				enum: [
+					"critical",
+					"serious",
+					"moderate",
+					"minor"
+				]
+			},
+			help: string,
+			helpUrl: string,
+			node: string,
+			name: string,
+			detail: string
+		}, ["node", "name"])
+	},
+	frames: integer,
+	warnings: strings
+});
+const componentsSchema = object({
+	components: strings,
+	iconLibraries: strings,
+	leftOut: {
+		type: "array",
+		items: object({
+			name: string,
+			path: string,
+			reason: string,
+			undecided: boolean_
+		}, ["undecided"])
+	},
+	drawn: integer,
+	failing: {
+		type: "array",
+		items: object({
+			id: string,
+			problem: {
+				type: "string",
+				enum: [
+					"provider",
+					"server",
+					"async",
+					"error"
+				]
+			},
+			reason: string
+		})
+	},
+	corrections: { type: "object" }
+}, [
+	"iconLibraries",
+	"leftOut",
+	"drawn",
+	"failing",
+	"corrections"
+]);
+const propsSchema = object({
+	component: string,
+	path: string,
+	import: string,
+	known: boolean_,
+	props: {
+		type: "array",
+		items: object({
+			name: string,
+			kind: string,
+			group: string,
+			options: {
+				type: "array",
+				items: { type: [
+					"string",
+					"number",
+					"boolean"
+				] }
+			},
+			default: { type: [
+				"string",
+				"number",
+				"boolean",
+				"null"
+			] },
+			required: boolean_
+		}, [
+			"group",
+			"options",
+			"default",
+			"required"
+		])
+	}
+}, ["path", "import"]);
+const viewportSchema = object({
+	id: string,
+	name: string,
+	width: { type: "number" },
+	height: { type: "number" },
+	device: string
+}, ["device"]);
+const frameReportSchema = object({
+	mode: string,
+	width: { type: "number" },
+	height: {
+		type: "number",
+		description: "Fixed frame height, which clips; absent when it grows."
+	},
+	window: object({
+		width: { type: "number" },
+		height: { type: "number" }
+	})
+}, ["height"]);
+const modesSchema = object({
+	tab: ref,
+	variables: {
+		type: "array",
+		items: object({
+			id: string,
+			name: string,
+			kind: {
+				type: "string",
+				enum: [
+					"viewport",
+					"theme",
+					"locale",
+					"custom"
+				]
+			},
+			options: {
+				type: "array",
+				items: { type: "object" }
+			}
+		})
+	},
+	viewports: {
+		type: "array",
+		items: viewportSchema,
+		description: "Viewport ids, which Responsive and a node's responsive patches take. Not mode ids."
+	},
+	modes: {
+		type: "array",
+		description: "Mode ids, which renders (screenshot, problems, accessibility) and a design's modes take.",
+		items: object({
+			id: string,
+			name: string,
+			primary: boolean_,
+			viewport: string,
+			width: { type: "number" },
+			height: { type: "number" },
+			values: {
+				type: "object",
+				additionalProperties: string
+			},
+			classNames: strings,
+			attributes: {
+				type: "object",
+				additionalProperties: string
+			}
+		})
+	},
+	designs: {
+		type: "array",
+		items: object({
+			id: string,
+			name: string,
+			state: string,
+			states: strings,
+			main: string,
+			beside: strings,
+			frames: {
+				type: "array",
+				items: frameReportSchema
+			}
+		}, ["frames"])
+	}
+});
+const historySide = object({
+	count: integer,
+	labels: {
+		...strings,
+		description: "With summary: newest first, up to limit."
+	}
+}, ["labels"]);
+const statusSchema = object({
+	tab: ref,
+	revision: {
+		type: "string",
+		description: "Opaque; the same only while nothing in the tab has changed. Compare it with state's revision."
+	},
+	dirty: {
+		...boolean_,
+		description: "Something applied (and undoable) isn't on disk yet."
+	},
+	autosave: {
+		...boolean_,
+		description: "Changes save themselves; otherwise they wait for the person's Save."
+	},
+	unsaved: {
+		type: "array",
+		items: object({
+			path: string,
+			kind: {
+				type: "string",
+				enum: ["document", "stylesheet"]
+			},
+			designs: object({
+				added: strings,
+				changed: strings,
+				removed: strings
+			}),
+			modes: boolean_,
+			tokens: strings,
+			more: integer
+		}, [
+			"designs",
+			"modes",
+			"tokens",
+			"more"
+		])
+	},
+	tokenEdits: {
+		...integer,
+		description: "Token values waiting for Save to write them to the stylesheet."
+	},
+	save: object({
+		status: {
+			type: "string",
+			enum: [
+				"saved",
+				"unsaved",
+				"saving",
+				"failed"
+			]
+		},
+		error: string
+	}, ["error"]),
+	errors: {
+		type: "array",
+		items: object({
+			path: string,
+			error: string
+		})
+	},
+	undo: historySide,
+	redo: historySide
+}, []);
+const checks = {
+	tab,
+	design,
+	state: selector("State id, list of ids, or \"all\".", "all"),
+	mode: selector("Mode id, list of ids, \"shown\" or \"all\".", "shown")
+};
+const operations = {
+	tabs: mapped("tabs", {}, object({ tabs: {
+		type: "array",
+		items: tabSchema
+	} }), (tabs) => ({ tabs })),
+	state: operation("state", { tab }, stateSchema),
+	status: operation("status", {
+		tab,
+		summary: boolean("Add each unsaved file's designs and token values, and the undo and redo labels."),
+		limit: limit("Most ids or labels in each list of the summary.", 10, 100)
+	}, statusSchema),
+	modes: operation("modes", {
+		tab,
+		design: text$1("Design id or name. With it, just that design, with each of its frames' sizes.")
+	}, modesSchema),
+	open: operation("open", { root: root$1 }, tabSchema),
+	screenshot: mapped("screenshot", {
+		tab,
+		design,
+		scale,
+		state: selector("State id, list of ids, or \"all\". Defaults to the state the design shows."),
+		mode: selector("Mode id, list of ids, \"shown\" or \"all\". Defaults to the primary mode.")
+	}, execOutputSchema, (reply) => execResponse(reply, [
+		"tab",
+		"design",
+		"scale",
+		"state",
+		"mode"
+	]), {
+		failed: executionFailed,
+		structured: structuredExec
+	}),
+	problems: operation("problems", checks, problemsSchema, { failed: (result) => result.problems.length > 0 }),
+	accessibility: operation("accessibility", checks, accessibilitySchema, { failed: (result) => result.findings.length > 0 }),
+	console: mapped("console", {
+		tab,
+		clear: boolean("Empty the console after reading, including entries beyond limit."),
+		limit: limit("Most entries to return, newest kept.", 50, 1e3)
+	}, consoleSchema, ({ tab: from, entries }, request) => {
+		const { items, total, truncated } = bounded(entries, Number(request.limit), "last");
+		return {
+			tab: from,
+			entries: items,
+			total,
+			truncated
+		};
+	}),
+	tokens: mapped("tokens", {
+		tab,
+		category: text$1("Token category."),
+		source: text$1("Token source, such as semantic or theme."),
+		search: {
+			schema: {
+				type: "string",
+				description: "Token name search."
+			},
+			read(value) {
+				if (value !== void 0 && typeof value !== "string") throw invalidInput("search", "search must be a string");
+				return value;
+			}
+		},
+		limit: limit("Most tokens to return.", 100, 1e3)
+	}, tokensSchema, (tokens, request) => {
+		const { items, total, truncated } = bounded(tokens, Number(request.limit));
+		return {
+			tokens: items,
+			total,
+			truncated
+		};
+	}),
+	components: operation("components", { tab }, componentsSchema),
+	props: operation("props", {
+		tab,
+		component: text$1("Component id or name.", true),
+		all: boolean("Include passed-through attributes.")
+	}, propsSchema)
+};
+const skill = fieldsContract({ path: text$1("Skill file to read.", false, "SKILL.md") });
+const skillOperation = {
+	inputSchema: skill.inputSchema,
+	fields: ["path"],
+	async run(input, read) {
+		const { path } = skill.request(input);
+		if (typeof path !== "string") throw invalidInput("path", "path must be a nonblank string");
+		return read(path);
+	}
+};
 // src/skills.ts
 const root = join(import.meta.dirname, "..", "skills");
 /** Reads the Parity design skill: SKILL.md, or a file it references. */
 async function readSkill(path = "SKILL.md") {
 	const target = normalize(join(root, path));
-	if (relative(root, target).startsWith("..") || relative(root, target).includes(`..${sep}`)) throw new Error(`${path} isn't part of the skill`);
+	if (relative(root, target).startsWith("..") || relative(root, target).includes(`..${sep}`)) throw invalidInput("path", `${path} isn't part of the skill`);
 	try {
 		return await readFile(target, "utf8");
 	} catch {
 		const files = await list();
-		throw new Error(`No skill file ${path}. Files: ${files.join(", ")}`);
+		throw new CodedError(`No skill file ${path}. Files: ${files.join(", ")}`, {
+			code: "invalid_input",
+			field: "path",
+			alternatives: closest(path, files)
+		});
 	}
 }
 async function list(directory = root) {
@@ -322,172 +1272,81 @@ async function list(directory = root) {
 	return (await Promise.all(entries.map(async (entry) => entry.isDirectory() ? list(join(directory, entry.name)) : [relative(root, join(directory, entry.name)).replaceAll("\\", "/")]))).flat();
 }
 // src/mcp.ts
-const tab = {
-	type: "string",
-	description: "Tab id, project root or name. Defaults to the active tab."
+/**
+* One adapter for RPC-backed tools: operation contracts own defaults, validation, failure semantics and the structured
+* result, which is what CLI --json prints. The text beside it is for people and clients that don't read structure.
+*
+* Tools publish no outputSchema (PAR-510). Claude Code never shows one to the model, Codex's code mode puts it in the
+* model's context, and with them tools/list was 33 KB rather than 11. structuredContent needs no schema; the contracts
+* keep theirs for CLI --json and the tests.
+*/
+function operationTool(name, description, operation, format) {
+	return {
+		name,
+		description,
+		inputSchema: operation.inputSchema,
+		fields: operation.fields,
+		async run(input) {
+			const result = await operation.run(input, call);
+			return {
+				content: format(result),
+				structuredContent: operation.structured(result),
+				isError: operation.failed(result)
+			};
+		}
+	};
+}
+/** Results that are data to begin with, as compact JSON text for clients that don't read structuredContent. */
+const json = (value) => [text(JSON.stringify(value))];
+/** MCP's names for execute's label and code. */
+const executeNames = {
+	label: "description",
+	code: "input"
 };
 const tools = [
-	{
-		name: "get_tabs",
-		description: "List the projects open in Parity, one per tab. The active tab is the one the person is looking at.",
-		inputSchema: {
-			type: "object",
-			properties: {}
-		},
-		run: async () => [text(JSON.stringify(await call("tabs"), null, 2))]
-	},
-	{
-		name: "get_app_state",
-		description: "Get a tab's state: its designs (ids, states, modes shown, where their boards are and how big), boards that overlap or crowd each other's titles, the selection, project modes, components and tokens, and what Parity detected in the project (each tool's version, where it's installed and its config, the package manager, and a note naming versions Parity doesn't test). Call it first, and again after the person may have changed things. Keep boards apart: Overlaps() and FindEmptySpace() in execute help place them.",
-		inputSchema: {
-			type: "object",
-			properties: { tab }
-		},
-		run: async (input) => [text(JSON.stringify(await call("state", { tab: input.tab }), null, 2))]
-	},
+	operationTool("get_tabs", "List the projects open in Parity, one per tab. The active tab is the one the person is looking at.", operations.tabs, json),
+	operationTool("get_app_state", "Get a tab's state: its designs (ids, states, modes shown, where their boards are and how big), boards that overlap or crowd each other's titles, the selection, project modes, components and tokens, and what Parity detected in the project (each tool's version, where it's installed and its config, the package manager, and a note naming versions Parity doesn't test). Call it first, and again after the person may have changed things. Keep boards apart: Overlaps() and FindEmptySpace() in execute help place them.", operations.state, json),
+	operationTool("get_status", "Read where a tab's edits stand, changing nothing: its revision (the same only while nothing has changed, so compare it before reading again), whether anything applied isn't saved (dirty), the files waiting for Save, token values waiting, how the last save went and writes that failed, and how many steps undo and redo hold. summary adds each unsaved file's designs added, changed and removed, the token values, and undo and redo labels, up to limit each. Changes are undoable once applied; only the person saves them, unless automatic saving is on.", operations.status, (result) => [text(describeStatus(result))]),
+	operationTool("get_modes", "Read the project's modes and what each design shows. viewports are the ids Responsive takes; modes are the ids screenshot, find_problems and check_accessibility take, each one option per variable (viewport, theme, locale), with its width, window height and the classes and attributes it sets. designs gives each board's state, main mode and the modes beside it; name a design to get just it, with each frame's size and window. Reading changes nothing.", operations.modes, (result) => [text(describeModes(result))]),
 	{
 		name: "execute",
-		description: "Run a JavaScript snippet against a tab's designs with the Parity API (read_skill \"execute.md\"). All changes land as one undoable step, or none if it fails. On failure, retry with editId and edits instead of resending.",
-		inputSchema: {
-			type: "object",
-			properties: {
-				description: {
-					type: "string",
-					description: "Shown to the person while it runs. 3 to 8 words, imperative, e.g. \"Add pricing tiers\"."
-				},
-				input: {
-					type: "string",
-					description: "The snippet. Omit when retrying with editId and edits."
-				},
-				editId: {
-					type: "string",
-					description: "The failed call's editId, to patch and rerun its snippet."
-				},
-				edits: {
-					type: "array",
-					description: "Exact find and replace edits to the failed snippet, applied in order.",
-					items: {
-						type: "object",
-						properties: {
-							find: { type: "string" },
-							replace: { type: "string" },
-							all: { type: "boolean" }
-						},
-						required: ["find", "replace"]
-					}
-				},
-				tab
-			},
-			required: ["description"]
-		},
-		run: async (input) => {
-			const result = await call("exec", {
+		description: "Run a JavaScript snippet with the Parity API (read_skill \"execute.md\"). All changes land as one undoable step, or none on failure. Retry failures with editId and edits.",
+		inputSchema: executeOperation.inputSchema(executeNames),
+		fields: executeOperation.fields,
+		names: executeNames,
+		async run(input) {
+			const result = await executeOperation.run({
 				tab: input.tab,
 				label: input.description,
 				code: input.input,
 				editId: input.editId,
 				edits: input.edits
-			});
-			return [text(describeExec(result)), ...result.screenshots.map((shot) => image(shot.png))];
-		}
-	},
-	{
-		name: "screenshot",
-		description: "Capture a design in any of its states and modes, rendered offscreen at real widths. state and mode take an id, a list, or \"all\"; mode also takes \"shown\".",
-		inputSchema: {
-			type: "object",
-			properties: {
-				design: {
-					type: "string",
-					description: "Design id or name."
-				},
-				state: { description: "State id, list of ids, or \"all\". Defaults to the state the design shows." },
-				mode: { description: "Mode id, list of ids, \"shown\" or \"all\". Defaults to the primary mode." },
-				scale: {
-					type: "number",
-					description: "Pixel density, 0.25 to 3. Defaults to 1."
-				},
-				tab
-			},
-			required: ["design"]
-		},
-		run: async (input) => {
-			const result = await call("screenshot", input);
-			return [text(describeExec(result)), ...result.screenshots.map((shot) => image(shot.png))];
+			}, call);
+			const structured = executeOperation.structured(result);
+			return {
+				content: [text(describeExec(result)), ...result.screenshots.map((shot) => image(shot.png))],
+				structuredContent: result.error ? {
+					...structured,
+					error: renamePath(result.error, executeNames)
+				} : structured,
+				isError: executeOperation.failed(result)
+			};
 		}
 	},
-	{
-		name: "find_problems",
-		description: "Find layout problems in a design, rendered offscreen in every state and the modes it shows unless you narrow it: render errors, content wider than the frame, nodes cut off by a parent that clips, and components that aren't the project's. Run it after changes, with screenshot. state and mode take an id, a list, or \"all\"; mode also takes \"shown\".",
-		inputSchema: {
-			type: "object",
-			properties: {
-				design: {
-					type: "string",
-					description: "Design id or name."
-				},
-				state: { description: "State id, list of ids, or \"all\". Defaults to \"all\"." },
-				mode: { description: "Mode id, list of ids, \"shown\" or \"all\". Defaults to \"shown\"." },
-				tab
-			},
-			required: ["design"]
-		},
-		run: async (input) => [text(describeProblems(await call("problems", input)))]
-	},
-	{
-		name: "check_accessibility",
-		description: "Check a design's accessibility with axe-core against WCAG 2.2 AA, rendered offscreen in every state and the modes it shows unless you narrow it. Lists each rule broken, worst first, with the layers that break it (ids you can pass to execute), the frames, what's wrong and a link on how to fix it. state and mode take an id, a list, or \"all\"; mode also takes \"shown\". Automated checks find some issues, not all.",
-		inputSchema: {
-			type: "object",
-			properties: {
-				design: {
-					type: "string",
-					description: "Design id or name."
-				},
-				state: { description: "State id, list of ids, or \"all\". Defaults to \"all\"." },
-				mode: { description: "Mode id, list of ids, \"shown\" or \"all\". Defaults to \"shown\"." },
-				tab
-			},
-			required: ["design"]
-		},
-		run: async (input) => [text(describeAccessibility(await call("accessibility", input)))]
-	},
-	{
-		name: "get_console",
-		description: "Read what the project's own code wrote to the console: errors, warnings and logs from its components on the canvas, including while the person interacts with them, and from offscreen renders such as screenshots. Oldest first; the same message several times in a row is counted once. clear: true empties it after reading, so the next read shows only what's new.",
-		inputSchema: {
-			type: "object",
-			properties: {
-				clear: {
-					type: "boolean",
-					description: "Empty it after reading."
-				},
-				tab
-			}
-		},
-		run: async (input) => [text(describeConsole(await call("console", input)))]
-	},
-	{
-		name: "open_project",
-		description: "Open a project folder in a new Parity tab, or switch to it if it's already open.",
-		inputSchema: {
-			type: "object",
-			properties: { root: {
-				type: "string",
-				description: "Absolute path."
-			} },
-			required: ["root"]
-		},
-		run: async (input) => [text(JSON.stringify(await call("open", { root: input.root }), null, 2))]
-	},
+	operationTool("screenshot", "Capture a design in any of its states and modes, rendered offscreen at real widths. state and mode take an id, a list, or \"all\"; mode also takes \"shown\".", operations.screenshot, (result) => [text(describeExec(result)), ...result.screenshots.map((shot) => image(shot.png))]),
+	operationTool("find_problems", "Find layout problems in a design, rendered offscreen in every state and the modes it shows unless you narrow it: render errors, content wider than the frame, nodes cut off by a parent that clips, and components that aren't the project's. Run it after changes, with screenshot. state and mode take an id, a list, or \"all\"; mode also takes \"shown\".", operations.problems, (result) => [text(describeProblems(result))]),
+	operationTool("check_accessibility", "Check a design's accessibility with axe-core against WCAG 2.2 AA, rendered offscreen in every state and the modes it shows unless you narrow it. Lists each rule broken, worst first, with the layers that break it (ids you can pass to execute), the frames, what's wrong and a link on how to fix it. state and mode take an id, a list, or \"all\"; mode also takes \"shown\". Automated checks find some issues, not all.", operations.accessibility, (result) => [text(describeAccessibility(result))]),
+	operationTool("get_console", "Read what the project's own code wrote to the console: errors, warnings and logs from its components on the canvas, including while the person interacts with them, and from offscreen renders such as screenshots. Oldest first; the same message several times in a row is counted once. clear: true empties it after reading, so the next read shows only what's new.", operations.console, (result) => [text(describeConsole(result))]),
+	operationTool("open_project", "Open a project folder in a new Parity tab, or switch to it if it's already open.", operations.open, json),
+	operationTool("get_tokens", "Read tokens filtered by category, source or name, with values in every theme.", operations.tokens, (result) => [text(describeTokens(result))]),
+	operationTool("get_components", "List project components, libraries, icon sets and exports that were left out or failed to render.", operations.components, (result) => [text(describeComponents(result))]),
+	operationTool("get_props", "Read a component's props from source. all includes attributes it passes through.", operations.props, (result) => [text(describeProps(result))]),
 	{
 		name: "read_skill",
-		description: "Read Parity's design skill: SKILL.md, or a file it references such as execute.md or guide/web-app.md.",
-		inputSchema: {
-			type: "object",
-			properties: { path: { type: "string" } }
-		},
-		run: async (input) => [text(await readSkill(input.path))]
+		description: "Read the Parity design skill or a file it references.",
+		inputSchema: skillOperation.inputSchema,
+		fields: skillOperation.fields,
+		run: async (input) => ({ content: [text(await skillOperation.run(input, readSkill))] })
 	}
 ];
 const instructions = "Parity renders a project's real components on a canvas. Designs are trees of the project's own components, layouts and text, styled only with its tokens, with states (like stories) and modes (viewport, theme, locale). Read the skill (read_skill) before designing, start with get_app_state, change designs with execute, check every state and mode with screenshot and find_problems, check accessibility with check_accessibility, and read what the components log with get_console.";
@@ -548,10 +1407,12 @@ async function respond(message) {
 				message: `Unknown tool ${String(message.params?.name)}`
 			} };
 			try {
-				return { result: { content: await tool.run(message.params?.arguments ?? {}) } };
+				return { result: await tool.run(message.params?.arguments ?? {}) };
 			} catch (error) {
+				const failure = renamePath(operationError(error, tool.fields), tool.names ?? {});
 				return { result: {
-					content: [text(error instanceof Error ? error.message : String(error))],
+					content: [text(failure.message)],
+					structuredContent: { error: failure },
 					isError: true
 				} };
 			}
@@ -580,6 +1441,12 @@ const usage = `parity: drive the Parity app from a terminal or an agent
 
   parity tabs                               list open project tabs
   parity state [--tab t]                    designs, selection, modes, components and tokens of a tab
+  parity status [--summary] [--limit 10] [--tab t]
+                                            the tab's revision, whether anything applied isn't saved, the files and
+                                            token values waiting for Save, the last save and failed writes, and undo
+                                            and redo; --summary names the designs, tokens and steps
+  parity modes [design] [--tab t]           viewports (the ids Responsive takes), variables, modes (the ids renders
+                                            take) and what each design shows; a design adds its frames' sizes
   parity exec [file] --label "Do x"         run a snippet (from a file, or stdin) as one undoable step
        [--edit-id id --edits '[{"find":"a","replace":"b"}]']   retry a failed snippet with edits
   parity screenshot <design> [--state s|all] [--mode m|shown|all] [--scale 2] [--tab t]
@@ -589,10 +1456,13 @@ const usage = `parity: drive the Parity app from a terminal or an agent
   parity problems <design> [--state s|all] [--mode m|shown|all] [--tab t]
                                             render errors, overflow, clipping and unknown components, in every state
                                             and the modes shown unless narrowed; exits with 1 when it finds any
-  parity console [--clear] [--tab t]        what the project's code wrote to the console, on the canvas and in
-                                            offscreen renders; --clear empties it after reading
-  parity tokens [--category c] [--source semantic|theme] [--search s] [--tab t]
-                                            the tokens styles can name, with their values per theme
+  parity console [--clear] [--limit 50] [--tab t]
+                                            what the project's code wrote to the console, on the canvas and in
+                                            offscreen renders, the newest 50 unless --limit says; --clear empties it
+                                            after reading
+  parity tokens [--category c] [--source semantic|theme] [--search s] [--limit 100] [--tab t]
+                                            the tokens styles can name, with their values per theme, the first 100
+                                            unless --limit says
   parity components [--tab t]               the components designs can use, by library
   parity props <Component> [--all] [--tab t]
                                             a component's props from its source; --all adds the attributes it passes on
@@ -628,7 +1498,11 @@ const usage = `parity: drive the Parity app from a terminal or an agent
   parity skill [file]                       print the design skill, or one of its files
   parity mcp                                serve these as MCP tools on stdio
 
-Options take a tab id, project root or name with --tab; the active tab is the default.`;
+Options take a tab id, project root or name with --tab, or "active" for what the person is looking at; without it, a
+command acts on the open project the current folder is in, else on "active". Each call goes to the running copy of
+Parity that has its project open. --json prints any command's
+result as the data MCP returns as structuredContent, and a failure as {"error": {code, message, retryable, path,
+alternatives, editId}}.`;
 const { positionals, values } = parseArgs({
 	allowPositionals: true,
 	options: {
@@ -648,10 +1522,12 @@ const { positionals, values } = parseArgs({
 		json: { type: "boolean" },
 		record: { type: "boolean" },
 		clear: { type: "boolean" },
+		summary: { type: "boolean" },
 		all: { type: "boolean" },
 		category: { type: "string" },
 		source: { type: "string" },
 		search: { type: "string" },
+		limit: { type: "string" },
 		root: { type: "string" },
 		out: { type: "string" },
 		registry: { type: "boolean" },
@@ -669,10 +1545,14 @@ const { positionals, values } = parseArgs({
 	}
 });
 const [command, ...rest] = positionals;
+/** The running command's input fields, which a failure's path can point at. */
+let fields;
 try {
 	await main();
 } catch (error) {
-	console.error(error instanceof Error ? error.message : String(error));
+	const failure = operationError(error, fields);
+	if (values.json) print({ error: failure });
+	console.error(failure.message);
 	process.exitCode = 1;
 }
 async function main() {
@@ -680,14 +1560,23 @@ async function main() {
 		console.log(usage);
 		return;
 	}
+	const limit = values.limit === void 0 ? void 0 : Number(values.limit);
 	switch (command) {
-		case "tabs": return print(await call("tabs"));
-		case "state": return print(await call("state", { tab: values.tab }));
-		case "open":
-			if (!rest[0]) throw new Error("parity open <folder>");
-			return print(await call("open", { root: resolve(rest[0]) }));
+		case "tabs": return show(operations.tabs, {});
+		case "state": return show(operations.state, { tab: values.tab });
+		case "status": return show(operations.status, {
+			tab: values.tab,
+			summary: values.summary,
+			limit
+		}, describeStatus);
+		case "modes": return show(operations.modes, {
+			tab: values.tab,
+			design: rest[0]
+		}, describeModes);
+		case "open": return show(operations.open, { root: rest[0]?.trim() ? resolve(rest[0]) : rest[0] });
 		case "skill":
-			console.log(await readSkill(rest[0]));
+			fields = skillOperation.fields;
+			console.log(await skillOperation.run({ path: rest[0] }, readSkill));
 			return;
 		case "mcp":
 			serveMcp();
@@ -714,111 +1603,82 @@ async function main() {
 				...values.json ? { json: true } : {}
 			});
 		case "exec": {
+			fields = executeOperation.fields;
 			const editId = values["edit-id"];
 			let code;
-			if (!editId) code = rest[0] ? await readFile(rest[0], "utf8") : await stdin();
-			const edits = values.edits ? JSON.parse(values.edits) : void 0;
-			report(await call("exec", {
+			if (rest[0]) code = await readFile(rest[0], "utf8");
+			else if (!editId) code = await stdin() || void 0;
+			let edits;
+			try {
+				edits = values.edits === void 0 ? void 0 : JSON.parse(values.edits);
+			} catch {
+				throw invalidInput("edits", "edits must be JSON: a list of {find, replace}");
+			}
+			const result = await executeOperation.run({
 				tab: values.tab,
-				label: values.label ?? "Edit from the CLI",
+				label: values.label,
 				code,
 				editId,
 				edits
-			}));
+			}, call);
+			if (values.json) print(executeOperation.structured(result));
+			else console.log(describeExec(result));
+			if (executeOperation.failed(result)) process.exitCode = 1;
 			return;
 		}
-		case "screenshot":
-			if (!rest[0]) throw new Error("parity screenshot <design> [--state s] [--mode m]");
-			report(await call("screenshot", {
-				tab: values.tab,
-				design: rest[0],
-				state: one(values.state),
-				mode: one(values.mode),
-				scale: values.scale ? Number(values.scale) : void 0
-			}));
-			return;
+		case "screenshot": return show(operations.screenshot, {
+			tab: values.tab,
+			design: rest[0],
+			state: values.state,
+			mode: values.mode,
+			scale: values.scale === void 0 ? void 0 : Number(values.scale)
+		}, describeExec);
 		case "a11y":
-		case "accessibility": {
-			if (!rest[0]) throw new Error("parity a11y <design> [--state s] [--mode m]");
-			const result = await call("accessibility", {
-				tab: values.tab,
-				design: rest[0],
-				state: one(values.state),
-				mode: one(values.mode)
-			});
-			if (values.json) print(result);
-			else console.log(describeAccessibility(result));
-			if (result.findings.length > 0) process.exitCode = 1;
-			return;
-		}
-		case "problems": {
-			if (!rest[0]) throw new Error("parity problems <design> [--state s] [--mode m]");
-			const result = await call("problems", {
-				tab: values.tab,
-				design: rest[0],
-				state: one(values.state),
-				mode: one(values.mode)
-			});
-			if (values.json) print(result);
-			else console.log(describeProblems(result));
-			if (result.problems.length > 0) process.exitCode = 1;
-			return;
-		}
-		case "tokens": {
-			const filter = {
-				category: values.category,
-				source: values.source,
-				search: values.search
-			};
-			const tokens = await call("tokens", {
-				tab: values.tab,
-				...filter
-			});
-			if (values.json) print(tokens);
-			else console.log(describeTokens(tokens));
-			return;
-		}
-		case "components": {
-			const result = await call("components", { tab: values.tab });
-			if (values.json) print(result);
-			else console.log(describeComponents(result));
-			return;
-		}
-		case "props": {
-			if (!rest[0]) throw new Error("parity props <Component> [--all]");
-			const result = await call("props", {
-				tab: values.tab,
-				component: rest[0],
-				all: values.all
-			});
-			if (values.json) print(result);
-			else console.log(describeProps(result));
-			return;
-		}
-		case "console": {
-			const result = await call("console", {
-				tab: values.tab,
-				clear: values.clear
-			});
-			if (values.json) print(result);
-			else console.log(describeConsole(result));
-			return;
-		}
-		default: throw new Error(`Unknown command ${command}\n\n${usage}`);
+		case "accessibility": return show(operations.accessibility, {
+			tab: values.tab,
+			design: rest[0],
+			state: values.state,
+			mode: values.mode
+		}, describeAccessibility);
+		case "problems": return show(operations.problems, {
+			tab: values.tab,
+			design: rest[0],
+			state: values.state,
+			mode: values.mode
+		}, describeProblems);
+		case "tokens": return show(operations.tokens, {
+			tab: values.tab,
+			category: values.category,
+			source: values.source,
+			search: values.search,
+			limit
+		}, describeTokens);
+		case "components": return show(operations.components, { tab: values.tab }, describeComponents);
+		case "props": return show(operations.props, {
+			tab: values.tab,
+			component: rest[0],
+			all: values.all
+		}, describeProps);
+		case "console": return show(operations.console, {
+			tab: values.tab,
+			clear: values.clear,
+			limit
+		}, describeConsole);
+		default: throw invalidInput(void 0, `Unknown command ${command}
+
+${usage}`);
 	}
 }
-function report(result) {
-	if (values.json) print({
-		...result,
-		screenshots: result.screenshots.map(({ png: _png, ...shot }) => shot)
-	});
-	else console.log(describeExec(result));
-	if (!result.ok) process.exitCode = 1;
-}
-/** A repeated option becomes a list; one value stays a string, so "all" and "shown" work. */
-function one(list) {
-	if (!list || list.length === 0) return void 0;
-	return list.length === 1 ? list[0] : list;
+/**
+* Runs a shared operation and prints it: the structured result with --json, the same data MCP returns as
+* structuredContent, or the account for people. A failure exits with 1 either way.
+*/
+async function show(operation, input, describe) {
+	fields = operation.fields;
+	const result = await operation.run(input, call);
+	if (values.json || !describe) print(operation.structured(result));
+	else console.log(describe(result));
+	if (operation.failed(result)) process.exitCode = 1;
 }
 function print(value) {
 	console.log(JSON.stringify(value, null, 2));