Add PR description Blueprint overrides

Author: adamziel

README.md

@@ -209,6 +209,64 @@ Use this when a PR should preview a plugin and a theme from the same repository.
     github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
+### PR description Blueprint overrides
+
+Use this when the default preview should exist for every pull request, but an
+individual PR needs to guide reviewers to a specific screen, install a companion
+plugin, or seed a small option without committing a one-off file to the branch.
+
+```yaml
+- uses: WordPress/action-wp-playground-pr-preview@v3
+  with:
+    plugin-path: .
+    blueprint-override-source: pr-description
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+By default, PRs from forks ignore PR-description Blueprint overrides. If your
+project wants community fork PRs to control the review Blueprint, opt in
+explicitly:
+
+```yaml
+    blueprint-override-allow-forks: true
+```
+
+Then add a collapsed details block to the PR description:
+
+````md
+<details>
+<summary>Playground Blueprint</summary>
+
+```json
+{
+  "landingPage": "/wp-admin/admin.php?page=my-plugin",
+  "siteOptions": {
+    "blogname": "Review this checkout flow"
+  },
+  "appendSteps": [
+    {
+      "step": "runPHP",
+      "code": "<?php require '/wordpress/wp-load.php'; update_option('my_plugin_mode', 'checkout');"
+    }
+  ]
+}
+```
+
+</details>
+````
+
+The override is merged into the generated Blueprint. `landingPage` and most
+top-level Blueprint fields replace the base value, `features` and `siteOptions`
+are merged, `prependSteps` run before the base steps, and `appendSteps` run
+afterwards. Raw `steps` are rejected so the override cannot accidentally remove
+the plugin or theme installation step. `preferredVersions` and
+`phpExtensionBundles` stay controlled by the workflow.
+
+Trade-off: the override is parsed from Markdown, so malformed JSON fails the
+preview action until the PR description is fixed. That is intentional: a broken
+review environment should be visible instead of silently falling back to a
+different setup.
+
 ### Custom blueprint (companion plugins, version pin, seed data, login)
 
 When you need more than "install this plugin," provide a full Blueprint via `blueprint:`. Example: install your plugin from the PR, also install WooCommerce from .org, pin PHP and WP versions, and log in as admin.
@@ -626,6 +684,9 @@ Use directly when there's no build step, or have the publish workflow call it (i
 | `theme-path` | one of four† | — | Path to theme directory. Auto-generates a `git:directory` blueprint. |
 | `blueprint` | one of four† | — | Custom Blueprint as a JSON string. When set, `plugin-path` and `theme-path` are ignored. |
 | `blueprint-url` | one of four† | — | URL pointing to a hosted Blueprint JSON. Used directly via `?blueprint-url=…`. |
+| `blueprint-override-source` | no | `none` | Set to `pr-description` to merge a PR description details-block override into the generated Blueprint. |
+| `blueprint-override-summary` | no | `Playground Blueprint` | Exact `<summary>` text identifying the override details block. |
+| `blueprint-override-allow-forks` | no | `false` | Set to `true` to allow PR-description Blueprint overrides on pull requests from forks. |
 | `description-template` | no | `{{PLAYGROUND_BUTTON}}` | Template for the PR description block. Supports the [template variables](#template-variables). |
 | `comment-template` | no | (full default) | Template for the PR comment. Supports the [template variables](#template-variables). |
 | `restore-button-if-removed` | no | `true` | If the PR author removes the button block, restore it on the next run. Set `false` to respect deletions. Only applies to `append-to-description` mode. |

action.yml

@@ -17,6 +17,18 @@ inputs:
   blueprint-url:
     type: string
     description: 'URL pointing to a remote blueprint. When provided, the Playground link uses `?blueprint-url={url}` directly.'
+  blueprint-override-source:
+    type: string
+    description: 'Optional source for a Blueprint override. Supported values: none, pr-description.'
+    default: none
+  blueprint-override-summary:
+    type: string
+    description: 'Exact <summary> text of the PR description <details> block containing the override JSON.'
+    default: Playground Blueprint
+  blueprint-override-allow-forks:
+    type: boolean
+    description: 'Whether PR description Blueprint overrides are allowed on pull requests from forks.'
+    default: false
   plugin-path:
     type: string
     description: Path to plugin directory inside the repository (e.g., `.` for root or `plugins/my-plugin`)

dist/index.js

@@ -31895,6 +31895,9 @@ const githubLib = __nccwpck_require__(3228);
   const headRef = pr.head.ref;
   const headSha = pr.head.sha;
   const baseRef = pr.base.ref;
+  const headRepoFullName = pr.head.repo && pr.head.repo.full_name;
+  const baseRepoFullName = pr.base.repo && pr.base.repo.full_name;
+  const isForkPullRequest = !headRepoFullName || !baseRepoFullName || headRepoFullName !== baseRepoFullName;
 
   const playgroundHostRaw = core.getInput('playground-host', {required: false}) || 'https://playground.wordpress.net';
   const playgroundHost = playgroundHostRaw.replace(/\/+$/, '');
@@ -31903,10 +31906,16 @@ const githubLib = __nccwpck_require__(3228);
   const themePath = (core.getInput('theme-path', {required: false}) || '').trim();
   const blueprintInput = core.getInput('blueprint', {required: false}) || '';
   const blueprintUrlInput = (core.getInput('blueprint-url', {required: false}) || '').trim();
+  const blueprintOverrideSource = (core.getInput('blueprint-override-source', {required: false}) || 'none').trim().toLowerCase();
+  const blueprintOverrideSummary = (core.getInput('blueprint-override-summary', {required: false}) || 'Playground Blueprint').trim();
+  const blueprintOverrideAllowForks = (core.getInput('blueprint-override-allow-forks', {required: false}) || 'false').trim().toLowerCase() === 'true';
 
   if(!pluginPath && !themePath && !blueprintInput && !blueprintUrlInput) {
     throw new Error('One of `plugin-path`, `theme-path`, `blueprint`, or `blueprint-url` inputs is required.');
   }
+  if (blueprintOverrideSource !== 'none' && blueprintOverrideSource !== 'pr-description') {
+    throw new Error(`Invalid blueprint-override-source: ${blueprintOverrideSource}. Accepted values: none, pr-description.`);
+  }
 
   const descriptionTemplateInput = core.getInput('description-template', {required: false}) || '';
   const commentTemplateInput = core.getInput('comment-template', {required: false}) || '';
@@ -31926,6 +31935,81 @@ const githubLib = __nccwpck_require__(3228);
     }
   };
 
+  const stripTags = (value) => String(value || '').replace(/<[^>]+>/g, '').trim();
+  const findPrDescriptionBlueprintOverride = (body, summaryText) => {
+    const expectedSummary = stripTags(summaryText).toLowerCase();
+    if (!expectedSummary) {
+      throw new Error('blueprint-override-summary must not be empty.');
+    }
+
+    const detailsPattern = /<details\b[^>]*>([\s\S]*?)<\/details>/gi;
+    let detailsMatch;
+    while ((detailsMatch = detailsPattern.exec(body || ''))) {
+      const details = detailsMatch[1];
+      const summaryMatch = details.match(/<summary\b[^>]*>([\s\S]*?)<\/summary>/i);
+      if (!summaryMatch || stripTags(summaryMatch[1]).toLowerCase() !== expectedSummary) {
+        continue;
+      }
+
+      const codeBlockMatch = details.match(/```json\s*([\s\S]*?)```/i);
+      if (!codeBlockMatch || !codeBlockMatch[1].trim()) {
+        throw new Error(`Found a "${summaryText}" details block, but it does not contain a non-empty json code block.`);
+      }
+      return codeBlockMatch[1].trim();
+    }
+    return '';
+  };
+
+  const mergeBlueprintOverride = (baseBlueprintJson, overrideJson) => {
+    const base = safeParseJson('base blueprint', baseBlueprintJson);
+    const override = safeParseJson('PR description Blueprint override', overrideJson);
+    const protectedFields = ['preferredVersions', 'phpExtensionBundles'];
+
+    for (const field of protectedFields) {
+      if (Object.prototype.hasOwnProperty.call(override, field)) {
+        delete override[field];
+        core.warning(`Ignoring protected Blueprint override field: ${field}`);
+      }
+    }
+
+    if (Object.prototype.hasOwnProperty.call(override, 'steps')) {
+      throw new Error('PR description Blueprint overrides must use prependSteps or appendSteps instead of steps.');
+    }
+
+    const prependSteps = Array.isArray(override.prependSteps) ? override.prependSteps : [];
+    const appendSteps = Array.isArray(override.appendSteps) ? override.appendSteps : [];
+    delete override.prependSteps;
+    delete override.appendSteps;
+
+    const siteOptions = override.siteOptions;
+    delete override.siteOptions;
+
+    const merged = {
+      ...base,
+      ...override,
+      features: {
+        ...(base.features || {}),
+        ...(override.features || {}),
+      },
+    };
+
+    const steps = Array.isArray(base.steps) ? [...base.steps] : [];
+    if (siteOptions && typeof siteOptions === 'object' && !Array.isArray(siteOptions)) {
+      const siteOptionsStep = steps.find((step) => step && step.step === 'setSiteOptions');
+      if (siteOptionsStep) {
+        siteOptionsStep.options = {
+          ...(siteOptionsStep.options || {}),
+          ...siteOptions,
+        };
+      } else {
+        steps.unshift({ step: 'setSiteOptions', options: siteOptions });
+      }
+    }
+
+    merged.steps = [...prependSteps, ...steps, ...appendSteps];
+    return JSON.stringify(merged);
+  };
+
   const archiveBranchSegment = headRef.replace(/[^0-9A-Za-z]/g, '-');
   const repoArchiveRoot = `${repoName}-${archiveBranchSegment}`;
   const repoGitUrl = `https://github.com/${repoFullName}.git`;
@@ -32011,6 +32095,21 @@ const githubLib = __nccwpck_require__(3228);
     blueprintJson = buildAutoBlueprint();
   }
 
+  if (blueprintOverrideSource === 'pr-description') {
+    if (isForkPullRequest && !blueprintOverrideAllowForks) {
+      core.info('Skipping PR description Blueprint override because this pull request comes from a fork and blueprint-override-allow-forks is false.');
+    } else {
+      if (!blueprintJson) {
+        throw new Error('blueprint-override-source: pr-description requires an inline Blueprint; blueprint-url cannot be merged.');
+      }
+      const overrideJson = findPrDescriptionBlueprintOverride(pr.body || '', blueprintOverrideSummary);
+      if (overrideJson) {
+        blueprintJson = mergeBlueprintOverride(blueprintJson, overrideJson);
+        core.info(`Merged Blueprint override from PR description details block: ${blueprintOverrideSummary}`);
+      }
+    }
+  }
+
   if (blueprintJson) {
     try {
       JSON.parse(blueprintJson);

src/index.js

@@ -59,6 +59,9 @@ const githubLib = require('@actions/github');
   const headRef = pr.head.ref;
   const headSha = pr.head.sha;
   const baseRef = pr.base.ref;
+  const headRepoFullName = pr.head.repo && pr.head.repo.full_name;
+  const baseRepoFullName = pr.base.repo && pr.base.repo.full_name;
+  const isForkPullRequest = !headRepoFullName || !baseRepoFullName || headRepoFullName !== baseRepoFullName;
 
   const playgroundHostRaw = core.getInput('playground-host', {required: false}) || 'https://playground.wordpress.net';
   const playgroundHost = playgroundHostRaw.replace(/\/+$/, '');
@@ -67,10 +70,16 @@ const githubLib = require('@actions/github');
   const themePath = (core.getInput('theme-path', {required: false}) || '').trim();
   const blueprintInput = core.getInput('blueprint', {required: false}) || '';
   const blueprintUrlInput = (core.getInput('blueprint-url', {required: false}) || '').trim();
+  const blueprintOverrideSource = (core.getInput('blueprint-override-source', {required: false}) || 'none').trim().toLowerCase();
+  const blueprintOverrideSummary = (core.getInput('blueprint-override-summary', {required: false}) || 'Playground Blueprint').trim();
+  const blueprintOverrideAllowForks = (core.getInput('blueprint-override-allow-forks', {required: false}) || 'false').trim().toLowerCase() === 'true';
 
   if(!pluginPath && !themePath && !blueprintInput && !blueprintUrlInput) {
     throw new Error('One of `plugin-path`, `theme-path`, `blueprint`, or `blueprint-url` inputs is required.');
   }
+  if (blueprintOverrideSource !== 'none' && blueprintOverrideSource !== 'pr-description') {
+    throw new Error(`Invalid blueprint-override-source: ${blueprintOverrideSource}. Accepted values: none, pr-description.`);
+  }
 
   const descriptionTemplateInput = core.getInput('description-template', {required: false}) || '';
   const commentTemplateInput = core.getInput('comment-template', {required: false}) || '';
@@ -90,6 +99,81 @@ const githubLib = require('@actions/github');
     }
   };
 
+  const stripTags = (value) => String(value || '').replace(/<[^>]+>/g, '').trim();
+  const findPrDescriptionBlueprintOverride = (body, summaryText) => {
+    const expectedSummary = stripTags(summaryText).toLowerCase();
+    if (!expectedSummary) {
+      throw new Error('blueprint-override-summary must not be empty.');
+    }
+
+    const detailsPattern = /<details\b[^>]*>([\s\S]*?)<\/details>/gi;
+    let detailsMatch;
+    while ((detailsMatch = detailsPattern.exec(body || ''))) {
+      const details = detailsMatch[1];
+      const summaryMatch = details.match(/<summary\b[^>]*>([\s\S]*?)<\/summary>/i);
+      if (!summaryMatch || stripTags(summaryMatch[1]).toLowerCase() !== expectedSummary) {
+        continue;
+      }
+
+      const codeBlockMatch = details.match(/```json\s*([\s\S]*?)```/i);
+      if (!codeBlockMatch || !codeBlockMatch[1].trim()) {
+        throw new Error(`Found a "${summaryText}" details block, but it does not contain a non-empty json code block.`);
+      }
+      return codeBlockMatch[1].trim();
+    }
+    return '';
+  };
+
+  const mergeBlueprintOverride = (baseBlueprintJson, overrideJson) => {
+    const base = safeParseJson('base blueprint', baseBlueprintJson);
+    const override = safeParseJson('PR description Blueprint override', overrideJson);
+    const protectedFields = ['preferredVersions', 'phpExtensionBundles'];
+
+    for (const field of protectedFields) {
+      if (Object.prototype.hasOwnProperty.call(override, field)) {
+        delete override[field];
+        core.warning(`Ignoring protected Blueprint override field: ${field}`);
+      }
+    }
+
+    if (Object.prototype.hasOwnProperty.call(override, 'steps')) {
+      throw new Error('PR description Blueprint overrides must use prependSteps or appendSteps instead of steps.');
+    }
+
+    const prependSteps = Array.isArray(override.prependSteps) ? override.prependSteps : [];
+    const appendSteps = Array.isArray(override.appendSteps) ? override.appendSteps : [];
+    delete override.prependSteps;
+    delete override.appendSteps;
+
+    const siteOptions = override.siteOptions;
+    delete override.siteOptions;
+
+    const merged = {
+      ...base,
+      ...override,
+      features: {
+        ...(base.features || {}),
+        ...(override.features || {}),
+      },
+    };
+
+    const steps = Array.isArray(base.steps) ? [...base.steps] : [];
+    if (siteOptions && typeof siteOptions === 'object' && !Array.isArray(siteOptions)) {
+      const siteOptionsStep = steps.find((step) => step && step.step === 'setSiteOptions');
+      if (siteOptionsStep) {
+        siteOptionsStep.options = {
+          ...(siteOptionsStep.options || {}),
+          ...siteOptions,
+        };
+      } else {
+        steps.unshift({ step: 'setSiteOptions', options: siteOptions });
+      }
+    }
+
+    merged.steps = [...prependSteps, ...steps, ...appendSteps];
+    return JSON.stringify(merged);
+  };
+
   const archiveBranchSegment = headRef.replace(/[^0-9A-Za-z]/g, '-');
   const repoArchiveRoot = `${repoName}-${archiveBranchSegment}`;
   const repoGitUrl = `https://github.com/${repoFullName}.git`;
@@ -175,6 +259,21 @@ const githubLib = require('@actions/github');
     blueprintJson = buildAutoBlueprint();
   }
 
+  if (blueprintOverrideSource === 'pr-description') {
+    if (isForkPullRequest && !blueprintOverrideAllowForks) {
+      core.info('Skipping PR description Blueprint override because this pull request comes from a fork and blueprint-override-allow-forks is false.');
+    } else {
+      if (!blueprintJson) {
+        throw new Error('blueprint-override-source: pr-description requires an inline Blueprint; blueprint-url cannot be merged.');
+      }
+      const overrideJson = findPrDescriptionBlueprintOverride(pr.body || '', blueprintOverrideSummary);
+      if (overrideJson) {
+        blueprintJson = mergeBlueprintOverride(blueprintJson, overrideJson);
+        core.info(`Merged Blueprint override from PR description details block: ${blueprintOverrideSummary}`);
+      }
+    }
+  }
+
   if (blueprintJson) {
     try {
       JSON.parse(blueprintJson);