From 167a71400ada06c7f5bd5bf297de438dd371841a Mon Sep 17 00:00:00 2001 From: katriendg Date: Wed, 4 Feb 2026 08:46:27 +0100 Subject: [PATCH 1/3] fix(extension): update extension kind and update PACKAGING.md to clarify extension configuration and execution contexts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - add details on dual-mode configuration for workspace and UI - explain script fallback patterns for different execution scenarios 🔧 - Generated by Copilot --- extension/PACKAGING.md | 75 +++++++++++++++++++++++++++--------------- extension/package.json | 1 + 2 files changed, 50 insertions(+), 26 deletions(-) diff --git a/extension/PACKAGING.md b/extension/PACKAGING.md index 72800717..f58c4d2a 100644 --- a/extension/PACKAGING.md +++ b/extension/PACKAGING.md @@ -23,6 +23,29 @@ extension/ └── PACKAGING.md # This file ``` +## Extension Configuration + +### Extension Kind + +The extension is configured with `"extensionKind": ["workspace", "ui"]` in `package.json` to support multiple execution contexts: + +* **Workspace mode**: Extension runs in the workspace extension host with direct access to workspace files (`.github/`, `scripts/dev-tools/`, etc.) +* **UI mode**: Extension runs in the UI extension host on the user's local machine + +### Why Bundling Solves Path Resolution Issues + +According to [VS Code Remote Extensions documentation](https://code.visualstudio.com/api/advanced-topics/remote-extensions#architecture-and-extension-kinds), **UI Extensions cannot directly access files in the remote workspace**, which causes instruction files and scripts to become unavailable. + +This dual-mode configuration with bundled resources solves critical installation issues: + +* **Instruction files not found**: In Windows/WSL environments, when Copilot runs as a UI extension, it cannot access workspace files through the remote workspace path. The documented behavior states UI extensions "cannot directly access files in the remote workspace"—bundled instruction files provide the required fallback. + +* **Cross-platform path resolution failures**: Windows paths (e.g., `/Users/username/.vscode-insiders/extensions/...`) fail when referenced from WSL Linux environments. VS Code Server runs standard Node.js (not Electron) in remote contexts, requiring platform-independent access patterns. + +* **Remote workspace limitations**: In Codespaces, devcontainers, and SSH hosts, workspace file access depends on extension kind. Bundling ensures consistent access regardless of where the extension host executes. + +The extension prioritizes local workspace files when running in workspace mode but seamlessly falls back to bundled copies when running in UI mode or when path resolution fails across OS boundaries. + ## Prerequisites Install the VS Code Extension Manager CLI: @@ -65,11 +88,11 @@ npm run extension:prepare The preparation script automatically: -- Discovers and registers all chat agents from `.github/agents/` -- Discovers and registers all prompts from `.github/prompts/` -- Discovers and registers all instruction files from `.github/instructions/` -- Updates `package.json` with discovered components -- Uses existing version from `package.json` (does not modify it) +* Discovers and registers all chat agents from `.github/agents/` +* Discovers and registers all prompts from `.github/prompts/` +* Discovers and registers all instruction files from `.github/instructions/` +* Updates `package.json` with discovered components +* Uses existing version from `package.json` (does not modify it) #### Step 2: Package the Extension @@ -94,13 +117,13 @@ pwsh ./scripts/extension/Package-Extension.ps1 -Version "1.1.0" -DevPatchNumber The packaging script automatically: -- Uses version from `package.json` (or specified version) -- Optionally appends dev patch number for pre-release builds -- Copies required `.github` directory -- Copies `scripts/dev-tools` directory (developer utilities) -- Packages the extension using `vsce` -- Cleans up temporary files -- Restores original `package.json` version if temporarily modified +* Uses version from `package.json` (or specified version) +* Optionally appends dev patch number for pre-release builds +* Copies required `.github` directory +* Copies `scripts/dev-tools` directory (developer utilities) +* Packages the extension using `vsce` +* Cleans up temporary files +* Restores original `package.json` version if temporarily modified ### Manual Packaging (Legacy) @@ -145,15 +168,15 @@ vsce publish --packagePath "$VSIX_FILE" The `extension/.vscodeignore` file controls what gets packaged. Currently included: -- `.github/agents/**` - All custom agent definitions -- `.github/prompts/**` - All prompt templates -- `.github/instructions/**` - All instruction files -- `docs/templates/**` - Document templates used by agents (ADR, BRD, Security Plan) -- `scripts/dev-tools/**` - Developer utilities (PR reference generation) -- `package.json` - Extension manifest -- `README.md` - Extension description -- `LICENSE` - License file -- `CHANGELOG.md` - Version history +* `.github/agents/**` - All custom agent definitions +* `.github/prompts/**` - All prompt templates +* `.github/instructions/**` - All instruction files +* `docs/templates/**` - Document templates used by agents (ADR, BRD, Security Plan) +* `scripts/dev-tools/**` - Developer utilities (PR reference generation) +* `package.json` - Extension manifest +* `README.md` - Extension description +* `LICENSE` - License file +* `CHANGELOG.md` - Version history ## Testing Locally @@ -243,11 +266,11 @@ See [Agent Maturity Levels](../docs/contributing/ai-artifacts-common.md#maturity ## Notes -- The `.github`, `docs/templates`, and `scripts/dev-tools` folders are temporarily copied during packaging (not permanently stored) -- `LICENSE` and `CHANGELOG.md` are copied from root during packaging and excluded from git -- Only essential extension files are included (agents, prompts, instructions, templates, dev-tools) -- Non-essential files are excluded (workflows, issue templates, agent installer, etc.) -- The root `package.json` contains development scripts for the repository +* The `.github`, `docs/templates`, and `scripts/dev-tools` folders are temporarily copied during packaging (not permanently stored) +* `LICENSE` and `CHANGELOG.md` are copied from root during packaging and excluded from git +* Only essential extension files are included (agents, prompts, instructions, templates, dev-tools) +* Non-essential files are excluded (workflows, issue templates, agent installer, etc.) +* The root `package.json` contains development scripts for the repository --- diff --git a/extension/package.json b/extension/package.json index 29a57d01..af24ef7d 100644 --- a/extension/package.json +++ b/extension/package.json @@ -1,6 +1,7 @@ { "name": "hve-core", "displayName": "HVE Core", + "extensionKind": ["workspace", "ui"], "version": "2.0.1", "description": "AI-powered chat agents, prompts, and instructions for hybrid virtual environments", "publisher": "ise-hve-essentials", From 36219a520785032a29ffbcdea516d02da8fa49fc Mon Sep 17 00:00:00 2001 From: katriendg Date: Wed, 4 Feb 2026 08:53:24 +0100 Subject: [PATCH 2/3] docs: simplify extension bundling benefits in PACKAGING.md --- extension/PACKAGING.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/extension/PACKAGING.md b/extension/PACKAGING.md index f58c4d2a..23898b6b 100644 --- a/extension/PACKAGING.md +++ b/extension/PACKAGING.md @@ -32,19 +32,7 @@ The extension is configured with `"extensionKind": ["workspace", "ui"]` in `pack * **Workspace mode**: Extension runs in the workspace extension host with direct access to workspace files (`.github/`, `scripts/dev-tools/`, etc.) * **UI mode**: Extension runs in the UI extension host on the user's local machine -### Why Bundling Solves Path Resolution Issues - -According to [VS Code Remote Extensions documentation](https://code.visualstudio.com/api/advanced-topics/remote-extensions#architecture-and-extension-kinds), **UI Extensions cannot directly access files in the remote workspace**, which causes instruction files and scripts to become unavailable. - -This dual-mode configuration with bundled resources solves critical installation issues: - -* **Instruction files not found**: In Windows/WSL environments, when Copilot runs as a UI extension, it cannot access workspace files through the remote workspace path. The documented behavior states UI extensions "cannot directly access files in the remote workspace"—bundled instruction files provide the required fallback. - -* **Cross-platform path resolution failures**: Windows paths (e.g., `/Users/username/.vscode-insiders/extensions/...`) fail when referenced from WSL Linux environments. VS Code Server runs standard Node.js (not Electron) in remote contexts, requiring platform-independent access patterns. - -* **Remote workspace limitations**: In Codespaces, devcontainers, and SSH hosts, workspace file access depends on extension kind. Bundling ensures consistent access regardless of where the extension host executes. - -The extension prioritizes local workspace files when running in workspace mode but seamlessly falls back to bundled copies when running in UI mode or when path resolution fails across OS boundaries. +The extension prioritizes local workspace files when available but seamlessly falls back to bundled copies when running in UI mode or when path resolution fails across OS boundaries. ## Prerequisites From 6bf17cdb912ecb7f839661dc5e8b9a89d1a51892 Mon Sep 17 00:00:00 2001 From: katriendg Date: Wed, 4 Feb 2026 09:26:24 +0100 Subject: [PATCH 3/3] docs: clarify extension configuration and execution contexts in PACKAGING.md - enhance descriptions for workspace and UI modes - explain access to bundled files and path resolution - detail declarative nature of the extension --- extension/PACKAGING.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/extension/PACKAGING.md b/extension/PACKAGING.md index 23898b6b..8f9e03f9 100644 --- a/extension/PACKAGING.md +++ b/extension/PACKAGING.md @@ -29,10 +29,12 @@ extension/ The extension is configured with `"extensionKind": ["workspace", "ui"]` in `package.json` to support multiple execution contexts: -* **Workspace mode**: Extension runs in the workspace extension host with direct access to workspace files (`.github/`, `scripts/dev-tools/`, etc.) -* **UI mode**: Extension runs in the UI extension host on the user's local machine +* **Workspace mode**: Extension runs in the workspace (remote) extension host. In this mode, the extension accesses its bundled files from the extension installation directory in the remote/workspace context (for example, the packaged `.github/` and `scripts/dev-tools/` folders). +* **UI mode**: Extension runs in the UI extension host on the user's local machine and accesses the same bundled extension files from the local installation directory. -The extension prioritizes local workspace files when available but seamlessly falls back to bundled copies when running in UI mode or when path resolution fails across OS boundaries. +Access to files in the user's project workspace always uses the standard VS Code workspace APIs and is independent of the extension kind. Both modes use the same packaged extension assets and differ only in execution context (local UI versus remote/workspace). This bundling approach ensures GitHub Copilot can reliably access instruction files and scripts regardless of cross-platform path resolution issues (for example, Windows/WSL environments). + +This is a declarative extension: it contributes configuration and file paths, and VS Code (together with the GitHub Copilot extension) resolves those paths based on the selected extension host and the extension installation location; it does not implement any custom runtime fallback mechanism between workspace and bundled files. ## Prerequisites