@outfitter/logging 0.1.0-rc.1

package/README.md

@@ -0,0 +1,338 @@
+# @outfitter/logging
+
+Structured logging via logtape with automatic sensitive data redaction. Provides consistent log formatting across CLI, MCP, and server contexts.
+
+## Installation
+
+```bash
+bun add @outfitter/logging
+```
+
+## Quick Start
+
+```typescript
+import {
+  createLogger,
+  createConsoleSink,
+  configureRedaction,
+} from "@outfitter/logging";
+
+// Configure global redaction (optional - defaults already cover common sensitive keys)
+configureRedaction({
+  keys: ["apiKey", "accessToken"],
+  patterns: [/sk-[a-zA-Z0-9]+/g],
+});
+
+// Create a logger
+const logger = createLogger({
+  name: "my-service",
+  level: "debug",
+  sinks: [createConsoleSink()],
+  redaction: { enabled: true },
+});
+
+// Log with metadata
+logger.info("Request received", {
+  path: "/api/users",
+  apiKey: "secret-key-123", // Will be redacted to "[REDACTED]"
+});
+```
+
+## Log Levels
+
+| Level    | Priority | Use For                                    |
+| -------- | -------- | ------------------------------------------ |
+| `trace`  | 0        | Very detailed debugging (loops, internals) |
+| `debug`  | 1        | Development debugging                      |
+| `info`   | 2        | Normal operations                          |
+| `warn`   | 3        | Unexpected but handled situations          |
+| `error`  | 4        | Failures requiring attention               |
+| `fatal`  | 5        | Unrecoverable failures                     |
+| `silent` | 6        | Disable all logging                        |
+
+Messages are filtered by minimum level. Setting `level: "warn"` filters out `trace`, `debug`, and `info`.
+
+```typescript
+const logger = createLogger({
+  name: "app",
+  level: "warn", // Only warn, error, fatal will be logged
+  sinks: [createConsoleSink()],
+});
+
+logger.debug("Filtered out");
+logger.warn("This appears");
+```
+
+### Changing Level at Runtime
+
+```typescript
+logger.setLevel("debug"); // Enable debug logging
+logger.setLevel("silent"); // Disable all logging
+```
+
+## Redaction
+
+Automatic redaction protects sensitive data from appearing in logs.
+
+### Default Sensitive Keys
+
+These keys are redacted by default (case-insensitive matching):
+
+- `password`
+- `secret`
+- `token`
+- `apikey`
+
+### Custom Redaction Patterns
+
+```typescript
+configureRedaction({
+  patterns: [
+    /Bearer [a-zA-Z0-9._-]+/g, // Bearer tokens
+    /sk-[a-zA-Z0-9]{20,}/g, // OpenAI keys
+    /ghp_[a-zA-Z0-9]{36}/g, // GitHub PATs
+  ],
+  keys: ["credentials", "privateKey"],
+});
+```
+
+### Per-Logger Redaction
+
+```typescript
+const logger = createLogger({
+  name: "auth",
+  redaction: {
+    enabled: true,
+    patterns: [/custom-secret-\d+/g],
+    keys: ["myCustomKey"],
+    replacement: "***", // Custom replacement (default: "[REDACTED]")
+  },
+});
+```
+
+### Nested Object Redaction
+
+Redaction is recursive and applies to nested objects:
+
+```typescript
+logger.info("Config loaded", {
+  database: {
+    host: "localhost",
+    password: "super-secret", // Redacted
+  },
+  api: {
+    url: "https://api.example.com",
+    token: "jwt-token", // Redacted
+  },
+});
+// Output: { database: { host: "localhost", password: "[REDACTED]" }, ... }
+```
+
+## Child Loggers
+
+Create scoped loggers that inherit parent configuration and merge context:
+
+```typescript
+const parent = createLogger({
+  name: "app",
+  context: { service: "api" },
+  sinks: [createConsoleSink()],
+  redaction: { enabled: true },
+});
+
+const child = createChildLogger(parent, { handler: "getUser" });
+
+child.info("Processing request");
+// Output includes merged context: { service: "api", handler: "getUser" }
+```
+
+Child loggers:
+
+- Inherit parent's sinks, level, and redaction config
+- Merge context (child overrides parent for conflicting keys)
+- Share the same `setLevel()` and `addSink()` behavior
+
+## Formatters
+
+### JSON Formatter
+
+Machine-readable output for log aggregation:
+
+```typescript
+import { createJsonFormatter } from "@outfitter/logging";
+
+const formatter = createJsonFormatter();
+// Output: {"timestamp":1705936800000,"level":"info","category":"app","message":"Hello","userId":"123"}
+```
+
+### Pretty Formatter
+
+Human-readable output with optional ANSI colors:
+
+```typescript
+import { createPrettyFormatter } from "@outfitter/logging";
+
+const formatter = createPrettyFormatter({ colors: true, timestamp: true });
+// Output: 2024-01-22T12:00:00.000Z [INFO] app: Hello {"userId":"123"}
+```
+
+## Sinks
+
+### Console Sink
+
+Routes logs to stdout/stderr based on level:
+
+- `trace`, `debug`, `info` -> stdout
+- `warn`, `error`, `fatal` -> stderr
+
+```typescript
+import { createConsoleSink } from "@outfitter/logging";
+
+const logger = createLogger({
+  name: "app",
+  sinks: [createConsoleSink()],
+});
+```
+
+### File Sink
+
+Buffered writes to a file path:
+
+```typescript
+import { createFileSink, flush } from "@outfitter/logging";
+
+const logger = createLogger({
+  name: "app",
+  sinks: [createFileSink({ path: "/var/log/app.log" })],
+});
+
+logger.info("Application started");
+
+// Call flush() before exit to ensure all logs are written
+await flush();
+```
+
+### Custom Sinks
+
+Implement the `Sink` interface for custom destinations:
+
+```typescript
+import type { Sink, LogRecord, Formatter } from "@outfitter/logging";
+
+const customSink: Sink = {
+  formatter: createJsonFormatter(), // Optional
+  write(record: LogRecord, formatted?: string): void {
+    // Send to your destination
+    sendToRemote(formatted ?? JSON.stringify(record));
+  },
+  async flush(): Promise<void> {
+    // Optional: ensure pending writes complete
+    await flushPendingWrites();
+  },
+};
+```
+
+### Multiple Sinks
+
+Logs can be sent to multiple destinations:
+
+```typescript
+const logger = createLogger({
+  name: "app",
+  sinks: [
+    createConsoleSink(),
+    createFileSink({ path: "/var/log/app.log" }),
+    customRemoteSink,
+  ],
+});
+```
+
+## Structured Metadata
+
+### Basic Metadata
+
+```typescript
+logger.info("User logged in", {
+  userId: "u123",
+  email: "user@example.com",
+});
+```
+
+### Error Serialization
+
+Error objects are automatically serialized with name, message, and stack:
+
+```typescript
+try {
+  await riskyOperation();
+} catch (error) {
+  logger.error("Operation failed", { error });
+  // error is serialized as: { name: "Error", message: "...", stack: "..." }
+}
+```
+
+### Context Inheritance
+
+Logger context is merged with per-call metadata:
+
+```typescript
+const logger = createLogger({
+  name: "api",
+  context: { requestId: "abc123" },
+  sinks: [createConsoleSink()],
+});
+
+logger.info("Processing", { step: 1 });
+// Metadata: { requestId: "abc123", step: 1 }
+```
+
+## Flushing
+
+Call `flush()` before process exit to ensure buffered logs are written:
+
+```typescript
+import { flush } from "@outfitter/logging";
+
+process.on("beforeExit", async () => {
+  await flush();
+});
+
+// Or before explicit exit
+logger.info("Shutting down");
+await flush();
+process.exit(0);
+```
+
+## API Reference
+
+### Functions
+
+| Function                | Description                                         |
+| ----------------------- | --------------------------------------------------- |
+| `createLogger`          | Create a configured logger instance                 |
+| `createChildLogger`     | Create a child logger with merged context           |
+| `configureRedaction`    | Configure global redaction patterns and keys        |
+| `flush`                 | Flush all pending log writes across all sinks       |
+| `createJsonFormatter`   | Create a JSON formatter for structured output       |
+| `createPrettyFormatter` | Create a human-readable formatter with colors       |
+| `createConsoleSink`     | Create a console sink (stdout/stderr routing)       |
+| `createFileSink`        | Create a file sink with buffered writes             |
+
+### Types
+
+| Type                     | Description                                     |
+| ------------------------ | ----------------------------------------------- |
+| `LogLevel`               | Union of log level strings                      |
+| `LogRecord`              | Structured log record with timestamp/metadata   |
+| `LoggerConfig`           | Configuration options for `createLogger`        |
+| `LoggerInstance`         | Logger interface with level methods             |
+| `RedactionConfig`        | Per-logger redaction configuration              |
+| `GlobalRedactionConfig`  | Global redaction patterns and keys              |
+| `Formatter`              | Interface for log record formatting             |
+| `Sink`                   | Interface for log output destinations           |
+| `PrettyFormatterOptions` | Options for human-readable formatter            |
+| `FileSinkOptions`        | Options for file sink configuration             |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,504 @@
+/**
+* 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)
+*
+* The special level "silent" (6) disables all logging when set as the minimum level.
+*
+* @example
+* ```typescript
+* const level: LogLevel = "info";
+*
+* // Set minimum level to filter logs
+* const logger = createLogger({ name: "app", level: "warn" });
+* logger.debug("Filtered out"); // Not logged
+* logger.warn("Logged");        // Logged
+* ```
+*/
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "silent";
+/**
+* A structured log record containing all information about a log event.
+*
+* Log records are passed to formatters and sinks for processing. They contain
+* the timestamp, level, category (logger name), message, and optional metadata.
+*
+* @example
+* ```typescript
+* const record: LogRecord = {
+*   timestamp: Date.now(),
+*   level: "info",
+*   category: "my-service",
+*   message: "Request processed",
+*   metadata: { duration: 150, status: 200 },
+* };
+* ```
+*/
+interface LogRecord {
+	/** Unix timestamp in milliseconds when the log was created */
+	timestamp: number;
+	/** Severity level of the log (excludes "silent" which is only for filtering) */
+	level: Exclude<LogLevel, "silent">;
+	/** Logger category/name identifying the source (e.g., "my-service", "api") */
+	category: string;
+	/** Human-readable log message describing the event */
+	message: string;
+	/** Optional structured metadata attached to the log for additional context */
+	metadata?: Record<string, unknown>;
+}
+/**
+* Formatter interface for converting log records to strings.
+*
+* Formatters are responsible for serializing log records into output strings.
+* Built-in formatters include JSON (for machine parsing) and pretty (for humans).
+*
+* @example
+* ```typescript
+* const customFormatter: Formatter = {
+*   format(record: LogRecord): string {
+*     return `[${record.level.toUpperCase()}] ${record.category}: ${record.message}`;
+*   },
+* };
+*
+* const sink: Sink = {
+*   formatter: customFormatter,
+*   write(record, formatted) {
+*     console.log(formatted); // "[INFO] app: Hello world"
+*   },
+* };
+* ```
+*/
+interface Formatter {
+	/**
+	* Format a log record into a string representation.
+	*
+	* @param record - The log record to format
+	* @returns Formatted string representation of the log record
+	*/
+	format(record: LogRecord): string;
+}
+/**
+* Sink interface for outputting log records to various destinations.
+*
+* Sinks receive log records and write them to their destination (console, file,
+* remote service, etc.). They can optionally have a formatter to convert records
+* to strings, and a flush method for buffered writes.
+*
+* @example
+* ```typescript
+* const customSink: Sink = {
+*   formatter: createJsonFormatter(),
+*   write(record: LogRecord, formatted?: string): void {
+*     const output = formatted ?? JSON.stringify(record);
+*     sendToRemoteService(output);
+*   },
+*   async flush(): Promise<void> {
+*     await flushPendingRequests();
+*   },
+* };
+* ```
+*/
+interface Sink {
+	/**
+	* Write a log record to the sink's destination.
+	*
+	* @param record - The log record to write
+	* @param formatted - Optional pre-formatted string from the sink's formatter
+	*/
+	write(record: LogRecord, formatted?: string): void;
+	/** Optional formatter specific to this sink for converting records to strings */
+	formatter?: Formatter;
+	/**
+	* Optional async flush to ensure all pending/buffered writes complete.
+	* Called by the global `flush()` function before process exit.
+	*
+	* @returns Promise that resolves when all pending writes are complete
+	*/
+	flush?(): Promise<void>;
+}
+/**
+* Redaction configuration for sensitive data scrubbing.
+*
+* Redaction automatically replaces sensitive values in log metadata to prevent
+* accidental exposure of secrets, tokens, and credentials. Default sensitive keys
+* (password, secret, token, apikey) are always redacted when enabled.
+*
+* @example
+* ```typescript
+* const logger = createLogger({
+*   name: "auth",
+*   redaction: {
+*     enabled: true,
+*     patterns: [/Bearer [a-zA-Z0-9._-]+/g], // Redact Bearer tokens in strings
+*     keys: ["privateKey", "credentials"],   // Additional keys to redact
+*     replacement: "***",                    // Custom replacement text
+*   },
+* });
+* ```
+*/
+interface RedactionConfig {
+	/**
+	* Enable or disable redaction for this logger.
+	* @defaultValue true (when RedactionConfig is provided)
+	*/
+	enabled?: boolean;
+	/** Additional regex patterns to match and redact within string values */
+	patterns?: RegExp[];
+	/** Additional key names whose values should be fully redacted (case-insensitive) */
+	keys?: string[];
+	/**
+	* Replacement string for redacted values.
+	* @defaultValue "[REDACTED]"
+	*/
+	replacement?: string;
+}
+/**
+* Configuration options for creating a logger.
+*
+* Defines the logger's name, minimum level, context, sinks, and redaction settings.
+*
+* @example
+* ```typescript
+* const config: LoggerConfig = {
+*   name: "my-service",
+*   level: "debug",
+*   context: { service: "api", version: "1.0.0" },
+*   sinks: [createConsoleSink(), createFileSink({ path: "/var/log/app.log" })],
+*   redaction: { enabled: true },
+* };
+*
+* const logger = createLogger(config);
+* ```
+*/
+interface LoggerConfig {
+	/** Logger name used as the category in log records */
+	name: string;
+	/**
+	* Minimum log level to output. Messages below this level are filtered.
+	* @defaultValue "info"
+	*/
+	level?: LogLevel;
+	/** Initial context metadata attached to all log records from this logger */
+	context?: Record<string, unknown>;
+	/** Array of sinks to output log records to */
+	sinks?: Sink[];
+	/** Redaction configuration for sensitive data scrubbing */
+	redaction?: RedactionConfig;
+}
+/**
+* Logger instance with methods for each log level.
+*
+* Provides methods for logging at each severity level, plus utilities for
+* runtime configuration changes and context inspection.
+*
+* @example
+* ```typescript
+* const logger = createLogger({ name: "app", sinks: [createConsoleSink()] });
+*
+* logger.info("Server started", { port: 3000 });
+* logger.error("Failed to connect", { error: new Error("timeout") });
+*
+* logger.setLevel("debug"); // Enable debug logging at runtime
+* logger.debug("Debug info", { details: "..." });
+* ```
+*/
+interface LoggerInstance {
+	/**
+	* Log at trace level (most verbose, for detailed debugging).
+	* @param message - Human-readable log message
+	* @param metadata - Optional structured metadata
+	*/
+	trace(message: string, metadata?: Record<string, unknown>): void;
+	/**
+	* 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;
+	/**
+	* 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;
+	/**
+	* 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;
+	/**
+	* 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;
+	/**
+	* 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;
+	/**
+	* Get the current context metadata attached to this logger.
+	* @returns Copy of the logger's context object
+	*/
+	getContext(): Record<string, unknown>;
+	/**
+	* Set the minimum log level at runtime.
+	* @param level - New minimum level (messages below this are filtered)
+	*/
+	setLevel(level: LogLevel): void;
+	/**
+	* Add a sink at runtime.
+	* @param sink - Sink to add to this logger's output destinations
+	*/
+	addSink(sink: Sink): void;
+	/**
+	* Creates a child logger with additional context.
+	*
+	* Context from the child is merged with the parent's context,
+	* with child context taking precedence for duplicate keys.
+	* Child loggers are composable (can create nested children).
+	*
+	* @param context - Additional context to include in all log messages
+	* @returns A new LoggerInstance with the merged context
+	*
+	* @example
+	* ```typescript
+	* const requestLogger = logger.child({ requestId: "abc123" });
+	* requestLogger.info("Processing request"); // includes requestId
+	*
+	* const opLogger = requestLogger.child({ operation: "create" });
+	* opLogger.debug("Starting"); // includes requestId + operation
+	* ```
+	*/
+	child(context: Record<string, unknown>): LoggerInstance;
+}
+/**
+* Options for the pretty (human-readable) formatter.
+*
+* Controls ANSI color output and timestamp inclusion for terminal display.
+*
+* @example
+* ```typescript
+* // Colorized with timestamps (default)
+* const formatter = createPrettyFormatter({ colors: true, timestamp: true });
+*
+* // Plain text without timestamps (for piping)
+* const plainFormatter = createPrettyFormatter({ colors: false, timestamp: false });
+* ```
+*/
+interface PrettyFormatterOptions {
+	/**
+	* Enable ANSI colors in output. Colors are applied per log level:
+	* trace (dim), debug (cyan), info (green), warn (yellow), error (red), fatal (magenta).
+	* @defaultValue false
+	*/
+	colors?: boolean;
+	/**
+	* Include ISO 8601 timestamp in output.
+	* @defaultValue true
+	*/
+	timestamp?: boolean;
+}
+/**
+* Options for the file sink.
+*
+* Configures the file path and append behavior for file-based logging.
+* File sink uses buffered writes - call `flush()` before exit to ensure
+* all logs are written.
+*
+* @example
+* ```typescript
+* const sink = createFileSink({
+*   path: "/var/log/app.log",
+*   append: true, // Append to existing file (default)
+* });
+*
+* // For fresh logs on each run:
+* const freshSink = createFileSink({
+*   path: "/tmp/session.log",
+*   append: false, // Truncate file on start
+* });
+* ```
+*/
+interface FileSinkOptions {
+	/** Absolute path to the log file */
+	path: string;
+	/**
+	* Append to existing file or truncate on start.
+	* @defaultValue true
+	*/
+	append?: boolean;
+}
+/**
+* Global redaction configuration options.
+*
+* Patterns and keys configured globally apply to all loggers that have
+* redaction enabled. Use `configureRedaction()` to add global patterns.
+*
+* @example
+* ```typescript
+* // Configure global patterns that apply to all loggers
+* configureRedaction({
+*   patterns: [
+*     /ghp_[a-zA-Z0-9]{36}/g,  // GitHub PATs
+*     /sk-[a-zA-Z0-9]{20,}/g,   // OpenAI keys
+*   ],
+*   keys: ["privateKey", "credentials"],
+* });
+* ```
+*/
+interface GlobalRedactionConfig {
+	/** Regex patterns to match and redact within string values (applied globally) */
+	patterns?: RegExp[];
+	/** Key names whose values should be fully redacted (case-insensitive, applied globally) */
+	keys?: string[];
+}
+/**
+* Default patterns for redacting secrets from log messages.
+* Applied to message strings and stringified metadata values.
+*
+* Patterns include:
+* - Bearer tokens (Authorization headers)
+* - API key patterns (api_key=xxx, apikey: xxx)
+* - GitHub Personal Access Tokens (ghp_xxx)
+* - GitHub OAuth tokens (gho_xxx)
+* - GitHub App tokens (ghs_xxx)
+* - GitHub refresh tokens (ghr_xxx)
+* - PEM-encoded private keys
+*
+* @example
+* ```typescript
+* import { DEFAULT_PATTERNS } from "@outfitter/logging";
+*
+* // Use with custom logger configuration
+* const logger = createLogger({
+*   name: "app",
+*   redaction: {
+*     enabled: true,
+*     patterns: [...DEFAULT_PATTERNS, /my-custom-secret-\w+/gi],
+*   },
+* });
+* ```
+*/
+declare const DEFAULT_PATTERNS: RegExp[];
+/**
+* Create a configured logger instance.
+*
+* @param config - Logger configuration options
+* @returns Configured LoggerInstance
+*
+* @example
+* ```typescript
+* const logger = createLogger({
+*   name: "my-service",
+*   level: "debug",
+*   redaction: { enabled: true },
+* });
+*
+* logger.info("Server started", { port: 3000 });
+* ```
+*/
+declare function createLogger(config: LoggerConfig): LoggerInstance;
+/**
+* Create a child logger with merged context from a parent logger.
+*
+* @param parent - Parent logger instance
+* @param context - Additional context to merge with parent context
+* @returns Child LoggerInstance with merged context
+*
+* @example
+* ```typescript
+* const parent = createLogger({ name: "app", context: { service: "api" } });
+* const child = createChildLogger(parent, { handler: "getUser" });
+* // child has context: { service: "api", handler: "getUser" }
+* ```
+*/
+declare function createChildLogger(parent: LoggerInstance, context: Record<string, unknown>): LoggerInstance;
+/**
+* Create a JSON formatter for structured log output.
+*
+* @returns Formatter that outputs JSON strings
+*
+* @example
+* ```typescript
+* const formatter = createJsonFormatter();
+* const output = formatter.format(record);
+* // {"timestamp":1705936800000,"level":"info","message":"Hello",...}
+* ```
+*/
+declare function createJsonFormatter(): Formatter;
+/**
+* Create a human-readable formatter with optional colors.
+*
+* @param options - Formatter options
+* @returns Formatter that outputs human-readable strings
+*
+* @example
+* ```typescript
+* const formatter = createPrettyFormatter({ colors: true });
+* const output = formatter.format(record);
+* // 2024-01-22T12:00:00.000Z [INFO] my-service: Hello world
+* ```
+*/
+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.
+*
+* @returns Sink configured for console output
+*
+* @example
+* ```typescript
+* const logger = createLogger({
+*   name: "app",
+*   sinks: [createConsoleSink()],
+* });
+* ```
+*/
+declare function createConsoleSink(): Sink;
+/**
+* Create a file sink that writes to a specified file path.
+*
+* @param options - File sink options
+* @returns Sink configured for file output
+*
+* @example
+* ```typescript
+* const logger = createLogger({
+*   name: "app",
+*   sinks: [createFileSink({ path: "/var/log/app.log" })],
+* });
+* ```
+*/
+declare function createFileSink(options: FileSinkOptions): Sink;
+/**
+* Configure global redaction patterns and keys that apply to all loggers.
+*
+* @param config - Global redaction configuration
+*
+* @example
+* ```typescript
+* configureRedaction({
+*   patterns: [/custom-secret-\d+/g],
+*   keys: ["myCustomKey"],
+* });
+* ```
+*/
+declare function configureRedaction(config: GlobalRedactionConfig): void;
+/**
+* Flush all pending log writes across all sinks.
+* Call this before process exit to ensure all logs are written.
+*
+* @returns Promise that resolves when all sinks have flushed
+*
+* @example
+* ```typescript
+* logger.info("Shutting down");
+* await flush();
+* process.exit(0);
+* ```
+*/
+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 };

package/dist/index.js

@@ -0,0 +1,371 @@
+// src/index.ts
+import { writeFileSync } from "node:fs";
+var LEVEL_PRIORITY = {
+  trace: 0,
+  debug: 1,
+  info: 2,
+  warn: 3,
+  error: 4,
+  fatal: 5,
+  silent: 6
+};
+var DEFAULT_SENSITIVE_KEYS = ["password", "secret", "token", "apikey"];
+var DEFAULT_PATTERNS = [
+  /Bearer\s+[A-Za-z0-9\-_.~+/]+=*/gi,
+  /(?:api[_-]?key|apikey)[=:]\s*["']?[A-Za-z0-9\-_.]+["']?/gi,
+  /ghp_[A-Za-z0-9]{36}/g,
+  /gho_[A-Za-z0-9]{36}/g,
+  /ghs_[A-Za-z0-9]{36}/g,
+  /ghr_[A-Za-z0-9]{36}/g,
+  /-----BEGIN[\s\S]*?PRIVATE\s*KEY-----[\s\S]*?-----END[\s\S]*?PRIVATE\s*KEY-----/gi
+];
+var globalRedactionConfig = {
+  patterns: [],
+  keys: []
+};
+var registeredSinks = new Set;
+function shouldLog(level, minLevel) {
+  if (minLevel === "silent")
+    return false;
+  return LEVEL_PRIORITY[level] >= LEVEL_PRIORITY[minLevel];
+}
+function isRedactedKey(key, additionalKeys) {
+  const lowerKey = key.toLowerCase();
+  const allKeys = [...DEFAULT_SENSITIVE_KEYS, ...additionalKeys];
+  return allKeys.some((k) => lowerKey === k.toLowerCase());
+}
+function applyPatterns(value, patterns, replacement) {
+  let result = value;
+  for (const pattern of patterns) {
+    pattern.lastIndex = 0;
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+function redactValue(value, keys, patterns, replacement, currentKey) {
+  if (currentKey !== undefined && isRedactedKey(currentKey, keys)) {
+    return replacement;
+  }
+  if (typeof value === "string") {
+    return applyPatterns(value, patterns, replacement);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactValue(item, keys, patterns, replacement));
+  }
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: value.message,
+      stack: value.stack
+    };
+  }
+  if (value !== null && typeof value === "object") {
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = redactValue(v, keys, patterns, replacement, k);
+    }
+    return result;
+  }
+  return value;
+}
+function processMetadata(metadata, redactionConfig) {
+  if (!metadata)
+    return;
+  const processed = {};
+  for (const [key, value] of Object.entries(metadata)) {
+    if (value instanceof Error) {
+      processed[key] = {
+        name: value.name,
+        message: value.message,
+        stack: value.stack
+      };
+    } else if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      processed[key] = processNestedForErrors(value);
+    } else {
+      processed[key] = value;
+    }
+  }
+  if (redactionConfig?.enabled === false) {
+    return processed;
+  }
+  const hasGlobalRules = (globalRedactionConfig.patterns?.length ?? 0) > 0 || (globalRedactionConfig.keys?.length ?? 0) > 0;
+  if (redactionConfig || hasGlobalRules) {
+    const allPatterns = [
+      ...DEFAULT_PATTERNS,
+      ...redactionConfig?.patterns ?? [],
+      ...globalRedactionConfig.patterns ?? []
+    ];
+    const allKeys = [
+      ...redactionConfig?.keys ?? [],
+      ...globalRedactionConfig.keys ?? []
+    ];
+    const replacement = redactionConfig?.replacement ?? "[REDACTED]";
+    return redactValue(processed, allKeys, allPatterns, replacement);
+  }
+  return processed;
+}
+function processNestedForErrors(obj) {
+  if (obj instanceof Error) {
+    return {
+      name: obj.name,
+      message: obj.message,
+      stack: obj.stack
+    };
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => {
+      if (item !== null && typeof item === "object") {
+        return processNestedForErrors(item);
+      }
+      return item;
+    });
+  }
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value instanceof Error) {
+      result[key] = {
+        name: value.name,
+        message: value.message,
+        stack: value.stack
+      };
+    } else if (value !== null && typeof value === "object") {
+      result[key] = processNestedForErrors(value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function createLoggerFromState(state) {
+  const log = (level, message, metadata) => {
+    if (!shouldLog(level, state.level))
+      return;
+    const processedMetadata = processMetadata({ ...state.context, ...metadata }, state.redaction);
+    let processedMessage = message;
+    if (state.redaction?.enabled !== false) {
+      const hasGlobalRules = (globalRedactionConfig.patterns?.length ?? 0) > 0 || (globalRedactionConfig.keys?.length ?? 0) > 0;
+      if (state.redaction || hasGlobalRules) {
+        const allPatterns = [
+          ...DEFAULT_PATTERNS,
+          ...state.redaction?.patterns ?? [],
+          ...globalRedactionConfig.patterns ?? []
+        ];
+        const replacement = state.redaction?.replacement ?? "[REDACTED]";
+        processedMessage = applyPatterns(message, allPatterns, replacement);
+      }
+    }
+    const record = {
+      timestamp: Date.now(),
+      level,
+      category: state.name,
+      message: processedMessage,
+      ...processedMetadata !== undefined ? { metadata: processedMetadata } : {}
+    };
+    for (const sink of state.sinks) {
+      try {
+        let formatted;
+        if (sink.formatter) {
+          formatted = sink.formatter.format(record);
+        }
+        sink.write(record, formatted);
+      } catch {}
+    }
+  };
+  return {
+    trace: (message, metadata) => log("trace", message, metadata),
+    debug: (message, metadata) => log("debug", message, metadata),
+    info: (message, metadata) => log("info", message, metadata),
+    warn: (message, metadata) => log("warn", message, metadata),
+    error: (message, metadata) => log("error", message, metadata),
+    fatal: (message, metadata) => log("fatal", message, metadata),
+    getContext: () => ({ ...state.context }),
+    setLevel: (level) => {
+      state.level = level;
+    },
+    addSink: (sink) => {
+      state.sinks.push(sink);
+      registeredSinks.add(sink);
+    },
+    child: (context) => {
+      const childState = {
+        name: state.name,
+        level: state.level,
+        context: { ...state.context, ...context },
+        sinks: state.sinks,
+        redaction: state.redaction
+      };
+      return createLoggerFromState(childState);
+    }
+  };
+}
+function createLogger(config) {
+  const state = {
+    name: config.name,
+    level: config.level ?? "info",
+    context: config.context ?? {},
+    sinks: [...config.sinks ?? []],
+    redaction: config.redaction
+  };
+  for (const sink of state.sinks) {
+    registeredSinks.add(sink);
+  }
+  return createLoggerFromState(state);
+}
+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 }),
+    getContext: () => mergedContext,
+    setLevel: (level) => parent.setLevel(level),
+    addSink: (sink) => parent.addSink(sink),
+    child: (newContext) => createChildLogger(childLogger, newContext)
+  };
+  return childLogger;
+}
+function createJsonFormatter() {
+  return {
+    format(record) {
+      const { timestamp, level, category, message, metadata } = record;
+      const output = {
+        timestamp,
+        level,
+        category,
+        message,
+        ...metadata
+      };
+      return JSON.stringify(output);
+    }
+  };
+}
+function createPrettyFormatter(options) {
+  const useColors = options?.colors ?? false;
+  const showTimestamp = options?.timestamp ?? true;
+  const ANSI = {
+    reset: "\x1B[0m",
+    dim: "\x1B[2m",
+    yellow: "\x1B[33m",
+    red: "\x1B[31m",
+    cyan: "\x1B[36m",
+    green: "\x1B[32m",
+    magenta: "\x1B[35m"
+  };
+  const levelColors = {
+    trace: ANSI.dim,
+    debug: ANSI.cyan,
+    info: ANSI.green,
+    warn: ANSI.yellow,
+    error: ANSI.red,
+    fatal: ANSI.magenta
+  };
+  return {
+    format(record) {
+      const { timestamp, level, category, message, metadata } = record;
+      const isoTime = new Date(timestamp).toISOString();
+      const levelUpper = level.toUpperCase();
+      let output = "";
+      if (showTimestamp) {
+        output += `${isoTime} `;
+      }
+      if (useColors) {
+        const color = levelColors[level];
+        output += `${color}[${levelUpper}]${ANSI.reset} `;
+      } else {
+        output += `[${levelUpper}] `;
+      }
+      output += `${category}: ${message}`;
+      if (metadata && Object.keys(metadata).length > 0) {
+        output += ` ${JSON.stringify(metadata)}`;
+      }
+      return output;
+    }
+  };
+}
+function createConsoleSink() {
+  const formatter = createPrettyFormatter({ colors: true });
+  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);
+      }
+    }
+  };
+  registeredSinks.add(sink);
+  return sink;
+}
+function createFileSink(options) {
+  const formatter = createJsonFormatter();
+  const buffer = [];
+  const { path } = options;
+  const append = options.append ?? true;
+  if (!append) {
+    writeFileSync(path, "");
+  }
+  const sink = {
+    formatter,
+    write(record, formatted) {
+      const output = formatted ?? formatter.format(record);
+      const outputWithNewline = output.endsWith(`
+`) ? output : `${output}
+`;
+      buffer.push(outputWithNewline);
+    },
+    async flush() {
+      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);
+      }
+    }
+  };
+  registeredSinks.add(sink);
+  return sink;
+}
+function configureRedaction(config) {
+  if (config.patterns) {
+    globalRedactionConfig.patterns = [
+      ...globalRedactionConfig.patterns ?? [],
+      ...config.patterns
+    ];
+  }
+  if (config.keys) {
+    globalRedactionConfig.keys = [
+      ...globalRedactionConfig.keys ?? [],
+      ...config.keys
+    ];
+  }
+}
+async function flush() {
+  const flushPromises = [];
+  for (const sink of registeredSinks) {
+    if (sink.flush) {
+      flushPromises.push(sink.flush());
+    }
+  }
+  await Promise.all(flushPromises);
+}
+export {
+  flush,
+  createPrettyFormatter,
+  createLogger,
+  createJsonFormatter,
+  createFileSink,
+  createConsoleSink,
+  createChildLogger,
+  configureRedaction,
+  DEFAULT_PATTERNS
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@outfitter/logging",
+  "description": "Structured logging via logtape with redaction support for Outfitter",
+  "version": "0.1.0-rc.1",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "bunup --filter @outfitter/logging",
+    "lint": "biome lint ./src",
+    "lint:fix": "biome lint --write ./src",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@outfitter/contracts": "workspace:*",
+    "@logtape/logtape": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.8.0"
+  },
+  "keywords": [
+    "outfitter",
+    "logging",
+    "logtape",
+    "structured",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/outfitter-dev/outfitter.git",
+    "directory": "packages/logging"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}