Clean up output and result contracts so core logic returns structured data while CLI/UI layers own interactive host output.

[stiwicourage]

Task

Implement a maintainability improvement: clean up output and result contracts so core logic returns structured data while CLI/UI layers own interactive host output.

The goal is to make NovaModuleTools easier to automate, test, and extend by separating data contracts from presentation concerns.

Why this follow-up is needed

The repository currently mixes:

• returned result objects
• host output via Write-Host
• helper-level messaging
• CLI-specific formatting

That is manageable at small scale, but enterprise-style maintainability improves when core logic is data-first and presentation is isolated.

Goal

After this change:

• core/business logic should return structured data where practical
• CLI/UI layers should own host output and presentation
• interactive prompts should stay interactive, but non-interactive workflow logic should be less host-bound
• result objects should become more predictable for automation and tests

Likely files to inspect first

Host output helpers and formatting

• src/private/cli/WriteMessage.ps1
• src/private/cli/FormatNovaCliCommandResult.ps1
• src/private/shared/WriteNovaModuleReleaseNotesLink.ps1

Interactive CLI behavior

• src/private/cli/ConfirmNovaCliBumpAction.ps1

Core/workflow code currently writing to host

• src/private/release/SetNovaModuleVersion.ps1
• other internal helpers using Write-Host or message wrappers

Public commands and command model tests

• src/public/UpdateNovaModuleVersion.ps1
• src/public/InvokeNovaCli.ps1
• tests/NovaCommandModel.BumpAndCli.Tests.ps1
• tests/NovaCommandModel.Tests.ps1

What to do

1. Inventory where the repo returns data versus where it writes directly to host.
2. Separate truly interactive UI behavior from non-interactive core workflow behavior.
3. Refactor the highest-value internal helpers so they return data rather than writing directly to host where practical.
4. Keep CLI presentation logic in CLI-focused helpers.
5. Preserve user-facing behavior unless there is a clear reason to improve it.
6. Add tests that make the output/result contract clearer.
7. Review docs/changelog if public output behavior changes.

Design constraints

• Do not remove legitimate interactive prompts where they belong.
• Prefer small focused improvements over sweeping output rewrites.
• Preserve automation-friendly object output.
• Avoid changing command behavior unnecessarily just to satisfy architectural purity.
• Keep host output in user-facing layers, not deep internal helpers, where possible.

Expected implementation shape

A good solution will likely:

• reduce Write-Host usage in internal workflow helpers
• preserve Write-Host where the behavior is inherently interactive or CLI-specific
• make result objects more consistent
• clarify which layer is responsible for formatting messages versus returning data

Testing requirements

Add or update tests to cover at least these scenarios:

1. Core workflow helpers still produce the needed information after refactor.
2. CLI/user-facing formatting still works as expected.
3. Commands remain automation-friendly where they should return objects.
4. Interactive confirmation flows still behave correctly.

Validation steps

Start with focused validation:

pwsh -NoLogo -NoProfile -Command 'Invoke-NovaBuild'
pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/NovaCommandModel.BumpAndCli.Tests.ps1 -Output Detailed'
pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/NovaCommandModel.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 if public output behavior changes materially

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. Output/result responsibilities are clearer.
2. Internal helpers are less presentation-bound where practical.
3. CLI/UI layers still present clear user-facing output.
4. Tests cover the intended contract.
5. Targeted tests pass.
6. Invoke-NovaBuild passes.
7. git diff --check passes.

Final report format

When done, report back with:

1. Output/result problems addressed
2. Files changed
3. Contract cleanup implemented
4. UI/core responsibilities clarified
5. Tests added/updated
6. Validation commands run and results
7. Documentation reviewed/updated
8. Remaining follow-up ideas