pgkiln 0.69.0 → 0.71.0

package/src/builder/ui-defaults.ts

@@ -0,0 +1,161 @@
+import type { FastifyInstance } from 'fastify';
+import { owner } from '../db.ts';
+import { html, raw } from '../html.ts';
+import { icon } from '../icons.ts';
+import { back, BASE, csrf, developer, flash, region, send, shell, type Body, type Req } from './ui.ts';
+import { usableSchemas, workshopDb } from './workspaces.ts';
+
+// (sprint 138, AP-5) UI defaults (APEX: Attribute Dictionary / Table UI
+// Defaults): per table column a label, format mask, help text, alignment and
+// list of values, in meta.ui_default (migration 138). The page wizards and the
+// Create Application wizard take the label from meta.wizard_column_label (a UI
+// default wins); a form item a wizard makes also gets the mask, help and list
+// of values (the meta.item trigger of migration 138). "Seed from comments" fills
+// the columns without a UI default from their COMMENT ON: a short comment (60
+// characters at most) as the label, a longer one as the help text.
+//
+// The tables are those the workspace's SQL Workshop connection can see
+// (workshopDb: an isolated workspace's own schemas); a table or column name
+// from a request is only used after it was found in that catalog.
+
+export const ALIGNMENTS = ['', 'start', 'center', 'end'] as const;
+/** Format masks: numbers (999G990D00, FML…) and dates (DD.MM.YYYY HH24:MI); the database checks the same. */
+export const MASK = /^[A-Za-z0-9GDLSCFM.,:/ -]{1,60}$/;
+const MAX_COLUMNS = 400;
+
+interface Column {
+  name: string;
+  type: string;
+  comment: string | null;
+  wizard: string;
+  d: { label: string | null; format_mask: string | null; help: string | null; alignment: string | null; lov: string | null; updated_by: string | null; updated_at: string | null } | null;
+}
+
+/** A table the session's catalog can see: [schema, table], or null. */
+async function findTable(s: Parameters<typeof workshopDb>[0], schema: unknown, table: unknown) {
+  if (typeof schema !== 'string' || typeof table !== 'string' || !schema || !table) return null;
+  const db = await workshopDb(s);
+  if (!(await usableSchemas(db)).includes(schema)) return null;
+  const r = await db.one<{ oid: number }>(
+    `select c.oid::int as oid from pg_class c join pg_namespace n on n.oid = c.relnamespace
+      where n.nspname = $1 and c.relname = $2 and c.relkind in ('r', 'p', 'v', 'm', 'f')`, [schema, table]);
+  return r ? { schema, table, oid: r.oid } : null;
+}
+
+async function columnsOf(oid: number, schema: string, table: string): Promise<Column[]> {
+  const cols = (await owner.query(
+    `select a.attname as name, format_type(a.atttypid, a.atttypmod) as type, col_description(a.attrelid, a.attnum) as comment,
+            meta.wizard_column_label(a.attrelid::regclass, a.attname) as wizard
+       from pg_attribute a where a.attrelid = $1 and a.attnum > 0 and not a.attisdropped order by a.attnum limit ${MAX_COLUMNS}`, [oid])).rows;
+  const defaults = new Map((await owner.query(
+    `select column_name, label, format_mask, help, alignment, lov, updated_by, updated_at::text from meta.ui_default where schema_name = $1 and table_name = $2`,
+    [schema, table])).rows.map((r) => [r.column_name, r]));
+  return cols.map((c) => ({ ...c, d: defaults.get(c.name) ?? null }));
+}
+
+const trim = (v: unknown, max: number) => (typeof v === 'string' && v.trim() ? v.trim().slice(0, max) : null);
+
+export async function uiDefaultRoutes(app: FastifyInstance) {
+  app.get(`${BASE}/ui-defaults`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const db = await workshopDb(s);
+    const schemas = await usableSchemas(db);
+    const q = req.query ?? {};
+    const schema = typeof q.schema === 'string' && schemas.includes(q.schema) ? q.schema : '';
+    const tables = schema
+      ? (await db.query<{ name: string; n: number }>(
+          `select c.relname as name, (select count(*) from meta.ui_default d where d.schema_name = $1 and d.table_name = c.relname)::int as n
+             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', 'f') and not c.relispartition order by 1`,
+          [schema])).rows
+      : [];
+    const t = schema ? await findTable(s, schema, q.table) : null;
+    const counts = (await owner.query<{ schema_name: string; n: number }>('select schema_name, count(*)::int as n from meta.ui_default group by 1')).rows;
+    const pick = html`<form method="get" class="util-filters">
+        <div class="field"><label class="label" for="f_schema">Schema</label><select id="f_schema" name="schema"><option value="">Choose a schema</option>
+          ${schemas.map((n) => html`<option value="${n}"${n === schema ? raw(' selected') : ''}>${n}${counts.find((c) => c.schema_name === n) ? ` (${counts.find((c) => c.schema_name === n)!.n})` : ''}</option>`)}</select></div>
+        ${schema ? html`<div class="field"><label class="label" for="f_table">Table or view</label><select id="f_table" name="table"><option value="">Choose a table</option>
+          ${tables.map((x) => html`<option value="${x.name}"${x.name === t?.table ? raw(' selected') : ''}>${x.name}${x.n ? ` (${x.n})` : ''}</option>`)}</select></div>` : ''}
+        <div class="buttons"><button class="btn btn-sm">${icon('table')} Show</button></div></form>`;
+    let body = html`${pick}`;
+    if (t) {
+      const cols = await columnsOf(t.oid, t.schema, t.table);
+      body = html`${pick}
+        <form method="post" action="${BASE}/ui-defaults">${csrf(s)}<input type="hidden" name="schema" value="${t.schema}"><input type="hidden" name="table" value="${t.table}">
+          <div class="table-wrap"><table class="table ui-defaults report-reflow"><thead><tr><th scope="col">Column</th><th scope="col">Label</th><th scope="col">Format mask</th><th scope="col">Alignment</th><th scope="col">Help</th><th scope="col">List of values</th></tr></thead><tbody>
+          ${cols.map((c, i) => html`<tr>
+            <td data-label="Column"><code>${c.name}</code><br><span class="muted small">${c.type}</span><input type="hidden" name="c.${i}.name" value="${c.name}"></td>
+            <td data-label="Label"><input id="f_l${i}" aria-label="Label of ${c.name}" name="c.${i}.label" value="${c.d?.label ?? ''}" maxlength="200" placeholder="${c.wizard}"></td>
+            <td data-label="Format mask"><input id="f_m${i}" aria-label="Format mask of ${c.name}" name="c.${i}.format_mask" value="${c.d?.format_mask ?? ''}" maxlength="60" placeholder="${/numeric|integer|bigint|smallint|real|double/.test(c.type) ? '999G990D00' : /date|time/.test(c.type) ? 'DD.MM.YYYY' : ''}"></td>
+            <td data-label="Alignment"><select id="f_a${i}" aria-label="Alignment of ${c.name}" name="c.${i}.alignment">${ALIGNMENTS.map((x) => html`<option value="${x}"${(c.d?.alignment ?? '') === x ? raw(' selected') : ''}>${x || '–'}</option>`)}</select></td>
+            <td data-label="Help"><textarea id="f_h${i}" aria-label="Help of ${c.name}" name="c.${i}.help" rows="1" maxlength="4000">${c.d?.help ?? ''}</textarea></td>
+            <td data-label="List of values"><input id="f_v${i}" aria-label="List of values of ${c.name}" name="c.${i}.lov" value="${c.d?.lov ?? ''}" maxlength="4000" placeholder="LOV:NAME"></td>
+          </tr>`)}</tbody></table></div>
+          <div class="buttons"><button class="btn btn-hot" name="mode" value="save">${icon('save')} Save</button>
+            <button class="btn" name="mode" value="seed">${icon('edit')} Seed from comments</button></div>
+          <p class="muted small">An empty row has no UI default. The placeholder of a label shows what the wizards use without one. Lists of values: <code>LOV:NAME</code> (a shared list of values of the application), <code>STATIC:Yes;Y,No;N</code> or a query (<code>select name d, id r from sales.status</code>).</p>
+        </form>`;
+    }
+    const main = html`<h1 class="u-mb1">UI defaults</h1>
+      ${region('UI defaults per column', html`<p class="muted u-mt0">Label, format mask, help text, alignment and list of values per table column (APEX: Attribute Dictionary). The page wizards and the Create Application wizard use the label for every generated report heading and form item, and a generated form item also gets the format mask, help and list of values. They apply to pages generated after the change, in every application.</p>${body}`)}`;
+    return send(reply, s, shell(s, 'UI defaults', [['App Builder', BASE], ['Workspace utilities', `${BASE}/utilities`], ['UI defaults']], main));
+  });
+
+  app.post(`${BASE}/ui-defaults`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const b: Body = req.body ?? {};
+    const t = await findTable(s, b.schema, b.table);
+    if (!t) return reply.code(404).send('Not found');
+    const to = `${BASE}/ui-defaults?${new URLSearchParams({ schema: t.schema, table: t.table })}`;
+    const cols = await columnsOf(t.oid, t.schema, t.table);
+    const known = new Map(cols.map((c) => [c.name, c]));
+    try {
+      if (b.mode === 'seed') {
+        // columns without a UI default: a short comment is the label, a longer one the help text
+        let n = 0;
+        for (const c of cols) {
+          if (c.d || !c.comment?.trim()) continue;
+          const text = c.comment.trim();
+          const short = text.length <= 60 && !text.includes('\n');
+          await owner.query(
+            `insert into meta.ui_default (schema_name, table_name, column_name, label, help, updated_by) values ($1, $2, $3, $4, $5, $6) on conflict do nothing`,
+            [t.schema, t.table, c.name, short ? text : null, short ? null : text.slice(0, 4000), s.username]);
+          n++;
+        }
+        flash(s, n ? `UI defaults of ${n} column${n === 1 ? '' : 's'} made from their comments.` : 'No column without a UI default has a comment.');
+        return back(reply, s, to);
+      }
+      const rows: { name: string; label: string | null; mask: string | null; help: string | null; align: string | null; lov: string | null }[] = [];
+      for (let i = 0; i < MAX_COLUMNS; i++) {
+        const name = b[`c.${i}.name`];
+        if (typeof name !== 'string' || !known.has(name)) continue;
+        const mask = trim(b[`c.${i}.format_mask`], 60);
+        if (mask && !MASK.test(mask)) throw new Error(`Format mask of ${name}: letters, digits and . , : / - only (e.g. 999G990D00 or DD.MM.YYYY).`);
+        const align = trim(b[`c.${i}.alignment`], 10);
+        if (align && !(ALIGNMENTS as readonly string[]).includes(align)) throw new Error(`Alignment of ${name}: start, center or end.`);
+        rows.push({ name, label: trim(b[`c.${i}.label`], 200), mask, help: trim(b[`c.${i}.help`], 4000), align, lov: trim(b[`c.${i}.lov`], 4000) });
+      }
+      await owner.tx(async (c) => {
+        for (const r of rows) {
+          const before = known.get(r.name)!.d;
+          if (!r.label && !r.mask && !r.help && !r.align && !r.lov) {
+            if (before) await c.query('delete from meta.ui_default where schema_name = $1 and table_name = $2 and column_name = $3', [t.schema, t.table, r.name]);
+            continue;
+          }
+          if (before && before.label === r.label && before.format_mask === r.mask && before.help === r.help && before.alignment === r.align && before.lov === r.lov) continue;
+          await c.query(
+            `insert into meta.ui_default (schema_name, table_name, column_name, label, format_mask, help, alignment, lov, updated_by)
+             values ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+             on conflict (schema_name, table_name, column_name) do update set label = excluded.label, format_mask = excluded.format_mask, help = excluded.help,
+               alignment = excluded.alignment, lov = excluded.lov, updated_by = excluded.updated_by, updated_at = now()`,
+            [t.schema, t.table, r.name, r.label, r.mask, r.help, r.align, r.lov, s.username]);
+        }
+      });
+      flash(s, `UI defaults of ${t.schema}.${t.table} saved.`);
+    } catch (e) {
+      flash(s, (e as Error).message, 'error');
+    }
+    return back(reply, s, to);
+  });
+}

package/src/builder/ui.ts

@@ -243,7 +243,7 @@ export const region = (title: string, body: Raw | Raw[], extra: Raw | '' = '', i
   html`<section class="region region-standard"${id ? raw(` id="${id.replace(/[^a-z0-9-]/g, '')}"`) : ''}><header class="region-header"><h2>${title}</h2>${extra}</header><div class="region-body">${body}</div></section>`;
 
 /** Title and tabs of an application's builder pages (Pages, Shared Components, …), in the session's builder language. */
-export const appHeader = (a: any, active: 'pages' | 'shared' | 'settings' | 'activity' | 'api' | 'search' | 'advisor', s?: Pick<Session, 'state'>) => {
+export const appHeader = (a: any, active: 'pages' | 'shared' | 'settings' | 'activity' | 'api' | 'search' | 'advisor' | 'utilities', s?: Pick<Session, 'state'>) => {
   const tx = tr(s);
   const tab = (key: typeof active, href: string, ic: string, label: string) =>
     html`<a class="ide-tab" href="${href}"${active === key ? raw(' aria-current="page"') : ''}>${bicon(ic)}<span>${label}</span></a>`;
@@ -266,6 +266,7 @@ export const appHeader = (a: any, active: 'pages' | 'shared' | 'settings' | 'act
         ${tab('settings', `${BASE}/apps/${a.id}/settings`, 'settings', tx('app.tab.settings'))}
         ${tab('search', `${BASE}/apps/${a.id}/search`, 'search', tx('common.search'))}
         ${tab('advisor', `${BASE}/apps/${a.id}/advisor`, 'check', tx('app.tab.advisor'))}
+        ${tab('utilities', `${BASE}/apps/${a.id}/utilities`, 'wrench', tx('app.tab.utilities'))}
       </nav>
     </div>`;
 };

package/src/builder/upgrade.ts

@@ -0,0 +1,154 @@
+import type { FastifyInstance } from 'fastify';
+import { stableJson } from '../appfiles.ts';
+import { owner } from '../db.ts';
+import { recordHistory } from '../history.ts';
+import { html, raw } from '../html.ts';
+import { icon } from '../icons.ts';
+import { appHeader, back, BASE, csrf, designerUrl, developer, flash, region, send, shell, type Req } from './ui.ts';
+import { diffHtml } from './utilities.ts';
+
+// (sprint 138, AP-5) App Builder → Utilities → Upgrade application (APEX:
+// Upgrade Application): components made before a pgkiln version that brought a
+// better default, each with its reason, a preview of the change and an Upgrade
+// button (or all of a kind at once). The candidates are worked out again on
+// every request: a POST names a candidate's key, and only a candidate that is
+// still found is changed. Each upgrade is recorded in the change history.
+//
+// Rules:
+//  - nav_appearance: an application without a navigation appearance gets
+//    Pillar Light (sprint 117), the look of new applications.
+//  - date_picker: a text item of a form whose column is a date or a timestamp
+//    becomes a date / date-time item with pgkiln's date picker (sprint 84).
+//  - popup_lov: a select list whose list of values reads a table of more than
+//    POPUP_ROWS rows (the planner's estimate) becomes a popup list of values,
+//    which searches and pages on the server instead of sending every row.
+
+export const POPUP_ROWS = 1000;
+
+export interface Candidate {
+  key: string;
+  rule: Rule;
+  label: string;
+  page: number | null;
+  url: string;
+  reason: string;
+  before: Record<string, unknown>;
+  after: Record<string, unknown>;
+  /** the change: a statement and its parameters */
+  sql: [string, unknown[]];
+}
+
+export type Rule = 'nav_appearance' | 'date_picker' | 'popup_lov';
+export const RULES: Record<Rule, { title: string; since: string }> = {
+  nav_appearance: { title: 'Navigation appearance', since: 'Navigation appearances (Pillar Light, Pillar Dark) came with sprint 117.' },
+  date_picker: { title: 'Date picker for date columns', since: 'Date and date-time items have had pgkiln\'s date picker since sprint 84.' },
+  popup_lov: { title: 'Paged list of values for large tables', since: 'Popup lists of values search and page on the server.' },
+};
+
+/** The relations a list of values query reads (FROM / JOIN names). */
+export const lovTables = (sql: string) =>
+  [...sql.matchAll(/\b(?:from|join)\s+((?:"[^"]+"|[A-Za-z_][\w$]*)(?:\s*\.\s*(?:"[^"]+"|[A-Za-z_][\w$]*))?)/gi)].map((m) => m[1].replace(/\s+/g, ''));
+
+/** Every upgrade candidate of an application. */
+export async function upgradeCandidates(appId: number): Promise<Candidate[]> {
+  const out: Candidate[] = [];
+  const app = await owner.one('select id, theme from meta.app where id = $1', [appId]);
+  if (!app) return out;
+  const theme = app.theme && typeof app.theme === 'object' ? app.theme : {};
+  if (typeof theme.appearance !== 'string' || !theme.appearance) {
+    out.push({
+      key: 'nav_appearance:app', rule: 'nav_appearance', label: 'Application settings › Theme', page: null, url: `${BASE}/apps/${appId}/theme`,
+      reason: 'The application has no navigation appearance: Pillar Light gives the header strip and the filled current page of new applications.',
+      before: { appearance: theme.appearance ?? null }, after: { appearance: 'pillar_light' },
+      sql: [`update meta.app set theme = coalesce(theme, '{}'::jsonb) || '{"appearance": "pillar_light"}' where id = $1 and coalesce(theme ->> 'appearance', '') = ''`, [appId]],
+    });
+  }
+  const dates = (await owner.query(
+    `select i.id, i.name, i.type, p.page_no, i.source_column, r.table_name, format_type(a.atttypid, a.atttypmod) as coltype,
+            a.atttypid = 'date'::regtype as is_date
+       from meta.item i join meta.page p on p.id = i.page_id join meta.region r on r.id = i.region_id
+       join pg_attribute a on a.attrelid = to_regclass(r.table_name) and a.attname = i.source_column and not a.attisdropped
+      where p.app_id = $1 and i.type = 'text' and r.type = 'form' and r.table_name is not null
+        and a.atttypid in ('date'::regtype, 'timestamp'::regtype, 'timestamptz'::regtype)
+      order by p.page_no, i.seq, i.id`, [appId])).rows;
+  for (const r of dates) {
+    const to = r.is_date ? 'date' : 'datetime';
+    out.push({
+      key: `date_picker:${r.id}`, rule: 'date_picker', label: `Page ${r.page_no} › item ${r.name}`, page: r.page_no, url: designerUrl(appId, r.page_no, `c=item-${r.id}`),
+      reason: `${r.table_name}.${r.source_column} is a ${r.coltype} column shown as a text field: a ${to} item has the date picker and reads the date in the application's format.`,
+      before: { type: 'text' }, after: { type: to },
+      sql: [`update meta.item set type = $2 where id = $1 and type = 'text'`, [r.id, to]],
+    });
+  }
+  const selects = (await owner.query(
+    `select i.id, i.name, p.page_no, i.lov from meta.item i join meta.page p on p.id = i.page_id
+      where p.app_id = $1 and i.type = 'select' and i.lov is not null and i.lov !~* '^\\s*(STATIC|LOV):'
+      order by p.page_no, i.seq, i.id`, [appId])).rows;
+  for (const r of selects) {
+    const names = lovTables(r.lov);
+    if (!names.length) continue;
+    const big = (await owner.query<{ name: string; n: number }>(
+      `select x as name, c.reltuples::bigint::int as n from unnest($1::text[]) x join pg_class c on c.oid = to_regclass(x) where c.reltuples > $2 order by c.reltuples desc limit 1`,
+      [names, POPUP_ROWS]).catch(() => ({ rows: [] }))).rows[0];
+    if (!big) continue;
+    out.push({
+      key: `popup_lov:${r.id}`, rule: 'popup_lov', label: `Page ${r.page_no} › item ${r.name}`, page: r.page_no, url: designerUrl(appId, r.page_no, `c=item-${r.id}`),
+      reason: `Its list of values reads ${big.name} (about ${big.n} rows): a select list sends every row with the page; a popup list of values searches and pages on the server.`,
+      before: { type: 'select' }, after: { type: 'popup_lov' },
+      sql: [`update meta.item set type = 'popup_lov' where id = $1 and type = 'select'`, [r.id]],
+    });
+  }
+  return out;
+}
+
+export async function upgradeRoutes(app: FastifyInstance) {
+  const appOf = async (id: string) => (/^\d{1,9}$/.test(id) ? owner.one('select * from meta.app where id = $1', [id]) : undefined);
+
+  app.get(`${BASE}/apps/:id/utilities/upgrade`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const a = await appOf(req.params.id);
+    if (!a) return reply.code(404).send('Not found');
+    const all = await upgradeCandidates(a.id);
+    const preview = typeof req.query?.preview === 'string' ? all.find((c) => c.key === req.query.preview) : undefined;
+    const u = `${BASE}/apps/${a.id}/utilities/upgrade`;
+    const sections = (Object.keys(RULES) as Rule[]).map((rule) => {
+      const list = all.filter((c) => c.rule === rule);
+      return html`<section class="util-upgrade" aria-labelledby="up-${rule}"><h3 id="up-${rule}">${RULES[rule].title} <span class="tag">${list.length}</span></h3>
+        <p class="muted small">${RULES[rule].since}</p>
+        ${list.length ? html`<div class="table-wrap"><table class="table report-reflow"><thead><tr><th scope="col">Component</th><th scope="col">Why</th><th scope="col">Actions</th></tr></thead><tbody>
+          ${list.map((c) => html`<tr${preview?.key === c.key ? raw(' aria-current="true"') : ''}><td data-label="Component"><a href="${c.url}">${c.label}</a></td><td data-label="Why">${c.reason}</td>
+            <td data-label="Actions"><div class="buttons"><a class="btn btn-sm" href="${u}?preview=${encodeURIComponent(c.key)}#preview">Preview</a>
+              <form method="post" action="${u}">${csrf(s)}<input type="hidden" name="key" value="${c.key}"><button class="btn btn-sm btn-hot">${icon('refresh')} Upgrade</button></form></div></td></tr>`)}</tbody></table></div>
+          ${list.length > 1 ? html`<form method="post" action="${u}" class="u-mt075">${csrf(s)}<input type="hidden" name="rule" value="${rule}"><button class="btn btn-sm">${icon('refresh')} Upgrade all ${list.length}</button></form>` : ''}`
+          : html`<p class="muted">Nothing to upgrade.</p>`}</section>`;
+    });
+    const main = html`${appHeader(a, 'utilities', s)}
+      ${region('Upgrade application', html`<p class="muted u-mt0">Components made before a pgkiln version that brought a better default. Preview a change, then upgrade one component or all of a kind; every upgrade is in the change history (and the backups) if you want to go back.</p>${sections}`)}
+      ${preview ? region(`Preview: ${preview.label}`, html`<p class="muted u-mt0">${preview.reason}</p>${diffHtml('settings', stableJson(preview.before), stableJson(preview.after), ['now', 'upgraded'])}
+        <form method="post" action="${u}">${csrf(s)}<input type="hidden" name="key" value="${preview.key}"><div class="buttons"><button class="btn btn-hot">${icon('refresh')} Upgrade</button></div></form>`, '', 'preview') : ''}`;
+    return send(reply, s, shell(s, `Upgrade application · ${a.name}`, [['App Builder', BASE], [a.name, `${BASE}/apps/${a.id}`], ['Utilities', `${BASE}/apps/${a.id}/utilities`], ['Upgrade application']], main));
+  });
+
+  app.post(`${BASE}/apps/:id/utilities/upgrade`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const a = await appOf(req.params.id);
+    if (!a) return reply.code(404).send('Not found');
+    const all = await upgradeCandidates(a.id);
+    const key = typeof req.body?.key === 'string' ? req.body.key : '';
+    const rule = typeof req.body?.rule === 'string' ? req.body.rule : '';
+    const chosen = key ? all.filter((c) => c.key === key) : all.filter((c) => c.rule === rule);
+    const to = `${BASE}/apps/${a.id}/utilities/upgrade`;
+    if (!chosen.length) {
+      flash(s, 'Nothing to upgrade: the component was changed or upgraded in the meantime.', 'error');
+      return back(reply, s, to);
+    }
+    await owner.tx(async (c) => {
+      for (const x of chosen) await c.query(x.sql[0], x.sql[1]);
+    });
+    await recordHistory(a.id, s.username, 'upgrade').catch((err) => req.log.warn({ err }, 'change history not recorded'));
+    flash(s, chosen.length === 1 ? `${chosen[0].label} upgraded.` : `${chosen.length} components upgraded.`);
+    return back(reply, s, to);
+  });
+}

package/src/builder/utilities.ts

@@ -0,0 +1,181 @@
+import type { FastifyInstance } from 'fastify';
+import { unifiedDiff } from '../cli/diff.ts';
+import { owner } from '../db.ts';
+import { appChecksum, ensureSnapshot, pageChecksums, shortSum } from '../history.ts';
+import { html, raw, type Raw } from '../html.ts';
+import { icon, ICONS, LUCIDE_VERSION, lucideNames, searchIcons } from '../icons.ts';
+import { appOfPath } from './locks.ts';
+import { appHeader, BASE, designerUrl, developer, region, select, send, shell, type Req } from './ui.ts';
+
+// (sprint 138, AP-5) App Builder → an application's Utilities (APEX: Application
+// Utilities): one page for what an application's maintenance needs, the tools
+// that existed elsewhere (Advisor, Search, Debug messages, Backups, Activity,
+// Working copies, Export) and the new ones: Database object dependencies
+// (dependencies.ts), Change history (below; recorded by src/history.ts), Upgrade
+// application (upgrade.ts), UI defaults (ui-defaults.ts), the application and
+// page checksums (history.ts) and the icon browser (/builder/icons).
+
+const appOf = async (id: string) => (/^\d{1,9}$/.test(id) ? owner.one('select * from meta.app where id = $1', [id]) : undefined);
+const when = (t: string | null | undefined) => (t ? String(t).slice(0, 16).replace('T', ' ') : '');
+
+/** A unified diff with its added and removed lines marked (escaped). */
+export function diffHtml(path: string, a: string | null | undefined, b: string | null | undefined, names: [string, string]): Raw {
+  const text = unifiedDiff(path, a === null || a === undefined ? undefined : Buffer.from(a), b === null || b === undefined ? undefined : Buffer.from(b), names);
+  return html`<pre class="code-block diff">${text.replace(/\n$/, '').split('\n').map((l) =>
+    l.startsWith('+') && !l.startsWith('+++') ? html`<span class="diff-add">${l}</span>\n` : l.startsWith('-') && !l.startsWith('---') ? html`<span class="diff-del">${l}</span>\n` : html`${l}\n`)}</pre>`;
+}
+
+/** The files of one change as diffs (before → after). */
+function changeDiff(before: Record<string, string> | null, after: Record<string, string> | null): Raw {
+  const paths = [...new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})])].sort();
+  return html`${paths.map((p) => (before?.[p] === after?.[p] ? '' : diffHtml(p, before?.[p], after?.[p], ['before', 'after'])))}`;
+}
+
+/** The component of a history row in the builder (a page component opens the page designer). */
+const componentUrl = (appId: number, page: number | null) => (page !== null && page !== undefined && page >= 0 ? designerUrl(appId, page) : `${BASE}/apps/${appId}/shared`);
+
+/** (registered on the root instance, like app-updates.ts) a first snapshot before an application's first recorded change */
+export function historyHooks(app: FastifyInstance) {
+  const snapshotted = new Set<number>();
+  app.addHook('preHandler', async (req) => {
+    if (req.method !== 'POST' || !req.url.startsWith(`${BASE}/`)) return;
+    const target = await appOfPath(req.url).catch(() => null);
+    if (!target || snapshotted.has(target.appId)) return;
+    await ensureSnapshot(target.appId).catch((err) => req.log.warn({ err }, 'app snapshot not taken'));
+    snapshotted.add(target.appId);
+  });
+}
+
+export async function utilityRoutes(app: FastifyInstance) {
+  // ---------------------------------------------------------------- the Utilities page
+  app.get(`${BASE}/apps/:id/utilities`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const a = await appOf(req.params.id);
+    if (!a) return reply.code(404).send('Not found');
+    const doc = (await owner.one('select meta.export_app($1) as d', [a.alias])).d;
+    const sum = appChecksum(doc);
+    const pageSums = pageChecksums(doc);
+    const counts = await owner.one(
+      `select (select count(*) from meta.page where app_id = $1)::int as pages,
+              (select count(*) from meta.region r join meta.page p on p.id = r.page_id where p.app_id = $1)::int as regions,
+              (select count(*) from meta.item i join meta.page p on p.id = i.page_id where p.app_id = $1)::int as items,
+              (select count(*) from meta.process x join meta.page p on p.id = x.page_id where p.app_id = $1)::int as processes,
+              (select count(*) from meta.lov where app_id = $1)::int as lovs,
+              (select count(*) from meta.component_change where app_id = $1 and changed_at > now() - interval '7 days')::int as week`,
+      [a.id],
+    );
+    const pages = (await owner.query<{ page_no: number; name: string }>('select page_no, name from meta.page where app_id = $1 order by page_no', [a.id])).rows;
+    const recent = (await owner.query<{ page_no: number; changed_at: string; changed_by: string | null; n: number }>(
+      `select distinct on (page_no) page_no, changed_at::text, changed_by, count(*) over (partition by page_no)::int as n
+         from meta.component_change where app_id = $1 and page_no is not null order by page_no, changed_at desc`, [a.id])).rows
+      .sort((x, y) => (x.changed_at < y.changed_at ? 1 : -1)).slice(0, 10);
+    const pageName = new Map(pages.map((p) => [p.page_no, p.name]));
+    const card = (href: string, ic: string, title: string, text: string) =>
+      html`<a class="ab-tile" href="${href}"><span class="ab-tile-icon">${icon(ic)}</span><strong>${title}</strong><span>${text}</span></a>`;
+    const u = `${BASE}/apps/${a.id}`;
+    const main = html`${appHeader(a, 'utilities', s)}
+      <div class="ab-tiles ab-tiles-wrap util-tiles">
+        ${card(`${u}/advisor`, 'check', 'Advisor', 'Plans every SQL statement as the application\'s role and checks every reference.')}
+        ${card(`${u}/utilities/dependencies`, 'database', 'Database object dependencies', 'The tables, views, sequences and functions the application uses, missing ones and missing grants.')}
+        ${card(`${u}/utilities/history`, 'history', 'Change history', 'Who changed which component and when, with the differences.')}
+        ${card(`${u}/utilities/upgrade`, 'refresh', 'Upgrade application', 'Components that can use a newer default of this pgkiln version.')}
+        ${card(`${BASE}/ui-defaults`, 'sliders-horizontal', 'UI defaults', 'Labels, format masks, help and lists of values per table column, used by the page wizards.')}
+        ${card(`${u}/search`, 'search', 'Search', 'Names, SQL, conditions, settings and help texts of every component.')}
+        ${card(`${u}/debug`, 'list', 'Debug messages', 'Timed steps of each request and messages from meta.debug().')}
+        ${card(`${u}/activity`, 'activity', 'Activity', 'Page views, errors, sign-ins and the application\'s logs.')}
+        ${card(`${u}/backups`, 'archive', 'Backups', 'Back up now, download and restore earlier versions.')}
+        ${card(`${u}/working-copies`, 'layers', 'Working copies', 'Change a copy, compare it and merge it back.')}
+        ${card(`${u}/export`, 'download', 'Export', `The application as a file (checksum ${shortSum(sum)}).`)}
+        ${card(`${BASE}/icons`, 'image', 'Icons', 'Browse the icons the icon picker offers.')}
+      </div>
+      ${region('Application dashboard', html`<dl class="util-stats">
+          <div><dt>Pages</dt><dd>${counts.pages}</dd></div><div><dt>Regions</dt><dd>${counts.regions}</dd></div>
+          <div><dt>Items</dt><dd>${counts.items}</dd></div><div><dt>Processes</dt><dd>${counts.processes}</dd></div>
+          <div><dt>Lists of values</dt><dd>${counts.lovs}</dd></div><div><dt>Changes in 7 days</dt><dd>${counts.week}</dd></div>
+        </dl>`)}
+      ${region('Recently updated pages', recent.length
+        ? html`<div class="table-wrap"><table class="table report-reflow"><thead><tr><th scope="col">Page</th><th scope="col">Last change</th><th scope="col">By</th><th scope="col">Changes</th></tr></thead><tbody>
+            ${recent.map((r) => html`<tr><td data-label="Page"><a href="${designerUrl(a.id, r.page_no)}">${r.page_no}${pageName.has(r.page_no) ? `: ${pageName.get(r.page_no)}` : ''}</a></td><td data-label="Last change">${when(r.changed_at)}</td>
+              <td data-label="By">${r.changed_by ?? 'command line'}</td><td data-label="Changes"><a href="${u}/utilities/history?page=${r.page_no}">${r.n}</a></td></tr>`)}</tbody></table></div>`
+        : html`<p class="muted u-mt0">No recorded changes yet: the change history starts with the first change after the upgrade to this version.</p>`)}
+      ${region('Application checksum', html`<p class="u-mt0">The checksum of the application's definition (its export without the alias): the same definition gives the same checksum on any installation, so two installations, or an application and its working copy, compare at a glance.</p>
+        <p class="util-sum"><code>${sum}</code></p>
+        <details><summary>Page checksums (${pageSums.size})</summary><div class="table-wrap"><table class="table report-reflow"><thead><tr><th scope="col">Page</th><th scope="col">Checksum</th></tr></thead><tbody>
+          ${[...pageSums].map(([p, h]) => html`<tr><td data-label="Page">${p}${pageName.has(p) ? `: ${pageName.get(p)}` : ''}</td><td data-label="Checksum"><code>${shortSum(h)}</code></td></tr>`)}</tbody></table></div></details>`, '', 'checksum')}`;
+    return send(reply, s, shell(s, `Utilities · ${a.name}`, [['App Builder', BASE], [a.name, u], ['Utilities']], main));
+  });
+
+  // ---------------------------------------------------------------- change history
+  app.get(`${BASE}/apps/:id/utilities/history`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const a = await appOf(req.params.id);
+    if (!a) return reply.code(404).send('Not found');
+    const q = req.query ?? {};
+    const dev = typeof q.dev === 'string' ? q.dev.slice(0, 200) : '';
+    const DATE = /^\d{4}-\d{2}-\d{2}$/;
+    const from = typeof q.from === 'string' && DATE.test(q.from) ? q.from : '';
+    const to = typeof q.to === 'string' && DATE.test(q.to) ? q.to : '';
+    const page = typeof q.page === 'string' && /^-?\d{1,9}$/.test(q.page) ? Number(q.page) : null;
+    const text = typeof q.q === 'string' ? q.q.trim().slice(0, 100) : '';
+    const shown = typeof q.c === 'string' && /^\d{1,18}$/.test(q.c) ? q.c : '';
+    const devs = (await owner.query<{ d: string | null }>('select distinct changed_by as d from meta.component_change where app_id = $1 order by 1 nulls last', [a.id])).rows.map((r) => r.d);
+    const params: unknown[] = [a.id];
+    const where = ['app_id = $1'];
+    const add = (sql: string, v: unknown) => {
+      params.push(v);
+      where.push(sql.replace('?', `$${params.length}`));
+    };
+    if (dev === '(command line)') where.push('changed_by is null');
+    else if (dev) add('changed_by = ?', dev);
+    if (from) add(`changed_at >= ?::date`, from);
+    if (to) add(`changed_at < ?::date + 1`, to);
+    if (page !== null) add('page_no = ?', page);
+    if (text) add(`(label ilike '%' || ? || '%' escape '\\')`, text.replace(/[\\%_]/g, (m) => `\\${m}`));
+    const rows = (await owner.query(
+      `select id::text, component, label, page_no, op, changed_by, source, changed_at::text from meta.component_change
+        where ${where.join(' and ')} order by changed_at desc, id desc limit 500`, params)).rows;
+    const detail = shown ? await owner.one('select id::text, label, page_no, op, before, after, changed_by, source, changed_at::text from meta.component_change where app_id = $1 and id = $2', [a.id, shown]) : null;
+    const keep = new URLSearchParams(Object.entries({ dev, from, to, page: page === null ? '' : String(page), q: text }).filter(([, v]) => v));
+    const link = (id: string) => `?${new URLSearchParams([...keep, ['c', id]])}#change`;
+    const OPS: Record<string, string> = { added: 'tag-info', changed: 'tag-warning', deleted: 'tag-error' };
+    const main = html`${appHeader(a, 'utilities', s)}
+      ${region('Change history', html`<p class="muted u-mt0">Every change made in the builder (and every import, restore or merge) is compared with the application before it: each component that was added, changed or deleted is listed here with who and when. Changes from the command line or the MCP server have no developer.</p>
+        <form method="get" class="util-filters">
+          ${select('dev', 'Developer', dev, [['', 'All'], ...devs.map((d): [string, string] => (d === null ? ['(command line)', 'Command line / import'] : [d, d]))])}
+          <div class="field"><label class="label" for="f_from">From</label><input id="f_from" name="from" type="date" value="${from}"></div>
+          <div class="field"><label class="label" for="f_to">To</label><input id="f_to" name="to" type="date" value="${to}"></div>
+          <div class="field"><label class="label" for="f_page">Page</label><input id="f_page" name="page" type="number" value="${page ?? ''}"></div>
+          <div class="field"><label class="label" for="f_q">Component</label><input id="f_q" name="q" type="search" value="${text}" placeholder="e.g. P3_ID"></div>
+          <div class="buttons"><button class="btn btn-sm">${icon('filter')} Show</button></div></form>
+        ${rows.length
+          ? html`<div class="table-wrap"><table class="table util-history report-reflow"><thead><tr><th scope="col">When</th><th scope="col">Developer</th><th scope="col">Component</th><th scope="col">Change</th><th scope="col">Differences</th></tr></thead><tbody>
+              ${rows.map((r) => html`<tr${r.id === shown ? raw(' aria-current="true"') : ''}><td data-label="When">${when(r.changed_at)}</td><td data-label="Developer">${r.changed_by ?? html`<span class="muted">${r.source === 'import' ? 'import' : 'command line'}</span>`}</td>
+                <td data-label="Component"><a href="${componentUrl(a.id, r.page_no)}">${r.label}</a></td>
+                <td data-label="Change"><span class="tag ${OPS[r.op] ?? ''}">${r.op}</span>${r.source !== 'builder' ? html` <span class="tag">${r.source}</span>` : ''}</td>
+                <td data-label="Differences"><a class="btn btn-sm" href="${link(r.id)}">Show</a></td></tr>`)}</tbody></table></div>`
+          : html`<p class="muted">No changes${where.length > 1 ? ' with these filters' : ' recorded yet'}.</p>`}`)}
+      ${detail ? region(`Differences: ${detail.label}`, html`<p class="muted u-mt0">${detail.op} by ${detail.changed_by ?? 'the command line'}, ${when(detail.changed_at)}. Lines with <code>-</code> are before the change, lines with <code>+</code> after it.</p>${changeDiff(detail.before, detail.after)}`, '', 'change') : ''}`;
+    return send(reply, s, shell(s, `Change history · ${a.name}`, [['App Builder', BASE], [a.name, `${BASE}/apps/${a.id}`], ['Utilities', `${BASE}/apps/${a.id}/utilities`], ['Change history']], main));
+  });
+
+  // ---------------------------------------------------------------- icons
+  app.get(`${BASE}/icons`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const q = typeof req.query?.q === 'string' ? req.query.q.trim().slice(0, 60) : '';
+    const needle = q.toLowerCase().replace(/^fa-/, '');
+    const own = (ICONS as readonly string[]).filter((n) => !needle || n.includes(needle));
+    const lucide = needle ? searchIcons(q, 300) : [];
+    const tile = (n: string) => html`<li><span class="icon-tile">${icon(n, 'icon icon-2x')}<code>${n}</code></span></li>`;
+    const main = html`<h1 class="u-mb1">Icons</h1>
+      ${region('Icon browser', html`<p class="muted u-mt0">The icons of the icon picker: pgkiln's own set and ${String(lucideNames().size)} Lucide icons (${LUCIDE_VERSION}, ISC licence). Use the name in an icon field; modifiers such as <code>lg</code>, <code>spin</code> or <code>success</code> may follow it (e.g. <code>truck lg success</code>), and Font APEX names work where Lucide has the same icon (<code>fa-users</code>).</p>
+        <form method="get" role="search" class="util-filters"><div class="field"><label class="label" for="f_icon_q">Search</label><input id="f_icon_q" name="q" type="search" value="${q}" placeholder="e.g. truck, money, arrow"></div>
+          <div class="buttons"><button class="btn btn-sm">${icon('search')} Search</button></div></form>
+        <h3>pgkiln (${own.length})</h3><ul class="util-icons">${own.map(tile)}</ul>
+        ${needle ? html`<h3>Lucide (${lucide.length}${lucide.length === 300 ? '+' : ''})</h3>${lucide.length ? html`<ul class="util-icons">${lucide.map(tile)}</ul>` : html`<p class="muted">No Lucide icon matches.</p>`}`
+          : html`<p class="muted">Search to see the matching Lucide icons.</p>`}`)}`;
+    return send(reply, s, shell(s, 'Icons', [['App Builder', BASE], ['Workspace utilities', `${BASE}/utilities`], ['Icons']], main));
+  });
+}