@warlock.js/logger 4.1.14 → 4.2.0

package/llms.txt

@@ -1,19 +1,20 @@
-# Warlock Logger
-
-> Package: `@warlock.js/logger`
-
-> A powerful logging system  for messages and errors in nodejs.
-
-## Skills
-
-- [capture-unhandled-errors](@warlock.js/logger/capture-unhandled-errors/SKILL.md): captureAnyUnhandledRejection() installs process.on('unhandledRejection') + ('uncaughtException') listeners routing failures through log.error('app', ...). Triggers: `captureAnyUnhandledRejection`, `unhandledRejection`, `uncaughtException`, `log.error`; "log unhandled promise rejections", "catch uncaught exceptions to a file", "record crashes before exit", "global error handler with logger"; typical import `import { captureAnyUnhandledRejection, log } from "@warlock.js/logger"`. Skip: flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; 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 — `@warlock.js/logger/pick-log-channel/SKILL.md`; flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; redaction — `@warlock.js/logger/redact-sensitive-log-fields/SKILL.md`; 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 — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; channel picks — `@warlock.js/logger/pick-log-channel/SKILL.md`; 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.flushSync`, `autoFlushOn`, `enableAutoFlush`, `disableAutoFlush`, `SIGINT`, `SIGTERM`, `beforeExit`; "drain logs before exit", "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 — `@warlock.js/logger/capture-unhandled-errors/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; competing `pino.final`, `winston.end`; native `process.on('exit')`.
-- [logger-basics](@warlock.js/logger/logger-basics/SKILL.md): Start with @warlock.js/logger — the log singleton, five levels (debug / info / warn / error / success), channel fan-out, foundations. Triggers: `log`, `Logger`, `log.info`, `log.error`, `log.debug`, `log.warn`, `log.success`, `ConsoleLog`, `FileLog`, `JSONFileLog`; "how do I log in node", "warlock logger basics", "which logger skill do I need"; typical import `import { log, ConsoleLog, FileLog } from "@warlock.js/logger"`. Skip: channel picks — `@warlock.js/logger/pick-log-channel/SKILL.md`; setup — `@warlock.js/logger/configure-logger/SKILL.md`; competing libs `winston`, `pino`, `bunyan`, `log4js`, `signale`; native `console.log`.
-- [overview](@warlock.js/logger/overview/SKILL.md): Front-door orientation for `@warlock.js/logger` — structured channel-based logging with five severity levels, PII redaction floor, buffered file/JSON channels, signal-flush on shutdown, ergonomic helpers (timer, assert). Standalone — no `@warlock.js/core` required. TRIGGER when: code imports anything from `@warlock.js/logger`; user asks "what does @warlock.js/logger do", "compare with pino / winston / bunyan", "structured logging for Node", "which logger should I use", "how do channels work"; package.json adds `@warlock.js/logger`. Skip: specific task already known — load the matching task skill directly (`logger-basics`, `configure-logger`, `pick-log-channel`, `write-custom-log-channel`, `redact-sensitive-log-fields`, `filter-log-entries`, `flush-logs-on-shutdown`, `capture-unhandled-errors`, `use-log-helpers`, `test-logging-code`); plain `console.log` in throwaway scripts.
-- [pick-log-channel](@warlock.js/logger/pick-log-channel/SKILL.md): Pick one of the three built-in channels — ConsoleLog (terminal), FileLog (plain text on disk), JSONFileLog (structured JSON for aggregators like Loki / Datadog / Elastic). Triggers: `ConsoleLog`, `FileLog`, `JSONFileLog`, `chunk`, `rotate`, `groupBy`, `maxFileSize`, `showContext`, `log.channel`; "log to a file", "rotate log files", "daily log chunks", "json logs for datadog / loki / elastic"; typical import `import { ConsoleLog, FileLog, JSONFileLog } from "@warlock.js/logger"`. Skip: custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; registration — `@warlock.js/logger/configure-logger/SKILL.md`; 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 — two-layer additive redaction via log.configure({redact: {paths}}) (logger floor) + per-channel redact (more paths on top). Dotted glob paths (*, **). Triggers: `redact`, `paths`, `censor`, `log.setRedact`, `applyRedact`; "redact passwords in logs", "strip tokens from log output", "hide authorization headers", "scrub PII before logging"; typical import `import { log } from "@warlock.js/logger"`. Skip: filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; competing libs `pino.redact`, `fast-redact`.
-- [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 — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; 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 — `@warlock.js/logger/logger-basics/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing `console.assert`, `console.time`, `console.timeEnd`, `perf_hooks.performance.now`.
-- [write-custom-log-channel](@warlock.js/logger/write-custom-log-channel/SKILL.md): Extend the abstract LogChannel class for custom sinks — Slack, database, HTTP endpoint, in-memory buffer. Triggers: `LogChannel`, `LogContract`, `LoggingData`, `shouldBeLogged`, `init`, `flushSync`, `terminal`; "log to slack", "log to a database", "send logs to datadog / loki HTTP api", "in-memory test capture channel", "build a custom log sink"; typical import `import { LogChannel, type LoggingData, type LogContract } from "@warlock.js/logger"`. Skip: built-in channels — `@warlock.js/logger/pick-log-channel/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing libs `winston-transport`, `pino-transport`.
+# Warlock Logger
+
+> Package: `@warlock.js/logger`
+
+> A powerful logging system  for messages and errors in nodejs.
+
+## Skills
+
+- [capture-unhandled-errors](@warlock.js/logger/capture-unhandled-errors/SKILL.md): captureAnyUnhandledRejection() installs process.on('unhandledRejection') → log.error and process.on('uncaughtException') → log.fatal so process-level failures land in your configured channels. Triggers: `captureAnyUnhandledRejection`, `unhandledRejection`, `uncaughtException`, `log.error`, `log.fatal`; "log unhandled promise rejections", "catch uncaught exceptions to a file", "record crashes before exit", "global error handler with logger"; typical import `import { captureAnyUnhandledRejection, log } from "@warlock.js/logger"`. Skip: flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; 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 — `@warlock.js/logger/pick-log-channel/SKILL.md`; flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; redaction — `@warlock.js/logger/redact-sensitive-log-fields/SKILL.md`; 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 — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; channel picks — `@warlock.js/logger/pick-log-channel/SKILL.md`; 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 — `@warlock.js/logger/capture-unhandled-errors/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; competing `pino.final`, `winston.end`; native `process.on('exit')`.
+- [logger-basics](@warlock.js/logger/logger-basics/SKILL.md): Start with @warlock.js/logger — the log singleton, six levels (debug / info / warn / error / success / fatal), channel fan-out, foundations. Triggers: `log`, `Logger`, `log.info`, `log.error`, `log.fatal`, `log.debug`, `log.warn`, `log.success`, `ConsoleLog`, `FileLog`, `JSONFileLog`; "how do I log in node", "warlock logger basics", "which logger skill do I need"; typical import `import { log, ConsoleLog, FileLog } from "@warlock.js/logger"`. Skip: channel picks — `@warlock.js/logger/pick-log-channel/SKILL.md`; setup — `@warlock.js/logger/configure-logger/SKILL.md`; competing libs `winston`, `pino`, `bunyan`, `log4js`, `signale`; native `console.log`.
+- [overview](@warlock.js/logger/overview/SKILL.md): Front-door orientation for `@warlock.js/logger` — structured channel-based logging with six severity levels (debug / info / warn / error / success / fatal), PII redaction floor, buffered file/JSON channels, optional SentryLog forwarding, async log.flush() + signal-flush on shutdown, ergonomic helpers (timer, assert). Standalone — no `@warlock.js/core` required. TRIGGER when: code imports anything from `@warlock.js/logger`; user asks "what does @warlock.js/logger do", "compare with pino / winston / bunyan", "structured logging for Node", "which logger should I use", "how do channels work"; package.json adds `@warlock.js/logger`. Skip: specific task already known — load the matching task skill directly (`logger-basics`, `configure-logger`, `pick-log-channel`, `write-custom-log-channel`, `ship-logs-to-sentry`, `redact-sensitive-log-fields`, `filter-log-entries`, `flush-logs-on-shutdown`, `capture-unhandled-errors`, `use-log-helpers`, `test-logging-code`); plain `console.log` in throwaway scripts.
+- [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 — `@warlock.js/logger/ship-logs-to-sentry/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; registration — `@warlock.js/logger/configure-logger/SKILL.md`; 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 — two-layer additive redaction via log.configure({redact: {paths}}) (logger floor) + per-channel redact (more paths on top). Dotted glob paths (*, **). Triggers: `redact`, `paths`, `censor`, `log.setRedact`, `applyRedact`; "redact passwords in logs", "strip tokens from log output", "hide authorization headers", "scrub PII before logging"; typical import `import { log } from "@warlock.js/logger"`. Skip: filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; 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 — `@warlock.js/logger/pick-log-channel/SKILL.md`; custom sinks — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; graceful-shutdown flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; 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 — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; 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 — `@warlock.js/logger/logger-basics/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing `console.assert`, `console.time`, `console.timeEnd`, `perf_hooks.performance.now`.
+- [write-custom-log-channel](@warlock.js/logger/write-custom-log-channel/SKILL.md): Extend the abstract LogChannel class for custom sinks — Slack, database, HTTP endpoint, in-memory buffer. Triggers: `LogChannel`, `LogContract`, `LoggingData`, `shouldBeLogged`, `init`, `flush`, `flushSync`, `terminal`; "log to slack", "log to a database", "send logs to datadog / loki HTTP api", "in-memory test capture channel", "build a custom log sink"; typical import `import { LogChannel, type LoggingData, type LogContract } from "@warlock.js/logger"`. Skip: built-in channels — `@warlock.js/logger/pick-log-channel/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing libs `winston-transport`, `pino-transport`.

package/package.json

@@ -15,13 +15,16 @@
     "url": "https://github.com/warlockjs/logger"
   },
   "dependencies": {
-    "@warlock.js/fs": "*",
     "@mongez/copper": "^2.1.2",
     "@mongez/reinforcements": "^3.2.0",
+    "@warlock.js/fs": "4.2.0",
     "dayjs": "^1.11.9",
     "safe-stable-stringify": "^2.5.0"
   },
-  "version": "4.1.14",
+  "peerDependencies": {
+    "@sentry/node": "^8.0.0 || ^9.0.0 || ^10.0.0"
+  },
+  "version": "4.2.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

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

@@ -1,103 +1,103 @@
----
-name: capture-unhandled-errors
-description: 'captureAnyUnhandledRejection() installs process.on(''unhandledRejection'') + (''uncaughtException'') listeners routing failures through log.error(''app'', ...). Triggers: `captureAnyUnhandledRejection`, `unhandledRejection`, `uncaughtException`, `log.error`; "log unhandled promise rejections", "catch uncaught exceptions to a file", "record crashes before exit", "global error handler with logger"; typical import `import { captureAnyUnhandledRejection, log } from "@warlock.js/logger"`. Skip: flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing `Sentry.init`, `@sentry/node`; native `process.on(''unhandledRejection'')`.'
----
-
-# Error capture — routing Node's unhandled errors through the logger
-
-`captureAnyUnhandledRejection()` installs two process-level listeners so crashes are logged (not silently swallowed) before Node exits.
-
-## What it does
-
-```ts
-import { captureAnyUnhandledRejection } from "@warlock.js/logger";
-
-captureAnyUnhandledRejection();
-```
-
-Registers:
-- `process.on("unhandledRejection", reason => log.error("app", "unhandledRejection", reason))`
-- `process.on("uncaughtException", error => log.error("app", "uncaughtException", error))`
-
-Nothing else — the failure goes through `log.error` only, so it lands in your configured channels rather than bypassing them with a raw `console.log`.
-
-## When to call it
-
-**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";
-
-log.configure({
-  channels: [new ConsoleLog(), new FileLog({ levels: ["error"] })],
-  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],   // ← important; see below
-});
-
-captureAnyUnhandledRejection();
-```
-
-## Pair with `autoFlushOn: ["beforeExit"]`
-
-Without a flush on exit, here's what happens on a crash:
-
-1. Promise rejection fires → `log.error(...)` queues the error into `FileLog`'s buffer.
-2. Node exits.
-3. Buffer is never flushed. **The error that killed your app is lost.**
-
-Including `"beforeExit"` in `autoFlushOn` closes the gap. Node fires `beforeExit` after the rejection handler resolves, the logger flushes, then Node exits. See [`@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md).
-
-## Idempotency — don't call it twice
-
-Calling `captureAnyUnhandledRejection()` a second time registers a second pair of listeners. Your next rejection gets logged twice. There's no dedup; just call it once.
-
-## What it does **not** do
-
-- **Does not swallow errors.** Node still exits after `uncaughtException` (this is the safe behavior — state is undefined). The logger just ensures the error is recorded first.
-- **Does not install Node's `--unhandled-rejections` policy.** That's a Node flag; set it in your launch script if you want strict mode.
-- **Does not hook `SIGTERM` / `SIGINT`** — use `enableAutoFlush` for signal flushes.
-- **Does not filter.** Every rejection/exception is logged at `error` level with `module: "app"`. Filter per-channel if some noise slips in.
-
-## Checking an error was captured in tests
-
-Don't mock `process.on` — use a capturing channel and emit the listener directly:
-
-```ts
-import { log, captureAnyUnhandledRejection, LogChannel } from "@warlock.js/logger";
-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 }); }
-}
-
-it("routes unhandled rejections to the logger", async () => {
-  const capture = new Capture();
-  const originalChannels = log.channels;
-  log.channels = [capture];
-
-  captureAnyUnhandledRejection();
-  process.emit("unhandledRejection", new Error("boom"), Promise.resolve());
-
-  await new Promise((r) => setTimeout(r, 0));
-
-  expect(capture.received[0]!.module).toBe("app");
-  expect(capture.received[0]!.action).toBe("unhandledRejection");
-
-  log.channels = originalChannels;
-});
-```
-
-## Module + action the capture uses
-
-Both listeners log with:
-- `module: "app"`
-- `action: "unhandledRejection"` or `action: "uncaughtException"`
-- `message`: the rejection reason / exception (keep it as the raw `Error` object — file channels capture the stack).
-
-If you want these routed to a specific file, filter on `data.module === "app"`. See [`@warlock.js/logger/filter-log-entries/SKILL.md`](@warlock.js/logger/filter-log-entries/SKILL.md).
+---
+name: capture-unhandled-errors
+description: 'captureAnyUnhandledRejection() installs process.on(''unhandledRejection'') → log.error and process.on(''uncaughtException'') → log.fatal so process-level failures land in your configured channels. Triggers: `captureAnyUnhandledRejection`, `unhandledRejection`, `uncaughtException`, `log.error`, `log.fatal`; "log unhandled promise rejections", "catch uncaught exceptions to a file", "record crashes before exit", "global error handler with logger"; typical import `import { captureAnyUnhandledRejection, log } from "@warlock.js/logger"`. Skip: flushing — `@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`; filtering — `@warlock.js/logger/filter-log-entries/SKILL.md`; competing `Sentry.init`, `@sentry/node`; native `process.on(''unhandledRejection'')`.'
+---
+
+# Error capture — routing Node's unhandled errors through the logger
+
+`captureAnyUnhandledRejection()` installs two process-level listeners so crashes are logged (not silently swallowed) before Node exits.
+
+## What it does
+
+```ts
+import { captureAnyUnhandledRejection } from "@warlock.js/logger";
+
+captureAnyUnhandledRejection();
+```
+
+Registers:
+- `process.on("unhandledRejection", reason => log.error("app", "unhandledRejection", reason))`
+- `process.on("uncaughtException", error => log.fatal("app", "uncaughtException", error))`
+
+The split is intentional: an `uncaughtException` terminates the Node process by default, so it's semantically `fatal`. An `unhandledRejection` is a failure but not always process-ending (depends on Node's `--unhandled-rejections` policy and your app's recovery), so it stays at `error`. This makes "page on fatal" alerting clean — only true crashes ring the pager.
+
+## When to call it
+
+**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";
+
+log.configure({
+  channels: [new ConsoleLog(), new FileLog({ levels: ["error"] })],
+  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],   // ← important; see below
+});
+
+captureAnyUnhandledRejection();
+```
+
+## Pair with `autoFlushOn: ["beforeExit"]`
+
+Without a flush on exit, here's what happens on a crash:
+
+1. Promise rejection fires → `log.error(...)` queues the error into `FileLog`'s buffer.
+2. Node exits.
+3. Buffer is never flushed. **The error that killed your app is lost.**
+
+Including `"beforeExit"` in `autoFlushOn` closes the gap. Node fires `beforeExit` after the rejection handler resolves, the logger flushes, then Node exits. See [`@warlock.js/logger/flush-logs-on-shutdown/SKILL.md`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md).
+
+## Idempotency — don't call it twice
+
+Calling `captureAnyUnhandledRejection()` a second time registers a second pair of listeners. Your next rejection gets logged twice. There's no dedup; just call it once.
+
+## What it does **not** do
+
+- **Does not swallow errors.** Node still exits after `uncaughtException` (this is the safe behavior — state is undefined). The logger just ensures the error is recorded first.
+- **Does not install Node's `--unhandled-rejections` policy.** That's a Node flag; set it in your launch script if you want strict mode.
+- **Does not hook `SIGTERM` / `SIGINT`** — use `enableAutoFlush` for signal flushes.
+- **Does not filter.** Every rejection is logged at `error` and every uncaught exception at `fatal`, both with `module: "app"`. Filter per-channel if some noise slips in.
+
+## Checking an error was captured in tests
+
+Don't mock `process.on` — use a capturing channel and emit the listener directly:
+
+```ts
+import { log, captureAnyUnhandledRejection, LogChannel } from "@warlock.js/logger";
+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 }); }
+}
+
+it("routes unhandled rejections to the logger", async () => {
+  const capture = new Capture();
+  const originalChannels = log.channels;
+  log.channels = [capture];
+
+  captureAnyUnhandledRejection();
+  process.emit("unhandledRejection", new Error("boom"), Promise.resolve());
+
+  await new Promise((r) => setTimeout(r, 0));
+
+  expect(capture.received[0]!.module).toBe("app");
+  expect(capture.received[0]!.action).toBe("unhandledRejection");
+
+  log.channels = originalChannels;
+});
+```
+
+## 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).
+
+If you want these routed to a specific file, filter on `data.module === "app"`. See [`@warlock.js/logger/filter-log-entries/SKILL.md`](@warlock.js/logger/filter-log-entries/SKILL.md).

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

@@ -1,120 +1,120 @@
----
-name: filter-log-entries
-description: '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 — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; channel picks — `@warlock.js/logger/pick-log-channel/SKILL.md`; competing libs `pino.levels`, `winston.format.filter`, `debug` env var.'
----
-
-# Filtering — `levels` + `filter` predicate + `minLevel`
-
-Every channel can silently drop entries it doesn't care about. Three mechanisms stack: a logger-wide `minLevel` floor (cheapest), then per-channel `levels` whitelist, then per-channel `filter` predicate.
-
-## 1. `levels` — the per-channel whitelist
-
-```ts
-new FileLog({ levels: ["error", "warn"] });
-// debug/info/success entries → skipped
-// error/warn entries → written
-```
-
-- Omitting `levels` (or passing `[]`) means **allow all five**.
-- No regex / no range — it's a literal whitelist of `LogLevel` strings.
-
-## 2. `filter` — the per-channel custom predicate
-
-```ts
-new ConsoleLog({
-  filter: (data) => data.module !== "healthcheck",
-});
-// Every entry is passed to the predicate; return false → skip.
-```
-
-- `data` is the full `LoggingData`: `{ type, module, action, message, context? }`.
-- Predicate runs **after** `levels` — an entry blocked by `levels` never reaches `filter`.
-
-## 3. `minLevel` — the logger-wide severity floor
-
-For the common "drop everything below X" case, skip the per-channel `levels` array and use the logger-wide fast path:
-
-```ts
-log.setMinLevel("info");
-// debug entries are dropped before fan-out — no channel ever sees them.
-
-log.configure({ minLevel: "warn" });   // shorthand inside configure()
-```
-
-Severity ordering: `debug < info ≈ success < warn < error`. `success` is treated as informational severity — `setMinLevel("warn")` drops it.
-
-Pass `undefined` to clear:
-
-```ts
-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.
-
-## Combining — real patterns
-
-### Route errors to a dedicated file
-
-```ts
-log.setChannels([
-  new ConsoleLog(),
-  new FileLog({
-    name: "errors",
-    levels: ["error", "warn"],
-    chunk: "daily",
-  }),
-]);
-// ConsoleLog sees everything; errors.log only grows with warnings and errors.
-```
-
-### Silence a noisy module
-
-```ts
-new ConsoleLog({
-  filter: (data) => data.module !== "socket.io",
-});
-```
-
-### Keep the dev terminal focused
-
-```ts
-// Only surface the subsystem you're actively working on
-new ConsoleLog({
-  filter: (data) => data.module === "auth",
-});
-```
-
-### Errors always pass, info only for one module
-
-```ts
-new ConsoleLog({
-  filter: (data) => data.type === "error" || data.module === "payments",
-});
-```
-
-## Where filtering happens
-
-`LogChannel.shouldBeLogged(data)` runs both checks in order:
-
-```ts
-// levels check — fast path
-if (this.config("levels")?.length && !this.config("levels").includes(data.type)) return false;
-
-// filter predicate — only runs if levels allowed it
-const filter = this.config("filter");
-if (filter) return filter(data);
-
-return true;
-```
-
-If you extend `LogChannel` to write a custom channel, call `this.shouldBeLogged(data)` first thing inside your `log(data)` method — you inherit both mechanisms for free. See [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md).
-
-## Logger-wide custom filtering — not a thing
-
-There is no `logger.setGlobalFilter()`. Each channel filters itself. If you want the same predicate everywhere, pass it to every channel constructor (or wrap your channels in a helper).
-
-## Performance note
-
-Filters run on **every** entry per channel. A synchronous, cheap predicate is fine. Avoid `await` inside — the channel receives a fully-formed `LoggingData` and the filter is sync-only (type: `(data: LoggingData) => boolean`).
-
-The `minLevel` check is the fastest of the three (single comparison before fan-out), so prefer it when "drop everything below X uniformly" matches your need.
+---
+name: filter-log-entries
+description: '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 — `@warlock.js/logger/write-custom-log-channel/SKILL.md`; channel picks — `@warlock.js/logger/pick-log-channel/SKILL.md`; competing libs `pino.levels`, `winston.format.filter`, `debug` env var.'
+---
+
+# Filtering — `levels` + `filter` predicate + `minLevel`
+
+Every channel can silently drop entries it doesn't care about. Three mechanisms stack: a logger-wide `minLevel` floor (cheapest), then per-channel `levels` whitelist, then per-channel `filter` predicate.
+
+## 1. `levels` — the per-channel whitelist
+
+```ts
+new FileLog({ levels: ["error", "warn"] });
+// debug/info/success entries → skipped
+// error/warn entries → written
+```
+
+- Omitting `levels` (or passing `[]`) means **allow all six**.
+- No regex / no range — it's a literal whitelist of `LogLevel` strings.
+
+## 2. `filter` — the per-channel custom predicate
+
+```ts
+new ConsoleLog({
+  filter: (data) => data.module !== "healthcheck",
+});
+// Every entry is passed to the predicate; return false → skip.
+```
+
+- `data` is the full `LoggingData`: `{ type, module, action, message, context? }`.
+- Predicate runs **after** `levels` — an entry blocked by `levels` never reaches `filter`.
+
+## 3. `minLevel` — the logger-wide severity floor
+
+For the common "drop everything below X" case, skip the per-channel `levels` array and use the logger-wide fast path:
+
+```ts
+log.setMinLevel("info");
+// debug entries are dropped before fan-out — no channel ever sees them.
+
+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).
+
+Pass `undefined` to clear:
+
+```ts
+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.
+
+## Combining — real patterns
+
+### Route errors to a dedicated file
+
+```ts
+log.setChannels([
+  new ConsoleLog(),
+  new FileLog({
+    name: "errors",
+    levels: ["error", "warn"],
+    chunk: "daily",
+  }),
+]);
+// ConsoleLog sees everything; errors.log only grows with warnings and errors.
+```
+
+### Silence a noisy module
+
+```ts
+new ConsoleLog({
+  filter: (data) => data.module !== "socket.io",
+});
+```
+
+### Keep the dev terminal focused
+
+```ts
+// Only surface the subsystem you're actively working on
+new ConsoleLog({
+  filter: (data) => data.module === "auth",
+});
+```
+
+### Errors always pass, info only for one module
+
+```ts
+new ConsoleLog({
+  filter: (data) => data.type === "error" || data.module === "payments",
+});
+```
+
+## Where filtering happens
+
+`LogChannel.shouldBeLogged(data)` runs both checks in order:
+
+```ts
+// levels check — fast path
+if (this.config("levels")?.length && !this.config("levels").includes(data.type)) return false;
+
+// filter predicate — only runs if levels allowed it
+const filter = this.config("filter");
+if (filter) return filter(data);
+
+return true;
+```
+
+If you extend `LogChannel` to write a custom channel, call `this.shouldBeLogged(data)` first thing inside your `log(data)` method — you inherit both mechanisms for free. See [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md).
+
+## Logger-wide custom filtering — not a thing
+
+There is no `logger.setGlobalFilter()`. Each channel filters itself. If you want the same predicate everywhere, pass it to every channel constructor (or wrap your channels in a helper).
+
+## Performance note
+
+Filters run on **every** entry per channel. A synchronous, cheap predicate is fine. Avoid `await` inside — the channel receives a fully-formed `LoggingData` and the filter is sync-only (type: `(data: LoggingData) => boolean`).
+
+The `minLevel` check is the fastest of the three (single comparison before fan-out), so prefer it when "drop everything below X uniformly" matches your need.