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.

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.

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.

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.

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.

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.

namespace Phred\ConsoleContracts;

interface ConsoleExceptionInterface extends \Throwable
{
}

3. Helper Contracts (Optional)

3.1 ProgressBarInterface

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

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

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