@cli
Feature: CLI consistency and UX polish
  As a developer
  I want all CLI commands to follow consistent UX patterns
  So that the tool is predictable and easy to use

  # -----------------------------------------------------------------
  # Exit code constants
  # -----------------------------------------------------------------

  Scenario: Exit code constants are defined
    Given the CLI constants module is imported
    Then EXIT_SUCCESS should equal 0
    And EXIT_ERROR should equal 1
    And EXIT_USAGE should equal 2
    And EXIT_NOT_FOUND should equal 3
    And EXIT_CONFLICT should equal 4

  # -----------------------------------------------------------------
  # Error formatting
  # -----------------------------------------------------------------

  Scenario: cli_error displays standardized error and exits
    Given the CLI errors module is imported
    When I call cli_error with only message "something broke"
    Then the process should exit with code 1
    And the stderr output should contain "Error:"
    And the stderr output should contain "something broke"

  Scenario: cli_error displays hint when provided
    Given the CLI errors module is imported
    When I call cli_error with message "not found" and hint "check the name"
    Then the process should exit with code 1
    And the stderr output should contain "Hint: check the name"

  Scenario: cli_error uses custom exit code
    Given the CLI errors module is imported
    When I call cli_error with message "bad usage" and exit code 2
    Then the process should exit with code 2

  Scenario: cli_warning displays warning without exiting
    Given the CLI errors module is imported
    When I call cli_warning with only message "heads up"
    Then the stderr output should contain "Warning:"
    And the stderr output should contain "heads up"

  Scenario: cli_warning displays hint when provided
    Given the CLI errors module is imported
    When I call cli_warning with message "slow" and hint "use cache"
    Then the stderr output should contain "Hint: use cache"

  Scenario: cli_not_found formats correctly and exits with code 3
    Given the CLI errors module is imported
    When I call cli_not_found with type "Project" and name "missing-proj"
    Then the process should exit with code 3
    And the stderr output should contain "Project 'missing-proj' not found"
    And the stderr output should contain "Hint:"

  # -----------------------------------------------------------------
  # Format constants
  # -----------------------------------------------------------------

  Scenario: Format constants are consistent
    Given the CLI constants module is imported
    Then FORMAT_HELP should mention "json"
    And FORMAT_HELP should mention "yaml"
    And FORMAT_HELP should mention "plain"
    And DEFAULT_FORMAT should equal "rich"
    And VALID_FORMATS should contain "json"
    And VALID_FORMATS should contain "yaml"
    And VALID_FORMATS should contain "plain"
    And VALID_FORMATS should contain "table"
    And VALID_FORMATS should contain "rich"

  Scenario: Named format shortcut constants are defined
    Given the CLI constants module is imported
    Then FORMAT_TEXT should equal "plain"
    And FORMAT_JSON should equal "json"
    And FORMAT_TABLE should equal "table"

  # -----------------------------------------------------------------
  # Help text consistency
  # -----------------------------------------------------------------

  Scenario: Main CLI provides help output
    Given a CLI consistency test runner
    When I invoke the CLI with "--help"
    Then the invoked CLI exit code should be 0
    And the invoked CLI output should contain "AI-powered development assistant"

  Scenario: Version command provides output
    Given a CLI consistency test runner
    When I invoke the CLI with "--version"
    Then the invoked CLI exit code should be 0
    And the invoked CLI output should contain "CleverAgents"

  Scenario: Invalid command returns usage exit code
    Given a CLI consistency test runner
    When I invoke the CLI with "nonexistent-command-xyz"
    Then the invoked CLI exit code should be 2

  # -----------------------------------------------------------------
  # Shell completion command
  # -----------------------------------------------------------------

  Scenario: Completion command exists
    Given a CLI consistency test runner
    When I invoke the CLI with "completion --help"
    Then the invoked CLI exit code should be 0
    And the invoked CLI output should contain "completion"

  Scenario: Completion rejects unsupported shell
    Given a CLI consistency test runner
    When I invoke the CLI with "completion ksh"
    Then the invoked CLI exit code should be 2

  # -----------------------------------------------------------------
  # JSON/text format switching
  # -----------------------------------------------------------------

  Scenario: Version command supports JSON format via global --format flag
    Given a CLI consistency test runner
    When I invoke the CLI with "--format json version"
    Then the invoked CLI exit code should be 0
    And the invoked CLI output should be valid JSON

  Scenario: Version command supports YAML format via global --format flag
    Given a CLI consistency test runner
    When I invoke the CLI with "--format yaml version"
    Then the invoked CLI exit code should be 0
    And the invoked CLI output should contain "version:"

  Scenario: Version command supports plain format via global --format flag
    Given a CLI consistency test runner
    When I invoke the CLI with "--format plain version"
    Then the invoked CLI exit code should be 0
    And the invoked CLI output should contain "version:"