CI: Install the built module from a local repository to verify install-time dependency behaviour

[tablackburn]

CI builds this module on every push and has never once installed it. The v1.0.0 roadmap (#120) records why that matters: several breaks this cycle are install-time — RequiredModules now demands psake 5.0.4 and Pester 6.0.0, and PlatyPS was removed from it — and none of them can be observed from a build. Until now the plan covered that gap with a 1.0.0-rc1 gallery prerelease and a seven-day soak. That prerelease has been dropped (decision recorded on #120, 2026-09-04), and this test is the safeguard that replaces it.

What the test does

Publish the built module into a temporary file-share repository alongside mirrored copies of its three dependencies, then in a fresh process whose PSModulePath holds only an empty directory, Save-Module it from that repository and import the result. That exercises, without touching the PowerShell Gallery or the machine's module store:

• every RequiredModules entry is declared correctly and resolves
• the generated nuspec's <dependencies> match the manifest — verified today to be exactly BuildHelpers 2.0.16, Pester 6.0.0, psake 5.0.4, with no PlatyPS
• the saved module imports its required modules from the isolated path and exports its commands
• on both PowerShell 7 and Windows PowerShell 5.1

Prototyped and measured, 2026-09-04

Both editions: Save-Module succeeded, all three dependencies resolved at the declared versions, the module imported and exported 12 functions plus the PowerShellBuild.IB.Tasks alias. The negative control — manifest edited to require psake 99.0.0 — failed on both editions with ProviderFailToDownloadFile and nothing on disk, so the test can fail.

Two traps the prototype hit that the implementation must avoid:

1. Save-Module restores the default PSModulePath when it returns. The first attempt imported the machine's installed 0.8.2 and loaded Pester 6.1.0 instead of the saved 6.0.0. Re-assert the isolated path after Save-Module and import by explicit manifest path.
2. Everything is already installed on a developer machine. Without the empty-PSModulePath isolation the test is vacuous.

On Windows PowerShell 5.1, stage PowerShellGet 2.2.5 from the WindowsPowerShell module path; the PowerShell 7 copy's PackageManagement ships coreclr binaries only and fails to load there.

The re-runnable prototype, including the negative control, is at scratchpad/local-repo-test/Invoke-LocalRepoProbe.ps1 on the maintainer's machine and should be the starting point.

What it does not cover, deliberately

A local repository is a snapshot: it does not resolve against the live dependency graph (newest-satisfying Pester 6.x rather than the 6.0.0 floor), transitive dependency drift, gallery ingestion, or real network transport on 5.1. Also note that with PowerShellGet 2.x a file-share repository gets prerelease gating wrong — Find-Module without -AllowPrerelease returns a prerelease — so this test must not be used to verify prerelease behaviour; PSResourceGet against the same folder gates correctly.

One thing worth recording because it changed the release decision: Publish-Module itself refuses to publish a package whose RequiredModules cannot be resolved on the destination repository (UnableToResolveModuleDependency), and the same code path runs against PSGallery. A 1.0.0 with an unsatisfiable dependency fails at publish rather than reaching consumers.

Options

1. A repository-local workflow that runs on every push, alongside the shared ModuleCI.yml call. Simplest; covers this repository only.
2. Add it to the shared psake/.github workflow as an opt-in step. More work; benefits psake too.
3. Run it as a documented pre-flight step on Release: bump to 1.0.0 and publish to PSGallery #160 only. Cheapest, but the coverage is lost the day after the release.

Option 1 is the straightforward first step and can be promoted to 2 later.

Done when

The test runs in CI on both editions, passes against main, and has been shown to fail against a manifest with an unsatisfiable dependency.