@vurb/core 3.2.0

package/dist/core/response.js

@@ -0,0 +1,286 @@
+/**
+ * Response Helpers
+ *
+ * Universal MCP response builders. No API coupling.
+ * These produce the standard MCP ToolResponse format.
+ *
+ * @example
+ * ```typescript
+ * import { success, error, toonSuccess } from 'vurb';
+ *
+ * // String response
+ * return success('Project created');
+ *
+ * // Object response (auto JSON.stringify)
+ * return success({ id: '123', name: 'My Project' });
+ *
+ * // Error response
+ * return error('Project not found');
+ *
+ * // TOON-encoded response (~40% fewer tokens)
+ * return toonSuccess(users);
+ * ```
+ *
+ * @see {@link ToolResponse} for the response shape
+ * @see {@link toonSuccess} for token-optimized responses
+ *
+ * @module
+ */
+import { encode } from '@toon-format/toon';
+import {} from './serialization/JsonSerializer.js';
+/**
+ * Non-enumerable brand symbol stamped on all helper-created ToolResponse objects.
+ * Used by FluentToolBuilder to reliably distinguish framework responses from
+ * domain data that coincidentally matches the ToolResponse shape (Bug #127).
+ *
+ * @internal
+ */
+export const TOOL_RESPONSE_BRAND = Symbol.for('vurb.ToolResponse');
+// ============================================================================
+// XML Safety
+// ============================================================================
+/**
+ * Escape XML structural characters for element content.
+ *
+ * Only `&` and `<` are mandatory escapes in XML element content.
+ * `>` is preserved for LLM readability (e.g. `>= 1`, `Must be > 0`).
+ * Single and double quotes are also preserved since they have no
+ * special meaning outside attribute values.
+ *
+ * @internal
+ */
+export function escapeXml(str) {
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;');
+}
+/**
+ * Escape XML special characters for use inside attribute values.
+ *
+ * Attribute values are delimited by `"` or `'` and must also
+ * escape `<`, `>`, and `&`. All 5 XML special characters are handled.
+ *
+ * @internal
+ */
+export function escapeXmlAttr(str) {
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+// ============================================================================
+// Response Builders
+// ============================================================================
+/**
+ * Create a success response from text or a JSON-serializable object.
+ *
+ * - Strings are returned verbatim (empty strings become `"OK"`)
+ * - Objects are serialized with `JSON.stringify(data, null, 2)`
+ *
+ * @param data - A string message or any JSON-serializable object
+ * @returns A {@link ToolResponse} with `isError` unset
+ *
+ * @example
+ * ```typescript
+ * // String response
+ * return success('Task completed');
+ *
+ * // Object response (pretty-printed JSON)
+ * const project = await db.projects.create({ name: 'Acme' });
+ * return success(project);
+ *
+ * // Array response
+ * const users = await db.users.findMany();
+ * return success(users);
+ * ```
+ *
+ * @see {@link error} for error responses
+ * @see {@link toonSuccess} for token-optimized array responses
+ */
+export function success(data, compiledStringify) {
+    const text = typeof data === 'string'
+        ? (data || 'OK')
+        : (compiledStringify ? compiledStringify(data) : JSON.stringify(data, null, 2));
+    const resp = { content: [{ type: "text", text }] };
+    Object.defineProperty(resp, TOOL_RESPONSE_BRAND, { value: true });
+    return resp;
+}
+/**
+ * Create an error response.
+ *
+ * Sets `isError: true` so the MCP client and LLM recognize the failure.
+ * The LLM will typically retry or ask the user for clarification.
+ *
+ * @param message - Human-readable error description
+ * @returns A {@link ToolResponse} with `isError: true`
+ *
+ * @example
+ * ```typescript
+ * // Simple error
+ * return error('Project not found');
+ *
+ * // Contextual error
+ * return error(`User "${userId}" does not have access to workspace "${wsId}"`);
+ *
+ * // In a handler with early return
+ * handler: async (ctx, args) => {
+ *     const project = await ctx.db.projects.findUnique(args.id);
+ *     if (!project) return error(`Project "${args.id}" not found`);
+ *     return success(project);
+ * }
+ * ```
+ *
+ * @see {@link required} for missing field errors
+ * @see {@link success} for success responses
+ */
+export function error(message, code) {
+    const codeAttr = code !== undefined ? ` code="${escapeXmlAttr(code)}"` : '';
+    const resp = {
+        content: [{ type: "text", text: `<tool_error${codeAttr}>\n<message>${escapeXml(message)}</message>\n</tool_error>` }],
+        isError: true,
+    };
+    Object.defineProperty(resp, TOOL_RESPONSE_BRAND, { value: true });
+    return resp;
+}
+/**
+ * Create a validation error for a missing required field.
+ *
+ * Convenience shortcut for `error(\`Error: ${field} required\`)`.
+ * Typically used in handlers that accept dynamic or optional schemas.
+ *
+ * @param field - Name of the missing required field
+ * @returns A {@link ToolResponse} with `isError: true`
+ *
+ * @example
+ * ```typescript
+ * handler: async (ctx, args) => {
+ *     if (!args.workspace_id) return required('workspace_id');
+ *     // ...
+ * }
+ * ```
+ *
+ * @see {@link error} for general error responses
+ */
+export function required(field) {
+    const f = escapeXml(field);
+    const resp = {
+        content: [{
+                type: "text",
+                text: `<tool_error code="MISSING_REQUIRED_FIELD">\n<message>Required field "${f}" is missing.</message>\n<recovery>Provide the "${f}" parameter and retry.</recovery>\n</tool_error>`,
+            }],
+        isError: true,
+    };
+    Object.defineProperty(resp, TOOL_RESPONSE_BRAND, { value: true });
+    return resp;
+}
+/**
+ * Create a success response with TOON-encoded payload.
+ *
+ * Encodes structured data using TOON (Token-Oriented Object Notation)
+ * for ~40-50% token reduction compared to `JSON.stringify()`.
+ * Ideal for list/tabular responses (arrays of uniform objects).
+ *
+ * @param data - Any JSON-serializable value (objects, arrays, primitives)
+ * @param options - Optional TOON encode options (default: pipe delimiter)
+ * @returns A {@link ToolResponse} with TOON-encoded text
+ *
+ * @example
+ * ```typescript
+ * // Array response — saves ~40% tokens vs JSON
+ * const users = await db.users.findMany();
+ * return toonSuccess(users);
+ * // Output: "id|name|email\n1|Alice|alice@co.io\n2|Bob|bob@co.io"
+ *
+ * // With custom delimiter
+ * return toonSuccess(data, { delimiter: ',' });
+ *
+ * // Single object (still valid, but savings are smaller)
+ * return toonSuccess({ id: 1, name: 'Alice' });
+ * ```
+ *
+ * @see {@link success} for standard JSON responses
+ */
+export function toonSuccess(data, options) {
+    const defaults = { delimiter: '|' };
+    const text = encode(data, { ...defaults, ...options });
+    const resp = { content: [{ type: "text", text }] };
+    Object.defineProperty(resp, TOOL_RESPONSE_BRAND, { value: true });
+    return resp;
+}
+/**
+ * Create a self-healing error response with recovery instructions.
+ *
+ * Unlike {@link error}, this provides structured guidance so the LLM
+ * agent can self-correct instead of hallucinating or giving up.
+ * The response includes an error code, message, suggestion, and
+ * available actions — all formatted for optimal LLM comprehension.
+ *
+ * @param code - Short error code (e.g. `'ProjectNotFound'`, `'Unauthorized'`)
+ * @param options - Error details and recovery instructions
+ * @returns A {@link ToolResponse} with `isError: true` and recovery guidance
+ *
+ * @example
+ * ```typescript
+ * handler: async (ctx, args) => {
+ *     const project = await ctx.db.get(args.project_id);
+ *
+ *     if (!project) {
+ *         return toolError('ProjectNotFound', {
+ *             message: `Project '${args.project_id}' does not exist.`,
+ *             suggestion: 'Call projects.list first to get valid IDs, then retry.',
+ *             availableActions: ['projects.list'],
+ *         });
+ *     }
+ *
+ *     return success(project);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Minimal usage (no suggestion)
+ * return toolError('RateLimited', {
+ *     message: 'Too many requests. Wait 30 seconds.',
+ * });
+ * ```
+ *
+ * @see {@link error} for simple error responses
+ * @see {@link required} for missing field errors
+ */
+export function toolError(code, options) {
+    const severity = options.severity ?? 'error';
+    const parts = [
+        `<tool_error code="${escapeXmlAttr(code)}" severity="${escapeXmlAttr(severity)}">`,
+        `<message>${escapeXml(options.message)}</message>`,
+    ];
+    if (options.suggestion) {
+        parts.push(`<recovery>${escapeXml(options.suggestion)}</recovery>`);
+    }
+    if ((options.availableActions?.length ?? 0) > 0) {
+        parts.push('<available_actions>');
+        for (const action of options.availableActions) {
+            parts.push(`  <action>${escapeXml(action)}</action>`);
+        }
+        parts.push('</available_actions>');
+    }
+    if (options.details != null && Object.keys(options.details).length > 0) {
+        parts.push('<details>');
+        for (const [key, value] of Object.entries(options.details)) {
+            parts.push(`  <detail key="${escapeXmlAttr(key)}">${escapeXml(value)}</detail>`);
+        }
+        parts.push('</details>');
+    }
+    if (options.retryAfter !== undefined && Number.isFinite(options.retryAfter) && options.retryAfter > 0) {
+        parts.push(`<retry_after>${options.retryAfter} seconds</retry_after>`);
+    }
+    parts.push('</tool_error>');
+    // Warnings are non-fatal — do not set isError so the response
+    // flows through the success path while still carrying guidance.
+    const isError = severity !== 'warning';
+    const resp = { content: [{ type: "text", text: parts.join('\n') }], isError };
+    Object.defineProperty(resp, TOOL_RESPONSE_BRAND, { value: true });
+    return resp;
+}
+//# sourceMappingURL=response.js.map

package/dist/core/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/core/response.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,MAAM,EAAsB,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAoB,MAAM,mCAAmC,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAkB,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;AAElF,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACjC,OAAO,GAAG;SACL,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACrC,OAAO,GAAG;SACL,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AACjC,CAAC;AA6BD,+EAA+E;AAC/E,oBAAoB;AACpB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,OAAO,CAAC,IAAqB,EAAE,iBAA+B;IAC1E,MAAM,IAAI,GAAG,OAAO,IAAI,KAAK,QAAQ;QACjC,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC;QAChB,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACpF,MAAM,IAAI,GAAiB,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACjE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,mBAAmB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,KAAK,CAAC,OAAe,EAAE,IAAgB;IACnD,MAAM,QAAQ,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5E,MAAM,IAAI,GAAiB;QACvB,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,QAAQ,eAAe,SAAS,CAAC,OAAO,CAAC,2BAA2B,EAAE,CAAC;QACrH,OAAO,EAAE,IAAI;KAChB,CAAC;IACF,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,mBAAmB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAa;IAClC,MAAM,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAC3B,MAAM,IAAI,GAAiB;QACvB,OAAO,EAAE,CAAC;gBACN,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,wEAAwE,CAAC,mDAAmD,CAAC,kDAAkD;aACxL,CAAC;QACF,OAAO,EAAE,IAAI;KAChB,CAAC;IACF,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,mBAAmB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,WAAW,CAAC,IAAa,EAAE,OAAuB;IAC9D,MAAM,QAAQ,GAAkB,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC;IACnD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACvD,MAAM,IAAI,GAAiB,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACjE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,mBAAmB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,OAAO,IAAI,CAAC;AAChB,CAAC;AAoFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,UAAU,SAAS,CAAC,IAAe,EAAE,OAAyB;IAChE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC;IAC7C,MAAM,KAAK,GAAa;QACpB,qBAAqB,aAAa,CAAC,IAAI,CAAC,eAAe,aAAa,CAAC,QAAQ,CAAC,IAAI;QAClF,YAAY,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY;KACrD,CAAC;IAEF,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,aAAa,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACxE,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9C,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QAClC,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,gBAAiB,EAAE,CAAC;YAC7C,KAAK,CAAC,IAAI,CAAC,aAAa,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC1D,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,OAAO,CAAC,OAAO,IAAI,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACxB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACzD,KAAK,CAAC,IAAI,CAAC,kBAAkB,aAAa,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QACrF,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC7B,CAAC;IAED,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;QACpG,KAAK,CAAC,IAAI,CAAC,gBAAgB,OAAO,CAAC,UAAU,wBAAwB,CAAC,CAAC;IAC3E,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAE5B,8DAA8D;IAC9D,gEAAgE;IAChE,MAAM,OAAO,GAAG,QAAQ,KAAK,SAAS,CAAC;IACvC,MAAM,IAAI,GAAiB,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC;IAC5F,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,mBAAmB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,OAAO,IAAI,CAAC;AAChB,CAAC"}

package/dist/core/result.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Result\<T\> — Railway-Oriented Programming for Vurb
+ *
+ * A lightweight, zero-overhead discriminated union for expressing
+ * success/failure pipelines without exception throwing.
+ *
+ * Follows the "Result Monad" pattern used in Rust, Haskell, and F#.
+ * Each step in a pipeline returns `Result<T>`: either `Success<T>` or `Failure`.
+ *
+ * @example
+ * ```typescript
+ * import { succeed, fail, error, type Result } from 'vurb';
+ *
+ * function parseId(input: string): Result<number> {
+ *     const id = parseInt(input, 10);
+ *     return isNaN(id) ? fail(error('Invalid ID')) : succeed(id);
+ * }
+ *
+ * // Usage in a pipeline:
+ * const result = parseId(args.id);
+ * if (!result.ok) return result.response;  // Early return on failure
+ * const userId = result.value;             // Narrowed to number
+ * ```
+ *
+ * @see {@link succeed} for creating successful results
+ * @see {@link fail} for creating failure results
+ *
+ * @module
+ */
+import { type ToolResponse } from './response.js';
+/**
+ * Successful result containing a typed value.
+ *
+ * @typeParam T - The success value type
+ */
+export interface Success<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+/**
+ * Failed result containing an error response.
+ *
+ * The `response` field is a standard {@link ToolResponse} that can
+ * be returned directly from a handler.
+ */
+export interface Failure {
+    readonly ok: false;
+    readonly response: ToolResponse;
+}
+/**
+ * Discriminated union: either `Success<T>` or `Failure`.
+ *
+ * Check `result.ok` to narrow the type:
+ *
+ * @example
+ * ```typescript
+ * const result: Result<User> = findUser(id);
+ * if (!result.ok) return result.response;  // Failure path
+ * const user = result.value;               // Success path — typed as User
+ * ```
+ */
+export type Result<T> = Success<T> | Failure;
+/**
+ * Create a successful result.
+ *
+ * @typeParam T - The value type
+ * @param value - The success value
+ * @returns A `Success<T>` with `ok: true`
+ *
+ * @example
+ * ```typescript
+ * return succeed(42);
+ * return succeed({ id: 'user_1', name: 'Alice' });
+ * ```
+ */
+export declare function succeed<T>(value: T): Success<T>;
+/**
+ * Create a failed result from a ToolResponse.
+ *
+ * @param response - An error {@link ToolResponse} (typically from `error()`)
+ * @returns A `Failure` with `ok: false`
+ *
+ * @example
+ * ```typescript
+ * return fail(error('User not found'));
+ * return fail(required('email'));
+ * ```
+ *
+ * @see {@link error} for creating error responses
+ * @see {@link required} for missing field errors
+ */
+export declare function fail(response: ToolResponse): Failure;
+//# sourceMappingURL=result.d.ts.map

package/dist/core/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/core/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAIlD;;;;GAIG;AACH,MAAM,WAAW,OAAO,CAAC,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACpB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;AAI7C;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE/C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAEpD"}

package/dist/core/result.js

@@ -0,0 +1,66 @@
+/**
+ * Result\<T\> — Railway-Oriented Programming for Vurb
+ *
+ * A lightweight, zero-overhead discriminated union for expressing
+ * success/failure pipelines without exception throwing.
+ *
+ * Follows the "Result Monad" pattern used in Rust, Haskell, and F#.
+ * Each step in a pipeline returns `Result<T>`: either `Success<T>` or `Failure`.
+ *
+ * @example
+ * ```typescript
+ * import { succeed, fail, error, type Result } from 'vurb';
+ *
+ * function parseId(input: string): Result<number> {
+ *     const id = parseInt(input, 10);
+ *     return isNaN(id) ? fail(error('Invalid ID')) : succeed(id);
+ * }
+ *
+ * // Usage in a pipeline:
+ * const result = parseId(args.id);
+ * if (!result.ok) return result.response;  // Early return on failure
+ * const userId = result.value;             // Narrowed to number
+ * ```
+ *
+ * @see {@link succeed} for creating successful results
+ * @see {@link fail} for creating failure results
+ *
+ * @module
+ */
+import {} from './response.js';
+// ── Constructors ─────────────────────────────────────────
+/**
+ * Create a successful result.
+ *
+ * @typeParam T - The value type
+ * @param value - The success value
+ * @returns A `Success<T>` with `ok: true`
+ *
+ * @example
+ * ```typescript
+ * return succeed(42);
+ * return succeed({ id: 'user_1', name: 'Alice' });
+ * ```
+ */
+export function succeed(value) {
+    return { ok: true, value };
+}
+/**
+ * Create a failed result from a ToolResponse.
+ *
+ * @param response - An error {@link ToolResponse} (typically from `error()`)
+ * @returns A `Failure` with `ok: false`
+ *
+ * @example
+ * ```typescript
+ * return fail(error('User not found'));
+ * return fail(required('email'));
+ * ```
+ *
+ * @see {@link error} for creating error responses
+ * @see {@link required} for missing field errors
+ */
+export function fail(response) {
+    return { ok: false, response };
+}
+//# sourceMappingURL=result.js.map

package/dist/core/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/core/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAqB,MAAM,eAAe,CAAC;AAuClD,4DAA4D;AAE5D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,OAAO,CAAI,KAAQ;IAC/B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,IAAI,CAAC,QAAsB;IACvC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AACnC,CAAC"}

package/dist/core/schema/AnnotationAggregator.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AnnotationAggregator — Tool Annotation Aggregation Strategy
+ *
+ * Aggregates per-action hints (readOnly, destructive, idempotent)
+ * into a single annotation record, with explicit overrides.
+ *
+ * Pure-function module: no state, no side effects.
+ */
+import { type InternalAction } from '../types.js';
+export declare function aggregateAnnotations<TContext>(actions: readonly InternalAction<TContext>[], explicitAnnotations: Record<string, unknown> | undefined): Record<string, unknown>;
+//# sourceMappingURL=AnnotationAggregator.d.ts.map

package/dist/core/schema/AnnotationAggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnnotationAggregator.d.ts","sourceRoot":"","sources":["../../../src/core/schema/AnnotationAggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAYlD,wBAAgB,oBAAoB,CAAC,QAAQ,EACzC,OAAO,EAAE,SAAS,cAAc,CAAC,QAAQ,CAAC,EAAE,EAC5C,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACzD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgCzB"}

package/dist/core/schema/AnnotationAggregator.js

@@ -0,0 +1,40 @@
+/**
+ * AnnotationAggregator — Tool Annotation Aggregation Strategy
+ *
+ * Aggregates per-action hints (readOnly, destructive, idempotent)
+ * into a single annotation record, with explicit overrides.
+ *
+ * Pure-function module: no state, no side effects.
+ */
+import {} from '../types.js';
+// ── Public API ───────────────────────────────────────────
+export function aggregateAnnotations(actions, explicitAnnotations) {
+    const result = {};
+    // Copy explicit annotations using explicit loop to guard against
+    // __proto__/constructor/prototype keys (prototype pollution defense).
+    // Matches the pattern in ContextDerivation, FluentToolBuilder, and ExecutionPipeline.
+    if (explicitAnnotations) {
+        for (const [key, value] of Object.entries(explicitAnnotations)) {
+            if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+                continue;
+            result[key] = value;
+        }
+    }
+    // Per-action aggregation (only override if not explicitly set)
+    if (result.readOnlyHint === undefined) {
+        const allReadOnly = actions.length > 0 &&
+            actions.every(a => a.readOnly === true);
+        result.readOnlyHint = allReadOnly;
+    }
+    if (result.destructiveHint === undefined) {
+        const anyDestructive = actions.some(a => a.destructive === true);
+        result.destructiveHint = anyDestructive;
+    }
+    if (result.idempotentHint === undefined) {
+        const allIdempotent = actions.length > 0 &&
+            actions.every(a => a.idempotent === true);
+        result.idempotentHint = allIdempotent;
+    }
+    return result;
+}
+//# sourceMappingURL=AnnotationAggregator.js.map

package/dist/core/schema/AnnotationAggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnnotationAggregator.js","sourceRoot":"","sources":["../../../src/core/schema/AnnotationAggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAuB,MAAM,aAAa,CAAC;AAUlD,4DAA4D;AAE5D,MAAM,UAAU,oBAAoB,CAChC,OAA4C,EAC5C,mBAAwD;IAExD,MAAM,MAAM,GAA0B,EAAE,CAAC;IAEzC,iEAAiE;IACjE,sEAAsE;IACtE,sFAAsF;IACtF,IAAI,mBAAmB,EAAE,CAAC;QACtB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,CAAC;YAC7D,IAAI,GAAG,KAAK,WAAW,IAAI,GAAG,KAAK,aAAa,IAAI,GAAG,KAAK,WAAW;gBAAE,SAAS;YACjF,MAAkC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACrD,CAAC;IACL,CAAC;IAED,+DAA+D;IAC/D,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC;YAClC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;QAC5C,MAAM,CAAC,YAAY,GAAG,WAAW,CAAC;IACtC,CAAC;IAED,IAAI,MAAM,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QACvC,MAAM,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,IAAI,CAAC,CAAC;QACjE,MAAM,CAAC,eAAe,GAAG,cAAc,CAAC;IAC5C,CAAC;IAED,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACtC,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC;YACpC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC;QAC9C,MAAM,CAAC,cAAc,GAAG,aAAa,CAAC;IAC1C,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC"}

package/dist/core/schema/DescriptionGenerator.d.ts

@@ -0,0 +1,12 @@
+/**
+ * DescriptionGenerator — LLM-friendly Tool Description Strategy
+ *
+ * Generates 3-layer descriptions from action metadata:
+ * - Layer 1: Tool summary + module/action listing
+ * - Layer 2: Workflow section with required params and destructive warnings
+ *
+ * Pure-function module: no state, no side effects.
+ */
+import { type InternalAction } from '../types.js';
+export declare function generateDescription<TContext>(actions: readonly InternalAction<TContext>[], name: string, description: string | undefined, hasGroup: boolean, discriminator?: string): string;
+//# sourceMappingURL=DescriptionGenerator.d.ts.map

package/dist/core/schema/DescriptionGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DescriptionGenerator.d.ts","sourceRoot":"","sources":["../../../src/core/schema/DescriptionGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAKlD,wBAAgB,mBAAmB,CAAC,QAAQ,EACxC,OAAO,EAAE,SAAS,cAAc,CAAC,QAAQ,CAAC,EAAE,EAC5C,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,QAAQ,EAAE,OAAO,EACjB,aAAa,SAAW,GACzB,MAAM,CAgCR"}

package/dist/core/schema/DescriptionGenerator.js

@@ -0,0 +1,81 @@
+/**
+ * DescriptionGenerator — LLM-friendly Tool Description Strategy
+ *
+ * Generates 3-layer descriptions from action metadata:
+ * - Layer 1: Tool summary + module/action listing
+ * - Layer 2: Workflow section with required params and destructive warnings
+ *
+ * Pure-function module: no state, no side effects.
+ */
+import {} from '../types.js';
+import { getActionRequiredFields } from './SchemaUtils.js';
+// ── Public API ───────────────────────────────────────────
+export function generateDescription(actions, name, description, hasGroup, discriminator = 'action') {
+    const lines = [];
+    // Layer 1: Tool description + action/module summary + dispatch instruction
+    if (hasGroup) {
+        const groups = getGroupSummaries(actions);
+        const moduleList = groups
+            .map(g => `${g.name} (${g.actions.join(',')})`)
+            .join(' | ');
+        lines.push(`${description || name}. ` +
+            `Select operation via the \`${discriminator}\` parameter. ` +
+            `Modules: ${moduleList}`);
+    }
+    else {
+        const actionNames = actions.map(a => a.key);
+        lines.push(`${description || name}. ` +
+            `Select operation via the \`${discriminator}\` parameter. ` +
+            `Actions: ${actionNames.join(', ')}`);
+    }
+    // Layer 2: Workflow section
+    const workflowLines = generateWorkflowLines(actions);
+    if (workflowLines.length > 0) {
+        lines.push('');
+        lines.push('Workflow:');
+        lines.push(...workflowLines);
+    }
+    return lines.join('\n');
+}
+// ── Internal helpers ─────────────────────────────────────
+function generateWorkflowLines(actions) {
+    const lines = [];
+    for (const action of actions) {
+        const requiredFields = getActionRequiredFields(action);
+        const isDestructive = action.destructive === true;
+        if (!action.description && requiredFields.length === 0 && !isDestructive) {
+            continue;
+        }
+        let line = `- '${action.key}': `;
+        if (action.description) {
+            line += action.description;
+        }
+        if (requiredFields.length > 0) {
+            line += action.description ? '. Requires: ' : 'Requires: ';
+            line += requiredFields.join(', ');
+        }
+        if (isDestructive) {
+            line += ' [DESTRUCTIVE]';
+        }
+        lines.push(line);
+    }
+    return lines;
+}
+function getGroupSummaries(actions) {
+    const groups = new Map();
+    for (const action of actions) {
+        if (!action.groupName)
+            continue;
+        let group = groups.get(action.groupName);
+        if (!group) {
+            group = [];
+            groups.set(action.groupName, group);
+        }
+        group.push(action.actionName);
+    }
+    return Array.from(groups.entries()).map(([name, groupActions]) => ({
+        name,
+        actions: groupActions,
+    }));
+}
+//# sourceMappingURL=DescriptionGenerator.js.map

package/dist/core/schema/DescriptionGenerator.js.map

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

package/dist/core/schema/SchemaGenerator.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SchemaGenerator — JSON Schema Input Schema Strategy
+ *
+ * Generates MCP-compatible inputSchema from Zod definitions:
+ * - Discriminator enum from action keys
+ * - Common + per-action schema merging (with omitCommon support)
+ * - Per-field annotations (required-for / optional-for)
+ *
+ * Pure-function module: no state, no side effects.
+ */
+import { type ZodObject, type ZodRawShape } from 'zod';
+import { type Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
+import { type InternalAction } from '../types.js';
+export declare function generateInputSchema<TContext>(actions: readonly InternalAction<TContext>[], discriminator: string, hasGroup: boolean, commonSchema: ZodObject<ZodRawShape> | undefined, selectEnabled?: boolean): McpTool['inputSchema'];
+//# sourceMappingURL=SchemaGenerator.d.ts.map

package/dist/core/schema/SchemaGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaGenerator.d.ts","sourceRoot":"","sources":["../../../src/core/schema/SchemaGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAEvD,OAAO,EAAE,KAAK,IAAI,IAAI,OAAO,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAkBlD,wBAAgB,mBAAmB,CAAC,QAAQ,EACxC,OAAO,EAAE,SAAS,cAAc,CAAC,QAAQ,CAAC,EAAE,EAC5C,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,OAAO,EACjB,YAAY,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,EAChD,aAAa,UAAQ,GACtB,OAAO,CAAC,aAAa,CAAC,CAyBxB"}