IncludeCPP 4.5.2__py3-none-any.whl → 4.9.3__py3-none-any.whl

includecpp/cli/commands.py

@@ -66,10 +66,13 @@ def _supports_unicode():
     """Check if terminal supports Unicode output."""
     if sys.platform == 'win32':
         try:
+            # Handle frozen PyInstaller where stdout may be None
+            if sys.stdout is None:
+                return False
             # Test if we can encode Unicode box characters
             '╔═╗'.encode(sys.stdout.encoding or 'utf-8')
             return True
-        except (UnicodeEncodeError, LookupError):
+        except (UnicodeEncodeError, LookupError, AttributeError):
             return False
     return True
 
@@ -430,11 +433,590 @@ def _show_doc(search_term: str = None):
     _safe_echo("=" * 70)
 
 
+def _show_pypi_stats():
+    """Show detailed PyPI download statistics with charts."""
+    from datetime import datetime, timedelta
+    import json
+    try:
+        import pypistats
+    except ImportError:
+        click.secho("Installing pypistats...", fg='yellow')
+        import subprocess
+        subprocess.run([sys.executable, '-m', 'pip', 'install', 'pypistats', '-q'])
+        import pypistats
+
+    package = 'includecpp'
+
+    # Header
+    click.echo()
+    click.secho("=" * 70, fg='cyan', bold=True)
+    click.secho("   INCLUDECPP - PyPI Download Statistics (CONFIDENTIAL)", fg='cyan', bold=True)
+    click.secho("=" * 70, fg='cyan', bold=True)
+    click.echo()
+
+    def draw_bar(value, max_value, width=40, fill_char='#', empty_char='.'):
+        """Draw a horizontal bar chart using ASCII."""
+        if max_value == 0:
+            return empty_char * width
+        filled = int((value / max_value) * width)
+        return fill_char * filled + empty_char * (width - filled)
+
+    def format_number(n):
+        """Format number with K/M suffix."""
+        if n >= 1_000_000:
+            return f"{n/1_000_000:.1f}M"
+        elif n >= 1_000:
+            return f"{n/1_000:.1f}K"
+        return str(n)
+
+    def section_header(title, color='green'):
+        """Print section header using ASCII."""
+        click.secho("+" + "-" * 68 + "+", fg=color)
+        click.secho(f"|  {title:<65}|", fg=color, bold=True)
+        click.secho("+" + "-" * 68 + "+", fg=color)
+
+    try:
+        # === ALL TIME DOWNLOADS ===
+        section_header("ALL TIME DOWNLOADS (since first release)", 'green')
+
+        try:
+            overall = pypistats.overall(package, format='json')
+            overall_data = json.loads(overall)
+            total_with_mirrors = 0
+            total_without_mirrors = 0
+            for row in overall_data.get('data', []):
+                if row.get('category') == 'with_mirrors':
+                    total_with_mirrors = row.get('downloads', 0)
+                elif row.get('category') == 'without_mirrors':
+                    total_without_mirrors = row.get('downloads', 0)
+
+            click.echo()
+            click.echo(f"  {'All downloads (incl. mirrors):':<35} {click.style(format_number(total_with_mirrors), fg='bright_white', bold=True):>10}")
+            click.echo(f"  {'Excl. known mirrors:':<35} {click.style(format_number(total_without_mirrors), fg='bright_white', bold=True):>10}")
+            click.echo()
+            click.secho("  Note: 'Excl. mirrors' still includes CI/CD, Docker, reinstalls.", fg='bright_black')
+            click.secho("  Actual unique users is likely 5-20% of this number.", fg='bright_black')
+            click.echo()
+        except Exception as e:
+            click.secho(f"  Could not fetch overall stats: {e}", fg='yellow')
+
+        # === RECENT DOWNLOADS (Last 30 days breakdown) ===
+        section_header("RECENT DOWNLOADS (Last 30 Days)", 'blue')
+
+        try:
+            recent = pypistats.recent(package, format='json')
+            recent_data = json.loads(recent) if isinstance(recent, str) else recent
+            # Handle both dict format {'data': [...]} and list format [...]
+            if isinstance(recent_data, dict):
+                rows = recent_data.get('data', [])
+            elif isinstance(recent_data, list):
+                rows = recent_data
+            else:
+                rows = []
+
+            click.echo()
+            # Find max for bar scaling
+            max_downloads = max((r.get('downloads', 0) for r in rows if isinstance(r, dict)), default=1)
+            for row in rows:
+                if not isinstance(row, dict):
+                    continue
+                period = row.get('category', 'unknown')
+                downloads = row.get('downloads', 0)
+                period_display = {'last_day': 'Last Day', 'last_week': 'Last Week', 'last_month': 'Last Month'}.get(period, period)
+                bar = draw_bar(downloads, max_downloads, width=30)
+                click.echo(f"  {period_display:<15} {click.style(bar, fg='green')} {click.style(format_number(downloads), fg='bright_white', bold=True):>10}")
+            click.echo()
+        except Exception as e:
+            click.secho(f"  Could not fetch recent stats: {e}", fg='yellow')
+
+        # === PYTHON VERSION BREAKDOWN (Last 30 days with classification) ===
+        section_header("PYTHON VERSION (Last 30 Days - classified only)", 'magenta')
+
+        try:
+            python_major = pypistats.python_major(package, format='json')
+            major_data = json.loads(python_major)
+            click.echo()
+            versions = [(row.get('category'), row.get('downloads', 0)) for row in major_data.get('data', []) if row.get('category') != 'null']
+            versions.sort(key=lambda x: x[1], reverse=True)
+            max_dl = versions[0][1] if versions else 1
+            for version, downloads in versions[:5]:
+                bar = draw_bar(downloads, max_dl, width=35, fill_char='=', empty_char='.')
+                pct = (downloads / sum(d for _, d in versions)) * 100 if versions else 0
+                click.echo(f"  Python {version:<6} {click.style(bar, fg='magenta')} {format_number(downloads):>8} ({pct:>5.1f}%)")
+            click.echo()
+        except Exception as e:
+            click.secho(f"  Could not fetch Python version stats: {e}", fg='yellow')
+
+        # === PYTHON MINOR VERSION (3.10, 3.11, 3.12, etc.) ===
+        section_header("PYTHON MINOR VERSION (Last 30 Days - classified only)", 'yellow')
+
+        try:
+            python_minor = pypistats.python_minor(package, format='json')
+            minor_data = json.loads(python_minor)
+            click.echo()
+            versions = [(row.get('category'), row.get('downloads', 0)) for row in minor_data.get('data', []) if row.get('category') and row.get('category') != 'null']
+            versions.sort(key=lambda x: x[1], reverse=True)
+            max_dl = versions[0][1] if versions else 1
+            for version, downloads in versions[:8]:
+                bar = draw_bar(downloads, max_dl, width=30, fill_char='#', empty_char='.')
+                pct = (downloads / sum(d for _, d in versions)) * 100 if versions else 0
+                click.echo(f"  {version:<8} {click.style(bar, fg='yellow')} {format_number(downloads):>8} ({pct:>5.1f}%)")
+            click.echo()
+        except Exception as e:
+            click.secho(f"  Could not fetch Python minor version stats: {e}", fg='yellow')
+
+        # === SYSTEM/OS BREAKDOWN ===
+        section_header("OPERATING SYSTEM (Last 30 Days - classified only)", 'red')
+
+        try:
+            system_stats = pypistats.system(package, format='json')
+            system_data = json.loads(system_stats)
+            click.echo()
+            systems = [(row.get('category'), row.get('downloads', 0)) for row in system_data.get('data', []) if row.get('category') and row.get('category') != 'null']
+            systems.sort(key=lambda x: x[1], reverse=True)
+            max_dl = systems[0][1] if systems else 1
+            os_labels = {'Windows': '[Win]', 'Linux': '[Lin]', 'Darwin': '[Mac]', 'null': '[?]'}
+            for system, downloads in systems[:5]:
+                bar = draw_bar(downloads, max_dl, width=35, fill_char='=', empty_char='.')
+                pct = (downloads / sum(d for _, d in systems)) * 100 if systems else 0
+                label = os_labels.get(system, '     ')
+                click.echo(f"  {label} {system:<10} {click.style(bar, fg='red')} {format_number(downloads):>8} ({pct:>5.1f}%)")
+            click.echo()
+        except Exception as e:
+            click.secho(f"  Could not fetch system stats: {e}", fg='yellow')
+
+        # === DAILY DOWNLOADS TREND (Last 14 days) ===
+        section_header("DAILY DOWNLOADS TREND (Last 14 Days)", 'cyan')
+
+        try:
+            # Fetch daily data directly from pypistats.org API
+            import urllib.request
+            end_date = datetime.now().strftime('%Y-%m-%d')
+            start_date = (datetime.now() - timedelta(days=14)).strftime('%Y-%m-%d')
+            api_url = f"https://pypistats.org/api/packages/{package}/overall?start_date={start_date}&end_date={end_date}"
+
+            req = urllib.request.Request(api_url, headers={'User-Agent': 'IncludeCPP-CLI'})
+            with urllib.request.urlopen(req, timeout=10) as response:
+                daily_data = json.loads(response.read().decode())
+
+            click.echo()
+            days = []
+            for row in daily_data.get('data', []):
+                date_val = row.get('date')
+                if date_val and row.get('category') == 'without_mirrors':
+                    days.append((date_val, row.get('downloads', 0)))
+
+            if days:
+                days.sort(key=lambda x: x[0])
+                max_dl = max(d for _, d in days) if days else 1
+
+                # Draw sparkline-style chart
+                click.echo("  Date        Downloads")
+                click.echo("  " + "-" * 50)
+                for date, downloads in days[-14:]:
+                    bar = draw_bar(downloads, max_dl, width=30, fill_char='=', empty_char=' ')
+                    date_short = date[5:]  # MM-DD format
+                    click.echo(f"  {date_short}    {click.style(bar, fg='cyan')} {format_number(downloads):>6}")
+
+                click.echo()
+                # Summary stats
+                total = sum(d for _, d in days)
+                avg = total / len(days) if days else 0
+                peak = max(d for _, d in days)
+                peak_date = [date for date, d in days if d == peak][0] if days else 'N/A'
+
+                click.echo(f"  {'14-Day Total:':<20} {click.style(format_number(total), fg='bright_white', bold=True)}")
+                click.echo(f"  {'Daily Average:':<20} {click.style(format_number(int(avg)), fg='bright_white')}")
+                click.echo(f"  {'Peak Day:':<20} {click.style(f'{format_number(peak)} ({peak_date})', fg='green', bold=True)}")
+            else:
+                click.secho("  No daily data available yet (data updates daily)", fg='yellow')
+            click.echo()
+        except Exception as e:
+            click.secho(f"  Could not fetch daily trend: {e}", fg='yellow')
+
+        # === REALISTIC ESTIMATE ===
+        section_header("REALISTIC USER ESTIMATE", 'bright_black')
+        click.echo()
+        click.secho("  PyPI download counts are NOT unique users. They include:", fg='bright_black')
+        click.secho("  * CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins)", fg='bright_black')
+        click.secho("  * Docker container builds", fg='bright_black')
+        click.secho("  * Package reinstalls and cache misses", fg='bright_black')
+        click.secho("  * Multiple machines per user (laptop, PC, VM, WSL)", fg='bright_black')
+        click.secho("  * Corporate proxies (Artifactory, devpi)", fg='bright_black')
+        click.echo()
+        click.secho("  Industry estimate: Actual unique humans ~ 5-15% of downloads", fg='yellow')
+        try:
+            if total_without_mirrors:
+                low_est = int(total_without_mirrors * 0.05)
+                high_est = int(total_without_mirrors * 0.15)
+                click.echo(f"  For {format_number(total_without_mirrors)} downloads: ~{format_number(low_est)} - {format_number(high_est)} unique users")
+        except:
+            pass
+        click.echo()
+
+        # === FOOTER ===
+        click.echo()
+        click.secho("=" * 70, fg='cyan', bold=True)
+        click.secho(f"  Report generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}", fg='bright_black')
+        click.secho(f"  Package: includecpp | Source: PyPI Stats API (BigQuery)", fg='bright_black')
+        click.secho("=" * 70, fg='cyan', bold=True)
+        click.echo()
+
+    except Exception as e:
+        click.secho(f"Error fetching PyPI stats: {e}", fg='red')
+        import traceback
+        traceback.print_exc()
+
+
+def _make_executable(script_path: str, output_name: str = None, onefile: bool = True, console: bool = True, icon: str = None):
+    """Build .exe from Python script using PyInstaller.
+
+    Auto-detects dependencies, rebuilds includecpp if needed, and cleans up.
+
+    Args:
+        script_path: Path to the Python script
+        output_name: Optional custom name for output executable (without .exe)
+        onefile: Build as single file (True) or directory (False)
+        console: Show console window (True) or windowed mode (False)
+        icon: Path to icon file (.ico)
+    """
+    import re
+    import shutil
+    import ast
+
+    script_path = Path(script_path).resolve()
+    if not script_path.exists():
+        click.secho(f"Error: File not found: {script_path}", fg='red')
+        return
+
+    if script_path.suffix.lower() != '.py':
+        click.secho(f"Error: Not a Python file: {script_path}", fg='red')
+        return
+
+    script_dir = script_path.parent
+    script_name = output_name if output_name else script_path.stem
+
+    click.echo()
+    click.secho(f"Building executable from: {script_path.name}", fg='cyan', bold=True)
+    if output_name:
+        click.echo(f"  Output name: {output_name}.exe")
+    click.echo("=" * 50)
+
+    # Check if PyInstaller is installed
+    try:
+        import PyInstaller
+        click.echo(f"  PyInstaller: v{PyInstaller.__version__}")
+    except ImportError:
+        click.secho("Error: PyInstaller is not installed.", fg='red')
+        click.echo("Install it with: pip install pyinstaller")
+        return
+
+    # Read and analyze the script
+    try:
+        with open(script_path, 'r', encoding='utf-8') as f:
+            script_content = f.read()
+    except Exception as e:
+        click.secho(f"Error reading script: {e}", fg='red')
+        return
+
+    # Detect imports
+    detected_imports = set()
+    uses_includecpp = False
+    uses_pyqt6 = False
+    uses_pyqt5 = False
+    uses_tkinter = False
+    uses_pyside6 = False
+    uses_pyside2 = False
+
+    # Simple regex-based import detection
+    import_patterns = [
+        r'^import\s+(\w+)',
+        r'^from\s+(\w+)',
+    ]
+
+    for line in script_content.split('\n'):
+        line = line.strip()
+        for pattern in import_patterns:
+            match = re.match(pattern, line)
+            if match:
+                module = match.group(1)
+                detected_imports.add(module)
+                if module == 'includecpp':
+                    uses_includecpp = True
+                elif module == 'PyQt6':
+                    uses_pyqt6 = True
+                elif module == 'PyQt5':
+                    uses_pyqt5 = True
+                elif module == 'PySide6':
+                    uses_pyside6 = True
+                elif module == 'PySide2':
+                    uses_pyside2 = True
+                elif module == 'tkinter':
+                    uses_tkinter = True
+
+    click.echo(f"  Detected imports: {len(detected_imports)}")
+
+    # Build data files list for PyInstaller
+    datas = []
+    binaries = []  # For .pyd/.so files
+    hidden_imports = []
+
+    # If includecpp is used, rebuild and include the compiled modules
+    includecpp_files_to_copy = []  # Initialize here for later use
+
+    if uses_includecpp:
+        click.echo()
+        click.secho("  IncludeCPP detected - checking for modules...", fg='yellow')
+
+        # Look for cpp.proj in script directory or parent directories
+        cpp_proj_path = None
+        search_dir = script_dir
+        for _ in range(5):  # Search up to 5 levels up
+            candidate = search_dir / 'cpp.proj'
+            if candidate.exists():
+                cpp_proj_path = candidate
+                break
+            if search_dir.parent == search_dir:
+                break
+            search_dir = search_dir.parent
+
+        if cpp_proj_path:
+            click.echo(f"    Found project: {cpp_proj_path}")
+
+            # Load project config to find build directory
+            try:
+                import json
+                with open(cpp_proj_path, 'r') as f:
+                    proj_config = json.load(f)
+
+                proj_dir = cpp_proj_path.parent
+
+                # Rebuild the modules
+                click.echo("    Rebuilding C++ modules...")
+                try:
+                    from ..core.build_manager import BuildManager
+                    from .config_parser import CppProjectConfig
+                    # detect_compiler is defined in this file
+
+                    config = CppProjectConfig(config_path=cpp_proj_path)
+                    project_root = cpp_proj_path.parent
+                    compiler = detect_compiler()
+                    build_dir_path = config.get_build_dir(compiler)
+                    build_dir_path.mkdir(parents=True, exist_ok=True)
+
+                    builder = BuildManager(project_root, build_dir_path, config)
+                    success = builder.rebuild(incremental=True)
+
+                    if success:
+                        click.secho("    Rebuild complete!", fg='green')
+                    else:
+                        click.secho("    Warning: Rebuild had errors", fg='yellow')
+                except Exception as e:
+                    click.secho(f"    Warning: Rebuild failed: {e}", fg='yellow')
+
+                # Use the build directory from the project config (already computed above)
+                build_dir = build_dir_path
+
+                # Store paths for copying AFTER PyInstaller completes
+                # (Don't bundle into exe - create external includecpp.dll instead)
+                if build_dir.exists():
+                    ext = '.pyd' if sys.platform == 'win32' else '.so'
+                    bindings_dir = build_dir / 'bindings'
+
+                    # Find api.pyd (or api.so)
+                    pyd_files = list(bindings_dir.glob(f'*{ext}')) if bindings_dir.exists() else []
+                    if not pyd_files:
+                        pyd_files = list(build_dir.glob(f'**/*{ext}'))
+
+                    if pyd_files:
+                        # Store the main api.pyd path for creating includecpp.dll
+                        api_pyd = pyd_files[0]  # Usually api.pyd
+                        includecpp_files_to_copy.append(('api', api_pyd))
+                        click.echo(f"    Found: {api_pyd.name} (will create includecpp.dll)")
+
+                    # Find runtime DLLs
+                    if bindings_dir.exists():
+                        dll_files = list(bindings_dir.glob('*.dll'))
+                        for dll_file in dll_files:
+                            includecpp_files_to_copy.append(('dll', dll_file))
+                            click.echo(f"    Found: {dll_file.name}")
+
+                    if pyd_files:
+                        click.secho(f"    Will copy {len(includecpp_files_to_copy)} file(s) to output directory", fg='green')
+                    else:
+                        click.secho("    Warning: No compiled modules found in build directory", fg='yellow')
+                else:
+                    click.secho("    Warning: Build directory not found", fg='yellow')
+
+            except Exception as e:
+                click.secho(f"    Warning: Could not process cpp.proj: {e}", fg='yellow')
+        else:
+            click.secho("    Warning: cpp.proj not found. C++ modules may not be included.", fg='yellow')
+
+        hidden_imports.append('includecpp')
+        hidden_imports.append('api')  # The compiled module
+
+    # Add GUI-specific settings
+    if uses_pyqt6:
+        click.echo("  PyQt6 detected")
+        hidden_imports.extend(['PyQt6', 'PyQt6.QtCore', 'PyQt6.QtGui', 'PyQt6.QtWidgets'])
+    if uses_pyqt5:
+        click.echo("  PyQt5 detected")
+        hidden_imports.extend(['PyQt5', 'PyQt5.QtCore', 'PyQt5.QtGui', 'PyQt5.QtWidgets'])
+    if uses_pyside6:
+        click.echo("  PySide6 detected")
+        hidden_imports.extend(['PySide6', 'PySide6.QtCore', 'PySide6.QtGui', 'PySide6.QtWidgets'])
+    if uses_pyside2:
+        click.echo("  PySide2 detected")
+        hidden_imports.extend(['PySide2', 'PySide2.QtCore', 'PySide2.QtGui', 'PySide2.QtWidgets'])
+
+    # Build PyInstaller command
+    click.echo()
+    click.secho("Building executable...", fg='cyan')
+
+    cmd = [
+        sys.executable, '-m', 'PyInstaller',
+        '--noconfirm',
+        '--clean',
+    ]
+
+    if onefile:
+        cmd.append('--onefile')
+    else:
+        cmd.append('--onedir')
+
+    if console:
+        cmd.append('--console')
+    else:
+        cmd.append('--windowed')
+
+    if icon:
+        cmd.extend(['--icon', str(Path(icon).resolve())])
+
+    # Set output name if specified
+    if output_name:
+        cmd.extend(['--name', output_name])
+
+    # Add data files
+    for src, dest in datas:
+        cmd.extend(['--add-data', f'{src}{os.pathsep}{dest}'])
+
+    # Add binary files (.pyd/.so)
+    for src, dest in binaries:
+        cmd.extend(['--add-binary', f'{src}{os.pathsep}{dest}'])
+
+    # Add hidden imports
+    for imp in hidden_imports:
+        cmd.extend(['--hidden-import', imp])
+
+    # Set output directory to script directory
+    cmd.extend(['--distpath', str(script_dir)])
+    cmd.extend(['--workpath', str(script_dir / 'build')])
+    cmd.extend(['--specpath', str(script_dir)])
+
+    # Add the script
+    cmd.append(str(script_path))
+
+    # Run PyInstaller
+    try:
+        result = subprocess.run(cmd, cwd=str(script_dir), capture_output=True, text=True)
+
+        if result.returncode != 0:
+            click.secho("PyInstaller failed!", fg='red')
+            if result.stderr:
+                click.echo(result.stderr[-2000:])  # Show last 2000 chars of error
+            return
+
+        click.secho("PyInstaller completed!", fg='green')
+
+    except Exception as e:
+        click.secho(f"Error running PyInstaller: {e}", fg='red')
+        return
+
+    # Copy includecpp.dll and runtime DLLs to output directory
+    if uses_includecpp and includecpp_files_to_copy:
+        click.echo()
+        click.echo("Creating includecpp.dll...")
+        try:
+            for file_type, file_path in includecpp_files_to_copy:
+                if file_type == 'api':
+                    # Copy api.pyd as includecpp.dll
+                    dll_output = script_dir / 'includecpp.dll'
+                    shutil.copy2(file_path, dll_output)
+                    click.secho("  Created: includecpp.dll", fg='green')
+                else:
+                    # Copy runtime DLLs
+                    dest = script_dir / file_path.name
+                    shutil.copy2(file_path, dest)
+                    click.echo(f"  Copied: {file_path.name}")
+        except Exception as e:
+            click.secho(f"  Warning: Could not copy files: {e}", fg='yellow')
+
+    # Clean up
+    click.echo()
+    click.echo("Cleaning up...")
+
+    # Remove build directory
+    build_path = script_dir / 'build'
+    if build_path.exists():
+        try:
+            shutil.rmtree(build_path)
+            click.echo("  Removed build/")
+        except Exception as e:
+            click.secho(f"  Warning: Could not remove build/: {e}", fg='yellow')
+
+    # Remove .spec file
+    spec_path = script_dir / f'{script_name}.spec'
+    if spec_path.exists():
+        try:
+            spec_path.unlink()
+            click.echo("  Removed .spec file")
+        except Exception as e:
+            click.secho(f"  Warning: Could not remove .spec: {e}", fg='yellow')
+
+    # Remove __pycache__ if created
+    pycache = script_dir / '__pycache__'
+    if pycache.exists():
+        try:
+            shutil.rmtree(pycache)
+            click.echo("  Removed __pycache__/")
+        except:
+            pass
+
+    # Check for output
+    if onefile:
+        exe_name = f'{script_name}.exe' if sys.platform == 'win32' else script_name
+        exe_path = script_dir / exe_name
+    else:
+        exe_name = script_name
+        exe_path = script_dir / exe_name
+
+    click.echo()
+    if exe_path.exists():
+        if exe_path.is_file():
+            size_mb = exe_path.stat().st_size / (1024 * 1024)
+            click.secho(f"Success! Created: {exe_path.name} ({size_mb:.1f} MB)", fg='green', bold=True)
+        else:
+            click.secho(f"Success! Created: {exe_path.name}/ (directory)", fg='green', bold=True)
+    else:
+        click.secho("Warning: Executable not found at expected location", fg='yellow')
+        # Try to find it
+        if sys.platform == 'win32':
+            found = list(script_dir.glob('*.exe'))
+            if found:
+                click.echo(f"Found: {found[0].name}")
+
+
 @click.group(invoke_without_command=True)
 @click.option('--doc', 'doc_search', default=None, help='Show documentation. Use --doc or --doc "term" to search.')
 @click.option('-d', 'doc_flag', is_flag=True, help='Show full documentation (shorthand)')
 @click.option('--changelog', 'show_changelog', is_flag=True, help='Show changelog (last 2 releases by default)')
 @click.option('--all', 'changelog_all', is_flag=True, help='Show all changelog entries (use with --changelog)')
+@click.option('--make-exe', 'make_exe_path', type=str, help='Build .exe from script, or "gui" for wizard')
+@click.option('--exe-name', 'exe_name', type=str, help='Output executable name (without .exe)')
+@click.option('--onefile/--onedir', 'onefile', default=True, help='Build as single file or directory (default: onefile)')
+@click.option('--console/--windowed', 'console', default=True, help='Show console window or not (default: console)')
+@click.option('--icon', type=click.Path(exists=True), help='Icon file for executable (.ico)')
 @click.option('--1', 'changelog_1', is_flag=True, hidden=True)
 @click.option('--2', 'changelog_2', is_flag=True, hidden=True)
 @click.option('--3', 'changelog_3', is_flag=True, hidden=True)
@@ -445,9 +1027,11 @@ def _show_doc(search_term: str = None):
 @click.option('--8', 'changelog_8', is_flag=True, hidden=True)
 @click.option('--9', 'changelog_9', is_flag=True, hidden=True)
 @click.option('--10', 'changelog_10', is_flag=True, hidden=True)
+@click.option('--stats', 'stats_key', type=str, default=None, hidden=True)
 @click.pass_context
-def cli(ctx, doc_search, doc_flag, show_changelog, changelog_all, changelog_1, changelog_2, changelog_3,
-        changelog_4, changelog_5, changelog_6, changelog_7, changelog_8, changelog_9, changelog_10):
+def cli(ctx, doc_search, doc_flag, show_changelog, changelog_all, make_exe_path, exe_name, onefile, console, icon,
+        changelog_1, changelog_2, changelog_3, changelog_4, changelog_5, changelog_6, changelog_7,
+        changelog_8, changelog_9, changelog_10, stats_key):
     """IncludeCPP - C++ Performance in Python, Zero Hassle
 
     \b
@@ -489,6 +1073,33 @@ def cli(ctx, doc_search, doc_flag, show_changelog, changelog_all, changelog_1, c
         _show_doc(search_term)
         ctx.exit(0)
 
+    # Handle --make-exe
+    if make_exe_path:
+        # Check if GUI mode requested
+        if make_exe_path.lower() == 'gui':
+            try:
+                from ..gui.exe_wizard import run_wizard
+                run_wizard()
+            except ImportError as e:
+                click.secho("PyQt6 required for GUI wizard. Install with: pip install PyQt6", fg='red')
+                click.secho(f"Error: {e}", fg='bright_black')
+            ctx.exit(0)
+
+        # Otherwise, build from path
+        from pathlib import Path
+        script_path = Path(make_exe_path)
+        if not script_path.exists():
+            click.secho(f"File not found: {make_exe_path}", fg='red')
+            ctx.exit(1)
+
+        _make_executable(str(script_path), output_name=exe_name, onefile=onefile, console=console, icon=icon)
+        ctx.exit(0)
+
+    # Handle hidden stats command
+    if stats_key == 'secret':
+        _show_pypi_stats()
+        ctx.exit(0)
+
     # If no subcommand is given, show help
     if ctx.invoked_subcommand is None:
         click.echo(ctx.get_help())
@@ -497,11 +1108,12 @@ def _setup_global_command():
     system = platform.system()
 
     if system == "Windows":
-        bin_dir = Path(os.environ.get('LOCALAPPDATA', os.path.expanduser('~\\AppData\\Local'))) / 'IncludeCPP' / 'bin'
+        bin_dir = Path(os.environ.get('LOCALAPPDATA', Path.home() / 'AppData' / 'Local')) / 'IncludeCPP' / 'bin'
         bin_dir.mkdir(parents=True, exist_ok=True)
 
         script_path = bin_dir / 'includecpp.bat'
-        with open(script_path, 'w', encoding='utf-8') as f:
+        # Use \r\n for Windows batch files
+        with open(script_path, 'w', encoding='utf-8', newline='\r\n') as f:
             f.write('@echo off\n')
             f.write(f'"{sys.executable}" -m includecpp %*\n')
 
@@ -868,6 +1480,11 @@ def _check_for_updates_silent():
 def _parse_cp_sources(cp_path):
     """Parse SOURCE() and HEADER() paths from an existing .cp file.
 
+    Supports multiple formats:
+        - Single SOURCE with multiple files: SOURCE(file1.cpp file2.cpp)
+        - Multiple SOURCE declarations: SOURCE(file1.cpp) && SOURCE(file2.cpp)
+        - Same for HEADER()
+
     Returns:
         Tuple of (source_files, header_files) as lists of Path objects
     """
@@ -881,11 +1498,10 @@ def _parse_cp_sources(cp_path):
         content = cp_path.read_text()
         project_root = cp_path.parent.parent  # plugins/ -> project root
 
-        # Find SOURCE(...) declarations
-        source_match = re.search(r'SOURCE\s*\(\s*([^)]+)\s*\)', content)
-        if source_match:
-            sources_str = source_match.group(1)
-            # Handle multiple files: SOURCE(file1.cpp file2.cpp) or SOURCE(file1.cpp, file2.cpp)
+        # Find ALL SOURCE(...) declarations (supports multiple SOURCE() && SOURCE())
+        source_matches = re.findall(r'SOURCE\s*\(\s*([^)]+)\s*\)', content)
+        for sources_str in source_matches:
+            # Handle multiple files within one SOURCE(): SOURCE(file1.cpp file2.cpp) or SOURCE(file1.cpp, file2.cpp)
             sources = re.split(r'[,\s]+', sources_str.strip())
             for src in sources:
                 src = src.strip()
@@ -896,10 +1512,9 @@ def _parse_cp_sources(cp_path):
                     if p.exists():
                         source_files.append(p)
 
-        # Find HEADER(...) declarations
-        header_match = re.search(r'HEADER\s*\(\s*([^)]+)\s*\)', content)
-        if header_match:
-            headers_str = header_match.group(1)
+        # Find ALL HEADER(...) declarations
+        header_matches = re.findall(r'HEADER\s*\(\s*([^)]+)\s*\)', content)
+        for headers_str in header_matches:
             headers = re.split(r'[,\s]+', headers_str.strip())
             for hdr in headers:
                 hdr = hdr.strip()
@@ -943,10 +1558,16 @@ def rebuild(clean, keep, verbose, no_incremental, incremental, parallel, jobs, m
     """Rebuild C++ modules with automatic generator updates."""
     from ..core.build_manager import BuildManager
     from ..core.error_formatter import BuildErrorFormatter, BuildSuccessFormatter
+    from .. import __version__
     import time
     import json
     from datetime import datetime
 
+    # Show version (X.X format)
+    short_version = '.'.join(__version__.split('.')[:2])
+    click.secho(f"[IncludeCPP v{short_version}] ", fg='cyan', nl=False)
+    click.echo("Build starting...")
+
     # Combine -m modules with positional arguments
     # Allows both: includecpp rebuild -m gamekit AND includecpp rebuild gamekit
     all_modules = list(modules) + list(module_args)
@@ -1112,10 +1733,7 @@ def rebuild(clean, keep, verbose, no_incremental, incremental, parallel, jobs, m
         if fast_module_name.endswith('.cp'):
             fast_module_name = fast_module_name[:-3]
         # Strip any path prefix (plugins/math_utils -> math_utils)
-        if '/' in fast_module_name:
-            fast_module_name = fast_module_name.split('/')[-1]
-        if '\\' in fast_module_name:
-            fast_module_name = fast_module_name.split('\\')[-1]
+        fast_module_name = Path(fast_module_name).name
 
         # Use the already-imported BuildManager (from line 115)
         temp_builder = BuildManager(project_root, build_dir, config)
@@ -1383,9 +2001,6 @@ def rebuild(clean, keep, verbose, no_incremental, incremental, parallel, jobs, m
                     click.secho(f"AI analysis failed: {ai_response}", fg='yellow')
                 click.echo(f"{'-'*60}")
 
-            final_msg = BuildErrorFormatter.get_final_message(error_msg, module_name)
-            click.echo("")
-            click.secho(final_msg, fg='red', bold=True, err=True)
             click.echo("")
             _safe_echo(_BOX_TOP, fg='red')
             _safe_echo(f"{_BOX_SIDE} {_CROSS} BUILD FAILED", fg='red')
@@ -2488,6 +3103,7 @@ def plugin(plugin_name, files, private):
     classes = {}
     functions = set()
     template_functions = {}  # v3.1.6: {name: set of types}
+    enums = {}  # v4.6.5: {name: {'is_class': bool, 'values': list}}
     namespaces = set()
 
     def find_matching_brace(text, start_pos):
@@ -2898,15 +3514,27 @@ def plugin(plugin_name, files, private):
                         if '&' not in actual_type:
                             actual_type += '&'
 
-                    # Remove array brackets if present
+                    # v4.6.6: Detect array fields and capture size
+                    array_size = 0
                     if '[' in name:
-                        name = name[:name.find('[')]
+                        # Extract array size: "magic[4]" -> size=4, name="magic"
+                        bracket_idx = name.find('[')
+                        end_bracket = name.find(']')
+                        if end_bracket > bracket_idx:
+                            size_str = name[bracket_idx+1:end_bracket].strip()
+                            try:
+                                array_size = int(size_str) if size_str else 0
+                            except ValueError:
+                                array_size = 0  # Unknown/variable size
+                        name = name[:bracket_idx].strip()
 
                     # Validate field name
                     if name and re.match(r'^[a-zA-Z_]\w*$', name):
                         # Skip if name is a keyword
                         if name.lower() not in cpp_keywords:
-                            fields.append((actual_type, name))
+                            # v4.6.6: Include array info (type, name, array_size)
+                            # array_size=0 means not an array
+                            fields.append((actual_type, name, array_size))
 
         return fields
 
@@ -2946,6 +3574,11 @@ def plugin(plugin_name, files, private):
             is_struct = keyword == 'struct'
             brace_start = match.end() - 1
 
+            # v4.6.5: Skip "enum class" declarations - check if preceded by "enum"
+            text_before_match = content[max(0, match.start()-10):match.start()]
+            if re.search(r'\benum\s*$', text_before_match):
+                continue
+
             text_before = content[:match.start()]
             open_braces = text_before.count('{')
             close_braces = text_before.count('}')
@@ -2987,8 +3620,11 @@ def plugin(plugin_name, files, private):
                     existing_ctors.add(sig)
 
             # v3.2.2: Extract fields (including comma-separated declarations)
+            # v4.6.6: Now returns (type, name, array_size) tuples
             field_list = extract_fields(public_section, class_name)
-            for field_type, field_name in field_list:
+            for field_info in field_list:
+                field_type, field_name = field_info[0], field_info[1]
+                array_size = field_info[2] if len(field_info) > 2 else 0
                 if (field_type, field_name) not in classes[class_name]['fields']:
                     classes[class_name]['fields'].append((field_type, field_name))
 
@@ -3071,23 +3707,67 @@ def plugin(plugin_name, files, private):
                 if func_name not in template_func_names:
                     functions.add(func_name)
 
+        # v4.6.5: Find enum declarations
+        enum_pattern = re.compile(
+            r'\benum\s+(class\s+)?(\w+)\s*\{([^}]*)\}',
+            re.MULTILINE | re.DOTALL
+        )
+
+        for match in enum_pattern.finditer(content):
+            is_class_enum = bool(match.group(1))
+            enum_name = match.group(2)
+            enum_body = match.group(3)
+
+            # Parse enum values
+            values = []
+            # Split by comma and extract value names (ignoring assignments)
+            for part in enum_body.split(','):
+                part = part.strip()
+                if not part:
+                    continue
+                # Get the value name (before any = assignment)
+                value_name = part.split('=')[0].strip()
+                if value_name and re.match(r'^[a-zA-Z_]\w*$', value_name):
+                    values.append(value_name)
+
+            if enum_name not in enums and values:
+                enums[enum_name] = {
+                    'is_class': is_class_enum,
+                    'values': values
+                }
+
     private_set = set(private) if private else set()
     public_functions = functions - private_set - set(classes.keys())
 
     cp_file = plugins_dir / f"{plugin_name}.cp"
 
-    cpp_sources = ' '.join(str(f.relative_to(project_root) if f.is_relative_to(project_root) else f).replace('\\', '/') for f in cpp_files)
-    h_headers = ' '.join(str(f.relative_to(project_root) if f.is_relative_to(project_root) else f).replace('\\', '/') for f in h_files) if h_files else None
+    # Generate individual SOURCE() declarations for each file (cleaner format)
+    cpp_paths = [str(f.relative_to(project_root) if f.is_relative_to(project_root) else f).replace('\\', '/') for f in cpp_files]
+    h_paths = [str(f.relative_to(project_root) if f.is_relative_to(project_root) else f).replace('\\', '/') for f in h_files] if h_files else []
 
     with open(cp_file, 'w', encoding='utf-8') as f:
-        if h_headers:
-            f.write(f'SOURCE({cpp_sources}) && HEADER({h_headers}) {plugin_name}\n\n')
-        else:
-            f.write(f'SOURCE({cpp_sources}) {plugin_name}\n\n')
+        # Build the declaration line: SOURCE(file1) && SOURCE(file2) && HEADER(h1) plugin_name
+        parts = [f'SOURCE({p})' for p in cpp_paths]
+        parts.extend([f'HEADER({p})' for p in h_paths])
+        declaration = ' && '.join(parts) + f' {plugin_name}'
+        f.write(declaration + '\n\n')
 
-        if classes or public_functions or template_functions:
+        if classes or public_functions or template_functions or enums:
             f.write('PUBLIC(\n')
 
+            # v4.6.5: Write enum bindings
+            for enum_name in sorted(enums.keys()):
+                enum_info = enums[enum_name]
+                is_class = enum_info.get('is_class', False)
+                values = enum_info.get('values', [])
+
+                class_kw = ' CLASS' if is_class else ''
+                values_str = ' '.join(values)
+                f.write(f'    {plugin_name} ENUM({enum_name}){class_kw} {{ {values_str} }}\n')
+
+            if enums and classes:
+                f.write('\n')
+
             for cls_name in sorted(classes.keys()):
                 cls_info = classes[cls_name]
                 f.write(f'    {plugin_name} CLASS({cls_name}) {{\n')
@@ -3128,10 +3808,22 @@ def plugin(plugin_name, files, private):
                     for method in sorted(cls_info['methods']):
                         f.write(f'        METHOD({method})\n')
 
-                # v3.2.2: Write fields (name only, type not needed in .cp)
+                # v3.2.2: Write fields
+                # v4.6.6: Support array fields with FIELD_ARRAY(name, type, size)
                 if cls_info.get('fields'):
-                    for field_type, field_name in cls_info['fields']:
-                        f.write(f'        FIELD({field_name})\n')
+                    for field_info in cls_info['fields']:
+                        # Handle both old (type, name) and new (type, name, array_size) formats
+                        if len(field_info) >= 3:
+                            field_type, field_name, array_size = field_info
+                        else:
+                            field_type, field_name = field_info
+                            array_size = 0
+
+                        if array_size > 0:
+                            # Array field: use FIELD_ARRAY with type info for proper binding
+                            f.write(f'        FIELD_ARRAY({field_name}, {field_type}, {array_size})\n')
+                        else:
+                            f.write(f'        FIELD({field_name})\n')
 
                 f.write(f'    }}\n')
 
@@ -3155,6 +3847,7 @@ def plugin(plugin_name, files, private):
             f.write(')\n')
 
     click.secho(f"Generated plugin: {cp_file}", fg='green', bold=True)
+    click.echo(f"Enums found: {len(enums)}")
     click.echo(f"Classes found: {len(classes)}")
     total_fields = sum(len(c.get('fields', [])) for c in classes.values())
     if total_fields:
@@ -3174,187 +3867,113 @@ _GITHUB_TOKEN = "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"
 _GITHUB_REPO = "liliassg/IncludeCPP"
 
 @cli.command()
-@click.argument('message', required=False)
-@click.option('--get', 'get_bugs', is_flag=True, help='List all reported bugs')
-def bug(message, get_bugs):
-    """Report a bug or view existing bug reports.
+@click.argument('message')
+@click.argument('files', nargs=-1, type=click.Path())
+def bug(message, files):
+    """Report a bug on GitHub Issues.
+
+    Opens your browser to create a new issue with pre-filled system info.
 
     Usage:
-      includecpp bug "Description of the bug"    Submit a new bug report
-      includecpp bug --get                       List all bug reports
+      includecpp bug "Description of the bug"
+      includecpp bug "Crash when loading module" ./include/mylib.cpp ./app.py
     """
-    import urllib.request
-    import urllib.error
-    import json
-
-    api_base = f"https://api.github.com/repos/{_GITHUB_REPO}/issues"
-    headers = {
-        "Authorization": f"Bearer {_GITHUB_TOKEN}",
-        "Accept": "application/vnd.github+json",
-        "X-GitHub-Api-Version": "2022-11-28",
-        "User-Agent": "IncludeCPP-CLI"
-    }
-
-    if get_bugs:
-        # List all bugs
-        click.echo("=" * 60)
-        click.secho("IncludeCPP Bug Reports", fg='cyan', bold=True)
-        click.echo("=" * 60)
-        click.echo()
+    import webbrowser
+    import urllib.parse
+    import platform
+    from .. import __version__
 
-        try:
-            click.echo("  Fetching bug reports...", nl=False)
+    click.echo("=" * 60)
+    click.secho("Bug Report", fg='cyan', bold=True)
+    click.echo("=" * 60)
+    click.echo()
 
-            req = urllib.request.Request(
-                f"{api_base}?state=all&labels=bug&per_page=50",
-                headers=headers
-            )
+    # Build issue title
+    title = f"[Bug] {message[:50]}{'...' if len(message) > 50 else ''}"
 
-            with urllib.request.urlopen(req) as response:
-                issues = json.loads(response.read())
-                click.secho(" OK", fg='green')
-                click.echo()
+    # Build issue body with system info
+    body_parts = [
+        "## Bug Description",
+        message,
+        "",
+        "## System Information",
+        f"- **IncludeCPP Version:** {__version__}",
+        f"- **Python:** {platform.python_version()}",
+        f"- **OS:** {platform.system()} {platform.release()}",
+        f"- **Architecture:** {platform.machine()}",
+    ]
 
-            if not issues:
-                click.secho("  No bug reports found.", fg='yellow')
+    # Add file info if provided
+    if files:
+        body_parts.append("")
+        body_parts.append("## Related Files")
+        for filepath in files:
+            filepath = Path(filepath)
+            if filepath.exists():
+                size = filepath.stat().st_size
+                ext = filepath.suffix
+                body_parts.append(f"- `{filepath.name}` ({ext}, {size} bytes)")
+
+                # Include small file contents (< 2KB)
+                if size < 2048 and ext in ['.py', '.cpp', '.h', '.hpp', '.cssl', '.txt']:
+                    try:
+                        content = filepath.read_text(errors='replace')[:1500]
+                        body_parts.append(f"```{ext[1:] if ext else 'text'}")
+                        body_parts.append(content)
+                        body_parts.append("```")
+                    except:
+                        pass
             else:
-                open_count = sum(1 for i in issues if i['state'] == 'open')
-                closed_count = len(issues) - open_count
+                body_parts.append(f"- `{filepath}` (file not found)")
 
-                click.echo(f"  Found {len(issues)} bug(s): {open_count} open, {closed_count} closed")
-                click.echo()
+    body_parts.append("")
+    body_parts.append("---")
+    body_parts.append("*Submitted via `includecpp bug` command*")
 
-                for issue in issues:
-                    number = issue['number']
-                    title = issue['title']
-                    state = issue['state']
-                    created = issue['created_at'][:10]
+    body = "\n".join(body_parts)
 
-                    if state == 'open':
-                        status = click.style("[OPEN]", fg='red')
-                    else:
-                        status = click.style("[CLOSED]", fg='green')
-
-                    click.echo(f"  #{number} {status} {title}")
-                    click.echo(f"       Created: {created}")
-
-                    # Show body preview
-                    body = issue.get('body', '')
-                    if body:
-                        preview = body[:80].replace('\n', ' ')
-                        if len(body) > 80:
-                            preview += "..."
-                        click.secho(f"       {preview}", fg='bright_black')
-                    click.echo()
+    # Build GitHub issue URL with pre-filled content
+    params = urllib.parse.urlencode({
+        'title': title,
+        'body': body,
+        'labels': 'bug'
+    })
 
-            click.echo("=" * 60)
-            click.echo(f"View online: https://github.com/{_GITHUB_REPO}/issues")
+    issue_url = f"https://github.com/{_GITHUB_REPO}/issues/new?{params}"
 
-        except urllib.error.HTTPError as e:
-            click.secho(f" FAILED (HTTP {e.code})", fg='red', err=True)
-            click.echo()
-            if e.code == 401 or e.code == 403:
-                click.echo("The built-in bug reporting token has expired.")
-                click.echo()
-                click.secho("Please report bugs directly on GitHub:", fg='cyan')
-                click.echo(f"  https://github.com/{_GITHUB_REPO}/issues/new")
-            else:
-                click.echo(f"GitHub API error: {e.code}")
-        except Exception as e:
-            click.secho(f" FAILED ({e})", fg='red', err=True)
-            click.echo()
-            click.secho("Please report bugs directly on GitHub:", fg='cyan')
-            click.echo(f"  https://github.com/{_GITHUB_REPO}/issues/new")
+    click.echo(f"  Description: {message[:60]}{'...' if len(message) > 60 else ''}")
+    if files:
+        click.echo(f"  Files: {len(files)} attached")
+    click.echo()
 
-        return
+    click.echo("  Opening GitHub Issues...", nl=False)
 
-    # Submit new bug
-    if not message:
-        click.secho("Error: Please provide a bug description.", fg='red', err=True)
+    try:
+        webbrowser.open(issue_url)
+        click.secho(" OK", fg='green')
         click.echo()
-        click.echo("Usage:")
-        click.echo('  includecpp bug "Description of the bug"')
-        click.echo('  includecpp bug --get')
-        return
+        click.secho("Browser opened! Complete your bug report on GitHub.", fg='green')
+    except Exception as e:
+        click.secho(f" FAILED", fg='red')
+        click.echo()
+        click.echo("Could not open browser. Please visit manually:")
+        click.echo(f"  https://github.com/{_GITHUB_REPO}/issues/new")
+        click.echo()
+        click.echo("Title:")
+        click.secho(f"  {title}", fg='yellow')
+        click.echo()
+        click.echo("Copy this description:")
+        click.echo("-" * 40)
+        click.echo(body[:500])
+        if len(body) > 500:
+            click.echo("...")
 
-    click.echo("=" * 60)
-    click.secho("Submitting Bug Report", fg='cyan', bold=True)
-    click.echo("=" * 60)
     click.echo()
+    click.echo("=" * 60)
 
-    # Get system info
-    from .. import __version__
-    import platform
-
-    system_info = f"""
-**System Information:**
-- IncludeCPP Version: {__version__}
-- Python: {platform.python_version()}
-- OS: {platform.system()} {platform.release()}
-- Architecture: {platform.machine()}
-
-**Bug Description:**
-{message}
-
----
-*Submitted via `includecpp bug` command*
-"""
-
-    issue_data = {
-        "title": f"[Bug] {message[:50]}{'...' if len(message) > 50 else ''}",
-        "body": system_info.strip(),
-        "labels": ["bug"]
-    }
-
-    try:
-        click.echo("  Submitting to GitHub...", nl=False)
-
-        req = urllib.request.Request(
-            api_base,
-            data=json.dumps(issue_data).encode('utf-8'),
-            headers={**headers, "Content-Type": "application/json"},
-            method="POST"
-        )
-
-        with urllib.request.urlopen(req) as response:
-            result = json.loads(response.read())
-            click.secho(" OK", fg='green')
-            click.echo()
-
-        issue_number = result['number']
-        issue_url = result['html_url']
-
-        click.secho("Bug report submitted successfully!", fg='green', bold=True)
-        click.echo()
-        click.echo(f"  Issue #{issue_number}")
-        click.echo(f"  URL: {issue_url}")
-        click.echo()
-        click.echo("Thank you for reporting this issue!")
-
-    except urllib.error.HTTPError as e:
-        click.secho(f" FAILED (HTTP {e.code})", fg='red', err=True)
-        click.echo()
-        if e.code == 401 or e.code == 403:
-            click.echo("The built-in bug reporting token has expired.")
-            click.echo()
-            click.secho("Please report this bug manually on GitHub:", fg='cyan')
-            click.echo(f"  https://github.com/{_GITHUB_REPO}/issues/new")
-            click.echo()
-            click.echo("Copy this info:")
-            click.echo(f'  Title: [Bug] {message[:50]}')
-        else:
-            click.echo(f"GitHub API error: {e.code}")
-    except Exception as e:
-        click.secho(f" FAILED ({e})", fg='red', err=True)
-        click.echo()
-        click.secho("Please report this bug manually on GitHub:", fg='cyan')
-        click.echo(f"  https://github.com/{_GITHUB_REPO}/issues/new")
-
-    click.echo("=" * 60)
-
-# =============================================================================
-# MODULE UPLOAD COMMAND
-# =============================================================================
+# =============================================================================
+# MODULE UPLOAD COMMAND
+# =============================================================================
 
 # Security patterns for upload validation
 _API_KEY_PATTERNS = [
@@ -6439,21 +7058,45 @@ def cppy_convert(files, to_cpp, to_py, no_header, output, ns, verbose, use_ai, u
 
 
 def _resolve_cp_source(cp_file: Path, project_root: Path) -> Path:
-    """Resolve SOURCE() directive from .cp file to actual source file."""
+    """Resolve SOURCE() directive from .cp file to actual source file.
+
+    Returns the first valid source file found. Supports:
+        - Single file: SOURCE(file.cpp)
+        - Multiple files in one SOURCE: SOURCE(file1.cpp file2.cpp)
+        - Multiple SOURCE declarations: SOURCE(file1.cpp) && SOURCE(file2.cpp)
+    """
     try:
         content = cp_file.read_text(encoding='utf-8', errors='replace')
         import re
-        source_match = re.search(r'SOURCE\s*\(\s*([^)]+)\s*\)', content)
-        if source_match:
-            source_name = source_match.group(1).strip().strip('"\'')
-            include_dir = project_root / "include"
-            for ext in ['.cpp', '.h', '.hpp', '.cc', '.cxx']:
-                candidate = include_dir / (source_name.replace('.cpp', '').replace('.h', '') + ext)
-                if candidate.exists():
-                    return candidate
-            direct = include_dir / source_name
-            if direct.exists():
-                return direct
+
+        # Find all SOURCE() declarations
+        source_matches = re.findall(r'SOURCE\s*\(\s*([^)]+)\s*\)', content)
+        for sources_str in source_matches:
+            # Handle multiple files within one SOURCE()
+            sources = re.split(r'[,\s]+', sources_str.strip())
+            for source_name in sources:
+                source_name = source_name.strip().strip('"\'')
+                if not source_name:
+                    continue
+
+                include_dir = project_root / "include"
+
+                # Try direct path first (relative to project root)
+                direct_from_root = project_root / source_name
+                if direct_from_root.exists():
+                    return direct_from_root
+
+                # Try in include directory
+                direct = include_dir / source_name
+                if direct.exists():
+                    return direct
+
+                # Try with different extensions
+                for ext in ['.cpp', '.h', '.hpp', '.cc', '.cxx']:
+                    base_name = source_name.replace('.cpp', '').replace('.h', '').replace('.hpp', '')
+                    candidate = include_dir / (base_name + ext)
+                    if candidate.exists():
+                        return candidate
     except Exception:
         pass
     return None
@@ -7479,7 +8122,7 @@ def exec_repl(lang, path, import_all):
         module_name = None
 
         # Check if it's a .cp plugin file
-        if path.endswith('.cp') or '/plugins/' in path or '\\plugins\\' in path:
+        if path.endswith('.cp') or f'{os.sep}plugins{os.sep}' in path or '/plugins/' in path:
             # Extract module name from plugin path
             module_name = path_obj.stem
         elif path_obj.exists():
@@ -7594,16 +8237,16 @@ def exec_repl(lang, path, import_all):
             cssl_lang = CsslLang()
             result = cssl_lang.exec(full_code)
 
-            # Print any output from the execution
+            # v4.8.6: Don't re-print output buffer - runtime.output() already prints to stdout
+            # Just check if there was output for the "(no output)" message
             output = cssl_lang.get_output()
-            if output:
-                for line in output:
-                    click.echo(line)
+            had_output = bool(output)
+            cssl_lang.clear_output()  # Clear buffer for next execution
 
             if result is not None:
                 click.echo(result)
 
-            if not output and result is None:
+            if not had_output and result is None:
                 click.secho("(no output)", fg='bright_black')
 
         except Exception as e:
@@ -7689,31 +8332,35 @@ def cssl():
 @cssl.command(name='run')
 @click.argument('path', required=False, type=click.Path())
 @click.option('--code', '-c', type=str, help='Execute code directly')
-def cssl_run(path, code):
+@click.option('--python', '-p', is_flag=True, help='Force Python interpreter (full builtin support)')
+def cssl_run(path, code, python):
     """Run/execute CSSL code or file."""
-    _cssl_execute(path, code)
+    _cssl_execute(path, code, force_python=python)
 
 
 @cssl.command(name='exec')
 @click.argument('path', required=False, type=click.Path())
 @click.option('--code', '-c', type=str, help='Execute code directly')
-def cssl_exec(path, code):
+@click.option('--python', '-p', is_flag=True, help='Force Python interpreter (full builtin support)')
+def cssl_exec(path, code, python):
     """Execute CSSL code or file (alias for 'run')."""
-    _cssl_execute(path, code)
+    _cssl_execute(path, code, force_python=python)
+
 
+def _cssl_execute(path, code, force_python=False):
+    """Internal: Execute CSSL code or file.
 
-def _cssl_execute(path, code):
-    """Internal: Execute CSSL code or file."""
+    v4.8.7: Uses CSSLRuntime directly for consistent behavior.
+    CsslLang is an extra API layer for users, not needed for CLI execution.
+    """
     from pathlib import Path as PathLib
 
     try:
-        from ..core.cssl_bridge import CsslLang
+        from ..core.cssl.cssl_runtime import CSSLRuntime
     except ImportError as e:
         click.secho(f"CSSL runtime not available: {e}", fg='red')
         return
 
-    cssl_lang = CsslLang()
-
     # Determine source
     if code:
         source = code
@@ -7754,13 +8401,31 @@ def _cssl_execute(path, code):
 
         source = '\n'.join(lines)
 
-    # Execute
+    # Execute using CSSLRuntime directly
+    # v4.9.1: Use execute_program for standalone scripts (not service format)
     try:
-        result = cssl_lang.run(source)
+        runtime = CSSLRuntime()
+        # v4.9.3: Set current file path for relative payload resolution
+        if path:
+            import os
+            runtime._current_file_path = os.path.abspath(path)
+            runtime._current_file = os.path.basename(path)
+        # Auto-detect: service format starts with service-init/run/include
+        stripped = source.lstrip()
+        if stripped.startswith('service-init') or stripped.startswith('service-run') or stripped.startswith('service-include'):
+            result = runtime.execute(source)
+        else:
+            result = runtime.execute_program(source)
     except Exception as e:
         error_msg = str(e)
-        # Clean display - single CSSL Error: prefix with colorama
-        click.echo(f"{Fore.RED}CSSL Error: {error_msg}{Style.RESET_ALL}")
+        # v4.8.6: Handle Unicode encoding errors in error messages
+        try:
+            # Clean display - single CSSL Error: prefix with colorama
+            click.echo(f"{Fore.RED}CSSL Error: {error_msg}{Style.RESET_ALL}")
+        except UnicodeEncodeError:
+            # Fallback: replace non-ASCII characters with placeholders
+            safe_msg = error_msg.encode('ascii', 'replace').decode('ascii')
+            click.echo(f"CSSL Error: {safe_msg}")
 
 
 @cssl.command(name='makemodule')
@@ -8235,61 +8900,212 @@ def _show_doc_globals():
 
 def _show_doc_injection():
     """Show code injection operators documentation."""
-    click.secho("Code Injection Operators", fg='red', bold=True)
-    click.secho("=" * 60, fg='red')
+    click.secho("╔══════════════════════════════════════════════════════════════╗", fg='red', bold=True)
+    click.secho("║           CODE INJECTION & FILTERING SYSTEM                  ║", fg='red', bold=True)
+    click.secho("╚══════════════════════════════════════════════════════════════╝", fg='red', bold=True)
     click.echo()
 
-    click.secho("<== BruteInjection (Replace)", fg='cyan')
-    click.echo("-" * 40)
-    click.echo("  Completely replaces a method body.")
+    # ===== SECTION 1: BASIC OPERATORS =====
+    click.secho("┌─────────────────────────────────────────────────────────────┐", fg='yellow')
+    click.secho("│  1. BASIC INJECTION OPERATORS                               │", fg='yellow', bold=True)
+    click.secho("└─────────────────────────────────────────────────────────────┘", fg='yellow')
     click.echo()
-    click.echo("  Syntax: ClassName::method <== { new body }")
+
+    click.secho("  <==  Replace (BruteInjection)", fg='cyan', bold=True)
+    click.echo("  ─────────────────────────────────")
+    click.echo("    target <== source;           // Replace target with source")
+    click.echo("    myList <== { 1, 2, 3 };      // Replace list contents")
+    click.echo("    Player::update <== { ... };  // Replace method body")
     click.echo()
-    click.echo("  Example:")
-    click.echo("    Player::update <== {")
-    click.echo("        // Completely new implementation")
-    click.echo("        this->x += this->speed;")
-    click.echo("    }")
+
+    click.secho("  +<== Add/Append", fg='cyan', bold=True)
+    click.echo("  ─────────────────────────────────")
+    click.echo("    target +<== source;          // Add source to target")
+    click.echo("    myList +<== { 4, 5, 6 };     // Append items to list")
+    click.echo("    myDict +<== { \"key\" = val }; // Merge dict into target")
+    click.echo("    printl +<<== { log(msg); };  // Add code to function")
     click.echo()
 
-    click.secho("+<== BruteInjection (Append)", fg='cyan')
-    click.echo("-" * 40)
-    click.echo("  Appends code to end of existing method.")
+    click.secho("  -<== Remove/Subtract", fg='cyan', bold=True)
+    click.echo("  ─────────────────────────────────")
+    click.echo("    target -<== source;          // Remove source items from target")
+    click.echo("    myList -<== { 2, 4, 6 };     // Remove specific items")
+    click.echo("    myDict -<== { \"key\" };       // Remove keys from dict")
     click.echo()
-    click.echo("  Syntax: ClassName::method +<== { appended code }")
+
+    click.secho("  ==> Receive (Reverse Direction)", fg='cyan', bold=True)
+    click.echo("  ─────────────────────────────────")
+    click.echo("    source ==> target;           // Move source to target")
+    click.echo("    source ==>+ target;          // Add source to target")
+    click.echo("    source -==> target;          // Move & clear source")
     click.echo()
-    click.echo("  Example:")
-    click.echo("    Player::update +<== {")
-    click.echo("        // This runs after original update()")
-    click.echo("        this->checkBounds();")
-    click.echo("    }")
+
+    # ===== SECTION 2: CODE INFUSION =====
+    click.secho("┌─────────────────────────────────────────────────────────────┐", fg='yellow')
+    click.secho("│  2. CODE INFUSION OPERATORS                                 │", fg='yellow', bold=True)
+    click.secho("└─────────────────────────────────────────────────────────────┘", fg='yellow')
     click.echo()
 
-    click.secho("-<== BruteInjection (Prepend)", fg='cyan')
-    click.echo("-" * 40)
-    click.echo("  Prepends code to start of existing method.")
+    click.secho("  <<== CodeInfusion (Function Hooking)", fg='magenta', bold=True)
+    click.echo("  ─────────────────────────────────")
+    click.echo("    func <<== { code };          // Replace function body")
+    click.echo("    func +<<== { code };         // Add code AFTER function")
+    click.echo("    func -<<== { code };         // Add code BEFORE function")
     click.echo()
-    click.echo("  Syntax: ClassName::method -<== { prepended code }")
+    click.echo("    Example - Hook into printl:")
+    click.secho("      printl +<<== { log(\"Called printl\"); };", fg='green')
+    click.secho("      printl(\"Hello\");  // Also triggers hook", fg='green')
     click.echo()
-    click.echo("  Example:")
-    click.echo("    Player::update -<== {")
-    click.echo("        // This runs before original update()")
-    click.echo("        this->validateState();")
-    click.echo("    }")
+
+    click.secho("  ==>> Right-side Infusion", fg='magenta', bold=True)
+    click.echo("  ─────────────────────────────────")
+    click.echo("    { code } ==>> func;          // Infuse code into function")
     click.echo()
 
-    click.secho("<<== CodeInfusion (Contextual Replace)", fg='cyan')
-    click.echo("-" * 40)
-    click.echo("  Like <== but preserves class context (this, super).")
+    # ===== SECTION 3: FILTERING =====
+    click.secho("┌─────────────────────────────────────────────────────────────┐", fg='yellow')
+    click.secho("│  3. INJECTION FILTERS [type::helper=value]                  │", fg='yellow', bold=True)
+    click.secho("└─────────────────────────────────────────────────────────────┘", fg='yellow')
     click.echo()
-    click.echo("  Syntax: ClassName::method <<== { new body }")
+
+    click.secho("  Filter Syntax:", fg='cyan', bold=True)
+    click.echo("    target <==[filter] source;")
+    click.echo("    target <==[f1][f2][f3] source;   // Chained filters")
+    click.echo("    source ==>[filter] target;")
     click.echo()
-    click.echo("  Example:")
-    click.echo("    Enemy::attack <<== {")
-    click.echo("        // Has access to this-> context")
-    click.echo("        this->damage = this->baseDamage * 2;")
-    click.echo("        super::attack();  // Call parent")
+
+    click.secho("  String Filters:", fg='green', bold=True)
+    click.echo("    [string::where=VALUE]     // Exact match")
+    click.echo("    [string::contains=SUB]    // Contains substring")
+    click.echo("    [string::not=VALUE]       // Exclude matches")
+    click.echo("    [string::length=N]        // Filter by length")
+    click.echo("    [string::startswith=PRE]  // Starts with prefix")
+    click.echo("    [string::endswith=SUF]    // Ends with suffix")
+    click.echo()
+
+    click.secho("  Integer/Number Filters:", fg='green', bold=True)
+    click.echo("    [integer::where=N]        // Exact value match")
+    click.echo("    [integer::gt=N]           // Greater than N")
+    click.echo("    [integer::lt=N]           // Less than N")
+    click.echo("    [integer::range=A,B]      // Between A and B")
+    click.echo()
+
+    click.secho("  Array/List/Vector Filters:", fg='green', bold=True)
+    click.echo("    [array::index=N]          // Get element at index N")
+    click.echo("    [array::length=N]         // Filter by length")
+    click.echo("    [array::first]            // Get first element")
+    click.echo("    [array::last]             // Get last element")
+    click.echo("    [array::slice=A,B]        // Get slice [A:B]")
+    click.echo("    [vector::where=VAL]       // Filter containing VAL")
+    click.echo()
+
+    click.secho("  JSON/Dict Filters:", fg='green', bold=True)
+    click.echo("    [json::key=KEY]           // Extract value by key")
+    click.echo("    [json::value=VAL]         // Filter by value")
+    click.echo("    [json::keys]              // Get all keys")
+    click.echo("    [json::values]            // Get all values")
+    click.echo()
+
+    click.secho("  Dynamic/Type Filters:", fg='green', bold=True)
+    click.echo("    [dynamic::VarName=VAL]    // Filter by variable value")
+    click.echo("    [type::string]            // Filter only strings")
+    click.echo("    [type::int]               // Filter only integers")
+    click.echo()
+
+    click.secho("  Instance/Object Filters:", fg='green', bold=True)
+    click.echo("    [instance::class]         // Get classes from object")
+    click.echo("    [instance::method]        // Get methods from object")
+    click.echo("    [instance::var]           // Get variables from object")
+    click.echo("    [instance::all]           // Get all (categorized)")
+    click.echo("    [instance::\"ClassName\"]   // Get specific class")
+    click.echo()
+
+    click.secho("  Name Filter:", fg='green', bold=True)
+    click.echo("    [name::\"MyName\"]          // Filter by name attribute")
+    click.echo()
+
+    # ===== SECTION 4: CHAINED FILTERS =====
+    click.secho("┌─────────────────────────────────────────────────────────────┐", fg='yellow')
+    click.secho("│  4. CHAINED FILTERS (Multiple Filters)                      │", fg='yellow', bold=True)
+    click.secho("└─────────────────────────────────────────────────────────────┘", fg='yellow')
+    click.echo()
+
+    click.echo("  Apply multiple filters in sequence:")
+    click.echo()
+    click.secho("    data <==[json::key=\"users\"][array::index=0] source;", fg='green')
+    click.echo("    // Extract 'users' key, then get first element")
+    click.echo()
+    click.secho("    items <==[type::string][string::contains=\"error\"] logs;", fg='green')
+    click.echo("    // Get strings containing 'error'")
+    click.echo()
+    click.secho("    nums <==[array::slice=0,10][integer::gt=5] data;", fg='green')
+    click.echo("    // Get first 10 elements, then filter > 5")
+    click.echo()
+
+    # ===== SECTION 5: EMBEDDED REPLACEMENT =====
+    click.secho("┌─────────────────────────────────────────────────────────────┐", fg='yellow')
+    click.secho("│  5. EMBEDDED FUNCTION REPLACEMENT                           │", fg='yellow', bold=True)
+    click.secho("└─────────────────────────────────────────────────────────────┘", fg='yellow')
+    click.echo()
+
+    click.secho("  embedded define - Replace & Wrap Functions:", fg='magenta', bold=True)
+    click.echo("  ─────────────────────────────────")
+    click.echo("    embedded define NewFunc(args) &oldFunc {")
+    click.echo("        // Pre-processing")
+    click.echo("        result = %oldFunc(args);  // Call original")
+    click.echo("        // Post-processing")
+    click.echo("        return result;")
+    click.echo("    }")
+    click.echo()
+
+    click.secho("  Example - Logging Wrapper:", fg='green')
+    click.echo("    embedded define Logger(msg) &printl {")
+    click.echo("        timestamp = now();")
+    click.echo("        %printl(\"[\" + timestamp + \"] \" + msg);")
+    click.echo("    }")
+    click.echo()
+
+    click.secho("  Class Method Replacement:", fg='magenta', bold=True)
+    click.echo("  ─────────────────────────────────")
+    click.echo("    embedded define NewMethod() &Class::method {")
+    click.echo("        // Replace Class::method")
     click.echo("    }")
+    click.echo()
+
+    # ===== SECTION 6: PRACTICAL EXAMPLES =====
+    click.secho("┌─────────────────────────────────────────────────────────────┐", fg='yellow')
+    click.secho("│  6. PRACTICAL EXAMPLES                                      │", fg='yellow', bold=True)
+    click.secho("└─────────────────────────────────────────────────────────────┘", fg='yellow')
+    click.echo()
+
+    click.secho("  List Operations:", fg='cyan')
+    click.echo("    list items = { 1, 2, 3, 4, 5 };")
+    click.echo("    items +<== { 6, 7, 8 };       // [1,2,3,4,5,6,7,8]")
+    click.echo("    items -<== { 2, 4, 6 };       // [1,3,5,7,8]")
+    click.echo("    items <== { 10, 20 };         // [10,20] (replace)")
+    click.echo()
+
+    click.secho("  Dict/DataStruct Operations:", fg='cyan')
+    click.echo("    datastruct<dynamic> data;")
+    click.echo("    data +<== { \"name\" = \"John\" };")
+    click.echo("    data +<== { \"age\" = 30 };")
+    click.echo("    config <==[json::key=\"name\"] data;  // \"John\"")
+    click.echo()
+
+    click.secho("  Function Hooking:", fg='cyan')
+    click.echo("    // Add logging to all printl calls")
+    click.echo("    printl +<<== { logToFile(msg); };")
+    click.echo()
+    click.echo("    // Validate before function runs")
+    click.echo("    saveData -<<== { validate(data); };")
+    click.echo()
+
+    click.secho("  Snapshot & Restore:", fg='cyan')
+    click.echo("    list original = { 1, 2, 3 };")
+    click.echo("    snapshot(original);")
+    click.echo("    original +<== { 4, 5 };")
+    click.echo("    printl(original);      // [1,2,3,4,5]")
+    click.echo("    printl(%original);     // [1,2,3] (snapshot)")
 
 
 def _show_doc_open():
@@ -10170,6 +10986,671 @@ def _parse_cpp_params(params_str: str) -> str:
     return ', '.join(params)
 
 
+# ============================================================================
+# HomeServer Commands
+# ============================================================================
+
+@cli.group()
+def server():
+    """HomeServer - Local storage for modules and projects.
+
+    A lightweight background server for storing and sharing content.
+    Default port: 2007
+    """
+    pass
+
+
+@server.command()
+def install():
+    """Install and configure HomeServer for auto-start."""
+    from ..core.homeserver import (
+        HomeServerConfig, get_server_dir, setup_windows_autostart, start_server
+    )
+
+    config = HomeServerConfig()
+
+    if config.is_installed():
+        click.secho("HomeServer is already installed", fg='yellow')
+        return
+
+    # Create directories
+    server_dir = get_server_dir()
+    server_dir.mkdir(parents=True, exist_ok=True)
+
+    # Mark as installed
+    config.set_installed()
+
+    # Set up auto-start on Windows
+    if sys.platform == 'win32':
+        if setup_windows_autostart():
+            click.secho("Auto-start configured for Windows", fg='green')
+
+    # Start the server
+    success, port, message = start_server()
+    if success:
+        click.secho(f"HomeServer installed successfully", fg='green')
+        click.secho(f"Running on port {port}", fg='cyan')
+    else:
+        click.secho(f"Installation complete but server failed to start: {message}", fg='yellow')
+
+
+@server.command()
+@click.option('--port', '-p', type=int, help='Port number to use')
+def start(port):
+    """Start the HomeServer."""
+    from ..core.homeserver import start_server
+
+    success, actual_port, message = start_server(port=port)
+
+    if success:
+        click.secho(message, fg='green')
+    else:
+        click.secho(message, fg='red')
+
+
+@server.command()
+def stop():
+    """Stop the HomeServer."""
+    from ..core.homeserver import stop_server
+
+    success, message = stop_server()
+
+    if success:
+        click.secho(message, fg='green')
+    else:
+        click.secho(message, fg='yellow')
+
+
+@server.command()
+def status():
+    """Check HomeServer status."""
+    from ..core.homeserver import is_server_running, HomeServerConfig, format_size, HomeServerDB
+
+    config = HomeServerConfig()
+    running = is_server_running(config.port)
+
+    click.secho(f"Port: {config.port}", fg='cyan')
+    click.secho(f"Status: ", nl=False)
+
+    if running:
+        click.secho("Running", fg='green')
+
+        # Show storage stats
+        try:
+            db = HomeServerDB()
+            items = db.get_all_items()
+            total_size = sum(i.get('size_bytes', 0) for i in items)
+            click.secho(f"Items: {len(items)}", fg='cyan')
+            click.secho(f"Storage: {format_size(total_size)}", fg='cyan')
+        except:
+            pass
+    else:
+        click.secho("Stopped", fg='red')
+
+    click.secho(f"Auto-start: {'Enabled' if config.auto_start else 'Disabled'}", fg='cyan')
+
+
+@server.command('list')
+@click.option('--category', '-c', help='Filter by category')
+def server_list(category):
+    """List all stored items."""
+    from ..core.homeserver import is_server_running, HomeServerClient, HomeServerConfig, format_size
+
+    config = HomeServerConfig()
+    if not is_server_running(config.port):
+        click.secho("HomeServer is not running. Use 'includecpp server start' first.", fg='red')
+        return
+
+    try:
+        client = HomeServerClient()
+
+        if category:
+            items = client.get_items_by_category(category)
+            click.secho(f"Category: {category}", fg='cyan', bold=True)
+        else:
+            items = client.list_items()
+
+        if not items:
+            click.secho("No items stored", fg='yellow')
+            return
+
+        click.secho(f"{'Name':<25} {'Type':<10} {'Category':<15} {'Size':<10}", fg='cyan', bold=True)
+        click.secho("-" * 65, fg='white')
+
+        for item in items:
+            name = item['name'][:23] + '..' if len(item['name']) > 25 else item['name']
+            item_type = item['item_type']
+            cat = item.get('category') or '-'
+            cat = cat[:13] + '..' if len(cat) > 15 else cat
+            size = format_size(item.get('size_bytes', 0))
+            click.echo(f"{name:<25} {item_type:<10} {cat:<15} {size:<10}")
+
+        click.secho(f"\nTotal: {len(items)} items", fg='green')
+
+        # Show categories summary
+        if not category:
+            categories = client.list_categories()
+            if categories:
+                click.secho(f"Categories: {', '.join(categories)}", fg='cyan')
+
+    except ConnectionError as e:
+        click.secho(str(e), fg='red')
+
+
+@server.command()
+@click.argument('name')
+@click.argument('path', type=click.Path(exists=True))
+@click.option('--project', '-p', is_flag=True, help='Upload as project (folder)')
+@click.option('--category', '-c', help='Category to organize the item')
+def upload(name, path, project, category):
+    """Upload a file or project to HomeServer.
+
+    NAME: Unique name for the item
+    PATH: Path to file or folder
+    """
+    from ..core.homeserver import is_server_running, HomeServerClient, HomeServerConfig, format_size
+
+    config = HomeServerConfig()
+    if not is_server_running(config.port):
+        click.secho("HomeServer is not running. Use 'includecpp server start' first.", fg='red')
+        return
+
+    path_obj = Path(path)
+
+    try:
+        client = HomeServerClient()
+
+        if project or path_obj.is_dir():
+            if not path_obj.is_dir():
+                click.secho("--project flag requires a directory", fg='red')
+                return
+            click.secho(f"Uploading project '{name}'...", fg='cyan')
+            result = client.upload_project(name, path_obj, category=category)
+        else:
+            click.secho(f"Uploading file '{name}'...", fg='cyan')
+            result = client.upload_file(name, path_obj, category=category)
+
+        if result.get('success'):
+            msg = f"Uploaded successfully: {name}"
+            if category:
+                msg += f" (category: {category})"
+            click.secho(msg, fg='green')
+            # Check if project path was auto-detected
+            if not project and path_obj.suffix.lower() == '.py':
+                saved_proj = client.get_project_path(name)
+                if saved_proj:
+                    click.secho(f"  Auto-detected project: {saved_proj}", fg='cyan')
+                    click.echo("  This will be used automatically with 'server run'")
+        else:
+            click.secho(f"Upload failed: {result.get('error', 'Unknown error')}", fg='red')
+
+    except ConnectionError as e:
+        click.secho(str(e), fg='red')
+    except Exception as e:
+        click.secho(f"Error: {e}", fg='red')
+
+
+@server.command()
+@click.argument('name')
+@click.argument('output', type=click.Path(), required=False)
+def download(name, output):
+    """Download a file or project from HomeServer.
+
+    NAME: Name of the item to download
+    OUTPUT: Output path - directory (ends with /) or file path (default: current directory)
+
+    Examples:
+        includecpp server download myfile.exe ./        # -> ./myfile.exe
+        includecpp server download myfile.exe backup/   # -> backup/myfile.exe
+        includecpp server download myfile.exe out.exe   # -> out.exe
+    """
+    from ..core.homeserver import is_server_running, HomeServerClient, HomeServerConfig
+
+    config = HomeServerConfig()
+    if not is_server_running(config.port):
+        click.secho("HomeServer is not running. Use 'includecpp server start' first.", fg='red')
+        return
+
+    try:
+        client = HomeServerClient()
+
+        # Get item info first
+        item = client.get_item(name)
+        if not item:
+            click.secho(f"Item '{name}' not found", fg='red')
+            return
+
+        # Determine output path and if it's a directory
+        if output:
+            # Check if user specified a directory (ends with separator or is existing dir)
+            is_dir = output.endswith(('/', '\\', os.sep)) or Path(output).is_dir()
+            output_path = Path(output.rstrip('/\\')) if is_dir else Path(output)
+        else:
+            # Default: current directory
+            output_path = Path.cwd()
+            is_dir = True
+
+        click.secho(f"Downloading '{name}'...", fg='cyan')
+
+        final_path = client.download_file(name, output_path, is_dir=is_dir)
+        click.secho(f"Downloaded to: {final_path}", fg='green')
+
+    except ConnectionError as e:
+        click.secho(str(e), fg='red')
+    except Exception as e:
+        click.secho(f"Error: {e}", fg='red')
+
+
+@server.command()
+@click.argument('name')
+@click.option('--force', '-f', is_flag=True, help='Skip confirmation')
+def delete(name, force):
+    """Delete an item from HomeServer.
+
+    NAME: Name of the item to delete
+    """
+    from ..core.homeserver import is_server_running, HomeServerClient, HomeServerConfig
+
+    config = HomeServerConfig()
+    if not is_server_running(config.port):
+        click.secho("HomeServer is not running. Use 'includecpp server start' first.", fg='red')
+        return
+
+    try:
+        client = HomeServerClient()
+
+        # Check item exists
+        item = client.get_item(name)
+        if not item:
+            click.secho(f"Item '{name}' not found", fg='red')
+            return
+
+        if not force:
+            if not click.confirm(f"Delete '{name}'?"):
+                return
+
+        result = client.delete_item(name)
+
+        if result.get('success'):
+            click.secho(f"Deleted: {name}", fg='green')
+        else:
+            click.secho(f"Delete failed: {result.get('error', 'Unknown error')}", fg='red')
+
+    except ConnectionError as e:
+        click.secho(str(e), fg='red')
+
+
+@server.command()
+@click.argument('target')
+@click.argument('args', nargs=-1)
+@click.option('--project', '-p', type=click.Path(exists=True),
+              help='IncludeCPP project path for module imports')
+@click.option('--cwd', '-c', type=click.Path(exists=True),
+              help='Working directory for execution')
+def run(target, args, project, cwd):
+    """Run a stored executable, script, or project file.
+
+    TARGET: Item name, or name.path.to.file for project files
+
+    Examples:
+        includecpp server run MyApp              # Run single executable
+        includecpp server run myproject.main    # Run myproject/main.py
+        includecpp server run proj.src.app      # Run proj/src/app.py
+
+        # With includecpp project for module imports:
+        includecpp server run myscript -p /path/to/project
+    """
+    from ..core.homeserver import (
+        is_server_running, HomeServerClient, HomeServerConfig,
+        get_server_dir, HomeServerDB
+    )
+    import tempfile
+    import subprocess
+
+    config = HomeServerConfig()
+    if not is_server_running(config.port):
+        click.secho("HomeServer is not running. Use 'includecpp server start' first.", fg='red')
+        return
+
+    try:
+        client = HomeServerClient()
+        db = HomeServerDB()
+
+        # Parse target: name or name.path.to.file
+        parts = target.split('.')
+        item_name = parts[0]
+        file_path = '.'.join(parts[1:]) if len(parts) > 1 else None
+
+        # Get item info
+        item = client.get_item(item_name)
+        if not item:
+            click.secho(f"Item '{item_name}' not found", fg='red')
+            return
+
+        storage_path = Path(item['storage_path'])
+
+        if item['item_type'] == 'project':
+            # Project: find the file to run
+            if file_path:
+                # Convert dots to path separators
+                rel_path = file_path.replace('.', os.sep)
+                # Try with common extensions
+                candidates = [
+                    storage_path / rel_path,
+                    storage_path / f"{rel_path}.py",
+                    storage_path / f"{rel_path}.bat",
+                    storage_path / f"{rel_path}.exe",
+                    storage_path / f"{rel_path}.sh",
+                ]
+                run_file = None
+                for c in candidates:
+                    if c.exists():
+                        run_file = c
+                        break
+
+                if not run_file:
+                    click.secho(f"File not found: {file_path}", fg='red')
+                    click.secho(f"Tried: {', '.join(str(c.relative_to(storage_path)) for c in candidates)}", fg='yellow')
+                    return
+            else:
+                # Try to find main entry point
+                for name in ['main.py', 'app.py', '__main__.py', 'run.py', 'main.bat', 'run.bat']:
+                    candidate = storage_path / name
+                    if candidate.exists():
+                        run_file = candidate
+                        break
+                else:
+                    click.secho(f"No entry point found in project. Use: server run {item_name}.<path.to.file>", fg='red')
+                    # List available files
+                    files = [str(f.relative_to(storage_path)) for f in storage_path.rglob('*')
+                             if f.is_file() and f.suffix in ('.py', '.bat', '.exe', '.sh')][:10]
+                    if files:
+                        click.secho(f"Available files: {', '.join(files)}", fg='cyan')
+                    return
+        else:
+            # Single file
+            run_file = storage_path
+
+        if not run_file.exists():
+            click.secho(f"File not found: {run_file}", fg='red')
+            return
+
+        # Determine how to run the file
+        suffix = run_file.suffix.lower()
+        click.secho(f"Running: {run_file.name}", fg='cyan')
+
+        # Set up environment for includecpp modules
+        env = os.environ.copy()
+
+        # Auto-detect project path from metadata if not explicitly provided
+        effective_project = project
+        if not effective_project:
+            saved_project = client.get_project_path(item_name)
+            if saved_project and Path(saved_project).exists():
+                effective_project = saved_project
+                click.secho(f"Using saved project: {saved_project}", fg='cyan')
+
+        if effective_project:
+            project_path = Path(effective_project).resolve()
+            # Add project to PYTHONPATH so imports work
+            pythonpath = env.get('PYTHONPATH', '')
+            env['PYTHONPATH'] = f"{project_path}{os.pathsep}{pythonpath}" if pythonpath else str(project_path)
+            # Set INCLUDECPP_PROJECT for the includecpp package to find modules
+            env['INCLUDECPP_PROJECT'] = str(project_path)
+
+        # Determine working directory
+        if cwd:
+            work_dir = Path(cwd)
+        elif effective_project:
+            work_dir = Path(effective_project)
+        else:
+            work_dir = storage_path.parent if item['item_type'] == 'file' else storage_path
+
+        if suffix == '.py':
+            cmd = [sys.executable, str(run_file)] + list(args)
+        elif suffix == '.exe':
+            cmd = [str(run_file)] + list(args)
+        elif suffix == '.bat':
+            cmd = ['cmd', '/c', str(run_file)] + list(args)
+        elif suffix == '.sh':
+            cmd = ['bash', str(run_file)] + list(args)
+        elif suffix in ('.js', '.mjs'):
+            cmd = ['node', str(run_file)] + list(args)
+        else:
+            # Try to execute directly
+            cmd = [str(run_file)] + list(args)
+
+        # Run the command
+        try:
+            result = subprocess.run(cmd, cwd=work_dir, env=env)
+            if result.returncode != 0:
+                click.secho(f"Process exited with code {result.returncode}", fg='yellow')
+        except FileNotFoundError:
+            click.secho(f"Cannot execute: {run_file.name}", fg='red')
+        except PermissionError:
+            click.secho(f"Permission denied: {run_file.name}", fg='red')
+
+    except ConnectionError as e:
+        click.secho(str(e), fg='red')
+    except Exception as e:
+        click.secho(f"Error: {e}", fg='red')
+
+
+@server.command()
+@click.argument('port_num', type=int)
+def port(port_num):
+    """Change the server port.
+
+    PORT_NUM: New port number (1024-65535)
+    """
+    from ..core.homeserver import HomeServerConfig, is_server_running
+
+    if port_num < 1024 or port_num > 65535:
+        click.secho("Port must be between 1024 and 65535", fg='red')
+        return
+
+    config = HomeServerConfig()
+    old_port = config.port
+
+    if is_server_running(old_port):
+        click.secho("Stop the server first before changing port", fg='yellow')
+        click.secho("Use: includecpp server stop", fg='cyan')
+        return
+
+    config.port = port_num
+    click.secho(f"Port changed from {old_port} to {port_num}", fg='green')
+
+
+@server.command()
+def deinstall():
+    """Remove HomeServer completely."""
+    from ..core.homeserver import (
+        stop_server, remove_windows_autostart, get_server_dir, is_server_running,
+        HomeServerConfig
+    )
+
+    if not click.confirm("This will delete all stored data. Continue?"):
+        return
+
+    config = HomeServerConfig()
+
+    # Stop if running
+    if is_server_running(config.port):
+        stop_server()
+        click.secho("Server stopped", fg='cyan')
+
+    # Remove auto-start
+    if sys.platform == 'win32':
+        remove_windows_autostart()
+        click.secho("Auto-start removed", fg='cyan')
+
+    # Delete all data
+    server_dir = get_server_dir()
+    if server_dir.exists():
+        shutil.rmtree(server_dir)
+        click.secho("Data deleted", fg='cyan')
+
+    click.secho("HomeServer deinstalled successfully", fg='green')
+
+
+# Category management subcommand group
+@server.group()
+def categories():
+    """Manage categories for organizing items."""
+    pass
+
+
+@categories.command('list')
+def categories_list():
+    """List all categories."""
+    from ..core.homeserver import is_server_running, HomeServerClient, HomeServerConfig
+
+    config = HomeServerConfig()
+    if not is_server_running(config.port):
+        click.secho("HomeServer is not running. Use 'includecpp server start' first.", fg='red')
+        return
+
+    try:
+        client = HomeServerClient()
+        cats = client.list_categories()
+
+        if not cats:
+            click.secho("No categories", fg='yellow')
+            return
+
+        click.secho("Categories:", fg='cyan', bold=True)
+        for cat in cats:
+            items = client.get_items_by_category(cat)
+            click.echo(f"  {cat} ({len(items)} items)")
+
+    except ConnectionError as e:
+        click.secho(str(e), fg='red')
+
+
+@categories.command('add')
+@click.argument('name')
+def categories_add(name):
+    """Create a new category."""
+    from ..core.homeserver import is_server_running, HomeServerClient, HomeServerConfig
+
+    config = HomeServerConfig()
+    if not is_server_running(config.port):
+        click.secho("HomeServer is not running. Use 'includecpp server start' first.", fg='red')
+        return
+
+    try:
+        client = HomeServerClient()
+        result = client.add_category(name)
+
+        if result.get('success'):
+            click.secho(f"Category '{name}' created", fg='green')
+        else:
+            click.secho(f"Failed: {result.get('error', 'Unknown error')}", fg='red')
+
+    except ConnectionError as e:
+        click.secho(str(e), fg='red')
+
+
+@categories.command('delete')
+@click.argument('name')
+def categories_delete(name):
+    """Delete a category (items become uncategorized)."""
+    from ..core.homeserver import is_server_running, HomeServerClient, HomeServerConfig
+
+    config = HomeServerConfig()
+    if not is_server_running(config.port):
+        click.secho("HomeServer is not running. Use 'includecpp server start' first.", fg='red')
+        return
+
+    try:
+        client = HomeServerClient()
+        result = client.delete_category(name)
+
+        if result.get('success'):
+            click.secho(f"Category '{name}' deleted", fg='green')
+        else:
+            click.secho(f"Failed: {result.get('error', 'Unknown error')}", fg='red')
+
+    except ConnectionError as e:
+        click.secho(str(e), fg='red')
+
+
+@categories.command('move')
+@click.argument('item_name')
+@click.argument('category')
+def categories_move(item_name, category):
+    """Move an item to a category.
+
+    Use '-' as category to uncategorize.
+    """
+    from ..core.homeserver import is_server_running, HomeServerClient, HomeServerConfig
+
+    config = HomeServerConfig()
+    if not is_server_running(config.port):
+        click.secho("HomeServer is not running. Use 'includecpp server start' first.", fg='red')
+        return
+
+    try:
+        client = HomeServerClient()
+        cat = None if category == '-' else category
+        result = client.move_to_category(item_name, cat)
+
+        if result.get('success'):
+            if cat:
+                click.secho(f"Moved '{item_name}' to category '{cat}'", fg='green')
+            else:
+                click.secho(f"Removed '{item_name}' from category", fg='green')
+        else:
+            click.secho(f"Failed: {result.get('error', 'Unknown error')}", fg='red')
+
+    except ConnectionError as e:
+        click.secho(str(e), fg='red')
+
+
+@categories.command('download')
+@click.argument('category')
+@click.argument('output', type=click.Path(), required=False)
+def categories_download(category, output):
+    """Download all items in a category.
+
+    CATEGORY: Category name to download
+    OUTPUT: Output directory (default: current directory)
+    """
+    from ..core.homeserver import is_server_running, HomeServerClient, HomeServerConfig
+
+    config = HomeServerConfig()
+    if not is_server_running(config.port):
+        click.secho("HomeServer is not running. Use 'includecpp server start' first.", fg='red')
+        return
+
+    output_path = Path(output) if output else Path.cwd()
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    try:
+        client = HomeServerClient()
+        items = client.get_items_by_category(category)
+
+        if not items:
+            click.secho(f"No items in category '{category}'", fg='yellow')
+            return
+
+        click.secho(f"Downloading {len(items)} items from '{category}'...", fg='cyan')
+
+        downloaded = []
+        for item in items:
+            try:
+                path = client.download_file(item['name'], output_path, is_dir=True)
+                downloaded.append(item['name'])
+                click.echo(f"  Downloaded: {item['name']}")
+            except Exception as e:
+                click.secho(f"  Failed: {item['name']} - {e}", fg='red')
+
+        click.secho(f"\nDownloaded {len(downloaded)}/{len(items)} items to {output_path}", fg='green')
+
+    except ConnectionError as e:
+        click.secho(str(e), fg='red')
+
+
 # ============================================================================
 # Conditional Registration of Experimental Commands
 # ============================================================================