@appydave/core 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# @appydave/core
+
+The shared, product-prefix-free foundation reused by every AppyDave boilerplate
+(AppyStack · AppySentinel · AppyTron).
+
+```bash
+npm i @appydave/core
+```
+
+## Primitives
+
+| Export | What it does |
+|--------|--------------|
+| `createLifecycle()` | start/stop hook harness (signals, ordered hooks, health) |
+| `createConfigLoader()` | defaults → file → env, Zod-validated, reloadable |
+| `createLogger({ name })` | Pino structured logging |
+| `atomicWrite(path, content)` | torn-write-proof file write (`string \| Uint8Array`) |
+| `SerialQueue` | ordered, one-at-a-time task queue |
+| `createStore({ path, defaults })` | local-first JSON store (atomic + serialised) |
+
+No product-specific, web, or Electron code — those live in the consuming boilerplate.
+
+MIT · David Cruwys · [github.com/appydave/foundation](https://github.com/appydave/foundation)

package/dist/atomic-write.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Atomic file write helper.
+ *
+ * Pattern: write to a sibling temp file, then `rename` into place. On POSIX
+ * filesystems (and APFS / NTFS via Node's promisified fs.rename) this is
+ * atomic at the directory-entry level — readers either see the previous
+ * version or the new one, never a torn write.
+ *
+ * Essential for crash safety with flat-file stores (JSONL indexes, registry
+ * snapshots, config files).
+ */
+export interface AtomicWriteOptions {
+    /** File mode (e.g. 0o600). Defaults to system default. */
+    mode?: number;
+    /** Encoding for string content. Defaults to 'utf8'. */
+    encoding?: BufferEncoding;
+    /**
+     * fsync the file before rename. Slower but stronger crash guarantee.
+     * Defaults to false.
+     */
+    fsync?: boolean;
+}
+/**
+ * Atomically write content to `path`.
+ *
+ * Behaviour:
+ * 1. Write to `<path>.<random>.tmp` in the same directory.
+ * 2. Optionally fsync.
+ * 3. `rename` over the destination.
+ * 4. On any error, the temp file is removed on a best-effort basis.
+ */
+export declare function atomicWrite(path: string, content: string | Uint8Array, options?: AtomicWriteOptions): Promise<void>;
+//# sourceMappingURL=atomic-write.d.ts.map

package/dist/atomic-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAuCf"}

package/dist/atomic-write.js

@@ -0,0 +1,63 @@
+/**
+ * Atomic file write helper.
+ *
+ * Pattern: write to a sibling temp file, then `rename` into place. On POSIX
+ * filesystems (and APFS / NTFS via Node's promisified fs.rename) this is
+ * atomic at the directory-entry level — readers either see the previous
+ * version or the new one, never a torn write.
+ *
+ * Essential for crash safety with flat-file stores (JSONL indexes, registry
+ * snapshots, config files).
+ */
+import { promises as fs } from 'node:fs';
+import { dirname, basename, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+/**
+ * Atomically write content to `path`.
+ *
+ * Behaviour:
+ * 1. Write to `<path>.<random>.tmp` in the same directory.
+ * 2. Optionally fsync.
+ * 3. `rename` over the destination.
+ * 4. On any error, the temp file is removed on a best-effort basis.
+ */
+export async function atomicWrite(path, content, options = {}) {
+    const dir = dirname(path);
+    const base = basename(path);
+    const suffix = randomBytes(6).toString('hex');
+    const tmp = join(dir, `.${base}.${suffix}.tmp`);
+    let handle;
+    try {
+        handle = await fs.open(tmp, 'w', options.mode);
+        if (typeof content === 'string') {
+            await handle.writeFile(content, { encoding: options.encoding ?? 'utf8' });
+        }
+        else {
+            await handle.writeFile(content);
+        }
+        if (options.fsync) {
+            await handle.sync();
+        }
+        await handle.close();
+        handle = undefined;
+        await fs.rename(tmp, path);
+    }
+    catch (err) {
+        if (handle) {
+            try {
+                await handle.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        try {
+            await fs.unlink(tmp);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=atomic-write.js.map

package/dist/atomic-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAc1C;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAY,EACZ,OAA4B,EAC5B,UAA8B,EAAE;IAEhC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,IAAI,MAAM,MAAM,CAAC,CAAC;IAEhD,IAAI,MAAiC,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAE/C,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,MAAM,EAAE,CAAC,CAAC;QAC5E,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACtB,CAAC;QAED,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,MAAM,GAAG,SAAS,CAAC;QAEnB,MAAM,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACvB,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;QACH,CAAC;QACD,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,yBAAyB;QAC3B,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Hierarchical config loader: built-in defaults → env vars → config file.
+ *
+ * Validated through a Zod schema. Optional file-watch reloads via SIGHUP or
+ * a chokidar watcher driven externally.
+ *
+ * Spec §5.4.
+ */
+import { z } from 'zod';
+export interface ConfigLoaderOptions<T> {
+    /** Zod schema describing the merged config. */
+    schema: z.ZodType<T>;
+    /** Static defaults applied first. */
+    defaults?: Partial<T>;
+    /**
+     * Map of env var names → object paths to layer in.
+     *
+     * Example: `{ LOG_LEVEL: 'logger.level' }` reads `process.env.LOG_LEVEL`
+     * and sets `config.logger.level`. Values are strings; coerce inside the
+     * Zod schema (via `z.coerce.number()` etc).
+     */
+    env?: Record<string, string>;
+    /** Optional path to a JSON config file. Missing file is not an error. */
+    filePath?: string;
+    /**
+     * Custom env source (defaults to process.env). Useful for tests.
+     */
+    envSource?: NodeJS.ProcessEnv;
+}
+export interface ConfigLoader<T> {
+    /** Load + validate the merged config. Throws on schema errors. */
+    load(): Promise<T>;
+    /**
+     * Re-read the config file and re-merge env. Returns the new config.
+     * Subscribers registered via `onChange` are notified.
+     */
+    reload(): Promise<T>;
+    /** Register a change handler. Returns an unsubscribe function. */
+    onChange(handler: (config: T) => void): () => void;
+    /** Most recently loaded config, if any. */
+    current(): T | undefined;
+}
+/**
+ * Create a hierarchical config loader.
+ *
+ * Layering order (later overrides earlier):
+ * 1. `options.defaults`
+ * 2. JSON file at `options.filePath` (if present)
+ * 3. environment variables mapped via `options.env`
+ *
+ * Validation runs once at the end against `options.schema`.
+ */
+export declare function createConfigLoader<T>(options: ConfigLoaderOptions<T>): ConfigLoader<T>;
+export { z };
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,+CAA+C;IAC/C,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAErB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAEtB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,kEAAkE;IAClE,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAEnB;;;OAGG;IACH,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAErB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAEnD,2CAA2C;IAC3C,OAAO,IAAI,CAAC,GAAG,SAAS,CAAC;CAC1B;AA4DD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CA6DtF;AAED,OAAO,EAAE,CAAC,EAAE,CAAC"}

package/dist/config.js

@@ -0,0 +1,129 @@
+/**
+ * Hierarchical config loader: built-in defaults → env vars → config file.
+ *
+ * Validated through a Zod schema. Optional file-watch reloads via SIGHUP or
+ * a chokidar watcher driven externally.
+ *
+ * Spec §5.4.
+ */
+import { promises as fs } from 'node:fs';
+import { z } from 'zod';
+function setPath(target, path, value) {
+    const segments = path.split('.');
+    let node = target;
+    for (let i = 0; i < segments.length - 1; i += 1) {
+        const seg = segments[i];
+        const next = node[seg];
+        if (next === undefined || next === null || typeof next !== 'object') {
+            const fresh = {};
+            node[seg] = fresh;
+            node = fresh;
+        }
+        else {
+            node = next;
+        }
+    }
+    node[segments[segments.length - 1]] = value;
+}
+/** Deep merge — plain objects only, arrays replace. */
+function deepMerge(base, overlay) {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(overlay)) {
+        const existing = out[key];
+        if (existing &&
+            typeof existing === 'object' &&
+            !Array.isArray(existing) &&
+            value &&
+            typeof value === 'object' &&
+            !Array.isArray(value)) {
+            out[key] = deepMerge(existing, value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+async function readJsonFile(path) {
+    try {
+        const raw = await fs.readFile(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        throw new Error(`config file ${path} must contain a JSON object`);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+}
+/**
+ * Create a hierarchical config loader.
+ *
+ * Layering order (later overrides earlier):
+ * 1. `options.defaults`
+ * 2. JSON file at `options.filePath` (if present)
+ * 3. environment variables mapped via `options.env`
+ *
+ * Validation runs once at the end against `options.schema`.
+ */
+export function createConfigLoader(options) {
+    const handlers = new Set();
+    let lastConfig;
+    const envSource = options.envSource ?? process.env;
+    const buildOnce = async () => {
+        let merged = (options.defaults ?? {});
+        if (options.filePath) {
+            const fileLayer = await readJsonFile(options.filePath);
+            if (fileLayer)
+                merged = deepMerge(merged, fileLayer);
+        }
+        if (options.env) {
+            const envOverlay = {};
+            for (const [varName, dottedPath] of Object.entries(options.env)) {
+                const raw = envSource[varName];
+                if (raw !== undefined) {
+                    setPath(envOverlay, dottedPath, raw);
+                }
+            }
+            if (Object.keys(envOverlay).length > 0) {
+                merged = deepMerge(merged, envOverlay);
+            }
+        }
+        return options.schema.parse(merged);
+    };
+    return {
+        async load() {
+            const cfg = await buildOnce();
+            lastConfig = cfg;
+            return cfg;
+        },
+        async reload() {
+            const cfg = await buildOnce();
+            lastConfig = cfg;
+            for (const handler of handlers) {
+                try {
+                    handler(cfg);
+                }
+                catch (err) {
+                    // eslint-disable-next-line no-console
+                    console.error('[appysentinel] config onChange handler error', err);
+                }
+            }
+            return cfg;
+        },
+        onChange(handler) {
+            handlers.add(handler);
+            return () => {
+                handlers.delete(handler);
+            };
+        },
+        current() {
+            return lastConfig;
+        },
+    };
+}
+export { z };
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @appydave/core — shared AppyDave foundation primitives.
+ *
+ * Cross-cutting building blocks reused by every AppyDave boilerplate
+ * (AppyStack, AppySentinel, AppyTron): process lifecycle, config loading,
+ * structured logging, atomic file writes, a serial task queue, and a
+ * local-first JSON store. No product-specific or Electron code lives here.
+ */
+export { type Lifecycle, type LifecycleStatus, type StopReason, type HealthReport, type StartHook, type StopHook, type ReloadHook, type CreateLifecycleOptions, createLifecycle, } from './lifecycle.js';
+export { type ConfigLoader, type ConfigLoaderOptions, createConfigLoader, z, } from './config.js';
+export { createLogger, type Logger, type LogLevel, type CreateLoggerOptions, } from './logger.js';
+export { atomicWrite, type AtomicWriteOptions } from './atomic-write.js';
+export { SerialQueue } from './serial-queue.js';
+export { createStore, type Store, type StoreOptions } from './store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,sBAAsB,EAC3B,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,kBAAkB,EAClB,CAAC,GACF,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,YAAY,EACZ,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEzE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAE,KAAK,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @appydave/core — shared AppyDave foundation primitives.
+ *
+ * Cross-cutting building blocks reused by every AppyDave boilerplate
+ * (AppyStack, AppySentinel, AppyTron): process lifecycle, config loading,
+ * structured logging, atomic file writes, a serial task queue, and a
+ * local-first JSON store. No product-specific or Electron code lives here.
+ */
+export { createLifecycle, } from './lifecycle.js';
+export { createConfigLoader, z, } from './config.js';
+export { createLogger, } from './logger.js';
+export { atomicWrite } from './atomic-write.js';
+export { SerialQueue } from './serial-queue.js';
+export { createStore } from './store.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EASL,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAGL,kBAAkB,EAClB,CAAC,GACF,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,YAAY,GAIb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AAEzE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAiC,MAAM,YAAY,CAAC"}

package/dist/lifecycle.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 declare function createLifecycle(options?: CreateLifecycleOptions): Lifecycle;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE9E,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElG,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AACnD,MAAM,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AACpE,MAAM,MAAM,UAAU,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpD,MAAM,WAAW,SAAS;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,MAAM,IAAI,YAAY,CAAC;IAEvB,6EAA6E;IAC7E,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,IAAI,CAAC;IACrC,gEAAgE;IAChE,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,IAAI,CAAC;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,yBAAyB;IACzB,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAC/F;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,SAAS,CAmJ/E"}

package/dist/lifecycle.js

@@ -0,0 +1,160 @@
+/**
+ * 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.
+ */
+/**
+ * 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 = {}) {
+    const startHooks = [];
+    const stopHooks = [];
+    const reloadHooks = [];
+    const installSignalHandlers = options.installSignalHandlers ?? true;
+    const log = options.log ??
+        (() => {
+            /* default: silent */
+        });
+    let status = 'idle';
+    let startedAt;
+    let stoppedAt;
+    let lastError;
+    let stopPromise;
+    let signalHandlersInstalled = false;
+    const installHandlers = (lifecycle) => {
+        if (signalHandlersInstalled || !installSignalHandlers)
+            return;
+        signalHandlersInstalled = true;
+        const handle = (reason) => () => {
+            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 = {
+        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 = '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() {
+            const report = {
+                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;
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

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

package/dist/logger.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 { type Logger as PinoLogger } 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 declare function createLogger(options?: CreateLoggerOptions): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAa,EAAE,KAAK,MAAM,IAAI,UAAU,EAAsB,MAAM,MAAM,CAAC;AAE3E,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1F,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,iFAAiF;AACjF,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC;AAEhC;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAmBtE"}