django-cfg 1.4.101__py3-none-any.whl → 1.4.103__py3-none-any.whl

django_cfg/__init__.py

@@ -32,7 +32,7 @@ Example:
 default_app_config = "django_cfg.apps.DjangoCfgConfig"
 
 # Version information
-__version__ = "1.4.101"
+__version__ = "1.4.103"
 __license__ = "MIT"
 
 # Import registry for organized lazy loading

django_cfg/models/django/crypto_fields.py

@@ -61,7 +61,11 @@ class CryptoFieldsConfig(BaseModel):
     # === Django Revision Settings (for django-audit-fields dependency) ===
     ignore_git_dir: bool = Field(
         default=True,
-        description="Ignore git directory for django-revision (set DJANGO_REVISION_IGNORE_WORKING_DIR=True)"
+        description=(
+            "Ignore git directory for django-revision. "
+            "When True, version is discovered from: package metadata → pyproject.toml → VERSION file. "
+            "Prevents 'not recommended' warning from settings.REVISION fallback."
+        )
     )
 
     def to_django_settings(self, base_dir: Path, is_production: bool, debug: bool) -> dict:
@@ -108,13 +112,52 @@ class CryptoFieldsConfig(BaseModel):
         }
 
         # Disable django-revision git integration (required by django-audit-fields)
-        # RevisionField will use package metadata or pyproject.toml instead
+        # RevisionField will use package metadata, pyproject.toml, or VERSION file instead
         if self.ignore_git_dir:
             settings["DJANGO_REVISION_IGNORE_WORKING_DIR"] = True
-            # Completely disable django-revision metadata checks to avoid errors
-            settings["DJANGO_REVISION_IGNORE_METADATA"] = True
-            # Set static revision to satisfy django-revision requirements
-            settings["REVISION"] = "1.0.0"
+            # Allow django-revision to discover version from:
+            # 1. Package metadata (version())
+            # 2. pyproject.toml [project][version]
+            # 3. VERSION file (BASE_DIR/VERSION)
+            # Do NOT set REVISION here to avoid "not recommended" warning
+
+            # Create VERSION file if it doesn't exist (prevents fallback to settings.REVISION)
+            version_file = base_dir / "VERSION"
+            if not version_file.exists():
+                try:
+                    # Try to get version from pyproject.toml or package metadata
+                    version_to_write = "1.0.0"  # Default fallback
+
+                    # Try pyproject.toml first
+                    pyproject_file = base_dir / "pyproject.toml"
+                    if pyproject_file.exists():
+                        try:
+                            import tomllib
+                        except ImportError:
+                            # Python < 3.11
+                            try:
+                                import tomli as tomllib  # type: ignore
+                            except ImportError:
+                                tomllib = None  # type: ignore
+
+                        if tomllib:
+                            try:
+                                with open(pyproject_file, "rb") as f:
+                                    pyproject_data = tomllib.load(f)
+                                    version_to_write = pyproject_data.get("project", {}).get("version", version_to_write)
+                            except Exception:
+                                pass  # Use default version
+
+                    # Write VERSION file
+                    version_file.write_text(version_to_write + "\n")
+
+                    import logging
+                    logger = logging.getLogger(__name__)
+                    logger.info(f"Created VERSION file at {version_file} with version {version_to_write}")
+                except Exception as e:
+                    import logging
+                    logger = logging.getLogger(__name__)
+                    logger.warning(f"Could not create VERSION file: {e}")
 
         return settings
 

django_cfg/modules/django_client/management/commands/generate_client.py

@@ -673,7 +673,11 @@ class Command(BaseCommand):
                         ))
 
                         # Create ZIP archive for Django static (Docker-ready)
-                        django_static_zip = base_dir / "static" / "nextjs_admin.zip"
+                        # Use solution project's BASE_DIR from Django settings
+                        from django.conf import settings as django_settings
+                        solution_base_dir = django_settings.BASE_DIR
+
+                        django_static_zip = nextjs_config.get_static_zip_path(solution_base_dir)
 
                         try:
                             # Ensure static directory exists
@@ -707,11 +711,14 @@ class Command(BaseCommand):
                             # Get ZIP size
                             zip_size_mb = django_static_zip.stat().st_size / (1024 * 1024)
 
+                            # Show relative path from solution BASE_DIR
+                            relative_zip_path = django_static_zip.relative_to(solution_base_dir)
+
                             self.stdout.write(self.style.SUCCESS(
-                                f"   ✅ Created ZIP archive: {django_static_zip.relative_to(base_dir)} ({zip_size_mb:.1f}MB)"
+                                f"   ✅ Created ZIP archive: {relative_zip_path} ({zip_size_mb:.1f}MB)"
                             ))
                             self.stdout.write(self.style.SUCCESS(
-                                f"   📍 ZIP location: {django_static_zip.relative_to(base_dir)}"
+                                f"   📍 ZIP location: {django_static_zip}"
                             ))
                             self.stdout.write(self.style.SUCCESS(
                                 "   ℹ️  This ZIP is used by NextJsAdminView (Tab 2: External Admin)"
@@ -729,17 +736,30 @@ class Command(BaseCommand):
                     self.stdout.write(self.style.ERROR(
                         f"\n❌ Next.js build failed with exit code {result.returncode}"
                     ))
+
+                    # Show full error output
                     if result.stderr:
-                        self.stdout.write(self.style.ERROR(f"   Error: {result.stderr[:500]}"))
+                        self.stdout.write(self.style.ERROR(f"\n   stderr:\n{result.stderr}"))
+                    if result.stdout:
+                        self.stdout.write(self.style.ERROR(f"\n   stdout:\n{result.stdout}"))
+
+                    # Exit on build failure
+                    raise CommandError(
+                        f"Next.js build failed with exit code {result.returncode}. "
+                        "Fix the build errors and try again."
+                    )
 
             except subprocess.TimeoutExpired:
                 self.stdout.write(self.style.ERROR(
                     "\n❌ Next.js build timed out (5 minutes)"
                 ))
+                raise CommandError("Next.js build timed out after 5 minutes")
+
             except Exception as build_error:
                 self.stdout.write(self.style.ERROR(
                     f"\n❌ Build command failed: {build_error}"
                 ))
+                raise CommandError(f"Next.js build command failed: {build_error}")
 
         except Exception as e:
             self.stdout.write(self.style.ERROR(f"\n❌ Failed to build Next.js admin: {e}"))

django_cfg/modules/nextjs_admin/models/config.py

@@ -165,6 +165,19 @@ class NextJsAdminConfig(BaseModel):
         """Get tab title with default."""
         return self.tab_title or "Next.js Admin"
 
+    def get_static_zip_path(self, solution_base_dir):
+        """
+        Get path to nextjs_admin.zip for Django static serving.
+
+        Args:
+            solution_base_dir: Solution project BASE_DIR (from settings.BASE_DIR)
+
+        Returns:
+            Path: Path to nextjs_admin.zip (e.g., solution/projects/django/static/nextjs_admin.zip)
+        """
+        from pathlib import Path
+        return Path(solution_base_dir) / "static" / "nextjs_admin.zip"
+
     # =================================================================
     # Validators
     # =================================================================

django_cfg/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "django-cfg"
-version = "1.4.101"
+version = "1.4.103"
 description = "Modern Django framework with type-safe Pydantic v2 configuration, Next.js admin integration, real-time WebSockets, and 8 enterprise apps. Replace settings.py with validated models, 90% less code. Production-ready with AI agents, auto-generated TypeScript clients, and zero-config features."
 readme = "README.md"
 keywords = [ "django", "configuration", "pydantic", "settings", "type-safety", "pydantic-settings", "django-environ", "startup-validation", "ide-autocomplete", "nextjs-admin", "react-admin", "websocket", "centrifugo", "real-time", "typescript-generation", "ai-agents", "enterprise-django", "django-settings", "type-safe-config", "modern-django",]

django_cfg/templates/admin/DUAL_TAB_ARCHITECTURE.md

@@ -0,0 +1,504 @@
+# Dual-Tab Admin Architecture
+
+This document explains the architecture and logic behind Django-CFG's dual-tab admin interface, which allows seamless integration of both built-in and external Next.js admin panels.
+
+## Overview
+
+Django-CFG admin interface supports **two independent Next.js admin panels** running side-by-side in separate tabs:
+
+1. **Tab 1: Built-in Dashboard** - The default Next.js admin panel shipped with Django-CFG
+2. **Tab 2: External Next.js Admin** - A custom Next.js admin panel from your solution project
+
+Each tab operates independently with its own:
+- Development server port
+- Static file serving path
+- Fallback mechanism
+- iframe communication channel
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Django Admin Interface                      │
+│  ┌───────────────────────────────┬───────────────────────────┐  │
+│  │   Tab 1: Built-in Dashboard   │  Tab 2: External Admin    │  │
+│  └───────────────────────────────┴───────────────────────────┘  │
+│                                                                  │
+│  Dev Mode:                      │  Dev Mode:                    │
+│  ↓ http://localhost:3777/admin  │  ↓ http://localhost:3000/admin│
+│                                                                  │
+│  Fallback (Static):             │  Fallback (Static):           │
+│  ↓ /cfg/admin/admin/            │  ↓ /cfg/nextjs-admin/admin/   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Port Allocation
+
+| Tab | Purpose | Dev Port | Static Path |
+|-----|---------|----------|-------------|
+| Tab 1 | Built-in Dashboard | `3777` | `/cfg/admin/admin/` |
+| Tab 2 | External Next.js Admin | `3000` | `/cfg/nextjs-admin/admin/` |
+
+### Why Different Ports?
+
+Using separate ports prevents conflicts and allows both dev servers to run simultaneously:
+- **Port 3777**: Reserved for Django-CFG's built-in admin panel
+- **Port 3000**: Reserved for solution project's custom admin panel
+
+## URL Resolution Logic
+
+### Development Mode (DEBUG=True)
+
+**Server-Side (Python)**: Always returns dev server URLs in DEBUG mode:
+
+```python
+def nextjs_admin_url(path=''):
+    """Built-in Dashboard (Tab 1)"""
+    if settings.DEBUG:
+        return f'http://localhost:3777/admin/{path}'
+    else:
+        return f'/cfg/admin/admin/{path}'
+
+def nextjs_external_admin_url(route=''):
+    """External Next.js Admin (Tab 2)"""
+    if settings.DEBUG:
+        return f'http://localhost:3000/admin/{route}'
+    else:
+        return f'/cfg/nextjs-admin/admin/{route}'
+```
+
+**Client-Side (JavaScript)**: Verifies dev server availability before loading iframe:
+
+```javascript
+async function checkDevServerAvailable(url, retries = 3, timeout = 1000) {
+    // Tries to fetch dev server with exponential backoff
+    // - Attempt 1: immediate
+    // - Attempt 2: +500ms delay
+    // - Attempt 3: +1000ms delay
+    // Total max: ~3.5s
+}
+```
+
+**Why client-side checking?**
+- Dev servers may be compiling on first request (cold start)
+- Browser can handle CORS/network errors better than server-side sockets
+- Allows retry with exponential backoff for slow Next.js compilation
+- No server-side blocking during HTML rendering
+
+### Production Mode (DEBUG=False)
+
+In production, both tabs serve static files:
+- Tab 1: Serves from `/cfg/admin/admin/` (built-in static files)
+- Tab 2: Serves from `/cfg/nextjs-admin/admin/` (extracted from ZIP)
+
+## Fallback Mechanism
+
+Each iframe implements a smart fallback strategy when dev servers are unavailable:
+
+```javascript
+function handleLoadFailure() {
+    if (!isDevMode) return; // Already using static files
+
+    const originalSrc = iframe.getAttribute('data-original-src');
+    const devUrl = new URL(originalSrc);
+    const pathPart = devUrl.pathname.replace('/admin', '');
+
+    // Determine correct fallback based on iframe ID
+    let staticUrl;
+    if (iframe.id === 'nextjs-dashboard-iframe-builtin') {
+        staticUrl = `/cfg/admin/admin/${pathPart}`;
+    } else if (iframe.id === 'nextjs-dashboard-iframe-nextjs') {
+        staticUrl = `/cfg/nextjs-admin/admin/${pathPart}`;
+    }
+
+    iframe.src = staticUrl;
+}
+```
+
+### Fallback Triggers
+
+1. **Timeout**: 3 seconds without successful load
+2. **Error Event**: iframe fails to load (network error, server down)
+3. **Manual**: Dev server stopped during development
+
+## iframe Communication
+
+Each iframe maintains its own communication channel with the parent window using `postMessage`.
+
+### Origin Detection
+
+```javascript
+// Get origin from data-original-src (not iframe.src, which may change)
+const iframeSrc = iframe.getAttribute('data-original-src');
+const iframeUrl = new URL(iframeSrc, window.location.origin);
+const iframeOrigin = iframeUrl.origin;
+```
+
+**Why `data-original-src`?**
+The `iframe.src` attribute may be changed by the fallback mechanism, so we use `data-original-src` to maintain the original intended origin for `postMessage` communication.
+
+### Message Types
+
+| Message Type | Direction | Purpose |
+|--------------|-----------|---------|
+| `parent-theme` | Parent → iframe | Sync theme (dark/light mode) |
+| `parent-auth` | Parent → iframe | Inject JWT tokens |
+| `iframe-ready` | iframe → Parent | iframe loaded and ready |
+| `iframe-resize` | iframe → Parent | Update iframe height |
+| `iframe-navigation` | iframe → Parent | Route change notification |
+| `iframe-auth-status` | iframe → Parent | Authentication status |
+
+## Tab Switching & State Reset
+
+### Reset Logic
+
+When switching tabs, the **previous** tab's iframe is reset to its initial URL:
+
+```javascript
+switchTab(tab) {
+    if (this.previousTab !== tab) {
+        // Reset iframe that was just hidden
+        this.resetIframe(this.previousTab);
+        this.previousTab = tab;
+    }
+    this.activeTab = tab;
+}
+
+resetIframe(tab) {
+    const iframeId = tab === 'builtin'
+        ? 'nextjs-dashboard-iframe-builtin'
+        : 'nextjs-dashboard-iframe-nextjs';
+    const iframe = document.getElementById(iframeId);
+
+    if (iframe) {
+        const originalSrc = iframe.getAttribute('data-original-src');
+        iframe.src = originalSrc; // Reset to initial URL
+    }
+}
+```
+
+**Why Reset?**
+This ensures that when users switch back to a tab, it starts from the home page rather than whatever route they navigated to previously.
+
+## Static File Serving
+
+### Built-in Admin (Tab 1)
+
+**Location**: `django_cfg/static/frontend/admin/`
+
+**Serving**:
+- Development: `http://localhost:3777/admin`
+- Production: `/cfg/admin/admin/` (Django `staticfiles`)
+
+### External Admin (Tab 2)
+
+**Source**: `{solution_project}/static/nextjs_admin.zip`
+
+**Extraction**:
+```python
+# Target directory
+base_dir = Path(settings.BASE_DIR) / 'static' / 'nextjs_admin'
+
+# ZIP with metadata tracking
+zip_path = Path(settings.BASE_DIR) / 'static' / 'nextjs_admin.zip'
+
+# Automatic extraction with metadata comparison
+extract_zip_if_needed(base_dir, zip_path, 'nextjs_admin')
+```
+
+**Serving**:
+- Development: `http://localhost:3000/admin`
+- Production: `/cfg/nextjs-admin/admin/` (Django serves extracted files)
+
+### ZIP Extraction Logic
+
+The system uses a **metadata marker file** (`.zip_meta`) to track ZIP state:
+
+```python
+# Metadata format: {size}:{mtime}
+current_meta = f"{zip_stat.st_size}:{zip_stat.st_mtime}"
+
+# Extraction triggers:
+# 1. Directory doesn't exist → Extract
+# 2. Marker file missing → Extract
+# 3. ZIP metadata changed → Re-extract
+# 4. Metadata matches → Use existing
+```
+
+**Why Metadata Comparison?**
+More reliable than timestamp-only comparison, especially in Docker environments where file timestamps can be misleading.
+
+## JWT Token Injection
+
+Both tabs receive JWT tokens automatically for authenticated users:
+
+```javascript
+// Inject tokens into localStorage
+localStorage.setItem('auth_token', '{access_token}');
+localStorage.setItem('refresh_token', '{refresh_token}');
+```
+
+### Injection Strategy
+
+1. **Server-Side**: Tokens injected into HTML response (see `views.py`)
+2. **Client-Side**: Tokens sent via `postMessage` after iframe loads
+3. **Storage**: Tokens stored in `localStorage` for Next.js apps
+
+### Cache Control
+
+HTML responses have aggressive cache-busting headers to ensure fresh token injection:
+
+```python
+response['Cache-Control'] = 'no-store, no-cache, must-revalidate, max-age=0'
+response['Pragma'] = 'no-cache'
+response['Expires'] = '0'
+```
+
+## Configuration
+
+### Django Config (solution project)
+
+```python
+from django_cfg import NextJsAdminConfig
+
+config = DjangoConfig(
+    nextjs_admin=NextJsAdminConfig(
+        project_path="../django_admin/apps/admin",
+        api_output_path="src/api/generated",
+        auto_build=True,
+        # Optional overrides:
+        # static_url="/cfg/nextjs-admin/",
+        # dev_url="http://localhost:3000",
+        # tab_title="Custom Admin",
+    )
+)
+```
+
+### Next.js Dev Servers
+
+**Built-in Admin** (`django_admin/apps/admin/package.json`):
+```json
+{
+  "scripts": {
+    "dev": "next dev -p 3777"
+  }
+}
+```
+
+**External Admin** (solution project):
+```json
+{
+  "scripts": {
+    "dev": "next dev -p 3000"
+  }
+}
+```
+
+## Development Workflow
+
+### Starting Both Dev Servers
+
+```bash
+# Terminal 1: Built-in admin
+cd projects/django-cfg-dev/src/django_admin/apps/admin
+pnpm dev  # Runs on port 3777
+
+# Terminal 2: External admin
+cd solution/projects/django_admin/apps/admin
+pnpm dev  # Runs on port 3000
+
+# Terminal 3: Django
+cd solution/projects/django
+python manage.py runserver
+```
+
+### Running Single Tab Only
+
+You can run only one dev server - the other will fallback to static files:
+
+```bash
+# Only external admin in dev mode
+cd solution/projects/django_admin/apps/admin
+pnpm dev
+
+# Built-in admin will fallback to /cfg/admin/admin/
+```
+
+## Template Tags Reference
+
+### `{% nextjs_admin_url %}`
+Returns URL for built-in dashboard (Tab 1)
+- Dev: `http://localhost:3777/admin`
+- Prod: `/cfg/admin/admin/`
+
+### `{% nextjs_external_admin_url %}`
+Returns URL for external admin (Tab 2)
+- Dev: `http://localhost:3000/admin`
+- Prod: `/cfg/nextjs-admin/admin/`
+
+### `{% nextjs_external_admin_title %}`
+Returns custom tab title from config (default: "Next.js Admin")
+
+### `{% is_frontend_dev_mode %}`
+Returns `True` if any dev server (port 3000 or 3777) is running
+
+### `{% has_nextjs_external_admin %}`
+Returns `True` if `NextJsAdminConfig` is configured
+
+## Troubleshooting
+
+### Tab shows wrong content
+
+**Symptom**: Second tab shows content from first tab
+
+**Cause**: `handleLoadFailure()` using wrong static URL
+
+**Solution**: Check iframe ID in fallback logic (see `index.html:342-353`)
+
+### postMessage origin mismatch
+
+**Symptom**: Console error about mismatched origins
+
+**Cause**: `iframeOrigin` determined from `iframe.src` after fallback changed it
+
+**Solution**: Use `data-original-src` attribute instead (see `index.html:287`)
+
+### Dev server not detected
+
+**Symptom**: Tabs use static files despite dev server running
+
+**Possible Causes**:
+1. **Dev server still compiling**: Next.js cold start can take 1-2s
+2. **Wrong port**: Dev server on different port than expected
+3. **IPv6 vs IPv4**: Dev server listening only on IPv6 (`::1`)
+4. **Firewall**: Connection blocked by firewall/antivirus
+5. **Retry exhausted**: All 3 retry attempts failed
+
+**Diagnostic Steps**:
+
+1. **Check dev server is actually running**:
+   ```bash
+   lsof -i :3000 -i :3777 | grep LISTEN
+   ```
+
+2. **Test connection manually**:
+   ```bash
+   curl -I http://localhost:3000/admin
+   curl -I http://localhost:3777/admin
+   ```
+
+3. **Check Django template tag logs** (add temporary logging):
+   ```python
+   # In django_cfg.py
+   result = _is_port_available('localhost', 3000)
+   print(f"[DEBUG] Port 3000 check: {result}")
+   ```
+
+4. **Increase retry attempts** (if dev server is very slow):
+   ```python
+   # Temporary test - increase retries
+   _is_port_available('localhost', 3000, timeout=0.5, retries=5, retry_delay=0.1)
+   ```
+
+**Solutions**:
+- **Wait for compilation**: Refresh page after 5-10 seconds
+- **Verify port**: Check `package.json` scripts (`"dev": "next dev -p 3000"`)
+- **Force IPv4**: Use `127.0.0.1` instead of `localhost`
+- **Disable firewall**: Temporarily disable to test
+- **Hard refresh**: Cmd+Shift+R to bypass browser cache
+
+### Tokens not injected
+
+**Symptom**: Next.js app shows "Not authenticated"
+
+**Cause**:
+1. User not logged in to Django
+2. Cache returning 304 Not Modified
+3. `postMessage` origin mismatch
+
+**Solution**:
+- Check Django session authentication
+- Verify cache-control headers
+- Check browser console for `postMessage` errors
+
+## Performance Considerations
+
+### Client-Side Dev Server Check
+
+Port availability check happens in browser with exponential backoff:
+```javascript
+checkDevServerAvailable('http://localhost:3000', retries=3, timeout=1000)
+```
+
+**Impact per check**:
+- **Best case**: ~0.1s (first fetch succeeds immediately)
+- **Typical case**: ~0.5-1.5s (dev server compiling, succeeds on retry)
+- **Worst case**: ~3.5s (all 3 attempts fail with delays: 1s + 0.5s + 1s + 1s)
+
+**Retry schedule** (exponential backoff):
+1. Attempt 1: immediate (0ms delay)
+2. Attempt 2: +500ms delay
+3. Attempt 3: +1000ms delay
+
+**Why client-side checking?**
+- ✅ Non-blocking: doesn't slow down server-side HTML rendering
+- ✅ Better error handling: browser handles CORS/network errors gracefully
+- ✅ User feedback: loading spinner shows progress
+- ✅ Parallel loading: both iframe checks can run concurrently
+
+### iframe Load Timeout
+
+3-second timeout before fallback:
+```javascript
+loadTimeout = setTimeout(() => {
+    handleLoadFailure();
+}, 3000);
+```
+
+**Impact**: Users may see loading spinner for up to 3s if dev server is down
+
+### Static File Caching
+
+- **HTML**: No caching (`no-store, no-cache`)
+- **Assets**: Standard browser caching (JS, CSS, images)
+
+## Security Considerations
+
+### iframe Sandbox
+
+Both iframes use restrictive sandbox attributes:
+```html
+sandbox="allow-same-origin allow-scripts allow-forms
+         allow-popups allow-modals
+         allow-storage-access-by-user-activation"
+```
+
+**Warning**: Console will show "iframe can escape sandboxing" - this is expected because `allow-same-origin` + `allow-scripts` together allow sandbox escape.
+
+### JWT Token Security
+
+- Tokens injected via `postMessage` with origin validation
+- Tokens stored in `localStorage` (accessible to Next.js apps)
+- New tokens generated on each HTML page load
+- Tokens cleared when Django session expires
+
+### CORS & Origins
+
+- Dev mode: Cross-origin iframes (`localhost:3777`, `localhost:3000`)
+- Prod mode: Same-origin iframes (both served from Django domain)
+
+## Future Enhancements
+
+- [ ] Configurable port allocation per project
+- [ ] Hot-reload coordination between Django and Next.js
+- [ ] Shared state synchronization between tabs
+- [ ] Tab-specific URL routing (preserve state across refreshes)
+- [ ] WebSocket support for real-time updates
+- [ ] SSO integration for external admin panels
+- [ ] Health check dashboard for dev servers
+
+---
+
+**Last Updated**: 2025-10-29
+**Django-CFG Version**: 2.x
+**Next.js Version**: 15.x

django_cfg/templates/admin/index.html

@@ -291,67 +291,17 @@
 
                 const iframeUrl = new URL(iframeSrc, window.location.origin);
                 const iframeOrigin = iframeUrl.origin;
-                const isDevMode = iframeOrigin !== window.location.origin;
 
                 // Debounce timer for resize events (prevents jittery iframe height changes)
                 let resizeTimer = null;
-                let loadTimeout = null;
 
                 // iframe load event
                 iframe.addEventListener('load', function() {
-                    // Clear the fallback timeout
-                    if (loadTimeout) {
-                        clearTimeout(loadTimeout);
-                        loadTimeout = null;
-                    }
-
                     setTimeout(() => {
                         sendDataToIframe();
                     }, 100);
                 });
 
-                // iframe error event - fallback to static files
-                iframe.addEventListener('error', function() {
-                    console.warn('[Django-CFG] iframe failed to load, falling back to static files');
-                    handleLoadFailure();
-                });
-
-                // Timeout fallback - if iframe doesn't load in 3 seconds
-                loadTimeout = setTimeout(() => {
-                    if (!iframe.classList.contains('loaded') && isDevMode) {
-                        console.warn('[Django-CFG] Dev server timeout, falling back to static files');
-                        handleLoadFailure();
-                    } else if (!iframe.classList.contains('loaded')) {
-                        console.log('[Django-CFG] Timeout - showing iframe anyway');
-                        if (loading) loading.classList.add('hidden');
-                        iframe.classList.add('loaded');
-                    }
-                }, 3000);
-
-                // Handle load failure - switch to static files
-                function handleLoadFailure() {
-                    if (!isDevMode) return; // Already using static files
-
-                    const originalSrc = iframe.getAttribute('data-original-src');
-                    if (!originalSrc) return;
-
-                    // Extract path from dev server URL
-                    const devUrl = new URL(originalSrc);
-                    const pathPart = devUrl.pathname.replace('/admin', '').replace(/^\//, '');
-
-                    // Build static files URL
-                    const staticUrl = `/cfg/admin/admin/${pathPart}`;
-
-                    console.log('[Django-CFG] Switching to static files:', staticUrl);
-                    iframe.src = staticUrl;
-
-                    // Show iframe after switching
-                    setTimeout(() => {
-                        if (loading) loading.classList.add('hidden');
-                        iframe.classList.add('loaded');
-                    }, 500);
-                }
-
                 // Send theme and auth data to iframe
                 function sendDataToIframe() {
                     if (!iframe || !iframe.contentWindow) {

django_cfg/templatetags/django_cfg.py

@@ -14,29 +14,53 @@ from rest_framework_simplejwt.tokens import RefreshToken
 register = template.Library()
 
 
-def _is_port_available(host: str, port: int, timeout: float = 0.1) -> bool:
+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.
+    Check if a port is available (listening) on the specified host with retry logic.
 
-    Uses a quick socket connection test with minimal timeout.
-    Returns True if the port is open and accepting connections.
+    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 (default: 0.1s)
+        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)
     """
-    try:
-        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-        sock.settimeout(timeout)
-        result = sock.connect_ex((host, port))
-        sock.close()
-        return result == 0
-    except Exception:
-        return False
+    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
@@ -169,9 +193,12 @@ def nextjs_admin_url(path=''):
     """
     Get the URL for Next.js Admin Panel (Built-in Dashboard - Tab 1).
 
-    Auto-detects development mode with priority:
-        1. If port 3001 is available → http://localhost:3001/admin/{path} (dev server)
-        2. Otherwise → /cfg/admin/admin/{path} (static files)
+    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.
@@ -188,12 +215,12 @@ def nextjs_admin_url(path=''):
         # Production mode: always use static files with /admin route
         return f'/cfg/admin/admin/{path}' if path else '/cfg/admin/admin/'
 
-    # Check if port 3001 is available for Tab 1 (built-in admin)
-    port_3001_available = _is_port_available('localhost', 3001)
+    # Check if port 3777 is available for Tab 1 (built-in admin)
+    port_3777_available = _is_port_available('localhost', 3777)
 
-    if port_3001_available:
-        # Dev server is running on 3001 - use /admin route for consistency
-        base_url = 'http://localhost:3001/admin'
+    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
@@ -207,7 +234,7 @@ def is_frontend_dev_mode():
 
     Auto-detects by checking:
         - DEBUG=True
-        - AND (port 3000 OR port 3001 is available)
+        - AND (port 3000 OR port 3777 is available)
 
     Returns True if any Next.js dev server is detected.
 
@@ -222,7 +249,7 @@ def is_frontend_dev_mode():
 
     # Check if either dev server is running
     return (_is_port_available('localhost', 3000) or
-            _is_port_available('localhost', 3001))
+            _is_port_available('localhost', 3777))
 
 
 @register.simple_tag
@@ -252,12 +279,14 @@ def nextjs_external_admin_url(route=''):
     """
     Get URL for external Next.js admin (Tab 2 - solution project).
 
-    Auto-detects development mode:
-        - If DEBUG=True AND localhost:3000 is available → http://localhost:3000/admin/{route}
-        - Otherwise → /cfg/nextjs-admin/admin/{route} (static files)
+    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).
-    No env variable needed - automatically detects running dev server!
 
     Usage in template:
         {% load django_cfg %}

{django_cfg-1.4.101.dist-info → django_cfg-1.4.103.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-cfg
-Version: 1.4.101
+Version: 1.4.103
 Summary: Modern Django framework with type-safe Pydantic v2 configuration, Next.js admin integration, real-time WebSockets, and 8 enterprise apps. Replace settings.py with validated models, 90% less code. Production-ready with AI agents, auto-generated TypeScript clients, and zero-config features.
 Project-URL: Homepage, https://djangocfg.com
 Project-URL: Documentation, https://djangocfg.com

{django_cfg-1.4.101.dist-info → django_cfg-1.4.103.dist-info}/RECORD

@@ -1,5 +1,5 @@
 django_cfg/README.md,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-django_cfg/__init__.py,sha256=-L4xh-iNYo38lfiLUM2y4ie60fmbzclNmpl6ULRBIt8,1621
+django_cfg/__init__.py,sha256=NcoABp5CJlspxHWWGZJqyOKUZB7Ny0hs794hP123d_Y,1621
 django_cfg/apps.py,sha256=72m3uuvyqGiLx6gOfE-BD3P61jddCCERuBOYpxTX518,1605
 django_cfg/config.py,sha256=y4Z3rnYsHBE0TehpwAIPaxr---mkvyKrZGGsNwYso74,1398
 django_cfg/apps/__init__.py,sha256=JtDmEYt1OcleWM2ZaeX0LKDnRQzPOavfaXBWG4ECB5Q,26
@@ -664,7 +664,7 @@ django_cfg/models/base/module.py,sha256=nxN1Y9J4l94kOfSXLQJ2eGgIGWTq8kyh7hUGvCQN
 django_cfg/models/django/__init__.py,sha256=xY_ts1oGmMROXfKHLuERqwG35dQf3EpsZxqj9DcRYwI,397
 django_cfg/models/django/axes.py,sha256=-4nk2gSfpj7lNY5vnm_2jHVLz8VAKoEd9yF2TuCR8O8,5624
 django_cfg/models/django/constance.py,sha256=E4U3HS_gFq5_q2nhI1R8inONGtD7IgvSwxOEGNGGrEI,9127
-django_cfg/models/django/crypto_fields.py,sha256=frqLVcDC0zymUyZ6u7tqakojjBNEziHyjbnu1PPvjY0,4187
+django_cfg/models/django/crypto_fields.py,sha256=EritHX2V8q5zHoVznGIO0sX78GPYif6NQDS_CiXvSKo,6238
 django_cfg/models/django/environment.py,sha256=lBCHBs1lphv9tlu1BCTfLZeH_kUame0p66A_BIjBY7M,9440
 django_cfg/models/django/openapi.py,sha256=avE3iapaCj8eyOqVUum_v2EExR3V-hwHrexqtXMHtTQ,3739
 django_cfg/models/django/revolution_legacy.py,sha256=Z4SPUS7QSv62EuPAeFFoXGEgqLmdXnVEr7Ofk1IDtVc,8918
@@ -859,7 +859,7 @@ django_cfg/modules/django_client/core/validation/rules/base.py,sha256=xVJli0eSEz
 django_cfg/modules/django_client/core/validation/rules/type_hints.py,sha256=hwjTMADillsTPruDvXZQeZMj4LVV443zxY9o0Gqgg6k,10200
 django_cfg/modules/django_client/management/__init__.py,sha256=mCTPP_bIOmqNnn0WAG2n4BuF6zwc9PTgdZr_dORfNDk,54
 django_cfg/modules/django_client/management/commands/__init__.py,sha256=CJ55pHUNYQ5h-QHUe3axeTtxzlUJv7wbEuZmGN21iCM,36
-django_cfg/modules/django_client/management/commands/generate_client.py,sha256=uPoHIU2-rqq0733H7Pj5fl-vNu7Oj5aZYyFqVNKlTVU,29955
+django_cfg/modules/django_client/management/commands/generate_client.py,sha256=JShicezcxeUJ8_5l5HJtINbDwsdhoK_4gljyaPlfXGM,30910
 django_cfg/modules/django_client/management/commands/validate_openapi.py,sha256=IBKk7oRP3tMQzXjvZNIgQtMPk3k_mB2diNS7bkaSLz4,11011
 django_cfg/modules/django_client/spectacular/__init__.py,sha256=M8fG-odu2ltkG36aMMr0KDkCKGX676TwdrJO8vky2cI,345
 django_cfg/modules/django_client/spectacular/async_detection.py,sha256=S_pwGR7_2SIWHjZJyiu7SCfySF3Nr3P8eqjDyBSkkLs,5731
@@ -1023,7 +1023,7 @@ django_cfg/modules/nextjs_admin/apps.py,sha256=HxVUMmWTKdYpwJ00iIfWVFsBzsawsOVhE
 django_cfg/modules/nextjs_admin/urls.py,sha256=7n0yStm0WNchw14Rtu_mgsIA3WKQsYP9WZt3-YOUWjU,603
 django_cfg/modules/nextjs_admin/views.py,sha256=SELkdq6ioNqFLInDKfYyRSZRaXRtuGAVjQfE8sACQ_Q,10382
 django_cfg/modules/nextjs_admin/models/__init__.py,sha256=WGw9KXcYd1O9AoA_bpMoz2gLZUlRzjGmUBjjbObcUi0,100
-django_cfg/modules/nextjs_admin/models/config.py,sha256=0ADqLuiywSCQfx_z9dkwjFCca3lr3F2uQffIjTr_QXw,5864
+django_cfg/modules/nextjs_admin/models/config.py,sha256=75iM81aaTlDQdhfvdlCzj6o9zD5JIK522CIVzM-GSvE,6326
 django_cfg/modules/nextjs_admin/templatetags/__init__.py,sha256=ChVBnJggCIY8rMhfyJFoA8k0qKo-8FtJknrk54Vx4wM,51
 django_cfg/modules/nextjs_admin/templatetags/nextjs_admin.py,sha256=aAekrlu3pvvx3I4uJGT3S2ie8QfF94umDBjgAF71EII,4483
 django_cfg/registry/__init__.py,sha256=CaiL9KwqPzXlIe5-4Qr7PQu5ZxAW1HtuDIXZ7-ktRQg,538
@@ -1072,11 +1072,12 @@ django_cfg/static/js/api/support/index.mjs,sha256=oPA3iGkUWYyKQuJlI5-tSxD3AOhwlA
 django_cfg/static/js/api/tasks/client.mjs,sha256=tIy8K-finXzTUL9kOo_L4Q1kchDaHyuzjwS4VymiWPM,3579
 django_cfg/static/js/api/tasks/index.mjs,sha256=yCY1GzdD-RtFZ3pAfk1l0msgO1epyo0lsGCjH0g1Afc,294
 django_cfg/templates/__init__.py,sha256=IzLjt-a7VIJ0OutmAE1_-w0_LpL2u0MgGpnIabjZuW8,19
-django_cfg/templates/admin/index.html,sha256=bKpeJFRJltoe3iWmFcR5YUzTwPgnogwAsQXjUlELQEE,20072
+django_cfg/templates/admin/DUAL_TAB_ARCHITECTURE.md,sha256=kDUOgLjEv6OdtZNadtQuPhNQmeEZ_TVNt6PKGF6abw4,15607
+django_cfg/templates/admin/index.html,sha256=ygX2GklrPx9yEzk507Kk7Z56zDfaxjMHpq-TqQCN_1M,17743
 django_cfg/templates/emails/base_email.html,sha256=TWcvYa2IHShlF_E8jf1bWZStRO0v8G4L_GexPxvz6XQ,8836
 django_cfg/templates/unfold/layouts/skeleton.html,sha256=2ArkcNZ34mFs30cOAsTQ1EZiDXcB0aVxkO71lJq9SLE,718
 django_cfg/templatetags/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-django_cfg/templatetags/django_cfg.py,sha256=pAUZQhq3k_JJtQXzabQnXyiHxkDoEGt0iUceeVHz6os,9498
+django_cfg/templatetags/django_cfg.py,sha256=bJPLZ9Uwlr499-umGN7bcaUibMgZs_XQHvoee93fMfk,10486
 django_cfg/utils/__init__.py,sha256=64wwXJuXytvwt8Ze_erSR2HmV07nGWJ6DV5wloRBvYE,435
 django_cfg/utils/path_resolution.py,sha256=2n0I04lQkSssFaELu3A93YyMAl1K10KPdpxMt5k4Iy0,13341
 django_cfg/utils/smart_defaults.py,sha256=ZUj6K_Deq-fp5O0Dy_Emt257UWFn0f9bkgFv9YCR58U,9239
@@ -1084,9 +1085,9 @@ django_cfg/utils/version_check.py,sha256=WO51J2m2e-wVqWCRwbultEwu3q1lQasV67Mw2aa
 django_cfg/CHANGELOG.md,sha256=jtT3EprqEJkqSUh7IraP73vQ8PmKUMdRtznQsEnqDZk,2052
 django_cfg/CONTRIBUTING.md,sha256=DU2kyQ6PU0Z24ob7O_OqKWEYHcZmJDgzw-lQCmu6uBg,3041
 django_cfg/LICENSE,sha256=xHuytiUkSZCRG3N11nk1X6q1_EGQtv6aL5O9cqNRhKE,1071
-django_cfg/pyproject.toml,sha256=fRimICIiTmgJtVtauQKZXaMf7_U-g66BldVRGf9DUdQ,8573
-django_cfg-1.4.101.dist-info/METADATA,sha256=iG0VURioei3gw3HtXC1UIxiE6k8xhcfEY9oZep_SnhA,23734
-django_cfg-1.4.101.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-django_cfg-1.4.101.dist-info/entry_points.txt,sha256=Ucmde4Z2wEzgb4AggxxZ0zaYDb9HpyE5blM3uJ0_VNg,56
-django_cfg-1.4.101.dist-info/licenses/LICENSE,sha256=xHuytiUkSZCRG3N11nk1X6q1_EGQtv6aL5O9cqNRhKE,1071
-django_cfg-1.4.101.dist-info/RECORD,,
+django_cfg/pyproject.toml,sha256=Z7stNPVSGKgzrgQe7wcp-wgZA9lz420IiQ2KoZSNcso,8573
+django_cfg-1.4.103.dist-info/METADATA,sha256=LAiU0BRYKRV1qpQVNFUSQKKBalgW4vsrSytQEoJ9T1w,23734
+django_cfg-1.4.103.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+django_cfg-1.4.103.dist-info/entry_points.txt,sha256=Ucmde4Z2wEzgb4AggxxZ0zaYDb9HpyE5blM3uJ0_VNg,56
+django_cfg-1.4.103.dist-info/licenses/LICENSE,sha256=xHuytiUkSZCRG3N11nk1X6q1_EGQtv6aL5O9cqNRhKE,1071
+django_cfg-1.4.103.dist-info/RECORD,,