django-cfg 1.4.46__py3-none-any.whl → 1.5.181__py3-none-any.whl

django_cfg/templates/unfold/layouts/skeleton.html

@@ -0,0 +1,27 @@
+{% extends "unfold/layouts/skeleton.html" %}
+
+{% block extrastyle %}
+{{ block.super }}
+<style id="django-cfg-theme-sync">
+/* ============================================== */
+/* Django CFG - Force Color Variables            */
+/* Ensures COLORS from get_color_scheme() apply  */
+/* ============================================== */
+
+/*
+ * NOTE: Colors are already defined via UNFOLD['COLORS'] in:
+ * django_cfg/modules/django_unfold/models/config.py:get_color_scheme()
+ *
+ * This CSS just ensures Tailwind classes use those variables correctly.
+ */
+
+/* Ensure color-scheme is set for proper dark mode rendering */
+html.dark {
+  color-scheme: dark;
+}
+
+html:not(.dark) {
+  color-scheme: light;
+}
+</style>
+{% endblock %}

django_cfg/templatetags/django_cfg.py

@@ -4,11 +4,65 @@ Django-CFG Template Tags
 Provides template tags for accessing django-cfg configuration constants.
 """
 
+import os
+import socket
 from django import template
+from django.conf import settings
+from django.utils.safestring import mark_safe
+from rest_framework_simplejwt.tokens import RefreshToken
 
 register = template.Library()
 
 
+def _is_port_available(host: str, port: int, timeout: float = 0.1, retries: int = 3, retry_delay: float = 0.05) -> bool:
+    """
+    Check if a port is available (listening) on the specified host with retry logic.
+
+    Performs multiple connection attempts with delays to handle dev servers
+    that may be compiling or starting up (e.g., Next.js first request).
+
+    Args:
+        host: Host to check (e.g., 'localhost', '127.0.0.1')
+        port: Port number to check
+        timeout: Connection timeout in seconds per attempt (default: 0.1s)
+        retries: Number of retry attempts (default: 3)
+        retry_delay: Delay between retries in seconds (default: 0.05s)
+
+    Returns:
+        bool: True if port is available, False otherwise
+
+    Example:
+        # Quick check (default): ~0.4s max (3 attempts × 0.1s + 2 × 0.05s delay)
+        _is_port_available('localhost', 3000)
+
+        # Patient check for slow servers
+        _is_port_available('localhost', 3000, timeout=0.5, retries=5)
+    """
+    import time
+
+    for attempt in range(retries):
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.settimeout(timeout)
+            result = sock.connect_ex((host, port))
+            sock.close()
+
+            if result == 0:
+                return True  # Success - port is available
+
+            # Port not available, retry if not last attempt
+            if attempt < retries - 1:
+                time.sleep(retry_delay)
+
+        except Exception:
+            # Connection error, retry if not last attempt
+            if attempt < retries - 1:
+                time.sleep(retry_delay)
+            continue
+
+    return False  # All retries failed
+
+
 @register.simple_tag
 def lib_name():
     """Get the library name."""
@@ -18,6 +72,38 @@ def lib_name():
     return f"{LIB_NAME} ({__version__})"
 
 
+@register.simple_tag
+def version_update_info():
+    """
+    Get version update information from PyPI.
+
+    Returns a dict with:
+    - current_version: installed version
+    - latest_version: latest on PyPI
+    - update_available: bool
+    - update_url: PyPI URL
+
+    Cached for 1 hour to avoid excessive API calls.
+
+    Usage in template:
+        {% load django_cfg %}
+        {% version_update_info as version %}
+        {% if version.update_available %}
+            Update: {{ version.current_version }} → {{ version.latest_version }}
+        {% endif %}
+    """
+    try:
+        from django_cfg.core.integration.version_checker import get_version_info
+        return get_version_info()
+    except Exception:
+        return {
+            'current_version': None,
+            'latest_version': None,
+            'update_available': False,
+            'update_url': None,
+        }
+
+
 @register.simple_tag
 def lib_site_url():
     """Get the library site URL."""
@@ -26,6 +112,14 @@ def lib_site_url():
     return LIB_SITE_URL
 
 
+@register.simple_tag
+def lib_docs_url():
+    """Get the library documentation URL."""
+    # Lazy import to avoid AppRegistryNotReady error
+    from django_cfg.config import LIB_SITE_URL
+    return LIB_SITE_URL
+
+
 @register.simple_tag
 def lib_health_url():
     """Get the library health URL."""
@@ -34,6 +128,28 @@ def lib_health_url():
     return LIB_HEALTH_URL
 
 
+@register.simple_tag
+def is_dev():
+    """
+    Check if project is in development mode.
+
+    Returns True if the current DjangoConfig has is_development = True.
+
+    Usage in template:
+        {% load django_cfg %}
+        {% is_dev as is_development %}
+        {% if is_development %}
+            <div>Development Mode</div>
+        {% endif %}
+    """
+    try:
+        from django_cfg.core.config import get_current_config
+        config = get_current_config()
+        return config and config.is_development
+    except Exception:
+        return False
+
+
 @register.simple_tag
 def lib_subtitle():
     """Get the library subtitle/tagline."""
@@ -54,3 +170,267 @@ def project_name():
 
     # Fallback to library name
     return LIB_NAME
+
+
+@register.simple_tag(takes_context=True)
+def user_jwt_token(context):
+    """
+    Generate JWT access token for the current authenticated user.
+
+    Returns JWT token that can be used for API authentication.
+    Uses Authorization: Bearer <token> header.
+
+    Usage in template:
+        {% load django_cfg %}
+        <script>
+            window.USER_JWT_TOKEN = '{% user_jwt_token %}';
+        </script>
+    """
+    request = context.get('request')
+    if not request or not request.user or not request.user.is_authenticated:
+        return ''
+
+    refresh = RefreshToken.for_user(request.user)
+    return str(refresh.access_token)
+
+
+@register.simple_tag(takes_context=True)
+def user_jwt_refresh_token(context):
+    """
+    Generate JWT refresh token for the current authenticated user.
+
+    Returns JWT refresh token that can be used to obtain new access tokens.
+
+    Usage in template:
+        {% load django_cfg %}
+        <script>
+            window.USER_JWT_REFRESH_TOKEN = '{% user_jwt_refresh_token %}';
+        </script>
+    """
+    request = context.get('request')
+    if not request or not request.user or not request.user.is_authenticated:
+        return ''
+
+    refresh = RefreshToken.for_user(request.user)
+    return str(refresh)
+
+
+@register.simple_tag(takes_context=True)
+def inject_jwt_tokens_script(context):
+    """
+    Generate complete script tag that injects JWT tokens into localStorage.
+
+    Automatically stores auth_token and refresh_token in localStorage
+    for the current authenticated user.
+
+    Usage in template (usually in <head> or before </body>):
+        {% load django_cfg %}
+        {% inject_jwt_tokens_script %}
+    """
+    request = context.get('request')
+    if not request or not request.user or not request.user.is_authenticated:
+        return ''
+
+    refresh = RefreshToken.for_user(request.user)
+    access_token = str(refresh.access_token)
+    refresh_token = str(refresh)
+
+    script = f"""<script>
+(function() {{
+    try {{
+        // Store JWT tokens in localStorage for Next.js app
+        localStorage.setItem('auth_token', '{access_token}');
+        localStorage.setItem('refresh_token', '{refresh_token}');
+    }} catch (e) {{
+        console.error('Failed to inject JWT tokens:', e);
+    }}
+}})();
+</script>"""
+    return mark_safe(script)
+
+
+@register.simple_tag
+def nextjs_admin_url(path=''):
+    """
+    Get the URL for Next.js Admin Panel (Built-in Dashboard - Tab 1).
+
+    In DEBUG mode, always returns dev server URL. Client-side JavaScript
+    will handle fallback to static files if dev server is unavailable.
+
+    Returns:
+        - DEBUG=True: http://localhost:3777/admin/{path}
+        - DEBUG=False: /cfg/admin/admin/{path}
+
+    Note: Port 3000 is reserved for external Next.js admin (Tab 2).
+    Both tabs use /admin route for consistency.
+
+    Usage in template:
+        {% load django_cfg %}
+        <iframe src="{% nextjs_admin_url %}"></iframe>
+        <iframe src="{% nextjs_admin_url 'crypto' %}"></iframe>
+    """
+    # Normalize path - remove leading/trailing slashes
+    path = path.strip('/')
+
+    if not settings.DEBUG:
+        # Production mode: always use static files with /admin route
+        return f'/cfg/admin/admin/{path}' if path else '/cfg/admin/admin/'
+
+    # Check if port 3777 is available for Tab 1 (built-in admin)
+    port_3777_available = _is_port_available('localhost', 3777)
+
+    if port_3777_available:
+        # Dev server is running on 3777 - use /admin route for consistency
+        base_url = 'http://localhost:3777/admin'
+        return f'{base_url}/{path}' if path else base_url
+    else:
+        # No dev server - use static files with /admin route
+        return f'/cfg/admin/admin/{path}' if path else '/cfg/admin/admin/'
+
+
+@register.simple_tag
+def is_frontend_dev_mode():
+    """
+    Check if frontend is in development mode.
+
+    Auto-detects by checking:
+        - DEBUG=True
+        - AND (port 3000 OR port 3777 is available)
+
+    Returns True if any Next.js dev server is detected.
+
+    Usage in template:
+        {% load django_cfg %}
+        {% if is_frontend_dev_mode %}
+            <div class="dev-badge">Dev Mode</div>
+        {% endif %}
+    """
+    if not settings.DEBUG:
+        return False
+
+    # Check if either dev server is running
+    return (_is_port_available('localhost', 3000) or
+            _is_port_available('localhost', 3777))
+
+
+@register.simple_tag
+def has_nextjs_external_admin():
+    """
+    Check if external Next.js admin is configured.
+
+    Returns True if NextJsAdminConfig is set in Django config.
+
+    Usage in template:
+        {% load django_cfg %}
+        {% has_nextjs_external_admin as is_enabled %}
+        {% if is_enabled %}
+            <div>External Next.js Admin Available</div>
+        {% endif %}
+    """
+    try:
+        from django_cfg.core.config import get_current_config
+        config = get_current_config()
+        return config and config.nextjs_admin is not None
+    except Exception:
+        return False
+
+
+@register.simple_tag
+def nextjs_external_admin_url(route=''):
+    """
+    Get URL for external Next.js admin (Tab 2 - solution project).
+
+    In DEBUG mode, always returns dev server URL. Client-side JavaScript
+    will handle fallback to static files if dev server is unavailable.
+
+    Returns:
+        - DEBUG=True: http://localhost:3000/admin/{route}
+        - DEBUG=False: /cfg/nextjs-admin/admin/{route}
+
+    This is for the external admin panel (solution project).
+
+    Usage in template:
+        {% load django_cfg %}
+        <iframe src="{% nextjs_external_admin_url %}"></iframe>
+        <iframe src="{% nextjs_external_admin_url 'dashboard' %}"></iframe>
+    """
+    try:
+        from django_cfg.core.config import get_current_config
+
+        config = get_current_config()
+        if not config or not config.nextjs_admin:
+            return ''
+
+        route = route.strip('/')
+
+        # Auto-detect development mode: DEBUG=True + port 3000 available
+        if settings.DEBUG and _is_port_available('localhost', 3000):
+            # Development mode: solution project on port 3000
+            # Routes start with /admin in Next.js (e.g., /admin, /admin/crypto)
+            base_url = 'http://localhost:3000/admin'
+            return f'{base_url}/{route}' if route else base_url
+        else:
+            # Production mode: use relative URL - Django serves from extracted ZIP with /admin prefix
+            return f"/cfg/nextjs-admin/admin/{route}" if route else "/cfg/nextjs-admin/admin/"
+    except Exception:
+        return ''
+
+
+@register.simple_tag
+def nextjs_external_admin_title():
+    """
+    Get tab title for external Next.js admin.
+
+    Returns custom title from config or default "Next.js Admin".
+
+    Usage in template:
+        {% load django_cfg %}
+        <button>{% nextjs_external_admin_title %}</button>
+    """
+    try:
+        from django_cfg.core.config import get_current_config
+        config = get_current_config()
+        if not config or not config.nextjs_admin:
+            return 'Next.js Admin'
+        return config.nextjs_admin.get_tab_title()
+    except Exception:
+        return 'Next.js Admin'
+
+
+@register.simple_tag(takes_context=True)
+def generate_jwt_tokens(context):
+    """
+    Generate JWT tokens for the current authenticated user.
+
+    Returns a dict with 'access' and 'refresh' tokens for use in templates.
+
+    Usage:
+        {% load django_cfg %}
+        {% generate_jwt_tokens as jwt_tokens %}
+        localStorage.setItem('auth_token', '{{ jwt_tokens.access }}');
+        localStorage.setItem('refresh_token', '{{ jwt_tokens.refresh }}');
+    """
+    from django.contrib.auth.models import AnonymousUser
+
+    request = context.get('request')
+    if not request:
+        return {'access': '', 'refresh': ''}
+
+    user = getattr(request, 'user', None)
+    if not user or isinstance(user, AnonymousUser) or not user.is_authenticated:
+        return {'access': '', 'refresh': ''}
+
+    try:
+        # Generate tokens for the authenticated user
+        refresh = RefreshToken.for_user(user)
+        access_token = str(refresh.access_token)
+        refresh_token = str(refresh)
+
+        return {
+            'access': access_token,
+            'refresh': refresh_token
+        }
+    except ImportError:
+        return {'access': '', 'refresh': ''}
+    except Exception as e:
+        return {'access': '', 'refresh': ''}

django_cfg/testing/README.md

@@ -0,0 +1,278 @@
+# Zero-Config Test Database Management
+
+## Overview
+
+Django-cfg now provides **zero-configuration** test database management. No setup needed - everything works automatically!
+
+## Features
+
+### ✅ Automatic Test Database Cleanup
+- Automatically removes conflicting test databases
+- No more `EOFError` in CI/CD pipelines
+- No interactive prompts during testing
+
+### ✅ PostgreSQL Extension Auto-Installation
+- Automatically installs `pgvector`, `pg_trgm`, `unaccent`
+- Detects extensions needed by scanning migrations
+- Works in test databases without manual configuration
+
+### ✅ Smart Database Selection
+- PostgreSQL for integration tests
+- SQLite for fast unit tests (optional)
+- Automatic TEST settings for all databases
+
+## Usage
+
+### Zero Configuration (Recommended)
+
+Just run your tests - everything is automatic:
+
+```bash
+python manage.py test
+```
+
+**That's it!** Django-cfg automatically:
+1. ✅ Detects you're running tests
+2. ✅ Removes old test database (`test_cmdop`) without confirmation
+3. ✅ Creates fresh test database
+4. ✅ Installs PostgreSQL extensions (pgvector, pg_trgm, etc.)
+5. ✅ Applies migrations in correct order
+6. ✅ Runs your tests
+7. ✅ Cleans up afterward
+
+### Fast Testing with SQLite
+
+For faster unit tests, use the FastTestRunner:
+
+```bash
+python manage.py test --testrunner=django_cfg.testing.runners.FastTestRunner
+```
+
+This automatically switches all databases to SQLite in-memory for maximum speed.
+
+## How It Works
+
+### 1. Automatic TEST Settings
+
+Django-cfg automatically generates TEST settings for each database:
+
+```python
+# In your config.py - NO changes needed!
+class MyConfig(DjangoConfig):
+    project_name = "cmdop"
+    databases = {
+        "default": DatabaseConfig.from_url(
+            "postgresql://user:pass@localhost/cmdop"
+        )
+    }
+    # That's all! Testing configuration is automatic.
+```
+
+Behind the scenes, django-cfg generates:
+
+```python
+DATABASES = {
+    'default': {
+        'ENGINE': 'django.db.backends.postgresql',
+        'NAME': 'cmdop',
+        # ... connection settings ...
+
+        # 🔥 Automatically added by django-cfg
+        'TEST': {
+            'NAME': 'test_cmdop',
+            'TEMPLATE': 'template0',  # Clean template without old data
+            'CHARSET': 'UTF8',
+            'CREATE_DB': True,
+            'MIGRATE': True,
+        }
+    }
+}
+
+# 🔥 Automatically set by django-cfg
+TEST_RUNNER = 'django_cfg.testing.runners.SmartTestRunner'
+```
+
+### 2. SmartTestRunner
+
+The `SmartTestRunner` automatically:
+
+#### Step 1: Cleanup Old Test Databases
+```python
+# Automatically executed before creating test database
+def _cleanup_old_test_databases(self):
+    # Check if test database exists
+    if test_database_exists('test_cmdop'):
+        # Terminate all connections
+        # Drop database WITHOUT confirmation
+        drop_database('test_cmdop')  # No EOFError!
+```
+
+#### Step 2: Install PostgreSQL Extensions
+```python
+# Automatically executed after creating test database
+def _install_extensions(self):
+    # Scan migrations for extension usage
+    if needs_pgvector():
+        # Install extensions in test database
+        CREATE EXTENSION IF NOT EXISTS vector;
+        CREATE EXTENSION IF NOT EXISTS pg_trgm;
+        CREATE EXTENSION IF NOT EXISTS unaccent;
+```
+
+### 3. What Gets Fixed
+
+#### Problem 1: EOFError in CI
+**Before:**
+```
+Got an error creating the test database: database "test_cmdop" already exists
+
+Type 'yes' if you would like to try deleting the test database 'test_cmdop', or 'no' to cancel:
+EOFError  # ← Fails in CI because no stdin!
+```
+
+**After:**
+```
+✅ Removed old test database: test_cmdop
+Creating test database for alias 'default'...
+```
+
+#### Problem 2: Missing Extensions
+**Before:**
+```
+django.db.utils.ProgrammingError: type "vector" does not exist
+```
+
+**After:**
+```
+✅ Installed PostgreSQL extensions for test database 'default'
+```
+
+#### Problem 3: Inconsistent Migration History
+**Before:**
+```
+Inconsistent migration history
+ai_chat.0001_initial applied before workspaces.0002_alter_workspacemember_options
+```
+
+**After:**
+```
+✅ Removed old test database: test_cmdop  # Fresh start!
+Running migrations...
+  Applying workspaces.0002_alter_workspacemember_options... OK
+  Applying ai_chat.0001_initial... OK
+```
+
+## Advanced Usage
+
+### Manual Test Runner Selection
+
+#### Smart Test Runner (Default)
+```bash
+python manage.py test --testrunner=django_cfg.testing.runners.SmartTestRunner
+```
+- Auto-cleanup old test databases
+- PostgreSQL extension installation
+- Full database feature support
+
+#### Fast Test Runner
+```bash
+python manage.py test --testrunner=django_cfg.testing.runners.FastTestRunner
+```
+- Switches all databases to SQLite in-memory
+- 10x faster for unit tests
+- No PostgreSQL features
+
+### Importing Test Runners
+
+```python
+# Lazy import (recommended)
+from django_cfg import SmartTestRunner, FastTestRunner
+
+# Direct import
+from django_cfg.testing.runners import SmartTestRunner, FastTestRunner
+
+# In settings.py (if not using django-cfg config)
+TEST_RUNNER = 'django_cfg.testing.runners.SmartTestRunner'
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+```yaml
+- name: Run Tests
+  run: python manage.py test
+  # No special configuration needed!
+  # SmartTestRunner handles everything automatically
+```
+
+### GitLab CI
+```yaml
+test:
+  script:
+    - python manage.py test
+  # Works out of the box!
+```
+
+### Docker
+```dockerfile
+# No changes needed to Dockerfile
+RUN python manage.py test
+```
+
+## Troubleshooting
+
+### Extensions Not Installing?
+
+Check if pgvector is installed on your system:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install postgresql-15-pgvector
+
+# macOS
+brew install pgvector
+```
+
+### Want More Verbosity?
+
+```bash
+python manage.py test --verbosity=2
+```
+
+Output:
+```
+✅ Removed old test database: test_cmdop
+Creating test database for alias 'default'...
+✅ Installed PostgreSQL extensions for test database 'default'
+...
+```
+
+### Disable Auto-Cleanup (Not Recommended)
+
+If you really need to keep the test database:
+
+```python
+# Custom test runner
+from django_cfg.testing.runners import SmartTestRunner
+
+class MyTestRunner(SmartTestRunner):
+    def _cleanup_old_test_databases(self):
+        pass  # Skip cleanup
+```
+
+## Summary
+
+**User does:**
+```bash
+python manage.py test
+```
+
+**Django-cfg does automatically:**
+1. ✅ Remove old test database (no confirmation)
+2. ✅ Create fresh test database
+3. ✅ Install PostgreSQL extensions
+4. ✅ Apply migrations correctly
+5. ✅ Run tests
+6. ✅ Clean up
+
+**Zero configuration. Just works.** 🚀