@c9up/spectrum 0.1.3

package/dist/channels/FileChannel.js

@@ -0,0 +1,150 @@
+/**
+ * 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";
+export class FileChannel {
+    name = "file";
+    #filePath;
+    #maxSize;
+    #maxFiles;
+    #stream = null;
+    #currentSize = 0;
+    #dirReady = false;
+    #rotating = false;
+    #pending = [];
+    constructor(config) {
+        this.#filePath = config.path;
+        this.#maxSize = config.maxSizeBytes ?? 10 * 1024 * 1024;
+        this.#maxFiles = config.maxFiles ?? 5;
+    }
+    write(entry) {
+        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() {
+        // 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() {
+        if (this.#rotating)
+            return;
+        this.#rotating = true;
+        queueMicrotask(() => {
+            this.#rotate().finally(() => {
+                this.#rotating = false;
+                this.#flushPending();
+            });
+        });
+    }
+    async #rotate() {
+        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() {
+        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() {
+        if (!this.#stream)
+            return;
+        const stream = this.#stream;
+        this.#stream = null;
+        return new Promise((resolve) => {
+            stream.end(() => resolve());
+        });
+    }
+    close() {
+        if (this.#stream) {
+            this.#stream.end();
+            this.#stream = null;
+        }
+    }
+}
+//# sourceMappingURL=FileChannel.js.map

package/dist/channels/FileChannel.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+import type { LogConfig } from "./types.js";
+export declare function defineConfig(config: LogConfig): LogConfig;
+export type { LogConfig };
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAEzD;AAED,YAAY,EAAE,SAAS,EAAE,CAAC"}

package/dist/config.js

@@ -0,0 +1,4 @@
+export function defineConfig(config) {
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC7C,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/configure.d.ts

@@ -0,0 +1,10 @@
+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 declare function configure(codemods: Codemods): Promise<void>;
+export {};
+//# sourceMappingURL=configure.d.ts.map

package/dist/configure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../src/configure.ts"],"names":[],"mappings":"AAAA,UAAU,QAAQ;IACjB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,SAAS,CACR,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;CACjB;AAED,wBAAsB,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAYjE"}

package/dist/configure.js

@@ -0,0 +1,11 @@
+export async function configure(codemods) {
+    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'],
+})
+`);
+}
+//# sourceMappingURL=configure.js.map

package/dist/configure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure.js","sourceRoot":"","sources":["../src/configure.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,QAAkB;IACjD,MAAM,QAAQ,CAAC,WAAW,CAAC,yBAAyB,CAAC,CAAC;IACtD,MAAM,QAAQ,CAAC,SAAS,CACvB,kBAAkB,EAClB;;;;;;CAMD,CACC,CAAC;AACH,CAAC"}

package/dist/index.d.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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * @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 } from "./Logger.js";
+export { createRustLogBridge, parseRustLog } from "./RustLogBridge.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAiB,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/services/main.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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";
+/** @internal Bind the singleton (called by SpectrumProvider). */
+export declare function setLogger(value: Logger): void;
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export declare function getLogger(): Logger | undefined;
+declare const logger: Logger;
+export default logger;
+//# sourceMappingURL=main.d.ts.map

package/dist/services/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/services/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAI3C,iEAAiE;AACjE,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED,8DAA8D;AAC9D,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAE9C;AAED,QAAA,MAAM,MAAM,EAAE,MAWZ,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/dist/services/main.js

@@ -0,0 +1,31 @@
+/**
+ * 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()`.
+ */
+let instance;
+/** @internal Bind the singleton (called by SpectrumProvider). */
+export function setLogger(value) {
+    instance = value;
+}
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export function getLogger() {
+    return instance;
+}
+const logger = new Proxy({}, {
+    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;
+//# sourceMappingURL=main.js.map

package/dist/services/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/services/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,IAAI,QAA4B,CAAC;AAEjC,iEAAiE;AACjE,MAAM,UAAU,SAAS,CAAC,KAAa;IACtC,QAAQ,GAAG,KAAK,CAAC;AAClB,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,SAAS;IACxB,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED,MAAM,MAAM,GAAW,IAAI,KAAK,CAAC,EAAY,EAAE;IAC9C,GAAG,CAAC,OAAO,EAAE,IAAI;QAChB,IAAI,CAAC,QAAQ,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACd,2EAA2E;gBAC1E,6EAA6E,CAC9E,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACnE,CAAC;CACD,CAAC,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/dist/testing/FakeLogger.d.ts

@@ -0,0 +1,28 @@
+/**
+ * In-memory `LogChannel` for tests — captures every `write(entry)`
+ * and exposes Adonis/Laravel-style `assertLogged` /
+ * `assertNotLogged` helpers in the same shape as Rover's
+ * `FakeMail` and Bay's `FakeQueue`.
+ *
+ * Not re-exported from the main barrel; reach via
+ * `@c9up/spectrum/testing`.
+ */
+import type { LogChannel, LogEntry, LogLevel } from "../types.js";
+export interface FakeLoggerPredicate {
+    /** Substring match against `entry.message`. */
+    containing?: string;
+    /** Custom predicate against `entry.data`. */
+    dataMatches?: (data: Record<string, unknown> | undefined) => boolean;
+}
+export type FakeLoggerPredicateArg = FakeLoggerPredicate | ((entry: LogEntry) => boolean);
+export declare class FakeLogger implements LogChannel {
+    #private;
+    readonly name = "fake";
+    write(entry: LogEntry): void;
+    /** Defensive snapshot of every captured entry. */
+    getLogged(): LogEntry[];
+    reset(): void;
+    assertLogged(level: LogLevel, predicate?: FakeLoggerPredicateArg): void;
+    assertNotLogged(level: LogLevel, predicate?: FakeLoggerPredicateArg): void;
+}
+//# sourceMappingURL=FakeLogger.d.ts.map

package/dist/testing/FakeLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FakeLogger.d.ts","sourceRoot":"","sources":["../../src/testing/FakeLogger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAElE,MAAM,WAAW,mBAAmB;IACnC,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAK,OAAO,CAAC;CACrE;AAED,MAAM,MAAM,sBAAsB,GAC/B,mBAAmB,GACnB,CAAC,CAAC,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC;AAElC,qBAAa,UAAW,YAAW,UAAU;;IAC5C,QAAQ,CAAC,IAAI,UAAU;IAGvB,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAU5B,kDAAkD;IAClD,SAAS,IAAI,QAAQ,EAAE;IAOvB,KAAK,IAAI,IAAI;IAIb,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,sBAAsB,GAAG,IAAI;IAQvE,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,sBAAsB,GAAG,IAAI;CAO1E"}

package/dist/testing/FakeLogger.js

@@ -0,0 +1,111 @@
+/**
+ * In-memory `LogChannel` for tests — captures every `write(entry)`
+ * and exposes Adonis/Laravel-style `assertLogged` /
+ * `assertNotLogged` helpers in the same shape as Rover's
+ * `FakeMail` and Bay's `FakeQueue`.
+ *
+ * Not re-exported from the main barrel; reach via
+ * `@c9up/spectrum/testing`.
+ */
+export class FakeLogger {
+    name = "fake";
+    #captured = [];
+    write(entry) {
+        // Deep-clone via `structuredClone` so nested objects in `data`
+        // are isolated — a shallow `{ ...entry.data }` would leak
+        // mutations of nested fields back into the captured entry.
+        this.#captured.push({
+            ...entry,
+            data: entry.data ? deepClone(entry.data) : undefined,
+        });
+    }
+    /** Defensive snapshot of every captured entry. */
+    getLogged() {
+        return this.#captured.map((e) => ({
+            ...e,
+            data: e.data ? deepClone(e.data) : undefined,
+        }));
+    }
+    reset() {
+        this.#captured = [];
+    }
+    assertLogged(level, predicate) {
+        const match = makeMatcher(level, predicate);
+        if (this.#captured.some(match))
+            return;
+        throw new Error(`logger.assertLogged('${level}'${describePredicate(predicate)}) failed — no captured entry matches.\n${describeCaptured(this.#captured)}`);
+    }
+    assertNotLogged(level, predicate) {
+        const match = makeMatcher(level, predicate);
+        if (!this.#captured.some(match))
+            return;
+        throw new Error(`logger.assertNotLogged('${level}'${describePredicate(predicate)}) failed — at least one captured entry matches.\n${describeCaptured(this.#captured)}`);
+    }
+}
+function makeMatcher(level, predicate) {
+    if (typeof predicate === "function") {
+        return (e) => e.level === level && predicate(e);
+    }
+    if (predicate === undefined) {
+        return (e) => e.level === level;
+    }
+    // Validate the predicate AT CONSTRUCTION, not inside the closure —
+    // Array.some short-circuits on an empty array, so a check inside
+    // the matcher would silently pass when nothing was captured.
+    if (predicate.containing === "") {
+        throw new Error("FakeLogger: `containing` predicate cannot be an empty string — it would match every captured message.");
+    }
+    return (e) => {
+        if (e.level !== level)
+            return false;
+        if (predicate.containing !== undefined &&
+            !e.message.includes(predicate.containing)) {
+            return false;
+        }
+        if (predicate.dataMatches && !predicate.dataMatches(e.data)) {
+            return false;
+        }
+        return true;
+    };
+}
+function describePredicate(predicate) {
+    if (predicate === undefined)
+        return "";
+    if (typeof predicate === "function")
+        return ", <function predicate>";
+    if (Object.keys(predicate).length === 0)
+        return ", <empty predicate (level-only)>";
+    return `, ${safeStringify(predicate)}`;
+}
+function describeCaptured(captured) {
+    if (captured.length === 0)
+        return "Captured: (none)";
+    const lines = captured.map((e, i) => `  [${i}] ${e.level} module="${e.module}" message="${e.message}"`);
+    return `Captured (${captured.length}):\n${lines.join("\n")}`;
+}
+/** `JSON.stringify` with circular-ref + function-field handling.
+ *  Functions render as `<function>`, circular refs as `<circular>`,
+ *  unstringifiable values as `<unstringifiable>` — so an assertion
+ *  failure message never gets eaten by a JSON throw. */
+function safeStringify(value) {
+    const seen = new WeakSet();
+    try {
+        return JSON.stringify(value, (_key, v) => {
+            if (typeof v === "function")
+                return "<function>";
+            if (typeof v === "object" && v !== null) {
+                if (seen.has(v))
+                    return "<circular>";
+                seen.add(v);
+            }
+            return v;
+        });
+    }
+    catch {
+        return "<unstringifiable>";
+    }
+}
+function deepClone(value) {
+    return structuredClone(value);
+}
+//# sourceMappingURL=FakeLogger.js.map

package/dist/testing/FakeLogger.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Spectrum types.
+ * @implements FR54, FR57
+ */
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+export declare const LOG_LEVEL_ORDER: Record<LogLevel, number>;
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    module: string;
+    correlationId?: string;
+    timestamp: string;
+    data?: Record<string, unknown>;
+}
+export interface LogChannel {
+    name: string;
+    write(entry: LogEntry): void;
+}
+export interface LogConfig {
+    level: LogLevel;
+    channels: LogChannel[];
+    /** Per-module log level overrides */
+    modules?: Record<string, LogLevel>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAE/E,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAOpD,CAAC;AAEF,MAAM,WAAW,QAAQ;IACxB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CACnC"}

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * Spectrum types.
+ * @implements FR54, FR57
+ */
+export const LOG_LEVEL_ORDER = {
+    trace: 0,
+    debug: 1,
+    info: 2,
+    warn: 3,
+    error: 4,
+    fatal: 5,
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,CAAC,MAAM,eAAe,GAA6B;IACxD,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;CACR,CAAC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@c9up/spectrum",
+  "version": "0.1.3",
+  "description": "Spectrum — structured logging for the Ream framework",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./provider": {
+      "types": "./dist/SpectrumProvider.d.ts",
+      "import": "./dist/SpectrumProvider.js"
+    },
+    "./services/main": {
+      "types": "./dist/services/main.d.ts",
+      "import": "./dist/services/main.js"
+    },
+    "./configure": {
+      "types": "./dist/configure.d.ts",
+      "import": "./dist/configure.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/FakeLogger.d.ts",
+      "import": "./dist/testing/FakeLogger.js"
+    }
+  },
+  "peerDependencies": {
+    "@c9up/ream": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "@c9up/ream": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/C9up/spectrum.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint": "biome check src/",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}