@appydave/core 0.1.0

package/src/lifecycle.ts

@@ -0,0 +1,206 @@
+/**
+ * Lifecycle harness — start, stop, reload, health.
+ *
+ * Coordinates graceful shutdown across the Sentinel:
+ * - Registers SIGINT / SIGTERM / SIGHUP listeners on first `start()`.
+ * - SIGINT/SIGTERM trigger `stop(reason)` exactly once.
+ * - SIGHUP triggers `reload()`.
+ * - Hooks fire in registration order on start, reverse order on stop.
+ * - `health()` is a synchronous snapshot suitable for `/health` endpoints.
+ *
+ * Spec §5.3.
+ */
+
+export type StopReason = 'sigint' | 'sigterm' | 'reload' | 'fatal' | 'manual';
+
+export type LifecycleStatus = 'idle' | 'starting' | 'running' | 'stopping' | 'stopped' | 'failed';
+
+export interface HealthReport {
+  status: LifecycleStatus;
+  startedAt?: string;
+  stoppedAt?: string;
+  uptimeMs?: number;
+  hooks: { start: number; stop: number; reload: number };
+  lastError?: string;
+}
+
+export type StartHook = () => void | Promise<void>;
+export type StopHook = (reason: StopReason) => void | Promise<void>;
+export type ReloadHook = () => void | Promise<void>;
+
+export interface Lifecycle {
+  start(): Promise<void>;
+  stop(reason?: StopReason): Promise<void>;
+  reload(): Promise<void>;
+  health(): HealthReport;
+
+  /** Register a hook that runs during `start()`. Returns an unsubscribe fn. */
+  onStart(hook: StartHook): () => void;
+  /** Register a hook that runs during `stop()`. Reverse-order. */
+  onStop(hook: StopHook): () => void;
+  /** Register a hook that runs during `reload()` / SIGHUP. */
+  onReload(hook: ReloadHook): () => void;
+}
+
+export interface CreateLifecycleOptions {
+  /**
+   * Whether to wire OS signal handlers (SIGINT/SIGTERM/SIGHUP) automatically.
+   * Defaults to true in production. Set false in tests.
+   */
+  installSignalHandlers?: boolean;
+  /** Optional log hook. */
+  log?: (level: 'info' | 'warn' | 'error', msg: string, meta?: Record<string, unknown>) => void;
+}
+
+/**
+ * Build a Lifecycle. The returned object is independent — multiple Sentinels
+ * in the same process each get their own (though OS signals will fan out).
+ */
+export function createLifecycle(options: CreateLifecycleOptions = {}): Lifecycle {
+  const startHooks: StartHook[] = [];
+  const stopHooks: StopHook[] = [];
+  const reloadHooks: ReloadHook[] = [];
+  const installSignalHandlers = options.installSignalHandlers ?? true;
+  const log =
+    options.log ??
+    (() => {
+      /* default: silent */
+    });
+
+  let status: LifecycleStatus = 'idle';
+  let startedAt: Date | undefined;
+  let stoppedAt: Date | undefined;
+  let lastError: string | undefined;
+  let stopPromise: Promise<void> | undefined;
+  let signalHandlersInstalled = false;
+
+  const installHandlers = (lifecycle: Lifecycle): void => {
+    if (signalHandlersInstalled || !installSignalHandlers) return;
+    signalHandlersInstalled = true;
+
+    const handle = (reason: StopReason) => () => {
+      log('info', `lifecycle: received signal`, { reason });
+      void lifecycle.stop(reason).then(() => {
+        // Once everything has shut down, exit cleanly so the process doesn't hang.
+        process.exit(0);
+      });
+    };
+
+    process.once('SIGINT', handle('sigint'));
+    process.once('SIGTERM', handle('sigterm'));
+    process.on('SIGHUP', () => {
+      log('info', 'lifecycle: received SIGHUP, reloading');
+      void lifecycle.reload().catch((err) => {
+        log('error', 'lifecycle: reload failed', { err: String(err) });
+      });
+    });
+  };
+
+  const lifecycle: Lifecycle = {
+    async start() {
+      if (status === 'starting' || status === 'running') return;
+      status = 'starting';
+      lastError = undefined;
+      startedAt = new Date();
+      stoppedAt = undefined;
+
+      try {
+        for (const hook of startHooks) {
+          await hook();
+        }
+        status = 'running';
+        installHandlers(lifecycle);
+        log('info', 'lifecycle: started');
+      } catch (err) {
+        status = 'failed';
+        lastError = String(err);
+        log('error', 'lifecycle: start failed', { err: lastError });
+        throw err;
+      }
+    },
+
+    async stop(reason: StopReason = 'manual') {
+      if (status === 'stopped' || status === 'idle') return;
+      if (stopPromise) return stopPromise;
+
+      status = 'stopping';
+      log('info', 'lifecycle: stopping', { reason });
+
+      stopPromise = (async () => {
+        // Reverse order — last-in, first-out.
+        for (let i = stopHooks.length - 1; i >= 0; i -= 1) {
+          const hook = stopHooks[i]!;
+          try {
+            await hook(reason);
+          } catch (err) {
+            log('error', 'lifecycle: stop hook threw', { err: String(err) });
+          }
+        }
+        status = 'stopped';
+        stoppedAt = new Date();
+        log('info', 'lifecycle: stopped');
+      })();
+
+      return stopPromise;
+    },
+
+    async reload() {
+      if (status !== 'running') {
+        log('warn', 'lifecycle: reload requested but not running', { status });
+        return;
+      }
+      log('info', 'lifecycle: reloading');
+      for (const hook of reloadHooks) {
+        try {
+          await hook();
+        } catch (err) {
+          log('error', 'lifecycle: reload hook threw', { err: String(err) });
+        }
+      }
+    },
+
+    health(): HealthReport {
+      const report: HealthReport = {
+        status,
+        hooks: {
+          start: startHooks.length,
+          stop: stopHooks.length,
+          reload: reloadHooks.length,
+        },
+      };
+      if (startedAt) {
+        report.startedAt = startedAt.toISOString();
+        report.uptimeMs = Date.now() - startedAt.getTime();
+      }
+      if (stoppedAt) report.stoppedAt = stoppedAt.toISOString();
+      if (lastError) report.lastError = lastError;
+      return report;
+    },
+
+    onStart(hook) {
+      startHooks.push(hook);
+      return () => {
+        const idx = startHooks.indexOf(hook);
+        if (idx >= 0) startHooks.splice(idx, 1);
+      };
+    },
+
+    onStop(hook) {
+      stopHooks.push(hook);
+      return () => {
+        const idx = stopHooks.indexOf(hook);
+        if (idx >= 0) stopHooks.splice(idx, 1);
+      };
+    },
+
+    onReload(hook) {
+      reloadHooks.push(hook);
+      return () => {
+        const idx = reloadHooks.indexOf(hook);
+        if (idx >= 0) reloadHooks.splice(idx, 1);
+      };
+    },
+  };
+
+  return lifecycle;
+}

package/src/logger.ts

@@ -0,0 +1,52 @@
+/**
+ * Pino logger factory with child-logger support.
+ *
+ * Sentinels emit structured logs. Pino is fast, JSON-by-default, and supports
+ * child loggers without context-passing ceremony.
+ */
+
+import pino, { type Logger as PinoLogger, type LoggerOptions } from 'pino';
+
+export type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'silent';
+
+export interface CreateLoggerOptions {
+  /** Component name used as the root binding (default: 'sentinel'). */
+  name?: string;
+  /** Log level. Reads $LOG_LEVEL or defaults to 'info'. */
+  level?: LogLevel;
+  /**
+   * If true, route through pino-pretty for human-readable dev output.
+   * Caller must install `pino-pretty` themselves.
+   */
+  pretty?: boolean;
+  /** Extra bindings included on every log line. */
+  bindings?: Record<string, unknown>;
+}
+
+/** A small re-export type so consumers don't need to depend on pino directly. */
+export type Logger = PinoLogger;
+
+/**
+ * Create a configured Pino logger. Convenient defaults; opts in to pretty
+ * printing only when explicitly requested.
+ */
+export function createLogger(options: CreateLoggerOptions = {}): Logger {
+  const level: LogLevel = options.level ?? (process.env['LOG_LEVEL'] as LogLevel) ?? 'info';
+  const baseOptions: LoggerOptions = {
+    name: options.name ?? 'sentinel',
+    level,
+    ...(options.bindings ? { base: options.bindings } : {}),
+  };
+
+  if (options.pretty) {
+    return pino({
+      ...baseOptions,
+      transport: {
+        target: 'pino-pretty',
+        options: { colorize: true, translateTime: 'SYS:standard' },
+      },
+    });
+  }
+
+  return pino(baseOptions);
+}

package/src/serial-queue.ts

@@ -0,0 +1,53 @@
+/**
+ * SerialQueue — promise-chain serialisation primitive.
+ *
+ * Ensures tasks run in submission order, one at a time. Non-blocking to
+ * callers — `enqueue` returns a promise that resolves when the task completes.
+ *
+ * Use when ordered I/O matters (e.g. JSONL append, atomic file write,
+ * subprocess request stream).
+ */
+export class SerialQueue {
+  private tail: Promise<unknown> = Promise.resolve();
+  private pendingCount = 0;
+
+  /**
+   * Enqueue a task. The task runs after every previously-enqueued task
+   * resolves (or rejects). The returned promise resolves with the task's
+   * value, or rejects with the task's error.
+   *
+   * Importantly, errors do NOT poison the chain — subsequent tasks still run.
+   */
+  enqueue<T>(task: () => Promise<T> | T): Promise<T> {
+    this.pendingCount += 1;
+    const run = this.tail.then(
+      () => task(),
+      () => task() // never let a previous failure block the next task
+    );
+    // The chain itself absorbs errors so subsequent enqueues don't see them.
+    // Track pending count off the swallowed chain too — otherwise the unhandled
+    // rejection lands on `run.finally(...)` when the caller awaits before the
+    // microtask flush.
+    const tracked = run.catch(() => undefined).then(() => {
+      this.pendingCount -= 1;
+    });
+    this.tail = tracked;
+    return run as Promise<T>;
+  }
+
+  /**
+   * Resolve once the queue has fully drained (no pending tasks).
+   */
+  async drain(): Promise<void> {
+    while (this.pendingCount > 0) {
+      await this.tail;
+    }
+  }
+
+  /**
+   * Number of tasks currently queued or running.
+   */
+  get size(): number {
+    return this.pendingCount;
+  }
+}

package/src/store.ts

@@ -0,0 +1,74 @@
+/**
+ * Store — local-first JSON persistence.
+ *
+ * A thin, crash-safe wrapper over `atomicWrite` (torn-write-proof file writes)
+ * and `SerialQueue` (ordered, one-at-a-time access). Every read/write/update is
+ * serialised through a single queue, so concurrent `update()` calls never lose a
+ * write — the classic read-modify-write race is eliminated.
+ *
+ * Not a database: one JSON document per Store. For structured/queryable data a
+ * consumer reaches for SQLite (a per-product recipe), not this.
+ */
+
+import { promises as fs } from 'node:fs';
+import { atomicWrite, type AtomicWriteOptions } from './atomic-write.js';
+import { SerialQueue } from './serial-queue.js';
+
+export interface StoreOptions<T> {
+  /** Absolute path to the JSON file backing this store. */
+  path: string;
+  /** Value returned by `read()` when the file does not yet exist. */
+  defaults: T;
+  /** Passed through to `atomicWrite` (mode, fsync, encoding). */
+  write?: AtomicWriteOptions;
+  /** `JSON.stringify` spacing. Defaults to 2 (pretty-printed). */
+  space?: number | string;
+}
+
+export interface Store<T> {
+  /** Read + parse the file. Returns a fresh clone of `defaults` if absent. */
+  read(): Promise<T>;
+  /** Atomically overwrite the file with `value`. Serialised. */
+  write(value: T): Promise<void>;
+  /** Read → apply `fn` → atomically write the result. Serialised end-to-end. */
+  update(fn: (current: T) => T): Promise<T>;
+}
+
+export function createStore<T>(options: StoreOptions<T>): Store<T> {
+  const { path, defaults, write: writeOptions, space = 2 } = options;
+  const queue = new SerialQueue();
+
+  async function readRaw(): Promise<T> {
+    try {
+      const text = await fs.readFile(path, 'utf8');
+      return JSON.parse(text) as T;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        // Fresh clone so callers can't mutate the shared defaults object.
+        return structuredClone(defaults);
+      }
+      throw err;
+    }
+  }
+
+  async function writeRaw(value: T): Promise<void> {
+    await atomicWrite(path, JSON.stringify(value, null, space), writeOptions);
+  }
+
+  return {
+    read() {
+      return queue.enqueue(readRaw);
+    },
+    write(value: T) {
+      return queue.enqueue(() => writeRaw(value));
+    },
+    update(fn: (current: T) => T) {
+      return queue.enqueue(async () => {
+        const current = await readRaw();
+        const next = fn(current);
+        await writeRaw(next);
+        return next;
+      });
+    },
+  };
+}