@vurb/core 3.2.0

package/dist/edge-stub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-stub.js","sourceRoot":"","sources":["../src/edge-stub.ts"],"names":[],"mappings":"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"}

package/dist/exposition/ExpositionCompiler.d.ts

@@ -0,0 +1,66 @@
+/**
+ * ExpositionCompiler — Topology Compiler Engine
+ *
+ * Pure-function transformation module responsible for projecting
+ * the tool registry's abstract definitions onto the MCP protocol
+ * wire format based on the configured Exposition Strategy.
+ *
+ * - **flat**: Deterministically expands each action into an independent
+ *   atomic MCP tool with isolated schema, description, and annotations.
+ *
+ * - **grouped**: Passthrough — yields the grouped tool definition unmodified.
+ *
+ * Also emits an O(1) dispatch map for constant-time request proxying
+ * during execution.
+ *
+ * Pure-function module: no state, no side effects.
+ *
+ * @module
+ */
+import { type Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
+import { type ToolBuilder } from '../core/types.js';
+import { type ToolExposition } from './types.js';
+/**
+ * Routing entry for the O(1) dispatch map.
+ *
+ * Maps a flat tool name (e.g. `projects_list`) back to its
+ * originating builder, the action key, and the discriminator field.
+ */
+export interface FlatRoute<TContext> {
+    /** The originating grouped builder */
+    readonly builder: ToolBuilder<TContext>;
+    /** Action key to inject as discriminator value (e.g. `"list"`) */
+    readonly actionKey: string;
+    /** Discriminator field name (e.g. `"action"`) */
+    readonly discriminator: string;
+}
+/**
+ * Result of the exposition compilation phase.
+ *
+ * Contains the protocol-facing tool definitions and the routing map
+ * for incoming flat tool calls.
+ */
+export interface ExpositionResult<TContext> {
+    /** MCP Tool definitions to expose in `tools/list` */
+    readonly tools: McpTool[];
+    /** O(1) dispatch map: flat tool name → route info */
+    readonly routingMap: Map<string, FlatRoute<TContext>>;
+    /** Whether flat mode is active (controls callHandler behavior) */
+    readonly isFlat: boolean;
+}
+/**
+ * Compile tool builders into the protocol-facing exposition format.
+ *
+ * @param builders - Iterable of registered tool builders
+ * @param exposition - Exposition strategy ('flat' or 'grouped')
+ * @param separator - Action separator for flat naming (default: '_')
+ * @returns Compiled tools and routing map
+ */
+/**
+ * Optional warning callback for diagnostics.
+ * Replaces console.warn to avoid polluting stdout/stderr in production.
+ * @see Bug #131
+ */
+export type ExpositionWarnFn = (message: string) => void;
+export declare function compileExposition<TContext>(builders: Iterable<ToolBuilder<TContext>>, exposition?: ToolExposition, separator?: string, onWarn?: ExpositionWarnFn): ExpositionResult<TContext>;
+//# sourceMappingURL=ExpositionCompiler.d.ts.map

package/dist/exposition/ExpositionCompiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpositionCompiler.d.ts","sourceRoot":"","sources":["../../src/exposition/ExpositionCompiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,KAAK,IAAI,IAAI,OAAO,EAAE,MAAM,oCAAoC,CAAC;AAG1E,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEzE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD;;;;;GAKG;AACH,MAAM,WAAW,SAAS,CAAC,QAAQ;IAC/B,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IACxC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAAC,QAAQ;IACtC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtD,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC5B;AAID;;;;;;;GAOG;AACH;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAEzD,wBAAgB,iBAAiB,CAAC,QAAQ,EACtC,QAAQ,EAAE,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,EACzC,UAAU,GAAE,cAAuB,EACnC,SAAS,GAAE,MAAY,EACvB,MAAM,CAAC,EAAE,gBAAgB,GAC1B,gBAAgB,CAAC,QAAQ,CAAC,CAK5B"}

package/dist/exposition/ExpositionCompiler.js

@@ -0,0 +1,279 @@
+/**
+ * ExpositionCompiler — Topology Compiler Engine
+ *
+ * Pure-function transformation module responsible for projecting
+ * the tool registry's abstract definitions onto the MCP protocol
+ * wire format based on the configured Exposition Strategy.
+ *
+ * - **flat**: Deterministically expands each action into an independent
+ *   atomic MCP tool with isolated schema, description, and annotations.
+ *
+ * - **grouped**: Passthrough — yields the grouped tool definition unmodified.
+ *
+ * Also emits an O(1) dispatch map for constant-time request proxying
+ * during execution.
+ *
+ * Pure-function module: no state, no side effects.
+ *
+ * @module
+ */
+import {} from '@modelcontextprotocol/sdk/types.js';
+import {} from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import {} from '../core/types.js';
+import { isPresenter } from '../presenter/Presenter.js';
+import {} from './types.js';
+export function compileExposition(builders, exposition = 'flat', separator = '_', onWarn) {
+    if (exposition === 'grouped') {
+        return compileGrouped(builders);
+    }
+    return compileFlat(builders, separator, onWarn);
+}
+// ── Flat Strategy ────────────────────────────────────────
+/**
+ * Flat strategy: expand each action into an independent atomic MCP tool.
+ *
+ * Iterates over each builder, extracts per-action metadata, and
+ * synthesizes one McpTool per action with:
+ * - Deterministic name: `{toolName}{separator}{actionKey}`
+ * - Isolated schema (action-specific + common, no discriminator)
+ * - Isolated annotations (readOnlyHint, destructiveHint, idempotentHint)
+ * - Per-action description
+ */
+function compileFlat(builders, separator, onWarn) {
+    const tools = [];
+    const routingMap = new Map();
+    for (const builder of builders) {
+        // Ensure the grouped definition is compiled (caches internally)
+        builder.buildToolDefinition();
+        // Use AST reflection interfaces to access internal structures
+        const actions = getBuilderActions(builder);
+        const discriminator = getBuilderDiscriminator(builder);
+        const commonSchema = getBuilderCommonSchema(builder);
+        const toolName = builder.getName();
+        const selectEnabled = getBuilderSelectEnabled(builder);
+        if (!actions || actions.length === 0) {
+            // Fallback: builder has no reflection — pass through as grouped
+            tools.push(builder.buildToolDefinition());
+            continue;
+        }
+        const isSingleAction = actions.length === 1;
+        for (const action of actions) {
+            // Single-action builders with 'default' key use bare tool name
+            // (no _default suffix). This covers standalone f.query/f.mutation/f.action
+            // tools created via the Fluent API which always use 'default' as the key.
+            // Multi-action builders and named single actions retain toolName_actionKey.
+            const flatName = (isSingleAction && action.key === 'default')
+                ? toolName
+                : `${toolName}${separator}${action.key}`;
+            // ── Schema Purification ──────────────────────────
+            const inputSchema = buildAtomicSchema(action, commonSchema, selectEnabled, onWarn);
+            // ── Boundary Isolation (Annotations) ─────────────
+            const annotations = buildAtomicAnnotations(action);
+            // ── Description ──────────────────────────────────
+            const description = buildAtomicDescription(action, toolName);
+            const tool = {
+                name: flatName,
+                description,
+                inputSchema,
+            };
+            if (Object.keys(annotations).length > 0) {
+                Object.defineProperty(tool, 'annotations', {
+                    value: annotations,
+                    enumerable: true,
+                });
+            }
+            tools.push(tool);
+            // ── O(1) Dispatch Map Entry ──────────────────────
+            // Detect flat name collisions — two builders
+            // producing the same flat name would silently overwrite
+            // the routing entry, making the first tool inaccessible.
+            if (routingMap.has(flatName)) {
+                const existing = routingMap.get(flatName);
+                const msg = `[Vurb] Flat tool name collision: "${flatName}" is produced by both ` +
+                    `"${existing.builder.getName()}" (action "${existing.actionKey}") and ` +
+                    `"${toolName}" (action "${action.key}"). ` +
+                    `Rename one of the tools or use a different action separator.`;
+                if (onWarn) {
+                    onWarn(msg);
+                }
+                else {
+                    throw new Error(msg);
+                }
+            }
+            routingMap.set(flatName, {
+                builder,
+                actionKey: action.key,
+                discriminator,
+            });
+        }
+    }
+    return { tools, routingMap, isFlat: true };
+}
+// ── Grouped Strategy ─────────────────────────────────────
+/**
+ * Grouped strategy: passthrough — yields the grouped tool definition unmodified.
+ * This preserves byte-for-byte identical protocol schema compared to pre-exposition behavior.
+ */
+function compileGrouped(builders) {
+    const tools = [];
+    for (const builder of builders) {
+        tools.push(builder.buildToolDefinition());
+    }
+    return { tools, routingMap: new Map(), isFlat: false };
+}
+// ── Atomic Builders (Internal) ───────────────────────────
+/**
+ * Build an isolated JSON Schema for a single action.
+ *
+ * Merges the action's specific schema with the common schema,
+ * applies omitCommon fields, and strips the discriminator.
+ * Result is a clean object schema without the union wrapper.
+ */
+function buildAtomicSchema(action, commonSchema, selectEnabled = false, onWarn) {
+    const properties = {};
+    const required = [];
+    // ── Merge common schema fields ───────────────────────
+    if (commonSchema) {
+        const omitSet = action.omitCommonFields
+            ? new Set(action.omitCommonFields)
+            : undefined;
+        const jsonSchema = zodToJsonSchema(commonSchema, { target: 'jsonSchema7' });
+        for (const [key, value] of Object.entries(jsonSchema.properties ?? {})) {
+            if (omitSet?.has(key))
+                continue;
+            properties[key] = value;
+        }
+        for (const key of jsonSchema.required ?? []) {
+            if (omitSet?.has(key))
+                continue;
+            if (key in properties) {
+                required.push(key);
+            }
+        }
+    }
+    // ── Merge action-specific schema fields ──────────────
+    if (action.schema) {
+        const jsonSchema = zodToJsonSchema(action.schema, { target: 'jsonSchema7' });
+        for (const [key, value] of Object.entries(jsonSchema.properties ?? {})) {
+            // Bug #54: Warn when action schema overwrites a common schema field
+            // Bug #131: Route through onWarn callback instead of console.warn
+            if (key in properties && onWarn) {
+                onWarn(`[Vurb] Action schema field '${key}' overwrites common schema field with the same name. ` +
+                    `Use omitCommonFields to exclude the common field, or rename the action field.`);
+            }
+            properties[key] = value;
+        }
+        for (const key of jsonSchema.required ?? []) {
+            if (key in properties && !required.includes(key)) {
+                required.push(key);
+            }
+        }
+    }
+    // ── _select Reflection (opt-in) ──────────────────────
+    if (selectEnabled && action.returns && isPresenter(action.returns)) {
+        const schemaKeys = action.returns.getSchemaKeys();
+        if (schemaKeys.length > 0) {
+            properties['_select'] = {
+                type: 'array',
+                description: '⚡ Context optimization: select only the response fields you need. Omit to receive all fields.',
+                items: {
+                    type: 'string',
+                    enum: [...schemaKeys].sort(),
+                },
+            };
+        }
+    }
+    return {
+        type: 'object',
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+    };
+}
+/**
+ * Build isolated annotations for a single action.
+ *
+ * Each action gets its own `readOnlyHint`, `destructiveHint`,
+ * and `idempotentHint` — no privilege bleed across actions.
+ */
+function buildAtomicAnnotations(action) {
+    const annotations = {};
+    if (action.readOnly === true) {
+        // Action is read-only → never destructive.
+        // readOnlyHint default is false, so we must explicitly signal true.
+        // destructiveHint default is true (MCP assumes dangerous), so we must
+        // explicitly signal false to prevent unnecessary confirmation dialogs.
+        annotations['readOnlyHint'] = true;
+        annotations['destructiveHint'] = false;
+    }
+    else if (action.destructive === true) {
+        // Action is destructive → matches MCP's conservative default.
+        // We still emit explicitly for clarity in tools/list responses.
+        annotations['destructiveHint'] = true;
+    }
+    else {
+        // Neither read-only nor destructive.
+        // MCP spec defaults destructiveHint to true (assume dangerous).
+        // We MUST emit false to override this — otherwise clients like
+        // Claude Desktop or Cursor will show unnecessary safety warnings.
+        annotations['destructiveHint'] = false;
+    }
+    if (action.idempotent === true) {
+        annotations['idempotentHint'] = true;
+    }
+    return annotations;
+}
+/**
+ * Build a human-readable description for a single atomic action.
+ */
+function buildAtomicDescription(action, toolName) {
+    const parts = [];
+    if (action.description) {
+        parts.push(action.description);
+    }
+    else {
+        // Generate a default description from the tool and action name
+        const actionLabel = action.groupName
+            ? `${action.groupName}.${action.actionName}`
+            : action.actionName;
+        parts.push(`${toolName} → ${actionLabel}`);
+    }
+    // Append safety flags for LLM awareness
+    if (action.destructive) {
+        parts.push('[DESTRUCTIVE]');
+    }
+    if (action.readOnly) {
+        parts.push('[READ-ONLY]');
+    }
+    return parts.join(' ');
+}
+// ── AST Reflection Helpers ───────────────────────────────
+/**
+ * Extract actions from a builder using optional AST reflection interface.
+ * Returns undefined if the builder doesn't implement `getActions()`.
+ */
+function getBuilderActions(builder) {
+    return builder.getActions?.();
+}
+/**
+ * Extract discriminator field name from a builder.
+ * Defaults to 'action' if the builder doesn't implement `getDiscriminator()`.
+ */
+function getBuilderDiscriminator(builder) {
+    return builder.getDiscriminator?.() ?? 'action';
+}
+/**
+ * Extract common schema from a builder.
+ * Returns undefined if the builder doesn't implement `getCommonSchema()`.
+ */
+function getBuilderCommonSchema(builder) {
+    return builder.getCommonSchema?.();
+}
+/**
+ * Check if select reflection is enabled on a builder.
+ * Returns false if the builder doesn't implement `getSelectEnabled()`.
+ */
+function getBuilderSelectEnabled(builder) {
+    return builder.getSelectEnabled?.() ?? false;
+}
+//# sourceMappingURL=ExpositionCompiler.js.map

package/dist/exposition/ExpositionCompiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpositionCompiler.js","sourceRoot":"","sources":["../../src/exposition/ExpositionCompiler.ts"],"names":[],"mappings":"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"}

package/dist/exposition/index.d.ts

@@ -0,0 +1,4 @@
+/** Exposition Strategy — Barrel Export */
+export type { ToolExposition, ExpositionConfig } from './types.js';
+export { compileExposition, type FlatRoute, type ExpositionResult } from './ExpositionCompiler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/exposition/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/exposition/index.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/exposition/index.js

@@ -0,0 +1,2 @@
+export { compileExposition } from './ExpositionCompiler.js';
+//# sourceMappingURL=index.js.map

package/dist/exposition/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/exposition/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAyC,MAAM,yBAAyB,CAAC"}

package/dist/exposition/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * ExpositionTypes — Tool Exposition Strategy Contracts
+ *
+ * Defines the configuration interfaces for the Topology Compiler Pattern.
+ * Controls how the framework projects grouped tool definitions onto the
+ * MCP protocol wire format.
+ *
+ * @module
+ */
+/**
+ * Tool exposition strategy.
+ *
+ * - `'flat'` — Each action is exposed as an independent atomic MCP tool.
+ *   Guarantees privilege isolation, deterministic routing, and granular UI.
+ *   **This is the default.**
+ *
+ * - `'grouped'` — All actions within a builder are merged into a single
+ *   MCP tool with a discriminated-union schema. Optimizes context-window
+ *   token economy at the cost of UI granularity.
+ *
+ * @see {@link ExpositionConfig} for full configuration
+ */
+export type ToolExposition = 'flat' | 'grouped';
+/**
+ * Configuration for the Topology Compiler's exposition strategy.
+ *
+ * @example
+ * ```typescript
+ * registry.attachToServer(server, {
+ *     contextFactory: createContext,
+ *     toolExposition: 'flat',      // Each action = 1 MCP tool
+ *     actionSeparator: '_',        // projects_list, projects_create
+ * });
+ * ```
+ */
+export interface ExpositionConfig {
+    /**
+     * Exposition strategy for projecting grouped tools onto the MCP wire format.
+     *
+     * @default 'flat'
+     */
+    toolExposition?: ToolExposition;
+    /**
+     * Delimiter for deterministic naming interpolation in flat mode.
+     * Used to join `{toolName}{separator}{actionKey}`.
+     *
+     * @default '_'
+     *
+     * @example
+     * ```typescript
+     * // With separator '_': projects_list, projects_create
+     * // With separator '.': projects.list, projects.create
+     * // With separator '-': projects-list, projects-create
+     * ```
+     */
+    actionSeparator?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/exposition/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/exposition/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;OAIG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B"}

package/dist/exposition/types.js

@@ -0,0 +1,11 @@
+/**
+ * ExpositionTypes — Tool Exposition Strategy Contracts
+ *
+ * Defines the configuration interfaces for the Topology Compiler Pattern.
+ * Controls how the framework projects grouped tool definitions onto the
+ * MCP protocol wire format.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/exposition/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/exposition/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}