Private CLI Helper Consolidation Plan

[stiwicourage]

Private CLI Helper Consolidation Plan

Purpose

This plan tracks a follow-up maintainability pass focused on src/private/cli/ after the completed public-command refactor.

The public entrypoints are now thin. The next opportunity is to review the private CLI layer for:

• further consolidation where helpers are too fragmented
• sharper contracts where helper boundaries are still vague
• clearer separation between argument parsing, invocation-context preparation, routing, formatting, and side effects

Why this follow-up is needed

The private CLI layer now contains many small helpers, which is better than a large monolithic public entrypoint, but it also creates a new review question:

• are the helper boundaries cohesive?
• are the contracts explicit enough?
• are there still places where parsing, routing, formatting, and environment-facing behavior are mixed?
• are there helpers that should stay separate versus be grouped more intentionally?

This pass should improve maintainability without undoing the public-command layering that was just established.

Goal

After this change:

• CLI helper responsibilities should be easier to understand at a glance
• helper contracts should be explicit and easy to test
• argument parsing should stay separate from command routing where practical
• formatting and result translation should stay separate from routing where practical
• environment/process/file/host interaction should be isolated when it improves clarity
• tests should describe CLI behavior through smaller seams, not only through end-to-end invocation

Scope

Primary scope:

• src/private/cli/

Likely helpers to inspect first:

• GetNovaCliInvocationContext.ps1
• InvokeNovaCliCommandRoute.ps1
• GetNovaCliForwardingParameterSet.ps1
• ConvertTo-NovaCliArgumentArray.ps1
• GetNovaCliCommandHelp.ps1
• InvokeNovaCliVersionCommand.ps1
• InvokeNovaCliInitCommand.ps1
• InvokeNovaCliUpdateCommand.ps1
• InvokeNovaCliNotificationCommand.ps1
• InvokeNovaCliDeployCommand.ps1
• FormatNovaCliCommandResult.ps1
• WriteMessage.ps1

Related supporting areas that may need small adjustments:

• src/public/InvokeNovaCli.ps1
• tests/CoverageGaps.Cli.Tests.ps1
• tests/NovaCommandModel.StandaloneCli.Tests.ps1
• tests/NovaCommandModel.BumpAndCli.Tests.ps1
• tests/UpdateNotification.Tests.ps1
• tests/RemainingCommandCoverage.Tests.ps1

Non-goals

• no broad CLI redesign
• no user-visible behavior changes unless current behavior is clearly wrong
• no large-scale renaming of commands or command arguments
• no conversion of the CLI layer into a framework-heavy abstraction

Review questions

Use these questions to guide the pass:

1. Which helpers are true contract boundaries versus temporary pass-through wrappers?
2. Are there helper files with multiple tiny functions that belong together conceptually?
3. Are there helpers with too many arguments that indicate a missing context object?
4. Are there places where the helper name does not clearly match its responsibility?
5. Are parsing, routing, result formatting, and side effects isolated at the right level?
6. Are tests protecting contracts or just incidental implementation details?

Working method

1. Inspect the private CLI flow end to end, starting from Invoke-NovaCli.
2. Group helpers by role:
   • invocation preparation
   • argument parsing
   • routing
   • result formatting
   • environment/process/host interaction
3. Identify the highest-value consolidation or contract-clarification opportunities.
4. Refactor in small, reviewable steps.
5. After each meaningful step:
   • re-run targeted tests
   • re-check Code Health on touched files
6. Keep PowerShell idioms readable and avoid abstraction for its own sake.

Desired architectural shape

Invocation preparation

Helpers in this group should resolve:

• normalized arguments
• forwarded common parameters
• routed mutation parameters
• help/WhatIf/Confirm intent

They should avoid performing command-specific business logic.

Routing

Helpers in this group should:

• choose the routed command or routed workflow helper
• keep per-command routing readable
• avoid environment/process side effects directly when a domain helper already exists

Formatting / translation

Helpers in this group should:

• format CLI-facing results
• translate domain/update results into user-facing CLI output
• stay separate from core routing where that improves clarity

Infrastructure-facing helpers

Helpers in this group should isolate:

• launcher file discovery
• file copying and permission changes
• PATH checks
• message/host output

Expected implementation shape

A good solution will likely:

• keep Invoke-NovaCli thin
• make private CLI contracts more obvious to readers
• reduce any remaining argument-heavy helpers when a context object is more expressive
• consolidate only where it increases cohesion
• keep tests focused on stable behavior and explicit seams

Testing requirements

Add or update tests to cover at least these scenarios:

1. Invocation-preparation helpers return the expected context shape.
2. Routing helpers dispatch the expected command/workflow.
3. Formatting helpers preserve current user-visible CLI output.
4. Standalone installed launcher behavior remains unchanged.
5. WhatIf/Confirm forwarding behavior remains intact.

Validation steps

Start with focused validation:

pwsh -NoLogo -NoProfile -Command 'Invoke-NovaBuild'
pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/CoverageGaps.Cli.Tests.ps1 -Output Detailed'
pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/NovaCommandModel.StandaloneCli.Tests.ps1 -Output Detailed'
pwsh -NoLogo -NoProfile -Command 'Invoke-Pester ./tests/NovaCommandModel.BumpAndCli.Tests.ps1 -Output Detailed'

Also run:

git --no-pager diff --check

Recommended full-project validation:

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"'

Documentation review requirements

After code changes, review and update if needed:

• README.md
• CONTRIBUTING.md
• CHANGELOG.md

If no documentation update is needed, explicitly state why.

Definition of done

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

1. The private CLI helper roles are easier to understand.
2. Any consolidation improves cohesion rather than hiding behavior.
3. Argument parsing, routing, and formatting contracts are clearer than before.
4. Targeted CLI tests pass.
5. Invoke-NovaBuild passes.
6. run.ps1 passes.
7. git diff --check passes.

Progress tracking

Candidate areas

• Invocation preparation helpers reviewed
• Routing helpers reviewed
• Formatting helpers reviewed
• Infrastructure-facing CLI helpers reviewed

Validation checklist

• Focused tests updated
• Invoke-NovaBuild passes
• Relevant Pester suites pass
• run.ps1 passes
• git diff --check passes
• Docs reviewed

Final report format

When done, report back with:

1. Private CLI boundary problems addressed
2. Files changed
3. Consolidation and contract decisions made
4. Tests added/updated
5. Validation commands run and results
6. Documentation reviewed/updated
7. Remaining CLI follow-up ideas

[stiwicourage]

We will look into this, after the CLI refactoring is done, so for now it will be blocked by those issues.