@warlock.js/logger 5.30.0 → 5.32.0

package/llms.txt

@@ -9,11 +9,11 @@
 - [capture-unhandled-errors](@warlock.js/logger/capture-unhandled-errors/SKILL.md): captureAnyUnhandledRejection() installs process.on('unhandledRejection') → log.error and process.on('uncaughtException') → log.fatal + process.exit(1) so process-level failures land in your channels and a fatal crash is never silently swallowed into exit 0. Triggers: `captureAnyUnhandledRejection`, `exitOnUncaughtException`, `unhandledRejection`, `uncaughtException`, `log.error`, `log.fatal`; "log unhandled promise rejections", "catch uncaught exceptions to a file", "record crashes before exit", "server exits 0 with no error", "silent exit / production server stopped", "global error handler with logger"; typical import `import { captureAnyUnhandledRejection, log } from "@warlock.js/logger"`. Skip: flushing — the `flush-logs-on-shutdown` topic; filtering — the `filter-log-entries` topic; competing `Sentry.init`, `@sentry/node`; native `process.on('unhandledRejection')`.
 - [configure-logger](@warlock.js/logger/configure-logger/SKILL.md): Register channels via log.addChannel / log.setChannels / log.configure({channels, autoFlushOn, redact, minLevel}) at boot. Triggers: `log.configure`, `log.addChannel`, `log.setChannels`, `Logger`, `autoFlushOn`, `disableAutoFlush`; "wire channels at startup", "branch logger by NODE_ENV", "isolate a library's logger", "replace channel list"; typical import `import { log, Logger, ConsoleLog, FileLog } from "@warlock.js/logger"`. Skip: channel picks — the `pick-log-channel` topic; flushing — the `flush-logs-on-shutdown` topic; redaction — the `redact-sensitive-log-fields` topic; competing libs `winston.createLogger`, `pino`.
 - [filter-log-entries](@warlock.js/logger/filter-log-entries/SKILL.md): Drop log entries — per-channel levels whitelist, per-channel filter predicate, logger-wide setMinLevel(level) fast path. Triggers: `levels`, `filter`, `minLevel`, `log.setMinLevel`, `shouldBeLogged`, `LoggingData`, `LogLevel`; "silence a noisy module", "route errors to a dedicated file", "raise global severity floor", "drop debug logs in prod"; typical import `import { log } from "@warlock.js/logger"`. Skip: custom sinks — the `write-custom-log-channel` topic; channel picks — the `pick-log-channel` topic; competing libs `pino.levels`, `winston.format.filter`, `debug` env var.
-- [flush-logs-on-shutdown](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md): Drain buffered channels before exit — log.flushSync() or log.configure({autoFlushOn: ['SIGINT', 'SIGTERM', 'beforeExit']}) installs handlers that re-raise the signal. Triggers: `log.flush`, `log.flushSync`, `autoFlushOn`, `enableAutoFlush`, `disableAutoFlush`, `SIGINT`, `SIGTERM`, `beforeExit`; "drain logs before exit", "await log.flush() before process.exit", "drain async or network channels on shutdown", "wire SIGTERM for container shutdown", "my logs never showed after a crash", "graceful shutdown logging"; typical import `import { log, FileLog } from "@warlock.js/logger"`. Skip: error capture — the `capture-unhandled-errors` topic; custom sinks — the `write-custom-log-channel` topic; competing `pino.final`, `winston.end`; native `process.on('exit')`.
+- [flush-logs-on-shutdown](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md): Drain buffered channels before exit — log.flushSync() or log.configure({autoFlushOn: ['SIGINT', 'SIGTERM', 'beforeExit']}) installs handlers that re-raise the signal. Triggers: `log.flush`, `log.flushSync`, `onChannelError`, `log.flush({ timeout })`, `autoFlushOn`, `enableAutoFlush`, `disableAutoFlush`, `SIGINT`, `SIGTERM`, `beforeExit`; "drain logs before exit", "await log.flush() before process.exit", "drain async or network channels on shutdown", "wire SIGTERM for container shutdown", "my logs never showed after a crash", "graceful shutdown logging"; typical import `import { log, FileLog } from "@warlock.js/logger"`. Skip: error capture — the `capture-unhandled-errors` topic; custom sinks — the `write-custom-log-channel` topic; competing `pino.final`, `winston.end`; native `process.on('exit')`.
 - [logger-basics](@warlock.js/logger/logger-basics/SKILL.md): Start here for @warlock.js/logger channels, structured entries, transports, and application logging setup.
 - [overview](@warlock.js/logger/overview/SKILL.md): @warlock.js/logger overview for orientation and choosing the focused skill for the task.
 - [pick-log-channel](@warlock.js/logger/pick-log-channel/SKILL.md): Pick one of the four built-in channels — ConsoleLog (terminal), FileLog (plain text on disk), JSONFileLog (structured JSON for aggregators like Loki / Datadog / Elastic), SentryLog (forwards errors + breadcrumbs to Sentry). Triggers: `ConsoleLog`, `FileLog`, `JSONFileLog`, `SentryLog`, `chunk`, `rotate`, `groupBy`, `maxFileSize`, `showContext`, `log.channel`; "log to a file", "rotate log files", "daily log chunks", "json logs for datadog / loki / elastic", "send logs to Sentry"; typical import `import { ConsoleLog, FileLog, JSONFileLog, SentryLog } from "@warlock.js/logger"`. Skip: Sentry-specific setup — the `ship-logs-to-sentry` topic; custom sinks — the `write-custom-log-channel` topic; registration — the `configure-logger` topic; competing libs `winston-daily-rotate-file`, `pino-pretty`.
-- [redact-sensitive-log-fields](@warlock.js/logger/redact-sensitive-log-fields/SKILL.md): Strip secrets from log output — a built-in secret-key denylist on by default (DEFAULT_REDACT_KEYS), plus two-layer additive redaction via log.configure({redact: {paths, keys}}) (logger floor) + per-channel redact (more on top). Dotted glob paths (*, **). Triggers: `redact`, `paths`, `keys`, `defaultKeys`, `censor`, `log.setRedact`, `applyRedact`; "redact passwords in logs", "strip tokens from log output", "hide authorization headers", "scrub PII before logging", "turn off default redaction"; typical import `import { log } from "@warlock.js/logger"`. Skip: filtering — the `filter-log-entries` topic; custom sinks — the `write-custom-log-channel` topic; competing libs `pino.redact`, `fast-redact`.
+- [redact-sensitive-log-fields](@warlock.js/logger/redact-sensitive-log-fields/SKILL.md): Strip secrets from log output — a built-in secret-key denylist on by default (DEFAULT_REDACT_KEYS), plus two-layer additive redaction via log.configure({redact: {paths, keys}}) (logger floor) + per-channel redact (more on top). Dotted glob paths (*, **). Triggers: `redact`, `paths`, `keys`, `defaultKeys`, `censor`, `log.setRedact`, `applyRedact`, `maskEmail`, `maskEmailsInText`; "redact passwords in logs", "strip tokens from log output", "hide authorization headers", "scrub PII before logging", "turn off default redaction"; typical import `import { log } from "@warlock.js/logger"`. Skip: filtering — the `filter-log-entries` topic; custom sinks — the `write-custom-log-channel` topic; competing libs `pino.redact`, `fast-redact`.
 - [ship-logs-to-sentry](@warlock.js/logger/ship-logs-to-sentry/SKILL.md): Forward log entries to Sentry with the SentryLog channel — error/warn become events (captureException/captureMessage), every other level a breadcrumb (no quota). @sentry/node is an OPTIONAL peer, lazily imported. Triggers: `SentryLog`, `@sentry/node`, `eventLevels`, `flushTimeout`, `Sentry.flush`, `captureException`, `addBreadcrumb`, `withScope`; "send logs to Sentry", "report errors to Sentry", "Sentry log channel", "Sentry breadcrumbs from logs", "log channel for Sentry"; typical import `import { SentryLog } from "@warlock.js/logger"`. Skip: file/console channels — the `pick-log-channel` topic; custom sinks — the `write-custom-log-channel` topic; graceful-shutdown flushing — the `flush-logs-on-shutdown` topic; Slack alerting recipe.
 - [test-logging-code](@warlock.js/logger/test-logging-code/SKILL.md): Test code that touches the logger — silence globally via log.setChannels([]) in setupFiles, assert specific log lines via a capturing LogChannel subclass (prefer it over vi.spyOn — it asserts on delivered entries, not just method calls, and isolates the shared singleton cleanly). Triggers: `log.setChannels`, `LogChannel`, `LoggingData`, `Logger`, `log.channels`; "silence logger in vitest", "assert a log line was emitted", "capture log output in tests", "test code that logs"; typical import `import { log, Logger, LogChannel, type LoggingData } from "@warlock.js/logger"`. Skip: custom sinks — the `write-custom-log-channel` topic; filtering — the `filter-log-entries` topic; competing `vi.spyOn(console)`, `jest.spyOn`.
 - [use-log-helpers](@warlock.js/logger/use-log-helpers/SKILL.md): Two DX shortcuts on every Logger — log.assert(condition, module, action, message, context?) logs an error when condition is falsy (free on the happy path), log.timer(module, action) returns an end-function emitting an info entry with measured duration. Triggers: `log.assert`, `log.timer`, `durationMs`; "assert an invariant via logger", "measure how long an operation took", "time a request", "log operation duration"; typical import `import { log } from "@warlock.js/logger"`. Skip: basics — the `logger-basics` topic; filtering — the `filter-log-entries` topic; competing `console.assert`, `console.time`, `console.timeEnd`, `perf_hooks.performance.now`.

package/package.json

@@ -4,7 +4,7 @@
   "dependencies": {
     "@mongez/copper": "^2.1.3",
     "@mongez/reinforcements": "^4.0.2",
-    "@warlock.js/fs": "5.30.0",
+    "@warlock.js/fs": "5.32.0",
     "dayjs": "^1.11.9",
     "safe-stable-stringify": "^2.5.0"
   },
@@ -33,7 +33,7 @@
   "warlock": {
     "environment": "server"
   },
-  "version": "5.30.0",
+  "version": "5.32.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/capture-unhandled-errors/SKILL.md

@@ -16,6 +16,7 @@ captureAnyUnhandledRejection();
 ```
 
 Registers:
+
 - `process.on("unhandledRejection", reason => log.error("app", "unhandledRejection", reason))` — logged; the process is kept alive.
 - `process.on("uncaughtException", error => log.fatal("app", "uncaughtException", error))` — logged, then `process.exit(1)` (by default).
 
@@ -23,7 +24,7 @@ The split is intentional: an `uncaughtException` leaves the process in an undefi
 
 ## Why it exits (and why that matters)
 
-Registering *any* `uncaughtException` listener **suppresses** Node's default "print the stack + exit non-zero." A listener that only logs therefore turns an unrecoverable crash into a silent `exit 0` — which is exactly how a config file that throws at boot can look like "the server started, then just stopped," with no error printed. So the handler restores the contract:
+Registering _any_ `uncaughtException` listener **suppresses** Node's default "print the stack + exit non-zero." A listener that only logs therefore turns an unrecoverable crash into a silent `exit 0` — which is exactly how a config file that throws at boot can look like "the server started, then just stopped," with no error printed. So the handler restores the contract:
 
 - **Exits non-zero** after logging (`process.exit(1)`), following a best-effort, time-bounded `log.flush()` so buffered `FileLog` / `SentryLog` entries drain first. Opt out with `captureAnyUnhandledRejection({ exitOnUncaughtException: false })` where the process is expected to recover on its own (a dev server reloading via HMR).
 - **Falls back to `console.error`** when no terminal channel is configured yet — the early-boot window, before `log.configure(...)`, where `log.fatal` has nowhere visible to go. When a `ConsoleLog` is present it already prints the entry, so the fallback is skipped (no double output).
@@ -35,16 +36,11 @@ Registering *any* `uncaughtException` listener **suppresses** Node's default "pr
 **Once**, at startup, **after** channels are registered. Typical place: immediately after your `log.configure({...})` call.
 
 ```ts title="src/index.ts"
-import {
-  log,
-  ConsoleLog,
-  FileLog,
-  captureAnyUnhandledRejection,
-} from "@warlock.js/logger";
+import { log, ConsoleLog, FileLog, captureAnyUnhandledRejection } from "@warlock.js/logger";
 
 log.configure({
   channels: [new ConsoleLog(), new FileLog({ levels: ["error"] })],
-  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],   // ← important; see below
+  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"], // ← important; see below
 });
 
 captureAnyUnhandledRejection();
@@ -54,7 +50,7 @@ captureAnyUnhandledRejection();
 
 The `uncaughtException` handler runs a best-effort, time-bounded `log.flush()` **before** its own `process.exit(1)`, so buffered `FileLog` / `SentryLog` entries drain even though `process.exit()` skips `beforeExit`. You don't need `autoFlushOn: ["beforeExit"]` for the fatal entry to survive — the handler already drains.
 
-`"beforeExit"` in `autoFlushOn` is still worth setting for the *other* exit routes (a natural drain when the event loop empties on its own). For signal-driven shutdown (`SIGINT` / `SIGTERM`), include those signals in `autoFlushOn`. See the `flush-logs-on-shutdown` topic.
+`"beforeExit"` in `autoFlushOn` is still worth setting for the _other_ exit routes (a natural drain when the event loop empties on its own). For signal-driven shutdown (`SIGINT` / `SIGTERM`), include those signals in `autoFlushOn`. See the `flush-logs-on-shutdown` topic.
 
 ## Idempotency — don't call it twice
 
@@ -79,7 +75,9 @@ import type { LoggingData } from "@warlock.js/logger";
 class Capture extends LogChannel {
   public name = "capture";
   public received: LoggingData[] = [];
-  public log(data: LoggingData) { this.received.push({ ...data }); }
+  public log(data: LoggingData) {
+    this.received.push({ ...data });
+  }
 }
 
 it("routes unhandled rejections to the logger", async () => {
@@ -104,6 +102,7 @@ Testing the **`uncaughtException`** path additionally trips `process.exit(1)`, s
 ## Module + action the capture uses
 
 Both listeners log with:
+
 - `module: "app"`
 - `action: "unhandledRejection"` (at `error`) or `action: "uncaughtException"` (at `fatal`)
 - `message`: the rejection reason / exception (keep it as the raw `Error` object — file channels capture the stack).

package/skills/configure-logger/SKILL.md

@@ -9,10 +9,10 @@ The logger is a singleton. Do all setup in one place, as early in the app entry
 
 ## The three channel-registration methods
 
-| Method | Semantics |
-|---|---|
-| `log.addChannel(channel)` | **Appends.** Safe to call multiple times. |
-| `log.setChannels([...])` | **Replaces** the full list. |
+| Method                                                       | Semantics                                                                                                                      |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `log.addChannel(channel)`                                    | **Appends.** Safe to call multiple times.                                                                                      |
+| `log.setChannels([...])`                                     | **Replaces** the full list.                                                                                                    |
 | `log.configure({ channels, autoFlushOn, redact, minLevel })` | **Replaces** channels if provided; installs auto-flush if provided; sets redact / minLevel if provided. All four are optional. |
 
 All three return `this` — chainable.
@@ -31,7 +31,7 @@ if (process.env.NODE_ENV === "production") {
     autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
   });
 } else if (process.env.NODE_ENV === "test") {
-  log.setChannels([]);   // silence logger during tests
+  log.setChannels([]); // silence logger during tests
 } else {
   log.setChannels([new ConsoleLog()]);
 }
@@ -40,7 +40,7 @@ if (process.env.NODE_ENV === "production") {
 Import it once at the top of `src/index.ts`:
 
 ```ts title="src/index.ts"
-import "./logger";                     // side-effect: configures singleton
+import "./logger"; // side-effect: configures singleton
 import { log } from "@warlock.js/logger";
 
 log.info("app", "start", "Server listening on :3000");
@@ -87,10 +87,7 @@ Every `new Logger()` gets a unique `id` (string, prefixed `"logger-"`).
 
 ```ts
 log.configure({
-  channels: [
-    new ConsoleLog({ showContext: true }),
-    new FileLog({ chunk: "daily" }),
-  ],
+  channels: [new ConsoleLog({ showContext: true }), new FileLog({ chunk: "daily" })],
   autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
   redact: { paths: ["context.password", "context.headers.authorization"] },
   minLevel: process.env.LOG_LEVEL === "debug" ? "debug" : "info",

package/skills/filter-log-entries/SKILL.md

@@ -38,7 +38,7 @@ For the common "drop everything below X" case, skip the per-channel `levels` arr
 log.setMinLevel("info");
 // debug entries are dropped before fan-out — no channel ever sees them.
 
-log.configure({ minLevel: "warn" });   // shorthand inside configure()
+log.configure({ minLevel: "warn" }); // shorthand inside configure()
 ```
 
 Severity ordering: `debug < info ≈ success < warn < error < fatal`. `success` is treated as informational severity — `setMinLevel("warn")` drops it. `fatal` is strictly above `error`, so `setMinLevel("fatal")` admits only fatal entries (handy for "page me only on fatal" routing).
@@ -46,7 +46,7 @@ Severity ordering: `debug < info ≈ success < warn < error < fatal`. `success`
 Pass `undefined` to clear:
 
 ```ts
-log.setMinLevel(undefined);   // accept everything again
+log.setMinLevel(undefined); // accept everything again
 ```
 
 This runs **before** the channel loop — cheaper than per-channel `levels` filters when you want a uniform floor. Per-channel `levels` and `filter` still run on top for channels that need a tighter or differently-shaped rule.

package/skills/flush-logs-on-shutdown/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: flush-logs-on-shutdown
-description: 'Drain buffered channels before exit — log.flushSync() or log.configure({autoFlushOn: [''SIGINT'', ''SIGTERM'', ''beforeExit'']}) installs handlers that re-raise the signal. Triggers: `log.flush`, `log.flushSync`, `autoFlushOn`, `enableAutoFlush`, `disableAutoFlush`, `SIGINT`, `SIGTERM`, `beforeExit`; "drain logs before exit", "await log.flush() before process.exit", "drain async or network channels on shutdown", "wire SIGTERM for container shutdown", "my logs never showed after a crash", "graceful shutdown logging"; typical import `import { log, FileLog } from "@warlock.js/logger"`. Skip: error capture — the `capture-unhandled-errors` topic; custom sinks — the `write-custom-log-channel` topic; competing `pino.final`, `winston.end`; native `process.on(''exit'')`.'
+description: 'Drain buffered channels before exit — log.flushSync() or log.configure({autoFlushOn: [''SIGINT'', ''SIGTERM'', ''beforeExit'']}) installs handlers that re-raise the signal. Triggers: `log.flush`, `log.flushSync`, `onChannelError`, `log.flush({ timeout })`, `autoFlushOn`, `enableAutoFlush`, `disableAutoFlush`, `SIGINT`, `SIGTERM`, `beforeExit`; "drain logs before exit", "await log.flush() before process.exit", "drain async or network channels on shutdown", "wire SIGTERM for container shutdown", "my logs never showed after a crash", "graceful shutdown logging"; typical import `import { log, FileLog } from "@warlock.js/logger"`. Skip: error capture — the `capture-unhandled-errors` topic; custom sinks — the `write-custom-log-channel` topic; competing `pino.final`, `winston.end`; native `process.on(''exit'')`.'
 ---
 
 # Lifecycle — flushing buffered channels before exit
@@ -20,14 +20,15 @@ log.configure({
 
 ### What each event does
 
-| Event | Behavior |
-|---|---|
+| Event                                                    | Behavior                                                                                                  |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
 | `SIGINT` / `SIGTERM` / `SIGHUP` / `SIGBREAK` / `SIGUSR2` | Flush → remove this handler → re-raise the signal so Node's default exit code runs (e.g. 130 for SIGINT). |
-| `beforeExit` | Flush in place. Node continues its natural exit. |
+| `beforeExit`                                             | Flush in place. Node continues its natural exit.                                                          |
 
 ### Default recommendation
 
 `["SIGINT", "SIGTERM", "beforeExit"]` covers:
+
 - Local `Ctrl+C` (SIGINT)
 - Container orchestrators (`docker stop`, Kubernetes sending SIGTERM)
 - Natural exit (Node finished all work)
@@ -46,7 +47,7 @@ Use this when you need async work (close an HTTP server, drain a queue) **before
 async function gracefulShutdown() {
   await httpServer.close();
   await queue.drain();
-  log.flushSync();          // still sync — guarantees disk write before exit
+  log.flushSync(); // still sync — guarantees disk write before exit
   process.exit(0);
 }
 
@@ -72,13 +73,13 @@ process.once("SIGTERM", gracefulShutdown);
 
 `log.flush()` drains every channel concurrently: each waits for its own async deliveries still in flight (level methods are fire-and-forget and never return a promise; entries logged during the flush are awaited too), then runs its `flush()`. A hung network delivery can't hold up the file channel, and one channel's flush rejecting neither aborts the others nor escapes as an unhandled rejection. It is bounded: `log.flush({ timeout })` resolves after `timeout` ms (default 5000) and reports each channel still draining to `onChannelError`.
 
-| | `flushSync()` | `flush()` |
-|---|---|---|
-| I/O | synchronous — blocks the loop | asynchronous — awaited |
-| Safe in a re-raising signal handler | yes | no — the signal exits before the promise settles |
-| Used by `autoFlushOn` | yes | no |
-| Reach for it when | file channels, last-resort durability | network/async channels, manual `await` before `process.exit` |
-| `FileLog` / `JSONFileLog` | ✓ | ✓ (async write) |
+|                                     | `flushSync()`                         | `flush()`                                                    |
+| ----------------------------------- | ------------------------------------- | ------------------------------------------------------------ |
+| I/O                                 | synchronous — blocks the loop         | asynchronous — awaited                                       |
+| Safe in a re-raising signal handler | yes                                   | no — the signal exits before the promise settles             |
+| Used by `autoFlushOn`               | yes                                   | no                                                           |
+| Reach for it when                   | file channels, last-resort durability | network/async channels, manual `await` before `process.exit` |
+| `FileLog` / `JSONFileLog`           | ✓                                     | ✓ (async write)                                              |
 
 `autoFlushOn` always uses `flushSync()` — signal re-raising can't wait on a promise. If a channel needs async delivery on shutdown, drive `await log.flush()` from your own handler and leave that signal out of `autoFlushOn`.
 
@@ -99,7 +100,7 @@ log.flushSync();
 
 ## Unhandled errors
 
-The `uncaughtException` path in `captureAnyUnhandledRejection()` (the `capture-unhandled-errors` topic) already runs a best-effort, time-bounded `log.flush()` before its own `process.exit(1)`, so the fatal entry drains without extra wiring (and `process.exit()` skips `beforeExit`, so a `beforeExit` handler would not fire on that path anyway). Still set `autoFlushOn` for the *other* shutdown routes — `"SIGINT"` / `"SIGTERM"` and a natural `"beforeExit"` — so those don't lose the last buffered batch.
+The `uncaughtException` path in `captureAnyUnhandledRejection()` (the `capture-unhandled-errors` topic) already runs a best-effort, time-bounded `log.flush()` before its own `process.exit(1)`, so the fatal entry drains without extra wiring (and `process.exit()` skips `beforeExit`, so a `beforeExit` handler would not fire on that path anyway). Still set `autoFlushOn` for the _other_ shutdown routes — `"SIGINT"` / `"SIGTERM"` and a natural `"beforeExit"` — so those don't lose the last buffered batch.
 
 ```ts
 log.configure({
@@ -115,3 +116,21 @@ captureAnyUnhandledRejection();
 - **Don't `await` inside a signal handler you wrote yourself and then call `flushSync`** — if an async step rejects, you skip the flush. Wrap in `try { await x } finally { log.flushSync(); process.exit(1); }`.
 - **Don't call `process.exit()` inside `autoFlushOn` handlers** — signal handlers here already re-raise the signal. Forcing an exit breaks exit codes.
 - **Don't rely on the 5-second flush interval for shutdown safety.** It's a throughput optimization, not a durability guarantee.
+
+## Observe channel failures and drain explicitly
+
+```ts
+import { log } from "@warlock.js/logger";
+
+log.onChannelError((error, channel) => {
+  // Do not call this logger from its own failure handler.
+  console.error("Log delivery failed", channel.name, error);
+});
+log.info("app", "shutdown", "Draining logs");
+await log.flush({ timeout: 3_000 });
+```
+
+Level methods return the logger synchronously. `flush()` waits for async
+channel work within its timeout, reports failures through `onChannelError`, and
+resolves so shutdown can continue. Timeout does not cancel a channel's network
+operation; its driver owns cancellation.

package/skills/index.md

@@ -1,11 +1,13 @@
 ---
-description: "Structured logging for Warlock.js with pluggable channels, redaction and shutdown flushing. Exports `log`, `Logger`, `LogChannel`, `ConsoleLog`, `FileLog`, `JSONFileLog`, `SentryLog`, `applyRedact`, `DEFAULT_REDACT_KEYS`, `captureAnyUnhandledRejection`. Use for: \"log an error with context\", \"write logs to a file as JSON\", \"send errors to Sentry\", \"hide passwords and tokens in logs\", \"flush logs before exit\", \"catch unhandled rejections\", \"write my own log channel\". Not this package: HTTP request handling and error responses live in @warlock.js/core; scheduled jobs are @warlock.js/scheduler."
+description: 'Structured logging for Warlock.js with pluggable channels, redaction and shutdown flushing. Exports `log`, `Logger`, `LogChannel`, `ConsoleLog`, `FileLog`, `JSONFileLog`, `SentryLog`, `applyRedact`, `DEFAULT_REDACT_KEYS`, `captureAnyUnhandledRejection`. Use for: "log an error with context", "write logs to a file as JSON", "send errors to Sentry", "hide passwords and tokens in logs", "flush logs before exit", "catch unhandled rejections", "write my own log channel". Not this package: HTTP request handling and error responses live in @warlock.js/core; scheduled jobs are @warlock.js/scheduler.'
 ---
+
 # @warlock.js/logger
 
 The `log` singleton (a `Logger`) sends each entry, with module, action, level and message, to every configured `LogChannel`. Channels decide where entries go (console, file, JSON file, Sentry, custom) and can filter by level or module.
 
 ## The 80% path
+
 1. Orient: `overview.md`, `logger-basics.md`.
 2. Pick channels: `pick-log-channel.md`; set them up: `configure-logger.md`.
 3. Log via `log.info/warn/error` or helpers: `use-log-helpers.md`.
@@ -14,6 +16,7 @@ The `log` singleton (a `Logger`) sends each entry, with module, action, level an
 6. Extend or test: `write-custom-log-channel.md`, `test-logging-code.md`.
 
 ## Conventions and pitfalls
+
 - `fatal` does not flush or exit by itself; the caller awaits `log.flush()` and then exits.
 - File channels buffer, so an unflushed process exit loses the tail of the log.
 - Configure redaction before logging request bodies or auth data; the default key set is a floor, not a guarantee.

package/skills/logger-basics/SKILL.md

@@ -37,10 +37,7 @@ The 11 things that are true in every logger use:
 import { log, ConsoleLog, FileLog } from "@warlock.js/logger";
 
 log.configure({
-  channels: [
-    new ConsoleLog(),
-    new FileLog({ chunk: "daily", storagePath: "./storage/logs" }),
-  ],
+  channels: [new ConsoleLog(), new FileLog({ chunk: "daily", storagePath: "./storage/logs" })],
   autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
 });
 
@@ -51,12 +48,12 @@ log.error("payments", "charge", new Error("Card declined"));
 ## The six levels
 
 ```ts
-log.debug("module", "action", "verbose detail");      // dev-only diagnostics
-log.info("module", "action", "neutral event");        // user-visible event
-log.warn("module", "action", "something off");         // recoverable concern
-log.error("module", "action", error);                 // handled failure, app continues
-log.success("module", "action", "operation done");    // explicit success
-log.fatal("module", "action", error);                 // unrecoverable, app is going down
+log.debug("module", "action", "verbose detail"); // dev-only diagnostics
+log.info("module", "action", "neutral event"); // user-visible event
+log.warn("module", "action", "something off"); // recoverable concern
+log.error("module", "action", error); // handled failure, app continues
+log.success("module", "action", "operation done"); // explicit success
+log.fatal("module", "action", error); // unrecoverable, app is going down
 ```
 
 `fatal` is purely informational — it does NOT auto-flush or exit. The caller decides whether to `await log.flush()` and `process.exit(...)`. See the `capture-unhandled-errors` topic for the `uncaughtException` → `fatal` routing.
@@ -65,17 +62,17 @@ Every call signature is the same — `module`, `action`, `message`, optional `co
 
 ## Pick a skill
 
-| If the task is about… | Load |
-| --- | --- |
-| Picking a channel — what each built-in does, when to use which | the `pick-log-channel` topic |
-| Startup — registering channels, environment-based setup, the `configure` method | the `configure-logger` topic |
-| Filtering log output (`levels`, `filter`, per-channel routing, `minLevel`) | the `filter-log-entries` topic |
-| Graceful shutdown — `flushSync`, `autoFlushOn`, signal behavior | the `flush-logs-on-shutdown` topic |
-| Extending `LogChannel` to build a custom sink (Slack, database, HTTP) | the `write-custom-log-channel` topic |
-| Routing Node's `unhandledRejection` / `uncaughtException` through the logger | the `capture-unhandled-errors` topic |
-| `log.assert(...)` and `log.timer(...)` shorthand helpers | the `use-log-helpers` topic |
-| Redacting secrets — logger floor + additive channel paths | the `redact-sensitive-log-fields` topic |
-| Tests that assert on log output, or code under test that logs | the `test-logging-code` topic |
+| If the task is about…                                                           | Load                                    |
+| ------------------------------------------------------------------------------- | --------------------------------------- |
+| Picking a channel — what each built-in does, when to use which                  | the `pick-log-channel` topic            |
+| Startup — registering channels, environment-based setup, the `configure` method | the `configure-logger` topic            |
+| Filtering log output (`levels`, `filter`, per-channel routing, `minLevel`)      | the `filter-log-entries` topic          |
+| Graceful shutdown — `flushSync`, `autoFlushOn`, signal behavior                 | the `flush-logs-on-shutdown` topic      |
+| Extending `LogChannel` to build a custom sink (Slack, database, HTTP)           | the `write-custom-log-channel` topic    |
+| Routing Node's `unhandledRejection` / `uncaughtException` through the logger    | the `capture-unhandled-errors` topic    |
+| `log.assert(...)` and `log.timer(...)` shorthand helpers                        | the `use-log-helpers` topic             |
+| Redacting secrets — logger floor + additive channel paths                       | the `redact-sensitive-log-fields` topic |
+| Tests that assert on log output, or code under test that logs                   | the `test-logging-code` topic           |
 
 ## Things NOT to do
 

package/skills/overview/SKILL.md

@@ -32,52 +32,63 @@ Eleven task skills cover everything. Load the one that matches your job — most
 ### Foundations
 
 #### `logger-basics`
+
 Start here. The `log` singleton, the six levels (`debug` / `info` / `warn` / `error` / `success` / `fatal`), how fan-out works, the `module / action / message / context` shape every entry carries.
 
 #### `configure-logger`
+
 Wire channels at boot — `log.addChannel`, `log.setChannels`, `log.configure({ channels, autoFlushOn, redact, minLevel })`. Branch on `NODE_ENV`, replace the channel list, isolate a library's logger from the host singleton.
 
 ### Channels
 
 #### `pick-log-channel`
+
 Pick one of the four built-ins: `ConsoleLog` (terminal, colored), `FileLog` (plain `.log` on disk with rotation), `JSONFileLog` (structured JSON for aggregators — Datadog, Loki, ELK), `SentryLog` (errors + breadcrumbs to Sentry; `@sentry/node` is an optional peer).
 
 #### `ship-logs-to-sentry`
+
 The `SentryLog` channel in depth — event-vs-breadcrumb level mapping, dual init modes (reuse an existing client or pass `options`), draining via `Sentry.flush(timeout)`, behavior when the optional peer isn't installed.
 
 #### `write-custom-log-channel`
+
 Extend `LogChannel<Options>` for sinks the built-ins don't cover — Slack, HTTP endpoint, in-memory buffer, database. The lazy `init()` lifecycle (`setTimeout(0)`), the `terminal: true/false` ANSI-stripping behavior, and the difference between `flush()` (async, network) and `flushSync()` (sync, files) are subtle — read this skill before subclassing.
 
 ### Production concerns
 
 #### `redact-sensitive-log-fields`
+
 Strip secrets before they reach a sink. Logger-wide `setRedact({ paths, censor })` is the security floor; per-channel `redact` configs add paths (never remove). Dotted-glob paths (`*`, `**`); censor as string or function `(value, path) => any`.
 
 #### `filter-log-entries`
+
 Drop entries before they cost anything. Logger-wide `setMinLevel("info")` is the fast path; per-channel `levels` array + `filter` predicate for fine control.
 
 #### `flush-logs-on-shutdown`
+
 Buffered channels need explicit drain. `log.flushSync()` (sync) for file channels — also wired by `enableAutoFlush(['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGBREAK', 'SIGUSR2', 'beforeExit'])`. `await log.flush()` (async) for network/async channels like `SentryLog` — the only path that can await an HTTPS round-trip on a graceful shutdown.
 
 #### `capture-unhandled-errors`
+
 `captureAnyUnhandledRejection()` hooks `unhandledRejection` (→ `log.error("app", ...)`, process kept alive) and `uncaughtException` (→ `log.fatal("app", ...)` then `process.exit(1)` — restoring the non-zero exit the listener would otherwise suppress, so a fatal crash never becomes a silent `exit 0`; opt out with `{ exitOnUncaughtException: false }`). It flushes before exiting and falls back to `console.error` when no terminal channel is set. One call at startup.
 
 ### Ergonomics + testing
 
 #### `use-log-helpers`
+
 Two shortcuts every `Logger` exposes: `log.assert(condition, module, action, message, context?)` logs an error only when the condition is falsy (free on the happy path); `log.timer(module, action)` returns an end-function that emits `info` with a measured `durationMs`.
 
 #### `test-logging-code`
+
 Silence the logger globally in tests via `log.setChannels([])` in `setupFiles`. Assert specific entries with a capturing `LogChannel` subclass — it proves an entry was actually delivered through the pipeline (filters, redaction), not merely that a method was called, and it isolates cleanly by swapping `log.channels`.
 
 ## Built-in channels at a glance
 
-| Channel | Sink | `terminal` | Buffered |
-| --- | --- | --- | --- |
-| `ConsoleLog` | `process.stdout` | `true` (colors kept) | no |
-| `FileLog` | `.log` files | `false` (ANSI stripped) | yes (5s timer or 100-entry buffer) |
-| `JSONFileLog` | `.json` files | `false` (ANSI stripped) | yes (same buffering) |
-| `SentryLog` | Sentry events + breadcrumbs | `false` | via the Sentry SDK's own transport (`@sentry/node` is an optional peer) |
+| Channel       | Sink                        | `terminal`              | Buffered                                                                |
+| ------------- | --------------------------- | ----------------------- | ----------------------------------------------------------------------- |
+| `ConsoleLog`  | `process.stdout`            | `true` (colors kept)    | no                                                                      |
+| `FileLog`     | `.log` files                | `false` (ANSI stripped) | yes (5s timer or 100-entry buffer)                                      |
+| `JSONFileLog` | `.json` files               | `false` (ANSI stripped) | yes (same buffering)                                                    |
+| `SentryLog`   | Sentry events + breadcrumbs | `false`                 | via the Sentry SDK's own transport (`@sentry/node` is an optional peer) |
 
 `terminal: true` is the flag that decides whether the channel sees raw colored messages or stripped plain text. Custom channels: pick `true` if you write to a terminal, `false` for anything else.
 

package/skills/pick-log-channel/SKILL.md

@@ -9,12 +9,12 @@ Four built-in channels (`SentryLog` needs the optional `@sentry/node` peer). A c
 
 ## The decision
 
-| Need | Pick |
-|---|---|
-| Local dev, colored output in the terminal | `ConsoleLog` |
-| Plain text `.log` files on disk — humans read them | `FileLog` |
+| Need                                                                              | Pick          |
+| --------------------------------------------------------------------------------- | ------------- |
+| Local dev, colored output in the terminal                                         | `ConsoleLog`  |
+| Plain text `.log` files on disk — humans read them                                | `FileLog`     |
 | Structured `.json` files — a log aggregator (Loki / Datadog / Elastic) reads them | `JSONFileLog` |
-| Errors & warnings into Sentry (events + breadcrumbs) | `SentryLog` |
+| Errors & warnings into Sentry (events + breadcrumbs)                              | `SentryLog`   |
 
 Most production setups use **two** channels: `ConsoleLog` + one file channel. Dev uses `ConsoleLog` only.
 
@@ -32,6 +32,7 @@ new ConsoleLog();
 ```
 
 Properties:
+
 - `name = "console"`, `terminal = true`
 - Accepts `ConsoleLogConfig` — `levels`, `filter`, `dateFormat`, `showContext`, `contextDepth`
 - If `message` is an object, a second `console.log(message)` is issued so Node's inspector can expand it
@@ -58,14 +59,26 @@ Plain text. Buffers in memory, flushes to disk periodically.
 import { FileLog } from "@warlock.js/logger";
 
 new FileLog({
-  storagePath: "./storage/logs",  // default: process.cwd() + "/storage/logs"
-  name: "app",                    // default: "app"
-  extension: "log",               // default: "log"
-  chunk: "daily",                 // "single" (default) | "daily" | "hourly"
-  rotate: true,                   // default: true
-  maxFileSize: 10 * 1024 * 1024,  // default: 10MB — triggers rotation
-  maxMessagesToWrite: 100,        // default: 100 — flush threshold
-  groupBy: ["level", "module"],   // optional subdirectory nesting
+  storagePath: "./storage/logs", // default: process.cwd() + "/storage/logs"
+  name: "app", // default: "app"
+  extension: "log", // default: "log"
+  chunk: "daily", // "single" (default) | "daily" | "hourly"
+  rotate: true, // default: true
+  maxFileSize: 10 * 1024 * 1024, // default: 10MB — triggers rotation
+  maxMessagesToWrite: 100, // default: 100 — flush threshold
+  groupBy: ["level", "module"], // optional subdirectory nesting
+  retention: { maxFiles: 14, maxAgeDays: 30 }, // optional pruning of old files
+});
+```
+
+Name dated files yourself with `fileName` — a pattern (`{YYYY}` `{MM}` `{DD}` `{HH}` `{mm}` `{name}`, local time) or a function of the date:
+
+```ts
+new FileLog({ storagePath: "./storage/logs", fileName: "{name}-{YYYY}-{MM}-{DD}" }); // app-2026-10-17.log
+new FileLog({
+  storagePath: "./storage/logs",
+  fileName: (date) => `audit-${date.getFullYear()}`,
+  retention: { maxFiles: 5, match: /^audit-\d{4}\.log$/ }, // a function fileName needs `match`
 });
 ```
 
@@ -74,7 +87,8 @@ Line format: `[date time] [level] [module][action]: message` — or a `[trace]`
 ### Key gotchas
 
 - **Buffers!** Messages sit in memory until either `maxMessagesToWrite` is reached, 5 seconds pass, or `flushSync()` is called. A process that crashes without flushing loses buffered entries.
-- **`chunk: "daily"` picks a filename per day.** File name becomes `DD-MM-YYYY.log`. Combined with `rotate: true`, rotated archives get `Date.now()` suffixed.
+- **`chunk: "daily"` picks a filename per day.** File name becomes `YYYY-MM-DD.log` (hourly: `YYYY-MM-DD-HH.log`), ignoring `name` unless `fileName` uses `{name}`. Since 5.31; keep the old `DD-MM-YYYY` with `fileName: "{DD}-{MM}-{YYYY}"`. Rotated archives are `<file name>-<rotateFileName>-<epoch ms>.<ext>`; `rotateFileName` is a pattern or function too (default `{YYYY}-{MM}-{DD}`).
+- **`retention` only touches this channel's files.** On boot and whenever a new file starts it removes files in the log directory (each group directory with `groupBy`) whose names match the channel's pattern — beyond `maxFiles` (newest by modification time, the current file counts) or older than `maxAgeDays`. Failures go to `log.onChannelError(...)`, never to the call site. `await channel.prune()` runs it on demand.
 - **`groupBy` nests directories.** `groupBy: ["level", "module"]` produces `storage/logs/error/payments/app.log`. Order matters.
 - **Dispose channels you discard.** A live `FileLog` keeps a 5-second flush interval running. If you swap the channel list at runtime (reconfigure the logger), call `channel.dispose()` on the old instance — it clears that timer and drains the buffer one last time. Skipping it leaks one timer per discarded channel and keeps the event loop alive. (Channels that live for the whole process don't need this — process exit clears the timer.)
 
@@ -91,16 +105,14 @@ Subclass of `FileLog` — same buffering, chunking, rotation, grouping. Output i
       "date": "15-03-2024 10:22:03",
       "module": "payments",
       "action": "charge",
-      "stack": [
-        "Error: Card declined",
-        "    at chargeCard (/app/src/payments.ts:42:11)"
-      ]
+      "stack": ["Error: Card declined", "    at chargeCard (/app/src/payments.ts:42:11)"]
     }
   ]
 }
 ```
 
 Differences from `FileLog`:
+
 - `name = "fileJson"` (**not** `"json"` — use this exact string for `log.channel("fileJson")`)
 - `extension` is always `"json"` — the option is silently ignored
 - Error `stack` is stored as `string[]` (split on newlines) — easy to query in aggregators
@@ -127,8 +139,8 @@ Every channel constructor accepts at minimum:
 
 ```ts
 type BasicLogConfigurations = {
-  levels?: LogLevel[];                       // whitelist — omit or [] to allow all
-  filter?: (data: LoggingData) => boolean;   // custom predicate
+  levels?: LogLevel[]; // whitelist — omit or [] to allow all
+  filter?: (data: LoggingData) => boolean; // custom predicate
   dateFormat?: { date?: string; time?: string }; // Day.js format strings
   context?: (data) => Promise<Record<string, any>>; // reserved — not yet read
 };
@@ -139,10 +151,10 @@ Concrete file channels extend this with their storage/chunk/rotate/groupBy optio
 ## Picking a channel by name at runtime
 
 ```ts
-log.channel("console");   // → ConsoleLog | undefined
-log.channel("file");      // → FileLog | undefined
-log.channel("fileJson");  // ← note the name — NOT "json"
-log.channel("sentry");    // → SentryLog | undefined
+log.channel("console"); // → ConsoleLog | undefined
+log.channel("file"); // → FileLog | undefined
+log.channel("fileJson"); // ← note the name — NOT "json"
+log.channel("sentry"); // → SentryLog | undefined
 ```
 
 If two channels share a `name`, only one is reachable this way — the search returns the first match.