dirsql 0.4.8__tar.gz → 0.4.10__tar.gz

{dirsql-0.4.8 → dirsql-0.4.10}/Cargo.lock

@@ -500,7 +500,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.4.8"
+version = "0.4.10"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.4.8 → dirsql-0.4.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.4.8
+Version: 0.4.10
 Requires-Dist: tomli>=2 ; python_full_version < '3.11'
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index

dirsql-0.4.10/dirsql/cli/resolve_config_extensions.py

@@ -0,0 +1,70 @@
+"""Launcher-side resolution of the TOML configs' ``[[dirsql.extension]]`` entries.
+
+The compiled ``dirsql`` binary loads a config's extensions literally -- it
+has no ``importlib``, so it cannot resolve a bare **package name**. When any
+TOML config in argv names an extension by package name, the shared SDK
+resolver (:mod:`dirsql.resolve_config_extensions`) resolves every config's
+extensions and this launcher passes the resolved literal paths to the binary
+via repeatable ``--extension`` flags; the binary then loads those and ignores
+the configs' own extension entries.
+
+Every config flag occurrence counts -- ``-c``/``--config`` are repeatable,
+and plugin discovery injects fragments as additional ``-c`` flags -- so the
+scan collects them all, in argv order.
+
+Native-language configs (``.py`` / ``.js`` / ``.mjs`` / ``.cjs``) are untouched:
+the binary dispatches those to ``dirsql interpret``, whose handshake already
+carries resolved paths.
+"""
+
+from __future__ import annotations
+
+from ..resolve_config_extensions import resolve_configs_extension_specs
+
+# Config extensions the binary dispatches to `dirsql interpret`; never
+# pre-resolved here (that path resolves via the handshake).
+_NATIVE_SUFFIXES = (".py", ".js", ".mjs", ".cjs")
+
+
+def _config_paths_from_argv(argv: list[str]) -> list[str]:
+    """Every config value in argv, in order (``--config X``, ``--config=X``,
+    ``-c X``, ``-c=X``, ``-cX``), or the default when none are given."""
+    paths: list[str] = []
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a == "--config" or a == "-c":
+            # A bare trailing flag (no following value) yields "".
+            paths.append(next(iter(argv[i + 1 :]), ""))
+            i += 2
+            continue
+        if a.startswith("--config="):
+            paths.append(a[len("--config=") :])
+        elif a.startswith("-c"):
+            paths.append(a[len("-c") :].removeprefix("="))
+        i += 1
+    return paths or ["./.dirsql.toml"]
+
+
+def with_resolved_extensions(argv: list[str]) -> list[str]:
+    """Return ``argv`` plus ``--extension`` flags when a TOML config names an
+    extension by package name; otherwise return ``argv`` unchanged. Raises if a
+    package name cannot be resolved (the launcher surfaces a clean error)."""
+    if argv and argv[0] == "init":
+        return argv
+    config_paths = [
+        p for p in _config_paths_from_argv(argv) if not p.endswith(_NATIVE_SUFFIXES)
+    ]
+    if not config_paths:
+        return argv
+    specs = resolve_configs_extension_specs(config_paths)
+    if specs is None:
+        return argv
+    flags: list[str] = []
+    for spec in specs:
+        entrypoint = spec["entrypoint"]
+        flags.append("--extension")
+        flags.append(
+            f"{spec['path']}::{entrypoint}" if entrypoint is not None else spec["path"]
+        )
+    return [*argv, *flags]

{dirsql-0.4.8 → dirsql-0.4.10}/docs/.vitepress/config.ts

@@ -29,6 +29,7 @@ export default defineConfig({
       { text: 'How-to Guides', link: '/howto/define-tables' },
       { text: 'Reference', link: '/reference/cli' },
       { text: 'Explanation', link: '/explanation' },
+      { text: 'Plugins', link: '/plugins' },
       { text: 'GitHub', link: 'https://github.com/thekevinscott/dirsql' }
     ],
 
@@ -80,6 +81,12 @@ export default defineConfig({
           items: [
             { text: 'How dirsql thinks', link: '/explanation' }
           ]
+        },
+        {
+          text: 'Plugins',
+          items: [
+            { text: 'Available plugins', link: '/plugins' }
+          ]
         }
       ]
     },

dirsql-0.4.10/docs/plugins.md

@@ -0,0 +1,123 @@
+# Plugins
+
+A **plugin** is an ordinary Python package that ships a `dirsql.toml` config
+fragment and declares itself via a `dirsql` entry point. Installing it in the
+same environment as `dirsql` activates it: the `pip`/`uvx` launcher discovers
+the package and loads its fragment automatically, with zero config edits. The
+full discovery contract (ordering, opt-out, failure modes) is in the
+[CLI reference](./reference/cli.md#plugins); to build your own, see
+[Write a plugin](./howto/write-a-plugin.md).
+
+This page lists the first-party plugins.
+
+## `dirsql-plugin-embeddings`
+
+Semantic search over a directory of documents. The plugin embeds every matched
+file — `**/*.{md,markdown,mdx,rst,txt,pdf}` — into a `documents` table through
+any OpenAI-compatible `/v1/embeddings` endpoint, then turns each incoming
+question into nearest-neighbor SQL over that table, ranked by
+[`sqlite-vec`](https://github.com/asg017/sqlite-vec)'s
+`vec_distance_cosine()`.
+
+[PyPI](https://pypi.org/project/dirsql-plugin-embeddings/) ·
+[Source](https://github.com/thekevinscott/dirsql/tree/main/plugins/dirsql-plugin-embeddings)
+
+It is the packaged form of the
+[Search documents by meaning](./howto/search-by-meaning.md) how-to, with that
+guide's local `model2vec` model swapped for a hosted endpoint.
+
+### Install and launch
+
+The plugin is a normal PyPI package; installing it alongside `dirsql` is the
+whole install story (installed = active — there is no enable step). Point the
+three environment variables at any OpenAI-compatible inference server, hosted
+or self-managed:
+
+```sh
+export DIRSQL_EMBEDDINGS_BASE_URL="https://api.openai.com"
+export DIRSQL_EMBEDDINGS_MODEL="text-embedding-3-small"
+export DIRSQL_EMBEDDINGS_API_KEY="sk-…"
+
+uvx --with dirsql-plugin-embeddings --with sqlite-vec dirsql server
+```
+
+The launcher finds the package through its `dirsql` entry point and injects
+the shipped `dirsql.toml` fragment as an ordinary `-c` flag, composed after
+your own configs. The fragment declares three things:
+
+- the `sqlite-vec` extension (resolved from the installed `sqlite-vec`
+  package — hence the second `--with`), for `vec_distance_cosine()`;
+- the `documents` table (`path`, `text`, `embedding`), whose
+  [`on-file`](./reference/hooks.md#on-file) hook embeds each matched file at
+  index time;
+- a [`pre-query`](./reference/hooks.md#pre-query) hook that embeds each
+  incoming question and emits the nearest-neighbor SQL, plus a 300-second
+  [`hook-timeout`](./reference/config.md#dirsql-keys) so slow embedding calls
+  don't hit the 30-second default.
+
+Ask a question as a `{"q": …}` body — via `POST /query` against the server,
+or in one shot from the shell:
+
+```sh
+uvx --with dirsql-plugin-embeddings --with sqlite-vec \
+  dirsql query '{"q": "how do I cook spaghetti?"}'
+# [{"path":"pasta.md","distance":0.113}, …]
+```
+
+The result is the three nearest documents, closest first. Discovery can be
+turned off per-invocation with `--no-plugin` or `DIRSQL_NO_PLUGIN=1`
+([reference](./reference/cli.md#plugins)).
+
+### Configuration
+
+The v0.1 configuration surface is environment variables. The hooks run as
+subprocesses, so the variables must be set in the environment `dirsql` itself
+runs in — they are inherited, not read from a file.
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `DIRSQL_EMBEDDINGS_BASE_URL` | yes | Base URL of the embeddings server; `/v1/embeddings` is appended. |
+| `DIRSQL_EMBEDDINGS_MODEL` | yes | Model name sent in each request. |
+| `DIRSQL_EMBEDDINGS_API_KEY` | yes | Bearer token for the `Authorization` header. |
+| `DIRSQL_EMBEDDINGS_CACHE_READ` | no | Set to `0` to bypass reads of the on-disk PDF text-extraction cache (see below). Anything else, or unset, leaves the cache on. |
+
+PDF text extraction is the expensive step of a scan, and a scan re-reads every
+matched file — so extracted text is cached on disk at
+`~/.cache/dirsql-plugin-embeddings/`, keyed on the file's path and mtime. An
+edited PDF is a cache miss, never a stale hit. `DIRSQL_EMBEDDINGS_CACHE_READ=0`
+forces every call to re-extract; writes still happen, so the cache stays warm
+for the next run that reads it.
+
+### What gets indexed
+
+Every file matching `**/*.{md,markdown,mdx,rst,txt,pdf}` under the root.
+Everything except `.pdf` is read as UTF-8 text; a `.pdf` is read with
+[pypdf](https://pypdf.readthedocs.io), its per-page text joined and embedded
+like any other document. The extension check is case-insensitive (`.PDF` is a
+PDF), but the glob itself is not — an uppercase-suffixed file is not matched
+at all.
+
+The glob is an allowlist rather than `**/*` on cost, not correctness: every
+matched file costs a hook subprocess, and every file the plugin can decode
+costs a billed embedding call. Widening the list trades money for recall.
+
+A *scanned*, image-only PDF is not an error: pypdf yields no text and the file
+is indexed with an empty `text`, exactly like an empty `.md`.
+
+### When a file fails
+
+A file the plugin cannot process — an unreadable file, a failed embedding
+call — is skipped, not fatal. Per the
+[`on-file` failure contract](./reference/hooks.md#failure-semantics), the file
+contributes no rows, `dirsql` names it on stderr and keeps indexing the rest,
+and the run exits `23`: a partial index, distinct from `0` (clean) and `1`
+(the run failed). From the SDK the same information is available via
+`scan_failures()` / `scanFailures()`.
+
+### Planned configurability
+
+v0.1 is deliberately minimal: one provider shape, one table, one file = one
+row = one embedding (no chunking), and a hardcoded glob. Configurability —
+alternate embedding backends, chunking strategies, choosing which files get
+indexed, cache knobs — is tracked in
+[#619](https://github.com/thekevinscott/dirsql/issues/619).

{dirsql-0.4.8 → dirsql-0.4.10}/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.8"
+version = "0.4.10"
 # 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.10/packages/python/changelog.d/2026-08-03-discovery-ext-resolution.md

@@ -0,0 +1,8 @@
+**Fixed** The CLI launcher now resolves package-name `[[dirsql.extension]]`
+entries for **every** config flag in argv — `-c X`, `-c=X`, `-cX`,
+`--config X`, `--config=X`, repeated flags included — instead of only the
+first `--config`. In particular, config fragments injected by plugin
+discovery (which arrive as `-c` flags) get their package-name extensions
+resolved to literal paths, so a plugin declaring e.g. `path = "sqlite_vec"`
+loads on the pure discovery path instead of failing with
+`failed to load extension` (#754).

{dirsql-0.4.8 → dirsql-0.4.10}/packages/python/docs/.vitepress/config.ts

@@ -29,6 +29,7 @@ export default defineConfig({
       { text: 'How-to Guides', link: '/howto/define-tables' },
       { text: 'Reference', link: '/reference/cli' },
       { text: 'Explanation', link: '/explanation' },
+      { text: 'Plugins', link: '/plugins' },
       { text: 'GitHub', link: 'https://github.com/thekevinscott/dirsql' }
     ],
 
@@ -80,6 +81,12 @@ export default defineConfig({
           items: [
             { text: 'How dirsql thinks', link: '/explanation' }
           ]
+        },
+        {
+          text: 'Plugins',
+          items: [
+            { text: 'Available plugins', link: '/plugins' }
+          ]
         }
       ]
     },

dirsql-0.4.10/packages/python/docs/plugins.md

@@ -0,0 +1,123 @@
+# Plugins
+
+A **plugin** is an ordinary Python package that ships a `dirsql.toml` config
+fragment and declares itself via a `dirsql` entry point. Installing it in the
+same environment as `dirsql` activates it: the `pip`/`uvx` launcher discovers
+the package and loads its fragment automatically, with zero config edits. The
+full discovery contract (ordering, opt-out, failure modes) is in the
+[CLI reference](./reference/cli.md#plugins); to build your own, see
+[Write a plugin](./howto/write-a-plugin.md).
+
+This page lists the first-party plugins.
+
+## `dirsql-plugin-embeddings`
+
+Semantic search over a directory of documents. The plugin embeds every matched
+file — `**/*.{md,markdown,mdx,rst,txt,pdf}` — into a `documents` table through
+any OpenAI-compatible `/v1/embeddings` endpoint, then turns each incoming
+question into nearest-neighbor SQL over that table, ranked by
+[`sqlite-vec`](https://github.com/asg017/sqlite-vec)'s
+`vec_distance_cosine()`.
+
+[PyPI](https://pypi.org/project/dirsql-plugin-embeddings/) ·
+[Source](https://github.com/thekevinscott/dirsql/tree/main/plugins/dirsql-plugin-embeddings)
+
+It is the packaged form of the
+[Search documents by meaning](./howto/search-by-meaning.md) how-to, with that
+guide's local `model2vec` model swapped for a hosted endpoint.
+
+### Install and launch
+
+The plugin is a normal PyPI package; installing it alongside `dirsql` is the
+whole install story (installed = active — there is no enable step). Point the
+three environment variables at any OpenAI-compatible inference server, hosted
+or self-managed:
+
+```sh
+export DIRSQL_EMBEDDINGS_BASE_URL="https://api.openai.com"
+export DIRSQL_EMBEDDINGS_MODEL="text-embedding-3-small"
+export DIRSQL_EMBEDDINGS_API_KEY="sk-…"
+
+uvx --with dirsql-plugin-embeddings --with sqlite-vec dirsql server
+```
+
+The launcher finds the package through its `dirsql` entry point and injects
+the shipped `dirsql.toml` fragment as an ordinary `-c` flag, composed after
+your own configs. The fragment declares three things:
+
+- the `sqlite-vec` extension (resolved from the installed `sqlite-vec`
+  package — hence the second `--with`), for `vec_distance_cosine()`;
+- the `documents` table (`path`, `text`, `embedding`), whose
+  [`on-file`](./reference/hooks.md#on-file) hook embeds each matched file at
+  index time;
+- a [`pre-query`](./reference/hooks.md#pre-query) hook that embeds each
+  incoming question and emits the nearest-neighbor SQL, plus a 300-second
+  [`hook-timeout`](./reference/config.md#dirsql-keys) so slow embedding calls
+  don't hit the 30-second default.
+
+Ask a question as a `{"q": …}` body — via `POST /query` against the server,
+or in one shot from the shell:
+
+```sh
+uvx --with dirsql-plugin-embeddings --with sqlite-vec \
+  dirsql query '{"q": "how do I cook spaghetti?"}'
+# [{"path":"pasta.md","distance":0.113}, …]
+```
+
+The result is the three nearest documents, closest first. Discovery can be
+turned off per-invocation with `--no-plugin` or `DIRSQL_NO_PLUGIN=1`
+([reference](./reference/cli.md#plugins)).
+
+### Configuration
+
+The v0.1 configuration surface is environment variables. The hooks run as
+subprocesses, so the variables must be set in the environment `dirsql` itself
+runs in — they are inherited, not read from a file.
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `DIRSQL_EMBEDDINGS_BASE_URL` | yes | Base URL of the embeddings server; `/v1/embeddings` is appended. |
+| `DIRSQL_EMBEDDINGS_MODEL` | yes | Model name sent in each request. |
+| `DIRSQL_EMBEDDINGS_API_KEY` | yes | Bearer token for the `Authorization` header. |
+| `DIRSQL_EMBEDDINGS_CACHE_READ` | no | Set to `0` to bypass reads of the on-disk PDF text-extraction cache (see below). Anything else, or unset, leaves the cache on. |
+
+PDF text extraction is the expensive step of a scan, and a scan re-reads every
+matched file — so extracted text is cached on disk at
+`~/.cache/dirsql-plugin-embeddings/`, keyed on the file's path and mtime. An
+edited PDF is a cache miss, never a stale hit. `DIRSQL_EMBEDDINGS_CACHE_READ=0`
+forces every call to re-extract; writes still happen, so the cache stays warm
+for the next run that reads it.
+
+### What gets indexed
+
+Every file matching `**/*.{md,markdown,mdx,rst,txt,pdf}` under the root.
+Everything except `.pdf` is read as UTF-8 text; a `.pdf` is read with
+[pypdf](https://pypdf.readthedocs.io), its per-page text joined and embedded
+like any other document. The extension check is case-insensitive (`.PDF` is a
+PDF), but the glob itself is not — an uppercase-suffixed file is not matched
+at all.
+
+The glob is an allowlist rather than `**/*` on cost, not correctness: every
+matched file costs a hook subprocess, and every file the plugin can decode
+costs a billed embedding call. Widening the list trades money for recall.
+
+A *scanned*, image-only PDF is not an error: pypdf yields no text and the file
+is indexed with an empty `text`, exactly like an empty `.md`.
+
+### When a file fails
+
+A file the plugin cannot process — an unreadable file, a failed embedding
+call — is skipped, not fatal. Per the
+[`on-file` failure contract](./reference/hooks.md#failure-semantics), the file
+contributes no rows, `dirsql` names it on stderr and keeps indexing the rest,
+and the run exits `23`: a partial index, distinct from `0` (clean) and `1`
+(the run failed). From the SDK the same information is available via
+`scan_failures()` / `scanFailures()`.
+
+### Planned configurability
+
+v0.1 is deliberately minimal: one provider shape, one table, one file = one
+row = one embedding (no chunking), and a hardcoded glob. Configurability —
+alternate embedding backends, chunking strategies, choosing which files get
+indexed, cache knobs — is tracked in
+[#619](https://github.com/thekevinscott/dirsql/issues/619).

dirsql-0.4.10/packages/python/e2e-attestations/fix-754-discovery-ext-resolution.json

@@ -0,0 +1,7 @@
+{
+  "command": "just test-e2e",
+  "ran_at": 1785779409,
+  "exit_code": 0,
+  "commit": "610d8ff41538de6e3d5f19b4abea3ec1b351986a",
+  "branch": "fix/754-discovery-ext-resolution"
+}

dirsql-0.4.10/packages/rust/docs/plugins.md

@@ -0,0 +1,123 @@
+# Plugins
+
+A **plugin** is an ordinary Python package that ships a `dirsql.toml` config
+fragment and declares itself via a `dirsql` entry point. Installing it in the
+same environment as `dirsql` activates it: the `pip`/`uvx` launcher discovers
+the package and loads its fragment automatically, with zero config edits. The
+full discovery contract (ordering, opt-out, failure modes) is in the
+[CLI reference](./reference/cli.md#plugins); to build your own, see
+[Write a plugin](./howto/write-a-plugin.md).
+
+This page lists the first-party plugins.
+
+## `dirsql-plugin-embeddings`
+
+Semantic search over a directory of documents. The plugin embeds every matched
+file — `**/*.{md,markdown,mdx,rst,txt,pdf}` — into a `documents` table through
+any OpenAI-compatible `/v1/embeddings` endpoint, then turns each incoming
+question into nearest-neighbor SQL over that table, ranked by
+[`sqlite-vec`](https://github.com/asg017/sqlite-vec)'s
+`vec_distance_cosine()`.
+
+[PyPI](https://pypi.org/project/dirsql-plugin-embeddings/) ·
+[Source](https://github.com/thekevinscott/dirsql/tree/main/plugins/dirsql-plugin-embeddings)
+
+It is the packaged form of the
+[Search documents by meaning](./howto/search-by-meaning.md) how-to, with that
+guide's local `model2vec` model swapped for a hosted endpoint.
+
+### Install and launch
+
+The plugin is a normal PyPI package; installing it alongside `dirsql` is the
+whole install story (installed = active — there is no enable step). Point the
+three environment variables at any OpenAI-compatible inference server, hosted
+or self-managed:
+
+```sh
+export DIRSQL_EMBEDDINGS_BASE_URL="https://api.openai.com"
+export DIRSQL_EMBEDDINGS_MODEL="text-embedding-3-small"
+export DIRSQL_EMBEDDINGS_API_KEY="sk-…"
+
+uvx --with dirsql-plugin-embeddings --with sqlite-vec dirsql server
+```
+
+The launcher finds the package through its `dirsql` entry point and injects
+the shipped `dirsql.toml` fragment as an ordinary `-c` flag, composed after
+your own configs. The fragment declares three things:
+
+- the `sqlite-vec` extension (resolved from the installed `sqlite-vec`
+  package — hence the second `--with`), for `vec_distance_cosine()`;
+- the `documents` table (`path`, `text`, `embedding`), whose
+  [`on-file`](./reference/hooks.md#on-file) hook embeds each matched file at
+  index time;
+- a [`pre-query`](./reference/hooks.md#pre-query) hook that embeds each
+  incoming question and emits the nearest-neighbor SQL, plus a 300-second
+  [`hook-timeout`](./reference/config.md#dirsql-keys) so slow embedding calls
+  don't hit the 30-second default.
+
+Ask a question as a `{"q": …}` body — via `POST /query` against the server,
+or in one shot from the shell:
+
+```sh
+uvx --with dirsql-plugin-embeddings --with sqlite-vec \
+  dirsql query '{"q": "how do I cook spaghetti?"}'
+# [{"path":"pasta.md","distance":0.113}, …]
+```
+
+The result is the three nearest documents, closest first. Discovery can be
+turned off per-invocation with `--no-plugin` or `DIRSQL_NO_PLUGIN=1`
+([reference](./reference/cli.md#plugins)).
+
+### Configuration
+
+The v0.1 configuration surface is environment variables. The hooks run as
+subprocesses, so the variables must be set in the environment `dirsql` itself
+runs in — they are inherited, not read from a file.
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `DIRSQL_EMBEDDINGS_BASE_URL` | yes | Base URL of the embeddings server; `/v1/embeddings` is appended. |
+| `DIRSQL_EMBEDDINGS_MODEL` | yes | Model name sent in each request. |
+| `DIRSQL_EMBEDDINGS_API_KEY` | yes | Bearer token for the `Authorization` header. |
+| `DIRSQL_EMBEDDINGS_CACHE_READ` | no | Set to `0` to bypass reads of the on-disk PDF text-extraction cache (see below). Anything else, or unset, leaves the cache on. |
+
+PDF text extraction is the expensive step of a scan, and a scan re-reads every
+matched file — so extracted text is cached on disk at
+`~/.cache/dirsql-plugin-embeddings/`, keyed on the file's path and mtime. An
+edited PDF is a cache miss, never a stale hit. `DIRSQL_EMBEDDINGS_CACHE_READ=0`
+forces every call to re-extract; writes still happen, so the cache stays warm
+for the next run that reads it.
+
+### What gets indexed
+
+Every file matching `**/*.{md,markdown,mdx,rst,txt,pdf}` under the root.
+Everything except `.pdf` is read as UTF-8 text; a `.pdf` is read with
+[pypdf](https://pypdf.readthedocs.io), its per-page text joined and embedded
+like any other document. The extension check is case-insensitive (`.PDF` is a
+PDF), but the glob itself is not — an uppercase-suffixed file is not matched
+at all.
+
+The glob is an allowlist rather than `**/*` on cost, not correctness: every
+matched file costs a hook subprocess, and every file the plugin can decode
+costs a billed embedding call. Widening the list trades money for recall.
+
+A *scanned*, image-only PDF is not an error: pypdf yields no text and the file
+is indexed with an empty `text`, exactly like an empty `.md`.
+
+### When a file fails
+
+A file the plugin cannot process — an unreadable file, a failed embedding
+call — is skipped, not fatal. Per the
+[`on-file` failure contract](./reference/hooks.md#failure-semantics), the file
+contributes no rows, `dirsql` names it on stderr and keeps indexing the rest,
+and the run exits `23`: a partial index, distinct from `0` (clean) and `1`
+(the run failed). From the SDK the same information is available via
+`scan_failures()` / `scanFailures()`.
+
+### Planned configurability
+
+v0.1 is deliberately minimal: one provider shape, one table, one file = one
+row = one embedding (no chunking), and a hardcoded glob. Configurability —
+alternate embedding backends, chunking strategies, choosing which files get
+indexed, cache knobs — is tracked in
+[#619](https://github.com/thekevinscott/dirsql/issues/619).

dirsql-0.4.8/dirsql/cli/resolve_config_extensions.py

@@ -1,55 +0,0 @@
-"""Launcher-side resolution of a TOML config's ``[[dirsql.extension]]`` entries.
-
-The compiled ``dirsql`` binary loads a config's extensions literally -- it
-has no ``importlib``, so it cannot resolve a bare **package name**. When a
-TOML config names an extension by package name, the shared SDK resolver
-(:mod:`dirsql.resolve_config_extensions`) resolves every one of its
-extensions and this launcher passes the resolved literal paths to the binary
-via repeatable ``--extension`` flags; the binary then loads those and ignores
-the config's own extension entries.
-
-Native-language configs (``.py`` / ``.js`` / ``.mjs`` / ``.cjs``) are untouched:
-the binary dispatches those to ``dirsql interpret``, whose handshake already
-carries resolved paths.
-"""
-
-from __future__ import annotations
-
-from ..resolve_config_extensions import resolve_config_extension_specs
-
-# Config extensions the binary dispatches to `dirsql interpret`; never
-# pre-resolved here (that path resolves via the handshake).
-_NATIVE_SUFFIXES = (".py", ".js", ".mjs", ".cjs")
-
-
-def _config_path_from_argv(argv: list[str]) -> str:
-    """The ``--config`` value (``--config X`` or ``--config=X``), or the default."""
-    for i, a in enumerate(argv):
-        if a == "--config":
-            # A bare trailing `--config` (no following value) yields "".
-            return next(iter(argv[i + 1 :]), "")
-        if a.startswith("--config="):
-            return a[len("--config=") :]
-    return "./.dirsql.toml"
-
-
-def with_resolved_extensions(argv: list[str]) -> list[str]:
-    """Return ``argv`` plus ``--extension`` flags when the TOML config names an
-    extension by package name; otherwise return ``argv`` unchanged. Raises if a
-    package name cannot be resolved (the launcher surfaces a clean error)."""
-    if argv and argv[0] == "init":
-        return argv
-    config_path = _config_path_from_argv(argv)
-    if config_path.endswith(_NATIVE_SUFFIXES):
-        return argv
-    specs = resolve_config_extension_specs(config_path)
-    if specs is None:
-        return argv
-    flags: list[str] = []
-    for spec in specs:
-        entrypoint = spec["entrypoint"]
-        flags.append("--extension")
-        flags.append(
-            f"{spec['path']}::{entrypoint}" if entrypoint is not None else spec["path"]
-        )
-    return [*argv, *flags]