ConsoleContracts/SPECS.md

# ConsoleContracts Specification

This document defines the technical specifications for the `getphred/console-contracts` package. These interfaces and constants form the foundational standard for the Phred CLI ecosystem.

## 1. Namespace & Constants

**Namespace**: `Phred\ConsoleContracts`

### 1.1 Verbosity Levels
The `Verbosity` class (or final class with constants) defines the following levels:
- `Verbosity::QUIET = 0`
- `Verbosity::NORMAL = 1`
- `Verbosity::VERBOSE = 2`
- `Verbosity::VERY_VERBOSE = 3`
- `Verbosity::DEBUG = 4`

### 1.2 Exit Codes
The `ExitCode` class (or final class with constants) follows the `sysexits.h` standard:
- `ExitCode::OK = 0`
- `ExitCode::USAGE = 64`
- `ExitCode::DATAERR = 65`
- `ExitCode::NOINPUT = 66`
- `ExitCode::UNAVAILABLE = 69`
- `ExitCode::SOFTWARE = 70`
- `ExitCode::IOERR = 74`
- `ExitCode::PERM = 77`
- `ExitCode::CONFIG = 78`

## 2. Core Interfaces

### 2.1 CommandInterface
Defines the metadata and execution logic for a CLI command.
```php
namespace Phred\ConsoleContracts;

interface CommandInterface
{
    public function getName(): string;
    public function getDescription(): string;
    public function getArguments(): array;
    public function getOptions(): array;
    public function execute(InputInterface $input, OutputInterface $output): int;
}
```

### 2.2 InputInterface
Provides access to command-line arguments and options.
```php
namespace Phred\ConsoleContracts;

interface InputInterface
{
    public function getArgument(string $name, mixed $default = null): mixed;
    public function getOption(string $name, mixed $default = null): mixed;
    public function hasOption(string $name): bool;
}
```

### 2.3 OutputInterface
Standard interface for console output with semantic methods and verbosity control.
```php
namespace Phred\ConsoleContracts;

interface OutputInterface
{
    public function write(string $message): void;
    public function writeln(string $message): void;
    public function success(string $message): void;
    public function info(string $message): void;
    public function error(string $message): void;
    public function warning(string $message): void;
    public function comment(string $message): void;
    public function setVerbosity(int $level): void;
    public function getVerbosity(): int;
}
```

### 2.4 InteractionInterface
Optional interface for interactive features.
```php
namespace Phred\ConsoleContracts;

interface InteractionInterface
{
    public function ask(string $question, ?string $default = null): string;
    public function confirm(string $question, bool $default = true): bool;
    public function secret(string $question): string;
    public function choice(string $question, array $choices, mixed $default = null): mixed;
}
```

### 2.5 ConsoleMiddlewareInterface
Standardized interface for wrapping command execution.
```php
namespace Phred\ConsoleContracts;

interface ConsoleMiddlewareInterface
{
    public function handle(
        CommandInterface $command,
        InputInterface $input,
        OutputInterface $output,
        callable $next
    ): int;
}
```

### 2.6 ConsoleExceptionInterface
Base interface for all console-related exceptions.
```php
namespace Phred\ConsoleContracts;

interface ConsoleExceptionInterface extends \Throwable
{
}
```

## 3. Helper Contracts (Optional)

### 3.1 ProgressBarInterface
```php
namespace Phred\ConsoleContracts\Helpers;

interface ProgressBarInterface
{
    public function start(int $max = 0): void;
    public function advance(int $step = 1): void;
    public function finish(): void;
}
```

### 3.2 TableInterface
```php
namespace Phred\ConsoleContracts\Helpers;

interface TableInterface
{
    public function setHeaders(array $headers): void;
    public function addRow(array $row): void;
    public function render(): void;
}
```

### 3.3 MarkdownConverterInterface
```php
namespace Phred\ConsoleContracts\Helpers;

interface MarkdownConverterInterface
{
    public function convert(string $markdown): string;
    public function convertFile(string $path): string;
}
```

## 4. Attributes (Optional DX)

Defined in `Phred\ConsoleContracts\Attributes`:

- `Cmd`: `#[Cmd(string $name, string $description = '')]`
- `Arg`: `#[Arg(string $name, string $description = '')]`
- `Opt`: `#[Opt(string $name, string $description = '')]`

## 5. Output Formatting Standard

Bridges must translate the following tags:
- `<success>`: Green
- `<info>`: Blue
- `<error>`: White on Red
- `<warning>`: Black on Yellow
- `<comment>`: Yellow
- `<b>`: Bold
- `<i>`: Italic
- `<u>`: Underline