@chronicle.app/logging 0.3.0 → 0.5.0

package/README.md

@@ -1,22 +1,65 @@
 # @chronicle.app/logging
 
-Shared stderr logger for Chronicle. Node.js 22.13+; ESM with TypeScript declarations.
+Chronicle's output events and the sinks that render them. Node.js 22.13+; ESM
+with TypeScript declarations.
 
 ```js
-import { createLogger } from '@chronicle.app/logging';
+import { createLogger, JsonSink } from '@chronicle.app/logging';
 
-const logger = createLogger({ prefix: '[extract]', verbose: true });
+const logger = createLogger({ scope: 'example', verbose: true });
 logger.info('Extracted records', { count: 3 });
 logger.debug('Source cursor', { position: 3 });
+
+// A host hands its own sink over; events then render its way.
+logger.use(new JsonSink(), { run: { id: 'run-1', source: 'example', strategy: 'file' } });
+logger.warn('Line skipped', { line: 42 });
 ```
 
-All output goes to stderr so stdout stays available for extracted data. `quiet`
-suppresses everything except errors. Debug messages require `verbose`; `level`
-filters info/warn output. `verboseInfo` requires verbose and non-quiet mode. Errors
-always print. Context can be rendered inline or with `debugMultiline`. A custom
-`theme` supplies functions for each level; default colors are disabled for pipes.
+Each logger call becomes an `OutputEvent`: a `kind`, a `level`, the logger's
+`scope` and `run`, a plain `message`, and the second argument as `fields`.
+`debug` and `verboseInfo` are debug-level diagnostics, `info` and `warn` are
+notices, and `error` is an error. `emit` sends any event, including the host's
+`progress`, `hint`, and `summary`.
+
+A sink decides what to show and how. `TextSink` writes lines to stderr; by
+default each is `HH:MM:SS level scope: message key=value`, and a host passes
+its own `format`. `JsonSink` writes one JSON object per line, turns progress
+into a heartbeat, and redacts the fields an event marks `sensitive` unless
+`personal` is set. Both filter by `level` (`thresholdFor({ quiet, verbose })`
+maps the common flags), and both keep repeated events from flooding.
+
+Events group by their `key`, or without one by scope and message with the
+numbers taken out (`Generated 1 actions` and `Generated 3 actions` are one
+group). Each group shows its first three events, then counts the rest and
+reports them as a roll-up (`…412 more like this in 5s`) at most every five
+seconds, or every second for warnings and errors. A roll-up's fields hold
+the count and how often each field value came up; personal values go under
+`personal`, which JSON redacts. `flush()` reports what's left as `…and N more
+like this`, and a `summary` event flushes first. Pass `aggregate: { examples,
+windowMs, urgentWindowMs }` to a sink to change the numbers.
+
+A logger without a sink of its own uses the process-wide one a host sets
+with `setDefaultSink`, so a host can redirect every logger, including
+module-level ones in shared packages. Without either, it writes plain lines
+to stderr at the level its `quiet`, `verbose`, and `level` options ask for;
+errors always print. With `sensitive: true` every field it logs is marked
+personal.
+
+`captureConsole(logger)` routes `console.*` through a logger as diagnostics
+until the function it returns restores the console, for code the host doesn't
+control. Chronicle's own code never calls `console`; lint enforces it.
+
+## Errors
 
-`npm run build -w @chronicle.app/logging` builds the package; `npm test -w
-@chronicle.app/logging` exercises its public API after a build.
+`ExtractorError` and its subclasses name a failure so hosts can act on it
+without reading the message: `AuthRequired` (exit code 3), `PermissionDenied`
+and `InputNotFound` (4), `RateLimited` with `retryAfter` (5), and
+`ExtractorError` itself with any `code` (1 unless given). Each carries a
+`hint`, the next step for a person, and `fields`, which are personal.
+`EXIT_CODES` lists the codes: 1 internal, 2 usage, 3 auth, 4 input, 5
+transient. `describeError` reads the code, exit code, and hint of any thrown
+value, duck-typed so an error from another copy of this package still reads
+as what it is. `markReported` and `isReported` let a host that already
+reported an error as an event avoid printing it twice.
 
 MIT. See [LICENSE](LICENSE).

package/dist/Logger.d.ts

@@ -1,15 +1,29 @@
-import { LoggerOptions, LoggerContext } from './types.js';
+import type { LoggerContext, LoggerOptions, OutputEvent, RunContext, Sink } from './types.js';
+/**
+ * Emits events to a sink. Each call becomes an {@link OutputEvent} with this
+ * logger's scope and run; the second argument becomes the event's `fields`.
+ * Without a sink of its own, a logger follows the process-wide default
+ * ({@link setDefaultSink}), and without that prints plain lines on stderr.
+ */
 export declare class Logger {
-    private prefix;
-    private level;
-    private quiet;
-    private verbose;
-    private theme;
+    private scope;
+    private sink?;
+    private fallback?;
+    private run?;
+    private readonly sensitive;
+    private readonly options;
     constructor(options?: LoggerOptions);
-    private shouldLog;
-    private formatPrefix;
-    private formatMessage;
-    private formatCompactJson;
+    /** This logger's sink, else the process default, else plain stderr at its options' level. */
+    private target;
+    /** Send events to the host's sink from now on, for its run, under `scope` if given. */
+    use(sink: Sink, { run, scope }?: {
+        run?: RunContext;
+        scope?: string;
+    }): void;
+    /** Emit an event of any kind; `time`, `scope`, and `run` default to this logger's. */
+    emit(event: Omit<OutputEvent, 'time' | 'scope'> & Partial<OutputEvent>): void;
+    flush(): void;
+    private log;
     debug(message: string, context?: LoggerContext): void;
     debugMultiline(message: string, context?: LoggerContext): void;
     info(message: string, context?: LoggerContext): void;

package/dist/Logger.js

@@ -1,112 +1,84 @@
-import { defaultTheme } from './DefaultTheme.js';
-import chalk from 'chalk';
-const LOG_LEVELS = {
-    debug: 0,
-    info: 1,
-    warn: 2,
-    error: 3,
-};
+import { thresholdFor } from './levels.js';
+import { defaultSink } from './defaultSink.js';
+import { TextSink } from './sinks.js';
+/** `[ServiceName]` → `ServiceName`. */
+const scopeOf = (prefix) => prefix.match(/\[([^\]]+)\]/)?.[1] ?? prefix.trim();
+/**
+ * Emits events to a sink. Each call becomes an {@link OutputEvent} with this
+ * logger's scope and run; the second argument becomes the event's `fields`.
+ * Without a sink of its own, a logger follows the process-wide default
+ * ({@link setDefaultSink}), and without that prints plain lines on stderr.
+ */
 export class Logger {
-    prefix;
-    level;
-    quiet;
-    verbose;
-    theme;
+    scope;
+    sink;
+    fallback;
+    run;
+    sensitive;
+    options;
     constructor(options = {}) {
-        this.prefix = options.prefix ? `${options.prefix} ` : '';
-        this.level = options.level ?? 'info';
-        this.quiet = options.quiet ?? false;
-        this.verbose = options.verbose ?? false;
-        this.theme = options.theme ?? defaultTheme;
-        // Only enable colors when writing to a real terminal (not when PM2 captures stderr)
-        if (process.stderr.isTTY) {
-            chalk.level = 3; // Force full color support for terminals
-        }
-        else {
-            chalk.level = 0; // Disable colors for file/pipe output
-        }
+        this.options = options;
+        this.scope = options.scope ?? (options.prefix ? scopeOf(options.prefix) : '');
+        this.sink = options.sink;
+        this.run = options.run;
+        this.sensitive = options.sensitive ?? false;
     }
-    shouldLog(level) {
-        if (level === 'error')
-            return true; // Always show errors
-        if (this.quiet)
-            return false;
-        if (level === 'debug')
-            return this.verbose; // Debug messages only in verbose mode
-        return LOG_LEVELS[level] >= LOG_LEVELS[this.level];
+    /** This logger's sink, else the process default, else plain stderr at its options' level. */
+    target() {
+        if (this.sink)
+            return this.sink;
+        const host = defaultSink();
+        if (host)
+            return host;
+        this.fallback ??= new TextSink({ level: thresholdFor(this.options) });
+        return this.fallback;
     }
-    formatPrefix(serviceName) {
-        // Extract service name from prefix like '[ServiceName]' or just use as-is
-        const match = serviceName.match(/\[([^\]]+)\]/);
-        const name = match ? match[1] : serviceName.replaceAll(/^\s*|\s*$/g, '');
-        // Fixed width of 25 characters, left-aligned
-        return name.padEnd(25);
+    /** Send events to the host's sink from now on, for its run, under `scope` if given. */
+    use(sink, { run, scope } = {}) {
+        this.sink = sink;
+        if (run)
+            this.run = run;
+        if (scope)
+            this.scope = scope;
     }
-    formatMessage(message, context, multiline = false) {
-        const service = this.prefix ? this.formatPrefix(this.prefix) : ''.padEnd(25);
-        let formatted = `${service} ${message}`;
-        if (context && Object.keys(context).length > 0) {
-            if (multiline) {
-                // Custom JSON formatting: compact arrays, multiline objects
-                const compactJson = this.formatCompactJson(context);
-                formatted += `\n${compactJson}`;
-            }
-            else {
-                formatted += ` ${JSON.stringify(context)}`;
-            }
-        }
-        return formatted;
+    /** Emit an event of any kind; `time`, `scope`, and `run` default to this logger's. */
+    emit(event) {
+        this.target().emit({
+            time: new Date(),
+            scope: this.scope,
+            ...(this.run && { run: this.run }),
+            ...event,
+        });
     }
-    formatCompactJson(obj, depth = 0) {
-        const indent = '  '.repeat(depth);
-        const nextIndent = '  '.repeat(depth + 1);
-        if (Array.isArray(obj)) {
-            // Keep arrays on single line for compactness
-            return JSON.stringify(obj);
-        }
-        if (obj && typeof obj === 'object') {
-            const entries = Object.entries(obj);
-            if (entries.length === 0)
-                return '{}';
-            const formatted = entries
-                .map(([key, value]) => `${nextIndent}"${key}": ${this.formatCompactJson(value, depth + 1)}`)
-                .join(',\n');
-            return `{\n${formatted}\n${indent}}`;
-        }
-        return JSON.stringify(obj);
+    flush() {
+        this.target().flush?.();
+    }
+    log(level, kind, message, context) {
+        const fields = context && Object.keys(context).length > 0 ? context : undefined;
+        this.emit({
+            level,
+            kind,
+            message,
+            ...(fields && { fields }),
+            ...(fields && this.sensitive && { sensitive: Object.keys(fields) }),
+        });
     }
     debug(message, context) {
-        if (this.shouldLog('debug')) {
-            const formatted = this.formatMessage(message, context);
-            process.stderr.write(`${this.theme.debug(formatted)}\n`);
-        }
+        this.log('debug', 'diagnostic', message, context);
     }
     debugMultiline(message, context) {
-        if (this.shouldLog('debug')) {
-            const formatted = this.formatMessage(message, context, true);
-            process.stderr.write(`${this.theme.debug(formatted)}\n`);
-        }
+        this.log('debug', 'diagnostic', message, context);
     }
     info(message, context) {
-        if (this.shouldLog('info')) {
-            const formatted = this.formatMessage(message, context);
-            process.stderr.write(`${this.theme.info(formatted)}\n`);
-        }
+        this.log('info', 'notice', message, context);
     }
     verboseInfo(message, context) {
-        if (!this.quiet && this.verbose) {
-            const formatted = this.formatMessage(message, context);
-            process.stderr.write(`${this.theme.info(formatted)}\n`);
-        }
+        this.log('debug', 'diagnostic', message, context);
     }
     warn(message, context) {
-        if (this.shouldLog('warn')) {
-            const formatted = this.formatMessage(message, context);
-            process.stderr.write(`${this.theme.warn(formatted)}\n`);
-        }
+        this.log('warn', 'notice', message, context);
     }
     error(message, context) {
-        const formatted = this.formatMessage(message, context);
-        process.stderr.write(`${this.theme.error(formatted)}\n`);
+        this.log('error', 'error', message, context);
     }
 }

package/dist/aggregate.d.ts

@@ -0,0 +1,42 @@
+import type { OutputEvent } from './types.js';
+/** Counts of each value a field took, and how many values went untracked. */
+export type ValueCounts = Record<string, number>;
+export interface AggregatorOptions {
+    /** Events shown per group before the rest are counted. Default 3. */
+    examples?: number;
+    /** Most often a group's roll-up prints, in milliseconds. Default 5s. */
+    windowMs?: number;
+    /** The same for warnings and errors, which shouldn't wait as long. Default 1s. */
+    urgentWindowMs?: number;
+}
+/**
+ * The group an event belongs to: its `key`, else its scope and message with
+ * the numbers taken out. Personal values belong in fields, so a message is
+ * already close to a template: `Generated 1 actions` and `Generated 3
+ * actions` group together.
+ */
+export declare function groupOf(event: OutputEvent): string | undefined;
+/**
+ * Keeps repeated events from flooding: each group shows its first few
+ * events, then counts the rest and reports them as a roll-up at most once a
+ * window, with how often each field value came up. 10,000 failed records
+ * become three examples and a line every second or so, not 10,000 lines.
+ */
+export declare class Aggregator {
+    private groups;
+    private readonly examples;
+    private readonly windowMs;
+    private readonly urgentWindowMs;
+    constructor(options?: AggregatorOptions | number);
+    /** What to print now for this event: roll-ups that came due, then the event if it shows. */
+    admit(event: OutputEvent): OutputEvent[];
+    /** Every pending roll-up, now: for a summary, a flush, or exit. */
+    drain(): OutputEvent[];
+    /** Whether any group is holding events back. */
+    get pending(): boolean;
+    /** Roll-ups whose window has passed by `now`. */
+    due(now: number): OutputEvent[];
+    private count;
+    private rollup;
+}
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/aggregate.js

@@ -0,0 +1,149 @@
+/** Distinct values tracked per field in a group, so memory stays bounded. */
+const MAX_VALUES = 50;
+const MAX_VALUE_LENGTH = 60;
+/** Kinds that repeat per record, and so group without being asked. */
+const GROUPABLE = new Set(['notice', 'diagnostic', 'error']);
+/**
+ * The group an event belongs to: its `key`, else its scope and message with
+ * the numbers taken out. Personal values belong in fields, so a message is
+ * already close to a template: `Generated 1 actions` and `Generated 3
+ * actions` group together.
+ */
+export function groupOf(event) {
+    if (event.key)
+        return event.key;
+    if (!GROUPABLE.has(event.kind))
+        return undefined;
+    return `${event.scope}\u0000${event.message.replaceAll(/\d+/g, '#')}`;
+}
+const text = (value) => {
+    const s = typeof value === 'string' ? value : JSON.stringify(value);
+    return s.length > MAX_VALUE_LENGTH ? `${s.slice(0, MAX_VALUE_LENGTH - 1)}…` : s;
+};
+const seconds = (ms) => `${Math.max(1, Math.round(ms / 1000))}s`;
+/**
+ * Keeps repeated events from flooding: each group shows its first few
+ * events, then counts the rest and reports them as a roll-up at most once a
+ * window, with how often each field value came up. 10,000 failed records
+ * become three examples and a line every second or so, not 10,000 lines.
+ */
+export class Aggregator {
+    groups = new Map();
+    examples;
+    windowMs;
+    urgentWindowMs;
+    constructor(options = {}) {
+        const o = typeof options === 'number' ? { examples: options } : options;
+        this.examples = o.examples ?? 3;
+        this.windowMs = o.windowMs ?? 5000;
+        this.urgentWindowMs = o.urgentWindowMs ?? 1000;
+    }
+    /** What to print now for this event: roll-ups that came due, then the event if it shows. */
+    admit(event) {
+        const now = event.time.getTime();
+        const out = this.due(now);
+        const key = groupOf(event);
+        if (!key)
+            return [...out, event];
+        let group = this.groups.get(key);
+        if (!group) {
+            group = {
+                key,
+                shown: 0,
+                pending: 0,
+                last: event,
+                since: now,
+                values: new Map(),
+                personal: new Set(),
+            };
+            this.groups.set(key, group);
+        }
+        group.last = event;
+        if (group.shown < this.examples) {
+            group.shown++;
+            group.since = now;
+            out.push(event);
+            return out;
+        }
+        group.pending++;
+        this.count(group, event);
+        return out;
+    }
+    /** Every pending roll-up, now: for a summary, a flush, or exit. */
+    drain() {
+        const out = [];
+        for (const group of this.groups.values()) {
+            if (group.pending > 0)
+                out.push(this.rollup(group, group.last.time.getTime(), true));
+        }
+        this.groups.clear();
+        return out;
+    }
+    /** Whether any group is holding events back. */
+    get pending() {
+        for (const group of this.groups.values())
+            if (group.pending > 0)
+                return true;
+        return false;
+    }
+    /** Roll-ups whose window has passed by `now`. */
+    due(now) {
+        const out = [];
+        for (const group of this.groups.values()) {
+            const urgent = group.last.level === 'warn' || group.last.level === 'error';
+            const window = urgent ? this.urgentWindowMs : this.windowMs;
+            if (group.pending > 0 && now - group.since >= window)
+                out.push(this.rollup(group, now));
+        }
+        return out;
+    }
+    count(group, event) {
+        for (const [field, value] of Object.entries(event.fields ?? {})) {
+            if (value === undefined || value === null || typeof value === 'object')
+                continue;
+            if (event.sensitive?.includes(field))
+                group.personal.add(field);
+            const counts = group.values.get(field) ?? new Map();
+            const label = text(value);
+            if (counts.has(label) || counts.size < MAX_VALUES) {
+                counts.set(label, (counts.get(label) ?? 0) + 1);
+            }
+            else {
+                counts.set('…', (counts.get('…') ?? 0) + 1);
+            }
+            group.values.set(field, counts);
+        }
+    }
+    rollup(group, now, final = false) {
+        const { last, pending } = group;
+        const values = {};
+        const personal = {};
+        for (const [field, counts] of group.values) {
+            (group.personal.has(field) ? personal : values)[field] = Object.fromEntries(counts);
+        }
+        const count = pending.toLocaleString('en-US');
+        const event = {
+            time: new Date(now),
+            level: last.level,
+            kind: last.kind,
+            scope: last.scope,
+            ...(last.run && { run: last.run }),
+            message: final
+                ? `…and ${count} more like this`
+                : `…${count} more like this in ${seconds(now - group.since)}`,
+            fields: {
+                suppressed: pending,
+                windowMs: now - group.since,
+                ...(Object.keys(values).length > 0 && { values }),
+                ...(Object.keys(personal).length > 0 && { personal }),
+            },
+            ...(Object.keys(personal).length > 0 && { sensitive: ['personal'] }),
+            key: group.key,
+        };
+        group.pending = 0;
+        group.since = now;
+        group.values.clear();
+        group.personal.clear();
+        return event;
+    }
+}

package/dist/console.d.ts

@@ -0,0 +1,8 @@
+import type { Logger } from './Logger.js';
+/**
+ * Route `console.*` through `logger` as diagnostics until the returned
+ * function restores it: code that writes to the console (a third-party
+ * plugin, a dependency) still reaches the host's sink, never stdout.
+ */
+export declare function captureConsole(logger: Logger): () => void;
+//# sourceMappingURL=console.d.ts.map

package/dist/console.js

@@ -0,0 +1,27 @@
+import { format } from 'node:util';
+const METHODS = {
+    debug: 'debug',
+    trace: 'debug',
+    log: 'info',
+    info: 'info',
+    warn: 'warn',
+    error: 'error',
+};
+/**
+ * Route `console.*` through `logger` as diagnostics until the returned
+ * function restores it: code that writes to the console (a third-party
+ * plugin, a dependency) still reaches the host's sink, never stdout.
+ */
+export function captureConsole(logger) {
+    const original = new Map();
+    for (const [method, level] of Object.entries(METHODS)) {
+        original.set(method, console[method]);
+        console[method] = (...args) => {
+            logger.emit({ level, kind: 'diagnostic', message: format(...args) });
+        };
+    }
+    return () => {
+        for (const [method, fn] of original)
+            console[method] = fn;
+    };
+}

package/dist/defaultSink.d.ts

@@ -0,0 +1,11 @@
+import type { Sink } from './types.js';
+/**
+ * Where loggers without a sink of their own send events, process-wide: a host
+ * sets this once so module-level loggers (in shared packages, or created
+ * before a run hands its sink over) follow its output instead of stderr.
+ * Returns the sink it replaced, so a caller can restore it.
+ */
+export declare function setDefaultSink(sink: Sink | undefined): Sink | undefined;
+/** The process-wide sink, if a host set one. */
+export declare const defaultSink: () => Sink | undefined;
+//# sourceMappingURL=defaultSink.d.ts.map

package/dist/defaultSink.js

@@ -0,0 +1,14 @@
+let current;
+/**
+ * Where loggers without a sink of their own send events, process-wide: a host
+ * sets this once so module-level loggers (in shared packages, or created
+ * before a run hands its sink over) follow its output instead of stderr.
+ * Returns the sink it replaced, so a caller can restore it.
+ */
+export function setDefaultSink(sink) {
+    const previous = current;
+    current = sink;
+    return previous;
+}
+/** The process-wide sink, if a host set one. */
+export const defaultSink = () => current;

package/dist/errors.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Exit codes a supervisor can act on without reading messages: whether to
+ * report a bug, fix the invocation, get a person to re-authorize or fix
+ * access, or retry later.
+ */
+export declare const EXIT_CODES: {
+    readonly internal: 1;
+    readonly usage: 2;
+    readonly auth: 3;
+    readonly input: 4;
+    readonly transient: 5;
+};
+export interface ExtractorErrorOptions {
+    /** A stable name for what went wrong: `auth-required`, `input-not-found`. */
+    code?: string;
+    exitCode?: number;
+    /** The next move for a person: `run chronicle auth login arena`. */
+    hint?: string;
+    /** Facts about the failure. Personal unless listed in `safe`. */
+    fields?: Record<string, unknown>;
+    cause?: unknown;
+}
+/**
+ * A failure a plugin can name. The runner reports it as an `error` event with
+ * its code, exit code, and hint, and the CLI exits with its code, so a person
+ * gets a next step and a supervisor can decide what to do without matching
+ * text. Put personal values (paths, names) in `fields`, not the message.
+ */
+export declare class ExtractorError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    readonly hint?: string;
+    readonly fields?: Record<string, unknown>;
+    constructor(message: string, options?: ExtractorErrorOptions);
+}
+/** No credentials, or they expired or were revoked: a person has to sign in. */
+export declare class AuthRequired extends ExtractorError {
+    constructor(message: string, options?: Omit<ExtractorErrorOptions, 'code' | 'exitCode'> & {
+        source?: string;
+    });
+}
+/** The operating system refused access: permissions, or macOS privacy controls. */
+export declare class PermissionDenied extends ExtractorError {
+    constructor(message: string, options?: Omit<ExtractorErrorOptions, 'code' | 'exitCode'> & {
+        path?: string;
+    });
+}
+/** The input the source reads from isn't there, or isn't what it expects. */
+export declare class InputNotFound extends ExtractorError {
+    constructor(message: string, options?: Omit<ExtractorErrorOptions, 'code' | 'exitCode'> & {
+        path?: string;
+    });
+}
+/** The source throttled us; `retryAfter` says how long to wait, when it said. */
+export declare class RateLimited extends ExtractorError {
+    readonly retryAfter?: number;
+    constructor(message: string, options?: Omit<ExtractorErrorOptions, 'code' | 'exitCode'> & {
+        retryAfter?: number;
+    });
+}
+/**
+ * The code, exit code, and hint of any thrown value, typed or not. Duck-typed,
+ * so an error from a plugin built against another copy of this package still
+ * reads as what it is.
+ */
+export declare function describeError(error: unknown): {
+    message: string;
+    code: string;
+    exitCode: number;
+    hint?: string;
+    fields?: Record<string, unknown>;
+    stack?: string;
+};
+/** Note that an error was already reported as an event, so a host doesn't print it twice. */
+export declare function markReported(error: unknown): void;
+/** Whether an error was already reported as an event. */
+export declare const isReported: (error: unknown) => boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,108 @@
+/**
+ * Exit codes a supervisor can act on without reading messages: whether to
+ * report a bug, fix the invocation, get a person to re-authorize or fix
+ * access, or retry later.
+ */
+export const EXIT_CODES = {
+    internal: 1,
+    usage: 2,
+    auth: 3,
+    input: 4,
+    transient: 5,
+};
+/**
+ * A failure a plugin can name. The runner reports it as an `error` event with
+ * its code, exit code, and hint, and the CLI exits with its code, so a person
+ * gets a next step and a supervisor can decide what to do without matching
+ * text. Put personal values (paths, names) in `fields`, not the message.
+ */
+export class ExtractorError extends Error {
+    code;
+    exitCode;
+    hint;
+    fields;
+    constructor(message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = new.target.name;
+        this.code = options.code ?? 'extractor-error';
+        this.exitCode = options.exitCode ?? EXIT_CODES.internal;
+        this.hint = options.hint;
+        this.fields = options.fields;
+    }
+}
+/** No credentials, or they expired or were revoked: a person has to sign in. */
+export class AuthRequired extends ExtractorError {
+    constructor(message, options = {}) {
+        const { source, ...rest } = options;
+        super(message, {
+            code: 'auth-required',
+            exitCode: EXIT_CODES.auth,
+            hint: source ? `Run \`chronicle auth login ${source}\` to sign in.` : undefined,
+            ...rest,
+        });
+    }
+}
+/** The operating system refused access: permissions, or macOS privacy controls. */
+export class PermissionDenied extends ExtractorError {
+    constructor(message, options = {}) {
+        const { path, ...rest } = options;
+        super(message, {
+            code: 'permission-denied',
+            exitCode: EXIT_CODES.input,
+            ...rest,
+            fields: { ...(path && { path }), ...rest.fields },
+        });
+    }
+}
+/** The input the source reads from isn't there, or isn't what it expects. */
+export class InputNotFound extends ExtractorError {
+    constructor(message, options = {}) {
+        const { path, ...rest } = options;
+        super(message, {
+            code: 'input-not-found',
+            exitCode: EXIT_CODES.input,
+            ...rest,
+            fields: { ...(path && { path }), ...rest.fields },
+        });
+    }
+}
+/** The source throttled us; `retryAfter` says how long to wait, when it said. */
+export class RateLimited extends ExtractorError {
+    retryAfter;
+    constructor(message, options = {}) {
+        const { retryAfter, ...rest } = options;
+        super(message, {
+            code: 'rate-limited',
+            exitCode: EXIT_CODES.transient,
+            hint: retryAfter === undefined ? 'Try again later.' : `Try again in ${retryAfter}s.`,
+            ...rest,
+            fields: { ...(retryAfter !== undefined && { retryAfter }), ...rest.fields },
+        });
+        this.retryAfter = retryAfter;
+    }
+}
+/**
+ * The code, exit code, and hint of any thrown value, typed or not. Duck-typed,
+ * so an error from a plugin built against another copy of this package still
+ * reads as what it is.
+ */
+export function describeError(error) {
+    const e = error;
+    const typed = typeof e?.code === 'string' && typeof e?.exitCode === 'number';
+    return {
+        message: error instanceof Error ? error.message : String(error),
+        code: typed ? e.code : 'internal',
+        exitCode: typed ? e.exitCode : EXIT_CODES.internal,
+        ...(typed && e.hint && { hint: e.hint }),
+        ...(typed && e.fields && { fields: e.fields }),
+        ...(e?.stack && { stack: e.stack }),
+    };
+}
+const REPORTED = Symbol.for('chronicle.error.reported');
+/** Note that an error was already reported as an event, so a host doesn't print it twice. */
+export function markReported(error) {
+    if (typeof error === 'object' && error !== null)
+        error[REPORTED] = true;
+}
+/** Whether an error was already reported as an event. */
+export const isReported = (error) => typeof error === 'object' && error !== null && error[REPORTED] === true;

package/dist/index.d.ts

@@ -1,6 +1,11 @@
 export { Logger } from './Logger.js';
-export { defaultTheme } from './DefaultTheme.js';
-export type { LoggerTheme, LoggerOptions, LogLevel, LoggerContext } from './types.js';
+export { AuthRequired, EXIT_CODES, ExtractorError, InputNotFound, PermissionDenied, RateLimited, describeError, isReported, markReported, type ExtractorErrorOptions, } from './errors.js';
+export { Aggregator, groupOf, type AggregatorOptions, type ValueCounts } from './aggregate.js';
+export { captureConsole } from './console.js';
+export { defaultSink, setDefaultSink } from './defaultSink.js';
+export { allows, thresholdFor } from './levels.js';
+export { JsonSink, REDACTED, TextSink, formatFields, formatPlain, timeOfDay, toJson, type JsonSinkOptions, type TextSinkOptions, } from './sinks.js';
+export type { EventKind, LoggerContext, LoggerOptions, LogLevel, OutputEvent, ProgressFields, RunContext, SummaryFields, Sink, } from './types.js';
 import { Logger } from './Logger.js';
 import { LoggerOptions } from './types.js';
 /**

package/dist/index.js

@@ -1,5 +1,10 @@
 export { Logger } from './Logger.js';
-export { defaultTheme } from './DefaultTheme.js';
+export { AuthRequired, EXIT_CODES, ExtractorError, InputNotFound, PermissionDenied, RateLimited, describeError, isReported, markReported, } from './errors.js';
+export { Aggregator, groupOf } from './aggregate.js';
+export { captureConsole } from './console.js';
+export { defaultSink, setDefaultSink } from './defaultSink.js';
+export { allows, thresholdFor } from './levels.js';
+export { JsonSink, REDACTED, TextSink, formatFields, formatPlain, timeOfDay, toJson, } from './sinks.js';
 import { Logger } from './Logger.js';
 /**
  * Factory function to create a logger instance

package/dist/levels.d.ts

@@ -0,0 +1,10 @@
+import type { LogLevel } from './types.js';
+/** Whether a sink set to `threshold` shows an event at `level`. */
+export declare const allows: (threshold: LogLevel, level: LogLevel) => boolean;
+/** The threshold the common flags ask for: `--quiet` shows errors, `--verbose` everything. */
+export declare function thresholdFor({ quiet, verbose, level, }: {
+    quiet?: boolean;
+    verbose?: boolean;
+    level?: LogLevel;
+}): LogLevel;
+//# sourceMappingURL=levels.d.ts.map

package/dist/levels.js

@@ -0,0 +1,11 @@
+const ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
+/** Whether a sink set to `threshold` shows an event at `level`. */
+export const allows = (threshold, level) => ORDER[level] >= ORDER[threshold];
+/** The threshold the common flags ask for: `--quiet` shows errors, `--verbose` everything. */
+export function thresholdFor({ quiet, verbose, level, }) {
+    if (quiet)
+        return 'error';
+    if (verbose)
+        return 'debug';
+    return level ?? 'info';
+}

package/dist/sinks.d.ts

@@ -0,0 +1,66 @@
+import { type AggregatorOptions } from './aggregate.js';
+import type { LogLevel, OutputEvent, Sink } from './types.js';
+/** `HH:MM:SS` in local time. */
+export declare const timeOfDay: (date: Date) => string;
+/** `key=value` pairs, values compact: strings bare, the rest as JSON. */
+export declare function formatFields(fields: Record<string, unknown> | undefined): string;
+/** The default line for a host that brings no formatter: time, level, scope, message, fields. */
+export declare function formatPlain(event: OutputEvent): string;
+export interface TextSinkOptions {
+    /** The quietest level shown. Default `info`. */
+    level?: LogLevel;
+    write?: (text: string) => void;
+    /** An event as text, or undefined to say nothing. Default {@link formatPlain}. */
+    format?: (event: OutputEvent) => string | undefined;
+    /** How repeated events group: examples shown, then roll-ups per window. */
+    aggregate?: AggregatorOptions;
+}
+/**
+ * Events as lines of text for a person. Progress is left to sinks that can
+ * draw it; keyed events aggregate, and the counts print before the summary.
+ */
+export declare class TextSink implements Sink {
+    readonly level: LogLevel;
+    protected readonly write: (text: string) => void;
+    private readonly format;
+    private readonly aggregator;
+    private readonly rollups;
+    /** Hints from a run, printed under its summary rather than mid-run. */
+    private held;
+    private summarized;
+    constructor(options?: TextSinkOptions);
+    emit(event: OutputEvent): void;
+    flush(): void;
+    /** Report what the groups held back. */
+    protected drain(): void;
+    /** Print held hints: a run's, or all of them. */
+    private release;
+    protected print(event: OutputEvent): void;
+}
+export declare const REDACTED = "[redacted]";
+/** An event as one JSON object, its personal fields redacted. */
+export declare function toJson(event: OutputEvent): Record<string, unknown>;
+export interface JsonSinkOptions {
+    level?: LogLevel;
+    write?: (text: string) => void;
+    /** At most one progress event per run in this many milliseconds. Default 10s. */
+    heartbeatMs?: number;
+    aggregate?: AggregatorOptions;
+}
+/**
+ * Events as JSON lines for a daemon or supervisor. Progress becomes a
+ * heartbeat, hints stay data, and personal fields are redacted.
+ */
+export declare class JsonSink implements Sink {
+    readonly level: LogLevel;
+    private readonly write;
+    private readonly heartbeatMs;
+    private readonly aggregator;
+    private readonly rollups;
+    private lastBeat;
+    constructor(options?: JsonSinkOptions);
+    emit(event: OutputEvent): void;
+    flush(): void;
+    private print;
+}
+//# sourceMappingURL=sinks.d.ts.map

package/dist/sinks.js

@@ -0,0 +1,202 @@
+import { Aggregator } from './aggregate.js';
+import { allows } from './levels.js';
+/** Resolved at each write, so a live view that wraps stderr still sees it. */
+const stderr = (text) => {
+    process.stderr.write(text);
+};
+const pad2 = (n) => String(n).padStart(2, '0');
+/** `HH:MM:SS` in local time. */
+export const timeOfDay = (date) => `${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}`;
+/** `key=value` pairs, values compact: strings bare, the rest as JSON. */
+export function formatFields(fields) {
+    if (!fields)
+        return '';
+    return Object.entries(fields)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => `${key}=${typeof value === 'string' ? value : JSON.stringify(value)}`)
+        .join(' ');
+}
+/** The default line for a host that brings no formatter: time, level, scope, message, fields. */
+export function formatPlain(event) {
+    const level = event.level === 'info' ? '' : `${event.level} `;
+    const fields = formatFields(event.fields);
+    const hint = event.hint ? ` · ${event.hint.action}` : '';
+    const guide = event.guide
+        ? [
+            ...(event.guide.text ?? []),
+            ...(event.guide.steps ?? []).map((step, i) => `${i + 1}. ${step}`),
+        ].map(part => `\n  ${part}`)
+        : [];
+    return `${timeOfDay(event.time)} ${level}${event.scope}: ${event.message}${hint}${fields ? ` ${fields}` : ''}${guide.join('')}`;
+}
+/** How often a sink checks for roll-ups that came due while nothing else arrived. */
+const TICK_MS = 1000;
+/**
+ * Prints roll-ups on time even when a group goes quiet: while events are held
+ * back, a timer checks once a second. It never keeps the process alive.
+ */
+class RollupTimer {
+    aggregator;
+    print;
+    timer;
+    constructor(aggregator, print) {
+        this.aggregator = aggregator;
+        this.print = print;
+    }
+    arm() {
+        if (this.timer || !this.aggregator.pending)
+            return;
+        this.timer = setInterval(() => {
+            for (const event of this.aggregator.due(Date.now()))
+                this.print(event);
+            if (!this.aggregator.pending)
+                this.stop();
+        }, TICK_MS);
+        this.timer.unref();
+    }
+    stop() {
+        clearInterval(this.timer);
+        this.timer = undefined;
+    }
+}
+/**
+ * Events as lines of text for a person. Progress is left to sinks that can
+ * draw it; keyed events aggregate, and the counts print before the summary.
+ */
+export class TextSink {
+    level;
+    write;
+    format;
+    aggregator;
+    rollups;
+    /** Hints from a run, printed under its summary rather than mid-run. */
+    held = [];
+    summarized = new Set();
+    constructor(options = {}) {
+        this.level = options.level ?? 'info';
+        this.write = options.write ?? stderr;
+        this.format = options.format ?? formatPlain;
+        this.aggregator = new Aggregator(options.aggregate);
+        this.rollups = new RollupTimer(this.aggregator, event => this.print(event));
+    }
+    emit(event) {
+        if (!allows(this.level, event.level) || event.kind === 'progress')
+            return;
+        // Hints go under the summary: a run's hints wait for it (or for a flush,
+        // if the run fails). Hints outside a run print as they come.
+        if (event.kind === 'hint' && event.run && !this.summarized.has(event.run.id)) {
+            this.held.push(event);
+            return;
+        }
+        if (event.kind === 'summary')
+            this.drain();
+        for (const shown of this.aggregator.admit(event))
+            this.print(shown);
+        if (event.kind === 'summary') {
+            if (event.run)
+                this.summarized.add(event.run.id);
+            this.release(event.run?.id);
+        }
+        this.rollups.arm();
+    }
+    flush() {
+        this.drain();
+        this.release();
+    }
+    /** Report what the groups held back. */
+    drain() {
+        this.rollups.stop();
+        for (const event of this.aggregator.drain()) {
+            if (allows(this.level, event.level))
+                this.print(event);
+        }
+    }
+    /** Print held hints: a run's, or all of them. */
+    release(run) {
+        const now = this.held.filter(event => run === undefined || event.run?.id === run);
+        this.held = this.held.filter(event => !now.includes(event));
+        for (const event of now)
+            this.print(event);
+    }
+    print(event) {
+        const text = this.format(event);
+        if (text !== undefined)
+            this.write(`${text}\n`);
+    }
+}
+export const REDACTED = '[redacted]';
+/** An event as one JSON object, its personal fields redacted. */
+export function toJson(event) {
+    let { fields } = event;
+    if (fields && event.sensitive?.length) {
+        fields = Object.fromEntries(Object.entries(fields).map(([key, value]) => [
+            key,
+            event.sensitive.includes(key) ? REDACTED : value,
+        ]));
+    }
+    return {
+        time: event.time.toISOString(),
+        level: event.level,
+        kind: event.kind,
+        scope: event.scope,
+        ...(event.run && { run: event.run }),
+        message: event.message,
+        ...(fields && { fields }),
+        ...(event.error && { error: event.error }),
+        ...(event.hint && { hint: event.hint }),
+        ...(event.guide && { guide: event.guide }),
+        ...(event.sensitive?.length && { sensitive: event.sensitive }),
+        ...(event.key && { key: event.key }),
+    };
+}
+/**
+ * Events as JSON lines for a daemon or supervisor. Progress becomes a
+ * heartbeat, hints stay data, and personal fields are redacted.
+ */
+export class JsonSink {
+    level;
+    write;
+    heartbeatMs;
+    aggregator;
+    rollups;
+    lastBeat = new Map();
+    constructor(options = {}) {
+        this.level = options.level ?? 'info';
+        this.write = options.write ?? stderr;
+        this.heartbeatMs = options.heartbeatMs ?? 10_000;
+        this.aggregator = new Aggregator(options.aggregate);
+        this.rollups = new RollupTimer(this.aggregator, event => this.print(event));
+    }
+    emit(event) {
+        if (event.kind === 'progress') {
+            // Progress is debug-level chatter, but its heartbeat is how a supervisor
+            // knows a run is alive: shown at the default threshold, not under --quiet.
+            if (!allows(this.level, 'info'))
+                return;
+            const run = event.run?.id ?? '';
+            const last = this.lastBeat.get(run);
+            if (last !== undefined && event.time.getTime() - last < this.heartbeatMs)
+                return;
+            this.lastBeat.set(run, event.time.getTime());
+            this.print(event);
+            return;
+        }
+        if (!allows(this.level, event.level))
+            return;
+        if (event.kind === 'summary')
+            this.flush();
+        for (const shown of this.aggregator.admit(event))
+            this.print(shown);
+        this.rollups.arm();
+    }
+    flush() {
+        this.rollups.stop();
+        for (const event of this.aggregator.drain()) {
+            if (allows(this.level, event.level))
+                this.print(event);
+        }
+    }
+    print(event) {
+        this.write(`${JSON.stringify(toJson(event))}\n`);
+    }
+}

package/dist/types.d.ts

@@ -1,18 +1,108 @@
-export interface LoggerTheme {
-    info: (message: string) => string;
-    warn: (message: string) => string;
-    error: (message: string) => string;
-    debug: (message: string) => string;
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** What an event is, apart from how loud it is. */
+export type EventKind = 'progress' | 'notice' | 'hint' | 'summary' | 'error' | 'diagnostic' | 'guide';
+/** The run an event belongs to; a daemon groups events by it, like a trace id. */
+export interface RunContext {
+    id: string;
+    source: string;
+    strategy: string;
+}
+/**
+ * One thing worth telling a person or a supervisor. Every line on stderr is
+ * the rendering of one of these; a sink decides how it looks.
+ */
+export interface OutputEvent {
+    time: Date;
+    level: LogLevel;
+    kind: EventKind;
+    /** Who spoke: `runner`, `shell.history`, `cli`. */
+    scope: string;
+    run?: RunContext;
+    /** Plain text, no styling, that reads on its own. */
+    message: string;
+    /** The source of truth: a JSON consumer reads `records: 1240`, not text. */
+    fields?: Record<string, unknown>;
+    error?: {
+        code?: string;
+        cause?: string;
+        stack?: string;
+        exitCode?: number;
+    };
+    /** A next move for a person. */
+    hint?: {
+        action: string;
+        when?: string;
+    };
+    /**
+     * A `guide` event's body: a section of a walkthrough a person follows,
+     * titled by `message`. `text` is a few plain sentences; `steps` are what to
+     * do, in order.
+     */
+    guide?: {
+        text?: string[];
+        steps?: string[];
+    };
+    /** Names of `fields` that carry personal data. */
+    sensitive?: string[];
+    /** Events sharing a key aggregate: the first few print, the rest are counted. */
+    key?: string;
+}
+/** Where events go. Level filtering, aggregation, and redaction happen here. */
+export interface Sink {
+    emit(event: OutputEvent): void;
+    /** Write anything held back (aggregated counts) and take down live views. */
+    flush?(): void;
 }
 export interface LoggerOptions {
+    /** `[ServiceName]` or a bare name; becomes the scope. */
     prefix?: string;
+    scope?: string;
     level?: LogLevel;
-    theme?: LoggerTheme;
     quiet?: boolean;
     verbose?: boolean;
+    /** The host's sink. Without one, the logger writes plain lines to stderr. */
+    sink?: Sink;
+    run?: RunContext;
+    /** Mark every field personal, as for plugin loggers. */
+    sensitive?: boolean;
 }
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 export interface LoggerContext {
     [key: string]: any;
 }
+/** What a `progress` event carries in its fields: a run as it goes. */
+export type ProgressFields = {
+    /** `shell · history`: what the run reads. */
+    title: string;
+    /**
+     * `reading` while the source is read in ahead of the run (`processed`
+     * counts records read), `loading` once records go through to the output,
+     * `writing` while the output flushes at the end.
+     */
+    phase?: 'reading' | 'loading' | 'writing';
+    processed: number;
+    /** Records expected, when the source knows; 0 when it doesn't. */
+    total: number;
+    /** Records by type so far. */
+    counts: Record<string, number>;
+    /** The record in hand, as a one-line label. Personal. */
+    current?: string;
+    /** Where a `writing` run's output goes. */
+    target?: string;
+    elapsedMs: number;
+};
+/** What a `summary` event carries in its fields: a finished run's totals. */
+export type SummaryFields = {
+    /** `shell · history`: what the run read. */
+    title: string;
+    /** Records read, by type, in the order first seen. */
+    counts: Record<string, number>;
+    records: number;
+    /** What reached the output, when that differs from records read less skipped: a fan-out, or failures. */
+    written?: number;
+    skipped?: number;
+    failed?: number;
+    durationMs: number;
+    /** Where the records went, when that's a file. */
+    output?: string;
+};
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronicle.app/logging",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -30,9 +30,6 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "dependencies": {
-    "chalk": "^4.1.2"
-  },
   "engines": {
     "node": ">=22.13.0"
   },
@@ -43,7 +40,7 @@
     }
   },
   "devDependencies": {
-    "@chronicle.app/tsconfig": "0.3.0",
+    "@chronicle.app/tsconfig": "0.5.0",
     "@types/node": "^22.10.1",
     "typescript": "^5.7.2"
   }

package/dist/DefaultTheme.d.ts

@@ -1,3 +0,0 @@
-import { LoggerTheme } from './types.js';
-export declare const defaultTheme: LoggerTheme;
-//# sourceMappingURL=DefaultTheme.d.ts.map

package/dist/DefaultTheme.js

@@ -1,8 +0,0 @@
-import chalk from 'chalk';
-// Enhanced theme with colored icons/timestamps only
-export const defaultTheme = {
-    debug: msg => `${chalk.gray('⚪')} ${msg}`,
-    info: msg => `${chalk.blue('ℹ')} ${msg}`,
-    warn: msg => `${chalk.yellow('⚠')} ${msg}`,
-    error: msg => `${chalk.red('✖')} ${msg}`,
-};