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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mjsnew file mode 100644index 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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 88b42b54c..f14a584e7 100644--- a/tools/perf-guard.mjs+++ b/tools/perf-guard.mjs@@ -50,7 +50,7 @@ import { readFileSync, writeFileSync, existsSync, mkdtempSync, rmSync } from 'noimport { 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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 },