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

package/dist/utils/pagination/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../src/utils/pagination/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAqCpD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,KAAsB;IACjD,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACzC,yEAAyE;QACzE,MAAM,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC;aACtC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;aACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;aACnB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACtB,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,IAAI,QAAQ,CAAC,gBAAgB,CAAC,aAAa,EAAE,oCAAoC,EAAE;YACvF,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,OAAuB;IAClE,IAAI,CAAC;QACH,wEAAwE;QACxE,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACpE,MAAM,UAAU,GAAG,cAAc,CAAC,cAAc,CAAC,CAAC;QAClD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAoB,CAAC;QAExD,2BAA2B;QAC3B,IACE,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;YAChC,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;YAC/B,KAAK,CAAC,MAAM,GAAG,CAAC;YAChB,KAAK,CAAC,KAAK,IAAI,CAAC,EAChB,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACxD,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,CAAC,OAAO,CAAC,oCAAoC,EAAE;YACnD,GAAG,OAAO;YACV,MAAM;YACN,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC,CAAC;QACH,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,aAAa,EAC9B,+FAA+F,EAC/F,EAAE,MAAM,EAAE,CACX,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,MAG7B;IACC,OAAO,MAAM,EAAE,MAAM,IAAI,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAU,EACV,SAA6B,EAC7B,eAAuB,EACvB,WAAmB,EACnB,OAAuB;IAEvB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,KAAK,GAAG,eAAe,CAAC;IAE5B,4BAA4B;IAC5B,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,KAAK,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC/C,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QACtB,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,wBAAwB;IACtE,CAAC;IAED,kBAAkB;IAClB,IAAI,MAAM,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QAC3B,OAAO;YACL,KAAK,EAAE,EAAE;YACT,UAAU,EAAE,KAAK,CAAC,MAAM;SACzB,CAAC;IACJ,CAAC;IAED,eAAe;IACf,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;IAE9C,kEAAkE;IAClE,MAAM,MAAM,GAAuB;QACjC,KAAK,EAAE,SAAS;QAChB,UAAU,EAAE,KAAK,CAAC,MAAM;KACzB,CAAC;IAEF,4CAA4C;IAC5C,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,CAAC,UAAU,GAAG,YAAY,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,uCAAuC;IACvC,iBAAiB,EAAE,EAAE;IACrB,qCAAqC;IACrC,aAAa,EAAE,IAAI;IACnB,qCAAqC;IACrC,aAAa,EAAE,CAAC;CACR,CAAC"}

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

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview Provides a utility class for parsing CSV strings.
+ * Wraps the `papaparse` peer dependency (lazy-loaded on first use) and strips
+ * optional `<think>...</think>` blocks that LLMs sometimes prepend to structured
+ * output before parsing. Handles CJS/ESM interop for the `papaparse` module.
+ *
+ * Peer dependency: `papaparse` — install with `bun add papaparse`.
+ * @module src/utils/parsing/csvParser
+ */
+import type Papa from 'papaparse';
+import { type RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Utility class for parsing CSV strings.
+ *
+ * Lazily loads `papaparse` on first use (peer dependency — install with `bun add papaparse`).
+ * Handles CJS/ESM interop for the `papaparse` module automatically. Handles optional
+ * `<think>...</think>` blocks that some LLMs prepend to structured output; the block's
+ * content is logged at debug level and stripped before parsing.
+ */
+export declare class CsvParser {
+    /**
+     * Parses a CSV string into a `Papa.ParseResult`.
+     *
+     * This method is async because `papaparse` is loaded lazily on first call.
+     * If the input begins with a `<think>...</think>` block, that block is stripped
+     * and its content logged before parsing the remainder. Parse options (delimiter,
+     * headers, etc.) are forwarded directly to `Papa.parse()`.
+     *
+     * If `papaparse` reports any parse errors in `result.errors`, an `McpError` is thrown
+     * with all error messages joined and the raw `errors` array attached as context.
+     *
+     * @template T - The type of each parsed row. Defaults to `unknown`.
+     * @param csvString - The CSV string to parse. May be prefixed with a `<think>` block.
+     * @param options - Optional `Papa.ParseConfig` forwarded directly to `Papa.parse()`.
+     *   Common options: `header` (boolean), `delimiter` (string), `dynamicTyping` (boolean).
+     * @param context - Optional request context for correlated logging and error metadata.
+     * @returns A promise resolving to `Papa.ParseResult<T>` containing `data`, `errors`, and `meta`.
+     * @throws {McpError} With code `ConfigurationError` if `papaparse` is not installed.
+     * @throws {McpError} With code `ValidationError` if the string is empty after stripping
+     *   the `<think>` block, or if `papaparse` reports parse errors.
+     * @example
+     * ```typescript
+     * import { csvParser } from '../../utils/parsing/csvParser.js';
+     *
+     * // Parse with header row — rows typed as objects
+     * const result = await csvParser.parse<{ name: string; age: string }>(
+     *   'name,age\nAlice,30\nBob,25',
+     *   { header: true },
+     * );
+     * console.log(result.data[0].name); // 'Alice'
+     *
+     * // LLM output with a <think> preamble
+     * const fromLlm = await csvParser.parse('<think>reasoning</think>\na,b\n1,2', { header: true });
+     * console.log(fromLlm.data[0]); // { a: '1', b: '2' }
+     * ```
+     */
+    parse<T = unknown>(csvString: string, options?: Papa.ParseConfig, context?: RequestContext): Promise<Papa.ParseResult<T>>;
+}
+/**
+ * Singleton instance of {@link CsvParser}.
+ *
+ * Prefer this over constructing a new `CsvParser` directly. Lazily loads `papaparse`
+ * on first call, so there is no startup cost if CSV parsing is never used.
+ *
+ * @example
+ * ```typescript
+ * import { csvParser } from '../../utils/parsing/csvParser.js';
+ *
+ * // Parse with header row
+ * const result = await csvParser.parse<{ a: string; b: string }>('a,b\n1,2', { header: true });
+ * console.log(result.data[0]); // { a: '1', b: '2' }
+ *
+ * // With request context for correlated logging
+ * import { requestContextService } from '../../utils/internal/requestContext.js';
+ * const ctx = requestContextService.createRequestContext({ operation: 'importData' });
+ * const imported = await csvParser.parse(rawCsv, { header: true, dynamicTyping: true }, ctx);
+ *
+ * // Strips LLM <think> preamble automatically
+ * const fromLlm = await csvParser.parse('<think>let me think</think>\na,b\n1,2', { header: true });
+ * console.log(fromLlm.data[0]); // { a: '1', b: '2' }
+ * ```
+ */
+export declare const csvParser: CsvParser;
+//# sourceMappingURL=csvParser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"csvParser.d.ts","sourceRoot":"","sources":["../../../src/utils/parsing/csvParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAIlC,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,oCAAoC,CAAC;AAkBhG;;;;;;;GAOG;AACH,qBAAa,SAAS;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,IAAI,CAAC,WAAW,EAC1B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;CA+DhC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,SAAS,WAAkB,CAAC"}

package/dist/utils/parsing/csvParser.js

@@ -0,0 +1,132 @@
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+import { logger } from '../../utils/internal/logger.js';
+import { requestContextService } from '../../utils/internal/requestContext.js';
+import { thinkBlockRegex } from './thinkBlock.js';
+let _papa;
+async function getPapa() {
+    if (!_papa) {
+        const mod = await import('papaparse').catch(() => {
+            throw new McpError(JsonRpcErrorCode.ConfigurationError, 'Install "papaparse" to use CSV parsing: bun add papaparse');
+        });
+        // Handle CJS/ESM interop — papaparse uses `export =`
+        _papa = ('default' in mod ? mod.default : mod);
+    }
+    return _papa;
+}
+/**
+ * Utility class for parsing CSV strings.
+ *
+ * Lazily loads `papaparse` on first use (peer dependency — install with `bun add papaparse`).
+ * Handles CJS/ESM interop for the `papaparse` module automatically. Handles optional
+ * `<think>...</think>` blocks that some LLMs prepend to structured output; the block's
+ * content is logged at debug level and stripped before parsing.
+ */
+export class CsvParser {
+    /**
+     * Parses a CSV string into a `Papa.ParseResult`.
+     *
+     * This method is async because `papaparse` is loaded lazily on first call.
+     * If the input begins with a `<think>...</think>` block, that block is stripped
+     * and its content logged before parsing the remainder. Parse options (delimiter,
+     * headers, etc.) are forwarded directly to `Papa.parse()`.
+     *
+     * If `papaparse` reports any parse errors in `result.errors`, an `McpError` is thrown
+     * with all error messages joined and the raw `errors` array attached as context.
+     *
+     * @template T - The type of each parsed row. Defaults to `unknown`.
+     * @param csvString - The CSV string to parse. May be prefixed with a `<think>` block.
+     * @param options - Optional `Papa.ParseConfig` forwarded directly to `Papa.parse()`.
+     *   Common options: `header` (boolean), `delimiter` (string), `dynamicTyping` (boolean).
+     * @param context - Optional request context for correlated logging and error metadata.
+     * @returns A promise resolving to `Papa.ParseResult<T>` containing `data`, `errors`, and `meta`.
+     * @throws {McpError} With code `ConfigurationError` if `papaparse` is not installed.
+     * @throws {McpError} With code `ValidationError` if the string is empty after stripping
+     *   the `<think>` block, or if `papaparse` reports parse errors.
+     * @example
+     * ```typescript
+     * import { csvParser } from '../../utils/parsing/csvParser.js';
+     *
+     * // Parse with header row — rows typed as objects
+     * const result = await csvParser.parse<{ name: string; age: string }>(
+     *   'name,age\nAlice,30\nBob,25',
+     *   { header: true },
+     * );
+     * console.log(result.data[0].name); // 'Alice'
+     *
+     * // LLM output with a <think> preamble
+     * const fromLlm = await csvParser.parse('<think>reasoning</think>\na,b\n1,2', { header: true });
+     * console.log(fromLlm.data[0]); // { a: '1', b: '2' }
+     * ```
+     */
+    async parse(csvString, options, context) {
+        let stringToParse = csvString;
+        const match = csvString.match(thinkBlockRegex);
+        if (match) {
+            const thinkContent = match[1]?.trim() ?? '';
+            const restOfString = match[2] ?? '';
+            const logContext = context ||
+                requestContextService.createRequestContext({
+                    operation: 'CsvParser.thinkBlock',
+                });
+            if (thinkContent) {
+                logger.debug('LLM <think> block detected and logged.', {
+                    ...logContext,
+                    thinkContent,
+                });
+            }
+            else {
+                logger.debug('Empty LLM <think> block detected.', logContext);
+            }
+            stringToParse = restOfString;
+        }
+        stringToParse = stringToParse.trim();
+        if (!stringToParse) {
+            throw new McpError(JsonRpcErrorCode.ValidationError, 'CSV string is empty after removing <think> block and trimming.', context);
+        }
+        const papa = await getPapa();
+        const result = papa.parse(stringToParse, options);
+        if (result.errors.length > 0) {
+            const errorLogContext = context ||
+                requestContextService.createRequestContext({
+                    operation: 'CsvParser.parseError',
+                });
+            logger.error('Failed to parse CSV content.', {
+                ...errorLogContext,
+                errors: result.errors,
+                contentAttempted: stringToParse.substring(0, 200),
+            });
+            throw new McpError(JsonRpcErrorCode.ValidationError, `Failed to parse CSV: ${result.errors.map((e) => e.message).join(', ')}`, {
+                ...context,
+                errors: result.errors,
+                originalContentSample: stringToParse.substring(0, 200) + (stringToParse.length > 200 ? '...' : ''),
+            });
+        }
+        return result;
+    }
+}
+/**
+ * Singleton instance of {@link CsvParser}.
+ *
+ * Prefer this over constructing a new `CsvParser` directly. Lazily loads `papaparse`
+ * on first call, so there is no startup cost if CSV parsing is never used.
+ *
+ * @example
+ * ```typescript
+ * import { csvParser } from '../../utils/parsing/csvParser.js';
+ *
+ * // Parse with header row
+ * const result = await csvParser.parse<{ a: string; b: string }>('a,b\n1,2', { header: true });
+ * console.log(result.data[0]); // { a: '1', b: '2' }
+ *
+ * // With request context for correlated logging
+ * import { requestContextService } from '../../utils/internal/requestContext.js';
+ * const ctx = requestContextService.createRequestContext({ operation: 'importData' });
+ * const imported = await csvParser.parse(rawCsv, { header: true, dynamicTyping: true }, ctx);
+ *
+ * // Strips LLM <think> preamble automatically
+ * const fromLlm = await csvParser.parse('<think>let me think</think>\na,b\n1,2', { header: true });
+ * console.log(fromLlm.data[0]); // { a: '1', b: '2' }
+ * ```
+ */
+export const csvParser = new CsvParser();
+//# sourceMappingURL=csvParser.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"csvParser.js","sourceRoot":"","sources":["../../../src/utils/parsing/csvParser.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAuB,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChG,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,IAAI,KAA8B,CAAC;AACnC,KAAK,UAAU,OAAO;IACpB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YAC/C,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,kBAAkB,EACnC,2DAA2D,CAC5D,CAAC;QACJ,CAAC,CAAC,CAAC;QACH,qDAAqD;QACrD,KAAK,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,CAAC,CAAE,GAAG,CAAC,OAAuB,CAAC,CAAC,CAAC,GAAG,CAAgB,CAAC;IACjF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,SAAS;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,KAAK,CAAC,KAAK,CACT,SAAiB,EACjB,OAA0B,EAC1B,OAAwB;QAExB,IAAI,aAAa,GAAG,SAAS,CAAC;QAC9B,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;QAE/C,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YAC5C,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAEpC,MAAM,UAAU,GACd,OAAO;gBACP,qBAAqB,CAAC,oBAAoB,CAAC;oBACzC,SAAS,EAAE,sBAAsB;iBAClC,CAAC,CAAC;YACL,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,CAAC,KAAK,CAAC,wCAAwC,EAAE;oBACrD,GAAG,UAAU;oBACb,YAAY;iBACb,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,KAAK,CAAC,mCAAmC,EAAE,UAAU,CAAC,CAAC;YAChE,CAAC;YACD,aAAa,GAAG,YAAY,CAAC;QAC/B,CAAC;QAED,aAAa,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC;QAErC,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,gEAAgE,EAChE,OAAO,CACR,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,OAAO,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAI,aAAa,EAAE,OAAO,CAAC,CAAC;QAErD,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,eAAe,GACnB,OAAO;gBACP,qBAAqB,CAAC,oBAAoB,CAAC;oBACzC,SAAS,EAAE,sBAAsB;iBAClC,CAAC,CAAC;YACL,MAAM,CAAC,KAAK,CAAC,8BAA8B,EAAE;gBAC3C,GAAG,eAAe;gBAClB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,gBAAgB,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC;aAClD,CAAC,CAAC;YAEH,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,wBAAwB,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACxE;gBACE,GAAG,OAAO;gBACV,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,qBAAqB,EACnB,aAAa,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9E,CACF,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,SAAS,EAAE,CAAC"}

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

@@ -0,0 +1,103 @@
+/**
+ * @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 type * as chrono from 'chrono-node';
+import type { RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Parses a natural language date string into a JavaScript `Date` object.
+ *
+ * Uses `chrono-node`'s `parseDate` with `forwardDate: true` so ambiguous dates
+ * (e.g. "next Friday") resolve to the nearest future occurrence. Returns `null`
+ * if no date can be extracted from the text.
+ *
+ * Async due to lazy loading of the `chrono-node` peer dependency
+ * (`bun add chrono-node`).
+ *
+ * @param text - The natural language date string to parse (e.g. `"next Friday at 3pm"`).
+ * @param context - `RequestContext` for correlated logging and error metadata.
+ * @param refDate - Reference date for relative expressions. Defaults to the current date/time.
+ * @returns A `Date` object if a date was found, or `null` if parsing yields no result.
+ * @throws {McpError} With `ConfigurationError` if `chrono-node` is not installed.
+ * @throws {McpError} With `ParseError` if an unexpected error occurs during parsing.
+ */
+export declare function parseDateString(text: string, context: RequestContext, refDate?: Date): Promise<Date | null>;
+/**
+ * Parses a natural language date string and returns detailed `chrono-node` results.
+ *
+ * Unlike `parseDateString`, this function returns the full `ParsedResult[]` from
+ * `chrono-node`, which includes each matched text span, its character index in the
+ * input, and parsed date/time components (start, optional end). Useful for
+ * multi-date strings or when the original matched text is needed.
+ *
+ * Uses `chrono-node`'s `parse` with `forwardDate: true`. Returns an empty array
+ * if no dates are found.
+ *
+ * Async due to lazy loading of the `chrono-node` peer dependency
+ * (`bun add chrono-node`).
+ *
+ * @param text - The natural language date string to parse.
+ * @param context - `RequestContext` for correlated logging and error metadata.
+ * @param refDate - Reference date for relative expressions. Defaults to the current date/time.
+ * @returns An array of `chrono.ParsedResult` objects — one per date expression found.
+ *   Empty array if no dates are present in the text.
+ * @throws {McpError} With `ConfigurationError` if `chrono-node` is not installed.
+ * @throws {McpError} With `ParseError` if an unexpected error occurs during parsing.
+ */
+export declare function parseDateStringDetailed(text: string, context: RequestContext, refDate?: Date): Promise<chrono.ParsedResult[]>;
+/**
+ * Singleton object providing natural language date parsing via `chrono-node`.
+ *
+ * Both methods are async due to lazy loading of the `chrono-node` peer dependency
+ * (`bun add chrono-node`). Use `parseDate` for a simple `Date | null` result and
+ * `parse` when you need the full matched-text details.
+ *
+ * @example
+ * ```typescript
+ * import { dateParser } from '../../utils/parsing/dateParser.js';
+ * import { requestContextService } from '../../utils/internal/requestContext.js';
+ *
+ * const ctx = requestContextService.createRequestContext({ operation: 'myOp' });
+ *
+ * // Simple Date result
+ * const date = await dateParser.parseDate('next Friday at 3pm', ctx);
+ * if (date) console.log(date.toISOString());
+ *
+ * // Detailed results — useful for multi-date strings
+ * const results = await dateParser.parse('Meeting on 2024-12-25 and another one tomorrow', ctx);
+ * for (const r of results) {
+ *   console.log(r.text, r.start.date());
+ * }
+ * ```
+ */
+export declare const dateParser: {
+    /**
+     * Parses a natural language date string and returns the full `chrono-node`
+     * `ParsedResult[]`, including matched text spans and parsed components.
+     *
+     * Async due to lazy loading of `chrono-node` (`bun add chrono-node`).
+     *
+     * @param text - The natural language date string to parse.
+     * @param context - `RequestContext` for correlated logging and error metadata.
+     * @param refDate - Reference date for relative expressions. Defaults to now.
+     * @returns An array of `chrono.ParsedResult` objects; empty if no dates found.
+     * @throws {McpError} With `ConfigurationError` if `chrono-node` is not installed.
+     * @throws {McpError} With `ParseError` if an unexpected error occurs.
+     */
+    parse: typeof parseDateStringDetailed;
+    /**
+     * Parses a natural language date string into a single JavaScript `Date` object.
+     *
+     * Async due to lazy loading of `chrono-node` (`bun add chrono-node`).
+     *
+     * @param text - The natural language date string to parse.
+     * @param context - `RequestContext` for correlated logging and error metadata.
+     * @param refDate - Reference date for relative expressions. Defaults to now.
+     * @returns A `Date` if a date expression was found, or `null` if none was recognized.
+     * @throws {McpError} With `ConfigurationError` if `chrono-node` is not installed.
+     * @throws {McpError} With `ParseError` if an unexpected error occurs.
+     */
+    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,KAAK,MAAM,MAAM,aAAa,CAAC;AAK3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAazE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,IAAI,GACb,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAwBtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,IAAI,GACb,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAsBhC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,UAAU;IACrB;;;;;;;;;;;;OAYG;;IAEH;;;;;;;;;;;OAWG;;CAEJ,CAAC"}

package/dist/utils/parsing/dateParser.js

@@ -0,0 +1,142 @@
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+import { ErrorHandler } from '../../utils/internal/error-handler/errorHandler.js';
+import { logger } from '../../utils/internal/logger.js';
+let _chrono;
+async function getChrono() {
+    _chrono ??= await import('chrono-node').catch(() => {
+        throw new McpError(JsonRpcErrorCode.ConfigurationError, 'Install "chrono-node" to use date parsing: bun add chrono-node');
+    });
+    return _chrono;
+}
+/**
+ * Parses a natural language date string into a JavaScript `Date` object.
+ *
+ * Uses `chrono-node`'s `parseDate` with `forwardDate: true` so ambiguous dates
+ * (e.g. "next Friday") resolve to the nearest future occurrence. Returns `null`
+ * if no date can be extracted from the text.
+ *
+ * Async due to lazy loading of the `chrono-node` peer dependency
+ * (`bun add chrono-node`).
+ *
+ * @param text - The natural language date string to parse (e.g. `"next Friday at 3pm"`).
+ * @param context - `RequestContext` for correlated logging and error metadata.
+ * @param refDate - Reference date for relative expressions. Defaults to the current date/time.
+ * @returns A `Date` object if a date was found, or `null` if parsing yields no result.
+ * @throws {McpError} With `ConfigurationError` if `chrono-node` is not installed.
+ * @throws {McpError} With `ParseError` if an unexpected error occurs during parsing.
+ */
+export async function parseDateString(text, context, refDate) {
+    const operation = 'parseDateString';
+    const logContext = { ...context, operation, inputText: text, refDate };
+    logger.debug(`Attempting to parse date string: "${text}"`, logContext);
+    return await ErrorHandler.tryCatch(async () => {
+        const chronoMod = await getChrono();
+        const parsedDate = chronoMod.parseDate(text, refDate, { forwardDate: true });
+        if (parsedDate) {
+            logger.debug(`Successfully parsed "${text}" to ${parsedDate.toISOString()}`, logContext);
+            return parsedDate;
+        }
+        else {
+            logger.warning(`Failed to parse date string: "${text}"`, logContext);
+            return null;
+        }
+    }, {
+        operation,
+        context: logContext,
+        input: { text, refDate },
+        errorCode: JsonRpcErrorCode.ParseError,
+    });
+}
+/**
+ * Parses a natural language date string and returns detailed `chrono-node` results.
+ *
+ * Unlike `parseDateString`, this function returns the full `ParsedResult[]` from
+ * `chrono-node`, which includes each matched text span, its character index in the
+ * input, and parsed date/time components (start, optional end). Useful for
+ * multi-date strings or when the original matched text is needed.
+ *
+ * Uses `chrono-node`'s `parse` with `forwardDate: true`. Returns an empty array
+ * if no dates are found.
+ *
+ * Async due to lazy loading of the `chrono-node` peer dependency
+ * (`bun add chrono-node`).
+ *
+ * @param text - The natural language date string to parse.
+ * @param context - `RequestContext` for correlated logging and error metadata.
+ * @param refDate - Reference date for relative expressions. Defaults to the current date/time.
+ * @returns An array of `chrono.ParsedResult` objects — one per date expression found.
+ *   Empty array if no dates are present in the text.
+ * @throws {McpError} With `ConfigurationError` if `chrono-node` is not installed.
+ * @throws {McpError} With `ParseError` if an unexpected error occurs during parsing.
+ */
+export async function parseDateStringDetailed(text, context, refDate) {
+    const operation = 'parseDateStringDetailed';
+    const logContext = { ...context, operation, inputText: text, refDate };
+    logger.debug(`Attempting detailed parse of date string: "${text}"`, logContext);
+    return await ErrorHandler.tryCatch(async () => {
+        const chronoMod = await getChrono();
+        const results = chronoMod.parse(text, refDate, { forwardDate: true });
+        logger.debug(`Detailed parse of "${text}" resulted in ${results.length} result(s)`, logContext);
+        return results;
+    }, {
+        operation,
+        context: logContext,
+        input: { text, refDate },
+        errorCode: JsonRpcErrorCode.ParseError,
+    });
+}
+/**
+ * Singleton object providing natural language date parsing via `chrono-node`.
+ *
+ * Both methods are async due to lazy loading of the `chrono-node` peer dependency
+ * (`bun add chrono-node`). Use `parseDate` for a simple `Date | null` result and
+ * `parse` when you need the full matched-text details.
+ *
+ * @example
+ * ```typescript
+ * import { dateParser } from '../../utils/parsing/dateParser.js';
+ * import { requestContextService } from '../../utils/internal/requestContext.js';
+ *
+ * const ctx = requestContextService.createRequestContext({ operation: 'myOp' });
+ *
+ * // Simple Date result
+ * const date = await dateParser.parseDate('next Friday at 3pm', ctx);
+ * if (date) console.log(date.toISOString());
+ *
+ * // Detailed results — useful for multi-date strings
+ * const results = await dateParser.parse('Meeting on 2024-12-25 and another one tomorrow', ctx);
+ * for (const r of results) {
+ *   console.log(r.text, r.start.date());
+ * }
+ * ```
+ */
+export const dateParser = {
+    /**
+     * Parses a natural language date string and returns the full `chrono-node`
+     * `ParsedResult[]`, including matched text spans and parsed components.
+     *
+     * Async due to lazy loading of `chrono-node` (`bun add chrono-node`).
+     *
+     * @param text - The natural language date string to parse.
+     * @param context - `RequestContext` for correlated logging and error metadata.
+     * @param refDate - Reference date for relative expressions. Defaults to now.
+     * @returns An array of `chrono.ParsedResult` objects; empty if no dates found.
+     * @throws {McpError} With `ConfigurationError` if `chrono-node` is not installed.
+     * @throws {McpError} With `ParseError` if an unexpected error occurs.
+     */
+    parse: parseDateStringDetailed,
+    /**
+     * Parses a natural language date string into a single JavaScript `Date` object.
+     *
+     * Async due to lazy loading of `chrono-node` (`bun add chrono-node`).
+     *
+     * @param text - The natural language date string to parse.
+     * @param context - `RequestContext` for correlated logging and error metadata.
+     * @param refDate - Reference date for relative expressions. Defaults to now.
+     * @returns A `Date` if a date expression was found, or `null` if none was recognized.
+     * @throws {McpError} With `ConfigurationError` if `chrono-node` is not installed.
+     * @throws {McpError} With `ParseError` if an unexpected error occurs.
+     */
+    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":"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"}

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

@@ -0,0 +1,91 @@
+import { type RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Result of parsing markdown with frontmatter.
+ * @template T The expected type of the parsed frontmatter object.
+ */
+export interface FrontmatterResult<T = unknown> {
+    /**
+     * Remaining markdown content after frontmatter extraction.
+     * If no frontmatter exists, contains the original markdown.
+     */
+    content: string;
+    /**
+     * Parsed frontmatter object. Empty object if no frontmatter found.
+     */
+    frontmatter: T;
+    /**
+     * Indicates whether frontmatter was found and extracted.
+     */
+    hasFrontmatter: boolean;
+}
+/**
+ * Utility class for extracting and parsing YAML frontmatter from markdown documents.
+ * Supports Obsidian-style and Jekyll-style frontmatter (YAML between `---` delimiters).
+ * Delegates YAML parsing to {@link yamlParser}.
+ */
+export declare class FrontmatterParser {
+    /**
+     * Extracts and parses YAML frontmatter from a markdown string.
+     *
+     * Looks for a `---`-delimited block at the very start of the document. If
+     * found, the YAML inside is parsed via {@link yamlParser} and the remaining
+     * markdown is returned separately. An empty `---\n---` block is accepted and
+     * returns `frontmatter: {}` with `hasFrontmatter: true`. If no frontmatter
+     * block is present, the original string is returned unchanged.
+     *
+     * @template T - The expected shape of the parsed frontmatter object. Defaults to `unknown`.
+     * @param markdown - The markdown string that may contain a frontmatter block.
+     * @param context - Optional {@link RequestContext} used for correlated logging.
+     * @returns A {@link FrontmatterResult} with `frontmatter`, `content`, and `hasFrontmatter`.
+     * @throws {McpError} With code `ValidationError` if the YAML content is present but malformed.
+     * @example
+     * ```typescript
+     * import { frontmatterParser } from './frontmatterParser.js';
+     *
+     * const md = `---\ntitle: Hello\ntags: [a, b]\n---\n\n# Body`;
+     * const result = await frontmatterParser.parse<{ title: string; tags: string[] }>(md);
+     * // result.frontmatter → { title: 'Hello', tags: ['a', 'b'] }
+     * // result.content     → '\n# Body'
+     * // result.hasFrontmatter → true
+     * ```
+     */
+    parse<T = unknown>(markdown: string, context?: RequestContext): Promise<FrontmatterResult<T>>;
+}
+/**
+ * Singleton instance of {@link FrontmatterParser}.
+ *
+ * Use this shared instance to extract and parse YAML frontmatter from markdown
+ * documents rather than constructing a new parser per call.
+ *
+ * @example
+ * ```typescript
+ * import { frontmatterParser } from './frontmatterParser.js';
+ * import { requestContextService } from '../../utils/internal/requestContext.js';
+ *
+ * const context = requestContextService.createRequestContext({ operation: 'ParseObsidianNote' });
+ *
+ * // Markdown with frontmatter
+ * const markdown = `---
+ * title: My Note
+ * tags: [productivity, notes]
+ * date: 2025-01-15
+ * ---
+ *
+ * # Note Content
+ * This is the actual note.`;
+ *
+ * const result = await frontmatterParser.parse(markdown, context);
+ * console.log(result.frontmatter);    // { title: 'My Note', tags: [...], date: '2025-01-15' }
+ * console.log(result.content);        // '\n# Note Content\nThis is the actual note.'
+ * console.log(result.hasFrontmatter); // true
+ *
+ * // Markdown without frontmatter
+ * const plainMarkdown = '# Just Content';
+ * const result2 = await frontmatterParser.parse(plainMarkdown, context);
+ * console.log(result2.frontmatter);    // {}
+ * console.log(result2.content);        // '# Just Content'
+ * console.log(result2.hasFrontmatter); // false
+ * ```
+ */
+export declare const frontmatterParser: FrontmatterParser;
+//# sourceMappingURL=frontmatterParser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatterParser.d.ts","sourceRoot":"","sources":["../../../src/utils/parsing/frontmatterParser.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,oCAAoC,CAAC;AAYhG;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO;IAC5C;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,WAAW,EAAE,CAAC,CAAC;IACf;;OAEG;IACH,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EACrB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;CA+FjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,iBAAiB,mBAA0B,CAAC"}