README

A CLI adapter and Pilot domain extension for the PilotPHP Agent-First framework.

ConsolePackage registers a domain ConsoleBuildStage that compiles ConsoleCommandDeclaration records from contracts-owned declaration replay into a deterministic console/command-map.json artifact. At process startup the application loads that finalized artifact into an immutable CommandMap, then ConsoleRuntime parses one argv vector, builds a typed invocation, and drives a single call through WorkerLifecycle.

It does not discover packages, scan the filesystem, read Composer metadata, auto-register Symfony Console commands, or implement operation dispatch.

Installation

composer require pilotphp/console

Requires PHP 8.5, pilotphp/contracts ^0.1.4@dev, and pilotphp/runtime ^0.1.4@dev (because ConsoleRuntime uses WorkerLifecycle).

Package discovery

Core reads the fixed path pilot/package.json inside the Composer package root. There is no extra.pilotphp.manifest.

pilot/package.json
  → entrypoint ConsolePackage
  → descriptor() / register() → ConsoleBuildStage

requiresPackages is empty: Composer type dependencies are not Pilot activation dependencies. Capability: pilotphp.console.

Build and runtime

active packages → DeclarationReplay → ConsoleBuildStage
  → console/command-map.json → ConsoleArtifactLoader → CommandMap
  → ConsoleRuntime → WorkerLifecycle → operation dispatcher

Runnable sketch

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use PilotPHP\Console\Artifact\ConsoleArtifactLoader;
use PilotPHP\Console\Input\DefaultConsoleInputFactory;
use PilotPHP\Console\IO\StreamConsoleErrorOutput;
use PilotPHP\Console\IO\StreamConsoleOutput;
use PilotPHP\Console\Runtime\ConsoleRuntime;
use PilotPHP\Contracts\Kernel\KernelInterface;
use PilotPHP\Contracts\Runtime\InvocationInterface;

$commands = new ConsoleArtifactLoader()->loadFromBytes(
    $finalizedConsoleArtifactBytes, // supplied by application bootstrap
);

$kernel = new class implements KernelInterface {
    public function boot(): void {}
    public function reset(): void {}
    public function shutdown(): void {}

    public function invoke(InvocationInterface $invocation): object
    {
        return new \PilotPHP\Console\Runtime\ConsoleResult('ok');
    }
};

$runtime = new ConsoleRuntime(
    argv: $argv,
    commands: $commands,
    inputFactory: new DefaultConsoleInputFactory(),
    requestScope: $requestScope,
    output: new StreamConsoleOutput(STDOUT),
    errorOutput: new StreamConsoleErrorOutput(STDERR),
    applicationName: 'acme',
    applicationVersion: '1.2.3',
);

exit($runtime->run($kernel));

Application packages register commands with $registration->add(new ConsoleCommandDeclaration(...)). bin/pilot lives in the application skeleton, not in this package.

Public API (summary)

ConsolePackage — discoverable entrypoint; registers ConsoleBuildStage
ConsoleCommandDeclaration / ArgumentDefinition / OptionDefinition
ConsoleBuildStage / PreparedConsoleBuildStage / ConsoleArtifact
ConsoleArtifactEncoder / ConsoleArtifactLoader / ConsoleArtifactSchema
CommandMap / CompiledCommand
ArgvParser / ParsedArgv
ConsoleInputFactoryInterface / DefaultConsoleInputFactory / ConsoleInput
ConsoleRuntime (+ state, summary, exit codes, result rendering)
IO interfaces and stream/buffer adapters
HelpRenderer

Details: Public API.

Exit values

Value	Enum case	Meaning
0	`Success`	Successful meta command or successful invocation
1	`InvalidUsage`	Known command with malformed argv
2	`CommandNotFound`	First token did not resolve to a command or alias
3	`InvocationFailure`	Worker processed the invocation and failed while healthy
4	`BootFailure`	`WorkerLifecycle::boot()` failed; shutdown was not attempted
5	`ShutdownFailure`	`WorkerLifecycle::shutdown()` failed; overrides earlier exit
6	`InternalFailure`	Poisoned worker, output failure, or other adapter failure

Documentation

Development

make install
make check
make benchmark

make check validates Composer metadata, checks style, runs PHPStan, and runs the tests. Benchmarks are measurements, not release gates.

pilotphp / console

Maintainers

Package info

Statistics

Security