wordpress-command-runners.ts

import { createHash, randomBytes } from "node:crypto"
import { mkdir, writeFile } from "node:fs/promises"
import { dirname, join } from "node:path"
import type { BrowserArtifact } from "./browser-artifacts.js"
import { promoteBrowserMetricsToBenchResults } from "./browser-metrics.js"
import { writePluginCheckArtifacts, writeThemeCheckArtifacts, type PluginCheckArtifact, type ThemeCheckArtifact } from "./check-artifacts.js"
import {
  abilityInputFromArgs,
  abilityPrincipalFromArgs,
  abilityResponseToCommandEnvelope,
  abilityPhpCode,
  expectedAbilityResultSchemaFromArgs,
  argValue,
  benchRunCode,
  booleanArg,
  cleanWpCliOutput,
  commaListArg,
  CORE_PHPUNIT_RESULT_FILE,
  corePhpunitRunCode,
  jsonArrayArg,
  jsonObjectArg,
  nonNegativeIntegerArg,
  normalizePhpCode,
  normalizePluginCheckOutput,
  normalizeThemeCheckOutput,
  pageLoadInputFromArgs,
  pageLoadPhpCode,
  cacheChurnObservationInputFromArgs,
  cacheChurnObservationPhpCode,
  restPerformanceObservationInputFromArgs,
  restPerformanceObservationPhpCode,
  phpunitRunCode,
  phpunitMultisitePreinstallCode,
  pluginStateInputFromArgs,
  pluginStatePhpCode,
  PLUGIN_PHPUNIT_RESULT_FILE,
  positiveIntegerArg,
  httpRequestInputFromArgs,
  runHttpRequest,
  restRequestInputFromArgs,
  restRequestPhpCode,
  runtimeAdminActionInventoryPhpCode,
  runtimeInventoryPhpCode,
  type RuntimeInventorySurface,
  runtimeDiscoveryPhpCode,
  runtimeDiscoverySurfacesFromArgs,
  wordpressExecutionActionInputFromArgs,
  wordpressExecutionActionPhpCode,
  pluginSetupInputFromArgs,
  themeCheckRunCode,
  themeSetupInputFromArgs,
} from "./commands.js"
import { bootstrapAbilityPhpCode, bootstrapPhpCode, phpCodeFromArgs, splitLeadingStrictTypesDeclare } from "./php-bootstrap.js"
import { assertPlaygroundResponseOk, attachPlaygroundDiagnostics, completedPlaygroundCommandError, playgroundCommandDiagnosticText, type PlaygroundRunResponse } from "./playground-command-errors.js"
import type { PlaygroundCliServer } from "./preview-server.js"
import { clearPluginPhpunitJunitResult, persistCorePhpunitResult, persistPluginPhpunitCompletedResult, persistPluginPhpunitJunitResult, persistPluginPhpunitResult, persistVfsDiagnosticFileToHost, phpunitJunitCaptureDiagnostic, readCorePhpunitDiagnostic, readPluginPhpunitCompletedResult, readPluginPhpunitDiagnostic, readPluginPhpunitDiscoveryResult } from "./runtime-diagnostics.js"
import { phpunitExecutionSemantics, requiresManagedMultisitePreinstall } from "./phpunit-command-semantics.js"
import { parsePhpunitOutput } from "./phpunit-test-results.js"
import { runRuntimeExternalHttpLoad, waitForRuntimePreviewReady, type RuntimeExternalHttpLoadResult } from "./external-http-load.js"
import type { RuntimeWpCliBridge } from "./runtime-wp-cli-bridge.js"
import { COMMAND_DIAGNOSTICS_ARTIFACT_SCHEMA, DEFAULT_CAPTURED_ARTIFACT_MAX_BYTES, PERFORMANCE_OBSERVATION_SCHEMA, captureArtifactFile, commandDiagnosticsCaptureArgs, commandDiagnosticsCaptureSpecFromArgs, createRuntimeCommandResultEnvelope, redactJsonValue, type ExecutionSpec, type MountSpec, type PerformanceObservation, type RuntimeCommandResultEnvelope, type RuntimeCreateSpec, type RuntimeEpisodeTraceRef, type WorkspaceRecipeResultPath } from "@automattic/wp-codebox-core"
import { wordpressUserSessionFromCommandArgs } from "./wordpress-user-sessions.js"
import { executeHostHttpTransportRequest, parseHostHttpTransportMessage } from "./host-http-transport.js"

type RunPlaygroundCommand = (command: string, server: PlaygroundCliServer, options: { code: string } | { scriptPath: string }) => Promise<PlaygroundRunResponse>
type RunWpCliCommand = (server: PlaygroundCliServer, argv: string[]) => Promise<PlaygroundRunResponse>
type CreateRuntimeWpCliBridge = (server: PlaygroundCliServer) => Promise<RuntimeWpCliBridge>

const BROWSER_PROVIDER_PROXY_SCHEMA = "wp-codebox/browser-provider-proxy-request/v1"
const BROWSER_PROVIDER_PROXY_MAX_BYTES = 1_000_000

type BrowserProviderProxyMessage = {
  schema: typeof BROWSER_PROVIDER_PROXY_SCHEMA
  [key: string]: unknown
}

export async function runPhpCommand({
  artifactRoot,
  createRuntimeWpCliBridge,
  runPlaygroundCommand,
  runtimeSpec,
  server,
  spec,
}: {
  artifactRoot: string
  createRuntimeWpCliBridge: CreateRuntimeWpCliBridge
  runPlaygroundCommand: RunPlaygroundCommand
  runtimeSpec: RuntimeCreateSpec
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<string | RuntimeCommandResultEnvelope> {
  const code = await phpCodeFromArgs(spec.args ?? [])
  const diagnosticsCapture = commandDiagnosticsCaptureSpecFromArgs(spec.args ?? [], spec.diagnostics)
  const bootstrapArgs = diagnosticsCapture ? [...(spec.args ?? []), ...commandDiagnosticsCaptureArgs(diagnosticsCapture)] : spec.args ?? []
  const marker = diagnosticsCapture ? `WP_CODEBOX_COMMAND_DIAGNOSTICS:${randomBytes(16).toString("hex")}:` : undefined
  const commandCode = diagnosticsCapture && marker ? runPhpCommandDiagnosticsPhp(code, marker, diagnosticsCapture.maxItems ?? 50, diagnosticsCapture.maxBytes ?? 64 * 1024) : code
  const bridge = argValue(spec.args ?? [], "wp-cli-bridge") === "1" ? await createRuntimeWpCliBridge(server) : undefined
  let response: PlaygroundRunResponse
  const removeProviderProxy = installPhpMessageBridges(server, runtimeSpec.policy.network)
  try {
    response = await runPlaygroundCommand("wordpress.run-php", server, { code: bootstrapPhpCode(runtimeSpec, commandCode, bootstrapArgs, bridge, undefined, server.hostHttpTransport) })
    assertPlaygroundResponseOk("wordpress.run-php", response)
  } finally {
    await removeProviderProxy?.()
    if (bridge) {
      await bridge.close()
    }
  }

  if (!diagnosticsCapture || !marker) {
    return response.text
  }

  const parsed = splitRunPhpDiagnostics(response.text, marker)
  if (!parsed.diagnostics) {
    return response.text
  }

  const artifact = await writeCommandDiagnosticsArtifact(artifactRoot, parsed.diagnostics)
  return createRuntimeCommandResultEnvelope({
    status: "ok",
    stdout: parsed.stdout,
    diagnostics: parsed.diagnostics,
    artifactRefs: [artifact],
  })
}

export async function runWordPressExecutionActionCommand({
  command,
  runPlaygroundCommand,
  runtimeSpec,
  server,
  spec,
}: {
  command: "wordpress.invoke-hook" | "wordpress.invoke-cron-event"
  runPlaygroundCommand: RunPlaygroundCommand
  runtimeSpec: RuntimeCreateSpec
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<string> {
  const input = wordpressExecutionActionInputFromArgs(spec.args ?? [], command)
  const response = await runPlaygroundCommand(command, server, { code: bootstrapPhpCode(runtimeSpec, wordpressExecutionActionPhpCode(input, command), spec.args ?? []) })
  assertPlaygroundResponseOk(command, response)
  return response.text
}

interface RunPhpDiagnosticsPayload {
  schema: typeof COMMAND_DIAGNOSTICS_ARTIFACT_SCHEMA
  command: "wordpress.run-php"
  capture: string[]
  limits: { maxItems: number; maxBytes: number }
  summary: { captured: number; truncated: boolean; bytes: number }
  performance?: PerformanceObservation
  wpdbQueries?: Array<{ fingerprint: string; count: number; totalTimeMs?: number; sampleMs?: number; caller?: string }>
}

function runPhpCommandDiagnosticsPhp(code: string, marker: string, maxItems: number, maxBytes: number): string {
  const command = splitLeadingStrictTypesDeclare(code)

  return `
${command.strictTypesDeclare ? `${command.strictTypesDeclare}\n` : ""}$wp_codebox_command_observation_started_at = gmdate('Y-m-d\\TH:i:s.v\\Z');
$wp_codebox_command_observation_start_time = microtime(true);
$wp_codebox_command_observation_start_memory = memory_get_usage(true);
$wp_codebox_command_diagnostics_start = isset($GLOBALS['wpdb']->queries) && is_array($GLOBALS['wpdb']->queries) ? count($GLOBALS['wpdb']->queries) : 0;
${command.body}
$wp_codebox_command_observation_finished_at = gmdate('Y-m-d\\TH:i:s.v\\Z');
$wp_codebox_command_observation_duration_ms = round((microtime(true) - $wp_codebox_command_observation_start_time) * 1000, 3);
$wp_codebox_command_observation_end_memory = memory_get_usage(true);
$wp_codebox_command_diagnostics_queries = array();
$wp_codebox_command_diagnostics_query_count = 0;
$wp_codebox_command_diagnostics_query_time_ms = 0.0;
$wp_codebox_command_diagnostics_queries_available = isset($GLOBALS['wpdb']->queries) && is_array($GLOBALS['wpdb']->queries);
if ($wp_codebox_command_diagnostics_queries_available) {
    $wp_codebox_command_diagnostics_slice = array_slice($GLOBALS['wpdb']->queries, $wp_codebox_command_diagnostics_start);
    foreach ($wp_codebox_command_diagnostics_slice as $wp_codebox_command_diagnostics_query) {
        $wp_codebox_command_diagnostics_sql = is_array($wp_codebox_command_diagnostics_query) && isset($wp_codebox_command_diagnostics_query[0]) ? (string) $wp_codebox_command_diagnostics_query[0] : '';
        if ($wp_codebox_command_diagnostics_sql === '') {
            continue;
        }
        $wp_codebox_command_diagnostics_query_count++;
        $wp_codebox_command_diagnostics_elapsed_ms = is_array($wp_codebox_command_diagnostics_query) && isset($wp_codebox_command_diagnostics_query[1]) ? round(((float) $wp_codebox_command_diagnostics_query[1]) * 1000, 3) : null;
        if ($wp_codebox_command_diagnostics_elapsed_ms !== null) {
            $wp_codebox_command_diagnostics_query_time_ms += $wp_codebox_command_diagnostics_elapsed_ms;
        }
        $wp_codebox_command_diagnostics_fingerprint = preg_replace('/\\s+/', ' ', trim($wp_codebox_command_diagnostics_sql));
        $wp_codebox_command_diagnostics_fingerprint = preg_replace("/'(?:''|[^'])*'/", "'?'", $wp_codebox_command_diagnostics_fingerprint);
        $wp_codebox_command_diagnostics_fingerprint = preg_replace('/\\b\\d+(?:\\.\\d+)?\\b/', '?', $wp_codebox_command_diagnostics_fingerprint);
        $wp_codebox_command_diagnostics_key = hash('sha256', $wp_codebox_command_diagnostics_fingerprint);
        if (!isset($wp_codebox_command_diagnostics_queries[$wp_codebox_command_diagnostics_key])) {
            $wp_codebox_command_diagnostics_queries[$wp_codebox_command_diagnostics_key] = array(
                'fingerprint' => $wp_codebox_command_diagnostics_fingerprint,
                'count' => 0,
                'sampleMs' => $wp_codebox_command_diagnostics_elapsed_ms,
                'totalTimeMs' => 0,
                'caller' => is_array($wp_codebox_command_diagnostics_query) && isset($wp_codebox_command_diagnostics_query[2]) ? substr((string) $wp_codebox_command_diagnostics_query[2], 0, 240) : null,
            );
        }
        $wp_codebox_command_diagnostics_queries[$wp_codebox_command_diagnostics_key]['count']++;
        if ($wp_codebox_command_diagnostics_elapsed_ms !== null) {
            $wp_codebox_command_diagnostics_queries[$wp_codebox_command_diagnostics_key]['totalTimeMs'] = round($wp_codebox_command_diagnostics_queries[$wp_codebox_command_diagnostics_key]['totalTimeMs'] + $wp_codebox_command_diagnostics_elapsed_ms, 3);
        }
    }
}
$wp_codebox_command_observation_fingerprints = array_values($wp_codebox_command_diagnostics_queries);
$wp_codebox_command_observation_repeated_queries = array_values(array_filter($wp_codebox_command_observation_fingerprints, static function ($wp_codebox_command_observation_query) {
    return isset($wp_codebox_command_observation_query['count']) && $wp_codebox_command_observation_query['count'] > 1;
}));
$wp_codebox_command_diagnostics_payload = array(
    'schema' => 'wp-codebox/command-diagnostics/v1',
    'command' => 'wordpress.run-php',
    'capture' => array('wpdb-queries'),
    'limits' => array('maxItems' => ${maxItems}, 'maxBytes' => ${maxBytes}),
    'summary' => array('captured' => 0, 'truncated' => false, 'bytes' => 0),
    'performance' => array(
        'schema' => '${PERFORMANCE_OBSERVATION_SCHEMA}',
        'command' => 'wordpress.run-php',
        'timing' => array(
            'status' => 'captured',
            'startedAt' => $wp_codebox_command_observation_started_at,
            'finishedAt' => $wp_codebox_command_observation_finished_at,
            'durationMs' => $wp_codebox_command_observation_duration_ms,
        ),
        'memory' => array(
            'status' => 'captured',
            'startBytes' => $wp_codebox_command_observation_start_memory,
            'endBytes' => $wp_codebox_command_observation_end_memory,
            'deltaBytes' => $wp_codebox_command_observation_end_memory - $wp_codebox_command_observation_start_memory,
            'peakBytes' => memory_get_peak_usage(true),
        ),
        'database' => array(
            'status' => $wp_codebox_command_diagnostics_queries_available ? 'captured' : 'uncaptured',
            'reason' => $wp_codebox_command_diagnostics_queries_available ? null : 'wpdb_queries_unavailable',
            'queryCount' => $wp_codebox_command_diagnostics_query_count,
            'totalTimeMs' => round($wp_codebox_command_diagnostics_query_time_ms, 3),
            'fingerprints' => $wp_codebox_command_observation_fingerprints,
            'repeatedQueries' => $wp_codebox_command_observation_repeated_queries,
        ),
        'hooks' => array('status' => 'unsupported', 'reason' => 'hook_timing_not_instrumented', 'timings' => array()),
        'network' => array('status' => 'unsupported', 'reason' => 'php_command_has_no_network_capture'),
        'browser' => array('status' => 'unsupported', 'reason' => 'not_a_browser_observation'),
        'metadata' => array('runner' => 'wp-codebox/runtime-playground', 'surface' => 'php-command'),
    ),
    'wpdbQueries' => $wp_codebox_command_observation_fingerprints,
);
$wp_codebox_command_diagnostics_payload['summary']['captured'] = count($wp_codebox_command_diagnostics_payload['wpdbQueries']);
if (count($wp_codebox_command_diagnostics_payload['wpdbQueries']) > ${maxItems}) {
    $wp_codebox_command_diagnostics_payload['wpdbQueries'] = array_slice($wp_codebox_command_diagnostics_payload['wpdbQueries'], 0, ${maxItems});
    $wp_codebox_command_diagnostics_payload['performance']['database']['fingerprints'] = $wp_codebox_command_diagnostics_payload['wpdbQueries'];
    $wp_codebox_command_diagnostics_payload['performance']['database']['repeatedQueries'] = array_values(array_filter($wp_codebox_command_diagnostics_payload['wpdbQueries'], static function ($wp_codebox_command_observation_query) {
        return isset($wp_codebox_command_observation_query['count']) && $wp_codebox_command_observation_query['count'] > 1;
    }));
    $wp_codebox_command_diagnostics_payload['summary']['truncated'] = true;
}
$wp_codebox_command_diagnostics_json = json_encode($wp_codebox_command_diagnostics_payload, JSON_UNESCAPED_SLASHES);
if (strlen($wp_codebox_command_diagnostics_json) > ${maxBytes}) {
    $wp_codebox_command_diagnostics_payload['wpdbQueries'] = array();
    $wp_codebox_command_diagnostics_payload['performance']['database']['fingerprints'] = array();
    $wp_codebox_command_diagnostics_payload['performance']['database']['repeatedQueries'] = array();
    $wp_codebox_command_diagnostics_payload['summary']['truncated'] = true;
    $wp_codebox_command_diagnostics_json = json_encode($wp_codebox_command_diagnostics_payload, JSON_UNESCAPED_SLASHES);
}
$wp_codebox_command_diagnostics_payload['summary']['bytes'] = strlen($wp_codebox_command_diagnostics_json);
$wp_codebox_command_diagnostics_json = json_encode($wp_codebox_command_diagnostics_payload, JSON_UNESCAPED_SLASHES);
echo "\n${marker}" . json_encode($wp_codebox_command_diagnostics_payload, JSON_UNESCAPED_SLASHES) . "\n";
`
}

function splitRunPhpDiagnostics(stdout: string, marker: string): { stdout: string; diagnostics?: RunPhpDiagnosticsPayload } {
  const index = stdout.lastIndexOf(`\n${marker}`)
  if (index < 0) {
    return { stdout }
  }
  const before = stdout.slice(0, index)
  const after = stdout.slice(index + marker.length + 1).trim()
  try {
    const diagnostics = JSON.parse(after) as RunPhpDiagnosticsPayload
    return { stdout: before, diagnostics }
  } catch {
    return { stdout }
  }
}

async function writeCommandDiagnosticsArtifact(artifactRoot: string, diagnostics: RunPhpDiagnosticsPayload): Promise<RuntimeEpisodeTraceRef> {
  const artifactPath = `files/commands/wordpress-run-php-diagnostics-${Date.now().toString(36)}-${randomBytes(4).toString("hex")}.json`
  const absolutePath = join(artifactRoot, artifactPath)
  const contents = `${JSON.stringify(diagnostics, null, 2)}\n`
  await mkdir(dirname(absolutePath), { recursive: true })
  await writeFile(absolutePath, contents)
  return {
    kind: "command-diagnostics",
    id: "wordpress.run-php:diagnostics",
    path: artifactPath,
    digest: { algorithm: "sha256", value: createHash("sha256").update(contents).digest("hex") },
  }
}

function installPhpMessageBridges(server: PlaygroundCliServer, networkPolicy: RuntimeCreateSpec["policy"]["network"]): (() => Promise<void>) | undefined {
  if (!server.playground.onMessage) {
    return undefined
  }

  const activeHostRequests = new Set<AbortController>()
  const remove = server.playground.onMessage(async (data) => {
    const hostHttpMessage = parseHostHttpTransportMessage(data)
    if (hostHttpMessage) {
      const controller = new AbortController()
      activeHostRequests.add(controller)
      try {
        return JSON.stringify(await executeHostHttpTransportRequest(hostHttpMessage, networkPolicy, { signal: controller.signal }))
      } finally {
        activeHostRequests.delete(controller)
      }
    }
    const message = parseBrowserProviderProxyMessage(data)
    if (!message) {
      return undefined
    }

    return JSON.stringify(await executeBrowserProviderProxyRequest(message))
  })

  return async () => {
    for (const controller of activeHostRequests) controller.abort(new Error("The runtime command ended before the host HTTP request completed."))
    const cleanup = await remove
    if (typeof cleanup === "function") {
      await cleanup()
    }
  }
}

function parseBrowserProviderProxyMessage(data: string): BrowserProviderProxyMessage | undefined {
  if (data.length > BROWSER_PROVIDER_PROXY_MAX_BYTES) {
    return undefined
  }

  let message: unknown
  try {
    message = JSON.parse(data)
  } catch {
    return undefined
  }

  if (!message || typeof message !== "object" || Array.isArray(message)) {
    return undefined
  }

  return (message as { schema?: unknown }).schema === BROWSER_PROVIDER_PROXY_SCHEMA
    ? message as BrowserProviderProxyMessage
    : undefined
}

async function executeBrowserProviderProxyRequest(message: BrowserProviderProxyMessage): Promise<Record<string, unknown>> {
  const body = JSON.stringify(message)
  if (body.length > BROWSER_PROVIDER_PROXY_MAX_BYTES) {
    return browserProviderProxyError("wp_codebox_browser_provider_proxy_payload_too_large", "Browser provider proxy request is too large.")
  }

  const endpoint = browserProviderProxyEndpoint()
  if (!endpoint || typeof fetch !== "function") {
    return browserProviderProxyError("wp_codebox_browser_provider_proxy_unavailable", "Browser provider proxy endpoint is unavailable.")
  }

  try {
    const response = await fetch(endpoint, {
      method: "POST",
      credentials: "same-origin",
      headers: browserProviderProxyHeaders(),
      body,
    })
    const json = await response.json().catch(() => undefined)
    if (!response.ok) {
      return browserProviderProxyError("wp_codebox_browser_provider_proxy_http_error", "Browser provider proxy request failed.", { status: response.status, response: json })
    }
    if (!json || typeof json !== "object" || Array.isArray(json)) {
      return browserProviderProxyError("wp_codebox_browser_provider_proxy_malformed_response", "Browser provider proxy returned a malformed response.")
    }

    return json as Record<string, unknown>
  } catch (error) {
    return browserProviderProxyError("wp_codebox_browser_provider_proxy_fetch_failed", error instanceof Error ? error.message : "Browser provider proxy request failed.")
  }
}

function browserProviderProxyEndpoint(): string | undefined {
  const globalValue = globalThis as typeof globalThis & { location?: { origin?: string }; window?: { wpApiSettings?: { root?: string } }; wpApiSettings?: { root?: string } }
  const root = globalValue.wpApiSettings?.root ?? globalValue.window?.wpApiSettings?.root
  if (typeof root === "string" && root.length > 0) {
    return new URL("wp-codebox/v1/browser-provider-request", root).toString()
  }

  if (typeof globalValue.location?.origin === "string" && globalValue.location.origin.length > 0) {
    return new URL("/wp-json/wp-codebox/v1/browser-provider-request", globalValue.location.origin).toString()
  }

  return undefined
}

function browserProviderProxyHeaders(): Record<string, string> {
  const globalValue = globalThis as typeof globalThis & { window?: { wpApiSettings?: { nonce?: string } }; wpApiSettings?: { nonce?: string } }
  const nonce = globalValue.wpApiSettings?.nonce ?? globalValue.window?.wpApiSettings?.nonce
  return {
    "Content-Type": "application/json",
    ...(typeof nonce === "string" && nonce.length > 0 ? { "X-WP-Nonce": nonce } : {}),
  }
}

function browserProviderProxyError(code: string, message: string, data: Record<string, unknown> = {}): Record<string, unknown> {
  const redactedData = redactBrowserProviderProxyData(data)
  return {
    success: false,
    error: {
      code,
      message,
      ...(redactedData && typeof redactedData === "object" && !Array.isArray(redactedData) ? redactedData as Record<string, unknown> : {}),
    },
  }
}

function redactBrowserProviderProxyData(value: unknown): unknown {
  return redactJsonValue(value, { redactStrings: false, extraPattern: /\b(?:key|value)\b/i })
}

export async function runPluginCheckCommand({
  artifactRoot,
  runWpCliCommand,
  server,
  spec,
}: {
  artifactRoot: string
  runWpCliCommand: RunWpCliCommand
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<{ artifact: PluginCheckArtifact; output: string }> {
  const args = spec.args ?? []
  const pluginSlug = argValue(args, "plugin-slug")?.trim()
  if (!pluginSlug) {
    throw new Error("wordpress.plugin-check requires plugin-slug=<slug>")
  }

  if (!/^[a-z0-9][a-z0-9_-]*$/.test(pluginSlug)) {
    throw new Error("wordpress.plugin-check plugin-slug must be a WordPress plugin slug")
  }
  const checkSlugs = commaListArg(args, "checks")

  if (!server.playground.writeFile) {
    throw new Error("wordpress.plugin-check requires a Playground backend with writeFile support")
  }

  const pluginPath = `/wordpress/wp-content/plugins/${pluginSlug}`
  const existsResponse = await runWpCliCommand(server, ["plugin", "path", pluginSlug])
  if (existsResponse.exitCode !== 0) {
    throw new Error(`wordpress.plugin-check target plugin is not installed or mounted at ${pluginPath}`)
  }

  const rawResponse = await runWpCliCommand(server, [
    "plugin",
    "check",
    pluginSlug,
    "--format=strict-json",
    "--fields=file,line,column,type,code,message,docs",
    "--mode=new",
    ...(checkSlugs.length > 0 ? [`--checks=${checkSlugs.join(",")}`] : []),
  ])
  const rawOutput = cleanWpCliOutput(rawResponse.text)
  const normalized = normalizePluginCheckOutput(rawOutput, rawResponse.exitCode ?? 0, pluginSlug)

  return {
    artifact: await writePluginCheckArtifacts(artifactRoot, pluginSlug, rawOutput, normalized),
    output: `${JSON.stringify(normalized, null, 2)}\n`,
  }
}

export async function runPluginStateCommand({
  runPlaygroundCommand,
  runtimeSpec,
  server,
  spec,
}: {
  runPlaygroundCommand: RunPlaygroundCommand
  runtimeSpec: RuntimeCreateSpec
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<string> {
  const input = pluginStateInputFromArgs(spec.args ?? [], spec.command === "wordpress.ensure-plugin-active" ? "activate" : "report", spec.command)
  const response = await runPlaygroundCommand("wordpress.plugin-state", server, { code: bootstrapPhpCode(runtimeSpec, pluginStatePhpCode(input), []) })
  assertPlaygroundResponseOk("wordpress.plugin-state", response)
  return response.text
}

export async function runPluginSetupCommand({
  runWpCliArgv,
  server,
  spec,
}: {
  runWpCliArgv: RunWpCliCommand
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<string> {
  if (!server.playground.writeFile) {
    throw new Error("wordpress.plugin-setup requires a Playground backend with writeFile support")
  }

  const input = pluginSetupInputFromArgs(spec.args ?? [])
  const operations: Array<{ operation: string; exitCode: number; stdout: string; stderr: string }> = []
  const errors: Array<{ code: string; message: string; exitCode?: number }> = []

  if (input.action === "install") {
    const installArgs = ["plugin", "install", input.slug as string, ...(input.activate ? [input.network ? "--activate-network" : "--activate"] : [])]
    const install = await runWpCliArgv(server, installArgs)
    operations.push(operationResult("plugin-install", install))
    if ((install.exitCode ?? 0) !== 0) {
      errors.push({ code: "plugin-install-failed", message: cleanWpCliOutput(install.text).trim() || `Plugin install failed for ${input.slug}.`, exitCode: install.exitCode })
    }
  }

  const list = await runWpCliArgv(server, ["plugin", "list", "--format=json", "--fields=name,status,update,version,title"])
  operations.push(operationResult("plugin-list", list))
  if ((list.exitCode ?? 0) !== 0) {
    errors.push({ code: "plugin-list-failed", message: cleanWpCliOutput(list.text).trim() || "Plugin list failed.", exitCode: list.exitCode })
  }

  const plugins = parseWpCliJsonList(cleanWpCliOutput(list.text))
  return `${JSON.stringify({
    schema: "wp-codebox/wordpress-plugin-setup/v1",
    command: "wordpress.plugin-setup",
    status: errors.length === 0 ? "ok" : "error",
    action: input.action,
    target: input.slug ? { slug: input.slug } : null,
    activate: input.activate,
    network: input.network,
    plugins,
    operations,
    errors,
    artifactRefs: [],
  }, null, 2)}\n`
}

export async function runThemeSetupCommand({
  runWpCliArgv,
  server,
  spec,
}: {
  runWpCliArgv: RunWpCliCommand
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<string> {
  if (!server.playground.writeFile) {
    throw new Error("wordpress.theme-setup requires a Playground backend with writeFile support")
  }

  const input = themeSetupInputFromArgs(spec.args ?? [])
  const operations: Array<{ operation: string; exitCode: number; stdout: string; stderr: string }> = []
  const errors: Array<{ code: string; message: string; exitCode?: number }> = []

  if (input.action === "install") {
    const install = await runWpCliArgv(server, ["theme", "install", input.slug as string, ...(input.activate ? ["--activate"] : [])])
    operations.push(operationResult("theme-install", install))
    if ((install.exitCode ?? 0) !== 0) {
      errors.push({ code: "theme-install-failed", message: cleanWpCliOutput(install.text).trim() || `Theme install failed for ${input.slug}.`, exitCode: install.exitCode })
    }
  }

  if (input.action === "switch") {
    const activate = await runWpCliArgv(server, ["theme", "activate", input.slug as string])
    operations.push(operationResult("theme-activate", activate))
    if ((activate.exitCode ?? 0) !== 0) {
      errors.push({ code: "theme-switch-failed", message: cleanWpCliOutput(activate.text).trim() || `Theme switch failed for ${input.slug}.`, exitCode: activate.exitCode })
    }
  }

  const list = await runWpCliArgv(server, ["theme", "list", "--format=json", "--fields=name,status,update,version,title"])
  operations.push(operationResult("theme-list", list))
  if ((list.exitCode ?? 0) !== 0) {
    errors.push({ code: "theme-list-failed", message: cleanWpCliOutput(list.text).trim() || "Theme list failed.", exitCode: list.exitCode })
  }

  const themes = parseWpCliJsonList(cleanWpCliOutput(list.text))
  return `${JSON.stringify({
    schema: "wp-codebox/wordpress-theme-setup/v1",
    command: "wordpress.theme-setup",
    status: errors.length === 0 ? "ok" : "error",
    action: input.action,
    target: input.slug ? { slug: input.slug } : null,
    activate: input.activate,
    themes,
    operations,
    errors,
    artifactRefs: [],
  }, null, 2)}\n`
}

export async function runThemeCheckCommand({
  artifactRoot,
  runPlaygroundCommand,
  runWpCliArgv,
  runtimeSpec,
  server,
  spec,
}: {
  artifactRoot: string
  runPlaygroundCommand: RunPlaygroundCommand
  runWpCliArgv: RunWpCliCommand
  runtimeSpec: RuntimeCreateSpec
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<{ artifact: ThemeCheckArtifact; output: string }> {
  const args = spec.args ?? []
  const theme = argValue(args, "theme")?.trim()
  if (!theme) {
    throw new Error("wordpress.theme-check requires theme=<slug>")
  }

  if (!server.playground.writeFile) {
    throw new Error("wordpress.theme-check requires a Playground backend with writeFile support")
  }

  if (!await themeCheckPluginInstalled(runPlaygroundCommand, server)) {
    const install = await runWpCliArgv(server, ["plugin", "install", "theme-check"])
    assertPlaygroundResponseOk("wordpress.theme-check", install)
  }

  const response = await runPlaygroundCommand("wordpress.theme-check", server, { code: bootstrapPhpCode(runtimeSpec, themeCheckRunCode(theme), []) })
  assertPlaygroundResponseOk("wordpress.theme-check", response)
  const raw = cleanWpCliOutput(response.text)
  const normalized = normalizeThemeCheckOutput(raw, response.exitCode ?? 0, theme)

  return {
    artifact: await writeThemeCheckArtifacts(artifactRoot, theme, raw, normalized),
    output: `${JSON.stringify(normalized, null, 2)}\n`,
  }
}

function operationResult(operation: string, response: PlaygroundRunResponse): { operation: string; exitCode: number; stdout: string; stderr: string } {
  return {
    operation,
    exitCode: response.exitCode ?? 0,
    stdout: cleanWpCliOutput(response.text).trim(),
    stderr: response.errors?.trim() ?? "",
  }
}

function parseWpCliJsonList(output: string): unknown[] {
  try {
    const value = JSON.parse(output.trim() || "[]")
    return Array.isArray(value) ? value : []
  } catch {
    return []
  }
}

export async function runAbilityCommand({
  runPlaygroundCommand,
  runtimeSpec,
  server,
  spec,
}: {
  runPlaygroundCommand: RunPlaygroundCommand
  runtimeSpec: RuntimeCreateSpec
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<RuntimeCommandResultEnvelope> {
  const name = argValue(spec.args ?? [], "name")?.trim()
  if (!name) {
    throw new Error("wordpress.ability requires name=<ability-name>")
  }

  const input = abilityInputFromArgs(spec.args ?? [])
  const userSession = wordpressUserSessionFromCommandArgs(spec.args ?? [], runtimeSpec)
  const principal = abilityPrincipalFromArgs(spec.args ?? [])
  if (userSession && principal) {
    throw new Error("wordpress.ability accepts either user/session or principal, not both")
  }
  const expectedResultSchema = expectedAbilityResultSchemaFromArgs(spec.args ?? [])
  const removeMessageBridges = installPhpMessageBridges(server, runtimeSpec.policy.network)
  let response: PlaygroundRunResponse
  try {
    response = await runPlaygroundCommand("wordpress.ability", server, { code: bootstrapAbilityPhpCode(runtimeSpec, abilityPhpCode({ name, input, userSession, principal }), server.hostHttpTransport) })
  } finally {
    await removeMessageBridges?.()
  }
  assertPlaygroundResponseOk("wordpress.ability", response)
  return abilityResponseToCommandEnvelope(cleanWpCliOutput(response.text), name, input, expectedResultSchema)
}

export async function runRestRequestCommand({
  runPlaygroundCommand,
  runtimeSpec,
  server,
  spec,
}: {
  runPlaygroundCommand: RunPlaygroundCommand
  runtimeSpec: RuntimeCreateSpec
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<string> {
  const input = restRequestInputFromArgs(spec.args ?? [])
  input.userSession = wordpressUserSessionFromCommandArgs(spec.args ?? [], runtimeSpec)
  const response = await runPlaygroundCommand("wordpress.rest-request", server, { code: bootstrapPhpCode(runtimeSpec, restRequestPhpCode(input), []) })
  assertPlaygroundResponseOk("wordpress.rest-request", response)
  return response.text
}

export async function runRestPerformanceObservationCommand({
  runPlaygroundCommand,
  runtimeSpec,
  server,
  spec,
}: {
  runPlaygroundCommand: RunPlaygroundCommand
  runtimeSpec: RuntimeCreateSpec
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<string> {
  const input = restPerformanceObservationInputFromArgs(spec.args ?? [])
  input.userSession = wordpressUserSessionFromCommandArgs(spec.args ?? [], runtimeSpec)
  const response = await runPlaygroundCommand("wordpress.rest-performance-observation", server, { code: bootstrapPhpCode(runtimeSpec, restPerformanceObservationPhpCode(input), []) })
  assertPlaygroundResponseOk("wordpress.rest-performance-observation", response)
  return response.text
}

export async function runCacheChurnObservationCommand({
  runPlaygroundCommand,
  runtimeSpec,
  server,
  spec,
}: {
  runPlaygroundCommand: RunPlaygroundCommand
  runtimeSpec: RuntimeCreateSpec
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<string> {
  const input = cacheChurnObservationInputFromArgs(spec.args ?? [])
  input.userSession = wordpressUserSessionFromCommandArgs(spec.args ?? [], runtimeSpec)
  const response = await runPlaygroundCommand("wordpress.cache-churn-observation", server, { code: bootstrapPhpCode(runtimeSpec, cacheChurnObservationPhpCode(input), []) })
  assertPlaygroundResponseOk("wordpress.cache-churn-observation", response)
  return response.text
}

export async function runRuntimeDiscoveryCommand({
  runPlaygroundCommand,
  runtimeSpec,
  server,
  spec,
}: {
  runPlaygroundCommand: RunPlaygroundCommand
  runtimeSpec: RuntimeCreateSpec
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<string> {
  const surfaces = runtimeDiscoverySurfacesFromArgs(spec.args ?? [])
  const response = await runPlaygroundCommand("wordpress.runtime-discovery", server, { code: bootstrapPhpCode(runtimeSpec, runtimeDiscoveryPhpCode(surfaces), []) })
  assertPlaygroundResponseOk("wordpress.runtime-discovery", response)
  return response.text
}

export async function runRuntimeInventoryCommand({
  command,
  runPlaygroundCommand,
  runtimeSpec,
  schema,
  server,
  surface,
}: {
  command: string
  runPlaygroundCommand: RunPlaygroundCommand
  runtimeSpec: RuntimeCreateSpec
  schema: string
  server: PlaygroundCliServer
  surface: RuntimeInventorySurface
}): Promise<string> {
  const response = await runPlaygroundCommand(command, server, { code: bootstrapPhpCode(runtimeSpec, runtimeInventoryPhpCode(surface, command, schema), []) })
  assertPlaygroundResponseOk(command, response)
  return response.text
}

export async function runAdminActionInventoryCommand({
  runPlaygroundCommand,
  runtimeSpec,
  server,
  spec,
}: {
  runPlaygroundCommand: RunPlaygroundCommand
  runtimeSpec: RuntimeCreateSpec
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<string> {
  const maxPages = argValue(spec.args ?? [], "max-pages") !== undefined ? positiveIntegerArg(spec.args ?? [], "max-pages", 25) : positiveIntegerArg(spec.args ?? [], "max_pages", 25)
  const command = "wordpress.admin-action-inventory"
  const response = await runPlaygroundCommand(command, server, { code: bootstrapPhpCode(runtimeSpec, runtimeAdminActionInventoryPhpCode(maxPages), []) })
  assertPlaygroundResponseOk(command, response)
  return response.text
}

export async function runPageLoadCommand({
  artifactRoot,
  runPlaygroundCommand,
  runtimeSpec,
  server,
  spec,
  surface,
}: {
  artifactRoot: string
  runPlaygroundCommand: RunPlaygroundCommand
  runtimeSpec: RuntimeCreateSpec
  server: PlaygroundCliServer
  spec: ExecutionSpec
  surface: "admin" | "frontend"
}): Promise<string> {
  const input = pageLoadInputFromArgs(spec.args ?? [], surface, spec.command as Parameters<typeof pageLoadInputFromArgs>[2])
  input.userSession = wordpressUserSessionFromCommandArgs(spec.args ?? [], runtimeSpec)
  const response = await runPlaygroundCommand(input.command, server, { code: bootstrapPhpCode(runtimeSpec, pageLoadPhpCode(input), []) })
  assertPlaygroundResponseOk(input.command, response)
  const result = JSON.parse(cleanWpCliOutput(response.text)) as Record<string, unknown>
  const artifact = await writePageLoadResultArtifact(artifactRoot, input.command, result)
  result.artifactRefs = [...(Array.isArray(result.artifactRefs) ? result.artifactRefs : []), artifact]
  return `${JSON.stringify(result, null, 2)}\n`
}

async function writePageLoadResultArtifact(artifactRoot: string, command: string, result: Record<string, unknown>): Promise<{ path: string; kind: string; contentType: string; sha256: string; metadata: Record<string, unknown> }> {
  const artifactPath = `files/commands/${command.replace(/[^a-z0-9.-]+/gi, "-")}-${Date.now().toString(36)}-${randomBytes(4).toString("hex")}.json`
  const absolutePath = join(artifactRoot, artifactPath)
  const contents = `${JSON.stringify(result, null, 2)}\n`
  await mkdir(dirname(absolutePath), { recursive: true })
  await writeFile(absolutePath, contents)
  return {
    path: artifactPath,
    kind: "wordpress-page-load-result",
    contentType: "application/json",
    sha256: createHash("sha256").update(contents).digest("hex"),
    metadata: { command, schema: result.schema ?? null },
  }
}

export async function runHttpRequestCommand({
  baseUrl,
  spec,
}: {
  baseUrl: string
  spec: ExecutionSpec
}): Promise<string> {
  return runHttpRequest(httpRequestInputFromArgs(spec.args ?? []), baseUrl)
}

export async function runServerPageLoadCommand({
  baseUrl,
  spec,
}: {
  baseUrl: string
  spec: ExecutionSpec
}): Promise<string> {
  const args = spec.args ?? []
  const surface = serverPageLoadSurface(args)
  const path = argValue(args, "path")?.trim() || (surface === "admin" ? "index.php" : "/")
  const input = httpRequestInputFromArgs(serverPageLoadArgs(args, surface, path))
  input.command = "wordpress.server-page-load"
  input.pageLoadTarget = { kind: surface, path }
  return runHttpRequest(input, baseUrl)
}

function serverPageLoadArgs(args: string[], surface: "admin" | "frontend", path: string): string[] {
  const url = argValue(args, "url")?.trim()
  const resolved = url || (surface === "admin" ? `/wp-admin/${path.replace(/^\/+/, "")}` : `/${path.replace(/^\/+/, "")}`)
  return [`url=${resolved}`, ...args.filter((arg) => !arg.startsWith("surface=") && !arg.startsWith("path=") && !arg.startsWith("url="))]
}

function serverPageLoadSurface(args: string[]): "admin" | "frontend" {
  return argValue(args, "surface")?.trim().toLowerCase() === "admin" ? "admin" : "frontend"
}

export async function runBenchCommand({
  browserProbes,
  createRuntimeWpCliBridge,
  runPlaygroundCommand,
  runtimeSpec,
  server,
  spec,
}: {
  browserProbes: BrowserArtifact[]
  createRuntimeWpCliBridge: CreateRuntimeWpCliBridge
  runPlaygroundCommand: RunPlaygroundCommand
  runtimeSpec: RuntimeCreateSpec
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<string> {
  const args = spec.args ?? []
  const pluginSlug = argValue(args, "plugin-slug")?.trim()
  if (!pluginSlug) {
    throw new Error("wordpress.bench requires plugin-slug=<slug>")
  }

  const componentId = argValue(args, "component-id")?.trim() || pluginSlug
  const iterations = positiveIntegerArg(args, "iterations", 3)
  const warmupIterations = nonNegativeIntegerArg(args, "warmup", 1)
  const dependencySlugs = commaListArg(args, "dependency-slugs")
  const env = jsonObjectArg(args, "env-json")
  const bootstrapFiles = jsonArrayArg(args, "bootstrap-files-json").filter((file): file is string => typeof file === "string")
  const workloads = jsonArrayArg(args, "workloads-json")
  const scenarioIds = jsonArrayArg(args, "scenario-ids-json").filter((id): id is string => typeof id === "string" && id.trim() !== "").map((id) => id.trim())
  const lifecycle = jsonObjectArg(args, "lifecycle-json")
  const resetPolicy = jsonObjectArg(args, "reset-policy-json")
  const externalHttpLoadPlans = benchExternalHttpLoadPlans(workloads)
    .filter((plan) => scenarioIds.length === 0 || scenarioIds.includes(plan.scenarioId))
  const runtimeWorkloads = benchReplaceExternalHttpLoadSteps(workloads)
  const bridge = benchWorkloadsUseWpCli([runtimeWorkloads, lifecycle]) ? await createRuntimeWpCliBridge(server) : undefined
  let response: PlaygroundRunResponse
  try {
    response = await runPlaygroundCommand("wordpress.bench", server, {
      code: bootstrapPhpCode(runtimeSpec, benchRunCode({ componentId, pluginSlug, iterations, warmupIterations, dependencySlugs, env, bootstrapFiles, workloads: runtimeWorkloads, scenarioIds, lifecycle, resetPolicy, wpCliBridge: bridge }), []),
    })
    assertPlaygroundResponseOk("wordpress.bench", response)
  } finally {
    if (bridge) {
      await bridge.close()
    }
  }

  const withExternalHttpLoad = await benchMergeExternalHttpLoadResults(response.text, externalHttpLoadPlans, {
    baseUrl: runtimeSpec.preview?.publicUrl ?? server.serverUrl,
    iterations,
    warmupIterations,
    workloads,
  })
  return promoteBrowserMetricsToBenchResults(withExternalHttpLoad, browserProbes)
}

export async function runPhpunitCommand({
  artifactRoot,
  mounts,
  runPlaygroundCommand,
  runtimeSpec,
  server,
  spec,
}: {
  artifactRoot: string
  mounts: MountSpec[]
  runPlaygroundCommand: RunPlaygroundCommand
  runtimeSpec: RuntimeCreateSpec
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<string | RuntimeCommandResultEnvelope> {
  const args = spec.args ?? []
  const processIdentity = boundedProcessIdentity(spec.processIdentity)
  const junitFile = processIdentity ? `/tmp/wp-codebox-phpunit-junit-${processIdentity}.xml` : "/tmp/wp-codebox-phpunit-junit.xml"
  await clearPluginPhpunitJunitResult(server, junitFile)
  const phpunitXmlArg = argValue(args, "phpunit-xml")
  const explicitCode = argValue(args, "code") || argValue(args, "code-file")
  const pluginSlug = argValue(args, "plugin-slug")?.trim() || ""
  const discoveryOnly = booleanArg(args, "discovery-only")
  const changedTestFiles = changedTestFilesArg(args)
  const selectedTestFile = argValue(args, "test-file")?.trim() || ""
  const phpunitArgs = jsonArrayArg(args, "phpunit-args-json").filter((value): value is string => typeof value === "string")
  if (discoveryOnly && (explicitCode || selectedTestFile || changedTestFiles.length > 0 || phpunitArgs.length > 0)) {
    throw new Error("wordpress.phpunit discovery-only cannot be combined with code overrides, test selectors, or PHPUnit arguments")
  }
  const { bootstrapMode, databaseType, externalDatabase, multisite } = phpunitExecutionSemantics(args, runtimeSpec)
  const declaredDatabaseType = argValue(args, "database-type")?.trim()
  if (databaseType === "mysql" && !externalDatabase) {
    throw new Error("wordpress.phpunit requires a managed external database service when database-type=mysql; refusing to substitute SQLite")
  }
  if (databaseType === "mdi-native" && externalDatabase) {
    throw new Error("wordpress.phpunit cannot combine database-type=mdi-native with an external database runtime; mdi-native owns the WordPress database boundary")
  }
  if (declaredDatabaseType === "sqlite" && externalDatabase) {
    throw new Error("wordpress.phpunit declared database-type=sqlite but the runtime uses an external database; refusing backend substitution")
  }
  const autoloadFile = argValue(args, "autoload-file")?.trim() || (bootstrapMode === "project" ? "" : "/wp-codebox-vendor/autoload.php")
  const autoloadFileRole = argValue(args, "autoload-file-role")?.trim() === "harness" ? "harness" : undefined
  const managedMultisitePreinstalled = !explicitCode && !discoveryOnly && requiresManagedMultisitePreinstall(args, runtimeSpec)
  const resultFile = processIdentity ? `/tmp/wp-codebox-phpunit-result-${processIdentity}.txt` : PLUGIN_PHPUNIT_RESULT_FILE
  const diagnosticHostFile = `/wordpress/wp-content/plugins/${pluginSlug}/.pg-test-result${processIdentity ? `-${processIdentity}` : ""}.txt`
  const code = explicitCode ? await phpCodeFromArgs(args, "wordpress.phpunit", false) : phpunitRunCode({
    pluginSlug,
    cwd: argValue(args, "cwd")?.trim() || `/wordpress/wp-content/plugins/${pluginSlug}`,
    autoloadFile,
    autoloadFileRole,
    projectAutoloadFile: argValue(args, "project-autoload-file")?.trim() || "",
    testsDir: argValue(args, "tests-dir")?.trim() || "/wp-codebox-vendor/wp-phpunit/wp-phpunit",
    testRoot: argValue(args, "test-root")?.trim() || `/wordpress/wp-content/plugins/${pluginSlug}/tests`,
    phpunitXml: phpunitXmlArg?.trim() || `/wordpress/wp-content/plugins/${pluginSlug}/phpunit.xml.dist`,
    phpunitXmlIsDefault: phpunitXmlArg === undefined || booleanArg(args, "phpunit-xml-default"),
    selectedTestFile,
    changedTestFiles,
    discoveryOnly,
    phpunitArgs,
    env: jsonObjectArg(args, "env-json"),
    wpConfigDefines: jsonObjectArg(args, "wp-config-defines-json"),
    dependencyMounts: commaListArg(args, "dependency-mounts"),
    dependencyPlugins: jsonArrayArg(args, "dependency-plugins-json").map((plugin) => {
      if (!plugin || typeof plugin !== "object" || Array.isArray(plugin)) throw new Error("dependency-plugins-json entries must be objects")
      const metadata = plugin as Record<string, unknown>
      const path = typeof metadata.path === "string" ? metadata.path : ""
      const pluginFile = typeof metadata.pluginFile === "string" ? metadata.pluginFile : ""
      if (!path) throw new Error("dependency-plugins-json entries require path")
      if (!pluginFile) throw new Error("dependency-plugins-json entries require pluginFile")
      return { path, pluginFile, activate: metadata.activate !== false, loadAs: metadata.loadAs === "mu-plugin" ? "mu-plugin" as const : "plugin" as const }
    }),
    bootstrapFiles: jsonArrayArg(args, "bootstrap-files-json").filter((value): value is string => typeof value === "string"),
    preloadFiles: jsonArrayArg(args, "preload-files-json").filter((value): value is string => typeof value === "string"),
    bootstrapMode,
    projectBootstrap: argValue(args, "project-bootstrap")?.trim() || "",
    multisite,
    databaseType,
    managedMultisitePreinstalled,
    resultFile,
    junitFile,
  })
  if (!explicitCode && !pluginSlug) {
    throw new Error("wordpress.phpunit requires plugin-slug=<slug> when code/code-file is not provided")
  }
  let response: PlaygroundRunResponse
  try {
    const bootstrapArgs = explicitCode ? args : [...args, "bootstrap=runtime-only"]
    if (managedMultisitePreinstalled) {
      const preinstallCode = phpunitMultisitePreinstallCode({
        testsDir: argValue(args, "tests-dir")?.trim() || "/wp-codebox-vendor/wp-phpunit/wp-phpunit",
        env: jsonObjectArg(args, "env-json"),
        wpConfigDefines: jsonObjectArg(args, "wp-config-defines-json"),
        databaseType,
        resultFile,
      })
      const preinstallResponse = await runPlaygroundCommand("wordpress.phpunit", server, { code: bootstrapPhpCode(runtimeSpec, preinstallCode, ["recipe-active-plugins=none", ...bootstrapArgs]) })
      assertPlaygroundResponseOk("wordpress.phpunit multisite preinstall", preinstallResponse)
    }
    response = await runPlaygroundCommand("wordpress.phpunit", server, { code: bootstrapPhpCode(runtimeSpec, code, bootstrapArgs, undefined, resultFile) })
  } catch (error) {
    // Capture before the runtime teardown can reset the command VFS.
    const junitCapture = await persistPluginPhpunitJunitResult(server, junitFile, artifactRoot, processIdentity)
    await persistPluginPhpunitResult(server, resultFile, artifactRoot, processIdentity)
    await persistVfsDiagnosticFileToHost(server, resultFile, diagnosticHostFile, mounts)
    await captureCommandResultPaths(server, spec, artifactRoot)
    const completed = await readPluginPhpunitCompletedResult(server, resultFile) ?? parsePhpunitOutput(playgroundCommandDiagnosticText(error))
    if (completed) {
      await persistPluginPhpunitCompletedResult(artifactRoot, completed, processIdentity)
      const completedError = attachPlaygroundDiagnostics(completedPlaygroundCommandError("wordpress.phpunit", error), "wordpress.phpunit completed result", `completed ${completed.status}; total ${completed.total}; failed ${completed.failed}; skipped ${completed.skipped}; failures ${completed.failures}; errors ${completed.errors}`)
      const diagnostic = phpunitJunitCaptureDiagnostic(junitCapture)
      throw diagnostic ? attachPlaygroundDiagnostics(completedError, "wordpress.phpunit JUnit artifact", diagnostic) : completedError
    }
    const structured = await readPluginPhpunitDiagnostic(server, resultFile)
    if (structured) {
      throw attachPlaygroundDiagnostics(error, "wordpress.phpunit structured diagnostics", structured)
    }
    throw error
  }

  const junitCapture = await persistPluginPhpunitJunitResult(server, junitFile, artifactRoot, processIdentity)
  await persistPluginPhpunitResult(server, resultFile, artifactRoot, processIdentity)
  await persistVfsDiagnosticFileToHost(server, resultFile, diagnosticHostFile, mounts)
  const structured = await readPluginPhpunitDiagnostic(server, resultFile)
  const completed = await readPluginPhpunitCompletedResult(server, resultFile) ?? parsePhpunitOutput(response.text)
  if (completed) {
    await persistPluginPhpunitCompletedResult(artifactRoot, completed, processIdentity)
  }
  const resultPathArtifacts = await captureCommandResultPaths(server, spec, artifactRoot)
  try {
    assertPlaygroundResponseOk("wordpress.phpunit", response)
  } catch (error) {
    const diagnostic = phpunitJunitCaptureDiagnostic(junitCapture)
    if (structured) {
      const structuredError = attachPlaygroundDiagnostics(error, "wordpress.phpunit structured diagnostics", structured)
      throw diagnostic ? attachPlaygroundDiagnostics(structuredError, "wordpress.phpunit JUnit artifact", diagnostic) : structuredError
    }
    throw diagnostic ? attachPlaygroundDiagnostics(error, "wordpress.phpunit JUnit artifact", diagnostic) : error
  }

  if (discoveryOnly) {
    const discovery = await readPluginPhpunitDiscoveryResult(server, resultFile)
    if (!discovery) throw new Error("wordpress.phpunit discovery-only completed without a valid discovery result")
    return `${JSON.stringify(discovery)}\n`
  }

  return resultPathArtifacts.length === 0 ? response.text : createRuntimeCommandResultEnvelope({
    status: "ok",
    stdout: response.text,
    artifactRefs: resultPathArtifacts,
  })
}

export async function captureCommandResultPaths(server: Pick<PlaygroundCliServer, "playground">, spec: Pick<ExecutionSpec, "resultPaths">, artifactRoot: string): Promise<RuntimeEpisodeTraceRef[]> {
  const declarations = spec.resultPaths ?? []
  if (declarations.length === 0) return []
  if (!server.playground.readFileAsText) {
    throw resultPathCollectionError("runtime does not support direct VFS result capture")
  }

  validateResultPathDeclarations(declarations)
  const refs: RuntimeEpisodeTraceRef[] = []
  for (const [index, declaration] of declarations.entries()) {
    try {
      const contents = await server.playground.readFileAsText(declaration.path)
      const bytes = Buffer.byteLength(contents, "utf8")
      const maxBytes = declaration.maxBytes ?? DEFAULT_CAPTURED_ARTIFACT_MAX_BYTES
      if (bytes > maxBytes) throw resultPathCollectionError(`result path ${index + 1} exceeds its byte limit`)
      JSON.parse(contents)
      const captured = await captureArtifactFile({
        root: artifactRoot,
        path: `files/command-results/${declaration.name}.json`,
        kind: declaration.type,
        contentType: "application/json",
        contents,
        maxBytes,
        redaction: { policy: "applied", sensitive: true, reason: "Command result JSON is redacted before artifact capture." },
        provenance: { source: "wordpress-playground", operation: "capture-command-result-path", id: declaration.path },
      })
      if (captured.status !== "captured") throw resultPathCollectionError(`could not capture result path ${index + 1}`)
      if (!captured.sha256) throw resultPathCollectionError(`captured result path ${index + 1} has no digest`)
      refs.push({ kind: declaration.type, id: declaration.name, path: captured.path, sourcePath: declaration.path, contentType: captured.contentType ?? "application/json", digest: { algorithm: "sha256", value: captured.sha256 } })
    } catch (error) {
      if (declaration.required === false) continue
      throw resultPathCollectionError(`required result path ${index + 1} is unavailable`, error)
    }
  }
  return refs
}

function validateResultPathDeclarations(declarations: readonly WorkspaceRecipeResultPath[]): void {
  if (declarations.length > 16) throw resultPathCollectionError("result path count exceeds 16")
  const names = new Set<string>()
  const paths = new Set<string>()
  for (const [index, declaration] of declarations.entries()) {
    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(declaration.name)) throw resultPathCollectionError(`result path ${index + 1} has an invalid artifact name`)
    if (!/^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,255}$/.test(declaration.type)) throw resultPathCollectionError(`result path ${index + 1} has an invalid artifact type`)
    if (declaration.path.length > 1024 || declaration.path.trim() !== declaration.path || !declaration.path.startsWith("/") || declaration.path.includes("\0") || declaration.path.split("/").some((segment) => segment === "." || segment === "..")) {
      throw resultPathCollectionError(`result path ${index + 1} is not a canonical absolute sandbox path`)
    }
    if (!Number.isInteger(declaration.maxBytes ?? DEFAULT_CAPTURED_ARTIFACT_MAX_BYTES) || (declaration.maxBytes ?? DEFAULT_CAPTURED_ARTIFACT_MAX_BYTES) < 1 || (declaration.maxBytes ?? DEFAULT_CAPTURED_ARTIFACT_MAX_BYTES) > 16 * 1024 * 1024) {
      throw resultPathCollectionError(`result path ${index + 1} has an invalid byte limit`)
    }
    if (names.has(declaration.name)) throw resultPathCollectionError(`result path ${index + 1} duplicates an artifact name`)
    if (paths.has(declaration.path)) throw resultPathCollectionError(`result path ${index + 1} duplicates a source path`)
    names.add(declaration.name)
    paths.add(declaration.path)
  }
}

function resultPathCollectionError(message: string, cause?: unknown): Error {
  return Object.assign(new Error(`Command result-path collection failed: ${message}`, cause === undefined ? undefined : { cause }), {
    name: "CommandResultPathCollectionError",
    code: "command-result-path-collection-failed",
    operation: "capture-command-result-path",
  })
}

function boundedProcessIdentity(value: string | undefined): string {
  if (!value) return ""
  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) throw new Error(`Invalid PHPUnit process identity: ${value}`)
  return value
}

function changedTestFilesArg(args: string[]): string[] {
  return jsonArrayArg(args, "changed-tests-json").map((value) => {
    if (typeof value !== "string" || value.trim() === "") {
      throw new Error("changed-tests-json must be a JSON array of non-empty test file paths")
    }
    return value.trim()
  })
}

export async function runCorePhpunitCommand({
  artifactRoot,
  runPlaygroundCommand,
  server,
  spec,
}: {
  artifactRoot: string
  runPlaygroundCommand: RunPlaygroundCommand
  server: PlaygroundCliServer
  spec: ExecutionSpec
}): Promise<string> {
  const args = spec.args ?? []
  const phpunitXmlArg = argValue(args, "phpunit-xml")
  const explicitCode = argValue(args, "code") || argValue(args, "code-file")
  // Write structured diagnostics to a sandbox-internal /tmp path rather than inside
  // the (often read-only) core mount, so the result survives read-only mounts and a
  // mid-require die() in core's bootstrap.php and can be read back from the VFS (#314).
  const resultFile = CORE_PHPUNIT_RESULT_FILE
  const code = explicitCode ? await phpCodeFromArgs(args, "wordpress.core-phpunit") : normalizePhpCode(corePhpunitRunCode({
    coreRoot: argValue(args, "core-root")?.trim() || "/wordpress",
    testsDir: argValue(args, "tests-dir")?.trim() || "/wordpress/tests/phpunit",
    phpunitXml: phpunitXmlArg?.trim() || "/wordpress/tests/phpunit/phpunit.xml.dist",
    phpunitXmlIsDefault: phpunitXmlArg === undefined || booleanArg(args, "phpunit-xml-default"),
    selectedTestFile: argValue(args, "test-file")?.trim() || "",
    changedTestFiles: changedTestFilesArg(args),
    autoloadFile: argValue(args, "autoload-file")?.trim() || "/wordpress/vendor/autoload.php",
    wpConfigDefines: jsonObjectArg(args, "wp-config-defines-json"),
    multisite: booleanArg(args, "multisite"),
    resultFile,
  }))

  let response: PlaygroundRunResponse
  try {
    response = await runPlaygroundCommand("wordpress.core-phpunit", server, { code })
  } catch (error) {
    // Core's bootstrap can die() mid-require when the Composer test toolchain is
    // absent, which surfaces here as a PlaygroundCommandCrashError with empty
    // output. Recover the structured diagnostics the PHP shutdown handler flushed
    // to the result file and re-throw a clear, actionable error instead (#314).
    await persistCorePhpunitResult(server, resultFile, artifactRoot)
    const structured = await readCorePhpunitDiagnostic(server, resultFile)
    if (structured) {
      throw attachPlaygroundDiagnostics(error, "wordpress.core-phpunit structured diagnostics", structured)
    }
    throw error
  }

  await persistCorePhpunitResult(server, resultFile, artifactRoot)
  assertPlaygroundResponseOk("wordpress.core-phpunit", response)

  return response.text
}

interface BenchExternalHttpLoadPlan {
  scenarioId: string
  stepIndex: number
  step: Record<string, unknown>
}

function benchExternalHttpLoadPlans(workloads: unknown[]): BenchExternalHttpLoadPlan[] {
  const plans: BenchExternalHttpLoadPlan[] = []
  workloads.forEach((workload, workloadIndex) => {
    if (!workload || typeof workload !== "object" || Array.isArray(workload)) {
      return
    }
    const record = workload as Record<string, unknown>
    const scenarioId = typeof record.id === "string" && record.id.trim() !== "" ? record.id : `configured-${workloadIndex}`
    const steps = Array.isArray(record.run) ? record.run : (Array.isArray(record.steps) ? record.steps : [])
    steps.forEach((step, stepIndex) => {
      if (step && typeof step === "object" && !Array.isArray(step) && (step as Record<string, unknown>).type === "external-http-load") {
        plans.push({ scenarioId, stepIndex, step: step as Record<string, unknown> })
      }
    })
  })
  return plans
}

function benchReplaceExternalHttpLoadSteps(workloads: unknown[]): unknown[] {
  return workloads.map((workload) => {
    if (!workload || typeof workload !== "object" || Array.isArray(workload)) {
      return workload
    }
    const record = workload as Record<string, unknown>
    const field = Array.isArray(record.run) ? "run" : (Array.isArray(record.steps) ? "steps" : undefined)
    if (!field) {
      return workload
    }
    return {
      ...record,
      [field]: (record[field] as unknown[]).map((step) => step && typeof step === "object" && !Array.isArray(step) && (step as Record<string, unknown>).type === "external-http-load"
        ? { type: "php", code: "return array();" }
        : step),
    }
  })
}

async function benchMergeExternalHttpLoadResults(
  text: string,
  plans: BenchExternalHttpLoadPlan[],
  options: { baseUrl: string; iterations: number; warmupIterations: number; workloads: unknown[] },
): Promise<string> {
  if (plans.length === 0) {
    return text
  }

  // Playground's one-time auto-login redirect belongs to startup, not a measured sample.
  await waitForRuntimePreviewReady(options.baseUrl)

  const results = JSON.parse(text) as { schema?: string; scenarios?: Array<Record<string, any>>; provenance?: Record<string, any> }
  if (results.schema !== "wp-codebox/bench-results/v1" || !Array.isArray(results.scenarios)) {
    throw new Error("external-http-load could not merge into an invalid wordpress.bench result")
  }
  if (results.provenance?.definition && typeof results.provenance.definition === "object") {
    results.provenance.definition.workloads = options.workloads
  }

  for (const plan of plans) {
    const scenario = results.scenarios.find((candidate) => candidate.id === plan.scenarioId)
    if (!scenario) {
      throw new Error(`external-http-load scenario result is missing: ${plan.scenarioId}`)
    }

    const measured: RuntimeExternalHttpLoadResult[] = []
    for (let iteration = 0; iteration < options.warmupIterations + options.iterations; iteration++) {
      const result = await runRuntimeExternalHttpLoad(plan.step, options.baseUrl)
      if (!result.success) {
        throw new Error(`external-http-load assertions failed. diagnostic=${JSON.stringify({
          schema: "wp-codebox/bench-external-http-load-diagnostic/v1",
          scenarioId: plan.scenarioId,
          stepIndex: plan.stepIndex,
          requestCount: result.requestCount,
          completedCount: result.completedCount,
          failureCount: result.failureCount,
          statusDistribution: result.statusDistribution,
          diagnostics: result.diagnostics,
        })}`)
      }
      if (iteration >= options.warmupIterations) {
        measured.push(result)
      }
    }
    if (measured.length !== options.iterations || measured.some((result) => result.samples.length !== result.requestCount)) {
      throw new Error(`external-http-load did not collect every measured request sample for scenario ${plan.scenarioId}`)
    }

    const prefix = benchExternalHttpMetricPrefix(plan.step)
    scenario.metrics ??= {}
    const metricValues: Record<string, { unit: "count" | "ms"; values: number[] }> = {
      [`${prefix}_request_count`]: { unit: "count", values: measured.map((result) => result.requestCount) },
      [`${prefix}_completed_count`]: { unit: "count", values: measured.map((result) => result.completedCount) },
      [`${prefix}_success_count`]: { unit: "count", values: measured.map((result) => result.successCount) },
      [`${prefix}_failure_count`]: { unit: "count", values: measured.map((result) => result.failureCount) },
      [`${prefix}_max_observed_concurrency_count`]: { unit: "count", values: measured.map((result) => result.maxObservedConcurrency) },
      [`${prefix}_latency_mean_ms`]: { unit: "ms", values: measured.map((result) => result.latency.mean) },
      [`${prefix}_latency_p50_ms`]: { unit: "ms", values: measured.map((result) => result.latency.p50) },
      [`${prefix}_latency_p95_ms`]: { unit: "ms", values: measured.map((result) => result.latency.p95) },
      [`${prefix}_latency_p99_ms`]: { unit: "ms", values: measured.map((result) => result.latency.p99) },
    }
    for (const [name, metric] of Object.entries(metricValues)) {
      scenario.metrics[name] = benchExternalHttpMetric(metric.values, metric.unit)
    }
    scenario.metrics.duration = benchExternalHttpMetric(measured.map((result) => result.durationMs), "ms")

    const artifact = benchAggregateExternalHttpLoadResults(measured)
    const artifactName = plans.filter((candidate) => candidate.scenarioId === plan.scenarioId).length === 1
      ? "external-http-load"
      : `external-http-load-${plan.stepIndex}`
    scenario.artifacts ??= {}
    scenario.artifacts[artifactName] = artifact
    scenario.steps ??= []
    scenario.steps.push({
      schema: "wp-codebox/bench-command-step/v1",
      type: "external-http-load",
      requestCount: artifact.requestCount,
      concurrency: artifact.concurrency,
      maxObservedConcurrency: artifact.maxObservedConcurrency,
      warmupIterations: options.warmupIterations,
      iterations: measured.length,
      provenance: artifact.provenance,
    })
    scenario.provenance = {
      ...(scenario.provenance ?? {}),
      external_http_load: [...(Array.isArray(scenario.provenance?.external_http_load) ? scenario.provenance.external_http_load : []), {
        artifact: artifactName,
        ...artifact.provenance,
      }],
    }
  }

  return `${JSON.stringify(results, null, 2)}\n`
}

function benchExternalHttpMetricPrefix(step: Record<string, unknown>): string {
  const value = typeof step["metric-prefix"] === "string" ? step["metric-prefix"] : "external_http_load"
  return value.trim().replace(/[^A-Za-z0-9_]+/g, "_").replace(/^_+|_+$/g, "") || "external_http_load"
}

function benchExternalHttpMetric(values: number[], unit: "count" | "ms"): Record<string, unknown> {
  return { unit, samples: benchNumericSummary(values) }
}

function benchNumericSummary(values: number[]): Record<string, number | number[]> {
  const sorted = [...values].sort((left, right) => left - right)
  const count = sorted.length
  const mean = count > 0 ? sorted.reduce((sum, value) => sum + value, 0) / count : 0
  const variance = count > 0 ? sorted.reduce((sum, value) => sum + ((value - mean) ** 2), 0) / count : 0
  const standardDeviation = Math.sqrt(variance)
  const percentile = (fraction: number): number => count > 0 ? sorted[Math.max(0, Math.ceil(fraction * count) - 1)] : 0
  return {
    count,
    mean,
    p50: percentile(0.5),
    p95: percentile(0.95),
    p99: percentile(0.99),
    min: count > 0 ? sorted[0] : 0,
    max: count > 0 ? sorted[count - 1] : 0,
    standard_deviation: standardDeviation,
    relative_standard_deviation: mean !== 0 ? standardDeviation / Math.abs(mean) : 0,
    values: sorted,
  }
}

function benchAggregateExternalHttpLoadResults(results: RuntimeExternalHttpLoadResult[]): Record<string, any> {
  const statusDistribution: Record<string, number> = {}
  const latenciesMs: number[] = []
  for (const result of results) {
    for (const [status, count] of Object.entries(result.statusDistribution as Record<string, number>)) {
      statusDistribution[status] = (statusDistribution[status] ?? 0) + count
    }
    latenciesMs.push(...result.latenciesMs)
  }
  const first = results[0] ?? {}
  return {
    schema: "wp-codebox/wordpress-external-http-load/v1",
    requestCount: first.requestCount ?? 0,
    concurrency: first.concurrency ?? 0,
    maxObservedConcurrency: Math.max(0, ...results.map((result) => result.maxObservedConcurrency)),
    completedCount: results.reduce((sum, result) => sum + result.completedCount, 0),
    successCount: results.reduce((sum, result) => sum + result.successCount, 0),
    failureCount: results.reduce((sum, result) => sum + result.failureCount, 0),
    statusDistribution,
    durationMs: results.reduce((sum, result) => sum + result.durationMs, 0),
    latenciesMs,
    samples: results.flatMap((result) => result.samples),
    latency: benchNumericSummary(latenciesMs),
    runs: results,
    diagnostics: results.flatMap((result) => result.diagnostics),
    conditions: first.conditions ?? {},
    provenance: first.provenance ?? {},
  }
}

function benchWorkloadsUseWpCli(value: unknown): boolean {
  if (Array.isArray(value)) {
    return value.some(benchWorkloadsUseWpCli)
  }
  if (!value || typeof value !== "object") {
    return false
  }

  const record = value as { type?: unknown; run?: unknown }
  return record.type === "wp-cli" || record.type === "artifact-postprocess" || benchWorkloadsUseWpCli(record.run)
}

async function themeCheckPluginInstalled(runPlaygroundCommand: RunPlaygroundCommand, server: PlaygroundCliServer): Promise<boolean> {
  const response = await runPlaygroundCommand("wordpress.theme-check", server, {
    code: "<?php echo file_exists('/wordpress/wp-content/plugins/theme-check/theme-check.php') ? 'yes' : 'no';",
  })

  return response.text.trim() === "yes"
}