pgkiln 0.50.0 → 0.52.0

package/src/builder/components.ts

@@ -11,6 +11,7 @@ import { scheduleProblem } from '../automations.ts';
 import { ICONS, isIcon } from '../icons.ts';
 import { templateProblem } from '../runtime/document.ts';
 import { stepProblems } from '../workflow.ts';
+import { eventProblems, notificationProblems, outcomeProblems } from '../task-events.ts';
 import { workflowBeforeSave } from './workflows.ts';
 import { handlerProblems } from '../runtime/rest.ts';
 import { TEMPLATE_COMPONENT_SPEC } from './template-spec.ts';
@@ -89,6 +90,14 @@ const conditionFields = (group: string): Field[] => [
 const menuBeforeSave = async (v: Record<string, unknown>) => {
   if (v.menu === '{}' || v.menu === '[]') v.menu = null;
   if (typeof v.menu === 'string' && !Array.isArray(JSON.parse(v.menu))) throw new Error('Menu entries: a JSON array, e.g. [{"label": "Details", "page": 3, "items": {"P3_ID": "&P2_ID."}}, {"label": "Archive", "request": "ARCHIVE"}]');
+  // (124) the database checks every entry too (meta.button_menu_ok); this names the one that's wrong
+  if (typeof v.menu === 'string')
+    for (const e of JSON.parse(v.menu) as Record<string, unknown>[]) {
+      const kinds = ['page', 'request', 'action'].filter((k) => e && typeof e === 'object' && k in e);
+      if (kinds.length !== 1) throw new Error(`Menu entry "${String(e?.label ?? '')}": exactly one of "page", "request" or "action".`);
+      if ('action' in e && !/^[A-Z][A-Z0-9_]{0,59}$/.test(String(e.action)))
+        throw new Error(`Menu entry "${String(e.label ?? '')}": "action" is a name in capitals (A-Z, 0-9, _), e.g. EXPORT.`);
+    }
 };
 const CLASS_LIST = /^[a-z][a-z0-9_-]{0,39}( [a-z][a-z0-9_-]{0,39}){0,4}$/;
 
@@ -175,7 +184,7 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
       { name: 'target_items', label: 'Set items (JSON)', kind: 'json', group: 'Behaviour', help: '{"P3_ID": "&P2_ID."}' },
       { name: 'confirm', label: 'Confirm message', kind: 'text', group: 'Behaviour' },
       { name: 'menu', label: 'Menu entries (action menu, JSON)', kind: 'json', wide: true, group: 'Behaviour',
-        help: '[{"label": "Details", "page": 3, "items": {"P3_ID": "&P2_ID."}}, {"label": "Archive", "request": "ARCHIVE", "confirm": "Archive it?", "authz": "ADMIN", "icon": "inbox"}] — a link to a page, or a submit with that request (processes and branches see it as the button pressed). At most 20.' },
+        help: '[{"label": "Details", "page": 3, "items": {"P3_ID": "&P2_ID."}}, {"label": "Archive", "request": "ARCHIVE", "confirm": "Archive it?", "authz": "ADMIN", "icon": "inbox"}, {"label": "Export", "action": "EXPORT"}] — a link to a page, a submit with that request (processes and branches see it as the button pressed), or an action: the dynamic actions of event menu_entry with that name (or the menu button\'s name) as trigger. At most 20.' },
       { name: 'hot', common: true, label: 'Primary (hot) button', kind: 'bool', group: 'Appearance' },
       { name: 'template_options', label: 'Template options', kind: 'options', choices: BUTTON_OPTIONS, group: 'Appearance',
         help: 'CSS classes from a fixed list, added to the button (APEX: Template Options).' },
@@ -206,18 +215,18 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
           : null,
     fields: [
       { name: 'name', label: 'Name', kind: 'text', group: 'When' },
-      { name: 'event', label: 'Event', kind: 'select', options: ['change', 'click', 'load', 'dialog_closed', 'focus', 'blur', 'key_release', 'after_refresh', 'selection_change', 'before_submit', 'custom'], group: 'When',
-        help: 'dialog_closed: a modal dialog opened from this page was submitted and closed (instead of reloading the page), e.g. refresh a region. focus / blur / key_release: an item gets or loses the focus, a key is released in it. after_refresh: a region was refreshed or loaded. selection_change: rows were selected in a report (row selection) or a grid\'s master row. before_submit: the page is about to be submitted (a declined confirm keeps it). custom: JavaScript raised it with pgkiln.trigger(\'NAME\', value). The actions of one event and trigger run in sequence order; a declined confirm stops the ones after it.' },
-      { name: 'trigger_element', label: 'Item(s) / button / region / page / event', kind: 'upper', group: 'When', help: 'Comma separated: item names (change, focus, blur, key_release), a button name (click), region ids or static ids (after_refresh, selection_change), dialog page numbers (dialog_closed; empty: any dialog), event names (custom). Empty for load and before_submit.' },
+      { name: 'event', label: 'Event', kind: 'select', options: ['change', 'click', 'load', 'dialog_closed', 'focus', 'blur', 'key_release', 'after_refresh', 'selection_change', 'before_submit', 'custom', 'menu_entry'], group: 'When',
+        help: 'dialog_closed: a modal dialog opened from this page was submitted and closed (instead of reloading the page), e.g. refresh a region. focus / blur / key_release: an item gets or loses the focus, a key is released in it. after_refresh: a region was refreshed or loaded. selection_change: rows were selected in a report (row selection) or a grid\'s master row. before_submit: the page is about to be submitted (a declined confirm keeps it). custom: JavaScript raised it with pgkiln.trigger(\'NAME\', value). menu_entry (Menu entry chosen): an entry {"label": …, "action": "NAME"} of a menu button was chosen. The actions of one event and trigger run in sequence order; a declined confirm stops the ones after it.' },
+      { name: 'trigger_element', label: 'Item(s) / button / region / page / event', kind: 'upper', group: 'When', help: 'Comma separated: item names (change, focus, blur, key_release), a button name (click), region ids or static ids (after_refresh, selection_change), dialog page numbers (dialog_closed; empty: any dialog), event names (custom), menu entry action names or menu button names (menu_entry: any of its entries; a client-side condition tests the entry\'s name). Empty for load and before_submit.' },
       { name: 'condition_type', label: 'Client-side condition', kind: 'select', options: ['', 'equals', 'not_equals', 'in_list', 'is_null', 'is_not_null'], group: 'When' },
       { name: 'condition_value', label: 'Condition value', kind: 'text', group: 'When' },
-      { name: 'action', label: 'Action', kind: 'select', options: ['show', 'hide', 'enable', 'disable', 'set_value', 'execute_sql', 'refresh_region', 'refresh_item', 'alert', 'submit', 'set_focus', 'add_class', 'remove_class', 'show_success', 'show_error', 'clear_errors', 'ai_generate', 'execute_javascript', 'plugin', 'push_subscribe', 'confirm', 'close_dialog', 'cancel_dialog', 'clear', 'open_region', 'close_region', 'download', 'print', 'current_position', 'share'], group: 'Action',
-        help: 'show/hide/enable/disable reverse automatically when the condition is false. set_focus: the first affected item (or the region). show_error: on the affected items, or at the top. clear_errors: of the affected items, or all. ai_generate: runs the "Generate text with AI" process named in Code through AJAX, without submitting the page (on a submit button, the button submits instead when JavaScript is off). execute_javascript: calls the function named in Code, registered by a static application file (Shared Components → Static Application Files). push_subscribe: turns on push notifications on the user\'s device (use it on click: browsers ask only after one; the app needs push notifications on in Settings → Progressive Web App); Message is shown when it worked. confirm: asks Message; No stops the actions after it. close_dialog / cancel_dialog: close the modal page this runs on (close_dialog refreshes the page below and runs its dialog_closed actions). clear: empties the affected items. open_region / close_region: a collapsible region opens or closes (another region shows or hides). download: the file of the download process named in Code (Items to submit are sent first). print: the browser\'s print dialog. current_position: the device\'s position as latitude,longitude into the first affected item. share: the device\'s share sheet for this page (Message as the text), or the link copied.' },
+      { name: 'action', label: 'Action', kind: 'select', options: ['show', 'hide', 'enable', 'disable', 'set_value', 'execute_sql', 'refresh_region', 'refresh_item', 'alert', 'submit', 'set_focus', 'add_class', 'remove_class', 'show_success', 'show_error', 'clear_errors', 'ai_generate', 'execute_javascript', 'plugin', 'push_subscribe', 'confirm', 'close_dialog', 'cancel_dialog', 'clear', 'open_region', 'close_region', 'download', 'print', 'current_position', 'share', 'wait_popup', 'remove_wait_popup'], group: 'Action',
+        help: 'show/hide/enable/disable reverse automatically when the condition is false. set_focus: the first affected item (or the region). show_error: on the affected items, or at the top. clear_errors: of the affected items, or all. ai_generate: runs the "Generate text with AI" process named in Code through AJAX, without submitting the page (on a submit button, the button submits instead when JavaScript is off). execute_javascript: calls the function named in Code, registered by a static application file (Shared Components → Static Application Files). push_subscribe: turns on push notifications on the user\'s device (use it on click: browsers ask only after one; the app needs push notifications on in Settings → Progressive Web App); Message is shown when it worked. confirm: asks Message; No stops the actions after it. close_dialog / cancel_dialog: close the modal page this runs on (close_dialog refreshes the page below and runs its dialog_closed actions). clear: empties the affected items. open_region / close_region: a collapsible region opens or closes (another region shows or hides). download: the file of the download process named in Code (Items to submit are sent first). print: the browser\'s print dialog. current_position: the device\'s position as latitude,longitude into the first affected item. share: the device\'s share sheet for this page (Message as the text), or the link copied. wait_popup: a modal "please wait" overlay (Message as its text) until remove_wait_popup or the next page, e.g. on before_submit around a long process, or wait_popup, execute_sql, remove_wait_popup around an Ajax call.' },
       { name: 'affected_items', label: 'Affected items', kind: 'upper', group: 'Action' },
       { name: 'affected_region_id', label: 'Affected region', kind: 'region', group: 'Action' },
       { name: 'code', label: 'SQL', kind: 'code', wide: true, group: 'Action', help: 'set_value: a SELECT whose columns set the affected items · execute_sql: any SQL; returned columns named like items set them · ai_generate: the name of an ai_generate process on this page (its output items are updated; items to submit default to the items its prompts use) · execute_javascript: the name of a function registered with pgkiln.actions.register(name, fn) in a static file the page loads.' },
       { name: 'items_to_submit', label: 'Items to submit', kind: 'upper', group: 'Action' },
-      { name: 'message', label: 'Message (alert, show_success, show_error)', kind: 'text', group: 'Action' },
+      { name: 'message', label: 'Message (alert, confirm, show_success, show_error, wait_popup)', kind: 'text', group: 'Action' },
       { name: 'config', label: 'Plug-in attributes (JSON)', kind: 'json', group: 'Action', help: 'plugin: {"attributes": {"NAME": "value or &ITEM."}} (Shared Components → Plug-ins lists each plug-in\'s attributes).' },
       { name: 'css_classes', label: 'CSS classes (add_class, remove_class)', kind: 'text', group: 'Action', help: 'Up to five class names, e.g. is-highlight is-muted (lower case letters, digits, - and _).' },
       { name: 'seq', label: 'Sequence', kind: 'int', group: 'Security' },
@@ -614,7 +623,18 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
       if (v.expiration && !v.due_in) return 'When overdue: set "Due in" first (a task without a due date is never overdue).';
       if (v.expiration === 'renew' && v.max_renewals !== null && v.max_renewals !== undefined && v.max_renewals !== '' && (Number(v.max_renewals) < 1 || Number(v.max_renewals) > 100)) return 'Maximum renewals: 1 to 100.';
       if (v.expiration === 'escalate' && !String(v.escalate_role ?? '').trim()) return 'Escalation role: the role that takes the task over.';
-      return null;
+      // (123) custom outcomes, events and notifications (parseFields gives the JSON as text)
+      const json = (x: unknown) => {
+        const parsed = typeof x === 'string' ? (x.trim() ? JSON.parse(x) : null) : x;
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) && !Object.keys(parsed).length ? null : parsed;
+      };
+      const problems = [...outcomeProblems(json(v.outcomes)), ...eventProblems(json(v.events)), ...notificationProblems(json(v.notifications))];
+      return problems.length ? problems.join(' ') : null;
+    },
+    // (123) an empty JSON field is "none" (null), not {}
+    beforeSave: async (v) => {
+      for (const k of ['outcomes', 'events', 'notifications']) if (v[k] === '{}' || v[k] === '[]' || v[k] === '') v[k] = null;
+      if (v.fail_recovery === '') v.fail_recovery = null;
     },
     fields: [
       { name: 'name', label: 'Name', kind: 'upper', group: 'Identification', help: "Application SQL creates tasks with meta.create_task('NAME', :P1_ID, params, owners)." },
@@ -632,7 +652,16 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
       { name: 'details_page', label: 'Details page', kind: 'page', group: 'Details', help: 'The subject links here, setting the item below to the task\'s record key.' },
       { name: 'details_item', label: 'Details item', kind: 'upper', group: 'Details', help: 'e.g. P7_ID' },
       { name: 'action_code', label: 'On completion (SQL)', kind: 'code', wide: true, group: 'Action',
-        help: 'Runs as the application\'s role when the task is approved, rejected or completed, in the same transaction (an error undoes the decision). Binds: :TASK_ID, :DETAIL_PK, :OUTCOME (APPROVED, REJECTED, COMPLETED), :COMMENT, :APPROVER, :INITIATOR and the task parameters, e.g. select expenses.decide(:DETAIL_PK::int, :OUTCOME, :COMMENT)' },
+        help: 'Runs as the application\'s role when the task is approved, rejected or completed, in the same transaction (an error undoes the decision). Binds: :TASK_ID, :DETAIL_PK, :OUTCOME (APPROVED, REJECTED, COMPLETED, or a custom outcome such as YES), :COMMENT, :APPROVER, :INITIATOR and the task parameters, e.g. select expenses.decide(:DETAIL_PK::int, :OUTCOME, :COMMENT)' },
+      // (123) custom outcomes, events and notifications
+      { name: 'outcomes', label: 'Outcomes (JSON)', kind: 'json', wide: true, group: 'Outcomes',
+        help: 'Custom outcomes instead of Approve / Reject (or Complete): [{"name": "YES", "label": "Yes", "colour": "success"}, {"name": "NO", "label": "No", "colour": "danger"}, {"name": "UNDECIDED", "label": "Undecided", "colour": "warning"}] · colours: default, primary, success, danger, warning. The task list shows one button each; :OUTCOME is the name (YES); a workflow\'s task step names them in "next" ({"yes": "PAY", "no": "END"}) and a switch case in "outcome". Empty: the type\'s own outcomes.' },
+      { name: 'events', label: 'Events (JSON)', kind: 'json', wide: true, group: 'Events',
+        help: '[{"on": "complete", "type": "sql", "code": "select expenses.log(:TASK_ID::bigint, :OUTCOME)"}, {"on": "expire", "type": "mail", "to": "select email from staff where role = \'manager\'", "template": "TASK_EXPIRED"}, {"on": "fail", "type": "workflow", "workflow": "FIX_REQUEST", "vars": {"REASON": "&ERROR."}}] · on: complete, expire, fail (the completion SQL failed) · type: sql (as the application\'s role), mail (meta.send_mail_template with a "template", or "subject" and "body"; "to" is a SELECT returning addresses, or addresses), workflow (meta.start_workflow with the task\'s record key and parameters, plus "vars"). Binds and #NAME# placeholders: the task parameters, :TASK_ID, :DETAIL_PK, :SUBJECT, :OUTCOME, :APPROVER, :INITIATOR, :EVENT; for fail also :ERROR and :COMMENT. Complete and expire run right after the commit, in a transaction of their own; fail runs in the request.' },
+      { name: 'fail_recovery', label: 'When the completion SQL fails', kind: 'select', options: ['', 'reopen', 'complete'], group: 'Events',
+        help: 'reopen (the default): the decision is undone and the task stays open; the user sees the error. complete: the task is completed with the outcome, without the SQL\'s effect. The "fail" events run either way.' },
+      { name: 'notifications', label: 'Notifications (JSON)', kind: 'json', wide: true, group: 'Events',
+        help: 'E-mail templates (Shared Components → E-mail templates) sent by pgkiln itself: {"create": "TASK_CREATED", "complete": "TASK_DONE", "expire": "TASK_EXPIRED"} · create: to the potential owners (named users and the application\'s users with an owner role), complete: to the initiator, expire: to both; at the e-mail address of their account. Placeholders: #SUBJECT#, #TASK_ID#, #DETAIL_PK#, #OUTCOME#, #APPROVER#, #INITIATOR#, #EVENT# and the task parameters. The application needs a mail service.' },
     ],
   },
   template_component: TEMPLATE_COMPONENT_SPEC,

package/src/builder/datasets.ts

@@ -0,0 +1,472 @@
+import type { FastifyInstance, FastifyReply } from 'fastify';
+import {
+  catalogOf, checkDataset, DATASET_LIMITS, DATASET_NAME, datasetFile, datasetOf, datasetSql, proposeDataset, proposeJoin, readDatasetFile,
+  readSchemaCatalog, storeDataset, workspaceDatasets, type Dataset, type DatasetRow,
+} from '../datasets.ts';
+import { owner, type Db } from '../db.ts';
+import { html, raw, type Raw } from '../html.ts';
+import { icon } from '../icons.ts';
+import { createReportingApp, MAX_REPORTING_DATASETS, reportingApps } from '../reporting-app.ts';
+import { readMultipart } from '../runtime/files.ts';
+import { heading } from '../runtime/items.ts';
+import { opLabel, OPERATORS } from '../runtime/report.ts';
+import { english } from '../i18n.ts';
+import { logActivity, clientIp, type Session } from '../session.ts';
+import { checkNewApp, createAppError } from './newapp.ts';
+import { back, BASE, csrf, developer, flash, input, region, send, shell, type Body, type Req } from './ui.ts';
+import { currentWorkspace, usableSchemas, workshopDb } from './workspaces.ts';
+
+// (sprint 110, migration 120) App Builder → Data Reporter (/builder/reporter; APEX 26.1: Data Reporter as a
+// workspace tool): the workspace's datasets (tables and views of one schema, joins proposed from foreign keys,
+// the columns business users may see with labels, format masks and descriptions, a row filter), their files
+// (pgkiln-dataset/1: download one or all, import), and reporting applications made from them (two clicks: Create
+// reporting application on a dataset, then Create). Every developer of the workspace manages them; the catalog is
+// read through the SQL Workshop's connection (an isolated workspace's own login), and a dataset is checked
+// against it before it is saved.
+
+const root = `${BASE}/reporter`;
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const PREVIEW_ROWS = 10;
+const crumbs = (extra: [string, string?][] = []): [string, string?][] => [['App Builder', BASE], ['Data Reporter', root], ...extra];
+const when = (d: string | Date | null) => (d ? new Date(d).toISOString().slice(0, 16).replace('T', ' ') : '');
+
+const page = (s: Session, reply: FastifyReply, title: string, extra: [string, string?][], main: Raw) =>
+  send(reply, s, shell(s, title, crumbs(extra), html`<div class="ab-narrow dataset-page">${main}</div>`, 'reporter'));
+
+/** A dataset of the current workspace by id (null: none, or another workspace's). */
+async function datasetRow(s: Session, id: string): Promise<DatasetRow | null> {
+  if (!/^\d{1,12}$/.test(id)) return null;
+  return (await owner.one<DatasetRow>('select * from meta.dataset where id = $1 and workspace_id = $2', [id, currentWorkspace(s)])) ?? null;
+}
+
+/** A schema the developer's SQL Workshop connection may use, or null. */
+async function usableSchema(db: Db, schema: string) {
+  return schema && (await usableSchemas(db)).includes(schema) ? schema : null;
+}
+
+/** "deptno = deptno, x = y" → join column pairs (this table's column = the earlier table's). */
+export function parseOn(text: string) {
+  return text
+    .split(',')
+    .map((p) => p.split('=').map((x) => x.trim()))
+    .filter((p) => p.length === 2 && p[0] && p[1])
+    .map(([column, ref]) => ({ column, ref }))
+    .slice(0, DATASET_LIMITS.joinColumns);
+}
+
+/** The dataset of the edit form (loose: checkDataset() does the checking). */
+export function datasetFromForm(d: Dataset, b: Body, cat: Awaited<ReturnType<typeof readSchemaCatalog>>): Record<string, unknown> {
+  const tables: any[] = [];
+  for (let i = 0; i < DATASET_LIMITS.tables && b[`t${i}_alias`] !== undefined; i++) {
+    const old = d.tables.find((t) => t.alias === b[`t${i}_alias`]);
+    if (!old || b[`t${i}_remove`] === 'true') continue;
+    tables.push(i === 0 || !tables.length ? { alias: old.alias, table: old.table } : {
+      alias: old.alias, table: old.table,
+      join: { to: String(b[`t${i}_to`] ?? ''), type: b[`t${i}_type`] === 'inner' ? 'inner' : 'left', on: parseOn(String(b[`t${i}_on`] ?? '')) },
+    });
+  }
+  const added = String(b.new_table ?? '');
+  if (added && cat.objects.some((o) => o.name === added) && tables.length < DATASET_LIMITS.tables) {
+    let n = 1;
+    while (tables.some((t) => t.alias === `t${n}`) || d.tables.some((t) => t.alias === `t${n}`)) n++;
+    const on = parseOn(String(b.new_on ?? ''));
+    const join = tables.length
+      ? on.length ? { to: String(b.new_to || tables[0].alias), type: 'left', on } : proposeJoin(added, tables, cat.fks)
+      : undefined;
+    tables.push({ alias: `t${n}`, table: added, ...(join ? { join } : {}) });
+  }
+  const columns: any[] = [];
+  for (let j = 0; j < 1000 && b[`c${j}_ref`] !== undefined; j++) {
+    if (b[`c${j}_on`] !== 'true') continue;
+    const [alias, ...rest] = String(b[`c${j}_ref`]).split('.');
+    columns.push({ table: alias, column: rest.join('.'), name: b[`c${j}_name`], label: b[`c${j}_label`], format: b[`c${j}_format`], description: b[`c${j}_desc`] });
+  }
+  // a table added just now: its columns are offered at once (except the join's and binary ones)
+  const fresh = tables.find((t) => !d.tables.some((x) => x.alias === t.alias));
+  if (fresh) {
+    const taken = new Set(columns.map((c) => String(c.name ?? '')));
+    const skip = new Set((fresh.join?.on ?? []).map((p: { column: string }) => p.column));
+    for (const c of cat.objects.find((o) => o.name === fresh.table)?.columns ?? []) {
+      if (c.type === 'bytea' || skip.has(c.name)) continue;
+      let name = c.name.toLowerCase().replace(/[^a-z0-9_]+/g, '_').replace(/^[^a-z]+/, '').slice(0, 40) || 'col';
+      if (taken.has(name)) name = `${fresh.table}_${name}`.toLowerCase().replace(/[^a-z0-9_]+/g, '_').slice(0, 40);
+      taken.add(name);
+      columns.push({ table: fresh.alias, column: c.name, name, label: heading(c.name) });
+    }
+  }
+  const filters: any[] = [];
+  for (let k = 0; k < DATASET_LIMITS.filters; k++) {
+    const ref = String(b[`f${k}_col`] ?? '');
+    if (!ref) continue;
+    const [alias, ...rest] = ref.split('.');
+    filters.push({ table: alias, column: rest.join('.'), op: b[`f${k}_op`], value: b[`f${k}_value`] ?? '' });
+  }
+  return { name: d.name, label: b.label, description: b.description, schema: d.schema, tables, columns, filters };
+}
+
+/** The first rows of a dataset, read only, through the SQL Workshop's connection (a timeout; errors as text). */
+async function preview(db: Db, d: Dataset): Promise<{ fields: string[]; rows: unknown[][] } | { error: string }> {
+  if (!d.columns.length) return { error: 'The dataset offers no columns.' };
+  try {
+    return await db.tx(async (c) => {
+      await c.query('set transaction read only');
+      await c.query(`set local statement_timeout = 5000`);
+      const r = await c.query({ text: `select * from (${datasetSql(d)}) "__q" limit ${PREVIEW_ROWS}`, rowMode: 'array' });
+      return { fields: r.fields.map((f) => f.name), rows: r.rows };
+    });
+  } catch (e) {
+    return { error: (e as Error).message };
+  }
+}
+
+const cellText = (v: unknown) => (v === null || v === undefined ? '' : v instanceof Date ? v.toISOString().slice(0, 19).replace('T', ' ') : typeof v === 'object' ? JSON.stringify(v) : String(v));
+
+export async function datasetRoutes(app: FastifyInstance) {
+  // ---------------------------------------------------------------- the home: datasets and reporting applications
+  app.get(root, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const ws = currentWorkspace(s);
+    const sets = await workspaceDatasets(owner, ws);
+    const apps = await reportingApps(ws);
+    const main = html`<div class="title-row"><h1>Data Reporter</h1>
+        <div class="buttons"><a class="btn btn-hot" href="${root}/datasets/new">${icon('plus')} New dataset</a><a class="btn" href="${root}/import">${icon('upload')} Import</a>${sets.length ? html`<a class="btn" href="${root}/export">${icon('download')} Export all</a>` : ''}</div></div>
+      <p class="muted u-mt0">Datasets are trusted views of ${s.workspace?.name ?? 'this workspace'}'s data for business users: tables and views of one schema, joined, with the columns they may see, labels, format masks and descriptions, and a row filter. A reporting application on one or more datasets lets its users build, save, publish and share reports; every report runs as the application's database role, so grants and row level security apply.</p>
+      ${region('Datasets', html`<div class="table-wrap"><table class="report report-reflow">
+        <thead><tr><th scope="col">Dataset</th><th scope="col">Schema</th><th scope="col">Tables and views</th><th scope="col" class="num">Columns</th><th scope="col">Updated (UTC)</th><th scope="col">Actions</th></tr></thead>
+        <tbody>${sets.length ? sets.map((d) => html`<tr>
+          <td data-label="Dataset"><a href="${root}/datasets/${d.id}">${d.label}</a> <code>${d.name}</code>${d.description ? html`<br><span class="muted small">${d.description.slice(0, 160)}</span>` : ''}</td>
+          <td data-label="Schema"><code>${d.schema_name}</code></td>
+          <td data-label="Tables and views">${d.tables.map((t) => t.table).join(', ')}</td>
+          <td class="num" data-label="Columns">${d.columns.length}</td>
+          <td data-label="Updated (UTC)">${when(d.updated_at)}${d.updated_by ? html` <span class="muted">${d.updated_by}</span>` : ''}</td>
+          <td data-label=""><a class="btn" href="${root}/apps/new?dataset=${encodeURIComponent(d.name)}">${icon('plus')} Create reporting application</a></td>
+        </tr>`) : html`<tr><td colspan="6" class="empty">No datasets yet: create one on tables and views of a schema, or import a dataset file.</td></tr>`}</tbody></table></div>`)}
+      ${region('Reporting applications', html`<div class="table-wrap"><table class="report report-reflow">
+        <thead><tr><th scope="col">Application</th><th scope="col">Datasets</th><th scope="col" class="num">Users</th><th scope="col" class="num">Published reports</th><th scope="col">Actions</th></tr></thead>
+        <tbody>${apps.length ? apps.map((a) => html`<tr>
+          <td data-label="Application"><a href="${BASE}/apps/${a.id}">${a.name}</a> <code>${a.alias}</code></td>
+          <td data-label="Datasets">${a.datasets.join(', ')}</td>
+          <td class="num" data-label="Users">${a.users}</td>
+          <td class="num" data-label="Published reports">${a.reports}</td>
+          <td data-label=""><a class="btn" href="/a/${a.alias}/">${icon('play')} Run</a> <a class="btn" href="${BASE}/apps/${a.id}/shared">${icon('users')} Users and roles</a></td>
+        </tr>`) : html`<tr><td colspan="5" class="empty">No reporting applications yet: choose Create reporting application on a dataset.</td></tr>`}</tbody></table></div>
+        <p class="muted small">Roles: <b>viewer</b> runs published reports (every user with access), <b>editor</b> also builds, saves, publishes and unpublishes reports, <b>administrator</b> also unpublishes and deletes anyone's. Give accounts access and roles under Users and roles.</p>`)}`;
+    return page(s, reply, 'Data Reporter', [], main);
+  });
+
+  // ---------------------------------------------------------------- a new dataset: schema, then tables and views
+  app.get(`${root}/datasets/new`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const db = await workshopDb(s);
+    const schemas = await usableSchemas(db);
+    const schema = await usableSchema(db, String(req.query.schema ?? ''));
+    const cat = schema ? await readSchemaCatalog(db, schema) : null;
+    const main = html`<h1>New dataset</h1>
+      ${region('1. Schema', html`<form method="get" action="${root}/datasets/new" class="search u-mwnone dataset-schema">
+        <label class="label" for="f_schema">Schema</label>
+        <select id="f_schema" name="schema">${schemas.map((n) => html`<option${n === schema ? raw(' selected') : ''}>${n}</option>`)}</select>
+        <button class="btn">Show its tables and views</button></form>`)}
+      ${cat ? region('2. Tables and views', html`<form method="post" action="${root}/datasets">${csrf(s)}<input type="hidden" name="schema" value="${schema}">
+        <div class="form-grid">
+          ${input('name', 'Name', '', { required: true, placeholder: 'e.g. sales', help: 'Lower case letters, digits and _ (at most 40): reports and files use it. It can\'t be changed later.' })}
+          ${input('label', 'Label', '', { placeholder: 'e.g. Sales', help: 'What business users see.' })}
+        </div>
+        <fieldset class="prop-group"><legend>Tables and views (the first is the main one)</legend>
+          ${cat.objects.length ? html`<div class="dataset-checks">${cat.objects.map((o) => html`<label class="check"><input type="checkbox" name="tables" value="${o.name}"> ${o.name} <span class="muted">${o.kind}, ${o.columns.length} columns</span></label>`)}</div>`
+            : html`<p class="muted">The schema has no tables or views you may use.</p>`}
+          <small class="help">Joins are proposed from foreign keys; every column is offered at first, labelled from its name. You change all of it on the next page.</small>
+        </fieldset>
+        <div class="buttons"><a class="btn" href="${root}">Cancel</a><button class="btn btn-hot">${icon('plus')} Create dataset</button></div></form>`) : ''}`;
+    return page(s, reply, 'New dataset', [['New dataset']], main);
+  });
+
+  app.post(`${root}/datasets`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const b = req.body ?? {};
+    const db = await workshopDb(s);
+    const schema = await usableSchema(db, String(b.schema ?? ''));
+    const name = String(b.name ?? '').trim().toLowerCase();
+    const again = (msg: string) => (flash(s, msg, 'error'), back(reply, s, `${root}/datasets/new${schema ? `?schema=${encodeURIComponent(schema)}` : ''}`));
+    if (!schema) return again('Choose one of the schemas in the list.');
+    if (!DATASET_NAME.test(name)) return again(`"${name}" is not a valid dataset name: lower case letters, digits and _, starting with a letter (at most 40).`);
+    const raw = (req.body as unknown as Record<string, unknown>)?.tables;
+    const chosen = (Array.isArray(raw) ? raw : raw ? [raw] : []).map(String);
+    if (!chosen.length) return again('Choose at least one table or view.');
+    const cat = await readSchemaCatalog(db, schema);
+    const proposed = proposeDataset(name, String(b.label ?? '').trim(), schema, chosen, cat);
+    const { dataset, errors } = checkDataset(proposed.dataset, catalogOf(cat.objects));
+    if (errors.length || !dataset.tables.length) return again([...proposed.errors, ...errors].join(' ') || 'The dataset is not valid.');
+    const exists = await owner.one('select 1 from meta.dataset where workspace_id = $1 and name = $2', [currentWorkspace(s), name]);
+    if (exists) return again(`There is already a dataset ${name}.`);
+    const id = await storeDataset(owner, currentWorkspace(s), dataset, s.username, { replace: false });
+    logActivity({ appId: null, username: s.username, event: 'dataset_create', ip: clientIp(req), detail: `${name} on ${schema}` });
+    flash(s, proposed.errors.length ? `Dataset ${name} created. ${proposed.errors.join(' ')}` : `Dataset ${name} created: check its columns and labels.`, proposed.errors.length ? 'error' : 'ok');
+    return back(reply, s, `${root}/datasets/${id}`);
+  });
+
+  // ---------------------------------------------------------------- a dataset
+  app.get(`${root}/datasets/:id`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const row = await datasetRow(s, req.params.id);
+    if (!row) return reply.code(404).send('Not found');
+    const d = datasetOf(row);
+    const db = await workshopDb(s);
+    const cat = await readSchemaCatalog(db, d.schema);
+    const { errors } = checkDataset({ ...d }, catalogOf(cat.objects));
+    const used = (await reportingApps(currentWorkspace(s))).filter((a) => a.datasets.includes(d.name));
+    const objCols = (table: string) => cat.objects.find((o) => o.name === table)?.columns ?? [];
+    // every column of the dataset's tables: the offered ones first (in their order), then the others
+    const rows: { ref: string; alias: string; table: string; column: string; type: string; c?: Dataset['columns'][number] }[] = [];
+    for (const c of d.columns) {
+      const t = d.tables.find((x) => x.alias === c.table)!;
+      rows.push({ ref: `${c.table}.${c.column}`, alias: c.table, table: t.table, column: c.column, type: objCols(t.table).find((x) => x.name === c.column)?.type ?? '', c });
+    }
+    for (const t of d.tables)
+      for (const col of objCols(t.table))
+        if (!d.columns.some((c) => c.table === t.alias && c.column === col.name)) rows.push({ ref: `${t.alias}.${col.name}`, alias: t.alias, table: t.table, column: col.name, type: col.type });
+    const colOptions = d.tables.flatMap((t) => objCols(t.table).map((c): [string, string] => [`${t.alias}.${c.name}`, `${t.alias} ${t.table}.${c.name}`]));
+    const shown = req.query.preview === '1' ? await preview(db, d) : null;
+    const opt = (v: string, l: string, cur: string) => html`<option value="${v}"${v === cur ? raw(' selected') : ''}>${l}</option>`;
+    const main = html`<div class="title-row"><h1>${d.label} <code>${d.name}</code></h1>
+        <div class="buttons"><a class="btn" href="${root}/datasets/${row.id}/export">${icon('download')} Download</a><a class="btn btn-hot" href="${root}/apps/new?dataset=${encodeURIComponent(d.name)}">${icon('plus')} Create reporting application</a></div></div>
+      <p class="muted u-mt0">On schema <code>${d.schema}</code>${used.length ? html` · used by ${used.map((a, i) => html`${i ? ', ' : ''}<a href="${BASE}/apps/${a.id}">${a.name}</a>`)}` : ''} · updated ${when(row.updated_at)} (UTC)${row.updated_by ? ` by ${row.updated_by}` : ''}</p>
+      ${errors.length ? html`<div class="alert alert-error" role="alert"><b>The dataset doesn't match the database (any more):</b><ul>${errors.map((e) => html`<li>${e}</li>`)}</ul></div>` : ''}
+      <form method="post" action="${root}/datasets/${row.id}">${csrf(s)}
+      ${region('Dataset', html`<div class="form-grid">
+        ${input('label', 'Label', d.label, { required: true })}
+        <div class="field" data-wide><label class="label" for="f_description">Description (shown to users)</label><input id="f_description" name="description" maxlength="${DATASET_LIMITS.description}" value="${d.description ?? ''}"></div>
+      </div>`)}
+      ${region('Tables and views', html`<div class="table-wrap"><table class="report report-reflow">
+        <thead><tr><th scope="col">Alias</th><th scope="col">Table or view</th><th scope="col">Joins to</th><th scope="col">Join</th><th scope="col">On (column = its column)</th><th scope="col">Remove</th></tr></thead><tbody>
+        ${d.tables.map((t, i) => html`<tr>
+          <td data-label="Alias"><code>${t.alias}</code><input type="hidden" name="t${i}_alias" value="${t.alias}"></td>
+          <td data-label="Table or view"><code>${t.table}</code></td>
+          ${i === 0 ? html`<td data-label="Joins to" colspan="3"><span class="muted">the main table</span></td>` : html`
+          <td data-label="Joins to"><select name="t${i}_to" aria-label="${t.table} joins to">${d.tables.slice(0, i).map((x) => opt(x.alias, `${x.alias} ${x.table}`, t.join?.to ?? ''))}</select></td>
+          <td data-label="Join"><select name="t${i}_type" aria-label="Join type of ${t.table}">${opt('left', 'Left (keep rows without a match)', t.join?.type ?? 'left')}${opt('inner', 'Inner (only matching rows)', t.join?.type ?? 'left')}</select></td>
+          <td data-label="On"><input name="t${i}_on" value="${t.join?.on.map((p) => `${p.column} = ${p.ref}`).join(', ') ?? ''}" aria-label="Join columns of ${t.table}" placeholder="deptno = deptno"></td>`}
+          <td data-label="Remove">${i === 0 ? '' : html`<input type="checkbox" name="t${i}_remove" value="true" aria-label="Remove ${t.table}">`}</td>
+        </tr>`)}</tbody></table></div>
+        ${d.tables.length < DATASET_LIMITS.tables ? html`<div class="form-grid">
+          <div class="field"><label class="label" for="f_new_table">Add a table or view</label><select id="f_new_table" name="new_table"><option value="">- none -</option>${cat.objects.map((o) => html`<option value="${o.name}">${o.name} (${o.kind})</option>`)}</select></div>
+          <div class="field"><label class="label" for="f_new_to">Joined to</label><select id="f_new_to" name="new_to">${d.tables.map((x) => opt(x.alias, `${x.alias} ${x.table}`, ''))}</select></div>
+          <div class="field"><label class="label" for="f_new_on">On</label><input id="f_new_on" name="new_on" placeholder="from a foreign key"><small class="help">Empty: proposed from a foreign key.</small></div>
+        </div>` : ''}`)}
+      ${region('Columns', html`<p class="muted u-mt0">Business users see only the offered columns, under their labels. The name is how reports refer to a column: changing it breaks saved reports that use it.</p>
+        <div class="table-wrap"><table class="report report-reflow dataset-columns">
+        <thead><tr><th scope="col">Offer</th><th scope="col">Column</th><th scope="col">Name</th><th scope="col">Label</th><th scope="col">Format mask</th><th scope="col">Description</th></tr></thead><tbody>
+        ${rows.map((r, j) => html`<tr>
+          <td data-label="Offer"><input type="hidden" name="c${j}_ref" value="${r.ref}"><input type="checkbox" name="c${j}_on" value="true"${r.c ? raw(' checked') : ''} aria-label="Offer ${r.table}.${r.column}"></td>
+          <td data-label="Column"><code>${r.alias}.${r.column}</code> <span class="muted">${r.type}</span></td>
+          <td data-label="Name"><input name="c${j}_name" maxlength="40" value="${r.c?.name ?? r.column.toLowerCase()}" aria-label="Name of ${r.table}.${r.column}"></td>
+          <td data-label="Label"><input name="c${j}_label" maxlength="${DATASET_LIMITS.label}" value="${r.c?.label ?? ''}" placeholder="${heading(r.column)}" aria-label="Label of ${r.table}.${r.column}"></td>
+          <td data-label="Format mask"><input name="c${j}_format" maxlength="${DATASET_LIMITS.format}" value="${r.c?.format ?? ''}" placeholder="999G990D00" aria-label="Format mask of ${r.table}.${r.column}"></td>
+          <td data-label="Description"><input name="c${j}_desc" maxlength="${DATASET_LIMITS.columnDescription}" value="${r.c?.description ?? ''}" aria-label="Description of ${r.table}.${r.column}"></td>
+        </tr>`)}</tbody></table></div>`)}
+      ${region('Row filter', html`<p class="muted u-mt0">Only rows that match every condition are in the dataset (on top of the application role's row level security).</p>
+        ${Array.from({ length: DATASET_LIMITS.filters }, (_, k) => {
+          const f = d.filters[k];
+          return html`<div class="dataset-filter">
+            <select name="f${k}_col" aria-label="Filter ${k + 1}: column">${opt('', '- none -', '')}${colOptions.map(([v, l]) => opt(v, l, f ? `${f.table}.${f.column}` : ''))}</select>
+            <select name="f${k}_op" aria-label="Filter ${k + 1}: operator">${Object.keys(OPERATORS).map((o) => opt(o, opLabel(english, o), f?.op ?? 'eq'))}</select>
+            <input name="f${k}_value" maxlength="${DATASET_LIMITS.value}" value="${f?.value ?? ''}" aria-label="Filter ${k + 1}: value" placeholder="value">
+          </div>`;
+        })}`)}
+      <div class="buttons"><button class="btn btn-hot">${icon('save')} Save dataset</button></div>
+      </form>
+      ${region('Query and preview', html`<p class="muted u-mt0">The query reports run on (as the application's role). The preview runs it read only through your SQL Workshop connection.</p>
+        <pre class="code" data-code-view="sql">${datasetSql(d)}</pre>
+        <p><a class="btn" href="${root}/datasets/${row.id}?preview=1#preview">${icon('play')} Preview ${PREVIEW_ROWS} rows</a></p>
+        ${shown ? 'error' in shown ? html`<div class="alert alert-error" role="alert" id="preview">${shown.error}</div>` : html`<div class="table-wrap" id="preview"><table class="report report-reflow"><thead><tr>${shown.fields.map((f) => html`<th scope="col">${d.columns.find((c) => c.name === f)?.label ?? f}</th>`)}</tr></thead>
+          <tbody>${shown.rows.length ? shown.rows.map((r) => html`<tr>${r.map((v, i) => html`<td data-label="${shown.fields[i]}">${cellText(v)}</td>`)}</tr>`) : html`<tr><td colspan="${shown.fields.length}" class="empty">No rows.</td></tr>`}</tbody></table></div>` : ''}`)}
+      ${region('Delete', html`<form method="post" action="${root}/datasets/${row.id}/delete">${csrf(s)}
+        <p class="muted u-mt0">${used.length ? `Reporting applications using it (${used.map((a) => a.name).join(', ')}) lose this data source: their reports on it stop working.` : 'No reporting application uses it.'}</p>
+        <button class="btn btn-danger" data-confirm="Delete the dataset ${d.name}?">${icon('trash')} Delete dataset</button></form>`)}`;
+    return page(s, reply, d.label, [[d.label]], main);
+  });
+
+  app.post(`${root}/datasets/:id`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const row = await datasetRow(s, req.params.id);
+    if (!row) return reply.code(404).send('Not found');
+    const d = datasetOf(row);
+    const db = await workshopDb(s);
+    if (!(await usableSchema(db, d.schema))) {
+      flash(s, `Your SQL Workshop connection may not use the schema ${d.schema}.`, 'error');
+      return back(reply, s, `${root}/datasets/${row.id}`);
+    }
+    const cat = await readSchemaCatalog(db, d.schema);
+    const { dataset, errors } = checkDataset(datasetFromForm(d, req.body ?? {}, cat), catalogOf(cat.objects));
+    if (!dataset.tables.length || !dataset.columns.length) {
+      flash(s, [...errors, 'A dataset needs a table and at least one offered column: nothing was saved.'].join(' '), 'error');
+      return back(reply, s, `${root}/datasets/${row.id}`);
+    }
+    await storeDataset(owner, row.workspace_id, dataset, s.username);
+    logActivity({ appId: null, username: s.username, event: 'dataset_save', ip: clientIp(req), detail: dataset.name });
+    flash(s, errors.length ? `Saved, but: ${errors.join(' ')}` : 'Dataset saved.', errors.length ? 'error' : 'ok');
+    return back(reply, s, `${root}/datasets/${row.id}`);
+  });
+
+  app.post(`${root}/datasets/:id/delete`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const row = await datasetRow(s, req.params.id);
+    if (!row) return reply.code(404).send('Not found');
+    await owner.query('delete from meta.dataset where id = $1', [row.id]);
+    logActivity({ appId: null, username: s.username, event: 'dataset_delete', ip: clientIp(req), detail: row.name });
+    flash(s, `Dataset ${row.name} deleted.`);
+    return back(reply, s, root);
+  });
+
+  // ---------------------------------------------------------------- files
+  const download = (reply: FastifyReply, name: string, list: Dataset[]) =>
+    reply.type('application/json').header('content-disposition', `attachment; filename="${name}.dataset.json"`).send(datasetFile(list));
+
+  app.get(`${root}/datasets/:id/export`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const row = await datasetRow(s, req.params.id);
+    if (!row) return reply.code(404).send('Not found');
+    return download(reply, row.name, [datasetOf(row)]);
+  });
+
+  app.get(`${root}/export`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const list = (await workspaceDatasets(owner, currentWorkspace(s))).map(datasetOf);
+    return download(reply, 'datasets', list);
+  });
+
+  app.get(`${root}/import`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const main = html`<h1>Import datasets</h1>
+      ${region('A dataset file', html`<form method="post" action="${root}/import" enctype="multipart/form-data">${csrf(s)}
+        <p class="muted u-mt0">A file downloaded from a Data Reporter (<code>*.dataset.json</code>, format pgkiln-dataset/1), with one dataset or several. Each is checked against this installation's database: its schema, tables, views and columns must exist here.</p>
+        <div class="form-grid">
+          <div class="field"><label class="label" for="f_file">File</label><input id="f_file" type="file" name="file" accept=".json,application/json"></div>
+          <div class="field" data-wide><label class="label" for="f_text">Or paste it</label><textarea id="f_text" name="text" class="code" rows="5" spellcheck="false"></textarea></div>
+          <div class="field"><label class="check"><input type="checkbox" name="replace" value="true"> Replace datasets with the same name</label></div>
+        </div>
+        <div class="buttons"><a class="btn" href="${root}">Cancel</a><button class="btn btn-hot">${icon('upload')} Import</button></div></form>`)}`;
+    return page(s, reply, 'Import datasets', [['Import']], main);
+  });
+
+  app.post(`${root}/import`, async (req: Req, reply) => {
+    // a multipart form: the session and CSRF token are checked after reading it
+    let text = '';
+    let tooLarge = false;
+    if (req.isMultipart()) {
+      const parsed = await readMultipart(req, MAX_FILE_BYTES / 1024 / 1024);
+      req.body = parsed.body as Body;
+      const f = parsed.files.get('file');
+      if (f?.truncated) tooLarge = true;
+      else if (f) text = f.data.toString('utf8');
+    }
+    const s = await developer(req, reply);
+    if (!s) return;
+    const fail = (msg: string) => (flash(s, msg, 'error'), back(reply, s, `${root}/import`));
+    if (tooLarge) return fail('The file is larger than 2 MB.');
+    if (!text.trim()) text = String(req.body?.text ?? '');
+    if (!text.trim()) return fail('Choose a file or paste one.');
+    let list: any[];
+    try {
+      list = readDatasetFile(text);
+    } catch (e) {
+      return fail((e as Error).message);
+    }
+    const db = await workshopDb(s);
+    const schemas = await usableSchemas(db);
+    const ws = currentWorkspace(s);
+    const replace = req.body?.replace === 'true';
+    const lines: string[] = [];
+    try {
+      await owner.tx(async (c) => {
+        const cats = new Map<string, Awaited<ReturnType<typeof readSchemaCatalog>>>();
+        for (const loose of list) {
+          const schema = typeof loose?.schema === 'string' ? loose.schema : '';
+          const name = typeof loose?.name === 'string' ? loose.name : '?';
+          if (!schemas.includes(schema)) throw new Error(`Dataset ${name}: the schema "${schema}" doesn't exist here, or your SQL Workshop connection may not use it.`);
+          if (!cats.has(schema)) cats.set(schema, await readSchemaCatalog(db, schema));
+          const { dataset, errors } = checkDataset(loose, catalogOf(cats.get(schema)!.objects));
+          if (errors.length || !dataset.columns.length) throw new Error(`Dataset ${name}: ${errors.join(' ') || 'it offers no columns.'}`);
+          const exists = (await c.query('select 1 from meta.dataset where workspace_id = $1 and name = $2', [ws, dataset.name])).rowCount;
+          if (exists && !replace) {
+            lines.push(`${dataset.name}: kept (same name)`);
+            continue;
+          }
+          await storeDataset(c, ws, dataset, s.username);
+          lines.push(`${dataset.name}: ${exists ? 'replaced' : 'added'}`);
+        }
+      });
+    } catch (e) {
+      return fail(`Nothing was imported. ${(e as Error).message}`);
+    }
+    logActivity({ appId: null, username: s.username, event: 'dataset_import', ip: clientIp(req), detail: lines.join('; ') });
+    flash(s, `Imported: ${lines.join('; ')}.`);
+    return back(reply, s, root);
+  });
+
+  // ---------------------------------------------------------------- create a reporting application
+  const appForm = async (s: Session, b: Body & { datasets?: string | string[] }, sets: DatasetRow[], error?: string) => {
+    const chosen = new Set(Array.isArray(b.datasets) ? b.datasets : b.datasets ? [b.datasets] : []);
+    return html`<h1>Create a reporting application</h1>
+      ${error ? html`<div class="alert alert-error" role="alert">${error}</div>` : ''}
+      <form method="post" action="${root}/apps">${csrf(s)}
+      ${region('Application', html`<div class="form-grid">
+        ${input('name', 'Name', b.name ?? '', { required: true })}
+        ${input('alias', 'Alias', b.alias ?? '', { required: true, help: 'Its address: /a/<alias>. Its database role is app_<alias>, which may only read the datasets\' tables and views.' })}
+        ${input('admin_user', 'First administrator', b.admin_user ?? s.username ?? '', { required: true, help: 'An account of the user directory (users sign in with their workspace accounts).' })}
+        ${input('admin_password', 'Password', '', { type: 'password', auto: 'new-password', help: 'Only for a new account.' })}
+      </div>`)}
+      ${region('Datasets', html`<div class="dataset-checks">${sets.map((d) => html`<label class="check"><input type="checkbox" name="datasets" value="${d.name}"${chosen.has(d.name) ? raw(' checked') : ''}> ${d.label} <code>${d.name}</code> <span class="muted">${d.schema_name}: ${d.tables.map((t) => t.table).join(', ')}</span></label>`)}</div>
+        <small class="help">The first dataset's schema is the application's parsing schema.</small>`)}
+      <div class="buttons"><a class="btn" href="${root}">Cancel</a><button class="btn btn-hot">${icon('plus')} Create</button></div></form>`;
+  };
+
+  app.get(`${root}/apps/new`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const sets = await workspaceDatasets(owner, currentWorkspace(s));
+    if (!sets.length) {
+      flash(s, 'Create a dataset first.', 'error');
+      return back(reply, s, root);
+    }
+    const first = sets.find((d) => d.name === req.query.dataset) ?? sets[0];
+    const base = first.name.replace(/_/g, '-').slice(0, 40);
+    return page(s, reply, 'Create reporting application', [['Create reporting application']],
+      await appForm(s, { name: `${first.label} reports`, alias: `${base}-reports`, datasets: first.name }, sets));
+  });
+
+  app.post(`${root}/apps`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const b = (req.body ?? {}) as Body & { datasets?: string | string[] };
+    const sets = await workspaceDatasets(owner, currentWorkspace(s));
+    const names = Array.isArray(b.datasets) ? b.datasets : b.datasets ? [b.datasets] : [];
+    const chosen = names.map((n) => sets.find((d) => d.name === n)).filter((d): d is DatasetRow => !!d);
+    const failed = async (msg: string) => {
+      reply.code(422);
+      return page(s, reply, 'Create reporting application', [['Create reporting application']], await appForm(s, b, sets, msg));
+    };
+    if (!chosen.length) return failed('Choose at least one dataset.');
+    if (chosen.length > MAX_REPORTING_DATASETS) return failed(`Choose at most ${MAX_REPORTING_DATASETS} datasets.`);
+    let created: { id: number; existingAccount: boolean };
+    let alias = '';
+    try {
+      const checked = await checkNewApp({ name: b.name, alias: b.alias, schema: chosen[0].schema_name, authentication: 'app_users', admin_user: b.admin_user, admin_password: b.admin_password }, currentWorkspace(s));
+      alias = checked.alias;
+      created = await owner.tx((c) => createReportingApp(c, checked, chosen));
+    } catch (e) {
+      return failed(createAppError(e, alias || String(b.alias ?? '')));
+    }
+    logActivity({ appId: created.id, username: s.username, event: 'app_create', ip: clientIp(req), detail: `reporting application on ${chosen.map((d) => d.name).join(', ')}` });
+    flash(s, `Reporting application ${b.name} created: run it at /a/${alias}/, and give accounts access and the roles viewer, editor or administrator under Users and roles.`);
+    return back(reply, s, root);
+  });
+}