tablewalk 0.0.2 → 0.0.4

package/README.md

@@ -1,38 +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 --demo                                   # a sample database, built and opened
-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.
-
-Or `npx tablewalk --demo` — it builds a small sample database (the eleven-table
-one the screenshots use) in a temp directory and opens it, so there is
-something to walk before you have a database of your own. Nothing of yours is
-touched, and the file is thrown away.
+```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
 
@@ -201,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
@@ -493,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/index.js

@@ -2170,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.2",
+  "version": "0.0.4",
   "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",