@warlock.js/logger 5.30.0 → 5.31.0

package/skills/redact-sensitive-log-fields/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: redact-sensitive-log-fields
-description: '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`.'
+description: '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`.'
 ---
 
 # Redaction — keeping secrets out of logs
@@ -25,15 +25,15 @@ import { DEFAULT_REDACT_KEYS } from "@warlock.js/logger";
 
 log.configure({
   redact: {
-    keys: ["internalRef"],   // union with the built-in set
-    defaultKeys: false,      // opt out of the built-in set entirely
+    keys: ["internalRef"], // union with the built-in set
+    defaultKeys: false, // opt out of the built-in set entirely
   },
 });
 ```
 
 `defaultKeys: false` is an escape hatch, not a tuning knob — it restores the pre-4.15.0 behavior where a `password` in `context` reaches every sink in cleartext. Prefer adding a function `censor` if you only need to keep a prefix.
 
-**A channel cannot turn the default set off** (it can only add keys, or turn it back *on* if the logger-wide config disabled it) — same additive-only contract as paths, below. And `log.setRedact(undefined)` clears *your* paths, not the default denylist.
+**A channel cannot turn the default set off** (it can only add keys, or turn it back _on_ if the logger-wide config disabled it) — same additive-only contract as paths, below. And `log.setRedact(undefined)` clears _your_ paths, not the default denylist.
 
 Not reachable by any layer: secrets interpolated into a `message` string (`` `token=${t}` ``), `Map`/`Set`/`Buffer` contents, and getter-backed or non-enumerable properties.
 
@@ -54,18 +54,14 @@ import { log } from "@warlock.js/logger";
 
 log.configure({
   redact: {
-    paths: [
-      "context.password",
-      "context.*.token",
-      "context.headers.authorization",
-    ],
-    censor: "[REDACTED]",  // default — string or function
+    paths: ["context.password", "context.*.token", "context.headers.authorization"],
+    censor: "[REDACTED]", // default — string or function
   },
 });
 
 // runtime equivalent:
 log.setRedact({ paths: ["context.password"] });
-log.setRedact(undefined);  // clear your paths (the default denylist stays on)
+log.setRedact(undefined); // clear your paths (the default denylist stays on)
 ```
 
 Every channel sees the redacted entry. Cheap: applied **once** before fan-out; channels share the redacted clone unless they add their own paths.
@@ -107,13 +103,13 @@ type LoggingData = {
 };
 ```
 
-| Pattern | Matches |
-| --- | --- |
-| `context.password` | exactly `data.context.password` |
-| `context.*.token` | `data.context.<any>.token` (one segment in between) |
-| `**.password` | `data.context.password`, `data.context.user.password`, … any depth |
-| `message.apiKey` | when message is an object, `data.message.apiKey` |
-| `context.users.*.token` | array element redaction (`*` matches indices too) |
+| Pattern                 | Matches                                                            |
+| ----------------------- | ------------------------------------------------------------------ |
+| `context.password`      | exactly `data.context.password`                                    |
+| `context.*.token`       | `data.context.<any>.token` (one segment in between)                |
+| `**.password`           | `data.context.password`, `data.context.user.password`, … any depth |
+| `message.apiKey`        | when message is an object, `data.message.apiKey`                   |
+| `context.users.*.token` | array element redaction (`*` matches indices too)                  |
 
 Wildcards:
 
@@ -154,3 +150,37 @@ If `message` is a plain object, paths under `message.*` work as expected. If `me
 - Each path is matched independently; cost grows linearly with `paths.length`.
 
 For most apps with `<10` redact paths and shallow context, the cost is below 100µs per entry. If you're logging millions of entries per second through paths like `**.something`, profile before scaling up — `**` is the only pattern that recurses through every key.
+
+## Email addresses inside strings
+
+```ts
+import { log, maskEmail, maskEmailsInText } from "@warlock.js/logger";
+
+log.info("mail", "send", `Sending to ${maskEmail("member@example.com")}`);
+log.debug("cache", "key", maskEmailsInText("profile:member@example.com"));
+```
+
+Key-based redaction cannot mask a substring inside a message or cache key.
+`maskEmail()` keeps the first code point and domain (`m***@example.com`);
+`maskEmailsInText()` handles text and bounds its scan at 16,384 characters,
+replacing the remaining suffix with a truncation marker.
+
+## Client text inside a message: `escapeLogValue()`
+
+A user agent or search term with a line break forges an extra entry in console
+and file logs; an ANSI sequence rewrites the terminal. Escape it first:
+
+```ts
+import { escapeLogValue, log } from "@warlock.js/logger";
+
+export function logSearch(term: string, userAgent: string) {
+  log.info("search", "query", `"${escapeLogValue(term, { maxLength: 200 })}"`, {
+    agent: escapeLogValue(userAgent),
+  });
+}
+```
+
+CR/LF/tab become `\r`/`\n`/`\t`, other control characters `\uXXXX`, ANSI
+sequences are removed; `maxLength` cuts and marks `…[truncated]`. `warlock
+check` (from `@warlock.js/core`) reports raw emails, credentials and request
+bodies in log calls as `WL9008` and accepts these helpers.

package/skills/ship-logs-to-sentry/SKILL.md

@@ -50,14 +50,14 @@ With neither `client` nor `options`, the channel reuses whatever global Sentry c
 
 This is the quota-control decision. Only `eventLevels` create Sentry **events** (which consume your error quota); every other level becomes a **breadcrumb** that rides along with the next event for free.
 
-| Logger level | Default | Sentry call |
-|---|---|---|
-| `fatal` | event | `captureException` for an `Error` message, else `captureMessage(…, "fatal")` |
-| `error` | event | `captureException` for an `Error` message, else `captureMessage(…, "error")` |
-| `warn` | event | `captureMessage(…, "warning")` |
-| `success` | breadcrumb | `addBreadcrumb({ level: "info" })` |
-| `info` | breadcrumb | `addBreadcrumb({ level: "info" })` |
-| `debug` | breadcrumb | `addBreadcrumb({ level: "debug" })` |
+| Logger level | Default    | Sentry call                                                                  |
+| ------------ | ---------- | ---------------------------------------------------------------------------- |
+| `fatal`      | event      | `captureException` for an `Error` message, else `captureMessage(…, "fatal")` |
+| `error`      | event      | `captureException` for an `Error` message, else `captureMessage(…, "error")` |
+| `warn`       | event      | `captureMessage(…, "warning")`                                               |
+| `success`    | breadcrumb | `addBreadcrumb({ level: "info" })`                                           |
+| `info`       | breadcrumb | `addBreadcrumb({ level: "info" })`                                           |
+| `debug`      | breadcrumb | `addBreadcrumb({ level: "debug" })`                                          |
 
 - **Errors keep their stack.** A `message` that is an `Error` goes through `captureException`, so Sentry parses the real stack and groups correctly — never pre-stringify the error.
 - **`module` / `action` become tags** and the entry's `context` becomes a structured Sentry context, both scoped to that single event via `withScope`.
@@ -82,14 +82,14 @@ Sentry sends events asynchronously over the network, so a synchronous flush can'
 ```ts
 async function shutdown() {
   await httpServer.close();
-  await log.flush();   // SentryLog.flush() → Sentry.flush(flushTimeout)
+  await log.flush(); // SentryLog.flush() → Sentry.flush(flushTimeout)
   process.exit(0);
 }
 
 process.once("SIGTERM", shutdown);
 ```
 
-`flushTimeout` (default `2000` ms) bounds the wait so an unreachable Sentry can't hang shutdown. `autoFlushOn` uses the **synchronous** `flushSync()`, which does *not* drain Sentry — wire `await log.flush()` yourself. See the `flush-logs-on-shutdown` topic.
+`flushTimeout` (default `2000` ms) bounds the wait so an unreachable Sentry can't hang shutdown. `autoFlushOn` uses the **synchronous** `flushSync()`, which does _not_ drain Sentry — wire `await log.flush()` yourself. See the `flush-logs-on-shutdown` topic.
 
 ## If `@sentry/node` isn't installed
 
@@ -97,17 +97,17 @@ The channel never crashes your app: the dynamic import failure is swallowed, the
 
 ## Config reference
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `client` | Sentry namespace / forwarder | — | Reuse an already-initialized Sentry instance. |
-| `options` | `SentryInitOptions` | — | Sentry init options (mirrors `@sentry/node`'s `NodeOptions`) — used when the channel owns Sentry. |
-| `eventLevels` | `LogLevel[]` | `["fatal", "error", "warn"]` | Levels sent as events; the rest become breadcrumbs. |
-| `flushTimeout` | `number` | `2000` | Ms `flush()` waits for the transport to drain. |
-| `levels`, `filter`, `dateFormat`, `redact` | — | — | Inherited from `BasicLogConfigurations`. |
+| Option                                     | Type                         | Default                      | Description                                                                                       |
+| ------------------------------------------ | ---------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------- |
+| `client`                                   | Sentry namespace / forwarder | —                            | Reuse an already-initialized Sentry instance.                                                     |
+| `options`                                  | `SentryInitOptions`          | —                            | Sentry init options (mirrors `@sentry/node`'s `NodeOptions`) — used when the channel owns Sentry. |
+| `eventLevels`                              | `LogLevel[]`                 | `["fatal", "error", "warn"]` | Levels sent as events; the rest become breadcrumbs.                                               |
+| `flushTimeout`                             | `number`                     | `2000`                       | Ms `flush()` waits for the transport to drain.                                                    |
+| `levels`, `filter`, `dateFormat`, `redact` | —                            | —                            | Inherited from `BasicLogConfigurations`.                                                          |
 
 ## Don't do
 
-- **Don't double-init Sentry.** Pass *either* `client` *or* `options`, not both. The channel guards against double-init, but a single owner of `Sentry.init` is cleaner.
+- **Don't double-init Sentry.** Pass _either_ `client` _or_ `options`, not both. The channel guards against double-init, but a single owner of `Sentry.init` is cleaner.
 - **Don't send every level as an event.** `eventLevels` with `info`/`debug`/`success` will flood your Sentry quota — keep them as breadcrumbs.
 - **Don't rely on `autoFlushOn` for Sentry.** It's synchronous; a network channel needs `await log.flush()`.
 

package/skills/test-logging-code/SKILL.md

@@ -41,7 +41,9 @@ class CapturingChannel extends LogChannel {
   public name = "capture";
   public terminal = false;
   public received: LoggingData[] = [];
-  public log(data: LoggingData) { this.received.push({ ...data }); }
+  public log(data: LoggingData) {
+    this.received.push({ ...data });
+  }
 }
 ```
 
@@ -100,7 +102,7 @@ No cleanup needed — the local `Logger` is garbage-collected.
 
 ## Why not spy on `log.info`?
 
-`log` is a plain `Logger` instance (`export const log = new Logger()`) and every level method lives on the prototype, so `vi.spyOn(log, "info")` *does* technically work. Prefer the capturing channel anyway:
+`log` is a plain `Logger` instance (`export const log = new Logger()`) and every level method lives on the prototype, so `vi.spyOn(log, "info")` _does_ technically work. Prefer the capturing channel anyway:
 
 - A spy on `log.info` proves the method was **called**, not that an entry was **delivered** — it skips the whole pipeline (`minLevel` floor, redaction, per-channel `levels` / `filter`). A capturing channel asserts on the entry your code under test actually produced after all of that ran.
 - The `log` singleton is shared global state. A spy you forget to `mockRestore()` leaks into the next test; swapping `log.channels` and restoring it in `afterEach` is the same amount of code and isolates cleanly.

package/skills/write-custom-log-channel/SKILL.md

@@ -19,6 +19,7 @@ export class NullChannel extends LogChannel {
 ```
 
 Then:
+
 ```ts
 log.addChannel(new NullChannel());
 ```
@@ -27,16 +28,16 @@ That's a working channel. `LogChannel` provides the scaffolding; you only need t
 
 ## What `LogChannel` gives you
 
-| Thing | Who provides it |
-|---|---|
-| `name`, `description`, `terminal` | You (fields on your subclass) |
-| `log(data)` | **You must implement** — abstract |
-| `flushSync()` | You (optional sync drain — only if you buffer) |
-| `flush()` | You (optional async drain — only if you buffer over async I/O) |
-| `init()` | You (optional async hook — see below) |
-| `shouldBeLogged(data)` | `LogChannel` — combines `levels` + `filter` |
-| `config<K>(key)` | `LogChannel` — merges user config with `defaultConfigurations` |
-| `getDateAndTimeFormat()` | `LogChannel` — returns resolved `dateFormat` |
+| Thing                             | Who provides it                                                |
+| --------------------------------- | -------------------------------------------------------------- |
+| `name`, `description`, `terminal` | You (fields on your subclass)                                  |
+| `log(data)`                       | **You must implement** — abstract                              |
+| `flushSync()`                     | You (optional sync drain — only if you buffer)                 |
+| `flush()`                         | You (optional async drain — only if you buffer over async I/O) |
+| `init()`                          | You (optional async hook — see below)                          |
+| `shouldBeLogged(data)`            | `LogChannel` — combines `levels` + `filter`                    |
+| `config<K>(key)`                  | `LogChannel` — merges user config with `defaultConfigurations` |
+| `getDateAndTimeFormat()`          | `LogChannel` — returns resolved `dateFormat`                   |
 
 ## Complete example — SlackLog
 
@@ -54,7 +55,7 @@ export class SlackLog extends LogChannel<SlackConfig> {
   public description = "Posts errors + warnings to a Slack webhook";
 
   public async log(data: LoggingData) {
-    if (!this.shouldBeLogged(data)) return;   // ← inherit levels + filter
+    if (!this.shouldBeLogged(data)) return; // ← inherit levels + filter
 
     await fetch(this.config("webhookUrl"), {
       method: "POST",
@@ -85,9 +86,7 @@ log.setChannels([
 Override `protected async init()` for one-time setup — open a socket, connect to a DB, prepare a write stream. Runs automatically after construction (inside a `setTimeout(0)`); `isInitialized` flips to `true` once resolved.
 
 ```ts
-export class DatabaseLog extends LogChannel<
-  BasicLogConfigurations & { connectionString: string }
-> {
+export class DatabaseLog extends LogChannel<BasicLogConfigurations & { connectionString: string }> {
   public name = "database";
   private client!: SomeDbClient;
 
@@ -102,6 +101,38 @@ export class DatabaseLog extends LogChannel<
 }
 ```
 
+## Reporting background failures — `reportError()`
+
+A failure inside `log()` reaches `log.onChannelError(...)` on its own. For work outside a `log()` call (a timer, a reconnect, a cleanup in `init()`), call `this.reportError(error, entry)`: the logger the channel was added to forwards it to its handler, and a channel not yet added writes one stderr line. It never throws.
+
+```ts
+export class QueueLog extends LogChannel {
+  public name = "queue";
+
+  protected init() {
+    setInterval(() => {
+      this.drain().catch((error) =>
+        this.reportError(error, {
+          type: "error",
+          module: "logger",
+          action: "drain",
+          message: "Queue drain failed",
+        }),
+      );
+    }, 1_000);
+  }
+
+  public log(data: LoggingData) {
+    if (!this.shouldBeLogged(data)) return;
+    // enqueue data …
+  }
+
+  private async drain() {
+    // send queued entries …
+  }
+}
+```
+
 ## Implementing `flushSync()`
 
 Only if your channel buffers. Signature: `flushSync?(): void`. Synchronous — no `await`, no promises.
@@ -123,7 +154,9 @@ export class BatchHttpLog extends LogChannel<BasicLogConfigurations & { url: str
     // so a follow-up async drain can recover it next boot.
   }
 
-  private async drain() { /* async post to this.config("url") */ }
+  private async drain() {
+    /* async post to this.config("url") */
+  }
 }
 ```
 
@@ -143,7 +176,7 @@ export class BatchHttpLog extends LogChannel<BasicLogConfigurations & { url: str
   }
 
   public async flush() {
-    await this.drain();   // awaited by log.flush() on shutdown
+    await this.drain(); // awaited by log.flush() on shutdown
   }
 
   private async drain() {
@@ -175,7 +208,7 @@ class MinimalSlack implements LogContract {
 
   public async log(data: LoggingData) {
     if (data.type !== "error") return;
-    await fetch(process.env.SLACK_WEBHOOK!, { /* ... */ });
+    await fetch(process.env.SLACK_WEBHOOK!, {/* ... */});
   }
 }
 ```