allset

.gitignore

@@ -0,0 +1,7 @@
+example_project/
+__pycache__/
+*/__pycache__
+*.pyc
+env/
+.env
+static/script.js.txt

Dockerfile

@@ -0,0 +1,16 @@
+# Read the doc: https://huggingface.co/docs/hub/spaces-sdks-docker
+# you will also find guides on how best to write your Dockerfile
+
+FROM python:3.9
+
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+COPY --chown=user . /app
+CMD ["python", "./run.py"]

codescribe/cli.py

@@ -0,0 +1,77 @@
+import click
+from .config import load_config
+from .llm_handler import LLMHandler
+from .orchestrator import DocstringOrchestrator
+from .readme_generator import ReadmeGenerator
+
+@click.group(context_settings=dict(help_option_names=['-h', '--help']))
+@click.pass_context
+def cli(ctx):
+    """
+    CodeScribe AI: A tool for AI-assisted project documentation.
+    
+    Choose a command below (e.g., 'docstrings', 'readmes') and provide its options.
+    """
+    # This parent command now only handles setup common to all subcommands.
+    ctx.ensure_object(dict)
+    try:
+        config = load_config()
+        if not config.api_keys:
+            raise click.UsageError("No API keys found in the .env file. Please create one.")
+        
+        ctx.obj['LLM_HANDLER'] = LLMHandler(config.api_keys)
+        click.echo(f"Initialized with {len(config.api_keys)} API keys.")
+
+    except Exception as e:
+        raise click.ClickException(f"Initialization failed: {e}")
+
+@cli.command()
+@click.option('--path', required=True, help='The local path or Git URL of the project.')
+@click.option('--desc', required=True, help='A short description of the project.')
+@click.option('--exclude', multiple=True, help='Directory/regex pattern to exclude. Can be used multiple times.')
+@click.pass_context
+def docstrings(ctx, path, desc, exclude):
+    """Generates Python docstrings for all files."""
+    click.echo("\n--- Starting Docstring Generation ---")
+    llm_handler = ctx.obj['LLM_HANDLER']
+    
+    orchestrator = DocstringOrchestrator(
+        path_or_url=path,
+        description=desc,
+        exclude=list(exclude),
+        llm_handler=llm_handler
+    )
+    try:
+        orchestrator.run()
+        click.secho("Successfully generated all docstrings.", fg="green")
+    except Exception as e:
+        click.secho(f"An error occurred during docstring generation: {e}", fg="red")
+
+
+@cli.command()
+@click.option('--path', required=True, help='The local path or Git URL of the project.')
+@click.option('--desc', required=True, help='A short description of the project.')
+@click.option('--exclude', multiple=True, help='Directory/regex pattern to exclude. Can be used multiple times.')
+@click.pass_context
+def readmes(ctx, path, desc, exclude):
+    """Generates README.md files for each directory."""
+    click.echo("\n--- Starting README Generation ---")
+    llm_handler = ctx.obj['LLM_HANDLER']
+    
+    generator = ReadmeGenerator(
+        path_or_url=path,
+        description=desc,
+        exclude=list(exclude),
+        llm_handler=llm_handler
+    )
+    try:
+        generator.run()
+        click.secho("Successfully generated all README files.", fg="green")
+    except Exception as e:
+        click.secho(f"An error occurred during README generation: {e}", fg="red")
+
+def main():
+    cli(obj={})
+
+if __name__ == '__main__':
+    main()

codescribe/config.py

@@ -0,0 +1,46 @@
+import os
+from dataclasses import dataclass, field
+from dotenv import load_dotenv
+from typing import List
+
+@dataclass
+class APIKey:
+    provider: str
+    key: str
+    model: str
+
+    def __repr__(self):
+        return f"APIKey(provider='{self.provider}', model='{self.model}')"
+
+@dataclass
+class Config:
+    api_keys: List[APIKey] = field(default_factory=list)
+
+def load_config() -> Config:
+    """Loads API keys from .env file into a Config object."""
+    load_dotenv()
+    
+    config = Config()
+    
+    # Load Groq keys (GROQ_API_KEY_1, GRO-API_KEY_2, etc.)
+    i = 1
+    while True:
+        key = os.getenv(f"GROQ_API_KEY_{i}")
+        if not key:
+            break
+        config.api_keys.append(APIKey(provider="groq", key=key, model="llama3-70b-8192"))
+        i += 1
+
+    # Load Gemini keys (GEMINI_API_KEY_1, etc.)
+    i = 1
+    while True:
+        key = os.getenv(f"GEMINI_API_KEY_{i}")
+        if not key:
+            break
+        config.api_keys.append(APIKey(provider="gemini", key=key, model="gemini-1.5-flash"))
+        i += 1
+        
+    if not config.api_keys:
+        print("Warning: No API keys found in .env file. Please create a .env file with GROQ_API_KEY_1 or GEMINI_API_KEY_1.")
+        
+    return config

codescribe/llm_handler.py

@@ -0,0 +1,123 @@
+import time
+import json
+from typing import Dict, List, Callable
+import google.generativeai as genai
+from groq import Groq, RateLimitError
+
+
+
+from .config import APIKey
+
+def no_op_callback(message: str):
+    print(message)
+
+class LLMHandler:
+    def __init__(self, api_keys: List[APIKey], progress_callback: Callable[[str], None] = no_op_callback):
+        self.clients = []
+        self.progress_callback = progress_callback # NEW
+        for key in api_keys:
+            if key.provider == "groq":
+                self.clients.append({
+                    "provider": "groq",
+                    "client": Groq(api_key=key.key),
+                    "model": key.model,
+                    "id": f"groq_{key.key[-4:]}"
+                })
+            elif key.provider == "gemini":
+                genai.configure(api_key=key.key)
+                self.clients.append({
+                    "provider": "gemini",
+                    "client": genai.GenerativeModel(key.model),
+                    "model": key.model,
+                    "id": f"gemini_{key.key[-4:]}"
+                })
+        
+        self.cooldowns: Dict[str, float] = {}
+        self.cooldown_period = 30  # 30 seconds
+
+    def generate_documentation(self, prompt: str) -> Dict:
+        """
+        Tries to generate documentation using available clients, handling rate limits and failovers.
+        """
+        if not self.clients:
+            raise ValueError("No LLM clients configured.")
+
+        for client_info in self.clients:
+            client_id = client_info["id"]
+
+            # Check if the client is on cooldown
+            if client_id in self.cooldowns:
+                if time.time() - self.cooldowns[client_id] < self.cooldown_period:
+                    self.progress_callback(f"Skipping {client_id} (on cooldown).")
+                    continue
+                else:
+                    # Cooldown has expired
+                    del self.cooldowns[client_id]
+            
+            try:
+                self.progress_callback(f"Attempting to generate docs with {client_id} ({client_info['model']})...")
+                if client_info["provider"] == "groq":
+                    response = client_info["client"].chat.completions.create(
+                        messages=[{"role": "user", "content": prompt}],
+                        model=client_info["model"],
+                        temperature=0.1,
+                        response_format={"type": "json_object"},
+                    )
+                    content = response.choices[0].message.content
+                
+                elif client_info["provider"] == "gemini":
+                    response = client_info["client"].generate_content(prompt)
+                    # Gemini might wrap JSON in ```json ... ```
+                    content = response.text.strip().replace("```json", "").replace("```", "").strip()
+
+                return json.loads(content)
+
+            except RateLimitError:
+                self.progress_callback(f"Rate limit hit for {client_id}. Placing it on a {self.cooldown_period}s cooldown.")
+                self.cooldowns[client_id] = time.time()
+                continue
+            except Exception as e:
+                self.progress_callback(f"An error occurred with {client_id}: {e}. Trying next client.")
+                continue
+
+        raise RuntimeError("Failed to generate documentation from all available LLM providers.")
+    
+    
+    def generate_text_response(self, prompt: str) -> str:
+        """
+        Generates a plain text response from LLMs, handling failovers.
+        """
+        if not self.clients:
+            raise ValueError("No LLM clients configured.")
+
+        for client_info in self.clients:
+            client_id = client_info["id"]
+            if client_id in self.cooldowns and time.time() - self.cooldowns[client_id] < self.cooldown_period:
+                self.progress_callback(f"Skipping {client_id} (on cooldown).")
+                continue
+            elif client_id in self.cooldowns:
+                 del self.cooldowns[client_id]
+
+            try:
+                self.progress_callback(f"Attempting to generate text with {client_id} ({client_info['model']})...")
+                if client_info["provider"] == "groq":
+                    response = client_info["client"].chat.completions.create(
+                        messages=[{"role": "user", "content": prompt}],
+                        model=client_info["model"],
+                        temperature=0.2,
+                    )
+                    return response.choices[0].message.content
+                
+                elif client_info["provider"] == "gemini":
+                    response = client_info["client"].generate_content(prompt)
+                    return response.text.strip()
+
+            except RateLimitError:
+                self.progress_callback(f"Rate limit hit for {client_id}. Placing it on a {self.cooldown_period}s cooldown.")
+                self.cooldowns[client_id] = time.time()
+                continue
+            except Exception as e:
+                self.progress_callback(f"An error occurred with {client_id}: {e}. Trying next client.")
+                continue
+
+        raise RuntimeError("Failed to generate text response from all available LLM providers.")

codescribe/orchestrator.py

@@ -0,0 +1,173 @@
+import shutil
+from pathlib import Path
+from typing import List, Callable, Dict
+import networkx as nx
+import json
+from collections import defaultdict
+
+from . import scanner, parser, updater
+from .llm_handler import LLMHandler
+
+COMBINED_DOCSTRING_PROMPT_TEMPLATE = """
+SYSTEM: You are an expert programmer writing high-quality, comprehensive Python docstrings in reStructuredText (reST) format. Your output MUST be a single JSON object.
+
+USER:
+Project Description:
+\"\"\"
+{project_description}
+\"\"\"
+
+---
+CONTEXT FROM DEPENDENCIES:
+This file depends on other modules. Here is their documentation for context:
+
+{dependency_context}
+---
+
+DOCUMENT THE FOLLOWING SOURCE FILE:
+
+File Path: `{file_path}`
+
+```python
+{file_content}
+```
+INSTRUCTIONS:
+Provide a single JSON object as your response.
+1.  The JSON object MUST have a special key `\"__module__\"`. The value for this key should be a concise, single-paragraph docstring that summarizes the purpose of the entire file.
+2.  The other keys in the JSON object should be the function or class names (e.g., "my_function", "MyClass", "MyClass.my_method").
+3.  The values for these other keys should be their complete docstrings.
+4.  Do NOT include the original code in your response. Only generate the JSON containing the docstrings.
+"""
+
+# --- UNCHANGED ---
+PACKAGE_INIT_PROMPT_TEMPLATE = """
+SYSTEM: You are an expert programmer writing a high-level, one-paragraph summary for a Python package. This summary will be the main docstring for the package's `__init__.py` file.
+
+USER:
+Project Description:
+\"\"\"
+{project_description}
+\"\"\"
+
+You are writing the docstring for the `__init__.py` of the `{package_name}` package.
+
+This package contains the following modules. Their summaries are provided below:
+{module_summaries}
+
+INSTRUCTIONS:
+Write a concise, single-paragraph docstring that summarizes the overall purpose and responsibility of the `{package_name}` package, based on the modules it contains. This docstring will be placed in the `__init__.py` file.
+"""
+
+def no_op_callback(event: str, data: dict):
+    print(f"{event}: {json.dumps(data, indent=2)}")
+
+class DocstringOrchestrator:
+    # --- UNCHANGED ---
+    def __init__(self, path_or_url: str, description: str, exclude: List[str], llm_handler: LLMHandler, progress_callback: Callable[[str, dict], None] = no_op_callback, repo_full_name: str = None):
+        self.path_or_url = path_or_url
+        self.description = description
+        self.exclude = exclude
+        self.llm_handler = llm_handler
+        self.progress_callback = progress_callback
+        self.project_path = None
+        self.is_temp_dir = path_or_url.startswith("http")
+        self.repo_full_name = repo_full_name
+
+        def llm_log_wrapper(message: str):
+            self.progress_callback("log", {"message": message})
+        
+        self.llm_handler.progress_callback = llm_log_wrapper
+
+    # --- MODIFIED: The run() method is refactored ---
+    def run(self):
+        def log_to_ui(message: str):
+            self.progress_callback("log", {"message": message})
+
+        try:
+            self.project_path = scanner.get_project_path(self.path_or_url, log_callback=log_to_ui)
+            
+            self.progress_callback("phase", {"id": "scan", "name": "Scanning Project", "status": "in-progress"})
+            files = scanner.scan_project(self.project_path, self.exclude)
+            log_to_ui(f"Found {len(files)} Python files to document.")
+            self.progress_callback("phase", {"id": "scan", "status": "success"})
+
+            graph = parser.build_dependency_graph(files, self.project_path, log_callback=log_to_ui)
+            
+            self.progress_callback("phase", {"id": "docstrings", "name": "Generating Docstrings", "status": "in-progress"})
+            doc_order = list(nx.topological_sort(graph)) if nx.is_directed_acyclic_graph(graph) else list(graph.nodes)
+            
+            # --- COMBINED PASS 1 & 2: Generate all docstrings in a single call per file ---
+            documented_context = {}
+            module_docstrings = {}
+            for file_path in doc_order:
+                rel_path = file_path.relative_to(self.project_path).as_posix()
+                # Use a single subtask for the entire file documentation process
+                self.progress_callback("subtask", {"parentId": "docstrings", "listId": "docstring-file-list", "id": f"doc-{rel_path}", "name": f"Documenting {rel_path}", "status": "in-progress"})
+                
+                deps = graph.predecessors(file_path)
+                dep_context_str = "\n".join([f"File: `{dep.relative_to(self.project_path)}`\n{json.dumps(documented_context.get(dep, {}), indent=2)}\n" for dep in deps]) or "No internal dependencies have been documented yet."
+                    
+                with open(file_path, "r", encoding="utf-8") as f:
+                    file_content = f.read()
+                
+                # Use the new combined prompt
+                prompt = COMBINED_DOCSTRING_PROMPT_TEMPLATE.format(project_description=self.description, dependency_context=dep_context_str, file_path=rel_path, file_content=file_content)
+                
+                try:
+                    # Single LLM call to get all docstrings for the file
+                    combined_docs = self.llm_handler.generate_documentation(prompt)
+
+                    # Separate the module docstring from the function/class docstrings
+                    module_summary = combined_docs.pop("__module__", None)
+                    function_class_docs = combined_docs # The remainder of the dict
+
+                    # Update the file with function/class docstrings
+                    updater.update_file_with_docstrings(file_path, function_class_docs, log_callback=log_to_ui)
+                    
+                    # Update the file with the module-level docstring if it was generated
+                    if module_summary:
+                        updater.update_module_docstring(file_path, module_summary, log_callback=log_to_ui)
+                        module_docstrings[file_path] = module_summary
+
+                    self.progress_callback("subtask", {"parentId": "docstrings", "id": f"doc-{rel_path}", "status": "success"})
+                    documented_context[file_path] = function_class_docs # Store for dependency context
+                except Exception as e:
+                    log_to_ui(f"Error processing docstrings for {rel_path}: {e}")
+                    self.progress_callback("subtask", {"parentId": "docstrings", "id": f"doc-{rel_path}", "status": "error"})
+            
+            # --- PASS 3: Generate __init__.py Docstrings for Packages (Unchanged) ---
+            packages = defaultdict(list)
+            for file_path, docstring in module_docstrings.items():
+                if file_path.name != "__init__.py":
+                    packages[file_path.parent].append(f"- `{file_path.name}`: {docstring}")
+            
+            for package_path, summaries in packages.items():
+                rel_path = package_path.relative_to(self.project_path).as_posix()
+                init_file = package_path / "__init__.py"
+                self.progress_callback("subtask", {"parentId": "docstrings", "listId": "docstring-package-list", "id": f"pkg-{rel_path}", "name": f"Package summary for {rel_path}", "status": "in-progress"})
+                
+                try:
+                    is_root_package = (package_path == self.project_path)
+                    package_name = self.repo_full_name if is_root_package and self.repo_full_name else package_path.name
+                    
+                    prompt = PACKAGE_INIT_PROMPT_TEMPLATE.format(
+                        project_description=self.description,
+                        package_name=package_name,
+                        module_summaries="\n".join(summaries)
+                    )
+                    package_summary = self.llm_handler.generate_text_response(prompt).strip().strip('"""').strip("'''").strip()
+                    
+                    if not init_file.exists():
+                        init_file.touch()
+                    
+                    updater.update_module_docstring(init_file, package_summary, log_callback=log_to_ui)
+                    self.progress_callback("subtask", {"parentId": "docstrings", "id": f"pkg-{rel_path}", "status": "success"})
+                except Exception as e:
+                    log_to_ui(f"Error generating package docstring for {rel_path}: {e}")
+                    self.progress_callback("subtask", {"parentId": "docstrings", "id": f"pkg-{rel_path}", "status": "error"})
+
+            self.progress_callback("phase", {"id": "docstrings", "status": "success"})
+
+        finally:
+            if self.is_temp_dir and self.project_path and self.project_path.exists():
+                shutil.rmtree(self.project_path, ignore_errors=True)

codescribe/parser.py

@@ -0,0 +1,52 @@
+
+import ast
+from pathlib import Path
+from typing import List, Set, Callable # Add Callable
+import networkx as nx
+
+def resolve_import_path(current_file: Path, module_name: str, level: int, project_root: Path) -> Path | None:
+    # ... (function content remains unchanged) ...
+    if level > 0:  # Relative import
+        base_path = current_file.parent
+        for _ in range(level - 1):
+            base_path = base_path.parent
+        
+        module_path = base_path / Path(*module_name.split('.'))
+    else:  # Absolute import
+        module_path = project_root / Path(*module_name.split('.'))
+
+    # Try to find the file (.py) or package (__init__.py)
+    if module_path.with_suffix(".py").exists():
+        return module_path.with_suffix(".py")
+    if (module_path / "__init__.py").exists():
+        return module_path / "__init__.py"
+    
+    return None
+
+def build_dependency_graph(file_paths: List[Path], project_root: Path, log_callback: Callable[[str], None] = print) -> nx.DiGraph:
+    """
+    Builds a dependency graph from a list of Python files.
+    Uses a callback for logging warnings.
+    """
+    graph = nx.DiGraph()
+    path_map = {p.stem: p for p in file_paths} # Simplified mapping
+    
+    for file_path in file_paths:
+        graph.add_node(file_path)
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                content = f.read()
+            tree = ast.parse(content)
+            
+            for node in ast.walk(tree):
+                if isinstance(node, ast.ImportFrom):
+                    if node.module:
+                        dep_path = resolve_import_path(file_path, node.module, node.level, project_root)
+                        if dep_path and dep_path in file_paths:
+                            graph.add_edge(file_path, dep_path)
+
+        except Exception as e:
+            # Use the callback instead of print
+            log_callback(f"Warning: Could not parse {file_path.name} for dependencies. Skipping. Error: {e}")
+            
+    return graph

codescribe/readme_generator.py

@@ -0,0 +1,270 @@
+# codescribe/readme_generator.py
+
+import os
+import shutil
+import ast
+from pathlib import Path
+from typing import List, Callable
+
+from . import scanner
+from .llm_handler import LLMHandler
+
+# Prompt templates remain unchanged.
+SUBDIR_PROMPT_TEMPLATE = """
+SYSTEM: You are an expert technical writer creating a README.md file for a specific directory within a larger project. Your tone should be informative and concise.
+
+USER:
+You are generating a `README.md` for the directory: `{current_dir_relative}`
+
+The overall project description is:
+"{project_description}"
+
+---
+This directory contains the following source code files. Use them to describe the specific purpose of this directory:
+{file_summaries}
+---
+
+This directory also contains the following subdirectories. Use their `README.md` content (provided below) to summarize their roles:
+{subdirectory_readmes}
+---
+
+TASK:
+Write a `README.md` for the `{current_dir_relative}` directory.
+- Start with a heading (e.g., `# Directory: {dir_name}`).
+- Briefly explain the purpose of this directory based on the files it contains.
+- If there are subdirectories, provide a section summarizing what each one does, using the context from their READMEs.
+- Use clear Markdown formatting. Do not describe the entire project; focus ONLY on the contents and role of THIS directory.
+"""
+
+ROOT_PROMPT_TEMPLATE = """
+SYSTEM: You are an expert technical writer creating the main `README.md` for an entire software project. Your tone should be welcoming and comprehensive.
+
+USER:
+You are generating the main `README.md` for a project.
+
+The user-provided project description is:
+"{project_description}"
+
+---
+The project's root directory contains the following source code files:
+{file_summaries}
+---
+
+The project has the following main subdirectories. Use their `README.md` content (provided below) to describe the overall structure of the project:
+{subdirectory_readmes}
+---
+
+TASK:
+Write a comprehensive `README.md` for the entire project. Structure it with the following sections:
+- A main title (`# Project: {project_name}`).
+- **Overview**: A slightly more detailed version of the user's description, enhanced with context from the files and subdirectories.
+- **Project Structure**: A description of the key directories and their roles, using the information from the subdirectory READMEs.
+- **Key Features**: Infer and list the key features of the project based on all the provided context.
+"""
+
+UPDATE_SUBDIR_PROMPT_TEMPLATE = """
+SYSTEM: You are an expert technical writer updating a README.md file for a specific directory. Your tone should be informative and concise. A user has provided a note with instructions.
+
+USER:
+You are updating the `README.md` for the directory: `{current_dir_relative}`
+
+The user-provided note with instructions for this update is:
+"{user_note}"
+
+The overall project description is:
+"{project_description}"
+---
+This directory contains the following source code files. Use them to describe the specific purpose of this directory:
+{file_summaries}
+---
+This directory also contains the following subdirectories. Use their `README.md` content (provided below) to summarize their roles:
+{subdirectory_readmes}
+---
+Here is the OLD `README.md` content. You must update it based on the new context and the user's note.
+---
+{existing_readme}
+---
+TASK:
+Rewrite the `README.md` for the `{current_dir_relative}` directory, incorporating the user's note and any new information from the files and subdirectories.
+- Start with a heading (e.g., `# Directory: {dir_name}`).
+- Use the existing content as a base, but modify it as needed.
+- Use clear Markdown formatting. Do not describe the entire project; focus ONLY on the contents and role of THIS directory.
+"""
+
+UPDATE_ROOT_PROMPT_TEMPLATE = """
+SYSTEM: You are an expert technical writer updating the main `README.md` for an entire software project. Your tone should be welcoming and comprehensive. A user has provided a note with instructions.
+
+USER:
+You are updating the main `README.md` for a project.
+
+The user-provided note with instructions for this update is:
+"{user_note}"
+
+The user-provided project description is:
+"{project_description}"
+---
+The project's root directory contains the following source code files:
+{file_summaries}
+---
+The project has the following main subdirectories. Use their `README.md` content (provided below) to describe the overall structure of the project:
+{subdirectory_readmes}
+---
+Here is the OLD `README.md` content. You must update it based on the new context and the user's note.
+---
+{existing_readme}
+---
+TASK:
+Rewrite a comprehensive `README.md` for the entire project. Structure it with the following sections, using the old README as a base but incorporating changes based on the user's note and new context.
+- A main title (`# Project: {project_name}`).
+- **Overview**: An updated version of the user's description, enhanced with context.
+- **Project Structure**: A description of the key directories and their roles.
+- **Key Features**: Infer and list key features based on all the provided context.
+"""
+
+def no_op_callback(event: str, data: dict):
+    pass
+
+class ReadmeGenerator:
+    def __init__(self, path_or_url: str, description: str, exclude: List[str], llm_handler: LLMHandler, user_note: str = "", repo_full_name="", progress_callback: Callable[[str, dict], None] = no_op_callback):
+        self.path_or_url = path_or_url
+        self.description = description
+        self.exclude = exclude + ["README.md"]
+        self.llm_handler = llm_handler
+        self.user_note = user_note
+        self.progress_callback = progress_callback
+        self.project_path = None
+        self.is_temp_dir = path_or_url.startswith("http")
+        self.repo_full_name  = repo_full_name
+        
+        def llm_log_wrapper(message: str):
+            self.progress_callback("log", {"message": message})
+        
+        self.llm_handler.progress_callback = llm_log_wrapper
+
+    def run(self):
+        """Public method to start README generation."""
+        try:
+            self.project_path = scanner.get_project_path(self.path_or_url)
+            self.progress_callback("phase", {"id": "readmes", "name": "Generating READMEs", "status": "in-progress"})
+            self.run_with_structured_logging()
+            self.progress_callback("phase", {"id": "readmes", "status": "success"})
+        except Exception as e:
+            self.progress_callback("log", {"message": f"An unexpected error occurred in README generation: {e}"})
+            self.progress_callback("phase", {"id": "readmes", "status": "error"})
+            raise
+        finally:
+            if self.is_temp_dir and self.project_path and self.project_path.exists():
+                shutil.rmtree(self.project_path, ignore_errors=True)
+
+    def _summarize_py_file(self, file_path: Path) -> str:
+        """
+        Extracts the module-level docstring, or a list of function/class names
+        as a fallback, to summarize a Python file.
+        """
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                content = f.read()
+            tree = ast.parse(content)
+            
+            # 1. Prioritize the module-level docstring
+            docstring = ast.get_docstring(tree)
+            if docstring:
+                return f"`{file_path.name}`: {docstring.strip().splitlines()[0]}"
+
+            # 2. Fallback: Find function and class names
+            definitions = []
+            for node in tree.body:
+                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                    definitions.append(node.name)
+            
+            if definitions:
+                summary = f"Contains definitions for: `{', '.join(definitions)}`."
+                return f"`{file_path.name}`: {summary}"
+
+        except Exception as e:
+            self.progress_callback("log", {"message": f"Could not parse {file_path.name} for summary: {e}"})
+        
+        # 3. Final fallback
+        return f"`{file_path.name}`: A Python source file."
+
+    def run_with_structured_logging(self):
+        """
+        Generates README files for each directory from the bottom up,
+        emitting structured events for the UI.
+        """
+        if not self.project_path:
+             self.project_path = scanner.get_project_path(self.path_or_url)
+             
+        for dir_path, subdir_names, file_names in os.walk(self.project_path, topdown=False):
+            current_dir = Path(dir_path)
+            
+            if scanner.is_excluded(current_dir, self.exclude, self.project_path):
+                continue
+
+            rel_path = current_dir.relative_to(self.project_path).as_posix()
+            dir_id = rel_path if rel_path != "." else "root"
+            dir_name_display = rel_path if rel_path != "." else "Project Root"
+
+            self.progress_callback("subtask", {"parentId": "readmes", "listId": "readme-dir-list", "id": dir_id, "name": f"Directory: {dir_name_display}", "status": "in-progress"})
+            
+            try:
+                file_summaries = self._gather_file_summaries(current_dir, file_names)
+                subdirectory_readmes = self._gather_subdirectory_readmes(current_dir, subdir_names)
+
+                existing_readme_content = None
+                existing_readme_path = current_dir / "README.md"
+                if existing_readme_path.exists():
+                    with open(existing_readme_path, "r", encoding="utf-8") as f:
+                        existing_readme_content = f.read()
+
+                prompt = self._build_prompt(current_dir, file_summaries, subdirectory_readmes, existing_readme_content)
+                generated_content = self.llm_handler.generate_text_response(prompt)
+                
+                with open(current_dir / "README.md", "w", encoding="utf-8") as f:
+                    f.write(generated_content)
+                
+                self.progress_callback("subtask", {"parentId": "readmes", "id": dir_id, "status": "success"})
+
+            except Exception as e:
+                self.progress_callback("log", {"message": f"Failed to generate README for {dir_name_display}: {e}"})
+                self.progress_callback("subtask", {"parentId": "readmes", "id": dir_id, "status": "error"})
+
+    # ... The rest of the file (_gather_file_summaries, _gather_subdirectory_readmes, _build_prompt) remains unchanged ...
+    def _gather_file_summaries(self, current_dir: Path, file_names: List[str]) -> str:
+        file_summaries_list = []
+        for fname in file_names:
+            if fname.endswith(".py"):
+               file_path = current_dir / fname
+               if not scanner.is_excluded(file_path, self.exclude, self.project_path):
+                   file_summaries_list.append(self._summarize_py_file(file_path))
+        return "\n".join(file_summaries_list) or "No Python source files in this directory."
+
+    def _gather_subdirectory_readmes(self, current_dir: Path, subdir_names: List[str]) -> str:
+        subdir_readmes_list = []
+        for sub_name in subdir_names:
+            readme_path = current_dir / sub_name / "README.md"
+            if readme_path.exists():
+                with open(readme_path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                subdir_readmes_list.append(f"--- Subdirectory: `{sub_name}` ---\n{content}\n")
+        return "\n".join(subdir_readmes_list) or "No subdirectories with READMEs."
+
+    def _build_prompt(self, current_dir: Path, file_summaries: str, subdirectory_readmes: str, existing_readme: str | None) -> str:
+        is_root = current_dir == self.project_path
+        common_args = {
+            "project_description": self.description,
+            "file_summaries": file_summaries,
+            "subdirectory_readmes": subdirectory_readmes,
+            "user_note": self.user_note or "No specific instructions provided.",
+        }
+
+        if is_root:
+            template = UPDATE_ROOT_PROMPT_TEMPLATE if existing_readme else ROOT_PROMPT_TEMPLATE
+            args = {**common_args, "project_name": self.repo_full_name if self.repo_full_name else self.project_path.name}
+            if existing_readme: args["existing_readme"] = existing_readme
+        else: # is subdirectory
+            template = UPDATE_SUBDIR_PROMPT_TEMPLATE if existing_readme else SUBDIR_PROMPT_TEMPLATE
+            args = {**common_args, "current_dir_relative": current_dir.relative_to(self.project_path).as_posix(), "dir_name": current_dir.name}
+            if existing_readme: args["existing_readme"] = existing_readme
+        
+        return template.format(**args)

codescribe/scanner.py

@@ -0,0 +1,57 @@
+
+import os
+import re
+from pathlib import Path
+from typing import List, Callable # Add Callable
+import git
+import tempfile
+import shutil
+
+# ... is_excluded function is unchanged ...
+def is_excluded(path: Path, exclude_patterns: List[str], project_root: Path) -> bool:
+    relative_path_str = path.relative_to(project_root).as_posix()
+    if any(part.startswith('.') for part in path.relative_to(project_root).parts):
+        return True
+    for pattern in exclude_patterns:
+        try:
+            if re.search(pattern, relative_path_str):
+                return True
+        except re.error:
+            if pattern in relative_path_str:
+                return True
+    return False
+
+# ... scan_project function is unchanged ...
+def scan_project(project_path: Path, exclude_patterns: List[str]) -> List[Path]:
+    py_files = []
+    for root, dirs, files in os.walk(project_path, topdown=True):
+        root_path = Path(root)
+        original_dirs = dirs[:]
+        dirs[:] = [d for d in original_dirs if not is_excluded(root_path / d, exclude_patterns, project_path)]
+        for file in files:
+            if file.endswith('.py'):
+                file_path = root_path / file
+                if not is_excluded(file_path, exclude_patterns, project_path):
+                    py_files.append(file_path)
+    return py_files
+
+def get_project_path(path_or_url: str, log_callback: Callable[[str], None] = print) -> Path:
+    """
+    Clones a repo if a URL is given, otherwise returns the Path object.
+    Uses a callback for logging.
+    """
+    if path_or_url.startswith("http") or path_or_url.startswith("git@"):
+        temp_dir = tempfile.mkdtemp()
+        # Use the callback instead of print
+        log_callback(f"Cloning repository {path_or_url} into temporary directory...")
+        try:
+            git.Repo.clone_from(path_or_url, temp_dir)
+            return Path(temp_dir)
+        except Exception as e:
+            shutil.rmtree(temp_dir)
+            raise RuntimeError(f"Failed to clone repository: {e}")
+    else:
+        path = Path(path_or_url)
+        if not path.is_dir():
+            raise FileNotFoundError(f"The specified path does not exist or is not a directory: {path}")
+        return path

codescribe/updater.py

@@ -0,0 +1,88 @@
+# codescribe/updater.py
+
+import ast
+from pathlib import Path
+from typing import Dict, Callable
+
+# Helper no-op function for default callback
+def _no_op_log(message: str):
+    pass
+
+class DocstringInserter(ast.NodeTransformer):
+    def __init__(self, docstrings: Dict[str, str]):
+        self.docstrings = docstrings
+        self.current_class = None
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> ast.ClassDef:
+        self.current_class = node.name
+        if node.name in self.docstrings:
+            self._insert_docstring(node, self.docstrings[node.name])
+        self.generic_visit(node)
+        self.current_class = None
+        return node
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.FunctionDef:
+        key = f"{self.current_class}.{node.name}" if self.current_class else node.name
+        if key in self.docstrings:
+            self._insert_docstring(node, self.docstrings[key])
+        return node
+
+    def _insert_docstring(self, node, docstring_text):
+        docstring_node = ast.Expr(value=ast.Constant(value=docstring_text))
+        if ast.get_docstring(node):
+            node.body[0] = docstring_node
+        else:
+            node.body.insert(0, docstring_node)
+
+def update_file_with_docstrings(file_path: Path, docstrings: Dict[str, str], log_callback: Callable[[str], None] = print):
+    """
+    Parses a Python file, inserts docstrings for functions/classes, and overwrites the file.
+    """
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            source_code = f.read()
+        
+        tree = ast.parse(source_code)
+        transformer = DocstringInserter(docstrings)
+        new_tree = transformer.visit(tree)
+        ast.fix_missing_locations(new_tree)
+        
+        new_source_code = ast.unparse(new_tree)
+        
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write(new_source_code)
+        log_callback(f"Successfully updated {file_path.name} with new docstrings.")
+
+    except Exception as e:
+        log_callback(f"Error updating file {file_path.name}: {e}")
+
+def update_module_docstring(file_path: Path, docstring: str, log_callback: Callable[[str], None] = print):
+    """
+    Parses a Python file, adds or replaces the module-level docstring, and overwrites the file.
+    """
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            source_code = f.read()
+        
+        tree = ast.parse(source_code)
+        
+        # Create the new docstring node
+        new_docstring_node = ast.Expr(value=ast.Constant(value=docstring))
+        
+        # Check if a module docstring already exists
+        if ast.get_docstring(tree):
+            # Replace the existing docstring node
+            tree.body[0] = new_docstring_node
+        else:
+            # Insert the new docstring node at the beginning
+            tree.body.insert(0, new_docstring_node)
+            
+        ast.fix_missing_locations(tree)
+        new_source_code = ast.unparse(tree)
+        
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write(new_source_code)
+        log_callback(f"Successfully added/updated module docstring for {file_path.name}.")
+
+    except Exception as e:
+        log_callback(f"Error updating module docstring for {file_path.name}: {e}")

requirements.txt

@@ -0,0 +1,16 @@
+# Existing
+click
+python-dotenv
+google-generativeai
+groq
+networkx
+GitPython
+
+# New for Web Server
+fastapi
+uvicorn[standard]
+python-multipart
+aiohttp
+sse-starlette
+PyGithub
+requests

run.py

@@ -0,0 +1,5 @@
+# run.py
+import uvicorn
+
+if __name__ == "__main__":
+    uvicorn.run("server.main:app", host="0.0.0.0", port=8000, reload=True)

server/main.py

@@ -0,0 +1,275 @@
+
+import os
+import tempfile
+import zipfile
+import shutil
+from pathlib import Path
+import requests
+
+from fastapi import FastAPI, UploadFile, File, Form, Request, HTTPException
+from fastapi.responses import FileResponse, RedirectResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.middleware.cors import CORSMiddleware
+
+from typing import List
+from git import Repo
+
+from github import Github, GithubException # Github is already imported
+
+from .tasks import process_project
+
+# Load environment variables
+from dotenv import load_dotenv
+load_dotenv()
+
+GITHUB_CLIENT_ID = os.getenv("GITHUB_CLIENT_ID")
+GITHUB_CLIENT_SECRET = os.getenv("GITHUB_CLIENT_SECRET")
+
+app = FastAPI()
+
+origins = [
+    "http://localhost",
+    "http://localhost:8000",
+    "http://127.0.0.1",
+    "http://12_7.0.0.1:8000",
+]
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.mount("/static", StaticFiles(directory="static"), name="static")
+
+@app.get("/")
+async def read_root():
+    return FileResponse('static/index.html')
+
+@app.get("/login/github")
+async def login_github():
+    return RedirectResponse(
+        f"https://github.com/login/oauth/authorize?client_id={GITHUB_CLIENT_ID}&scope=repo",
+        status_code=302
+    )
+
+@app.get("/auth/github/callback")
+async def auth_github_callback(code: str, request: Request):
+    params = {
+        "client_id": GITHUB_CLIENT_ID,
+        "client_secret": GITHUB_CLIENT_SECRET,
+        "code": code,
+    }
+    headers = {"Accept": "application/json"}
+    base_url = str(request.base_url)
+    try:
+        response = requests.post("https://github.com/login/oauth/access_token", params=params, headers=headers)
+        response.raise_for_status()
+        response_json = response.json()
+        if "error" in response_json:
+            error_description = response_json.get("error_description", "Unknown error.")
+            return RedirectResponse(f"{base_url}?error={error_description}")
+        token = response_json.get("access_token")
+        if not token:
+            return RedirectResponse(f"{base_url}?error=Authentication failed, no token received.")
+        return RedirectResponse(f"{base_url}?token={token}")
+    except requests.exceptions.RequestException as e:
+        return RedirectResponse(f"{base_url}?error=Failed to connect to GitHub: {e}")
+
+@app.get("/api/github/repos")
+async def get_github_repos(request: Request):
+    auth_header = request.headers.get("Authorization")
+    if not auth_header or not auth_header.startswith("Bearer "):
+        raise HTTPException(status_code=401, detail="Unauthorized")
+    token = auth_header.split(" ")[1]
+    try:
+        g = Github(token)
+        user = g.get_user()
+        repos = [{"full_name": repo.full_name, "default_branch": repo.default_branch} for repo in user.get_repos(type='owner')]
+        return repos
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"Failed to fetch repos: {e}")
+
+@app.get("/api/github/branches")
+async def get_github_repo_branches(request: Request, repo_full_name: str):
+    auth_header = request.headers.get("Authorization")
+    if not auth_header or not auth_header.startswith("Bearer "):
+        raise HTTPException(status_code=401, detail="Unauthorized")
+    token = auth_header.split(" ")[1]
+    try:
+        g = Github(token)
+        repo = g.get_repo(repo_full_name)
+        branches = [branch.name for branch in repo.get_branches()]
+        return branches
+    except GithubException as e:
+        raise HTTPException(status_code=e.status, detail=f"GitHub API error: {e.data.get('message', 'Could not fetch branches.')}")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"An unexpected error occurred while fetching branches: {e}")
+
+
+@app.get("/api/github/tree")
+async def get_github_repo_tree(request: Request, repo_full_name: str, branch: str):
+    auth_header = request.headers.get("Authorization")
+    if not auth_header or not auth_header.startswith("Bearer "):
+        raise HTTPException(status_code=401, detail="Unauthorized")
+    token = auth_header.split(" ")[1]
+    temp_dir = tempfile.mkdtemp(prefix="codescribe-tree-")
+    try:
+        repo_url = f"https://x-access-token:{token}@github.com/{repo_full_name}.git"
+        Repo.clone_from(repo_url, temp_dir, branch=branch, depth=1)
+        repo_path = Path(temp_dir)
+        tree = []
+        for root, dirs, files in os.walk(repo_path):
+            if '.git' in dirs:
+                dirs.remove('.git')
+            current_level = tree
+            rel_path = Path(root).relative_to(repo_path)
+            if str(rel_path) != ".":
+                for part in rel_path.parts:
+                    parent = next((item for item in current_level if item['name'] == part), None)
+                    if not parent: break
+                    current_level = parent.get('children', [])
+            for d in sorted(dirs):
+                current_level.append({'name': d, 'children': []})
+            for f in sorted(files):
+                current_level.append({'name': f})
+        return tree
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to clone or process repo tree: {e}")
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+@app.get("/api/github/branch-exists")
+async def check_branch_exists(request: Request, repo_full_name: str, branch_name: str):
+    auth_header = request.headers.get("Authorization")
+    if not auth_header or not auth_header.startswith("Bearer "):
+        raise HTTPException(status_code=401, detail="Unauthorized")
+    token = auth_header.split(" ")[1]
+
+    try:
+        g = Github(token)
+        repo = g.get_repo(repo_full_name)
+        # The get_branch method throws a 404 GithubException if not found
+        repo.get_branch(branch=branch_name)
+        return {"exists": True}
+    except GithubException as e:
+        if e.status == 404:
+            return {"exists": False}
+        # Re-raise for other errors like permissions, repo not found, etc.
+        raise HTTPException(status_code=e.status, detail=f"GitHub API error: {e.data.get('message', 'Unknown error')}")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"An unexpected error occurred: {e}")
+
+
+@app.post("/process-zip")
+async def process_zip_endpoint(
+    description: str = Form(...),
+    readme_note: str = Form(""),
+    zip_file: UploadFile = File(...),
+    exclude_patterns: str = Form("")
+):
+    exclude_list = [p.strip() for p in exclude_patterns.splitlines() if p.strip()]
+    temp_dir = tempfile.mkdtemp(prefix="codescribe-zip-")
+    project_path = Path(temp_dir)
+    zip_location = project_path / zip_file.filename
+
+    with open(zip_location, "wb+") as f:
+        shutil.copyfileobj(zip_file.file, f)
+    with zipfile.ZipFile(zip_location, 'r') as zip_ref:
+        zip_ref.extractall(project_path)
+    os.remove(zip_location)
+
+    stream_headers = {
+        "Content-Type": "text/plain",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+        "X-Accel-Buffering": "no",
+    }
+
+    # Create a placeholder repo name from the zip filename for the orchestrator
+    placeholder_repo_name = f"zip-upload/{Path(zip_file.filename).stem}"
+
+    return StreamingResponse(
+        process_project(
+            project_path=project_path,
+            description=description,
+            readme_note=readme_note,
+            is_temp=True,
+            exclude_list=exclude_list,
+            repo_full_name=placeholder_repo_name,
+        ),
+        headers=stream_headers,
+        media_type="text/plain"
+    )
+
+@app.post("/process-github")
+async def process_github_endpoint(request: Request,
+    repo_full_name: str = Form(...),
+    base_branch: str = Form(...),
+    new_branch_name: str = Form(...),
+    description: str = Form(...),
+    readme_note: str = Form(""),
+    exclude_patterns: str = Form(""),
+    exclude_paths: List[str] = Form([])
+):
+    auth_header = request.headers.get("Authorization")
+    if not auth_header or not auth_header.startswith("Bearer "):
+        raise HTTPException(status_code=401, detail="Unauthorized")
+    token = auth_header.split(" ")[1]
+
+    # --- Server-side Branch Existence Check (as a fallback) ---
+    try:
+        g = Github(token)
+        repo = g.get_repo(repo_full_name)
+        existing_branches = [b.name for b in repo.get_branches()]
+        if new_branch_name in existing_branches:
+            raise HTTPException(
+                status_code=409, # 409 Conflict is appropriate here
+                detail=f"Branch '{new_branch_name}' already exists. Please use a different name."
+            )
+    except GithubException as e:
+        raise HTTPException(status_code=404, detail=f"Repository '{repo_full_name}' not found or token lacks permissions: {e}")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"An error occurred while checking branches: {e}")
+    # --- END of check ---
+
+    regex_list = [p.strip() for p in exclude_patterns.splitlines() if p.strip()]
+    exclude_list = regex_list + exclude_paths
+
+    temp_dir = tempfile.mkdtemp(prefix="codescribe-git-")
+    project_path = Path(temp_dir)
+    repo_url = f"https://x-access-token:{token}@github.com/{repo_full_name}.git"
+
+    Repo.clone_from(repo_url, project_path, branch=base_branch)
+
+    stream_headers = {
+        "Content-Type": "text/plain",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+        "X-Accel-Buffering": "no",
+    }
+
+    return StreamingResponse(
+        process_project(
+            project_path=project_path,
+            description=description,
+            readme_note=readme_note,
+            is_temp=True,
+            new_branch_name=new_branch_name,
+            repo_full_name=repo_full_name,
+            github_token=token,
+            exclude_list=exclude_list,
+        ),
+        headers=stream_headers,
+        media_type="text/plain"
+    )
+
+@app.get("/download/{file_path}")
+async def download_file(file_path: str):
+    temp_dir = tempfile.gettempdir()
+    full_path = Path(temp_dir) / file_path
+    if not full_path.exists():
+        raise HTTPException(status_code=404, detail="File not found or expired.")
+    return FileResponse(path=full_path, filename=file_path, media_type='application/zip')

server/tasks.py

@@ -0,0 +1,146 @@
+# server/tasks.py
+
+import os
+import shutil
+import tempfile
+import zipfile
+import json
+import asyncio
+from pathlib import Path
+from typing import AsyncGenerator, List
+
+from git import Repo, GitCommandError
+
+from codescribe.config import load_config
+from codescribe.llm_handler import LLMHandler
+from codescribe.orchestrator import DocstringOrchestrator
+from codescribe.readme_generator import ReadmeGenerator
+
+async def process_project(
+    project_path: Path,
+    description: str,
+    readme_note: str,
+    is_temp: bool,
+    exclude_list: List[str],
+    new_branch_name: str = None,
+    repo_full_name: str = None,
+    github_token: str = None
+) -> AsyncGenerator[str, None]:
+
+    loop = asyncio.get_running_loop()
+    queue = asyncio.Queue()
+
+    def emit_event(event: str, data: dict):
+        """A thread-safe way to send events from the worker thread to the async generator."""
+        loop.call_soon_threadsafe(queue.put_nowait, {"event": event, "data": data})
+
+    def _blocking_process():
+        """The main, synchronous processing logic that runs in a separate thread."""
+        try:
+            # --- Setup ---
+            config = load_config()
+            llm_handler = LLMHandler(config.api_keys, progress_callback=lambda msg: emit_event("log", {"message": msg}))
+
+            # --- 1. Docstrings Phase (using the orchestrator) ---
+            doc_orchestrator = DocstringOrchestrator(
+                path_or_url=str(project_path),
+                description=description,
+                exclude=exclude_list,
+                llm_handler=llm_handler,
+                progress_callback=emit_event,
+                repo_full_name=repo_full_name  # <<< THIS IS THE FIX
+            )
+            doc_orchestrator.project_path = project_path
+            doc_orchestrator.is_temp_dir = False
+            doc_orchestrator.run()
+
+            # --- 2. READMEs Phase (using the generator) ---
+            readme_gen = ReadmeGenerator(
+                path_or_url=str(project_path),
+                description=description,
+                exclude=exclude_list,
+                llm_handler=llm_handler,
+                user_note=readme_note,
+                progress_callback=emit_event,
+                repo_full_name=repo_full_name
+            )
+            readme_gen.project_path = project_path
+            readme_gen.is_temp_dir = False
+            readme_gen.run()
+
+            # --- 3. Output Phase ---
+            emit_event("phase", {"id": "output", "status": "in-progress"})
+            if new_branch_name:
+                # Git logic remains the same
+                emit_event("subtask", {"parentId": "output", "listId": "output-step-list", "id": "git-check", "name": "Checking for changes...", "status": "in-progress"})
+                repo = Repo(project_path)
+                
+                if repo.untracked_files:
+                    repo.git.add(repo.untracked_files)
+
+                if not repo.is_dirty(untracked_files=True):
+                    emit_event("subtask", {"parentId": "output", "id": "git-check", "status": "success"})
+                    emit_event("log", {"message": "No changes were generated by the AI."})
+                    emit_event("done", {"type": "github", "url": f"https://github.com/{repo_full_name}", "message": "✅ No changes needed. Your repository is up to date."})
+                    return
+
+                emit_event("subtask", {"parentId": "output", "id": "git-check", "status": "success"})
+                emit_event("subtask", {"parentId": "output", "listId": "output-step-list", "id": "git-push", "name": f"Pushing to branch '{new_branch_name}'...", "status": "in-progress"})
+                
+                try:
+                    if new_branch_name in repo.heads:
+                        repo.heads[new_branch_name].checkout()
+                    else:
+                        repo.create_head(new_branch_name).checkout()
+
+                    repo.git.add(A=True)
+                    repo.index.commit("docs: Add AI-generated documentation by CodeScribe")
+                    
+                    origin = repo.remote(name='origin')
+                    origin.push(new_branch_name, force=True)
+                    
+                    pr_url = f"https://github.com/{repo_full_name}/pull/new/{new_branch_name}"
+                    emit_event("subtask", {"parentId": "output", "id": "git-push", "status": "success"})
+                    emit_event("done", {"type": "github", "url": pr_url, "message": "✅ Successfully pushed changes!"})
+
+                except GitCommandError as e:
+                    emit_event("log", {"message": f"Git Error: {e}"})
+                    raise RuntimeError(f"Failed to push to GitHub: {e}")
+            else:
+                # ZIP logic remains the same
+                emit_event("subtask", {"parentId": "output", "listId": "output-step-list", "id": "zip-create", "name": "Creating downloadable ZIP file...", "status": "in-progress"})
+                
+                temp_dir = tempfile.gettempdir()
+                try:
+                    contained_dir = next(project_path.iterdir())
+                    project_name = contained_dir.name
+                except StopIteration:
+                    project_name = "documented-project"
+                
+                zip_filename_base = f"codescribe-docs-{project_name}"
+                zip_path_base = Path(temp_dir) / zip_filename_base
+                
+                zip_full_path = shutil.make_archive(str(zip_path_base), 'zip', project_path)
+                zip_file_name = Path(zip_full_path).name
+                
+                emit_event("subtask", {"parentId": "output", "id": "zip-create", "status": "success"})
+                emit_event("done", {"type": "zip", "download_path": zip_file_name, "message": "✅ Your documented project is ready for download."})
+
+            emit_event("phase", {"id": "output", "status": "success"})
+
+        except Exception as e:
+            emit_event("error", str(e))
+        finally:
+            loop.call_soon_threadsafe(queue.put_nowait, None)
+
+    # Async runner remains the same
+    main_task = loop.run_in_executor(None, _blocking_process)
+    while True:
+        message = await queue.get()
+        if message is None:
+            break
+        json_line = json.dumps({"type": message["event"], "payload": message["data"]})
+        yield f"{json_line}\n"
+    await main_task
+    if is_temp and project_path and project_path.exists():
+        shutil.rmtree(project_path, ignore_errors=True)

static/index.html

@@ -0,0 +1,183 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+  <title>CodeScribe AI</title>
+  <link rel="stylesheet" href="/static/style.css"/>
+  <meta name="color-scheme" content="dark light"/>
+</head>
+<body>
+   <!-- Decorative Background  -->
+  <div class="bg">
+    <div class="bg-gradient"></div>
+    <div class="bg-grid"></div>
+    <canvas id="bg-canvas" aria-hidden="true"></canvas>
+  </div>
+
+  <main class="shell">
+    <div class="container glass-card" data-animate>
+      <header class="app-header">
+        <div class="brand">
+          <div class="brand-mark" aria-hidden="true">
+            <span class="dot dot-1"></span>
+            <span class="dot dot-2"></span>
+            <span class="dot dot-3"></span>
+          </div>
+          <h1 class="title text-gradient">CodeScribe AI</h1>
+        </div>
+        <p class="subtitle">AI-powered project documentation, right in your browser.</p>
+      </header>
+
+       <!-- Auth  -->
+      <section id="auth-section" class="panel" data-animate>
+        <button id="github-login-btn" class="btn btn-primary btn-glow" aria-label="Login with GitHub">
+          <span class="btn-inner">
+            <svg class="icon" width="20" height="20" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M8 .198a8 8 0 0 0-2.53 15.6c.4.073.547-.173.547-.385v-1.35c-2.226.483-2.695-1.073-2.695-1.073c-.364-.925-.89-1.172-.89-1.172c-.727-.497.055-.487.055-.487c.803.056 1.225.825 1.225.825c.715 1.224 1.874.87 2.33.665c.073-.518.28-.871.508-1.072C4.9 9.83 3 9.232 3 6.58c0-.87.31-1.58.824-2.136c-.083-.203-.357-1.02.078-2.127c0 0 .673-.215 2.206.817c.64-.18 1.325-.27 2.006-.273c.68.003 1.365.093 2.006.273c1.532-1.032 2.204-.817 2.204-.817c.437 1.107.163 1.924.08 2.127C12.69 5 13 5.71 13 6.58c0 2.66-1.902 3.248-3.714 3.419c.287.247.543.736.543 1.484v2.2c0 .214.145.462.55.384A8 8 0 0 0 8 .198"/></svg>
+            <span>Login with GitHub</span>
+          </span>
+        </button>
+      </section>
+
+       <!-- Main Content  -->
+      <section id="main-content" class="hidden" data-animate>
+         <!-- Tabs  -->
+        <div class="tabs">
+          <button id="select-zip-btn" class="tab-btn active" type="button">
+            <span>Upload Zip</span>
+          </button>
+          <button id="select-github-btn" class="tab-btn" type="button">
+            <span>Use GitHub Repo</span>
+          </button>
+          <span class="tab-indicator" aria-hidden="true"></span>
+        </div>
+
+         <!-- Form  -->
+        <form id="doc-form" class="form">
+           GitHub Inputs 
+          <div id="github-inputs" class="panel">
+            <div class="form-row">
+              <div class="form-group">
+                <label for="repo-select">Select a Repository</label>
+                <select id="repo-select" name="repo_full_name" required></select>
+              </div>
+              <div class="form-group">
+                <label for="base-branch-select">Base Branch</label>
+                <select id="base-branch-select" name="base_branch" required></select>
+              </div>
+            </div>
+            <div class="form-group">
+              <label for="new-branch-input">New Branch Name</label>
+              <input id="new-branch-input" type="text" name="new_branch_name" value="docs/codescribe-ai" required/>
+              <small id="branch-name-error" class="form-error" aria-live="polite" style="display:none;"></small>
+            </div>
+          </div>
+
+           <!-- ZIP Inputs  -->
+          <div id="zip-inputs" class="panel hidden">
+            <div class="form-group">
+              <label for="zip-file">Upload Project as .zip</label>
+              <input id="zip-file" type="file" name="zip_file" accept=".zip" required/>
+            </div>
+          </div>
+
+          <div class="divider"></div>
+
+           <!-- Common Inputs  -->
+          <div class="panel">
+            <div class="form-group">
+              <label for="description">Short Project Description</label>
+              <textarea id="description" name="description" rows="3" required placeholder="e.g., A Python library for advanced data analysis and visualization."></textarea>
+            </div>
+            <div class="form-group">
+              <label for="readme-note">Note for README (Optional)</label>
+              <textarea id="readme-note" name="readme_note" rows="2" placeholder="e.g., Emphasize the new data processing pipeline. Mention the v2.0 release."></textarea>
+            </div>
+          </div>
+
+          <div class="divider"></div>
+
+          <div class="panel">
+            <div class="form-group">
+              <label for="exclude-patterns">Exclude (Regex Patterns)</label>
+              <textarea id="exclude-patterns" name="exclude_patterns" rows="2" placeholder="e.g., tests/.*, .*/migrations/.*, specific_file.py"></textarea>
+              <small>One regex pattern per line. Matches relative paths like 'src/utils/helpers.py'.</small>
+            </div>
+
+            <div id="file-tree-container" class="form-group hidden">
+              <label>Exclude Specific Files/Folders</label>
+              <div id="file-tree" class="tree"></div>
+            </div>
+          </div>
+
+          <div class="form-actions">
+            <button id="submit-btn" type="submit" class="btn btn-primary btn-glow">
+              <span class="btn-inner">
+                <span class="loader" aria-hidden="true"></span>
+                <span>Generate Documentation</span>
+              </span>
+            </button>
+          </div>
+        </form>
+      </section>
+
+       <!-- Live Progress  -->
+      <section id="live-progress-view" class="hidden" data-animate>
+        <h2 class="section-title">Processing Your Project...</h2>
+        <div class="progress-layout">
+          <ul id="phase-list" class="timeline">
+            <li id="phase-scan" class="phase-item" data-status="pending">
+              <span class="status-icon" aria-hidden="true"></span>
+              <div class="phase-details">
+                <span class="phase-title">1. Scan Project Files</span>
+                <ul class="subtask-list" id="scan-file-list"></ul>
+              </div>
+            </li>
+            <li id="phase-docstrings" class="phase-item" data-status="pending">
+              <span class="status-icon" aria-hidden="true"></span>
+              <div class="phase-details">
+                <span class="phase-title">2. Generate Docstrings</span>
+                <ul class="subtask-list" id="docstring-file-list"></ul>
+                <ul class="subtask-list" id="docstring-module-list"></ul>
+                <ul class="subtask-list" id="docstring-package-list"></ul>
+              </div>
+            </li>
+            <li id="phase-readmes" class="phase-item" data-status="pending">
+              <span class="status-icon" aria-hidden="true"></span>
+              <div class="phase-details">
+                <span class="phase-title">3. Generate READMEs</span>
+                <ul class="subtask-list" id="readme-dir-list"></ul>
+              </div>
+            </li>
+            <li id="phase-output" class="phase-item" data-status="pending">
+              <span class="status-icon" aria-hidden="true"></span>
+              <div class="phase-details">
+                <span class="phase-title">4. Finalize and Push</span>
+                <ul class="subtask-list" id="output-step-list"></ul>
+              </div>
+            </li>
+          </ul>
+
+          <div id="raw-log-container" class="terminal">
+            <div class="terminal-head">
+              <span class="dot red" aria-hidden="true"></span>
+              <span class="dot yellow" aria-hidden="true"></span>
+              <span class="dot green" aria-hidden="true"></span>
+              <h4>Live Log Details</h4>
+            </div>
+            <pre id="log-output" class="terminal-body" aria-live="polite"></pre>
+          </div>
+        </div>
+      </section>
+
+       <!-- Result  -->
+      <section id="result-section" class="hidden" data-animate>
+        <h2 class="section-title success">Complete!</h2>
+        <div id="result-link" class="result-card"></div>
+      </section>
+    </div>
+  </main>
+
+  <script src="/static/script.js" defer></script>
+</body>
+</html>

static/script.js

@@ -0,0 +1,541 @@
+document.addEventListener("DOMContentLoaded", () => {
+  // --- Constants ---
+  const GITHUB_TOKEN_KEY = "github_access_token";
+
+  // --- DOM Element Cache ---
+  const docForm = document.getElementById("doc-form");
+  const submitBtn = document.getElementById("submit-btn");
+  const authSection = document.getElementById("auth-section");
+  const mainContent = document.getElementById("main-content");
+  const githubLoginBtn = document.getElementById("github-login-btn");
+  const selectZipBtn = document.getElementById("select-zip-btn");
+  const selectGithubBtn = document.getElementById("select-github-btn");
+  const zipInputs = document.getElementById("zip-inputs");
+  const githubInputs = document.getElementById("github-inputs");
+  const zipFileInput = document.getElementById("zip-file");
+  const repoSelect = document.getElementById("repo-select");
+  const baseBranchSelect = document.getElementById("base-branch-select");
+  const newBranchInput = document.getElementById("new-branch-input");
+  const branchNameError = document.getElementById("branch-name-error");
+  const fileTreeContainer = document.getElementById("file-tree-container");
+  const fileTree = document.getElementById("file-tree");
+  const liveProgressView = document.getElementById("live-progress-view");
+  const resultSection = document.getElementById("result-section");
+  const resultLink = document.getElementById("result-link");
+  const logOutput = document.getElementById("log-output");
+
+  // --- Helper Functions ---
+  const showView = (viewId) => {
+    [authSection, mainContent, liveProgressView, resultSection].forEach((el) =>
+      el.classList.add("hidden")
+    );
+    document.getElementById(viewId).classList.remove("hidden");
+  };
+  const sanitizeForId = (str) =>
+    `subtask-${str.replace(/[^a-zA-Z0-9-]/g, "-")}`;
+  const resetProgressView = () => {
+    document
+      .querySelectorAll(".phase-item")
+      .forEach((item) => (item.dataset.status = "pending"));
+    document
+      .querySelectorAll(".subtask-list")
+      .forEach((list) => (list.innerHTML = ""));
+    logOutput.textContent = "";
+  };
+  const createTreeHtml = (nodes, pathPrefix = "") => {
+    let html = "<ul>";
+    nodes.forEach((node) => {
+      const fullPath = pathPrefix ? `${pathPrefix}/${node.name}` : node.name;
+      const isDir = !!node.children;
+      html += `<li><input type="checkbox" name="exclude_paths" value="${fullPath}" id="cb-${fullPath}"> <label for="cb-${fullPath}"><strong>${
+        node.name
+      }${isDir ? "/" : ""}</strong></label>`;
+      if (isDir) html += createTreeHtml(node.children, fullPath);
+      html += "</li>";
+    });
+    html += "</ul>";
+    return html;
+  };
+
+  // --- Core Logic (unchanged app behavior) ---
+  const checkBranchName = async () => {
+    const repoFullName = repoSelect.value;
+    const branchName = newBranchInput.value.trim();
+    const token = localStorage.getItem(GITHUB_TOKEN_KEY);
+
+    branchNameError.textContent = "";
+    branchNameError.style.display = "none";
+
+    if (
+      !repoFullName ||
+      !branchName ||
+      !token ||
+      !selectGithubBtn.classList.contains("active")
+    ) {
+      submitBtn.disabled = false;
+      return;
+    }
+
+    submitBtn.disabled = true;
+    submitBtn
+      .querySelector(".btn-inner span:last-child")
+      ?.replaceWith(document.createTextNode("Checking branch..."));
+
+    try {
+      const response = await fetch(
+        `/api/github/branch-exists?repo_full_name=${encodeURIComponent(
+          repoFullName
+        )}&branch_name=${encodeURIComponent(branchName)}`,
+        {
+          headers: { Authorization: `Bearer ${token}` },
+        }
+      );
+
+      if (!response.ok) {
+        const errData = await response.json();
+        throw new Error(errData.detail || `Server error: ${response.status}`);
+      }
+
+      const data = await response.json();
+      if (data.exists) {
+        branchNameError.textContent = `Branch '${branchName}' already exists. Please choose another name.`;
+        branchNameError.style.display = "block";
+        submitBtn.disabled = true;
+      } else {
+        submitBtn.disabled = false;
+      }
+    } catch (error) {
+      console.error("Error checking branch name:", error);
+      branchNameError.textContent = `Could not verify branch name. ${error.message}`;
+      branchNameError.style.display = "block";
+      submitBtn.disabled = false; // Allow submission, server will catch it if it's a real issue.
+    } finally {
+      // Restore button text
+      const inner = submitBtn.querySelector(".btn-inner");
+      if (inner) {
+        inner.innerHTML =
+          '<span class="loader" aria-hidden="true"></span><span>Generate Documentation</span>';
+      }
+    }
+  };
+
+  const handleAuth = () => {
+    const urlParams = new URLSearchParams(window.location.search);
+    const token = urlParams.get("token");
+    const error = urlParams.get("error");
+
+    if (error) alert(`Authentication failed: ${error}`);
+    if (token && token !== "None")
+      localStorage.setItem(GITHUB_TOKEN_KEY, token);
+    window.history.replaceState({}, document.title, "/");
+
+    if (localStorage.getItem(GITHUB_TOKEN_KEY)) {
+      // --- Logged In User Flow ---
+      showView("main-content");
+      fetchGithubRepos();
+      switchMode("github");
+    } else {
+      // --- Logged Out User Flow (FIXED) ---
+      // 1. Always show the main form content, not the separate auth screen.
+      // This makes the form, including ZIP upload, always accessible.
+      showView("main-content");
+
+      // 2. The auth section with the login button should be visible.
+      // We manually un-hide it because showView is designed to show only one view.
+      authSection.classList.remove("hidden");
+
+      // 3. Default to ZIP mode and disable the GitHub tab.
+      switchMode("zip");
+      selectGithubBtn.disabled = true;
+    }
+  };
+
+  const fetchGithubRepos = async () => {
+    const token = localStorage.getItem(GITHUB_TOKEN_KEY);
+    if (!token) return;
+
+    try {
+      const response = await fetch("/api/github/repos", {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      if (response.status === 401) {
+        localStorage.removeItem(GITHUB_TOKEN_KEY);
+        alert("GitHub session expired. Please log in again.");
+        handleAuth();
+        return;
+      }
+      if (!response.ok) throw new Error("Failed to fetch repos");
+
+      const repos = await response.json();
+      repoSelect.innerHTML =
+        '<option value="">-- Select a repository --</option>';
+      repos.forEach((repo) => {
+        const option = document.createElement("option");
+        option.value = repo.full_name;
+        option.textContent = repo.full_name;
+        option.dataset.defaultBranch = repo.default_branch;
+        repoSelect.appendChild(option);
+      });
+    } catch (error) {
+      console.error(error);
+    }
+  };
+
+  const fetchRepoBranches = async (repoFullName, defaultBranch) => {
+    const token = localStorage.getItem(GITHUB_TOKEN_KEY);
+    if (!token || !repoFullName) return;
+
+    baseBranchSelect.innerHTML = "<option>Loading branches...</option>";
+    baseBranchSelect.disabled = true;
+
+    try {
+      const response = await fetch(
+        `/api/github/branches?repo_full_name=${repoFullName}`,
+        {
+          headers: { Authorization: `Bearer ${token}` },
+        }
+      );
+      if (!response.ok) throw new Error("Failed to fetch branches");
+      const branches = await response.json();
+
+      baseBranchSelect.innerHTML = "";
+      branches.forEach((branchName) => {
+        const option = document.createElement("option");
+        option.value = branchName;
+        option.textContent = branchName;
+        if (branchName === defaultBranch) option.selected = true;
+        baseBranchSelect.appendChild(option);
+      });
+    } catch (error) {
+      console.error(error);
+      baseBranchSelect.innerHTML = `<option>Error loading branches</option>`;
+    } finally {
+      baseBranchSelect.disabled = false;
+    }
+  };
+
+  const fetchAndBuildTree = async (repoFullName, branch) => {
+    fileTreeContainer.classList.remove("hidden");
+    fileTree.innerHTML = "<em>Loading repository file tree...</em>";
+    const token = localStorage.getItem(GITHUB_TOKEN_KEY);
+    if (!token || !repoFullName || !branch) return;
+
+    try {
+      const response = await fetch(
+        `/api/github/tree?repo_full_name=${repoFullName}&branch=${branch}`,
+        {
+          headers: { Authorization: `Bearer ${token}` },
+        }
+      );
+      if (!response.ok)
+        throw new Error(
+          `Failed to fetch file tree (status: ${response.status})`
+        );
+      const treeData = await response.json();
+      fileTree.innerHTML = createTreeHtml(treeData);
+    } catch (error) {
+      console.error(error);
+      fileTree.innerHTML = `<em style="color: #ef4444;">${error.message}</em>`;
+    }
+  };
+
+// --- In script.js ---
+
+  const switchMode = (mode) => {
+    fileTreeContainer.classList.add("hidden");
+    if (mode === "github") {
+      selectGithubBtn.classList.add("active");
+      selectZipBtn.classList.remove("active");
+      githubInputs.classList.remove("hidden");
+      zipInputs.classList.add("hidden");
+      // GitHub Mode: ZIP is not required, GitHub fields are.
+      zipFileInput.required = false;
+      repoSelect.required = true;
+      baseBranchSelect.required = true;
+      newBranchInput.required = true;
+      if (repoSelect.value)
+        fetchAndBuildTree(repoSelect.value, baseBranchSelect.value);
+    } else { // This is ZIP mode
+      selectZipBtn.classList.add("active");
+      selectGithubBtn.classList.remove("active");
+      zipInputs.classList.remove("hidden");
+      githubInputs.classList.add("hidden");
+      // ZIP Mode: ZIP is required, GitHub fields are not.
+      zipFileInput.required = true;
+      repoSelect.required = false;
+      baseBranchSelect.required = false; // <-- FIX: Added this line
+      newBranchInput.required = false;   // <-- FIX: Added this line
+    }
+  };
+
+  const handleFormSubmit = (e) => {
+    e.preventDefault();
+    resetProgressView();
+    showView("live-progress-view");
+    submitBtn.disabled = true;
+
+    const formData = new FormData(docForm);
+    const endpoint = selectGithubBtn.classList.contains("active")
+      ? "/process-github"
+      : "/process-zip";
+
+    const headers = new Headers();
+    if (endpoint === "/process-github") {
+      headers.append(
+        "Authorization",
+        `Bearer ${localStorage.getItem(GITHUB_TOKEN_KEY)}`
+      );
+    }
+
+    const options = { method: "POST", body: formData, headers: headers };
+
+    fetch(endpoint, options)
+      .then((response) => {
+        if (!response.ok) {
+          return response.json().then((errData) => {
+            throw new Error(
+              `Server error: ${response.status} - ${
+                errData.detail || "Unknown error"
+              }`
+            );
+          });
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+
+        function push() {
+          reader
+            .read()
+            .then(({ done, value }) => {
+              if (done) {
+                if (buffer) {
+                  try {
+                    const json = JSON.parse(buffer);
+                    handleStreamEvent(json.type, json.payload);
+                  } catch (e) {
+                    console.error(
+                      "Error parsing final buffer chunk:",
+                      buffer,
+                      e
+                    );
+                  }
+                }
+                return;
+              }
+              buffer += decoder.decode(value, { stream: true });
+              const lines = buffer.split("\n");
+              buffer = lines.pop();
+              for (const line of lines) {
+                if (line.trim() === "") continue;
+                try {
+                  const json = JSON.parse(line);
+                  handleStreamEvent(json.type, json.payload);
+                } catch (e) {
+                  console.error("Failed to parse JSON line:", line, e);
+                }
+              }
+              push();
+            })
+            .catch((err) => {
+              console.error("Stream reading error:", err);
+              handleStreamEvent("error", `Stream error: ${err.message}`);
+            });
+        }
+        push();
+      })
+      .catch((err) => handleStreamEvent("error", `${err.message}`));
+  };
+
+  const handleStreamEvent = (type, payload) => {
+    switch (type) {
+      case "phase": {
+        const phaseEl = document.getElementById(`phase-${payload.id}`);
+        if (phaseEl) phaseEl.dataset.status = payload.status;
+        break;
+      }
+      case "subtask": {
+        const subtaskId = sanitizeForId(payload.id);
+        let subtaskEl = document.getElementById(subtaskId);
+        const listEl = document.getElementById(payload.listId);
+        if (!subtaskEl && listEl) {
+          subtaskEl = document.createElement("li");
+          subtaskEl.id = subtaskId;
+          subtaskEl.textContent = payload.name;
+          listEl.appendChild(subtaskEl);
+        }
+        if (subtaskEl) subtaskEl.dataset.status = payload.status;
+        break;
+      }
+      case "log": {
+        logOutput.textContent += payload.message.replace(/\\n/g, "\n") + "\n";
+        logOutput.scrollTop = logOutput.scrollHeight;
+        break;
+      }
+      case "error": {
+        document
+          .querySelectorAll('.phase-item[data-status="in-progress"]')
+          .forEach((el) => (el.dataset.status = "error"));
+        logOutput.textContent += `\n\n--- ERROR ---\n${payload}\n`;
+        submitBtn.disabled = false;
+        break;
+      }
+      case "done": {
+        showView("result-section");
+        resultLink.innerHTML = `<p>${payload.message}</p>`;
+        if (payload.type === "zip") {
+          resultLink.innerHTML += `<a href="/download/${payload.download_path}" class="button-link" download>Download ZIP</a>`;
+        } else if (payload.url) {
+          const linkText = payload.url.includes("/pull/new/")
+            ? "Create Pull Request"
+            : "View Repository";
+          resultLink.innerHTML += `<a href="${payload.url}" target="_blank" rel="noopener noreferrer" class="button-link">${linkText}</a>`;
+        }
+        submitBtn.disabled = false;
+        break;
+      }
+    }
+  };
+
+  // --- Events ---
+  githubLoginBtn.addEventListener(
+    "click",
+    () => (window.location.href = "/login/github")
+  );
+  selectZipBtn.addEventListener("click", () => switchMode("zip"));
+  selectGithubBtn.addEventListener("click", () => switchMode("github"));
+  docForm.addEventListener("submit", handleFormSubmit);
+
+  repoSelect.addEventListener("change", async (e) => {
+    const selectedOption = e.target.options[e.target.selectedIndex];
+    const repoFullName = selectedOption.value;
+    const defaultBranch = selectedOption.dataset.defaultBranch || "";
+
+    if (repoFullName) {
+      await fetchRepoBranches(repoFullName, defaultBranch);
+      fetchAndBuildTree(repoFullName, baseBranchSelect.value);
+      checkBranchName();
+    } else {
+      baseBranchSelect.innerHTML = "";
+      fileTreeContainer.classList.add("hidden");
+    }
+  });
+
+  baseBranchSelect.addEventListener("change", () => {
+    fetchAndBuildTree(repoSelect.value, baseBranchSelect.value);
+  });
+
+  newBranchInput.addEventListener("blur", checkBranchName);
+
+  // Initialize
+  handleAuth();
+
+  // --- UI Enhancements: glow cursor on buttons ---
+  document.querySelectorAll(".btn-glow").forEach((btn) => {
+    btn.addEventListener("pointermove", (e) => {
+      const rect = btn.getBoundingClientRect();
+      const x = ((e.clientX - rect.left) / rect.width) * 100;
+      const y = ((e.clientY - rect.top) / rect.height) * 100;
+      btn.style.setProperty("--x", x + "%");
+      btn.style.setProperty("--y", y + "%");
+    });
+  });
+
+  // --- Ripple effect for buttons and links ---
+  function addRipple(e) {
+    const el = e.currentTarget;
+    const rect = el.getBoundingClientRect();
+    const circle = document.createElement("span");
+    circle.className = "ripple";
+    circle.style.left = `${e.clientX - rect.left}px`;
+    circle.style.top = `${e.clientY - rect.top}px`;
+    el.appendChild(circle);
+    setTimeout(() => circle.remove(), 600);
+  }
+  document.querySelectorAll("button.btn, .button-link").forEach((el) => {
+    el.addEventListener("click", addRipple);
+  });
+
+  // --- Subtle parallax tilt on hover for panels and phase items ---
+  const tiltEls = document.querySelectorAll(
+    ".panel, .phase-item, .terminal, .glass-card"
+  );
+  tiltEls.forEach((el) => {
+    let enter = false;
+    el.addEventListener("pointerenter", () => {
+      enter = true;
+    });
+    el.addEventListener("pointerleave", () => {
+      enter = false;
+      el.style.transform = "";
+    });
+    el.addEventListener("pointermove", (e) => {
+      if (!enter) return;
+      const rect = el.getBoundingClientRect();
+      const cx = rect.left + rect.width / 2;
+      const cy = rect.top + rect.height / 2;
+      const dx = (e.clientX - cx) / rect.width;
+      const dy = (e.clientY - cy) / rect.height;
+      const max = 6;
+      el.style.transform = `rotateX(${(-dy * max).toFixed(2)}deg) rotateY(${(
+        dx * max
+      ).toFixed(2)}deg) translateZ(0)`;
+    });
+  });
+
+  // --- Optional: lightweight animated background canvas (respects reduced motion) ---
+  const prefersReduced = window.matchMedia(
+    "(prefers-reduced-motion: reduce)"
+  ).matches;
+  const canvas = document.getElementById("bg-canvas");
+  if (canvas && !prefersReduced) {
+    const ctx = canvas.getContext("2d", { alpha: true });
+    let w, h, dots;
+    function resize() {
+      w = canvas.width = window.innerWidth;
+      h = canvas.height = window.innerHeight;
+      dots = Array.from(
+        { length: Math.min(90, Math.floor((w * h) / 60000)) },
+        () => ({
+          x: Math.random() * w,
+          y: Math.random() * h,
+          vx: (Math.random() - 0.5) * 0.4,
+          vy: (Math.random() - 0.5) * 0.4,
+        })
+      );
+    }
+    function step() {
+      ctx.clearRect(0, 0, w, h);
+      ctx.fillStyle = "rgba(34, 211, 238, 0.6)";
+      const threshold = 120;
+      for (let i = 0; i < dots.length; i++) {
+        const a = dots[i];
+        a.x += a.vx;
+        a.y += a.vy;
+        if (a.x < 0 || a.x > w) a.vx *= -1;
+        if (a.y < 0 || a.y > h) a.vy *= -1;
+        ctx.beginPath();
+        ctx.arc(a.x, a.y, 1.2, 0, Math.PI * 2);
+        ctx.fill();
+        for (let j = i + 1; j < dots.length; j++) {
+          const b = dots[j];
+          const dx = a.x - b.x,
+            dy = a.y - b.y;
+          const dist = Math.hypot(dx, dy);
+          if (dist < threshold) {
+            const alpha = (1 - dist / threshold) * 0.2;
+            ctx.strokeStyle = `rgba(96,165,250,${alpha})`;
+            ctx.beginPath();
+            ctx.moveTo(a.x, a.y);
+            ctx.lineTo(b.x, b.y);
+            ctx.stroke();
+          }
+        }
+      }
+      requestAnimationFrame(step);
+    }
+    window.addEventListener("resize", resize);
+    resize();
+    step();
+  }
+});

static/style.css

@@ -0,0 +1,406 @@
+
+:root {
+  --bg: #0b1220;
+  --bg-2: #0d1528;
+  --panel: rgba(16, 24, 40, 0.72);
+  --panel-solid: #101828;
+  --card: rgba(17, 24, 39, 0.7);
+  --border: rgba(148, 163, 184, 0.16);
+  --text: #e2e8f0;
+  --muted: #94a3b8;
+  --primary: #22d3ee; /* cyan */
+  --primary-2: #06b6d4;
+  --success: #22c55e;
+  --danger: #ef4444;
+  --warning: #f59e0b;
+  --shadow: 0 10px 30px rgba(2, 8, 23, 0.6);
+  --radius: 14px;
+  --radius-sm: 10px;
+  --radius-lg: 20px;
+  --ring: 0 0 0 2px rgba(34, 211, 238, 0.35), 0 0 0 6px rgba(34, 211, 238, 0.15);
+}
+
+* { box-sizing: border-box; }
+html, body { height: 100%; }
+body {
+  margin: 0;
+  color: var(--text);
+  background: var(--bg);
+  font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, Apple Color Emoji, Segoe UI Emoji;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* Background */
+.bg {
+  position: fixed; inset: 0; overflow: hidden; z-index: -1;
+}
+.bg-gradient {
+  position: absolute; inset: -20%;
+  background:
+    radial-gradient(60% 60% at 10% 10%, rgba(34,211,238,0.12) 0%, transparent 60%),
+    radial-gradient(40% 40% at 90% 20%, rgba(59,130,246,0.12) 0%, transparent 60%),
+    radial-gradient(50% 50% at 50% 100%, rgba(16,185,129,0.1) 0%, transparent 60%);
+  filter: blur(40px);
+  animation: bgShift 20s ease-in-out infinite alternate;
+}
+@keyframes bgShift {
+  0% { transform: translateY(-2%) scale(1); }
+  100% { transform: translateY(2%) scale(1.04); }
+}
+.bg-grid {
+  position: absolute; inset: 0;
+  background-image:
+    linear-gradient(to right, rgba(148,163,184,0.08) 1px, transparent 1px),
+    linear-gradient(to bottom, rgba(148,163,184,0.08) 1px, transparent 1px);
+  background-size: 40px 40px, 40px 40px;
+  mask-image: radial-gradient(ellipse at center, #000 60%, transparent 100%);
+  animation: gridPan 30s linear infinite;
+}
+@keyframes gridPan {
+  from { background-position: 0 0, 0 0; }
+  to { background-position: 40px 40px, 40px 40px; }
+}
+
+/* Layout */
+.shell {
+  min-height: 100svh;
+  display: grid;
+  place-items: center;
+  padding: 24px;
+}
+.container {
+  width: 100%;
+  max-width: 980px;
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  box-shadow: var(--shadow);
+  backdrop-filter: saturate(140%) blur(12px);
+  padding: 28px;
+}
+.glass-card[data-animate] {
+  opacity: 0; transform: translateY(8px);
+  animation: fadeInUp 600ms ease forwards;
+}
+[data-animate].hidden { opacity: 0 !important; transform: none; animation: none !important; }
+@keyframes fadeInUp {
+  0% { opacity: 0; transform: translateY(10px) scale(.98); }
+  100% { opacity: 1; transform: translateY(0) scale(1); }
+}
+.panel {
+  background: linear-gradient(180deg, rgba(15,23,42,0.6), rgba(15,23,42,0.35));
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 16px;
+}
+
+/* Header */
+.app-header { text-align: center; margin-bottom: 16px; }
+.brand {
+  display: flex; align-items: center; justify-content: center; gap: 12px;
+}
+.brand-mark {
+  position: relative; width: 36px; height: 36px;
+  background: radial-gradient(circle at 30% 30%, var(--primary), transparent 60%),
+              radial-gradient(circle at 70% 70%, #60a5fa, transparent 60%);
+  border-radius: 12px;
+  border: 1px solid var(--border);
+  box-shadow: inset 0 0 20px rgba(34,211,238,0.15), 0 10px 20px rgba(2,8,23,0.6);
+  overflow: visible;
+}
+.brand-mark .dot {
+  position: absolute; width: 6px; height: 6px; border-radius: 50%;
+  background: var(--text); opacity: .7; filter: blur(.3px);
+}
+.dot-1 { top: 6px; left: 6px; animation: float 3.6s ease-in-out infinite; }
+.dot-2 { bottom: 8px; right: 8px; animation: float 3.2s 250ms ease-in-out infinite; }
+.dot-3 { top: 8px; right: 6px; animation: float 3.8s 400ms ease-in-out infinite; }
+@keyframes float {
+  0%,100% { transform: translateY(0); }
+  50% { transform: translateY(-3px); }
+}
+.title {
+  margin: 0;
+  font-size: clamp(28px, 3.8vw, 40px);
+  letter-spacing: -.02em;
+}
+.text-gradient {
+  background: linear-gradient(90deg, #e2e8f0 0%, var(--primary) 50%, #60a5fa 100%);
+  -webkit-background-clip: text; background-clip: text; color: transparent;
+}
+.subtitle {
+  margin: 8px auto 0;
+  color: var(--muted);
+  max-width: 48ch;
+}
+
+/* Tabs */
+.tabs {
+  position: relative;
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 8px;
+  background: rgba(148,163,184,0.08);
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  padding: 6px;
+  margin: 18px 0 12px;
+}
+.tab-btn {
+  position: relative;
+  border: none;
+  background: transparent;
+  color: var(--muted);
+  padding: 10px 14px;
+  border-radius: 999px;
+  cursor: pointer;
+  font-weight: 600;
+  transition: color .2s ease;
+  z-index: 1;
+}
+.tab-btn.active { color: var(--text); }
+.tab-indicator {
+  position: absolute; top: 6px; bottom: 6px; width: calc(50% - 6px);
+  background: linear-gradient(180deg, rgba(34,211,238,0.16), rgba(59,130,246,0.12));
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  box-shadow: inset 0 0 0 1px rgba(255,255,255,0.04), 0 6px 18px rgba(2,8,23,0.6);
+  transition: transform .35s cubic-bezier(.2,.8,.2,1);
+  transform: translateX(0);
+}
+.tab-btn.active ~ .tab-indicator { transform: translateX(0); }
+#select-github-btn.tab-btn.active ~ .tab-indicator { transform: translateX(100%); }
+
+/* Form */
+.form { display: grid; gap: 12px; }
+.form-row { display: grid; gap: 12px; grid-template-columns: 1fr; }
+@media (min-width: 700px){ .form-row { grid-template-columns: 1fr 1fr; } }
+
+.form-group { display: grid; gap: 8px; }
+label { font-weight: 600; color: var(--text); }
+small { color: var(--muted); }
+
+input[type="text"],
+input[type="file"],
+select,
+textarea {
+  width: 100%;
+  padding: 12px 12px;
+  border-radius: 10px;
+  border: 1px solid var(--border);
+  color: var(--text);
+  background: linear-gradient(180deg, rgba(14,22,38,0.9), rgba(14,22,38,0.6));
+  outline: none;
+  transition: box-shadow .2s ease, border-color .2s ease, transform .08s ease;
+}
+textarea { resize: vertical; min-height: 92px; }
+input:focus, select:focus, textarea:focus {
+  border-color: rgba(34,211,238,0.55);
+  box-shadow: var(--ring);
+}
+
+select{background: var(--bg);}
+option {color: var(--primary); background-color: var(--bg-2);}
+
+.form-error { color: var(--danger); font-weight: 600; }
+
+/* Tree */
+.tree {
+  background: linear-gradient(180deg, rgba(14,22,38,0.9), rgba(14,22,38,0.5));
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: 12px;
+  max-height: 320px;
+  overflow: auto;
+}
+#file-tree ul { list-style: none; padding-left: 1rem; margin: 6px 0; }
+#file-tree label { font-weight: 500; }
+
+/* Divider */
+.divider {
+  height: 1px; width: 100%;
+  background: linear-gradient(90deg, transparent, rgba(148,163,184,0.2), transparent);
+  margin: 6px 0;
+}
+
+/* Buttons */
+.btn {
+  --inset: inset 0 0 0 1px rgba(255,255,255,0.06);
+  display: inline-flex; align-items: center; justify-content: center;
+  gap: 10px;
+  border: none;
+  border-radius: 12px;
+  padding: 12px 16px;
+  font-weight: 700;
+  cursor: pointer;
+  background: linear-gradient(180deg, #0ea5b7, #0891a6);
+  color: white;
+  box-shadow: var(--inset), 0 8px 24px rgba(6, 182, 212, 0.25);
+  transition: transform .08s ease, box-shadow .2s ease, filter .2s ease;
+}
+.btn:hover { transform: translateY(-1px); filter: brightness(1.05); }
+.btn:active { transform: translateY(0); filter: brightness(.98); }
+.btn:disabled { opacity: .6; cursor: not-allowed; filter: grayscale(.2); }
+.btn-primary { background: linear-gradient(180deg, var(--primary), var(--primary-2)); }
+.btn-inner { display: inline-flex; align-items: center; gap: 10px; }
+.icon { opacity: .9; }
+
+/* Button glow + ripple */
+.btn-glow { position: relative; overflow: hidden; }
+.btn-glow::after {
+  content: ""; position: absolute; inset: -2px;
+  background: radial-gradient(120px 120px at var(--x,50%) var(--y,50%), rgba(255,255,255,0.18), transparent 40%);
+  transition: opacity .2s ease;
+  opacity: 0; pointer-events: none;
+}
+.btn-glow:hover::after { opacity: 1; }
+.ripple {
+  position: absolute; border-radius: 50%; transform: translate(-50%, -50%);
+  background: rgba(255,255,255,0.35);
+  animation: ripple .6s ease-out forwards;
+  pointer-events: none;
+}
+@keyframes ripple {
+  from { width: 0; height: 0; opacity: .45; }
+  to { width: 360px; height: 360px; opacity: 0; }
+}
+
+/* Loader dot */
+.loader {
+  width: 0.85em; height: 0.85em; border-radius: 50%;
+  background: currentColor; opacity: 0; transform: scale(.6);
+  box-shadow: 16px 0 0 currentColor, -16px 0 0 currentColor;
+  filter: drop-shadow(0 0 8px rgba(34,211,238,0.5));
+}
+button[disabled] .loader { opacity: .9; animation: pulseDots 1s infinite ease-in-out; }
+@keyframes pulseDots {
+  0%, 100% { box-shadow: 16px 0 0 currentColor, -16px 0 0 currentColor; }
+  50% { box-shadow: 0 0 0 currentColor, 0 0 0 currentColor; }
+}
+
+/* Actions */
+.form-actions { display: flex; justify-content: center; margin-top: 8px; }
+
+/* Progress Layout */
+.section-title { margin: 0 0 10px; }
+.section-title.success { color: var(--success); }
+
+.progress-layout {
+  display: grid; gap: 16px;
+}
+@media (min-width: 960px){
+  .progress-layout { grid-template-columns: 1.1fr .9fr; align-items: start; }
+}
+
+/* Timeline */
+.timeline {
+  list-style: none; margin: 0; padding: 0;
+  display: grid; gap: 12px;
+}
+.phase-item {
+  display: grid; grid-template-columns: 28px 1fr; gap: 12px;
+  background: linear-gradient(180deg, rgba(15,23,42,0.6), rgba(15,23,42,0.35));
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 12px;
+  transition: transform .2s ease, border-color .2s ease, background .3s ease, box-shadow .3s ease;
+  will-change: transform;
+}
+.phase-item:hover { transform: translateY(-2px); border-color: rgba(34,211,238,0.35); box-shadow: 0 8px 20px rgba(2,8,23,0.6); }
+.phase-title { font-weight: 700; }
+
+.status-icon {
+  position: relative; width: 24px; height: 24px; border-radius: 50%;
+  background: #334155; align-self: start;
+  box-shadow: inset 0 0 0 2px rgba(15,23,42,0.7);
+}
+.phase-item[data-status="pending"] .status-icon { background: #475569; opacity: .8; }
+.phase-item[data-status="in-progress"] .status-icon {
+  background: linear-gradient(180deg, #60a5fa, #3b82f6);
+  animation: spin 1.2s linear infinite;
+  box-shadow: 0 0 0 6px rgba(59,130,246,0.15);
+}
+.phase-item[data-status="success"] .status-icon {
+  background: linear-gradient(180deg, #34d399, #22c55e);
+  box-shadow: 0 0 0 6px rgba(34,197,94,0.12);
+}
+.phase-item[data-status="error"] .status-icon {
+  background: linear-gradient(180deg, #f97373, #ef4444);
+  box-shadow: 0 0 0 6px rgba(239,68,68,0.15);
+}
+
+.phase-item[data-status="success"] .status-icon::after,
+.phase-item[data-status="error"] .status-icon::after {
+  position: absolute; content: "";
+  inset: 5px; border-radius: 50%; background: rgba(0,0,0,0.2);
+  mask: center / contain no-repeat;
+}
+.phase-item[data-status="success"] .status-icon::after {
+  mask-image: radial-gradient(circle at 50% 58%, transparent 56%, black 56.5%),
+              linear-gradient(transparent 45%, black 45% 55%, transparent 55%);
+}
+.phase-item[data-status="error"] .status-icon::after {
+  mask-image: linear-gradient(transparent 45%, black 45% 55%, transparent 55%),
+              linear-gradient(90deg, transparent 45%, black 45% 55%, transparent 55%);
+}
+
+@keyframes spin { to { transform: rotate(360deg); } }
+
+.subtask-list { list-style: none; padding-left: 0; margin: 8px 0 0; font-size: 14px; color: var(--muted); }
+.subtask-list li { margin: 4px 0; opacity: .8; transition: opacity .2s ease, color .2s ease, text-decoration-color .2s ease; }
+.subtask-list li[data-status="in-progress"] { opacity: 1; color: #cbd5e1; }
+.subtask-list li[data-status="success"] { opacity: 1; color: #93a3b3; text-decoration: line-through; }
+.subtask-list li[data-status="error"] { opacity: 1; color: var(--danger); font-weight: 600; }
+
+/* Terminal */
+.terminal {
+  background: #0b1020;
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  overflow: hidden;
+  box-shadow: inset 0 0 0 1px rgba(255,255,255,0.03);
+}
+.terminal-head {
+  display: flex; align-items: center; gap: 8px;
+  padding: 8px 10px; background: rgba(255,255,255,0.03);
+  border-bottom: 1px solid var(--border);
+}
+.terminal-head h4 { margin: 0 0 0 auto; color: var(--muted); font-weight: 600; }
+.terminal .dot { width: 10px; height: 10px; border-radius: 50%; display: inline-block; }
+.terminal .dot.red { background: #ef4444; }
+.terminal .dot.yellow { background: #f59e0b; }
+.terminal .dot.green { background: #22c55e; }
+
+.terminal-body {
+  margin: 0; padding: 14px; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
+  font-size: 13px; color: #cbd5e1; white-space: pre-wrap; word-wrap: break-word;
+  max-height: 420px; overflow: auto; line-height: 1.45;
+  background-image:
+    linear-gradient(rgba(255,255,255,0.025) 50%, transparent 50%);
+  background-size: 100% 22px;
+}
+
+/* Result */
+.result-card {
+  background: linear-gradient(180deg, rgba(16,185,129,0.1), rgba(16,185,129,0.06));
+  border: 1px solid rgba(16,185,129,0.3);
+  border-radius: 12px;
+  padding: 14px;
+}
+.button-link {
+  display: inline-flex; align-items: center; gap: 8px;
+  text-decoration: none; color: white;
+  margin-top: 10px;
+  background: linear-gradient(180deg, var(--primary), var(--primary-2));
+  padding: 10px 14px; border-radius: 10px; font-weight: 700;
+  box-shadow: 0 8px 24px rgba(6, 182, 212, 0.25);
+}
+
+/* Utility */
+.hidden { display: none !important; }
+
+/* Accessibility: reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  * { animation-duration: .01ms !important; animation-iteration-count: 1 !important; transition-duration: .01ms !important; scroll-behavior: auto !important; }
+}