pgkiln 0.46.0 → 0.48.0

package/src/builder/workspaces.ts

@@ -28,12 +28,13 @@ export const DEFAULT_WORKSPACE = 1;
 /** The workspaces a developer may use (administrators: all), and the current one, on the session object. */
 export async function loadWorkspaces(s: Session) {
   const rows = (
-    await owner.query<WorkspaceRef>(
+    await owner.query<WorkspaceRef & { instance_admin?: boolean }>(
       `select w.id, w.name, w.message, w.banner_label, w.banner_color, w.isolated, w.sql_workshop, w.rest_services,
               coalesce((select json_agg(json_build_object('label', l.label, 'url', l.url, 'description', l.description) order by l.position, lower(l.label))
                           from meta.workspace_link l where l.workspace_id = w.id), '[]') as links,
               exists (select 1 from meta.developer d where d.username = $1 and d.is_admin)
-                or exists (select 1 from meta.workspace_member m where m.workspace_id = w.id and m.username = $1 and m.is_admin) as admin
+                or exists (select 1 from meta.workspace_member m where m.workspace_id = w.id and m.username = $1 and m.is_admin) as admin,
+              exists (select 1 from meta.developer d where d.username = $1 and d.is_admin) as instance_admin
          from meta.workspace w
         where exists (select 1 from meta.developer d where d.username = $1 and d.is_admin)
            or exists (select 1 from meta.workspace_member m where m.workspace_id = w.id and m.username = $1)
@@ -42,6 +43,7 @@ export async function loadWorkspaces(s: Session) {
     )
   ).rows;
   s.workspaces = rows;
+  s.instanceAdmin = !!rows[0]?.instance_admin;
   const wanted = Number(s.state.__WS);
   s.workspace = rows.find((w) => w.id === wanted) ?? rows[0] ?? null;
 }
@@ -213,7 +215,7 @@ function preferencesRegion(s: Session, w: { id: number; sql_workshop: boolean; r
   const check = (name: string, on: boolean, label: string, help: string) =>
     html`<div class="field"><label class="check"><input type="checkbox" name="${name}" value="true"${on ? raw(' checked') : ''}> ${label}</label><small class="help">${help}</small></div>`;
   return region('Workspace preferences', html`<form method="post" action="${BASE}/workspaces/${w.id}/preferences">${csrf(s)}
-      ${check('sql_workshop', w.sql_workshop, 'Enable the SQL Workshop', 'Off: SQL Commands, the Object Browser, SQL scripts, data loading and unloading, Quick SQL, the query builder, DDL, Compare and AI are refused while this workspace is current, for every developer.')}
+      ${check('sql_workshop', w.sql_workshop, 'Enable the SQL Workshop', 'Off: the SQL Worksheet, the Object Browser, SQL scripts, data loading and unloading, Quick SQL, the query builder, DDL, Compare and AI are refused while this workspace is current, for every developer.')}
       ${check('rest_services', w.rest_services, 'Enable RESTful services', 'Off: the REST modules of this workspace\'s applications answer 404 (Not found) at /a/<alias>/rest/…; they can still be edited.')}
       <div class="buttons"><button class="btn">Save preferences</button></div></form>`, '', 'preferences');
 }

package/src/cli/replace.ts

@@ -72,7 +72,9 @@ export const KEPT = ['app_access', 'api_client', 'session', 'sso_pending', 'save
   // (081) the mail service an application sends through, and its queued and sent mail
   'app_mail_service', 'mail_queue',
   // (086) users' preferences
-  'user_preference'];
+  'user_preference',
+  // (113) AutoREST: the tables and views the application publishes (SQL Workshop › RESTful Services)
+  'rest_object'];
 /** Children of pages (replaced with their page). */
 const PAGE_CHILDREN = ['region', 'item', 'button', 'dynamic_action', 'validation', 'process', 'computation', 'branch'];
 /** References into replaced tables from kept data, repointed below: "table.column". */

package/src/datamodel.ts

@@ -0,0 +1,324 @@
+import { html, raw, type Raw } from './html.ts';
+
+// (sprint 98, Database Actions DA-10: Data Modeler) A relational diagram of some tables and views of one schema:
+// the catalog read for them (columns, keys, foreign keys, comments), each box's size, an automatic layout, the
+// foreign key lines with crow's feet, and the whole diagram as one SVG. The same SVG is the page's diagram (the
+// boxes at their saved positions, so it shows without JavaScript), the Export SVG file and the source of the
+// PNG export. It uses SVG presentation attributes only (no style attributes, no <style>): the strict CSP allows
+// them, the builder's stylesheet themes them on the page, and a downloaded file looks the same anywhere.
+// public/data-modeler.js moves the boxes and draws the lines again with the same geometry (fkPath).
+
+export interface ModelColumn {
+  name: string;
+  type: string;
+  notNull: boolean;
+  default: string | null;
+  comment: string | null;
+}
+export interface ModelConstraint {
+  name: string;
+  /** p primary key, u unique, f foreign key, c check */
+  type: 'p' | 'u' | 'f' | 'c';
+  cols: string[];
+  refSchema: string | null;
+  refTable: string | null;
+  refCols: string[];
+  def: string;
+}
+export interface ModelTable {
+  name: string;
+  kind: 'table' | 'view' | 'materialized view';
+  /** the regclass text (schema-qualified, quoted when needed) */
+  ref: string;
+  comment: string | null;
+  columns: ModelColumn[];
+  constraints: ModelConstraint[];
+}
+export interface Placed {
+  name: string;
+  x: number;
+  y: number;
+}
+
+type Q = { query: <T extends Record<string, any> = any>(sql: string, params?: unknown[]) => Promise<{ rows: T[] }> };
+
+/** Names of the tables and views of a schema (not partitions), for the Add objects search. */
+export async function modelNames(db: Q, schema: string): Promise<{ name: string; kind: ModelTable['kind'] }[]> {
+  return (await db.query<{ name: string; kind: ModelTable['kind'] }>(
+    `select c.relname as name, case when c.relkind in ('r', 'p') then 'table' when c.relkind = 'm' then 'materialized view' else 'view' end as kind
+       from pg_class c join pg_namespace n on n.oid = c.relnamespace
+      where n.nspname = $1 and c.relkind in ('r', 'p', 'v', 'm') and not c.relispartition
+      order by c.relname limit 5000`, [schema])).rows;
+}
+
+/** The named tables and views of a schema as the diagram shows them (missing names are left out). */
+export async function readModel(db: Q, schema: string, names: string[]): Promise<ModelTable[]> {
+  if (!names.length) return [];
+  return (await db.query<ModelTable>(
+    `select c.relname as name, case when c.relkind in ('r', 'p') then 'table' when c.relkind = 'm' then 'materialized view' else 'view' end as kind,
+            c.oid::regclass::text as ref, obj_description(c.oid, 'pg_class') as comment,
+            coalesce((select json_agg(json_build_object('name', a.attname, 'type', format_type(a.atttypid, a.atttypmod), 'notNull', a.attnotnull,
+                        'default', case when a.attidentity = 'a' then 'generated always as identity' when a.attidentity = 'd' then 'generated by default as identity'
+                                        when a.attgenerated = 's' then 'generated always as (' || pg_get_expr(d.adbin, d.adrelid) || ') stored'
+                                        else pg_get_expr(d.adbin, d.adrelid) end,
+                        'comment', col_description(c.oid, a.attnum)) order by a.attnum)
+                        from pg_attribute a left join pg_attrdef d on d.adrelid = a.attrelid and d.adnum = a.attnum
+                       where a.attrelid = c.oid and a.attnum > 0 and not a.attisdropped), '[]') as columns,
+            coalesce((select json_agg(json_build_object('name', k.conname, 'type', k.contype,
+                        'cols', array(select a.attname from unnest(k.conkey) with ordinality u(n, i) join pg_attribute a on a.attrelid = k.conrelid and a.attnum = u.n order by u.i),
+                        'refSchema', fn.nspname, 'refTable', f.relname,
+                        'refCols', coalesce(array(select a.attname from unnest(k.confkey) with ordinality u(n, i) join pg_attribute a on a.attrelid = k.confrelid and a.attnum = u.n order by u.i), '{}'),
+                        'def', pg_get_constraintdef(k.oid)) order by position(k.contype in 'pufc'), k.conname)
+                        from pg_constraint k left join pg_class f on f.oid = k.confrelid left join pg_namespace fn on fn.oid = f.relnamespace
+                       where k.conrelid = c.oid and k.contype in ('p', 'u', 'f', 'c')), '[]') as constraints
+       from pg_class c join pg_namespace n on n.oid = c.relnamespace
+      where n.nspname = $1 and c.relname = any ($2::text[]) and c.relkind in ('r', 'p', 'v', 'm') and not c.relispartition
+      order by c.relname`, [schema, names])).rows;
+}
+
+/**
+ * The names a search picks: `*` all of them; a pattern with `*` (emp*, *_log) matches whole names; other words match
+ * a part of a name (any case). Several words or patterns, separated by spaces or commas, add up.
+ */
+export function matchNames(all: string[], q: string, opts: { exact?: boolean } = {}): string[] {
+  const terms = q.split(/[\s,]+/).map((t) => t.trim()).filter(Boolean).slice(0, 50);
+  if (!terms.length) return [];
+  const tests = terms.map((t) => {
+    if (t.includes('*')) {
+      const re = new RegExp(`^${t.split('*').map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`, 'i');
+      return (n: string) => re.test(n);
+    }
+    const low = t.toLowerCase();
+    return opts.exact ? (n: string) => n === t || n.toLowerCase() === low : (n: string) => n.toLowerCase().includes(low);
+  });
+  return all.filter((n) => tests.some((f) => f(n)));
+}
+
+/** A diagram's saved objects, cleaned: names (unique) and positions within 0..20000. */
+export function cleanObjects(v: unknown): Placed[] {
+  if (!Array.isArray(v)) return [];
+  const seen = new Set<string>();
+  const out: Placed[] = [];
+  for (const o of v.slice(0, 500)) {
+    if (!o || typeof o !== 'object') continue;
+    const name = (o as any).name;
+    if (typeof name !== 'string' || !name || name.length > 63 || seen.has(name)) continue;
+    seen.add(name);
+    const n = (x: unknown) => (Number.isFinite(Number(x)) ? Math.min(20000, Math.max(0, Math.round(Number(x)))) : 0);
+    out.push({ name, x: n((o as any).x), y: n((o as any).y) });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- geometry
+
+export const HEAD = 30;
+export const ROW = 20;
+const FOOT = 8;
+/** columns drawn per box; the others are counted in a last row */
+export const MAX_ROWS = 40;
+const CHAR = 7;
+const TYPE_CHAR = 6.4;
+const cut = (s: string, n: number) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+
+export interface Box {
+  name: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** The rows a box shows: its columns (at most MAX_ROWS) and a "more" row. */
+const shownColumns = (t: ModelTable) => t.columns.slice(0, t.columns.length > MAX_ROWS ? MAX_ROWS - 1 : MAX_ROWS);
+
+export function boxSize(t: ModelTable): { w: number; h: number } {
+  const cols = shownColumns(t);
+  const rows = cols.length + (cols.length < t.columns.length ? 1 : 0);
+  const widest = Math.max(0, ...cols.map((c) => 30 + cut(c.name, 36).length * CHAR + 18 + cut(c.type, 24).length * TYPE_CHAR + 10));
+  const title = 24 + cut(t.name, 48).length * 7.6 + (t.kind === 'table' ? 0 : 50);
+  return { w: Math.round(Math.min(480, Math.max(160, widest, title))), h: HEAD + Math.max(1, rows) * ROW + 6 };
+}
+
+/** The y offset (in its box) of a column's row; the header for a column not drawn. */
+export function rowOffset(t: ModelTable, column: string) {
+  const i = shownColumns(t).findIndex((c) => c.name === column);
+  return i < 0 ? HEAD / 2 : HEAD + i * ROW + ROW / 2;
+}
+
+/**
+ * A foreign key line from a child's row (a, ay) to its parent's row (b, by): an orthogonal path, the crow's foot
+ * (many) at the child and a bar (one) at the parent. The same function is in public/data-modeler.js.
+ */
+export function fkPath(a: Box, ay: number, b: Box, by: number) {
+  const y1 = a.y + ay;
+  const y2 = b.y + by;
+  let x1: number, x2: number, d1: number, d2: number, path: string;
+  if (a.x + a.w + 40 <= b.x) {
+    [x1, x2, d1, d2] = [a.x + a.w, b.x, 1, -1];
+    const mx = Math.round((x1 + x2) / 2);
+    path = `M ${x1} ${y1} H ${mx} V ${y2} H ${x2}`;
+  } else if (b.x + b.w + 40 <= a.x) {
+    [x1, x2, d1, d2] = [a.x, b.x + b.w, -1, 1];
+    const mx = Math.round((x1 + x2) / 2);
+    path = `M ${x1} ${y1} H ${mx} V ${y2} H ${x2}`;
+  } else {
+    // one above the other (or the same table): around the right-hand sides
+    [x1, x2, d1, d2] = [a.x + a.w, b.x + b.w, 1, 1];
+    const lx = Math.max(x1, x2) + (a === b ? 18 : 30);
+    const yy = a === b && y1 === y2 ? y2 + 10 : y2;
+    path = `M ${x1} ${y1} H ${lx} V ${yy} H ${x2}`;
+  }
+  const foot = `M ${x1 + d1 * 14} ${y1} L ${x1} ${y1 - 7} M ${x1 + d1 * 14} ${y1} L ${x1} ${y1 + 7} M ${x1 + d1 * 14} ${y1 - 7} V ${y1 + 7}`;
+  const bar = `M ${x2 + d2 * 10} ${y2 - 7} V ${y2 + 7}`;
+  return { path, ends: `${foot} ${bar}`, circle: { cx: x2 + d2 * 20, cy: y2 } };
+}
+
+export interface Line {
+  from: string;
+  to: string;
+  name: string;
+  fy: number;
+  ty: number;
+  optional: boolean;
+  label: string;
+}
+
+/** The foreign key lines between the shown tables. */
+export function lines(schema: string, tables: ModelTable[]): Line[] {
+  const by = new Map(tables.map((t) => [t.name, t]));
+  return tables.flatMap((t) =>
+    t.constraints.filter((k) => k.type === 'f' && k.refSchema === schema && k.refTable && by.has(k.refTable)).map((k) => ({
+      from: t.name,
+      to: k.refTable!,
+      name: k.name,
+      fy: rowOffset(t, k.cols[0]),
+      ty: rowOffset(by.get(k.refTable!)!, k.refCols[0]),
+      optional: k.cols.some((c) => !t.columns.find((x) => x.name === c)?.notNull),
+      label: `${t.name}(${k.cols.join(', ')}) → ${k.refTable}(${k.refCols.join(', ')}): ${k.name}`,
+    })),
+  );
+}
+
+/**
+ * Positions for all tables: parents left of their children (by foreign key levels), each level a column, a column
+ * wraps when it gets taller than the others need.
+ */
+export function autoLayout(schema: string, tables: ModelTable[]): Placed[] {
+  const size = new Map(tables.map((t) => [t.name, boxSize(t)]));
+  const parents = new Map(tables.map((t) => [t.name, [...new Set(t.constraints.filter((k) => k.type === 'f' && k.refSchema === schema && k.refTable !== t.name && size.has(k.refTable!)).map((k) => k.refTable!))]]));
+  const level = new Map<string, number>();
+  const visiting = new Set<string>();
+  const levelOf = (n: string): number => {
+    if (level.has(n)) return level.get(n)!;
+    if (visiting.has(n)) return 0; // a cycle: this edge doesn't count
+    visiting.add(n);
+    const l = Math.max(-1, ...parents.get(n)!.map(levelOf)) + 1;
+    visiting.delete(n);
+    level.set(n, l);
+    return l;
+  };
+  for (const t of tables) levelOf(t.name);
+  const total = tables.reduce((s, t) => s + size.get(t.name)!.h + 40, 0);
+  const maxH = Math.max(900, Math.sqrt(total * 900), ...tables.map((t) => size.get(t.name)!.h));
+  const levels = [...new Set(level.values())].sort((a, b) => a - b);
+  const index = new Map<string, number>();
+  const out: Placed[] = [];
+  let x = 20;
+  for (const l of levels) {
+    const members = tables.filter((t) => level.get(t.name) === l).map((t) => t.name);
+    // near their parents: by the parents' mean position, then by name
+    const key = (n: string) => {
+      const p = parents.get(n)!.filter((x) => index.has(x));
+      return p.length ? p.reduce((s, x) => s + index.get(x)!, 0) / p.length : Number.MAX_SAFE_INTEGER;
+    };
+    members.sort((a, b) => key(a) - key(b) || a.localeCompare(b));
+    let y = 20;
+    let colW = 0;
+    for (const n of members) {
+      const s = size.get(n)!;
+      if (y > 20 && y + s.h > maxH) {
+        x += colW + 60;
+        y = 20;
+        colW = 0;
+      }
+      index.set(n, index.size);
+      out.push({ name: n, x, y });
+      y += s.h + 40;
+      colW = Math.max(colW, s.w);
+    }
+    x += colW + 100;
+  }
+  return out;
+}
+
+/** Saved positions for the shown tables; tables without one get the automatic layout's (below the others when some are placed). */
+export function placeAll(schema: string, tables: ModelTable[], saved: Placed[]): Placed[] {
+  const known = new Map(saved.map((p) => [p.name, p]));
+  const missing = tables.filter((t) => !known.has(t.name));
+  if (!missing.length) return tables.map((t) => known.get(t.name)!);
+  const placedTables = tables.filter((t) => known.has(t.name));
+  if (!placedTables.length) return autoLayout(schema, tables);
+  const bottom = Math.max(...placedTables.map((t) => known.get(t.name)!.y + boxSize(t).h)) + 60;
+  const extra = autoLayout(schema, missing).map((p) => ({ ...p, y: p.y + bottom - 20 }));
+  return tables.map((t) => known.get(t.name) ?? extra.find((p) => p.name === t.name)!);
+}
+
+// ---------------------------------------------------------------- SVG
+
+export const COLORS = { bg: '#ffffff', frame: '#94a3b8', head: '#e8eefc', title: '#1e293b', text: '#334155', muted: '#64748b', key: '#b45309', line: '#475569', view: '#f1f5f9' };
+
+/** Where a box's title links: Table Properties for a table, the Object Browser for a view. */
+export const objectHref = (schema: string, t: ModelTable) =>
+  t.kind === 'table'
+    ? `/builder/sql/objects/table?${new URLSearchParams({ o: t.ref })}`
+    : `/builder/sql/objects?${new URLSearchParams({ schema, k: t.kind === 'view' ? 'view' : 'matview', o: t.ref })}`;
+
+/** Key markers of a column: P primary key, F foreign key, U unique. */
+export function markers(t: ModelTable, column: string) {
+  const has = (type: string) => t.constraints.some((k) => k.type === type && k.cols.includes(column));
+  return `${has('p') ? 'P' : ''}${has('f') ? 'F' : ''}${!has('p') && has('u') ? 'U' : ''}`;
+}
+
+/** The whole diagram. `title` names it; `links` makes box titles links (the page; not an exported file); `auto`: each box's automatic position (data-ax/ay, for the page's Auto layout). */
+export function diagramSvg(schema: string, title: string, tables: ModelTable[], placed: Placed[], opts: { links?: boolean; id?: string; auto?: Placed[] } = {}): Raw {
+  const autoAt = new Map((opts.auto ?? []).map((p) => [p.name, p]));
+  const pos = new Map(placed.map((p) => [p.name, p]));
+  const boxes = new Map(tables.map((t) => [t.name, { ...pos.get(t.name)!, ...boxSize(t) } as Box]));
+  const all = [...boxes.values()];
+  const W = Math.max(400, ...all.map((b) => b.x + b.w + 60));
+  const H = Math.max(240, ...all.map((b) => b.y + b.h + 40));
+  const c = COLORS;
+  const fk = lines(schema, tables).map((l) => {
+    const p = fkPath(boxes.get(l.from)!, l.fy, boxes.get(l.to)!, l.ty);
+    return html`<g class="dm-fk${l.optional ? ' dm-optional' : ''}" data-from="${l.from}" data-to="${l.to}" data-fy="${l.fy}" data-ty="${l.ty}"><title>${l.label}</title>
+      <path class="dm-line" d="${p.path}" fill="none" stroke="${c.line}" stroke-width="1.5"${l.optional ? raw(' stroke-dasharray="6 4"') : ''}/>
+      <path class="dm-end" d="${p.ends}" fill="none" stroke="${c.line}" stroke-width="1.5"/>${l.optional ? html`<circle class="dm-opt" cx="${p.circle.cx}" cy="${p.circle.cy}" r="4" fill="${c.bg}" stroke="${c.line}" stroke-width="1.5"/>` : ''}</g>`;
+  });
+  const box = (t: ModelTable) => {
+    const b = boxes.get(t.name)!;
+    const cols = shownColumns(t);
+    const titleText = html`<text class="dm-title" x="10" y="20" font-weight="600" font-size="13" fill="${c.title}">${cut(t.name, 48)}</text>`;
+    return html`<g class="dm-box dm-${t.kind === 'table' ? 'table' : 'view'}" data-name="${t.name}" data-x="${b.x}" data-y="${b.y}" data-w="${b.w}" data-h="${b.h}"${autoAt.has(t.name) ? html` data-ax="${autoAt.get(t.name)!.x}" data-ay="${autoAt.get(t.name)!.y}"` : ''} transform="translate(${b.x} ${b.y})"${opts.links ? raw(' tabindex="0"') : ''} aria-label="${t.kind} ${t.name}">
+      <title>${t.kind} ${schema}.${t.name}${t.comment ? `: ${t.comment}` : ''}</title>
+      <rect class="dm-frame" width="${b.w}" height="${b.h}" rx="4" fill="${t.kind === 'table' ? c.bg : c.view}" stroke="${c.frame}"/>
+      <path class="dm-head" d="M 0.5 4.5 a 4 4 0 0 1 4 -4 H ${b.w - 4.5} a 4 4 0 0 1 4 4 V ${HEAD} H 0.5 Z" fill="${c.head}" stroke="${c.frame}"/>
+      ${opts.links ? html`<a class="dm-link" href="${objectHref(schema, t)}">${titleText}</a>` : titleText}
+      ${t.kind === 'table' ? '' : html`<text class="dm-kind" x="${b.w - 8}" y="20" text-anchor="end" font-size="10" fill="${c.muted}">${t.kind === 'view' ? 'view' : 'mat. view'}</text>`}
+      ${cols.map((col, i) => {
+        const y = HEAD + i * ROW + 14;
+        return html`<g class="dm-row"><title>${col.name} ${col.type}${col.notNull ? ' not null' : ''}${col.comment ? `: ${col.comment}` : ''}</title>
+          <text class="dm-key" x="6" y="${y}" font-size="10" font-weight="700" fill="${c.key}">${markers(t, col.name)}</text>
+          <text class="dm-col" x="26" y="${y}" font-size="12" fill="${c.text}"${col.notNull ? raw(' font-weight="600"') : ''}>${col.notNull ? '* ' : ''}${cut(col.name, 36)}</text>
+          <text class="dm-type" x="${b.w - 8}" y="${y}" text-anchor="end" font-size="11" fill="${c.muted}">${cut(col.type, 24)}</text></g>`;
+      })}
+      ${cols.length < t.columns.length ? html`<text class="dm-more" x="26" y="${HEAD + cols.length * ROW + 14}" font-size="11" font-style="italic" fill="${c.muted}">… ${t.columns.length - cols.length} more columns</text>` : ''}
+      ${!t.columns.length ? html`<text class="dm-more" x="26" y="${HEAD + 14}" font-size="11" font-style="italic" fill="${c.muted}">no columns</text>` : ''}
+    </g>`;
+  };
+  return html`<svg xmlns="http://www.w3.org/2000/svg" class="dm-svg"${opts.id ? raw(` id="${opts.id.replace(/[^a-z0-9-]/g, '')}"`) : ''} width="${W}" height="${H}" viewBox="0 0 ${W} ${H}" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif" role="group" aria-label="Diagram ${title}">
+    <title>${title}: ${tables.length} objects of schema ${schema}</title>
+    <rect class="dm-bg" width="100%" height="100%" fill="${c.bg}"/>
+    <g class="dm-content"><g class="dm-lines">${fk}</g><g class="dm-boxes">${tables.map(box)}</g></g>
+  </svg>`;
+}

package/src/dbroles.ts

@@ -0,0 +1,215 @@
+import { createHash, createHmac, pbkdf2Sync, randomBytes } from 'node:crypto';
+import pg from 'pg';
+
+// (sprint 99, Database Actions DA-13) Database Users: the SQL that creates, changes and drops a PostgreSQL role,
+// from what the form says and what the catalog says now. Pure functions: src/builder/db-users.ts reads the
+// catalog and runs the statements; test/db-users.test.ts tests them.
+//
+// Passwords: the server never sends a password to PostgreSQL. scramVerifier() hashes it here (SCRAM-SHA-256,
+// like psql's \password and libpq's PQencryptPasswordConn), and the statement carries the verifier as a literal
+// (pg's escapeLiteral). Statements are built with PASSWORD_SLOT in its place: maskSql() shows them with
+// '********' (the review, the activity log), withVerifier() fills in the verifier only for running them.
+
+const ident = pg.escapeIdentifier;
+// pg's escapeLiteral starts a literal with a backslash as " E'…'": without the space
+const literal = (s: string) => pg.escapeLiteral(s).trim();
+
+/** Where the password goes in a generated statement (never shown: see maskSql / withVerifier). */
+export const PASSWORD_SLOT = '\u0000password\u0000';
+export const MASK = `'********'`;
+
+export type DefaultPriv = 'none' | 'read' | 'write' | 'custom';
+export type ExistingPriv = '' | 'read' | 'write' | 'revoke';
+
+export interface SchemaGrant {
+  schema: string;
+  usage: boolean;
+  create: boolean;
+  /** privileges on tables (and sequences) the creator makes in the schema from now on */
+  defaults: DefaultPriv;
+  /** a one-off grant on the tables there now ('' = no change) */
+  existing?: ExistingPriv;
+}
+
+export interface RoleSpec {
+  name: string;
+  login: boolean;
+  /** keep the password, set a new one, or remove it (an existing role); none / set for a new one */
+  password: 'keep' | 'set' | 'remove';
+  /** YYYY-MM-DD, '' = no expiry */
+  validUntil: string;
+  /** -1 = no limit */
+  connLimit: number;
+  memberOf: string[];
+  /** the search path in this database, comma separated ('' = the server's default) */
+  searchPath: string;
+  comment: string;
+  schemas: SchemaGrant[];
+}
+
+export interface RoleContext {
+  /** the current database (ALTER ROLE … IN DATABASE) */
+  database: string;
+  /** the role whose new objects the default privileges cover (pgkiln's owner connection) */
+  creator: string;
+}
+
+export const emptyRole = (name = ''): RoleSpec => ({ name, login: false, password: 'keep', validUntil: '', connLimit: -1, memberOf: [], searchPath: '', comment: '', schemas: [] });
+
+/** A name for a new role: PostgreSQL reserves pg_, pgkiln reserves pgkiln. */
+export const ROLE_NAME = /^[A-Za-z_][A-Za-z0-9_$]{0,62}$/;
+export const reservedName = (name: string) => /^pg_/i.test(name) || /^pgkiln/i.test(name);
+
+/** The schemas of a search path ($user stays $user), or null when one isn't a plain name. */
+export function parseSearchPath(text: string): string[] | null {
+  const parts = text.split(',').map((p) => p.trim()).filter(Boolean).map((p) => (/^".*"$/.test(p) ? p.slice(1, -1).replace(/""/g, '"') : p));
+  return parts.every((p) => p === '$user' || /^[A-Za-z_][A-Za-z0-9_$]{0,62}$/.test(p)) ? parts : null;
+}
+
+const validDate = (d: string) => {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(d)) return false;
+  const t = new Date(`${d}T00:00:00Z`);
+  return !Number.isNaN(t.getTime()) && t.toISOString().slice(0, 10) === d;
+};
+
+export interface CheckOptions {
+  isNew: boolean;
+  /** roles a role may be made a member of (existing memberships may stay) */
+  grantable: string[];
+  /** schemas whose privileges the form may change */
+  schemas: string[];
+  before: RoleSpec | null;
+}
+
+/** What is wrong with a spec (empty: fine). */
+export function checkRole(spec: RoleSpec, o: CheckOptions): string[] {
+  const errors: string[] = [];
+  if (o.isNew) {
+    if (!ROLE_NAME.test(spec.name)) errors.push('The name starts with a letter or _ and has only letters, digits, _ and $ (at most 63).');
+    else if (reservedName(spec.name)) errors.push('Names starting with pg_ or pgkiln are reserved (PostgreSQL, pgkiln).');
+  }
+  if (spec.validUntil && !validDate(spec.validUntil)) errors.push('Valid until is a date (YYYY-MM-DD).');
+  if (!Number.isInteger(spec.connLimit) || spec.connLimit < -1 || spec.connLimit > 100000) errors.push('The connection limit is a whole number from -1 (no limit) to 100000.');
+  if (spec.searchPath && !parseSearchPath(spec.searchPath)) errors.push('The search path is a comma-separated list of schema names ($user for the role\'s own).');
+  if (spec.comment.length > 1000) errors.push('The comment has at most 1000 characters.');
+  const kept = new Set(o.before?.memberOf ?? []);
+  for (const m of spec.memberOf) {
+    if (m === spec.name) errors.push('A role is not a member of itself.');
+    else if (!kept.has(m) && !o.grantable.includes(m)) errors.push(`The role ${m} can't be granted here (pgkiln's own roles, superusers and login roles can't).`);
+  }
+  for (const s of spec.schemas) {
+    if (!o.schemas.includes(s.schema)) errors.push(`Privileges on the schema ${s.schema} aren't changed here.`);
+    if (!['none', 'read', 'write', 'custom'].includes(s.defaults)) errors.push(`Unknown default privileges for ${s.schema}.`);
+    if (s.existing && !['read', 'write', 'revoke'].includes(s.existing)) errors.push(`Unknown privileges on the tables of ${s.schema}.`);
+  }
+  if (o.isNew && spec.password === 'remove') errors.push('A new role has no password to remove.');
+  return errors;
+}
+
+/** What is wrong with a new password and its confirmation (empty: fine). */
+export function checkPassword(password: string, confirm: string): string[] {
+  if (password.length < 8) return ['The password has at least 8 characters.'];
+  if (password.length > 1024) return ['The password has at most 1024 characters.'];
+  if (password.includes('\0')) return ['The password can\'t contain a NUL character.'];
+  if (password !== confirm) return ['The password and its confirmation differ.'];
+  return [];
+}
+
+const privs: Record<Exclude<DefaultPriv, 'custom' | 'none'>, string> = { read: 'SELECT', write: 'SELECT, INSERT, UPDATE, DELETE' };
+
+/**
+ * The statements that make `before` (the catalog; null for a new role) into `after`, the password as
+ * PASSWORD_SLOT. Nothing that is already so is repeated.
+ */
+export function roleSql(before: RoleSpec | null, after: RoleSpec, ctx: RoleContext): string[] {
+  const out: string[] = [];
+  const r = ident(after.name);
+  const b = before ?? emptyRole(after.name);
+  const opts: string[] = [];
+  if (!before || before.login !== after.login) opts.push(after.login ? 'LOGIN' : 'NOLOGIN');
+  if (after.password === 'set') opts.push(`PASSWORD ${PASSWORD_SLOT}`);
+  else if (after.password === 'remove' && before) opts.push('PASSWORD NULL');
+  if (b.validUntil !== after.validUntil) opts.push(`VALID UNTIL ${literal(after.validUntil || 'infinity')}`);
+  if (b.connLimit !== after.connLimit) opts.push(`CONNECTION LIMIT ${after.connLimit}`);
+  if (!before) out.push(`CREATE ROLE ${r}${opts.length ? ` ${opts.join(' ')}` : ''};`);
+  else if (opts.length) out.push(`ALTER ROLE ${r} ${opts.join(' ')};`);
+
+  for (const g of after.memberOf.filter((m) => !b.memberOf.includes(m))) out.push(`GRANT ${ident(g)} TO ${r};`);
+  for (const g of b.memberOf.filter((m) => !after.memberOf.includes(m))) out.push(`REVOKE ${ident(g)} FROM ${r};`);
+
+  const path = (t: string) => (parseSearchPath(t) ?? []).join(',');
+  if (path(b.searchPath) !== path(after.searchPath)) {
+    const p = parseSearchPath(after.searchPath) ?? [];
+    out.push(p.length ? `ALTER ROLE ${r} IN DATABASE ${ident(ctx.database)} SET search_path TO ${p.map(ident).join(', ')};`
+      : `ALTER ROLE ${r} IN DATABASE ${ident(ctx.database)} RESET search_path;`);
+  }
+
+  for (const s of after.schemas) {
+    const was = b.schemas.find((x) => x.schema === s.schema) ?? { schema: s.schema, usage: false, create: false, defaults: 'none' as DefaultPriv };
+    const n = ident(s.schema);
+    const grant = [s.usage && !was.usage ? 'USAGE' : '', s.create && !was.create ? 'CREATE' : ''].filter(Boolean);
+    const revoke = [!s.usage && was.usage ? 'USAGE' : '', !s.create && was.create ? 'CREATE' : ''].filter(Boolean);
+    if (grant.length) out.push(`GRANT ${grant.join(', ')} ON SCHEMA ${n} TO ${r};`);
+    if (revoke.length) out.push(`REVOKE ${revoke.join(', ')} ON SCHEMA ${n} FROM ${r};`);
+    if (s.defaults !== 'custom' && s.defaults !== was.defaults) {
+      const adp = `ALTER DEFAULT PRIVILEGES FOR ROLE ${ident(ctx.creator)} IN SCHEMA ${n}`;
+      if (was.defaults !== 'none') out.push(`${adp} REVOKE ALL ON TABLES FROM ${r};`, `${adp} REVOKE ALL ON SEQUENCES FROM ${r};`);
+      if (s.defaults !== 'none') out.push(`${adp} GRANT ${privs[s.defaults]} ON TABLES TO ${r};`);
+      if (s.defaults === 'write') out.push(`${adp} GRANT USAGE, SELECT ON SEQUENCES TO ${r};`);
+    }
+    if (s.existing === 'revoke') out.push(`REVOKE ALL ON ALL TABLES IN SCHEMA ${n} FROM ${r};`, `REVOKE ALL ON ALL SEQUENCES IN SCHEMA ${n} FROM ${r};`);
+    else if (s.existing === 'read' || s.existing === 'write') {
+      out.push(`GRANT ${privs[s.existing]} ON ALL TABLES IN SCHEMA ${n} TO ${r};`);
+      if (s.existing === 'write') out.push(`GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ${n} TO ${r};`);
+    }
+  }
+
+  if (b.comment !== after.comment) out.push(`COMMENT ON ROLE ${r} IS ${after.comment ? literal(after.comment) : 'NULL'};`);
+  return out;
+}
+
+/**
+ * The statements that drop a role: its objects reassigned to another role (or, without one, dropped with it),
+ * its privileges and default privileges in this database revoked (DROP OWNED), then the role.
+ */
+export function dropSql(name: string, reassignTo: string | null): string[] {
+  const r = ident(name);
+  return [...(reassignTo ? [`REASSIGN OWNED BY ${r} TO ${ident(reassignTo)};`] : []), `DROP OWNED BY ${r};`, `DROP ROLE ${r};`];
+}
+
+/** The statements as the review and the activity log show them: the password masked. */
+export const maskSql = (stmts: string[]) => stmts.map((s) => s.split(PASSWORD_SLOT).join(MASK)).join('\n');
+
+/** The statements to run: the password slot filled with the SCRAM verifier (never shown or logged). */
+export const withVerifier = (stmts: string[], verifier: string | null) =>
+  stmts.map((s) => {
+    if (!s.includes(PASSWORD_SLOT)) return s;
+    if (!verifier) throw new Error('A password is needed.');
+    return s.split(PASSWORD_SLOT).join(literal(verifier));
+  });
+
+/** A digest of the reviewed (masked) statements: Apply runs only what the review showed. */
+export const reviewDigest = (stmts: string[]) => createHash('sha256').update(maskSql(stmts)).digest('base64url');
+
+// ------------------------------------------------------------------ SCRAM-SHA-256
+
+// RFC 4013 SASLprep, as PostgreSQL applies it (src/common/saslprep.c): non-ASCII spaces become spaces,
+// characters "mapped to nothing" go, NFKC; a password it can't prepare (control characters) is used as it is.
+const NON_ASCII_SPACE = /[   -   　]/g;
+const TO_NOTHING = /[­͏᠆᠋-᠍​-‍⁠︀-️]/g;
+export function saslprep(password: string): string {
+  // eslint-disable-next-line no-control-regex
+  if (/^[\x20-\x7E]*$/.test(password)) return password;
+  const prepared = password.replace(NON_ASCII_SPACE, ' ').replace(TO_NOTHING, '').normalize('NFKC');
+  // eslint-disable-next-line no-control-regex
+  return /[\u0000-\u001F\u007F-\u009F]/.test(prepared) || !prepared ? password : prepared;
+}
+
+/** A SCRAM-SHA-256 verifier for ALTER ROLE … PASSWORD (PostgreSQL stores a verifier as it is). */
+export function scramVerifier(password: string, salt: Buffer = randomBytes(16), iterations = 4096): string {
+  const salted = pbkdf2Sync(Buffer.from(saslprep(password), 'utf8'), salt, iterations, 32, 'sha256');
+  const clientKey = createHmac('sha256', salted).update('Client Key').digest();
+  const storedKey = createHash('sha256').update(clientKey).digest();
+  const serverKey = createHmac('sha256', salted).update('Server Key').digest();
+  return `SCRAM-SHA-256$${iterations}:${salt.toString('base64')}$${storedKey.toString('base64')}:${serverKey.toString('base64')}`;
+}