@arcforgelabs/flow 2026.10.29 → 2026.10.32-beta.1

package/server/core/sending.js

@@ -4,7 +4,7 @@ import { invoiceLines, invoices } from '../db/schema.js';
 import { FlowError } from './errors.js';
 import { issueInvoice } from './invoices.js';
 import { soleOrganisation } from './pipeline.js';
-import { enqueueJob, runNextJob } from './queue.js';
+import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
 
 // Drafts, Problem, Ready and Send all ready (docs/INVOICE_SENDING.md).
 //
@@ -124,9 +124,10 @@ export async function markReady(db, organisationId, invoiceIds, { personId, acco
   return { marked: good.length, refused: [...problems].map(([invoiceId, found]) => ({ invoiceId, problems: found })) };
 }
 
-// Back to drafts: the drafts need another look before they go.
+// Back to drafts: the drafts need another look before they go. The new
+// updatedAt keeps "Ready when drafted" (automations.js) off them.
 export async function markNotReady(db, organisationId, invoiceIds) {
-  const rows = await db.update(invoices).set({ readyAt: null, readyBy: null })
+  const rows = await db.update(invoices).set({ readyAt: null, readyBy: null, updatedAt: sql`now()` })
     .where(and(eq(invoices.organisationId, organisationId), eq(invoices.status, 'draft'), inArray(invoices.id, invoiceIds)))
     .returning({ id: invoices.id });
   return { moved: rows.length };
@@ -215,6 +216,7 @@ export async function sendQueued(db, organisationId, { accounting, limit = WORKE
         const error = result.error ?? { code: `send_${result.outcome}`, message: `Sending ended as ${result.outcome}.` };
         await settle(db, organisationId, result.invoiceId, { sendState: 'failed', sendError: { code: error.code, message: error.message } });
         summary.failed += 1;
+        summary.refused = [...new Set([...(summary.refused ?? []), error.code])];
       }
     }
   }
@@ -230,6 +232,7 @@ function settle(db, organisationId, invoiceId, fields) {
 // the job queue.
 export function createSendWorker({ db, integrations, log = console, timers = { setTimeout, clearTimeout }, everyMs = WORKER_EVERY_MS }) {
   const workerId = `send-${randomUUID()}`;
+  const startedAtMs = Date.now();
   let timer = null;
   let running = null;
   let stopped = true;
@@ -252,13 +255,22 @@ export function createSendWorker({ db, integrations, log = console, timers = { s
         const [waiting] = await db.select({ id: invoices.id }).from(invoices)
           .where(and(eq(invoices.organisationId, organisationId), eq(invoices.sendState, 'queued'))).limit(1);
         if (!waiting) return;
+        // Issue #101: a send run that gave up waits for a person, a restart or
+        // the next day; the timer never starts it again by itself.
+        if (await deadSince(db, organisationId, { kind: SEND_KIND, dedupeKey: 'all', since: deadHoldSince(startedAtMs) })) return;
         await enqueueJob(db, organisationId, { kind: SEND_KIND, dedupeKey: 'all' });
         const ran = await runNextJob(db, {
           workerId,
           leaseMs: LEASE_MS,
           handlers: { [SEND_KIND]: () => sendQueued(db, organisationId, { accounting }) },
         });
-        if (ran) log.info?.(`[sending] ${ran.outcome}: ${JSON.stringify(ran.job.result ?? ran.job.lastError ?? {})}`);
+        if (!ran) return;
+        const line = `[sending] ${ran.outcome}: ${JSON.stringify(ran.job.result ?? ran.job.lastError ?? {})}`;
+        // An invoice the accounting system refused waits in Problem for a
+        // person; it is reported once, when it is refused.
+        if (ran.outcome === 'dead') log.error?.('[sending] the send run gave up after its last attempt');
+        if (ran.job.result?.failed) log.error?.('[sending] the accounting system refused an invoice');
+        (ran.outcome === 'succeeded' && !ran.job.result?.failed ? log.info : log.warn)?.(line);
       } catch (error) {
         log.error?.(`[sending] ${error?.code ?? 'error'}: ${error?.message ?? error}`);
       }

package/server/db/commands.js

@@ -0,0 +1,42 @@
+import { adapters } from '../integrations/adapters.js';
+import { diagnoseDatabase, formatReport, liveMigrationCounts, publishVerdict } from './doctor.js';
+import { openDatabase } from './index.js';
+import { migrateEverything } from './migrate-all.js';
+
+// `flow-server migrate` and `flow-server doctor` (server/flow-server.js).
+// Each returns the exit code.
+export async function runCommand(command, args, { log = console } = {}) {
+  const option = (name) => {
+    const at = args.indexOf(name);
+    return at === -1 ? undefined : args[at + 1];
+  };
+  let handle;
+  try {
+    handle = openDatabase({ max: 1 });
+  } catch (error) {
+    log.error(`[doctor] ${error.message}`);
+    return 2;
+  }
+  try {
+    if (command === 'migrate') {
+      await migrateEverything(handle.db, { log: (line) => log.log(`[migrate] ${line}`) });
+      log.log('[migrate] the database is at this build');
+      return 0;
+    }
+    const report = await diagnoseDatabase(handle.pool, { adapters });
+    const origin = option('--live');
+    const live = origin ? await liveMigrationCounts(origin) : undefined;
+    const verdict = origin ? publishVerdict(report, live) : null;
+    if (args.includes('--json')) {
+      log.log(JSON.stringify({ ...report, live: live ?? null, verdict }, null, 2));
+    } else {
+      for (const line of formatReport(report, verdict)) log.log(`[doctor] ${line}`);
+    }
+    return report.ok ? 0 : 1;
+  } catch (error) {
+    log.error(`[doctor] ${error.message}`);
+    return 2;
+  } finally {
+    await handle.close();
+  }
+}

package/server/db/doctor.js

@@ -0,0 +1,168 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { migrationsTable } from '../integrations/schema.js';
+
+// Flow's doctor: checks a database against this build. It reads, and never
+// changes anything.
+//
+//   - each migration journal (Flow's own, and each shipped adapter's): how
+//     many of this build's migrations the database has applied;
+//   - every table and column this build's latest core snapshot declares, and
+//     every table each adapter declares: which are missing;
+//   - 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`.
+
+const CORE_MIGRATIONS = fileURLToPath(new URL('./migrations', import.meta.url));
+const CORE_TABLE = '__drizzle_migrations';
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+// What this build expects: one journal per migrations folder, and the tables
+// (with their columns, where a snapshot names them) those migrations create.
+export function expectedSchema({ adapters = [] } = {}) {
+  const journals = [{ id: 'core', table: CORE_TABLE, folder: CORE_MIGRATIONS }];
+  for (const adapter of adapters) {
+    if (!adapter.schema) continue;
+    journals.push({ id: adapter.id, table: migrationsTable(adapter), folder: adapter.schema.migrationsFolder, tables: adapter.schema.tables });
+  }
+  const tables = new Map();
+  for (const journal of journals) {
+    const { entries } = readJson(`${journal.folder}/meta/_journal.json`);
+    journal.tags = entries.map((entry) => entry.tag);
+    const last = entries.at(-1);
+    let snapshot = null;
+    try {
+      snapshot = last ? readJson(`${journal.folder}/meta/${String(last.idx).padStart(4, '0')}_snapshot.json`) : null;
+    } catch {
+      snapshot = null; // An adapter may ship its migrations without snapshots.
+    }
+    for (const table of Object.values(snapshot?.tables ?? {})) {
+      if ((table.schema || 'public') !== 'public') continue;
+      tables.set(table.name, new Set(Object.keys(table.columns)));
+    }
+    for (const name of journal.tables ?? []) {
+      if (!tables.has(name)) tables.set(name, null);
+    }
+  }
+  return { journals, tables };
+}
+
+// How many migrations each journal has applied: { core: 14, xero: 6, ... }.
+// A journal whose table does not exist (an adapter never turned on) counts 0.
+export async function appliedMigrationCounts(pool, journals) {
+  const { rows } = await pool.query(
+    "select table_name from information_schema.tables where table_schema = 'drizzle'",
+  );
+  const present = new Set(rows.map((row) => row.table_name));
+  const counts = {};
+  for (const journal of journals) {
+    if (!present.has(journal.table)) {
+      counts[journal.id] = 0;
+      continue;
+    }
+    // The name was read from the catalogue above, so quoting it is enough.
+    const result = await pool.query(`select count(*)::int as n from drizzle."${journal.table.replaceAll('"', '""')}"`);
+    counts[journal.id] = result.rows[0].n;
+  }
+  return counts;
+}
+
+export async function diagnoseDatabase(pool, { adapters = [] } = {}) {
+  const expected = expectedSchema({ adapters });
+  const applied = await appliedMigrationCounts(pool, expected.journals);
+  const pending = expected.journals
+    .filter((journal) => applied[journal.id] < journal.tags.length)
+    .map((journal) => ({ journal: journal.id, applied: applied[journal.id], shipped: journal.tags.length, next: journal.tags.slice(applied[journal.id]) }));
+
+  const { rows } = await pool.query(
+    "select table_name, column_name from information_schema.columns where table_schema = 'public'",
+  );
+  const actual = new Map();
+  for (const row of rows) {
+    if (!actual.has(row.table_name)) actual.set(row.table_name, new Set());
+    actual.get(row.table_name).add(row.column_name);
+  }
+  const missingTables = [];
+  const missingColumns = [];
+  for (const [table, columns] of expected.tables) {
+    const have = actual.get(table);
+    if (!have) {
+      missingTables.push(table);
+      continue;
+    }
+    for (const column of columns ?? []) {
+      if (!have.has(column)) missingColumns.push(`${table}.${column}`);
+    }
+  }
+  const unknownTables = [...actual.keys()].filter((table) => !expected.tables.has(table)).sort();
+  return {
+    ok: pending.length === 0 && missingTables.length === 0 && missingColumns.length === 0,
+    migrations: applied,
+    pending,
+    missingTables: missingTables.sort(),
+    missingColumns: missingColumns.sort(),
+    unknownTables,
+  };
+}
+
+// What Replit's publish step will offer, 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).
+//
+//   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
+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.' };
+  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: 'same', say: 'The workspace and production are at the same migrations. Publish: Replit shows no database changes.' };
+}
+
+// The live app's migration counts from its GET /health, or null.
+export async function liveMigrationCounts(origin, { fetchImpl = fetch, timeoutMs = 8000 } = {}) {
+  try {
+    const url = new URL('/health', origin);
+    const res = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok && res.status !== 503) return null;
+    const body = await res.json();
+    const counts = body?.schema?.migrations;
+    return counts && typeof counts === 'object' ? counts : null;
+  } catch {
+    return null;
+  }
+}
+
+export function formatReport(report, verdict = null) {
+  const lines = [];
+  for (const [id, n] of Object.entries(report.migrations)) {
+    const pending = report.pending.find((p) => p.journal === id);
+    lines.push(`${id} migrations: ${n} applied${pending ? `, ${pending.next.length} pending (${pending.next.join(', ')})` : ''}`);
+  }
+  lines.push(report.missingTables.length ? `missing tables: ${report.missingTables.join(', ')}` : 'tables: all present');
+  lines.push(report.missingColumns.length ? `missing columns: ${report.missingColumns.join(', ')}` : 'columns: all present');
+  if (report.unknownTables.length) {
+    lines.push(`tables this build does not know: ${report.unknownTables.join(', ')}. On Replit, publishing offers to copy them to production.`);
+  }
+  if (verdict) lines.push(`verdict: ${verdict.verdict}. ${verdict.say}`);
+  return lines;
+}

package/server/db/migrations/0014_price_list.sql

@@ -0,0 +1,34 @@
+CREATE TABLE IF NOT EXISTS "price_item_links" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"price_item_id" uuid NOT NULL,
+	"system" text NOT NULL,
+	"external_id" text NOT NULL,
+	"external_code" text,
+	"matched_by" text NOT NULL,
+	"created_by" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "price_item_links_matched_by_valid" CHECK ("price_item_links"."matched_by" in ('code', 'person')),
+	CONSTRAINT "price_item_links_system_valid" CHECK ("price_item_links"."system" ~ '^[a-z][a-z0-9-]{1,31}$')
+);
+--> statement-breakpoint
+ALTER TABLE "price_items" ADD COLUMN IF NOT EXISTS "account_code" text;--> statement-breakpoint
+ALTER TABLE "price_items" ADD COLUMN IF NOT EXISTS "updated_by" uuid;--> statement-breakpoint
+ALTER TABLE "price_items" ADD COLUMN IF NOT EXISTS "updated_at" timestamp with time zone DEFAULT now() NOT NULL;--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "price_item_links" ADD CONSTRAINT "price_item_links_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 "price_item_links" ADD CONSTRAINT "price_item_links_created_by_people_id_fk" FOREIGN KEY ("created_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 "price_item_links" ADD CONSTRAINT "price_item_links_item_same_org" FOREIGN KEY ("organisation_id","price_item_id") REFERENCES "public"."price_items"("organisation_id","id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "price_item_links_external" ON "price_item_links" USING btree ("organisation_id","system","external_id");--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "price_items" ADD CONSTRAINT "price_items_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$;

package/server/db/migrations/0015_alert_dismissals.sql

@@ -0,0 +1,17 @@
+CREATE TABLE IF NOT EXISTS "alert_dismissals" (
+	"organisation_id" uuid NOT NULL,
+	"person_id" uuid NOT NULL,
+	"alert_key" text NOT NULL,
+	"members" text[] DEFAULT '{}'::text[] NOT NULL,
+	"dismissed_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "alert_dismissals_organisation_id_person_id_alert_key_pk" PRIMARY KEY("organisation_id","person_id","alert_key")
+);
+--> statement-breakpoint
+DO $flow_guard$ BEGIN
+	ALTER TABLE "alert_dismissals" ADD CONSTRAINT "alert_dismissals_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 "alert_dismissals" ADD CONSTRAINT "alert_dismissals_person_id_people_id_fk" FOREIGN KEY ("person_id") REFERENCES "public"."people"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION WHEN duplicate_object OR duplicate_table OR invalid_table_definition THEN NULL;
+END $flow_guard$;