staysfixed 0.1.0

package/src/drive/find.js

@@ -0,0 +1,331 @@
+/**
+ * Finding the pieces we need on whatever machine this is running on:
+ * a browser to drive, the real executable inside a Mac app bundle, and a free port.
+ *
+ * Everything here is best-effort and never throws unless the caller asked for a
+ * guarantee (`requireChrome`, `resolveElectronBinary`).
+ */
+
+import { existsSync, statSync, readdirSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { createServer, connect as netConnect } from 'node:net';
+import { join, basename, sep } from 'node:path';
+import { homedir } from 'node:os';
+
+import { StaysFixedError } from '../core/errors.js';
+
+/** Env vars people already set for other tools — honour them before guessing. */
+const ENV_KEYS = ['STAYSFIXED_CHROME', 'CHROME_PATH', 'PUPPETEER_EXECUTABLE_PATH'];
+
+/**
+ * @param {string} p
+ * @returns {boolean}
+ */
+function isFileOnDisk(p) {
+  const s = statSync(p, { throwIfNoEntry: false });
+  return Boolean(s && s.isFile());
+}
+
+/**
+ * Bare names get looked up on PATH; anything with a separator is a real path.
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isBareName(name) {
+  return !name.includes('/') && !name.includes(sep);
+}
+
+/**
+ * Every place a browser might be on this machine, best first.
+ * @returns {string[]}
+ */
+export function chromeCandidates() {
+  /** @type {string[]} */
+  const out = [];
+  for (const key of ENV_KEYS) {
+    const value = process.env[key];
+    if (value) out.push(value);
+  }
+
+  const home = homedir();
+
+  if (process.platform === 'darwin') {
+    const apps = [
+      ['Google Chrome.app', 'Google Chrome'],
+      ['Google Chrome Canary.app', 'Google Chrome Canary'],
+      ['Chromium.app', 'Chromium'],
+      ['Brave Browser.app', 'Brave Browser'],
+      ['Microsoft Edge.app', 'Microsoft Edge'],
+    ];
+    for (const root of ['/Applications', join(home, 'Applications')]) {
+      for (const [bundle, exe] of apps) {
+        out.push(join(root, bundle, 'Contents', 'MacOS', exe));
+      }
+    }
+  } else if (process.platform === 'win32') {
+    const roots = [
+      process.env.PROGRAMFILES,
+      process.env['PROGRAMFILES(X86)'],
+      process.env.LOCALAPPDATA,
+    ].filter((/** @type {string|undefined} */ v) => Boolean(v));
+    for (const root of /** @type {string[]} */ (roots)) {
+      out.push(join(root, 'Google', 'Chrome', 'Application', 'chrome.exe'));
+      out.push(join(root, 'Google', 'Chrome SxS', 'Application', 'chrome.exe'));
+      out.push(join(root, 'Chromium', 'Application', 'chrome.exe'));
+      out.push(join(root, 'BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'));
+      out.push(join(root, 'Microsoft', 'Edge', 'Application', 'msedge.exe'));
+    }
+    out.push('chrome.exe', 'msedge.exe');
+  } else {
+    const names = [
+      'google-chrome',
+      'google-chrome-stable',
+      'chromium',
+      'chromium-browser',
+      'microsoft-edge',
+      'microsoft-edge-stable',
+      'brave-browser',
+    ];
+    for (const dir of ['/usr/bin', '/usr/local/bin', '/snap/bin', '/opt/google/chrome']) {
+      for (const name of names) out.push(join(dir, name));
+    }
+    // /opt/google/chrome ships the binary as plain "chrome".
+    out.push('/opt/google/chrome/chrome');
+    out.push(...names);
+  }
+
+  // Keep the order, drop repeats.
+  return [...new Set(out)];
+}
+
+/**
+ * Ask the shell where a bare command lives.
+ * @param {string} name
+ * @returns {string|null}
+ */
+function lookupOnPath(name) {
+  const finder = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    const found = execFileSync(finder, [name], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    });
+    const first = String(found)
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .find((line) => line.length > 0);
+    if (first && isFileOnDisk(first)) return first;
+  } catch {
+    // Not on PATH. That is an answer, not a failure.
+  }
+  return null;
+}
+
+/**
+ * A path the user gave us may point at a Mac app bundle; unwrap it quietly.
+ * @param {string} p
+ * @returns {string}
+ */
+function unwrapIfBundle(p) {
+  if (!p.endsWith('.app')) return p;
+  try {
+    return resolveElectronBinary(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * @param {string} [explicit]  A path from config or the command line.
+ * @returns {string|null}
+ */
+export function findChrome(explicit) {
+  if (explicit) {
+    const unwrapped = unwrapIfBundle(explicit);
+    if (existsSync(unwrapped)) return unwrapped;
+    if (isBareName(explicit)) {
+      const onPath = lookupOnPath(explicit);
+      if (onPath) return onPath;
+    }
+    return null;
+  }
+
+  const candidates = chromeCandidates();
+  for (const candidate of candidates) {
+    if (isBareName(candidate)) continue;
+    const unwrapped = unwrapIfBundle(candidate);
+    if (isFileOnDisk(unwrapped)) return unwrapped;
+  }
+  for (const candidate of candidates) {
+    if (!isBareName(candidate)) continue;
+    const onPath = lookupOnPath(candidate);
+    if (onPath) return onPath;
+  }
+  return null;
+}
+
+/**
+ * @param {string} [explicit]
+ * @returns {string}
+ */
+export function requireChrome(explicit) {
+  const found = findChrome(explicit);
+  if (found) return found;
+
+  if (explicit) {
+    throw new StaysFixedError(`There is no browser at "${explicit}".`, {
+      hint: 'Check the path in your config under app.browser, or remove it and let Stays Fixed find one.',
+    });
+  }
+
+  const looked = chromeCandidates()
+    .filter((c) => !isBareName(c))
+    .slice(0, 6)
+    .map((c) => `  ${c}`)
+    .join('\n');
+
+  throw new StaysFixedError('Stays Fixed could not find Chrome, Chromium, Brave or Edge on this machine.', {
+    hint:
+      'Install Google Chrome, or point Stays Fixed at the browser you have: set app.browser in your config, or the STAYSFIXED_CHROME environment variable.\n' +
+      `It looked in places like:\n${looked}`,
+  });
+}
+
+/**
+ * Turn a Mac `.app` bundle into the executable inside it. Anything else is
+ * handed straight back, so this is safe to call on every platform.
+ * @param {string} p
+ * @returns {string}
+ */
+export function resolveElectronBinary(p) {
+  if (!p) {
+    throw new StaysFixedError('No app was given to open.', {
+      hint: 'Set app.binary in your config to the app you want checked.',
+    });
+  }
+  const stat = statSync(p, { throwIfNoEntry: false });
+  if (!stat) {
+    throw new StaysFixedError(`There is nothing at "${p}".`, {
+      hint: 'Check app.binary in your config — it should point at your built app.',
+    });
+  }
+  if (stat.isFile()) return p;
+
+  const macos = join(p, 'Contents', 'MacOS');
+  const macosStat = statSync(macos, { throwIfNoEntry: false });
+  if (!macosStat || !macosStat.isDirectory()) {
+    throw new StaysFixedError(`"${p}" is a folder, not an app Stays Fixed can open.`, {
+      hint: 'Point app.binary at the built app itself — on a Mac that is the .app bundle, elsewhere the executable file.',
+    });
+  }
+
+  // Info.plist is usually XML; a plain regex beats adding a plist library.
+  // When it is the binary format the regex simply misses and we fall through.
+  const plist = join(p, 'Contents', 'Info.plist');
+  try {
+    const text = readFileSync(plist, 'utf8');
+    const match = text.match(/<key>\s*CFBundleExecutable\s*<\/key>\s*<string>([^<]+)<\/string>/);
+    if (match) {
+      const named = join(macos, match[1].trim());
+      if (isFileOnDisk(named)) return named;
+    }
+  } catch {
+    // No readable Info.plist. Fall back to looking in the folder.
+  }
+
+  const entries = readdirSync(macos).filter((name) => isFileOnDisk(join(macos, name)));
+  if (entries.length === 1) return join(macos, entries[0]);
+
+  const wanted = basename(p).replace(/\.app$/, '');
+  const guess = entries.find((name) => name === wanted);
+  if (guess) return join(macos, guess);
+
+  throw new StaysFixedError(`Stays Fixed could not tell which program to run inside "${p}".`, {
+    hint: `Point app.binary straight at the executable, for example ${join(macos, entries[0] ?? wanted)}.`,
+  });
+}
+
+/**
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+function canBind(port) {
+  return new Promise((resolve) => {
+    const server = createServer();
+    const done = (/** @type {boolean} */ answer) => {
+      server.removeAllListeners();
+      try {
+        server.close();
+      } catch {
+        /* already closed */
+      }
+      resolve(answer);
+    };
+    server.once('error', () => done(false));
+    server.once('listening', () => done(true));
+    try {
+      server.listen(port, '127.0.0.1');
+    } catch {
+      done(false);
+    }
+  });
+}
+
+/**
+ * A port nothing else is using. Asking the operating system for one beats
+ * guessing — two runs at once must never fight over the same number.
+ * @param {number} [preferred]
+ * @returns {Promise<number>}
+ */
+export async function freePort(preferred) {
+  if (typeof preferred === 'number' && Number.isInteger(preferred) && preferred > 0 && preferred < 65_536) {
+    if (await canBind(preferred)) return preferred;
+  }
+  return await new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once('error', (e) => {
+      reject(new StaysFixedError('Stays Fixed could not reserve a port to talk to the app on.', { cause: e }));
+    });
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      const port = address && typeof address === 'object' ? address.port : 0;
+      server.close(() => {
+        if (port) resolve(port);
+        else reject(new StaysFixedError('Stays Fixed could not reserve a port to talk to the app on.'));
+      });
+    });
+  });
+}
+
+/**
+ * @param {number} port
+ * @param {string} [host]
+ * @returns {Promise<boolean>}
+ */
+export function isPortOpen(port, host = '127.0.0.1') {
+  return new Promise((resolve) => {
+    const socket = netConnect({ port, host });
+    let answered = false;
+    const done = (/** @type {boolean} */ answer) => {
+      if (answered) return;
+      answered = true;
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(answer);
+    };
+    socket.setTimeout(1000);
+    socket.once('connect', () => done(true));
+    socket.once('timeout', () => done(false));
+    socket.once('error', () => done(false));
+  });
+}
+
+/**
+ * Pictures are tagged with this because text is drawn differently on every
+ * operating system — a Mac picture will never match a Linux one.
+ * @returns {string}
+ */
+export function platformTag() {
+  return `${process.platform}-${process.arch}`;
+}

package/src/drive/launch.js

@@ -0,0 +1,263 @@
+/**
+ * One door in. Everything that needs an app open — a picture check, a guard, a
+ * walk, the MCP server — comes through here and gets back the same thing back:
+ * a page it can drive and a `close()` that cleans up exactly what we started.
+ */
+
+import { StaysFixedError } from '../core/errors.js';
+import { detail } from '../core/log.js';
+import { fetchVersion, listTargets, connect } from './cdp.js';
+import { createPage } from './page.js';
+import { launchBrowser, startWebApp, delay } from './browser.js';
+import { launchElectron } from './electron.js';
+
+/**
+ * Accept the endpoint however a person naturally writes it: a full address, a
+ * host and port, or just the port.
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizeEndpoint(value) {
+  const v = String(value).trim();
+  if (/^\d+$/.test(v)) return `http://127.0.0.1:${v}`;
+  if (!/^https?:\/\//i.test(v)) return `http://${v}`;
+  return v.replace(/\/+$/, '');
+}
+
+/**
+ * @param {string} endpoint
+ * @param {string|undefined} match
+ * @param {number} deadline epoch ms
+ * @returns {Promise<any>}
+ */
+async function pickTarget(endpoint, match, deadline) {
+  /** @type {any[]} */
+  let pages = [];
+  for (;;) {
+    const targets = /** @type {any[]} */ (await listTargets(endpoint));
+    pages = targets.filter((t) => t && t.type === 'page' && !String(t.url ?? '').startsWith('devtools://'));
+    const hit = match
+      ? pages.find((t) => String(t.title ?? '').includes(match) || String(t.url ?? '').includes(match))
+      : pages[0];
+    if (hit) return hit;
+    if (Date.now() > deadline) break;
+    await delay(250);
+  }
+  const open = pages.map((t) => `  ${String(t.title ?? '(no title)')}  —  ${String(t.url ?? '')}`).join('\n');
+  throw new StaysFixedError(
+    match ? `Nothing open there matches "${match}".` : 'That app is running, but it has no window open to look at.',
+    { hint: open ? `What it does have open:\n${open}` : undefined },
+  );
+}
+
+/**
+ * Attach to something that is already running.
+ *
+ * We did not start this process, so we must NEVER stop it. `close()` here only
+ * hangs up the debugging socket. Killing a person's running app because a check
+ * finished would be unforgivable, and it is a one-line mistake to make.
+ * @param {import('../types.js').AppConfig} app
+ * @returns {Promise<import('../types.js').LaunchedApp>}
+ */
+async function attachToApp(app) {
+  const endpoint = normalizeEndpoint(String(app.attach));
+  const timeoutMs = app.startTimeoutMs ?? 30_000;
+
+  /** @type {any} */
+  let version;
+  try {
+    version = await fetchVersion(endpoint);
+  } catch (cause) {
+    throw new StaysFixedError(`Nothing is answering at ${endpoint}.`, {
+      hint: 'Start the app with a debugging port open, or remove `app.attach` to let Stays Fixed start it.',
+      cause,
+    });
+  }
+  const wsUrl = version?.webSocketDebuggerUrl;
+  if (!wsUrl) {
+    throw new StaysFixedError(`Something answered at ${endpoint}, but it is not an app I can drive.`);
+  }
+
+  const cdp = /** @type {import('../types.js').CdpSession} */ (await connect(wsUrl, { timeoutMs: 15_000 }));
+  try {
+    const target = await pickTarget(endpoint, app.windowMatch, Date.now() + timeoutMs);
+    const targetId = String(target.id ?? target.targetId);
+    detail(`attached to: ${String(target.title ?? '(no title)')} — ${String(target.url ?? '')}`);
+
+    const attached = await cdp.send('Target.attachToTarget', { targetId, flatten: true });
+    const sessionId = String(attached.sessionId);
+    const page = await createPage(
+      cdp,
+      /** @type {any} */ ({ sessionId, targetId, baseUrl: app.url ?? null, timeoutMs }),
+    );
+
+    /** @type {Promise<void>|null} */
+    let closing = null;
+    const close = () => {
+      closing ??= (async () => {
+        try {
+          await cdp.send('Target.detachFromTarget', { sessionId });
+        } catch {
+          // Detaching from something that already went away is fine.
+        }
+        try {
+          await cdp.close();
+        } catch {
+          // Hanging up cannot meaningfully fail.
+        }
+        // Deliberately nothing else. We did not start it; we do not stop it.
+      })();
+      return closing;
+    };
+
+    return { cdp, page, close, endpoint, pid: null, kind: app.kind };
+  } catch (e) {
+    await cdp.close().catch(() => {});
+    throw e;
+  }
+}
+
+/**
+ * Put the window at the size the pictures were approved at. Doing this before
+ * anyone gets the handle means every caller starts from the same geometry.
+ * @param {import('../types.js').LaunchedApp} launched
+ * @param {import('../types.js').ViewportConfig} viewport
+ * @returns {Promise<import('../types.js').LaunchedApp>}
+ */
+async function withViewport(launched, viewport) {
+  try {
+    await launched.page.setViewport(viewport);
+    return launched;
+  } catch (e) {
+    // A half-launched app is a leaked process on somebody's machine.
+    await launched.close().catch(() => {});
+    throw e;
+  }
+}
+
+/**
+ * Open the project's app, whatever kind it is, and hand back a page to drive.
+ * @param {import('../types.js').Project} project
+ * @param {import('./browser.js').LaunchOptions} [opts]
+ * @returns {Promise<import('../types.js').LaunchedApp>}
+ */
+export async function launchApp(project, opts = {}) {
+  const { app, viewport, freeze } = project.config;
+
+  /** @type {import('./browser.js').LaunchOptions} */
+  const launchOpts = {
+    ...opts,
+    viewport: opts.viewport ?? viewport,
+    // The clock's timezone and the locale have to be set on the process before
+    // it starts, so they travel down from the freeze settings with the launch.
+    timezone: opts.timezone ?? freeze.timezone,
+    locale: opts.locale ?? freeze.locale,
+  };
+
+  if (app.attach) {
+    return await withViewport(await attachToApp(app), viewport);
+  }
+
+  if (app.kind === 'electron') {
+    return await withViewport(await launchElectron(app, launchOpts), viewport);
+  }
+
+  /** @type {{stop: () => Promise<void>, pid: number|null}|null} */
+  let server = null;
+  try {
+    // The app has to be answering before the browser goes looking for it.
+    if (app.start) server = await startWebApp(app, launchOpts);
+    const browser = await launchBrowser(app, launchOpts);
+    const startedServer = server;
+
+    /** @type {import('../types.js').LaunchedApp} */
+    const launched = {
+      ...browser,
+      close: async () => {
+        // Browser first: the dev server is what it is looking at, and pulling
+        // the floor out first produces a page of connection errors.
+        await browser.close();
+        if (startedServer) await startedServer.stop();
+      },
+    };
+    return await withViewport(launched, viewport);
+  } catch (e) {
+    if (server) await server.stop().catch(() => {});
+    throw e;
+  }
+}
+
+/**
+ * Settle a desktop app between checks.
+ *
+ * This deliberately does NOT reload the window, and the reason is worth keeping.
+ *
+ * Reloading looked like the obvious way to give a desktop app the isolation a web app
+ * gets for free from its `goto`. It was tried, and it made a guard fail one run in two:
+ * a complex Electron renderer re-initialises on reload and asks its main process for
+ * state that the main process had already sent once and does not send again, so the app
+ * sometimes came back half-wired — a window that looked right with half its controls
+ * missing. A reset that works half the time is worse than no reset, because it turns a
+ * green suite into a coin toss and teaches people to re-run until it passes.
+ *
+ * So a desktop app is left alone. Its screens run in the order they are written, the
+ * pointer is parked, the DOM is allowed to go quiet, and a screen that changes something
+ * the app SAVES puts it back with its own `after` steps. That is honest about what a
+ * desktop app is, and it holds still.
+ *
+ * @param {import('../types.js').LaunchedApp} app
+ * @returns {Promise<void>}
+ */
+export async function resetWindow(app) {
+  try {
+    await app.page.moveMouseAway();
+    await waitForQuietDom(app, { quietMs: 150, timeoutMs: 3000 });
+  } catch {
+    // Nothing here is worth failing a check over.
+  }
+}
+
+/**
+ * Wait until the page stops changing itself.
+ *
+ * Resolves after `quietMs` with no DOM mutation, or gives up at `timeoutMs` — giving up
+ * is not an error, it just means the app never stops fidgeting and the settle loop will
+ * have to carry it.
+ *
+ * @param {import('../types.js').LaunchedApp} app
+ * @param {{quietMs?: number, timeoutMs?: number}} [opts]
+ * @returns {Promise<void>}
+ */
+export async function waitForQuietDom(app, opts = {}) {
+  const quietMs = opts.quietMs ?? 250;
+  const timeoutMs = opts.timeoutMs ?? 5000;
+  const source = `(() => new Promise((resolve) => {
+    var done = false;
+    var timer = null;
+    var finish = function (why) {
+      if (done) return;
+      done = true;
+      try { obs.disconnect(); } catch (e) {}
+      if (timer) clearTimeout(timer);
+      clearTimeout(cap);
+      resolve(why);
+    };
+    var arm = function () {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(function () { finish('quiet'); }, ${quietMs});
+    };
+    var obs = new MutationObserver(arm);
+    try {
+      obs.observe(document.documentElement, { childList: true, subtree: true, attributes: true, characterData: true });
+    } catch (e) {
+      return finish('no-observer');
+    }
+    var cap = setTimeout(function () { finish('gave-up'); }, ${timeoutMs});
+    arm();
+  }))()`;
+  try {
+    await app.page.evaluate(source);
+  } catch {
+    // A context that vanished mid-wait is not worth failing over.
+  }
+}