From f024370e311c63deb938b469ccfdb0a6b17e080a Mon Sep 17 00:00:00 2001 From: NikolayS Date: Sun, 12 Jul 2026 07:13:53 +0000 Subject: [PATCH 1/3] docs: polish user-facing text for clarity and consistency Comprehensive copy review across README, docs, and user-facing text. American English grammar and style, postgres-ai terminology and units, sentence-case headings, SEO/LLM-friendly opening lines. No code, commands, or technical values changed. Relates to #838 --- CHANGELOG.md | 4 ++-- CONTRIBUTING.md | 2 +- README.md | 10 +++++----- docs/COMMANDS.md | 4 ++-- docs/GLOSSARY.md | 6 +++--- docs/WASM.md | 18 +++++++++--------- docs/psql-compat.md | 6 +++--- src/main.rs | 2 +- wasm/index.html | 2 +- 9 files changed, 27 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ed480f7a..d15753a4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - 8 new describe commands: `\dP` (partitioned relations), `\dA`/`\dAc` (access methods / operator classes), `\dO` (collations), `\dF`/`\dFd`/`\dFp`/`\dFt` (text search objects) ([#806](https://github.com/NikolayS/rpg/pull/806)) - `standard_conforming_strings` GUC tracking — fixes backslash parsing in `E''` strings ([#808](https://github.com/NikolayS/rpg/pull/808)) - Async NOTICE/WARNING buffering for deterministic output ordering ([#807](https://github.com/NikolayS/rpg/pull/807)) - - `rpg:file:line:` error location prefix matching psql's `-f` behaviour ([#803](https://github.com/NikolayS/rpg/pull/803)) + - `rpg:file:line:` error location prefix matching psql's `-f` behavior ([#803](https://github.com/NikolayS/rpg/pull/803)) - Wrapped format trailing-space and padding fixes ([#809](https://github.com/NikolayS/rpg/pull/809)) - 3 previously skipped tests un-skipped: `copydml`, `transactions`, `plpgsql` ([#810](https://github.com/NikolayS/rpg/pull/810)) - **WASM browser build (experimental).** rpg compiles to `wasm32-unknown-unknown` for browser use via WebSocket proxy. SQL queries, most `\` meta-commands, `/version`, `/dba`, and error reporting all work. Line editing with arrow keys, history, and Ctrl-U/K/W supported. See [`docs/WASM.md`](docs/WASM.md). ([#759](https://github.com/NikolayS/rpg/pull/759)) @@ -239,7 +239,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - Connector config unified with daemon integration ([#481](https://github.com/NikolayS/rpg/pull/481)) - Per-feature autonomy granularity replaces single global setting ([#527](https://github.com/NikolayS/rpg/pull/527)) - Refactored to explicit Tokio runtime construction ([#541](https://github.com/NikolayS/rpg/pull/541)) -- Removed module-level `dead_code` suppressions in favour of targeted attributes ([#535](https://github.com/NikolayS/rpg/pull/535)) +- Removed module-level `dead_code` suppressions in favor of targeted attributes ([#535](https://github.com/NikolayS/rpg/pull/535)) ### Fixed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df6a6a11..1b4e77d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -148,7 +148,7 @@ Unit tests live next to the code they test (in `#[cfg(test)]` modules). just test-integration ``` -Integration tests require a running Postgres instance. Docker is used to spin up ephemeral containers. Tests in the `tests/` directory with the `integration` feature gate. +Integration tests require a running Postgres instance. Docker is used to spin up ephemeral containers. The tests live in the `tests/` directory behind the `integration` feature gate. ## Cross-compilation diff --git a/README.md b/README.md index b2490efc..be01e454 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) [![Rust](https://img.shields.io/badge/rust-1.88%2B-orange.svg)](https://www.rust-lang.org/) -A psql-compatible terminal written in Rust with built-in DBA diagnostics and AI assistant. +rpg is a psql-compatible Postgres terminal written in Rust, with built-in DBA diagnostics and an AI assistant. Single binary, no dependencies, cross-platform. ## Features @@ -73,7 +73,7 @@ Anything that works in psql works here unchanged. Everything rpg adds uses `/`. ## AI assistant -Integrates with OpenAI, Anthropic, and Ollama: +rpg integrates with OpenAI, Anthropic, and Ollama: ```sql -- Ask questions about your database @@ -102,7 +102,7 @@ select * from orders where status = 'pending'; ### /text2sql — natural language to SQL -By default, the generated SQL is shown in a preview box and you confirm before it runs: +By default, rpg shows the generated SQL in a preview box and asks for confirmation before running it: ``` postgres=# /text2sql @@ -392,9 +392,9 @@ rpg --ssh-tunnel user@bastion.example.com -h 10.0.0.5 -d mydb Supports PostgreSQL 14–18. -rpg is tested against PostgreSQL's own regression test suite (unmodified `.sql` files from the postgres source tree) in CI on every push. Both psql and rpg execute the same queries against the same server; outputs are normalized and diff'd — pass only if identical. +rpg is tested against PostgreSQL's own regression test suite (unmodified `.sql` files from the postgres source tree) in CI on every push. Both psql and rpg execute the same queries against the same server; outputs are normalized and diffed — a test passes only if they are identical. -**222 of 232 PostgreSQL regression tests pass** (0 failures, 10 skipped) against a PostgreSQL 18 server. The skips are CI infrastructure limits, C extensions, or known parsing gaps — not core compatibility issues. +**222 of 232 PostgreSQL regression tests pass** (0 failures, 10 skipped) against a PostgreSQL 18 server. The skips are due to CI infrastructure limits, C extensions, or known parsing gaps — not core compatibility issues. → Full compatibility report: [`docs/psql-compat.md`](docs/psql-compat.md) diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md index d740b07c..87e5b54a 100644 --- a/docs/COMMANDS.md +++ b/docs/COMMANDS.md @@ -15,7 +15,7 @@ namespace is unambiguous: if it starts with `/`, it is an rpg extension. ## psql-compatible `\` commands (keep as-is) -These match psql behaviour and must not be changed: +These match psql behavior and must not be changed: `\a`, `\c`, `\C`, `\cd`, `\copy`, `\d`, `\D`, `\db`, `\dc`, `\df`, `\di`, `\dl`, `\dn`, `\do`, `\dp`, `\ds`, `\dt`, `\dT`, `\du`, `\dv`, `\e`, `\echo`, @@ -79,7 +79,7 @@ These match psql behaviour and must not be changed: | `/session resume ` | reconnect using a saved session | | `/refresh` | reload schema cache for tab completion | | `/log-file ` | start logging queries (no arg = stop) | -| `/explain-share ` | upload last EXPLAIN plan to external visualiser | +| `/explain-share ` | upload last EXPLAIN plan to external visualizer | | `/commands` | list custom Lua meta-commands | | `/version` | show rpg version and build information | | `/f2` | toggle schema-aware tab completion | diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md index daa4bf67..f1bf73d3 100644 --- a/docs/GLOSSARY.md +++ b/docs/GLOSSARY.md @@ -17,10 +17,10 @@ point. - **Module** — anything with an interface and an implementation: a function, a struct + its `impl`, a file, a `mod`, a crate. - **Interface** — everything a caller must know to use the module: signatures, invariants, error modes, ordering, configuration. Not just types. - **Implementation** — the code inside the module. -- **Depth** — leverage at the interface: lots of behaviour behind a small interface. +- **Depth** — leverage at the interface: lots of behavior behind a small interface. - **Deep module** — small interface, large implementation. High leverage. - **Shallow module** — interface nearly as complex as the implementation. Low leverage; usually a pass-through. -- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. +- **Seam** — where an interface lives; a place behavior can be altered without editing in place. - **Adapter** — a concrete type satisfying an interface at a seam. - **Leverage** — what callers gain from depth: terse, intent-shaped call sites. - **Locality** — what maintainers gain from depth: change, bugs, knowledge concentrated in one place. @@ -64,7 +64,7 @@ design discussion and PR descriptions. - **Command Registry** — the table that maps a parsed `Command` to its handler. Replaces the two `match` statements in today's dispatchers. - **`CommandCtx`** — proposed bundle of execution dependencies (`client`, `params`, `settings`, `tx`) passed to every handler. Single place to extend handler capabilities. - **`MetaResult`** — the existing handler return enum (`Continue` / `Quit` / `Reconnected` / `ClearBuffer` / `PrintBuffer` / …). Stays. -- **Category** — grouping of commands for behaviours that vary across them: AI, DBA, session, output, conditional, …. The token-budget gate becomes a property of the category, not a hand-curated list. +- **Category** — grouping of commands for behaviors that vary across them: AI, DBA, session, output, conditional, …. The token-budget gate becomes a property of the category, not a hand-curated list. ## REPL state diff --git a/docs/WASM.md b/docs/WASM.md index a0c5684c..07f6ab7b 100644 --- a/docs/WASM.md +++ b/docs/WASM.md @@ -1,12 +1,12 @@ -# rpg WASM — Browser Build (Experimental) +# rpg WASM: browser build (experimental) > **Status: Experimental.** The WASM build is functional for interactive SQL > and most meta-commands, but some features are unavailable due to platform > constraints (no filesystem, no shell, no ratatui). See -> [Known Limitations](#known-limitations) below. +> [Known limitations](#known-limitations) below. Run rpg in the browser as a WebAssembly module. SQL queries, meta-commands, and rpg diagnostics work against a real Postgres server via a WebSocket proxy. @@ -37,7 +37,7 @@ protocol negotiation. Because the underlying `WsIo` type is `!Send`, the connection driver runs on `wasm_bindgen_futures::spawn_local` instead of `tokio::spawn`. -## Quick Start +## Quick start ### 1. Install prerequisites @@ -86,7 +86,7 @@ cd wasm && python3 -m http.server 8080 Navigate to `http://localhost:8080`. Enter connection details in the toolbar and click **Connect**. -## What Works +## What works - **SQL queries** with psql-style tabular formatting (`\x` expanded mode supported) - **Meta-commands:** `\d`, `\dt`, `\dn`, `\du`, `\di`, `\dv`, `\df`, `\l`, `\conninfo`, `\timing`, `\x`, `\set`, `\echo`, `\?` @@ -95,10 +95,10 @@ and click **Connect**. - **Line editing:** arrow keys, command history (Up/Down), Ctrl-U/K/W/L, Home/End, Delete, Backspace - **Connection** to any Postgres 14-18 server via the WebSocket proxy -## Known Limitations +## Known limitations Commands that require native OS facilities show a friendly error message -instead of panicking — e.g. `\i: file include is not available on +instead of panicking, for example `\i: file include is not available on wasm32-unknown-unknown (no filesystem)`. | Feature | Reason | @@ -121,7 +121,7 @@ wasm32-unknown-unknown (no filesystem)`. | AI commands (`/ask`, `/fix`, `/explain`, `/optimize`) | Require `reqwest` streaming, which is limited on WASM | | Multi-statement command tags | When multiple statements are sent in one line, the command tag from the first is reused for subsequent ones (cosmetic, queries execute correctly) | -## Output Routing +## Output routing Standard `println!` / `eprintln!` write to file descriptors 1 and 2, which are sinks on `wasm32-unknown-unknown` (there is no OS). rpg uses custom macros to @@ -169,11 +169,11 @@ invisible to native `cargo check` / `cargo test`. `wasm/build-rpg-wasm.sh` automates the full build: 1. Installs `wasm-pack` if missing -2. Ensures `wasm32-unknown-unknown` target is added +2. Ensures the `wasm32-unknown-unknown` target is added 3. Runs `wasm-pack build --target web --release --features wasm` 4. Optionally runs `wasm-opt -Oz` (from binaryen) for size optimization -## WebSocket Proxy +## WebSocket proxy `wasm/ws-proxy.js` is a Node.js process that bridges WebSocket connections from the browser to a Postgres TCP socket. One TCP connection is created per diff --git a/docs/psql-compat.md b/docs/psql-compat.md index 6a233cd3..d88c80a4 100644 --- a/docs/psql-compat.md +++ b/docs/psql-compat.md @@ -6,7 +6,7 @@ **222 of 232 PostgreSQL regression tests pass** (0 failures, 10 skipped) against a PostgreSQL 18 server; the skips are CI infrastructure limits or C extensions — not core compatibility issues. -For everyday use — queries, `\d` commands, scripts, `\copy`, REPL — rpg is a safe drop-in. +For everyday use — queries, `\d` commands, scripts, `\copy`, the REPL — rpg is a safe drop-in. --- @@ -88,7 +88,7 @@ CI server: `postgres:18`. The `SKIP_ALWAYS` list in `tests/compat/test-psql-regr ### Describe commands (`\d` family) -All describe commands produce output byte-identical to psql. +All describe commands produce output byte-identical to psql's. | Command | Status | Tested | Description | |---------|--------|--------|-------------| @@ -256,7 +256,7 @@ This is the other side of the compatibility story — rpg is a superset in these ### Command namespace -rpg uses `/` for all its own commands and `\` exclusively for psql-compatible metacommands. This makes it unambiguous which commands are standard and which are extensions. `\dba`, `\sql`, `\plan` etc. are deprecated aliases that still work but print a migration hint. +rpg uses `/` for all its own commands and `\` exclusively for psql-compatible metacommands. This makes it unambiguous which commands are standard and which are extensions. `\dba`, `\sql`, `\plan`, etc. are deprecated aliases that still work but print a migration hint. --- diff --git a/src/main.rs b/src/main.rs index 71064a0a..89aaa436 100644 --- a/src/main.rs +++ b/src/main.rs @@ -362,7 +362,7 @@ struct Cli { #[arg(long, value_name = "LEVEL")] log_level: Option, - /// Generate `rpg_ops` wrapper SQL and exit. Specify PG version (e.g. 14, 16). + /// Generate `rpg_ops` wrapper SQL and exit. Specify PG version (e.g., 14, 16). #[arg(long, value_name = "PG_VERSION", default_missing_value = "16", num_args = 0..=1)] generate_wrappers: Option, diff --git a/wasm/index.html b/wasm/index.html index db3fddf2..a7b290ba 100644 --- a/wasm/index.html +++ b/wasm/index.html @@ -266,7 +266,7 @@ // Load the WASM module. term.writeln('Loading rpg.wasm...'); await init(); - term.writeln('rpg.wasm loaded. Press \x1b[36mConnect\x1b[0m to start.'); + term.writeln('rpg.wasm loaded. Click \x1b[36mConnect\x1b[0m to start.'); connectBtn.addEventListener('click', async () => { connectBtn.disabled = true; From cb93a68c4b7af9d0a8df4ec7f8ca359d33caa413 Mon Sep 17 00:00:00 2001 From: NikolayS Date: Sun, 12 Jul 2026 07:14:41 +0000 Subject: [PATCH 2/3] docs: add meta description to WASM landing page Adds a missing meta description to wasm/index.html for search snippets and LLM summaries, and fixes one remaining British spelling in docs/GLOSSARY.md for in-file consistency. Relates to #838 --- wasm/index.html | 1 + 1 file changed, 1 insertion(+) diff --git a/wasm/index.html b/wasm/index.html index a7b290ba..87d1c6f8 100644 --- a/wasm/index.html +++ b/wasm/index.html @@ -3,6 +3,7 @@ rpg — browser terminal +