thatcher 1.0.4 → 1.0.6

package/src/lib/perf-profiler.js

@@ -0,0 +1,238 @@
+/**
+ * Performance Profiler - Threshold-based profiling with regression detection
+ * Per-operation p50/p95/p99 statistics with automatic alerting
+ */
+
+import { createLogger } from './logger.js';
+
+const logger = createLogger('[PerfProfiler]');
+
+const _profiles = new Map();
+const _thresholds = new Map();
+const _alerts = [];
+const MAX_ALERTS = 100;
+const BASELINE_WINDOW_MS = 3600000;
+
+const DEFAULT_THRESHOLDS = {
+  'http.request': 500,
+  'db.query': 100,
+  'db.write': 200,
+  'hook.execute': 50,
+  'workflow.transition': 100,
+  'formula.evaluate': 50,
+  'auth.login': 300,
+  'render.page': 200,
+};
+
+export class PerfProfiler {
+  constructor() {
+    this._profiles = _profiles;
+    this._thresholds = new Map(Object.entries(DEFAULT_THRESHOLDS));
+  }
+
+  setThreshold(operation, thresholdMs) {
+    this._thresholds.set(operation, thresholdMs);
+  }
+
+  getThreshold(operation) {
+    return this._thresholds.get(operation) || 100;
+  }
+
+  record(operation, durationMs, metadata = {}) {
+    let profile = _profiles.get(operation);
+    if (!profile) {
+      profile = {
+        operation,
+        count: 0,
+        totalMs: 0,
+        minMs: Infinity,
+        maxMs: 0,
+        durations: [],
+        slowCount: 0,
+        lastRecorded: null,
+        metadata: {},
+      };
+      _profiles.set(operation, profile);
+    }
+
+    profile.count++;
+    profile.totalMs += durationMs;
+    profile.minMs = Math.min(profile.minMs, durationMs);
+    profile.maxMs = Math.max(profile.maxMs, durationMs);
+    profile.lastRecorded = Date.now();
+
+    profile.durations.push({ durationMs, timestamp: Date.now(), ...metadata });
+    while (profile.durations.length > 10000) {
+      profile.durations.shift();
+    }
+
+    const threshold = this.getThreshold(operation);
+    if (durationMs > threshold) {
+      profile.slowCount++;
+      this._maybeAlert(operation, durationMs, threshold, metadata);
+    }
+
+    return profile;
+  }
+
+  async measure(operation, fn, metadata = {}) {
+    const start = performance.now();
+    try {
+      const result = await fn();
+      const duration = performance.now() - start;
+      this.record(operation, duration, metadata);
+      return result;
+    } catch (error) {
+      const duration = performance.now() - start;
+      this.record(operation, duration, { ...metadata, error: error.message });
+      throw error;
+    }
+  }
+
+  measureSync(operation, fn, metadata = {}) {
+    const start = performance.now();
+    try {
+      const result = fn();
+      const duration = performance.now() - start;
+      this.record(operation, duration, metadata);
+      return result;
+    } catch (error) {
+      const duration = performance.now() - start;
+      this.record(operation, duration, { ...metadata, error: error.message });
+      throw error;
+    }
+  }
+
+  getStats(operation) {
+    const profile = _profiles.get(operation);
+    if (!profile) return null;
+
+    const durations = profile.durations.map(d => d.durationMs).sort((a, b) => a - b);
+    const count = durations.length;
+
+    return {
+      operation: profile.operation,
+      count: profile.count,
+      totalMs: profile.totalMs,
+      avgMs: profile.count > 0 ? profile.totalMs / profile.count : 0,
+      minMs: profile.minMs === Infinity ? 0 : profile.minMs,
+      maxMs: profile.maxMs,
+      p50: this._percentile(durations, 50),
+      p95: this._percentile(durations, 95),
+      p99: this._percentile(durations, 99),
+      slowCount: profile.slowCount,
+      threshold: this.getThreshold(operation),
+      lastRecorded: profile.lastRecorded,
+    };
+  }
+
+  getAllStats() {
+    return Array.from(_profiles.keys()).map(key => this.getStats(key));
+  }
+
+  getSlowOperations() {
+    return this.getAllStats()
+      .filter(s => s.slowCount > 0)
+      .sort((a, b) => b.slowCount - a.slowCount);
+  }
+
+  detectRegressions(windowMs = 300000) {
+    const regressions = [];
+    const now = Date.now();
+
+    for (const [operation, profile] of _profiles.entries()) {
+      const recent = profile.durations.filter(d => now - d.timestamp < windowMs);
+      const older = profile.durations.filter(d => now - d.timestamp >= windowMs && now - d.timestamp < windowMs * 2);
+
+      if (recent.length < 10 || older.length < 10) continue;
+
+      const recentAvg = recent.reduce((sum, d) => sum + d.durationMs, 0) / recent.length;
+      const olderAvg = older.reduce((sum, d) => sum + d.durationMs, 0) / older.length;
+
+      if (olderAvg > 0 && recentAvg > olderAvg * 1.5) {
+        regressions.push({
+          operation,
+          recentAvg: Math.round(recentAvg * 100) / 100,
+          olderAvg: Math.round(olderAvg * 100) / 100,
+          regressionPercent: Math.round((recentAvg / olderAvg - 1) * 100),
+          sampleSize: recent.length,
+        });
+      }
+    }
+
+    return regressions;
+  }
+
+  getAlerts() {
+    return [..._alerts];
+  }
+
+  clearAlerts() {
+    _alerts.length = 0;
+  }
+
+  clear() {
+    _profiles.clear();
+    _alerts.length = 0;
+  }
+
+  _percentile(sorted, p) {
+    if (sorted.length === 0) return 0;
+    const index = Math.ceil((p / 100) * sorted.length) - 1;
+    return sorted[Math.max(0, index)];
+  }
+
+  _maybeAlert(operation, durationMs, thresholdMs, metadata) {
+    const alertKey = `${operation}:slow`;
+    const existing = _alerts.find(a => a.key === alertKey && Date.now() - a.timestamp < 60000);
+    if (existing) return;
+
+    const alert = {
+      key: alertKey,
+      operation,
+      type: 'slow_operation',
+      durationMs: Math.round(durationMs * 100) / 100,
+      thresholdMs,
+      severity: durationMs > thresholdMs * 5 ? 'critical' : durationMs > thresholdMs * 2 ? 'warning' : 'info',
+      timestamp: Date.now(),
+      metadata,
+    };
+
+    _alerts.push(alert);
+    while (_alerts.length > MAX_ALERTS) {
+      _alerts.shift();
+    }
+
+    logger.warn('Slow operation detected', alert);
+  }
+}
+
+export const perfProfiler = new PerfProfiler();
+
+export function createPerfProfiler() {
+  return new PerfProfiler();
+}
+
+export function getPerfProfiler() {
+  return perfProfiler;
+}
+
+export async function measurePerf(operation, fn, metadata = {}) {
+  return perfProfiler.measure(operation, fn, metadata);
+}
+
+export function measurePerfSync(operation, fn, metadata = {}) {
+  return perfProfiler.measureSync(operation, fn, metadata);
+}
+
+export default PerfProfiler;
+
+if (globalThis.__debug__) {
+  globalThis.__debug__.expose('perf', {
+    stats: (op) => op ? perfProfiler.getStats(op) : perfProfiler.getAllStats(),
+    slow: () => perfProfiler.getSlowOperations(),
+    regressions: () => perfProfiler.detectRegressions(),
+    alerts: () => perfProfiler.getAlerts(),
+    thresholds: () => Object.fromEntries(perfProfiler._thresholds),
+  }, 'Performance Profiler');
+}

package/src/lib/query-engine.js

@@ -42,6 +42,22 @@ function execGet(sql, params = [], context = {}) {
   }
 }
 
+/**
+ * Execute a write statement (INSERT/UPDATE/DELETE) with error handling
+ * @param {string} sql
+ * @param {Array} params
+ * @param {object} context
+ * @returns {object} better-sqlite3 RunResult
+ */
+function execRun(sql, params = [], context = {}) {
+  try {
+    return db.prepare(sql).run(...params);
+  } catch (e) {
+    logger.error(`${context.operation || 'Run'} ${context.entity || ''}`, { sql, error: e.message });
+    throw new Error(`Database run failed: ${e.message}`);
+  }
+}
+
 /**
  * Get table name for entity (users vs user)
  * @param {object} spec
@@ -345,6 +361,28 @@ export function getChildren(parentEntity, parentId, childDef) {
   return execQuery(sql, [parentId], { entity: childDef.entity, operation: 'GetChildren' });
 }
 
+/**
+ * Batch-fetch children of a parent for several child definitions at once.
+ * Ported from moonlanding; uses thatcher's `list` + getChildren fk convention
+ * (`fk`, falling back to moon's `foreignKey`, then `${parentEntity}_id`).
+ * @param {string} parentEntity
+ * @param {string|number} parentId
+ * @param {object|Array} childSpecs - map of key->def, or array of entity names
+ * @returns {Promise<object>} map of key -> rows
+ */
+export function batchGetChildren(parentEntity, parentId, childSpecs) {
+  const childEntries = Array.isArray(childSpecs)
+    ? childSpecs.map(s => [s, { entity: s }])
+    : Object.entries(childSpecs);
+  const queries = childEntries.map(async ([key, def]) => {
+    const entity = def.entity || def;
+    const foreignKey = def.fk || def.foreignKey || `${parentEntity}_id`;
+    const results = list(entity, { [foreignKey]: parentId });
+    return [key, results];
+  });
+  return Promise.all(queries).then(results => Object.fromEntries(results));
+}
+
 /**
  * Get pagination config from system settings
  * @param {object} spec - Entity spec
@@ -397,3 +435,12 @@ export async function withTransaction(callback) {
     throw e;
   }
 }
+
+// Re-export write operations so consumers can import all CRUD from a single
+// module (ported from moonlanding). Several thatcher modules already import
+// `create`/`update`/`remove` from './query-engine.js'; this wires them through
+// to the existing write implementation without changing those callers.
+export { create, update, remove } from './query-engine-write.js';
+
+// Expose low-level executors for callers that need raw SQL access.
+export { execQuery, execGet, execRun };

package/src/lib/query-string-adapter.js

@@ -3,6 +3,10 @@
  * Adapted from moonlanding/src/lib/query-string-adapter.js
  */
 
+// Thatcher uses a fixed default page size (no async config-engine lookup);
+// keeps QueryAdapter helpers synchronous to match existing call sites.
+const DEFAULT_PAGE_SIZE = 50;
+
 /**
  * Parse query string from URL
  * @param {object} request - Fetch Request or NextRequest-like
@@ -67,9 +71,100 @@ function coerceValue(value) {
 export function getDefault(key) {
   const defaults = {
     page: 1,
-    pageSize: 50,
+    pageSize: DEFAULT_PAGE_SIZE,
     q: null,
     filters: {},
+    sortDir: 'asc',
+    limit: null,
+    offset: null,
   };
-  return defaults[key];
+  return defaults[key] ?? null;
+}
+
+/**
+ * QueryAdapter - static helpers for parsing and building query strings.
+ * Ported from moonlanding; methods kept synchronous to match thatcher call sites
+ * (e.g. api.js destructures QueryAdapter.fromSearchParams(...) without await).
+ */
+export class QueryAdapter {
+  /**
+   * Parse a Request-like object. Delegates to thatcher's parseQuery so the
+   * returned shape ({ q, page, pageSize, filters, sort }) stays consistent.
+   */
+  static parse(request) {
+    return parseQuery(request);
+  }
+
+  /**
+   * Extract non-reserved filter params from a URLSearchParams instance.
+   */
+  static extractFilters(searchParams) {
+    const filters = {};
+    const reserved = new Set(['q', 'page', 'pageSize', 'page_size', 'action', 'limit', 'offset', 'sort', 'sortBy', 'dir', 'direction', 'sortDir', 'domain']);
+    for (const [key, value] of searchParams) {
+      if (!reserved.has(key) && value) {
+        filters[key] = value;
+      }
+    }
+    return filters;
+  }
+
+  /**
+   * Build a URLSearchParams from a params object, dropping empty values.
+   */
+  static build(params = {}) {
+    const query = new URLSearchParams();
+    Object.entries(params)
+      .filter(([, v]) => v !== undefined && v !== null && v !== '')
+      .forEach(([k, v]) => query.append(k, v));
+    return query;
+  }
+
+  /**
+   * Build a full URL from a base and params object.
+   */
+  static buildUrl(baseUrl, params = {}) {
+    const queryString = QueryAdapter.build(params).toString();
+    return queryString ? `${baseUrl}?${queryString}` : baseUrl;
+  }
+
+  /**
+   * Get a default value for a config key (synchronous; delegates to getDefault).
+   */
+  static getDefault(key) {
+    return getDefault(key);
+  }
+
+  /**
+   * Parse pagination params from a URLSearchParams instance OR a plain object.
+   * Synchronous so callers can destructure the result directly.
+   */
+  static fromSearchParams(searchParams, spec = null) {
+    const get = (key) => {
+      if (searchParams && typeof searchParams.get === 'function') {
+        return searchParams.get(key);
+      }
+      return searchParams ? searchParams[key] : undefined;
+    };
+    const pageSizeParam = get('pageSize') || get('limit') || String(spec?.list?.pageSize || DEFAULT_PAGE_SIZE);
+    return {
+      q: get('q') || null,
+      page: Math.max(1, parseInt(get('page') || '1', 10)),
+      pageSize: parseInt(pageSizeParam, 10),
+    };
+  }
+
+  /**
+   * Serialize a params object to a query string.
+   */
+  static toQueryString(params = {}) {
+    return QueryAdapter.build(params).toString();
+  }
 }
+
+// Named exports matching moonlanding's surface, so consumers importing
+// `parse`, `build`, `buildUrl`, `fromSearchParams` resolve correctly.
+export const parse = (request) => QueryAdapter.parse(request);
+export const build = (params) => QueryAdapter.build(params);
+export const buildUrl = (baseUrl, params) => QueryAdapter.buildUrl(baseUrl, params);
+export const fromSearchParams = (searchParams, spec) => QueryAdapter.fromSearchParams(searchParams, spec);

package/src/lib/request-tracing.js

@@ -0,0 +1,216 @@
+/**
+ * Request Tracing Middleware - Instruments all HTTP requests with distributed tracing
+ * Wraps handlers with automatic trace/span creation and context propagation
+ */
+
+import { tracer } from './tracing.js';
+import { perfProfiler } from './perf-profiler.js';
+import { createLogger } from './logger.js';
+
+const logger = createLogger('[RequestTracing]');
+
+export function withTracing(handler) {
+  return async (req, ...rest) => {
+    const method = req.method || 'UNKNOWN';
+    const url = req.url || '/';
+    const path = url.split('?')[0];
+
+    const traceparent = req.headers?.['traceparent'] || req.headers?.['x-traceparent'];
+    const extracted = traceparent ? tracer.extractTraceparent(traceparent) : null;
+
+    const attributes = {
+      'http.method': method,
+      'http.url': url,
+      'http.path': path,
+      'http.user_agent': req.headers?.['user-agent'],
+      'http.client_ip': req.headers?.['x-forwarded-for'] || req.socket?.remoteAddress,
+    };
+
+    if (extracted) {
+      attributes['traceparent'] = traceparent;
+    }
+
+    return tracer.withSpan(`${method} ${path}`, async (span) => {
+      span.setAttributes(attributes);
+
+      const start = performance.now();
+
+      try {
+        let response;
+        if (rest.length > 0) {
+          response = await handler(req, ...rest);
+        } else {
+          response = await handler(req);
+        }
+
+        const duration = performance.now() - start;
+        const statusCode = response?.status || response?.statusCode || 200;
+
+        span.setAttribute('http.status_code', statusCode);
+        span.setAttribute('http.duration_ms', Math.round(duration * 100) / 100);
+
+        perfProfiler.record('http.request', duration, { method, path, statusCode });
+
+        return response;
+      } catch (error) {
+        span.recordException(error);
+        throw error;
+      }
+    }, { attributes });
+  };
+}
+
+export function withDbTracing(db, queryName = 'db.query') {
+  const original = { prepare: db.prepare?.bind(db) };
+
+  if (db.prepare) {
+    db.prepare = function(sql) {
+      const stmt = original.prepare(sql);
+
+      const wrapped = {};
+      for (const method of ['run', 'get', 'all']) {
+        if (stmt[method]) {
+          wrapped[method] = async function(...args) {
+            return tracer.withSpan(`${queryName}:${method}`, async (span) => {
+              span.setAttributes({
+                'db.statement': sql,
+                'db.operation': method,
+                'db.system': 'sqlite',
+              });
+
+              const start = performance.now();
+              try {
+                const result = stmt[method].call(stmt, ...args);
+                const duration = performance.now() - start;
+
+                span.setAttribute('db.duration_ms', Math.round(duration * 100) / 100);
+                perfProfiler.record(`db.${method}`, duration, { sql: sql.slice(0, 100) });
+
+                return result;
+              } catch (error) {
+                span.recordException(error);
+                throw error;
+              }
+            });
+          };
+        }
+      }
+
+      return { ...stmt, ...wrapped };
+    };
+  }
+
+  return db;
+}
+
+export function withHookTracing(hookEngine) {
+  const originalExecute = hookEngine.execute.bind(hookEngine);
+  const originalPipe = hookEngine.pipe.bind(hookEngine);
+
+  hookEngine.execute = async function(name, data, options) {
+    return tracer.withSpan(`hook:${name}`, async (span) => {
+      span.setAttributes({
+        'hook.name': name,
+        'hook.handler_count': hookEngine.listeners(name).length,
+      });
+
+      const start = performance.now();
+      try {
+        const result = await originalExecute(name, data, options);
+        const duration = performance.now() - start;
+
+        span.setAttribute('hook.duration_ms', Math.round(duration * 100) / 100);
+        perfProfiler.record('hook.execute', duration, { name });
+
+        return result;
+      } catch (error) {
+        span.recordException(error);
+        throw error;
+      }
+    });
+  };
+
+  hookEngine.pipe = async function(name, data) {
+    return tracer.withSpan(`hook:pipe:${name}`, async (span) => {
+      span.setAttributes({
+        'hook.name': name,
+        'hook.handler_count': hookEngine.listeners(name).length,
+      });
+
+      const start = performance.now();
+      try {
+        const result = await originalPipe(name, data);
+        const duration = performance.now() - start;
+
+        span.setAttribute('hook.duration_ms', Math.round(duration * 100) / 100);
+
+        return result;
+      } catch (error) {
+        span.recordException(error);
+        throw error;
+      }
+    });
+  };
+
+  return hookEngine;
+}
+
+export function addTraceHeaders(response, traceId) {
+  if (!traceId) return response;
+
+  if (response?.headers) {
+    response.headers['X-Trace-Id'] = traceId;
+  }
+
+  if (typeof response?.setHeader === 'function') {
+    response.setHeader('X-Trace-Id', traceId);
+  }
+
+  return response;
+}
+
+export function createTracingMiddleware() {
+  return (req, res, next) => {
+    const traceparent = req.headers?.['traceparent'];
+    const extracted = traceparent ? tracer.extractTraceparent(traceparent) : null;
+
+    const { span, context } = tracer.startSpan(`${req.method} ${req.url}`, {
+      attributes: {
+        'http.method': req.method,
+        'http.url': req.url,
+        'http.user_agent': req.headers?.['user-agent'],
+      },
+    });
+
+    if (extracted) {
+      span.setAttribute('trace.parent', traceparent);
+    }
+
+    const originalEnd = res.end;
+    const originalWriteHead = res.writeHead;
+
+    res.writeHead = function(...args) {
+      span.setAttribute('http.status_code', args[0]);
+      return originalWriteHead.apply(this, args);
+    };
+
+    res.end = function(...args) {
+      const duration = performance.now() - span.startTime;
+      span.setAttribute('http.duration_ms', Math.round(duration * 100) / 100);
+      span.end();
+
+      tracer._exportSpan(span);
+
+      return originalEnd.apply(this, args);
+    };
+
+    req.traceId = context.traceId;
+    req.span = span;
+
+    if (next) {
+      return next();
+    }
+  };
+}
+
+export default withTracing;

package/src/lib/response-formatter.js

@@ -76,5 +76,3 @@ export function error(message, status = HTTP.INTERNAL_ERROR, code = 'ERROR') {
 export function withMetadata(data, status, type = 'success') {
   return { ...data, _meta: { status, type, timestamp: Date.now() } };
 }
-
-import { HTTP } from '../config/constants.js';

package/src/lib/route-resolver.js

@@ -62,6 +62,16 @@ export function buildNestedRoutePath(baseDir, domain, parentEntity, childParts)
     () => buildSegments('[id]', () => `[${singularize(childParts[0])}Id]`),
   ];
 
+  // Also try a "leaf-action" shape with no further id after the child segment.
+  // Routes like /mwr/review/[id]/export-pdf/route.js (parent + id + leaf action)
+  // were missed by the segment-pair variants above.
+  if (childParts.length === 1) {
+    const leaf = path.join(baseDir, 'src/app/api', domain, parentEntity, '[id]', childParts[0], 'route.js');
+    if (fs.existsSync(leaf)) return leaf;
+    const leafByEntity = path.join(baseDir, 'src/app/api', domain, parentEntity, `[${parentEntity}Id]`, childParts[0], 'route.js');
+    if (fs.existsSync(leafByEntity)) return leafByEntity;
+  }
+
   for (const variant of variants) {
     const candidate = variant();
     if (fs.existsSync(candidate)) return candidate;