Merge branch 'staging' into copilot/align-ci-and-makefile-tools

Author: gkorland

.env.template

@@ -2,15 +2,28 @@
 FALKORDB_HOST=localhost
 FALKORDB_PORT=6379
 
-# OpenAI API key for LLM features
-OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
+# Optional FalkorDB authentication
+FALKORDB_USERNAME=
+FALKORDB_PASSWORD=
 
-# Secret token for API authentication
+# Token checked by authenticated endpoints. If left empty, the current
+# implementation accepts requests without an Authorization header.
 SECRET_TOKEN=<YOUR_SECRET_TOKEN>
 
-# Flask server settings
-FLASK_RUN_HOST=0.0.0.0
-FLASK_RUN_PORT=5000
-
-# Set to 1 to enable public access for analyze_repo/switch_commit endpoints
+# Set to 1 to make read-only endpoints public.
 CODE_GRAPH_PUBLIC=0
+
+# Limit /api/analyze_folder to this directory tree. Leave commented to use
+# the repository root as the default allowed directory.
+# ALLOWED_ANALYSIS_DIR=/absolute/path/to/projects
+
+# LiteLLM model used by /api/chat
+MODEL_NAME=gemini/gemini-flash-lite-latest
+
+# Provider credential for the default Gemini model. Change this to the
+# appropriate provider key if you change MODEL_NAME.
+GEMINI_API_KEY=<YOUR_GEMINI_API_KEY>
+
+# Optional Uvicorn bind settings used by start.sh / make run-*
+HOST=0.0.0.0
+PORT=5000

.github/workflows/build.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Node
         uses: actions/setup-node@v6
@@ -47,7 +47,7 @@ jobs:
           python-version: "3.12"
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v7
         with:
           version: "latest"
 
@@ -58,7 +58,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Build Docker image
         uses: docker/build-push-action@v7

.github/workflows/playwright.yml

@@ -25,7 +25,7 @@ jobs:
         ports:
           - 6379:6379
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
     - uses: actions/setup-node@v6
       with:
@@ -40,7 +40,7 @@ jobs:
         python-version: '3.12'
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v5
+      uses: astral-sh/setup-uv@v7
       with:
         version: "latest"
 
@@ -66,7 +66,7 @@ jobs:
 
     - name: Cache Playwright browsers
       id: playwright-cache
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       with:
         path: ~/.cache/ms-playwright
         key: playwright-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('package-lock.json') }}
@@ -81,17 +81,17 @@ jobs:
         npx playwright install chromium firefox
         npx playwright install-deps chromium firefox
 
-    - name: Start Flask server
+    - name: Start server
       id: start-server
       env:
         OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
         SECRET_TOKEN: ${{ secrets.SECRET_TOKEN }}
         CODE_GRAPH_PUBLIC: "1"
         MODEL_NAME: "openai/gpt-4.1-mini"
       run: |
-        uv run flask --app api/index.py run --host 0.0.0.0 --port 5000 &
+        uv run uvicorn api.index:app --host 0.0.0.0 --port 5000 &
         echo "pid=$!" >> "$GITHUB_OUTPUT"
-        # Wait for Flask to be ready
+        # Wait for server to be ready
         timeout 30 bash -c 'until curl -s http://localhost:5000/ > /dev/null 2>&1; do sleep 0.5; done'
 
     - name: Run Playwright tests
@@ -102,7 +102,7 @@ jobs:
         MODEL_NAME: "openai/gpt-4.1-mini"
       run: npx playwright test --shard=${{ matrix.shard }}/2 --reporter=dot,list
 
-    - name: Stop Flask server
+    - name: Stop server
       if: always()
       run: kill ${{ steps.start-server.outputs.pid }} 2>/dev/null || true
 

.github/workflows/release-image.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set tags
         run: |

AGENTS.md

@@ -0,0 +1,132 @@
+# CodeGraph - Agent Instructions
+
+Knowledge graph visualization tool for codebases. Python FastAPI backend + React/TypeScript frontend + FalkorDB graph database.
+
+## Architecture
+
+- **Backend** (`api/`): FastAPI, async-first. All routes in `api/index.py`. Graph ops in `api/graph.py`. LLM chat via GraphRAG in `api/llm.py`.
+- **Frontend** (`app/`): React 18 + TypeScript + Vite. Tailwind CSS + Radix UI. 3D force-graph visualization (D3/Force-Graph).
+- **Database**: FalkorDB (graph DB on Redis). Metadata in Redis key-value store.
+- **Analyzers** (`api/analyzers/`): tree-sitter (Python), multilspy (Java, C#). Base class in `analyzer.py`, orchestrator in `source_analyzer.py`.
+
+### Data flow
+
+1. User submits repo URL or folder path -> backend clones/reads and analyzes via language-specific analyzers
+2. Entities stored in FalkorDB (nodes: File, Class, Function; edges: DEFINES, CALLS, etc.)
+3. Metadata (URL, commit) stored in Redis
+4. Frontend fetches graph, renders interactive visualization
+5. User can chat (GraphRAG), explore neighbors, find paths
+
+## Directory structure
+
+```text
+api/                  # Python backend
+  index.py            # FastAPI app, routes, auth, SPA serving
+  graph.py            # FalkorDB graph operations (sync + async)
+  llm.py              # GraphRAG + LiteLLM chat
+  project.py          # Repo cloning and analysis pipeline
+  info.py             # Redis metadata operations
+  prompts.py          # LLM prompt templates
+  auto_complete.py    # Prefix search
+  analyzers/          # Language-specific code analyzers
+  entities/           # Graph entity models
+  git_utils/          # Git history graph construction
+app/                  # React frontend (Vite)
+  src/components/     # React components (ForceGraph, chat, code-graph, etc.)
+  src/lib/            # Utilities
+tests/                # Pytest backend tests
+  endpoints/          # API endpoint integration tests
+e2e/                  # Playwright E2E tests
+  seed_test_data.py   # Test data seeder
+```
+
+## Commands
+
+```bash
+make install         # Install all deps (uv sync + npm install)
+make build-dev       # Build frontend (dev mode)
+make build-prod      # Build frontend (production)
+make run-dev         # Build dev frontend + run API with reload
+make run-prod        # Build prod frontend + run API
+make test            # Run pytest suite
+make lint            # Ruff + TypeScript type-check
+make lint-py         # Ruff only
+make lint-fe         # TypeScript type-check only
+make e2e             # Run Playwright tests
+make clean           # Remove build artifacts
+make docker-falkordb # Start FalkorDB container for testing
+make docker-stop     # Stop test containers
+```
+
+### Manual commands
+
+```bash
+# Backend
+uv run uvicorn api.index:app --host 127.0.0.1 --port 5000 --reload
+uv run python -m pytest tests/ --verbose
+uv run ruff check .
+
+# Frontend
+npm --prefix ./app run dev          # Vite dev server (port 3000, proxies /api to 5000)
+npm --prefix ./app run build        # Production build
+npm --prefix ./app run lint         # Type-check
+
+# E2E
+npx playwright test
+```
+
+## Conventions
+
+### Python (backend)
+- snake_case for functions/variables, PascalCase for classes
+- Async-first: route handlers and most graph operations are async, though api/graph.py includes some synchronous helpers
+- Auth: `public_or_auth` for read endpoints, `token_required` for mutating endpoints
+- Graph labels: PascalCase (File, Class, Function). Relations: SCREAMING_SNAKE_CASE (DEFINES, CALLS)
+- Linter: Ruff
+
+### TypeScript (frontend)
+- camelCase for functions/variables, PascalCase for components
+- Tailwind CSS for styling
+- Radix UI for headless components
+- Linter: tsc (type-check only)
+
+### General
+- Python >=3.12,<3.14. Node 20+.
+- Package managers: `uv` (Python), `npm` (frontend)
+- Environment variables: SCREAMING_SNAKE_CASE. See `.env.template` for reference.
+
+## Environment variables
+
+Key variables (see `.env.template` for full list):
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `FALKORDB_HOST` | `localhost` | Graph DB host |
+| `FALKORDB_PORT` | `6379` | Graph DB port |
+| `SECRET_TOKEN` | empty | API auth token |
+| `CODE_GRAPH_PUBLIC` | `0` | Skip auth on read endpoints when `1` |
+| `MODEL_NAME` | `gemini/gemini-flash-lite-latest` | LiteLLM model for chat |
+| `ALLOWED_ANALYSIS_DIR` | repo root | Root path for analyze_folder |
+
+## Testing
+
+- **Backend**: `make test` runs pytest against `tests/`. Endpoint tests in `tests/endpoints/`.
+- **E2E**: `make e2e` runs Playwright (Chromium + Firefox). Test data seeded via `e2e/seed_test_data.py`.
+- **CI**: GitHub Actions — `build.yml` (lint + build), `playwright.yml` (E2E, 2 shards), `release-image.yml` (Docker image).
+
+## API endpoints
+
+### Read (public_or_auth)
+- `GET /api/list_repos` — List indexed repos
+- `GET /api/graph_entities?repo=<name>` — Fetch graph entities
+- `POST /api/get_neighbors` — Neighboring nodes
+- `POST /api/auto_complete` — Prefix search
+- `POST /api/repo_info` — Repo stats/metadata
+- `POST /api/find_paths` — Paths between nodes
+- `POST /api/chat` — GraphRAG chat
+- `POST /api/list_commits` — Git commit history
+
+### Mutating (token_required)
+- `POST /api/analyze_folder` — Analyze local folder
+- `POST /api/analyze_repo` — Clone and analyze repo
+- `POST /api/switch_commit` — Switch to specific commit

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

Makefile

@@ -40,10 +40,10 @@ clean: ## Clean up build and test artifacts
 	find . -name "*.pyo" -delete
 
 run-dev: build-dev ## Run development server (Python backend serving built frontend)
-	uv run flask --app api/index.py run --host $${HOST:-127.0.0.1} --port $${PORT:-5000} --debug
+	uv run uvicorn api.index:app --host $${HOST:-127.0.0.1} --port $${PORT:-5000} --reload
 
 run-prod: build-prod ## Run production server
-	uv run flask --app api/index.py run --host $${HOST:-0.0.0.0} --port $${PORT:-5000}
+	uv run uvicorn api.index:app --host $${HOST:-0.0.0.0} --port $${PORT:-5000}
 
 docker-falkordb: ## Start FalkorDB in Docker for testing
 	docker run -d --name falkordb-test -p 6379:6379 falkordb/falkordb:latest