Support running Blueprint packages containing a Blueprint and Assets used by the Blueprint

[brandonpayton]

What if we support running Blueprints from a Blueprint+Assets package where the Blueprint has access to assets included with the package zip?

More specifically:

• Create a zip containing a blueprint at a well-known path like META-INF/blueprint.json (might as well use a special dir name like epub and Java .jar's use to avoid path conflicts).
• Allow assets to be present anywhere else in the zip.
• Allow blueprint steps to reference those assets.

We could use this kind of packaging for Blueprints in general because it can be awkward to encode binary data or larger things entirely within a JSON file. Being , but one specific use case would be site exports or snapshots. Exports could be represented by WXR files, a SQLite database, or anything else, and the packaged blueprint would have steps for consuming the export.

For example, a package containing a blueprint, a WXR, and images under wp-content/uploads could have blueprint steps to do things like:

• Copy uploads into place
• Import WXR (possibly after adjusting media URLs if needed)

Perhaps Snapshots Support #9 could also be implemented using this kind of package.

What do you think?

@adamziel @bgrgicak @zaerl @akirk

[bgrgicak]

I like this a lot, and I would use it more to unpack code. For example, when I have a mu-plugin that I want to test, I can create a GitHub repository with a blueprint.json and my code files. The Blueprint URL would be the repository ZIP download URL.
I know that we can already import from GitHub, but this would make it even simpler.

It could work as any other blueprint-url. When Playground detects it's a ZIP it gets extracted, the blueprint could have a relative path resource type that works within that extracted folder.

This reminds me of some discussions we had about Blueprints in WordPress. We discussed that a WordPress site could be started by adding a blueprint to a site folder and then running the WordPress setup. In that case, the resulting site would be created based on the blueprint.

My first thought was this is useful for assets (media files) and then I started thinking about this as a new import method.
Is there a use case when you would prefer to add your assets to a Blueprint ZIP instead of using WXR?

[bgrgicak]

If we do this let's also support it in the CLI. For example you cd into the extracted zip and just start the CLI.
It picks up that there is a blueprint.json in the current folder and runs it.

[zaerl]

Adding this to the CLI for quick prototyping is a good idea. I know there are already other methods to do it, but for example:

bun cli.ts \
    server \
    --mount=from-folder/:/to-folder \
    --blueprint=a-blueprint.json

It can potentially be run as:

bun cli.ts server --blueprint=a-blueprint.zip

Or even:

bun cli.ts server --blueprint=a-folder

If the folder has a blueprint JSON in a well-known folder like what you mentioned for jar files.

[brandonpayton]

Awesome. It sounds good to me too.

It could work as any other blueprint-url. When Playground detects it's a ZIP it gets extracted, the blueprint could have a relative path resource type that works within that extracted folder.

I think this is probably the way forward.

For a prototype with Blueprints v1, I think we might already have what we need without relative references. We can extract the assets to a well-known or specified VFS path so they can be used via VFSReference or directly by PHP scripts.

But for Blueprints v2 (this repo) which we expect to be applicable within Playground and also within regular WP server contexts, Blueprints will need to be independent of absolute FS paths. So we'll need some kind of support for stable (probably relative) paths in declarative Blueprint steps and within runPHP steps.

My first thought was this is useful for assets (media files) and then I started thinking about this as a new import method.
Is there a use case when you would prefer to add your assets to a Blueprint ZIP instead of using WXR?

Yes! It offers a lot of flexibility.

It can be used to provide assets along with a WXR file, but it could be used for another scheme if that made more sense.

If we do this let's also support it in the CLI.

That sounds good, and @zaerl, I think you're right that it's a good place to prototype.

bun cli.ts server --blueprint=a-folder

I like this :) It doesn't have to be a zip.

[zaerl]

I like this :) It doesn't have to be a zip.

Thanks. The CLI can quickly check if you pass a folder, a zip, or a JSON. Having the possibility to use a folder will speed things up. So, there is no need to zip everything when testing something during the prototype phase. 👍