promptspeak-mcp-server 0.1.0

package/dist/core/result/mcp-adapter.d.ts

@@ -0,0 +1,192 @@
+/**
+ * ===============================================================================
+ * MCP RESPONSE ADAPTER
+ * ===============================================================================
+ *
+ * Bridges the unified Result<T> pattern to MCP's CallToolResult format.
+ * Provides consistent response formatting for all MCP tool handlers.
+ *
+ * Usage:
+ *   import { toMcpResult, mcpSuccess, mcpFailure } from '../core/result/mcp-adapter.js';
+ *
+ *   // From a Result<T>
+ *   const result = await someOperation();
+ *   return toMcpResult(result);
+ *
+ *   // Direct creation
+ *   return mcpSuccess({ id: 1, name: 'test' });
+ *   return mcpFailure('NOT_FOUND', 'Item not found');
+ *
+ * ===============================================================================
+ */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { Result } from './types.js';
+/**
+ * Options for MCP response formatting.
+ */
+export interface McpResponseOptions {
+    /** Pretty print JSON output (default: true) */
+    prettyPrint?: boolean;
+    /** Include metadata in response (default: false for cleaner output) */
+    includeMetadata?: boolean;
+    /** Include timestamp in response (default: true) */
+    includeTimestamp?: boolean;
+}
+/**
+ * Standard success response structure for MCP tools.
+ */
+export interface McpSuccessPayload<T = unknown> {
+    success: true;
+    data: T;
+    timestamp?: string;
+}
+/**
+ * Standard error response structure for MCP tools.
+ */
+export interface McpErrorPayload {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+        retryable?: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Converts a Result<T> to MCP's CallToolResult format.
+ *
+ * @param result - The Result to convert
+ * @param options - Formatting options
+ * @returns CallToolResult for MCP response
+ *
+ * @example
+ * ```typescript
+ * const result = await validateSymbol(input);
+ * return toMcpResult(result);
+ * ```
+ */
+export declare function toMcpResult<T>(result: Result<T>, options?: McpResponseOptions): CallToolResult;
+/**
+ * Creates an MCP success response directly from data.
+ *
+ * @param data - The success data
+ * @param options - Formatting options
+ * @returns CallToolResult for MCP response
+ *
+ * @example
+ * ```typescript
+ * return mcpSuccess({ validated: true, symbolId: 'Ξ.COMPANY.NVDA' });
+ * ```
+ */
+export declare function mcpSuccess<T>(data: T, options?: McpResponseOptions): CallToolResult;
+/**
+ * Creates an MCP failure response directly.
+ *
+ * @param code - Machine-readable error code
+ * @param message - Human-readable error message
+ * @param details - Optional additional details
+ * @param options - Formatting options
+ * @returns CallToolResult with isError: true
+ *
+ * @example
+ * ```typescript
+ * return mcpFailure('VALIDATION_FAILED', 'Invalid symbol format', { input });
+ * ```
+ */
+export declare function mcpFailure(code: string, message: string, details?: Record<string, unknown>, options?: McpResponseOptions): CallToolResult;
+/**
+ * Creates an MCP failure response in legacy format for backwards compatibility.
+ * Uses simple { error: "message" } format instead of structured error.
+ *
+ * @param message - Error message
+ * @param options - Formatting options
+ * @returns CallToolResult with isError: true
+ *
+ * @deprecated Use mcpFailure for new code
+ */
+export declare function mcpLegacyFailure(message: string, options?: McpResponseOptions): CallToolResult;
+/**
+ * Creates an MCP failure response from an Error object.
+ *
+ * @param error - The error to convert
+ * @param defaultCode - Default error code if not present on error
+ * @param options - Formatting options
+ * @returns CallToolResult with isError: true
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation();
+ * } catch (err) {
+ *   return mcpFromError(err, 'OPERATION_FAILED');
+ * }
+ * ```
+ */
+export declare function mcpFromError(error: Error | unknown, defaultCode?: string, options?: McpResponseOptions): CallToolResult;
+/**
+ * Legacy response format used by existing tool handlers.
+ * For migration purposes only.
+ */
+export interface LegacyToolResponse {
+    success?: boolean;
+    error?: string;
+    message?: string;
+    [key: string]: unknown;
+}
+/**
+ * Converts a legacy tool response to MCP format.
+ * Use this to wrap existing tool handlers during migration.
+ *
+ * @param response - Legacy response object
+ * @param options - Formatting options
+ * @returns CallToolResult for MCP response
+ *
+ * @example
+ * ```typescript
+ * const legacyResult = await oldToolHandler(args);
+ * return fromLegacyResponse(legacyResult);
+ * ```
+ */
+export declare function fromLegacyResponse(response: LegacyToolResponse, options?: McpResponseOptions): CallToolResult;
+/**
+ * Creates an MCP response for batch operations with summary.
+ *
+ * @param results - Array of individual results
+ * @param summary - Batch operation summary
+ * @param options - Formatting options
+ * @returns CallToolResult for MCP response
+ */
+export declare function mcpBatchResult<T>(results: Array<{
+    key: string;
+    result: Result<T>;
+}>, summary: {
+    total: number;
+    succeeded: number;
+    failed: number;
+}, options?: McpResponseOptions): CallToolResult;
+/**
+ * Wraps an async tool handler to automatically convert Results to MCP format.
+ *
+ * @param handler - Async function returning Result<T>
+ * @param errorCode - Default error code for unexpected errors
+ * @returns Wrapped handler returning CallToolResult
+ *
+ * @example
+ * ```typescript
+ * const handler = wrapToolHandler(
+ *   async (args) => validateSymbol(args.symbol),
+ *   'VALIDATION_FAILED'
+ * );
+ * ```
+ */
+export declare function wrapToolHandler<TArgs, TResult>(handler: (args: TArgs) => Promise<Result<TResult>>, errorCode?: string): (args: TArgs) => Promise<CallToolResult>;
+/**
+ * Wraps a sync tool handler to automatically convert Results to MCP format.
+ *
+ * @param handler - Sync function returning Result<T>
+ * @param errorCode - Default error code for unexpected errors
+ * @returns Wrapped handler returning CallToolResult
+ */
+export declare function wrapToolHandlerSync<TArgs, TResult>(handler: (args: TArgs) => Result<TResult>, errorCode?: string): (args: TArgs) => CallToolResult;
+//# sourceMappingURL=mcp-adapter.d.ts.map

package/dist/core/result/mcp-adapter.d.ts.map

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

package/dist/core/result/mcp-adapter.js

@@ -0,0 +1,255 @@
+/**
+ * ===============================================================================
+ * MCP RESPONSE ADAPTER
+ * ===============================================================================
+ *
+ * Bridges the unified Result<T> pattern to MCP's CallToolResult format.
+ * Provides consistent response formatting for all MCP tool handlers.
+ *
+ * Usage:
+ *   import { toMcpResult, mcpSuccess, mcpFailure } from '../core/result/mcp-adapter.js';
+ *
+ *   // From a Result<T>
+ *   const result = await someOperation();
+ *   return toMcpResult(result);
+ *
+ *   // Direct creation
+ *   return mcpSuccess({ id: 1, name: 'test' });
+ *   return mcpFailure('NOT_FOUND', 'Item not found');
+ *
+ * ===============================================================================
+ */
+import { isSuccess, success, failure as createFailure, fromError } from './builders.js';
+// -----------------------------------------------------------------------------
+// MCP RESULT CONVERTERS
+// -----------------------------------------------------------------------------
+/**
+ * Converts a Result<T> to MCP's CallToolResult format.
+ *
+ * @param result - The Result to convert
+ * @param options - Formatting options
+ * @returns CallToolResult for MCP response
+ *
+ * @example
+ * ```typescript
+ * const result = await validateSymbol(input);
+ * return toMcpResult(result);
+ * ```
+ */
+export function toMcpResult(result, options = {}) {
+    const { prettyPrint = true, includeTimestamp = true } = options;
+    if (isSuccess(result)) {
+        const payload = {
+            success: true,
+            data: result.data,
+        };
+        if (includeTimestamp) {
+            payload.timestamp = new Date().toISOString();
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: prettyPrint ? JSON.stringify(payload, null, 2) : JSON.stringify(payload),
+                }],
+        };
+    }
+    // Failure case
+    const errorPayload = {
+        success: false,
+        error: {
+            code: result.error.code,
+            message: result.error.message,
+            details: result.error.details,
+            retryable: result.error.retryable,
+        },
+        timestamp: new Date().toISOString(),
+    };
+    return {
+        content: [{
+                type: 'text',
+                text: prettyPrint ? JSON.stringify(errorPayload, null, 2) : JSON.stringify(errorPayload),
+            }],
+        isError: true,
+    };
+}
+/**
+ * Creates an MCP success response directly from data.
+ *
+ * @param data - The success data
+ * @param options - Formatting options
+ * @returns CallToolResult for MCP response
+ *
+ * @example
+ * ```typescript
+ * return mcpSuccess({ validated: true, symbolId: 'Ξ.COMPANY.NVDA' });
+ * ```
+ */
+export function mcpSuccess(data, options = {}) {
+    return toMcpResult(success(data), options);
+}
+/**
+ * Creates an MCP failure response directly.
+ *
+ * @param code - Machine-readable error code
+ * @param message - Human-readable error message
+ * @param details - Optional additional details
+ * @param options - Formatting options
+ * @returns CallToolResult with isError: true
+ *
+ * @example
+ * ```typescript
+ * return mcpFailure('VALIDATION_FAILED', 'Invalid symbol format', { input });
+ * ```
+ */
+export function mcpFailure(code, message, details, options = {}) {
+    return toMcpResult(createFailure(code, message, { details }), options);
+}
+/**
+ * Creates an MCP failure response in legacy format for backwards compatibility.
+ * Uses simple { error: "message" } format instead of structured error.
+ *
+ * @param message - Error message
+ * @param options - Formatting options
+ * @returns CallToolResult with isError: true
+ *
+ * @deprecated Use mcpFailure for new code
+ */
+export function mcpLegacyFailure(message, options = {}) {
+    const { prettyPrint = true } = options;
+    const payload = { error: message };
+    return {
+        content: [{
+                type: 'text',
+                text: prettyPrint ? JSON.stringify(payload, null, 2) : JSON.stringify(payload),
+            }],
+        isError: true,
+    };
+}
+/**
+ * Creates an MCP failure response from an Error object.
+ *
+ * @param error - The error to convert
+ * @param defaultCode - Default error code if not present on error
+ * @param options - Formatting options
+ * @returns CallToolResult with isError: true
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation();
+ * } catch (err) {
+ *   return mcpFromError(err, 'OPERATION_FAILED');
+ * }
+ * ```
+ */
+export function mcpFromError(error, defaultCode = 'UNKNOWN_ERROR', options = {}) {
+    return toMcpResult(fromError(error, defaultCode), options);
+}
+/**
+ * Converts a legacy tool response to MCP format.
+ * Use this to wrap existing tool handlers during migration.
+ *
+ * @param response - Legacy response object
+ * @param options - Formatting options
+ * @returns CallToolResult for MCP response
+ *
+ * @example
+ * ```typescript
+ * const legacyResult = await oldToolHandler(args);
+ * return fromLegacyResponse(legacyResult);
+ * ```
+ */
+export function fromLegacyResponse(response, options = {}) {
+    const { prettyPrint = true } = options;
+    // Check if it's an error response
+    const isError = response.success === false || !!response.error;
+    return {
+        content: [{
+                type: 'text',
+                text: prettyPrint ? JSON.stringify(response, null, 2) : JSON.stringify(response),
+            }],
+        ...(isError && { isError: true }),
+    };
+}
+// -----------------------------------------------------------------------------
+// BATCH RESPONSE HELPERS
+// -----------------------------------------------------------------------------
+/**
+ * Creates an MCP response for batch operations with summary.
+ *
+ * @param results - Array of individual results
+ * @param summary - Batch operation summary
+ * @param options - Formatting options
+ * @returns CallToolResult for MCP response
+ */
+export function mcpBatchResult(results, summary, options = {}) {
+    const { prettyPrint = true } = options;
+    const formattedResults = results.map(({ key, result }) => ({
+        key,
+        success: isSuccess(result),
+        ...(isSuccess(result)
+            ? { data: result.data }
+            : { error: { code: result.error.code, message: result.error.message } }),
+    }));
+    const payload = {
+        success: summary.failed === 0,
+        summary,
+        results: formattedResults,
+        timestamp: new Date().toISOString(),
+    };
+    return {
+        content: [{
+                type: 'text',
+                text: prettyPrint ? JSON.stringify(payload, null, 2) : JSON.stringify(payload),
+            }],
+        ...(summary.failed > 0 && summary.succeeded === 0 && { isError: true }),
+    };
+}
+// -----------------------------------------------------------------------------
+// UTILITY FUNCTIONS
+// -----------------------------------------------------------------------------
+/**
+ * Wraps an async tool handler to automatically convert Results to MCP format.
+ *
+ * @param handler - Async function returning Result<T>
+ * @param errorCode - Default error code for unexpected errors
+ * @returns Wrapped handler returning CallToolResult
+ *
+ * @example
+ * ```typescript
+ * const handler = wrapToolHandler(
+ *   async (args) => validateSymbol(args.symbol),
+ *   'VALIDATION_FAILED'
+ * );
+ * ```
+ */
+export function wrapToolHandler(handler, errorCode = 'HANDLER_ERROR') {
+    return async (args) => {
+        try {
+            const result = await handler(args);
+            return toMcpResult(result);
+        }
+        catch (error) {
+            return mcpFromError(error, errorCode);
+        }
+    };
+}
+/**
+ * Wraps a sync tool handler to automatically convert Results to MCP format.
+ *
+ * @param handler - Sync function returning Result<T>
+ * @param errorCode - Default error code for unexpected errors
+ * @returns Wrapped handler returning CallToolResult
+ */
+export function wrapToolHandlerSync(handler, errorCode = 'HANDLER_ERROR') {
+    return (args) => {
+        try {
+            const result = handler(args);
+            return toMcpResult(result);
+        }
+        catch (error) {
+            return mcpFromError(error, errorCode);
+        }
+    };
+}
+//# sourceMappingURL=mcp-adapter.js.map

package/dist/core/result/mcp-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-adapter.js","sourceRoot":"","sources":["../../../src/core/result/mcp-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAyCxF,gFAAgF;AAChF,wBAAwB;AACxB,gFAAgF;AAEhF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CACzB,MAAiB,EACjB,UAA8B,EAAE;IAEhC,MAAM,EAAE,WAAW,GAAG,IAAI,EAAE,gBAAgB,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAEhE,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;QACtB,MAAM,OAAO,GAAyB;YACpC,OAAO,EAAE,IAAI;YACb,IAAI,EAAE,MAAM,CAAC,IAAI;SAClB,CAAC;QAEF,IAAI,gBAAgB,EAAE,CAAC;YACrB,OAAO,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC/C,CAAC;QAED,OAAO;YACL,OAAO,EAAE,CAAC;oBACR,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;iBAC/E,CAAC;SACH,CAAC;IACJ,CAAC;IAED,eAAe;IACf,MAAM,YAAY,GAAoB;QACpC,OAAO,EAAE,KAAK;QACd,KAAK,EAAE;YACL,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI;YACvB,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO;YAC7B,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO;YAC7B,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS;SAClC;QACD,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IAEF,OAAO;QACL,OAAO,EAAE,CAAC;gBACR,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC;aACzF,CAAC;QACF,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CACxB,IAAO,EACP,UAA8B,EAAE;IAEhC,OAAO,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,OAAe,EACf,OAAiC,EACjC,UAA8B,EAAE;IAEhC,OAAO,WAAW,CAChB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC,EACzC,OAAO,CACR,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,UAA8B,EAAE;IAEhC,MAAM,EAAE,WAAW,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACvC,MAAM,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAEnC,OAAO;QACL,OAAO,EAAE,CAAC;gBACR,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;aAC/E,CAAC;QACF,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAsB,EACtB,cAAsB,eAAe,EACrC,UAA8B,EAAE;IAEhC,OAAO,WAAW,CAAC,SAAS,CAAC,KAAK,EAAE,WAAW,CAAC,EAAE,OAAO,CAAC,CAAC;AAC7D,CAAC;AAiBD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAA4B,EAC5B,UAA8B,EAAE;IAEhC,MAAM,EAAE,WAAW,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAEvC,kCAAkC;IAClC,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;IAE/D,OAAO;QACL,OAAO,EAAE,CAAC;gBACR,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;aACjF,CAAC;QACF,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;KAClC,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAkD,EAClD,OAA6D,EAC7D,UAA8B,EAAE;IAEhC,MAAM,EAAE,WAAW,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAEvC,MAAM,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QACzD,GAAG;QACH,OAAO,EAAE,SAAS,CAAC,MAAM,CAAC;QAC1B,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC;YACnB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE;YACvB,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CACxE;KACF,CAAC,CAAC,CAAC;IAEJ,MAAM,OAAO,GAAG;QACd,OAAO,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC;QAC7B,OAAO;QACP,OAAO,EAAE,gBAAgB;QACzB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IAEF,OAAO;QACL,OAAO,EAAE,CAAC;gBACR,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;aAC/E,CAAC;QACF,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,SAAS,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;KACxE,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAkD,EAClD,YAAoB,eAAe;IAEnC,OAAO,KAAK,EAAE,IAAW,EAA2B,EAAE;QACpD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;YACnC,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,YAAY,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACxC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAyC,EACzC,YAAoB,eAAe;IAEnC,OAAO,CAAC,IAAW,EAAkB,EAAE;QACrC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;YAC7B,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,YAAY,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACxC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,170 @@
+/**
+ * ===============================================================================
+ * RESULT TYPE DEFINITIONS
+ * ===============================================================================
+ *
+ * Unified result type for operations that can fail.
+ * Replaces inconsistent { success, error?, data? } patterns with a type-safe
+ * discriminated union that enables proper type narrowing.
+ *
+ * Usage:
+ *   const result = await someOperation();
+ *   if (isSuccess(result)) {
+ *     console.log(result.data);  // TypeScript knows data exists
+ *   } else {
+ *     console.error(result.error.message);  // TypeScript knows error exists
+ *   }
+ *
+ * ===============================================================================
+ */
+/**
+ * Optional metadata attached to any result.
+ * Useful for performance tracking, caching, and correlation.
+ */
+export interface ResultMetadata {
+    /** Execution time in milliseconds */
+    executionTimeMs?: number;
+    /** Whether the result came from cache */
+    cacheHit?: boolean;
+    /** Number of retry attempts before success/failure */
+    retryCount?: number;
+    /** Correlation ID for distributed tracing */
+    correlationId?: string;
+    /** Timestamp when the result was created */
+    timestamp?: number;
+    /** Additional context-specific metadata */
+    context?: Record<string, unknown>;
+}
+/**
+ * Structured error information for failed operations.
+ * Provides consistent error handling across the codebase.
+ */
+export interface ResultError {
+    /** Machine-readable error code (e.g., 'VALIDATION_FAILED', 'NOT_FOUND') */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error details for debugging */
+    details?: Record<string, unknown>;
+    /** Whether the operation can be retried */
+    retryable?: boolean;
+    /** Suggested retry delay in milliseconds */
+    retryAfterMs?: number;
+    /** Stack trace (only in development) */
+    stack?: string;
+    /** Nested cause error */
+    cause?: ResultError;
+}
+/**
+ * Represents a successful operation result.
+ * The `success: true` literal enables TypeScript type narrowing.
+ */
+export interface Success<T> {
+    /** Discriminant for type narrowing - always true for Success */
+    success: true;
+    /** The successful result data */
+    data: T;
+    /** Optional metadata about the operation */
+    metadata?: ResultMetadata;
+}
+/**
+ * Represents a failed operation result.
+ * The `success: false` literal enables TypeScript type narrowing.
+ */
+export interface Failure {
+    /** Discriminant for type narrowing - always false for Failure */
+    success: false;
+    /** Structured error information */
+    error: ResultError;
+    /** Optional metadata about the operation */
+    metadata?: ResultMetadata;
+}
+/**
+ * Unified result type representing either success or failure.
+ *
+ * This is a discriminated union on the `success` property, enabling
+ * TypeScript to narrow the type correctly:
+ *
+ * ```typescript
+ * function handle(result: Result<User>): void {
+ *   if (result.success) {
+ *     // TypeScript knows: result is Success<User>
+ *     console.log(result.data.name);
+ *   } else {
+ *     // TypeScript knows: result is Failure
+ *     console.error(result.error.message);
+ *   }
+ * }
+ * ```
+ */
+export type Result<T> = Success<T> | Failure;
+/**
+ * Result entry for batch operations.
+ * Associates a key with its result for tracking individual items.
+ */
+export interface BatchResultEntry<T> {
+    /** Unique key identifying this item in the batch */
+    key: string;
+    /** The result for this item */
+    result: Result<T>;
+}
+/**
+ * Summary statistics for batch operations.
+ */
+export interface BatchSummary {
+    /** Total number of items processed */
+    total: number;
+    /** Number of successful operations */
+    succeeded: number;
+    /** Number of failed operations */
+    failed: number;
+    /** Total execution time in milliseconds */
+    executionTimeMs: number;
+    /** Average execution time per item */
+    averageTimePerItemMs?: number;
+    /** Timestamp when batch started */
+    startedAt?: number;
+    /** Timestamp when batch completed */
+    completedAt?: number;
+}
+/**
+ * Result type for batch operations.
+ * Contains individual results keyed by identifier plus summary statistics.
+ */
+export interface BatchResult<T> {
+    /** Individual results for each item in the batch */
+    results: Array<BatchResultEntry<T>>;
+    /** Summary statistics for the batch operation */
+    summary: BatchSummary;
+    /** Whether all operations succeeded */
+    allSucceeded: boolean;
+    /** Whether all operations failed */
+    allFailed: boolean;
+    /** List of keys that failed (for easy error handling) */
+    failedKeys: string[];
+    /** List of keys that succeeded (for easy result extraction) */
+    succeededKeys: string[];
+}
+/**
+ * Promise that resolves to a Result.
+ * Convenience type for async operations.
+ */
+export type AsyncResult<T> = Promise<Result<T>>;
+/**
+ * Promise that resolves to a BatchResult.
+ * Convenience type for async batch operations.
+ */
+export type AsyncBatchResult<T> = Promise<BatchResult<T>>;
+/**
+ * Legacy result format found in existing codebase.
+ * Used for migration utilities.
+ *
+ * @deprecated Use Result<T> instead
+ */
+export interface LegacyResult<T = unknown> {
+    success: boolean;
+    error?: string;
+    data?: T;
+    [key: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/core/result/types.js

@@ -0,0 +1,21 @@
+/**
+ * ===============================================================================
+ * RESULT TYPE DEFINITIONS
+ * ===============================================================================
+ *
+ * Unified result type for operations that can fail.
+ * Replaces inconsistent { success, error?, data? } patterns with a type-safe
+ * discriminated union that enables proper type narrowing.
+ *
+ * Usage:
+ *   const result = await someOperation();
+ *   if (isSuccess(result)) {
+ *     console.log(result.data);  // TypeScript knows data exists
+ *   } else {
+ *     console.error(result.error.message);  // TypeScript knows error exists
+ *   }
+ *
+ * ===============================================================================
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/result/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/result/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}