noodleseed-cli 0.1.4

package/node_modules/@noodle-borg/compiler/dist/compile.js

@@ -0,0 +1,719 @@
+import { parse as parseYaml, YAMLParseError } from 'yaml';
+import { ARTIFACT_SCHEMA_VERSION, MCP_APP_MIME_TYPE, } from './artifact/types.js';
+import { computeSignatureHash } from './catalog/signature.js';
+import { collectPaths, parseCondition, parseValue, } from './manifest/expression.js';
+import { parseOperationRef } from './manifest/naming.js';
+import { manifestSchema } from './manifest/schema.js';
+import { resolveSchemaUses } from './manifest/schema-refs.js';
+import { docAnchorFor, suggestionFields } from './suggest.js';
+import { parseUriTemplate } from './uri-template.js';
+const JSON_SCHEMA_2020_12 = 'https://json-schema.org/draft/2020-12/schema';
+const NO_STEPS = { stepIndexById: new Map(), currentIdx: null };
+/**
+ * Compile a YAML manifest into a normalized runtime artifact.
+ *
+ * Pipeline: parse YAML -> validate static shape (Zod) -> structural passes (duplicate names,
+ * `$use` schema resolution, external `$ref` rejection, fulfilment parsing — flow steps + `${...}`
+ * expressions to AST) -> emit artifact. Expression and `$use` resolution are catalog-independent and
+ * always run. With a catalog in {@link CompileOptions}, connector resolution follows (alias/operation
+ * lookup, argument signature checks) and the artifact is `resolved`; without one it is `shape-only`
+ * (only connector resolution deferred). Returns every error it can find rather than stopping at the
+ * first. See docs/SPEC.md and docs/IMPLEMENTATION-LOG.md.
+ */
+export function compile(source, options = {}) {
+    // 1. Parse YAML.
+    let raw;
+    try {
+        raw = parseYaml(source);
+    }
+    catch (err) {
+        if (err instanceof YAMLParseError) {
+            const pos = err.linePos?.[0];
+            const where = pos ? ` at line ${pos.line}, column ${pos.col}` : '';
+            return {
+                ok: false,
+                errors: [{ code: 'yaml_parse_error', path: '', message: `${err.message}${where}` }],
+            };
+        }
+        throw err;
+    }
+    return compileManifest(raw, options);
+}
+/**
+ * Validate an already-materialized manifest **object** for authoring-contract conformance **without** a
+ * connector catalog: Zod shape validation plus every catalog-independent structural pass (duplicate
+ * names, `$use` resolution, external-`$ref` rejection, fulfilment + `${...}` expression parsing,
+ * URI-template classification, resource/prompt namespacing). Connector-resolution errors (unknown
+ * alias/operation, unused alias, argument signature) are **not** reported here — they require a catalog
+ * and are produced by {@link compile} / {@link compileManifest} with `{ catalog }`.
+ *
+ * This is the stable, in-process contract a *machine* manifest generator targets: an object in,
+ * structured {@link CompileError}s out (carrying GT-1's `didYouMean`/`expected`/`got` where relevant).
+ * To also parse YAML, use {@link compile}; to resolve against a catalog, pass one to
+ * {@link compileManifest}. See GT-2 in docs/STATUS.md. It is a faithful projection of
+ * `compileManifest(raw)` — the artifact is dropped, the error set is identical.
+ */
+export function validateManifest(raw) {
+    const result = compileManifest(raw);
+    return result.ok ? { ok: true, errors: [] } : { ok: false, errors: result.errors };
+}
+/**
+ * Compile an already-materialized manifest object into the same normalized runtime artifact emitted by
+ * {@link compile}. This is the shared path for YAML manifests and TypeScript authoring SDK output.
+ */
+export function compileManifest(raw, options = {}) {
+    // 1. Validate static shape.
+    const parsed = manifestSchema.safeParse(raw);
+    if (!parsed.success) {
+        return { ok: false, errors: parsed.error.issues.map(translateIssue) };
+    }
+    const manifest = parsed.data;
+    // 2. Structural passes (catalog-independent): duplicate names, `$use` resolution, external refs,
+    // fulfilment parsing. `$use` is resolved first so external-ref detection also scans bundled defs.
+    const errors = [];
+    const seen = new Set();
+    const schemasMap = manifest.schemas ?? {};
+    const structural = [];
+    manifest.tools.forEach((tool, i) => {
+        if (seen.has(tool.name)) {
+            errors.push({
+                code: 'duplicate_name',
+                path: `tools.${i}.name`,
+                message: `duplicate tool name "${tool.name}"`,
+            });
+        }
+        seen.add(tool.name);
+        const input = resolveSchemaUses(tool.inputSchema, schemasMap, `tools.${i}.inputSchema`);
+        errors.push(...input.errors);
+        const inputExternalRef = findExternalRef(input.schema, `tools.${i}.inputSchema`);
+        if (inputExternalRef)
+            errors.push(inputExternalRef);
+        let outputSchema;
+        if (tool.outputSchema) {
+            const output = resolveSchemaUses(tool.outputSchema, schemasMap, `tools.${i}.outputSchema`);
+            errors.push(...output.errors);
+            const outputExternalRef = findExternalRef(output.schema, `tools.${i}.outputSchema`);
+            if (outputExternalRef)
+                errors.push(outputExternalRef);
+            outputSchema = output.schema;
+        }
+        const fulfilment = parseFulfilment(tool.fulfilment, `tools.${i}.fulfilment`, schemasMap, errors);
+        if (!fulfilment)
+            return; // a structural fulfilment error was already recorded
+        structural.push({
+            tool,
+            index: i,
+            inputSchema: input.schema,
+            ...(outputSchema ? { outputSchema } : {}),
+            fulfilment,
+        });
+    });
+    // Resources: separate name namespace, unique URIs, `{var}` template classification. Fulfilment may be
+    // a steps-less flow (a static constant), so empty flows are allowed.
+    const structResources = [];
+    const resourceSeen = new Set();
+    const resourceUriSeen = new Set();
+    (manifest.resources ?? []).forEach((resource, i) => {
+        if (resourceSeen.has(resource.name)) {
+            errors.push({
+                code: 'duplicate_resource',
+                path: `resources.${i}.name`,
+                message: `duplicate resource name "${resource.name}"`,
+            });
+        }
+        resourceSeen.add(resource.name);
+        const parsedUri = parseUriTemplate(resource.uri);
+        if (!parsedUri.ok) {
+            errors.push({
+                code: 'unsupported_uri_template',
+                path: `resources.${i}.uri`,
+                message: parsedUri.error,
+            });
+            return;
+        }
+        if (resourceUriSeen.has(resource.uri)) {
+            errors.push({
+                code: 'duplicate_resource_uri',
+                path: `resources.${i}.uri`,
+                message: `duplicate resource uri "${resource.uri}"`,
+            });
+        }
+        resourceUriSeen.add(resource.uri);
+        const fulfilment = parseFulfilment(resource.fulfilment, `resources.${i}.fulfilment`, schemasMap, errors);
+        if (!fulfilment)
+            return;
+        structResources.push({
+            resource,
+            isTemplate: parsedUri.value.kind === 'template',
+            variables: parsedUri.value.kind === 'template' ? parsedUri.value.variables : [],
+            fulfilment,
+        });
+    });
+    // Prompts: separate name namespace; fulfilment input scope is the supplied arguments.
+    const structPrompts = [];
+    const promptSeen = new Set();
+    (manifest.prompts ?? []).forEach((prompt, i) => {
+        if (promptSeen.has(prompt.name)) {
+            errors.push({
+                code: 'duplicate_prompt',
+                path: `prompts.${i}.name`,
+                message: `duplicate prompt name "${prompt.name}"`,
+            });
+        }
+        promptSeen.add(prompt.name);
+        const fulfilment = parseFulfilment(prompt.fulfilment, `prompts.${i}.fulfilment`, schemasMap, errors);
+        if (!fulfilment)
+            return;
+        structPrompts.push({ prompt, fulfilment });
+    });
+    // Widgets (MCP Apps; ADR 0022): each links an existing tool and desugars to a fixed `ui://` resource.
+    // Validate name uniqueness, the tool link, one-widget-per-tool, and that the synthesized resource
+    // name/uri do not collide with a declared resource (widgets share the resources/list namespace). `seen`
+    // holds the tool names accumulated above; `resourceSeen`/`resourceUriSeen` hold the declared resources.
+    const widgetSeen = new Set();
+    const widgetToolSeen = new Set();
+    (manifest.widgets ?? []).forEach((widget, i) => {
+        if (widgetSeen.has(widget.name)) {
+            errors.push({
+                code: 'duplicate_widget',
+                path: `widgets.${i}.name`,
+                message: `duplicate widget name "${widget.name}"`,
+            });
+        }
+        widgetSeen.add(widget.name);
+        if (!seen.has(widget.tool)) {
+            // The actionable root cause is the missing tool; do not also flag a "duplicate link" below.
+            errors.push({
+                code: 'unknown_widget_tool',
+                path: `widgets.${i}.tool`,
+                message: `widget "${widget.name}" links unknown tool "${widget.tool}"`,
+                got: widget.tool,
+                ...suggestionFields('unknown_widget_tool', widget.tool, [...seen]),
+            });
+        }
+        else {
+            if (widgetToolSeen.has(widget.tool)) {
+                errors.push({
+                    code: 'duplicate_widget_tool',
+                    path: `widgets.${i}.tool`,
+                    message: `tool "${widget.tool}" is already linked to a widget (a tool declares at most one widget)`,
+                });
+            }
+            widgetToolSeen.add(widget.tool);
+        }
+        if (resourceSeen.has(widget.name)) {
+            errors.push({
+                code: 'duplicate_resource',
+                path: `widgets.${i}.name`,
+                message: `widget name "${widget.name}" collides with a declared resource name`,
+            });
+        }
+        resourceSeen.add(widget.name);
+        const uri = widgetUri(manifest.server.name, widget.name);
+        if (resourceUriSeen.has(uri)) {
+            errors.push({
+                code: 'duplicate_resource_uri',
+                path: `widgets.${i}.name`,
+                message: `widget resource uri "${uri}" collides with a declared resource uri`,
+            });
+        }
+        resourceUriSeen.add(uri);
+    });
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    // Desugar widgets to fixed `ui://` resources + a `_meta.ui.resourceUri` link on the named tool. The
+    // `html` body is emitted as a constant `literal` expression — never run through the expression parser —
+    // so inline `<script>` `${...}` in widget HTML stays opaque (it is not our mapping language).
+    const widgetResources = (manifest.widgets ?? []).map((widget) => {
+        const uri = widgetUri(manifest.server.name, widget.name);
+        const uiMeta = resourceUiMeta(widget);
+        return {
+            name: widget.name,
+            uri,
+            ...(widget.title ? { title: widget.title } : {}),
+            ...(widget.description ? { description: widget.description } : {}),
+            mimeType: MCP_APP_MIME_TYPE,
+            isTemplate: false,
+            fulfilment: {
+                kind: 'flow',
+                steps: [],
+                output: { value: { kind: 'literal', value: widget.html } },
+            },
+            ...(uiMeta ? { _meta: { ui: uiMeta } } : {}),
+        };
+    });
+    const toolUiMetaByName = new Map((manifest.widgets ?? []).map((widget) => [
+        widget.tool,
+        { ui: { resourceUri: widgetUri(manifest.server.name, widget.name) } },
+    ]));
+    // 3. Resolve connector references and emit per-tool fulfilment.
+    const declared = manifest.connectors ?? {};
+    const usedAliases = new Set();
+    const artifactTools = structural.map((s) => {
+        const fulfilment = emitFulfilment(s.fulfilment, options.catalog, declared, usedAliases, errors);
+        const inputSchema = withDialect(s.inputSchema);
+        // A tool's `_meta.ui` merges the widget link (`resourceUri`, when a widget targets this tool) with
+        // its declared `visibility` (`['app']` = UI-only). Emit `_meta` only when `ui` carries something.
+        const linkedUi = toolUiMetaByName.get(s.tool.name)?.ui;
+        const ui = {
+            ...(linkedUi ?? {}),
+            ...(s.tool.visibility ? { visibility: s.tool.visibility } : {}),
+        };
+        const meta = Object.keys(ui).length > 0 ? { ui } : undefined;
+        return {
+            name: s.tool.name,
+            description: s.tool.description,
+            inputSchema,
+            ...(s.outputSchema ? { outputSchema: withDialect(s.outputSchema) } : {}),
+            fulfilment,
+            ...(meta ? { _meta: meta } : {}),
+        };
+    });
+    // Emit resources/prompts. Their connector aliases also count toward `usedAliases`, so a connector
+    // referenced only by a resource/prompt is not falsely flagged as unused.
+    const artifactResources = structResources.map((s) => {
+        const fulfilment = emitFulfilment(s.fulfilment, options.catalog, declared, usedAliases, errors);
+        return {
+            name: s.resource.name,
+            uri: s.resource.uri,
+            ...(s.resource.title ? { title: s.resource.title } : {}),
+            ...(s.resource.description ? { description: s.resource.description } : {}),
+            ...(s.resource.mimeType ? { mimeType: s.resource.mimeType } : {}),
+            isTemplate: s.isTemplate,
+            ...(s.variables.length > 0 ? { variables: s.variables } : {}),
+            fulfilment,
+        };
+    });
+    const artifactPrompts = structPrompts.map((s) => {
+        const fulfilment = emitFulfilment(s.fulfilment, options.catalog, declared, usedAliases, errors);
+        const args = s.prompt.arguments?.map((a) => ({
+            name: a.name,
+            ...(a.description !== undefined ? { description: a.description } : {}),
+            ...(a.required !== undefined ? { required: a.required } : {}),
+        }));
+        return {
+            name: s.prompt.name,
+            ...(s.prompt.title ? { title: s.prompt.title } : {}),
+            ...(s.prompt.description ? { description: s.prompt.description } : {}),
+            ...(args ? { arguments: args } : {}),
+            fulfilment,
+        };
+    });
+    // Reject connector aliases that are declared but never referenced (docs/SPEC.md line 166).
+    if (options.catalog) {
+        for (const alias of Object.keys(declared)) {
+            if (!usedAliases.has(alias)) {
+                errors.push({
+                    code: 'unused_connector_alias',
+                    path: `connectors.${alias}`,
+                    message: `connector alias "${alias}" is declared but never used`,
+                });
+            }
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    // Widget `ui://` resources are appended after the hand-declared resources; both share the resources
+    // surface (resources/list + resources/read), so widgets are served by the existing wire path.
+    const allResources = [...artifactResources, ...widgetResources];
+    // 4. Assemble the artifact. `resources`/`prompts` and their capability lists are emitted only when
+    // present, keeping a tools-only artifact byte-identical to before this slice.
+    const capabilities = {
+        tools: manifest.tools.map((tool) => tool.name),
+        ...(allResources.length > 0 ? { resources: allResources.map((r) => r.name) } : {}),
+        ...(artifactPrompts.length > 0 ? { prompts: artifactPrompts.map((p) => p.name) } : {}),
+    };
+    const artifact = {
+        artifactSchemaVersion: ARTIFACT_SCHEMA_VERSION,
+        resolution: options.catalog ? 'resolved' : 'shape-only',
+        source: { manifestName: manifest.server.name, manifestVersion: manifest.server.version },
+        server: {
+            name: manifest.server.name,
+            version: manifest.server.version,
+            title: manifest.server.title,
+        },
+        tools: artifactTools,
+        ...(allResources.length > 0 ? { resources: allResources } : {}),
+        ...(artifactPrompts.length > 0 ? { prompts: artifactPrompts } : {}),
+        capabilities,
+    };
+    return { ok: true, artifact };
+}
+/**
+ * Parse a fulfilment into a {@link StructFulfilment} with all `${...}` expressions resolved to AST and
+ * all step references validated. `prefix` is the dotted path of the fulfilment (e.g.
+ * `tools.0.fulfilment`). A steps-less flow (pure `output`, no connector call) is valid — a static
+ * resource/prompt or a pure-computation tool — but a flow still needs an `output`. Returns `null` (after
+ * recording an error) when the fulfilment is structurally invalid.
+ */
+function parseFulfilment(raw, prefix, schemasMap, errors) {
+    const hasUse = raw.use !== undefined;
+    const hasSteps = raw.steps !== undefined;
+    if (hasUse === hasSteps) {
+        errors.push({
+            code: 'invalid_fulfilment',
+            path: prefix,
+            message: 'fulfilment must have exactly one of "use" (single operation) or "steps" (flow)',
+        });
+        return null;
+    }
+    if (hasUse) {
+        if (raw.output !== undefined) {
+            errors.push({
+                code: 'invalid_fulfilment',
+                path: `${prefix}.output`,
+                message: '"output" is only valid in a flow ("steps")',
+            });
+        }
+        const op = parseOp(raw.use, raw.args, prefix, NO_STEPS, errors);
+        return op ? { kind: 'operation', op } : null;
+    }
+    // Flow.
+    const steps = raw.steps;
+    if (raw.args !== undefined) {
+        errors.push({
+            code: 'invalid_fulfilment',
+            path: `${prefix}.args`,
+            message: '"args" is only valid on a single operation or a step, not on a flow',
+        });
+    }
+    if (raw.output === undefined) {
+        errors.push({
+            code: 'invalid_fulfilment',
+            path: `${prefix}.output`,
+            message: 'a flow needs an "output" mapping',
+        });
+    }
+    // First pass: step ids + duplicate detection.
+    const stepIndexById = new Map();
+    steps.forEach((step, m) => {
+        if (stepIndexById.has(step.id)) {
+            errors.push({
+                code: 'duplicate_step_id',
+                path: `${prefix}.steps.${m}.id`,
+                message: `duplicate step id "${step.id}"`,
+            });
+        }
+        else {
+            stepIndexById.set(step.id, m);
+        }
+    });
+    // Second pass: parse each step with reference checks against earlier steps.
+    const structSteps = [];
+    steps.forEach((step, m) => {
+        const parsed = parseStep(step, `${prefix}.steps.${m}`, { stepIndexById, currentIdx: m }, schemasMap, errors);
+        if (parsed)
+            structSteps.push(parsed);
+    });
+    // Output mapping runs after all steps, so any declared step is in scope.
+    const output = parseExprMap(raw.output, `${prefix}.output`, { stepIndexById, currentIdx: null }, errors);
+    return { kind: 'flow', steps: structSteps, output };
+}
+/** Parse a single operation occurrence: its operation reference and its parsed argument expressions. */
+function parseOp(use, rawArgs, path, ctx, errors) {
+    const ref = parseOperationRef(use);
+    if (!ref) {
+        errors.push({
+            code: 'invalid_operation_ref',
+            path: `${path}.use`,
+            message: `invalid operation reference "${use}"; expected <connector>.<operation>`,
+        });
+        return null;
+    }
+    const args = parseExprMap(rawArgs, `${path}.args`, ctx, errors);
+    return { connectorAlias: ref.connector, operation: ref.operation, args, path };
+}
+/** Parse a flow step, enforcing exactly one verb (`use`/`map`/`elicit`) and parsing its expressions. */
+function parseStep(step, path, ctx, schemasMap, errors) {
+    const verbs = [step.use !== undefined, step.map !== undefined, step.elicit !== undefined].filter(Boolean).length;
+    if (verbs !== 1) {
+        errors.push({
+            code: 'invalid_fulfilment',
+            path,
+            message: 'a step must have exactly one of "use", "map", or "elicit"',
+        });
+        return null;
+    }
+    if (step.args !== undefined && step.use === undefined) {
+        errors.push({
+            code: 'invalid_fulfilment',
+            path: `${path}.args`,
+            message: '"args" is only valid on an operation ("use") step',
+        });
+    }
+    let cond;
+    if (step.if !== undefined) {
+        const parsed = parseCondition(step.if, `${path}.if`);
+        errors.push(...parsed.errors);
+        validateRefs(parsed.node, `${path}.if`, ctx, errors);
+        cond = parsed.node;
+    }
+    if (step.use !== undefined) {
+        const op = parseOp(step.use, step.args, path, ctx, errors);
+        if (!op)
+            return null;
+        return { id: step.id, kind: 'operation', ...(cond ? { cond } : {}), op };
+    }
+    if (step.map !== undefined) {
+        const value = parseExprMap(step.map, `${path}.map`, ctx, errors);
+        return { id: step.id, kind: 'map', ...(cond ? { cond } : {}), value };
+    }
+    // elicit: resolve its requested-input schema through the standard schema pipeline.
+    const resolved = resolveSchemaUses(step.elicit, schemasMap, `${path}.elicit`);
+    errors.push(...resolved.errors);
+    const ext = findExternalRef(resolved.schema, `${path}.elicit`);
+    if (ext)
+        errors.push(ext);
+    return { id: step.id, kind: 'elicit', ...(cond ? { cond } : {}), schema: resolved.schema };
+}
+/** Parse an `args`/`map`/`output` map of raw values into expression nodes and validate step refs. */
+function parseExprMap(raw, pathPrefix, ctx, errors) {
+    const out = {};
+    for (const [key, value] of Object.entries(raw ?? {})) {
+        const path = `${pathPrefix}.${key}`;
+        const { node, errors: e } = parseValue(value, path);
+        errors.push(...e);
+        validateRefs(node, path, ctx, errors);
+        out[key] = node;
+    }
+    return out;
+}
+/** Validate every `${steps.<id>}` reference in a node against declared step order. */
+function validateRefs(node, path, ctx, errors) {
+    for (const p of collectPaths(node)) {
+        if (p.root !== 'steps')
+            continue;
+        const first = p.segments[0];
+        if (first?.kind !== 'prop') {
+            errors.push({
+                code: 'unknown_step_ref',
+                path,
+                message: 'a "steps" reference must name a step (`${steps.<id>...}`)',
+            });
+            continue;
+        }
+        const id = first.name;
+        const idx = ctx.stepIndexById.get(id);
+        if (idx === undefined) {
+            errors.push({ code: 'unknown_step_ref', path, message: `unknown step "${id}"` });
+        }
+        else if (ctx.currentIdx !== null) {
+            if (idx === ctx.currentIdx) {
+                errors.push({ code: 'self_step_ref', path, message: `step "${id}" references itself` });
+            }
+            else if (idx > ctx.currentIdx) {
+                errors.push({
+                    code: 'forward_step_ref',
+                    path,
+                    message: `step "${id}" is referenced before it runs`,
+                });
+            }
+        }
+    }
+}
+// ─── Connector resolution + emit ───────────────────────────────────────────────
+/** Build the artifact fulfilment, resolving each operation occurrence against the catalog (if any). */
+function emitFulfilment(struct, catalog, declared, usedAliases, errors) {
+    if (struct.kind === 'operation') {
+        const operationRef = resolveOp(struct.op, catalog, declared, usedAliases, errors);
+        return { kind: 'operation', operationRef, args: struct.op.args };
+    }
+    const steps = struct.steps.map((s) => {
+        const cond = s.cond ? { if: s.cond } : {};
+        if (s.kind === 'operation') {
+            const operationRef = resolveOp(s.op, catalog, declared, usedAliases, errors);
+            return { id: s.id, kind: 'operation', ...cond, operationRef, args: s.op.args };
+        }
+        if (s.kind === 'map') {
+            return { id: s.id, kind: 'map', ...cond, value: s.value };
+        }
+        return { id: s.id, kind: 'elicit', ...cond, schema: withDialect(s.schema) };
+    });
+    return { kind: 'flow', steps, output: struct.output };
+}
+/**
+ * Resolve one operation occurrence against the catalog (docs/SPEC.md "Runtime Invariants"). Without a
+ * catalog, returns an unresolved reference (shape-only). Pushes a CompileError per failure.
+ */
+function resolveOp(op, catalog, declared, usedAliases, errors) {
+    const unresolved = {
+        connector: op.connectorAlias,
+        operation: op.operation,
+        resolved: false,
+    };
+    if (!catalog)
+        return unresolved;
+    usedAliases.add(op.connectorAlias);
+    const connectorRef = declared[op.connectorAlias];
+    if (!connectorRef) {
+        errors.push({
+            code: 'unknown_connector_alias',
+            path: `${op.path}.use`,
+            message: `connector alias "${op.connectorAlias}" is not declared in the "connectors" block`,
+            got: op.connectorAlias,
+            ...suggestionFields('unknown_connector_alias', op.connectorAlias, Object.keys(declared)),
+        });
+        return unresolved;
+    }
+    const connector = catalog.get(connectorRef.id, connectorRef.version);
+    if (!connector) {
+        errors.push({
+            code: 'connector_not_in_catalog',
+            path: `connectors.${op.connectorAlias}`,
+            message: `connector "${connectorRef.id}" version "${connectorRef.version}" is not in the catalog`,
+            expected: `a catalog entry for connector "${connectorRef.id}" version "${connectorRef.version}"`,
+            got: `${connectorRef.id}@${connectorRef.version}`,
+            docAnchor: docAnchorFor('connector_not_in_catalog'),
+        });
+        return unresolved;
+    }
+    const operation = connector.operations[op.operation];
+    if (!operation) {
+        errors.push({
+            code: 'unknown_operation',
+            path: `${op.path}.use`,
+            message: `operation "${op.operation}" does not exist on connector "${connector.id}" version "${connector.version}"`,
+            got: op.operation,
+            ...suggestionFields('unknown_operation', op.operation, Object.keys(connector.operations)),
+        });
+        return unresolved;
+    }
+    checkArgs(op.args, connector, op.operation, operation, `${op.path}.args`, errors);
+    return {
+        alias: op.connectorAlias,
+        connectorId: connector.id,
+        connectorVersion: connector.version,
+        operation: op.operation,
+        signatureHash: computeSignatureHash(op.operation, operation),
+        resolved: true,
+    };
+}
+/**
+ * Check parsed `args` against an operation's input signature (docs/SPEC.md line 165): reject argument
+ * keys the operation does not accept, require every required input field, and — where statically
+ * possible — reject a literal/template value whose primitive type does not match the field. Argument
+ * *path* expressions are not type-inferred here (deferred to a later slice).
+ */
+function checkArgs(args, connector, opName, operation, argsPathPrefix, errors) {
+    for (const [key, node] of Object.entries(args)) {
+        const field = operation.input[key];
+        if (!field) {
+            errors.push({
+                code: 'arg_mismatch',
+                path: `${argsPathPrefix}.${key}`,
+                message: `operation "${connector.id}.${opName}" does not accept argument "${key}"`,
+            });
+            continue;
+        }
+        const got = primitiveType(node);
+        if (got && !typeMatches(node, got, field.type)) {
+            errors.push({
+                code: 'arg_type_mismatch',
+                path: `${argsPathPrefix}.${key}`,
+                message: `argument "${key}" expects ${field.type} but got ${got}`,
+            });
+        }
+    }
+    for (const [field, spec] of Object.entries(operation.input)) {
+        if (spec.required && !(field in args)) {
+            errors.push({
+                code: 'arg_mismatch',
+                path: `${argsPathPrefix}.${field}`,
+                message: `operation "${connector.id}.${opName}" requires argument "${field}"`,
+            });
+        }
+    }
+}
+/** The statically-known primitive type of a value node, or `null` when it cannot be determined. */
+function primitiveType(node) {
+    if (node.kind === 'template')
+        return 'string';
+    if (node.kind === 'literal') {
+        if (typeof node.value === 'string')
+            return 'string';
+        if (typeof node.value === 'number')
+            return 'number';
+        if (typeof node.value === 'boolean')
+            return 'boolean';
+    }
+    return null; // path (deferred inference) or literal null (nullable)
+}
+/** Whether a known primitive type satisfies a JSON Schema field type. */
+function typeMatches(node, got, fieldType) {
+    if (got === 'number') {
+        if (fieldType === 'integer') {
+            return (node.kind === 'literal' && typeof node.value === 'number' && Number.isInteger(node.value));
+        }
+        return fieldType === 'number';
+    }
+    return got === fieldType;
+}
+/** Map a Zod issue to a CompileError, deriving a stable error code from its path. */
+function translateIssue(issue) {
+    const path = issue.path.map(String).join('.');
+    const leaf = issue.path.length > 0 ? String(issue.path[issue.path.length - 1]) : '';
+    let code = 'invalid_shape';
+    if (path === 'manifestVersion')
+        code = 'unsupported_manifest_version';
+    else if (leaf === 'name')
+        code = 'invalid_name';
+    return { code, path, message: issue.message };
+}
+/** Ensure an emitted tool schema advertises the JSON Schema 2020-12 dialect. */
+function withDialect(schema) {
+    if (typeof schema.$schema === 'string')
+        return schema;
+    return { $schema: JSON_SCHEMA_2020_12, ...schema };
+}
+/** The canonical `ui://` URI for a widget: `ui://<server>/<widget>` (a fixed, non-template resource). */
+function widgetUri(serverName, widgetName) {
+    return `ui://${serverName}/${widgetName}`;
+}
+/**
+ * The widget UI resource's `_meta.ui` value — its host-enforced CSP/permission metadata — or `undefined`
+ * when the widget declares neither, so a metadata-free widget stays `_meta`-free on the wire.
+ */
+function resourceUiMeta(widget) {
+    const csp = widget.csp;
+    const hasCsp = csp !== undefined && Object.values(csp).some((v) => v !== undefined);
+    const permissions = widget.permissions;
+    const hasPermissions = permissions !== undefined && Object.keys(permissions).length > 0;
+    if (!hasCsp && !hasPermissions)
+        return undefined;
+    return {
+        ...(csp && hasCsp ? { csp } : {}),
+        ...(permissions && hasPermissions ? { permissions } : {}),
+    };
+}
+/**
+ * Recursively scan an authored JSON Schema for an external `$ref` (any `$ref` that is not a local
+ * `#`-fragment). External refs are rejected per docs/SPEC.md "Schemas". Returns the first one found.
+ */
+function findExternalRef(value, path) {
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            const found = findExternalRef(value[i], `${path}.${i}`);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    if (value !== null && typeof value === 'object') {
+        for (const [key, val] of Object.entries(value)) {
+            if (key === '$ref' && typeof val === 'string' && !val.startsWith('#')) {
+                return {
+                    code: 'external_ref',
+                    path: `${path}.$ref`,
+                    message: `external $ref "${val}" is not allowed; use $use or a local "#/" reference`,
+                };
+            }
+            const found = findExternalRef(val, `${path}.${key}`);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=compile.js.map