@ibm/ibmi-mcp-server 0.1.0

package/dist/utils/network/fetchWithTimeout.js

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Provides a utility function to make fetch requests with a specified timeout.
+ * @module src/utils/network/fetchWithTimeout
+ */
+import { logger } from "../internal/logger.js"; // Adjusted import path
+import { McpError, JsonRpcErrorCode } from "../../types-global/errors.js";
+/**
+ * Fetches a resource with a specified timeout.
+ *
+ * @param url - The URL to fetch.
+ * @param timeoutMs - The timeout duration in milliseconds.
+ * @param context - The request context for logging.
+ * @param options - Optional fetch options (RequestInit), excluding 'signal'.
+ * @returns A promise that resolves to the Response object.
+ * @throws {McpError} If the request times out or another fetch-related error occurs.
+ */
+export async function fetchWithTimeout(url, timeoutMs, context, options) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    const urlString = url.toString();
+    const operationDescription = `fetch ${options?.method || "GET"} ${urlString}`;
+    logger.debug(context, `Attempting ${operationDescription} with ${timeoutMs}ms timeout.`);
+    try {
+        const response = await fetch(url, {
+            ...options,
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            const errorBody = await response
+                .text()
+                .catch(() => "Could not read response body");
+            logger.error({
+                ...context,
+                statusCode: response.status,
+                statusText: response.statusText,
+                responseBody: errorBody,
+                errorSource: "FetchHttpError",
+            }, `Fetch failed for ${urlString} with status ${response.status}.`);
+            throw new McpError(JsonRpcErrorCode.ServiceUnavailable, `Fetch failed for ${urlString}. Status: ${response.status}`, {
+                ...context,
+                statusCode: response.status,
+                statusText: response.statusText,
+                responseBody: errorBody,
+            });
+        }
+        logger.debug(context, `Successfully fetched ${urlString}. Status: ${response.status}`);
+        return response;
+    }
+    catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof Error && error.name === "AbortError") {
+            logger.error({
+                ...context,
+                errorSource: "FetchTimeout",
+            }, `${operationDescription} timed out after ${timeoutMs}ms.`);
+            throw new McpError(JsonRpcErrorCode.Timeout, `${operationDescription} timed out.`, { ...context, errorSource: "FetchTimeout" });
+        }
+        // Log and re-throw other errors as McpError
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error({
+            ...context,
+            originalErrorName: error instanceof Error ? error.name : "UnknownError",
+            errorSource: "FetchNetworkError",
+        }, `Network error during ${operationDescription}: ${errorMessage}`);
+        if (error instanceof McpError) {
+            // If it's already an McpError, re-throw it
+            throw error;
+        }
+        throw new McpError(JsonRpcErrorCode.ServiceUnavailable, // Generic error for network/service issues
+        `Network error during ${operationDescription}: ${errorMessage}`, {
+            ...context,
+            originalErrorName: error instanceof Error ? error.name : "UnknownError",
+            errorSource: "FetchNetworkErrorWrapper",
+        });
+    }
+}
+//# sourceMappingURL=fetchWithTimeout.js.map

package/dist/utils/network/fetchWithTimeout.js.map

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

package/dist/utils/network/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for network utilities.
+ * @module src/utils/network/index
+ */
+export * from "./fetchWithTimeout.js";
+export type { FetchWithTimeoutOptions } from "./fetchWithTimeout.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/network/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/network/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,uBAAuB,CAAC;AACtC,YAAY,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/utils/network/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Barrel file for network utilities.
+ * @module src/utils/network/index
+ */
+export * from "./fetchWithTimeout.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/network/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/network/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,uBAAuB,CAAC"}

package/dist/utils/parsing/dateParser.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Provides utility functions for parsing natural language date strings
+ * into Date objects or detailed parsing results using the `chrono-node` library.
+ * @module src/utils/parsing/dateParser
+ */
+import * as chrono from "chrono-node";
+import { RequestContext } from "../index.js";
+/**
+ * Parses a natural language date string into a JavaScript Date object.
+ * Uses `chrono.parseDate` for lenient parsing of various date formats.
+ *
+ * @param text - The natural language date string to parse.
+ * @param context - The request context for logging and error tracking.
+ * @param refDate - Optional reference date for parsing relative dates. Defaults to current date/time.
+ * @returns A promise resolving with a Date object or `null` if parsing fails.
+ * @throws {McpError} If an unexpected error occurs during parsing.
+ * @private
+ */
+export declare function parseDateString(text: string, context: RequestContext, refDate?: Date): Promise<Date | null>;
+/**
+ * Parses a natural language date string and returns detailed parsing results.
+ * Provides more information than just the Date object, including matched text and components.
+ *
+ * @param text - The natural language date string to parse.
+ * @param context - The request context for logging and error tracking.
+ * @param refDate - Optional reference date for parsing relative dates. Defaults to current date/time.
+ * @returns A promise resolving with an array of `chrono.ParsedResult` objects. Empty if no dates found.
+ * @throws {McpError} If an unexpected error occurs during parsing.
+ * @private
+ */
+export declare function parseDateStringDetailed(text: string, context: RequestContext, refDate?: Date): Promise<chrono.ParsedResult[]>;
+/**
+ * An object providing date parsing functionalities.
+ *
+ * @example
+ * ```typescript
+ * import { dateParser, requestContextService } from './utils'; // Assuming utils/index.js exports these
+ * const context = requestContextService.createRequestContext({ operation: 'TestDateParsing' });
+ *
+ * async function testParsing() {
+ *   const dateObj = await dateParser.parseDate("next Friday at 3pm", context);
+ *   if (dateObj) {
+ *     console.log("Parsed Date:", dateObj.toISOString());
+ *   }
+ *
+ *   const detailedResults = await dateParser.parse("Meeting on 2024-12-25 and another one tomorrow", context);
+ *   detailedResults.forEach(result => {
+ *     console.log("Detailed Result:", result.text, result.start.date());
+ *   });
+ * }
+ * testParsing();
+ * ```
+ */
+export declare const dateParser: {
+    /**
+     * Parses a natural language date string and returns detailed parsing results
+     * from `chrono-node`.
+     * @param text - The natural language date string to parse.
+     * @param context - The request context for logging and error tracking.
+     * @param refDate - Optional reference date for parsing relative dates.
+     * @returns A promise resolving with an array of `chrono.ParsedResult` objects.
+     */
+    parse: typeof parseDateStringDetailed;
+    /**
+     * Parses a natural language date string into a single JavaScript Date object.
+     * @param text - The natural language date string to parse.
+     * @param context - The request context for logging and error tracking.
+     * @param refDate - Optional reference date for parsing relative dates.
+     * @returns A promise resolving with a Date object or `null`.
+     */
+    parseDate: typeof parseDateString;
+};
+//# sourceMappingURL=dateParser.d.ts.map

package/dist/utils/parsing/dateParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dateParser.d.ts","sourceRoot":"","sources":["../../../src/utils/parsing/dateParser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC,OAAO,EAAwB,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAExE;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,IAAI,GACb,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CA0BtB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,IAAI,GACb,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAwBhC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,UAAU;IACrB;;;;;;;OAOG;;IAEH;;;;;;OAMG;;CAEJ,CAAC"}

package/dist/utils/parsing/dateParser.js

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Provides utility functions for parsing natural language date strings
+ * into Date objects or detailed parsing results using the `chrono-node` library.
+ * @module src/utils/parsing/dateParser
+ */
+import * as chrono from "chrono-node";
+import { JsonRpcErrorCode } from "../../types-global/errors.js";
+import { ErrorHandler, logger } from "../index.js";
+/**
+ * Parses a natural language date string into a JavaScript Date object.
+ * Uses `chrono.parseDate` for lenient parsing of various date formats.
+ *
+ * @param text - The natural language date string to parse.
+ * @param context - The request context for logging and error tracking.
+ * @param refDate - Optional reference date for parsing relative dates. Defaults to current date/time.
+ * @returns A promise resolving with a Date object or `null` if parsing fails.
+ * @throws {McpError} If an unexpected error occurs during parsing.
+ * @private
+ */
+export async function parseDateString(text, context, refDate) {
+    const operation = "parseDateString";
+    const logContext = { ...context, operation, inputText: text, refDate };
+    logger.debug(logContext, `Attempting to parse date string: "${text}"`);
+    return await ErrorHandler.tryCatch(async () => {
+        const parsedDate = chrono.parseDate(text, refDate, { forwardDate: true });
+        if (parsedDate) {
+            logger.debug(logContext, `Successfully parsed "${text}" to ${parsedDate.toISOString()}`);
+            return parsedDate;
+        }
+        else {
+            logger.warning(logContext, `Failed to parse date string: "${text}"`);
+            return null;
+        }
+    }, {
+        operation,
+        context: logContext,
+        input: { text, refDate },
+        errorCode: JsonRpcErrorCode.ParseError,
+    });
+}
+/**
+ * Parses a natural language date string and returns detailed parsing results.
+ * Provides more information than just the Date object, including matched text and components.
+ *
+ * @param text - The natural language date string to parse.
+ * @param context - The request context for logging and error tracking.
+ * @param refDate - Optional reference date for parsing relative dates. Defaults to current date/time.
+ * @returns A promise resolving with an array of `chrono.ParsedResult` objects. Empty if no dates found.
+ * @throws {McpError} If an unexpected error occurs during parsing.
+ * @private
+ */
+export async function parseDateStringDetailed(text, context, refDate) {
+    const operation = "parseDateStringDetailed";
+    const logContext = { ...context, operation, inputText: text, refDate };
+    logger.debug(logContext, `Attempting detailed parse of date string: "${text}"`);
+    return await ErrorHandler.tryCatch(async () => {
+        const results = chrono.parse(text, refDate, { forwardDate: true });
+        logger.debug(logContext, `Detailed parse of "${text}" resulted in ${results.length} result(s)`);
+        return results;
+    }, {
+        operation,
+        context: logContext,
+        input: { text, refDate },
+        errorCode: JsonRpcErrorCode.ParseError,
+    });
+}
+/**
+ * An object providing date parsing functionalities.
+ *
+ * @example
+ * ```typescript
+ * import { dateParser, requestContextService } from './utils'; // Assuming utils/index.js exports these
+ * const context = requestContextService.createRequestContext({ operation: 'TestDateParsing' });
+ *
+ * async function testParsing() {
+ *   const dateObj = await dateParser.parseDate("next Friday at 3pm", context);
+ *   if (dateObj) {
+ *     console.log("Parsed Date:", dateObj.toISOString());
+ *   }
+ *
+ *   const detailedResults = await dateParser.parse("Meeting on 2024-12-25 and another one tomorrow", context);
+ *   detailedResults.forEach(result => {
+ *     console.log("Detailed Result:", result.text, result.start.date());
+ *   });
+ * }
+ * testParsing();
+ * ```
+ */
+export const dateParser = {
+    /**
+     * Parses a natural language date string and returns detailed parsing results
+     * from `chrono-node`.
+     * @param text - The natural language date string to parse.
+     * @param context - The request context for logging and error tracking.
+     * @param refDate - Optional reference date for parsing relative dates.
+     * @returns A promise resolving with an array of `chrono.ParsedResult` objects.
+     */
+    parse: parseDateStringDetailed,
+    /**
+     * Parses a natural language date string into a single JavaScript Date object.
+     * @param text - The natural language date string to parse.
+     * @param context - The request context for logging and error tracking.
+     * @param refDate - Optional reference date for parsing relative dates.
+     * @returns A promise resolving with a Date object or `null`.
+     */
+    parseDate: parseDateString,
+};
+//# sourceMappingURL=dateParser.js.map

package/dist/utils/parsing/dateParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dateParser.js","sourceRoot":"","sources":["../../../src/utils/parsing/dateParser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,EAAkB,MAAM,kBAAkB,CAAC;AAExE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAY,EACZ,OAAuB,EACvB,OAAc;IAEd,MAAM,SAAS,GAAG,iBAAiB,CAAC;IACpC,MAAM,UAAU,GAAG,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACvE,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,qCAAqC,IAAI,GAAG,CAAC,CAAC;IAEvE,OAAO,MAAM,YAAY,CAAC,QAAQ,CAChC,KAAK,IAAI,EAAE;QACT,MAAM,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1E,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CACV,UAAU,EACV,wBAAwB,IAAI,QAAQ,UAAU,CAAC,WAAW,EAAE,EAAE,CAC/D,CAAC;YACF,OAAO,UAAU,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,iCAAiC,IAAI,GAAG,CAAC,CAAC;YACrE,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,EACD;QACE,SAAS;QACT,OAAO,EAAE,UAAU;QACnB,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;QACxB,SAAS,EAAE,gBAAgB,CAAC,UAAU;KACvC,CACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,IAAY,EACZ,OAAuB,EACvB,OAAc;IAEd,MAAM,SAAS,GAAG,yBAAyB,CAAC;IAC5C,MAAM,UAAU,GAAG,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACvE,MAAM,CAAC,KAAK,CACV,UAAU,EACV,8CAA8C,IAAI,GAAG,CACtD,CAAC;IAEF,OAAO,MAAM,YAAY,CAAC,QAAQ,CAChC,KAAK,IAAI,EAAE;QACT,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,MAAM,CAAC,KAAK,CACV,UAAU,EACV,sBAAsB,IAAI,iBAAiB,OAAO,CAAC,MAAM,YAAY,CACtE,CAAC;QACF,OAAO,OAAO,CAAC;IACjB,CAAC,EACD;QACE,SAAS;QACT,OAAO,EAAE,UAAU;QACnB,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE;QACxB,SAAS,EAAE,gBAAgB,CAAC,UAAU;KACvC,CACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB;;;;;;;OAOG;IACH,KAAK,EAAE,uBAAuB;IAC9B;;;;;;OAMG;IACH,SAAS,EAAE,eAAe;CAC3B,CAAC"}

package/dist/utils/parsing/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Barrel file for parsing utility modules.
+ * This file re-exports utilities related to parsing various data formats,
+ * such as JSON and dates.
+ * @module src/utils/parsing
+ */
+export * from "./dateParser.js";
+export * from "./jsonParser.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/parsing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/parsing/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/utils/parsing/index.js

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Barrel file for parsing utility modules.
+ * This file re-exports utilities related to parsing various data formats,
+ * such as JSON and dates.
+ * @module src/utils/parsing
+ */
+export * from "./dateParser.js";
+export * from "./jsonParser.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/parsing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/parsing/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/utils/parsing/jsonParser.d.ts

@@ -0,0 +1,83 @@
+import { RequestContext } from "../index.js";
+/**
+ * Enum mirroring `partial-json`'s `Allow` constants. These specify
+ * what types of partial JSON structures are permissible during parsing.
+ * They can be combined using bitwise OR (e.g., `Allow.STR | Allow.OBJ`).
+ *
+ * The available properties are:
+ * - `STR`: Allow partial string.
+ * - `NUM`: Allow partial number.
+ * - `ARR`: Allow partial array.
+ * - `OBJ`: Allow partial object.
+ * - `NULL`: Allow partial null.
+ * - `BOOL`: Allow partial boolean.
+ * - `NAN`: Allow partial NaN. (Note: Standard JSON does not support NaN)
+ * - `INFINITY`: Allow partial Infinity. (Note: Standard JSON does not support Infinity)
+ * - `_INFINITY`: Allow partial -Infinity. (Note: Standard JSON does not support -Infinity)
+ * - `INF`: Allow both partial Infinity and -Infinity.
+ * - `SPECIAL`: Allow all special values (NaN, Infinity, -Infinity).
+ * - `ATOM`: Allow all atomic values (strings, numbers, booleans, null, special values).
+ * - `COLLECTION`: Allow all collection values (objects, arrays).
+ * - `ALL`: Allow all value types to be partial (default for `partial-json`'s parse).
+ * @see {@link https://github.com/promplate/partial-json-parser-js} for more details.
+ */
+export declare const Allow: {
+    STR: number;
+    NUM: number;
+    ARR: number;
+    OBJ: number;
+    NULL: number;
+    BOOL: number;
+    NAN: number;
+    INFINITY: number;
+    _INFINITY: number;
+    INF: number;
+    SPECIAL: number;
+    ATOM: number;
+    COLLECTION: number;
+    ALL: number;
+};
+/**
+ * Utility class for parsing potentially partial JSON strings.
+ * Wraps the 'partial-json' library for robust JSON parsing, handling
+ * incomplete structures and optional <think> blocks from LLMs.
+ */
+export declare class JsonParser {
+    /**
+     * Parses a JSON string, which may be partial or prefixed with a <think> block.
+     * If a <think> block is present, its content is logged, and parsing proceeds on the
+     * remainder. Uses 'partial-json' to handle incomplete JSON.
+     *
+     * @template T The expected type of the parsed JSON object. Defaults to `any`.
+     * @param jsonString - The JSON string to parse.
+     * @param allowPartial - Bitwise OR combination of `Allow` constants specifying permissible
+     *   partial JSON types. Defaults to `Allow.ALL`.
+     * @param context - Optional `RequestContext` for logging and error correlation.
+     * @returns The parsed JavaScript value.
+     * @throws {McpError} If the string is empty after processing or if `partial-json` fails.
+     */
+    parse<T = unknown>(jsonString: string, allowPartial?: number, context?: RequestContext): T;
+}
+/**
+ * Singleton instance of the `JsonParser`.
+ * Use this instance to parse JSON strings, with support for partial JSON and <think> blocks.
+ * @example
+ * ```typescript
+ * import { jsonParser, Allow, requestContextService } from './utils';
+ * const context = requestContextService.createRequestContext({ operation: 'TestJsonParsing' });
+ *
+ * const fullJson = '{"key": "value"}';
+ * const parsedFull = jsonParser.parse(fullJson, Allow.ALL, context);
+ * console.log(parsedFull); // Output: { key: 'value' }
+ *
+ * const partialObject = '<think>This is a thought.</think>{"key": "value", "arr": [1,';
+ * try {
+ *   const parsedPartial = jsonParser.parse(partialObject, undefined, context);
+ *   console.log(parsedPartial);
+ * } catch (e) {
+ *   console.error("Parsing partial object failed:", e);
+ * }
+ * ```
+ */
+export declare const jsonParser: JsonParser;
+//# sourceMappingURL=jsonParser.d.ts.map

package/dist/utils/parsing/jsonParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonParser.d.ts","sourceRoot":"","sources":["../../../src/utils/parsing/jsonParser.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,cAAc,EAEf,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;CAAmB,CAAC;AAStC;;;;GAIG;AACH,qBAAa,UAAU;IACrB;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,CAAC,GAAG,OAAO,EACf,UAAU,EAAE,MAAM,EAClB,YAAY,GAAE,MAAkB,EAChC,OAAO,CAAC,EAAE,cAAc,GACvB,CAAC;CAoEL;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,UAAU,YAAmB,CAAC"}

package/dist/utils/parsing/jsonParser.js

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview Provides a utility class for parsing potentially partial JSON strings.
+ * It wraps the 'partial-json' npm library and includes functionality to handle
+ * optional <think>...</think> blocks often found at the beginning of LLM outputs.
+ * @module src/utils/parsing/jsonParser
+ */
+import { parse as parsePartialJson, Allow as PartialJsonAllow, } from "partial-json";
+import { JsonRpcErrorCode, McpError } from "../../types-global/errors.js";
+import { logger, requestContextService, } from "../index.js";
+/**
+ * Enum mirroring `partial-json`'s `Allow` constants. These specify
+ * what types of partial JSON structures are permissible during parsing.
+ * They can be combined using bitwise OR (e.g., `Allow.STR | Allow.OBJ`).
+ *
+ * The available properties are:
+ * - `STR`: Allow partial string.
+ * - `NUM`: Allow partial number.
+ * - `ARR`: Allow partial array.
+ * - `OBJ`: Allow partial object.
+ * - `NULL`: Allow partial null.
+ * - `BOOL`: Allow partial boolean.
+ * - `NAN`: Allow partial NaN. (Note: Standard JSON does not support NaN)
+ * - `INFINITY`: Allow partial Infinity. (Note: Standard JSON does not support Infinity)
+ * - `_INFINITY`: Allow partial -Infinity. (Note: Standard JSON does not support -Infinity)
+ * - `INF`: Allow both partial Infinity and -Infinity.
+ * - `SPECIAL`: Allow all special values (NaN, Infinity, -Infinity).
+ * - `ATOM`: Allow all atomic values (strings, numbers, booleans, null, special values).
+ * - `COLLECTION`: Allow all collection values (objects, arrays).
+ * - `ALL`: Allow all value types to be partial (default for `partial-json`'s parse).
+ * @see {@link https://github.com/promplate/partial-json-parser-js} for more details.
+ */
+export const Allow = PartialJsonAllow;
+/**
+ * Regular expression to find a <think> block at the start of a string.
+ * Captures content within <think>...</think> (Group 1) and the rest of the string (Group 2).
+ * @private
+ */
+const thinkBlockRegex = /^<think>([\s\S]*?)<\/think>\s*([\s\S]*)$/;
+/**
+ * Utility class for parsing potentially partial JSON strings.
+ * Wraps the 'partial-json' library for robust JSON parsing, handling
+ * incomplete structures and optional <think> blocks from LLMs.
+ */
+export class JsonParser {
+    /**
+     * Parses a JSON string, which may be partial or prefixed with a <think> block.
+     * If a <think> block is present, its content is logged, and parsing proceeds on the
+     * remainder. Uses 'partial-json' to handle incomplete JSON.
+     *
+     * @template T The expected type of the parsed JSON object. Defaults to `any`.
+     * @param jsonString - The JSON string to parse.
+     * @param allowPartial - Bitwise OR combination of `Allow` constants specifying permissible
+     *   partial JSON types. Defaults to `Allow.ALL`.
+     * @param context - Optional `RequestContext` for logging and error correlation.
+     * @returns The parsed JavaScript value.
+     * @throws {McpError} If the string is empty after processing or if `partial-json` fails.
+     */
+    parse(jsonString, allowPartial = Allow.ALL, context) {
+        let stringToParse = jsonString;
+        const match = jsonString.match(thinkBlockRegex);
+        if (match) {
+            const thinkContent = match[1]?.trim() ?? "";
+            const restOfString = match[2] ?? "";
+            const logContext = context ||
+                requestContextService.createRequestContext({
+                    operation: "JsonParser.thinkBlock",
+                });
+            if (thinkContent) {
+                logger.debug({
+                    ...logContext,
+                    thinkContent,
+                }, "LLM <think> block detected and logged.");
+            }
+            else {
+                logger.debug(logContext, "Empty LLM <think> block detected.");
+            }
+            stringToParse = restOfString;
+        }
+        stringToParse = stringToParse.trim();
+        if (!stringToParse) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, "JSON string is empty after removing <think> block and trimming.", context);
+        }
+        try {
+            return parsePartialJson(stringToParse, allowPartial);
+        }
+        catch (e) {
+            const error = e;
+            const errorLogContext = context ||
+                requestContextService.createRequestContext({
+                    operation: "JsonParser.parseError",
+                });
+            logger.error({
+                ...errorLogContext,
+                errorDetails: error.message,
+                contentAttempted: stringToParse.substring(0, 200),
+            }, "Failed to parse JSON content.");
+            throw new McpError(JsonRpcErrorCode.ValidationError, `Failed to parse JSON: ${error.message}`, {
+                ...context,
+                originalContentSample: stringToParse.substring(0, 200) +
+                    (stringToParse.length > 200 ? "..." : ""),
+                rawError: error instanceof Error ? error.stack : String(error),
+            });
+        }
+    }
+}
+/**
+ * Singleton instance of the `JsonParser`.
+ * Use this instance to parse JSON strings, with support for partial JSON and <think> blocks.
+ * @example
+ * ```typescript
+ * import { jsonParser, Allow, requestContextService } from './utils';
+ * const context = requestContextService.createRequestContext({ operation: 'TestJsonParsing' });
+ *
+ * const fullJson = '{"key": "value"}';
+ * const parsedFull = jsonParser.parse(fullJson, Allow.ALL, context);
+ * console.log(parsedFull); // Output: { key: 'value' }
+ *
+ * const partialObject = '<think>This is a thought.</think>{"key": "value", "arr": [1,';
+ * try {
+ *   const parsedPartial = jsonParser.parse(partialObject, undefined, context);
+ *   console.log(parsedPartial);
+ * } catch (e) {
+ *   console.error("Parsing partial object failed:", e);
+ * }
+ * ```
+ */
+export const jsonParser = new JsonParser();
+//# sourceMappingURL=jsonParser.js.map

package/dist/utils/parsing/jsonParser.js.map

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

package/dist/utils/scheduling/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for the scheduling module.
+ * Exports the singleton schedulerService for application-wide use.
+ * @module src/utils/scheduling
+ */
+export * from "./scheduler.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/scheduling/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/scheduling/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAC"}

package/dist/utils/scheduling/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Barrel file for the scheduling module.
+ * Exports the singleton schedulerService for application-wide use.
+ * @module src/utils/scheduling
+ */
+export * from "./scheduler.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/scheduling/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/scheduling/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAC"}

package/dist/utils/scheduling/scheduler.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Provides a singleton service for scheduling and managing cron jobs.
+ * This service wraps the 'node-cron' library to offer a unified interface for
+ * defining, starting, stopping, and listing recurring tasks within the application.
+ * @module src/utils/scheduling/scheduler
+ */
+import { ScheduledTask } from "node-cron";
+import { RequestContext } from "../internal/index.js";
+/**
+ * Represents a scheduled job managed by the SchedulerService.
+ */
+export interface Job {
+    /** A unique identifier for the job. */
+    id: string;
+    /** The cron pattern defining the job's schedule. */
+    schedule: string;
+    /** A description of what the job does. */
+    description: string;
+    /** The underlying 'node-cron' task instance. */
+    task: ScheduledTask;
+    /** Indicates whether the job is currently running. */
+    isRunning: boolean;
+}
+/**
+ * A singleton service for scheduling and managing cron jobs.
+ */
+export declare class SchedulerService {
+    private static instance;
+    private jobs;
+    /** @private */
+    private constructor();
+    /**
+     * Gets the singleton instance of the SchedulerService.
+     * @returns The singleton SchedulerService instance.
+     */
+    static getInstance(): SchedulerService;
+    /**
+     * Schedules a new job.
+     *
+     * @param id - A unique identifier for the job.
+     * @param schedule - The cron pattern for the schedule (e.g., '* * * * *').
+     * @param taskFunction - The function to execute on schedule. It receives a RequestContext.
+     * @param description - A description of the job.
+     * @returns The newly created Job object.
+     */
+    schedule(id: string, schedule: string, taskFunction: (context: RequestContext) => void | Promise<void>, description: string): Job;
+    /**
+     * Starts a scheduled job.
+     * @param id - The ID of the job to start.
+     */
+    start(id: string): void;
+    /**
+     * Stops a scheduled job.
+     * @param id - The ID of the job to stop.
+     */
+    stop(id: string): void;
+    /**
+     * Removes a job from the scheduler. The job is stopped before being removed.
+     * @param id - The ID of the job to remove.
+     */
+    remove(id: string): void;
+    /**
+     * Gets a list of all scheduled jobs.
+     * @returns An array of all Job objects.
+     */
+    listJobs(): Job[];
+}
+/**
+ * The singleton instance of the SchedulerService.
+ * Use this instance for all job scheduling operations.
+ */
+export declare const schedulerService: SchedulerService;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/utils/scheduling/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../src/utils/scheduling/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAa,EAAE,aAAa,EAAc,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAU,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGnE;;GAEG;AACH,MAAM,WAAW,GAAG;IAClB,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,IAAI,EAAE,aAAa,CAAC;IACpB,sDAAsD;IACtD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmB;IAC1C,OAAO,CAAC,IAAI,CAA+B;IAE3C,eAAe;IACf,OAAO;IAUP;;;OAGG;WACW,WAAW,IAAI,gBAAgB;IAO7C;;;;;;;;OAQG;IACI,QAAQ,CACb,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,EAC/D,WAAW,EAAE,MAAM,GAClB,GAAG;IAqEN;;;OAGG;IACI,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAe9B;;;OAGG;IACI,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAe7B;;;OAGG;IACI,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAgB/B;;;OAGG;IACI,QAAQ,IAAI,GAAG,EAAE;CAGzB;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,kBAAiC,CAAC"}