thatcher 1.0.83 → 1.0.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thatcher",
-  "version": "1.0.83",
+  "version": "1.0.85",
   "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

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

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

@@ -172,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 },
   },
 };
 
@@ -208,6 +209,7 @@ const PRODUCT_ENTITY_DEFAULT = {
     description: { type: 'textarea', label: 'Description' },
     unit_price: { type: 'currency', label: 'Unit Price' },
     reorder_threshold: { type: 'number', min: 0, label: 'Reorder Threshold' },
+    lead_time_days: { type: 'number', min: 0, default: 14, label: 'Lead Time (days)' },
   },
 };
 

package/src/lib/formula-fields.js

@@ -1,26 +1,96 @@
 import { evaluateFormula } from './formula-evaluator.js';
 
-// Formula fields are never stored -- computed at read time from the SAME
-// record's own field values 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.
-export function computeFormulaFields(record, specFields) {
+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' || !fieldDef.formula) continue;
-    const allowedFieldNames = new Set(Object.keys(specFields));
+    if (fieldDef.type !== 'formula') continue;
+    if (!fieldDef.formula && !fieldDef.aggregate) continue;
+    if (result === record) result = { ...record };
     try {
-      if (result === record) result = { ...record };
-      result[key] = evaluateFormula(fieldDef.formula, record, allowedFieldNames);
+      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.
-      if (result === record) result = { ...record };
       result[key] = null;
     }
   }

package/src/lib/inventory-forecast.js

@@ -0,0 +1,53 @@
+// Single source of truth for inventory demand-forecast math, shared between
+// page-handler.js's product detail-view computation and any future forecast
+// summary view -- kept in one place so they never drift, the same pattern
+// contract-expiry.js already established for expiry math.
+const DEFAULT_WINDOW_DAYS = 90;
+const DEFAULT_LEAD_TIME_DAYS = 14;
+const DAY_SECONDS = 86400;
+
+// Average daily consumption over a trailing window: sum of every OUTBOUND
+// (negative quantity) movement within the window, divided by the window's
+// day-count -- not the number of movements, so sparse activity (e.g. one
+// large monthly shipment) still averages correctly over the full period
+// rather than only the days something happened.
+export function averageDailyConsumption(movements, windowDays = DEFAULT_WINDOW_DAYS, nowSeconds = Math.floor(Date.now() / 1000)) {
+  const windowStart = nowSeconds - windowDays * DAY_SECONDS;
+  const outboundTotal = movements
+    .filter(m => Number(m.created_at) >= windowStart && Number(m.quantity) < 0)
+    .reduce((sum, m) => sum + Math.abs(Number(m.quantity) || 0), 0);
+  return outboundTotal / windowDays;
+}
+
+// null (not Infinity, not a crash) when there is no consumption to project
+// against -- a caller rendering this must be able to tell "we don't know"
+// apart from "never" without special-casing an infinite number.
+export function daysUntilStockout(currentStock, avgDailyConsumption) {
+  if (!Number.isFinite(avgDailyConsumption) || avgDailyConsumption <= 0) return null;
+  if (currentStock <= 0) return 0;
+  return currentStock / avgDailyConsumption;
+}
+
+export function suggestedReorderDate(daysUntilStockoutValue, leadTimeDays = DEFAULT_LEAD_TIME_DAYS, nowSeconds = Math.floor(Date.now() / 1000)) {
+  if (daysUntilStockoutValue == null) return null;
+  const daysUntilReorder = daysUntilStockoutValue - leadTimeDays;
+  return nowSeconds + daysUntilReorder * DAY_SECONDS;
+}
+
+export function isReorderDue(reorderDateSeconds, nowSeconds = Math.floor(Date.now() / 1000)) {
+  if (reorderDateSeconds == null) return false;
+  return reorderDateSeconds <= nowSeconds;
+}
+
+export function computeInventoryForecast(product, movements, currentStock, options = {}) {
+  const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+  const windowDays = options.windowDays ?? DEFAULT_WINDOW_DAYS;
+  const leadTimeDays = product.lead_time_days ?? DEFAULT_LEAD_TIME_DAYS;
+
+  const avgDailyConsumption = averageDailyConsumption(movements, windowDays, nowSeconds);
+  const daysUntilOut = daysUntilStockout(currentStock, avgDailyConsumption);
+  const reorderDate = suggestedReorderDate(daysUntilOut, leadTimeDays, nowSeconds);
+  const reorderDue = isReorderDue(reorderDate, nowSeconds);
+
+  return { avg_daily_consumption: avgDailyConsumption, days_until_stockout: daysUntilOut, reorder_date: reorderDate, reorder_due: reorderDue };
+}

package/src/ui/entity-renderer.js

@@ -139,6 +139,24 @@ export function renderEntityDetail(entityName, item, spec, user, history = []) {
       })()
     : ''
 
+  // Forecast fields are computed alongside current_stock (page-handler.js's
+  // inventory-forecast.js), same not-a-spec-field treatment.
+  const forecastRow = entityName === 'product' && item.days_until_stockout !== undefined
+    ? (() => {
+        const daysLabel = item.days_until_stockout == null ? 'Unknown (no recent consumption)' : `${Math.round(item.days_until_stockout)} days`
+        const reorderLabel = item.reorder_date == null ? '-' : new Date(item.reorder_date * 1000).toISOString().slice(0, 10)
+        const pillCls = item.reorder_due ? 'pill-danger' : 'pill-success'
+        return `<div class="detail-row">
+          <span class="detail-row-label">Days Until Stockout</span>
+          <span class="detail-row-value">${esc(daysLabel)}</span>
+        </div>
+        <div class="detail-row">
+          <span class="detail-row-label">Suggested Reorder Date</span>
+          <span class="detail-row-value"><span class="pill ${pillCls}">${esc(reorderLabel)}${item.reorder_due ? ' (Reorder Now)' : ''}</span></span>
+        </div>`
+      })()
+    : ''
+
   // total_hours/billable_amount are computed (page-handler.js sums time_entry
   // rows, directly for a task or joined through task for a project), same
   // not-a-spec-field treatment as current_stock above.
@@ -177,7 +195,7 @@ export function renderEntityDetail(entityName, item, spec, user, history = []) {
 
   const visibleFields = Object.entries(fields).filter(([k]) => k !== 'id' && !HIDDEN_FIELDS.has(k) && item[k] !== undefined)
 
-  const fieldRows = stockRow + timeTrackingRows + expiryRow + utilizationRow + visibleFields.map(([k, f]) =>
+  const fieldRows = stockRow + forecastRow + timeTrackingRows + expiryRow + utilizationRow + visibleFields.map(([k, f]) =>
     `<div class="detail-row">
       <span class="detail-row-label">${esc(f.label || k)}</span>
       <span class="detail-row-value">${formatFieldValue(k, item[k], entityName, f)}</span>

package/src/ui/page-handler.js

@@ -9,7 +9,7 @@ import { renderEngagementGrid } from '@/ui/engagement-grid-renderer.js';
 import { renderBoardView } from '@/ui/board-view-renderer.js';
 import { renderGridView } from '@/ui/grid-view-renderer.js';
 import { renderCalendarView, renderTimelineView } from '@/ui/calendar-view-renderer.js';
-import { renderCountByFieldReport, renderCountOverTimeReport, renderSumByFieldReport, renderRollupReport } from '@/ui/report-renderer.js';
+import { renderCountByFieldReport, renderCountOverTimeReport, renderSumByFieldReport, renderRollupReport, renderInventoryForecastReport } from '@/ui/report-renderer.js';
 import { renderClientProgress } from '@/ui/client-progress-renderer.js';
 import { renderLetterWorkflow } from '@/ui/letter-workflow-renderer.js';
 import { renderAdvancedSearch } from '@/ui/advanced-search-renderer.js';
@@ -118,12 +118,18 @@ async function handleGenericEntityView(user, entityName, id, req) {
   if (entityName === 'product') {
     // current_stock is derived, never a stored/editable field -- summed fresh
     // from stock_movement history so it can never drift from the ledger the
-    // way a separately-writable counter could.
+    // way a separately-writable counter could. stock_movement carries no
+    // organization_id (product is a system_entity, exempt from multi-tenancy
+    // auto-scoping the same way every other system entity this session is),
+    // so this unscoped list() matches the entity's actual access model
+    // rather than bypassing a row-access check that was never in effect.
     try {
       const movements = await list('stock_movement', { product_id: id });
       const currentStock = movements.reduce((sum, m) => sum + (Number(m.quantity) || 0), 0);
-      resolvedItem = { ...resolvedItem, current_stock: currentStock };
-    } catch { resolvedItem = { ...resolvedItem, current_stock: 0 }; }
+      const { computeInventoryForecast } = await import('@/lib/inventory-forecast.js');
+      const forecast = computeInventoryForecast(resolvedItem, movements, currentStock);
+      resolvedItem = { ...resolvedItem, current_stock: currentStock, ...forecast };
+    } catch { resolvedItem = { ...resolvedItem, current_stock: 0, avg_daily_consumption: 0, days_until_stockout: null, reorder_date: null, reorder_due: false }; }
   }
   if (entityName === 'task') {
     // total_hours/billable_amount are derived from time_entry history, same
@@ -370,6 +376,22 @@ export async function handlePage(pathname, req, res) {
       const relatedRecords = await list(relatedEntity, {}, { user });
       return renderRollupReport(user, entityName, spec, items, refField, relatedEntity, relatedSpec, relatedRecords, rollupField);
     }
+    if (report === 'inventory-forecast' && entityName === 'product') {
+      // items is already the {user}-scoped product list from above -- no new
+      // unscoped bulk query. stock_movement itself carries no organization_id
+      // (product is a system_entity, exempt from multi-tenancy auto-scoping
+      // like every other system entity this session), so it is read
+      // per-product the same unscoped way the detail view already does.
+      const { computeInventoryForecast } = await import('@/lib/inventory-forecast.js');
+      const forecastRows = [];
+      for (const p of items) {
+        const movements = await list('stock_movement', { product_id: p.id });
+        const currentStock = movements.reduce((sum, m) => sum + (Number(m.quantity) || 0), 0);
+        const forecast = computeInventoryForecast(p, movements, currentStock);
+        forecastRows.push({ ...p, current_stock: currentStock, ...forecast });
+      }
+      return renderInventoryForecastReport(user, spec, forecastRows);
+    }
     const view = params.get('view');
     if (view === 'board') return renderBoardView(user, entityName, spec, items);
     if (view === 'grid') return renderGridView(user, entityName, spec, items);

package/src/ui/report-renderer.js

@@ -206,3 +206,34 @@ export function renderCountOverTimeReport(user, entityName, spec, records, dateF
     ${barChart(buckets)}`;
   return page(user, `${label} Report | Thatcher`, null, content);
 }
+
+// One table per-product rather than a bar chart: unlike count-by-field/
+// sum-by-field's single grouped metric, a forecast is inherently multiple
+// values per row (stock, consumption rate, days-out, reorder date) -- a bar
+// chart of any single one of those would discard the others, so a table is
+// the correct shape here, reusing the same page()/esc() rendering discipline
+// as every other report rather than inventing a new chart type.
+export function renderInventoryForecastReport(user, spec, forecastRows) {
+  const label = getEntityLabel(spec, true) || 'Products';
+  const rows = forecastRows.map(p => {
+    const daysLabel = p.days_until_stockout == null ? 'Unknown' : String(Math.round(p.days_until_stockout))
+    const reorderLabel = p.reorder_date == null ? '-' : new Date(p.reorder_date * 1000).toISOString().slice(0, 10)
+    const rowCls = p.reorder_due ? 'style="background:var(--color-danger-bg,#fee2e2)"' : ''
+    return `<tr ${rowCls}>
+      <td>${esc(p.name || p.id)}</td>
+      <td>${esc(String(p.current_stock))}</td>
+      <td>${esc((p.avg_daily_consumption || 0).toFixed(2))}</td>
+      <td>${esc(daysLabel)}</td>
+      <td>${esc(reorderLabel)}${p.reorder_due ? ' <span class="pill pill-danger">Reorder Now</span>' : ''}</td>
+    </tr>`;
+  }).join('') || emptyState('No products to forecast', 'bar-chart');
+
+  const content = `<div class="page-header">
+      <div><h1 class="page-title">${esc(label)}: Inventory Forecast</h1><p class="page-subtitle">${forecastRows.length} products</p></div>
+    </div>
+    <div class="table-wrap"><table class="data-table">
+      <thead><tr><th>Product</th><th>Current Stock</th><th>Avg Daily Use</th><th>Days Until Stockout</th><th>Suggested Reorder</th></tr></thead>
+      <tbody>${rows}</tbody>
+    </table></div>`;
+  return page(user, `Inventory Forecast | Thatcher`, null, content);
+}