dirsql 0.3.119__tar.gz → 0.3.120__tar.gz

{dirsql-0.3.119 → dirsql-0.3.120}/Cargo.lock

@@ -500,7 +500,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.3.119"
+version = "0.3.120"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.3.119 → dirsql-0.3.120}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.119
+Version: 0.3.120
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index
 Author: Kevin Scott

{dirsql-0.3.119 → dirsql-0.3.120}/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).

{dirsql-0.3.119/packages/python → dirsql-0.3.120}/docs/reference/cli.md

@@ -183,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
@@ -225,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

{dirsql-0.3.119 → dirsql-0.3.120}/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.3.119"
+version = "0.3.120"
 # abi3 note: the `abi3-py311` pyo3 feature (below) builds ONE stable-ABI
 # `cp311-abi3` wheel per platform that loads on every CPython >= 3.11
 # (matching `pyproject.toml`'s `requires-python = ">=3.11"`), instead of

{dirsql-0.3.119/packages/rust → dirsql-0.3.120/packages/python}/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).

{dirsql-0.3.119/packages/rust → dirsql-0.3.120/packages/python}/docs/reference/cli.md

@@ -183,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
@@ -225,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

dirsql-0.3.120/packages/python/e2e-attestations/feat-637-init-escalation-example.json

@@ -0,0 +1,7 @@
+{
+  "command": "just test-e2e",
+  "ran_at": 1784825108,
+  "exit_code": 0,
+  "commit": "6b2c6696cfbf87c61a1e4d57c5f0acd6c65fb50d",
+  "branch": "feat/637-init-escalation-example"
+}

dirsql-0.3.120/packages/rust/changelog.d/2026-07-23-init-escalation-example.md

@@ -0,0 +1,10 @@
+**Changed** — `dirsql init` now scaffolds an *escalation* example instead of a
+catch-all `files` table. Because any path (`./`, `../`, `/`, `~/`) is already a
+zero-config live view of the filesystem (`SELECT * FROM './'`), duplicating
+that as a starter table taught nothing. The generated `.dirsql.toml` is now a
+single named `[[table]]` (`records`) with a scoped `glob`, a pinned DDL, and a
+real `on-file = "cat {path}"` hook that turns each matched `*.json` file into
+rows — with a commented custom-parser stub and a header comment pointing at the
+zero-config floor. The scaffold works as written: `dirsql init` then
+`dirsql query "SELECT * FROM records" -c .dirsql.toml` returns the parsed rows.
+The `--include-default` launcher path seeds this same table.

{dirsql-0.3.119/packages/python → dirsql-0.3.120/packages/rust}/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).

{dirsql-0.3.119 → dirsql-0.3.120/packages/rust}/docs/reference/cli.md

@@ -183,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
@@ -225,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

dirsql-0.3.120/packages/rust/migrations.d/2026-07-23-init-escalation-example.md

@@ -0,0 +1,64 @@
+### `dirsql init` output rewritten as an escalation example (#637)
+
+#### Summary
+
+`dirsql init` no longer writes a catch-all `files` table over `**/*` with a
+stat-column schema. That table only duplicated the zero-config path-table floor
+(`SELECT * FROM './'`), which already lists every file with `path`, `basename`,
+`dir`, `ext`, `size`, `mtime` and `ctime` and no config at all. The generated
+`.dirsql.toml` is now an **escalation** scaffold: one named `[[table]]`
+(`records`) with a scoped `glob = "**/*.json"`, a pinned
+`ddl = "CREATE TABLE records (id TEXT, name TEXT)"`, and a real
+`on-file = "cat {path}"` hook whose rows come entirely from the hook (dirsql
+injects no columns). The internal `--include-default` launcher path seeds this
+same table's glob and DDL.
+
+The public `init` contract is otherwise unchanged: `--root`, `--output`,
+`--force`, the no-auto-load behavior, and every exit-code / error arm are the
+same. Only the *bytes written* changed.
+
+Carrying a genuine `on-file` hook keeps the shipped asset a valid config both
+today and once hook-less `[[table]]` entries become a load error, so
+`--include-default` (which parses the asset with `.expect(...)`) never panics.
+
+#### Required changes
+
+| Surface | Before | After |
+| ------- | ------ | ----- |
+| Query the init scaffold | `dirsql query "SELECT * FROM files" -c .dirsql.toml` | `dirsql query "SELECT * FROM records" -c .dirsql.toml` |
+| Want the old `files` table | (what `init` emitted) | write it yourself (snippet below) and pass with `-c` |
+
+To restore the previous starter table verbatim, write this `.dirsql.toml` and
+pass it explicitly:
+
+```toml
+[[table]]
+ddl  = "CREATE TABLE files (path TEXT, basename TEXT, dir TEXT, ext TEXT, size INTEGER, mtime INTEGER, ctime INTEGER)"
+glob = "**/*"
+```
+
+Note: this hook-less form loads today but is on track to become a config error;
+prefer the zero-config `SELECT * FROM './'` for filesystem listings.
+
+#### Deprecations removed
+
+_None._
+
+#### Behavior changes without code changes
+
+- `dirsql init` writes different bytes: a `records` escalation example rather
+  than a `files` catch-all table. No flags or exit codes changed.
+- `--include-default` now seeds a `records` table (glob `**/*.json`) instead of
+  a `files` table (glob `**/*`).
+
+#### Verification
+
+```bash
+cd "$(mktemp -d)"
+printf '[{"id":"1","name":"widget"}]' > things.json
+dirsql init
+dirsql query "SELECT id, name FROM records" -c .dirsql.toml
+# [{"id":"1","name":"widget"}]
+dirsql query "SELECT basename FROM './'"    # the zero-config floor still needs no config
+# [{"basename":".dirsql.toml"},{"basename":"things.json"}]
+```

{dirsql-0.3.119 → dirsql-0.3.120}/packages/rust/src/bin/dirsql.rs

@@ -75,7 +75,7 @@ struct ConfigArgs {
     config: Vec<PathBuf>,
 
     /// Internal (launcher-only): seed the resolved config set with the shipped
-    /// starter `files` table *before* the `-c` configs, so an explicit `-c`
+    /// starter `records` table *before* the `-c` configs, so an explicit `-c`
     /// composes with it instead of standing alone. `--include-default -c
     /// <plugin>` yields that table **plus** the plugin's tables — the additive
     /// composition the plugin launcher (#529) injects for the no-user-`-c`
@@ -328,14 +328,14 @@ fn load_state(cfg: &ConfigArgs, path_table_parser: Option<String>) -> AppState {
     }
 
     let mut builder = DirSQL::builder();
-    // `--include-default` seeds the shipped starter `files` table before the
+    // `--include-default` seeds the shipped starter `records` table before the
     // `-c` configs, so an explicit config composes with it instead of standing
     // alone (#604). Programmatic tables sort before config tables in
-    // `resolve`, giving `[starter] ++ [-c]`; a starter-vs-config `files`
+    // `resolve`, giving `[starter] ++ [-c]`; a starter-vs-config `records`
     // collision hits the existing dedup in `compile_matcher`. With no `-c` at
     // all the flag still applies, yielding just the starter table.
     if cfg.include_default {
-        builder = builder.table(default_files_table());
+        builder = builder.table(default_records_table());
     }
     for config_path in &cfg.config {
         // Canonicalize so config-relative paths (extension libraries, hook
@@ -487,11 +487,11 @@ fn load_configless_state(cfg: &ConfigArgs, path_table_parser: Option<String>) ->
     }
 }
 
-/// The shipped starter `files` table, parsed from the [`dirsql::DEFAULT_CONFIG_TOML`]
+/// The shipped starter `records` table, parsed from the [`dirsql::DEFAULT_CONFIG_TOML`]
 /// asset `dirsql init` writes. Used only by the explicit `--include-default`
 /// compose path (#604), which seeds it as a programmatic table *before* the
 /// `-c` configs. There is no implicit no-`-c` fallback (#636).
-fn default_files_table() -> Table {
+fn default_records_table() -> Table {
     let config = dirsql::config::load_config_str(dirsql::DEFAULT_CONFIG_TOML)
         .expect("DEFAULT_CONFIG_TOML must be valid dirsql config TOML");
     let table_config = &config.tables[0];

{dirsql-0.3.119 → dirsql-0.3.120}/packages/rust/src/cli/init.rs

@@ -2,10 +2,11 @@
 //! `docs/reference/cli.md` for the user-facing contract.
 //!
 //! `init` does not inspect the target directory at all: it writes
-//! [`super::DEFAULT_CONFIG_TOML`] verbatim -- the same single `files` table
-//! [zero-config mode](../bin/dirsql.rs) parses that same asset to build --
-//! so a user always has something loadable to hand-edit, and the two
-//! surfaces can never drift apart. No LLM, no network, no filesystem walk.
+//! [`super::DEFAULT_CONFIG_TOML`] verbatim -- the escalation scaffold (a named
+//! `[[table]]` with glob, DDL, and a real `on-file` hook) that the
+//! `--include-default` launcher path also seeds from -- so a user always has
+//! a loadable, working config to hand-edit, and the two surfaces can never
+//! drift apart. No LLM, no network, no filesystem walk.
 
 use std::path::PathBuf;
 

dirsql-0.3.120/packages/rust/src/default_config.toml

@@ -0,0 +1,33 @@
+# You do NOT need this file to use dirsql.
+#
+# Any FROM target that starts with ./, ../, /, or ~/ is a live, read-only
+# view of the filesystem -- no config required. To list every file under the
+# current directory:
+#
+#     dirsql query "SELECT * FROM './'"
+#
+# That path-table gives you path, basename, dir, ext, size, mtime and ctime
+# for free, and takes a glob to scope it: "SELECT * FROM './**/*.md'".
+#
+# Reach for a config file only to ESCALATE past that floor: to name a table,
+# scope it, pin a schema, and pull STRUCTURED rows out of your files. The
+# example below does exactly that -- edit it, then run:
+#
+#     dirsql query "SELECT * FROM records" -c .dirsql.toml
+
+[[table]]
+# The files this table is built from (glob, relative to the index root).
+glob = "**/*.json"
+
+# The table's schema. Rows come entirely from the on-file hook below --
+# dirsql injects no columns of its own -- so the hook must emit exactly
+# these fields.
+ddl = "CREATE TABLE records (id TEXT, name TEXT)"
+
+# on-file runs once per matched file, receives its absolute {path}, and
+# prints a JSON array of row objects. Each *.json file here is already such
+# an array, so `cat` is enough. For any other format, point this at your own
+# parser instead -- it just has to read {path} and print the same JSON shape:
+#
+#     on-file = "./parse.py {path}"
+on-file = "cat {path}"

{dirsql-0.3.119 → dirsql-0.3.120}/packages/rust/src/lib.rs

@@ -67,11 +67,12 @@ pub use crate::watcher::FileEvent as RawFileEvent;
 pub type Row = HashMap<String, Value>;
 pub type WatchStream = UnboundedReceiver<RowEvent>;
 
-/// The baked-in default config -- a single `files` table over every file, built
-/// from the seven stat columns. A builder with no `.config()` and no
-/// programmatic tables serves this (parity with the CLI's no-`-c` default,
-/// #603); `dirsql init` writes it verbatim; the CLI serves it directly. One
-/// asset, so the SDK default, the CLI default, and `init` can never drift.
+/// The escalation scaffold `dirsql init` writes verbatim: one named
+/// `[[table]]` (glob + DDL + a real `on-file` hook) demonstrating how to pull
+/// structured rows out of files, rather than duplicating the zero-config
+/// path-table floor (`SELECT * FROM './'`). The `--include-default` launcher
+/// path also seeds this table's glob/DDL. Carrying a genuine hook keeps it a
+/// valid config even once hook-less `[[table]]` entries become a load error.
 pub const DEFAULT_CONFIG_TOML: &str = include_str!("default_config.toml");
 
 type BoxError = Box<dyn StdError + Send + Sync + 'static>;

dirsql-0.3.119/packages/python/e2e-attestations/feat-655-drop-glob-captures.json

@@ -1,7 +0,0 @@
-{
-  "command": "just test-e2e",
-  "ran_at": 1784634695,
-  "exit_code": 0,
-  "commit": "d5dfb6f091ee4270d20067031e22b20ffe356dd9",
-  "branch": "feat/655-drop-glob-captures"
-}

dirsql-0.3.119/packages/rust/src/default_config.toml

@@ -1,3 +0,0 @@
-[[table]]
-ddl  = "CREATE TABLE files (path TEXT, basename TEXT, dir TEXT, ext TEXT, size INTEGER, mtime INTEGER, ctime INTEGER)"
-glob = "**/*"