# TaskerBridges Specification

This document defines the technical specifications for the `getphred/tasker-bridges` package, which adapts `Phred\ConsoleContracts` for various CLI runtimes.

## 1. Bridge Strategy

Bridges act as adapters between the standardized Phred CLI contracts and the native APIs of target console toolkits.

### 1.1 Universal Bridge Requirements
All bridges must:
- Adapt command metadata (name, description, arguments, options) to the native format.
- Wrap execution to translate native input/output to Phred `InputInterface` and `OutputInterface`.
- Implement fixed markup translation.
- Map native verbosity and interaction states to Phred's standardized levels/flags.
- Handle common exceptions and map them to `sysexits.h` exit codes.

## 2. SymfonyBridge

**Target**: `symfony/console` (v6.x and v7.x)
**Namespace**: `Phred\TaskerBridges\Symfony`

### 2.1 SymfonyCommandAdapter
- Extends `Symfony\Component\Console\Command\Command`.
- Wraps a `Phred\ConsoleContracts\CommandInterface`.
- Maps Phred metadata to Symfony's `setName`, `setDescription`, `addArgument`, and `addOption`.

### 2.2 Symfony IO Adapters
- `SymfonyInputAdapter`: Wraps `Symfony\Input\InputInterface` and implements `Phred\ConsoleContracts\InputInterface`.
- `SymfonyOutputAdapter`: Wraps `Symfony\Output\OutputInterface` and implements `Phred\ConsoleContracts\OutputInterface`.

### 2.3 Symfony Helper Adapters
- `SymfonyInteractionAdapter`: Wraps `Symfony\Helper\QuestionHelper` to implement `Phred\ConsoleContracts\InteractionInterface`.
- `SymfonyProgressBarAdapter`: Wraps `Symfony\Helper\ProgressBar`.
- `SymfonyTableAdapter`: Wraps `Symfony\Helper\Table`.

## 3. LaravelBridge

**Target**: `illuminate/console` (v10.x and v11.x)
**Namespace**: `Phred\TaskerBridges\Laravel`

### 3.1 LaravelCommandAdapter
- Extends `Illuminate\Console\Command`.
- Wraps a `Phred\ConsoleContracts\CommandInterface`.
- Internally uses Symfony adapters for IO and helpers where applicable (as Artisan is built on Symfony).

### 3.2 LaravelServiceProvider
- Handles auto-discovery of Phred commands from `composer.json` (`extra.phred-tasker`).
- Registers commands within the Laravel container and Artisan application.

## 4. PhredBridge (Native)

**Target**: Tasker Core Runner
**Namespace**: `Phred\TaskerBridges\Phred`

### 4.1 Native Adapters
- Provides ANSI-based implementations for `OutputInterface`.
- Provides lightweight implementations for `InteractionInterface`, `ProgressBarInterface`, and `TableInterface` with zero external dependencies.

### 4.2 MarkdownConverterInterface (Native)
- **Implementation**: Provides a regex-based parser to translate standard Markdown (headings, emphasis, links) into the fixed Phred markup tag set (`<b>`, `<i>`, `<u>`, etc.).

## 5. Markup Translation Mapping

| Phred Tag | Phred Color/Style | Symfony/Laravel Implementation | Native Implementation (ANSI) |
|:---|:---|:---|:---|
| `<success>` | Green | Custom `SymfonyStyle` or Formatter style | `\e[32m` |
| `<info>` | Blue | Custom Formatter style | `\e[34m` |
| `<error>` | White on Red | `<error>` tag | `\e[97;41m` |
| `<warning>` | Black on Yellow | Custom Formatter style | `\e[30;43m` |
| `<comment>` | Yellow | `<comment>` tag | `\e[33m` |
| `<b>` | Bold | `\e[1m` (if not native) | `\e[1m` |
| `<i>` | Italic | `\e[3m` (if not native) | `\e[3m` |
| `<u>` | Underline | `\e[4m` (if not native) | `\e[4m` |

## 6. Exit Code Translation

Bridges should map the following standard exceptions:
- `InvalidArgumentException` -> `ExitCode::USAGE` (64)
- `RuntimeException` -> `ExitCode::SOFTWARE` (70)
- `LogicException` -> `ExitCode::SOFTWARE` (70)
- `Phred\ConsoleContracts\ConsoleExceptionInterface` implementations -> mapped per category.

## 7. Global Options & Flags

Bridges are responsible for mapping toolkit-specific global options to the Phred state:
- Symfony `--ansi` / `--no-ansi` -> `OutputInterface::setDecorated()`
- Symfony `-v` / `-vv` / `-vvv` -> `OutputInterface::setVerbosity()`
- Symfony `--no-interaction` -> `InteractionInterface` behavior (non-blocking).
- Laravel specific variants of the above.