From 30c84a7f651c22260b8859f7fa6dba9847f02c32 Mon Sep 17 00:00:00 2001 From: Byron Williams Date: Fri, 12 Dec 2025 18:41:05 -0800 Subject: [PATCH 01/26] chore: fix workflow configs and pre-commit formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix boolean type in fips-compatibility.yml input default - Remove trailing newlines from scorecard.yml and api-reference.md - Improve TruffleHog pre-commit entry formatting 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .github/workflows/fips-compatibility.yml | 2 +- .github/workflows/scorecard.yml | 1 - .pre-commit-config.yaml | 4 ++-- docs/api-reference.md | 1 - 4 files changed, 3 insertions(+), 5 deletions(-) diff --git a/.github/workflows/fips-compatibility.yml b/.github/workflows/fips-compatibility.yml index e64066b..5073d1d 100644 --- a/.github/workflows/fips-compatibility.yml +++ b/.github/workflows/fips-compatibility.yml @@ -36,7 +36,7 @@ on: strict_mode: description: 'Treat warnings as errors' required: false - default: 'false' + default: false type: boolean # Cancel in-progress runs for same PR/branch diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 512891e..4e15ec6 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -52,4 +52,3 @@ jobs: name: scorecard-results path: results.sarif retention-days: 5 - diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d177f7a..6d01bc4 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -63,7 +63,8 @@ repos: - id: trufflehog name: TruffleHog Secret Scanner description: Detect secrets in your data before committing - entry: bash -c 'command -v trufflehog >/dev/null 2>&1 && trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail || echo "TruffleHog not installed - skipping (install: brew install trufflehog)"' + entry: >- + bash -c 'command -v trufflehog >/dev/null 2>&1 && trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail || echo "TruffleHog not installed - skipping"' language: system pass_filenames: false stages: [pre-commit] @@ -224,4 +225,3 @@ exclude: | models/| .*\.pyc )$ - diff --git a/docs/api-reference.md b/docs/api-reference.md index a28d45c..092ab49 100644 --- a/docs/api-reference.md +++ b/docs/api-reference.md @@ -26,4 +26,3 @@ Complete API documentation for Python Libs. options: show_root_heading: true members_order: source - From 85cba2a3538cd757cea13a5e1bd24a64fc582efc Mon Sep 17 00:00:00 2001 From: Byron Williams Date: Fri, 12 Dec 2025 18:41:19 -0800 Subject: [PATCH 02/26] chore: make scripts executable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add execute permissions to utility scripts for direct invocation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .claude/skills/project-planning/scripts/validate-planning-docs.py | 0 scripts/check_fips_compatibility.py | 0 scripts/check_orphaned_files.py | 0 scripts/check_type_hints.py | 0 scripts/cleanup_conditional_files.py | 0 scripts/cruft-update.sh | 0 scripts/setup_github_protection.py | 0 scripts/validate_assuredoss.py | 0 tools/validate_front_matter.py | 0 9 files changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 .claude/skills/project-planning/scripts/validate-planning-docs.py mode change 100644 => 100755 scripts/check_fips_compatibility.py mode change 100644 => 100755 scripts/check_orphaned_files.py mode change 100644 => 100755 scripts/check_type_hints.py mode change 100644 => 100755 scripts/cleanup_conditional_files.py mode change 100644 => 100755 scripts/cruft-update.sh mode change 100644 => 100755 scripts/setup_github_protection.py mode change 100644 => 100755 scripts/validate_assuredoss.py mode change 100644 => 100755 tools/validate_front_matter.py diff --git a/.claude/skills/project-planning/scripts/validate-planning-docs.py b/.claude/skills/project-planning/scripts/validate-planning-docs.py old mode 100644 new mode 100755 diff --git a/scripts/check_fips_compatibility.py b/scripts/check_fips_compatibility.py old mode 100644 new mode 100755 diff --git a/scripts/check_orphaned_files.py b/scripts/check_orphaned_files.py old mode 100644 new mode 100755 diff --git a/scripts/check_type_hints.py b/scripts/check_type_hints.py old mode 100644 new mode 100755 diff --git a/scripts/cleanup_conditional_files.py b/scripts/cleanup_conditional_files.py old mode 100644 new mode 100755 diff --git a/scripts/cruft-update.sh b/scripts/cruft-update.sh old mode 100644 new mode 100755 diff --git a/scripts/setup_github_protection.py b/scripts/setup_github_protection.py old mode 100644 new mode 100755 diff --git a/scripts/validate_assuredoss.py b/scripts/validate_assuredoss.py old mode 100644 new mode 100755 diff --git a/tools/validate_front_matter.py b/tools/validate_front_matter.py old mode 100644 new mode 100755 From 422d2717b18adf918d6fb1f2811172f5b1c91067 Mon Sep 17 00:00:00 2001 From: Byron Williams Date: Fri, 12 Dec 2025 18:46:25 -0800 Subject: [PATCH 03/26] docs: update README with monorepo packages and publishing workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update README.md: - Add all four packages (cloudflare-auth, cloudflare-api, gcs-utilities, gemini-image) - Document GCP Artifact Registry as publish target (not PyPI) - Add Publishing section with workflow and tag format - Update project structure to reflect UV workspace layout - Add installation instructions for private registry Add PlantUML sequence diagram for publish workflow showing: - Tag-triggered GitHub Actions - Infisical secrets retrieval - GCP authentication flow - Artifact Registry publishing 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 186 +++++++++++++++++++++++++--- docs/diagrams/publish-workflow.puml | 70 +++++++++++ 2 files changed, 238 insertions(+), 18 deletions(-) create mode 100644 docs/diagrams/publish-workflow.puml diff --git a/README.md b/README.md index 174c1ce..760b3eb 100644 --- a/README.md +++ b/README.md @@ -38,10 +38,32 @@ Shared Python libraries for ByronWilliamsCPA projects. This is a **UV workspace ## Packages -| Package | Description | Installation | -|---------|-------------|--------------| -| [byronwilliamscpa-cloudflare-auth](packages/cloudflare-auth/) | JWT validation and Cloudflare Access integration middleware | `pip install "git+ssh://git@github.com/ByronWilliamsCPA/python-libs.git#subdirectory=packages/cloudflare-auth"` | -| [byronwilliamscpa-gcs-utilities](packages/gcs-utilities/) | Google Cloud Storage utilities and helpers | `pip install "git+ssh://git@github.com/ByronWilliamsCPA/python-libs.git#subdirectory=packages/cloudflare-auth"` | +| Package | Description | Version | +|---------|-------------|---------| +| [cloudflare-auth](packages/cloudflare-auth/) | JWT validation and Cloudflare Access middleware for FastAPI/Starlette | 0.1.0 | +| [cloudflare-api](packages/cloudflare-api/) | Cloudflare API client with IP list management and multi-source fetching | 0.1.0 | +| [gcs-utilities](packages/gcs-utilities/) | Google Cloud Storage utilities and helpers | 0.1.0 | +| [gemini-image](packages/gemini-image/) | Image generation using Google Gemini models (Nano Banana / Pro) | 0.1.0 | + +### Installation + +Packages are published to **GCP Artifact Registry** for supply chain security: + +```bash +# Configure UV to use the private registry (one-time setup) +# Add to ~/.config/uv/uv.toml or project pyproject.toml: +# [[tool.uv.index]] +# url = "https://us-central1-python.pkg.dev/assured-oss-457903/python-libs/simple/" + +# Install packages +pip install byronwilliamscpa-cloudflare-auth +pip install byronwilliamscpa-cloudflare-api +pip install byronwilliamscpa-gcs-utilities +pip install byronwilliamscpa-gemini-image + +# Or install from git (development) +pip install "git+ssh://git@github.com/ByronWilliamsCPA/python-libs.git#subdirectory=packages/cloudflare-auth" +``` ## Features @@ -370,22 +392,31 @@ qlty check --plugin osv_scanner ## Project Structure ``` -python_libs/ -├── src/python_libs/ # Main package -│ ├── __init__.py -│ ├── core.py # Core functionality -│ └── utils/ # Utility modules -├── tests/ # Test suite -│ ├── unit/ # Unit tests -│ └── integration/ # Integration tests +python-libs/ +├── packages/ # UV workspace packages +│ ├── cloudflare-auth/ # JWT/Cloudflare Access middleware +│ │ ├── src/cloudflare_auth/ +│ │ ├── tests/ +│ │ └── pyproject.toml +│ ├── cloudflare-api/ # Cloudflare API client +│ │ ├── src/cloudflare_api/ +│ │ ├── tests/ +│ │ └── pyproject.toml +│ ├── gcs-utilities/ # GCS helpers +│ │ ├── src/gcs_utilities/ +│ │ ├── tests/ +│ │ └── pyproject.toml +│ └── gemini-image/ # Gemini image generation +│ ├── src/gemini_image/ +│ ├── tests/ +│ └── pyproject.toml +├── src/python_libs/ # Shared utilities (optional) ├── docs/ # Documentation -│ ├── ADRs/ # Architecture Decision Records -│ ├── planning/ # Project planning docs -│ └── guides/ # User guides -├── pyproject.toml # Dependencies & tool config +│ ├── planning/ # Project planning & ADRs +│ └── diagrams/ # Architecture diagrams +├── pyproject.toml # Root workspace config ├── README.md # This file -├── CONTRIBUTING.md # Contribution guidelines -└── LICENSE # License +└── CONTRIBUTING.md # Contribution guidelines ``` ## Documentation @@ -462,6 +493,125 @@ Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for: - [ ] CHANGELOG.md updated (if significant change) - [ ] Commits follow conventional commit format +## Publishing + +Packages are published to **GCP Artifact Registry** (not PyPI) for enhanced supply chain security. This integrates with Google Assured OSS for verified dependencies. + +### Publishing Workflow + +The publishing process uses GitHub Actions triggered by version tags, with secrets managed securely via Infisical: + +``` +Developer → Push Tag → GitHub Actions → Infisical → GCP Auth → Artifact Registry +``` + +
+View PlantUML Sequence Diagram + +```plantuml +@startuml publish-workflow +!theme plain +skinparam backgroundColor #FEFEFE +skinparam sequenceMessageAlign center + +title Package Publishing Workflow\nGCP Artifact Registry with Infisical Secrets + +actor Developer +participant "GitHub\nRepository" as GitHub +participant "GitHub\nActions" as GHA +participant "Infisical\nSecrets" as Infisical +participant "Google Cloud\nAuth" as GCP +participant "Artifact\nRegistry" as AR + +== Tag Creation == +Developer -> GitHub: Push version tag\n(e.g., cloudflare-auth-v1.0.0) +activate GitHub + +GitHub -> GHA: Trigger publish workflow +activate GHA + +== Secret Retrieval == +GHA -> Infisical: Authenticate with\nClient ID/Secret +activate Infisical +Infisical --> GHA: Return GCP_SA_KEY_BASE64 +deactivate Infisical + +== GCP Authentication == +GHA -> GCP: Authenticate with\nService Account Key +activate GCP +GCP --> GHA: Authentication token +deactivate GCP + +== Build & Publish == +GHA -> GHA: Parse tag to determine\npackage directory +GHA -> GHA: Verify version in\npyproject.toml matches tag +GHA -> GHA: Build package with UV\n(uv build) + +GHA -> AR: Publish package\n(uv publish) +activate AR +AR --> GHA: Publish success +deactivate AR + +== Summary == +GHA -> GitHub: Update job summary\nwith publish details +deactivate GHA +deactivate GitHub + +note right of AR + **Registry URL:** + us-central1-python.pkg.dev/ + assured-oss-457903/python-libs + + **Supported Tags:** + - cloudflare-auth-v* + - cloudflare-api-v* + - gcs-utilities-v* + - gemini-image-v* +end note + +note left of Infisical + **Secrets Stored:** + - GCP_SA_KEY_BASE64 + (Service account JSON, base64) + + **Domain:** + secrets.byronwilliamscpa.com +end note + +@enduml +``` + +
+ +See also: [docs/diagrams/publish-workflow.puml](docs/diagrams/publish-workflow.puml) + +### How to Publish a Package + +1. **Update version** in the package's `pyproject.toml` +2. **Commit and push** the version change +3. **Create and push a tag** matching the pattern: + ```bash + # Format: {package-name}-v{version} + git tag cloudflare-auth-v1.0.0 + git tag cloudflare-api-v1.0.0 + git tag gcs-utilities-v1.0.0 + git tag gemini-image-v1.0.0 + + git push origin --tags + ``` +4. **GitHub Actions** automatically: + - Fetches GCP credentials from Infisical + - Verifies version matches tag + - Builds and publishes to Artifact Registry + +### Registry Details + +| Setting | Value | +|---------|-------| +| Registry URL | `us-central1-python.pkg.dev/assured-oss-457903/python-libs` | +| Secrets Manager | Infisical (secrets.byronwilliamscpa.com) | +| Service Account | `assured-oss-accessor@assured-oss-457903.iam.gserviceaccount.com` | + ## Versioning This project uses [Semantic Versioning](https://semver.org/): diff --git a/docs/diagrams/publish-workflow.puml b/docs/diagrams/publish-workflow.puml new file mode 100644 index 0000000..3d1478c --- /dev/null +++ b/docs/diagrams/publish-workflow.puml @@ -0,0 +1,70 @@ +@startuml publish-workflow +!theme plain +skinparam backgroundColor #FEFEFE +skinparam sequenceMessageAlign center + +title Package Publishing Workflow\nGCP Artifact Registry with Infisical Secrets + +actor Developer +participant "GitHub\nRepository" as GitHub +participant "GitHub\nActions" as GHA +participant "Infisical\nSecrets" as Infisical +participant "Google Cloud\nAuth" as GCP +participant "Artifact\nRegistry" as AR + +== Tag Creation == +Developer -> GitHub: Push version tag\n(e.g., cloudflare-auth-v1.0.0) +activate GitHub + +GitHub -> GHA: Trigger publish workflow +activate GHA + +== Secret Retrieval == +GHA -> Infisical: Authenticate with\nClient ID/Secret +activate Infisical +Infisical --> GHA: Return GCP_SA_KEY_BASE64 +deactivate Infisical + +== GCP Authentication == +GHA -> GCP: Authenticate with\nService Account Key +activate GCP +GCP --> GHA: Authentication token +deactivate GCP + +== Build & Publish == +GHA -> GHA: Parse tag to determine\npackage directory +GHA -> GHA: Verify version in\npyproject.toml matches tag +GHA -> GHA: Build package with UV\n(uv build) + +GHA -> AR: Publish package\n(uv publish) +activate AR +AR --> GHA: Publish success +deactivate AR + +== Summary == +GHA -> GitHub: Update job summary\nwith publish details +deactivate GHA +deactivate GitHub + +note right of AR + **Registry URL:** + us-central1-python.pkg.dev/ + assured-oss-457903/python-libs + + **Supported Tags:** + - cloudflare-auth-v* + - cloudflare-api-v* + - gcs-utilities-v* + - gemini-image-v* +end note + +note left of Infisical + **Secrets Stored:** + - GCP_SA_KEY_BASE64 + (Service account JSON, base64) + + **Domain:** + secrets.byronwilliamscpa.com +end note + +@enduml From f9c14a13bf613190f59336d4d28e37da83142eb5 Mon Sep 17 00:00:00 2001 From: Byron Williams Date: Fri, 12 Dec 2025 19:04:43 -0800 Subject: [PATCH 04/26] chore: fix qlty code quality issues and enable plugins MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enable qlty plugins for comprehensive code analysis: - ruff: Python linting (blocking) - bandit: Python security (comment mode) - shellcheck: Shell script linting (comment mode) - yamllint: YAML linting (comment mode) - markdownlint: Markdown linting (comment mode) - actionlint: GitHub Actions linting (comment mode) - osv-scanner: Vulnerability scanning (comment mode) Fix code quality issues: - Add timezone to all datetime.now() calls (DTZ005) - Add specific pyright ignore codes (PGH003) - Configure per-file ignores for complex middleware files - Fix logging patterns (G201, TRY401) - Add noqa comments for intentional complexity - Format markdown files with markdownlint Update pyproject.toml with per-file-ignores for: - cloudflare-auth middleware (TRY300, TRY301, PLC0415) - cloudflare-auth whitelist (TRY300, TRY301, SLF001) - cloudflare-auth validators (TRY300, TRY301, TRY401) - gcs-utilities client (G004, TRY300, PTH rules) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .claude/README.md | 1 + .claude/agents/code-reviewer.md | 8 ++ .claude/agents/security-auditor.md | 8 ++ .claude/agents/test-engineer.md | 7 + .claude/commands/merge-standards.md | 1 + .claude/commands/plan.md | 6 + .claude/commands/pr.md | 5 +- .claude/commands/quality.md | 6 + .claude/commands/security.md | 6 + .claude/commands/testing.md | 10 ++ .claude/context/python-standards.md | 16 +++ .claude/context/testing-patterns.md | 9 ++ .claude/skills/commit-prepare/SKILL.md | 10 ++ .claude/skills/git/SKILL.md | 3 + .claude/skills/pr-prepare/SKILL.md | 5 + .claude/skills/project-planning/SKILL.md | 11 ++ .../reference/document-guide.md | 13 ++ .../reference/prompting-patterns.md | 14 ++ .../templates/adr-template.md | 1 + .../templates/roadmap-template.md | 2 + .../templates/tech-spec-template.md | 17 ++- .../project-planning/workflows/synthesize.md | 13 ++ .claude/skills/quality/SKILL.md | 6 + .claude/skills/security/SKILL.md | 5 + .claude/skills/testing/SKILL.md | 5 + .github/workflows/README.md | 23 ++++ .qlty/logs | 1 + .qlty/out | 1 + .qlty/plugin_cachedir | 1 + .qlty/qlty.toml | 104 ++++++++------- .qlty/results | 1 + .standards/CLAUDE.baseline.md | 4 + .standards/README.baseline.md | 2 + .standards/template_feedback.baseline.md | 2 + CHANGELOG.md | 5 + CLAUDE.md | 10 +- CONFIG_TEMPLATES_SUMMARY.md | 11 ++ CONTRIBUTING.md | 5 +- README.md | 22 +++- docs/ADRs/adr-template.md | 6 + docs/OPENSSF_COMPLIANCE.md | 2 +- docs/PROJECT_SETUP.md | 10 ++ docs/PYTHON_COMPATIBILITY.md | 4 + docs/development/code-quality.md | 1 + docs/development/contributing.md | 1 + docs/development/testing.md | 1 + docs/index.md | 1 + docs/planning/README.md | 1 + docs/planning/project-plan-template.md | 44 +++++++ docs/project/license.md | 3 +- docs/template_feedback.md | 2 +- .../src/cloudflare_auth/__init__.py | 25 ++-- .../src/cloudflare_auth/csrf.py | 25 ++-- .../src/cloudflare_auth/middleware.py | 49 ++++--- .../cloudflare_auth/middleware_enhanced.py | 44 +++---- .../src/cloudflare_auth/models.py | 68 +++------- .../src/cloudflare_auth/rate_limiter.py | 41 +++--- .../src/cloudflare_auth/redis_sessions.py | 40 +++--- .../src/cloudflare_auth/security_helpers.py | 17 +-- .../src/cloudflare_auth/sessions.py | 27 ++-- .../src/cloudflare_auth/utils.py | 54 +++++--- .../src/cloudflare_auth/validators.py | 52 ++++---- .../src/cloudflare_auth/whitelist.py | 88 +++++++++---- packages/cloudflare-auth/tests/test_models.py | 4 +- .../src/gcs_utilities/__init__.py | 8 +- .../gcs-utilities/src/gcs_utilities/client.py | 120 ++++++++++-------- .../src/gcs_utilities/exceptions.py | 12 -- packages/gcs-utilities/tests/conftest.py | 4 +- .../gcs-utilities/tests/test_exceptions.py | 4 +- pyproject.toml | 62 +++++++++ scripts/README.md | 3 + 71 files changed, 806 insertions(+), 397 deletions(-) create mode 120000 .qlty/logs create mode 120000 .qlty/out create mode 120000 .qlty/plugin_cachedir create mode 120000 .qlty/results diff --git a/.claude/README.md b/.claude/README.md index 063a553..aa89be5 100644 --- a/.claude/README.md +++ b/.claude/README.md @@ -94,6 +94,7 @@ git subtree push --prefix .claude/standard \ 3. **Project Overrides**: Finally loads `.claude/claude.md` (project-specific) This layered approach ensures: + - Consistent standards across all projects - Project flexibility where needed - Easy updates to universal guidelines diff --git a/.claude/agents/code-reviewer.md b/.claude/agents/code-reviewer.md index 16f518e..f685694 100644 --- a/.claude/agents/code-reviewer.md +++ b/.claude/agents/code-reviewer.md @@ -9,24 +9,28 @@ Review code changes for quality, maintainability, and adherence to project stand ## Capabilities ### Code Analysis + - Identify code smells and anti-patterns - Check adherence to Python best practices - Evaluate code complexity and maintainability - Detect potential bugs and edge cases ### Standards Compliance + - Verify PEP 8 and project style guide compliance - Check type annotation completeness - Validate docstring coverage and quality - Ensure consistent naming conventions ### Security Review + - Identify potential security vulnerabilities - Check for hardcoded secrets or credentials - Validate input handling and sanitization - Review authentication and authorization logic ### Performance Review + - Identify potential performance bottlenecks - Check for unnecessary database queries (N+1) - Review memory usage patterns @@ -35,24 +39,28 @@ Review code changes for quality, maintainability, and adherence to project stand ## Review Checklist ### Code Quality + - [ ] Code is readable and self-documenting - [ ] Functions are single-purpose (SRP) - [ ] No unnecessary complexity - [ ] Error handling is appropriate ### Testing + - [ ] Tests cover new functionality - [ ] Edge cases are tested - [ ] Test names are descriptive - [ ] Mocks are used appropriately ### Documentation + - [ ] Public APIs are documented - [ ] Complex logic has comments - [ ] README updated if needed - [ ] CHANGELOG entry added ### Security + - [ ] No hardcoded secrets - [ ] Input validation present - [ ] SQL injection prevented diff --git a/.claude/agents/security-auditor.md b/.claude/agents/security-auditor.md index d8c8305..4a6bb68 100644 --- a/.claude/agents/security-auditor.md +++ b/.claude/agents/security-auditor.md @@ -9,24 +9,28 @@ Proactively identify and mitigate security vulnerabilities, ensure compliance wi ## Capabilities ### Vulnerability Detection + - Static code analysis for security issues - Dependency vulnerability scanning - Secret detection and prevention - Configuration security review ### Threat Assessment + - Identify attack vectors - Assess risk levels - Prioritize security fixes - Document security findings ### Compliance Validation + - OWASP Top 10 compliance - Security policy adherence - Secure coding standards - Audit trail verification ### Security Testing + - Injection attack testing - Authentication testing - Authorization testing @@ -35,6 +39,7 @@ Proactively identify and mitigate security vulnerabilities, ensure compliance wi ## Security Checklist ### Code Security + - [ ] No hardcoded credentials - [ ] Input validation on all user input - [ ] Output encoding for XSS prevention @@ -43,18 +48,21 @@ Proactively identify and mitigate security vulnerabilities, ensure compliance wi - [ ] Proper error handling (no info leakage) ### Dependency Security + - [ ] No known vulnerabilities in dependencies - [ ] Dependencies up to date - [ ] Minimal dependency footprint - [ ] Trusted sources only ### Configuration Security + - [ ] Secrets in environment variables - [ ] Secure default configurations - [ ] TLS/SSL properly configured - [ ] CORS properly restricted ### Authentication & Authorization + - [ ] Strong password policies - [ ] Secure session management - [ ] Role-based access control diff --git a/.claude/agents/test-engineer.md b/.claude/agents/test-engineer.md index 969cbbf..8c0fcd9 100644 --- a/.claude/agents/test-engineer.md +++ b/.claude/agents/test-engineer.md @@ -9,24 +9,28 @@ Design and implement test strategies, generate test cases, and ensure code quali ## Capabilities ### Test Strategy + - Design test plans and strategies - Identify critical paths for testing - Balance unit, integration, and e2e tests - Define coverage targets and metrics ### Test Generation + - Generate unit tests for new code - Create integration test scenarios - Design edge case and boundary tests - Implement property-based tests ### Test Review + - Review existing test quality - Identify gaps in test coverage - Suggest test improvements - Validate test isolation ### Test Automation + - Configure CI/CD test pipelines - Set up parallel test execution - Implement test reporting @@ -35,11 +39,13 @@ Design and implement test strategies, generate test cases, and ensure code quali ## Testing Standards ### Coverage Requirements + - **Minimum Coverage**: 80% - **Branch Coverage**: Enabled - **Critical Paths**: 100% coverage ### Test Organization + ``` tests/ ├── unit/ # Fast, isolated tests @@ -50,6 +56,7 @@ tests/ ``` ### Test Quality Criteria + - Tests are deterministic (no flaky tests) - Tests are isolated (no shared state) - Tests are fast (< 1s for unit tests) diff --git a/.claude/commands/merge-standards.md b/.claude/commands/merge-standards.md index 0a83194..3343524 100644 --- a/.claude/commands/merge-standards.md +++ b/.claude/commands/merge-standards.md @@ -5,6 +5,7 @@ After running `cruft update`, merge any changes from `.standards/` into project ## Task 1. Check for changes in baseline files: + ```bash git diff .standards/ ``` diff --git a/.claude/commands/plan.md b/.claude/commands/plan.md index 4e29abb..560af0a 100644 --- a/.claude/commands/plan.md +++ b/.claude/commands/plan.md @@ -32,11 +32,13 @@ Using the `project-planning` skill, generate these four documents with expert re For EACH document, follow this generate-review-refine cycle: ### 1. Generate Document + - Read the corresponding template from `.claude/skills/project-planning/templates/` - Generate project-specific content based on the user's description - Write to the appropriate location in `docs/planning/` ### 2. Expert Review (Consensus) + After writing each document, request expert review: ``` @@ -60,12 +62,15 @@ DOCUMENT: ``` ### 3. Refine if Needed + - If NEEDS REVISION: Incorporate feedback and re-submit for review - If READY: Proceed to next document - Each document must be READY before generating the next ### 4. Final Validation + After all documents pass review: + - Run validation script - Ensure cross-references are valid - Summarize outcomes @@ -99,6 +104,7 @@ This project was created from the cookiecutter-python-template with: ## Fallback (No MCP Server) If `mcp__zen__consensus` is not available: + - Skip the expert review step - Generate all documents sequentially - Run validation script for basic checks diff --git a/.claude/commands/pr.md b/.claude/commands/pr.md index 5541169..90cfac7 100644 --- a/.claude/commands/pr.md +++ b/.claude/commands/pr.md @@ -42,9 +42,9 @@ Analyze the current branch and prepare a PR description following the project te ``` -4. **Output the PR description** ready to copy-paste into GitHub. +1. **Output the PR description** ready to copy-paste into GitHub. -5. **Suggest a PR title** following conventional commits: +2. **Suggest a PR title** following conventional commits: - `feat:` for new features - `fix:` for bug fixes - `docs:` for documentation @@ -57,6 +57,7 @@ Analyze the current branch and prepare a PR description following the project te **Title**: `feat: add user authentication with OAuth2` **Description**: + ``` ## Summary diff --git a/.claude/commands/quality.md b/.claude/commands/quality.md index cc232d2..4e4652c 100644 --- a/.claude/commands/quality.md +++ b/.claude/commands/quality.md @@ -9,6 +9,7 @@ Run code quality checks including formatting, linting, and type checking. ``` **Arguments:** + - `scope` (optional): `all`, `format`, `lint`, `types` (default: `all`) ## Workflow @@ -21,22 +22,26 @@ Run code quality checks including formatting, linting, and type checking. ## Commands Executed ### Format + ```bash uv run black --check . uv run ruff format --check . ``` ### Lint + ```bash uv run ruff check . ``` ### Types + ```bash uv run basedpyright src/ ``` ### All (Pre-commit) + ```bash uv run pre-commit run --all-files ``` @@ -50,6 +55,7 @@ uv run pre-commit run --all-files ## Fix Issues To automatically fix formatting and some lint issues: + ```bash uv run black . uv run ruff check --fix . diff --git a/.claude/commands/security.md b/.claude/commands/security.md index 1a67a08..786f542 100644 --- a/.claude/commands/security.md +++ b/.claude/commands/security.md @@ -9,6 +9,7 @@ Run security validation including environment checks, vulnerability scanning, an ``` **Arguments:** + - `scope` (optional): `all`, `env`, `scan`, `deps` (default: `all`) ## Workflow @@ -21,6 +22,7 @@ Run security validation including environment checks, vulnerability scanning, an ## Commands Executed ### Environment Validation + ```bash # Check GPG key gpg --list-secret-keys @@ -33,6 +35,7 @@ git config --get user.signingkey ``` ### Code Scanning + ```bash # Bandit security scanner uv run bandit -r src/ -c pyproject.toml @@ -42,6 +45,7 @@ uv run semgrep scan --config auto src/ ``` ### Dependency Audit + ```bash # Check for vulnerable dependencies uv run pip-audit @@ -51,6 +55,7 @@ uv run safety check ``` ### Secrets Detection + ```bash # Gitleaks scan gitleaks detect --source . @@ -69,6 +74,7 @@ trufflehog filesystem . ## OWASP Compliance Focus on preventing: + - A01: Broken Access Control - A03: Injection - A07: Authentication Failures diff --git a/.claude/commands/testing.md b/.claude/commands/testing.md index 63c5b9e..bab15e7 100644 --- a/.claude/commands/testing.md +++ b/.claude/commands/testing.md @@ -9,22 +9,26 @@ Run tests with coverage reporting and optional test generation. ``` **Arguments:** + - `action` (optional): `run`, `generate`, `review`, `coverage` (default: `run`) - `scope` (optional): `all`, `unit`, `integration`, `e2e` (default: `all`) ## Workflow ### Run Tests + 1. Execute pytest with specified scope 2. Generate coverage report 3. Report results and coverage percentage ### Generate Tests + 1. Analyze target code 2. Generate test cases for untested functions 3. Create test file with fixtures ### Review Tests + 1. Analyze existing test quality 2. Identify coverage gaps 3. Suggest improvements @@ -32,31 +36,37 @@ Run tests with coverage reporting and optional test generation. ## Commands Executed ### Run All Tests + ```bash uv run pytest -v --tb=short ``` ### Run with Coverage + ```bash uv run pytest --cov=src/python_libs --cov-report=html --cov-report=term-missing ``` ### Run Unit Tests Only + ```bash uv run pytest tests/unit/ -v --tb=short ``` ### Run Integration Tests + ```bash uv run pytest tests/integration/ -v --tb=short -m "integration" ``` ### Run E2E Tests + ```bash uv run pytest tests/e2e/ -v --tb=short -m "e2e" ``` ### Mutation Testing + ```bash uv run mutmut run --paths-to-mutate=src/ ``` diff --git a/.claude/context/python-standards.md b/.claude/context/python-standards.md index 226ff13..e4e4e85 100644 --- a/.claude/context/python-standards.md +++ b/.claude/context/python-standards.md @@ -5,22 +5,26 @@ Standards and patterns for Python development in this project. ## Code Style ### Formatting + - **Formatter**: Black (88 character line length) - **Import Sorting**: Ruff isort rules - **Docstrings**: Google style ### Linting + - **Linter**: Ruff with PyStrict-aligned rules - **Type Checker**: BasedPyright (strict mode) ## Type Annotations ### Required Annotations + - All public function parameters - All public function return types - All class attributes ### Type Checking Configuration + ```toml [tool.basedpyright] pythonVersion = "3.12" @@ -33,6 +37,7 @@ strictSetInference = true ## Error Handling ### Patterns + ```python # Use specific exceptions def process_data(data: dict[str, Any]) -> Result: @@ -47,6 +52,7 @@ def process_data(data: dict[str, Any]) -> Result: ``` ### Anti-Patterns + ```python # Avoid bare except try: @@ -64,6 +70,7 @@ except Exception: # Too broad ## Testing Standards ### Test Organization + ```text tests/ ├── unit/ # Fast, isolated tests (<1s each) @@ -73,11 +80,13 @@ tests/ ``` ### Coverage Requirements + - **Minimum**: 80% - **Branch Coverage**: Enabled - **Critical Paths**: 100% ### Test Naming + ```python def test_function_name_when_condition_then_expected_result(): """Descriptive test names following Given-When-Then pattern.""" @@ -87,6 +96,7 @@ def test_function_name_when_condition_then_expected_result(): ## Documentation ### Docstring Format (Google Style) + ```python def function(param1: str, param2: int) -> bool: """Short description of function. @@ -112,16 +122,19 @@ def function(param1: str, param2: int) -> bool: ## Security Considerations ### Input Validation + - Always validate user input at boundaries - Use type annotations for runtime validation - Sanitize before processing ### Secret Management + - Never hardcode secrets - Use environment variables - Encrypt sensitive data at rest ### Dependency Management + - Pin dependency versions - Regular security audits - Use trusted sources only @@ -129,16 +142,19 @@ def function(param1: str, param2: int) -> bool: ## Performance Guidelines ### Database Queries + - Avoid N+1 queries - Use eager loading where appropriate - Index frequently queried columns ### Memory Management + - Use generators for large datasets - Clean up resources (context managers) - Profile memory usage ### Async Operations + - Use asyncio for I/O-bound operations - Avoid blocking calls in async contexts - Use connection pooling diff --git a/.claude/context/testing-patterns.md b/.claude/context/testing-patterns.md index de70029..b9fee0d 100644 --- a/.claude/context/testing-patterns.md +++ b/.claude/context/testing-patterns.md @@ -5,6 +5,7 @@ Common testing patterns and best practices for this project. ## Test Structure ### AAA Pattern (Arrange-Act-Assert) + ```python def test_user_creation(): # Arrange @@ -21,6 +22,7 @@ def test_user_creation(): ## Fixtures ### Basic Fixture + ```python @pytest.fixture def sample_user(): @@ -31,6 +33,7 @@ def test_user_display(sample_user): ``` ### Factory Fixture + ```python @pytest.fixture def user_factory(): @@ -45,6 +48,7 @@ def test_custom_user(user_factory): ``` ### Async Fixture + ```python @pytest.fixture async def async_client(): @@ -55,6 +59,7 @@ async def async_client(): ## Mocking ### Mock External Services + ```python @pytest.fixture def mock_api(mocker): @@ -67,6 +72,7 @@ def test_with_mock(mock_api): ``` ### Mock Database + ```python @pytest.fixture def mock_db(mocker): @@ -102,6 +108,7 @@ def test_encode_decode_roundtrip(text): ## Test Categories ### Unit Tests + ```python @pytest.mark.unit def test_pure_function(): @@ -109,6 +116,7 @@ def test_pure_function(): ``` ### Integration Tests + ```python @pytest.mark.integration def test_database_integration(db_session): @@ -117,6 +125,7 @@ def test_database_integration(db_session): ``` ### Slow Tests + ```python @pytest.mark.slow def test_complex_operation(): diff --git a/.claude/skills/commit-prepare/SKILL.md b/.claude/skills/commit-prepare/SKILL.md index 7ec0b22..f2f1dc8 100644 --- a/.claude/skills/commit-prepare/SKILL.md +++ b/.claude/skills/commit-prepare/SKILL.md @@ -10,6 +10,7 @@ Automatically prepare commit messages following conventional commits standard. ## Activation This skill activates on keywords: + - "commit", "prepare commit", "commit this" - "commit message", "write commit" - "stage and commit", "commit changes" @@ -38,6 +39,7 @@ git diff --stat ### 2. Analyze Changes Determine: + - **Type**: feat, fix, docs, refactor, test, chore, perf, ci - **Scope**: Which component/module is affected (optional) - **Breaking**: Are there breaking changes? @@ -79,6 +81,7 @@ Follow conventional commits format: ### 4. Handle Staging If there are unstaged changes, ask: + - "Stage all changes?" (`git add .`) - "Stage specific files?" (list them) - "Review changes first?" (show diff) @@ -111,6 +114,7 @@ EOF ### 6. Post-Commit After successful commit: + - Show `git log -1` to confirm - Suggest `git push` if ready - Mention if more changes remain unstaged @@ -122,16 +126,19 @@ After successful commit: **User**: "commit these changes" **Claude**: + ```bash git status git diff --cached ``` Looking at your staged changes: + - Modified `src/auth/oauth.py` - added token refresh logic - Modified `tests/test_auth.py` - added refresh tests **Suggested commit**: + ``` feat(auth): add OAuth token refresh @@ -150,6 +157,7 @@ Shall I commit with this message? **Claude**: I see you've changed the API response format. This is a breaking change. **Suggested commit**: + ``` feat(api)!: change response envelope format @@ -168,11 +176,13 @@ This marks it as a breaking change with `!`. Proceed? **User**: "commit this" **Claude**: I see changes to multiple unrelated areas: + 1. Bug fix in `parser.py` 2. New feature in `export.py` 3. Updated docs Recommend splitting into separate commits: + 1. `fix(parser): handle empty input gracefully` 2. `feat(export): add CSV export option` 3. `docs: update export documentation` diff --git a/.claude/skills/git/SKILL.md b/.claude/skills/git/SKILL.md index 906a46e..d18efdd 100644 --- a/.claude/skills/git/SKILL.md +++ b/.claude/skills/git/SKILL.md @@ -9,13 +9,16 @@ Auto-activates on keywords: git, branch, commit, pull request, PR, merge, rebase ## Workflows ### Branch Management + - **branch.md**: Branch creation, validation, and naming conventions - **status.md**: Repository status and health checks ### Commit Management + - **commit.md**: Conventional commit message preparation ### PR Workflow + - **pr-prepare.md**: Pull request description generation - **pr-check.md**: PR validation and checklist diff --git a/.claude/skills/pr-prepare/SKILL.md b/.claude/skills/pr-prepare/SKILL.md index 0b449a2..5ca058a 100644 --- a/.claude/skills/pr-prepare/SKILL.md +++ b/.claude/skills/pr-prepare/SKILL.md @@ -10,6 +10,7 @@ Automatically prepare pull request descriptions following project standards. ## Activation This skill activates on keywords: + - "prepare PR", "prepare the PR", "prepare a PR" - "create PR", "create pull request" - "PR description", "pull request description" @@ -41,6 +42,7 @@ git diff $(git merge-base HEAD main)..HEAD ### 2. Analyze Changes Identify: + - **Components modified**: Which files/modules changed - **Purpose**: Why these changes were made - **Impact**: Benefits, risks, breaking changes @@ -95,6 +97,7 @@ Follow conventional commits format: Present the complete PR description ready to copy-paste into GitHub. Remind the user: + - CodeRabbit will auto-fill `@coderabbitai summary` placeholder - They can push and create PR with `gh pr create` @@ -103,6 +106,7 @@ Remind the user: **User**: "Can you prepare the PR for this branch?" **Claude**: + 1. Runs git commands to gather context 2. Analyzes the changes 3. Outputs: @@ -143,6 +147,7 @@ Follow-up: Add Microsoft provider support --- Ready to copy! Push with: + ```bash git push -u origin HEAD gh pr create --fill diff --git a/.claude/skills/project-planning/SKILL.md b/.claude/skills/project-planning/SKILL.md index 123aaa2..5175c12 100644 --- a/.claude/skills/project-planning/SKILL.md +++ b/.claude/skills/project-planning/SKILL.md @@ -33,6 +33,7 @@ maintain context coherence across coding sessions and prevent architectural drif ### Step 1: Gather Project Context Before generating, collect: + 1. **Project description** from user input 2. **Technical constraints** from `pyproject.toml` and existing code 3. **Cookiecutter choices** reflected in project structure @@ -71,6 +72,7 @@ Document content: ``` **Review each document in order**: + 1. PVS → Must be READY before generating ADR 2. ADR → Must be READY before generating Tech Spec 3. Tech Spec → Must be READY before generating Roadmap @@ -81,6 +83,7 @@ If any document NEEDS REVISION, incorporate feedback and re-review before procee ### Step 4: Validate and Cross-Reference After all documents pass review: + - Ensure documents reference each other correctly - Verify technical choices are consistent across documents - Flag any assumptions needing user validation @@ -101,6 +104,7 @@ After all documents pass review: Use template: `templates/pvs-template.md` Focus on: + - Problem being solved and user impact - Core capabilities (3-5 max for MVP) - Explicit scope boundaries (in vs out) @@ -111,6 +115,7 @@ Focus on: Use template: `templates/adr-template.md` Create ADR for: + - Database/storage choice - Authentication strategy - API design approach @@ -124,6 +129,7 @@ Format: `adr-001-{decision-slug}.md` Use template: `templates/tech-spec-template.md` Include: + - Complete tech stack with versions - Component architecture diagram (ASCII) - Data model with schemas @@ -136,12 +142,14 @@ Include: Use template: `templates/roadmap-template.md` Structure as: + - Phase 0: Foundation (environment, CI/CD) - Phase 1: MVP Core (essential features) - Phase 2: Enhancement (additional features) - Phase 3: Polish (testing, documentation) Each phase needs: + - Clear deliverables - Success criteria (testable) - Estimated duration @@ -174,6 +182,7 @@ Before completing generation: ## Templates Reference Templates are in `templates/` directory: + - `pvs-template.md` - Project Vision & Scope structure - `adr-template.md` - Architecture Decision Record structure - `tech-spec-template.md` - Technical Spec structure @@ -182,12 +191,14 @@ Templates are in `templates/` directory: ## Detailed Guidance For comprehensive documentation on each document type, see `reference/` directory: + - `reference/document-guide.md` - Full guidance for all document types - `reference/prompting-patterns.md` - How to use documents during development ## After Generation Instruct user to: + 1. Review each document for accuracy 2. Validate assumptions marked with `[ ]` 3. Adjust timelines in roadmap if needed diff --git a/.claude/skills/project-planning/reference/document-guide.md b/.claude/skills/project-planning/reference/document-guide.md index fac276f..669019b 100644 --- a/.claude/skills/project-planning/reference/document-guide.md +++ b/.claude/skills/project-planning/reference/document-guide.md @@ -17,6 +17,7 @@ Comprehensive guidance for creating and maintaining project planning documents. ### The Problem They Solve AI-assisted development fails when: + - Massive context dumps overwhelm the model - Planning is skipped, leading to architectural drift - Decisions aren't documented, causing hallucinations @@ -56,11 +57,13 @@ AI-assisted development fails when: ### Project Vision & Scope (PVS) **Feeds into**: + - ADRs: Technical choices stem from requirements - Tech Spec: Features define what to implement - Roadmap: Scope determines work items **Updated when**: + - Major scope changes - New success metrics identified - Quarterly review @@ -68,14 +71,17 @@ AI-assisted development fails when: ### Architecture Decision Records (ADRs) **Feeds into**: + - Tech Spec: Decisions define implementation approach - Roadmap: Some decisions require phased migration **Referenced by**: + - Code comments where decisions are implemented - Tech Spec for rationale **Updated when**: + - New architectural decision made - Previous decision superseded - Post-implementation review reveals issues @@ -83,14 +89,17 @@ AI-assisted development fails when: ### Technical Implementation Spec **Feeds into**: + - Roadmap: Components map to work items - Code: Direct reference during implementation **References**: + - PVS for requirements context - ADRs for decision rationale **Updated when**: + - Architecture changes - Version upgrades - Security requirements change @@ -98,11 +107,13 @@ AI-assisted development fails when: ### Development Roadmap **References**: + - PVS for scope - Tech Spec for component breakdown - ADRs for dependencies **Updated when**: + - After each phase/sprint - Timeline shifts - New features added @@ -154,6 +165,7 @@ As mentioned elsewhere... **Solution**: Replace every placeholder with project-specific content **Bad**: + ```markdown ### Success Metrics - Improve user satisfaction @@ -161,6 +173,7 @@ As mentioned elsewhere... ``` **Good**: + ```markdown ### Success Metrics - Transaction import time: 30s → 5s (6x improvement) diff --git a/.claude/skills/project-planning/reference/prompting-patterns.md b/.claude/skills/project-planning/reference/prompting-patterns.md index 6d5d381..968e924 100644 --- a/.claude/skills/project-planning/reference/prompting-patterns.md +++ b/.claude/skills/project-planning/reference/prompting-patterns.md @@ -57,11 +57,13 @@ Continue with US-003 from roadmap. ### Feature Implementation **Bad** (too broad): + ``` Build the entire authentication system. ``` **Good** (incremental): + ``` Implement user registration endpoint per tech-spec.md section 4.1. Focus on input validation first, per ADR-002 validation strategy. @@ -183,12 +185,14 @@ Flag if this affects timeline. ### Context Dumping **Bad**: + ``` Here's my entire project-vision.md, tech-spec.md, and all ADRs. Now implement feature X. ``` **Good**: + ``` From tech-spec.md section 4.2 and ADR-001, implement the database migration for User entity. @@ -197,12 +201,14 @@ implement the database migration for User entity. ### Vague References **Bad**: + ``` Follow the spec. Per the architecture decision. ``` **Good**: + ``` Per tech-spec.md section 3.2 (User entity schema). Per ADR-001 decision to use PostgreSQL with UUID primary keys. @@ -211,11 +217,13 @@ Per ADR-001 decision to use PostgreSQL with UUID primary keys. ### Skipping Validation **Bad**: + ``` Looks good, merge it. ``` **Good**: + ``` Before merging, validate against: - tech-spec.md section 6 (security) @@ -225,11 +233,13 @@ Before merging, validate against: ### Ignoring Document Updates **Bad**: + ``` We changed the approach but the docs still say the old way. ``` **Good**: + ``` Implementation differs from tech-spec.md section 3. @@ -247,6 +257,7 @@ Create ADR if this is a significant architectural change. ### Prompt Templates **Implement Feature**: + ``` Per [doc] section [X], implement [feature]. Reference [ADR-XXX] for [specific decision]. @@ -254,6 +265,7 @@ Success criteria from roadmap.md: [criteria]. ``` **Validate Code**: + ``` Review against: - [doc] section [X] ([topic]) @@ -262,6 +274,7 @@ Flag violations. ``` **Update Documents**: + ``` Completed [task/decision]. Update: @@ -270,6 +283,7 @@ Update: ``` **Start Session**: + ``` Load from: - [doc] sections [X-Y] diff --git a/.claude/skills/project-planning/templates/adr-template.md b/.claude/skills/project-planning/templates/adr-template.md index 985d2d6..a284017 100644 --- a/.claude/skills/project-planning/templates/adr-template.md +++ b/.claude/skills/project-planning/templates/adr-template.md @@ -100,6 +100,7 @@ ## Common Initial ADRs For new projects, typically create: + 1. `adr-001-database-choice.md` - Storage strategy 2. `adr-002-auth-strategy.md` - Authentication approach (if applicable) 3. `adr-003-api-design.md` - API patterns (if applicable) diff --git a/.claude/skills/project-planning/templates/roadmap-template.md b/.claude/skills/project-planning/templates/roadmap-template.md index 34f64b1..ba57642 100644 --- a/.claude/skills/project-planning/templates/roadmap-template.md +++ b/.claude/skills/project-planning/templates/roadmap-template.md @@ -13,10 +13,12 @@ ## Timeline Overview ``` + Phase 0: Foundation ████████░░░░░░░░ (1 week) - Setup Phase 1: MVP Core ░░░░░░░░████████ (3 weeks) - Core features Phase 2: Enhancement ░░░░░░░░░░░░░░░░ (2 weeks) - Additional features Phase 3: Polish ░░░░░░░░░░░░░░░░ (1 week) - Testing & docs + ``` ## Milestones diff --git a/.claude/skills/project-planning/templates/tech-spec-template.md b/.claude/skills/project-planning/templates/tech-spec-template.md index 91144ab..955ab45 100644 --- a/.claude/skills/project-planning/templates/tech-spec-template.md +++ b/.claude/skills/project-planning/templates/tech-spec-template.md @@ -40,6 +40,7 @@ ### Component Diagram ``` + ┌─────────────────────────────────────────┐ │ [Component] │ ├─────────────┬─────────────┬─────────────┤ @@ -50,6 +51,7 @@ ┌─────────────────────────────────────────┐ │ [Data Layer] │ └─────────────────────────────────────────┘ + ``` ### Component Responsibilities @@ -72,17 +74,20 @@ class [Entity]: ``` ### Relationships + - [Entity A] → [Entity B]: [Relationship type] ## 4. API Specification (if applicable) ### Endpoints + | Method | Path | Purpose | Auth | |--------|------|---------|------| | GET | /api/v1/[resource] | [Purpose] | [Yes/No] | | POST | /api/v1/[resource] | [Purpose] | [Yes/No] | ### Request/Response Format + ```json { "[field]": "[type]", @@ -93,22 +98,25 @@ class [Entity]: ## 5. CLI Specification (if applicable) ### Commands + | Command | Purpose | Example | |---------|---------|---------| | `[cmd] [subcmd]` | [Purpose] | `[example]` | ### Arguments + - `--[arg]`: [Description] (default: [value]) ## 6. Security ### Authentication + [Method]: [Details] - See [ADR-XXX] ### Authorization -[RBAC/ABAC/etc]: [Details] ### Data Protection + - **At Rest**: [Encryption method] - **In Transit**: [TLS/etc] - **Sensitive Data**: [Handling approach] @@ -116,14 +124,17 @@ class [Entity]: ## 7. Error Handling ### Strategy + [Approach to errors - fail fast, graceful degradation, etc] ### Error Codes + | Code | Meaning | User Action | |------|---------|-------------| | [Code] | [Description] | [What user should do] | ### Logging + - **Format**: Structured JSON - **Levels**: DEBUG, INFO, WARNING, ERROR - **Sensitive**: [What NOT to log] @@ -139,18 +150,22 @@ class [Entity]: ## 9. Testing Strategy ### Coverage Target + - Minimum: [X]% - Critical paths: 100% ### Test Types + - **Unit**: [Focus areas] - **Integration**: [Key scenarios] - **E2E**: [User workflows] ## Related Documents + - [Project Vision](./project-vision.md) - [Architecture Decisions](./adr/) - [Development Roadmap](./roadmap.md) + ``` ## Generation Notes diff --git a/.claude/skills/project-planning/workflows/synthesize.md b/.claude/skills/project-planning/workflows/synthesize.md index 4fb93a6..e5caa3a 100644 --- a/.claude/skills/project-planning/workflows/synthesize.md +++ b/.claude/skills/project-planning/workflows/synthesize.md @@ -52,6 +52,7 @@ echo "✅ Found $adr_count ADR(s)" Read and extract key information from each document: **project-vision.md**: + - TL;DR / Executive summary - Problem statement - Target users @@ -61,6 +62,7 @@ Read and extract key information from each document: - Constraints **tech-spec.md**: + - Technology stack - Architecture overview - Data model @@ -69,6 +71,7 @@ Read and extract key information from each document: - Dependencies **roadmap.md**: + - Phase names and durations - Deliverables per phase - Success criteria @@ -76,6 +79,7 @@ Read and extract key information from each document: - Risks **adr/*.md**: + - Decision titles - Status - Key rationale @@ -96,6 +100,7 @@ For each phase in the roadmap, determine the appropriate branch type: | Refactoring | `refactor/` | No release | **Branch Naming**: + ``` {type}/phase-{number}-{short-slug} @@ -156,6 +161,7 @@ source_documents: ``` **Complete a phase**: + ```bash /git/milestone complete /git/pr-prepare --include_wtd=true @@ -178,6 +184,7 @@ source_documents: {criteria from roadmap} **Start Phase**: + ```bash /git/milestone start {branch-name} ``` @@ -228,9 +235,11 @@ source_documents: 1. Review this synthesized plan for accuracy 2. Start Phase 0: + ```bash /git/milestone start feat/phase-0-foundation ``` + 3. Track progress with TodoWrite 4. Complete phases with PR workflow @@ -240,6 +249,7 @@ source_documents: - [Technical Specification](./tech-spec.md) - [Development Roadmap](./roadmap.md) - [Architecture Decisions](./adr/) + ``` ### 5. Create Initial TODO List @@ -299,6 +309,7 @@ After synthesis: ## Error Handling ### Missing Documents + ``` ❌ Missing required documents: - project-vision.md (placeholder) @@ -308,6 +319,7 @@ Run first: /plan ``` ### Conflicting Information + ``` ⚠️ Inconsistency detected: - Roadmap Phase 1 duration: 3 weeks @@ -317,6 +329,7 @@ Please clarify timeline before synthesis. ``` ### No ADRs Found + ``` ⚠️ No Architecture Decision Records found. diff --git a/.claude/skills/quality/SKILL.md b/.claude/skills/quality/SKILL.md index d28aa50..1377057 100644 --- a/.claude/skills/quality/SKILL.md +++ b/.claude/skills/quality/SKILL.md @@ -9,13 +9,16 @@ Auto-activates on keywords: quality, lint, format, precommit, naming, black, ruf ## Workflows ### Formatting + - **format.md**: Code formatting with Black and Ruff ### Linting + - **lint.md**: Linting checks with Ruff - **naming.md**: Naming convention validation ### Pre-commit + - **precommit.md**: Pre-commit hook validation ## Commands @@ -39,11 +42,13 @@ uv run pre-commit run --all-files ## Quality Standards ### Python Standards + - **Line Length**: 88 characters (Black default) - **Type Checking**: BasedPyright strict mode - **Linting**: Ruff with PyStrict-aligned rules ### Rule Categories + - **BLE**: Blind except detection - **EM**: Error message best practices - **SLF**: Private member access violations @@ -52,4 +57,5 @@ uv run pre-commit run --all-files - **G**: Logging format strings ### Per-File Ignores + Tests and scripts have relaxed rules for pragmatic development. diff --git a/.claude/skills/security/SKILL.md b/.claude/skills/security/SKILL.md index 0631210..e299759 100644 --- a/.claude/skills/security/SKILL.md +++ b/.claude/skills/security/SKILL.md @@ -9,12 +9,15 @@ Auto-activates on keywords: security, vulnerability, audit, OWASP, encryption, G ## Workflows ### Environment Validation + - **validate-env.md**: GPG/SSH key validation ### Scanning + - **scan.md**: Security vulnerability scanning ### Encryption + - **encrypt.md**: Secret encryption and management ## Commands @@ -43,11 +46,13 @@ uv run semgrep scan --config auto src/ ## Security Checklist ### Pre-Commit + - [ ] No secrets in code (checked by gitleaks) - [ ] Dependencies scanned for vulnerabilities - [ ] Bandit security scan passes ### Pre-Release + - [ ] All known vulnerabilities addressed - [ ] Security advisory published (if applicable) - [ ] Dependencies updated to secure versions diff --git a/.claude/skills/testing/SKILL.md b/.claude/skills/testing/SKILL.md index a815b80..f46c1d8 100644 --- a/.claude/skills/testing/SKILL.md +++ b/.claude/skills/testing/SKILL.md @@ -9,12 +9,15 @@ Auto-activates on keywords: test, coverage, pytest, unittest, integration test, ## Workflows ### Test Generation + - **generate.md**: Generate test cases for code ### Test Review + - **review.md**: Review existing tests for quality ### Specialized Testing + - **e2e.md**: End-to-end testing patterns - **security.md**: Security testing patterns - **performance.md**: Performance testing patterns @@ -69,6 +72,7 @@ tests/ ## Testing Patterns ### AAA Pattern (Arrange-Act-Assert) + ```python def test_example(): # Arrange @@ -82,6 +86,7 @@ def test_example(): ``` ### Fixtures + ```python @pytest.fixture def sample_data(): diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 0a5153a..2de93ad 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -48,9 +48,11 @@ This project uses **org-level reusable workflows** for consistency and maintaina ## Workflow Descriptions ### CI Pipeline (`ci.yml`) + **Calls**: `ByronWilliamsCPA/.github/.github/workflows/python-ci.yml@main` Comprehensive CI with: + - Multi-version Python testing (3.12) - UV dependency management - Ruff linting and formatting @@ -63,9 +65,11 @@ Comprehensive CI with: --- ### Security Analysis (`security-analysis.yml`) + **Calls**: `ByronWilliamsCPA/.github/.github/workflows/python-security-analysis.yml@main` Comprehensive security scanning with: + - CodeQL advanced analysis - Bandit static security analysis - Safety dependency CVE scanning @@ -78,9 +82,11 @@ Comprehensive security scanning with: --- ### Documentation (`docs.yml`) + **Calls**: `ByronWilliamsCPA/.github/.github/workflows/python-docs.yml@main` Documentation build and deployment: + - MkDocs build with Material theme - Link validation - Deployment to GitHub Pages (on push to main) @@ -89,9 +95,11 @@ Documentation build and deployment: --- ### Publish to PyPI (`publish-pypi.yml`) + **Calls**: `ByronWilliamsCPA/.github/.github/workflows/python-publish-pypi.yml@main` Package publishing with: + - OIDC trusted publishing (no API tokens needed) - Test PyPI validation - SBOM generation @@ -102,9 +110,11 @@ Package publishing with: --- ### Release (`release.yml`) + **Calls**: `ByronWilliamsCPA/.github/.github/workflows/python-release.yml@main` Release automation with: + - SLSA provenance generation - Signed artifacts - Comprehensive changelog @@ -115,9 +125,11 @@ Release automation with: --- ### SBOM & Security Scan (`sbom.yml`) + **Calls**: `ByronWilliamsCPA/.github/.github/workflows/python-sbom.yml@main` Software Bill of Materials and vulnerability scanning: + - CycloneDX SBOM generation - Trivy vulnerability scanning - License compliance checking @@ -130,22 +142,27 @@ Software Bill of Materials and vulnerability scanning: ## Benefits of Org-Level Reusable Workflows ### ✅ **Consistency** + All projects use the same tested CI/CD pipeline configuration. ### ✅ **Maintainability** + - Update workflows once at org level - All projects inherit improvements automatically - No need to update hundreds of project workflows ### ✅ **Reduced Duplication** + - Caller workflows are ~50 lines vs ~300+ for embedded workflows - 85% reduction in workflow code per project ### ✅ **Version Control** + - Workflows versioned at `@main` (or pin to specific version/SHA) - Easy rollback if needed ### ✅ **Security** + - Centralized security updates - Consistent security practices across org @@ -156,6 +173,7 @@ All projects use the same tested CI/CD pipeline configuration. Caller workflows are configured via `with:` parameters. See individual workflow files for available options. Example customization: + ```yaml jobs: ci: @@ -188,22 +206,27 @@ act push -j ci ## Troubleshooting ### Workflow Fails to Find Reusable Workflow + **Error**: `Workflow file not found` **Solution**: Ensure the org-level `.github` repository exists and workflows are at: + ``` ByronWilliamsCPA/.github/.github/workflows/*.yml ``` ### Permission Denied + **Error**: `Resource not accessible by integration` **Solution**: Check workflow permissions. Caller workflows inherit permissions from reusable workflows, but may need additional `permissions:` blocks. ### Secrets Not Available + **Error**: `Secret not found` **Solution**: Add secrets at repository or organization level: + - Repository Settings → Secrets and variables → Actions - Organization Settings → Secrets and variables → Actions diff --git a/.qlty/logs b/.qlty/logs new file mode 120000 index 0000000..4bd246a --- /dev/null +++ b/.qlty/logs @@ -0,0 +1 @@ +/home/byron/.qlty/cache/repos/2a3113e896eb2e52f86ae7c01748afc7/logs \ No newline at end of file diff --git a/.qlty/out b/.qlty/out new file mode 120000 index 0000000..ca355ad --- /dev/null +++ b/.qlty/out @@ -0,0 +1 @@ +/home/byron/.qlty/cache/repos/2a3113e896eb2e52f86ae7c01748afc7/out \ No newline at end of file diff --git a/.qlty/plugin_cachedir b/.qlty/plugin_cachedir new file mode 120000 index 0000000..e15fde5 --- /dev/null +++ b/.qlty/plugin_cachedir @@ -0,0 +1 @@ +/home/byron/.qlty/cache/repos/2a3113e896eb2e52f86ae7c01748afc7/plugin_cachedir \ No newline at end of file diff --git a/.qlty/qlty.toml b/.qlty/qlty.toml index 01f98ba..6ac2141 100644 --- a/.qlty/qlty.toml +++ b/.qlty/qlty.toml @@ -1,35 +1,17 @@ # Qlty Configuration for Python Libs # This configuration uses Qlty for unified code quality analysis. # Note: Most security tools run via pre-commit hooks instead. - +# +# For configuration reference: https://qlty.sh/d/qlty-toml config_version = "0" -# File patterns to completely exclude from all analysis -exclude_patterns = [ - "*.log", - "**/__pycache__/**", - "**/*.pyc", - "**/*.pyo", - "**/.pytest_cache/**", - "**/.mypy_cache/**", - "**/.ruff_cache/**", - "**/node_modules/**", - "**/.venv/**", - "**/venv/**", - "**/build/**", - "**/dist/**", - "**/*.egg-info/**", - "**/data/**", - "**/models/**", - "**/.git/**", -] - -# Patterns to identify test files for enhanced analysis -test_patterns = [ - "**/tests/**", - "**/test_*.py", - "**/*_test.py", -] +# Default source for plugin definitions +[[source]] +name = "default" +default = true + +# Note: File exclude and test patterns are configured at the top-level +# exclude_patterns and test_patterns are not supported in [[source]] blocks # ============================================================================ # Python Linting and Formatting - Ruff @@ -101,36 +83,52 @@ boolean_logic.threshold = 6 # Allow larger Python files for models, views, etc. file_complexity.threshold = 750 +# ============================================================================ +# Plugins - Using default source +# ============================================================================ + +# Python linting with Ruff +[[plugin]] +name = "ruff" +drivers = ["lint"] + +# Python security with Bandit (comment mode - subprocess use is intentional for validation) +# Note: B101 (assert) warnings in tests are expected - nosec comments inline or ignored +# Note: Bandit configured in pyproject.toml to skip tests directory +[[plugin]] +name = "bandit" +mode = "comment" + +# Shell script linting (comment mode - script styling preferences) +[[plugin]] +name = "shellcheck" +mode = "comment" + +# YAML linting (comment mode - don't block CI for formatting) +[[plugin]] +name = "yamllint" +mode = "comment" + +# Markdown linting (comment mode - don't block CI) +[[plugin]] +name = "markdownlint" +mode = "comment" + +# GitHub Actions linting (comment mode - empty string in options is intentional) +[[plugin]] +name = "actionlint" +mode = "comment" + +# Vulnerability scanning (comment mode - vulnerabilities reported but don't block) +[[plugin]] +name = "osv-scanner" +mode = "comment" + # ============================================================================ # Note on Security Scanning # ============================================================================ -# Security tools are run via pre-commit hooks instead of qlty plugins: +# Additional security tools run via pre-commit hooks: # - detect-secrets: Secrets detection -# - bandit: Python security linter (via pyproject.toml [tool.bandit]) # - safety: Dependency vulnerability scanning # -# This approach is more reliable as qlty plugin availability varies. # See .pre-commit-config.yaml for the full security tool configuration. - -# ============================================================================ -# Documentation and Maintenance -# ============================================================================ -# This configuration is maintained as part of the project template. -# -# To update plugins: -# qlty plugins update -# -# To see the full merged configuration: -# qlty config show -# -# To validate this configuration: -# qlty config validate -# -# ============================================================================ -# Duplication Detection -# ============================================================================ -# Duplicate code detection is handled by the smells feature (mode="comment" above). -# Note: CPD (Copy-Paste Detector) is not available as a qlty plugin. - -# For more information: -# https://docs.qlty.sh/qlty-toml diff --git a/.qlty/results b/.qlty/results new file mode 120000 index 0000000..220b472 --- /dev/null +++ b/.qlty/results @@ -0,0 +1 @@ +/home/byron/.qlty/cache/repos/2a3113e896eb2e52f86ae7c01748afc7/results \ No newline at end of file diff --git a/.standards/CLAUDE.baseline.md b/.standards/CLAUDE.baseline.md index bafc58f..e409ead 100644 --- a/.standards/CLAUDE.baseline.md +++ b/.standards/CLAUDE.baseline.md @@ -126,11 +126,13 @@ Claude MUST adopt a security-first approach in all development: For deployment on FIPS-enabled systems (Ubuntu LTS with fips-updates, government systems, healthcare, finance): **Prohibited algorithms** (will fail in FIPS mode): + - MD5, MD4, SHA-1 (for security purposes) - DES, 3DES, RC2, RC4, Blowfish - Non-approved key exchange methods **Required patterns**: + ```python # ✗ WRONG - Will fail on FIPS systems import hashlib @@ -144,11 +146,13 @@ h = hashlib.sha256(data) ``` **Check FIPS compatibility**: + ```bash uv run python scripts/check_fips_compatibility.py --fix-hints ``` **Problematic packages** (need verification or replacement): + - `bcrypt` → Use `passlib` with PBKDF2 or `argon2-cffi` - `pycrypto` → Use `pycryptodome` with FIPS mode - Verify `cryptography` version >= 3.4.6 with OpenSSL FIPS provider diff --git a/.standards/README.baseline.md b/.standards/README.baseline.md index 4124c0c..d1a39a7 100644 --- a/.standards/README.baseline.md +++ b/.standards/README.baseline.md @@ -152,12 +152,14 @@ When `.standards/README.baseline.md` is updated by cruft: 3. **Preserve project content** - Keep your custom Overview, Features, etc. **What to merge:** + - Badge URLs and formats (may add new badges) - Tool installation instructions (versions may change) - Quality standards tables (rules may be added) - Workflow documentation (process improvements) **What NOT to merge:** + - Your project's Overview section - Your project's Features section - Project-specific configuration diff --git a/.standards/template_feedback.baseline.md b/.standards/template_feedback.baseline.md index 9381cd1..6b695b8 100644 --- a/.standards/template_feedback.baseline.md +++ b/.standards/template_feedback.baseline.md @@ -146,12 +146,14 @@ When `.standards/template_feedback.baseline.md` is updated by cruft: 4. **Preserve your feedback** - NEVER overwrite actual feedback items **What to merge:** + - Format template updates - New categories or priority definitions - Updated submission instructions - Example improvements **What NOT to merge:** + - Your actual feedback items - Your project-specific notes - Any local workarounds documented diff --git a/CHANGELOG.md b/CHANGELOG.md index 147ca26..a08d750 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,11 +8,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Added + - Initial project setup and structure ## [0.1.0] - TBD ### Added + - Initial project structure with Poetry package management - Pydantic v2 JSON schema validation - Structured logging with structlog and rich console output @@ -23,12 +25,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - License ### Documentation + - README with project overview and quick start - CONTRIBUTING guidelines with development workflow - References to ByronWilliamsCPA org-level Security Policy - References to ByronWilliamsCPA org-level Code of Conduct ### Infrastructure + - Poetry dependency management with lock file - pytest test framework with coverage reporting - GitHub issue tracking and templates @@ -37,6 +41,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - CI/CD pipeline with multiple quality gates ### Security + - Bandit security linting - Safety dependency vulnerability scanning - Pre-commit hooks for security validation diff --git a/CLAUDE.md b/CLAUDE.md index b86b496..611d65e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -28,7 +28,7 @@ This feedback will be shared with the template team to improve the cookiecutter **Name**: Python Libs **Description**: Shared Python libraries for ByronWilliamsCPA projects - JWT auth, GCS utilities, and more **Author**: Byron Williams -**Repository**: https://github.com/ByronWilliamsCPA/python-libs +**Repository**: **Created**: 2025-12-04 ### Technology Stack @@ -39,6 +39,7 @@ This feedback will be shared with the template team to improve the cookiecutter - **Testing**: pytest, coverage - **Security**: Bandit, Safety - **Documentation**: MkDocs Material + ---