thatcher 1.0.4 → 1.0.6

package/src/lib/debug-registry.js

@@ -0,0 +1,165 @@
+/**
+ * Debug Registry - Comprehensive globalThis.__debug__ registry for all Thatcher subsystems
+ * Modules register on import/init; supports nested namespaces and live data
+ */
+
+import { createLogger } from './logger.js';
+
+const logger = createLogger('[DebugRegistry]');
+
+class DebugRegistry {
+  constructor() {
+    this._modules = new Map();
+    this._metadata = new Map();
+  }
+
+  expose(path, valueOrGetter, description = '') {
+    const parts = path.split('.');
+    const leaf = parts.pop();
+
+    let current = this._modules;
+    for (const part of parts) {
+      if (!current.has(part)) {
+        current.set(part, new Map());
+      }
+      current = current.get(part);
+    }
+
+    current.set(leaf, valueOrGetter);
+    this._metadata.set(path, { description, registeredAt: Date.now() });
+
+    this._syncToGlobal();
+    return this;
+  }
+
+  remove(path) {
+    const parts = path.split('.');
+    const leaf = parts.pop();
+
+    let current = this._modules;
+    for (const part of parts) {
+      if (!current.has(part)) return this;
+      current = current.get(part);
+    }
+
+    current.delete(leaf);
+    this._metadata.delete(path);
+
+    this._syncToGlobal();
+    return this;
+  }
+
+  get(path) {
+    const parts = path.split('.');
+    let current = this._modules;
+
+    for (const part of parts) {
+      if (!current.has(part)) return undefined;
+      current = current.get(part);
+    }
+
+    return typeof current === 'function' ? current() : current;
+  }
+
+  inspect(path) {
+    const value = this.get(path);
+    if (value === undefined) return { error: `Path "${path}" not found` };
+
+    const meta = this._metadata.get(path);
+    return {
+      path,
+      value: typeof value === 'function' ? value() : value,
+      metadata: meta,
+    };
+  }
+
+  list(prefix = '') {
+    const results = [];
+    for (const [path, meta] of this._metadata.entries()) {
+      if (!prefix || path.startsWith(prefix)) {
+        results.push({ path, description: meta.description, registeredAt: meta.registeredAt });
+      }
+    }
+    return results;
+  }
+
+  health() {
+    const checks = {};
+
+    if (globalThis.healthState) {
+      checks.health = globalThis.healthState;
+    }
+
+    if (globalThis.__resources) {
+      checks.resources = globalThis.__resources;
+    }
+
+    if (globalThis.__alerts) {
+      checks.alerts = globalThis.__alerts;
+    }
+
+    if (globalThis.__dbMonitor) {
+      checks.database = {
+        activeQueries: globalThis.__dbMonitor?.activeQueries?.length || 0,
+        slowQueries: globalThis.__dbMonitor?.slowQueries?.length || 0,
+      };
+    }
+
+    checks.modules = this._modules.size;
+    checks.uptime = process.uptime();
+    checks.memory = process.memoryUsage();
+
+    return checks;
+  }
+
+  toJSON() {
+    return this.list().map(item => ({
+      ...item,
+      value: this.get(item.path),
+    }));
+  }
+
+  _syncToGlobal() {
+    if (!globalThis.__debug__) {
+      globalThis.__debug__ = {
+        expose: (path, value, desc) => this.expose(path, value, desc),
+        get: (path) => this.get(path),
+        inspect: (path) => this.inspect(path),
+        list: (prefix) => this.list(prefix),
+        health: () => this.health(),
+        remove: (path) => this.remove(path),
+      };
+    } else {
+      globalThis.__debug__.expose = (path, value, desc) => this.expose(path, value, desc);
+      globalThis.__debug__.get = (path) => this.get(path);
+      globalThis.__debug__.inspect = (path) => this.inspect(path);
+      globalThis.__debug__.list = (prefix) => this.list(prefix);
+      globalThis.__debug__.health = () => this.health();
+      globalThis.__debug__.remove = (path) => this.remove(path);
+    }
+  }
+}
+
+export const debugRegistry = new DebugRegistry();
+
+export function expose(path, value, description = '') {
+  return debugRegistry.expose(path, value, description);
+}
+
+export function removeDebug(path) {
+  return debugRegistry.remove(path);
+}
+
+export function getDebug(path) {
+  return debugRegistry.get(path);
+}
+
+export function inspectDebug(path) {
+  return debugRegistry.inspect(path);
+}
+
+export function listDebug(prefix = '') {
+  return debugRegistry.list(prefix);
+}
+
+export default DebugRegistry;

package/src/lib/error-handler.js

@@ -80,5 +80,83 @@ export function createErrorLogger(context = '') {
     warn: (msg, meta = {}) => {
       console.warn(`[${context}] ${msg}`, meta);
     },
+    info: (_msg, _meta = {}) => {},
+    debug: (msg, meta = {}) => {
+      if (process.env.DEBUG) {
+        console.debug(`[${context}] Debug:`, msg, meta);
+      }
+    },
+  };
+}
+
+/**
+ * Normalize an arbitrary thrown value into one of thatcher's AppError-class
+ * instances. AppError instances (and anything already shaped like one — a
+ * numeric `status` + a `code`) pass through untouched; common low-level
+ * errors are mapped to the appropriate thatcher error class.
+ *
+ * (Ported from moonlanding, adapted to thatcher's class-based hierarchy and
+ * its `status`/`code`/`details` shape. Kept import-free so the module stays
+ * loadable under the plain-node test runner.)
+ * @param {unknown} error
+ * @returns {AppError}
+ */
+export function normalizeError(error) {
+  if (error instanceof AppError) {
+    return error;
+  }
+
+  if (error && typeof error === 'object' && typeof error.status === 'number' && error.code) {
+    return error;
+  }
+
+  if (error instanceof SyntaxError) {
+    return new BadRequestError('Invalid request format');
+  }
+
+  if (error instanceof TypeError) {
+    return new AppError('Invalid operation', 'TYPE_ERROR', 400, { originalMessage: error.message });
+  }
+
+  const message = error && error.message ? String(error.message) : '';
+
+  if (message.includes('database is locked')) {
+    return new DatabaseError('operation', error);
+  }
+
+  if (message.includes('UNIQUE constraint failed')) {
+    const field = message.match(/UNIQUE constraint failed: (.+)/)?.[1] || 'record';
+    return new ConflictError(`${field} already exists`);
+  }
+
+  return new AppError(message || 'An unexpected error occurred', 'INTERNAL_ERROR', 500, {
+    originalMessage: message,
+    stack: error && error.stack ? error.stack.split('\n').slice(0, 3).join('\n') : undefined,
+  });
+}
+
+/**
+ * Build a JSON-serializable error response body from any thrown value.
+ * (Ported from moonlanding, adapted to thatcher's error shape.)
+ * @param {unknown} error
+ * @param {boolean} [includeStack=false]
+ * @returns {object}
+ */
+export function formatErrorResponse(error, includeStack = false) {
+  const normalized = normalizeError(error);
+  const response = {
+    status: 'error',
+    message: normalized.message,
+    code: normalized.code,
+    statusCode: normalized.status,
   };
+
+  if (normalized.details) response.details = normalized.details;
+  if (normalized.errors) response.errors = normalized.errors;
+
+  if (includeStack && error && error.stack) {
+    response.stack = error.stack.split('\n').slice(0, 5);
+  }
+
+  return response;
 }

package/src/lib/export-sink.js

@@ -0,0 +1,226 @@
+/**
+ * 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';
+
+const logger = createLogger('[ExportSink]');
+
+const BATCH_DEFAULT_SIZE = 100;
+const BATCH_DEFAULT_INTERVAL_MS = 5000;
+const MAX_QUEUE_SIZE = 10000;
+const RETRY_BACKOFF_MS = [1000, 2000, 5000, 10000, 30000];
+
+export class ExportSink {
+  constructor(options = {}) {
+    this.target = options.target || process.env.OBSERVABILITY_EXPORT_TARGET || 'stdout';
+    this.url = options.url || process.env.OBSERVABILITY_EXPORT_URL || '';
+    this.batchSize = options.batchSize || BATCH_DEFAULT_SIZE;
+    this.batchIntervalMs = options.batchIntervalMs || BATCH_DEFAULT_INTERVAL_MS;
+    this._queue = [];
+    this._running = false;
+    this._timer = null;
+    this._exportCount = 0;
+    this._errorCount = 0;
+    this._lastError = null;
+  }
+
+  async init() {
+    if (this.target === 'file') {
+      this._filePath = options.filePath || process.env.OBSERVABILITY_EXPORT_FILE || path.join(process.cwd(), 'observability.jsonl');
+      logger.info('File export sink initialized', { path: this._filePath });
+    } else if (this.target === 'http') {
+      if (!this.url) {
+        logger.error('HTTP export requires OBSERVABILITY_EXPORT_URL');
+        return;
+      }
+      logger.info('HTTP export sink initialized', { url: this.url });
+    } else {
+      logger.info('Stdout export sink initialized');
+    }
+
+    this._startBatchLoop();
+    globalThis.__trace_export__ = this;
+
+    return this;
+  }
+
+  async export(span) {
+    if (this._queue.length >= MAX_QUEUE_SIZE) {
+      this._queue.shift();
+    }
+
+    this._queue.push(span);
+
+    if (this._queue.length >= this.batchSize) {
+      await this._flush();
+    }
+  }
+
+  async _flush() {
+    if (this._queue.length === 0 || this._running) return;
+
+    this._running = true;
+    const batch = this._queue.splice(0, this.batchSize);
+
+    try {
+      await this._sendBatch(batch);
+      this._exportCount += batch.length;
+    } catch (error) {
+      this._errorCount += batch.length;
+      this._lastError = error.message;
+      logger.error('Export failed', { error: error.message, target: this.target });
+
+      this._queue.unshift(...batch);
+      if (this._queue.length > MAX_QUEUE_SIZE) {
+        this._queue.length = MAX_QUEUE_SIZE;
+      }
+    } finally {
+      this._running = false;
+    }
+  }
+
+  async _sendBatch(batch) {
+    const otlpBatch = batch.map(span => this._toOTLP(span));
+
+    switch (this.target) {
+      case 'file':
+        await this._exportToFile(otlpBatch);
+        break;
+      case 'http':
+        await this._exportToHTTP(otlpBatch);
+        break;
+      case 'stdout':
+      default:
+        await this._exportToStdout(otlpBatch);
+        break;
+    }
+  }
+
+  async _exportToFile(batch) {
+    const filePath = this._filePath || path.join(process.cwd(), 'observability.jsonl');
+    const lines = batch.map(s => JSON.stringify(s)).join('\n') + '\n';
+    fs.appendFileSync(filePath, lines);
+  }
+
+  async _exportToHTTP(batch) {
+    let lastError;
+
+    for (let attempt = 0; attempt < RETRY_BACKOFF_MS.length; attempt++) {
+      try {
+        const response = await fetch(this.url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({ resourceSpans: batch }),
+          signal: AbortSignal.timeout(10000),
+        });
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+
+        return;
+      } catch (error) {
+        lastError = error;
+        if (attempt < RETRY_BACKOFF_MS.length - 1) {
+          await new Promise(resolve => setTimeout(resolve, RETRY_BACKOFF_MS[attempt]));
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  async _exportToStdout(batch) {
+    for (const span of batch) {
+      console.log(JSON.stringify(span));
+    }
+  }
+
+  _toOTLP(span) {
+    return {
+      traceId: span.traceId,
+      spanId: span.spanId,
+      parentSpanId: span.parentSpanId,
+      name: span.name,
+      kind: span.kind,
+      startTimeUnixNano: (span.startTime * 1000000).toString(),
+      endTimeUnixNano: span.endTime ? (span.endTime * 1000000).toString() : null,
+      durationNano: span.duration ? (span.duration * 1000000).toString() : null,
+      status: { code: span.status === 'ok' ? 1 : 2, message: span.attributes.get('status.message') || '' },
+      attributes: Object.entries(span.attributes).map(([key, value]) => ({
+        key,
+        value: this._toOTLPValue(value),
+      })),
+      events: span.events.map(e => ({
+        timeUnixNano: (e.timestamp * 1000000).toString(),
+        name: e.name,
+        attributes: Object.entries(e.attributes).map(([key, value]) => ({
+          key,
+          value: this._toOTLPValue(value),
+        })),
+      })),
+    };
+  }
+
+  _toOTLPValue(value) {
+    if (value === null || value === undefined) {
+      return { stringValue: 'null' };
+    }
+    switch (typeof value) {
+      case 'string': return { stringValue: value };
+      case 'number': return Number.isInteger(value) ? { intValue: value.toString() } : { doubleValue: value };
+      case 'boolean': return { boolValue: value };
+      default: return { stringValue: JSON.stringify(value) };
+    }
+  }
+
+  _startBatchLoop() {
+    this._timer = setInterval(() => {
+      this._flush().catch(() => {});
+    }, this.batchIntervalMs);
+
+    this._timer.unref();
+  }
+
+  getStats() {
+    return {
+      target: this.target,
+      queueSize: this._queue.length,
+      exportCount: this._exportCount,
+      errorCount: this._errorCount,
+      lastError: this._lastError,
+      running: this._running,
+    };
+  }
+
+  async close() {
+    if (this._timer) {
+      clearInterval(this._timer);
+      this._timer = null;
+    }
+
+    await this._flush();
+  }
+}
+
+let _sink = null;
+
+export async function createExportSink(options = {}) {
+  if (!_sink) {
+    _sink = new ExportSink(options);
+    await _sink.init();
+  }
+  return _sink;
+}
+
+export function getExportSink() {
+  return _sink;
+}
+
+export default ExportSink;

package/src/lib/field-iterator.js

@@ -48,3 +48,129 @@ 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 = [];
+  for (const [key, field] of Object.entries(spec.fields || {})) {
+    if (preds.every(pred => pred(field, key))) {
+      results.push(options.keysOnly ? key : { key, ...field });
+    }
+  }
+  return results;
+}
+
+/**
+ * Reusable field predicates for fieldQuery.
+ */
+export const is = {
+  notId: f => f.type !== 'id',
+  notHidden: f => !f.hidden,
+  notReadOnly: f => !f.readOnly,
+  required: f => f.required,
+  searchable: f => f.search,
+  listable: f => f.list === true,
+  ref: f => f.type === 'ref' && f.ref,
+  editable: f => !f.hidden && !f.readOnly && f.type !== 'id' && !f.auto && f.type !== 'auto_timestamp' && !f.auto_generate,
+  displayable: f => !f.hidden && f.type !== 'id',
+  ofType: type => f => f.type === type,
+  hasProperty: prop => f => f[prop] !== undefined,
+};
+
+/**
+ * Editable fields as full { key, ...field } objects (form rendering).
+ * Distinct from thatcher's 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);
+  }
+}