Creating an extension for Visual Studio

.github/instructions/cli.instructions.md

@@ -0,0 +1,61 @@
+---
+applyTo: "cli/**"
+---
+
+# CLI — Architecture & Integration Guide
+
+The CLI (`cli/`) is a standalone command-line tool that **shares the session discovery and data access classes** from `vscode-extension/src/` but has its own aggregation pipeline. It is built with TypeScript and bundled via `cli/esbuild.js` into `cli/dist/cli.js`.
+
+## Key Files
+
+- **`cli/src/helpers.ts`**: Shared helper functions — session discovery, file processing, stats aggregation. Imports all data access classes from `vscode-extension/src/`.
+- **`cli/src/commands/`**: One file per sub-command (`stats`, `usage`, `environmental`, `fluency`, `diagnostics`).
+- **`cli/esbuild.js`**: Build script. Copies JSON data files from `vscode-extension/src/` to a temp location before bundling, then removes them.
+- **`cli/tsconfig.json`**: `paths` alias points to `../vscode-extension/src/*`.
+
+## Developer Workflow
+
+```bash
+cd cli
+npm install
+npm run build            # development build
+npm run build:production # minified release build
+```
+
+Or from the repo root:
+```powershell
+./build.ps1 -Project cli
+```
+
+## Adding a New Editor / Data Source
+
+When adding support for a new editor or data source, wire it into **both** `vscode-extension/src/` (see `.github/instructions/vscode-extension.instructions.md`) **and** this CLI.
+
+### CLI Files to Update
+
+| File | What to add |
+|---|---|
+| `cli/src/helpers.ts` | Import, factory function, singleton, detection, stat routing, `processSessionFile()` branch, `calculateUsageAnalysisStats()` deps |
+| `cli/src/commands/stats.ts` | Add entry to `getEditorDisplayName()` |
+| `cli/src/commands/usage.ts` | No change needed — uses shared helpers |
+| `cli/README.md` | Add the new editor to the "Data Sources" section |
+
+### Integration Points in `cli/src/helpers.ts`
+
+1. **Import** — `import { NewEditorDataAccess } from '../../vscode-extension/src/neweditor';`
+2. **Factory function** — `function createNewEditor(): NewEditorDataAccess { return new NewEditorDataAccess(); }`
+3. **Singleton** — `const _newEditorInstance = createNewEditor();`
+4. **`createSessionDiscovery()`** — pass `newEditor: _newEditorInstance` in the deps object
+5. **`statSessionFile()`** — add guard routing virtual paths to the real DB file (before the generic `fs.promises.stat()` fallthrough)
+6. **`getEditorSourceFromPath()`** — add a path pattern check *before* the generic `'/code/'` or `'vscode'` fallthrough, returning a stable lowercase identifier (e.g. `'neweditor'`)
+7. **`processSessionFile()`** — add a guard block calling `getTokens()`, `countInteractions()`, `getModelUsage()` from the data access class and returning a `SessionData` object
+8. **`calculateUsageAnalysisStats()` deps** — pass `newEditor: _newEditorInstance` so `analyzeSessionUsage()` can route to it
+
+### Checklist
+
+- [ ] `cli/src/helpers.ts` — import, factory, singleton, detection, stat routing, processSessionFile block, usageAnalysis deps
+- [ ] `cli/src/commands/stats.ts` — `getEditorDisplayName()` entry
+- [ ] `cli/README.md` — "Data Sources" section updated
+- [ ] `npm run build` passes (from `cli/`)
+- [ ] CLI `stats` command shows the new editor in the session list
+- [ ] Token counts are non-zero and plausible

.github/instructions/visualstudio-extension.instructions.md

@@ -0,0 +1,72 @@
+---
+applyTo: "visualstudio-extension/**"
+---
+
+# Visual Studio Extension — Architecture & Development Guide
+
+The `visualstudio-extension/` folder contains a C# Visual Studio extension (`.vsix`) that replicates the core views of the VS Code extension for users of Visual Studio IDE.
+
+## Planned Approach (Option C — WebView2 + existing webviews)
+
+The extension hosts a **WebView2** control inside a Visual Studio Tool Window (C# `AsyncPackage`). The existing compiled webview bundles from `vscode-extension/dist/webview/` run inside WebView2 — avoiding a full UI rewrite. A thin C# bridge handles file I/O and passes JSON to the webview via `PostWebMessageAsJson`.
+
+### Key design decisions
+
+- **Data layer**: The `VisualStudioDataAccess` class in `vscode-extension/src/visualstudio.ts` already handles all session discovery and parsing for Visual Studio Copilot Chat binary session files (MessagePack format). The C# host reads session metadata and delegates token estimation to this layer by shelling out to the CLI, or by re-implementing only the discovery logic in C#.
+- **UI**: WebView2 renders the existing `details`, `chart`, `usage`, and `diagnostics` webview bundles. The VS Code CSS theme tokens (`--vscode-*`) will need a compatibility shim mapping to Visual Studio theme tokens.
+- **No cloud storage**: Azure Storage integration is out of scope for the initial version.
+
+## Developer Workflow
+
+```bash
+# Prerequisites: Visual Studio 2022, .NET SDK, VSIX workload
+cd visualstudio-extension
+dotnet build --configuration Release
+```
+
+Or from the repo root:
+```powershell
+./build.ps1 -Project visualstudio
+```
+
+## Build Validation
+
+VSIX projects require Visual Studio's MSBuild toolchain — **not `dotnet build`**.
+
+### Correct way: use `build.ps1`
+
+Always build the VS extension via the root orchestrator:
+```powershell
+# From the repo root:
+./build.ps1 -Project visualstudio
+```
+
+This uses `vswhere.exe` to locate the correct `MSBuild.exe` from the Visual Studio install. Running `dotnet build` against the `.csproj` directly **always fails** with:
+```
+error MSB4018: The "GenerateResourceAndCtoFileManifests" task failed unexpectedly.
+```
+That error is a `dotnet build` / VSSDK incompatibility, **not a code error** — ignore it if seen.
+
+### Checking for C# compiler errors without a full build
+
+```powershell
+# From the repo root:
+./build.ps1 -Project visualstudio 2>&1 | Select-String -Pattern "error CS|FAILED"
+# No "error CS" lines = no compiler errors
+```
+
+- The language server (Roslyn / `get_errors` tool) surfaces C# errors in the IDE without a build run.
+- After editing C# files, call `get_errors` on the changed files first, then run `./build.ps1 -Project visualstudio` to confirm a clean MSBuild result.
+
+### C# interpolated verbatim strings (`$@"..."`) — escaping `{` / `}`
+
+HTML templates in `ThemedHtmlBuilder.cs` use C# `$@"..."` strings. Literal `{` and `}` characters inside embedded JavaScript **must** be doubled (`{{` / `}}`) to avoid being treated as interpolation holes. Forgetting this produces `CS1073`, `CS1012`, `CS1011` errors at the JS lines.
+
+## Session File Discovery
+
+Visual Studio Copilot Chat stores sessions as MessagePack-encoded binary files:
+```
+<project>\.vs\<solution>.<ext>\copilot-chat\<hash>\sessions\<uuid>
+```
+
+Discovery is already implemented — see `vscode-extension/src/visualstudio.ts` for `VisualStudioDataAccess.discoverSessions()`.