dirsql 0.3.59__tar.gz → 0.3.60__tar.gz

{dirsql-0.3.59 → dirsql-0.3.60}/Cargo.lock

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

{dirsql-0.3.59 → dirsql-0.3.60}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.59
+Version: 0.3.60
 Requires-Dist: pytest>=8 ; extra == 'dev'
 Requires-Dist: pytest-describe>=2 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'

dirsql-0.3.60/docs/AGENTS.md

@@ -0,0 +1,95 @@
+# Documentation Development
+
+Instructions for agents working on `dirsql` documentation.
+
+## Stack
+
+The docs site uses [VitePress](https://vitepress.dev/). Source files are in `docs/` at the project root.
+
+## Running locally
+
+```bash
+cd docs
+pnpm install
+pnpm dev
+```
+
+This starts a local dev server (default: `http://localhost:5173/dirsql/`). The site hot-reloads on file changes.
+
+## Building
+
+```bash
+cd docs
+pnpm build
+```
+
+The build must succeed before pushing. VitePress will fail on broken links, missing assets, and syntax errors in markdown.
+
+## Testing changes
+
+Before pushing any docs changes:
+
+1. Run `pnpm build` in `docs/` and confirm it exits cleanly
+2. Spot-check the built output with `pnpm preview`
+3. Verify sidebar navigation, code blocks, and internal links render correctly
+
+## Structure
+
+The docs follow the [Diataxis](https://diataxis.fr/) framework. **Type is
+the only organizational axis** -- there are no product-area sections (no
+"CLI" section; #353). The nav and the sidebar mirror the four types exactly.
+
+The **primary reader is the CLI user**: someone with a directory of files,
+one command (`uvx` / `npx dirsql`), and a `.dirsql.toml`. The SDKs are the
+secondary audience and appear **only in Reference**, plus the single
+"Embed `dirsql` in your application" how-to.
+
+Target tree (the spec for #353; existing pages are *quarried* into it, not
+migrated -- a page survives only if a slot wants its content):
+
+- **Tutorial** -- one lesson: *Your first dirsql database*. The reader
+  performs every step and sees output at each one; success is
+  author-guaranteed (toy dataset, no branching).
+- **How-to Guides** -- goal-named recipes: define tables for your files;
+  derive columns from file paths; extract rows from file contents
+  (`on-file`); search documents by meaning; skip files; load a SQLite
+  extension; keep the index across restarts; react to file changes; embed
+  `dirsql` in an application.
+- **Reference** -- CLI flags and defaults; the complete `.dirsql.toml`
+  schema; the command hook contract (placeholders, stdout protocol, exit
+  codes, timeouts); virtual columns and glob captures; the HTTP API;
+  per-language SDK pages (the sole SDK home).
+- **Explanation** -- one page: how `dirsql` thinks (the filesystem is the
+  source of truth; the database is a derived, ephemeral, read-only view;
+  reconcile and diffing). Its canonical home is the root `ARCHITECTURE.md`;
+  #374 surfaces it via an include page, the same mechanism
+  `docs/migrations.md` uses for `MIGRATIONS.md`. Edit the root file, never
+  a rendered include.
+
+Working rules:
+
+- **Facts live once, in Reference.** Tutorials and how-tos link to reference
+  material; they never re-list constructor parameters or duplicate API tables.
+- **A how-to opens with a 1-2 line goal/motivation statement.** Deep
+  rationale (tradeoffs, alternatives considered, theory) moves to Explanation
+  only when it is substantial enough to stand alone and is reused across
+  pages. Do not manufacture stub pages for a paragraph of "why".
+- **Tutorial vs how-to:** a tutorial is a lesson along a path the author
+  guarantees; a how-to serves a competent reader pursuing their own goal.
+- **One global sidebar.** Never add a path-scoped sidebar key -- it swaps
+  out the whole tree and hides every other section while inside one (#301;
+  see the comment above `sidebar` in `config.ts`).
+
+## Conventions
+
+- **Lead with the use case.** Open each feature description with *why* a
+  reader would reach for it before *how* it works. Don't frame a feature
+  by what an adjacent feature can't do.
+  *Don't:* "Persistence avoids the thing the default mode can't do..."
+  *Do:* "Persistence keeps the SQLite index on disk between runs so large
+  directories don't re-scan on every startup."
+- Wrap `dirsql` in backticks in all prose text
+- Use VitePress [code group](https://vitepress.dev/guide/markdown#code-groups) syntax (`::: code-group`) for multi-language examples with `Python`, `Rust`, and `TypeScript` tabs
+- Internal links use relative paths (e.g., `./guide/tables.md`)
+- The VitePress config is at `docs/.vitepress/config.ts`
+- The site is deployed under the `/dirsql/` base path

{dirsql-0.3.59 → dirsql-0.3.60}/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.3.59"
+version = "0.3.60"
 edition.workspace = true
 publish = false
 readme = "README.md"

dirsql-0.3.60/packages/python/docs/AGENTS.md

@@ -0,0 +1,95 @@
+# Documentation Development
+
+Instructions for agents working on `dirsql` documentation.
+
+## Stack
+
+The docs site uses [VitePress](https://vitepress.dev/). Source files are in `docs/` at the project root.
+
+## Running locally
+
+```bash
+cd docs
+pnpm install
+pnpm dev
+```
+
+This starts a local dev server (default: `http://localhost:5173/dirsql/`). The site hot-reloads on file changes.
+
+## Building
+
+```bash
+cd docs
+pnpm build
+```
+
+The build must succeed before pushing. VitePress will fail on broken links, missing assets, and syntax errors in markdown.
+
+## Testing changes
+
+Before pushing any docs changes:
+
+1. Run `pnpm build` in `docs/` and confirm it exits cleanly
+2. Spot-check the built output with `pnpm preview`
+3. Verify sidebar navigation, code blocks, and internal links render correctly
+
+## Structure
+
+The docs follow the [Diataxis](https://diataxis.fr/) framework. **Type is
+the only organizational axis** -- there are no product-area sections (no
+"CLI" section; #353). The nav and the sidebar mirror the four types exactly.
+
+The **primary reader is the CLI user**: someone with a directory of files,
+one command (`uvx` / `npx dirsql`), and a `.dirsql.toml`. The SDKs are the
+secondary audience and appear **only in Reference**, plus the single
+"Embed `dirsql` in your application" how-to.
+
+Target tree (the spec for #353; existing pages are *quarried* into it, not
+migrated -- a page survives only if a slot wants its content):
+
+- **Tutorial** -- one lesson: *Your first dirsql database*. The reader
+  performs every step and sees output at each one; success is
+  author-guaranteed (toy dataset, no branching).
+- **How-to Guides** -- goal-named recipes: define tables for your files;
+  derive columns from file paths; extract rows from file contents
+  (`on-file`); search documents by meaning; skip files; load a SQLite
+  extension; keep the index across restarts; react to file changes; embed
+  `dirsql` in an application.
+- **Reference** -- CLI flags and defaults; the complete `.dirsql.toml`
+  schema; the command hook contract (placeholders, stdout protocol, exit
+  codes, timeouts); virtual columns and glob captures; the HTTP API;
+  per-language SDK pages (the sole SDK home).
+- **Explanation** -- one page: how `dirsql` thinks (the filesystem is the
+  source of truth; the database is a derived, ephemeral, read-only view;
+  reconcile and diffing). Its canonical home is the root `ARCHITECTURE.md`;
+  #374 surfaces it via an include page, the same mechanism
+  `docs/migrations.md` uses for `MIGRATIONS.md`. Edit the root file, never
+  a rendered include.
+
+Working rules:
+
+- **Facts live once, in Reference.** Tutorials and how-tos link to reference
+  material; they never re-list constructor parameters or duplicate API tables.
+- **A how-to opens with a 1-2 line goal/motivation statement.** Deep
+  rationale (tradeoffs, alternatives considered, theory) moves to Explanation
+  only when it is substantial enough to stand alone and is reused across
+  pages. Do not manufacture stub pages for a paragraph of "why".
+- **Tutorial vs how-to:** a tutorial is a lesson along a path the author
+  guarantees; a how-to serves a competent reader pursuing their own goal.
+- **One global sidebar.** Never add a path-scoped sidebar key -- it swaps
+  out the whole tree and hides every other section while inside one (#301;
+  see the comment above `sidebar` in `config.ts`).
+
+## Conventions
+
+- **Lead with the use case.** Open each feature description with *why* a
+  reader would reach for it before *how* it works. Don't frame a feature
+  by what an adjacent feature can't do.
+  *Don't:* "Persistence avoids the thing the default mode can't do..."
+  *Do:* "Persistence keeps the SQLite index on disk between runs so large
+  directories don't re-scan on every startup."
+- Wrap `dirsql` in backticks in all prose text
+- Use VitePress [code group](https://vitepress.dev/guide/markdown#code-groups) syntax (`::: code-group`) for multi-language examples with `Python`, `Rust`, and `TypeScript` tabs
+- Internal links use relative paths (e.g., `./guide/tables.md`)
+- The VitePress config is at `docs/.vitepress/config.ts`
+- The site is deployed under the `/dirsql/` base path

{dirsql-0.3.59 → dirsql-0.3.60}/packages/python/e2e-attestation.json

@@ -1,6 +1,6 @@
 {
   "command": "uv run python -m pytest tests/e2e/ -x -q",
-  "ran_at": 1783120355,
+  "ran_at": 1783167859,
   "exit_code": 0,
-  "commit": "c460b738d83c83b4c76b10cd967e3641cbe35c7c"
+  "commit": "edd031c6e37ab86d3e7906b6e67b22d7c37ba43d"
 }