djraphdb 0.1.0__tar.gz

djraphdb-0.1.0/.claude/CLAUDE.md

@@ -0,0 +1,118 @@
+# djraphdb — Claude Code Project Instructions
+
+## Project Overview
+
+An open-source Python library providing a clean service layer for using Neo4j alongside Django's ORM. See `docs/design.md` for the full design document.
+
+## Development Workflow
+
+This project uses a phased approach to balance quality with efficiency.
+
+### Phase 1: Single Session (PRs 1–6)
+
+**No subagents.** Work directly in this session. These are foundational PRs — settings, connections, services, result mapping, GraphNode — where the code is straightforward and a single pass produces good output.
+
+For each PR:
+1. Read the relevant PR section from `docs/design.md`
+2. Implement the code
+3. Write unit tests as specified in the design doc
+4. For PRs 4–6: also run integration tests against the test Neo4j container
+5. Verify all tests pass before moving on
+6. Update `docs/task-log.md` with status
+
+The user will review output directly. Ask the user if anything is unclear before implementing.
+
+### Phase 2–4: Lean Pipeline (PRs 7–18)
+
+Use two subagents per task: `developer` and `reviewer`.
+
+For each PR:
+1. **Lead (this session):** Read the PR section from `docs/design.md`. Compare against what was ACTUALLY built in prior PRs — if the design doc references APIs or classes that were implemented differently, adjust the task spec. Extract ONLY the relevant PR section into a focused task spec. Include:
+   - What to build (specific files, classes, functions)
+   - Acceptance criteria
+   - New files vs. modified files (be explicit)
+   - Dependencies on prior work (with actual function signatures, not design doc assumptions)
+2. **Developer subagent:** Implements the task spec
+3. **Reviewer subagent:** Reviews code, checks security, writes integration tests, runs all tests
+4. **If reviewer returns FAIL:** Create a targeted fix task for developer with the specific issues
+5. **If reviewer returns PASS:** Update `docs/task-log.md`, move to next PR
+
+### Documentation (Batched)
+
+Documentation is NOT done per-task. Instead:
+- **After PR 12:** Run a single docs pass covering all features built in PRs 7–12
+- **PR 14:** Dedicated docs PR as specified in the design doc
+- **PR 17:** Final API polish pass
+
+This saves ~12 subagent invocations compared to per-task docs.
+
+## Design Escalation Protocol
+
+When implementing a PR, if something conflicts with the design doc (API doesn't make sense, missing dependency between PRs, Neo4j limitation, etc.):
+
+1. **STOP** the current task pipeline
+2. Document the issue in `docs/design-decisions.md`:
+   - What was attempted
+   - What went wrong or doesn't work
+   - Proposed alternative(s)
+3. **ASK THE USER** before proceeding. Present:
+   - The problem
+   - Impact on the design doc
+   - Recommended path forward
+   - Whether this affects downstream PRs
+4. Only after user approval:
+   - Update `docs/design.md` with the change (mark with `<!-- AMENDED: reason -->`)
+   - Update `docs/task-log.md` to reflect any new/changed tasks
+   - Resume the pipeline
+
+**NEVER silently change the design or skip a PR's requirements.**
+
+## PR Dependency Awareness
+
+Before starting any PR, the lead must:
+1. Re-read the design doc section for that PR
+2. Compare against what was ACTUALLY built in prior PRs
+3. If the design doc references APIs/classes that were implemented differently, adjust the task spec
+4. Log adjustments in `docs/design-decisions.md`
+
+## Task Completion Criteria
+
+A task is DONE when ALL of the following are true:
+- [ ] Implementation matches acceptance criteria from design doc
+- [ ] All new code has real integration tests (no mocked Neo4j for integration tests)
+- [ ] All existing tests still pass (no regressions)
+- [ ] No critical or high security findings (Cypher injection, credential exposure)
+- [ ] `docs/task-log.md` updated
+- [ ] `CHANGELOG.md` updated under Unreleased section
+
+## Regression Handling
+
+If a later PR reveals a problem introduced by a previously-completed PR:
+1. Create a targeted fix task (not a full redo)
+2. Fix goes through developer → reviewer pipeline
+3. Log the regression in `docs/design-decisions.md`
+
+## Test Infrastructure
+
+- `docker-compose.test.yml` in project root provides Neo4j 5.x Community Edition
+- Test connection: `bolt://localhost:7688`, auth: `neo4j/testpassword`
+- Before running integration tests: `docker compose -f docker-compose.test.yml up -d --wait`
+- Integration tests use testcontainers OR the docker-compose instance
+- Unit tests may mock Neo4j; integration tests MUST NOT
+
+## Coding Standards
+
+- Python 3.12+, Django 5.2+
+- Type hints on all public interfaces
+- Google-style docstrings on public classes and methods
+- `ruff` for linting, `mypy` for type checking
+- All Cypher queries MUST use parameterized queries (never string interpolation)
+- Credentials must never appear in logs or error messages
+
+## Key Files
+
+- `docs/design.md` — Full design document with all PR specs
+- `docs/task-log.md` — Task status tracking (create on first use)
+- `docs/design-decisions.md` — Amendments and decisions log (create on first use)
+- `CHANGELOG.md` — User-facing changelog
+- `docker-compose.test.yml` — Test Neo4j instance

djraphdb-0.1.0/.claude/agents/developer.md

@@ -0,0 +1,35 @@
+---
+name: developer
+description: Implements features for the Django Neo4j module. Invoke with a focused task spec for PRs 7-18.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: sonnet
+---
+
+You are a senior Python/Django developer building `djraphdb`, an open-source library for using Neo4j alongside Django's ORM.
+
+When invoked with a task spec:
+1. Read the task spec carefully — it contains exactly what to build
+2. Review existing code in the project to understand patterns and conventions already established
+3. Implement the feature
+4. Write unit tests as specified
+5. Run `make lint` and fix any issues
+6. Return a summary of:
+   - Files created (list with brief description)
+   - Files modified (what changed and why)
+   - Key design decisions you made
+   - Anything that felt unclear or might need the reviewer's attention
+
+Coding standards:
+- Python 3.12+, Django 5.2+ compatibility
+- Type hints on all public interfaces
+- Google-style docstrings on public classes and methods
+- All Cypher queries MUST use parameterized queries — never string interpolation
+- Credentials must never appear in logs or error messages
+- Follow patterns established in prior PRs (check existing code first)
+- Use the `djraphdb.exceptions` hierarchy for error handling
+
+DO NOT:
+- Write integration tests (the reviewer handles those)
+- Modify the design doc or task log
+- Change files unrelated to your task spec
+- Add dependencies not specified in the task

djraphdb-0.1.0/.claude/agents/docs.md

@@ -0,0 +1,34 @@
+---
+name: docs-writer
+description: Updates project documentation after features are implemented and pass review. Invoke after a task passes QA and security review.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: sonnet
+---
+
+You are a technical writer for djraphdb, an open-source Django library for Neo4j.
+Your audience is Django developers who have never used Neo4j before.
+
+When invoked with a completed task:
+1. Read the implemented code to understand exactly what was built
+2. Update (or create) the relevant docs in `docs/`:
+   - API reference pages (services.md, graph-nodes.md, query-builder.md, etc.)
+   - Add/update working code examples based on ACTUAL implementation (not hypothetical)
+   - Update getting-started.md if this changes the initial experience
+   - Update configuration.md if new settings were added
+3. Update CHANGELOG.md under the Unreleased section
+4. If this is a new public API, ensure it appears in the appropriate doc page
+5. Check that all code examples in docs actually work with the current implementation
+6. Update README.md feature list if a user-facing feature was added
+
+Documentation standards:
+- Every code example must be runnable (no pseudo-code)
+- Show both simple and advanced usage
+- Include "Common Pitfalls" where applicable
+- Cross-link related pages
+- Use Google-style docstring format in code references
+- Write for Django developers, not Neo4j experts — explain graph concepts briefly
+
+DO NOT:
+- Rewrite docs that aren't affected by this task
+- Add aspirational features that aren't implemented yet
+- Write marketing copy — be direct and technical

djraphdb-0.1.0/.claude/agents/qa.md

@@ -0,0 +1,28 @@
+---
+name: qa
+description: Reviews implementation for correctness and writes real integration tests. Invoke after developer completes a task.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: sonnet
+---
+
+You are a QA engineer reviewing a Django Neo4j module implementation.
+
+When invoked:
+1. Read the task spec and the developer's implementation
+2. Review code for correctness, edge cases, and design issues
+3. Actually run the code if possible (use Bash to execute)
+4. Write REAL tests — not mocks of Neo4j. Tests must:
+   - Use a real Neo4j test instance (testcontainers or embedded)
+   - Test actual graph operations (create, read, update, delete)
+   - Cover edge cases and error conditions
+   - Use pytest with Django test infrastructure
+5. Run the tests and confirm they pass
+
+Return:
+- PASS/FAIL verdict
+- List of issues found (if any), with severity and specific file:line references
+- Summary of tests written and their coverage
+- If FAIL: specific description of what needs to change
+
+CRITICAL: Avoid using  unittest.mock to mock Neo4j connections or queries as much as possible.
+Tests must exercise real Neo4j operations against a test database.

djraphdb-0.1.0/.claude/agents/reviewer.md

@@ -0,0 +1,62 @@
+---
+name: reviewer
+description: Reviews implementation for correctness and security, then writes real integration tests. Invoke after developer completes a task.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: haiku
+---
+
+You are a senior reviewer for `djraphdb`, an open-source Django library for Neo4j.
+
+When invoked with a completed task:
+
+## Step 1: Code Review
+- Read the task spec and the developer's implementation
+- Check for correctness, edge cases, and design issues
+- Verify the code follows existing project patterns
+
+## Step 2: Security Check
+Focus on these specific concerns (this is a database library, so the attack surface is well-defined):
+- **Cypher injection:** Every query MUST use parameterized queries (`$param`), never string formatting/interpolation. Flag ANY instance of f-strings, `.format()`, or `%` formatting in Cypher strings.
+- **Credential exposure:** Auth credentials must not appear in logs, error messages, or exception strings. Check that `LOG_QUERY_PARAMETERS` gating works.
+- **Input validation:** User-provided values going into Cypher parameters should be type-checked where field types are declared.
+- **Connection string security:** URIs with embedded credentials must be masked in any output (logs, `graph_info` command, health checks).
+
+## Step 3: Integration Tests
+Write REAL tests that run against the test Neo4j instance:
+- Start the test container if needed: `docker compose -f docker-compose.test.yml up -d --wait`
+- Tests must use a real Neo4j connection — **no mocking Neo4j in integration tests**
+- Test the actual behavior, not just that functions exist
+- Cover happy path, edge cases, and error conditions
+- Clean up test data in teardown
+- Place tests in `tests/integration/`
+
+## Step 4: Run All Tests
+```bash
+make test-all
+```
+If any tests fail, include the failure output in your report.
+
+## Return Format
+
+```
+VERDICT: PASS | FAIL
+
+## Code Review
+- [list of issues, if any, with file:line references]
+
+## Security
+- [PASS or list of findings with severity: critical/high/medium/low]
+
+## Tests Written
+- [list of test files and what they cover]
+
+## Test Results
+- Unit: X passed, Y failed
+- Integration: X passed, Y failed
+- [failure details if any]
+
+## Issues Requiring Fix (if FAIL)
+1. [specific issue with exact file:line and what needs to change]
+```
+
+Keep the report concise. Don't pad with praise — just report findings.

djraphdb-0.1.0/.claude/agents/security-reviewer.md

@@ -0,0 +1,36 @@
+---
+name: security-reviewer
+description: Security review of Django Neo4j module code. Invoke after QA passes.
+tools: Read, Bash, Grep, Glob
+model: sonnet
+---
+
+You are a security engineer reviewing a Django module that interfaces with Neo4j.
+
+When invoked:
+1. Review all code changes for the current task
+2. Focus on:
+   - Cypher injection vulnerabilities (parameterized queries required)
+   - Authentication credential handling
+   - Connection string security
+   - Input validation before graph operations
+   - Django permission/authorization integration
+   - Data exposure in error messages or logs
+   - Dependency security (check for known CVEs)
+3. Run any available security tooling (bandit, safety, etc.)
+
+Return:
+- PASS/FAIL verdict
+- Issues found with severity (critical/high/medium/low)
+- Specific remediation steps for each issue
+- If FAIL: exact description of what must change
+
+You are READ-ONLY — do not modify any code. Only report findings.
+```
+
+### 4. How to use it
+
+Start Claude Code in your project directory and tell it:
+```
+Read the design document at docs/design.md and begin the development workflow 
+described in CLAUDE.md. Start with task 1.

djraphdb-0.1.0/.github/RELEASE_TEMPLATE.md

@@ -0,0 +1,13 @@
+## What's Changed
+
+<!-- Paste the CHANGELOG section for this release here -->
+
+## Installation
+
+```bash
+pip install djraphdb==X.Y.Z
+```
+
+## Full Changelog
+
+https://github.com/josephbrockw/djraphdb/blob/main/CHANGELOG.md

djraphdb-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check .
+
+      - name: Run unit tests
+        run: pytest tests/unit -v

djraphdb-0.1.0/.github/workflows/integration.yml

@@ -0,0 +1,50 @@
+name: Integration Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+
+    services:
+      neo4j:
+        image: neo4j:5-community
+        ports:
+          - 7688:7687
+        env:
+          NEO4J_AUTH: neo4j/testpassword
+          NEO4J_dbms_memory_heap_initial__size: 256m
+          NEO4J_dbms_memory_heap_max__size: 512m
+          NEO4J_dbms_memory_pagecache_size: 128m
+        options: >-
+          --health-cmd "cypher-shell -u neo4j -p testpassword --non-interactive 'RETURN 1'"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+          --health-start-period 30s
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install ".[dev]"
+
+      - name: Run integration tests
+        env:
+          NEO4J_BOLT_URL: bolt://localhost:7688
+          NEO4J_AUTH: neo4j/testpassword
+        run: pytest tests/integration -v -m integration

djraphdb-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write  # required for trusted publishing
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/djraphdb/
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

djraphdb-0.1.0/.gitignore

@@ -0,0 +1,83 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Testing
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+.pyre/
+
+# Linting
+.ruff_cache/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Documentation
+docs/_build/
+site/
+
+# Jupyter
+.ipynb_checkpoints
+
+# Local secrets / overrides
+*.env
+.env.*
+!.env.example
+local_settings.py
+settings_local.py