dirsql 0.4.12 → 0.4.14

package/dist/cli/main.js

@@ -1,23 +1,75 @@
-// Launcher entry: resolve the bundled `dirsql` binary and forward argv,
-// exit code, and signals to it. The launcher is a transparent forwarder —
-// every argv (including any subcommand) goes straight to the Rust binary,
-// which owns subcommand dispatch and clap-rejects unknown ones.
-import { spawnSync } from "node:child_process";
+// Launcher entry: run the CLI in-process through the napi addon.
+//
+// The launcher is a transparent forwarder — every argv (including any
+// subcommand) goes straight to the core's `runCli`, which owns subcommand
+// dispatch and clap-rejects unknown ones. Nothing is spawned: the same
+// `@dirsql/lib-*` addon the SDK loads carries the CLI, so a package ships one
+// copy of the core instead of two (#739).
+import { mainInProcess } from "bin-shim";
+import { loadNativeCore } from "../load-native-core.js";
 import { die } from "./die.js";
-import { resolveBinary } from "./resolve-binary.js";
 import { withResolvedExtensions } from "./resolve-config-extensions.js";
+/**
+ * Resolve `runCli` off the same addon the SDK loads.
+ *
+ * bin-shim can resolve an addon itself, but its default naming is
+ * `@{scope}/lib-{platform}-{arch}`, which cannot express the ABI suffix
+ * dirsql's packages carry (`@dirsql/lib-linux-x64-gnu`). Reusing
+ * `loadNativeCore` keeps one resolution rule for the SDK and the CLI —
+ * including its dev fallback to a locally built `dirsql.node` — so a
+ * monorepo checkout and a published install take the same path.
+ */
+function resolveRunCli() {
+    const core = loadNativeCore();
+    if (typeof core.runCli !== "function") {
+        throw new Error("dirsql: the native addon has no callable `runCli` export; " +
+            "it was built without the `cli` feature.");
+    }
+    return core.runCli;
+}
+/**
+ * Keep Ctrl-C fatal while the CLI runs in-process.
+ *
+ * The core installs tokio signal handlers for `dirsql server`, and
+ * signal-hook (which tokio uses) *chains*: it runs its own actions and then
+ * the handler installed before it. CPython installs `default_int_handler` at
+ * startup, so the pip launcher gets a terminating disposition for free —
+ * bare Node leaves `SIG_DFL`, which signal-hook does not emulate, so the
+ * signal is swallowed and the process becomes SIGKILL-only (measured: a
+ * probe ignored SIGTERM for 143 seconds).
+ *
+ * Registering a JS listener first gives signal-hook a real prior handler to
+ * chain to. This cannot be fixed after the fact: `removeAllListeners` only
+ * drops JS listeners and cannot touch a disposition installed by native
+ * code, and `unregister_signal` leaves the OS handler in place. One listener
+ * is the whole remedy — no `unsafe`, no `sigaction`.
+ */
+function keepSignalsFatal() {
+    // While the core is running, its own handler drives shutdown and this
+    // listener is the tail of the chain; it matters for signals arriving
+    // outside that window, where exiting is exactly right.
+    process.on("SIGINT", () => process.exit(130));
+    process.on("SIGTERM", () => process.exit(143));
+}
 export async function main(argv = process.argv.slice(2)) {
-    const binary = resolveBinary();
-    // Resolve any package-name extensions in a TOML config here (the binary
+    keepSignalsFatal();
+    // Resolve any package-name extensions in a TOML config here (the core
     // can't) and pass them as `--extension` flags; a no-op otherwise.
-    const result = spawnSync(binary, await withResolvedExtensions(argv), {
-        stdio: "inherit",
-    });
-    if (result.error) {
-        die(result.error.message, 1);
+    const resolved = await withResolvedExtensions(argv);
+    let code;
+    try {
+        code = await mainInProcess({
+            argv: resolved,
+            binaryName: "dirsql",
+            // Resolution is ours (see `resolveRunCli`), so bin-shim never consults
+            // its own naming; `from` only satisfies the shared options type.
+            from: import.meta.url,
+            runCli: resolveRunCli(),
+        });
     }
-    if (result.signal) {
-        process.kill(process.pid, result.signal);
+    catch (e) {
+        die(e instanceof Error ? e.message : String(e), 1);
+        return;
     }
-    process.exit(result.status ?? 1);
+    process.exit(code);
 }

package/dist/platforms.d.ts

@@ -5,8 +5,6 @@ export interface Platform {
     nodePlatform: NodeJS.Platform;
     /** Node `process.arch` value for this target. */
     nodeArch: NodeJS.Architecture;
-    /** CLI sub-package name (`@dirsql/cli-<slug>`). */
-    name: string;
     /** napi library sub-package name (`@dirsql/lib-<slug>`). */
     libName: string;
     /** Wheel-style `os` constraint for the sub-package's package.json. */
@@ -15,14 +13,8 @@ export interface Platform {
     cpu: string[];
     /** libc constraint (Linux only). */
     libc?: string[];
-    /** Archive extension cargo-dist emits for this target. */
-    ext: "tar.xz" | "zip";
-    /** Whether the binary has a `.exe` suffix on this platform. */
-    exe?: boolean;
 }
 export declare const PLATFORMS: readonly Platform[];
-/** Node `${platform}-${arch}` → `@dirsql/cli-*` sub-package name. */
-export declare function nodeTriples(): Record<string, string>;
 /** Node `${platform}-${arch}` → `@dirsql/lib-*` napi sub-package name. */
 export declare function libTriples(): Record<string, string>;
 /**

package/dist/platforms.js

@@ -1,82 +1,61 @@
 // Single source of truth for the target platforms `dirsql` publishes.
 //
-// Every target triple generates two npm sub-packages:
+// Every target triple generates ONE npm sub-package: `@dirsql/lib-<slug>`,
+// holding the napi-rs `.node` addon. It backs both layers — the TypeScript
+// SDK loads it via `loadNativeCore()`, and since #739 the `dirsql` CLI runs
+// in-process through its `runCli` export rather than spawning a binary. The
+// second family, `@dirsql/cli-<slug>`, shipped a redundant copy of the same
+// core and is gone.
 //
-// 1. `@dirsql/cli-<slug>` — holds the standalone `dirsql` CLI binary
-//    (from cargo-dist). Consumed at runtime by `src/cli/resolveBinary.ts`
-//    when a user runs the `dirsql` CLI.
-// 2. `@dirsql/lib-<slug>` — holds the napi-rs `.node` addon used by the
-//    TypeScript SDK. Consumed at runtime by `loadNativeCore()` in
-//    `src/index.ts` when a user `import`s from `dirsql`.
+// The sub-packages are `optionalDependencies` of the main `dirsql` package,
+// so npm/pnpm install only the one matching the host's OS/arch.
 //
-// Both sub-package sets use `optionalDependencies` on the main `dirsql`
-// package so npm/pnpm install only the one matching the host's OS/arch.
-//
-// `nodeTriples()` / `libTriples()` return `${process.platform}-${process.arch}`
-// → sub-package-name maps for the respective layer.
+// `libTriples()` returns a `${process.platform}-${process.arch}` →
+// sub-package-name map.
 export const PLATFORMS = [
     {
         triple: "x86_64-unknown-linux-gnu",
         nodePlatform: "linux",
         nodeArch: "x64",
-        name: "@dirsql/cli-linux-x64-gnu",
         libName: "@dirsql/lib-linux-x64-gnu",
         os: ["linux"],
         cpu: ["x64"],
         libc: ["glibc"],
-        ext: "tar.xz",
     },
     {
         triple: "aarch64-unknown-linux-gnu",
         nodePlatform: "linux",
         nodeArch: "arm64",
-        name: "@dirsql/cli-linux-arm64-gnu",
         libName: "@dirsql/lib-linux-arm64-gnu",
         os: ["linux"],
         cpu: ["arm64"],
         libc: ["glibc"],
-        ext: "tar.xz",
     },
     {
         triple: "x86_64-apple-darwin",
         nodePlatform: "darwin",
         nodeArch: "x64",
-        name: "@dirsql/cli-darwin-x64",
         libName: "@dirsql/lib-darwin-x64",
         os: ["darwin"],
         cpu: ["x64"],
-        ext: "tar.xz",
     },
     {
         triple: "aarch64-apple-darwin",
         nodePlatform: "darwin",
         nodeArch: "arm64",
-        name: "@dirsql/cli-darwin-arm64",
         libName: "@dirsql/lib-darwin-arm64",
         os: ["darwin"],
         cpu: ["arm64"],
-        ext: "tar.xz",
     },
     {
         triple: "x86_64-pc-windows-msvc",
         nodePlatform: "win32",
         nodeArch: "x64",
-        name: "@dirsql/cli-win32-x64-msvc",
         libName: "@dirsql/lib-win32-x64-msvc",
         os: ["win32"],
         cpu: ["x64"],
-        ext: "zip",
-        exe: true,
     },
 ];
-/** Node `${platform}-${arch}` → `@dirsql/cli-*` sub-package name. */
-export function nodeTriples() {
-    const out = {};
-    for (const p of PLATFORMS) {
-        out[`${p.nodePlatform}-${p.nodeArch}`] = p.name;
-    }
-    return out;
-}
 /** Node `${platform}-${arch}` → `@dirsql/lib-*` napi sub-package name. */
 export function libTriples() {
     const out = {};

package/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).

package/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).

package/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

package/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

package/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]]

package/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).

package/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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "description": "Ephemeral SQL index over a local directory",
   "license": "MIT",
   "repository": "https://github.com/thekevinscott/dirsql",
@@ -190,6 +190,7 @@
     }
   },
   "dependencies": {
+    "bin-shim": "^0.2.0",
     "smol-toml": "^1.6.1"
   },
   "devDependencies": {
@@ -212,15 +213,10 @@
     ]
   },
   "optionalDependencies": {
-    "@dirsql/lib-linux-x64-gnu": "0.4.12",
-    "@dirsql/lib-linux-arm64-gnu": "0.4.12",
-    "@dirsql/lib-darwin-x64": "0.4.12",
-    "@dirsql/lib-darwin-arm64": "0.4.12",
-    "@dirsql/lib-win32-x64-msvc": "0.4.12",
-    "@dirsql/cli-linux-x64-gnu": "0.4.12",
-    "@dirsql/cli-linux-arm64-gnu": "0.4.12",
-    "@dirsql/cli-darwin-x64": "0.4.12",
-    "@dirsql/cli-darwin-arm64": "0.4.12",
-    "@dirsql/cli-win32-x64-msvc": "0.4.12"
+    "@dirsql/lib-linux-x64-gnu": "0.4.14",
+    "@dirsql/lib-linux-arm64-gnu": "0.4.14",
+    "@dirsql/lib-darwin-x64": "0.4.14",
+    "@dirsql/lib-darwin-arm64": "0.4.14",
+    "@dirsql/lib-win32-x64-msvc": "0.4.14"
   }
 }

package/dist/cli/platform-key.d.ts

@@ -1 +0,0 @@
-export declare function platformKey(): string;

package/dist/cli/platform-key.js

@@ -1,5 +0,0 @@
-// Return the `platform-arch` key used to look up the per-platform
-// optional-dependency package (e.g. `linux-x64`, `darwin-arm64`).
-export function platformKey() {
-    return `${process.platform}-${process.arch}`;
-}

package/dist/cli/resolve-binary.d.ts

@@ -1,5 +0,0 @@
-/** A minimal `require.resolve`-shaped function. Injectable for tests. */
-export type Resolver = (specifier: string) => string;
-/** Default resolver: a CJS-style `require.resolve` rooted at this ESM module. */
-export declare function defaultResolver(): Resolver;
-export declare function resolveBinary(key?: string, resolver?: Resolver): string;

package/dist/cli/resolve-binary.js

@@ -1,25 +0,0 @@
-// Resolve the absolute path of the prebuilt `dirsql` binary shipped by
-// whichever `@dirsql/cli-<triple>` optional-dependency package matched
-// the host at `npm install` time.
-import { createRequire } from "node:module";
-import { nodeTriples } from "../platforms.js";
-import { die } from "./die.js";
-import { platformKey } from "./platform-key.js";
-/** Default resolver: a CJS-style `require.resolve` rooted at this ESM module. */
-export function defaultResolver() {
-    return createRequire(import.meta.url).resolve;
-}
-export function resolveBinary(key = platformKey(), resolver = defaultResolver()) {
-    const triples = nodeTriples();
-    const pkg = triples[key];
-    if (!pkg) {
-        die(`no prebuilt binary for ${key}. Build from source with \`cargo install dirsql --features cli\`.`);
-    }
-    const bin = process.platform === "win32" ? "dirsql.exe" : "dirsql";
-    try {
-        return resolver(`${pkg}/${bin}`);
-    }
-    catch {
-        die(`${pkg} is not installed. If you ran \`npm install --no-optional\` or \`--ignore-optional\`, re-install without that flag.`);
-    }
-}

package/docs/howto/search-by-meaning.md

@@ -1,153 +0,0 @@
-# Search documents by meaning
-
-Ask a question in plain language and get the closest documents back — even
-when they share no keywords with it. Three pieces you already have compose
-into semantic search: a SQLite vector extension for the distance math, an
-[`on-file`](../reference/hooks.md#on-file) command to embed each file at
-index time, and a [`pre-query`](../reference/hooks.md#pre-query) command to
-embed each question at query time.
-
-::: tip Just want it working?
-[`dirsql-plugin-embeddings`](https://pypi.org/project/dirsql-plugin-embeddings/)
-packages exactly what this guide builds, ready to install:
-`uvx --with dirsql-plugin-embeddings dirsql server`. Keep reading to see how it's
-built — the same three pieces, from scratch.
-:::
-
-## How the pieces fit
-
-1. **[`[[dirsql.extension]]`](../reference/config.md#dirsql-extension)**
-   loads [`sqlite-vec`](https://github.com/asg017/sqlite-vec), making
-   `vec_distance_cosine()` callable in queries.
-2. **`on-file`** runs an embedding command once per matched file; the
-   vector lands in an `embedding` column next to the text.
-3. **`pre-query`** receives each raw `POST /query` body, embeds the
-   question, and prints the nearest-neighbor SQL to run.
-
-`dirsql` never sees a model — both hooks are commands you own, so any
-embedding model works. This guide uses
-[`model2vec`](https://github.com/MinishLab/model2vec), a small, fast,
-CPU-only embedding library (its `potion-base-8M` model downloads ~30 MB
-from Hugging Face on first use).
-
-## 1. The embedding scripts
-
-Suppose short notes live in `notes/*.md`:
-
-```
-notes/pasta.md      # boiling spaghetti, olive oil, garlic
-notes/branches.md   # git feature branches and pull requests
-notes/tomatoes.md   # planting tomato seedlings after the last frost
-```
-
-Next to them, `embed.py` turns one file into one row carrying its text and
-its `path`, text, and embedding (a JSON array, stored as TEXT — `sqlite-vec`
-accepts JSON vectors directly). dirsql injects no columns, so the script emits
-the path itself, deriving it from the `{path}`/`{root}` the hook passes in:
-
-```python
-"""Embed one file's text; print a dirsql row array on stdout."""
-import json
-import os
-import sys
-
-from model2vec import StaticModel
-
-path, root = sys.argv[1], sys.argv[2]
-text = open(path, encoding="utf-8").read()
-model = StaticModel.from_pretrained("minishlab/potion-base-8M")
-vector = model.encode([text])[0]
-row = {"path": os.path.relpath(path, root), "text": text,
-       "embedding": json.dumps([round(float(x), 6) for x in vector])}
-print(json.dumps([row]))
-```
-
-And `search.py` turns a `{"q": "..."}` request body into SQL, embedding the
-question with the same model:
-
-```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).
-:::
-
-## 2. Wire them up in `.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]]
-path       = "sqlite_vec"          # Python module name; see note below
-entrypoint = "sqlite3_vec_init"
-
-[[table]]
-ddl     = "CREATE TABLE notes (path TEXT, text TEXT, embedding TEXT)"
-glob    = "notes/*.md"
-on-file = "uv run --with model2vec python embed.py {path} {root}"
-```
-
-The extension is named by package: the Python launcher resolves the
-installed `sqlite_vec` module to its bundled loadable. Naming rules per
-runtime — and the literal-path alternative that works everywhere — are in
-[Load a SQLite extension](./load-extension.md).
-
-## 3. Ask questions
-
-Run with `sqlite-vec` available to the launcher's environment. The initial
-scan runs `embed.py` once per note, then the query argument goes straight to
-`pre-query`, exactly as a `POST /query` body would. Pass the config with
-[`-c`](../reference/cli.md#flags) — `dirsql` does not auto-load a
-`.dirsql.toml` from the current directory:
-
-```bash
-uvx --with sqlite-vec dirsql query '{"q": "how do I cook pasta?"}' -c ./.dirsql.toml
-```
-
-```json
-[{"path":"notes/pasta.md","distance":0.315},{"path":"notes/tomatoes.md","distance":0.881},{"path":"notes/branches.md","distance":0.92}]
-```
-
-```bash
-uvx --with sqlite-vec dirsql query '{"q": "reviewing code on github"}' -c ./.dirsql.toml
-```
-
-```json
-[{"path":"notes/branches.md","distance":0.51},{"path":"notes/pasta.md","distance":1.033},{"path":"notes/tomatoes.md","distance":1.074}]
-```
-
-Neither question shares a keyword with its top note — "cook" appears
-nowhere in `pasta.md`, "github" nowhere in `branches.md`. The distance
-ranking is doing the work.
-
-Because `pre-query` is set, the query argument is *not* the usual
-`{"sql": …}` — it goes to your script as-is, which decides what SQL runs
-([hook interactions](../reference/http-api.md#hook-interactions)).
-
-## Recomputing vs. caching
-
-Embeddings are recomputed on every startup, because the database is a
-derived, ephemeral view of the files
-([how `dirsql` thinks](../explanation.md)). Once the model is cached this
-is fast for small trees; for large ones, enable persistence so unchanged
-files keep their stored embeddings across restarts —
-[Keep the index across restarts](./persist.md). Editing a note re-embeds
-just that file, automatically.