@arcforgelabs/flow 2026.10.43 → 2026.10.45

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.43",
+  "version": "2026.10.45",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.43",
+      "version": "2026.10.45",
       "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.43",
+  "version": "2026.10.45",
   "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/api/invoicing.js

@@ -1,5 +1,6 @@
 import { and, asc, desc, eq, ilike, inArray, isNull, or, sql } from 'drizzle-orm';
 import express from 'express';
+import { invoicePage, INVOICE_SORTS, normaliseInvoicesView } from '../ui/list-views.js';
 import { FlowError } from '../core/errors.js';
 import { createActionGuard } from '../integrations/call-guard.js';
 import {
@@ -165,6 +166,21 @@ function limitOf(raw, fallback, max) {
   return Math.min(n, max);
 }
 
+function offsetOf(raw) {
+  if (raw === undefined) return 0;
+  const n = Number(text(raw));
+  if (!Number.isInteger(n) || n < 0) throw invalid('offset must be a whole number from 0');
+  return n;
+}
+
+// The Filter chip's view, sent as JSON (list-views.js keeps only what it knows).
+function filterViewOf(raw) {
+  if (raw === undefined || text(raw) === '') return normaliseInvoicesView({});
+  let value;
+  try { value = JSON.parse(String(raw)); } catch { throw invalid('filter must be JSON'); }
+  return normaliseInvoicesView(value);
+}
+
 // A LIKE pattern that matches the text anywhere, with its wildcards escaped.
 const containing = (q) => `%${q.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
 
@@ -404,7 +420,20 @@ export function createInvoicingRouter({
       throw invalid(`status must be one of ${TABS.join(', ')}`);
     }
     const q = text(req.query.q);
+    // The list pages on the server, so it works with any number of invoices:
+    // the tab and the search pick rows, the Filter chip's view and the sort
+    // (job-view.js, the page's own rules) run over all of them, and one page
+    // goes back with the total.
     const limit = limitOf(req.query.limit, 200, 500);
+    const offset = offsetOf(req.query.offset);
+    const view = filterViewOf(req.query.filter);
+    const sort = text(req.query.sort) || null;
+    if (sort && !INVOICE_SORTS.includes(sort)) throw invalid(`sort must be one of ${INVOICE_SORTS.join(', ')}`);
+    const dir = text(req.query.dir) || 'asc';
+    if (!['asc', 'desc'].includes(dir)) throw invalid('dir must be asc or desc');
+    // The person's own day, for date filters such as This week.
+    const day = text(req.query.today) || new Date().toISOString().slice(0, 10);
+    if (!isRealDate(day)) throw invalid('today must be a date (yyyy-mm-dd)');
     // Each tab switch runs this, so the independent reads run side by side.
     const system = accounting();
     const sendMode = system
@@ -420,11 +449,25 @@ export function createInvoicingRouter({
       const pattern = containing(q);
       where.push(or(ilike(invoices.number, pattern), ilike(invoices.reference, pattern), ilike(contacts.name, pattern)));
     }
-    const rows = await db.select({ invoice: invoices, contactName: contacts.name }).from(invoices)
+    // First the few columns the filter and sort read, for every row; then
+    // the whole rows of the one page.
+    const light = (await db.select({
+      id: invoices.id, number: invoices.number, reference: invoices.reference, issueDate: invoices.issueDate,
+      createdAt: invoices.createdAt, totalCents: invoices.totalCents, contactName: contacts.name,
+    }).from(invoices)
       .leftJoin(contacts, eq(contacts.id, invoices.contactId))
       .where(and(...where))
-      .orderBy(desc(invoices.createdAt), desc(invoices.id))
-      .limit(limit);
+      .orderBy(desc(invoices.createdAt), desc(invoices.id)))
+      .map((row) => ({ ...row, problems: tabs.problems.get(row.id) ?? [] }));
+    const page = invoicePage(light, { view, sort, dir, offset, limit, today: day });
+    const pageIds = page.rows.map((r) => r.id);
+    const full = pageIds.length
+      ? await db.select({ invoice: invoices, contactName: contacts.name }).from(invoices)
+        .leftJoin(contacts, eq(contacts.id, invoices.contactId))
+        .where(and(eq(invoices.organisationId, organisationId), inArray(invoices.id, pageIds)))
+      : [];
+    const byId = new Map(full.map((r) => [r.invoice.id, r]));
+    const rows = pageIds.map((id) => byId.get(id)).filter(Boolean);
     const jobs = await jobsByInvoice(db, organisationId, rows.map((r) => r.invoice.id));
     const systems = work();
     res.json({
@@ -438,6 +481,13 @@ export function createInvoicingRouter({
         problems: tabs.problems.get(invoice.id) ?? [],
       })),
       counts: Object.fromEntries(TABS.map((t) => [t, tabs.ids[t].length])),
+      // The page: where it starts, its size, and every row the filter keeps.
+      offset,
+      limit,
+      total: page.total,
+      totalCents: page.totalCents,
+      // The Filter chip's Client choices: every client of the tab.
+      clients: [...new Set(light.map((r) => r.contactName).filter(Boolean))].sort((a, b) => a.localeCompare(b)),
       sendsTo: system?.name ?? null,
       sendMode: mode,
       // The Linked column: one icon for each connected system.

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, PRICE_COLUMNS, 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,13 @@ 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);
+    case 'price-list': return (view) => normaliseListView(view, PRICE_COLUMNS);
     default: return null;
   }
 }
-const VIEW_PAGE_NAMES = ['jobs'];
+const VIEW_PAGE_NAMES = ['jobs', 'invoices', 'reconcile', 'price-list'];
 
 // 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 +72,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 +167,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/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];