thatcher 1.0.41 → 1.0.43

package/src/lib/{busybase-lucia-adapter.js → busybase/lucia-adapter.js}

@@ -7,7 +7,7 @@
  * receives back; busybase stores it as an epoch-ms number, so we convert at the boundary.
  */
 
-import { list, get, create, update, remove } from '@/lib/busybase-store.js';
+import { list, get, create, update, remove } from '@/lib/busybase/store.js';
 
 const SESSION = 'sessions';
 const USER = 'users';

package/src/lib/{busybase-store.js → busybase/store.js}

@@ -14,9 +14,9 @@
  * Requires Bun (busybase embedded uses Bun.password + the vectordb native binding).
  */
 
-import { getSpec } from '../config/spec-helpers.js';
-import { RECORD_STATUS } from '../config/constants.js';
-import { genId, now } from './id-helpers.js';
+import { getSpec } from '../../config/spec-helpers.js';
+import { RECORD_STATUS } from '../../config/constants.js';
+import { genId, now } from '../id-helpers.js';
 
 let _client = null;
 

package/src/lib/config-generator-engine.js

@@ -1,5 +1,17 @@
 // Adapted from moonlanding/src/lib/config-generator-engine.js
-
+//
+// Config/spec generation layer -- a genuinely SEPARATE concern from
+// workflow-engine.js / xstate-workflow-engine.js. This file loads+validates
+// the master YAML config and generates cached, deep-frozen derived specs
+// (entity field specs via generateEntitySpec, roles, permission templates,
+// status enums, theme, thresholds, automation jobs). It does not itself
+// validate or execute a workflow transition -- both workflow engines simply
+// READ the `workflows` config section through this engine's
+// getConfigEngineSync().getConfig(). By far the most widely consumed of the
+// three files (16 importers repo-wide across services/lib/ui/app-api routes
+// as of this writing, vs. workflow-engine.js's 2 and
+// xstate-workflow-engine.js's 2 debug/test-only importers) -- this is live,
+// central infrastructure, not a candidate for deprecation.
 import { load as yamlLoad } from 'js-yaml';
 import { LRUCache, deepFreeze, deepClone, recursiveResolve } from './config-helpers.js';
 import { generateFieldsFromOverrides, ensureFieldLabels } from './config-field-helpers.js';

package/src/lib/crud-action-helpers.js

@@ -1,4 +1,4 @@
-import { AppError } from '@/lib/error-handler';
+import { AppError } from '@/lib/errors';
 import { HTTP } from '@/config/constants';
 import { now } from '@/lib/id-helpers';
 

package/src/lib/crud-handlers.js

@@ -1,18 +1,18 @@
 import { createLogger } from './logger.js';
-import { get, listWithPagination, searchWithPagination, create, update, remove } from './busybase-store.js';
+import { get, listWithPagination, searchWithPagination, create, update, remove } from './busybase/store.js';
 
 const log = createLogger('[CRUD]');
-import { validateEntity, validateUpdate, sanitizeData } from './validate.js';
+import { validateEntity, validateUpdate, sanitizeData } from './validation/index.js';
 import { requirePermission, getSessionToken } from './auth-middleware.js';
 import { executeHook } from './hook-engine.js';
-import { AppError, NotFoundError, ValidationError } from './error-handler.js';
+import { AppError, NotFoundError, ValidationError } from './errors/index.js';
 import { ok, created, paginated, noContent, error } from './response-formatter.js';
 import { HTTP } from '../config/constants.js';
 import { permissionService } from '../services/permission.service.js';
 import { parse as parseQuery } from './query-string-adapter.js';
 import { now } from './id-helpers.js';
 import { getConfigEngineSync } from './config-generator-engine.js';
-import { logAction } from './busybase-audit.js';
+import { logAction } from './busybase/audit.js';
 
 export function createCrudHandlers(entityName, spec) {
   if (!spec) {

package/src/lib/email-sender.js

@@ -2,7 +2,7 @@ import { createLogger } from './logger.js';
 import { now, genId } from '@/lib/id-helpers';
 
 const log = createLogger('[Email]');
-import { list, update, create } from '@/lib/busybase-store';
+import { list, update, create } from '@/lib/busybase/store';
 import { sendEmail } from '@/adapters/google-gmail';
 import { EMAIL_STATUS } from '@/config/constants';
 import { config } from '@/config/env';

package/src/lib/errors/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './wrap.js';
+export * from './recovery.js';

package/src/lib/{error-recovery.js → errors/recovery.js}

@@ -1,10 +1,120 @@
-import { createLogger } from './logger.js';
-import { retryWithBackoff, withCircuitBreaker, checkpoint, restoreCheckpoint, logRecovery } from '@/lib/error-resilience';
+import { createLogger } from '../logger.js';
+import { retryWithBackoff } from './wrap.js';
+import { normalizeError, AppError } from './types.js';
+import { HTTP } from '../../config/constants.js';
 
 const log = createLogger('[Recovery]');
-import { normalizeError, AppError } from '@/lib/error-handler';
-import { HTTP } from '@/config/constants';
+const resilienceLog = createLogger('[Resilience]');
+
+// ---------------------------------------------------------------------------
+// Ported from error-resilience.js — circuit breaker + checkpoint primitives.
+// These are used directly, and also passed as strategies into withRecovery()
+// below rather than living as a second parallel wrapper module.
+// ---------------------------------------------------------------------------
+const errorState = { errors: [], circuitBreakers: new Map(), checkpoints: new Map() };
+
+export function createCircuitBreaker(name, options = {}) {
+  const { threshold = 5, resetTimeout = 30000 } = options;
+
+  if (!errorState.circuitBreakers.has(name)) {
+    errorState.circuitBreakers.set(name, {
+      failures: 0,
+      state: 'closed',
+      lastFailure: null,
+      nextAttempt: null,
+      threshold,
+      resetTimeout
+    });
+  }
+
+  return errorState.circuitBreakers.get(name);
+}
+
+export async function withCircuitBreaker(name, fn, options = {}) {
+  const breaker = createCircuitBreaker(name, options);
+
+  if (breaker.state === 'open') {
+    const now = Date.now();
+    if (breaker.nextAttempt && now < breaker.nextAttempt) {
+      throw new AppError(`Service unavailable: ${name}`, 'CIRCUIT_OPEN', HTTP.SERVICE_UNAVAILABLE, { nextAttempt: breaker.nextAttempt });
+    }
+    breaker.state = 'half-open';
+  }
+
+  try {
+    const result = await fn();
+    if (breaker.state === 'half-open') {
+    }
+    breaker.failures = 0;
+    breaker.state = 'closed';
+    return result;
+  } catch (error) {
+    breaker.failures++;
+    breaker.lastFailure = Date.now();
+
+    if (breaker.failures >= breaker.threshold) {
+      breaker.state = 'open';
+      breaker.nextAttempt = Date.now() + breaker.resetTimeout;
+      resilienceLog.error(`circuit ${name} opened after ${breaker.failures} failures`);
+    }
+
+    throw error;
+  }
+}
+
+export function checkpoint(name, state) {
+  errorState.checkpoints.set(name, {
+    state: JSON.parse(JSON.stringify(state)),
+    timestamp: Date.now()
+  });
+}
+
+export function restoreCheckpoint(name) {
+  const cp = errorState.checkpoints.get(name);
+  if (cp) {
+    return cp.state;
+  }
+  return null;
+}
+
+export function logRecovery(context, action) {
+  errorState.errors.push({
+    type: 'recovery',
+    context,
+    action,
+    timestamp: new Date().toISOString()
+  });
+  if (errorState.errors.length > 1000) errorState.errors.shift();
+}
+
+export function getErrorStats() {
+  const recent = errorState.errors.slice(-100);
+  const byType = {};
+
+  for (const err of recent) {
+    byType[err.type || 'error'] = (byType[err.type || 'error'] || 0) + 1;
+  }
+
+  return {
+    total: errorState.errors.length,
+    recent: recent.length,
+    byType,
+    circuitBreakers: Array.from(errorState.circuitBreakers.entries()).map(([name, state]) => ({
+      name,
+      state: state.state,
+      failures: state.failures,
+      lastFailure: state.lastFailure ? new Date(state.lastFailure).toISOString() : null
+    })),
+    checkpoints: Array.from(errorState.checkpoints.keys())
+  };
+}
 
+// ---------------------------------------------------------------------------
+// Ported from error-recovery.js — supervisor / degraded-mode / health-check
+// strategies, now composed with the circuit-breaker + retry primitives above
+// (and wrap.js's retryWithBackoff) rather than importing a second sibling
+// wrapper module.
+// ---------------------------------------------------------------------------
 const recoveryState = { supervisors: new Map(), lastHealthCheck: null };
 
 export function createSupervisor(name, fn, options = {}) {
@@ -190,4 +300,10 @@ if (typeof global !== 'undefined') {
   global.getSupervisorStats = getSupervisorStats;
   global.supervise = supervise;
   global.healthCheck = healthCheck;
+  global.errorState = errorState;
+  global.getErrorStats = getErrorStats;
+  global.retryWithBackoff = retryWithBackoff;
+  global.withCircuitBreaker = withCircuitBreaker;
+  global.checkpoint = checkpoint;
+  global.restoreCheckpoint = restoreCheckpoint;
 }

package/src/lib/{error-handler.js → errors/types.js}

@@ -1,4 +1,4 @@
-import { createLogger } from './logger.js';
+import { createLogger } from '../logger.js';
 
 // AppError stays a real class (base error type; `instanceof AppError` works).
 export class AppError extends Error {

package/src/lib/errors/wrap.js

@@ -0,0 +1,225 @@
+import { AppError, normalizeError, createErrorLogger } from './types.js';
+import { apiError } from '../response-formatter.js';
+import { NextResponse } from '../next-shim.js';
+import { HTTP } from '../../config/constants.js';
+
+// ---------------------------------------------------------------------------
+// wrap(): the single configurable wrapper subsuming what with-error-handler.js
+// and api-error-wrapper.js used to do separately (timeout, retry-with-backoff,
+// logging) as options. Every call site keeps its original named import below —
+// each is now a thin adapter over wrap() with the exact defaults/behavior the
+// original standalone function had.
+// ---------------------------------------------------------------------------
+export function wrap(fn, options = {}) {
+  const {
+    retry = false,
+    retryOptions = { maxAttempts: 3 },
+    timeout = null,
+    log = null, // { context } to enable normalize+log-on-error, or null to skip
+  } = options;
+
+  return async (...args) => {
+    const operation = async () => {
+      if (!timeout) return fn(...args);
+
+      const timeoutPromise = new Promise((_, reject) =>
+        setTimeout(() => reject(new Error(`Request timeout after ${timeout}ms`)), timeout)
+      );
+
+      return await Promise.race([fn(...args), timeoutPromise]);
+    };
+
+    try {
+      if (retry) {
+        return await retryWithBackoff(operation, retryOptions);
+      }
+      return await operation();
+    } catch (e) {
+      if (log) {
+        const logger = createErrorLogger(log.context || '');
+        const error = normalizeError(e);
+        logger.error(error.code || 'ERROR', error.context || {});
+      }
+      throw e;
+    }
+  };
+}
+
+// retryWithBackoff lives here (not recovery.js) because wrap() itself needs it
+// with no circular dependency; recovery.js imports it back from here.
+export async function retryWithBackoff(fn, options = {}) {
+  const { maxAttempts = 3, delay = 1000, backoff = 2, context = {} } = options;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt === maxAttempts) {
+        const normalized = normalizeError(error);
+        throw normalized;
+      }
+
+      const waitTime = delay * Math.pow(backoff, attempt - 1);
+      await new Promise(resolve => setTimeout(resolve, waitTime));
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Ported from with-error-handler.js — identical behavior, same imports
+// (including the pre-existing `apiError` import from response-formatter.js,
+// which has no such export today; preserved as-is, not silently fixed, since
+// fixing it is a behavior change outside this consolidation's scope).
+// ---------------------------------------------------------------------------
+export const withErrorHandler = (handler, operation = 'Operation') => {
+  const logger = createErrorLogger(operation);
+
+  return async (...args) => {
+    try {
+      return await handler(...args);
+    } catch (e) {
+      const error = normalizeError(e);
+      logger.error(error.code, error.context);
+      return apiError(error);
+    }
+  };
+};
+
+export const withAsyncErrorHandler = (handler, context = '') => {
+  const logger = createErrorLogger(context);
+
+  return async (...args) => {
+    try {
+      return await handler(...args);
+    } catch (e) {
+      const error = e instanceof AppError ? e : new AppError(e.message, 'INTERNAL_ERROR', HTTP.INTERNAL_ERROR, { originalMessage: e.message });
+      logger.error(error.code || 'ERROR', error.context || {});
+      throw error;
+    }
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Ported from api-error-wrapper.js — identical behavior/defaults.
+// ---------------------------------------------------------------------------
+const apiLogger = createErrorLogger('API');
+
+export function wrapAPIRoute(handler, options = {}) {
+  const { retry = false, timeout = 30000, logErrors = true } = options;
+
+  return async (request, context) => {
+    const startTime = Date.now();
+    const url = new URL(request.url);
+
+    try {
+      const operation = async () => {
+        const timeoutPromise = new Promise((_, reject) =>
+          setTimeout(() => reject(new Error(`Request timeout after ${timeout}ms`)), timeout)
+        );
+
+        const handlerPromise = handler(request, context);
+
+        return await Promise.race([handlerPromise, timeoutPromise]);
+      };
+
+      const result = retry
+        ? await retryWithBackoff(operation, { maxAttempts: 3, context: { url: url.pathname } })
+        : await operation();
+
+      const duration = Date.now() - startTime;
+
+      if (duration > 1000) {
+        apiLogger.warn('Slow request', { url: url.pathname, duration });
+      }
+
+      return result;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      const normalized = normalizeError(error);
+
+      if (logErrors) {
+        apiLogger.error('Request failed', {
+          url: url.pathname,
+          method: request.method,
+          error: normalized.toJSON(),
+          duration
+        });
+      }
+
+      return NextResponse.json(
+        normalized.toJSON(),
+        {
+          status: normalized.statusCode,
+          headers: { 'Content-Type': 'application/json' }
+        }
+      );
+    }
+  };
+}
+
+export function wrapGETRoute(handler, options = {}) {
+  return wrapAPIRoute(handler, { ...options, retry: true });
+}
+
+export function wrapPOSTRoute(handler, options = {}) {
+  return wrapAPIRoute(handler, options);
+}
+
+export function wrapPUTRoute(handler, options = {}) {
+  return wrapAPIRoute(handler, options);
+}
+
+export function wrapDELETERoute(handler, options = {}) {
+  return wrapAPIRoute(handler, options);
+}
+
+export function createAPIHandler(handlers) {
+  const wrapped = {};
+
+  if (handlers.GET) wrapped.GET = wrapGETRoute(handlers.GET);
+  if (handlers.POST) wrapped.POST = wrapPOSTRoute(handlers.POST);
+  if (handlers.PUT) wrapped.PUT = wrapPUTRoute(handlers.PUT);
+  if (handlers.DELETE) wrapped.DELETE = wrapDELETERoute(handlers.DELETE);
+  if (handlers.PATCH) wrapped.PATCH = wrapAPIRoute(handlers.PATCH);
+  if (handlers.HEAD) wrapped.HEAD = wrapAPIRoute(handlers.HEAD);
+
+  return wrapped;
+}
+
+export async function safeJSONParse(text, fallback = null) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    apiLogger.warn('JSON parse failed', { error: error.message });
+    return fallback;
+  }
+}
+
+export async function safeReadBody(request, fallback = {}) {
+  try {
+    const text = await request.text();
+    return text ? await safeJSONParse(text, fallback) : fallback;
+  } catch (error) {
+    apiLogger.warn('Body read failed', { error: error.message });
+    return fallback;
+  }
+}
+
+export function validateRequired(data, fields) {
+  const missing = [];
+
+  for (const field of fields) {
+    if (data[field] === undefined || data[field] === null || data[field] === '') {
+      missing.push(field);
+    }
+  }
+
+  if (missing.length > 0) {
+    throw new Error(`Missing required fields: ${missing.join(', ')}`);
+  }
+}
+
+export function sanitizeError(error) {
+  const safe = String(error?.message || error || 'Unknown error');
+  return safe.substring(0, 500);
+}

package/src/lib/events-engine.js

@@ -6,7 +6,7 @@ import { list, get, update, create, remove } from '@/engine.js';
 import { queueEmail } from '@/services/notification-engine.js';
 import { safeJsonParse } from '@/lib/safe-json.js';
 import { validateTransition } from '@/lib/workflow-engine.js';
-import { AppError } from '@/lib/error-handler';
+import { AppError } from '@/lib/errors';
 import { HTTP } from '@/config/constants';
 
 const logActivity = (t, id, act, msg, u, d) =>

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

@@ -1,3 +1,37 @@
+// NOTE (repo audit, 2026-07-16): this barrel and every module it wires together
+// (promise-container, supervisor, checkpoint, timeout-wrapper, safe-error,
+// cache-invalidator, directory-watcher, debug-exposure) has NO importer anywhere
+// in the repo -- grepped for `hot-reload`, `@/lib/hot-reload`, and each filename
+// individually across src/, bin/, scripts/, server-bootstrap.js, cli.js. This
+// index.js is never imported, so `expose('hotReload', ...)` and the unconditional
+// `globalThis.__debug__` assignment in debug-exposure.js never actually fire.
+// None of these files gate on NODE_ENV or any dev-only flag internally (the one
+// NODE_ENV check in route-wrapper.js only toggles whether a stack trace is
+// included in an error body, not whether the module runs) -- so "dev-mode-only"
+// is not enforced by this code, it is simply unreferenced.
+//
+// The ONE exception is mutex.js: `globalManager` is imported directly (bypassing
+// this barrel) by src/app/api/auth/google/route.js and
+// src/app/api/auth/google/callback/route.js to lock an OAuth token-refresh
+// critical section -- a genuinely generic, domain-free primitive with no
+// hot-reload-specific coupling, and it is live production code.
+//
+// Collapse decision: did NOT merge cache-invalidator.js/directory-watcher.js/
+// supervisor.js. Since none of the three (nor checkpoint.js, debug-exposure.js,
+// route-wrapper.js, promise-container.js, safe-error.js, timeout-wrapper.js) has
+// a single live call site, merging them carries real risk (losing individually
+// resumable git history, plus this index.js barrel still exports all of them by
+// name so any future consumer added via this barrel would need the merge
+// un-done) for zero runtime benefit -- there is nothing executing today to make
+// faster, safer, or smaller. Generic/extractable-if-ever-needed: mutex.js (already
+// proven generic by its live OAuth use), promise-container.js, timeout-wrapper.js,
+// safe-error.js -- each is domain-free with no hot-reload-specific coupling.
+// Hot-reload-coupled and not generic: cache-invalidator.js (require.cache
+// invalidation), directory-watcher.js (fs.watch tree), debug-exposure.js
+// (globalThis.__debug__ registry) -- these only make sense together as a dev
+// hot-reload feature, but since nothing invokes them, no risky structural
+// change was forced. Left as-is, working code, simply dormant.
+
 import { createRequire } from 'module';
 import { fileURLToPath } from 'url';
 import path from 'path';

package/src/lib/index.js

@@ -1,5 +1,5 @@
-export * from '@/lib/busybase-store';
-export * from '@/lib/validate';
+export * from '@/lib/busybase/store';
+export * from '@/lib/validation/entity-validators';
 export * from '@/lib/field-types';
 export * from '@/lib/field-iterator';
 export * from '@/lib/list-data-transform';
@@ -20,11 +20,11 @@ export {
   normalizeError,
   formatErrorResponse,
   createErrorLogger,
-} from '@/lib/error-handler';
+} from '@/lib/errors';
 export { createApiHandler } from '@/lib/api';
 export { genId, now } from '@/lib/id-helpers';
-export { setBusyBaseClient } from '@/lib/busybase-store';
-export { logAction } from '@/lib/busybase-audit';
+export { setBusyBaseClient } from '@/lib/busybase/store';
+export { logAction } from '@/lib/busybase/audit';
 export * from '@/lib/realtime-server';
 export * from '@/lib/hook-engine';
 export * from '@/lib/events-engine';

package/src/lib/keyed-cache.js

@@ -0,0 +1,112 @@
+/*
+ * Shared keyed-cache primitive: a Map-backed store with TTL expiry and
+ * size-bounded eviction, factored out of the near-identical Map+eviction
+ * logic query-cache.js and render-cache.js each rolled independently.
+ *
+ * createCache({ ttlMs, maxSize }) returns a cache with get/set/delete/clear,
+ * plus size/stats helpers callers can build their own public stats on top of.
+ *
+ * Eviction policy: insertion-order (oldest-first / FIFO), matching what both
+ * original callers did via `cache.keys().next().value` -- not LRU. A `get()`
+ * does not move a key to the back of the map, so read-heavy hot keys are not
+ * specially protected from eviction; this preserves the exact prior behaviour
+ * of both callers being ported onto this primitive.
+ *
+ * ttlMs: 0 disables storage entirely (every set() is a no-op, every get() is
+ * a miss) -- mirrors query-cache.js's per-entity TTL_CONFIG=0 "never cache"
+ * entries (e.g. audit_logs). Omit/undefined ttlMs means "no expiry" (entries
+ * live until evicted by size or explicitly cleared) -- matches a cache that
+ * never expired anything by time.
+ */
+
+export function createCache({ ttlMs, maxSize = Infinity } = {}) {
+  const store = new Map();
+  let hits = 0;
+  let misses = 0;
+
+  function isExpired(entry) {
+    if (ttlMs == null || ttlMs < 0) return false;
+    return Date.now() - entry.ts > ttlMs;
+  }
+
+  function evictIfFull() {
+    while (store.size >= maxSize && maxSize > 0) {
+      const firstKey = store.keys().next().value;
+      if (firstKey === undefined) break;
+      store.delete(firstKey);
+    }
+  }
+
+  function get(key) {
+    const entry = store.get(key);
+    if (!entry) {
+      misses++;
+      return undefined;
+    }
+    if (isExpired(entry)) {
+      store.delete(key);
+      misses++;
+      return undefined;
+    }
+    hits++;
+    return entry.value;
+  }
+
+  function has(key) {
+    const entry = store.get(key);
+    if (!entry) return false;
+    if (isExpired(entry)) {
+      store.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  function set(key, value) {
+    if (ttlMs === 0) return; // 0 means "never cache" (matches TTL_CONFIG=0 entities)
+    if (!store.has(key)) evictIfFull();
+    store.set(key, { value, ts: Date.now() });
+  }
+
+  function del(key) {
+    return store.delete(key);
+  }
+
+  function clear() {
+    store.clear();
+  }
+
+  function keys() {
+    return store.keys();
+  }
+
+  function deleteWhere(predicate) {
+    let count = 0;
+    for (const key of store.keys()) {
+      if (predicate(key)) {
+        store.delete(key);
+        count++;
+      }
+    }
+    return count;
+  }
+
+  function stats() {
+    const total = hits + misses;
+    return {
+      size: store.size,
+      maxSize,
+      ttlMs,
+      hits,
+      misses,
+      hitRate: total > 0 ? hits / total : 0,
+    };
+  }
+
+  function resetStats() {
+    hits = 0;
+    misses = 0;
+  }
+
+  return { get, set, has, delete: del, clear, keys, deleteWhere, stats, resetStats };
+}