dirsql 0.4.101 → 0.4.102

package/dist/dirsql.d.ts

@@ -43,7 +43,7 @@ export interface DirSQLOptions {
     config?: string | string[];
     /**
      * Enable persistent on-disk SQLite cache. When `true`, the database is
-     * written to `<root>/.dirsql/cache.db` (override via `persistPath`) so
+     * written to the platform cache directory (override via `persistPath`) so
      * subsequent startups only re-parse files that have actually changed.
      */
     persist?: boolean;

package/docs/howto/persist.md

@@ -17,9 +17,11 @@ why it is a CLI flag, not a config key.
 dirsql --persist
 ```
 
-That's the whole change. On the next run the cache is written to
-`.dirsql/cache.db` under the root; runs after that start from it. To put
-the cache elsewhere (a CI cache dir, a tmpfs), pass a path:
+That's the whole change. On the next run the cache is written to your platform cache directory
+(`$XDG_CACHE_HOME/dirsql/<root hash>/cache.db` on Linux, `~/Library/Caches`
+on macOS, `%LOCALAPPDATA%` on Windows), outside the scanned tree; runs after
+that start from it. To put the cache elsewhere (a CI cache dir, a tmpfs), pass
+a path:
 
 ```bash
 dirsql --persist /var/cache/dirsql.db
@@ -30,20 +32,13 @@ put a bare `--persist` after the SQL there so it does not consume the query
 argument. Embedding `dirsql`? The SDK constructors expose the same switch —
 see [_Embedding `dirsql`?_](#embedding-dirsql) below.
 
-## 2. Keep the cache out of git
+## 2. Nothing to ignore in git
 
-The cache is derived data — reproducible from the tree and frequently
-large. Add it to `.gitignore`:
-
-```
-.dirsql/
-```
-
-The top-level `.dirsql/` directory is reserved for `dirsql`'s metadata and
-is never scanned as data, so the cache can't index itself
-([config reference](../reference/config.md#dirsql-keys)). While running,
-`dirsql` also creates transient `cache.db-wal` and `cache.db-shm` sidecar
-files next to the cache; the `.dirsql/` ignore already covers all three.
+The default cache lives outside the scanned tree, so there is nothing to add
+to `.gitignore` and the cache can't index itself. With `--persist <path>`, keep
+that path out of the scanned tree too, or ignore it. While running, `dirsql`
+also creates transient `cache.db-wal` and `cache.db-shm` sidecar files next to
+the cache.
 
 ## What survives, what rebuilds
 

package/docs/howto/search-indexes.md

@@ -224,7 +224,7 @@ Rows are embedded once, at ingest, and cached on disk by content and model
 ::: warning Editing `ddl` wedges a persisted `vec0` cache
 Under `--persist`, editing any part of a `ddl` batch whose cache holds a
 `vec0` table currently fails with `SQLite error: no such module: vec0`, and
-keeps failing until the cache is deleted (`rm -rf <root>/.dirsql`). Tracked in
+keeps failing until the cache is deleted (delete it, or pass a fresh `--persist <path>`). Tracked in
 [#1008](https://github.com/thekevinscott/dirsql/issues/1008); FTS5 is
 unaffected.
 :::

package/docs/howto/skip-files.md

@@ -51,9 +51,6 @@ dirsql query "SELECT basename FROM notes ORDER BY basename" -c ./.dirsql.toml
   list, though its path-tables still apply the built-in
   [skip rules](../reference/path-tables.md#skip-rules) and respect
   `.gitignore`.
-- The top-level `.dirsql/` directory is always excluded, ignore list or
-  not — it is reserved for `dirsql`'s own metadata
-  ([config reference](../reference/config.md#dirsql-keys)).
 - Narrow table globs are the other half of the story: a file matching no
   table's glob contributes no rows either. Use `ignore` for things that
   should never be looked at; use precise globs to shape what each table

package/docs/reference/cli.md

@@ -248,7 +248,7 @@ Config flags are subcommand-local: pass them after `server`
 | `--host <addr>` | `localhost` | Bind address. |
 | `--port <n>` | `7117` | TCP port to bind. |
 | `--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 at `<root>/.dirsql/cache.db`; `--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). |
+| `--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). |
 | `--extension <path>` | none | Load a SQLite extension by literal path, overriding the config's `[[dirsql.extension]]` entries. Repeatable. Format: `<path>` or `<path>::<entrypoint>`. Internal plumbing for the pip/npm launchers, which resolve package-name extensions and pass the resolved paths here — not intended for direct use. When any `--extension` is present, the config file's own extension entries are not loaded. |
 | `--version` | | Print the version and exit. |

package/docs/reference/config.md

@@ -34,12 +34,6 @@ A config that still declares the removed `hook-timeout` key fails to load with
 an error naming that replacement. [`[[dirsql.function]]`](#dirsql-function)
 worker calls have their own per-call `timeout` key (default 30 seconds).
 
-The top-level `.dirsql/` directory under the root is always excluded from
-scanning, whether or not it appears in `ignore` — it is reserved for
-`dirsql`'s own metadata (the persist cache lives there by default). Only the
-top-level `.dirsql/` is reserved; a nested `sub/.dirsql/` is an ordinary
-directory.
-
 ```toml
 [dirsql]
 ignore = ["node_modules/**", ".git/**"]

package/docs/reference/path-tables.md

@@ -228,8 +228,7 @@ The table itself is per-connection: it lives in `temp`, so it cannot leak into
 `sqlite_master` or survive a restart. Under `--persist` a *parsed* table's rows
 outlive the connection in the cache (above), but the table is still minted
 fresh each run and the scan still decides what exists. A `.dirsql/` directory
-at the top of the directory the scan starts in is reserved and excluded, as
-everywhere else.
+is an ordinary dot directory.
 
 ### When to promote to a declared table
 

package/docs/reference/sdk.md

@@ -86,7 +86,7 @@ DirSQL::builder()
     .config(config_toml_path)       // optional; repeatable — call again to
                                     //   merge another config in call order
     .persist(cache_path)            // optional; Some(path), or None for the
-                                    //   default <root>/.dirsql/cache.db
+                                    //   platform cache dir
     .extensions(extensions)         // optional; append one with .extension(e)
     .poll_interval(duration)        // optional; watch-loop cadence, default 200ms
     .build()                        // -> Result<DirSQL>  (synchronous scan)
@@ -139,8 +139,8 @@ shortcut was removed in #603 — use
   accumulate; a duplicate table name across configs errors), mirroring the
   CLI's repeatable [`-c/--config`](./cli.md#flags).
 - `persist` — Keep the SQLite index on disk between runs (default off:
-  ephemeral, rebuilt every startup). The cache lives at
-  `<root>/.dirsql/cache.db` by default; on restart, only files whose stat
+  ephemeral, rebuilt every startup). The cache lives in the
+  platform cache directory by default (outside `<root>`); on restart, only files whose stat
   changed are re-parsed. (The CLI exposes the same switch as the
   [`--persist [PATH]`](./cli.md#dirsql-server) flag; it is not a config key.)
 - `persist_path` / `persistPath` — Override the cache location. Ignored when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.4.101",
+  "version": "0.4.102",
   "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.101",
-    "@dirsql/lib-linux-arm64-gnu": "0.4.101",
-    "@dirsql/lib-darwin-x64": "0.4.101",
-    "@dirsql/lib-darwin-arm64": "0.4.101",
-    "@dirsql/lib-win32-x64-msvc": "0.4.101"
+    "@dirsql/lib-linux-x64-gnu": "0.4.102",
+    "@dirsql/lib-linux-arm64-gnu": "0.4.102",
+    "@dirsql/lib-darwin-x64": "0.4.102",
+    "@dirsql/lib-darwin-arm64": "0.4.102",
+    "@dirsql/lib-win32-x64-msvc": "0.4.102"
   }
 }