class-wp-codebox-cli-command.php

<?php
/**
 * WP-CLI adapter for WP Codebox public API operations.
 *
 * @package WPCodebox
 */

defined( 'ABSPATH' ) || exit;

final class WP_Codebox_CLI_Command {

	/** Register focused `wp codebox ...` commands. */
	public static function register(): void {
		$command = new self();

		\WP_CLI::add_command( 'codebox artifacts list', array( $command, 'artifacts_list' ) );
		\WP_CLI::add_command( 'codebox artifacts get', array( $command, 'artifacts_get' ) );
		\WP_CLI::add_command( 'codebox artifacts inspect', array( $command, 'artifacts_inspect' ) );
		\WP_CLI::add_command( 'codebox artifacts preflight-apply', array( $command, 'artifacts_preflight_apply' ) );
		\WP_CLI::add_command( 'codebox artifacts stage-apply', array( $command, 'artifacts_stage_apply' ) );
		\WP_CLI::add_command( 'codebox artifacts apply', array( $command, 'artifacts_apply' ) );
		\WP_CLI::add_command( 'codebox runtime descriptor', array( $command, 'runtime_descriptor' ) );
		\WP_CLI::add_command( 'codebox browser-session create', array( $command, 'browser_session_create' ) );
		\WP_CLI::add_command( 'codebox run-agent-task', array( $command, 'run_agent_task' ) );
		\WP_CLI::add_command( 'codebox run-agent-task-batch', array( $command, 'run_agent_task_batch' ) );
		\WP_CLI::add_command( 'codebox run-agent-task-fanout', array( $command, 'run_agent_task_fanout' ) );
		\WP_CLI::add_command( 'codebox run-runtime-task', array( $command, 'run_runtime_task' ) );
		\WP_CLI::add_command( 'codebox run-wordpress-workload', array( $command, 'run_wordpress_workload' ) );
		\WP_CLI::add_command( 'codebox run-runtime-package', array( $command, 'run_runtime_package' ) );
		\WP_CLI::add_command( 'codebox resolve-runtime-requirements', array( $command, 'resolve_runtime_requirements' ) );
		\WP_CLI::add_command( 'codebox wordpress-fuzz-runtime-contract', array( $command, 'wordpress_fuzz_runtime_contract' ) );
		\WP_CLI::add_command( 'codebox run-fuzz-suite', array( $command, 'run_fuzz_suite' ) );
	}

	/**
	 * List artifact bundles.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function artifacts_list( array $args, array $assoc_args ): void {
		unset( $args );
		$this->emit( WP_Codebox_API::list_artifacts( $this->input_from_args( $assoc_args ) ), $assoc_args );
	}

	/**
	 * Read one artifact bundle.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function artifacts_get( array $args, array $assoc_args ): void {
		$this->emit( WP_Codebox_API::get_artifact( $this->artifact_input( $args, $assoc_args ) ), $assoc_args );
	}

	/**
	 * Inspect one artifact bundle and its verification payload.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function artifacts_inspect( array $args, array $assoc_args ): void {
		$this->emit( WP_Codebox_API::inspect_artifact( $this->artifact_input( $args, $assoc_args ) ), $assoc_args );
	}

	/**
	 * Preflight a reviewed artifact apply without mutating the parent control plane.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function artifacts_preflight_apply( array $args, array $assoc_args ): void {
		$this->emit( WP_Codebox_API::preflight_artifact_apply( $this->apply_input( $args, $assoc_args ) ), $assoc_args );
	}

	/**
	 * Stage a reviewed artifact apply through the host approval adapter.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function artifacts_stage_apply( array $args, array $assoc_args ): void {
		$this->emit( WP_Codebox_API::stage_artifact_apply( $this->apply_input( $args, $assoc_args ) ), $assoc_args );
	}

	/**
	 * Apply a reviewed artifact through the configured apply-back adapter.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function artifacts_apply( array $args, array $assoc_args ): void {
		$this->emit( WP_Codebox_API::apply_approved_artifact( $this->apply_input( $args, $assoc_args ) ), $assoc_args );
	}

	/**
	 * Print public runtime readiness, capabilities, ability names, and contract manifest.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function runtime_descriptor( array $args, array $assoc_args ): void {
		unset( $args );
		$this->emit( WP_Codebox_API::runtime_descriptor(), $assoc_args );
	}

	/**
	 * Create a browser-executed Playground session payload.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function browser_session_create( array $args, array $assoc_args ): void {
		unset( $args );
		$this->emit( WP_Codebox_API::create_browser_session( $this->input_from_args( $assoc_args ) ), $assoc_args );
	}

	/**
	 * Run a bounded task inside an isolated WP Codebox agent sandbox.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function run_agent_task( array $args, array $assoc_args ): void {
		unset( $args );
		$this->emit( WP_Codebox_API::run_agent_task( $this->input_from_args( $assoc_args ) ), $assoc_args );
	}

	/**
	 * Run multiple bounded tasks sequentially through the public API facade.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function run_agent_task_batch( array $args, array $assoc_args ): void {
		unset( $args );
		$this->emit( WP_Codebox_API::run_agent_task_batch( $this->input_from_args( $assoc_args ) ), $assoc_args );
	}

	/**
	 * Run multiple workers with bounded WP Codebox host fanout.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function run_agent_task_fanout( array $args, array $assoc_args ): void {
		unset( $args );
		$this->emit( WP_Codebox_API::run_agent_task_fanout( $this->input_from_args( $assoc_args ) ), $assoc_args );
	}

	/**
	 * Run a public runtime task through the public API facade.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function run_runtime_task( array $args, array $assoc_args ): void {
		unset( $args );
		$this->emit( WP_Codebox_API::run_runtime_task( $this->input_from_args( $assoc_args ) ), $assoc_args );
	}

	/**
	 * Run a safe WordPress workload through the public API facade.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function run_wordpress_workload( array $args, array $assoc_args ): void {
		unset( $args );
		$this->emit( WP_Codebox_API::run_wordpress_workload( $this->input_from_args( $assoc_args ) ), $assoc_args );
	}

	/**
	 * Run a runtime package through the public API facade.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function run_runtime_package( array $args, array $assoc_args ): void {
		unset( $args );
		$this->emit( WP_Codebox_API::run_runtime_package( $this->input_from_args( $assoc_args ) ), $assoc_args );
	}

	/**
	 * Resolve runtime/provider readiness through the public API facade.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function resolve_runtime_requirements( array $args, array $assoc_args ): void {
		unset( $args );
		$this->emit( WP_Codebox_API::resolve_runtime_requirements( $this->input_from_args( $assoc_args ) ), $assoc_args );
	}

	/**
	 * Print the public WordPress fuzz runtime descriptor contract.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function wordpress_fuzz_runtime_contract( array $args, array $assoc_args ): void {
		unset( $args );
		$this->emit( WP_Codebox_API::wordpress_fuzz_runtime_contract(), $assoc_args );
	}

	/**
	 * Run a public fuzz suite through the public API facade.
	 *
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 */
	public function run_fuzz_suite( array $args, array $assoc_args ): void {
		unset( $args );
		$this->emit( WP_Codebox_API::run_fuzz_suite( $this->input_from_args( $assoc_args ) ), $assoc_args );
	}

	/**
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 * @return array<string,mixed>
	 */
	private function artifact_input( array $args, array $assoc_args ): array {
		$input                = $this->input_from_args( $assoc_args );
		$input['artifact_id'] = (string) ( $args[0] ?? $input['artifact_id'] ?? '' );

		return $input;
	}

	/**
	 * @param array<int,string>   $args       Positional arguments.
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 * @return array<string,mixed>
	 */
	private function apply_input( array $args, array $assoc_args ): array {
		$input = $this->artifact_input( $args, $assoc_args );
		if ( isset( $assoc_args['approved-files'] ) ) {
			$input['approved_files'] = $this->string_list( $assoc_args['approved-files'] );
		}

		return $input;
	}

	/**
	 * @param array<string,mixed> $assoc_args Associated arguments.
	 * @return array<string,mixed>
	 */
	private function input_from_args( array $assoc_args ): array {
		$input = array();

		if ( isset( $assoc_args['input-file'] ) ) {
			$input = array_merge( $input, $this->json_file( (string) $assoc_args['input-file'] ) );
		}

		if ( isset( $assoc_args['input-json'] ) ) {
			$input = array_merge( $input, $this->json_object( (string) $assoc_args['input-json'], 'input-json' ) );
		}

		foreach ( $assoc_args as $key => $value ) {
			if ( in_array( $key, array( 'format', 'input-file', 'input-json' ), true ) ) {
				continue;
			}

			$field           = str_replace( '-', '_', (string) $key );
			$input[ $field ] = $this->normalize_value( $field, $value );
		}

		return $input;
	}

	private function normalize_value( string $field, mixed $value ): mixed {
		if ( in_array( $field, array( 'target', 'tool_bridge', 'parent_tool_bridge', 'sandbox_tool_policy', 'policy', 'context', 'inherit', 'orchestrator', 'parent_request', 'runtime_task', 'runtime_env', 'playground', 'browser_runner', 'runtime', 'blueprint', 'apply_target', 'aggregator', 'suite', 'package', 'requirements', 'runner_capabilities', 'metadata' ), true ) ) {
			return $this->json_object( (string) $value, $field );
		}

		if ( in_array( $field, array( 'allowed_tools', 'expected_artifacts', 'agent_bundles', 'provider_plugin_paths', 'secret_env', 'mounts', 'workspaces', 'runtime_stack_mounts', 'runtime_state_mounts', 'runtime_config_mounts', 'runtime_overlays', 'browser_plugins', 'artifact_files', 'approved_files', 'workers', 'dependencies', 'tasks', 'cases', 'coverage', 'capabilities' ), true ) ) {
			return $this->json_or_list( (string) $value, $field );
		}

		if ( in_array( $field, array( 'max_turns', 'task_timeout_seconds', 'preview_hold_seconds', 'preview_port', 'agent_id', 'user_id', 'concurrency' ), true ) ) {
			return (int) $value;
		}

		return $value;
	}

	/** @return array<string,mixed> */
	private function json_file( string $path ): array {
		$contents = is_readable( $path ) ? file_get_contents( $path ) : false;
		if ( false === $contents ) {
			\WP_CLI::error( 'Input file is not readable: ' . $path );
		}

		return $this->json_object( (string) $contents, 'input-file' );
	}

	/** @return array<string,mixed> */
	private function json_object( string $json, string $field ): array {
		$decoded = WP_Codebox_Json::decode_object( $json );
		if ( null === $decoded ) {
			\WP_CLI::error( $field . ' must be a JSON object.' );
		}

		return $decoded;
	}

	/** @return array<int,mixed> */
	private function json_or_list( string $value, string $field ): array {
		$trimmed = trim( $value );
		if ( str_starts_with( $trimmed, '[' ) ) {
			$decoded = WP_Codebox_Json::decode_list( $trimmed );
			if ( null === $decoded ) {
				\WP_CLI::error( $field . ' must be a JSON array.' );
			}

			return $decoded;
		}

		return $this->string_list( $value );
	}

	/** @return string[] */
	private function string_list( mixed $value ): array {
		$items = is_array( $value ) ? $value : explode( ',', (string) $value );

		return array_values(
			array_filter(
				array_map( static fn( mixed $item ): string => trim( (string) $item ), $items ),
				static fn( string $item ): bool => '' !== $item
			)
		);
	}

	/** @param array<string,mixed>|WP_Error $result Service result. */
	private function emit( array|WP_Error $result, array $assoc_args ): void {
		if ( is_wp_error( $result ) ) {
			\WP_CLI::error( $result->get_error_message() );
		}

		$format = (string) ( $assoc_args['format'] ?? 'json' );
		if ( 'json' !== $format ) {
			\WP_CLI::warning( 'WP Codebox WP-CLI wrappers currently emit JSON; ignoring --format=' . $format . '.' );
		}

		\WP_CLI::line( $this->json_encode( $result ) );
	}

	/** @param array<string,mixed> $data Data to encode. */
	private function json_encode( array $data ): string {
		return WP_Codebox_Json::encode( $data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES, '{}' );
	}
}