thatcher 1.0.4 → 1.0.6

package/src/lib/status-helpers.js

@@ -3,6 +3,8 @@
  * These are the standard status values used by moonlanding parity entities
  */
 
+import { getConfigEngineSync } from './config-generator-engine.js';
+
 // Engagement statuses
 export const ENGAGEMENT_STATUS = {
   DRAFT: 'draft',
@@ -96,3 +98,129 @@ export function getValidTransitions(currentStage) {
   }
   return [...new Set(transitions)];
 }
+
+// ---------------------------------------------------------------------------
+// Config-driven enrichment (ported from moonlanding status-helpers).
+// These are ADDITIVE: each falls back to thatcher's static enums / transition
+// maps above when no config engine is initialized, so thatcher's architecture
+// and enum model remain authoritative.
+// ---------------------------------------------------------------------------
+
+let _cachedConfig = null;
+
+function getCachedConfig() {
+  if (!_cachedConfig) {
+    try {
+      const engine = getConfigEngineSync();
+      _cachedConfig = engine.getConfig();
+    } catch {
+      return null;
+    }
+  }
+  return _cachedConfig;
+}
+
+function buildEnumFromWorkflow(workflowName) {
+  const stages = getCachedConfig()?.workflows?.[workflowName]?.stages;
+  if (!stages) return null;
+  const result = {};
+  for (const stage of stages) {
+    const name = typeof stage === 'string' ? stage : stage.name;
+    result[name.toUpperCase()] = name;
+  }
+  return result;
+}
+
+/**
+ * Human-readable labels for status/stage values.
+ * Built from thatcher's own enums so labels track thatcher's enum model.
+ */
+function titleCase(v) {
+  return String(v).replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+export const STATUS_LABELS = {
+  ...Object.fromEntries(Object.values(ENGAGEMENT_STATUS).map((v) => [v, titleCase(v)])),
+  ...Object.fromEntries(Object.values(ENGAGEMENT_STAGE).map((v) => [v, titleCase(v)])),
+  ...Object.fromEntries(Object.values(RFI_STATUS).map((v) => [v, titleCase(v)])),
+  ...Object.fromEntries(Object.values(RFI_CLIENT_STATUS).map((v) => [v, titleCase(v)])),
+  ...Object.fromEntries(Object.values(RFI_AUDITOR_STATUS).map((v) => [v, titleCase(v)])),
+  ...Object.fromEntries(Object.values(REVIEW_STATUS).map((v) => [v, titleCase(v)])),
+  ...Object.fromEntries(Object.values(HIGHLIGHT_STATUS).map((v) => [v, titleCase(v)])),
+};
+
+/**
+ * Get the display label for a status/stage value.
+ * @param {string} value
+ * @returns {string}
+ */
+export function getStatusLabel(value) {
+  return STATUS_LABELS[value] || value;
+}
+
+/**
+ * Resolve engagement stages from config workflow, falling back to ENGAGEMENT_STAGE.
+ * @returns {Object}
+ */
+export function getEngagementStages() {
+  return buildEnumFromWorkflow('engagement_lifecycle') || ENGAGEMENT_STAGE;
+}
+
+/**
+ * Resolve RFI states from config workflow, falling back to RFI_STATUS.
+ * @returns {Object}
+ */
+export function getRfiStates() {
+  return buildEnumFromWorkflow('rfi_type_standard') || RFI_STATUS;
+}
+
+/**
+ * Resolve review stages from config workflow, falling back to REVIEW_STATUS.
+ * @returns {Object}
+ */
+export function getReviewStages() {
+  return buildEnumFromWorkflow('review_lifecycle') || REVIEW_STATUS;
+}
+
+/**
+ * Resolve the engagement stage transition map from config, falling back to
+ * thatcher's static STAGE_TRANSITIONS.
+ * @returns {Object<string,string>}
+ */
+export function getStageTransitions() {
+  const stages = getCachedConfig()?.workflows?.engagement_lifecycle?.stages;
+  if (!stages) return STAGE_TRANSITIONS;
+  const result = {};
+  for (let i = 0; i < stages.length - 1; i++) {
+    const cur = typeof stages[i] === 'string' ? stages[i] : stages[i].name;
+    const nxt = typeof stages[i + 1] === 'string' ? stages[i + 1] : stages[i + 1].name;
+    result[cur] = nxt;
+  }
+  return result;
+}
+
+/**
+ * Check whether a transition between two states is valid for an entity type.
+ * @param {string} entityType
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+export function isValidTransition(entityType, from, to) {
+  if (entityType === 'engagement') {
+    const transitions = getStageTransitions();
+    return transitions[from] === to;
+  }
+  if (entityType === 'review') {
+    const allowed = getValidTransitions(from) || [];
+    return allowed.includes(to);
+  }
+  return false;
+}
+
+/**
+ * Clear the cached config snapshot (call after a config hot-reload).
+ */
+export function clearCachedConfig() {
+  _cachedConfig = null;
+}

package/src/lib/tracing.js

@@ -0,0 +1,287 @@
+/**
+ * Observability Tracing Core - OpenTelemetry-style distributed tracing for Thatcher
+ * Provides trace/span lifecycle, async context propagation, and trace export
+ */
+
+import { AsyncLocalStorage } from 'async_hooks';
+import { createLogger } from './logger.js';
+
+const logger = createLogger('[Tracing]');
+
+const _asyncLocalStorage = new AsyncLocalStorage();
+const _traceBuffer = [];
+const _activeSpans = new Map();
+const MAX_BUFFER_SIZE = 5000;
+const SLOW_THRESHOLD_MS = 100;
+
+let _traceIdCounter = 0;
+let _spanIdCounter = 0;
+
+function generateTraceId() {
+  _traceIdCounter++;
+  return `trace-${Date.now()}-${_traceIdCounter.toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function generateSpanId() {
+  _spanIdCounter++;
+  return `span-${_spanIdCounter.toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+
+export class Span {
+  constructor(options) {
+    this.traceId = options.traceId;
+    this.spanId = options.spanId;
+    this.parentSpanId = options.parentSpanId || null;
+    this.name = options.name;
+    this.kind = options.kind || 'internal';
+    this.startTime = options.startTime || Date.now();
+    this.endTime = null;
+    this.duration = null;
+    this.status = options.status || 'ok';
+    this.statusCode = options.statusCode || null;
+    this.attributes = new Map(Object.entries(options.attributes || {}));
+    this.events = [];
+    this._isRecording = true;
+  }
+
+  setAttribute(key, value) {
+    if (!this._isRecording) return this;
+    this.attributes.set(key, value);
+    return this;
+  }
+
+  setAttributes(attrs) {
+    if (!this._isRecording) return this;
+    for (const [key, value] of Object.entries(attrs)) {
+      this.attributes.set(key, value);
+    }
+    return this;
+  }
+
+  addEvent(name, attributes = {}) {
+    if (!this._isRecording) return this;
+    this.events.push({
+      name,
+      timestamp: Date.now(),
+      attributes,
+    });
+    return this;
+  }
+
+  setStatus(status, message) {
+    if (!this._isRecording) return this;
+    this.status = status;
+    if (message) {
+      this.attributes.set('status.message', message);
+    }
+    return this;
+  }
+
+  end() {
+    if (!this._isRecording) return;
+    this.endTime = Date.now();
+    this.duration = this.endTime - this.startTime;
+
+    if (this.duration > SLOW_THRESHOLD_MS) {
+      this.setAttribute('slow', true);
+      this.setAttribute('threshold.exceeded', SLOW_THRESHOLD_MS);
+    }
+
+    this._isRecording = false;
+    _activeSpans.delete(this.spanId);
+  }
+
+  recordException(error) {
+    if (!this._isRecording) return this;
+    this.setStatus('error', error.message);
+    this.addEvent('exception', {
+      'exception.type': error.constructor?.name || 'Error',
+      'exception.message': error.message,
+      'exception.stacktrace': error.stack,
+    });
+    return this;
+  }
+
+  toJSON() {
+    return {
+      traceId: this.traceId,
+      spanId: this.spanId,
+      parentSpanId: this.parentSpanId,
+      name: this.name,
+      kind: this.kind,
+      startTime: this.startTime,
+      endTime: this.endTime,
+      duration: this.duration,
+      status: this.status,
+      statusCode: this.statusCode,
+      attributes: Object.fromEntries(this.attributes),
+      events: this.events,
+    };
+  }
+}
+
+export class Tracer {
+  constructor(name = 'thatcher') {
+    this.name = name;
+  }
+
+  startSpan(name, options = {}) {
+    const parentContext = _asyncLocalStorage.getStore();
+    const parentSpan = parentContext?.span || null;
+
+    const traceId = options.traceId || parentContext?.traceId || generateTraceId();
+    const spanId = generateSpanId();
+
+    const span = new Span({
+      traceId,
+      spanId,
+      parentSpanId: parentSpan?.spanId,
+      name,
+      kind: options.kind,
+      attributes: options.attributes,
+    });
+
+    _activeSpans.set(spanId, span);
+
+    const context = { traceId, span };
+    return { span, context };
+  }
+
+  async withSpan(name, fn, options = {}) {
+    const { span, context } = this.startSpan(name, options);
+
+    try {
+      const result = await _asyncLocalStorage.run(context, () => fn(span));
+      span.setStatus('ok');
+      return result;
+    } catch (error) {
+      span.recordException(error);
+      throw error;
+    } finally {
+      span.end();
+      this._exportSpan(span);
+    }
+  }
+
+  getCurrentContext() {
+    return _asyncLocalStorage.getStore();
+  }
+
+  getCurrentTraceId() {
+    return _asyncLocalStorage.getStore()?.traceId || null;
+  }
+
+  getCurrentSpan() {
+    return _asyncLocalStorage.getStore()?.span || null;
+  }
+
+  getTraceparentHeader() {
+    const ctx = this.getCurrentContext();
+    if (!ctx?.span) return null;
+    return `00-${ctx.traceId}-${ctx.span.spanId.replace('span-', '').replace(/-/g, '').padStart(16, '0')}-01`;
+  }
+
+  extractTraceparent(header) {
+    if (!header) return null;
+    const parts = header.split('-');
+    if (parts.length !== 4) return null;
+    return {
+      version: parts[0],
+      traceId: parts[1],
+      parentSpanId: parts[2],
+      flags: parts[3],
+    };
+  }
+
+  getActiveSpans() {
+    return Array.from(_activeSpans.values()).map(s => s.toJSON());
+  }
+
+  getRecentTraces(limit = 100) {
+    return _traceBuffer.slice(-limit);
+  }
+
+  getTraceById(traceId) {
+    const spans = _traceBuffer.filter(s => s.traceId === traceId);
+    if (spans.length === 0) return null;
+
+    const spanMap = new Map();
+    for (const span of spans) {
+      spanMap.set(span.spanId, { ...span, children: [] });
+    }
+
+    let root = null;
+    for (const span of spanMap.values()) {
+      if (span.parentSpanId && spanMap.has(span.parentSpanId)) {
+        spanMap.get(span.parentSpanId).children.push(span);
+      } else {
+        root = span;
+      }
+    }
+
+    return root;
+  }
+
+  getStats() {
+    return {
+      activeSpans: _activeSpans.size,
+      bufferedTraces: _traceBuffer.length,
+      maxBufferSize: MAX_BUFFER_SIZE,
+    };
+  }
+
+  _exportSpan(span) {
+    const json = span.toJSON();
+    _traceBuffer.push(json);
+
+    while (_traceBuffer.length > MAX_BUFFER_SIZE) {
+      _traceBuffer.shift();
+    }
+
+    if (globalThis.__trace_export__) {
+      globalThis.__trace_export__.export(json).catch(() => {});
+    }
+  }
+
+  clear() {
+    _traceBuffer.length = 0;
+    _activeSpans.clear();
+  }
+}
+
+export const tracer = new Tracer('thatcher');
+
+export function createTracer(name) {
+  return new Tracer(name);
+}
+
+export function getTracer() {
+  return tracer;
+}
+
+export async function traceOperation(name, fn, attributes = {}) {
+  return tracer.withSpan(name, async (span) => {
+    span.setAttributes(attributes);
+    return fn(span);
+  }, { attributes });
+}
+
+export function getCurrentTraceId() {
+  return tracer.getCurrentTraceId();
+}
+
+export function getTraceparentHeader() {
+  return tracer.getTraceparentHeader();
+}
+
+export default Tracer;
+
+if (globalThis.__debug__) {
+  globalThis.__debug__.expose('tracing', {
+    activeSpans: () => tracer.getActiveSpans(),
+    recentTraces: (limit) => tracer.getRecentTraces(limit),
+    traceById: (id) => tracer.getTraceById(id),
+    stats: () => tracer.getStats(),
+    currentTraceId: () => tracer.getCurrentTraceId(),
+  }, 'Tracing Core');
+}

package/src/lib/utils.js

@@ -2,6 +2,72 @@
  * Utility Functions - Common helpers
  */
 
+import { list } from './query-engine.js';
+import { getSpec } from '../config/spec-helpers.js';
+
+/**
+ * Load ref-field options for a spec's form (ported from moonlanding).
+ * For each `ref` field, fetch the referenced entity's rows and build
+ * `{ value, label }` option lists. `engagement` refs get a richer label
+ * and skip archived rows. Failures degrade to an empty option list.
+ * @param {object} spec - Entity spec with a `fields` map
+ * @returns {Promise<Record<string, Array<{value:any,label:string}>>>}
+ */
+export async function loadFormOptions(spec) {
+  const options = {};
+  for (const [key, field] of Object.entries(spec.fields || {})) {
+    if (field.type === 'ref' && field.ref) {
+      try {
+        const data = list(field.ref);
+        if (field.ref === 'engagement') {
+          options[key] = data
+            .filter(r => r.status !== 'archived')
+            .map(r => ({
+              value: r.id,
+              label: `${r.client_name || 'No Client'} - ${r.name} (${r.financial_year || r.year || 'N/A'})`,
+            }));
+        } else {
+          options[key] = data.map(r => ({
+            value: r.id,
+            label: r.name || r.email || r.id,
+          }));
+        }
+      } catch {
+        options[key] = [];
+      }
+    }
+  }
+  return options;
+}
+
+/**
+ * Error thrown when an entity spec cannot be resolved (ported from moonlanding).
+ */
+export class SpecError extends Error {
+  constructor(entity) {
+    super(`Unknown entity: ${entity}`);
+    this.code = 'UNKNOWN_ENTITY';
+    this.name = 'SpecError';
+  }
+}
+
+/**
+ * Resolve an entity spec, throwing a typed SpecError on failure (ported from
+ * moonlanding). Uses thatcher's single-arg getSpec convention.
+ * @param {string} entity
+ * @returns {Promise<object>}
+ */
+export async function resolveSpec(entity) {
+  try {
+    const spec = getSpec(entity);
+    if (!spec) throw new SpecError(entity);
+    return spec;
+  } catch (e) {
+    if (e instanceof SpecError) throw e;
+    throw new SpecError(entity);
+  }
+}
+
 /**
  * Get display name for user
  * @param {object} user - User with name or email
@@ -91,3 +157,18 @@ export function randomColor() {
   ];
   return colors[Math.floor(Math.random() * colors.length)];
 }
+
+/**
+ * Determine whether a user record is active (ported from moonlanding).
+ * Treats explicit inactive/disabled/suspended status, falsy `is_active`,
+ * or a set `deleted_at` as inactive.
+ * @param {object} user
+ * @returns {boolean}
+ */
+export function isUserActive(user) {
+  if (!user) return false;
+  if (user.is_active === false || user.is_active === 0) return false;
+  if (user.status === 'inactive' || user.status === 'disabled' || user.status === 'suspended') return false;
+  if (user.deleted_at) return false;
+  return true;
+}

package/src/lib/validate.js

@@ -4,7 +4,12 @@
  */
 
 import { getSpec } from '../config/spec-helpers.js';
-import { isValidEmail as checkEmailFormat } from './validators.js';
+import { isValidEmail as checkEmailFormat, isValidEmail } from './validators.js';
+import { getValidTransitions } from './status-helpers.js';
+import { isBeforeDate } from './date-utils.js';
+
+// Re-export so consumers can reach the email validator from validate.js (parity with moon)
+export { isValidEmail };
 
 const HTML_ESC = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
 
@@ -153,11 +158,44 @@ export async function validateEntity(entityName, data, existingRecord = null) {
     if (!result.valid && result.error) {
       errors[fieldName] = result.error;
     }
+
+    const uniqueErr = await checkUnique(fieldDef, value, {
+      fieldName,
+      entityName,
+      existingRecord,
+    });
+    if (uniqueErr && !errors[fieldName]) errors[fieldName] = uniqueErr;
   }
 
   return errors;
 }
 
+/**
+ * Enforce a field's `unique` constraint against the datastore.
+ * Returns an error string if a duplicate exists, otherwise null.
+ * @param {object} fieldDef
+ * @param {any} value
+ * @param {object} options - { fieldName, entityName, existingRecord }
+ * @returns {Promise<string|null>}
+ */
+async function checkUnique(fieldDef, value, { fieldName, entityName, existingRecord }) {
+  if (!fieldDef.unique) return null;
+  if (value == null || value === '') return null;
+  const existingValue = existingRecord?.[fieldName];
+  if (value === existingValue) return null;
+  try {
+    const { get } = await import('./query-engine.js');
+    const table = entityName === 'user' ? 'users' : entityName;
+    const dup = get(table, undefined, { [fieldName]: value });
+    if (dup && (!existingRecord || dup.id !== existingRecord.id)) {
+      return `Field '${fieldName}' must be unique`;
+    }
+  } catch {
+    // Table might not exist yet; skip uniqueness enforcement
+  }
+  return null;
+}
+
 /**
  * Validate update (only changed fields)
  * @param {string} entityName
@@ -182,6 +220,13 @@ export async function validateUpdate(entityName, changes, existingRecord) {
     if (!result.valid && result.error) {
       errors[fieldName] = result.error;
     }
+
+    const uniqueErr = await checkUnique(fieldDef, value, {
+      fieldName,
+      entityName,
+      existingRecord,
+    });
+    if (uniqueErr && !errors[fieldName]) errors[fieldName] = uniqueErr;
   }
 
   return errors;
@@ -195,3 +240,81 @@ export async function validateUpdate(entityName, changes, existingRecord) {
 export function hasErrors(errors) {
   return errors && Object.keys(errors).length > 0;
 }
+
+/**
+ * Validate a status/stage transition is permitted.
+ * Uses thatcher's STAGE_TRANSITIONS graph via getValidTransitions.
+ * @param {string} entityType
+ * @param {string} currentStatus
+ * @param {string} newStatus
+ * @returns {{valid: boolean, reason?: string}}
+ */
+export function validateStatusTransition(entityType, currentStatus, newStatus) {
+  if (!currentStatus || !newStatus) {
+    return { valid: false, reason: 'Status values required' };
+  }
+  if (currentStatus === newStatus) return { valid: true };
+  const allowed = getValidTransitions(currentStatus) || [];
+  if (!allowed.includes(newStatus)) {
+    return {
+      valid: false,
+      reason: `Cannot transition ${entityType} from '${currentStatus}' to '${newStatus}'`,
+    };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate that an end date is not before a start date.
+ * @param {number} startSeconds - Unix timestamp (seconds)
+ * @param {number} endSeconds - Unix timestamp (seconds)
+ * @param {string} label
+ * @returns {{valid: boolean, reason?: string}}
+ */
+export function validateDateRange(startSeconds, endSeconds, label = 'date') {
+  if (!startSeconds || !endSeconds) return { valid: true };
+  if (isBeforeDate(endSeconds, startSeconds)) {
+    return { valid: false, reason: `End ${label} cannot be before start ${label}` };
+  }
+  return { valid: true };
+}
+
+/**
+ * Validate a deadline: required, not before a reference date, within maxYears.
+ * @param {number} deadlineSeconds - Unix timestamp (seconds)
+ * @param {number} [referenceSeconds] - Unix timestamp (seconds)
+ * @param {number} [maxYears=2]
+ * @returns {{valid: boolean, reason?: string}}
+ */
+export function validateDeadline(deadlineSeconds, referenceSeconds, maxYears = 2) {
+  if (!deadlineSeconds) return { valid: false, reason: 'Deadline is required' };
+  if (referenceSeconds && isBeforeDate(deadlineSeconds, referenceSeconds)) {
+    return { valid: false, reason: 'Deadline cannot be before the reference date' };
+  }
+  // Upper-bound window check (moon isWithinYears semantics: deadline must be within maxYears ahead).
+  // Inlined rather than reusing thatcher's isWithinYears(ts, minYearsAgo, maxYearsAhead) whose
+  // 2nd positional arg differs in meaning.
+  const limit = new Date();
+  limit.setFullYear(limit.getFullYear() + maxYears);
+  if (new Date(deadlineSeconds * 1000) > limit) {
+    return { valid: false, reason: `Deadline must be within ${maxYears} years` };
+  }
+  return { valid: true };
+}
+
+/**
+ * Sanitize string/text fields of a record using the entity spec.
+ * @param {object} data
+ * @param {object} spec
+ * @returns {object} Sanitized shallow copy
+ */
+export function sanitizeData(data, spec) {
+  const sanitized = { ...data };
+  for (const [fieldName, value] of Object.entries(sanitized)) {
+    const fieldDef = spec?.fields?.[fieldName];
+    if (fieldDef && (fieldDef.type === 'string' || fieldDef.type === 'text') && typeof value === 'string') {
+      sanitized[fieldName] = sanitizeHtml(value);
+    }
+  }
+  return sanitized;
+}