Tasker/SPECS.md

Tasker Specification

This document defines the technical specifications for the getphred/tasker runner, the central CLI manager for the Phred Framework.

1. Core Architecture

Tasker is a command runner that orchestrates command discovery, dependency injection, and execution using ConsoleContracts and TaskerBridges.

1.1 Command Discovery

• Discovery Strategy:
  1. Explicit Registration: Commands registered directly via the Tasker API.
  2. Composer Discovery: Scans installed packages for the extra.phred-tasker key in composer.json.
• Composer Schema:

  "extra": {
      "phred-tasker": {
          "commands": [
              "Phred\\Library\\Command\\ExampleCommand"
          ]
      }
  }
  

1.2 Dependency Injection

• Tasker must be initialized with a PSR-11 ContainerInterface.
• All commands are resolved from the container to support constructor injection.

2. Runner Behavior

2.1 Argument & Option Parsing

• Tasker will implement a basic argv parser to support standard flags:
  • -v, -vv, -vvv, -q (Verbosity)
  • -n or --no-interaction (Non-interactive)
  • --no-ansi (Color/Decoration)
  • -h, --help (Help information)

2.2 Execution Lifecycle

1. Initialize Runner: Boot with a PSR-11 container.
2. Discover Commands: Resolve commands from container and/or composer.json.
3. Parse Input: Detect the target command and global flags.
4. Resolve Command: Retrieve the CommandInterface instance from the container.
5. Orchestrate Middleware: Apply any registered ConsoleMiddlewareInterface instances.
6. Execute: Call execute() on the command (or middleware chain).
7. Handle Output & Errors: Capture exit codes and map exceptions to sysexits.h standards.

2.3 Middleware Execution

1. Middleware Resolution: Retrieve registered middleware from the PSR-11 container.
2. Execution Chain: Construct a callable chain where each middleware can inspect/modify the Command, Input, and Output before passing control to the next layer.
3. Command Execution: The final layer of the chain executes the command's execute() method.

3. Global Commands

Tasker provides the following built-in commands:

• list: Lists all registered commands.
• help: Displays help for a specific command, including arguments and options.

4. Middleware Stack

Tasker implements a standard middleware runner:

• Middleware is resolved from the DI container.
• Middleware handles cross-cutting concerns (logging, locking, etc.).
• The execution chain is wrapped in a top-level try/catch to ensure clean exit codes.

5. Exit Code Standards

Tasker follows the sysexits.h standard. The runner will capture any \Throwable and map it as follows:

• Phred\ConsoleContracts\ConsoleExceptionInterface -> Mapped according to internal implementation.
• \InvalidArgumentException -> ExitCode::USAGE (64)
• \RuntimeException -> ExitCode::SOFTWARE (70)
• All other exceptions -> ExitCode::SOFTWARE (70)