@outfitter/logging 0.1.0-rc.3 → 0.2.0

package/README.md

@@ -184,6 +184,7 @@ Routes logs to stdout/stderr based on level:
 
 - `trace`, `debug`, `info` -> stdout
 - `warn`, `error`, `fatal` -> stderr
+ - Falls back to `console.*` when process streams are unavailable (edge/serverless)
 
 ```typescript
 import { createConsoleSink } from "@outfitter/logging";

package/dist/index.d.ts

@@ -1,4 +1,12 @@
 /**
+* @outfitter/logging
+*
+* Structured logging via logtape with automatic sensitive data redaction.
+* Provides consistent log formatting across CLI, MCP, and server contexts.
+*
+* @packageDocumentation
+*/
+/**
 * Log levels supported by the logger, ordered from lowest to highest severity.
 *
 * Level priority (lowest to highest): trace (0) < debug (1) < info (2) < warn (3) < error (4) < fatal (5)
@@ -208,36 +216,42 @@ interface LoggerInstance {
 	* @param metadata - Optional structured metadata
 	*/
 	trace(message: string, metadata?: Record<string, unknown>): void;
+	trace(metadata: Record<string, unknown>, message: string): never;
 	/**
 	* Log at debug level (development debugging).
 	* @param message - Human-readable log message
 	* @param metadata - Optional structured metadata
 	*/
 	debug(message: string, metadata?: Record<string, unknown>): void;
+	debug(metadata: Record<string, unknown>, message: string): never;
 	/**
 	* Log at info level (normal operations).
 	* @param message - Human-readable log message
 	* @param metadata - Optional structured metadata
 	*/
 	info(message: string, metadata?: Record<string, unknown>): void;
+	info(metadata: Record<string, unknown>, message: string): never;
 	/**
 	* Log at warn level (unexpected but handled situations).
 	* @param message - Human-readable log message
 	* @param metadata - Optional structured metadata
 	*/
 	warn(message: string, metadata?: Record<string, unknown>): void;
+	warn(metadata: Record<string, unknown>, message: string): never;
 	/**
 	* Log at error level (failures requiring attention).
 	* @param message - Human-readable log message
 	* @param metadata - Optional structured metadata
 	*/
 	error(message: string, metadata?: Record<string, unknown>): void;
+	error(metadata: Record<string, unknown>, message: string): never;
 	/**
 	* Log at fatal level (unrecoverable failures).
 	* @param message - Human-readable log message
 	* @param metadata - Optional structured metadata
 	*/
 	fatal(message: string, metadata?: Record<string, unknown>): void;
+	fatal(metadata: Record<string, unknown>, message: string): never;
 	/**
 	* Get the current context metadata attached to this logger.
 	* @returns Copy of the logger's context object
@@ -302,6 +316,33 @@ interface PrettyFormatterOptions {
 	timestamp?: boolean;
 }
 /**
+* Options for the console sink.
+*
+* Controls ANSI color output for terminal display. By default, colors are
+* auto-detected based on whether stdout is a TTY.
+*
+* @example
+* ```typescript
+* // Auto-detect TTY (default)
+* const sink = createConsoleSink();
+*
+* // Force colors off (for piped output, CI)
+* const plainSink = createConsoleSink({ colors: false });
+*
+* // Force colors on (even in non-TTY)
+* const colorSink = createConsoleSink({ colors: true });
+* ```
+*/
+interface ConsoleSinkOptions {
+	/**
+	* Enable ANSI colors in output.
+	* - `undefined` (default): Auto-detect based on stdout TTY status
+	* - `true`: Always use colors
+	* - `false`: Never use colors
+	*/
+	colors?: boolean;
+}
+/**
 * Options for the file sink.
 *
 * Configures the file path and append behavior for file-based logging.
@@ -326,7 +367,7 @@ interface FileSinkOptions {
 	/** Absolute path to the log file */
 	path: string;
 	/**
-	* Append to existing file or truncate on start.
+	* Append to existing file or truncate before the first write.
 	* @defaultValue true
 	*/
 	append?: boolean;
@@ -444,9 +485,10 @@ declare function createJsonFormatter(): Formatter;
 */
 declare function createPrettyFormatter(options?: PrettyFormatterOptions): Formatter;
 /**
-* Create a console sink that writes to stdout/stderr.
-* Info and below go to stdout, warn and above go to stderr.
+* Create a console sink that writes via console methods.
+* Info and below go to console.info/debug, warn and above go to console.warn/error.
 *
+* @param options - Console sink options
 * @returns Sink configured for console output
 *
 * @example
@@ -455,9 +497,15 @@ declare function createPrettyFormatter(options?: PrettyFormatterOptions): Format
 *   name: "app",
 *   sinks: [createConsoleSink()],
 * });
+*
+* // Disable colors for CI/piped output
+* const plainLogger = createLogger({
+*   name: "app",
+*   sinks: [createConsoleSink({ colors: false })],
+* });
 * ```
 */
-declare function createConsoleSink(): Sink;
+declare function createConsoleSink(options?: ConsoleSinkOptions): Sink;
 /**
 * Create a file sink that writes to a specified file path.
 *
@@ -501,4 +549,4 @@ declare function configureRedaction(config: GlobalRedactionConfig): void;
 * ```
 */
 declare function flush(): Promise<void>;
-export { flush, createPrettyFormatter, createLogger, createJsonFormatter, createFileSink, createConsoleSink, createChildLogger, configureRedaction, Sink, RedactionConfig, PrettyFormatterOptions, LoggerInstance, LoggerConfig, LogRecord, LogLevel, GlobalRedactionConfig, Formatter, FileSinkOptions, DEFAULT_PATTERNS };
+export { flush, createPrettyFormatter, createLogger, createJsonFormatter, createFileSink, createConsoleSink, createChildLogger, configureRedaction, Sink, RedactionConfig, PrettyFormatterOptions, LoggerInstance, LoggerConfig, LogRecord, LogLevel, GlobalRedactionConfig, Formatter, FileSinkOptions, DEFAULT_PATTERNS, ConsoleSinkOptions };

package/dist/index.js

@@ -1,5 +1,4 @@
 // src/index.ts
-import { writeFileSync } from "node:fs";
 var LEVEL_PRIORITY = {
   trace: 0,
   debug: 1,
@@ -215,12 +214,30 @@ function createChildLogger(parent, context) {
   const parentContext = parent.getContext();
   const mergedContext = { ...parentContext, ...context };
   const childLogger = {
-    trace: (message, metadata) => parent.trace(message, { ...context, ...metadata }),
-    debug: (message, metadata) => parent.debug(message, { ...context, ...metadata }),
-    info: (message, metadata) => parent.info(message, { ...context, ...metadata }),
-    warn: (message, metadata) => parent.warn(message, { ...context, ...metadata }),
-    error: (message, metadata) => parent.error(message, { ...context, ...metadata }),
-    fatal: (message, metadata) => parent.fatal(message, { ...context, ...metadata }),
+    trace: (message, metadata) => parent.trace(message, {
+      ...context,
+      ...metadata
+    }),
+    debug: (message, metadata) => parent.debug(message, {
+      ...context,
+      ...metadata
+    }),
+    info: (message, metadata) => parent.info(message, {
+      ...context,
+      ...metadata
+    }),
+    warn: (message, metadata) => parent.warn(message, {
+      ...context,
+      ...metadata
+    }),
+    error: (message, metadata) => parent.error(message, {
+      ...context,
+      ...metadata
+    }),
+    fatal: (message, metadata) => parent.fatal(message, {
+      ...context,
+      ...metadata
+    }),
     getContext: () => mergedContext,
     setLevel: (level) => parent.setLevel(level),
     addSink: (sink) => parent.addSink(sink),
@@ -286,20 +303,29 @@ function createPrettyFormatter(options) {
     }
   };
 }
-function createConsoleSink() {
-  const formatter = createPrettyFormatter({ colors: true });
+function createConsoleSink(options) {
+  const useColors = options?.colors ?? (typeof process !== "undefined" ? Boolean(process.stdout?.isTTY) : false);
+  const formatter = createPrettyFormatter({ colors: useColors });
   const sink = {
     formatter,
     write(record, formatted) {
       const output = formatted ?? formatter.format(record);
-      const outputWithNewline = output.endsWith(`
-`) ? output : `${output}
-`;
-      if (LEVEL_PRIORITY[record.level] >= LEVEL_PRIORITY.warn) {
-        process.stderr.write(outputWithNewline);
-      } else {
-        process.stdout.write(outputWithNewline);
+      const outputLine = output.endsWith(`
+`) ? output.slice(0, -1) : output;
+      const runtimeConsole = globalThis["console"];
+      if (record.level === "fatal" || record.level === "error") {
+        runtimeConsole.error(outputLine);
+        return;
       }
+      if (record.level === "warn") {
+        runtimeConsole.warn(outputLine);
+        return;
+      }
+      if (record.level === "debug" || record.level === "trace") {
+        runtimeConsole.debug(outputLine);
+        return;
+      }
+      runtimeConsole.info(outputLine);
     }
   };
   registeredSinks.add(sink);
@@ -310,9 +336,7 @@ function createFileSink(options) {
   const buffer = [];
   const { path } = options;
   const append = options.append ?? true;
-  if (!append) {
-    writeFileSync(path, "");
-  }
+  let cachedContent = append ? null : "";
   const sink = {
     formatter,
     write(record, formatted) {
@@ -326,9 +350,14 @@ function createFileSink(options) {
       if (buffer.length > 0) {
         const content = buffer.join("");
         buffer.length = 0;
-        const file = Bun.file(path);
-        const existing = await file.exists() ? await file.text() : "";
-        await Bun.write(path, existing + content);
+        if (append) {
+          const file = Bun.file(path);
+          const existing = await file.exists() ? await file.text() : "";
+          await Bun.write(path, existing + content);
+          return;
+        }
+        cachedContent = (cachedContent ?? "") + content;
+        await Bun.write(path, cachedContent);
       }
     }
   };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@outfitter/logging",
   "description": "Structured logging via logtape with redaction support for Outfitter",
-  "version": "0.1.0-rc.3",
+  "version": "0.2.0",
   "type": "module",
   "files": [
     "dist"
@@ -27,7 +27,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@outfitter/contracts": "0.1.0-rc.2",
+    "@outfitter/contracts": "0.2.0",
     "@logtape/logtape": "^2.0.0"
   },
   "devDependencies": {