thatcher 1.0.7 → 1.0.34

package/src/lib/error-recovery.js

@@ -1,5 +1,8 @@
-import { retryWithBackoff, withCircuitBreaker, checkpoint, restoreCheckpoint, logRecovery, normalizeError } from '@/lib/error-handler';
-import { AppError } from '@/lib/errors';
+import { createLogger } from './logger.js';
+import { retryWithBackoff, withCircuitBreaker, checkpoint, restoreCheckpoint, logRecovery } from '@/lib/error-resilience';
+
+const log = createLogger('[Recovery]');
+import { normalizeError, AppError } from '@/lib/error-handler';
 import { HTTP } from '@/config/constants';
 
 const recoveryState = { supervisors: new Map(), lastHealthCheck: null };
@@ -37,7 +40,7 @@ export async function supervise(name, fn, options = {}) {
     );
     supervisor.state = 'failed';
     supervisor.lastError = error;
-    console.error(`[SUPERVISOR] ${name} failed permanently after ${supervisor.restarts.length} restarts`);
+    log.error(`${name} failed permanently after ${supervisor.restarts.length} restarts`);
     throw error;
   }
 
@@ -58,7 +61,7 @@ export async function supervise(name, fn, options = {}) {
 
     if (supervisor.restarts.length < supervisor.maxRestarts) {
       const delay = Math.min(1000 * Math.pow(2, supervisor.restarts.length - 1), 30000);
-      console.warn(`[SUPERVISOR] ${name} restarting in ${delay}ms (attempt ${supervisor.restarts.length})`);
+      log.warn(`${name} restarting in ${delay}ms (attempt ${supervisor.restarts.length})`);
       await new Promise(resolve => setTimeout(resolve, delay));
       return supervise(name, fn, options);
     }
@@ -79,7 +82,7 @@ export async function degradedMode(fn, fallback, options = {}) {
     ]);
     return { mode: 'normal', result };
   } catch (error) {
-    console.warn('[DEGRADED] Falling back to degraded mode', { error: error.message });
+    log.warn('falling back to degraded mode', { error: error.message });
     const result = await fallback();
     return { mode: 'degraded', result };
   }
@@ -115,7 +118,7 @@ export function isolateFailure(fn, defaultValue = null) {
     try {
       return await fn(...args);
     } catch (error) {
-      console.error('[ISOLATE] Failure contained', {
+      log.error('failure contained', {
         function: fn.name,
         error: String(error.message || error)
       });
@@ -163,7 +166,7 @@ export async function withRecovery(fn, options = {}) {
     return result;
   } catch (error) {
     if (fallback) {
-      console.warn('[RECOVERY] Using fallback after error', { error: error.message });
+      log.warn('using fallback after error', { error: error.message });
       return fallback();
     }
     throw error;

package/src/lib/error-resilience.js

@@ -1,6 +1,8 @@
+import { createLogger } from './logger.js';
 import { HTTP } from '@/config/constants';
-import { AppError } from '@/lib/errors';
-import { normalizeError } from '@/lib/error-handler';
+
+const log = createLogger('[Resilience]');
+import { AppError, normalizeError } from '@/lib/error-handler';
 
 const errorState = { errors: [], circuitBreakers: new Map(), checkpoints: new Map() };
 
@@ -13,12 +15,12 @@ export async function retryWithBackoff(fn, options = {}) {
     } catch (error) {
       if (attempt === maxAttempts) {
         const normalized = normalizeError(error);
-        console.error(`[RETRY] Final attempt failed:`, { ...context, attempt, error: normalized.toJSON() });
+        log.error('final attempt failed:', { ...context, attempt, error: normalized.toJSON() });
         throw normalized;
       }
 
       const waitTime = delay * Math.pow(backoff, attempt - 1);
-      console.warn(`[RETRY] Attempt ${attempt} failed, retrying in ${waitTime}ms`, context);
+      log.warn(`attempt ${attempt} failed, retrying in ${waitTime}ms`, context);
       await new Promise(resolve => setTimeout(resolve, waitTime));
     }
   }
@@ -66,7 +68,7 @@ export async function withCircuitBreaker(name, fn, options = {}) {
     if (breaker.failures >= breaker.threshold) {
       breaker.state = 'open';
       breaker.nextAttempt = Date.now() + breaker.resetTimeout;
-      console.error(`[CIRCUIT] ${name} opened after ${breaker.failures} failures`);
+      log.error(`circuit ${name} opened after ${breaker.failures} failures`);
     }
 
     throw error;

package/src/lib/events-engine.js

@@ -1,4 +1,7 @@
+import { createLogger } from './logger.js';
 import { hookEngine } from '@/lib/hook-engine.js';
+
+const log = createLogger('[EventsEngine]');
 import { list, get, update, create, remove } from '@/engine.js';
 import { queueEmail } from '@/engine/notification-engine';
 import { safeJsonParse } from '@/lib/safe-json.js';
@@ -31,7 +34,7 @@ const activateWorkflowsForStage = async (engagementId, stage, user) => {
       hookEngine.execute(`feature:activated:${feature}`, { engagementId, stage, feature, user });
     }
   } catch (error) {
-    console.error(`[ACTIVATION] Error activating workflows for stage ${stage}:`, error.message);
+    log.error(`error activating workflows for stage ${stage}:`, { message: error.message });
   }
 };
 
@@ -47,7 +50,7 @@ export const registerEntityHandlers = () => {
       create('activity_log', { entity_type: 'engagement', entity_id: context.id, action: 'stage_transition',
         message: `Stage transitioned: ${prev.stage} -> ${data.stage}`,
         details: JSON.stringify({ from: prev.stage, to: data.stage, user_role: user?.role }), user_email: user?.email }, user);
-    } catch (e) { console.error('[events-engine] Failed to log stage change:', e.message); }
+    } catch (e) { log.error('failed to log stage change:', { message: e.message }); }
     return context;
   }, { priority: 100, name: 'workflow-stage-validator' });
 
@@ -70,7 +73,7 @@ export const registerEntityHandlers = () => {
 
   hookEngine.on('engagement:afterUpdate', async (engagement, changes, prev, user) => {
     if (changes.stage && changes.stage !== prev.stage) {
-      logActivity('engagement', engagement.id, 'stage_change', `Stage: ${prev.stage} → ${changes.stage}`, user, { from: prev.stage, to: changes.stage });
+      logActivity('engagement', engagement.id, 'stage_change', `Stage: ${prev.stage} -> ${changes.stage}`, user, { from: prev.stage, to: changes.stage });
       const stageActions = {
         commencement: () => queueEmail('engagement_commencement', { engagement, recipients: 'client_users' }),
         finalization: async () => {
@@ -85,7 +88,7 @@ export const registerEntityHandlers = () => {
       await stageActions[changes.stage]?.();
     }
     if (changes.status && changes.status !== prev.status) {
-      logActivity('engagement', engagement.id, 'status_change', `Status: ${prev.status} → ${changes.status}`, user);
+      logActivity('engagement', engagement.id, 'status_change', `Status: ${prev.status} -> ${changes.status}`, user);
     }
     if (changes.commencement_date && changes.commencement_date !== prev.commencement_date) {
       await queueEmail('engagement_date_change', { engagement, field: 'commencement_date', recipients: 'team_members' });
@@ -118,7 +121,7 @@ export const registerEntityHandlers = () => {
       if (changes.client_status && changes.client_status !== prev.client_status) {
         await queueEmail('rfi_status_change', { rfi, from: prev.client_status, to: changes.client_status, recipients: 'assigned_users' });
       }
-      logActivity('rfi', rfi.id, 'status_change', `Status: ${prev.status} → ${changes.status}`, user);
+      logActivity('rfi', rfi.id, 'status_change', `Status: ${prev.status} -> ${changes.status}`, user);
     }
     if (changes.deadline && changes.deadline !== prev.deadline) {
       await queueEmail('rfi_deadline_change', { rfi, newDeadline: changes.deadline, recipients: 'assigned_users' });
@@ -160,7 +163,7 @@ export const registerEntityHandlers = () => {
   hookEngine.on('review:afterUpdate', async (review, changes, prev, user) => {
     if (changes.status && changes.status !== prev.status) {
       await queueEmail('review_status_change', { review, from: prev.status, to: changes.status, recipients: 'team_members' });
-      logActivity('review', review.id, 'status_change', `Status: ${prev.status} → ${changes.status}`, user);
+      logActivity('review', review.id, 'status_change', `Status: ${prev.status} -> ${changes.status}`, user);
     }
     if (changes.collaborators && changes.collaborators !== prev.collaborators) {
       const added = safeJsonParse(changes.collaborators, []).filter(c => !safeJsonParse(prev.collaborators, []).find(p => p.id === c.id));

package/src/lib/export-sink.js

@@ -1,8 +1,3 @@
-/**
- * Observability Export Sink - Streams traces and metrics to external systems
- * Supports file, HTTP (OTLP), and stdout targets with batching and retry
- */
-
 import fs from 'fs';
 import path from 'path';
 import { createLogger } from './logger.js';

package/src/lib/field-iterator.js

@@ -1,13 +1,9 @@
-/**
- * Field Iterator - Iterate over all fields (including nested/computed) in a spec
- */
-
-/**
- * Iterate over all fields in an entity spec
- * @param {object} spec - Entity specification
- * @param {Function} callback - (key, fieldDef) => void
- * @param {object} options - { includeComputed, includeHidden }
- */
+/* ------------------------------------------------------------------ *
+ * Predicate-based field query helpers (ported from moonlanding).
+ * Additive: these do not change thatcher's existing forEachField /
+ * getEditableFields / getFieldNames / getFieldsByType signatures.
+ * ------------------------------------------------------------------ */
+
 export function forEachField(spec, callback, options = {}) {
   const { includeComputed = false, includeHidden = false } = options;
 
@@ -18,50 +14,21 @@ export function forEachField(spec, callback, options = {}) {
   }
 }
 
-/**
- * Get all field names
- * @param {object} spec
- * @returns {string[]}
- */
 export function getFieldNames(spec) {
   return Object.keys(spec.fields || {});
 }
 
-/**
- * Get only editable fields
- * @param {object} spec
- * @returns {string[]}
- */
 export function getEditableFields(spec) {
   return Object.entries(spec.fields || {})
     .filter(([key, field]) => !field.readonly && !field.auto && !field.auto_generate)
     .map(([key]) => key);
 }
 
-/**
- * Get field by type
- * @param {object} spec
- * @param {string} type
- * @returns {Array<{key: string, field: object}>}
- */
 export function getFieldsByType(spec, type) {
   return Object.entries(spec.fields || {})
     .filter(([key, field]) => field.type === type);
 }
 
-/* ------------------------------------------------------------------ *
- * Predicate-based field query helpers (ported from moonlanding).
- * Additive: these do not change thatcher's existing forEachField /
- * getEditableFields / getFieldNames / getFieldsByType signatures.
- * ------------------------------------------------------------------ */
-
-/**
- * Query the fields of a spec with one or more predicates.
- * @param {object} spec
- * @param {Function|Function[]} predicates - (field, key) => boolean
- * @param {object} [options] - { keysOnly }
- * @returns {Array<string|object>} keys when keysOnly, else { key, ...field }
- */
 export function fieldQuery(spec, predicates, options = {}) {
   const preds = Array.isArray(predicates) ? predicates : [predicates];
   const results = [];
@@ -73,9 +40,6 @@ export function fieldQuery(spec, predicates, options = {}) {
   return results;
 }
 
-/**
- * Reusable field predicates for fieldQuery.
- */
 export const is = {
   notId: f => f.type !== 'id',
   notHidden: f => !f.hidden,
@@ -90,85 +54,52 @@ export const is = {
   hasProperty: prop => f => f[prop] !== undefined,
 };
 
-/**
- * Editable fields as full { key, ...field } objects (form rendering).
- * Distinct from thatcher's getEditableFields (which returns names only).
- */
+// Returns { key, ...field } objects, unlike getEditableFields() which returns names only.
 export function getFormFields(spec) {
   if (spec.system_entity) return [];
   return fieldQuery(spec, is.editable);
 }
 
-/**
- * Listable fields as full { key, ...field } objects.
- */
 export function getListFields(spec) {
   return fieldQuery(spec, is.listable);
 }
 
-/**
- * Displayable fields as full { key, ...field } objects.
- */
 export function getDisplayFields(spec) {
   return fieldQuery(spec, is.displayable);
 }
 
-/**
- * Required field names.
- */
 export function getRequiredFields(spec) {
   return fieldQuery(spec, is.required, { keysOnly: true });
 }
 
-/**
- * Searchable field names.
- */
 export function getSearchFields(spec) {
   return fieldQuery(spec, is.searchable, { keysOnly: true });
 }
 
-/**
- * Filterable fields, resolved from list.filters config.
- */
 export function getFilterableFields(spec) {
   return (spec.list?.filters || [])
     .map(filterKey => spec.fields?.[filterKey])
     .filter(Boolean);
 }
 
-/**
- * Reference (ref) fields as full { key, ...field } objects.
- */
 export function getRefFields(spec) {
   return fieldQuery(spec, is.ref);
 }
 
-/**
- * Get a single field definition by key.
- */
 export function getField(spec, fieldKey) {
   return spec.fields?.[fieldKey];
 }
 
-/**
- * Get a single field's type by key.
- */
 export function getFieldType(spec, fieldKey) {
   return spec.fields?.[fieldKey]?.type;
 }
 
-/**
- * Iterate editable fields on create. callback = (key, field) => void
- */
 export function iterateCreateFields(spec, callback) {
   for (const { key, ...field } of fieldQuery(spec, is.editable)) {
     callback(key, field);
   }
 }
 
-/**
- * Iterate editable fields on update. callback = (key, field) => void
- */
 export function iterateUpdateFields(spec, callback) {
   for (const { key, ...field } of fieldQuery(spec, is.editable)) {
     callback(key, field);

package/src/lib/field-registry.js

@@ -1,13 +1,3 @@
-/**
- * Field Registry - Type coercion and field utilities
- */
-
-/**
- * Coerce value to field type
- * @param {any} value
- * @param {string} type
- * @returns {any}
- */
 export function coerceFieldValue(value, type) {
   if (value === null || value === undefined) return value;
 
@@ -31,22 +21,10 @@ export function coerceFieldValue(value, type) {
   }
 }
 
-/**
- * Serialize field value for database
- * @param {any} value
- * @param {string} type
- * @returns {any}
- */
 export function serializeField(value, type) {
   return coerceFieldValue(value, type);
 }
 
-/**
- * Deserialize field value from database
- * @param {any} value
- * @param {string} type
- * @returns {any}
- */
 export function deserializeField(value, type) {
   if (value === null) return null;
 

package/src/lib/generic-crud-handler.js

@@ -1,26 +1,10 @@
-/**
- * Generic CRUD Handler - Catch-all API handler for any entity
- * This provides out-of-the-box CRUD for all entities defined in config
- * Users can override by creating their own route files
- */
-
 import { createCrudHandlers } from '../lib/crud-factory.js';
 import { getConfigEngineSync } from '../lib/config-generator-engine.js';
 
-/**
- * Get handler for an entity
- * @param {string} entityName
- * @returns {object} {GET, POST, PUT, DELETE}
- */
 export function getEntityHandlers(entityName) {
   return createCrudHandlers(entityName);
 }
 
-/**
- * Check if entity exists and is accessible
- * @param {string} entityName
- * @returns {boolean}
- */
 export function hasEntity(entityName) {
   try {
     const engine = getConfigEngineSync();

package/src/lib/hook-engine.js

@@ -1,19 +1,12 @@
-/**
- * Hook Engine - Event system for plugins and lifecycle hooks
- * Fires events like 'create:entity:after', 'update:entity:before', etc.
- */
+import { createLogger } from './logger.js';
+
+const log = createLogger('[HookEngine]');
 
 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, []);
@@ -23,16 +16,10 @@ export class HookEngine {
     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;
@@ -42,13 +29,6 @@ export class HookEngine {
     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);
@@ -60,7 +40,7 @@ export class HookEngine {
         await hook.callback(data);
         if (hook.once) this.off(name, hook.callback);
       } catch (error) {
-        console.error(`[HookEngine] Hook "${name}" error:`, error.message);
+        log.error(`hook "${name}" error:`, { message: error.message });
         errors.push(error);
         if (!fallthrough) throw error;
       }
@@ -69,12 +49,6 @@ export class HookEngine {
     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;
@@ -86,25 +60,16 @@ export class HookEngine {
         if (result !== undefined) current = result;
         if (hook.once) this.off(name, hook.callback);
       } catch (error) {
-        console.error(`[HookEngine] Pipe hook "${name}" error:`, error.message);
+        log.error(`pipe hook "${name}" error:`, { message: 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()) {
@@ -113,34 +78,21 @@ export class HookEngine {
     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', {

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

@@ -1,6 +1,9 @@
+import { createLogger } from '../logger.js';
 import fs from 'fs';
 import path from 'path';
 
+const log = createLogger('[Checkpoint]');
+
 export class CheckpointManager {
   constructor(options = {}) {
     this.checkpointDir = options.checkpointDir || path.join(process.cwd(), 'data', 'checkpoints');
@@ -23,7 +26,7 @@ export class CheckpointManager {
       await this._pruneOldCheckpoints(key);
       return true;
     } catch (err) {
-      console.error(`[Checkpoint] Failed to save ${key}:`, err);
+      log.error(`failed to save ${key}:`, { message: err?.message || String(err) });
       return false;
     }
   }
@@ -42,7 +45,7 @@ export class CheckpointManager {
       this.checkpoints.set(key, checkpoint);
       return checkpoint.state;
     } catch (err) {
-      console.error(`[Checkpoint] Failed to load ${key}:`, err);
+      log.error(`failed to load ${key}:`, { message: err?.message || String(err) });
       return null;
     }
   }

package/src/lib/hot-reload/promise-container.js

@@ -1,5 +1,9 @@
 import { EventEmitter } from 'events';
 
+import { createLogger } from '../logger.js';
+
+const log = createLogger('[PromiseContainer]');
+
 export class PromiseContainer extends EventEmitter {
   constructor() {
     super();
@@ -40,7 +44,7 @@ export class PromiseContainer extends EventEmitter {
     try {
       await Promise.race([drainPromise, timeoutPromise]);
     } catch (err) {
-      console.warn(`Promise drain timeout: ${this.activePromises.size} promises still active`);
+      log.warn(`promise drain timeout: ${this.activePromises.size} promises still active`);
     }
   }
 
@@ -55,11 +59,11 @@ export class PromiseContainer extends EventEmitter {
 export const globalContainer = new PromiseContainer();
 
 globalContainer.setGlobalHandler((err, context) => {
-  console.error(`[PromiseContainer] Unhandled rejection in ${context}:`, err);
+  log.error(`unhandled rejection in ${context}:`, { message: err?.message || String(err) });
 });
 
 process.on('unhandledRejection', (reason, promise) => {
-  console.error('[Process] Unhandled Promise Rejection:', reason);
+  log.error('unhandled promise rejection:', { message: reason?.message || String(reason) });
   globalContainer.emit('processRejection', { reason, promise });
 });
 

package/src/lib/hot-reload/route-wrapper.js

@@ -1,4 +1,7 @@
+import { createLogger } from '../logger.js';
 import { safeError } from './safe-error.js';
+
+const log = createLogger('[RouteWrapper]');
 import { contain } from './promise-container.js';
 
 export function wrapRouteHandler(handler, options = {}) {
@@ -13,7 +16,7 @@ export function wrapRouteHandler(handler, options = {}) {
       return result;
     } catch (err) {
       if (logErrors) {
-        console.error(`[RouteError:${context}] ${req.method} ${req.url}:`, err);
+        log.error(`${context} ${req.method} ${req.url}:`, { message: err?.message || String(err) });
       }
       if (sendErrorResponse && !res.headersSent) {
         const safe = safeError(err);

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

@@ -1,5 +1,8 @@
+import { createLogger } from '../logger.js';
 import { EventEmitter } from 'events';
 
+const log = createLogger('[Supervisor]');
+
 export class Supervisor extends EventEmitter {
   constructor(name, workerFn, options = {}) {
     super();
@@ -22,7 +25,7 @@ export class Supervisor extends EventEmitter {
 
     if (this.listenerCount('error') === 0) {
       this.on('error', (data) => {
-        console.error(`[Supervisor:${this.name}] Worker error:`, data.error?.message || data.error);
+        log.error(`[${this.name}] worker error:`, { message: data.error?.message || String(data.error) });
       });
     }
   }
@@ -73,7 +76,7 @@ export class Supervisor extends EventEmitter {
       try {
         await this.options.onError(err);
       } catch (handlerErr) {
-        console.error(`[Supervisor:${this.name}] Error handler failed:`, handlerErr);
+        log.error(`[${this.name}] error handler failed:`, { message: handlerErr?.message || String(handlerErr) });
       }
     }
 
@@ -84,7 +87,7 @@ export class Supervisor extends EventEmitter {
     this.restarts.push(now);
 
     if (this.restarts.length > this.options.maxRestarts) {
-      console.error(`[Supervisor:${this.name}] Max restarts exceeded. Giving up.`);
+      log.error(`[${this.name}] max restarts exceeded, giving up`);
       this.emit('giveup', this.name);
       this.running = false;
       return;

package/src/lib/hyperformula-service.js

@@ -1,8 +1,3 @@
-/**
- * HyperFormula Compute Engine - Spreadsheet formula evaluation for Thatcher
- * Provides calculated fields, business rules, and data transformations
- */
-
 import { HyperFormula } from 'hyperformula';
 import { createLogger } from './logger.js';
 

package/src/lib/id-helpers.js

@@ -0,0 +1,10 @@
+// Extracted from database-core.js so modules that need genId()/now() (e.g. the
+// busybase store) don't have to import database-core, which pulls in better-sqlite3.
+
+export function genId() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function now() {
+  return Math.floor(Date.now() / 1000);
+}