MegaBites-AI/Windows-powershell

1---2applyTo:3  - "tools/ci.psm1"4  - "build.psm1"5  - "tools/packaging/**/*.psm1"6  - ".github/**/*.yml"7  - ".github/**/*.yaml"8---9 10# Guidelines for PowerShell Code Organization11 12## When to Move Code from YAML to PowerShell Modules13 14PowerShell code in GitHub Actions YAML files should be kept minimal. Move code to a module when:15 16### Size Threshold17- **More than ~30 lines** of PowerShell in a YAML file step18- **Any use of .NET types** like `[regex]`, `[System.IO.Path]`, etc.19- **Complex logic** requiring multiple nested loops or conditionals20- **Reusable functionality** that might be needed elsewhere21 22### Indicators to Move Code231. Using .NET type accelerators (`[regex]`, `[PSCustomObject]`, etc.)242. Complex string manipulation or parsing253. File system operations beyond basic reads/writes264. Logic that would benefit from unit testing275. Code that's difficult to read/maintain in YAML format28 29## Which Module to Use30 31### ci.psm1 (`tools/ci.psm1`)32**Purpose**: CI/CD-specific operations and workflows33 34**Use for**:35- Build orchestration (invoking builds, tests, packaging)36- CI environment setup and configuration37- Test execution and result processing38- Artifact handling and publishing39- CI-specific validations and checks40- Environment variable management for CI41 42**Examples**:43- `Invoke-CIBuild` - Orchestrates build process44- `Invoke-CITest` - Runs Pester tests45- `Test-MergeConflictMarker` - Validates files for conflicts46- `Set-BuildVariable` - Manages CI variables47 48**When NOT to use**:49- Core build operations (use build.psm1)50- Package creation logic (use packaging.psm1)51- Platform-specific build steps52 53### build.psm1 (`build.psm1`)54**Purpose**: Core build operations and utilities55 56**Use for**:57- Compiling source code58- Resource generation59- Build configuration management60- Core build utilities (New-PSOptions, Get-PSOutput, etc.)61- Bootstrap operations62- Cross-platform build helpers63 64**Examples**:65- `Start-PSBuild` - Main build function66- `Start-PSBootstrap` - Bootstrap dependencies67- `New-PSOptions` - Create build configuration68- `Start-ResGen` - Generate resources69 70**When NOT to use**:71- CI workflow orchestration (use ci.psm1)72- Package creation (use packaging.psm1)73- Test execution74 75### packaging.psm1 (`tools/packaging/packaging.psm1`)76**Purpose**: Package creation and distribution77 78**Use for**:79- Creating distribution packages (MSI, RPM, DEB, etc.)80- Package-specific metadata generation81- Package signing operations82- Platform-specific packaging logic83 84**Examples**:85- `Start-PSPackage` - Create packages86- `New-MSIXPackage` - Create Windows MSIX87- `New-DotnetSdkContainerFxdPackage` - Create container packages88 89**When NOT to use**:90- Building binaries (use build.psm1)91- Running tests (use ci.psm1)92- General utilities93 94## Best Practices95 96### Keep YAML Minimal97```yaml98# ❌ Bad - too much logic in YAML99- name: Check files100  shell: pwsh101  run: |102    $files = Get-ChildItem -Recurse103    foreach ($file in $files) {104      $content = Get-Content $file -Raw105      if ($content -match $pattern) {106        # ... complex processing ...107      }108    }109 110# ✅ Good - call function from module111- name: Check files112  shell: pwsh113  run: |114    Import-Module ./tools/ci.psm1115    Test-SomeCondition -Path ${{ github.workspace }}116```117 118### Document Functions119Always include comment-based help for functions:120```powershell121function Test-MyFunction122{123    <#124    .SYNOPSIS125        Brief description126    .DESCRIPTION127        Detailed description128    .PARAMETER ParameterName129        Parameter description130    .EXAMPLE131        Test-MyFunction -ParameterName Value132    #>133    [CmdletBinding()]134    param(135        [Parameter(Mandatory)]136        [string] $ParameterName137    )138    # Implementation139}140```141 142### Error Handling143Use proper error handling in modules:144```powershell145try {146    # Operation147}148catch {149    Write-Error "Detailed error message: $_"150    throw151}152```153 154### Verbose Output155Use `Write-Verbose` for debugging information:156```powershell157Write-Verbose "Processing file: $filePath"158```159 160## Module Dependencies161 162- **ci.psm1** imports both `build.psm1` and `packaging.psm1`163- **build.psm1** is standalone (minimal dependencies)164- **packaging.psm1** imports `build.psm1`165 166When adding new functions, consider these import relationships to avoid circular dependencies.167 168## Testing Modules169 170Functions in modules should be testable:171```powershell172# Test locally173Import-Module ./tools/ci.psm1 -Force174Test-MyFunction -Parameter Value175 176# Can be unit tested with Pester177Describe "Test-MyFunction" {178    It "Should return expected result" {179        # Test implementation180    }181}182```183 184## Migration Checklist185 186When moving code from YAML to a module:187 1881. ✅ Determine which module is appropriate (ci, build, or packaging)1892. ✅ Create function with proper parameter validation1903. ✅ Add comment-based help documentation1914. ✅ Use `[CmdletBinding()]` for advanced function features1925. ✅ Include error handling1936. ✅ Add verbose output for debugging1947. ✅ Test the function independently1958. ✅ Update YAML to call the new function1969. ✅ Verify the workflow still works end-to-end197 198## References199 200- PowerShell Advanced Functions: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced201- Comment-Based Help: https://learn.microsoft.com/powershell/scripting/developer/help/writing-help-for-windows-powershell-scripts-and-functions202