@happyvertical/smrt-scanner 0.47.0 → 0.47.2

package/AGENTS.md

@@ -38,6 +38,9 @@ executes the source.
   by `OxcScanner` and the core manifest preflight.
 - `extractAgentSurface` / `scanSvelteAgentSurface` / `mergeAgentSurfaces` —
   the agent-surface matcher (#2591). See below.
+- `checkAgentSurfaceToolNames(surface, { generatedToolNames, uiToolPrefixes })`
+  — report an emitted intent whose derived WebMCP tool name a generated model
+  tool or a fixed UI tool already registers (#2725). Takes names, never config.
 - Types (re-exported from `./types`): `RawClassDefinition`,
   `RawFieldDefinition`, `RawMethodDefinition`, `ResolvedClassDefinition`,
   `ScanResults`, `FileScanResult`, `OxcScannerOptions`, `InferredFieldType`,
@@ -79,7 +82,9 @@ build output can retain declarations and otherwise win duplicate resolution.
 ### What it refuses, always with a diagnostic
 
 Never a silent omission — every message names `useWebMcpTool`, the escape hatch
-for a tool set genuinely derived from computed or fetched data:
+for a tool set genuinely derived from computed or fetched data. Every code here
+means the declaration was NOT emitted; `tool-name-collision` (below) is the one
+exception and is advisory:
 
 | Code | Shape |
 |---|---|
@@ -90,6 +95,7 @@ for a tool set genuinely derived from computed or fetched data:
 | `invalid-identity` | a declaration the runtime helper itself would reject: an intent `id` that is not lowercase and dot-namespaced, over 128 chars, or resolving into the reserved `smrt_ui_` namespace; an unknown declaration, target, or capability key; a malformed `capability` (bad `effect`, non-boolean flag); a `target` outside the closed `control`/`dataSurface` unions or missing a required `controlId`; a playbook with no steps, an empty/non-array/unknown-plane `planes`, an `onStepFailure` outside `abort`/`continue`, a non-boolean `enabled`, or a step whose `model` is not a qualified pair |
 | `svelte-declaration` | written inline in a `.svelte` file |
 | `duplicate-identity` | two modules declare the same `id`/`key`, or two intent ids derive the same WebMCP tool name |
+| `tool-name-collision` | an EMITTED intent whose derived tool name is already registered by a generated model tool or a fixed UI tool (see below) |
 
 Mirror `defineIntent` and `definePlaybook` validation without importing their
 packages; update the scanner whenever those runtime rules tighten. Reject
@@ -120,6 +126,68 @@ cross-profile parity snapshot does not churn on directory order:
 - paths are recorded `cwd`-relative and POSIX-separated, so a checked-in
   artifact is neither machine- nor platform-specific.
 
+### Collisions with names this pass does not own (#2725)
+
+`mergeAgentSurfaces` resolves intent-vs-intent by dropping the loser, because
+`defineIntent` REJECTS the second colliding declaration — only one can exist.
+Two other sources register into the same document and are invisible to the
+declaration scan, so `checkAgentSurfaceToolNames` reports them **without
+dropping anything**:
+
+- **generated model tools**, `${className.toLowerCase()}_${action}`, so
+  `defineIntent({ id: 'product.list' })` lands on `Product.list`;
+- **the six fixed UI tools** under the configured `webmcp.ui.prefix`.
+
+Warnings, not drops, and the asymmetry is the point: `defineIntent` accepts
+these ids, so the declarations are real and belong in the artifact; the
+document-global tool-name lock (#2613) decides which registration survives,
+rejecting the second with a `WebMcpToolNameCollisionError` — a runtime answer to
+a question the build can already see coming, which costs whoever loses its tool;
+and whether it happens at all turns on runtime values no artifact records (a
+WebMCP `namespace`, an `effects` policy, whether a page mounts both). A
+build-time drop would guess all three, and the emitted surface would stop
+matching the source.
+
+Because those values are unknowable here, the generated-tool message **states
+the precondition it assumes** — no `namespace`, action within the `effects`
+policy — and says to disregard it when either already separates the pair. A
+`namespace` prefixes generated tools and leaves intents alone, so it dissolves
+the collision outright; without that sentence a namespaced app would get a
+notice that is always wrong where it fires, recommending the remedy it had
+already applied. `smrt doctor`'s header is `Tool name also claimed` for the same
+reason: it must not assert past what the message says.
+
+**It takes NAMES, never config.** The caller passes the tool names that will
+really register; this module never derives a generated name and never applies a
+namespace. `namespace` and `ui.prefix` are runtime `<Provider webmcp={…}>`
+values that no build artifact records, so a build-time declaration of either
+would be a second place to say what the provider already says, free to diverge
+silently. Core supplies the names from `buildWebMcpToolDefinitions` — the same
+function that emits the runtime `webMcpToolDefinitions`, and therefore already
+filtered by the exposure policy. Comparing against every verb a class *could*
+expose would invent collisions with tools nobody mounts.
+
+`uiToolPrefixes` is supplied for the same reason, defaulting to the registrar's
+`smrt_ui_`. Do NOT replace it with a prefix derived from the name: quantifying
+over every prefix an app could have configured has, under the default, no true
+positive at all — an id flattening to `smrt_ui_*` is rejected during extraction
+— so every diagnostic it emits for a default-configured app is false, persisted
+into the artifact and clearable only by renaming a correct intent. There is no
+build-time source for `ui.prefix` (a runtime `<Provider>` prop), so this half is
+dormant by default and the seam waits for a caller that can fill it.
+
+`RESERVED_TOOL_NAME_PREFIX` is **not** configurable and must not become so — it
+mirrors `defineIntent`'s own literal, which rejects the id wherever an app moved
+its UI tools, so accepting one here would emit an entry the runtime refuses to
+construct.
+
+Consumers: core's Vite plugin runs the check once the manifest exists and
+appends the diagnostics to the emitted surface; `dev:knowledge-check` maps the
+code to the `agent-surface-tool-name-collision` warning and **excludes it from
+the artifact-drift comparison**, which re-derives declarations from source and
+has no manifest to produce one from; `smrt doctor` prints it under
+`⚠️  Tool name also claimed`, separately from `Not statically emittable`.
+
 The scanner mirrors the #2587 capability vocabulary structurally instead of
 importing `@happyvertical/smrt-types`: core depends on this package, so the
 reverse edge would close a cycle. Core reconciles the two shapes in exactly one
@@ -160,7 +228,8 @@ place, `toKnowledgeAgentSurface` in `vite-plugin/index.ts`.
   field-type inference.
 - `src/verify-completeness.ts` — `verifyManifestCompleteness` publish guard.
 - `src/agent-surface.ts` — the `defineIntent` / `definePlaybook` matcher, its
-  diagnostics, and `mergeAgentSurfaces` (#2591).
+  diagnostics, `mergeAgentSurfaces` (#2591), and `checkAgentSurfaceToolNames`
+  (#2725).
 - `src/source-location.ts` — `getLineColumn`, split out so `agent-surface.ts`
   can resolve a diagnostic's position without importing `oxc-parser.ts`, which
   imports it back.

package/dist/chunks/{scanner-9p-PUN-X.js → scanner-CxUeI0FI.js}

@@ -29,6 +29,16 @@ 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 FIXED_UI_TOOL_SUFFIXES = [
+	"execute_data_surface_control",
+	"execute_form_control",
+	"inspect_data_surface",
+	"inspect_form_control",
+	"list_data_surfaces",
+	"list_form_controls"
+];
+var UI_TOOL_PREFIX_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+var DEFAULT_UI_TOOL_PREFIX = "smrt_ui_";
 var INTENT_DECLARATION_KEYS = /* @__PURE__ */ new Set([
 	"id",
 	"description",
@@ -668,6 +678,37 @@ function mergeAgentSurfaces(surfaces, relativize = (filePath) => 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 checkAgentSurfaceToolNames(surface, options = {}) {
+	const diagnostics = [];
+	const generated = /* @__PURE__ */ new Map();
+	for (const tool of options.generatedToolNames ?? []) if (!generated.has(tool.name)) generated.set(tool.name, tool);
+	const uiTools = /* @__PURE__ */ new Map();
+	for (const prefix of options.uiToolPrefixes ?? [DEFAULT_UI_TOOL_PREFIX]) {
+		if (!UI_TOOL_PREFIX_PATTERN.test(prefix)) continue;
+		for (const suffix of FIXED_UI_TOOL_SUFFIXES) if (!uiTools.has(`${prefix}${suffix}`)) uiTools.set(`${prefix}${suffix}`, prefix);
+	}
+	for (const intent of surface.intents) {
+		const toolName = intentToolName(intent.id);
+		const collidingTool = generated.get(toolName);
+		if (collidingTool) {
+			const owner = collidingTool.declaredBy ? `\`${collidingTool.declaredBy}\`` : "a generated model action";
+			diagnostics.push({
+				code: "tool-name-collision",
+				helper: "defineIntent",
+				message: `view intent \`${intent.id}\` derives the WebMCP tool name \`${toolName}\`, which is also the generated model tool for ${owner}. Both are emitted \u2014 \`defineIntent\` accepts the id, so the declaration is real. On a page that mounts both with no WebMCP \`namespace\`, the document-global tool-name lock rejects whichever registers second with a \`WebMcpToolNameCollisionError\`. A build cannot see the provider's \`namespace\` or \`effects\` policy, so if either already separates this pair, disregard this. Otherwise set a \`namespace\`, which prefixes the generated tools and leaves intents alone, or rename the intent.`,
+				filePath: intent.filePath
+			});
+		}
+		const uiPrefix = uiTools.get(toolName);
+		if (uiPrefix !== void 0) diagnostics.push({
+			code: "tool-name-collision",
+			helper: "defineIntent",
+			message: `view intent \`${intent.id}\` derives the WebMCP tool name \`${toolName}\`, which is also one of the six fixed UI tools mounted under \`ui.prefix\` \`${uiPrefix}\`. \`defineIntent\` accepts the id because it reserves only the default \`smrt_ui_\` prefix, so the two reach the document-global tool-name lock and whichever registers second is rejected with a \`WebMcpToolNameCollisionError\`. Rename the intent, or give the fixed UI tools a different \`ui.prefix\`.`,
+			filePath: intent.filePath
+		});
+	}
+	return diagnostics.sort((a, b) => compareStrings(a.filePath, b.filePath) || compareStrings(a.code, b.code) || compareStrings(a.message, b.message));
+}
 function emptyAgentSurface() {
 	return {
 		intents: [],
@@ -3095,6 +3136,6 @@ var OxcScanner = class {
 	}
 };
 //#endregion
-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 };
+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 };
 
-//# sourceMappingURL=scanner-9p-PUN-X.js.map
+//# sourceMappingURL=scanner-CxUeI0FI.js.map