@spooky-sync/core 0.0.1-canary.30 → 0.0.1-canary.300

package/src/services/logger/index.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { LogTap, createLogger, stringifyLog } from './index';
+
+// Vitest runs in node, where `pino` resolves to its node build and ignores the
+// `browser` options the tap hangs off. Apps bundle the browser build.
+// The specifier is widened to `string`: pino ships no types for that entry.
+vi.mock('pino', async () => ({ default: (await import('pino/browser.js' as string)).default }));
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+function silentConsole() {
+  return vi.spyOn(console, 'log').mockImplementation(() => {});
+}
+
+describe('LogTap', () => {
+  it('records what the logger writes, child bindings included', () => {
+    silentConsole();
+    const tap = new LogTap('info');
+    const logger = createLogger('info', undefined, tap);
+    logger.child({ service: 'Database' }).warn({ Category: 'x' }, 'slow query');
+    logger.debug('not at this level');
+    const { entries, head } = tap.read();
+    expect(entries).toHaveLength(1);
+    expect(head).toBe(1);
+    expect(entries[0]).toMatchObject({ seq: 1, level: 40, msg: 'slow query' });
+    expect(JSON.parse(entries[0].line)).toMatchObject({ service: 'Database', Category: 'x' });
+  });
+
+  it('captures below the console level without printing it, on existing children too', () => {
+    const printed = silentConsole();
+    const tap = new LogTap('info');
+    const logger = createLogger('info', undefined, tap);
+    const child = logger.child({ service: 'Sync' });
+    child.debug('before');
+    tap.setCaptureLevel('debug');
+    child.debug('after');
+    logger.info('shown');
+    expect(tap.read().entries.map((e) => e.msg)).toEqual(['after', 'shown']);
+    expect(printed).toHaveBeenCalledTimes(1);
+    expect(String(printed.mock.calls[0][0])).toContain('shown');
+  });
+
+  it('keeps the capture level for the tab session', () => {
+    const store = new Map<string, string>();
+    vi.stubGlobal('sessionStorage', {
+      getItem: (k: string) => store.get(k) ?? null,
+      setItem: (k: string, v: string) => void store.set(k, v),
+      removeItem: (k: string) => void store.delete(k),
+    });
+    new LogTap('info').setCaptureLevel('trace');
+    expect(new LogTap('info').captureLevel).toBe('trace');
+    new LogTap('info').setCaptureLevel('info');
+    expect(store.size).toBe(0);
+  });
+
+  it('is a bounded ring that reports what a slow reader missed', () => {
+    silentConsole();
+    const tap = new LogTap('info');
+    const logger = createLogger('info', undefined, tap);
+    for (let i = 0; i < LogTap.CAPACITY + 10; i++) logger.info(`line ${i}`);
+    const all = tap.read();
+    expect(all.entries).toHaveLength(LogTap.CAPACITY);
+    expect(all.dropped).toBe(10);
+    const delta = tap.read(all.head - 2);
+    expect(delta.entries.map((e) => e.msg)).toEqual([`line ${LogTap.CAPACITY + 8}`, `line ${LogTap.CAPACITY + 9}`]);
+    expect(delta.dropped).toBe(0);
+  });
+
+  it('does not count cleared lines as dropped', () => {
+    silentConsole();
+    const tap = new LogTap('info');
+    const logger = createLogger('info', undefined, tap);
+    logger.info('a');
+    logger.info('b');
+    tap.clear();
+    logger.info('c');
+    expect(tap.read(0)).toMatchObject({ dropped: 0, head: 3 });
+    expect(tap.read(0).entries.map((e) => e.msg)).toEqual(['c']);
+  });
+
+  it('caps a huge line', () => {
+    silentConsole();
+    const tap = new LogTap('info');
+    createLogger('info', undefined, tap).info({ blob: 'x'.repeat(LogTap.LINE_MAX * 2) }, 'big');
+    const [entry] = tap.read().entries;
+    expect(entry.line.length).toBe(LogTap.LINE_MAX + 1);
+    expect(entry.msg).toBe('big');
+  });
+
+  it('notifies listeners and survives one that throws', () => {
+    silentConsole();
+    const tap = new LogTap('info');
+    const logger = createLogger('info', undefined, tap);
+    const seen: number[] = [];
+    tap.subscribe(() => {
+      throw new Error('listener bug');
+    });
+    tap.subscribe(() => seen.push(tap.head));
+    expect(() => logger.info('x')).not.toThrow();
+    expect(seen).toEqual([1]);
+  });
+
+  it('keeps the otel transmit at the configured level when capture goes lower', () => {
+    silentConsole();
+    const sent: string[] = [];
+    const tap = new LogTap('info');
+    const logger = createLogger('info', { send: (level) => void sent.push(level) }, tap);
+    tap.setCaptureLevel('debug');
+    logger.debug('d');
+    logger.info('i');
+    expect(sent).toEqual(['info']);
+  });
+});
+
+describe('stringifyLog', () => {
+  it('keeps errors readable and never throws on bigints or cycles', () => {
+    const o: Record<string, unknown> = { err: new Error('boom'), n: 10n };
+    o.self = o;
+    const parsed = JSON.parse(stringifyLog(o));
+    expect(parsed.err).toMatchObject({ type: 'Error', message: 'boom' });
+    expect(parsed.n).toBe('10');
+    expect(parsed.self).toBe('[Circular]');
+  });
+
+  it('does not mistake a shared reference for a cycle', () => {
+    const shared = { a: 1 };
+    expect(JSON.parse(stringifyLog({ x: shared, y: shared }))).toEqual({ x: { a: 1 }, y: { a: 1 } });
+  });
+});

package/src/services/logger/index.ts

@@ -1,22 +1,204 @@
-import pino, { Level, type Logger as PinoLogger, type LoggerOptions } from 'pino';
-import { PinoTransmit } from '../../types';
+import pino, { type Level, type Logger as PinoLogger, type LoggerOptions } from 'pino';
+import type { PinoTransmit } from '../../types';
 
 export type Logger = PinoLogger;
 
-export function createLogger(level: Level = 'info', transmit?: PinoTransmit): Logger {
+/** One line the logger wrote, as the DevTools Logs tab and the MCP read it. */
+export interface CapturedLog {
+  /** Monotonic for the page's lifetime; a reader resumes after the last one it holds. */
+  seq: number;
+  time: number;
+  /** Pino's numeric level: 10 trace … 60 fatal. */
+  level: number;
+  msg: string;
+  /** The whole log object as JSON (what the console printed), capped at {@link LogTap.LINE_MAX}. */
+  line: string;
+}
+
+export interface LogRead {
+  entries: CapturedLog[];
+  /** `seq` of the newest captured line; pass it back as `after` to resume. */
+  head: number;
+  /** Lines after `after` the ring overwrote before they were read (cleared ones excluded). */
+  dropped: number;
+  consoleLevel: Level;
+  captureLevel: Level;
+}
+
+const LEVELS = pino.levels.values as Record<Level, number>;
+const CAPTURE_KEY = 'sp00ky:devtools:logCapture';
+
+function isLevel(value: unknown): value is Level {
+  return typeof value === 'string' && value in LEVELS;
+}
+
+/**
+ * JSON for a log object that can never throw into the call site: Errors keep
+ * their message and stack (plain `JSON.stringify` prints `{}`), bigints become
+ * strings, and a cycle prints `[Circular]` instead of throwing.
+ */
+export function stringifyLog(o: unknown): string {
+  const ancestors: unknown[] = [];
+  try {
+    return JSON.stringify(o, function (this: unknown, _key: string, value: unknown) {
+      if (typeof value === 'bigint') return value.toString();
+      if (value instanceof Error) return { type: value.name, message: value.message, stack: value.stack };
+      if (typeof value !== 'object' || value === null) return value;
+      while (ancestors.length > 0 && ancestors.at(-1) !== this) ancestors.pop();
+      if (ancestors.includes(value)) return '[Circular]';
+      ancestors.push(value);
+      return value;
+    });
+  } catch {
+    const msg = (o as { msg?: unknown } | null)?.msg;
+    return JSON.stringify({ msg: typeof msg === 'string' ? msg : '[unserializable log object]' });
+  }
+}
+
+/**
+ * The page-side log buffer behind the DevTools Logs tab. Always on and
+ * bounded: a line costs the JSON the console write produces anyway, and a
+ * panel opened after boot still sees the boot.
+ *
+ * It also owns the logger's level. The console prints at the configured level
+ * only; `setCaptureLevel` changes what is RECORDED (debug without flooding the
+ * console), live on every child logger, and keeps it for this tab's session so
+ * a reload captures its boot at that level too.
+ */
+export class LogTap {
+  static readonly CAPACITY = 500;
+  static readonly LINE_MAX = 4000;
+
+  private readonly ring: CapturedLog[] = [];
+  private seq = 0;
+  /** `seq` at the last `clear()`: lines up to here are gone on purpose, not dropped. */
+  private clearedThrough = 0;
+  private readonly listeners = new Set<() => void>();
+  private readonly loggers: Array<WeakRef<Logger>> = [];
+  private captureLevelValue: Level;
+
+  constructor(readonly consoleLevel: Level) {
+    this.captureLevelValue = consoleLevel;
+    try {
+      const saved = typeof sessionStorage !== 'undefined' ? sessionStorage.getItem(CAPTURE_KEY) : null;
+      if (isLevel(saved)) this.captureLevelValue = saved;
+    } catch {
+      // Storage blocked: capture at the console level.
+    }
+  }
+
+  /** `seq` of the newest captured line. */
+  get head(): number {
+    return this.seq;
+  }
+
+  get captureLevel(): Level {
+    return this.captureLevelValue;
+  }
+
+  /** What pino has to produce for both the console and the buffer. */
+  get effectiveLevel(): Level {
+    return LEVELS[this.captureLevelValue] < LEVELS[this.consoleLevel] ? this.captureLevelValue : this.consoleLevel;
+  }
+
+  /** Whether the console prints a line at this numeric level. */
+  printsToConsole(level: number): boolean {
+    return level >= LEVELS[this.consoleLevel];
+  }
+
+  /** Remember a logger (the root and every child) so a level change reaches it. */
+  track(logger: Logger): void {
+    this.loggers.push(new WeakRef(logger));
+  }
+
+  setCaptureLevel(level: Level): void {
+    if (!isLevel(level)) throw new Error(`unknown log level: ${String(level)}`);
+    this.captureLevelValue = level;
+    try {
+      if (typeof sessionStorage !== 'undefined') {
+        if (level === this.consoleLevel) sessionStorage.removeItem(CAPTURE_KEY);
+        else sessionStorage.setItem(CAPTURE_KEY, level);
+      }
+    } catch {
+      // Storage blocked: the change holds until the page goes away.
+    }
+    const effective = this.effectiveLevel;
+    for (let i = this.loggers.length - 1; i >= 0; i--) {
+      const logger = this.loggers[i].deref();
+      if (logger) logger.level = effective;
+      else this.loggers.splice(i, 1);
+    }
+  }
+
+  record(o: Record<string, unknown>, line: string): void {
+    const level = typeof o.level === 'number' ? o.level : LEVELS.info;
+    if (level < LEVELS[this.captureLevelValue]) return;
+    this.ring.push({
+      seq: ++this.seq,
+      time: typeof o.time === 'number' ? o.time : Date.now(),
+      level,
+      msg: typeof o.msg === 'string' ? o.msg : '',
+      line: line.length > LogTap.LINE_MAX ? `${line.slice(0, LogTap.LINE_MAX)}…` : line,
+    });
+    if (this.ring.length > LogTap.CAPACITY) this.ring.shift();
+    for (const cb of this.listeners) {
+      try {
+        cb();
+      } catch {
+        // A listener must never turn a log call into a throw.
+      }
+    }
+  }
+
+  /** Lines after `after` (0 = everything still buffered), oldest first. */
+  read(after = 0, limit = LogTap.CAPACITY): LogRead {
+    const first = this.ring[0]?.seq ?? this.seq + 1;
+    const fresh = this.ring.filter((e) => e.seq > after);
+    return {
+      entries: fresh.slice(Math.max(0, fresh.length - limit)),
+      head: this.seq,
+      dropped: Math.max(0, first - Math.max(after, this.clearedThrough) - 1),
+      consoleLevel: this.consoleLevel,
+      captureLevel: this.captureLevelValue,
+    };
+  }
+
+  clear(): void {
+    this.ring.length = 0;
+    this.clearedThrough = this.seq;
+  }
+
+  /** Called synchronously inside the log call: keep it cheap, never log from it. */
+  subscribe(cb: () => void): () => void {
+    this.listeners.add(cb);
+    return () => void this.listeners.delete(cb);
+  }
+}
+
+export function createLogger(level: Level = 'info', transmit?: PinoTransmit, tap?: LogTap): Logger {
   const browserConfig: LoggerOptions['browser'] = {
     asObject: true,
     write: (o: any) => {
-      console.log(JSON.stringify(o));
+      const line = stringifyLog(o);
+      if (!tap || tap.printsToConsole(o?.level)) {
+        // oxlint-disable-next-line no-console
+        console.log(line);
+      }
+      tap?.record(o, line);
     },
   };
 
   if (transmit) {
-    browserConfig.transmit = transmit;
+    // Pinned to the configured level: a lower capture level for DevTools must
+    // not start shipping debug lines to the collector.
+    browserConfig.transmit = { ...transmit, level: transmit.level ?? level };
   }
 
-  return pino({
-    level,
+  const logger = pino({
+    level: tap ? tap.effectiveLevel : level,
     browser: browserConfig,
+    onChild: (child) => tap?.track(child),
   });
+  tap?.track(logger);
+  return logger;
 }

package/src/services/persistence/localstorage.ts

@@ -1,5 +1,5 @@
-import { Logger } from 'pino';
-import { PersistenceClient } from '../../types';
+import type { Logger } from 'pino';
+import type { PersistenceClient } from '../../types';
 
 export class LocalStoragePersistenceClient implements PersistenceClient {
   private logger: Logger;

package/src/services/persistence/resilient.ts

@@ -1,5 +1,5 @@
-import { Logger } from 'pino';
-import { PersistenceClient } from '../../types';
+import type { Logger } from 'pino';
+import type { PersistenceClient } from '../../types';
 
 export class ResilientPersistenceClient implements PersistenceClient {
   private logger: Logger;
@@ -23,7 +23,14 @@ export class ResilientPersistenceClient implements PersistenceClient {
         { key, error: e, Category: 'sp00ky-client::ResilientPersistenceClient::get' },
         'Persistence read failed, dropping key'
       );
-      await this.inner.remove(key).catch(() => {});
+      // Best-effort cleanup of the corrupt key; if removal also fails, the key
+      // just gets dropped again on the next failed read, so the failure is safe.
+      await this.inner.remove(key).catch((removeErr) => {
+        this.logger.debug(
+          { key, error: removeErr, Category: 'sp00ky-client::ResilientPersistenceClient::get' },
+          'Failed to drop corrupt persistence key'
+        );
+      });
       return null;
     }
   }

package/src/services/persistence/surrealdb.ts

@@ -1,13 +1,13 @@
-import { PersistenceClient } from '../../types';
+import type { PersistenceClient } from '../../types';
 import { parseRecordIdString, surql } from '../../utils/index';
-import { Logger } from 'pino';
-import { AbstractDatabaseService } from '../database/database';
+import type { Logger } from 'pino';
+import type { LocalStore } from '../database/cache-engine';
 
 export class SurrealDBPersistenceClient implements PersistenceClient {
   private logger: Logger;
 
   constructor(
-    private db: AbstractDatabaseService,
+    private db: LocalStore,
     logger: Logger
   ) {
     this.logger = logger.child({ service: 'PersistenceClient:SurrealDb' });