dirsql 0.4.64 → 0.4.66

package/docs/getting-started.md

@@ -156,11 +156,17 @@ folder name), and prints them as a JSON row:
 ```bash
 cat > note.sh <<'EOF'
 #!/usr/bin/env sh
-title=$(sed -n 's/^# //p' "$1" | head -n1)
-author=$(basename "$(dirname "$1")")
-printf '[{"title":%s,"author":%s}]' \
-  "$(jq -Rn --arg t "$title" '$t')" \
-  "$(jq -Rn --arg a "$author" '$a')"
+printf '['
+sep=''
+for f; do
+  title=$(sed -n 's/^# //p' "$f" | head -n1)
+  author=$(basename "$(dirname "$f")")
+  printf '%s{"title":%s,"author":%s}' "$sep" \
+    "$(jq -Rn --arg t "$title" '$t')" \
+    "$(jq -Rn --arg a "$author" '$a')"
+  sep=','
+done
+printf ']'
 EOF
 ```
 
@@ -172,7 +178,7 @@ cat > .dirsql.toml <<'EOF'
 name = "notes"
 ddl     = "CREATE TABLE notes (title TEXT, author TEXT)"
 glob    = "notes/**/*.md"
-on-file = "sh note.sh {path}"
+on-file = "sh note.sh"
 EOF
 ```
 
@@ -181,9 +187,10 @@ Three keys define the table:
 - `glob` selects which files feed the table — every `.md` at any depth under
   `notes/`, relative to the directory the config sits in.
 - `ddl` is ordinary `CREATE TABLE` SQL naming the columns you want to keep.
-- `on-file` is the command run once per matched file; `{path}` is the file's
-  path, and its printed JSON row becomes the file's row. The columns are
-  exactly what it emits — `title` from the heading, `author` from the folder.
+- `on-file` is the command run once for the table, with every matched file's
+  path appended as an argument; the JSON array it prints is the table's rows.
+  The columns are exactly what it emits — `title` from the heading, `author`
+  from the folder.
 
 ## 5. Query the table
 

package/docs/howto/columns-from-paths.md

@@ -15,18 +15,21 @@ photos/2024/11/hike.jpg
 photos/2025/01/snow.jpg
 ```
 
-Write a small parser, `pathcols.py`, that turns the path into a row. It
-receives the file's absolute path as its argument and prints a JSON array of
-row objects:
+Write a small parser, `pathcols.py`, that turns each path into a row. It
+receives the matched files' absolute paths as its arguments and prints one
+JSON array of row objects:
 
 ```python
 #!/usr/bin/env python3
 import json, os, sys
 
-parts = sys.argv[1].split(os.sep)
-# .../photos/<year>/<month>/<file>
-print(json.dumps([{"year": parts[-3], "month": parts[-2],
-                   "basename": os.path.basename(sys.argv[1])}]))
+rows = []
+for path in sys.argv[1:]:
+    parts = path.split(os.sep)
+    # .../photos/<year>/<month>/<file>
+    rows.append({"year": parts[-3], "month": parts[-2],
+                 "basename": os.path.basename(path)})
+print(json.dumps(rows))
 ```
 
 Point a table at it in `.dirsql.toml`:
@@ -36,12 +39,12 @@ Point a table at it in `.dirsql.toml`:
 name = "photos"
 ddl     = "CREATE TABLE photos (year TEXT, month TEXT, basename TEXT)"
 glob    = "photos/*/*/*.jpg"
-on-file = "python3 pathcols.py {path}"
+on-file = "python3 pathcols.py"
 ```
 
-The hook emits every column the table has — dirsql injects nothing. `{path}`
-is the matched file's absolute path, one of the placeholders in the
-[command hook contract](../reference/hooks.md#on-file). A column appears only
+The hook emits every column the table has — dirsql injects nothing. The
+matched files' absolute paths arrive as the command's trailing arguments, per
+the [command hook contract](../reference/hooks.md#on-file). A column appears only
 because the DDL declares it *and* the hook emits it.
 
 ## 2. Query the derived columns

package/docs/howto/define-tables.md

@@ -10,16 +10,19 @@ persist across restarts, instead of repeating an ad-hoc
 Suppose your blog posts live under `posts/`, one markdown file each. A named
 table needs three keys: a `glob` that selects the files, a `ddl` that names
 the columns, and an [`on-file`](../reference/config.md#table) hook that emits
-each file's rows. Put a small parser next to the config — `extract.py`, which
-reads a post's title line and prints a JSON array of row objects:
+the table's rows. Put a small parser next to the config — `extract.py`, which
+reads each post's title line and prints one JSON array of row objects:
 
 ```python
 #!/usr/bin/env python3
 import json, os, sys
 
-text = open(sys.argv[1], encoding="utf-8").read()
-title = next((l[2:].strip() for l in text.splitlines() if l.startswith("# ")), None)
-print(json.dumps([{"title": title, "slug": os.path.basename(sys.argv[1])[:-3]}]))
+rows = []
+for path in sys.argv[1:]:
+    text = open(path, encoding="utf-8").read()
+    title = next((l[2:].strip() for l in text.splitlines() if l.startswith("# ")), None)
+    rows.append({"title": title, "slug": os.path.basename(path)[:-3]})
+print(json.dumps(rows))
 ```
 
 Then declare the table in `.dirsql.toml`:
@@ -29,15 +32,15 @@ Then declare the table in `.dirsql.toml`:
 name = "posts"
 ddl     = "CREATE TABLE posts (title TEXT, slug TEXT)"
 glob    = "posts/**/*.md"
-on-file = "python3 extract.py {path}"
+on-file = "python3 extract.py"
 ```
 
 - `glob` selects the files: every `.md` under `posts/`, at any depth, relative
   to the directory containing the config.
 - `ddl` is a plain SQLite `CREATE TABLE` naming the columns you want to keep.
 - `on-file` is **required** — it is where the table's rows come from. dirsql
-  injects nothing; the hook emits every column, reading the file (it has
-  `{path}`) and deriving whatever it needs. A `[[table]]` with no `on-file` is
+  injects nothing; the hook emits every column, reading the files (their
+  paths are its arguments) and deriving whatever it needs. A `[[table]]` with no `on-file` is
   a [config error](../reference/config.md#parse-errors). For plain stat
   columns with no code, query the path directly with a path-table instead.
 
@@ -75,7 +78,7 @@ two triggers:
 [[table]]
 name    = "posts"
 glob    = "posts/**/*.md"
-on-file = "python3 extract.py {path}"
+on-file = "python3 extract.py"
 ddl     = '''
 CREATE TABLE posts (title TEXT, slug TEXT, body TEXT);
 CREATE INDEX posts_slug ON posts(slug);

package/docs/howto/extract-from-contents.md

@@ -21,11 +21,11 @@ stdout works. With [`jq`](https://jqlang.org/):
 name = "books"
 ddl     = "CREATE TABLE books (title TEXT, author TEXT, year INTEGER)"
 glob    = "books/*.json"
-on-file = "jq -c '[{title, author, year}]' {path}"
+on-file = "jq -c -n '[inputs | {title, author, year}]'"
 ```
 
-`{path}` is the matched file's absolute path — one of the
-placeholders defined by the
+The command runs once for the table, with every matched file's absolute path
+appended as an argument, and prints one array for all of them — the
 [command hook contract](../reference/hooks.md#on-file), which also covers
 the argv splitting, working directory, stdout protocol, and timeout shared
 by every hook.
@@ -45,7 +45,7 @@ dirsql query "SELECT title, author, year FROM books ORDER BY year" -c ./.dirsql.
 
 The table's columns are exactly what the command emits, narrowed to the DDL —
 `dirsql` adds nothing. To include the file's `path`, have the command emit it
-(it has `{path}`); dirsql will not merge it in for you.
+(it has the path); dirsql will not merge it in for you.
 
 ## Multiple rows per file
 
@@ -57,7 +57,7 @@ row per line, slurp it:
 name = "events"
 ddl     = "CREATE TABLE events (event TEXT, user TEXT)"
 glob    = "logs/*.jsonl"
-on-file = "jq -c -s '.' {path}"
+on-file = "jq -c -s '.'"
 ```
 
 ```bash

package/docs/howto/parse-files-into-columns.md

@@ -32,40 +32,43 @@ To get them, you need a parser.
 
 ## 2. Attach a parser with `--on-file`
 
-Any program that reads one file and prints a **JSON array of row objects** on
-stdout is a parser. Here is a small one, `extract.py`, that reads a post's
-frontmatter:
+Any program that reads the files named by its arguments and prints a **JSON
+array of row objects** on stdout is a parser. Here is a small one,
+`extract.py`, that reads each post's frontmatter:
 
 ```python
 #!/usr/bin/env python3
 import json, re, sys
 
-text = open(sys.argv[1], encoding="utf-8").read()
-m = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
-fields = dict(
-    (k.strip(), v.strip())
-    for k, _, v in (line.partition(":") for line in (m.group(1).splitlines() if m else []))
-)
-print(json.dumps([{"title": fields.get("title"), "author": fields.get("author")}]))
+rows = []
+for path in sys.argv[1:]:
+    text = open(path, encoding="utf-8").read()
+    m = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
+    fields = dict(
+        (k.strip(), v.strip())
+        for k, _, v in (line.partition(":") for line in (m.group(1).splitlines() if m else []))
+    )
+    rows.append({"title": fields.get("title"), "author": fields.get("author")})
+print(json.dumps(rows))
 ```
 
 Point the path-table at it with `--on-file`:
 
 ```bash
 dirsql query "SELECT title, author FROM './posts/*.md' ORDER BY title" \
-  --on-file 'python3 extract.py {path}'
+  --on-file 'python3 extract.py'
 ```
 
 ```json
 [{"author":"Ada Lovelace","title":"Hello World"},{"author":"Alan Turing","title":"On Recursion"}]
 ```
 
-Now the parser's output *is* the table. `--on-file` runs the command once per
-matched file; `{path}` is the file's absolute path, one of the placeholders in
-the shared [`on-file` hook contract](../reference/hooks.md#on-file) (argv
-splitting, timeout, and per-file failure isolation all come from there). The
-stat columns are no longer reachable — a parser that wants the path emits it,
-since it already has `{path}`. See
+Now the parser's output *is* the table. `--on-file` runs the command once,
+with every matched file's absolute path appended as an argument, under the
+shared [`on-file` hook contract](../reference/hooks.md#on-file) (argv
+splitting, timeout, and failure semantics all come from there). The stat
+columns are no longer reachable — a parser that wants the path emits it, since
+it already has the path. See
 [Parsing rows with `--on-file`](../reference/path-tables.md#parsing-rows-with-on-file)
 for the full behavior.
 
@@ -87,7 +90,7 @@ command in verbatim:
 name = "posts"
 ddl     = "CREATE TABLE posts (title TEXT, author TEXT)"
 glob    = "posts/*.md"
-on-file = "python3 extract.py {path}"
+on-file = "python3 extract.py"
 ```
 
 The `on-file` value is byte-for-byte the string you passed to `--on-file`. The
@@ -109,7 +112,7 @@ indexed on build, kept fresh by the watcher, survives restarts with
 [many tables](./define-tables.md) — each with its own `on-file` — where the flag
 gives every path-table one parser. In both spellings the table's columns are
 exactly what the parser emits: `dirsql` merges no filesystem facts back on. A
-row that needs the file's `path` emits it (the parser has `{path}`).
+row that needs the file's `path` emits it (the parser has the path).
 
 ## Going further
 

package/docs/howto/react-to-changes.md

@@ -17,7 +17,7 @@ prints each file's basename:
 name = "files"
 ddl     = "CREATE TABLE files (basename TEXT)"
 glob    = "**/*"
-on-file = '''sh -c 'printf "[{\"basename\":\"%s\"}]" "${1##*/}"' sh {path}'''
+on-file = '''sh -c 'printf "["; sep=""; for p; do printf "%s{\"basename\":\"%s\"}" "$sep" "${p##*/}"; sep=","; done; printf "]"' sh'''
 ```
 
 ## 1. Open the stream

package/docs/howto/search-indexes.md

@@ -31,7 +31,7 @@ external-content index beside the row table and let the two triggers feed it:
 [[table]]
 name    = "notes"
 glob    = "notes/**/*.md"
-on-file = "python3 extract.py {path}"
+on-file = "python3 extract.py"
 ddl     = '''
 CREATE TABLE notes (slug TEXT, title TEXT, body TEXT);
 
@@ -150,7 +150,7 @@ inserted vector for the "embedding" column. Expected 8 dimensions but received 4
 [[table]]
 name    = "notes"
 glob    = "notes/**/*.md"
-on-file = "python3 extract.py {path}"
+on-file = "python3 extract.py"
 ddl     = '''
 CREATE TABLE notes (slug TEXT, title TEXT, body TEXT);
 

package/docs/howto/skip-files.md

@@ -25,7 +25,7 @@ ignore = ["notes/drafts/**", "**/*.tmp"]
 name = "notes"
 ddl     = "CREATE TABLE notes (basename TEXT)"
 glob    = "notes/**/*"
-on-file = '''sh -c 'printf "[{\"basename\":\"%s\"}]" "${1##*/}"' sh {path}'''
+on-file = '''sh -c 'printf "["; sep=""; for p; do printf "%s{\"basename\":\"%s\"}" "$sep" "${p##*/}"; sep=","; done; printf "]"' sh'''
 ```
 
 Patterns match against root-relative paths, the same way table globs do. An

package/docs/howto/write-a-plugin.md

@@ -73,11 +73,11 @@ Both hook command styles from the [hook contract](../reference/hooks.md) work
 in a plugin fragment:
 
 - **Console scripts** — a `bin`-style entry point your package installs on
-  `PATH` (`embed-file {path} {root}`). Recommended for published plugins: the command
+  `PATH` (`embed-file {root}`). Recommended for published plugins: the command
   is bound to your package's interpreter and dependencies, and it is
   language-neutral (the fragment names a command, not a Python file).
 - **Relative scripts** — a path resolved against the fragment's own directory
-  (`uv run python embed.py {path}`). Convenient while developing the plugin
+  (`uv run python embed.py {root}`). Convenient while developing the plugin
   in-tree.
 
 Two facts from the [execution contract](../reference/hooks.md#execution-contract)
@@ -85,12 +85,12 @@ matter most for a published plugin:
 
 - **A hook runs in its declaring config's directory.** For a plugin that is
   the installed fragment's directory — inside **site-packages**. That is a
-  read-only, shared location: **run from it, never write to it.** Use the
-  absolute [`{path}`](../reference/hooks.md#on-file) placeholder to read the
-  matched file, and [`{root}`](../reference/hooks.md#on-file) to reach the
-  user's project directory. Write any cache to `{root}` or a real cache dir,
+  read-only, shared location: **run from it, never write to it.** Read the
+  matched files from the absolute paths the hook appends as arguments, and use
+  [`{root}`](../reference/hooks.md#on-file) to reach the user's project
+  directory. Write any cache to `{root}` or a real cache dir,
   never next to the fragment.
-- **`{path}` is absolute and `{root}` is the index root**, so a command is
+- **The paths are absolute and `{root}` is the index root**, so a command is
   self-sufficient from any working directory — it works whether the plugin
   lives in the project or in site-packages.
 
@@ -112,28 +112,30 @@ entrypoint = "sqlite3_vec_init"
 name = "notes"
 ddl     = "CREATE TABLE notes (path TEXT, text TEXT, embedding TEXT)"
 glob    = "notes/*.md"
-on-file = "uv run --with model2vec python embed.py {path} {root}"
+on-file = "uv run --with model2vec python embed.py {root}"
 ```
 
-`embed.py` turns one file into one row carrying its path, text, and embedding.
-dirsql injects no columns, so the script emits the path itself, from the
-`{path}`/`{root}` the hook passes in:
+`embed.py` turns each file into one row carrying its path, text, and
+embedding. dirsql injects no columns, so the script emits the path itself,
+from the `{root}` the hook passes in and the paths it appends:
 
 ```python
-"""Embed one file's text; print a dirsql row array on stdout."""
+"""Embed each file's text; print one 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()
+root, paths = sys.argv[1], sys.argv[2:]
+texts = [open(path, encoding="utf-8").read() for path in paths]
 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]))
+rows = [
+    {"path": os.path.relpath(path, root), "text": text,
+     "embedding": json.dumps([round(float(x), 6) for x in vector])}
+    for path, text, vector in zip(paths, texts, model.encode(texts))
+]
+print(json.dumps(rows))
 ```
 
 The relative `embed.py` above resolves against the fragment directory, which

package/docs/reference/cli.md

@@ -370,12 +370,12 @@ array of row objects) instead of the stat columns:
 
 ```sh
 dirsql query "SELECT title, author FROM './posts/*.md'" \
-  --on-file 'extract.py {path}'
+  --on-file 'extract.py'
 ```
 
 The command follows the [`on-file` hook contract](./hooks.md#on-file) — argv
-splitting, `{path}`/`{root}` placeholders, per-file failure isolation, and the
-timeout. The parser's output is the whole schema; the stat columns are not
+splitting, the `{root}` placeholder, every matched path as a trailing
+argument, the failure semantics, and the timeout. The parser's output is the whole schema; the stat columns are not
 reachable on a parsed path-table. `--on-file` may be given **at most once** (a
 repeat is an error pointing at config files) and never touches config-declared
 tables. It is a `query`-only flag — server mode rejects it as an unknown

package/docs/reference/columns.md

@@ -12,8 +12,8 @@ A named [`[[table]]`](./config.md#table) — or an SDK
 [`on-file` hook](./hooks.md#on-file) emits, narrowed to the columns the DDL
 declares. dirsql adds nothing on top: no `path`, no `size`, no value derived
 from the filename. A hook that wants any of those computes them itself. The
-hook receives the file's `{path}` (an SDK `on_file` callback receives the same
-path as its argument) and may stat or read the file however it likes.
+hook receives every matched file's path as an argument (an SDK `on_file`
+callback receives one path) and may stat or read the files however it likes.
 
 The hook is **required**. A `[[table]]` with no `on-file` is a
 [config-load error](./config.md#parse-errors): with nothing supplying columns,
@@ -58,12 +58,12 @@ ORDER BY mtime DESC;
 [Attaching a parser](./path-tables.md#parsing-rows-with-on-file) to a
 path-table with `--on-file` **replaces** these stat columns with the parser's
 own output — the two modes stay cleanly separate, exactly as for a named
-table. A parser that wants the path emits it; it has `{path}`.
+table. A parser that wants the path emits it; it has the paths.
 
 ## Deriving columns from the path
 
 To turn path segments (an author, a year, a thread id) into columns, a hook
-splits `{path}` and emits the pieces — the same as any other column it
+splits the path and emits the pieces — the same as any other column it
 produces. dirsql does not do this for you: a `{name}` segment in a glob is
 rewritten to `*` and matches a single path segment, but captures no value.
 [Derive columns from file paths](../howto/columns-from-paths.md) walks a

package/docs/reference/config.md

@@ -221,12 +221,12 @@ what its required `on-file` command emits — dirsql injects nothing (see
 | `name` | yes | The table's SQL name — the name you query it by. Declared, never derived from `ddl`: dirsql does not read the DDL text. The `ddl` must create a table by this name; if it doesn't, loading fails. |
 | `ddl` | yes | A SQL batch, run verbatim — any number of statements. It must create a table called `name`; that table holds the file rows, and only the columns it declares are kept (keys the `on-file` command emits that are not declared are dropped). The rest of the batch is yours: indexes, virtual tables, triggers. See [Batch `ddl`](#batch-ddl). |
 | `glob` | yes | Glob pattern matched against root-relative paths. Every table whose glob matches a file receives that file's rows — a file can populate multiple tables. A `{name}` segment is rewritten to `*` (it matches one path segment but captures nothing). |
-| `on-file` | **yes** | A command run once per matched file; its stdout (a JSON array of row objects) becomes the file's rows. Must be non-empty. A `[[table]]` with no `on-file` is a load error (see [parse errors](#parse-errors)). See [Command hooks](./hooks.md#on-file). |
+| `on-file` | **yes** | A command run once per table, with every matched file's absolute path appended as a trailing argument; its stdout (one JSON array of row objects) is the table's rows. Must be non-empty. A `[[table]]` with no `on-file` is a load error (see [parse errors](#parse-errors)). See [Command hooks](./hooks.md#on-file). |
 | `strict` | no (default `false`) | When `true`, rows whose keys do not exactly match the declared columns are rejected with an error: extra keys error, and every declared column must be supplied by the `on-file` output. When `false`, extra keys are dropped and missing columns become `NULL`. |
 
 `on-file` is required because a table's rows come from nowhere else. dirsql
 does not read file contents or merge filesystem facts on your behalf: the
-command reads the file (it receives `{path}`) and prints the rows, and those
+command reads the files (it receives their paths as arguments) and prints the rows, and those
 rows — filtered to the DDL — are the table. For plain stat columns with no
 command, query the path directly with a [path-table](./path-tables.md)
 instead of declaring a table.
@@ -236,13 +236,13 @@ instead of declaring a table.
 name = "comments"
 ddl     = "CREATE TABLE comments (path TEXT, author TEXT, body TEXT)"
 glob    = "_comments/*/*.jsonl"
-on-file = "jq -c -s '.' {path}"
+on-file = "jq -c -s '.'"
 
 [[table]]
 name = "papers"
 ddl     = "CREATE TABLE papers (paper_id TEXT, title TEXT)"
 glob    = "**/meta.json"
-on-file = "uv run python extract_papers.py {path}"
+on-file = "uv run python extract_papers.py"
 strict  = true
 ```
 
@@ -255,7 +255,7 @@ statement:
 [[table]]
 name    = "messages"
 glob    = "sessions/*/messages/*.json"
-on-file = "jq -c '.' {path}"
+on-file = "jq -c -s add"
 ddl     = '''
 CREATE TABLE messages (session TEXT, idx INT, role TEXT, text TEXT);
 CREATE INDEX messages_session ON messages(session);
@@ -419,11 +419,11 @@ timeout       = "600s"
 name = "comments"
 ddl     = "CREATE TABLE comments (author TEXT, body TEXT)"
 glob    = "_comments/*/*.jsonl"
-on-file = "jq -c -s '.' {path}"
+on-file = "jq -c -s '.'"
 
 [[table]]
 name = "documents"
 ddl     = "CREATE TABLE documents (title TEXT, summary TEXT)"
 glob    = "**/index.md"
-on-file = "uv run python extract_doc.py {path}"
+on-file = "uv run python extract_doc.py"
 ```

package/docs/reference/hooks.md

@@ -10,7 +10,7 @@ external command under the execution contract below.
 
 The command string is split into an argv with shell-like quoting: whitespace
 separates arguments, and single or double quotes group them (so
-`sh -c 'grep foo {path} | sort'` keeps the quoted script as a single
+`sh -c 'grep foo "$@" | sort' sh` keeps the quoted script as a single
 argument). **No shell is invoked** — there is no globbing, piping, `$VAR`
 expansion, or `&&`/`;` chaining. To get shell features, ask for a shell
 explicitly with `sh -c '…'`.
@@ -65,7 +65,7 @@ bound a hook, make the bound part of the command by wrapping it in
 `timeout(1)`:
 
 ```toml
-on-file = "timeout 30 my-extractor {path}"
+on-file = "timeout 30 my-extractor"
 ```
 
 When the wrapper kills an overrunning command, the run exits non-zero and
@@ -117,9 +117,14 @@ flag is the inline form, the config key the declared form (see
 [Parse your files into columns](../howto/parse-files-into-columns.md)). In both
 spellings the table's columns are exactly what the command emits, narrowed to
 the DDL — `dirsql` injects no filesystem facts either way. A command that wants
-the path or stat metadata emits it (it has `{path}`).
+the path or stat metadata emits it (it has the paths).
 
 | Placeholder | Value |
 |---|---|
-| `{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})`. |
+| `{root}` | The index root directory. Derive a root-relative path with `relpath(path, {root})`. |
+
+The matched files' **absolute** paths are not placeholders: they are appended
+to the command as trailing arguments, after everything written in the
+command, so `on-file = "extract.py"` receives them as `sys.argv[1:]` — one run
+per table, self-sufficient from any working directory. A command that still
+spells `{path}` is rejected at startup.

package/docs/reference/path-tables.md

@@ -139,18 +139,18 @@ the `dirsql query` flag [`--on-file`](/reference/cli):
 
 ```sh
 dirsql query "SELECT title, author FROM './posts/*.md'" \
-  --on-file 'extract.py {path}'
+  --on-file 'extract.py'
 ```
 
-The command runs once per matched file and prints a JSON array of row objects,
-exactly like a declared table's [`on-file` hook](/reference/hooks) — same argv
-splitting, same `{path}`/`{root}` placeholders, same timeout. Its output *is*
-the table:
+The command runs once, with every matched file's absolute path appended as an
+argument, and prints one JSON array of row objects, exactly like a declared
+table's [`on-file` hook](/reference/hooks) — same argv splitting, same `{root}`
+placeholder, same timeout. Its output *is* the table:
 
 - **The parser supplies the whole schema.** Columns are inferred from the keys
   across the emitted rows. The stat columns (`path`, `size`, …) are **not**
   reachable on a parsed path-table — a parser that wants the path emits it (it
-  has `{path}`). The two modes stay cleanly separate.
+  has the paths). The two modes stay cleanly separate.
 - **Failures are isolated per file.** A file whose parser fails (spawn, non-zero
   exit, timeout, or no output) or whose output is not a JSON array of rows
   contributes no rows; a one-line warning naming the file goes to stderr and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.4.64",
+  "version": "0.4.66",
   "description": "Ephemeral SQL index over a local directory",
   "license": "MIT",
   "repository": "https://github.com/thekevinscott/dirsql",
@@ -221,10 +221,10 @@
     ]
   },
   "optionalDependencies": {
-    "@dirsql/lib-linux-x64-gnu": "0.4.64",
-    "@dirsql/lib-linux-arm64-gnu": "0.4.64",
-    "@dirsql/lib-darwin-x64": "0.4.64",
-    "@dirsql/lib-darwin-arm64": "0.4.64",
-    "@dirsql/lib-win32-x64-msvc": "0.4.64"
+    "@dirsql/lib-linux-x64-gnu": "0.4.66",
+    "@dirsql/lib-linux-arm64-gnu": "0.4.66",
+    "@dirsql/lib-darwin-x64": "0.4.66",
+    "@dirsql/lib-darwin-arm64": "0.4.66",
+    "@dirsql/lib-win32-x64-msvc": "0.4.66"
   }
 }