@newrelic/preflight 0.0.1-pre.1 → 1.0.0

package/dist/storage/local-store.d.ts

@@ -0,0 +1,153 @@
+import type { HookEvent, SessionSummary, AuditEntry } from './types.js';
+export declare class LocalStore {
+    private readonly storagePath;
+    private readonly bufferPath;
+    private readonly sessionId;
+    /**
+     * @param storagePath The base storage directory (e.g. ~/.newrelic-preflight).
+     * @param bufferPathOrSessionId Either an explicit absolute buffer path
+     *   (legacy / test override; takes precedence over sessionId) or a sessionId
+     *   that scopes the per-session buffer file (`buffer-<sessionId>.jsonl`).
+     *   Pass `undefined` for fan-out drain mode (`--local`) where there is no
+     *   single owning session — `drainBuffer()` will then return [] and callers
+     *   should use `drainAllBuffers()` instead.
+     * @param sessionId Optional sessionId for scoping per-session buffers.
+     *   Used when an explicit bufferPath is also provided (rare — the explicit
+     *   path still wins for the buffer location, sessionId is then ignored).
+     */
+    constructor(storagePath: string, bufferPathOrSessionId?: string, sessionId?: string);
+    initialize(): void;
+    /**
+     * Append a hook event as a JSON line to the buffer file.
+     * Uses appendFileSync for minimal latency (<5ms budget).
+     */
+    appendToBuffer(event: HookEvent): void;
+    /**
+     * Atomically drain all events from the buffer file.
+     * Renames the file to a temp path (atomic on POSIX), reads it, then deletes.
+     * This avoids data loss from concurrent hook writes during drain.
+     */
+    drainBuffer(): HookEvent[];
+    /**
+     * Drain every per-session buffer file under the storage path. Used by
+     * `--local` standalone mode where the dashboard owner sees all live
+     * sessions' events. Each file is drained atomically (rename-then-read) so a
+     * concurrent writer for that session can't lose events; orphan files (whose
+     * MCP isn't running) are picked up too.
+     */
+    drainAllBuffers(): HookEvent[];
+    /**
+     * Read every per-session buffer file under the storage path WITHOUT draining
+     * (no rename, no unlink). Used by the dashboard owner's
+     * `/api/sessions/today/aggregate` endpoint, which surfaces a global view
+     * across every live session — its own session_id-scoped drainBuffer() only
+     * covers its own events, so we need a read-only fan-out for cross-session
+     * KPIs.
+     *
+     * Torn-line handling: the LAST non-empty line is the only line that can
+     * legitimately be torn (a concurrent appender's incomplete write). If it
+     * fails to parse we drop it silently. Any earlier line that fails to parse
+     * is real corruption — events >PIPE_BUF (typically 4 KiB) interleaved by
+     * concurrent appenders, or an on-disk write that flushed partially. We log
+     * a WARN so the loss is visible rather than silently dropped.
+     *
+     * The legacy shared `buffer.jsonl` is included so an upgrading user with
+     * unmigrated events still appears in aggregate views before the next
+     * `migrateLegacyBuffer()` runs.
+     */
+    peekAllBuffers(): HookEvent[];
+    /**
+     * Write a heartbeat file `active-<sessionId>.pid` containing this process's
+     * PID. Used by the dashboard owner's GC pass to determine which buffer
+     * files still have a live owner. The MCP should call this once after
+     * resolving its session_id, and remove it on graceful shutdown via
+     * `removeHeartbeat()`.
+     *
+     * No-op if the LocalStore is not bound to a sessionId (e.g. --local mode).
+     */
+    writeHeartbeat(pid?: number): void;
+    /**
+     * Remove this MCP's heartbeat file. Called from the shutdown handler so the
+     * dashboard owner's next GC pass knows the buffer is up for adoption.
+     *
+     * No-op if no heartbeat was ever written or if the file is already gone.
+     */
+    removeHeartbeat(): void;
+    /**
+     * Garbage-collect orphan per-session buffer files. A buffer is orphan when
+     * no live process is currently draining it; we determine that with two
+     * signals:
+     *
+     *   1. Heartbeat (authoritative): if `active-<sessionId>.pid` exists and
+     *      its PID is alive, the buffer has an owner — leave it alone. If the
+     *      heartbeat exists but the PID is dead (process crashed before
+     *      cleanup), archive the buffer and delete the stale heartbeat.
+     *   2. Mtime fallback: if no heartbeat exists AND the buffer hasn't been
+     *      written to in `ORPHAN_BUFFER_MTIME_MS`, treat as orphan. This catches
+     *      crashes that happened before any heartbeat was written.
+     *
+     * Recently-modified buffers without a heartbeat are left alone — the MCP
+     * for that session may be in the breadcrumb-resolution window and not yet
+     * have written its heartbeat.
+     *
+     * The `activeSessionIds` set is also consulted: any session id present
+     * there is considered live regardless of heartbeat/mtime, which protects
+     * against heartbeat write delays on slow disks.
+     *
+     * Orphan buffers are renamed to `buffer-<sessionId>.jsonl.archived-<ts>`
+     * (preserved on disk for forensics, no longer scanned by the aggregator).
+     *
+     * @returns counts of files archived and stale heartbeats removed
+     */
+    gcOrphanBuffers(activeSessionIds: ReadonlySet<string>): {
+        archived: number;
+        staleHeartbeats: number;
+    };
+    /**
+     * Scan `<storage>/active-*.pid` heartbeat files and return the set of
+     * session ids whose owner PID is currently alive. Used by the dashboard
+     * owner to construct the `activeSessionIds` argument to
+     * `gcOrphanBuffers()`.
+     */
+    getActiveSessionIdsFromHeartbeats(): Set<string>;
+    /**
+     * Garbage-collect stale per-PPID breadcrumb files at
+     * `<storage>/session-by-ppid/<pid>.txt`. A breadcrumb is stale when its
+     * PID names a process that no longer exists (Claude Code session ended).
+     *
+     * @returns the number of breadcrumb files deleted
+     */
+    gcStaleBreadcrumbs(): number;
+    /**
+     * Migrate any pre-Fix-3 events left in the legacy shared `buffer.jsonl` into
+     * per-session `buffer-<sessionId>.jsonl` files, then delete the legacy file.
+     * Idempotent: returns 0 when the legacy file is absent or already empty.
+     *
+     * Concurrent-MCP-safe: the very first step is to atomically rename
+     * `buffer.jsonl` to `buffer.jsonl.migrating-<pid>`. The rename is the
+     * mutual-exclusion primitive — only one MCP wins; the loser sees ENOENT
+     * (the file is no longer at the legacy path) and skips migration.
+     *
+     * Failure recovery: if any partition append fails partway through, the
+     * `.migrating-<pid>` file is intentionally left in place. On the next boot
+     * the legacy file is gone, so we no-op; the partitioned files written so
+     * far hold the events that did make it across. The straggler events stuck
+     * in `.migrating-<pid>` are recovered manually (forensics) or dropped — we
+     * accept this trade because re-migrating from `.migrating-<pid>` would
+     * re-append already-migrated partitions and produce duplicate events,
+     * which is worse than a once-only loss bounded by the size of the legacy
+     * file at upgrade time.
+     *
+     * Returns the number of events migrated.
+     */
+    migrateLegacyBuffer(): number;
+    private drainPath;
+    /** The buffer path this store is currently scoped to (test helper). */
+    getBufferPath(): string;
+    /** The sessionId this store was scoped to, if any (test helper). */
+    getSessionId(): string | null;
+    saveSession(session: SessionSummary): void;
+    loadRecentSessions(days: number): SessionSummary[];
+    appendAuditLog(entry: AuditEntry): void;
+}
+//# sourceMappingURL=local-store.d.ts.map

package/dist/storage/local-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-store.d.ts","sourceRoot":"","sources":["../../src/storage/local-store.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAgCxE,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAE1C;;;;;;;;;;;OAWG;gBACS,WAAW,EAAE,MAAM,EAAE,qBAAqB,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;IAwCnF,UAAU,IAAI,IAAI;IAiBlB;;;OAGG;IACH,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAStC;;;;OAIG;IACH,WAAW,IAAI,SAAS,EAAE;IAI1B;;;;;;OAMG;IACH,eAAe,IAAI,SAAS,EAAE;IAuB9B;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,IAAI,SAAS,EAAE;IAsD7B;;;;;;;;OAQG;IACH,cAAc,CAAC,GAAG,GAAE,MAAoB,GAAG,IAAI;IAc/C;;;;;OAKG;IACH,eAAe,IAAI,IAAI;IAUvB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,eAAe,CAAC,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG;QACtD,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,MAAM,CAAC;KACzB;IAmGD;;;;;OAKG;IACH,iCAAiC,IAAI,GAAG,CAAC,MAAM,CAAC;IAyBhD;;;;;;OAMG;IACH,kBAAkB,IAAI,MAAM;IAmC5B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,mBAAmB,IAAI,MAAM;IAkG7B,OAAO,CAAC,SAAS;IA0DjB,uEAAuE;IACvE,aAAa,IAAI,MAAM;IAIvB,oEAAoE;IACpE,YAAY,IAAI,MAAM,GAAG,IAAI;IAI7B,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAc1C,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE;IAgClD,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;CAYxC"}