feat(#104): implement package upload file selection utilities

[stiwicourage]

Summary

• Refactored the private package-upload file-selection chain so the responsibilities around explicit path handling, requested type normalization, output-directory discovery, and upload file-info shaping are clearer and easier to evolve.
• Added focused private seams in src/private/package/:
  • Get-NovaPackageUploadRequestedTypeList
  • Get-NovaPackageUploadOutputDirectoryFileList
  • Get-NovaPackageUploadFileInfo
• Updated the existing private helpers so the orchestration now reads more top-down without changing the public contract of Deploy-NovaPackage or Invoke-NovaCli deploy.
• This follow-up was needed because the upload-selection chain still mixed orchestration and resolution details, which made the private upload path harder to reason about and refactor safely.
• Follow-up reference: internal maintainability plan captured in plan.md.

Affected area

• nova CLI or command routing
• Public PowerShell cmdlet behavior
• Scaffolding or project.json handling
• Build, test, analyzer, coverage, or CI helper flow
• Package, raw upload, or package metadata workflow
• Publish, release, semantic-release, or GitHub Actions automation
• Self-update or notification preference behavior
• Contributor documentation (README.md, CONTRIBUTING.md, repository workflow docs)
• End-user docs (docs/*.html)
• Command help (docs/NovaModuleTools/en-US/*.md)
• src/resources/example/
• Dependency or manifest changes (package.json, workflow dependencies, release tooling)
• Security-sensitive change
• Documentation-only change
• Other

Other affected area details:

• Private package-upload helper layering in src/private/package/

Review guidance

• Start with src/private/package/GetNovaPackageUploadFileList.ps1 to see the high-level split between explicit package-path resolution and output-directory fallback.
• Then review these private seams in order:
  • src/private/package/GetNovaPackageUploadRequestedTypeList.ps1
  • src/private/package/ResolveNovaPackageUploadExplicitFileList.ps1
  • src/private/package/GetNovaPackageUploadOutputDirectoryFileList.ps1
  • src/private/package/ResolveNovaPackageUploadOutputFileSet.ps1
  • src/private/package/GetNovaPackageUploadFileInfo.ps1
• Review tests/NovaCommandModel.PackageUpload.Tests.ps1 for the new regression coverage that makes the internal boundaries explicit.
• Trade-off: the refactor intentionally stops at the private selection seams. It does not redesign Deploy-NovaPackage, Resolve-NovaPackageUploadInvocation, or the public CLI route because the plan constrained this work to private internals only.

Validation

• Invoke-NovaBuild
• Test-NovaBuild
• ./scripts/build/Invoke-ScriptAnalyzerCI.ps1
• ./scripts/build/ci/Invoke-NovaModuleToolsCI.ps1
• Targeted Nova workflow validated (% nova build, % nova test, % nova merge, % nova deploy,
  % nova publish,
  % nova release, % nova update, % nova notification, or % nova init as relevant)
• Docs/example only; executable validation not needed

Validation notes:

Build and focused regression coverage:
- pwsh -NoLogo -NoProfile -Command 'Invoke-NovaBuild'
  Result: passed.

- pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/NovaCommandModel.PackageUpload.Tests.ps1 -Output Detailed'
  Result: 40/40 passed.
  Included the new private-boundary tests for:
	* explicit path precedence
	* output discovery fallback
	* requested type normalization
	* output-file discovery ordering
	* shared upload file-info shaping

- pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/NovaCommandModel.StandaloneCli.Tests.ps1 -Output Detailed'
  Result: 69/69 passed.
  This preserved the public deploy/CLI behavior while the private package-upload chain changed underneath it.

Full repository 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"'
  Result: EXIT:0
  Tests Passed: 567, Failed: 0

Diff hygiene:
- git --no-pager diff --check
  Result: clean.

Maintainability safeguards:
- CodeScene pre-commit safeguard: passed
- Code Health review: 10.0 for
	* src/private/package/ResolveNovaPackageUploadExplicitFileList.ps1
	* src/private/package/ResolveNovaPackageUploadOutputFileSet.ps1
	* tests/NovaCommandModel.PackageUpload.Tests.ps1

The unchecked template boxes above were not run as separate standalone commands in this task. Their coverage came through the full repository quality flow instead.

Documentation and release follow-up

• README.md reviewed and updated if contributor workflow, architecture, CI, release, or automation changed
• CONTRIBUTING.md reviewed and updated if contribution expectations or review guidance changed
• CHANGELOG.md reviewed and updated if the change matters to users, maintainers, or contributors
• docs/NovaModuleTools/en-US/ help updated if a public command or CLI behavior changed
• docs/*.html updated if end-user workflows or examples changed
• src/resources/example/ reviewed and updated if the real-world project layout, package model, or upload workflow
  changed
• No documentation, changelog, or example updates were needed

Maintainability, compatibility, and risk

• Code Health / maintainability impact considered
• No breaking change
• Breaking change
• Security-sensitive change
• CI, workflow, or release-pipeline impact
• Dependency-review impact

Risk, rollout, or rollback notes:

Compatibility risk is low because the work stayed inside private package-upload helpers and preserved the public deploy and CLI contracts.

Rollback is straightforward:
- revert the new helper files
- restore the previous implementations in the four touched private package-upload helpers
- keep the package-upload regression tests aligned with whichever structure remains

Maintainer follow-up:
- continue adding small private seams only where orchestration and resolution become mixed again
- avoid broad abstraction layers unless another package workflow needs the same helper behavior

Important

Do not use a public pull request to disclose a vulnerability before coordinated handling.
Use the private reporting path in SECURITY.md for new security issues.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[codescene-delta-analysis]

Gates Passed
6 Quality Gates Passed

See analysis details in CodeScene

Quality Gate Profile: Pay Down Tech Debt
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!