@polymorphism-tech/morph-spec 8.47.0 → 9.0.0

package/framework/hooks/shared/e2e-check.js

@@ -22,10 +22,12 @@
 
 import { execFileSync } from 'child_process';
 import { createHash } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
 import { join } from 'path';
 
+import { E2E_SPEC_LOCATIONS } from './frontend-locations.js';
 import { isSecondaryWorktree } from './git-paths.js';
+import { resolveSpawn } from './spawn-command.js';
 
 /** Compose filenames Docker itself recognises, in the order it resolves them. */
 const COMPOSE_CANDIDATES = [
@@ -42,9 +44,6 @@ const PLAYWRIGHT_CONFIGS = [
   'playwright.config.mjs',
 ];
 
-/** Task groups that touch runtime and therefore deserve an e2e pass. */
-const RUNTIME_GROUPS = ['frontend', 'backend', 'infra'];
-
 /** How long to wait for every service to report healthy. */
 export const DEFAULT_HEALTH_TIMEOUT = 180_000;
 
@@ -71,9 +70,11 @@ const OUTPUT_TAIL_LINES = 20;
  * @returns {{ code: number, output: string }}
  */
 export function defaultExec(file, args, opts = {}) {
+  const spawn = resolveSpawn(file, args, { cwd: opts.cwd });
   try {
-    const stdout = execFileSync(file, args, {
+    const stdout = execFileSync(spawn.file, spawn.args, {
       cwd: opts.cwd,
+      shell: spawn.shell,
       timeout: opts.timeout,
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
@@ -125,8 +126,7 @@ export function resolveSpecCommand(cwd, config, frontendPath) {
     return { command, args, cwd };
   }
 
-  const searchDirs = frontendPath ? [join(cwd, frontendPath), cwd] : [cwd];
-  for (const dir of searchDirs) {
+  for (const dir of specSearchDirs(cwd, frontendPath)) {
     const hasConfig = PLAYWRIGHT_CONFIGS.some((name) => existsSync(join(dir, name)));
     // node_modules guard, same rationale as getBuildSteps(): a config file is
     // versioned but the toolchain is not, and `npx playwright` in a fresh
@@ -138,6 +138,49 @@ export function resolveSpecCommand(cwd, config, frontendPath) {
   return null;
 }
 
+function specSearchDirs(cwd, frontendPath) {
+  return frontendPath ? [join(cwd, frontendPath), cwd] : E2E_SPEC_LOCATIONS.map((loc) => join(cwd, loc));
+}
+
+function hasPlaywrightConfig(dir) {
+  return PLAYWRIGHT_CONFIGS.some((name) => existsSync(join(dir, name)));
+}
+
+// Configs `resolveSpecCommand` did not run (searched dir without node_modules,
+// or a first-level dir outside the search): each is a smoke pass hiding specs.
+export function findUnrunPlaywrightConfigs(cwd, frontendPath) {
+  const searched = frontendPath ? [frontendPath, '.'] : [...E2E_SPEC_LOCATIONS];
+  const norm = (rel) => rel.replace(/\\/g, '/').replace(/^\.\/|\/$/g, '') || '.';
+  const searchedSet = new Set(searched.map(norm));
+  let firstLevel = [];
+  try {
+    firstLevel = readdirSync(cwd, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name !== 'node_modules' && !e.name.startsWith('.'))
+      .map((e) => e.name);
+  } catch { /* unreadable root: nothing to report */ }
+
+  const found = [];
+  const seen = new Set();
+  for (const rel of [...searched.map(norm), ...firstLevel]) {
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+    const dir = join(cwd, rel);
+    if (!hasPlaywrightConfig(dir)) continue;
+    if (!searchedSet.has(rel)) found.push({ dir: rel, why: 'not-searched' });
+    else if (!existsSync(join(dir, 'node_modules'))) found.push({ dir: rel, why: 'no-node-modules' });
+  }
+  return found;
+}
+
+function unrunConfigWarning({ dir, why }) {
+  const where = dir === '.' ? 'na raiz' : `em ${dir}/`;
+  const cause = why === 'no-node-modules'
+    ? 'sem node_modules ao lado'
+    : 'fora de project.frontendPath e dos locais conhecidos';
+  const fix = dir === '.' ? 'instale as dependências' : `declare project.frontendPath: "${dir}" e instale as dependências`;
+  return `playwright.config.* ${where} não rodou (${cause}) — o nó e2e ficou só no smoke; ${fix}`;
+}
+
 /**
  * Compose project name for a feature — the isolation key that lets two
  * worktrees run their stacks side by side without fighting over container
@@ -486,7 +529,7 @@ export function isDockerAvailable(cwd, exec = defaultExec) {
 // ============================================================================
 
 /**
- * Decide whether this scope deserves an e2e run, and if not, why.
+ * Decide whether this project deserves an e2e run, and if not, why.
  *
  * The load-bearing rule is the third one: a project that declares Docker in
  * `project.integrations` but has no compose file is NOT dispensed — it is a
@@ -494,13 +537,10 @@ export function isDockerAvailable(cwd, exec = defaultExec) {
  * would end up decorative (every project without a compose file collecting a
  * green Gate 3 forever).
  *
- * @param {{ taskGroup?: string|null, scope?: string, composeFile: string|null,
- *           integrations?: string[], skipRequested?: boolean }} params
+ * @param {{ composeFile: string|null, integrations?: string[], skipRequested?: boolean }} params
  * @returns {{ run: boolean, status?: 'skip'|'fail', reason?: string }}
  */
 export function decideApplicability({
-  taskGroup,
-  scope = 'feature',
   composeFile,
   integrations = [],
   skipRequested = false,
@@ -509,13 +549,6 @@ export function decideApplicability({
     return { run: false, status: 'skip', reason: 'requested' };
   }
 
-  // Task scope only runs for groups that touch runtime; feature scope (Gate 3)
-  // always runs. An absent group is treated as runtime-touching — the safe
-  // direction, since a missing field must never buy a free pass.
-  if (scope === 'task' && taskGroup && !RUNTIME_GROUPS.includes(String(taskGroup).toLowerCase())) {
-    return { run: false, status: 'skip', reason: `task group "${taskGroup}" does not touch runtime` };
-  }
-
   if (!composeFile) {
     if (integrations.map((i) => String(i).toLowerCase()).includes('docker')) {
       return {
@@ -836,8 +869,6 @@ export function prepareAuth(
  * @param {object} [options]
  * @param {object} [options.config] - .morph/config/config.json contents
  * @param {string} [options.featureName] - drives COMPOSE_PROJECT_NAME
- * @param {string|null} [options.taskGroup] - task's `group`, for applicability
- * @param {string} [options.scope] - 'feature' | 'task'
  * @param {string} [options.gitCommonDir] - where the freshness stamp lives
  * @param {object} [options.env] - extra env (port block) for compose
  * @param {boolean} [options.skipRequested]
@@ -852,8 +883,6 @@ export function runE2eCheck(cwd, options = {}) {
   const {
     config,
     featureName = 'default',
-    taskGroup = null,
-    scope = 'feature',
     gitCommonDir = null,
     env,
     skipRequested = false,
@@ -863,6 +892,7 @@ export function runE2eCheck(cwd, options = {}) {
     healthTimeout = DEFAULT_HEALTH_TIMEOUT,
     specTimeout = DEFAULT_SPEC_TIMEOUT,
     beforeHeavy = null,
+    countSpecs = null,
     _exec: exec = defaultExec,
   } = options;
 
@@ -870,7 +900,7 @@ export function runE2eCheck(cwd, options = {}) {
   const composeFile = resolveComposeFile(cwd, config);
   const integrations = Array.isArray(config?.project?.integrations) ? config.project.integrations : [];
 
-  const applicability = decideApplicability({ taskGroup, scope, composeFile, integrations, skipRequested });
+  const applicability = decideApplicability({ composeFile, integrations, skipRequested });
   if (!applicability.run) {
     return { status: applicability.status, command: null, output: '', reason: applicability.reason, warnings };
   }
@@ -936,7 +966,8 @@ export function runE2eCheck(cwd, options = {}) {
     if (auth.status === 'fail') {
       return { status: 'fail', command: null, output: '', reason: auth.reason, warnings };
     }
-    return { ...runSpecs(cwd, { config, composeFile, up, auth, specTimeout, composeEnv }, exec), warnings };
+    const specs = runSpecs(cwd, { config, composeFile, up, auth, specTimeout, composeEnv, countSpecs }, exec);
+    return { ...specs, warnings: [...warnings, ...(specs.warnings || [])] };
   } finally {
     if (!keepUp) {
       tearDownStack(cwd, { composeFile, projectName, env: composeEnv }, exec);
@@ -952,8 +983,9 @@ export function runE2eCheck(cwd, options = {}) {
  * hardcoded localhost:3000 — ECONNREFUSED that looks exactly like a broken app.
  * `PLAYWRIGHT_BASE_URL` travels in that env for the config to read.
  */
-function runSpecs(cwd, { config, composeFile, up, auth, specTimeout, composeEnv }, exec) {
-  const spec = resolveSpecCommand(cwd, config, config?.project?.frontendPath);
+function runSpecs(cwd, { config, composeFile, up, auth, specTimeout, composeEnv, countSpecs }, exec) {
+  const frontendPath = config?.project?.frontendPath;
+  const spec = resolveSpecCommand(cwd, config, frontendPath);
   const notes = [up.reused ? up.reason : null, auth?.reason].filter(Boolean);
 
   if (!spec) {
@@ -962,11 +994,14 @@ function runSpecs(cwd, { config, composeFile, up, auth, specTimeout, composeEnv
       command: `docker compose -f ${composeFile} up -d --wait`,
       output: '',
       reason: joinNotes('smoke only — stack healthy, no Playwright specs found', notes),
+      warnings: findUnrunPlaywrightConfigs(cwd, frontendPath).map(unrunConfigWarning),
     };
   }
 
   const commandLine = `${spec.command} ${spec.args.join(' ')}`;
   const run = exec(spec.command, spec.args, { cwd: spec.cwd, timeout: specTimeout, env: composeEnv });
+  // Read from the FULL output, before the tail cut; unparseable is null, never 0.
+  const count = typeof countSpecs === 'function' ? (countSpecs(run.output) ?? null) : null;
 
   if (run.code !== 0) {
     return {
@@ -974,6 +1009,7 @@ function runSpecs(cwd, { config, composeFile, up, auth, specTimeout, composeEnv
       command: commandLine,
       output: tailLines(run.output, OUTPUT_TAIL_LINES),
       reason: 'e2e specs failed against the running stack',
+      count,
     };
   }
 
@@ -982,6 +1018,7 @@ function runSpecs(cwd, { config, composeFile, up, auth, specTimeout, composeEnv
     command: commandLine,
     output: '',
     reason: notes.length ? notes.join('; ') : null,
+    count,
   };
 }
 

package/framework/hooks/shared/errata.js

@@ -0,0 +1,72 @@
+export const ERRATA_HEADING = '## Errata';
+
+/** Strip BOM and CRLF — the one normalization every reader of a frozen markdown applies. */
+export function normalizeMarkdown(text) {
+  return String(text ?? '').replace(/^/, '').replace(/\r\n?/g, '\n');
+}
+
+/**
+ * Lines with fenced blocks marked, so no heading is read inside ``` or ~~~.
+ *
+ * @returns {{ raw: string, n: number, fenced: boolean }[]}
+ */
+export function markdownLines(text) {
+  const out = [];
+  let fence = null;
+  normalizeMarkdown(text).split('\n').forEach((raw, i) => {
+    const opener = /^\s*(`{3,}|~{3,})/.exec(raw);
+    let fenced = Boolean(fence);
+    if (fence) {
+      if (opener && opener[1][0] === fence[0] && opener[1].length >= fence.length) fence = null;
+    } else if (opener) {
+      fence = opener[1];
+      fenced = true;
+    }
+    out.push({ raw, n: i + 1, fenced });
+  });
+  return out;
+}
+
+const isErrataHeading = (line) => !line.fenced
+  && /^##\s+errata\s*$/i.test(line.raw);
+
+/** Offset of the `## Errata` heading in the NORMALIZED text, or -1. */
+export function errataOffset(text) {
+  let offset = 0;
+  for (const line of markdownLines(text)) {
+    if (isErrataHeading(line)) return offset;
+    offset += line.raw.length + 1;
+  }
+  return -1;
+}
+
+/** Everything before the errata block, normalized, without trailing blank. */
+export function frozenBody(text) {
+  const norm = normalizeMarkdown(text);
+  const at = errataOffset(norm);
+  return (at === -1 ? norm : norm.slice(0, at)).trimEnd();
+}
+
+/**
+ * Is `proposed` the approved text plus an append-only errata? The body stays
+ * byte-identical, the result carries an errata block, and what the errata
+ * already said is never rewritten.
+ *
+ * @returns {{ok: true} | {ok: false, why: string}}
+ */
+export function errataViolation(original, proposed) {
+  if (frozenBody(proposed) !== frozenBody(original)) {
+    return { ok: false, why: 'o corpo aprovado mudou — errata só ACRESCENTA ao fim, nunca altera o texto aprovado' };
+  }
+  const next = normalizeMarkdown(proposed);
+  const nextAt = errataOffset(next);
+  if (nextAt === -1) {
+    return { ok: false, why: `o conteúdo novo precisa estar sob um bloco \`${ERRATA_HEADING}\` no fim do arquivo` };
+  }
+  const prev = normalizeMarkdown(original);
+  const prevAt = errataOffset(prev);
+  if (prevAt !== -1 && !next.slice(nextAt).startsWith(prev.slice(prevAt).trimEnd())) {
+    return { ok: false, why: 'a errata existente foi reescrita — ela é append-only, entradas anteriores não se apagam' };
+  }
+  return { ok: true };
+}

package/framework/hooks/shared/feature-locator.js

@@ -100,7 +100,7 @@ export function featureNamedIn(text, names) {
  * know" as opposed to "the text names nothing in particular".
  *
  * This is what the single-feature fallback below was missing: a gate question
- * for a feature not yet registered (no `create`, no `proposal.md` written
+ * for a feature not yet registered (no `create`, no `plan.md` written
  * yet — a fresh hotfix, say) names NO known feature either, and used to fall
  * through to "the tree's one feature must be it". That is exactly how a Gate 3
  * for `backfill-bool-filter` landed on `export-hub`, the tree's only

package/framework/hooks/shared/frontend-locations.js

@@ -0,0 +1,6 @@
+// The single list of frontend package locations: `src/lib/detectors` re-exports it,
+// because a hook cannot import `src/`.
+export const PACKAGE_LOCATIONS = ['.', 'src/frontend', 'src/web', 'frontend', 'apps/web', 'packages/app'];
+
+// Where `verify`/`e2e` look for a Playwright setup when `project.frontendPath` is absent.
+export const E2E_SPEC_LOCATIONS = [...PACKAGE_LOCATIONS, 'web'];

package/framework/hooks/shared/gate-question.js

@@ -0,0 +1,18 @@
+/**
+ * The gate a gate question asks about, or null. Explicit gate names win over
+ * words that may also appear in a feature slug ("plan", "design", "review").
+ *
+ * @param {string} question
+ * @returns {'plan'|'uiux'|'review'|null}
+ */
+export function gateFromQuestion(question) {
+  if (typeof question !== 'string') return null;
+  if (/gate\s+uiux/i.test(question)) return 'uiux';
+  if (/gate\s+3\b/i.test(question)) return 'review';
+  if (/gate\s+(?:[12]\b|d[oe]\s+plano|plan\b)/i.test(question)) return 'plan';
+  const lower = question.toLowerCase();
+  if (lower.includes('plano') || lower.includes('plan')) return 'plan';
+  if (lower.includes('design')) return 'uiux';
+  if (lower.includes('review') || lower.includes('ship')) return 'review';
+  return null;
+}

package/framework/hooks/shared/phase-utils.js

@@ -8,13 +8,12 @@
  */
 
 /** Phase order */
-export const PHASE_ORDER = ["proposal","uiux","plan","implement","review","sync"];
+export const PHASE_ORDER = ["plan","uiux","implement","review","sync"];
 
 /** Map phase → allowed output subdirectory */
 export const PHASE_DIRS = {
-  proposal: '0-proposal',
-  uiux: '1-design',
   plan: '2-plan',
+  uiux: '1-design',
   implement: '3-implement',
   review: '4-review',
   sync: '3-implement',
@@ -22,57 +21,41 @@ export const PHASE_DIRS = {
 
 /** Map output type (camelCase) → phase that produces it */
 export const OUTPUT_PHASE_MAP = {
-  proposal: 'proposal',
-  stackScan: 'proposal',
+  plan: 'plan',
+  checks: 'plan',
   uiDesignSystem: 'uiux',
   uiMockups: 'uiux',
   uiComponents: 'uiux',
   uiFlows: 'uiux',
-  spec: 'plan',
-  tasks: 'plan',
-  decisions: 'plan',
-  usecases: 'plan',
-  recap: 'implement',
   evidencias: 'implement',
-  reviewReport: 'review',
-  evaluatorReport: 'review',
+  verifierReport: 'review',
+  reviewerReport: 'review',
+  securityReport: 'review',
 };
 
 /** Map filename → output type (camelCase) */
 export const FILENAME_TO_OUTPUT = {
-  'proposal.md': 'proposal',
-  'stack-scan.md': 'stackScan',
+  'plan.md': 'plan',
+  'checks.json': 'checks',
   'design-system.md': 'uiDesignSystem',
   'mockups.md': 'uiMockups',
   'components.md': 'uiComponents',
   'flows.md': 'uiFlows',
-  'spec.md': 'spec',
-  'tasks.json': 'tasks',
-  'decisions.md': 'decisions',
-  'recap.md': 'recap',
-  'review-report.md': 'reviewReport',
-  'evaluator-report.md': 'evaluatorReport',
+  'verifier.md': 'verifierReport',
+  'reviewer.md': 'reviewerReport',
+  'security.md': 'securityReport',
 };
 
 /** Protected spec files and the approval gate that locks them */
 export const PROTECTED_SPEC_FILES = {
+  'plan.md': 'plan',
+  'checks.json': 'plan',
   'design-system.md': 'uiux',
   'mockups.md': 'uiux',
   'components.md': 'uiux',
   'flows.md': 'uiux',
-  'spec.md': 'plan',
-  'tasks.json': 'plan',
 };
 
-/**
- * For protected files that carry mutable progress fields: filename → the
- * top-level array-item fields that may change after the gate is approved.
- * When a protected file is listed here, the protect-spec-files hook does a
- * semantic diff (allowing only these fields to change) instead of a blanket block.
- */
-export const MUTABLE_SPEC_FIELDS = {
-  'tasks.json': ['status', 'outputs', 'notes'],
-};
 
 /**
  * Extract feature name from a .morph/features/{feature}/... path
@@ -88,7 +71,7 @@ export function extractFeatureName(filePath) {
 /**
  * Extract phase subdirectory from a .morph/features/{feature}/{phaseDir}/... path
  * @param {string} filePath - File path to analyze
- * @returns {string|null} Phase directory (e.g., '0-proposal', '2-design') or null
+ * @returns {string|null} Phase directory (e.g., '2-plan', '1-design') or null
  */
 export function extractPhaseDir(filePath) {
   const normalized = filePath.replace(/\\/g, '/');

package/framework/hooks/shared/slice-progress.js

@@ -0,0 +1,118 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/** `PARCIAL` on the report's first non-blank line, tolerating heading/bold/quote typography. */
+export const PARTIAL_MARKER = /^[\s#>*_]*PARCIAL\b/;
+
+export const SLICE_STATUSES = ['pendente', 'parcial', 'feito'];
+
+export function checksPath(featureDir) {
+  return join(featureDir, '2-plan', 'checks.json');
+}
+
+export function sliceReportPath(featureDir, sliceId) {
+  return join(featureDir, '3-implement', 'reports', `${sliceId}.md`);
+}
+
+/** Status of a slice from its report text: no report = pendente, PARCIAL first line = parcial, else feito. */
+export function sliceStatusFromReport(text) {
+  if (text == null) return 'pendente';
+  const first = String(text).split(/\r?\n/).find((l) => l.trim() !== '') ?? '';
+  return PARTIAL_MARKER.test(first) ? 'parcial' : 'feito';
+}
+
+/**
+ * Progress of a feature's slices.
+ *
+ * @param {string|null} checksText - the raw extracted checks file of the plan
+ * @param {(sliceId: string) => string|null} readReport - report text, null when absent
+ * @returns {{ total: number, done: number, partial: number, pending: number,
+ *   slices: { id: string, title: string, depends: string[], covers: string[], status: string }[] } | null} null when that file is unreadable
+ */
+export function sliceProgressFrom(checksText, readReport) {
+  let slices;
+  try {
+    slices = JSON.parse(checksText ?? '').slices;
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(slices)) return null;
+  const out = slices
+    .filter((s) => s && typeof s.id === 'string')
+    .map((s) => ({
+      id: s.id,
+      title: s.title ?? '',
+      depends: Array.isArray(s.depends) ? s.depends : [],
+      covers: Array.isArray(s.covers) ? s.covers : [],
+      status: sliceStatusFromReport(readReport(s.id)),
+    }));
+  const count = (status) => out.filter((s) => s.status === status).length;
+  return { total: out.length, done: count('feito'), partial: count('parcial'), pending: count('pendente'), slices: out };
+}
+
+function readOrNull(path) {
+  try {
+    return existsSync(path) ? readFileSync(path, 'utf8') : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Slice progress of the feature directory on disk. */
+export function sliceProgress(featureDir) {
+  return sliceProgressFrom(readOrNull(checksPath(featureDir)), (id) => readOrNull(sliceReportPath(featureDir, id)));
+}
+
+/** Unfinished slices whose dependencies are all done: what the next dispatch can take. */
+export function readySlices(progress) {
+  if (!progress) return [];
+  const done = new Set(progress.slices.filter((s) => s.status === 'feito').map((s) => s.id));
+  return progress.slices.filter((s) => s.status !== 'feito' && s.depends.every((d) => done.has(d)));
+}
+
+/**
+ * What a slice report must carry, besides prose and its covered scenarios.
+ * Loose on purpose: a false "complete" costs a read, a false "incomplete"
+ * re-dispatches finished work.
+ */
+export const REPORT_MARKERS = [
+  { id: 'files', re: /^\s*(?:[-*]\s*)?(?:\*\*|#+\s*)?arquivos\s*:?\**\s*:?/mi },
+];
+
+const MIN_PROSE_CHARS = 80;
+
+const scenarioRe = (id) => new RegExp(`(?<![\\w-])${id}(?![\\w-])`);
+
+/**
+ * Inspect one report file: does it exist, which mandatory items it lacks,
+ * and whether it is partial.
+ *
+ * @param {string} path
+ * @param {{ covers?: string[] }} [slice] - every scenario the slice covers must be named
+ */
+export function inspectReport(path, { covers = [] } = {}) {
+  const missingAll = ['what', 'files', ...covers];
+  if (!existsSync(path)) return { exists: false, complete: false, missing: missingAll };
+  let body = '';
+  try {
+    body = readFileSync(path, 'utf8');
+  } catch {
+    return { exists: true, complete: false, missing: missingAll, unreadable: true };
+  }
+
+  const missing = REPORT_MARKERS.filter((m) => !m.re.test(body)).map((m) => m.id);
+  missing.push(...covers.filter((id) => !scenarioRe(id).test(body)));
+  const prose = body
+    .split('\n')
+    .filter((l) => !/^\s*(#|[-*]\s|\*\*)/.test(l))
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (prose.length < MIN_PROSE_CHARS) missing.unshift('what');
+
+  const firstLine = body.split('\n').find((l) => l.trim() !== '') ?? '';
+  const partial = PARTIAL_MARKER.test(firstLine);
+  if (partial) missing.push('partial');
+
+  return { exists: true, complete: missing.length === 0, missing, partial };
+}

package/framework/hooks/shared/spawn-command.js

@@ -0,0 +1,23 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+const NEEDS_CMD_SHIM = /^(npm|npx|pnpm|yarn)$/;
+
+/**
+ * On win32 `npx`/`npm`/… are `.cmd` shims: ENOENT without a shell, EINVAL as `.cmd`
+ * with `shell: false`. Playwright runs from its own JS entry, so it needs no shell.
+ */
+export function resolveSpawn(file, args = [], {
+  cwd = process.cwd(),
+  platform = process.platform,
+  exists = existsSync,
+  execPath = process.execPath,
+} = {}) {
+  if (platform !== 'win32' || !NEEDS_CMD_SHIM.test(file)) return { file, args, shell: false };
+
+  if (file === 'npx' && args[0] === 'playwright') {
+    const cli = join(cwd, 'node_modules', '@playwright', 'test', 'cli.js');
+    if (exists(cli)) return { file: execPath, args: [cli, ...args.slice(1)], shell: false };
+  }
+  return { file: `${file}.cmd`, args, shell: true };
+}