feat(#99): enhance adapter architecture for external dependencies

[stiwicourage]

Summary

• What changed?
  • Refactored several internal Nova workflows to isolate external dependency access behind smaller adapter-style helpers.
  • Added clearer seams around git, raw upload request execution, repository publish execution, module self-update execution,
    settings JSON persistence, and CLI environment-variable access.
  • Updated targeted tests to mock the new seams directly, and renamed new helper functions to satisfy
    PSScriptAnalyzer singular-noun rules so the local quality flow stays green.
• Why was this change needed?
  • The workflow logic had direct coupling to external tools and system APIs in a few high-value areas, which made tests
    broader than necessary and made change points less explicit.
  • The refactor keeps outward behavior stable while making release, upload, publish, update, and environment-dependent
    paths easier to reason about, isolate, and evolve.
• Link the issue, discussion, or follow-up work (for example Closes #123).
  • Follow-up implementation from 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

Review guidance

• Start with the new shared and execution-seam helpers:
  • src/private/shared/InvokeNovaGitCommand.ps1
  • src/private/shared/InvokeNovaJsonFile.ps1
  • src/private/package/InvokeNovaPackageUploadRequest.ps1
  • src/private/release/InvokeNovaRepositoryPublishCommand.ps1
  • src/private/update/InvokeNovaModuleUpdateCommand.ps1
• Then review the migrated workflows that now depend on those seams:
  • src/private/release/GetGitCommitMessagesForVersionBump.ps1
  • src/private/release/GetNovaVersionLabelForBump.ps1
  • src/private/release/InitiateGitRepo.ps1
  • src/private/release/PublishNovaBuiltModuleToRepository.ps1
  • src/private/package/InvokeNovaPackageArtifactUpload.ps1
  • src/private/update/InvokeNovaModuleSelfUpdate.ps1
  • src/private/update/ReadNovaUpdateNotificationPreference.ps1
  • src/private/update/WriteNovaUpdateNotificationPreference.ps1
  • src/private/cli/ConfirmNovaCliAction.ps1
  • src/private/cli/GetNovaCliInstallDirectory.ps1
  • src/private/cli/TestNovaCliDirectoryOnPath.ps1
• Focused tests were added or updated in:
  • tests/CoverageGaps.ReleaseInternals.Tests.ps1
  • tests/NovaCommandModel.PackageUpload.Tests.ps1
  • tests/NovaCommandModel.ReleasePublish.Tests.ps1
  • tests/UpdateNotification.Tests.ps1
  • tests/CoverageGaps.Cli.Tests.ps1
• Trade-offs / limitations:
  • This is intentionally an internal maintainability refactor, so behavior changes were avoided where possible.
  • The main risk area is delegation wiring: git history lookup, upload request execution, repository publish execution,
    self-update execution, and settings/environment resolution now flow through helper boundaries instead of direct calls.

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:

Primary end-to-end validation:
- pwsh -NoLogo -NoProfile -File ./run.ps1
  - Passed with exit code 0
  - Final result: Tests Passed: 548, Failed: 0, Skipped: 0

Focused validation run during implementation:
- 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'
- pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/CoverageGaps.Cli.Tests.ps1 -Output Detailed'
- pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/RemainingCommandCoverage.Tests.ps1 -Output Detailed'
- pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/CoverageCompletion.Tests.ps1 -Output Detailed'

Other checks:
- git --no-pager diff --check
- Local Code Health safeguard passed

Skipped:
- Full CI entrypoint script was not run from this summary task
- No live publish/upload/release against external services was exercised

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 impact:
- No intended user-facing behavior change. This change primarily restructures internal execution seams.

Main risk areas:
- git command delegation in version bump/repository-init paths
- raw upload request delegation
- repository publish delegation
- module self-update delegation
- settings JSON persistence and environment-variable lookup delegation

Rollback / maintainer follow-up:
- Rollback is straightforward because the change is mostly seam extraction and helper renaming.
- The final analyzer-related follow-up was a naming cleanup so run.ps1 no longer fails on PSScriptAnalyzer warnings.
- Branch-level PR pre-flight Code Health may still need separate cleanup for pre-existing test-file global-conditionals debt.

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

[codecov]

Codecov Report

❌ Patch coverage is 99.00000% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/private/cli/ConfirmNovaCliAction.ps1	90.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[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.