docs/EXECUTION_GUIDE.md

Repository Intelligence Platform — End-to-End Execution Guide

This guide describes how to set up, build, package, run, and validate the Repository Intelligence Platform from scratch.

---

1. Prerequisites

Before setting up the platform, ensure your environment meets the following specifications:

• OS: Windows, macOS, or Linux (Ubuntu 20.04+)
• Python: Version >=3.9 (validated against Python 3.10, 3.11, and 3.12 in development)
• Node.js: Version 18 or higher (LTS recommended)
• npm: Version 9.x or 10.x
• VS Code: v1.85.0 or higher
• Git: Version 2.30.0 or higher (installed and configured in your PATH)

---

2. Backend Setup

Follow these steps to configure and start the backend service.

Step 2.1: Create a Virtual Environment & Install Dependencies

Run these commands from the repository root:

# Create a virtual environment
python -m venv .venv

# Activate the virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Upgrade pip and install package dependencies
pip install --upgrade pip
pip install -r requirements.txt

Step 2.2: Configure Environment Variables

Copy the template .env.example to .env and fill in the required LLM provider credentials:

# On Windows:
copy .env.example .env
# On macOS/Linux:
cp .env.example .env

Ensure your .env contains the required keys:

PORT=8001
HOST=127.0.0.1
GEMINI_API_KEY=your_gemini_api_key_here
DEEPSEEK_API_KEY=your_deepseek_api_key_here

Step 2.3: Run Database Migrations

Initialize the local SQLite database state:

python -m backend.cli run-migrations

Step 2.4: Start the FastAPI Backend Server

Launch the development server:

python -m uvicorn backend.api:app --host 127.0.0.1 --port 8001 --reload

---

3. VS Code Extension Setup

Follow these steps to compile and package the extension.

Step 3.1: Install Node Dependencies

Navigate to the vscode-extension directory and install the packages:

cd vscode-extension
npm install

Step 3.2: Compile and Package the Extension

Compile TypeScript files and create the .vsix distribution package:

# Compile TypeScript code
npm run compile

# Package the extension into a VSIX file
npx @vscode/vsce package --allow-missing-repository

This generates the packaged file: vscode-extension/repo-intelligence-agent-0.1.0.vsix.

---

4. VSIX Installation

Verify the extension in a clean, isolated VS Code profile:

1. Open your terminal.
2. Create a clean profile directory:

   mkdir -p C:\temp\vscode-profile
   

3. Launch a new VS Code window using that profile:

   code --user-data-dir C:\temp\vscode-profile\data --extensions-dir C:\temp\vscode-profile\extensions
   

4. In the new VS Code window:
   • Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
   • Select Extensions: Install from VSIX....
   • Locate and select repo-intelligence-agent-0.1.0.vsix.
   • Click Install.
5. Once installation finishes, reload the window (Developer: Reload Window).
6. Open your target repository folder in VS Code.

---

5. End-to-End Functional Verification

Confirm all components function correctly by completing the following checklist.

Feature Checklist

• [ ] Backend health: Open a browser or run curl http://127.0.0.1:8001/health and verify the status is "healthy".
• [ ] Analyze Repository: Click ARIA: Analyze Repository in the VS Code sidebar. Verify that the repository is cloned and the Digital Twin / Knowledge Graph are built under data/.
• [ ] Findings: Verify that the Engineering Findings panel renders the list of detected issues (Complexity, Performance, etc.).
• [ ] Advisor: Verify that the Advisor Dashboard lists advisor recommendations and roadmaps.
• [ ] Execution Planner: Verify that the Execution Planner displays tasks, batches, critical paths, and rollback checkpoints.
• [ ] Hover: Open a file, hover over a symbol (function/class name), and verify that the rich documentation card appears.
• [ ] CodeLens: Verify that CodeLens annotations ("Show Callers", "Show Blast Radius") render above symbol declarations.
• [ ] Code Actions: Highlight a block of code, press Ctrl+. / Cmd+., and verify that refactoring suggestions are shown.
• [ ] Search: Use the Search field in the ARIA bar and verify that it resolves matching files/symbols.
• [ ] Review: Right-click a file in the explorer, select ARIA: Review Current File, and check for feedback.
• [ ] Graph Navigation: Select Show Call Graph or Show Dependency Graph to display interactive visual maps.

---

6. Troubleshooting

Issue 6.1: Backend is unavailable

• Symptoms: The Backend Connection tree view shows status "offline".
• Probable Cause: The FastAPI server is not running, or is running on a different port/address.
• Resolution: Ensure you ran python -m uvicorn backend.api:app --host 127.0.0.1 --port 8001. Check if repoIntelligence.backendUrl in VS Code settings matches http://127.0.0.1:8001.

Issue 6.2: VSIX packaging failure

• Symptoms: vsce package errors out complaining about missing repository fields or missing files.
• Probable Cause: Repository metadata is missing from package.json, or the LICENSE file is missing.
• Resolution: Run npx @vscode/vsce package --allow-missing-repository. Ensure a copy of the LICENSE file exists in the vscode-extension directory.

Issue 6.3: Empty Tree Views

• Symptoms: The findings, advisor, or execution panels show "No active repository" or are completely blank.
• Probable Cause: Active repository is not selected, or analysis hasn't been run yet.
• Resolution: Click Set Active Repository (or run command repoIntelligence.setActiveRepository) and enter owner/repo-name. Run Analyze Repository to kick off the backend pipeline.

Issue 6.4: Authentication/Access Token Errors

• Symptoms: Analysis fails with a 401 or 403 status code.
• Probable Cause: Required GitHub token or API Key is missing or invalid.
• Resolution: Ensure repoIntelligence.apiToken is set in your VS Code settings, or check your backend .env variables.

Issue 6.5: API Endpoint mismatch (404 Not Found)

• Symptoms: Generating an execution plan returns a 404 error from the server.
• Probable Cause: VS Code extension client calls the wrong API path (e.g. /execution instead of /execution-plan).
• Resolution: Ensure you are using v1.5.0 where the client path has been mapped to /execution-plan.