dirsql 0.4.85 → 0.4.87

package/dist/dirsql.d.ts

@@ -22,7 +22,8 @@ export interface ExtensionSpec {
  * Options accepted by the {@link DirSQL} constructor.
  *
  * The index root is the explicit `root` when given, otherwise the process
- * working directory. The `config` file's location never sets the root.
+ * working directory. The `config` file's location never sets the root; its
+ * `[[table]]` globs anchor at the config file's own directory.
  */
 export interface DirSQLOptions {
     /** Root directory to scan. */

package/docs/howto/write-a-plugin.md

@@ -62,7 +62,9 @@ and [`ignore`](../reference/config.md#dirsql-keys).
 There are **no plugin-specific keys and no plugin-specific restrictions**. The
 config schema is content-only: the index root and persistence are
 [runner-owned](../reference/config.md#dirsql-keys) — the root is the directory
-`dirsql` is run from (or an SDK's explicit `root`), persistence is the
+`dirsql` is run from (or an SDK's explicit `root`) and governs path-tables,
+while a fragment's own `[[table]]` globs anchor at the fragment's directory
+(see [glob anchor](../reference/config.md#glob-anchor)); persistence is the
 `--persist [PATH]` flag — decided by whoever runs `dirsql`, never by a config
 file, so a plugin has nothing to say about them. Whatever you can put in your
 own `.dirsql.toml`, a plugin can put in its fragment, and vice-versa.
@@ -86,11 +88,10 @@ matter most for a published plugin:
 - **A hook runs in its declaring config's directory.** For a plugin that is
   the installed fragment's directory — inside **site-packages**. That is a
   read-only, shared location: **run from it, never write to it.** Read the
-  matched files from the absolute paths the hook appends as arguments, and use
-  [`{root}`](../reference/hooks.md#on-file) to reach the user's project
-  directory. Write any cache to `{root}` or a real cache dir,
-  never next to the fragment.
-- **The paths are absolute and `{root}` is the index root**, so a command is
+  matched files from the absolute paths the hook appends as arguments. Write any cache to a real cache dir, never next to
+  the fragment.
+- **The paths are absolute and `{root}` is the table's glob anchor** (the
+  fragment's directory, or the literal prefix of an absolute / `~/` glob), so a command is
   self-sufficient from any working directory — it works whether the plugin
   lives in the project or in site-packages.
 

package/docs/reference/cli.md

@@ -244,7 +244,7 @@ Config flags are subcommand-local: pass them after `server`
 
 | Flag | Default | Description |
 |---|---|---|
-| `-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 is always rooted at the **invocation directory** (the current working directory), regardless of where a config lives — so `--config /elsewhere/.dirsql.toml` still indexes the directory you ran `dirsql server` from. 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). |
+| `-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. |
 | `--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). |

package/docs/reference/config.md

@@ -14,17 +14,19 @@ with none given [no named tables](./cli.md#configless-mode) are defined (a
 `./.dirsql.toml` on disk is **not** auto-loaded). The [SDKs](./sdk.md) load a
 config via the `config` constructor parameter.
 
-**Path resolution.** Relative paths in the config (`[[dirsql.extension]]`
-`path`) resolve against the config file's parent
-directory. The **index root is not a config concern** — it is decided by the
-runner (the CLI's invocation directory, or an SDK's explicit root), never by
-the config file's location. See [`--config`](./cli.md#flags).
+**Path resolution.** A path written in a config resolves against the config
+file's parent directory: a `[[table]]` `glob` (see [anchoring](#glob-anchor)),
+`ignore`, and `[[dirsql.extension]]` `path`. A config therefore works from any
+working directory. The **index root is not a config concern** — it is decided
+by the runner (the CLI's invocation directory, or an SDK's explicit root) and
+governs only path-tables and programmatic tables. See
+[`--config`](./cli.md#flags).
 
 ## `[dirsql]` keys
 
 | Key | Type | Default | Description |
 |---|---|---|---|
-| `ignore` | array of strings | `[]` | Glob patterns matched against root-relative paths, under the [one glob rule](#glob-rule): `*` matches one level, `**` any depth. Matched files are skipped entirely — excluded from the initial scan and from watch events. |
+| `ignore` | array of strings | `[]` | Glob patterns matched against paths relative to the config file's directory, under the [one glob rule](#glob-rule): `*` matches one level, `**` any depth. They apply only to this config's `[[table]]` entries (not to path-tables, and not to another config's tables). Matched files are skipped entirely — excluded from the initial scan and from watch events. |
 
 There is no timeout key. `on-file` hook runs are unbounded; to bound one, wrap
 its command in `timeout(1)` (see [Command hooks](./hooks.md#bounding-a-hook)).
@@ -230,7 +232,7 @@ what its required `on-file` command emits — dirsql injects nothing (see
 |---|---|---|
 | `name` | yes | The table's SQL name — the name you query it by. Declared, never derived from `ddl`: dirsql does not read the DDL text. The `ddl` must create a table by this name; if it doesn't, loading fails. |
 | `ddl` | yes | A SQL batch, run verbatim — any number of statements. It must create a table called `name`; that table holds the file rows, and only the columns it declares are kept (keys the `on-file` command emits that are not declared are dropped). The rest of the batch is yours: indexes, virtual tables, triggers. See [Batch `ddl`](#batch-ddl). |
-| `glob` | yes | Glob pattern matched against root-relative paths, under the [one glob rule](#glob-rule): `*` matches one level, `**` any depth. Every table whose glob matches a file receives that file's rows — a file can populate multiple tables. A `{name}` segment is rewritten to `*` (it matches one path segment but captures nothing). |
+| `glob` | yes | Glob pattern, [anchored](#glob-anchor) at the config file's directory, under the [one glob rule](#glob-rule): `*` matches one level, `**` any depth. Every table whose glob matches a file receives that file's rows — a file can populate multiple tables. A `{name}` segment is rewritten to `*` (it matches one path segment but captures nothing). |
 | `on-file` | **yes** | A command run once per table, with every matched file's absolute path appended as a trailing argument; its stdout (one JSON array of row objects) is the table's rows. Must be non-empty. A `[[table]]` with no `on-file` is a load error (see [parse errors](#parse-errors)). See [Command hooks](./hooks.md#on-file). |
 | `strict` | no (default `false`) | When `true`, rows whose keys do not exactly match the declared columns are rejected with an error: extra keys error, and every declared column must be supplied by the `on-file` output. When `false`, extra keys are dropped and missing columns become `NULL`. |
 
@@ -256,6 +258,22 @@ on-file = "uv run python extract_papers.py"
 strict  = true
 ```
 
+### Glob anchor
+
+A table's `glob` is matched beneath its **anchor**, never the index root:
+
+| `glob` starts with | Anchor |
+|---|---|
+| nothing special, or `./` | the config file's directory |
+| `/` (or a drive / UNC root) | the literal directory chain before the first glob character |
+| `~/` | your home directory, then the literal chain |
+| `../` | resolved against the config file's directory, then the literal chain |
+
+So `glob = "projects/*/*.jsonl"` in `~/.claude/.dirsql.toml` indexes
+`~/.claude/projects` from any working directory, and a shared config elsewhere
+writes `glob = "~/.claude/projects/*/*.jsonl"`. A table's `path` and `dir`
+columns, `{root}`, and `ignore` are all relative to its anchor.
+
 ### Batch `ddl`
 
 `ddl` is handed to SQLite whole, so a table declaration is not limited to one
@@ -346,7 +364,7 @@ dirsql -c ./.dirsql.toml -c ~/team/embeddings.toml -c ./local.toml
 
 The configs load and merge in **argv order**:
 
-- **`[[table]]`, `ignore`, `[[dirsql.extension]]`, and `[[dirsql.function]]`
+- **`[[table]]`, `[[dirsql.extension]]`, and `[[dirsql.function]]`
   entries accumulate** across all configs, in order.
 - **Each config's `on-file` hooks and `[[dirsql.function]]` workers run from
   that config file's own directory** — so a relative command like
@@ -360,7 +378,8 @@ The configs load and merge in **argv order**:
   silent last-writer-wins.
 
 The index [root](./cli.md#flags) is the invocation directory regardless of where
-any config lives. With no `-c`, [no named tables](./cli.md#configless-mode) are
+any config lives; each config's `[[table]]` globs anchor at that config's own
+directory, and its `ignore` applies to its own tables only. With no `-c`, [no named tables](./cli.md#configless-mode) are
 defined (no `./.dirsql.toml` auto-discovery); a single `-c` behaves exactly as
 before.
 

package/docs/reference/hooks.md

@@ -42,7 +42,8 @@ relative paths in the command resolve predictably regardless of where
 `dirsql` was launched. A command named by the `--on-file` flag has no config
 file: it runs in the **index root**, the directory `dirsql query` was run in,
 which is also the directory a `./` path-table is relative to. In both forms
-`{root}` is the index root. The command inherits `dirsql`'s environment, so
+`{root}` is where the table's glob is anchored: the index root for `--on-file`,
+the [glob anchor](./config.md#glob-anchor) for a `[[table]]`. The command inherits `dirsql`'s environment, so
 tools like `uvx --with …` / `npx …` resolve their dependencies as usual.
 
 ### stdout protocol
@@ -143,7 +144,7 @@ the path or stat metadata emits it (it has the paths).
 
 | Placeholder | Value |
 |---|---|
-| `{root}` | The index root directory. Derive a root-relative path with `relpath(path, {root})`. |
+| `{root}` | The directory the table's glob is anchored at (the index root for `--on-file`; the config file's directory, or the literal prefix of an absolute / `~/` glob, for a `[[table]]`). Derive an anchor-relative path with `relpath(path, {root})`. |
 
 The matched files' **absolute** paths are not placeholders: they are appended
 to the command as trailing arguments, after everything written in the

package/docs/reference/sdk.md

@@ -98,7 +98,9 @@ DirSQL::builder()
 
 Creates a SQLite index over a directory. The index root is the explicit
 `root` when given, else the **process cwd** — the `config` file's location
-never sets the root.
+never sets the root. A config's `[[table]]` globs anchor at the config file's
+own directory instead (see [glob anchor](./config.md#glob-anchor)); `root`
+governs programmatic tables and path-tables.
 
 Constructing with **neither a `config` nor programmatic `tables`** defines
 **no named tables** — the same as the CLI with no
@@ -127,7 +129,9 @@ shortcut was removed in #603 — use
   entries are appended after any programmatic `tables`; its `ignore`
   patterns and `[[dirsql.extension]]` entries are appended likewise. The
   config file does **not** set the index root: with no explicit `root`, the
-  index roots at the process cwd. **Multiple configs merge in order** on
+  index roots at the process cwd. Its `[[table]]` globs anchor at the config
+  file's directory (or at the literal prefix of an absolute / `~/` glob), not
+  at `root`; its `ignore` applies to its own tables only. **Multiple configs merge in order** on
   every SDK — **Python** `config` accepts a `str` or a `list[str]`, the
   **Rust** builder's `.config()` is repeatable (call it once per file), and
   **TypeScript** `config` accepts a `string` or a `string[]`; the configs

package/package.json

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