# 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**:
  ```json
  "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)