@mason-data/cli 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/README.md

@@ -1,3 +1,269 @@
-# Temporary Holding Version
+# @mason-data/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `mason` command points [Mason](https://masondata.ai) at the Postgres your app already uses, copies the tables you
+add, keeps the copy current, and serves it to BI tools and your app over the Postgres protocol. Every command works the
+same for you and for a coding agent (Claude Code, Codex, …): it prints for a person, or with `--json` as data, and its
+exit code says how it went ([for coding agents](#for-coding-agents)).
+
+There is nothing to clone or build: install this package and run `mason`. It needs Node 22.13 or later and nothing
+else — no Docker, no database of its own; `mason doctor` checks this machine and says what is missing. On a terminal
+its output is coloured and wrapped to the window, and a command that takes a moment shows a spinner; piped,
+redirected, with `--json` or with `NO_COLOR` set, it is plain text.
+
+**A Mason project is your app's folder.** `mason init` makes it one: its sources file in `mason/sources/` — the
+database and the tables to copy — yours to commit; this machine's copy of your data and Mason's state in `.mason/`,
+both rebuilt from that file. Every other command works
+anywhere in the folder, as git does. `mason destroy` removes the copy and the state. ([Cleaning up](#cleaning-up))
+
+```sh
+npm i -g @mason-data/cli
+cd my-app
+mason doctor                         # Node, memory, ports: what is missing, and what to do
+mason init                           # this folder becomes a project, on the database in .env's DATABASE_URL (checked first)
+mason tables                         # the tables: rows, keys, added; a table's columns with `mason tables orders`
+mason add orders customers           # add them to the sources file (--columns id,status: those only)
+mason start                          # Mason in the background, copying them, then returns
+mason wait                           # until every added table is copied and served
+mason user add metabase              # a user for a BI tool: its password, printed once, and the URL to paste
+mason ui                             # the status page and the users, in your browser
+```
+
+`mason init` takes the database's URL as an argument too (`mason init postgres://user:password@localhost:5432/your_app`);
+without one it reads `DATABASE_URL` from the folder's `.env.local`, `.env` or the shell. The sources file it writes says
+`url: ${DATABASE_URL}`, and the URL itself stays in `.env` (init writes the line there when you gave the URL as an
+argument or it was only in the shell, and gitignores that file): change it there when the password changes. The
+database is required.
+
+**No database at hand?** `mason init demo && mason start`, in a new folder, makes a project on a demo database Mason
+hosts itself — a small shop (`customers`, `products`, `orders`, `order_items`; the first three added, `order_items`
+left for your first `mason add order_items` after `mason start`), kept in `.mason/demo/`, served on a port of this machine, with a new order every few seconds (`MASON_DEMO_CHANGE_MS`, default 5000) so
+`mason status` shows the copy keeping up. Nothing to install. It is read by polling only (it has no change log), and
+`mason destroy` removes it with the copy.
+
+## The project: its sources file, in your app
+
+```
+my-app/
+  .env                    the database's URL (DATABASE_URL), as your app has it (gitignored)
+  .mason/                 this machine's: Mason's key, the copy of your data, its state and logs (gitignored)
+  mason/sources/app.yml   the database and the tables Mason copies — commit it
+  mason/mason.yml         the Mason version the project is written for — commit it: production runs that version
+```
+
+The sources file is named for the database (`app.yml` above) and lists what Mason copies, one entry per table:
+
+```yaml
+kind: postgres
+url: ${DATABASE_URL}          # a variable from .env.local, .env or the shell; a literal URL is allowed for local dev
+tables:
+  orders:                     # a bare name is in `public`; `billing.invoices` names its schema
+    columns: [id, customer_id, status, amount, created_at, payload]
+  customers: {}               # every column
+  events:
+    exclude: [raw_body]       # every column but these
+  sessions:
+    key: [tenant_id, id]      # only for a table with no primary key: the unique columns to copy it by
+```
+
+- An entry is `{}` (every column), `columns:` (those; the primary key is always copied), `exclude:` (every column but
+  those) — never both — and, for a table with no primary key, `key:`: the columns that tell its rows apart, which it is
+  copied by (polling only: logical replication cannot apply a change by them). A table with a primary key refuses `key:`.
+- Column types are not in the file: Mason reads them from the database at every start.
+- `url:` is `${NAME}`, read from `.env.local`, `.env` or the shell — or a literal URL, for a database on your machine.
+- One source per project for now, and `postgres` is its only kind.
+- `mason add` and `mason remove` edit one entry and keep every other byte of the file, your comments included, and
+  apply at once; an entry you edit by hand is applied at the next `mason start`. A mistake — a column the table does
+  not have, `columns` and `exclude` together, a variable that is not set — is refused, every one of the file's
+  mistakes on one report, each with its key and the way out (`did you mean …?`).
+
+`mason init --folder <dir>` puts `sources/` elsewhere in the folder (`--folder .` for the folder itself). Keep it in
+your app's repo, so a schema change and the tables that copy it travel together. A teammate who clones the repo runs
+`mason init` once: the sources file is kept, and `.mason/` is per machine.
+
+**A project an older Mason made** (its tables listed in `mason/models/`) is refused by `mason start`; nothing is
+migrated. `mason init` in it writes the sources file alone — its `.mason/` and copy kept — then `mason add` each table
+again and remove `mason/models/`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `mason help [<command> \| <guide>]` | The commands by step, one command's usage, or one of the guides, offline: `mason help agent` (driving Mason from a coding agent: the commands in order, `--json` and its shapes, exit codes, failures) and `mason help production` (the road from a laptop to production: the image, its settings, Docker Compose, logical replication, upgrades). |
+| `mason doctor` | Checks what Mason needs here — Node 22.13+, memory, Mason's ports — and in a project's folder its database; with Mason running for it, the run itself: whether every added table is copied, the statements refused or slow in the last day. Every failing line says what to do; it ends with the next command. |
+| `mason init [<postgres url>]` | Makes this folder a project: checks it can read the database (nothing is written when it cannot; `--skip-check` writes anyway), writes `.mason/config.json` (Mason's key, never the URL) and `mason/sources/<database>.yml` (keeping a sources file already there), adds the URL to `.env` when it was not there, and adds `.mason/` and that `.env` to `.gitignore`. The URL from the argument, else `DATABASE_URL` in `.env.local`, `.env` or the shell. `--name` sets the project's name (default: the folder's) — the database name a tool connects to — `--folder` where its files go, `--remote` allows a database on another machine. Refuses a folder already in a project, but for one with no sources file (an older Mason's), whose sources file alone it writes. |
+| `mason start` | Starts Mason for this folder's project in the background and returns once it is up. Run it again any time: it says so when Mason is already running. `--replication` reads the database's change log as production does (below); `--poll` goes back. `--self-signed-tls` serves the Postgres API over TLS; `--attach` stays in the foreground. |
+| `mason tables [<table>…] [--all]` | The tables this user can read against the sources file, one line each: rows, primary key, whether added (and with which columns), and why a table cannot be added yet (no primary key: the `--key` to add it by). Name a table (or pass `--all` for every one) for its columns: each one's type, what it references, and whether `mason add` would leave it out as a secret. It reads the project's database itself, so Mason need not be running. |
+| `mason add <table>… [--columns …] [--include …] [--key …]` | Copies tables into Mason, each one an entry of the sources file: every column (`orders: {}`), or `--columns id,status,created_at` for those (one table at a time; the key is written with them). Columns that look like secrets (`password`, `token`, `api_key`, `private_key`, …) are left out, named, and written as `exclude:`; `--include password_hash` adds one. `--key tenant_id,id` adds a table with no primary key, copied by those columns. Adding a table again with other columns changes its entry. Mason need not be running: the entry is checked against the database as the run checks it, and the copy begins at `mason start` (with Mason running, at once). |
+| `mason remove <table>…` | Takes tables out of the sources file — each one's entry, every other byte as it was — and Mason drops their copies: at once when it is running, else at the next `mason start`. Mason need not be running. |
+| `mason wait [--timeout <s>]` | Waits until every added table is copied and served, showing every added table on a line of its own: 100% for the finished ones, in the order they finished, and a bar for each still copying (rows, %, rate, time left) at the bottom. Exit 0 ready, 1 a copy failed (printed, with what to do), 124 timed out (default 600 s). |
+| `mason user add\|list\|remove <name>` | The users of the Postgres API: a name and a password that does not expire, as a BI tool's datasource form asks for them or an app's `DATABASE_URL` carries them. `add` prints the password once with the URL; `remove` refuses the next connection at once and ends the sessions it holds at their next statement, without a restart. |
+| `mason mcp [--url <url>]` | An MCP server on stdio for Claude Code, Claude Desktop and other agents (below): the tables Mason serves with each copy's rows and how current it is, a table's columns, a statement's rows with their Postgres types or Mason's refusal with its way out, and EXPLAIN — connected as a `mason user` (`MASON_URL`, else `--url`), beside `mason start` or a `mason serve` elsewhere. |
+| `mason ui` | Opens the running Mason's web page in your browser: what `mason status` says, refreshed every 2 s, and the users of `mason user` (add one, its password shown once; remove one). It prints the URL with the run's token, which the page trades for a cookie on the first visit; `--no-open` prints it only, `--json` is `{ url, port }`. `mason start`'s alone: `mason serve` serves no page. |
+| `mason status` | What Mason is doing: the database and how its changes are read, the project folder, the copy's file, the Postgres API and how it listens, each table's copy, the statements answered slowly in the last day and the ones refused or failed, each with its reason. In replication mode, where the stream is. |
+| `mason sync <table>…` | Makes the copy of these tables current now: a table over the sync's row limit (1,000,000 rows) is copied and served but kept current only so, or by replication. |
+| `mason logs [-n <lines>] [-f] [--start] [--requests [--failed]]` | Mason's log: every copy, poll and statement, with warnings and errors and their reasons; `-f` follows it, `--start` shows what `mason start` printed instead. `--requests` is the request log: every statement a tool sent, when, the outcome and SQLSTATE, how long, the rows, the tool and the user; `--failed` only the refused and failed ones. |
+| `mason stop` | Stops Mason for this project. The copy and the state stay: the next `mason start` resumes in seconds. |
+| `mason destroy` | Removes this project's copy of the data (its file) and Mason's state in `.mason/`, stopping Mason first if it runs — and, for a project started with `--replication`, its slot and publication on the database. Your files, `.mason/config.json` and the users stay: the next `mason start` copies the tables again. |
+| `mason serve` | Mason for a server or a container: `mason start --attach` configured by the environment alone, its state in one folder (a volume), its log on stdout, `GET /healthz`, a clean stop on SIGTERM. `mason serve --help` lists every setting with its default. |
+
+Every command documents itself: `mason --help` lists them, and `mason <command> --help` (or `mason help <command>`) says
+how to use one, with examples. Every command but `help` and `mcp` (whose stdout is the MCP protocol's) takes `--json`. A command means the project of the folder it
+runs in, or the nearest one above it.
+
+## What `mason start` does
+
+1. **It only reads the database** — the one the sources file names. Mason polls it with `SELECT` statements. It does not
+   need `wal_level = logical`, a replication slot, a publication or the `REPLICATION` attribute, and it creates none of
+   them. When you stop it, nothing is left behind on the database. A table over 1,000,000 rows is copied and served but
+   kept current only by `mason sync` or by replication, and `mason status` says so on its line. (`--replication` is the
+   exception, said below: it reads the change log, as production does, and makes its own slot.)
+2. **It copies each added table** into a DuckDB file in `.mason/`, a range of pages at a time, a few in parallel, one
+   Postgres backend each, smallest table first; a copy that stops continues with the ranges it did not commit. The table
+   is served the moment its copy lands; the copy runs beside the polls, never instead of them.
+3. **It serves the Postgres API** on 5433, or on the next port free on every address when something holds 5433 (often a
+   second Postgres; `mason start` says what held it) — and records it: every later start listens on the same port, so a
+   tool's saved connection keeps working, and refuses, naming what holds it, rather than move. `MASON_PG_PORT=55433` in
+   your shell names the port, or moves the project to it (said). It listens on 127.0.0.1 unless `MASON_PG_HOST` names
+   another address; off this machine it needs TLS (`--self-signed-tls`, or `MASON_PG_TLS_CERT` / `MASON_PG_TLS_KEY`).
+4. **It runs in the background**, copying what the sources file names: `mason add` and `mason remove` change it at once,
+   a hand edit (or an add or remove made while Mason was stopped) at the next `mason start`.
+
+Mason's own settings (`MASON_POLL_MS`, `MASON_DUCKDB_MEMORY`, `MASON_COPY_PARALLEL`, …) set in your shell reach Mason.
+A copy reads `MASON_COPY_PARALLEL` chunks at once (default 3), each sized to take about `MASON_COPY_CHUNK_SECONDS` to
+read (default 12) at the rate it measures on your connection, so `mason wait` moves every few seconds even over a slow
+link, and a copy that stops reads at most those chunks again.
+A JSON value your queries keep reading (`payload ->> 'customer_id'`) is stored as a column of the copy and read from
+there (`mason status` lists them); `MASON_STORE_JSON_PATHS=off` turns that off.
+
+## `mason start` options
+
+| Option | What it does |
+|---|---|
+| `--replication` | Read the database's changes from its change log (logical replication), as production does, instead of polling. It needs `wal_level = logical` and a user that may replicate, and makes its own publication and slot (`mason_dev_<project>_<source>`, the source the sources file's name; past 63 bytes, a prefix and a hash) on the database. The project keeps the mode until `--poll`; a switch keeps the copies and catches each table up by one poll. `mason stop` leaves the slot (it holds WAL until the next start); `mason destroy` and `--poll` drop it. |
+| `--publication <name>` | With `--replication`: a publication the database owner made (else `PG_PUBLICATION`), read as it is, verified to carry every added table and column, never created, altered or dropped. A read replica needs one. |
+| `--poll` | Read them with `SELECT` again (the default). |
+| `--self-signed-tls` | The Postgres API requires TLS, from a certificate made for this project in `.mason/` (served again by every later start with the flag); clients connect with `sslmode=require`. |
+| `--port <n>` | The port the `mason` commands reach it on (default 4039, or the next free one). |
+| `--attach` | Stay in the foreground: the terminal shows Mason's progress, and Ctrl-C stops it. |
+
+A database on another machine needs `mason init --remote`, which records that you mean it: the copy leaves the
+database's network, and each added table under the row limit is read whole every few seconds (`--replication` reads only
+its changes). Point it at a read replica, never the primary your app writes to.
+
+**When the database moves.** Mason records the Postgres server it copied from. The same database on a new server (a
+restore, a move to another host) is read again at the next `mason start`: every row is compared with the copy, and only
+what changed is written. A different database is refused: `mason destroy`, then `mason start`, copies it.
+
+## For coding agents
+
+`mason help agent` is the page an agent reads first, offline: the commands in the order a project takes them, every
+answer's shape, the exit codes and the failure codes. In short:
+
+- Every command but `help` and `mcp` takes `--json` and answers with **one JSON object on stdout**, always with
+  `next: [{ command, what }]` — the commands to run next, the same a person reads under `Next:`. The other keys are the
+  command's own; `mason help <command>` names them on its `--json` line. Lists are wrapped (`{ tables: […], next }`).
+- A failure is `{ "error": { "code", "message", "why", "fix" }, "next": […] }` on stdout, and the **exit code** says it:
+  0 done, 1 failed with the reason, 2 the command line is wrong, 124 `mason wait` ran out of time. The codes are a closed
+  set (`usage`, `no_project`, `bad_config`, `bad_source`, `not_running`, `unreachable`, `not_found`, `nothing_yet`,
+  `refused`, `failed`, `timeout`). For a person the same failure is three short lines — what is wrong, `why`, `fix` — then `Next:`.
+- Progress (a spinner, `mason wait`'s bars) goes to stderr, and only on a terminal; a pipe gets plain text, and nothing
+  under `--json`. The Postgres API's URL is in `mason status --json` (`postgres.url`); a user's password is printed by
+  `mason user add` once: never read `.mason/config.json`.
+
+```sh
+mason doctor --json && mason init --json && mason start --json
+mason tables --json                      # choose the tables
+mason add orders customers --json && mason wait --json
+mason user add app --json                # the password and URL for the app, as data
+```
+
+### From an MCP client: `mason mcp`
+
+A chat agent asks Mason with tools, over MCP, rather than through a shell. `mason mcp` is an MCP server on stdin and
+stdout (newline-delimited JSON-RPC; stdout carries the protocol alone, what it says goes to stderr) that serves until
+the client closes stdin; it takes no `--json`, and says a failure to start on stderr. It connects to the Postgres API as
+a `mason user`, by the URL `mason user add` printed — `MASON_URL`, or `--url` — so it works beside `mason start` as against a `mason serve` elsewhere; TLS is as the URL's `sslmode`
+says (a host off the machine: `require` when it names none). It never makes a user by itself: with no URL, it refuses
+and says `mason user add claude`.
+
+| Tool | Arguments | What it answers |
+|---|---|---|
+| `tables` | none | each table Mason serves, named as a statement writes it (`public.orders`, `public."Clients"`): `rows_about` (the copy's estimate), `kept` (how it is kept current, as `mason status` says it) and `kept_current_by` (`polling`, `logical replication`, `copying again`, or null when nothing keeps it current now) |
+| `describe` | `table` (as `tables` names it, or a bare name in `public`) | its columns with their Postgres types and NOT NULL, its primary key, its foreign keys, comments, and the same rows and `kept` |
+| `query` | `sql`, `max_rows` (200, at most 10,000), `timeout_ms` (30,000, at most 300,000) | `columns` (name, Postgres type), `rows` as Postgres's text, `truncated` when `max_rows` cut it; a refusal is a tool error with the SQLSTATE, message, DETAIL and HINT (the way out) |
+| `explain` | `sql`, `analyze`, `timeout_ms` | Mason's EXPLAIN: each copy read with its rows and how current it is, the SQL it runs, the plan |
+
+Its resources are `mason://help/agent` and `mason://help/mcp` (the two pages `mason help` prints). Every statement it
+runs is in the request log under `application_name` `mason-mcp/<the client's name>` (`mason logs --requests`), a query
+`max_rows` cut with the rows it sent; its catalog reads (the tables, a table's columns) are not, as no catalog read is.
+A request the client cancels (`notifications/cancelled`) cancels its statement on the Postgres API.
+
+Claude Code, in the project's folder with Mason running, the URL in the server's environment (the server's name
+comes before `--env`, which takes every value after it):
+
+```sh
+mason user add claude                    # the URL, printed once
+claude mcp add mason --env MASON_URL="postgres://claude:<password>@127.0.0.1:5433/shop" -- mason mcp
+# or on its command line, where ps shows it to this machine's users and claude mcp add prints it
+claude mcp add mason -- mason mcp --url "postgres://claude:<password>@127.0.0.1:5433/shop"
+```
+
+Claude Desktop, in `claude_desktop_config.json`. The app often starts a server without your shell's `PATH`, where
+neither `mason` nor the `node` its first line asks for is found: name both by their absolute paths (`which node`,
+`which mason`):
+
+```json
+{
+  "mcpServers": {
+    "mason": {
+      "command": "/absolute/path/to/node",
+      "args": ["/absolute/path/to/mason", "mcp"],
+      "env": { "MASON_URL": "postgres://claude:<password>@127.0.0.1:5433/shop" }
+    }
+  }
+}
+```
+
+## Cleaning up
+
+Three things exist once a project has run: your **files** (the sources file, in your app), the **copy of your data** (a
+file in `.mason/`) and **Mason's state** (`.mason/`: its settings, logs and the request log). Each way of cleaning up
+keeps a different set:
+
+| You want | Run | Keeps |
+|---|---|---|
+| Pause | `mason stop` | the data, the state, your files: the next `mason start` resumes in seconds |
+| Copy the data again, or free its disk | `mason destroy` | your files, `.mason/config.json` and the users: the next `mason start` copies everything again |
+
+Restarting the machine is a `mason stop` that nobody ran: the next `mason start` resumes. In a demo project
+(`mason init demo`) the demo database is state too: `mason destroy` removes it with the copy, and the next `mason start`
+seeds it again.
+
+## Requirements
+
+`mason doctor` checks all of this and says what is missing.
+
+- Node 22.13 or later. The SQL parser (`libpg-query`), the catalog (`PGlite`) and the engine (DuckDB) ship as
+  WebAssembly or prebuilt binaries: no native build, no Python or compiler needed.
+- Memory: the copy may use half the container's memory limit by default, else half the machine's RAM
+  (`MASON_DUCKDB_MEMORY=4GB` sets it; `mason doctor` says it). Sizing a server:
+  [deploy/mason-data/README.md#memory](https://github.com/embeddable-hq/mason-data/blob/main/deploy/mason-data/README.md#memory).
+- Postgres 13 or later. Each table needs a primary key, or a `key:` in the sources file (polling only).
+
+## Security
+
+`mason start`'s command server listens on 127.0.0.1 only; each request must carry the run's token, read from the
+project's `.mason/config.json`, which a browser cannot send — or, for its web page (`mason ui`), the cookie the run's token is traded for on the first visit (HttpOnly, SameSite=Strict, its Host and every change's Origin checked). The Postgres API takes a user's password (`mason user`): a
+MAC over its name keyed by the project's API key, so rotating the key removes every user at once. Off loopback the Postgres API is TLS or refused.
+
+What a project keeps on this machine (the database URL, the API key, the run's token, the copy, its log and request
+log) is in its `.mason/`, readable by your user only and gitignored by `mason init`.
+
+## In production
+
+Only the project folder travels — `mason/`, with `mason.yml` naming the Mason version it is written for. Production runs
+it as one container, `ghcr.io/embeddable-hq/mason-data`, with `mason serve`: the same run, configured by the environment,
+its copy on one volume, reading Postgres's change log (`MASON_CHANGES=replication`) or polling it. `mason help
+production` is the road, offline; `deploy/mason-data/` in the repo is the Compose file and its walkthrough.
+
+Apache-2.0.

package/dist/src/api/error.js

@@ -0,0 +1,18 @@
+/**
+ * A refusal the Postgres listener answers as an ErrorResponse: a login or a users file that would not do
+ * (src/duck/users.ts), with the HTTP-style status the listener maps to a SQLSTATE (src/api/postgres/server.ts
+ * `sqlstateOf`) and a stable machine-readable code.
+ */
+export class ApiError extends Error {
+    status;
+    /** The STABLE machine-readable name of the failure (`invalid_user`, `users_unreadable`, ...), carried in the
+     *  ErrorResponse's detail so a reader branches on it instead of parsing `message`. */
+    code;
+    /** The user a refused `mason user` login asked for (src/duck/users.ts): its request-log row names it. */
+    userName;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}

package/dist/src/api/postgres/catalog-worker.js

@@ -0,0 +1,92 @@
+/**
+ * THE CATALOG'S WORKER: PGlite (Postgres as WebAssembly) runs HERE, on a worker thread, never on the listener's own
+ * (review of #480: a forwarded `SELECT pg_sleep(3600)` froze every other Postgres session, and PGlite ignores
+ * `statement_timeout`). The main thread (catalog.ts PgCatalog) posts one request at a
+ * time on the port and holds a deadline for it; past the deadline it TERMINATES this thread and starts another, so a
+ * statement that never ends costs one instance, not the process.
+ *
+ * Messages in: `{ id, op: "init", statements, optional? }` (start PGlite and run the DDL; the reply names the refused
+ * statement, or the optional ones refused),
+ * `{ id, op: "raw", bytes }` (frontend protocol bytes in, backend bytes out), `{ id, op: "query", sql }` (rows as
+ * objects, for the server's own lookups and the tests), `{ id, op: "close" }`. Every reply carries the id:
+ * `{ id, ok: true, bytes | rows }` or `{ id, ok: false, message }`.
+ */
+import { parentPort } from "node:worker_threads";
+import { PGlite } from "@electric-sql/pglite";
+import { citext } from "@electric-sql/pglite/contrib/citext";
+const port = parentPort;
+if (port === null)
+    throw new Error("catalog-worker.ts runs on a worker thread only");
+const errorMessage = (e) => (e instanceof Error ? e.message : String(e));
+let db = null;
+port.on("message", (m) => {
+    void (async () => {
+        try {
+            switch (m.op) {
+                case "init": {
+                    // citext bundled: a copied citext column is declared as itself (catalog.ts `catalogDdl`)
+                    const instance = new PGlite({ extensions: { citext } });
+                    await instance.waitReady;
+                    for (const statement of m.statements) {
+                        try {
+                            await instance.exec(statement);
+                        }
+                        catch (e) {
+                            // the half-made instance is discarded (the start failed, said below with the statement); a close that fails is said too
+                            await instance.close().catch((ce) => console.error(`catalog worker: PGlite did not close cleanly after a refused DDL: ${errorMessage(ce)}`));
+                            throw new Error(`the catalog DDL was refused (${errorMessage(e)}) at:\n${statement}`, { cause: e });
+                        }
+                    }
+                    // a statement the catalog may do without (a source's column default or view, catalog.ts `catalogDefaults`,
+                    // `catalogViews`): each on its own (a multi-statement one is its own implicit transaction: all or none), in
+                    // passes while one more stands — a view over a view stands once the other does — and the refused ones named in
+                    // the reply for the log
+                    let left = [...(m.optional ?? [])];
+                    let refused = [];
+                    for (let progress = true; progress && left.length > 0;) {
+                        refused = [];
+                        for (const statement of left) {
+                            try {
+                                await instance.exec(statement);
+                            }
+                            catch (e) {
+                                refused.push({ statement, message: errorMessage(e) });
+                            }
+                        }
+                        progress = refused.length < left.length;
+                        left = refused.map((r) => r.statement);
+                    }
+                    db = instance;
+                    port.postMessage({ id: m.id, ok: true, ...(refused.length > 0 ? { refused } : {}) });
+                    return;
+                }
+                case "raw": {
+                    if (db === null)
+                        throw new Error("the catalog is not started");
+                    const bytes = await db.execProtocolRaw(m.bytes);
+                    const copy = new Uint8Array(bytes); // PGlite may reuse its buffer: a copy of our own is transferred
+                    port.postMessage({ id: m.id, ok: true, bytes: copy }, [copy.buffer]);
+                    return;
+                }
+                case "query": {
+                    if (db === null)
+                        throw new Error("the catalog is not started");
+                    const result = await db.query(m.sql);
+                    port.postMessage({ id: m.id, ok: true, rows: result.rows });
+                    return;
+                }
+                case "close": {
+                    const instance = db;
+                    db = null;
+                    if (instance !== null)
+                        await instance.close();
+                    port.postMessage({ id: m.id, ok: true });
+                    return;
+                }
+            }
+        }
+        catch (e) {
+            port.postMessage({ id: m.id, ok: false, message: errorMessage(e) });
+        }
+    })();
+});