staysfixed 0.1.0

package/src/cli/approve.js

@@ -0,0 +1,126 @@
+/**
+ * `staysfixed approve` — the human gate.
+ *
+ * This is the one command an agent is not allowed to run for you. So it is also
+ * the one command that must never guess: with no name and no --all it lists what
+ * is waiting and stops. Approving is a person saying "yes, that is what I meant".
+ */
+
+import { loadProject } from '../core/config.js';
+import { approveScreens, projectStatus } from '../run.js';
+import { say, ok, blank, heading, table, paint, mark } from '../core/log.js';
+import { EXIT } from '../core/errors.js';
+
+/**
+ * @param {import('./index.js').CliContext} ctx
+ * @returns {Promise<number>}
+ */
+export async function run(ctx) {
+  const project = await loadProject({ cwd: ctx.cwd, configFile: ctx.configFile });
+  const all = ctx.bool('all');
+  const names = ctx.args.filter((a) => a.trim() !== '');
+
+  if (!all && names.length === 0) return listWhatIsWaiting(project);
+
+  const result = await approveScreens(
+    project,
+    names,
+    /** @type {any} */ ({ all, reason: ctx.str('reason'), tool: ctx.version }),
+  );
+
+  const approved = namesFrom(result, names);
+
+  blank();
+  if (approved.length === 0) {
+    say('Nothing was waiting, so nothing changed.');
+    say(paint.grey('Run `staysfixed check` first — approving only ever accepts a picture the last check took.'));
+    blank();
+    return EXIT.ok;
+  }
+
+  const one = approved.length === 1;
+  ok(`${one ? 'This picture is' : 'These pictures are'} the new normal now:`);
+  for (const name of approved) say(`  ${paint.green(mark.pass)} ${name}`);
+  const reason = ctx.str('reason');
+  if (reason) say(paint.grey(`  reason saved with ${one ? 'it' : 'them'}: ${reason}`));
+  blank();
+  say(paint.grey(`From now on every check measures against ${one ? 'it' : 'them'}. Commit ${one ? 'it' : 'them'} with your code.`));
+  blank();
+  return EXIT.ok;
+}
+
+/**
+ * With nothing named, say what could be approved and how — never approve.
+ * @param {import('../types.js').Project} project
+ * @returns {Promise<number>}
+ */
+async function listWhatIsWaiting(project) {
+  const status = /** @type {any} */ (await projectStatus(project));
+  /** @type {import('../types.js').PictureResult[]} */
+  const pictures = status?.lastRun?.pictures ?? [];
+  const waiting = pictures.filter((p) => p.status === 'changed' || p.status === 'new' || p.status === 'missing');
+
+  if (!status?.lastRun) {
+    blank();
+    say('Nothing has been checked here yet, so there is nothing to approve.');
+    say(`Run ${paint.cyan('staysfixed check')} first.`);
+    blank();
+    return EXIT.ok;
+  }
+  if (waiting.length === 0) {
+    blank();
+    ok('Nothing is waiting for you. Every picture already matches the approved one.');
+    blank();
+    return EXIT.ok;
+  }
+
+  heading('Waiting for you to look at');
+  table(
+    waiting.map((p) => [p.name, paint.grey(whatHappened(p))]),
+    { indent: 2 },
+  );
+  blank();
+  say('Look at each one, then accept the ones that are right:');
+  for (const p of waiting.slice(0, 10)) say(`  ${paint.cyan(`staysfixed approve ${p.name}`)}`);
+  if (waiting.length > 10) say(paint.grey(`  ...and ${waiting.length - 10} more`));
+  if (waiting.length > 1) say(`Or accept every one of them: ${paint.cyan('staysfixed approve --all')}`);
+  blank();
+  say(paint.grey('Nothing was approved just now. Approving is deliberate, on purpose.'));
+  blank();
+  return EXIT.ok;
+}
+
+/**
+ * @param {import('../types.js').PictureResult} p
+ * @returns {string}
+ */
+function whatHappened(p) {
+  if (p.status === 'new') return 'brand new — there is no approved picture yet';
+  if (p.status === 'missing') return 'the approved picture is gone';
+  return 'it looks different from the approved picture';
+}
+
+/**
+ * The runner may hand back names, picture results, or a small report. Read all
+ * three, so this command never has to guess which one it got.
+ *
+ * @param {unknown} result
+ * @param {string[]} asked
+ * @returns {string[]}
+ */
+function namesFrom(result, asked) {
+  /** @type {any} */
+  const value = result;
+  /** @type {unknown[]} */
+  let list = [];
+  if (Array.isArray(value)) list = value;
+  else if (Array.isArray(value?.approved)) list = value.approved;
+  else if (Array.isArray(value?.names)) list = value.names;
+  else if (Array.isArray(value?.pictures)) list = value.pictures;
+  else if (value === undefined || value === null) return asked;
+
+  const names = list
+    .map((item) => (typeof item === 'string' ? item : /** @type {any} */ (item)?.name))
+    .filter((name) => typeof name === 'string' && name !== '');
+  return /** @type {string[]} */ (names);
+}

package/src/cli/check.js

@@ -0,0 +1,73 @@
+/**
+ * `staysfixed check` — the one command people actually run.
+ *
+ * Results are printed the moment each one lands, because a run that goes quiet
+ * for two minutes feels broken. The summary at the end is the part that matters.
+ */
+
+import { loadProject } from '../core/config.js';
+import { runCheck } from '../run.js';
+import { printPictureResult, printGuardResult, printRunSummary } from '../report/console.js';
+import { setLogLevel } from '../core/log.js';
+import { EXIT } from '../core/errors.js';
+
+/**
+ * @param {import('./index.js').CliContext} ctx
+ * @returns {Promise<number>}
+ */
+export async function run(ctx) {
+  const asJson = ctx.bool('json');
+  // With --json the only thing on stdout may be the JSON itself.
+  if (asJson) setLogLevel({ quiet: true, verbose: false });
+
+  const project = await loadProject({ cwd: ctx.cwd, configFile: ctx.configFile });
+
+  const onlyGuards = ctx.bool('guards');
+  const onlyPictures = ctx.bool('pictures');
+
+  /** Printed once, whether it arrived live or only in the summary. */
+  const shown = new Set();
+
+  /** @param {import('../types.js').PictureResult} result */
+  const showPicture = (result) => {
+    const key = `picture:${result.name}`;
+    if (shown.has(key)) return;
+    shown.add(key);
+    if (!asJson) printPictureResult(result);
+  };
+
+  /** @param {import('../types.js').GuardResult} result */
+  const showGuard = (result) => {
+    const key = `guard:${result.name}`;
+    if (shown.has(key)) return;
+    shown.add(key);
+    if (!asJson) printGuardResult(result);
+  };
+
+  const opts = /** @type {any} */ ({
+    only: ctx.list('only'),
+    // These names are the contract runCheck reads. They were `pictures` and `guards`
+    // here once, which typechecked fine and silently did nothing: `--guards` still
+    // photographed all thirteen screens.
+    guardsOnly: onlyGuards && !onlyPictures,
+    picturesOnly: onlyPictures && !onlyGuards,
+    record: ctx.bool('record'),
+    writeReport: ctx.flags.report !== false && !asJson,
+    onPicture: showPicture,
+    onGuard: showGuard,
+    tool: ctx.version,
+  });
+
+  /** @type {import('../types.js').RunSummary} */
+  const summary = await runCheck(project, opts);
+
+  if (asJson) {
+    process.stdout.write(JSON.stringify(summary, null, 2) + '\n');
+  } else {
+    for (const picture of summary.pictures ?? []) showPicture(picture);
+    for (const guard of summary.guards ?? []) showGuard(guard);
+    printRunSummary(summary, project);
+  }
+
+  return summary.ok ? EXIT.ok : EXIT.failed;
+}

package/src/cli/doctor.js

@@ -0,0 +1,379 @@
+/**
+ * `staysfixed doctor` — the "why will this not work" command.
+ *
+ * Every other command is allowed to give up on the first problem. This one is
+ * not: somebody running doctor is already stuck, and being told about one broken
+ * thing at a time is how people give up on a tool. So it collects everything and
+ * never throws.
+ */
+
+import path from 'node:path';
+import fsp from 'node:fs/promises';
+import { loadProject } from '../core/config.js';
+import { findConfigFile, GITIGNORE_LINES } from '../core/paths.js';
+import { findChrome, resolveElectronBinary, platformTag } from '../drive/find.js';
+import { listElectronWindows } from '../drive/electron.js';
+import { loadGuards } from '../guard/load.js';
+import { isRepo } from '../core/git.js';
+import { messageOf, isExpected, EXIT } from '../core/errors.js';
+import { say, ok, warn, fail, blank, heading, paint, mark, shortPath } from '../core/log.js';
+
+/**
+ * @typedef {object} Note
+ * @property {'ok'|'warn'|'bad'} level
+ * @property {string} text
+ * @property {string[]} [more]
+ */
+
+/**
+ * @param {import('./index.js').CliContext} ctx
+ * @returns {Promise<number>}
+ */
+export async function run(ctx) {
+  /** @type {Note[]} */
+  const notes = [];
+  const good = (/** @type {string} */ text, /** @type {string[]} */ more = []) => notes.push({ level: 'ok', text, more });
+  const soso = (/** @type {string} */ text, /** @type {string[]} */ more = []) => notes.push({ level: 'warn', text, more });
+  const bad = (/** @type {string} */ text, /** @type {string[]} */ more = []) => notes.push({ level: 'bad', text, more });
+  const fix = ctx.bool('fix');
+
+  heading('Stays Fixed — checking this project');
+  blank();
+
+  // 1. Settings.
+  const configFile = ctx.configFile ? path.resolve(ctx.cwd, ctx.configFile) : findConfigFile(ctx.cwd);
+  /** @type {import('../types.js').Project|null} */
+  let project = null;
+
+  if (!configFile) {
+    bad('There are no settings here — Stays Fixed does not know what to open.', [
+      'Run `staysfixed init` in this folder and it will write them for you.',
+    ]);
+  } else {
+    good(`Settings found: ${shortPath(configFile)}`);
+    try {
+      project = await loadProject({ cwd: ctx.cwd, configFile });
+      const screens = project.config.screens.length;
+      good(`The settings read fine — ${screens} ${screens === 1 ? 'screen' : 'screens'} named in them.`);
+      if (screens === 0) {
+        soso('No screens are listed, so `staysfixed check` has no pictures to take.', [
+          'Add one under `screens:` in your settings file.',
+        ]);
+      }
+    } catch (error) {
+      bad(messageOf(error), hintsOf(error));
+    }
+  }
+
+  const root = project ? project.paths.root : ctx.cwd;
+
+  // 2. The app itself.
+  if (project) {
+    const app = project.config.app;
+    if (app.attach) {
+      await checkAttached(app.attach, good, soso);
+    } else if (app.kind === 'web') {
+      await checkWebApp(app, good, soso, bad);
+    } else {
+      checkElectronApp(app, good, bad);
+    }
+
+    // 3. A browser to drive it with. Electron brings its own.
+    if (app.kind === 'web' && !app.attach) {
+      const browser = findChrome(app.browser ?? process.env.STAYSFIXED_CHROME);
+      if (browser) good(`Browser it will use: ${browser}`);
+      else
+        bad('No Chrome, Chromium, Brave or Edge could be found on this machine.', [
+          'Install Google Chrome, or point Stays Fixed at the one you have:',
+          "set `app: { browser: '/path/to/chrome' }` in your settings, or the STAYSFIXED_CHROME environment variable.",
+        ]);
+    }
+  }
+
+  // 4. The folders, and 5. the pictures inside them.
+  if (project) {
+    const wanted = [
+      ['the state folder', project.paths.dir],
+      ['approved pictures', project.paths.approved],
+      ['guards', project.paths.guards],
+      ['markers', project.paths.markers],
+    ];
+    /** @type {string[]} */
+    const missing = [];
+    for (const [label, dir] of wanted) {
+      if (!(await isDir(dir))) missing.push(`${label} (${shortPath(dir)})`);
+    }
+    if (missing.length === 0) {
+      good('All the folders it needs are there.');
+    } else if (fix) {
+      for (const [, dir] of wanted) await fsp.mkdir(dir, { recursive: true }).catch(() => {});
+      good(`Made the folders that were missing: ${missing.length}.`);
+    } else {
+      soso(`${missing.length} ${missing.length === 1 ? 'folder is' : 'folders are'} missing.`, [
+        ...missing.map((m) => `${mark.info} ${m}`),
+        'Run `staysfixed doctor --fix` to make them.',
+      ]);
+    }
+
+    const pictures = await approvedPictures(project.paths.approved);
+    if (pictures.length === 0) {
+      soso('There are no approved pictures yet, so there is nothing to compare against.', [
+        'Run `staysfixed check`, look at what it took, then `staysfixed approve --all`.',
+      ]);
+    } else {
+      good(`${pictures.length} approved ${pictures.length === 1 ? 'picture' : 'pictures'} on disk.`);
+    }
+
+    // 9. Text is drawn differently on every operating system, so a picture taken
+    // on a Mac will never match one taken on Linux. Worth saying out loud.
+    const here = platformTag();
+    const elsewhere = [...new Set(pictures.map((p) => p.platform).filter((p) => typeof p === 'string' && p !== here))];
+    if (elsewhere.length > 0) {
+      soso(`Some approved pictures were taken on a different system (${elsewhere.join(', ')}); this one is ${here}.`, [
+        'Text is drawn differently on every operating system, so those will look changed here even when nothing is wrong.',
+        'Approve them again on this machine, or take the pictures on one machine only — usually CI.',
+      ]);
+    } else if (pictures.length > 0) {
+      good(`Every approved picture was taken on this kind of machine (${here}).`);
+    }
+  }
+
+  // 6. Guards.
+  if (project) {
+    try {
+      const guards = await loadGuards(project);
+      if (guards.length === 0) {
+        soso('No guards yet.', [
+          'A guard is one check per bug you have already fixed, named in plain English.',
+          'The next time something comes back, write one — that is the whole point of them.',
+        ]);
+      } else {
+        good(`${guards.length} ${guards.length === 1 ? 'guard loads' : 'guards load'}, and every name reads like a sentence.`);
+      }
+    } catch (error) {
+      bad('The guards could not be loaded.', [...messageOf(error).split('\n'), ...hintsOf(error)]);
+    }
+  }
+
+  // 7. .gitignore.
+  await checkGitignore(root, fix, good, soso);
+
+  // 8. git.
+  if (await isRepo(root)) good('This is a git repository, so a regression can be traced to a commit.');
+  else
+    soso('This folder is not a git repository.', [
+      'Everything still works, but `staysfixed trace` cannot tell you which commit changed something.',
+    ]);
+
+  // A last word about the rule that matters most.
+  if (project?.config.mcp.allowApprove) {
+    soso('Your settings let an agent approve its own pictures (`mcp.allowApprove: true`).', [
+      'That gives away the only thing this tool really guarantees. Turn it off unless you meant it.',
+    ]);
+  }
+
+  return report(notes);
+}
+
+/**
+ * The advice an expected error carries, as lines. Anything else has none.
+ * @param {unknown} error
+ * @returns {string[]}
+ */
+function hintsOf(error) {
+  if (!isExpected(error) || !error.hint) return [];
+  return error.hint.split('\n');
+}
+
+/**
+ * @param {Note[]} notes
+ * @returns {number}
+ */
+function report(notes) {
+  for (const note of notes) {
+    if (note.level === 'ok') ok(note.text);
+    else if (note.level === 'warn') warn(note.text);
+    else fail(note.text);
+    for (const line of note.more ?? []) say(paint.grey(`    ${line}`));
+  }
+
+  const bad = notes.filter((n) => n.level === 'bad').length;
+  const warns = notes.filter((n) => n.level === 'warn').length;
+
+  blank();
+  if (bad > 0) {
+    fail(`${bad} ${bad === 1 ? 'thing has' : 'things have'} to be fixed before Stays Fixed can run here.`);
+    blank();
+    return EXIT.failed;
+  }
+  if (warns > 0) {
+    warn(`It will run. ${warns} ${warns === 1 ? 'thing is' : 'things are'} worth a look.`);
+    blank();
+    return EXIT.ok;
+  }
+  ok('Everything it needs is in place.');
+  blank();
+  return EXIT.ok;
+}
+
+/**
+ * @param {import('../types.js').AppConfig} app
+ * @param {(t: string, more?: string[]) => void} good
+ * @param {(t: string, more?: string[]) => void} soso
+ * @param {(t: string, more?: string[]) => void} bad
+ */
+async function checkWebApp(app, good, soso, bad) {
+  const url = app.url;
+  if (!url) {
+    bad('The settings do not say which address to open.');
+    return;
+  }
+  const answered = await answers(url);
+  if (answered.ok) {
+    good(`Your app answered at ${url}.`);
+    return;
+  }
+  if (app.start) {
+    soso(`Nothing is answering at ${url} right now.`, [
+      `That is fine — Stays Fixed will start it itself with: ${app.start}`,
+      `It could not reach it just now because: ${answered.why}`,
+    ]);
+    return;
+  }
+  bad(`Nothing is answering at ${url}.`, [
+    `Tried it and got: ${answered.why}`,
+    'Start your app first, or add `app: { start: "npm run dev" }` to your settings so Stays Fixed starts it for you.',
+  ]);
+}
+
+/**
+ * @param {import('../types.js').AppConfig} app
+ * @param {(t: string, more?: string[]) => void} good
+ * @param {(t: string, more?: string[]) => void} bad
+ */
+function checkElectronApp(app, good, bad) {
+  try {
+    const binary = resolveElectronBinary(app.binary ?? '');
+    good(`The app it will open: ${binary}`);
+  } catch (error) {
+    bad(messageOf(error), hintsOf(error));
+  }
+}
+
+/**
+ * @param {string} endpoint
+ * @param {(t: string, more?: string[]) => void} good
+ * @param {(t: string, more?: string[]) => void} soso
+ */
+async function checkAttached(endpoint, good, soso) {
+  try {
+    const windows = await listElectronWindows(endpoint);
+    const pages = windows.filter((w) => w.type === 'page');
+    good(`Attached to what is already running at ${endpoint} — ${pages.length} ${pages.length === 1 ? 'window' : 'windows'} open.`);
+    for (const window of pages.slice(0, 6)) {
+      say(paint.grey(`    ${window.title || '(no title)'} ${paint.grey(window.url)}`));
+    }
+    if (pages.length > 1) {
+      say(paint.grey('    More than one window is open. Put a word from the right title in `app.windowMatch`.'));
+    }
+  } catch (error) {
+    soso(`Nothing is listening at ${endpoint} right now.`, [
+      `Tried it and got: ${messageOf(error)}`,
+      'Start the app with remote debugging on before running a check, or drop `app.attach` and let Stays Fixed launch it.',
+    ]);
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {boolean} fix
+ * @param {(t: string, more?: string[]) => void} good
+ * @param {(t: string, more?: string[]) => void} soso
+ */
+async function checkGitignore(root, fix, good, soso) {
+  const file = path.join(root, '.gitignore');
+  let current = '';
+  try {
+    current = await fsp.readFile(file, 'utf8');
+  } catch {
+    current = '';
+  }
+  const lines = new Set(current.split('\n').map((l) => l.trim()));
+  const missing = GITIGNORE_LINES.filter((line) => !line.startsWith('#') && !lines.has(line.trim()));
+
+  if (missing.length === 0) {
+    good('Your .gitignore already keeps the throwaway files out of git.');
+    return;
+  }
+  if (fix) {
+    const prefix = current === '' || current.endsWith('\n') ? '' : '\n';
+    await fsp.writeFile(file, `${current}${prefix}\n${GITIGNORE_LINES.join('\n')}\n`);
+    good(`Added ${missing.length} ${missing.length === 1 ? 'line' : 'lines'} to .gitignore.`);
+    return;
+  }
+  soso('Your .gitignore is missing the lines that keep throwaway files out of git.', [
+    ...missing.map((line) => `${mark.info} ${line}`),
+    'Run `staysfixed doctor --fix` to add them.',
+  ]);
+}
+
+/**
+ * @param {string} url
+ * @returns {Promise<{ok: boolean, why: string}>}
+ */
+async function answers(url) {
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(4000), redirect: 'manual' });
+    return { ok: response.status < 500, why: `${response.status}` };
+  } catch (error) {
+    return { ok: false, why: messageOf(error) };
+  }
+}
+
+/**
+ * @param {string} dir
+ * @returns {Promise<boolean>}
+ */
+async function isDir(dir) {
+  try {
+    return (await fsp.stat(dir)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The metadata next to every approved picture, so doctor can spot pictures that
+ * were taken somewhere else.
+ * @param {string} dir
+ * @returns {Promise<import('../types.js').PictureMeta[]>}
+ */
+async function approvedPictures(dir) {
+  /** @type {import('../types.js').PictureMeta[]} */
+  const out = [];
+  /** @type {string[]} */
+  let names = [];
+  try {
+    names = await fsp.readdir(dir);
+  } catch {
+    return out;
+  }
+  for (const name of names) {
+    if (!name.endsWith('.png')) continue;
+    const meta = await readMeta(path.join(dir, name.replace(/\.png$/, '.json')));
+    out.push(meta ?? /** @type {any} */ ({ name: name.replace(/\.png$/, '') }));
+  }
+  return out;
+}
+
+/**
+ * @param {string} file
+ * @returns {Promise<import('../types.js').PictureMeta|null>}
+ */
+async function readMeta(file) {
+  try {
+    return JSON.parse(await fsp.readFile(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}

package/src/cli/flake.js

@@ -0,0 +1,61 @@
+/**
+ * `staysfixed flake` — the register of checks that cannot make up their mind.
+ *
+ * A check that cries wolf gets ignored, and then the real one gets ignored too.
+ * So this command exists to make wobbling visible rather than tolerable.
+ */
+
+import { loadProject } from '../core/config.js';
+import { loadHistory, saveHistory, clearFlakes, condemned, blindWithoutGit } from '../core/history.js';
+import { printFlakes } from '../report/console.js';
+import { say, ok, warn, blank, paint } from '../core/log.js';
+import { gitInfo } from '../core/git.js';
+import { EXIT } from '../core/errors.js';
+
+/**
+ * @param {import('./index.js').CliContext} ctx
+ * @returns {Promise<number>}
+ */
+export async function run(ctx) {
+  const project = await loadProject({ cwd: ctx.cwd, configFile: ctx.configFile });
+  const history = await loadHistory(project.paths.historyFile);
+
+  const forgive = ctx.str('clear');
+  if (forgive) {
+    const known = Object.values(history).some((entry) => entry.name === forgive);
+    if (!known) {
+      blank();
+      warn(`No check called "${forgive}" has ever wobbled, so there is nothing to forgive.`);
+      blank();
+      return EXIT.failed;
+    }
+    await saveHistory(project.paths.historyFile, clearFlakes(history, forgive));
+    blank();
+    ok(`"${forgive}" starts again with a clean record.`);
+    say(paint.grey('If it wobbles again, it is not fixed.'));
+    blank();
+    return EXIT.ok;
+  }
+
+  if (ctx.bool('json')) {
+    process.stdout.write(JSON.stringify(history, null, 2) + '\n');
+    return EXIT.ok;
+  }
+
+  printFlakes(history, project.config.flakeLimit);
+
+  // A register that looks clean for the wrong reason is worse than one that admits what
+  // it cannot see. Comparing a check's verdict between two runs only means something if
+  // the code stood still in between, and only git can say that.
+  if (blindWithoutGit(await gitInfo(project.paths.root))) {
+    say(
+      paint.grey(
+        'Note: this folder has no commit to pin results to, so a wobble is only counted when a\n' +
+          'check needs a second try inside one run. Commit your work and the register sees more.',
+      ),
+    );
+    blank();
+  }
+
+  return condemned(history).length > 0 ? EXIT.failed : EXIT.ok;
+}