feat(#105): consolidate CLI helper functions for improved command han…

[stiwicourage]

Summary

• Refactored the private CLI layer to make invocation-context preparation and command routing contracts easier to understand without changing public Invoke-NovaCli behavior.
• Consolidated the invocation-context shaping in src/private/cli/GetNovaCliInvocationContext.ps1 so the final routed/help context, WhatIf state, and CLI confirm intent are derived through smaller explicit seams instead of several overlapping context builders.
• Simplified src/private/cli/InvokeNovaCliCommandRoute.ps1 by removing the dead unknown-command adapter path and keeping the stable unknown-command error contract directly in the router.
• Updated tests/CoverageGaps.Cli.Tests.ps1 to validate the stable private CLI contracts directly: unknown-command routing and raw Confirm stripping while preserving CLI confirm intent.
• This follow-up was needed because the private CLI layer had become more modular after the public-entrypoint refactor, but some helper boundaries were still more fragmented than necessary.
• Follow-up reference: private CLI helper consolidation 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 CLI helper contracts in src/private/cli/

Review guidance

• Start with src/public/InvokeNovaCli.ps1, then go immediately to src/private/cli/GetNovaCliInvocationContext.ps1.
• Reviewers should focus on these files in order:
  • src/private/cli/GetNovaCliInvocationContext.ps1
  • src/private/cli/InvokeNovaCliCommandRoute.ps1
  • tests/CoverageGaps.Cli.Tests.ps1
• Main changes to inspect:
  • the shared invocation-context shaping now happens through Get-NovaCliResolvedInvocationContext
  • WhatIf and CLI confirm intent are derived through explicit helpers instead of duplicated inline context shaping
  • the router now throws the stable unknown-command error directly instead of delegating through a dead adapter
• Trade-off: this intentionally does not perform a broad CLI redesign. It only tightens the current high-value seams that were still vague or redundant.

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:

Focused validation:
- pwsh -NoLogo -NoProfile -Command 'Invoke-NovaBuild'
  Result: passed.

- pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/CliSharedParser.Tests.ps1 -Output Detailed'
  Result: 3/3 passed.

- pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/CoverageGaps.Cli.Tests.ps1 -Output Detailed'
  Result: 61/61 passed.
  Included the updated private-contract coverage for:
	* stable unknown-command routing
	* invocation-context stripping of raw Confirm while preserving CliConfirmEnabled

- pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/NovaCommandModel.StandaloneCli.Tests.ps1 -Output Detailed'
  Result: 69/69 passed.

- pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/NovaCommandModel.BumpAndCli.Tests.ps1 -Output Detailed'
  Result: 33/33 passed.

- pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/RemainingCommandCoverage.Tests.ps1 -Output Detailed'
  Result: 25/25 passed.

Full repository quality flow:
- zsh -lc 'pwsh -NoLogo -NoProfile -File "/Users/stiwi.courage/workspace/couragedk/NovaModuleTools/run.ps1" > /tmp/novamoduletools-run-private-cli.log 2>&1; rc=$?; tail -n 80 /tmp/novamoduletools-run-private-cli.log | cat; echo "EXIT:$rc"'
  Result: EXIT:0
  Tests Passed: 568, Failed: 0

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

Maintainability safeguards:
- CodeScene pre-commit safeguard: passed
- Code Health review:
	* src/private/cli/GetNovaCliInvocationContext.ps1 -> 10.0
	* src/private/cli/InvokeNovaCliCommandRoute.ps1 -> 10.0
	* tests/CoverageGaps.Cli.Tests.ps1 -> 10.0

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

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 change stayed inside private CLI helpers and preserved the public Invoke-NovaCli behavior and existing user-visible CLI contracts.

Rollback is straightforward:
- restore the previous invocation-context helper structure in src/private/cli/GetNovaCliInvocationContext.ps1
- restore the previous unknown-command adapter path in src/private/cli/InvokeNovaCliCommandRoute.ps1
- remove the two focused CLI coverage additions from tests/CoverageGaps.Cli.Tests.ps1 if the old structure returns

Maintainer follow-up:
- continue reviewing private CLI helpers only where consolidation improves cohesion rather than hiding behavior
- keep tests focused on stable CLI contracts instead of incidental wrappers

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!