@vinkius-core/mcp-fusion 2.9.0 → 2.12.0

package/dist/core/builder/FluentToolBuilder.js

@@ -0,0 +1,525 @@
+/**
+ * FluentToolBuilder — Type-Chaining Builder for Semantic Verb Tools
+ *
+ * The core builder behind `f.query()`, `f.mutation()`, and `f.action()`.
+ * Uses TypeScript generic accumulation so that each fluent step narrows
+ * the types — the IDE "magically" knows the exact shape of `input` and
+ * `ctx` inside `.handle()` without any manual Interface declaration.
+ *
+ * @example
+ * ```typescript
+ * const f = initFusion<AppContext>();
+ *
+ * const listUsers = f.query('users.list')
+ *     .describe('List users from the database')
+ *     .withNumber('limit', 'Max results to return')
+ *     .withOptionalEnum('status', ['active', 'inactive'], 'Filter by status')
+ *     .returns(UserPresenter)
+ *     .handle(async (input, ctx) => {
+ *         return ctx.db.user.findMany({ take: input.limit });
+ *     });
+ * ```
+ *
+ * @see {@link FluentRouter} for prefix grouping
+ * @see {@link initFusion} for the factory that creates these builders
+ *
+ * @module
+ */
+import { z } from 'zod';
+import { GroupedToolBuilder } from './GroupedToolBuilder.js';
+import {} from '../types.js';
+import { success } from '../response.js';
+import {} from '../../presenter/Presenter.js';
+import {} from '../execution/ConcurrencyGuard.js';
+/** Defaults for `f.query()` — read-only, no side effects */
+export const QUERY_DEFAULTS = { readOnly: true };
+/** Defaults for `f.mutation()` — destructive, irreversible */
+export const MUTATION_DEFAULTS = { destructive: true };
+/** Defaults for `f.action()` — neutral, no assumptions */
+export const ACTION_DEFAULTS = {};
+// ── Array Item Type Resolution ───────────────────────────
+/** Resolve Zod type from array item type string */
+function resolveArrayItemType(itemType) {
+    switch (itemType) {
+        case 'string': return z.string();
+        case 'number': return z.number();
+        case 'boolean': return z.boolean();
+    }
+}
+// ── FluentToolBuilder ────────────────────────────────────
+/**
+ * Fluent builder that accumulates types at each step.
+ *
+ * @typeParam TContext - Base application context (from `initFusion<TContext>()`)
+ * @typeParam TInput - Accumulated input type (built by `with*()` methods)
+ * @typeParam TCtx - Accumulated context type (enriched by `.use()`)
+ */
+export class FluentToolBuilder {
+    /** @internal */ _name;
+    /** @internal */ _description;
+    /** @internal */ _instructions;
+    /** @internal */ _inputSchema;
+    /** @internal */ _withParams = {};
+    /** @internal */ _tags = [];
+    /** @internal */ _middlewares = [];
+    /** @internal */ _returns;
+    /** @internal */ _semanticDefaults;
+    /** @internal */ _readOnly;
+    /** @internal */ _destructive;
+    /** @internal */ _idempotent;
+    /** @internal */ _toonMode = false;
+    /** @internal */ _annotations;
+    /** @internal */ _invalidatesPatterns = [];
+    /** @internal */ _cacheControl;
+    /** @internal */ _concurrency;
+    /** @internal */ _egressMaxBytes;
+    /**
+     * @param name - Tool name in `domain.action` format (e.g. `'users.list'`)
+     * @param defaults - Semantic defaults from the verb (`query`, `mutation`, `action`)
+     */
+    constructor(name, defaults = {}) {
+        this._name = name;
+        this._semanticDefaults = defaults;
+    }
+    // ── Configuration (fluent, each returns narrowed type) ──
+    /**
+     * Set the tool description shown to the LLM.
+     *
+     * @param text - Human-readable description
+     * @returns `this` for chaining
+     */
+    describe(text) {
+        this._description = text;
+        return this;
+    }
+    /**
+     * Set AI-First instructions — injected as system-level guidance in the tool description.
+     *
+     * This is **Prompt Engineering embedded in the framework**. The instructions
+     * tell the LLM WHEN and HOW to use this tool, reducing hallucination.
+     *
+     * @param text - System prompt for the tool
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * f.query('docs.search')
+     *     .describe('Search internal documentation')
+     *     .instructions('Use ONLY when the user asks about internal policies.')
+     *     .withString('query', 'Search term')
+     *     .handle(async (input) => { ... });
+     * ```
+     */
+    instructions(text) {
+        this._instructions = text;
+        return this;
+    }
+    // ── Parameter Declaration (with* methods) ────────────
+    /**
+     * Add a required string parameter.
+     *
+     * @param name - Parameter name
+     * @param description - Human-readable description for the LLM
+     * @returns Builder with narrowed `TInput` type
+     *
+     * @example
+     * ```typescript
+     * f.query('projects.get')
+     *     .withString('project_id', 'The project ID to retrieve')
+     *     .handle(async (input) => { ... });
+     * // input.project_id: string ✅
+     * ```
+     */
+    withString(name, description) {
+        this._withParams[name] = description ? z.string().describe(description) : z.string();
+        return this;
+    }
+    /**
+     * Add an optional string parameter.
+     *
+     * @param name - Parameter name
+     * @param description - Human-readable description for the LLM
+     * @returns Builder with narrowed `TInput` type
+     */
+    withOptionalString(name, description) {
+        const base = description ? z.string().describe(description) : z.string();
+        this._withParams[name] = base.optional();
+        return this;
+    }
+    /**
+     * Add a required number parameter.
+     *
+     * @param name - Parameter name
+     * @param description - Human-readable description for the LLM
+     * @returns Builder with narrowed `TInput` type
+     */
+    withNumber(name, description) {
+        this._withParams[name] = description ? z.number().describe(description) : z.number();
+        return this;
+    }
+    /**
+     * Add an optional number parameter.
+     *
+     * @param name - Parameter name
+     * @param description - Human-readable description for the LLM
+     * @returns Builder with narrowed `TInput` type
+     */
+    withOptionalNumber(name, description) {
+        const base = description ? z.number().describe(description) : z.number();
+        this._withParams[name] = base.optional();
+        return this;
+    }
+    /**
+     * Add a required boolean parameter.
+     *
+     * @param name - Parameter name
+     * @param description - Human-readable description for the LLM
+     * @returns Builder with narrowed `TInput` type
+     */
+    withBoolean(name, description) {
+        this._withParams[name] = description ? z.boolean().describe(description) : z.boolean();
+        return this;
+    }
+    /**
+     * Add an optional boolean parameter.
+     *
+     * @param name - Parameter name
+     * @param description - Human-readable description for the LLM
+     * @returns Builder with narrowed `TInput` type
+     */
+    withOptionalBoolean(name, description) {
+        const base = description ? z.boolean().describe(description) : z.boolean();
+        this._withParams[name] = base.optional();
+        return this;
+    }
+    /**
+     * Add a required enum parameter.
+     *
+     * @param name - Parameter name
+     * @param values - Allowed enum values
+     * @param description - Human-readable description for the LLM
+     * @returns Builder with narrowed `TInput` type
+     *
+     * @example
+     * ```typescript
+     * f.query('invoices.list')
+     *     .withEnum('status', ['draft', 'sent', 'paid'], 'Filter by status')
+     *     .handle(async (input) => { ... });
+     * // input.status: 'draft' | 'sent' | 'paid' ✅
+     * ```
+     */
+    withEnum(name, values, description) {
+        const schema = z.enum(values);
+        this._withParams[name] = description ? schema.describe(description) : schema;
+        return this;
+    }
+    /**
+     * Add an optional enum parameter.
+     *
+     * @param name - Parameter name
+     * @param values - Allowed enum values
+     * @param description - Human-readable description for the LLM
+     * @returns Builder with narrowed `TInput` type
+     */
+    withOptionalEnum(name, values, description) {
+        const schema = z.enum(values);
+        this._withParams[name] = description ? schema.describe(description).optional() : schema.optional();
+        return this;
+    }
+    /**
+     * Add a required array parameter.
+     *
+     * @param name - Parameter name
+     * @param itemType - Type of array items (`'string'`, `'number'`, `'boolean'`)
+     * @param description - Human-readable description for the LLM
+     * @returns Builder with narrowed `TInput` type
+     *
+     * @example
+     * ```typescript
+     * f.mutation('tasks.tag')
+     *     .withString('task_id', 'The task to tag')
+     *     .withArray('tags', 'string', 'Tags to apply')
+     *     .handle(async (input) => { ... });
+     * // input.tags: string[] ✅
+     * ```
+     */
+    withArray(name, itemType, description) {
+        const schema = z.array(resolveArrayItemType(itemType));
+        this._withParams[name] = description ? schema.describe(description) : schema;
+        return this;
+    }
+    /**
+     * Add an optional array parameter.
+     *
+     * @param name - Parameter name
+     * @param itemType - Type of array items (`'string'`, `'number'`, `'boolean'`)
+     * @param description - Human-readable description for the LLM
+     * @returns Builder with narrowed `TInput` type
+     */
+    withOptionalArray(name, itemType, description) {
+        const schema = z.array(resolveArrayItemType(itemType));
+        this._withParams[name] = description ? schema.describe(description).optional() : schema.optional();
+        return this;
+    }
+    // ── Middleware ────────────────────────────────────────
+    /**
+     * Add context-derivation middleware (tRPC-style).
+     *
+     * The middleware receives `{ ctx, next }` and can enrich the context
+     * for downstream steps. The TypeScript type of `ctx` in `.handle()`
+     * is automatically extended with the derived properties.
+     *
+     * @param mw - Middleware that returns enriched context
+     * @returns A **new type** of `FluentToolBuilder` with `TCtx` enriched
+     *
+     * @example
+     * ```typescript
+     * f.mutation('users.delete')
+     *     .use(async ({ ctx, next }) => {
+     *         const admin = await requireAdmin(ctx.headers);
+     *         return next({ ...ctx, adminUser: admin });
+     *     })
+     *     .withString('id', 'User ID to delete')
+     *     .handle(async (input, ctx) => {
+     *         // ctx.adminUser is typed! Zero casting.
+     *         ctx.logger.info(`${ctx.adminUser.name} deleting ${input.id}`);
+     *     });
+     * ```
+     */
+    use(mw) {
+        // Convert the fluent middleware signature to the standard MiddlewareFn
+        const standardMw = async (ctx, args, next) => {
+            const wrappedNext = async (enrichedCtx) => {
+                // Merge enriched properties into context
+                Object.assign(ctx, enrichedCtx);
+                return next();
+            };
+            return mw({ ctx: ctx, next: wrappedNext });
+        };
+        this._middlewares.push(standardMw);
+        return this;
+    }
+    /**
+     * Set the MVA Presenter for automatic response formatting.
+     *
+     * When a Presenter is attached, the handler can return raw data
+     * and the framework pipes it through schema validation, system rules,
+     * and UI block generation.
+     *
+     * @param presenter - A Presenter instance
+     * @returns `this` for chaining
+     */
+    returns(presenter) {
+        this._returns = presenter;
+        return this;
+    }
+    /**
+     * Add capability tags for selective tool exposure.
+     *
+     * Tags are accumulated — calling `.tags()` multiple times
+     * (or inheriting from a router) appends rather than replaces.
+     *
+     * @param tags - Tag strings for filtering
+     * @returns `this` for chaining
+     */
+    tags(...tags) {
+        this._tags.push(...tags);
+        return this;
+    }
+    // ── Semantic Overrides ───────────────────────────────
+    /** Override: mark this tool as read-only (no side effects) */
+    readOnly() {
+        this._readOnly = true;
+        return this;
+    }
+    /** Override: mark this tool as destructive (irreversible) */
+    destructive() {
+        this._destructive = true;
+        return this;
+    }
+    /** Override: mark this tool as idempotent (safe to retry) */
+    idempotent() {
+        this._idempotent = true;
+        return this;
+    }
+    /**
+     * Enable TOON-formatted descriptions for token optimization.
+     *
+     * @returns `this` for chaining
+     */
+    toonDescription() {
+        this._toonMode = true;
+        return this;
+    }
+    /**
+     * Set MCP tool annotations.
+     *
+     * @param a - Annotation key-value pairs
+     * @returns `this` for chaining
+     */
+    annotations(a) {
+        this._annotations = a;
+        return this;
+    }
+    // ── State Sync (Fluent) ──────────────────────────────
+    /**
+     * Declare glob patterns invalidated when this tool succeeds.
+     *
+     * @param patterns - Glob patterns (e.g. `'sprints.*'`, `'tasks.*'`)
+     * @returns `this` for chaining
+     */
+    invalidates(...patterns) {
+        this._invalidatesPatterns.push(...patterns);
+        return this;
+    }
+    /**
+     * Mark this tool's data as immutable (safe to cache forever).
+     *
+     * @returns `this` for chaining
+     */
+    cached() {
+        this._cacheControl = 'immutable';
+        return this;
+    }
+    /**
+     * Mark this tool's data as volatile (never cache).
+     *
+     * @returns `this` for chaining
+     */
+    stale() {
+        this._cacheControl = 'no-store';
+        return this;
+    }
+    // ── Runtime Guards (Fluent) ──────────────────────────
+    /**
+     * Set concurrency limits for this tool (Semaphore + Queue pattern).
+     *
+     * @param config - Concurrency configuration
+     * @returns `this` for chaining
+     */
+    concurrency(config) {
+        this._concurrency = config;
+        return this;
+    }
+    /**
+     * Set maximum payload size for tool responses (Egress Guard).
+     *
+     * @param bytes - Maximum payload size in bytes
+     * @returns `this` for chaining
+     */
+    egress(bytes) {
+        this._egressMaxBytes = bytes;
+        return this;
+    }
+    // ── Terminal: handle() ───────────────────────────────
+    /**
+     * Set the handler and build the tool — the terminal step.
+     *
+     * The handler receives `(input, ctx)` with fully typed `TInput` and `TCtx`.
+     * **Implicit `success()` wrapping**: if the handler returns raw data
+     * (not a `ToolResponse`), the framework wraps it with `success()`.
+     *
+     * @param handler - Async function receiving typed `(input, ctx)`
+     * @returns A `GroupedToolBuilder` ready for registration
+     *
+     * @example
+     * ```typescript
+     * const getProject = f.query('projects.get')
+     *     .describe('Get a project by ID')
+     *     .withString('project_id', 'The exact project ID')
+     *     .handle(async (input, ctx) => {
+     *         return await ctx.db.projects.findUnique({ where: { id: input.project_id } });
+     *     });
+     * ```
+     */
+    handle(handler) {
+        return this._build(handler);
+    }
+    /**
+     * Alias for `.handle()` — for backward compatibility.
+     * @internal
+     */
+    resolve(handler) {
+        // Adapt { input, ctx } signature to (input, ctx)
+        return this._build((input, ctx) => handler({ input, ctx }));
+    }
+    // ── Internal Build ───────────────────────────────────
+    /** @internal */
+    _build(handler) {
+        // Build accumulated with* params into ZodObject
+        if (Object.keys(this._withParams).length > 0) {
+            this._inputSchema = z.object(this._withParams);
+        }
+        // Parse name: 'domain.action' → tool='domain', action='action'
+        const dotIndex = this._name.indexOf('.');
+        const toolName = dotIndex > 0 ? this._name.slice(0, dotIndex) : this._name;
+        const actionName = dotIndex > 0 ? this._name.slice(dotIndex + 1) : 'default';
+        // Compile description: instructions + description
+        const descParts = [];
+        if (this._instructions) {
+            descParts.push(`[INSTRUCTIONS] ${this._instructions}`);
+        }
+        if (this._description) {
+            descParts.push(this._description);
+        }
+        const compiledDescription = descParts.length > 0 ? descParts.join('\n\n') : undefined;
+        // Resolve semantic defaults + overrides
+        const readOnly = this._readOnly ?? this._semanticDefaults.readOnly;
+        const destructive = this._destructive ?? this._semanticDefaults.destructive;
+        const idempotent = this._idempotent ?? this._semanticDefaults.idempotent;
+        // Wrap handler: (input, ctx) → (ctx, args)
+        const resolvedHandler = handler;
+        const wrappedHandler = async (ctx, args) => {
+            const result = await resolvedHandler(args, ctx);
+            // Auto-wrap non-ToolResponse results (implicit success)
+            if (typeof result === 'object' &&
+                result !== null &&
+                'content' in result &&
+                Array.isArray(result.content)) {
+                return result;
+            }
+            // Implicit success() — the dev just returns raw data!
+            return success(result);
+        };
+        // Build via GroupedToolBuilder for consistency with existing pipeline
+        const builder = new GroupedToolBuilder(toolName);
+        if (compiledDescription)
+            builder.description(compiledDescription);
+        if (this._tags.length > 0)
+            builder.tags(...this._tags);
+        if (this._toonMode)
+            builder.toonDescription();
+        if (this._annotations)
+            builder.annotations(this._annotations);
+        // Propagate state sync hints
+        if (this._invalidatesPatterns.length > 0) {
+            builder.invalidates(...this._invalidatesPatterns);
+        }
+        if (this._cacheControl) {
+            this._cacheControl === 'immutable' ? builder.cached() : builder.stale();
+        }
+        // Propagate runtime guards
+        if (this._concurrency) {
+            builder.concurrency(this._concurrency);
+        }
+        if (this._egressMaxBytes !== undefined) {
+            builder.maxPayloadBytes(this._egressMaxBytes);
+        }
+        // Apply middleware
+        for (const mw of this._middlewares) {
+            builder.use(mw);
+        }
+        // Register the single action
+        builder.action({
+            name: actionName,
+            handler: wrappedHandler,
+            ...(this._inputSchema ? { schema: this._inputSchema } : {}),
+            ...(readOnly !== undefined ? { readOnly } : {}),
+            ...(destructive !== undefined ? { destructive } : {}),
+            ...(idempotent !== undefined ? { idempotent } : {}),
+            ...(this._returns ? { returns: this._returns } : {}),
+        });
+        return builder;
+    }
+}
+//# sourceMappingURL=FluentToolBuilder.js.map

package/dist/core/builder/FluentToolBuilder.js.map

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

package/dist/core/builder/GroupedToolBuilder.d.ts

@@ -45,7 +45,7 @@
  */
 import { type ZodObject, type ZodRawShape } from 'zod';
 import { type Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
-import { type ToolResponse, type ToolBuilder, type ActionMetadata, type InternalAction, type MiddlewareFn, type ActionConfig } from '../types.js';
+import { type ToolResponse, type ToolBuilder, type ActionMetadata, type InternalAction, type MiddlewareFn, type ActionConfig, type StateSyncHint } from '../types.js';
 import { type DebugObserverFn } from '../../observability/DebugObserver.js';
 import { type FusionTracer } from '../../observability/Tracing.js';
 import { type ProgressSink } from '../execution/ProgressHelper.js';
@@ -129,12 +129,14 @@ export declare class GroupedToolBuilder<TContext = void, TCommon extends Record<
     private _hasFlat;
     private _hasGroup;
     private _toonMode;
+    private _selectEnabled;
     private _frozen;
     private _debug?;
     private _tracer?;
     private _concurrencyGuard?;
     private _egressMaxBytes?;
     private _mutationSerializer?;
+    private readonly _stateSyncHints;
     private _cachedTool?;
     private _executionContext?;
     constructor(name: string);
@@ -263,6 +265,90 @@ export declare class GroupedToolBuilder<TContext = void, TCommon extends Record<
      * @see {@link toonSuccess} for TOON-encoded responses
      */
     toonDescription(): this;
+    /**
+     * Declare glob patterns invalidated when this tool succeeds.
+     *
+     * Eliminates manual `stateSync.policies` configuration —
+     * the framework auto-collects hints from all builders.
+     *
+     * @param patterns - Glob patterns (e.g. `'sprints.*'`, `'tasks.*'`)
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * createTool('tasks')
+     *     .invalidates('tasks.*', 'sprints.*')
+     *     .action({ name: 'update', handler: updateTask });
+     * ```
+     *
+     * @see {@link StateSyncConfig} for centralized configuration
+     */
+    invalidates(...patterns: string[]): this;
+    /**
+     * Mark this tool's data as immutable (safe to cache forever).
+     *
+     * Use for reference data: countries, currencies, ICD-10 codes.
+     * Equivalent to `cacheControl: 'immutable'` in manual policies.
+     *
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * createTool('countries')
+     *     .cached()
+     *     .action({ name: 'list', readOnly: true, handler: listCountries });
+     * ```
+     */
+    cached(): this;
+    /**
+     * Mark this tool's data as volatile (never cache).
+     *
+     * Equivalent to `cacheControl: 'no-store'` in manual policies.
+     * Use for dynamic data that changes frequently.
+     *
+     * @returns `this` for chaining
+     */
+    stale(): this;
+    /** @internal */
+    private _setCacheDirective;
+    /**
+     * Enable `_select` reflection for context window optimization.
+     *
+     * When enabled, actions that use a Presenter with a Zod schema
+     * expose an optional `_select` parameter in the input schema.
+     * The AI can send `_select: ['status', 'amount']` to receive
+     * only the specified top-level fields in the data payload,
+     * reducing context window usage without developer effort.
+     *
+     * **Disabled by default** — opt-in to avoid changing existing
+     * tool schemas.
+     *
+     * **Late Guillotine**: UI blocks, system rules, and action
+     * suggestions are always computed with the **full** validated
+     * data. Only the wire-facing data block is filtered.
+     *
+     * **Shallow (top-level only)**: Nested objects are returned
+     * whole. If the AI selects `'user'`, it gets the entire `user`
+     * object. No recursive GraphQL-style traversal.
+     *
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * createTool<AppContext>('invoices')
+     *     .enableSelect()  // Expose _select in input schema
+     *     .action({
+     *         name: 'get',
+     *         returns: InvoicePresenter,
+     *         handler: async (ctx, args) => ctx.db.invoices.findUnique(args.id),
+     *     });
+     * // AI sends: { action: 'get', id: '123', _select: ['status'] }
+     * // Returns: { status: 'paid' } instead of full invoice
+     * ```
+     *
+     * @see {@link Presenter.getSchemaKeys} for introspection
+     */
+    enableSelect(): this;
     /**
      * Set concurrency limits for this tool (Semaphore + Queue pattern).
      *
@@ -589,6 +675,10 @@ export declare class GroupedToolBuilder<TContext = void, TCommon extends Record<
      * @returns The common Zod schema, or undefined if not set
      */
     getCommonSchema(): ZodObject<ZodRawShape> | undefined;
+    /** Check if `_select` reflection is enabled. Used by the Exposition Compiler. */
+    getSelectEnabled(): boolean;
+    /** Get per-action state sync hints for auto-policy generation. */
+    getStateSyncHints(): ReadonlyMap<string, StateSyncHint>;
     /**
      * Preview the exact MCP protocol payload that the LLM will receive.
      *