dirsql 0.3.69__tar.gz → 0.3.71__tar.gz

{dirsql-0.3.69 → dirsql-0.3.71}/Cargo.lock

@@ -500,7 +500,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.3.69"
+version = "0.3.71"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.3.69 → dirsql-0.3.71}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.69
+Version: 0.3.71
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index
 Author: Kevin Scott

{dirsql-0.3.69/packages/rust → dirsql-0.3.71}/docs/reference/cli.md

@@ -1,10 +1,11 @@
 # CLI
 
-The `dirsql` binary has two modes:
+The `dirsql` binary has three modes:
 
 | Invocation | Behavior |
 |---|---|
 | `dirsql` (no subcommand) | Start a long-lived HTTP server exposing a SQL view of a directory. See [HTTP API](./http-api.md). |
+| `dirsql query "<sql>"` | Build the index, run one query, print the rows as JSON, exit. No server, no watch. |
 | `dirsql init` | Generate a starter `.dirsql.toml` by running `claude` over a directory. |
 
 ## Installation
@@ -97,6 +98,46 @@ with a JSON body describing the failure:
 | `0` | Clean shutdown after `SIGINT` / `SIGTERM`. |
 | `1` | Failed to bind `host:port`, or an error during shutdown. |
 
+## `dirsql query`
+
+Run one SQL query from the shell — for ad-hoc inspection, scripting, and
+docs verification snippets — without booting the server and `curl`ing it:
+
+```bash
+dirsql query "SELECT _basename, _size FROM files ORDER BY _size DESC LIMIT 5"
+# [{"_basename":"model.bin","_size":104857600}, …]
+
+dirsql query "SELECT COUNT(*) AS n FROM posts" | jq '.[0].n'
+```
+
+The subcommand builds the index, runs the SQL, prints the result rows as a
+JSON array on stdout (byte-identical to the [`POST /query`](./http-api.md)
+response body), and exits `0`.
+
+`dirsql query` is a thin adapter over the **same query pipeline the server
+uses**, so behavior is identical to `POST /query` by construction:
+
+- **Config discovery** honors `--config` (default `./.dirsql.toml`),
+  [zero-config mode](#zero-config-mode), and `--extension` overrides,
+  exactly as server mode does.
+- **Hooks** ([`pre-query`](./hooks.md#pre-query) /
+  [`post-query`](./hooks.md#post-query)) and the
+  [`[dirsql].hook-timeout`](./config.md#dirsql-keys) apply identically.
+- The **30-second query timeout**, the **read-only rule**, and the
+  `_dirsql_*` **internal-table denial** apply identically. A rejected read
+  is an error, not empty output.
+
+Errors print the same diagnostic the HTTP `{"error": …}` body carries —
+config failures, SQL errors, rejected reads, hook failures, timeouts — to
+stderr, with exit code `1`.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Query succeeded; rows printed on stdout. |
+| `1` | Any failure: config, SQL, rejected read, hook, or timeout. The diagnostic is on stderr. |
+
 ## `dirsql init`
 
 Generates a `.dirsql.toml` by running the `claude` CLI over the target

{dirsql-0.3.69 → dirsql-0.3.71}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.3.69"
+version = "0.3.71"
 edition.workspace = true
 publish = false
 readme = "README.md"

{dirsql-0.3.69 → dirsql-0.3.71}/packages/python/docs/reference/cli.md

@@ -1,10 +1,11 @@
 # CLI
 
-The `dirsql` binary has two modes:
+The `dirsql` binary has three modes:
 
 | Invocation | Behavior |
 |---|---|
 | `dirsql` (no subcommand) | Start a long-lived HTTP server exposing a SQL view of a directory. See [HTTP API](./http-api.md). |
+| `dirsql query "<sql>"` | Build the index, run one query, print the rows as JSON, exit. No server, no watch. |
 | `dirsql init` | Generate a starter `.dirsql.toml` by running `claude` over a directory. |
 
 ## Installation
@@ -97,6 +98,46 @@ with a JSON body describing the failure:
 | `0` | Clean shutdown after `SIGINT` / `SIGTERM`. |
 | `1` | Failed to bind `host:port`, or an error during shutdown. |
 
+## `dirsql query`
+
+Run one SQL query from the shell — for ad-hoc inspection, scripting, and
+docs verification snippets — without booting the server and `curl`ing it:
+
+```bash
+dirsql query "SELECT _basename, _size FROM files ORDER BY _size DESC LIMIT 5"
+# [{"_basename":"model.bin","_size":104857600}, …]
+
+dirsql query "SELECT COUNT(*) AS n FROM posts" | jq '.[0].n'
+```
+
+The subcommand builds the index, runs the SQL, prints the result rows as a
+JSON array on stdout (byte-identical to the [`POST /query`](./http-api.md)
+response body), and exits `0`.
+
+`dirsql query` is a thin adapter over the **same query pipeline the server
+uses**, so behavior is identical to `POST /query` by construction:
+
+- **Config discovery** honors `--config` (default `./.dirsql.toml`),
+  [zero-config mode](#zero-config-mode), and `--extension` overrides,
+  exactly as server mode does.
+- **Hooks** ([`pre-query`](./hooks.md#pre-query) /
+  [`post-query`](./hooks.md#post-query)) and the
+  [`[dirsql].hook-timeout`](./config.md#dirsql-keys) apply identically.
+- The **30-second query timeout**, the **read-only rule**, and the
+  `_dirsql_*` **internal-table denial** apply identically. A rejected read
+  is an error, not empty output.
+
+Errors print the same diagnostic the HTTP `{"error": …}` body carries —
+config failures, SQL errors, rejected reads, hook failures, timeouts — to
+stderr, with exit code `1`.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Query succeeded; rows printed on stdout. |
+| `1` | Any failure: config, SQL, rejected read, hook, or timeout. The diagnostic is on stderr. |
+
 ## `dirsql init`
 
 Generates a `.dirsql.toml` by running the `claude` CLI over the target

{dirsql-0.3.69 → dirsql-0.3.71}/packages/python/e2e-attestation.json

@@ -1,6 +1,6 @@
 {
   "command": "uv run python -m pytest tests/e2e/ -x -q",
-  "ran_at": 1783257990,
+  "ran_at": 1783389455,
   "exit_code": 0,
-  "commit": "cb8d663ecb72a808f4ab99589af16949e9449f3b"
+  "commit": "edd5f78fd484ce51829ff3f8387e720b989fb8fb"
 }

{dirsql-0.3.69 → dirsql-0.3.71/packages/rust}/docs/reference/cli.md

@@ -1,10 +1,11 @@
 # CLI
 
-The `dirsql` binary has two modes:
+The `dirsql` binary has three modes:
 
 | Invocation | Behavior |
 |---|---|
 | `dirsql` (no subcommand) | Start a long-lived HTTP server exposing a SQL view of a directory. See [HTTP API](./http-api.md). |
+| `dirsql query "<sql>"` | Build the index, run one query, print the rows as JSON, exit. No server, no watch. |
 | `dirsql init` | Generate a starter `.dirsql.toml` by running `claude` over a directory. |
 
 ## Installation
@@ -97,6 +98,46 @@ with a JSON body describing the failure:
 | `0` | Clean shutdown after `SIGINT` / `SIGTERM`. |
 | `1` | Failed to bind `host:port`, or an error during shutdown. |
 
+## `dirsql query`
+
+Run one SQL query from the shell — for ad-hoc inspection, scripting, and
+docs verification snippets — without booting the server and `curl`ing it:
+
+```bash
+dirsql query "SELECT _basename, _size FROM files ORDER BY _size DESC LIMIT 5"
+# [{"_basename":"model.bin","_size":104857600}, …]
+
+dirsql query "SELECT COUNT(*) AS n FROM posts" | jq '.[0].n'
+```
+
+The subcommand builds the index, runs the SQL, prints the result rows as a
+JSON array on stdout (byte-identical to the [`POST /query`](./http-api.md)
+response body), and exits `0`.
+
+`dirsql query` is a thin adapter over the **same query pipeline the server
+uses**, so behavior is identical to `POST /query` by construction:
+
+- **Config discovery** honors `--config` (default `./.dirsql.toml`),
+  [zero-config mode](#zero-config-mode), and `--extension` overrides,
+  exactly as server mode does.
+- **Hooks** ([`pre-query`](./hooks.md#pre-query) /
+  [`post-query`](./hooks.md#post-query)) and the
+  [`[dirsql].hook-timeout`](./config.md#dirsql-keys) apply identically.
+- The **30-second query timeout**, the **read-only rule**, and the
+  `_dirsql_*` **internal-table denial** apply identically. A rejected read
+  is an error, not empty output.
+
+Errors print the same diagnostic the HTTP `{"error": …}` body carries —
+config failures, SQL errors, rejected reads, hook failures, timeouts — to
+stderr, with exit code `1`.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Query succeeded; rows printed on stdout. |
+| `1` | Any failure: config, SQL, rejected read, hook, or timeout. The diagnostic is on stderr. |
+
 ## `dirsql init`
 
 Generates a `.dirsql.toml` by running the `claude` CLI over the target

{dirsql-0.3.69 → dirsql-0.3.71}/packages/rust/src/bin/dirsql.rs

@@ -1,5 +1,7 @@
-//! `dirsql` CLI binary. Two modes:
+//! `dirsql` CLI binary. Three modes:
 //! - No subcommand: HTTP server documented in `docs/reference/cli.md`.
+//! - `query`: one-shot query over the same pipeline the server uses; see
+//!   `docs/reference/cli.md`.
 //! - `init`: starter `.dirsql.toml` generation; see `docs/reference/cli.md`.
 //!
 //! Only compiled with `--features cli`.
@@ -9,7 +11,8 @@ use std::process::ExitCode;
 
 use clap::{Args, Parser, Subcommand};
 use dirsql::cli::{
-    AppState, PostQuery, PreQuery, ServerConfig, init::InitOptions, serve_with_state,
+    AppState, PostQuery, PreQuery, ServerConfig, execute::execute_query, init::InitOptions,
+    serve_with_state,
 };
 use dirsql::{DirSQL, Extension, Row, Table};
 
@@ -31,9 +34,9 @@ struct Cli {
 
     /// Path to the config file (default: `./.dirsql.toml`). The index is
     /// rooted at the directory containing this file. When the file does
-    /// not exist, a default `files` table is served. Used when no
-    /// subcommand is given.
-    #[arg(long, default_value = "./.dirsql.toml")]
+    /// not exist, a default `files` table is served. Used by server mode
+    /// and by the `query` subcommand.
+    #[arg(long, default_value = "./.dirsql.toml", global = true)]
     config: PathBuf,
 
     /// Bind address. Used when no subcommand is given.
@@ -53,8 +56,9 @@ struct Cli {
     /// which need an interpreter this compiled binary lacks (see #227) — and
     /// passes the resolved literal paths here. When any are present, the TOML
     /// config's own extension entries are not loaded (the launcher already
-    /// merged and resolved them).
-    #[arg(long = "extension")]
+    /// merged and resolved them). Used by server mode and by the `query`
+    /// subcommand.
+    #[arg(long = "extension", global = true)]
     extension: Vec<String>,
 }
 
@@ -63,6 +67,19 @@ enum Command {
     /// Generate a starter `.dirsql.toml` by running `claude` over the
     /// target directory.
     Init(InitArgs),
+
+    /// Run one SQL query against the indexed directory, print the result
+    /// rows as JSON on stdout, and exit. No server, no watch. Shares the
+    /// server's query pipeline, so config discovery, hooks, the query
+    /// timeout, the read-only rule, and error classification are identical
+    /// to `POST /query`.
+    Query(QueryArgs),
+}
+
+#[derive(Debug, Args)]
+struct QueryArgs {
+    /// The SQL to run (a single read-only statement).
+    sql: String,
 }
 
 #[derive(Debug, Args)]
@@ -86,10 +103,51 @@ async fn main() -> ExitCode {
 
     match cli.command.take() {
         Some(Command::Init(args)) => run_init(args),
+        Some(Command::Query(args)) => run_query(&cli, args).await,
         None => run_server(cli).await,
     }
 }
 
+/// One-shot `dirsql query`: build the index exactly as server mode would
+/// (same `load_state` / hook loading), run the SQL through the shared
+/// [`execute_query`] pipeline, print the result JSON on stdout, and exit.
+/// Any [`QueryFailure`](dirsql::cli::execute::QueryFailure) prints its
+/// message — the same string the HTTP `{"error": …}` body carries — to
+/// stderr with a non-zero exit.
+async fn run_query(cli: &Cli, args: QueryArgs) -> ExitCode {
+    let state = load_state(cli);
+    let pre_query = load_pre_query(cli);
+    let post_query = load_post_query(cli);
+    // Same default the server binds with; the pipeline enforces it.
+    let timeout = ServerConfig::default().query_timeout;
+
+    match execute_query(
+        &state,
+        query_body(&args.sql),
+        timeout,
+        pre_query.as_ref(),
+        post_query.as_ref(),
+    )
+    .await
+    {
+        Ok(value) => {
+            println!("{value}");
+            ExitCode::SUCCESS
+        }
+        Err(failure) => {
+            eprintln!("dirsql query: {}", failure.message());
+            ExitCode::from(1)
+        }
+    }
+}
+
+/// Synthesize the exact `POST /query` body for a positional SQL argument,
+/// so the shared pipeline's intake validation and `pre-query` hook see
+/// byte-for-byte what an HTTP client would send.
+fn query_body(sql: &str) -> String {
+    serde_json::json!({ "sql": sql }).to_string()
+}
+
 fn run_init(args: InitArgs) -> ExitCode {
     let root = match args.root {
         Some(p) => p,
@@ -322,6 +380,30 @@ async fn wait_for_shutdown() -> std::io::Result<()> {
 mod tests {
     use super::*;
 
+    #[test]
+    fn query_body_wraps_sql_in_the_http_request_shape() {
+        // The subcommand must feed the pipeline the exact body a curl'd
+        // `POST /query` carries, so intake validation stays single-sourced.
+        assert_eq!(query_body("SELECT 1"), r#"{"sql":"SELECT 1"}"#);
+    }
+
+    #[test]
+    fn query_body_escapes_sql_as_json() {
+        // SQL containing quotes/newlines must arrive as valid JSON, not be
+        // spliced raw into the body.
+        assert_eq!(
+            query_body("SELECT \"a\"\nFROM t"),
+            r#"{"sql":"SELECT \"a\"\nFROM t"}"#
+        );
+    }
+
+    #[test]
+    fn query_body_preserves_blank_sql_for_the_shared_rejection() {
+        // Blank SQL is NOT rejected here: it flows to the pipeline's shared
+        // empty-rejection so both surfaces emit the identical message.
+        assert_eq!(query_body("   "), r#"{"sql":"   "}"#);
+    }
+
     #[test]
     fn parse_extension_specs_handles_bare_path_and_entrypoint() {
         let specs = vec![

dirsql-0.3.71/packages/rust/src/cli/execute.rs

@@ -0,0 +1,314 @@
+//! Transport-agnostic `/query` pipeline.
+//!
+//! The full orchestration for running one query — intake validation,
+//! the `pre-query` hook, the query timeout, [`DirSQL::query`], row
+//! serialization, the `post-query` hook, and error classification —
+//! lives here exactly once. The HTTP handler and the one-shot
+//! `dirsql query` subcommand (#399) are thin transport adapters over
+//! [`execute_query`], so the two surfaces cannot drift behaviorally:
+//! per-surface code only maps [`QueryFailure`] to a status code or an
+//! exit code.
+
+use std::time::Duration;
+
+use serde::Deserialize;
+use serde_json::Value;
+
+use super::serialize::rows_to_json;
+use super::{AppState, PostQuery, PreQuery};
+use crate::command::{Placeholder, run_command};
+use crate::{DirSQL, DirSqlError};
+
+/// Cap on the serialized result payload passed as the `{args}` argv token.
+/// Beyond this, `{args}` is emptied and the operator is directed to stdin
+/// (which always carries the full payload) — comfortably under Linux's 128 KiB
+/// single-arg `MAX_ARG_STRLEN`.
+const POST_QUERY_ARGS_MAX: usize = 96 * 1024;
+
+/// Why a query failed, classified independently of transport. The HTTP
+/// adapter maps each arm to a status code (400 / 408 / 500 / 503); the CLI
+/// adapter maps every arm to stderr + a non-zero exit.
+#[derive(Debug)]
+pub enum QueryFailure {
+    /// Malformed input the caller can fix: unparsable body, missing/empty
+    /// `sql`, or a SQL error from the core (HTTP 400).
+    BadRequest(String),
+    /// The query exceeded the configured timeout (HTTP 408).
+    Timeout(Duration),
+    /// A server-side fault: hook failure, join error, lock poisoning
+    /// (HTTP 500).
+    Internal(String),
+    /// The index never became ready — the degraded config state (HTTP 503).
+    Unavailable(String),
+}
+
+impl QueryFailure {
+    /// The diagnostic message, identical across transports (the HTTP
+    /// `{"error": …}` body and the CLI stderr line).
+    pub fn message(&self) -> String {
+        match self {
+            Self::Timeout(timeout) => format!("query exceeded {timeout:?} timeout"),
+            Self::BadRequest(msg) | Self::Internal(msg) | Self::Unavailable(msg) => msg.clone(),
+        }
+    }
+}
+
+#[derive(Debug, Deserialize)]
+struct QueryBody {
+    sql: Option<String>,
+}
+
+/// Run one query end to end: resolve the SQL from `raw_body` (through the
+/// `pre-query` hook when present, else parsed as `{"sql": …}`), execute it
+/// against the index under `timeout`, serialize the rows, and reshape them
+/// through the `post-query` hook when present. `raw_body` is the exact
+/// payload a `POST /query` request carries; the CLI adapter synthesizes the
+/// same shape so both surfaces share intake validation and hook semantics.
+pub async fn execute_query(
+    state: &AppState,
+    raw_body: String,
+    timeout: Duration,
+    pre_query: Option<&PreQuery>,
+    post_query: Option<&PostQuery>,
+) -> Result<Value, QueryFailure> {
+    // Resolve the SQL to run. With a `pre-query` hook the raw body is
+    // rewritten by the command; without one it is parsed as `{"sql": …}`.
+    let sql = match pre_query {
+        Some(pq) => run_pre_query(pq, raw_body).await?,
+        None => parse_sql_body(&raw_body)?,
+    };
+
+    let db = require_ready(state)?;
+
+    let join =
+        tokio::time::timeout(timeout, tokio::task::spawn_blocking(move || db.query(&sql))).await;
+
+    match join {
+        Ok(Ok(Ok(rows))) => {
+            let rows_json = rows_to_json(&rows);
+            match post_query {
+                Some(pq) => run_post_query(pq, rows_json).await,
+                None => Ok(Value::Array(rows_json)),
+            }
+        }
+        Ok(Ok(Err(err))) => Err(classify_query_error(err)),
+        Ok(Err(join_err)) => Err(QueryFailure::Internal(join_err.to_string())),
+        Err(_elapsed) => Err(QueryFailure::Timeout(timeout)),
+    }
+}
+
+/// Return a cloned [`DirSQL`] handle, or [`QueryFailure::Unavailable`] if
+/// the index started in the degraded [`AppState::Unavailable`] state.
+pub fn require_ready(state: &AppState) -> Result<DirSQL, QueryFailure> {
+    match state {
+        AppState::Ready(db) => Ok(db.clone()),
+        AppState::Unavailable(reason) => Err(QueryFailure::Unavailable(reason.clone())),
+    }
+}
+
+/// Parse a raw query body as `{"sql": …}` and return the trimmed SQL.
+/// `BadRequest` on malformed JSON, and on a missing/empty `sql` field.
+fn parse_sql_body(body: &str) -> Result<String, QueryFailure> {
+    let parsed: QueryBody =
+        serde_json::from_str(body).map_err(|err| QueryFailure::BadRequest(err.to_string()))?;
+    match parsed.sql.as_deref().map(str::trim) {
+        Some(s) if !s.is_empty() => Ok(s.to_string()),
+        Some(_) => Err(QueryFailure::BadRequest("`sql` must not be empty".into())),
+        None => Err(QueryFailure::BadRequest("missing `sql` field".into())),
+    }
+}
+
+/// SQL errors from the core are the caller's to fix (`BadRequest`); every
+/// other failure (lock poisoning, watch/config faults) is server-side
+/// (`Internal`).
+fn classify_query_error(err: DirSqlError) -> QueryFailure {
+    match err {
+        DirSqlError::Core(_) => QueryFailure::BadRequest(err.to_string()),
+        _ => QueryFailure::Internal(err.to_string()),
+    }
+}
+
+/// Run the `pre-query` hook over the raw request body and return the SQL it
+/// prints. The body is passed as the injection-safe `{args}` placeholder (a
+/// single argv token); the command's last non-empty stdout line is the SQL to
+/// run. Any failure (non-zero exit, timeout, spawn error) maps to `Internal`
+/// carrying the command's stderr tail.
+async fn run_pre_query(pq: &PreQuery, raw_body: String) -> Result<String, QueryFailure> {
+    let command = pq.command.clone();
+    let config_dir = pq.config_dir.clone();
+    let timeout = pq.timeout;
+    // `run_command` is blocking — it spawns a child and joins drain threads —
+    // so run it off the async runtime. It enforces the hook's timeout
+    // (the global `[dirsql].hook-timeout`, default 30s) internally, so no outer
+    // `tokio::time::timeout` is needed.
+    let outcome = tokio::task::spawn_blocking(move || {
+        run_command(
+            &command,
+            &[Placeholder::new("args", &raw_body)],
+            &config_dir,
+            timeout,
+            None,
+        )
+    })
+    .await
+    .map_err(|join_err| QueryFailure::Internal(join_err.to_string()))?;
+
+    // `run_command` only returns `Ok` with a non-empty last stdout line
+    // (`EmptyOutput` otherwise), so the payload is the SQL as-is.
+    outcome
+        .map(|out| out.payload)
+        .map_err(|err| QueryFailure::Internal(err.to_string()))
+}
+
+/// Run the `post-query` hook over a successful result set and return the JSON
+/// body it prints. The rows are serialized to a JSON array and delivered two
+/// ways: always on the child's stdin (unbounded, injection-safe), and as the
+/// `{args}` placeholder when the payload is within [`POST_QUERY_ARGS_MAX`]
+/// (beyond that `{args}` is emptied and a warning names the size, directing
+/// the operator to stdin — never silent truncation). The command's last
+/// non-empty stdout line is parsed as JSON and returned as the result;
+/// anything that isn't valid JSON, or any failure (non-zero exit, timeout,
+/// spawn error), maps to `Internal`.
+async fn run_post_query(pq: &PostQuery, rows: Vec<Value>) -> Result<Value, QueryFailure> {
+    let payload =
+        serde_json::to_string(&rows).map_err(|err| QueryFailure::Internal(err.to_string()))?;
+    let command = pq.command.clone();
+    let config_dir = pq.config_dir.clone();
+    let timeout = pq.timeout;
+    // `run_command` is blocking — it spawns a child and joins drain threads —
+    // so run it off the async runtime. It enforces the hook's timeout
+    // (the global `[dirsql].hook-timeout`, default 30s) internally, so no outer
+    // `tokio::time::timeout` is needed.
+    let outcome = tokio::task::spawn_blocking(move || {
+        let args_value = if payload.len() <= POST_QUERY_ARGS_MAX {
+            payload.clone()
+        } else {
+            eprintln!(
+                "dirsql: post-query result payload is {} bytes, exceeding the \
+                 {POST_QUERY_ARGS_MAX}-byte argv threshold; `{{args}}` is emptied — \
+                 read the rows from stdin instead",
+                payload.len()
+            );
+            String::new()
+        };
+        run_command(
+            &command,
+            &[Placeholder::new("args", &args_value)],
+            &config_dir,
+            timeout,
+            Some(payload.as_bytes()),
+        )
+    })
+    .await
+    .map_err(|join_err| QueryFailure::Internal(join_err.to_string()))?;
+
+    let out = outcome.map_err(|err| QueryFailure::Internal(err.to_string()))?;
+
+    // The command's payload (last non-empty stdout line) is the JSON result
+    // body; reject anything that doesn't parse as JSON.
+    serde_json::from_str(&out.payload).map_err(|err| {
+        QueryFailure::Internal(format!("post-query did not return valid JSON: {err}"))
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // The `DirSqlError::Core => BadRequest` arm of `classify_query_error` is
+    // exercised end-to-end at the integration tier by
+    // `post_query_malformed_sql_returns_400_not_500` in
+    // `tests/cli_integration.rs`, which posts malformed SQL to `/query` and
+    // asserts the 400. Constructing a `Core` value inline would require
+    // importing the first-party `crate::db::DbError`, which the
+    // `testing-conventions` `unit lint` isolation rule forbids (a unit test
+    // may reach only `super::` and pure `std`). The non-Core arm below is
+    // pure -- it builds a `super::DirSqlError::Lock` -- so it stays inline.
+
+    #[test]
+    fn classify_non_core_error_is_internal() {
+        // Lock/watch/config failures are server-side faults -> `Internal`.
+        // This drives the `_ =>` arm of `classify_query_error`.
+        let err = DirSqlError::Lock("poisoned".into());
+        let failure = classify_query_error(err);
+        assert!(
+            matches!(failure, QueryFailure::Internal(_)),
+            "got: {failure:?}"
+        );
+    }
+
+    #[test]
+    fn require_ready_fails_unavailable_when_degraded() {
+        // The degraded state yields `Unavailable` carrying the diagnostic
+        // verbatim instead of a `DirSQL` handle.
+        let state = AppState::Unavailable("config failed to load".into());
+        // `DirSQL` isn't `Debug`, so go through `.err()` (which drops the Ok
+        // value) rather than `expect_err`.
+        let failure = require_ready(&state)
+            .err()
+            .expect("Unavailable must not yield a db");
+        match failure {
+            QueryFailure::Unavailable(reason) => assert_eq!(reason, "config failed to load"),
+            other => panic!("expected Unavailable, got: {other:?}"),
+        }
+    }
+
+    // `parse_sql_body` is the no-`pre-query` intake path: it is pure (serde
+    // only), so it is unit-tested here directly rather than through the async
+    // `execute_query` pipeline (which needs a live index and is covered at
+    // the integration tier).
+
+    #[test]
+    fn parse_sql_body_returns_trimmed_sql() {
+        // Surrounding whitespace is stripped; the inner SQL is returned as-is.
+        let sql = parse_sql_body(r#"{"sql": "  SELECT 1  "}"#).expect("valid body");
+        assert_eq!(sql, "SELECT 1");
+    }
+
+    #[test]
+    fn parse_sql_body_rejects_malformed_json() {
+        // A body that isn't JSON fails at the serde step -> `BadRequest`.
+        let failure = parse_sql_body("not json").expect_err("malformed JSON must be rejected");
+        assert!(
+            matches!(failure, QueryFailure::BadRequest(_)),
+            "got: {failure:?}"
+        );
+    }
+
+    #[test]
+    fn parse_sql_body_rejects_whitespace_only_sql() {
+        // A present-but-blank `sql` trims to empty -> `BadRequest` (the
+        // `Some(_)` arm, and the `false` side of the `!s.is_empty()` guard).
+        let failure = parse_sql_body(r#"{"sql": "   "}"#).expect_err("empty sql must be rejected");
+        match failure {
+            QueryFailure::BadRequest(msg) => assert_eq!(msg, "`sql` must not be empty"),
+            other => panic!("expected BadRequest, got: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn parse_sql_body_rejects_missing_sql_field() {
+        // Valid JSON object with no `sql` key -> the `None` arm -> `BadRequest`.
+        let failure = parse_sql_body("{}").expect_err("missing sql must be rejected");
+        match failure {
+            QueryFailure::BadRequest(msg) => assert_eq!(msg, "missing `sql` field"),
+            other => panic!("expected BadRequest, got: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn timeout_failure_message_names_the_duration() {
+        // The timeout arm formats its message from the stored duration —
+        // the exact text the HTTP 408 body carried before the extraction.
+        let failure = QueryFailure::Timeout(Duration::from_secs(30));
+        assert_eq!(failure.message(), "query exceeded 30s timeout");
+    }
+
+    #[test]
+    fn non_timeout_failure_messages_pass_through_verbatim() {
+        // The other three arms carry their diagnostic string as-is.
+        assert_eq!(QueryFailure::BadRequest("a".into()).message(), "a");
+        assert_eq!(QueryFailure::Internal("b".into()).message(), "b");
+        assert_eq!(QueryFailure::Unavailable("c".into()).message(), "c");
+    }
+}