thatcher 1.0.82 → 1.0.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thatcher",
-  "version": "1.0.82",
+  "version": "1.0.84",
   "description": "A config-driven application framework for building data-intensive web apps without code.",
   "main": "src/index.js",
   "type": "module",

package/src/lib/busybase/store.js

@@ -198,7 +198,9 @@ export async function list(entity, where = {}, options = {}) {
   }
   const { decryptFields } = await import('../field-encryption.js');
   const decryptedRows = rows.map(r => decryptFields(r, spec.fields));
-  return attachRefDisplays(entity, decryptedRows);
+  const { computeFormulaFields } = await import('../formula-fields.js');
+  const withFormulas = await Promise.all(decryptedRows.map(r => computeFormulaFields(r, spec.fields, entity)));
+  return attachRefDisplays(entity, withFormulas);
 }
 
 export async function count(entity, where = {}, options = {}) {
@@ -231,7 +233,9 @@ export async function get(entity, id, options = {}) {
   }
   const { decryptFields } = await import('../field-encryption.js');
   const decrypted = decryptFields(row, spec.fields);
-  const [withDisplay] = await attachRefDisplays(entity, [decrypted]);
+  const { computeFormulaFields } = await import('../formula-fields.js');
+  const withFormula = await computeFormulaFields(decrypted, spec.fields, entity);
+  const [withDisplay] = await attachRefDisplays(entity, [withFormula]);
   return withDisplay;
 }
 

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

@@ -147,6 +147,7 @@ const OPPORTUNITY_ENTITY_DEFAULT = {
     expected_close_date: { type: 'date', label: 'Expected Close Date' },
     owner_id: { type: 'ref', ref: 'user', label: 'Owner' },
     probability: { type: 'number', min: 0, max: 100, label: 'Probability (%)' },
+    weighted_value: { type: 'formula', formula: 'value * probability / 100', label: 'Weighted Value', readonly: true },
   },
 };
 
@@ -171,6 +172,7 @@ const PROJECT_ENTITY_DEFAULT = {
     status: { type: 'enum', options: ['planning', 'active', 'on_hold', 'completed', 'cancelled'], default: 'planning', label: 'Status' },
     start_date: { type: 'date', label: 'Start Date' },
     due_date: { type: 'date', label: 'Due Date' },
+    task_count: { type: 'formula', aggregate: { related_entity: 'task', ref_field: 'project_id', aggregate_field: 'id', fn: 'count' }, label: 'Task Count', readonly: true },
   },
 };
 
@@ -300,7 +302,7 @@ function withCustomEntityDefaults(masterConfig) {
 const KNOWN_FIELD_TYPES = new Set([
   'text', 'textarea', 'email', 'number', 'int', 'decimal', 'currency', 'date',
   'timestamp', 'enum', 'bool', 'boolean', 'multiselect', 'ref', 'multiref',
-  'file', 'attachment', 'json',
+  'file', 'attachment', 'json', 'formula',
 ]);
 
 // A custom field key colliding with a reserved system field would let a

package/src/lib/formula-evaluator.js

@@ -0,0 +1,122 @@
+// Minimal safe arithmetic expression evaluator for formula fields: tokenize
+// -> recursive-descent parse -> evaluate, over a fixed grammar of + - * / ( )
+// and bare field-name references only. Deliberately NOT eval/new Function/vm
+// -- there is no code-injection surface because the parser only ever builds
+// number/operator/identifier nodes and the evaluator only ever does
+// arithmetic, never property access or function calls, regardless of what
+// text the formula string contains.
+const TOKEN_RE = /\s*(?:([0-9]+(?:\.[0-9]+)?)|([A-Za-z_][A-Za-z0-9_]*)|([+\-*/()]))/g;
+
+function tokenize(formula) {
+  const tokens = [];
+  let idx = 0;
+  while (idx < formula.length) {
+    TOKEN_RE.lastIndex = idx;
+    const m = TOKEN_RE.exec(formula);
+    if (!m || m.index !== idx) {
+      throw new Error(`Invalid character in formula at position ${idx}: "${formula[idx]}"`);
+    }
+    idx = TOKEN_RE.lastIndex;
+    if (m[1] !== undefined) tokens.push({ type: 'number', value: Number(m[1]) });
+    else if (m[2] !== undefined) tokens.push({ type: 'ident', value: m[2] });
+    else if (m[3] !== undefined) tokens.push({ type: 'op', value: m[3] });
+  }
+  return tokens;
+}
+
+// Recursive-descent parser for: expr := term (('+' | '-') term)*
+//                                term := factor (('*' | '/') factor)*
+//                                factor := number | ident | '(' expr ')'
+function parse(tokens) {
+  let pos = 0;
+  function peek() { return tokens[pos]; }
+  function next() { return tokens[pos++]; }
+
+  function parseFactor() {
+    const t = peek();
+    if (!t) throw new Error('Unexpected end of formula');
+    if (t.type === 'number') { next(); return { type: 'number', value: t.value }; }
+    if (t.type === 'ident') { next(); return { type: 'ident', value: t.value }; }
+    if (t.type === 'op' && t.value === '(') {
+      next();
+      const node = parseExpr();
+      const close = next();
+      if (!close || close.type !== 'op' || close.value !== ')') throw new Error('Expected closing parenthesis');
+      return node;
+    }
+    throw new Error(`Unexpected token: ${t.type === 'op' ? t.value : t.value}`);
+  }
+
+  function parseTerm() {
+    let node = parseFactor();
+    while (peek() && peek().type === 'op' && (peek().value === '*' || peek().value === '/')) {
+      const opTok = next();
+      node = { type: 'binop', op: opTok.value, left: node, right: parseFactor() };
+    }
+    return node;
+  }
+
+  function parseExpr() {
+    let node = parseTerm();
+    while (peek() && peek().type === 'op' && (peek().value === '+' || peek().value === '-')) {
+      const opTok = next();
+      node = { type: 'binop', op: opTok.value, left: node, right: parseTerm() };
+    }
+    return node;
+  }
+
+  const result = parseExpr();
+  if (pos !== tokens.length) throw new Error(`Unexpected trailing tokens starting at "${tokens[pos].value}"`);
+  return result;
+}
+
+// Every identifier the formula references must exist in allowedFieldNames
+// (this entity's own spec.fields keys) -- checked up front so a formula
+// naming an unknown/foreign field is rejected before evaluation is ever
+// attempted, never silently treated as 0 or undefined.
+function validateIdentifiers(node, allowedFieldNames) {
+  if (node.type === 'ident') {
+    if (!allowedFieldNames.has(node.value)) {
+      throw new Error(`Formula references unknown field "${node.value}"`);
+    }
+    return;
+  }
+  if (node.type === 'binop') {
+    validateIdentifiers(node.left, allowedFieldNames);
+    validateIdentifiers(node.right, allowedFieldNames);
+  }
+}
+
+function evaluateNode(node, record) {
+  if (node.type === 'number') return node.value;
+  if (node.type === 'ident') {
+    const v = Number(record[node.value]);
+    return Number.isFinite(v) ? v : 0;
+  }
+  if (node.type === 'binop') {
+    const l = evaluateNode(node.left, record);
+    const r = evaluateNode(node.right, record);
+    if (node.op === '+') return l + r;
+    if (node.op === '-') return l - r;
+    if (node.op === '*') return l * r;
+    if (node.op === '/') return r === 0 ? 0 : l / r;
+  }
+  throw new Error('Unreachable formula node');
+}
+
+// Parses AND validates a formula against a fixed set of allowed field names
+// (this entity's own spec.fields keys), throwing on anything outside the
+// arithmetic/identifier grammar or referencing an unknown field. Call once
+// at spec-generation or first-use time to fail fast on a malformed formula
+// definition, separately from per-record evaluation.
+export function compileFormula(formula, allowedFieldNames) {
+  const tokens = tokenize(formula);
+  const ast = parse(tokens);
+  validateIdentifiers(ast, allowedFieldNames);
+  return ast;
+}
+
+export function evaluateFormula(formula, record, allowedFieldNames) {
+  const ast = compileFormula(formula, allowedFieldNames);
+  return evaluateNode(ast, record);
+}

package/src/lib/formula-fields.js

@@ -0,0 +1,98 @@
+import { evaluateFormula } from './formula-evaluator.js';
+
+const AGGREGATE_FUNCTIONS = new Set(['count', 'sum', 'avg']);
+
+// An aggregate formula's list() call re-enters computeFormulaFields for every
+// related row, which could itself have an aggregate formula pointing back at
+// the original entity -- a config mistake (A aggregates B, B aggregates A)
+// would otherwise recurse without bound. A simple depth counter (not
+// per-request-scoped -- formula evaluation has no request context threaded
+// through it, same as every other computeFormulaFields caller) caps this at
+// a depth no legitimate one-hop-or-two-hop aggregate design would ever need.
+const MAX_AGGREGATE_DEPTH = 3;
+let currentAggregateDepth = 0;
+
+// Cross-entity aggregate formula (task_count-style): join through a field on
+// the RELATED entity that points back to THIS record's id -- the reverse
+// direction of a normal ref field, since the "one" side of a one-to-many
+// relationship never names the "many" side directly. Reuses the exact same
+// list(relatedEntity, {[ref_field]: id}) query shape resource_allocation's
+// capacity check and the rollup report's ref-join already use, not new join
+// logic. Runs WITHOUT a user context in scope -- the same unscoped-internal
+// read pattern checkStockBalance/checkResourceCapacity/the same-record
+// formula path all already establish for computeFormulaFields' call sites in
+// busybase/store.js -- an aggregate is more visibly "reading across
+// entities" than the same-record arithmetic case, so this is stated
+// explicitly rather than left implicit: it is consistent with, not an
+// expansion of, the existing unscoped-lookup contract.
+async function evaluateAggregateFormula(aggregate, record, entityName) {
+  const { related_entity, ref_field, aggregate_field, fn } = aggregate || {};
+  if (typeof related_entity !== 'string' || typeof ref_field !== 'string' || typeof aggregate_field !== 'string') {
+    throw new Error('aggregate formula requires related_entity, ref_field, and aggregate_field');
+  }
+  if (!AGGREGATE_FUNCTIONS.has(fn)) {
+    throw new Error(`aggregate formula fn must be one of ${[...AGGREGATE_FUNCTIONS].join(', ')}`);
+  }
+
+  const { getSpec } = await import('@/config/spec-helpers');
+  const relatedSpec = getSpec(related_entity);
+  if (!relatedSpec) throw new Error(`aggregate formula references unknown entity "${related_entity}"`);
+  if (!relatedSpec.fields?.[ref_field]) {
+    throw new Error(`aggregate formula's ref_field "${ref_field}" does not exist on entity "${related_entity}"`);
+  }
+  if (aggregate_field !== 'id' && !relatedSpec.fields?.[aggregate_field]) {
+    throw new Error(`aggregate formula's aggregate_field "${aggregate_field}" does not exist on entity "${related_entity}"`);
+  }
+
+  if (currentAggregateDepth >= MAX_AGGREGATE_DEPTH) {
+    throw new Error(`aggregate formula exceeded max nesting depth (${MAX_AGGREGATE_DEPTH}) -- check for a cross-entity aggregate cycle`);
+  }
+
+  currentAggregateDepth++;
+  let relatedRows;
+  try {
+    const { list } = await import('./busybase/store');
+    relatedRows = await list(related_entity, { [ref_field]: record.id });
+  } finally {
+    currentAggregateDepth--;
+  }
+
+  if (fn === 'count') return relatedRows.length;
+  if (!relatedRows.length) return 0;
+  const values = relatedRows.map(r => Number(r[aggregate_field]) || 0);
+  const total = values.reduce((sum, v) => sum + v, 0);
+  if (fn === 'sum') return total;
+  return total / values.length; // avg
+}
+
+// Formula fields are never stored -- computed at read time so the result
+// can never drift from its inputs the way a separately-writable computed
+// column could. Runs right after decryption in busybase/store.js's
+// get()/list(), the same choke point field-encryption already uses, so it
+// is transparent to every existing caller of either function. Two shapes:
+// fieldDef.formula (same-record arithmetic expression) and fieldDef.aggregate
+// (cross-entity count/sum/avg) -- mutually exclusive per field, checked here.
+export async function computeFormulaFields(record, specFields, entityName) {
+  if (!record || !specFields) return record;
+  let result = record;
+  for (const [key, fieldDef] of Object.entries(specFields)) {
+    if (fieldDef.type !== 'formula') continue;
+    if (!fieldDef.formula && !fieldDef.aggregate) continue;
+    if (result === record) result = { ...record };
+    try {
+      if (fieldDef.aggregate) {
+        result[key] = await evaluateAggregateFormula(fieldDef.aggregate, record, entityName);
+      } else {
+        const allowedFieldNames = new Set(Object.keys(specFields));
+        result[key] = evaluateFormula(fieldDef.formula, record, allowedFieldNames);
+      }
+    } catch {
+      // A malformed/unreferenceable formula must not crash the read path for
+      // every other field on the record -- degrade to null for this field
+      // only, the same fail-soft pattern current_stock/total_hours already
+      // use on their own computation failures in page-handler.js.
+      result[key] = null;
+    }
+  }
+  return result;
+}

package/src/lib/validation/entity-validators.js

@@ -18,6 +18,18 @@ export function sanitizeHtml(str) {
 export async function validateField(fieldDef, value, options = {}) {
   const { fieldName, entityName, existingValue } = options;
 
+  // A formula field is never stored -- computed fresh from the record's own
+  // other fields at every read (busybase/store.js's computeFormulaFields).
+  // Unlike a generic readOnly field (which silently ignores a client-
+  // supplied value), a write attempt against a formula field is rejected
+  // outright: the caller almost certainly intended to set an input field,
+  // not the derived output, and silently swallowing that mistake would hide
+  // a real bug rather than surface it.
+  if (fieldDef.type === 'formula') {
+    if (value === null || value === undefined || value === '') return { valid: true };
+    return { valid: false, error: `Field '${fieldName}' is computed and cannot be set directly` };
+  }
+
   if (fieldDef.auto || fieldDef.auto_generate || fieldDef.readOnly) {
     return { valid: true };
   }

package/src/ui/entity-renderer.js

@@ -73,6 +73,7 @@ function formatFieldValue(k, v, entityName, f) {
   if (entityName === 'user' && k === 'email' && v) { const e = esc(v); return `<a href="mailto:${e}" class="text-primary hover:underline">${e}</a>` }
   if (k === 'photo_url' && v && v.startsWith('http')) return `<img src="${esc(v)}" style="width:2.5rem;height:2.5rem;border-radius:50%;object-fit:cover" alt="avatar" onerror="this.style.display='none'"/>`
   if (f?.type === 'currency' && typeof v === 'number') return esc((f.currency_symbol || '$') + (v / 100).toFixed(2))
+  if (f?.type === 'formula') return v == null ? '-' : esc(String(Math.round(v * 100) / 100)) + ' <span class="pill pill-neutral" style="margin-left:4px;font-size:10px">computed</span>'
   if (f?.type === 'multiselect') {
     const arr = Array.isArray(v) ? v : (typeof v === 'string' && v ? (() => { try { return JSON.parse(v) } catch { return [] } })() : [])
     return arr.length ? arr.map(x => `<span class="pill pill-neutral" style="margin-right:4px">${esc(x)}</span>`).join('') : '-'
@@ -274,7 +275,12 @@ export function renderEntityForm(entityName, item, spec, user, isNew = false, re
     if (permissionService.checkFieldAccess(user, spec || {}, k, 'edit')) fields[k] = f
   }
   const lbl = (k, f, req) => `<label class="form-label" for="field-${k}">${esc(f.label||k)}${req ? '<span class="req">*</span>' : ''}</label>`
-  const formFields = Object.entries(fields).filter(([k, f]) => k !== 'id' && !f.auto && !f.readOnly && !f.auto_generate && k !== 'password_hash').map(([k, f]) => {
+  // f.readonly (lowercase) is the actual normalized key generateEntitySpec
+  // sets -- f.readOnly (camelCase) is never present on a spec object, so
+  // this exclusion was previously silently dead: a field marked readonly
+  // without ALSO being marked auto (e.g. a formula field) would render as
+  // an editable input despite the label claiming otherwise.
+  const formFields = Object.entries(fields).filter(([k, f]) => k !== 'id' && !f.auto && !f.readonly && !f.auto_generate && f.type !== 'formula' && k !== 'password_hash').map(([k, f]) => {
     let val = item?.[k] ?? f.default ?? ''
     const req = f.required ? 'required' : ''
     const type = f.type === 'number' || f.type === 'int' || f.type === 'decimal' ? 'number' : f.type === 'email' ? 'email' : f.type === 'timestamp' || f.type === 'date' ? 'date' : f.type === 'bool' ? 'checkbox' : 'text'