@happyvertical/smrt-cli 0.55.10 → 0.55.11

package/dist/server-Dp096tZj.js

@@ -0,0 +1,898 @@
+import { c as SMRT_SCOPE, l as loadRegistryManifest, r as cliVersion, s as validateCookbookText, t as createCookbookApplier, u as resolveRecipeIndex } from "./apply-BNDIdixP.js";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash, randomUUID } from "node:crypto";
+import { validateCookbook } from "@happyvertical/smrt-core/cookbook";
+import { Server } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { buildBatchTool, checkSchema, createCookbookEngine } from "@happyvertical/smrt-core/cookbook/engine";
+//#region src/commands/kitchen/mcp/catalog.ts
+/**
+* The engine catalog (#3752) built from real recipe manifests: the recipes
+* each package declares, the models its objects declare, and the library of
+* ready-made cookbooks. Nothing here is invented; a package that cannot be
+* found contributes nothing and is reported.
+*/
+var FILE_SUFFIX = ".cookbook.json";
+/** Fields every object has, or that policies cannot target. */
+var SYSTEM_FIELDS = [
+	"id",
+	"slug",
+	"context",
+	"createdAt",
+	"updatedAt",
+	"created_at",
+	"updated_at"
+];
+/** `@happyvertical/smrt-commerce` -> `commerce`, as item ids spell it. */
+function packageIdOf(packageName) {
+	return packageName.replace(/^@[^/]+\//, "").replace(/^smrt-/, "");
+}
+var isExposed = (object) => {
+	const api = object.decoratorConfig?.api;
+	if (api === false) return false;
+	const include = api?.include;
+	return !(Array.isArray(include) && include.length === 0);
+};
+function modelsOf(packageName, manifest) {
+	const packageId = packageIdOf(packageName);
+	const models = [];
+	for (const [id, object] of Object.entries(manifest.objects ?? {})) {
+		const fields = object.fields ?? {};
+		const name = object.className ?? id.slice(id.lastIndexOf(":") + 1);
+		if (name.endsWith("Collection") && Object.keys(fields).length === 0) continue;
+		const listed = Object.entries(fields).map(([field, def]) => ({
+			name: field,
+			...def?._meta?.__tenancy ? { system: true } : {}
+		}));
+		for (const field of SYSTEM_FIELDS) if (!listed.some((f) => f.name === field)) listed.push({
+			name: field,
+			system: true
+		});
+		models.push({
+			id,
+			name,
+			packageId,
+			exposed: isExposed(object),
+			fields: listed
+		});
+	}
+	return models;
+}
+/** Recipes the engine can use: they need an id, a label and a nav list. */
+function recipesOf(manifest) {
+	return (manifest.recipes ?? []).flatMap((recipe) => recipe.id && recipe.label ? [{
+		...recipe,
+		id: recipe.id,
+		label: recipe.label,
+		models: recipe.models ?? [],
+		nav: recipe.nav ?? [],
+		requires: recipe.requires ?? []
+	}] : []);
+}
+/** Build the engine catalog from every manifest in the index. */
+function catalogFromIndex(index, cookbooks = []) {
+	const recipes = [];
+	const models = [];
+	for (const entry of [...index.packages.values()].sort((a, b) => a.packageName.localeCompare(b.packageName))) {
+		const manifest = entry.manifest;
+		recipes.push(...recipesOf(manifest));
+		models.push(...modelsOf(entry.packageName, manifest));
+	}
+	return {
+		recipes,
+		models,
+		cookbooks
+	};
+}
+/** The package that ships this CLI's own files (`cookbooks/`). */
+function packageRoot() {
+	let current = dirname(fileURLToPath(import.meta.url));
+	while (true) {
+		if (existsSync(join(current, "cookbooks"))) {
+			if (existsSync(join(current, "package.json"))) return current;
+		}
+		const parent = dirname(current);
+		if (parent === current) return dirname(fileURLToPath(import.meta.url));
+		current = parent;
+	}
+}
+/** `yoga-studio` -> `Yoga Studio`. */
+var titleOf = (id) => id.split(/[-_.]/).filter(Boolean).map((part) => part[0]?.toUpperCase() + part.slice(1)).join(" ");
+/**
+* Ready-made cookbooks from `<dir>/<id>.cookbook.json` files. A file that is
+* not a valid cookbook is skipped and named in `warnings`.
+*/
+function readLibraryDir(dir, warnings) {
+	if (!existsSync(dir)) {
+		warnings.push(`Cookbook library directory not found: ${dir}`);
+		return [];
+	}
+	const library = [];
+	for (const file of readdirSync(dir).sort()) {
+		if (!file.endsWith(FILE_SUFFIX)) continue;
+		const id = file.slice(0, -14);
+		try {
+			const checked = validateCookbook(JSON.parse(readFileSync(join(dir, file), "utf-8")));
+			if (!checked.ok) {
+				warnings.push(`${file}: ${checked.errors.join("; ")}`);
+				continue;
+			}
+			library.push({
+				id,
+				name: checked.cookbook.name ?? titleOf(id),
+				document: checked.cookbook
+			});
+		} catch (error) {
+			warnings.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return library;
+}
+/** The library this CLI ships plus any extra directories (later ids win). */
+function loadLibrary(extraDirs, warnings) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const dir of [join(packageRoot(), "cookbooks"), ...extraDirs.map((d) => resolve(d))]) for (const entry of readLibraryDir(dir, warnings)) byId.set(entry.id, entry);
+	return [...byId.values()];
+}
+/**
+* Resolve the manifests behind the library's recipes (local sources first,
+* then the scope registry, as `cookbook validate` does) and build the catalog.
+*/
+async function loadCatalog(options) {
+	const warnings = [];
+	const library = loadLibrary(options.library ?? [], warnings);
+	const index = await resolveRecipeIndex({
+		recipes: [...new Set(library.flatMap((c) => c.document.recipes))],
+		features: [],
+		policies: []
+	}, {
+		dir: options.dir,
+		manifests: options.manifests ?? [],
+		registry: options.registry !== false,
+		warn: (message) => warnings.push(message)
+	});
+	for (const name of options.packages ?? []) {
+		const full = name.startsWith("@") ? name : `${SMRT_SCOPE}/smrt-${name}`;
+		if (index.packages.has(full) || options.registry === false) continue;
+		if (!await loadRegistryManifest(index, full, { dir: options.dir })) warnings.push(`Could not find a manifest for ${full}.`);
+	}
+	for (const name of index.missing) warnings.push(`No manifest found for ${name}; its recipes are unavailable.`);
+	const catalog = catalogFromIndex(index, library);
+	if (catalog.recipes.length === 0) warnings.push(index.packages.size > 0 ? `Manifests were found for ${index.packages.size} package(s) but none declares recipes; use package versions that ship recipes, or pass --manifests.` : "No recipe manifests were found, so no recipes are available. Run from a SMRT workspace or project, pass --manifests, or allow registry access.");
+	return {
+		catalog,
+		index,
+		warnings
+	};
+}
+var SCHEMA = "https://json-schema.org/draft/2020-12/schema";
+var planId = {
+	type: "string",
+	description: "The plan id start_plan returned.",
+	minLength: 1,
+	maxLength: 100
+};
+var errorSchema = {
+	type: "object",
+	description: "Present when ok is false.",
+	properties: {
+		code: { type: "string" },
+		message: { type: "string" },
+		path: { type: "string" },
+		details: {
+			type: "object",
+			additionalProperties: true
+		}
+	},
+	required: ["code", "message"],
+	additionalProperties: true
+};
+var snapshotSchema = {
+	type: "object",
+	description: "The plan: revision, app name, recipes, features, settings, theme, menu sections and undo ids.",
+	properties: {
+		version: { type: "integer" },
+		revision: { type: "integer" }
+	},
+	required: ["revision"],
+	additionalProperties: true
+};
+/** An output schema: `ok` always, `error` when it is false, plus the extras. */
+var output = (properties, required = []) => ({
+	$schema: SCHEMA,
+	type: "object",
+	properties: {
+		ok: { type: "boolean" },
+		error: errorSchema,
+		warnings: {
+			type: "array",
+			items: { type: "string" }
+		},
+		...properties
+	},
+	required: ["ok", ...required],
+	additionalProperties: true
+});
+var input = (properties, required = []) => ({
+	$schema: SCHEMA,
+	type: "object",
+	properties,
+	...required.length ? { required } : {},
+	additionalProperties: false
+});
+var annotations = (title, hints) => ({
+	title,
+	readOnlyHint: false,
+	destructiveHint: false,
+	idempotentHint: false,
+	openWorldHint: false,
+	...hints
+});
+var READ_ONLY = {
+	readOnlyHint: true,
+	idempotentHint: true
+};
+/** The batch tool's schema without catalog enums: ids come from search_recipes. */
+var batchBase = buildBatchTool({
+	recipes: [],
+	models: []
+}).inputSchema;
+var KITCHEN_TOOLS = [
+	{
+		name: "list_cookbooks",
+		title: "List cookbooks",
+		description: "List the ready-made cookbooks (starting points such as a bakery or a yoga studio) with the recipes each one switches on. Start here to offer the user a head start.",
+		inputSchema: input({}),
+		outputSchema: output({ cookbooks: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					id: { type: "string" },
+					name: { type: "string" },
+					recipes: {
+						type: "array",
+						items: { type: "string" }
+					},
+					features: {
+						type: "array",
+						items: { type: "string" }
+					}
+				},
+				required: [
+					"id",
+					"name",
+					"recipes"
+				]
+			}
+		} }, ["cookbooks"]),
+		annotations: annotations("List cookbooks", READ_ONLY)
+	},
+	{
+		name: "search_recipes",
+		title: "Search recipes",
+		description: "Find recipes (units of app function such as Sales or Customers) by words in their id, name, summary or synonyms. With no query, lists them all. Use the returned ids with add_recipes.",
+		inputSchema: input({
+			query: {
+				type: "string",
+				description: "Words to look for; every word must match.",
+				maxLength: 200
+			},
+			limit: {
+				type: "integer",
+				description: "Most results to return (default 20).",
+				minimum: 1,
+				maximum: 100
+			}
+		}),
+		outputSchema: output({
+			total: { type: "integer" },
+			recipes: {
+				type: "array",
+				items: {
+					type: "object",
+					properties: {
+						id: { type: "string" },
+						label: { type: "string" },
+						summary: { type: "string" },
+						requires: {
+							type: "array",
+							items: { type: "string" }
+						},
+						models: {
+							type: "array",
+							items: { type: "string" }
+						}
+					},
+					required: ["id", "label"]
+				}
+			}
+		}, ["total", "recipes"]),
+		annotations: annotations("Search recipes", READ_ONLY)
+	},
+	{
+		name: "start_plan",
+		title: "Start a plan",
+		description: "Start a new plan for an app, empty or from a ready-made cookbook (see list_cookbooks). Returns the plan id every other tool takes. The plan lives in this server process until apply_plan writes it to a project.",
+		inputSchema: input({
+			cookbook: {
+				type: "string",
+				description: "A ready-made cookbook id from list_cookbooks.",
+				minLength: 1,
+				maxLength: 200
+			},
+			name: {
+				type: "string",
+				description: "A name for the app.",
+				minLength: 1,
+				maxLength: 200
+			}
+		}),
+		outputSchema: output({
+			planId: { type: "string" },
+			snapshot: snapshotSchema
+		}, []),
+		annotations: annotations("Start a plan", {})
+	},
+	{
+		name: "run_commands",
+		title: "Change the plan",
+		description: "Apply plan commands (add_recipes, set_settings, set_theme, rename_item, hide, ...) all-or-nothing. Send expectedRevision from the last snapshot so a stale change is refused, and a batch id so a retry is not applied twice. A single undo command is also accepted. Returns the new snapshot and one receipt per command.",
+		inputSchema: {
+			...batchBase,
+			$schema: SCHEMA,
+			properties: {
+				planId,
+				...batchBase.properties
+			},
+			required: ["planId", "commands"]
+		},
+		outputSchema: output({
+			planId: { type: "string" },
+			replayed: { type: "boolean" },
+			receipt: {
+				type: "object",
+				additionalProperties: true
+			},
+			results: {
+				type: "array",
+				items: { type: "object" }
+			},
+			snapshot: snapshotSchema
+		}),
+		annotations: annotations("Change the plan", { idempotentHint: true })
+	},
+	{
+		name: "get_plan",
+		title: "Get the plan",
+		description: "The current plan as a compact snapshot: revision, recipes, settings, theme and the menu the app would show.",
+		inputSchema: input({ planId }, ["planId"]),
+		outputSchema: output({
+			planId: { type: "string" },
+			snapshot: snapshotSchema
+		}),
+		annotations: annotations("Get the plan", READ_ONLY)
+	},
+	{
+		name: "validate_plan",
+		title: "Validate the plan",
+		description: "Check the plan as a cookbook: the document, that every recipe exists with what it requires, and that policies name real fields. Run before apply_plan. Changes nothing.",
+		inputSchema: input({ planId }, ["planId"]),
+		outputSchema: output({
+			planId: { type: "string" },
+			valid: { type: "boolean" },
+			errors: {
+				type: "array",
+				items: { type: "string" }
+			},
+			diagnostics: {
+				type: "array",
+				items: { type: "object" }
+			},
+			packages: {
+				type: "array",
+				items: { type: "string" }
+			}
+		}),
+		annotations: annotations("Validate the plan", READ_ONLY)
+	},
+	{
+		name: "export_plan",
+		title: "Export the plan",
+		description: "The plan as a cookbook document (version 1) and its `<name>.cookbook.json` text, to show, save or send elsewhere. Changes nothing.",
+		inputSchema: input({
+			planId,
+			name: {
+				type: "string",
+				description: "File name stem; default the app name.",
+				maxLength: 200
+			}
+		}, ["planId"]),
+		outputSchema: output({
+			planId: { type: "string" },
+			fileName: { type: "string" },
+			text: { type: "string" },
+			cookbook: {
+				type: "object",
+				additionalProperties: true
+			}
+		}),
+		annotations: annotations("Export the plan", READ_ONLY)
+	},
+	{
+		name: "apply_plan",
+		title: "Create the project",
+		description: "Create the project from the plan in an absolute directory: copy the template, add the packages the recipes need to package.json, and write smrt.cookbook.json. Writes files, so ask the user to confirm the directory first; without confirm: true and the confirmCode from the preview nothing is written and the plan is previewed. The template is set by the server (--template), not chosen per call. Re-applying to a project that already has smrt.cookbook.json updates it. Does not install packages unless install is true.",
+		inputSchema: input({
+			planId,
+			dir: {
+				type: "string",
+				description: "Absolute path of the project directory: absent or empty for a new project, or an existing project that holds smrt.cookbook.json.",
+				minLength: 1,
+				maxLength: 1e3
+			},
+			confirm: {
+				type: "boolean",
+				description: "true once the user agreed to write into dir. Needs confirmCode from the preview of this same plan and dir; otherwise only a preview is returned."
+			},
+			confirmCode: {
+				type: "string",
+				description: "The confirmCode the preview returned for this exact plan state and dir. A code from another dir or an edited plan is refused.",
+				maxLength: 200
+			},
+			dryRun: {
+				type: "boolean",
+				description: "Preview only, even with confirm."
+			},
+			install: {
+				type: "boolean",
+				description: "Run the package manager install afterwards (slow; default false)."
+			}
+		}, ["planId", "dir"]),
+		outputSchema: output({
+			planId: { type: "string" },
+			applied: { type: "boolean" },
+			confirmCode: { type: "string" },
+			dir: { type: "string" },
+			mode: {
+				type: "string",
+				enum: ["new", "update"]
+			},
+			installed: { type: "boolean" },
+			packagesAdded: {
+				type: "array",
+				items: { type: "string" }
+			},
+			config: { type: "string" },
+			nextSteps: {
+				type: "array",
+				items: { type: "string" }
+			},
+			errors: {
+				type: "array",
+				items: { type: "string" }
+			}
+		}),
+		annotations: annotations("Create the project", {
+			destructiveHint: true,
+			idempotentHint: true,
+			openWorldHint: true
+		})
+	}
+];
+var fail = (code, message, extra = {}) => ({
+	data: {
+		ok: false,
+		error: {
+			code,
+			message,
+			...extra
+		}
+	},
+	text: `Error ${code}: ${message}`
+});
+var failFrom = (error) => fail(error.code, error.message, {
+	...error.path ? { path: error.path } : {},
+	...error.details ? { details: error.details } : {}
+});
+/** One line of a snapshot, for the model's text. */
+function describeSnapshot(snapshot) {
+	const recipes = snapshot.recipes.map((r) => r.id).join(", ") || "none";
+	const menu = snapshot.sections.filter((s) => !s.hidden).map((s) => `${s.label} (${s.items.filter((i) => !i.hidden).map((i) => i.label).join(", ")})`).join("; ");
+	return [
+		`"${snapshot.app.name}" revision ${snapshot.revision}`,
+		`recipes: ${recipes}`,
+		...snapshot.features.length ? [`features: ${snapshot.features.join(", ")}`] : [],
+		...snapshot.unavailable.length ? [`unavailable: ${snapshot.unavailable.join(", ")}`] : [],
+		`settings: ${snapshot.settings.currency}, tax ${snapshot.settings.taxRate}%, ${snapshot.settings.paymentTerms}`,
+		`theme: ${snapshot.theme.text}`,
+		`menu: ${menu || "empty"}`
+	].join("\n");
+}
+/** The first `max` lines, then a count of the rest. */
+var firstLines = (lines, max) => [...lines.slice(0, max), ...lines.length > max ? [`... and ${lines.length - max} more`] : []].join("\n");
+/** Tools that say what the catalog lacks; the rest stay quiet. */
+var WARNS = /* @__PURE__ */ new Set([
+	"list_cookbooks",
+	"search_recipes",
+	"start_plan",
+	"validate_plan"
+]);
+var words = (text) => text.toLowerCase().split(/\s+/).filter(Boolean);
+/** The server's state: the lazily loaded catalog and the plans. */
+var KitchenSession = class KitchenSession {
+	options;
+	loaded;
+	plans = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.options = options;
+	}
+	/** Load the catalog once; a failed load is retried on the next call. */
+	catalog() {
+		if (!this.loaded) {
+			const load = this.options.catalogLoader ?? (() => loadCatalog(this.options));
+			this.loaded = load().catch((error) => {
+				this.loaded = void 0;
+				throw error;
+			});
+		}
+		return this.loaded;
+	}
+	plan(id) {
+		return (typeof id === "string" ? this.plans.get(id) : void 0) ?? fail("not_found", `No plan ${JSON.stringify(id)} in this server; call start_plan (a restart forgets plans).`, { path: "planId" });
+	}
+	/** Validate arguments against a tool's published schema. */
+	static check(tool, args) {
+		const problem = checkSchema(tool.inputSchema, args, "arguments");
+		return problem ? fail("invalid_input", problem.message, { path: problem.path }) : null;
+	}
+	async call(name, args = {}) {
+		const tool = KITCHEN_TOOLS.find((t) => t.name === name);
+		if (!tool) return fail("unknown_tool", `Unknown tool ${JSON.stringify(name)}.`);
+		const invalid = KitchenSession.check(tool, args);
+		if (invalid) return invalid;
+		try {
+			const result = await this.dispatch(name, args);
+			if (!result.data.ok || !WARNS.has(name)) return result;
+			const { warnings } = await this.catalog().catch(() => ({ warnings: [] }));
+			if (!warnings.length || result.data.warnings) return result;
+			return {
+				data: {
+					...result.data,
+					warnings
+				},
+				text: `${result.text}\nWarnings:\n${firstLines(warnings, 5)}`
+			};
+		} catch (error) {
+			return fail("failed", error instanceof Error ? error.message : String(error));
+		}
+	}
+	async dispatch(name, args) {
+		switch (name) {
+			case "list_cookbooks": return this.listCookbooks();
+			case "search_recipes": return this.searchRecipes(args);
+			case "start_plan": return this.startPlan(args);
+			case "run_commands": return this.runCommands(args);
+			case "get_plan": {
+				const plan = this.plan(args.planId);
+				if (!("engine" in plan)) return plan;
+				const snapshot = plan.engine.snapshot();
+				return {
+					data: {
+						ok: true,
+						planId: args.planId,
+						snapshot
+					},
+					text: describeSnapshot(snapshot)
+				};
+			}
+			case "validate_plan": return this.validatePlan(args);
+			case "export_plan": return this.exportPlan(args);
+			case "apply_plan": return this.applyPlan(args);
+			default: return fail("unknown_tool", `Unknown tool ${JSON.stringify(name)}.`);
+		}
+	}
+	async listCookbooks() {
+		const { catalog } = await this.catalog();
+		const cookbooks = (catalog.cookbooks ?? []).map((c) => ({
+			id: c.id,
+			name: c.name,
+			recipes: c.document.recipes,
+			features: c.document.features
+		}));
+		return {
+			data: {
+				ok: true,
+				cookbooks
+			},
+			text: cookbooks.length ? cookbooks.map((c) => `${c.id}: ${c.name} (${c.recipes.join(", ")})`).join("\n") : "No ready-made cookbooks are available; start an empty plan."
+		};
+	}
+	async searchRecipes(args) {
+		const { catalog } = await this.catalog();
+		const wanted = words(typeof args.query === "string" ? args.query : "");
+		const limit = typeof args.limit === "number" ? args.limit : 20;
+		const matches = catalog.recipes.filter((recipe) => {
+			const hay = `${recipe.id} ${recipe.label} ${recipe.summary ?? ""} ${(recipe.synonyms ?? []).join(" ")}`.toLowerCase();
+			return wanted.every((word) => hay.includes(word));
+		});
+		const recipes = matches.slice(0, limit).map((recipe) => ({
+			id: recipe.id,
+			label: recipe.label,
+			summary: recipe.summary ?? "",
+			requires: recipe.requires,
+			models: recipe.models
+		}));
+		return {
+			data: {
+				ok: true,
+				total: matches.length,
+				recipes
+			},
+			text: recipes.length ? `${matches.length} recipe(s)${matches.length > recipes.length ? `, first ${recipes.length}` : ""}:\n${recipes.map((r) => `${r.id}: ${r.label}${r.summary ? ` - ${r.summary}` : ""}`).join("\n")}` : "No recipes match."
+		};
+	}
+	async startPlan(args) {
+		const { catalog } = await this.catalog();
+		const engine = createCookbookEngine({ catalog });
+		const steps = [];
+		if (typeof args.cookbook === "string") steps.push({
+			name: "apply_cookbook",
+			input: { id: args.cookbook }
+		});
+		if (typeof args.name === "string") steps.push({
+			name: "set_name",
+			input: { name: args.name }
+		});
+		for (const step of steps) {
+			const result = engine.run(step);
+			if (!result.ok) return failFrom(result.error);
+		}
+		const id = `plan-${randomUUID().slice(0, 8)}`;
+		this.plans.set(id, { engine });
+		while (this.plans.size > 20) {
+			const oldest = this.plans.keys().next().value;
+			if (oldest === void 0) break;
+			this.plans.delete(oldest);
+		}
+		const snapshot = engine.snapshot();
+		return {
+			data: {
+				ok: true,
+				planId: id,
+				snapshot
+			},
+			text: `Started ${id}.\n${describeSnapshot(snapshot)}`
+		};
+	}
+	runCommands(args) {
+		const plan = this.plan(args.planId);
+		if (!("engine" in plan)) return plan;
+		const { planId: _planId, ...batch } = args;
+		const commands = batch.commands;
+		const lone = commands.length === 1 && commands[0]?.name === "undo" ? plan.engine.run({
+			...commands[0],
+			...batch.id !== void 0 ? { id: batch.id } : {},
+			...batch.expectedRevision !== void 0 ? { expectedRevision: batch.expectedRevision } : {}
+		}) : null;
+		if (lone) {
+			if (!lone.ok) return failFrom(lone.error);
+			return {
+				data: {
+					ok: true,
+					planId: args.planId,
+					...lone.replayed ? { replayed: true } : {},
+					receipt: lone.receipt,
+					results: [lone.receipt],
+					snapshot: lone.snapshot
+				},
+				text: `${lone.receipt.summary}\n${describeSnapshot(lone.snapshot)}`
+			};
+		}
+		const result = plan.engine.batch(batch);
+		if (!result.ok) {
+			const current = result.snapshot;
+			return {
+				data: {
+					ok: false,
+					planId: args.planId,
+					error: result.error,
+					snapshot: current
+				},
+				text: `Error ${result.error.code}: ${result.error.message}\nNothing was changed (revision ${current.revision}).`
+			};
+		}
+		return {
+			data: {
+				ok: true,
+				planId: args.planId,
+				...result.replayed ? { replayed: true } : {},
+				receipt: result.receipt,
+				results: result.results.map((r) => r.receipt),
+				snapshot: result.snapshot
+			},
+			text: `${result.replayed ? "Already applied (same id): " : ""}${result.results.map((r) => r.receipt.summary).join("\n")}\n${describeSnapshot(result.snapshot)}`
+		};
+	}
+	async validatePlan(args) {
+		const plan = this.plan(args.planId);
+		if (!("engine" in plan)) return plan;
+		const { index } = await this.catalog();
+		const checked = plan.engine.run({ name: "validate" });
+		if (!checked.ok) return failFrom(checked.error);
+		const diagnostics = checked.data.diagnostics;
+		const exported = plan.engine.run({ name: "export_cookbook" });
+		if (!exported.ok) return failFrom(exported.error);
+		const report = validateCookbookText(exported.data.text, index);
+		const valid = checked.data.ok && report.ok;
+		const errors = report.errors;
+		return {
+			data: {
+				ok: true,
+				planId: args.planId,
+				valid,
+				errors,
+				diagnostics,
+				packages: report.packages,
+				...report.warnings.length ? { warnings: report.warnings } : {}
+			},
+			text: valid ? `Valid. Packages needed: ${report.packages.join(", ") || "none"}.` : `Not valid:\n${firstLines(errors.length ? errors : diagnostics.map((d) => `${d.path}: ${d.message}`), 12)}`
+		};
+	}
+	exportPlan(args) {
+		const plan = this.plan(args.planId);
+		if (!("engine" in plan)) return plan;
+		const result = plan.engine.run({
+			name: "export_cookbook",
+			input: typeof args.name === "string" ? { name: args.name } : {}
+		});
+		if (!result.ok) return failFrom(result.error);
+		const exported = result.data;
+		return {
+			data: {
+				ok: true,
+				planId: args.planId,
+				fileName: exported.fileName,
+				text: exported.text,
+				cookbook: exported.cookbook
+			},
+			text: `${exported.fileName}\n${exported.text}`
+		};
+	}
+	async applyPlan(args) {
+		const plan = this.plan(args.planId);
+		if (!("engine" in plan)) return plan;
+		const dir = args.dir;
+		if (!isAbsolute(dir)) return fail("invalid_input", "dir must be an absolute path.", { path: "dir" });
+		const exported = plan.engine.run({ name: "export_cookbook" });
+		if (!exported.ok) return failFrom(exported.error);
+		const confirmCode = createHash("sha256").update([
+			dir,
+			this.options.template ?? "",
+			exported.data.text
+		].join("\0")).digest("hex").slice(0, 32);
+		const confirmed = args.confirm === true && args.dryRun !== true && args.confirmCode === confirmCode;
+		const { index } = await this.catalog();
+		const outcome = await createCookbookApplier({
+			dir,
+			index,
+			template: this.options.template,
+			install: confirmed && args.install === true,
+			installOutput: "stderr",
+			dryRun: !confirmed,
+			manifests: this.options.manifests,
+			registry: this.options.registry !== false
+		})(exported.data.text);
+		if (!outcome.ok) return {
+			data: {
+				ok: false,
+				planId: args.planId,
+				error: {
+					code: outcome.status === 422 ? "invalid_cookbook" : "apply_refused",
+					message: outcome.errors.join("; ")
+				},
+				errors: outcome.errors
+			},
+			text: `Not applied:\n${firstLines(outcome.errors, 12)}`
+		};
+		const { plan: applied } = outcome.result;
+		const added = Object.keys(applied.addDependencies);
+		const summary = `${applied.mode === "new" ? "new project" : "update"} in ${applied.targetDir}; packages added: ${added.join(", ") || "none"}; smrt.cookbook.json ${applied.config}`;
+		const common = {
+			planId: args.planId,
+			dir: applied.targetDir,
+			mode: applied.mode,
+			packagesAdded: added,
+			config: applied.config,
+			nextSteps: outcome.body.nextSteps
+		};
+		if (!confirmed) return {
+			data: {
+				ok: false,
+				error: {
+					code: "confirmation_required",
+					message: "Nothing was written. Show the user this preview and the directory, then call apply_plan again with confirm: true and this confirmCode once they agree.",
+					details: { preview: summary }
+				},
+				confirmCode,
+				applied: false,
+				installed: false,
+				...common
+			},
+			text: `Preview only (nothing written): ${summary}\nAsk the user to confirm, then call apply_plan with confirm: true and confirmCode: ${confirmCode}.`
+		};
+		return {
+			data: {
+				ok: true,
+				applied: true,
+				installed: outcome.body.installed,
+				...common
+			},
+			text: `Applied: ${summary}\nNext steps:\n${outcome.body.nextSteps.join("\n")}`
+		};
+	}
+};
+//#endregion
+//#region src/commands/kitchen/mcp/server.ts
+/**
+* `smrt kitchen mcp` (#3752): the Kitchen tools served over stdio. stdout
+* carries the protocol only; everything else goes to stderr.
+*/
+var SERVER_NAME = "smrt-kitchen";
+/** The tool catalog changes only with a release. */
+var CATALOG_CACHE_HINT = {
+	ttlMs: 864e5,
+	cacheScope: "private"
+};
+/** Build the MCP server; one {@link KitchenSession} (plans, catalog) per server. */
+function createKitchenMcpServer(options) {
+	const session = new KitchenSession(options);
+	const server = new Server({
+		name: SERVER_NAME,
+		version: cliVersion()
+	}, {
+		capabilities: { tools: {} },
+		cacheHints: { "tools/list": CATALOG_CACHE_HINT }
+	});
+	server.setRequestHandler("tools/list", async () => ({ tools: KITCHEN_TOOLS.map((tool) => ({
+		name: tool.name,
+		title: tool.title,
+		description: tool.description,
+		inputSchema: tool.inputSchema,
+		outputSchema: tool.outputSchema,
+		annotations: tool.annotations
+	})) }));
+	server.setRequestHandler("tools/call", async (request) => {
+		const { name, arguments: args } = request.params;
+		const result = await session.call(name, args ?? {});
+		return {
+			content: [{
+				type: "text",
+				text: result.text
+			}],
+			structuredContent: result.data,
+			...result.data.ok ? {} : { isError: true }
+		};
+	});
+	return {
+		server,
+		session
+	};
+}
+/** Serve on this process's stdio until the host closes it or the process is stopped. */
+async function runKitchenMcp(options) {
+	const handle = serveStdio(() => createKitchenMcpServer(options).server, { onerror: (error) => console.error(`[${SERVER_NAME}] ${error.message}`) });
+	await new Promise((resolve) => {
+		const done = () => {
+			handle.close().finally(resolve);
+		};
+		process.once("SIGINT", done);
+		process.once("SIGTERM", done);
+		process.stdin.once("end", done);
+		process.stdin.once("close", done);
+	});
+}
+//#endregion
+export { runKitchenMcp };