Convert Install-SpecKitTemplate.ps1 into a PowerShell module

.gitignore

@@ -4,6 +4,9 @@
 
 # PowerShell temporary files
 *.ps1xml
+# Don't ignore module files
+!PSSpecKit/**/*.psm1
+!PSSpecKit/**/*.psd1
 *.psm1
 *.psd1
 *.psd1.updated

PSSpecKit/PSSpecKit.psd1

@@ -0,0 +1,133 @@
+#
+# Module manifest for module 'PSSpecKit'
+#
+# Generated by: PSSpecKit Contributors
+#
+# Generated on: 10/02/2025
+#
+
+@{
+
+# Script module or binary module file associated with this manifest.
+RootModule = 'PSSpecKit.psm1'
+
+# Version number of this module.
+ModuleVersion = '1.0.0'
+
+# Supported PSEditions
+# CompatiblePSEditions = @()
+
+# ID used to uniquely identify this module
+GUID = 'e99b9261-d8cf-4f06-9a6d-983a8f298378'
+
+# Author of this module
+Author = 'PSSpecKit Contributors'
+
+# Company or vendor of this module
+CompanyName = 'Unknown'
+
+# Copyright statement for this module
+Copyright = '(c) PSSpecKit Contributors. All rights reserved.'
+
+# Description of the functionality provided by this module
+Description = 'Tools for downloading and installing GitHub Spec Kit templates'
+
+# Minimum version of the PowerShell engine required by this module
+PowerShellVersion = '7.0'
+
+# Name of the PowerShell host required by this module
+# PowerShellHostName = ''
+
+# Minimum version of the PowerShell host required by this module
+# PowerShellHostVersion = ''
+
+# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
+# DotNetFrameworkVersion = ''
+
+# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
+# ClrVersion = ''
+
+# Processor architecture (None, X86, Amd64) required by this module
+# ProcessorArchitecture = ''
+
+# Modules that must be imported into the global environment prior to importing this module
+# RequiredModules = @()
+
+# Assemblies that must be loaded prior to importing this module
+# RequiredAssemblies = @()
+
+# Script files (.ps1) that are run in the caller's environment prior to importing this module.
+# ScriptsToProcess = @()
+
+# Type files (.ps1xml) to be loaded when importing this module
+# TypesToProcess = @()
+
+# Format files (.ps1xml) to be loaded when importing this module
+# FormatsToProcess = @()
+
+# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
+# NestedModules = @()
+
+# Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
+FunctionsToExport = 'Install-SpecKitTemplate', 'Test-ZipArchive', 'Expand-SafeArchive',
+               'Find-ReleaseAsset', 'Get-LatestRelease', 'Save-ReleaseAsset'
+
+# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
+CmdletsToExport = @()
+
+# Variables to export from this module
+# VariablesToExport = @()
+
+# Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
+AliasesToExport = @()
+
+# DSC resources to export from this module
+# DscResourcesToExport = @()
+
+# List of all modules packaged with this module
+# ModuleList = @()
+
+# List of all files packaged with this module
+# FileList = @()
+
+# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
+PrivateData = @{
+
+    PSData = @{
+
+        # Tags applied to this module. These help with module discovery in online galleries.
+        Tags = 'spec-kit', 'templates', 'github'
+
+        # A URL to the license for this module.
+        LicenseUri = 'https://github.com/johnmbaughman/PSSpecKit/blob/main/LICENSE'
+
+        # A URL to the main website for this project.
+        ProjectUri = 'https://github.com/johnmbaughman/PSSpecKit'
+
+        # A URL to an icon representing this module.
+        # IconUri = ''
+
+        # ReleaseNotes of this module
+        # ReleaseNotes = ''
+
+        # Prerelease string of this module
+        # Prerelease = ''
+
+        # Flag to indicate whether the module requires explicit user acceptance for install/update/save
+        # RequireLicenseAcceptance = $false
+
+        # External dependent modules of this module
+        # ExternalModuleDependencies = @()
+
+    } # End of PSData hashtable
+
+} # End of PrivateData hashtable
+
+# HelpInfo URI of this module
+# HelpInfoURI = ''
+
+# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
+# DefaultCommandPrefix = ''
+
+}
+

PSSpecKit/PSSpecKit.psm1

@@ -0,0 +1,31 @@
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# Import private functions
+$PrivateDir = Join-Path $PSScriptRoot 'Private'
+$Private = @(Get-ChildItem -Path "$PrivateDir\*.ps1" -ErrorAction SilentlyContinue)
+foreach ($import in $Private) {
+    try {
+        . $import.FullName
+    } catch {
+        Write-Error -Message "Failed to import function $($import.FullName): $_"
+    }
+}
+
+# Import public functions
+$PublicDir = Join-Path $PSScriptRoot 'Public'
+$Public = @(Get-ChildItem -Path "$PublicDir\*.ps1" -ErrorAction SilentlyContinue)
+foreach ($import in $Public) {
+    try {
+        . $import.FullName
+    } catch {
+        Write-Error -Message "Failed to import function $($import.FullName): $_"
+    }
+}
+
+# Export public functions and private functions for testing
+# Private functions are marked as internal and should not be used directly by end users
+$AllFunctions = @($Public.BaseName) + @($Private.BaseName)
+if ($AllFunctions) {
+    Export-ModuleMember -Function $AllFunctions
+}

PSSpecKit/Private/Expand-SafeArchive.ps1

@@ -0,0 +1,36 @@
+function Expand-SafeArchive {
+    param([string]$ZipPath, [string]$TargetPath, [switch]$Force)
+    # Extract into a temporary extraction directory located next to the zip when possible.
+    # This keeps the downloaded zip in the parent work directory and allows us to remove only the extraction temp.
+    $zipParent = Split-Path -Path $ZipPath -Parent
+    if (-not $zipParent) { $zipParent = [System.IO.Path]::GetTempPath() }
+    $tempExtract = Join-Path -Path $zipParent -ChildPath ([System.Guid]::NewGuid().ToString())
+    New-Item -Path $tempExtract -ItemType Directory | Out-Null
+    try {
+        Add-Type -AssemblyName System.IO.Compression.FileSystem
+        [System.IO.Compression.ZipFile]::ExtractToDirectory($ZipPath, $tempExtract)
+        # Move files from temp to target
+        Get-ChildItem -Path $tempExtract -Recurse | ForEach-Object {
+            $rel = $_.FullName.Substring($tempExtract.Length).TrimStart([System.IO.Path]::DirectorySeparatorChar)
+            $dest = Join-Path $TargetPath $rel
+            if ($_.PSIsContainer) {
+                if (-not (Test-Path $dest)) { New-Item -Path $dest -ItemType Directory | Out-Null }
+            } else {
+                $destDir = Split-Path -Path $dest -Parent
+                if (-not (Test-Path $destDir)) { New-Item -Path $destDir -ItemType Directory | Out-Null }
+                if ((Test-Path $dest) -and (-not $Force)) {
+                    Write-Warn "Skipping existing file: $dest"
+                } else {
+                    Move-Item -Path $_.FullName -Destination $dest -Force:$true
+                }
+            }
+        }
+        return $true
+    } catch {
+        Write-Err "Extraction failed: $_"
+        return $false
+    } finally {
+        # Remove only the extraction temp directory. Do NOT remove the zip or its parent work directory.
+        if (Test-Path $tempExtract) { Remove-Item -Path $tempExtract -Recurse -Force }
+    }
+}

PSSpecKit/Private/Find-ReleaseAsset.ps1

@@ -0,0 +1,15 @@
+function Find-ReleaseAsset {
+    param(
+        $Release,
+        [string]$Agent,
+        [string]$Shell
+    )
+    $pattern = "spec-kit-template-{0}-{1}-v" -f ($Agent -replace '[^a-zA-Z0-9_-]',''), $Shell
+    # Try find asset containing pattern
+    foreach ($asset in $Release.assets) {
+        if ($asset.name -like "*{0}*.zip" -f $pattern) {
+            return $asset
+        }
+    }
+    return $null
+}

PSSpecKit/Private/Get-GitHubApiHeader.ps1

@@ -0,0 +1,9 @@
+function Get-GitHubApiHeader {
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param()
+    $headers = @{}
+    if ($env:GITHUB_TOKEN) { $headers['Authorization'] = "token $($env:GITHUB_TOKEN)" }
+    $headers['User-Agent'] = 'spec-kit-downloader'
+    return $headers
+}

PSSpecKit/Private/Get-LatestRelease.ps1

@@ -0,0 +1,14 @@
+function Get-LatestRelease {
+    param([string]$Owner = 'github', [string]$Repo = 'spec-kit')
+    $url = "https://api.github.com/repos/$Owner/$Repo/releases"
+    $headers = Get-GitHubApiHeader
+    $releases = Invoke-WithRetry -ScriptBlock { Invoke-RestMethod -Uri $url -Headers $headers -UseBasicParsing } -Retries $Retry
+    if (-not $releases) { throw 'No releases found' }
+    # Sort by semantic version if possible, fallback to published_at
+    try {
+        $sorted = $releases | Sort-Object { [Version]($_.tag_name.TrimStart('v')) } -Descending
+    } catch {
+        $sorted = $releases | Sort-Object published_at -Descending
+    }
+    return $sorted[0]
+}

PSSpecKit/Private/Invoke-WithRetry.ps1

@@ -0,0 +1,18 @@
+function Invoke-WithRetry {
+    param(
+        [scriptblock]$ScriptBlock,
+        [int]$Retries = 3
+    )
+    $attempt = 0
+    while ($true) {
+        try {
+            return & $ScriptBlock
+        } catch {
+            $attempt++
+            if ($attempt -ge $Retries) { throw }
+            $delay = [math]::Pow(2, $attempt)
+            Write-Warn "Attempt $attempt failed. Retrying in ${delay}s..."
+            Start-Sleep -Seconds $delay
+        }
+    }
+}

PSSpecKit/Private/Save-ReleaseAsset.ps1

@@ -0,0 +1,21 @@
+function Save-ReleaseAsset {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory=$true)] $Asset,
+        [string]$OutPath
+    )
+    $headers = Get-GitHubApiHeader
+    if (-not $OutPath) {
+        # Create a dedicated temp work directory for this download and keep the zip there
+        $workDir = Join-Path -Path ([System.IO.Path]::GetTempPath()) -ChildPath ([System.Guid]::NewGuid().ToString())
+        New-Item -Path $workDir -ItemType Directory -Force | Out-Null
+        $OutPath = Join-Path -Path $workDir -ChildPath $Asset.name
+    }
+    $url = $Asset.browser_download_url
+    Write-Info "Downloading $($Asset.name) from $url to $OutPath"
+    # Ensure the parent directory exists when OutPath is provided
+    $parent = Split-Path -Path $OutPath -Parent
+    if ($parent -and -not (Test-Path $parent)) { New-Item -Path $parent -ItemType Directory | Out-Null }
+    Invoke-WithRetry -ScriptBlock { Invoke-WebRequest -Uri $url -Headers $headers -OutFile $OutPath -UseBasicParsing } -Retries $Retry
+    return $OutPath
+}

PSSpecKit/Private/Test-ZipArchive.ps1

@@ -0,0 +1,10 @@
+function Test-ZipArchive {
+    param([string]$ZipPath)
+    try {
+        [System.IO.Compression.ZipFile]::OpenRead($ZipPath).Dispose()
+        return $true
+    } catch {
+        Write-Err "ZIP validation failed: $_"
+        return $false
+    }
+}

PSSpecKit/Private/Write-Err.ps1

@@ -0,0 +1,4 @@
+function Write-Err {
+    param([string]$Message)
+    Write-Information $Message -Tags Error
+}

PSSpecKit/Private/Write-Info.ps1

@@ -0,0 +1,4 @@
+function Write-Info {
+    param([string]$Message)
+    Write-Information $Message -Tags Info
+}

PSSpecKit/Private/Write-Warn.ps1

@@ -0,0 +1,4 @@
+function Write-Warn {
+    param([string]$Message)
+    Write-Verbose $Message
+}