@vinkius-core/mcp-fusion 2.5.0 → 2.7.0

package/dist/presenter/ZodDescriptionExtractor.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ZodDescriptionExtractor — Automatic Prompt Extraction from Zod .describe()
+ *
+ * Walks a Zod schema's AST and collects `.describe()` annotations from
+ * every field. These descriptions are injected as system rules via
+ * Context Tree-Shaking, eliminating the need for manual `systemRules`
+ * when the Zod schema already carries domain-specific constraints.
+ *
+ * This ensures documentation never drifts from the actual data shape:
+ * the single source of truth is the Zod `.describe()` annotation.
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   amount_cents: z.number().describe('CRITICAL: in CENTS. Divide by 100.'),
+ *   status: z.enum(['paid', 'pending']).describe('Always display with emoji'),
+ * });
+ *
+ * extractZodDescriptions(schema);
+ * // → ['amount_cents: CRITICAL: in CENTS. Divide by 100.',
+ * //    'status: Always display with emoji']
+ * ```
+ *
+ * @module
+ */
+import { type ZodType } from 'zod';
+/**
+ * Extract `.describe()` annotations from a Zod schema's fields.
+ *
+ * Walks the top-level `z.object()` shape and retrieves the description
+ * string from each field (after unwrapping wrappers like `z.optional()`,
+ * `z.nullable()`, `z.default()`, etc.).
+ *
+ * Returns an array of human-readable `"fieldName: description"` strings,
+ * ready to be injected as system rules.
+ *
+ * @param schema - A Zod schema (typically z.object, but safely handles non-objects)
+ * @returns Array of `"fieldName: description"` strings (empty if no descriptions found)
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   amount_cents: z.number().describe('CRITICAL: value is in CENTS. Divide by 100.'),
+ *   currency: z.string(), // No .describe() → skipped
+ *   status: z.enum(['paid', 'pending']).describe('Show with emoji'),
+ * });
+ *
+ * extractZodDescriptions(schema);
+ * // → ['amount_cents: CRITICAL: value is in CENTS. Divide by 100.',
+ * //    'status: Show with emoji']
+ * ```
+ */
+export declare function extractZodDescriptions(schema: ZodType): string[];
+//# sourceMappingURL=ZodDescriptionExtractor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ZodDescriptionExtractor.d.ts","sourceRoot":"","sources":["../../src/presenter/ZodDescriptionExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAqEnC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAehE"}

package/dist/presenter/ZodDescriptionExtractor.js

@@ -0,0 +1,131 @@
+/**
+ * ZodDescriptionExtractor — Automatic Prompt Extraction from Zod .describe()
+ *
+ * Walks a Zod schema's AST and collects `.describe()` annotations from
+ * every field. These descriptions are injected as system rules via
+ * Context Tree-Shaking, eliminating the need for manual `systemRules`
+ * when the Zod schema already carries domain-specific constraints.
+ *
+ * This ensures documentation never drifts from the actual data shape:
+ * the single source of truth is the Zod `.describe()` annotation.
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   amount_cents: z.number().describe('CRITICAL: in CENTS. Divide by 100.'),
+ *   status: z.enum(['paid', 'pending']).describe('Always display with emoji'),
+ * });
+ *
+ * extractZodDescriptions(schema);
+ * // → ['amount_cents: CRITICAL: in CENTS. Divide by 100.',
+ * //    'status: Always display with emoji']
+ * ```
+ *
+ * @module
+ */
+import {} from 'zod';
+// ── Extraction Logic ─────────────────────────────────────
+/**
+ * Recursively unwrap wrapper Zod nodes (optional, nullable, default, branded,
+ * readonly, effects, lazy, catches, pipes) to reach the inner schema.
+ * @internal
+ */
+function unwrap(node) {
+    const def = node._def;
+    if (!def)
+        return node;
+    const typeName = def.typeName ?? '';
+    const wrapperTypes = [
+        'ZodOptional', 'ZodNullable', 'ZodDefault', 'ZodBranded',
+        'ZodReadonly', 'ZodEffects', 'ZodLazy', 'ZodCatch', 'ZodPipeline',
+    ];
+    if (wrapperTypes.includes(typeName)) {
+        const inner = def.innerType ?? def.type ?? def.schema;
+        if (inner)
+            return unwrap(inner);
+    }
+    return node;
+}
+/**
+ * Get the shape record from a Zod object node.
+ * Supports both v3 (`_def.shape()`) and v4 (`_def.shape`) patterns.
+ * @internal
+ */
+function getShape(node) {
+    const def = node._def;
+    if (!def)
+        return undefined;
+    if (typeof def.shape === 'function') {
+        return def.shape();
+    }
+    if (typeof def.shape === 'object' && def.shape !== null) {
+        return def.shape;
+    }
+    return undefined;
+}
+/**
+ * Extract `.describe()` annotations from a Zod schema's fields.
+ *
+ * Walks the top-level `z.object()` shape and retrieves the description
+ * string from each field (after unwrapping wrappers like `z.optional()`,
+ * `z.nullable()`, `z.default()`, etc.).
+ *
+ * Returns an array of human-readable `"fieldName: description"` strings,
+ * ready to be injected as system rules.
+ *
+ * @param schema - A Zod schema (typically z.object, but safely handles non-objects)
+ * @returns Array of `"fieldName: description"` strings (empty if no descriptions found)
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   amount_cents: z.number().describe('CRITICAL: value is in CENTS. Divide by 100.'),
+ *   currency: z.string(), // No .describe() → skipped
+ *   status: z.enum(['paid', 'pending']).describe('Show with emoji'),
+ * });
+ *
+ * extractZodDescriptions(schema);
+ * // → ['amount_cents: CRITICAL: value is in CENTS. Divide by 100.',
+ * //    'status: Show with emoji']
+ * ```
+ */
+export function extractZodDescriptions(schema) {
+    const node = schema;
+    const shape = getShape(node);
+    if (!shape)
+        return [];
+    const descriptions = [];
+    for (const [key, fieldNode] of Object.entries(shape)) {
+        const desc = resolveDescription(fieldNode);
+        if (desc) {
+            descriptions.push(`${key}: ${desc}`);
+        }
+    }
+    return descriptions;
+}
+/**
+ * Resolve the description from a field node by unwrapping wrappers.
+ *
+ * Priority:
+ * 1. Outermost `.description` (Zod v4 style)
+ * 2. `_def.description` (Zod v3 style)
+ * 3. Unwrapped inner node's description
+ * @internal
+ */
+function resolveDescription(node) {
+    // Check outermost description first
+    if (node.description)
+        return node.description;
+    if (node._def?.description)
+        return node._def.description;
+    // Unwrap and check inner
+    const inner = unwrap(node);
+    if (inner !== node) {
+        if (inner.description)
+            return inner.description;
+        if (inner._def?.description)
+            return inner._def.description;
+    }
+    return undefined;
+}
+//# sourceMappingURL=ZodDescriptionExtractor.js.map

package/dist/presenter/ZodDescriptionExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZodDescriptionExtractor.js","sourceRoot":"","sources":["../../src/presenter/ZodDescriptionExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAgB,MAAM,KAAK,CAAC;AAwBnC,4DAA4D;AAE5D;;;;GAIG;AACH,SAAS,MAAM,CAAC,IAAa;IACzB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC;IACtB,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAEtB,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;IACpC,MAAM,YAAY,GAAG;QACjB,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY;QACxD,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa;KACpE,CAAC;IAEF,IAAI,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC;QACtD,IAAI,KAAK;YAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,SAAS,QAAQ,CAAC,IAAa;IAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC;IACtB,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAE3B,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QAClC,OAAO,GAAG,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QACtD,OAAO,GAAG,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,OAAO,SAAS,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAe;IAClD,MAAM,IAAI,GAAG,MAA4B,CAAC;IAC1C,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAEtB,MAAM,YAAY,GAAa,EAAE,CAAC;IAElC,KAAK,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,IAAI,EAAE,CAAC;YACP,YAAY,CAAC,IAAI,CAAC,GAAG,GAAG,KAAK,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC;IACL,CAAC;IAED,OAAO,YAAY,CAAC;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,kBAAkB,CAAC,IAAa;IACrC,oCAAoC;IACpC,IAAI,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC,WAAW,CAAC;IAC9C,IAAI,IAAI,CAAC,IAAI,EAAE,WAAW;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC;IAEzD,yBAAyB;IACzB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACjB,IAAI,KAAK,CAAC,WAAW;YAAE,OAAO,KAAK,CAAC,WAAW,CAAC;QAChD,IAAI,KAAK,CAAC,IAAI,EAAE,WAAW;YAAE,OAAO,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC;IAC/D,CAAC;IAED,OAAO,SAAS,CAAC;AACrB,CAAC"}

package/dist/presenter/definePresenter.d.ts

@@ -0,0 +1,172 @@
+/**
+ * definePresenter() — Declarative Presenter Definition
+ *
+ * Zero-friction object-config API for creating Presenters.
+ * Replaces the fluent builder pattern with a single object literal
+ * that enables instant Ctrl+Space autocomplete and zero generic noise.
+ *
+ * The `schema` field drives type inference: the `ui`, `rules`, and
+ * `suggestActions` callbacks automatically receive the inferred type,
+ * so the developer never writes a generic parameter manually.
+ *
+ * @example
+ * ```typescript
+ * import { definePresenter, ui } from '@vinkius-core/mcp-fusion';
+ * import { z } from 'zod';
+ *
+ * export const InvoicePresenter = definePresenter({
+ *   name: 'Invoice',
+ *   schema: z.object({
+ *     id: z.string(),
+ *     amount_cents: z.number().describe('CRITICAL: in CENTS. Divide by 100.'),
+ *     status: z.enum(['paid', 'pending']),
+ *   }),
+ *   rules: ['CRITICAL: Divide amount_cents by 100 before displaying.'],
+ *   ui: (inv) => [ui.echarts({ series: [{ type: 'gauge', data: [{ value: inv.amount_cents / 100 }] }] })],
+ *   suggestActions: (inv) =>
+ *     inv.status === 'pending'
+ *       ? [{ tool: 'billing.pay', reason: 'Offer immediate payment' }]
+ *       : [],
+ * });
+ * ```
+ *
+ * @module
+ */
+import { type ZodType } from 'zod';
+import { Presenter, type ActionSuggestion } from './Presenter.js';
+import { type UiBlock } from './ui.js';
+/**
+ * Agent limit configuration for cognitive guardrails.
+ */
+export interface AgentLimitDef {
+    /** Maximum items to keep when data is an array */
+    readonly max: number;
+    /** Callback that produces a warning block when items are truncated */
+    readonly onTruncate: (omittedCount: number) => UiBlock;
+}
+/**
+ * Embedded child Presenter definition for relational composition.
+ */
+export interface EmbedDef {
+    /** Property key in the parent data that contains the nested data */
+    readonly key: string;
+    /** The child Presenter to apply to the nested data */
+    readonly presenter: Presenter<unknown>;
+}
+/**
+ * Full declarative configuration for `definePresenter()`.
+ *
+ * @typeParam T - Inferred from the `schema` field's output type
+ */
+export interface PresenterConfig<T> {
+    /** Human-readable domain name (for debugging and introspection) */
+    readonly name: string;
+    /** Zod schema for data validation and field filtering */
+    readonly schema?: ZodType<T>;
+    /**
+     * System rules that travel with the data.
+     *
+     * - **Static**: `string[]` — always injected
+     * - **Dynamic**: `(data, ctx?) => (string | null)[]` — context-aware (RBAC, DLP, locale)
+     *
+     * Return `null` from dynamic rules to conditionally exclude them.
+     */
+    readonly rules?: readonly string[] | ((data: T, ctx?: unknown) => (string | null)[]);
+    /**
+     * UI blocks for a **single data item**.
+     *
+     * Return `null` for conditional blocks (filtered automatically).
+     */
+    readonly ui?: (item: T, ctx?: unknown) => (UiBlock | null)[];
+    /**
+     * Aggregated UI blocks for a **collection** (array) of items.
+     *
+     * Called once with the entire validated array. Prevents N individual
+     * charts from flooding the LLM's context.
+     */
+    readonly collectionUi?: (items: T[], ctx?: unknown) => (UiBlock | null)[];
+    /**
+     * Cognitive guardrail that truncates large collections.
+     *
+     * Protects against context DDoS by limiting returned array length
+     * and injecting a summary block.
+     */
+    readonly agentLimit?: AgentLimitDef;
+    /**
+     * HATEOAS-style next-action suggestions based on data state.
+     *
+     * Eliminates routing hallucinations by providing explicit next-step hints.
+     */
+    readonly suggestActions?: (data: T, ctx?: unknown) => ActionSuggestion[];
+    /**
+     * Embedded child Presenters for nested relational data.
+     *
+     * Define once, embed everywhere. Each embed's `key` is looked up on
+     * the parent data, and the child Presenter renders its own blocks/rules.
+     */
+    readonly embeds?: readonly EmbedDef[];
+    /**
+     * Automatically extract `.describe()` annotations from the Zod schema
+     * and merge them with `rules` as system rules.
+     *
+     * When `true` (the default), field-level `.describe()` annotations
+     * become system rules, ensuring documentation never drifts from the
+     * actual data shape. Set to `false` to opt out.
+     *
+     * @default true
+     */
+    readonly autoRules?: boolean;
+}
+/**
+ * Define a domain-level Presenter using a declarative config object.
+ *
+ * This is the recommended, zero-friction API. The `schema` field drives
+ * full type inference — `ui`, `rules`, and `suggestActions` callbacks
+ * all receive correctly-typed parameters without any explicit generics.
+ *
+ * @typeParam TSchema - Zod type (inferred from the `schema` field)
+ * @param config - Declarative presenter configuration
+ * @returns A fully-configured {@link Presenter} ready for use
+ *
+ * @example
+ * ```typescript
+ * // Minimal
+ * const TaskPresenter = definePresenter({
+ *   name: 'Task',
+ *   schema: z.object({ id: z.string(), title: z.string(), done: z.boolean() }),
+ *   rules: ['Use ✅ for done, 🔄 for in-progress.'],
+ *   ui: (task) => [ui.markdown(`**${task.title}**: ${task.done ? '✅' : '🔄'}`)],
+ * });
+ *
+ * // With embeds, agent limit, and dynamic rules
+ * const OrderPresenter = definePresenter({
+ *   name: 'Order',
+ *   schema: orderSchema,
+ *   rules: (order, ctx) => [
+ *     ctx?.locale === 'pt-BR' ? 'Formate datas em DD/MM/YYYY' : null,
+ *   ],
+ *   agentLimit: { max: 100, onTruncate: (n) => ui.summary(`⚠️ ${n} orders hidden`) },
+ *   embeds: [{ key: 'customer', presenter: CustomerPresenter }],
+ *   suggestActions: (order) =>
+ *     order.status === 'pending'
+ *       ? [{ tool: 'orders.approve', reason: 'Ready for approval' }]
+ *       : [],
+ * });
+ * ```
+ *
+ * @see {@link createPresenter} for the legacy fluent builder API
+ * @see {@link Presenter} for the full Presenter class documentation
+ */
+export declare function definePresenter<TSchema extends ZodType>(config: PresenterConfig<TSchema['_output']> & {
+    schema: TSchema;
+}): Presenter<TSchema['_output']>;
+/**
+ * Define a Presenter without a schema (untyped data passthrough).
+ *
+ * @param config - Configuration without a schema field
+ * @returns A Presenter that passes data through without validation
+ */
+export declare function definePresenter(config: PresenterConfig<unknown> & {
+    schema?: undefined;
+}): Presenter<unknown>;
+//# sourceMappingURL=definePresenter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"definePresenter.d.ts","sourceRoot":"","sources":["../../src/presenter/definePresenter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAKvC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1D;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACrB,oEAAoE;IACpE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,yDAAyD;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAE7B;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;IAErF;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;IAE7D;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;IAE1E;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;IAEpC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,gBAAgB,EAAE,CAAC;IAEzE;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAEtC;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAChC;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS,OAAO,EACnD,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAClE,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;AAEjC;;;;;GAKG;AACH,wBAAgB,eAAe,CAC3B,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG;IAAE,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GAC1D,SAAS,CAAC,OAAO,CAAC,CAAC"}

package/dist/presenter/definePresenter.js

@@ -0,0 +1,96 @@
+/**
+ * definePresenter() — Declarative Presenter Definition
+ *
+ * Zero-friction object-config API for creating Presenters.
+ * Replaces the fluent builder pattern with a single object literal
+ * that enables instant Ctrl+Space autocomplete and zero generic noise.
+ *
+ * The `schema` field drives type inference: the `ui`, `rules`, and
+ * `suggestActions` callbacks automatically receive the inferred type,
+ * so the developer never writes a generic parameter manually.
+ *
+ * @example
+ * ```typescript
+ * import { definePresenter, ui } from '@vinkius-core/mcp-fusion';
+ * import { z } from 'zod';
+ *
+ * export const InvoicePresenter = definePresenter({
+ *   name: 'Invoice',
+ *   schema: z.object({
+ *     id: z.string(),
+ *     amount_cents: z.number().describe('CRITICAL: in CENTS. Divide by 100.'),
+ *     status: z.enum(['paid', 'pending']),
+ *   }),
+ *   rules: ['CRITICAL: Divide amount_cents by 100 before displaying.'],
+ *   ui: (inv) => [ui.echarts({ series: [{ type: 'gauge', data: [{ value: inv.amount_cents / 100 }] }] })],
+ *   suggestActions: (inv) =>
+ *     inv.status === 'pending'
+ *       ? [{ tool: 'billing.pay', reason: 'Offer immediate payment' }]
+ *       : [],
+ * });
+ * ```
+ *
+ * @module
+ */
+import {} from 'zod';
+import { Presenter } from './Presenter.js';
+import {} from './ui.js';
+import { extractZodDescriptions } from './ZodDescriptionExtractor.js';
+/**
+ * Implementation
+ * @internal
+ */
+export function definePresenter(config) {
+    const presenter = new Presenter(config.name);
+    if (config.schema) {
+        presenter.schema(config.schema);
+    }
+    // ── Zod-Driven Prompts: auto-extract .describe() annotations ──
+    const autoRules = config.autoRules !== false; // default: true
+    const zodDescriptions = (autoRules && config.schema)
+        ? extractZodDescriptions(config.schema)
+        : [];
+    if (config.rules) {
+        if (typeof config.rules === 'function') {
+            // Dynamic rules — wrap to prepend Zod descriptions
+            if (zodDescriptions.length > 0) {
+                const dynamicFn = config.rules;
+                presenter.systemRules((data, ctx) => [
+                    ...zodDescriptions,
+                    ...dynamicFn(data, ctx),
+                ]);
+            }
+            else {
+                presenter.systemRules(config.rules);
+            }
+        }
+        else {
+            // Static rules — merge with Zod descriptions
+            const merged = [...zodDescriptions, ...config.rules];
+            presenter.systemRules(merged);
+        }
+    }
+    else if (zodDescriptions.length > 0) {
+        // No explicit rules — use Zod descriptions alone
+        presenter.systemRules(zodDescriptions);
+    }
+    if (config.ui) {
+        presenter.uiBlocks(config.ui);
+    }
+    if (config.collectionUi) {
+        presenter.collectionUiBlocks(config.collectionUi);
+    }
+    if (config.agentLimit) {
+        presenter.agentLimit(config.agentLimit.max, config.agentLimit.onTruncate);
+    }
+    if (config.suggestActions) {
+        presenter.suggestActions(config.suggestActions);
+    }
+    if (config.embeds) {
+        for (const embed of config.embeds) {
+            presenter.embed(embed.key, embed.presenter);
+        }
+    }
+    return presenter;
+}
+//# sourceMappingURL=definePresenter.js.map

package/dist/presenter/definePresenter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definePresenter.js","sourceRoot":"","sources":["../../src/presenter/definePresenter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAAgB,MAAM,KAAK,CAAC;AACnC,OAAO,EAAE,SAAS,EAAyB,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAgB,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAyJtE;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAgC;IAC5D,MAAM,SAAS,GAAG,IAAI,SAAS,CAAU,MAAM,CAAC,IAAI,CAAC,CAAC;IAEtD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAChB,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAED,iEAAiE;IACjE,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,KAAK,KAAK,CAAC,CAAC,gBAAgB;IAC9D,MAAM,eAAe,GAAG,CAAC,SAAS,IAAI,MAAM,CAAC,MAAM,CAAC;QAChD,CAAC,CAAC,sBAAsB,CAAC,MAAM,CAAC,MAAM,CAAC;QACvC,CAAC,CAAC,EAAE,CAAC;IAET,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YACrC,mDAAmD;YACnD,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC7B,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC;gBAC/B,SAAS,CAAC,WAAW,CAAC,CAAC,IAAa,EAAE,GAAa,EAAE,EAAE,CAAC;oBACpD,GAAG,eAAe;oBAClB,GAAG,SAAS,CAAC,IAAI,EAAE,GAAG,CAAC;iBAC1B,CAAC,CAAC;YACP,CAAC;iBAAM,CAAC;gBACJ,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC,KAA4D,CAAC,CAAC;YAC/F,CAAC;QACL,CAAC;aAAM,CAAC;YACJ,6CAA6C;YAC7C,MAAM,MAAM,GAAG,CAAC,GAAG,eAAe,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YACrD,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;IACL,CAAC;SAAM,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,iDAAiD;QACjD,SAAS,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACZ,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QACtB,SAAS,CAAC,kBAAkB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACtD,CAAC;IAED,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACpB,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;QACxB,SAAS,CAAC,cAAc,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAChB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAChC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;QAChD,CAAC;IACL,CAAC;IAED,OAAO,SAAS,CAAC;AACrB,CAAC"}

package/dist/presenter/index.d.ts

@@ -8,6 +8,9 @@ export type { ActionSuggestion } from './ResponseBuilder.js';
 export { ui } from './ui.js';
 export type { UiBlock } from './ui.js';
 export { Presenter, createPresenter, isPresenter } from './Presenter.js';
+export { definePresenter } from './definePresenter.js';
+export type { PresenterConfig, AgentLimitDef, EmbedDef } from './definePresenter.js';
+export { extractZodDescriptions } from './ZodDescriptionExtractor.js';
 export { PresenterValidationError } from './PresenterValidationError.js';
 export { postProcessResult, isToolResponse } from './PostProcessor.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/presenter/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACpF,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGzE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAGzE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/presenter/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACpF,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG7D,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGzE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGrF,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAGzE,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/presenter/index.js

@@ -9,6 +9,10 @@ export { ResponseBuilder, response, isResponseBuilder } from './ResponseBuilder.
 export { ui } from './ui.js';
 // ── Presenter ────────────────────────────────────────────
 export { Presenter, createPresenter, isPresenter } from './Presenter.js';
+// ── Declarative Presenter ────────────────────────────────
+export { definePresenter } from './definePresenter.js';
+// ── Zod Description Extraction ───────────────────────────
+export { extractZodDescriptions } from './ZodDescriptionExtractor.js';
 // ── Validation Error ─────────────────────────────────────
 export { PresenterValidationError } from './PresenterValidationError.js';
 // ── Post-Processing ──────────────────────────────────────

package/dist/presenter/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/presenter/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,4DAA4D;AAC5D,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGpF,4DAA4D;AAC5D,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAG7B,4DAA4D;AAC5D,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEzE,4DAA4D;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,4DAA4D;AAC5D,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/presenter/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,4DAA4D;AAC5D,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGpF,4DAA4D;AAC5D,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAG7B,4DAA4D;AAC5D,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEzE,4DAA4D;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,4DAA4D;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAEtE,4DAA4D;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,4DAA4D;AAC5D,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/server/DevServer.d.ts

@@ -0,0 +1,96 @@
+/** Duck-typed MCP server that supports notifications */
+interface McpServerLike {
+    notification(notification: {
+        method: string;
+    }): Promise<void>;
+    sendNotification?(notification: {
+        method: string;
+    }): Promise<void>;
+}
+/** Duck-typed ToolRegistry */
+interface ToolRegistryLike {
+    register(builder: unknown): void;
+    getBuilders?(): unknown[];
+}
+/**
+ * Configuration for the development server.
+ */
+export interface DevServerConfig {
+    /**
+     * Directory to watch for file changes.
+     * Relative paths are resolved from the current working directory.
+     */
+    readonly dir: string;
+    /**
+     * File extension filter for watched files.
+     * @default ['.ts', '.js', '.mjs', '.mts']
+     */
+    readonly extensions?: string[];
+    /**
+     * Debounce interval in milliseconds.
+     * Prevents rapid-fire reloads when editors save multiple files.
+     * @default 300
+     */
+    readonly debounce?: number;
+    /**
+     * Setup callback invoked on every reload.
+     *
+     * Receives a fresh ToolRegistry. The callback should:
+     * 1. Import/define all tools
+     * 2. Register them on the registry
+     *
+     * This is called on initial startup and on every file change.
+     */
+    readonly setup: (registry: ToolRegistryLike) => void | Promise<void>;
+    /**
+     * Optional callback when a reload occurs.
+     * Useful for logging or triggering downstream updates.
+     */
+    readonly onReload?: (changedFile: string) => void;
+    /**
+     * Optional MCP server reference for sending tool list change notifications.
+     * When provided, the dev server sends `notifications/tools/list_changed`
+     * on every reload, so the LLM client picks up changes automatically.
+     */
+    readonly server?: McpServerLike;
+}
+/**
+ * Interface for a running dev server instance.
+ */
+export interface DevServer {
+    /** Start watching and perform initial load */
+    start(): Promise<void>;
+    /** Stop the watcher and clean up */
+    stop(): void;
+    /** Force a manual reload (useful from CLI) */
+    reload(reason?: string): Promise<void>;
+}
+/**
+ * Create an HMR-enabled MCP development server.
+ *
+ * Watches a directory for file changes and automatically reloads
+ * tools, then notifies the connected MCP client via the native
+ * `notifications/tools/list_changed` notification.
+ *
+ * @param config - Dev server configuration
+ * @returns A {@link DevServer} instance with start/stop/reload controls
+ *
+ * @example
+ * ```typescript
+ * import { createDevServer, autoDiscover, ToolRegistry } from '@vinkius-core/mcp-fusion';
+ *
+ * const devServer = createDevServer({
+ *   dir: './src/tools',
+ *   setup: async (registry) => {
+ *     await autoDiscover(registry, './src/tools');
+ *   },
+ *   onReload: (file) => console.log(`[HMR] Reloaded: ${file}`),
+ * });
+ *
+ * await devServer.start();
+ * // File changes → auto-reload → LLM client gets notification
+ * ```
+ */
+export declare function createDevServer(config: DevServerConfig): DevServer;
+export {};
+//# sourceMappingURL=DevServer.d.ts.map

package/dist/server/DevServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DevServer.d.ts","sourceRoot":"","sources":["../../src/server/DevServer.ts"],"names":[],"mappings":"AAkDA,wDAAwD;AACxD,UAAU,aAAa;IACnB,YAAY,CAAC,YAAY,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,gBAAgB,CAAC,CAAC,YAAY,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AAED,8BAA8B;AAC9B,UAAU,gBAAgB;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAEjC,WAAW,CAAC,IAAI,OAAO,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAElD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB,8CAA8C;IAC9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,oCAAoC;IACpC,IAAI,IAAI,IAAI,CAAC;IACb,8CAA8C;IAC9C,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAuCD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CA+FlE"}