[blueprints] Implement blueprints v2 runner in TypeScript#3447
Draft
brandonpayton wants to merge 16 commits intotrunkfrom
Draft
[blueprints] Implement blueprints v2 runner in TypeScript#3447brandonpayton wants to merge 16 commits intotrunkfrom
brandonpayton wants to merge 16 commits intotrunkfrom
Conversation
Add DataReferenceResolverImpl that resolves V2 data references into concrete file and directory contents. Supports inline files/directories, HTTP(S) URLs with CORS proxy and semaphore-based concurrency limiting, execution context paths, and WordPress.org plugin/theme slug resolution.
Add validateBlueprintV2() that performs structural validation of V2 blueprint declarations, including version check, property type checks, step name validation with fuzzy matching (Levenshtein distance) for suggesting corrections to misspelled step names. Export the validator and known step names from the V2 module index.
Fill in extractRuntimeConfig() to read phpVersion, wordpressVersion, and applicationOptions from the blueprint declaration. String versions are wrapped as V2VersionConstraint with preferred set. Object constraints map min/max/preferred (or recommended) fields accordingly.
Wire the compilation pipeline together: - Add validation via validateBlueprintV2() at the start of compileBlueprintV2() - Import transpileDeclarativeToSteps from ./transpile-declarative (stub placeholder for Task 8) - Implement executeSteps() with data reference resolver creation, progress tracking, step handler dispatch, and error wrapping
…options, runPHP, wp-cli, writeFiles) Implement six V2 step handler modules: - filesystem.ts: cp, mv, mkdir, rm, rmdir handlers with site: path resolution - define-constants.ts: defineConstants handler using WP_Config_Transformer to safely modify wp-config.php - set-site-options.ts: setSiteOptions handler calling update_option() with rewrite rule flushing for permalink_structure - run-php.ts: runPHP handler that resolves data references to PHP source, supports env variables, writes to temp file and executes - wp-cli.ts: wp-cli handler reusing V1 shell command parsing and WP-CLI bootstrap pattern - write-files.ts: writeFiles handler resolving data references and writing to site: prefixed target paths All handlers self-register via registerV2StepHandler() and are loaded through side-effect imports in steps/index.ts.
…, unzip, content, media)
Adds transpileV1toV2() which converts V1 blueprints (no version property) into V2 format following the spec's mapping tables: - Top-level: preferredVersions → phpVersion/wordpressVersion, landingPage/login/features → applicationOptions, meta → blueprintMeta - Declarative: constants/siteOptions/plugins → additionalSteps - Per-step rewrites: field renaming, step name mapping - Resource → DataReference conversion (url, literal, vfs, bundled, git) - /wordpress/ path translation Wired into compileBlueprintV2() for automatic V1 detection and transpilation before validation. 57 tests.
Adds mergeBlueprintsV2() which merges multiple V2 blueprint declarations following the spec's composition rules: - Scalar exclusives (siteLanguage, activeTheme): conflict detection - Key-value maps (constants, siteOptions, postTypes, fonts): append with key conflict detection - Version constraints: range intersection - Array by slug (plugins, themes, muPlugins): deduplication - Append arrays (steps, content, media) - Users/roles: merge with conflict detection - applicationOptions: shallow merge per app key 30 tests covering all merge strategies and conflict scenarios.
…te workers Replace the PHP .phar-based runBlueprintV2() with the new TypeScript compileBlueprintV2() + compiled.run() pattern in both the CLI worker and the website remote worker. Progress reporting now uses ProgressTracker events instead of the old onMessage callback.
The PHP .phar-based runBlueprintV2() and getV2Runner() have been replaced by the TypeScript compilation pipeline. Empty these files and remove their exports from the package barrel.
brandonpayton
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replaces the PHP
.phar-based Blueprints V2 runner with a pure TypeScript compilation and execution pipeline. This enables blueprint execution without shelling out to a PHP CLI process, improving debuggability, type safety, and integration with the existing Playground infrastructure.compileBlueprintV2()): Validates, extracts runtime config, transpiles declarative properties to steps, resolves data references, and returns aCompiledBlueprintV2with arun(php)methodversionproperty) to V2 format using spec-defined mapping tablesgetV2Runner,runBlueprintV2) emptied and legacy exports removedBreaking Changes
getV2Runner()andrunBlueprintV2()exports are removed from@wp-playground/blueprintsBlueprintMessagetype export is removed (the event format is unchanged, just not exported as a type)New exports from
@wp-playground/blueprintscompileBlueprintV2(),extractRuntimeConfig()transpileV1toV2(),mergeBlueprintsV2()validateBlueprintV2(),KNOWN_V2_STEP_NAMESv2StepHandlers,registerV2StepHandler()CompiledBlueprintV2,CompileBlueprintV2Options,V2RuntimeConfig,V2StepHandler,StepExecutionContext, etc.Test plan
npm run devand load a V2 blueprint in browser (?experimental-blueprints-v2-runner&blueprint={"version":2,"plugins":["hello-dolly"]})npx nx dev playground-cli server --blueprint='{"version":2,"plugins":["hello-dolly"]}'🤖 Generated with Claude Code