tablewalk 0.0.1 → 0.0.3

package/README.md

@@ -1,32 +1,35 @@
 # tablewalk
 
-**Follow the data.**
+**[Follow the data.](https://tablewalk.pages.dev)** — [tablewalk.pages.dev](https://tablewalk.pages.dev)
 
 Most database tools are SQL clients that happen to render a grid. tablewalk
-starts somewhere else: a foreign key is a place you can go.
+starts somewhere else: a foreign key is a place you can go. Open a row and it
+shows you every row elsewhere that points at it — the orders on a customer, the
+customer on an order — so you follow the data instead of writing joins to reach
+it. The same machinery answers over **MCP**, so a coding agent sees what you
+see ([jump to setup](#for-coding-agents-mcp)).
 
 ```bash
-npx tablewalk                                          # asks in the browser
-npx tablewalk mydata.sqlite
-npx tablewalk postgres://user:pass@localhost/appdb
-npx tablewalk mydata.sqlite --export md >> CLAUDE.md   # the schema, as a committed brief
-npx tablewalk postgres://… --lint --fail-on high        # what the shape costs, for CI
-npx tablewalk --config ./tablewalk.json --diff staging # is staging the same shape?
+npx tablewalk --demo          # build a sample database and open it — an instant try
+npx tablewalk mydata.sqlite   # or your own: SQLite, Postgres, MySQL
+npx tablewalk                 # or nothing, and the page asks for a connection
 ```
 
-No config file, no saved connection, no schema to define first. Point it at a
-database and it reads the catalog on connect.
+No config, no build step, no schema to define first — it reads the catalog on
+connect. **Read-only** until you turn editing on, per connection. Runs from
+`npx`, a [Docker image](#docker-and-a-desktop-app), or a desktop app.
 
-Or point it at nothing. `npx tablewalk` on its own starts the server and the
-page asks for a connection — a form that takes either a URL or its parts, tests
-it before keeping it, and can read the password from an environment variable or
-the keychain instead of the string. A connection added that way lasts for the
-session; "Save to file…" writes it down, with any typed password moved to the
-keychain rather than into the file.
+`npx tablewalk` with no target opens a page that asks for a connection: a form
+that takes a URL or its parts, tests it before keeping it, and reads the
+password from an environment variable or the keychain rather than the string.
+The print-and-exit commands need a target, though — there is nothing for
+`--export`, `--lint`, `--diff` or `--mcp` to read without one:
 
-The commands that print and exit still need a target, because there is nothing
-for `--export`, `--lint` or `--diff` to read without one, and `--mcp` does too:
-an agent on stdio has no dialog to fill in.
+```bash
+npx tablewalk mydata.sqlite --export md >> CLAUDE.md    # the schema, as a committed brief
+npx tablewalk postgres://… --lint --fail-on high         # what the shape costs, for CI
+npx tablewalk --config ./tablewalk.json --diff staging   # is staging the same shape?
+```
 
 ## The idea
 
@@ -195,39 +198,45 @@ npx tablewalk --mcp --config ./tablewalk.json   # speaks MCP on stdio
 { "mcpServers": { "tablewalk": { "command": "npx", "args": ["tablewalk", "--mcp", "--config", "./tablewalk.json"] } } }
 ```
 
-Twenty-three tools. Reading everywhere: `refresh` (re-read the catalog after a migration — the schema is cached per open, and the error for an unknown table says when to call it), `schema_summary` (orientation in a few hundred
-tokens — hubs, event tables, the deepest reference chain), `tables`, `table`
-(columns, DDL, and foreign keys in **both** directions), `find` (where a name
-lives, across tables and columns), `query` (the query language, whose errors
-carry suggestions and the table's real columns — what lets an agent fix a
-mistake in one retry), `breakdown` (counts and sums grouped by something —
-`invoice count by month invoice_date`), `sql` (read-only, for whatever the
-language still cannot say), `record`
-(one row, its human name, and everything that points at it), `explain` (the
-planner's account of a statement without running it — feed a `query` answer's
-`sql` back verbatim), `profile` (what a column actually holds: null share,
-distinct count, range, the values that repeat), `lint` (what the shape will
-cost: keyless tables, unindexed references, naive timestamps),
-`change_impact` (what breaks if you change this table or column — asked
-*before* the migration is written: what points at it under which delete rule,
-whether those columns are NOT NULL, whether an index leads on them, and how
-many rows actually hold null, which is the fact that decides whether an
-`ALTER` succeeds), `diff` (whether
-two connections are still the same shape), `order` (what has to exist before
-what, and the reverse for teardown), `fixture` (a real row and the graph it belongs to, ready to replay into a test database), and `connections`. Every result carries a deep link the human beside the agent
-can open in the UI, and says what it cost: wall time and rows read.
-
-Writing only where your config says so. `insert`, `update`, `delete`,
-`insert_graph`, `delete_graph` and `revert` are offered only when a connection
-is marked `"writable": true` — a read-only server does not list tools it would
-refuse. `revert` undoes the last write behind the same two-call `confirm` gate
-`delete` uses; a `sql` write is recorded but marked unrevertible, because
-arbitrary SQL has no general inverse.
-`insert` answers with the row as the database stored it, defaults filled and
-key assigned; `delete` answers with its impact first — every table pointing at
-the row, counts, and `ON DELETE` rules — removing nothing until called again
-with `confirm: true`. Write answers carry `rowsInserted` / `rowsWritten` /
-`rowsDeleted`.
+Or point it at a database instead of a config file: `"args": ["tablewalk",
+"--mcp", "--db", "postgres://localhost/app"]`. **Twenty-three tools** —
+seventeen read-only, and six writes offered only when a connection is
+`"writable": true`. Every answer carries a deep link the human beside the
+agent can open in the UI, and says what it cost in rows and milliseconds.
+
+**Reading**
+
+| tool | what it answers |
+|---|---|
+| `schema_summary` | orientation in a few hundred tokens — hubs, event tables, the deepest reference chain |
+| `tables` / `table` | the list; then a table's columns, DDL, and foreign keys in **both** directions |
+| `find` | where a name lives, across every table and column |
+| `query` | the query language; its errors carry suggestions and the table's real columns, so a mistake is fixed in one retry |
+| `breakdown` | counts and sums grouped by something — `invoice count by month invoice_date` |
+| `record` | one row, its human name, and everything that points at it |
+| `sql` | read-only, for whatever the language cannot say |
+| `explain` | the planner's account of a statement without running it — feed a `query` answer's `sql` back |
+| `profile` | what a column actually holds: null share, distinct count, range, the values that repeat |
+| `lint` | what the shape will cost: keyless tables, unindexed references, naive timestamps |
+| `change_impact` | what breaks if you change a table or column — asked *before* the migration is written |
+| `diff` | whether two connections are still the same shape |
+| `order` | what has to exist before what, and the reverse for teardown |
+| `fixture` | a real row and the graph it belongs to, ready to replay into a test database |
+| `refresh` | re-read the catalog after a migration |
+| `connections` | list them; the call to start with |
+
+**Writing** — offered only when a connection is marked `"writable": true`; a
+read-only server does not list tools it would refuse.
+
+| tool | what it does |
+|---|---|
+| `insert` | one row; answers with what the database stored, defaults filled and key assigned |
+| `update` | one row, by its primary key |
+| `delete` | reports its impact first — every table pointing at the row, counts, `ON DELETE` rules — and removes nothing until called again with `confirm: true` |
+| `insert_graph` / `delete_graph` | several related rows in one all-or-nothing transaction |
+| `revert` | undo the last write, behind the same two-call `confirm` gate; a raw `sql` write is recorded but marked unrevertible, since it has no general inverse |
+
+Write answers carry `rowsInserted` / `rowsWritten` / `rowsDeleted`.
 
 A fixture is a graph, so `insert_graph` takes one: several related rows in one
 transaction, where either all of them land or none does. A row that cannot
@@ -487,10 +496,22 @@ is your own machine; bind wider and it is whoever else can reach you.
 
 ## Docker, and a desktop app
 
-There is a Dockerfile and an Electron app in `desktop/`. Both are covered in
-[DEPLOY.md](DEPLOY.md), including the two things a container changes about the
+**Container** — `ghcr.io/rbaljinder/tablewalk`. It reads its connections from a
+mounted `tablewalk.json` and holds no configuration of its own:
+
+```bash
+docker run --rm -p 127.0.0.1:4111:4111 -v "$PWD:/config:ro" ghcr.io/rbaljinder/tablewalk
+```
+
+[DEPLOY.md](DEPLOY.md) covers the two things a container changes about the
 security model — binding `0.0.0.0` inside while publishing only to the host's
-loopback, and `--allowed-host` for reaching it by any name but `localhost`.
+loopback, and `--allowed-host` for reaching it by a name other than
+`localhost`.
+
+**Desktop** — a native app (macOS, Windows, Linux) is attached to each
+[GitHub release](https://github.com/rbaljinder/tablewalk/releases). The builds
+are currently unsigned, so the first open needs an "open anyway" past the OS
+warning; `npx tablewalk` and the container need no such thing.
 
 ## Keyboard
 

package/dist/server/demo.js

@@ -0,0 +1,405 @@
+/**
+ * Build the demo database.
+ *
+ * Lives in `src/` (not `test/`) because it ships: `tablewalk --demo` builds
+ * one of these at runtime so a new install has something to walk without
+ * hunting for a database first. `test/make-demo-db.ts` re-exports it, so the
+ * suite and `npm run demo` keep the path they have always used.
+ *
+ * A demo that ships as a binary file is a demo nobody can review, so this
+ * writes one from source instead. The shape is chosen to exercise the parts
+ * of the tool that are easy to get wrong: a self-referencing key, a composite
+ * key, a view, a nullable reference, and one table that several others point
+ * at so the reverse-reference panel has something to say.
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync, rmSync } from 'node:fs';
+import { dirname } from 'node:path';
+const SCHEMA = `
+CREATE TABLE country (
+  code        TEXT PRIMARY KEY,
+  name        TEXT NOT NULL
+);
+
+CREATE TABLE customer (
+  id          INTEGER PRIMARY KEY,
+  name        TEXT NOT NULL,
+  email       TEXT,
+  country_code TEXT REFERENCES country(code),
+  credit_limit REAL DEFAULT 0,
+  active      INTEGER NOT NULL DEFAULT 1,
+  signed_up   DATE
+);
+
+-- Self-referencing: an employee reports to an employee. The graph view has to
+-- handle an edge whose two ends are the same table without looping forever.
+CREATE TABLE employee (
+  id          INTEGER PRIMARY KEY,
+  first_name  TEXT NOT NULL,
+  last_name   TEXT NOT NULL,
+  title       TEXT,
+  manager_id  INTEGER REFERENCES employee(id),
+  hired_on    DATE
+);
+
+CREATE TABLE invoice (
+  id          INTEGER PRIMARY KEY,
+  customer_id INTEGER NOT NULL REFERENCES customer(id),
+  sold_by     INTEGER REFERENCES employee(id),
+  invoice_date DATE NOT NULL,
+  total       REAL NOT NULL DEFAULT 0,
+  -- A CHECK, not a lookup table: this is how most schemas in the wild spell
+  -- an enum, and to anything reading the catalog it is an untyped TEXT column
+  -- unless the constraint is read too.
+  status      TEXT NOT NULL DEFAULT 'issued'
+                CHECK (status IN ('draft','issued','paid','void'))
+);
+
+CREATE TABLE product (
+  sku         TEXT PRIMARY KEY,
+  name        TEXT NOT NULL,
+  unit_price  REAL NOT NULL
+);
+
+-- Composite primary key AND a composite-capable child, so PRAGMA collapsing
+-- and multi-column reverse lookups both get exercised.
+CREATE TABLE invoice_line (
+  invoice_id  INTEGER NOT NULL REFERENCES invoice(id),
+  line_no     INTEGER NOT NULL,
+  sku         TEXT NOT NULL REFERENCES product(sku),
+  quantity    INTEGER NOT NULL DEFAULT 1,
+  PRIMARY KEY (invoice_id, line_no)
+);
+
+CREATE TABLE shipment (
+  id          INTEGER PRIMARY KEY,
+  invoice_id  INTEGER NOT NULL,
+  line_no     INTEGER NOT NULL,
+  shipped_on  DATE,
+  FOREIGN KEY (invoice_id, line_no) REFERENCES invoice_line(invoice_id, line_no)
+);
+
+CREATE VIEW customer_totals AS
+  SELECT c.id, c.name, COUNT(i.id) AS invoices, COALESCE(SUM(i.total), 0) AS lifetime
+    FROM customer c LEFT JOIN invoice i ON i.customer_id = c.id
+   GROUP BY c.id, c.name;
+`;
+const DATA = `
+INSERT INTO country VALUES ('AU','Australia'), ('NZ','New Zealand'), ('GB','United Kingdom');
+
+INSERT INTO customer (id, name, email, country_code, credit_limit, active, signed_up) VALUES
+  (1,'Harbour Freight','ops@harbourfreight.example','AU',5000,1,'2023-02-11'),
+  (2,'Kereru Coffee','hello@kereru.example','NZ',1200,1,'2024-06-30'),
+  (3,'Pennine Tools','accounts@pennine.example','GB',0,0,'2022-11-05'),
+  (4,'Dry Creek Vineyards',NULL,'AU',9000,1,'2025-01-19'),
+  (5,'Southerly Logistics','ap@southerly.example',NULL,2500,1,'2025-09-02');
+
+INSERT INTO employee (id, first_name, last_name, title, manager_id, hired_on) VALUES
+  (1,'Ada','Fraser','Managing Director',NULL,'2019-03-01'),
+  (2,'Miles','Okonkwo','Sales Manager',1,'2020-07-15'),
+  (3,'Rina','Petrova','Account Executive',2,'2022-01-10'),
+  (4,'Tom','Whitfield','Account Executive',2,'2023-08-22'),
+  (5,'Joan','Alvarez','Support Lead',1,'2021-05-04');
+
+INSERT INTO product VALUES
+  ('SKU-100','Bench Vice 150mm',249.00),
+  ('SKU-200','Torque Wrench',389.50),
+  ('SKU-300','Impact Driver',179.95),
+  ('SKU-400','Socket Set 42pc',129.00);
+
+INSERT INTO invoice (id, customer_id, sold_by, invoice_date, total) VALUES
+  (1001,1,3,'2025-03-14',627.95),
+  (1002,1,3,'2025-07-02',389.50),
+  (1003,2,4,'2025-08-19',258.00),
+  (1004,4,3,'2026-01-08',1247.40),
+  (1005,4,4,'2026-05-21',179.95),
+  (1006,5,NULL,'2026-07-30',908.00),
+  -- Deliberately has no lines. An aggregate over no children must count 0
+  -- and sum to null, and without a childless parent in the fixture that
+  -- distinction cannot be tested at all.
+  (1007,3,4,'2026-08-02',0);
+
+INSERT INTO invoice_line VALUES
+  (1001,1,'SKU-100',1),(1001,2,'SKU-300',2),
+  (1002,1,'SKU-200',1),
+  (1003,1,'SKU-400',2),
+  (1004,1,'SKU-200',2),(1004,2,'SKU-300',1),(1004,3,'SKU-400',2),
+  (1005,1,'SKU-300',1),
+  (1006,1,'SKU-100',2),(1006,2,'SKU-200',1);
+
+INSERT INTO shipment (id, invoice_id, line_no, shipped_on) VALUES
+  (1,1001,1,'2025-03-16'),(2,1001,2,'2025-03-16'),
+  (3,1002,1,'2025-07-04'),(4,1004,1,'2026-01-10'),(5,1004,2,NULL);
+`;
+export function makeDemoDatabase(file) {
+    mkdirSync(dirname(file), { recursive: true });
+    rmSync(file, { force: true });
+    const db = new DatabaseSync(file);
+    db.exec('PRAGMA foreign_keys = ON');
+    db.exec(SCHEMA);
+    db.exec(DATA);
+    db.close();
+}
+/* ---------- bulk seeding ----------
+
+   Opt-in, and deterministic. The small fixture above is what the test suite
+   asserts against — `customer` has exactly five rows and several tests say so
+   — so bulk data is layered on top by request rather than by default.
+
+   Determinism comes from a seeded generator rather than Math.random: the same
+   scale always produces the same database, so a screenshot, a row count or a
+   reported bug can be reproduced exactly. */
+/** mulberry32 — small, fast, and good enough for plausible-looking data. */
+function rng(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+const FIRST = ['Ada', 'Miles', 'Rina', 'Tom', 'Joan', 'Priya', 'Hugo', 'Wren', 'Kofi', 'Ines', 'Bo', 'Yuki', 'Omar', 'Lena', 'Fitz', 'Nadia', 'Ravi', 'Signe', 'Cormac', 'Tess'];
+const LAST = ['Fraser', 'Okonkwo', 'Petrova', 'Whitfield', 'Alvarez', 'Nair', 'Lindqvist', 'Baptiste', 'Mensah', 'Duarte', 'Kirby', 'Tanaka', 'Haddad', 'Vogel', 'Moss', 'Rahman', 'Iyer', 'Bergen', 'Doyle', 'Whelan'];
+const NOUN = ['Freight', 'Coffee', 'Tools', 'Vineyards', 'Logistics', 'Foundry', 'Provisions', 'Marine', 'Timber', 'Electrics', 'Joinery', 'Bakery', 'Optics', 'Fabrication', 'Roasters', 'Surveying', 'Plumbing', 'Glassworks'];
+const PLACE = ['Harbour', 'Pennine', 'Dry Creek', 'Southerly', 'Kereru', 'Otway', 'Blackwood', 'Fitzroy', 'Kaimai', 'Torrens', 'Mallee', 'Waikato', 'Bendigo', 'Arthurs', 'Nullarbor', 'Kimberley'];
+const TITLES = ['Account Executive', 'Sales Manager', 'Support Lead', 'Field Technician', 'Operations Analyst', 'Warehouse Lead', 'Credit Controller', 'Regional Manager'];
+/* The countries a seeded demo spreads its customers over, beyond the three the
+   fixture declares. Real places with real names, because a column of `CC-07`
+   teaches nothing about what a grouped answer looks like. */
+const MORE_COUNTRIES = [
+    ['IE', 'Ireland'], ['CA', 'Canada'], ['US', 'United States'], ['DE', 'Germany'],
+    ['FR', 'France'], ['ES', 'Spain'], ['IT', 'Italy'], ['NL', 'Netherlands'],
+    ['SE', 'Sweden'], ['NO', 'Norway'], ['JP', 'Japan'], ['SG', 'Singapore'],
+    ['ZA', 'South Africa'], ['BR', 'Brazil'], ['IN', 'India'],
+];
+const GEAR = ['Bench Vice', 'Torque Wrench', 'Impact Driver', 'Socket Set', 'Angle Grinder', 'Circular Saw', 'Air Compressor', 'Bandsaw', 'Drill Press', 'Welder', 'Lathe Chuck', 'Caliper Set'];
+/* A deliberately awkward table, created only when seeding.
+
+   Everything here is something that is easy to get wrong and easy to miss:
+   twenty-seven columns so the grid has to scroll and the column chooser has
+   to be usable; *two* self-references, because code that handles one often
+   assumes there is only one; eight outgoing keys and two incoming, so the
+   neighbourhood diagram has to lay out both directions at once; and three
+   separate references to the same table, which a naive reverse-reference
+   count collapses into one.
+
+   It is kept out of the base fixture on purpose — several tests assert the
+   exact table list, and that assertion is worth keeping honest. */
+const WIDE_SCHEMA = `
+CREATE TABLE work_order (
+  id              INTEGER PRIMARY KEY,
+  reference       TEXT NOT NULL,
+  parent_id       INTEGER REFERENCES work_order(id),
+  supersedes_id   INTEGER REFERENCES work_order(id),
+  customer_id     INTEGER NOT NULL REFERENCES customer(id),
+  raised_by       INTEGER REFERENCES employee(id),
+  assigned_to     INTEGER REFERENCES employee(id),
+  approved_by     INTEGER REFERENCES employee(id),
+  country_code    TEXT REFERENCES country(code),
+  product_sku     TEXT REFERENCES product(sku),
+  invoice_id      INTEGER REFERENCES invoice(id),
+  -- A CHECK rather than a bare TEXT column, because that is how most SQLite
+  -- and Postgres schemas actually spell an enum -- and it is the vocabulary
+  -- the table tool reports and the insert form offers.
+  status          TEXT NOT NULL DEFAULT 'open'
+                    CHECK (status IN ('open','scheduled','in_progress','awaiting_parts','on_hold','completed','cancelled')),
+  priority        INTEGER NOT NULL DEFAULT 3,
+  is_urgent       INTEGER NOT NULL DEFAULT 0,
+  is_billable     INTEGER NOT NULL DEFAULT 1,
+  opened_on       DATE NOT NULL,
+  due_on          DATE,
+  closed_on       DATE,
+  estimated_hours REAL,
+  actual_hours    REAL,
+  labour_cost     REAL NOT NULL DEFAULT 0,
+  parts_cost      REAL NOT NULL DEFAULT 0,
+  total_cost      REAL NOT NULL DEFAULT 0,
+  site_address    TEXT,
+  external_ref    TEXT,
+  notes           TEXT,
+  sys_updated_at  TIMESTAMP NOT NULL
+);
+
+CREATE INDEX work_order_customer_idx ON work_order (customer_id, status);
+CREATE INDEX work_order_opened_idx   ON work_order (opened_on);
+
+CREATE TABLE work_order_note (
+  id            INTEGER PRIMARY KEY,
+  work_order_id INTEGER NOT NULL REFERENCES work_order(id),
+  author_id     INTEGER REFERENCES employee(id),
+  written_on    DATE NOT NULL,
+  body          TEXT NOT NULL
+);
+
+CREATE TABLE work_order_part (
+  work_order_id INTEGER NOT NULL REFERENCES work_order(id),
+  line_no       INTEGER NOT NULL,
+  sku           TEXT NOT NULL REFERENCES product(sku),
+  quantity      INTEGER NOT NULL DEFAULT 1,
+  PRIMARY KEY (work_order_id, line_no)
+);
+`;
+const STATUSES = ['open', 'scheduled', 'in_progress', 'awaiting_parts', 'on_hold', 'completed', 'cancelled'];
+const STREETS = ['Wharf Rd', 'Kembla St', 'Beach Pde', 'Rundle Ml', 'Flinders Ln', 'Cuba St', 'Vulcan Ln'];
+const NOTE_TEXT = [
+    'Attended site, isolated the unit and confirmed the fault reported by the customer.',
+    'Parts ordered from the supplier. Lead time quoted as five working days.',
+    'Customer requested the visit be rescheduled to the following week.',
+    'Work completed and signed off on site. No further action required.',
+];
+export function seedDemoDatabase(file, { scale = 1000, seed = 20260822 } = {}) {
+    const db = new DatabaseSync(file);
+    const random = rng(seed);
+    const pick = (list) => list[Math.floor(random() * list.length)];
+    const between = (lo, hi) => lo + Math.floor(random() * (hi - lo + 1));
+    /* More countries, but only when seeding.
+  
+       The small fixture has three, which is right for it — several tests count
+       that table. It is wrong for a demo: "which countries have the most
+       customers" is one of the questions `breakdown` exists to answer and one
+       of the examples in the README, and three groups does not show what a
+       breakdown is for. Inserted here rather than in the fixture so the tests
+       that assert three keep asserting three.
+  
+       `INSERT OR IGNORE`, so seeding a database twice is not an error. */
+    const insertCountry = db.prepare('INSERT OR IGNORE INTO country (code, name) VALUES (?, ?)');
+    for (const [code, name] of MORE_COUNTRIES)
+        insertCountry.run(code, name);
+    const countries = db.prepare('SELECT code FROM country').all()
+        .map((r) => r.code);
+    /* One transaction for the whole load. Without it SQLite commits per
+       statement and a hundred thousand rows takes minutes instead of seconds. */
+    db.exec('BEGIN');
+    try {
+        const employees = Math.max(8, Math.round(scale / 12));
+        const insertEmployee = db.prepare('INSERT INTO employee (first_name, last_name, title, manager_id, hired_on) VALUES (?, ?, ?, ?, ?)');
+        for (let i = 0; i < employees; i++) {
+            // Managers are drawn from employees already inserted, so the
+            // self-reference always points backwards and never dangles.
+            const managerId = i < 3 ? null : between(1, 3 + Math.floor(i / 4));
+            insertEmployee.run(pick(FIRST), pick(LAST), pick(TITLES), managerId, `${between(2018, 2026)}-${String(between(1, 12)).padStart(2, '0')}-${String(between(1, 28)).padStart(2, '0')}`);
+        }
+        const employeeCount = Number(db.prepare('SELECT COUNT(*) AS n FROM employee').get().n);
+        const insertProduct = db.prepare('INSERT INTO product (sku, name, unit_price) VALUES (?, ?, ?)');
+        const products = Math.max(20, Math.round(scale / 4));
+        const skus = [];
+        for (let i = 0; i < products; i++) {
+            const sku = `SKU-${String(1000 + i)}`;
+            skus.push(sku);
+            insertProduct.run(sku, `${pick(GEAR)} ${between(50, 900)}mm`, Math.round(random() * 90000) / 100);
+        }
+        const insertCustomer = db.prepare('INSERT INTO customer (name, email, country_code, credit_limit, active, signed_up) VALUES (?, ?, ?, ?, ?, ?)');
+        for (let i = 0; i < scale; i++) {
+            const name = `${pick(PLACE)} ${pick(NOUN)}`;
+            // Roughly one in nine has no email and one in eleven no country, so the
+            // null rendering and `is empty` filters have something to find.
+            const email = random() < 0.11 ? null : `${name.toLowerCase().replace(/[^a-z]+/g, '.')}@example.com`;
+            insertCustomer.run(name, email, random() < 0.09 ? null : pick(countries), between(0, 40) * 250, random() < 0.18 ? 0 : 1, `${between(2021, 2026)}-${String(between(1, 12)).padStart(2, '0')}-${String(between(1, 28)).padStart(2, '0')}`);
+        }
+        const customerCount = Number(db.prepare('SELECT COUNT(*) AS n FROM customer').get().n);
+        const insertInvoice = db.prepare('INSERT INTO invoice (customer_id, sold_by, invoice_date, total, status) VALUES (?, ?, ?, ?, ?)');
+        /* A spread of statuses, weighted the way a ledger actually looks: mostly
+           settled, a working set outstanding, a few never finished.
+    
+           Without this every seeded invoice took the column default and the demo
+           answered `invoice count by status` — the first example in the README —
+           with a single group of eighteen thousand. The CHECK constraint on the
+           column lists four values; a demo that only ever shows one of them
+           teaches nothing about the column, the constraint, or the breakdown. */
+        const STATUSES = [['paid', 0.62], ['issued', 0.24], ['draft', 0.11], ['void', 0.03]];
+        const statusFor = () => {
+            let r = random();
+            for (const [name, share] of STATUSES) {
+                if (r < share)
+                    return name;
+                r -= share;
+            }
+            return 'issued';
+        };
+        const insertLine = db.prepare('INSERT INTO invoice_line (invoice_id, line_no, sku, quantity) VALUES (?, ?, ?, ?)');
+        const insertShipment = db.prepare('INSERT INTO shipment (invoice_id, line_no, shipped_on) VALUES (?, ?, ?)');
+        const invoices = scale * 6;
+        let nextInvoiceId = Number(db.prepare('SELECT COALESCE(MAX(id), 0) + 1 AS n FROM invoice').get().n);
+        for (let i = 0; i < invoices; i++) {
+            const id = nextInvoiceId++;
+            const date = `${between(2023, 2026)}-${String(between(1, 12)).padStart(2, '0')}-${String(between(1, 28)).padStart(2, '0')}`;
+            let total = 0;
+            const lines = between(1, 6);
+            insertInvoice.run(between(1, customerCount), random() < 0.08 ? null : between(1, employeeCount), date, 0, statusFor());
+            for (let line = 1; line <= lines; line++) {
+                const quantity = between(1, 12);
+                insertLine.run(id, line, pick(skus), quantity);
+                total += quantity * between(50, 900);
+                // Most lines ship; some are pending, and a few shipped rows carry a
+                // null date so the date column has nulls to render.
+                if (random() < 0.72) {
+                    insertShipment.run(id, line, random() < 0.1 ? null : date);
+                }
+            }
+            db.prepare('UPDATE invoice SET total = ? WHERE id = ?').run(total, id);
+        }
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        db.exec('ROLLBACK');
+        db.close();
+        throw err;
+    }
+    seedWorkOrders(db, random, pick, between, scale);
+    /* ANALYZE so the planner has statistics, and so anything reading row
+       estimates sees real numbers rather than zeros. */
+    db.exec('ANALYZE');
+    db.close();
+}
+/**
+ * The wide table, its notes and its parts.
+ *
+ * Split out because it is a different shape of data from the invoice chain
+ * above, and because the interesting part is the reference pattern rather
+ * than the volume.
+ */
+function seedWorkOrders(db, random, pick, between, scale) {
+    db.exec(WIDE_SCHEMA);
+    const customers = Number(db.prepare('SELECT COUNT(*) AS n FROM customer').get().n);
+    const employees = Number(db.prepare('SELECT COUNT(*) AS n FROM employee').get().n);
+    const invoices = Number(db.prepare('SELECT MAX(id) AS n FROM invoice').get().n);
+    const skus = db.prepare('SELECT sku FROM product').all().map((r) => r.sku);
+    const countries = db.prepare('SELECT code FROM country').all().map((r) => r.code);
+    const orders = Math.max(50, scale * 3);
+    const date = (fromYear) => `${between(fromYear, 2026)}-${String(between(1, 12)).padStart(2, '0')}-${String(between(1, 28)).padStart(2, '0')}`;
+    db.exec('BEGIN');
+    const insert = db.prepare(`
+    INSERT INTO work_order (
+      reference, parent_id, supersedes_id, customer_id, raised_by, assigned_to, approved_by,
+      country_code, product_sku, invoice_id, status, priority, is_urgent, is_billable,
+      opened_on, due_on, closed_on, estimated_hours, actual_hours,
+      labour_cost, parts_cost, total_cost, site_address, external_ref, notes, sys_updated_at
+    ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`);
+    for (let i = 1; i <= orders; i++) {
+        const status = pick(STATUSES);
+        const closed = status === 'completed' || status === 'cancelled';
+        const estimated = Math.round(random() * 400) / 10;
+        const actual = closed ? Math.round(estimated * (0.6 + random()) * 10) / 10 : null;
+        const labour = Math.round((actual ?? 0) * between(80, 190) * 100) / 100;
+        const parts = Math.round(random() * 250000) / 100;
+        /* Parents and predecessors point only at rows already inserted, so both
+           self-references stay acyclic — a cycle here would be legal SQL and a
+           trap for anything that walks the graph. */
+        const parent = i > 10 && random() < 0.22 ? between(1, i - 1) : null;
+        const supersedes = i > 20 && random() < 0.1 ? between(1, i - 1) : null;
+        insert.run(`WO-${String(100000 + i)}`, parent, supersedes, between(1, customers), random() < 0.05 ? null : between(1, employees), random() < 0.15 ? null : between(1, employees), closed && random() < 0.8 ? between(1, employees) : null, random() < 0.12 ? null : pick(countries), random() < 0.3 ? null : pick(skus), random() < 0.55 && invoices ? between(1001, invoices) : null, status, between(1, 5), random() < 0.18 ? 1 : 0, random() < 0.85 ? 1 : 0, date(2023), random() < 0.9 ? date(2024) : null, closed ? date(2024) : null, estimated, actual, labour, parts, Math.round((labour + parts) * 100) / 100, `${between(1, 400)} ${pick(STREETS)}`, random() < 0.4 ? `EXT-${between(10000, 99999)}` : null, random() < 0.5 ? pick(NOTE_TEXT) : null, `${date(2025)}T${String(between(0, 23)).padStart(2, '0')}:${String(between(0, 59)).padStart(2, '0')}:00`);
+    }
+    const insertNote = db.prepare('INSERT INTO work_order_note (work_order_id, author_id, written_on, body) VALUES (?,?,?,?)');
+    const insertPart = db.prepare('INSERT INTO work_order_part (work_order_id, line_no, sku, quantity) VALUES (?,?,?,?)');
+    for (let id = 1; id <= orders; id++) {
+        for (let n = 0; n < between(0, 4); n++) {
+            insertNote.run(id, random() < 0.1 ? null : between(1, employees), date(2024), pick(NOTE_TEXT));
+        }
+        const parts = between(0, 5);
+        for (let line = 1; line <= parts; line++) {
+            insertPart.run(id, line, pick(skus), between(1, 20));
+        }
+    }
+    db.exec('COMMIT');
+}

package/dist/server/index.js

@@ -12,6 +12,7 @@ import { readFile } from 'node:fs/promises';
 import { extname, join, normalize } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { ANSI_STYLE, ESTIMATE_ABOVE, MYSQL_STYLE, POSTGRES_STYLE, clampLimit, clampOffset, } from '../adapters/adapter.js';
 import { Registry, loadConfig, redact, configLocations, saveConfig } from './connections.js';
 import { Refusal } from '../adapters/adapter.js';
@@ -42,14 +43,18 @@ function parseArgs(argv) {
     const opts = {
         target: '', port: 4111, host: '127.0.0.1', schemas: [], open: false, noConfig: false,
         allowedHosts: [], mcp: false, outputSchema: false, tools: '',
-        help: false, version: false,
+        help: false, version: false, demo: false, portGiven: false,
     };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === '--db' || arg === '-d')
             opts.target = argv[++i] ?? '';
-        else if (arg === '--port' || arg === '-p')
+        else if (arg === '--port' || arg === '-p') {
             opts.port = Number(argv[++i] ?? 4111);
+            opts.portGiven = true;
+        }
+        else if (arg === '--demo')
+            opts.demo = true;
         else if (arg === '--host')
             opts.host = argv[++i] ?? '127.0.0.1';
         else if (arg === '--allowed-host')
@@ -128,6 +133,8 @@ Options:
       --schema <name> Postgres only; repeatable. Defaults to all user schemas.
       --config <path> Read connections from this file
       --no-config     Ignore any config file
+      --demo          Build a throwaway sample database and open it. Nothing of
+                      yours is touched; it lives in the temp directory.
       --open          Open a browser once the server is up
       --mcp           Speak MCP on stdio for coding agents, instead of HTTP
       --tools <name>  Offer one job's worth of tools instead of all of them:
@@ -258,9 +265,33 @@ async function main() {
             process.exit(1);
         }
     }
+    /* `--demo`: a throwaway database, built on the fly, so a fresh install has
+       something to walk without a database of its own. It is written into the
+       OS temp directory, small and deterministic, and rebuilt each run (a few
+       tens of milliseconds) so it never drifts from the schema this version
+       knows. Naming a real target alongside it is a contradiction, so the target
+       wins and the flag is ignored with a word rather than silently. */
+    if (opts.demo) {
+        if (opts.target) {
+            console.log(`tablewalk: ignoring --demo because a database was named (${redact(opts.target)}).`);
+        }
+        else {
+            const { makeDemoDatabase, seedDemoDatabase } = await import('./demo.js');
+            const file = join(tmpdir(), 'tablewalk-demo.db');
+            makeDemoDatabase(file);
+            seedDemoDatabase(file, { scale: 150 });
+            opts.target = file;
+            /* Serving a demo without opening it would be handing someone a URL and
+               hoping they paste it. The one mode where that is wrong is a
+               print-and-exit or MCP run, which never opens anything. */
+            if (!opts.mcp && !opts.export && !opts.lint && !opts.diff)
+                opts.open = true;
+            console.log('tablewalk: built a demo database — 11 tables to walk. Nothing of yours is touched.');
+        }
+    }
     if (opts.target) {
         const added = registry.add({
-            name: redact(opts.target),
+            name: opts.demo ? 'demo' : redact(opts.target),
             url: opts.target,
             schemas: opts.schemas,
             source: 'argument',
@@ -414,7 +445,31 @@ async function main() {
         layouts: configLayouts,
         bound: { host: opts.host, port: opts.port, allowedHosts: opts.allowedHosts },
     });
-    server.listen(opts.port, opts.host, () => {
+    /* A busy port is a normal thing, not a stack trace.
+  
+       `server.listen` with no error handler throws EADDRINUSE and takes the
+       process down with a Node-internal trace — which is what happened when a
+       second `tablewalk` met the first on 4111. So: if the port was the default
+       and something is already there, roll on to the next one and say so; if it
+       was named explicitly with --port, respect that and fail with one clear
+       line rather than a guess the caller did not ask for. */
+    const FIRST_PORT = opts.port;
+    server.on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+            if (!opts.portGiven && opts.port - FIRST_PORT < 20) {
+                console.log(`tablewalk: port ${opts.port} is in use, trying ${opts.port + 1}…`);
+                opts.port += 1;
+                setImmediate(() => server.listen(opts.port, opts.host));
+                return;
+            }
+            console.error(`tablewalk: port ${opts.port} is already in use.`
+                + (opts.portGiven ? ' Pick another with --port <n>.' : ' Give it a free one with --port <n>.'));
+            process.exit(1);
+        }
+        console.error(`tablewalk: ${err.message}`);
+        process.exit(1);
+    });
+    server.on('listening', () => {
         const shown = opts.host === '127.0.0.1' ? 'localhost' : opts.host;
         console.log(`Listening on http://${shown}:${opts.port}`);
         if (nothingToOpen) {
@@ -438,6 +493,7 @@ async function main() {
         if (opts.open)
             void openBrowser(`http://${shown}:${opts.port}`);
     });
+    server.listen(opts.port, opts.host);
     const shutdown = async () => {
         server.close();
         await registry.closeAll();
@@ -2114,7 +2170,22 @@ async function readJson(req) {
 async function openBrowser(url) {
     const { spawn } = await import('node:child_process');
     const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-    spawn(cmd, [url], { detached: true, stdio: 'ignore' }).unref();
+    try {
+        const child = spawn(cmd, [url], { detached: true, stdio: 'ignore' });
+        /* A headless box — a container, a server, an SSH session — has no
+           `xdg-open`, and `spawn` reports that as an `error` event, not a throw.
+           With no handler Node re-raises it as an uncaught exception and takes the
+           whole process down — so `--open`, and `--demo` which implies it, crashed
+           exactly where it was most useful: the container serving the demo. A
+           missing opener is not fatal. The server is already listening and the URL
+           is already printed; opening it is a convenience, not a requirement. */
+        child.once('error', () => { });
+        child.unref();
+    }
+    catch {
+        /* Some platforms throw synchronously instead. Same non-answer: the server
+           stays up, the URL is on screen, the reader opens it themselves. */
+    }
 }
 /* Started only when run, not when imported.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tablewalk",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Follow the data. A database browser built around the walk: a foreign key is a place you can go.",
   "license": "MIT",
   "author": "Baljinder Randhawa",