71 lines
3 KiB
Markdown
71 lines
3 KiB
Markdown
|
# 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)
|