README.md

This directory contains PowerShell scripts for preparing, packaging, and publishing the HVE Core VS Code extension.

Architecture

The extension packaging pipeline follows a three-stage process:

1. Find-CollectionManifests.ps1 discovers collection manifests and builds a packaging matrix
2. Prepare-Extension.ps1 gathers agents, prompts, instructions, and skills, filtering by maturity and channel
3. Package-Extension.ps1 produces one .vsix per collection using vsce

All three scripts import CIHelpers.psm1 for CI platform detection. Prepare-Extension.ps1 and Package-Extension.ps1 additionally import CollectionHelpers.psm1 for YAML manifest parsing; Find-CollectionManifests.ps1 does not.

Scripts

Prepare-Extension.ps1

Prepares extension contents by auto-discovering agents, prompts, instructions, and skills from the repository.

Purpose: Gather and filter artifacts for inclusion in the extension package.

Features

• Auto-discovers .agent.md, .prompt.md, .instructions.md, and SKILL.md files
• Filters artifacts by maturity level and release channel
• Supports collection-scoped preparation
• Dry-run mode for previewing changes

Parameters

• -ChangelogPath - Path to the changelog file
• -Channel - Release channel: Stable or PreRelease
• -DryRun (switch) - Preview changes without modifying files
• -Collection - Collection name for scoped preparation

Usage

# Prepare stable channel
./scripts/extension/Prepare-Extension.ps1

# Prepare pre-release channel
./scripts/extension/Prepare-Extension.ps1 -Channel PreRelease

# Dry run to preview
./scripts/extension/Prepare-Extension.ps1 -DryRun

Package-Extension.ps1

Packages the VS Code extension into a .vsix file using vsce.

Purpose: Produce a distributable extension package from prepared contents.

Features

• Sets version from parameters or changelog
• Supports pre-release and dev patch builds
• Collection-scoped packaging
• Dry-run mode for validation

Parameters

• -Version - Explicit version string
• -DevPatchNumber - Development patch number for dev builds
• -ChangelogPath - Path to the changelog file
• -PreRelease (switch) - Mark as pre-release build
• -Collection - Collection name for scoped packaging
• -DryRun (switch) - Preview changes without producing a package

Usage

# Package the extension
./scripts/extension/Package-Extension.ps1

# Package a pre-release build
./scripts/extension/Package-Extension.ps1 -PreRelease

# Package a specific collection
./scripts/extension/Package-Extension.ps1 -Collection hve-core

Find-CollectionManifests.ps1

Discovers collection manifests for the packaging matrix.

Purpose: Build a list of collections to package based on channel and maturity rules.

Features

• Scans collections/ for .collection.yml files
• Filters collections by maturity and channel
• Outputs a matrix for CI workflow consumption

Parameters

• -Channel - Release channel filter: Stable or PreRelease
• -CollectionsDir - Path to the collections directory

Usage

# Discover stable collections
./scripts/extension/Find-CollectionManifests.ps1 -Channel Stable

# Discover all collections for pre-release
./scripts/extension/Find-CollectionManifests.ps1 -Channel PreRelease

Resolve-VsixFile.ps1

Resolves the single .vsix file within a directory.

Purpose: Return the one VSIX path in a directory, failing when zero or multiple .vsix files are present. Used by the extension-provenance.yml reusable workflow to locate the built VSIX before signing and attestation.

Parameters

• -DirectoryPath - Directory to search for a .vsix file (defaults to $env:VSIX_DIRECTORY)

Usage

# Resolve the VSIX in a directory
./scripts/extension/Resolve-VsixFile.ps1 -DirectoryPath ./extension

Select-CollectionVsix.ps1

Selects the collection-specific VSIX from a set of candidate assets.

Purpose: Pick the .vsix matching a collection ID from a directory of release assets. Used by the extension-marketplace-publish.yml reusable workflow to choose the correct collection artifact before publishing.

Parameters

• -AssetDirectory - Directory containing candidate assets (defaults to $env:ASSET_DIRECTORY)
• -CollectionId - Collection ID to match (defaults to $env:COLLECTION_ID)

Usage

# Select the VSIX for a collection
./scripts/extension/Select-CollectionVsix.ps1 -AssetDirectory ./dist -CollectionId hve-core

Export-AttestationBundle.ps1

Exports attestation files from an attestation bundle.

Purpose: Extract the Sigstore and in-toto attestation files from a bundle to local paths. Used in the provenance flow to materialize attestation artifacts for verification and release upload.

Parameters

• -BundlePath - Path to the attestation bundle (defaults to $env:BUNDLE_PATH)
• -SigstorePath - Output path for the Sigstore attestation (defaults to $env:SIGSTORE_PATH)
• -IntotoPath - Output path for the in-toto attestation (defaults to $env:INTOTO_PATH)

Usage

# Export attestation files from a bundle
./scripts/extension/Export-AttestationBundle.ps1 -BundlePath ./bundle.json -SigstorePath ./out.sigstore.json -IntotoPath ./out.intoto.jsonl

npm Scripts

npm Script	Description
extension:prepare	Prepare stable channel
extension:prepare:prerelease	Prepare pre-release channel
extension:package	Package extension
extension:package:prerelease	Package pre-release extension
package:extension	Alias for extension:package

GitHub Actions Integration

The extension packaging workflow (extension-package.yml) orchestrates all three scripts:

1. Find-CollectionManifests.ps1 produces the collection matrix
2. Prepare-Extension.ps1 runs per collection to gather artifacts
3. Package-Extension.ps1 runs per collection to produce .vsix files

See Build Workflows for pipeline details.

Related Documentation

• PACKAGING.md for packaging conventions
• Scripts README for overall script organization

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.