command like feedback on incorrect syntax is not super helpful

[walterheck]

when I issue commands with arguments in the wrong order, the cli help is not clear enough on what I am doing wrong

walterheck in ~/Source/helixiora/internal/swamp-test
> swamp model hetzner-server method getSystemInfo

Usage:   swamp model                   
Version: 20260217.201029.0-sha.67f29849

Description:

  Manage models

Options:

  -h, --help                  - Show this help.                                            
  --json                      - Output in JSON format (non-interactive)                    
  --log-level        <level>  - Set log level (trace, debug, info, warning, error, fatal)  
  -q, --quiet                 - Suppress non-essential output                              
  -v, --verbose               - Show detailed output                                       
  --no-telemetry              - Disable telemetry for this invocation                      
  --show-properties           - Show structured properties in log output                   
  --no-color                  - Disable colored output                                     

Commands:

  create    <type> <name>       - Create a new model definition                 
  delete    <model_id_or_name>  - Delete a model and all related artifacts      
  edit      [model_id_or_name]  - Edit a model definition file                  
  evaluate  [model_id_or_name]  - Evaluate expressions in model definitions     
  get       <model_id_or_name>  - Show details of a model definition            
  search    [query]             - Search for model definitions                  
  validate  [model_id_or_name]  - Validate a model definition against its schema
  method                        - Execute model methods                         
  output                        - Manage model outputs                          
  type                          - Inspect model types                           

  error: Unknown command "hetzner-server". Did you mean command "create"?

[stack72]

Plan: Improve CLI Feedback for Incorrect swamp model method Syntax

Root Cause

When a user types swamp model hetzner-server method getSystemInfo, Cliffy (the CLI framework) sees hetzner-server as an unknown subcommand of model and immediately writes its error to stderr before our code can intercept it. The "Did you mean command 'create'?" suggestion is a fuzzy-match against known subcommands — useless in this context.

The correct syntax is:

swamp model method run hetzner-server getSystemInfo

---

Proposed Changes

1. Arg Normalization in src/cli/mod.ts

Add a normalizeModelMethodArgs() function (exported for testing) that runs before cli.parse(). It detects the misplaced-model-name pattern and transparently rewrites it to the canonical form.

Pattern detected:

swamp [global-flags] model <model-name> method [run] <method-name> [options...]

Rewritten to:

swamp [global-flags] model method run <model-name> <method-name> [options...]

When rewriting occurs, a one-line hint is written to stderr (suppressed in --json mode):

Note: rewriting to canonical form: swamp model method run hetzner-server getSystemInfo

The function correctly handles:

• Global flags before model (e.g. --json, --log-level debug)
• User already typing run in the wrong place
• Trailing options after the method name
• Known model subcommands (create, delete, get, etc.) — these are never mistaken for model names

2. Usage Examples in src/cli/commands/model_method_run.ts

Add .example() calls to both modelMethodRunCommand and modelMethodCommand so users see correct syntax in --help output:

Examples:

  run a method
    $ swamp model method run hetzner-server getSystemInfo

  run with inputs
    $ swamp model method run my-model deploy --input environment=production

  common mistake (auto-corrected)
    $ swamp model hetzner-server method getSystemInfo  # auto-corrected to canonical form

3. Unit Tests in src/cli/mod_test.ts

Extend the existing test file with ~13 test cases covering:

• The motivating example from this issue
• Global flag prefixes (--json, --log-level debug)
• User typing run in the wrong position
• Trailing options preserved correctly
• No-op cases: canonical form, known subcommands, non-model commands, empty args

---

Impact on Existing Users

User type	Impact
Uses canonical swamp model method run <name> <method>	None — normalization only triggers on the wrong-order pattern
Uses wrong-order form (currently gets an error)	Positive — command now works transparently
Scripts consuming --json output	None — hint is stderr-only and suppressed in JSON mode
Model names matching known subcommands (create, delete, etc.)	None — these are excluded from the rewrite trigger

The change is purely additive. Since swamp model <non-subcommand> method ... is not valid syntax for any existing command, any invocation matching this pattern is necessarily a user error today — making it safe to rewrite.

[stack72]

@walterheck would love you to give this a read and see what you think

[walterheck]

Looks good I think. Small remarks:

1. Be careful with words like canonical, second language English speakers will understand better if you use simple English
2. This should work for all forms, not just model method run
3. I noticed that in some places a model is referred to as @hetzner/server and others it's hetzner-server. I got it wrong twice before I got it right :)
4. One small thought I had is wether auto-rewriting is going to be useful in the long term for the user as they get lazy. Maybe an error would be better?

[stack72]

Revised Plan: Improve CLI Error Messages for Unknown Subcommands

Based on @walterheck's feedback, we're going with clearer error messages instead of auto-rewriting args. This teaches users the correct syntax rather than hiding mistakes.

---

Root Cause

When a user types swamp model hetzner-server method getSystemInfo, Cliffy sees hetzner-server as an unknown subcommand of model and outputs:

error: Unknown command "hetzner-server". Did you mean command "create"?

The "Did you mean" suggestion is a fuzzy-match against known subcommands — useless when the user put a model name in the wrong position.

Technical Approach

Swamp doesn't use Cliffy's .throwErrors(), so Cliffy prints help+error and calls Deno.exit(2) directly — the catch block never fires. We'll use Cliffy's .error() handler to intercept UnknownCommandError before Cliffy renders its default output, and replace it with a context-aware UserError.

The .error() handler receives the error and the command object, giving us:

• cmd.getName() — the command being parsed (e.g., "model")
• cmd.getPath() — full path (e.g., "swamp model")
• cmd.getCommands() — known subcommands of that command

Proposed Changes

1. Extract Shared String Distance Utility

New file: src/domain/string_distance.ts

The Levenshtein distance function is duplicated in two files. Extract it to a shared module so the error handler can use it for typo detection.

2. Create Unknown Command Error Handler

New file: src/cli/unknown_command_handler.ts

Intercepts Cliffy's UnknownCommandError and provides context-aware suggestions:

Case A — Typo of a real subcommand (e.g., swamp model creat):

error: Unknown command "creat". Did you mean "create"?

    swamp model create ...

Case B — Model name in wrong position (e.g., swamp model hetzner-server method getSystemInfo):

error: "hetzner-server" is not a subcommand of "model".

  Did you mean one of these?

    Run a method:    swamp model method run hetzner-server getSystemInfo
    Get model info:  swamp model get hetzner-server

  Run "swamp model --help" for available subcommands.

Case C — Nested unknown (e.g., swamp model method hetzner-server getSystemInfo):

error: "hetzner-server" is not a subcommand of "model method".

  Did you mean to run a method?

    swamp model method run hetzner-server <method_name>

The handler uses Levenshtein distance to distinguish typos from model names — if the unknown name is close to a real subcommand, it suggests the correction; otherwise it assumes it's a model/workflow name and suggests the correct syntax.

3. Integrate into CLI

File: src/cli/mod.ts (~5 lines changed)

Add .error() handler to the root CLI command that calls the handler for UnknownCommandError and re-throws everything else.

4. Add Help Examples

File: src/cli/commands/model_method_run.ts

Add .example() calls so --help shows correct usage:

Examples:

  Run a method:     swamp model method run my-server getSystemInfo
  Run with inputs:  swamp model method run my-server deploy --input env=prod

Impact on Existing Users

User type	Impact
Uses correct syntax	None — only changes error output
Types commands in wrong order	Positive — gets clear guidance instead of confusing suggestion
Typos real subcommands	Improved — still gets "Did you mean" but with example syntax
Scripts / --json mode	None — errors go through existing UserError rendering

Files Changed

File	Action
src/domain/string_distance.ts	NEW — shared Levenshtein utility
src/cli/unknown_command_handler.ts	NEW — error interceptor
src/cli/mod.ts	MODIFY — add .error() handler
src/cli/commands/model_method_run.ts	MODIFY — add .example()
src/domain/expressions/schema_path_validator.ts	MODIFY — import shared utility
src/domain/inputs/input_override_validation_service.ts	MODIFY — import shared utility
+ test files for new modules