@c9up/spectrum 0.1.3

package/src/Logger.ts

@@ -0,0 +1,99 @@
+/**
+ * Spectrum Logger — structured logging with levels and correlation ID.
+ *
+ * @implements FR54, FR55, FR56, FR58
+ */
+
+import type { LogConfig, LogEntry, LogLevel } from "./types.js";
+import { LOG_LEVEL_ORDER } from "./types.js";
+
+export type { LogLevel };
+
+export class Logger {
+	private config: LogConfig;
+	private module: string;
+	private correlationId?: string;
+
+	constructor(config: LogConfig, module = "app", correlationId?: string) {
+		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: { module?: string; correlationId?: string }): Logger {
+		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: string): void {
+		this.correlationId = id;
+	}
+
+	trace(message: string, data?: Record<string, unknown>): void {
+		this.log("trace", message, data);
+	}
+
+	debug(message: string, data?: Record<string, unknown>): void {
+		this.log("debug", message, data);
+	}
+
+	info(message: string, data?: Record<string, unknown>): void {
+		this.log("info", message, data);
+	}
+
+	warn(message: string, data?: Record<string, unknown>): void {
+		this.log("warn", message, data);
+	}
+
+	error(message: string, data?: Record<string, unknown>): void {
+		this.log("error", message, data);
+	}
+
+	fatal(message: string, data?: Record<string, unknown>): void {
+		this.log("fatal", message, data);
+	}
+
+	private log(
+		level: LogLevel,
+		message: string,
+		data?: Record<string, unknown>,
+	): void {
+		const rawEffective =
+			this.config.modules?.[this.module] ?? this.config.level;
+		const effectiveLevel: LogLevel =
+			LOG_LEVEL_ORDER[rawEffective] !== undefined ? rawEffective : "info";
+		if ((LOG_LEVEL_ORDER[level] ?? 0) < LOG_LEVEL_ORDER[effectiveLevel]) {
+			return;
+		}
+
+		const entry: LogEntry = {
+			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`,
+				);
+			}
+		}
+	}
+}

package/src/RustLogBridge.ts

@@ -0,0 +1,142 @@
+/**
+ * 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, LogLevel } 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 function parseRustLog(line: string): LogEntry | null {
+	// Pattern: [LEVEL module] message
+	const match = line.match(/^\[(\w+)\s+(\S+)\]\s+(.+)$/);
+	if (!match) return null;
+
+	const levelMap: Record<string, LogLevel> = {
+		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: typeof process.stderr.write | undefined;
+let activeBridge: { stop: () => void } | undefined;
+
+export function createRustLogBridge(channels: LogChannel[]): {
+	start: () => void;
+	stop: () => void;
+} {
+	let bridgingDepth = 0;
+
+	const bridge = {
+		start() {
+			if (activeBridge === bridge) return;
+			if (activeBridge) {
+				const prev = activeOriginalWrite;
+				activeBridge.stop();
+				if (prev) {
+					process.stderr.write = prev as typeof process.stderr.write;
+					prev(
+						"[Spectrum] RustLogBridge replaced — previous bridge stopped. Only one bridge can be active per process.\n" as never,
+					);
+				}
+			}
+
+			activeOriginalWrite = process.stderr.write.bind(process.stderr);
+			activeBridge = bridge;
+
+			process.stderr.write = ((
+				chunk: string | Uint8Array,
+				...args: unknown[]
+			) => {
+				const origWrite = activeOriginalWrite;
+				if (!origWrite) return true;
+				if (bridgingDepth > 0) {
+					return origWrite(chunk as never, ...(args as []));
+				}
+
+				const str =
+					typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
+				let hadRustLog = false;
+				const passthroughLines: string[] = [];
+
+				// 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 as never, ...(args as []));
+				}
+
+				for (const line of passthroughLines) {
+					origWrite(`${line}\n`);
+				}
+
+				return true;
+			}) as typeof process.stderr.write;
+		},
+
+		stop() {
+			if (activeBridge !== bridge) return;
+			if (activeOriginalWrite) {
+				process.stderr.write =
+					activeOriginalWrite as typeof process.stderr.write;
+				activeOriginalWrite = undefined;
+			}
+			activeBridge = undefined;
+		},
+	};
+
+	return bridge;
+}

package/src/SpectrumProvider.ts

@@ -0,0 +1,52 @@
+import { ConsoleChannel } from "./channels/ConsoleChannel.js";
+import { Logger } from "./Logger.js";
+import { setLogger } from "./services/main.js";
+import type { LogLevel } from "./types.js";
+import { LOG_LEVEL_ORDER } from "./types.js";
+
+const VALID_LEVELS = new Set<string>(Object.keys(LOG_LEVEL_ORDER));
+
+function resolveLogLevel(raw: string | undefined): LogLevel {
+	if (raw && VALID_LEVELS.has(raw)) return raw as LogLevel;
+	return "info";
+}
+
+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 {
+	constructor(protected app: SpectrumAppContext) {}
+
+	register() {
+		this.app.container.singleton(Logger, () => {
+			const config = this.app.config.get<{ level?: LogLevel }>("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>(Logger);
+		});
+	}
+
+	async boot() {
+		setLogger(this.app.container.resolve<Logger>(Logger));
+	}
+}

package/src/channels/ConsoleChannel.ts

@@ -0,0 +1,100 @@
+/**
+ * Console log channel — pretty-print in dev, JSON in prod.
+ *
+ * @implements FR57, FR58
+ */
+
+import type { LogChannel, LogEntry } from "../types.js";
+
+export class ConsoleChannel implements LogChannel {
+	name = "console";
+	#format: "pretty" | "json";
+
+	constructor(format: "pretty" | "json" = "pretty") {
+		this.#format = format;
+	}
+
+	write(entry: LogEntry): void {
+		if (this.#format === "json") {
+			this.#writeJson(entry);
+		} else {
+			this.#writePretty(entry);
+		}
+	}
+
+	#writeJson(entry: LogEntry): void {
+		// 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: string): string {
+		// 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: LogEntry): void {
+		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: string, output: string): void {
+		if (level === "error" || level === "fatal") {
+			process.stderr.write(output);
+		} else {
+			process.stdout.write(output);
+		}
+	}
+
+	#levelPrefix(level: string): string {
+		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 " ";
+		}
+	}
+}

package/src/channels/FileChannel.ts

@@ -0,0 +1,170 @@
+/**
+ * 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 * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import type { LogChannel, LogEntry } from "../types.js";
+
+export interface FileChannelConfig {
+	path: string;
+	maxSizeBytes?: number; // default 10MB
+	maxFiles?: number; // default 5
+}
+
+export class FileChannel implements LogChannel {
+	name = "file";
+	#filePath: string;
+	#maxSize: number;
+	#maxFiles: number;
+	#stream: fs.WriteStream | null = null;
+	#currentSize = 0;
+	#dirReady = false;
+	#rotating = false;
+	#pending: string[] = [];
+
+	constructor(config: FileChannelConfig) {
+		this.#filePath = config.path;
+		this.#maxSize = config.maxSizeBytes ?? 10 * 1024 * 1024;
+		this.#maxFiles = config.maxFiles ?? 5;
+	}
+
+	write(entry: LogEntry): void {
+		const line = `${JSON.stringify(entry)}\n`;
+		const bytes = Buffer.byteLength(line, "utf8");
+
+		if (this.#rotating) {
+			this.#pending.push(line);
+			return;
+		}
+
+		if (!this.#stream) {
+			try {
+				this.#openStream();
+			} catch {
+				process.stderr.write(
+					`[Spectrum] FileChannel: failed to open '${this.#filePath}'\n`,
+				);
+				return;
+			}
+		}
+
+		if (this.#currentSize + bytes > this.#maxSize) {
+			this.#pending.push(line);
+			this.#scheduleRotation();
+			return;
+		}
+
+		if (this.#stream) {
+			this.#stream.write(line);
+			this.#currentSize += bytes;
+		}
+	}
+
+	#openStream(): void {
+		// mkdirSync + statSync only on first open (boot) — never on the hot path.
+		// The fast write path goes straight through this.#stream.write() (non-blocking).
+		if (!this.#dirReady) {
+			const dir = path.dirname(this.#filePath);
+			fs.mkdirSync(dir, { recursive: true });
+			this.#dirReady = true;
+		}
+		try {
+			this.#currentSize = fs.statSync(this.#filePath).size;
+		} catch {
+			this.#currentSize = 0;
+		}
+		this.#stream = fs.createWriteStream(this.#filePath, { flags: "a" });
+		this.#stream.on("error", (err) => {
+			process.stderr.write(
+				`[Spectrum] FileChannel stream error: ${err.message}\n`,
+			);
+		});
+	}
+
+	#scheduleRotation(): void {
+		if (this.#rotating) return;
+		this.#rotating = true;
+		queueMicrotask(() => {
+			this.#rotate().finally(() => {
+				this.#rotating = false;
+				this.#flushPending();
+			});
+		});
+	}
+
+	async #rotate(): Promise<void> {
+		try {
+			await this.#closeStream();
+
+			const oldest = `${this.#filePath}.${this.#maxFiles - 1}`;
+			await fsp.rm(oldest, { force: true });
+
+			for (let i = this.#maxFiles - 2; i >= 1; i--) {
+				const from = i === 1 ? this.#filePath : `${this.#filePath}.${i}`;
+				const to = `${this.#filePath}.${i + 1}`;
+				try {
+					await fsp.rename(from, to);
+				} catch {
+					// File doesn't exist — skip
+				}
+			}
+
+			try {
+				await fsp.rename(this.#filePath, `${this.#filePath}.1`);
+			} catch {
+				// Nothing to rotate
+			}
+
+			this.#openStream();
+		} catch {
+			try {
+				this.#openStream();
+			} catch {
+				process.stderr.write(
+					`[Spectrum] FileChannel: rotation failed, logging suspended for '${this.#filePath}'\n`,
+				);
+				this.#stream = null;
+			}
+		}
+	}
+
+	#flushPending(): void {
+		if (!this.#stream) return;
+		while (this.#pending.length > 0) {
+			const line = this.#pending.shift();
+			if (!line) continue;
+			const bytes = Buffer.byteLength(line, "utf8");
+			if (this.#currentSize + bytes > this.#maxSize) {
+				this.#pending.unshift(line);
+				this.#scheduleRotation();
+				return;
+			}
+			this.#stream.write(line);
+			this.#currentSize += bytes;
+		}
+	}
+
+	async #closeStream(): Promise<void> {
+		if (!this.#stream) return;
+		const stream = this.#stream;
+		this.#stream = null;
+		return new Promise((resolve) => {
+			stream.end(() => resolve());
+		});
+	}
+
+	close(): void {
+		if (this.#stream) {
+			this.#stream.end();
+			this.#stream = null;
+		}
+	}
+}

package/src/config.ts

@@ -0,0 +1,7 @@
+import type { LogConfig } from "./types.js";
+
+export function defineConfig(config: LogConfig): LogConfig {
+	return config;
+}
+
+export type { LogConfig };

package/src/configure.ts

@@ -0,0 +1,23 @@
+interface Codemods {
+	addProvider(importPath: string): Promise<void>;
+	addEnvVars(vars: Record<string, string>): Promise<void>;
+	writeFile(
+		filePath: string,
+		content: string,
+		options?: { force?: boolean },
+	): Promise<void>;
+}
+
+export async function configure(codemods: Codemods): Promise<void> {
+	await codemods.addProvider("@c9up/spectrum/provider");
+	await codemods.writeFile(
+		"config/logger.ts",
+		`import { defineConfig } from '@c9up/spectrum'
+
+export default defineConfig({
+  level: process.env.LOG_LEVEL ?? 'info',
+  channels: ['console'],
+})
+`,
+	);
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @module @c9up/spectrum
+ * @description Spectrum — structured logging for the Ream framework
+ * @implements FR54, FR55, FR56, FR57, FR58
+ */
+
+export { ConsoleChannel } from "./channels/ConsoleChannel.js";
+export { FileChannel } from "./channels/FileChannel.js";
+export { defineConfig } from "./config.js";
+export { configure } from "./configure.js";
+export { Logger, type LogLevel } from "./Logger.js";
+export { createRustLogBridge, parseRustLog } from "./RustLogBridge.js";
+export type { LogChannel, LogConfig, LogEntry } from "./types.js";

package/src/services/main.ts

@@ -0,0 +1,39 @@
+/**
+ * Default `Logger` singleton — mirror of Adonis's
+ * `import logger from '@adonisjs/core/services/logger'` shape.
+ *
+ *   import logger from '@c9up/spectrum/services/main'
+ *
+ *   logger.info({ userId }, 'user logged in')
+ *
+ * Populated by `SpectrumProvider.boot()`.
+ */
+
+import type { Logger } from "../Logger.js";
+
+let instance: Logger | undefined;
+
+/** @internal Bind the singleton (called by SpectrumProvider). */
+export function setLogger(value: Logger): void {
+	instance = value;
+}
+
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export function getLogger(): Logger | undefined {
+	return instance;
+}
+
+const logger: Logger = new Proxy({} as Logger, {
+	get(_target, prop) {
+		if (!instance) {
+			throw new Error(
+				"[spectrum] Logger singleton accessed before SpectrumProvider.boot() ran. " +
+					"Check that `@c9up/spectrum/provider` is listed in your reamrc.ts providers.",
+			);
+		}
+		const value = Reflect.get(instance, prop, instance);
+		return typeof value === "function" ? value.bind(instance) : value;
+	},
+});
+
+export default logger;