thatcher 1.0.4

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

@@ -0,0 +1,445 @@
+/**
+ * Config Generator Engine - Resolves entity specs from YAML config
+ * Core of Thatcher's configuration-driven architecture
+ * Adapted from moonlanding/src/lib/config-generator-engine.js
+ */
+
+import yaml from 'js-yaml';
+import { LRUCache, deepFreeze, deepClone, recursiveResolve } from './config-helpers.js';
+import { generateFieldsFromOverrides, ensureFieldLabels } from './config-field-helpers.js';
+
+export class ConfigGeneratorEngine {
+  constructor(masterConfig) {
+    if (!masterConfig) throw new Error('[ConfigGeneratorEngine] masterConfig is required');
+    this.masterConfig = deepFreeze(masterConfig);
+    this.specCache = new LRUCache(100);
+    this._plugins = new Map();
+  }
+
+  /**
+   * Register a plugin to extend an entity
+   */
+  registerPlugin(entityName, plugin = {}) {
+    if (!entityName || typeof entityName !== 'string') {
+      throw new Error('[ConfigGeneratorEngine] registerPlugin: entityName required');
+    }
+
+    const existing = this._plugins.get(entityName) || { fields: {}, hooks: [], validators: [] };
+
+    this._plugins.set(entityName, {
+      fields: { ...existing.fields, ...(plugin.fields || {}) },
+      hooks: [...existing.hooks, ...(plugin.hooks || [])],
+      validators: [...existing.validators, ...(plugin.validators || [])],
+    });
+
+    this.specCache.clear();
+
+    // Register hooks with global hook engine if available
+    for (const { event, handler } of (plugin.hooks || [])) {
+      if (event && handler && globalThis.__hookEngine) {
+        globalThis.__hookEngine.register(event, handler);
+      }
+    }
+
+    if (globalThis.__debug__) {
+      globalThis.__debug__.expose('plugins', Object.fromEntries(this._plugins.entries()), 'Plugin registry');
+    }
+
+    return this;
+  }
+
+  getPlugins(entityName) {
+    return this._plugins.get(entityName) || null;
+  }
+
+  getConfig() {
+    return deepFreeze(deepClone(this.masterConfig));
+  }
+
+  getRoles() {
+    return this._cached('roles:all', () => deepFreeze(deepClone(this.masterConfig.roles || {})));
+  }
+
+  getRole(roleName) {
+    return this._cached(`role:${roleName}`, () => deepFreeze(deepClone(this._require('roles', roleName))));
+  }
+
+  getDomains() {
+    return deepFreeze(deepClone(this.masterConfig.domains || {}));
+  }
+
+  getHighlightPalette() {
+    return deepFreeze(deepClone(this.masterConfig.highlights?.palette || []));
+  }
+
+  getSystemConfig() {
+    return deepFreeze(deepClone(this.masterConfig.system || {}));
+  }
+
+  getRepeatIntervals() {
+    return deepFreeze(deepClone(this.masterConfig.repeat_intervals || { once: 'once', monthly: 'monthly', yearly: 'yearly' }));
+  }
+
+  getAllEntities() {
+    return Object.keys(this.masterConfig.entities || {}).sort();
+  }
+
+  getAllAutomations() {
+    return deepClone(this.masterConfig.automation?.schedules || []);
+  }
+
+  getTheme() {
+    return this._cached('theme:all', () => deepFreeze(deepClone(this.masterConfig.theme || {})));
+  }
+
+  getIcons() {
+    return this._cached('icons:all', () => deepFreeze(deepClone(this.masterConfig.icons || {})));
+  }
+
+  getIcon(iconType, iconName) {
+    return this.masterConfig.icons?.[iconType]?.[iconName] || null;
+  }
+
+  getWorkflow(name) {
+    return this._resolved('workflow', 'workflows', name);
+  }
+
+  getPermissionTemplate(name) {
+    return deepFreeze(deepClone(this._require('permission_templates', name)));
+  }
+
+  getStatusEnum(name) {
+    return deepFreeze(deepClone(this._require('status_enums', name)));
+  }
+
+  getStatuses(name) {
+    return this._cached(`statuses:${name}`, () => deepFreeze(deepClone(this._require('status_enums', name))));
+  }
+
+  getStatus(entity, status) {
+    return this._cached(`status:${entity}:${status}`, () => deepFreeze(deepClone(this._require(`status_enums.${entity}_status`, status))));
+  }
+
+  getEntity(name) {
+    return this._cached(`entity:${name}`, () => deepFreeze(deepClone(this._require('entities', name))));
+  }
+
+  getValidationRule(name) {
+    return this._resolved('validation rule', 'validation', name);
+  }
+
+  getDocumentTemplate(name) {
+    return this._resolved('document template', 'document_generation.templates', name);
+  }
+
+  getIntegration(name) {
+    return deepFreeze(deepClone(this._require('integrations', name)));
+  }
+
+  getThreshold(dotPath) {
+    const segments = dotPath.split('.');
+    let cur = this.masterConfig.thresholds;
+    for (const s of segments) {
+      if (cur == null) throw new Error(`[config] Threshold "${dotPath}" not found`);
+      cur = cur[s];
+    }
+    if (cur === undefined) throw new Error(`[config] Threshold "${dotPath}" not found`);
+    return typeof cur === 'object' ? deepFreeze(deepClone(cur)) : cur;
+  }
+
+  getTimingConfig() {
+    return this._cached('thresholds:timing', () => deepFreeze(deepClone(this.getThreshold('timing'))));
+  }
+
+  getSystemLimitsConfig() {
+    return this._cached('thresholds:system', () => deepFreeze(deepClone(this.getThreshold('system'))));
+  }
+
+  getUIConfig() {
+    return this._cached('thresholds:ui', () => deepFreeze(deepClone(this.getThreshold('ui'))));
+  }
+
+  getPollingConfig() {
+    return this._cached('thresholds:polling', () => deepFreeze(deepClone(this.getThreshold('polling'))));
+  }
+
+  getWorkflowStages(wfName) {
+    return (this.masterConfig.workflows?.[wfName]?.stages || []).map(s => typeof s === 'string' ? s : s.name);
+  }
+
+  getStageConfig(wfName, stageName) {
+    const stage = (this.masterConfig.workflows?.[wfName]?.stages || []).find(
+      s => (typeof s === 'string' ? s : s.name) === stageName
+    );
+    if (!stage) return null;
+    return deepFreeze(recursiveResolve(deepClone(typeof stage === 'string' ? { name: stage } : stage), this.masterConfig));
+  }
+
+  getEntitiesForDomain(domain) {
+    return [...(this._require('domains', domain).entities || [])];
+  }
+
+  isFeatureEnabled(name, ctx = {}) {
+    const f = this.masterConfig.features?.[name];
+    if (!f || f.enabled === false || f.deprecated) return false;
+    if (f.domain && ctx.domain && f.domain !== ctx.domain) return false;
+    if (f.workflow_stage && ctx.stage && f.workflow_stage !== ctx.stage) return false;
+    if (f.roles && ctx.role && !f.roles.includes(ctx.role)) return false;
+    if (f.requires && ctx.features && f.requires.some(r => !ctx.features.includes(r))) return false;
+    return true;
+  }
+
+  getFieldValue(entity, field) {
+    const spec = this.generateEntitySpec(entity);
+    if (!spec.fields?.[field]) throw new Error(`[config] Field "${field}" not found for entity "${entity}"`);
+    return deepFreeze(deepClone(spec.fields[field]));
+  }
+
+  getRolePermissions(role, entity) {
+    return [...(this.generateEntitySpec(entity).permissions?.[role] || [])];
+  }
+
+  canRoleDoAction(role, entity, action) {
+    const p = this.getRolePermissions(role, entity);
+    return p.includes(action) || p.includes('all');
+  }
+
+  generateNotificationHandler(name) {
+    return deepFreeze(recursiveResolve(deepClone(this._require('notifications', name)), this.masterConfig));
+  }
+
+  generateAutomationJob(name) {
+    const s = (this.masterConfig.automation?.schedules || []).find(s => s.name === name);
+    if (!s) throw new Error(`[config] Automation schedule "${name}" not found`);
+    return deepFreeze(recursiveResolve(deepClone(s), this.masterConfig));
+  }
+
+  cacheSpec(entityName, spec) {
+    if (!entityName || !spec) throw new Error('[config] cacheSpec requires entityName and spec');
+    this.specCache.set(`spec:${entityName}`, deepFreeze(spec));
+    return true;
+  }
+
+  invalidateCache() {
+    this.specCache.clear();
+    this.masterConfig = null;
+    return true;
+  }
+
+  enableDebug(enabled = true) {
+    this.debugMode = enabled;
+    return this;
+  }
+
+  /**
+   * Generate complete entity specification from config
+   * This is the main method that builds the spec used by CRUD, UI, etc.
+   */
+  generateEntitySpec(entityName) {
+    if (!entityName) throw new Error('[config] generateEntitySpec: entityName required');
+
+    const cacheKey = `spec:${entityName}`;
+    const cached = this.specCache.get(cacheKey);
+    if (cached) return deepFreeze(deepClone(cached));
+
+    const config = this.masterConfig;
+    let name = entityName;
+    let entityDef = config.entities?.[entityName] || (() => {
+      const match = Object.keys(config.entities || {}).find(k => {
+        const d = config.entities[k];
+        return (d.label_plural || d.label || k).toLowerCase() === entityName.toLowerCase();
+      });
+      if (match) {
+        name = match;
+        return config.entities[match];
+      }
+    })();
+
+    if (!entityDef) throw new Error(`[config] Entity "${entityName}" not found`);
+
+    entityDef = deepClone(entityDef);
+    const childrenObj = {};
+    (entityDef.children || []).forEach(c => { childrenObj[c] = { entity: c }; });
+
+    const spec = {
+      name,
+      label: entityDef.label || name,
+      labelPlural: entityDef.label_plural || entityDef.label || entityName,
+      icon: entityDef.icon || 'Circle',
+      order: entityDef.order || 999,
+      parent: entityDef.parent || null,
+      children: childrenObj,
+      computed_fields: entityDef.computed_fields || [],
+      has_timeline: entityDef.has_timeline || false,
+      has_roles: entityDef.has_roles || [],
+      has_pdf_viewer: entityDef.has_pdf_viewer || false,
+      has_collaboration: entityDef.has_collaboration || false,
+      has_tender_tracking: entityDef.has_tender_tracking || false,
+      has_notifications: entityDef.has_notifications || false,
+      has_authentication: entityDef.has_authentication || false,
+      has_google_sync: entityDef.has_google_sync || false,
+      recreation_enabled: entityDef.recreation_enabled || false,
+      recreation_intervals: entityDef.recreation_intervals || [],
+      immutable: entityDef.immutable || false,
+      immutable_strategy: entityDef.immutable_strategy || null,
+      state_machine: entityDef.state_machine || false,
+      row_access: entityDef.row_access || null,
+      embedded: entityDef.embedded || false,
+      system_entity: entityDef.system_entity || false,
+      fields: {},
+      options: {},
+    };
+
+    // Merge field overrides
+    if (entityDef.field_overrides) {
+      spec.field_overrides = recursiveResolve(entityDef.field_overrides, config);
+    }
+
+    // Build fields from definition + overrides + plugin additions
+    const baseFields = entityDef.fields || {};
+    const plugin = this._plugins.get(entityName);
+    const pluginFields = plugin?.fields || {};
+
+    // Combine and process fields
+    const allFields = {
+      ...baseFields,
+      ...spec.field_overrides,
+      ...pluginFields,
+    };
+
+    // Ensure required metadata (label, type defaults)
+    for (const [key, field] of Object.entries(allFields)) {
+      spec.fields[key] = {
+        type: field.type || 'text',
+        label: field.label || key,
+        required: field.required || false,
+        unique: field.unique || false,
+        readonly: field.readonly || field.readOnly || false,
+        hidden: field.hidden || false,
+        searchable: field.search || field.searchable || false,
+        sortable: field.sortable || field.sort || false,
+        default: field.default !== undefined ? field.default : null,
+        options: field.options || [],
+        ref: field.ref || null,
+        display: field.display || null,
+        auto: field.auto || null,
+        min: field.min,
+        max: field.max,
+        ...field,
+      };
+    }
+
+    // Permission matrix
+    if (entityDef.permission_template) {
+      const matrix = this.getPermissionTemplate(entityDef.permission_template);
+      const access = {};
+      const roleActions = {};
+
+      for (const [role, actions] of Object.entries(matrix)) {
+        if (!Array.isArray(actions)) continue;
+        roleActions[role] = [...actions];
+        actions.forEach(a => {
+          if (!access[a]) access[a] = [];
+          access[a].push(role);
+        });
+      }
+
+      spec.access = access;
+      spec.permissions = roleActions;
+    }
+
+    // Workflow binding
+    if (entityDef.workflow) {
+      const wf = this.getWorkflow(entityDef.workflow);
+      spec.workflow = wf;
+      spec.workflowDef = wf;
+      if (wf?.stages && Array.isArray(wf.stages)) {
+        const stagesObj = {};
+        wf.stages.forEach(s => {
+          stagesObj[typeof s === 'string' ? s : s.name] = s;
+        });
+        entityDef.stages = stagesObj;
+      }
+    }
+
+    // List options
+    if (entityDef.list) {
+      spec.list = {
+        defaultSort: entityDef.list.defaultSort || { field: 'created_at', dir: 'desc' },
+        pageSize: entityDef.list.pageSize || 50,
+        filters: entityDef.list.filters || [],
+        ...entityDef.list,
+      };
+    }
+
+    this.specCache.set(cacheKey, deepFreeze(spec));
+    return spec;
+  }
+
+  // Internal helpers
+
+  _cached(key, fn) {
+    const cached = this.specCache.get(key);
+    if (cached) return deepFreeze(deepClone(cached));
+    const value = fn();
+    this.specCache.set(key, value);
+    return value;
+  }
+
+  _require(section, key) {
+    const sectionData = this.masterConfig[section];
+    if (!sectionData) throw new Error(`[config] Missing section: ${section}`);
+    const value = sectionData[key];
+    if (value === undefined) throw new Error(`[config] Key "${key}" not found in ${section}`);
+    return value;
+  }
+
+  _resolved(type, section, key) {
+    const value = this._require(section, key);
+    return deepFreeze(recursiveResolve(deepClone(value), this.masterConfig));
+  }
+}
+
+/**
+ * Get or create singleton config engine
+ */
+let _singleton = null;
+
+export function getConfigEngineSync() {
+  if (!_singleton) {
+    throw new Error('ConfigEngine not initialized. Call initConfig() first.');
+  }
+  return _singleton;
+}
+
+export async function getConfigEngine() {
+  return getConfigEngineSync();
+}
+
+/**
+ * Initialize config engine from config source
+ * @param {string|object} configSource
+ * @returns {ConfigGeneratorEngine}
+ */
+export async function initConfig(configSource) {
+  const { loadConfig } = await import('../config/config-loader.js');
+  const { validateConfig, getConfigWithDefaults } = await import('../config/config-loader.js');
+
+  const rawConfig = await loadConfig(configSource);
+  const config = getConfigWithDefaults(rawConfig);
+  const errors = validateConfig(config);
+
+  if (errors.length > 0) {
+    throw new Error(`Configuration validation failed:\n- ${errors.join('\n- ')}`);
+  }
+
+  _singleton = new ConfigGeneratorEngine(config);
+  return _singleton;
+}
+
+/**
+ * Reset singleton (for hot reload)
+ */
+export function resetConfigEngine() {
+  _singleton = null;
+}

package/src/lib/config-helpers.js

@@ -0,0 +1,120 @@
+/**
+ * Configuration Helpers - Utilities for config processing
+ * LRUCache, deep cloning, freezing, recursive resolution
+ */
+
+/**
+ * LRU Cache implementation
+ */
+export class LRUCache {
+  constructor(maxSize = 100) {
+    this.maxSize = maxSize;
+    this.cache = new Map();
+  }
+
+  get(key) {
+    if (!this.cache.has(key)) return undefined;
+    const value = this.cache.get(key);
+    this.cache.delete(key);
+    this.cache.set(key, value);
+    return value;
+  }
+
+  set(key, value) {
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    } else if (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+    this.cache.set(key, value);
+  }
+
+  clear() {
+    this.cache.clear();
+  }
+
+  get size() {
+    return this.cache.size;
+  }
+}
+
+/**
+ * Deep freeze object (immutable)
+ */
+export function deepFreeze(obj) {
+  if (obj === null || typeof obj !== 'object') return obj;
+  if (Object.isFrozen(obj)) return obj;
+
+  Object.freeze(obj);
+  Object.getOwnPropertyNames(obj).forEach(prop => {
+    if (obj[prop] && typeof obj[prop] === 'object' && !Object.isFrozen(obj[prop])) {
+      deepFreeze(obj[prop]);
+    }
+  });
+  return obj;
+}
+
+/**
+ * Deep clone object
+ */
+export function deepClone(obj) {
+  if (obj === null || typeof obj !== 'object') return obj;
+  if (Array.isArray(obj)) return obj.map(deepClone);
+
+  const cloned = {};
+  for (const key of Object.keys(obj)) {
+    cloned[key] = deepClone(obj[key]);
+  }
+  return cloned;
+}
+
+/**
+ * Recursively resolve string template references in config
+ * Replaces ${ref.path} with value from config
+ */
+export function recursiveResolve(value, config) {
+  if (typeof value === 'string') {
+    return value.replace(/\$\{([^}]+)\}/g, (_, path) => {
+      const segments = path.split('.');
+      let current = config;
+      for (const seg of segments) {
+        if (current && typeof current === 'object' && seg in current) {
+          current = current[seg];
+        } else {
+          return _; // Keep original if not found
+        }
+      }
+      return typeof current === 'undefined' ? _ : current;
+    });
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(item => recursiveResolve(item, config));
+  }
+
+  if (value && typeof value === 'object') {
+    const resolved = {};
+    for (const [k, v] of Object.entries(value)) {
+      resolved[k] = recursiveResolve(v, config);
+    }
+    return resolved;
+  }
+
+  return value;
+}
+
+/**
+ * Merge objects deeply
+ */
+export function deepMerge(target, source) {
+  const output = { ...target };
+  for (const key of Object.keys(source)) {
+    if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+      output[key] = deepMerge(target[key] || {}, source[key]);
+    } else {
+      output[key] = source[key];
+    }
+  }
+  return output;
+}

package/src/lib/connection-guard.js

@@ -0,0 +1,79 @@
+class ConnectionGuard {
+  constructor(config) {
+    this.config = config
+    this.ipConnections = new Map()
+    this.messageRates = new Map()
+    this.pingIntervalId = null
+  }
+
+  checkConnectionLimit(ip) {
+    const count = this.ipConnections.get(ip) || 0
+    return count < this.config.maxConnectionsPerIP
+  }
+
+  trackIPConnection(ip) {
+    this.ipConnections.set(ip, (this.ipConnections.get(ip) || 0) + 1)
+  }
+
+  untrackIPConnection(ip) {
+    const count = this.ipConnections.get(ip) || 0
+    if (count <= 1) {
+      this.ipConnections.delete(ip)
+    } else {
+      this.ipConnections.set(ip, count - 1)
+    }
+  }
+
+  checkRateLimit(clientId) {
+    const now = Date.now()
+    const rate = this.messageRates.get(clientId) || { count: 0, window: now }
+
+    if (now - rate.window > 1000) {
+      rate.count = 1
+      rate.window = now
+    } else {
+      rate.count++
+    }
+
+    this.messageRates.set(clientId, rate)
+    return rate.count <= this.config.messageRateLimit
+  }
+
+  clearRateLimit(clientId) {
+    this.messageRates.delete(clientId)
+  }
+
+  startPingInterval(clients, onDead) {
+    this.pingIntervalId = setInterval(() => {
+      for (const [clientId, client] of clients) {
+        if (!client.alive) {
+          client.ws.terminate()
+          onDead(clientId)
+        } else {
+          client.alive = false
+          client.ws.ping()
+        }
+      }
+    }, this.config.pingInterval)
+  }
+
+  stopPingInterval() {
+    if (this.pingIntervalId) {
+      clearInterval(this.pingIntervalId)
+      this.pingIntervalId = null
+    }
+  }
+
+  generateClientId() {
+    return `client_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`
+  }
+
+  destroy() {
+    this.stopPingInterval()
+    this.ipConnections.clear()
+    this.messageRates.clear()
+  }
+}
+
+export { ConnectionGuard }
+export default ConnectionGuard

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

@@ -0,0 +1,34 @@
+import { AppError } from '@/lib/errors';
+import { HTTP } from '@/config/constants';
+import { now } from '@/lib/database-core';
+
+const ACTION_FIELD_MAPS = {
+  resolve_highlight: { status: 'resolved', color: 'green' },
+  reopen_highlight: { status: 'unresolved', color: 'grey', resolved_at: null, resolved_by: null, resolution_notes: null },
+  change_status: (data, user) => ({ status: data.status || data.toStatus, status_changed_at: now(), status_changed_by: user.id }),
+  respond: (data, user) => ({ status: 'responded', response: data.response, responded_at: now(), responded_by: user.id }),
+};
+
+export function resolveActionUpdate(action, data, user, record) {
+  const mapped = ACTION_FIELD_MAPS[action];
+  if (typeof mapped === 'function') return mapped(data, user);
+  if (mapped) {
+    const result = { ...mapped };
+    if (action === 'resolve_highlight') {
+      result.resolved_at = now();
+      result.resolved_by = user.id;
+      result.resolution_notes = data.notes || data.resolution_notes || '';
+    }
+    return result;
+  }
+  return data;
+}
+
+export function validateActionPrecondition(action, record) {
+  if (action === 'resolve_highlight' && record.status === 'resolved') {
+    throw new AppError('Highlight already resolved', 'BAD_REQUEST', HTTP.BAD_REQUEST);
+  }
+  if (action === 'reopen_highlight' && record.status !== 'resolved') {
+    throw new AppError('Highlight not resolved', 'BAD_REQUEST', HTTP.BAD_REQUEST);
+  }
+}