@vinkius-core/mcp-fusion 2.9.0 → 2.12.0

package/dist/core/builder/ActionGroupBuilder.js

@@ -11,23 +11,14 @@
  * @example
  * ```typescript
  * createTool<AppContext>('platform')
- *     .group('users', 'User management', g => {
- *         g.use(requireAdmin)  // Group-scoped middleware
- *          .action({
- *              name: 'list',
- *              readOnly: true,
- *              handler: async (ctx, _args) => success(await ctx.db.users.findMany()),
- *          })
- *          .action({
- *              name: 'ban',
- *              destructive: true,
- *              schema: z.object({ user_id: z.string() }),
- *              handler: async (ctx, args) => {
- *                  await ctx.db.users.ban(args.user_id);
- *                  return success('User banned');
- *              },
- *          });
- *     });
+ *     .group('users', 'User management', g => g
+ *         .use(requireAdmin)
+ *         .query('list', async (ctx) => success(await ctx.db.users.findMany()))
+ *         .mutation('ban', async (ctx, args) => {
+ *             await ctx.db.users.ban(args.user_id);
+ *             return success('User banned');
+ *         })
+ *     );
  * ```
  *
  * @see {@link GroupedToolBuilder.group} for creating groups
@@ -87,10 +78,11 @@ export class ActionGroupBuilder {
      *
      * @example
      * ```typescript
-     * builder.group('admin', 'Admin operations', g => {
-     *     g.use(requireAdmin)  // Only runs for admin.* actions
-     *      .action({ name: 'reset', handler: resetHandler });
-     * });
+     * builder.group('admin', 'Admin operations', (g) => g
+     *     .use(requireAdmin)
+     *     .query('list', listHandler)
+     *     .mutation('reset', resetHandler)
+     * );
      * ```
      *
      * @see {@link MiddlewareFn} for the middleware signature
@@ -112,17 +104,67 @@ export class ActionGroupBuilder {
      *
      * @example
      * ```typescript
-     * builder.group('profile', 'User profile', g => {
-     *     g.omitCommon('workspace_id')  // All profile.* actions skip workspace_id
-     *      .action({ name: 'me', readOnly: true, handler: meHandler });
-     * });
+     * builder.group('profile', 'User profile', (g) => g
+     *     .omitCommon('workspace_id')
+     *     .query('me', meHandler)
+     * );
      * ```
      */
     omitCommon(...fields) {
         this._groupOmitCommon.push(...fields);
         return this;
     }
-    action(config) {
+    // ── Semantic Verb Shortcuts ──────────────────────────
+    /**
+     * Register a **read-only** action (readOnly: true).
+     *
+     * Semantic shortcut — eliminates the need for config objects.
+     * The action name is automatically prefixed with the group name
+     * (e.g., `"list"` in group `"users"` → `"users.list"`).
+     *
+     * @param name - Action name (must not contain dots)
+     * @param handler - Handler function
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.group('users', 'User management', (g) => g
+     *     .query('list', async (ctx) => success(await ctx.db.users.findMany()))
+     *     .query('get', async (ctx, args) => success(await ctx.db.users.find(args.id)))
+     * );
+     * ```
+     */
+    query(name, handler) {
+        return this.action({ name, readOnly: true, handler });
+    }
+    /**
+     * Register a **destructive** action (destructive: true).
+     *
+     * Semantic shortcut — eliminates the need for config objects.
+     * Signals to the LLM that this action has irreversible side effects.
+     *
+     * @param name - Action name (must not contain dots)
+     * @param handler - Handler function
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.group('users', 'User management', (g) => g
+     *     .mutation('ban', async (ctx, args) => {
+     *         await ctx.db.users.ban(args.user_id);
+     *         return success('User banned');
+     *     })
+     * );
+     * ```
+     */
+    mutation(name, handler) {
+        return this.action({ name, destructive: true, handler });
+    }
+    action(configOrName, maybeHandler) {
+        // 2-arg shorthand: action('invite', inviteHandler)
+        const config = typeof configOrName === 'string'
+            ? { name: configOrName, handler: maybeHandler }
+            : configOrName;
         if (config.name.includes('.')) {
             throw new Error(`Action name "${config.name}" must not contain dots. ` +
                 `The framework uses dots internally for group.action compound keys.`);

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

@@ -1 +1 @@
-{"version":3,"file":"ActionGroupBuilder.js","sourceRoot":"","sources":["../../../src/core/builder/ActionGroupBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAoC,MAAM,KAAK,CAAC;AACvD,OAAO,EAKN,MAAM,aAAa,CAAC;AAsBrB,4DAA4D;AAE5D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CACnC,MAA8B,EAC9B,gBAAsC;IAKtC,OAAO;QACH,UAAU,EAAE,MAAM,CAAC,IAAI;QACvB,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,SAAS;QAC5C,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,SAAS;QAClC,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,SAAS;QAC5C,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,SAAS;QAC1C,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,SAAS;QACtC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,gBAAgB,EAAE,CAAC,gBAAgB,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS;QACpF,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,SAAS;KACvC,CAAC;AACN,CAAC;AAED,4DAA4D;AAE5D,MAAM,OAAO,kBAAkB;IAC3B,gBAAgB;IACP,QAAQ,GAA+B,EAAE,CAAC;IAClC,UAAU,CAAS;IACnB,iBAAiB,CAAS;IAC1B,iBAAiB,GAA6B,EAAE,CAAC;IAC1D,gBAAgB,GAAa,EAAE,CAAC;IAExC,YAAY,SAAiB,EAAE,WAAoB;QAC/C,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,iBAAiB,GAAG,WAAW,IAAI,EAAE,CAAC;IAC/C,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,GAAG,CAAC,EAA0B;QAC1B,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,GAAG,MAAgB;QAC1B,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC;IAChB,CAAC;IA6CD,MAAM,CAAC,MAA8B;QACjC,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACX,gBAAgB,MAAM,CAAC,IAAI,2BAA2B;gBACtD,oEAAoE,CACvE,CAAC;QACN,CAAC;QAED,qDAAqD;QACrD,MAAM,SAAS,GAAI,MAAoC,CAAC,UAAU,IAAI,EAAE,CAAC;QACzE,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,gBAAgB,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QAE1E,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YACf,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,IAAI,MAAM,CAAC,IAAI,EAAE;YACxC,SAAS,EAAE,IAAI,CAAC,UAAU;YAC1B,gBAAgB,EAAE,IAAI,CAAC,iBAAiB;YACxC,GAAG,uBAAuB,CAAC,MAAM,EAAE,UAAU,CAAC;YAC9C,WAAW,EAAE,IAAI,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC;gBAC1C,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,SAAS;SAChD,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IAChB,CAAC;CACJ"}
+{"version":3,"file":"ActionGroupBuilder.js","sourceRoot":"","sources":["../../../src/core/builder/ActionGroupBuilder.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,59 @@
+import type { ErrorCode, ErrorSeverity, ToolResponse } from '../response.js';
+/**
+ * ErrorBuilder — Fluent API for Self-Healing Errors
+ *
+ * Provides a chaining interface to construct structured tool errors
+ * with recovery suggestions, available actions, and metadata.
+ *
+ * Designed to be used via `f.error()` in a tool handler.
+ *
+ * @example
+ * ```typescript
+ * return f.error('NOT_FOUND', `Project "${id}" missing`)
+ *     .suggest('Check the ID and try again')
+ *     .actions('projects.list')
+ *     .critical();
+ * ```
+ */
+export declare class ErrorBuilder {
+    private _message;
+    private _code;
+    private _suggestion?;
+    private _actions;
+    private _severity;
+    private _details;
+    private _retryAfter?;
+    /** @internal Cached build result — invalidated by any setter */
+    private _cached;
+    constructor(code: ErrorCode, message: string);
+    /** Add a recovery suggestion for the LLM agent */
+    suggest(suggestion: string): this;
+    /** List tool names the agent should try instead */
+    actions(...names: string[]): this;
+    /** Set error severity (default: 'error') */
+    severity(level: ErrorSeverity): this;
+    /** Set severity to 'critical' (stops agent execution) */
+    critical(): this;
+    /** Set severity to 'warning' (non-fatal guidance) */
+    warning(): this;
+    /** Add structured metadata details about the error */
+    details(data: Record<string, string | number | boolean>): this;
+    /** Suggest a retry delay in seconds for transient errors */
+    retryAfter(seconds: number): this;
+    /**
+     * Build the final {@link ToolResponse}.
+     *
+     * Note: The execution pipeline also accepts the builder instance
+     * directly and calls this method automatically.
+     */
+    build(): ToolResponse;
+    /** @internal Ensure the response is built and cached */
+    private _ensureBuilt;
+    /** Implementation of ToolResponse for direct return in handlers */
+    get content(): readonly {
+        readonly type: "text";
+        readonly text: string;
+    }[];
+    get isError(): boolean | undefined;
+}
+//# sourceMappingURL=ErrorBuilder.d.ts.map

package/dist/core/builder/ErrorBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorBuilder.d.ts","sourceRoot":"","sources":["../../../src/core/builder/ErrorBuilder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE7E;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;IACrB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B,gEAAgE;IAChE,OAAO,CAAC,OAAO,CAAuC;gBAE1C,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM;IAK5C,kDAAkD;IAClD,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAMjC,mDAAmD;IACnD,OAAO,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAMjC,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAMpC,yDAAyD;IACzD,QAAQ,IAAI,IAAI;IAEhB,qDAAqD;IACrD,OAAO,IAAI,IAAI;IAEf,sDAAsD;IACtD,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI;IAQ9D,4DAA4D;IAC5D,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAMjC;;;;;OAKG;IACH,KAAK,IAAI,YAAY;IAmBrB,wDAAwD;IACxD,OAAO,CAAC,YAAY;IAKpB,mEAAmE;IACnE,IAAI,OAAO;;;QAA0C;IACrD,IAAI,OAAO,wBAA0C;CACxD"}

package/dist/core/builder/ErrorBuilder.js

@@ -0,0 +1,99 @@
+import { toolError } from '../response.js';
+/**
+ * ErrorBuilder — Fluent API for Self-Healing Errors
+ *
+ * Provides a chaining interface to construct structured tool errors
+ * with recovery suggestions, available actions, and metadata.
+ *
+ * Designed to be used via `f.error()` in a tool handler.
+ *
+ * @example
+ * ```typescript
+ * return f.error('NOT_FOUND', `Project "${id}" missing`)
+ *     .suggest('Check the ID and try again')
+ *     .actions('projects.list')
+ *     .critical();
+ * ```
+ */
+export class ErrorBuilder {
+    _message;
+    _code;
+    _suggestion;
+    _actions = [];
+    _severity = 'error';
+    _details = {};
+    _retryAfter;
+    /** @internal Cached build result — invalidated by any setter */
+    _cached = undefined;
+    constructor(code, message) {
+        this._code = code;
+        this._message = message;
+    }
+    /** Add a recovery suggestion for the LLM agent */
+    suggest(suggestion) {
+        this._suggestion = suggestion;
+        this._cached = undefined;
+        return this;
+    }
+    /** List tool names the agent should try instead */
+    actions(...names) {
+        this._actions.push(...names);
+        this._cached = undefined;
+        return this;
+    }
+    /** Set error severity (default: 'error') */
+    severity(level) {
+        this._severity = level;
+        this._cached = undefined;
+        return this;
+    }
+    /** Set severity to 'critical' (stops agent execution) */
+    critical() { return this.severity('critical'); }
+    /** Set severity to 'warning' (non-fatal guidance) */
+    warning() { return this.severity('warning'); }
+    /** Add structured metadata details about the error */
+    details(data) {
+        for (const [key, value] of Object.entries(data)) {
+            this._details[key] = String(value);
+        }
+        this._cached = undefined;
+        return this;
+    }
+    /** Suggest a retry delay in seconds for transient errors */
+    retryAfter(seconds) {
+        this._retryAfter = seconds;
+        this._cached = undefined;
+        return this;
+    }
+    /**
+     * Build the final {@link ToolResponse}.
+     *
+     * Note: The execution pipeline also accepts the builder instance
+     * directly and calls this method automatically.
+     */
+    build() {
+        const opts = {
+            message: this._message,
+            severity: this._severity,
+        };
+        if (this._suggestion)
+            opts.suggestion = this._suggestion;
+        if (this._actions.length > 0)
+            opts.availableActions = this._actions;
+        if (Object.keys(this._details).length > 0)
+            opts.details = this._details;
+        if (this._retryAfter !== undefined)
+            opts.retryAfter = this._retryAfter;
+        return toolError(this._code, opts);
+    }
+    /** @internal Ensure the response is built and cached */
+    _ensureBuilt() {
+        if (!this._cached)
+            this._cached = this.build();
+        return this._cached;
+    }
+    /** Implementation of ToolResponse for direct return in handlers */
+    get content() { return this._ensureBuilt().content; }
+    get isError() { return this._ensureBuilt().isError; }
+}
+//# sourceMappingURL=ErrorBuilder.js.map

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

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

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

@@ -0,0 +1,91 @@
+/**
+ * FluentRouter — Prefix Grouping for Fluent Tools
+ *
+ * Eliminates repetitive `'users.'` prefixes across dozens of tools.
+ * A router shares a common prefix, description, and middleware chain
+ * across all child tools.
+ *
+ * @example
+ * ```typescript
+ * const f = initFusion<AppContext>();
+ *
+ * const users = f.router('users')
+ *     .describe('User management')
+ *     .use(requireAuth);
+ *
+ * // Tool name: "users", action: "list"
+ * const listUsers = users.query('list')
+ *     .input({ limit: f.number() })
+ *     .resolve(async ({ input }) => { ... });
+ *
+ * // Tool name: "users", action: "delete"
+ * const deleteUser = users.mutation('delete')
+ *     .input({ id: f.string() })
+ *     .resolve(async ({ input }) => { ... });
+ * ```
+ *
+ * @module
+ */
+import { type MiddlewareFn } from '../types.js';
+import { FluentToolBuilder } from './FluentToolBuilder.js';
+/**
+ * Fluent router that shares prefix, description, and middleware
+ * across child tools created via `.query()`, `.mutation()`, `.action()`.
+ *
+ * @typeParam TContext - Base application context
+ */
+export declare class FluentRouter<TContext> {
+    /** @internal */ readonly _prefix: string;
+    /** @internal */ _description?: string;
+    /** @internal */ _middlewares: MiddlewareFn<TContext>[];
+    /** @internal */ _tags: string[];
+    constructor(prefix: string);
+    /**
+     * Set the shared description for all tools in this router.
+     *
+     * @param text - Human-readable description
+     * @returns `this` for chaining
+     */
+    describe(text: string): this;
+    /**
+     * Add middleware shared by all tools in this router.
+     *
+     * @param mw - Middleware function
+     * @returns `this` for chaining
+     */
+    use(mw: MiddlewareFn<TContext>): this;
+    /**
+     * Set capability tags shared by all tools in this router.
+     *
+     * @param tags - Tag strings for filtering
+     * @returns `this` for chaining
+     */
+    tags(...tags: string[]): this;
+    /**
+     * Create a read-only query tool under this router's prefix.
+     *
+     * @param action - Action name (e.g. `'list'` → tool name `'prefix.list'`)
+     * @returns A `FluentToolBuilder` with the prefixed name and inherited config
+     */
+    query(action: string): FluentToolBuilder<TContext>;
+    /**
+     * Create a destructive mutation tool under this router's prefix.
+     *
+     * @param action - Action name (e.g. `'delete'` → tool name `'prefix.delete'`)
+     * @returns A `FluentToolBuilder` with the prefixed name and inherited config
+     */
+    mutation(action: string): FluentToolBuilder<TContext>;
+    /**
+     * Create a neutral action tool under this router's prefix.
+     *
+     * @param action - Action name (e.g. `'update'` → tool name `'prefix.update'`)
+     * @returns A `FluentToolBuilder` with the prefixed name and inherited config
+     */
+    action(action: string): FluentToolBuilder<TContext>;
+    /**
+     * Create a FluentToolBuilder with inherited router config.
+     * @internal
+     */
+    private _createBuilder;
+}
+//# sourceMappingURL=FluentRouter.d.ts.map

package/dist/core/builder/FluentRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FluentRouter.d.ts","sourceRoot":"","sources":["../../../src/core/builder/FluentRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACH,iBAAiB,EAIpB,MAAM,wBAAwB,CAAC;AAEhC;;;;;GAKG;AACH,qBAAa,YAAY,CAAC,QAAQ;IAC9B,gBAAgB,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAC1C,gBAAgB,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IACvC,gBAAgB,CAAC,YAAY,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAM;IAC7D,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,CAAM;gBAE1B,MAAM,EAAE,MAAM;IAI1B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK5B;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,YAAY,CAAC,QAAQ,CAAC,GAAG,IAAI;IAKrC;;;;;OAKG;IACH,IAAI,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAK7B;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC;IAIlD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC;IAIrD;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC;IAInD;;;OAGG;IACH,OAAO,CAAC,cAAc;CAwBzB"}

package/dist/core/builder/FluentRouter.js

@@ -0,0 +1,121 @@
+/**
+ * FluentRouter — Prefix Grouping for Fluent Tools
+ *
+ * Eliminates repetitive `'users.'` prefixes across dozens of tools.
+ * A router shares a common prefix, description, and middleware chain
+ * across all child tools.
+ *
+ * @example
+ * ```typescript
+ * const f = initFusion<AppContext>();
+ *
+ * const users = f.router('users')
+ *     .describe('User management')
+ *     .use(requireAuth);
+ *
+ * // Tool name: "users", action: "list"
+ * const listUsers = users.query('list')
+ *     .input({ limit: f.number() })
+ *     .resolve(async ({ input }) => { ... });
+ *
+ * // Tool name: "users", action: "delete"
+ * const deleteUser = users.mutation('delete')
+ *     .input({ id: f.string() })
+ *     .resolve(async ({ input }) => { ... });
+ * ```
+ *
+ * @module
+ */
+import {} from '../types.js';
+import { FluentToolBuilder, QUERY_DEFAULTS, MUTATION_DEFAULTS, ACTION_DEFAULTS, } from './FluentToolBuilder.js';
+/**
+ * Fluent router that shares prefix, description, and middleware
+ * across child tools created via `.query()`, `.mutation()`, `.action()`.
+ *
+ * @typeParam TContext - Base application context
+ */
+export class FluentRouter {
+    /** @internal */ _prefix;
+    /** @internal */ _description;
+    /** @internal */ _middlewares = [];
+    /** @internal */ _tags = [];
+    constructor(prefix) {
+        this._prefix = prefix;
+    }
+    /**
+     * Set the shared description for all tools in this router.
+     *
+     * @param text - Human-readable description
+     * @returns `this` for chaining
+     */
+    describe(text) {
+        this._description = text;
+        return this;
+    }
+    /**
+     * Add middleware shared by all tools in this router.
+     *
+     * @param mw - Middleware function
+     * @returns `this` for chaining
+     */
+    use(mw) {
+        this._middlewares.push(mw);
+        return this;
+    }
+    /**
+     * Set capability tags shared by all tools in this router.
+     *
+     * @param tags - Tag strings for filtering
+     * @returns `this` for chaining
+     */
+    tags(...tags) {
+        this._tags = tags;
+        return this;
+    }
+    /**
+     * Create a read-only query tool under this router's prefix.
+     *
+     * @param action - Action name (e.g. `'list'` → tool name `'prefix.list'`)
+     * @returns A `FluentToolBuilder` with the prefixed name and inherited config
+     */
+    query(action) {
+        return this._createBuilder(action, QUERY_DEFAULTS);
+    }
+    /**
+     * Create a destructive mutation tool under this router's prefix.
+     *
+     * @param action - Action name (e.g. `'delete'` → tool name `'prefix.delete'`)
+     * @returns A `FluentToolBuilder` with the prefixed name and inherited config
+     */
+    mutation(action) {
+        return this._createBuilder(action, MUTATION_DEFAULTS);
+    }
+    /**
+     * Create a neutral action tool under this router's prefix.
+     *
+     * @param action - Action name (e.g. `'update'` → tool name `'prefix.update'`)
+     * @returns A `FluentToolBuilder` with the prefixed name and inherited config
+     */
+    action(action) {
+        return this._createBuilder(action, ACTION_DEFAULTS);
+    }
+    /**
+     * Create a FluentToolBuilder with inherited router config.
+     * @internal
+     */
+    _createBuilder(action, defaults) {
+        const builder = new FluentToolBuilder(`${this._prefix}.${action}`, defaults);
+        // Inherit router middleware
+        builder._middlewares.push(...this._middlewares);
+        // Inherit router tags
+        if (this._tags.length > 0) {
+            builder._tags.push(...this._tags);
+        }
+        // Inherit router description as fallback
+        if (this._description && !builder._description) {
+            builder._description = this._description;
+        }
+        return builder;
+    }
+}
+//# sourceMappingURL=FluentRouter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FluentRouter.js","sourceRoot":"","sources":["../../../src/core/builder/FluentRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAqB,MAAM,aAAa,CAAC;AAChD,OAAO,EACH,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,eAAe,GAClB,MAAM,wBAAwB,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,OAAO,YAAY;IACrB,gBAAgB,CAAU,OAAO,CAAS;IAC1C,gBAAgB,CAAC,YAAY,CAAU;IACvC,gBAAgB,CAAC,YAAY,GAA6B,EAAE,CAAC;IAC7D,gBAAgB,CAAC,KAAK,GAAa,EAAE,CAAC;IAEtC,YAAY,MAAc;QACtB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IAC1B,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,IAAY;QACjB,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,EAA0B;QAC1B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,GAAG,IAAc;QAClB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAc;QAChB,OAAO,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACvD,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,MAAc;QACnB,OAAO,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC1D,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAc;QACjB,OAAO,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxD,CAAC;IAED;;;OAGG;IACK,cAAc,CAClB,MAAc,EACd,QAA6E;QAE7E,MAAM,OAAO,GAAG,IAAI,iBAAiB,CACjC,GAAG,IAAI,CAAC,OAAO,IAAI,MAAM,EAAE,EAC3B,QAAQ,CACX,CAAC;QAEF,4BAA4B;QAC5B,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;QAEhD,sBAAsB;QACtB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;QAED,yCAAyC;QACzC,IAAI,IAAI,CAAC,YAAY,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;YAC7C,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QAC7C,CAAC;QAED,OAAO,OAAO,CAAC;IACnB,CAAC;CACJ"}