@happyvertical/smrt-scanner 0.55.1 → 0.55.3

package/dist/chunks/{scanner-ItT4WTxN.js → scanner-CeTWAIar.js}

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { isAbsolute, relative, resolve, sep, win32 } from "node:path";
+import { dirname, isAbsolute, relative, resolve, sep, win32 } from "node:path";
 import fg from "fast-glob";
 import { parseSync } from "oxc-parser";
 //#region src/source-location.ts
@@ -759,6 +759,87 @@ function normalizeGlobSeparators(pattern, pathSeparator = sep) {
 	return pathSeparator === "/" ? pattern : pattern.replaceAll(pathSeparator, "/");
 }
 //#endregion
+//#region src/enum-values.ts
+var MAX_ALIAS_DEPTH = 8;
+function splitUnion(type) {
+	const parts = [];
+	let current = "";
+	let quote = null;
+	let escaped = false;
+	for (const ch of type) {
+		if (quote) {
+			current += ch;
+			if (escaped) escaped = false;
+			else if (ch === "\\") escaped = true;
+			else if (ch === quote) quote = null;
+			continue;
+		}
+		if (ch === "'" || ch === "\"") {
+			quote = ch;
+			current += ch;
+		} else if (ch === "|") {
+			parts.push(current.trim());
+			current = "";
+		} else current += ch;
+	}
+	parts.push(current.trim());
+	return parts.filter((part) => part !== "");
+}
+function resolveMember(member, aliases, depth, out) {
+	const quoted = member.match(/^(['"])(.*)\1$/s);
+	if (quoted) try {
+		let encoded = member;
+		if (quoted[1] === "'") {
+			encoded = "\"";
+			for (let index = 0; index < quoted[2].length; index += 1) {
+				const char = quoted[2][index];
+				if (char === "\\" && quoted[2][index + 1]) {
+					const escapedChar = quoted[2][index + 1];
+					encoded += escapedChar === "'" ? "'" : `\\${escapedChar}`;
+					index += 1;
+				} else encoded += char === "\"" ? "\\\"" : char;
+			}
+			encoded += "\"";
+		}
+		const value = JSON.parse(encoded);
+		if (typeof value !== "string") return false;
+		out.push(value);
+		return true;
+	} catch {
+		return false;
+	}
+	if (/^-?\d+(\.\d+)?$/.test(member)) {
+		out.push(Number(member));
+		return true;
+	}
+	if (member === "null" || member === "undefined") return true;
+	if (depth < MAX_ALIAS_DEPTH && /^[A-Za-z_$][\w$]*$/.test(member) && Object.hasOwn(aliases, member)) {
+		const nested = collect$1(aliases[member], aliases, depth + 1);
+		if (!nested) return false;
+		out.push(...nested);
+		return true;
+	}
+	return false;
+}
+function collect$1(type, aliases, depth) {
+	const out = [];
+	for (const member of splitUnion(type)) if (!resolveMember(member, aliases, depth, out)) return void 0;
+	return out;
+}
+function resolveEnumValues(type, aliases = {}) {
+	if (!type) return void 0;
+	const values = collect$1(type.trim(), aliases, 0);
+	if (!values || values.length === 0) return void 0;
+	const seen = /* @__PURE__ */ new Set();
+	const unique = [];
+	for (const value of values) {
+		if (seen.has(value)) continue;
+		seen.add(value);
+		unique.push(value);
+	}
+	return unique;
+}
+//#endregion
 //#region src/inheritance-resolver.ts
 var FRAMEWORK_BASE_CLASSES = /* @__PURE__ */ new Set([
 	"SmrtObject",
@@ -1076,6 +1157,606 @@ var InheritanceResolver = class {
 	}
 };
 //#endregion
+//#region src/recipes.ts
+var RECIPE_BASE = "SmrtRecipe";
+var CORE_SPECIFIER = "@happyvertical/smrt-core";
+function isCoreSpecifier(source) {
+	return source === CORE_SPECIFIER || source.startsWith(`${CORE_SPECIFIER}/`);
+}
+var RECIPE_ID_PATTERN = /^[a-z][a-z0-9]*(?:\.[a-z0-9][a-z0-9_-]*)+$/;
+var RECIPE_ID_MAX_LENGTH = 128;
+var FIELD_OPTION_KEYS = /* @__PURE__ */ new Set([
+	"default",
+	"label",
+	"help",
+	"order",
+	"visibility",
+	"locked"
+]);
+var VISIBILITIES = /* @__PURE__ */ new Set([
+	"basic",
+	"advanced",
+	"hidden"
+]);
+var EXPOSURE_TRANSPORTS = [
+	"api",
+	"mcp",
+	"cli"
+];
+function sourceMayDeclareRecipe(sourceText) {
+	return sourceText.includes(RECIPE_BASE);
+}
+var RecipeReadError = class extends Error {
+	constructor(message, node) {
+		super(message);
+		this.node = node;
+	}
+	node;
+};
+function collectImports(body) {
+	const bindings = /* @__PURE__ */ new Map();
+	for (const node of body) {
+		if (node.type !== "ImportDeclaration") continue;
+		const source = node.source?.value;
+		if (typeof source !== "string") continue;
+		for (const spec of node.specifiers ?? []) {
+			const local = spec.local?.name;
+			if (typeof local !== "string") continue;
+			if (spec.type === "ImportSpecifier") {
+				const imported = spec.imported;
+				const name = imported?.name ?? imported?.value;
+				if (typeof name === "string") bindings.set(local, {
+					imported: name,
+					source,
+					namespace: false
+				});
+			} else if (spec.type === "ImportDefaultSpecifier") bindings.set(local, {
+				imported: local,
+				source,
+				namespace: false
+			});
+			else if (spec.type === "ImportNamespaceSpecifier") bindings.set(local, {
+				imported: "*",
+				source,
+				namespace: true
+			});
+		}
+	}
+	return bindings;
+}
+function unwrap(node) {
+	let current = node;
+	for (let depth = 0; depth < 8; depth++) {
+		if (current.type === "TSAsExpression" || current.type === "TSSatisfiesExpression" || current.type === "TSNonNullExpression" || current.type === "TSTypeAssertion" || current.type === "ParenthesizedExpression") {
+			current = current.expression;
+			continue;
+		}
+		break;
+	}
+	return current;
+}
+function isRecipeBase(superClass, imports) {
+	if (!superClass) return false;
+	const node = unwrap(superClass);
+	if (node.type === "Identifier") {
+		const binding = imports.get(node.name);
+		return !!binding && binding.imported === RECIPE_BASE && isCoreSpecifier(binding.source);
+	}
+	if (node.type === "MemberExpression" && node.computed !== true) {
+		const object = node.object;
+		const property = node.property;
+		const binding = object.type === "Identifier" ? imports.get(object.name) : void 0;
+		return !!binding && binding.namespace && isCoreSpecifier(binding.source) && property.name === RECIPE_BASE;
+	}
+	return false;
+}
+function keyName(node) {
+	if (node.computed === true) return null;
+	const key = node.key;
+	if (!key) return null;
+	if (key.type === "Identifier") return key.name;
+	if (key.type === "Literal" && typeof key.value === "string") return key.value;
+	return null;
+}
+function stringValue(node, what) {
+	const value = unwrap(node);
+	if (value.type === "Literal" && typeof value.value === "string") return value.value;
+	if (value.type === "TemplateLiteral" && value.expressions.length === 0) {
+		const cooked = value.quasis[0]?.value?.cooked;
+		if (typeof cooked === "string") return cooked;
+	}
+	throw new RecipeReadError(`${what} must be a string literal`, node);
+}
+function arrayElements(node, what) {
+	const value = unwrap(node);
+	if (value.type !== "ArrayExpression") throw new RecipeReadError(`${what} must be an array literal`, node);
+	return value.elements.map((element) => {
+		if (!element || element.type === "SpreadElement") throw new RecipeReadError(`${what} must list its entries literally (no spread or holes)`, element ?? node);
+		return element;
+	});
+}
+function objectEntries(node, what) {
+	const value = unwrap(node);
+	if (value.type !== "ObjectExpression") throw new RecipeReadError(`${what} must be an object literal`, node);
+	return value.properties.map((property) => {
+		if (property.type !== "Property" || property.kind !== "init") throw new RecipeReadError(`${what} must use plain \`key: value\` properties (no spread, getters, or methods)`, property);
+		if (property.method === true) throw new RecipeReadError(`${what} cannot contain methods`, property);
+		const key = keyName(property);
+		if (key === null) throw new RecipeReadError(`${what} cannot use computed property keys`, property);
+		return {
+			key,
+			value: property.value,
+			node: property
+		};
+	});
+}
+function literalValue(node, what, depth = 0) {
+	if (depth > 16) throw new RecipeReadError(`${what} is nested too deeply`, node);
+	const value = unwrap(node);
+	switch (value.type) {
+		case "Literal":
+			if (value.regex || typeof value.value === "bigint") break;
+			return value.value;
+		case "TemplateLiteral": return stringValue(value, what);
+		case "UnaryExpression": {
+			const argument = unwrap(value.argument);
+			if ((value.operator === "-" || value.operator === "+") && argument.type === "Literal" && typeof argument.value === "number") return value.operator === "-" ? -argument.value : argument.value;
+			break;
+		}
+		case "ArrayExpression": return arrayElements(value, what).map((element) => literalValue(element, what, depth + 1));
+		case "ObjectExpression": {
+			const out = {};
+			for (const entry of objectEntries(value, what)) {
+				if (isUnsafeKey(entry.key)) throw new RecipeReadError(`${what} cannot use the key \`${entry.key}\``, entry.node);
+				out[entry.key] = literalValue(entry.value, what, depth + 1);
+			}
+			return out;
+		}
+		default: break;
+	}
+	throw new RecipeReadError(`${what} must be a literal value; the scanner cannot evaluate expressions`, node);
+}
+function isUnsafeKey(key) {
+	return key === "__proto__" || key === "constructor" || key === "prototype";
+}
+function modelRef(node, imports, declaredHere, what, sourceText) {
+	const value = unwrap(node);
+	const line = lineOf(sourceText, value);
+	if (value.type === "Identifier") {
+		const local = value.name;
+		const binding = imports.get(local);
+		if (binding && !binding.namespace) return {
+			local,
+			imported: binding.imported,
+			source: binding.source,
+			line
+		};
+		if (declaredHere.has(local)) return {
+			local,
+			imported: local,
+			source: null,
+			line
+		};
+		throw new RecipeReadError(`${what} \`${local}\` is neither imported nor declared in this file`, node);
+	}
+	if (value.type === "MemberExpression" && value.computed !== true && value.object.type === "Identifier") {
+		const object = value.object.name;
+		const binding = imports.get(object);
+		const property = value.property.name;
+		if (binding?.namespace && typeof property === "string") return {
+			local: `${object}.${property}`,
+			imported: property,
+			source: binding.source,
+			line
+		};
+	}
+	throw new RecipeReadError(`${what} must be a class reference (an imported or same-file class identifier), not an expression or a string`, node);
+}
+function lineOf(sourceText, node) {
+	const start = node.start;
+	return typeof start === "number" ? getLineColumn(sourceText, start)?.line : void 0;
+}
+function extractRecipes(input) {
+	const body = input.body;
+	const imports = collectImports(body);
+	const recipes = [];
+	const errors = [];
+	const classes = [];
+	const declaredHere = /* @__PURE__ */ new Set();
+	for (const statement of body) {
+		let node = statement;
+		if ((node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration") && node.declaration) node = node.declaration;
+		if (node.type === "ClassDeclaration") {
+			classes.push(node);
+			const name = node.id?.name;
+			if (typeof name === "string") declaredHere.add(name);
+		}
+	}
+	const recipeNames = /* @__PURE__ */ new Set();
+	for (const node of classes) if (isRecipeBase(node.superClass, imports)) recipeNames.add(node.id?.name ?? "");
+	const reportAt = (message, at) => {
+		const loc = typeof at.start === "number" ? getLineColumn(input.sourceText, at.start) : void 0;
+		errors.push({
+			message,
+			filePath: input.filePath,
+			line: loc?.line,
+			column: loc?.column,
+			severity: "error"
+		});
+	};
+	for (const node of classes) {
+		const base = node.superClass ? unwrap(node.superClass) : void 0;
+		if (base?.type === "Identifier" && recipeNames.has(base.name) && !isRecipeBase(base, imports)) reportAt(`Recipe ${node.id?.name ?? "AnonymousRecipe"}: extends the recipe ${base.name}; a recipe must extend SmrtRecipe directly`, node);
+	}
+	for (const found of findClassExpressions(body)) if (isRecipeBase(found.superClass, imports)) reportAt("Recipe declared as a class expression or inside a block; declare it as a top-level `class X extends SmrtRecipe`", found);
+	for (const node of classes) {
+		if (!isRecipeBase(node.superClass, imports)) continue;
+		const className = node.id?.name ?? "AnonymousRecipe";
+		const report = (message, at) => {
+			const loc = typeof at?.start === "number" ? getLineColumn(input.sourceText, at.start) : void 0;
+			errors.push({
+				message: `Recipe ${className}: ${message}`,
+				filePath: input.filePath,
+				line: loc?.line,
+				column: loc?.column,
+				severity: "error"
+			});
+		};
+		const recipe = {
+			className,
+			filePath: input.filePath,
+			line: lineOf(input.sourceText, node),
+			id: null,
+			label: null,
+			summary: null,
+			synonyms: [],
+			models: [],
+			nav: [],
+			requires: [],
+			options: [],
+			help: null
+		};
+		const seen = /* @__PURE__ */ new Set();
+		for (const member of node.body.body) {
+			if (member.type !== "PropertyDefinition" || member.static !== true) continue;
+			const name = keyName(member);
+			if (!name || !member.value) continue;
+			const value = member.value;
+			try {
+				switch (name) {
+					case "id":
+						recipe.id = stringValue(value, "static id");
+						break;
+					case "label":
+						recipe.label = stringValue(value, "static label");
+						break;
+					case "summary":
+						recipe.summary = stringValue(value, "static summary");
+						break;
+					case "synonyms":
+						recipe.synonyms = arrayElements(value, "static synonyms").map((entry) => stringValue(entry, "static synonyms entries"));
+						break;
+					case "requires":
+						recipe.requires = arrayElements(value, "static requires").map((entry) => stringValue(entry, "static requires entries"));
+						break;
+					case "models":
+						recipe.models = arrayElements(value, "static models").map((entry) => modelRef(entry, imports, declaredHere, "static models entry", input.sourceText));
+						break;
+					case "nav":
+						recipe.nav = arrayElements(value, "static nav").map((entry) => {
+							const fields = objectEntries(entry, "static nav entries");
+							const label = fields.find((field) => field.key === "label");
+							const model = fields.find((field) => field.key === "model");
+							const extra = fields.find((field) => field.key !== "label" && field.key !== "model");
+							if (extra) throw new RecipeReadError(`static nav entries accept only \`label\` and \`model\`, not \`${extra.key}\``, extra.node);
+							if (!label || !model) throw new RecipeReadError("static nav entries need both `label` and `model`", entry);
+							return {
+								label: stringValue(label.value, "static nav label"),
+								model: modelRef(model.value, imports, declaredHere, "static nav model", input.sourceText),
+								line: lineOf(input.sourceText, entry)
+							};
+						});
+						break;
+					case "options":
+						recipe.options = objectEntries(value, "static options").map((entry) => ({
+							key: entry.key,
+							value: literalValue(entry.value, "static options"),
+							line: lineOf(input.sourceText, entry.node)
+						}));
+						break;
+					case "help":
+						recipe.help = {
+							path: stringValue(value, "static help"),
+							line: lineOf(input.sourceText, member)
+						};
+						break;
+					default: continue;
+				}
+				seen.add(name);
+			} catch (error) {
+				if (!(error instanceof RecipeReadError)) throw error;
+				report(error.message, error.node ?? member);
+			}
+		}
+		for (const required of [
+			"id",
+			"label",
+			"summary",
+			"models"
+		]) if (!seen.has(required)) report(`must declare a readable \`static ${required}\``, node.id);
+		recipes.push(recipe);
+	}
+	return {
+		recipes,
+		errors
+	};
+}
+var HELP_EXTENSION = ".md";
+var FIELD_REF_PATTERN = /\{field:([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)?)\}/g;
+function deriveHelpFieldRefs(markdown) {
+	const refs = /* @__PURE__ */ new Set();
+	for (const block of markdown.replace(/\r\n?/g, "\n").split(/\n\s*\n/)) for (const match of block.replace(/`[^`]+`/g, "").matchAll(FIELD_REF_PATTERN)) refs.add(match[1]);
+	return [...refs].sort();
+}
+function readHelp(help, raw) {
+	const fail = (message) => {
+		throw new RecipeReadError(`static help ${message}`);
+	};
+	if (help.path.trim() === "" || isAbsolute(help.path) || help.path.split(/[\\/]/).includes("..") || !help.path.toLowerCase().endsWith(HELP_EXTENSION)) return fail(`must be a relative path to a ${HELP_EXTENSION} file beside the recipe (got \`${help.path}\`)`);
+	const absolute = resolve(dirname(raw.filePath), help.path);
+	let markdown;
+	try {
+		markdown = readFileSync(absolute, "utf-8");
+	} catch (error) {
+		return fail(`file \`${help.path}\` cannot be read (${error instanceof Error ? error.message : String(error)})`);
+	}
+	markdown = markdown.replace(/\r\n?/g, "\n");
+	if (markdown.trim() === "") return fail(`file \`${help.path}\` is empty`);
+	return {
+		markdown,
+		fieldRefs: deriveHelpFieldRefs(markdown)
+	};
+}
+function findClassExpressions(body) {
+	const found = [];
+	const topLevel = /* @__PURE__ */ new Set();
+	for (const statement of body) {
+		const node = (statement.type === "ExportNamedDeclaration" || statement.type === "ExportDefaultDeclaration") && statement.declaration ? statement.declaration : statement;
+		if (node.type === "ClassDeclaration") topLevel.add(node);
+	}
+	const visit = (value, depth) => {
+		if (depth > 200 || !value || typeof value !== "object") return;
+		if (Array.isArray(value)) {
+			for (const entry of value) visit(entry, depth + 1);
+			return;
+		}
+		const node = value;
+		if ((node.type === "ClassExpression" || node.type === "ClassDeclaration") && !topLevel.has(node)) found.push(node);
+		for (const [key, child] of Object.entries(node)) {
+			if (key === "loc" || key === "range") continue;
+			visit(child, depth + 1);
+		}
+	};
+	visit(body, 0);
+	return found;
+}
+function stripExtension(path) {
+	return path.replace(/\.(?:[cm]?[jt]sx?|svelte)$/, "");
+}
+function isRelativeSpecifier(source) {
+	return source.startsWith("./") || source.startsWith("../");
+}
+function isExternalPackageSpecifier(source) {
+	if (isRelativeSpecifier(source) || source.startsWith("/")) return false;
+	if (/^[$~#]/.test(source) || source.startsWith("@/")) return false;
+	return true;
+}
+function resolveModel(ref, recipe, classes, what) {
+	const byName = classes.filter((candidate) => candidate.className === ref.imported);
+	let candidates = byName;
+	if (ref.source === null) candidates = byName.filter((c) => c.filePath === recipe.filePath);
+	else if (isExternalPackageSpecifier(ref.source)) throw new RecipeReadError(`${what} \`${ref.local}\` is imported from \`${ref.source}\`, another package; a recipe's models must belong to its own package`);
+	else if (isRelativeSpecifier(ref.source)) {
+		const target = stripExtension(resolve(dirname(recipe.filePath), ref.source));
+		const byFile = byName.filter((c) => {
+			const file = stripExtension(c.filePath);
+			return file === target || file === `${target}/index`;
+		});
+		candidates = byFile.length > 0 ? byFile : byName;
+	}
+	if (candidates.length === 0) throw new RecipeReadError(`${what} \`${ref.local}\` does not resolve to a model class scanned in this package`);
+	if (candidates.length > 1) throw new RecipeReadError(`${what} \`${ref.local}\` is ambiguous: ${candidates.length} scanned classes are named \`${ref.imported}\``);
+	return candidates[0];
+}
+var CRUD_VERBS = [
+	"list",
+	"get",
+	"create",
+	"update",
+	"delete"
+];
+function isNarrowing(value, operations) {
+	if (value === false) return true;
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const keys = Object.keys(value);
+	const exclude = value.exclude;
+	return keys.length === 1 && keys[0] === "exclude" && Array.isArray(exclude) && exclude.length > 0 && exclude.every((entry) => typeof entry === "string" && operations.has(entry));
+}
+function isPlainObject(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function readModelOptions(raw, model, classes, where, bad) {
+	if (!isPlainObject(raw)) {
+		bad(`${where} must be an object`);
+		return;
+	}
+	let ok = true;
+	const fail = (message) => {
+		ok = false;
+		bad(message);
+	};
+	const out = {};
+	const operations = new Set(CRUD_VERBS);
+	const chain = /* @__PURE__ */ new Set([model.className, ...model.inheritanceChain]);
+	for (const candidate of classes) {
+		if (!chain.has(candidate.className)) continue;
+		for (const method of candidate.methods) if (!method.isStatic && method.accessibility === "public" && method.name !== "constructor") operations.add(method.name);
+	}
+	for (const [key, value] of Object.entries(raw)) if (key === "fields") {
+		if (!isPlainObject(value)) {
+			fail(`${where}.fields must be an object`);
+			continue;
+		}
+		const fields = {};
+		for (const [field, hints] of Object.entries(value)) {
+			if (!isPlainObject(hints)) {
+				fail(`${where}.fields.${field} must be an object`);
+				continue;
+			}
+			const entry = {};
+			for (const [hint, hintValue] of Object.entries(hints)) {
+				const at = `${where}.fields.${field}.${hint}`;
+				if (!FIELD_OPTION_KEYS.has(hint)) fail(`${at} is not a field option; use default, label, help, order, visibility, or locked`);
+				else if ((hint === "label" || hint === "help") && typeof hintValue !== "string") fail(`${at} must be a string`);
+				else if (hint === "order" && (typeof hintValue !== "number" || !Number.isFinite(hintValue))) fail(`${at} must be a finite number`);
+				else if (hint === "locked" && typeof hintValue !== "boolean") fail(`${at} must be a boolean`);
+				else if (hint === "visibility" && !(typeof hintValue === "string" && VISIBILITIES.has(hintValue))) fail(`${at} must be one of basic, advanced, hidden`);
+				else entry[hint] = hintValue;
+			}
+			fields[field] = entry;
+		}
+		out.fields = fields;
+	} else if (key === "exposure") {
+		if (!isPlainObject(value)) {
+			fail(`${where}.exposure must be an object`);
+			continue;
+		}
+		const exposure = {};
+		for (const [transport, narrowing] of Object.entries(value)) if (!EXPOSURE_TRANSPORTS.includes(transport)) fail(`${where}.exposure.${transport} is not a transport; use api, mcp, or cli`);
+		else if (!isNarrowing(narrowing, operations)) fail(`${where}.exposure.${transport} may only be \`false\` or a non-empty \`{ exclude: [...] }\` naming ${[...CRUD_VERBS].join("/")} or a method of \`${model.className}\`: options narrow exposure and never widen it, so \`true\` and \`include\` are rejected`);
+		else exposure[transport] = narrowing;
+		out.exposure = exposure;
+	} else fail(`${where}.${key} is not a model option; use \`fields\` or \`exposure\``);
+	return ok ? out : void 0;
+}
+function resolveRecipes(raws, classes) {
+	const errors = [];
+	const recipes = [];
+	const ids = /* @__PURE__ */ new Map();
+	for (const raw of raws) {
+		const report = (message, line) => errors.push({
+			message: `Recipe ${raw.className}: ${message}`,
+			filePath: raw.filePath,
+			line: line ?? raw.line,
+			severity: "error"
+		});
+		const attempt = (work, line) => {
+			try {
+				return work();
+			} catch (error) {
+				if (!(error instanceof RecipeReadError)) throw error;
+				report(error.message, line);
+				return;
+			}
+		};
+		if (raw.id === null || raw.label === null || raw.summary === null) continue;
+		const id = raw.id;
+		if (id.length > RECIPE_ID_MAX_LENGTH || !RECIPE_ID_PATTERN.test(id)) report(`id \`${id}\` must be dotted lowercase segments such as \`commerce.sales\``);
+		const first = ids.get(id);
+		if (first) report(`id \`${id}\` is already declared by ${first.className} (${first.filePath})`);
+		else ids.set(id, raw);
+		if (raw.label.trim() === "") report("label must not be empty");
+		if (raw.models.length === 0) report("models must list at least one model");
+		const byLocal = /* @__PURE__ */ new Map();
+		const models = [];
+		for (const ref of raw.models) {
+			const model = attempt(() => resolveModel(ref, raw, classes, "static models entry"), ref.line);
+			if (!model) continue;
+			if (models.includes(model)) {
+				report(`models lists \`${model.className}\` more than once`, ref.line);
+				continue;
+			}
+			models.push(model);
+			byLocal.set(ref.local, model);
+			byLocal.set(model.className, model);
+		}
+		const nav = [];
+		for (const entry of raw.nav) {
+			const model = attempt(() => resolveModel(entry.model, raw, classes, "static nav model"), entry.line);
+			if (!model) continue;
+			if (!models.includes(model)) {
+				report(`nav entry \`${entry.label}\` points at \`${model.className}\`, which is not listed in models`, entry.line);
+				continue;
+			}
+			nav.push({
+				label: entry.label,
+				model: model.className
+			});
+		}
+		const requires = [];
+		for (const required of raw.requires) if (required.length > RECIPE_ID_MAX_LENGTH || !RECIPE_ID_PATTERN.test(required)) report(`requires \`${required}\` is not a recipe id`);
+		else if (required === id) report("a recipe cannot require itself");
+		else if (requires.includes(required)) report(`requires lists \`${required}\` more than once`);
+		else requires.push(required);
+		let options;
+		for (const entry of raw.options) {
+			const model = byLocal.get(entry.key);
+			if (!model) {
+				report(`options.${entry.key} does not name one of the recipe's models`, entry.line);
+				continue;
+			}
+			const read = readModelOptions(entry.value, model, classes, `options.${entry.key}`, (message) => report(message, entry.line));
+			if (read) {
+				options ??= {};
+				if (options[model.className]) report(`options names \`${model.className}\` more than once`, entry.line);
+				else options[model.className] = read;
+			}
+		}
+		const help = raw.help ? attempt(() => readHelp(raw.help, raw), raw.help.line) : void 0;
+		recipes.push({
+			id,
+			className: raw.className,
+			label: raw.label,
+			summary: raw.summary,
+			synonyms: raw.synonyms,
+			models: models.map((model) => model.className),
+			nav,
+			requires,
+			...options && Object.keys(options).length > 0 ? { options } : {},
+			...help ? { help } : {}
+		});
+	}
+	const byId = new Map(recipes.map((recipe) => [recipe.id, recipe]));
+	const reported = /* @__PURE__ */ new Set();
+	const visit = (recipe, trail) => {
+		if (trail.includes(recipe.id)) {
+			const cycle = [...trail.slice(trail.indexOf(recipe.id)), recipe.id];
+			const key = [...cycle].sort().join("|");
+			if (!reported.has(key)) {
+				reported.add(key);
+				const raw = ids.get(recipe.id);
+				errors.push({
+					message: `Recipe ${recipe.className}: requires cycle ${cycle.join(" -> ")}`,
+					filePath: raw?.filePath ?? "",
+					line: raw?.line,
+					severity: "error"
+				});
+			}
+			return;
+		}
+		for (const required of recipe.requires) {
+			const next = byId.get(required);
+			if (next) visit(next, [...trail, recipe.id]);
+		}
+	};
+	for (const recipe of recipes) visit(recipe, []);
+	recipes.sort((a, b) => a.id.localeCompare(b.id));
+	return {
+		recipes,
+		errors
+	};
+}
+//#endregion
 //#region src/oxc-parser.ts
 function getLangFromFilename(filename) {
 	if (filename.endsWith(".tsx")) return "tsx";
@@ -1099,6 +1780,7 @@ function parseFile(filePath) {
 	let typeAliases = {};
 	let smrtImports;
 	let agentSurface;
+	let recipes;
 	try {
 		const sourceText = readFileSync(filePath, "utf-8");
 		const result = parseSync(filePath, sourceText, {
@@ -1131,6 +1813,15 @@ function parseFile(filePath) {
 			}
 			reportUnresolvedSpreads(ctx.unresolved, filePath, sourceText, errors);
 			agentSurface = maybeExtractAgentSurface(program, sourceText, filePath);
+			if (sourceMayDeclareRecipe(sourceText)) {
+				const found = extractRecipes({
+					body: program.body,
+					sourceText,
+					filePath
+				});
+				errors.push(...found.errors);
+				if (found.recipes.length > 0) recipes = found.recipes;
+			}
 		}
 	} catch (error) {
 		errors.push({
@@ -1148,6 +1839,7 @@ function parseFile(filePath) {
 	};
 	if (smrtImports && smrtImports.size > 0) result2.smrtImports = smrtImports;
 	if (agentSurface) result2.agentSurface = agentSurface;
+	if (recipes) result2.recipes = recipes;
 	return result2;
 }
 function maybeExtractAgentSurface(program, sourceText, filePath) {
@@ -1178,6 +1870,49 @@ function parseAgentSurfaceFile(filePath) {
 		return;
 	}
 }
+function parseRecipeFile(filePath) {
+	let sourceText;
+	try {
+		sourceText = readFileSync(filePath, "utf-8");
+	} catch (error) {
+		return {
+			recipes: [],
+			errors: [{
+				message: `Cannot read file for recipe discovery: ${error instanceof Error ? error.message : String(error)}`,
+				filePath,
+				severity: "error"
+			}]
+		};
+	}
+	if (!sourceMayDeclareRecipe(sourceText)) return {
+		recipes: [],
+		errors: []
+	};
+	try {
+		const program = parseSync(filePath, sourceText, {
+			lang: getLangFromFilename(filePath),
+			preserveParens: false
+		}).program;
+		if (!program?.body) return {
+			recipes: [],
+			errors: []
+		};
+		return extractRecipes({
+			body: program.body,
+			sourceText,
+			filePath
+		});
+	} catch (error) {
+		return {
+			recipes: [],
+			errors: [{
+				message: error instanceof Error ? error.message : String(error),
+				filePath,
+				severity: "error"
+			}]
+		};
+	}
+}
 function parseSource(sourceText, filename = "test.ts") {
 	const startTime = performance.now();
 	const errors = [];
@@ -1185,6 +1920,7 @@ function parseSource(sourceText, filename = "test.ts") {
 	let typeAliases = {};
 	let smrtImports;
 	let agentSurface;
+	let recipes;
 	try {
 		const result = parseSync(filename, sourceText, {
 			lang: getLangFromFilename(filename),
@@ -1216,6 +1952,15 @@ function parseSource(sourceText, filename = "test.ts") {
 			}
 			reportUnresolvedSpreads(ctx.unresolved, filename, sourceText, errors);
 			agentSurface = maybeExtractAgentSurface(program, sourceText, filename);
+			if (sourceMayDeclareRecipe(sourceText)) {
+				const found = extractRecipes({
+					body: program.body,
+					sourceText,
+					filePath: filename
+				});
+				errors.push(...found.errors);
+				if (found.recipes.length > 0) recipes = found.recipes;
+			}
 		}
 	} catch (error) {
 		errors.push({
@@ -1233,6 +1978,7 @@ function parseSource(sourceText, filename = "test.ts") {
 	};
 	if (smrtImports && smrtImports.size > 0) result2.smrtImports = smrtImports;
 	if (agentSurface) result2.agentSurface = agentSurface;
+	if (recipes) result2.recipes = recipes;
 	return result2;
 }
 var FORBIDDEN_OBJECT_KEYS = /* @__PURE__ */ new Set([
@@ -1301,22 +2047,39 @@ function extractTypeAliases(body) {
 			const name = enumDecl.id?.name;
 			const members = enumDecl.body?.members ?? enumDecl.members;
 			if (name && isSafeObjectKey(name) && members && members.length > 0) {
-				const values = members.map((m) => {
-					if (m.initializer?.type === "Literal") {
-						const val = m.initializer.value;
-						if (typeof val === "string") return `'${val}'`;
-						if (typeof val === "number") return String(val);
-					}
-					return null;
-				}).filter((v) => v !== null);
-				if (values.length > 0) {
-					if (values.every((v) => v.startsWith("'"))) aliases[name] = values.join(" | ");
-				}
+				const union = enumMembersToUnion(members);
+				if (union) aliases[name] = union;
 			}
 		}
 	}
 	return aliases;
 }
+function enumMembersToUnion(members) {
+	const values = [];
+	let next = 0;
+	for (const member of members) {
+		const init = member.initializer;
+		if (!init) {
+			values.push(next);
+			next += 1;
+		} else if (init.type === "Literal" && typeof init.value === "string") values.push(init.value);
+		else if (init.type === "Literal" && typeof init.value === "number") {
+			values.push(init.value);
+			next = init.value + 1;
+		} else if (init.type === "UnaryExpression" && init.operator === "-" && init.argument?.type === "Literal" && typeof init.argument.value === "number") {
+			values.push(-init.argument.value);
+			next = -init.argument.value + 1;
+		} else if (init.type === "TemplateLiteral" && init.expressions?.length === 0 && typeof init.quasis?.[0]?.value?.cooked === "string") values.push(init.quasis[0].value.cooked);
+		else return null;
+	}
+	const allStrings = values.every((v) => typeof v === "string");
+	const allNumbers = values.every((v) => typeof v === "number");
+	if (!allStrings && !allNumbers) return null;
+	return values.map((v) => {
+		if (typeof v !== "string") return String(v);
+		return `'${JSON.stringify(v).slice(1, -1).replaceAll("'", "\\'")}'`;
+	}).join(" | ");
+}
 function unwrapTypeAssertion(node) {
 	let current = node;
 	for (let depth = 0; current && depth < 8; depth++) {
@@ -2170,15 +2933,38 @@ var ManifestAdapter = class ManifestAdapter {
 			const manifestKey = definition.qualifiedName || definition.name.toLowerCase();
 			objects[manifestKey] = definition;
 		}
+		const recipes = this.qualifyRecipes(options.recipes ?? [], options.packageName);
+		const selectorEntries = Object.entries(options.uiSelectors ?? {}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+		const selectors = selectorEntries.length > 0 ? Object.fromEntries(selectorEntries.map(([id, decl]) => [id, {
+			slotId: decl.slotId,
+			selects: decl.selects,
+			...decl.label !== void 0 ? { label: decl.label } : {},
+			...decl.description !== void 0 ? { description: decl.description } : {}
+		}])) : void 0;
 		return {
 			version: "1.0.0",
 			timestamp: MANIFEST_TIMESTAMP,
 			packageName: options.packageName,
 			packageVersion: options.packageVersion,
 			objects,
-			moduleType: "smrt"
+			moduleType: "smrt",
+			...recipes.length > 0 ? { recipes } : {},
+			...selectors ? { uiSelectors: selectors } : {}
 		};
 	}
+	/** Qualify recipe model names (`@scope/pkg:Class`) once the package is known. */
+	qualifyRecipes(recipes, packageName) {
+		const qualify = (className) => packageName ? createQualifiedName(packageName, className) : className;
+		return recipes.map((recipe) => ({
+			...recipe,
+			models: recipe.models.map(qualify),
+			nav: recipe.nav.map((entry) => ({
+				label: entry.label,
+				model: qualify(entry.model)
+			})),
+			...recipe.options ? { options: Object.fromEntries(Object.entries(recipe.options).map(([model, value]) => [qualify(model), value])) } : {}
+		}));
+	}
 	/**
 	* Convert a single resolved class definition to a `SmartObjectDefinition`.
 	*
@@ -2329,6 +3115,8 @@ var ManifestAdapter = class ManifestAdapter {
 			...definition._meta,
 			underlyingType: inference.underlyingType
 		};
+		const enumValues = this.resolveFieldEnum(field, definition.type);
+		if (enumValues) definition.enum = enumValues;
 		if (isFunctionType) definition.transient = true;
 		if (fieldDecoratorOptions.transient === true) definition.transient = true;
 		if (fieldDecoratorOptions.sensitive === true) definition.sensitive = true;
@@ -2725,6 +3513,19 @@ var ManifestAdapter = class ManifestAdapter {
 				this._aliasDepth = (this._aliasDepth ?? 0) - 1;
 			}
 		}
+		const closedSet = type ? resolveEnumValues(type, this.typeAliases) : void 0;
+		if (closedSet?.every((v) => typeof v === "string")) return {
+			type: "text",
+			required: isRequired,
+			defaultValue: this.parseDefaultValue(field.initializer, "string"),
+			source: "annotation"
+		};
+		if (closedSet?.every((v) => typeof v === "number")) return {
+			type: closedSet.every(Number.isInteger) ? "integer" : "decimal",
+			required: isRequired,
+			defaultValue: field.numericValue ?? void 0,
+			source: "annotation"
+		};
 		if (field.initializer?.match(/^(['"]).*\1$/)) return {
 			type: "text",
 			required: isRequired,
@@ -2738,6 +3539,18 @@ var ManifestAdapter = class ManifestAdapter {
 		};
 	}
 	/**
+	* Allowed values of a field whose declared type is a closed literal set.
+	* Only emitted when the final column type agrees with the value kind, so a
+	* `@field({ type })` override can never contradict its own `enum`.
+	*/
+	resolveFieldEnum(field, fieldType) {
+		if (!field.typeAnnotation) return void 0;
+		const values = resolveEnumValues(field.typeAnnotation, this.typeAliases);
+		if (!values) return void 0;
+		if (fieldType === "text") return values.every((v) => typeof v === "string") ? values : void 0;
+		if (fieldType === "integer" || fieldType === "decimal") return values.every((v) => typeof v === "number") ? values : void 0;
+	}
+	/**
 	* Parse default value from initializer string
 	*/
 	parseDefaultValue(initializer, expectedType) {
@@ -2810,8 +3623,119 @@ var ManifestAdapter = class ManifestAdapter {
 	}
 };
 //#endregion
+//#region src/ui-selectors.ts
+var QUALIFIED_NAME = /^@[^/\s:]+\/[^/\s:]+:[A-Za-z_$][\w$]*$/;
+function ordinal(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+function langOf(filePath) {
+	if (filePath.endsWith(".tsx")) return "tsx";
+	if (filePath.endsWith(".ts")) return "ts";
+	if (filePath.endsWith(".jsx")) return "jsx";
+	return "js";
+}
+function collect(value, fallbackId, filePath, out, errors, seen) {
+	if (!value || typeof value !== "object" || seen.has(value)) return;
+	seen.add(value);
+	if (Array.isArray(value)) {
+		for (const entry of value) collect(entry, void 0, filePath, out, errors, seen);
+		return;
+	}
+	const record = value;
+	if (Object.hasOwn(record, "selects")) {
+		const slotId = typeof record.id === "string" && record.id !== "" ? record.id : fallbackId;
+		if (typeof record.selects !== "string" || !QUALIFIED_NAME.test(record.selects)) errors.push({
+			message: `UI slot "${slotId ?? "?"}" declares selects ${JSON.stringify(record.selects)}; it must be a string literal qualified model name ("@scope/package:ClassName").`,
+			filePath,
+			severity: "error"
+		});
+		else if (!slotId) errors.push({
+			message: `A UI slot selecting ${record.selects} has no string \`id\`.`,
+			filePath,
+			severity: "error"
+		});
+		else out.push({
+			slotId,
+			selects: record.selects,
+			...typeof record.label === "string" ? { label: record.label } : {},
+			...typeof record.description === "string" ? { description: record.description } : {},
+			filePath
+		});
+	}
+	for (const [key, child] of Object.entries(record)) {
+		if (key === "selects") continue;
+		collect(child, key, filePath, out, errors, seen);
+	}
+}
+function parseUiSelectorsFile(filePath) {
+	const empty = {
+		selectors: [],
+		errors: []
+	};
+	let sourceText;
+	try {
+		sourceText = readFileSync(filePath, "utf-8");
+	} catch {
+		return empty;
+	}
+	if (!sourceText.includes("selects")) return empty;
+	try {
+		const program = parseSync(filePath, sourceText, {
+			lang: langOf(filePath),
+			preserveParens: false
+		}).program;
+		if (!program?.body) return empty;
+		const constants = extractModuleObjectConstants(program.body, sourceText);
+		const selectors = [];
+		const errors = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const [name, constant] of constants) collect(constant.value, name, filePath, selectors, errors, seen);
+		return {
+			selectors,
+			errors
+		};
+	} catch {
+		return empty;
+	}
+}
+function mergeUiSelectors(files, relativize = (p) => p) {
+	const errors = files.flatMap((file) => file.errors);
+	const all = files.flatMap((file) => file.selectors).sort((a, b) => ordinal(a.slotId, b.slotId) || ordinal(a.filePath, b.filePath));
+	const selectors = {};
+	const byModel = /* @__PURE__ */ new Map();
+	for (const decl of all) {
+		if (selectors[decl.slotId]) {
+			errors.push({
+				message: `UI slot id "${decl.slotId}" is declared more than once.`,
+				filePath: decl.filePath,
+				severity: "error"
+			});
+			continue;
+		}
+		const other = byModel.get(decl.selects);
+		if (other) {
+			errors.push({
+				message: `UI slots "${other}" and "${decl.slotId}" both select ${decl.selects}; a model has one selector.`,
+				filePath: decl.filePath,
+				severity: "error"
+			});
+			continue;
+		}
+		byModel.set(decl.selects, decl.slotId);
+		selectors[decl.slotId] = {
+			...decl,
+			filePath: relativize(decl.filePath)
+		};
+	}
+	return {
+		selectors,
+		errors
+	};
+}
+//#endregion
 //#region src/scanner.ts
 var DEFAULT_INCLUDE = ["**/*.ts", "**/*.tsx"];
+var DEFAULT_UI_SELECTOR_INCLUDE = ["src/**/ui.ts"];
 var DEFAULT_SVELTE_INCLUDE = ["**/*.svelte"];
 var DEFAULT_AGENT_SURFACE_INCLUDE = [
 	"**/*.ts",
@@ -2839,6 +3763,8 @@ var OxcScanner = class {
 	options;
 	resolver;
 	scanResults = null;
+	recipeErrors = [];
+	outsideRecipes = [];
 	/**
 	* Create a new `OxcScanner` with the given options.
 	*
@@ -2862,7 +3788,8 @@ var OxcScanner = class {
 			followSymbolicLinks: options.followSymbolicLinks ?? false,
 			agentSurface: options.agentSurface ?? true,
 			svelteInclude: options.svelteInclude || DEFAULT_SVELTE_INCLUDE,
-			agentSurfaceInclude: options.agentSurfaceInclude || DEFAULT_AGENT_SURFACE_INCLUDE
+			agentSurfaceInclude: options.agentSurfaceInclude || DEFAULT_AGENT_SURFACE_INCLUDE,
+			uiSelectorInclude: options.uiSelectorInclude || DEFAULT_UI_SELECTOR_INCLUDE
 		};
 		this.resolver = new InheritanceResolver({
 			baseClasses: this.options.baseClasses,
@@ -2899,7 +3826,8 @@ var OxcScanner = class {
 			totalParseTimeMs: performance.now() - startTime,
 			fileCount: files.length,
 			typeAliases: {},
-			agentSurface: emptyAgentSurface()
+			agentSurface: emptyAgentSurface(),
+			recipes: []
 		};
 		const surfaces = [];
 		for (const file of fileResults) {
@@ -2913,6 +3841,14 @@ var OxcScanner = class {
 			surfaces.push(await this.scanSvelteDeclarations());
 			results.agentSurface = mergeAgentSurfaces(surfaces, (filePath) => this.relativizeSourcePath(filePath));
 		}
+		const outside = await this.scanRecipesOutsideClassGlob(new Set(files));
+		this.outsideRecipes = outside.recipes;
+		results.errors.push(...outside.errors);
+		const uiSelectors = await this.scanUiSelectors();
+		if (uiSelectors) {
+			results.uiSelectors = uiSelectors.selectors;
+			results.errors.push(...uiSelectors.errors);
+		}
 		this.resolver.addClasses(results.classes);
 		this.scanResults = results;
 		return results;
@@ -2934,7 +3870,13 @@ var OxcScanner = class {
 	*/
 	resolve() {
 		if (!this.scanResults) throw new Error("Must call scan() before resolve()");
-		return this.resolver.resolveAll();
+		const resolved = this.resolver.resolveAll();
+		const { recipes, errors } = resolveRecipes([...this.scanResults.files.flatMap((file) => file.recipes ?? []), ...this.outsideRecipes], resolved);
+		this.scanResults.recipes = recipes;
+		this.scanResults.errors = this.scanResults.errors.filter((error) => !this.recipeErrors.includes(error));
+		this.recipeErrors = errors;
+		this.scanResults.errors.push(...errors);
+		return resolved;
 	}
 	/**
 	* Run both scan phases in a single call.
@@ -3092,6 +4034,59 @@ var OxcScanner = class {
 		return surfaces;
 	}
 	/**
+	* Find `SmrtRecipe` declarations in files the CLASS scan did not cover.
+	*
+	* Same rule as {@link scanDeclarationsOutsideClassGlob}: the model glob is
+	* narrowed to where models live, a recipe need not live there, and a recipe
+	* that vanished with no diagnostic is the failure to prevent.
+	*/
+	async scanRecipesOutsideClassGlob(alreadyScanned) {
+		const out = {
+			recipes: [],
+			errors: []
+		};
+		if (this.options.agentSurfaceInclude.length === 0) return out;
+		let files;
+		try {
+			files = await discoverSourceFiles({
+				cwd: this.options.cwd,
+				include: this.options.agentSurfaceInclude,
+				exclude: [...this.options.exclude, ...AGENT_SURFACE_PRUNE],
+				followSymbolicLinks: this.options.followSymbolicLinks
+			});
+		} catch {
+			return out;
+		}
+		for (const filePath of files) {
+			if (alreadyScanned.has(filePath)) continue;
+			if (!isAgentSurfaceSourcePath(filePath, this.options.cwd)) continue;
+			const found = parseRecipeFile(filePath);
+			out.recipes.push(...found.recipes);
+			out.errors.push(...found.errors);
+		}
+		return out;
+	}
+	/**
+	* Read selector-slot declarations (`selects`, #3599) from the package's
+	* `ui.ts` files, independently of the class-scan glob.
+	*/
+	async scanUiSelectors() {
+		if (this.options.uiSelectorInclude.length === 0) return void 0;
+		let files;
+		try {
+			files = await discoverSourceFiles({
+				cwd: this.options.cwd,
+				include: this.options.uiSelectorInclude,
+				exclude: [...this.options.exclude, ...AGENT_SURFACE_PRUNE],
+				followSymbolicLinks: this.options.followSymbolicLinks
+			});
+		} catch {
+			return;
+		}
+		const merged = mergeUiSelectors(files.sort().map((file) => parseUiSelectorsFile(file)), (filePath) => this.relativizeSourcePath(filePath));
+		return Object.keys(merged.selectors).length > 0 || merged.errors.length > 0 ? merged : void 0;
+	}
+	/**
 	* Search `.svelte` files for declarations the scanner can never read.
 	*
 	* A `.svelte` file is not a TypeScript program and is never parsed here, so
@@ -3141,6 +4136,6 @@ var OxcScanner = class {
 	}
 };
 //#endregion
-export { scanSvelteAgentSurface as _, parseFile as a, discoverSourceFiles as c, checkAgentSurfaceToolNames as d, emptyAgentSurface as f, mergeAgentSurfaces as g, isPrunedAgentSurfacePath as h, parseAgentSurfaceFile as i, normalizeGlobSeparators as l, isAgentSurfaceSourcePath as m, ManifestAdapter as n, parseSource as o, extractAgentSurface as p, extractSmrtImports as r, InheritanceResolver as s, OxcScanner as t, relativeGlobToCwd as u, sourceMayDeclareAgentSurface as v };
+export { mergeAgentSurfaces as C, isPrunedAgentSurfacePath as S, sourceMayDeclareAgentSurface as T, relativeGlobToCwd as _, parseAgentSurfaceFile as a, extractAgentSurface as b, parseSource as c, resolveRecipes as d, sourceMayDeclareRecipe as f, normalizeGlobSeparators as g, discoverSourceFiles as h, extractSmrtImports as i, deriveHelpFieldRefs as l, resolveEnumValues as m, parseUiSelectorsFile as n, parseFile as o, InheritanceResolver as p, ManifestAdapter as r, parseRecipeFile as s, OxcScanner as t, extractRecipes as u, checkAgentSurfaceToolNames as v, scanSvelteAgentSurface as w, isAgentSurfaceSourcePath as x, emptyAgentSurface as y };
 
-//# sourceMappingURL=scanner-ItT4WTxN.js.map
+//# sourceMappingURL=scanner-CeTWAIar.js.map