pi-harness-runtime 1.1.394 → 1.1.396

package/packages/logging/dist/shipper.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The shipper owns the delivery decision.
+ *
+ * Producers call `log()`. The shipper redacts, samples, buffers, and then
+ * delivers a batch through the configured transports in priority order:
+ *
+ *   R2 (durable archive) -> webhook (live) -> local spool (last resort)
+ *
+ * If every transport fails the batch is spooled to disk and retried on the
+ * next flush, so a temporary outage costs latency, not data.
+ */
+import { type LogBufferOptions } from "./buffer.js";
+import { type RedactionOptions } from "./redact.js";
+import { type SamplingPolicy } from "./sampler.js";
+import { LogSpool } from "./spool.js";
+import type { FlushStats, LogInput, LogLevel, LogTransport } from "./types.js";
+export interface LogShipperOptions {
+    /** Application name reported with every batch. */
+    app?: string;
+    /** Host name reported with every batch. */
+    host?: string;
+    /** Transports in priority order. */
+    transports?: LogTransport[];
+    /** Local spool used when every transport fails. */
+    spool?: LogSpool;
+    /** Buffer bounds. */
+    buffer?: LogBufferOptions;
+    /** Sampling policy. */
+    sampling?: Partial<SamplingPolicy>;
+    /** Redaction limits. */
+    redaction?: RedactionOptions;
+    /** Interval for the automatic flush timer. Default 15000 ms. */
+    flushIntervalMs?: number;
+    /** Clock injection (tests). */
+    now?: () => number;
+    /** Batch id factory (tests). */
+    createBatchId?: () => string;
+}
+export declare class LogShipper {
+    private readonly app;
+    private readonly host;
+    private readonly transports;
+    private readonly spool;
+    private readonly buffer;
+    private readonly sampler;
+    private readonly redaction;
+    private readonly flushIntervalMs;
+    private readonly now;
+    private readonly createBatchId;
+    private timer;
+    private flushing;
+    private stats;
+    constructor(options?: LogShipperOptions);
+    /** Record a log event. Never throws. */
+    log(input: LogInput): void;
+    /** Convenience wrappers around `log()`. */
+    debug(source: string, event: string, message?: string, fields?: Record<string, unknown>): void;
+    info(source: string, event: string, message?: string, fields?: Record<string, unknown>): void;
+    warn(source: string, event: string, message?: string, fields?: Record<string, unknown>): void;
+    error(source: string, event: string, message?: string, fields?: Record<string, unknown>, error?: unknown): void;
+    /** Deliver buffered records (and drain the spool). Never throws. */
+    flush(): Promise<void>;
+    /**
+     * Synchronous last resort used on process exit: whatever is still in
+     * memory is written to the local spool so it is not lost.
+     */
+    flushSync(): void;
+    /** Start the periodic flush timer. */
+    start(): void;
+    /** Stop the timer and flush once more. */
+    stop(): Promise<void>;
+    getStats(): FlushStats;
+    private buildRecord;
+    private buildBatch;
+    private doFlush;
+    /** Try every transport in order. Returns true when one accepted the batch. */
+    private deliver;
+    /** Re-send spooled files. Stops at the first failure. */
+    private drainSpool;
+}
+export type { LogLevel };
+//# sourceMappingURL=shipper.d.ts.map

package/packages/logging/dist/shipper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shipper.d.ts","sourceRoot":"","sources":["../src/shipper.ts"],"names":[],"mappings":"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"}

package/packages/logging/dist/shipper.js

@@ -0,0 +1,238 @@
+/**
+ * The shipper owns the delivery decision.
+ *
+ * Producers call `log()`. The shipper redacts, samples, buffers, and then
+ * delivers a batch through the configured transports in priority order:
+ *
+ *   R2 (durable archive) -> webhook (live) -> local spool (last resort)
+ *
+ * If every transport fails the batch is spooled to disk and retried on the
+ * next flush, so a temporary outage costs latency, not data.
+ */
+import { hostname } from "node:os";
+import { LogBuffer } from "./buffer.js";
+import { redactFields, redactText } from "./redact.js";
+import { LogSampler } from "./sampler.js";
+function defaultBatchId() {
+    const stamp = new Date().toISOString().replace(/[-:.]/g, "").slice(0, 15);
+    return `${stamp}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function toErrorInfo(error) {
+    if (error instanceof Error) {
+        const info = { name: error.name, message: error.message };
+        if (error.stack)
+            info.stack = error.stack;
+        return info;
+    }
+    return { name: "Error", message: String(error) };
+}
+export class LogShipper {
+    app;
+    host;
+    transports;
+    spool;
+    buffer;
+    sampler;
+    redaction;
+    flushIntervalMs;
+    now;
+    createBatchId;
+    timer;
+    flushing;
+    stats = {
+        shipped: 0,
+        spooled: 0,
+        dropped: 0,
+        sampled: 0,
+        errors: {},
+    };
+    constructor(options = {}) {
+        this.app = options.app ?? "pi-harness";
+        this.host = options.host ?? hostname();
+        this.transports = options.transports ?? [];
+        this.spool = options.spool;
+        this.buffer = new LogBuffer(options.buffer);
+        this.sampler = new LogSampler(options.sampling);
+        this.redaction = options.redaction ?? {};
+        this.flushIntervalMs = options.flushIntervalMs ?? 15_000;
+        this.now = options.now ?? (() => Date.now());
+        this.createBatchId = options.createBatchId ?? defaultBatchId;
+    }
+    /** Record a log event. Never throws. */
+    log(input) {
+        try {
+            const record = this.buildRecord(input);
+            if (!this.sampler.shouldLog(record, this.now())) {
+                this.stats.sampled++;
+                return;
+            }
+            this.buffer.push(record);
+            if (this.buffer.size >= this.buffer.batchSize) {
+                void this.flush();
+            }
+        }
+        catch {
+            // A logging failure must never break the caller.
+        }
+    }
+    /** Convenience wrappers around `log()`. */
+    debug(source, event, message, fields) {
+        this.log({ level: "debug", source, event, message, fields });
+    }
+    info(source, event, message, fields) {
+        this.log({ level: "info", source, event, message, fields });
+    }
+    warn(source, event, message, fields) {
+        this.log({ level: "warn", source, event, message, fields });
+    }
+    error(source, event, message, fields, error) {
+        this.log({ level: "error", source, event, message, fields, error });
+    }
+    /** Deliver buffered records (and drain the spool). Never throws. */
+    async flush() {
+        if (this.flushing)
+            return this.flushing;
+        this.flushing = this.doFlush().finally(() => {
+            this.flushing = undefined;
+        });
+        return this.flushing;
+    }
+    /**
+     * Synchronous last resort used on process exit: whatever is still in
+     * memory is written to the local spool so it is not lost.
+     */
+    flushSync() {
+        try {
+            const records = this.buffer.peekAll();
+            if (records.length === 0)
+                return;
+            this.buffer.clear();
+            if (!this.spool)
+                return;
+            this.spool.append(this.buildBatch(records));
+            this.stats.spooled += records.length;
+        }
+        catch {
+            // Nothing else we can do at exit time.
+        }
+    }
+    /** Start the periodic flush timer. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.flush();
+        }, this.flushIntervalMs);
+        // Never keep the process alive just for log delivery.
+        this.timer.unref?.();
+    }
+    /** Stop the timer and flush once more. */
+    async stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        await this.flush();
+    }
+    getStats() {
+        return {
+            ...this.stats,
+            dropped: this.stats.dropped + this.buffer.dropped,
+            errors: { ...this.stats.errors },
+        };
+    }
+    buildRecord(input) {
+        const record = {
+            ts: new Date(this.now()).toISOString(),
+            level: input.level,
+            source: input.source,
+            event: input.event,
+        };
+        if (input.message !== undefined) {
+            record.message = redactText(input.message, this.redaction.placeholder);
+        }
+        if (input.sessionId)
+            record.sessionId = input.sessionId;
+        if (typeof input.durationMs === "number")
+            record.durationMs = input.durationMs;
+        const fields = redactFields(input.fields, this.redaction);
+        if (fields && Object.keys(fields).length > 0)
+            record.fields = fields;
+        if (input.error !== undefined) {
+            const info = toErrorInfo(input.error);
+            record.error = {
+                name: info.name,
+                message: redactText(info.message, this.redaction.placeholder),
+                ...(info.stack ? { stack: redactText(info.stack, this.redaction.placeholder) } : {}),
+            };
+        }
+        return record;
+    }
+    buildBatch(records) {
+        return {
+            batchId: this.createBatchId(),
+            app: this.app,
+            host: this.host,
+            sentAt: new Date(this.now()).toISOString(),
+            records,
+        };
+    }
+    async doFlush() {
+        try {
+            await this.drainSpool();
+            const records = this.buffer.takeBatch();
+            if (records.length === 0)
+                return;
+            const batch = this.buildBatch(records);
+            const delivered = await this.deliver(batch);
+            if (delivered) {
+                this.stats.shipped += records.length;
+                return;
+            }
+            if (this.spool) {
+                this.spool.append(batch);
+                this.stats.spooled += records.length;
+            }
+            else {
+                this.stats.dropped += records.length;
+            }
+        }
+        catch {
+            // Never let a flush failure escape.
+        }
+    }
+    /** Try every transport in order. Returns true when one accepted the batch. */
+    async deliver(batch) {
+        for (const transport of this.transports) {
+            try {
+                await transport.send(batch);
+                return true;
+            }
+            catch (error) {
+                this.stats.errors[transport.name] =
+                    error instanceof Error ? error.message : String(error);
+            }
+        }
+        return false;
+    }
+    /** Re-send spooled files. Stops at the first failure. */
+    async drainSpool() {
+        if (!this.spool)
+            return;
+        const files = this.spool.list();
+        for (const file of files) {
+            const records = this.spool.read(file);
+            if (records.length === 0) {
+                this.spool.remove(file);
+                continue;
+            }
+            const batch = this.buildBatch(records);
+            const delivered = await this.deliver(batch);
+            if (!delivered)
+                return;
+            this.spool.remove(file);
+            this.stats.shipped += records.length;
+        }
+    }
+}
+//# sourceMappingURL=shipper.js.map

package/packages/logging/dist/shipper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shipper.js","sourceRoot":"","sources":["../src/shipper.ts"],"names":[],"mappings":"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"}

package/packages/logging/dist/singleton.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The process-wide logging singleton.
+ *
+ * The singleton lives in the package (not in the harness) so that every
+ * producer - the root extension and the harness modules - shares exactly one
+ * shipper, one buffer and one spool.
+ *
+ * Nothing here throws: a logging failure must never break the caller.
+ */
+import { type LogSinkConfig } from "./config.js";
+import { LogShipper } from "./shipper.js";
+import type { LogLevel } from "./types.js";
+export interface InitCentralLoggingOptions {
+    /** Environment used for the configuration. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Directory holding the credential key files. */
+    keysDir?: string;
+}
+/**
+ * Initialize the centralized logging pipeline.
+ *
+ * Calling it twice is safe: the second call returns the existing
+ * configuration without creating a second shipper.
+ */
+export declare function initCentralLogging(options?: InitCentralLoggingOptions): LogSinkConfig | null;
+/** The active shipper, or null when logging is not initialized. */
+export declare function getCentralShipper(): LogShipper | null;
+/** The resolved configuration, or null when logging was never initialized. */
+export declare function getCentralLogConfig(): LogSinkConfig | null;
+/** Emit one record. No-op when the pipeline is not initialized. */
+export declare function centralLog(level: LogLevel, source: string, event: string, message?: string, fields?: Record<string, unknown>, error?: unknown): void;
+export declare function centralDebug(source: string, event: string, message?: string, fields?: Record<string, unknown>): void;
+export declare function centralInfo(source: string, event: string, message?: string, fields?: Record<string, unknown>): void;
+export declare function centralWarn(source: string, event: string, message?: string, fields?: Record<string, unknown>): void;
+export declare function centralError(source: string, event: string, message?: string, fields?: Record<string, unknown>, error?: unknown): void;
+/** Flush and stop the pipeline. Safe to call when it was never started. */
+export declare function shutdownCentralLogging(): Promise<void>;
+//# sourceMappingURL=singleton.d.ts.map

package/packages/logging/dist/singleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton.d.ts","sourceRoot":"","sources":["../src/singleton.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,WAAW,yBAAyB;IACzC,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,GAAE,yBAA8B,GACrC,aAAa,GAAG,IAAI,CAiCtB;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,IAAI,UAAU,GAAG,IAAI,CAErD;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,IAAI,aAAa,GAAG,IAAI,CAE1D;AAED,mEAAmE;AACnE,wBAAgB,UAAU,CACzB,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,KAAK,CAAC,EAAE,OAAO,GACb,IAAI,CAMN;AAED,wBAAgB,YAAY,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,IAAI,CAEN;AAED,wBAAgB,WAAW,CAC1B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,IAAI,CAEN;AAED,wBAAgB,WAAW,CAC1B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,IAAI,CAEN;AAED,wBAAgB,YAAY,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,KAAK,CAAC,EAAE,OAAO,GACb,IAAI,CAEN;AAED,2EAA2E;AAC3E,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAS5D"}

package/packages/logging/dist/singleton.js

@@ -0,0 +1,95 @@
+/**
+ * The process-wide logging singleton.
+ *
+ * The singleton lives in the package (not in the harness) so that every
+ * producer - the root extension and the harness modules - shares exactly one
+ * shipper, one buffer and one spool.
+ *
+ * Nothing here throws: a logging failure must never break the caller.
+ */
+import { resolveLogSinkConfig } from "./config.js";
+import { LogShipper } from "./shipper.js";
+import { LogSpool } from "./spool.js";
+let shipper = null;
+let config = null;
+/**
+ * Initialize the centralized logging pipeline.
+ *
+ * Calling it twice is safe: the second call returns the existing
+ * configuration without creating a second shipper.
+ */
+export function initCentralLogging(options = {}) {
+    if (config)
+        return config;
+    try {
+        const resolved = resolveLogSinkConfig({
+            env: options.env ?? process.env,
+            keysDir: options.keysDir,
+        });
+        config = resolved;
+        if (!resolved.enabled)
+            return resolved;
+        const spool = resolved.spoolDir ? new LogSpool({ dir: resolved.spoolDir }) : undefined;
+        shipper = new LogShipper({
+            app: resolved.app,
+            transports: resolved.transports,
+            spool,
+            buffer: resolved.buffer,
+            sampling: resolved.sampling,
+            flushIntervalMs: resolved.flushIntervalMs,
+        });
+        shipper.start();
+        // The exit handler is synchronous on purpose: an async flush cannot
+        // run during `exit`, so the remaining records go to the local spool.
+        process.once("exit", () => {
+            shipper?.flushSync();
+        });
+        return resolved;
+    }
+    catch {
+        return null;
+    }
+}
+/** The active shipper, or null when logging is not initialized. */
+export function getCentralShipper() {
+    return shipper;
+}
+/** The resolved configuration, or null when logging was never initialized. */
+export function getCentralLogConfig() {
+    return config;
+}
+/** Emit one record. No-op when the pipeline is not initialized. */
+export function centralLog(level, source, event, message, fields, error) {
+    try {
+        shipper?.log({ level, source, event, message, fields, error });
+    }
+    catch {
+        // Never let logging break the caller.
+    }
+}
+export function centralDebug(source, event, message, fields) {
+    centralLog("debug", source, event, message, fields);
+}
+export function centralInfo(source, event, message, fields) {
+    centralLog("info", source, event, message, fields);
+}
+export function centralWarn(source, event, message, fields) {
+    centralLog("warn", source, event, message, fields);
+}
+export function centralError(source, event, message, fields, error) {
+    centralLog("error", source, event, message, fields, error);
+}
+/** Flush and stop the pipeline. Safe to call when it was never started. */
+export async function shutdownCentralLogging() {
+    if (!shipper)
+        return;
+    const current = shipper;
+    shipper = null;
+    try {
+        await current.stop();
+    }
+    catch {
+        // Nothing to do at shutdown time.
+    }
+}
+//# sourceMappingURL=singleton.js.map

package/packages/logging/dist/singleton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton.js","sourceRoot":"","sources":["../src/singleton.ts"],"names":[],"mappings":"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"}

package/packages/logging/dist/spool.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Local NDJSON spool - the last-resort destination for log batches.
+ *
+ * When every transport fails (no network, R2 down, webhook server down) the
+ * batch is written to disk instead of being lost. The spool is drained on
+ * the next successful flush, so a temporary outage does not cost data.
+ *
+ * Files are plain NDJSON, one record per line, so an operator can inspect
+ * them with `tail`, `jq` or `less` without any tooling.
+ */
+import type { LogBatch, LogRecord } from "./types.js";
+export interface LogSpoolOptions {
+    /** Directory that holds the spool files. */
+    dir: string;
+    /** Rotate a file when it would exceed this size. Default 5 MB. */
+    maxFileBytes?: number;
+    /** Maximum number of spool files kept. Default 20. */
+    maxFiles?: number;
+}
+export declare class LogSpool {
+    private readonly dir;
+    private readonly maxFileBytes;
+    private readonly maxFiles;
+    constructor(options: LogSpoolOptions);
+    /** Append a batch to the spool. Returns the file that was written. */
+    append(batch: LogBatch, now?: Date): string;
+    /** Spool files, oldest first. */
+    list(): string[];
+    /** Read the records of a spool file. */
+    read(file: string): LogRecord[];
+    /** Delete a spool file after it was shipped. */
+    remove(file: string): void;
+    private ensureDir;
+    private currentFile;
+    private shouldRotate;
+    private rotate;
+    private enforceRetention;
+}
+//# sourceMappingURL=spool.d.ts.map

package/packages/logging/dist/spool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spool.d.ts","sourceRoot":"","sources":["../src/spool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAaH,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC/B,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAKD,qBAAa,QAAQ;IACpB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,YAAY,OAAO,EAAE,eAAe,EAInC;IAED,sEAAsE;IACtE,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAYtD;IAED,iCAAiC;IACjC,IAAI,IAAI,MAAM,EAAE,CAUf;IAED,wCAAwC;IACxC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAc9B;IAED,gDAAgD;IAChD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMzB;IAED,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,MAAM;IAUd,OAAO,CAAC,gBAAgB;CAOxB"}

package/packages/logging/dist/spool.js

@@ -0,0 +1,110 @@
+/**
+ * Local NDJSON spool - the last-resort destination for log batches.
+ *
+ * When every transport fails (no network, R2 down, webhook server down) the
+ * batch is written to disk instead of being lost. The spool is drained on
+ * the next successful flush, so a temporary outage does not cost data.
+ *
+ * Files are plain NDJSON, one record per line, so an operator can inspect
+ * them with `tail`, `jq` or `less` without any tooling.
+ */
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, } from "node:fs";
+import { join } from "node:path";
+const FILE_PREFIX = "logs-spool-";
+const FILE_SUFFIX = ".ndjson";
+export class LogSpool {
+    dir;
+    maxFileBytes;
+    maxFiles;
+    constructor(options) {
+        this.dir = options.dir;
+        this.maxFileBytes = Math.max(1024, options.maxFileBytes ?? 5 * 1024 * 1024);
+        this.maxFiles = Math.max(1, options.maxFiles ?? 20);
+    }
+    /** Append a batch to the spool. Returns the file that was written. */
+    append(batch, now = new Date()) {
+        this.ensureDir();
+        const file = this.currentFile(now);
+        const payload = batch.records.map((record) => JSON.stringify(record)).join("\n") + "\n";
+        if (this.shouldRotate(file, payload.length)) {
+            this.rotate(file);
+        }
+        appendFileSync(file, payload, "utf8");
+        this.enforceRetention();
+        return file;
+    }
+    /** Spool files, oldest first. */
+    list() {
+        if (!existsSync(this.dir))
+            return [];
+        return readdirSync(this.dir)
+            .filter((name) => name.startsWith(FILE_PREFIX) &&
+            (name.endsWith(FILE_SUFFIX) || new RegExp(`\\${FILE_SUFFIX}\\.\\d+$`).test(name)))
+            .map((name) => join(this.dir, name))
+            .sort();
+    }
+    /** Read the records of a spool file. */
+    read(file) {
+        if (!existsSync(file))
+            return [];
+        const content = readFileSync(file, "utf8");
+        const records = [];
+        for (const line of content.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                records.push(JSON.parse(trimmed));
+            }
+            catch {
+                // A truncated last line is expected after a crash; skip it.
+            }
+        }
+        return records;
+    }
+    /** Delete a spool file after it was shipped. */
+    remove(file) {
+        try {
+            rmSync(file, { force: true });
+        }
+        catch {
+            // Nothing to do - the file stays and is retried later.
+        }
+    }
+    ensureDir() {
+        if (!existsSync(this.dir)) {
+            mkdirSync(this.dir, { recursive: true });
+        }
+    }
+    currentFile(now) {
+        const day = now.toISOString().slice(0, 10);
+        return join(this.dir, `${FILE_PREFIX}${day}${FILE_SUFFIX}`);
+    }
+    shouldRotate(file, incomingBytes) {
+        if (!existsSync(file))
+            return false;
+        try {
+            return statSync(file).size + incomingBytes > this.maxFileBytes;
+        }
+        catch {
+            return false;
+        }
+    }
+    rotate(file) {
+        for (let index = 1; index <= this.maxFiles; index++) {
+            const candidate = `${file}.${index}`;
+            if (!existsSync(candidate)) {
+                renameSync(file, candidate);
+                return;
+            }
+        }
+    }
+    enforceRetention() {
+        const files = this.list();
+        const extra = files.length - this.maxFiles;
+        for (let i = 0; i < extra; i++) {
+            this.remove(files[i]);
+        }
+    }
+}
+//# sourceMappingURL=spool.js.map

package/packages/logging/dist/spool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spool.js","sourceRoot":"","sources":["../src/spool.ts"],"names":[],"mappings":"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"}