# CLI Framework

## Requirements

### Requirement: Command Base Class

The system SHALL provide an abstract `Command` base class for CLI command
implementations with type-safe argument parsing integration.

#### Scenario: Command implementation
- **WHEN** a class inherits from `Command`
- **THEN** it must implement an `execute()` method
- **AND** the command receives `Globals` for access to framework state

#### Scenario: Command argument parsing
- **WHEN** a command class defines typed fields
- **THEN** `tyro` automatically generates argument parsing from type annotations
- **AND** help text is generated from field docstrings

#### Scenario: Command execution
- **WHEN** a command instance is called with `Globals`
- **THEN** the `execute()` method is invoked with the provided state
- **AND** the command can access configuration, directories, and inscription

### Requirement: Application Base Class

The system SHALL provide an `Application` base class for CLI application
definition with automatic command routing.

#### Scenario: Application definition
- **WHEN** a class inherits from `Application`
- **THEN** it defines its command structure through typed fields
- **AND** `tyro` generates the CLI interface from the class definition

#### Scenario: Application preparation
- **WHEN** `Application.prepare()` is called
- **THEN** it extends the standard `prepare()` with CLI-specific initialization
- **AND** display options and inscription are configured from CLI arguments

#### Scenario: Application execution
- **WHEN** `Application()` is called (the instance is callable)
- **THEN** argument parsing occurs via `tyro`
- **AND** the application's `execute()` method is invoked with `Globals`

### Requirement: Command Routing via Type Guards

The system SHALL use `isinstance()` type guards for command routing within
CLI applications.

#### Scenario: Single command routing
- **WHEN** an application has a single command type
- **THEN** the application directly instantiates and executes the command

#### Scenario: Multiple command routing
- **WHEN** an application has multiple command types
- **THEN** the application uses `isinstance()` checks to determine which
  command to execute
- **AND** each command type is a distinct class inheriting from `Command`

#### Scenario: Subcommand composition
- **WHEN** commands need subcommands
- **THEN** each subcommand is a separate `Command` subclass
- **AND** the parent command routes to subcommands via `isinstance()` checks

### Requirement: Display and Output Control

The system SHALL provide `DisplayOptions` for controlling output presentation
and routing.

#### Scenario: Presentation mode selection
- **WHEN** display options specify a presentation mode (plain, rich, json, toml)
- **THEN** output is formatted according to the selected mode
- **AND** rich mode enables terminal-aware formatting when available

#### Scenario: Output stream routing
- **WHEN** display options specify a target stream (stdout, stderr, file)
- **THEN** output is directed to the specified stream
- **AND** file targets are created with proper resource management

#### Scenario: Colorization control
- **WHEN** display options specify colorization preferences
- **THEN** ANSI color codes are applied or stripped accordingly
- **AND** non-TTY streams automatically disable colorization