microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
scripts/extension/README.md
162lines · modecode
| 1 | --- |
| 2 | title: Extension Scripts |
| 3 | description: PowerShell scripts for VS Code extension preparation, packaging, and collection discovery |
| 4 | author: HVE Core Team |
| 5 | ms.date: 2025-11-05 |
| 6 | ms.topic: reference |
| 7 | keywords: |
| 8 | - powershell |
| 9 | - vscode |
| 10 | - extension |
| 11 | - packaging |
| 12 | - vsix |
| 13 | estimated_reading_time: 5 |
| 14 | --- |
| 15 | |
| 16 | This directory contains PowerShell scripts for preparing, packaging, and |
| 17 | publishing the HVE Core VS Code extension. |
| 18 | |
| 19 | ## Architecture |
| 20 | |
| 21 | The extension packaging pipeline follows a three-stage process: |
| 22 | |
| 23 | 1. `Find-CollectionManifests.ps1` discovers collection manifests and builds a |
| 24 | packaging matrix |
| 25 | 2. `Prepare-Extension.ps1` gathers agents, prompts, instructions, and skills, |
| 26 | filtering by maturity and channel |
| 27 | 3. `Package-Extension.ps1` produces one `.vsix` per collection using `vsce` |
| 28 | |
| 29 | All three scripts import `CIHelpers.psm1` and `CollectionHelpers.psm1` for CI |
| 30 | platform detection and YAML manifest parsing. |
| 31 | |
| 32 | ## Scripts |
| 33 | |
| 34 | ### `Prepare-Extension.ps1` |
| 35 | |
| 36 | Prepares extension contents by auto-discovering agents, prompts, instructions, |
| 37 | and skills from the repository. |
| 38 | |
| 39 | Purpose: Gather and filter artifacts for inclusion in the extension package. |
| 40 | |
| 41 | #### Features |
| 42 | |
| 43 | * Auto-discovers `.agent.md`, `.prompt.md`, `.instructions.md`, and `SKILL.md` |
| 44 | files |
| 45 | * Filters artifacts by maturity level and release channel |
| 46 | * Supports collection-scoped preparation |
| 47 | * Dry-run mode for previewing changes |
| 48 | |
| 49 | #### Parameters |
| 50 | |
| 51 | * `-ChangelogPath` - Path to the changelog file |
| 52 | * `-Channel` - Release channel: `Stable` or `PreRelease` |
| 53 | * `-DryRun` (switch) - Preview changes without modifying files |
| 54 | * `-Collection` - Collection name for scoped preparation |
| 55 | |
| 56 | #### Usage |
| 57 | |
| 58 | ```powershell |
| 59 | # Prepare stable channel |
| 60 | ./scripts/extension/Prepare-Extension.ps1 |
| 61 | |
| 62 | # Prepare pre-release channel |
| 63 | ./scripts/extension/Prepare-Extension.ps1 -Channel PreRelease |
| 64 | |
| 65 | # Dry run to preview |
| 66 | ./scripts/extension/Prepare-Extension.ps1 -DryRun |
| 67 | ``` |
| 68 | |
| 69 | ### `Package-Extension.ps1` |
| 70 | |
| 71 | Packages the VS Code extension into a `.vsix` file using `vsce`. |
| 72 | |
| 73 | Purpose: Produce a distributable extension package from prepared contents. |
| 74 | |
| 75 | #### Features |
| 76 | |
| 77 | * Sets version from parameters or changelog |
| 78 | * Supports pre-release and dev patch builds |
| 79 | * Collection-scoped packaging |
| 80 | * Dry-run mode for validation |
| 81 | |
| 82 | #### Parameters |
| 83 | |
| 84 | * `-Version` - Explicit version string |
| 85 | * `-DevPatchNumber` - Development patch number for dev builds |
| 86 | * `-ChangelogPath` - Path to the changelog file |
| 87 | * `-PreRelease` (switch) - Mark as pre-release build |
| 88 | * `-Collection` - Collection name for scoped packaging |
| 89 | * `-DryRun` (switch) - Preview changes without producing a package |
| 90 | |
| 91 | #### Usage |
| 92 | |
| 93 | ```powershell |
| 94 | # Package the extension |
| 95 | ./scripts/extension/Package-Extension.ps1 |
| 96 | |
| 97 | # Package a pre-release build |
| 98 | ./scripts/extension/Package-Extension.ps1 -PreRelease |
| 99 | |
| 100 | # Package a specific collection |
| 101 | ./scripts/extension/Package-Extension.ps1 -Collection hve-core |
| 102 | ``` |
| 103 | |
| 104 | ### `Find-CollectionManifests.ps1` |
| 105 | |
| 106 | Discovers collection manifests for the packaging matrix. |
| 107 | |
| 108 | Purpose: Build a list of collections to package based on channel and |
| 109 | maturity rules. |
| 110 | |
| 111 | #### Features |
| 112 | |
| 113 | * Scans `collections/` for `.collection.yml` files |
| 114 | * Filters collections by maturity and channel |
| 115 | * Outputs a matrix for CI workflow consumption |
| 116 | |
| 117 | #### Parameters |
| 118 | |
| 119 | * `-Channel` - Release channel filter: `Stable` or `PreRelease` |
| 120 | * `-CollectionsDir` - Path to the collections directory |
| 121 | |
| 122 | #### Usage |
| 123 | |
| 124 | ```powershell |
| 125 | # Discover stable collections |
| 126 | ./scripts/extension/Find-CollectionManifests.ps1 -Channel Stable |
| 127 | |
| 128 | # Discover all collections for pre-release |
| 129 | ./scripts/extension/Find-CollectionManifests.ps1 -Channel PreRelease |
| 130 | ``` |
| 131 | |
| 132 | ## npm Scripts |
| 133 | |
| 134 | | npm Script | Description | |
| 135 | |--------------------------------|-------------------------------| |
| 136 | | `extension:prepare` | Prepare stable channel | |
| 137 | | `extension:prepare:prerelease` | Prepare pre-release channel | |
| 138 | | `extension:package` | Package extension | |
| 139 | | `extension:package:prerelease` | Package pre-release extension | |
| 140 | | `package:extension` | Alias for `extension:package` | |
| 141 | |
| 142 | ## GitHub Actions Integration |
| 143 | |
| 144 | The extension packaging workflow (`extension-package.yml`) orchestrates all |
| 145 | three scripts: |
| 146 | |
| 147 | 1. `Find-CollectionManifests.ps1` produces the collection matrix |
| 148 | 2. `Prepare-Extension.ps1` runs per collection to gather artifacts |
| 149 | 3. `Package-Extension.ps1` runs per collection to produce `.vsix` files |
| 150 | |
| 151 | See [Build Workflows](../../docs/architecture/workflows.md) for pipeline |
| 152 | details. |
| 153 | |
| 154 | ## Related Documentation |
| 155 | |
| 156 | * [PACKAGING.md](../../extension/PACKAGING.md) for packaging conventions |
| 157 | * [Scripts README](../README.md) for overall script organization |
| 158 | |
| 159 | <!-- markdownlint-disable MD036 --> |
| 160 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 161 | then carefully refined by our team of discerning human reviewers.* |
| 162 | <!-- markdownlint-enable MD036 --> |
| 163 | |