dirsql 0.4.14__tar.gz → 0.4.16__tar.gz

{dirsql-0.4.14 → dirsql-0.4.16}/Cargo.lock

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

{dirsql-0.4.14 → dirsql-0.4.16}/PKG-INFO

@@ -1,7 +1,8 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.4.14
+Version: 0.4.16
 Requires-Dist: tomli>=2 ; python_full_version < '3.11'
+Requires-Dist: bin-shim>=0.1
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index
 Author: Kevin Scott

dirsql-0.4.16/dirsql/cli/main.py

@@ -0,0 +1,66 @@
+"""Console-script entry point. Runs the CLI in-process through the compiled
+extension module — the same `_dirsql` the SDK imports — so the wheel ships one
+copy of the core instead of a `.so` plus a bundled binary (#738).
+
+All argv is forwarded transparently to the core, which owns subcommand
+dispatch; the launcher only prepends what the core cannot work out for itself
+(plugin config fragments, resolved extension paths).
+"""
+
+from __future__ import annotations
+
+import signal
+import sys
+
+from bin_shim import main as run_in_process
+
+from .discover_plugins.with_discovered_plugins import with_discovered_plugins
+from .resolve_config_extensions import with_resolved_extensions
+
+
+def _absorb_interrupt(*_args: object) -> None:
+    """Let the core's own shutdown decide the exit code on SIGINT.
+
+    signal-hook (which tokio uses) *chains*: it runs tokio's handler — which
+    drives `dirsql server`'s graceful shutdown, after which `run_cli` returns
+    0 — and then whatever handler was installed before it. CPython's default
+    is `default_int_handler`, which raises `KeyboardInterrupt`; that lands
+    after `run_cli` has already returned 0 and turns a clean shutdown into a
+    130. This handler occupies that slot without raising, so the core's exit
+    code is the one that survives, exactly as it does when the CLI is its own
+    process.
+
+    A signal arriving when the core is NOT handling signals still terminates:
+    `run_cli` is only reached with this installed, and it returns promptly for
+    every non-server command.
+    """
+
+
+def with_core_owned_signals(handler=signal.signal):
+    """Install `_absorb_interrupt` for SIGINT and return the prior handler."""
+    return handler(signal.SIGINT, _absorb_interrupt)
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    # Discover installed plugins (CLI only) and inject their config fragments as
+    # `-c` flags before resolving extensions; then resolve any package-name
+    # extensions in a TOML config here (the core can't) as `--extension`
+    # flags. Both are no-ops when nothing applies.
+    try:
+        argv = with_discovered_plugins(argv)
+        argv = with_resolved_extensions(argv)
+    except Exception as exc:
+        print(f"dirsql: {exc}", file=sys.stderr)
+        return 1
+
+    previous = with_core_owned_signals()
+    try:
+        return run_in_process(argv=argv, module="dirsql._dirsql")
+    except Exception as exc:
+        print(f"dirsql: {exc}", file=sys.stderr)
+        return 1
+    finally:
+        signal.signal(signal.SIGINT, previous)

{dirsql-0.4.14 → dirsql-0.4.16}/docs/.vitepress/config.ts

@@ -54,7 +54,6 @@ export default defineConfig({
             { text: 'Derive columns from file paths', link: '/howto/columns-from-paths' },
             { text: 'Extract rows from file contents', link: '/howto/extract-from-contents' },
             { text: 'Parse your files into columns', link: '/howto/parse-files-into-columns' },
-            { text: 'Search documents by meaning', link: '/howto/search-by-meaning' },
             { text: "Skip files you don't want indexed", link: '/howto/skip-files' },
             { text: 'Load a SQLite extension', link: '/howto/load-extension' },
             { text: 'Keep the index across restarts', link: '/howto/persist' },

{dirsql-0.4.14/packages/rust → dirsql-0.4.16}/docs/howto/extract-from-contents.md

@@ -79,8 +79,6 @@ SQLite value mapping is under
 
 - The command re-runs on every startup and on every change to a matched
   file. If it is expensive, [keep the index across restarts](./persist.md).
-- The flagship use of `on-file` — computing embeddings — is
-  [Search documents by meaning](./search-by-meaning.md).
 - Embedding `dirsql` in a program instead? The SDK's `on_file` callback
   fills the same role in-process — see
   [Embed `dirsql` in your application](./embed.md).

{dirsql-0.4.14/packages/rust → dirsql-0.4.16}/docs/howto/load-extension.md

@@ -85,5 +85,3 @@ interpreter to resolve package names with
 - Embedding `dirsql` in a program? The SDK constructor takes the same
   specs via its `extensions` parameter
   ([SDK reference](../reference/sdk.md#constructor)).
-- The payoff use case — `sqlite-vec` powering semantic search — is
-  [Search documents by meaning](./search-by-meaning.md).

{dirsql-0.4.14/packages/rust → dirsql-0.4.16}/docs/howto/write-a-plugin.md

@@ -24,8 +24,7 @@ dirsql-embeddings/
     └── dirsql_embeddings/
         ├── __init__.py
         ├── dirsql.toml       # the config fragment
-        ├── embed.py          # on-file hook
-        └── search.py         # pre-query hook
+        └── embed.py          # on-file hook
 ```
 
 The entry point maps a **source label** (the name) to the **module that
@@ -55,8 +54,7 @@ structurally **identical to a user config**. It may declare
 [`[[table]]`](../reference/config.md#table) (with
 [`on-file`](../reference/hooks.md#on-file)),
 [`[[dirsql.extension]]`](../reference/config.md#dirsql-extension),
-[`ignore`](../reference/config.md#dirsql-keys),
-[`pre-query`/`post-query`](../reference/hooks.md#pre-query), and
+[`ignore`](../reference/config.md#dirsql-keys), and
 [`hook-timeout`](../reference/hooks.md#timeout).
 
 There are **no plugin-specific keys and no plugin-specific restrictions**. The
@@ -96,17 +94,14 @@ matter most for a published plugin:
 ## Worked example: an embeddings plugin
 
 Here is the whole plugin — vector search over a directory of notes, buildable
-in about fifty lines. It composes the same three pieces as
-[Search documents by meaning](./search-by-meaning.md): the
+in about forty lines. It composes two pieces: the
 [`sqlite-vec`](https://github.com/asg017/sqlite-vec) extension for the
-distance math, an `on-file` command to embed each file, and a `pre-query`
-command to embed the question.
+distance math, and an `on-file` command to embed each file.
 
 The fragment, `src/dirsql_embeddings/dirsql.toml`:
 
 ```toml
 [dirsql]
-pre-query    = "uv run --with model2vec python search.py {args}"
 hook-timeout = 300   # headroom for the first-run model download
 
 [[dirsql.extension]]
@@ -140,46 +135,23 @@ row = {"path": os.path.relpath(path, root), "text": text,
 print(json.dumps([row]))
 ```
 
-`search.py` turns a `{"q": "..."}` request body into nearest-neighbor SQL:
-
-```python
-"""Turn a {"q": "..."} request body into a nearest-neighbor SQL query."""
-import json
-import sys
-
-from model2vec import StaticModel
-
-body = json.loads(sys.argv[1])
-model = StaticModel.from_pretrained("minishlab/potion-base-8M")
-vector = model.encode([body["q"]])[0]
-needle = json.dumps([round(float(x), 6) for x in vector])
-print(
-    "SELECT path, ROUND(vec_distance_cosine(embedding, '%s'), 3) AS distance "
-    "FROM notes ORDER BY distance LIMIT 3" % needle
-)
-```
-
-::: warning The hook owns SQL safety
-Whatever SQL `pre-query` prints is executed as-is. Here the interpolated
-value is a numeric vector the script itself produced; never splice raw request
-text into SQL. See [`pre-query`](../reference/hooks.md#pre-query).
-:::
-
-The relative `embed.py` / `search.py` above resolve against the fragment
-directory, which is convenient during development. For a published plugin,
-promote them to console scripts (`[project.scripts]` → `embed-file`,
-`embed-search`) so the commands carry their own interpreter and dependencies
-and no longer depend on `uv run --with`.
+The relative `embed.py` above resolves against the fragment directory, which
+is convenient during development. For a published plugin, promote it to a
+console script (`[project.scripts]` → `embed-file`) so the command carries
+its own interpreter and dependencies and no longer depends on
+`uv run --with`.
 
 Once the package is installed alongside the launcher, its `notes` table is
 queryable with no config edits:
 
 ```bash
-uvx --with dirsql-embeddings dirsql query '{"q": "how do I cook pasta?"}'
+uvx --with dirsql-embeddings dirsql query \
+  "SELECT path FROM notes ORDER BY vec_distance_cosine(embedding, '[0.1, ...]') LIMIT 3"
 ```
 
 The launcher discovers the installed plugin, composes its fragment, and the
-`pre-query` hook turns the question into vector-distance SQL.
+`notes` table (with `vec_distance_cosine()` from the loaded extension) is
+available to the query.
 
 ## SDK-style convention: expose the config
 
@@ -230,8 +202,8 @@ Discovery is deliberately narrow. Know exactly who does what:
   [convention above](#sdk-style-convention-expose-the-config)).
 - **Name collisions are a hard error.** Because fragments compose like any
   [multiple configs](../reference/config.md#composing-multiple-configs), two
-  plugins (or a plugin and your config) defining a table of the same name — or
-  the same query hook — fail loudly, naming the conflict. It is never a silent
+  plugins (or a plugin and your config) defining a table of the same name
+  fail loudly, naming the conflict. It is never a silent
   last-writer-wins.
 
 ::: warning Config flags are subcommand-local

{dirsql-0.4.14/packages/rust → dirsql-0.4.16}/docs/plugins.md

@@ -22,10 +22,6 @@ question into nearest-neighbor SQL over that table, ranked by
 [PyPI](https://pypi.org/project/dirsql-plugin-embeddings/) ·
 [Source](https://github.com/thekevinscott/dirsql/tree/main/plugins/dirsql-plugin-embeddings)
 
-It is the packaged form of the
-[Search documents by meaning](./howto/search-by-meaning.md) how-to, with that
-guide's local `model2vec` model swapped for a hosted endpoint.
-
 ### Install and launch
 
 The plugin is a normal PyPI package; installing it alongside `dirsql` is the
@@ -43,29 +39,10 @@ uvx --with dirsql-plugin-embeddings dirsql server
 
 The launcher finds the package through its `dirsql` entry point and injects
 the shipped `dirsql.toml` fragment as an ordinary `-c` flag, composed after
-your own configs. The fragment declares three things:
-
-- the `sqlite-vec` extension (resolved from the installed `sqlite-vec`
-  package, which the plugin depends on), for `vec_distance_cosine()`;
-- the `documents` table (`path`, `text`, `embedding`), whose
-  [`on-file`](./reference/hooks.md#on-file) hook embeds each matched file at
-  index time;
-- a [`pre-query`](./reference/hooks.md#pre-query) hook that embeds each
-  incoming question and emits the nearest-neighbor SQL, plus a 300-second
-  [`hook-timeout`](./reference/config.md#dirsql-keys) so slow embedding calls
-  don't hit the 30-second default.
-
-Ask a question as a `{"q": …}` body — via `POST /query` against the server,
-or in one shot from the shell:
-
-```sh
-uvx --with dirsql-plugin-embeddings \
-  dirsql query '{"q": "how do I cook spaghetti?"}'
-# [{"path":"pasta.md","distance":0.113}, …]
-```
-
-The result is the three nearest documents, closest first. Discovery can be
-turned off per-invocation with `--no-plugin` or `DIRSQL_NO_PLUGIN=1`
+your own configs. The fragment declares the `sqlite-vec` extension (resolved
+from the installed `sqlite-vec` package, which the plugin depends on), so
+`vec_distance_cosine()` is callable in queries. Discovery can be turned off
+per-invocation with `--no-plugin` or `DIRSQL_NO_PLUGIN=1`
 ([reference](./reference/cli.md#plugins)).
 
 ### Configuration

{dirsql-0.4.14/packages/python → dirsql-0.4.16}/docs/reference/cli.md

@@ -78,8 +78,8 @@ Config flags are subcommand-local: pass them after `server`
 
 - Per-query timeout: **30 seconds**. A query exceeding it returns
   `408 Request Timeout`.
-- Command hooks (`on-file`, `pre-query`, `post-query`) default to a
-  **30-second** timeout each, overridable with the config key
+- `on-file` command hooks default to a **30-second** timeout each,
+  overridable with the config key
   [`[dirsql].hook-timeout`](./config.md#dirsql-keys).
 
 ### Configless mode
@@ -166,8 +166,7 @@ uses**, so behavior is identical to `POST /query` by construction:
   (`--persist=/path`) so it does not swallow the SQL argument.
 - **`--no-ignore`** is honored: path-tables in the query scan files a
   `.gitignore` would hide. See [Skip rules](./path-tables.md#skip-rules).
-- **Hooks** ([`pre-query`](./hooks.md#pre-query) /
-  [`post-query`](./hooks.md#post-query)) and the
+- **`on-file` hooks** 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

{dirsql-0.4.14/packages/rust → dirsql-0.4.16}/docs/reference/config.md

@@ -23,9 +23,7 @@ the config file's location. See [`--config`](./cli.md#flags).
 | Key | Type | Default | Description |
 |---|---|---|---|
 | `ignore` | array of strings | `[]` | Glob patterns matched against root-relative paths. Matched files are skipped entirely — excluded from the initial scan and from watch events. |
-| `pre-query` | string | none | Server-wide command hook: the raw `POST /query` request body is passed to this command as `{args}`, and the plain-text SQL it prints is executed instead of parsing the body as `{"sql": …}`. CLI server only; the SDKs ignore it. Must be non-empty. See [Command hooks](./hooks.md#pre-query). |
-| `post-query` | string | none | Server-wide command hook: each successful `POST /query` result set is handed to this command (as a JSON array on stdin, and as `{args}` up to 96 KiB), and the JSON body it prints is returned instead of the bare row array. CLI server only; the SDKs ignore it. Must be non-empty. See [Command hooks](./hooks.md#post-query). |
-| `hook-timeout` | integer (seconds) | `30` | One global per-run timeout for every command hook — `on-file`, `pre-query`, and `post-query` alike. Positive whole seconds; zero and negative values are a config error. See [Command hooks](./hooks.md#timeout). |
+| `hook-timeout` | integer (seconds) | `30` | One global per-run timeout for every `on-file` command hook run. Positive whole seconds; zero and negative values are a config error. See [Command hooks](./hooks.md#timeout). |
 
 The top-level `.dirsql/` directory under the root is always excluded from
 scanning, whether or not it appears in `ignore` — it is reserved for
@@ -147,15 +145,10 @@ The configs load and merge in **argv order**:
 
 - **`[[table]]`, `ignore`, and `[[dirsql.extension]]` entries accumulate** across
   all configs, in order.
-- **Each config's `on-file`, `pre-query`, and `post-query` hooks run from that
-  config file's own directory**, under that config's own
-  [`hook-timeout`](#dirsql-keys) — so a relative command like
-  `on-file = "sh ./extract.sh"` resolves against the config that declared it,
-  wherever it lives.
-- **`pre-query` / `post-query` hooks chain FIFO**: the request body flows through
-  each `pre-query` stage in order to the final SQL, and the result rows flow
-  through each `post-query` stage to the response. See the
-  [hook contract](./hooks.md).
+- **Each config's `on-file` hooks run from that config file's own
+  directory**, under that config's own [`hook-timeout`](#dirsql-keys) — so a
+  relative command like `on-file = "sh ./extract.sh"` resolves against the
+  config that declared it, wherever it lives.
 - Each config is **validated on its own** (the [parse errors](#parse-errors)
   below apply per file). There is no cross-file merge validation, with one
   structural exception: **two configs defining a table of the same name is an
@@ -181,7 +174,6 @@ SDKs raise/reject) when:
   > `[[table]] '**/*.md' has no on-file hook, so every row would be all-NULL. Add an `on-file` hook that emits the columns, or, for stat columns with no code, query the path directly: `FROM './'``
 
 - A `[[dirsql.extension]]` entry omits `path`, or `path` is empty.
-- `pre-query` or `post-query` is present but empty/whitespace.
 - `hook-timeout` is zero or negative.
 
 ## Full example
@@ -189,8 +181,6 @@ SDKs raise/reject) when:
 ```toml
 [dirsql]
 ignore = ["node_modules/**", ".git/**", "dist/**"]
-pre-query = "uv run python to_sql.py {args}"
-post-query = "jq -c '{results: .}'"
 hook-timeout = 120
 
 [[dirsql.extension]]

{dirsql-0.4.14/packages/rust → dirsql-0.4.16}/docs/reference/hooks.md

@@ -1,8 +1,8 @@
 # Command hooks
 
-Three [config keys](./config.md) run an external command: `on-file` (per
-`[[table]]`), and the server-wide `pre-query` and `post-query` (under
-`[dirsql]`; CLI server only). All three share one execution contract.
+The `on-file` [config key](./config.md) (per `[[table]]`, also available as
+the [`--on-file` flag](./cli.md#on-file-command) on `dirsql query`) runs an
+external command under the execution contract below.
 
 ## Execution contract
 
@@ -32,8 +32,8 @@ occurrence, within whole argv tokens, in a single left-to-right pass:
   `{…}` is inert.
 - An unrecognized `{…}` is left literal.
 
-Which placeholders exist depends on the hook (see
-[per-hook contracts](#per-hook-contracts) below).
+The available placeholders are listed under the
+[`on-file` contract](#on-file-contract) below.
 
 ### Working directory and environment
 
@@ -62,7 +62,7 @@ compactly on one line.
 
 Every hook run is bounded by a **30-second** default timeout. A run
 exceeding it is killed and treated as a failure. One global config key
-raises (or tightens) the bound for **all** hooks:
+raises (or tightens) the bound:
 
 ```toml
 [dirsql]
@@ -80,19 +80,16 @@ A hook run fails when the command:
   stderr tail are reported),
 - exceeds the timeout (killed; stderr tail reported),
 - exits zero but prints no non-empty stdout line,
-- or (per hook, below) prints output that does not parse as expected.
+- or prints output that does not parse as a JSON array of row objects.
 
-What a failure *means* differs per hook:
+What a failure *means*: **per-file isolation.** The file contributes no rows
+and is reported as skipped; the scan indexes every other file and commits.
+The CLI names up to ten skipped files on stderr, then `... and N more`, and
+exits `23` — distinct from `0` (clean) and `1` (the run failed), so a caller
+can tell a partial index from a complete one. A row the table rejects under
+`strict` counts as the same kind of failure.
 
-| Hook | On failure |
-|---|---|
-| `on-file` | **Per-file isolation.** The file contributes no rows and is reported as skipped; the scan indexes every other file and commits. The CLI names up to ten skipped files on stderr, then `... and N more`, and exits `23` — distinct from `0` (clean) and `1` (the run failed), so a caller can tell a partial index from a complete one. A row the table rejects under `strict` counts as the same kind of failure. |
-| `pre-query` | The request returns `500 Internal Server Error` with the command's stderr tail in the JSON `error` body. |
-| `post-query` | The request returns `500 Internal Server Error` with the command's stderr tail (or, for unparseable output, `post-query did not return valid JSON: <err>`) in the JSON `error` body. |
-
-## Per-hook contracts
-
-### `on-file`
+## `on-file` contract
 
 Runs once per file matched by the table's `glob`, at initial scan and on
 every watched change. The command reads the file itself and prints a JSON
@@ -114,38 +111,3 @@ the path or stat metadata emits it (it has `{path}`).
 |---|---|
 | `{path}` | The matched file's **absolute** path. `on-file = "extract.py {path}"` — self-sufficient from any working directory, so the command resolves it even when the config lives outside the index. |
 | `{root}` | The index root directory. Derive a root-relative path with `relpath({path}, {root})`. |
-
-### `pre-query`
-
-Runs once per `POST /query` request, before the query. The raw request body
-goes in; plain-text SQL comes out (the stdout payload line). `dirsql` runs
-that SQL and returns rows as usual. With no `pre-query` key, the body is
-parsed as `{"sql": …}` instead — see [HTTP API](./http-api.md#post-query).
-
-| Placeholder | Value |
-|---|---|
-| `{args}` | The raw `POST /query` request body, verbatim, as one argv token. |
-
-**The hook owns SQL safety.** The `{args}` substitution keeps the untrusted
-body inert *as an argv token*, but whatever SQL string the hook prints is
-executed as-is. Validate, escape, or parameterize inside the hook.
-
-### `post-query`
-
-Runs once per successful `POST /query`, after the query. The result rows
-are serialized to a JSON array and delivered two ways:
-
-- **On stdin** — always, unbounded. This is the recommended path.
-- **As `{args}`** — only when the serialized payload is ≤ **96 KiB**. Above
-  that, `{args}` is substituted with an **empty string** and a stderr
-  warning naming the byte size directs the operator to stdin. The full
-  payload is still on stdin — this is a fallback, not truncation.
-
-| Placeholder | Value |
-|---|---|
-| `{args}` | The result rows as a JSON array, as one argv token; emptied (with a stderr warning) when the payload exceeds 96 KiB. |
-
-The stdout payload line is parsed as JSON and returned verbatim as the
-`200 application/json` response body. A payload that is not valid JSON
-fails the request (`500`). With no `post-query` key, the bare row array is
-returned — see [HTTP API](./http-api.md#post-query).

{dirsql-0.4.14/packages/rust → dirsql-0.4.16}/docs/reference/http-api.md

@@ -48,11 +48,11 @@ excluded from `SELECT *` results.
 
 | Status | When |
 |---|---|
-| `200` | Query succeeded. Body: array of row objects (or the [`post-query`](./hooks.md#post-query) hook's JSON). |
+| `200` | Query succeeded. Body: array of row objects. |
 | `400` | Malformed JSON body, missing or empty `sql` field, or a SQL error (syntax error, unknown table, or a statement SQLite classifies as a write — queries are read-only). |
 | `405` | `GET /query`. Plain-text body `method not allowed`. |
 | `408` | The query exceeded the 30-second per-query timeout. |
-| `500` | Internal server fault, or a failed [`pre-query`](./hooks.md#pre-query) / [`post-query`](./hooks.md#post-query) hook. |
+| `500` | Internal server fault. |
 | `503` | The server is in [degraded mode](./cli.md#degraded-mode) (the config file exists but failed to load). |
 
 All error responses (except `405`) are `application/json`:
@@ -61,15 +61,6 @@ All error responses (except `405`) are `application/json`:
 {"error": "syntax error near \"SLECT\""}
 ```
 
-### Hook interactions
-
-- With [`[dirsql].pre-query`](./config.md#dirsql-keys) configured, the
-  request body is **not** parsed as `{"sql": …}`; the raw body is passed to
-  the hook, which prints the SQL to run. Hook failure → `500`.
-- With [`[dirsql].post-query`](./config.md#dirsql-keys) configured, the
-  `200` body is whatever JSON the hook prints instead of the bare row
-  array. Hook failure or non-JSON output → `500`.
-
 ## `GET /events`
 
 Opens a [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events)

{dirsql-0.4.14 → dirsql-0.4.16}/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.4.14"
+version = "0.4.16"
 # abi3 note: the `abi3-py310` pyo3 feature (below) builds ONE stable-ABI
 # `cp310-abi3` wheel per platform that loads on every CPython >= 3.10
 # (matching `pyproject.toml`'s `requires-python = ">=3.10"`), instead of
@@ -22,7 +22,10 @@ name = "dirsql_py_ext"
 crate-type = ["cdylib", "rlib"]
 
 [dependencies]
-dirsql.workspace = true
+# `cli` is on so the extension module carries `dirsql::cli::run_cli`: the
+# console script calls it in-process instead of exec'ing a bundled binary
+# (#738), which is what lets `dirsql/_binary/` leave the wheel.
+dirsql = { workspace = true, features = ["cli"] }
 pyo3 = { version = "0.28", features = ["extension-module", "generate-import-lib", "abi3-py310"], optional = true }
 
 [lints.rust]

dirsql-0.4.16/packages/python/changelog.d/2026-08-04-cli-in-process.md

@@ -0,0 +1,3 @@
+**Changed** — the `dirsql` console script now runs **in-process** through the compiled extension module instead of `exec`ing a bundled binary. `_dirsql` is built with the core's `cli` feature and exports `run_cli`, which the launcher calls via [bin-shim](https://pypi.org/project/bin-shim/). Plugin discovery and config-extension resolution are unchanged and still run first. The Windows/POSIX split is gone — `os.execv` on POSIX and `subprocess.run` on Windows are replaced by one in-process call on every platform, so the two no longer drift.
+
+**Removed** — **BREAKING (packaging)**: the wheel no longer ships `dirsql/_binary/`. It held a standalone `dirsql` executable duplicating the core already present in the extension module; `pyproject.toml`'s `[tool.maturin].include` row and the release pipeline's pypi `bundle_cli` staging are both gone. `pip install dirsql && dirsql ...` and `uvx dirsql` behave exactly as before — verified across `--version`, a query, a SQL error (1), an unknown flag (2), and `dirsql server` + Ctrl-C (graceful shutdown, **0**). Anyone locating that binary by path must instead call `dirsql._dirsql.run_cli(argv)`, or install the Rust binary with `cargo install dirsql --features cli`. See [MIGRATIONS.md](../../MIGRATIONS.md). #738.

{dirsql-0.4.14 → dirsql-0.4.16}/packages/python/docs/.vitepress/config.ts

@@ -54,7 +54,6 @@ export default defineConfig({
             { text: 'Derive columns from file paths', link: '/howto/columns-from-paths' },
             { text: 'Extract rows from file contents', link: '/howto/extract-from-contents' },
             { text: 'Parse your files into columns', link: '/howto/parse-files-into-columns' },
-            { text: 'Search documents by meaning', link: '/howto/search-by-meaning' },
             { text: "Skip files you don't want indexed", link: '/howto/skip-files' },
             { text: 'Load a SQLite extension', link: '/howto/load-extension' },
             { text: 'Keep the index across restarts', link: '/howto/persist' },

{dirsql-0.4.14 → dirsql-0.4.16}/packages/python/docs/howto/extract-from-contents.md

@@ -79,8 +79,6 @@ SQLite value mapping is under
 
 - The command re-runs on every startup and on every change to a matched
   file. If it is expensive, [keep the index across restarts](./persist.md).
-- The flagship use of `on-file` — computing embeddings — is
-  [Search documents by meaning](./search-by-meaning.md).
 - Embedding `dirsql` in a program instead? The SDK's `on_file` callback
   fills the same role in-process — see
   [Embed `dirsql` in your application](./embed.md).

{dirsql-0.4.14 → dirsql-0.4.16}/packages/python/docs/howto/load-extension.md

@@ -85,5 +85,3 @@ interpreter to resolve package names with
 - Embedding `dirsql` in a program? The SDK constructor takes the same
   specs via its `extensions` parameter
   ([SDK reference](../reference/sdk.md#constructor)).
-- The payoff use case — `sqlite-vec` powering semantic search — is
-  [Search documents by meaning](./search-by-meaning.md).

{dirsql-0.4.14 → dirsql-0.4.16}/packages/python/docs/howto/write-a-plugin.md

@@ -24,8 +24,7 @@ dirsql-embeddings/
     └── dirsql_embeddings/
         ├── __init__.py
         ├── dirsql.toml       # the config fragment
-        ├── embed.py          # on-file hook
-        └── search.py         # pre-query hook
+        └── embed.py          # on-file hook
 ```
 
 The entry point maps a **source label** (the name) to the **module that
@@ -55,8 +54,7 @@ structurally **identical to a user config**. It may declare
 [`[[table]]`](../reference/config.md#table) (with
 [`on-file`](../reference/hooks.md#on-file)),
 [`[[dirsql.extension]]`](../reference/config.md#dirsql-extension),
-[`ignore`](../reference/config.md#dirsql-keys),
-[`pre-query`/`post-query`](../reference/hooks.md#pre-query), and
+[`ignore`](../reference/config.md#dirsql-keys), and
 [`hook-timeout`](../reference/hooks.md#timeout).
 
 There are **no plugin-specific keys and no plugin-specific restrictions**. The
@@ -96,17 +94,14 @@ matter most for a published plugin:
 ## Worked example: an embeddings plugin
 
 Here is the whole plugin — vector search over a directory of notes, buildable
-in about fifty lines. It composes the same three pieces as
-[Search documents by meaning](./search-by-meaning.md): the
+in about forty lines. It composes two pieces: the
 [`sqlite-vec`](https://github.com/asg017/sqlite-vec) extension for the
-distance math, an `on-file` command to embed each file, and a `pre-query`
-command to embed the question.
+distance math, and an `on-file` command to embed each file.
 
 The fragment, `src/dirsql_embeddings/dirsql.toml`:
 
 ```toml
 [dirsql]
-pre-query    = "uv run --with model2vec python search.py {args}"
 hook-timeout = 300   # headroom for the first-run model download
 
 [[dirsql.extension]]
@@ -140,46 +135,23 @@ row = {"path": os.path.relpath(path, root), "text": text,
 print(json.dumps([row]))
 ```
 
-`search.py` turns a `{"q": "..."}` request body into nearest-neighbor SQL:
-
-```python
-"""Turn a {"q": "..."} request body into a nearest-neighbor SQL query."""
-import json
-import sys
-
-from model2vec import StaticModel
-
-body = json.loads(sys.argv[1])
-model = StaticModel.from_pretrained("minishlab/potion-base-8M")
-vector = model.encode([body["q"]])[0]
-needle = json.dumps([round(float(x), 6) for x in vector])
-print(
-    "SELECT path, ROUND(vec_distance_cosine(embedding, '%s'), 3) AS distance "
-    "FROM notes ORDER BY distance LIMIT 3" % needle
-)
-```
-
-::: warning The hook owns SQL safety
-Whatever SQL `pre-query` prints is executed as-is. Here the interpolated
-value is a numeric vector the script itself produced; never splice raw request
-text into SQL. See [`pre-query`](../reference/hooks.md#pre-query).
-:::
-
-The relative `embed.py` / `search.py` above resolve against the fragment
-directory, which is convenient during development. For a published plugin,
-promote them to console scripts (`[project.scripts]` → `embed-file`,
-`embed-search`) so the commands carry their own interpreter and dependencies
-and no longer depend on `uv run --with`.
+The relative `embed.py` above resolves against the fragment directory, which
+is convenient during development. For a published plugin, promote it to a
+console script (`[project.scripts]` → `embed-file`) so the command carries
+its own interpreter and dependencies and no longer depends on
+`uv run --with`.
 
 Once the package is installed alongside the launcher, its `notes` table is
 queryable with no config edits:
 
 ```bash
-uvx --with dirsql-embeddings dirsql query '{"q": "how do I cook pasta?"}'
+uvx --with dirsql-embeddings dirsql query \
+  "SELECT path FROM notes ORDER BY vec_distance_cosine(embedding, '[0.1, ...]') LIMIT 3"
 ```
 
 The launcher discovers the installed plugin, composes its fragment, and the
-`pre-query` hook turns the question into vector-distance SQL.
+`notes` table (with `vec_distance_cosine()` from the loaded extension) is
+available to the query.
 
 ## SDK-style convention: expose the config
 
@@ -230,8 +202,8 @@ Discovery is deliberately narrow. Know exactly who does what:
   [convention above](#sdk-style-convention-expose-the-config)).
 - **Name collisions are a hard error.** Because fragments compose like any
   [multiple configs](../reference/config.md#composing-multiple-configs), two
-  plugins (or a plugin and your config) defining a table of the same name — or
-  the same query hook — fail loudly, naming the conflict. It is never a silent
+  plugins (or a plugin and your config) defining a table of the same name
+  fail loudly, naming the conflict. It is never a silent
   last-writer-wins.
 
 ::: warning Config flags are subcommand-local