dirsql 0.4.55__tar.gz → 0.4.57__tar.gz

{dirsql-0.4.55 → dirsql-0.4.57}/Cargo.lock

@@ -552,7 +552,7 @@ checksum = "6184e33543162437515c2e2b48714794e37845ec9851711914eec9d308f6ebe8"
 
 [[package]]
 name = "dirsql"
-version = "0.4.55"
+version = "0.4.57"
 dependencies = [
  "assert_cmd",
  "axum",
@@ -592,6 +592,7 @@ name = "dirsql-napi"
 version = "0.1.0"
 dependencies = [
  "dirsql",
+ "libc",
  "napi",
  "napi-build",
  "napi-derive",
@@ -599,7 +600,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.4.55"
+version = "0.4.57"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.4.55 → dirsql-0.4.57}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.4.55
+Version: 0.4.57
 Requires-Dist: bin-shim>=0.1
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index

{dirsql-0.4.55 → dirsql-0.4.57}/docs/.vitepress/config.ts

@@ -3,7 +3,7 @@ import { defineConfig } from 'vitepress'
 export default defineConfig({
   title: 'dirsql',
   description: 'Ephemeral SQL index over a local directory. Watches a filesystem, ingests structured files into an ephemeral SQLite database, and exposes a SQL query interface.',
-  base: '/dirsql/',
+  base: '/',
 
   // Vite blocks dev-server requests whose Host header isn't allowlisted, so
   // `pnpm dev --host` reached by a network hostname (e.g. a Tailscale

{dirsql-0.4.55 → dirsql-0.4.57}/docs/AGENTS.md

@@ -14,7 +14,7 @@ pnpm install
 pnpm dev
 ```
 
-This starts a local dev server (default: `http://localhost:5173/dirsql/`). The site hot-reloads on file changes.
+This starts a local dev server (default: `http://localhost:5173/`). The site hot-reloads on file changes.
 
 ## Building
 
@@ -94,4 +94,4 @@ Working rules:
 - Use VitePress [code group](https://vitepress.dev/guide/markdown#code-groups) syntax (`::: code-group`) for multi-language examples with `Python`, `Rust`, and `TypeScript` tabs
 - Internal links use relative paths (e.g., `./howto/define-tables.md`)
 - The VitePress config is at `docs/.vitepress/config.ts`
-- The site is deployed under the `/dirsql/` base path
+- The site is deployed at the root of `dirsql.dev`

{dirsql-0.4.55 → dirsql-0.4.57}/docs/reference/sdk.md

@@ -223,6 +223,9 @@ Executes a SQL query and returns rows keyed by column name.
   [Read-only by design](../explanation#read-only-by-design).
 - Internal tracking columns (`_dirsql_file_path`, `_dirsql_row_index`) are
   excluded from `SELECT *` results; name them explicitly to see them.
+- **Column order.** Python row dicts are keyed in the order the SELECT list
+  names the columns. Rust and TypeScript rows do not carry that order; use
+  [`queryOrdered`](#queryordered).
 - SQLite values map back to language types:
 
 | SQLite | Python | TypeScript | Rust |
@@ -239,6 +242,25 @@ than `Number.MAX_SAFE_INTEGER`, 2^53 − 1) cannot be represented as a JS
 than return a rounded value. Python's `int` is unbounded, so it always
 round-trips.
 
+### `queryOrdered`
+
+::: code-group
+
+```typescript [TypeScript]
+await db.queryOrdered(sql: string) -> { columns: string[]; rows: Record<string, unknown>[] }
+```
+
+```rust [Rust]
+db.query_ordered(sql: &str) -> Result<QueryResult>   // QueryResult { columns, rows }
+```
+
+:::
+
+Runs `query` and also returns the column names in the order the SELECT list
+names them. Use it to render columns in the order the caller asked for: a
+row's keys do not carry that order. In TypeScript, object keys that look like
+integers always enumerate first.
+
 ### `watch`
 
 ::: code-group

{dirsql-0.4.55 → dirsql-0.4.57}/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.55"
+version = "0.4.57"
 # 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.57/packages/python/changelog.d/2026-09-24-query-rows-in-projection-order.md

@@ -0,0 +1 @@
+**Fixed** `db.query()` rows are now dicts keyed in the order the SELECT list names the columns, so `list(row)` gives the projection order (`SELECT *` follows the table's declared column order). Keys previously came out in the core's hash-map order, which varied from run to run, so a caller rendering columns had no order to follow.

{dirsql-0.4.55 → dirsql-0.4.57}/packages/python/docs/.vitepress/config.ts

@@ -3,7 +3,7 @@ import { defineConfig } from 'vitepress'
 export default defineConfig({
   title: 'dirsql',
   description: 'Ephemeral SQL index over a local directory. Watches a filesystem, ingests structured files into an ephemeral SQLite database, and exposes a SQL query interface.',
-  base: '/dirsql/',
+  base: '/',
 
   // Vite blocks dev-server requests whose Host header isn't allowlisted, so
   // `pnpm dev --host` reached by a network hostname (e.g. a Tailscale

{dirsql-0.4.55 → dirsql-0.4.57}/packages/python/docs/AGENTS.md

@@ -14,7 +14,7 @@ pnpm install
 pnpm dev
 ```
 
-This starts a local dev server (default: `http://localhost:5173/dirsql/`). The site hot-reloads on file changes.
+This starts a local dev server (default: `http://localhost:5173/`). The site hot-reloads on file changes.
 
 ## Building
 
@@ -94,4 +94,4 @@ Working rules:
 - Use VitePress [code group](https://vitepress.dev/guide/markdown#code-groups) syntax (`::: code-group`) for multi-language examples with `Python`, `Rust`, and `TypeScript` tabs
 - Internal links use relative paths (e.g., `./howto/define-tables.md`)
 - The VitePress config is at `docs/.vitepress/config.ts`
-- The site is deployed under the `/dirsql/` base path
+- The site is deployed at the root of `dirsql.dev`

{dirsql-0.4.55/packages/rust → dirsql-0.4.57/packages/python}/docs/reference/sdk.md

@@ -223,6 +223,9 @@ Executes a SQL query and returns rows keyed by column name.
   [Read-only by design](../explanation#read-only-by-design).
 - Internal tracking columns (`_dirsql_file_path`, `_dirsql_row_index`) are
   excluded from `SELECT *` results; name them explicitly to see them.
+- **Column order.** Python row dicts are keyed in the order the SELECT list
+  names the columns. Rust and TypeScript rows do not carry that order; use
+  [`queryOrdered`](#queryordered).
 - SQLite values map back to language types:
 
 | SQLite | Python | TypeScript | Rust |
@@ -239,6 +242,25 @@ than `Number.MAX_SAFE_INTEGER`, 2^53 − 1) cannot be represented as a JS
 than return a rounded value. Python's `int` is unbounded, so it always
 round-trips.
 
+### `queryOrdered`
+
+::: code-group
+
+```typescript [TypeScript]
+await db.queryOrdered(sql: string) -> { columns: string[]; rows: Record<string, unknown>[] }
+```
+
+```rust [Rust]
+db.query_ordered(sql: &str) -> Result<QueryResult>   // QueryResult { columns, rows }
+```
+
+:::
+
+Runs `query` and also returns the column names in the order the SELECT list
+names them. Use it to render columns in the order the caller asked for: a
+row's keys do not carry that order. In TypeScript, object keys that look like
+integers always enumerate first.
+
 ### `watch`
 
 ::: code-group

dirsql-0.4.57/packages/python/e2e-attestations/claude-1172-on-file-path.json

@@ -0,0 +1,7 @@
+{
+  "command": "just test-e2e",
+  "ran_at": 1790250389,
+  "exit_code": 0,
+  "commit": "b36c850be9c0cd4b06992b42fe2c689d38783757",
+  "branch": "claude/1172-on-file-path"
+}

dirsql-0.4.57/packages/python/e2e-attestations/claude-1173-py-projection-order.json

@@ -0,0 +1,7 @@
+{
+  "command": "just test-e2e",
+  "ran_at": 1790283783,
+  "exit_code": 0,
+  "commit": "2fb22b61a9db9022d3c3adbdf7b7373530de091c",
+  "branch": "claude/1173-py-projection-order"
+}

dirsql-0.4.57/packages/python/migrations.d/2026-09-24-query-rows-in-projection-order.md

@@ -0,0 +1,36 @@
+### `db.query()` rows are keyed in projection order
+
+**Summary**
+
+Each dict `db.query()` returns is now keyed in the order the SELECT list names the columns; `SELECT *` follows the table's declared column order. The keys previously came out in the core's hash-map order, which varied from process to process. No signature changed.
+
+**Required changes**
+
+_None._
+
+**Deprecations removed**
+
+_None._
+
+**Behavior changes without code changes**
+
+| Call | Before | After |
+| --- | --- | --- |
+| `await db.query("SELECT path, size FROM './'")` | keys in arbitrary order, e.g. `{'size': 6, 'path': 'a.md'}` | `{'path': 'a.md', 'size': 6}` |
+
+The old order was never stable, so no caller could have depended on it. Code that sorted the keys to get a stable order can drop the sort if it wants the order the query asked for.
+
+**Verification**
+
+```python
+import asyncio
+from dirsql import DirSQL
+
+async def main():
+    db = DirSQL(".")
+    print(await db.query("SELECT size, path FROM './' LIMIT 1"))
+
+asyncio.run(main())
+```
+
+Expected: `[{'size': ..., 'path': ...}]`, `size` first as written.

{dirsql-0.4.55 → dirsql-0.4.57}/packages/python/src/lib.rs

@@ -193,11 +193,13 @@ mod python {
 
         fn query(&self, py: Python<'_>, sql: String) -> PyResult<Py<PyList>> {
             let db = self.inner.clone();
-            let rows = py.detach(move || db.query(&sql)).map_err(to_py_err)?;
+            let result = py
+                .detach(move || db.query_ordered(&sql))
+                .map_err(to_py_err)?;
 
             let list = PyList::empty(py);
-            for row in rows {
-                list.append(value_row_to_py_dict(py, &row)?)?;
+            for row in &result.rows {
+                list.append(ordered_row_to_py_dict(py, &result.columns, row)?)?;
             }
             Ok(list.unbind())
         }
@@ -302,6 +304,18 @@ mod python {
         Ok(dict.unbind())
     }
 
+    fn ordered_row_to_py_dict(
+        py: Python<'_>,
+        columns: &[String],
+        row: &Row,
+    ) -> PyResult<Py<PyDict>> {
+        let dict = PyDict::new(py);
+        for column in columns {
+            dict.set_item(column, value_to_py(py, &row[column]))?;
+        }
+        Ok(dict.unbind())
+    }
+
     fn convert_py_row(
         py: Python<'_>,
         py_row: &HashMap<String, Py<PyAny>>,

dirsql-0.4.57/packages/python/tests/e2e/speed_of_light.py

@@ -0,0 +1,124 @@
+"""Harness for the use-case speed-of-light tests.
+
+Each use-case test asks one question of a generated corpus twice: once through
+the fastest native pipeline (find, sort, join, awk, a single parser process)
+and once through the real `dirsql` launcher. The rows must be identical and
+dirsql's wall time, after subtracting the launcher's measured startup, must be
+within ten percent of native. The bar is a ratio, never a millisecond number,
+so it holds on any machine.
+
+Startup is the mean of ten `dirsql --help` runs; `--help` and `SELECT 1` cost
+the same, so it stands in for the fixed per-invocation cost. A corpus too
+small to time is grown by doubling until the native pipeline takes at least a
+second, so the comparison is above the noise floor. Each side is run three
+times and the fastest run counts.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import time
+
+ONE_SECOND = 1.0
+TOLERANCE = 1.1
+STARTUP_PROBES = 10
+BEST_OF = 3
+
+
+def cli() -> str:
+    dirsql = shutil.which("dirsql")
+    assert dirsql is not None, (
+        "`dirsql` console script not on PATH -- run `uv run maturin develop`"
+    )
+    return dirsql
+
+
+def timed(argv, cwd, timeout, env=None):
+    started = time.perf_counter()
+    proc = subprocess.run(
+        argv,
+        cwd=str(cwd),
+        stdin=subprocess.DEVNULL,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        env=env,
+        check=False,
+    )
+    return proc, time.perf_counter() - started
+
+
+def startup_seconds(argv=None, cwd=None) -> float:
+    argv = [cli(), "--help"] if argv is None else argv
+    samples = []
+    for _ in range(STARTUP_PROBES):
+        proc, seconds = timed(argv, cwd or ".", timeout=60)
+        assert proc.returncode == 0, proc.stderr
+        samples.append(seconds)
+    return sum(samples) / len(samples)
+
+
+def dirsql_rows(proc, columns):
+    assert proc.returncode == 0, (
+        f"dirsql failed: stdout={proc.stdout!r} stderr={proc.stderr!r}"
+    )
+    return [tuple(row[column] for column in columns) for row in json.loads(proc.stdout)]
+
+
+def grow_until_native_takes_a_second(build, native, start, ceiling):
+    """Grow the corpus by doubling until `native` runs for a second.
+
+    `build(lo, hi)` adds items `lo` through `hi - 1` to the corpus already
+    holding `lo` items, so each doubling writes only the new half.
+    """
+    built, size = 0, start
+    while True:
+        build(built, size)
+        built = size
+        _, seconds = native()
+        if seconds >= ONE_SECOND or size >= ceiling:
+            return size
+        size *= 2
+
+
+def best_of(run, name, hopeless=None):
+    """Run `run` three times; return the rows and wall time of the fastest.
+
+    `run` returns `(rows, seconds)`. A run that raises `TimeoutExpired` fails
+    the test immediately with the timeout it blew through. A run slower than
+    `hopeless` seconds ends the series early: noise does not account for an
+    order of magnitude, so no retry could bring the best under the bar.
+    """
+    fastest = None
+    for _ in range(BEST_OF):
+        try:
+            rows, seconds = run()
+        except subprocess.TimeoutExpired as expired:
+            raise AssertionError(
+                f"{name} did not finish within {expired.timeout:.0f}s"
+            ) from None
+        if fastest is None or seconds < fastest[1]:
+            fastest = (rows, seconds)
+        if hopeless is not None and seconds > hopeless:
+            break
+    return fastest
+
+
+def hopeless_seconds(native_seconds: float, startup: float) -> float:
+    return startup + 10 * TOLERANCE * native_seconds
+
+
+def dirsql_timeout(native_seconds: float) -> float:
+    return max(60.0, 30 * native_seconds)
+
+
+def assert_speed_of_light(name, native_seconds, dirsql_seconds, startup):
+    measured = dirsql_seconds - startup
+    budget = TOLERANCE * native_seconds
+    assert measured <= budget, (
+        f"{name}: dirsql {dirsql_seconds:.3f}s minus startup {startup:.3f}s"
+        f" = {measured:.3f}s, over {TOLERANCE}x native {native_seconds:.3f}s"
+        f" = {budget:.3f}s"
+    )

{dirsql-0.4.55 → dirsql-0.4.57}/packages/rust/Cargo.toml

@@ -6,7 +6,7 @@ description = "Ephemeral SQL index over a local directory"
 # version stays for the binding crates (publish = false). The literal
 # intentionally lags the published version: putitoutthere rewrites it to
 # the planned release version at build time and never commits it back.
-version = "0.4.55"
+version = "0.4.57"
 edition.workspace = true
 # Literal `license` (not `license.workspace = true`) because
 # putitoutthere's preflight check reads `[package].license` directly

{dirsql-0.4.55/packages/python → dirsql-0.4.57/packages/rust}/docs/reference/sdk.md

@@ -223,6 +223,9 @@ Executes a SQL query and returns rows keyed by column name.
   [Read-only by design](../explanation#read-only-by-design).
 - Internal tracking columns (`_dirsql_file_path`, `_dirsql_row_index`) are
   excluded from `SELECT *` results; name them explicitly to see them.
+- **Column order.** Python row dicts are keyed in the order the SELECT list
+  names the columns. Rust and TypeScript rows do not carry that order; use
+  [`queryOrdered`](#queryordered).
 - SQLite values map back to language types:
 
 | SQLite | Python | TypeScript | Rust |
@@ -239,6 +242,25 @@ than `Number.MAX_SAFE_INTEGER`, 2^53 − 1) cannot be represented as a JS
 than return a rounded value. Python's `int` is unbounded, so it always
 round-trips.
 
+### `queryOrdered`
+
+::: code-group
+
+```typescript [TypeScript]
+await db.queryOrdered(sql: string) -> { columns: string[]; rows: Record<string, unknown>[] }
+```
+
+```rust [Rust]
+db.query_ordered(sql: &str) -> Result<QueryResult>   // QueryResult { columns, rows }
+```
+
+:::
+
+Runs `query` and also returns the column names in the order the SELECT list
+names them. Use it to render columns in the order the caller asked for: a
+row's keys do not carry that order. In TypeScript, object keys that look like
+integers always enumerate first.
+
 ### `watch`
 
 ::: code-group

{dirsql-0.4.55 → dirsql-0.4.57}/packages/rust/src/command.rs

@@ -26,7 +26,7 @@
 //! - **Errors.** A non-zero exit is a failure carrying the tail of stderr.
 
 use std::io::{Read, Write};
-use std::path::Path;
+use std::path::{Path, PathBuf};
 use std::process::{Command, Stdio};
 
 /// A named placeholder substituted into a command's argv.
@@ -66,14 +66,22 @@ pub enum CommandError {
     #[error("invalid command template: {0:?}")]
     InvalidCommand(String),
 
-    /// The child could not be spawned (e.g. the program was not found).
-    #[error("failed to spawn `{command}`: {source}")]
+    /// The child could not be spawned.
+    #[error("failed to spawn `{program}`: {source}")]
     Spawn {
-        command: String,
+        program: String,
         #[source]
         source: std::io::Error,
     },
 
+    /// A program named without a `/` was not found on `$PATH`. `local` is the
+    /// file of that name in the child's cwd, which a bare name never reaches.
+    #[error("failed to spawn `{program}`: not found on $PATH{}", local_hint(.program, .local.as_deref()))]
+    NotOnPath {
+        program: String,
+        local: Option<PathBuf>,
+    },
+
     /// The child exited with a non-zero status. `code` is the exit code, or
     /// `"signal"` when the child was terminated by a signal.
     #[error("command `{command}` failed (exit {code}): {stderr_tail}")]
@@ -121,10 +129,9 @@ pub fn run_command(
             Stdio::null()
         });
 
-    let mut child = cmd.spawn().map_err(|source| CommandError::Spawn {
-        command: command.to_string(),
-        source,
-    })?;
+    let mut child = cmd
+        .spawn()
+        .map_err(|source| spawn_error(&argv[0], source, cwd))?;
 
     // Feed stdin and drain stdout/stderr on their own threads. Draining the
     // output pipes concurrently is required: a child that writes more than a
@@ -186,6 +193,37 @@ pub fn run_command(
     }
 }
 
+fn spawn_error(program: &str, source: std::io::Error, cwd: &Path) -> CommandError {
+    // A missing cwd fails the child's chdir with `NotFound` too.
+    if !searched_path(program, source.kind()) || !cwd.is_dir() {
+        return CommandError::Spawn {
+            program: program.to_string(),
+            source,
+        };
+    }
+    let candidate = cwd.join(program);
+    CommandError::NotOnPath {
+        program: program.to_string(),
+        local: candidate.is_file().then_some(candidate),
+    }
+}
+
+/// A `NotFound` for a name without a `/` means the `$PATH` search came up
+/// empty (`execvp` semantics); with a `/` the name was a path.
+fn searched_path(program: &str, kind: std::io::ErrorKind) -> bool {
+    kind == std::io::ErrorKind::NotFound && !program.contains('/')
+}
+
+fn local_hint(program: &str, local: Option<&Path>) -> String {
+    match local {
+        Some(path) => format!(
+            ". Names without a `/` are resolved against $PATH; use `./{program}` to run `{}`",
+            path.display()
+        ),
+        None => String::new(),
+    }
+}
+
 /// Split a command template into argv (shell-like quoting, no shell) and
 /// substitute placeholders into whole tokens.
 pub(crate) fn build_argv(
@@ -444,8 +482,65 @@ mod tests {
     }
 
     #[test]
-    fn run_command_reports_spawn_failure_for_a_missing_program() {
+    fn run_command_reports_a_bare_missing_program_as_not_on_path() {
         let err = run_command("definitely-not-a-real-binary-xyzzy", &[], &cwd(), None).unwrap_err();
+        assert!(
+            matches!(err, CommandError::NotOnPath { local: None, .. }),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn run_command_reports_a_missing_path_as_a_plain_spawn_error() {
+        let err =
+            run_command("./definitely-not-a-real-binary-xyzzy", &[], &cwd(), None).unwrap_err();
         assert!(matches!(err, CommandError::Spawn { .. }), "got: {err:?}");
     }
+
+    #[test]
+    fn a_bare_not_found_name_searched_path() {
+        assert!(searched_path("extract.py", std::io::ErrorKind::NotFound));
+    }
+
+    #[test]
+    fn a_name_with_a_slash_did_not_search_path() {
+        assert!(!searched_path("./extract.py", std::io::ErrorKind::NotFound));
+        assert!(!searched_path(
+            "bin/extract.py",
+            std::io::ErrorKind::NotFound
+        ));
+    }
+
+    #[test]
+    fn a_non_not_found_error_did_not_search_path() {
+        assert!(!searched_path(
+            "extract.py",
+            std::io::ErrorKind::PermissionDenied
+        ));
+    }
+
+    #[test]
+    fn not_on_path_without_a_local_file_offers_no_hint() {
+        let err = CommandError::NotOnPath {
+            program: "extract.py".to_string(),
+            local: None,
+        };
+        assert_eq!(
+            err.to_string(),
+            "failed to spawn `extract.py`: not found on $PATH"
+        );
+    }
+
+    #[test]
+    fn not_on_path_with_a_local_file_offers_the_dot_slash_form() {
+        let err = CommandError::NotOnPath {
+            program: "extract.py".to_string(),
+            local: Some(PathBuf::from("/notes/extract.py")),
+        };
+        assert_eq!(
+            err.to_string(),
+            "failed to spawn `extract.py`: not found on $PATH. Names without a `/` are \
+             resolved against $PATH; use `./extract.py` to run `/notes/extract.py`"
+        );
+    }
 }