BlackOps CLI

Project Rootのblackopsから利用できるBuild、Worker、Operation Inspect／Viewer、Retention Commandを確認する。

Project RootのblackopsはApplication所有の薄いEntrypointです。Framework Packageが提供するCommandを、ApplicationのConfiguration Snapshotから起動します。EntrypointへCommand実装をCopyしないため、composer update blackops/framework後は同じ入口から更新済みCommandを利用できます。

php blackops list
php blackops help build:compile

listはDatabase接続、Migration Scan、Compiled Container、PCNTL、Retention Runtimeを要求しません。ValidなCommand ManifestがあればApplication CommandのMetadataだけを表示します。Command固有のhelpは、そのCommandのDefinitionを得るためCompiled Containerから一度だけ解決します。

Canonical Journal の Observer 再配送は Observer Replay を参照してください。journal:observer:replay の Selector、Dry-run、Confirm、Resume、At-least-once と安全な Audit 境界を説明しています。

BuildとDiscovery

operation:list
build:compile

Operation ListとBuildだけがconfig/operations.phpのOperation Source Rootを探索します。Buildはさらにconfig/app.phpのcommand_discovery RootからSymfony #[AsCommand]を探索し、Operation Manifest、HTTP Manifest、Frontend Contract Manifest、Command Manifest、DI Containerを同じBuild IDで生成します。TypeScript Source Treeは変更しません。

Command ManifestがMissing／Invalid／Build ID不一致の場合、Application Commandは登録せずFramework Commandだけで起動します。Source ScanへFallbackしないため、壊れたArtifactからもphp blackops build:compileで復旧できます。

Operation Command

Operation Classへ#[ConsoleCommand]を付けると、build:compileがCommand ManifestへCLI契約を固定します。OperationValueのpublic constructor-promotedなstring、int、float、bool PropertyはLong Named Optionになり、例えば$orderReferenceは--order-referenceになります。

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, '/reports/' . $value->reportName . '.json');
    }
}

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

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

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

{"schemaVersion":1,"status":"completed","outcome":{"reportName":"weekly","location":"/reports/weekly.json"}}

CommandはHTTPと同じValidation、Authorization、Inline／Deferred Lifecycle、Journal、Transactionを通ります。--jsonは一行JSONをstdoutへ出し、成功／Deferred受付はExit 0、CLI Binding／ValidationはExit 2、その他Rejected／Internal ErrorはExit 1です。位置引数、未知Option、配列／Object／Enum入力、#[Sensitive]を含むValueやOutcomeは受け付けません。省略できるのはConstructor Defaultを持つOptionだけです。

Global listとOperation CommandのhelpはManifest Metadataだけを使い、Handler、Container、Database、Actor Providerを解決しません。実行時だけArtifactからOperation Runtimeを構成します。

Frontend

frontend:generate
frontend:check

frontend:generateは現在のFrontend Contract Artifactからconfig/frontend.phpのOutputへFramework-neutral TypeScript ESMを全再生成します。frontend:checkは生成せず、Expected Treeと既存TreeのPath／Bytes／余剰Fileを比較します。Checkの固定ContractはFresh 0、Missing／Drift 1、Invalid 2です。どちらもbuild:compileを暗黙実行せず、ArtifactのMissing、Stale、Build ID不一致を拒否します。

php blackops build:compile
php blackops frontend:generate
php blackops frontend:check

Frontend BridgeはRepository mainのExperimental Surfaceであり、Stable 1.1.0には含まれません。

Database

database:status
database:migrate
database:seed

Status、Dry-run、MigrateはFramework MigrationとApplication Migrationを一つの明示Deployment Flowで扱います。

database:seedはFreshなCompiled ContainerからApplicationのRoot Seederを一度実行します。標準順序はdatabase:migrate -> build:compile -> database:seedです。MigrationやBuildを暗黙実行しません。

Execution

worker:run
operation:inspect <operation-id> [--json]
operation:viewer

Deferred Workerは対象Command実行時にだけDatabase、Transport、Lifecycle、Heartbeatを構成します。

operation:inspectは一つのOperation IDからSafe Diagnosticsを読みます。既定はHuman形式、--jsonはschemaVersion: 1のMachine-readable形式です。成功時はDataをstdout、Command自体のErrorをstderrへ出します。

operation:viewerはRead-onlyのLocal Viewerを明示起動します。config/diagnostics.php のEnable Gateも必要で、起動ごとに一度だけBootstrap URLをstdoutへ出します。既定は無効、Quickstart Localだけ有効です。BindはLoopbackに限定され、GET／HEAD以外は変更処理として受け付けません。

RetentionとScheduler

retention:plan
retention:purge
scheduler:run
scheduler:daemon

PlanとDry-runは変更を行いません。Purgeは--confirmを要求し、Schedulerも明示Commandでのみ開始します。

Generator

make:operation
make:migration
make:auth
make:seeder

make:operationとmake:migrationはExperimental Stable 1.1.0で利用できます。make:authとmake:seederはRepository mainのExperimental Commandです。make:authはApplication-owned Identity Domain、DBAL Adapter、Ephemeral Register／Login／Logout、Session Migrationを一度だけ生成します。make:seederはapp/Infrastructure/Seed/へ空のSeederを生成します。詳細はGenerators、Seeder、Session Authentication Starterを参照してください。生成済みApplication SourceはFramework Updateで自動変更されません。

1.0.0のbin/blackopsとblackops:* Commandは互換対象ではありません。1.1.0への移行ではProject Root blackopsとPrefixなしCommandへ更新してください。

Outbox delivery

BlackOps CLIはoutbox:relay:run、outbox:relay:daemon、outbox:dead-letter:retry <record-id> --actor=<actor> --reason=<reason>を提供します。出力は件数だけで、Payload、Context、SQL、Credential、Throwableの詳細は表示しません。