dirsql 0.3.70__tar.gz → 0.3.72__tar.gz

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

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

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

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

{dirsql-0.3.70 → dirsql-0.3.72}/dirsql/_async.py

@@ -59,7 +59,7 @@ class DirSQL:
     at startup. Any ``[[dirsql.extension]]`` entries in a ``config`` file are
     appended after the programmatic ones. A ``path`` (programmatic or
     config-file) may be a bare **package name**, resolved from the installed
-    package in the runtime env (#298 / #313).
+    package in the runtime env.
     """
 
     def __init__(
@@ -98,15 +98,13 @@ class DirSQL:
         """Resolve extensions and construct the Rust-backed instance.
 
         Runs on a worker thread (via ``asyncio.to_thread``): both the
-        package-name resolution (``importlib`` + filesystem globs) and the
-        core's initial scan are blocking work.
+        package-name resolution and the core's initial scan are blocking.
 
         When the ``config`` file names an extension by bare package name, the
         SDK resolves every one of the config's ``[[dirsql.extension]]`` entries
-        itself (#313) -- appended after the programmatic ones, matching the
-        core's ordering -- and suppresses the core's own config-extension
-        loading so the entries are not loaded a second time (and the core never
-        sees the unresolvable bare name).
+        itself -- appended after the programmatic ones -- and suppresses the
+        core's own config-extension loading so the entries are not loaded a
+        second time (the core cannot resolve a bare name).
         """
         extensions = self._resolved_extensions()
         suppress = False
@@ -129,9 +127,8 @@ class DirSQL:
     def _resolved_extensions(self):
         """Resolve each programmatic extension's ``path`` to a loadable file.
 
-        A bare package name is resolved to the loadable installed in the runtime
-        env (#298); path-looking values are passed through verbatim (mirroring
-        the Rust builder, which takes programmatic paths as-is). Config-file
+        A bare package name is resolved to the loadable installed in the
+        runtime env; path-looking values pass through verbatim. Config-file
         ``[[dirsql.extension]]`` entries are handled by ``_build_db``.
         """
         if not self._extensions:

{dirsql-0.3.70 → dirsql-0.3.72}/dirsql/cli/main.py

@@ -24,7 +24,7 @@ def main(argv: list[str] | None = None) -> int:
         return 1
 
     # Resolve any package-name extensions in a TOML config here (the binary
-    # can't) and pass them as `--extension` flags; a no-op otherwise (#227).
+    # can't) and pass them as `--extension` flags; a no-op otherwise.
     try:
         argv = with_resolved_extensions(argv)
     except Exception as exc:

{dirsql-0.3.70 → dirsql-0.3.72}/dirsql/cli/resolve_config_extensions.py

@@ -1,14 +1,12 @@
 """Launcher-side resolution of a TOML config's ``[[dirsql.extension]]`` entries.
 
-Mirrors the TypeScript launcher. The compiled ``dirsql`` binary reads a
-``.dirsql.toml`` itself and loads its extensions literally -- it has no
-``importlib``, so it cannot resolve a bare **package name** (#227). This
-launcher can. When a TOML config names an extension by package name, the
-shared SDK resolver (:mod:`dirsql.resolve_config_extensions`, #313) resolves
-every one of its extensions and this launcher passes the resolved literal
-paths to the binary via repeatable ``--extension`` flags; the binary then
-loads those and ignores the config's own extension entries (the Rust
-``--extension`` flag / ``suppress_config_extensions``).
+The compiled ``dirsql`` binary loads a config's extensions literally -- it
+has no ``importlib``, so it cannot resolve a bare **package name**. When a
+TOML config names an extension by package name, the shared SDK resolver
+(:mod:`dirsql.resolve_config_extensions`) resolves every one of its
+extensions and this launcher passes the resolved literal paths to the binary
+via repeatable ``--extension`` flags; the binary then loads those and ignores
+the config's own extension entries.
 
 Native-language configs (``.py`` / ``.js`` / ``.mjs`` / ``.cjs``) are untouched:
 the binary dispatches those to ``dirsql interpret``, whose handshake already

{dirsql-0.3.70 → dirsql-0.3.72}/dirsql/resolve_config_extensions.py

@@ -1,16 +1,14 @@
 """SDK-side resolution of a TOML config's ``[[dirsql.extension]]`` entries.
 
-The Rust core parses a ``.dirsql.toml`` itself and loads its extensions
-literally -- it has no ``importlib``, so it cannot resolve a bare **package
-name** (#227). The SDK can (#313). When a TOML config names an extension by
-package name, the SDK resolves every one of its extensions here, hands the
-core the resolved literal paths, and suppresses the core's own config-extension
-loading (the Rust ``suppress_config_extensions`` builder toggle) so the
-config's entries are not loaded a second time.
+The Rust core loads a config's extensions literally -- it has no
+``importlib``, so it cannot resolve a bare **package name**. When a TOML
+config names an extension by package name, the SDK resolves every one of its
+extensions here, hands the core the resolved literal paths, and suppresses
+the core's own config-extension loading (``suppress_config_extensions``) so
+the config's entries are not loaded a second time.
 
 Shared by the ``DirSQL`` constructor (``config=`` path) and the CLI launcher
-(``dirsql.cli.resolve_config_extensions``, which converts the resolved specs
-into ``--extension`` flags for the binary).
+(which converts the resolved specs into ``--extension`` flags).
 """
 
 from __future__ import annotations
@@ -45,9 +43,7 @@ def resolve_config_extension_specs(config_path):
     entries = cfg.get("extension")
     if not isinstance(entries, list):
         return None
-    # Only intervene when at least one path is a bare package name; a config
-    # with only literal paths (or no entries at all) keeps the core's existing
-    # behavior untouched.
+    # Only intervene when at least one path is a bare package name.
     if not any(
         isinstance(e, dict)
         and isinstance(e.get("path"), str)

{dirsql-0.3.70 → dirsql-0.3.72}/dirsql/resolve_extension.py

@@ -1,23 +1,17 @@
 """Resolve an extension entry's ``path`` to a concrete loadable file.
 
-#225 supports only literal file paths. #298 adds resolving a bare **package
-name**: when ``path`` carries no path separator and no loadable-file suffix, it
-names a package installed in the runtime env, and dirsql discovers the loadable
-file *inside* that package.
-
-Resolution is an ordered probe (file-first, then package), so every literal
-path from #225 keeps its old behavior and only a bare name reaches the package
-machinery:
+Resolution is an ordered probe (file-first, then package), so only a bare
+package name reaches the package machinery:
 
 1. **Path-looking** (contains a separator, or ends in ``.so`` / ``.dylib`` /
    ``.dll`` / ``.pyd``) -- returned as a file path: made absolute against
    ``base`` when ``resolve_relative`` is set (config-file entries), else
-   verbatim (programmatic entries, mirroring the Rust builder).
+   verbatim (programmatic entries).
 2. **Bare name** -- a same-named local file under ``base`` *shadows* the
-   package (parity with #225's file-first probe); otherwise the package dir is
-   located via :func:`importlib.util.find_spec` and the current platform's
-   loadable is globbed from inside it. Zero matches and multiple matches are
-   both hard errors -- the caller must disambiguate with a literal path.
+   package; otherwise the package dir is located via
+   :func:`importlib.util.find_spec` and the current platform's loadable is
+   globbed from inside it. Zero matches and multiple matches are both hard
+   errors -- the caller must disambiguate with a literal path.
 """
 
 import glob as _glob
@@ -25,9 +19,8 @@ import importlib.util
 import os
 import sys
 
-# Suffixes that mark a value as "already a file path" (so package resolution is
-# never attempted) and, per platform, the globs used to find a loadable inside
-# a package directory.
+# Suffixes that mark a value as "already a file path", so package resolution
+# is never attempted.
 _LOADABLE_SUFFIXES = (".so", ".dylib", ".dll", ".pyd")
 
 
@@ -73,8 +66,6 @@ def _resolve_package(name):
             matches.update(_glob.glob(os.path.join(d, "**", pat), recursive=True))
     found = sorted(matches)
 
-    # Exactly one loadable resolves; unpacking (rather than a guarded
-    # subscript) makes the zero- and multiple-match failures each observable.
     try:
         (single,) = found
     except ValueError:

{dirsql-0.3.70/packages/rust → dirsql-0.3.72}/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.72}/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.72"
 edition.workspace = true
 publish = false
 readme = "README.md"

{dirsql-0.3.70 → dirsql-0.3.72}/packages/python/conftest.py

@@ -1,15 +1,9 @@
 """Stub the compiled `_dirsql` extension for unit tests that don't need it.
 
-`cli_test.py` exercises the pure-Python launcher; it must be runnable
-without `maturin develop` having built the PyO3 extension. We stub the
-missing module here (rather than in the test file) so the stub is in
-place before pytest imports `dirsql.__init__`, which transitively
-imports real types from `dirsql._dirsql`.
-
-The stub is installed ONLY when the real extension can't be imported.
-When `maturin develop` has been run (as in CI), the real extension wins
-and tests that depend on it — `_async_test.py`, the integration suites —
-see the real bindings.
+Must live here (not in a test file) so the stub is in place before pytest
+imports `dirsql.__init__`, which imports real types from `dirsql._dirsql`.
+Installed only when the real extension can't be imported; when `maturin
+develop` has been run, the real bindings win.
 """
 
 from __future__ import annotations

{dirsql-0.3.70 → dirsql-0.3.72}/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.72}/packages/python/e2e-attestation.json

@@ -1,6 +1,6 @@
 {
   "command": "uv run python -m pytest tests/e2e/ -x -q",
-  "ran_at": 1783387386,
+  "ran_at": 1783420501,
   "exit_code": 0,
-  "commit": "a9cf031533c564bf43c77d893745f9e85fed059f"
+  "commit": "fe9d09208be0b3c6084d9b916a41403d5822d096"
 }

{dirsql-0.3.70 → dirsql-0.3.72}/packages/python/src/lib.rs

@@ -20,8 +20,6 @@ mod python {
     use std::path::PathBuf;
     use std::time::Duration;
 
-    // -- Public PyO3 classes ------------------------------------------------
-
     /// A table definition. Mirrors `dirsql::Table` but holds a Python
     /// callable for `extract`.
     #[pyclass(name = "Table", frozen)]
@@ -34,15 +32,11 @@ mod python {
         extract: Py<PyAny>,
         #[pyo3(get)]
         strict: bool,
-        /// Parsed table name (from `ddl`), or `None` if the DDL doesn't
-        /// match `CREATE TABLE <name> (...)`. Computed once at construction
-        /// via `dirsql::db::parse_table_name` so the `dirsql interpret`
-        /// dispatcher (#196) and other consumers share the core's single
-        /// source of truth instead of re-parsing DDL. We return `None`
-        /// rather than raising at construction so `DirSQL.ready()` keeps
-        /// surfacing malformed DDLs as the loud failure path (the Rust
-        /// core's `DirSqlError::Ddl`); callers that care about the name
-        /// before that point can check `t.name is None` themselves.
+        /// Parsed table name (from `ddl`) via `dirsql::db::parse_table_name`,
+        /// or `None` if the DDL doesn't match `CREATE TABLE <name> (...)`.
+        /// `None` rather than a construction error so `DirSQL.ready()` keeps
+        /// surfacing malformed DDLs as the loud failure path (the core's
+        /// `DirSqlError::Ddl`).
         #[pyo3(get)]
         name: Option<String>,
     }
@@ -64,11 +58,9 @@ mod python {
     }
 
     /// Marshals a Python `{"path": str, "entrypoint"?: str}` mapping from the
-    /// `extensions=` constructor argument into a [`dirsql::Extension`]. Mirrors
-    /// the `[[dirsql.extension]]` config-file fields and the Rust builder's
-    /// `Extension { path, entrypoint }`. Paths are taken verbatim (the
-    /// programmatic surface does not resolve relative paths), matching
-    /// `DirSQLBuilder::extensions`.
+    /// `extensions=` constructor argument into a [`dirsql::Extension`]. Paths
+    /// are taken verbatim; the programmatic surface does not resolve relative
+    /// paths.
     #[derive(FromPyObject)]
     struct PyExtensionSpec {
         #[pyo3(item)]
@@ -117,8 +109,8 @@ mod python {
         /// `suppress_config_extensions` skips the core's own loading of the
         /// config's `[[dirsql.extension]]` entries; the SDK sets it after
         /// resolving those entries itself (package names need `importlib`,
-        /// which the core lacks -- #313) and passing the resolved literal
-        /// paths via `extensions`, so the entries are not loaded twice.
+        /// which the core lacks) and passing the resolved literal paths via
+        /// `extensions`, so the entries are not loaded twice.
         #[new]
         #[pyo3(signature = (root=None, *, tables=None, ignore=None, config=None, persist=false, persist_path=None, extensions=None, suppress_config_extensions=false))]
         fn new(
@@ -205,8 +197,6 @@ mod python {
         }
     }
 
-    // -- Helpers ------------------------------------------------------------
-
     fn build_table(py: Python<'_>, t: &PyTable) -> Table {
         let extract_ref = t.extract.clone_ref(py);
         let mut table = Table::try_new(
@@ -260,10 +250,7 @@ mod python {
     /// Pure, GIL-free intermediate for a row event. [`row_event_to_plain`]
     /// builds it from a core [`RowEvent`] (unit-testable without a Python
     /// interpreter); [`row_event_to_py`] then marshals it into the
-    /// Python-facing [`PyRowEvent`] (the GIL step). Splitting the two keeps the
-    /// variant -> action / field-selection mapping testable at the unit tier,
-    /// mirroring the napi binding's pure `row_event_to_js`. The value-level
-    /// `Row -> PyDict` conversion stays GIL-bound (binding-tier covered).
+    /// Python-facing [`PyRowEvent`] (the GIL step).
     struct PlainRowEvent {
         table: Option<String>,
         action: &'static str,
@@ -406,8 +393,6 @@ mod python {
         }
     }
 
-    // -- Module registration ------------------------------------------------
-
     #[pymodule]
     #[pyo3(name = "_dirsql")]
     fn py_dirsql_module(m: &Bound<'_, PyModule>) -> PyResult<()> {

{dirsql-0.3.70 → dirsql-0.3.72}/packages/python/tests/conftest.py

@@ -15,7 +15,6 @@ def tmp_dir():
 @pytest.fixture
 def jsonl_dir(tmp_dir):
     """Create a temp dir with JSONL files for testing."""
-    # Create a simple JSONL file
     os.makedirs(os.path.join(tmp_dir, "comments", "abc"), exist_ok=True)
     os.makedirs(os.path.join(tmp_dir, "comments", "def"), exist_ok=True)
 

{dirsql-0.3.70 → dirsql-0.3.72}/packages/rust/benches/differ_bench.rs

@@ -46,7 +46,6 @@ fn bench_diff_single_line_change(c: &mut Criterion) {
     for count in [10, 100, 1000] {
         let old = make_rows(count);
         let mut new = old.clone();
-        // Change one row in the middle
         new[count / 2].insert("name".to_string(), Value::Text("CHANGED".to_string()));
         group.bench_with_input(BenchmarkId::from_parameter(count), &count, |b, _| {
             b.iter(|| {
@@ -62,7 +61,6 @@ fn bench_diff_append(c: &mut Criterion) {
     for count in [10, 100, 1000] {
         let old = make_rows(count);
         let mut new = old.clone();
-        // Append 10% more rows
         let extra = make_rows(count + count / 10);
         new.extend_from_slice(&extra[count..]);
         group.bench_with_input(BenchmarkId::from_parameter(count), &count, |b, _| {
@@ -78,7 +76,6 @@ fn bench_diff_full_replace(c: &mut Criterion) {
     let mut group = c.benchmark_group("differ/full_replace");
     for count in [10, 100, 1000] {
         let old = make_rows(count);
-        // Completely different rows trigger full replace
         let new: Vec<HashMap<String, Value>> = (0..count)
             .map(|i| {
                 HashMap::from([

{dirsql-0.3.70 → dirsql-0.3.72}/packages/rust/benches/scanner_bench.rs

@@ -7,7 +7,6 @@ use tempfile::TempDir;
 fn create_temp_tree(file_count: usize) -> TempDir {
     let dir = TempDir::new().unwrap();
     for i in 0..file_count {
-        // Distribute files across subdirectories
         let subdir = dir.path().join(format!("dir_{}", i % 10));
         fs::create_dir_all(&subdir).unwrap();
         fs::write(
@@ -16,7 +15,6 @@ fn create_temp_tree(file_count: usize) -> TempDir {
         )
         .unwrap();
     }
-    // Add some non-matching files
     for i in 0..file_count / 5 {
         fs::write(dir.path().join(format!("readme_{i}.md")), "# not matched").unwrap();
     }

{dirsql-0.3.70 → dirsql-0.3.72/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