@vurb/core 3.2.0

package/dist/presenter/ResponseBuilder.js

@@ -0,0 +1,374 @@
+/**
+ * ResponseBuilder — Fluent Multi-Block Response Composer
+ *
+ * Standalone builder for composing rich, multi-content-block MCP
+ * responses. Each semantic layer (data, UI blocks, system rules,
+ * LLM hints) becomes a separate content block in the response array,
+ * following MCP's multimodal content design.
+ *
+ * Inspired by Next.js's `NextResponse` — the builder is a standalone
+ * function, keeping `ctx` pure and the response testable.
+ *
+ * @example
+ * ```typescript
+ * import { response, ui } from 'vurb';
+ *
+ * // Simple data response (equivalent to success())
+ * return response({ id: '123', amount: 4500 }).build();
+ *
+ * // Rich multi-block response
+ * return response(data)
+ *     .uiBlock(ui.echarts(chartConfig))
+ *     .llmHint('Divide amounts by 100 before displaying.')
+ *     .systemRules(['Use $ for currency', 'Emojis: ✅ Paid'])
+ *     .build();
+ * ```
+ *
+ * @see {@link response} for the factory function
+ * @see {@link Presenter} for automatic response composition
+ *
+ * @module
+ */
+import {} from '../core/response.js';
+import {} from './ui.js';
+import { MVA_META_SYMBOL } from '../testing/MvaMetaSymbol.js';
+import {} from '../core/serialization/JsonSerializer.js';
+// ── Brand ────────────────────────────────────────────────
+const RESPONSE_BUILDER_BRAND = 'VurbResponseBuilder';
+/**
+ * Check if a value is a {@link ResponseBuilder} instance.
+ *
+ * Used by the execution pipeline to auto-call `.build()` when
+ * a handler returns a builder without explicitly calling `.build()`.
+ *
+ * @param value - Any value returned by a handler
+ * @returns `true` if the value is a ResponseBuilder
+ */
+export function isResponseBuilder(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__brand' in value &&
+        value.__brand === RESPONSE_BUILDER_BRAND);
+}
+// ── ResponseBuilder ──────────────────────────────────────
+/**
+ * Fluent builder for multi-content-block MCP responses.
+ *
+ * Each method appends a semantic layer. The final `.build()` compiles
+ * all layers into an array of `{ type: "text", text: "..." }` blocks,
+ * one per layer, following MCP's multimodal content specification.
+ *
+ * Content block order:
+ * 1. Data (JSON-serialized raw data)
+ * 2. UI Blocks (fenced code blocks from Presenter/manual)
+ * 3. Raw Blocks (merged from embedded child Presenters)
+ * 4. LLM Hints (inline directives)
+ * 5. System Rules (domain-level `[DOMAIN RULES]` block)
+ * 6. Action Suggestions (HATEOAS-style `[SYSTEM HINT]` block)
+ *
+ * @see {@link response} for the factory function
+ */
+export class ResponseBuilder {
+    /** @internal Brand for instanceof-free detection in the pipeline */
+    __brand = RESPONSE_BUILDER_BRAND;
+    _data;
+    _uiBlocks = [];
+    _hints = [];
+    _rules = [];
+    _suggestions = [];
+    _rawBlocks = [];
+    /** @internal Use {@link response} factory instead */
+    constructor(data, compiledStringify) {
+        this._data = typeof data === 'string'
+            ? (data.length > 0 ? data : 'OK')
+            : (compiledStringify ? compiledStringify(data) : JSON.stringify(data, null, 2));
+    }
+    uiBlock(blockOrType, content) {
+        if (typeof blockOrType === 'object') {
+            this._uiBlocks.push(blockOrType);
+        }
+        else {
+            this._uiBlocks.push({ type: blockOrType, content: content });
+        }
+        return this;
+    }
+    /**
+     * Append pre-built UI blocks (from a Presenter's SSR layer).
+     *
+     * @param blocks - Array of {@link UiBlock} objects
+     * @returns `this` for chaining
+     *
+     * @internal Used by the Presenter engine
+     */
+    uiBlocks(blocks) {
+        this._uiBlocks.push(...blocks);
+        return this;
+    }
+    /**
+     * Append an inline LLM hint to the response.
+     *
+     * Hints are action-specific directives that guide the LLM's
+     * behavior for this particular response. Unlike system rules,
+     * hints are typically added manually in handlers for dynamic context.
+     *
+     * @param hint - Directive text for the LLM
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * response(invoice)
+     *     .llmHint('This client has an overdue balance. Mention it.')
+     *     .build();
+     * ```
+     */
+    llmHint(hint) {
+        this._hints.push(hint);
+        return this;
+    }
+    /**
+     * Append domain-level system rules to the response.
+     *
+     * Rules are JIT context directives that travel with the data,
+     * eliminating the need for bloated system prompts. They are
+     * rendered as a `[DOMAIN RULES]` block in the response.
+     *
+     * @param rules - Array of rule strings
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * response(data)
+     *     .systemRules([
+     *         'CRITICAL: amounts are in CENTS — divide by 100.',
+     *         'Use emojis: ✅ Paid, ⚠️ Pending.',
+     *     ])
+     *     .build();
+     * ```
+     */
+    systemRules(rules) {
+        this._rules.push(...rules);
+        return this;
+    }
+    /**
+     * Append HATEOAS-style action suggestions to the response.
+     *
+     * Generates a `[SYSTEM HINT]` block with recommended next tools,
+     * guiding the AI through the business state machine.
+     *
+     * @param suggestions - Array of action suggestions
+     * @returns `this` for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.systemHint([
+     *     { tool: 'billing.pay', reason: 'Offer immediate payment' },
+     * ]);
+     * ```
+     */
+    systemHint(suggestions) {
+        this._suggestions.push(...suggestions);
+        return this;
+    }
+    /**
+     * Append a raw text block to the response.
+     *
+     * Used internally by Presenter composition (`.embed()`) to merge
+     * child Presenter blocks into the parent response.
+     *
+     * @param text - Raw text content
+     * @returns `this` for chaining
+     * @internal
+     */
+    rawBlock(text) {
+        this._rawBlocks.push(text);
+        return this;
+    }
+    // ── Introspection (for cross-module composition) ─────
+    /**
+     * Get the serialized data payload.
+     *
+     * Returns the JSON-stringified (or raw string) data
+     * that was passed to the constructor.
+     *
+     * @returns The data string
+     *
+     * @remarks Used by {@link PromptMessage.fromView} to decompose
+     * a Presenter view into prompt messages without calling `.build()`.
+     */
+    getData() {
+        return this._data;
+    }
+    /**
+     * Get the accumulated domain rules.
+     *
+     * @returns Read-only array of rule strings
+     */
+    getRules() {
+        return this._rules;
+    }
+    /**
+     * Get the accumulated UI blocks.
+     *
+     * @returns Read-only array of UI blocks
+     */
+    getUiBlocks() {
+        return this._uiBlocks;
+    }
+    /**
+     * Get the accumulated LLM hints.
+     *
+     * @returns Read-only array of hint strings
+     */
+    getHints() {
+        return this._hints;
+    }
+    /**
+     * Get the accumulated action suggestions.
+     *
+     * @returns Read-only array of action suggestions
+     */
+    getSuggestions() {
+        return this._suggestions;
+    }
+    // ── Compilation ──────────────────────────────────────
+    /**
+     * Compile all layers into a multi-block MCP `ToolResponse`.
+     *
+     * Block order:
+     * 1. **Data** — JSON-serialized raw data
+     * 2. **UI Blocks** — one content entry per UI block,
+     *    each with a `[SYSTEM]` pass-through instruction
+     * 3. **Hints** — inline LLM directives
+     * 4. **Rules** — domain-level `[DOMAIN RULES]` block
+     *
+     * @returns A valid MCP {@link ToolResponse}
+     */
+    build() {
+        const content = [];
+        // Block 1: Data
+        content.push({ type: 'text', text: this._data });
+        // Block 2: UI Blocks — XML semantic boundary for pass-through rendering
+        for (const block of this._uiBlocks) {
+            content.push({
+                type: 'text',
+                text: `<ui_passthrough type="${block.type}">\n${block.content}\n</ui_passthrough>`,
+            });
+        }
+        // Block 3: Raw blocks (from embedded child Presenters)
+        for (const raw of this._rawBlocks) {
+            content.push({ type: 'text', text: raw });
+        }
+        // Block 4: LLM Directives — XML semantic boundary
+        if (this._hints.length > 0) {
+            const hintsText = '<llm_directives>\n' +
+                this._hints.map(h => `- ${h}`).join('\n') +
+                '\n</llm_directives>';
+            content.push({ type: 'text', text: hintsText });
+        }
+        // Block 5: Domain Rules — XML semantic boundary
+        if (this._rules.length > 0) {
+            const rulesText = '<domain_rules>\n' +
+                this._rules.map(r => `- ${r}`).join('\n') +
+                '\n</domain_rules>';
+            content.push({ type: 'text', text: rulesText });
+        }
+        // Block 6: Action Suggestions (HATEOAS) — XML semantic boundary
+        if (this._suggestions.length > 0) {
+            const suggestionsText = '<action_suggestions>\n' +
+                this._suggestions.map(s => `- ${s.tool}: ${s.reason}`).join('\n') +
+                '\n</action_suggestions>';
+            content.push({ type: 'text', text: suggestionsText });
+        }
+        const response = { content };
+        // ── MVA Meta Backdoor (Testing) ──────────────────
+        // Attach structured MVA layers via Symbol — invisible to
+        // JSON.stringify (MCP transport), readable by VurbTester.
+        let parsedData;
+        try {
+            parsedData = JSON.parse(this._data);
+        }
+        catch {
+            parsedData = this._data;
+        }
+        response[MVA_META_SYMBOL] = {
+            data: parsedData,
+            systemRules: this._rules,
+            uiBlocks: this._uiBlocks,
+        };
+        return response;
+    }
+}
+// ── Factory ──────────────────────────────────────────────
+/**
+ * Create a new response builder for composing multi-block MCP responses.
+ *
+ * This is the **recommended standalone function** for building rich
+ * responses with UI blocks, LLM hints, and system rules. It keeps
+ * the handler's `ctx` pure — no framework methods injected.
+ *
+ * For simple responses, continue using {@link success} and {@link error}.
+ * Use `response()` when you need JIT context, UI blocks, or domain rules.
+ *
+ * @param data - A string message or any JSON-serializable object
+ * @returns A new {@link ResponseBuilder} for chaining
+ *
+ * @example
+ * ```typescript
+ * import { response, ui } from 'vurb';
+ *
+ * // Simple (equivalent to success())
+ * return response('Task created').build();
+ *
+ * // Rich multi-block response
+ * return response(sprintData)
+ *     .uiBlock(ui.echarts(burndownConfig))
+ *     .llmHint('Summarize the sprint progress analytically.')
+ *     .systemRules(['Use tables for task lists.'])
+ *     .build();
+ * ```
+ *
+ * @see {@link ResponseBuilder} for all available methods
+ * @see {@link Presenter} for automatic response composition
+ */
+export function response(data) {
+    return new ResponseBuilder(data);
+}
+/**
+ * Build a complete response in one call.
+ *
+ * Shorthand for `response(data).build()` — the fastest path
+ * to a valid multi-block response.
+ *
+ * @param data - A string message or JSON-serializable object
+ * @returns A ready-to-return {@link ToolResponse}
+ *
+ * @example
+ * ```typescript
+ * return response.ok('Task created');
+ * return response.ok({ id: '123', name: 'Acme' });
+ * ```
+ */
+response.ok = function ok(data) {
+    return new ResponseBuilder(data).build();
+};
+/**
+ * Build a response with domain rules in one call.
+ *
+ * Shorthand for `response(data).systemRules(rules).build()`.
+ *
+ * @param data - A string message or JSON-serializable object
+ * @param rules - Array of domain rule strings
+ * @returns A ready-to-return {@link ToolResponse}
+ *
+ * @example
+ * ```typescript
+ * return response.withRules(invoiceData, [
+ *     'CRITICAL: amounts are in CENTS — divide by 100.',
+ *     'Use emojis: ✅ Paid, ⚠️ Pending.',
+ * ]);
+ * ```
+ */
+response.withRules = function withRules(data, rules) {
+    return new ResponseBuilder(data).systemRules(rules).build();
+};
+//# sourceMappingURL=ResponseBuilder.js.map

package/dist/presenter/ResponseBuilder.js.map

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

package/dist/presenter/SelectUtils.d.ts

@@ -0,0 +1,78 @@
+/**
+ * SelectUtils — Zod Reflection & Shallow Field Filter
+ *
+ * Utilities for the `_select` context window optimization feature.
+ *
+ * - `extractZodKeys()`: Recursively unwraps Zod wrappers (Optional,
+ *   Nullable, Default, Effects, Array) to reach the inner ZodObject
+ *   and extract its top-level keys. Fails gracefully (returns [])
+ *   for schemas without a discoverable shape.
+ *
+ * - `pickFields()`: Shallow (top-level only) field filter. Keeps
+ *   only the keys requested by the AI's `_select` parameter.
+ *   Nested objects are returned whole — no recursive GraphQL-style
+ *   traversal. This resolves 95% of real-world overfetching.
+ *
+ * @module
+ * @internal
+ */
+import { type ZodType } from 'zod';
+/**
+ * Recursively unwrap a Zod schema to extract the top-level object keys.
+ *
+ * Peels through layers of modifiers (Optional → Nullable → Default →
+ * Effects → Array) until it finds a ZodObject, then returns
+ * `Object.keys(shape)`.
+ *
+ * Returns `[]` for schemas that don't resolve to an object shape
+ * (e.g. `z.string()`, `z.any()`, `z.record()`), which gracefully
+ * disables `_select` injection for that Presenter.
+ *
+ * @param schema - Any Zod schema (ZodType)
+ * @returns Array of top-level key names, or `[]` if not extractable
+ *
+ * @example
+ * ```typescript
+ * extractZodKeys(z.object({ id: z.string(), name: z.string() }))
+ * // → ['id', 'name']
+ *
+ * extractZodKeys(z.object({ id: z.string() }).optional().array())
+ * // → ['id']
+ *
+ * extractZodKeys(z.string())
+ * // → []
+ * ```
+ */
+export declare function extractZodKeys(schema: ZodType): string[];
+/**
+ * Shallow (top-level only) field picker.
+ *
+ * Keeps only the keys present in `selectSet`. Nested objects are
+ * returned whole — no recursive path traversal. This is by design:
+ * the `_select` enum only lists root-level keys, matching 95% of
+ * real-world overfetching scenarios with O(1) complexity.
+ *
+ * @param data - The validated object to filter
+ * @param selectSet - Set of top-level keys to keep
+ * @returns A new object with only the selected keys
+ *
+ * @example
+ * ```typescript
+ * pickFields({ id: '1', status: 'paid', amount: 100 }, new Set(['status']))
+ * // → { status: 'paid' }
+ * ```
+ */
+export declare function pickFields(data: Record<string, unknown>, selectSet: Set<string>): Record<string, unknown>;
+/**
+ * Apply `_select` filtering to validated data.
+ *
+ * Handles both single objects and arrays. When `isArray` is true,
+ * each item in the array is filtered independently.
+ *
+ * @param data - Validated data (single object or array)
+ * @param selectFields - Array of top-level keys to keep
+ * @param isArray - Whether `data` is an array
+ * @returns The filtered data (same shape as input, fewer fields)
+ */
+export declare function applySelectFilter<T>(data: T | T[], selectFields: string[], isArray: boolean): T | T[];
+//# sourceMappingURL=SelectUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SelectUtils.d.ts","sourceRoot":"","sources":["../../src/presenter/SelectUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAInC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAqDxD;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,GACvB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAC/B,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,EACb,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,EAAE,OAAO,GACjB,CAAC,GAAG,CAAC,EAAE,CAUT"}

package/dist/presenter/SelectUtils.js

@@ -0,0 +1,141 @@
+/**
+ * SelectUtils — Zod Reflection & Shallow Field Filter
+ *
+ * Utilities for the `_select` context window optimization feature.
+ *
+ * - `extractZodKeys()`: Recursively unwraps Zod wrappers (Optional,
+ *   Nullable, Default, Effects, Array) to reach the inner ZodObject
+ *   and extract its top-level keys. Fails gracefully (returns [])
+ *   for schemas without a discoverable shape.
+ *
+ * - `pickFields()`: Shallow (top-level only) field filter. Keeps
+ *   only the keys requested by the AI's `_select` parameter.
+ *   Nested objects are returned whole — no recursive GraphQL-style
+ *   traversal. This resolves 95% of real-world overfetching.
+ *
+ * @module
+ * @internal
+ */
+import {} from 'zod';
+// ── Zod Key Extraction ───────────────────────────────────
+/**
+ * Recursively unwrap a Zod schema to extract the top-level object keys.
+ *
+ * Peels through layers of modifiers (Optional → Nullable → Default →
+ * Effects → Array) until it finds a ZodObject, then returns
+ * `Object.keys(shape)`.
+ *
+ * Returns `[]` for schemas that don't resolve to an object shape
+ * (e.g. `z.string()`, `z.any()`, `z.record()`), which gracefully
+ * disables `_select` injection for that Presenter.
+ *
+ * @param schema - Any Zod schema (ZodType)
+ * @returns Array of top-level key names, or `[]` if not extractable
+ *
+ * @example
+ * ```typescript
+ * extractZodKeys(z.object({ id: z.string(), name: z.string() }))
+ * // → ['id', 'name']
+ *
+ * extractZodKeys(z.object({ id: z.string() }).optional().array())
+ * // → ['id']
+ *
+ * extractZodKeys(z.string())
+ * // → []
+ * ```
+ */
+export function extractZodKeys(schema) {
+    let current = schema;
+    // Safety: iterate up to 20 layers to prevent infinite loops
+    // on pathological or circular Zod constructions.
+    for (let depth = 0; depth < 20; depth++) {
+        if (!current || typeof current !== 'object')
+            return [];
+        const def = current._def;
+        if (!def)
+            return [];
+        const typeName = def['typeName'];
+        switch (typeName) {
+            // ── Modifier Wrappers ─────────────────────────
+            case 'ZodOptional':
+            case 'ZodNullable':
+            case 'ZodDefault':
+            case 'ZodReadonly':
+            case 'ZodBranded':
+            case 'ZodCatch':
+            case 'ZodLazy':
+                current = def['innerType'];
+                continue;
+            // ── Effects (Refine, Transform, Preprocess) ───
+            case 'ZodEffects':
+                current = def['schema'];
+                continue;
+            // ── Array → extract element type ──────────────
+            case 'ZodArray':
+                current = def['type'];
+                continue;
+            // ── Pipeline → follow through ─────────────────
+            case 'ZodPipeline':
+                current = def['out'];
+                continue;
+            // ── Object → extract keys ─────────────────────
+            case 'ZodObject': {
+                const shape = current.shape;
+                return shape ? Object.keys(shape) : [];
+            }
+            // ── Terminal: cannot extract keys ─────────────
+            default:
+                return [];
+        }
+    }
+    return [];
+}
+// ── Field Filtering ──────────────────────────────────────
+/**
+ * Shallow (top-level only) field picker.
+ *
+ * Keeps only the keys present in `selectSet`. Nested objects are
+ * returned whole — no recursive path traversal. This is by design:
+ * the `_select` enum only lists root-level keys, matching 95% of
+ * real-world overfetching scenarios with O(1) complexity.
+ *
+ * @param data - The validated object to filter
+ * @param selectSet - Set of top-level keys to keep
+ * @returns A new object with only the selected keys
+ *
+ * @example
+ * ```typescript
+ * pickFields({ id: '1', status: 'paid', amount: 100 }, new Set(['status']))
+ * // → { status: 'paid' }
+ * ```
+ */
+export function pickFields(data, selectSet) {
+    const result = {};
+    for (const key of selectSet) {
+        // Defense-in-depth: only copy OWN properties, blocking
+        // prototype chain access (__proto__, constructor, etc.)
+        if (Object.hasOwn(data, key)) {
+            result[key] = data[key];
+        }
+    }
+    return result;
+}
+/**
+ * Apply `_select` filtering to validated data.
+ *
+ * Handles both single objects and arrays. When `isArray` is true,
+ * each item in the array is filtered independently.
+ *
+ * @param data - Validated data (single object or array)
+ * @param selectFields - Array of top-level keys to keep
+ * @param isArray - Whether `data` is an array
+ * @returns The filtered data (same shape as input, fewer fields)
+ */
+export function applySelectFilter(data, selectFields, isArray) {
+    const selectSet = new Set(selectFields);
+    if (isArray) {
+        return data.map(item => pickFields(item, selectSet));
+    }
+    return pickFields(data, selectSet);
+}
+//# sourceMappingURL=SelectUtils.js.map

package/dist/presenter/SelectUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SelectUtils.js","sourceRoot":"","sources":["../../src/presenter/SelectUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAgB,MAAM,KAAK,CAAC;AAEnC,4DAA4D;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,cAAc,CAAC,MAAe;IAC1C,IAAI,OAAO,GAAY,MAAM,CAAC;IAE9B,4DAA4D;IAC5D,iDAAiD;IACjD,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC;QACtC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAEvD,MAAM,GAAG,GAAI,OAA8C,CAAC,IAAI,CAAC;QACjE,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,CAAC;QAEpB,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAuB,CAAC;QAEvD,QAAQ,QAAQ,EAAE,CAAC;YACf,iDAAiD;YACjD,KAAK,aAAa,CAAC;YACnB,KAAK,aAAa,CAAC;YACnB,KAAK,YAAY,CAAC;YAClB,KAAK,aAAa,CAAC;YACnB,KAAK,YAAY,CAAC;YAClB,KAAK,UAAU,CAAC;YAChB,KAAK,SAAS;gBACV,OAAO,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC;gBAC3B,SAAS;YAEb,iDAAiD;YACjD,KAAK,YAAY;gBACb,OAAO,GAAI,GAA+B,CAAC,QAAQ,CAAC,CAAC;gBACrD,SAAS;YAEb,iDAAiD;YACjD,KAAK,UAAU;gBACX,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;gBACtB,SAAS;YAEb,iDAAiD;YACjD,KAAK,aAAa;gBACd,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;gBACrB,SAAS;YAEb,iDAAiD;YACjD,KAAK,WAAW,CAAC,CAAC,CAAC;gBACf,MAAM,KAAK,GAAI,OAA+C,CAAC,KAAK,CAAC;gBACrE,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3C,CAAC;YAED,iDAAiD;YACjD;gBACI,OAAO,EAAE,CAAC;QAClB,CAAC;IACL,CAAC;IAED,OAAO,EAAE,CAAC;AACd,CAAC;AAED,4DAA4D;AAE5D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CACtB,IAA6B,EAC7B,SAAsB;IAEtB,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC1B,uDAAuD;QACvD,wDAAwD;QACxD,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC7B,IAAa,EACb,YAAsB,EACtB,OAAgB;IAEhB,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;IAExC,IAAI,OAAO,EAAE,CAAC;QACV,OAAQ,IAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAC5B,UAAU,CAAC,IAA+B,EAAE,SAAS,CAAM,CAC9D,CAAC;IACN,CAAC;IAED,OAAO,UAAU,CAAC,IAA+B,EAAE,SAAS,CAAM,CAAC;AACvE,CAAC"}

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"}