tablewalk 0.0.1

package/dist/client/welcome.js

@@ -0,0 +1,170 @@
+/**
+ * The screen for someone who has nothing connected yet.
+ *
+ * Until now `tablewalk` with no database printed its usage and exited(1). The
+ * flags were all correct and it answered the wrong question: somebody who has
+ * just installed a thing called tablewalk to find out what it is gets a wall
+ * of options and no program. Worse, the tool already owned the answer — a
+ * dialog that takes a connection string or its parts, tests it before keeping
+ * it, and resolves the password from the environment or the keychain — and it
+ * was one successful startup out of reach.
+ *
+ * So the server starts with nothing and this asks. Three things it is careful
+ * about:
+ *
+ *   - It does not pretend to be the app. The query bar, the table list and
+ *     the write toggle are all controls over a database, and leaving them on
+ *     screen greyed or live-but-broken is an interface saying "try me" about
+ *     things that cannot work yet. They are hidden until there is something
+ *     for them to act on.
+ *
+ *   - It says what the tool is before asking for credentials. "Paste your
+ *     production connection string" is a large request from a program that
+ *     has not yet said what it does with it, so the read-only default and the
+ *     fact that nothing is written to disk are on the screen making the ask,
+ *     not in a README.
+ *
+ *   - It reloads rather than booting a second way. Once a connection exists,
+ *     the ordinary start path is the one that has every other feature wired
+ *     into it; assembling half of it again here is how the two would drift.
+ *     A reload of a local page is imperceptible and cannot disagree with
+ *     itself.
+ */
+import { $, api, el } from './core.js';
+import { addConnection, openConnections } from './connmanager.js';
+
+/** The shapes a target can take, kept in the order they are likely to be met. */
+const EXAMPLES = [
+  { label: 'PostgreSQL', text: 'postgres://user@localhost:5432/appdb' },
+  { label: 'MySQL or MariaDB', text: 'mysql://user@localhost:3306/appdb' },
+  { label: 'SQLite', text: './data/app.db' },
+];
+
+/**
+ * What the server has, for the screen that runs when none of it opened.
+ *
+ * Returns the list, not a yes/no. "Is there anything?" was the wrong
+ * question: a first connection that fails to open is listed and does not
+ * open, so the answer was yes and the welcome screen was skipped — leaving
+ * "Could not read the schema: No connection is open." on screen with nothing
+ * to click. The right question is what is there, so the screen can say.
+ */
+export async function listConnections() {
+  try {
+    const data = await api('/api/connections');
+    return data.connections ?? [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Draw it.
+ *
+ * Nothing is initialised beyond this point on purpose — no palette, no
+ * shortcuts, no undo. Every one of them reads `state.schema`, and there
+ * isn't one.
+ */
+export function showWelcome(listed = []) {
+  document.body.classList.add('first-run');
+  document.title = 'tablewalk';
+  $('db-label').textContent = 'No database';
+
+  const button = el('button', {
+    type: 'button',
+    class: 'welcome-go',
+    text: 'Connect a database',
+    onclick: () => addConnection(() => window.location.reload()),
+  });
+
+  /* Connections that exist and would not open.
+  
+     Without this the screen said "nothing connected" over a list of things
+     that were connected-ish and broken, and offered adding another as the
+     only move — when the useful move is almost always to fix or remove the
+     one that failed. It is the whole reason this screen is reachable with a
+     non-empty list at all. */
+  const broken = listed.filter((c) => c.error);
+  const trouble = broken.length ? el('div', { class: 'welcome-trouble' }, [
+    el('p', { class: 'welcome-trouble-head' }, [
+      el('strong', {
+        text: broken.length === 1
+          ? 'One connection is configured, and it did not open.'
+          : `${broken.length} connections are configured, and none of them opened.`,
+      }),
+    ]),
+    el('ul', {}, broken.map((c) => el('li', {}, [
+      el('span', { class: 'welcome-trouble-name', text: c.name }),
+      el('span', { class: 'welcome-trouble-why', text: c.error }),
+    ]))),
+    el('button', {
+      type: 'button',
+      class: 'ghost',
+      text: 'Open connections',
+      onclick: () => void openConnections(),
+    }),
+  ]) : null;
+
+  $('content').replaceChildren(el('div', { class: 'welcome' }, [
+    /* The promise, not a status report.
+    
+       This read "Nothing connected yet." — accurate, and the software's point
+       of view rather than the reader's: the first sentence somebody meets
+       named an absence at the moment they wanted to know what they had found.
+       The absence is already on the screen twice over, in the top bar and in
+       the one button, so the heading does not have to carry it.
+    
+       It is the README's own line, and deliberately. The wordmark is in the
+       top bar directly above, which makes this the same pairing the front
+       page opens with — a product whose first screen and first paragraph say
+       different things about what it is for has two pitches, and one of them
+       is wrong. */
+    el('h1', { text: 'Follow the data.' }),
+    el('p', { class: 'welcome-lede' }, [
+      /* Two plain sentences with an example in them.
+      
+         This was "A database is a graph, and this walks it: open a row and
+         you get every row elsewhere that points at it, without writing a join
+         to reach them. Give it something to read." — an abstract reframe, a
+         colon, a clause defending against an objection nobody had raised
+         yet, and a closing instruction for a button that is four inches
+         below and already says the same thing. Naming two real rows does more
+         than any of that. */
+      document.createTextNode('Open any row and you see what points at it. '
+        + 'The orders on a customer, the customer on an order.'),
+    ]),
+    button,
+    trouble,
+    el('p', { class: 'welcome-assure' }, [
+      /* The two facts most likely to be someone's actual hesitation, said
+         before the box that asks for a password rather than after. */
+      el('strong', { text: 'Read only.' }),
+      document.createTextNode(' You turn editing on yourself, per connection. '
+        + 'Connections you add here are gone when you quit, unless you save them to a file.'),
+    ]),
+    el('div', { class: 'welcome-examples' }, [
+      el('h2', { text: 'What to point it at' }),
+      el('ul', {}, EXAMPLES.map((e) => el('li', {}, [
+        el('span', { class: 'welcome-ex-label', text: e.label }),
+        el('code', { text: e.text }),
+      ]))),
+      el('p', { class: 'note' }, [
+        document.createTextNode('The password does not have to be in the string. Write '),
+        el('code', { text: '${DB_PASSWORD}' }),
+        document.createTextNode(' and it comes from the environment, or leave it out and keep it in '
+          + 'the keychain. There is a Test button either way.'),
+      ]),
+      el('p', { class: 'note' }, [
+        document.createTextNode('To skip this next time, put them in a '),
+        el('code', { text: 'tablewalk.json' }),
+        document.createTextNode(' where you start tablewalk:'),
+      ]),
+      el('pre', {
+        class: 'welcome-config',
+        text: '{\n  "connections": [\n    { "name": "app", "url": "postgres://localhost/appdb" }\n  ]\n}',
+      }),
+    ]),
+  ]));
+
+  button.focus();
+}

package/dist/client/write.js

@@ -0,0 +1,414 @@
+/**
+ * Write mode.
+ *
+ * Read is the default and stays the default: the connection the browsing path
+ * uses is opened read-only and never changes, so nothing you do while looking
+ * around can write, even after the toggle is on. Editing goes through a
+ * separate connection that the server opens lazily, the first time it is
+ * actually asked to write.
+ *
+ * The toggle is deliberately not sticky. It lives in memory for the session
+ * and resets on reload, because a mode that silently persists is a mode you
+ * forget you are in — and the whole risk of an editor is a change you did not
+ * realise you were making.
+ *
+ * The real guard is on the server, not here. This file makes the state
+ * obvious and asks for confirmation; the server independently refuses any
+ * update whose WHERE clause does not match exactly one row.
+ */
+import { $, api, el, loadJson, render, rowLabel, saveJson, state, toast } from './core.js';
+import { planColumn } from './columns.js';
+import { refreshUndo, undoLast } from './undo.js';
+
+/* Write mode is remembered per connection.
+   Per connection, not globally: switching from the demo to production must
+   not silently inherit permission to edit it. Each database is opted into
+   separately, and the choice sticks until it is turned off. */
+const WRITE_KEY = 'tablewalk.write.v1';
+
+const connectionKey = () => state.activeConnection ?? 'default';
+
+function rememberedWrite() {
+  return loadJson(WRITE_KEY, {})[connectionKey()] === true;
+}
+
+function rememberWrite(on) {
+  const all = loadJson(WRITE_KEY, {});
+  if (on) all[connectionKey()] = true;
+  else delete all[connectionKey()];
+  saveJson(WRITE_KEY, all);
+}
+
+export function initWriteMode() {
+  const toggle = $('write-toggle');
+  toggle.addEventListener('click', () => {
+    if (state.canWrite) {
+      setWriteMode(false);
+      return;
+    }
+    confirmWrite().then((ok) => ok && setWriteMode(true));
+  });
+  // Restored without asking again: the confirmation was given for this
+  // database and has not been withdrawn.
+  setWriteMode(rememberedWrite(), { remember: false });
+}
+
+/** Re-evaluate on connection switch, since the setting is per database. */
+export function syncWriteMode() {
+  setWriteMode(rememberedWrite(), { remember: false });
+}
+
+function setWriteMode(on, { remember = true } = {}) {
+  state.canWrite = on;
+  if (remember) rememberWrite(on);
+  const toggle = $('write-toggle');
+  toggle.setAttribute('aria-pressed', String(on));
+  /* An icon, but not a quiet one.
+
+     Write mode is the one state in this header worth noticing without being
+     looked for, so the two states are drawn as opposites rather than as two
+     similar glyphs: a closed padlock, dim and unfilled, against an open one
+     that is filled and coloured. The label goes to assistive technology
+     rather than disappearing — an icon-only control still has to say what it
+     is. */
+  toggle.textContent = on ? '🔓' : '🔒';
+  toggle.setAttribute('aria-label', on ? 'Write mode — click to return to read only' : 'Read only — click to enable editing');
+  toggle.title = on
+    ? 'Editing is enabled. Click to return to read only.'
+    : 'Browsing only. Click to enable editing.';
+  /* The indicator is on <body> rather than the button, so it can colour the
+     window frame. Being in write mode should be visible from across the room,
+     not something you have to go looking for. */
+  document.body.classList.toggle('write-mode', on);
+  // Leaving write mode drops anything staged: pending edits you can no longer
+  // see or apply are worse than no pending edits.
+  if (!on) discardStaged();
+  render();
+}
+
+/**
+ * A real confirmation, naming the database. "Are you sure?" teaches nothing;
+ * the name of the thing you are about to be able to change does.
+ */
+function confirmWrite() {
+  return new Promise((resolve) => {
+    const dialog = el('dialog', { class: 'confirm' }, [
+      el('h2', { text: 'Enable write mode?' }),
+      el('p', {}, [
+        document.createTextNode('You will be able to edit rows in '),
+        el('strong', { text: state.schema.label }),
+        document.createTextNode('. Changes go straight to the database and cannot be undone from here.'),
+      ]),
+      el('ul', { class: 'confirm-terms' }, [
+        el('li', { text: 'Only rows with a primary key can be edited — one row, one column at a time.' }),
+        el('li', { text: 'Every change is shown as SQL before it runs.' }),
+        el('li', { text: 'An update that would touch more than one row is refused.' }),
+        el('li', { text: 'Write mode stays on for this database until you turn it off, including after a reload.' }),
+        el('li', { text: 'It applies to this database only — switching connections does not carry it over.' }),
+      ]),
+      el('div', { class: 'confirm-actions' }, [
+        el('button', { type: 'button', class: 'ghost', text: 'Stay read only', onclick: () => { dialog.close(); resolve(false); } }),
+        el('button', { type: 'button', class: 'danger', text: 'Enable write mode', onclick: () => { dialog.close(); resolve(true); } }),
+      ]),
+    ]);
+    dialog.addEventListener('close', () => dialog.remove());
+    dialog.addEventListener('cancel', () => resolve(false));
+    document.body.append(dialog);
+    dialog.showModal();
+  });
+}
+
+/* ---------- staged edits ----------
+
+   An edit does not go to the database when you leave the field. It is held
+   until you apply, so several fields become one statement — three edits as
+   three statements means three chances to fail half way, leaving a row in a
+   state nobody asked for.
+
+   Staging is keyed by table and row, so walking away and back does not
+   silently carry pending edits onto a different row. */
+
+let staged = { connection: null, table: null, key: null, values: {}, originals: {}, inputs: {} };
+
+export function pendingCount() {
+  return Object.keys(staged.values).length;
+}
+
+/**
+ * Whether what is staged belongs to the row on screen.
+ *
+ * The connection is part of the answer. Keyed by table and key alone, an edit
+ * staged against staging's `customer:4` showed as pending on production's
+ * `customer:4` — the same table name and the same id, a different database,
+ * and one click from being written to the wrong one.
+ */
+function sameRow(table, key) {
+  return staged.connection === state.activeConnection
+    && staged.table === table
+    && JSON.stringify(staged.key) === JSON.stringify(key);
+}
+
+export function discardStaged() {
+  staged = { connection: null, table: null, key: null, values: {}, originals: {}, inputs: {} };
+}
+
+function stage(table, key, column, value, original) {
+  if (!sameRow(table.id, key)) {
+    staged = {
+      connection: state.activeConnection, table: table.id, key,
+      values: {}, originals: {}, inputs: {},
+    };
+  }
+  // Typing a value and then typing the original back is not a change. Keeping
+  // it staged would show "1 change" for an edit that changes nothing.
+  if (String(value) === String(original) || (value === null && original === null)) {
+    delete staged.values[column.name];
+    delete staged.originals[column.name];
+  } else {
+    staged.values[column.name] = value;
+    staged.originals[column.name] = original;
+  }
+}
+
+/**
+ * The two values a boolean column actually holds, or null if it is not one.
+ *
+ * MySQL has no boolean — BOOL is a spelling of TINYINT(1) — and SQLite keeps
+ * 0 and 1 in an INTEGER, so the pair depends on the column rather than on a
+ * type name. Written back exactly as it was read, which is what stops an
+ * edit to a *different* field of the same row from rewriting `1` to `true`
+ * on the way past.
+ */
+function booleanChoices(column, row) {
+  /* The grid's own rule, not a second one: a column drawn as ✓/✗ has to edit
+     as yes/no, or the same value is a tick in one view and a `0` to type in
+     the other. That rule is more than the declared type — MySQL has no
+     boolean and SQLite keeps flags in INTEGER, so a name like `is_urgent`
+     holding only 0 and 1 counts. */
+  const plan = planColumn(column, column?.name ?? '', row ? [row] : []);
+  if (plan.kind !== 'boolean') return null;
+  return /bool/i.test(column?.type ?? '') ? { yes: 'true', no: 'false' } : { yes: '1', no: '0' };
+}
+
+/**
+ * Turn a field into an editor. Called from the record view, and only when
+ * write mode is on and the row has a usable key.
+ */
+export function editable(table, row, column, key, onSaved) {
+  const value = row[column.name];
+  const original = value === null || value === undefined ? null : String(value);
+  const stagedValue = sameRow(table.id, key) ? staged.values[column.name] : undefined;
+  const shown = stagedValue !== undefined ? stagedValue : original;
+
+  /* A box you type `0` or `1` into is not an editor for a column that holds
+     two values. The choices are the values the database stores — `1` and `0`
+     where the column is an integer flag, `true` and `false` where it is a
+     real boolean — so what is written is what was already there, and the
+     empty option is NULL rather than a third state. */
+  const choices = booleanChoices(column, row);
+  const input = choices
+    ? el('select', {
+        class: `cell-edit${stagedValue !== undefined ? ' dirty' : ''}`,
+        'aria-label': `${column.name} (${column.type})`,
+      }, [
+        ...(column.nullable ? [el('option', { value: '', text: 'null' })] : []),
+        el('option', { value: choices.yes, text: 'yes' }),
+        el('option', { value: choices.no, text: 'no' }),
+      ])
+    : el('input', {
+    class: `cell-edit${stagedValue !== undefined ? ' dirty' : ''}`,
+    /* Named by its column. A record page is a grid of unlabelled text boxes
+       to anything that cannot see the `dt` beside each one, and "edit field"
+       repeated forty times is no better than nothing. */
+    'aria-label': `${column.name} (${column.type})`,
+    type: 'text',
+    value: shown === null ? '' : String(shown),
+    'data-null': String(shown === null),
+    'aria-label': `${column.name} (${column.type})`,
+    /* Where the database pins the vocabulary, say it — but still a text box.
+       A column that gained a CHECK after the rows were written holds values
+       the check would refuse, and a select would silently rewrite one of
+       them the moment someone edited a different field of that row. */
+    title: column.allowed?.length ? `one of: ${column.allowed.join(', ')}` : undefined,
+  });
+
+  if (choices) input.value = shown === null ? '' : String(shown);
+
+  const onEdit = () => {
+    // An empty box on a nullable column means NULL, not the empty string.
+    // They are different values and conflating them loses data silently.
+    const next = input.value === '' && column.nullable ? null : input.value;
+    stage(table, key, column, next, original);
+    input.classList.toggle('dirty', staged.values[column.name] !== undefined);
+    onSaved?.();
+  };
+
+  // Kept so a successful write can confirm in place rather than re-render.
+  if (!sameRow(table.id, key)) staged = { table: table.id, key, values: {}, originals: {}, inputs: {} };
+  staged.inputs[column.name] = input;
+
+  /* `input` only, deliberately: a `change` listener fires on blur, which is
+     the moment someone clicks "Review & apply" — the re-render it triggered
+     detached the button mid-click and the confirmation never opened. Selects
+     fire `input` too, so nothing is lost. */
+  input.addEventListener('input', onEdit);
+  input.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      if (pendingCount()) void applyStaged(table, key, onSaved);
+    }
+    if (e.key === 'Escape') {
+      input.value = original === null ? '' : original;
+      onEdit();
+    }
+  });
+  return input;
+}
+
+/**
+ * The pending-changes bar. Rendered by the record view above the fields, so
+ * the fact that edits are held rather than saved is impossible to miss.
+ */
+export function pendingBar(table, key, onDone) {
+  if (!sameRow(table.id, key) || !pendingCount()) return null;
+  const n = pendingCount();
+  return el('div', { class: 'pending' }, [
+    el('span', { class: 'pending-count', text: `${n} unsaved change${n === 1 ? '' : 's'}` }),
+    el('span', { class: 'pending-cols', text: Object.keys(staged.values).join(', ') }),
+    el('button', {
+      type: 'button', class: 'ghost', text: 'Discard',
+      onclick: () => { discardStaged(); onDone?.(); },
+    }),
+    el('button', {
+      type: 'button', class: 'danger', text: `Review & apply`,
+      onclick: () => void applyStaged(table, key, onDone),
+    }),
+  ]);
+}
+
+async function applyStaged(table, key, onDone) {
+  if (!pendingCount()) return;
+  const values = { ...staged.values };
+  const originals = { ...staged.originals };
+  const ok = await confirmUpdate(table, key, values, originals);
+  if (!ok) return;
+  try {
+    const result = await api('/api/update', { table: table.id, key, values });
+    const n = Object.keys(result.applied).length;
+
+    /* Recorded before the toast, so the offer to undo cannot appear for a
+       write the history does not have. */
+    /* The server journalled the write as it landed; this just re-reads what
+       there is to undo, so the menu and ⌘Z are right immediately. */
+    void refreshUndo();
+    toast(`Updated ${n} column${n === 1 ? '' : 's'} on ${table.name}.`, 'ok', {
+      /* Beside the confirmation, because this is the moment someone realises
+         it was the wrong row — and sending them to a menu to find Undo wastes
+         the seconds in which they still remember what they changed. */
+      label: 'Undo',
+      run: () => void undoLast().then(() => render()),
+    });
+
+    /* Confirmed in place rather than by re-rendering. A re-render would throw
+       away the row you are looking at and rebuild it, which reads as a flicker
+       and loses the caret; worse, it left the fields showing their unsaved
+       styling because the DOM they styled was gone before the class was.
+       Showing the saved value, in green, on the field you just edited is both
+       calmer and more specific — it says *which* fields landed. */
+    const inputs = staged.inputs;
+    confirmSaved(inputs, result.applied);
+    discardStaged();
+    // Only the pending bar is refreshed, so the green fields survive.
+    onDone?.({ inPlace: true });
+  } catch (err) {
+    // Nothing is discarded on failure: the edits stay staged so they can be
+    // corrected rather than retyped.
+    toast(err.message, 'error');
+  }
+}
+
+/** How long the green confirmation stays before fading. */
+const SAVED_MS = 2200;
+
+function confirmSaved(inputs, applied) {
+  for (const [column, value] of Object.entries(applied)) {
+    const input = inputs[column];
+    if (!input || !input.isConnected) continue;
+    // The value the database actually stored, which may differ from what was
+    // typed — "17901" comes back as the number 17901.
+    input.value = value === null ? '' : String(value);
+    input.dataset.null = String(value === null);
+    input.classList.remove('dirty');
+    input.classList.add('saved');
+    setTimeout(() => input.classList.remove('saved'), SAVED_MS);
+  }
+}
+
+/** Show the statement before it runs. This is the last stop before a write. */
+function confirmUpdate(table, key, values, originals) {
+  return new Promise((resolve) => {
+    const q = (id) => `"${id}"`;
+    const sets = Object.keys(values).map((c) => `${q(c)} = ?`).join(',\n       ');
+    const where = Object.keys(key).map((c) => `${q(c)} = ?`).join(' AND ');
+    const sql = `UPDATE ${q(table.id)}\n   SET ${sets}\n WHERE ${where};`;
+
+    /* The parameters shown are the raw staged values. The server coerces them
+       against the declared column types and returns what it applied, so a
+       number typed as text is corrected there rather than guessed at here. */
+    const params = JSON.stringify([...Object.values(values), ...Object.values(key)]);
+
+    const rows = Object.entries(values).map(([column, to]) => {
+      const from = originals[column];
+      const type = table.columns.find((c) => c.name === column)?.type ?? '';
+      return el('tr', {}, [
+        el('td', {}, [
+          el('span', { class: 'diff-col', text: column }),
+          el('span', { class: 'diff-type', text: type.toLowerCase() }),
+        ]),
+        el('td', { class: `diff-from${from === null ? ' null' : ''}`, text: from === null ? 'null' : String(from) }),
+        el('td', { class: 'diff-arrow', text: '→' }),
+        el('td', { class: `diff-to${to === null ? ' null' : ''}`, text: to === null ? 'null' : String(to) }),
+      ]);
+    });
+
+    const dialog = el('dialog', { class: 'confirm confirm-wide' }, [
+      el('h2', { text: rows.length === 1 ? 'Apply this change?' : `Apply ${rows.length} changes?` }),
+      el('p', {}, [
+        document.createTextNode('One row in '),
+        el('strong', { text: table.id }),
+        document.createTextNode(', identified by '),
+        el('strong', { text: Object.entries(key).map(([k, v]) => `${k} = ${v}`).join(', ') }),
+        document.createTextNode('. Applied as a single statement.'),
+      ]),
+      el('table', { class: 'confirm-diff' }, el('tbody', {}, rows)),
+      el('pre', { class: 'ddl', text: sql }),
+      el('p', { class: 'confirm-params', text: `parameters ${params}` }),
+      el('div', { class: 'confirm-actions' }, [
+        el('button', { type: 'button', class: 'ghost', text: 'Cancel', onclick: () => { dialog.close(); resolve(false); } }),
+        el('button', { type: 'button', class: 'danger', text: 'Apply', onclick: () => { dialog.close(); resolve(true); } }),
+      ]),
+    ]);
+    dialog.addEventListener('close', () => dialog.remove());
+    dialog.addEventListener('cancel', () => resolve(false));
+    document.body.append(dialog);
+    dialog.showModal();
+  });
+}
+
+/** True when this row can be edited at all: write mode on, and a full key. */
+export function canEditRow(table, key) {
+  if (!state.canWrite || !table || table.isView) return false;
+  const pk = table.columns.filter((c) => c.primaryKey).map((c) => c.name);
+  return pk.length > 0 && pk.every((c) => key[c] !== undefined && key[c] !== null);
+}
+
+/** Why a row is not editable, for the record view to explain rather than hide. */
+export function whyNotEditable(table) {
+  if (!state.canWrite) return null; // not in write mode: say nothing
+  if (!table) return 'Unknown table.';
+  if (table.isView) return 'This is a view. Views are read-only.';
+  if (!table.columns.some((c) => c.primaryKey)) {
+    return 'This table has no primary key, so there is no way to identify one row safely.';
+  }
+  return null;
+}