@maestro-js/log 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,316 @@
+# @maestro-js/log
+
+Structured logging with pluggable transports and channel-based routing. Messages have a severity level (`emergency`, `error`, `warn`, `info`) and an optional channel for routing to specific transports.
+
+## Quick Setup
+
+```ts
+import { Log } from '@maestro-js/log'
+
+// Use the default logger directly (falls back to console if no transports added)
+Log.info('Server started on port', 3000)
+
+// Or create an independent logger with transports
+const logger = Log.create({
+  transports: [
+    Log.transports.console(),
+    Log.transports.file({ filename: '/var/log/app.log' })
+  ]
+})
+
+logger.info('Server started on port', 3000)
+logger.error('Connection failed', err)
+```
+
+## Architecture
+
+The package does NOT use the service-registry Provider pattern. Instead it exports a `Log` object that acts as a default logger facade and a `Log.create()` factory for independent logger instances.
+
+### Source Files
+
+- `packages/log/src/index.ts` -- Main entry: `Log.create()`, default logger facade, `Log.transports` namespace
+- `packages/log/src/log-types.ts` -- Core types: `LogLevel`, `LogChannel`, `LogMessage`, `LogTransport`, `LogMessageFilter`, `LogFormatter`
+- `packages/log/src/console-transport.ts` -- Console transport with colorized output
+- `packages/log/src/file-transport.ts` -- File transport with streaming writes and `flush()`
+- `packages/log/src/sentry-transport.ts` -- Sentry error/message capture transport
+- `packages/log/src/sentry-breadcrumbs-transport.ts` -- Sentry breadcrumbs transport
+- `packages/log/src/stub-transport.ts` -- In-memory transport for testing
+- `packages/log/src/transport-helpers.ts` -- `parseLogMessageFilter()` utility
+
+### Key Types
+
+```ts
+type LogLevel = 'emergency' | 'error' | 'warn' | 'info'
+type LogChannel = string | null
+
+interface LogMessage<LogMessageData extends any[] = any[]> {
+  data: LogMessageData
+  level: LogLevel
+  channel: LogChannel
+  time: Iso.Instant
+}
+
+interface LogTransport<LogMessageData extends any[] = any[]> {
+  write(message: LogMessage<LogMessageData>): void
+}
+
+type LogMessageFilter<LogMessageData extends any[] = any[]> =
+  | { level?: LogLevel | LogLevel[]; channel?: LogChannel | LogChannel[] }
+  | ((message: LogMessage<LogMessageData>) => boolean)
+  | undefined
+```
+
+## Transports
+
+All transports accept an optional `filter` for level/channel-based routing.
+
+### Console Transport
+
+Colorized output to stdout with configurable formatting.
+
+```ts
+Log.transports.console()
+Log.transports.console({ filter: { level: ['error', 'emergency'] } })
+Log.transports.console({ format: (message) => `${message.level}: ${message.data.join(' ')}\n` })
+// Pass InspectOptions instead of a formatter function
+Log.transports.console({ format: { colors: true, depth: 4 } })
+```
+
+### File Transport
+
+Appends log messages to a file via streaming. Creates the directory if it does not exist. Returns a transport with an additional `flush()` method.
+
+```ts
+const fileTransport = Log.transports.file({
+  filename: '/var/log/app.log',
+  filter: { level: ['error', 'emergency'] },
+  format: (message) => JSON.stringify(message) + '\n'
+})
+
+// Ensure all buffered writes are flushed to disk
+await fileTransport.flush()
+```
+
+### Sentry Transport
+
+Captures errors and messages to Sentry. Errors at `error`/`emergency` level use `captureException`; other levels use `captureMessage`.
+
+```ts
+import * as Sentry from '@sentry/node'
+
+Log.transports.sentry({
+  sentry: Sentry,
+  filter: { level: ['error', 'emergency'] },
+  getCaptureContext(message) {
+    return {
+      tags: { channel: message.channel ?? 'default' },
+      extra: {},
+      level: message.level === 'emergency' ? 'fatal' : message.level
+    }
+  }
+})
+```
+
+### Sentry Breadcrumbs Transport
+
+Adds log messages as Sentry breadcrumbs for context on future error captures.
+
+```ts
+import * as Sentry from '@sentry/node'
+
+Log.transports.sentryBreadcrumbs({
+  sentry: Sentry,
+  filter: { level: ['info', 'warn'] }
+})
+```
+
+### Stub Transport
+
+In-memory transport for testing. Captures messages and provides `listMessages()` and `reset()`.
+
+```ts
+const stub = Log.transports.stub()
+const logger = Log.create({ transports: [stub] })
+
+logger.info('test message')
+stub.listMessages() // => [{ data: ['test message'], level: 'info', channel: null, time: '...' }]
+stub.reset()
+```
+
+### Silence Transport
+
+Suppresses all output. Use to disable logging entirely.
+
+```ts
+Log.addTransport(Log.transports.silence)
+```
+
+## API Reference
+
+### `Log.create(config?)`
+
+Create an independent logger instance.
+
+```ts
+const logger = Log.create({
+  transports: [Log.transports.console()]
+})
+```
+
+### Default Logger Facade
+
+Call logging methods directly on `Log` without creating an instance.
+
+```ts
+Log.addTransport(Log.transports.console())
+Log.info('message', data)
+Log.warn('slow query', { durationMs: 500 })
+Log.error('failed', new Error('timeout'))
+Log.emergency('system down')
+Log.removeTransport(someTransport)
+```
+
+### Logging Methods
+
+- `info(...data)` -- Log at info level
+- `warn(...data)` -- Log at warn level
+- `error(...data)` -- Log at error level
+- `emergency(...data)` -- Log at emergency level
+- `write(message)` -- Write a raw log message (supply `level`, `data`, and `time` yourself)
+
+### Channels
+
+Create channel-scoped sub-loggers that tag every message with a channel name. Transports can filter by channel.
+
+```ts
+const logger = Log.create({ transports: [Log.transports.console()] })
+const dbLog = logger.channel('database')
+dbLog.info('Query executed', { table: 'users', durationMs: 12 })
+dbLog.warn('Slow query detected')
+
+// Filter transport to only receive database channel messages
+Log.transports.console({ filter: { channel: 'database' } })
+```
+
+### `Log.overrideNodeJsConsole(logger)`
+
+Replace global `console.log`, `console.warn`, `console.error`, `console.info`, and `console.debug` with methods from the provided logger. Returns a restore function.
+
+```ts
+const restore = Log.overrideNodeJsConsole(logger)
+console.log('now goes through logger')
+restore() // restores original console methods
+```
+
+## Filtering
+
+Transports accept a `filter` option that controls which messages reach them.
+
+```ts
+// Filter by level
+Log.transports.console({ filter: { level: 'error' } })
+Log.transports.console({ filter: { level: ['error', 'emergency'] } })
+
+// Filter by channel
+Log.transports.console({ filter: { channel: 'database' } })
+
+// Filter by both level and channel
+Log.transports.console({ filter: { level: 'error', channel: 'database' } })
+
+// Custom filter function
+Log.transports.console({
+  filter: (message) => message.level === 'error' && message.data.some((d) => d instanceof Error)
+})
+```
+
+## Fallback Behavior
+
+When a logger has no transports registered, it falls back to a default `ConsoleTransport()`. Add `Log.transports.silence` to explicitly suppress all output.
+
+## Custom Transports
+
+Implement the `LogTransport` interface.
+
+```ts
+const customTransport: Log.Transport = {
+  write(message) {
+    // message.data, message.level, message.channel, message.time
+    fetch('https://log-service.example.com', {
+      method: 'POST',
+      body: JSON.stringify(message)
+    })
+  }
+}
+```
+
+## Testing
+
+Run tests:
+
+```bash
+pnpm --filter @maestro-js/log test
+cd packages/log && npx beartest ./tests/log.test.ts
+```
+
+Use `StubTransport` to capture and assert on log output:
+
+```ts
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+import { Log } from '@maestro-js/log'
+
+test('should capture log messages', () => {
+  const stub = Log.transports.stub()
+  const logger = Log.create({ transports: [stub] })
+
+  logger.info('test')
+
+  const messages = stub.listMessages()
+  expect(messages).toHaveLength(1)
+  expect(messages[0].level).toBe('info')
+  expect(messages[0].data).toEqual(['test'])
+
+  stub.reset()
+})
+```
+
+Use inline transports for targeted assertions:
+
+```ts
+test('should write to transport', () => {
+  const messages: Log.Message[] = []
+  const log = Log.create()
+  log.addTransport({ write(message) { messages.push(message) } })
+
+  log.info('log')
+  expect(messages).toHaveLength(1)
+})
+```
+
+## Cross-Package Integration
+
+Log is used widely across Maestro packages as the standard logging mechanism:
+
+- **queue, recurring-jobs, mail** -- Log job processing, email sending, and scheduling events
+- **db** -- Log queries and connection events
+- **cache, events, broadcast** -- Log cache operations and event dispatching
+- **metrics, exceptions** -- Log metric collection and exception handling
+
+Typical integration pattern in other packages:
+
+```ts
+import { Log } from '@maestro-js/log'
+
+const log = Log.create()
+// or use Log.info(), Log.error() directly via the default facade
+```
+
+### Context Integration
+
+Combine with `@maestro-js/context` (AsyncLocalStorage) for request-scoped logging by passing contextual data through log message data arguments.
+
+## Dependencies
+
+- `colorette` -- Terminal color support for console transport
+- `iso-fns2` -- ISO timestamp types (`Iso.Instant`)
+- `@sentry/types` (devDependency) -- Sentry type definitions

package/dist/index.d.ts

@@ -0,0 +1,221 @@
+import { Iso } from 'iso-fns2';
+import { InspectOptions } from 'node:util';
+
+type LogLevel = 'emergency' | 'error' | 'warn' | 'info';
+type LogChannel = string | null;
+type LogFormatter<LogMessageData extends any[] = any[]> = (message: LogMessage<LogMessageData>) => string;
+interface LogMessage<LogMessageData extends any[] = any[]> {
+    data: LogMessageData;
+    level: LogLevel;
+    channel: LogChannel;
+    time: Iso.Instant;
+}
+type LogMessageFilter<LogMessageData extends any[] = any[]> = {
+    level?: LogLevel | LogLevel[] | undefined;
+    channel?: LogChannel | LogChannel[] | undefined;
+} | ((message: LogMessage<LogMessageData>) => boolean) | undefined;
+interface LogTransport<LogMessageData extends any[] = any[]> {
+    write(message: LogMessage<LogMessageData>): void;
+}
+interface LogFunctions<LogMessageData extends any[] = any[]> {
+    write(message: Omit<LogMessage<LogMessageData>, 'channel'>): void;
+    info(...data: LogMessageData): void;
+    warn(...data: LogMessageData): void;
+    error(...data: LogMessageData): void;
+    emergency(...data: LogMessageData): void;
+}
+
+declare function ConsoleTransport<LogMessageData extends any[] = any[]>(options?: {
+    filter?: LogMessageFilter<LogMessageData>;
+    format?: LogFormatter<LogMessageData> | InspectOptions;
+}): LogTransport<LogMessageData>;
+
+declare function FileTransport<LogMessageData extends any[] = any[]>(options: {
+    filter?: LogMessageFilter<LogMessageData>;
+    format?: LogFormatter<LogMessageData>;
+    filename: string;
+}): {
+    flush(): Promise<void>;
+    write(message: LogMessage<LogMessageData>): void;
+};
+
+type Primitive = number | string | boolean | bigint | symbol | null | undefined;
+interface SentryCaptureContext {
+    tags: {
+        [key: string]: Primitive;
+    };
+    extra: Record<string, unknown>;
+    level?: 'fatal' | 'error' | 'warning' | 'log' | 'info' | 'debug';
+}
+declare function SentryTransport<LogMessageData extends any[] = any[]>(options: {
+    filter?: LogMessageFilter<LogMessageData>;
+    sentry: {
+        captureException(exception: any, context: SentryCaptureContext): unknown;
+        captureMessage(message: string, context: SentryCaptureContext): unknown;
+    };
+    getCaptureContext(message: LogMessage): SentryCaptureContext;
+}): LogTransport<LogMessageData>;
+
+declare function SentryBreadcrumbsTransport<LogMessageData extends any[] = any[]>(options: {
+    filter?: LogMessageFilter<LogMessageData>;
+    sentry: {
+        addBreadcrumb(breadcrumb: {
+            level?: 'fatal' | 'error' | 'warning' | 'log' | 'info' | 'debug';
+            category?: string;
+            message?: string;
+            data?: {
+                [key: string]: any;
+            };
+            timestamp?: number;
+        }): void;
+    };
+}): LogTransport<LogMessageData>;
+
+declare function StubTransport<LogMessageData extends any[] = any[]>(options?: {
+    filter?: LogMessageFilter<LogMessageData>;
+    transform?: (message: LogMessage<LogMessageData>) => LogMessage<LogMessageData>;
+}): {
+    write(message: LogMessage<LogMessageData>): void;
+    reset(): void;
+    listMessages(): LogMessage<LogMessageData>[];
+};
+
+/**
+ * Creates a new logger. By default loggers have no transports
+ */
+declare function create<LoggerMessageData extends any[] = any>(config?: Log.Config<LoggerMessageData>): Log.Logger<LoggerMessageData>;
+/**
+ * Monkey patches the default console methods with methods
+ * from the supplied logger. Returns a function that restores
+ * the original console methods.
+ */
+declare function overrideNodeJsConsole(logger: LogFunctions): () => void;
+/**
+ * Structured logging with pluggable transports and channel-based routing.
+ *
+ * Log messages have a severity {@link Log.Level level} (`emergency`, `error`,
+ * `warn`, `info`) and an optional {@link Log.Channel channel} for routing.
+ * {@link Log.Transport Transports} move messages from the logger to their
+ * final destination — stdout, a file, Sentry, Slack, etc.
+ *
+ * If no transports are registered the logger falls back to console output.
+ * Add the built-in `Log.transports.silence` transport to suppress output
+ * entirely.
+ *
+ * @example
+ * ```ts
+ * import { Log } from '@maestro-js/log'
+ *
+ * // Create a logger with transports
+ * const logger = Log.create({
+ *   transports: [
+ *     Log.transports.console(),
+ *     Log.transports.file({ filename: '/var/log/app.log' })
+ *   ]
+ * })
+ *
+ * // Log at different levels
+ * logger.info('Server started on port', 3000)
+ * logger.error('Connection failed', err)
+ *
+ * // Route messages through a named channel
+ * const db = logger.channel('database')
+ * db.warn('Slow query detected', query)
+ *
+ * // Or use the default facade directly
+ * Log.addTransport(Log.transports.console())
+ * Log.info('Hello from the default logger')
+ * ```
+ */
+declare namespace Log {
+    /** Configuration options passed to {@link Log.create}. */
+    interface Config<LoggerMessageData extends any[] = any> {
+        transports?: Log.Transport<LoggerMessageData>[];
+    }
+    /**
+     * Full logger instance returned by {@link Log.create}.
+     *
+     * Extends {@link Log.LogFunctions} with transport management and the
+     * ability to create channel-scoped sub-loggers.
+     *
+     * @example
+     * ```ts
+     * const logger = Log.create()
+     * logger.addTransport(Log.transports.console())
+     * const dbLog = logger.channel('database')
+     * dbLog.info('Query executed', { table: 'users', durationMs: 12 })
+     * ```
+     */
+    interface Logger<LogMessageData extends any[] = any[]> extends Log.LogFunctions<LogMessageData> {
+        /** Appends one or more transports to this logger. */
+        addTransport(...transport: Log.Transport<LogMessageData>[]): void;
+        /** Removes one or more previously added transports. */
+        removeTransport(...transport: Log.Transport<LogMessageData>[]): void;
+        /** Return a channel-scoped subset of logging methods that tag every message with `channel`. */
+        channel<ChannelMessageData extends LogMessageData = LogMessageData>(channel: LogChannel): Log.LogFunctions<ChannelMessageData>;
+    }
+    /**
+     * Channel-scoped subset of logging methods.
+     *
+     * Returned by {@link Log.Logger.channel} and also the base shape of every
+     * {@link Log.Logger}.
+     *
+     * @example
+     * ```ts
+     * const logger = Log.create({ transports: [Log.transports.console()] })
+     * logger.info('Server started on port', 3000)
+     * logger.warn('Disk usage high', { usedPct: 83 })
+     * logger.error('Payment failed', new Error('Timeout'))
+     * ```
+     */
+    interface LogFunctions<LogMessageData extends any[] = any[]> {
+        /** Write a raw log message (you must supply `level` and `data` yourself). */
+        write(message: Omit<LogMessage<LogMessageData>, 'channel'>): void;
+        /** Log at `info` level. */
+        info(...data: LogMessageData): void;
+        /** Log at `warn` level. */
+        warn(...data: LogMessageData): void;
+        /** Log at `error` level. */
+        error(...data: LogMessageData): void;
+        /** Log at `emergency` level. */
+        emergency(...data: LogMessageData): void;
+    }
+    /** Named scope that tags log messages for transport filtering. */
+    type Channel = LogChannel;
+    /** Converts a {@link Log.Message} into a string for output. */
+    type Formatter<LogMessageData extends any[] = any[]> = LogFormatter<LogMessageData>;
+    /** Severity level for log messages, from most to least critical: `emergency`, `error`, `warn`, `info`. */
+    type Level = LogLevel;
+    /** Structured log entry passed to every {@link Log.Transport}. */
+    type Message<LogMessageData extends any[] = any[]> = LogMessage<LogMessageData>;
+    /** Predicate or descriptor that controls which messages reach a {@link Log.Transport}. */
+    type MessageFilter<LogMessageData extends any[] = any[]> = LogMessageFilter<LogMessageData>;
+    /** Destination that receives {@link Log.Message messages} from a logger. */
+    type Transport<LogMessageData extends any[] = any[]> = LogTransport<LogMessageData>;
+}
+/**
+ * Structured logging with pluggable transports.
+ * Use `Log.create()` for an independent logger, or call methods directly on the default instance.
+ */
+declare const Log: {
+    create: typeof create;
+    overrideNodeJsConsole: typeof overrideNodeJsConsole;
+    write: (message: Omit<LogMessage<any>, "channel">) => void;
+    info: (...data: any) => void;
+    warn: (...data: any) => void;
+    error: (...data: any) => void;
+    emergency: (...data: any) => void;
+    addTransport: (...transport: Log.Transport<any>[]) => void;
+    removeTransport: (...transport: Log.Transport<any>[]) => void;
+    channel: <ChannelMessageData extends any = any>(channel: LogChannel) => Log.LogFunctions<ChannelMessageData>;
+    transports: {
+        console: typeof ConsoleTransport;
+        file: typeof FileTransport;
+        sentry: typeof SentryTransport;
+        sentryBreadcrumbs: typeof SentryBreadcrumbsTransport;
+        silence: LogTransport<any[]>;
+        stub: typeof StubTransport;
+    };
+};
+
+export { Log };

package/dist/index.js

@@ -0,0 +1,337 @@
+// src/transport-helpers.ts
+var alwaysTrue = () => true;
+function parseLogMessageFilter(filter) {
+  if (filter === void 0) {
+    return alwaysTrue;
+  } else if (typeof filter === "function") {
+    return filter;
+  } else {
+    const levelSet = new Set(Array.isArray(filter.level) ? filter.level : [filter.level]);
+    const levelMatch = filter.level === void 0 ? alwaysTrue : (level) => levelSet.has(level);
+    const channelSet = new Set(Array.isArray(filter.channel) ? filter.channel : [filter.channel]);
+    const channelMatch = filter.channel === void 0 ? alwaysTrue : (channel) => channelSet.has(channel);
+    return (message) => levelMatch(message.level) && channelMatch(message.channel);
+  }
+}
+
+// src/console-transport.ts
+import { formatWithOptions } from "util";
+import { isColorSupported, red, green, yellow, bgRed } from "colorette";
+function ConsoleTransport(options) {
+  const { filter: filterRaw, format: formatRaw } = options ?? {};
+  const filter = parseLogMessageFilter(filterRaw);
+  const format2 = typeof formatRaw === "function" ? formatRaw : (message) => defaultFormatter(message, formatRaw);
+  return {
+    write(message) {
+      if (filter(message)) {
+        process.stdout.write(format2(message));
+      }
+    }
+  };
+}
+function colorizeLevel(level, colorize) {
+  if (!colorize) {
+    return level.toUpperCase();
+  } else if (level === "emergency") {
+    return bgRed(level.toUpperCase());
+  } else if (level === "error") {
+    return red(level.toUpperCase());
+  } else if (level === "warn") {
+    return yellow(level.toUpperCase());
+  } else if (level === "info") {
+    return green(level.toUpperCase());
+  }
+}
+function formatTime(date) {
+  return `${date.getHours().toString().padStart(2, "0")}:${date.getMinutes().toString().padStart(2, "0")}:${date.getSeconds().toString().padStart(2, "0")}.${date.getMilliseconds().toString().padStart(3, "0")}`;
+}
+function defaultFormatter(message, options = {}) {
+  const inColor = options?.colors ?? isColorSupported;
+  const inspectOptions = { ...options, colors: inColor };
+  return `[${formatTime(new Date(message.time))}] ${colorizeLevel(message.level, inColor)}: ${formatWithOptions(
+    inspectOptions,
+    ...Array.isArray(message.data) ? message.data : [message.data]
+  )}
+`;
+}
+
+// src/file-transport.ts
+import fs from "fs";
+import path from "path";
+import { Transform } from "stream";
+import util from "util";
+function FileTransport(options) {
+  function defaultFormatter2(message) {
+    return logMessageToString(message) + "\n";
+  }
+  const { filter: filterRaw, format: format2 = defaultFormatter2, filename } = options ?? {};
+  const folder = path.parse(filename).dir;
+  try {
+    fs.mkdirSync(folder);
+  } catch (e) {
+    if (e.code !== "EEXIST") {
+      throw e;
+    }
+  }
+  const fileStream = fs.createWriteStream(filename, { flags: "a" });
+  const filter = parseLogMessageFilter(filterRaw);
+  const noContent = Buffer.alloc(0);
+  const stream = new Transform({
+    objectMode: true,
+    transform(message, encoding, callback) {
+      if (filter(message)) {
+        callback(null, format2(message));
+      } else {
+        callback(null, noContent);
+      }
+    }
+  });
+  stream.pipe(fileStream);
+  const transport = {
+    write(message) {
+      stream.write(message, void 0);
+    }
+  };
+  return {
+    ...transport,
+    async flush() {
+      await new Promise((resolve) => {
+        if (stream.destroyed) {
+          resolve();
+          return;
+        }
+        if (stream.writableNeedDrain) {
+          stream.once("drain", resolve);
+        } else {
+          resolve();
+        }
+      });
+      await new Promise((resolve) => {
+        if (fileStream.destroyed) {
+          resolve();
+          return;
+        }
+        if (fileStream.writableNeedDrain) {
+          fileStream.once("drain", resolve);
+        } else {
+          resolve();
+        }
+      });
+    }
+  };
+}
+function logMessageToString(obj) {
+  try {
+    return JSON.stringify(obj);
+  } catch {
+    return util.formatWithOptions({ compact: true, breakLength: Infinity, depth: Infinity }, obj);
+  }
+}
+
+// src/sentry-transport.ts
+import { format } from "util";
+function SentryTransport(options) {
+  const { filter: filterRaw, sentry, getCaptureContext } = options ?? {};
+  const filter = parseLogMessageFilter(filterRaw);
+  return {
+    write(message) {
+      if (filter(message)) {
+        if (message.level === "error" || message.level === "emergency") {
+          const exception = message.data.find((d) => d instanceof Error) ?? new Error(format(...message.data));
+          sentry.captureException(exception, getCaptureContext(message));
+        } else {
+          sentry.captureMessage(format(...message.data), getCaptureContext(message));
+        }
+      }
+    }
+  };
+}
+
+// src/sentry-breadcrumbs-transport.ts
+import util2 from "util";
+function SentryBreadcrumbsTransport(options) {
+  const { filter: filterRaw, sentry } = options ?? {};
+  const filter = parseLogMessageFilter(filterRaw);
+  return {
+    write(message) {
+      if (filter(message)) {
+        sentry.addBreadcrumb({
+          level: message.level === "emergency" ? "fatal" : message.level === "error" ? "error" : message.level === "warn" ? "warning" : "info",
+          category: message.channel ?? void 0,
+          message: message.data.length ? util2.format(...message.data) : void 0,
+          data: message.data.find((d) => d !== null && typeof d === "object" && !(d instanceof Error)),
+          timestamp: Math.floor(new Date(message.time).getTime() / 1e3)
+        });
+      }
+    }
+  };
+}
+
+// src/stub-transport.ts
+function StubTransport(options) {
+  const { filter: filterRaw } = options ?? {};
+  const transform = options?.transform ?? ((a) => a);
+  const filter = parseLogMessageFilter(filterRaw);
+  let messages = [];
+  return {
+    write(message) {
+      if (filter(message)) {
+        messages.push(transform(message));
+      }
+    },
+    reset() {
+      messages = [];
+    },
+    listMessages() {
+      return messages;
+    }
+  };
+}
+
+// src/index.ts
+var defaultConsoleTransport = ConsoleTransport();
+function create(config) {
+  let transports = [...config?.transports ?? []];
+  function write(message) {
+    try {
+      if (transports.length) {
+        transports.forEach((t) => t.write({ ...message, channel: null }));
+      } else {
+        defaultConsoleTransport.write({ ...message, channel: null });
+      }
+    } catch (e) {
+      process.stderr.write(Buffer.from(`Failed to log message. ${(e instanceof Error ? e : new Error()).stack}`).toString());
+    }
+  }
+  function writeHelper(messageRaw) {
+    const message = { ...messageRaw, time: (/* @__PURE__ */ new Date()).toISOString() };
+    write(message);
+  }
+  function addTransport(...transportToAdd) {
+    transports = [...transports, ...transportToAdd];
+  }
+  function removeTransport(...transportToRemove) {
+    transports = transports.filter((t) => !transportToRemove.includes(t));
+  }
+  function info(...data) {
+    writeHelper({
+      data,
+      level: "info",
+      channel: null
+    });
+  }
+  function warn(...data) {
+    writeHelper({
+      data,
+      level: "warn",
+      channel: null
+    });
+  }
+  function error(...data) {
+    writeHelper({
+      data,
+      level: "error",
+      channel: null
+    });
+  }
+  function emergency(...data) {
+    writeHelper({
+      data,
+      level: "emergency",
+      channel: null
+    });
+  }
+  function channel(channel2) {
+    function write2(message) {
+      try {
+        if (transports.length) {
+          transports.forEach((t) => t.write({ ...message, channel: channel2 }));
+        } else {
+          defaultConsoleTransport.write({ ...message, channel: channel2 });
+        }
+      } catch (e) {
+        process.stderr.write(
+          Buffer.from(`Failed to log message. ${(e instanceof Error ? e : new Error()).stack}`).toString()
+        );
+      }
+    }
+    function writeHelper2(messageRaw) {
+      const message = { ...messageRaw, time: (/* @__PURE__ */ new Date()).toISOString() };
+      write2(message);
+    }
+    function info2(...data) {
+      writeHelper2({
+        data,
+        level: "info"
+      });
+    }
+    function warn2(...data) {
+      writeHelper2({
+        data,
+        level: "warn"
+      });
+    }
+    function error2(...data) {
+      writeHelper2({
+        data,
+        level: "error"
+      });
+    }
+    function emergency2(...data) {
+      writeHelper2({
+        data,
+        level: "emergency"
+      });
+    }
+    return { info: info2, warn: warn2, error: error2, emergency: emergency2, write: write2 };
+  }
+  return { info, warn, error, emergency, write, channel, addTransport, removeTransport };
+}
+function overrideNodeJsConsole(logger) {
+  const original = {
+    debug: console.debug,
+    log: console.log,
+    info: console.info,
+    warn: console.warn,
+    error: console.error
+  };
+  console.debug = logger.info;
+  console.log = logger.info;
+  console.info = logger.info;
+  console.warn = logger.warn;
+  console.error = logger.error;
+  return function restoreNodeJsConsole() {
+    console.debug = original.debug;
+    console.log = original.log;
+    console.info = original.info;
+    console.warn = original.warn;
+    console.error = original.error;
+  };
+}
+var defaultLogger = create();
+var Log = {
+  create,
+  overrideNodeJsConsole,
+  write: defaultLogger.write,
+  info: defaultLogger.info,
+  warn: defaultLogger.warn,
+  error: defaultLogger.error,
+  emergency: defaultLogger.emergency,
+  addTransport: defaultLogger.addTransport,
+  removeTransport: defaultLogger.removeTransport,
+  channel: defaultLogger.channel,
+  transports: {
+    console: ConsoleTransport,
+    file: FileTransport,
+    sentry: SentryTransport,
+    sentryBreadcrumbs: SentryBreadcrumbsTransport,
+    silence: {
+      write() {
+      }
+    },
+    stub: StubTransport
+  }
+};
+export {
+  Log
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@maestro-js/log",
+  "description": "Structured logging with pluggable transports and channel-based routing for the Maestro framework. Use when working with @maestro-js/log, adding or modifying log transports, configuring log channels, filtering log messages by level or channel, integrating logging into other packages, or writing tests that capture log output. Key capabilities: create loggers with pluggable transports (console, file, Sentry, stub), route messages through named channels, filter by level and channel, override Node.js console, custom formatters, and the silence transport for suppressing output.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "colorette": "^2.0.20",
+    "iso-fns2": "npm:iso-fns@2.0.0-alpha.26"
+  },
+  "devDependencies": {
+    "@sentry/types": "^8.30.0",
+    "@types/node": "^22.19.11"
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "beartest ./tests/**/*",
+    "format": "prettier --write src/ tests/",
+    "lint": "prettier --check src/ tests/"
+  }
+}