Refactor Nova CLI schema/parsing so command argument handling becomes more declarative, consistent, and scalable.

[stiwicourage]

Task

Implement a maintainability improvement: refactor Nova CLI schema/parsing so command argument handling becomes more declarative, consistent, and scalable.

The goal is to reduce duplicated manual parsing logic and make it easier to add commands, validation rules, and help behavior without drift.

Why this follow-up is needed

The repository currently has multiple command-specific CLI parsing helpers, which is workable but can become harder to scale and keep consistent across:

• argument parsing
• validation
• help/error messages
• forwarding to command execution

A more schema-driven or centralized pattern would improve maintainability as the Nova command model grows.

Goal

After this change:

• CLI option parsing should be more consistent across commands
• command-specific parsing should depend on a shared pattern or schema
• error messages and required-argument handling should be easier to keep uniform
• it should be easier to add or evolve CLI commands without repeating parser logic

Likely files to inspect first

CLI parsing helpers

• src/private/cli/GetNovaCliOptions.ps1
• src/private/cli/GetNovaCliRequiredArgumentValue.ps1
• src/private/cli/AddNovaCliOptionValue.ps1
• src/private/cli/AddNovaCliHeaderOption.ps1
• src/private/cli/ConvertTo-NovaCliArgumentArray.ps1

Command-specific parsers

• src/private/cli/ConvertFromNovaInitCliArgument.ps1
• src/private/cli/ConvertFromNovaDeployCliArgument.ps1
• src/private/cli/ConvertFromNovaUpdateCliArgument.ps1
• src/private/cli/ConvertFromNovaVersionCliArgument.ps1
• src/private/cli/ConvertFromNovaNotificationCliArgument.ps1

CLI execution layer

• src/public/InvokeNovaCli.ps1
• src/private/cli/InvokeNovaCliInitCommand.ps1
• src/private/cli/InvokeNovaCliDeployCommand.ps1
• src/private/cli/InvokeNovaCliUpdateCommand.ps1
• src/private/cli/InvokeNovaCliVersionCommand.ps1
• src/private/cli/InvokeNovaCliNotificationCommand.ps1

Tests likely relevant

• tests/NovaCommandModel.Tests.ps1
• tests/NovaCommandModel.BumpAndCli.Tests.ps1
• tests/NovaCommandModel.StandaloneCli.Tests.ps1
• deploy/init/update-related command tests if present

What to do

1. Map the current parsing approach command by command.
2. Identify repeated parsing/validation patterns.
3. Define a more declarative CLI schema or shared parsing model.
4. Refactor the highest-value command parsers first.
5. Preserve existing command syntax unless a change is clearly justified.
6. Improve consistency of missing-value and unknown-argument behavior.
7. Add or update tests for the refactored command parsing behavior.
8. Review docs/help if command parsing or usage rules change.

Design constraints

• Keep the change incremental.
• Avoid rewriting the entire CLI in one pass unless truly necessary.
• Preserve existing CLI contracts where possible.
• Prefer clarity and maintainability over over-engineered generic parsing abstractions.
• Keep the final model understandable to PowerShell maintainers.

Expected implementation shape

A good solution will likely:

• introduce a shared schema or option-definition model
• reduce repetitive token-walking logic in command-specific parsers
• centralize required-value handling and unknown-argument reporting
• make command parsing easier to extend in the future

Testing requirements

Add or update tests to cover at least these scenarios:

1. Existing supported CLI forms still parse correctly.
2. Unknown arguments fail consistently.
3. Missing required option values fail consistently.
4. Refactored commands still invoke the correct execution path.
5. Help/usage behavior remains coherent.

Validation steps

Start with focused validation:

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

If the standalone launcher path is affected, run related CLI tests too.

Also run:

git --no-pager diff --check

Documentation review requirements

After code changes, review and update if needed:

• README.md
• CHANGELOG.md
• docs/commands.html
• docs/NovaModuleTools/en-US/Invoke-NovaCli.md
• command help/docs for any affected CLI usage

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. The CLI parsing model is more consistent and maintainable.
2. At least the highest-value command parsers use the new/shared pattern.
3. CLI behavior remains correct.
4. Tests cover the refactored parsing paths.
5. Targeted tests pass.
6. Invoke-NovaBuild passes.
7. git diff --check passes.

Final report format

When done, report back with:

1. CLI parsing problems addressed
2. Files changed
3. Shared schema/parsing approach introduced
4. Commands migrated
5. Tests added/updated
6. Validation commands run and results
7. Documentation reviewed/updated
8. Remaining follow-up ideas

[stiwicourage]

Is this needed with the current implementation of workflows.