dirsql 0.4.110__tar.gz → 0.4.112__tar.gz

{dirsql-0.4.110 → dirsql-0.4.112}/Cargo.lock

@@ -573,7 +573,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql"
-version = "0.4.110"
+version = "0.4.112"
 dependencies = [
  "assert_cmd",
  "axum",
@@ -625,7 +625,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.4.110"
+version = "0.4.112"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.4.110 → dirsql-0.4.112}/PKG-INFO

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

{dirsql-0.4.110 → dirsql-0.4.112}/docs/reference/cli.md

@@ -237,6 +237,50 @@ On startup the server prints `Running at <host>:<port>` to stdout. It runs
 until it receives `SIGINT` (Ctrl-C) or `SIGTERM`, then drains in-flight
 requests, closes open `/events` streams, and exits.
 
+Pass `--frontend` to serve the bundled dirsql SQL explorer shell at `/` on
+the same origin as the HTTP API. It works offline and prints `Frontend at
+http://<host>:<actual-port>/` without opening a browser. With `--port 0`, the
+printed URL uses the assigned port. The page offers an editable SQL box
+holding the starter query `SELECT * FROM './' LIMIT 100`. Nothing runs until
+you press **Run** (or Ctrl/Cmd+Enter); pressing it again refreshes the
+result. Queries go through `POST /query`, so the read-only rule applies, and
+run exactly as written. The page shows elapsed time, the number of rows
+returned, and errors. Values render as text (`NULL` is marked), and only the
+first 1000 rows are displayed. An empty result says so and shows no column
+names, since the response carries none.
+
+```bash
+dirsql server --frontend
+dirsql server --frontend -c .dirsql.toml
+```
+
+The shell reads `GET /frontend/state`. When the index is ready it returns
+HTTP `200`:
+
+```json
+{
+  "error": null,
+  "root": "/abs/path/of/the/invocation/directory",
+  "tables": [
+    {"name": "posts", "columns": [{"name": "basename", "type": "TEXT"}]}
+  ]
+}
+```
+
+`root` is the query root, where [path-tables](./path-tables.md) resolve.
+`tables` lists the declared tables, ordered by name, each with its columns in
+declaration order and the declared SQLite type (`""` when untyped). Empty
+tables are listed. A configless server, or a config with only functions or
+extensions, returns `"tables": []`. dirsql's bookkeeping tables, SQLite's own
+tables, virtual tables with their shadow tables, and path-tables are never
+listed. The metadata is read from SQLite's catalog: no file is parsed, no
+directory walked, no table counted.
+
+When config loading fails the endpoint returns HTTP `503` with
+`{"error":"<diagnostic>"}` and no `root` or `tables`. Fix the config and
+restart the server. Without `--frontend`, the `/` and `/frontend/state`
+routes return `404`. `POST /query` is unchanged.
+
 ### Flags
 
 Config flags are subcommand-local: pass them after `server`
@@ -247,6 +291,7 @@ Config flags are subcommand-local: pass them after `server`
 | `-c, --config <path>` | none | Path to a [config file](./config.md). **Repeatable** (`-c a -c b`): the configs load and merge in argv order — see [Composing multiple configs](./config.md#composing-multiple-configs). The index root is the **invocation directory** (the current working directory) and governs path-tables; a config's `[[table]]` globs anchor at **that config's own directory** (see [glob anchor](./config.md#glob-anchor)), so `--config /elsewhere/.dirsql.toml` indexes `/elsewhere`, from any working directory. With none given, **no named tables are defined** — query the filesystem with a [path-table](./path-tables.md) (`FROM './'`). A `./.dirsql.toml` on disk is **not** auto-loaded; pass it explicitly. A `-c` naming a file that does not exist is an [error](#degraded-mode). |
 | `--host <addr>` | `localhost` | Bind address. |
 | `--port <n>` | `7117` | TCP port to bind. |
+| `--frontend` | off | Serve the bundled SQL explorer shell and print its URL. |
 | `--cors-origin <origin>` | off | Let browser pages on `<origin>` (an exact origin such as `http://localhost:3202`, or `*` for any) call `/query` and open `/events`. See [Cross-origin requests](#cross-origin-requests). |
 | `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches under the platform cache directory (`$XDG_CACHE_HOME/dirsql/<root hash>/cache.db` on Linux), outside the root; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
 | `--no-ignore` | off | Scan files a `.gitignore` would hide. [Path-tables](./path-tables.md#skip-rules) respect `.gitignore` files by default; this flag restores the full walk. The built-in `.git` skip and configured `ignore` patterns still apply. Also available on [`dirsql query`](#dirsql-query). |

{dirsql-0.4.110 → dirsql-0.4.112}/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.110"
+version = "0.4.112"
 # 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.110/packages/rust → dirsql-0.4.112/packages/python}/docs/reference/cli.md

@@ -237,6 +237,50 @@ On startup the server prints `Running at <host>:<port>` to stdout. It runs
 until it receives `SIGINT` (Ctrl-C) or `SIGTERM`, then drains in-flight
 requests, closes open `/events` streams, and exits.
 
+Pass `--frontend` to serve the bundled dirsql SQL explorer shell at `/` on
+the same origin as the HTTP API. It works offline and prints `Frontend at
+http://<host>:<actual-port>/` without opening a browser. With `--port 0`, the
+printed URL uses the assigned port. The page offers an editable SQL box
+holding the starter query `SELECT * FROM './' LIMIT 100`. Nothing runs until
+you press **Run** (or Ctrl/Cmd+Enter); pressing it again refreshes the
+result. Queries go through `POST /query`, so the read-only rule applies, and
+run exactly as written. The page shows elapsed time, the number of rows
+returned, and errors. Values render as text (`NULL` is marked), and only the
+first 1000 rows are displayed. An empty result says so and shows no column
+names, since the response carries none.
+
+```bash
+dirsql server --frontend
+dirsql server --frontend -c .dirsql.toml
+```
+
+The shell reads `GET /frontend/state`. When the index is ready it returns
+HTTP `200`:
+
+```json
+{
+  "error": null,
+  "root": "/abs/path/of/the/invocation/directory",
+  "tables": [
+    {"name": "posts", "columns": [{"name": "basename", "type": "TEXT"}]}
+  ]
+}
+```
+
+`root` is the query root, where [path-tables](./path-tables.md) resolve.
+`tables` lists the declared tables, ordered by name, each with its columns in
+declaration order and the declared SQLite type (`""` when untyped). Empty
+tables are listed. A configless server, or a config with only functions or
+extensions, returns `"tables": []`. dirsql's bookkeeping tables, SQLite's own
+tables, virtual tables with their shadow tables, and path-tables are never
+listed. The metadata is read from SQLite's catalog: no file is parsed, no
+directory walked, no table counted.
+
+When config loading fails the endpoint returns HTTP `503` with
+`{"error":"<diagnostic>"}` and no `root` or `tables`. Fix the config and
+restart the server. Without `--frontend`, the `/` and `/frontend/state`
+routes return `404`. `POST /query` is unchanged.
+
 ### Flags
 
 Config flags are subcommand-local: pass them after `server`
@@ -247,6 +291,7 @@ Config flags are subcommand-local: pass them after `server`
 | `-c, --config <path>` | none | Path to a [config file](./config.md). **Repeatable** (`-c a -c b`): the configs load and merge in argv order — see [Composing multiple configs](./config.md#composing-multiple-configs). The index root is the **invocation directory** (the current working directory) and governs path-tables; a config's `[[table]]` globs anchor at **that config's own directory** (see [glob anchor](./config.md#glob-anchor)), so `--config /elsewhere/.dirsql.toml` indexes `/elsewhere`, from any working directory. With none given, **no named tables are defined** — query the filesystem with a [path-table](./path-tables.md) (`FROM './'`). A `./.dirsql.toml` on disk is **not** auto-loaded; pass it explicitly. A `-c` naming a file that does not exist is an [error](#degraded-mode). |
 | `--host <addr>` | `localhost` | Bind address. |
 | `--port <n>` | `7117` | TCP port to bind. |
+| `--frontend` | off | Serve the bundled SQL explorer shell and print its URL. |
 | `--cors-origin <origin>` | off | Let browser pages on `<origin>` (an exact origin such as `http://localhost:3202`, or `*` for any) call `/query` and open `/events`. See [Cross-origin requests](#cross-origin-requests). |
 | `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches under the platform cache directory (`$XDG_CACHE_HOME/dirsql/<root hash>/cache.db` on Linux), outside the root; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
 | `--no-ignore` | off | Scan files a `.gitignore` would hide. [Path-tables](./path-tables.md#skip-rules) respect `.gitignore` files by default; this flag restores the full walk. The built-in `.git` skip and configured `ignore` patterns still apply. Also available on [`dirsql query`](#dirsql-query). |

dirsql-0.4.112/packages/python/e2e-attestations/bot-1469-ci-speed-sanity-1009.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/release_speed_test.py -x -q",
+  "ran_at": 1791556899,
+  "exit_code": 0,
+  "commit": "f4ef45b80656a68f454aafdcacc9b56cd555b917",
+  "branch": "bot/1469-ci-speed-sanity-1009"
+}

dirsql-0.4.112/packages/python/e2e-attestations/bot-1487-frontend-query-1011.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/cli_version_test.py tests/e2e/query_contract_test.py tests/e2e/fanout_test.py tests/e2e/extension_package_test.py tests/e2e/server_speed_test.py -x -q",
+  "ran_at": 1791765336,
+  "exit_code": 0,
+  "commit": "a2b5671787b3cfa038a128d5cbbeac13e6c268a9",
+  "branch": "bot/1487-frontend-query-1011"
+}

dirsql-0.4.112/packages/python/e2e-attestations/bot-1488-frontend-metadata-1011.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/cli_version_test.py tests/e2e/query_contract_test.py tests/e2e/declared_table_name_test.py tests/e2e/on_file_query_test.py -x -q",
+  "ran_at": 1791764712,
+  "exit_code": 0,
+  "commit": "ae61a26f7b9018c3e12aebeea7c6a3cf32ef4d87",
+  "branch": "bot/1488-frontend-metadata-1011"
+}

dirsql-0.4.112/packages/python/e2e-attestations/bot-1503-bench-watch-1011.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m tests.e2e.bench_suite --pairs 5 --out /tmp/bench-1503 -k watch",
+  "ran_at": 1791769095,
+  "exit_code": 0,
+  "commit": "409ebb5a7e1da55d1516983fcd936cae7fdc952c",
+  "branch": "bot/1503-bench-watch-1011"
+}

dirsql-0.4.112/packages/python/e2e-attestations/bot-1504-bench-names-1011.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m tests.e2e.bench_suite --pairs 3 --out /tmp/bench-1504 -k \"glob_speed_symlink or glob_speed_dotfiles or glob_speed_recursive\"",
+  "ran_at": 1791770495,
+  "exit_code": 0,
+  "commit": "cce3e83ece8026cc8feedbb1cd64f73242f1d230",
+  "branch": "bot/1504-bench-names-1011"
+}

dirsql-0.4.112/packages/python/e2e-attestations/bot-issue-1486-frontend-20261009.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/cli_version_test.py tests/e2e/query_contract_test.py tests/e2e/fanout_test.py tests/e2e/extension_package_test.py -x -q",
+  "ran_at": 1791556016,
+  "exit_code": 0,
+  "commit": "fc84f87effcd648162d3c143d308bc0c24222dcb",
+  "branch": "bot/issue-1486-frontend-20261009"
+}

dirsql-0.4.112/packages/python/e2e-attestations/bot-speed-gap-childpath-1011.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/glob_speed_depth_bound_test.py tests/e2e/glob_speed_one_level_test.py tests/e2e/glob_speed_recursive_test.py tests/e2e/glob_speed_symlink_test.py tests/e2e/glob_speed_matchers_test.py tests/e2e/glob_speed_dotfiles_test.py tests/e2e/glob_speed_gitignore_test.py -x -q",
+  "ran_at": 1791777891,
+  "exit_code": 0,
+  "commit": "fb7068d3883fd35c014146a174f4f342aaf93dab",
+  "branch": "bot/speed-gap-childpath-1011"
+}

dirsql-0.4.112/packages/python/e2e-attestations/bot-speed-parse-overlap-1011.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/jsonl_parse_speed_test.py tests/e2e/frontmatter_parse_speed_test.py tests/e2e/on_file_query_test.py tests/e2e/query_contract_test.py -x -q",
+  "ran_at": 1791768023,
+  "exit_code": 0,
+  "commit": "db8e06627eb807a3932ae3989ef662019a288ce1",
+  "branch": "bot/speed-parse-overlap-1011"
+}

dirsql-0.4.112/packages/python/e2e-attestations/bot-speed-parse-paths-1009.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/frontmatter_parse_speed_test.py tests/e2e/jsonl_parse_speed_test.py tests/e2e/on_file_query_test.py tests/e2e/query_contract_test.py tests/e2e/fanout_test.py tests/e2e/declared_table_name_test.py tests/e2e/use_case_dossier_test.py tests/e2e/use_case_join_test.py tests/e2e/use_case_notebook_test.py tests/e2e/use_case_transcripts_test.py -x -q -s",
+  "ran_at": 1791560842,
+  "exit_code": 0,
+  "commit": "d5ea2e249e40f6b64e6eb1f799fc47d8290b795e",
+  "branch": "bot/speed-parse-paths-1009"
+}

dirsql-0.4.112/packages/python/e2e-attestations/bot-speed-parse-pragmas-1011.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/jsonl_parse_speed_test.py tests/e2e/frontmatter_parse_speed_test.py tests/e2e/on_file_query_test.py tests/e2e/query_contract_test.py -x -q",
+  "ran_at": 1791766109,
+  "exit_code": 0,
+  "commit": "a2a42d2c9ac8c5aa5292f4d4d540296cf1e1ee6c",
+  "branch": "bot/speed-parse-pragmas-1011"
+}

dirsql-0.4.112/packages/python/e2e-attestations/bot-speed-walk-components-1011.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/glob_speed_depth_bound_test.py tests/e2e/glob_speed_one_level_test.py tests/e2e/glob_speed_recursive_test.py tests/e2e/glob_speed_symlink_test.py tests/e2e/glob_speed_dotfiles_test.py tests/e2e/glob_speed_node_modules_test.py tests/e2e/glob_speed_matchers_test.py tests/e2e/glob_speed_gitignore_test.py tests/e2e/stat_speed_test.py tests/e2e/query_contract_test.py -x -q",
+  "ran_at": 1791771802,
+  "exit_code": 0,
+  "commit": "6a704d60f7963656097b921100e1f3aaefba6bbd",
+  "branch": "bot/speed-walk-components-1011"
+}

dirsql-0.4.112/packages/python/e2e-attestations/bot-speed-walk-rowpath-1011.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/glob_speed_depth_bound_test.py tests/e2e/glob_speed_one_level_test.py tests/e2e/glob_speed_recursive_test.py tests/e2e/glob_speed_symlink_test.py tests/e2e/glob_speed_dotfiles_test.py tests/e2e/glob_speed_node_modules_test.py tests/e2e/glob_speed_matchers_test.py tests/e2e/glob_speed_gitignore_test.py tests/e2e/stat_speed_test.py tests/e2e/query_contract_test.py -x -q",
+  "ran_at": 1791768231,
+  "exit_code": 0,
+  "commit": "d6653e1f4d8a1d8b4b723b6f24c0bc805e4aa7e1",
+  "branch": "bot/speed-walk-rowpath-1011"
+}

dirsql-0.4.112/packages/python/e2e-attestations/bot-speed-walk-sched-1009.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run python -m pytest tests/e2e/glob_speed_depth_bound_test.py tests/e2e/glob_speed_one_level_test.py tests/e2e/glob_speed_recursive_test.py tests/e2e/glob_speed_symlink_test.py -x -q",
+  "ran_at": 1791561608,
+  "exit_code": 0,
+  "commit": "d4ace79bbd16978ba199811907976d240ca55507",
+  "branch": "bot/speed-walk-sched-1009"
+}

{dirsql-0.4.110 → dirsql-0.4.112}/packages/python/tests/e2e/speed_of_light.py

@@ -415,3 +415,56 @@ def assert_speed_of_light(name, result, startup):
     assert median <= TOLERANCE, (
         f"bar native {result.bar}: {line}; median is over {TOLERANCE}x"
     )
+
+
+SLOWDOWN = 1.5
+RELEASE_PAIRS = 10
+ATTEMPTS = 3
+
+
+def release_ratios(pr, release, startup, pairs=RELEASE_PAIRS):
+    """Per-pair PR/release time ratios, each side net of its own startup.
+
+    `startup.dirsql` is the PR build's, `startup.native` the release's. One
+    discarded warm-up pair, then pairs alternate which build runs first.
+    """
+    release()
+    pr()
+    series = run_pairs({"release": release}, pr, pairs)
+    return pair_ratios(series.native_seconds["release"], series.dirsql_seconds, startup)
+
+
+def assert_no_slowdown(name, measure, threshold=SLOWDOWN, attempts=ATTEMPTS):
+    """Pass on the first attempt whose median ratio is within `threshold`.
+
+    Fails only when every attempt is over, so one noisy window on a shared
+    runner does not fail the check.
+    """
+    medians = []
+    for attempt in range(1, attempts + 1):
+        ratios = measure()
+        low, median, high, spread = summarize(ratios)
+        print(
+            f"SPEED {name} vs release: attempt {attempt}, {len(ratios)} pairs,"
+            f" ratio min {low:.3f} median {median:.3f} max {high:.3f}"
+            f" spread {spread:.0%}"
+        )
+        if median <= threshold:
+            return
+        medians.append(median)
+    shown = ", ".join(f"{median:.3f}" for median in medians)
+    raise AssertionError(
+        f"{name}: PR build is over {threshold}x the previous release on every"
+        f" attempt (median ratios {shown})"
+    )
+
+
+def install_release(dest):
+    """Install the latest published dirsql into a fresh venv at `dest`."""
+    subprocess.run(["uv", "venv", str(dest)], check=True, capture_output=True)
+    subprocess.run(
+        ["uv", "pip", "install", "--python", str(dest), "dirsql"],
+        check=True,
+        capture_output=True,
+    )
+    return dest / "bin" / "dirsql"

{dirsql-0.4.110 → dirsql-0.4.112}/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.110"
+version = "0.4.112"
 edition.workspace = true
 # Literal `license` (not `license.workspace = true`) because
 # putitoutthere's preflight check reads `[package].license` directly

{dirsql-0.4.110/packages/python → dirsql-0.4.112/packages/rust}/docs/reference/cli.md

@@ -237,6 +237,50 @@ On startup the server prints `Running at <host>:<port>` to stdout. It runs
 until it receives `SIGINT` (Ctrl-C) or `SIGTERM`, then drains in-flight
 requests, closes open `/events` streams, and exits.
 
+Pass `--frontend` to serve the bundled dirsql SQL explorer shell at `/` on
+the same origin as the HTTP API. It works offline and prints `Frontend at
+http://<host>:<actual-port>/` without opening a browser. With `--port 0`, the
+printed URL uses the assigned port. The page offers an editable SQL box
+holding the starter query `SELECT * FROM './' LIMIT 100`. Nothing runs until
+you press **Run** (or Ctrl/Cmd+Enter); pressing it again refreshes the
+result. Queries go through `POST /query`, so the read-only rule applies, and
+run exactly as written. The page shows elapsed time, the number of rows
+returned, and errors. Values render as text (`NULL` is marked), and only the
+first 1000 rows are displayed. An empty result says so and shows no column
+names, since the response carries none.
+
+```bash
+dirsql server --frontend
+dirsql server --frontend -c .dirsql.toml
+```
+
+The shell reads `GET /frontend/state`. When the index is ready it returns
+HTTP `200`:
+
+```json
+{
+  "error": null,
+  "root": "/abs/path/of/the/invocation/directory",
+  "tables": [
+    {"name": "posts", "columns": [{"name": "basename", "type": "TEXT"}]}
+  ]
+}
+```
+
+`root` is the query root, where [path-tables](./path-tables.md) resolve.
+`tables` lists the declared tables, ordered by name, each with its columns in
+declaration order and the declared SQLite type (`""` when untyped). Empty
+tables are listed. A configless server, or a config with only functions or
+extensions, returns `"tables": []`. dirsql's bookkeeping tables, SQLite's own
+tables, virtual tables with their shadow tables, and path-tables are never
+listed. The metadata is read from SQLite's catalog: no file is parsed, no
+directory walked, no table counted.
+
+When config loading fails the endpoint returns HTTP `503` with
+`{"error":"<diagnostic>"}` and no `root` or `tables`. Fix the config and
+restart the server. Without `--frontend`, the `/` and `/frontend/state`
+routes return `404`. `POST /query` is unchanged.
+
 ### Flags
 
 Config flags are subcommand-local: pass them after `server`
@@ -247,6 +291,7 @@ Config flags are subcommand-local: pass them after `server`
 | `-c, --config <path>` | none | Path to a [config file](./config.md). **Repeatable** (`-c a -c b`): the configs load and merge in argv order — see [Composing multiple configs](./config.md#composing-multiple-configs). The index root is the **invocation directory** (the current working directory) and governs path-tables; a config's `[[table]]` globs anchor at **that config's own directory** (see [glob anchor](./config.md#glob-anchor)), so `--config /elsewhere/.dirsql.toml` indexes `/elsewhere`, from any working directory. With none given, **no named tables are defined** — query the filesystem with a [path-table](./path-tables.md) (`FROM './'`). A `./.dirsql.toml` on disk is **not** auto-loaded; pass it explicitly. A `-c` naming a file that does not exist is an [error](#degraded-mode). |
 | `--host <addr>` | `localhost` | Bind address. |
 | `--port <n>` | `7117` | TCP port to bind. |
+| `--frontend` | off | Serve the bundled SQL explorer shell and print its URL. |
 | `--cors-origin <origin>` | off | Let browser pages on `<origin>` (an exact origin such as `http://localhost:3202`, or `*` for any) call `/query` and open `/events`. See [Cross-origin requests](#cross-origin-requests). |
 | `--persist [<path>]` | off | Keep the SQLite index on disk between runs so a restart only re-parses files that actually changed. Bare `--persist` caches under the platform cache directory (`$XDG_CACHE_HOME/dirsql/<root hash>/cache.db` on Linux), outside the root; `--persist <path>` caches at `<path>`. Off by default (the index is ephemeral). Also available on [`dirsql query`](#dirsql-query). See [Keep the index across restarts](../howto/persist.md). |
 | `--no-ignore` | off | Scan files a `.gitignore` would hide. [Path-tables](./path-tables.md#skip-rules) respect `.gitignore` files by default; this flag restores the full walk. The built-in `.git` skip and configured `ignore` patterns still apply. Also available on [`dirsql query`](#dirsql-query). |

dirsql-0.4.112/packages/rust/src/cli/frontend.html

@@ -0,0 +1,80 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>dirsql SQL explorer</title>
+  <style>
+    :root { color-scheme: light; font-family: ui-sans-serif, system-ui, sans-serif; background: #f4f6f4; color: #173026; }
+    * { box-sizing: border-box; }
+    body { margin: 0; min-height: 100vh; }
+    header { border-bottom: 1px solid #d9e1da; background: #fff; padding: 1.1rem max(1.5rem, calc((100vw - 56rem) / 2)); }
+    header strong { font-size: 1.15rem; letter-spacing: -.03em; }
+    main { max-width: 56rem; margin: 0 auto; padding: clamp(2rem, 7vw, 5rem) 1.5rem; }
+    h1 { font-size: clamp(2rem, 5vw, 3.4rem); line-height: 1.1; letter-spacing: -.055em; margin: 0 0 1rem; }
+    p { line-height: 1.6; color: #4a5d51; max-width: 42rem; }
+    .panel { margin-top: 2.5rem; padding: 1.5rem; border: 1px solid #d9e1da; border-radius: 12px; background: #fff; box-shadow: 0 3px 12px #17302609; }
+    .panel h2 { margin: 0 0 .5rem; font-size: 1rem; }
+    .panel p { margin: 0; }
+    form { margin-top: 2rem; }
+    label { display: block; font-weight: 600; margin-bottom: .4rem; }
+    textarea { width: 100%; min-height: 7rem; padding: .7rem; border: 1px solid #b9c7bd; border-radius: 8px; font: .95rem/1.5 ui-monospace, monospace; resize: vertical; }
+    button { margin-top: .6rem; padding: .5rem 1.2rem; border: 0; border-radius: 8px; background: #1f6b46; color: #fff; font: inherit; font-weight: 600; cursor: pointer; }
+    button[aria-busy="true"] { opacity: .6; cursor: progress; }
+    .hint { font-size: .85rem; margin: .4rem 0 0; }
+    #result { margin-top: 1.5rem; overflow-x: auto; }
+    #result p.error { color: #a0362a; white-space: pre-wrap; overflow-wrap: anywhere; }
+    table { border-collapse: collapse; font: .85rem/1.4 ui-monospace, monospace; background: #fff; }
+    th, td { border: 1px solid #d9e1da; padding: .3rem .6rem; text-align: left; vertical-align: top; white-space: pre-wrap; overflow-wrap: anywhere; max-width: 40rem; }
+    th { background: #eef2ee; }
+    td.null { color: #7a8a80; font-style: italic; }
+    .error { border-color: #d7a7a1; background: #fff8f7; }
+    .error h2 { color: #a0362a; }
+    .error pre { white-space: pre-wrap; overflow-wrap: anywhere; font: .9rem/1.5 ui-monospace, monospace; margin: .8rem 0; }
+  </style>
+</head>
+<body>
+  <header><strong>dirsql</strong></header>
+  <main>
+    <h1>dirsql SQL explorer</h1>
+    <p>Explore the files and tables in this directory with SQL.</p>
+    <section class="panel" id="state" aria-live="polite">
+      <h2 id="state-title">Connecting to dirsql…</h2>
+      <p id="state-message">Checking the server state.</p>
+    </section>
+    <form id="query" onsubmit="return false">
+      <label for="sql">SQL (read-only)</label>
+      <textarea id="sql" name="sql" spellcheck="false" aria-describedby="sql-hint">SELECT * FROM './' LIMIT 100</textarea>
+      <button type="button" id="run">Run</button>
+      <p class="hint" id="sql-hint">Runs exactly as written; edit the LIMIT as needed. Press Ctrl+Enter or Cmd+Enter to run.</p>
+    </form>
+    <section id="result" aria-live="polite" aria-label="Query result"></section>
+  </main>
+  <script type="module" src="/frontend.js"></script>
+  <script>
+    (async () => {
+      const panel = document.getElementById('state');
+      const title = document.getElementById('state-title');
+      const message = document.getElementById('state-message');
+      try {
+        const response = await fetch('/frontend/state');
+        const state = await response.json();
+        if (state.error) {
+          panel.classList.add('error');
+          title.textContent = 'Configuration could not load';
+          message.textContent = state.error + ' Fix the configuration and restart dirsql server.';
+        } else if (response.ok) {
+          title.textContent = 'Ready to explore';
+          message.textContent = 'The SQL explorer is connected to this directory.';
+        } else {
+          throw new Error('Unexpected server response');
+        }
+      } catch (error) {
+        panel.classList.add('error');
+        title.textContent = 'Could not connect';
+        message.textContent = error.message;
+      }
+    })();
+  </script>
+</body>
+</html>

dirsql-0.4.112/packages/rust/src/cli/frontend.js

@@ -0,0 +1,161 @@
+export const STARTER_QUERY = "SELECT * FROM './' LIMIT 100";
+export const DISPLAY_ROW_LIMIT = 1000;
+
+export function formatCell(value) {
+  if (value === null || value === undefined) return { text: 'NULL', isNull: true };
+  if (typeof value === 'object') return { text: JSON.stringify(value), isNull: false };
+  return { text: String(value), isNull: false };
+}
+
+async function failureOf(response) {
+  let message = `HTTP ${response.status}`;
+  try {
+    const body = await response.json();
+    if (body && typeof body.error === 'string') message = body.error;
+  } catch {}
+  return { kind: response.status === 400 ? 'query' : 'server', httpStatus: response.status, message };
+}
+
+export function createQueryRunner({ fetch, now, onChange }) {
+  let current = { status: 'idle' };
+  let seq = 0;
+  let inflight = null;
+
+  const set = (state) => {
+    current = state;
+    onChange(state);
+  };
+
+  async function execute(sql, id, controller) {
+    const started = now();
+    const elapsed = () => Math.round(now() - started);
+    let outcome;
+    try {
+      const response = await fetch('/query', { method: 'POST', body: JSON.stringify({ sql }), signal: controller.signal });
+      if (response.ok) {
+        const rows = await response.json();
+        if (!Array.isArray(rows)) throw new Error('unexpected response');
+        const shown = rows.slice(0, DISPLAY_ROW_LIMIT);
+        outcome = {
+          status: 'success',
+          sql,
+          rows: shown,
+          columns: shown.length ? Object.keys(shown[0]) : [],
+          rowCount: rows.length,
+          shownCount: shown.length,
+          truncated: rows.length > shown.length,
+        };
+      } else {
+        outcome = { status: 'error', sql, ...(await failureOf(response)) };
+      }
+    } catch (error) {
+      outcome =
+        error instanceof TypeError || error.name === 'AbortError'
+          ? { status: 'error', sql, kind: 'network', message: error.message }
+          : { status: 'error', sql, kind: 'server', message: error.message };
+    }
+    if (id !== seq) return;
+    inflight = null;
+    set({ ...outcome, elapsedMs: elapsed() });
+  }
+
+  return {
+    state: () => current,
+    run(sql) {
+      if (inflight && inflight.sql === sql) return Promise.resolve();
+      if (inflight) inflight.controller.abort();
+      seq += 1;
+      const controller = new AbortController();
+      inflight = { sql, controller, done: null };
+      set({ status: 'running', sql });
+      inflight.done = execute(sql, seq, controller);
+      return inflight.done;
+    },
+  };
+}
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+function summaryOf(state) {
+  const returned = `${plural(state.rowCount, 'row')} returned in ${state.elapsedMs} ms`;
+  if (state.truncated) return `${returned}. Display limit: first ${state.shownCount} shown.`;
+  if (state.rowCount === 0) return `${returned}. Column names are not available for an empty result.`;
+  return `${returned}.`;
+}
+
+function tableOf(doc, state) {
+  const table = doc.createElement('table');
+  const head = doc.createElement('tr');
+  for (const column of state.columns) {
+    const th = doc.createElement('th');
+    th.setAttribute('scope', 'col');
+    th.textContent = column;
+    head.append(th);
+  }
+  table.append(head);
+  for (const row of state.rows) {
+    const tr = doc.createElement('tr');
+    for (const column of state.columns) {
+      const { text, isNull } = formatCell(row[column]);
+      const td = doc.createElement('td');
+      td.textContent = text;
+      if (isNull) td.className = 'null';
+      tr.append(td);
+    }
+    table.append(tr);
+  }
+  return table;
+}
+
+const ERROR_LABEL = { query: 'Query error', server: 'Server error', network: 'Could not reach the server' };
+
+function errorText(state) {
+  if (state.kind === 'network') return `${ERROR_LABEL.network}: ${state.message}`;
+  const status = state.httpStatus ? ` (HTTP ${state.httpStatus})` : '';
+  return `${ERROR_LABEL[state.kind]}${status}: ${state.message}`;
+}
+
+export function renderResult(doc, container, state) {
+  const note = doc.createElement('p');
+  if (state.status === 'running') {
+    note.textContent = 'Running…';
+    container.replaceChildren(note);
+    return;
+  }
+  if (state.status === 'error') {
+    note.className = 'error';
+    note.setAttribute('role', 'alert');
+    note.textContent = errorText(state);
+    container.replaceChildren(note);
+    return;
+  }
+  if (state.status !== 'success') {
+    container.replaceChildren();
+    return;
+  }
+  note.textContent = summaryOf(state);
+  container.replaceChildren(...(state.rowCount ? [note, tableOf(doc, state)] : [note]));
+}
+
+if (typeof document !== 'undefined') {
+  const sql = document.getElementById('sql');
+  const run = document.getElementById('run');
+  const result = document.getElementById('result');
+  sql.value = STARTER_QUERY;
+  const runner = createQueryRunner({
+    fetch: (url, init) => fetch(url, init),
+    now: () => performance.now(),
+    onChange(state) {
+      run.setAttribute('aria-busy', String(state.status === 'running'));
+      renderResult(document, result, state);
+    },
+  });
+  const submit = () => runner.run(sql.value);
+  run.addEventListener('click', submit);
+  sql.addEventListener('keydown', (event) => {
+    if (event.key === 'Enter' && (event.ctrlKey || event.metaKey)) {
+      event.preventDefault();
+      submit();
+    }
+  });
+}