dirsql 0.0.1

package/.claude/CLAUDE.md

@@ -0,0 +1,120 @@
+# dirsql Development
+
+## 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`
+
+### 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. Creates a worktree and branch for its bead
+2. Does the implementation work (red/green TDD)
+3. Pushes the branch and opens a PR
+4. Monitors the PR and proactively resolves:
+   - CI failures
+   - GPG signing complaints
+   - Merge conflicts
+5. 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. **Set up cron polling** (via CronCreate, every minute) when waiting for a PR to be merged. The cron prompt should handle the full post-merge cycle: pull, cleanup, monitor release, delete the cron job.
+
+### 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.

package/.github/workflows/minor-release.yml

@@ -0,0 +1,14 @@
+name: Minor Release
+
+on:
+  workflow_dispatch:
+
+jobs:
+  release:
+    uses: ./.github/workflows/publish.yml
+    with:
+      bump_type: minor
+    secrets: inherit
+    permissions:
+      contents: write
+      id-token: write

package/.github/workflows/patch-release.yml

@@ -0,0 +1,45 @@
+name: Patch Release
+
+on:
+  schedule:
+    # Run at 2:00 AM UTC every day
+    - cron: '0 2 * * *'
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    outputs:
+      should_release: ${{ steps.decide.outputs.should_release }}
+    steps:
+      - id: decide
+        env:
+          EVENT: ${{ github.event_name }}
+          STRATEGY: ${{ vars.RELEASE_STRATEGY }}
+          COMMIT_MSG: ${{ github.event.head_commit.message }}
+        run: |
+          if [ "$EVENT" = "workflow_dispatch" ]; then
+            echo "should_release=true" >> "$GITHUB_OUTPUT"
+          elif [ "$EVENT" = "schedule" ] && [ "$STRATEGY" != "immediate" ]; then
+            echo "should_release=true" >> "$GITHUB_OUTPUT"
+          elif [ "$EVENT" = "push" ] && [ "$STRATEGY" = "immediate" ]; then
+            case "$COMMIT_MSG" in
+              *'[no-release]'*) echo "should_release=false" >> "$GITHUB_OUTPUT" ;;
+              *) echo "should_release=true" >> "$GITHUB_OUTPUT" ;;
+            esac
+          else
+            echo "should_release=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  release:
+    needs: check
+    if: needs.check.outputs.should_release == 'true'
+    uses: ./.github/workflows/publish.yml
+    with:
+      bump_type: patch
+    secrets: inherit
+    permissions:
+      contents: write
+      id-token: write

package/.github/workflows/pr-monitor.yml

@@ -0,0 +1,16 @@
+name: PR Monitor
+
+on:
+  pull_request:
+
+permissions:
+  checks: read
+
+jobs:
+  monitor:
+    name: 'CI Gate'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: clankerbot/pr-monitor@v1
+        with:
+          job-name: 'CI Gate'

package/.github/workflows/publish.yml

@@ -0,0 +1,306 @@
+name: Publish Release
+
+on:
+  workflow_call:
+    inputs:
+      bump_type:
+        description: 'Version bump type: patch or minor'
+        required: true
+        type: string
+
+jobs:
+  check-python:
+    runs-on: ubuntu-latest
+    outputs:
+      has_python: ${{ steps.check.outputs.has_python }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Check for pyproject.toml
+        id: check
+        run: |
+          if [ -f pyproject.toml ]; then
+            echo "has_python=true" >> $GITHUB_OUTPUT
+          else
+            echo "has_python=false" >> $GITHUB_OUTPUT
+          fi
+
+  build:
+    needs: check-python
+    if: needs.check-python.outputs.has_python == 'true'
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - os: ubuntu-latest
+            target: aarch64-unknown-linux-gnu
+          - os: macos-latest
+            target: x86_64-apple-darwin
+          - os: macos-latest
+            target: aarch64-apple-darwin
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up QEMU
+        if: runner.os == 'Linux' && matrix.target == 'aarch64-unknown-linux-gnu'
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: arm64
+
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          manylinux: auto
+          before-script-linux: |
+            # Install OpenSSL dev for cross-compilation
+            if [ "${{ matrix.target }}" = "aarch64-unknown-linux-gnu" ]; then
+              apt-get update && apt-get install -y gcc-aarch64-linux-gnu
+            fi
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.target }}
+          path: dist
+
+  sdist:
+    needs: check-python
+    if: needs.check-python.outputs.has_python == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+  tag:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      created: ${{ steps.tag.outputs.created }}
+      new_version: ${{ steps.version.outputs.new_version }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Get current version
+        id: current
+        run: |
+          latest_tag=$(git tag --sort=-v:refname | grep -E '^v[0-9]' | head -n1)
+
+          if [ -z "$latest_tag" ]; then
+            echo "No tags found"
+            echo "version=0.0.0" >> $GITHUB_OUTPUT
+            echo "has_tags=false" >> $GITHUB_OUTPUT
+          else
+            echo "Latest tag: $latest_tag"
+            echo "version=${latest_tag#v}" >> $GITHUB_OUTPUT
+            echo "has_tags=true" >> $GITHUB_OUTPUT
+
+            commits_since_tag=$(git rev-list ${latest_tag}..HEAD --count)
+            echo "commits_since_tag=$commits_since_tag" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Check for changes (patch only)
+        if: inputs.bump_type == 'patch' && steps.current.outputs.has_tags == 'true'
+        id: check_changes
+        run: |
+          if [ "${{ steps.current.outputs.commits_since_tag }}" -eq 0 ]; then
+            echo "No new commits since last tag, skipping release"
+            echo "should_release=false" >> $GITHUB_OUTPUT
+          else
+            echo "Found ${{ steps.current.outputs.commits_since_tag }} commits since last tag"
+            echo "should_release=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Calculate new version
+        id: version
+        run: |
+          current="${{ steps.current.outputs.version }}"
+          IFS='.' read -r major minor patch <<< "$current"
+
+          if [ "${{ inputs.bump_type }}" == "minor" ]; then
+            new_version="${major}.$((minor + 1)).0"
+          else
+            new_version="${major}.${minor}.$((patch + 1))"
+          fi
+
+          echo "new_version=$new_version" >> $GITHUB_OUTPUT
+          echo "New version will be: $new_version"
+
+      - name: Check if tag exists
+        id: tag_check
+        run: |
+          if git ls-remote --tags origin | grep -q "refs/tags/v${{ steps.version.outputs.new_version }}$"; then
+            echo "Tag v${{ steps.version.outputs.new_version }} already exists on remote"
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Determine if release should proceed
+        id: should_release
+        run: |
+          if [ "${{ steps.tag_check.outputs.exists }}" == "true" ]; then
+            echo "proceed=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          if [ "${{ inputs.bump_type }}" == "patch" ] && [ "${{ steps.current.outputs.has_tags }}" == "true" ]; then
+            if [ "${{ steps.check_changes.outputs.should_release }}" == "false" ]; then
+              echo "proceed=false" >> $GITHUB_OUTPUT
+              exit 0
+            fi
+          fi
+
+          echo "proceed=true" >> $GITHUB_OUTPUT
+
+      - name: Create and push tag
+        if: steps.should_release.outputs.proceed == 'true'
+        id: tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "v${{ steps.version.outputs.new_version }}" -m "Release v${{ steps.version.outputs.new_version }}"
+          git push origin "v${{ steps.version.outputs.new_version }}"
+          echo "created=true" >> $GITHUB_OUTPUT
+
+  publish-pypi:
+    needs: [tag, build, sdist]
+    if: always() && needs.tag.outputs.created == 'true' && needs.sdist.result == 'success'
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment: release
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          merge-multiple: true
+          path: dist
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-crates:
+    needs: tag
+    if: needs.tag.outputs.created == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Update Cargo.toml version
+        run: |
+          sed -i 's/^version = ".*"/version = "${{ needs.tag.outputs.new_version }}"/' Cargo.toml
+
+      - name: Publish to crates.io
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: |
+          for attempt in 1 2 3; do
+            echo "Attempt $attempt of 3"
+            if cargo publish --allow-dirty; then
+              echo "Published successfully"
+              break
+            fi
+            if [ "$attempt" -lt 3 ]; then
+              echo "Publish failed, retrying in 15s..."
+              sleep 15
+            else
+              echo "All attempts failed"
+              exit 1
+            fi
+          done
+
+  publish-npm:
+    needs: tag
+    if: needs.tag.outputs.created == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Check if package.json exists
+        id: check
+        run: |
+          if [ -f package.json ]; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Setup Node.js
+        if: steps.check.outputs.exists == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: https://registry.npmjs.org
+
+      - name: Publish to npm
+        if: steps.check.outputs.exists == 'true'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --provenance --access public
+
+  github-release:
+    needs: [tag, publish-crates]
+    if: always() && needs.tag.outputs.created == 'true' && (needs.publish-crates.result == 'success' || needs.publish-crates.result == 'skipped')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "v${{ needs.tag.outputs.new_version }}" \
+            --repo ${{ github.repository }} \
+            --title "v${{ needs.tag.outputs.new_version }}" \
+            --generate-notes
+
+  rollback:
+    needs: [tag, publish-pypi, publish-crates, publish-npm, github-release]
+    if: failure() && needs.tag.outputs.created == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Rollback tag on failure
+        run: git push --delete origin "v${{ needs.tag.outputs.new_version }}"

package/.github/workflows/python-lint.yml

@@ -0,0 +1,35 @@
+name: Python Lint
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '**.py'
+      - 'pyproject.toml'
+      - 'uv.lock'
+  pull_request:
+    paths:
+      - '**.py'
+      - 'pyproject.toml'
+      - 'uv.lock'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install just
+        uses: extractions/setup-just@v2
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run just lint
+
+      - name: Format check
+        run: uv run just format-check

package/.github/workflows/python-test.yml

@@ -0,0 +1,45 @@
+name: Python Test
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '**.py'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'tests/**'
+  pull_request:
+    paths:
+      - '**.py'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'tests/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install just
+        uses: extractions/setup-just@v2
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Build Rust extension
+        run: uv run maturin develop
+
+      - name: Run tests
+        run: uv run just test-ci

package/.github/workflows/rust-test.yml

@@ -0,0 +1,41 @@
+name: Rust Test
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '**.rs'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+  pull_request:
+    paths:
+      - '**.rs'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('Cargo.lock') }}
+
+      - name: Run tests
+        run: cargo test
+
+      - name: Clippy
+        run: cargo clippy -- -D warnings
+
+      - name: Format check
+        run: cargo fmt -- --check