@appydave/core 0.1.0

package/dist/logger.js

@@ -0,0 +1,30 @@
+/**
+ * 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 from 'pino';
+/**
+ * Create a configured Pino logger. Convenient defaults; opts in to pretty
+ * printing only when explicitly requested.
+ */
+export function createLogger(options = {}) {
+    const level = options.level ?? process.env['LOG_LEVEL'] ?? 'info';
+    const baseOptions = {
+        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);
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,IAAuD,MAAM,MAAM,CAAC;AAqB3E;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,UAA+B,EAAE;IAC5D,MAAM,KAAK,GAAa,OAAO,CAAC,KAAK,IAAK,OAAO,CAAC,GAAG,CAAC,WAAW,CAAc,IAAI,MAAM,CAAC;IAC1F,MAAM,WAAW,GAAkB;QACjC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,UAAU;QAChC,KAAK;QACL,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC;IAEF,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC;YACV,GAAG,WAAW;YACd,SAAS,EAAE;gBACT,MAAM,EAAE,aAAa;gBACrB,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,cAAc,EAAE;aAC3D;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC;AAC3B,CAAC"}

package/dist/serial-queue.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare class SerialQueue {
+    private tail;
+    private pendingCount;
+    /**
+     * 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>;
+    /**
+     * Resolve once the queue has fully drained (no pending tasks).
+     */
+    drain(): Promise<void>;
+    /**
+     * Number of tasks currently queued or running.
+     */
+    get size(): number;
+}
+//# sourceMappingURL=serial-queue.d.ts.map

package/dist/serial-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial-queue.d.ts","sourceRoot":"","sources":["../src/serial-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,IAAI,CAAuC;IACnD,OAAO,CAAC,YAAY,CAAK;IAEzB;;;;;;OAMG;IACH,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAiBlD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/serial-queue.js

@@ -0,0 +1,49 @@
+/**
+ * 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 {
+    tail = Promise.resolve();
+    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(task) {
+        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;
+    }
+    /**
+     * Resolve once the queue has fully drained (no pending tasks).
+     */
+    async drain() {
+        while (this.pendingCount > 0) {
+            await this.tail;
+        }
+    }
+    /**
+     * Number of tasks currently queued or running.
+     */
+    get size() {
+        return this.pendingCount;
+    }
+}
+//# sourceMappingURL=serial-queue.js.map

package/dist/serial-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial-queue.js","sourceRoot":"","sources":["../src/serial-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,OAAO,WAAW;IACd,IAAI,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3C,YAAY,GAAG,CAAC,CAAC;IAEzB;;;;;;OAMG;IACH,OAAO,CAAI,IAA0B;QACnC,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC;QACvB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CACxB,GAAG,EAAE,CAAC,IAAI,EAAE,EACZ,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,mDAAmD;SACjE,CAAC;QACF,yEAAyE;QACzE,4EAA4E;QAC5E,0EAA0E;QAC1E,mBAAmB;QACnB,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;YACnD,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC;QACpB,OAAO,GAAiB,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,OAAO,IAAI,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,CAAC,IAAI,CAAC;QAClB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;CACF"}

package/dist/store.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 { type AtomicWriteOptions } from './atomic-write.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 declare function createStore<T>(options: StoreOptions<T>): Store<T>;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAe,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAGzE,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,QAAQ,EAAE,CAAC,CAAC;IACZ,+DAA+D;IAC/D,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,4EAA4E;IAC5E,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IACnB,8DAA8D;IAC9D,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC3C;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAqCjE"}

package/dist/store.js

@@ -0,0 +1,51 @@
+/**
+ * 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 } from './atomic-write.js';
+import { SerialQueue } from './serial-queue.js';
+export function createStore(options) {
+    const { path, defaults, write: writeOptions, space = 2 } = options;
+    const queue = new SerialQueue();
+    async function readRaw() {
+        try {
+            const text = await fs.readFile(path, 'utf8');
+            return JSON.parse(text);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                // Fresh clone so callers can't mutate the shared defaults object.
+                return structuredClone(defaults);
+            }
+            throw err;
+        }
+    }
+    async function writeRaw(value) {
+        await atomicWrite(path, JSON.stringify(value, null, space), writeOptions);
+    }
+    return {
+        read() {
+            return queue.enqueue(readRaw);
+        },
+        write(value) {
+            return queue.enqueue(() => writeRaw(value));
+        },
+        update(fn) {
+            return queue.enqueue(async () => {
+                const current = await readRaw();
+                const next = fn(current);
+                await writeRaw(next);
+                return next;
+            });
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAsBhD,MAAM,UAAU,WAAW,CAAI,OAAwB;IACrD,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC;IACnE,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC;IAEhC,KAAK,UAAU,OAAO;QACpB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC7C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;QAC/B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACrD,kEAAkE;gBAClE,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;YACnC,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,KAAK,UAAU,QAAQ,CAAC,KAAQ;QAC9B,MAAM,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO;QACL,IAAI;YACF,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;QACD,KAAK,CAAC,KAAQ;YACZ,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9C,CAAC;QACD,MAAM,CAAC,EAAqB;YAC1B,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE;gBAC9B,MAAM,OAAO,GAAG,MAAM,OAAO,EAAE,CAAC;gBAChC,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC;gBACzB,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;gBACrB,OAAO,IAAI,CAAC;YACd,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@appydave/core",
+  "version": "0.1.0",
+  "description": "AppyDave shared foundation primitives — Lifecycle, ConfigLoader, Logger, atomicWrite, SerialQueue, Store. Neutral (no product prefix); reused by AppyStack, AppySentinel, AppyTron.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./lifecycle": {
+      "types": "./dist/lifecycle.d.ts",
+      "import": "./dist/lifecycle.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./logger": {
+      "types": "./dist/logger.d.ts",
+      "import": "./dist/logger.js"
+    },
+    "./atomic-write": {
+      "types": "./dist/atomic-write.d.ts",
+      "import": "./dist/atomic-write.js"
+    },
+    "./serial-queue": {
+      "types": "./dist/serial-queue.d.ts",
+      "import": "./dist/serial-queue.js"
+    },
+    "./store": {
+      "types": "./dist/store.d.ts",
+      "import": "./dist/store.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "echo 'core lint stub' && exit 0",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "pino": "^9.5.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "keywords": [
+    "appydave",
+    "foundation",
+    "core",
+    "lifecycle",
+    "config",
+    "logger",
+    "store",
+    "atomic-write",
+    "bun",
+    "node"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appydave/foundation.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/appydave/foundation#readme",
+  "author": "David Cruwys",
+  "license": "MIT"
+}

package/src/atomic-write.ts

@@ -0,0 +1,81 @@
+/**
+ * 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';
+
+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 async function atomicWrite(
+  path: string,
+  content: string | Uint8Array,
+  options: AtomicWriteOptions = {}
+): Promise<void> {
+  const dir = dirname(path);
+  const base = basename(path);
+  const suffix = randomBytes(6).toString('hex');
+  const tmp = join(dir, `.${base}.${suffix}.tmp`);
+
+  let handle: fs.FileHandle | undefined;
+  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;
+  }
+}

package/src/config.ts

@@ -0,0 +1,186 @@
+/**
+ * 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';
+
+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;
+}
+
+function setPath(target: Record<string, unknown>, path: string, value: unknown): void {
+  const segments = path.split('.');
+  let node: Record<string, unknown> = 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: Record<string, unknown> = {};
+      node[seg] = fresh;
+      node = fresh;
+    } else {
+      node = next as Record<string, unknown>;
+    }
+  }
+  node[segments[segments.length - 1]!] = value;
+}
+
+/** Deep merge — plain objects only, arrays replace. */
+function deepMerge(
+  base: Record<string, unknown>,
+  overlay: Record<string, unknown>
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...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 as Record<string, unknown>,
+        value as Record<string, unknown>
+      );
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+async function readJsonFile(path: string): Promise<Record<string, unknown> | undefined> {
+  try {
+    const raw = await fs.readFile(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+    throw new Error(`config file ${path} must contain a JSON object`);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).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<T>(options: ConfigLoaderOptions<T>): ConfigLoader<T> {
+  const handlers = new Set<(config: T) => void>();
+  let lastConfig: T | undefined;
+  const envSource = options.envSource ?? process.env;
+
+  const buildOnce = async (): Promise<T> => {
+    let merged: Record<string, unknown> = (options.defaults ?? {}) as Record<string, unknown>;
+
+    if (options.filePath) {
+      const fileLayer = await readJsonFile(options.filePath);
+      if (fileLayer) merged = deepMerge(merged, fileLayer);
+    }
+
+    if (options.env) {
+      const envOverlay: Record<string, unknown> = {};
+      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 };

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * @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';