Skip to content

Support Playground backend overrides for local runtime changes #408

@chubes4

Description

@chubes4

Problem

WP Codebox runtime overlays are useful for changing the WordPress filesystem inside Playground, for example Core files under /wordpress or bundled libraries under /wordpress/wp-includes/*.

That does not cover changes to Playground itself. Playground is the backend/runtime package WP Codebox uses to boot and execute WordPress. Testing local Playground internals requires selecting a different backend package/build, not mounting files into /wordpress.

This is a separate seam from WordPress runtime overlays and should stay out of the current Core/bundled-library overlay work.

Desired capability

Allow a WP Codebox recipe to opt into a local or alternate Playground backend/runtime package for testing Playground changes.

Possible recipe shape:

{
  "runtime": {
    "backend": {
      "kind": "playground",
      "source": "/Users/chubes/Developer/wordpress-playground@feature-branch",
      "package": "@wp-playground/cli"
    },
    "overlays": [
      {
        "kind": "wordpress-core",
        "source": "/Users/chubes/Developer/wordpress-develop@feature-branch"
      }
    ]
  }
}

The exact contract can differ, but the design should preserve the distinction:

WP Codebox
  -> Playground backend/runtime package override
      -> WordPress filesystem overlays
          -> Core files, bundled libraries, plugins, themes

Acceptance criteria

  • Add a recipe-level way to select a local/alternate Playground backend package or built artifact.
  • Keep backend selection separate from /wordpress filesystem overlays.
  • Record backend provenance in artifacts: source path/ref, package name/version/digest when available, and preparation diagnostics.
  • Fail clearly if the selected backend package is missing, incompatible, or cannot boot.
  • Preserve current default behavior when no backend override is declared.
  • Include focused smoke coverage proving WP Codebox can select a fixture/local backend entrypoint without changing WordPress filesystem overlay semantics.

Non-goals

  • Do not block the Core/bundled-library overlay work.
  • Do not require Playground backend overrides for ordinary Core, plugin, theme, or bundled-library testing.
  • Do not merge this into the same PR as first-class WordPress runtime overlays unless it is already independently implemented and low-risk.

Why this matters

This would make WP Codebox useful for testing local Playground runtime changes with the same artifact/provenance discipline it provides for WordPress Core/plugin work. It is cool and likely valuable, but not required for the current Codex/Core overlay proof.

AI assistance

  • AI assistance: Yes
  • Tool(s): OpenCode (GPT-5.5)
  • Used for: Drafted this follow-up issue from product/design discussion; Chris remains responsible for prioritization.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions