pgkiln 0.69.0 → 0.71.0

package/src/builder/wizards.ts

@@ -3,6 +3,7 @@ import { owner } from '../db.ts';
 import { html, raw, type Raw } from '../html.ts';
 import { ICONS } from '../icons.ts';
 import { appOr404 } from './forms.ts';
+import { addDashboard } from './appsheets.ts';
 import { appHeader, back, BASE, csrf, developer, flash, input, region, select, send, shell, type Req } from './ui.ts';
 
 // Create page wizards (APEX: Create Page). Step 1, on the app's Pages tab,
@@ -23,7 +24,32 @@ export const WIZARD_KINDS: [string, string, string][] = [
   ['facets', 'Faceted search', 'A report with a filter panel: values with counts, ranges and a search field.'],
   ['master_detail', 'Master detail', 'A grid of the table and, below it, an editable grid of the selected row\'s details.'],
 ];
-const KINDS = new Set(WIZARD_KINDS.map((k) => k[0]));
+/**
+ * (sprint 137, AP-3) The page types that reuse other regions (APEX: Create a Page → Component), made by the same
+ * meta.generate_page (migration 137), and the dashboard (addDashboard). WIZARD_KINDS above stay the types the
+ * AI path and blueprints propose.
+ */
+export const MORE_KINDS: [string, string, string][] = [
+  ['report', 'Interactive report', 'An interactive report of the table on its own page, optionally with a modal form page.'],
+  ['smart_filters', 'Smart filters', 'An interactive report with one search field above it that suggests filters (chips) from the columns.'],
+  ['search', 'Search page', 'A search region over the application\'s search configurations, or a new one on a table.'],
+  ['data_load', 'Data loading', 'A data load definition for the table and a page where users upload a CSV, Excel, JSON or XML file into it.'],
+  ['tree', 'Tree', 'The rows as a tree: an id, a parent (from a foreign key to the table itself) and a label.'],
+  ['timeline', 'Timeline', 'Rows as events on a vertical line: when, who, a title and a text (template component Timeline).'],
+  ['media_list', 'Media list', 'Rows with initials, a title, a description and a badge (template component Media list).'],
+  ['content_row', 'Content row', 'Rows with initials, a title and a description, and a secondary text and a badge on the right (template component Content row).'],
+  ['comments', 'Comments', 'Rows as a conversation: who wrote what and when (template component Comments).'],
+  ['dashboard', 'Dashboard', 'Charts of the application\'s tables, chosen from the data like a new application\'s dashboard.'],
+  ['wizard', 'Wizard', 'A form over several steps, one page per step with a progress list, Previous and Next; Finish adds the row.'],
+  ['tasks', 'Unified task list', 'The approval and action tasks of the signed-in user (a task list region).'],
+  ['workflows', 'Workflow console', 'The workflows the user started or administers, with their state and history.'],
+];
+/** All the page types step 2 knows: [key, label, description]. */
+export const PAGE_KINDS: [string, string, string][] = [...WIZARD_KINDS, ...MORE_KINDS];
+const KINDS = new Set(PAGE_KINDS.map((k) => k[0]));
+/** Page types that need no table (search takes one optionally, for a new search configuration). */
+export const NO_TABLE = new Set(['search', 'tasks', 'workflows', 'dashboard']);
+const TASK_CONTEXTS: [string, string][] = [['my', 'My tasks (to act on or claim)'], ['initiated', 'Tasks I requested'], ['admin', 'Tasks I administer']];
 const CHART_KINDS = ['bar', 'column', 'line', 'area', 'donut', 'pie', 'funnel'];
 const FUNCTIONS: [string, string][] = [['count', 'Count'], ['sum', 'Sum'], ['avg', 'Average'], ['min', 'Minimum'], ['max', 'Maximum']];
 
@@ -110,6 +136,55 @@ export function wizardOptions(kind: string, b: Record<string, unknown>) {
       o.search = b.search === 'true';
       o.form_page = formPage();
       break;
+    // (137) the page types of migration 137
+    case 'report':
+      o.form_page = formPage();
+      break;
+    case 'smart_filters':
+      o.facets = list(b.facets);
+      o.form_page = formPage();
+      break;
+    case 'tree':
+      for (const k of ['id_column', 'parent_column', 'label_column']) o[k] = str(k) || null;
+      o.expanded = /^\d{1,2}$/.test(str('expanded')) ? Number(str('expanded')) : 1;
+      o.form_page = formPage();
+      break;
+    case 'timeline':
+      for (const k of ['title', 'when', 'who', 'body']) o[k] = str(k) || null;
+      o.form_page = formPage();
+      break;
+    case 'media_list':
+    case 'content_row':
+      for (const k of ['title', 'description', 'badge', ...(kind === 'content_row' ? ['misc'] : [])]) o[k] = str(k) || null;
+      o.form_page = formPage();
+      break;
+    case 'comments':
+      for (const k of ['user', 'date', 'comment']) o[k] = str(k) || null;
+      break;
+    case 'data_load':
+      o.definition = str('definition').toUpperCase() || null;
+      o.mode = ['append', 'merge', 'replace'].includes(str('mode')) ? str('mode') : 'append';
+      o.skip_errors = b.skip_errors === 'true';
+      break;
+    case 'wizard':
+      o.columns = list(b.columns);
+      o.steps = /^\d{1,2}$/.test(str('steps')) ? Number(str('steps')) : 2;
+      o.return_page = pageNo(b.return_page);
+      break;
+    case 'search':
+      o.configs = list(b.configs).map((c) => c.toUpperCase());
+      o.form_page = formPage();
+      break;
+    case 'tasks':
+      o.context = TASK_CONTEXTS.some(([c]) => c === str('context')) ? str('context') : 'my';
+      o.completed = b.completed === 'true';
+      break;
+    case 'workflows':
+      o.context = str('context') === 'admin' ? 'admin' : 'initiator';
+      break;
+    case 'dashboard':
+      o.tables = list(b.tables);
+      break;
     case 'master_detail': {
       const d = str('detail');
       const at = d.lastIndexOf('|');
@@ -130,30 +205,31 @@ export async function wizardRoutes(app: FastifyInstance) {
     if (!a) return reply.code(404).send('Not found');
     const kind = String(req.query.kind ?? '');
     const table = String(req.query.table ?? '');
-    const rel = KINDS.has(kind) && table
+    const rel = KINDS.has(kind) && table && kind !== 'dashboard'
       ? await owner.one<{ t: string; relkind: string }>(
           `select meta.wizard_qname(c.oid) as t, c.relkind::text from pg_class c join pg_namespace n on n.oid = c.relnamespace
             where c.oid = to_regclass($1) and c.relkind in ('r', 'p', 'v', 'm') and n.nspname !~ '^pg_' and n.nspname not in ('information_schema', 'meta')`,
           [table],
         )
       : null;
-    if (!rel) {
+    if (!rel && !(NO_TABLE.has(kind) && !table)) {
       flash(s, KINDS.has(kind) ? 'Choose a table or view.' : 'Choose a page type.', 'error');
-      return back(reply, s, `${BASE}/apps/${a.id}`);
+      // (137) back to the type's table step on the Create page grid
+      return back(reply, s, KINDS.has(kind) ? `${BASE}/apps/${a.id}/create-page?type=${encodeURIComponent(kind)}` : `${BASE}/apps/${a.id}/create-page`);
     }
     const [cols, defaults] = await Promise.all([
-      owner.query<Col>('select * from meta.wizard_catalog($1::regclass)', [rel.t]).then((r) => r.rows),
-      owner.one<{ d: Record<string, any> }>('select meta.wizard_defaults($1, $2::regclass) as d', [kind, rel.t]).then((r) => r?.d ?? {}),
+      rel ? owner.query<Col>('select * from meta.wizard_catalog($1::regclass)', [rel.t]).then((r) => r.rows) : Promise.resolve([] as Col[]),
+      owner.one<{ d: Record<string, any> }>('select meta.wizard_defaults($1, $2::regclass) as d', [kind, rel?.t ?? null]).then((r) => r?.d ?? {}),
     ]);
     const nextPage = await freePage(a.id, Math.max(0, ...(await owner.query('select page_no from meta.page where app_id = $1', [a.id])).rows.map((p) => p.page_no)) + 1);
     const pk = cols.find((c) => c.is_pk)?.column_name ?? null;
     const role = a.db_role as string | null;
-    const access = role
+    const access = role && rel
       ? await owner.one<{ s: boolean; i: boolean; u: boolean; d: boolean }>(
           `select has_table_privilege($1, $2::regclass, 'select') as s, has_table_privilege($1, $2::regclass, 'insert') as i,
                   has_table_privilege($1, $2::regclass, 'update') as u, has_table_privilege($1, $2::regclass, 'delete') as d
             where exists (select 1 from pg_roles where rolname = $1)`,
-          [role, rel.t],
+          [role, rel!.t],
         )
       : null;
 
@@ -171,6 +247,8 @@ export async function wizardRoutes(app: FastifyInstance) {
       )}</div></fieldset>`;
     const formPage = (help: string) => input('form_page', 'Form page', '', { type: 'number', placeholder: `e.g. ${nextPage + 1} (empty: no form)`, help });
     const needsPk = ['report_form', 'grid', 'form', 'master_detail'].includes(kind);
+    const allCols = (c: Col) => c.kind !== 'binary';
+    const dates = (c: Col) => c.kind === 'date' || c.kind === 'timestamp';
 
     let fields: Raw | string = '';
     switch (kind) {
@@ -228,43 +306,134 @@ export async function wizardRoutes(app: FastifyInstance) {
           ${check('search', 'A search field above the facets', defaults.search !== false)}
           ${pk ? html`<div class="form-grid">${formPage('A modal form page, linked from each row, and a Create button.')}</div>` : ''}`;
         break;
+      // (137) the page types of migration 137
+      case 'report':
+        fields = pk ? html`<div class="form-grid">${formPage('A modal form page, linked from each row, and a Create button.')}</div>` : '';
+        break;
+      case 'smart_filters':
+        fields = html`
+          ${colChecks('facets', 'Filters (suggested in the search field)', defaults.facets ?? [], (c) => notBinary(c) && c.kind !== 'point' && c.kind !== 'other', (c) => (c.fk_table ? `: values of ${c.fk_table}.${c.fk_display ?? c.column_name}` : ['number', 'date', 'timestamp'].includes(c.kind) ? ': ranges' : ': values'))}
+          ${pk ? html`<div class="form-grid">${formPage('A modal form page, linked from each row, and a Create button.')}</div>` : ''}`;
+        break;
+      case 'tree':
+        fields = html`<div class="form-grid">
+            ${select('id_column', 'Node id', defaults.id_column ?? '', colOpts(allCols, false), 'What identifies a node: usually the primary key.')}
+            ${select('parent_column', 'Parent', defaults.parent_column ?? '', colOpts(allCols), 'The column with the parent node\'s id; proposed from a foreign key to the table itself. Rows whose parent is not in the table are the top level.')}
+            ${select('label_column', 'Label', defaults.label_column ?? '', colOpts(notBinary, false))}
+            ${input('expanded', 'Levels open at first', defaults.expanded ?? 1, { type: 'number' })}
+            ${pk ? formPage('A modal form page, opened by clicking a node.') : ''}
+          </div>`;
+        break;
+      case 'timeline':
+        fields = html`<div class="form-grid">
+            ${select('title', 'Title', defaults.title ?? '', colOpts(notBinary, false))}
+            ${select('when', 'When', defaults.when ?? '', colOpts(dates), 'The events come newest first.')}
+            ${select('who', 'Who', defaults.who ?? '', colOpts(notBinary))}
+            ${select('body', 'Text', defaults.body ?? '', colOpts(notBinary))}
+            ${pk ? formPage('A modal form page, linked from each title.') : ''}
+          </div>`;
+        break;
+      case 'media_list':
+      case 'content_row':
+        fields = html`<div class="form-grid">
+            ${select('title', 'Title', defaults.title ?? '', colOpts(notBinary, false), 'Its first two letters are the initials.')}
+            ${select('description', 'Description', defaults.description ?? '', colOpts(notBinary))}
+            ${kind === 'content_row' ? select('misc', 'Secondary text (on the right)', defaults.misc ?? '', colOpts(notBinary)) : ''}
+            ${select('badge', 'Badge', defaults.badge ?? '', colOpts(notBinary))}
+            ${pk ? formPage('A modal form page, linked from each title.') : ''}
+          </div>`;
+        break;
+      case 'comments':
+        fields = html`<div class="form-grid">
+            ${select('user', 'Who wrote it', defaults.user ?? '', colOpts(notBinary))}
+            ${select('date', 'When', defaults.date ?? '', colOpts(dates), 'The newest first.')}
+            ${select('comment', 'Comment', defaults.comment ?? '', colOpts(notBinary, false))}
+          </div>`;
+        break;
+      case 'data_load': {
+        const defs = (await owner.query<{ name: string; table_name: string }>('select name, table_name from meta.data_load_def where app_id = $1 order by name', [a.id])).rows;
+        fields = html`<div class="form-grid">
+            ${input('definition', 'Data load definition', defaults.definition ?? '', { required: true, help: `Upper case, e.g. ORDERS_LOAD. A new definition for ${rel?.t ?? 'the table'}; an existing one of that name is used as it is${defs.length ? ` (this application has ${defs.map((d) => d.name).join(', ')})` : ''}.` })}
+            ${select('mode', 'Mode', defaults.mode ?? 'append', [['append', 'Append: add the rows'], ['merge', 'Merge: update rows with the same key, add the others'], ['replace', 'Replace: delete all rows first']])}
+          </div>
+          ${check('skip_errors', 'Skip rows with errors', !!defaults.skip_errors, 'Load the good rows and list the others; otherwise nothing is loaded when a row fails.')}`;
+        break;
+      }
+      case 'wizard':
+        fields = html`<div class="form-grid">
+            ${input('steps', 'Steps', defaults.steps ?? 2, { type: 'number', help: 'One page per step, numbered from the page number up; the columns are shared out in order.' })}
+            ${input('return_page', 'After Finish or Cancel, go to page', defaults.return_page ?? '', { type: 'number', placeholder: a.home_page ? `empty: the home page (${a.home_page})` : 'empty: this page' })}
+          </div>
+          ${colChecks('columns', 'Columns', defaults.columns ?? [], (c) => !c.is_pk && !c.generated && c.kind !== 'binary' && c.kind !== 'geometry', (c) => (c.not_null && !c.has_default ? ', required: always included' : c.fk_table ? `, a select list of ${c.fk_table}` : ''))}`;
+        break;
+      case 'search': {
+        const configs = (await owner.query<{ name: string; label: string; source: string }>('select name, label, source from meta.search_config where app_id = $1 order by seq, name', [a.id])).rows;
+        const tables = await wizardTables(role);
+        fields = html`
+          ${configs.length
+            ? html`<fieldset class="prop-group"><legend>Search configurations</legend><div class="qb-pick">${configs.map((c) => html`<label class="check"><input type="checkbox" name="configs" value="${c.name}" checked> ${c.label} <span class="muted small">${c.name}, ${c.source.slice(0, 60)}</span></label>`)}</div></fieldset>`
+            : html`<p class="muted">This application has no search configurations yet (<a href="${BASE}/apps/${a.id}/shared?type=search_config">Shared Components → Search configurations</a>): choose a table to search below.</p>`}
+          <div class="form-grid">
+            ${select('table', 'And a new configuration on', rel?.t ?? '', [['', '- none -'], ...tables.filter((t) => t.access).map((t): [string, string] => [t.t, t.t])], 'Searches the table\'s text columns and shows its name (or first text) column as the result\'s title.')}
+            ${formPage('With a table: a modal form page that each result links to.')}
+          </div>`;
+        break;
+      }
+      case 'tasks':
+        fields = html`<div class="form-grid">${select('context', 'Show', defaults.context ?? 'my', TASK_CONTEXTS)}</div>
+          ${check('completed', 'Also completed tasks', !!defaults.completed)}
+          <p class="muted small">Tasks come from task definitions (Shared Components → Task definitions) and approvals started in processes or workflows.</p>`;
+        break;
+      case 'workflows':
+        fields = html`<div class="form-grid">${select('context', 'Show', defaults.context ?? 'initiator', [['initiator', 'The workflows the user started'], ['admin', 'The workflows the user administers']])}</div>`;
+        break;
+      case 'dashboard': {
+        const tables = (await wizardTables(role)).filter((t) => t.access);
+        fields = tables.length
+          ? html`<fieldset class="prop-group"><legend>Tables</legend><div class="qb-pick">${tables.map((t, n) => html`<label class="check"><input type="checkbox" name="tables" value="${t.t}"${n < 12 ? raw(' checked') : ''}> ${t.t}</label>`)}</div></fieldset>
+              <p class="muted small">A chart per table (at most six) of the rows per parent row or per repeating value, read from the data; tables with row level security are left out.</p>`
+          : html`<p class="alert alert-error" role="status">The application's database role can't read any table.</p>`;
+        break;
+      }
       case 'master_detail': {
+        const t = rel!.t;
         const details = (
           await owner.query<{ t: string; col: string }>(
             `select meta.wizard_qname(con.conrelid) as t, a.attname::text as col
                from pg_constraint con join pg_attribute a on a.attrelid = con.conrelid and a.attnum = con.conkey[1]
               where con.confrelid = $1::regclass and con.contype = 'f' and con.conrelid <> con.confrelid and array_length(con.conkey, 1) = 1
               order by 1, 2`,
-            [rel.t],
+            [t],
           )
         ).rows;
         fields = details.length
-          ? select('detail', 'Detail table', defaults.detail ? `${defaults.detail}|${defaults.detail_column}` : '', details.map((d): [string, string] => [`${d.t}|${d.col}`, `${d.t} (${d.col} → ${rel.t})`]), 'Tables with a foreign key to this table. Selecting a master row shows its details; new detail rows get the master\'s key.')
-          : html`<p class="alert alert-error" role="status">No table has a foreign key to ${rel.t}: a master-detail page needs one.</p>`;
+          ? select('detail', 'Detail table', defaults.detail ? `${defaults.detail}|${defaults.detail_column}` : '', details.map((d): [string, string] => [`${d.t}|${d.col}`, `${d.t} (${d.col} → ${t})`]), 'Tables with a foreign key to this table. Selecting a master row shows its details; new detail rows get the master\'s key.')
+          : html`<p class="alert alert-error" role="status">No table has a foreign key to ${t}: a master-detail page needs one.</p>`;
         break;
       }
     }
 
-    const kindName = WIZARD_KINDS.find((k) => k[0] === kind)![1];
+    const kindDef = PAGE_KINDS.find((k) => k[0] === kind)!;
+    const kindName = kindDef[1];
     const main = html`${appHeader(a, 'pages', s)}
-      ${region(`${kindName} on ${rel.t}`, html`
-        <p class="muted u-mt0">${WIZARD_KINDS.find((k) => k[0] === kind)![2]} The proposals come from the table's columns, key and foreign keys; change them below. <a href="${BASE}/apps/${a.id}">Back to choose another type or table</a>.</p>
-        ${needsPk && !pk ? html`<p class="alert alert-error" role="status">${rel.t} has no single-column primary key, which this page type needs.</p>` : ''}
-        ${role && access && !(access.s && (!needsPk || (access.i && access.u && access.d)))
-          ? html`<p class="alert alert-error" role="status">The application's database role <code>${role}</code> ${access.s ? 'can read but not change' : 'has no access to'} ${rel.t}: grant it the privileges the page needs (${needsPk ? 'select, insert, update, delete' : 'select'}).</p>`
+      ${region(rel && kind !== 'search' ? `${kindName} on ${rel.t}` : kindName, html`
+        <p class="muted u-mt0">${kindDef[2]} ${rel ? 'The proposals come from the table\'s columns, key and foreign keys; change them below.' : ''} <a href="${BASE}/apps/${a.id}/create-page">Back to choose another type${rel ? ' or table' : ''}</a>.</p>
+        ${rel && needsPk && !pk ? html`<p class="alert alert-error" role="status">${rel.t} has no single-column primary key, which this page type needs.</p>` : ''}
+        ${rel && role && access && !(access.s && (!(needsPk || kind === 'wizard' || kind === 'data_load') || (access.i && (kind === 'wizard' || (access.u && access.d)))))
+          ? html`<p class="alert alert-error" role="status">The application's database role <code>${role}</code> ${access.s ? 'can read but not change' : 'has no access to'} ${rel.t}: grant it the privileges the page needs (${needsPk ? 'select, insert, update, delete' : kind === 'wizard' ? 'select, insert' : kind === 'data_load' ? 'select, insert, update, delete for merge or replace' : 'select'}).</p>`
           : ''}
         <form method="post" action="${BASE}/apps/${a.id}/wizard">${csrf(s)}
-          <input type="hidden" name="kind" value="${kind}"><input type="hidden" name="table" value="${rel.t}">
+          <input type="hidden" name="kind" value="${kind}">${rel && kind !== 'search' ? html`<input type="hidden" name="table" value="${rel.t}">` : ''}
           <div class="form-grid">
             ${input('report_page', 'Page number', nextPage, { type: 'number', required: true })}
             ${input('label', 'Name', defaults.label ?? '', { help: 'The page title and the navigation entry.' })}
             ${select('icon', 'Menu icon', defaults.icon ?? 'table', [...ICONS])}
           </div>
-          ${['report_form', 'grid'].includes(kind) ? '' : check('nav', 'Add a navigation entry', !!defaults.nav)}
+          ${['report_form', 'grid', 'dashboard'].includes(kind) ? '' : check('nav', 'Add a navigation entry', !!defaults.nav)}
           ${fields}
           <div class="buttons"><a class="btn" href="${BASE}/apps/${a.id}">Cancel</a><button class="btn btn-hot">Create page</button></div>
         </form>`)}`;
-    return send(reply, s, shell(s, `Create page · ${a.name}`, [['App Builder', BASE], [a.name, `${BASE}/apps/${a.id}`], [`Create ${kindName.toLowerCase()} page`]], main));
+    return send(reply, s, shell(s, `Create page · ${a.name}`, [['App Builder', BASE], [a.name, `${BASE}/apps/${a.id}`], ['Create page', `${BASE}/apps/${a.id}/create-page`], [kindName]], main));
   });
 
   app.post(`${BASE}/apps/:id/wizard`, async (req: Req, reply) => {
@@ -272,26 +441,42 @@ export async function wizardRoutes(app: FastifyInstance) {
     if (!s) return;
     const b = (req.body ?? {}) as Record<string, unknown>;
     const kind = KINDS.has(String(b.kind)) ? String(b.kind) : 'report_form';
-    const table = String(b.table ?? '');
-    const retry = `${BASE}/apps/${req.params.id}/wizard?kind=${encodeURIComponent(kind)}&table=${encodeURIComponent(table)}`;
+    const table = kind === 'dashboard' || kind === 'tasks' || kind === 'workflows' ? '' : String(b.table ?? '');
+    const retry = `${BASE}/apps/${req.params.id}/wizard?kind=${encodeURIComponent(kind)}${table && kind !== 'search' ? `&table=${encodeURIComponent(table)}` : ''}`;
     try {
       const page = pageNo(b.report_page);
       if (page === null) throw new Error('Enter a page number.');
       const options = wizardOptions(kind, b);
+      if (!table && !NO_TABLE.has(kind)) throw new Error('Choose a table or view.');
       const id = await owner.tx(async (c) => {
-        const a = await c.query('select alias from meta.app where id = $1', [req.params.id]);
+        const a = await c.query('select alias, db_role from meta.app where id = $1', [req.params.id]);
         if (!a.rowCount) throw new Error('This application does not exist.');
         // report and form and grid keep their own icons and need no step 2 (older forms post here directly)
         if (kind === 'report_form' && options.form_page === null) throw new Error('Enter the form page number.');
         if (['report_form', 'grid'].includes(kind) && !options.icon) options.icon = kind === 'grid' ? 'grid' : 'table';
-        return (await c.query('select meta.generate_page($1, $2, $3::regclass, $4, $5::jsonb) as id', [a.rows[0].alias, kind, table, page, JSON.stringify(options)])).rows[0].id as number;
+        if (kind === 'dashboard') {
+          // (137) only tables the application's role can read
+          const readable = new Set((await wizardTables(a.rows[0].db_role)).filter((t) => t.access).map((t) => t.t));
+          const tables = (options.tables as string[]).filter((t) => readable.has(t));
+          if (!tables.length) throw new Error('Choose at least one table the application can read.');
+          const made = await addDashboard(c, a.rows[0].alias, tables, page);
+          if (!made) throw new Error('None of these tables has a column worth a chart (a foreign key, or values that repeat).');
+          const pid = (await c.query('select id from meta.page where app_id = $1 and page_no = $2', [req.params.id, page])).rows[0].id as number;
+          if (options.label) {
+            await c.query('update meta.page set name = $2, title = $2 where id = $1', [pid, options.label]);
+            await c.query('update meta.nav_entry set label = $3 where app_id = $1 and target_page = $2', [req.params.id, page, options.label]);
+          }
+          if (options.icon) await c.query('update meta.nav_entry set icon = $3 where app_id = $1 and target_page = $2', [req.params.id, page, options.icon]);
+          return pid;
+        }
+        return (await c.query('select meta.generate_page($1, $2, $3::regclass, $4, $5::jsonb) as id', [a.rows[0].alias, kind, table || null, page, JSON.stringify(options)])).rows[0].id as number;
       });
       const pages = (await owner.query('select page_no from meta.page where app_id = $1 and id >= $2 order by page_no', [req.params.id, id])).rows.map((r) => r.page_no);
-      flash(s, `${pages.length > 1 ? `Pages ${pages.join(' and ')}` : `Page ${page}`} created for ${table}. Make sure the app's database role has privileges on it.`);
+      flash(s, `${pages.length > 1 ? `Pages ${pages.join(', ')}` : `Page ${page}`} created${table ? ` for ${table}. Make sure the app's database role has privileges on it` : ''}.`);
       return back(reply, s, `${BASE}/pages/${id}`);
     } catch (e) {
       flash(s, (e as Error).message, 'error');
-      return back(reply, s, KINDS.has(String(b.kind)) && table ? retry : `${BASE}/apps/${req.params.id}`);
+      return back(reply, s, KINDS.has(String(b.kind)) && (table || NO_TABLE.has(kind)) ? retry : `${BASE}/apps/${req.params.id}`);
     }
   });
 }

package/src/cli/replace.ts

@@ -12,6 +12,7 @@
 import { randomBytes } from 'node:crypto';
 import type pg from 'pg';
 import { regionKeys } from '../appfiles.ts';
+import { ensureSnapshot, recordHistory } from '../history.ts';
 
 /** Tables of an application that are its definition: replaced. */
 export const REPLACED = [
@@ -84,7 +85,12 @@ export const KEPT = ['app_access', 'api_client', 'session', 'sso_pending', 'save
   // (125) who changed the application last in the builder (App Builder list: Updated by)
   'app_change',
   // (126) outgoing calls the network access lists refused (Administration → Network access; a log, 7 days)
-  'network_refusal'];
+  'network_refusal',
+  // (136) rows queued for their embeddings (the vector providers travel in meta.app)
+  'embedding_queue',
+  // (138) the change history and the snapshot it compares with (this installation's record)
+  'app_snapshot', 'component_change',
+];
 /** 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". */
@@ -138,6 +144,9 @@ export async function replaceApp(db: Db, doc: unknown, alias: string, opts: Repl
   const target = (await db.query<{ id: number }>('select id from meta.app where alias = $1 for update', [alias])).rows[0];
   if (!target) throw new Error(`application ${alias} not found`);
   const old = target.id;
+  // (sprint 138) the change history compares the application before and after (src/history.ts); not on a bare pool
+  const inTx = !('totalCount' in db);
+  if (inTx) await ensureSnapshot(old, db as pg.ClientBase);
   const backup = opts.backup === undefined ? { reason: 'import' as const } : opts.backup;
   if (backup) await db.query('select meta.backup_app($1, $2, $3, $4)', [old, backup.reason, backup.user ?? null, backup.note ?? null]);
   const tmpAlias = `pgkiln-replace-${randomBytes(6).toString('hex')}`;
@@ -249,5 +258,6 @@ export async function replaceApp(db: Db, doc: unknown, alias: string, opts: Repl
     [old, neu],
   );
   await db.query('delete from meta.app where id = $1', [neu]);
+  if (inTx) await recordHistory(old, opts.backup ? (opts.backup.user ?? null) : null, 'import', db as pg.ClientBase).catch(() => {});
   return old;
 }

package/src/history.ts

@@ -0,0 +1,155 @@
+// (sprint 138, AP-5) Change history per component (APEX: Application Utilities ›
+// Change History) and application checksums (APEX: Application Checksum).
+//
+// meta.app_snapshot keeps an application's export after its last recorded
+// change. After a builder change (app-updates.ts, onSend) and inside an import
+// --replace (cli/replace.ts: restores, merges, the command line and the MCP
+// server), recordHistory() exports the application again, splits both exports
+// into components the way working copies compare them (workingcopy.ts
+// components(): a region with its SQL, a page's settings, a list of values, …)
+// and stores each added, changed or deleted component with its files before and
+// after in meta.component_change (migration 138). The first change of an
+// application without a snapshot has nothing to compare with: ensureSnapshot()
+// takes one before a builder POST runs (a preHandler hook).
+//
+// appChecksum(): a SHA-256 over the export's files (the text layout, without the
+// format marker and with the alias blanked), so two installations, or an
+// application and its working copy, compare at a glance; pageChecksums() per page.
+import { createHash } from 'node:crypto';
+import type pg from 'pg';
+import { docToFiles, MARKER, type Doc, type FileMap } from './appfiles.ts';
+import { owner } from './db.ts';
+import { components, describe } from './workingcopy.ts';
+
+type Db = { query: (sql: string, params?: unknown[]) => Promise<pg.QueryResult<any>> };
+
+/** Days a change stays in the history (CHANGE_HISTORY_DAYS, default 365; 0 keeps everything). */
+export const historyDays = () => {
+  const n = Number(process.env.CHANGE_HISTORY_DAYS ?? 365);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 365;
+};
+
+/** The export as files of the text layout (SQL inline in YAML: readable diffs), the alias blanked. */
+export function appFiles(doc: Doc): FileMap {
+  const d = { ...doc, app: { ...(doc.app ?? {}), alias: '' } };
+  const files = docToFiles(d, 'text');
+  files.delete(MARKER);
+  return files;
+}
+
+const isText = (b: Buffer) => !b.subarray(0, 8000).includes(0);
+const asText = (files: Map<string, Buffer> | undefined) =>
+  files ? Object.fromEntries([...files].map(([p, b]) => [p, isText(b) ? b.toString('utf8') : `(binary, ${b.length} bytes, sha256 ${createHash('sha256').update(b).digest('hex').slice(0, 16)})`])) : null;
+
+const sameFiles = (a?: Map<string, Buffer>, b?: Map<string, Buffer>) => {
+  if (!a || !b) return !a && !b;
+  if (a.size !== b.size) return false;
+  for (const [p, buf] of a) if (!b.get(p)?.equals(buf)) return false;
+  return true;
+};
+
+export interface ComponentDiff {
+  component: string;
+  label: string;
+  page: number | null;
+  op: 'added' | 'changed' | 'deleted';
+  before: Record<string, string> | null;
+  after: Record<string, string> | null;
+}
+
+/** The components that differ between two exports. */
+export function diffDocs(before: Doc, after: Doc): ComponentDiff[] {
+  const a = components(appFiles(before)), b = components(appFiles(after));
+  const out: ComponentDiff[] = [];
+  for (const id of [...new Set([...a.keys(), ...b.keys()])].sort()) {
+    const x = a.get(id), y = b.get(id);
+    if (sameFiles(x, y)) continue;
+    const { label, page } = describe(id);
+    out.push({ component: id, label, page, op: !x ? 'added' : !y ? 'deleted' : 'changed', before: asText(x), after: asText(y) });
+  }
+  return out;
+}
+
+const exportDoc = async (db: Db, appId: number): Promise<Doc | null> =>
+  (await db.query('select meta.export_app(alias) as d from meta.app where id = $1', [appId])).rows[0]?.d ?? null;
+
+/** Take a first snapshot of an application that has none (before its first recorded change); with `db`, inside its transaction. */
+export async function ensureSnapshot(appId: number, db?: pg.ClientBase) {
+  const sql = `insert into meta.app_snapshot (app_id, doc) select id, meta.export_app(alias) from meta.app
+                where id = $1 and not exists (select 1 from meta.app_snapshot where app_id = $1)
+               on conflict (app_id) do nothing`;
+  if (!db) return void (await owner.query(sql, [appId]));
+  await db.query('savepoint history_snapshot');
+  try {
+    await db.query(sql, [appId]);
+    await db.query('release savepoint history_snapshot');
+  } catch {
+    await db.query('rollback to savepoint history_snapshot');
+  }
+}
+
+/**
+ * Compare the application with its snapshot, record what changed and keep the new snapshot.
+ * With `db` a client in the caller's transaction (an import --replace), else a transaction of its own.
+ */
+export async function recordHistory(appId: number, changedBy: string | null, source: 'builder' | 'import' | 'upgrade' = 'builder', db?: pg.ClientBase): Promise<number> {
+  const run = async (c: Db) => {
+    // one change at a time per application: the snapshot row is the lock
+    const snap = (await c.query('select doc from meta.app_snapshot where app_id = $1 for update', [appId])).rows[0];
+    const now = await exportDoc(c, appId);
+    if (!now) return 0;
+    if (!snap) {
+      await c.query('insert into meta.app_snapshot (app_id, doc) values ($1, $2) on conflict (app_id) do update set doc = excluded.doc, taken_at = now()', [appId, now]);
+      return 0;
+    }
+    const changes = diffDocs(snap.doc, now);
+    if (!changes.length) return 0;
+    await c.query(
+      `insert into meta.component_change (app_id, component, label, page_no, op, before, after, changed_by, source)
+       select $1, x.component, x.label, x.page, x.op, x.before, x.after, $2, $3
+         from jsonb_to_recordset($4::jsonb) as x(component text, label text, page int, op text, before jsonb, after jsonb)`,
+      [appId, changedBy?.slice(0, 200) ?? null, source, JSON.stringify(changes)],
+    );
+    await c.query('update meta.app_snapshot set doc = $2, taken_at = now() where app_id = $1', [appId, now]);
+    const days = historyDays();
+    if (days) await c.query(`delete from meta.component_change where app_id = $1 and changed_at < now() - make_interval(days => $2)`, [appId, days]);
+    return changes.length;
+  };
+  if (db) {
+    await db.query('savepoint history');
+    try {
+      const n = await run(db);
+      await db.query('release savepoint history');
+      return n;
+    } catch (e) {
+      await db.query('rollback to savepoint history');
+      throw e;
+    }
+  }
+  return owner.tx(run);
+}
+
+/** SHA-256 of a set of files (paths and contents, in path order). */
+function hashFiles(files: [string, Buffer][]) {
+  const h = createHash('sha256');
+  for (const [p, b] of files.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) h.update(p).update('\0').update(b).update('\0');
+  return h.digest('hex');
+}
+
+/** The application checksum of an export (the same definition gives the same checksum on any installation). */
+export const appChecksum = (doc: Doc) => hashFiles([...appFiles(doc)]);
+
+/** A checksum per page: page number → the hash of the page's files. */
+export function pageChecksums(doc: Doc): Map<number, string> {
+  const byPage = new Map<number, [string, Buffer][]>();
+  for (const [id, files] of components(appFiles(doc))) {
+    const page = id.startsWith('pages/') ? describe(id).page : null;
+    if (page === null) continue;
+    if (!byPage.has(page)) byPage.set(page, []);
+    byPage.get(page)!.push(...files);
+  }
+  return new Map([...byPage].sort(([a], [b]) => a - b).map(([p, f]) => [p, hashFiles(f)]));
+}
+
+/** A short form for display (the first 16 hex digits). */
+export const shortSum = (sum: string) => sum.slice(0, 16);