`postinstall` scripts are failing in some environments

[desrosj]

A ​Host Test participant surfaced a bug in the recent changes to the build process, mainly [61458] and [61492] which added and modified postinstall scripts.

Here's the relevant log output:

cd '/home/wptestrunners2q3/tmp' && source /home/wptestrunners2q3/nodevenv/tmp/20/bin/activate && npm install && bash /home/wptestrunners2q3/patch_gruntfile.sh /home/wptestrunners2q3/tmp/Gruntfile.js && npm run build --force

> WordPress@7.0.0 postinstall
> npm run gutenberg:verify

> WordPress@7.0.0 gutenberg:verify
> node tools/gutenberg/utils.js



node:internal/modules/cjs/loader:1210
  throw err;
  ^

Error: Cannot find module '/home/wptestrunners2q3/nodevenv/tmp/20/lib/tools/gutenberg/utils.js'
    at Module._resolveFilename (node:internal/modules/cjs/loader:1207:15)
    at Module._load (node:internal/modules/cjs/loader:1038:27)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:164:12)
    at node:internal/main/run_main_module:28:49 {
  code: 'MODULE_NOT_FOUND',
  requireStack: []
}

Node.js v20.20.0
npm error code 1
npm error path /home/wptestrunners2q3/nodevenv/tmp/20/lib
npm error command failed
npm error command sh -c npm run gutenberg:verify
npm error A complete log of this run can be found in: /home/wptestrunners2q3/.npm/_logs/2026-03-17T14_10_59_295Z-debug-0.log
Error: Failed to perform operation.
Environment variables pass checks.
cd '/home/wptestrunners2q3/tmp' && /usr/local/bin/php -q ./vendor/phpunit/phpunit/phpunit --dont-report-useless-tests
Could not open input file: ./vendor/phpunit/phpunit/phpunit
Error: Failed to perform operation.
Environment variables pass checks.
Getting SVN Revision
Getting SVN message
Copying junit.xml results
rsync -r '/home/wptestrunners2q3/tmp'/tests/phpunit/build/logs/* '/home/wptestrunners2q3/tmp'
rsync: change_dir "/home/wptestrunners2q3/tmp/tests/phpunit/build/logs" failed: No such file or directory (2)
rsync error: some files/attrs were not transferred (see previous errors) (code 23) at main.c(1187) [sender=3.1.3]
Error: Failed to perform operation.

After debugging a bit with Claude, it seems that when nodevenv is used as a wrapper for Node.js, it causes some issues with relative paths when running postinstall scripts.

When nodevenv is active, it sets NPM_CONFIG_PREFIX to the virtual environment directory (/home/wptestrunners2q3/nodevenv/tmp/20). This causes npm to treat the WordPress package as if it were being installed to $prefix/lib/, making npm run the postinstall lifecycle script with CWD set to that prefix lib path — not the actual project source directory.

Chain of events:

npm install runs with nodevenv's prefix active
npm triggers postinstall → npm run gutenberg:verify → node tools/gutenberg/utils.js
npm sets the script's CWD to what it considers the package root: /home/wptestrunners2q3/nodevenv/tmp/20/lib
tools/gutenberg/utils.js doesn't exist there → error

It seems that postinstall can cause issues with certain setups, notably nodevenv.

Trac ticket: Core-64874.

## Use of AI Tools

[desrosj]

One option to fix this is to remove the postinstall scripts entirely. gutenberg:verify is the first Grunt task when build is run, which ensures the gutenberg directory is present and contains the files for the commit SHA value pinned in the package.json file.

However, a potential downside of this approach is that the files will not be present locally unless someone runs a build command. In my opinion, this is reasonable because there are other files that must also be built for WP to be usable (this is ​documented in the README.md, though probably deserves it's own section.

Other solutions I have found so far do not seem to work across platforms.

[johnbillion]

Related: #64543

To answer the first question that popped into my head, what's the impact of this change?

Answer: The verifyGutenbergVersion() function no longer runs post install. This function verifies that the Gutenberg package was installed to its correct location with the correct SHA hash.

How necessary is that check? Can it be moved to the build script?

How necessary is that check? Can it be moved to the build script?

Essentially, that's what this PR does. Because gutenberg:verify is ​the first task listed in the `build` task, it just kicks the can down the road a bit.

[juanmaguitar]

Comment from @desrosj from today's Bug Scrub

This prevents some setups from running the unit test suite, so I'd like to resolve this during RC. It's a Build/Test tool change and the contents of all built files will be identical, so it's fine to commit after RC so long as there is double sign off.

​https://wordpress.slack.com/archives/C02RQBWTW/p1774455948067049

[desrosj]

In 62321:

Build/Test Tools: Remove gutenberg:verify script on postinstall.

In [61458], a postinstall script was introduced that ensured the source code from the gutenberg repository was present before attempting to run the build script.

The WordPress.org Hosting Tests surfaced an edge case where the postinstall script was failing when nodevenv is used. Because it serves as a wrapper for Node.js, NPM_CONFIG_PREFIX is set to the virual envirnoment directory and not the actual project source directory.

This removes gutenberg:verify from postinstall entirely. gutenberg:verify is responsible for confirming that the gutenberg directory exists, that the commit SHA value in gutenberg/.gutenberg-hash matches gutenberg.sha in the package.json file, and it downloads a fresh copy if not.

While this will result in the necessary files not being present locally after running npm install, gutenberg:verify is specified as the first task executed when the build and build:dev scripts are run. Running either build script has been a requirement to run WordPress locally for some time now, so this does not introduce a new required step. It simply delays when the built asset will be retrieved from the GitHub Container Registry when necessary.

postinstall scripts should also be avoided entirely due to their significantly insecure nature (see #64543).

Follow up to [61492], [61873], and [62021].

Props jorbin, johnbillion.
Fixes #64874. See #64393, #64543.

[desrosj]

Reopening to consider for backporting.

[jorbin]

[62321] Looks good for backport to 7.0

[desrosj]

In 62330:

Build/Test Tools: Remove gutenberg:verify script on postinstall.

In [61458], a postinstall script was introduced that ensured the source code from the gutenberg repository was present before attempting to run the build script.

The WordPress.org Hosting Tests surfaced an edge case where the postinstall script was failing when nodevenv is used. Because it serves as a wrapper for Node.js, NPM_CONFIG_PREFIX is set to the virual envirnoment directory and not the actual project source directory.

This removes gutenberg:verify from postinstall entirely. gutenberg:verify is responsible for confirming that the gutenberg directory exists, that the commit SHA value in gutenberg/.gutenberg-hash matches gutenberg.sha in the package.json file, and it downloads a fresh copy if not.

While this will result in the necessary files not being present locally after running npm install, gutenberg:verify is specified as the first task executed when the build and build:dev scripts are run. Running either build script has been a requirement to run WordPress locally for some time now, so this does not introduce a new required step. It simply delays when the built asset will be retrieved from the GitHub Container Registry when necessary.

postinstall scripts should also be avoided entirely due to their significantly insecure nature (see #64543).

Follow up to [61492], [61873], and [62021].

Reviewed by jorbin.
Merges [62321] to the 7.0.

Props jorbin, johnbillion, desrosj.
Fixes #64874. See #64393, #64543.