@arcforgelabs/flow 2026.10.37 → 2026.10.39

package/server/core/sending.js

@@ -3,19 +3,19 @@ import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
 import { billingObligations, invoiceLines, invoices } from '../db/schema.js';
 import { FlowError } from './errors.js';
 import { issueInvoice } from './invoices.js';
+import { CHANGED_REASON, diffJobLines, STATUS_BACK_REASON } from './ledger.js';
 import { soleOrganisation } from './pipeline.js';
 import { needsRead, readAccountingFirst, readBeforeAct, READS_PER_PASS } from './read-before-act.js';
 import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
 
-// Drafts, Problem, Ready and Send all ready (docs/INVOICE_SENDING.md).
+// Pending, Ready and Send all ready (docs/INVOICE_SENDING.md).
 //
 // Flow checks every draft. It checks its own data first: the draft has lines,
 // a total above zero, and a price item (or, for a line such as a rush
 // charge, an account) on every line. When an accounting
 // system is connected, its own checks are added (for Xero: the customer
 // matches one Xero contact, every item is in Xero). A draft with a problem is
-// in Problem. A person marks a draft without one ready. A saved change keeps
-// it ready; only Move to Drafts (markNotReady) takes it back.
+// Pending (the "problem" view). A draft without one is Ready.
 //
 // Send all ready issues every ready draft (each gets its number) and, when an
 // accounting system is connected, queues it to go there. The send worker
@@ -35,19 +35,35 @@ 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']);
 
-const problem = (code, message) => ({ code, message });
+// `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 } : {}) });
 
 // Flow's own checks of one draft. `lines` are its invoice lines.
 export function draftProblems(invoice, lines) {
   const problems = [];
-  if (!lines.length) problems.push(problem('no_lines', 'The invoice has no lines.'));
-  else if (invoice.totalCents <= 0) problems.push(problem('no_amount', 'The total is $0.00 or less.'));
+  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.`));
+    if (!line.priceItemId && !line.accountCode) problems.push(problem('line_no_item', `Line ${line.position} has no price item.`, `Line ${line.position}: no item`));
   }
   return problems;
 }
 
+// The few words for a job in review: what changed, for this job.
+export function reviewShort(obligation) {
+  if (obligation.holdReason === STATUS_BACK_REASON) return 'Status moved back';
+  if (obligation.holdReason !== CHANGED_REASON) return /deleted/.test(obligation.holdReason ?? '') ? 'Job deleted' : 'Job needs a look';
+  const basis = obligation.draftBasis;
+  if (!basis) return 'Job changed';
+  const changes = diffJobLines(basis.lines ?? [], obligation.lines ?? []);
+  const words = changes.map((c) => (['added', 'removed'].includes(c.change)
+    ? `Line ${c.position} ${c.change}`
+    : `Line ${c.position} ${{ item: 'item', description: 'text', quantity: 'qty', price: 'price' }[c.fields[0]] ?? 'changed'}`));
+  if ((basis.contactId ?? null) !== (obligation.contactId ?? null)) words.unshift('Client changed');
+  if (!words.length) return 'Job changed';
+  return words.length > 1 ? `${words[0]} +${words.length - 1}` : words[0];
+}
+
 // Flow's checks, and the accounting system's, for some drafts. Answers
 // Map(id -> problems) holding only the drafts that have one.
 async function checkDrafts(db, organisationId, drafts, accounting) {
@@ -63,11 +79,11 @@ async function checkDrafts(db, organisationId, drafts, accounting) {
   }
   // A draft whose job the ledger sent to review (the job changed after the
   // draft was made, or the work system deleted it) waits for a person.
-  const reviewed = await db.select({ invoiceId: billingObligations.invoiceId, reason: billingObligations.holdReason })
-    .from(billingObligations)
+  const reviewed = await db.select().from(billingObligations)
     .where(and(eq(billingObligations.organisationId, organisationId), inArray(billingObligations.invoiceId, ids), eq(billingObligations.holdState, 'review')));
-  for (const { invoiceId, reason } of reviewed) {
-    const found = problem('job_review', `The job needs a look before this invoice goes: ${reason ?? 'it was sent to review'}.`);
+  for (const obligation of reviewed) {
+    const { invoiceId, holdReason: reason } = obligation;
+    const found = problem('job_review', `The job needs a look before this invoice goes: ${reason ?? 'it was sent to review'}.`, reviewShort(obligation));
     problems.set(invoiceId, [...(problems.get(invoiceId) ?? []), found]);
   }
   if (accounting) {
@@ -80,8 +96,8 @@ async function checkDrafts(db, organisationId, drafts, accounting) {
 }
 
 // The views of the Invoices page. `accounting` is the accounting adapter, or
-// null. Every draft is in one view: Problem (a check failed), Ready (a person
-// marked it ready) or To check (the rest). An issued invoice is Sending while
+// null. Every draft is in one view: Problem (a check failed; the Pending tab)
+// or Ready (its checks pass). An issued invoice is Sending while
 // queued, and a Problem when the accounting system refused it. Answers
 // { toCheck: [ids], ready: [ids], problems: Map(id -> problems), sending: Set(ids) }.
 export async function invoiceViews(db, organisationId, { accounting = null } = {}) {
@@ -96,12 +112,14 @@ export async function invoiceViews(db, organisationId, { accounting = null } = {
     .orderBy(desc(invoices.sendUpdatedAt));
   for (const row of issued) {
     if (row.sendState === 'queued') sending.add(row.id);
-    else problems.set(row.id, [row.sendError ?? problem('send_failed', 'Sending failed.')]);
+    else problems.set(row.id, [row.sendError ?? problem('send_failed', 'Sending failed.', 'Send failed')]);
   }
+  // A draft whose checks pass is ready (Samuel, 2026-10-20): no person
+  // needs to mark it. toCheck stays for callers that still read it.
   const clean = drafts.filter((d) => !problems.has(d.id));
   return {
-    toCheck: clean.filter((d) => !d.readyAt).map((d) => d.id),
-    ready: clean.filter((d) => d.readyAt).map((d) => d.id),
+    toCheck: [],
+    ready: clean.map((d) => d.id),
     problems,
     sending,
   };
@@ -112,11 +130,11 @@ export async function invoiceView(db, organisationId, invoice, { accounting = nu
   if (invoice.status === 'void') return { view: null, problems: [] };
   if (invoice.status === 'issued') {
     if (invoice.sendState === 'queued') return { view: 'sending', problems: [] };
-    if (invoice.sendState === 'failed') return { view: 'problem', problems: [invoice.sendError ?? problem('send_failed', 'Sending failed.')] };
+    if (invoice.sendState === 'failed') return { view: 'problem', problems: [invoice.sendError ?? problem('send_failed', 'Sending failed.', 'Send failed')] };
     return { view: null, problems: [] };
   }
   const found = (await checkDrafts(db, organisationId, [invoice], accounting)).get(invoice.id) ?? [];
-  return { view: found.length ? 'problem' : invoice.readyAt ? 'ready' : 'to_check', problems: found };
+  return { view: found.length ? 'problem' : 'ready', problems: found };
 }
 
 // Mark ready: a person checked these drafts. A draft with a problem stays

package/server/db/doctor.js

@@ -12,12 +12,10 @@ import { migrationsTable } from '../integrations/schema.js';
 //   - the tables in public that neither declares (another app's, or an
 //     earlier Flow's).
 //
-// On Replit it runs on the workspace's database after each update
-// (scripts/replit-deploy.sh), and compares that database with the live app's
-// GET /health, which reports the same migration counts. Replit's publish step
-// offers to make production's tables match the workspace's, so the
-// comparison says what that step will show (docs/REPLIT.md, "The workspace
-// updater"). Anyone who runs Flow can run it: `flow-server doctor`.
+// On Replit, `flow-server doctor --live <address>` compares the workspace's
+// database with the live app's GET /health, which reports the same migration
+// counts, and says what Replit's publish step will show (docs/REPLIT.md, "The
+// workspace database"). Anyone who runs Flow can run it: `flow-server doctor`.
 
 const CORE_MIGRATIONS = fileURLToPath(new URL('./migrations', import.meta.url));
 const CORE_TABLE = '__drizzle_migrations';
@@ -114,26 +112,27 @@ export async function diagnoseDatabase(pool, { adapters = [] } = {}) {
   };
 }
 
-// What Replit's publish step will offer, from the workspace's report and the
+// What Replit's publish step will show, from the workspace's report and the
 // live app's migration counts (GET /health's schema.migrations, or null when
-// the live app could not say).
+// the live app could not say). Flow migrates production itself when it
+// starts, so the answer to "Development database changes detected" is always
+// Cancel (docs/REPLIT.md, "The workspace database").
 //
-//   broken  the workspace database is not at this build: do not publish
-//   behind  production has migrations the workspace lacks: the list would
-//           drop them, so Cancel and update the workspace first
-//   adds    the workspace is ahead: the list holds additions only; approve
 //   same    the two match: no list
-//   unknown the live app did not say: approve additions, Cancel a DROP
+//   behind  production has migrations the workspace lacks: follow production
+//   ahead   the workspace has migrations production does not run
+//   unknown the live app did not say
+export const CANCEL_RULE = 'If Replit shows "Development database changes detected", press Cancel.';
+
 export function publishVerdict(report, live) {
-  if (!report.ok) return { verdict: 'broken', say: 'The workspace database is not at this build. Do not publish. Update the workspace again.' };
-  if (!live) return { verdict: 'unknown', say: 'The live app did not report its migrations. Publish: approve a list of additions; Cancel any DROP.' };
+  if (!live) return { verdict: 'unknown', say: `The live app did not report its migrations. ${CANCEL_RULE}` };
   const behind = Object.entries(live).filter(([id, n]) => n > (report.migrations[id] ?? 0)).map(([id]) => id);
-  if (behind.length) {
-    return { verdict: 'behind', say: `Production has ${behind.join(', ')} migrations the workspace lacks. Do not publish: Replit would offer to DROP them. Update the workspace first.` };
-  }
   const ahead = Object.entries(report.migrations).filter(([id, n]) => n > (live[id] ?? 0)).map(([id]) => id);
   if (ahead.length) {
-    return { verdict: 'adds', say: `The workspace is ahead of production (${ahead.join(', ')}). Publish: Replit offers to add tables or columns only. Approve.` };
+    return { verdict: 'ahead', say: `The workspace has ${ahead.join(', ')} migrations production does not run. ${CANCEL_RULE} Production applies its own migrations when it starts.` };
+  }
+  if (behind.length) {
+    return { verdict: 'behind', say: `Production has ${behind.join(', ')} migrations the workspace lacks. Run npm run db:follow-production (or press Run). ${CANCEL_RULE}` };
   }
   return { verdict: 'same', say: 'The workspace and production are at the same migrations. Publish: Replit shows no database changes.' };
 }

package/server/db/index.js

@@ -6,6 +6,13 @@ import * as schema from './schema.js';
 
 const migrationsFolder = fileURLToPath(new URL('./migrations', import.meta.url));
 
+// Session advisory lock held while any migration runs (Flow's own, each
+// integration's, and the Replit workspace sync), so two processes sharing one
+// database never apply the same migration at once. Field uses the same
+// pattern with its own key.
+export const MIGRATION_LOCK_KEY = 7_139_000_101n;
+const DEFAULT_MIGRATION_LOCK_TIMEOUT_MS = 300_000;
+
 // Opens Flow's PostgreSQL database. The caller owns the pool: call close().
 export function openDatabase({ url = process.env.DATABASE_URL, max = 10 } = {}) {
   if (!url) throw new Error('flow: DATABASE_URL is not set');
@@ -14,8 +21,72 @@ export function openDatabase({ url = process.env.DATABASE_URL, max = 10 } = {})
   return { db, pool, close: () => pool.end() };
 }
 
-export function migrateDatabase(db) {
-  return migrate(db, { migrationsFolder });
+// A transaction-mode pooler (PgBouncer, Neon's "-pooler" hosts) does not keep
+// a session, so it cannot hold a session lock. Neon names a pooled endpoint
+// by adding "-pooler" to the endpoint id; the same host without it is the
+// direct endpoint, which migrations use instead (as Field does).
+const POOLER_HOST = /-pooler(?=\.|$)/i;
+
+export function directUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  if (!POOLER_HOST.test(parsed.hostname)) return null;
+  parsed.hostname = parsed.hostname.replace(POOLER_HOST, '');
+  return parsed.toString();
+}
+
+function migrationLockTimeoutMs(env = process.env) {
+  const value = Number.parseInt(env.FLOW_DB_MIGRATION_LOCK_TIMEOUT_MS || '', 10);
+  return Number.isInteger(value) && value >= 0 ? value : DEFAULT_MIGRATION_LOCK_TIMEOUT_MS;
+}
+
+// Runs fn(lockedDb) under MIGRATION_LOCK_KEY. The lock and fn share one
+// connection taken from db's pool (or the pooler's direct endpoint), because
+// a session lock belongs to one connection. It waits up to
+// FLOW_DB_MIGRATION_LOCK_TIMEOUT_MS (300000) for another process to finish.
+export async function withMigrationLock(db, fn, { timeoutMs = migrationLockTimeoutMs() } = {}) {
+  const source = db?.$client;
+  if (!source) throw new Error('flow: a migration needs a PostgreSQL database from openDatabase');
+  const direct = source instanceof pg.Pool ? directUrl(source.options?.connectionString) : null;
+  let client;
+  if (direct) {
+    client = new pg.Client({ connectionString: direct });
+    await client.connect();
+  } else {
+    client = source instanceof pg.Pool ? await source.connect() : source;
+  }
+  let broken = false;
+  try {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const { rows } = await client.query('select pg_try_advisory_lock($1::bigint) as locked', [MIGRATION_LOCK_KEY.toString()]);
+      if (rows[0].locked) break;
+      if (Date.now() >= deadline) {
+        throw new Error(`flow: another process held the migration lock (advisory lock ${MIGRATION_LOCK_KEY}) for over ${timeoutMs} ms; is a migration hung? (FLOW_DB_MIGRATION_LOCK_TIMEOUT_MS)`);
+      }
+      await new Promise((wake) => setTimeout(wake, 250));
+    }
+    try {
+      return await fn(drizzle(client, { schema }));
+    } finally {
+      // A connection that cannot unlock is closed, which also frees the lock.
+      await client.query('select pg_advisory_unlock($1::bigint)', [MIGRATION_LOCK_KEY.toString()]).catch(() => { broken = true; });
+    }
+  } finally {
+    if (direct) await client.end().catch(() => {});
+    else if (client !== source) client.release(broken);
+  }
+}
+
+// Applies the migrations in `folder` (this build's own by default) under the
+// migration lock. `table` names the journal: drizzle.__drizzle_migrations for
+// Flow's own, one per integration (server/integrations/schema.js).
+export function migrateDatabase(db, { folder = migrationsFolder, table } = {}) {
+  return withMigrationLock(db, (locked) => migrate(locked, { migrationsFolder: folder, ...(table ? { migrationsTable: table } : {}) }));
 }
 
-export { schema };
+export { migrationsFolder, schema };

package/server/db/migrate-all.js

@@ -3,10 +3,9 @@ import { adapters as shipped } from '../integrations/adapters.js';
 import { migrateAdapterSchema } from '../integrations/schema.js';
 
 // Brings a database up to this build: the core migrations, then the tables
-// of every adapter this build ships, whether or not it is on. On Replit the
-// workspace's database runs this before a publish (scripts/replit-deploy.sh
-// update-workspace), so it holds every table production can hold and
-// publishing never offers to drop one (docs/REPLIT.md).
+// of every adapter this build ships, whether or not it is on
+// (`flow-server migrate`). Not for a Replit workspace: its database follows
+// production instead (scripts/replit-workspace-db.js, docs/REPLIT.md).
 export async function migrateEverything(db, { adapters = shipped, log = () => {} } = {}) {
   await migrateDatabase(db);
   for (const adapter of adapters) {

package/server/db/migrations/0020_custom_field_colours.sql

@@ -0,0 +1,21 @@
+CREATE TABLE IF NOT EXISTS "job_field_settings" (
+	"organisation_id" uuid PRIMARY KEY NOT NULL,
+	"group_colors" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"assignee_made_at" timestamp with time zone,
+	"updated_by" uuid,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "job_fields" ADD COLUMN IF NOT EXISTS "color" text;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "job_field_settings" ADD CONSTRAINT "job_field_settings_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "job_field_settings" ADD CONSTRAINT "job_field_settings_updated_by_people_id_fk" FOREIGN KEY ("updated_by") REFERENCES "public"."people"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "job_fields" ADD CONSTRAINT "job_fields_color_valid" CHECK ("job_fields"."color" is null or "job_fields"."color" in ('gray', 'blue', 'teal', 'green', 'amber', 'red', 'purple', 'pink'));
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;