pnpm run-local cannot start on Windows: spawnSync pnpm ENOENT

[snowyukitty]

Summary

pnpm run-local, the command the README gives for trying the Workshop locally, cannot start on
Windows. It fails on the first nested pnpm call, before anything is installed or built.

> gadgets@1.0.0 run-local D:\...\cloudflare-os
> node scripts/run-local.mjs

> pnpm install
node:internal/child_process:1120
    result.error = new ErrnoException(result.error, 'spawnSync ' + options.file);
                   ^
<ref *1> Error: spawnSync pnpm ENOENT
    at execFileSync (node:child_process:911:15)
    at run (file:///D:/.../cloudflare-os/scripts/run-local.mjs:118:3)

Environment: Windows 11, Node v22.12.0, pnpm 10.6.3, clean clone of main (e1ab8fb).

Cause

On Windows the pnpm on PATH is a .cmd shim. execFileSync starts a process directly instead
of going through a shell, so there is no extensionless pnpm for it to execute and the call fails
with ENOENT. Naming the shim explicitly does not help either — since the fix for CVE-2024-27980,
Node refuses to spawn .bat/.cmd without a shell and returns EINVAL:

execFileSync('pnpm.cmd', ['--version'])   ->  EINVAL  spawnSync pnpm.cmd EINVAL
execFileSync('pnpm',     ['--version'])   ->  ENOENT  spawnSync pnpm ENOENT

Affected call sites

Four sites are on the pnpm run-local / pnpm dev-server path. Fixing only the first just moves
the failure to the next one:

File	What it runs
scripts/run-local.mjs (run())	pnpm install, and both builds
run-dev-server.js	pnpm exec wrangler dev
packages/gatekeeper-context/build-app.mjs	pnpm exec vite build
packages/gatekeeper-scheduler/build-app.mjs	pnpm exec vite build

scripts/release/build-release.mjs has the same pattern in its own run() helper, but that path is
CI-only, so it is not part of the failure above.

Everything else in these scripts already spawns process.execPath or git, which are real
executables and unaffected.

Two things worth knowing before fixing it

shell: true is not a safe fix here. It makes the call work, but a shell re-splits the command
line, and run-dev-server.js passes wrangler absolute config paths built from gk.dir. On a
checkout whose path contains a space — C:\Users\Some Name\... — those arguments break apart.

npm_execpath needs a guard. It holds pnpm's own JS entry point, which node can run directly
with no shell, so arguments keep their exact values. But under npm run the same variable points at
npm instead:

pnpm run ...  ->  npm_execpath = ...\pnpm\bin\pnpm.cjs
npm  run ...  ->  npm_execpath = ...\npm\bin\npm-cli.js

Substituting it unchecked would silently run npm install against a pnpm workspace.

Patch

Happy to send this as a PR if you want it — flagging it here first because it lands at about 30
changed lines across five files, which is past the guideline in CONTRIBUTING.md.

A small shared helper keeps it to one copy (packages/* already reference ../../scripts/, e.g.
build:configurator):

// scripts/pnpm-command.js
export function pnpmCommand(args) {
  const execPath = process.env.npm_execpath ?? "";
  return process.platform === "win32" && /[\\/]pnpm\.[cm]?js$/i.test(execPath)
      ? [process.execPath, [execPath, ...args]]
      : ["pnpm", args];
}

used as const [file, argv] = pnpmCommand([...]); execFileSync(file, argv, opts); at the four sites.
It is a no-op off Windows, and on Windows it falls back to today's behaviour whenever the launcher
was not pnpm, so the failure stays loud rather than turning into the wrong package manager.

Verification

On Windows 11 / Node v22.12.0, from a clean clone:

• before: pnpm run-local dies at pnpm install with the ENOENT above;
• after: it completes install, @gadgets/typed-storage build and the frontend vite build, runs
  both gatekeeper build-app.mjs bundles, and reaches
  [wrangler:info] Ready on http://127.0.0.1:8787 with the Workshop serving.
• pnpm lint:check passes.
• The helper was exercised under pnpm run, npm run, and bare node to confirm the guard picks
  pnpm's entry point only in the first case.

Not verified: Linux/macOS behaviour is unchanged by inspection only (the platform check makes it a
no-op), and I did not run pnpm test — the release-manifest golden test already fails on Windows
before any change, from CRLF line endings.

[snowyukitty]

For triage: #18 is the same bug and was opened a few minutes before this issue, so this is
effectively a duplicate — close it in favour of that PR if that is tidier. I have left the details
there rather than opening a competing PR.

One thing worth adding here, which I found after filing: the breakage is wider than run-local.
On a clean main, pnpm types:check — half of what pnpm lint runs in CI — also fails on Windows,
because packages/gatekeeper-context's types:check shells out to pnpm through the same
execFileSync path:

packages/gatekeeper-context types:check: <ref *1> Error: spawnSync pnpm ENOENT

So a Windows contributor cannot run the repo's own pre-push check either, not just the local server.

[Sainigurnoor511]

Reproduced the same Windows breakage on my machine — details below.

Environment

• OS: Windows 10 (build 10.0.26200)
• Shell: PowerShell
• Node: v24.16.0
• pnpm: 11.17.0
• Repo path: E:\Projects\cloudflare-os (no spaces in path)
• Command: pnpm run-local (README Quick Start)

Actual result

Fails at the first nested pnpm call in scripts/run-local.mjs:

> pnpm install
node:internal/child_process:1143
    result.error = new ErrnoException(result.error, 'spawnSync ' + options.file);
                   ^

Error: spawnSync pnpm.cmd EINVAL
    at Object.spawnSync (node:internal/child_process:1143:20)
    at execFileSync (node:child_process:954:15)
    at run (file:///E:/Projects/cloudflare-os/scripts/run-local.mjs:122:3)
  errno: -4071,
  code: 'EINVAL',
  syscall: 'spawnSync pnpm.cmd',
  path: 'pnpm.cmd',
  spawnargs: [ 'install' ]

(Same class of bug as the ENOENT report here — on Windows pnpm is a .cmd shim; Node 24 won’t spawn it without a shell.)

Local fix / verification

I applied a small local patch (shared scripts/run-command.mjs helper + updates at the pnpm call sites). After that, on the same machine:

• pnpm install succeeds
• typed-storage + frontend vite build succeed
• gatekeeper build-app.mjs bundles run
• wrangler reaches [wrangler:info] Ready on http://127.0.0.1:8787

I have not tested a checkout path containing spaces yet (the spaced-path case raised on #18).

Happy to open a PR if maintainers want an external contribution — otherwise I’ll wait here for direction so we don’t duplicate work with others already investigating.

[snowyukitty]

@Sainigurnoor511 — thanks, the Node 24 result is a useful additional data point. I'm not preparing a
PR, so there's nothing to coordinate with me; I'll leave PR direction to the maintainers.

Two things I've measured since filing this.

The spaced-path case, now run rather than reasoned. Applying #18's shell: process.platform === "win32" at the five execFileSync calls it patches gets through install and both builds, and the
run then fails at wrangler, which rejects the gatekeeper config paths broken at the space:

✘ [ERROR] Unknown arguments: os\repo\packages\gatekeeper-confluence\wrangler.dev.jsonc, …

That was from a checkout at C:\Users\snowy\cf os\repo on Windows 11, Node 22.22.3, pnpm 11.17.0.
Worth having a path containing a space as a regression case, since shell: true is the obvious fix
and it does clear the failure in this issue's title.

npm_execpath varies more than the example above shows. In the installations I tested it ended
in pnpm.mjs (pnpm 11 managed through its own .tools directory) and pnpm.cjs (pnpm installed
through npm), and it was unset for the pnpm exec invocation I tested. The guard in the patch above
already accepts both extensions and tolerates the variable being absent, but anything written from
the prose example alone could end up narrower than it needs to be.

For what it's worth, the acceptance criteria I'd aim at: nothing goes through a shell, argument
boundaries survive intact, and pnpm run-local starts from a checkout path containing a space. With
those satisfied the dev server reached Ready on http://127.0.0.1:8787 and a request to / came
back 200 from that same spaced checkout. Happy to test a candidate fix against it.

AI tools assisted this investigation; I ran the reproductions myself and the output above is what
they actually printed.