@outfitter/logging 0.3.0 → 0.4.0

package/README.md

@@ -193,8 +193,21 @@ const logger = createLogger({
   name: "app",
   sinks: [createConsoleSink()],
 });
+
+// Use JSON formatting instead of the default pretty formatter
+const jsonLogger = createLogger({
+  name: "app",
+  sinks: [createConsoleSink({ formatter: createJsonFormatter() })],
+});
 ```
 
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `colors` | `boolean` | auto-detect | Enable ANSI colors |
+| `formatter` | `Formatter` | `createPrettyFormatter()` | Custom log formatter |
+
 ### File Sink
 
 Buffered writes to a file path:
@@ -310,6 +323,8 @@ process.exit(0);
 
 Resolve the log level from environment configuration. Use this instead of hardcoding levels so your app responds to `OUTFITTER_ENV` and `OUTFITTER_LOG_LEVEL` automatically.
 
+Accepts `LogLevel` or a plain `string` — useful when forwarding CLI flags or MCP values without casting. Invalid strings are ignored and fall through to the next precedence level.
+
 **Precedence** (highest wins):
 1. `OUTFITTER_LOG_LEVEL` environment variable
 2. Explicit `level` parameter
@@ -328,10 +343,97 @@ const logger = createLogger({
 // With OUTFITTER_ENV=development → "debug"
 // With OUTFITTER_LOG_LEVEL=error → "error" (overrides everything)
 // With nothing set → "info"
+
+// Forward a CLI string without casting
+const level = flags.logLevel; // string from commander
+const logger2 = createLogger({
+  name: "cli",
+  level: resolveLogLevel(level),
+  sinks: [createConsoleSink()],
+});
 ```
 
 MCP-style level names are mapped automatically: `warning` to `warn`, `emergency`/`critical`/`alert` to `fatal`, `notice` to `info`.
 
+### Edge Runtime Compatibility
+
+`resolveLogLevel` and `createConsoleSink` are safe to use in environments where `process` is unavailable (V8 isolates, Cloudflare Workers, edge runtimes). Environment variable reads are guarded and environment profile resolution falls back gracefully to defaults.
+
+## Logger Factory + BYO Backends
+
+Use the Outfitter logger factory when wiring runtimes (CLI, MCP, daemons). It applies Outfitter defaults for log level resolution and redaction.
+
+```typescript
+import { createOutfitterLoggerFactory } from "@outfitter/logging";
+
+const factory = createOutfitterLoggerFactory();
+const logger = factory.createLogger({
+  name: "mcp",
+  context: { surface: "mcp" },
+});
+
+logger.info("Tool invoked", { tool: "search" });
+await factory.flush();
+```
+
+If you need a different backend, you can use the shared contracts factory with your own adapter and still satisfy the same `Logger` interface expected by Outfitter packages.
+
+```typescript
+import {
+  createLoggerFactory,
+  type Logger,
+  type LoggerAdapter,
+} from "@outfitter/contracts";
+
+type BackendOptions = { write: (line: string) => void };
+
+const adapter: LoggerAdapter<BackendOptions> = {
+  createLogger(config) {
+    const write = config.backend?.write ?? (() => {});
+    const createMethod = (level: string): Logger["info"] =>
+      ((message: string) => {
+        write(`[${level}] ${message}`);
+      }) as Logger["info"];
+
+    return {
+      trace: createMethod("trace"),
+      debug: createMethod("debug"),
+      info: createMethod("info"),
+      warn: createMethod("warn"),
+      error: createMethod("error"),
+      fatal: createMethod("fatal"),
+      child: () => adapter.createLogger(config),
+    };
+  },
+};
+
+const customFactory = createLoggerFactory(adapter);
+const customLogger = customFactory.createLogger({
+  name: "custom-runtime",
+  backend: { write: (line) => console.log(line) },
+});
+
+customLogger.info("Hello from custom backend");
+```
+
+## Runtime Compatibility
+
+| Export | Node.js | Bun | Edge/V8 Isolates | Notes |
+|---|---|---|---|---|
+| `createLogger` | Yes | Yes | Yes | Universal |
+| `createConsoleSink` | Yes | Yes | Yes | Falls back to `console.*` when `process` unavailable |
+| `createFileSink` | No | Yes | No | Requires `Bun.file` / `Bun.write` |
+| `createJsonFormatter` | Yes | Yes | Yes | Universal |
+| `createPrettyFormatter` | Yes | Yes | Yes | Universal |
+| `resolveLogLevel` | Yes | Yes | Yes | Guards `process.env` access |
+| `resolveOutfitterLogLevel` | Yes | Yes | Yes | Guards `process.env` access |
+| `configureRedaction` | Yes | Yes | Yes | Universal |
+| `flush` | Yes | Yes | Yes | Universal |
+
+Edge-runtime notes:
+- `resolveLogLevel()` safely returns defaults when `process` is undefined
+- `createConsoleSink()` auto-detects TTY via `process.stdout?.isTTY` with graceful fallback
+
 ## API Reference
 
 ### Functions
@@ -363,6 +465,10 @@ MCP-style level names are mapped automatically: `warning` to `warn`, `emergency`
 | `PrettyFormatterOptions` | Options for human-readable formatter            |
 | `FileSinkOptions`        | Options for file sink configuration             |
 
+## Upgrading
+
+Run `outfitter update --guide` for version-specific migration instructions, or check the [migration docs](https://github.com/outfitter-dev/outfitter/tree/main/plugins/outfitter/shared/migrations) for detailed upgrade steps.
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Logger as ContractLogger, LoggerAdapter as ContractLoggerAdapter, LoggerFactory as ContractLoggerFactory } from "@outfitter/contracts";
 /**
 * Log levels supported by the logger, ordered from lowest to highest severity.
 *
@@ -185,6 +186,32 @@ interface LoggerConfig {
 	redaction?: RedactionConfig;
 }
 /**
+* Backend options accepted by the Outfitter logger factory.
+*
+* These options are passed via `LoggerFactoryConfig.backend`.
+*/
+interface OutfitterLoggerBackendOptions {
+	/** Sinks for this specific logger instance */
+	sinks?: Sink[];
+	/** Redaction overrides for this specific logger instance */
+	redaction?: RedactionConfig;
+}
+/**
+* Default options applied by the Outfitter logger factory.
+*/
+interface OutfitterLoggerDefaults {
+	/** Default sinks used when a logger does not provide backend sinks */
+	sinks?: Sink[];
+	/** Default redaction policy merged with logger-specific redaction */
+	redaction?: RedactionConfig;
+}
+/**
+* Options for creating the Outfitter logger factory.
+*/
+interface OutfitterLoggerFactoryOptions {
+	defaults?: OutfitterLoggerDefaults;
+}
+/**
 * Logger instance with methods for each log level.
 *
 * Provides methods for logging at each severity level, plus utilities for
@@ -201,7 +228,7 @@ interface LoggerConfig {
 * logger.debug("Debug info", { details: "..." });
 * ```
 */
-interface LoggerInstance {
+interface LoggerInstance extends ContractLogger {
 	/**
 	* Log at trace level (most verbose, for detailed debugging).
 	* @param message - Human-readable log message
@@ -333,6 +360,17 @@ interface ConsoleSinkOptions {
 	* - `false`: Never use colors
 	*/
 	colors?: boolean;
+	/**
+	* Custom formatter for log output.
+	* When provided, overrides the default pretty formatter.
+	* Use `createJsonFormatter()` for structured output.
+	*
+	* @example
+	* ```typescript
+	* const sink = createConsoleSink({ formatter: createJsonFormatter() });
+	* ```
+	*/
+	formatter?: Formatter;
 }
 /**
 * Options for the file sink.
@@ -568,5 +606,36 @@ declare function flush(): Promise<void>;
 * // With nothing set → "info"
 * ```
 */
-declare function resolveLogLevel(level?: LogLevel): LogLevel;
-export { resolveLogLevel, flush, createPrettyFormatter, createLogger, createJsonFormatter, createFileSink, createConsoleSink, createChildLogger, configureRedaction, Sink, RedactionConfig, PrettyFormatterOptions, LoggerInstance, LoggerConfig, LogRecord, LogLevel, GlobalRedactionConfig, Formatter, FileSinkOptions, DEFAULT_PATTERNS, ConsoleSinkOptions };
+declare function resolveLogLevel(level?: LogLevel | string): LogLevel;
+/**
+* Resolve log level using Outfitter runtime defaults.
+*
+* Precedence (highest wins):
+* 1. `OUTFITTER_LOG_LEVEL` environment variable
+* 2. Explicit `level` parameter
+* 3. `OUTFITTER_ENV` profile defaults
+* 4. `"silent"` (when profile default is null)
+*/
+declare function resolveOutfitterLogLevel(level?: LogLevel | string): LogLevel;
+/**
+* Outfitter logger adapter contract type.
+*/
+type OutfitterLoggerAdapter = ContractLoggerAdapter<OutfitterLoggerBackendOptions>;
+/**
+* Outfitter logger factory contract type.
+*/
+type OutfitterLoggerFactory = ContractLoggerFactory<OutfitterLoggerBackendOptions>;
+/**
+* Create an Outfitter logger adapter with environment defaults and redaction.
+*
+* Defaults:
+* - log level resolution via `resolveOutfitterLogLevel()`
+* - redaction enabled by default (`enabled: true`)
+* - console sink when no explicit sinks are provided
+*/
+declare function createOutfitterLoggerAdapter(options?: OutfitterLoggerFactoryOptions): OutfitterLoggerAdapter;
+/**
+* Create an Outfitter logger factory over the contracts logger abstraction.
+*/
+declare function createOutfitterLoggerFactory(options?: OutfitterLoggerFactoryOptions): OutfitterLoggerFactory;
+export { resolveOutfitterLogLevel, resolveLogLevel, flush, createPrettyFormatter, createOutfitterLoggerFactory, createOutfitterLoggerAdapter, createLogger, createJsonFormatter, createFileSink, createConsoleSink, createChildLogger, configureRedaction, Sink, RedactionConfig, PrettyFormatterOptions, OutfitterLoggerFactoryOptions, OutfitterLoggerFactory, OutfitterLoggerDefaults, OutfitterLoggerBackendOptions, OutfitterLoggerAdapter, LoggerInstance, LoggerConfig, LogRecord, LogLevel, GlobalRedactionConfig, Formatter, FileSinkOptions, DEFAULT_PATTERNS, ConsoleSinkOptions };

package/dist/index.js

@@ -1,8 +1,16 @@
 // src/index.ts
+import {
+  configureSync,
+  getConfig,
+  getLogger
+} from "@logtape/logtape";
 import {
   getEnvironment as _getEnvironment,
   getEnvironmentDefaults as _getEnvironmentDefaults
 } from "@outfitter/config";
+import {
+  createLoggerFactory as createContractLoggerFactory
+} from "@outfitter/contracts";
 var LEVEL_PRIORITY = {
   trace: 0,
   debug: 1,
@@ -27,6 +35,13 @@ var globalRedactionConfig = {
   keys: []
 };
 var registeredSinks = new Set;
+var LOGGER_ID_PROPERTY = "__outfitter_internal_logger_id";
+var loggerSinkRegistry = new Map;
+var logtapeBackendConfigured = false;
+var logtapeBridgeEnabled = true;
+var loggerIdCounter = 0;
+var LOGTAPE_BRIDGE_SINK = "__outfitter_bridge_sink";
+var LOGTAPE_BRIDGE_CATEGORY = "__outfitter_bridge";
 function shouldLog(level, minLevel) {
   if (minLevel === "silent")
     return false;
@@ -139,6 +154,154 @@ function processNestedForErrors(obj) {
   }
   return result;
 }
+function mergeRedactionConfig(base, override) {
+  if (!(base || override)) {
+    return;
+  }
+  const merged = {};
+  const keys = [...base?.keys ?? [], ...override?.keys ?? []];
+  const patterns = [...base?.patterns ?? [], ...override?.patterns ?? []];
+  if (keys.length > 0) {
+    merged.keys = keys;
+  }
+  if (patterns.length > 0) {
+    merged.patterns = patterns;
+  }
+  if (base?.enabled !== undefined) {
+    merged.enabled = base.enabled;
+  }
+  if (override?.enabled !== undefined) {
+    merged.enabled = override.enabled;
+  }
+  if (base?.replacement !== undefined) {
+    merged.replacement = base.replacement;
+  }
+  if (override?.replacement !== undefined) {
+    merged.replacement = override.replacement;
+  }
+  return merged;
+}
+function stringifyLogtapeMessage(parts) {
+  return parts.map((part) => String(part)).join("");
+}
+function fromLogtapeLevel(level) {
+  if (level === "warning") {
+    return "warn";
+  }
+  return level;
+}
+function registerLoggerSink(loggerId, sink) {
+  const sinks = loggerSinkRegistry.get(loggerId);
+  if (sinks) {
+    sinks.add(sink);
+    return;
+  }
+  loggerSinkRegistry.set(loggerId, new Set([sink]));
+}
+function dispatchRecordToSinks(sinks, record) {
+  for (const sink of sinks) {
+    try {
+      let formatted;
+      if (sink.formatter) {
+        formatted = sink.formatter.format(record);
+      }
+      sink.write(record, formatted);
+    } catch {}
+  }
+}
+function isLogtapeBridgeConfigured(config) {
+  if (!config) {
+    return false;
+  }
+  if (!(LOGTAPE_BRIDGE_SINK in config.sinks)) {
+    return false;
+  }
+  return config.loggers.some((logger) => {
+    const categoryParts = Array.isArray(logger.category) ? logger.category : [logger.category];
+    if (categoryParts.length !== 1 || categoryParts[0] !== LOGTAPE_BRIDGE_CATEGORY) {
+      return false;
+    }
+    return (logger.sinks ?? []).includes(LOGTAPE_BRIDGE_SINK);
+  });
+}
+function emitViaLogtape(logger, level, message, metadata) {
+  const loggerWithMetadata = logger.with(metadata);
+  switch (level) {
+    case "trace":
+      loggerWithMetadata.trace`${message}`;
+      return;
+    case "debug":
+      loggerWithMetadata.debug`${message}`;
+      return;
+    case "info":
+      loggerWithMetadata.info`${message}`;
+      return;
+    case "warn":
+      loggerWithMetadata.warn`${message}`;
+      return;
+    case "error":
+      loggerWithMetadata.error`${message}`;
+      return;
+    case "fatal":
+      loggerWithMetadata.fatal`${message}`;
+      return;
+    default:
+      return;
+  }
+}
+function ensureLogtapeBackendConfigured() {
+  const currentConfig = getConfig();
+  if (logtapeBackendConfigured) {
+    logtapeBridgeEnabled = isLogtapeBridgeConfigured(currentConfig);
+    return;
+  }
+  if (currentConfig !== null) {
+    logtapeBridgeEnabled = isLogtapeBridgeConfigured(currentConfig);
+    logtapeBackendConfigured = true;
+    return;
+  }
+  try {
+    configureSync({
+      sinks: {
+        [LOGTAPE_BRIDGE_SINK](record) {
+          const loggerId = record.properties[LOGGER_ID_PROPERTY];
+          if (typeof loggerId !== "string") {
+            return;
+          }
+          const sinks = loggerSinkRegistry.get(loggerId);
+          if (!sinks || sinks.size === 0) {
+            return;
+          }
+          const metadata = { ...record.properties };
+          delete metadata[LOGGER_ID_PROPERTY];
+          const categoryParts = record.category[0] === LOGTAPE_BRIDGE_CATEGORY ? record.category.slice(1) : record.category;
+          const converted = {
+            timestamp: record.timestamp,
+            level: fromLogtapeLevel(record.level),
+            category: categoryParts.join("."),
+            message: stringifyLogtapeMessage(record.message),
+            ...Object.keys(metadata).length > 0 ? { metadata } : {}
+          };
+          dispatchRecordToSinks(sinks, converted);
+        }
+      },
+      loggers: [
+        {
+          category: [LOGTAPE_BRIDGE_CATEGORY],
+          sinks: [LOGTAPE_BRIDGE_SINK],
+          lowestLevel: "trace"
+        },
+        {
+          category: ["logtape", "meta"],
+          lowestLevel: "error"
+        }
+      ]
+    });
+  } catch {
+    logtapeBridgeEnabled = false;
+  }
+  logtapeBackendConfigured = true;
+}
 function createLoggerFromState(state) {
   const log = (level, message, metadata) => {
     if (!shouldLog(level, state.level))
@@ -157,22 +320,21 @@ function createLoggerFromState(state) {
         processedMessage = applyPatterns(message, allPatterns, replacement);
       }
     }
-    const record = {
+    if (logtapeBridgeEnabled) {
+      emitViaLogtape(state.backendLogger, level, processedMessage, {
+        ...processedMetadata ?? {},
+        [LOGGER_ID_PROPERTY]: state.loggerId
+      });
+      return;
+    }
+    const directRecord = {
       timestamp: Date.now(),
       level,
       category: state.name,
       message: processedMessage,
-      ...processedMetadata !== undefined ? { metadata: processedMetadata } : {}
+      ...processedMetadata ? { metadata: processedMetadata } : {}
     };
-    for (const sink of state.sinks) {
-      try {
-        let formatted;
-        if (sink.formatter) {
-          formatted = sink.formatter.format(record);
-        }
-        sink.write(record, formatted);
-      } catch {}
-    }
+    dispatchRecordToSinks(state.sinks, directRecord);
   };
   return {
     trace: (message, metadata) => log("trace", message, metadata),
@@ -188,9 +350,12 @@ function createLoggerFromState(state) {
     addSink: (sink) => {
       state.sinks.push(sink);
       registeredSinks.add(sink);
+      registerLoggerSink(state.loggerId, sink);
     },
     child: (context) => {
       const childState = {
+        loggerId: state.loggerId,
+        backendLogger: state.backendLogger,
         name: state.name,
         level: state.level,
         context: { ...state.context, ...context },
@@ -202,7 +367,11 @@ function createLoggerFromState(state) {
   };
 }
 function createLogger(config) {
+  ensureLogtapeBackendConfigured();
+  const loggerId = `logger-${++loggerIdCounter}`;
   const state = {
+    loggerId,
+    backendLogger: getLogger([LOGTAPE_BRIDGE_CATEGORY, config.name]),
     name: config.name,
     level: config.level ?? "info",
     context: config.context ?? {},
@@ -211,6 +380,7 @@ function createLogger(config) {
   };
   for (const sink of state.sinks) {
     registeredSinks.add(sink);
+    registerLoggerSink(loggerId, sink);
   }
   return createLoggerFromState(state);
 }
@@ -309,7 +479,7 @@ function createPrettyFormatter(options) {
 }
 function createConsoleSink(options) {
   const useColors = options?.colors ?? (typeof process !== "undefined" ? Boolean(process.stdout?.isTTY) : false);
-  const formatter = createPrettyFormatter({ colors: useColors });
+  const formatter = options?.formatter ?? createPrettyFormatter({ colors: useColors });
   const sink = {
     formatter,
     write(record, formatted) {
@@ -382,15 +552,24 @@ function configureRedaction(config) {
     ];
   }
 }
-async function flush() {
+async function flushSinks(sinks) {
   const flushPromises = [];
-  for (const sink of registeredSinks) {
+  for (const sink of sinks) {
     if (sink.flush) {
-      flushPromises.push(sink.flush());
+      flushPromises.push(sink.flush().catch(() => {}));
     }
   }
   await Promise.all(flushPromises);
 }
+async function flush() {
+  await flushSinks(registeredSinks);
+}
+function safeGetEnv(key) {
+  if (typeof process !== "undefined") {
+    return process.env?.[key];
+  }
+  return;
+}
 var ENV_LEVEL_MAP = {
   trace: "trace",
   debug: "debug",
@@ -406,30 +585,80 @@ var ENV_LEVEL_MAP = {
   silent: "silent"
 };
 function resolveLogLevel(level) {
-  const envLogLevel = process.env["OUTFITTER_LOG_LEVEL"];
-  if (envLogLevel !== undefined) {
-    const mapped = ENV_LEVEL_MAP[envLogLevel];
-    if (mapped !== undefined) {
-      return mapped;
-    }
+  const envLogLevel = safeGetEnv("OUTFITTER_LOG_LEVEL");
+  if (envLogLevel !== undefined && Object.hasOwn(ENV_LEVEL_MAP, envLogLevel)) {
+    return ENV_LEVEL_MAP[envLogLevel];
   }
-  if (level !== undefined) {
-    return level;
+  if (level !== undefined && Object.hasOwn(ENV_LEVEL_MAP, level)) {
+    return ENV_LEVEL_MAP[level];
   }
-  const env = _getEnvironment();
-  const defaults = _getEnvironmentDefaults(env);
-  if (defaults.logLevel !== null) {
-    const mapped = ENV_LEVEL_MAP[defaults.logLevel];
-    if (mapped !== undefined) {
-      return mapped;
+  try {
+    const env = _getEnvironment();
+    const defaults = _getEnvironmentDefaults(env);
+    if (defaults.logLevel !== null && Object.hasOwn(ENV_LEVEL_MAP, defaults.logLevel)) {
+      return ENV_LEVEL_MAP[defaults.logLevel];
     }
-  }
+  } catch {}
   return "info";
 }
+function resolveOutfitterLogLevel(level) {
+  const envLogLevel = safeGetEnv("OUTFITTER_LOG_LEVEL");
+  if (envLogLevel !== undefined && Object.hasOwn(ENV_LEVEL_MAP, envLogLevel)) {
+    return ENV_LEVEL_MAP[envLogLevel];
+  }
+  if (level !== undefined && Object.hasOwn(ENV_LEVEL_MAP, level)) {
+    return ENV_LEVEL_MAP[level];
+  }
+  try {
+    const env = _getEnvironment();
+    const defaults = _getEnvironmentDefaults(env);
+    if (defaults.logLevel !== null && Object.hasOwn(ENV_LEVEL_MAP, defaults.logLevel)) {
+      return ENV_LEVEL_MAP[defaults.logLevel];
+    }
+  } catch {}
+  return "silent";
+}
+function createOutfitterLoggerAdapter(options) {
+  const factorySinks = new Set;
+  return {
+    createLogger(config) {
+      const backend = config.backend;
+      const sinks = backend?.sinks ?? options?.defaults?.sinks ?? [createConsoleSink()];
+      const defaultRedaction = mergeRedactionConfig({ enabled: true }, options?.defaults?.redaction);
+      const redaction = mergeRedactionConfig(defaultRedaction, backend?.redaction);
+      const loggerConfig = {
+        name: config.name,
+        level: resolveOutfitterLogLevel(config.level),
+        sinks,
+        ...config.context !== undefined ? { context: config.context } : {},
+        ...redaction !== undefined ? { redaction } : {}
+      };
+      for (const sink of sinks) {
+        factorySinks.add(sink);
+      }
+      const logger = createLogger(loggerConfig);
+      const originalAddSink = logger.addSink.bind(logger);
+      logger.addSink = (sink) => {
+        factorySinks.add(sink);
+        originalAddSink(sink);
+      };
+      return logger;
+    },
+    async flush() {
+      await flushSinks(factorySinks);
+    }
+  };
+}
+function createOutfitterLoggerFactory(options) {
+  return createContractLoggerFactory(createOutfitterLoggerAdapter(options));
+}
 export {
+  resolveOutfitterLogLevel,
   resolveLogLevel,
   flush,
   createPrettyFormatter,
+  createOutfitterLoggerFactory,
+  createOutfitterLoggerAdapter,
   createLogger,
   createJsonFormatter,
   createFileSink,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@outfitter/logging",
   "description": "Structured logging via logtape with redaction support for Outfitter",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "files": [
     "dist"
@@ -27,11 +27,15 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@outfitter/config": "0.3.0",
-    "@outfitter/contracts": "0.2.0",
     "@logtape/logtape": "^2.0.0"
   },
+  "peerDependencies": {
+    "@outfitter/config": ">=0.3.0",
+    "@outfitter/contracts": ">=0.2.0"
+  },
   "devDependencies": {
+    "@outfitter/config": "0.3.1",
+    "@outfitter/contracts": "0.3.0",
     "@types/bun": "latest",
     "typescript": "^5.8.0"
   },