Package Upload File Selection Internals

[stiwicourage]

Task

Implement an internal maintainability refactor focused only on the package-upload file-selection chain in NovaModuleTools.

This is not a public entry-point refactor. Do not change the public surface of Deploy-NovaPackage, Invoke-NovaCli, or any user-facing command contract unless you discover a clearly incorrect behavior that must be fixed.

Scope

Refactor only the private helper chain around:

• Get-NovaPackageUploadFileList
• Resolve-NovaPackageUploadExplicitFileList
• Resolve-NovaPackageUploadOutputFileList

The goal is to make responsibilities inside that private flow easier to understand, test, and evolve.

Why this follow-up is needed

The current upload-selection chain works, but it still mixes:

• high-level file-selection orchestration
• explicit-file resolution rules
• output-directory discovery rules
• package-type expansion decisions
• some implicit branching that is harder to reason about than it needs to be

This makes the private upload path harder to refactor safely than the newer workflow helpers in the build, test, package, and deploy flows.

Goal

After the change:

• the file-selection helpers should have clearer boundaries
• orchestration should read top-down
• specific resolution rules should be isolated in smaller private helpers where useful
• behavior must remain unchanged from a user perspective
• package-upload tests should make the private boundaries more visible

Important constraint

This work is about private internals only.

Keep these stable unless behavior is clearly wrong:

• Deploy-NovaPackage
• Invoke-NovaCli deploy
• parameter names
• error message intent
• artifact selection behavior
• upload ordering and returned object shape

Likely files to inspect first

Primary private helpers

• src/private/package/GetNovaPackageUploadFileList.ps1
• src/private/package/ResolveNovaPackageUploadExplicitFileList.ps1
• src/private/package/ResolveNovaPackageUploadOutputFileList.ps1

Closely related private helpers

• src/private/package/ResolveNovaPackageUploadExplicitFile.ps1
• src/private/package/ResolveNovaPackageUploadOutputFileSet.ps1
• src/private/package/ResolveNovaPackageUploadTypeList.ps1
• src/private/package/GetNovaPackageArtifactPatternInfo.ps1
• src/private/package/ResolveNovaPackageUploadInvocation.ps1

Public command to preserve

• src/public/DeployNovaPackage.ps1

Tests likely relevant

• tests/NovaCommandModel.PackageUpload.Tests.ps1
• tests/NovaCommandModel.PackageUpload.TestSupport.ps1
• tests/NovaCommandModel.StandaloneCli.Tests.ps1

What to do

1. Inspect the current file-selection flow end-to-end.
2. Identify where orchestration and resolution details are mixed.
3. Introduce the smallest helpful private seams needed to clarify responsibilities.
4. Keep the refactor incremental and reviewable.
5. Prefer small private helpers over broad rewrites.
6. Preserve existing behavior and result shape.
7. Update tests so the private orchestration boundaries are explicitly covered.

Design constraints

• Do not redesign the public deploy workflow.
• Do not rename public commands.
• Do not change user-facing behavior unless the current behavior is clearly wrong.
• Prefer extractions that make the code easier to read in a top-down way.
• Avoid introducing unnecessary abstraction layers.
• Stay consistent with existing PowerShell style in src/private/package/.
• Follow the repository preference for maintainable, short, simple helpers.

Testing requirements

Add or update tests to cover at least these scenarios:

1. The file-selection orchestrator still chooses explicit files when -PackagePath is provided.
2. The file-selection orchestrator still falls back to output-directory discovery when explicit files are not provided.
3. Requested package types are still resolved the same way as before.
4. Explicit-file resolution and output-file resolution remain behaviorally stable.
5. Existing deploy command behavior remains unchanged.

Validation steps

Run at least:

pwsh -NoLogo -NoProfile -Command 'Set-Location "/Users/stiwi.courage/workspace/couragedk/NovaModuleTools"; Invoke-NovaBuild'
pwsh -NoLogo -NoProfile -Command 'Set-Location "/Users/stiwi.courage/workspace/couragedk/NovaModuleTools"; Invoke-Pester ./tests/NovaCommandModel.PackageUpload.Tests.ps1 -Output Detailed'
pwsh -NoLogo -NoProfile -Command 'Set-Location "/Users/stiwi.courage/workspace/couragedk/NovaModuleTools"; Invoke-Pester ./tests/NovaCommandModel.StandaloneCli.Tests.ps1 -Output Detailed'

Also run the full project quality flow:

zsh -lc 'pwsh -NoLogo -NoProfile -File "/Users/stiwi.courage/workspace/couragedk/NovaModuleTools/run.ps1" > /tmp/novamoduletools-run-file-selection.log 2>&1; rc=$?; tail -n 80 /tmp/novamoduletools-run-file-selection.log | cat; echo "EXIT:$rc"'

And finally:

zsh -lc 'cd "/Users/stiwi.courage/workspace/couragedk/NovaModuleTools" && git --no-pager diff --check'

Documentation review requirements

After code changes, review whether these need updates:

• README.md
• CONTRIBUTING.md
• CHANGELOG.md

Because this task is internal/private refactoring only, documentation updates will usually not be needed unless behavior or contributor expectations actually change.

Definition of done

The task is done only when all of the following are true:

1. The private file-selection flow is easier to read top-down.
2. Responsibilities between orchestration and resolution are clearer.
3. No public command contract changed unintentionally.
4. Relevant tests pass.
5. Invoke-NovaBuild passes.
6. run.ps1 passes.
7. git diff --check passes.
8. The resulting touched code maintains strong Code Health.

Expected final report

When done, report back with:

1. Boundary problems addressed
2. Files changed
3. Internal layering model applied
4. Tests added or updated
5. Validation commands run and results
6. Documentation reviewed or updated
7. Any remaining follow-up ideas for the package-upload chain

[stiwicourage]

We need to review is this is still a problem, and how it should be resolved.