Update macOS packaging to use Xcode command line tools instead of fpm

Summary

This PR replaces the Ruby gem fpm (Effing Package Management) with native macOS packaging tools (pkgbuild and productbuild) from Xcode Command Line Tools for creating macOS PowerShell packages.

Plan

• Explore the current implementation to understand how fpm is used
• Understand macOS packaging tools (pkgbuild, productbuild)
• Create new functions to build macOS packages using native tools
• Replace fpm-based implementation for macOS (osxpkg type)
• Update Test-Dependencies to check for pkgbuild/productbuild on macOS
• Remove fpm workarounds and hacks
• Fix symlink handling to match fpm behavior
• Update documentation to reflect the changes
• Review and validate changes
• Run security checks (CodeQL - no issues found)
• Add package creation and validation to macOS CI workflow
• Combine build and package steps in same task to preserve build state
• Convert package validation to Pester test
• Add -SkipReleaseChecks to avoid repo path validation in CI
• Use process-pester-results action for proper test result publishing
• Fix symlink creation to recreate instead of copy temp files
• Use Pester TestDrive for temporary test directories
• Improve verbose logging and path construction in test
• Refactor to reuse New-MacOsDistributionPackage function
• Use Start-NativeExecution for native command execution
• Add Copilot instructions for Start-NativeExecution usage
• Configure public NuGet feeds for CI environment
• Apply Start-NativeExecution consistently for all native commands

Changes Made

New Function: New-MacOSPackage (tools/packaging/packaging.psm1)

Created a comprehensive function that uses native macOS packaging tools:

• Uses pkgbuild via Start-NativeExecution to create a component package from the staged files
• Calls New-MacOsDistributionPackage to create the final distribution package with proper metadata
• Handles complete file layout including binaries, modules, man pages, symlinks, launcher app, and post-install scripts
• Recreates symlinks in package root by reading target from temp symlinks
• Uses Start-NativeExecution for all native commands (chmod, pkgbuild)

Refactored New-MacOsDistributionPackage Function

Modernized and generalized this function to work with component packages from the native tools:

• Updated parameters to accept a component package instead of FPM package
• Added explicit parameters for package name, version, output directory, and package identifier
• Uses productbuild via Start-NativeExecution with proper distribution XML
• Handles background image and resources
• Supports both x86_64 and arm64 architectures
• Now reused by New-MacOSPackage to avoid code duplication

Updated Packaging Module Initialization

• Dot-sourced startNativeExecution.ps1 to make Start-NativeExecution available
• Updated all native command invocations to use Start-NativeExecution with proper error handling
• Consistently applied Start-NativeExecution for chmod, pkgbuild, productbuild, and pkgutil commands
• Improved error handling and diagnostics for packaging operations

Updated New-UnixPackage Function

• Added conditional logic to call New-MacOSPackage for osxpkg type packages
• Removed fpm symlink workaround hack - no longer needed with native tools
• Removed call to New-MacOsDistributionPackage since the new implementation creates distribution packages directly
• Simplified cleanup logic in finally block

Updated Test-Dependencies Function

• Added checks for pkgbuild and productbuild on macOS
• Kept fpm dependency check only for Debian-based systems
• Updated comments to reflect tool usage by platform

Updated Documentation

• docs/maintainers/releasing.md: Clarified that different packaging tools are used for different platforms
• .github/instructions/start-native-execution.instructions.md: Comprehensive guide on using Start-NativeExecution for native command execution in packaging scripts
• .github/instructions/build-configuration-guide.instructions.md: Added comprehensive documentation about Switch-PSNugetConfig usage, including when and why to use public feeds in CI/CD environments

Enhanced macOS CI Workflow (.github/workflows/macos-ci.yml)

• Added Switch-PSNugetConfig -Source Public to use public NuGet feeds (required for CI environments)
• Combined build and package steps in single task to preserve PowerShell build state (PSOptions)
• Added -SkipReleaseChecks flag to Start-PSPackage to bypass repo path validation in CI
• Replaced inline validation script with comprehensive Pester test for package validation
• Configured Pester to output NUnitXml format test results
• Integrated with .github/actions/test/process-pester-results action for proper test result publishing and aggregation
• Added artifact upload for created packages

New Pester Test (tools/packaging/releaseTests/macOSPackage.tests.ps1)

Created comprehensive Pester-based validation test:

• Tests package existence and structure
• Validates required files (pwsh executable, symlinks, man pages, launcher app)
• Verifies PowerShell binary has executable permissions
• Validates launcher application bundle structure
• Uses Start-NativeExecution for pkgutil command to ensure proper error handling
• Provides detailed test output with clear assertions
• Follows existing test patterns in the repository (similar to sbom.tests.ps1)
• Outputs results in NUnitXml format for CI processing
• Uses Pester TestDrive for temporary directories, allowing pkgutil to create directories as it expects
• Improved verbose logging to show full path of component package being processed
• Uses Join-Path for proper path construction

Key Benefits

1. No Ruby Dependency: Eliminates the need for Ruby and the fpm gem on macOS
2. Native Tools: Uses Apple's official packaging tools that come with Xcode Command Line Tools
3. Better Integration: Native tools are better maintained and aligned with macOS standards
4. Cleaner Code: Removed workarounds and hacks needed for fpm quirks, and refactored to reuse existing functions
5. Better Maintainability: Uses Apple-supported tools that are kept up-to-date with macOS releases
6. CI Validation: Package creation and contents are now validated in CI with proper Pester tests
7. Better Testing: Package validation now uses standard Pester test framework for consistency and maintainability
8. Proper Test Reporting: Uses the standard process-pester-results action for consistent test result publishing across the repository
9. Code Reusability: Refactored New-MacOsDistributionPackage to be reusable by both legacy and new packaging approaches
10. Consistent Error Handling: Uses Start-NativeExecution for all native command execution with proper error handling and diagnostics
11. CI-Ready Configuration: Properly configured to use public NuGet feeds for CI/CD environments

Testing

The macOS CI workflow now includes comprehensive testing that:

• Switches to public NuGet feeds before building (via Switch-PSNugetConfig -Source Public)
• Builds PowerShell from source
• Creates the macOS package using the new implementation in the same task (preserving build state)
• Uses -SkipReleaseChecks to bypass repo path validation (CI repos are not at /PowerShell)
• Properly handles symlink creation by reading the target from temp symlinks and recreating them in the package
• Runs Pester tests (tools/packaging/releaseTests/macOSPackage.tests.ps1) using TestDrive for temporary directories
• Lets pkgutil create the expand directory itself (as expected by the tool)
• Saves test results in NUnitXml format to ${{ runner.workspace }}/testResults
• Uses .github/actions/test/process-pester-results action to aggregate, summarize, and upload test results
• Uploads the package as an artifact for inspection

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.