@tekyzinc/gsd-t 3.21.11 → 3.22.10

package/bin/headless-auto-spawn.cjs

@@ -42,6 +42,31 @@ const {
 const SESSIONS_DIR_REL = path.join(".gsd-t", "headless-sessions");
 const LOG_DIR_REL = ".gsd-t"; // headless-{id}.log lives directly in .gsd-t
 
+// M50 D2 — Whitelist of commands that touch UI / tests. Centralized constant
+// referenced by the spawn-gate (`_isTestingOrUICommand`). When any of these
+// commands is about to spawn for a project where `hasUI(projectDir) === true`
+// and `hasPlaywright(projectDir) === false`, the gate auto-installs Playwright
+// before the spawn proceeds. See playwright-bootstrap-contract.md §3 +
+// m50-integration-points.md "E2E Specs Server Lifecycle".
+const TESTING_OR_UI_COMMANDS = new Set([
+  "gsd-t-execute",
+  "gsd-t-test-sync",
+  "gsd-t-verify",
+  "gsd-t-quick",
+  "gsd-t-wave",
+  "gsd-t-milestone",
+  "gsd-t-complete-milestone",
+  "gsd-t-debug",
+  "gsd-t-integrate",
+]);
+
+function _isTestingOrUICommand(command) {
+  if (typeof command !== "string" || !command) return false;
+  // Accept both raw command names and prefixed variants ("execute" or "gsd-t-execute").
+  const normalized = command.startsWith("gsd-t-") ? command : `gsd-t-${command}`;
+  return TESTING_OR_UI_COMMANDS.has(normalized);
+}
+
 // ── Exports ──────────────────────────────────────────────────────────────────
 
 module.exports = {
@@ -55,6 +80,11 @@ module.exports = {
   // it now unconditionally returns true. See headless-default-contract
   // v2.0.0 §Invariants.
   shouldSpawnHeadless: () => true,
+  // M49 — exported for tests. Synchronous probe; never throws.
+  _probeDashboardLazy,
+  // M50 D2 — exported for tests. Whitelist + classifier, both synchronous.
+  TESTING_OR_UI_COMMANDS,
+  _isTestingOrUICommand,
 };
 
 // M43 D4 — one-shot deprecation banner when a caller still passes `watch`
@@ -119,6 +149,99 @@ function autoSpawnHeadless(opts) {
     );
   }
 
+  // M50 D2 — Spawn-time Playwright gate. When the command being spawned is a
+  // testing/UI-touching command AND the project has a UI signal AND there's
+  // no playwright.config.* yet, auto-install Playwright before the spawn
+  // proceeds. On install failure, write a `mode: 'blocked-needs-human'`
+  // session-state file (read by gsd-t-resume Step 0 + read-back banner) and
+  // exit 4. See playwright-bootstrap-contract.md §3 + §8 and
+  // m50-integration-points.md for the full protocol.
+  //
+  // Hot path: the gate evaluates `_isTestingOrUICommand` (Set lookup) →
+  // `hasUI` (depth-bounded fs walk) → `hasPlaywright` (existsSync). When the
+  // gate does NOT fire (non-testing command, non-UI project, or already
+  // configured), overhead is the cost of three fast filesystem checks.
+  // Tests inject `opts._gateInstaller` to substitute a stub installer; tests
+  // also inject `opts._gateProbes` to override `hasUI`/`hasPlaywright` for
+  // non-fixture-based assertions.
+  if (_isTestingOrUICommand(command)) {
+    const probes = (opts && opts._gateProbes) || null;
+    let projectHasUI;
+    let projectHasPlaywright;
+    try {
+      const ui = probes && probes.hasUI ? probes.hasUI : require("./ui-detection.cjs").hasUI;
+      const pw = probes && probes.hasPlaywright ? probes.hasPlaywright : require("./playwright-bootstrap.cjs").hasPlaywright;
+      projectHasUI = !!ui(projectDir);
+      projectHasPlaywright = !!pw(projectDir);
+    } catch (_e) {
+      // Probe failure → fail open: skip the gate. A broken probe is worse
+      // than a permissive one (we don't want to block every spawn on a stale
+      // import path).
+      projectHasUI = false;
+      projectHasPlaywright = true;
+    }
+    if (projectHasUI && !projectHasPlaywright) {
+      let installer;
+      try {
+        installer = (opts && opts._gateInstaller) ||
+          require("./playwright-bootstrap.cjs").installPlaywrightSync;
+      } catch (_e) {
+        installer = null;
+      }
+      if (typeof installer === "function") {
+        const result = installer(projectDir);
+        if (result && result.ok) {
+          try {
+            // Concise stdout signal so the user sees the gate fired.
+            process.stdout.write(
+              `▶ Playwright auto-installed (${path.relative(projectDir, path.join(projectDir, "playwright.config.ts"))})\n`,
+            );
+          } catch (_) { /* best-effort */ }
+        } else {
+          // Install failed → mode: 'blocked-needs-human', exit 4.
+          const blockedId = makeSessionId(command, new Date());
+          try {
+            ensureDir(path.join(projectDir, SESSIONS_DIR_REL));
+            writeSessionFile(projectDir, {
+              id: blockedId,
+              pid: null,
+              logPath: null,
+              startTimestamp: new Date().toISOString(),
+              command,
+              args,
+              status: "blocked",
+              mode: "blocked-needs-human",
+              reason: "playwright-install-failed",
+              err: (result && result.err) || "unknown",
+              hint: (result && result.hint) || null,
+              continueFromPath: continue_from,
+              surfaced: false,
+            });
+          } catch (_) { /* best-effort */ }
+          try {
+            process.stderr.write(
+              `[m50-spawn-gate] Playwright install failed (${(result && result.err) || "unknown"}). ` +
+              `Run \`gsd-t doctor --install-playwright\` to retry. Spawn aborted.\n`,
+            );
+          } catch (_) { /* best-effort */ }
+          // In test runs we don't want to actually exit the test harness;
+          // tests inject `opts._gateExit` to capture the exit instead.
+          if (opts && typeof opts._gateExit === "function") {
+            opts._gateExit(4);
+            return {
+              id: blockedId,
+              pid: null,
+              logPath: null,
+              timestamp: new Date().toISOString(),
+              mode: "blocked-needs-human",
+            };
+          }
+          process.exit(4);
+        }
+      }
+    }
+  }
+
   const timestamp = new Date().toISOString();
   const id = makeSessionId(command, new Date());
   const logPath = path.join(projectDir, LOG_DIR_REL, `headless-${id}.log`);
@@ -126,16 +249,18 @@ function autoSpawnHeadless(opts) {
   ensureDir(path.join(projectDir, LOG_DIR_REL));
   ensureDir(path.join(projectDir, SESSIONS_DIR_REL));
 
-  // M43 D6-T4 — Ensure dashboard is running (idempotent; no-op if already up).
-  // Must happen BEFORE the URL banner print (D6-T3) so the link is live.
-  // Never throws — autostart is best-effort.
-  let autostartInfo = null;
-  try {
-    const { ensureDashboardRunning } = require("../scripts/gsd-t-dashboard-autostart.cjs");
-    autostartInfo = ensureDashboardRunning({ projectDir });
-  } catch (_) {
-    /* best-effort; fall through without banner port info */
-  }
+  // M49 — Lazy dashboard. Spawns no longer autostart the dashboard. Each
+  // spawn would otherwise fork-detach a fresh `gsd-t-dashboard-server.js`
+  // (M43 D6-T4); 99% of those banners are never opened so they accumulated
+  // to 88+ orphans on the project-scoped port range. The dashboard now only
+  // starts when the user explicitly invokes `/gsd-t-visualize`. The banner
+  // below remains, but becomes conditional on whether a dashboard is already
+  // listening on the project's scoped port.
+  //
+  // Probe is sync + cheap: read `.gsd-t/.dashboard.pid` and `process.kill(pid, 0)`.
+  // Falls back to "no dashboard" on any error — never throws.
+  // See .gsd-t/contracts/headless-default-contract.md v2.0.0 §M49 (lazy banner).
+  const dashboardInfo = _probeDashboardLazy(projectDir);
 
   // M46 follow-up — Date + version banner. Printed before the transcript URL
   // so multi-day-old read-backs are immediately dated. Best-effort.
@@ -155,17 +280,27 @@ function autoSpawnHeadless(opts) {
     /* best-effort — never crash the spawn on banner failure */
   }
 
-  // M43 D6-T3 — Live transcript URL banner. Printed for every spawn so the
-  // viewer at :PORT is "the" primary watching surface. Never throws.
-  // Text is coordinated with D4 — exact line shape is part of
-  // dashboard-server-contract.md §Banner Format.
+  // M49 — Conditional transcript banner. If a dashboard is already running
+  // on the project's scoped port, point at the live URL (M43 D6-T3 shape).
+  // Otherwise, point at the on-disk log path and hint at /gsd-t-visualize so
+  // the user knows how to open the viewer if they want it. The viewer URL
+  // is no longer printed for spawns where no listener exists — that is what
+  // caused users to assume one was running and accumulated orphans on retry.
+  //
+  // Text is coordinated with D4 — banner format spec in
+  // .gsd-t/contracts/dashboard-server-contract.md v1.3.0 §Banner Format
+  // and headless-default-contract.md v2.0.0 §M49.
   try {
-    let port = autostartInfo && autostartInfo.port;
-    if (!port) {
-      const { projectScopedDefaultPort } = require("../scripts/gsd-t-dashboard-server.js");
-      port = projectScopedDefaultPort(projectDir);
+    if (dashboardInfo.running && dashboardInfo.port) {
+      process.stdout.write(
+        `▶ Live transcript: http://127.0.0.1:${dashboardInfo.port}/transcript/${id}\n`,
+      );
+    } else {
+      const relLog = path.relative(projectDir, logPath);
+      process.stdout.write(
+        `▶ Transcript file: ${relLog}\n  (to view live: gsd-t-visualize)\n`,
+      );
     }
-    process.stdout.write(`▶ Live transcript: http://127.0.0.1:${port}/transcript/${id}\n`);
   } catch (_) {
     /* best-effort — never crash the spawn on banner failure */
   }
@@ -515,6 +650,57 @@ function appendTokenLog(projectDir, entry) {
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
+/**
+ * M49 — Cheap synchronous probe: is a dashboard listening on this project's
+ * scoped port? Strategy: read `.gsd-t/.dashboard.pid`; if the pid is alive
+ * (`process.kill(pid, 0)` doesn't throw), assume the dashboard is up and
+ * resolve the port via `projectScopedDefaultPort(projectDir)`. No child
+ * process forking — this runs on every spawn and must be cheap.
+ *
+ * Returns `{ running: boolean, port: number|null, pid: number|null }`. Never
+ * throws. A return of `{ running: false }` is the safe fallback that drives
+ * the file-path-only banner.
+ *
+ * @param {string} projectDir
+ * @returns {{ running: boolean, port: number|null, pid: number|null }}
+ */
+function _probeDashboardLazy(projectDir) {
+  const out = { running: false, port: null, pid: null };
+  try {
+    const pidFile = path.join(projectDir, ".gsd-t", ".dashboard.pid");
+    if (!fs.existsSync(pidFile)) return out;
+    const raw = fs.readFileSync(pidFile, "utf8").trim();
+    const pid = parseInt(raw, 10);
+    if (!pid || Number.isNaN(pid) || pid <= 0) return out;
+    // process.kill(pid, 0) — signal 0 only checks for existence/permission.
+    // Throws ESRCH if no such process; EPERM if process exists but owned by
+    // someone else. EPERM still implies "alive", so treat both ESRCH-only as
+    // dead.
+    try {
+      process.kill(pid, 0);
+    } catch (err) {
+      if (err && err.code === "EPERM") {
+        // Alive but not owned by us — still a live listener; treat as running.
+      } else {
+        return out; // ESRCH or unknown — treat as dead.
+      }
+    }
+    out.pid = pid;
+    out.running = true;
+    try {
+      const { projectScopedDefaultPort } = require("../scripts/gsd-t-dashboard-server.js");
+      out.port = projectScopedDefaultPort(projectDir);
+    } catch (_) {
+      // Without the port we can't render the URL — fall back to file banner.
+      out.running = false;
+      out.port = null;
+    }
+  } catch (_) {
+    /* probe is best-effort */
+  }
+  return out;
+}
+
 function ensureDir(d) {
   if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
 }

package/bin/playwright-bootstrap.cjs

@@ -0,0 +1,315 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { exec, spawn, spawnSync } = require('child_process');
+
+function hasPlaywright(projectDir) {
+  const configs = ['playwright.config.ts', 'playwright.config.js', 'playwright.config.mjs'];
+  try {
+    return configs.some((f) => fs.existsSync(path.join(projectDir, f)));
+  } catch (_) {
+    return false;
+  }
+}
+
+function detectPackageManager(projectDir) {
+  try {
+    if (fs.existsSync(path.join(projectDir, 'pnpm-lock.yaml'))) return 'pnpm';
+    if (fs.existsSync(path.join(projectDir, 'yarn.lock'))) return 'yarn';
+    if (fs.existsSync(path.join(projectDir, 'bun.lockb'))) return 'bun';
+  } catch (_) {
+    // fall through to default
+  }
+  return 'npm';
+}
+
+function verifyPlaywrightHealth(projectDir) {
+  return new Promise((resolve) => {
+    const child = exec(
+      'npx playwright --version',
+      { cwd: projectDir, timeout: 5000 },
+      (err, stdout, stderr) => {
+        if (err) {
+          resolve({ ok: false, error: stderr || err.message || String(err) });
+          return;
+        }
+        const match = (stdout || '').match(/Version\s+([\d.]+)/i);
+        if (match) {
+          resolve({ ok: true, version: match[1] });
+        } else {
+          resolve({ ok: false, error: 'Could not parse version from: ' + stdout.trim() });
+        }
+      },
+    );
+    // Belt-and-suspenders: exec timeout option should handle this, but guard anyway
+    child.on('error', (err) => {
+      resolve({ ok: false, error: err.message || String(err) });
+    });
+  });
+}
+
+// ── installPlaywright ────────────────────────────────────────────────────────
+//
+// Idempotent installer. Per playwright-bootstrap-contract.md §3 + §6 + §7 + §8.
+// Returns { ok: true } on success, { ok: false, err, hint } on failure.
+
+const PLAYWRIGHT_CONFIG_TEMPLATE = `import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: 'html',
+  use: {
+    baseURL: process.env.PLAYWRIGHT_BASE_URL ?? 'http://localhost:3000',
+    trace: 'on-first-retry',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+  ],
+  // webServer is intentionally omitted — projects manage their own server lifecycle.
+});
+`;
+
+const PLACEHOLDER_SPEC_TEMPLATE = `import { test } from '@playwright/test';
+
+// Placeholder spec — replace with real specs when UI tests land.
+test.skip('placeholder', () => {});
+`;
+
+const INSTALL_COMMANDS = {
+  npm: { cmd: 'npm', args: ['install', '-D', '@playwright/test'] },
+  pnpm: { cmd: 'pnpm', args: ['add', '-D', '@playwright/test'] },
+  yarn: { cmd: 'yarn', args: ['add', '-D', '@playwright/test'] },
+  bun: { cmd: 'bun', args: ['add', '-d', '@playwright/test'] },
+};
+
+function _classifyError(stderr, code, command) {
+  const text = String(stderr || '').toLowerCase();
+  if (code === 127 || /command not found|enoent|not recognized|spawn .* enoent/i.test(text)) {
+    return {
+      err: 'package-manager-not-found',
+      hint: 'Install the package manager (' + command + ') and re-run: gsd-t doctor --install-playwright',
+    };
+  }
+  if (/network|registry|getaddrinfo|enotfound|econnrefused|etimedout|enetunreach/i.test(text)) {
+    return {
+      err: stderr || 'network-failure',
+      hint: 'Check network connectivity and retry: gsd-t doctor --install-playwright',
+    };
+  }
+  if (/chromium|browsers? could not be downloaded|browser.*download/i.test(text)) {
+    return {
+      err: stderr || 'chromium-download-failed',
+      hint: 'Run npx playwright install chromium manually',
+    };
+  }
+  if (/eacces|eperm|permission|read-only|enospc|disk/i.test(text)) {
+    return {
+      err: stderr || 'disk-write-failed',
+      hint: 'Check filesystem permissions',
+    };
+  }
+  return {
+    err: stderr || 'install-failed',
+    hint: 'Run gsd-t doctor --install-playwright to retry',
+  };
+}
+
+function _runSubprocess(cmd, args, cwd) {
+  return new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let child;
+    try {
+      child = spawn(cmd, args, {
+        cwd,
+        env: process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      resolve({ code: 127, stdout: '', stderr: err.message || String(err) });
+      return;
+    }
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', (err) => {
+      resolve({ code: 127, stdout, stderr: stderr + (err.message || String(err)) });
+    });
+    child.on('close', (code) => {
+      resolve({ code: code == null ? 1 : code, stdout, stderr });
+    });
+  });
+}
+
+function _writeIfAbsent(filePath, content) {
+  try {
+    if (fs.existsSync(filePath)) return { ok: true, wrote: false };
+    fs.writeFileSync(filePath, content);
+    return { ok: true, wrote: true };
+  } catch (err) {
+    return { ok: false, error: err.message || String(err) };
+  }
+}
+
+function _ensureE2EPlaceholder(projectDir) {
+  try {
+    const e2eDir = path.join(projectDir, 'e2e');
+    let dirExists = false;
+    try {
+      dirExists = fs.statSync(e2eDir).isDirectory();
+    } catch (_e) {
+      dirExists = false;
+    }
+    if (!dirExists) {
+      fs.mkdirSync(e2eDir, { recursive: true });
+    } else {
+      // If e2e exists and is non-empty, do not overwrite.
+      const entries = fs.readdirSync(e2eDir);
+      if (entries.length > 0) return { ok: true, wrote: false };
+    }
+    const specPath = path.join(e2eDir, '__placeholder.spec.ts');
+    if (!fs.existsSync(specPath)) {
+      fs.writeFileSync(specPath, PLACEHOLDER_SPEC_TEMPLATE);
+      return { ok: true, wrote: true };
+    }
+    return { ok: true, wrote: false };
+  } catch (err) {
+    return { ok: false, error: err.message || String(err) };
+  }
+}
+
+async function installPlaywright(projectDir, opts) {
+  // Idempotent short-circuit: already configured.
+  if (hasPlaywright(projectDir)) return { ok: true };
+
+  const pm = detectPackageManager(projectDir);
+  const install = INSTALL_COMMANDS[pm] || INSTALL_COMMANDS.npm;
+
+  // Tests use opts.runner to inject a stub of `_runSubprocess` so we can
+  // exercise each package-manager branch and error path without actually
+  // hitting npm/pnpm/yarn/bun. Production callers omit it.
+  const runner = (opts && opts.runner) || _runSubprocess;
+
+  // Step 3: install @playwright/test as a devDependency
+  let r = await runner(install.cmd, install.args, projectDir);
+  if (r.code !== 0) {
+    const c = _classifyError(r.stderr, r.code, install.cmd);
+    return { ok: false, err: c.err, hint: c.hint };
+  }
+
+  // Step 4: install chromium browser
+  r = await runner('npx', ['playwright', 'install', 'chromium'], projectDir);
+  if (r.code !== 0) {
+    const c = _classifyError(r.stderr, r.code, 'npx');
+    // Partial install: @playwright/test landed, chromium did not. Surface that.
+    return {
+      ok: false,
+      err: c.err,
+      hint: c.hint,
+      partial: true,
+    };
+  }
+
+  // Step 5: write playwright.config.ts (idempotent — does not overwrite)
+  const configPath = path.join(projectDir, 'playwright.config.ts');
+  const cfgWrite = _writeIfAbsent(configPath, PLAYWRIGHT_CONFIG_TEMPLATE);
+  if (!cfgWrite.ok) {
+    const c = _classifyError(cfgWrite.error, 1, 'fs.writeFile');
+    return { ok: false, err: c.err, hint: c.hint };
+  }
+
+  // Step 6: e2e/ scaffolding (idempotent — does not overwrite existing files)
+  const placeholderWrite = _ensureE2EPlaceholder(projectDir);
+  if (!placeholderWrite.ok) {
+    const c = _classifyError(placeholderWrite.error, 1, 'fs.writeFile');
+    return { ok: false, err: c.err, hint: c.hint };
+  }
+
+  return { ok: true };
+}
+
+// ── installPlaywrightSync ────────────────────────────────────────────────────
+//
+// Synchronous variant of installPlaywright(). Same idempotency + template +
+// error-classifier semantics as the async form, implemented with `spawnSync`
+// so it can be embedded inside synchronous code paths (notably the M50 D2
+// spawn-gate in bin/headless-auto-spawn.cjs::autoSpawnHeadless, which must
+// remain sync to preserve the existing return-value contract relied on by
+// bin/gsd-t-parallel.cjs::runDispatch).
+//
+// Returns the same shape as installPlaywright(): {ok: true} or
+// {ok: false, err, hint, partial?: true}. Tests inject opts.runner the same
+// way; production callers omit it.
+
+function _runSubprocessSync(cmd, args, cwd) {
+  let res;
+  try {
+    res = spawnSync(cmd, args, {
+      cwd,
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    });
+  } catch (err) {
+    return { code: 127, stdout: '', stderr: err.message || String(err) };
+  }
+  if (res.error) {
+    return { code: 127, stdout: '', stderr: res.error.message || String(res.error) };
+  }
+  return {
+    code: res.status == null ? 1 : res.status,
+    stdout: res.stdout || '',
+    stderr: res.stderr || '',
+  };
+}
+
+function installPlaywrightSync(projectDir, opts) {
+  if (hasPlaywright(projectDir)) return { ok: true };
+
+  const pm = detectPackageManager(projectDir);
+  const install = INSTALL_COMMANDS[pm] || INSTALL_COMMANDS.npm;
+  const runner = (opts && opts.runner) || _runSubprocessSync;
+
+  let r = runner(install.cmd, install.args, projectDir);
+  if (r.code !== 0) {
+    const c = _classifyError(r.stderr, r.code, install.cmd);
+    return { ok: false, err: c.err, hint: c.hint };
+  }
+
+  r = runner('npx', ['playwright', 'install', 'chromium'], projectDir);
+  if (r.code !== 0) {
+    const c = _classifyError(r.stderr, r.code, 'npx');
+    return { ok: false, err: c.err, hint: c.hint, partial: true };
+  }
+
+  const configPath = path.join(projectDir, 'playwright.config.ts');
+  const cfgWrite = _writeIfAbsent(configPath, PLAYWRIGHT_CONFIG_TEMPLATE);
+  if (!cfgWrite.ok) {
+    const c = _classifyError(cfgWrite.error, 1, 'fs.writeFile');
+    return { ok: false, err: c.err, hint: c.hint };
+  }
+
+  const placeholderWrite = _ensureE2EPlaceholder(projectDir);
+  if (!placeholderWrite.ok) {
+    const c = _classifyError(placeholderWrite.error, 1, 'fs.writeFile');
+    return { ok: false, err: c.err, hint: c.hint };
+  }
+
+  return { ok: true };
+}
+
+module.exports = {
+  hasPlaywright,
+  detectPackageManager,
+  verifyPlaywrightHealth,
+  installPlaywright,
+  installPlaywrightSync,
+  // Exposed for tests; treat as private.
+  _PLAYWRIGHT_CONFIG_TEMPLATE: PLAYWRIGHT_CONFIG_TEMPLATE,
+  _PLACEHOLDER_SPEC_TEMPLATE: PLACEHOLDER_SPEC_TEMPLATE,
+  _INSTALL_COMMANDS: INSTALL_COMMANDS,
+};