@arcforgelabs/flow 2026.10.42 → 2026.10.44

package/README.md

@@ -35,6 +35,7 @@ run a lab.
 | `docs/index.md` | The docs site home page |
 | `docs/releases/` | One release notes page per version (`<version>.md`), shown on the docs site |
 | `docs/DESIGN.md` | The design systems (theme families), how pages and Clerk's components take them, and the screens |
+| `docs/DESIGN_SYSTEM.md` | The Flow Design System artifact: how `npm run design-system` builds it from the code, the card per shared component, publishing and review |
 | `docs/DATA_MODEL.md` | The PostgreSQL records, the rules the database holds, and how to change the schema |
 | `docs/DATA_SPINE.md` | The design of the tables and jobs every integration shares: mirror, identity map, job queue, outbox, review queue |
 | `docs/JOB_INVOICE_LINKS.md` | The pipeline: how each job links to its customer and to the accounting invoice that bills it |

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.42",
+  "version": "2026.10.44",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.42",
+      "version": "2026.10.44",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.25.0",
@@ -33,7 +33,8 @@
         "flow-server": "server/flow-server.js"
       },
       "devDependencies": {
-        "drizzle-kit": "0.31.11"
+        "drizzle-kit": "0.31.11",
+        "esbuild": "0.25.12"
       },
       "engines": {
         "node": ">=24"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.42",
+  "version": "2026.10.44",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {
@@ -36,7 +36,8 @@
     "theme:contrast": "node scripts/theme-contrast.mjs",
     "db:generate": "drizzle-kit generate && node scripts/db-guard-migrations.js",
     "db:follow-production": "node scripts/replit-workspace-db.js sync",
-    "db:follow-production:status": "node scripts/replit-workspace-db.js status"
+    "db:follow-production:status": "node scripts/replit-workspace-db.js status",
+    "design-system": "node scripts/design-system/build.mjs"
   },
   "dependencies": {
     "@clerk/backend": "3.25.0",
@@ -60,7 +61,8 @@
     "pg": "8.23.1"
   },
   "devDependencies": {
-    "drizzle-kit": "0.31.11"
+    "drizzle-kit": "0.31.11",
+    "esbuild": "0.25.12"
   },
   "overrides": {
     "@esbuild-kit/core-utils": {

package/server/auth/people.js

@@ -2,7 +2,8 @@ import { and, asc, eq, isNull, ne, sql } from 'drizzle-orm';
 import { people, PERSON_ROLES } from '../db/schema.js';
 import { FlowError } from '../core/errors.js';
 import { isThemeFamily, normalizeAccent } from '../theme/themes.js';
-import { normaliseJobsView } from '../ui/job-view.js';
+import { INVOICE_COLUMNS, normaliseJobsView, normaliseListView, RECONCILE_COLUMNS } from '../ui/job-view.js';
+import { normaliseSavedViews, SAVED_VIEW_PAGES } from '../ui/list-views.js';
 import { isPlainEmail } from './settings.js';
 
 // The people who may sign in, and their roles. Only an owner changes this
@@ -57,10 +58,12 @@ export async function setPersonAppearance(db, { id, appearance }) {
 function viewCheck(page) {
   switch (page) {
     case 'jobs': return normaliseJobsView;
+    case 'invoices': return (view) => normaliseListView(view, INVOICE_COLUMNS);
+    case 'reconcile': return (view) => normaliseListView(view, RECONCILE_COLUMNS);
     default: return null;
   }
 }
-const VIEW_PAGE_NAMES = ['jobs'];
+const VIEW_PAGE_NAMES = ['jobs', 'invoices', 'reconcile'];
 
 // A person's saved views as Flow sends them: only the known pages, each
 // checked, so a view saved by an older Flow still loads.
@@ -68,9 +71,31 @@ export function normaliseViews(input) {
   const value = input && typeof input === 'object' ? input : {};
   const out = {};
   for (const page of VIEW_PAGE_NAMES) if (value[page]) out[page] = viewCheck(page)(value[page]);
+  // The named views a person saved on each page, and their default
+  // (ui/list-views.js), kept under `saved`.
+  const saved = value.saved && typeof value.saved === 'object' ? value.saved : {};
+  const lists = {};
+  for (const page of SAVED_VIEW_PAGES) if (saved[page]) lists[page] = normaliseSavedViews(page, saved[page]);
+  if (Object.keys(lists).length) out.saved = lists;
   return out;
 }
 
+// Each person keeps their own named views of a page and picks their
+// default; saving one page's list leaves the other pages as they were.
+export async function setPersonSavedViews(db, { id, page, saved }) {
+  if (!SAVED_VIEW_PAGES.includes(page)) throw new FlowError('not_found', 'no such page');
+  const value = normaliseSavedViews(page, saved);
+  const [row] = await db.update(people)
+    .set({
+      views: sql`coalesce(${people.views}, '{}'::jsonb) || jsonb_build_object('saved', coalesce(${people.views}->'saved', '{}'::jsonb) || ${JSON.stringify({ [page]: value })}::jsonb)`,
+      updatedAt: new Date(),
+    })
+    .where(eq(people.id, id))
+    .returning();
+  if (!row) throw new FlowError('not_found', 'person not found');
+  return value;
+}
+
 // Each person keeps their own view of a page; saving one page leaves the
 // others as they were.
 export async function setPersonView(db, { id, page, view }) {
@@ -141,6 +166,19 @@ export async function linkPerson(db, { id, clerkUserId }) {
   return row ?? null;
 }
 
+// Fills a person's name from their sign-in account (Clerk) when Flow has
+// none, so pickers show "Jane Citizen", not an email. A name Flow already
+// holds stays.
+export async function fillPersonName(db, { id, name }) {
+  const value = String(name ?? '').trim();
+  if (!value) return null;
+  const [row] = await db.update(people)
+    .set({ name: value, updatedAt: new Date() })
+    .where(and(eq(people.id, id), isNull(people.name)))
+    .returning();
+  return row ?? null;
+}
+
 // While the installation has no owner, invite `email` as its owner (or make
 // that person the owner if they are already listed). Returns the row, or null
 // when an owner already exists.

package/server/auth/routes.js

@@ -13,6 +13,7 @@ import {
   publicPerson,
   removePerson,
   setPersonAppearance,
+  setPersonSavedViews,
   setPersonView,
   updatePerson,
 } from './people.js';
@@ -127,6 +128,16 @@ export function createSignInRouter({ settings, db, clerk, personAuth, defaultFam
     }
   });
 
+  // Each person's named views of a page and their default (ui/list-views.js).
+  router.put('/api/me/saved-views/:page', requireSession, express.json({ limit: '64kb' }), async (req, res) => {
+    try {
+      const saved = await setPersonSavedViews(db, { id: req.person.id, page: req.params.page, saved: req.body });
+      res.json({ ok: true, saved });
+    } catch (error) {
+      sendError(res, error, log);
+    }
+  });
+
   // Only an owner manages people.
   const people = express.Router();
   people.use(requireSession, requireOwner, express.json({ limit: '16kb' }));

package/server/auth/session.js

@@ -1,5 +1,5 @@
 import { displayNameOf, googleWorkspaceOwner, primaryEmailOf, secondFactorVerified } from './clerk.js';
-import { findPersonByClerkId, findPersonByEmail, linkPerson, recordPendingPerson } from './people.js';
+import { fillPersonName, findPersonByClerkId, findPersonByEmail, linkPerson, recordPendingPerson } from './people.js';
 import { DEFAULT_OWNER_MFA_MAX_AGE_MINUTES, isPlainEmail } from './settings.js';
 
 // Checks the Clerk session on every person request, then maps the Clerk user
@@ -60,10 +60,29 @@ export function createPersonAuth({
   // owner requests costs one Clerk call. Failures are never cached.
   const clerkUsers = new Map();
 
+  // Clerk users already checked for a name in this run, so a person whose
+  // sign-in has no name costs one Clerk call, not one per request.
+  const nameChecked = new Set();
+
+  // The person, with their Clerk name filled in when Flow has none. Never
+  // stops a sign-in: a Clerk error keeps the person as they are.
+  async function withName(person, clerkUser = null) {
+    if (person.name?.trim() || nameChecked.has(person.clerkUserId)) return person;
+    if (nameChecked.size > 1000) nameChecked.clear();
+    nameChecked.add(person.clerkUserId);
+    try {
+      const name = displayNameOf(clerkUser ?? await cachedClerkUser(person.clerkUserId));
+      return (name && await fillPersonName(db, { id: person.id, name })) || person;
+    } catch (error) {
+      log.warn?.(`[auth] could not read the name of Flow person ${person.id}: ${error.message}`);
+      return person;
+    }
+  }
+
   // { person } or { denial }.
   async function personFor(clerkUserId) {
     const linked = await findPersonByClerkId(db, clerkUserId);
-    if (linked) return { person: linked };
+    if (linked) return { person: await withName(linked) };
 
     const clerkUser = await clerk.getUser(clerkUserId);
     const { email, verified } = primaryEmailOf(clerkUser);
@@ -76,7 +95,7 @@ export function createPersonAuth({
       const person = await linkPerson(db, { id: invited.id, clerkUserId });
       if (person) {
         log.info?.(`[auth] linked Clerk user ${clerkUserId} to Flow person ${person.id} (${person.role})`);
-        return { person };
+        return { person: await withName(person, clerkUser) };
       }
       const again = await findPersonByClerkId(db, clerkUserId);
       return again ? { person: again } : { denial: 'email_linked_elsewhere' };

package/server/core/custom-fields.js

@@ -4,6 +4,7 @@ import {
   CUSTOM_FIELD_TYPES, integrationSettingEvents, integrationSettings, jobFieldEvents, jobFields, jobFieldSettings, jobFieldValues, people,
 } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
+import { personLabel } from '../ui/person.js';
 
 // Custom fields (docs/CUSTOM_FIELDS.md): fields a lab makes for its jobs in
 // Flow, like ClickUp's custom fields. An owner or admin makes them in
@@ -372,11 +373,11 @@ export async function listJobFieldValues(db, organisationId, { jobs = null } = {
   return rows.filter((r) => !wanted || wanted.has(`${r.sourceSystem}\u0000${r.sourceJobRef}`)).map(publicValue);
 }
 
-// The people a person field can name: every active person, by id and name
-// (the part of the email before @ when they have no name), A to Z.
+// The people a person field can name: every active person, by id and label
+// (full name, else the whole email: server/ui/person.js), A to Z.
 export async function choosablePeople(db) {
   const rows = await db.select({ id: people.id, name: people.name, email: people.email }).from(people).where(eq(people.status, 'active'));
-  return rows.map((r) => ({ id: r.id, name: r.name?.trim() || r.email.replace(/@.*/, '') }))
+  return rows.map((r) => ({ id: r.id, name: personLabel(r) }))
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 

package/server/core/invoice-rules.js

@@ -57,7 +57,7 @@ export const TESTS = Object.freeze({
   number: ['more_than', 'at_most', 'is', 'is_not', 'is_empty'],
   money: ['more_than', 'at_most', 'is', 'is_not'],
   choice: ['is', 'is_not', 'is_one_of', 'is_empty'],
-  text: ['is', 'is_not', 'is_one_of', 'is_not_one_of', 'contains', 'does_not_contain', 'starts_with', 'does_not_start_with', 'has_number', 'one_word', 'is_empty', 'is_not_empty'],
+  text: ['is', 'is_not', 'is_one_of', 'is_not_one_of', 'contains', 'does_not_contain', 'starts_with', 'does_not_start_with', 'has_number', 'number_in_words', 'one_word', 'is_empty', 'is_not_empty'],
   boolean: ['is'],
   items: ['has', 'has_not'],
   share: ['is', 'is_not'],
@@ -65,7 +65,7 @@ export const TESTS = Object.freeze({
 
 export const ACTIONS = Object.freeze(['wait', 'skip', 'pending']);
 // Tests that take no value.
-const NO_VALUE = new Set(['is_empty', 'is_not_empty', 'has_number', 'one_word']);
+const NO_VALUE = new Set(['is_empty', 'is_not_empty', 'has_number', 'number_in_words', 'one_word']);
 
 function readCondition(raw, index) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw invalid(`condition ${index + 1} must be an object`);
@@ -131,6 +131,9 @@ function matches(condition, job, context) {
     if (!left) return false;
     if (test === 'is_not_one_of') return !value.some((v) => norm(v) === left);
     if (test === 'has_number') return /\d/.test(left);
+    // A part (between " - ") that is only a number is a client's reference,
+    // such as a patient number, so only a number beside words matches.
+    if (test === 'number_in_words') return left.split(' - ').some((part) => /\d/.test(part) && /\p{L}/u.test(part));
     if (test === 'one_word') return !left.includes(' ');
     if (test === 'contains') return left.includes(norm(value));
     if (test === 'does_not_contain') return !left.includes(norm(value));
@@ -182,12 +185,14 @@ export function ruleReasons(rules, job, { customer = {}, now = new Date() } = {}
 // The notes of the enabled pending rules that match one draft, as problems:
 // they put the draft on Pending (sending.js). `job` is the draft's job with
 // `reference`, the draft's Reference. A pending rule never stops a draft.
+// `fields` names the fields the rule reads, so the invoice page marks the
+// one to fix (the Reference box goes red).
 export function rulePending(rules, job, { customer = {}, now = new Date() } = {}) {
   const context = { customer, now };
   return rules
     .filter((r) => r.enabled && r.trigger === 'job_ready' && r.action.kind === 'pending')
     .filter((r) => r.conditions.every((c) => matches(c, job, context)))
-    .map((r) => ({ code: 'rule', message: r.action.note, short: r.name.slice(0, 40), rule: r.id ?? null }));
+    .map((r) => ({ code: 'rule', message: r.action.note, short: r.name.slice(0, 40), rule: r.id ?? null, fields: [...new Set(r.conditions.map((c) => c.field))] }));
 }
 
 // The starter rules made from the earlier fixed settings.

package/server/core/job-match.js

@@ -87,8 +87,9 @@ function jobLines(o, codes) {
 }
 
 // The two queues, oldest first. jobs: { id, clientName, practitioner,
-// jobDate, totalCents, possible }; invoices: { id, number, clientName,
-// issueDate, status, totalCents, possible }. `possible` counts the other
+// jobDate, totalCents, status, sourceSystem, sourceJobRef, possible };
+// invoices: { id, number, clientName, issueDate, status, totalCents,
+// possible }. `possible` counts the other
 // side with the same client and total.
 export async function listReconcile(db, organisationId) {
   const jobs = await db.select({
@@ -97,6 +98,9 @@ export async function listReconcile(db, organisationId) {
     practitioner: billingObligations.practitioner,
     jobDate: billingObligations.jobDate,
     totalCents: billingObligations.totalCents,
+    status: billingObligations.sourceStatus,
+    sourceSystem: billingObligations.sourceSystem,
+    sourceJobRef: billingObligations.sourceJobRef,
     // An unclear accounting match: "Make invoice" settles it first.
     unclear: sql`${billingObligations.accountingState} = 'ambiguous'`.mapWith(Boolean),
     possible: sql`(select count(*) from invoices i

package/server/core/sending.js

@@ -38,8 +38,9 @@ const LEASE_MS = 15 * 60 * 1000;
 // Outcomes that mean the accounting system holds the invoice.
 const SENT = new Set(['created', 'reconciled', 'existing', 'already_in_xero']);
 
-// `short` is the few words the Invoices list shows; `message` says how to fix it.
-const problem = (code, message, short = null) => ({ code, message, ...(short ? { short } : {}) });
+// `short` is the few words the Invoices list shows; `message` says how to fix
+// it. `extra` adds `fields` (the invoice fields to fix) and `line`.
+const problem = (code, message, short = null, extra = {}) => ({ code, message, ...(short ? { short } : {}), ...extra });
 
 // Flow's own checks of one draft. `lines` are its invoice lines.
 export function draftProblems(invoice, lines) {
@@ -47,7 +48,7 @@ export function draftProblems(invoice, lines) {
   if (!lines.length) problems.push(problem('no_lines', 'The invoice has no lines.', 'No lines'));
   else if (invoice.totalCents <= 0) problems.push(problem('no_amount', 'The total is $0.00 or less.', 'Total $0'));
   for (const line of lines) {
-    if (!line.priceItemId && !line.accountCode) problems.push(problem('line_no_item', `Line ${line.position} has no price item.`, `Line ${line.position}: no item`));
+    if (!line.priceItemId && !line.accountCode) problems.push(problem('line_no_item', `Line ${line.position} has no price item.`, `Line ${line.position}: no item`, { fields: ['line_item'], line: line.position }));
   }
   return problems;
 }

package/server/integrations/sentry/index.js

@@ -42,6 +42,7 @@ export const SENTRY_SETUP = {
   fields: [
     { name: 'SENTRY_DSN', label: 'DSN', kind: 'url', help: 'From the Sentry project\'s Client Keys. Browsers see it, so it is not a secret.' },
     { name: 'SENTRY_ENVIRONMENT', label: 'Environment', help: 'How Sentry labels this installation, for example production. Empty: production, or workspace in a Replit workspace.' },
+    { name: 'SENTRY_CLIENT', label: 'Client', help: 'The name your support desk files this installation\'s reports under. Sent as the client tag. Empty: no client tag.' },
     { name: 'SENTRY_FEEDBACK', label: 'Report a problem button', kind: 'onoff', help: 'On: everyone signed in can send a report, with a screenshot, to this Sentry project.' },
     { name: 'SENTRY_TRACES_SAMPLE_RATE', label: 'Traces', help: 'The share of clicks, page loads and requests timed, from 0 (off) to 1 (all). Empty: 0.2.' },
   ],
@@ -60,7 +61,12 @@ export function readSentrySettings(env) {
   if (!/^\d*\.?\d+$/.test(rate || '0') || !(tracesSampleRate >= 0 && tracesSampleRate <= 1)) {
     throw new Error('SENTRY_TRACES_SAMPLE_RATE must be a number from 0 to 1, such as 0.2.');
   }
-  return { dsn, environment, feedback, tracesSampleRate };
+  const client = String(env.SENTRY_CLIENT ?? '').trim();
+  if (client.length > 60 || /[\r\n]/.test(client)) throw new Error('SENTRY_CLIENT must be one short line.');
+  // Every event says which product and, when set, which client it is from,
+  // so one support desk can serve many installations.
+  const tags = client ? { product: 'flow', client } : { product: 'flow' };
+  return { dsn, environment, feedback, tracesSampleRate, tags };
 }
 
 // No trace for the host's health check: it is not a person waiting.
@@ -92,6 +98,7 @@ export function createSentryAdapter({ sdk = SentryNode, env: hostEnv = process.e
         dsn: settings.dsn,
         environment: settings.environment,
         release: release ?? undefined,
+        initialScope: { tags: settings.tags },
         // Flow sends what it logs; no request bodies, cookies or IP addresses.
         sendDefaultPii: false,
         // A request the browser traced keeps the browser's choice, so a
@@ -132,6 +139,7 @@ export function createSentryAdapter({ sdk = SentryNode, env: hostEnv = process.e
           environment: settings.environment,
           release,
           feedback: settings.feedback,
+          tags: settings.tags,
           tracesSampleRate,
           script: tracesSampleRate > 0 ? SENTRY_BROWSER_TRACING : SENTRY_BROWSER,
         };

package/server/release-channel.js

@@ -77,7 +77,9 @@ async function get(url, { fetchImpl, retryDelayMs, as = "json" }) {
   throw new ReleaseUnavailable(lastError);
 }
 
-async function fromGitHub(channel, { slug, githubApi, fetchImpl, retryDelayMs }) {
+// The release GitHub names for the channel, alone. A publish guard asks
+// GitHub and npm separately, so the two must agree.
+export async function fromGitHub(channel, { slug, githubApi, fetchImpl, retryDelayMs }) {
   if (channel === "stable") {
     const latest = await get(`${githubApi}/repos/${slug}/releases/latest`, { fetchImpl, retryDelayMs });
     const release = parseReleaseTag(latest?.tag_name);
@@ -95,7 +97,8 @@ async function fromGitHub(channel, { slug, githubApi, fetchImpl, retryDelayMs })
   return tags.at(-1);
 }
 
-async function fromNpm(channel, { npmRegistry, packageName, fetchImpl, retryDelayMs }) {
+// The release npm's dist-tag names for the channel, alone.
+export async function fromNpm(channel, { npmRegistry, packageName, fetchImpl, retryDelayMs }) {
   const metadata = await get(`${npmRegistry}/${packageName.replaceAll("/", "%2f")}`, { fetchImpl, retryDelayMs });
   const distTag = channel === "stable" ? "latest" : "beta";
   const version = metadata?.["dist-tags"]?.[distTag];

package/server/ui/app-page.js

@@ -51,7 +51,7 @@ const BODY = `<div class="fx-app">
   <div id="toasts" class="fx-toasts" aria-live="polite"></div>
 </div>`;
 
-export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/reconcile', '/reconcile/:id', '/xero-import', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/price-list', '/custom-fields'];
+export const APP_PATHS = ['/sign-in', '/jobs', '/invoices', '/invoices/:id', '/reconcile', '/reconcile/:id', '/xero-import', '/people', '/integrations', '/integrations/:id', '/account', '/appearance', '/invoicing-settings', '/invoicing-settings/:id', '/automations', '/price-list', '/custom-fields'];
 
 export function appPage({ defaultFamily }) {
   return renderPage({