dirsql 0.3.70__tar.gz → 0.3.71__tar.gz

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

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

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

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

{dirsql-0.3.70/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.70 → 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.70"
+version = "0.3.71"
 edition.workspace = true
 publish = false
 readme = "README.md"

{dirsql-0.3.70 → 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.70 → 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": 1783387386,
+  "ran_at": 1783389455,
   "exit_code": 0,
-  "commit": "a9cf031533c564bf43c77d893745f9e85fed059f"
+  "commit": "edd5f78fd484ce51829ff3f8387e720b989fb8fb"
 }

{dirsql-0.3.70 → 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.70 → 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![