Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(tools): a verify tool that shells out to pnpm runs on windows too

yhhdf0a0082b1ba
diff --git a/tools/check-tool-spawn.mjs b/tools/check-tool-spawn.mjs
new file mode 100644
index 000000000..af53b6042
--- /dev/null
+++ b/tools/check-tool-spawn.mjs
@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-tool-spawn.mjs — a tool that shells out to pnpm or npx runs on
+ * every OS the repo is developed on.
+ *
+ * Windows installs both as `.cmd` shims, which node will not spawn directly: the
+ * bare name is ENOENT and the suffixed one EINVAL. Six release-gate tools did it
+ * anyway, so on Windows they never started a process at all — and each reported
+ * the absence as whatever it had been about to measure. `verify-golden` said the
+ * editor never produced a play frame. That is the shape this forbids: the launch
+ * failure has one spelling, in lib/runTool.mjs, and it says which it was.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SCANNED = ['tools', 'build-tools'];
+const HELPER = 'tools/lib/runTool.mjs';
+
+/** The shims. `node`, `git`, `cmake` and friends are real executables and fine. */
+const SHIMS = ['pnpm', 'npx', 'npm', 'yarn'];
+const SPAWNS = new RegExp(String.raw`\b(?:spawnSync|spawn|execFileSync|execFile)\(\s*['"\`](${SHIMS.join('|')})['"\`]`, 'g');
+
+function scripts(dir, into = []) {
+ for (const name of readdirSync(dir)) {
+ if (name === 'node_modules') continue;
+ const full = path.join(dir, name);
+ if (statSync(full).isDirectory()) scripts(full, into);
+ else if (/\.(mjs|js|cjs)$/.test(name)) into.push(full);
+ }
+ return into;
+}
+
+const violations = [];
+for (const dir of SCANNED) {
+ for (const file of scripts(path.join(ROOT, dir))) {
+ const rel = path.relative(ROOT, file).split(path.sep).join('/');
+ if (rel === HELPER) continue;
+ const text = readFileSync(file, 'utf8');
+ for (const m of text.matchAll(SPAWNS)) {
+ violations.push({
+ rel,
+ line: text.slice(0, m.index).split('\n').length,
+ what: m[0],
+ shim: m[1],
+ });
+ }
+ }
+}
+
+if (violations.length > 0) {
+ console.error(`\n✗ ${violations.length} site(s) spawn a package-manager shim directly:\n`);
+ for (const v of violations) {
+ console.error(` ${v.rel}:${v.line} ${v.what}…`);
+ console.error(` node cannot spawn ${v.shim} on windows without a shell\n`);
+ }
+ console.error(`Use \`runTool\` from ${HELPER}, which picks the launch for the OS and`);
+ console.error('reports a process that never started as one.\n');
+ process.exit(1);
+}
+
+const users = scripts(path.join(ROOT, 'tools'))
+ .filter((f) => path.relative(ROOT, f).split(path.sep).join('/') !== HELPER)
+ .filter((f) => /\brunTool\(/.test(readFileSync(f, 'utf8')))
+ .length;
+console.log(`check-tool-spawn: ${users} tool(s) launch pnpm/npx through ${HELPER} — none does it by hand.`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 313298db1..82e755c4d 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -70,6 +70,7 @@ export const GATES = [
{ id: 'system-access', run: 'node tools/check-system-access.mjs' },
{ id: 'project-settings', run: 'node tools/check-project-settings.mjs' },
{ id: 'workflows', run: 'node tools/check-workflows.mjs' },
+ { id: 'tool-spawn', run: 'node tools/check-tool-spawn.mjs' },
{ id: 'tool-calls', run: 'node tools/check-tool-calls.mjs' },
{ id: 'capabilities', run: 'node tools/check-capabilities.mjs' },
{ id: 'inspector-door', run: 'node tools/check-inspector-door.mjs' },
diff --git a/tools/lib/runTool.mjs b/tools/lib/runTool.mjs
new file mode 100644
index 000000000..887e4b261
--- /dev/null
+++ b/tools/lib/runTool.mjs
@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file runTool.mjs — spawn a workspace CLI (pnpm, npx, xvfb-run) on every OS.
+ */
+import { spawnSync } from 'node:child_process';
+
+/** Windows installs pnpm and npx as `.cmd` shims. Node refuses to spawn either
+ * directly (ENOENT for the bare name, EINVAL for the suffix), so they have to
+ * go through a shell — which then concatenates the args, hence the quoting. */
+const VIA_SHELL = process.platform === 'win32';
+
+const quote = (arg) => (VIA_SHELL && /[\s"^&|<>()]/.test(arg) ? `"${String(arg).replace(/"/g, '\\"')}"` : arg);
+
+/**
+ * `spawnSync` with the caller's usual result shape, except that a process which
+ * never started reports as one: `status` is a failure and the reason is in
+ * `stderr`. Without that a launch failure arrives as a zero-length output and
+ * every caller blames whatever it was about to measure.
+ */
+export function runTool(cmd, args, options = {}) {
+ // One string rather than a command plus args: node deprecates the second form
+ // under a shell, because the shell concatenates them anyway (DEP0190).
+ const r = VIA_SHELL
+ ? spawnSync([cmd, ...args].map(quote).join(' '), { ...options, shell: true })
+ : spawnSync(cmd, args, options);
+ if (!r.error) return r;
+ const why = `${cmd} did not start: ${r.error.code ?? r.error.message}`;
+ return { ...r, status: r.status ?? 127, stderr: `${r.stderr ?? ''}${why}\n` };
+}
diff --git a/tools/perf-budget.mjs b/tools/perf-budget.mjs
index 9f6b8a864..958a13e71 100644
--- a/tools/perf-budget.mjs
+++ b/tools/perf-budget.mjs
@@ -28,7 +28,7 @@
import { existsSync, readFileSync, rmSync, appendFileSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
+import { runTool } from './lib/runTool.mjs';
import { generateStressProject, countAssets } from './stress-project.mjs';
@@ -60,7 +60,7 @@ if (corpus.assets !== countAssets(1)) {
// before writing anything.
rmSync(REPORT, { force: true });
-const run = spawnSync('pnpm', ['exec', 'vitest', 'run', '--config', 'vitest.scale.config.ts'], {
+const run = runTool('pnpm', ['exec', 'vitest', 'run', '--config', 'vitest.scale.config.ts'], {
cwd: join(ROOT, 'desktop'),
stdio: 'inherit',
env: { ...process.env, ESTELLA_STRESS_PROJECT: corpus.dir },
diff --git a/tools/perf-guard.mjs b/tools/perf-guard.mjs
index 88b42b54c..f14a584e7 100644
--- a/tools/perf-guard.mjs
+++ b/tools/perf-guard.mjs
@@ -50,7 +50,7 @@ import { readFileSync, writeFileSync, existsSync, mkdtempSync, rmSync } from 'no
import { resolve, dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { tmpdir } from 'node:os';
-import { spawnSync } from 'node:child_process';
+import { runTool } from './lib/runTool.mjs';
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const SDK = join(ROOT, 'sdk');
@@ -113,7 +113,7 @@ if (mode !== '--check' && mode !== '--update') {
const tmp = mkdtempSync(join(tmpdir(), 'estella-perf-'));
const out = join(tmp, 'bench.json');
try {
- const run = spawnSync('npx', ['vitest', 'bench', '--run', '--outputJson', out], {
+ const run = runTool('npx', ['vitest', 'bench', '--run', '--outputJson', out], {
cwd: SDK, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
});
if (!existsSync(out)) {
diff --git a/tools/verify-golden.mjs b/tools/verify-golden.mjs
index 0236ce35a..7d2ff8fc5 100644
--- a/tools/verify-golden.mjs
+++ b/tools/verify-golden.mjs
@@ -22,6 +22,7 @@ import path from 'node:path';
import { atTier, projectDir, parityFor, interactFor, audioFor, suspendFor, safeAreaFor, atlasFor, webPixels, launchTimeoutFor, ROOT } from './goldenProjects.mjs';
import { frameDistance, frameCellMax, readPNG } from './frameCompare.mjs';
import { retryOnDeadGpu, deadGpuVerdict } from './lib/deadGpu.mjs';
+import { runTool } from './lib/runTool.mjs';
const argv = process.argv.slice(2);
const flag = (n, d) => {
@@ -87,7 +88,7 @@ function captureEditorFrame(id, out) {
const attempt = () => {
// A partial file from the attempt before would be read as this attempt's frame.
rmSync(out, { force: true });
- const r = spawnSync('npx', ['electron', '.'], {
+ const r = runTool('npx', ['electron', '.'], {
encoding: 'utf8',
cwd: DESKTOP,
env: {
@@ -173,7 +174,7 @@ function probePositions(target, dir, w, h, names, extra = []) {
function launchPackage(id, target, args) {
const run = retryOnDeadGpu(
() => {
- const r = spawnSync('npx', ['electron', path.join('scripts', LAUNCHER(target)), ...args],
+ const r = runTool('npx', ['electron', path.join('scripts', LAUNCHER(target)), ...args],
{ encoding: 'utf8', cwd: DESKTOP });
return { ok: r.status === 0, output: `${r.stdout ?? ''}${r.stderr ?? ''}`, r };
},
diff --git a/tools/verify-legacy.mjs b/tools/verify-legacy.mjs
index 173375bad..7e288fea4 100644
--- a/tools/verify-legacy.mjs
+++ b/tools/verify-legacy.mjs
@@ -23,6 +23,7 @@ import { mkdtempSync, mkdirSync, rmSync, readFileSync, existsSync, readdirSync }
import { tmpdir } from 'node:os';
import path from 'node:path';
import { legacyAtTier, ROOT } from './goldenProjects.mjs';
+import { runTool } from './lib/runTool.mjs';
const argv = process.argv.slice(2);
const flag = (n, d) => {
@@ -108,7 +109,7 @@ for (const { tag, id } of cases) {
}
return JSON.stringify(shape);
})()`;
- const run = spawnSync('npx', ['electron', '.'], {
+ const run = runTool('npx', ['electron', '.'], {
encoding: 'utf8',
cwd: DESKTOP,
env: {
diff --git a/tools/verify-playthrough.mjs b/tools/verify-playthrough.mjs
index 0628ffa66..696700073 100644
--- a/tools/verify-playthrough.mjs
+++ b/tools/verify-playthrough.mjs
@@ -19,6 +19,7 @@ import { spawnSync } from 'node:child_process';
import { existsSync, mkdirSync, rmSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
+import { runTool } from './lib/runTool.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const DESKTOP = path.join(ROOT, 'desktop');
@@ -58,7 +59,7 @@ if (exported.status !== 0) {
process.exit(1);
}
-const played = spawnSync('npx', [
+const played = runTool('npx', [
'electron', path.join('scripts', 'play-through.mjs'),
'--dir', out, '--route', ROUTE,
'--out', path.join(WORK, `${PROJECT}.png`),
diff --git a/tools/verify-render.mjs b/tools/verify-render.mjs
index df4026340..5d8b09b7e 100644
--- a/tools/verify-render.mjs
+++ b/tools/verify-render.mjs
@@ -16,6 +16,7 @@ import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { TIERS, SCENES, scenesAtTier } from './renderScenes.mjs';
import { retryOnDeadGpu, deadGpuVerdict } from './lib/deadGpu.mjs';
+import { runTool } from './lib/runTool.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const DESKTOP = path.join(ROOT, 'desktop');
@@ -75,7 +76,7 @@ const scenes = selected.map((s) => ({
console.log(`render ${only ? `${scenes.length} named scene(s)` : `${TIER}: ${scenes.length} scene(s)`} on ${BACKEND}`);
if (!NO_BUILD) {
- const built = spawnSync('pnpm', ['exec', 'vite', 'build'], { cwd: DESKTOP, encoding: 'utf8' });
+ const built = runTool('pnpm', ['exec', 'vite', 'build'], { cwd: DESKTOP, encoding: 'utf8' });
if (built.status !== 0) {
console.error(`verify-render: vite build failed\n${(built.stderr || built.stdout || '').slice(-800)}`);
process.exit(1);
@@ -86,7 +87,7 @@ function runScene(scene) {
const args = XVFB
? ['-a', 'pnpm', 'exec', 'electron', 'scripts/headless-verify.mjs']
: ['exec', 'electron', 'scripts/headless-verify.mjs'];
- const r = spawnSync(XVFB ? 'xvfb-run' : 'pnpm', args, {
+ const r = runTool(XVFB ? 'xvfb-run' : 'pnpm', args, {
cwd: DESKTOP,
encoding: 'utf8',
env: { ...process.env, ELECTRON_DISABLE_SANDBOX: '1', ...scene.env },