thatcher 1.0.4

package/src/lib/hook-engine.js

@@ -0,0 +1,169 @@
+/**
+ * Hook Engine - Event system for plugins and lifecycle hooks
+ * Fires events like 'create:entity:after', 'update:entity:before', etc.
+ */
+
+export class HookEngine {
+  constructor() {
+    this.hooks = new Map();
+  }
+
+  /**
+   * Register a hook handler
+   * @param {string} name - Event name
+   * @param {Function} callback - Handler function
+   * @param {object} options - { priority, once }
+   */
+  register(name, callback, options = {}) {
+    const { priority = 0, once = false } = options;
+    if (!this.hooks.has(name)) this.hooks.set(name, []);
+    const list = this.hooks.get(name);
+    list.push({ callback, priority, once });
+    list.sort((a, b) => b.priority - a.priority);
+    return this;
+  }
+
+  /**
+   * Alias for register
+   */
+  on(name, callback, options = {}) {
+    return this.register(name, callback, options);
+  }
+
+  /**
+   * Unregister a hook handler
+   */
+  off(name, callback) {
+    const list = this.hooks.get(name);
+    if (!list) return this;
+    const idx = list.findIndex(h => h.callback === callback);
+    if (idx !== -1) list.splice(idx, 1);
+    if (list.length === 0) this.hooks.delete(name);
+    return this;
+  }
+
+  /**
+   * Execute all handlers for an event (fire-and-forget style)
+   * @param {string} name
+   * @param {object} data
+   * @param {object} options - { fallthrough: true to continue on error }
+   * @returns {Promise<{success: boolean, data, errors}>}
+   */
+  async execute(name, data = {}, options = {}) {
+    const { fallthrough = true } = options;
+    const hooks = this.hooks.get(name);
+    if (!hooks || hooks.length === 0) return { success: true, data };
+    const errors = [];
+
+    for (const hook of [...hooks]) {
+      try {
+        await hook.callback(data);
+        if (hook.once) this.off(name, hook.callback);
+      } catch (error) {
+        console.error(`[HookEngine] Hook "${name}" error:`, error.message);
+        errors.push(error);
+        if (!fallthrough) throw error;
+      }
+    }
+
+    return { success: errors.length === 0, data, errors };
+  }
+
+  /**
+   * Pipe data through transformation hooks
+   * @param {string} name
+   * @param {any} data
+   * @returns {Promise<any>}
+   */
+  async pipe(name, data = {}) {
+    const hooks = this.hooks.get(name);
+    if (!hooks || hooks.length === 0) return data;
+
+    let current = data;
+    for (const hook of [...hooks]) {
+      try {
+        const result = await hook.callback(current);
+        if (result !== undefined) current = result;
+        if (hook.once) this.off(name, hook.callback);
+      } catch (error) {
+        console.error(`[HookEngine] Pipe hook "${name}" error:`, error.message);
+      }
+    }
+    return current;
+  }
+
+  /**
+   * Get all listeners for an event
+   * @param {string} name
+   * @returns {Array}
+   */
+  listeners(name) {
+    return this.hooks.has(name) ? Array.from(this.hooks.get(name)) : [];
+  }
+
+  /**
+   * Get statistics
+   * @returns {object} Map of event -> count
+   */
+  stats() {
+    const result = {};
+    for (const [name, list] of this.hooks.entries()) {
+      result[name] = list.length;
+    }
+    return result;
+  }
+
+  /**
+   * Clear all hooks
+   */
+  clear() {
+    this.hooks.clear();
+  }
+}
+
+// Global singleton
+export const hookEngine = new HookEngine();
+
+/**
+ * Execute hook (convenience function)
+ */
+export async function executeHook(name, data = {}, options = {}) {
+  return hookEngine.execute(name, data, options);
+}
+
+/**
+ * Pipe through hooks
+ */
+export async function pipeHook(name, data = {}) {
+  return hookEngine.pipe(name, data);
+}
+
+/**
+ * Register hook debug exposure
+ */
+function registerHookDebug() {
+  if (globalThis.__debug__) {
+    globalThis.__debug__.expose('hooks', {
+      stats: () => hookEngine.stats(),
+      engine: hookEngine,
+    }, 'HookEngine registry');
+  }
+}
+
+// Auto-register when __debug__ becomes available
+if (globalThis.__debug__) {
+  registerHookDebug();
+} else {
+  const origDesc = Object.getOwnPropertyDescriptor(globalThis, '__debug__');
+  Object.defineProperty(globalThis, '__debug__', {
+    configurable: true,
+    set(v) {
+      Object.defineProperty(globalThis, '__debug__', { value: v, configurable: true, writable: true });
+      registerHookDebug();
+      if (origDesc?.set) origDesc.set.call(this, v);
+    },
+    get() { return undefined; }
+  });
+}
+
+export default hookEngine;

package/src/lib/hot-reload/cache-invalidator.js

@@ -0,0 +1,115 @@
+import path from 'path';
+import { createRequire } from 'module';
+import { DirectoryWatcher } from './directory-watcher.js';
+
+const _require = createRequire(import.meta.url);
+
+export class CacheInvalidator {
+  constructor() {
+    this.invalidated = new Set();
+    this.watcher = null;
+    this.onInvalidate = null;
+  }
+
+  startWatching(rootDir) {
+    if (this.watcher) return this;
+    this.watcher = new DirectoryWatcher({ rootDir });
+    this.watcher.on('change', (event) => {
+      const count = this.invalidateByFilePath(event.path);
+      if (count > 0 && this.onInvalidate) {
+        this.onInvalidate(event.path, count);
+      }
+    });
+    this.watcher.start();
+    return this;
+  }
+
+  stopWatching() {
+    if (this.watcher) {
+      this.watcher.stop();
+      this.watcher = null;
+    }
+    return this;
+  }
+
+  invalidateByFilePath(filePath) {
+    const normalized = path.resolve(filePath);
+    let count = 0;
+    if (typeof _require.cache === 'undefined') return count;
+    for (const modulePath of Object.keys(_require.cache)) {
+      if (modulePath === normalized || modulePath.startsWith(normalized)) {
+        this._invalidateModule(modulePath);
+        this.invalidated.add(modulePath);
+        count++;
+      }
+    }
+    return count;
+  }
+
+  invalidate(modulePath) {
+    try {
+      const resolved = _require.resolve(modulePath);
+      if (_require.cache[resolved]) {
+        this._invalidateModule(resolved);
+        this.invalidated.add(resolved);
+        return true;
+      }
+    } catch (_) {}
+    return false;
+  }
+
+  invalidatePattern(pattern) {
+    const regex = new RegExp(pattern);
+    let count = 0;
+    if (typeof _require.cache === 'undefined') return count;
+    for (const modulePath of Object.keys(_require.cache)) {
+      if (regex.test(modulePath)) {
+        this._invalidateModule(modulePath);
+        this.invalidated.add(modulePath);
+        count++;
+      }
+    }
+    return count;
+  }
+
+  invalidateAll(excludePattern = /node_modules/) {
+    let count = 0;
+    if (typeof _require.cache === 'undefined') return count;
+    for (const modulePath of Object.keys(_require.cache)) {
+      if (excludePattern && excludePattern.test(modulePath)) continue;
+      this._invalidateModule(modulePath);
+      this.invalidated.add(modulePath);
+      count++;
+    }
+    return count;
+  }
+
+  _invalidateModule(modulePath) {
+    if (typeof _require.cache === 'undefined') return;
+    const mod = _require.cache[modulePath];
+    if (!mod) return;
+    if (mod.parent) {
+      const index = mod.parent.children.indexOf(mod);
+      if (index !== -1) mod.parent.children.splice(index, 1);
+    }
+    for (const child of mod.children || []) {
+      this._invalidateModule(child.id);
+    }
+    delete _require.cache[modulePath];
+  }
+
+  getStats() {
+    return {
+      totalCached: typeof _require.cache !== 'undefined' ? Object.keys(_require.cache).length : 0,
+      invalidated: this.invalidated.size,
+      watching: !!this.watcher,
+      watcherStats: this.watcher ? this.watcher.getStats() : null
+    };
+  }
+
+  clearStats() {
+    this.invalidated.clear();
+  }
+}
+
+export const globalInvalidator = new CacheInvalidator();

package/src/lib/hot-reload/checkpoint.js

@@ -0,0 +1,95 @@
+import fs from 'fs';
+import path from 'path';
+
+export class CheckpointManager {
+  constructor(options = {}) {
+    this.checkpointDir = options.checkpointDir || path.join(process.cwd(), 'data', 'checkpoints');
+    this.maxCheckpoints = options.maxCheckpoints || 10;
+    this.checkpoints = new Map();
+
+    if (!fs.existsSync(this.checkpointDir)) {
+      fs.mkdirSync(this.checkpointDir, { recursive: true });
+    }
+  }
+
+  async save(key, state) {
+    const checkpoint = { key, state, timestamp: Date.now(), version: 1 };
+    this.checkpoints.set(key, checkpoint);
+    const filename = this._getFilename(key);
+    const filepath = path.join(this.checkpointDir, filename);
+
+    try {
+      await fs.promises.writeFile(filepath, JSON.stringify(checkpoint, null, 2), 'utf-8');
+      await this._pruneOldCheckpoints(key);
+      return true;
+    } catch (err) {
+      console.error(`[Checkpoint] Failed to save ${key}:`, err);
+      return false;
+    }
+  }
+
+  async load(key) {
+    if (this.checkpoints.has(key)) {
+      return this.checkpoints.get(key).state;
+    }
+    const files = await this._getCheckpointFiles(key);
+    if (files.length === 0) return null;
+    const latest = files[files.length - 1];
+    const filepath = path.join(this.checkpointDir, latest);
+    try {
+      const data = await fs.promises.readFile(filepath, 'utf-8');
+      const checkpoint = JSON.parse(data);
+      this.checkpoints.set(key, checkpoint);
+      return checkpoint.state;
+    } catch (err) {
+      console.error(`[Checkpoint] Failed to load ${key}:`, err);
+      return null;
+    }
+  }
+
+  async restore(key, defaultState = null) {
+    const state = await this.load(key);
+    return state !== null ? state : defaultState;
+  }
+
+  async clear(key) {
+    this.checkpoints.delete(key);
+    const files = await this._getCheckpointFiles(key);
+    await Promise.all(files.map(f => fs.promises.unlink(path.join(this.checkpointDir, f))));
+  }
+
+  async clearAll() {
+    this.checkpoints.clear();
+    const files = await fs.promises.readdir(this.checkpointDir);
+    await Promise.all(files.map(f => fs.promises.unlink(path.join(this.checkpointDir, f))));
+  }
+
+  _getFilename(key) {
+    const safe = key.replace(/[^a-z0-9-_]/gi, '_');
+    return `${safe}_${Date.now()}.json`;
+  }
+
+  async _getCheckpointFiles(key) {
+    const safe = key.replace(/[^a-z0-9-_]/gi, '_');
+    const prefix = `${safe}_`;
+    const files = await fs.promises.readdir(this.checkpointDir);
+    return files.filter(f => f.startsWith(prefix) && f.endsWith('.json')).sort();
+  }
+
+  async _pruneOldCheckpoints(key) {
+    const files = await this._getCheckpointFiles(key);
+    if (files.length <= this.maxCheckpoints) return;
+    const toDelete = files.slice(0, files.length - this.maxCheckpoints);
+    await Promise.all(toDelete.map(f => fs.promises.unlink(path.join(this.checkpointDir, f))));
+  }
+
+  getStats() {
+    return {
+      inMemory: this.checkpoints.size,
+      checkpointDir: this.checkpointDir,
+      maxCheckpoints: this.maxCheckpoints
+    };
+  }
+}
+
+export const globalCheckpoint = new CheckpointManager();

package/src/lib/hot-reload/debug-exposure.js

@@ -0,0 +1,67 @@
+export class DebugExposure {
+  constructor() {
+    this.exposed = new Map();
+    globalThis.__debug__ = this;
+  }
+
+  expose(key, value, description = '') {
+    this.exposed.set(key, {
+      value,
+      description,
+      exposedAt: new Date().toISOString()
+    });
+    if (!globalThis[key]) globalThis[key] = value;
+    return value;
+  }
+
+  get(key) {
+    const entry = this.exposed.get(key);
+    return entry ? entry.value : undefined;
+  }
+
+  list() {
+    const list = [];
+    for (const [key, entry] of this.exposed.entries()) {
+      list.push({
+        key,
+        description: entry.description,
+        exposedAt: entry.exposedAt,
+        type: typeof entry.value
+      });
+    }
+    return list;
+  }
+
+  inspect(key) {
+    const entry = this.exposed.get(key);
+    if (!entry) return null;
+    const value = entry.value;
+    const info = {
+      key,
+      description: entry.description,
+      exposedAt: entry.exposedAt,
+      type: typeof value,
+      constructor: value?.constructor?.name
+    };
+    if (typeof value === 'object' && value !== null) {
+      if (typeof value.getStats === 'function') info.stats = value.getStats();
+      if (typeof value.getState === 'function') info.state = value.getState();
+      info.keys = Object.keys(value);
+    }
+    return info;
+  }
+
+  remove(key) {
+    this.exposed.delete(key);
+    if (globalThis[key]) delete globalThis[key];
+  }
+
+  clear() {
+    for (const key of this.exposed.keys()) {
+      this.remove(key);
+    }
+  }
+}
+
+export const globalDebug = new DebugExposure();
+export const expose = globalDebug.expose.bind(globalDebug);

package/src/lib/hot-reload/directory-watcher.js

@@ -0,0 +1,96 @@
+import fs from 'fs';
+import path from 'path';
+import { EventEmitter } from 'events';
+
+export class DirectoryWatcher extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.rootDir = options.rootDir || path.join(process.cwd(), 'src');
+    this.debounceMs = options.debounceMs || 100;
+    this.extensions = options.extensions || ['.js', '.jsx', '.ts', '.tsx'];
+    this.exclude = options.exclude || ['node_modules', '.git', 'migration'];
+    this.watchers = new Map();
+    this.debounceTimers = new Map();
+    this.running = false;
+    this.stats = { totalWatched: 0, eventsReceived: 0, invalidations: 0 };
+  }
+
+  start() {
+    if (this.running) return this;
+    this.running = true;
+    this._watchRecursive(this.rootDir);
+    this.emit('started', { directories: this.watchers.size });
+    return this;
+  }
+
+  stop() {
+    this.running = false;
+    for (const [, watcher] of this.watchers.entries()) {
+      try { watcher.close(); } catch (_) {}
+    }
+    this.watchers.clear();
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.debounceTimers.clear();
+    this.emit('stopped');
+    return this;
+  }
+
+  _watchRecursive(dir) {
+    if (!this.running) return;
+    if (!fs.existsSync(dir)) return;
+
+    try {
+      const watcher = fs.watch(dir, { persistent: false }, (eventType, filename) => {
+        if (!filename) return;
+        this._handleChange(dir, filename, eventType);
+      });
+      watcher.on('error', (err) => {
+        this.emit('watchError', { dir, error: err });
+        this.watchers.delete(dir);
+      });
+      this.watchers.set(dir, watcher);
+      this.stats.totalWatched++;
+    } catch (err) {
+      this.emit('watchError', { dir, error: err });
+      return;
+    }
+
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (this.exclude.includes(entry.name)) continue;
+        if (entry.name.startsWith('.')) continue;
+        this._watchRecursive(path.join(dir, entry.name));
+      }
+    } catch (_) {}
+  }
+
+  _handleChange(dir, filename, eventType) {
+    const ext = path.extname(filename);
+    if (!this.extensions.includes(ext)) return;
+    this.stats.eventsReceived++;
+    const fullPath = path.join(dir, filename);
+    if (this.debounceTimers.has(fullPath)) {
+      clearTimeout(this.debounceTimers.get(fullPath));
+    }
+    this.debounceTimers.set(fullPath, setTimeout(() => {
+      this.debounceTimers.delete(fullPath);
+      this.stats.invalidations++;
+      this.emit('change', { path: fullPath, dir, filename, eventType, timestamp: Date.now() });
+    }, this.debounceMs));
+  }
+
+  getStats() {
+    return {
+      running: this.running,
+      directoriesWatched: this.watchers.size,
+      pendingDebounce: this.debounceTimers.size,
+      ...this.stats
+    };
+  }
+}
+
+export const globalWatcher = new DirectoryWatcher();

package/src/lib/hot-reload/index.js

@@ -0,0 +1,50 @@
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+
+const promiseContainerMod = require('./promise-container.js');
+export { Mutex, MutexManager, globalManager } from './mutex.js';
+import { Supervisor, SupervisorTree, globalTree } from './supervisor.js';
+const checkpointMod = require('./checkpoint.js');
+const timeoutMod = require('./timeout-wrapper.js');
+const safeErrorMod = require('./safe-error.js');
+const cacheInvalidatorMod = require('./cache-invalidator.js');
+const directoryWatcherMod = require('./directory-watcher.js');
+const routeWrapperMod = require('./route-wrapper.js');
+const debugExposureMod = require('./debug-exposure.js');
+
+const { PromiseContainer, globalContainer, contain } = promiseContainerMod;
+
+const { CheckpointManager, globalCheckpoint } = checkpointMod;
+const { TimeoutError, withTimeout, withAbortableTimeout, retry } = timeoutMod;
+const { safeError, safeStringify } = safeErrorMod;
+const { CacheInvalidator, globalInvalidator } = cacheInvalidatorMod;
+const { DirectoryWatcher, globalWatcher } = directoryWatcherMod;
+const { wrapRouteHandler, wrapRouteHandlers } = routeWrapperMod;
+const { DebugExposure, globalDebug, expose } = debugExposureMod;
+
+expose('hotReload', {
+  promises: globalContainer,
+  mutexes: globalManager,
+  supervisors: globalTree,
+  checkpoints: globalCheckpoint,
+  cache: globalInvalidator,
+  watcher: globalWatcher,
+  debug: globalDebug
+}, 'Hot reload infrastructure');
+
+export {
+  PromiseContainer, globalContainer, contain,
+  Supervisor, SupervisorTree, globalTree,
+  CheckpointManager, globalCheckpoint,
+  TimeoutError, withTimeout, withAbortableTimeout, retry,
+  safeError, safeStringify,
+  CacheInvalidator, globalInvalidator,
+  DirectoryWatcher, globalWatcher,
+  wrapRouteHandler, wrapRouteHandlers,
+  DebugExposure, globalDebug, expose
+};

package/src/lib/hot-reload/mutex.js

@@ -0,0 +1,75 @@
+export class Mutex {
+  constructor(name = 'anonymous') {
+    this.name = name;
+    this.locked = false;
+    this.queue = [];
+  }
+
+  async acquire() {
+    if (!this.locked) {
+      this.locked = true;
+      return () => this.release();
+    }
+
+    return new Promise(resolve => {
+      this.queue.push(resolve);
+    });
+  }
+
+  release() {
+    if (this.queue.length > 0) {
+      const next = this.queue.shift();
+      next(() => this.release());
+    } else {
+      this.locked = false;
+    }
+  }
+
+  async runExclusive(fn) {
+    const release = await this.acquire();
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+
+  isLocked() {
+    return this.locked;
+  }
+
+  getQueueSize() {
+    return this.queue.length;
+  }
+}
+
+export class MutexManager {
+  constructor() {
+    this.mutexes = new Map();
+  }
+
+  get(key) {
+    if (!this.mutexes.has(key)) {
+      this.mutexes.set(key, new Mutex(key));
+    }
+    return this.mutexes.get(key);
+  }
+
+  async lock(key, fn) {
+    const mutex = this.get(key);
+    return mutex.runExclusive(fn);
+  }
+
+  getStats() {
+    const stats = {};
+    for (const [key, mutex] of this.mutexes.entries()) {
+      stats[key] = {
+        locked: mutex.isLocked(),
+        queueSize: mutex.getQueueSize()
+      };
+    }
+    return stats;
+  }
+}
+
+export const globalManager = new MutexManager();