"""
FastAPI Main Application
========================

Main entry point for the Autonomous Coding UI server.
Provides REST API, WebSocket, and static file serving.
"""

import shutil
from contextlib import asynccontextmanager
from pathlib import Path

from fastapi import FastAPI, HTTPException, Request, WebSocket
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import FileResponse
from fastapi.staticfiles import StaticFiles

from .routers import (
    agent_router,
    assistant_chat_router,
    features_router,
    filesystem_router,
    projects_router,
    spec_creation_router,
)
from .schemas import SetupStatus
from .services.assistant_chat_session import cleanup_all_sessions as cleanup_assistant_sessions
from .services.process_manager import cleanup_all_managers
from .websocket import project_websocket

# Paths
ROOT_DIR = Path(__file__).parent.parent
UI_DIST_DIR = ROOT_DIR / "ui" / "dist"

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Lifespan context manager for startup and shutdown."""
    # Startup
    yield
    # Shutdown - cleanup all running agents and assistant sessions
    await cleanup_all_managers()
    await cleanup_assistant_sessions()

# Create FastAPI app
app = FastAPI(
    title="Autonomous Coding UI",
    description="Web UI for the Autonomous Coding Agent",
    version="1.0.0",
    lifespan=lifespan,
)

# CORS - allow only localhost origins for security
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:5173",      # Vite dev server
        "http://127.0.0.1:5173",
        "http://localhost:8888",      # Production
        "http://127.0.0.1:8888",
    ],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# ============================================================================
# Security Middleware
# ============================================================================

@app.middleware("http")
async def require_localhost(request: Request, call_next):
    """Only allow requests from localhost."""
    client_host = request.client.host if request.client else None

    # Allow localhost connections
    if client_host not in ("127.0.0.1", "::1", "localhost", None):
        raise HTTPException(status_code=403, detail="Localhost access only")

    return await call_next(request)

# ============================================================================
# Include Routers
# ============================================================================

app.include_router(projects_router)
app.include_router(features_router)
app.include_router(agent_router)
app.include_router(spec_creation_router)
app.include_router(filesystem_router)
app.include_router(assistant_chat_router)

# ============================================================================
# WebSocket Endpoint
# ============================================================================

@app.websocket("/ws/projects/{project_name}")
async def websocket_endpoint(websocket: WebSocket, project_name: str):
    """WebSocket endpoint for real-time project updates."""
    await project_websocket(websocket, project_name)

# ============================================================================
# Setup & Health Endpoints
# ============================================================================

@app.get("/api/health")
async def health_check():
    """Health check endpoint."""
    return {"status": "healthy"}

@app.get("/api/setup/status", response_model=SetupStatus)
async def setup_status():
    """Check system setup status."""
    # Check for Claude CLI
    claude_cli = shutil.which("claude") is not None

    # Check for credentials file
    credentials_path = Path.home() / ".claude" / ".credentials.json"
    credentials = credentials_path.exists()

    # Check for Node.js and npm
    node = shutil.which("node") is not None
    npm = shutil.which("npm") is not None

    return SetupStatus(
        claude_cli=claude_cli,
        credentials=credentials,
        node=node,
        npm=npm,
    )

# ============================================================================
# Static File Serving (Production)
# ============================================================================

# Serve React build files if they exist
if UI_DIST_DIR.exists():
    # Mount static assets
    app.mount("/assets", StaticFiles(directory=UI_DIST_DIR / "assets"), name="assets")

    @app.get("/")
    async def serve_index():
        """Serve the React app index.html."""


#!/usr/bin/env python3
"""
Simple CLI launcher for the Autonomous Coding Agent.
Provides an interactive menu to create new projects or continue existing ones.

Supports two paths for new projects:
1. Claude path: Use /create-spec to generate spec interactively
2. Manual path: Edit template files directly, then continue
"""

import os
import subprocess
import sys
from pathlib import Path

from prompts import (
    get_project_prompts_dir,
    has_project_prompts,
    scaffold_project_prompts,
)
from registry import (
    get_project_path,
    list_registered_projects,
    register_project,
)

def check_spec_exists(project_dir: Path) -> bool:
    """
    Check if valid spec files exist for a project.

    Checks in order:
    1. Project prompts directory: {project_dir}/prompts/app_spec.txt
    2. Project root (legacy): {project_dir}/app_spec.txt
    """
    # Check project prompts directory first
    project_prompts = get_project_prompts_dir(project_dir)
    spec_file = project_prompts / "app_spec.txt"
    if spec_file.exists():
        try:
            content = spec_file.read_text(encoding="utf-8")
            return "<project_specification>" in content
        except (OSError, PermissionError):
            return False

    # Check legacy location in project root
    legacy_spec = project_dir / "app_spec.txt"
    if legacy_spec.exists():
        try:
            content = legacy_spec.read_text(encoding="utf-8")
            return "<project_specification>" in content
        except (OSError, PermissionError):
            return False

    return False

def get_existing_projects() -> list[tuple[str, Path]]:
    """Get list of existing projects from registry.

    Returns:
        List of (name, path) tuples for registered projects that still exist.
    """
    registry = list_registered_projects()
    projects = []

    for name, info in registry.items():
        path = Path(info["path"])
        if path.exists():
            projects.append((name, path))

    return sorted(projects, key=lambda x: x[0])

def display_menu(projects: list[tuple[str, Path]]) -> None:
    """Display the main menu."""
    print("\n" + "=" * 50)
    print("  Autonomous Coding Agent Launcher")
    print("=" * 50)
    print("\n[1] Create new project")

    if projects:
        print("[2] Continue existing project")

    print("[q] Quit")
    print()

def display_projects(projects: list[tuple[str, Path]]) -> None:
    """Display list of existing projects."""
    print("\n" + "-" * 40)
    print("  Existing Projects")
    print("-" * 40)

    for i, (name, path) in enumerate(projects, 1):
        print(f"  [{i}] {name}")
        print(f"      {path}")

    print("\n  [b] Back to main menu")
    print()

def get_project_choice(projects: list[tuple[str, Path]]) -> tuple[str, Path] | None:
    """Get user's project selection.

    Returns:
        Tuple of (name, path) for the selected project, or None if cancelled.
    """
    while True:
        choice = input("Select project number: ").strip().lower()

        if choice == 'b':
            return None

        try:
            idx = int(choice) - 1
            if 0 <= idx < len(projects):
                return projects[idx]
            print(f"Please enter a number between 1 and {len(projects)}")
        except ValueError:
            print("Invalid input. Enter a number or 'b' to go back.")

def get_new_project_info() -> tuple[str, Path] | None:
    """Get name and path for new project.

    Returns:
        Tuple of (name, path) for the new project, or None if cancelled.
    """
    print("\n" + "-" * 40)
    print("  Create New Project")
    print("-" * 40)
    print("\nEnter project name (e.g., my-awesome-app)")
    print("Leave empty to cancel.\n")

    name = input("Project name: ").strip()

    if not name:
        return None

    # Basic validation - OS-aware invalid characters
    # Windows has more restrictions than Unix
    if sys.platform == "win32":
        invalid_chars = '<>:"/\\|?*'
    else:
        # Unix only restricts / and null
        invalid_chars = '/'

    for char in invalid_chars:
        if char in name:
            print(f"Invalid character '{char}' in project name")
            return None

    # Check if name already registered
    existing = get_project_path(name)
    if existing:
        print(f"Project '{name}' already exists at {existing}")
        return None

    # Get project path
    print("\nEnter the full path for the project directory")
    print("(e.g., C:/Projects/my-app or /home/user/projects/my-app)")
    print("Leave empty to cancel.\n")

    path_str = input("Project path: ").strip()
    if not path_str:
        return None

    project_path = Path(path_str).resolve()

    return name, project_path

def ensure_project_scaffolded(project_name: str, project_dir: Path) -> Path:
    """
    Ensure project directory exists with prompt templates and is registered.

    Creates the project directory, copies template files, and registers in registry.

    Args:
        project_name: Name of the project
        project_dir: Absolute path to the project directory

    Returns:
        The project directory path
    """
    # Create project directory if it doesn't exist
    project_dir.mkdir(parents=True, exist_ok=True)

    # Scaffold prompts (copies templates if they don't exist)
    print(f"\nSetting up project: {project_name}")
    print(f"Location: {project_dir}")
    scaffold_project_prompts(project_dir)

    # Register in registry
    register_project(project_name, project_dir)

    return project_dir


Perfect! Now let me check the prompt templates to understand what the agent sees:


total 64
drwxr-xr-x 1 AzureAD+MikeSwanson 4096     0 Jan  8 13:53 ./
drwxr-xr-x 1 AzureAD+MikeSwanson 4096     0 Jan  8 13:53 ../
-rw-r--r-- 1 AzureAD+MikeSwanson 4096  9035 Jan  8 08:02 app_spec.template.txt
-rw-r--r-- 1 AzureAD+MikeSwanson 4096 14174 Jan  8 08:02 coding_prompt.template.md
-rw-r--r-- 1 AzureAD+MikeSwanson 4096  7910 Jan  8 08:02 coding_prompt_yolo.template.md
-rw-r--r-- 1 AzureAD+MikeSwanson 4096 19456 Jan  8 08:02 initializer_prompt.template.md


## YOUR ROLE - INITIALIZER AGENT (Session 1 of Many)

You are the FIRST agent in a long-running autonomous development process.
Your job is to set up the foundation for all future coding agents.

### FIRST: Read the Project Specification

Start by reading `app_spec.txt` in your working directory. This file contains
the complete specification for what you need to build. Read it carefully
before proceeding.

---

## REQUIRED FEATURE COUNT

**CRITICAL:** You must create exactly **[FEATURE_COUNT]** features using the `feature_create_bulk` tool.

This number was determined during spec creation and must be followed precisely. Do not create more or fewer features than specified.

---

### CRITICAL FIRST TASK: Create Features

Based on `app_spec.txt`, create features using the feature_create_bulk tool. The features are stored in a SQLite database,
which is the single source of truth for what needs to be built.

**Creating Features:**

Use the feature_create_bulk tool to add all features at once:

```
Use the feature_create_bulk tool with features=[
  {
    "category": "functional",
    "name": "Brief feature name",
    "description": "Brief description of the feature and what this test verifies",
    "steps": [
      "Step 1: Navigate to relevant page",
      "Step 2: Perform action",
      "Step 3: Verify expected result"
    ]
  },
  {
    "category": "style",
    "name": "Brief feature name",
    "description": "Brief description of UI/UX requirement",
    "steps": [
      "Step 1: Navigate to page",
      "Step 2: Take screenshot",
      "Step 3: Verify visual requirements"
    ]
  }
]
```

**Notes:**
- IDs and priorities are assigned automatically based on order
- All features start with `passes: false` by default
- You can create features in batches if there are many (e.g., 50 at a time)

**Requirements for features:**

- Feature count must match the `feature_count` specified in app_spec.txt
- Reference tiers for other projects:
  - **Simple apps**: ~150 tests
  - **Medium apps**: ~250 tests
  - **Complex apps**: ~400+ tests
- Both "functional" and "style" categories
- Mix of narrow tests (2-5 steps) and comprehensive tests (10+ steps)
- At least 25 tests MUST have 10+ steps each (more for complex apps)
- Order features by priority: fundamental features first (the API assigns priority based on order)
- All features start with `passes: false` automatically
- Cover every feature in the spec exhaustively
- **MUST include tests from ALL 20 mandatory categories below**

---

## MANDATORY TEST CATEGORIES

The feature_list.json **MUST** include tests from ALL of these categories. The minimum counts scale by complexity tier.

### Category Distribution by Complexity Tier

| Category                         | Simple  | Medium  | Complex  |
| -------------------------------- | ------- | ------- | -------- |
| A. Security & Access Control     | 5       | 20      | 40       |
| B. Navigation Integrity          | 15      | 25      | 40       |
| C. Real Data Verification        | 20      | 30      | 50       |
| D. Workflow Completeness         | 10      | 20      | 40       |
| E. Error Handling                | 10      | 15      | 25       |
| F. UI-Backend Integration        | 10      | 20      | 35       |
| G. State & Persistence           | 8       | 10      | 15       |
| H. URL & Direct Access           | 5       | 10      | 20       |
| I. Double-Action & Idempotency   | 5       | 8       | 15       |
| J. Data Cleanup & Cascade        | 5       | 10      | 20       |
| K. Default & Reset               | 5       | 8       | 12       |
| L. Search & Filter Edge Cases    | 8       | 12      | 20       |
| M. Form Validation               | 10      | 15      | 25       |
| N. Feedback & Notification       | 8       | 10      | 15       |
| O. Responsive & Layout           | 8       | 10      | 15       |
| P. Accessibility                 | 8       | 10      | 15       |
| Q. Temporal & Timezone           | 5       | 8       | 12       |
| R. Concurrency & Race Conditions | 5       | 8       | 15       |
| S. Export/Import                 | 5       | 6       | 10       |
| T. Performance                   | 5       | 5       | 10       |
| **TOTAL**                        | **150** | **250** | **400+** |

---

### A. Security & Access Control Tests

Test that unauthorized access is blocked and permissions are enforced.

**Required tests (examples):**

- Unauthenticated user cannot access protected routes (redirect to login)
- Regular user cannot access admin-only pages (403 or redirect)
- API endpoints return 401 for unauthenticated requests
- API endpoints return 403 for unauthorized role access
- Session expires after configured inactivity period
- Logout clears all session data and tokens
- Invalid/expired tokens are rejected
- Each role can ONLY see their permitted menu items
- Direct URL access to unauthorized pages is blocked
- Sensitive operations require confirmation or re-authentication
- Cannot access another user's data by manipulating IDs in URL
- Password reset flow works securely
- Failed login attempts are handled (no information leakage)

### B. Navigation Integrity Tests

Test that every button, link, and menu item goes to the correct place.

**Required tests (examples):**

- Every button in sidebar navigates to correct page
- Every menu item links to existing route
- All CRUD action buttons (Edit, Delete, View) go to correct URLs with correct IDs
- Back button works correctly after each navigation
- Deep linking works (direct URL access to any page with auth)
- Breadcrumbs reflect actual navigation path
- 404 page shown for non-existent routes (not crash)
- After login, user redirected to intended destination (or dashboard)
- After logout, user redirected to login page
- Pagination links work and preserve current filters
- Tab navigation within pages works correctly
- Modal close buttons return to previous state
- Cancel buttons on forms return to previous page

### C. Real Data Verification Tests

Test that data is real (not mocked) and persists correctly.

**Required tests (examples):**

- Create a record via UI with unique content → verify it appears in list
- Create a record → refresh page → record still exists
- Create a record → log out → log in → record still exists
- Edit a record → verify changes persist after refresh
- Delete a record → verify it's gone from list AND database
- Delete a record → verify it's gone from related dropdowns
- Filter/search → results match actual data created in test
- Dashboard statistics reflect real record counts (create 3 items, count shows 3)
- Reports show real aggregated data
- Export functionality exports actual data you created
- Related records update when parent changes
- Timestamps are real and accurate (created_at, updated_at)
- Data created by User A is not visible to User B (unless shared)
- Empty state shows correctly when no data exists

### D. Workflow Completeness Tests

Test that every workflow can be completed end-to-end through the UI.

**Required tests (examples):**

- Every entity has working Create operation via UI form
- Every entity has working Read/View operation (detail page loads)
- Every entity has working Update operation (edit form saves)
- Every entity has working Delete operation (with confirmation dialog)
- Every status/state has a UI mechanism to transition to next state
- Multi-step processes (wizards) can be completed end-to-end
- Bulk operations (select all, delete selected) work
- Cancel/Undo operations work where applicable
- Required fields prevent submission when empty
- Form validation shows errors before submission
- Successful submission shows success feedback
- Backend workflow (e.g., user→customer conversion) has UI trigger

### E. Error Handling Tests

Test graceful handling of errors and edge cases.

**Required tests (examples):**

- Network failure shows user-friendly error message, not crash
- Invalid form input shows field-level errors
- API errors display meaningful messages to user
- 404 responses handled gracefully (show not found page)
- 500 responses don't expose stack traces or technical details


## YOUR ROLE - CODING AGENT

You are continuing work on a long-running autonomous development task.
This is a FRESH context window - you have no memory of previous sessions.

### STEP 1: GET YOUR BEARINGS (MANDATORY)

Start by orienting yourself:

```bash
# 1. See your working directory
pwd

# 2. List files to understand project structure
ls -la

# 3. Read the project specification to understand what you're building
cat app_spec.txt

# 4. Read progress notes from previous sessions
cat claude-progress.txt

# 5. Check recent git history
git log --oneline -20
```

Then use MCP tools to check feature status:

```
# 6. Get progress statistics (passing/total counts)
Use the feature_get_stats tool

# 7. Get the next feature to work on
Use the feature_get_next tool
```

Understanding the `app_spec.txt` is critical - it contains the full requirements
for the application you're building.

### STEP 2: START SERVERS (IF NOT RUNNING)

If `init.sh` exists, run it:

```bash
chmod +x init.sh
./init.sh
```

Otherwise, start servers manually and document the process.

### STEP 3: VERIFICATION TEST (CRITICAL!)

**MANDATORY BEFORE NEW WORK:**

The previous session may have introduced bugs. Before implementing anything
new, you MUST run verification tests.

Run 1-2 of the features marked as passing that are most core to the app's functionality to verify they still work.

To get passing features for regression testing:

```
Use the feature_get_for_regression tool (returns up to 3 random passing features)
```

For example, if this were a chat app, you should perform a test that logs into the app, sends a message, and gets a response.

**If you find ANY issues (functional or visual):**

- Mark that feature as "passes": false immediately
- Add issues to a list
- Fix all issues BEFORE moving to new features
- This includes UI bugs like:
  - White-on-white text or poor contrast
  - Random characters displayed
  - Incorrect timestamps
  - Layout issues or overflow
  - Buttons too close together
  - Missing hover states
  - Console errors

### STEP 4: CHOOSE ONE FEATURE TO IMPLEMENT

#### TEST-DRIVEN DEVELOPMENT MINDSET (CRITICAL)

Features are **test cases** that drive development. This is test-driven development:

- **If you can't test a feature because functionality doesn't exist → BUILD IT**
- You are responsible for implementing ALL required functionality
- Never assume another process will build it later
- "Missing functionality" is NOT a blocker - it's your job to create it

**Example:** Feature says "User can filter flashcards by difficulty level"
- WRONG: "Flashcard page doesn't exist yet" → skip feature
- RIGHT: "Flashcard page doesn't exist yet" → build flashcard page → implement filter → test feature

Get the next feature to implement:

```
# Get the highest-priority pending feature
Use the feature_get_next tool
```

Once you've retrieved the feature, **immediately mark it as in-progress**:

```
# Mark feature as in-progress to prevent other sessions from working on it
Use the feature_mark_in_progress tool with feature_id=42
```

Focus on completing one feature perfectly and completing its testing steps in this session before moving on to other features.
It's ok if you only complete one feature in this session, as there will be more sessions later that continue to make progress.

#### When to Skip a Feature (EXTREMELY RARE)

**Skipping should almost NEVER happen.** Only skip for truly external blockers you cannot control:

- **External API not configured**: Third-party service credentials missing (e.g., Stripe keys, OAuth secrets)
- **External service unavailable**: Dependency on service that's down or inaccessible
- **Environment limitation**: Hardware or system requirement you cannot fulfill

**NEVER skip because:**

| Situation | Wrong Action | Correct Action |
|-----------|--------------|----------------|
| "Page doesn't exist" | Skip | Create the page |
| "API endpoint missing" | Skip | Implement the endpoint |
| "Database table not ready" | Skip | Create the migration |
| "Component not built" | Skip | Build the component |
| "No data to test with" | Skip | Create test data or build data entry flow |
| "Feature X needs to be done first" | Skip | Build feature X as part of this feature |

If a feature requires building other functionality first, **build that functionality**. You are the coding agent - your job is to make the feature work, not to defer it.

If you must skip (truly external blocker only):

```
Use the feature_skip tool with feature_id={id}
```

Document the SPECIFIC external blocker in `claude-progress.txt`. "Functionality not built" is NEVER a valid reason.

### STEP 5: IMPLEMENT THE FEATURE

Implement the chosen feature thoroughly:

1. Write the code (frontend and/or backend as needed)
2. Test manually using browser automation (see Step 6)
3. Fix any issues discovered
4. Verify the feature works end-to-end

### STEP 6: VERIFY WITH BROWSER AUTOMATION

**CRITICAL:** You MUST verify features through the actual UI.

Use browser automation tools:

- Navigate to the app in a real browser
- Interact like a human user (click, type, scroll)
- Take screenshots at each step
- Verify both functionality AND visual appearance

**DO:**

- Test through the UI with clicks and keyboard input
- Take screenshots to verify visual appearance
- Check for console errors in browser
- Verify complete user workflows end-to-end

**DON'T:**

- Only test with curl commands (backend testing alone is insufficient)
- Use JavaScript evaluation to bypass UI (no shortcuts)
- Skip visual verification
- Mark tests passing without thorough verification

### STEP 6.5: MANDATORY VERIFICATION CHECKLIST (BEFORE MARKING ANY TEST PASSING)

**You MUST complete ALL of these checks before marking any feature as "passes": true**

#### Security Verification (for protected features)

- [ ] Feature respects user role permissions
- [ ] Unauthenticated access is blocked (redirects to login)
- [ ] API endpoint checks authorization (returns 401/403 appropriately)
- [ ] Cannot access other users' data by manipulating URLs

#### Real Data Verification (CRITICAL - NO MOCK DATA)

- [ ] Created unique test data via UI (e.g., "TEST_12345_VERIFY_ME")
- [ ] Verified the EXACT data I created appears in UI
- [ ] Refreshed page - data persists (proves database storage)
- [ ] Deleted the test data - verified it's gone everywhere
- [ ] NO unexplained data appeared (would indicate mock data)
- [ ] Dashboard/counts reflect real numbers after my changes

#### Navigation Verification

- [ ] All buttons on this page link to existing routes
- [ ] No 404 errors when clicking any interactive element
- [ ] Back button returns to correct previous page
- [ ] Related links (edit, view, delete) have correct IDs in URLs

#### Integration Verification

- [ ] Console shows ZERO JavaScript errors
- [ ] Network tab shows successful API calls (no 500s)
- [ ] Data returned from API matches what UI displays
- [ ] Loading states appeared during API calls
- [ ] Error states handle failures gracefully

### STEP 6.6: MOCK DATA DETECTION SWEEP

**Run this sweep AFTER EVERY FEATURE before marking it as passing:**

#### 1. Code Pattern Search

Search the codebase for forbidden patterns:

```bash
# Search for mock data patterns
grep -r "mockData\|fakeData\|sampleData\|dummyData\|testData" --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx"
grep -r "// TODO\|// FIXME\|// STUB\|// MOCK" --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx"
grep -r "hardcoded\|placeholder" --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx"
```

**If ANY matches found related to your feature - FIX THEM before proceeding.**

#### 2. Runtime Verification

For ANY data displayed in UI:

1. Create NEW data with UNIQUE content (e.g., "TEST_12345_DELETE_ME")
2. Verify that EXACT content appears in the UI
3. Delete the record
4. Verify it's GONE from the UI
5. **If you see data that wasn't created during testing - IT'S MOCK DATA. Fix it.**

#### 3. Database Verification

Check that:

- Database tables contain only data you created during tests
- Counts/statistics match actual database record counts
- No seed data is masquerading as user data

#### 4. API Response Verification

For API endpoints used by this feature:


Excellent! Now let me create a comprehensive summary. Let me check one more thing about the data flow:


<!--
  Project Specification Template
  ==============================

  This is a placeholder template. Replace with your actual project specification.

  You can either:
  1. Use the /create-spec command to generate this interactively with Claude
  2. Manually edit this file following the structure below

  See existing projects in generations/ for examples of complete specifications.
-->

<project_specification>
  <project_name>YOUR_PROJECT_NAME</project_name>

  <overview>
    Describe your project in 2-3 sentences. What are you building? What problem
    does it solve? Who is it for? Include key features and design goals.
  </overview>

  <technology_stack>
    <frontend>
      <framework>React with Vite</framework>
      <styling>Tailwind CSS</styling>
      <state_management>React hooks and context</state_management>
      <routing>React Router for navigation</routing>
      <port>3000</port>
    </frontend>
    <backend>
      <runtime>Node.js with Express</runtime>
      <database>SQLite with better-sqlite3</database>
      <port>3001</port>
    </backend>
    <communication>
      <api>RESTful endpoints</api>
    </communication>
  </technology_stack>

  <prerequisites>
    <environment_setup>
      - Node.js 18+ installed
      - npm or pnpm package manager
      - Any API keys or external services needed
    </environment_setup>
  </prerequisites>

  <core_features>
    <!--
      List features grouped by category. Each feature should be:
      - Specific and testable
      - Independent where possible
      - Written as a capability ("User can...", "System displays...")
    -->

    <authentication>
      - User registration with email/password
      - User login with session management
      - User logout
      - Password reset flow
      - Profile management
    </authentication>

    <main_functionality>
      <!-- Replace with your app's primary features -->
      - Create new items
      - View list of items with pagination
      - Edit existing items
      - Delete items with confirmation
      - Search and filter items
    </main_functionality>

    <user_interface>
      - Responsive layout (mobile, tablet, desktop)
      - Dark/light theme toggle
      - Loading states and skeletons
      - Error handling with user feedback
      - Toast notifications for actions
    </user_interface>

    <data_management>
      - Data validation on forms
      - Auto-save drafts
      - Export data functionality
      - Import data functionality
    </data_management>

    <!-- Add more feature categories as needed -->
  </core_features>

  <database_schema>
    <tables>
      <users>
        - id (PRIMARY KEY)
        - email (UNIQUE, NOT NULL)
        - password_hash (NOT NULL)
        - name
        - avatar_url
        - preferences (JSON)
        - created_at, updated_at


Perfect! Now I have a comprehensive understanding. Let me create a detailed report:


Bash

find "/c/Users/MikeSwanson/claude-projects/Autocode-remix/Autocode-fork/autocoder-master" -type f -name "*.py" | wc -l


Now let me provide you with a comprehensive analysis of the Autocode-remix architecture:

## AUTOCODE-REMIX CODEBASE ARCHITECTURE ANALYSIS

Based on thorough exploration of `/c/Users/MikeSwanson/claude-projects/Autocode-remix/Autocode-fork/autocoder-master`, here's the complete architectural understanding:

### 1. OVERALL ARCHITECTURE - END-TO-END FLOW

The system implements a **two-agent autonomous development loop** that builds complete applications over multiple sessions:

```
User Specification (app_spec.txt)
         ↓
    Session 1: INITIALIZER AGENT
    - Reads spec, generates 150-400+ test cases
    - Creates features in SQLite database
    - Sets up git repo
         ↓
    Session 2+: CODING AGENT(S) (repeating loop)
    - Retrieves next feature from database
    - Implements functionality to pass the feature test
    - Runs browser verification (Playwright automation)
    - Marks feature as passing, commits to git
    - Auto-continues every 3 seconds until completion
```

**Key insight:** The system uses **test-driven development** where features are test cases that drive development. Each feature defines explicit steps that must be verified via UI automation.

---

### 2. CLAUDE AGENT SDK ORCHESTRATION

The codebase uses **Claude Agent SDK** (from `claude_agent_sdk` import) with a sophisticated multi-layer integration:

#### Entry Point: `autonomous_agent_demo.py`
- Command-line harness for agent execution
- Handles project directory resolution (absolute paths or registry lookup)
- Supports YOLO mode (rapid prototyping without browser testing)
- Implements max-iterations control for testing

#### Core Agent Loop: `agent.py`
The main orchestration logic that:

1. **Receives asynchronous message stream** from Claude SDK client:
   ```python
   async with client:
       await client.query(message)  # Send prompt
       async for msg in client.receive_response():  # Stream response
   ```

2. **Processes three message types:**
   - `AssistantMessage` - Claude's text output and tool use blocks
   - `UserMessage` - Tool results from MCP servers
   - `ToolResultBlock` - Success/error responses from tools

3. **Displays real-time output:**
   - Shows text responses immediately with `print()`
   - Displays tool names as they're called: `[Tool: feature_get_next]`
   - Shows brief status after tool execution: `[Done]` or `[BLOCKED]`

4. **Auto-continues with 3-second delays** between sessions to allow human pause/intervention

#### Client Configuration: `client.py`

Creates `ClaudeSDKClient` with sophisticated settings:

**Security Configuration:**
```python
ClaudeAgentOptions(
    system_prompt="You are an expert full-stack developer...",
    sandbox={"enabled": True},  # OS-level bash isolation
    permissions={
        "allow": ["Read(./**)", "Write(./**)", "Bash(*)", ...],
        "defaultMode": "acceptEdits"  # Auto-approve safe edits
    },
    hooks={"PreToolUse": [bash_security_hook]},  # Command validation
)
```

**MCP Server Configuration:**
- Always includes `features` MCP server for database access
- Optionally includes `playwright` MCP for browser automation (skipped in YOLO mode)
- MCP servers spawn as separate processes with environment variables

**Tool Allowlists:**
```python
FEATURE_MCP_TOOLS = [
    "feature_get_stats",      # Get progress (passing/total)
    "feature_get_next",       # Get next feature to work on
    "feature_get_for_regression",  # Get random passing features
    "feature_mark_passing",   # Mark feature complete
    "feature_skip",           # Move to end of queue
    "feature_create_bulk",    # Bulk create (initializer only)
]

PLAYWRIGHT_TOOLS = [
    # Browser navigation, screenshots, element interaction
    "browser_navigate", "browser_click", "browser_type", ...
]

BUILTIN_TOOLS = ["Read", "Write", "Edit", "Glob", "Grep", "Bash", "WebFetch", "WebSearch"]
```

---

### 3. THE "SANDBOX" - AGENT CONSTRAINT MODEL

Multi-layered defense-in-depth security:

#### Layer 1: OS-Level Sandbox
- Configured in `client.py` security settings: `sandbox: {"enabled": True}`
- Claude SDK handles bash command isolation at OS level
- Prevents filesystem escape attempts

#### Layer 2: Filesystem Restrictions
- Project directory (`./**`) is the operating boundary
- All Read/Write/Edit/Glob/Grep restricted to project files only
- `cwd=str(project_dir.resolve())` - working directory locked to project

#### Layer 3: Bash Command Allowlist (`security.py`)

Pre-tool-use hook validates ALL bash commands against `ALLOWED_COMMANDS`:

```python
ALLOWED_COMMANDS = {
    # File inspection
    "ls", "cat", "head", "tail", "wc", "grep",
    # File operations
    "cp", "mkdir", "chmod", "mv", "rm", "touch",
    # Node.js development
    "npm", "npx", "pnpm", "node",
    # Version control
    "git",
    # Process management
    "ps", "lsof", "sleep", "kill", "pkill",
    # Docker, curl, bash, sh
}
```

**Extra validation for sensitive commands:**
- `pkill` - Only allows dev process names (node, npm, vite)
- `chmod` - Only allows `+x` (execute permission)
- `init.sh` - Only allows `./init.sh` execution

**Validation mechanism:**
```python
async def bash_security_hook(input_data, tool_use_id=None, context=None):
    # Extract command names from command string
    commands = extract_commands(command)

    # Check each against allowlist
    for cmd in commands:
        if cmd not in ALLOWED_COMMANDS:
            return {"decision": "block", "reason": f"..."}
```

---

### 4. FEATURE/TASK BREAKDOWN AND EXECUTION

#### Feature Database Schema (`api/database.py`)

SQLite Feature table (persisted in `features.db`):

```python
class Feature(Base):
    __tablename__ = "features"

    id = Column(Integer, primary_key=True)
    priority = Column(Integer, nullable=False)  # Execution order
    category = Column(String)  # "functional", "style", "security", etc.
    name = Column(String)      # "User can log in"
    description = Column(Text) # Detailed requirement
    steps = Column(JSON)       # ["Step 1: ...", "Step 2: ...", ...]
    passes = Column(Boolean)   # Test passing status
    in_progress = Column(Boolean)  # Prevents race conditions
```

#### Feature Lifecycle

1. **Initializer Session:** Creates all features at once
   ```
   feature_create_bulk(features=[
     {
       "category": "functional",
       "name": "User login",
       "description": "...",
       "steps": ["Navigate to login", "Enter credentials", "Verify logged in"]
     },
     ...
   ])
   ```

2. **Coding Session:** Sequential implementation
   ```
   feature_get_next()  # Get highest-priority incomplete feature
   feature_mark_in_progress(feature_id=42)  # Lock it

   # ... implement and test ...

   feature_mark_passing(feature_id=42)  # Mark complete
   ```

3. **Skipping (Rare):** Move to end of queue
   ```
   feature_skip(feature_id=42)  # Sets priority to max+1
   ```

4. **Regression:** Random sampling of passing features
   ```
   feature_get_for_regression(limit=3)  # Get 3 random passing features
   ```

#### Feature Categories (20 Mandatory)

From `initializer_prompt.template.md`:

| Category | Examples |
|----------|----------|
| A. Security & Access Control | Role-based access, session expiration, token validation |
| B. Navigation Integrity | All buttons link correctly, proper redirect flow |
| C. Real Data Verification | Create unique data, verify persistence, refresh page |
| D. Workflow Completeness | CRUD operations, multi-step processes |
| E. Error Handling | Network failures, validation errors, API errors |
| F. UI-Backend Integration | API calls match UI display, loading states |
| ... (14 more categories) | ... |

**Feature count by complexity:**
- Simple apps: ~150 tests
- Medium apps: ~250 tests
- Complex apps: ~400+ tests

---

### 5. DATA FLOW: SPEC → CODE GENERATION

```
┌─────────────────────────────────────────────────────────────────┐
│ PROJECT CREATION                                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ User writes app spec.txt (XML format):                         │
│  <project_specification>                                        │
│    <project_name>My App</project_name>                         │
│    <overview>Build a task management system...</overview>      │
│    <technology_stack>React, Node.js, SQLite</tech>            │
│    <core_features>                                             │
│      <authentication>...</authentication>                       │
│      <main_functionality>...</main_functionality>              │
│    </core_features>                                            │
│    <database_schema>...</database_schema>                      │
│  </project_specification>                                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
         ↓
┌─────────────────────────────────────────────────────────────────┐
│ SESSION 1: INITIALIZER AGENT                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ Input: app_spec.txt + initializer_prompt.template.md          │
│                                                                 │
│ Prompt template instructs agent to:                            │
│  1. Read and understand app_spec.txt                           │
│  2. Generate 150-400+ features covering 20 test categories    │
│  3. Order by priority (fundamental features first)             │
│  4. Call feature_create_bulk() to populate SQLite database    │
│  5. Set up git repo and project structure                     │
│                                                                 │
│ Output:                                                         │
│  - features.db (SQLite with 150-400+ test cases)              │
│  - .git repository initialized                                 │
│  - Project structure scaffolded                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
         ↓
┌─────────────────────────────────────────────────────────────────┐
│ SESSION 2+: CODING AGENT (Repeating Loop)                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ Input: coding_prompt.template.md (or coding_prompt_yolo.md)  │
│                                                                 │
│ Agent workflow:                                                 │
│  1. Read app_spec.txt (understand requirements)                │
│  2. Read claude-progress.txt (understand previous sessions)    │
│  3. feature_get_stats() → Check progress                       │
│  4. feature_get_next() → Get highest-priority incomplete       │
│  5. feature_mark_in_progress(id) → Lock feature               │
│                                                                 │
│  6. REGRESSION TEST:                                            │
│     - feature_get_for_regression(3) → Get 3 random passing    │
│     - Run those tests via browser automation to verify still   │
│       working (catch regressions)                              │
│                                                                 │
│  7. IMPLEMENT FEATURE:                                          │
│     - Write frontend code (React components)                   │
│     - Write backend code (Express endpoints)                   │
│     - Create database migrations if needed                     │
│     - Add UI tests for visual verification                     │
│                                                                 │
│  8. BROWSER VERIFICATION (Playwright automation):              │
│     - Execute each step in feature.steps list                  │
│     - Navigate, click, type, take screenshots                  │
│     - Verify actual UI matches expected behavior               │
│     - Check for console errors                                 │
│     - Verify real data created in test persists                │
│                                                                 │
│  9. MARK PASSING:                                               │
│     - feature_mark_passing(id) → Mark complete                │
│     - git commit with feature details                          │
│     - Update claude-progress.txt                               │
│                                                                 │
│ Output: Passing feature + Git commit                            │
│                                                                 │
│ Auto-continues: 3-second delay, loop to step 3                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

### 6. KEY FILES AND THEIR PURPOSES

#### Core Orchestration
| File | Purpose |
|------|---------|
| `/c/Users/MikeSwanson/claude-projects/Autocode-remix/Autocode-fork/autocoder-master/autonomous_agent_demo.py` | CLI entry point; argument parsing, project resolution |
| `agent.py` | Main async agent loop; receives/processes SDK messages; calls prompts |
| `client.py` | Creates ClaudeSDKClient; configures security, MCP servers, permissions |
| `prompts.py` | Loads prompt templates; project-specific fallback chain |
| `progress.py` | Progress tracking; database queries; webhook notifications |
| `security.py` | Bash command allowlist; pre-tool-use hook validation |
| `registry.py` | Project registry (SQLite at ~/.autocoder/registry.db) |

#### Agent Tooling (MCP Servers)
| File | Purpose |
|------|---------|
| `mcp_server/feature_mcp.py` | MCP server for feature management; exposes tools like feature_get_next, feature_mark_passing |
| `api/database.py` | SQLAlchemy models; Feature table schema; database connection |
| `api/migration.py` | Legacy JSON to SQLite migration for backwards compatibility |

#### Web UI (FastAPI Backend)
| File | Purpose |
|------|---------|
| `server/main.py` | FastAPI app; CORS, middleware, route mounting, static file serving |
| `server/routers/projects.py` | Project CRUD with registry integration |
| `server/routers/features.py` | Feature CRUD via API |
| `server/routers/agent.py` | Agent control (start/stop/pause) |
| `server/routers/filesystem.py` | Filesystem browser API (security-restricted) |
| `server/websocket.py` | WebSocket handler for real-time updates to UI |
| `server/services/process_manager.py` | Manages agent subprocess lifecycle |

#### Prompt Templates
| File | Purpose |
|------|---------|
| `.claude/templates/initializer_prompt.template.md` | First session prompt; instructs agent to create features |
| `.claude/templates/coding_prompt.template.md` | Continuation session prompt; full test-driven development workflow |
| `.claude/templates/coding_prompt_yolo.template.md` | YOLO mode prompt; skips browser testing for speed |
| `.claude/templates/app_spec.template.txt` | Template for user's project specification (XML format) |

#### Project Initialization
| File | Purpose |
|------|---------|
| `start.py` | CLI launcher; project creation/selection menu |
| `start_ui.py` | Starts FastAPI server + launches React UI browser tab |
| `init.sh` / `init.bat` | Platform-specific entry points for setup |

---

### 7. AGENT CAPABILITIES & CONSTRAINTS

#### What Agents CAN Do
- Create/edit/delete files within project directory
- Run npm/node commands for development
- Execute git operations (commit, log, etc.)
- Query the feature database (via MCP)
- Control browser via Playwright (navigate, click, screenshot, etc.)
- Call Claude Code tools (Read, Write, Bash, WebFetch, etc.)
- Create test data in the application for verification

#### What Agents CANNOT Do
- Run arbitrary bash commands (only allowlisted ones)
- Access files outside project directory
- Kill production processes (only dev servers like node, npm)
- Install system packages (no apt-get, brew, yum, etc.)
- Access other users' data
- Modify system configuration
- Execute Python subprocess commands directly (only through Bash tool)

---

### 8. REAL-TIME UI UPDATES

WebSocket connection (`/ws/projects/{project_name}`) streams updates:

```python
# From subprocess stdout
"log": "Agent output line appears here..."

# From feature database
"progress": {"passing": 42, "total": 150, "percentage": 28}

# Agent process status
"agent_status": "running" | "paused" | "stopped" | "crashed"

# Feature changes
"feature_update": {"id": 42, "passes": true, "in_progress": false}
```

---

### 9. YOLO MODE (RAPID PROTOTYPING)

Skips expensive verification:

```bash
python autonomous_agent_demo.py --project-dir my-app --yolo
```

**Changes in YOLO mode:**
- No Playwright MCP server (no browser automation)
- Uses `coding_prompt_yolo.template.md` instead of `coding_prompt.template.md`
- Skips `feature_get_for_regression()` (regression testing)
- Features marked passing after lint/type-check succeeds
- Faster iteration for prototyping phase

**Still included:**
- Feature database tracking (feature_get_next, feature_mark_passing)
- Code linting and type-checking
- Git commits

---

### 10. CRITICAL INSIGHTS

1. **Test-Driven Development as Core Pattern:** Features ARE test cases. The agent must implement functionality to pass tests, not vice versa.

2. **Stateless Sessions:** Each session gets a fresh context window. All state is persisted in SQLite database and git history.

3. **Multi-Agent Architecture:** Initializer and Coding agents have different responsibilities. Initializer generates comprehensive test suite; Coding agents implement features iteratively.

4. **Real Data Verification:** Strict requirement to use actual UI, create unique test data, and verify persistence. No mock data allowed.

5. **Security-First Design:** Bash commands, filesystem access, and permissions all validated through pre-tool-use hooks and project-scoped settings.

6. **Project Registry System:** Cross-platform support using POSIX paths in SQLite registry at `~/.autocoder/registry.db`.

7. **Extensible MCP Architecture:** New tools can be added by creating new MCP servers; agents discover tools dynamically.

---

### FILE LOCATIONS (ABSOLUTE PATHS)

- **Main codebase:** `/c/Users/MikeSwanson/claude-projects/Autocode-remix/Autocode-fork/autocoder-master/`
- **Entry point:** `/c/Users/MikeSwanson/claude-projects/Autocode-remix/Autocode-fork/autocoder-master/autonomous_agent_demo.py`
- **Agent loop:** `/c/Users/MikeSwanson/claude-projects/Autocode-remix/Autocode-fork/autocoder-master/agent.py`
- **Security:** `/c/Users/MikeSwanson/claude-projects/Autocode-remix/Autocode-fork/autocoder-master/security.py`
- **MCP server:** `/c/Users/MikeSwanson/claude-projects/Autocode-remix/Autocode-fork/autocoder-master/mcp_server/feature_mcp.py`
- **Database models:** `/c/Users/MikeSwanson/claude-projects/Autocode-remix/Autocode-fork/autocoder-master/api/database.py`
- **Prompts:** `/c/Users/MikeSwanson/claude-projects/Autocode-remix/Autocode-fork/autocoder-master/.claude/templates/`

This architecture represents a sophisticated implementation of long-running autonomous development using Claude Agent SDK, with comprehensive safety constraints and multi-session state management through SQLite.