ConsoleCommand

OperationをCLIへ公開し、Help、Human／JSON結果、Exit Codeを確認する。

Console CommandはTerminalからOperationを起動するApplication入口です。#[ConsoleCommand]は公開済みExperimental Stable 1.2.1のFramework／Skeleton Adapterです。Releasesを確認し、Applicationが選んだConsole Actor、Secret配布、Process Supervisorを準備してください。

実行手順

1. AttributeとValueを定義する

OperationへCanonicalなCommand名（空白や|を含まないsegment:command）と説明を付けます。Application-owned PHP File（たとえばapp/Feature/Report/ExportReport/ExportReport.php）へOperation、Value、Outcomeを配置します。public constructor-promotedなstring、int、float、boolのValue PropertyがLong Optionになります。DefaultがあるOptionだけ省略できます。

use BlackOps\Core\Attribute\ConsoleCommand;
use BlackOps\Core\Attribute\OperationType;
use BlackOps\Core\Operation;
use BlackOps\Core\OperationValue;
use BlackOps\Core\Outcome;

#[ConsoleCommand('report:export', 'Export a report.')]
#[OperationType('report.export')]
final readonly class ExportReport implements Operation
{
    public function handle(ExportReportValue $value): ReportExported
    {
        return new ReportExported($value->reportName);
    }
}

final readonly class ExportReportValue implements OperationValue
{
    public function __construct(public string $reportName) {}
}

final readonly class ReportExported implements Outcome
{
    public function __construct(public string $reportName) {}
}

#[Sensitive]を含むValue、Outcome、配列／Object／Enum入力、位置引数はConsole Contractで受け付けません。Raw Credential、Canonical Payload、Throwableをstdoutへ追加しないでください。

2. BuildとHelpを確認する

Project RootでManifestとContainerを更新し、公開Optionを実装から確認します。

php blackops build:compile
php blackops help report:export

helpはCommand ManifestのMetadataを表示します。Handler、Database、Actor Providerを実行しないため、実行前の安全な探索に使えます。Build失敗時はBuild Artifact不在／Build ID不一致を参照します。

3. Human／JSONで実行する

php blackops report:export --report-name=weekly
php blackops report:export --report-name=weekly --json

Human成功は次のように表示されます。

Completed.

--jsonは一行のVersioned JSONをstdoutへ出します。

{"schemaVersion":1,"status":"completed","outcome":{"reportName":"weekly"}}

Deferred OperationならHumanはAccepted operation <operation-id>.、JSONはstatus: "accepted"とoperationIdを返します。受付後はInline and DeferredのStatus／Outcome手順でWorker完了を確認します。

Exit／Failure Contract

結果	Human／JSONの安全な分類	Exit
Inline Completed／Deferred Accepted	`completed`／`accepted`	`0`
Binding／Value Validation	`rejected`、`category: validation`、Violation	`2`
業務Rejected／Internal Error	`rejected`または`internal_error`	`1`

ValidationはOperation IDを伴う場合があります。RejectedのcodeとViolationのfield／rule／codeだけを調査キーにし、Exception Message、SQL、Credentialを公開Outputへ出しません。Unknown Optionや型不一致もBinding／Validationとして扱い、Exit 2を返します。

Failure時はExit CodeとSafe Errorだけを確認し、Attribute、Value、Bindingを修正してbuild:compileから再実行します。既存の失敗Operationを成功扱いに変えたり、ThrowableをOutputへ追加したりしません。

AuthorizationとActor

Console Runtimeは、ApplicationがConsoleActorProviderをBindingしていればそのActorをCurrent／Origin Actorへ設定し、未Bindingならnull Actorとconsole-runtimeの入口識別子を使います。Operationの#[Authorize] PolicyはこのContextを評価し、Denyは業務Rejected（Exit 1）として返ります。OS User、Scheduler、Secret配布、Role／Permission検索はApplication／運用責務です。

ConsoleからEphemeral Outcome Operationを実行するContractはありません。Commandを追加したらbuild:compile、help、Human／JSON、Validation、Authorization、DeferredならWorker／Statusまでを同じTaskで確認してください。詳細なCommand一覧はOperation Command、失敗時はTroubleshootingを参照します。

次に全Commandを引く

Commandの一覧、Option、Exit Code、変更有無を調べる場合は、BlackOps CLIをReferenceとして使います。