@vinkius-core/mcp-fusion 2.9.0 → 2.12.0

package/dist/presenter/typeHelpers.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Type Helpers — Zod-Backed Namespace for Presenter Schemas
+ *
+ * Inspired by ElysiaJS (`t.String`), Convex (`v.string()`), and
+ * Encore.ts (native TS types). Provides a compact namespace that
+ * eliminates the need to import Zod directly.
+ *
+ * Every `t.*` value IS a ZodType — zero abstraction leakage.
+ * Developers who need advanced Zod features can use `t.zod` escape hatch
+ * or mix `t.*` with raw Zod schemas freely.
+ *
+ * @example
+ * ```typescript
+ * import { createPresenter, t, ui } from '@vinkius-core/mcp-fusion';
+ *
+ * const InvoicePresenter = createPresenter('Invoice')
+ *     .schema({
+ *         id:           t.string,
+ *         amount_cents: t.number.describe('CENTS — divide by 100'),
+ *         status:       t.enum('draft', 'sent', 'paid', 'overdue'),
+ *         tags:         t.array(t.string),
+ *         metadata:     t.optional(t.record(t.string)),
+ *     });
+ * ```
+ *
+ * @module
+ */
+import { z, type ZodType, type ZodRawShape } from 'zod';
+/**
+ * Compact type namespace for Presenter schema definitions.
+ *
+ * Eliminates `import { z } from 'zod'` for 95% of use cases.
+ * Every value is a real ZodType — `.describe()`, `.optional()`,
+ * `.nullable()`, `.default()` all work natively.
+ *
+ * @example
+ * ```typescript
+ * .schema({
+ *     id:     t.string,
+ *     count:  t.number,
+ *     active: t.boolean,
+ *     role:   t.enum('admin', 'user', 'guest'),
+ *     tags:   t.array(t.string),
+ * })
+ * ```
+ */
+export declare const t: {
+    /** String type — equivalent to `z.string()` */
+    readonly string: z.ZodString;
+    /** Number type — equivalent to `z.number()` */
+    readonly number: z.ZodNumber;
+    /** Boolean type — equivalent to `z.boolean()` */
+    readonly boolean: z.ZodBoolean;
+    /** Date type — equivalent to `z.date()` */
+    readonly date: z.ZodDate;
+    /**
+     * Create an enum type from string literals.
+     *
+     * @param values - At least one enum value
+     * @returns A Zod enum schema
+     *
+     * @example
+     * ```typescript
+     * t.enum('active', 'archived')  // z.enum(['active', 'archived'])
+     * ```
+     */
+    readonly enum: <V extends string>(values_0: V, ...values: V[]) => z.ZodEnum<[V, ...V[]]>;
+    /**
+     * Create an array type.
+     *
+     * @param item - The schema for array items
+     * @returns A Zod array schema
+     *
+     * @example
+     * ```typescript
+     * t.array(t.string)       // z.array(z.string())
+     * t.array(t.number)       // z.array(z.number())
+     * ```
+     */
+    readonly array: <T extends ZodType>(item: T) => z.ZodArray<T, "many">;
+    /**
+     * Create a nested object type.
+     *
+     * @param shape - Object shape with ZodType values
+     * @returns A Zod object schema
+     *
+     * @example
+     * ```typescript
+     * t.object({ lat: t.number, lng: t.number })  // z.object({...})
+     * ```
+     */
+    readonly object: <T extends ZodRawShape>(shape: T) => z.ZodObject<T, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<T>, any> extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never, z.baseObjectInputType<T> extends infer T_2 ? { [k_1 in keyof T_2]: T_2[k_1]; } : never>;
+    /**
+     * Create a record (dictionary) type.
+     *
+     * @param valueType - Schema for record values
+     * @returns A Zod record schema
+     *
+     * @example
+     * ```typescript
+     * t.record(t.string)  // z.record(z.string())
+     * ```
+     */
+    readonly record: <T extends ZodType>(valueType: T) => z.ZodRecord<z.ZodString, T>;
+    /**
+     * Make a type optional.
+     *
+     * @param type - Any ZodType to make optional
+     * @returns An optional variant of the given type
+     *
+     * @example
+     * ```typescript
+     * t.optional(t.string)   // z.string().optional()
+     * t.optional(t.number)   // z.number().optional()
+     * ```
+     */
+    readonly optional: <T extends ZodType>(type: T) => z.ZodOptional<T>;
+    /**
+     * Make a type nullable.
+     *
+     * @param type - Any ZodType to make nullable
+     * @returns A nullable variant of the given type
+     *
+     * @example
+     * ```typescript
+     * t.nullable(t.string)   // z.string().nullable()
+     * ```
+     */
+    readonly nullable: <T extends ZodType>(type: T) => z.ZodNullable<T>;
+    /**
+     * Direct access to Zod for advanced use cases.
+     *
+     * Use when `t.*` helpers don't cover your needs:
+     * regex, transforms, refinements, unions, discriminated unions, etc.
+     *
+     * @example
+     * ```typescript
+     * .schema({
+     *     id:    t.string,
+     *     email: t.zod.string().email().min(5),  // Zod power features
+     *     role:  t.zod.union([t.zod.literal('admin'), t.zod.literal('user')]),
+     * })
+     * ```
+     */
+    readonly zod: typeof z;
+};
+//# sourceMappingURL=typeHelpers.d.ts.map

package/dist/presenter/typeHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeHelpers.d.ts","sourceRoot":"","sources":["../../src/presenter/typeHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,CAAC,EAAE,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAIxD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,CAAC;IAGV,+CAA+C;;IAG/C,+CAA+C;;IAG/C,iDAAiD;;IAGjD,2CAA2C;;IAK3C;;;;;;;;;;OAUG;oBACI,CAAC,SAAS,MAAM;IAGvB;;;;;;;;;;;OAWG;qBACK,CAAC,SAAS,OAAO,QAAQ,CAAC;IAGlC;;;;;;;;;;OAUG;sBACM,CAAC,SAAS,WAAW,SAAS,CAAC;IAGxC;;;;;;;;;;OAUG;sBACM,CAAC,SAAS,OAAO,aAAa,CAAC;IAKxC;;;;;;;;;;;OAWG;wBACQ,CAAC,SAAS,OAAO,QAAQ,CAAC;IAGrC;;;;;;;;;;OAUG;wBACQ,CAAC,SAAS,OAAO,QAAQ,CAAC;IAKrC;;;;;;;;;;;;;;OAcG;;CAEG,CAAC"}

package/dist/presenter/typeHelpers.js

@@ -0,0 +1,152 @@
+/**
+ * Type Helpers — Zod-Backed Namespace for Presenter Schemas
+ *
+ * Inspired by ElysiaJS (`t.String`), Convex (`v.string()`), and
+ * Encore.ts (native TS types). Provides a compact namespace that
+ * eliminates the need to import Zod directly.
+ *
+ * Every `t.*` value IS a ZodType — zero abstraction leakage.
+ * Developers who need advanced Zod features can use `t.zod` escape hatch
+ * or mix `t.*` with raw Zod schemas freely.
+ *
+ * @example
+ * ```typescript
+ * import { createPresenter, t, ui } from '@vinkius-core/mcp-fusion';
+ *
+ * const InvoicePresenter = createPresenter('Invoice')
+ *     .schema({
+ *         id:           t.string,
+ *         amount_cents: t.number.describe('CENTS — divide by 100'),
+ *         status:       t.enum('draft', 'sent', 'paid', 'overdue'),
+ *         tags:         t.array(t.string),
+ *         metadata:     t.optional(t.record(t.string)),
+ *     });
+ * ```
+ *
+ * @module
+ */
+import { z } from 'zod';
+// ── Type Helpers Namespace ─────────────────────────────────
+/**
+ * Compact type namespace for Presenter schema definitions.
+ *
+ * Eliminates `import { z } from 'zod'` for 95% of use cases.
+ * Every value is a real ZodType — `.describe()`, `.optional()`,
+ * `.nullable()`, `.default()` all work natively.
+ *
+ * @example
+ * ```typescript
+ * .schema({
+ *     id:     t.string,
+ *     count:  t.number,
+ *     active: t.boolean,
+ *     role:   t.enum('admin', 'user', 'guest'),
+ *     tags:   t.array(t.string),
+ * })
+ * ```
+ */
+export const t = {
+    // ── Primitives (singleton instances) ──────────────────
+    /** String type — equivalent to `z.string()` */
+    string: z.string(),
+    /** Number type — equivalent to `z.number()` */
+    number: z.number(),
+    /** Boolean type — equivalent to `z.boolean()` */
+    boolean: z.boolean(),
+    /** Date type — equivalent to `z.date()` */
+    date: z.date(),
+    // ── Composites (factory functions) ────────────────────
+    /**
+     * Create an enum type from string literals.
+     *
+     * @param values - At least one enum value
+     * @returns A Zod enum schema
+     *
+     * @example
+     * ```typescript
+     * t.enum('active', 'archived')  // z.enum(['active', 'archived'])
+     * ```
+     */
+    enum: (...values) => z.enum(values),
+    /**
+     * Create an array type.
+     *
+     * @param item - The schema for array items
+     * @returns A Zod array schema
+     *
+     * @example
+     * ```typescript
+     * t.array(t.string)       // z.array(z.string())
+     * t.array(t.number)       // z.array(z.number())
+     * ```
+     */
+    array: (item) => z.array(item),
+    /**
+     * Create a nested object type.
+     *
+     * @param shape - Object shape with ZodType values
+     * @returns A Zod object schema
+     *
+     * @example
+     * ```typescript
+     * t.object({ lat: t.number, lng: t.number })  // z.object({...})
+     * ```
+     */
+    object: (shape) => z.object(shape),
+    /**
+     * Create a record (dictionary) type.
+     *
+     * @param valueType - Schema for record values
+     * @returns A Zod record schema
+     *
+     * @example
+     * ```typescript
+     * t.record(t.string)  // z.record(z.string())
+     * ```
+     */
+    record: (valueType) => z.record(valueType),
+    // ── Modifiers (wrappers) ─────────────────────────────
+    /**
+     * Make a type optional.
+     *
+     * @param type - Any ZodType to make optional
+     * @returns An optional variant of the given type
+     *
+     * @example
+     * ```typescript
+     * t.optional(t.string)   // z.string().optional()
+     * t.optional(t.number)   // z.number().optional()
+     * ```
+     */
+    optional: (type) => type.optional(),
+    /**
+     * Make a type nullable.
+     *
+     * @param type - Any ZodType to make nullable
+     * @returns A nullable variant of the given type
+     *
+     * @example
+     * ```typescript
+     * t.nullable(t.string)   // z.string().nullable()
+     * ```
+     */
+    nullable: (type) => type.nullable(),
+    // ── Escape Hatch ─────────────────────────────────────
+    /**
+     * Direct access to Zod for advanced use cases.
+     *
+     * Use when `t.*` helpers don't cover your needs:
+     * regex, transforms, refinements, unions, discriminated unions, etc.
+     *
+     * @example
+     * ```typescript
+     * .schema({
+     *     id:    t.string,
+     *     email: t.zod.string().email().min(5),  // Zod power features
+     *     role:  t.zod.union([t.zod.literal('admin'), t.zod.literal('user')]),
+     * })
+     * ```
+     */
+    zod: z,
+};
+//# sourceMappingURL=typeHelpers.js.map

package/dist/presenter/typeHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeHelpers.js","sourceRoot":"","sources":["../../src/presenter/typeHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,CAAC,EAAkC,MAAM,KAAK,CAAC;AAExD,8DAA8D;AAE9D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,CAAC,GAAG;IACb,yDAAyD;IAEzD,+CAA+C;IAC/C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAElB,+CAA+C;IAC/C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAElB,iDAAiD;IACjD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IAEpB,2CAA2C;IAC3C,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;IAEd,yDAAyD;IAEzD;;;;;;;;;;OAUG;IACH,IAAI,EAAE,CAAmB,GAAG,MAAmB,EAAE,EAAE,CAC/C,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;IAElB;;;;;;;;;;;OAWG;IACH,KAAK,EAAE,CAAoB,IAAO,EAAE,EAAE,CAClC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,CAAwB,KAAQ,EAAE,EAAE,CACxC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;IAEnB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,CAAoB,SAAY,EAAE,EAAE,CACxC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;IAEvB,wDAAwD;IAExD;;;;;;;;;;;OAWG;IACH,QAAQ,EAAE,CAAoB,IAAO,EAAE,EAAE,CACrC,IAAI,CAAC,QAAQ,EAAE;IAEnB;;;;;;;;;;OAUG;IACH,QAAQ,EAAE,CAAoB,IAAO,EAAE,EAAE,CACrC,IAAI,CAAC,QAAQ,EAAE;IAEnB,wDAAwD;IAExD;;;;;;;;;;;;;;OAcG;IACH,GAAG,EAAE,CAAC;CACA,CAAC"}

package/dist/prompt/FluentPromptBuilder.d.ts

@@ -0,0 +1,155 @@
+/**
+ * FluentPromptBuilder — Chainable Prompt Definition API
+ *
+ * Provides a builder-pattern alternative to the config-bag `definePrompt()`.
+ * Follows the same architectural pattern as `FluentToolBuilder`.
+ *
+ * @example
+ * ```typescript
+ * const greet = f.prompt('greet')
+ *     .describe('Greet a user by name')
+ *     .input({ name: f.string() })
+ *     .handler(async (ctx, { name }) => ({
+ *         messages: [PromptMessage.user(`Hello ${name}!`)],
+ *     }));
+ * ```
+ *
+ * @module
+ */
+import { type ZodObject, type ZodRawShape } from 'zod';
+import { type PromptBuilder, type PromptResult, type PromptParamsMap, type LoopbackContext } from './types.js';
+import { type MiddlewareFn } from '../core/types.js';
+/**
+ * Chainable builder for MCP Prompts.
+ *
+ * Each setter returns `this` for chaining. Finalisation happens lazily
+ * when the `PromptBuilder` interface methods are accessed — this means
+ * you can pass a `FluentPromptBuilder` directly to `PromptRegistry.register()`.
+ *
+ * @typeParam TContext - Application context type (inherited from `initFusion`)
+ * @typeParam TArgs - Inferred argument type from the schema
+ */
+export declare class FluentPromptBuilder<TContext = void, TArgs extends Record<string, unknown> = Record<string, unknown>> implements PromptBuilder<TContext> {
+    private readonly _name;
+    private _title?;
+    private _description?;
+    private _icons?;
+    private _tags;
+    private _middlewares;
+    private _args?;
+    private _hydrationTimeout?;
+    private _handler?;
+    /** @internal Cached delegate built on first access to PromptBuilder methods */
+    private _delegate;
+    constructor(name: string);
+    /**
+     * Set a human-readable title for UI display.
+     *
+     * @param title - The prompt title
+     * @returns `this` for chaining
+     */
+    title(title: string): this;
+    /**
+     * Set the prompt description shown in the slash command palette.
+     *
+     * @param description - Human-readable description
+     * @returns `this` for chaining
+     */
+    describe(description: string): this;
+    /**
+     * Set icons for light/dark themes.
+     *
+     * @param icons - Icon paths for light and/or dark themes
+     * @returns `this` for chaining
+     */
+    icons(icons: {
+        light?: string;
+        dark?: string;
+    }): this;
+    /**
+     * Set capability tags for selective exposure.
+     *
+     * @param tags - Tag strings for filtering
+     * @returns `this` for chaining
+     */
+    tags(...tags: string[]): this;
+    /**
+     * Define the input schema for prompt arguments.
+     *
+     * Accepts the same formats as `FluentToolBuilder.input()`:
+     * - Fluent param descriptors (`f.string()`, `f.number()`, etc.) — zero imports
+     * - Zod schema for power users
+     *
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * // Fluent descriptors (recommended — zero Zod imports)
+     * f.prompt('greet')
+     *     .input({ name: f.string(), age: f.number().optional() })
+     *     .handler(async (ctx, { name, age }) => ({ ... }));
+     *
+     * // Zod schema (advanced)
+     * f.prompt('search')
+     *     .input(z.object({ query: z.string().min(1) }))
+     *     .handler(async (ctx, { query }) => ({ ... }));
+     * ```
+     */
+    input<S extends ZodRawShape>(schema: ZodObject<S>): FluentPromptBuilder<TContext, ZodObject<S>['_output']>;
+    input(params: PromptParamsMap): this;
+    /**
+     * Add middleware to the prompt's execution pipeline.
+     *
+     * Middleware runs in registration order around the handler
+     * (same onion model as tool middleware).
+     *
+     * @param fns - Middleware functions
+     * @returns `this` for chaining
+     */
+    use(...fns: MiddlewareFn<TContext>[]): this;
+    /**
+     * Set the maximum hydration time in milliseconds.
+     *
+     * If the handler doesn't complete within this time,
+     * the framework returns a graceful SYSTEM ALERT.
+     *
+     * @param ms - Timeout in milliseconds
+     * @returns `this` for chaining
+     */
+    timeout(ms: number): this;
+    /**
+     * Set the hydration handler.
+     *
+     * This is the terminal method — after calling `.handler()`,
+     * the builder is ready to be registered.
+     *
+     * @param fn - Handler function receiving `(ctx, args)` → `PromptResult`
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * .handler(async (ctx, { name }) => ({
+     *     messages: [PromptMessage.user(`Hello ${name}!`)],
+     * }))
+     * ```
+     */
+    handler(fn: (ctx: TContext & LoopbackContext, args: TArgs) => Promise<PromptResult>): this;
+    /** @internal Build the underlying PromptBuilder delegate lazily */
+    private _build;
+    getName(): string;
+    getDescription(): string | undefined;
+    getTags(): string[];
+    hasMiddleware(): boolean;
+    getHydrationTimeout(): number | undefined;
+    buildPromptDefinition(): {
+        name: string;
+        description?: string;
+        arguments?: Array<{
+            name: string;
+            description?: string;
+            required?: boolean;
+        }>;
+    };
+    execute(ctx: TContext, args: Record<string, string>): Promise<PromptResult>;
+}
+//# sourceMappingURL=FluentPromptBuilder.d.ts.map

package/dist/prompt/FluentPromptBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FluentPromptBuilder.d.ts","sourceRoot":"","sources":["../../src/prompt/FluentPromptBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AACvD,OAAO,EACH,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,eAAe,EACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAOrD;;;;;;;;;GASG;AACH,qBAAa,mBAAmB,CAAC,QAAQ,GAAG,IAAI,EAAE,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAC7G,YAAW,aAAa,CAAC,QAAQ,CAAC;IAElC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,MAAM,CAAC,CAAoC;IACnD,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,YAAY,CAAgC;IACpD,OAAO,CAAC,KAAK,CAAC,CAA2C;IACzD,OAAO,CAAC,iBAAiB,CAAC,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,CAA0E;IAE3F,+EAA+E;IAC/E,OAAO,CAAC,SAAS,CAAsC;gBAE3C,IAAI,EAAE,MAAM;IAMxB;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM1B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAMnC;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAMrD;;;;;OAKG;IACH,IAAI,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAM7B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC1G,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAQpC;;;;;;;;OAQG;IACH,GAAG,CAAC,GAAG,GAAG,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,GAAG,IAAI;IAM3C;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMzB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,QAAQ,GAAG,eAAe,EAAE,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAQ1F,mEAAmE;IACnE,OAAO,CAAC,MAAM;IAuBd,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,MAAM,GAAG,SAAS;IAIpC,OAAO,IAAI,MAAM,EAAE;IAInB,aAAa,IAAI,OAAO;IAIxB,mBAAmB,IAAI,MAAM,GAAG,SAAS;IAIzC,qBAAqB;;;;;uBAQ6/J,CAAC;oBAA8B,CAAC;;;IAJljK,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC;CAG9E"}

package/dist/prompt/FluentPromptBuilder.js

@@ -0,0 +1,193 @@
+/**
+ * FluentPromptBuilder — Chainable Prompt Definition API
+ *
+ * Provides a builder-pattern alternative to the config-bag `definePrompt()`.
+ * Follows the same architectural pattern as `FluentToolBuilder`.
+ *
+ * @example
+ * ```typescript
+ * const greet = f.prompt('greet')
+ *     .describe('Greet a user by name')
+ *     .input({ name: f.string() })
+ *     .handler(async (ctx, { name }) => ({
+ *         messages: [PromptMessage.user(`Hello ${name}!`)],
+ *     }));
+ * ```
+ *
+ * @module
+ */
+import {} from 'zod';
+import {} from './types.js';
+import {} from '../core/types.js';
+import { definePrompt } from './definePrompt.js';
+// ============================================================================
+// FluentPromptBuilder
+// ============================================================================
+/**
+ * Chainable builder for MCP Prompts.
+ *
+ * Each setter returns `this` for chaining. Finalisation happens lazily
+ * when the `PromptBuilder` interface methods are accessed — this means
+ * you can pass a `FluentPromptBuilder` directly to `PromptRegistry.register()`.
+ *
+ * @typeParam TContext - Application context type (inherited from `initFusion`)
+ * @typeParam TArgs - Inferred argument type from the schema
+ */
+export class FluentPromptBuilder {
+    _name;
+    _title;
+    _description;
+    _icons;
+    _tags = [];
+    _middlewares = [];
+    _args;
+    _hydrationTimeout;
+    _handler;
+    /** @internal Cached delegate built on first access to PromptBuilder methods */
+    _delegate;
+    constructor(name) {
+        this._name = name;
+    }
+    // ── Chainable Setters ────────────────────────────────
+    /**
+     * Set a human-readable title for UI display.
+     *
+     * @param title - The prompt title
+     * @returns `this` for chaining
+     */
+    title(title) {
+        this._title = title;
+        this._delegate = undefined;
+        return this;
+    }
+    /**
+     * Set the prompt description shown in the slash command palette.
+     *
+     * @param description - Human-readable description
+     * @returns `this` for chaining
+     */
+    describe(description) {
+        this._description = description;
+        this._delegate = undefined;
+        return this;
+    }
+    /**
+     * Set icons for light/dark themes.
+     *
+     * @param icons - Icon paths for light and/or dark themes
+     * @returns `this` for chaining
+     */
+    icons(icons) {
+        this._icons = icons;
+        this._delegate = undefined;
+        return this;
+    }
+    /**
+     * Set capability tags for selective exposure.
+     *
+     * @param tags - Tag strings for filtering
+     * @returns `this` for chaining
+     */
+    tags(...tags) {
+        this._tags = tags;
+        this._delegate = undefined;
+        return this;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    input(schemaOrParams) {
+        this._args = schemaOrParams;
+        this._delegate = undefined;
+        return this;
+    }
+    /**
+     * Add middleware to the prompt's execution pipeline.
+     *
+     * Middleware runs in registration order around the handler
+     * (same onion model as tool middleware).
+     *
+     * @param fns - Middleware functions
+     * @returns `this` for chaining
+     */
+    use(...fns) {
+        this._middlewares.push(...fns);
+        this._delegate = undefined;
+        return this;
+    }
+    /**
+     * Set the maximum hydration time in milliseconds.
+     *
+     * If the handler doesn't complete within this time,
+     * the framework returns a graceful SYSTEM ALERT.
+     *
+     * @param ms - Timeout in milliseconds
+     * @returns `this` for chaining
+     */
+    timeout(ms) {
+        this._hydrationTimeout = ms;
+        this._delegate = undefined;
+        return this;
+    }
+    /**
+     * Set the hydration handler.
+     *
+     * This is the terminal method — after calling `.handler()`,
+     * the builder is ready to be registered.
+     *
+     * @param fn - Handler function receiving `(ctx, args)` → `PromptResult`
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * .handler(async (ctx, { name }) => ({
+     *     messages: [PromptMessage.user(`Hello ${name}!`)],
+     * }))
+     * ```
+     */
+    handler(fn) {
+        this._handler = fn;
+        this._delegate = undefined;
+        return this;
+    }
+    // ── PromptBuilder Interface (delegation) ─────────────
+    /** @internal Build the underlying PromptBuilder delegate lazily */
+    _build() {
+        if (this._delegate)
+            return this._delegate;
+        if (!this._handler) {
+            throw new Error(`FluentPromptBuilder('${this._name}'): .handler() must be called before the prompt can be used.`);
+        }
+        this._delegate = definePrompt(this._name, {
+            title: this._title,
+            description: this._description,
+            icons: this._icons,
+            tags: this._tags.length > 0 ? this._tags : undefined,
+            middleware: this._middlewares.length > 0 ? this._middlewares : undefined,
+            args: this._args,
+            hydrationTimeout: this._hydrationTimeout,
+            handler: this._handler,
+        });
+        return this._delegate;
+    }
+    getName() {
+        return this._name;
+    }
+    getDescription() {
+        return this._description;
+    }
+    getTags() {
+        return this._tags;
+    }
+    hasMiddleware() {
+        return this._middlewares.length > 0;
+    }
+    getHydrationTimeout() {
+        return this._hydrationTimeout;
+    }
+    buildPromptDefinition() {
+        return this._build().buildPromptDefinition();
+    }
+    execute(ctx, args) {
+        return this._build().execute(ctx, args);
+    }
+}
+//# sourceMappingURL=FluentPromptBuilder.js.map

package/dist/prompt/FluentPromptBuilder.js.map

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

package/dist/prompt/index.d.ts

@@ -7,5 +7,6 @@
 export type { PromptMessagePayload, PromptResult, PromptParamDef, PromptParamsMap, PromptBuilder, PromptConfig, ToolInvocationResult, LoopbackContext, PromptInterceptorFn, InterceptorBuilder, PromptMeta, } from './types.js';
 export { PromptMessage } from './PromptMessage.js';
 export { definePrompt } from './definePrompt.js';
+export { FluentPromptBuilder } from './FluentPromptBuilder.js';
 export { assertFlatSchema, coercePromptArgs, } from './PromptExecutionPipeline.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompt/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACR,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,eAAe,EACf,aAAa,EACb,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,OAAO,EACH,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompt/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACR,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,eAAe,EACf,aAAa,EACb,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAG/D,OAAO,EACH,gBAAgB,EAChB,gBAAgB,GACnB,MAAM,8BAA8B,CAAC"}