dirsql 0.3.45__tar.gz → 0.3.47__tar.gz

{dirsql-0.3.45 → dirsql-0.3.47}/Cargo.lock

@@ -501,7 +501,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.3.45"
+version = "0.3.47"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.3.45 → dirsql-0.3.47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.45
+Version: 0.3.47
 Requires-Dist: pytest>=8 ; extra == 'dev'
 Requires-Dist: pytest-describe>=2 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'

{dirsql-0.3.45 → dirsql-0.3.47}/dirsql/_async.py

@@ -1,8 +1,10 @@
 """Async-by-default DirSQL wrapper."""
 
 import asyncio
+import os
 
 from dirsql._dirsql import DirSQL as _RustDirSQL
+from dirsql.resolve_extension import resolve_extension_path
 
 
 class _WatchStream:
@@ -91,13 +93,33 @@ class DirSQL:
                 config=self._config,
                 persist=self._persist,
                 persist_path=self._persist_path,
-                extensions=self._extensions,
+                extensions=self._resolved_extensions(),
             )
         except Exception as exc:
             self._init_error = exc
         finally:
             self._ready_event.set()
 
+    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
+        ``[[dirsql.extension]]`` entries are resolved by the Rust core, not here.
+        """
+        if not self._extensions:
+            return self._extensions
+        return [
+            {
+                "path": resolve_extension_path(
+                    e["path"], base=os.getcwd(), resolve_relative=False
+                ),
+                "entrypoint": e.get("entrypoint"),
+            }
+            for e in self._extensions
+        ]
+
     async def ready(self):
         """Wait until the initial scan is complete.
 

{dirsql-0.3.45 → dirsql-0.3.47}/dirsql/cli/main.py

@@ -10,6 +10,7 @@ import sys
 
 from .binary_path import binary_path
 from .is_windows import is_windows
+from .resolve_config_extensions import with_resolved_extensions
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -22,6 +23,14 @@ def main(argv: list[str] | None = None) -> int:
         print(f"dirsql: {exc}", file=sys.stderr)
         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).
+    try:
+        argv = with_resolved_extensions(argv)
+    except Exception as exc:
+        print(f"dirsql: {exc}", file=sys.stderr)
+        return 1
+
     if is_windows():
         completed = subprocess.run([binary, *argv])
         return completed.returncode

dirsql-0.3.47/dirsql/cli/resolve_config_extensions.py

@@ -0,0 +1,81 @@
+"""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, we resolve
+every one of its extensions here and pass 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``).
+
+Native-language configs (``.py`` / ``.js`` / ``.mjs`` / ``.cjs``) are untouched:
+the binary dispatches those to ``dirsql interpret``, whose handshake already
+carries resolved paths.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+
+from ..resolve_extension import is_bare_name, resolve_extension_path
+
+# Config extensions the binary dispatches to `dirsql interpret`; never
+# pre-resolved here (that path resolves via the handshake).
+_NATIVE_SUFFIXES = (".py", ".js", ".mjs", ".cjs")
+
+
+def _config_path_from_argv(argv: list[str]) -> str:
+    """The ``--config`` value (``--config X`` or ``--config=X``), or the default."""
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a == "--config":
+            return argv[i + 1] if i + 1 < len(argv) else ""
+        if a.startswith("--config="):
+            return a[len("--config=") :]
+        i += 1
+    return "./.dirsql.toml"
+
+
+def with_resolved_extensions(argv: list[str]) -> list[str]:
+    """Return ``argv`` plus ``--extension`` flags when the TOML config names an
+    extension by package name; otherwise return ``argv`` unchanged. Raises if a
+    package name cannot be resolved (the launcher surfaces a clean error)."""
+    if argv and argv[0] == "init":
+        return argv
+    config_path = _config_path_from_argv(argv)
+    if config_path.endswith(_NATIVE_SUFFIXES):
+        return argv
+    if not os.path.isfile(config_path):
+        return argv
+    try:
+        with open(config_path, "rb") as f:
+            doc = tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError):
+        # Leave a malformed / unreadable config for the binary to report.
+        return argv
+
+    cfg = doc.get("dirsql") or {}
+    entries = cfg.get("extension") or []
+    if not isinstance(entries, list) or not entries:
+        return argv
+    # Only intervene when at least one path is a bare package name; a config
+    # with only literal paths keeps the binary's existing behavior untouched.
+    if not any(
+        isinstance(e, dict)
+        and isinstance(e.get("path"), str)
+        and is_bare_name(e["path"])
+        for e in entries
+    ):
+        return argv
+
+    base = os.path.dirname(os.path.abspath(config_path))
+    flags: list[str] = []
+    for e in entries:
+        path = resolve_extension_path(e["path"], base=base, resolve_relative=True)
+        entrypoint = e.get("entrypoint")
+        flags.append("--extension")
+        flags.append(f"{path}::{entrypoint}" if isinstance(entrypoint, str) else path)
+    return [*argv, *flags]

dirsql-0.3.47/dirsql/resolve_extension.py

@@ -0,0 +1,106 @@
+"""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:
+
+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).
+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.
+"""
+
+import glob as _glob
+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.
+_LOADABLE_SUFFIXES = (".so", ".dylib", ".dll", ".pyd")
+
+
+def _platform_patterns():
+    """Loadable-file glob(s) for the current platform."""
+    if sys.platform == "darwin":
+        return ("*.dylib",)
+    if sys.platform == "win32":
+        return ("*.dll", "*.pyd")
+    return ("*.so",)
+
+
+def is_bare_name(path):
+    """True when ``path`` is a bare package name rather than a file path."""
+    if os.sep in path or (os.altsep and os.altsep in path):
+        return False
+    return not path.endswith(_LOADABLE_SUFFIXES)
+
+
+def _resolve_package(name):
+    """Locate ``name``'s package dir and glob its platform loadable file."""
+    try:
+        spec = importlib.util.find_spec(name)
+    except (ImportError, ValueError) as exc:
+        raise ValueError(
+            f"could not resolve extension package {name!r}: {exc}"
+        ) from exc
+    if spec is None:
+        raise ValueError(f"could not resolve extension package {name!r}: not installed")
+
+    dirs = list(spec.submodule_search_locations or [])
+    if not dirs and spec.origin and spec.origin not in ("built-in", "frozen"):
+        dirs.append(os.path.dirname(spec.origin))
+    if not dirs:
+        raise ValueError(
+            f"could not resolve extension package {name!r}: no package directory"
+        )
+
+    patterns = _platform_patterns()
+    matches = set()
+    for d in dirs:
+        for pat in patterns:
+            matches.update(_glob.glob(os.path.join(d, "**", pat), recursive=True))
+    found = sorted(matches)
+
+    pat_desc = " / ".join(patterns)
+    if not found:
+        raise ValueError(
+            f"no loadable extension file ({pat_desc}) found in package "
+            f"{name!r} (searched {', '.join(dirs)})"
+        )
+    if len(found) > 1:
+        raise ValueError(
+            f"multiple loadable extension files found in package {name!r}: "
+            f"{', '.join(found)}; disambiguate with a literal path"
+        )
+    return found[0]
+
+
+def resolve_extension_path(path, base, resolve_relative):
+    """Resolve an extension ``path`` to a concrete file.
+
+    ``base`` is the directory a relative path and the bare-name shadow probe
+    resolve against (a config file's parent dir, or the cwd for programmatic
+    entries). ``resolve_relative`` makes a relative path-looking value absolute
+    against ``base`` (config-file semantics); when false it is returned verbatim
+    (programmatic semantics).
+    """
+    if not is_bare_name(path):
+        if resolve_relative and not os.path.isabs(path):
+            return os.path.join(base, path)
+        return path
+    local = os.path.join(base, path)
+    if os.path.isfile(local):
+        return local
+    return _resolve_package(path)

{dirsql-0.3.45 → dirsql-0.3.47}/docs/api/index.md

@@ -77,7 +77,7 @@ In Python, the constructor starts scanning in a background thread and returns im
 - `tables` -- List of `Table` definitions. Each defines a SQLite table, a glob pattern, and an extract function.
 - `ignore` -- Optional list of glob patterns. Files matching any ignore pattern are skipped regardless of table globs.
 - `config` -- Optional path to a `.dirsql.toml` config file. Its `[[table]]` entries are appended to any programmatic `tables`; its `[dirsql].ignore` patterns are appended to any explicit `ignore`; its optional `[dirsql].root` supplies the root directory when `root` is not passed explicitly; its `[[dirsql.extension]]` entries are appended to any programmatic `extensions`.
-- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`; TypeScript: `{ path, entrypoint? }` objects). Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. Available in the Python, Rust, and TypeScript SDKs. See [Loading extensions](../cli/config.md#loading-extensions).
+- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`; TypeScript: `{ path, entrypoint? }` objects). A `path` is either a file path or a bare **package name**; a package name is resolved from the installed package (Python `importlib` / TypeScript `node_modules`, file-first, erroring on zero or multiple matches). This works on the Python/TypeScript constructor and CLI; the Rust binary and SDK are file-path-only. Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. See [Loading extensions](../cli/config.md#loading-extensions).
 
 ### Methods
 

{dirsql-0.3.45/packages/python → dirsql-0.3.47}/docs/cli/config.md

@@ -158,8 +158,11 @@ path       = "./ext/myext.dylib"
 entrypoint = "sqlite3_myext_init"
 ```
 
-- **`path`** — a path to the extension's shared library (`.so` / `.dylib` /
-  `.dll`). Relative paths resolve against the config file's parent directory.
+- **`path`** — the extension's shared library: either a file path (`.so` /
+  `.dylib` / `.dll`, relative to the config file's directory) or a bare
+  **package name**. A package name is resolved from the installed package when
+  run through the pip/npm `dirsql` CLI; the standalone Rust binary is
+  file-path-only.
 - **`entrypoint`** *(optional)* — the extension's init symbol. When omitted,
   SQLite derives a default from the filename; set it when that default does not
   match (for example, `sqlite-vec`'s entry point is `sqlite3_vec_init`).
@@ -242,6 +245,71 @@ other files' rows are indexed normally.
 See [Command execution](#command-execution) for the full contract (argv
 splitting, injection safety, cwd, environment, timeout, and output framing).
 
+### Rewriting queries (`pre-query`)
+
+The `pre-query` hook intercepts every incoming request and transforms it into
+the SQL that runs against the index. Because the hook owns SQL construction,
+`POST /query` can accept whatever shape you want — a natural-language question,
+a saved-query name, a templating DSL — and your command translates it to SQL
+before it runs. Unlike `on-file` (a per-`[[table]]` key), `pre-query` is a
+**server-wide** `[dirsql]` key: every query flows through it.
+
+```toml
+[dirsql]
+pre-query = "uv run python to_sql.py {args}"
+```
+
+With `pre-query` set, the **raw `POST /query` request body** is passed to the
+command as the `{args}` placeholder — a single, injection-safe argv token even
+though the body is untrusted. The command prints **plain-text SQL** on stdout
+(the last non-empty line is used); `dirsql` runs that SQL and returns rows
+exactly as it would for a normal query.
+
+| Placeholder | Value |
+|-------------|-------|
+| `{args}`    | The raw `POST /query` request body, verbatim, as one argv token. |
+
+When `pre-query` is **absent**, nothing changes: the request body is parsed as
+`{"sql": "…"}` JSON and executed — the [HTTP API](./http-api.md#post-query)
+default. Enabling the hook is fully backward compatible in reverse: remove the
+key and the `{"sql": …}` contract returns.
+
+**On failure** — a non-zero exit, a timeout, or a spawn error — the request
+returns `500 Internal Server Error` with the command's stderr tail in the JSON
+`error` body. The command runs in the config file's directory and is bounded by
+a fixed **30-second** timeout.
+
+#### The hook owns SQL safety
+
+Because the hook returns **plain SQL** (not a parameterized query), it is the
+**trusted component** that turns the untrusted request body into safe SQL. The
+`{args}` substitution keeps the body inert *as an argv token* — it can never
+break out into extra command arguments — but whatever SQL string the hook
+prints is executed as-is. Validate, escape, or parameterize **inside** the
+hook. This trade-off is intentional for v1: it keeps the contract a simple
+plain-text-SQL pipe and puts translation logic — and its safety — in your hook.
+
+Worked example — a hook that maps a saved-query name to SQL:
+
+```python
+# to_sql.py
+import sys
+
+QUERIES = {
+    "recent-posts": "SELECT title, author FROM posts ORDER BY _mtime DESC LIMIT 10",
+}
+name = sys.argv[1].strip() if len(sys.argv) > 1 else ""
+# Fall back to an empty result rather than trusting arbitrary input.
+print(QUERIES.get(name, "SELECT 1 WHERE 0"))
+```
+
+```bash
+curl -s http://localhost:7117/query -d 'recent-posts' | jq
+```
+
+See [Command execution](#command-execution) for the full contract (argv
+splitting, injection safety, cwd, environment, timeout, and output framing).
+
 ### Full Example
 
 ```toml
@@ -263,8 +331,8 @@ glob = "logs/*.csv"
 
 ## Command execution
 
-Config keys that run an external command — today `on-file`, with more events to
-follow — share one execution contract:
+Config keys that run an external command — today `on-file` and `pre-query`,
+with more events to follow — share one execution contract:
 
 - **argv, not a shell.** The command string is split into an argv with
   shell-like quoting (spaces separate arguments; quotes group them), but **no

{dirsql-0.3.45 → dirsql-0.3.47}/docs/cli/http-api.md

@@ -35,6 +35,15 @@ On error, the server returns a non-2xx status with a JSON body:
 
 Malformed SQL returns `400`. An unreadable or malformed config returns `503`; a *missing* config is not an error — the server serves the default `files` table.
 
+::: tip `pre-query` changes the body contract
+When [`[dirsql].pre-query`](./config.md#rewriting-queries-pre-query) is
+configured, the request body is **not** parsed as `{"sql": …}`. Instead the raw
+body is passed verbatim to the hook command, which prints the SQL to run. A hook
+that fails (non-zero exit, timeout, or spawn error) returns `500` with the
+command's stderr tail. With no `pre-query` key, the `{"sql": …}` contract above
+applies.
+:::
+
 ```bash
 curl -s http://localhost:7117/query \
   -H 'content-type: application/json' \

{dirsql-0.3.45 → dirsql-0.3.47}/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.45"
+version = "0.3.47"
 edition.workspace = true
 publish = false
 readme = "README.md"

{dirsql-0.3.45/packages/rust → dirsql-0.3.47/packages/python}/docs/api/index.md

@@ -77,7 +77,7 @@ In Python, the constructor starts scanning in a background thread and returns im
 - `tables` -- List of `Table` definitions. Each defines a SQLite table, a glob pattern, and an extract function.
 - `ignore` -- Optional list of glob patterns. Files matching any ignore pattern are skipped regardless of table globs.
 - `config` -- Optional path to a `.dirsql.toml` config file. Its `[[table]]` entries are appended to any programmatic `tables`; its `[dirsql].ignore` patterns are appended to any explicit `ignore`; its optional `[dirsql].root` supplies the root directory when `root` is not passed explicitly; its `[[dirsql.extension]]` entries are appended to any programmatic `extensions`.
-- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`; TypeScript: `{ path, entrypoint? }` objects). Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. Available in the Python, Rust, and TypeScript SDKs. See [Loading extensions](../cli/config.md#loading-extensions).
+- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`; TypeScript: `{ path, entrypoint? }` objects). A `path` is either a file path or a bare **package name**; a package name is resolved from the installed package (Python `importlib` / TypeScript `node_modules`, file-first, erroring on zero or multiple matches). This works on the Python/TypeScript constructor and CLI; the Rust binary and SDK are file-path-only. Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. See [Loading extensions](../cli/config.md#loading-extensions).
 
 ### Methods
 

{dirsql-0.3.45 → dirsql-0.3.47/packages/python}/docs/cli/config.md

@@ -158,8 +158,11 @@ path       = "./ext/myext.dylib"
 entrypoint = "sqlite3_myext_init"
 ```
 
-- **`path`** — a path to the extension's shared library (`.so` / `.dylib` /
-  `.dll`). Relative paths resolve against the config file's parent directory.
+- **`path`** — the extension's shared library: either a file path (`.so` /
+  `.dylib` / `.dll`, relative to the config file's directory) or a bare
+  **package name**. A package name is resolved from the installed package when
+  run through the pip/npm `dirsql` CLI; the standalone Rust binary is
+  file-path-only.
 - **`entrypoint`** *(optional)* — the extension's init symbol. When omitted,
   SQLite derives a default from the filename; set it when that default does not
   match (for example, `sqlite-vec`'s entry point is `sqlite3_vec_init`).
@@ -242,6 +245,71 @@ other files' rows are indexed normally.
 See [Command execution](#command-execution) for the full contract (argv
 splitting, injection safety, cwd, environment, timeout, and output framing).
 
+### Rewriting queries (`pre-query`)
+
+The `pre-query` hook intercepts every incoming request and transforms it into
+the SQL that runs against the index. Because the hook owns SQL construction,
+`POST /query` can accept whatever shape you want — a natural-language question,
+a saved-query name, a templating DSL — and your command translates it to SQL
+before it runs. Unlike `on-file` (a per-`[[table]]` key), `pre-query` is a
+**server-wide** `[dirsql]` key: every query flows through it.
+
+```toml
+[dirsql]
+pre-query = "uv run python to_sql.py {args}"
+```
+
+With `pre-query` set, the **raw `POST /query` request body** is passed to the
+command as the `{args}` placeholder — a single, injection-safe argv token even
+though the body is untrusted. The command prints **plain-text SQL** on stdout
+(the last non-empty line is used); `dirsql` runs that SQL and returns rows
+exactly as it would for a normal query.
+
+| Placeholder | Value |
+|-------------|-------|
+| `{args}`    | The raw `POST /query` request body, verbatim, as one argv token. |
+
+When `pre-query` is **absent**, nothing changes: the request body is parsed as
+`{"sql": "…"}` JSON and executed — the [HTTP API](./http-api.md#post-query)
+default. Enabling the hook is fully backward compatible in reverse: remove the
+key and the `{"sql": …}` contract returns.
+
+**On failure** — a non-zero exit, a timeout, or a spawn error — the request
+returns `500 Internal Server Error` with the command's stderr tail in the JSON
+`error` body. The command runs in the config file's directory and is bounded by
+a fixed **30-second** timeout.
+
+#### The hook owns SQL safety
+
+Because the hook returns **plain SQL** (not a parameterized query), it is the
+**trusted component** that turns the untrusted request body into safe SQL. The
+`{args}` substitution keeps the body inert *as an argv token* — it can never
+break out into extra command arguments — but whatever SQL string the hook
+prints is executed as-is. Validate, escape, or parameterize **inside** the
+hook. This trade-off is intentional for v1: it keeps the contract a simple
+plain-text-SQL pipe and puts translation logic — and its safety — in your hook.
+
+Worked example — a hook that maps a saved-query name to SQL:
+
+```python
+# to_sql.py
+import sys
+
+QUERIES = {
+    "recent-posts": "SELECT title, author FROM posts ORDER BY _mtime DESC LIMIT 10",
+}
+name = sys.argv[1].strip() if len(sys.argv) > 1 else ""
+# Fall back to an empty result rather than trusting arbitrary input.
+print(QUERIES.get(name, "SELECT 1 WHERE 0"))
+```
+
+```bash
+curl -s http://localhost:7117/query -d 'recent-posts' | jq
+```
+
+See [Command execution](#command-execution) for the full contract (argv
+splitting, injection safety, cwd, environment, timeout, and output framing).
+
 ### Full Example
 
 ```toml
@@ -263,8 +331,8 @@ glob = "logs/*.csv"
 
 ## Command execution
 
-Config keys that run an external command — today `on-file`, with more events to
-follow — share one execution contract:
+Config keys that run an external command — today `on-file` and `pre-query`,
+with more events to follow — share one execution contract:
 
 - **argv, not a shell.** The command string is split into an argv with
   shell-like quoting (spaces separate arguments; quotes group them), but **no

{dirsql-0.3.45/packages/rust → dirsql-0.3.47/packages/python}/docs/cli/http-api.md

@@ -35,6 +35,15 @@ On error, the server returns a non-2xx status with a JSON body:
 
 Malformed SQL returns `400`. An unreadable or malformed config returns `503`; a *missing* config is not an error — the server serves the default `files` table.
 
+::: tip `pre-query` changes the body contract
+When [`[dirsql].pre-query`](./config.md#rewriting-queries-pre-query) is
+configured, the request body is **not** parsed as `{"sql": …}`. Instead the raw
+body is passed verbatim to the hook command, which prints the SQL to run. A hook
+that fails (non-zero exit, timeout, or spawn error) returns `500` with the
+command's stderr tail. With no `pre-query` key, the `{"sql": …}` contract above
+applies.
+:::
+
 ```bash
 curl -s http://localhost:7117/query \
   -H 'content-type: application/json' \

{dirsql-0.3.45 → dirsql-0.3.47}/packages/python/e2e-attestation.json

@@ -1,6 +1,6 @@
 {
   "command": "uv run python -m pytest tests/e2e/ -x -q",
-  "ran_at": 1782833107,
+  "ran_at": 1782996616,
   "exit_code": 0,
-  "commit": "07bd37825c22f9ad73153d70fc65c9e3c92f855e"
+  "commit": "19cf2e30ef5bff8fe5e77b2c59fd54ca0fc46575"
 }

{dirsql-0.3.45/packages/python → dirsql-0.3.47/packages/rust}/docs/api/index.md

@@ -77,7 +77,7 @@ In Python, the constructor starts scanning in a background thread and returns im
 - `tables` -- List of `Table` definitions. Each defines a SQLite table, a glob pattern, and an extract function.
 - `ignore` -- Optional list of glob patterns. Files matching any ignore pattern are skipped regardless of table globs.
 - `config` -- Optional path to a `.dirsql.toml` config file. Its `[[table]]` entries are appended to any programmatic `tables`; its `[dirsql].ignore` patterns are appended to any explicit `ignore`; its optional `[dirsql].root` supplies the root directory when `root` is not passed explicitly; its `[[dirsql.extension]]` entries are appended to any programmatic `extensions`.
-- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`; TypeScript: `{ path, entrypoint? }` objects). Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. Available in the Python, Rust, and TypeScript SDKs. See [Loading extensions](../cli/config.md#loading-extensions).
+- `extensions` -- Optional SQLite extensions to load onto the connection at startup, before any table DDL (enable → load → disable, so the SQL `load_extension()` function is never left exposed). Each entry pairs a shared-library `path` with an optional `entrypoint` init-symbol override (Python: `{ "path", "entrypoint"? }` dicts; Rust: `Extension { path, entrypoint }`; TypeScript: `{ path, entrypoint? }` objects). A `path` is either a file path or a bare **package name**; a package name is resolved from the installed package (Python `importlib` / TypeScript `node_modules`, file-first, erroring on zero or multiple matches). This works on the Python/TypeScript constructor and CLI; the Rust binary and SDK are file-path-only. Programmatic entries load first, then any `[[dirsql.extension]]` from `config`. See [Loading extensions](../cli/config.md#loading-extensions).
 
 ### Methods
 

{dirsql-0.3.45 → dirsql-0.3.47}/packages/rust/docs/cli/config.md

@@ -158,8 +158,11 @@ path       = "./ext/myext.dylib"
 entrypoint = "sqlite3_myext_init"
 ```
 
-- **`path`** — a path to the extension's shared library (`.so` / `.dylib` /
-  `.dll`). Relative paths resolve against the config file's parent directory.
+- **`path`** — the extension's shared library: either a file path (`.so` /
+  `.dylib` / `.dll`, relative to the config file's directory) or a bare
+  **package name**. A package name is resolved from the installed package when
+  run through the pip/npm `dirsql` CLI; the standalone Rust binary is
+  file-path-only.
 - **`entrypoint`** *(optional)* — the extension's init symbol. When omitted,
   SQLite derives a default from the filename; set it when that default does not
   match (for example, `sqlite-vec`'s entry point is `sqlite3_vec_init`).
@@ -242,6 +245,71 @@ other files' rows are indexed normally.
 See [Command execution](#command-execution) for the full contract (argv
 splitting, injection safety, cwd, environment, timeout, and output framing).
 
+### Rewriting queries (`pre-query`)
+
+The `pre-query` hook intercepts every incoming request and transforms it into
+the SQL that runs against the index. Because the hook owns SQL construction,
+`POST /query` can accept whatever shape you want — a natural-language question,
+a saved-query name, a templating DSL — and your command translates it to SQL
+before it runs. Unlike `on-file` (a per-`[[table]]` key), `pre-query` is a
+**server-wide** `[dirsql]` key: every query flows through it.
+
+```toml
+[dirsql]
+pre-query = "uv run python to_sql.py {args}"
+```
+
+With `pre-query` set, the **raw `POST /query` request body** is passed to the
+command as the `{args}` placeholder — a single, injection-safe argv token even
+though the body is untrusted. The command prints **plain-text SQL** on stdout
+(the last non-empty line is used); `dirsql` runs that SQL and returns rows
+exactly as it would for a normal query.
+
+| Placeholder | Value |
+|-------------|-------|
+| `{args}`    | The raw `POST /query` request body, verbatim, as one argv token. |
+
+When `pre-query` is **absent**, nothing changes: the request body is parsed as
+`{"sql": "…"}` JSON and executed — the [HTTP API](./http-api.md#post-query)
+default. Enabling the hook is fully backward compatible in reverse: remove the
+key and the `{"sql": …}` contract returns.
+
+**On failure** — a non-zero exit, a timeout, or a spawn error — the request
+returns `500 Internal Server Error` with the command's stderr tail in the JSON
+`error` body. The command runs in the config file's directory and is bounded by
+a fixed **30-second** timeout.
+
+#### The hook owns SQL safety
+
+Because the hook returns **plain SQL** (not a parameterized query), it is the
+**trusted component** that turns the untrusted request body into safe SQL. The
+`{args}` substitution keeps the body inert *as an argv token* — it can never
+break out into extra command arguments — but whatever SQL string the hook
+prints is executed as-is. Validate, escape, or parameterize **inside** the
+hook. This trade-off is intentional for v1: it keeps the contract a simple
+plain-text-SQL pipe and puts translation logic — and its safety — in your hook.
+
+Worked example — a hook that maps a saved-query name to SQL:
+
+```python
+# to_sql.py
+import sys
+
+QUERIES = {
+    "recent-posts": "SELECT title, author FROM posts ORDER BY _mtime DESC LIMIT 10",
+}
+name = sys.argv[1].strip() if len(sys.argv) > 1 else ""
+# Fall back to an empty result rather than trusting arbitrary input.
+print(QUERIES.get(name, "SELECT 1 WHERE 0"))
+```
+
+```bash
+curl -s http://localhost:7117/query -d 'recent-posts' | jq
+```
+
+See [Command execution](#command-execution) for the full contract (argv
+splitting, injection safety, cwd, environment, timeout, and output framing).
+
 ### Full Example
 
 ```toml
@@ -263,8 +331,8 @@ glob = "logs/*.csv"
 
 ## Command execution
 
-Config keys that run an external command — today `on-file`, with more events to
-follow — share one execution contract:
+Config keys that run an external command — today `on-file` and `pre-query`,
+with more events to follow — share one execution contract:
 
 - **argv, not a shell.** The command string is split into an argv with
   shell-like quoting (spaces separate arguments; quotes group them), but **no