@momentumcms/logger 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+## 0.1.1 (2026-02-16)
+
+This was a version bump only for logger to align it with other projects, there were no code changes.
+
+## 0.1.0 (2026-02-16)
+
+This was a version bump only for logger to align it with other projects, there were no code changes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Momentum CMS Contributors
+
+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/index.cjs

@@ -0,0 +1,288 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// libs/logger/src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ANSI: () => ANSI,
+  LOG_LEVEL_VALUES: () => LOG_LEVEL_VALUES,
+  MomentumLogger: () => MomentumLogger,
+  colorize: () => colorize,
+  createLogger: () => createLogger,
+  getMomentumLogger: () => getMomentumLogger,
+  initializeMomentumLogger: () => initializeMomentumLogger,
+  jsonFormatter: () => jsonFormatter,
+  prettyFormatter: () => prettyFormatter,
+  resetMomentumLogger: () => resetMomentumLogger,
+  resolveLoggingConfig: () => resolveLoggingConfig,
+  shouldLog: () => shouldLog,
+  supportsColor: () => supportsColor
+});
+module.exports = __toCommonJS(src_exports);
+
+// libs/logger/src/lib/log-level.ts
+var LOG_LEVEL_VALUES = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  fatal: 4,
+  silent: 5
+};
+function shouldLog(messageLevel, configuredLevel) {
+  return LOG_LEVEL_VALUES[messageLevel] >= LOG_LEVEL_VALUES[configuredLevel];
+}
+
+// libs/logger/src/lib/ansi-colors.ts
+var ANSI = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  // Foreground colors
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  magenta: "\x1B[35m",
+  cyan: "\x1B[36m",
+  white: "\x1B[37m",
+  gray: "\x1B[90m",
+  // Background colors
+  bgRed: "\x1B[41m",
+  bgYellow: "\x1B[43m"
+};
+function colorize(text, ...codes) {
+  if (codes.length === 0)
+    return text;
+  return `${codes.join("")}${text}${ANSI.reset}`;
+}
+function supportsColor() {
+  if (process.env["FORCE_COLOR"] === "1")
+    return true;
+  if (process.env["NO_COLOR"] !== void 0)
+    return false;
+  if (process.env["TERM"] === "dumb")
+    return false;
+  return process.stdout.isTTY === true;
+}
+
+// libs/logger/src/lib/formatters.ts
+var LEVEL_COLORS = {
+  debug: [ANSI.dim, ANSI.gray],
+  info: [ANSI.cyan],
+  warn: [ANSI.yellow],
+  error: [ANSI.red],
+  fatal: [ANSI.bold, ANSI.white, ANSI.bgRed]
+};
+function padLevel(level) {
+  return level.toUpperCase().padEnd(5);
+}
+function formatTimestamp(date) {
+  const y = date.getFullYear();
+  const mo = String(date.getMonth() + 1).padStart(2, "0");
+  const d = String(date.getDate()).padStart(2, "0");
+  const h = String(date.getHours()).padStart(2, "0");
+  const mi = String(date.getMinutes()).padStart(2, "0");
+  const s = String(date.getSeconds()).padStart(2, "0");
+  const ms = String(date.getMilliseconds()).padStart(3, "0");
+  return `${y}-${mo}-${d} ${h}:${mi}:${s}.${ms}`;
+}
+function formatData(data) {
+  const entries = Object.entries(data);
+  if (entries.length === 0)
+    return "";
+  return " " + entries.map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`).join(" ");
+}
+function prettyFormatter(entry) {
+  const useColor = supportsColor();
+  const level = entry.level;
+  const ts = formatTimestamp(entry.timestamp);
+  const levelStr = padLevel(entry.level);
+  const ctx = `[${entry.context}]`;
+  const msg = entry.message;
+  const enrichmentStr = entry.enrichments ? formatData(entry.enrichments) : "";
+  const dataStr = entry.data ? formatData(entry.data) : "";
+  const extra = `${enrichmentStr}${dataStr}`;
+  if (useColor) {
+    const colors = LEVEL_COLORS[level];
+    const coloredLevel = colorize(levelStr, ...colors);
+    const coloredCtx = colorize(ctx, ANSI.magenta);
+    const coloredTs = colorize(ts, ANSI.gray);
+    return `${coloredTs} ${coloredLevel} ${coloredCtx} ${msg}${extra}
+`;
+  }
+  return `${ts} ${levelStr} ${ctx} ${msg}${extra}
+`;
+}
+function jsonFormatter(entry) {
+  const output = {
+    timestamp: entry.timestamp.toISOString(),
+    level: entry.level,
+    context: entry.context,
+    message: entry.message
+  };
+  if (entry.enrichments && Object.keys(entry.enrichments).length > 0) {
+    Object.assign(output, entry.enrichments);
+  }
+  if (entry.data && Object.keys(entry.data).length > 0) {
+    output["data"] = entry.data;
+  }
+  return JSON.stringify(output) + "\n";
+}
+
+// libs/logger/src/lib/logger-config.types.ts
+function resolveLoggingConfig(config) {
+  return {
+    level: config?.level ?? "info",
+    format: config?.format ?? "pretty",
+    timestamps: config?.timestamps ?? true,
+    output: config?.output ?? ((msg) => {
+      process.stdout.write(msg);
+    }),
+    errorOutput: config?.errorOutput ?? ((msg) => {
+      process.stderr.write(msg);
+    })
+  };
+}
+
+// libs/logger/src/lib/logger.ts
+var ERROR_LEVELS = /* @__PURE__ */ new Set(["warn", "error", "fatal"]);
+var MomentumLogger = class _MomentumLogger {
+  static {
+    this.enrichers = [];
+  }
+  constructor(context, config) {
+    this.context = context;
+    this.config = isResolvedConfig(config) ? config : resolveLoggingConfig(config);
+    this.formatter = this.config.format === "json" ? jsonFormatter : prettyFormatter;
+  }
+  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);
+  }
+  /**
+   * Creates a child logger with a sub-context.
+   * e.g., `Momentum:DB` → `Momentum:DB:Migrate`
+   */
+  child(subContext) {
+    return new _MomentumLogger(`${this.context}:${subContext}`, this.config);
+  }
+  /**
+   * Registers a global enricher that adds extra fields to all log entries.
+   */
+  static registerEnricher(enricher) {
+    _MomentumLogger.enrichers.push(enricher);
+  }
+  /**
+   * Removes a previously registered enricher.
+   */
+  static removeEnricher(enricher) {
+    const index = _MomentumLogger.enrichers.indexOf(enricher);
+    if (index >= 0) {
+      _MomentumLogger.enrichers.splice(index, 1);
+    }
+  }
+  /**
+   * Clears all registered enrichers. Primarily for testing.
+   */
+  static clearEnrichers() {
+    _MomentumLogger.enrichers.length = 0;
+  }
+  log(level, message, data) {
+    if (!shouldLog(level, this.config.level))
+      return;
+    const enrichments = this.collectEnrichments();
+    const entry = {
+      timestamp: /* @__PURE__ */ new Date(),
+      level,
+      context: this.context,
+      message,
+      data,
+      enrichments: Object.keys(enrichments).length > 0 ? enrichments : void 0
+    };
+    const formatted = this.formatter(entry);
+    if (ERROR_LEVELS.has(level)) {
+      this.config.errorOutput(formatted);
+    } else {
+      this.config.output(formatted);
+    }
+  }
+  collectEnrichments() {
+    const result = {};
+    for (const enricher of _MomentumLogger.enrichers) {
+      Object.assign(result, enricher.enrich());
+    }
+    return result;
+  }
+};
+function isResolvedConfig(config) {
+  if (!config)
+    return false;
+  return typeof config.level === "string" && typeof config.format === "string" && typeof config.timestamps === "boolean" && // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- type guard narrows union
+  typeof config.output === "function" && // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- type guard narrows union
+  typeof config.errorOutput === "function";
+}
+
+// libs/logger/src/lib/logger-singleton.ts
+var loggerInstance = null;
+var ROOT_CONTEXT = "Momentum";
+function initializeMomentumLogger(config) {
+  loggerInstance = new MomentumLogger(ROOT_CONTEXT, config);
+  return loggerInstance;
+}
+function getMomentumLogger() {
+  if (!loggerInstance) {
+    loggerInstance = new MomentumLogger(ROOT_CONTEXT);
+  }
+  return loggerInstance;
+}
+function createLogger(context) {
+  return getMomentumLogger().child(context);
+}
+function resetMomentumLogger() {
+  loggerInstance = null;
+  MomentumLogger.clearEnrichers();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ANSI,
+  LOG_LEVEL_VALUES,
+  MomentumLogger,
+  colorize,
+  createLogger,
+  getMomentumLogger,
+  initializeMomentumLogger,
+  jsonFormatter,
+  prettyFormatter,
+  resetMomentumLogger,
+  resolveLoggingConfig,
+  shouldLog,
+  supportsColor
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@momentumcms/logger",
+  "version": "0.0.1",
+  "description": "Structured logging for Momentum CMS",
+  "license": "MIT",
+  "author": "Momentum CMS Contributors",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/momentum-cms/momentum-cms.git",
+    "directory": "libs/logger"
+  },
+  "homepage": "https://github.com/momentum-cms/momentum-cms#readme",
+  "bugs": {
+    "url": "https://github.com/momentum-cms/momentum-cms/issues"
+  },
+  "keywords": [
+    "cms",
+    "momentum-cms",
+    "logging",
+    "logger"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "commonjs",
+  "main": "./index.cjs",
+  "types": "./src/index.d.ts",
+  "dependencies": {}
+}

package/src/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @momentumcms/logger
+ *
+ * Colorful, configurable logging engine for Momentum CMS.
+ * Built from scratch with ANSI color support, log levels, and child loggers.
+ */
+export { MomentumLogger, type LogEnricher } from './lib/logger';
+export { initializeMomentumLogger, getMomentumLogger, resetMomentumLogger, createLogger, } from './lib/logger-singleton';
+export { type LogLevel, shouldLog, LOG_LEVEL_VALUES } from './lib/log-level';
+export { type LoggingConfig, type LogFormat, type ResolvedLoggingConfig, resolveLoggingConfig, } from './lib/logger-config.types';
+export { type LogEntry, type LogFormatter, prettyFormatter, jsonFormatter } from './lib/formatters';
+export { ANSI, colorize, supportsColor } from './lib/ansi-colors';

package/src/lib/ansi-colors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ANSI escape codes for colorful terminal output.
+ * Built from scratch — no external dependencies.
+ */
+export declare const ANSI: {
+    readonly reset: "\u001B[0m";
+    readonly bold: "\u001B[1m";
+    readonly dim: "\u001B[2m";
+    readonly red: "\u001B[31m";
+    readonly green: "\u001B[32m";
+    readonly yellow: "\u001B[33m";
+    readonly blue: "\u001B[34m";
+    readonly magenta: "\u001B[35m";
+    readonly cyan: "\u001B[36m";
+    readonly white: "\u001B[37m";
+    readonly gray: "\u001B[90m";
+    readonly bgRed: "\u001B[41m";
+    readonly bgYellow: "\u001B[43m";
+};
+/**
+ * Wraps text with ANSI escape codes and a reset suffix.
+ */
+export declare function colorize(text: string, ...codes: string[]): string;
+/**
+ * Checks if the current environment supports color output.
+ * Respects NO_COLOR and FORCE_COLOR environment variables.
+ */
+export declare function supportsColor(): boolean;

package/src/lib/formatters.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Log entry formatters for pretty (colorful) and JSON output.
+ */
+import type { LogLevel } from './log-level';
+export interface LogEntry {
+    timestamp: Date;
+    level: LogLevel;
+    context: string;
+    message: string;
+    data?: Record<string, unknown>;
+    enrichments?: Record<string, unknown>;
+}
+export type LogFormatter = (entry: LogEntry) => string;
+/**
+ * Pretty formatter with colorful aligned output.
+ *
+ * Output: `2026-02-07 10:23:45.123  INFO  [Momentum:DB] Message here`
+ */
+export declare function prettyFormatter(entry: LogEntry): string;
+/**
+ * JSON formatter for structured logging.
+ *
+ * Output: `{"timestamp":"...","level":"info","context":"Momentum:DB","message":"..."}`
+ */
+export declare function jsonFormatter(entry: LogEntry): string;

package/src/lib/log-level.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Log level definitions and utilities.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
+export declare const LOG_LEVEL_VALUES: Readonly<Record<LogLevel, number>>;
+/**
+ * Determines if a message at the given level should be logged
+ * based on the configured minimum level.
+ */
+export declare function shouldLog(messageLevel: LogLevel, configuredLevel: LogLevel): boolean;

package/src/lib/logger-config.types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Logger configuration types.
+ */
+import type { LogLevel } from './log-level';
+export type LogFormat = 'pretty' | 'json';
+export interface LoggingConfig {
+    /** Minimum log level. @default 'info' */
+    level?: LogLevel;
+    /** Output format. @default 'pretty' */
+    format?: LogFormat;
+    /** Whether to include timestamps. @default true */
+    timestamps?: boolean;
+    /** Custom output function for debug/info (defaults to process.stdout.write) */
+    output?: (message: string) => void;
+    /** Custom error output function for warn/error/fatal (defaults to process.stderr.write) */
+    errorOutput?: (message: string) => void;
+}
+export interface ResolvedLoggingConfig {
+    level: LogLevel;
+    format: LogFormat;
+    timestamps: boolean;
+    output: (message: string) => void;
+    errorOutput: (message: string) => void;
+}
+/**
+ * Resolves logging config with defaults applied.
+ */
+export declare function resolveLoggingConfig(config?: LoggingConfig): ResolvedLoggingConfig;

package/src/lib/logger-singleton.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Logger singleton management.
+ *
+ * Mirrors the MomentumAPI singleton pattern from momentum-api.ts.
+ */
+import type { LoggingConfig } from './logger-config.types';
+import { MomentumLogger } from './logger';
+/**
+ * Initialize the global Momentum logger.
+ * Should be called once during server startup.
+ *
+ * @returns The root logger instance
+ */
+export declare function initializeMomentumLogger(config?: LoggingConfig): MomentumLogger;
+/**
+ * Get the initialized root logger.
+ * Falls back to a default logger if not initialized (for use before init).
+ */
+export declare function getMomentumLogger(): MomentumLogger;
+/**
+ * Creates a child logger with a named context.
+ * e.g., `createLogger('DB')` → logger with context `Momentum:DB`
+ *
+ * This is the primary way to get a logger in library code.
+ */
+export declare function createLogger(context: string): MomentumLogger;
+/**
+ * Reset the logger singleton. Primarily for testing.
+ */
+export declare function resetMomentumLogger(): void;

package/src/lib/logger.d.ts

@@ -0,0 +1,45 @@
+/**
+ * MomentumLogger — the core logging class.
+ *
+ * Supports log levels, child loggers, and enrichers.
+ * Uses process.stdout/stderr directly (ESLint no-console compliant).
+ */
+import type { LoggingConfig, ResolvedLoggingConfig } from './logger-config.types';
+/**
+ * Interface for enriching log entries with additional context.
+ * Used by plugins (e.g., OTel) to inject trace IDs into log output.
+ */
+export interface LogEnricher {
+    enrich(): Record<string, unknown>;
+}
+export declare class MomentumLogger {
+    private static enrichers;
+    readonly context: string;
+    private readonly config;
+    private readonly formatter;
+    constructor(context: string, config?: LoggingConfig | ResolvedLoggingConfig);
+    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;
+    /**
+     * Creates a child logger with a sub-context.
+     * e.g., `Momentum:DB` → `Momentum:DB:Migrate`
+     */
+    child(subContext: string): MomentumLogger;
+    /**
+     * Registers a global enricher that adds extra fields to all log entries.
+     */
+    static registerEnricher(enricher: LogEnricher): void;
+    /**
+     * Removes a previously registered enricher.
+     */
+    static removeEnricher(enricher: LogEnricher): void;
+    /**
+     * Clears all registered enrichers. Primarily for testing.
+     */
+    static clearEnrichers(): void;
+    private log;
+    private collectEnrichments;
+}