@happyvertical/smrt-scanner 0.43.10 → 0.44.0

package/dist/chunks/{scanner-CW9g-vyS.js → scanner-C3VqXyzB.js}

@@ -1,7 +1,681 @@
-import { isAbsolute, resolve, sep, win32 } from "node:path";
-import fg from "fast-glob";
 import { readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep, win32 } from "node:path";
+import fg from "fast-glob";
 import { parseSync } from "oxc-parser";
+//#region src/source-location.ts
+function getLineColumn(sourceText, offset) {
+	if (offset < 0 || offset > sourceText.length) return;
+	let line = 1;
+	let lastNewlinePos = -1;
+	for (let i = 0; i < offset; i++) if (sourceText[i] === "\n") {
+		line++;
+		lastNewlinePos = i;
+	}
+	return {
+		line,
+		column: offset - lastNewlinePos
+	};
+}
+//#endregion
+//#region src/agent-surface.ts
+var HELPER_SPECIFIERS = {
+	defineIntent: "@happyvertical/smrt-web/intents",
+	definePlaybook: "@happyvertical/smrt-playbooks"
+};
+var HELPER_NAMES = Object.keys(HELPER_SPECIFIERS);
+var ESCAPE_HATCH = "A declaration the scanner cannot read without evaluating it is not emittable — use `useWebMcpTool` for a tool set derived from computed or fetched data.";
+var MAX_LITERAL_DEPTH = 32;
+var INTENT_ID_PATTERN = /^[a-z][a-z0-9]*(?:\.[a-z0-9][a-z0-9_]*)+$/;
+var INTENT_ID_MAX_LENGTH = 128;
+var DESCRIPTION_MAX_LENGTH = 1024;
+var RESERVED_TOOL_NAME_PREFIX = "smrt_ui_";
+var INTENT_DECLARATION_KEYS = /* @__PURE__ */ new Set([
+	"id",
+	"description",
+	"inputSchema",
+	"capability",
+	"target"
+]);
+var CONTROL_TARGET_KEYS = /* @__PURE__ */ new Set([
+	"registry",
+	"action",
+	"formId",
+	"controlId"
+]);
+var DATA_SURFACE_TARGET_KEYS = /* @__PURE__ */ new Set([
+	"registry",
+	"controlId",
+	"surfaceId",
+	"kind"
+]);
+var CONTROL_ACTIONS = /* @__PURE__ */ new Set([
+	"focus",
+	"reveal",
+	"highlight",
+	"explain",
+	"validate",
+	"stage",
+	"apply",
+	"discard",
+	"clear",
+	"undo"
+]);
+var DATA_SURFACE_KINDS = /* @__PURE__ */ new Set([
+	"table",
+	"list",
+	"report",
+	"custom"
+]);
+var PLAYBOOK_PLANES = /* @__PURE__ */ new Set(["browser", "server"]);
+var FAILURE_POLICIES = /* @__PURE__ */ new Set(["abort", "continue"]);
+var QUALIFIED_MODEL_PATTERN = /^\S+:\S+$/;
+function intentToolName(id) {
+	return id.replace(/[.-]/g, "_");
+}
+var EXCLUDED_DIRECTORIES = /* @__PURE__ */ new Set([
+	"node_modules",
+	"dist",
+	"build",
+	"coverage",
+	"__tests__",
+	"__typechecks__"
+]);
+function isAgentSurfaceSourcePath(filePath, rootDir) {
+	if (!/\.(?:ts|tsx|js|jsx)$/.test(filePath)) return false;
+	if (filePath.endsWith(".d.ts")) return false;
+	if (/\.(?:test|spec)\.(?:ts|tsx|js|jsx)$/.test(filePath)) return false;
+	return !isPrunedAgentSurfacePath(filePath, rootDir);
+}
+function isPrunedAgentSurfacePath(filePath, rootDir) {
+	let scoped = filePath;
+	if (rootDir) {
+		const relativePath = relative(rootDir, filePath);
+		if (relativePath && !relativePath.startsWith("..")) scoped = relativePath;
+	}
+	return scoped.split(/[\\/]/).some((segment) => EXCLUDED_DIRECTORIES.has(segment) || segment.startsWith(".") && segment !== "." && segment !== "..");
+}
+function isNode(value) {
+	return typeof value === "object" && value !== null && typeof value.type === "string";
+}
+function collectHelperBindings(body) {
+	const bindings = /* @__PURE__ */ new Map();
+	const namespaces = /* @__PURE__ */ new Map();
+	for (const node of body) {
+		if (node.type !== "ImportDeclaration") continue;
+		const source = node.source;
+		if (!source || typeof source.value !== "string") continue;
+		const specifier = source.value;
+		const specifiers = node.specifiers ?? [];
+		for (const spec of specifiers) {
+			const local = spec.local?.name;
+			if (!local) continue;
+			if (spec.type === "ImportSpecifier") {
+				const imported = spec.imported?.name;
+				const helper = HELPER_NAMES.find((name) => name === imported && HELPER_SPECIFIERS[name] === specifier);
+				if (helper) bindings.set(local, helper);
+				continue;
+			}
+			if (spec.type === "ImportNamespaceSpecifier") namespaces.set(local, specifier);
+		}
+	}
+	for (const [local, specifier] of namespaces) for (const helper of HELPER_NAMES) if (HELPER_SPECIFIERS[helper] === specifier) bindings.set(`${local}.${helper}`, helper);
+	return bindings;
+}
+function resolveCallee(callee, bindings) {
+	if (!isNode(callee)) return void 0;
+	if (callee.type === "Identifier") return bindings.get(String(callee.name));
+	if (callee.type === "MemberExpression" && callee.computed !== true) {
+		const object = callee.object;
+		const property = callee.property;
+		if (isNode(object) && object.type === "Identifier" && isNode(property) && property.type === "Identifier") return bindings.get(`${String(object.name)}.${String(property.name)}`);
+	}
+}
+function readLiteral(node, failures, path, depth = 0) {
+	if (!isNode(node)) {
+		failures.push({ reason: `${path} is not a readable expression` });
+		return;
+	}
+	if (depth > MAX_LITERAL_DEPTH) {
+		failures.push({
+			reason: `${path} nests deeper than ${MAX_LITERAL_DEPTH} levels`,
+			start: node.start
+		});
+		return;
+	}
+	switch (node.type) {
+		case "Literal": {
+			const value = node.value;
+			if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number") return value;
+			failures.push({
+				reason: `${path} is not a JSON literal`,
+				start: node.start
+			});
+			return;
+		}
+		case "UnaryExpression": {
+			const argument = node.argument;
+			if (node.operator === "-" && isNode(argument) && argument.type === "Literal" && typeof argument.value === "number") return -argument.value;
+			failures.push({
+				reason: `${path} is a computed unary expression`,
+				start: node.start
+			});
+			return;
+		}
+		case "ArrayExpression": {
+			const elements = node.elements ?? [];
+			const result = [];
+			elements.forEach((element, index) => {
+				if (isNode(element) && element.type === "SpreadElement") {
+					failures.push({
+						reason: `${path}[${index}] is a spread`,
+						start: element.start
+					});
+					return;
+				}
+				if (element === null) {
+					failures.push({ reason: `${path}[${index}] is an array hole` });
+					return;
+				}
+				result.push(readLiteral(element, failures, `${path}[${index}]`, depth + 1));
+			});
+			return result;
+		}
+		case "ObjectExpression": {
+			const properties = node.properties ?? [];
+			const result = {};
+			for (const property of properties) {
+				if (property.type === "SpreadElement") {
+					failures.push({
+						reason: `${path} contains a spread`,
+						start: property.start
+					});
+					continue;
+				}
+				if (property.type !== "Property") {
+					failures.push({
+						reason: `${path} contains an unsupported member`,
+						start: property.start
+					});
+					continue;
+				}
+				if (property.computed === true || property.shorthand === true) {
+					failures.push({
+						reason: `${path} contains a ${property.computed === true ? "computed" : "shorthand"} key`,
+						start: property.start
+					});
+					continue;
+				}
+				const key = readPropertyKey(property.key);
+				if (key === void 0) {
+					failures.push({
+						reason: `${path} contains a non-literal key`,
+						start: property.start
+					});
+					continue;
+				}
+				if (!isSafeKey(key)) {
+					failures.push({
+						reason: `${path}.${key} uses a reserved prototype key`,
+						start: property.start
+					});
+					continue;
+				}
+				result[key] = readLiteral(property.value, failures, `${path}.${key}`, depth + 1);
+			}
+			return result;
+		}
+		case "TSAsExpression":
+		case "TSSatisfiesExpression":
+		case "TSNonNullExpression":
+		case "TSTypeAssertion": return readLiteral(node.expression, failures, path, depth);
+		case "Identifier": {
+			const name = String(node.name);
+			if (name === "undefined") return void 0;
+			failures.push({
+				reason: `${path} references the identifier \`${name}\``,
+				start: node.start
+			});
+			return;
+		}
+		case "TemplateLiteral":
+			failures.push({
+				reason: `${path} is a template literal`,
+				start: node.start
+			});
+			return;
+		case "ConditionalExpression":
+			failures.push({
+				reason: `${path} is a conditional expression`,
+				start: node.start
+			});
+			return;
+		default:
+			failures.push({
+				reason: `${path} is a computed \`${node.type}\``,
+				start: node.start
+			});
+			return;
+	}
+}
+function readPropertyKey(key) {
+	if (!isNode(key)) return void 0;
+	if (key.type === "Identifier") return String(key.name);
+	if (key.type === "Literal" && typeof key.value === "string") return key.value;
+}
+function isSafeKey(key) {
+	return key !== "__proto__" && key !== "constructor" && key !== "prototype";
+}
+function unwrapTypeWrappers(node) {
+	let current = node;
+	while (isNode(current) && (current.type === "TSAsExpression" || current.type === "TSSatisfiesExpression" || current.type === "TSNonNullExpression" || current.type === "TSTypeAssertion")) current = current.expression;
+	return isNode(current) ? current : void 0;
+}
+function collectModuleScopeCalls(body) {
+	const calls = /* @__PURE__ */ new Set();
+	const addInitializer = (value) => {
+		const init = unwrapTypeWrappers(value);
+		if (!init) return;
+		if (init.type === "CallExpression") {
+			calls.add(init);
+			return;
+		}
+		if (init.type === "ArrayExpression") for (const element of init.elements ?? []) {
+			const entry = unwrapTypeWrappers(element);
+			if (entry && entry.type === "CallExpression") calls.add(entry);
+		}
+	};
+	const addDeclaration = (declaration) => {
+		if (!isNode(declaration)) return;
+		if (declaration.type !== "VariableDeclaration") return;
+		for (const declarator of declaration.declarations ?? []) addInitializer(declarator.init);
+	};
+	for (const statement of body) {
+		if (statement.type === "ExpressionStatement") {
+			const expression = unwrapTypeWrappers(statement.expression);
+			if (expression && expression.type === "CallExpression") calls.add(expression);
+			continue;
+		}
+		if (statement.type === "VariableDeclaration") {
+			addDeclaration(statement);
+			continue;
+		}
+		if (statement.type === "ExportNamedDeclaration") {
+			addDeclaration(statement.declaration);
+			continue;
+		}
+		if (statement.type === "ExportDefaultDeclaration") {
+			const declaration = unwrapTypeWrappers(statement.declaration);
+			if (declaration && declaration.type === "CallExpression") calls.add(declaration);
+		}
+	}
+	return calls;
+}
+function collectMatchedCalls(body, bindings) {
+	const moduleScope = collectModuleScopeCalls(body);
+	const matches = [];
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (value) => {
+		if (Array.isArray(value)) {
+			for (const entry of value) visit(entry);
+			return;
+		}
+		if (!isNode(value) || seen.has(value)) return;
+		seen.add(value);
+		if (value.type === "CallExpression") {
+			const helper = resolveCallee(value.callee, bindings);
+			if (helper) matches.push({
+				helper,
+				node: value,
+				moduleScope: moduleScope.has(value)
+			});
+		}
+		for (const key of Object.keys(value)) {
+			if (key === "type" || key === "loc" || key === "range") continue;
+			visit(value[key]);
+		}
+	};
+	visit(body);
+	matches.sort((a, b) => (a.node.start ?? 0) - (b.node.start ?? 0));
+	return matches;
+}
+function resolveCapability(declared) {
+	const value = typeof declared === "object" && declared !== null ? declared : {};
+	const effect = value.effect;
+	return {
+		effect: effect === "read" || effect === "write" || effect === "destructive" ? effect : "destructive",
+		idempotent: value.idempotent === true,
+		openWorld: value.openWorld !== false
+	};
+}
+function readString(value) {
+	return typeof value === "string" && value.trim() !== "" ? value : void 0;
+}
+var IDENTIFIER_MAX_LENGTH = 256;
+function identifierProblem(value, path) {
+	if (typeof value !== "string" || value.length === 0) return `${path} must be a non-empty string`;
+	if (value.length > IDENTIFIER_MAX_LENGTH) return `${path} is longer than ${IDENTIFIER_MAX_LENGTH} characters, which \`defineIntent\` rejects`;
+	for (const character of value) {
+		const code = character.charCodeAt(0);
+		if (code < 32 || code === 127) return `${path} contains a control character, which \`defineIntent\` rejects`;
+	}
+}
+function intentDeclarationProblem(declaration, id, description) {
+	const identity = intentIdentityProblem(id);
+	if (identity) return identity;
+	for (const key of Object.keys(declaration)) if (!INTENT_DECLARATION_KEYS.has(key)) return `view intent '${id}' declares unknown key '${key}'. A declaration is data only \u2014 there is no field for an execute function, a URL, a route, or a fetch, and \`defineIntent\` rejects one.`;
+	if (description.length > DESCRIPTION_MAX_LENGTH) return `view intent '${id}' has a description longer than ${DESCRIPTION_MAX_LENGTH} characters, which \`defineIntent\` rejects.`;
+	if (declaration.inputSchema !== void 0 && !isPlainRecord(declaration.inputSchema)) return `view intent '${id}' has an inputSchema that is not an object literal, which \`defineIntent\` rejects.`;
+	const capability = declaration.capability;
+	if (capability !== void 0) {
+		if (!isPlainRecord(capability)) return `view intent '${id}' has a capability that is not an object literal, which \`defineIntent\` rejects.`;
+		for (const key of Object.keys(capability)) if (key !== "effect" && key !== "idempotent" && key !== "openWorld") return `view intent '${id}' declares unknown capability key '${key}', which \`defineIntent\` rejects.`;
+		if (capability.effect !== void 0 && capability.effect !== "read" && capability.effect !== "write" && capability.effect !== "destructive") return `view intent '${id}' declares capability.effect '${String(capability.effect)}'; \`defineIntent\` accepts only read, write, or destructive.`;
+		for (const flag of ["idempotent", "openWorld"]) if (capability[flag] !== void 0 && typeof capability[flag] !== "boolean") return `view intent '${id}' declares a non-boolean capability.${flag}, which \`defineIntent\` rejects.`;
+	}
+	const target = declaration.target;
+	const registry = target.registry;
+	if (registry !== "control" && registry !== "dataSurface") return `view intent '${id}' targets registry '${String(registry)}'; \`defineIntent\` accepts only 'control' or 'dataSurface'. An intent moves mounted browser state and has no path to REST.`;
+	const allowed = registry === "control" ? CONTROL_TARGET_KEYS : DATA_SURFACE_TARGET_KEYS;
+	for (const key of Object.keys(target)) if (!allowed.has(key)) return `view intent '${id}' declares unknown target key '${key}' for the '${registry}' registry, which \`defineIntent\` rejects.`;
+	if (registry === "control") {
+		if (!CONTROL_ACTIONS.has(String(target.action))) return `view intent '${id}' declares control action '${String(target.action)}', which is not a \`ControlInteractionRegistry\` command.`;
+		for (const key of ["formId", "controlId"]) {
+			if (target[key] === void 0) continue;
+			const problem = identifierProblem(target[key], `target.${key}`);
+			if (problem) return `view intent '${id}': ${problem}.`;
+		}
+		return;
+	}
+	if (!isNonEmptyString(target.controlId)) return `view intent '${id}' targets the dataSurface registry without a \`controlId\`, which \`defineIntent\` requires.`;
+	for (const key of ["controlId", "surfaceId"]) {
+		if (target[key] === void 0) continue;
+		const problem = identifierProblem(target[key], `target.${key}`);
+		if (problem) return `view intent '${id}': ${problem}.`;
+	}
+	if (target.kind !== void 0 && !DATA_SURFACE_KINDS.has(String(target.kind))) return `view intent '${id}' declares data-surface kind '${String(target.kind)}', which \`defineIntent\` rejects.`;
+}
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.length > 0;
+}
+function isPlainRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function playbookDeclarationProblem(declaration, key, steps) {
+	if (steps.length === 0) return `playbook '${key}' declares no steps; \`definePlaybook\` requires at least one.`;
+	const planes = declaration.planes;
+	if (planes !== void 0 && planes !== null) {
+		if (!Array.isArray(planes)) return `playbook '${key}' declares planes that are not an array, which \`definePlaybook\` rejects.`;
+		for (const plane of planes) if (!PLAYBOOK_PLANES.has(String(plane))) return `playbook '${key}' declares unknown plane '${String(plane)}'; expected 'browser' or 'server'.`;
+		if (planes.length === 0) return `playbook '${key}' declares an empty planes list; \`definePlaybook\` requires at least one, and defaulting it here would assert a validity the author never declared.`;
+	}
+	const onStepFailure = declaration.onStepFailure;
+	if (onStepFailure !== void 0 && !FAILURE_POLICIES.has(String(onStepFailure))) return `playbook '${key}' declares onStepFailure '${String(onStepFailure)}'; \`definePlaybook\` accepts only 'abort' or 'continue'.`;
+	const enabled = declaration.enabled;
+	if (enabled !== void 0 && typeof enabled !== "boolean") return `playbook '${key}' declares a non-boolean \`enabled\`, which \`definePlaybook\` rejects rather than coercing \u2014 a truthy '"false"' would otherwise read as enabled.`;
+	for (const step of declaration.steps ?? []) {
+		const record = step;
+		if (record.kind === "operation" && !QUALIFIED_MODEL_PATTERN.test(String(record.model))) return `playbook '${key}' has a step whose model '${String(record.model)}' is not a qualified pair such as '@happyvertical/smrt-commerce:Order'.`;
+	}
+}
+function intentIdentityProblem(id) {
+	if (id.length > INTENT_ID_MAX_LENGTH) return `intent id '${id}' is longer than ${INTENT_ID_MAX_LENGTH} characters, which \`defineIntent\` rejects.`;
+	if (!INTENT_ID_PATTERN.test(id)) return `intent id '${id}' must be lowercase and namespaced with at least one dot, e.g. 'orders.filter_by_status' \u2014 \`defineIntent\` rejects it as written, so emitting it would advertise an operation that can never register.`;
+	if (intentToolName(id).startsWith(RESERVED_TOOL_NAME_PREFIX)) return `intent id '${id}' resolves into the reserved '${RESERVED_TOOL_NAME_PREFIX}' namespace of the six fixed UI tools, which \`defineIntent\` rejects.`;
+}
+function normalizeSteps(value) {
+	if (!Array.isArray(value)) return void 0;
+	const steps = [];
+	for (const entry of value) {
+		if (typeof entry !== "object" || entry === null) return void 0;
+		const step = entry;
+		if (step.kind === "operation") {
+			const model = readString(step.model);
+			const action = readString(step.action);
+			if (!model || !action) return void 0;
+			steps.push({
+				kind: "operation",
+				model,
+				action
+			});
+			continue;
+		}
+		if (step.kind === "intent") {
+			const id = readString(step.id);
+			if (!id) return void 0;
+			steps.push({
+				kind: "intent",
+				id
+			});
+			continue;
+		}
+		return;
+	}
+	return steps;
+}
+function normalizePlanes(value) {
+	if (!Array.isArray(value)) return [];
+	return value.filter((entry) => entry === "browser" || entry === "server").sort();
+}
+function sourceMayDeclareAgentSurface(sourceText) {
+	return HELPER_NAMES.some((helper) => sourceText.includes(helper));
+}
+function extractAgentSurface(options) {
+	const { sourceText, filePath } = options;
+	const body = options.body.filter(isNode);
+	const intents = [];
+	const playbooks = [];
+	const diagnostics = [];
+	const bindings = collectHelperBindings(body);
+	if (bindings.size === 0) return {
+		intents,
+		playbooks,
+		diagnostics
+	};
+	const report = (code, helper, message, start) => {
+		const loc = start === void 0 ? void 0 : getLineColumn(sourceText, start);
+		diagnostics.push({
+			code,
+			helper,
+			message,
+			filePath,
+			line: loc?.line,
+			column: loc?.column
+		});
+	};
+	for (const match of collectMatchedCalls(body, bindings)) {
+		const { helper, node } = match;
+		if (!match.moduleScope) {
+			report("not-module-scope", helper, `\`${helper}()\` must be called at module scope to be emitted into the manifest and knowledge graph. ${ESCAPE_HATCH}`, node.start);
+			continue;
+		}
+		const args = node.arguments ?? [];
+		if (args.length !== 1) {
+			report("argument-count", helper, `\`${helper}()\` takes exactly one object-literal argument; found ${args.length}. ${ESCAPE_HATCH}`, node.start);
+			continue;
+		}
+		const argument = unwrapTypeWrappers(args[0]);
+		if (!argument || argument.type !== "ObjectExpression") {
+			report("non-literal-argument", helper, `\`${helper}()\` must be called with an object literal, not a ${argument?.type ?? "unknown expression"}. ${ESCAPE_HATCH}`, (argument ?? node).start);
+			continue;
+		}
+		const failures = [];
+		const declaration = readLiteral(argument, failures, helper);
+		if (failures.length > 0) {
+			for (const failure of failures) report("non-literal-argument", helper, `${failure.reason}. ${ESCAPE_HATCH}`, failure.start ?? node.start);
+			continue;
+		}
+		if (!declaration) continue;
+		if (helper === "defineIntent") {
+			const id = readString(declaration.id);
+			const description2 = readString(declaration.description);
+			const target = declaration.target;
+			if (!id || !description2 || typeof target !== "object" || target === null || Array.isArray(target)) {
+				report("incomplete-declaration", helper, "a view intent needs a literal `id`, `description`, and `target` to be emitted. A declaration the scanner cannot read without evaluating it is not emittable — use `useWebMcpTool` for a tool set derived from computed or fetched data.", node.start);
+				continue;
+			}
+			const problem = intentDeclarationProblem(declaration, id, description2);
+			if (problem) {
+				report("invalid-identity", helper, problem, node.start);
+				continue;
+			}
+			intents.push({
+				kind: "intent",
+				id,
+				description: description2,
+				capability: resolveCapability(declaration.capability),
+				target,
+				hasInputSchema: typeof declaration.inputSchema === "object" && declaration.inputSchema !== null,
+				planes: ["browser"],
+				filePath
+			});
+			continue;
+		}
+		const key = readString(declaration.key);
+		const title = readString(declaration.title);
+		const description = readString(declaration.description);
+		const steps = normalizeSteps(declaration.steps);
+		if (!key || !title || !description || !steps) {
+			report("incomplete-declaration", helper, `a playbook needs a literal \`key\`, \`title\`, \`description\`, and a \`steps\` array of \`{ kind: "operation", model, action }\` / \`{ kind: "intent", id }\` members to be emitted. ${ESCAPE_HATCH}`, node.start);
+			continue;
+		}
+		const playbookProblem = playbookDeclarationProblem(declaration, key, steps);
+		if (playbookProblem) {
+			report("invalid-identity", helper, playbookProblem, node.start);
+			continue;
+		}
+		const declaredPlanes = normalizePlanes(declaration.planes);
+		playbooks.push({
+			kind: "playbook",
+			key,
+			title,
+			description,
+			steps,
+			planes: declaredPlanes.length > 0 ? declaredPlanes : steps.some((step) => step.kind === "intent") ? ["browser"] : ["browser", "server"],
+			planesDeclared: declaredPlanes.length > 0,
+			onStepFailure: declaration.onStepFailure === "continue" ? "continue" : "abort",
+			enabled: declaration.enabled !== false,
+			filePath
+		});
+	}
+	return {
+		intents,
+		playbooks,
+		diagnostics
+	};
+}
+function svelteCallOffset(text, helper) {
+	const names = /* @__PURE__ */ new Set([helper]);
+	const importPattern = new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*['"\`]${escapeRegExp(HELPER_SPECIFIERS[helper])}['"\`]`, "g");
+	for (const match of text.matchAll(importPattern)) for (const clause of match[1].split(",")) {
+		const alias = clause.trim().match(/^(\w+)\s+as\s+(\w+)$/);
+		if (alias && alias[1] === helper) names.add(alias[2]);
+	}
+	let earliest;
+	for (const name of names) {
+		const call = new RegExp(`\\b${escapeRegExp(name)}\\s*\\(`, "g");
+		for (const match of text.matchAll(call)) if (match.index !== void 0 && (earliest === void 0 || match.index < earliest)) earliest = match.index;
+	}
+	return earliest;
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function scanSvelteAgentSurface(filePath, sourceText) {
+	let text;
+	try {
+		text = sourceText ?? readFileSync(filePath, "utf-8");
+	} catch {
+		return [];
+	}
+	const diagnostics = [];
+	for (const helper of HELPER_NAMES) {
+		if (!text.includes(HELPER_SPECIFIERS[helper])) continue;
+		const callIndex = svelteCallOffset(text, helper);
+		if (callIndex === void 0) continue;
+		const loc = getLineColumn(text, callIndex);
+		const sidecar = helper === "defineIntent" ? "intents" : "playbooks";
+		diagnostics.push({
+			code: "svelte-declaration",
+			helper,
+			message: `\`${helper}()\` is called in a .svelte file, which the scanner never reads, so this declaration can never reach the manifest or knowledge graph. Move it to a \`.ts\` sidecar (\`Foo.${sidecar}.ts\`) and import it from the component. ${ESCAPE_HATCH}`,
+			filePath,
+			line: loc?.line,
+			column: loc?.column
+		});
+	}
+	return diagnostics;
+}
+function compareStrings(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+function mergeAgentSurfaces(surfaces, relativize = (filePath) => filePath) {
+	const diagnostics = [];
+	const intents = /* @__PURE__ */ new Map();
+	const playbooks = /* @__PURE__ */ new Map();
+	const claim = (bucket, identity, entry, helper, label) => {
+		const existing = bucket.get(identity);
+		if (!existing) {
+			bucket.set(identity, entry);
+			return;
+		}
+		const [winner, loser] = entry.filePath < existing.filePath ? [entry, existing] : [existing, entry];
+		bucket.set(identity, winner);
+		diagnostics.push({
+			code: "duplicate-identity",
+			helper,
+			message: `${label} \`${identity}\` is declared in both \`${winner.filePath}\` and \`${loser.filePath}\`. Identity must be unique across the project; the declaration in the first path is emitted and this one is dropped.`,
+			filePath: loser.filePath
+		});
+	};
+	for (const surface of surfaces) {
+		for (const intent of surface.intents) claim(intents, intent.id, {
+			...intent,
+			filePath: relativize(intent.filePath)
+		}, "defineIntent", "view intent");
+		for (const playbook of surface.playbooks) claim(playbooks, playbook.key, {
+			...playbook,
+			filePath: relativize(playbook.filePath)
+		}, "definePlaybook", "playbook");
+		for (const diagnostic of surface.diagnostics) diagnostics.push({
+			...diagnostic,
+			filePath: relativize(diagnostic.filePath)
+		});
+	}
+	const sortedIntents = [...intents.values()].sort((a, b) => compareStrings(a.id, b.id) || compareStrings(a.filePath, b.filePath));
+	const byToolName = /* @__PURE__ */ new Map();
+	const survivingIntents = [];
+	for (const intent of sortedIntents) {
+		const toolName = intentToolName(intent.id);
+		const claimed = byToolName.get(toolName);
+		if (!claimed) {
+			byToolName.set(toolName, intent);
+			survivingIntents.push(intent);
+			continue;
+		}
+		const [winner, loser] = intent.filePath < claimed.filePath ? [intent, claimed] : [claimed, intent];
+		byToolName.set(toolName, winner);
+		if (winner !== claimed) survivingIntents[survivingIntents.indexOf(claimed)] = winner;
+		diagnostics.push({
+			code: "duplicate-identity",
+			helper: "defineIntent",
+			message: `view intents \`${winner.id}\` and \`${loser.id}\` both derive the WebMCP tool name \`${toolName}\`, which \`defineIntent\` rejects at registration. The declaration in \`${winner.filePath}\` is emitted and the one in \`${loser.filePath}\` is dropped.`,
+			filePath: loser.filePath
+		});
+	}
+	return {
+		intents: survivingIntents.sort((a, b) => compareStrings(a.id, b.id) || compareStrings(a.filePath, b.filePath)),
+		playbooks: [...playbooks.values()].sort((a, b) => compareStrings(a.key, b.key) || compareStrings(a.filePath, b.filePath)),
+		diagnostics: diagnostics.sort((a, b) => compareStrings(a.filePath, b.filePath) || (a.line ?? 0) - (b.line ?? 0) || (a.column ?? 0) - (b.column ?? 0) || compareStrings(a.code, b.code) || compareStrings(a.message, b.message))
+	};
+}
+function emptyAgentSurface() {
+	return {
+		intents: [],
+		playbooks: [],
+		diagnostics: []
+	};
+}
+//#endregion
 //#region src/discovery.ts
 var MANDATORY_DISCOVERY_EXCLUDES = Object.freeze([
 	"**/node_modules/**",
@@ -367,19 +1041,6 @@ function getLangFromFilename(filename) {
 	if (filename.endsWith(".jsx")) return "jsx";
 	return "js";
 }
-function getLineColumn(sourceText, offset) {
-	if (offset < 0 || offset > sourceText.length) return;
-	let line = 1;
-	let lastNewlinePos = -1;
-	for (let i = 0; i < offset; i++) if (sourceText[i] === "\n") {
-		line++;
-		lastNewlinePos = i;
-	}
-	return {
-		line,
-		column: offset - lastNewlinePos
-	};
-}
 function getRange(node) {
 	if (node.range) return node.range;
 	if (node.start !== void 0 && node.end !== void 0) return [node.start, node.end];
@@ -395,6 +1056,7 @@ function parseFile(filePath) {
 	const classes = [];
 	let typeAliases = {};
 	let smrtImports;
+	let agentSurface;
 	try {
 		const sourceText = readFileSync(filePath, "utf-8");
 		const result = parseSync(filePath, sourceText, {
@@ -425,6 +1087,7 @@ function parseFile(filePath) {
 				if (extracted) classes.push(extracted);
 			}
 			reportUnresolvedSpreads(ctx.unresolved, filePath, sourceText, errors);
+			agentSurface = maybeExtractAgentSurface(program, sourceText, filePath);
 		}
 	} catch (error) {
 		errors.push({
@@ -441,14 +1104,44 @@ function parseFile(filePath) {
 		typeAliases
 	};
 	if (smrtImports && smrtImports.size > 0) result2.smrtImports = smrtImports;
+	if (agentSurface) result2.agentSurface = agentSurface;
 	return result2;
 }
+function maybeExtractAgentSurface(program, sourceText, filePath) {
+	if (!sourceMayDeclareAgentSurface(sourceText)) return void 0;
+	const surface = extractAgentSurface({
+		body: program.body,
+		sourceText,
+		filePath
+	});
+	return surface.intents.length > 0 || surface.playbooks.length > 0 || surface.diagnostics.length > 0 ? surface : void 0;
+}
+function parseAgentSurfaceFile(filePath) {
+	let sourceText;
+	try {
+		sourceText = readFileSync(filePath, "utf-8");
+	} catch {
+		return;
+	}
+	if (!sourceMayDeclareAgentSurface(sourceText)) return void 0;
+	try {
+		const program = parseSync(filePath, sourceText, {
+			lang: getLangFromFilename(filePath),
+			preserveParens: false
+		}).program;
+		if (!program?.body) return void 0;
+		return maybeExtractAgentSurface(program, sourceText, filePath);
+	} catch {
+		return;
+	}
+}
 function parseSource(sourceText, filename = "test.ts") {
 	const startTime = performance.now();
 	const errors = [];
 	const classes = [];
 	let typeAliases = {};
 	let smrtImports;
+	let agentSurface;
 	try {
 		const result = parseSync(filename, sourceText, {
 			lang: getLangFromFilename(filename),
@@ -478,6 +1171,7 @@ function parseSource(sourceText, filename = "test.ts") {
 				if (extracted) classes.push(extracted);
 			}
 			reportUnresolvedSpreads(ctx.unresolved, filename, sourceText, errors);
+			agentSurface = maybeExtractAgentSurface(program, sourceText, filename);
 		}
 	} catch (error) {
 		errors.push({
@@ -494,6 +1188,7 @@ function parseSource(sourceText, filename = "test.ts") {
 		typeAliases
 	};
 	if (smrtImports && smrtImports.size > 0) result2.smrtImports = smrtImports;
+	if (agentSurface) result2.agentSurface = agentSurface;
 	return result2;
 }
 var FORBIDDEN_OBJECT_KEYS = /* @__PURE__ */ new Set([
@@ -1951,6 +2646,20 @@ var ManifestAdapter = class ManifestAdapter {
 //#endregion
 //#region src/scanner.ts
 var DEFAULT_INCLUDE = ["**/*.ts", "**/*.tsx"];
+var DEFAULT_SVELTE_INCLUDE = ["**/*.svelte"];
+var DEFAULT_AGENT_SURFACE_INCLUDE = [
+	"**/*.ts",
+	"**/*.tsx",
+	"**/*.js",
+	"**/*.jsx"
+];
+var AGENT_SURFACE_PRUNE = [
+	"**/dist/**",
+	"**/build/**",
+	"**/coverage/**",
+	"**/__tests__/**",
+	"**/__typechecks__/**"
+];
 var DEFAULT_EXCLUDE = [
 	"**/node_modules/**",
 	"**/dist/**",
@@ -1984,7 +2693,10 @@ var OxcScanner = class {
 			includePrivateMethods: options.includePrivateMethods ?? false,
 			includeStaticMethods: options.includeStaticMethods ?? true,
 			externalManifests: options.externalManifests || /* @__PURE__ */ new Map(),
-			followSymbolicLinks: options.followSymbolicLinks ?? false
+			followSymbolicLinks: options.followSymbolicLinks ?? false,
+			agentSurface: options.agentSurface ?? true,
+			svelteInclude: options.svelteInclude || DEFAULT_SVELTE_INCLUDE,
+			agentSurfaceInclude: options.agentSurfaceInclude || DEFAULT_AGENT_SURFACE_INCLUDE
 		};
 		this.resolver = new InheritanceResolver({
 			baseClasses: this.options.baseClasses,
@@ -2020,12 +2732,20 @@ var OxcScanner = class {
 			errors: [],
 			totalParseTimeMs: performance.now() - startTime,
 			fileCount: files.length,
-			typeAliases: {}
+			typeAliases: {},
+			agentSurface: emptyAgentSurface()
 		};
+		const surfaces = [];
 		for (const file of fileResults) {
 			for (const classDef of file.classes) results.classes.push(classDef);
 			for (const error of file.errors) results.errors.push(error);
 			Object.assign(results.typeAliases, file.typeAliases);
+			if (file.agentSurface && isAgentSurfaceSourcePath(file.filePath, this.options.cwd)) surfaces.push(file.agentSurface);
+		}
+		if (this.options.agentSurface) {
+			surfaces.push(...await this.scanDeclarationsOutsideClassGlob(new Set(files)));
+			surfaces.push(await this.scanSvelteDeclarations());
+			results.agentSurface = mergeAgentSurfaces(surfaces, (filePath) => this.relativizeSourcePath(filePath));
 		}
 		this.resolver.addClasses(results.classes);
 		this.scanResults = results;
@@ -2172,6 +2892,82 @@ var OxcScanner = class {
 		});
 	}
 	/**
+	* Find declarations in files the CLASS scan did not cover.
+	*
+	* The class `include` is routinely narrowed to where models live, but an
+	* intent sidecar lives beside its component. Without this pass those
+	* declarations would be missing from every artifact with no diagnostic — a
+	* silent omission, and in the shipped SvelteKit template's own layout at
+	* that. Files already parsed by the class scan are skipped so a declaration
+	* is never counted twice and cannot collide with itself.
+	*
+	* @param alreadyScanned - Absolute paths the class scan already parsed.
+	*/
+	async scanDeclarationsOutsideClassGlob(alreadyScanned) {
+		if (this.options.agentSurfaceInclude.length === 0) return [];
+		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 [];
+		}
+		const surfaces = [];
+		for (const filePath of files) {
+			if (alreadyScanned.has(filePath)) continue;
+			if (!isAgentSurfaceSourcePath(filePath, this.options.cwd)) continue;
+			const surface = parseAgentSurfaceFile(filePath);
+			if (surface) surfaces.push(surface);
+		}
+		return surfaces;
+	}
+	/**
+	* Search `.svelte` files for declarations the scanner can never read.
+	*
+	* A `.svelte` file is not a TypeScript program and is never parsed here, so
+	* this pass produces diagnostics only — never an emitted entry. It exists
+	* because the alternative is silence: an intent declared inline in a
+	* component simply would not appear anywhere, with nothing to explain why.
+	*/
+	async scanSvelteDeclarations() {
+		const surface = emptyAgentSurface();
+		if (this.options.svelteInclude.length === 0) return surface;
+		const exclude = [...this.options.exclude.filter((pattern) => !pattern.endsWith(".svelte")), ...AGENT_SURFACE_PRUNE];
+		let files;
+		try {
+			files = await discoverSourceFiles({
+				cwd: this.options.cwd,
+				include: this.options.svelteInclude,
+				exclude,
+				followSymbolicLinks: this.options.followSymbolicLinks
+			});
+		} catch {
+			return surface;
+		}
+		for (const filePath of files) {
+			if (isPrunedAgentSurfacePath(filePath, this.options.cwd)) continue;
+			surface.diagnostics.push(...scanSvelteAgentSurface(filePath));
+		}
+		return surface;
+	}
+	/**
+	* Record a declaring module as a `cwd`-relative POSIX path.
+	*
+	* Emitted entries land in checked-in artifacts, so an absolute path would
+	* make them machine-specific and a Windows separator would make them
+	* platform-specific — either one churns a snapshot that is supposed to prove
+	* two builds agree.
+	*/
+	relativizeSourcePath(filePath) {
+		const relativePath = relative(this.options.cwd, filePath);
+		if (!relativePath || relativePath.startsWith("..")) return filePath;
+		return sep === "/" ? relativePath : relativePath.split(sep).join("/");
+	}
+	/**
 	* Parse a single file with timing
 	*/
 	async parseFileWithTiming(filePath) {
@@ -2179,6 +2975,6 @@ var OxcScanner = class {
 	}
 };
 //#endregion
-export { parseSource as a, normalizeGlobSeparators as c, parseFile as i, relativeGlobToCwd as l, ManifestAdapter as n, InheritanceResolver as o, extractSmrtImports as r, discoverSourceFiles as s, OxcScanner as t };
+export { sourceMayDeclareAgentSurface as _, parseFile as a, discoverSourceFiles as c, emptyAgentSurface as d, extractAgentSurface as f, scanSvelteAgentSurface as g, mergeAgentSurfaces as h, parseAgentSurfaceFile as i, normalizeGlobSeparators as l, isPrunedAgentSurfacePath as m, ManifestAdapter as n, parseSource as o, isAgentSurfaceSourcePath as p, extractSmrtImports as r, InheritanceResolver as s, OxcScanner as t, relativeGlobToCwd as u };
 
-//# sourceMappingURL=scanner-CW9g-vyS.js.map
+//# sourceMappingURL=scanner-C3VqXyzB.js.map