Execution

Author(s)

• Manuel

Tags

Execution Self-Elevation Stub PowerShell Windows

Functions

Clear-TempDirectories ConvertTo-SplatHashtable Exit-AndWaitOnUI Format-SplatHashtable Get-QuotedPath Invoke-NativeCommand Invoke-StubScript Invoke-WhenFileChanged Remove-ItemSafe Restart-SelfElevated Set-PSScriptID

PSEditions

Desktop Core

Dependencies

This module has no dependencies.

Release Notes

Execution v5.0.0+sha.7a4e9fb

## [v5.0.0] - 2026-05-05

### Added

- `Invoke-NativeCommand`: consolidated Public-API for native program
 invocations. Two parameter sets (`ByCommand` for V3-style positional+
 remaining, `ByScriptBlock` for modern `{ tool args }` calls).
 Switches: `-WorkingDirectory`, `-TimeoutSec`, `-Encoding`,
 `-IgnoreExitCode`, `-NoWait`, `-PassThru`. Honors `-WhatIf` /
 `-Confirm` via SupportsShouldProcess (ConfirmImpact = Low, does not
 prompt of its own accord). PassThru returns a PSCustomObject with
 Command, ExitCode, Output, Stdout, Stderr, Success, Duration.
- Hybrid backend: default ScriptBlock path (~5-8ms overhead),
 Process path on `-TimeoutSec` / `-Encoding` / `-NoWait` (~15-25ms
 overhead, with separate Stdout / Stderr streams via async readers
 and full Cancellation support).
- cmd.exe / sh shell-builtin detection raises a terminating error
 with a hint pointing at the correct invocation form.
- `-NoWait`: starts the process and returns immediately with a
 PSCustomObject whose `.Process` member is the live
 `[System.Diagnostics.Process]`; the other fields are `$null`.
- `build.ps1`: `-Sign` and `-Publish` switches for local sign-and-publish workflow.
 Signs both built artifacts (`Execution.psd1` and `Execution.psm1`) with a code-signing
 certificate from `Cert:\CurrentUser\My` (resolved via `-CertificateThumbprint` or
 `$env:EXECUTION_SIGN_THUMBPRINT`), timestamps via `http://timestamp.digicert.com/`,
 verifies the resulting signature, and publishes to PSGallery via `Publish-Module`.
 `-Publish` implies `-Sign`; combining `-Publish` with `-SkipTests` is rejected.
 Pre-publish guards check that the unreleased-changes section in `CHANGELOG.md` is empty
 and that the manifest version is strictly greater than the latest version on PSGallery.
- `build.ps1`: `-Version` parameter as an explicit override for the
 CHANGELOG-derived version. Hard-fails when the override does not match
 a section already in `CHANGELOG.md` (no silent fallthrough).
- `tests/Build.Tests.ps1`: regression suite asserting the built manifest
 invariants (non-placeholder `ModuleVersion`, non-empty `ReleaseNotes`,
 exactly one version section, no unreleased-section leakage).

### Changed (BREAKING)

- `FunctionsToExport`: `Start-NativeExecution`, `Invoke-Process` and
 `Test-CalledFromPrompt` removed. No aliases, no compatibility
 wrappers. All callers must migrate to `Invoke-NativeCommand`; see
 the README migration section.
- **Breaking (build layout)**: build output moves from `out/Execution/`
 to `_build/Execution/`. Leading-underscore is the convention for
 generated directories. Distribution / installation should target the
 built form (`Import-Module ./_build/Execution/Execution.psd1`);
 source-form `Import-Module ./src/Execution/Execution.psd1` still
 works for fast development iteration.
- **Breaking (manifest authoring)**: `CHANGELOG.md` is now the single
 source of truth for `ModuleVersion`, `Prerelease`, and `ReleaseNotes`.
 `build.ps1` reads the topmost `## [vX.Y.Z]` heading from
 `CHANGELOG.md`, passes the version (plus `+sha.<short-sha>` build
 metadata when run inside a git working copy) to `Build-Module
 -SemVer`, and injects the matching CHANGELOG section into the built
 manifest's `ReleaseNotes` via `Update-Metadata`. The corresponding
 fields in `src/Execution/Execution.psd1` are placeholders
 (`ModuleVersion = '0.0.0'`, empty `ReleaseNotes` / `Prerelease`);
 editing them has no effect. Removes the previous
 manifest/CHANGELOG.md double-source-of-truth and stops the built
 manifest from leaking unreleased-changes content into shipped versions.
- Build infrastructure: source layout under `src/Execution/` is
 concatenated into a single-file module artifact at
 `_build/Execution/Execution.psm1` via
 [ModuleBuilder](https://github.com/PoshCode/ModuleBuilder).
 `build.ps1` drives the build (`Install-Module ModuleBuilder` if
 missing, `Build-Module ./src/Execution/build.psd1`, run Pester against
 the built artifact).
- `Set-PSScriptID`: module-root detection now reads `$script:ModuleRoot`
 set by the loader, rather than computing it from `$PSScriptRoot` on
 every call. The built single-file form has a different
 `$PSScriptRoot` semantics from the source multi-file form, so the
 loader-set variable is the only path that works correctly in both.
 No behavior change at the public-API surface.
- CI workflow now builds via ModuleBuilder before running
 `Test-ModuleManifest`, `Import-Module`, and Pester against the built
 artifact. PSScriptAnalyzer continues to lint the source tree.

### Fixed

- v4.0.0 regression "A positional parameter cannot be found that
 accepts argument 'X'": positional + remaining-args call style
 (`Invoke-NativeCommand git fetch --all`) works again, via an
 explicit `[ValueFromRemainingArguments]` parameter that does not
 rely on the `$args` automatic that `[CmdletBinding()]` reserves.

### Removed

- `Start-NativeExecution` (replaced by `Invoke-NativeCommand`).
- `Invoke-Process` (replaced by `Invoke-NativeCommand -PassThru`).
- `Test-CalledFromPrompt` (only consumer was
 `Start-NativeExecution`; the call-stack heuristic was fragile and
 is dropped without a replacement).