Replace "Mode" concept with auto-loading or explicit CLI flags

[dmsnell]

mode seems arbitrarily limiting as a loading strategy, and as WordPress/wordpress-playground#277 evidences, will need to be routinely expanded to encompass the multitude of ways people have unique setups.

I propose that we replace this concept that we created for this tool with one of two options:

• automatically infer directories to mount from the location the tool runs from (I have taken this approach in the VSCode extension)
• provide explicit flags on the CLI to mount the different directories

In the one case there's nothing someone needs to do other than start wp-cli. The startup looks for WordPress core files, and takes a guess (e.g. is there a wp-config.php). It looks for a themes subdirectory or a plugins subdirectory and can load either of those or both of those. If there are other subdirectories, it can look for a .php or .css file that appears to be a plugin or theme and loads those subdirectories accordingly.

Things can go wrong and the Playground can guess wrong, but this keeps the configuration simple, and those failures may not be very big in the grand scheme of things.

In the second case everything is explicit. wp-cli --core=wordpress-6.2 --plugins=my-plugins --plugin=test-plugin --plugin=another-plugin --theme=parent-theme --theme=child-theme

[adamziel]

I really like this idea, especially since I've already seen a bunch of instances of "it inferred the wrong mode and gave me confusing errors." The "mount everything" mode would make it "just work" with VS Code workspaces where I can have multiple types of WordPress code open as different folders in the same workspace (e.g. themes, plugins, mu-plugins).

The explicit flags would be a good addition, too, if the automated mode ends up being not enough.

cc @danielbachhuber @sejas

[danielbachhuber]

Let's proceed with mode for now, and await further feedback from the CfT.

Here are a few opinions I have:

1. We want to optimize for "it's so fast and it just works".
2. We don't want to do a major refactor a few days before opening it up to broader testing.
3. When we do refactor, we'll want to make sure we add test coverage first so we don't break any existing behaviors.

mode seems to cover most use cases at the moment, so I think it's good enough for now.

[wojtekn]

If we go that way, I would also like to keep the "mount as is" model to support projects that consist of full WordPress installation stored in the project root.

[danielbachhuber]

A great (and important, I think) place to start would be to document these various permutations we want to support.

[sejas]

I like mode and the way it works automatically. It solves most use cases. I would allow users to override it through a parameter in case they want to use a different mode in their project.

I also agree that devs can end up with very complex file architecture, and I would propose using just mappings. Similar to what wp-env does. They could pass a list of mappings through blueprint or wp-now.json where they specify the local directory and the VFS directory (considering / as the documentRoot).

[sejas]

If a user uses mappings, the inline parameters will not be enough because they would need to type all the options each time, and different ones for each project.

[adamziel]

@sejas we're talking about the same things and probably just arguing arounds word selection. Let's stop calling it "mount as is" – an "Automount" would be a better name.

Automount is just "use a few modes at once and detect them automatically." If we did that and let the --mode option do nothing, noone would even notice because everything would still work – the plugins, themes, wp-content directories would all be auto-detected.

In other words, "modes" confine us to only supporting either a plugin or a theme or a WordPress core repo. Automount = support everything at once in the same wp-now start run.

I would allow users to override it through a parameter in case they want to use a different mode in their project.

With an automount mindset, this would be the same as "assume I only have a plugin here, don't autodetect other stuff" – what would be a use-case for this?

I'm all for additional, explicit mappings, too.

[wojtekn]

we're talking about the same things and probably just arguing arounds word selection. Let's stop calling it "mount as is" – an "Automount" would be a better name.

@adamziel I think those are still different things:

• "mount as is" we mount the project directory without performing any automated detection. As a developer working on a client's site, I would like my local environment to work as closely as possible to the production environment. I would like to pull the code from the repository and have my local environment serve it as it sees it.
• Automount is a proposal to traverse project content and detect plugins and themes. It can be useful, but it could result in adding themes or plugins we don't want (e.g., imagine developer keeps some old theme for reference in another directory)

[adamziel]

"mount as is" we mount the project directory without performing any automated detection

Where do we mount it, though? Instead of WordPress? As a plugin? As wp-config? Or just as a document root and don't even have WordPress in the mix?

Automount is a proposal to traverse project content and detect plugins and themes. It can be useful, but it could result in adding themes or plugins we don't want

I mean we already do it with inferMode. We don't go one level deep to detect what else is there, but eventually we'll have to wp-now is to support working with multiple plugins at once without specifying all paths manually.

(e.g., imagine developer keeps some old theme for reference in another directory)

If it's not in cwd, then there's no problem. Even if it's in cwd, it should still be fine – mounting a theme means it's available in WordPress but doesn't mean you have to activate it. And if a particular developer never even wants to see that old theme in /wp-admin/themes.php – then we could allow an explicit directory mapping. I'd just not make "write a lot of CLI args" the default mode of operations. There's a lot of value in being able to just run wp-now and have it figure out everything for you.

[danielbachhuber]

Someone needs to first document all of the different usage permutations. Once we have the variations documented, it will be much easier to communicate how a proposed approach might address each one.

[danielbachhuber]

Filesystem mounting is most likely to be handled with Blueprints: https://github.com/WordPress/blueprints/issues/46

[adamziel]

I ran into this when working on static site generation. I wanted a plain WordPress server, but wp-now always picks a mode and doesn't allow me to specify one explicitly. My directory structure resembles wp-content but only contains a subset of the files.

For example, there's no theme as I want to use WordPress default theme. However, the wp-content mode assumes my wp-content directory is complete and serves a WordPress with "theme not found" error. It could bring in twentytwentyfour from a vanilla WordPress installation, but that would break setups that expect no extra themes.

There's no way to guess the developer's intention. wp-now absolutely needs a way to say "please don't automate anything for me, here's exactly what I want to do instead."