@c9up/spectrum 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C9up
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @c9up/spectrum
+
+Structured logging for Node.js. Levels, channels, correlation IDs, per-module overrides.
+
+## Usage
+
+```typescript
+import { Logger, ConsoleChannel } from '@c9up/spectrum'
+
+const logger = new Logger({
+  level: 'info',
+  channels: [new ConsoleChannel('pretty')],
+})
+
+logger.info('Server started', { port: 3000 })
+logger.child({ module: 'db', correlationId: 'abc-123' }).debug('Query executed')
+```
+
+## Features
+
+- 6 log levels: trace, debug, info, warn, error, fatal
+- ConsoleChannel (pretty + JSON formats)
+- Per-module level overrides
+- Child loggers with scoped module/correlationId
+- error/fatal → stderr, others → stdout
+
+## License
+
+MIT

package/dist/Logger.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Spectrum Logger — structured logging with levels and correlation ID.
+ *
+ * @implements FR54, FR55, FR56, FR58
+ */
+import type { LogConfig, LogLevel } from "./types.js";
+export type { LogLevel };
+export declare class Logger {
+    private config;
+    private module;
+    private correlationId?;
+    constructor(config: LogConfig, module?: string, correlationId?: string);
+    /**
+     * Create a child logger scoped to a module and/or correlation ID.
+     * This is the preferred way to set correlation ID — creates an immutable copy.
+     */
+    child(options: {
+        module?: string;
+        correlationId?: string;
+    }): Logger;
+    /**
+     * Set the correlation ID on THIS instance.
+     * Prefer child() for per-request scoping to avoid shared-state mutation.
+     */
+    setCorrelationId(id: string): void;
+    trace(message: string, data?: Record<string, unknown>): void;
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    fatal(message: string, data?: Record<string, unknown>): void;
+    private log;
+}
+//# sourceMappingURL=Logger.d.ts.map

package/dist/Logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../src/Logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAY,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGhE,YAAY,EAAE,QAAQ,EAAE,CAAC;AAEzB,qBAAa,MAAM;IAClB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAC,CAAS;gBAEnB,MAAM,EAAE,SAAS,EAAE,MAAM,SAAQ,EAAE,aAAa,CAAC,EAAE,MAAM;IAMrE;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;IAQnE;;;OAGG;IACH,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIlC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D,OAAO,CAAC,GAAG;CAgCX"}

package/dist/Logger.js

@@ -0,0 +1,72 @@
+/**
+ * Spectrum Logger — structured logging with levels and correlation ID.
+ *
+ * @implements FR54, FR55, FR56, FR58
+ */
+import { LOG_LEVEL_ORDER } from "./types.js";
+export class Logger {
+    config;
+    module;
+    correlationId;
+    constructor(config, module = "app", correlationId) {
+        this.config = config;
+        this.module = module;
+        this.correlationId = correlationId;
+    }
+    /**
+     * Create a child logger scoped to a module and/or correlation ID.
+     * This is the preferred way to set correlation ID — creates an immutable copy.
+     */
+    child(options) {
+        return new Logger(this.config, options.module ?? this.module, options.correlationId ?? this.correlationId);
+    }
+    /**
+     * Set the correlation ID on THIS instance.
+     * Prefer child() for per-request scoping to avoid shared-state mutation.
+     */
+    setCorrelationId(id) {
+        this.correlationId = id;
+    }
+    trace(message, data) {
+        this.log("trace", message, data);
+    }
+    debug(message, data) {
+        this.log("debug", message, data);
+    }
+    info(message, data) {
+        this.log("info", message, data);
+    }
+    warn(message, data) {
+        this.log("warn", message, data);
+    }
+    error(message, data) {
+        this.log("error", message, data);
+    }
+    fatal(message, data) {
+        this.log("fatal", message, data);
+    }
+    log(level, message, data) {
+        const rawEffective = this.config.modules?.[this.module] ?? this.config.level;
+        const effectiveLevel = LOG_LEVEL_ORDER[rawEffective] !== undefined ? rawEffective : "info";
+        if ((LOG_LEVEL_ORDER[level] ?? 0) < LOG_LEVEL_ORDER[effectiveLevel]) {
+            return;
+        }
+        const entry = {
+            level,
+            message,
+            module: this.module,
+            correlationId: this.correlationId,
+            timestamp: new Date().toISOString(),
+            data,
+        };
+        for (const channel of this.config.channels) {
+            try {
+                channel.write(entry);
+            }
+            catch (err) {
+                process.stderr.write(`[Spectrum] Channel '${channel.name}' failed for: ${message} — ${String(err)}\n`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=Logger.js.map

package/dist/Logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.js","sourceRoot":"","sources":["../src/Logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAI7C,MAAM,OAAO,MAAM;IACV,MAAM,CAAY;IAClB,MAAM,CAAS;IACf,aAAa,CAAU;IAE/B,YAAY,MAAiB,EAAE,MAAM,GAAG,KAAK,EAAE,aAAsB;QACpE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACpC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAoD;QACzD,OAAO,IAAI,MAAM,CAChB,IAAI,CAAC,MAAM,EACX,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,EAC7B,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC,aAAa,CAC3C,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,gBAAgB,CAAC,EAAU;QAC1B,IAAI,CAAC,aAAa,GAAG,EAAE,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAA8B;QACpD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAA8B;QACpD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAA8B;QACnD,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAA8B;QACnD,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAA8B;QACpD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAA8B;QACpD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAEO,GAAG,CACV,KAAe,EACf,OAAe,EACf,IAA8B;QAE9B,MAAM,YAAY,GACjB,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;QACzD,MAAM,cAAc,GACnB,eAAe,CAAC,YAAY,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC;QACrE,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,eAAe,CAAC,cAAc,CAAC,EAAE,CAAC;YACrE,OAAO;QACR,CAAC;QAED,MAAM,KAAK,GAAa;YACvB,KAAK;YACL,OAAO;YACP,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,IAAI;SACJ,CAAC;QAEF,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YAC5C,IAAI,CAAC;gBACJ,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACd,OAAO,CAAC,MAAM,CAAC,KAAK,CACnB,uBAAuB,OAAO,CAAC,IAAI,iBAAiB,OAAO,MAAM,MAAM,CAAC,GAAG,CAAC,IAAI,CAChF,CAAC;YACH,CAAC;QACF,CAAC;IACF,CAAC;CACD"}

package/dist/RustLogBridge.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Rust Log Bridge — unifies Rust stderr output with Spectrum log entries.
+ *
+ * Captures Rust log output (which goes to stderr) and re-emits it
+ * through the Spectrum Logger so both Rust and TS logs appear in
+ * the same stream with the same format.
+ *
+ * @implements FR55
+ */
+import type { LogChannel, LogEntry } from "./types.js";
+/**
+ * Parse a Rust log line into a Spectrum LogEntry.
+ * Supports common Rust log formats:
+ *   [INFO ream_http] Server listening on 0.0.0.0:3000
+ *   [WARN ream_bus] Slow dispatch: 5ms
+ */
+export declare function parseRustLog(line: string): LogEntry | null;
+export declare function createRustLogBridge(channels: LogChannel[]): {
+    start: () => void;
+    stop: () => void;
+};
+//# sourceMappingURL=RustLogBridge.d.ts.map

package/dist/RustLogBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RustLogBridge.d.ts","sourceRoot":"","sources":["../src/RustLogBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAY,MAAM,YAAY,CAAC;AAEjE;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAuB1D;AAcD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG;IAC5D,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,IAAI,CAAC;CACjB,CAmFA"}

package/dist/RustLogBridge.js

@@ -0,0 +1,124 @@
+/**
+ * Rust Log Bridge — unifies Rust stderr output with Spectrum log entries.
+ *
+ * Captures Rust log output (which goes to stderr) and re-emits it
+ * through the Spectrum Logger so both Rust and TS logs appear in
+ * the same stream with the same format.
+ *
+ * @implements FR55
+ */
+/**
+ * Parse a Rust log line into a Spectrum LogEntry.
+ * Supports common Rust log formats:
+ *   [INFO ream_http] Server listening on 0.0.0.0:3000
+ *   [WARN ream_bus] Slow dispatch: 5ms
+ */
+export function parseRustLog(line) {
+    // Pattern: [LEVEL module] message
+    const match = line.match(/^\[(\w+)\s+(\S+)\]\s+(.+)$/);
+    if (!match)
+        return null;
+    const levelMap = {
+        TRACE: "trace",
+        DEBUG: "debug",
+        INFO: "info",
+        WARN: "warn",
+        ERROR: "error",
+        FATAL: "fatal",
+    };
+    const level = levelMap[match[1].toUpperCase()];
+    if (!level)
+        return null;
+    return {
+        level,
+        message: match[3],
+        module: match[2].replace(/_/g, "-"),
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Create a bridge that captures stderr and routes Rust logs to Spectrum channels.
+ *
+ * Usage:
+ *   const bridge = createRustLogBridge(logger.config.channels)
+ *   bridge.start()
+ *   // ... Rust crates emit to stderr
+ *   bridge.stop()
+ */
+let activeOriginalWrite;
+let activeBridge;
+export function createRustLogBridge(channels) {
+    let bridgingDepth = 0;
+    const bridge = {
+        start() {
+            if (activeBridge === bridge)
+                return;
+            if (activeBridge) {
+                const prev = activeOriginalWrite;
+                activeBridge.stop();
+                if (prev) {
+                    process.stderr.write = prev;
+                    prev("[Spectrum] RustLogBridge replaced — previous bridge stopped. Only one bridge can be active per process.\n");
+                }
+            }
+            activeOriginalWrite = process.stderr.write.bind(process.stderr);
+            activeBridge = bridge;
+            process.stderr.write = ((chunk, ...args) => {
+                const origWrite = activeOriginalWrite;
+                if (!origWrite)
+                    return true;
+                if (bridgingDepth > 0) {
+                    return origWrite(chunk, ...args);
+                }
+                const str = typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
+                let hadRustLog = false;
+                const passthroughLines = [];
+                // Try to parse as Rust log — if it matches, route to channels
+                for (const line of str.split("\n")) {
+                    const trimmed = line.trim();
+                    if (!trimmed)
+                        continue;
+                    const entry = parseRustLog(trimmed);
+                    if (entry) {
+                        hadRustLog = true;
+                        for (const channel of channels) {
+                            bridgingDepth++;
+                            try {
+                                channel.write(entry);
+                            }
+                            catch {
+                                /* ignore */
+                            }
+                            finally {
+                                bridgingDepth--;
+                            }
+                        }
+                    }
+                    else {
+                        passthroughLines.push(line);
+                    }
+                }
+                // Preserve original chunk when we didn't intercept any Rust logs.
+                if (!hadRustLog) {
+                    return origWrite(chunk, ...args);
+                }
+                for (const line of passthroughLines) {
+                    origWrite(`${line}\n`);
+                }
+                return true;
+            });
+        },
+        stop() {
+            if (activeBridge !== bridge)
+                return;
+            if (activeOriginalWrite) {
+                process.stderr.write =
+                    activeOriginalWrite;
+                activeOriginalWrite = undefined;
+            }
+            activeBridge = undefined;
+        },
+    };
+    return bridge;
+}
+//# sourceMappingURL=RustLogBridge.js.map

package/dist/RustLogBridge.js.map

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

package/dist/SpectrumProvider.d.ts

@@ -0,0 +1,19 @@
+interface SpectrumContainer {
+    singleton(token: unknown, factory: () => unknown): void;
+    resolve<T = unknown>(token: unknown): T;
+}
+interface SpectrumConfigStore {
+    get<T = unknown>(key: string): T | undefined;
+}
+export interface SpectrumAppContext {
+    container: SpectrumContainer;
+    config: SpectrumConfigStore;
+}
+export default class SpectrumProvider {
+    protected app: SpectrumAppContext;
+    constructor(app: SpectrumAppContext);
+    register(): void;
+    boot(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=SpectrumProvider.d.ts.map

package/dist/SpectrumProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpectrumProvider.d.ts","sourceRoot":"","sources":["../src/SpectrumProvider.ts"],"names":[],"mappings":"AAaA,UAAU,iBAAiB;IAC1B,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;IACxD,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAAC;CACxC;AAED,UAAU,mBAAmB;IAC5B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,iBAAiB,CAAC;IAC7B,MAAM,EAAE,mBAAmB,CAAC;CAC5B;AAED,MAAM,CAAC,OAAO,OAAO,gBAAgB;IACxB,SAAS,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAE7C,QAAQ;IAkBF,IAAI;CAGV"}

package/dist/SpectrumProvider.js

@@ -0,0 +1,35 @@
+import { ConsoleChannel } from "./channels/ConsoleChannel.js";
+import { Logger } from "./Logger.js";
+import { setLogger } from "./services/main.js";
+import { LOG_LEVEL_ORDER } from "./types.js";
+const VALID_LEVELS = new Set(Object.keys(LOG_LEVEL_ORDER));
+function resolveLogLevel(raw) {
+    if (raw && VALID_LEVELS.has(raw))
+        return raw;
+    return "info";
+}
+export default class SpectrumProvider {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    register() {
+        this.app.container.singleton(Logger, () => {
+            const config = this.app.config.get("logger");
+            const level = config?.level && VALID_LEVELS.has(config.level)
+                ? config.level
+                : resolveLogLevel(process.env.LOG_LEVEL);
+            return new Logger({
+                level,
+                channels: [new ConsoleChannel("pretty")],
+            });
+        });
+        this.app.container.singleton("logger", () => {
+            return this.app.container.resolve(Logger);
+        });
+    }
+    async boot() {
+        setLogger(this.app.container.resolve(Logger));
+    }
+}
+//# sourceMappingURL=SpectrumProvider.js.map

package/dist/SpectrumProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpectrumProvider.js","sourceRoot":"","sources":["../src/SpectrumProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,YAAY,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC;AAEnE,SAAS,eAAe,CAAC,GAAuB;IAC/C,IAAI,GAAG,IAAI,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,GAAe,CAAC;IACzD,OAAO,MAAM,CAAC;AACf,CAAC;AAgBD,MAAM,CAAC,OAAO,OAAO,gBAAgB;IACd;IAAtB,YAAsB,GAAuB;QAAvB,QAAG,GAAH,GAAG,CAAoB;IAAG,CAAC;IAEjD,QAAQ;QACP,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE;YACzC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAuB,QAAQ,CAAC,CAAC;YACnE,MAAM,KAAK,GACV,MAAM,EAAE,KAAK,IAAI,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC9C,CAAC,CAAC,MAAM,CAAC,KAAK;gBACd,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC3C,OAAO,IAAI,MAAM,CAAC;gBACjB,KAAK;gBACL,QAAQ,EAAE,CAAC,IAAI,cAAc,CAAC,QAAQ,CAAC,CAAC;aACxC,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,QAAQ,EAAE,GAAG,EAAE;YAC3C,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAS,MAAM,CAAC,CAAC;QACnD,CAAC,CAAC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,IAAI;QACT,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAS,MAAM,CAAC,CAAC,CAAC;IACvD,CAAC;CACD"}

package/dist/channels/ConsoleChannel.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Console log channel — pretty-print in dev, JSON in prod.
+ *
+ * @implements FR57, FR58
+ */
+import type { LogChannel, LogEntry } from "../types.js";
+export declare class ConsoleChannel implements LogChannel {
+    #private;
+    name: string;
+    constructor(format?: "pretty" | "json");
+    write(entry: LogEntry): void;
+}
+//# sourceMappingURL=ConsoleChannel.d.ts.map

package/dist/channels/ConsoleChannel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsoleChannel.d.ts","sourceRoot":"","sources":["../../src/channels/ConsoleChannel.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAExD,qBAAa,cAAe,YAAW,UAAU;;IAChD,IAAI,SAAa;gBAGL,MAAM,GAAE,QAAQ,GAAG,MAAiB;IAIhD,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;CAmF5B"}

package/dist/channels/ConsoleChannel.js

@@ -0,0 +1,89 @@
+/**
+ * Console log channel — pretty-print in dev, JSON in prod.
+ *
+ * @implements FR57, FR58
+ */
+export class ConsoleChannel {
+    name = "console";
+    #format;
+    constructor(format = "pretty") {
+        this.#format = format;
+    }
+    write(entry) {
+        if (this.#format === "json") {
+            this.#writeJson(entry);
+        }
+        else {
+            this.#writePretty(entry);
+        }
+    }
+    #writeJson(entry) {
+        // Data nested under 'data' key — no spread to prevent key collisions
+        const output = JSON.stringify({
+            timestamp: entry.timestamp,
+            level: entry.level,
+            module: entry.module,
+            message: entry.message,
+            correlationId: entry.correlationId,
+            data: entry.data,
+        });
+        this.#writeToStream(entry.level, `${output}\n`);
+    }
+    #sanitize(str) {
+        // Strip ANSI escape sequences. ESC (0x1B) is a control char so we match
+        // it via String.fromCharCode rather than a /\x1b/ regex (Biome's
+        // noControlCharactersInRegex rule rightly flags the literal form).
+        const ESC = String.fromCharCode(0x1b);
+        return str
+            .replace(/\r/g, "\\r")
+            .replace(/\n/g, "\\n")
+            .replaceAll(ESC, "[ESC]");
+    }
+    #writePretty(entry) {
+        const time = entry.timestamp.substring(11, 19); // HH:MM:SS
+        const levelStr = entry.level.toUpperCase().padEnd(5);
+        const prefix = this.#levelPrefix(entry.level);
+        // Sanitize every interpolated piece — `module` is usually
+        // developer-controlled but `correlationId` typically flows in from
+        // an HTTP header (X-Request-Id / X-Correlation-Id) and can carry
+        // attacker-supplied CRLF that would otherwise forge fake log lines.
+        const cidRaw = entry.correlationId
+            ? entry.correlationId.length > 8
+                ? `${entry.correlationId.substring(0, 8)}…`
+                : entry.correlationId
+            : "";
+        const cid = cidRaw ? ` cid=${this.#sanitize(cidRaw)}` : "";
+        const dataStr = entry.data ? ` ${JSON.stringify(entry.data)}` : "";
+        const message = this.#sanitize(entry.message);
+        const module = this.#sanitize(entry.module);
+        this.#writeToStream(entry.level, `${prefix} ${time} ${levelStr} [${module}] ${message}${cid}${dataStr}\n`);
+    }
+    /** Route error/fatal to stderr, others to stdout. */
+    #writeToStream(level, output) {
+        if (level === "error" || level === "fatal") {
+            process.stderr.write(output);
+        }
+        else {
+            process.stdout.write(output);
+        }
+    }
+    #levelPrefix(level) {
+        switch (level) {
+            case "trace":
+                return " ";
+            case "debug":
+                return " ";
+            case "info":
+                return "i";
+            case "warn":
+                return "!";
+            case "error":
+                return "x";
+            case "fatal":
+                return "X";
+            default:
+                return " ";
+        }
+    }
+}
+//# sourceMappingURL=ConsoleChannel.js.map

package/dist/channels/ConsoleChannel.js.map

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

package/dist/channels/FileChannel.d.ts

@@ -0,0 +1,23 @@
+/**
+ * File logging channel — writes log entries to a file as JSON lines.
+ *
+ * Uses a non-blocking WriteStream with an internal buffer. Rotation is
+ * scheduled via queueMicrotask to avoid blocking the event loop on the
+ * HTTP hot path.
+ *
+ * @implements MISS-14, MISS-15
+ */
+import type { LogChannel, LogEntry } from "../types.js";
+export interface FileChannelConfig {
+    path: string;
+    maxSizeBytes?: number;
+    maxFiles?: number;
+}
+export declare class FileChannel implements LogChannel {
+    #private;
+    name: string;
+    constructor(config: FileChannelConfig);
+    write(entry: LogEntry): void;
+    close(): void;
+}
+//# sourceMappingURL=FileChannel.d.ts.map

package/dist/channels/FileChannel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileChannel.d.ts","sourceRoot":"","sources":["../../src/channels/FileChannel.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,WAAY,YAAW,UAAU;;IAC7C,IAAI,SAAU;gBAUF,MAAM,EAAE,iBAAiB;IAMrC,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IA6H5B,KAAK,IAAI,IAAI;CAMb"}