Add VS Code extension E2E test architecture

.agents/skills/cli-e2e-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cli-e2e-testing
-description: Guide for writing Aspire CLI end-to-end tests using Hex1b terminal automation. Use this when asked to create, modify, or debug CLI E2E tests.
+description: Use when creating, modifying, debugging, or reviewing Aspire CLI end-to-end tests that use Hex1b terminal automation under tests/Aspire.Cli.EndToEnd.Tests/.
 ---
 
 # Aspire CLI End-to-End Testing with Hex1b
@@ -22,7 +22,7 @@ CLI E2E tests use the Hex1b library to automate terminal sessions, simulating re
 - **`Hex1bTerminal`**: The main terminal class from the Hex1b library for terminal automation
 - **`Hex1bTerminalAutomator`**: Async/await API for driving a `Hex1bTerminal` — the preferred approach for new tests
 - **`Hex1bAutomatorTestHelpers`** (shared helpers): Async extension methods on `Hex1bTerminalAutomator` (`WaitForSuccessPromptAsync`, `AspireNewAsync`, etc.)
-- **`CliE2EAutomatorHelpers`** (`Helpers/CliE2EAutomatorHelpers.cs`): CLI-specific async extension methods on `Hex1bTerminalAutomator` (`PrepareDockerEnvironmentAsync`, `InstallAspireCliInDockerAsync`, etc.)
+- **`CliE2EAutomatorHelpers`** (`Helpers/CliE2EAutomatorHelpers.cs`): CLI-specific async extension methods on `Hex1bTerminalAutomator` (`PrepareDockerEnvironmentAsync`, `InstallAspireCliAsync`, etc.)
 - **`CellPatternSearcher`**: Pattern matching for terminal cell content
 - **`SequenceCounter`** (`Helpers/SequenceCounter.cs`): Tracks command execution count for deterministic prompt detection
 - **`CliE2ETestHelpers`** (`Helpers/CliE2ETestHelpers.cs`): Environment variable helpers and terminal factory methods
@@ -53,7 +53,7 @@ public sealed class SmokeTests(ITestOutputHelper output)
 
         var counter = new SequenceCounter();
         var auto = new Hex1bTerminalAutomator(terminal, defaultTimeout: TimeSpan.FromSeconds(500));
-        await using var terminalRun = CliE2ETestHelpers.StartRun(terminal, workspace, auto, counter, TestContext.Current.CancellationToken);
+        await using var terminalRun = CliE2ETestHelpers.StartRun(terminal, workspace, auto, counter, output, TestContext.Current.CancellationToken);
 
         await auto.PrepareDockerEnvironmentAsync(counter, workspace);
         await auto.InstallAspireCliAsync(strategy, counter);
@@ -80,7 +80,7 @@ using var terminal = CliE2ETestHelpers.CreateDockerTestTerminal(repoRoot, strate
 
 var counter = new SequenceCounter();
 var auto = new Hex1bTerminalAutomator(terminal, defaultTimeout: TimeSpan.FromSeconds(500));
-await using var terminalRun = CliE2ETestHelpers.StartRun(terminal, workspace, auto, counter, TestContext.Current.CancellationToken);
+await using var terminalRun = CliE2ETestHelpers.StartRun(terminal, workspace, auto, counter, output, TestContext.Current.CancellationToken);
 
 // ... test body — no exit/pendingRun needed at the end
 
@@ -284,7 +284,7 @@ See [AspireNew Helper](#aspirenew-helper) below for detailed usage.
 | Method | Description |
 |--------|-------------|
 | `PrepareDockerEnvironmentAsync(counter, workspace)` | Sets up Docker container environment with custom prompt and command tracking |
-| `InstallAspireCliInDockerAsync(installMode, counter)` | Installs the Aspire CLI inside the Docker container |
+| `InstallAspireCliAsync(installMode, counter)` | Installs the Aspire CLI inside the Docker container |
 | `ClearScreenAsync(counter)` | Clears the terminal screen and waits for prompt |
 
 ### SequenceCounterExtensions
@@ -442,10 +442,10 @@ await auto.WaitForSuccessPromptAsync(counter);
 Some operations only apply in CI (like installing CLI from PR artifacts):
 
 ```csharp
-var installMode = CliE2ETestHelpers.DetectDockerInstallMode();
+var installMode = CliInstallStrategy.Detect(output.WriteLine);
 
 await auto.PrepareDockerEnvironmentAsync(counter, workspace);
-await auto.InstallAspireCliInDockerAsync(installMode, counter);
+await auto.InstallAspireCliAsync(installMode, counter);
 
 // Continue with test commands...
 ```
@@ -611,6 +611,45 @@ When CLI E2E tests fail in CI, follow these steps to diagnose the issue:
 
 > **Flaky test investigation:** for recurring/intermittent failures, see [`troubleshooting.md`](./troubleshooting.md) for a catalog of known flake classes (Y/n input race, prompt-counter desync, etc.) and the recipes to identify them from `.cast` recordings.
 
+### VS Code Extension E2E Diagnostics
+
+For VS Code extension behavior or extension/CLI integration issues, strongly prefer adding or
+updating a reproducible test under `extension/src/test-e2e/`. Use agent-driven Playwright/VS Code UI
+driving only as exploratory diagnosis when the E2E scenario is not clear yet; convert any successful
+manual reproduction into an E2E test before fixing the bug unless there is a strong, explicit reason
+not to.
+
+When running extension E2E tests against an older published CLI for compatibility validation, set
+`ASPIRE_EXTENSION_E2E_SKIP_CURRENT_CLI_REGRESSIONS=true` to skip tests that intentionally cover bugs
+fixed only by the current repo-built CLI.
+
+VS Code extension E2E jobs upload shard-specific diagnostics as `extension-e2e-diagnostics-<rid>-<shard>-attempt<N>` artifacts. Linux shards include `.mp4` display recordings from Xvfb by default; Windows shards do not record video and instead rely on screenshots, VS Code logs, state files, and workspace diagnostics.
+
+```bash
+# List VS Code extension E2E diagnostic artifacts for a run.
+gh api "repos/microsoft/aspire/actions/runs/<run-id>/artifacts?per_page=100" --paginate \
+  --jq '.artifacts[] | select(.name | startswith("extension-e2e-diagnostics")) | "\(.size_in_bytes)\t\(.name)"'
+
+# Download one shard's diagnostics. The artifact contains .mp4 recordings
+# on Linux, .ffmpeg.log files, screenshots, VS Code logs, state files, and
+# captured workspace diagnostics.
+mkdir -p ./e2e-diagnostics && cd ./e2e-diagnostics
+gh run download <run-id> --repo microsoft/aspire \
+  -n extension-e2e-diagnostics-linux-x64-<shard>-attempt<N> \
+  -D <shard>
+```
+
+Important paths inside the downloaded shard:
+
+```text
+<shard>/.test-recordings/<shard>/<runId>.mp4
+<shard>/.test-recordings/<shard>/<runId>.ffmpeg.log
+<shard>/.test-storage/**/screenshots/
+<shard>/.test-results/e2e/<shard>/extension-state.json
+```
+
+The workflow keeps Linux recordings by default with `ASPIRE_EXTENSION_E2E_RECORDING_MODE=always`. Use `failure` to keep only failed-run videos or `off` to disable recording for local runs.
+
 ### Quick Start: Download and Play Recordings
 
 The fastest way to debug a CLI E2E test failure is to download and play the asciinema recording.

.agents/skills/vscode-extension/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: vscode-extension
+description: "Use when investigating, developing, debugging, testing, or reviewing Aspire VS Code extension behavior under extension/, including extension UI, command, debugger, RPC, DCP, MCP, and CLI-integration issues or features."
+---
+
+# Aspire VS Code Extension
+
+This skill covers working on the Aspire VS Code extension, which lives entirely under
+[extension/](../../../extension). It is a TypeScript extension built with **yarn** (pinned via
+`packageManager` in `extension/package.json`) and **webpack**, and it communicates with the Aspire
+CLI over RPC.
+
+## Orientation
+
+All commands below are run from the `extension/` directory unless noted.
+
+| Path | What it is |
+|------|------------|
+| `extension/src/extension.ts` | Activation entry point |
+| `extension/src/commands/` | Command implementations |
+| `extension/src/views/` | Tree views, welcome views, panel UI |
+| `extension/src/debugger/` | Debug adapter + per-language debuggers (dotnet, node, python, go) |
+| `extension/src/server/`, `extension/src/mcp/`, `extension/src/dcp/` | RPC server, MCP provider, DCP integration |
+| `extension/src/loc/strings.ts` | Localized strings (TypeScript-side) |
+| `extension/package.nls.json` | Localized strings referenced from `package.json` (`%key%`) |
+| `extension/src/test/` | Mocha unit tests (`*.test.ts`) run via `vscode-test` |
+| `extension/package.json` | Manifest: `contributes`, `activationEvents`, scripts |
+
+## Prerequisites
+
+**Do NOT run the repo-root `./build.sh` or `./restore.sh` when you are only working on the Aspire
+CLI and/or the VS Code extension.** The root scripts build the entire product (all of `src/`, native
+AOT, packages) and are slow and unnecessary for this work. Instead, **build the extension and CLI
+together with the extension build script.** From `extension/`, run `./build.sh` (Linux/macOS) or
+`./build.ps1` (Windows). This script builds the Aspire CLI
+(`dotnet build ../src/Aspire.Cli/Aspire.Cli.csproj`) **and** the extension, and installs extension
+dependencies (seeds Corepack and runs `corepack yarn install`). You do not install Yarn yourself —
+it is pinned via `packageManager`.
+
+Use **yarn** for extension commands (`corepack yarn ...` or `yarn run ...`), not `npm` / `npx`.
+The dependency graph and scripts are pinned for Yarn via `extension/package.json` and `yarn.lock`.
+
+If `corepack yarn install` fails with registry 401/404 or `EACCES`, see the Troubleshooting section
+of [extension/CONTRIBUTING.md](../../../extension/CONTRIBUTING.md) — these are environment/npm-mirror
+issues, not code issues.
+
+## Extension ↔ CLI compatibility (IMPORTANT)
+
+The extension and the Aspire CLI are tightly coupled: **new features or changes in the extension
+often require corresponding changes in the CLI.** When you add or modify extension behavior, expect
+to also touch `src/Aspire.Cli/` and rebuild both with `extension/build.sh` / `extension/build.ps1`.
+
+When you change a CLI contract or expectation (command output shape, JSON schema, new flags, new
+behavior the extension relies on), **you must remain backwards compatible and keep working with older
+Aspire CLI versions.** A user may have a newer extension paired with an older `aspire` CLI on their
+PATH. Do not assume the CLI supports a capability just because the current build does.
+
+Detect what the installed CLI supports at runtime instead of assuming, by reading capabilities from extension functionality that wraps `aspire config info`.
+
+## Develop / modify the extension
+
+- Prefer **TypeScript** (`.ts`) files; never create `.js` source files for extension code.
+- Use **static imports**, not dynamic imports, unless dynamic import is absolutely necessary.
+- Use the latest TypeScript features consistent with the existing code style.
+- New user-facing commands, views, settings, or debugger config go in the `contributes` section of
+  `extension/package.json`.
+
+### Localization (REQUIRED for any user-facing string)
+
+Every string shown to the user must be localized. There are two surfaces:
+
+- **TypeScript code** → add to `extension/src/loc/strings.ts` using `vscode.l10n.t(...)`. Follow the
+  existing pattern (plain `const` for static strings, an arrow function for strings with
+  placeholders like `{0}`). Import from `loc/strings` rather than inlining literals.
+- **`package.json` manifest** (command titles, view names, setting descriptions, debugger
+  properties) → use a `%key%` reference and define the key in `extension/package.nls.json`.
+
+Do not hand-edit generated localization bundles (the `l10n/` output, `*.xlf`, or
+`*/localize/templatestrings.*.json`); translation is handled by a dedicated workflow. The npm
+scripts `l10n:export` / `l10n:import` (run automatically by `precompile`/`prepackage`/`prewatch`)
+regenerate the l10n bundle from `package.nls.json` and the `vscode.l10n.t` calls.
+
+## Build
+
+From `extension/`:
+
+```bash
+yarn run compile      # one-off webpack build to ./dist
+yarn run watch        # incremental webpack build (use while iterating)
+yarn run package      # production build (minified, hidden source maps)
+```
+
+`watch`, `compile`, and `package` are preceded by `prewatch`/`precompile`/`prepackage`, which run
+`generate-version`, `generate-schema`, and the l10n export/import. The VS Code task
+`yarn: watch extension` (the default build task) runs `yarn run watch`.
+
+To produce a `.vsix`, the full MSBuild path is `extension/Extension.proj` (used by CI/signing); for
+local iteration `yarn run package` plus the launch configs below is usually enough.
+
+## Test
+
+The extension has Mocha unit tests under `extension/src/test/` executed by `@vscode/test-cli`.
+
+```bash
+yarn run compile-tests   # tsc -> ./out (or watch-tests to keep rebuilding)
+yarn run test            # alias for unit-test (vscode-test); runs lint+compile via pretest
+yarn run lint            # eslint src
+```
+
+`pretest` runs `compile-tests`, `compile`, and `lint`, so `yarn run test` is the single command that
+builds and runs everything. When iterating on one area, keep `watch-tests` running and re-run
+`yarn run test`.
+
+Add new tests as `extension/src/test/<area>.test.ts` mirroring nearby tests (e.g.
+`appHostDiscovery.test.ts`, `strings.test.ts`). There is a `strings.test.ts` that guards
+localization conventions — run it after touching `loc/strings.ts` or `package.nls.json`.
+
+When adding, changing, or investigating user-visible UI behavior or interactions, strongly prefer
+adding or updating VS Code extension E2E coverage under `extension/src/test-e2e/` so the behavior is
+reproducible and protected from regressions. Skip this only with a strong, explicit justification.
+If you run these tests against an older published CLI for compatibility validation, set
+`ASPIRE_EXTENSION_E2E_SKIP_CURRENT_CLI_REGRESSIONS=true` to skip tests that intentionally cover bugs
+fixed only by the current repo-built CLI.
+
+## Debug / run locally
+
+1. Open the `extension/` folder in VS Code.
+2. Launch the **Run Extension** launch configuration to start an Extension Development Host, or
+   **Run Extension (cli stop on entry)** to make the CLI wait for a debugger to attach (use this to
+   debug the CLI and the extension together).
+3. To debug against a locally built CLI, set the `Aspire Cli Executable Path` setting to the build
+   output, e.g. `artifacts/bin/Aspire.Cli/Debug/net10.0/aspire` (relative to the repo root). The
+   `Aspire: Extension settings` command opens settings filtered to the extension.
+
+RPC and debugger issues usually live in `src/server/`, `src/debugger/`, or `src/dcp/`.
+
+## Reproducing issues yourself (do this FIRST for root-cause / "can you repro" requests)
+
+When asked to **find the root cause of** or **reproduce** an issue, do not stop at reading source
+code. Strongly prefer a reproducible VS Code extension E2E test under `extension/src/test-e2e/` that
+opens a workspace, drives the extension through its public UI/commands, and captures the failing
+behavior in the E2E state file, VS Code logs, screenshots, or assertions.
+
+Use Playwright or an Extension Development Host only as exploratory help when the right E2E shape is
+not yet clear. If that exploration reproduces the issue, convert the scenario into an E2E test before
+fixing the bug unless there is a strong, explicit reason not to. You can test a custom CLI build by
+pointing the `Aspire Cli Executable Path` setting at your locally built `aspire`.
+
+## Gotchas
+
+- Do not modify `package.json` / `yarn.lock` / `package-lock.json` unless explicitly asked; when you
+  must pin a transitive dependency, add it to `resolutions` and regenerate `yarn.lock` with
+  `corepack yarn install` (see CONTRIBUTING).
+- `yarn.lock` must resolve through the internal `dotnet-public-npm` feed; the build rejects public
+  npmjs.org URLs.
+- Generated files (`l10n/` bundle, schema, version) are produced by the pre-scripts — edit the
+  sources (`package.nls.json`, `loc/strings.ts`, schema/version generator scripts), not the output.

.github/agents/agentic-workflows.agent.md

@@ -176,3 +176,4 @@ gh aw compile --validate
 - Follow security best practices: minimal permissions, explicit network access, no template injection
 - **Network configuration**: Use ecosystem identifiers (`node`, `python`, `go`, etc.) or explicit FQDNs in `network.allowed`. Bare shorthands like `npm` or `pypi` are **not** valid. See https://github.com/github/gh-aw/blob/v0.72.0/.github/aw/network.md for the full list of valid ecosystem identifiers and domain patterns.
 - **Single-file output**: When creating a workflow, produce exactly **one** workflow `.md` file. Do not create separate documentation files (architecture docs, runbooks, usage guides, etc.). If documentation is needed, add a brief `## Usage` section inside the workflow file itself.
+- **User-facing changelog/release-note output**: Workflows that generate changelogs, release notes, status reports intended for release communication, or related summaries must explicitly exclude non-user-facing issues and PRs. Do not include agentic workflow, automation, CI/build, test-only, dependency-bump, release-engineering, changelog-generation, or repository-maintenance changes unless they directly change the released product experience for users.

.github/workflows/extension-changelog.md

@@ -238,12 +238,20 @@ enrich when helpful (for example `is:pr is:merged repo:microsoft/aspire` queries
 to confirm PR titles and labels). You may also read the changed file list /
 diff under `extension/` to understand what actually changed.
 
+Exclude anything that is not user-facing. A change is user-facing only when
+someone using the VS Code extension can observe it in commands, settings,
+debugging, tree views, walkthroughs, diagnostics, packaging/installation,
+security, compatibility, or performance. Do not mention issues or PRs that only
+affect repository operation or the engineering process.
+
 Exclude noise that a user-facing changelog should not mention:
 
 - Dependency-bump / Dependabot PRs unless they fix a user-visible security issue.
 - Build, CI, and test-only changes with no user-facing effect.
 - Internal refactors with no behavior change.
 - Version-bump and release-prep commits (including this PR's own commit).
+- Agentic workflow, automation, changelog-generation, and repository maintenance
+  changes unless they directly change the released extension experience.
 
 ## Step 5: Learn the existing changelog format