pgkiln 0.69.0 → 0.71.0

package/src/builder/create-page.ts

@@ -0,0 +1,259 @@
+import type { FastifyInstance } from 'fastify';
+import { owner } from '../db.ts';
+import { html, raw, type Raw } from '../html.ts';
+import { icon } from '../icons.ts';
+import { featureStates } from './features.ts';
+import { appOr404 } from './forms.ts';
+import { appHeader, back, BASE, csrf, developer, flash, input, region, select, send, shell, type Req } from './ui.ts';
+import { NO_TABLE, PAGE_KINDS, wizardTables } from './wizards.ts';
+
+// (sprint 137, AP-3) Create Page like APEX's: a grid of page types with small previews (tab Component), the
+// features (tab Feature, features.ts) and Create page as copy (tab Copy), at /builder/apps/:id/create-page.
+// A type that needs a table asks for one first (?type=…), then goes to the options step (wizards.ts); the
+// others go to the options step at once. Blank page and Create pages with AI stay as they were. Plain links and
+// forms: no JavaScript needed. The previews are inline SVG drawn with classes (public/builder.css), no styles.
+
+/** The grid's order (APEX's names), each with the step it starts with. */
+const GRID: { key: string; label: string; help: string; table: boolean }[] = [
+  { key: 'blank', label: 'Blank page', help: 'An empty page to build in the Page Designer.', table: false },
+  ...['calendar', 'cards', 'chart', 'comments', 'content_row', 'dashboard', 'data_load', 'facets', 'form', 'grid', 'report', 'map',
+    'master_detail', 'media_list', 'report_form', 'search', 'smart_filters', 'timeline', 'tree', 'tasks', 'wizard', 'workflows'].map((k) => {
+    const d = PAGE_KINDS.find((x) => x[0] === k)!;
+    return { key: k, label: d[1], help: d[2], table: !NO_TABLE.has(k) };
+  }),
+];
+
+// ---------------------------------------------------------------- previews (80 × 50, inline SVG, classes only)
+const rect = (x: number, y: number, w: number, h: number, cls = 'pv-line', rx = 1.5) => `<rect class="${cls}" x="${x}" y="${y}" width="${w}" height="${h}" rx="${rx}"/>`;
+const circle = (cx: number, cy: number, r: number, cls = 'pv-soft') => `<circle class="${cls}" cx="${cx}" cy="${cy}" r="${r}"/>`;
+const rows = (y0: number, n: number, x = 6, w = 68, gap = 7) => Array.from({ length: n }, (_, i) => rect(x, y0 + i * gap, w, 3)).join('');
+const table = `${rect(6, 6, 68, 6, 'pv-soft')}${rows(16, 5)}`;
+const listRows = (n: number, avatar: boolean, right = false) => Array.from({ length: n }, (_, i) => {
+  const y = 7 + i * 13;
+  return `${avatar ? circle(11, y + 4, 4.5) : ''}${rect(avatar ? 20 : 6, y, 30, 3.5, 'pv-acc')}${rect(avatar ? 20 : 6, y + 5.5, 40, 2.5)}${right ? rect(62, y + 1, 12, 5, 'pv-soft', 2.5) : ''}`;
+}).join('');
+const PREVIEWS: Record<string, string> = {
+  blank: rect(6, 6, 68, 38, 'pv-frame', 3),
+  calendar: `${rect(6, 6, 68, 6, 'pv-soft')}${Array.from({ length: 15 }, (_, i) => rect(6 + (i % 5) * 14, 15 + Math.floor(i / 5) * 10, 12, 8, i === 7 ? 'pv-acc' : 'pv-line')).join('')}`,
+  cards: Array.from({ length: 4 }, (_, i) => `${rect(6 + (i % 2) * 35, 6 + Math.floor(i / 2) * 20, 33, 18, 'pv-frame', 2)}${rect(9 + (i % 2) * 35, 9 + Math.floor(i / 2) * 20, 18, 3, 'pv-acc')}${rect(9 + (i % 2) * 35, 15 + Math.floor(i / 2) * 20, 24, 2.5)}`).join(''),
+  chart: [14, 26, 20, 32, 10].map((h, i) => rect(10 + i * 13, 44 - h, 9, h, i === 3 ? 'pv-acc' : 'pv-soft', 1)).join('') + rect(6, 44, 68, 1.5),
+  comments: listRows(3, true),
+  content_row: listRows(3, true, true),
+  dashboard: Array.from({ length: 4 }, (_, i) => {
+    const x = 6 + (i % 2) * 35;
+    const y = 6 + Math.floor(i / 2) * 20;
+    return `${rect(x, y, 33, 18, 'pv-frame', 2)}${[6, 10, 7, 12].map((h, j) => rect(x + 4 + j * 7, y + 15 - h, 5, h, j === i ? 'pv-acc' : 'pv-soft', 0.8)).join('')}`;
+  }).join(''),
+  data_load: `${rect(18, 26, 44, 18, 'pv-frame', 2)}${rect(37, 10, 6, 18, 'pv-acc', 1)}<path class="pv-acc" d="M30 14 L40 4 L50 14 Z"/>${rect(24, 32, 32, 2.5)}${rect(24, 37, 24, 2.5)}`,
+  facets: `${rect(6, 6, 18, 38, 'pv-soft', 2)}${[10, 16, 22, 28].map((y) => rect(9, y, 12, 2.5)).join('')}${rect(28, 6, 46, 6, 'pv-soft')}${rows(16, 5, 28, 46)}`,
+  form: [8, 20, 32].map((y) => `${rect(8, y, 16, 3)}${rect(28, y - 2, 44, 7, 'pv-frame', 1.5)}`).join('') + rect(56, 42, 16, 5, 'pv-acc', 2),
+  grid: `${table}${[25, 45].map((x) => rect(x, 13, 0.8, 34, 'pv-line', 0)).join('')}${rect(25.8, 22, 19.2, 6, 'pv-frame', 0)}`,
+  report: `${rect(6, 3, 30, 5, 'pv-frame', 1.5)}${rect(6, 11, 68, 6, 'pv-soft')}${rows(21, 4)}`,
+  map: `${rect(6, 6, 68, 38, 'pv-soft', 3)}<path class="pv-stroke" d="M6 30 C 24 20, 40 40, 74 18"/>${circle(48, 20, 5, 'pv-acc')}${circle(48, 20, 2, 'pv-bg')}`,
+  master_detail: `${rect(6, 4, 68, 5, 'pv-soft')}${rows(12, 2)}${rect(6, 12, 68, 4, 'pv-acc')}${rect(6, 28, 68, 5, 'pv-soft')}${rows(36, 2)}`,
+  media_list: Array.from({ length: 3 }, (_, i) => `${rect(6, 6 + i * 13, 9, 9, 'pv-soft', 2)}${rect(19, 7 + i * 13, 30, 3.5, 'pv-acc')}${rect(19, 12.5 + i * 13, 40, 2.5)}${rect(62, 8 + i * 13, 12, 5, 'pv-soft', 2.5)}`).join(''),
+  report_form: `${rect(6, 6, 42, 6, 'pv-soft')}${rows(16, 4, 6, 42)}${rect(52, 10, 22, 32, 'pv-frame', 2)}${[15, 22, 29].map((y) => rect(55, y, 16, 3)).join('')}${rect(59, 35, 12, 4, 'pv-acc', 1.5)}`,
+  search: `${rect(6, 6, 68, 8, 'pv-frame', 4)}${circle(12, 10, 2.2, 'pv-acc')}${[18, 30].map((y) => `${rect(6, y, 26, 3.5, 'pv-acc')}${rect(6, y + 5, 60, 2.5)}`).join('')}`,
+  smart_filters: `${rect(6, 3, 68, 7, 'pv-frame', 3.5)}${rect(8, 12, 16, 4, 'pv-soft', 2)}${rect(26, 12, 14, 4, 'pv-soft', 2)}${rect(6, 19, 68, 5, 'pv-soft')}${rows(27, 3)}`,
+  timeline: `${rect(13, 4, 1.5, 42, 'pv-line', 0)}${[8, 22, 36].map((y, i) => `${circle(13.75, y, 3, i === 0 ? 'pv-acc' : 'pv-soft')}${rect(21, y - 3, 28, 3, 'pv-acc')}${rect(21, y + 2, 46, 2.5)}`).join('')}`,
+  tree: `${rect(6, 5, 24, 4, 'pv-acc')}<path class="pv-stroke" d="M10 9 V38 M10 18 H18 M10 28 H18 M10 38 H18 M22 32 V38 M22 38 H28"/>${rect(20, 16, 22, 3.5)}${rect(20, 26, 26, 3.5)}${rect(30, 36, 20, 3.5)}`,
+  tasks: [8, 20, 32].map((y, i) => `${rect(8, y, 7, 7, i === 0 ? 'pv-acc' : 'pv-frame', 1.5)}${rect(19, y, 34, 3)}${rect(19, y + 4.5, 22, 2.5)}${rect(60, y + 1, 14, 5, 'pv-soft', 2.5)}`).join(''),
+  wizard: `<path class="pv-stroke" d="M16 9 H64"/>${[16, 40, 64].map((x, i) => circle(x, 9, 4, i === 0 ? 'pv-acc' : 'pv-soft')).join('')}${[20, 30].map((y) => `${rect(10, y, 14, 3)}${rect(28, y - 2, 42, 7, 'pv-frame', 1.5)}`).join('')}${rect(54, 41, 16, 5, 'pv-acc', 2)}`,
+  workflows: `${rect(4, 19, 18, 12, 'pv-acc', 2)}${rect(31, 8, 18, 12, 'pv-soft', 2)}${rect(31, 30, 18, 12, 'pv-soft', 2)}${rect(58, 19, 18, 12, 'pv-frame', 2)}<path class="pv-stroke" d="M22 25 L31 14 M22 25 L31 36 M49 14 L58 25 M49 36 L58 25"/>`,
+  ai: `<path class="pv-acc" d="M40 6 L44 20 L58 25 L44 30 L40 44 L36 30 L22 25 L36 20 Z"/>${circle(62, 12, 3, 'pv-soft')}${circle(18, 38, 2.5, 'pv-soft')}`,
+};
+/** A page type's small picture, decorative (the label says what it is). */
+export const preview = (key: string): Raw =>
+  raw(`<svg class="cp-svg" viewBox="0 0 80 50" aria-hidden="true" focusable="false">${PREVIEWS[key] ?? PREVIEWS.blank}</svg>`);
+
+const TABS: [string, string][] = [['component', 'Component'], ['feature', 'Feature'], ['copy', 'Copy']];
+
+export async function createPageRoutes(app: FastifyInstance) {
+  app.get(`${BASE}/apps/:id/create-page`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const a = await appOr404(req.params.id);
+    if (!a) return reply.code(404).send('Not found');
+    const q = req.query as Record<string, string | undefined>;
+    const tab = TABS.some(([t]) => t === q.tab) ? q.tab! : 'component';
+    const type = GRID.find((g) => g.key === q.type);
+    const crumbs: [string, string?][] = [['App Builder', BASE], [a.name, `${BASE}/apps/${a.id}`], ['Create page', type ? `${BASE}/apps/${a.id}/create-page` : undefined]];
+    const nextPage = async () => {
+      const used = new Set((await owner.query('select page_no from meta.page where app_id = $1', [a.id])).rows.map((r) => r.page_no as number));
+      let n = Math.max(0, ...[...used].filter((x) => x < 9000)) + 1;
+      while (used.has(n)) n++;
+      return n;
+    };
+
+    // a page type that needs a table: choose it first (APEX: the data source step)
+    if (type) {
+      let body: Raw;
+      if (type.key === 'blank') {
+        body = html`<form method="post" action="${BASE}/apps/${a.id}/pages">${csrf(s)}
+            <div class="form-grid">
+              ${input('page_no', 'Page number', await nextPage(), { type: 'number', required: true })}
+              ${input('name', 'Name', '', { required: true })}
+              ${select('mode', 'Page mode', 'normal', [['normal', 'Normal page'], ['modal', 'Modal dialog']])}
+              ${input('parent_page', 'Breadcrumb parent', a.home_page ?? '', { type: 'number' })}
+            </div>
+            <div class="buttons"><a class="btn" href="${BASE}/apps/${a.id}/create-page">Back</a><button class="btn btn-hot">Create page</button></div>
+          </form>`;
+      } else {
+        const tables = await wizardTables(a.db_role);
+        body = html`<form method="get" action="${BASE}/apps/${a.id}/wizard">
+            <input type="hidden" name="kind" value="${type.key}">
+            <div class="form-grid">
+              ${select('table', 'Table or view', '', tables.map((t): [string, string] => [t.t, t.access ? t.t : `${t.t} (no access for ${a.db_role})`]),
+                'The next step proposes the columns, keys and foreign keys from the database catalog.')}
+            </div>
+            <div class="buttons"><a class="btn" href="${BASE}/apps/${a.id}/create-page">Back</a><button class="btn btn-hot">Next</button></div>
+          </form>`;
+      }
+      const main = html`${appHeader(a, 'pages', s)}
+        ${region(type.label, html`<div class="cp-step"><span class="cp-preview cp-preview-lg">${preview(type.key)}</span><p class="muted">${type.help}</p></div>${body}`)}`;
+      return send(reply, s, shell(s, `Create page · ${a.name}`, [...crumbs, [type.label]], main));
+    }
+
+    const tabs = html`<nav class="gal-tabs segmented cp-tabs" aria-label="Create page">${TABS.map(([t, l]) =>
+      html`<a href="${BASE}/apps/${a.id}/create-page?tab=${t}"${t === tab ? raw(' aria-current="page"') : ''}>${l}</a>`)}</nav>`;
+    let body: Raw;
+    if (tab === 'component') {
+      const href = (g: (typeof GRID)[number]) =>
+        g.key !== 'blank' && !g.table ? `${BASE}/apps/${a.id}/wizard?kind=${g.key}` : `${BASE}/apps/${a.id}/create-page?type=${g.key}`;
+      body = html`<p class="muted u-mt0">Choose a page type. Types on a table ask for it next; every type proposes its settings and opens the new page in the Page Designer.</p>
+        <ul class="cp-grid">${GRID.map((g) => html`<li><a class="cp-type" href="${href(g)}"><span class="cp-preview">${preview(g.key)}</span><b>${g.label}</b><small>${g.help}</small></a></li>`)}
+          <li><a class="cp-type" href="${BASE}/apps/${a.id}/ai-pages"><span class="cp-preview">${preview('ai')}</span><b>Create pages with AI</b><small>Describe the pages in your own words; check the proposals before they are made.</small></a></li></ul>`;
+    } else if (tab === 'feature') {
+      const states = await featureStates(a.id);
+      body = html`<p class="muted u-mt0">Features add pages and settings to the application. Each lists what it adds before it creates anything; an installed feature is greyed out.</p>
+        <ul class="cp-grid">${states.map(({ f, installed, blocked }) => html`<li><a class="cp-type${installed || blocked ? ' cp-done' : ''}" href="${BASE}/apps/${a.id}/features/${f.key}">
+            <span class="cp-feature-icon">${icon(f.icon)}</span><b>${f.label}</b><small>${f.help}</small>
+            ${installed ? html`<span class="tag">Installed</span>` : blocked ? html`<span class="tag">Not available</span>` : ''}</a></li>`)}</ul>`;
+    } else {
+      body = await copyStep1(a, s.username!);
+    }
+    const main = html`${appHeader(a, 'pages', s)}${region('Create page', html`${tabs}${body}`)}`;
+    return send(reply, s, shell(s, `Create page · ${a.name}`, crumbs, main));
+  });
+
+  // ---------------------------------------------------------------- Create page as copy
+  // step 2 (?from=): the page to copy; step 3 (?from=&page=): number, name and the shared components; POST: copy
+  app.get(`${BASE}/apps/:id/copy-page`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const a = await appOr404(req.params.id);
+    if (!a) return reply.code(404).send('Not found');
+    const q = req.query as Record<string, string | undefined>;
+    const from = await sourceApp(a.id, q.from);
+    if (!from) {
+      flash(s, 'Choose an application of this workspace.', 'error');
+      return back(reply, s, `${BASE}/apps/${a.id}/create-page?tab=copy`);
+    }
+    const pages = (await owner.query<{ id: number; page_no: number; name: string }>('select id, page_no, name from meta.page where app_id = $1 order by page_no', [from.id])).rows;
+    const page = pages.find((p) => String(p.page_no) === q.page);
+    const crumbs: [string, string?][] = [['App Builder', BASE], [a.name, `${BASE}/apps/${a.id}`], ['Create page', `${BASE}/apps/${a.id}/create-page?tab=copy`], ['Copy']];
+    let body: Raw;
+    if (!page) {
+      body = html`<form method="get" action="${BASE}/apps/${a.id}/copy-page"><input type="hidden" name="from" value="${from.id}">
+          <div class="form-grid">${select('page', `Page of ${from.name}`, '', pages.map((p): [string, string] => [String(p.page_no), `${p.page_no} ${p.name}`]))}</div>
+          <div class="buttons"><a class="btn" href="${BASE}/apps/${a.id}/create-page?tab=copy">Back</a><button class="btn btn-hot">Next</button></div></form>`;
+    } else {
+      const refs = (await owner.query<{ kind: string; name: string; in_target: boolean }>('select * from meta.page_shared_refs($1, $2)', [page.id, a.id])).rows;
+      const used = new Set((await owner.query('select page_no from meta.page where app_id = $1', [a.id])).rows.map((r) => r.page_no as number));
+      let no = used.has(page.page_no) ? Math.max(0, ...[...used].filter((x) => x < 9000)) + 1 : page.page_no;
+      while (used.has(no)) no++;
+      const same = from.id === a.id;
+      const options = async (kind: string) => (await owner.query<{ n: string }>(SHARED_NAMES[kind], [a.id])).rows.map((r) => r.n);
+      const mapRows = await Promise.all(refs.map(async (r) => {
+        const names = await options(r.kind);
+        const opts: [string, string][] = [...(same || r.in_target ? [] : [['', 'Copy it into this application'] as [string, string]]), ...names.map((n): [string, string] => [n, `Use ${n}`])];
+        return html`<tr><td>${KIND_LABELS[r.kind] ?? r.kind}</td><td><code>${r.name}</code></td><td>
+          <select name="map:${r.kind}:${r.name}" aria-label="${KIND_LABELS[r.kind] ?? r.kind} ${r.name}">${opts.map(([v, l]) => html`<option value="${v}"${v === (r.in_target || same ? r.name : '') ? raw(' selected') : ''}>${l}</option>`)}</select></td></tr>`;
+      }));
+      body = html`<p class="muted u-mt0">Page ${page.page_no} <b>${page.name}</b> of ${from.name}: its regions, items, buttons, dynamic actions, validations, processes, computations and branches. Items named P${page.page_no}_… are renamed to the new number, also where the page's code refers to them.</p>
+        <form method="post" action="${BASE}/apps/${a.id}/copy-page">${csrf(s)}
+          <input type="hidden" name="from" value="${from.id}"><input type="hidden" name="page" value="${page.page_no}">
+          <div class="form-grid">
+            ${input('new_page', 'New page number', no, { type: 'number', required: true })}
+            ${input('name', 'Name', page.name, { required: true })}
+          </div>
+          ${refs.length
+            ? html`<h3>Shared components</h3><p class="muted small">The page refers to these by name. ${same ? 'In the same application they stay as they are, or point to another of the same kind.' : 'Use one of this application\'s, or copy it from the other application.'}</p>
+              <div class="table-wrap"><table class="report"><thead><tr><th>Kind</th><th>Name</th><th>In this application</th></tr></thead><tbody>${mapRows}</tbody></table></div>`
+            : html`<p class="muted">The page uses no shared components.</p>`}
+          ${same ? '' : html`<p class="muted small">Its SQL runs as this application's database role <code>${a.db_role ?? '(none)'}</code>: grant it what ${from.name}'s role may read and change.</p>`}
+          <div class="buttons"><a class="btn" href="${BASE}/apps/${a.id}/copy-page?from=${from.id}">Back</a><button class="btn btn-hot">Copy page</button></div>
+        </form>`;
+    }
+    const main = html`${appHeader(a, 'pages', s)}${region('Create page as copy', body)}`;
+    return send(reply, s, shell(s, `Copy page · ${a.name}`, crumbs, main));
+  });
+
+  app.post(`${BASE}/apps/:id/copy-page`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const a = await appOr404(req.params.id);
+    if (!a) return reply.code(404).send('Not found');
+    const b = (req.body ?? {}) as Record<string, unknown>;
+    const from = await sourceApp(a.id, String(b.from ?? ''));
+    const retry = `${BASE}/apps/${a.id}/copy-page?from=${encodeURIComponent(String(b.from ?? ''))}&page=${encodeURIComponent(String(b.page ?? ''))}`;
+    if (!from) {
+      flash(s, 'Choose an application of this workspace.', 'error');
+      return back(reply, s, `${BASE}/apps/${a.id}/create-page?tab=copy`);
+    }
+    try {
+      const page = /^\d{1,6}$/.test(String(b.page ?? '')) ? Number(b.page) : NaN;
+      const no = /^\d{1,6}$/.test(String(b.new_page ?? '').trim()) ? Number(String(b.new_page).trim()) : NaN;
+      if (!(no >= 1)) throw new Error('Enter a page number.');
+      const name = String(b.name ?? '').trim().slice(0, 200);
+      if (!name) throw new Error('Enter a name.');
+      // map:<kind>:<NAME> → a name of the target's (empty: copy); only known kinds pass
+      const map: Record<string, string> = {};
+      for (const [k, v] of Object.entries(b)) {
+        const m = /^map:([a-z_]+):(.{1,100})$/.exec(k);
+        if (m && Object.hasOwn(SHARED_NAMES, m[1]) && typeof v === 'string') map[`${m[1]}:${m[2]}`] = v.slice(0, 100);
+      }
+      const id = await owner.tx(async (c) => (await c.query('select meta.copy_page($1, $2, $3, $4, $5, $6::jsonb) as id', [from.id, page, a.id, no, name, JSON.stringify(map)])).rows[0].id as number);
+      flash(s, `Page ${no} "${name}" created as a copy of page ${page}${from.id === a.id ? '' : ` of ${from.name}`}.`);
+      return back(reply, s, `${BASE}/pages/${id}`);
+    } catch (e) {
+      flash(s, (e as Error).message, 'error');
+      return back(reply, s, retry);
+    }
+  });
+}
+
+const KIND_LABELS: Record<string, string> = {
+  authz_scheme: 'Authorization scheme', build_option: 'Build option', lov: 'List of values', list: 'List',
+  template_component: 'Template component', search_config: 'Search configuration', data_load_def: 'Data load definition',
+};
+/** The target application's names of each kind (the choices of the mapping). */
+const SHARED_NAMES: Record<string, string> = {
+  authz_scheme: 'select name as n from meta.authz_scheme where app_id = $1 order by 1',
+  build_option: 'select name as n from meta.build_option where app_id = $1 order by 1',
+  lov: 'select name as n from meta.lov where app_id = $1 order by 1',
+  list: 'select name as n from meta.list where app_id = $1 order by 1',
+  template_component: 'select static_id as n from meta.template_component where app_id = $1 order by 1',
+  search_config: 'select name as n from meta.search_config where app_id = $1 order by 1',
+  data_load_def: 'select name as n from meta.data_load_def where app_id = $1 order by 1',
+};
+
+/** An application of the same workspace as the target (the target itself too), or null. */
+async function sourceApp(targetId: number, from: string | undefined) {
+  if (!/^\d{1,9}$/.test(String(from ?? ''))) return null;
+  return (await owner.one<{ id: number; name: string; alias: string }>(
+    'select id, name, alias from meta.app where id = $1 and meta.app_workspace(id) = meta.app_workspace($2)', [from, targetId],
+  )) ?? null;
+}
+
+/** Copy, step 1: the application to copy from (this one first). */
+async function copyStep1(a: { id: number; name: string }, _user: string): Promise<Raw> {
+  const apps = (await owner.query<{ id: number; name: string; alias: string }>(
+    'select id, name, alias from meta.app where meta.app_workspace(id) = meta.app_workspace($1) order by id <> $1, lower(name)', [a.id],
+  )).rows;
+  return html`<p class="muted u-mt0">Copy a page of this application or another application of the workspace, under a new number and name. The shared components it uses (lists of values, authorization schemes, lists…) are mapped to this application's or copied.</p>
+    <form method="get" action="${BASE}/apps/${a.id}/copy-page">
+      <div class="form-grid">${select('from', 'Copy from application', String(a.id), apps.map((x): [string, string] => [String(x.id), x.id === a.id ? `${x.name} (this application)` : `${x.name} (${x.alias})`]))}</div>
+      <div class="buttons"><button class="btn btn-hot">Next</button></div>
+    </form>`;
+}

package/src/builder/dependencies.ts

@@ -0,0 +1,311 @@
+import type { FastifyInstance } from 'fastify';
+import pg from 'pg';
+import { applyBinds, splitStatements } from '../binds.ts';
+import { owner } from '../db.ts';
+import { html, raw, type Raw } from '../html.ts';
+import { icon } from '../icons.ts';
+import { devDbForApp } from '../workspace-db.ts';
+import { EXPLAINABLE, sqlFields, type SqlShape } from './advisor.ts';
+import { COMPONENTS } from './components.ts';
+import { appEntries, type Entry } from './search.ts';
+import { appHeader, BASE, developer, region, send, shell, type Req } from './ui.ts';
+
+// (sprint 138, AP-5) App Builder → Utilities → Database object dependencies
+// (APEX: Database Object Dependencies). Every piece of SQL the Advisor plans
+// (region sources, lists of values, conditions, processes, …) and the tables of
+// form and grid regions are parsed as the application's database role into a
+// temporary SQL-standard function (CREATE FUNCTION … BEGIN ATOMIC), whose
+// dependencies PostgreSQL records in pg_depend: the tables, views, sequences
+// and functions the statement uses, resolved with the role's search path.
+// Nothing runs; the transaction is rolled back. A statement that names an
+// object that doesn't exist is reported as a missing object (in red), and the
+// role's privileges are compared with what the statements need (SELECT for
+// queries, INSERT / UPDATE / DELETE for the target of a DML statement, USAGE
+// on sequences, EXECUTE on functions). PL/pgSQL blocks (DO) can't be parsed this
+// way and are listed as not scanned.
+
+export type ObjKind = 'table' | 'view' | 'matview' | 'sequence' | 'foreign table' | 'function' | 'procedure' | 'relation';
+
+export interface Use {
+  entry: Entry | null;
+  field: string;
+}
+
+export interface DepObject {
+  key: string;
+  kind: ObjKind;
+  schema: string;
+  name: string;
+  /** schema-qualified display name (functions with their argument types) */
+  display: string;
+  /** the Object Browser's reference (regclass / regprocedure text), null for a missing object */
+  ref: string | null;
+  missing: boolean;
+  /** privileges the statements need that the role doesn't have */
+  lacking: string[];
+  /** the role's privileges on the object */
+  privileges: string[];
+  usedBy: Use[];
+}
+
+export interface Dependencies {
+  objects: DepObject[];
+  role: string | null;
+  scanned: number;
+  unscanned: (Use & { message: string })[];
+}
+
+interface Fragment extends Use {
+  sql: string;
+  shape: SqlShape | 'relation';
+}
+
+const SYSTEM = new Set(['pg_catalog', 'information_schema', 'meta', 'pg_toast']);
+
+/** Every piece of SQL of an application, and the tables of its form and grid regions. */
+async function fragments(appId: number): Promise<Fragment[]> {
+  const entries = await appEntries(appId);
+  const byKey = new Map(entries.map((e) => [`${e.kind}-${e.id}`, e]));
+  const out: Fragment[] = [];
+  for (const [kind, spec] of Object.entries(COMPONENTS)) {
+    const rows = spec.scope === 'page'
+      ? (await owner.query(`select t.* from ${spec.table} t join meta.page p on p.id = t.page_id where p.app_id = $1`, [appId])).rows
+      : (await owner.query(`select * from ${spec.table} where app_id = $1`, [appId])).rows;
+    for (const row of rows) {
+      const entry = byKey.get(`${kind}-${row.id}`) ?? null;
+      const label = (name: string) => spec.fields.find((x) => x.name === name)?.label ?? name;
+      for (const f of sqlFields(kind, row)) if (f.shape !== 'regex' && typeof row[f.name] === 'string' && row[f.name].trim()) out.push({ entry, field: label(f.name), sql: row[f.name], shape: f.shape });
+      if (kind === 'region' && (row.type === 'form' || row.type === 'grid') && typeof row.table_name === 'string' && row.table_name.trim() && !row.rest_source)
+        out.push({ entry, field: label('table_name'), sql: row.table_name.trim(), shape: 'relation' });
+      if (kind === 'region' && row.type === 'map')
+        for (const l of Array.isArray(row.config?.layers) ? row.config.layers : [])
+          if (typeof l?.source === 'string' && l.source.trim()) out.push({ entry, field: `Layer "${typeof l.name === 'string' ? l.name : ''}" query`, sql: l.source, shape: 'select' });
+      if (kind === 'search_config' && row.source_type !== 'list' && typeof row.source === 'string' && row.source.trim())
+        out.push({ entry, field: 'Source', sql: row.source.trim(), shape: row.source_type === 'table' ? 'relation' : 'select' });
+      if (kind === 'rest_module')
+        for (const h of Array.isArray(row.handlers) ? row.handlers : [])
+          if (typeof h?.source === 'string' && h.source.trim() && h.type !== 'plpgsql') out.push({ entry, field: `${h.method} ${h.path}`, sql: h.source, shape: h.type === 'sql' ? 'statements' : 'select' });
+      if (kind === 'workflow_definition')
+        for (const st of Array.isArray(row.steps) ? row.steps : []) {
+          if (st?.type === 'sql' && typeof st.code === 'string') out.push({ entry, field: `step ${st.name}: code`, sql: st.code, shape: 'statements' });
+          if (st?.type === 'task' && typeof st.owners === 'string' && st.owners.trim()) out.push({ entry, field: `step ${st.name}: owners`, sql: st.owners, shape: 'select' });
+          if (st?.type === 'switch' && Array.isArray(st.cases)) for (const cs of st.cases) if (typeof cs?.when === 'string') out.push({ entry, field: `step ${st.name}: when`, sql: cs.when, shape: 'boolean' });
+        }
+    }
+  }
+  return out;
+}
+
+/** The DML target of a statement (INSERT INTO x, UPDATE x, DELETE FROM x, MERGE INTO x) and the privilege it needs. */
+export function dmlTarget(stmt: string): { name: string; privilege: string } | null {
+  const m = /^\s*(?:with\b[\s\S]*?\)\s*)?(insert\s+into|update|delete\s+from|merge\s+into)\s+((?:"[^"]+"|[A-Za-z_][\w$]*)(?:\s*\.\s*(?:"[^"]+"|[A-Za-z_][\w$]*))?)/i.exec(stmt);
+  if (!m) return null;
+  const verb = m[1].toLowerCase().split(/\s+/)[0];
+  return { name: m[2].replace(/\s+/g, ''), privilege: verb === 'merge' ? 'UPDATE' : verb.toUpperCase() };
+}
+
+/** The statements of a fragment as the body of a BEGIN ATOMIC function, and what can't be parsed that way. */
+export function bodyOf(sql: string, shape: SqlShape | 'relation'): { statements: string[]; skipped: string[] } {
+  const plain = applyBinds(sql.trim().replace(/;+\s*$/, ''), {});
+  if (shape === 'boolean') return { statements: [`select (${plain})::boolean`], skipped: [] };
+  if (shape === 'select') return EXPLAINABLE.test(plain) ? { statements: [plain], skipped: [] } : { statements: [], skipped: ['not a query'] };
+  const statements: string[] = [];
+  const skipped: string[] = [];
+  for (const stmt of splitStatements(plain)) {
+    if (EXPLAINABLE.test(stmt)) statements.push(stmt);
+    else if (stmt.trim()) skipped.push(stmt.trim().split(/\s+/).slice(0, 2).join(' '));
+  }
+  return { statements, skipped };
+}
+
+/** A missing object named by an error message of the parser. */
+export function missingOf(message: string): { kind: ObjKind; name: string } | null {
+  let m = /relation "([^"]+)" does not exist/.exec(message);
+  if (m) return { kind: 'relation', name: m[1] };
+  m = /^(function|procedure) (.+?\)) does not exist/.exec(message);
+  if (m) return { kind: m[1] as ObjKind, name: m[2] };
+  return null;
+}
+
+const RELKINDS: Record<string, ObjKind> = { r: 'table', p: 'table', v: 'view', m: 'matview', S: 'sequence', f: 'foreign table' };
+
+/** Scan an application. */
+export async function appDependencies(appId: number): Promise<Dependencies> {
+  const app = await owner.one<{ db_role: string | null }>('select db_role from meta.app where id = $1', [appId]);
+  if (!app) throw new Error('application not found');
+  const frags = await fragments(appId);
+  const found = new Map<string, { cls: 'pg_class' | 'pg_proc'; oid: number; needs: Set<string>; uses: Use[] }>();
+  const missing = new Map<string, DepObject>();
+  const unscanned: Dependencies['unscanned'] = [];
+  let scanned = 0;
+  const note = (cls: 'pg_class' | 'pg_proc', oid: number, use: Use, need: string | null) => {
+    const k = `${cls}:${oid}`;
+    if (!found.has(k)) found.set(k, { cls, oid, needs: new Set(), uses: [] });
+    const f = found.get(k)!;
+    if (need) f.needs.add(need);
+    if (!f.uses.some((u) => u.entry === use.entry && u.field === use.field)) f.uses.push(use);
+  };
+  const own = await devDbForApp(appId);
+  const c = await own.pool.connect();
+  try {
+    await c.query('begin');
+    await c.query(`set local statement_timeout = '5s'`);
+    await c.query(`select set_config('pgkiln.app_id', $1, true)`, [String(appId)]);
+    if (app.db_role) await c.query(`set local role ${pg.escapeIdentifier(app.db_role)}`);
+    for (const f of frags) {
+      const use: Use = { entry: f.entry, field: f.field };
+      await c.query('savepoint deps');
+      try {
+        if (f.shape === 'relation') {
+          scanned++;
+          const r = (await c.query<{ oid: number | null }>('select to_regclass($1)::oid::int as oid', [f.sql])).rows[0];
+          if (r?.oid) note('pg_class', r.oid, use, 'SELECT');
+          else addMissing(missing, { kind: 'relation', name: f.sql }, use);
+          continue;
+        }
+        const { statements, skipped } = bodyOf(f.sql, f.shape);
+        if (skipped.length) unscanned.push({ ...use, message: `Not scanned (only SELECT, INSERT, UPDATE, DELETE and MERGE are parsed): ${skipped.join(', ')}` });
+        if (!statements.length) continue;
+        scanned++;
+        // the extended protocol takes exactly one statement: SQL that ends the function early (…; end; drop …) is refused
+        await c.query({ text: `create function pg_temp.__pgkiln_deps() returns void language sql begin atomic ${statements.join(';\n')}; end`, queryMode: 'extended' } as pg.QueryConfig);
+        const deps = (await c.query<{ cls: 'pg_class' | 'pg_proc'; oid: number }>(
+          `select distinct d.refclassid::regclass::text as cls, d.refobjid::int as oid from pg_depend d
+            where d.classid = 'pg_proc'::regclass and d.objid = 'pg_temp.__pgkiln_deps()'::regprocedure
+              and d.refclassid in ('pg_class'::regclass, 'pg_proc'::regclass)`)).rows;
+        // what the statements need: the target of a DML statement its verb's privilege, everything else SELECT
+        const targets = new Map<number, string>();
+        for (const st of statements) {
+          const t = dmlTarget(st);
+          if (!t) continue;
+          const oid = (await c.query<{ oid: number | null }>('select to_regclass($1)::oid::int as oid', [t.name])).rows[0]?.oid;
+          if (oid) targets.set(oid, t.privilege);
+        }
+        for (const d of deps) note(d.cls, d.oid, use, d.cls === 'pg_proc' ? 'EXECUTE' : (targets.get(d.oid) ?? 'SELECT'));
+      } catch (e) {
+        const message = (e as Error).message;
+        const m = missingOf(message);
+        if (m) addMissing(missing, m, use);
+        else unscanned.push({ ...use, message });
+      } finally {
+        await c.query('rollback to savepoint deps');
+      }
+    }
+  } finally {
+    await c.query('rollback').catch(() => {});
+    c.release();
+  }
+
+  // the objects, their kinds and the role's privileges (as the owner: the catalog)
+  const objects: DepObject[] = [...missing.values()];
+  const rels = [...found.values()].filter((f) => f.cls === 'pg_class');
+  const procs = [...found.values()].filter((f) => f.cls === 'pg_proc');
+  const role = app.db_role;
+  if (rels.length) {
+    const rows = (await owner.query(
+      `select c.oid::int as oid, c.relkind::text as relkind, n.nspname as schema, c.relname as name, c.oid::regclass::text as ref,
+              array_remove(array[
+                case when $2::text is null or has_table_privilege($2, c.oid, 'SELECT') then 'SELECT' end,
+                case when c.relkind <> 'S' and ($2::text is null or has_table_privilege($2, c.oid, 'INSERT')) then 'INSERT' end,
+                case when c.relkind <> 'S' and ($2::text is null or has_table_privilege($2, c.oid, 'UPDATE')) then 'UPDATE' end,
+                case when c.relkind <> 'S' and ($2::text is null or has_table_privilege($2, c.oid, 'DELETE')) then 'DELETE' end,
+                case when c.relkind = 'S' and ($2::text is null or has_sequence_privilege($2, c.oid, 'USAGE')) then 'USAGE' end], null) as privileges,
+              $2::text is null or has_schema_privilege($2, n.oid, 'USAGE') as schema_usage
+         from pg_class c join pg_namespace n on n.oid = c.relnamespace where c.oid = any ($1::oid[])`,
+      [rels.map((r) => r.oid), role])).rows;
+    for (const r of rows) {
+      if (SYSTEM.has(r.schema)) continue;
+      const f = found.get(`pg_class:${r.oid}`)!;
+      const kind = RELKINDS[r.relkind] ?? 'relation';
+      // a sequence used by nextval() needs USAGE (or UPDATE); one only read, SELECT
+      const needs = kind === 'sequence' ? ['USAGE'] : [...f.needs];
+      const lacking = [...(r.schema_usage ? [] : [`USAGE on schema ${r.schema}`]), ...needs.filter((p) => !r.privileges.includes(p))];
+      objects.push({ key: `pg_class:${r.oid}`, kind, schema: r.schema, name: r.name, display: `${r.schema}.${r.name}`, ref: r.ref, missing: false, lacking, privileges: r.privileges, usedBy: f.uses });
+    }
+  }
+  if (procs.length) {
+    const rows = (await owner.query(
+      `select p.oid::int as oid, p.prokind::text as prokind, n.nspname as schema, p.proname as name, p.oid::regprocedure::text as ref,
+              pg_get_function_identity_arguments(p.oid) as args,
+              $2::text is null or has_function_privilege($2, p.oid, 'EXECUTE') as exec,
+              $2::text is null or has_schema_privilege($2, n.oid, 'USAGE') as schema_usage
+         from pg_proc p join pg_namespace n on n.oid = p.pronamespace where p.oid = any ($1::oid[])`,
+      [procs.map((r) => r.oid), role])).rows;
+    for (const r of rows) {
+      if (SYSTEM.has(r.schema)) continue;
+      const f = found.get(`pg_proc:${r.oid}`)!;
+      const lacking = [...(r.schema_usage ? [] : [`USAGE on schema ${r.schema}`]), ...(r.exec ? [] : ['EXECUTE'])];
+      objects.push({ key: `pg_proc:${r.oid}`, kind: r.prokind === 'p' ? 'procedure' : 'function', schema: r.schema, name: r.name, display: `${r.schema}.${r.name}(${r.args})`, ref: r.ref, missing: false, lacking, privileges: r.exec ? ['EXECUTE'] : [], usedBy: f.uses });
+    }
+  }
+  const rank = (o: DepObject) => (o.missing ? 0 : o.lacking.length ? 1 : 2);
+  objects.sort((a, b) => rank(a) - rank(b) || (a.display < b.display ? -1 : a.display > b.display ? 1 : 0));
+  return { objects, role, scanned, unscanned };
+}
+
+function addMissing(missing: Map<string, DepObject>, m: { kind: ObjKind; name: string }, use: Use) {
+  const key = `missing:${m.kind}:${m.name}`;
+  if (!missing.has(key)) {
+    const dot = m.name.indexOf('.');
+    missing.set(key, { key, kind: m.kind, schema: dot > 0 ? m.name.slice(0, dot) : '', name: dot > 0 ? m.name.slice(dot + 1) : m.name, display: m.name, ref: null, missing: true, lacking: [], privileges: [], usedBy: [] });
+  }
+  const o = missing.get(key)!;
+  if (!o.usedBy.some((u) => u.entry === use.entry && u.field === use.field)) o.usedBy.push(use);
+}
+
+const OB_KIND: Partial<Record<ObjKind, string>> = { table: 'table', view: 'view', matview: 'matview', sequence: 'sequence', function: 'function', procedure: 'procedure' };
+const KIND_ICON: Record<ObjKind, string> = { table: 'table', view: 'layers', matview: 'layers', sequence: 'hash', 'foreign table': 'table', function: 'code', procedure: 'code', relation: 'table' };
+
+/** The Object Browser's address of an object (null: it has no page there). */
+export const objectUrl = (o: Pick<DepObject, 'kind' | 'schema' | 'ref'>) =>
+  o.ref && OB_KIND[o.kind] ? `${BASE}/sql/objects?${new URLSearchParams({ schema: o.schema, k: OB_KIND[o.kind]!, o: o.ref })}` : null;
+
+const useLink = (u: Use) =>
+  u.entry
+    ? html`<li><a href="${u.entry.url}">${icon(u.entry.icon)}<span>${u.entry.kindLabel}: ${u.entry.label}</span></a>${u.entry.pageNo !== null && u.entry.kind !== 'page' ? html` <span class="tag">page ${u.entry.pageNo}</span>` : ''} <span class="muted small">${u.field}</span></li>`
+    : html`<li><span class="muted small">${u.field}</span></li>`;
+
+export async function dependencyRoutes(app: FastifyInstance) {
+  app.get(`${BASE}/apps/:id/utilities/dependencies`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const a = /^\d{1,9}$/.test(req.params.id) ? await owner.one('select * from meta.app where id = $1', [req.params.id]) : undefined;
+    if (!a) return reply.code(404).send('Not found');
+    const deps = await appDependencies(a.id);
+    const filter = String(req.query?.q ?? '').trim().slice(0, 100).toLowerCase();
+    const onlyProblems = req.query?.show === 'problems';
+    const shown = deps.objects.filter((o) => (!filter || o.display.toLowerCase().includes(filter)) && (!onlyProblems || o.missing || o.lacking.length));
+    const missingN = deps.objects.filter((o) => o.missing).length;
+    const grantsN = deps.objects.filter((o) => o.lacking.length).length;
+    const pages = (o: DepObject) => [...new Set(o.usedBy.map((u) => u.entry?.pageNo).filter((p): p is number => p !== null && p !== undefined))].sort((x, y) => x - y);
+    const rows: Raw = shown.length
+      ? html`<div class="table-wrap"><table class="table dep-table report-reflow"><thead><tr><th scope="col">Object</th><th scope="col">Type</th><th scope="col">Status</th><th scope="col">Pages</th><th scope="col">Used by</th></tr></thead>
+        <tbody>${shown.map((o) => {
+          const url = objectUrl(o);
+          const status = o.missing
+            ? html`<span class="tag tag-error">Missing</span>`
+            : o.lacking.length
+              ? html`<span class="tag tag-error">No grant</span> <span class="small dep-missing">${deps.role} lacks ${o.lacking.join(', ')}</span>`
+              : html`<span class="tag tag-success">OK</span> <span class="muted small">${o.privileges.join(', ')}</span>`;
+          return html`<tr${o.missing || o.lacking.length ? raw(' class="dep-problem"') : ''}>
+            <td data-label="Object">${icon(KIND_ICON[o.kind])} ${url ? html`<a href="${url}">${o.display}</a>` : html`<span class="dep-missing">${o.display}</span>`}</td>
+            <td data-label="Type">${o.kind === 'relation' ? 'table or view' : o.kind}</td>
+            <td data-label="Status">${status}</td>
+            <td data-label="Pages">${pages(o).join(', ')}</td>
+            <td data-label="Used by"><details class="dep-uses"><summary>${o.usedBy.length} component${o.usedBy.length === 1 ? '' : 's'}</summary><ul class="dep-list">${o.usedBy.map(useLink)}</ul></details></td>
+          </tr>`;
+        })}</tbody></table></div>`
+      : html`<p class="muted">No objects${filter || onlyProblems ? ' match' : ''}.</p>`;
+    const main = html`${appHeader(a, 'utilities', s)}
+      ${region('Database object dependencies', html`<p class="muted u-mt0">The tables, views, sequences and functions the application's SQL uses (${deps.scanned} statements parsed as the role <code>${deps.role ?? '(the runtime connection)'}</code>; nothing is run), with the components that use them. Missing objects and privileges the role lacks are marked.</p>
+        <p><span class="tag">${deps.objects.length} objects</span> <span class="tag tag-error">${missingN} missing</span> <span class="tag tag-warning">${grantsN} without the grants they need</span></p>
+        <form method="get" class="util-filters" role="search">
+          <div class="field"><label class="label" for="dep-q">Filter</label><input id="dep-q" name="q" type="search" value="${filter}" placeholder="e.g. sales.orders"></div>
+          <div class="field"><label class="label" for="dep-show">Show</label><select id="dep-show" name="show"><option value="">All objects</option><option value="problems"${onlyProblems ? raw(' selected') : ''}>Only problems</option></select></div>
+          <div class="buttons"><button class="btn">${icon('filter')} Filter</button></div>
+        </form>
+        ${rows}`)}
+      ${deps.unscanned.length ? region('Not scanned', html`<ul class="hits findings">${deps.unscanned.map((u) => html`<li class="finding-info">${u.entry ? html`<a href="${u.entry.url}">${icon(u.entry.icon)}<span>${u.entry.kindLabel}: ${u.entry.label}</span></a>` : html`<span>${u.field}</span>`}<span></span><span class="tag tag-info">Note</span><span class="hit-snippet"><b>${u.field}:</b> ${u.message}</span></li>`)}</ul>`) : ''}`;
+    return send(reply, s, shell(s, `Object dependencies · ${a.name}`, [['App Builder', BASE], [a.name, `${BASE}/apps/${a.id}`], ['Utilities', `${BASE}/apps/${a.id}/utilities`], ['Object dependencies']], main));
+  });
+}