Extract clearer adapters around external dependencies such as git, HTTP/package upload, publishing, filesystem, and environment access.

[stiwicourage]

Task

Implement a maintainability improvement: extract clearer adapters around external dependencies such as git, HTTP/package upload, publishing, filesystem, and environment access.

The goal is to reduce direct coupling between workflow logic and external systems so the code becomes easier to test, reason about, and evolve.

Why this follow-up is needed

NovaModuleTools interacts with several external systems:

• git
• filesystem
• environment variables
• package upload endpoints / HTTP-like targets
• PowerShell publishing commands / repositories

Those interactions are necessary, but maintainability improves when they are isolated behind smaller, testable adapters instead of being spread across workflow code.

Goal

After this change:

• external system access should be more explicit and isolated
• workflow logic should depend less on raw shell or direct external calls
• tests should require fewer broad mocks of unrelated behavior
• future changes to external integrations should have clearer change points

Likely files to inspect first

Git-related flows

• src/private/release/GetGitCommitMessagesForVersionBump.ps1
• src/private/release/GetNovaVersionLabelForBump.ps1
• other release/git helpers under src/private/release/

Package upload / HTTP-related flows

• src/private/package/ResolveNovaPackageUploadTarget.ps1
• src/private/package/ResolveNovaPackageUploadHeaders.ps1
• src/private/package/GetNovaPackageUploadToken.ps1
• src/private/package/DeployNovaPackage*.ps1 or related package upload helpers

Publishing-related flows

• src/private/release/PublishNovaBuiltModuleToRepository.ps1
• src/private/release/PublishNovaBuiltModule.ps1

Filesystem-heavy flows

• src/private/scaffold/
• src/private/build/
• src/private/package/
• src/private/update/

Environment access hotspots

• src/private/update/GetNovaUpdateSettingsFilePath.ps1
• src/private/release/PublishNovaBuiltModuleToRepository.ps1
• src/private/cli/ConfirmNovaCliBumpAction.ps1
• src/private/release/GetLocalModulePathEntryList.ps1

Tests likely relevant

• tests/CoverageGaps.ReleaseInternals.Tests.ps1
• tests/NovaCommandModel.PackageUpload.Tests.ps1
• tests/NovaCommandModel.ReleasePublish.Tests.ps1
• tests/UpdateNotification.Tests.ps1

What to do

1. Identify the most important external dependencies used directly in workflow logic.
2. Group them by integration type:
   • git
   • filesystem
   • publishing
   • upload/network
   • environment/settings
3. Extract small adapter-style helpers where the separation adds clear value.
4. Refactor the highest-value flows first.
5. Keep the change focused and avoid introducing an over-engineered abstraction layer.
6. Add/update tests to reflect clearer seams around external calls.
7. Review docs/changelog if public behavior changes.

Design constraints

• Keep the refactor incremental and practical.
• Prefer small focused adapters over a large framework-like abstraction.
• Preserve existing behavior unless there is a clear bug or inconsistency.
• Do not hide important failure behavior.
• Keep PowerShell code readable and idiomatic.

Expected implementation shape

A good solution will likely:

• isolate direct git command execution more clearly
• isolate upload/publish side effects more clearly
• isolate environment access where it materially improves testability
• keep core workflow code more focused on decisions than on external mechanics

Testing requirements

Add or update tests to cover at least these scenarios:

1. Refactored workflows still behave correctly.
2. External interaction boundaries are easier to mock.
3. Git-dependent logic can be tested with clearer seams.
4. Upload/publish flows still resolve auth, headers, and targets correctly.
5. Environment-dependent behavior remains correct.

Validation steps

Start with focused validation:

pwsh -NoLogo -NoProfile -Command 'Invoke-NovaBuild'
pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/CoverageGaps.ReleaseInternals.Tests.ps1 -Output Detailed'
pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/NovaCommandModel.PackageUpload.Tests.ps1 -Output Detailed'
pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/NovaCommandModel.ReleasePublish.Tests.ps1 -Output Detailed'
pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/UpdateNotification.Tests.ps1 -Output Detailed'

Also run:

git --no-pager diff --check

Documentation review requirements

After code changes, review and update if needed:

• README.md
• CHANGELOG.md
• command help/docs for any affected publish/upload/update flows

If no doc updates are needed, state that they were reviewed and why no change was necessary.

Definition of done

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

1. High-value external interactions are better isolated.
2. Workflow code is less tightly coupled to raw external calls.
3. Tests benefit from clearer seams.
4. Targeted tests pass.
5. Invoke-NovaBuild passes.
6. git diff --check passes.

Final report format

When done, report back with:

1. External dependency problems addressed
2. Files changed
3. Adapter boundaries introduced
4. Flows migrated
5. Tests added/updated
6. Validation commands run and results
7. Documentation reviewed/updated
8. Remaining follow-up ideas