@warlock.js/logger 5.23.2 → 5.25.0

package/skills/overview/SKILL.md

@@ -1,94 +1,94 @@
----
-name: overview
-description: "@warlock.js/logger overview for orientation and choosing the focused skill for the task."
----
-
-# `@warlock.js/logger` — overview
-
-Structured logging for Node. Six severity levels (with `fatal` strictly above `error`), a singleton plus a `Logger` class, channel-based fan-out (one entry → many sinks), PII redaction as a floor that channels can extend, buffered file writes with signal-triggered flush on shutdown, an awaitable async `log.flush()` for network/async channels, an optional Sentry channel, and a couple of ergonomic helpers (`timer`, `assert`) that turn boilerplate into one-liners.
-
-Ships standalone — `@warlock.js/core` is not required. Drop it into any Node project.
-
-## Server-only package
-
+---
+name: overview
+description: "@warlock.js/logger overview for orientation and choosing the focused skill for the task."
+---
+
+# `@warlock.js/logger` — overview
+
+Structured logging for Node. Six severity levels (with `fatal` strictly above `error`), a singleton plus a `Logger` class, channel-based fan-out (one entry → many sinks), PII redaction as a floor that channels can extend, buffered file writes with signal-triggered flush on shutdown, an awaitable async `log.flush()` for network/async channels, an optional Sentry channel, and a couple of ergonomic helpers (`timer`, `assert`) that turn boilerplate into one-liners.
+
+Ships standalone — `@warlock.js/core` is not required. Drop it into any Node project.
+
+## Server-only package
+
 `@warlock.js/logger`'s entire runtime surface is server-only — its `package.json` declares `"warlock": { "environment": "server" }`. This is build-boundary metadata read by `@warlock.js/web`'s Gate A (import resolution) and Gate C (emitted-bundle verification), not application behavior. App code that reaches the client bundle (including page and layout modules) must not value-import `@warlock.js/logger` — Gate A refuses the build. A type-only import (`import type { ... }`) is allowed. Server loaders, controllers, and modules may import it freely.
-
-## When to reach for it
-
-- Building a Node service that needs **structured** logs (key-value pairs, not bare strings) and you want them to land in multiple destinations (console for dev, JSON file for prod, third-party sink for audits) without rewriting the call sites.
-- You'd reach for **pino** or **winston** but want a smaller surface that's already wired into Warlock conventions (`module / action / message` shape, redaction floor, signal flush built-in).
-- Your team agrees that **`console.log` doesn't survive contact with production** — you need filtering, level routing, channel-specific sinks, and a redaction story before secrets leak into Slack/Datadog.
-
-Skip if your code is a throwaway script where `console.log` is genuinely fine — there's no value in adding a dependency for one-off logs.
-
-## The mental model in one paragraph
-
-You write `log.info("auth", "login", "user signed in", { userId })`. The logger fans that single entry out to every registered channel (`ConsoleLog`, `FileLog`, `JSONFileLog`, `SentryLog`, or your custom subclass). Each channel decides whether to emit it (per-level whitelist, per-channel filter predicate, logger-wide minimum severity). Redaction runs once at the logger level and can be extended per channel — never relaxed. Buffered channels (file + JSON file) drain on flush — synchronously via `log.flushSync()` / `enableAutoFlush(['SIGINT', 'SIGTERM', 'beforeExit'])`, or asynchronously via `await log.flush()` (the only path that works for network channels like `SentryLog`). That's the whole package.
-
-## Skills index
-
-Eleven task skills cover everything. Load the one that matches your job — most callers only ever need `logger-basics` + `configure-logger` + `pick-log-channel`.
-
-### Foundations
-
-#### [`logger-basics`](@warlock.js/logger/logger-basics/SKILL.md)
-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`](@warlock.js/logger/configure-logger/SKILL.md)
-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`](@warlock.js/logger/pick-log-channel/SKILL.md)
-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`](@warlock.js/logger/ship-logs-to-sentry/SKILL.md)
-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`](@warlock.js/logger/write-custom-log-channel/SKILL.md)
-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`](@warlock.js/logger/redact-sensitive-log-fields/SKILL.md)
-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`](@warlock.js/logger/filter-log-entries/SKILL.md)
-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`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md)
-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`](@warlock.js/logger/capture-unhandled-errors/SKILL.md)
-`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`](@warlock.js/logger/use-log-helpers/SKILL.md)
-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`](@warlock.js/logger/test-logging-code/SKILL.md)
-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) |
-
-`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.
-
-## What this package deliberately doesn't do
-
-- **Distributed tracing.** Use OpenTelemetry. Logger gets you structured local logs with `module / action`; trace correlation is a different problem.
-- **Log aggregator integrations beyond Sentry.** `SentryLog` is bundled (with `@sentry/node` as an optional peer). For Datadog, Loki, ELK, etc., either write a custom channel that POSTs to the aggregator or use `JSONFileLog` + a sidecar (fluentbit, vector, promtail).
-- **Pretty-printing of arbitrary objects.** `ConsoleLog` has a `showContext` flag that runs `util.inspect` on the context object; for richer formatting, use `JSONFileLog` and view the file through your favorite viewer.
-- **Log analysis.** Querying / aggregating / alerting is on the sink side (Loki, ELK, Datadog).
-
-## See also
-
-- [`@warlock.js/core/warlock-conventions`](@warlock.js/core/warlock-conventions/SKILL.md) — the parent framework's conventions; logger is one of its foundation packages and ships transitively when you install core.
-- When synced via agent-kit, this `overview/SKILL.md` is flattened to the front-door skill `.claude/skills/warlock-js-logger-overview/` — every cross-link above uses the `@warlock.js/logger/<skill>/SKILL.md` name form so it survives that flattening.
+
+## When to reach for it
+
+- Building a Node service that needs **structured** logs (key-value pairs, not bare strings) and you want them to land in multiple destinations (console for dev, JSON file for prod, third-party sink for audits) without rewriting the call sites.
+- You'd reach for **pino** or **winston** but want a smaller surface that's already wired into Warlock conventions (`module / action / message` shape, redaction floor, signal flush built-in).
+- Your team agrees that **`console.log` doesn't survive contact with production** — you need filtering, level routing, channel-specific sinks, and a redaction story before secrets leak into Slack/Datadog.
+
+Skip if your code is a throwaway script where `console.log` is genuinely fine — there's no value in adding a dependency for one-off logs.
+
+## The mental model in one paragraph
+
+You write `log.info("auth", "login", "user signed in", { userId })`. The logger fans that single entry out to every registered channel (`ConsoleLog`, `FileLog`, `JSONFileLog`, `SentryLog`, or your custom subclass). Each channel decides whether to emit it (per-level whitelist, per-channel filter predicate, logger-wide minimum severity). Redaction runs once at the logger level and can be extended per channel — never relaxed. Buffered channels (file + JSON file) drain on flush — synchronously via `log.flushSync()` / `enableAutoFlush(['SIGINT', 'SIGTERM', 'beforeExit'])`, or asynchronously via `await log.flush()` (the only path that works for network channels like `SentryLog`). That's the whole package.
+
+## Skills index
+
+Eleven task skills cover everything. Load the one that matches your job — most callers only ever need `logger-basics` + `configure-logger` + `pick-log-channel`.
+
+### Foundations
+
+#### [`logger-basics`](@warlock.js/logger/logger-basics/SKILL.md)
+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`](@warlock.js/logger/configure-logger/SKILL.md)
+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`](@warlock.js/logger/pick-log-channel/SKILL.md)
+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`](@warlock.js/logger/ship-logs-to-sentry/SKILL.md)
+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`](@warlock.js/logger/write-custom-log-channel/SKILL.md)
+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`](@warlock.js/logger/redact-sensitive-log-fields/SKILL.md)
+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`](@warlock.js/logger/filter-log-entries/SKILL.md)
+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`](@warlock.js/logger/flush-logs-on-shutdown/SKILL.md)
+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`](@warlock.js/logger/capture-unhandled-errors/SKILL.md)
+`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`](@warlock.js/logger/use-log-helpers/SKILL.md)
+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`](@warlock.js/logger/test-logging-code/SKILL.md)
+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) |
+
+`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.
+
+## What this package deliberately doesn't do
+
+- **Distributed tracing.** Use OpenTelemetry. Logger gets you structured local logs with `module / action`; trace correlation is a different problem.
+- **Log aggregator integrations beyond Sentry.** `SentryLog` is bundled (with `@sentry/node` as an optional peer). For Datadog, Loki, ELK, etc., either write a custom channel that POSTs to the aggregator or use `JSONFileLog` + a sidecar (fluentbit, vector, promtail).
+- **Pretty-printing of arbitrary objects.** `ConsoleLog` has a `showContext` flag that runs `util.inspect` on the context object; for richer formatting, use `JSONFileLog` and view the file through your favorite viewer.
+- **Log analysis.** Querying / aggregating / alerting is on the sink side (Loki, ELK, Datadog).
+
+## See also
+
+- [`@warlock.js/core/warlock-conventions`](@warlock.js/core/warlock-conventions/SKILL.md) — the parent framework's conventions; logger is one of its foundation packages and ships transitively when you install core.
+- When synced via agent-kit, this `overview/SKILL.md` is flattened to the front-door skill `.claude/skills/warlock-js-logger-overview/` — every cross-link above uses the `@warlock.js/logger/<skill>/SKILL.md` name form so it survives that flattening.

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

@@ -1,155 +1,155 @@
----
-name: pick-log-channel
-description: '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`.'
----
-
-# Channels — which one to pick and how to configure it
-
-Four built-in channels (`SentryLog` needs the optional `@sentry/node` peer). A channel is a destination for a log entry — the logger fans out every entry to every registered channel in parallel.
-
-## The decision
-
-| 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` |
-
-Most production setups use **two** channels: `ConsoleLog` + one file channel. Dev uses `ConsoleLog` only.
-
-## `ConsoleLog`
-
-Zero config. Colored, icon-prefixed lines to the terminal.
-
-```ts
-import { ConsoleLog } from "@warlock.js/logger";
-
-new ConsoleLog();
-// ⚙ debug (10:22:00.000) [auth] [hashPassword] Hashing started
-// ℹ info (10:22:01.482) [users] [register] New user created
-// ✗ error (10:22:03.111) [payments] [charge] Card declined
-```
-
-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
-
-### Showing context
-
-By default `ConsoleLog` drops the `context` payload (the file/JSON channels still keep it). Flip `showContext: true` to render it on a second line — useful in development:
-
-```ts
-new ConsoleLog({ showContext: true });
-
-log.info("payments", "charge", "card declined", { userId: 42, amount: 1999 });
-// ℹ info (…) [payments] [charge] card declined
-//   ↳ { userId: 42, amount: 1999 }
-```
-
-Tune `contextDepth` (default `4`) to clamp how deep `util.inspect` recurses into nested objects.
-
-## `FileLog`
-
-Plain text. Buffers in memory, flushes to disk periodically.
-
-```ts
-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
-});
-```
-
-Line format: `[date time] [level] [module][action]: message` — or a `[trace]` block when `message` is an `Error`.
-
-### 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.
-- **`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.)
-
-## `JSONFileLog`
-
-Subclass of `FileLog` — same buffering, chunking, rotation, grouping. Output is a JSON object with a `messages` array:
-
-```json
-{
-  "messages": [
-    {
-      "content": "Card declined",
-      "level": "error",
-      "date": "15-03-2024 10:22:03",
-      "module": "payments",
-      "action": "charge",
-      "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
-- `content` holds the original user-supplied `message` (not a pre-formatted line)
-- Corrupted existing file → reinitialized to `{ messages: [] }` on next write (does not throw)
-- **Safe serialization by construction.** All writes go through `safe-stable-stringify` with a custom `Error` replacer — circular refs become `"[Circular]"`, BigInt is stringified, functions/symbols are dropped, nested `Error` instances expand to `{ name, message, stack, ...enumerable }`. A context payload with a class graph or circular reference will never throw during the write.
-
-## `SentryLog`
-
-Forwards entries to Sentry — `error` / `warn` become events (`captureException` for `Error` messages, `captureMessage` otherwise), every other level a breadcrumb (no quota). `@sentry/node` is an optional peer, lazily imported; pass an existing `client` or `options`.
-
-```ts
-import * as Sentry from "@sentry/node";
-import { SentryLog } from "@warlock.js/logger";
-
-new SentryLog({ client: Sentry, eventLevels: ["error", "warn"] });
-```
-
-Full guide — level mapping, init modes, shutdown draining: [`ship-logs-to-sentry`](@warlock.js/logger/ship-logs-to-sentry/SKILL.md).
-
-## Shared config — `BasicLogConfigurations`
-
-Every channel constructor accepts at minimum:
-
-```ts
-type BasicLogConfigurations = {
-  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
-};
-```
-
-Concrete file channels extend this with their storage/chunk/rotate/groupBy options via intersection.
-
-## 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
-```
-
-If two channels share a `name`, only one is reachable this way — the search returns the first match.
-
-## See also
-
-- [`@warlock.js/logger/configure-logger/SKILL.md`](@warlock.js/logger/configure-logger/SKILL.md) — registering channels at startup
-- [`@warlock.js/logger/filter-log-entries/SKILL.md`](@warlock.js/logger/filter-log-entries/SKILL.md) — `levels` and `filter` config in detail
-- [`@warlock.js/logger/ship-logs-to-sentry/SKILL.md`](@warlock.js/logger/ship-logs-to-sentry/SKILL.md) — the `SentryLog` channel in depth
-- [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md) — extending `LogChannel` for custom sinks
+---
+name: pick-log-channel
+description: '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`.'
+---
+
+# Channels — which one to pick and how to configure it
+
+Four built-in channels (`SentryLog` needs the optional `@sentry/node` peer). A channel is a destination for a log entry — the logger fans out every entry to every registered channel in parallel.
+
+## The decision
+
+| 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` |
+
+Most production setups use **two** channels: `ConsoleLog` + one file channel. Dev uses `ConsoleLog` only.
+
+## `ConsoleLog`
+
+Zero config. Colored, icon-prefixed lines to the terminal.
+
+```ts
+import { ConsoleLog } from "@warlock.js/logger";
+
+new ConsoleLog();
+// ⚙ debug (10:22:00.000) [auth] [hashPassword] Hashing started
+// ℹ info (10:22:01.482) [users] [register] New user created
+// ✗ error (10:22:03.111) [payments] [charge] Card declined
+```
+
+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
+
+### Showing context
+
+By default `ConsoleLog` drops the `context` payload (the file/JSON channels still keep it). Flip `showContext: true` to render it on a second line — useful in development:
+
+```ts
+new ConsoleLog({ showContext: true });
+
+log.info("payments", "charge", "card declined", { userId: 42, amount: 1999 });
+// ℹ info (…) [payments] [charge] card declined
+//   ↳ { userId: 42, amount: 1999 }
+```
+
+Tune `contextDepth` (default `4`) to clamp how deep `util.inspect` recurses into nested objects.
+
+## `FileLog`
+
+Plain text. Buffers in memory, flushes to disk periodically.
+
+```ts
+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
+});
+```
+
+Line format: `[date time] [level] [module][action]: message` — or a `[trace]` block when `message` is an `Error`.
+
+### 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.
+- **`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.)
+
+## `JSONFileLog`
+
+Subclass of `FileLog` — same buffering, chunking, rotation, grouping. Output is a JSON object with a `messages` array:
+
+```json
+{
+  "messages": [
+    {
+      "content": "Card declined",
+      "level": "error",
+      "date": "15-03-2024 10:22:03",
+      "module": "payments",
+      "action": "charge",
+      "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
+- `content` holds the original user-supplied `message` (not a pre-formatted line)
+- Corrupted existing file → reinitialized to `{ messages: [] }` on next write (does not throw)
+- **Safe serialization by construction.** All writes go through `safe-stable-stringify` with a custom `Error` replacer — circular refs become `"[Circular]"`, BigInt is stringified, functions/symbols are dropped, nested `Error` instances expand to `{ name, message, stack, ...enumerable }`. A context payload with a class graph or circular reference will never throw during the write.
+
+## `SentryLog`
+
+Forwards entries to Sentry — `error` / `warn` become events (`captureException` for `Error` messages, `captureMessage` otherwise), every other level a breadcrumb (no quota). `@sentry/node` is an optional peer, lazily imported; pass an existing `client` or `options`.
+
+```ts
+import * as Sentry from "@sentry/node";
+import { SentryLog } from "@warlock.js/logger";
+
+new SentryLog({ client: Sentry, eventLevels: ["error", "warn"] });
+```
+
+Full guide — level mapping, init modes, shutdown draining: [`ship-logs-to-sentry`](@warlock.js/logger/ship-logs-to-sentry/SKILL.md).
+
+## Shared config — `BasicLogConfigurations`
+
+Every channel constructor accepts at minimum:
+
+```ts
+type BasicLogConfigurations = {
+  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
+};
+```
+
+Concrete file channels extend this with their storage/chunk/rotate/groupBy options via intersection.
+
+## 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
+```
+
+If two channels share a `name`, only one is reachable this way — the search returns the first match.
+
+## See also
+
+- [`@warlock.js/logger/configure-logger/SKILL.md`](@warlock.js/logger/configure-logger/SKILL.md) — registering channels at startup
+- [`@warlock.js/logger/filter-log-entries/SKILL.md`](@warlock.js/logger/filter-log-entries/SKILL.md) — `levels` and `filter` config in detail
+- [`@warlock.js/logger/ship-logs-to-sentry/SKILL.md`](@warlock.js/logger/ship-logs-to-sentry/SKILL.md) — the `SentryLog` channel in depth
+- [`@warlock.js/logger/write-custom-log-channel/SKILL.md`](@warlock.js/logger/write-custom-log-channel/SKILL.md) — extending `LogChannel` for custom sinks