pgexplain 0.1.0 → 0.2.0

package/README.md

@@ -67,6 +67,34 @@ Point at a directory to analyze every plan in it (batch mode):
 pg-explain ./plans/
 ```
 
+Or launch the local **Studio** — a GUI for everything the CLI does:
+
+```sh
+pg-explain studio        # opens http://127.0.0.1:5177 in your browser
+```
+
+---
+
+## Studio (local web UI)
+
+`pg-explain studio` starts a local, single-user web app (binds `127.0.0.1`, no auth) that
+mirrors the CLI with a friendlier surface. It ships inside the package, so `npx pgexplain studio`
+just works — the PostgreSQL driver and the UI are only loaded on demand.
+
+- **Analyze** a pasted `EXPLAIN (FORMAT JSON)` plan, or **Run** a query (connect → EXPLAIN-only,
+  rollback-wrapped, read-only; non-`SELECT` refused unless forced).
+- **Findings** as plain-language cards (what / why / fix + copy-paste commands + docs links).
+- **Lock advisor** — static warnings (rewrites, missing `CONCURRENTLY`, unindexed `UPDATE/DELETE`,
+  unbounded `FOR UPDATE`, …) plus a **🔒 Live locks** view of current blocking chains.
+- Interactive **plan tree** (heat-colored by self-time), **bottlenecks**, raw JSON.
+- **History** of every run (SQLite under `~/.pgexplain`), **Compare** any two runs (structured
+  diff), and **Export** to Markdown / HTML / JSON.
+- **Saved connections** and a **Settings** page to tune advisor thresholds (applied live).
+
+Flags: `pg-explain studio [--port 5177] [--host 127.0.0.1] [--no-open] [--unsafe-host]`.
+Binding a non-loopback host requires `--unsafe-host` (the studio can reach arbitrary databases,
+so exposing it is an SSRF/credential risk). Set `PGEXPLAIN_DATA_DIR` to relocate the local store.
+
 ---
 
 ## Example output
@@ -180,12 +208,20 @@ Choose with `-f`/`--format` (default `terminal`); write to a file with `-o`/`--o
 | `terminal` | Color, severity heat, and proportional self-time bars for interactive use. |
 | `markdown` | The headline shareable deliverable — paste into a PR or ticket. |
 | `json` | Stable, machine-readable (`schemaVersion = 1`). |
-| `html` | Single self-contained file (no external assets). |
+| `html` | Single self-contained file (no external assets). Auto-opens in your browser when run interactively. |
 | `text` | Plain text, no escapes — good for logs. |
 
 `diff` supports `terminal`, `markdown`, and `json`.
 
-Shared output flags: `--tldr` (summary + findings, no plan tree), `--redact` (strip literal values so the report is safe to share), `--ascii` (ASCII tree glyphs), `--color auto|always|never` / `--no-color`, `--compact` (compact JSON), `--config <path>`, `-q/--quiet`, `--verbose`, `--debug`.
+When you run `-f html` in an interactive terminal, the report opens in your default browser automatically: with `-o report.html` that file is opened, otherwise a temp file is written and opened. Auto-open is off when output is piped/redirected or `CI` is set; use `--open` to force it (e.g. into a file in CI) and `--no-open` to disable it.
+
+```bash
+pg-explain plan.json -f html -o report.html   # writes the file and opens it
+pg-explain plan.json -f html                   # writes a temp file and opens it
+pg-explain plan.json -f html > report.html     # redirected → no open, HTML to stdout
+```
+
+Shared output flags: `--tldr` (summary + findings, no plan tree), `--redact` (strip literal values so the report is safe to share), `--open` / `--no-open` (HTML browser opening), `--ascii` (ASCII tree glyphs), `--color auto|always|never` / `--no-color`, `--compact` (compact JSON), `--config <path>`, `-q/--quiet`, `--verbose`, `--debug`.
 
 ---