[Blueprints] Support plugin activationOptions

[adamziel]

What it does

Adds activationOptions to the installPlugin Blueprint step.

{
  "step": "installPlugin",
  "pluginData": { "resource": "wordpress.org/plugins", "slug": "my-plugin" },
  "options": {
    "activate": true,
    "activationOptions": {
      "storeCity": "Wroclaw",
      "enabled": true
    }
  }
}

When activation options are provided, installPlugin stores them in a temporary WordPress option before running the plugin activation hook. The option name is based on plugin_basename(__FILE__), so plugin code can read:

get_option('blueprint_activation_' . plugin_basename(__FILE__))

The temporary option is deleted after activation, even if activation fails.

Rationale

Some plugins need setup values during activation, not after activation. A later Blueprint step can update options or run PHP, but it cannot affect code that already ran inside register_activation_hook().

The Blueprint v2 schema already describes activationOptions as data exposed through a WordPress option named blueprint_activation_ plus plugin_basename(__FILE__), and removed after activation. This PR brings the v1 installPlugin step in line with that contract so the behavior can be reviewed independently before #3725 depends on it.

This does not change plugin installation, plugin path validation, overwrite behavior, or onError handling.

Implementation

installPlugin now wraps the activation call:

1. Locate the plugin PHP file that will receive activation options.
2. Store options.activationOptions in blueprint_activation_<plugin_basename>.
3. Run activatePlugin() as before.
4. Delete the temporary option in finally.

The PHP staging helper prints a sentinel-prefixed JSON payload because plugin bootstrap code may write to stdout before the helper reports the option name.

Testing instructions

npm exec nx run playground-blueprints:test:vite -- --testFiles=packages/playground/blueprints/src/tests/steps/install-plugin.spec.ts
npm exec nx run playground-blueprints:typecheck
npm exec nx run playground-blueprints:lint
git diff --check

The new tests cover:

• a plugin activation hook reading activationOptions
• cleanup of the temporary activation option after activation
• a clear error when activationOptions is requested but no plugin PHP file can be found

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds support for passing activationOptions through the v1 installPlugin Blueprint step by staging the options in a temporary WP option during plugin activation, aligning behavior with the Blueprint v2 contract.

Changes:

• Extend installPlugin options to accept activationOptions, stage them before activation, and delete them in a finally.
• Add a PHP staging helper + JS output parser to locate the plugin file and compute the blueprint_activation_<plugin_basename> option name.
• Add tests and update the public Blueprint schema to include activationOptions.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 4 comments.

File	Description
packages/playground/blueprints/src/tests/steps/install-plugin.spec.ts	Adds integration tests validating activationOptions exposure, cleanup, and error behavior.
packages/playground/blueprints/src/lib/steps/install-plugin.ts	Implements activation option staging/cleanup and parses helper output.
packages/playground/blueprints/public/blueprint-schema.json	Documents activationOptions in the v1 installPlugin step schema.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.