@ontrails/logging 1.0.0-beta.0

package/.turbo/turbo-build.log

@@ -0,0 +1 @@
+$ tsc -b

package/.turbo/turbo-lint.log

@@ -0,0 +1,3 @@
+$ oxlint ./src
+Found 0 warnings and 0 errors.
+Finished in 106ms on 13 files with 93 rules using 24 threads.

package/.turbo/turbo-typecheck.log

@@ -0,0 +1 @@
+$ tsc --noEmit

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @ontrails/logging
+
+## 1.0.0-beta.0
+
+### Minor Changes
+
+- Initial v1 beta release of the Trails framework.
+
+  - **@ontrails/core** — Result type, error taxonomy, trail/hike/event/topo, validateTopo, validateInput/Output, deriveFields, patterns, redaction, branded types, resilience
+  - **@ontrails/cli** — CLI surface adapter, Commander integration, flag derivation, layers
+  - **@ontrails/mcp** — MCP surface adapter, tool generation, annotations, progress bridge
+  - **@ontrails/logging** — Structured logging, sinks, formatters, LogTape adapter
+  - **@ontrails/testing** — testAll, testExamples, testTrail, testHike, testContracts, testDetours, surface harnesses
+  - **@ontrails/warden** — AST-based code convention rules via oxc-parser, drift detection, CI formatters
+  - **@ontrails/schema** — Surface map generation, hashing, semantic diffing
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.0

package/README.md

@@ -0,0 +1,160 @@
+# @ontrails/logging
+
+Structured logging for Trails. One API: `createLogger(config)`. Built-in sinks and formatters, hierarchical category filtering, automatic redaction, and an optional LogTape adapter.
+
+## Installation
+
+```bash
+bun add @ontrails/logging @ontrails/core
+```
+
+For LogTape integration:
+
+```bash
+bun add @logtape/logtape
+```
+
+## Quick Start
+
+```typescript
+import { createLogger } from '@ontrails/logging';
+
+const logger = createLogger({
+  name: 'app.entity',
+  level: 'info',
+});
+
+logger.info('Entity created', { entityId: 'e1', name: 'Alpha' });
+// 10:00:00 INFO  [app.entity] Entity created  entityId=e1 name=Alpha
+```
+
+## API Overview
+
+### `createLogger(config)`
+
+The single entry point. Returns a `Logger` (from `@ontrails/core`) that plugs directly into `TrailContext.logger`.
+
+```typescript
+const logger = createLogger({
+  name: 'app.db.queries',
+  level: 'info',
+  levels: {
+    app: 'info',
+    'app.db': 'debug',
+    'app.http': 'warn',
+  },
+  sinks: [createConsoleSink(), createFileSink({ path: './app.log' })],
+  redaction: { sensitiveKeys: ['password', 'token'] },
+});
+```
+
+### Sinks
+
+A `LogSink` receives formatted log records and writes them somewhere.
+
+```typescript
+import { createConsoleSink, createFileSink } from '@ontrails/logging';
+
+// Console output (default sink)
+createConsoleSink({ formatter: createPrettyFormatter() });
+
+// File output
+createFileSink({ path: './logs/app.log', formatter: createJsonFormatter() });
+```
+
+### Formatters
+
+```typescript
+import { createJsonFormatter, createPrettyFormatter } from '@ontrails/logging';
+
+// Structured JSON -- one object per line, ISO 8601 timestamps
+createJsonFormatter();
+// {"level":"info","message":"Entity created","category":"app.entity","timestamp":"2026-03-25T10:00:00.000Z"}
+
+// Human-readable -- optional ANSI colors, compact metadata
+createPrettyFormatter();
+// 10:00:00 INFO  [app.entity] Entity created  entityId=e1
+```
+
+### Hierarchical Category Filtering
+
+Categories are dot-separated. Level resolution walks up the hierarchy until a match is found:
+
+```typescript
+const logger = createLogger({
+  name: 'app.db.queries',
+  level: 'info', // global fallback
+  levels: {
+    app: 'info',
+    'app.db': 'debug', // matches "app.db.queries"
+    'app.http': 'warn',
+  },
+});
+```
+
+Resolution for `"app.db.queries"`: check exact match, then `"app.db"` (found: `"debug"`), then `"app"`, then `config.level`, then `TRAILS_LOG_LEVEL` env var, then `"info"`.
+
+### Child Loggers
+
+```typescript
+const child = logger.child({ requestId: 'abc-123', trail: 'entity.show' });
+child.info('Processing');
+// Every log record from this child includes requestId and trail metadata
+```
+
+Children inherit the parent's sinks, level config, and redaction. They share the parent's sink pipeline.
+
+### Redaction
+
+Sensitive data is automatically stripped before any sink dispatch. Uses `@ontrails/core/redaction` under the hood.
+
+```typescript
+const logger = createLogger({
+  name: 'app',
+  redaction: {
+    patterns: [/custom-secret-\w+/g],
+    sensitiveKeys: ['password', 'internalToken'],
+  },
+});
+
+logger.info('Auth', { user: 'admin', password: 'hunter2' });
+// password is redacted: "[REDACTED]"
+```
+
+### Environment Configuration
+
+Log level can be set via environment:
+
+1. Explicit `config.level` (highest priority)
+2. `config.levels` hierarchy
+3. `TRAILS_LOG_LEVEL` env var
+4. `TRAILS_ENV` profile defaults (`development` = `"debug"`, `test` = silent)
+5. Fallback: `"info"`
+
+### LogTape Adapter (`@ontrails/logging/logtape`)
+
+Bridge Trails logging to an existing LogTape infrastructure:
+
+```typescript
+import { logtapeSink } from '@ontrails/logging/logtape';
+import { getLogger } from '@logtape/logtape';
+
+const logger = createLogger({
+  name: 'app',
+  sinks: [logtapeSink({ logger: getLogger('app') })],
+});
+```
+
+`@logtape/logtape` is an optional peer dependency. The main package does not depend on it.
+
+## Subpath Exports
+
+| Export | Contents |
+| --- | --- |
+| `@ontrails/logging` | `createLogger`, `createConsoleSink`, `createFileSink`, `createJsonFormatter`, `createPrettyFormatter`, level resolution |
+| `@ontrails/logging/logtape` | `logtapeSink` adapter (requires `@logtape/logtape` peer) |
+
+## Further Reading
+
+- [Getting Started](../../docs/getting-started.md)
+- [Architecture](../../docs/architecture.md)

package/dist/env.d.ts

@@ -0,0 +1,13 @@
+import type { LogLevel } from './types.js';
+/**
+ * Resolve log level from environment variables.
+ *
+ * 1. `TRAILS_LOG_LEVEL` -- explicit override (if valid).
+ * 2. `TRAILS_ENV` profile defaults:
+ *    - `development` -> `"debug"`
+ *    - `test` -> `undefined` (no logging by default)
+ *    - `production` -> `undefined` (caller falls through to `"info"`)
+ * 3. `undefined` -- no env-based level configured.
+ */
+export declare const resolveLogLevel: (env?: Record<string, string | undefined>) => LogLevel | undefined;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAe3C;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC1B,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KACvC,QAAQ,GAAG,SAoBb,CAAC"}

package/dist/env.js

@@ -0,0 +1,38 @@
+import { LEVEL_PRIORITY } from './levels.js';
+// ---------------------------------------------------------------------------
+// Valid log level set (for validation)
+// ---------------------------------------------------------------------------
+const VALID_LEVELS = new Set(Object.keys(LEVEL_PRIORITY));
+const isValidLogLevel = (value) => VALID_LEVELS.has(value);
+// ---------------------------------------------------------------------------
+// resolveLogLevel
+// ---------------------------------------------------------------------------
+/**
+ * Resolve log level from environment variables.
+ *
+ * 1. `TRAILS_LOG_LEVEL` -- explicit override (if valid).
+ * 2. `TRAILS_ENV` profile defaults:
+ *    - `development` -> `"debug"`
+ *    - `test` -> `undefined` (no logging by default)
+ *    - `production` -> `undefined` (caller falls through to `"info"`)
+ * 3. `undefined` -- no env-based level configured.
+ */
+export const resolveLogLevel = (env) => {
+    const source = env ?? process.env;
+    // 1. Explicit override
+    const explicit = source['TRAILS_LOG_LEVEL'];
+    if (explicit !== undefined && isValidLogLevel(explicit)) {
+        return explicit;
+    }
+    // 2. Profile defaults
+    const profile = source['TRAILS_ENV'];
+    if (profile === 'development') {
+        return 'debug';
+    }
+    if (profile === 'test') {
+        return undefined;
+    }
+    // production and everything else -- no opinion
+    return undefined;
+};
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E,MAAM,YAAY,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;AAElE,MAAM,eAAe,GAAG,CAAC,KAAa,EAAqB,EAAE,CAC3D,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAE1B,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,GAAwC,EAClB,EAAE;IACxB,MAAM,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IAElC,uBAAuB;IACvB,MAAM,QAAQ,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC;IAC5C,IAAI,QAAQ,KAAK,SAAS,IAAI,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,sBAAsB;IACtB,MAAM,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;IACrC,IAAI,OAAO,KAAK,aAAa,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,+CAA+C;IAC/C,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC"}

package/dist/formatters.d.ts

@@ -0,0 +1,8 @@
+import type { LogFormatter, PrettyFormatterOptions } from './types.js';
+/**
+ * One JSON object per log record, newline-delimited.
+ * Metadata fields are flattened into the top-level object.
+ */
+export declare const createJsonFormatter: () => LogFormatter;
+export declare const createPrettyFormatter: (options?: PrettyFormatterOptions) => LogFormatter;
+//# sourceMappingURL=formatters.d.ts.map

package/dist/formatters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../src/formatters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EAEZ,sBAAsB,EACvB,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAO,YAYrC,CAAC;AAoDH,eAAO,MAAM,qBAAqB,GAChC,UAAU,sBAAsB,KAC/B,YAoBF,CAAC"}

package/dist/formatters.js

@@ -0,0 +1,72 @@
+// ---------------------------------------------------------------------------
+// JSON Formatter
+// ---------------------------------------------------------------------------
+/**
+ * One JSON object per log record, newline-delimited.
+ * Metadata fields are flattened into the top-level object.
+ */
+export const createJsonFormatter = () => ({
+    format(record) {
+        const { level, message, category, timestamp, metadata } = record;
+        const obj = {
+            category,
+            level,
+            message,
+            timestamp: timestamp.toISOString(),
+            ...metadata,
+        };
+        return JSON.stringify(obj);
+    },
+});
+// ---------------------------------------------------------------------------
+// Pretty Formatter
+// ---------------------------------------------------------------------------
+const LEVEL_COLORS = {
+    debug: '\u001B[36m',
+    error: '\u001B[31m',
+    fatal: '\u001B[35m',
+    info: '\u001B[32m',
+    trace: '\u001B[90m',
+    warn: '\u001B[33m',
+};
+const RESET = '\u001B[0m';
+const formatMetadata = (metadata) => {
+    const entries = Object.entries(metadata);
+    if (entries.length === 0) {
+        return '';
+    }
+    return `  ${entries
+        .map(([k, v]) => {
+        const display = typeof v === 'string' ? v : JSON.stringify(v);
+        return `${k}=${display}`;
+    })
+        .join(' ')}`;
+};
+/**
+ * Human-readable formatter.
+ *
+ * Output: `10:00:00 INFO  [app.entity] Entity created  requestId=abc-123`
+ */
+const formatTimestamp = (timestamp) => `${timestamp.toISOString().slice(11, 19)} `;
+const formatLevelAndMessage = (level, levelLabel, category, message, useColors) => {
+    if (useColors) {
+        const color = LEVEL_COLORS[level] ?? '';
+        return `${color}${levelLabel}${RESET} [${category}] ${message}`;
+    }
+    return `${levelLabel} [${category}] ${message}`;
+};
+export const createPrettyFormatter = (options) => {
+    const showTimestamps = options?.timestamps !== false;
+    const useColors = options?.colors ?? process.stdout?.isTTY === true;
+    return {
+        format(record) {
+            const { level, message, category, timestamp, metadata } = record;
+            const levelLabel = level.toUpperCase().padEnd(5);
+            const meta = formatMetadata(metadata);
+            const prefix = showTimestamps ? formatTimestamp(timestamp) : '';
+            const body = formatLevelAndMessage(level, levelLabel, category, message, useColors);
+            return meta.length > 0 ? `${prefix}${body}${meta}` : `${prefix}${body}`;
+        },
+    };
+};
+//# sourceMappingURL=formatters.js.map

package/dist/formatters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.js","sourceRoot":"","sources":["../src/formatters.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createLogger } from './logger.js';
+export type { Logger } from '@ontrails/core';
+export { createConsoleSink, createFileSink } from './sinks.js';
+export { createJsonFormatter, createPrettyFormatter } from './formatters.js';
+export { resolveLogLevel } from './env.js';
+export { LEVEL_PRIORITY, shouldLog, resolveCategory } from './levels.js';
+export type { LogLevel, LogMetadata, LogRecord, LoggerConfig, LogSink, LogFormatter, ConsoleSinkOptions, FileSinkOptions, PrettyFormatterOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAG7C,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG7E,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG3C,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGzE,YAAY,EACV,QAAQ,EACR,WAAW,EACX,SAAS,EACT,YAAY,EACZ,OAAO,EACP,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,sBAAsB,GACvB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// Logger
+export { createLogger } from './logger.js';
+// Sinks and formatters
+export { createConsoleSink, createFileSink } from './sinks.js';
+export { createJsonFormatter, createPrettyFormatter } from './formatters.js';
+// Level resolution
+export { resolveLogLevel } from './env.js';
+// Levels
+export { LEVEL_PRIORITY, shouldLog, resolveCategory } from './levels.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAK3C,uBAAuB;AACvB,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE7E,mBAAmB;AACnB,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3C,SAAS;AACT,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/levels.d.ts

@@ -0,0 +1,9 @@
+import type { LogLevel } from './types.js';
+export declare const LEVEL_PRIORITY: Record<LogLevel, number>;
+/**
+ * Returns true if a message at `messageLevel` should be emitted given the
+ * configured threshold `configuredLevel`.
+ */
+export declare const shouldLog: (messageLevel: LogLevel, configuredLevel: LogLevel) => boolean;
+export declare const resolveCategory: (name: string, levels: Record<string, LogLevel> | undefined, fallback: LogLevel) => LogLevel;
+//# sourceMappingURL=levels.d.ts.map

package/dist/levels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"levels.d.ts","sourceRoot":"","sources":["../src/levels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAM3C,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAQnD,CAAC;AAMF;;;GAGG;AACH,eAAO,MAAM,SAAS,GACpB,cAAc,QAAQ,EACtB,iBAAiB,QAAQ,KACxB,OAA0E,CAAC;AAgC9E,eAAO,MAAM,eAAe,GAC1B,MAAM,MAAM,EACZ,QAAQ,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,SAAS,EAC5C,UAAU,QAAQ,KACjB,QAKF,CAAC"}

package/dist/levels.js

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// Level Priority
+// ---------------------------------------------------------------------------
+export const LEVEL_PRIORITY = {
+    debug: 1,
+    error: 4,
+    fatal: 5,
+    info: 2,
+    silent: 6,
+    trace: 0,
+    warn: 3,
+};
+// ---------------------------------------------------------------------------
+// shouldLog
+// ---------------------------------------------------------------------------
+/**
+ * Returns true if a message at `messageLevel` should be emitted given the
+ * configured threshold `configuredLevel`.
+ */
+export const shouldLog = (messageLevel, configuredLevel) => LEVEL_PRIORITY[messageLevel] >= LEVEL_PRIORITY[configuredLevel];
+// ---------------------------------------------------------------------------
+// resolveCategory
+// ---------------------------------------------------------------------------
+/**
+ * Walk up the dot-separated category hierarchy to find the most specific
+ * configured level.
+ *
+ * Example: "app.db.queries" -> "app.db" -> "app" -> fallback
+ */
+/** Walk up the dot-separated hierarchy looking for a configured level. */
+const findLevel = (name, levels) => {
+    let prefix = name;
+    while (prefix.length > 0) {
+        const level = levels[prefix];
+        if (level !== undefined) {
+            return level;
+        }
+        const lastDot = prefix.lastIndexOf('.');
+        if (lastDot === -1) {
+            break;
+        }
+        prefix = prefix.slice(0, lastDot);
+    }
+    return undefined;
+};
+export const resolveCategory = (name, levels, fallback) => {
+    if (!levels) {
+        return fallback;
+    }
+    return findLevel(name, levels) ?? fallback;
+};
+//# sourceMappingURL=levels.js.map

package/dist/levels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"levels.js","sourceRoot":"","sources":["../src/levels.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,cAAc,GAA6B;IACtD,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;CACR,CAAC;AAEF,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,YAAsB,EACtB,eAAyB,EAChB,EAAE,CAAC,cAAc,CAAC,YAAY,CAAC,IAAI,cAAc,CAAC,eAAe,CAAC,CAAC;AAE9E,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;;;GAKG;AACH,0EAA0E;AAC1E,MAAM,SAAS,GAAG,CAChB,IAAY,EACZ,MAAgC,EACV,EAAE;IACxB,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC;YACnB,MAAM;QACR,CAAC;QACD,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,IAAY,EACZ,MAA4C,EAC5C,QAAkB,EACR,EAAE;IACZ,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,QAAQ,CAAC;AAC7C,CAAC,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,10 @@
+import type { Logger } from '@ontrails/core';
+import type { LoggerConfig } from './types.js';
+/**
+ * Create a structured logger with hierarchical category filtering,
+ * automatic redaction, and pluggable sinks.
+ *
+ * This is the **only** API for creating loggers in `@ontrails/logging`.
+ */
+export declare const createLogger: (config: LoggerConfig) => Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAK7C,OAAO,KAAK,EAGV,YAAY,EAGb,MAAM,YAAY,CAAC;AAwFpB;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,YAAY,KAAG,MAuBnD,CAAC"}

package/dist/logger.js

@@ -0,0 +1,80 @@
+import { createRedactor, DEFAULT_PATTERNS, DEFAULT_SENSITIVE_KEYS, } from '@ontrails/core/redaction';
+import { resolveLogLevel } from './env.js';
+import { resolveCategory, shouldLog } from './levels.js';
+import { createConsoleSink } from './sinks.js';
+const buildInstance = (name, effectiveLevel, redactor, sinks, 
+// oxlint-disable-next-line only-used-in-recursion
+config, baseMetadata) => {
+    const log = (level, message, metadata) => {
+        if (!shouldLog(level, effectiveLevel)) {
+            return;
+        }
+        const mergedMeta = {
+            ...baseMetadata,
+            ...metadata,
+        };
+        const record = {
+            category: name,
+            level,
+            message: redactor.redact(message),
+            metadata: Object.keys(mergedMeta).length > 0
+                ? redactor.redactObject(mergedMeta)
+                : {},
+            timestamp: new Date(),
+        };
+        for (const sink of sinks) {
+            sink.write(record);
+        }
+    };
+    return {
+        child(metadata) {
+            return buildInstance(name, effectiveLevel, redactor, sinks, config, {
+                ...baseMetadata,
+                ...metadata,
+            });
+        },
+        debug(message, metadata) {
+            log('debug', message, metadata);
+        },
+        error(message, metadata) {
+            log('error', message, metadata);
+        },
+        fatal(message, metadata) {
+            log('fatal', message, metadata);
+        },
+        info(message, metadata) {
+            log('info', message, metadata);
+        },
+        name,
+        trace(message, metadata) {
+            log('trace', message, metadata);
+        },
+        warn(message, metadata) {
+            log('warn', message, metadata);
+        },
+    };
+};
+// ---------------------------------------------------------------------------
+// createLogger
+// ---------------------------------------------------------------------------
+/**
+ * Create a structured logger with hierarchical category filtering,
+ * automatic redaction, and pluggable sinks.
+ *
+ * This is the **only** API for creating loggers in `@ontrails/logging`.
+ */
+export const createLogger = (config) => {
+    const envLevel = resolveLogLevel();
+    const baseLevel = config.level ?? envLevel ?? 'info';
+    const effectiveLevel = resolveCategory(config.name, config.levels, baseLevel);
+    const redactor = createRedactor({
+        patterns: [...DEFAULT_PATTERNS, ...(config.redaction?.patterns ?? [])],
+        sensitiveKeys: [
+            ...DEFAULT_SENSITIVE_KEYS,
+            ...(config.redaction?.sensitiveKeys ?? []),
+        ],
+    });
+    const sinks = config.sinks ?? [createConsoleSink()];
+    return buildInstance(config.name, effectiveLevel, redactor, sinks, { baseLevel, levels: config.levels }, {});
+};
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/logtape/index.d.ts

@@ -0,0 +1,24 @@
+import type { LogSink } from '../types.js';
+/**
+ * Subset of the logtape Logger interface that we forward records to.
+ * Accepts any object that provides the standard log-level methods.
+ */
+export interface LogtapeLoggerLike {
+    trace(message: string, props?: Record<string, unknown>): void;
+    debug(message: string, props?: Record<string, unknown>): void;
+    info(message: string, props?: Record<string, unknown>): void;
+    warn(message: string, props?: Record<string, unknown>): void;
+    error(message: string, props?: Record<string, unknown>): void;
+    fatal(message: string, props?: Record<string, unknown>): void;
+}
+export interface LogtapeSinkOptions {
+    /** An existing logtape logger (or compatible object) to forward records to. */
+    readonly logger: LogtapeLoggerLike;
+}
+/**
+ * Sink adapter that forwards `LogRecord` instances to an existing logtape
+ * logger. Redaction runs _before_ the sink receives records, so sensitive
+ * data is scrubbed regardless of the backend.
+ */
+export declare const logtapeSink: (options: LogtapeSinkOptions) => LogSink;
+//# sourceMappingURL=index.d.ts.map

package/dist/logtape/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logtape/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,OAAO,EAAE,MAAM,aAAa,CAAC;AAMtD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC/D;AAMD,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAiBD;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,kBAAkB,KAAG,OAmBzD,CAAC"}

package/dist/logtape/index.js

@@ -0,0 +1,31 @@
+const LEVEL_MAP = {
+    debug: 'debug',
+    error: 'error',
+    fatal: 'fatal',
+    info: 'info',
+    trace: 'trace',
+    warn: 'warn',
+};
+/**
+ * Sink adapter that forwards `LogRecord` instances to an existing logtape
+ * logger. Redaction runs _before_ the sink receives records, so sensitive
+ * data is scrubbed regardless of the backend.
+ */
+export const logtapeSink = (options) => {
+    const { logger } = options;
+    return {
+        name: 'logtape',
+        write(record) {
+            const method = LEVEL_MAP[record.level];
+            if (method === undefined) {
+                return;
+            }
+            const props = {
+                category: record.category,
+                ...record.metadata,
+            };
+            logger[method](record.message, props);
+        },
+    };
+};
+//# sourceMappingURL=index.js.map

package/dist/logtape/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/logtape/index.ts"],"names":[],"mappings":"AAkCA,MAAM,SAAS,GAAkC;IAC/C,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,MAAM;CACb,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAA2B,EAAW,EAAE;IAClE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAE3B,OAAO;QACL,IAAI,EAAE,SAAS;QACf,KAAK,CAAC,MAAiB;YACrB,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,OAAO;YACT,CAAC;YAED,MAAM,KAAK,GAA4B;gBACrC,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,GAAG,MAAM,CAAC,QAAQ;aACnB,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACxC,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/sinks.d.ts

@@ -0,0 +1,13 @@
+import type { ConsoleSinkOptions, FileSinkOptions, LogSink } from './types.js';
+/**
+ * Sink that writes to `console.*` methods.
+ *
+ * By default, uses `createPrettyFormatter()` when `TRAILS_ENV` is
+ * `"development"` and `createJsonFormatter()` otherwise.
+ */
+export declare const createConsoleSink: (options?: ConsoleSinkOptions) => LogSink;
+/**
+ * Sink that appends log records to a file using `Bun.file()`.
+ */
+export declare const createFileSink: (options: FileSinkOptions) => LogSink;
+//# sourceMappingURL=sinks.d.ts.map

package/dist/sinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sinks.d.ts","sourceRoot":"","sources":["../src/sinks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EAEf,OAAO,EACR,MAAM,YAAY,CAAC;AAepB;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,kBAAkB,KAAG,OAoBhE,CAAC;AAMF;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,eAAe,KAAG,OAczD,CAAC"}