Copilot instructions

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 Organization
11 
12## When to Move Code from YAML to PowerShell Modules
13 
14PowerShell code in GitHub Actions YAML files should be kept minimal. Move code to a module when:
15 
16### Size Threshold
17- **More than ~30 lines** of PowerShell in a YAML file step
18- **Any use of .NET types** like `[regex]`, `[System.IO.Path]`, etc.
19- **Complex logic** requiring multiple nested loops or conditionals
20- **Reusable functionality** that might be needed elsewhere
21 
22### Indicators to Move Code
231. Using .NET type accelerators (`[regex]`, `[PSCustomObject]`, etc.)
242. Complex string manipulation or parsing
253. File system operations beyond basic reads/writes
264. Logic that would benefit from unit testing
275. Code that's difficult to read/maintain in YAML format
28 
29## Which Module to Use
30 
31### ci.psm1 (`tools/ci.psm1`)
32**Purpose**: CI/CD-specific operations and workflows
33 
34**Use for**:
35- Build orchestration (invoking builds, tests, packaging)
36- CI environment setup and configuration
37- Test execution and result processing
38- Artifact handling and publishing
39- CI-specific validations and checks
40- Environment variable management for CI
41 
42**Examples**:
43- `Invoke-CIBuild` - Orchestrates build process
44- `Invoke-CITest` - Runs Pester tests
45- `Test-MergeConflictMarker` - Validates files for conflicts
46- `Set-BuildVariable` - Manages CI variables
47 
48**When NOT to use**:
49- Core build operations (use build.psm1)
50- Package creation logic (use packaging.psm1)
51- Platform-specific build steps
52 
53### build.psm1 (`build.psm1`)
54**Purpose**: Core build operations and utilities
55 
56**Use for**:
57- Compiling source code
58- Resource generation
59- Build configuration management
60- Core build utilities (New-PSOptions, Get-PSOutput, etc.)
61- Bootstrap operations
62- Cross-platform build helpers
63 
64**Examples**:
65- `Start-PSBuild` - Main build function
66- `Start-PSBootstrap` - Bootstrap dependencies
67- `New-PSOptions` - Create build configuration
68- `Start-ResGen` - Generate resources
69 
70**When NOT to use**:
71- CI workflow orchestration (use ci.psm1)
72- Package creation (use packaging.psm1)
73- Test execution
74 
75### packaging.psm1 (`tools/packaging/packaging.psm1`)
76**Purpose**: Package creation and distribution
77 
78**Use for**:
79- Creating distribution packages (MSI, RPM, DEB, etc.)
80- Package-specific metadata generation
81- Package signing operations
82- Platform-specific packaging logic
83 
84**Examples**:
85- `Start-PSPackage` - Create packages
86- `New-MSIXPackage` - Create Windows MSIX
87- `New-DotnetSdkContainerFxdPackage` - Create container packages
88 
89**When NOT to use**:
90- Building binaries (use build.psm1)
91- Running tests (use ci.psm1)
92- General utilities
93 
94## Best Practices
95 
96### Keep YAML Minimal
97```yaml
98# ❌ Bad - too much logic in YAML
99- name: Check files
100  shell: pwsh
101  run: |
102    $files = Get-ChildItem -Recurse
103    foreach ($file in $files) {
104      $content = Get-Content $file -Raw
105      if ($content -match $pattern) {
106        # ... complex processing ...
107      }
108    }
109 
110# ✅ Good - call function from module
111- name: Check files
112  shell: pwsh
113  run: |
114    Import-Module ./tools/ci.psm1
115    Test-SomeCondition -Path ${{ github.workspace }}
116```
117 
118### Document Functions
119Always include comment-based help for functions:
120```powershell
121function Test-MyFunction
122{
123    <#
124    .SYNOPSIS
125        Brief description
126    .DESCRIPTION
127        Detailed description
128    .PARAMETER ParameterName
129        Parameter description
130    .EXAMPLE
131        Test-MyFunction -ParameterName Value
132    #>
133    [CmdletBinding()]
134    param(
135        [Parameter(Mandatory)]
136        [string] $ParameterName
137    )
138    # Implementation
139}
140```
141 
142### Error Handling
143Use proper error handling in modules:
144```powershell
145try {
146    # Operation
147}
148catch {
149    Write-Error "Detailed error message: $_"
150    throw
151}
152```
153 
154### Verbose Output
155Use `Write-Verbose` for debugging information:
156```powershell
157Write-Verbose "Processing file: $filePath"
158```
159 
160## Module Dependencies
161 
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 Modules
169 
170Functions in modules should be testable:
171```powershell
172# Test locally
173Import-Module ./tools/ci.psm1 -Force
174Test-MyFunction -Parameter Value
175 
176# Can be unit tested with Pester
177Describe "Test-MyFunction" {
178    It "Should return expected result" {
179        # Test implementation
180    }
181}
182```
183 
184## Migration Checklist
185 
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 validation
1903. ✅ Add comment-based help documentation
1914. ✅ Use `[CmdletBinding()]` for advanced function features
1925. ✅ Include error handling
1936. ✅ Add verbose output for debugging
1947. ✅ Test the function independently
1958. ✅ Update YAML to call the new function
1969. ✅ Verify the workflow still works end-to-end
197 
198## References
199 
200- PowerShell Advanced Functions: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced
201- Comment-Based Help: https://learn.microsoft.com/powershell/scripting/developer/help/writing-help-for-windows-powershell-scripts-and-functions
202