thatcher 1.0.4

package/src/lib/workflow-engine.js

@@ -0,0 +1,250 @@
+/**
+ * Workflow Engine - State machine management for entity lifecycle transitions
+ * Handles validation of state transitions and available actions
+ */
+
+import { get, update, create } from './query-engine.js';
+import { getConfigEngineSync } from './config-generator-engine.js';
+import { AppError } from './error-handler.js';
+import { HTTP } from '../config/constants.js';
+
+const LOCKOUT_SECONDS = 300; // 5 minutes default
+const workflowCache = new Map();
+
+/**
+ * Get workflow definition from config
+ * @param {string} workflowName
+ * @returns {object}
+ */
+function getWorkflowDef(workflowName) {
+  if (workflowCache.has(workflowName)) {
+    return workflowCache.get(workflowName);
+  }
+
+  const config = getConfigEngineSync().getConfig();
+  const wf = config?.workflows?.[workflowName];
+  if (!wf) throw new Error(`Workflow "${workflowName}" not found in config`);
+
+  const stageMap = {};
+  if (wf.stages) {
+    for (const stage of wf.stages) {
+      stageMap[stage.name] = stage;
+    }
+  }
+  if (wf.states) {
+    for (const state of wf.states) {
+      stageMap[state.name] = state;
+    }
+  }
+
+  const def = { ...wf, stageMap };
+  workflowCache.set(workflowName, def);
+  return def;
+}
+
+/**
+ * Validate a state transition
+ * @param {string} workflowName
+ * @param {string} fromState
+ * @param {string} toState
+ * @param {object} user
+ * @returns {{forward: boolean, backward: boolean}}
+ * @throws {AppError} if transition invalid
+ */
+export function validateTransition(workflowName, fromState, toState, user) {
+  const def = getWorkflowDef(workflowName);
+  const fromCfg = def.stageMap[fromState];
+  const toCfg = def.stageMap[toState];
+
+  if (!fromCfg) throw new AppError(`Invalid current state: ${fromState}`, 'INVALID_STATE', HTTP.BAD_REQUEST);
+  if (!toCfg) throw new AppError(`Invalid target state: ${toState}`, 'INVALID_STATE', HTTP.BAD_REQUEST);
+
+  const forward = fromCfg.forward || [];
+  const backward = fromCfg.backward || [];
+
+  if (!forward.includes(toState) && !backward.includes(toState)) {
+    throw new AppError(
+      `Cannot transition from "${fromState}" to "${toState}". Allowed: ${[...forward, ...backward].join(', ') || 'none'}`,
+      'TRANSITION_INVALID',
+      HTTP.BAD_REQUEST
+    );
+  }
+
+  // Role requirement check
+  const requiresRole = toCfg.requires_role || [];
+  if (requiresRole.length > 0 && user && !requiresRole.includes(user.role)) {
+    throw new AppError(`Role "${user.role}" cannot enter state "${toState}"`, 'INSUFFICIENT_PERMISSIONS', HTTP.FORBIDDEN);
+  }
+
+  // Entry constraint (e.g., partner_only)
+  if (toCfg.entry === 'partner_only' && user?.role !== 'partner') {
+    throw new AppError(`Only partners can enter "${toState}"`, 'ENTRY_CONSTRAINT', HTTP.FORBIDDEN);
+  }
+
+  // Readonly check
+  if (toCfg.readonly) {
+    throw new AppError(`State "${toState}" is read-only`, 'STATE_READONLY', HTTP.FORBIDDEN);
+  }
+
+  return {
+    forward: forward.includes(toState),
+    backward: backward.includes(toState),
+  };
+}
+
+/**
+ * Get available transitions for current state
+ * @param {string} workflowName
+ * @param {string} currentState
+ * @param {object} user
+ * @param {object} [record]
+ * @returns {Array<{stage: string, label: string, forward: boolean, backward: boolean}>}
+ */
+export function getAvailableTransitions(workflowName, currentState, user, record = null) {
+  const def = getWorkflowDef(workflowName);
+  const currentCfg = def.stageMap[currentState];
+  if (!currentCfg) return [];
+
+  const available = [];
+  const candidates = [...(currentCfg.forward || []), ...(currentCfg.backward || [])];
+  const currentOrder = currentCfg.order || 0;
+
+  for (const stateName of candidates) {
+    try {
+      // Lockout check based on last_transition_at
+      if (record?.last_transition_at) {
+        const elapsed = (Date.now() / 1000) - record.last_transition_at;
+        if (elapsed < LOCKOUT_SECONDS) continue;
+      }
+
+      validateTransition(workflowName, currentState, stateName, user);
+      const cfg = def.stageMap[stateName];
+      available.push({
+        stage: stateName,
+        label: cfg.label || stateName,
+        forward: (cfg.order || 0) > currentOrder,
+        backward: (cfg.order || 0) < currentOrder,
+      });
+    } catch {
+      // Skip invalid transitions
+    }
+  }
+
+  return available;
+}
+
+/**
+ * Get transition lockout status
+ * @param {object} record
+ * @returns {{inLockout: boolean, minutesRemaining: number, failedGates: Array}}
+ */
+export function getTransitionStatus(record) {
+  let inLockout = false;
+  let minutesRemaining = 0;
+
+  if (record?.last_transition_at) {
+    const elapsed = (Date.now() / 1000) - record.last_transition_at;
+    if (elapsed < LOCKOUT_SECONDS) {
+      inLockout = true;
+      minutesRemaining = Math.ceil((LOCKOUT_SECONDS - elapsed) / 60);
+    }
+  }
+
+  return { inLockout, minutesRemaining, failedGates: [] };
+}
+
+/**
+ * Execute a state transition
+ * @param {string} entityType
+ * @param {string} entityId
+ * @param {string} workflowName
+ * @param {string} toState
+ * @param {object} user
+ * @param {string} [reason='']
+ * @returns {Promise<object>} Updated record
+ */
+export async function transition(entityType, entityId, workflowName, toState, user, reason = '') {
+  // Validate transition
+  const record = get(entityType, entityId);
+  if (!record) throw new AppError('Record not found', 'NOT_FOUND', HTTP.NOT_FOUND);
+
+  validateTransition(workflowName, record.status || record.stage, toState, user);
+
+  // Update record
+  const updates = {
+    status: toState,
+    updated_at: Math.floor(Date.now() / 1000),
+  };
+
+  if (reason) {
+    updates.transition_reason = reason;
+  }
+
+  // Dynamically import write engine to avoid circular dependency
+  const { update: updateRecord } = await import('./query-engine-write.js');
+  const updated = updateRecord(entityType, entityId, updates, user);
+
+  // Execute hooks
+  executeHook(`transition:${entityType}`, {
+    entity: entityType,
+    id: entityId,
+    from: record.status,
+    to: toState,
+    user,
+    record: updated,
+  }).catch(err => console.error('transition hook error:', err));
+
+  return updated;
+}
+
+/**
+ * Get state field name for workflow (usually 'status' or 'stage')
+ * @param {string} workflowName
+ * @returns {string}
+ */
+export function getStateField(workflowName) {
+  const def = getWorkflowDef(workflowName);
+  return def.state_field || 'status';
+}
+
+/**
+ * Get stage labels mapping
+ * @param {string} workflowName
+ * @returns {object}
+ */
+export function getStageLabels(workflowName) {
+  const def = getWorkflowDef(workflowName);
+  const labels = {};
+  if (def.stages) {
+    for (const stage of def.stages) {
+      labels[stage.name] = stage.label || stage.name;
+    }
+  }
+  return labels;
+}
+
+/**
+ * Get locked fields for a state (readonly fields)
+ * @param {string} workflowName
+ * @param {string} state
+ * @returns {string[]}
+ */
+export function getStateLocks(workflowName, state) {
+  const def = getWorkflowDef(workflowName);
+  const stage = def.stageMap[state];
+  if (!stage) return [];
+  return stage.locks || [];
+}
+
+/**
+ * Get actions available in a state
+ * @param {string} workflowName
+ * @param {string} state
+ * @returns {string[]}
+ */
+export function getStateActions(workflowName, state) {
+  const def = getWorkflowDef(workflowName);
+  const stage = def.stageMap[state];
+  if (!stage) return [];
+  return stage.actions || [];
+}

package/src/server/server.js

@@ -0,0 +1,305 @@
+/**
+ * Thatcher HTTP Server - Simplified generic CRUD router
+ * Provides out-of-the-box API for all entities
+ */
+
+import http from 'http';
+import { fileURLToPath, pathToFileURL } from 'url';
+import * as thatcherLib from '../index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function createServer(options) {
+  const { thatcher, config, configEngine, port, host } = options;
+  const PORT = port || 3000;
+  const SERVER_START = Date.now();
+
+  let systemInitialized = false;
+  const moduleCache = new Map();
+
+  // Debug registry
+  globalThis.__debug__ = globalThis.__debug__ || {};
+  globalThis.__debug__.moduleCache = { get size() { return moduleCache.size; }, entries: () => [...moduleCache.keys()] };
+  globalThis.__debug__.activeRequests = { count: 0 };
+  globalThis.__debug__.hooks = null;
+  globalThis.__debug__.serverStart = SERVER_START;
+  globalThis.__debug__.uptime = () => Date.now() - SERVER_START;
+
+  // Load module with caching
+  const load = (p) => {
+    const cached = moduleCache.get(p);
+    if (cached) return cached;
+    return import(`file://${p}?t=${Date.now()}`).then(mod => {
+      moduleCache.set(p, mod);
+      return mod;
+    });
+  };
+
+  const server = http.createServer(async (req, res) => {
+    const t0 = Date.now();
+    globalThis.__debug__.activeRequests.count++;
+
+    try {
+      // Initialize on first request
+      if (!systemInitialized) {
+        const { loadPlugins } = await load(path.join(__dirname, '../plugins/index.js'));
+        await loadPlugins(configEngine);
+        systemInitialized = true;
+        console.log('[Server] System ready');
+      }
+
+      const url = new URL(req.url, `http://${req.headers.host}`);
+      const pathname = url.pathname;
+
+      // API routes
+      if (pathname.startsWith('/api/')) {
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        const parts = pathname.slice(5).split('/').filter(Boolean); // remove /api/
+
+        if (parts.length === 0) {
+          res.writeHead(400);
+          res.end(JSON.stringify({ error: 'Entity required' }));
+          return;
+        }
+
+        const entity = parts[0];
+        const id = parts[1] || null;
+        const action = parts[2] || null;
+
+        // Check if user has custom route for this
+        const userRoutePath = path.join(process.cwd(), 'app/api', ...parts, 'route.js');
+        const routeExists = await fileExists(userRoutePath);
+
+        if (routeExists) {
+          const mod = await load(userRoutePath);
+          const handler = mod[req.method] || mod.default;
+          if (handler) {
+            const response = await handler(req, { params: { entity, id, action, path: parts.slice(1) }, configEngine });
+            return sendResponse(res, response);
+          }
+        }
+
+        // Fall back to generic CRUD
+        return await handleGenericCrud(req, res, entity, id, action, thatcher);
+      }
+
+      // Static file serving (simplified)
+      if (serveStaticFile(pathname, req, res, load)) {
+        return;
+      }
+
+      // Page routing (UI)
+      if (!pathname.startsWith('/api/')) {
+        try {
+          const { handlePage } = await load(path.join(__dirname, '../ui/page-handler.js'));
+          const html = await handlePage(pathname, req, res, configEngine, thatcher);
+          if (html) {
+            res.setHeader('Content-Type', 'text/html; charset=utf-8');
+            res.setHeader('Content-Length', Buffer.byteLength(html, 'utf-8'));
+            res.writeHead(200);
+            res.end(html);
+            return;
+          }
+        } catch (e) {
+          console.error('[Page]', e.message);
+        }
+      }
+
+      // 404
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Not found' }));
+
+    } catch (err) {
+      console.error('[Server]', err.message);
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    } finally {
+      globalThis.__debug__.activeRequests.count--;
+    }
+  });
+
+  return server;
+}
+
+/**
+ * Serve static file if exists
+ */
+async function serveStaticFile(pathname, req, res, load) {
+  if (pathname === '/' || pathname === '/index.html') {
+    // Could serve SPA
+    return false;
+  }
+  // Try to serve from public/ or static/
+  const filePath = path.join(process.cwd(), 'public', pathname);
+  try {
+    if (await fileExists(filePath)) {
+      const content = await fs.promises.readFile(filePath);
+      const ext = path.extname(filePath);
+      const mime = {
+        '.js': 'application/javascript',
+        '.css': 'text/css',
+        '.html': 'text/html',
+        '.png': 'image/png',
+        '.jpg': 'image/jpeg',
+        '.svg': 'image/svg+xml',
+      }[ext] || 'text/plain';
+      res.setHeader('Content-Type', mime);
+      res.writeHead(200);
+      res.end(content);
+      return true;
+    }
+  } catch {}
+  return false;
+}
+
+/**
+ * File exists check
+ */
+function fileExists(p) {
+  try {
+    return fs.existsSync(p);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Send response appropriately
+ */
+async function sendResponse(res, response) {
+  const headerObj = {};
+  if (response.headers) {
+    for (const [k, v] of response.headers) {
+      headerObj[k] = v;
+    }
+  }
+
+  if (response.status >= 300 && response.status < 400) {
+    res.writeHead(response.status, headerObj);
+    res.end();
+    return;
+  }
+
+  const ct = (headerObj['Content-Type'] || '').toLowerCase();
+  const isJson = !ct || ct.includes('json');
+  let bodyOut;
+
+  if (isJson) {
+    bodyOut = JSON.stringify(await response.json());
+    if (!headerObj['Content-Type']) headerObj['Content-Type'] = 'application/json; charset=utf-8';
+  } else {
+    bodyOut = await response.text();
+  }
+
+  headerObj['Content-Length'] = Buffer.byteLength(bodyOut).toString();
+  res.writeHead(response.status, headerObj);
+  res.end(bodyOut);
+}
+
+/**
+ * Generic CRUD handler
+ */
+async function handleGenericCrud(req, res, entity, id, action, thatcher) {
+  // Simple auth: get from cookie or header
+  let user = null;
+  // In a real implementation, we'd decode session token
+  // For now, default to system user for testing
+  user = { id: 'system', role: 'admin' };
+
+  const { configEngine } = thatcher;
+  let spec;
+  try {
+    spec = configEngine.generateEntitySpec(entity);
+  } catch (e) {
+    res.writeHead(404);
+    res.end(JSON.stringify({ error: `Entity '${entity}' not found` }));
+    return;
+  }
+
+  // Permission check would go here via thatcher.can(user, spec, action)
+
+  let body;
+  try {
+    body = await readBody(req);
+  } catch (e) {
+    res.writeHead(400);
+    res.end(JSON.stringify({ error: 'Invalid JSON' }));
+    return;
+  }
+
+  try {
+    let result;
+    let status = 200;
+
+    switch (req.method) {
+      case 'GET':
+        if (id) {
+          result = await thatcher.get(entity, id);
+          if (!result) {
+            res.writeHead(404);
+            res.end(JSON.stringify({ error: 'Not found' }));
+            return;
+          }
+        } else {
+          result = await thatcher.list(entity);
+        }
+        break;
+
+      case 'POST':
+        result = await thatcher.create(entity, body, user);
+        status = 201;
+        break;
+
+      case 'PUT':
+      case 'PATCH':
+        if (!id) {
+          res.writeHead(400);
+          res.end(JSON.stringify({ error: 'ID required' }));
+          return;
+        }
+        result = await thatcher.update(entity, id, body, user);
+        break;
+
+      case 'DELETE':
+        if (!id) {
+          res.writeHead(400);
+          res.end(JSON.stringify({ error: 'ID required' }));
+          return;
+        }
+        await thatcher.delete(entity, id);
+        res.writeHead(204);
+        res.end();
+        return;
+
+      default:
+        res.writeHead(405);
+        res.end(JSON.stringify({ error: 'Method not allowed' }));
+        return;
+    }
+
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(result));
+  } catch (err) {
+    console.error('[API]', err.message);
+    res.writeHead(500);
+    res.end(JSON.stringify({ error: err.message }));
+  }
+}
+
+/**
+ * Read request body
+ */
+async function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    req.on('data', chunk => data += chunk);
+    req.on('end', () => {
+      try {
+        resolve(JSON.parse(data));
+      } catch {
+        resolve(data);
+      }
+    });
+    req.on('error', reject);
+  });
+}