staysfixed 0.1.0

package/src/cli/trace.js

@@ -0,0 +1,73 @@
+/**
+ * `staysfixed trace` — "when did this stop looking right?"
+ */
+
+import { loadProject } from '../core/config.js';
+import { projectStatus } from '../run.js';
+import { traceScreens } from '../marker/trace.js';
+import { printTrace } from '../report/console.js';
+import { say, paint } from '../core/log.js';
+import { resultPicture } from '../core/paths.js';
+import { sha256File } from '../core/hash.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 asked = ctx.args.filter((a) => a.trim() !== '');
+  const changed = asked.length > 0 ? [] : await changedInLastRun(project);
+  const names = asked.length > 0 ? asked : changed;
+
+  if (asked.length === 0) {
+    if (names.length === 0) {
+      say(paint.grey('Nothing is different right now, so this looks at every screen there is a record of.'));
+    } else {
+      say(paint.grey(`Tracing what the last check said had changed: ${names.join(', ')}`));
+    }
+  }
+
+  // When a screen has just gone wrong, the picture worth tracing is the one the
+  // failing run took — not the approved one, which is by definition the old, good
+  // version and would trace as "nothing has changed".
+  const current = await fingerprintsOfLastRun(project, names);
+
+  /** @type {{names?: string[], current?: Record<string,string>}} */
+  const options = { names };
+  if (Object.keys(current).length > 0) options.current = current;
+
+  const report = await traceScreens(project, options);
+
+  printTrace(report);
+  return report.findings.some((f) => f.verdict === 'changed') ? EXIT.failed : EXIT.ok;
+}
+
+/**
+ * @param {import('../types.js').Project} project
+ * @returns {Promise<string[]>}
+ */
+async function changedInLastRun(project) {
+  const status = /** @type {any} */ (await projectStatus(project));
+  /** @type {import('../types.js').PictureResult[]} */
+  const pictures = status?.lastRun?.pictures ?? [];
+  return pictures.filter((p) => p.status === 'changed').map((p) => p.name);
+}
+
+/**
+ * Fingerprints of the pictures this project's last run actually took.
+ * @param {import('../types.js').Project} project
+ * @param {string[]} names
+ * @returns {Promise<Record<string,string>>}
+ */
+async function fingerprintsOfLastRun(project, names) {
+  /** @type {Record<string,string>} */
+  const out = {};
+  for (const name of names) {
+    const hash = await sha256File(resultPicture(project.paths, name).png);
+    if (hash) out[name] = hash;
+  }
+  return out;
+}

package/src/cli/walk.js

@@ -0,0 +1,57 @@
+/**
+ * `staysfixed walk` — the last look before a release.
+ */
+
+import { spawn } from 'node:child_process';
+import { loadProject } from '../core/config.js';
+import { runWalk } from '../run.js';
+import { printWalkReport } from '../report/console.js';
+import { say, warn, paint, shortPath } 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 });
+
+  /** @type {import('../types.js').WalkReport} */
+  const report = await runWalk(project, /** @type {any} */ ({ only: ctx.list('only'), tool: ctx.version }));
+
+  printWalkReport(report);
+
+  const sheet = report.reportFile || report.dir;
+  if (ctx.bool('open')) {
+    if (sheet) openIt(sheet);
+    else warn('There is no contact sheet to open — the walk did not photograph anything.');
+  } else if (sheet) {
+    say(paint.grey(`  Open it with: staysfixed walk --open, or just open ${shortPath(sheet)}`));
+  }
+
+  return report.ok ? EXIT.ok : EXIT.failed;
+}
+
+/**
+ * Hand the file to whatever the operating system uses to open things. It is
+ * detached and ignored on purpose: the viewer outliving this command is the point.
+ * @param {string} file
+ * @returns {void}
+ */
+function openIt(file) {
+  /** @type {[string, string[]]} */
+  const opener =
+    process.platform === 'darwin'
+      ? ['open', [file]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', file]]
+        : ['xdg-open', [file]];
+  const [command, args] = opener;
+  try {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.on('error', () => warn(`Could not open it for you. The file is at ${shortPath(file)}`));
+    child.unref();
+  } catch {
+    warn(`Could not open it for you. The file is at ${shortPath(file)}`);
+  }
+}

package/src/core/config.js

@@ -0,0 +1,226 @@
+/**
+ * Loading, defaulting and validating a project's config.
+ *
+ * Two shapes are accepted on purpose:
+ *  - staysfixed.config.js   — screens can use code (`do(page) { ... }`)
+ *  - staysfixed.config.json — screens use declarative steps only
+ *
+ * The JSON form exists so a Rust, Python or Go project can use this tool
+ * without anybody writing JavaScript.
+ */
+
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { StaysFixedError } from './errors.js';
+import { findConfigFile, pathsFor, rootForConfig, DEFAULT_DIR } from './paths.js';
+
+/** @type {Required<import('../types.js').ViewportConfig>} */
+export const DEFAULT_VIEWPORT = {
+  width: 1440,
+  height: 900,
+  deviceScaleFactor: 2,
+  mobile: false,
+};
+
+/** @type {Required<import('../types.js').SettleConfig>} */
+export const DEFAULT_SETTLE = {
+  frames: 2,
+  intervalMs: 250,
+  timeoutMs: 10_000,
+  maxDriftPixels: 0,
+};
+
+/** @type {Required<Omit<import('../types.js').FreezeConfig,'settle'>> & {settle: Required<import('../types.js').SettleConfig>}} */
+export const DEFAULT_FREEZE = {
+  clock: '2026-01-01T12:00:00.000Z',
+  timezone: 'UTC',
+  locale: 'en-US',
+  motion: true,
+  random: 'seeded',
+  seed: 20260101,
+  fonts: true,
+  network: 'block-external',
+  networkAllow: [],
+  hideScrollbars: true,
+  hideCaret: true,
+  settle: DEFAULT_SETTLE,
+};
+
+/** @type {Required<Omit<import('../types.js').ToleranceConfig,'maxPixels'>>} */
+export const DEFAULT_TOLERANCE = {
+  // 0.05% of pixels. On a 1440x900 @2x picture that is about 1300 pixels — enough
+  // for font hinting noise, nowhere near enough to hide a missing stylesheet.
+  pixels: 0.0005,
+  threshold: 0.12,
+  antialiasing: true,
+};
+
+/** @type {Required<import('../types.js').McpConfig>} */
+export const DEFAULT_MCP = {
+  // An agent must never approve its own work. This default is the whole point.
+  allowApprove: false,
+  allowMark: false,
+};
+
+/**
+ * Find, import and resolve the config.
+ * @param {{cwd?: string, configFile?: string}} [opts]
+ * @returns {Promise<import('../types.js').Project>}
+ */
+export async function loadProject(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const file = opts.configFile ? path.resolve(cwd, opts.configFile) : findConfigFile(cwd);
+  if (!file) {
+    throw new StaysFixedError('No Stays Fixed config found here.', {
+      hint: 'Run `staysfixed init` in your project to make one.',
+    });
+  }
+  const raw = await importConfig(file);
+  const root = rootForConfig(file);
+  const config = resolveConfig(raw, file);
+  const paths = pathsFor(root, file, config.dir);
+  // `guards` is the one folder a project is free to move, so the config wins over the
+  // default layout. Without this the setting silently did nothing and the tool reported
+  // "no guards yet" while staring straight at a folder full of them.
+  paths.guards = path.isAbsolute(config.guards) ? config.guards : path.join(root, config.guards);
+  return { config, paths };
+}
+
+/**
+ * @param {string} file
+ * @returns {Promise<unknown>}
+ */
+async function importConfig(file) {
+  if (file.endsWith('.json')) {
+    try {
+      return JSON.parse(await fsp.readFile(file, 'utf8'));
+    } catch (cause) {
+      throw new StaysFixedError(`Could not read ${path.basename(file)} — it is not valid JSON.`, { cause });
+    }
+  }
+  try {
+    // Cache-bust so a long-lived MCP server picks up config edits without restarting.
+    const url = pathToFileURL(file).href + `?t=${(await fsp.stat(file)).mtimeMs}`;
+    const mod = await import(url);
+    return mod.default ?? mod.config ?? mod;
+  } catch (cause) {
+    throw new StaysFixedError(`Could not load ${path.basename(file)}.`, {
+      hint: cause instanceof Error ? cause.message : undefined,
+      cause,
+    });
+  }
+}
+
+/**
+ * Fill in defaults and reject anything that would fail later in a confusing way.
+ * @param {unknown} raw
+ * @param {string} file
+ * @returns {import('../types.js').ResolvedConfig}
+ */
+export function resolveConfig(raw, file = '(inline)') {
+  if (!raw || typeof raw !== 'object') {
+    throw new StaysFixedError(`${path.basename(file)} did not export a config object.`, {
+      hint: 'It should `export default { app: { ... }, screens: [ ... ] }`.',
+    });
+  }
+  const c = /** @type {import('../types.js').StaysFixedConfig} */ (raw);
+
+  if (!c.app || typeof c.app !== 'object') {
+    throw new StaysFixedError('The config has no `app` — Stays Fixed does not know what to open.', {
+      hint: "Add `app: { kind: 'web', url: 'http://localhost:3000' }` or `app: { kind: 'electron', binary: '...' }`.",
+    });
+  }
+  const kind = c.app.kind;
+  if (kind !== 'web' && kind !== 'electron') {
+    throw new StaysFixedError(`app.kind must be 'web' or 'electron' (found ${JSON.stringify(kind)}).`);
+  }
+  if (kind === 'web' && !c.app.url && !c.app.attach) {
+    throw new StaysFixedError('A web app needs `app.url` — the address to open.');
+  }
+  if (kind === 'electron' && !c.app.binary && !c.app.attach) {
+    throw new StaysFixedError('An Electron app needs `app.binary` — the path to the executable.', {
+      hint: 'On macOS that is inside the bundle: /Applications/Your App.app/Contents/MacOS/Your App',
+    });
+  }
+
+  const screens = (c.screens ?? []).map((s, i) => resolveScreen(s, i));
+  const names = new Set();
+  for (const s of screens) {
+    if (names.has(s.name)) {
+      throw new StaysFixedError(`Two screens are both called "${s.name}". Screen names have to be unique.`);
+    }
+    names.add(s.name);
+  }
+
+  const freeze = {
+    ...DEFAULT_FREEZE,
+    ...(c.freeze ?? {}),
+    settle: { ...DEFAULT_SETTLE, ...(c.freeze?.settle ?? {}) },
+  };
+  if (freeze.clock !== false && typeof freeze.clock === 'string' && Number.isNaN(Date.parse(freeze.clock))) {
+    throw new StaysFixedError(`freeze.clock is not a time I can read: ${JSON.stringify(freeze.clock)}.`, {
+      hint: "Use an ISO timestamp like '2026-01-01T12:00:00.000Z', or false to leave the clock alone.",
+    });
+  }
+  if (freeze.network !== 'replay' && freeze.network !== 'block-external' && freeze.network !== 'live') {
+    throw new StaysFixedError(`freeze.network must be 'replay', 'block-external' or 'live'.`);
+  }
+
+  return {
+    ...c,
+    app: { ...c.app, args: c.app.args ?? [], env: c.app.env ?? {} },
+    viewport: { ...DEFAULT_VIEWPORT, ...(c.viewport ?? {}) },
+    freeze,
+    tolerance: { ...DEFAULT_TOLERANCE, ...(c.tolerance ?? {}) },
+    masks: c.masks ?? [],
+    screens,
+    guards: c.guards ?? path.join(c.dir ?? DEFAULT_DIR, 'guards'),
+    walk: c.walk ?? {},
+    mcp: { ...DEFAULT_MCP, ...(c.mcp ?? {}) },
+    dir: c.dir ?? DEFAULT_DIR,
+    flakeLimit: c.flakeLimit ?? 2,
+    retries: c.retries ?? 1,
+    concurrency: Math.max(1, c.concurrency ?? 1),
+  };
+}
+
+/**
+ * @param {import('../types.js').ScreenConfig} s
+ * @param {number} i
+ * @returns {import('../types.js').ScreenConfig}
+ */
+function resolveScreen(s, i) {
+  if (!s || typeof s !== 'object') {
+    throw new StaysFixedError(`screens[${i}] is not an object.`);
+  }
+  if (!s.name || typeof s.name !== 'string') {
+    throw new StaysFixedError(`screens[${i}] has no name. Every screen needs one, e.g. name: 'sessions-empty'.`);
+  }
+  if (!s.url && !s.steps && !s.do) {
+    throw new StaysFixedError(`Screen "${s.name}" says nothing about how to get there.`, {
+      hint: "Give it a `url`, a list of `steps`, or a `do(page)` function.",
+    });
+  }
+  const steps = s.steps ? [...s.steps] : [];
+  if (s.url) steps.unshift({ goto: s.url });
+  return { ...s, steps };
+}
+
+/**
+ * Merge a screen's overrides on top of the project settings.
+ * @param {import('../types.js').ResolvedConfig} config
+ * @param {import('../types.js').ScreenConfig} screen
+ */
+export function settingsForScreen(config, screen) {
+  return {
+    viewport: { ...config.viewport, ...(screen.viewport ?? {}) },
+    tolerance: { ...config.tolerance, ...(screen.tolerance ?? {}) },
+    freeze: {
+      ...config.freeze,
+      ...(screen.freeze ?? {}),
+      settle: { ...config.freeze.settle, ...(screen.freeze?.settle ?? {}) },
+    },
+    masks: [...config.masks, ...(screen.masks ?? [])],
+  };
+}

package/src/core/errors.js

@@ -0,0 +1,48 @@
+/**
+ * One error type, so the CLI can tell "your setup is wrong" (worth explaining)
+ * apart from "something exploded" (worth a stack trace).
+ */
+
+export class StaysFixedError extends Error {
+  /**
+   * @param {string} message  Written for a human, in plain language.
+   * @param {{hint?: string, cause?: unknown, exitCode?: number}} [opts]
+   */
+  constructor(message, opts = {}) {
+    super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
+    this.name = 'StaysFixedError';
+    /** @type {string|undefined} */
+    this.hint = opts.hint;
+    /** @type {number} */
+    this.exitCode = opts.exitCode ?? 2;
+    /** @type {true} */
+    this.expected = true;
+  }
+}
+
+/**
+ * @param {unknown} e
+ * @returns {e is StaysFixedError}
+ */
+export function isExpected(e) {
+  return Boolean(e && typeof e === 'object' && /** @type {any} */ (e).expected === true);
+}
+
+/**
+ * @param {unknown} e
+ * @returns {string}
+ */
+export function messageOf(e) {
+  if (e instanceof Error) return e.message;
+  return String(e);
+}
+
+/** Exit codes the CLI uses. Stable, so scripts can rely on them. */
+export const EXIT = {
+  /** Everything the tool knows about still works. */
+  ok: 0,
+  /** Something changed or a guard failed — a human needs to look. */
+  failed: 1,
+  /** The tool could not run: bad config, no browser, app would not start. */
+  error: 2,
+};

package/src/core/git.js

@@ -0,0 +1,90 @@
+/**
+ * Just enough git to answer "which commit was this true at?".
+ *
+ * Every call is read-only and every call is allowed to fail — Stays Fixed works
+ * in a folder that is not a git repository, it just cannot trace history there.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+
+/**
+ * @param {string[]} args
+ * @param {string} cwd
+ * @returns {Promise<string|null>}
+ */
+async function git(args, cwd) {
+  try {
+    const { stdout } = await run('git', args, { cwd, timeout: 10_000, maxBuffer: 8 * 1024 * 1024 });
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<import('../types.js').GitInfo>}
+ */
+export async function gitInfo(cwd) {
+  const sha = await git(['rev-parse', 'HEAD'], cwd);
+  const branch = await git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+  const status = await git(['status', '--porcelain'], cwd);
+  const name = await git(['config', 'user.name'], cwd);
+  const email = await git(['config', 'user.email'], cwd);
+  return {
+    sha,
+    shortSha: sha ? sha.slice(0, 7) : null,
+    branch: branch === 'HEAD' ? null : branch,
+    dirty: status !== null && status.length > 0,
+    user: name ? (email ? `${name} <${email}>` : name) : null,
+  };
+}
+
+/**
+ * Commits between two points, newest first. The heart of `staysfixed trace`.
+ * @param {string} cwd
+ * @param {string} from  older sha
+ * @param {string} to    newer sha
+ * @returns {Promise<{sha: string, shortSha: string, subject: string, author: string, date: string}[]>}
+ */
+export async function commitsBetween(cwd, from, to) {
+  const out = await git(['log', '--no-merges', '--format=%H%x1f%h%x1f%s%x1f%an%x1f%ad', '--date=short', `${from}..${to}`], cwd);
+  if (!out) return [];
+  return out
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const [sha, shortSha, subject, author, date] = line.split('\x1f');
+      return { sha, shortSha, subject, author, date };
+    });
+}
+
+/**
+ * Files touched between two commits — narrows "which change did it" further.
+ * @param {string} cwd
+ * @param {string} from
+ * @param {string} to
+ * @returns {Promise<string[]>}
+ */
+export async function filesBetween(cwd, from, to) {
+  const out = await git(['diff', '--name-only', `${from}..${to}`], cwd);
+  return out ? out.split('\n').filter(Boolean) : [];
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} sha
+ */
+export async function commitExists(cwd, sha) {
+  return (await git(['cat-file', '-e', `${sha}^{commit}`], cwd)) !== null;
+}
+
+/**
+ * @param {string} cwd
+ */
+export async function isRepo(cwd) {
+  return (await git(['rev-parse', '--is-inside-work-tree'], cwd)) === 'true';
+}

package/src/core/hash.js

@@ -0,0 +1,32 @@
+/** Hashing. Used to fingerprint pictures so markers can spot a change without storing copies. */
+
+import crypto from 'node:crypto';
+import fsp from 'node:fs/promises';
+
+/**
+ * @param {Buffer|Uint8Array|string} data
+ * @returns {string} hex sha256
+ */
+export function sha256(data) {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * @param {string} file
+ * @returns {Promise<string|null>} hex sha256, or null when the file is not there
+ */
+export async function sha256File(file) {
+  try {
+    return sha256(await fsp.readFile(file));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A short, readable fingerprint for logs. Never used for comparison.
+ * @param {string} hex
+ */
+export function shortHash(hex) {
+  return hex.slice(0, 12);
+}