Merge origin/main into recipe evidence fixes

Author: chubes4

docs/recipe-contract.md

@@ -166,6 +166,51 @@ artifact bundle and returns after recipe work finishes. Use
 `--preview-hold-blocking` only for operator workflows that need the CLI process
 to keep a live preview server open for the hold duration.
 
+## WordPress PHPUnit Runtime
+
+`wordpress.phpunit` is the lightweight WP Codebox equivalent of plugin PHPUnit
+commands commonly run through `wp-env run ... vendor/bin/phpunit`. It boots a
+disposable WordPress Playground runtime, mounts the tested plugin at
+`/wordpress/wp-content/plugins/<plugin-slug>`, prepares the WordPress PHPUnit
+contract, and captures command output in the artifact bundle.
+
+The runtime provides:
+
+- `WP_TESTS_DIR` pointing at the configured WordPress tests library.
+- `WP_TESTS_CONFIG_FILE_PATH` and `WP_PHPUNIT__TESTS_CONFIG` pointing at the
+  generated `wp-tests-config.php`.
+- An isolated SQLite test database via `DB_NAME=':memory:'`.
+- A plugin working directory via `cwd=<sandbox path>`, matching the practical
+  role of `wp-env run --env-cwd`.
+- Structured diagnostics in the recipe artifact bundle, including the raw test
+  result log collected from `/tmp/wp-codebox-phpunit-result.txt`.
+
+Use `recipe build phpunit` when generating recipes for plugin CI or offloaded lab
+runners:
+
+```json
+{
+  "pluginSlug": "woocommerce",
+  "pluginSource": "../woocommerce/plugins/woocommerce",
+  "cwd": "/wordpress/wp-content/plugins/woocommerce",
+  "autoloadFile": "/wp-codebox-vendor/autoload.php",
+  "testsDir": "/wp-codebox-vendor/wp-phpunit/wp-phpunit",
+  "bootstrapMode": "project",
+  "projectBootstrap": "tests/legacy/bootstrap.php",
+  "phpunitArgs": ["--filter", "WC_Checkout_Test::test_checkout"]
+}
+```
+
+```bash
+npm run wp-codebox -- recipe build phpunit --options ./phpunit-options.json --output ./phpunit.recipe.json
+npm run wp-codebox -- recipe-run --recipe ./phpunit.recipe.json --artifacts ./artifacts/phpunit --json
+```
+
+For monorepos such as WooCommerce, set `pluginSource` to the directory that
+should appear as `wp-content/plugins/<plugin-slug>` and set `cwd` to the same
+sandbox directory a `wp-env --env-cwd` command would use. Relative `cwd` values
+resolve inside the mounted plugin directory.
+
 ## Browser Assertions
 
 `wordpress.browser-probe` accepts repeated `assert=<assertion>` arguments.

packages/cli/src/commands/recipe-build.ts

@@ -11,7 +11,9 @@ interface WordPressPhpunitBuilderOptions {
   blueprint?: unknown
   wordpressVersion?: string
   mounts?: WorkspaceRecipeMount[]
+  pluginSource?: string
   pluginSlug: string
+  cwd?: string
   selectedTestFile?: string
   changedTestFiles?: string[]
   env?: Record<string, unknown>
@@ -64,7 +66,9 @@ function buildRecipe(recipeType: RecipeBuildOptions["recipeType"], options: Word
         blueprint: options.blueprint,
         wordpressVersion: stringOrUndefined(options.wordpressVersion),
         mounts: Array.isArray(options.mounts) ? options.mounts : [],
+        pluginSource: stringOrUndefined((options as WordPressPhpunitBuilderOptions).pluginSource),
         pluginSlug: requiredString(options.pluginSlug, "pluginSlug"),
+        cwd: stringOrUndefined((options as WordPressPhpunitBuilderOptions).cwd),
         selectedTestFile: stringOrUndefined((options as WordPressPhpunitBuilderOptions).selectedTestFile),
         changedTestFiles: Array.isArray((options as WordPressPhpunitBuilderOptions).changedTestFiles) ? (options as WordPressPhpunitBuilderOptions).changedTestFiles : [],
         env: plainObject(options.env),

packages/runtime-core/src/command-registry.ts

@@ -105,6 +105,7 @@ export const commandRegistry = [
     description: "Run plugin PHPUnit tests with normalized diagnostics and test-result artifact capture.",
     acceptedArgs: [
       { name: "plugin-slug", description: "Plugin slug under wp-content/plugins.", format: "slug" },
+      { name: "cwd", description: "Sandbox working directory for the PHPUnit process. Relative values resolve inside the mounted plugin directory; defaults to wp-content/plugins/<plugin-slug>.", format: "sandbox path" },
       { name: "code", description: "Inline override PHP runner code.", format: "PHP string" },
       { name: "code-file", description: "Path to override PHP runner code.", format: "path" },
       { name: "autoload-file", description: "PHPUnit/vendor autoload path inside the sandbox.", format: "sandbox path" },

packages/runtime-core/src/recipe-builders.ts

@@ -11,7 +11,9 @@ export interface WordPressPhpunitRecipeOptions {
   wordpressVersion?: string
   blueprint?: unknown
   mounts?: WorkspaceRecipeMount[]
+  pluginSource?: string
   pluginSlug: string
+  cwd?: string
   selectedTestFile?: string
   changedTestFiles?: string[]
   env?: JsonObject
@@ -72,6 +74,7 @@ export function normalizeRecipeMounts(mounts: readonly WorkspaceRecipeMount[] =
 
 export function buildWordPressPhpunitRecipe(options: WordPressPhpunitRecipeOptions): WorkspaceRecipe {
   const pluginSlug = requiredPluginSlug(options.pluginSlug, "buildWordPressPhpunitRecipe")
+  const pluginTarget = `/wordpress/wp-content/plugins/${pluginSlug}`
 
   return {
     schema: "wp-codebox/workspace-recipe/v1",
@@ -80,13 +83,17 @@ export function buildWordPressPhpunitRecipe(options: WordPressPhpunitRecipeOptio
       blueprint: options.blueprint ?? { steps: [] },
     },
     inputs: {
-      mounts: normalizeRecipeMounts(options.mounts),
+      mounts: normalizeRecipeMounts([
+        ...(options.pluginSource ? [{ source: options.pluginSource, target: pluginTarget } satisfies WorkspaceRecipeMount] : []),
+        ...(options.mounts ?? []),
+      ]),
     },
     workflow: {
       steps: [{
         command: "wordpress.phpunit",
         args: [
           `plugin-slug=${pluginSlug}`,
+          `cwd=${options.cwd ?? pluginTarget}`,
           `test-file=${options.selectedTestFile ?? ""}`,
           `changed-tests-json=${JSON.stringify(options.changedTestFiles ?? [])}`,
           `env-json=${JSON.stringify(options.env ?? {})}`,

packages/runtime-playground/src/phpunit-command-handlers.ts

@@ -1,5 +1,6 @@
 export interface PhpunitRunCodeOptions {
   pluginSlug: string
+  cwd: string
   autoloadFile: string
   testsDir: string
   phpunitXml: string
@@ -281,6 +282,7 @@ ini_set('display_startup_errors', '1');
 
 $plugin_slug = ${JSON.stringify(options.pluginSlug)};
 $plugin_path = '/wordpress/wp-content/plugins/' . $plugin_slug;
+$runtime_cwd = ${JSON.stringify(options.cwd || `/wordpress/wp-content/plugins/${options.pluginSlug}`)};
 $result_file = ${JSON.stringify(options.resultFile ?? PLUGIN_PHPUNIT_RESULT_FILE)};
 $current_stage = 'preboot';
 $pg_stage_output_buffering = false;
@@ -547,6 +549,25 @@ CONFIG;
     }
 }
 
+function pg_resolve_runtime_cwd(string $cwd, string $plugin_path): string {
+    $cwd = trim(str_replace('\\', '/', $cwd));
+    if ($cwd === '') {
+        return $plugin_path;
+    }
+    if ($cwd[0] !== '/') {
+        $cwd = rtrim($plugin_path, '/') . '/' . ltrim($cwd, '/');
+    }
+    $real = realpath($cwd);
+    $plugin_real = realpath($plugin_path);
+    if ($real === false || $plugin_real === false || !is_dir($real)) {
+        throw new RuntimeException('cwd is not a readable sandbox directory: ' . $cwd);
+    }
+    if ($real !== $plugin_real && strpos($real, rtrim($plugin_real, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR) !== 0) {
+        throw new RuntimeException('cwd must resolve inside the mounted plugin directory: ' . $cwd);
+    }
+    return $real;
+}
+
 function pg_plugin_real_path(string $relative_path, string $kind): ?string {
     global $plugin_path;
     $relative_path = trim(str_replace('\\\\', '/', $relative_path));
@@ -779,6 +800,17 @@ ${phpunitChangedTestFilterPhp({
 
 pg_install_diagnostics_handlers();
 
+pg_stage_begin('cwd');
+try {
+    $runtime_cwd = pg_resolve_runtime_cwd($runtime_cwd, $plugin_path);
+    chdir($runtime_cwd);
+    pg_log('CWD:' . $runtime_cwd);
+    pg_stage_ok('cwd');
+} catch (Throwable $e) {
+    pg_stage_fail('cwd', $e);
+    exit(1);
+}
+
 if (is_array($bench_env)) {
     foreach ($bench_env as $name => $value) {
         if (is_string($name) && preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/', $name)) {

packages/runtime-playground/src/wordpress-command-runners.ts

@@ -392,6 +392,7 @@ export async function runPhpunitCommand({
   const resultFile = PLUGIN_PHPUNIT_RESULT_FILE
   const code = explicitCode ? await phpCodeFromArgs(args, "wordpress.phpunit") : normalizePhpCode(phpunitRunCode({
     pluginSlug,
+    cwd: argValue(args, "cwd")?.trim() || `/wordpress/wp-content/plugins/${pluginSlug}`,
     autoloadFile: argValue(args, "autoload-file")?.trim() || "/wp-codebox-vendor/autoload.php",
     testsDir: argValue(args, "tests-dir")?.trim() || "/wp-codebox-vendor/wp-phpunit/wp-phpunit",
     phpunitXml: argValue(args, "phpunit-xml")?.trim() || `/wordpress/wp-content/plugins/${pluginSlug}/phpunit.xml.dist`,

scripts/wordpress-recipe-builders-smoke.ts

@@ -11,6 +11,8 @@ const validateBenchResults = ajv.compile(createBenchResultsJsonSchema())
 const phpunitRecipe = buildWordPressPhpunitRecipe({
   wordpressVersion: "6.9",
   pluginSlug: "demo-plugin",
+  pluginSource: "/repo/demo-plugin-source",
+  cwd: "tests/phpunit",
   selectedTestFile: "tests/unit/DemoTest.php",
   changedTestFiles: ["tests/unit/DemoTest.php"],
   env: { DEMO_ENV: "yes" },
@@ -22,7 +24,6 @@ const phpunitRecipe = buildWordPressPhpunitRecipe({
   projectBootstrap: "tests/bootstrap.php",
   multisite: true,
   mounts: [
-    { source: "/repo/demo-plugin", target: "/wordpress/wp-content/plugins/demo-plugin" },
     { source: "/repo/vendor", target: "/wp-codebox-vendor", mode: "readonly" },
   ],
 })
@@ -31,8 +32,11 @@ assert.equal(buildWordPressPhpunitRecipe({ pluginSlug: "demo-plugin" }).runtime?
 assert.equal(buildWordPressBenchRecipe({ pluginSlug: "demo-plugin" }).runtime?.wp, DEFAULT_WORDPRESS_VERSION)
 
 assert.equal(phpunitRecipe.inputs?.mounts?.[0]?.mode, "readwrite")
+assert.deepEqual(phpunitRecipe.inputs?.mounts?.[0], { source: "/repo/demo-plugin-source", target: "/wordpress/wp-content/plugins/demo-plugin", mode: "readwrite" })
+assert.deepEqual(phpunitRecipe.inputs?.mounts?.[1], { source: "/repo/vendor", target: "/wp-codebox-vendor", mode: "readonly" })
 assert.deepEqual(phpunitRecipe.workflow.steps[0]?.args, [
   "plugin-slug=demo-plugin",
+  "cwd=tests/phpunit",
   "test-file=tests/unit/DemoTest.php",
   'changed-tests-json=["tests/unit/DemoTest.php"]',
   'env-json={"DEMO_ENV":"yes"}',