@outfitter/logging 0.1.0 → 0.3.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";
@@ -303,6 +304,34 @@ await flush();
 process.exit(0);
 ```
 
+## Environment-Aware Log Level
+
+### `resolveLogLevel(level?)`
+
+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.
+
+**Precedence** (highest wins):
+1. `OUTFITTER_LOG_LEVEL` environment variable
+2. Explicit `level` parameter
+3. `OUTFITTER_ENV` profile defaults (`"debug"` in development)
+4. `"info"` (default)
+
+```typescript
+import { createLogger, resolveLogLevel } from "@outfitter/logging";
+
+const logger = createLogger({
+  name: "my-app",
+  level: resolveLogLevel(),
+  sinks: [createConsoleSink()],
+});
+
+// With OUTFITTER_ENV=development → "debug"
+// With OUTFITTER_LOG_LEVEL=error → "error" (overrides everything)
+// With nothing set → "info"
+```
+
+MCP-style level names are mapped automatically: `warning` to `warn`, `emergency`/`critical`/`alert` to `fatal`, `notice` to `info`.
+
 ## API Reference
 
 ### Functions
@@ -311,6 +340,7 @@ process.exit(0);
 | ----------------------- | --------------------------------------------------- |
 | `createLogger`          | Create a configured logger instance                 |
 | `createChildLogger`     | Create a child logger with merged context           |
+| `resolveLogLevel`       | Resolve log level from env vars and profile         |
 | `configureRedaction`    | Configure global redaction patterns and keys        |
 | `flush`                 | Flush all pending log writes across all sinks       |
 | `createJsonFormatter`   | Create a JSON formatter for structured output       |

package/dist/index.d.ts

@@ -208,36 +208,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
@@ -353,7 +359,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;
@@ -471,8 +477,8 @@ 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
@@ -535,4 +541,32 @@ 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, ConsoleSinkOptions };
+/**
+* Resolve the log level from environment configuration.
+*
+* Precedence (highest wins):
+* 1. `OUTFITTER_LOG_LEVEL` environment variable
+* 2. Explicit `level` parameter
+* 3. `OUTFITTER_ENV` environment profile defaults
+* 4. `"info"` (default)
+*
+* @param level - Optional explicit log level (overridden by env var)
+* @returns Resolved LogLevel
+*
+* @example
+* ```typescript
+* import { createLogger, resolveLogLevel } from "@outfitter/logging";
+*
+* // Auto-resolve from environment
+* const logger = createLogger({
+*   name: "my-app",
+*   level: resolveLogLevel(),
+* });
+*
+* // With OUTFITTER_ENV=development → "debug"
+* // With OUTFITTER_LOG_LEVEL=error → "error" (overrides everything)
+* // 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 };

package/dist/index.js

@@ -1,5 +1,8 @@
 // src/index.ts
-import { writeFileSync } from "node:fs";
+import {
+  getEnvironment as _getEnvironment,
+  getEnvironmentDefaults as _getEnvironmentDefaults
+} from "@outfitter/config";
 var LEVEL_PRIORITY = {
   trace: 0,
   debug: 1,
@@ -215,12 +218,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),
@@ -287,20 +308,28 @@ function createPrettyFormatter(options) {
   };
 }
 function createConsoleSink(options) {
-  const useColors = options?.colors ?? process.stdout.isTTY ?? false;
+  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);
@@ -311,9 +340,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) {
@@ -327,9 +354,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);
       }
     }
   };
@@ -359,7 +391,43 @@ async function flush() {
   }
   await Promise.all(flushPromises);
 }
+var ENV_LEVEL_MAP = {
+  trace: "trace",
+  debug: "debug",
+  info: "info",
+  notice: "info",
+  warn: "warn",
+  warning: "warn",
+  error: "error",
+  critical: "fatal",
+  alert: "fatal",
+  emergency: "fatal",
+  fatal: "fatal",
+  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;
+    }
+  }
+  if (level !== undefined) {
+    return level;
+  }
+  const env = _getEnvironment();
+  const defaults = _getEnvironmentDefaults(env);
+  if (defaults.logLevel !== null) {
+    const mapped = ENV_LEVEL_MAP[defaults.logLevel];
+    if (mapped !== undefined) {
+      return mapped;
+    }
+  }
+  return "info";
+}
 export {
+  resolveLogLevel,
   flush,
   createPrettyFormatter,
   createLogger,

package/package.json

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