thatcher 1.0.4

package/src/lib/events-engine.js

@@ -0,0 +1,182 @@
+import { hookEngine } from '@/lib/hook-engine.js';
+import { list, get, update, create, remove } from '@/engine.js';
+import { queueEmail } from '@/engine/notification-engine';
+import { safeJsonParse } from '@/lib/safe-json.js';
+import { validateTransition } from '@/lib/workflow-engine.js';
+import { AppError } from '@/lib/error-handler';
+import { HTTP } from '@/config/constants';
+
+const logActivity = (t, id, act, msg, u, d) =>
+  create('activity_log', { entity_type: t, entity_id: id, action: act, message: msg, details: d ? JSON.stringify(d) : null, user_email: u?.email }, u);
+
+const updateEngagementProgress = (eid) => {
+  const rfis = list('rfi', { engagement_id: eid });
+  if (rfis.length > 0) {
+    const comp = rfis.filter(r => r.status === 'completed' || r.client_status === 'completed');
+    update('engagement', eid, { progress: Math.round((comp.length / rfis.length) * 100) });
+  }
+};
+
+const activateWorkflowsForStage = async (engagementId, stage, user) => {
+  try {
+    const { getConfigEngine } = await import('@/lib/config-generator-engine');
+    const configEngine = await getConfigEngine();
+    const config = configEngine.getConfig();
+
+    const stageConfig = config.workflows?.engagement_lifecycle?.stages?.find(s => s.name === stage);
+    if (!stageConfig?.activates?.length) return;
+
+    for (const feature of stageConfig.activates) {
+      logActivity('engagement', engagementId, 'feature_activated', `Activated ${feature}`, user, { activated_feature: feature });
+      hookEngine.execute(`feature:activated:${feature}`, { engagementId, stage, feature, user });
+    }
+  } catch (error) {
+    console.error(`[ACTIVATION] Error activating workflows for stage ${stage}:`, error.message);
+  }
+};
+
+export const registerEntityHandlers = () => {
+  hookEngine.register('update:engagement:before', async (context) => {
+    const { entity, data, user, prev } = context;
+    if (entity !== 'engagement' || !data.stage || data.stage === prev.stage) return context;
+    validateTransition('engagement_lifecycle', prev.stage, data.stage, user);
+    if (user?.role === 'clerk' && !(prev.clerks_can_approve === true || prev.clerks_can_approve === 1)) {
+      throw new AppError('Clerks cannot change engagement stage unless clerksCanApprove is enabled', 'INSUFFICIENT_PERMISSIONS', HTTP.FORBIDDEN);
+    }
+    try {
+      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); }
+    return context;
+  }, { priority: 100, name: 'workflow-stage-validator' });
+
+  hookEngine.on('create:rfi_response:after', async (ctx) => {
+    if (!ctx.data?.rfi_id) return;
+    const rfi = get('rfi', ctx.data.rfi_id);
+    if (rfi) update('rfi', ctx.data.rfi_id, { response_count: (rfi.response_count || 0) + 1, last_response_date: Math.floor(Date.now() / 1000) });
+  });
+
+  hookEngine.on('engagement:afterCreate', async (engagement, user) => {
+    if (engagement.client_id) {
+      const cnt = list('engagement', { client_id: engagement.client_id }).length;
+      update('client', engagement.client_id, { engagement_count: cnt });
+    }
+    if (engagement.stage === 'info_gathering') {
+      await queueEmail('engagement_info_gathering', { engagement, recipients: 'client_users' });
+    }
+    logActivity('engagement', engagement.id, 'create', `Engagement "${engagement.name}" created`, user);
+  });
+
+  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 });
+      const stageActions = {
+        commencement: () => queueEmail('engagement_commencement', { engagement, recipients: 'client_users' }),
+        finalization: async () => {
+          await queueEmail('engagement_finalization', { engagement, recipients: 'client_admin' });
+          await activateWorkflowsForStage(engagement.id, 'finalization', user);
+        },
+        closeout: () => {
+          if (engagement.letter_auditor_status !== 'accepted' && engagement.progress > 0)
+            throw new Error('Cannot close out: Letter must be accepted or progress must be 0%');
+        },
+      };
+      await stageActions[changes.stage]?.();
+    }
+    if (changes.status && changes.status !== prev.status) {
+      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' });
+    }
+  });
+
+  hookEngine.on('engagement:afterDelete', async (engagement) => {
+    if (engagement.client_id) {
+      const cnt = list('engagement', { client_id: engagement.client_id }).length;
+      update('client', engagement.client_id, { engagement_count: cnt });
+    }
+  });
+
+  hookEngine.on('client:afterUpdate', async (client, changes, prev, user) => {
+    if (changes.status === 'inactive' && prev.status !== 'inactive') {
+      const engagements = list('engagement', { client_id: client.id });
+      for (const e of engagements) {
+        if (e.repeat_interval !== 'once') update('engagement', e.id, { repeat_interval: 'once' });
+        if (e.stage === 'info_gathering' && e.progress === 0) remove('engagement', e.id);
+      }
+      logActivity('client', client.id, 'status_change', `Client inactive. Updated ${engagements.length} engagements.`, user);
+    }
+  });
+
+  hookEngine.on('rfi:afterUpdate', async (rfi, changes, prev, user) => {
+    if (changes.status !== undefined && changes.status !== prev.status) {
+      if (changes.status === 'completed' && !rfi.date_resolved) {
+        update('rfi', rfi.id, { date_resolved: Math.floor(Date.now() / 1000) });
+      }
+      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);
+    }
+    if (changes.deadline && changes.deadline !== prev.deadline) {
+      await queueEmail('rfi_deadline_change', { rfi, newDeadline: changes.deadline, recipients: 'assigned_users' });
+      logActivity('rfi', rfi.id, 'update', `Deadline: ${changes.deadline}`, user);
+    }
+    if (changes.status !== undefined || changes.client_status !== undefined) {
+      await updateEngagementProgress(rfi.engagement_id);
+    }
+  });
+
+  hookEngine.on('team:afterUpdate', async (team, changes, prev) => {
+    if (changes.users && prev.users) {
+      const prevUsers = safeJsonParse(prev.users, []);
+      const newUsers = safeJsonParse(changes.users, []);
+      const removed = prevUsers.filter(u => !newUsers.includes(u));
+      if (removed.length > 0) {
+        for (const e of list('engagement', { team_id: team.id })) {
+          const users = safeJsonParse(e.users, []).filter(u => !removed.includes(u));
+          if (users.length !== safeJsonParse(e.users, []).length) {
+            update('engagement', e.id, { users: JSON.stringify(users) });
+          }
+        }
+      }
+    }
+  });
+
+  hookEngine.on('review:afterCreate', async (review, user) => {
+    await queueEmail('review_created', { review, recipients: 'team_partners' });
+    if (review.template_id) {
+      const template = get('review_template', review.template_id);
+      for (const id of safeJsonParse(template?.default_checklists, [])) {
+        const checklist = get('checklist', id);
+        if (checklist) create('review_checklist', { review_id: review.id, checklist_id: id, items: checklist.section_items || checklist.items, status: 'pending' }, user);
+      }
+    }
+    logActivity('review', review.id, 'create', `Review "${review.name}" created`, user);
+  });
+
+  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);
+    }
+    if (changes.collaborators && changes.collaborators !== prev.collaborators) {
+      const added = safeJsonParse(changes.collaborators, []).filter(c => !safeJsonParse(prev.collaborators, []).find(p => p.id === c.id));
+      for (const c of added) await queueEmail('collaborator_added', { review, collaborator: c, recipients: 'collaborator' });
+    }
+  });
+
+  hookEngine.on('highlight:beforeDelete', async (highlight, user) => {
+    create('removed_highlight', { review_id: highlight.review_id, original_id: highlight.id, highlight_data: JSON.stringify(highlight) }, user);
+  });
+
+  hookEngine.on('collaborator:afterCreate', async (collaborator, user) => {
+    const review = get('review', collaborator.review_id);
+    const collabUser = get('user', collaborator.user_id);
+    if (review && collabUser) {
+      await queueEmail('collaborator_added', { review, collaborator: collabUser, type: collaborator.type, expiresAt: collaborator.expires_at, recipients: 'collaborator' });
+    }
+  });
+};

package/src/lib/field-iterator.js

@@ -0,0 +1,50 @@
+/**
+ * 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 }
+ */
+export function forEachField(spec, callback, options = {}) {
+  const { includeComputed = false, includeHidden = false } = options;
+
+  for (const [key, field] of Object.entries(spec.fields || {})) {
+    if (!includeHidden && field.hidden) continue;
+    if (!includeComputed && field.computed) continue;
+    callback(key, field);
+  }
+}
+
+/**
+ * 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);
+}

package/src/lib/field-registry.js

@@ -0,0 +1,68 @@
+/**
+ * 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;
+
+  switch (type) {
+    case 'int':
+    case 'decimal':
+      return Number(value);
+    case 'bool':
+    case 'boolean':
+      return value === true || value === 'true' || value === 1;
+    case 'json':
+      return typeof value === 'string' ? JSON.parse(value) : value;
+    case 'date':
+    case 'timestamp':
+      const num = Number(value);
+      return isNaN(num) ? null : num;
+    case 'ref':
+      return String(value);
+    default:
+      return String(value);
+  }
+}
+
+/**
+ * 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;
+
+  switch (type) {
+    case 'json':
+      try {
+        return typeof value === 'string' ? JSON.parse(value) : value;
+      } catch {
+        return {};
+      }
+    case 'bool':
+      return Boolean(value);
+    case 'date':
+    case 'timestamp':
+      return Number(value);
+    default:
+      return value;
+  }
+}

package/src/lib/field-types.js

@@ -0,0 +1,154 @@
+const TRUNCATE = { text: 50, textarea: 100, json: 80 };
+const INDICATORS = { text: '...', multiline: '... (see more)', json: '... (see more)' };
+const DATE_FORMATS = {
+  short: { month: 'short', day: 'numeric', year: 'numeric' },
+  long: { month: 'long', day: 'numeric', year: 'numeric' },
+  time: { hour: '2-digit', minute: '2-digit' },
+  datetime: { month: 'short', day: 'numeric', year: 'numeric', hour: '2-digit', minute: '2-digit' },
+  iso: 'iso',
+};
+
+const SECONDS_TO_MS = 1000;
+
+export function secondsToDate(seconds) {
+  return seconds ? new Date(seconds * SECONDS_TO_MS) : null;
+}
+
+export function dateToSeconds(date) {
+  return date ? Math.floor(date.getTime() / SECONDS_TO_MS) : null;
+}
+
+export function formatDate(value, format = 'short') {
+  if (!value) return null;
+  const date = typeof value === 'number' ? secondsToDate(value) : new Date(value);
+  if (isNaN(date.getTime())) return null;
+  if (format === 'iso') return date.toISOString().split('T')[0];
+  const opts = DATE_FORMATS[format] || DATE_FORMATS.short;
+  return date.toLocaleDateString(undefined, opts);
+}
+
+export function parseDate(dateString) {
+  if (!dateString) return null;
+  return dateToSeconds(new Date(dateString));
+}
+
+function truncateText(text, limit = TRUNCATE.text, indicator = INDICATORS.text) {
+  if (!text) return '';
+  const str = String(text);
+  return str.length > limit ? str.substring(0, limit) + indicator : str;
+}
+
+function truncateJson(val) {
+  const str = typeof val === 'string' ? val : JSON.stringify(val);
+  return str.length > TRUNCATE.json ? str.substring(0, TRUNCATE.json) + INDICATORS.json : str;
+}
+
+function truncateTextarea(text) {
+  return truncateText(text, TRUNCATE.textarea, INDICATORS.multiline);
+}
+
+function createSimpleType(sqlType, overrides = {}) {
+  return { sqlType, coerce: (val) => val, format: (val) => val, isValid: () => true, ...overrides };
+}
+
+function createNumberType(sqlType, coerceFn, formatFn) {
+  return { sqlType, coerce: coerceFn, format: formatFn, isValid: () => true };
+}
+
+function createDateType(sqlType, formatType) {
+  return {
+    sqlType,
+    coerce: (val) => (!val || typeof val !== 'string' ? val : dateToSeconds(new Date(val))),
+    format: (val) => formatDate(val, formatType),
+    isValid: (val) => !isNaN(new Date(val).getTime()),
+  };
+}
+
+export const fieldRegistry = {
+  text: createSimpleType('TEXT', { format: (val) => String(val ?? '') }),
+  email: createSimpleType('TEXT', {
+    format: (val) => String(val ?? ''),
+    isValid: (val) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(val),
+  }),
+  textarea: createSimpleType('TEXT', { format: (val) => truncateTextarea(String(val ?? '')) }),
+  int: createNumberType('INTEGER', (val) => {
+    if (val === undefined || val === '' || val === null) return null;
+    const num = parseInt(val, 10);
+    if (isNaN(num)) throw new Error(`Invalid integer: ${val}`);
+    return num;
+  }, (val) => String(val ?? '')),
+  number: createNumberType('REAL', (val) => {
+    if (val === undefined || val === '' || val === null) return null;
+    const num = parseFloat(val);
+    if (isNaN(num)) throw new Error(`Invalid number: ${val}`);
+    return num;
+  }, (val) => String(val ?? '')),
+  decimal: createNumberType('REAL', (val) => {
+    if (val === undefined || val === '' || val === null) return null;
+    const num = parseFloat(val);
+    if (isNaN(num)) throw new Error(`Invalid decimal: ${val}`);
+    return num;
+  }, (val) => (typeof val === 'number' ? val.toFixed(2) : val)),
+  bool: createSimpleType('INTEGER', {
+    coerce: (val) => (val === true || val === 'true' || val === 'on' || val === 1 ? 1 : 0),
+    format: (val) => (val ? 'Yes' : 'No'),
+  }),
+  date: createDateType('INTEGER', 'locale'),
+  timestamp: createDateType('INTEGER', 'datetime'),
+  enum: {
+    sqlType: 'TEXT',
+    coerce: (val) => val,
+    format: (val, field, spec) => {
+      if (!field.options || !spec || val === null || val === undefined) return String(val);
+      const opt = spec.options?.[field.options]?.find(o => String(o.value) === String(val));
+      return opt ? { label: opt.label, color: opt.color || 'gray' } : String(val);
+    },
+    isValid: () => true,
+  },
+  ref: {
+    sqlType: 'TEXT',
+    coerce: (val) => val,
+    format: (val, field, spec, row) => {
+      if (!field.display) return val;
+      if (field.display === 'avatars' && Array.isArray(val)) return { type: 'avatars', users: val };
+      return row?.[`${field.key}_display`] || val;
+    },
+    isValid: () => true,
+  },
+  json: createSimpleType('TEXT', {
+    coerce: (val) => {
+      if (val === undefined || val === '' || val === null) return null;
+      return typeof val === 'string' ? val : JSON.stringify(val);
+    },
+    format: (val) => truncateJson(val),
+  }),
+  image: createSimpleType('TEXT'),
+  id: createSimpleType('TEXT PRIMARY KEY'),
+};
+
+export function getFieldHandler(type) {
+  return fieldRegistry[type] || fieldRegistry.text;
+}
+
+export function coerceFieldValue(value, type) {
+  return getFieldHandler(type).coerce(value);
+}
+
+export function formatFieldValue(value, field, spec, row) {
+  if (value === null || value === undefined || value === '') return null;
+  return getFieldHandler(field.type).format(value, field, spec, row);
+}
+
+export function validateFieldValue(value, field) {
+  return getFieldHandler(field.type).isValid(value, field);
+}
+
+export function getEnumOption(spec, optionsKey, value) {
+  return spec.options?.[optionsKey]?.find(o => String(o.value) === String(value));
+}
+
+export function getEnumOptions(spec, optionsKey) {
+  return spec.options?.[optionsKey] || [];
+}
+
+export { TRUNCATE as FIELD_TRUNCATE, INDICATORS as TRUNCATION_INDICATORS, DATE_FORMATS };

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

@@ -0,0 +1,32 @@
+/**
+ * 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();
+    engine.generateEntitySpec(entityName);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/lib/health-monitor.js

@@ -0,0 +1,134 @@
+import { getDatabase } from '@/engine';
+
+const healthState = {
+  checks: new Map(),
+  history: [],
+  lastCheck: null,
+  status: 'unknown'
+};
+
+export function registerHealthCheck(name, checkFn, options = {}) {
+  const { critical = false, timeout = 5000 } = options;
+
+  healthState.checks.set(name, {
+    name,
+    checkFn,
+    critical,
+    timeout,
+    lastResult: null,
+    lastCheck: null
+  });
+}
+
+export async function runHealthCheck(name) {
+  const check = healthState.checks.get(name);
+  if (!check) return null;
+
+  const start = Date.now();
+
+  try {
+    const timeoutPromise = new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('Health check timeout')), check.timeout)
+    );
+
+    const checkPromise = check.checkFn();
+
+    await Promise.race([checkPromise, timeoutPromise]);
+
+    const result = {
+      status: 'healthy',
+      latency: Date.now() - start,
+      timestamp: new Date().toISOString()
+    };
+
+    check.lastResult = result;
+    check.lastCheck = Date.now();
+
+    return result;
+  } catch (error) {
+    const result = {
+      status: 'unhealthy',
+      error: String(error?.message || error),
+      latency: Date.now() - start,
+      timestamp: new Date().toISOString()
+    };
+
+    check.lastResult = result;
+    check.lastCheck = Date.now();
+
+    if (check.critical) {
+      console.error(`[HEALTH] Critical check failed: ${name}`, error);
+    }
+
+    return result;
+  }
+}
+
+export async function runAllHealthChecks() {
+  const results = {};
+  const checks = Array.from(healthState.checks.keys());
+
+  for (const name of checks) {
+    results[name] = await runHealthCheck(name);
+  }
+
+  const allHealthy = Object.values(results).every(r => r.status === 'healthy');
+  const criticalUnhealthy = Array.from(healthState.checks.values())
+    .filter(c => c.critical && c.lastResult?.status === 'unhealthy')
+    .length > 0;
+
+  const status = criticalUnhealthy ? 'critical' : allHealthy ? 'healthy' : 'degraded';
+
+  const summary = {
+    status,
+    timestamp: new Date().toISOString(),
+    checks: results,
+    uptime: process.uptime()
+  };
+
+  healthState.lastCheck = summary;
+  healthState.status = status;
+  healthState.history.push(summary);
+
+  if (healthState.history.length > 100) {
+    healthState.history.shift();
+  }
+
+  return summary;
+}
+
+export function getHealthStatus() {
+  return healthState.lastCheck || { status: 'unknown', checks: {} };
+}
+
+export function getHealthHistory() {
+  return healthState.history.slice(-20);
+}
+
+registerHealthCheck('database', async () => {
+  const db = getDatabase();
+  db.prepare('SELECT 1').get();
+}, { critical: true, timeout: 2000 });
+
+registerHealthCheck('memory', async () => {
+  const usage = process.memoryUsage();
+  const heapUsedMB = usage.heapUsed / 1024 / 1024;
+
+  if (heapUsedMB > 512) {
+    throw new Error(`High memory usage: ${heapUsedMB.toFixed(0)}MB`);
+  }
+}, { critical: false, timeout: 1000 });
+
+registerHealthCheck('uptime', async () => {
+  const uptime = process.uptime();
+  if (uptime < 5) {
+    throw new Error('Recently restarted');
+  }
+}, { critical: false, timeout: 100 });
+
+if (typeof global !== 'undefined') {
+  global.healthState = healthState;
+  global.runHealthCheck = runHealthCheck;
+  global.runAllHealthChecks = runAllHealthChecks;
+  global.getHealthStatus = getHealthStatus;
+}