feat(gemini-image): v0.2.0 major refactor with modular architecture

.qlty/qlty.toml

@@ -42,6 +42,31 @@ test_patterns = [
     "**/*.spec.*",
 ]
 
+# ============================================================================
+# Issue Triage - Rule-level Ignores
+# ============================================================================
+# Ignore Bandit B101 (assert_used) in test files - pytest uses assert statements
+[[triage]]
+match.plugins = ["bandit"]
+match.rules = ["bandit:B101"]
+match.file_patterns = [
+    "**/tests/**",
+    "**/test_*.py",
+    "**/*_test.py",
+]
+set.ignored = true
+
+# Ignore Bandit B108 (hardcoded_tmp_directory) in test files - test fixtures use /tmp
+[[triage]]
+match.plugins = ["bandit"]
+match.rules = ["bandit:B108"]
+match.file_patterns = [
+    "**/tests/**",
+    "**/test_*.py",
+    "**/*_test.py",
+]
+set.ignored = true
+
 # Default source for plugin definitions
 [[source]]
 name = "default"
@@ -72,17 +97,8 @@ default = true
 [smells]
 # Mode: comment (add PR comments) vs block (fail CI)
 mode = "comment"
-
-# Ignore complexity warnings for files with documented intentional complexity
-[[smells.ignore]]
-rules = [
-    "function-complexity",
-    "function-parameters",
-    "nested-control-flow",
-]
-file_patterns = [
-    "**/gemini_image/generator.py",
-]
+# Note: Complexity warnings for gemini_image/generator.py are intentional
+# and documented in the file header. Use exclude_patterns at top level if needed.
 
 # Boolean logic complexity
 [smells.boolean_logic]
@@ -145,15 +161,6 @@ drivers = ["lint"]
 name = "bandit"
 mode = "comment"
 
-# Ignore B101 (assert_used) in test files - pytest uses assert statements
-[[plugin.ignore]]
-rule = "bandit:B101"
-file_patterns = [
-    "**/tests/**",
-    "**/test_*.py",
-    "**/*_test.py",
-]
-
 # Shell script linting (comment mode - script styling preferences)
 [[plugin]]
 name = "shellcheck"

FIXES_NEEDED.md

@@ -0,0 +1,235 @@
+# python-libs cloudflare-auth Package Fixes Needed
+
+**Status**: Critical - Package cannot be used as a dependency
+**Discovered**: 2025-12-06 during homelab-infra migration
+**Reporter**: Claude Code (via ByronWilliams)
+
+---
+
+## Summary
+
+The `byronwilliamscpa-cloudflare-auth` package has broken imports that prevent it from being used
+as a dependency in other projects. This violates the core purpose of python-libs as a shared
+library repository.
+
+## Issues Found
+
+### 1. ✅ FIXED LOCALLY: Incorrect Import Statements (21+ occurrences)
+
+**Problem**: Module imports use `src.cloudflare_auth` instead of `cloudflare_auth`
+
+**Status**: Fixed locally in this clone (not committed)
+
+**Files Affected**:
+- `packages/cloudflare-auth/src/cloudflare_auth/__init__.py`
+- `packages/cloudflare-auth/src/cloudflare_auth/middleware.py`
+- `packages/cloudflare-auth/src/cloudflare_auth/middleware_enhanced.py`
+- `packages/cloudflare-auth/src/cloudflare_auth/validators.py`
+- `packages/cloudflare-auth/src/cloudflare_auth/redis_sessions.py`
+- And potentially others
+
+**Example**:
+
+```python
+# Incorrect (current in repo)
+from src.cloudflare_auth.models import CloudflareUser
+from src.cloudflare_auth.middleware import CloudflareAuthMiddleware
+
+# Correct (fixed locally)
+from cloudflare_auth.models import CloudflareUser
+from cloudflare_auth.middleware import CloudflareAuthMiddleware
+```
+
+**Fix Applied**:
+
+```bash
+cd packages/cloudflare-auth
+find src -name "*.py" -exec sed -i 's/from src\.cloudflare_auth/from cloudflare_auth/g' {} \;
+find src -name "*.py" -exec sed -i 's/import src\.cloudflare_auth/import cloudflare_auth/g' {} \;
+```
+
+---
+
+### 2. ❌ NOT FIXED: Missing CloudflareSettings Module
+
+**Problem**: Multiple files import from non-existent `src.config.settings` module
+
+**Files Affected**:
+- `packages/cloudflare-auth/src/cloudflare_auth/validators.py:40`
+- `packages/cloudflare-auth/src/cloudflare_auth/middleware.py`
+- `packages/cloudflare-auth/src/cloudflare_auth/middleware_enhanced.py`
+
+**Import Statement**:
+
+```python
+from src.config.settings import CloudflareSettings, get_cloudflare_settings
+```
+
+**Problem**: This module doesn't exist in the cloudflare-auth package
+
+**Options for Resolution**:
+
+#### Option A: Create CloudflareSettings within package (RECOMMENDED)
+
+```python
+# packages/cloudflare-auth/src/cloudflare_auth/settings.py
+from pydantic_settings import BaseSettings
+
+class CloudflareSettings(BaseSettings):
+    """Cloudflare Access configuration settings."""
+
+    cloudflare_team_domain: str
+    cloudflare_audience_tag: str
+    cloudflare_enabled: bool = True
+    service_token_enabled: bool = False
+    # ... other settings
+
+    class Config:
+        env_file = ".env"
+
+def get_cloudflare_settings() -> CloudflareSettings:
+    """Get singleton CloudflareSettings instance."""
+    return CloudflareSettings()
+```
+
+Then update imports:
+
+```python
+# In validators.py, middleware.py, middleware_enhanced.py
+from cloudflare_auth.settings import CloudflareSettings, get_cloudflare_settings
+```
+
+#### Option B: Make settings injectable (alternative)
+
+Remove direct settings import and require settings to be passed as parameters:
+
+```python
+# In validators.py
+class CloudflareJWTValidator:
+    def __init__(self, team_domain: str, audience_tag: str):
+        self.team_domain = team_domain
+        self.audience_tag = audience_tag
+```
+
+**Recommendation**: Option A is preferred for backward compatibility and ease of use.
+
+---
+
+## Root Cause
+
+The package appears to have been copied from a different project structure where it was nested under `src/` with a separate `src/config/` module. When moved to the python-libs monorepo structure, imports were not updated to reflect the new package structure.
+
+---
+
+## Impact
+
+**Current State**:
+- ❌ Package cannot be imported: `ModuleNotFoundError: No module named 'src.config'`
+- ❌ Cannot be used as a dependency in other projects
+- ❌ Forces code duplication instead of reuse
+- ❌ Violates the stated purpose of python-libs repository
+
+**Blocked Projects**:
+- homelab-infra (PR #54) - waiting for these fixes before tests can run
+
+---
+
+## Action Items
+
+### Immediate (Required for PR #54)
+
+1. **Commit local import fixes**:
+
+   ```bash
+   cd packages/cloudflare-auth
+   git add src/cloudflare_auth/*.py
+   git commit -m "fix: correct all module imports from src.cloudflare_auth to cloudflare_auth"
+   ```
+
+2. **Create CloudflareSettings module**:
+   - Create `src/cloudflare_auth/settings.py`
+   - Define `CloudflareSettings` and `get_cloudflare_settings`
+   - Update imports in affected files
+   - Test imports work correctly
+
+3. **Add import tests**:
+
+   ```python
+   # tests/test_imports.py
+   def test_public_imports():
+       """Verify all public imports work correctly."""
+       from cloudflare_auth import (
+           CloudflareAuthMiddleware,
+           CloudflareUser,
+           setup_cloudflare_auth_enhanced,
+       )
+       assert CloudflareAuthMiddleware is not None
+   ```
+
+4. **Add CI check**:
+
+   ```yaml
+   # .github/workflows/ci.yml
+   - name: Test package imports
+     run: |
+       uv run python -c "from cloudflare_auth import CloudflareUser"
+   ```
+
+### Follow-up (Before PyPI Publication)
+
+5. **Publish to PyPI**:
+   - Once fixes are complete and tests pass
+   - Follow semantic versioning (v0.1.1 for patch)
+   - Update homelab-infra to use PyPI package instead of path dependency
+
+6. **Update template**:
+   - Add import tests to cookiecutter-python-template
+   - Ensure packages in workspace members have validated imports
+
+---
+
+## Files Changed Locally (Not Committed)
+
+All files in `packages/cloudflare-auth/src/cloudflare_auth/`:
+- `__init__.py` - Fixed imports and docstring
+- `middleware.py` - Fixed imports
+- `middleware_enhanced.py` - Fixed imports
+- `validators.py` - Fixed imports
+- `security_helpers.py` - Fixed imports
+- `sessions.py` - Fixed imports
+- `utils.py` - Fixed imports
+- `whitelist.py` - Fixed imports
+- `models.py` - Fixed imports
+- `csrf.py` - Fixed imports
+- `rate_limiter.py` - Fixed imports
+- `redis_sessions.py` - Fixed imports
+
+---
+
+## Testing Verification
+
+After fixes are applied, verify with:
+
+```bash
+# 1. Clean install test
+cd /tmp
+uv venv test-env
+source test-env/bin/activate
+uv pip install /path/to/python-libs/packages/cloudflare-auth
+
+# 2. Import test
+python -c "from cloudflare_auth import CloudflareUser, setup_cloudflare_auth_enhanced"
+
+# 3. Run package tests
+cd /path/to/python-libs/packages/cloudflare-auth
+uv run pytest tests/ -v
+```
+
+---
+
+## Contact
+
+For questions or to coordinate fixes:
+- **Project**: homelab-infra (blocked PR #54)
+- **Reporter**: Claude Code
+- **Related**: [homelab-infra PR #54](https://github.com/ByronWilliamsCPA/homelab-infra/pull/54)

REUSE.toml

@@ -14,6 +14,7 @@ path = [
     "src/**",
     "packages/**/src/**/*.py",
     "packages/**/tests/**/*.py",
+    "packages/**/scripts/**/*.py",
     "tools/**",
     "tests/**",
     "validation/**",