sqlrite 0.1.23__tar.gz → 0.1.25__tar.gz

{sqlrite-0.1.23 → sqlrite-0.1.25}/.github/workflows/release.yml

@@ -127,6 +127,7 @@ jobs:
             "sqlrite-v$V"
             "sqlrite-ffi-v$V"
             "sqlrite-ask-v$V"
+            "sqlrite-mcp-v$V"
             "sqlrite-desktop-v$V"
             "sqlrite-py-v$V"
             "sqlrite-node-v$V"
@@ -267,6 +268,164 @@ jobs:
             See the umbrella release [v${{ needs.detect.outputs.version }}](../../releases/tag/v${{ needs.detect.outputs.version }}) for the full changelog.
           generate_release_notes: true
 
+  # ---------------------------------------------------------------------------
+  # Step 3a'': publish the `sqlrite-mcp` crate (Phase 7h) — Model
+  # Context Protocol server adapter that exposes SQLRite as a
+  # stdio-spawned tool surface for LLM agents (Claude Code, Cursor,
+  # mcp-inspector, etc.). Same shape as `publish-ask` above; gated
+  # `needs: publish-crate, publish-ask` because sqlrite-mcp depends
+  # on both (the engine via `default-features = false` + the engine's
+  # `ask` feature for the natural-language → SQL `ask` tool).
+  #
+  # Crate name on crates.io: `sqlrite-mcp`. Binary name produced by
+  # `cargo install`: `sqlrite-mcp` (one [[bin]] target). Per-platform
+  # prebuilt binary tarballs are produced by `build-mcp-binaries`
+  # below — `cargo install` is the from-source path.
+  publish-mcp:
+    name: Publish sqlrite-mcp crate to crates.io
+    needs: [detect, tag-all, publish-crate, publish-ask]
+    if: needs.detect.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: publish-mcp
+
+      - name: cargo publish
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CRATES_IO_TOKEN }}
+        # `--no-verify` mirrors `publish-crate` / `publish-ask` —
+        # Release-PR CI already validated this commit.
+        #
+        # `needs: [..., publish-crate, publish-ask]` is load-bearing:
+        # sqlrite-mcp's path-dep on sqlrite-engine + (transitive)
+        # sqlrite-ask only resolves on crates.io once both have been
+        # published at the matching version. crates.io rejects
+        # path-dep publishes whose path-dep version isn't reachable.
+        run: cargo publish -p sqlrite-mcp --no-verify
+
+      - name: GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: sqlrite-mcp-v${{ needs.detect.outputs.version }}
+          name: sqlrite-mcp v${{ needs.detect.outputs.version }}
+          body: |
+            Published to crates.io: https://crates.io/crates/sqlrite-mcp/${{ needs.detect.outputs.version }}
+
+            Model Context Protocol (MCP) server for SQLRite. Wraps a SQLRite database as a stdio-spawned subprocess that LLM agents (Claude Code, Cursor, `mcp-inspector`) can drive without custom integration code.
+
+            ```sh
+            cargo install sqlrite-mcp
+            ```
+
+            ```json
+            // ~/.claude.json
+            {
+              "mcpServers": {
+                "sqlrite": {
+                  "command": "sqlrite-mcp",
+                  "args": ["/path/to/your.sqlrite"],
+                  "env": { "SQLRITE_LLM_API_KEY": "sk-ant-…" }
+                }
+              }
+            }
+            ```
+
+            Seven tools: `list_tables`, `describe_table`, `query`, `execute`, `schema_dump`, `vector_search`, `ask`. Pass `--read-only` to hide `execute`. Pre-built binary tarballs (no Rust toolchain required) are attached to this release as well — see `sqlrite-mcp-v${{ needs.detect.outputs.version }}-{platform}.tar.gz`.
+
+            Full docs: https://github.com/joaoh82/rust_sqlite/blob/main/docs/mcp.md
+
+            See the umbrella release [v${{ needs.detect.outputs.version }}](../../releases/tag/v${{ needs.detect.outputs.version }}) for the full changelog.
+          generate_release_notes: true
+
+  # ---------------------------------------------------------------------------
+  # Step 3a''': build the `sqlrite-mcp` binary for each supported
+  # platform and upload the per-platform tarballs to the
+  # `sqlrite-mcp-v<V>` GitHub Release. So users who don't want to
+  # `cargo install` (no Rust toolchain) can grab a tarball and drop
+  # the binary on their PATH.
+  #
+  # Matrix mirrors `publish-ffi` — same four platforms, same
+  # "aarch64 on macOS, x86_64 elsewhere" choice. The binary is much
+  # smaller than the FFI artifact (one [[bin]], no .so/.a files) so
+  # we just package the executable + the README.
+  build-mcp-binaries:
+    name: Build sqlrite-mcp binary (${{ matrix.platform }})
+    needs: [detect, tag-all, publish-mcp]
+    if: needs.detect.outputs.should_release == 'true'
+    runs-on: ${{ matrix.os }}
+    environment: release
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            platform: linux-x86_64
+            bin: sqlrite-mcp
+          - os: ubuntu-24.04-arm
+            platform: linux-aarch64
+            bin: sqlrite-mcp
+          - os: macos-latest
+            platform: macos-aarch64
+            bin: sqlrite-mcp
+          - os: windows-latest
+            platform: windows-x86_64
+            bin: sqlrite-mcp.exe
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: build-mcp-${{ matrix.platform }}
+
+      - name: Build sqlrite-mcp
+        # Default features include `ask`, so the binary ships with the
+        # natural-language → SQL tool wired in. Users who want a leaner
+        # build (no LLM machinery, six pure-SQL tools) can
+        # `cargo install sqlrite-mcp --no-default-features` from source.
+        run: cargo build --release -p sqlrite-mcp
+
+      - name: Package tarball
+        shell: bash
+        run: |
+          V="${{ needs.detect.outputs.version }}"
+          STAGE="sqlrite-mcp-v$V-${{ matrix.platform }}"
+          mkdir -p "$STAGE"
+          cp "target/release/${{ matrix.bin }}" "$STAGE/"
+          cat > "$STAGE/README" <<EOF
+          sqlrite-mcp v$V — ${{ matrix.platform }}
+
+          Model Context Protocol server for SQLRite.
+
+          Drop the binary on your PATH and wire it into your MCP client
+          (Claude Code, Cursor, mcp-inspector, etc.):
+
+            sqlrite-mcp /path/to/your.sqlrite              # read-write
+            sqlrite-mcp /path/to/your.sqlrite --read-only  # shared-lock RO
+            sqlrite-mcp --in-memory                        # ephemeral
+
+          Full docs: https://github.com/joaoh82/rust_sqlite/blob/main/docs/mcp.md
+          EOF
+          tar czf "$STAGE.tar.gz" "$STAGE"
+          echo "ASSET=$STAGE.tar.gz" >> "$GITHUB_ENV"
+
+      - name: Upload to GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: sqlrite-mcp-v${{ needs.detect.outputs.version }}
+          name: sqlrite-mcp v${{ needs.detect.outputs.version }}
+          files: ${{ env.ASSET }}
+          # The release body was already populated by `publish-mcp`
+          # above; this job only attaches assets. Don't overwrite it.
+          append_body: false
+
   # ---------------------------------------------------------------------------
   # Step 3b: build `libsqlrite_c` for each supported platform and
   # upload the tarballs to the `sqlrite-ffi-v<V>` GitHub Release.
@@ -1291,7 +1450,7 @@ jobs:
   # config if we add one later.
   finalize:
     name: Finalize umbrella release
-    needs: [detect, publish-crate, publish-ask, publish-ffi, publish-desktop, publish-python, publish-nodejs, publish-wasm, publish-go]
+    needs: [detect, publish-crate, publish-ask, publish-mcp, build-mcp-binaries, publish-ffi, publish-desktop, publish-python, publish-nodejs, publish-wasm, publish-go]
     if: needs.detect.outputs.should_release == 'true'
     runs-on: ubuntu-latest
     steps:
@@ -1310,6 +1469,7 @@ jobs:
             Per-product releases in this wave:
 
             - 🦀 [Rust engine](../../releases/tag/sqlrite-v${{ needs.detect.outputs.version }}) → [crates.io](https://crates.io/crates/sqlrite-engine/${{ needs.detect.outputs.version }})
+            - 🤖 [MCP server](../../releases/tag/sqlrite-mcp-v${{ needs.detect.outputs.version }}) → [crates.io](https://crates.io/crates/sqlrite-mcp/${{ needs.detect.outputs.version }}) — `cargo install sqlrite-mcp` or grab a prebuilt binary tarball; wires SQLRite into Claude Code / Cursor / any MCP client over stdio
             - 🔧 [C FFI](../../releases/tag/sqlrite-ffi-v${{ needs.detect.outputs.version }}) — prebuilt `libsqlrite_c` for Linux x86_64/aarch64, macOS aarch64, Windows x86_64
             - 🖥️ [Desktop](../../releases/tag/sqlrite-desktop-v${{ needs.detect.outputs.version }}) — unsigned installers for Linux (AppImage + deb), macOS (dmg aarch64), Windows (msi)
             - 🐍 [Python](../../releases/tag/sqlrite-py-v${{ needs.detect.outputs.version }}) → [PyPI](https://pypi.org/project/sqlrite/${{ needs.detect.outputs.version }}/) — abi3-py38 wheels for Linux x86_64/aarch64, macOS aarch64, Windows x86_64 + sdist

{sqlrite-0.1.23 → sqlrite-0.1.25}/Cargo.lock

@@ -415,6 +415,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1ddb117e43bbf7dacf0a4190fef4d345b9bad68dfc649cb349e7d17d28428e51"
 dependencies = [
  "clap_builder",
+ "clap_derive",
 ]
 
 [[package]]
@@ -429,6 +430,18 @@ dependencies = [
  "strsim",
 ]
 
+[[package]]
+name = "clap_derive"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9"
+dependencies = [
+ "heck 0.5.0",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
 [[package]]
 name = "clap_lex"
 version = "1.1.0"
@@ -3804,7 +3817,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ask"
-version = "0.1.23"
+version = "0.1.25"
 dependencies = [
  "serde",
  "serde_json",
@@ -3815,7 +3828,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-desktop"
-version = "0.1.23"
+version = "0.1.25"
 dependencies = [
  "serde",
  "serde_json",
@@ -3827,7 +3840,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-engine"
-version = "0.1.23"
+version = "0.1.25"
 dependencies = [
  "clap",
  "env_logger",
@@ -3844,7 +3857,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ffi"
-version = "0.1.23"
+version = "0.1.25"
 dependencies = [
  "cbindgen",
  "serde",
@@ -3852,9 +3865,20 @@ dependencies = [
  "sqlrite-engine",
 ]
 
+[[package]]
+name = "sqlrite-mcp"
+version = "0.1.25"
+dependencies = [
+ "clap",
+ "libc",
+ "serde",
+ "serde_json",
+ "sqlrite-engine",
+]
+
 [[package]]
 name = "sqlrite-nodejs"
-version = "0.1.23"
+version = "0.1.25"
 dependencies = [
  "napi",
  "napi-build",
@@ -3864,7 +3888,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-python"
-version = "0.1.23"
+version = "0.1.25"
 dependencies = [
  "pyo3",
  "sqlrite-engine",

{sqlrite-0.1.23 → sqlrite-0.1.25}/Cargo.toml

@@ -27,7 +27,7 @@ resolver = "3"
 # `package =` key so the import name stays `sqlrite` internally:
 #     sqlrite = { package = "sqlrite-engine", path = "…" }
 name = "sqlrite-engine"
-version = "0.1.23"
+version = "0.1.25"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"

{sqlrite-0.1.23 → sqlrite-0.1.25}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlrite
-Version: 0.1.23
+Version: 0.1.25
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -243,6 +243,10 @@ python -m pytest tests/
 - maturin as the build backend, emitting standard `.whl` files that pip can install directly.
 - Phase 6f's CI publishes abi3-py38 wheels to PyPI for manylinux x86_64/aarch64, macOS aarch64, and Windows x86_64 (plus an sdist) on every release. OIDC trusted publishing — no long-lived PyPI token in the repo.
 
+## Sibling products
+
+This SDK is for when *your code* drives the database. If you want an *LLM agent* to drive a SQLRite database directly, install the [`sqlrite-mcp`](../../docs/mcp.md) Model Context Protocol server (`cargo install sqlrite-mcp`) and wire it into Claude Code / Cursor / `mcp-inspector` / any MCP-aware client. Same engine underneath.
+
 ## Status
 
 Phase 5c MVP: ✅ — basic CRUD, transactions, context managers, read-only mode, iteration. Parameter binding, CursorRow namedtuples, and type converters (datetime, Decimal) are natural follow-ups.

{sqlrite-0.1.23 → sqlrite-0.1.25}/README.md

@@ -80,6 +80,32 @@ A cross-platform Tauri 2.0 + Svelte 5 desktop GUI ships alongside the REPL (see
 
 **From source** — `cd desktop && npm install && npm run tauri dev`. The header's New… / Open… / Save As… buttons cover the file lifecycle; the query editor has a live line-number gutter, `⌘/` (Ctrl+/) SQL comment toggle, and selection-aware Run (highlight a statement to run just that one).
 
+### MCP server (drive SQLRite from an LLM agent)
+
+`sqlrite-mcp` exposes a SQLRite database as a [Model Context Protocol](https://modelcontextprotocol.io/) stdio server. Spawn it from any MCP client (Claude Code, Cursor, `mcp-inspector`, …) and the agent gets seven tools — `list_tables`, `describe_table`, `query`, `execute`, `schema_dump`, `vector_search`, plus `ask` for natural-language → SQL — without any custom integration code.
+
+```sh
+cargo install sqlrite-mcp
+```
+
+Or grab a per-platform pre-built binary from the [latest release](https://github.com/joaoh82/rust_sqlite/releases/latest) (Linux x86_64/aarch64, macOS aarch64, Windows x86_64).
+
+Wire it into Claude Code (`~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "sqlrite": {
+      "command": "sqlrite-mcp",
+      "args": ["/absolute/path/to/your.sqlrite"],
+      "env": { "SQLRITE_LLM_API_KEY": "sk-ant-…" }
+    }
+  }
+}
+```
+
+`--read-only` opens the DB with a shared lock and hides the `execute` tool. Full docs + the other six tools' references in [`docs/mcp.md`](docs/mcp.md).
+
 ### Developer guide
 
 In-depth documentation lives under [`docs/`](docs/). Start at [`docs/_index.md`](docs/_index.md) — it navigates to:
@@ -100,10 +126,10 @@ Build and launch the REPL:
 cargo run
 ```
 
-You'll drop into a REPL connected to a transient in-memory database. On-disk persistence (`.open`, `.save`) is coming in Phase 2.
+You'll drop into a REPL connected to a transient in-memory database. Use `.open <path>` to switch to a file-backed database (auto-saves on every statement; see Meta commands).
 
 ```
-SQLRite - 0.1.0
+SQLRite
 Enter .exit to quit.
 Enter .help for usage hints.
 Connected to a transient in-memory database.
@@ -183,7 +209,9 @@ println!("Why: {}",          resp.explanation);
 
 **Defaults:** `claude-sonnet-4-6`, `max_tokens: 1024`, schema dump cached for 5 minutes via Anthropic prompt caching (configurable to 1h or off via `AskConfig::cache_ttl`). Bring your own API key — set `SQLRITE_LLM_API_KEY` or pass it on `AskConfig`.
 
-In the REPL: `.ask <question>`. From an open `Connection` (this section). Per-product wrappers — desktop "Ask" button, `conn.ask()` in the Python / Node / Go SDKs, MCP `ask` tool, WASM with a JS-callback shape so the API key never enters the browser — ship in **7g.3-7g.8** as follow-up sub-phases. See [`docs/phase-7-plan.md`](docs/phase-7-plan.md) §7g for the full surface plan.
+In the REPL: `.ask <question>`. From an open `Connection` (this section). Per-product wrappers shipped across **7g.3 – 7g.8**: the desktop "Ask…" composer, `conn.ask()` / `db.ask()` in the Python / Node / Go SDKs, the WASM SDK's split `db.askPrompt()` / `db.askParse()` shape (so the API key never enters the browser), and the MCP `ask` tool exposed by [`sqlrite-mcp`](docs/mcp.md) (so any LLM agent over MCP can call `ask` against your database directly). See [`docs/phase-7-plan.md`](docs/phase-7-plan.md) §7g for the full surface plan.
+
+For the canonical Ask reference covering every surface (REPL, desktop, Rust library, Python / Node / Go / WASM), env vars, defaults, prompt caching, and the security model — read [`docs/ask.md`](docs/ask.md). For copy-paste backend proxy templates the WASM SDK needs (Cloudflare Workers, Vercel Edge, Deno Deploy, Firebase, AWS Lambda, Express), see [`docs/ask-backend-examples.md`](docs/ask-backend-examples.md).
 
 ### Roadmap
 
@@ -228,7 +256,7 @@ The project is staged in phases, each independently shippable. A finished phase
 - [x] **Tauri 2.0 backend**: four commands (`open_database`, `list_tables`, `table_rows`, `execute_sql`) wrap the engine; results are tagged enums shipped to the UI via the JSON IPC bridge.
 - [x] **Svelte 5 frontend**: dark-themed three-pane layout — header with "Open…" file picker, sidebar with table list + schema, query editor with Cmd/Ctrl+Enter to run, result grid with sticky header.
 
-**Phase 4 — Durability and concurrency** *(in progress)*
+**Phase 4 — Durability and concurrency** *(done)*
 - [x] **4a — Exclusive file lock**: `Pager::open` / `::create` takes an OS advisory lock (`fs2::try_lock_exclusive`); a second process on the same file gets a clean "already in use" error. Lock releases automatically when the Pager drops.
 - [x] **4b — Write-Ahead Log (`<db>.sqlrite-wal`) file format + frame codec**: 32-byte WAL header (magic / version / page size / salt / checkpoint seq), 4112-byte frames carrying `(page_num, commit_page_count, salt, checksum, body)`. Rolling-sum checksum. Torn-write recovery: corrupt or partial trailing frames are silently truncated at the boundary. Standalone module; not wired yet.
 - [x] **4c — WAL-aware Pager**: `Pager::open` / `::create` now own both the main file and its `-wal` sidecar. Reads resolve `staged → wal_cache → on_disk` with a page-count bounds check; commits append a WAL frame per dirty page plus a final commit frame carrying the new page 0 (encoded header). The main file stays frozen between checkpoints — reopening replays the WAL and the decoded page-0 frame overrides the (stale) main-file header.
@@ -244,7 +272,7 @@ The project is staged in phases, each independently shippable. A finished phase
 - [x] **5e — Go SDK**: new `sdk/go/` module at `github.com/joaoh82/rust_sqlite/sdk/go`; cgo-wired against `libsqlrite_c` from Phase 5b. Implements the full `database/sql/driver` surface so users get the standard-library experience (`sql.Open("sqlrite", path)`, `db.Query/Exec/Begin`, `rows.Scan(&id, &name)`). 9-test `go test` integration suite. `examples/go/hello.go` runs after `cargo build --release -p sqlrite-ffi`. Module publish landed in Phase 6i — `go get github.com/joaoh82/rust_sqlite/sdk/go@vX.Y.Z` resolves directly via VCS tag.
 - [ ] **5f — Rust crate polish** *(deferred — Phase 6c companion)*: crate metadata, docs.rs config, prep for `cargo publish`. Deferred to land alongside the actual publish workflow.
 - [x] **5g — WASM** build: new `sdk/wasm/` crate via `wasm-bindgen`; engine runs entirely in a browser tab. Feature-gated root crate (`cli` + `file-locks` optional, both default-on) so WASM disables fs2 / rustyline / clap / env_logger cleanly. `Database` class with `exec/query/columns/inTransaction`; rows as plain JS objects in projection order. ~1.8 MB wasm / ~500 KB gzipped. Three `wasm-pack` targets (web/bundler/nodejs). `examples/wasm/` ships a self-contained HTML SQL console.
-- [ ] Code examples for every language under `examples/{rust,python,nodejs,go,wasm}/`
+- [x] Code examples for every language under `examples/{rust,python,nodejs,go,wasm,c}/`
 
 **Phase 6 — Release engineering + CI/CD**
 Lockstep versioning — one dispatch bumps every product to the same `vX.Y.Z`. Two-workflow design: `release-pr.yml` opens a Release PR with the version bumps (human reviews + merges), then `release.yml` fires on merge to tag + publish everything. Trusted-publishing via OIDC for PyPI + npm (no long-lived tokens). Full plan: [`docs/release-plan.md`](docs/release-plan.md).
@@ -263,7 +291,7 @@ Lockstep versioning — one dispatch bumps every product to the same `vX.Y.Z`. T
 - [ ] macOS Apple Developer ID cert → `codesign` + `notarytool` in `tauri-action`
 - [ ] Windows code-signing cert → `signtool` in `tauri-action`
 
-**Phase 7 — AI-era extensions** *(in progress — full plan in [`docs/phase-7-plan.md`](docs/phase-7-plan.md))*
+**Phase 7 — AI-era extensions** *(7a–7h shipped; FTS deferred to Phase 8 — full plan in [`docs/phase-7-plan.md`](docs/phase-7-plan.md))*
 - [x] **7a — `VECTOR(N)` column type** *(v0.1.10)*: dense f32 vectors with bracket-array literal syntax (`[0.1, 0.2, ...]`); file format bumped to v4
 - [x] **7b — Distance functions** *(v0.1.11)*: `vec_distance_l2/cosine/dot` + `ORDER BY <expr> LIMIT k` so KNN queries work end-to-end
 - [x] **7c — Bounded-heap top-k optimization** *(v0.1.12)*
@@ -272,8 +300,11 @@ Lockstep versioning — one dispatch bumps every product to the same `vX.Y.Z`. T
 - [x] **7g.1 — `sqlrite-ask` crate** *(v0.1.18)*: foundational natural-language → SQL via the [Anthropic API](https://docs.anthropic.com/) (Sonnet 4.6 by default), prompt-cached schema dump, sync `ureq` HTTP.
 - [x] **7g.2 — REPL `.ask` + dep-direction flip** *(v0.1.19)*: `.ask <question>` meta-command with `Run? [Y/n]` confirmation. The wiring required dropping the engine dep from `sqlrite-ask` (cargo cycle) — `sqlrite-ask` is now pure over `&str` schemas; the `Connection`/`Database` integration moved to the engine's new `ask` feature. Public surface for callers: `use sqlrite::{Connection, ConnectionAskExt}`.
 - [x] **7g.3 — Desktop "Ask…" button** *(this wave)*: composer panel above the editor textarea; click → type a natural-language question → submit → generated SQL drops into the editor for review before Run. Schema introspection + LLM HTTP call run in the Tauri Rust backend, so the API key never crosses into the webview.
-- [ ] **7g.4-7g.8** — per-product `ask()` adapters: Python/Node/Go/WASM SDKs, MCP `ask` tool
-- [ ] **7h** — MCP server adapter (`sqlrite-mcp` binary)
+- [x] **7g.4 — Python SDK `conn.ask` / `ask_run` / `AskConfig`** *(v0.1.20)*: PyO3 wrappers; three-layer config precedence (per-call > per-connection > env > defaults); `__repr__` omits the API key.
+- [x] **7g.5 — Node.js SDK `db.ask` / `askRun` / `AskConfig`** *(v0.1.21)*: napi-rs wrappers with idiomatic camelCase option-object; same three-layer precedence; mock HTTP test runs in `worker_thread` to avoid event-loop deadlock.
+- [x] **7g.6 — Go SDK `sqlrite.Ask` / `AskRun` / `AskConfig`** *(v0.1.22)*: cgo wrapper plus `AskContext` / `AskRunContext`; new C FFI function takes `AskConfig` as a JSON string for ABI extensibility.
+- [x] **7g.7 — WASM SDK `db.askPrompt` / `db.askParse` (Q9 split shape)** *(v0.1.23)*: browser builds the prompt + parses the response; user's backend holds the API key. Plus `docs/ask.md` (canonical Ask reference) and `docs/ask-backend-examples.md` (Cloudflare Workers / Vercel Edge / Deno Deploy / Firebase / AWS Lambda / Express templates).
+- [x] **7h — MCP server adapter (`sqlrite-mcp` binary)** *(this wave)*: hand-rolled JSON-RPC 2.0 over stdio; seven tools — `list_tables`, `describe_table`, `query`, `execute`, `schema_dump`, `vector_search`, plus `ask` as Phase **7g.8** behind a default-on cargo feature. Read-only mode hides `execute`. Stdout-redirect dance keeps engine prettytable noise off the protocol channel. See [`docs/mcp.md`](docs/mcp.md) for wiring into Claude Code / Cursor / `mcp-inspector`.
 - [ ] *(deferred to Phase 8)* Full-text search with BM25 + hybrid retrieval
 
 **Possible extras** *(no committed phase)*

{sqlrite-0.1.23 → sqlrite-0.1.25}/desktop/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sqlrite-desktop-frontend",
   "private": true,
-  "version": "0.1.23",
+  "version": "0.1.25",
   "type": "module",
   "scripts": {
     "dev": "vite",

{sqlrite-0.1.23 → sqlrite-0.1.25}/docs/_index.md

@@ -18,6 +18,12 @@ A small, hand-written guide to the SQLRite codebase — how it's structured, how
 - [Embedding](embedding.md) — the public `Connection` / `Statement` / `Rows` API (Phase 5a) and where the non-Rust SDKs plug in (Phase 5b – 5g)
 - [`examples/`](../examples/) — runnable Rust quickstart (`cargo run --example quickstart`); language-specific subdirectories fill in as each 5x sub-phase lands
 
+## Phase 7 — AI-era extensions
+
+- [Ask — natural-language → SQL](ask.md) — the canonical reference for the `ask()` feature across every product surface (REPL, desktop, Rust library, Python / Node / Go / WASM SDKs, MCP server); env vars, defaults, prompt caching, security
+- [Ask backend proxy templates](ask-backend-examples.md) — copy-paste backend examples for the WASM SDK's split design: Cloudflare Workers, Vercel Edge, Deno Deploy, Firebase Functions, AWS Lambda, Express, pure Node
+- [MCP server (`sqlrite-mcp`)](mcp.md) — Phase 7h: SQLRite as a Model Context Protocol stdio server. Wiring into Claude Code / Cursor / `mcp-inspector`; the seven tools (`list_tables`, `describe_table`, `query`, `execute`, `schema_dump`, `vector_search`, `ask`); read-only mode; the JSON-RPC wire format
+
 ## Internals
 
 These documents go into the implementation of each subsystem.
@@ -30,28 +36,29 @@ These documents go into the implementation of each subsystem.
 
 ## Project state
 
-As of April 2026, SQLRite has:
+As of May 2026, SQLRite has:
 
 - A working SQL engine (in-memory + on-disk with a real B-Tree per table + secondary indexes, Phases 0 – 3 complete)
 - WAL-backed persistence with crash-safe checkpointing, shared/exclusive lock modes, and real `BEGIN` / `COMMIT` / `ROLLBACK` transactions (Phase 4 complete)
 - A stable public Rust embedding API plus C FFI shim and SDKs for Python, Node.js, Go, and WASM (Phase 5 complete except the optional 5f crate-polish task)
 - A Tauri 2.0 + Svelte desktop app (Phase 2.5 complete)
-- A fully-automated release pipeline that ships every product to its registry on every release with one human action — Rust crate to crates.io (`sqlrite-engine`), Python wheels to PyPI (`sqlrite`), Node.js + WASM to npm (`@joaoh82/sqlrite` + `@joaoh82/sqlrite-wasm`), Go module via `sdk/go/v*` git tag, plus C FFI tarballs and unsigned desktop installers as GitHub Release assets (Phase 6 complete)
+- AI-era extensions across the product surface (Phase 7 complete except FTS): VECTOR columns + HNSW indexes (7a-7d), JSON columns (7e), the `ask()` natural-language → SQL family across the REPL / desktop / Rust / Python / Node / Go / WASM (7g.1-7g.7), and the [`sqlrite-mcp`](mcp.md) Model Context Protocol server with seven tools including `ask` (7h + 7g.8)
+- A fully-automated release pipeline that ships every product to its registry on every release with one human action — Rust engine + `sqlrite-ask` + `sqlrite-mcp` to crates.io, Python wheels to PyPI (`sqlrite`), Node.js + WASM to npm (`@joaoh82/sqlrite` + `@joaoh82/sqlrite-wasm`), Go module via `sdk/go/v*` git tag, plus C FFI tarballs, MCP binary tarballs, and unsigned desktop installers as GitHub Release assets (Phase 6 complete)
 
-The active frontier is **Phase 7 — AI-era extensions**.
+The active frontier is **Phase 8 — Full-text search + hybrid retrieval** (the deferred 7f scope).
 
 See the [Roadmap](roadmap.md) for the full phase plan.
 
 ## Release engineering
 
-- [Release plan](release-plan.md) — Phase 6 design doc: lockstep versioning, PR-based release flow, OIDC trusted publishing, the ten-file version-bump surface
+- [Release plan](release-plan.md) — Phase 6 design doc: lockstep versioning, PR-based release flow, OIDC trusted publishing, the version-bump surface
 - [Release secrets runbook](release-secrets.md) — one-time web-UI setup for crates.io, PyPI, npm, GitHub `release` environment, and `main` branch protection
 - [`scripts/`](../scripts/) — runnable tooling used by release workflows + reproducible locally (start with `scripts/bump-version.sh`)
 
 ## Future work
 
-- [Phase 7 plan](phase-7-plan.md) — AI-era extensions (vector column type + HNSW, JSON, NL→SQL `ask()` API across REPL/library/SDKs/desktop/MCP, MCP server). **Approved 2026-04-26**, implementation starts at sub-phase 7a.
-- Phase 8 — Full-text search (FTS5-style BM25) + hybrid retrieval, deferred from Phase 7 per the plan-doc's Q1.
+- [Phase 7 plan](phase-7-plan.md) — AI-era extensions (vector column type + HNSW, JSON, NL→SQL `ask()` API across REPL/library/SDKs/desktop/MCP, MCP server). **Implementation complete except 7f, which deferred to Phase 8.**
+- Phase 8 — Full-text search (FTS5-style BM25) + hybrid retrieval, deferred from Phase 7 per the plan-doc's Q1. **Active frontier as of May 2026.**
 
 ## Conventions
 

{sqlrite-0.1.23 → sqlrite-0.1.25}/docs/architecture.md

@@ -66,20 +66,43 @@ A bird's-eye view of the system, with pointers into the code.
                      └───────────────────────────┘
 ```
 
-## Module map
+## Workspace layout
+
+The repo is a Cargo workspace. The engine is the root crate; everything else lives in a sibling directory.
+
+| Crate / directory | Role |
+|---|---|
+| Root (`./`) — `sqlrite-engine` on crates.io, `use sqlrite::…` in code | The engine. Library + the REPL `[[bin]]`. Library surface: `Connection`, `Statement`, `Rows`, `Value`, `Database`. |
+| [`sqlrite-ffi/`](../sqlrite-ffi/) | C FFI shim. Builds `libsqlrite_c.{so,dylib,dll}` + cbindgen-generated `sqlrite.h`. Used by the Go SDK + by anyone wanting to dlopen SQLRite from another language. Phase 5b. |
+| [`sqlrite-ask/`](../sqlrite-ask/) | Pure-Rust LLM transport adapter (Anthropic-first; OpenAI / Ollama follow-ups pending). Takes a `&str` schema dump + `&str` question, returns generated SQL. No engine dep — the engine integration lives in `sqlrite-engine`'s `ask` feature. Phase 7g.1 + the 7g.2 dep-direction flip. |
+| [`sqlrite-mcp/`](../sqlrite-mcp/) | Model Context Protocol server binary. Hand-rolled JSON-RPC 2.0 over stdio. Seven tools (`list_tables`, `describe_table`, `query`, `execute`, `schema_dump`, `vector_search`, `ask`). Phase 7h + 7g.8. See [`mcp.md`](mcp.md). |
+| [`sdk/python/`](../sdk/python/) | PyO3 bindings — `sqlrite` on PyPI. Phase 5c. |
+| [`sdk/nodejs/`](../sdk/nodejs/) | napi-rs bindings — `@joaoh82/sqlrite` on npm. Phase 5d. |
+| [`sdk/go/`](../sdk/go/) | cgo wrapper over `sqlrite-ffi`. `database/sql` driver. Phase 5e. |
+| [`sdk/wasm/`](../sdk/wasm/) | wasm-bindgen build — `@joaoh82/sqlrite-wasm` on npm. Phase 5g. *(Not a workspace member — wasm32 target only.)* |
+| [`desktop/src-tauri/`](../desktop/src-tauri/) | Tauri 2.0 + Svelte 5 desktop app. Embeds the engine directly. Phase 2.5. |
+
+The engine never depends on the SDK crates; the SDK crates each depend on the engine via path-dep. `sqlrite-mcp` depends on the engine (default-features = false) plus its own optional `ask` feature that re-enables the engine's `ask` feature, which pulls `sqlrite-ask` transitively. The whole graph is acyclic — see the 7g.2 dep-direction flip retrospective in [roadmap.md](roadmap.md) for the work that made it so.
+
+## Module map (engine)
 
 | Module | What it owns |
 |---|---|
 | [`src/main.rs`](../src/main.rs) | Binary entry: init env_logger, build rustyline editor, run the REPL loop, route input to either the meta or SQL dispatcher |
+| [`src/lib.rs`](../src/lib.rs) | Library entry: re-exports `Connection`, `Statement`, `Rows`, `Value`, `Database`, `process_command`, the `ask` module (when feature on), etc. — the stable public surface every SDK binds against |
+| [`src/connection.rs`](../src/connection.rs) | `Connection` / `Statement` / `Rows` / `Row` / `OwnedRow` / `FromValue` — the Phase 5a public API |
+| [`src/ask/`](../src/ask/) | Engine integration with `sqlrite-ask`: `ConnectionAskExt`, `ask_with_database`, the `schema::dump_schema_for_database` helper. The `schema` submodule is always available; the rest is gated behind the `ask` feature. Phase 7g.2. |
 | [`src/repl/`](../src/repl/) | `REPLHelper` (implements rustyline's `Helper` trait: completer, hinter, highlighter, validator). Also `get_config` and `get_command_type` |
-| [`src/meta_command/`](../src/meta_command/) | `MetaCommand` enum, parsing (`.open FOO.db` → `Open(PathBuf)`), and dispatch to persistence helpers |
+| [`src/meta_command/`](../src/meta_command/) | `MetaCommand` enum, parsing (`.open FOO.db` → `Open(PathBuf)`, `.ask <Q>` → `Ask(String)`), and dispatch to persistence + ask helpers |
 | [`src/error.rs`](../src/error.rs) | `SQLRiteError` (thiserror-derived), `Result<T>` alias, hand-rolled `PartialEq` that handles `io::Error` |
 | [`src/sql/mod.rs`](../src/sql/mod.rs) | `SQLCommand` classifier, `process_command` — the top-level entry that parses a SQL string and routes to the right executor. Also triggers auto-save. |
 | [`src/sql/parser/`](../src/sql/parser/) | Takes a `sqlparser::ast::Statement` and produces internal query structs (`CreateQuery`, `InsertQuery`, `SelectQuery`) with only the fields we actually use |
-| [`src/sql/executor.rs`](../src/sql/executor.rs) | `execute_select`, `execute_delete`, `execute_update`, plus the shared expression evaluator `eval_expr` / `eval_predicate` |
-| [`src/sql/db/database.rs`](../src/sql/db/database.rs) | `Database`: table map + optional `source_path` + optional long-lived `Pager` |
-| [`src/sql/db/table.rs`](../src/sql/db/table.rs) | `Table`, `Column`, `Row`, `Index` (in-memory storage); helpers for row iteration (`rowids`, `get_value`, `set_value`, `delete_row`, `insert_row`) |
-| [`src/sql/pager/`](../src/sql/pager/) | On-disk file format and I/O — see [file-format.md](file-format.md) and [pager.md](pager.md) for details |
+| [`src/sql/executor.rs`](../src/sql/executor.rs) | `execute_select`, `execute_delete`, `execute_update`, plus the shared expression evaluator `eval_expr` / `eval_predicate`. Also the bounded-heap top-k optimization (Phase 7c) and the HNSW probe shortcut (Phase 7d.2). |
+| [`src/sql/db/database.rs`](../src/sql/db/database.rs) | `Database`: table map + optional `source_path` + optional long-lived `Pager` + transaction-snapshot state |
+| [`src/sql/db/table.rs`](../src/sql/db/table.rs) | `Table`, `Column`, `Row`, `Value` (in-memory storage incl. VECTOR + JSON columns); helpers for row iteration (`rowids`, `get_value`, `set_value`, `delete_row`, `insert_row`) |
+| [`src/sql/hnsw.rs`](../src/sql/hnsw.rs) | Standalone HNSW algorithm — insert / search / layer assignment / beam search. Phase 7d.1. |
+| [`src/sql/json.rs`](../src/sql/json.rs) | JSON column type + path-extraction functions (`json_extract`, `json_type`, `json_array_length`, `json_object_keys`). Phase 7e. |
+| [`src/sql/pager/`](../src/sql/pager/) | On-disk file format and I/O — see [file-format.md](file-format.md) and [pager.md](pager.md) for details. WAL + checkpointer + shared/exclusive lock modes (Phase 4a-4e) live here. |
 
 ## Flow of a SQL statement
 
@@ -104,16 +127,18 @@ Steps 1–7 are purely in-memory; step 8 is the only disk contact, and after the
 - **Planning**: intentionally not a thing yet. Execution is direct — a query plan is implicit in the executor code path.
 - **Execution**: `src/sql/executor.rs` walks the internal structs, drives reads against `Table`, and writes via `Table::set_value` / `insert_row` / `delete_row`.
 - **Storage (in memory)**: `src/sql/db/table.rs` — column-oriented `BTreeMap<rowid, value>` per column; indexes as separate `BTreeMap`s on UNIQUE/PK columns.
-- **Storage (on disk)**: `src/sql/pager/` — 4 KiB pages. Currently every table serializes to a `bincode` blob laid across chained pages; a real B-Tree replaces this in Phase 3d.
-- **Persistence policy**: `src/sql/mod.rs::process_command` for when to auto-save; `src/sql/pager/mod.rs::save_database` for how.
+- **Storage (on disk)**: `src/sql/pager/` — 4 KiB pages, real B-Tree per table (Phase 3d), secondary indexes (3e), HNSW indexes as their own page tree (7d.3), WAL + crash-safe checkpointer (4c-4d), shared/exclusive lock modes (4e).
+- **Persistence policy**: `src/sql/mod.rs::process_command` for when to auto-save; `src/sql/pager/mod.rs::save_database` for how. Inside a `BEGIN`/`COMMIT` block, auto-save is suppressed and changes accumulate against an in-memory snapshot — `COMMIT` flushes the whole batch in one WAL frame; `ROLLBACK` restores the snapshot.
 - **Error handling**: `src/error.rs` defines a single `SQLRiteError` enum used throughout, with `#[from]` conversions from `ParserError` and `io::Error`.
 
 ## What's deliberately missing
 
-- No network layer — SQLRite is embedded only. Phase 5 will split into a `lib` crate with a Connection API.
-- No transactions — every statement implicitly commits. `BEGIN`/`COMMIT` are parsed by `sqlparser` but rejected by the executor.
-- No query optimizer — simple table scans.
-- No server process — no daemon, no wire protocol.
-- No concurrent access — single process, single thread. WAL + file locking is Phase 4.
+The roadmap has shipped far enough that the original "deliberately missing" list mostly turned into shipped features. What's still left:
+
+- **No query optimizer** beyond the bounded-heap top-k pass for KNN (Phase 7c) and the HNSW probe shortcut (7d.2). Equality-on-PK probes are direct; everything else is a table scan.
+- **No joins.** `INNER` / `LEFT OUTER` / `CROSS` are parsed but rejected by the executor. On the "possible extras" list in [roadmap.md](roadmap.md).
+- **No aggregates.** `COUNT(*)` / `SUM` / `AVG` / `GROUP BY` aren't implemented yet — the parser accepts them but the executor errors. Phase 8 candidate alongside FTS.
+- **No network layer.** SQLRite is embedded-only. The closest thing is the [`sqlrite-mcp`](mcp.md) server, which is stdio (not network). A real wire protocol isn't on the roadmap.
+- **No streaming row cursor.** `Rows` is currently backed by an eager `Vec` (Phase 5a). The `Rows::next` API is shaped to support a real cursor — the swap is deferred to **5a.2**.
 
-Most of these are on the [Roadmap](roadmap.md).
+Everything else from the original "deliberately missing" list (transactions, file locking, concurrency, embedding API, FFI, language SDKs, WASM, AI extensions) has shipped. See [roadmap.md](roadmap.md) for the full ledger.