dirsql 0.4.16__tar.gz → 0.4.18__tar.gz

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

@@ -484,7 +484,6 @@ dependencies = [
  "tokio",
  "tokio-stream",
  "toml",
- "wait-timeout",
  "walkdir",
 ]
 
@@ -500,7 +499,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.4.16"
+version = "0.4.18"
 dependencies = [
  "dirsql",
  "pyo3",

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.4.16
+Version: 0.4.18
 Requires-Dist: tomli>=2 ; python_full_version < '3.11'
 Requires-Dist: bin-shim>=0.1
 Summary: Ephemeral SQL index over a local directory

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

@@ -54,6 +54,7 @@ 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.18/docs/howto/search-by-meaning.md

@@ -0,0 +1,114 @@
+# Search documents by meaning
+
+Ask a question in plain language and get the closest documents back — even
+when they share no keywords with it. Install
+[`dirsql-plugin-embeddings`](../plugins.md#dirsql-plugin-embeddings) and
+semantic search becomes plain SQL: the plugin's `embed()` function turns
+text into vectors, [`sqlite-vec`](https://github.com/asg017/sqlite-vec)'s
+`vec_distance_cosine()` measures distance, and `ORDER BY … LIMIT` does the
+ranking. No config, no API keys, no services — the model runs locally.
+
+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
+```
+
+## The one-liner
+
+The plugin package is also its own command. Give it a corpus glob and a
+question, and it prints the closest paths, ranked by distance:
+
+```bash
+uvx dirsql-plugin-embeddings 'notes/*.md' "how do I cook pasta?" -k 3
+```
+
+- The **corpus glob is required**, and always first: the plugin never picks a
+  default corpus, so you always say exactly which files are in scope. A bare
+  glob is fine — the command normalizes it to the `./`-relative form the SQL
+  layer requires.
+- The question is the second positional.
+- `-k` / `--limit` (both spellings, default 10) is the number of results —
+  it is exactly the SQL `LIMIT` of the generated query; there is no other
+  cutoff.
+- `--model <id>` switches the embedding model
+  ([model story](../plugins.md#model)).
+
+The first-ever run downloads the model (on the order of a hundred megabytes,
+with progress on stderr); after that it loads from the local cache. Results
+print one `path<TAB>distance` line per match, closest first.
+
+## The SQL behind it
+
+The one-liner generates and runs ordinary `dirsql` SQL, and you can write it
+yourself when you want more than ranked paths — a different projection, a
+join, a `WHERE` clause, a subset of a JSON file's content:
+
+```bash
+uvx --with dirsql-plugin-embeddings dirsql "
+  SELECT path,
+         vec_distance_cosine(emb, embed('how do I cook pasta?')) AS distance
+  FROM (SELECT path, embed(content) AS emb FROM './notes/*.md')
+  ORDER BY distance
+  LIMIT 3"
+```
+
+```json
+[{"path":"notes/pasta.md","distance":0.315},{"path":"notes/tomatoes.md","distance":0.881},{"path":"notes/branches.md","distance":0.92}]
+```
+
+Neither "cook" nor any other keyword needs to appear in `pasta.md` — the
+distance ranking is doing the work.
+
+Reading the query inside-out:
+
+1. The subquery scans the [path-table](../reference/path-tables.md)
+   `'./notes/*.md'` and embeds each file's
+   [`content`](../reference/path-tables.md#columns) — only the files the
+   glob matches are ever read or embedded. In hand-written SQL the `./`
+   prefix is [required](../reference/path-tables.md#writing-the-path); only
+   the one-liner normalizes a bare glob for you.
+2. `embed('how do I cook pasta?')` embeds the question once (the function is
+   deterministic, so SQLite reuses the value across rows).
+3. `vec_distance_cosine(...)` computes cosine distance between the two
+   vectors; `ORDER BY distance LIMIT 3` keeps the three nearest.
+
+Structured files compose with SQL's JSON operators — embed one field instead
+of the whole file:
+
+```sql
+SELECT path
+FROM (SELECT path, embed(content ->> 'abstract') AS emb
+      FROM './papers/**/metadata.json')
+ORDER BY vec_distance_cosine(emb, embed('local private models'))
+LIMIT 10
+```
+
+::: tip Top-k is `LIMIT k`
+If you know `sqlite-vec` you may reach for its `MATCH … AND k = 10` idiom.
+That syntax belongs to `sqlite-vec`'s `vec0` virtual table, which `dirsql`
+does not use — `dirsql` tables are per-file row tables. For plain
+expressions, `sqlite-vec`'s own documented pattern is exactly what this
+guide uses: `ORDER BY vec_distance_cosine(...) LIMIT k`.
+:::
+
+## Repeat runs are cheap
+
+Computed vectors are cached on disk, keyed on content and model
+([vector cache](../plugins.md#vector-cache)) — re-running a search over
+unchanged files skips the model entirely and re-embeds only what changed.
+And the plugin costs nothing when idle: a query that never calls `embed()`
+spawns no worker and loads no model
+([zero cost when unused](../plugins.md#zero-cost-when-unused)).
+
+## How `embed()` gets into SQL
+
+The plugin ships a config fragment declaring `embed()` via
+[`[[dirsql.function]]`](../reference/config.md#dirsql-function), which the
+`uvx`/`pip` launcher [discovers automatically](../reference/cli.md#plugins).
+The same mechanism is open to your own configs and plugins — any external
+command that speaks the
+[worker protocol](../reference/config.md#worker-protocol) can back a SQL
+function. To build one, see [Write a plugin](./write-a-plugin.md).

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

@@ -54,8 +54,10 @@ 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), and
-[`hook-timeout`](../reference/hooks.md#timeout).
+[`[[dirsql.function]]`](../reference/config.md#dirsql-function) (how
+[`dirsql-plugin-embeddings`](../plugins.md#dirsql-plugin-embeddings) provides
+its `embed()` SQL function),
+and [`ignore`](../reference/config.md#dirsql-keys).
 
 There are **no plugin-specific keys and no plugin-specific restrictions**. The
 config schema is content-only: the index `root` and `--persist` are
@@ -101,9 +103,6 @@ distance math, and an `on-file` command to embed each file.
 The fragment, `src/dirsql_embeddings/dirsql.toml`:
 
 ```toml
-[dirsql]
-hook-timeout = 300   # headroom for the first-run model download
-
 [[dirsql.extension]]
 path       = "sqlite_vec"
 entrypoint = "sqlite3_vec_init"
@@ -202,7 +201,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
+  plugins (or a plugin and your config) defining a table — or declaring a
+  [function](../reference/config.md#dirsql-function) — of the same name
   fail loudly, naming the conflict. It is never a silent
   last-writer-wins.
 

dirsql-0.4.18/docs/plugins.md

@@ -0,0 +1,100 @@
+# Plugins
+
+A **plugin** is an ordinary Python package that ships a `dirsql.toml` config
+fragment and declares itself via a `dirsql` entry point. Installing it in the
+same environment as `dirsql` activates it: the `pip`/`uvx` launcher discovers
+the package and loads its fragment automatically, with zero config edits. The
+full discovery contract (ordering, opt-out, failure modes) is in the
+[CLI reference](./reference/cli.md#plugins); to build your own, see
+[Write a plugin](./howto/write-a-plugin.md).
+
+This page lists the first-party plugins.
+
+## `dirsql-plugin-embeddings`
+
+Semantic search over files. The plugin's product is content → vectors: it
+declares an `embed()` SQL scalar function (via
+[`[[dirsql.function]]`](./reference/config.md#dirsql-function)) that turns
+TEXT or BLOB values into embedding vectors, and loads
+[`sqlite-vec`](https://github.com/asg017/sqlite-vec) so
+`vec_distance_cosine()` and friends do the distance math. You scope the
+search with an ordinary [path-table](./reference/path-tables.md) glob, rank
+with `ORDER BY`, and cut with `LIMIT` — search is plain SQL.
+
+[PyPI](https://pypi.org/project/dirsql-plugin-embeddings/) ·
+[Source](https://github.com/thekevinscott/dirsql/tree/main/plugins/dirsql-plugin-embeddings)
+
+### Install and launch
+
+The plugin is a normal PyPI package; installing it alongside `dirsql` is the
+whole install story (installed = active — there is no enable step, and no
+configuration at all):
+
+```sh
+uvx --with dirsql-plugin-embeddings dirsql "
+  SELECT path
+  FROM (SELECT path, embed(content ->> 'abstract') AS emb
+        FROM './arxiv-firehose/data/**/metadata.json')
+  ORDER BY vec_distance_cosine(emb, embed('local private models'))
+  LIMIT 10"
+```
+
+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 the `sqlite-vec` extension (resolved
+from the installed `sqlite-vec` package, which the plugin depends on) and the
+`embed()` function entry. Discovery can be turned off per-invocation with
+`--no-plugin` or `DIRSQL_NO_PLUGIN=1`
+([reference](./reference/cli.md#plugins)).
+
+For the common case — one glob, one question, top-k paths — the package is
+also its own command, generating and running exactly that SQL:
+
+```sh
+uvx dirsql-plugin-embeddings '**/*.md' "local private models" -k 10
+```
+
+The corpus glob is a **required** first positional — the plugin never picks a
+default corpus for you — and a bare glob is normalized to the `./`-relative
+form the SQL layer requires. Results print as ranked `path<TAB>distance`
+lines, closest first. See
+[Search documents by meaning](./howto/search-by-meaning.md) for the guide to
+both styles.
+
+### Zero cost when unused
+
+`embed()` is [inert until called](./reference/config.md#worker-lifecycle):
+installing the plugin changes nothing for queries that never call it. No
+worker process is spawned, no model is loaded or downloaded, and no cache is
+touched. Only what a query's glob actually selects is ever embedded — the
+worker receives **values, not paths**, and never opens files itself.
+
+### Model
+
+Embeddings come from [model2vec](https://github.com/MinishLab/model2vec)
+static models — inference needs numpy and tokenizers only, no torch, so the
+plugin stays light enough for `uvx` ephemeral environments and is fast on
+CPU. The default model is
+[`minishlab/potion-retrieval-32M`](https://huggingface.co/minishlab/potion-retrieval-32M).
+
+The very first `embed()` call downloads the model (on the order of a hundred
+megabytes — expect seconds to a few minutes depending on your connection,
+with progress on stderr) into the standard Hugging Face cache
+(`~/.cache/huggingface`), which persists across `uvx` environments; every
+later run loads it from disk.
+
+Override the model per call with the optional second argument —
+`embed(text, 'model-id')` — or per run with the one-liner's `--model` flag,
+which templates the same second argument. The id must be a
+**model2vec-loadable** model; sentence-transformers/torch models are out of
+scope.
+
+### Vector cache
+
+Computed vectors are cached at `~/.cache/dirsql/embeddings/` (respecting
+`XDG_CACHE_HOME`), keyed on the SHA-256 of the value bytes plus the model
+identifier. Changing either recomputes — switching models never serves stale
+vectors — and re-running a query over unchanged files is cache hits all the
+way. There is no eviction: the directory is **safe to wipe at any time**; the
+only cost is re-embedding. The cache never lives inside a queried tree — the
+worker writes nothing into the directories you query.

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

@@ -76,11 +76,12 @@ Config flags are subcommand-local: pass them after `server`
 
 ### Defaults
 
-- Per-query timeout: **30 seconds**. A query exceeding it returns
-  `408 Request Timeout`.
-- `on-file` command hooks default to a **30-second** timeout each,
-  overridable with the config key
-  [`[dirsql].hook-timeout`](./config.md#dirsql-keys).
+- Per-query timeout: **30 seconds**, in server mode only. A query exceeding
+  it returns `408 Request Timeout`. One-shot [`dirsql query`](#dirsql-query)
+  has no built-in timeout.
+- `on-file` command hooks run **unbounded**; bound one by wrapping its
+  command in `timeout(1)` (see
+  [Bounding a hook](./hooks.md#bounding-a-hook)).
 
 ### Configless mode
 
@@ -166,13 +167,17 @@ 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).
-- **`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
-  is an error, not empty output. The read-only rule here governs SQL
-  statements; dirsql separately never modifies the files it indexes — see
+- **`on-file` hooks** apply identically (unbounded; wrap in `timeout(1)` to
+  bound — see [Bounding a hook](./hooks.md#bounding-a-hook)).
+- The **read-only rule** and the `_dirsql_*` **internal-table denial** apply
+  identically. A rejected read is an error, not empty output. The read-only
+  rule here governs SQL statements; dirsql separately never modifies the
+  files it indexes — see
   [Read-only by design](../explanation#read-only-by-design).
+- **No per-query timeout.** Unlike the server's 30-second bound (`408`),
+  a one-shot query runs to completion — the process *is* the query, so
+  cap it from the shell if you want one: `timeout 60 dirsql query "<sql>"`
+  (see `timeout(1)`).
 
 #### `--on-file <command>`
 

{dirsql-0.4.16 → dirsql-0.4.18}/docs/reference/config.md

@@ -1,11 +1,13 @@
 # Configuration file (`.dirsql.toml`)
 
 `.dirsql.toml` is a TOML file with one optional `[dirsql]` section, zero or
-more `[[dirsql.extension]]` entries, and zero or more `[[table]]` entries.
+more `[[dirsql.extension]]` entries, zero or more `[[dirsql.function]]`
+entries, and zero or more `[[table]]` entries.
 An empty file is valid. A missing `[dirsql]` section behaves as an
 all-defaults one. Unknown keys are a parse error at every level (top level,
-`[dirsql]`, `[[table]]`, `[[dirsql.extension]]`) — a typo or a removed key
-fails loudly, naming the offending key, rather than silently no-opping.
+`[dirsql]`, `[[table]]`, `[[dirsql.extension]]`, `[[dirsql.function]]`) — a
+typo or a removed key fails loudly, naming the offending key, rather than
+silently no-opping.
 
 The [CLI](./cli.md) loads a config only when you pass it with `-c/--config`;
 with none given [no named tables](./cli.md#configless-mode) are defined (a
@@ -23,7 +25,12 @@ 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. |
-| `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). |
+
+There is no timeout key. `on-file` hook runs are unbounded; to bound one, wrap
+its command in `timeout(1)` (see [Command hooks](./hooks.md#bounding-a-hook)).
+A config that still declares the removed `hook-timeout` key fails to load with
+an error naming that replacement. [`[[dirsql.function]]`](#dirsql-function)
+worker calls have their own per-call `timeout` key (default 30 seconds).
 
 The top-level `.dirsql/` directory under the root is always excluded from
 scanning, whether or not it appears in `ignore` — it is reserved for
@@ -34,7 +41,6 @@ directory.
 ```toml
 [dirsql]
 ignore = ["node_modules/**", ".git/**"]
-hook-timeout = 300
 ```
 
 Persistence is not a config key. Keep the SQLite index on disk between runs
@@ -86,6 +92,72 @@ extension-backed **virtual table** cannot be declared as a `[[table]]` —
 `dirsql` tables are per-file row tables, so a `CREATE VIRTUAL TABLE` DDL is
 rejected; call the extension's functions in queries instead.
 
+## `[[dirsql.function]]`
+
+Each entry declares a **worker-backed SQL scalar function**: a function
+queries can call by name, whose values are computed by an external worker
+process you (or a [plugin](../plugins.md)) provide. This is how a plugin adds
+computed values — an embedding, a hash, a classification — to SQL without
+`dirsql` knowing anything about the domain: the config names the function and
+the command, the worker does the work. The first-party
+[`dirsql-plugin-embeddings`](../plugins.md#dirsql-plugin-embeddings) declares
+its `embed()` function exactly this way.
+
+| Key | Required | Description |
+|---|---|---|
+| `name` | yes | The SQL name queries call. Must be a plain identifier — an ASCII letter or underscore followed by ASCII letters, digits, or underscores. |
+| `args` | yes | The accepted arities (argument counts), each `0`–`127`. The function is registered once per listed arity, so `args = [1, 2]` makes both `f(x)` and `f(x, y)` callable and any other count a SQL error. An empty list, an out-of-range value, or a repeated value is a config error. |
+| `command` | yes (non-empty) | The worker command. Argv-split with the same no-shell quoting rules as [command hooks](./hooks.md#argv-not-a-shell); runs in the config file's directory. |
+| `deterministic` | no (default `false`) | When `true`, the function is registered with `SQLITE_DETERMINISTIC`, letting SQLite cache and reuse results for identical arguments within a query. Only set it when the worker really is a pure function of its arguments. |
+| `timeout` | no | Per-**call** time bound: a positive integer is whole seconds (`timeout = 600`), a string is an integer suffixed `s` or `ms` (`"600s"`, `"250ms"`). When absent, the function mechanism's own 30-second default applies. |
+
+```toml
+[[dirsql.function]]
+name          = "embed"
+args          = [1, 2]
+command       = "dirsql-plugin-embeddings worker"
+deterministic = true
+timeout       = "600s"   # generous: absorbs a first-call model download
+```
+
+### Worker lifecycle
+
+Declaring a function is **inert**: at startup the function is registered on
+the connection and nothing else happens. No process is spawned and nothing is
+read until a query actually calls the function — a declared function nobody
+calls costs nothing.
+
+On the **first call**, `dirsql` spawns `command` and keeps that one worker
+process alive for the rest of the invocation, sending it every subsequent
+call — one process total, never one per row or per file. The worker is torn
+down when the invocation ends.
+
+The `timeout` bounds each **round-trip call**, not the query: a query that
+calls the function on 10 000 rows is 10 000 individually timed calls. A call
+that times out, or a worker that crashes or closes its pipes, fails the query
+with an actionable error naming the function and command; the worker is
+killed and the next call starts a fresh one.
+
+Calling a function that no loaded config declares (say, the plugin providing
+it is not installed) is SQLite's ordinary `no such function` error.
+
+### Worker protocol
+
+The worker speaks **newline-delimited JSON** over its stdin/stdout — one
+request line in, one response line out, per call:
+
+- **Request:** `{"call": [<arg>, ...]}` with the call's SQL arguments
+  encoded as: TEXT → JSON string, INTEGER/REAL → JSON number, NULL → `null`,
+  BLOB → `{"$bytes": "<base64>"}`.
+- **Response:** `{"ok": <value>}` with the same scalar encodings — a JSON
+  array or any other object is bound as TEXT, its JSON text (which is how an
+  embedding worker returns a vector: `sqlite-vec`'s distance functions accept
+  JSON-text vectors) — or `{"err": "message"}`, which **fails the query**
+  with that message. An `{"err": ...}` response leaves the healthy worker
+  running; only transport failures (timeout, crash) recycle it.
+- **stderr passes through** to `dirsql`'s stderr, so a worker's progress
+  bars and download logs reach the terminal.
+
 ## `[[table]]`
 
 Each entry maps a glob pattern to a SQL table. A table's columns are exactly
@@ -143,16 +215,18 @@ dirsql -c ./.dirsql.toml -c ~/team/embeddings.toml -c ./local.toml
 
 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` 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.
+- **`[[table]]`, `ignore`, `[[dirsql.extension]]`, and `[[dirsql.function]]`
+  entries accumulate** across all configs, in order.
+- **Each config's `on-file` hooks and `[[dirsql.function]]` workers run from
+  that config file's own directory** — 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
-  error**, naming the table.
+  below apply per file). There is no cross-file merge validation, with two
+  structural exceptions: **two configs defining a table of the same name is
+  an error**, naming the table, and **two configs declaring a function of the
+  same name is an error**, naming the function and both sources — never a
+  silent last-writer-wins.
 
 The index [root](./cli.md#flags) is the invocation directory regardless of where
 any config lives. With no `-c`, [no named tables](./cli.md#configless-mode) are
@@ -174,20 +248,32 @@ 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.
-- `hook-timeout` is zero or negative.
+- A `[[dirsql.function]]` entry omits `name`, `command`, or `args` (or
+  `command` is empty/whitespace); its `name` is not a plain identifier; its
+  `args` list is empty, repeats an arity, or lists one outside `0`–`127`; or
+  its `timeout` is not positive whole seconds / a positive-integer `"...s"` or
+  `"...ms"` string.
+- `[dirsql]` declares the removed `hook-timeout` key (the error names the
+  `timeout(1)` replacement).
 
 ## Full example
 
 ```toml
 [dirsql]
 ignore = ["node_modules/**", ".git/**", "dist/**"]
-hook-timeout = 120
 
 [[dirsql.extension]]
 path       = "sqlite_vec"            # Python module name; on Node use the
                                      # platform package, e.g. sqlite-vec-linux-x64
 entrypoint = "sqlite3_vec_init"
 
+[[dirsql.function]]
+name          = "embed"
+args          = [1, 2]
+command       = "dirsql-plugin-embeddings worker"
+deterministic = true
+timeout       = "600s"
+
 [[table]]
 ddl     = "CREATE TABLE comments (author TEXT, body TEXT)"
 glob    = "_comments/*/*.jsonl"

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

@@ -58,18 +58,30 @@ everything above the last line. `jq` users: pass `-c` so the JSON is emitted
 compactly on one line.
 :::
 
-### Timeout
+### Bounding a hook
 
-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:
+Hook runs are **unbounded** — `dirsql` imposes no timeout of its own. To
+bound a hook, make the bound part of the command by wrapping it in
+`timeout(1)`:
 
 ```toml
-[dirsql]
-hook-timeout = 300   # positive whole seconds
+on-file = "timeout 30 my-extractor {path}"
 ```
 
-Zero and negative values are a config error.
+When the wrapper kills an overrunning command, the run exits non-zero and
+the ordinary [failure semantics](#failure-semantics) apply — the file is
+skipped, the scan continues.
+
+::: warning Windows
+Windows's built-in `timeout` command is a *sleep*, not a bound — it cannot
+wrap another command. On Windows, bound the work inside the command itself
+(or accept unbounded runs).
+:::
+
+[`[[dirsql.function]]`](./config.md#dirsql-function) worker calls are
+different: a call is a round-trip on a persistent worker process, which
+`timeout(1)` cannot express, so the function mechanism carries its own
+per-call `timeout` key with a 30-second default.
 
 ### Failure semantics
 
@@ -77,8 +89,8 @@ A hook run fails when the command:
 
 - cannot be spawned (e.g. the program is not found),
 - exits non-zero (the exit code — or `signal`, if killed by one — and the
-  stderr tail are reported),
-- exceeds the timeout (killed; stderr tail reported),
+  stderr tail are reported; a `timeout(1)` wrapper killing an overrun lands
+  here),
 - exits zero but prints no non-empty stdout line,
 - or prints output that does not parse as a JSON array of row objects.
 

{dirsql-0.4.16 → dirsql-0.4.18}/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.16"
+version = "0.4.18"
 # 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

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

@@ -54,6 +54,7 @@ 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' },