tablewalk 0.0.1

package/dist/client/connmanager.js

@@ -0,0 +1,962 @@
+/**
+ * Connections, as a place rather than a dropdown.
+ *
+ * The picker in the sidebar answers "switch to another database" and nothing
+ * else. Everything a person actually wants to do with a connection — see why
+ * one will not open, correct a typed host, notice that a password is sitting
+ * in a URL, remove one they added by mistake, make a session connection
+ * permanent — had no home at all.
+ *
+ * Three ideas hold this together:
+ *
+ *   - **A connection is a card, not a row.** Its state is not one value: it
+ *     has a target, a dialect, whether it is open, how many tables it found,
+ *     where its password came from, and whether anything is worth warning
+ *     about. A table of columns would either drop most of that or be unreadable.
+ *
+ *   - **Editing is session-scoped until you say otherwise.** Changes take
+ *     effect immediately in the running process and touch no file. Writing
+ *     them to disk is a separate button that names the file it is about to
+ *     write. A page that silently edits a config file is a surprise, and this
+ *     tool's whole argument is against surprises.
+ *
+ *   - **Failure is shown, not hidden.** A connection that cannot open stays in
+ *     the list with its error, because a database missing from the list looks
+ *     like one you never configured.
+ */
+import { $, api, el, render, state, toast, trapFocus } from './core.js';
+import { promptFor } from './prompt.js';
+import { dropdown } from './dropdown.js';
+import { selectConnection } from './connections.js';
+import {
+  DEFAULT_PORTS, DRIVERS, buildConnectionUrl, isEnvReference, looksSchemeless, parseConnectionUrl,
+  redactConnectionUrl,
+} from './connurl.js';
+
+let panel = null;
+/** Undoes the focus trap, and hands the keyboard back where it came from. */
+let release = null;
+
+/** Latest list from the server, so a redraw does not need a round trip. */
+let connections = [];
+let configFile = null;
+/** Connections currently being introspected, by id. */
+const busy = new Set();
+
+export function connectionsOpen() {
+  return Boolean(panel);
+}
+
+export async function openConnections() {
+  if (panel) return;
+  panel = el('div', { class: 'conn-manager', role: 'dialog', 'aria-modal': 'true', 'aria-label': 'Connections' });
+  document.body.append(panel);
+  release = trapFocus(panel);
+  document.addEventListener('keydown', onKey, true);
+  paint({ loading: true });
+  await refresh();
+}
+
+function close() {
+  release?.();
+  release = null;
+  panel?.remove();
+  panel = null;
+  document.removeEventListener('keydown', onKey, true);
+}
+
+function onKey(e) {
+  if (e.key !== 'Escape') return;
+  // Not while a dialog of our own is on top of us, and not mid-edit.
+  if (document.querySelector('dialog[open]')) return;
+  const tag = document.activeElement?.tagName;
+  if (tag === 'INPUT' || tag === 'TEXTAREA') { document.activeElement.blur(); return; }
+  e.preventDefault();
+  close();
+}
+
+async function refresh() {
+  try {
+    const data = await api('/api/connections');
+    connections = data.connections ?? [];
+    if (data.active) state.activeConnection = data.active;
+  } catch (err) {
+    toast(err.message, 'error');
+  }
+  paint();
+}
+
+/** Run something that changes the list, then redraw from the server's answer. */
+async function mutate(path, body, { success } = {}) {
+  try {
+    const data = await api(path, body);
+    if (data.connections) connections = data.connections;
+    if (data.active) state.activeConnection = data.active;
+    paint();
+    if (success) toast(success(data), 'ok');
+    return data;
+  } catch (err) {
+    toast(err.message, 'error');
+    await refresh();
+    return null;
+  }
+}
+
+/* ---------- rendering ---------- */
+
+/** What the reader has typed into the filter. Kept across redraws. */
+let needle = '';
+/** Keyboard cursor into the filtered list. */
+let cursor = -1;
+
+function matching() {
+  const q = needle.trim().toLowerCase();
+  if (!q) return connections;
+  return connections.filter((c) =>
+    `${c.name} ${c.detail} ${c.dialect} ${c.source}`.toLowerCase().includes(q));
+}
+
+function paint({ loading = false } = {}) {
+  if (!panel) return;
+
+  const filter = el('input', {
+    type: 'search',
+    class: 'conn-filter',
+    placeholder: 'Filter connections…',
+    'aria-label': 'Filter connections',
+    value: needle,
+    oninput: (e) => {
+      needle = e.target.value;
+      cursor = -1;
+      paint();
+      // Repainting replaces the field, so the caret has to be put back.
+      const next = panel.querySelector('.conn-filter');
+      next.focus();
+      next.setSelectionRange(next.value.length, next.value.length);
+    },
+    onkeydown: onFilterKey,
+  });
+
+  const head = el('div', { class: 'conn-head' }, [
+    el('div', { class: 'conn-head-titles' }, [
+      /* The screen is full-bleed on purpose — a place you finish and leave —
+         but a place with no wordmark read as a different application: the
+         chrome vanished and the URL still named a table. The mark says whose
+         house this room is in. */
+      el('div', { class: 'conn-brand', 'aria-hidden': 'true' }, [
+        el('span', { class: 'brand-mark' }),
+        el('span', { class: 'conn-brand-name', text: 'tablewalk' }),
+      ]),
+      el('h2', { text: 'Connections' }),
+      el('p', {
+        class: 'conn-lede',
+        text: 'Changes apply to this session straight away. Nothing is written to disk until you save.',
+      }),
+    ]),
+    el('div', { class: 'conn-head-actions' }, [
+      el('button', { type: 'button', class: 'ghost', text: '+ Add', onclick: () => void addDialog() }),
+      el('button', { type: 'button', class: 'ghost', text: 'Save to file…', onclick: () => void saveDialog() }),
+      el('button', { type: 'button', text: 'Done', onclick: close }),
+    ]),
+  ]);
+
+  const shown = matching();
+  const list = el('div', { class: 'conn-list', role: 'listbox', 'aria-label': 'Connections' });
+
+  if (loading) {
+    list.append(el('p', { class: 'loading', text: 'Reading connections…' }));
+  } else if (!connections.length) {
+    list.append(el('p', { class: 'note', text: 'No connections. Add one to get started.' }));
+  } else if (!shown.length) {
+    list.append(el('p', { class: 'note', text: `Nothing matches "${needle.trim()}".` }));
+  } else {
+    shown.forEach((conn, i) => list.append(row(conn, i)));
+  }
+
+  panel.replaceChildren(el('div', { class: 'conn-inner' }, [
+    head,
+    el('div', { class: 'conn-toolbar' }, [
+      filter,
+      el('span', {
+        class: 'conn-count',
+        text: needle.trim()
+          ? `${shown.length} of ${connections.length}`
+          : `${connections.length} connection${connections.length === 1 ? '' : 's'}`,
+      }),
+    ]),
+    list,
+    footnote(),
+  ]));
+}
+
+function onFilterKey(e) {
+  const shown = matching();
+  if (e.key === 'ArrowDown') {
+    e.preventDefault();
+    move(cursor + 1, shown.length);
+  } else if (e.key === 'ArrowUp') {
+    e.preventDefault();
+    move(cursor - 1, shown.length);
+  } else if (e.key === 'Enter') {
+    e.preventDefault();
+    // No explicit highlight means the obvious one: the only match, or the first.
+    const conn = shown[cursor >= 0 ? cursor : 0];
+    if (conn) void open(conn);
+  }
+}
+
+function move(next, total) {
+  if (!total) return;
+  cursor = (next + total) % total;
+  const rows = [...panel.querySelectorAll('.conn-row')];
+  rows.forEach((node, i) => {
+    node.classList.toggle('cursor', i === cursor);
+    node.setAttribute('aria-selected', String(i === cursor));
+  });
+  rows[cursor]?.scrollIntoView({ block: 'nearest' });
+}
+
+async function open(conn) {
+  if (conn.id === state.activeConnection) { close(); return; }
+  close();
+  await selectConnection(conn.id);
+}
+
+/**
+ * One connection, one line.
+ *
+ * Cards were legible and did not scale: at 170 pixels each, fifty connections
+ * is eight thousand pixels of scrolling to find one name. A row is forty, and
+ * the filter above means you rarely scroll at all.
+ *
+ * Nothing is dropped to get there — the target, the state, the table count and
+ * the password source all still show. What moves is the *actions*, which
+ * appear on hover or focus. They are the same four for every row, so a
+ * permanent copy beside each one is fifty repetitions of a fixed list.
+ */
+function row(conn, index) {
+  const active = conn.id === state.activeConnection;
+
+  const status = busy.has(conn.id)
+    ? { tone: 'busy', text: 'reading…' }
+    : conn.error
+      ? { tone: 'bad', text: 'will not open' }
+      : conn.connected
+        ? { tone: 'ok', text: `${conn.tables ?? 0} table${conn.tables === 1 ? '' : 's'}` }
+        : { tone: 'idle', text: 'not opened' };
+
+  const action = (label, title, onclick, extra = '') =>
+    el('button', {
+      type: 'button', class: `conn-action ${extra}`, title, text: label,
+      // The row itself opens the connection; an action inside it must not
+      // also do that on its way through.
+      onclick: (e) => { e.stopPropagation(); onclick(); },
+    });
+
+  return el('div', {
+    class: `conn-row${active ? ' active' : ''}${conn.error ? ' failed' : ''}${index === cursor ? ' cursor' : ''}${busy.has(conn.id) ? ' busy' : ''}`,
+    role: 'option',
+    'aria-selected': String(index === cursor),
+    tabindex: 0,
+    title: active ? 'Already open' : `Open ${conn.name}`,
+    onclick: () => void open(conn),
+    onkeydown: (e) => {
+      if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); void open(conn); }
+    },
+  }, [
+    el('span', { class: `conn-dot ${status.tone}`, 'aria-hidden': 'true' }),
+
+    el('span', { class: 'conn-name' }, [
+      el('span', { class: 'conn-name-text', text: conn.name }),
+      active ? el('span', { class: 'conn-badge current', text: 'current' }) : null,
+    ].filter(Boolean)),
+
+    // Host and database, or a file name. Never a password.
+    el('span', { class: 'conn-detail', title: conn.detail, text: conn.detail }),
+
+    el('span', { class: 'conn-meta' }, [
+      el('span', { class: 'conn-badge', text: conn.dialect }),
+      el('span', { class: `conn-badge source-${conn.source}`, text: conn.source }),
+      conn.secret && conn.secret !== 'none'
+        ? el('span', { class: 'conn-badge', title: `Password from ${conn.secret}`, text: conn.secret })
+        : null,
+      /* Said where the connection is chosen, not discovered when a query
+         comes back refused: this one answers the schema and nothing out of
+         its rows. */
+      conn.rows === false
+        ? el('span', {
+            class: 'conn-badge shape-only',
+            title: 'Shape only: the catalog, counts and plans answer; no row values leave this connection.',
+            text: 'shape only',
+          })
+        : null,
+    ].filter(Boolean)),
+
+    el('span', { class: `conn-status ${status.tone}`, text: status.text }),
+
+    el('span', { class: 'conn-actions' }, [
+      action('Edit', `Edit ${conn.name}`, () => void editDialog(conn)),
+      busy.has(conn.id)
+        ? el('span', { class: 'conn-action working', text: 'Introspecting…' })
+        : action('Introspect', 'Read this database\u2019s schema again', () => void introspect(conn)),
+      action('Remove', `Remove ${conn.name}`, () => void removeConnection(conn), 'conn-remove'),
+    ]),
+
+    /* The reason a row is red, on its own line under it. A one-line list has
+       nowhere to put an error message, and an error hidden in a tooltip is an
+       error nobody reads. */
+    conn.error ? el('p', { class: 'conn-error', text: conn.error }) : null,
+    conn.warning ? el('p', { class: 'conn-warning', text: conn.warning }) : null,
+  ].filter(Boolean));
+}
+
+function footnote() {
+  /* Said once, in the place where someone is about to type a password into a
+     text field, rather than in a README they will not be reading at the time. */
+  return el('div', { class: 'conn-note' }, [
+    el('p', { text: 'Passwords: tablewalk stores none of its own.' }),
+    el('ul', {}, [
+      el('li', { text: 'postgres://app:${PROD_PASSWORD}@host/db — expanded from the environment, never stored.' }),
+      el('li', { text: 'The macOS keychain, looked up by connection name.' }),
+      el('li', { text: 'A credentials file at mode 600, refused if anyone else can read it.' }),
+    ]),
+  ]);
+}
+
+/* ---------- actions ---------- */
+
+/**
+ * Read a database's schema again, saying so while it happens.
+ *
+ * Introspection is not instant — a Postgres catalog query across sixty tables
+ * takes long enough to notice, and a remote database over a slow link takes
+ * much longer. A button that does nothing visible for four seconds looks
+ * broken, and the second click that produces is a second full introspection.
+ *
+ * So the row shows its own state: the action becomes a label, the status
+ * becomes "reading…", the row is marked, and the button cannot be pressed
+ * again. The request itself is left to run in the background — nothing is
+ * blocked while it does, and the rest of the manager stays usable.
+ */
+async function introspect(conn) {
+  busy.add(conn.id);
+  paint();
+  try {
+    await api('/api/connections/refresh', { id: conn.id });
+    toast(`Read ${conn.name}\u2019s schema again.`, 'ok');
+  } catch (err) {
+    toast(err.message, 'error');
+  } finally {
+    busy.delete(conn.id);
+    // Refreshed from the server rather than patched locally: the table count
+    // and any error are what the introspection was for.
+    await refresh();
+  }
+}
+
+async function removeConnection(conn) {
+  const typed = await promptFor({
+    title: `Remove "${conn.name}"?`,
+    label: 'Type the name to confirm',
+    hint:
+      conn.source === 'config'
+        ? 'This connection came from the config file. Removing it here affects this session only, until you save.'
+        : 'Removing it here affects this session only.',
+    placeholder: conn.name,
+  });
+  if (typed?.trim() !== conn.name) {
+    if (typed !== null && typed !== undefined) toast('Names did not match — nothing removed.', 'error');
+    return;
+  }
+  const data = await mutate('/api/connections/remove', { id: conn.id }, { success: () => `Removed ${conn.name}.` });
+  /* Removing the last one leaves a page whose sidebar, query bar and grid all
+     describe a database that is gone. The first-run screen is the honest view
+     of that, and boot is the only thing that draws it — so the same reload
+     the first-run screen uses on the way in is used on the way back out. */
+  if (data && !data.connections?.length) window.location.reload();
+}
+
+function urlField(value) {
+  return el('input', {
+    type: 'text',
+    class: 'cell-edit',
+    value: value ?? '',
+    placeholder: 'postgres://user@host/db  or  /path/to/file.db',
+    /* A placeholder is not a label: it disappears the moment there is a value
+       in the box, which is exactly when someone re-reading the form needs to
+       know what the box is. */
+    'aria-label': 'Connection URL or file path',
+    spellcheck: 'false',
+  });
+}
+
+/** The shared shape of Add and Edit: same fields, different verb. */
+function connectionDialog({ title, name: nameValue, url: urlValue, schemas: schemasValue, verb, run }) {
+  /* Two ways to say the same thing.
+  
+     One box wanting `postgres://user:password@host:5432/db` is fine if you
+     already know the shape and unhelpful if you do not — and the people most
+     likely not to know are the ones this tool is for. Pasting is still how
+     most connections start, from a colleague or a dashboard, so both are
+     offered and kept in sync: `connurl.js` is the pair of pure functions that
+     lets them be the same thing rather than two forms that disagree. */
+  const url = urlField(urlValue);
+  const name = el('input', {
+    type: 'text', class: 'cell-edit', value: nameValue ?? '',
+    placeholder: 'Optional name', 'aria-label': 'Connection name',
+  });
+
+  /**
+   * What to call it, if nobody says.
+   *
+   * Left blank, the server falls back to the public form of the URL —
+   * `postgres@127.0.0.1/tablewalk` — which is correct, unambiguous, and
+   * thirty characters of mostly punctuation in the top bar, in the sidebar
+   * heading, and slugged into every link as `postgres-127-0-0-1-tablewalk`.
+   * It is also the one part that cannot be fixed afterwards: renaming changes
+   * the label and deliberately not the id, because the id is what saved
+   * links, pages and layouts already point at.
+   *
+   * The database's own name is what people call it out loud, so that is the
+   * suggestion. It goes in the placeholder rather than the value, so the box
+   * still reads as optional and still shows what leaving it empty will do —
+   * and it is sent when empty, rather than left for the server to guess
+   * something longer.
+   */
+  const suggestedName = () => (parts.driver === 'sqlite'
+    ? String(parts.file ?? '').split('/').pop() ?? ''
+    : parts.database || parts.host || '').trim();
+
+  /** What to file it under: what they typed, or the suggestion. */
+  const chosenName = () => name.value.trim() || suggestedName();
+
+  /**
+   * `user@host/db` with no `://`, and the one click that fixes it.
+   *
+   * The name tablewalk prints for a connection is its public URL form —
+   * `postgres@127.0.0.1/tablewalk` — so copying what the app showed you and
+   * pasting it back is a completely reasonable thing to do, and it landed in
+   * the file path branch and failed with "unable to open database file".
+   *
+   * Which driver it wants is the one thing the string does not say, so it is
+   * asked rather than guessed: two buttons, one click, and the paste is
+   * re-read as what it plainly was.
+   */
+  const schemeHint = el('p', { class: 'conn-scheme-hint', hidden: true });
+
+  function paintSchemeHint() {
+    const missing = looksSchemeless(url.value);
+    schemeHint.hidden = !missing;
+    if (!missing) return;
+    const repair = (scheme) => el('button', {
+      type: 'button',
+      class: 'conn-scheme-fix',
+      text: `${scheme}://`,
+      onclick: () => {
+        url.value = `${scheme}://${url.value.trim()}`;
+        url.dispatchEvent(new Event('input'));
+        url.focus();
+      },
+    });
+    schemeHint.replaceChildren(
+      el('span', { text: 'No scheme, so this is being read as a file path. Add one:' }),
+      repair('postgres'),
+      repair('mysql'),
+    );
+  }
+  const schemas = el('input', {
+    type: 'text', class: 'cell-edit', spellcheck: 'false',
+    value: (schemasValue ?? []).join(', '),
+    placeholder: 'public  (Postgres only, comma separated)',
+    'aria-label': 'Postgres schemas to browse',
+  });
+/**
+   * What happened, when something happens.
+   *
+   * This was a `<p class="note">` sitting between the Schemas field and the
+   * fine print, in the same grey as both — so the one line on the form that
+   * answers a question you just asked read as more static help text. Somebody
+   * pressed Test and had to hunt for the reply.
+   *
+   * It is a block with a mark on it now, coloured by outcome, and it sits
+   * against the buttons rather than in the middle of the fields. `role=status`
+   * because the whole point is that it appears after an action, and a screen
+   * reader has even less chance of noticing a paragraph quietly changing
+   * halfway up a dialog.
+   */
+  const result = el('div', {
+    class: 'conn-result', hidden: true, role: 'status', 'aria-live': 'polite',
+  });
+
+  function showResult(ok, text, detail) {
+    result.hidden = false;
+    result.className = `conn-result ${ok ? 'ok' : 'bad'}`;
+    result.replaceChildren(
+      el('span', { class: 'conn-result-mark', 'aria-hidden': 'true', text: ok ? '✓' : '✕' }),
+      el('div', {}, [
+        el('p', { class: 'conn-result-text', text }),
+        ...(detail ? [el('p', { class: 'conn-result-detail', text: detail })] : []),
+      ]),
+    );
+    /* The form is taller than the screen on a laptop, and this sits at the
+       bottom of it — so on the one press where somebody is waiting for an
+       answer, the answer could arrive below the fold. `nearest` scrolls only
+       when it has to, which leaves the common case where the whole dialog
+       fits exactly where it was. */
+    result.scrollIntoView({ block: 'nearest' });
+  }
+
+  let parts = parseConnectionUrl(urlValue ?? '');
+
+  const field = (label, key, attrs = {}) => {
+    const input = el('input', {
+      type: 'text', class: 'cell-edit', spellcheck: 'false',
+      value: parts[key] ?? '', 'aria-label': label, ...attrs,
+    });
+    input.addEventListener('input', () => {
+      parts = { ...parts, [key]: input.value };
+      syncFromParts();
+    });
+    return { input, row: el('label', { class: 'field-stack' }, [el('span', { text: label }), input]) };
+  };
+
+  /* The app's own dropdown, like the connection picker and the page size — a
+     native `<select>` opens a system popup in the middle of a dialog that has
+     its own look, and reads as something the page did not draw. */
+  const driver = dropdown({
+    ariaLabel: 'Driver',
+    value: parts.driver,
+    items: DRIVERS.map((d) => ({ value: d, label: d })),
+    onChange: (chosen) => {
+      parts = { ...parts, driver: chosen };
+      syncFromParts();
+      paintForm();
+    },
+  });
+  const driverRow = el('label', { class: 'field-stack' }, [el('span', { text: 'Driver' }), driver]);
+
+  const host = field('Host', 'host', { placeholder: '127.0.0.1' });
+  const port = field('Port', 'port', { placeholder: String(DEFAULT_PORTS[parts.driver] ?? ''), inputmode: 'numeric' });
+  const database = field('Database', 'database', { placeholder: 'appdb' });
+  const user = field('User', 'user', { placeholder: 'postgres' });
+  /* A real password field. The value is about to be moved to the keychain on
+     save, and until then it should not be sitting on screen in plain text
+     where a shoulder or a screen share can reach it. */
+  /* Where the password comes from, offered at the moment somebody is deciding.
+  
+     The panel behind this dialog has always listed the options — an
+     environment reference, the keychain, a credentials file — and the form
+     offered one box, so the only one anybody met was the worst one. A
+     reference is the arrangement the documentation recommends first and it
+     stores nothing anywhere; it deserves to be a choice rather than a fact
+     you have to already know to type. */
+  let secretMode = /^\$\{?[A-Za-z_]/.test(parts.password ?? '') ? 'env' : 'typed';
+  const envName = (value) => String(value ?? '').replace(/^\$\{?/, '').replace(/\}$/, '');
+
+  const password = field('Password', 'password', { type: 'password', placeholder: 'kept out of the config file' });
+  /* Its own input: a variable name is not a secret and must not be masked —
+     the whole value of seeing it is catching a misspelling. */
+  const envVar = el('input', {
+    type: 'text', class: 'cell-edit', spellcheck: 'false',
+    value: envName(parts.password), 'aria-label': 'Environment variable',
+    placeholder: 'PROD_PASSWORD',
+  });
+  envVar.addEventListener('input', () => {
+    parts = { ...parts, password: envVar.value.trim() ? `\${${envVar.value.trim()}}` : '' };
+    syncFromParts();
+  });
+
+  const secretTab = (label, which, hint) => el('button', {
+    type: 'button',
+    class: `conn-tab${secretMode === which ? ' active' : ''}`,
+    'aria-pressed': String(secretMode === which),
+    title: hint,
+    text: label,
+    onclick: () => {
+      secretMode = which;
+      /* Switching clears rather than converts: `${PROD_PASSWORD}` is not a
+         password anyone typed, and a literal turned into a variable name
+         would be a guess about what they meant. */
+      parts = { ...parts, password: '' };
+      password.input.value = '';
+      envVar.value = '';
+      syncFromParts();
+      paintSecret();
+    },
+  });
+
+  const secretRow = el('div', { class: 'field-stack conn-secret' });
+  function paintSecret() {
+    secretRow.replaceChildren(
+      el('div', { class: 'conn-secret-head' }, [
+        el('span', { text: 'Password' }),
+        el('div', { class: 'conn-tabs conn-tabs-small' }, [
+          secretTab('Type it', 'typed', 'Moved to the keychain when you save to a file'),
+          secretTab('From the environment', 'env', 'Stored nowhere — read from the environment each time'),
+        ]),
+      ]),
+      secretMode === 'env' ? envVar : password.input,
+      el('p', {
+        class: 'conn-secret-note',
+        text: secretMode === 'env'
+          ? 'The URL will hold ${NAME}. Nothing is stored, here or anywhere.'
+          : 'Kept in this session only, and moved to the keychain if you save to a file.',
+      }),
+    );
+  }
+  const file = field('File', 'file', { placeholder: '/path/to/database.sqlite' });
+
+  /* What the parts add up to, with the secret dotted out — so it can be
+     checked before it is saved without the checking being the leak. */
+  const preview = el('code', { class: 'conn-preview' });
+
+  /* One driver control, moved between the two shapes rather than copied into
+     both. A clone carries no listener, so choosing `sqlite` from the file
+     pane's copy would have changed nothing at all — the control that is only
+     reachable *after* switching to sqlite would have been the dead one. */
+  const serverParts = el('div', { class: 'conn-parts' }, [host.row, port.row, database.row, user.row, secretRow]);
+  const fileParts = el('div', { class: 'conn-parts' }, [file.row]);
+
+  /**
+   * Whether the password is one that must not be shown.
+   *
+   * An environment reference is not a secret — `${PROD_PASSWORD}` names a
+   * variable and reveals nothing, and reading it back is the only way to
+   * notice the name is misspelt. A typed one is.
+   */
+  const secretIsHidden = () => Boolean(parts.password) && !isEnvReference(parts.password);
+
+  /**
+   * The URL as the box shows it: everything except a typed password.
+   *
+   * This is what makes one screen possible. With the two shapes on tabs, the
+   * box only ever held what somebody had pasted into it, so a password on
+   * screen was one they had put there. Side by side, typing into the masked
+   * Password field would echo it in plain text a few lines below — undoing
+   * the one decision the form had already made about that.
+   *
+   * So the box shows the shareable half and `parts` stays the single source
+   * of truth. What is submitted is built from `parts`, not read out of the
+   * box, which is what lets the two disagree safely.
+   */
+  const shownUrl = () => buildConnectionUrl(secretIsHidden() ? { ...parts, password: '' } : parts);
+
+  /** What will actually be opened. */
+  const targetUrl = () => buildConnectionUrl(parts);
+
+  function syncFromParts() {
+    name.placeholder = suggestedName() || 'Optional name';
+    url.value = shownUrl();
+    paintSchemeHint();
+    preview.textContent = redactConnectionUrl(targetUrl()) || '—';
+    /* Only worth a line when it says something the box above does not, which
+       is exactly when a password is being held back from it. */
+    previewRow.hidden = !secretIsHidden();
+  }
+
+  /* Typing or pasting in the URL box fills the parts below, which is the
+     whole point of having both on screen: paste what a colleague sent, then
+     read it back as fields and correct the one that is wrong. */
+  url.addEventListener('input', () => {
+    const text = url.value.trim();
+    /* Before the early return below: the hint is about what is in the box,
+       not about whether the parts were rebuilt from it. */
+    paintSchemeHint();
+    const parsed = parseConnectionUrl(text);
+    /* A half-typed URL is not a value, and this fires on every keystroke.
+       Applying one emptied every field under the cursor — invisible while the
+       parts were behind a tab, and the first thing you would see now.
+    
+       Two shapes of half-typed, and the second is the interesting one. A
+       string with no `://` in it is a file path, which is how SQLite is named
+       everywhere in this tool — so `postgres:/`, one slash into a URL, parses
+       as a *file* called `postgres:/` and switched the whole form to SQLite
+       mid-word. A scheme with nothing after it yet is a URL someone is still
+       writing. `sqlite:/path/to.db` is not, and still lands. */
+    const started = /^[a-z][\w+.-]*:\/?$/i.test(text);
+    if (text && (started || (!parsed.host && !parsed.file))) return;
+    /* A URL with no password does not clear one that was typed into the field
+       below, because the box is not showing it in the first place. Pasting a
+       URL that *does* carry one replaces it. */
+    const password_ = !parsed.password && secretIsHidden() ? parts.password : parsed.password;
+    parts = { ...parsed, password: password_ };
+    secretMode = isEnvReference(parts.password) ? 'env' : 'typed';
+    driver.value = parts.driver;
+    host.input.value = parts.host;
+    port.input.value = parts.port;
+    database.input.value = parts.database;
+    user.input.value = parts.user;
+    password.input.value = isEnvReference(parts.password) ? '' : parts.password;
+    envVar.value = envName(parts.password);
+    file.input.value = parts.file;
+    preview.textContent = redactConnectionUrl(targetUrl()) || '—';
+    previewRow.hidden = !secretIsHidden();
+    name.placeholder = suggestedName() || 'Optional name';
+    paintForm();
+  });
+
+  /**
+   * Both shapes, at once.
+   *
+   * They used to be two tabs, which meant the form opened by guessing which
+   * one you wanted and hid the other behind a click. The guess is not
+   * knowable: pasting is how most connections start, from a colleague or a
+   * dashboard, and filling in the parts is what you want when you are working
+   * out what the connection even is. A tab makes you answer that question
+   * before you have looked at either.
+   *
+   * They were always two views of one value — `connurl.js` exists to keep
+   * them the same thing rather than two forms that disagree — so showing both
+   * costs a divider and removes a decision.
+   */
+  const previewRow = el('p', { class: 'conn-preview-row', hidden: true }, [
+    el('span', { text: 'Opens as' }),
+    preview,
+  ]);
+  const body = el('div');
+
+  function paintForm() {
+    body.replaceChildren(
+      el('label', { class: 'field-stack' }, [el('span', { text: 'Paste a URL' }), url, schemeHint]),
+      el('div', { class: 'conn-or', role: 'separator' }, [el('span', { text: 'or fill in the parts' })]),
+      /* `driverRow` is appended, not cloned — appending moves it. */
+      driverRow,
+      parts.driver === 'sqlite' ? fileParts : serverParts,
+      previewRow,
+    );
+  }
+
+  paintSecret();
+  syncFromParts();
+  paintForm();
+
+  const dialog = el('dialog', { class: 'confirm conn-dialog' }, [
+    el('h2', { text: title }),
+    el('p', { text: 'Opened straight away, so a bad target fails here rather than later.' }),
+    body,
+    el('label', { class: 'field-stack' }, [
+      el('span', { text: 'Name' }),
+      name,
+      el('span', {
+        class: 'field-hint',
+        text: 'What it is called in the top bar, the picker, and its links. Renaming '
+          + 'later changes the label, not the links.',
+      }),
+    ]),
+    el('label', { class: 'field-stack' }, [el('span', { text: 'Schemas' }), schemas]),
+    el('p', {
+      class: 'conn-fineprint',
+      /* Three facts in one faint monospace line, one of them pointing at a
+         button on a screen you cannot see from here. Somebody read it and
+         asked what it meant, which is the whole report.
+      
+         Two sentences now: what happens if you do nothing, then what to do
+         about it and what that costs. "On the Connections screen" because
+         "Save to file…" is not in this dialog and never was. */
+      text: 'This connection lasts until you stop tablewalk. To keep it, use '
+        + '"Save to file…" on the Connections screen — the password moves to your '
+        + 'keychain and the file gets the URL without it.',
+    }),
+    result,
+    el('div', { class: 'confirm-actions' }, [
+      el('button', { type: 'button', class: 'ghost', text: 'Cancel', onclick: () => dialog.close() }),
+      /* Try it without keeping it.
+      
+         Adding was the only way to find out whether a target worked, and a
+         failed add leaves the entry behind on purpose — so a mistyped
+         password is a correction rather than a retype. That is right for
+         adding and wrong for checking: somebody who is not sure yet should
+         not have to tidy up after asking. */
+      el('button', {
+        type: 'button',
+        class: 'ghost',
+        text: 'Test',
+        onclick: async (e) => {
+          const target = targetUrl().trim();
+          /* Nothing to test, and saying so rather than doing nothing.
+          
+             This mattered most where it looked most broken: the Edit dialog.
+             A stored connection string never leaves the server — only its
+             redacted form does — so Edit opens with every field blank on
+             purpose, and pressing Test there produced no reply of any kind.
+             A button that answers sometimes and silently ignores you the
+             rest of the time is worse than one that is disabled. */
+          if (!target) {
+            showResult(false, 'Nothing to test yet. Paste a URL, or fill in the parts — '
+              + 'a saved connection string is kept on the server, so this form starts empty.');
+            return;
+          }
+          const button = e.currentTarget;
+          const was = button.textContent;
+          button.disabled = true;
+          button.textContent = 'Testing…';
+          result.hidden = true;
+          try {
+            const answer = await api('/api/connections/test', {
+              url: target, name: chosenName(), schemas: schemas.value.split(',').map((x) => x.trim()).filter(Boolean),
+            });
+            /* The table count is the part that says it *read* the database
+               rather than merely reached it, and where the password came from
+               is half the answer to "will this work" — one that works because
+               a secret is sitting in the URL is a different answer from one
+               that works from the keychain. */
+            const where = answer.secret && answer.secret !== 'none'
+              ? ` Password from ${answer.secret}.` : '';
+            showResult(
+              answer.ok,
+              answer.ok
+                ? `Connected. ${answer.dialect}, ${answer.tables} table${answer.tables === 1 ? '' : 's'}.${where}`
+                : answer.error,
+              /* The server works this out and the form used to drop it on the
+                 floor. "Password from inline" is a fact; the warning is the
+                 part that says why anyone should care. */
+              answer.ok ? answer.warning : undefined,
+            );
+          } catch (err) {
+            showResult(false, err.message);
+          } finally {
+            button.disabled = false;
+            button.textContent = was;
+          }
+        },
+      }),
+      el('button', {
+        type: 'button',
+        text: verb,
+        onclick: async () => {
+          result.hidden = true;
+          const list = schemas.value.split(',').map((s) => s.trim()).filter(Boolean);
+          const outcome = await run({
+            url: targetUrl().trim(),
+            name: chosenName(),
+            schemas: list,
+          });
+          if (outcome?.error) {
+            showResult(false, outcome.error);
+            return;
+          }
+          dialog.close();
+        },
+      }),
+    ]),
+  ]);
+
+  document.body.append(dialog);
+  dialog.addEventListener('close', () => dialog.remove());
+  dialog.showModal();
+  /* The URL box, always. It is the first field on the form, it is what a
+     paste wants, and it fills in everything below when it lands. */
+  url.focus();
+}
+
+/**
+ * Add a connection without the manager around it.
+ *
+ * The first-run screen has one thing to ask for and no list to show — opening
+ * the whole manager to reach its "+ Add" button would put an empty table of
+ * connections between someone and the only action on the page. The dialog
+ * mounts on `document.body` and stands alone, so it is offered alone.
+ *
+ * `paint` and `refresh` below are no-ops when the manager is not open; they
+ * already check for the panel, because every one of them can be reached from
+ * a dialog that outlives a redraw.
+ */
+export function addConnection(onAdded) {
+  addDialog(onAdded);
+}
+
+function addDialog(onAdded) {
+  connectionDialog({
+    title: 'Add a connection',
+    verb: 'Add and open',
+    run: async ({ url, name, schemas }) => {
+      if (!url) return { error: 'A connection string or file path is required.' };
+      try {
+        const data = await api('/api/connections', { url, name, schemas });
+        connections = data.connections ?? connections;
+        paint();
+        toast(`Added ${name || url}.`, 'ok');
+        if (onAdded) {
+          /* The first-run screen has its own idea of what happens next — a
+             reload, because a browser with no schema cannot switch to one. */
+          onAdded(data);
+          return null;
+        }
+        /* "Add and open" said open, and did not.
+        
+           `add` on the server makes a connection active only when there is
+           not one already, so adding a second connection left you looking at
+           the first — and if that first one was broken, at its error, with
+           the connection you had just successfully added sitting unselected
+           in the list. The button names the act; this is the act. */
+        if (data.added) {
+          close();
+          await selectConnection(data.added);
+        }
+        return null;
+      } catch (err) {
+        // Refreshed even on failure: the server may have kept the entry with
+        // its error attached, and a list that does not show it would be lying.
+        await refresh();
+        return { error: err.message };
+      }
+    },
+  });
+}
+
+function editDialog(conn) {
+  connectionDialog({
+    title: `Edit "${conn.name}"`,
+    name: conn.name,
+    /* The stored URL is not sent to the browser — only its redacted form — so
+       there is nothing to prefill here. Left blank with the current target
+       shown as the placeholder: typing a new one replaces it, leaving it empty
+       keeps it. That is the direct consequence of the rule that connection
+       strings never leave the server, and it is worth the small awkwardness. */
+    url: '',
+    schemas: conn.schemas,
+    verb: 'Save changes',
+    run: async ({ url, name, schemas }) => {
+      if (!url && !name) return { error: 'Nothing to change.' };
+      const body = { id: conn.id };
+      if (url) body.url = url;
+      if (name && name !== conn.name) body.name = name;
+      if (schemas.length) body.schemas = schemas;
+      const data = await mutate('/api/connections/update', body, { success: () => `Updated ${name || conn.name}.` });
+      return data ? null : { error: 'Could not update the connection.' };
+    },
+  });
+}
+
+async function saveDialog() {
+  const path = await promptFor({
+    title: 'Write connections to a file',
+    label: 'Path',
+    value: configFile ?? 'tablewalk.json',
+    hint: `${connections.length} connection${connections.length === 1 ? '' : 's'} will be written, with their URLs exactly as typed. A password written into a URL is written to the file as well.`,
+    placeholder: 'tablewalk.json',
+  });
+  if (!path) return;
+  try {
+    const data = await api('/api/connections/save', { path });
+    configFile = data.path;
+    /* Say where the passwords went.
+    
+       Saving moves an inline password out of the URL and into the keychain —
+       or a 0600 credentials file where there is no keychain — so the file can
+       be shared or committed without thinking about it. That is a helpful
+       thing to do and a surprising thing to discover later, so it is said at
+       the moment it happens rather than left in a README. */
+    const moved = data.secrets ?? [];
+    const where = moved.every((m) => m.stored === 'keychain') ? 'the keychain' : 'a credentials file (mode 600)';
+    const secrets = moved.length
+      ? ` ${moved.length} password${moved.length === 1 ? '' : 's'} moved to ${where} — the file has none.`
+      : '';
+    toast(
+      `Wrote ${data.count} connection${data.count === 1 ? '' : 's'} to ${data.path}.${secrets}`,
+      'ok',
+    );
+  } catch (err) {
+    toast(err.message, 'error');
+  }
+}