@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwCH,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E,SAAS,gBAAgB;IAGvB,MAAM,KAAK,GAA0D,EAAE,CAAC;IAExE,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,GAAW,EAAE,IAA8B,EAAE,EAAE;QAC/E,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;IACnC,CAAC,CAAC;IAEF,OAAO;QACL,KAAK;QACL,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC;QACrB,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC;QACnB,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC;QACvB,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC;QACzB,KAAK,EAAE,CAAC,GAAW,EAAE,MAAc,EAAE,IAA8B,EAAE,EAAE;YACrE,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5C,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,QAAiB;IACxC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAExC,MAAM,aAAa,GAAG,GAAG,EAAE;QACzB,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,GAAG,CAAC,GAAG;YACL,aAAa,EAAE,CAAC;YAChB,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,CAAC;QACjD,CAAC;QACD,GAAG,CAAC,GAAG,EAAE,KAAK;YACZ,aAAa,EAAE,CAAC;YAChB,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACtB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,MAAM,CAAC,GAAG;YACR,aAAa,EAAE,CAAC;YAChB,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAClB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,MAAM;YACT,aAAa,EAAE,CAAC;YAChB,MAAM,KAAK,GAA0C,EAAE,CAAC;YACxD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;gBACjC,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;oBACtC,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;gBAC7B,CAAC;YACH,CAAC;YACD,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB;IAKzB,MAAM,KAAK,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,SAAS,EAAE,EAAc,EAAE,CAAC;IAEtE,OAAO;QACL,IAAI,MAAM;YACR,OAAO,KAAK,CAAC,MAAM,CAAC;QACtB,CAAC;QACD,IAAI,UAAU;YACZ,OAAO,KAAK,CAAC,UAAU,CAAC;QAC1B,CAAC;QACD,IAAI,SAAS;YACX,OAAO,KAAK,CAAC,SAAS,CAAC;QACzB,CAAC;QACD,QAAQ,CAAC,CAAC;YACR,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;YACjB,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC;YACrB,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,SAAS,CAAC,MAAM,GAAG,CAAC;YAClB,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CACzB,KAAK,CAAC,UAAU,GAAG,MAAM,EACzB,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,UAAU,GAAG,MAAM,CAC1C,CAAC;YACF,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,MAAM,CAAC,OAAO;YACZ,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC9B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAA8B,EAAE;IAChE,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAErE,OAAO;QACL,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,iBAAiB;QACjD,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,GAAG;QACH,KAAK;QACL,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC,MAAM;QACtD,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ;QACR,GAAG,EAAE,OAAO,CAAC,GAAG;KACjB,CAAC;AACJ,CAAC"}

package/dist/types-global/errors.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Defines standardized error codes, a custom error class, and related schemas
+ * for handling errors within the Model Context Protocol (MCP) server and its components.
+ * This module provides a structured way to represent and communicate errors, ensuring
+ * consistency and clarity for both server-side operations and client-side error handling.
+ * @module src/types-global/errors
+ */
+import { z } from 'zod';
+/**
+ * Defines JSON-RPC 2.0 error codes, including standard and implementation-defined codes.
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
+export declare enum JsonRpcErrorCode {
+    ParseError = -32700,
+    InvalidRequest = -32600,
+    MethodNotFound = -32601,
+    InvalidParams = -32602,
+    InternalError = -32603,
+    ServiceUnavailable = -32000,
+    NotFound = -32001,
+    Conflict = -32002,
+    RateLimited = -32003,
+    Timeout = -32004,
+    Forbidden = -32005,
+    Unauthorized = -32006,
+    ValidationError = -32007,
+    ConfigurationError = -32008,
+    InitializationFailed = -32009,
+    DatabaseError = -32010,
+    SerializationError = -32070,// Data serialization/deserialization failed
+    UnknownError = -32099
+}
+/**
+ * Custom error class for MCP-specific errors, extending the built-in `Error` class.
+ * It standardizes error reporting by encapsulating a `JsonRpcErrorCode`, a descriptive
+ * human-readable message, and optional structured data for more context.
+ *
+ * This class is central to error handling within the MCP framework, allowing for
+ * consistent error creation and propagation.
+ */
+export declare class McpError extends Error {
+    /**
+     * The standardized error code from {@link JsonRpcErrorCode}.
+     */
+    readonly code: JsonRpcErrorCode;
+    /**
+     * Optional additional data about the error, conforming to the JSON-RPC 2.0 specification.
+     * This can be any structured data that helps in understanding or debugging the error.
+     * @see https://www.jsonrpc.org/specification#error_object
+     */
+    readonly data?: Record<string, unknown>;
+    /**
+     * Creates an instance of McpError.
+     *
+     * @param code - The standardized error code that categorizes the error.
+     * @param message - A human-readable description of the error.
+     * @param data - Optional. A record containing additional structured data about the error.
+     */
+    constructor(code: JsonRpcErrorCode, message?: string, data?: Record<string, unknown>, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Zod schema for validating error objects. This schema can be used for:
+ * - Validating error structures when parsing error responses from external services.
+ * - Ensuring consistency when creating or handling error objects internally.
+ * - Generating TypeScript types for error objects.
+ *
+ * The schema enforces the presence of a `code` (from {@link JsonRpcErrorCode}) and a `message`,
+ * and allows for optional `data`.
+ */
+export declare const ErrorSchema: z.ZodObject<{
+    code: z.ZodEnum<typeof JsonRpcErrorCode>;
+    message: z.ZodString;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * TypeScript type inferred from the {@link ErrorSchema}.
+ * This type represents the structure of a validated error object, commonly used
+ * for error responses or when passing error information within the application.
+ */
+export type ErrorResponse = z.infer<typeof ErrorSchema>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/types-global/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types-global/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,oBAAY,gBAAgB;IAE1B,UAAU,SAAS;IACnB,cAAc,SAAS;IACvB,cAAc,SAAS;IACvB,aAAa,SAAS;IACtB,aAAa,SAAS;IAGtB,kBAAkB,SAAS;IAC3B,QAAQ,SAAS;IACjB,QAAQ,SAAS;IACjB,WAAW,SAAS;IACpB,OAAO,SAAS;IAChB,SAAS,SAAS;IAClB,YAAY,SAAS;IACrB,eAAe,SAAS;IACxB,kBAAkB,SAAS;IAC3B,oBAAoB,SAAS;IAC7B,aAAa,SAAS;IACtB,kBAAkB,SAAS,CAAE,4CAA4C;IACzE,YAAY,SAAS;CACtB;AAED;;;;;;;GAOG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC;;OAEG;IACH,SAAgB,IAAI,EAAE,gBAAgB,CAAC;IAEvC;;;;OAIG;IACH,SAAgB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE/C;;;;;;OAMG;gBAED,IAAI,EAAE,gBAAgB,EACtB,OAAO,CAAC,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAkBhC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW;;;;iBA4BrB,CAAC;AAEJ;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}

package/dist/types-global/errors.js

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Defines standardized error codes, a custom error class, and related schemas
+ * for handling errors within the Model Context Protocol (MCP) server and its components.
+ * This module provides a structured way to represent and communicate errors, ensuring
+ * consistency and clarity for both server-side operations and client-side error handling.
+ * @module src/types-global/errors
+ */
+import { z } from 'zod';
+/**
+ * Defines JSON-RPC 2.0 error codes, including standard and implementation-defined codes.
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
+export var JsonRpcErrorCode;
+(function (JsonRpcErrorCode) {
+    // Standard JSON-RPC 2.0 Errors
+    JsonRpcErrorCode[JsonRpcErrorCode["ParseError"] = -32700] = "ParseError";
+    JsonRpcErrorCode[JsonRpcErrorCode["InvalidRequest"] = -32600] = "InvalidRequest";
+    JsonRpcErrorCode[JsonRpcErrorCode["MethodNotFound"] = -32601] = "MethodNotFound";
+    JsonRpcErrorCode[JsonRpcErrorCode["InvalidParams"] = -32602] = "InvalidParams";
+    JsonRpcErrorCode[JsonRpcErrorCode["InternalError"] = -32603] = "InternalError";
+    // Implementation-defined server-errors (-32000 to -32099)
+    JsonRpcErrorCode[JsonRpcErrorCode["ServiceUnavailable"] = -32000] = "ServiceUnavailable";
+    JsonRpcErrorCode[JsonRpcErrorCode["NotFound"] = -32001] = "NotFound";
+    JsonRpcErrorCode[JsonRpcErrorCode["Conflict"] = -32002] = "Conflict";
+    JsonRpcErrorCode[JsonRpcErrorCode["RateLimited"] = -32003] = "RateLimited";
+    JsonRpcErrorCode[JsonRpcErrorCode["Timeout"] = -32004] = "Timeout";
+    JsonRpcErrorCode[JsonRpcErrorCode["Forbidden"] = -32005] = "Forbidden";
+    JsonRpcErrorCode[JsonRpcErrorCode["Unauthorized"] = -32006] = "Unauthorized";
+    JsonRpcErrorCode[JsonRpcErrorCode["ValidationError"] = -32007] = "ValidationError";
+    JsonRpcErrorCode[JsonRpcErrorCode["ConfigurationError"] = -32008] = "ConfigurationError";
+    JsonRpcErrorCode[JsonRpcErrorCode["InitializationFailed"] = -32009] = "InitializationFailed";
+    JsonRpcErrorCode[JsonRpcErrorCode["DatabaseError"] = -32010] = "DatabaseError";
+    JsonRpcErrorCode[JsonRpcErrorCode["SerializationError"] = -32070] = "SerializationError";
+    JsonRpcErrorCode[JsonRpcErrorCode["UnknownError"] = -32099] = "UnknownError";
+})(JsonRpcErrorCode || (JsonRpcErrorCode = {}));
+/**
+ * Custom error class for MCP-specific errors, extending the built-in `Error` class.
+ * It standardizes error reporting by encapsulating a `JsonRpcErrorCode`, a descriptive
+ * human-readable message, and optional structured data for more context.
+ *
+ * This class is central to error handling within the MCP framework, allowing for
+ * consistent error creation and propagation.
+ */
+export class McpError extends Error {
+    /**
+     * The standardized error code from {@link JsonRpcErrorCode}.
+     */
+    code;
+    /**
+     * Optional additional data about the error, conforming to the JSON-RPC 2.0 specification.
+     * This can be any structured data that helps in understanding or debugging the error.
+     * @see https://www.jsonrpc.org/specification#error_object
+     */
+    data;
+    /**
+     * Creates an instance of McpError.
+     *
+     * @param code - The standardized error code that categorizes the error.
+     * @param message - A human-readable description of the error.
+     * @param data - Optional. A record containing additional structured data about the error.
+     */
+    constructor(code, message, data, options) {
+        super(message, options);
+        this.code = code;
+        if (data) {
+            this.data = data;
+        }
+        this.name = 'McpError';
+        // Maintain a proper prototype chain.
+        Object.setPrototypeOf(this, McpError.prototype);
+        // Capture the stack trace, excluding the constructor call from it, if available.
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, McpError);
+        }
+    }
+}
+/**
+ * Zod schema for validating error objects. This schema can be used for:
+ * - Validating error structures when parsing error responses from external services.
+ * - Ensuring consistency when creating or handling error objects internally.
+ * - Generating TypeScript types for error objects.
+ *
+ * The schema enforces the presence of a `code` (from {@link JsonRpcErrorCode}) and a `message`,
+ * and allows for optional `data`.
+ */
+export const ErrorSchema = z
+    .object({
+    /**
+     * The error code, corresponding to one of the {@link JsonRpcErrorCode} enum values.
+     * This field is required and helps in programmatically identifying the error type.
+     */
+    code: z
+        .nativeEnum(JsonRpcErrorCode)
+        .describe('Standardized error code from JsonRpcErrorCode enum'),
+    /**
+     * A human-readable, descriptive message explaining the error.
+     * This field is required and provides context to developers or users.
+     */
+    message: z
+        .string()
+        .min(1, 'Error message cannot be empty.')
+        .describe('Detailed human-readable error message'),
+    /**
+     * Optional. A record containing additional structured data or context about the error,
+     * conforming to the JSON-RPC 2.0 `data` field.
+     */
+    data: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe('Optional structured data providing more context about the error'),
+})
+    .describe('Schema for validating structured error objects, ensuring consistency in error reporting.');
+//# sourceMappingURL=errors.js.map

package/dist/types-global/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/types-global/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,MAAM,CAAN,IAAY,gBAsBX;AAtBD,WAAY,gBAAgB;IAC1B,+BAA+B;IAC/B,wEAAmB,CAAA;IACnB,gFAAuB,CAAA;IACvB,gFAAuB,CAAA;IACvB,8EAAsB,CAAA;IACtB,8EAAsB,CAAA;IAEtB,0DAA0D;IAC1D,wFAA2B,CAAA;IAC3B,oEAAiB,CAAA;IACjB,oEAAiB,CAAA;IACjB,0EAAoB,CAAA;IACpB,kEAAgB,CAAA;IAChB,sEAAkB,CAAA;IAClB,4EAAqB,CAAA;IACrB,kFAAwB,CAAA;IACxB,wFAA2B,CAAA;IAC3B,4FAA6B,CAAA;IAC7B,8EAAsB,CAAA;IACtB,wFAA2B,CAAA;IAC3B,4EAAqB,CAAA;AACvB,CAAC,EAtBW,gBAAgB,KAAhB,gBAAgB,QAsB3B;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC;;OAEG;IACa,IAAI,CAAmB;IAEvC;;;;OAIG;IACa,IAAI,CAA2B;IAE/C;;;;;;OAMG;IACH,YACE,IAAsB,EACtB,OAAgB,EAChB,IAA8B,EAC9B,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAExB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACnB,CAAC;QACD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QAEvB,qCAAqC;QACrC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;QAEhD,iFAAiF;QACjF,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC;KACzB,MAAM,CAAC;IACN;;;OAGG;IACH,IAAI,EAAE,CAAC;SACJ,UAAU,CAAC,gBAAgB,CAAC;SAC5B,QAAQ,CAAC,oDAAoD,CAAC;IACjE;;;OAGG;IACH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,gCAAgC,CAAC;SACxC,QAAQ,CAAC,uCAAuC,CAAC;IACpD;;;OAGG;IACH,IAAI,EAAE,CAAC;SACJ,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/B,QAAQ,EAAE;SACV,QAAQ,CAAC,iEAAiE,CAAC;CAC/E,CAAC;KACD,QAAQ,CACP,0FAA0F,CAC3F,CAAC"}

package/dist/utils/formatting/diffFormatter.d.ts

@@ -0,0 +1,227 @@
+/**
+ * @fileoverview Diff formatter utility for comparing text and generating unified diffs.
+ * Wraps the `diff` npm package (jsdiff) to produce git-style unified diff output with
+ * configurable context lines and multiple output formats. All public methods are async
+ * because the underlying `diff` library is loaded lazily on first use to avoid paying
+ * the import cost when the formatter is not needed.
+ * @module src/utils/formatting/diffFormatter
+ */
+import { type RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Diff output format options.
+ * - `unified`: Standard unified diff hunks only — strips file/index headers (like `git diff` body).
+ * - `patch`: Full patch format including `---`/`+++` file headers and index line.
+ * - `inline`: No headers or hunk markers; additions wrapped as `[+text+]`, deletions as `[-text-]`.
+ */
+export type DiffFormat = 'unified' | 'patch' | 'inline';
+/**
+ * Configuration options for diff formatting.
+ */
+export interface DiffFormatterOptions {
+    /**
+     * Number of unchanged lines to show around each change (default: 3).
+     * This is the "context" in unified diff format.
+     */
+    context?: number;
+    /**
+     * Output format for the diff. Defaults to `'unified'`.
+     * See {@link DiffFormat} for a description of each format.
+     */
+    format?: DiffFormat;
+    /**
+     * Whether to include file headers in patch format (default: true).
+     */
+    includeHeaders?: boolean;
+    /**
+     * File path for new version (used in headers).
+     */
+    newPath?: string;
+    /**
+     * File path for old version (used in headers).
+     */
+    oldPath?: string;
+    /**
+     * Whether to include line numbers in the output (default: true).
+     */
+    showLineNumbers?: boolean;
+}
+/**
+ * Utility class for generating diffs between text content.
+ *
+ * Wraps the `diff` npm package to produce git-style unified diff output. The `diff`
+ * dependency is loaded lazily — all methods are `async` and will throw a
+ * `ConfigurationError` if the package is not installed (`bun add diff`).
+ *
+ * Use the exported {@link diffFormatter} singleton rather than constructing instances
+ * directly.
+ */
+export declare class DiffFormatter {
+    /** Default formatting options applied when options are omitted or partially provided. */
+    private readonly defaultOptions;
+    /**
+     * Generate a unified diff between two text strings.
+     *
+     * Compares content line-by-line using `diff.createPatch` and produces output
+     * equivalent to `git diff`. This method is async because the `diff` package is
+     * loaded lazily on first call.
+     *
+     * @param oldText - Original text content.
+     * @param newText - Modified text content.
+     * @param options - Diff formatting options. Defaults: `format: 'unified'`, `context: 3`,
+     *   `showLineNumbers: true`, `includeHeaders: true`.
+     * @param context - Optional request context for correlated logging. A new context is
+     *   created automatically when omitted.
+     * @returns Formatted diff string. Returns an empty string (or a no-change patch) when
+     *   `oldText` and `newText` are identical.
+     * @throws {McpError} With `ConfigurationError` if the `diff` package is not installed.
+     * @throws {McpError} With `ValidationError` if either argument is not a string.
+     * @throws {McpError} With `InternalError` if diff generation fails unexpectedly.
+     *
+     * @example
+     * ```typescript
+     * const oldCode = 'function hello() {\n  console.log("Hi");\n}';
+     * const newCode = 'function hello(name) {\n  console.log(`Hello, ${name}!`);\n}';
+     * const result = await diffFormatter.diff(oldCode, newCode, { context: 2 });
+     * ```
+     */
+    diff(oldText: string, newText: string, options?: DiffFormatterOptions, context?: RequestContext): Promise<string>;
+    /**
+     * Generate a diff between two arrays of lines.
+     *
+     * A convenience wrapper around {@link diff} for callers that have already split
+     * text into line arrays. Lines are joined with `\n` before diffing. This method
+     * is async because it delegates to {@link diff}, which loads the `diff` package lazily.
+     *
+     * @param oldLines - Original lines (each element is one line, without a trailing newline).
+     * @param newLines - Modified lines.
+     * @param options - Diff formatting options. Passed through to {@link diff}.
+     * @param context - Optional request context for correlated logging.
+     * @returns Formatted diff string.
+     * @throws {McpError} With `ValidationError` if either argument is not an array.
+     * @throws {McpError} Propagates any error thrown by {@link diff}.
+     *
+     * @example
+     * ```typescript
+     * const oldLines = ['line 1', 'line 2', 'line 3'];
+     * const newLines = ['line 1', 'modified line 2', 'line 3', 'line 4'];
+     * const result = await diffFormatter.diffLines(oldLines, newLines);
+     * ```
+     */
+    diffLines(oldLines: string[], newLines: string[], options?: DiffFormatterOptions, context?: RequestContext): Promise<string>;
+    /**
+     * Generate a word-level diff between two text strings.
+     *
+     * Uses `diff.diffWords` to highlight changes at the word boundary rather than
+     * at the line level. Output uses inline visual markers: added words are wrapped
+     * as `[+word+]` and removed words as `[-word-]`. Unchanged words are emitted
+     * as-is. This is particularly useful for diffing prose or documentation.
+     *
+     * This method is async because the `diff` package is loaded lazily on first call.
+     *
+     * @param oldText - Original text content.
+     * @param newText - Modified text content.
+     * @param context - Optional request context for correlated logging.
+     * @returns Inline word-diff string with `[+added+]` and `[-removed-]` markers.
+     * @throws {McpError} With `ConfigurationError` if the `diff` package is not installed.
+     * @throws {McpError} With `ValidationError` if either argument is not a string.
+     * @throws {McpError} With `InternalError` if diff generation fails unexpectedly.
+     *
+     * @example
+     * ```typescript
+     * const oldText = 'The quick brown fox';
+     * const newText = 'The fast brown dog';
+     * const result = await diffFormatter.diffWords(oldText, newText);
+     * // => 'The [-quick-][+fast+] brown [-fox-][+dog+]'
+     * ```
+     */
+    diffWords(oldText: string, newText: string, context?: RequestContext): Promise<string>;
+    /**
+     * Dispatch to the appropriate formatter based on `options.format`.
+     *
+     * @param patch - Raw patch string produced by `diff.createPatch`.
+     * @param options - Resolved formatting options (no optional fields except path names).
+     * @returns Formatted diff string.
+     */
+    private formatDiff;
+    /**
+     * Strip the `Index:`, `===`, `---`, and `+++` header lines from a patch string,
+     * returning only the `@@` hunk markers and diff body lines.
+     *
+     * @param patch - Raw patch string from `diff.createPatch`.
+     * @returns Patch with file/index headers removed, starting from the first `@@` line.
+     *   Returns `patch` unchanged if no `@@` line is found (no differences).
+     */
+    private stripHeaders;
+    /**
+     * Convert a unified patch string to inline format.
+     *
+     * Strips all header lines (`Index:`, `===`, `---`, `+++`, `@@`, `\ No newline…`) and
+     * rewrites each diff line using visual markers: lines beginning with `-` become
+     * `[-content-]`, lines beginning with `+` become `[+content+]`, and context lines
+     * (space-prefixed) are emitted without the leading space.
+     *
+     * @param patch - Raw patch string from `diff.createPatch`.
+     * @returns Inline diff string with `[+..+]`/`[-..-]` markers and no header lines.
+     */
+    private formatInline;
+    /**
+     * Compute line-level statistics for the differences between two texts.
+     *
+     * Uses `diff.diffLines` to count added and deleted lines. The `changes` field is
+     * the sum of `additions + deletions`. This method is async because the `diff`
+     * package is loaded lazily on first call.
+     *
+     * @param oldText - Original text content.
+     * @param newText - Modified text content.
+     * @param context - Optional request context for correlated logging.
+     * @returns `{ additions, deletions, changes }` — all values are line counts.
+     *   `additions` and `deletions` are both `0` when the texts are identical.
+     * @throws {McpError} With `ConfigurationError` if the `diff` package is not installed.
+     * @throws {McpError} With `InternalError` if analysis fails unexpectedly.
+     *
+     * @example
+     * ```typescript
+     * const stats = await diffFormatter.getStats(oldText, newText);
+     * console.log(`+${stats.additions} -${stats.deletions} (~${stats.changes} lines changed)`);
+     * ```
+     */
+    getStats(oldText: string, newText: string, context?: RequestContext): Promise<{
+        additions: number;
+        deletions: number;
+        changes: number;
+    }>;
+}
+/**
+ * Singleton instance of {@link DiffFormatter}.
+ *
+ * All methods are async — they load the `diff` package lazily on first call.
+ * Install the peer dependency if not already present: `bun add diff`.
+ *
+ * @example
+ * ```typescript
+ * import { diffFormatter } from '../../utils/formatting/diffFormatter.js';
+ *
+ * const oldCode = `function hello() {
+ *   console.log('Hi');
+ * }`;
+ *
+ * const newCode = `function hello(name: string) {
+ *   console.log(\`Hello, \${name}!\`);
+ * }`;
+ *
+ * // Standard unified diff (hunk headers, no file headers)
+ * const unified = await diffFormatter.diff(oldCode, newCode);
+ *
+ * // Inline diff — additions as [+text+], deletions as [-text-]
+ * const inline = await diffFormatter.diff(oldCode, newCode, { format: 'inline' });
+ *
+ * // Line-level change counts
+ * const stats = await diffFormatter.getStats(oldCode, newCode);
+ * console.log(`Changes: +${stats.additions} -${stats.deletions}`);
+ *
+ * // Word-level diff for prose
+ * const wordDiff = await diffFormatter.diffWords('The quick brown fox', 'The fast brown dog');
+ * ```
+ */
+export declare const diffFormatter: DiffFormatter;
+//# sourceMappingURL=diffFormatter.d.ts.map

package/dist/utils/formatting/diffFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diffFormatter.d.ts","sourceRoot":"","sources":["../../../src/utils/formatting/diffFormatter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,oCAAoC,CAAC;AAEhG;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IAEpB;;OAEG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACxB,yFAAyF;IACzF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAK7B;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,IAAI,CACR,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,oBAAoB,EAC9B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,MAAM,CAAC;IAiElB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,SAAS,CACb,QAAQ,EAAE,MAAM,EAAE,EAClB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,oBAAoB,EAC9B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,MAAM,CAAC;IAuBlB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAwD5F;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAuBlB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAUpB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,YAAY;IA+BpB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,QAAQ,CACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAiCtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,aAAa,eAAsB,CAAC"}