dirsql 0.4.29 → 0.4.31

package/docs/reference/cli.md

@@ -460,3 +460,47 @@ Turn discovery off with either:
 
 A plugin that declares itself but is missing its module or its `dirsql.toml`
 fragment is a launcher error naming the package — never a silent skip.
+
+## Progress reporting
+
+Building the index over a large tree is not instant: the walk visits every
+file, then each matched file costs one `on-file` round trip plus whatever the
+table's `ddl` fires on insert. On a big corpus that is minutes. dirsql reports
+the two phases on **stderr** while they run:
+
+```
+dirsql: scanning 128413 files
+dirsql: indexing 9204/41231 files (22%)
+```
+
+Each line is rewritten in place. When a phase ends its line is erased and
+replaced by one summary of what it cost:
+
+```
+dirsql: scanned 128413 files in 4.2s
+dirsql: indexed 41231 files in 3m12s
+```
+
+stdout is untouched — it carries the query result and nothing else.
+
+By default this is **terminal-only, and only for work slow enough to wonder
+about**: a phase that finishes in under half a second prints nothing at all,
+and a run whose stderr is a pipe or a file prints nothing regardless of how
+long it takes. `dirsql "…" 2>run.log` and `dirsql "…" | jq` are byte-for-byte
+what they were before.
+
+Override with `DIRSQL_PROGRESS`:
+
+| Value | Effect |
+|---|---|
+| unset, or `auto` | Report only on a terminal, and only once a phase has run for half a second. The default. |
+| `always`, `1`, `true` | Report from the first update, terminal or not. Use it to watch a scan whose stderr is redirected. |
+| `never`, `0`, `false` | Report nothing, ever. |
+
+Values are case-insensitive and surrounding whitespace is ignored; anything
+unrecognized reads as `auto`, so a typo cannot stop a scan from running.
+
+The setting is read by the **core**, not the CLI, so it governs an index built
+from any SDK as well — a Python or TypeScript program that builds a `DirSQL`
+with a terminal attached gets the same two phases on stderr, and the same
+silence when piped.

package/docs/reference/sdk.md

@@ -396,3 +396,22 @@ not fit that range is a hard error, not a lossy conversion: Python raises
 A TypeScript `bigint` **within** `i64` range maps to `INTEGER`. Only a real
 `bytes`/`bytearray` (Python) or `Buffer`/`Uint8Array` (TypeScript) maps to
 `BLOB` — a list/array of integers does not.
+
+## Progress on construction
+
+Constructing a `DirSQL` walks the tree and ingests every matched file, which
+on a large corpus is the slowest thing your program does. The core reports
+both phases on **stderr** while they run, then erases the live line and leaves
+one summary of what each cost:
+
+```
+dirsql: indexed 41231 files in 3m12s
+```
+
+This is terminal-only by default, and only for a phase that runs longer than
+half a second — a program whose stderr is a pipe, a file, or a log collector
+sees nothing, whatever the scan costs. Set `DIRSQL_PROGRESS=never` to
+guarantee silence even on a terminal, or `DIRSQL_PROGRESS=always` to report
+regardless. The full table is in the
+[CLI reference](cli.md#progress-reporting); the setting lives in the shared
+core, so it behaves identically from all three SDKs.

package/package.json

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