dirsql 0.4.118 → 0.4.120

package/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). |

package/package.json

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