TaskerBridges/NOTES.md

TaskerBridges: Phred CLI Interoperability Adapters

TaskerBridges is the adapter layer that allows commands written against Phred\ConsoleContracts to run inside multiple CLI runtimes with a native experience. Bridges translate Phred's runner-agnostic contracts into the APIs of specific console toolkits.

Project Phase: Idea (NOTES.md)

1. Core Vision

• Interoperability first: Write a command once, run it anywhere (Tasker native runner, Symfony Console, Laravel Artisan, etc.).
• Contracts-driven: Bridges never change command code; they only adapt ConsoleContracts to the target runtime.
• Minimal footprint: Optional, per-bridge dependencies and lazy wiring. No heavy transitive dependencies for users who don't need a given bridge.
• Native UX: When running under a given toolkit, output, helpers, and ergonomics should feel native to that toolkit.

2. Scope & Responsibilities

Bridges provide a cohesive set of adapters:

• Command adapter: Wraps CommandInterface and exposes a native command entrypoint.
• IO adapters: Implement InputInterface/OutputInterface on top of the target toolkit’s input/output.
• Helper adapters: Implement optional helper contracts (InteractionInterface, ProgressBarInterface, TableInterface, MarkdownConverterInterface).
• Markup translator: Converts Phred’s fixed markup tags (<success>, <info>, <error>, <warning>, <comment>, <b>, <i>, <u>) to the target toolkit’s styles or to raw ANSI.
• Policy alignment: Honor Verbosity levels, non-interactive mode, TTY/color detection, and sysexits.h exit code semantics.

Non-goals:

• Defining new business logic or command semantics.
• Extending the fixed markup set (bridges must support the core set only).

3. Supported Bridges (Initial Set)

• SymfonyBridge: Adapter for symfony/console (targeting Symfony 6/7 lines).
• PhredBridge (Native): Minimal adapters used by the Tasker core runner.
• LaravelBridge: Adapter for Laravel's Artisan console (illuminate/console).

3.1 Future / Potential Bridges (Roadmap)

The following bridges are identified as high-value for future development or upon community request:

• LaminasBridge: Adapter for laminas/laminas-cli.
• CakePHPBridge: Adapter for the CakePHP Console/Shell ecosystem.
• YiiBridge: Adapter for Yii 2.0 console commands (Note: Yii 3.0 uses symfony/console and may be covered by SymfonyBridge).
• AuraCliBridge: Adapter for Aura.Cli for users of the Aura library suite.
• RichOutputBridge: A bridge leveraging a library like CLImate for advanced terminal UI features (colors, progress bars) when the native Phred runner is used.

Each bridge lives under Phred\TaskerBridges\{BridgeName}\... and can be installed/used independently via Composer suggests.

4. SymfonyBridge — Design

4.1 High-Level Mapping

• Command metadata

  • CommandInterface::getName() -> Symfony\Component\Console\Command\Command::setName()
  • getDescription() -> setDescription()
  • getArguments() -> loop addArgument($name, InputArgument::OPTIONAL|REQUIRED, $description, $default)
  • getOptions() -> loop addOption($name, $shortcut, InputOption::VALUE_NONE|VALUE_OPTIONAL|VALUE_REQUIRED, $description, $default)
  • Note: ConsoleContracts currently models arguments/options as name => description (DX-minimal). Bridge MAY enhance by honoring defaults/modes if/when added to contracts in future specs.

• Execution

  • The adapter class (e.g., SymfonyCommandAdapter) extends Symfony\Component\Console\Command\Command and wraps a CommandInterface instance.
  • In execute(InputInterface $in, OutputInterface $out), it:
    1. Adapts Symfony input/output to Phred InputInterface/OutputInterface via IO adapters.
    2. Invokes $wrapped->execute($phredInput, $phredOutput).
    3. Returns the integer exit code from the wrapped command.

4.2 IO Adapters

• SymfonyInputAdapter implements GetPhred\ConsoleContracts\InputInterface by delegating to Symfony\Component\Console\Input\InputInterface methods (getArgument, getOption, hasOption).
• SymfonyOutputAdapter implements GetPhred\ConsoleContracts\OutputInterface by delegating to Symfony\Component\Console\Output\OutputInterface/Style and applying markup translation.

Verbosity mapping:

• Phred Verbosity::QUIET|NORMAL|VERBOSE|VERY_VERBOSE|DEBUG <-> Symfony OutputInterface::VERBOSITY_*.

Non-interactive:

• Respect a runner-provided flag; adapters should avoid prompts and ensure helpers also respect non-interactive mode.

4.3 Markup Translation (Fixed Set)

• Translate Phred tags into Symfony formatter equivalents or raw ANSI where Symfony lacks a native tag.
  • <success> -> Symfony style (green, bold) using SymfonyStyle or custom formatter style.
  • <info> -> Symfony <info> (blue where applicable) or custom style to match Phred’s blue guideline.
  • <error> -> white on red background.
  • <warning> -> black on yellow background.
  • <comment> -> yellow.
  • <b> -> bold; <i> -> italic; <u> -> underline (use ANSI sequences if formatter lacks direct styles).
• If output is not decorated (no TTY or colors disabled), strip tags to plain text.

4.4 Helper Adapters

• InteractionInterface -> wrap QuestionHelper (ask, confirm, secret, choice), ensuring non-interactive fallback behavior (return defaults, never block).
• ProgressBarInterface -> wrap Symfony\Component\Console\Helper\ProgressBar.
• TableInterface -> wrap Symfony\Component\Console\Helper\Table.
• MarkdownConverterInterface -> use a lightweight adapter strategy:
  • Prefer Symfony-native formatting if available; otherwise convert Markdown to Phred markup (headings -> <b>, emphasis -> <i>/<b>, links -> underline/text), then pass through normal markup translation.

4.5 Error & Exit Codes

• Return integer exit codes from wrapped command directly.
• Exceptions: Allow the runner to handle globally; optionally map known ConsoleExceptionInterface to ExitCode::USAGE|CONFIG|UNAVAILABLE|SOFTWARE as appropriate.

5. PhredBridge (Native) — Design

• Provide minimal in-house adapters usable by the Tasker runner.
• PhredOutputAdapter: translates fixed markup to ANSI escape sequences:
  • <success> -> green (e.g., \e[32m), <info> -> blue (\e[34m), <error> -> white on red (\e[97;41m), <warning> -> black on yellow (\e[30;43m), <comment> -> yellow (\e[33m), <b> -> bold (\e[1m), <i> -> italic (\e[3m), <u> -> underline (\e[4m). Reset with \e[0m.
• TTY detection and --no-interaction/--no-ansi handling (strip tags when colors disabled or piping to files).
• Provide simple InteractionInterface, ProgressBarInterface, TableInterface, and MarkdownConverterInterface implementations with zero external dependencies (basic, but reliable).

6. LaravelBridge — Design

6.1 Registration & Discovery

• Provide a TaskerServiceProvider for Laravel applications.
• Leverage Laravel Package Auto-Discovery via composer.json to register the provider automatically.
• The provider will:
  • Discover Phred commands via extra.phred-tasker or explicit container binding.
  • Register them with the Artisan application.
  • Provide configuration for non-interactive defaults and formatting.

6.2 Container & Execution

• Resolve CommandInterface instances via the Laravel Service Container (app()), favoring constructor injection.
• Wrap commands in a LaravelCommandAdapter that extends Illuminate\Console\Command.
• Delegate execution and return integer exit codes.

6.3 IO & Markup

• Reuse SymfonyBridge IO adapters internally (Artisan's IO is built on Symfony).
• Ensure Phred’s fixed markup set (<success>, <info>, <error>, <warning>, <comment>, <b>, <i>, <u>) renders natively in Artisan.

6.4 Helper Adapters

• InteractionInterface -> Map to Laravel's native console methods (ask, confirm, secret, choice).
• ProgressBarInterface / TableInterface -> Reuse SymfonyBridge adapters via Artisan.
• MarkdownConverterInterface -> Standard Phred implementation (lightweight regex/mapping).

7. Dependency & Packaging Strategy

• Composer suggest dependencies per bridge:
  • symfony/console for SymfonyBridge.
  • illuminate/console for LaravelBridge.
• Hard requirements: only php:^8.2 and getphred/console-contracts.
• Conditional wiring: Bridge factory/services check for class existence before enabling a bridge.
• Namespacing: Phred\TaskerBridges\Symfony\..., Phred\TaskerBridges\Phred\..., Phred\TaskerBridges\Laravel\....

8. Registration & Discovery

• Consumers may register bridges explicitly in DI (preferred for clarity).
• For Laravel, auto-discovery via TaskerServiceProvider is the primary path.
• For Symfony apps, provide a small integration guide to register SymfonyCommandAdapter instances in the application.
• For Tasker, PhredBridge is used by default; other bridges are opt-in and instantiated only if their dependencies are present.

9. Middleware Compatibility

• Bridges must compose with ConsoleMiddlewareInterface stacks managed by the runner. The adapter boundary is after middleware resolution so that middlewares see Phred InputInterface/OutputInterface consistently.

10. Performance & Lazy Loading

• Metadata access should be O(1) with minimal reflection at runtime. If attributes are used (#[Cmd], #[Arg], #[Opt]) and surfaced via HasAttributes, bridges continue to consume only the CommandInterface methods — no extra reflection needed in bridges.
• For toolkits that support lazy command discovery, prefer deferring heavy initialization until execution.

11. Testing Strategy (for later phases)

• Unit tests: Markup translation, verbosity mapping, non-interactive behavior, helpers integration.
• Integration tests: Execute a sample Phred command through SymfonyBridge, LaravelBridge, and PhredBridge, verify identical behavior and exit codes.

12. Architectural Decisions (Resolved)

12.1 Global Options & Flags

• Bridges will map toolkit-specific flags (e.g., Symfony’s --ansi, --no-interaction) to the Phred InputInterface and OutputInterface state.
• Purity: Commands must NOT depend on toolkit-specific options. Instead, they should rely on the standardized Phred flags:
  • -v, -vv, -vvv, -q (Verbosity)
  • -n or --no-interaction (Non-interactive)
  • --no-ansi (Color/Decoration)
• Passthrough: Toolkit-specific global options remain at the application layer and are consumed only by the bridge to configure the IO adapters.

12.2 Error Mapping Policy

• Bridges are responsible for a "Standard Translation" of common exceptions into sysexits.h exit codes.
• Mapping Strategy:
  • InvalidArgumentException -> ExitCode::USAGE (64)
  • RuntimeException -> ExitCode::SOFTWARE (70)
  • ConsoleExceptionInterface (from Contracts) -> Mapped according to category (e.g., UNAVAILABLE, CONFIG).
• Global Handler: The primary runner (Tasker) or Bridge wrapper provides the top-level try/catch to ensure these codes are returned to the shell.

12.3 Helper Feature Parity

• Guaranteed Minimum API: Bridges must implement the full ProgressBarInterface and TableInterface as defined in ConsoleContracts.
• Progressive Enhancement: Bridges MAY support advanced features (e.g., table styling, progress bar steps) if the underlying toolkit supports it, but commands should avoid depending on these for core functionality.
• Fallback: In non-TTY or non-supported environments, bridges must provide a "silent" or "degraded" implementation (e.g., printing table as a list, silencing progress bars) to prevent command failure.

Brainstorming / Open Questions

(All current open questions have been resolved and moved to Architectural Decisions.)