thatcher 1.0.86 → 1.0.87

package/package.json

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

package/src/lib/resource-capacity.js

@@ -0,0 +1,28 @@
+// Single source of truth for resource-allocation load math, extracted from
+// entity-validators.js's checkResourceCapacity so the over-allocation
+// PREVENTION check and the resource-optimizer's SUGGESTION ranking compute a
+// user's committed load identically -- two independently-maintained copies
+// of the same overlap/sum formula would inevitably drift.
+export const DEFAULT_WEEKLY_CAPACITY_HOURS = 40;
+
+// Two date ranges overlap unless one entirely precedes the other -- the
+// standard interval-intersection test, not a same-day/exact-match check.
+export function rangesOverlap(startA, endA, startB, endB) {
+  return Number(startA) <= Number(endB) && Number(startB) <= Number(endA);
+}
+
+// Sum of allocated_hours_per_week across every existing allocation for
+// userId whose date range overlaps [startDate, endDate], excluding
+// excludeAllocationId (the record being updated, if any, so it doesn't
+// double-count itself). Reads via list('resource_allocation', {user_id}),
+// the same unscoped-internal lookup pattern every other entity-specific
+// check this session (checkStockBalance/checkContractDateOrder) already
+// uses -- no user context threaded through this layer.
+export async function userCommittedHours(userId, startDate, endDate, excludeAllocationId = null) {
+  const { list } = await import('./busybase/store.js');
+  const existingAllocations = await list('resource_allocation', { user_id: userId });
+  const overlapping = existingAllocations.filter(a =>
+    a.id !== excludeAllocationId && rangesOverlap(startDate, endDate, a.start_date, a.end_date)
+  );
+  return overlapping.reduce((sum, a) => sum + (Number(a.allocated_hours_per_week) || 0), 0);
+}

package/src/lib/resource-optimizer.js

@@ -0,0 +1,20 @@
+import { userCommittedHours, DEFAULT_WEEKLY_CAPACITY_HOURS } from './resource-capacity.js';
+
+// Ranks a pool of REAL users (queried from the user list, never an arbitrary
+// id range) by remaining weekly capacity in the given date range, using the
+// exact same overlap-based load calculation checkResourceCapacity already
+// enforces -- so a "best fit" suggestion and the prevention check it feeds
+// into can never disagree about how loaded a candidate actually is.
+// Excludes anyone already at or over capacity entirely (not just ranked
+// last), since they are not a valid suggestion regardless of rank.
+export async function suggestBestFitUsers(candidateUserIds, startDate, endDate, hoursNeeded, capacityHours = DEFAULT_WEEKLY_CAPACITY_HOURS) {
+  const results = [];
+  for (const userId of candidateUserIds) {
+    const committedHours = await userCommittedHours(userId, startDate, endDate);
+    const remainingCapacity = capacityHours - committedHours;
+    if (remainingCapacity < hoursNeeded) continue;
+    results.push({ user_id: userId, committed_hours: committedHours, remaining_capacity: remainingCapacity });
+  }
+  results.sort((a, b) => b.remaining_capacity - a.remaining_capacity);
+  return results;
+}

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

@@ -303,19 +303,14 @@ async function checkCrossEntityRules(entityName, data, existingRecord) {
   return null;
 }
 
-const WEEKLY_CAPACITY_HOURS = 40;
-
-// Two date ranges overlap unless one entirely precedes the other -- the
-// standard interval-intersection test, not a same-day/exact-match check.
-function rangesOverlap(startA, endA, startB, endB) {
-  return Number(startA) <= Number(endB) && Number(startB) <= Number(endA);
-}
-
 // A user's total weekly allocation across every project they're assigned to,
 // for any date range that overlaps the new/changed allocation, must not
 // exceed a configurable weekly capacity. Checked against EVERY OTHER
 // existing allocation for that user (excluding the record being updated, if
-// any) plus the new one -- never trusting a client-supplied total.
+// any) plus the new one -- never trusting a client-supplied total. The
+// overlap/load math itself lives in resource-capacity.js, shared with
+// resource-optimizer.js's suggestion ranking so both compute a user's
+// committed load identically.
 async function checkResourceCapacity(entityName, data, existingRecord) {
   if (entityName !== 'resource_allocation') return null;
   const userId = data.user_id !== undefined ? data.user_id : existingRecord?.user_id;
@@ -324,15 +319,11 @@ async function checkResourceCapacity(entityName, data, existingRecord) {
   const hours = Number(data.allocated_hours_per_week !== undefined ? data.allocated_hours_per_week : existingRecord?.allocated_hours_per_week);
   if (!userId || startDate == null || endDate == null || !Number.isFinite(hours)) return null;
 
-  const { list } = await import('@/lib/busybase/store');
-  const existingAllocations = await list('resource_allocation', { user_id: userId });
-  const overlapping = existingAllocations.filter(a =>
-    a.id !== existingRecord?.id && rangesOverlap(startDate, endDate, a.start_date, a.end_date)
-  );
-  const overlappingTotal = overlapping.reduce((sum, a) => sum + (Number(a.allocated_hours_per_week) || 0), 0);
+  const { userCommittedHours, DEFAULT_WEEKLY_CAPACITY_HOURS } = await import('@/lib/resource-capacity');
+  const overlappingTotal = await userCommittedHours(userId, startDate, endDate, existingRecord?.id);
   const resultingTotal = overlappingTotal + hours;
-  if (resultingTotal > WEEKLY_CAPACITY_HOURS) {
-    return `Over-allocated: this would bring the user's weekly total to ${resultingTotal}h against overlapping allocations, exceeding the ${WEEKLY_CAPACITY_HOURS}h capacity`;
+  if (resultingTotal > DEFAULT_WEEKLY_CAPACITY_HOURS) {
+    return `Over-allocated: this would bring the user's weekly total to ${resultingTotal}h against overlapping allocations, exceeding the ${DEFAULT_WEEKLY_CAPACITY_HOURS}h capacity`;
   }
   return null;
 }

package/src/server/server.js

@@ -151,6 +151,10 @@ export function createServer(options) {
           return await handleChangesSince(req, res, parts[1], parts[2], parts[4]);
         }
 
+        if (req.method === 'GET' && entity === 'resource-optimizer' && id === 'suggest') {
+          return await handleResourceOptimizerSuggest(req, res);
+        }
+
         if (req.method === 'GET' && entity === 'auth' && id === 'google' && !action) {
           return await handleOAuthGoogleStart(req, res);
         }
@@ -1589,6 +1593,46 @@ async function handlePresenceHeartbeat(req, res, entityName, id) {
   res.end(JSON.stringify({ ok: true }));
 }
 
+async function handleResourceOptimizerSuggest(req, res) {
+  const user = await resolveRequestUser(req);
+  if (!user) {
+    res.writeHead(401, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Authentication required' }));
+    return;
+  }
+
+  const url = new URL(req.url, `http://${req.headers.host}`);
+  const startDate = Number(url.searchParams.get('start_date'));
+  const endDate = Number(url.searchParams.get('end_date'));
+  const hoursNeeded = Number(url.searchParams.get('hours_needed'));
+  if (!Number.isFinite(startDate) || !Number.isFinite(endDate) || !Number.isFinite(hoursNeeded)) {
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'start_date, end_date, and hours_needed are required numeric query params' }));
+    return;
+  }
+
+  // Self-only unless partner/manager -- the SAME privilege boundary
+  // resource_allocation's own checkTimeEntryOwnership-derived ownership
+  // check already enforces on write. A non-privileged caller asking for
+  // suggestions must not learn how loaded ANY other user is (that leaks
+  // workload/capacity across the org), so their candidate pool is
+  // themselves alone rather than filtered results from a broader query.
+  const isPrivileged = ['partner', 'admin', 'manager'].includes(user.role);
+  let candidateUserIds;
+  if (isPrivileged) {
+    const { list } = await import('../lib/busybase/store.js');
+    const users = await list('user', {});
+    candidateUserIds = users.map(u => u.id);
+  } else {
+    candidateUserIds = [user.id];
+  }
+
+  const { suggestBestFitUsers } = await import('../lib/resource-optimizer.js');
+  const suggestions = await suggestBestFitUsers(candidateUserIds, startDate, endDate, hoursNeeded);
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ suggestions }));
+}
+
 async function handlePresenceGet(req, res, entityName, id) {
   const user = await verifyRecordAccess(req, res, entityName, id);
   if (!user) return;

package/src/ui/entity-renderer.js

@@ -315,7 +315,10 @@ export function renderEntityForm(entityName, item, spec, user, isNew = false, re
     }
     if (f.type === 'ref' && refOptions[k]) {
       const opts = refOptions[k].map(o => `<option value="${esc(o.value)}" ${val===o.value?'selected':''}>${esc(o.label)}</option>`).join('')
-      return `<div class="form-field">${lbl(k,f,f.required)}<select id="field-${k}" name="${k}" class="form-input" ${req}><option value="">Select ${esc(f.label||k)}...</option>${opts}</select></div>`
+      const suggestBtn = entityName === 'resource_allocation' && k === 'user_id'
+        ? `<button type="button" class="btn-ghost-clean" style="margin-top:4px" data-action="suggestBestFitUser">Suggest best-fit user</button>`
+        : ''
+      return `<div class="form-field">${lbl(k,f,f.required)}<select id="field-${k}" name="${k}" class="form-input" ${req}><option value="">Select ${esc(f.label||k)}...</option>${opts}</select>${suggestBtn}</div>`
     }
     if (f.type === 'textarea') return `<div class="form-field full">${lbl(k,f,f.required)}<textarea id="field-${k}" name="${k}" class="form-input" style="min-height:100px;resize:vertical" ${req} placeholder="Enter ${esc((f.label||k).toLowerCase())}">${esc(val)}</textarea></div>`
     if (f.type === 'bool') return `<div class="form-field"><label style="display:flex;align-items:center;gap:8px;cursor:pointer"><input type="checkbox" id="field-${k}" name="${k}" class="checkbox checkbox-primary" ${val?'checked':''}/><span class="form-label" style="margin:0">${esc(f.label||k)}</span></label></div>`
@@ -361,7 +364,10 @@ export function renderEntityForm(entityName, item, spec, user, isNew = false, re
     <div class="form-actions" style="grid-column:1/-1"><button type="submit" id="submit-btn" class="btn-primary-clean"><span class="btn-text">Save</span><span class="btn-loading-text" style="display:none">Saving...</span></button>
     <a href="/${entityName}${isNew ? '' : '/' + item?.id}" class="btn-ghost-clean">Cancel</a></div></form></div></div>`
   const script = `${TOAST_SCRIPT}const form=document.getElementById('entity-form');const sb=document.getElementById('submit-btn');form.addEventListener('submit',async(e)=>{e.preventDefault();sb.classList.add('btn-loading');sb.querySelector('.btn-text').style.display='none';sb.querySelector('.btn-loading-text').style.display='inline';sb.disabled=true;try{const fileInputs=[...form.querySelectorAll('input[type=file][data-attachment]')];for(const fi of fileInputs){const f=fi.files&&fi.files[0];if(!f)continue;const uf=new FormData();uf.append('file',f);const ures=await fetch('/api/upload',{method:'POST',body:uf});const ud=await ures.json();if(!ures.ok)throw new Error(ud.error||'File upload failed');const hidden=document.getElementById('field-'+fi.dataset.attachment+'-value');hidden.value=JSON.stringify(ud)}const fd=new FormData(form);const data={};for(const[k,v]of fd.entries()){if(k.endsWith('[]'))continue;data[k]=v}form.querySelectorAll('input[type=checkbox]:not([name$="[]"])').forEach(cb=>{data[cb.name]=cb.checked});form.querySelectorAll('[data-multiselect]').forEach(ms=>{const name=ms.dataset.multiselect;data[name]=[...ms.querySelectorAll('input[type=checkbox]:checked')].map(cb=>cb.value)});form.querySelectorAll('input[type=number]:not([data-currency])').forEach(inp=>{if(inp.name&&data[inp.name]!==undefined&&data[inp.name]!=='')data[inp.name]=Number(data[inp.name])});form.querySelectorAll('input[data-currency]').forEach(inp=>{const name=inp.dataset.currency;if(inp.value!=='')data[name]=Math.round(Number(inp.value)*100)});const url=${isNew}?'/api/${entityName}':'/api/${entityName}/${item?.id}';const method=${isNew}?'POST':'PUT';const res=await fetch(url,{method,headers:{'Content-Type':'application/json'},body:JSON.stringify(data)});const result=await res.json();if(res.ok){showToast('${isNew?'Created':'Updated'} successfully!','success');const ed=result.data||result;setTimeout(()=>{window.location='/${entityName}/'+(ed.id||'${item?.id}')},500)}else{showToast(result.message||result.error||'Save failed','error');sb.classList.remove('btn-loading');sb.querySelector('.btn-text').style.display='inline';sb.querySelector('.btn-loading-text').style.display='none';sb.disabled=false}}catch(err){showToast('Error: '+err.message,'error');sb.classList.remove('btn-loading');sb.querySelector('.btn-text').style.display='inline';sb.querySelector('.btn-loading-text').style.display='none';sb.disabled=false}})`
-  return page(user, `${isNew ? 'Create' : 'Edit'} ${label}`, bc, content, [script])
+  const suggestScript = entityName === 'resource_allocation'
+    ? `window.suggestBestFitUser=async function(){const start=document.getElementById('field-start_date');const end=document.getElementById('field-end_date');const hours=document.getElementById('field-allocated_hours_per_week');if(!start.value||!end.value||!hours.value){showToast('Fill in start date, end date, and hours first','error');return}const startTs=Math.floor(new Date(start.value).getTime()/1000);const endTs=Math.floor(new Date(end.value).getTime()/1000);try{const res=await fetch('/api/resource-optimizer/suggest?start_date='+startTs+'&end_date='+endTs+'&hours_needed='+encodeURIComponent(hours.value));const data=await res.json();if(!res.ok){showToast(data.error||'Suggestion failed','error');return}if(!data.suggestions||!data.suggestions.length){showToast('No user has enough remaining capacity','warning');return}const top=data.suggestions[0];const select=document.getElementById('field-user_id');if(select){select.value=top.user_id;showToast('Suggested user selected ('+top.remaining_capacity+'h remaining capacity)','success')}}catch(err){showToast('Error: '+err.message,'error')}}`
+    : ''
+  return page(user, `${isNew ? 'Create' : 'Edit'} ${label}`, bc, content, [script, suggestScript])
 }
 
 export function renderSettings(user, config = {}) {