dirsql 0.3.122 → 0.3.124

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

@@ -217,7 +217,7 @@ Discovery is deliberately narrow. Know exactly who does what:
   your config still takes ordering precedence
   ([composing configs](../reference/config.md#composing-multiple-configs)). When
   you pass no `-c` of your own, the launcher also keeps the
-  shipped starter `files` table (an internal `--include-default`), so plugins
+  shipped starter `records` table (an internal `--include-default`), so plugins
   **add** tables rather than standing alone. Discovery is **pip/uvx only** for now — the `npx`
   launcher does not yet discover — and is switched off per invocation with
   [`--no-plugin` or `DIRSQL_NO_PLUGIN=1`](../reference/cli.md#plugins).

package/docs/reference/cli.md

@@ -151,6 +151,25 @@ uses**, so behavior is identical to `POST /query` by construction:
   statements; dirsql separately never modifies the files it indexes — see
   [Read-only by design](../explanation#read-only-by-design).
 
+#### `--on-file <command>`
+
+Attach a parser to every [path-table](./path-tables.md#parsing-rows-with-on-file)
+in the query, so each matched file yields the rows the command prints (a JSON
+array of row objects) instead of the stat columns:
+
+```sh
+dirsql query "SELECT title, author FROM './posts/*.md'" \
+  --on-file 'extract.py {path}'
+```
+
+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
+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
+argument.
+
 Errors print the same diagnostic the HTTP `{"error": …}` body carries —
 config failures, SQL errors, rejected reads, hook failures, timeouts — to
 stderr, with exit code `1`.
@@ -164,8 +183,11 @@ stderr, with exit code `1`.
 
 ## `dirsql init`
 
-Writes a starter `.dirsql.toml` defining a catch-all `files` table, as a
-scaffold to edit:
+Writes a starter `.dirsql.toml` as a scaffold to edit. It does **not**
+duplicate the zero-config floor (`SELECT * FROM './'` already lists every file
+with no config); instead it shows the **escalation**: one named `[[table]]`
+with a glob, a schema, and a real `on-file` hook that pulls structured rows
+out of your files.
 
 ```bash
 dirsql init
@@ -206,7 +228,7 @@ installed in the same environment as `dirsql` (`pip install …`, or
 loads its fragment — its tables are queryable with zero config edits.
 Installed = active: there is no enable step and no naming convention. The
 fragment is composed *after* your own `-c` configs (so your config takes
-precedence in ordering), and the shipped starter `files` table is preserved.
+precedence in ordering), and the shipped starter `records` table is preserved.
 
 Discovery is **launcher-only** — the standalone `cargo`-installed binary does no
 discovery, and the SDKs never auto-discover (pass a plugin's config explicitly

package/docs/reference/path-tables.md

@@ -114,6 +114,39 @@ SELECT path FROM './docs/*.md' WHERE content LIKE '%deprecated%';
 A file that cannot be read, or is not valid UTF-8, yields `NULL` content rather
 than failing the query.
 
+## Parsing rows with `--on-file`
+
+By default a path-table's columns are the stat columns above — one row per
+file. When you want *one row per record inside* each file, attach a parser with
+the `dirsql query` flag [`--on-file`](/reference/cli):
+
+```sh
+dirsql query "SELECT title, author FROM './posts/*.md'" \
+  --on-file 'extract.py {path}'
+```
+
+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 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.
+- **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
+  scan continues. The schema is inferred from the files that did parse.
+- **The skip rules still apply.** A parsed scan honors the same `node_modules`
+  /`.git`/`ignore` rules a stat scan does (see below).
+
+`--on-file` applies to **every** path-table in the query and may be given **at
+most once**. For different parsers per file set, define named tables in a
+`.dirsql.toml` with their own `on-file` keys and pass it with `-c` — the flag
+never touches config-declared tables. It is a `query`-subcommand flag; server
+mode does not accept it.
+
 ## Freshness and scope
 
 A path-table is scanned when the statement runs, so it always reflects the

package/package.json

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