create-protobase 0.23.13 → 0.24.0

package/dist/templates/erp/db/migrations/016_jobs.sql

@@ -0,0 +1,99 @@
+-- The jobs schema this version of Protobase needs, written by `protobase migration`.
+-- Applied with the project's other migrations; edit or remove statements the project handles differently.
+
+create or replace function jobs.enqueue(
+  job_name text,
+  payload jsonb default null,
+  run_at timestamptz default null,
+  key text default null,
+  group_key text default null,
+  priority integer default 0
+) returns uuid
+language plpgsql as $$
+declare
+  queue jobs.queue;
+  start timestamptz := coalesce(run_at, jobs.job_now());
+  job_id uuid;
+begin
+  if key is not null and group_key is not null then
+    raise exception 'Job "%": an ordered job takes a group_key and no key', job_name;
+  end if;
+  perform jobs.create_queue(job_name, jsonb_build_object('policy', case when group_key is null then 'standard' else 'key_strict_fifo' end));
+  select * into queue from jobs.queue where name = job_name;
+  if (queue.policy = 'key_strict_fifo') <> (group_key is not null) then
+    raise exception 'Job "%" %', job_name, case when group_key is null then 'is ordered: pass its group_key' else 'is not ordered: it takes no group_key' end;
+  end if;
+  if key is not null then
+    select id into job_id from jobs.job
+    where name = job_name and singleton_key = key and state < 'active'
+    order by created_on desc limit 1;
+    if found then
+      return job_id;
+    end if;
+  end if;
+  execute format(
+    'insert into jobs.%I (name, data, priority, start_after, singleton_key, retry_limit, retry_delay, retry_backoff,
+       retry_delay_max, expire_seconds, deletion_seconds, keep_until, policy, dead_letter, heartbeat_seconds, upsert_by_key, id)
+     values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $4 + $12 * interval ''1s'', $13, $14, $15, $16, $17)
+     on conflict do nothing
+     returning id',
+    queue.table_name)
+  using job_name, payload, priority, start, coalesce(key, group_key), queue.retry_limit, queue.retry_delay,
+    queue.retry_backoff, queue.retry_delay_max, queue.expire_seconds, queue.deletion_seconds, queue.retention_seconds,
+    queue.policy, queue.dead_letter, queue.heartbeat_seconds, key is not null,
+    case when group_key is null then gen_random_uuid() else uuidv7() end
+  into job_id;
+  -- A concurrent enqueue of the same key inserted first: its job is the one waiting.
+  if job_id is null and key is not null then
+    select id into job_id from jobs.job
+    where name = job_name and singleton_key = key and state < 'active'
+    order by created_on desc limit 1;
+  end if;
+  return job_id;
+end
+$$;
+comment on function jobs.enqueue(text, jsonb, timestamptz, text, text, integer) is 'Protobase jobs 3';
+
+create or replace function jobs.next_due() returns timestamptz
+language sql stable as $$
+  select min(due) from (
+    select j.start_after as due from jobs.job j
+    where j.state < 'active' and not j.blocked
+      and not (j.policy = 'key_strict_fifo' and exists (
+        select 1 from jobs.job h where h.name = j.name and h.singleton_key = j.singleton_key and h.state = 'failed'))
+    union all
+    select started_on + expire_seconds * interval '1s' from jobs.job where state = 'active'
+  ) jobs
+$$;
+comment on function jobs.next_due() is 'Protobase jobs 3';
+
+create index if not exists job_failed_i on jobs.job (completed_on) where state = 'failed';
+drop view if exists jobs.failed;
+create view jobs.failed as
+select id, name, data as payload, retry_count + 1 as attempts,
+  coalesce(output ->> 'message', output -> 'value' ->> 'message', output ->> 'value') as error,
+  output, completed_on as failed_at, created_on as created_at, singleton_key as key, false as retry
+from jobs.job where state = 'failed';
+create or replace function jobs.failed_retry() returns trigger
+language plpgsql as $$
+begin
+  if new.retry then
+    update jobs.job
+    set state = 'retry', retry_limit = retry_limit + 1, completed_on = null,
+      start_after = greatest(start_after, jobs.job_now()), keep_until = greatest(keep_until, jobs.job_now() + interval '14 days')
+    where name = old.name and id = old.id and state = 'failed';
+  end if;
+  return new;
+end
+$$;
+comment on function jobs.failed_retry() is 'Protobase jobs 3';
+create or replace function jobs.failed_delete() returns trigger
+language plpgsql as $$
+begin
+  delete from jobs.job where name = old.name and id = old.id and state = 'failed';
+  return old;
+end
+$$;
+comment on function jobs.failed_delete() is 'Protobase jobs 3';
+create trigger failed_retry instead of update on jobs.failed for each row execute function jobs.failed_retry();
+create trigger failed_delete instead of delete on jobs.failed for each row execute function jobs.failed_delete();

package/dist/templates/erp/db/migrations/017_filter_indexes.sql

@@ -0,0 +1,5 @@
+-- A filter, sort or search reads only columns an index serves: search reads these through pg_trgm.
+create index companies_city_trgm_idx on crm.companies using gin (city gin_trgm_ops);
+create index orders_number_trgm_idx on sales.orders using gin (number gin_trgm_ops);
+create index invoices_number_trgm_idx on sales.invoices using gin (number gin_trgm_ops);
+create index locations_path_btree_idx on inventory.locations (organization_id, path);

package/dist/templates/erp/db/migrations/018_sort_indexes.sql

@@ -0,0 +1,4 @@
+-- Each sortable column is served alone too, as a list sorted by it is; the tenant is pinned, so it leads.
+create index categories_position_idx on catalog.categories (organization_id, position);
+create index invoice_lines_position_idx on sales.invoice_lines (organization_id, position);
+create index order_lines_line_no_idx on sales.order_lines (organization_id, line_no);

package/dist/templates/erp/db/migrations/019_auth_users.sql

@@ -0,0 +1,18 @@
+-- Everyone who signs in is one of the ERP's users: their Better Auth id is the next core.users id (`generateUserId` in
+-- auth/auth.ts), which records name as their owner, and their row there comes with their first membership, in that
+-- organization, whichever way they join. The roles they hold in the app live in the auth schema, so the ERP's own
+-- role column stays empty for them.
+alter table core.users alter column role drop not null;
+
+create function core.add_member_user() returns trigger language plpgsql as $$
+begin
+  insert into core.users (id, organization_id, email, name)
+  select u.id::integer, new.organization_id::integer, u.email, u.name
+  from auth."user" u
+  where u.id = new.user_id and u.id ~ '^[0-9]+$'
+  on conflict do nothing;
+  return new;
+end
+$$;
+
+create trigger member_user after insert on auth.member for each row execute function core.add_member_user();

package/dist/templates/erp/functions/unpaid-orders.ts

@@ -0,0 +1,13 @@
+import { defineFunction } from '@protobase/server'
+
+// GET /api/functions/unpaid-orders: delivered orders that are not paid yet, oldest first, as the caller may see them
+// (a sales rep, only their own).
+export default defineFunction(async (_request, { records }) => {
+  const page = await records.list('orders', {
+    filter: 'status = "delivered" AND paid = false',
+    order_by: 'created_at',
+    page_size: 20,
+    fields: ['id', 'number', 'company_id', 'total', 'created_at'],
+  })
+  return Response.json({ orders: page.items.map(({ etag, permissions, ...order }) => order) })
+})

package/dist/templates/erp/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "erp",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "db:migrate": "bun db/migrate.ts",
+    "db:seed:base": "bun seed/base.ts",
+    "db:seed": "bun seed/cli.ts",
+    "db:reset": "bun db/drop.ts && bun db/migrate.ts && bun seed/cli.ts --scale small",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "protobase": "protobase",
+    "build": "protobase build",
+    "serve": "protobase build && protobase serve dist",
+    "dev": "protobase dev"
+  },
+  "dependencies": {
+    "@protobase/cli": ">=0.24.0 <1",
+    "@protobase/layout": ">=0.24.0 <1",
+    "@protobase/schema": ">=0.24.0 <1",
+    "@protobase/server": ">=0.24.0 <1",
+    "@protobase/ui": ">=0.24.0 <1",
+    "better-auth": "^1.7.7",
+    "jose": "^6.2.12",
+    "kysely": "^0.29.6",
+    "pg": "^8.23.1",
+    "postgres": "^3.4.9",
+    "react": "^19.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/pg": "^8.23.1",
+    "@types/react": "^19.3.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.3"
+  }
+}

package/dist/templates/erp/protobase.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from '@protobase/server'
+import * as config from './config'
+import * as jobs from './config/jobs'
+import { roles } from './config/roles'
+import { auth, authenticate } from './auth/auth'
+
+export default defineConfig({
+  config,
+  auth,
+  authenticate,
+  jobs,
+  options: {
+    roles,
+    writeHooks: [
+      // In the write's own transaction: the invoice and the check of its payment commit together or not at all.
+      async (event, trx) => {
+        const check = jobs.overdueCheck(event)
+        if (check) await jobs.markInvoiceOverdue.enqueue(trx, { invoiceId: check.invoiceId }, { runAt: check.runAt, key: check.key, mode: 'replace' })
+      },
+    ],
+  },
+})

package/dist/templates/erp/protobase.ui.tsx

@@ -0,0 +1,14 @@
+import { defineUi, type ActionContext } from '@protobase/ui'
+
+// The custom components, each in a file of its own, exported by the name their layouts declare.
+export { OrdersPerDay } from './components/orders-per-day'
+
+/** "Send reminder" on an invoice: opens a mail to the customer, and marks a draft invoice as sent. */
+const send = async ({ record, recordKey, etag, client }: ActionContext) => {
+  const company = await client.get('companies', String(record!.company_id))
+  const subject = encodeURIComponent(`Invoice ${String(record!.number)}`)
+  window.location.assign(`mailto:${String(company.record.email ?? '')}?subject=${subject}`)
+  if (record!.status === 'draft') await client.update('invoices', recordKey!, { status: 'sent' }, etag ?? '*')
+}
+
+export default defineUi({ actions: { send } })

package/dist/templates/erp/seed/auth-organizations.ts

@@ -0,0 +1,11 @@
+import type { TransactionSql } from 'postgres'
+import type { Db } from '../db/connection'
+
+/**
+ * Better Auth's rows for the ERP's own organizations, under the same ids, so people work in them once they are members.
+ * The first user of a new app becomes the owner of those that have no members yet (`protobase users create`).
+ */
+export const seedAuthOrganizations = async (sql: Db | TransactionSql, organizations: { id: number; name: string; slug: string }[]) => {
+  const rows = organizations.map(({ id, name, slug }) => ({ id: String(id), name, slug, created_at: new Date() }))
+  await sql`insert into auth.organization ${sql(rows)} on conflict do nothing`
+}

package/dist/templates/erp/seed/base-organization.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest'
+import { baseOrganization } from './base-organization'
+
+describe('baseOrganization', () => {
+  it('is organization 1, named after the app, in the Netherlands and in euros', () => {
+    expect(baseOrganization('Acme Supply')).toEqual({ id: 1, name: 'Acme Supply', slug: 'acme-supply', country_code: 'NL', currency_code: 'EUR' })
+  })
+
+  it('makes a slug of any name', () => {
+    expect(baseOrganization('Müller & Söhne B.V.').slug).toBe('muller-sohne-b-v')
+    expect(baseOrganization('!!!').slug).toBe('organization')
+  })
+
+  it('refuses an empty name', () => {
+    expect(() => baseOrganization('  ')).toThrow('name')
+  })
+})

package/dist/templates/erp/seed/base-organization.ts

@@ -0,0 +1,10 @@
+// Lowercase ASCII words joined by dashes; diacritics are dropped, so Müller becomes muller.
+const slugOf = (name: string) =>
+  name.normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'organization'
+
+/** Organization 1, the one every user works in (auth/auth.ts), named after the app. */
+export const baseOrganization = (name: string) => {
+  const trimmed = name.trim()
+  if (!trimmed) throw new Error('The organization needs a name: pass --name "<the app name>"')
+  return { id: 1, name: trimmed, slug: slugOf(trimmed), country_code: 'NL', currency_code: 'EUR' }
+}

package/dist/templates/erp/seed/base.ts

@@ -0,0 +1,22 @@
+import { connect } from '../db/connection'
+import { seedAuthOrganizations } from './auth-organizations'
+import { baseOrganization } from './base-organization'
+import { countries, currencies } from './data/reference'
+
+// `db:seed:base [--name <app name>]`: what a new app starts with, the countries, the currencies and organization 1,
+// in the ERP's tables and in the auth schema's.
+// Rows already there stay as they are, so it can run again and after the sample seed (`db:seed`).
+const flag = process.argv.indexOf('--name')
+const organization = baseOrganization(flag === -1 ? 'ERP' : (process.argv[flag + 1] ?? ''))
+
+const sql = connect({ max: 1 })
+await sql.begin(async (tx) => {
+  await tx`insert into core.countries ${tx(countries.map(([code, name, euMember]) => ({ code, name, eu_member: euMember })))} on conflict do nothing`
+  await tx`insert into core.currencies ${tx(currencies.map(([code, name, symbol, decimals]) => ({ code, name, symbol, decimals })))} on conflict do nothing`
+  await tx`insert into core.organizations ${tx(organization)} on conflict do nothing`
+  // An explicit id leaves the identity sequence behind, so the next organization would take id 1 again.
+  await tx`select setval(pg_get_serial_sequence('core.organizations', 'id'), (select max(id) from core.organizations))`
+  await seedAuthOrganizations(tx, [organization])
+})
+await sql.end()
+console.log(`seeded the base data of ${organization.name}`)

package/dist/templates/erp/seed/builders/categories.ts

@@ -0,0 +1,18 @@
+import { tree } from '../data/catalogTree'
+import { slugify } from '../format'
+
+type Category = { name: string; slug: string; parent: number | null; position: number }
+type Base = { name: string; price: number; category: number; code: string }
+
+export const categories: Category[] = []
+export const bases: Base[] = []
+
+tree.forEach((root, rootPosition) => {
+  const rootIndex = categories.length
+  categories.push({ name: root.name, slug: slugify(root.name), parent: null, position: rootPosition })
+  root.children.forEach((child, childPosition) => {
+    const childIndex = categories.length
+    categories.push({ name: child.name, slug: slugify(child.name), parent: rootIndex, position: childPosition })
+    child.items.forEach(([name, price]) => bases.push({ name, price, category: childIndex, code: root.code }))
+  })
+})

package/dist/templates/erp/seed/builders/company.ts

@@ -0,0 +1,61 @@
+import { DAY, windowEnd, windowStart } from '../calendar'
+import { jobTitles, locales, qualifiers } from '../data/names'
+import { slugify } from '../format'
+import { int, pick, rngAt, weighted } from '../rng'
+import type { Org } from '../world'
+
+const legacyShare = 0.6
+
+export const legacyCompanies = (org: Org) => Math.floor(org.companyCount * legacyShare)
+
+// Companies are ordered by creation time: the first 60% predate the window.
+export const companyAt = (org: Org, ordinal: number) => {
+  const rand = rngAt(org.seed + 1, ordinal)
+  const country = weighted(rand, org.locales)
+  const locale = locales[country]
+  const city = pick(rand, locale.cities)
+  const surname = pick(rand, locale.surnames)
+  const qualifier = rand() < 0.12 ? ` ${pick(rand, qualifiers)}` : ''
+  const base = weighted(rand, [
+    [`${pick(rand, locale.stems)} ${pick(rand, locale.nouns)}`, 40],
+    [`${surname} ${pick(rand, locale.nouns)}`, 30],
+    [`${surname} ${locale.andWord}`, 15],
+    [`${city} ${pick(rand, locale.nouns)}`, 15],
+  ])
+  const domain = `${slugify(base)}.${locale.tld}`
+  const legacy = legacyCompanies(org)
+  const createdAt =
+    ordinal < legacy
+      ? Math.floor(windowStart - (1 - ordinal / legacy) * 3 * 365 * DAY)
+      : Math.floor(windowStart + ((ordinal - legacy) / (org.companyCount - legacy)) * (windowEnd - windowStart))
+  return {
+    id: org.companyFirstId + ordinal,
+    name: `${base}${qualifier} ${locale.suffix}`,
+    country,
+    city,
+    domain,
+    vatNumber: locale.vat(int(rand, 100_000_000, 999_999_999)),
+    email: `info@${domain}`,
+    phone: `${locale.dial} ${int(rand, 10, 99)} ${int(rand, 1_000_000, 9_999_999)}`,
+    status: weighted(rand, [['active', 85], ['dormant', 10], ['lead', 5]] as const),
+    createdAt,
+  }
+}
+
+export const peopleOf = (org: Org, ordinal: number) => org.personStarts[ordinal + 1]! - org.personStarts[ordinal]!
+
+export const personAt = (org: Org, company: ReturnType<typeof companyAt>, ordinal: number, slot: number) => {
+  const rand = rngAt(org.seed + 4, org.personStarts[ordinal]! + slot)
+  const locale = locales[company.country]
+  const first = pick(rand, locale.firstNames)
+  const last = pick(rand, locale.surnames)
+  return {
+    id: org.personFirstId + org.personStarts[ordinal]! + slot,
+    first,
+    last,
+    email: `${slugify(first)}.${slugify(last)}@${company.domain}`,
+    phone: rand() < 0.6 ? `${locale.dial} 6 ${int(rand, 10_000_000, 99_999_999)}` : null,
+    title: pick(rand, jobTitles),
+    createdAt: company.createdAt + int(rand, 0, 20) * 3_600_000,
+  }
+}

package/dist/templates/erp/seed/builders/invoice.ts

@@ -0,0 +1,31 @@
+import { DAY, windowEnd, within } from '../calendar'
+import { pick, rngAt } from '../rng'
+import type { Org } from '../world'
+import type { SeededOrder } from './order'
+
+const vatRates = { NL: 21, DE: 19, GB: 20 } as const
+
+// Shipped and delivered orders are invoiced; the invoice id follows the order ordinal.
+export const invoiceFor = (org: Org, ordinal: number, order: SeededOrder) => {
+  if (order.status !== 'shipped' && order.status !== 'delivered') return null
+  const rand = rngAt(org.seed + 9, ordinal)
+  const issuedAt = within(order.createdAt, (1 + Math.floor(rand() * 3)) * DAY, rand)
+  const dueAt = issuedAt + pick(rand, [14, 30, 30, 30, 60]) * DAY
+  const vatRate = vatRates[order.company.country]
+  const subtotalCents = order.totalCents
+  const vatCents = Math.round((subtotalCents * vatRate) / 100)
+  const recent = windowEnd - issuedAt < 2 * DAY
+  return {
+    id: org.orderFirstId + ordinal + 1,
+    number: `INV-${new Date(issuedAt).getUTCFullYear()}-${String(ordinal + 1).padStart(6, '0')}`,
+    status: order.paid ? 'paid' : dueAt < windowEnd ? 'overdue' : recent && rand() < 0.5 ? 'draft' : 'sent',
+    issuedAt,
+    dueAt,
+    vatRate,
+    subtotalCents,
+    vatCents,
+    totalCents: subtotalCents + vatCents,
+    createdAt: issuedAt,
+    updatedAt: within(issuedAt, Math.floor(rand() * 20 * DAY), rand),
+  }
+}

package/dist/templates/erp/seed/builders/order.ts

@@ -0,0 +1,66 @@
+import { DAY, windowEnd, windowStart, within, yearOf } from '../calendar'
+import { int, pick, rngAt, weighted } from '../rng'
+import type { Org } from '../world'
+import { companyAt, legacyCompanies, peopleOf } from './company'
+import { productName, productPriceCents } from './product'
+
+const notes = ['Deliver before 10:00', 'Call on arrival', 'Partial delivery accepted', 'Customer pickup', 'Include delivery note in box', 'Urgent, production stopped']
+
+const statusFor = (ageDays: number, rand: () => number) => {
+  if (ageDays < 2) return pick(rand, ['draft', 'confirmed', 'confirmed', 'picking'] as const)
+  if (ageDays < 10) return weighted(rand, [['confirmed', 20], ['picking', 25], ['shipped', 35], ['delivered', 20]] as const)
+  return weighted(rand, [['delivered', 88], ['shipped', 3], ['cancelled', 7], ['picking', 1], ['confirmed', 1]] as const)
+}
+
+const hex = (value: number, width: number) => value.toString(16).padStart(width, '0')
+
+const uuidv7 = (ms: number, rand: () => number) => {
+  const time = hex(ms, 12)
+  const tail = hex(int(rand, 0, 0xffffffff), 8) + hex(int(rand, 0, 0xffff), 4)
+  return `${time.slice(0, 8)}-${time.slice(8)}-7${hex(int(rand, 0, 0xfff), 3)}-${hex(0x8000 + int(rand, 0, 0x3fff), 4)}-${tail}`
+}
+
+// A whole order, rebuilt from its ordinal alone. The order, line, invoice and
+// invoice line seeds each call this, so no pass has to keep the others in memory.
+export const orderAt = (org: Org, ordinal: number) => {
+  const rand = rngAt(org.seed + 7, ordinal)
+  const createdAt = org.orderTimes[ordinal]!
+  const progress = (createdAt - windowStart) / (windowEnd - windowStart)
+  const legacy = legacyCompanies(org)
+  const available = Math.max(1, legacy + Math.floor((org.companyCount - legacy) * progress))
+  const companyOrdinal = Math.floor(rand() ** 2 * available)
+  const company = companyAt(org, companyOrdinal)
+  const people = peopleOf(org, companyOrdinal)
+  const personId = rand() < 0.85 ? org.personFirstId + org.personStarts[companyOrdinal]! + int(rand, 0, people - 1) : null
+  const status = statusFor((windowEnd - createdAt) / DAY, rand)
+  const discount = weighted(rand, [[0, 55], [5, 20], [10, 15], [15, 10]] as const)
+  const lineCount = weighted(rand, [[1, 10], [2, 15], [3, 22], [4, 20], [5, 14], [6, 10], [7, 5], [8, 4]] as const)
+  const lines = Array.from({ length: lineCount }, (_, index) => {
+    const productOrdinal = Math.floor(rand() ** 1.6 * org.productCount)
+    return {
+      lineNo: index + 1,
+      productId: org.productFirstId + productOrdinal,
+      description: productName(productOrdinal),
+      quantity: weighted(rand, [[int(rand, 1, 5), 50], [int(rand, 6, 20), 35], [int(rand, 21, 60), 15]] as const),
+      unitPriceCents: Math.round((productPriceCents(productOrdinal) * (100 - discount)) / 100),
+    }
+  })
+  const paid = status === 'delivered' ? rand() < 0.88 : status === 'shipped' ? rand() < 0.3 : false
+  return {
+    id: uuidv7(createdAt, rand),
+    number: `SO-${yearOf(createdAt)}-${String(ordinal + 1).padStart(6, '0')}`,
+    company,
+    personId,
+    ownerId: pick(rand, org.salesUsers).id,
+    status,
+    discount,
+    totalCents: lines.reduce((sum, line) => sum + line.quantity * line.unitPriceCents, 0),
+    paid,
+    notes: rand() < 0.08 ? pick(rand, notes) : null,
+    createdAt,
+    updatedAt: within(createdAt, Math.floor(rand() * (status === 'draft' ? 0.1 : 8) * DAY), rand),
+    lines,
+  }
+}
+
+export type SeededOrder = ReturnType<typeof orderAt>

package/dist/templates/erp/seed/builders/product.ts

@@ -0,0 +1,46 @@
+import { DAY, windowStart } from '../calendar'
+import { int, pick, rngAt } from '../rng'
+import type { Org } from '../world'
+import { bases } from './categories'
+
+const qualifiers = ['', 'Pro', 'Eco', 'Heavy duty', 'Food grade', 'Marine', 'Low profile', 'Extended', 'Compact', 'Industrial', 'Standard', 'Premium', 'Trade pack', 'Bulk', 'Value', 'Light', 'Reinforced', 'EU spec', 'UK spec', 'Retrofit']
+const materials = ['steel', 'stainless steel', 'zinc plated steel', 'aluminium', 'nylon', 'rubber', 'polyethylene', 'cardboard', 'brass']
+const origins = ['NL', 'DE', 'PL', 'IT', 'CN', 'TR']
+
+const variantOf = (ordinal: number) => Math.floor(ordinal / bases.length) % qualifiers.length
+
+export const productName = (ordinal: number) => {
+  const qualifier = qualifiers[variantOf(ordinal)]!
+  const round = Math.floor(ordinal / (bases.length * qualifiers.length))
+  const name = qualifier ? `${bases[ordinal % bases.length]!.name} - ${qualifier}` : bases[ordinal % bases.length]!.name
+  return round > 0 ? `${name} (series ${round + 1})` : name
+}
+
+// Rounded to 5 cents; later qualifiers cost a little more.
+export const productPriceCents = (ordinal: number) =>
+  Math.round((bases[ordinal % bases.length]!.price * (1 + variantOf(ordinal) * 0.045)) / 5) * 5
+
+export const productAt = (org: Org, ordinal: number) => {
+  const rand = rngAt(org.seed + 2, ordinal)
+  const base = bases[ordinal % bases.length]!
+  const name = productName(ordinal)
+  const createdAt = windowStart - 30 * DAY - Math.floor((1 - ordinal / org.productCount) * 3 * 365 * DAY)
+  const deleted = ordinal % 37 === 36
+  return {
+    id: org.productFirstId + ordinal,
+    categoryId: org.categoryFirstId + base.category,
+    sku: `${base.code}-${String(ordinal + 1).padStart(5, '0')}`,
+    name,
+    description: rand() < 0.4 ? null : `${name}. Stocked for industrial maintenance and assembly.`,
+    priceCents: productPriceCents(ordinal),
+    attributes: {
+      material: pick(rand, materials),
+      weight_g: int(rand, 5, 8000),
+      pack_size: pick(rand, [1, 10, 25, 50, 100, 250]),
+      origin: pick(rand, origins),
+      hazardous: rand() < 0.04,
+    },
+    deletedAt: deleted ? createdAt + int(rand, 30, 900) * DAY : null,
+    createdAt,
+  }
+}

package/dist/templates/erp/seed/calendar.ts

@@ -0,0 +1,60 @@
+import { makeRng, type Rand } from './rng'
+
+export const DAY = 86_400_000
+
+export const windowEnd = Date.UTC(2026, 9, 6, 9, 41)
+export const windowStart = windowEnd - 3 * 365 * DAY
+
+export const yearOf = (ms: number) => new Date(ms).getUTCFullYear()
+
+// Sunday first. Weekdays carry the traffic, Saturday a fifth, Sunday almost nothing.
+const dayShare = [0.05, 1.15, 1.1, 1.05, 1.0, 0.85, 0.2]
+
+const HOUR = 3_600_000
+
+// Time of day in ms: mostly business hours with a midday-ish peak, some early and evening traffic.
+const timeOfDay = (weekday: number, rand: Rand) => {
+  const roll = rand()
+  if (weekday === 0 || weekday === 6) return (9 + 6 * rand()) * HOUR
+  if (roll < 0.82) return (8 + (9 * (rand() + rand())) / 2) * HOUR
+  if (roll < 0.9) return (6 + 2 * rand()) * HOUR
+  return (17 + 5 * rand()) * HOUR
+}
+
+// A moment `delay` after `at`; when that would pass the end of the window, somewhere between `at` and the end.
+export const within = (at: number, delay: number, rand: Rand) => (at + delay <= windowEnd ? at + delay : at + Math.floor(rand() * (windowEnd - at)))
+
+// Ascending timestamps (ms) spread over the window: weekday/weekend pattern,
+// slow growth over three years, a quieter December and day-to-day noise.
+// Times never leave the window, and the first and last day are partial days.
+export const timestamps = (count: number, seed: number) => {
+  const rand = makeRng(seed)
+  const firstDay = Math.floor(windowStart / DAY) * DAY
+  const days = Math.ceil((windowEnd - firstDay) / DAY)
+  const bounds = (d: number) => [Math.max(firstDay + d * DAY, windowStart), Math.min(firstDay + (d + 1) * DAY, windowEnd)] as const
+  const weights = Array.from({ length: days }, (_, d) => {
+    const date = new Date(firstDay + d * DAY)
+    const [lo, hi] = bounds(d)
+    const season = date.getUTCMonth() === 11 ? 0.8 : 1
+    return dayShare[date.getUTCDay()]! * ((hi - lo) / DAY) * (0.7 + (0.3 * d) / days) * season * (0.85 + 0.3 * rand())
+  })
+  const total = weights.reduce((sum, weight) => sum + weight, 0)
+
+  const times = new Float64Array(count)
+  let assigned = 0
+  let cumulative = 0
+  for (let d = 0; d < days; d++) {
+    cumulative += weights[d]!
+    const dayCount = Math.round((count * cumulative) / total) - assigned
+    const [lo, hi] = bounds(d)
+    const day = firstDay + d * DAY
+    const weekday = new Date(day).getUTCDay()
+    const sampled = Array.from({ length: dayCount }, () => {
+      const at = Math.floor(day + timeOfDay(weekday, rand))
+      return at >= lo && at <= hi ? at : lo + Math.floor(rand() * (hi - lo))
+    }).sort((a, b) => a - b)
+    times.set(sampled, assigned)
+    assigned += dayCount
+  }
+  return times
+}

package/dist/templates/erp/seed/cli.ts

@@ -0,0 +1,54 @@
+import { connect } from '../db/connection'
+import { isScale, scales } from './scales'
+import { seedCatalog } from './steps/catalog'
+import { seedCrm } from './steps/crm'
+import { seedHr } from './steps/hr'
+import { seedLedger } from './steps/ledger'
+import { seedReference } from './steps/reference'
+import { seedSales } from './steps/sales'
+import { seedWarehouses } from './steps/warehouses'
+import { analyzeAll, createIndexes, dropIndexes, resetSequences, setTriggers, truncateAll } from './maintenance'
+import { buildWorld } from './world'
+
+const flag = process.argv.indexOf('--scale')
+const scale = flag === -1 ? 'small' : process.argv[flag + 1]
+if (!isScale(scale)) throw new Error(`Unknown scale "${scale}", expected one of: ${Object.keys(scales).join(', ')}`)
+
+const started = performance.now()
+const step = async (name: string, run: () => Promise<unknown>) => {
+  const before = performance.now()
+  await run()
+  console.log(`${name} (${((performance.now() - before) / 1000).toFixed(1)}s)`)
+}
+
+const world = buildWorld(scale)
+
+// One connection for the load, with the foreign keys checked: an app's own role may not skip them
+// (session_replication_role), only switch its triggers off. The generators are consistent by construction and
+// tests/examples/erp/smoke.test.ts checks the result.
+const loader = connect({ max: 1 })
+
+await step('truncate', () => truncateAll(loader))
+const indexes = await dropIndexes(loader)
+await setTriggers(loader, false)
+try {
+  await step('reference', () => seedReference(loader, world))
+  await step('crm', () => seedCrm(loader, world))
+  await step('catalog', () => seedCatalog(loader, world))
+  await step('hr', () => seedHr(loader, world))
+  await step('warehouses', () => seedWarehouses(loader, world))
+  await step('sales', () => seedSales(loader, world))
+  await step('stock moves', () => seedLedger(loader, world))
+} finally {
+  await setTriggers(loader, true)
+}
+await loader.end()
+
+const sql = connect({ max: 4 })
+await step('indexes', () => createIndexes(sql, indexes))
+await step('sequences', () => resetSequences(sql))
+await sql`insert into public.seed_info (scale) values (${scale})`
+await step('analyze', () => analyzeAll(sql))
+await sql.end()
+
+console.log(`seeded ${scale} in ${((performance.now() - started) / 1000).toFixed(1)}s`)

package/dist/templates/erp/seed/copy.ts

@@ -0,0 +1,22 @@
+import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+import type { Db } from '../db/connection'
+
+const batchSize = 2000
+
+function* batches(rows: Iterable<string>) {
+  let batch: string[] = []
+  for (const line of rows) {
+    batch.push(line)
+    if (batch.length < batchSize) continue
+    yield batch.join('')
+    batch = []
+  }
+  if (batch.length > 0) yield batch.join('')
+}
+
+// Streams COPY text-format rows into `schema.table (columns)`.
+export const copyRows = async (sql: Db, target: string, rows: Iterable<string>) => {
+  const writable = await sql.unsafe(`copy ${target} from stdin`).writable()
+  await pipeline(Readable.from(batches(rows)), writable)
+}