RoslynBridge/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• RoslynBridge/ – VSIX source (C#). Key folders: Server/ (HTTP host), Services/ (Roslyn queries, refactorings), Models/, Constants/.
• Build artifacts: RoslynBridge/bin/ and RoslynBridge/obj/.
• Claude skills: .claude/skills/roslyn-api/SKILL.md (HTTP query reference for local discovery/testing).

Build, Test, and Development Commands

• IMPORTANT: This VSIX project MUST be built with MSBuild, NOT dotnet build. Using dotnet build will fail with missing namespace errors.
• Build (CLI): msbuild RoslynBridge.sln /p:Configuration=Debug or with full path:

  & 'C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe' RoslynBridge.sln /t:Restore /t:Build /p:Configuration=Debug
  

• Build (VS): Open RoslynBridge.sln, set RoslynBridge as startup, press F5 to launch the Experimental Instance.
• Health check (server running in VS):
  • PowerShell: $b=@{queryType='getprojects'}|ConvertTo-Json; Invoke-RestMethod -Uri 'http://localhost:59123/query' -Method Post -Body $b -ContentType 'application/json'
  • curl (Windows): curl -X POST http://localhost:59123/query -H "Content-Type: application/json" -d "{\"queryType\":\"getprojects\"}"

Coding Style & Naming Conventions

• Language: C# (net48 VSIX). Use 4‑space indentation; braces on new lines.
• Naming: PascalCase for types/methods; camelCase for locals; private fields as _camelCase.
• Prefer async/await, avoid blocking the UI thread; use JoinableTaskFactory when switching.
• Keep nullable annotations consistent with project settings.
• Run Format Document and Organize Usings before commits.

Testing Guidelines

• No unit test project yet. Validate via HTTP endpoints (see SKILL.md): getprojects, getdiagnostics, getsolutionoverview, getsymbol, etc.
• Expected response shape: { success, message, data, error } (JSON).
• Lines are 1‑based; columns 0‑based. File paths in JSON require escaped backslashes.

Commit & Pull Request Guidelines

• Commits: concise, imperative subject (e.g., "Add diagnostics endpoint"), with short body explaining rationale and scope.
• PRs: include description, linked issues, sample requests/responses, and screenshots when UI/VS behavior is affected.
• Checklist: builds clean, getdiagnostics shows no new errors, code formatted, usings organized.

Security & Configuration Tips

• Server binds to http://localhost:59123/ and accepts only POST; CORS is permissive for local tooling. Do not expose externally.
• Endpoints: /query (main), /health route exists but still requires POST.
• Adjust port/paths in RoslynBridge/Constants/ServerConstants.cs if needed.

Agent Script Usage: rb.ps1 (for AI agents)

This section is for the agent only. Use rb.ps1 to minimize tokens and speed up local Roslyn queries.

• Location: rb.ps1 (repo root). Invoke with PowerShell.
• Auto-detects endpoints: prefers Web API (http://localhost:5001), falls back to VS plugin (http://localhost:59123).
• Output defaults to compact JSON. Use -Raw to emit raw response strings, -Pretty only for debugging.
• Override detection with -BaseUrl http://localhost:5001 if needed; -NoDetect forces Web API pathing.

Examples (run from repo root):

# Health and discovery
powershell -NoProfile -Command .\rb.ps1 health
powershell -NoProfile -Command .\rb.ps1 projects -Raw
powershell -NoProfile -Command .\rb.ps1 overview

# File-specific queries (use full paths from `projects`)
powershell -NoProfile -Command .\rb.ps1 diagnostics -FilePath C:/full/path/File.cs
powershell -NoProfile -Command .\rb.ps1 symbol -FilePath C:/full/path/File.cs -Line 12 -Column 4
powershell -NoProfile -Command .\rb.ps1 references -FilePath C:/full/path/File.cs -Line 12 -Column 4 -Raw

# Symbol search
powershell -NoProfile -Command .\rb.ps1 search -SymbolName Service -Kind class

# Project operations
powershell -NoProfile -Command .\rb.ps1 build -ProjectName MyProject
powershell -NoProfile -Command .\rb.ps1 package-add -ProjectName MyProject -PackageName Newtonsoft.Json -Version 13.0.3

# History (Web API only)
powershell -NoProfile -Command .\rb.ps1 history-recent -Count 10
powershell -NoProfile -Command .\rb.ps1 history-stats

# Compact solution overview summary (uses API-level summary)
powershell -NoProfile -Command .\rb.ps1 solution-overview -Format yaml -Top 5

Key behaviors and assumptions:

• Lines are 1-based; columns 0-based.
• Forward slashes / are accepted in file paths.
• Prefer -Raw to minimize token usage when chaining outputs.
• If Web API is down, commands transparently fall back to the plugin when possible. History endpoints require Web API.
• If auto-detection is ambiguous, set -BaseUrl explicitly.

Policy (agent-only):

• Do NOT call curl, Invoke-RestMethod, or Invoke-WebRequest directly to Roslyn Bridge.
• Always invoke rb.ps1 for all Roslyn-related queries and operations.
• Prefer -Raw output and parse only what’s needed to reduce tokens.
• Keep timeouts short unless debugging (-TimeoutSec can be raised temporarily).
• Avoid pretty output unless explicitly needed (-Pretty).