pgkiln 0.52.0 → 0.54.0

package/src/builder/data-security.ts

@@ -0,0 +1,182 @@
+import type { FastifyInstance, FastifyReply } from 'fastify';
+import { html, raw, type Raw } from '../html.ts';
+import { icon } from '../icons.ts';
+import { owner } from '../db.ts';
+import { clientIp, logActivity, type Session } from '../session.ts';
+import { back, BASE, csrf, developer, flash, send, shell, workshopTabs, type Body, type Req } from './ui.ts';
+import { SYSTEM_SCHEMAS } from './object-browser.ts';
+import { clearCompletions } from './code-editor.ts';
+import { roleHints, splitRoles } from './users.ts';
+import { currentWorkspace, inWorkspaceSql, usableSchemas, workshopDb } from './workspaces.ts';
+import { joinStatements, recordChanges } from '../changelog.ts';
+import {
+  APP_ROLE_RE, checkSecurity, currentDef, MASK_LABELS, MASKS, maskedColumns, readSecurity, securitySql, sees,
+  type ColumnMask, type SecurityDef, type TableSecurity,
+} from '../datasec.ts';
+
+// (sprint 119, WS-13: data security per table) SQL Workshop › Object Browser › a table › Security: the table's row
+// level security policies, a matrix of database roles × columns (read, update) and masked values per application
+// role, in one form. Preview SQL shows the GRANT / REVOKE statements and the masking view (src/datasec.ts); Apply runs
+// them in one transaction with the workshop's connection and records a change set; Open in the worksheet puts them
+// there. Like Table Properties, the statements are made against the catalog as it is at the time of the post.
+
+/** The workspace's applications with a database role, and the application roles they check. */
+async function workspaceApps(s: Session) {
+  const apps = (await owner.query<{ id: number; alias: string; role: string }>(
+    `select a.id, a.alias, a.db_role as role from meta.app a where a.db_role is not null and ${inWorkspaceSql('a', 1)} order by a.alias`,
+    [currentWorkspace(s)])).rows;
+  const hints = await roleHints(apps.map((a) => a.id));
+  const appRoles = [...new Set([...hints.values()].flat().map((h) => h.role))].filter((r) => APP_ROLE_RE.test(r));
+  return { appDbRoles: apps.map((a) => ({ role: a.role, alias: a.alias })), appRoles };
+}
+
+/** The definition the form posted. Grant rows and columns are matched by index against the catalog's state. */
+function fromForm(b: Body, cur: TableSecurity): SecurityDef {
+  const on = (k: string) => b[k] === 'on';
+  const all = cur.columns.map((c) => c.name);
+  const grants = cur.grants.map((g, i) => ({
+    role: g.role,
+    select: all.filter((_, j) => on(`g.${i}.s.${j}`)),
+    update: all.filter((_, j) => on(`g.${i}.u.${j}`)),
+  }));
+  // the roles the matrix's checkboxes were drawn for (a changed list applies after the next Preview)
+  const shown = splitRoles(String(b.shown_roles ?? ''));
+  const roles = splitRoles(String(b.roles ?? ''));
+  const cols: Record<string, ColumnMask> = {};
+  all.forEach((c, j) => {
+    const mask = MASKS.find((m) => m === b[`m.${j}.mask`]);
+    if (!mask) return;
+    cols[c] = { mask, others: on(`m.${j}.others`), see: shown.filter((r, k) => roles.includes(r) && on(`m.${j}.see.${k}`)) };
+  });
+  return {
+    grants,
+    view: { enabled: on('view'), name: String(b.view_name ?? '').trim(), roles, cols },
+  };
+}
+
+function form(s: Session, cur: TableSecurity, def: SecurityDef, opts: { ref: string; sql: string[]; warnings: string[]; errors: string[]; output: Raw | '' }): Raw {
+  const chk = (x: boolean) => (x ? raw(' checked') : '');
+  const all = cur.columns.map((c) => c.name);
+  const v = def.view;
+  const masked = new Set(maskedColumns(v));
+  const objUrl = `${BASE}/sql/objects?${new URLSearchParams({ schema: cur.schema, k: 'table', o: opts.ref })}`;
+  const policyUrl = `${BASE}/sql/objects/action?${new URLSearchParams({ schema: cur.schema, k: 'table', o: opts.ref, do: 'policy' })}`;
+  const rows = html`<div class="table-wrap"><table class="report ds-table"><caption class="sr-only">Database roles and columns</caption>
+    <thead><tr><th scope="col">Database role</th>${all.map((c) => html`<th scope="col"><code>${c}</code>${masked.has(c) ? html` <span class="badge" title="Masked in ${v.name}">masked</span>` : ''}</th>`)}</tr></thead>
+    <tbody>${cur.grants.length ? def.grants.map((g, i) => {
+      const info = cur.grants[i];
+      return html`<tr><th scope="row"><code>${g.role === 'PUBLIC' ? 'PUBLIC' : g.role}</code>${info.apps.length ? html`<br><small class="muted">runs ${info.apps.join(', ')}</small>` : ''}</th>
+        ${all.map((c, j) => html`<td class="ds-cell"><label class="check"><input type="checkbox" name="g.${i}.s.${j}"${chk(g.select.includes(c))}> read</label>
+          <label class="check"><input type="checkbox" name="g.${i}.u.${j}"${chk(g.update.includes(c))}> update</label></td>`)}</tr>`;
+    }) : html`<tr><td colspan="${all.length + 1}" class="muted">No database role has privileges on this table, and no application of the workspace runs with a database role.</td></tr>`}</tbody></table></div>
+    ${cur.excluded.length ? html`<p class="muted small">Not in the matrix, because column privileges can't restrict them: ${cur.excluded.map((x) => html`<code>${x.role}</code> (${x.why}) `)}</p>` : ''}`;
+  const maskRows = html`<div class="table-wrap"><table class="report ds-table"><caption class="sr-only">Masks per column</caption>
+    <thead><tr><th scope="col">Column</th><th scope="col">Mask</th>${v.roles.map((r) => html`<th scope="col">${r} sees it</th>`)}<th scope="col">Everyone else sees it</th></tr></thead>
+    <tbody>${all.map((c, j) => {
+      const m = v.cols[c];
+      return html`<tr><th scope="row"><code>${c}</code> <small class="muted">${cur.columns[j].type}</small></th>
+        <td><select name="m.${j}.mask" aria-label="Mask of ${c}"><option value="">Not masked</option>${MASKS.map((x) => html`<option value="${x}"${m?.mask === x ? raw(' selected') : ''}>${MASK_LABELS[x]}</option>`)}</select></td>
+        ${v.roles.map((r, k) => html`<td class="ds-c"><input type="checkbox" aria-label="${r} sees ${c}" name="m.${j}.see.${k}"${chk(!!m && sees(v, c, r))}></td>`)}
+        <td class="ds-c"><input type="checkbox" aria-label="Everyone else sees ${c}" name="m.${j}.others"${chk(!!m && m.others)}></td></tr>`;
+    })}</tbody></table></div>`;
+  return html`<form method="post" action="${BASE}/sql/objects/security" class="ds">${csrf(s)}
+    <input type="hidden" name="ref" value="${opts.ref}"><input type="hidden" name="shown_roles" value="${v.roles.join(', ')}">
+    ${opts.errors.length ? html`<div class="alert alert-error" role="alert"><ul>${opts.errors.map((e) => html`<li>${e}</li>`)}</ul></div>` : ''}
+    <section class="ds-section"><h2>${icon('shield')} Rows</h2>
+      <p>Row level security is <strong>${cur.rls ? (cur.forceRls ? 'on, also for the owner' : 'on') : 'off'}</strong>${cur.rls ? '' : ': every role that may read the table reads every row'}.
+        <a href="${BASE}/sql/objects/table?${new URLSearchParams({ o: opts.ref })}">Table Properties</a> switches it on; <a href="${policyUrl}">Add policy</a> writes one in the worksheet.</p>
+      ${cur.policies.length ? html`<div class="table-wrap"><table class="report"><thead><tr><th>Policy</th><th>Command</th><th>Roles</th><th>Using</th><th>With check</th></tr></thead><tbody>
+        ${cur.policies.map((p) => html`<tr><td>${p.name}${p.permissive === 'RESTRICTIVE' ? html` <span class="badge">restrictive</span>` : ''}</td><td>${p.command}</td><td><code>${p.roles}</code></td><td><code>${p.using ?? ''}</code></td><td><code>${p.check ?? ''}</code></td></tr>`)}</tbody></table></div>`
+        : html`<p class="muted">No policies${cur.rls ? ': with row level security on, the roles below read no rows at all' : ''}.</p>`}
+    </section>
+    <section class="ds-section"><h2>${icon('table')} Columns</h2>
+      <p class="muted">What each database role may read and update, per column. A column a role may not read is refused by PostgreSQL whoever sends the query: pages, REST handlers, AutoREST, AI tools, MCP or psql.</p>
+      ${rows}
+    </section>
+    <section class="ds-section"><h2>${icon('eye')} Values</h2>
+      <p class="muted">Masked columns show their value only to the application roles you tick (<code>meta.has_role()</code> of the signed-in user); others see the mask. The masks live in a view next to the table that the roles above read instead of the table.</p>
+      <label class="check"><input type="checkbox" name="view"${chk(v.enabled)}> Masking view</label>
+      <div class="form-grid">
+        <div class="field"><label class="label" for="ds-view">View name</label><input id="ds-view" name="view_name" value="${v.name}" autocomplete="off" spellcheck="false"></div>
+        <div class="field"><label class="label" for="ds-roles">Application roles</label><input id="ds-roles" name="roles" value="${v.roles.join(', ')}" autocomplete="off" spellcheck="false">
+          <small class="help">Comma-separated. Changed roles get their column in the table below after Preview SQL.</small></div>
+      </div>
+      ${maskRows}
+    </section>
+    <section class="ds-section"><h2>${icon('code')} SQL</h2>
+      ${opts.warnings.length ? html`<div class="alert alert-warning" role="status"><ul>${opts.warnings.map((w) => html`<li>${w}</li>`)}</ul></div>` : ''}
+      ${opts.sql.length ? html`<pre class="source" data-code-view="sql" tabindex="0" aria-label="SQL">${opts.sql.join(';\n\n')};</pre>` : html`<p class="muted">No changes: the table's security is as the form shows it.</p>`}
+      ${opts.output}
+    </section>
+    <div class="buttons">
+      <button class="btn" name="mode" value="preview">${icon('eye')} Preview SQL</button>
+      <button class="btn btn-hot" name="mode" value="apply">${icon('check')} Apply</button>
+      <button class="btn" name="mode" value="worksheet">${icon('code')} Open in the worksheet</button>
+      <a class="btn" href="${objUrl}">Cancel</a>
+    </div></form>`;
+}
+
+async function page(req: Req, reply: FastifyReply) {
+  const s = await developer(req, reply);
+  if (!s) return;
+  const db = await workshopDb(s);
+  const isPost = req.method === 'POST';
+  const b: Body = isPost ? (req.body ?? {}) : (req.query ?? {});
+  const ref = String((isPost ? b.ref : b.o) ?? '');
+  const schemas = (await usableSchemas(db)).filter((n) => !SYSTEM_SCHEMAS.includes(n));
+  const { appDbRoles, appRoles } = await workspaceApps(s);
+  const cur = ref ? await readSecurity(db, ref, appDbRoles, appRoles) : null;
+  if (!cur || !schemas.includes(cur.schema)) return reply.code(404).send('Not found');
+  let def = currentDef(cur);
+  let errors: string[] = [];
+  let sql: string[] = [];
+  let warnings: string[] = [];
+  let output: Raw | '' = '';
+  if (isPost) {
+    def = fromForm(b, cur);
+    const taken = (await db.query<{ n: string }>(`select relname as n from pg_class where relnamespace = $1::regnamespace`, [cur.schema])).rows.map((r) => r.n);
+    errors = checkSecurity(def, cur, taken);
+    if (!errors.length) ({ statements: sql, warnings } = securitySql(def, cur));
+    if (!errors.length && b.mode === 'worksheet') {
+      s.state.__SQLDRAFT = sql.length ? `${sql.join(';\n\n')};` : '-- no changes';
+      flash(s, 'Review the statements and run them: nothing has been changed yet.');
+      return back(reply, s, `${BASE}/sql/worksheet`);
+    }
+    if (!errors.length && b.mode === 'apply' && sql.length) {
+      const c = await db.pool.connect();
+      let failed = '';
+      let at = '';
+      try {
+        await c.query('begin');
+        for (const x of sql) {
+          at = x;
+          await c.query(x);
+        }
+        await c.query('commit');
+      } catch (e) {
+        failed = (e as Error).message;
+        await c.query('rollback').catch(() => {});
+      } finally {
+        c.release(true);
+      }
+      await logActivity({ username: s.username, event: 'sql_command', ip: clientIp(req), detail: sql.join(';\n').slice(0, 2000) });
+      clearCompletions();
+      if (!failed) {
+        await recordChanges({ workspaceId: currentWorkspace(s), author: s.username ?? '?', source: 'table', name: `security_${cur.table}`.slice(0, 63), defaultSchema: cur.schema, statements: [joinStatements(sql)] });
+        flash(s, `Changed the security of ${cur.schema}.${cur.table}: ${sql.length} statement${sql.length === 1 ? '' : 's'}.`);
+        return back(reply, s, `${BASE}/sql/objects/security?${new URLSearchParams({ o: ref })}`);
+      }
+      output = html`<div class="alert alert-error" role="alert"><p><strong>Nothing was changed</strong>: the statements ran in one transaction, which was rolled back.</p><p>${failed}</p><pre class="source" data-code-view="sql" tabindex="0" aria-label="Failed statement">${at}</pre></div>`;
+    }
+  }
+  const title = `Security of ${cur.schema}.${cur.table}`;
+  const objUrl = `${BASE}/sql/objects?${new URLSearchParams({ schema: cur.schema, k: 'table', o: ref })}`;
+  const main = html`<h1 class="u-mb1">${title}</h1>${workshopTabs('objects')}${form(s, cur, def, { ref, sql, warnings, errors, output })}`;
+  return send(reply, s, shell(s, title, [['SQL Workshop', `${BASE}/sql`], ['Object Browser', `${BASE}/sql/objects`], [`${cur.schema}.${cur.table}`, objUrl], ['Security']], main, 'sql'));
+}
+
+export async function dataSecurityRoutes(app: FastifyInstance) {
+  app.get(`${BASE}/sql/objects/security`, page);
+  app.post(`${BASE}/sql/objects/security`, page);
+}
+

package/src/builder/gallery.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { FastifyInstance } from 'fastify';
-import { owner, ownerUrl } from '../db.ts';
+import { owner, ownerUrl, type Client } from '../db.ts';
 import { root } from '../env.ts';
 import { html, raw } from '../html.ts';
 import { icon } from '../icons.ts';
@@ -13,16 +13,21 @@ import { back, BASE, csrf, developer, flash, send, shell, type Req } from './ui.
 import { currentWorkspace, inWorkspaceSql, placeApp } from './workspaces.ts';
 import { workspacesChanged } from '../workspace-db.ts';
 
-// The App Gallery (sprint 61; APEX: App Gallery with Sample, Starter and Custom Apps).
+// The App Gallery (sprint 61, sprint 120; APEX: App Gallery with Sample, Starter, Utility and
+// Custom Apps).
 //
-//   Sample apps   applications shipped with pgkiln (examples/): an administrator installs
-//                 one with its schema, data and demo accounts, as `pgkiln migrate --example`;
+//   Sample apps   applications shipped with pgkiln: an administrator installs one with its
+//                 schema, data and demo account, either an example directory (`example`, as
+//                 `pgkiln migrate --example`) or one SQL file (`file`: examples/*.sql or
+//                 examples/gallery/samples/*.sql, run in one transaction as the owner);
 //   Starter apps  blueprints shipped with pgkiln (examples/gallery/starters/): Install opens
 //                 the blueprint's review, and the developer creates the application from it
 //                 in the current workspace (a new role and schema, like every new application);
+//   Utility apps  (sprint 120) blueprints too (examples/gallery/utilities/), of applications a
+//                 workspace uses rather than learns from, installed the same way;
 //   Custom apps   the workspace's boilerplate applications: Create application starts from one.
 //
-// The list is examples/gallery/gallery.json.
+// The list is examples/gallery/gallery.json; requests only ever name a key of it.
 
 interface Sample {
   key: string;
@@ -44,64 +49,94 @@ interface Starter {
 const GALLERY = join(root, 'examples', 'gallery');
 const KEY = /^[a-z][a-z0-9-]{0,40}$/;
 
-function catalog(): { samples: Sample[]; starters: Starter[] } {
+const list = <T>(v: unknown): T[] => (Array.isArray(v) ? v : []);
+
+function catalog(): { samples: Sample[]; starters: Starter[]; utilities: Starter[] } {
   try {
     const c = JSON.parse(readFileSync(join(GALLERY, 'gallery.json'), 'utf8'));
-    return { samples: Array.isArray(c.samples) ? c.samples : [], starters: Array.isArray(c.starters) ? c.starters : [] };
+    return { samples: list(c.samples), starters: list(c.starters), utilities: list(c.utilities) };
   } catch {
-    return { samples: [], starters: [] };
+    return { samples: [], starters: [], utilities: [] };
   }
 }
 
+/** The blueprint files a kind of entry may name: starters/x.json or utilities/x.json. */
+const BLUEPRINT_FILE = { starters: /^starters\/[a-z0-9-]+\.json$/, utilities: /^utilities\/[a-z0-9-]+\.json$/ } as const;
+/** The SQL files a sample may name: examples/x.sql or examples/gallery/samples/x.sql. */
+const SAMPLE_FILE = /^(samples\/)?[a-z0-9-]+\.sql$/;
+
 /** A file of the gallery: only names from the catalogue, never a path from the request. */
 const galleryFile = (rel: string) => readFileSync(join(rel.includes('/') ? GALLERY : join(root, 'examples'), rel), 'utf8');
 
-type Tab = 'samples' | 'starters' | 'custom';
+type Tab = 'samples' | 'starters' | 'utilities' | 'custom';
+const TABS: readonly [Tab, string][] = [['samples', 'Sample Apps'], ['starters', 'Starter Apps'], ['utilities', 'Utility Apps'], ['custom', 'Custom Apps']];
 
 export async function galleryRoutes(app: FastifyInstance) {
   app.get(`${BASE}/gallery`, async (req: Req, reply) => {
     const s = await developer(req, reply);
     if (!s) return;
-    const tab: Tab = (['samples', 'starters', 'custom'] as const).find((t) => t === req.query?.tab) ?? 'samples';
+    const tab: Tab = TABS.map(([t]) => t).find((t) => t === req.query?.tab) ?? 'samples';
+    const q = typeof req.query?.q === 'string' ? req.query.q.trim().slice(0, 100) : '';
     const admin = await isAdmin(s.username);
-    const { samples, starters } = catalog();
+    const ws = currentWorkspace(s);
+    const { samples, starters, utilities } = catalog();
+    // an installed sample: Edit only in its own workspace
     const installed = new Map(
-      (await owner.query<{ alias: string; id: number }>('select alias, id from meta.app where alias = any($1)', [samples.map((x) => x.alias)])).rows.map((r) => [r.alias, r.id]),
+      (await owner.query<{ alias: string; id: number; here: boolean }>(`select a.alias, a.id, ${inWorkspaceSql('a', 2)} as here from meta.app a where a.alias = any($1)`,
+        [samples.map((x) => x.alias), ws])).rows.map((r) => [r.alias, r]),
     );
     const custom = (await owner.query<{ id: number; name: string; description: string | null }>(
       `select a.id, a.name, null::text as description from meta.app a where a.app_type = 'boilerplate' and ${inWorkspaceSql('a', 1)} order by lower(a.name), a.id`,
-      [currentWorkspace(s)],
+      [ws],
     )).rows;
+    // (sprint 120) the search also works without JavaScript: ?q= leaves out what doesn't match
+    // (like the script's filter: every word of the search in the title or description)
+    const words = q.toLowerCase().split(/\s+/).filter(Boolean);
+    const matches = (x: { title?: string; name?: string; description?: string | null }) => {
+      const text = `${x.title ?? x.name ?? ''} ${x.description ?? ''}`.toLowerCase();
+      return words.every((w) => text.includes(w));
+    };
+    const counts: Record<Tab, number> = { samples: samples.length, starters: starters.length, utilities: utilities.length, custom: custom.length };
     const card = (ic: string, title: string, by: string, text: string, action: unknown) =>
       html`<article class="gal-card" data-filter-row><div class="gal-head"><span class="gal-icon">${icon(ic)}</span><div><h2>${title}</h2><span class="muted small">${by}</span></div></div>
         <p>${text}</p><div class="gal-foot">${action}</div></article>`;
-    const tabs = html`<nav class="gal-tabs segmented" aria-label="Kinds of applications">${([['samples', 'Sample Apps'], ['starters', 'Starter Apps'], ['custom', 'Custom Apps']] as const).map(([t, l]) =>
-      html`<a href="${BASE}/gallery?tab=${t}"${tab === t ? raw(' aria-current="page"') : ''}>${l}</a>`)}</nav>`;
+    const tabs = html`<nav class="gal-tabs segmented" aria-label="Kinds of applications">${TABS.map(([t, l]) =>
+      html`<a href="${BASE}/gallery?tab=${t}${q ? `&q=${encodeURIComponent(q)}` : ''}"${tab === t ? raw(' aria-current="page"') : ''}>${l} <span class="gal-count">${counts[t]}</span></a>`)}</nav>`;
+    const blueprintCard = (kind: 'starters' | 'utilities') => (x: Starter) => card(x.icon, x.title, 'pgkiln', x.description,
+      html`<form method="post" action="${BASE}/gallery/${kind}/${x.key}">${csrf(s)}<button class="btn btn-hot btn-sm">Install</button></form>`);
     const cards =
       tab === 'samples'
-        ? samples.map((x) => card(x.icon, x.title, 'pgkiln', x.description,
-            installed.has(x.alias)
-              ? html`<span class="tag tag-ok">Installed</span><a class="btn btn-sm" href="/a/${x.alias}" target="_blank" rel="noopener">Run</a><a class="btn btn-sm" href="${BASE}/apps/${installed.get(x.alias)}">Edit</a>`
-              : admin
-                ? html`<form method="post" action="${BASE}/gallery/samples/${x.key}">${csrf(s)}<button class="btn btn-hot btn-sm" data-confirm="Install ${x.title}? It adds its own schema, data and demo accounts with known passwords: not for a production instance.">Install</button></form>`
-                : html`<span class="muted small">An administrator installs it.</span>`))
-        : tab === 'starters'
-          ? starters.map((x) => card(x.icon, x.title, 'pgkiln', x.description,
-              html`<form method="post" action="${BASE}/gallery/starters/${x.key}">${csrf(s)}<button class="btn btn-hot btn-sm">Install</button></form>`))
-          : custom.map((x) => card('copy', x.name, 'This workspace', x.description ?? 'A boilerplate application: a new application starts with its pages, shared components and settings.',
+        ? samples.filter(matches).map((x) => {
+            const it = installed.get(x.alias);
+            return card(x.icon, x.title, 'pgkiln', x.description,
+              it
+                ? html`<span class="tag tag-ok">Installed</span><a class="btn btn-sm" href="/a/${x.alias}" target="_blank" rel="noopener">Run</a>${it.here
+                    ? html`<a class="btn btn-sm" href="${BASE}/apps/${it.id}">Edit</a>`
+                    : html`<span class="muted small">in another workspace</span>`}`
+                : admin
+                  ? html`<form method="post" action="${BASE}/gallery/samples/${x.key}">${csrf(s)}<button class="btn btn-hot btn-sm" data-confirm="Install ${x.title}? It adds its own schema, data and demo accounts with known passwords: not for a production instance.">Install</button></form>`
+                  : html`<span class="muted small">An administrator installs it.</span>`);
+          })
+        : tab === 'starters' || tab === 'utilities'
+          ? (tab === 'starters' ? starters : utilities).filter(matches).map(blueprintCard(tab))
+          : custom.filter(matches).map((x) => card('copy', x.name, 'This workspace', x.description ?? 'A boilerplate application: a new application starts with its pages, shared components and settings.',
               html`<a class="btn btn-hot btn-sm" href="${BASE}/create?boilerplate=${x.id}">Create from it</a><a class="btn btn-sm" href="${BASE}/apps/${x.id}">Edit</a>`));
-    const empty = tab === 'custom'
-      ? html`<p class="muted">No custom apps yet: make an application of type <em>Boilerplate</em> (Application settings → Application type) and it appears here.</p>`
-      : html`<p class="muted">The gallery is empty.</p>`;
+    const empty = q && counts[tab]
+      ? html`<p class="muted">No app matches <strong>${q}</strong>. <a href="${BASE}/gallery?tab=${tab}">Show all</a></p>`
+      : tab === 'custom'
+        ? html`<p class="muted">No custom apps yet: make an application of type <em>Boilerplate</em> (Application settings → Application type) and it appears here.</p>`
+        : html`<p class="muted">The gallery is empty.</p>`;
     const intro = {
-      samples: 'Applications that show what pgkiln can do, with their own data and demo accounts. Install them on a development or demo instance.',
+      samples: 'Applications that show what pgkiln can do, each with its own schema, data and demo account: the showcase, the tutorial, one app per feature area and the UX Pattern Catalog. An administrator installs them on a development or demo instance.',
       starters: 'Small, ready-to-use applications. Install shows what will be created (tables, pages, sample data) before anything happens; the application gets its own role and schema in this workspace.',
+      utilities: 'Applications a workspace uses rather than learns from: shared lookup lists, release notes, announcements. Like starter apps, Install shows what will be created first, and the application gets its own role and schema in this workspace.',
       custom: 'The boilerplate applications of this workspace: start a new application from one.',
     }[tab];
     const main = html`<div class="gal">
       <div class="gal-bar">
-        <div class="ab-search gal-search" role="search"><label class="sr-only" for="gal-q">Search apps</label>${icon('search')}
-          <input id="gal-q" type="search" placeholder="Search apps" autocomplete="off" data-filter-list=".gal [data-filter-row]"></div>
+        <form class="ab-search gal-search" role="search" method="get" action="${BASE}/gallery"><label class="sr-only" for="gal-q">Search apps</label>${icon('search')}
+          <input type="hidden" name="tab" value="${tab}">
+          <input id="gal-q" name="q" type="search" placeholder="Search apps" autocomplete="off" value="${q}" data-filter-list=".gal [data-filter-row]"></form>
         ${tabs}
       </div>
       <h1 class="sr-only">App Gallery</h1>
@@ -120,19 +155,30 @@ export async function galleryRoutes(app: FastifyInstance) {
     if (!x) return reply.code(404).send('Not found');
     try {
       if (await owner.one('select 1 as ok from meta.app where alias = $1', [x.alias])) throw new Error(`an application with the alias ${x.alias} exists already.`);
-      if (x.example && KEY.test(x.example)) await migrate({ root, databaseUrl: ownerUrl, example: x.example, log: () => {} });
-      else if (x.file && /^[a-z0-9-]+\.sql$/.test(x.file)) await owner.query(galleryFile(x.file));
-      else throw new Error('the gallery entry names nothing to install.');
-      const made = await owner.one<{ id: number; db_role: string | null }>('select id, db_role from meta.app where alias = $1', [x.alias]);
-      if (!made) throw new Error(`the scripts ran, but there is no application ${x.alias}.`);
-      // into the current workspace (an isolated one gets the application's role too)
       const ws = currentWorkspace(s);
-      if (ws > 1)
-        await owner.tx(async (c) => {
+      // into the current workspace (an isolated one gets the application's role too)
+      const place = async (c: Client) => {
+        const made = (await c.query('select id, db_role from meta.app where alias = $1', [x.alias])).rows[0] as { id: number; db_role: string | null } | undefined;
+        if (!made) throw new Error(`the scripts ran, but there is no application ${x.alias}.`);
+        if (ws > 1) {
           if (made.db_role && (await c.query('select 1 from meta.workspace where id = $1 and isolated', [ws])).rowCount)
             await c.query('insert into meta.workspace_role (workspace_id, role_name) values ($1, $2) on conflict do nothing', [ws, made.db_role]);
           await placeApp(c, made.id, ws);
+        }
+        return made;
+      };
+      let made: { id: number; db_role: string | null };
+      if (x.example && KEY.test(x.example)) {
+        await migrate({ root, databaseUrl: ownerUrl, example: x.example, log: () => {} });
+        made = await owner.tx(place);
+      } else if (x.file && SAMPLE_FILE.test(x.file)) {
+        // (sprint 120) the file and the placement in one transaction: a failing script leaves nothing behind
+        const sql = galleryFile(x.file);
+        made = await owner.tx(async (c) => {
+          await c.query(sql);
+          return place(c);
         });
+      } else throw new Error('the gallery entry names nothing to install.');
       await workspacesChanged();
       await logActivity({ appId: made.id, username: s.username, event: 'gallery', ip: clientIp(req), detail: `installed sample app ${x.key}` });
       flash(s, `${x.title} installed (/a/${x.alias}).`);
@@ -143,12 +189,13 @@ export async function galleryRoutes(app: FastifyInstance) {
     }
   });
 
-  // a starter app: its blueprint's review (nothing is created before the developer confirms there)
-  app.post(`${BASE}/gallery/starters/:key`, async (req: Req, reply) => {
-    const s = await developer(req, reply);
-    if (!s) return;
-    const x = KEY.test(req.params.key) ? catalog().starters.find((c) => c.key === req.params.key) : undefined;
-    if (!x || !/^starters\/[a-z0-9-]+\.json$/.test(x.file)) return reply.code(404).send('Not found');
-    return openBlueprint(s, reply, x.title, JSON.stringify(JSON.parse(galleryFile(x.file)), null, 2));
-  });
+  // a starter or utility app: its blueprint's review (nothing is created before the developer confirms there)
+  for (const kind of ['starters', 'utilities'] as const)
+    app.post(`${BASE}/gallery/${kind}/:key`, async (req: Req, reply) => {
+      const s = await developer(req, reply);
+      if (!s) return;
+      const x = KEY.test(req.params.key) ? catalog()[kind].find((c) => c.key === req.params.key) : undefined;
+      if (!x || typeof x.file !== 'string' || !BLUEPRINT_FILE[kind].test(x.file)) return reply.code(404).send('Not found');
+      return openBlueprint(s, reply, x.title, JSON.stringify(JSON.parse(galleryFile(x.file)), null, 2));
+    });
 }

package/src/builder/home.ts

@@ -20,7 +20,7 @@ const SORTS: Record<Sort, string> = {
   id: 'a.id',
   alias: 'a.alias',
   pages: 'pages desc, lower(a.name)',
-  updated: 'a.updated_at desc nulls last, lower(a.name)',
+  updated: 'greatest(a.updated_at, c.updated_at) desc nulls last, lower(a.name)',
 };
 const RECENT_MAX = 8;
 
@@ -45,6 +45,10 @@ export function ago(at: Date | string | null | undefined, now = Date.now()) {
   return 'just now';
 }
 
+/** (116) the App Builder list's working copies count and lock state */
+const copiesText = (n: number) => `${n} working cop${n === 1 ? 'y' : 'ies'}`;
+const lockedText = (by: string) => `Locked by ${by}`;
+
 const appIcon = (a: { id: number; name: string }, cls = '') =>
   html`<span class="app-icon app-color-${a.id % APP_COLORS}${cls ? ` ${cls}` : ''}" aria-hidden="true">${a.name.slice(0, 1).toUpperCase()}</span>`;
 
@@ -108,10 +112,14 @@ export async function homeRoutes(app: FastifyInstance) {
     const group = groups.find((g) => String(g.id) === s.state.__BGROUP) ?? null;
     const [apps, total, recent] = await Promise.all([
       owner.query(
-        `select a.id, a.name, a.alias, a.authentication, a.db_role, a.updated_at, g.name as group_name,
+        `select a.id, a.name, a.alias, a.authentication, a.db_role, greatest(a.updated_at, c.updated_at) as updated_at, g.name as group_name,
+                c.updated_by,
+                (select count(*) from meta.working_copy w where w.main_app_id = a.id)::int as copies,
+                (select locked_by from meta.builder_lock k where k.app_id = a.id and k.page_no = 0) as locked_by,
                 (select count(*) from meta.page p where p.app_id = a.id)::int as pages,
                 (select count(*) from meta.activity_log l where l.app_id = a.id and l.event = 'page_view' and l.at > now() - interval '1 day')::int as views
            from meta.app a
+           left join meta.app_change c on c.app_id = a.id
            left join meta.app_group_member gm on gm.app_id = a.id
            left join meta.app_group g on g.id = gm.group_id
           where ($1 = '' or a.name ilike '%' || $1 || '%' or a.alias ilike '%' || $1 || '%' or a.id::text = $1) and ${inWorkspaceSql('a', 2)}
@@ -137,22 +145,25 @@ export async function homeRoutes(app: FastifyInstance) {
       : view === 'grid'
         ? html`<div class="ab-cards">${rows.map((a) => html`<article class="ab-card" data-filter-row>
             <a class="ab-card-main" href="${BASE}/apps/${a.id}">${appIcon(a)}<span><strong>${a.name}</strong><small>${a.id} · /a/${a.alias}</small></span></a>
-            <div class="ab-card-meta">${a.group_name ? html`<span class="tag">${a.group_name}</span>` : ''}<span>${a.pages} pages</span><span>${a.views} views today</span><span>${ago(a.updated_at)}</span></div>
+            <div class="ab-card-meta">${a.group_name ? html`<span class="tag">${a.group_name}</span>` : ''}<span>${a.pages} pages</span><span>${a.views} views today</span><span>${ago(a.updated_at)}${a.updated_by ? html` by <span class="ab-by">${a.updated_by}</span>` : ''}</span></div>
+            ${a.copies || a.locked_by ? html`<div class="ab-card-badges">${a.copies ? html`<a class="tag" href="${BASE}/apps/${a.id}/working-copies">${icon('layers')} ${copiesText(a.copies)}</a>` : ''}${a.locked_by ? html`<span class="tag ab-locked" title="${lockedText(a.locked_by)}">${icon('lock')} <span class="ab-by">${lockedText(a.locked_by)}</span></span>` : ''}</div>` : ''}
             <div class="ab-card-actions">
               <a class="tb-btn" href="${BASE}/apps/${a.id}" title="Edit ${a.name}">${icon('edit')}<span class="sr-only">Edit ${a.name}</span></a>
               <a class="tb-btn" href="/a/${a.alias}" target="_blank" rel="noopener" title="Run ${a.name}">${icon('play')}<span class="sr-only">Run ${a.name}</span></a>
             </div></article>`)}</div>`
         : html`<div class="table-wrap ab-table"><table class="report ab-apps">
             <caption class="sr-only">Applications</caption>
-            <thead><tr>${th('id', 'Application', 'num')}${th('name', 'Name')}${th('alias', 'Alias')}${th('pages', 'Pages', 'num')}<th scope="col" class="num">Views (24h)</th><th scope="col">Sign-in</th>${th('updated', 'Updated')}<th scope="col" class="ab-actions-col">Actions</th></tr></thead>
+            <thead><tr>${th('id', 'Application', 'num')}${th('name', 'Name')}${th('alias', 'Alias')}${th('pages', 'Pages', 'num')}<th scope="col" class="num">Views (24h)</th><th scope="col">Sign-in</th>${th('updated', 'Updated')}<th scope="col">Updated by</th><th scope="col" class="num">Working copies</th><th scope="col" class="ab-actions-col">Actions</th></tr></thead>
             <tbody>${rows.map((a) => html`<tr data-filter-row>
               <td class="num">${a.id}</td>
-              <td class="ab-name"><a href="${BASE}/apps/${a.id}">${appIcon(a)}<span>${a.name}</span></a></td>
+              <td class="ab-name"><a href="${BASE}/apps/${a.id}">${appIcon(a)}<span>${a.name}</span></a>${a.locked_by ? html`<span class="ab-lock" role="img" aria-label="${lockedText(a.locked_by)}" title="${lockedText(a.locked_by)}">${icon('lock')}</span>` : ''}</td>
               <td>${a.alias}${a.group_name ? html` <span class="tag">${a.group_name}</span>` : ''}</td>
               <td class="num">${a.pages}</td>
               <td class="num">${a.views}</td>
               <td>${a.authentication === 'none' ? 'Public' : a.authentication === 'header' ? 'HTTP header' : a.authentication === 'database' ? 'Database accounts' : a.authentication === 'custom' ? 'Custom' : 'App users'}</td>
               <td title="${a.updated_at ? new Date(a.updated_at).toISOString().slice(0, 16).replace('T', ' ') : ''}">${ago(a.updated_at)}</td>
+              <td class="ab-by">${a.updated_by ?? ''}</td>
+              <td class="num">${a.copies ? html`<a href="${BASE}/apps/${a.id}/working-copies" aria-label="${copiesText(a.copies)} of ${a.name}">${a.copies}</a>` : '0'}</td>
               <td class="ab-actions">
                 <a class="tb-btn" href="${BASE}/apps/${a.id}" title="Edit ${a.name}">${icon('edit')}<span class="sr-only">Edit ${a.name}</span></a>
                 <a class="tb-btn" href="/a/${a.alias}" target="_blank" rel="noopener" title="Run ${a.name}">${icon('play')}<span class="sr-only">Run ${a.name}</span></a>