tracelattice 1.2.5

package/dist/logger/NullLogger.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Null logger that discards all log messages.
+ *
+ * This logger implements the same interface as `StructuredLogger` but
+ * silently discards all log messages. It's useful as a default/fallback
+ * logger when logging is disabled or when no logger is provided.
+ *
+ * @module logger
+ */
+import type { LogLevel, Logger, LoggerOptions } from './StructuredLogger.js';
+/**
+ * Null logger that discards all log messages.
+ *
+ * This class provides a no-op implementation of the logger interface.
+ * All method calls are silent and have no effect, making it suitable
+ * for use as a default logger when logging is disabled or not needed.
+ *
+ * @remarks
+ * The `NullLogger` implements the same interface as `StructuredLogger`,
+ * making them interchangeable. Use `NullLogger` when:
+ * - You want to disable logging completely
+ * - You need a logger placeholder that can be swapped later
+ * - Testing components that don't need output
+ * - Reducing overhead in performance-critical sections
+ *
+ * @example
+ * ```typescript
+ * import { NullLogger } from './logger/index.js';
+ *
+ * // Create a null logger
+ * const logger = new NullLogger();
+ *
+ * // All log calls are silently discarded
+ * logger.debug('This will not appear');
+ * logger.info('Nor will this');
+ * logger.warn('Or this warning');
+ * logger.error('Or even this error');
+ *
+ * // Methods exist for compatibility but have no effect
+ * logger.setLevel('debug');
+ * const level = logger.getLevel(); // Returns 'error' (default)
+ * ```
+ */
+export declare class NullLogger implements Logger {
+    /**
+     * Current minimum log level.
+     *
+     * @remarks
+     * Since all messages are discarded, the level setting has no practical
+     * effect. This property exists only for interface compatibility.
+     * @private
+     */
+    private _level;
+    /**
+     * Creates a new NullLogger instance.
+     *
+     * @param options - Configuration options (ignored, but accepted for interface compatibility)
+     *
+     * @example
+     * ```typescript
+     * // Create a null logger
+     * const logger1 = new NullLogger();
+     *
+     * // With options (ignored)
+     * const logger2 = new NullLogger({
+     *   level: 'debug',
+     *   context: 'MyApp',
+     *   pretty: true
+     * });
+     * ```
+     */
+    constructor(options?: LoggerOptions);
+    /**
+     * Log a debug message (no-op).
+     *
+     * This method exists for interface compatibility but does nothing.
+     *
+     * @param _message - Ignored
+     * @param _meta - Ignored
+     */
+    debug(_message: string, _meta?: Record<string, unknown>): void;
+    /**
+     * Log an info message (no-op).
+     *
+     * This method exists for interface compatibility but does nothing.
+     *
+     * @param _message - Ignored
+     * @param _meta - Ignored
+     */
+    info(_message: string, _meta?: Record<string, unknown>): void;
+    /**
+     * Log a warning message (no-op).
+     *
+     * This method exists for interface compatibility but does nothing.
+     *
+     * @param _message - Ignored
+     * @param _meta - Ignored
+     */
+    warn(_message: string, _meta?: Record<string, unknown>): void;
+    /**
+     * Log an error message (no-op).
+     *
+     * This method exists for interface compatibility but does nothing.
+     *
+     * @param _message - Ignored
+     * @param _meta - Ignored
+     */
+    error(_message: string, _meta?: Record<string, unknown>): void;
+    /**
+     * Sets the minimum log level (no-op).
+     *
+     * This method exists for interface compatibility but has no effect
+     * since all messages are discarded anyway.
+     *
+     * @param level - The new minimum log level (ignored)
+     *
+     * @example
+     * ```typescript
+     * logger.setLevel('debug');  // No effect
+     * ```
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Gets the current minimum log level.
+     *
+     * @returns The current log level (stored value, unused)
+     *
+     * @example
+     * ```typescript
+     * const currentLevel = logger.getLevel();
+     * console.log(`Current level: ${currentLevel}`); // 'error' by default
+     * ```
+     */
+    getLevel(): LogLevel;
+    /**
+     * Creates a child null logger (returns a new NullLogger).
+     *
+     * This method exists for interface compatibility. It returns a new
+     * `NullLogger` instance (not a child with extended context) since
+     * context tracking is not applicable for a no-op logger.
+     *
+     * @param _context - Additional context (ignored)
+     * @returns A new NullLogger instance
+     *
+     * @example
+     * ```typescript
+     * const nullLogger = new NullLogger();
+     * const childLogger = nullLogger.createChild('ChildModule');
+     * // childLogger is also a NullLogger
+     * ```
+     */
+    createChild(_context: string): NullLogger;
+}
+//# sourceMappingURL=NullLogger.d.ts.map

package/dist/logger/NullLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NullLogger.d.ts","sourceRoot":"","sources":["../../src/logger/NullLogger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,UAAW,YAAW,MAAM;IACxC;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAW;IAEzB;;;;;;;;;;;;;;;;;OAiBG;gBACS,OAAO,GAAE,aAAkB;IAIvC;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAE9D;;;;;;;OAOG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAE7D;;;;;;;OAOG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAE7D;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAE9D;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B;;;;;;;;;;OAUG;IACH,QAAQ,IAAI,QAAQ;IAIpB;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU;CAGzC"}

package/dist/logger/NullLogger.js

@@ -0,0 +1,24 @@
+class NullLogger {
+    _level;
+    constructor(options = {}){
+        this._level = options.level ?? 'error';
+    }
+    debug(_message, _meta) {}
+    info(_message, _meta) {}
+    warn(_message, _meta) {}
+    error(_message, _meta) {}
+    setLevel(level) {
+        this._level = level;
+    }
+    getLevel() {
+        return this._level;
+    }
+    createChild(_context) {
+        return new NullLogger({
+            level: this._level
+        });
+    }
+}
+export { NullLogger };
+
+//# sourceMappingURL=NullLogger.js.map

package/dist/logger/NullLogger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger/NullLogger.js","sources":["../../src/logger/NullLogger.ts"],"sourcesContent":["/**\n * Null logger that discards all log messages.\n *\n * This logger implements the same interface as `StructuredLogger` but\n * silently discards all log messages. It's useful as a default/fallback\n * logger when logging is disabled or when no logger is provided.\n *\n * @module logger\n */\n\nimport type { LogLevel, Logger, LoggerOptions } from './StructuredLogger.js';\n\n/**\n * Null logger that discards all log messages.\n *\n * This class provides a no-op implementation of the logger interface.\n * All method calls are silent and have no effect, making it suitable\n * for use as a default logger when logging is disabled or not needed.\n *\n * @remarks\n * The `NullLogger` implements the same interface as `StructuredLogger`,\n * making them interchangeable. Use `NullLogger` when:\n * - You want to disable logging completely\n * - You need a logger placeholder that can be swapped later\n * - Testing components that don't need output\n * - Reducing overhead in performance-critical sections\n *\n * @example\n * ```typescript\n * import { NullLogger } from './logger/index.js';\n *\n * // Create a null logger\n * const logger = new NullLogger();\n *\n * // All log calls are silently discarded\n * logger.debug('This will not appear');\n * logger.info('Nor will this');\n * logger.warn('Or this warning');\n * logger.error('Or even this error');\n *\n * // Methods exist for compatibility but have no effect\n * logger.setLevel('debug');\n * const level = logger.getLevel(); // Returns 'error' (default)\n * ```\n */\nexport class NullLogger implements Logger {\n\t/**\n\t * Current minimum log level.\n\t *\n\t * @remarks\n\t * Since all messages are discarded, the level setting has no practical\n\t * effect. This property exists only for interface compatibility.\n\t * @private\n\t */\n\tprivate _level: LogLevel;\n\n\t/**\n\t * Creates a new NullLogger instance.\n\t *\n\t * @param options - Configuration options (ignored, but accepted for interface compatibility)\n\t *\n\t * @example\n\t * ```typescript\n\t * // Create a null logger\n\t * const logger1 = new NullLogger();\n\t *\n\t * // With options (ignored)\n\t * const logger2 = new NullLogger({\n\t *   level: 'debug',\n\t *   context: 'MyApp',\n\t *   pretty: true\n\t * });\n\t * ```\n\t */\n\tconstructor(options: LoggerOptions = {}) {\n\t\tthis._level = options.level ?? 'error';\n\t}\n\n\t/**\n\t * Log a debug message (no-op).\n\t *\n\t * This method exists for interface compatibility but does nothing.\n\t *\n\t * @param _message - Ignored\n\t * @param _meta - Ignored\n\t */\n\tdebug(_message: string, _meta?: Record<string, unknown>): void {}\n\n\t/**\n\t * Log an info message (no-op).\n\t *\n\t * This method exists for interface compatibility but does nothing.\n\t *\n\t * @param _message - Ignored\n\t * @param _meta - Ignored\n\t */\n\tinfo(_message: string, _meta?: Record<string, unknown>): void {}\n\n\t/**\n\t * Log a warning message (no-op).\n\t *\n\t * This method exists for interface compatibility but does nothing.\n\t *\n\t * @param _message - Ignored\n\t * @param _meta - Ignored\n\t */\n\twarn(_message: string, _meta?: Record<string, unknown>): void {}\n\n\t/**\n\t * Log an error message (no-op).\n\t *\n\t * This method exists for interface compatibility but does nothing.\n\t *\n\t * @param _message - Ignored\n\t * @param _meta - Ignored\n\t */\n\terror(_message: string, _meta?: Record<string, unknown>): void {}\n\n\t/**\n\t * Sets the minimum log level (no-op).\n\t *\n\t * This method exists for interface compatibility but has no effect\n\t * since all messages are discarded anyway.\n\t *\n\t * @param level - The new minimum log level (ignored)\n\t *\n\t * @example\n\t * ```typescript\n\t * logger.setLevel('debug');  // No effect\n\t * ```\n\t */\n\tsetLevel(level: LogLevel): void {\n\t\tthis._level = level;\n\t}\n\n\t/**\n\t * Gets the current minimum log level.\n\t *\n\t * @returns The current log level (stored value, unused)\n\t *\n\t * @example\n\t * ```typescript\n\t * const currentLevel = logger.getLevel();\n\t * console.log(`Current level: ${currentLevel}`); // 'error' by default\n\t * ```\n\t */\n\tgetLevel(): LogLevel {\n\t\treturn this._level;\n\t}\n\n\t/**\n\t * Creates a child null logger (returns a new NullLogger).\n\t *\n\t * This method exists for interface compatibility. It returns a new\n\t * `NullLogger` instance (not a child with extended context) since\n\t * context tracking is not applicable for a no-op logger.\n\t *\n\t * @param _context - Additional context (ignored)\n\t * @returns A new NullLogger instance\n\t *\n\t * @example\n\t * ```typescript\n\t * const nullLogger = new NullLogger();\n\t * const childLogger = nullLogger.createChild('ChildModule');\n\t * // childLogger is also a NullLogger\n\t * ```\n\t */\n\tcreateChild(_context: string): NullLogger {\n\t\treturn new NullLogger({ level: this._level });\n\t}\n}\n"],"names":["NullLogger","options","_message","_meta","level","_context"],"mappings":"AA6CO,MAAMA;IASJ,OAAiB;IAoBzB,YAAYC,UAAyB,CAAC,CAAC,CAAE;QACxC,IAAI,CAAC,MAAM,GAAGA,QAAQ,KAAK,IAAI;IAChC;IAUA,MAAMC,QAAgB,EAAEC,KAA+B,EAAQ,CAAC;IAUhE,KAAKD,QAAgB,EAAEC,KAA+B,EAAQ,CAAC;IAU/D,KAAKD,QAAgB,EAAEC,KAA+B,EAAQ,CAAC;IAU/D,MAAMD,QAAgB,EAAEC,KAA+B,EAAQ,CAAC;IAehE,SAASC,KAAe,EAAQ;QAC/B,IAAI,CAAC,MAAM,GAAGA;IACf;IAaA,WAAqB;QACpB,OAAO,IAAI,CAAC,MAAM;IACnB;IAmBA,YAAYC,QAAgB,EAAc;QACzC,OAAO,IAAIL,WAAW;YAAE,OAAO,IAAI,CAAC,MAAM;QAAC;IAC5C;AACD"}

package/dist/logger/StructuredLogger.d.ts

@@ -0,0 +1,327 @@
+/**
+ * Lightweight structured logging without external dependencies.
+ *
+ * This module provides a structured logging implementation that writes to stderr
+ * for MCP server compatibility. It supports multiple log levels, pretty printing,
+ * and hierarchical child loggers with inherited context.
+ *
+ * @module logger
+ */
+/**
+ * Log level severity ordering.
+ *
+ * Levels are ordered from least severe (debug) to most severe (error).
+ * Only messages at or above the configured level will be logged.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Common logger interface for all logger implementations.
+ *
+ * This interface defines the contract that all loggers must implement,
+ * allowing them to be used interchangeably throughout the application.
+ */
+export interface Logger {
+    /**
+     * Log a debug message.
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     */
+    debug(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log an info message.
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     */
+    info(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log a warning message.
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     */
+    warn(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log an error message.
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     */
+    error(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Sets the minimum log level.
+     * @param level - The new minimum log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Gets the current minimum log level.
+     * @returns The current log level
+     */
+    getLevel(): LogLevel;
+}
+/**
+ * A single log entry with all relevant metadata.
+ *
+ * @example
+ * ```typescript
+ * const entry: LogEntry = {
+ *   level: 'info',
+ *   message: 'Server started',
+ *   timestamp: '2026-01-18T10:30:00.000Z',
+ *   context: 'SequentialThinking',
+ *   meta: { port: 3000 }
+ * };
+ * ```
+ */
+export interface LogEntry {
+    /** Severity level of the log entry. */
+    level: LogLevel;
+    /** The primary log message. */
+    message: string;
+    /** ISO 8601 timestamp of when the log was created. */
+    timestamp: string;
+    /** Optional context/module name for categorization. */
+    context?: string;
+    /** Optional request correlation ID for tracing. */
+    requestId?: string;
+    /** Additional structured metadata to include with the log. */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Configuration options for creating a `StructuredLogger` instance.
+ *
+ * @example
+ * ```typescript
+ * const options: LoggerOptions = {
+ *   level: 'debug',
+ *   context: 'MyModule',
+ *   pretty: true
+ * };
+ * ```
+ */
+export interface LoggerOptions {
+    /**
+     * Minimum log level to output.
+     * Messages below this level will be suppressed.
+     * @default 'info'
+     */
+    level?: LogLevel;
+    /**
+     * Default context for log messages.
+     * Can be extended with child loggers.
+     * @default 'SequentialThinking'
+     */
+    context?: string;
+    /**
+     * Whether to enable pretty (human-readable) output.
+     * When false, outputs JSON-formatted logs.
+     * @default true
+     */
+    pretty?: boolean;
+}
+/**
+ * Structured logger with level filtering and context support.
+ *
+ * This logger provides structured logging capabilities with configurable
+ * output formats, log levels, and hierarchical context. All output is
+ * written to stderr for compatibility with MCP servers.
+ *
+ * @remarks
+ * **Log Level Priority** (lowest to highest):
+ * - `debug` (0) - Detailed debugging information
+ * - `info` (1) - General informational messages
+ * - `warn` (2) - Warning messages for potential issues
+ * - `error` (3) - Error messages for failures
+ *
+ * Only messages at or above the configured level will be output.
+ *
+ * **Output Formats:**
+ * - Pretty (default): `[timestamp] [LEVEL] [context] message {meta}`
+ * - JSON: `{"level":"info","message":"...","timestamp":"...","context":"...","meta":{...}}`
+ *
+ * @example
+ * ```typescript
+ * // Create a logger
+ * const logger = new StructuredLogger({
+ *   level: 'info',
+ *   context: 'SequentialThinking',
+ *   pretty: true
+ * });
+ *
+ * // Log messages
+ * logger.debug('Detailed debug info', { userId: '123' });
+ * logger.info('Server started', { port: 3000 });
+ * logger.warn('High memory usage', { usage: '85%' });
+ * logger.error('Connection failed', { error: 'ECONNREFUSED' });
+ *
+ * // Create a child logger with extended context
+ * const childLogger = logger.createChild('Database');
+ * childLogger.info('Query executed', { rows: 42 });
+ * // Output: [timestamp] [INFO] [SequentialThinking:Database] Query executed {"rows":42}
+ * ```
+ */
+export declare class StructuredLogger {
+    /** Current minimum log level. */
+    private _level;
+    /** Default context for log messages. */
+    private _context;
+    /** Whether pretty printing is enabled. */
+    private _pretty;
+    /**
+     * Log level priority ordering for filtering.
+     * Higher numbers = higher severity.
+     * @private
+     */
+    private static readonly LEVEL_PRIORITY;
+    /**
+     * Creates a new StructuredLogger instance.
+     *
+     * @param options - Configuration options for the logger
+     *
+     * @example
+     * ```typescript
+     * // Default configuration
+     * const logger1 = new StructuredLogger();
+     *
+     * // Custom configuration
+     * const logger2 = new StructuredLogger({
+     *   level: 'debug',
+     *   context: 'MyApp',
+     *   pretty: false  // JSON output
+     * });
+     * ```
+     */
+    constructor(options?: LoggerOptions);
+    /**
+     * Determines whether a message at the given level should be logged.
+     * @param level - The log level to check
+     * @returns true if the level meets the threshold, false otherwise
+     * @private
+     */
+    private shouldLog;
+    /**
+     * Formats a log entry for output.
+     * @param entry - The log entry to format
+     * @returns Formatted string representation
+     * @private
+     */
+    private format;
+    /**
+     * Internal logging method that handles level filtering and output.
+     * @param level - The log level for this message
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     * @private
+     */
+    private log;
+    /**
+     * Log a debug message.
+     *
+     * Debug messages contain detailed information typically used for
+     * troubleshooting and development. Only output when log level is 'debug'.
+     *
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     *
+     * @example
+     * ```typescript
+     * logger.debug('Processing request', { path: '/api/users', method: 'GET' });
+     * ```
+     */
+    debug(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log an info message.
+     *
+     * Info messages contain general informational messages about normal operation.
+     * Output when log level is 'info' or lower.
+     *
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     *
+     * @example
+     * ```typescript
+     * logger.info('Server started', { port: 3000, env: 'production' });
+     * ```
+     */
+    info(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log a warning message.
+     *
+     * Warning messages indicate potential issues that don't prevent operation
+     * but may require attention. Output when log level is 'warn' or lower.
+     *
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     *
+     * @example
+     * ```typescript
+     * logger.warn('High memory usage detected', { usage: '85%', threshold: '80%' });
+     * ```
+     */
+    warn(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Log an error message.
+     *
+     * Error messages indicate failures or error conditions. Always output
+     * regardless of log level setting.
+     *
+     * @param message - The message to log
+     * @param meta - Optional structured metadata
+     *
+     * @example
+     * ```typescript
+     * logger.error('Database connection failed', { error: err.message, code: err.code });
+     * ```
+     */
+    error(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Creates a child logger with inherited settings and extended context.
+     *
+     * Child loggers inherit the parent's log level and pretty print setting,
+     * but have their context appended to the parent's context for hierarchical logging.
+     *
+     * @param context - Additional context to append to the parent's context
+     * @returns A new logger instance with extended context
+     *
+     * @example
+     * ```typescript
+     * const parentLogger = new StructuredLogger({ context: 'App' });
+     * const dbLogger = parentLogger.createChild('Database');
+     * const queryLogger = dbLogger.createChild('Query');
+     *
+     * parentLogger.info('Starting up');
+     * // Output: [timestamp] [INFO] [App] Starting up
+     *
+     * dbLogger.info('Connected');
+     * // Output: [timestamp] [INFO] [App:Database] Connected
+     *
+     * queryLogger.info('Executed in 5ms');
+     * // Output: [timestamp] [INFO] [App:Database:Query] Executed in 5ms
+     * ```
+     */
+    createChild(context: string): StructuredLogger;
+    /**
+     * Sets the minimum log level.
+     *
+     * Only messages at or above this level will be output.
+     *
+     * @param level - The new minimum log level
+     *
+     * @example
+     * ```typescript
+     * logger.setLevel('debug');  // Enable all logging
+     * logger.setLevel('error');  // Only show errors
+     * ```
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Gets the current minimum log level.
+     *
+     * @returns The current log level
+     *
+     * @example
+     * ```typescript
+     * const currentLevel = logger.getLevel();
+     * console.log(`Current level: ${currentLevel}`);
+     * ```
+     */
+    getLevel(): LogLevel;
+}
+//# sourceMappingURL=StructuredLogger.d.ts.map

package/dist/logger/StructuredLogger.d.ts.map

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

package/dist/logger/StructuredLogger.js

@@ -0,0 +1,72 @@
+import { getRequestId } from "../context/RequestContext.js";
+class StructuredLogger {
+    _level;
+    _context;
+    _pretty;
+    static LEVEL_PRIORITY = {
+        debug: 0,
+        info: 1,
+        warn: 2,
+        error: 3
+    };
+    constructor(options = {}){
+        this._level = options.level ?? 'info';
+        this._context = options.context ?? 'SequentialThinking';
+        this._pretty = options.pretty ?? true;
+    }
+    shouldLog(level) {
+        return StructuredLogger.LEVEL_PRIORITY[level] >= StructuredLogger.LEVEL_PRIORITY[this._level];
+    }
+    format(entry) {
+        if (this._pretty) {
+            const metaStr = entry.meta ? ` ${JSON.stringify(entry.meta)}` : '';
+            const requestIdStr = entry.requestId ? ` [${entry.requestId}]` : '';
+            return `[${entry.timestamp}] [${entry.level.toUpperCase()}]${entry.context ? ` [${entry.context}]` : ''}${requestIdStr} ${entry.message}${metaStr}`;
+        }
+        return JSON.stringify(entry);
+    }
+    log(level, message, meta) {
+        if (!this.shouldLog(level)) return;
+        const requestId = getRequestId();
+        const entry = {
+            level,
+            message,
+            timestamp: new Date().toISOString(),
+            context: this._context,
+            meta,
+            ...requestId ? {
+                requestId
+            } : {}
+        };
+        const formatted = this.format(entry);
+        console.error(formatted);
+    }
+    debug(message, meta) {
+        this.log('debug', message, meta);
+    }
+    info(message, meta) {
+        this.log('info', message, meta);
+    }
+    warn(message, meta) {
+        this.log('warn', message, meta);
+    }
+    error(message, meta) {
+        this.log('error', message, meta);
+    }
+    createChild(context) {
+        return new StructuredLogger({
+            level: this._level,
+            context: `${this._context}:${context}`,
+            pretty: this._pretty
+        });
+    }
+    setLevel(level) {
+        this._level = level;
+    }
+    getLevel() {
+        return this._level;
+    }
+}
+export { StructuredLogger };
+
+//# sourceMappingURL=StructuredLogger.js.map

package/dist/logger/StructuredLogger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger/StructuredLogger.js","sources":["../../src/logger/StructuredLogger.ts"],"sourcesContent":["/**\n * Lightweight structured logging without external dependencies.\n *\n * This module provides a structured logging implementation that writes to stderr\n * for MCP server compatibility. It supports multiple log levels, pretty printing,\n * and hierarchical child loggers with inherited context.\n *\n * @module logger\n */\n\nimport { getRequestId } from '../context/RequestContext.js';\n\n/**\n * Log level severity ordering.\n *\n * Levels are ordered from least severe (debug) to most severe (error).\n * Only messages at or above the configured level will be logged.\n */\nexport type LogLevel = 'debug' | 'info' | 'warn' | 'error';\n\n/**\n * Common logger interface for all logger implementations.\n *\n * This interface defines the contract that all loggers must implement,\n * allowing them to be used interchangeably throughout the application.\n */\nexport interface Logger {\n\t/**\n\t * Log a debug message.\n\t * @param message - The message to log\n\t * @param meta - Optional structured metadata\n\t */\n\tdebug(message: string, meta?: Record<string, unknown>): void;\n\n\t/**\n\t * Log an info message.\n\t * @param message - The message to log\n\t * @param meta - Optional structured metadata\n\t */\n\tinfo(message: string, meta?: Record<string, unknown>): void;\n\n\t/**\n\t * Log a warning message.\n\t * @param message - The message to log\n\t * @param meta - Optional structured metadata\n\t */\n\twarn(message: string, meta?: Record<string, unknown>): void;\n\n\t/**\n\t * Log an error message.\n\t * @param message - The message to log\n\t * @param meta - Optional structured metadata\n\t */\n\terror(message: string, meta?: Record<string, unknown>): void;\n\n\t/**\n\t * Sets the minimum log level.\n\t * @param level - The new minimum log level\n\t */\n\tsetLevel(level: LogLevel): void;\n\n\t/**\n\t * Gets the current minimum log level.\n\t * @returns The current log level\n\t */\n\tgetLevel(): LogLevel;\n}\n\n/**\n * A single log entry with all relevant metadata.\n *\n * @example\n * ```typescript\n * const entry: LogEntry = {\n *   level: 'info',\n *   message: 'Server started',\n *   timestamp: '2026-01-18T10:30:00.000Z',\n *   context: 'SequentialThinking',\n *   meta: { port: 3000 }\n * };\n * ```\n */\nexport interface LogEntry {\n\t/** Severity level of the log entry. */\n\tlevel: LogLevel;\n\n\t/** The primary log message. */\n\tmessage: string;\n\n\t/** ISO 8601 timestamp of when the log was created. */\n\ttimestamp: string;\n\n\t/** Optional context/module name for categorization. */\n\tcontext?: string;\n\n\t/** Optional request correlation ID for tracing. */\n\trequestId?: string;\n\n\t/** Additional structured metadata to include with the log. */\n\tmeta?: Record<string, unknown>;\n}\n\n/**\n * Configuration options for creating a `StructuredLogger` instance.\n *\n * @example\n * ```typescript\n * const options: LoggerOptions = {\n *   level: 'debug',\n *   context: 'MyModule',\n *   pretty: true\n * };\n * ```\n */\nexport interface LoggerOptions {\n\t/**\n\t * Minimum log level to output.\n\t * Messages below this level will be suppressed.\n\t * @default 'info'\n\t */\n\tlevel?: LogLevel;\n\n\t/**\n\t * Default context for log messages.\n\t * Can be extended with child loggers.\n\t * @default 'SequentialThinking'\n\t */\n\tcontext?: string;\n\n\t/**\n\t * Whether to enable pretty (human-readable) output.\n\t * When false, outputs JSON-formatted logs.\n\t * @default true\n\t */\n\tpretty?: boolean;\n}\n\n/**\n * Structured logger with level filtering and context support.\n *\n * This logger provides structured logging capabilities with configurable\n * output formats, log levels, and hierarchical context. All output is\n * written to stderr for compatibility with MCP servers.\n *\n * @remarks\n * **Log Level Priority** (lowest to highest):\n * - `debug` (0) - Detailed debugging information\n * - `info` (1) - General informational messages\n * - `warn` (2) - Warning messages for potential issues\n * - `error` (3) - Error messages for failures\n *\n * Only messages at or above the configured level will be output.\n *\n * **Output Formats:**\n * - Pretty (default): `[timestamp] [LEVEL] [context] message {meta}`\n * - JSON: `{\"level\":\"info\",\"message\":\"...\",\"timestamp\":\"...\",\"context\":\"...\",\"meta\":{...}}`\n *\n * @example\n * ```typescript\n * // Create a logger\n * const logger = new StructuredLogger({\n *   level: 'info',\n *   context: 'SequentialThinking',\n *   pretty: true\n * });\n *\n * // Log messages\n * logger.debug('Detailed debug info', { userId: '123' });\n * logger.info('Server started', { port: 3000 });\n * logger.warn('High memory usage', { usage: '85%' });\n * logger.error('Connection failed', { error: 'ECONNREFUSED' });\n *\n * // Create a child logger with extended context\n * const childLogger = logger.createChild('Database');\n * childLogger.info('Query executed', { rows: 42 });\n * // Output: [timestamp] [INFO] [SequentialThinking:Database] Query executed {\"rows\":42}\n * ```\n */\nexport class StructuredLogger {\n\t/** Current minimum log level. */\n\tprivate _level: LogLevel;\n\n\t/** Default context for log messages. */\n\tprivate _context: string;\n\n\t/** Whether pretty printing is enabled. */\n\tprivate _pretty: boolean;\n\n\t/**\n\t * Log level priority ordering for filtering.\n\t * Higher numbers = higher severity.\n\t * @private\n\t */\n\tprivate static readonly LEVEL_PRIORITY: Record<LogLevel, number> = {\n\t\tdebug: 0,\n\t\tinfo: 1,\n\t\twarn: 2,\n\t\terror: 3,\n\t};\n\n\t/**\n\t * Creates a new StructuredLogger instance.\n\t *\n\t * @param options - Configuration options for the logger\n\t *\n\t * @example\n\t * ```typescript\n\t * // Default configuration\n\t * const logger1 = new StructuredLogger();\n\t *\n\t * // Custom configuration\n\t * const logger2 = new StructuredLogger({\n\t *   level: 'debug',\n\t *   context: 'MyApp',\n\t *   pretty: false  // JSON output\n\t * });\n\t * ```\n\t */\n\tconstructor(options: LoggerOptions = {}) {\n\t\tthis._level = options.level ?? 'info';\n\t\tthis._context = options.context ?? 'SequentialThinking';\n\t\tthis._pretty = options.pretty ?? true;\n\t}\n\n\t/**\n\t * Determines whether a message at the given level should be logged.\n\t * @param level - The log level to check\n\t * @returns true if the level meets the threshold, false otherwise\n\t * @private\n\t */\n\tprivate shouldLog(level: LogLevel): boolean {\n\t\treturn StructuredLogger.LEVEL_PRIORITY[level] >= StructuredLogger.LEVEL_PRIORITY[this._level];\n\t}\n\n\t/**\n\t * Formats a log entry for output.\n\t * @param entry - The log entry to format\n\t * @returns Formatted string representation\n\t * @private\n\t */\n\tprivate format(entry: LogEntry): string {\n\t\tif (this._pretty) {\n\t\t\tconst metaStr = entry.meta ? ` ${JSON.stringify(entry.meta)}` : '';\n\t\t\tconst requestIdStr = entry.requestId ? ` [${entry.requestId}]` : '';\n\t\t\treturn `[${entry.timestamp}] [${entry.level.toUpperCase()}]${entry.context ? ` [${entry.context}]` : ''}${requestIdStr} ${entry.message}${metaStr}`;\n\t\t}\n\t\treturn JSON.stringify(entry);\n\t}\n\n\t/**\n\t * Internal logging method that handles level filtering and output.\n\t * @param level - The log level for this message\n\t * @param message - The message to log\n\t * @param meta - Optional structured metadata\n\t * @private\n\t */\n\tprivate log(level: LogLevel, message: string, meta?: Record<string, unknown>): void {\n\t\tif (!this.shouldLog(level)) return;\n\n\t\tconst requestId = getRequestId();\n\n\t\tconst entry: LogEntry = {\n\t\t\tlevel,\n\t\t\tmessage,\n\t\t\ttimestamp: new Date().toISOString(),\n\t\t\tcontext: this._context,\n\t\t\tmeta,\n\t\t\t...(requestId ? { requestId } : {}),\n\t\t};\n\n\t\tconst formatted = this.format(entry);\n\n\t\t// Write to stderr for MCP server compatibility\n\t\tconsole.error(formatted);\n\t}\n\n\t/**\n\t * Log a debug message.\n\t *\n\t * Debug messages contain detailed information typically used for\n\t * troubleshooting and development. Only output when log level is 'debug'.\n\t *\n\t * @param message - The message to log\n\t * @param meta - Optional structured metadata\n\t *\n\t * @example\n\t * ```typescript\n\t * logger.debug('Processing request', { path: '/api/users', method: 'GET' });\n\t * ```\n\t */\n\tdebug(message: string, meta?: Record<string, unknown>): void {\n\t\tthis.log('debug', message, meta);\n\t}\n\n\t/**\n\t * Log an info message.\n\t *\n\t * Info messages contain general informational messages about normal operation.\n\t * Output when log level is 'info' or lower.\n\t *\n\t * @param message - The message to log\n\t * @param meta - Optional structured metadata\n\t *\n\t * @example\n\t * ```typescript\n\t * logger.info('Server started', { port: 3000, env: 'production' });\n\t * ```\n\t */\n\tinfo(message: string, meta?: Record<string, unknown>): void {\n\t\tthis.log('info', message, meta);\n\t}\n\n\t/**\n\t * Log a warning message.\n\t *\n\t * Warning messages indicate potential issues that don't prevent operation\n\t * but may require attention. Output when log level is 'warn' or lower.\n\t *\n\t * @param message - The message to log\n\t * @param meta - Optional structured metadata\n\t *\n\t * @example\n\t * ```typescript\n\t * logger.warn('High memory usage detected', { usage: '85%', threshold: '80%' });\n\t * ```\n\t */\n\twarn(message: string, meta?: Record<string, unknown>): void {\n\t\tthis.log('warn', message, meta);\n\t}\n\n\t/**\n\t * Log an error message.\n\t *\n\t * Error messages indicate failures or error conditions. Always output\n\t * regardless of log level setting.\n\t *\n\t * @param message - The message to log\n\t * @param meta - Optional structured metadata\n\t *\n\t * @example\n\t * ```typescript\n\t * logger.error('Database connection failed', { error: err.message, code: err.code });\n\t * ```\n\t */\n\terror(message: string, meta?: Record<string, unknown>): void {\n\t\tthis.log('error', message, meta);\n\t}\n\n\t/**\n\t * Creates a child logger with inherited settings and extended context.\n\t *\n\t * Child loggers inherit the parent's log level and pretty print setting,\n\t * but have their context appended to the parent's context for hierarchical logging.\n\t *\n\t * @param context - Additional context to append to the parent's context\n\t * @returns A new logger instance with extended context\n\t *\n\t * @example\n\t * ```typescript\n\t * const parentLogger = new StructuredLogger({ context: 'App' });\n\t * const dbLogger = parentLogger.createChild('Database');\n\t * const queryLogger = dbLogger.createChild('Query');\n\t *\n\t * parentLogger.info('Starting up');\n\t * // Output: [timestamp] [INFO] [App] Starting up\n\t *\n\t * dbLogger.info('Connected');\n\t * // Output: [timestamp] [INFO] [App:Database] Connected\n\t *\n\t * queryLogger.info('Executed in 5ms');\n\t * // Output: [timestamp] [INFO] [App:Database:Query] Executed in 5ms\n\t * ```\n\t */\n\tcreateChild(context: string): StructuredLogger {\n\t\treturn new StructuredLogger({\n\t\t\tlevel: this._level,\n\t\t\tcontext: `${this._context}:${context}`,\n\t\t\tpretty: this._pretty,\n\t\t});\n\t}\n\n\t/**\n\t * Sets the minimum log level.\n\t *\n\t * Only messages at or above this level will be output.\n\t *\n\t * @param level - The new minimum log level\n\t *\n\t * @example\n\t * ```typescript\n\t * logger.setLevel('debug');  // Enable all logging\n\t * logger.setLevel('error');  // Only show errors\n\t * ```\n\t */\n\tsetLevel(level: LogLevel): void {\n\t\tthis._level = level;\n\t}\n\n\t/**\n\t * Gets the current minimum log level.\n\t *\n\t * @returns The current log level\n\t *\n\t * @example\n\t * ```typescript\n\t * const currentLevel = logger.getLevel();\n\t * console.log(`Current level: ${currentLevel}`);\n\t * ```\n\t */\n\tgetLevel(): LogLevel {\n\t\treturn this._level;\n\t}\n}\n"],"names":["StructuredLogger","options","level","entry","metaStr","JSON","requestIdStr","message","meta","requestId","getRequestId","Date","formatted","console","context"],"mappings":";AAkLO,MAAMA;IAEJ,OAAiB;IAGjB,SAAiB;IAGjB,QAAiB;IAOzB,OAAwB,iBAA2C;QAClE,OAAO;QACP,MAAM;QACN,MAAM;QACN,OAAO;IACR,EAAE;IAoBF,YAAYC,UAAyB,CAAC,CAAC,CAAE;QACxC,IAAI,CAAC,MAAM,GAAGA,QAAQ,KAAK,IAAI;QAC/B,IAAI,CAAC,QAAQ,GAAGA,QAAQ,OAAO,IAAI;QACnC,IAAI,CAAC,OAAO,GAAGA,QAAQ,MAAM,IAAI;IAClC;IAQQ,UAAUC,KAAe,EAAW;QAC3C,OAAOF,iBAAiB,cAAc,CAACE,MAAM,IAAIF,iBAAiB,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC;IAC9F;IAQQ,OAAOG,KAAe,EAAU;QACvC,IAAI,IAAI,CAAC,OAAO,EAAE;YACjB,MAAMC,UAAUD,MAAM,IAAI,GAAG,CAAC,CAAC,EAAEE,KAAK,SAAS,CAACF,MAAM,IAAI,GAAG,GAAG;YAChE,MAAMG,eAAeH,MAAM,SAAS,GAAG,CAAC,EAAE,EAAEA,MAAM,SAAS,CAAC,CAAC,CAAC,GAAG;YACjE,OAAO,CAAC,CAAC,EAAEA,MAAM,SAAS,CAAC,GAAG,EAAEA,MAAM,KAAK,CAAC,WAAW,GAAG,CAAC,EAAEA,MAAM,OAAO,GAAG,CAAC,EAAE,EAAEA,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,KAAKG,aAAa,CAAC,EAAEH,MAAM,OAAO,GAAGC,SAAS;QACpJ;QACA,OAAOC,KAAK,SAAS,CAACF;IACvB;IASQ,IAAID,KAAe,EAAEK,OAAe,EAAEC,IAA8B,EAAQ;QACnF,IAAI,CAAC,IAAI,CAAC,SAAS,CAACN,QAAQ;QAE5B,MAAMO,YAAYC;QAElB,MAAMP,QAAkB;YACvBD;YACAK;YACA,WAAW,IAAII,OAAO,WAAW;YACjC,SAAS,IAAI,CAAC,QAAQ;YACtBH;YACA,GAAIC,YAAY;gBAAEA;YAAU,IAAI,CAAC,CAAC;QACnC;QAEA,MAAMG,YAAY,IAAI,CAAC,MAAM,CAACT;QAG9BU,QAAQ,KAAK,CAACD;IACf;IAgBA,MAAML,OAAe,EAAEC,IAA8B,EAAQ;QAC5D,IAAI,CAAC,GAAG,CAAC,SAASD,SAASC;IAC5B;IAgBA,KAAKD,OAAe,EAAEC,IAA8B,EAAQ;QAC3D,IAAI,CAAC,GAAG,CAAC,QAAQD,SAASC;IAC3B;IAgBA,KAAKD,OAAe,EAAEC,IAA8B,EAAQ;QAC3D,IAAI,CAAC,GAAG,CAAC,QAAQD,SAASC;IAC3B;IAgBA,MAAMD,OAAe,EAAEC,IAA8B,EAAQ;QAC5D,IAAI,CAAC,GAAG,CAAC,SAASD,SAASC;IAC5B;IA2BA,YAAYM,OAAe,EAAoB;QAC9C,OAAO,IAAId,iBAAiB;YAC3B,OAAO,IAAI,CAAC,MAAM;YAClB,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAEc,SAAS;YACtC,QAAQ,IAAI,CAAC,OAAO;QACrB;IACD;IAeA,SAASZ,KAAe,EAAQ;QAC/B,IAAI,CAAC,MAAM,GAAGA;IACf;IAaA,WAAqB;QACpB,OAAO,IAAI,CAAC,MAAM;IACnB;AACD"}

package/dist/metrics/__tests__/metrics.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=metrics.test.d.ts.map

package/dist/metrics/__tests__/metrics.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.test.d.ts","sourceRoot":"","sources":["../../../src/metrics/__tests__/metrics.test.ts"],"names":[],"mappings":""}