dirsql 0.0.16__tar.gz → 0.0.18__tar.gz

dirsql-0.0.18/.claude/CLAUDE.md

@@ -0,0 +1,3 @@
+# dirsql
+
+All project conventions, workflow rules, and development instructions are in [AGENTS.md](../AGENTS.md).

{dirsql-0.0.16 → dirsql-0.0.18}/.gitignore

@@ -1,7 +1,6 @@
 /target
 .beads
 .claude/settings.local.json
-AGENTS.md
 
 # Dolt database files (added by bd init)
 .dolt/

{dirsql-0.0.16 → dirsql-0.0.18}/PKG-INFO

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

{dirsql-0.0.16 → dirsql-0.0.18}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "dirsql"
-version = "0.0.16"
+version = "0.0.18"
 description = "Ephemeral SQL index over a local directory"
 license = "MIT"
 requires-python = ">=3.12"
@@ -24,7 +24,7 @@ dev = [
 ]
 
 [tool.maturin]
-features = ["pyo3/extension-module"]
+features = ["extension-module"]
 exclude = [
     ".github/",
     ".claude/",

{dirsql-0.0.16 → dirsql-0.0.18}/python/dirsql/_async.py

@@ -33,7 +33,8 @@ class AsyncDirSQL:
     """Async wrapper around DirSQL.
 
     Usage:
-        db = await AsyncDirSQL(root, tables=[...])
+        db = AsyncDirSQL(root, tables=[...])
+        await db.ready()
         results = await db.query("SELECT ...")
         async for event in db.watch():
             ...
@@ -44,15 +45,30 @@ class AsyncDirSQL:
         self._tables = tables
         self._ignore = ignore
         self._db = None
-
-    def __await__(self):
-        return self._init().__await__()
-
-    async def _init(self):
-        self._db = await asyncio.to_thread(
-            DirSQL, self._root, tables=self._tables, ignore=self._ignore
-        )
-        return self
+        self._ready_event = asyncio.Event()
+        self._init_error = None
+        self._task = asyncio.ensure_future(self._init_bg())
+
+    async def _init_bg(self):
+        """Run the scan in the background."""
+        try:
+            self._db = await asyncio.to_thread(
+                DirSQL, self._root, tables=self._tables, ignore=self._ignore
+            )
+        except Exception as exc:
+            self._init_error = exc
+        finally:
+            self._ready_event.set()
+
+    async def ready(self):
+        """Wait until the initial scan is complete.
+
+        Raises any exception that occurred during init.
+        Can be called multiple times safely.
+        """
+        await self._ready_event.wait()
+        if self._init_error is not None:
+            raise self._init_error
 
     async def query(self, sql):
         """Execute a SQL query asynchronously."""

{dirsql-0.0.16 → dirsql-0.0.18}/tests/integration/test_async_dirsql.py

@@ -12,9 +12,9 @@ from dirsql import AsyncDirSQL, Table
 def describe_AsyncDirSQL():
     def describe_init():
         @pytest.mark.asyncio
-        async def it_creates_instance_with_await(jsonl_dir):
-            """AsyncDirSQL can be initialized with await."""
-            db = await AsyncDirSQL(
+        async def it_creates_instance_synchronously(jsonl_dir):
+            """AsyncDirSQL constructor is sync and returns immediately."""
+            db = AsyncDirSQL(
                 jsonl_dir,
                 tables=[
                     Table(
@@ -35,9 +35,9 @@ def describe_AsyncDirSQL():
             assert db is not None
 
         @pytest.mark.asyncio
-        async def it_indexes_files_on_init(jsonl_dir):
-            """Async init scans and indexes directory contents."""
-            db = await AsyncDirSQL(
+        async def it_indexes_files_after_ready(jsonl_dir):
+            """Data is available after awaiting ready()."""
+            db = AsyncDirSQL(
                 jsonl_dir,
                 tables=[
                     Table(
@@ -55,33 +55,61 @@ def describe_AsyncDirSQL():
                     ),
                 ],
             )
+            await db.ready()
             results = await db.query("SELECT * FROM comments")
             assert len(results) == 3
 
         @pytest.mark.asyncio
-        async def it_raises_on_extract_error_during_init(tmp_dir):
-            """Extract lambda errors during init raise exceptions."""
+        async def it_raises_on_extract_error_during_ready(tmp_dir):
+            """Extract lambda errors during ready() raise exceptions."""
             os.makedirs(os.path.join(tmp_dir, "data"), exist_ok=True)
             with open(os.path.join(tmp_dir, "data", "bad.json"), "w") as f:
                 f.write("not valid json")
 
+            db = AsyncDirSQL(
+                tmp_dir,
+                tables=[
+                    Table(
+                        ddl="CREATE TABLE items (name TEXT)",
+                        glob="data/*.json",
+                        extract=lambda path, content: [json.loads(content)],
+                    ),
+                ],
+            )
             with pytest.raises(Exception):
-                await AsyncDirSQL(
-                    tmp_dir,
-                    tables=[
-                        Table(
-                            ddl="CREATE TABLE items (name TEXT)",
-                            glob="data/*.json",
-                            extract=lambda path, content: [json.loads(content)],
-                        ),
-                    ],
-                )
+                await db.ready()
+
+        @pytest.mark.asyncio
+        async def it_allows_multiple_ready_calls(jsonl_dir):
+            """Calling ready() multiple times is safe and idempotent."""
+            db = AsyncDirSQL(
+                jsonl_dir,
+                tables=[
+                    Table(
+                        ddl="CREATE TABLE comments (id TEXT, body TEXT, author TEXT)",
+                        glob="comments/**/index.jsonl",
+                        extract=lambda path, content: [
+                            {
+                                "id": os.path.basename(os.path.dirname(path)),
+                                "body": row["body"],
+                                "author": row["author"],
+                            }
+                            for line in content.splitlines()
+                            for row in [json.loads(line)]
+                        ],
+                    ),
+                ],
+            )
+            await db.ready()
+            await db.ready()
+            results = await db.query("SELECT * FROM comments")
+            assert len(results) == 3
 
     def describe_query():
         @pytest.mark.asyncio
         async def it_returns_results_as_list_of_dicts(jsonl_dir):
             """Async query returns list of dicts with column names."""
-            db = await AsyncDirSQL(
+            db = AsyncDirSQL(
                 jsonl_dir,
                 tables=[
                     Table(
@@ -99,6 +127,7 @@ def describe_AsyncDirSQL():
                     ),
                 ],
             )
+            await db.ready()
             results = await db.query(
                 "SELECT author FROM comments WHERE body = 'first comment'"
             )
@@ -108,7 +137,7 @@ def describe_AsyncDirSQL():
         @pytest.mark.asyncio
         async def it_raises_on_invalid_sql(jsonl_dir):
             """Invalid SQL raises an exception."""
-            db = await AsyncDirSQL(
+            db = AsyncDirSQL(
                 jsonl_dir,
                 tables=[
                     Table(
@@ -126,6 +155,7 @@ def describe_AsyncDirSQL():
                     ),
                 ],
             )
+            await db.ready()
             with pytest.raises(Exception):
                 await db.query("NOT VALID SQL")
 
@@ -133,7 +163,7 @@ def describe_AsyncDirSQL():
         @pytest.mark.asyncio
         async def it_emits_insert_events_for_new_files(tmp_dir):
             """watch() yields insert events when a new file is created."""
-            db = await AsyncDirSQL(
+            db = AsyncDirSQL(
                 tmp_dir,
                 tables=[
                     Table(
@@ -143,6 +173,7 @@ def describe_AsyncDirSQL():
                     ),
                 ],
             )
+            await db.ready()
 
             events = []
 
@@ -179,7 +210,7 @@ def describe_AsyncDirSQL():
             with open(os.path.join(tmp_dir, "doomed.json"), "w") as f:
                 json.dump({"name": "doomed"}, f)
 
-            db = await AsyncDirSQL(
+            db = AsyncDirSQL(
                 tmp_dir,
                 tables=[
                     Table(
@@ -189,6 +220,7 @@ def describe_AsyncDirSQL():
                     ),
                 ],
             )
+            await db.ready()
 
             # Confirm initial data
             results = await db.query("SELECT * FROM items")
@@ -228,7 +260,7 @@ def describe_AsyncDirSQL():
             with open(os.path.join(tmp_dir, "item.json"), "w") as f:
                 json.dump({"name": "draft"}, f)
 
-            db = await AsyncDirSQL(
+            db = AsyncDirSQL(
                 tmp_dir,
                 tables=[
                     Table(
@@ -238,6 +270,7 @@ def describe_AsyncDirSQL():
                     ),
                 ],
             )
+            await db.ready()
 
             events = []
 
@@ -267,7 +300,7 @@ def describe_AsyncDirSQL():
         @pytest.mark.asyncio
         async def it_emits_error_events_for_bad_extract(tmp_dir):
             """watch() yields error events when extract lambda fails."""
-            db = await AsyncDirSQL(
+            db = AsyncDirSQL(
                 tmp_dir,
                 tables=[
                     Table(
@@ -277,6 +310,7 @@ def describe_AsyncDirSQL():
                     ),
                 ],
             )
+            await db.ready()
 
             events = []
 
@@ -305,7 +339,7 @@ def describe_AsyncDirSQL():
         @pytest.mark.asyncio
         async def it_updates_db_on_file_changes(tmp_dir):
             """The database is kept in sync with file system changes."""
-            db = await AsyncDirSQL(
+            db = AsyncDirSQL(
                 tmp_dir,
                 tables=[
                     Table(
@@ -315,6 +349,7 @@ def describe_AsyncDirSQL():
                     ),
                 ],
             )
+            await db.ready()
 
             # Initially empty
             results = await db.query("SELECT * FROM items")

dirsql-0.0.16/.claude/CLAUDE.md

@@ -1,132 +0,0 @@
-# dirsql Development
-
-## Cross-Language Parity
-
-dirsql ships SDKs in Rust, Python, and TypeScript. Aim for **complete API parity across all three languages**: same concepts, same capabilities, same naming where possible. Exceptions are allowed for language-idiomatic patterns:
-
-- **Python**: `await db.ready()` (method call, not awaitable property). snake_case. Async iterators for event streams.
-- **TypeScript**: `await db.ready` (awaitable property is idiomatic). camelCase. AsyncIterables for event streams.
-- **Rust**: Builder pattern or `db.ready().await`. snake_case. Stream trait for event streams.
-
-When adding a feature to one SDK, create beads for the other two. Don't let them drift apart.
-
-## Scratch Files
-
-Write scratch/temporary files to `/tmp` instead of asking permission. Use unique filenames to avoid collisions with other sessions.
-
-## Workflow
-
-- Work in git worktrees under `.worktrees/` folder
-- **NEVER commit directly to main** - always create a PR
-- One PR per bead. Beads should be concise and small -- as small as possible while still being useful
-- Use `bd` (Beads) for task tracking: `bd list`, `bd show <id>`, `bd ready`
-- **Bead first**: When starting new work, the first step is always to create a bead (`bd create`). No implementation work begins without a bead.
-
-### Git Worktrees
-
-**ALL work happens in git worktrees.** Never edit files in the root repo directory. Never commit outside a worktree.
-
-#### Creating a Worktree
-
-```bash
-git worktree add .worktrees/my-feature -b feat/my-feature
-cd .worktrees/my-feature
-```
-
-#### Removing a Worktree
-
-**DANGER: removing a worktree while your shell CWD is inside it permanently breaks the shell.** The ONLY safe procedure:
-
-```bash
-# Step 1: Move CWD to the root repo FIRST (not optional)
-cd /home/duncan/work/code/projects/dirsql
-
-# Step 2: Now remove the worktree
-git worktree remove .worktrees/my-feature
-```
-
-**Do NOT skip step 1. Do NOT substitute `git -C` for `cd`.**
-
-### Beads Workflow
-
-**Lifecycle:**
-1. **Claim it FIRST**: `bd update <id> --claim` before any work
-2. **Create worktree and branch**
-3. **Link the PR**: `bd update <id> --external-ref "gh-<pr-number>"` after creating the PR
-4. **Close**: `bd close <id>` immediately after the PR is merged
-
-### Subagent Workflow
-
-New work on beads should be done via subagents in isolated worktrees. Each subagent:
-1. Claims the bead (`bd update <id> --claim`) before starting any work
-2. Creates a worktree and branch for its bead
-3. Does the implementation work (red/green TDD)
-4. Pushes the branch and opens a PR
-5. Monitors the PR and proactively resolves:
-   - CI failures
-   - GPG signing complaints
-   - Merge conflicts
-6. Continues monitoring until the PR is in a mergeable state
-
-### Orchestrator Responsibilities
-
-The orchestrator (main Claude session) must proactively:
-1. **Monitor all open PRs** -- don't wait for the user to report failures. Check CI status after agent completion and on an ongoing basis.
-2. **Fix CI failures** on open PRs immediately, either directly or by dispatching a fix agent.
-3. **Handle post-merge cleanup** as soon as a PR merges (pull main, remove worktree, delete branch, close bead).
-4. **Keep the user informed** of PR status without being asked.
-5. **Use foreground monitoring** when waiting on CI and there's no other work to do. Background monitoring causes the conversation to go silent -- use it only when there's genuinely parallel work to perform.
-6. **Scripts to `/tmp`**: For polling/monitoring scripts (watching CI, waiting for merges), write the script to `/tmp` then run it via `bash /tmp/script.sh`. Do not use inline bash loops in tool calls.
-
-### Post-Merge Cleanup
-
-After a PR merges, the agent (or orchestrator) must:
-1. Pull main in the **root repo**: `git -C /home/duncan/work/code/projects/dirsql pull origin main`
-2. **Move CWD to root repo first** (CRITICAL -- never remove a worktree from inside it): `cd /home/duncan/work/code/projects/dirsql`
-3. Remove the worktree: `git worktree remove .worktrees/<name>`
-4. Delete the local branch: `git branch -d <branch-name>`
-5. **Verify the bead is addressed** by the merged PR, then close it: `bd close <id>`
-
-## Testing
-
-### Red/Green Development
-
-Follow **red/green** (test-first) methodology:
-
-1. **Write the test first** -- it must capture the desired behavior
-2. **Run it and confirm it fails (RED)** -- do NOT proceed until the test turns red reliably. A test that passes before implementation proves nothing.
-3. **Make the minimal change to pass (GREEN)** -- only then write the implementation
-4. Refactor if needed, keeping tests green
-
-### TDD Order: Outside-In
-
-Tests are written **before** implementation, starting from the outermost layer:
-
-1. **Integration test first** -- proves the feature works from the consumer's perspective
-2. **Unit tests** -- written as you implement each module
-
-A feature is not done until integration tests pass and cover the new functionality.
-
-### When to Write What
-
-**Does the commit change the public-facing API?**
-- Yes -> **integration test required**, plus unit tests as you go
-- No -> Check if adequate integration coverage already exists:
-  - Adequate -> unit tests only
-  - Gaps -> add the missing integration tests, plus unit tests
-
-**Always write unit tests.** The question is whether you also need integration tests.
-
-### Test Locations
-
-- **Unit tests**: Colocated with source
-  - Python: `foo.py` -> `foo_test.py` in same directory
-  - Rust: inline `#[cfg(test)]` module at bottom of each source file
-- **Integration tests**: `tests/integration/` -- test the Python SDK layer, mock third-party deps (SQLite, LLM calls). Heavy use of pytest fixtures. Run in CI.
-- **E2E tests**: `tests/e2e/` -- real filesystem, real SQLite, real LLM calls, no mocks. Heavy use of pytest fixtures. **NOT run in CI** (eventual LLM calls make them non-free). Run locally by Claude after significant code changes.
-
-### E2E Test Policy
-
-E2E tests are your primary feedback mechanism. Run them liberally after significant changes -- they catch issues that integration tests miss because integration tests mock out SQLite and (eventually) LLM calls. But do NOT add them to CI workflows. They are a local development tool.
-
-See skillet or karat for examples of test organization, fixtures, and pytest-describe patterns.