staysfixed 0.4.0 → 0.6.1

package/src/v2/watch/focus.js

@@ -0,0 +1,215 @@
+/**
+ * Letting you watch, without taking your screen.
+ *
+ * The owner asked for something more precise than "run it invisibly", and he was right
+ * to. He wants to SEE it work — the app opening, the panel beside it, each check ticking
+ * green — because watching it is most of how you come to trust it. What he does not want
+ * is what it did to him tonight:
+ *
+ *   "if i click something and bring [my app] on the first layer of the screen and i am
+ *    working on something, after my click it will not keep bringing it up. it will just
+ *    keep it back side and keep working."
+ *
+ * So the rule is not "stay hidden". It is: **come up once, then never come up again.**
+ *
+ * That distinction is the whole of this file. An app the tool opens is allowed to appear —
+ * it should, the first time, so a person can see what is happening. From the moment the
+ * person picks something else, whatever the tool launched loses the argument for good.
+ *
+ * ## Why a guard rather than a flag
+ *
+ * There is no flag for this. An Electron app calls `app.focus()` and `win.show()` from its
+ * own main process during startup, when a window opens, when a dialog appears; a simulator
+ * activates when it boots; a browser activates when a new window is created. None of that
+ * goes through us, so none of it can be forbidden at launch time. The only thing that
+ * actually works is to watch who is in front and put the person's app back when something
+ * of ours pushes in front of it.
+ *
+ * ## Why polling is the right answer here, unusually
+ *
+ * The standing rule in this codebase is events over polling. macOS does publish an
+ * activation notification, but reading it needs a process inside the window server session
+ * with an event loop — a small native helper or a persistent AppleScript, both of which are
+ * a thing to install and a thing to leave running on his machine. A twelve-line
+ * `osascript` every 400ms costs about a millisecond of CPU and installs nothing. The rule
+ * exists to stop wasteful polling; this is the case it does not cover.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { detail } from '../../core/log.js';
+
+const run = promisify(execFile);
+
+/** How often to look. Fast enough that a stolen screen is given back before it is annoying. */
+const LOOK_EVERY_MS = 400;
+
+/**
+ * How long to leave the tool's window alone at the start.
+ *
+ * It has just been opened deliberately and a person is probably looking at it. Snatching
+ * focus away in the same instant would be its own kind of rude, and would also fight the
+ * launch itself while the app is still deciding which of its windows is in front.
+ */
+const GRACE_MS = 2500;
+
+/** @typedef {{name: string}} Frontmost */
+
+/**
+ * Who is in front right now, by application name.
+ *
+ * Returns null rather than throwing on any failure — no window server, no Apple Events
+ * permission, a headless machine, a locked screen. Every one of those means "there is no
+ * screen to take", which is not an error and must never fail a check.
+ *
+ * @returns {Promise<string|null>}
+ */
+export async function frontmostApp() {
+  if (process.platform !== 'darwin') return null;
+  try {
+    const { stdout } = await run(
+      'osascript',
+      ['-e', 'tell application "System Events" to get name of first application process whose frontmost is true'],
+      { timeout: 3000 },
+    );
+    const name = stdout.trim();
+    return name.length > 0 ? name : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Bring one application back to the front.
+ *
+ * @param {string} name
+ * @returns {Promise<boolean>} whether it worked
+ */
+export async function bringForward(name) {
+  if (process.platform !== 'darwin' || !name) return false;
+  try {
+    await run(
+      'osascript',
+      [
+        '-e',
+        `tell application "System Events" to set frontmost of first application process whose name is ${JSON.stringify(name)} to true`,
+      ],
+      { timeout: 3000 },
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @typedef {object} ScreenGuard
+ * @property {(name: string) => void} claim      Tell the guard an application belongs to the tool.
+ * @property {() => Promise<void>} release       Stop guarding. Always safe to call twice.
+ * @property {() => GuardReport} report          What it did, for the run summary.
+ */
+
+/**
+ * @typedef {object} GuardReport
+ * @property {number} handedBack   How many times the screen was taken and given back.
+ * @property {string|null} yours   The application the guard believes is yours.
+ * @property {string[]} ours       Everything the tool opened.
+ * @property {boolean} watching    False when there is no screen to guard.
+ */
+
+/**
+ * Watch who is in front, and give the screen back when something of ours takes it.
+ *
+ * The bookkeeping is deliberately simple, because a clever version of this would guess
+ * wrong and fight the person for their own screen:
+ *
+ *  - Anything the tool launches is `ours`, named as the tool launches it.
+ *  - Anything else that is frontmost is *yours*, and the guard remembers the last one. That
+ *    is how it learns what to put back — by watching what you actually chose, never by
+ *    being told.
+ *  - When one of ours is in front and you have chosen something since, yours goes back.
+ *  - When one of ours is in front and you have chosen nothing yet, it is left alone. That
+ *    first appearance is the point: it is how you see what is happening.
+ *
+ * @param {{claims?: string[], everyMs?: number, graceMs?: number}} [opts]
+ * @returns {ScreenGuard}
+ */
+export function guardTheScreen(opts = {}) {
+  const everyMs = opts.everyMs ?? LOOK_EVERY_MS;
+  const graceMs = opts.graceMs ?? GRACE_MS;
+
+  /** @type {Set<string>} everything the tool opened */
+  const ours = new Set(opts.claims ?? []);
+  /** @type {string|null} the last application the person chose for themselves */
+  let yours = null;
+  let handedBack = 0;
+  let stopped = process.platform !== 'darwin';
+  /** @type {ReturnType<typeof setTimeout>|null} */
+  let timer = null;
+  const startedAt = Date.now();
+
+  /** @param {string} name */
+  const claim = (name) => {
+    if (name) ours.add(name);
+  };
+
+  const isOurs = (/** @type {string} */ name) => {
+    for (const one of ours) {
+      // A launched application is often reported under a slightly different name than the
+      // path it was started from — "Terminal Deck" for a binary called "Terminal Deck", but
+      // "Electron" for a development build, and "Simulator" for a simulator boot. Matching
+      // loosely in both directions is what makes this work without a table of special cases.
+      if (name === one || name.includes(one) || one.includes(name)) return true;
+    }
+    return false;
+  };
+
+  const look = async () => {
+    if (stopped) return;
+    const front = await frontmostApp();
+    if (front) {
+      if (!isOurs(front)) {
+        // The person chose this. It is now what "yours" means.
+        yours = front;
+      } else if (yours && Date.now() - startedAt > graceMs) {
+        // Something of ours is in front, and there is somewhere to put you back.
+        const ok = await bringForward(yours);
+        if (ok) {
+          handedBack += 1;
+          detail(`the screen was taken by ${front}; gave it back to ${yours}`);
+        }
+      }
+    }
+    if (!stopped) timer = setTimeout(look, everyMs);
+  };
+
+  if (!stopped) timer = setTimeout(look, everyMs);
+
+  return {
+    claim,
+    async release() {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      timer = null;
+    },
+    report() {
+      return { handedBack, yours, ours: [...ours], watching: !stopped };
+    },
+  };
+}
+
+/**
+ * One sentence for the summary, or nothing when there is nothing worth saying.
+ *
+ * A person who was not interrupted should not be told about the machinery that did not
+ * interrupt them. This only speaks when it actually did something.
+ *
+ * @param {GuardReport} report
+ * @returns {string|null}
+ */
+export function describeGuard(report) {
+  if (!report || report.handedBack === 0) return null;
+  const times = report.handedBack === 1 ? 'once' : `${report.handedBack} times`;
+  const back = report.yours ? ` to ${report.yours}` : '';
+  return `Something the check opened came to the front ${times} and the screen was handed straight back${back}.`;
+}

package/src/v2/watch/index.js

@@ -0,0 +1,382 @@
+/**
+ * The watch window, from the check's point of view.
+ *
+ * A check describes itself into an event stream and carries on. This subscribes to that
+ * stream, opens a window beside whatever is being checked, and forwards everything to it. It
+ * has no other effect on the check: it takes nothing away from it, it holds nothing up, and
+ * when the window cannot open the check does not notice.
+ *
+ * THREE THINGS HERE ARE NOT OBVIOUS, and all three are the owner's one requirement said in
+ * different places:
+ *
+ *   "That window should come up... But once we minimise it, it should keep working headless
+ *    in the background. Not invisible. It should not keep bringing itself to the front."
+ *
+ * ONE. The window is opened WITHOUT being waited for. `attachWatcher` hands back a watcher
+ * immediately and the browser starts behind it, so the check begins in the same millisecond it
+ * would have begun with no window at all. That is safe only because the event stream hands a
+ * late listener everything that already happened, in order — so a window that took two seconds
+ * to open still draws the two seconds it missed.
+ *
+ * TWO. The ENGINE works everything out and the PANEL only draws. Every sentence and every
+ * number a person reads is made here, on this side, by `events.js`, and pushed over finished.
+ * Nothing in the page is computed on a clock of its own. That is what makes minimising the
+ * window harmless: a browser slows a hidden page right down, and a page that is only drawing
+ * what it was handed loses nothing by being slow. It catches up the moment it is looked at.
+ *
+ * THREE. Nothing here ever waits on the window. `push` hands back nothing, so there is no
+ * promise to await by accident; every send has a hard timeout on it in `window.js`; and
+ * stopping the watcher never blocks on a window that has stopped answering.
+ *
+ * The division of labour across these four files: `events.js` decides WHAT to say, `panel.js`
+ * decides how it LOOKS, `window.js` owns the window it is said in, and this file is the seam
+ * between all of that and a check.
+ */
+
+import { detail } from '../../core/log.js';
+import { messageOf } from '../../core/errors.js';
+import { openPanel } from './window.js';
+import { attachPanel, panelPlan } from './events.js';
+
+/** @typedef {import('../types.js').Journey} Journey */
+/** @typedef {import('./events.js').PanelPlanShape} PanelPlan */
+/** @typedef {import('./events.js').PanelReference} PanelReference */
+/** @typedef {import('./window.js').Panel} Panel */
+/** @typedef {import('./window.js').BesideThis} BesideThis */
+/** @typedef {import('./window.js').PanelHealth} PanelHealth */
+
+/** Panel width when nobody says otherwise. */
+const DEFAULT_WIDTH = 480;
+
+/** How long `snapTo` will wait for a window that is still opening before shrugging. */
+const SNAP_WAIT_MS = 6000;
+
+/**
+ * How long stopping will wait for a window that is STILL opening.
+ *
+ * Short, and it has to be. A check that finishes in two seconds on a machine where a browser
+ * takes twenty to start would otherwise sit there at the end, done, with nothing to say,
+ * waiting on a window nobody is going to read. So stopping calls the opening off and gives it
+ * a moment to tidy up; a window that arrives after that closes itself, because the opening
+ * sequence already knows it was stopped.
+ */
+const STOP_WAIT_MS = 1500;
+
+/**
+ * Anything with the two halves of an event stream on it.
+ *
+ * Written structurally rather than as the engine's own type so this can be handed a real
+ * check's stream, a stub in a test, or whatever the stream grows into next, without any of
+ * them having to import each other.
+ *
+ * @typedef {object} Watchable
+ * @property {(listener: (event: any) => void) => () => void} on
+ */
+
+/**
+ * What the panel is told to do.
+ *
+ * `snap` lives here rather than in the shared options so that whether the two windows are
+ * pushed together stays a decision of the watch code.
+ *
+ * @typedef {import('../../types.js').WatchOptions & {snap?: boolean}} PanelOptions
+ */
+
+/**
+ * @typedef {object} AttachOptions
+ * @property {string} [product]       One repository can build five. This names the one being checked.
+ * @property {string} [project]       The folder it is being run in.
+ * @property {Journey[]} [journeys]   Every journey about to be walked, in order.
+ * @property {PanelReference} [reference]  What it is being compared against, already in words.
+ * @property {PanelPlan} [plan]       The finished plan, when a caller has built one itself.
+ * @property {PanelOptions} [watch]
+ * @property {string} [dir]           Where to remember the window position. The project's own folder.
+ * @property {{width: number, height: number}} [appViewport]
+ */
+
+/**
+ * A check's handle on its window.
+ *
+ * `snapTo` is how the check introduces the thing being observed once it is up. It is safe to
+ * call when there is no panel, when the panel cannot move windows, when the panel is still
+ * opening, and when the person asked for no snapping: in every one of those cases it does
+ * nothing and costs nothing.
+ *
+ * `health` is there so the claim this whole file makes — that the window never held the check
+ * up — has a number behind it rather than being taken on trust.
+ *
+ * @typedef {object} Watcher
+ * @property {() => Promise<void>} stop
+ * @property {(beside: BesideThis) => Promise<void>} snapTo
+ * @property {() => PanelHealth|null} health
+ * @property {() => boolean} open   Is there a window right now.
+ */
+
+/**
+ * Wait for something, but not for long, and never mind if it does not arrive.
+ *
+ * The whole of "stopping never blocks on a window", in five lines. The promise itself carries
+ * on — nothing here can cancel it, and it does not need to, because whatever it eventually
+ * produces knows it was stopped and puts itself away.
+ *
+ * @template T
+ * @param {Promise<T>} work
+ * @param {number} ms
+ * @returns {Promise<T|null>}
+ */
+function soon(work, ms) {
+  /** @type {Promise<null>} */
+  const giveUp = new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(null), ms);
+    // Never hold the program open waiting for a window.
+    if (typeof timer.unref === 'function') timer.unref();
+  });
+  return Promise.race([work.catch(() => null), giveUp]);
+}
+
+/**
+ * A watcher that is not watching anything.
+ *
+ * Handed back whenever there is no window — switched off, no browser, a page that would not
+ * build — so every caller has the same shape to stop, whatever happened.
+ *
+ * @returns {Watcher}
+ */
+function noWatcher() {
+  return { stop: async () => {}, snapTo: async () => {}, health: () => null, open: () => false };
+}
+
+/**
+ * The opening plan: what the window draws before anything has happened.
+ *
+ * A window that opens empty and fills up looks broken for the first few seconds, so it is
+ * given the product, the surfaces in play and every journey it is about to walk, in order,
+ * from the moment it appears.
+ *
+ * @param {AttachOptions} opts
+ * @returns {PanelPlan}
+ */
+function planFor(opts) {
+  if (opts.plan) return opts.plan;
+  return panelPlan({
+    ...(opts.product ? { product: opts.product } : {}),
+    ...(opts.project ? { project: opts.project } : {}),
+    ...(opts.journeys ? { journeys: opts.journeys } : {}),
+    ...(opts.reference ? { reference: opts.reference } : {}),
+  });
+}
+
+/**
+ * Open a window and point it at a check.
+ *
+ * Never throws, and never waits for the window. Every way this can go wrong ends the same way:
+ * a line of detail, a watcher that does nothing, and a check that carries on at full speed.
+ *
+ * @param {Watchable} events
+ * @param {AttachOptions} [opts]
+ * @returns {Promise<Watcher>}
+ */
+export async function attachWatcher(events, opts = {}) {
+  const watch = opts.watch ?? {};
+  if (watch.enabled === false) return noWatcher();
+  if (!events || typeof events.on !== 'function') return noWatcher();
+
+  const plan = { ...planFor(opts), theme: watch.theme ?? 'dark' };
+
+  /** @type {Panel|null} */
+  let panel = null;
+  /** @type {(() => void)|null} */
+  let unsubscribe = null;
+  let stopped = false;
+  // How stopping reaches a window that has not finished opening. Every wait inside `openPanel`
+  // watches this, so calling it off ends them all at once instead of one timeout at a time.
+  const givingUp = new AbortController();
+
+  /**
+   * Start the window and, when it is up, start feeding it.
+   *
+   * Nothing awaits this. Everything that can go wrong inside it ends with no panel and a check
+   * that never knew there was going to be one.
+   *
+   * @type {Promise<Panel|null>}
+   */
+  const opening = openPanel({
+    plan,
+    watch,
+    signal: givingUp.signal,
+    ...(opts.dir ? { dir: opts.dir } : {}),
+    ...(opts.appViewport ? { appViewport: opts.appViewport } : {}),
+  })
+    .then((open) => {
+      if (!open) return null;
+      if (stopped) {
+        // Stopped while it was still opening. Close it rather than leave a window nobody asked
+        // for standing on somebody's screen.
+        void open.close().catch(() => {});
+        return null;
+      }
+      panel = open;
+      // Everything that already happened arrives here first, in order, before the first live
+      // event does — which is the whole reason opening the window in the background is safe.
+      //
+      // `push` hands back nothing and swallows everything, so there is nothing in this
+      // callback that could hold a check up even by accident.
+      unsubscribe = attachPanel(events, (drawn) => open.push(drawn), {
+        plan,
+        onProblem: (problem) => {
+          detail(`The watch window refused an update. The check is unaffected. ${messageOf(problem)}`);
+        },
+      });
+      return open;
+    })
+    .catch((e) => {
+      // openPanel reports its own trouble and hands back null; this is only here for whatever
+      // it could not have seen coming.
+      detail(`The watch window could not open, so this check has no live view. ${messageOf(e)}`);
+      return null;
+    });
+
+  /**
+   * Wait a little for a window that is still opening, and give up cheerfully.
+   *
+   * Used only by `snapTo`, which happens once, early, at the one moment the window and the
+   * thing being checked are both about to exist. Everything else in here refuses to wait at all.
+   *
+   * @returns {Promise<Panel|null>}
+   */
+  async function panelSoon() {
+    if (panel) return panel;
+    return await soon(opening, SNAP_WAIT_MS);
+  }
+
+  const maySnap = watch.snap !== false;
+
+  /** @type {Promise<void>|null} */
+  let stopping = null;
+
+  return {
+    stop: () => {
+      stopping ??= (async () => {
+        stopped = true;
+        // Stop listening first, so nothing new is queued while we are putting it away.
+        try {
+          if (unsubscribe) unsubscribe();
+        } catch {
+          // Already gone. Nothing left to stop listening to.
+        }
+        // Call off a window that is still opening, and do not wait it out. A window that
+        // arrives late finds `stopped` already true and closes itself.
+        givingUp.abort();
+        const open = panel ?? (await soon(opening, STOP_WAIT_MS));
+        if (open) await open.close().catch(() => {});
+      })();
+      return stopping;
+    },
+
+    snapTo: async (beside) => {
+      if (!maySnap) return;
+      try {
+        const open = await panelSoon();
+        if (open) await open.snapTo(beside);
+      } catch (e) {
+        // Where two windows sit is a nicety. Losing it must never cost a check, and it is not
+        // worth a warning in the middle of a clean one.
+        detail(`The panel could not put itself beside what is being checked. ${messageOf(e)}`);
+      }
+    },
+
+    health: () => (panel ? panel.health() : null),
+    open: () => panel !== null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Settings
+// ---------------------------------------------------------------------------
+
+/**
+ * What the command line hands over. Anything the person did not type is left out, so the
+ * settings file still gets a say.
+ *
+ * @typedef {object} WatchFlags
+ * @property {boolean} [enabled]
+ * @property {'left'|'right'} [side]
+ * @property {number} [width]
+ * @property {number} [height]
+ * @property {boolean} [keepOpen]
+ * @property {boolean} [foreground]
+ * @property {boolean} [snap]
+ * @property {'dark'|'light'|'system'} [theme]
+ */
+
+/**
+ * Settle what the panel should do: the settings file first, then anything typed on the command
+ * line, then the defaults.
+ *
+ * `--watch` can only ever turn the panel on. A person who did not type it has not said no to
+ * it — they have said nothing — so it never switches off a panel the settings file asked for.
+ *
+ * @param {{watch?: import('../../types.js').WatchOptions|boolean}|null} [config]
+ * @param {WatchFlags|null} [cli]
+ * @returns {PanelOptions}
+ */
+export function watchOptionsFrom(config, cli) {
+  const raw = config?.watch;
+  // Read as PanelOptions on the way in: a settings file is free to carry a `snap` that the
+  // shared shape does not yet describe.
+  const settings = /** @type {PanelOptions} */ (
+    raw === true ? { enabled: true } : raw && typeof raw === 'object' ? raw : {}
+  );
+  const flags = cli ?? {};
+
+  const width = firstNumber(flags.width, settings.width) ?? DEFAULT_WIDTH;
+  const height = firstNumber(flags.height, settings.height);
+  const side = flags.side ?? settings.side ?? 'right';
+  const theme = flags.theme ?? settings.theme;
+
+  /** @type {PanelOptions} */
+  const merged = {
+    enabled: flags.enabled === true || settings.enabled === true,
+    width,
+    side: side === 'left' ? 'left' : 'right',
+    keepOpen: firstBoolean(flags.keepOpen, settings.keepOpen) ?? true,
+    // Never, unless somebody explicitly asks. This is the whole complaint: it must not keep
+    // bringing itself to the front.
+    foreground: firstBoolean(flags.foreground, settings.foreground) ?? false,
+    // On by default: the point of the panel is that it reads as a side panel of the thing it
+    // is checking, and it cannot do that sitting somewhere else on the screen.
+    snap: firstBoolean(flags.snap, settings.snap) ?? true,
+    // Dark unless somebody asks otherwise. The panel opens on a brand new browser profile, and
+    // a fresh profile insists the computer is in light mode however it is really set, so this
+    // is stated rather than detected.
+    theme: theme === 'light' || theme === 'system' ? theme : 'dark',
+  };
+  // Left out rather than guessed: with no height the panel is as tall as whatever it is
+  // standing next to.
+  if (height !== undefined) merged.height = height;
+  return merged;
+}
+
+/**
+ * @param {...unknown} values
+ * @returns {number|undefined}
+ */
+function firstNumber(...values) {
+  for (const value of values) {
+    if (value === undefined || value === null || value === '') continue;
+    const n = Number(value);
+    if (Number.isFinite(n) && n > 0) return Math.round(n);
+  }
+  return undefined;
+}
+
+/**
+ * @param {...unknown} values
+ * @returns {boolean|undefined}
+ */
+function firstBoolean(...values) {
+  for (const value of values) {
+    if (typeof value === 'boolean') return value;
+  }
+  return undefined;
+}