create-pmos 0.15.0 → 0.16.1

package/workspace/design-parity.js

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+/* design-parity — decides whether the workspace matches the design the PM handed over.
+ *
+ * The PM's bar for this surface was one word: IDENTICAL. That is not a thing anyone can hold in
+ * their head across four panels, two themes and ten interaction states, so it is decided here
+ * mechanically instead. This renders the PM's own prototype and the built app side by side at the
+ * same viewport with the same font files, and diffs them on four axes:
+ *
+ *   text      the ordered list of rendered text nodes — a reworded label is a failure
+ *   style     computed styles on structurally-matched elements
+ *   geometry  bounding boxes, to a 2px tolerance
+ *   pixels    a screenshot diff, failing above 0.5% of the viewport
+ *
+ * WHY THE APP IS RENDERED IN FIXTURE MODE. A diff needs like-for-like content, and the app's real
+ * content is this repository. `?fixture=proto` loads the prototype's own seed data through the app's
+ * real renderer — so what is being compared is the rendering, which is the thing under test, and not
+ * the data, which is not. The same fixture doubles as the offline demo path: it proves the UI draws
+ * with no repository readable at all. What it deliberately does NOT prove is that the app is wired to
+ * anything; that is dimension 2 of the rubric and it is asserted in ui-test.js against real state.
+ *
+ * OFFLINE BY CONSTRUCTION. The prototype's runtime fetches React from unpkg. Both files are vendored
+ * under planning/design/four-panel/vendor/ and injected through the runtime's own `window.__resources`
+ * override, and the Google Fonts link is rewritten to the workspace's own vendored woff2 — the same
+ * byte-identical faces the app serves, so a font-fallback difference can never be mistaken for a
+ * design difference. Babel is not vendored because the prototype does not need it (verified: the
+ * render is node-for-node identical without it).
+ *
+ *   node design-parity.js                  both themes, default state
+ *   node design-parity.js --theme=light    one theme
+ *   node design-parity.js --states         also walk the interaction states (see STATES below)
+ *   node design-parity.js --state=<id>     one named state
+ *   node design-parity.js --keep           keep the rendered PNGs for inspection
+ *
+ * THE STATE WALK. `--states` was advertised in this header for two review rounds while doing
+ * nothing — the flag was never read, so "identical across the captured interaction states" (PRD
+ * success criterion 1, and the rubric's test_method) was decided on the opening screen alone. It is
+ * implemented now: each state is a list of LABELS to click, applied to the prototype and to the app
+ * from a fresh load, and the same four axes are diffed at the end of the sequence. The steps are
+ * text, not selectors, deliberately — a selector would encode one page's DOM and quietly stop
+ * matching on the other, which is the shape a check takes when it goes decorative. A step that
+ * cannot find its label on EITHER page is a hard failure: "could not drive the app there" must
+ * never be recorded as "the app matched there".
+ *
+ * Exit 0 only when every axis is clean. Exit 3 means it could not run (no browser, no server) —
+ * which is a skip, and is reported as one rather than as a pass.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const os = require('os');
+
+const ROOT = path.resolve(__dirname, '..');
+const DESIGN = path.join(ROOT, 'planning', 'design', 'four-panel');
+const FONTS = path.join(__dirname, 'public', 'vendor');
+const APP_URL = process.env.PMOS_PARITY_APP || 'http://127.0.0.1:7433';
+const REF_PORT = +(process.env.PMOS_PARITY_PORT || 8899);
+const OUT = process.env.PMOS_PARITY_OUT || path.join(os.tmpdir(), 'pmos-design-parity');
+
+const argv = process.argv.slice(2);
+const themes = argv.some((a) => a.startsWith('--theme=')) ? [argv.find((a) => a.startsWith('--theme=')).split('=')[1]] : ['dark', 'light'];
+const KEEP = argv.includes('--keep');
+const W = 1600, H = 1000;
+
+/* THE CAPTURED INTERACTION STATES.
+ *
+ * Each entry is a state the PM can put the surface into, expressed as the labels a person would
+ * click to get there — read as the element's OWN text, so "add repository" means the span holding
+ * exactly that, in either page's markup. `default` is the opening screen and always runs.
+ *
+ * Chosen because each one changes a DIFFERENT part of the layout, so the set covers the interaction
+ * model the handoff brief calls final rather than repeating one kind of change: a drawer over panel
+ * 1, a collapsed group in panel 2, an expanded task tree and an opened tab in panels 3 and 4, a
+ * collapsed column, and the panel-3 inline expansion. A state whose divergence is a DECISION rather
+ * than a defect does not belong here — it belongs in the PRD — so if one is ever excluded, the
+ * reason goes in `why` and gets printed, not left as an absence nobody can see.
+ */
+const STATES = [
+  { id: 'default', steps: [] },
+  { id: 'settings-drawer', steps: ['settings & tools'] },
+  { id: 'group-collapsed', steps: ['health:tech'] },
+  { id: 'phase-collapsed', steps: ['intake'] },
+  { id: 'task-tab-open', steps: ['produce the build output'] },
+  { id: 'column-collapsed', steps: ['⟨'] },
+  { id: 'add-repository', steps: ['add repository'] },
+];
+const stateArg = argv.find((a) => a.startsWith('--state='));
+const states = stateArg
+  ? STATES.filter((s) => s.id === stateArg.split('=')[1])
+  : (argv.includes('--states') ? STATES : STATES.filter((s) => s.id === 'default'));
+if (!states.length) {
+  console.error(`no such state: ${stateArg.split('=')[1]} — known: ${STATES.map((s) => s.id).join(', ')}`);
+  process.exit(2);
+}
+
+const PROPS = [
+  'display', 'gridTemplateColumns', 'gridTemplateRows', 'flexDirection', 'alignItems',
+  'justifyContent', 'gap', 'minHeight', 'padding', 'backgroundColor', 'color',
+  'borderTopWidth', 'borderRightWidth', 'borderBottomWidth', 'borderLeftWidth',
+  'borderLeftColor', 'borderBottomColor', 'borderRadius', 'fontFamily', 'fontSize', 'fontWeight',
+  'lineHeight', 'letterSpacing', 'textTransform', 'writingMode', 'overflowX', 'overflowY',
+];
+
+function skip(why) { console.log(`⏭  design-parity SKIPPED — ${why}`); process.exit(3); }
+
+function requireOptional(name) { try { return require(name); } catch { return null; } }
+
+// ── the reference page, patched offline in memory ───────────────────────────────────────────────
+function referenceHtml() {
+  const src = fs.readFileSync(path.join(DESIGN, 'prototype-original.html'), 'utf8');
+  const map = JSON.stringify({
+    'https://unpkg.com/react@18.3.1/umd/react.production.min.js': './vendor/react.production.min.js',
+    'https://unpkg.com/react-dom@18.3.1/umd/react-dom.production.min.js': './vendor/react-dom.production.min.js',
+  });
+  let h = src.replace('<script src="./support.js"></script>',
+    `<script>window.__resources=${map};</script>\n<script src="./support.js"></script>`);
+  h = h.replace(/<link rel="preconnect"[^>]*>\s*/g, '');
+  h = h.replace(/<link href="https:\/\/fonts\.googleapis\.com[^>]*>/, '<link rel="stylesheet" href="./fonts.css">');
+  if (/fonts\.googleapis|unpkg\.com/.test(h.replace(map, ''))) {
+    throw new Error('reference page still carries a remote asset after patching — refusing to compare against a page that would need the network');
+  }
+  return h;
+}
+
+const FONTS_CSS = `
+@font-face{font-family:"Space Grotesk";src:url("./fonts/space-grotesk-var.woff2") format("woff2-variations");font-weight:300 700;font-style:normal;font-display:block}
+@font-face{font-family:"IBM Plex Mono";src:url("./fonts/ibm-plex-mono-400.woff2") format("woff2");font-weight:400;font-style:normal;font-display:block}
+@font-face{font-family:"IBM Plex Mono";src:url("./fonts/ibm-plex-mono-500.woff2") format("woff2");font-weight:500;font-style:normal;font-display:block}
+@font-face{font-family:"IBM Plex Mono";src:url("./fonts/ibm-plex-mono-700.woff2") format("woff2");font-weight:700;font-style:normal;font-display:block}
+`;
+
+function serveReference() {
+  const html = referenceHtml();
+  const types = { '.js': 'text/javascript', '.css': 'text/css', '.woff2': 'font/woff2', '.html': 'text/html' };
+  const server = http.createServer((req, res) => {
+    const p = decodeURIComponent(req.url.split('?')[0]);
+    if (p === '/' || p === '/index.html') { res.writeHead(200, { 'content-type': 'text/html' }); return res.end(html); }
+    if (p === '/fonts.css') { res.writeHead(200, { 'content-type': 'text/css' }); return res.end(FONTS_CSS); }
+    let file = null;
+    if (p.startsWith('/fonts/')) file = path.join(FONTS, path.basename(p));
+    else if (p === '/support.js' || p.startsWith('/vendor/')) file = path.join(DESIGN, p.replace(/^\//, ''));
+    if (file && fs.existsSync(file)) {
+      res.writeHead(200, { 'content-type': types[path.extname(file)] || 'application/octet-stream' });
+      return res.end(fs.readFileSync(file));
+    }
+    res.writeHead(404).end('not found');
+  });
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(REF_PORT, '127.0.0.1', () => resolve(server));
+  });
+}
+
+/* Click the element whose OWN text is `label`, on whichever page it is given. Returns false when
+ * nothing visible carries that text — the caller turns that into a failure rather than skipping the
+ * state, because a state that could not be reached is not a state that matched. `closest('button')`
+ * is what actually gets clicked: the prototype's runtime wraps each interpolated label in a span, so
+ * the text node and the control are usually different elements. */
+async function drive(page, steps) {
+  const applied = [];
+  for (const label of steps) {
+    const hit = await page.evaluate((lab) => {
+      const own = (e) => [...e.childNodes].filter((n) => n.nodeType === 3)
+        .map((n) => n.textContent.replace(/\s+/g, ' ').trim()).join(' ').trim();
+      const visible = (e) => {
+        const cs = getComputedStyle(e);
+        if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0') return false;
+        const r = e.getBoundingClientRect();
+        return r.width > 0 && r.height > 0;
+      };
+      const target = [...document.querySelectorAll('*')].find((e) => own(e) === lab && visible(e));
+      if (!target) return false;
+      (target.closest('button,[role="button"]') || target).click();
+      return true;
+    }, label);
+    applied.push({ label, hit });
+    await page.waitForTimeout(600);
+  }
+  return applied;
+}
+
+async function snap(browser, url, theme, tag, steps = []) {
+  const page = await browser.newPage({ viewport: { width: W, height: H }, deviceScaleFactor: 1 });
+  const errors = [];
+  page.on('pageerror', (e) => errors.push(String(e.message)));
+  page.on('console', (m) => { if (m.type() === 'error') errors.push(m.text()); });
+  await page.goto(url, { waitUntil: 'networkidle', timeout: 60000 });
+  await page.waitForTimeout(1200);
+  if (theme === 'light') {
+    await page.evaluate(() => {
+      const b = [...document.querySelectorAll('button')].find((x) => /theme/i.test(x.textContent || ''));
+      if (b) b.click();
+    });
+    await page.waitForTimeout(500);
+  }
+  // The interaction steps are applied AFTER the theme is settled, so a state is diffed in the theme
+  // it was reached in rather than in whatever theme the toggle left behind.
+  const applied = await drive(page, steps);
+  await page.waitForFunction(() => document.fonts.status === 'loaded', null, { timeout: 15000 }).catch(() => {});
+  const png = path.join(OUT, `${tag}.png`);
+  await page.screenshot({ path: png });
+  const data = await page.evaluate((props) => {
+    const root = document.querySelector('[data-pm-theme]') || document.body;
+    const nodes = [], texts = [];
+    const walk = (e) => {
+      const cs = getComputedStyle(e);
+      if (cs.display === 'none') return;
+      const r = e.getBoundingClientRect();
+      const own = [...e.childNodes].filter((n) => n.nodeType === 3)
+        .map((n) => n.textContent.replace(/\s+/g, ' ').trim()).filter(Boolean).join(' ');
+      const st = {}; for (const p of props) st[p] = cs[p];
+      // `full` is the element's WHOLE visible text, used to anchor style comparison; `own` is only
+      // its own text nodes. They differ because the prototype's runtime wraps each interpolation in
+      // a span, so its label sits one element deeper than the app's.
+      nodes.push({ text: own.slice(0, 60), full: (e.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 80),
+        box: [r.x, r.y, r.width, r.height].map(Math.round), st });
+      // Walk childNodes IN ORDER, emitting text where it actually sits rather than hoisting all of an
+      // element's own text ahead of its children. The status bar is the case that forced this: the
+      // design writes "local · persistent server · ", then a <span> holding the count, then
+      // " sessions running", so hoisting produced "…server · sessions running 3" and reported a text
+      // difference on a bar that is pixel-identical. Reading order is what the PM sees; it is what
+      // the stream has to be.
+      for (const c of e.childNodes) {
+        if (c.nodeType === 3) {
+          const s = c.textContent.replace(/\s+/g, ' ').trim();
+          if (s) texts.push(s);
+        } else if (c.nodeType === 1) walk(c);
+      }
+    };
+    walk(root);
+    return { nodes, texts };
+  }, PROPS);
+  await page.close();
+  return { ...data, errors, png, applied };
+}
+
+function diff(A, B, theme) {
+  const problems = [];
+  if (B.errors.length) problems.push(`console errors in the app (${B.errors.length}): ${B.errors.slice(0, 5).join(' | ')}`);
+  // Compare the CONCATENATED stream, not the node list. Node boundaries are an artefact of the
+  // prototype's interpolation wrappers: its template runtime wraps every {{ }} in a <span>, so the
+  // status bar's session count is three text nodes there and one in the app. The handoff brief calls
+  // that runtime an implementation detail, so reproducing its wrapper elements would be copying the
+  // scaffolding rather than the design. What the PM reads is the sequence of words on screen, and
+  // that is what has to match — in content and in order.
+  const streamA = A.texts.join(' ').replace(/\s+/g, ' ').trim();
+  const streamB = B.texts.join(' ').replace(/\s+/g, ' ').trim();
+  let missing = [], extra = [];
+  if (streamA !== streamB) {
+    const wa = streamA.split(' '), wb = streamB.split(' ');
+    let i = 0;
+    while (i < wa.length && i < wb.length && wa[i] === wb[i]) i++;
+    missing = wa.slice(i, i + 20); extra = wb.slice(i, i + 20);
+    problems.push('the rendered text differs — first divergence at word ' + i + ':\n    design: …' +
+      wa.slice(Math.max(0, i - 6), i + 14).join(' ') + '\n    app:    …' +
+      wb.slice(Math.max(0, i - 6), i + 14).join(' '));
+  }
+
+  // Anchor on FULL text, keeping the OUTERMOST match. The walk is pre-order, so a parent is seen
+  // before its children and first-wins yields the outermost element carrying that text — pairing the
+  // design's <button> with the app's <button>, rather than pairing the design's interpolation <span>
+  // against the app's button and reporting the button's own padding and border as differences.
+  const index = (ns) => { const m = new Map(); for (const n of ns) if (n.full && !m.has(n.full)) m.set(n.full, n); return m; };
+  const ia = index(A.nodes), ib = index(B.nodes);
+  const sd = [];
+  for (const [t, na] of ia) {
+    const nb = ib.get(t); if (!nb) continue;
+    for (const p of PROPS) if (na.st[p] !== nb.st[p]) sd.push(`    [${JSON.stringify(t.slice(0, 30))}] ${p}: design=${na.st[p]} app=${nb.st[p]}`);
+    const off = na.box.map((v, i) => Math.abs(v - nb.box[i]));
+    if (Math.max(...off) > 2) sd.push(`    [${JSON.stringify(t.slice(0, 30))}] box: design=${na.box} app=${nb.box}`);
+  }
+  if (sd.length) problems.push(`${sd.length} computed-style / geometry difference(s):\n` + sd.slice(0, 40).join('\n'));
+  return { problems, missing, extra, styleDiffs: sd, theme };
+}
+
+(async () => {
+  const pw = requireOptional('playwright-core');
+  if (!pw) skip('playwright-core is not installed (npm install in workspace/)');
+  // Discovery is lib/find-browser.js's, not a third private candidate list. This file used to hunt
+  // only under /opt/pw-browsers, so on a runner whose browser is /usr/bin/chromium-browser it found
+  // nothing and reported a SKIP — from a machine that had a browser the whole time.
+  const exe = require('./lib/find-browser').findBrowser();
+  if (!exe) skip('no Chrome/Chromium found (set PMOS_CHROME, or install one)');
+  if (!fs.existsSync(path.join(DESIGN, 'prototype-original.html'))) skip(`the design reference is missing at ${DESIGN}`);
+
+  const alive = await new Promise((r) => {
+    const req = http.get(APP_URL, (res) => { res.resume(); r(true); });
+    req.on('error', () => r(false)); req.setTimeout(3000, () => { req.destroy(); r(false); });
+  });
+  if (!alive) skip(`the workspace is not running at ${APP_URL} (node server.js)`);
+
+  fs.mkdirSync(OUT, { recursive: true });
+  const server = await serveReference();
+  const browser = await pw.chromium.launch({ executablePath: exe, args: ['--no-sandbox', '--font-render-hinting=none'] });
+
+  let failed = 0, compared = 0;
+  const report = {};
+  for (const theme of themes) for (const st of states) {
+    const key = `${theme}/${st.id}`;
+    const A = await snap(browser, `http://127.0.0.1:${REF_PORT}/index.html`, theme, `design-${theme}-${st.id}`, st.steps);
+    const B = await snap(browser, `${APP_URL}/?fixture=proto`, theme, `app-${theme}-${st.id}`, st.steps);
+    const d = diff(A, B, theme);
+
+    // COULD THE STATE BE REACHED AT ALL? Asserted before anything is compared, and on BOTH pages: a
+    // step that found no label leaves the page in the previous state, where a clean diff would say
+    // only that two unchanged screens still match. Reported as a failure with the step named.
+    const missedD = A.applied.filter((s) => !s.hit).map((s) => s.label);
+    const missedA = B.applied.filter((s) => !s.hit).map((s) => s.label);
+    if (missedD.length || missedA.length) {
+      d.problems.push(`the state could not be reached — ` +
+        (missedD.length ? `no visible "${missedD.join('", "')}" in the DESIGN; ` : '') +
+        (missedA.length ? `no visible "${missedA.join('", "')}" in the APP; ` : '') +
+        `nothing below this line is a comparison of ${st.id}`);
+    }
+
+    let pixels = null;
+    const pixelmatch = requireOptional('pixelmatch'); const pngjs = requireOptional('pngjs');
+    if (pixelmatch && pngjs) {
+      const pm = pixelmatch.default || pixelmatch;
+      const a = pngjs.PNG.sync.read(fs.readFileSync(A.png)), b = pngjs.PNG.sync.read(fs.readFileSync(B.png));
+      if (a.width === b.width && a.height === b.height) {
+        const out = new pngjs.PNG({ width: a.width, height: a.height });
+        const n = pm(a.data, b.data, out.data, a.width, a.height, { threshold: 0.12 });
+        fs.writeFileSync(path.join(OUT, `diff-${theme}-${st.id}.png`), pngjs.PNG.sync.write(out));
+        pixels = n / (a.width * a.height);
+        if (pixels > 0.005) d.problems.push(`pixel diff ${(pixels * 100).toFixed(2)}% of the viewport — ${path.join(OUT, `diff-${theme}-${st.id}.png`)}`);
+      } else d.problems.push(`screenshot sizes differ: design ${a.width}x${a.height}, app ${b.width}x${b.height}`);
+    }
+
+    report[key] = {
+      steps: st.steps,
+      designNodes: A.nodes.length, appNodes: B.nodes.length,
+      textMissing: d.missing.length, textExtra: d.extra.length,
+      styleDiffs: d.styleDiffs.length,
+      pixelPct: pixels === null ? 'not measured (pixelmatch/pngjs absent)' : +(pixels * 100).toFixed(3),
+      clean: d.problems.length === 0,
+    };
+    compared++;
+    console.log(`\n── ${key} ──`);
+    console.log(JSON.stringify(report[key], null, 1));
+    if (d.problems.length) { failed++; console.log('\n' + d.problems.join('\n\n')); }
+  }
+
+  await browser.close();
+  server.close();
+  fs.writeFileSync(path.join(OUT, 'report.json'), JSON.stringify(report, null, 1));
+  if (!KEEP && !failed) for (const f of fs.readdirSync(OUT)) if (f.endsWith('.png')) fs.unlinkSync(path.join(OUT, f));
+
+  const scope = `${themes.join(' and ')} × ${states.length} state(s) [${states.map((s) => s.id).join(', ')}]`;
+  if (failed) {
+    console.log(`\n❌ design parity FAILED in ${failed}/${compared} comparison(s). Renders kept in ${OUT}.`);
+    process.exit(1);
+  }
+  console.log(`\n✅ design parity — the app is identical to the PM's prototype across ${scope} — ${compared} comparison(s).`);
+  if (states.length === 1 && states[0].id === 'default') {
+    console.log('   (default state only. `--states` walks all ' + STATES.length + ', which is what the PRD asks for.)');
+  }
+})().catch((e) => { console.error('design-parity ERROR:', e.stack); process.exit(2); });

package/workspace/doctor.js

@@ -6,6 +6,8 @@
 'use strict';
 const fs = require('fs');
 const path = require('path');
+const http = require('http');
+const net = require('net');
 const { spawnSync } = require('child_process');
 
 const checks = [];
@@ -116,6 +118,58 @@ function binaryArch(file) {
     console.log('  optional fix: install tmux (macOS `brew install tmux`; Linux `apt install tmux`) for restart-proof sessions.');
   }
 
+  // 6. ports — who is running, and who holds the door. `pmos` points here after a failed start,
+  //    and until now the doctor had nothing to say about the one thing that had just failed.
+  //    Reports every workspace server it can find (the launcher discovers them the same way) and,
+  //    when none is running, whether the port it would use is free and who holds it if not.
+  {
+    const D = require('./lib/server-discovery');
+    const STATE = path.join(__dirname, 'state');
+    const pinned = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : null;
+    const ports = D.candidatePorts({ stateDir: STATE, pinned });
+    const probe = (port) => new Promise((res) => {
+      const req = http.get(`http://127.0.0.1:${port}/api/sessions`, { timeout: 2000 }, (r) => {
+        let b = ''; r.on('data', (c) => (b += c));
+        r.on('end', () => { let j = null; try { j = JSON.parse(b); } catch {} res(D.looksLikeWorkspace(j) ? j : null); });
+      });
+      req.on('error', () => res(null));
+      req.on('timeout', () => { req.destroy(); res(null); });
+    });
+    const free = (port) => new Promise((res) => {
+      const s = net.createServer();
+      s.once('error', () => res(false));
+      s.once('listening', () => s.close(() => res(true)));
+      s.listen(port, '127.0.0.1');
+    });
+    const owner = (port) => {
+      if (process.platform === 'win32') return null;
+      const r = spawnSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-F', 'cn'], { encoding: 'utf8' });
+      const lines = String(r.stdout || '').split('\n');
+      let pid = null, cmd = null;
+      for (const l of lines) {
+        if (l.startsWith('p') && pid === null) pid = Number(l.slice(1)) || null;
+        if (l.startsWith('c') && cmd === null) cmd = l.slice(1).trim() || null;
+      }
+      return pid ? `${cmd || 'unknown'} (pid ${pid})` : null;
+    };
+    const live = [];
+    for (const p of ports) if (await probe(p)) live.push(p);
+    if (live.length === 1) ok(`workspace server running on port ${live[0]} — http://127.0.0.1:${live[0]}`);
+    else if (live.length > 1) {
+      console.log(`• ${live.length} workspace servers are running (ports ${live.join(', ')}).`);
+      console.log('  Each hosts its OWN repos, and a browser tab only sees one of them. `pmos stop` shuts them all down.');
+    } else {
+      const want = pinned || D.DEFAULT_PORT;
+      if (await free(want)) ok(`no server running; port ${want} is free (start it with: pmos)`);
+      else {
+        const who = owner(want) || 'another program';
+        bad(`no workspace server is answering, but port ${want} is held by ${who}`,
+          pinned ? `stop that process, or pin a free port:  PMOS_WS_PORT=7500 pmos`
+            : 'run `pmos` — it starts on the next free port when this one is taken; or stop that process');
+      }
+    }
+  }
+
   const fails = checks.filter((c) => !c).length;
   console.log(`\n${checks.length - fails}/${checks.length} checks passed${fails ? ' — fix the ✗ items above, then re-run npm run doctor' : ' — environment healthy, npm start away'}`);
   process.exit(fails ? 1 : 0);

package/workspace/lib/find-browser.js

@@ -0,0 +1,60 @@
+'use strict';
+/* find-browser — locate a Chrome/Chromium this machine already has.
+ *
+ * WHY THIS EXISTS AS A MODULE. Three suites need a browser (ui-test, pm-shell-test, design-parity)
+ * and each had its own candidate list. Two of them listed only system paths — /usr/bin/chromium and
+ * the two macOS bundles — and so found nothing on a machine whose browser is the Playwright-managed
+ * one under a browsers root. What happens then is the part worth naming: the suite prints
+ * "no Chrome/Chromium — skipped" and exits 0. **A skip is indistinguishable from a pass in a CI
+ * summary**, which is how the browser assertions came to be believed without ever having run. The
+ * explainer for this surface found the same thing from the other end: ui-test.js is the only suite
+ * that measures real geometry, and it does not run in CI.
+ *
+ * So discovery is one function, it knows about the Playwright layout, and the callers report a skip
+ * as its own outcome rather than as success.
+ *
+ * NO DOWNLOAD, EVER. This finds a browser; it never fetches one. PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD is
+ * the environment's own stance and this module agrees with it: a local PM tool must not pull 150 MB
+ * off the network because a test ran.
+ */
+const fs = require('fs');
+const path = require('path');
+
+// A Playwright browsers root holds versioned directories — chromium-1194, chromium_headless_shell-1194
+// — each with the executable at a platform-specific path inside. Enumerated rather than hard-coded,
+// because the version suffix changes with every Playwright bump and a pinned one silently stops
+// matching (which is the same skip-looks-like-pass failure, arriving later).
+function playwrightCandidates() {
+  const roots = [process.env.PLAYWRIGHT_BROWSERS_PATH, '/opt/pw-browsers',
+    path.join(process.env.HOME || '', '.cache', 'ms-playwright')].filter(Boolean);
+  const out = [];
+  for (const root of roots) {
+    let entries = [];
+    try { entries = fs.readdirSync(root); } catch { continue; }
+    for (const dir of entries.sort().reverse()) {          // newest version first
+      if (!/^chromium/.test(dir)) continue;
+      out.push(
+        path.join(root, dir, 'chrome-linux', 'chrome'),
+        path.join(root, dir, 'chrome-linux', 'headless_shell'),
+        path.join(root, dir, 'chrome-mac', 'Chromium.app', 'Contents', 'MacOS', 'Chromium'),
+        path.join(root, dir, 'chrome-win', 'chrome.exe'),
+      );
+    }
+  }
+  return out;
+}
+
+function findBrowser() {
+  const cands = [
+    process.env.PMOS_CHROME,
+    process.env.PMOS_CHROMIUM,
+    ...playwrightCandidates(),
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+  ].filter(Boolean);
+  return cands.find((c) => { try { fs.accessSync(c, fs.constants.X_OK); return true; } catch { return false; } });
+}
+
+module.exports = { findBrowser, playwrightCandidates };