Use vip dev-env configuration file from parent directories

[alecgeatches]

Description

Extends configuration file support to work in any subdirectory of a VIP site.

vip dev-env commands run anywhere within a configured site will automatically use the site's configuration file. vip dev-env create will pull environment settings from the .wpvip configuration folder, and subsequent vip dev-env commands will use the site's configured slug. There's no longer any need to remember a slug or where configuration is setup as long as it's in the root of a VIP site.

In the demo below, a skeleton site is set up with this structure:

vip-go-skeleton/
├── .wpvip/
│   └── vip-dev-env.yml      <-- Configuration file here
├── client-mu-plugins/
├── ...
├── themes/
│   └── twentytwentythree/   <-- CLI commands run here
├── private/
└── vip-config/

The video demonstrates using the same site's development environment in the site root, and within a theme folder:

vip-dev-env-version-1.mp4

Additional changes

1. The .vip-dev-env.yml file previously could be located anywhere. For consistency, the file is now always loaded from the configuration directory in .wpvip/vip-dev-env.yml. Because the configuration directory is hidden, the . has been removed from the vip-dev-env.yml filename.
2. Changed the supported configuration-version from 0.preview-unstable to 1.
3. Removed echoing the whole configuration file on vip dev-env create.

Steps to Test

Manually

These changes can be tested globally via npm run build && npm link using the add/configuration-file-from-ancestor branch, or commands can be run directly from compiled files like this:

$ cd vip-cli
$ npm run build
$ node dist/bin/vip-dev-env-start.js

1. Clone vip-go-skeleton into a new directory:

   $ git clone [email protected]:Automattic/vip-go-skeleton.git

2. In the vip-go-skeleton/ root directory, create a .wpvip/ folder containing a vip-dev-env.yml configuration file:

   $ cd vip-go-skeleton
   $ mkdir .wpvip
   $ vim .wpvip/vip-dev-env.yml

3. Add the following configuration file contents:

   configuration-version: 1
   slug: test-ancestor-configuration
   title: Test ancestor configuration
   php: 8.0
   wordpress: 6.2
   app-code: ../
   mu-plugins: image
   xdebug: false
   mailpit: false
   multisite: false
   elasticsearch: false
   phpmyadmin: false
   photon: false

4. In the same root vip-go-skeleton/ directory, create and run the environment:

   $ vip dev-env create
   $ vip dev-env start
   Using environment test-ancestor-configuration from /Users/alec/.../vip-go-skeleton/.wpvip/vip-dev-env.yml
   
   # ...
   SLUG              test-ancestor-configuration                                                                                          
   LOCATION          /Users/alec/.local/share/vip/dev-environment/test-ancestor-configuration                                             
   # ...                                                                                                     

   vip dev-env create/vip dev-env start commands can also be run in any subdirectory of the configured skeleton site.

5. Verify that vip dev-env commands work in subdirectories of vip-go-skeleton/

   $ cd plugins/
   $ vip dev-env info
   Using environment test-ancestor-configuration from /Users/alec/.../vip-go-skeleton/.wpvip/vip-dev-env.yml
   # ...
   SLUG              test-ancestor-configuration                                                                                          
   LOCATION          /Users/alec/.local/share/vip/dev-environment/test-ancestor-configuration                                             
   # ...  
   
   $ vip dev-env exec -- wp option get siteurl
   Using environment test-ancestor-configuration from /Users/alec/.../vip-go-skeleton/.wpvip/vip-dev-env.yml
   
   Running validation steps...
   # ...
   http://test-ancestor-configuration.vipdev.lndo.site

6. Try entering deeper subdirectories (e.g. something in themes/) and ensure vip dev-env commands automatically pull the environment slug from the root site directory.

Tests

New end-to-end tests have been added in __tests/devenv-e2e/013-configuration-file.spec.js. Run these tests with:

$ npm run test:e2e:dev-env 013

[alecgeatches]

Added this meta key for ConfigurationFileOptions to store information about the configuration file that doesn't affect the instance. This meta currently stores configuration-path which is used to show this configuration status line:

[alecgeatches]

Note: I see there are some type issues causing test failures, fixing those now.

[rinatkhaziev]

Just a note on mailhog vs mailpit, since we ditched the former probably need to update all instances. Step 3: mentions mailhog

[alecgeatches]

Just a note on mailhog vs mailpit, since we ditched the former probably need to update all instances. Step 3: mentions mailhog

Thank you! The code appears to be updated to work with mailpit/fallback to mailhog properly. Updated testing instructions to use mailpit instead.

[alecgeatches]

The tests have been fixed and this is ready for review.

[github-actions]

This pull request has been marked stale because it has been open for 60 days with no activity. If there is no activity within 7 days, it will be closed.

This is an automation to keep pull requests manageable and actionable and is not a comment on the quality of this pull request nor on the work done so far. Closed PRs are still valuable to the project and their branches are preserved.

[alecgeatches]

Commenting to unstale this. I'm going to re-merge trunk and get this reviewed.

[rinatkhaziev]

@alecgeatches I took the liberty and merged the trunk.

[rinatkhaziev]

Tested, works great. Even went as far as:

mkdir -p 1/2/3/4/5/6/7/8/9/10
cd 1/2/3/4/5/6/7/8/9/10 

vip dev-env start

On the other hand, this also works:

 mv .wpvip ../
 /tmp/vip-go-skeleton   production  vip dev-env start
Using environment test-ancestor-configuration from /private/tmp/.wpvip/vip-dev-env.yml

I'm not sure whether this is an imaginary or a real problem, but this may lead to unintended consequences.

[rinatkhaziev]

After further discussion it seems that many other developer tools follow the same traversal strategy, so let's go with it.

We print the path to the file we use, so it's going to be easier to spot in case the unintended file is being used to start the env.

[mjangda]

This is awesome.

Let's make sure to test on Windows as well so that we don't have any unexpected surprises there :)

In a future PR, it could be interesting to support a reference to a VIP environment in the config file for pulling defaults (similar to how you can do vip @123.develop dev-env create).

[rinatkhaziev]

oh good point re: Windows. Booting up :)

[rinatkhaziev]

Tested both under WSL and native Win, works as expected.

[sonarqubecloud]

Quality Gate passed

Kudos, no new issues were introduced!

0 New issues
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud

[alecgeatches]

Note: I made a final change in here to address the security fix made by @sjinks in #1652 in this commit: 631f443.

The new code moves readFile() into findConfigurationFile(), which returns both the configuration path and contents in a { configurationPath, configurationContents } object on success. This should address the same security issue by using a single readFile() call to check access and return file contents.

These changes also drop the ENOENT/error code checking, as we'll silently drop any errors and continue if a configuration file isn't available.