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.

4 KiB Raw Permalink Blame History