90 lines
4 KiB
Markdown
90 lines
4 KiB
Markdown
|
# 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.
|