@ticket-gate/engine 0.0.0-stage → 0.1.0-rc.1

package/nightly/status.mjs

@@ -0,0 +1,189 @@
+import { readdirSync } from 'node:fs';
+
+import { isAlive, lockPath } from '../lock.mjs';
+import { NIGHTLY_DEFAULTS } from './define.mjs';
+import { FORCED_MAX, forcedShare, readE2eRuns } from './e2e-runs.mjs';
+import {
+  H,
+  REACHED,
+  WINDOW_MS,
+  freshness,
+  nightlyDir,
+  readNightly,
+  suiteView,
+} from './record.mjs';
+import { mutationLines } from '../mutations/rotation-status.mjs';
+import { SEED_CAP, fixSeed, realGit, short } from './seed.mjs';
+
+const DEFAULT_CFG = {
+  ...NIGHTLY_DEFAULTS,
+  suites: [{ name: '' }],
+};
+
+const localDay = (ms) => new Date(ms).toLocaleDateString('en-CA');
+
+/** The two "Move to CI" triggers over the last 7 days. */
+export function moveToCi({
+  history,
+  nowMs,
+  queued,
+  suite = null,
+  e2eRuns = [],
+}) {
+  const recent = history.filter(
+    (r) => nowMs - Date.parse(r.ranAt) <= WINDOW_MS,
+  );
+  // a top-level skipped-busy night counts for every suite
+  const busyOf = (r) =>
+    r.status === 'skipped-busy' || suiteView(r, suite)?.reason === 'cut-short';
+  const maxWallMs = Math.max(
+    0,
+    ...recent
+      .map((r) => suiteView(r, suite))
+      .filter(Boolean)
+      .filter(REACHED)
+      .map((v) => (suite === null ? (v.firstMs ?? v.ms) : v.ms) ?? 0),
+  );
+  const busy = new Set(
+    recent.filter(busyOf).map((r) => localDay(Date.parse(r.ranAt))),
+  );
+  const busyNights = busy.size;
+  const { share, totalMs } = forcedShare(e2eRuns, nowMs);
+  return {
+    t1: {
+      maxWallMs,
+      busyNights,
+      met: maxWallMs > 4 * H || busyNights >= 2,
+    },
+    t2: {
+      forcedShare: share,
+      totalMs,
+      queued,
+      met: queued >= 3 || (share !== null && share > FORCED_MAX),
+    },
+  };
+}
+
+function headline(latest, fresh, cfg) {
+  if (!latest) return `no nightly runs on record (${cfg.commands.run} --now)`;
+  const s = latest.stats;
+  const counts = s
+    ? ` ${s.expected} passed, ${s.unexpected} failed, ${s.flaky} flaky`
+    : '';
+  let text = `${latest.status} ${short(latest.sha)} ${latest.ranAt}${counts}`;
+  if (latest.reason) text += ` reason ${latest.reason}`;
+  if (latest.status === 'red' && latest.redSpecs?.length)
+    text += ` specs ${latest.redSpecs.join(', ')}`;
+  if (latest.status === 'amber' && latest.flakySpecs?.length)
+    text += ` flaky ${latest.flakySpecs.join(', ')}`;
+  if (fresh === null) text += ' [no run has reached Playwright]';
+  else if (fresh.stale)
+    text += ` [STALE: last full run ${Math.round(fresh.ageMs / H)} h ago]`;
+  return text;
+}
+
+function seedLines(seed) {
+  const out = [];
+  for (const t of seed.redTests)
+    out.push(
+      `  red: ${t.file} > ${t.title} [${t.project}]: ${String(t.error).split('\n')[0]}`,
+    );
+  out.push(
+    seed.lastGreenSha
+      ? `fix seed: merges since last green ${short(seed.lastGreenSha)} (suspects first)`
+      : `fix seed: no green run on record; the newest ${SEED_CAP} merges (suspects first)`,
+  );
+  for (const m of seed.merges)
+    out.push(`  ${m.suspect ? '*' : ' '} ${short(m.sha)} ${m.subject}`);
+  out.push('  next: branch fix/nightly-<date> seeded from the lines above');
+  return out;
+}
+
+/** Lines to print; [0] is the one-line status. */
+export function statusLines(
+  { latest, history, queued, e2eRuns = [] },
+  nowMs,
+  git = realGit,
+  selects = undefined,
+  cfg = DEFAULT_CFG,
+) {
+  selects ??= cfg.selects.interim;
+  const fresh = freshness(history, nowMs);
+  const lines = [headline(latest, fresh, cfg)];
+  for (const suite of cfg.suites.slice(1)) {
+    const view = latest ? suiteView(latest, suite.name) : null;
+    if (view) lines.push(suite.runner.statusLine(view));
+  }
+  for (const d of latest?.drift ?? [])
+    lines.push(
+      `  drift: ${d.file} visited ${d.pathname} (${d.area}) not in its header`,
+    );
+  if (latest?.status === 'red') {
+    try {
+      lines.push(...seedLines(fixSeed({ latest, history, git, selects })));
+    } catch (e) {
+      lines.push(`fix seed unavailable: ${e.message}`);
+    }
+  }
+  const m = moveToCi({ history, nowMs, queued, e2eRuns });
+  const t1Line = (t1, label) =>
+    `move-to-ci 1${label}: max wall ${(t1.maxWallMs / H).toFixed(1)} h, busy nights ${t1.busyNights} of last 7 (${t1.met ? 'MET' : 'not met'}; move at over 4 h or 2 nights)`;
+  lines.push(t1Line(m.t1, ''));
+  for (const suite of cfg.suites.slice(1))
+    lines.push(
+      t1Line(
+        moveToCi({ history, nowMs, queued, e2eRuns, suite: suite.name }).t1,
+        ` (${suite.name})`,
+      ),
+    );
+  const share2 =
+    m.t2.forcedShare === null
+      ? 'n/a (no gate e2e runs in 14 days)'
+      : `${Math.round(m.t2.forcedShare * 100)}% of ${(m.t2.totalMs / H).toFixed(1)} h in 14 days`;
+  lines.push(
+    `move-to-ci 2: forced-full share ${share2}, queued branches ${m.t2.queued} (${m.t2.met ? 'MET' : 'not met'}; move at over 25% or 3 or more)`,
+  );
+  lines.push(...mutationLines(latest, history, nowMs, git));
+  return lines;
+}
+
+/** Live waiting gates: <lock>.waiters/<pid>.json whose pid is alive. */
+export function queuedCount() {
+  try {
+    const dir = `${lockPath()}.waiters`;
+    return readdirSync(dir).filter((f) => isAlive(Number.parseInt(f, 10)))
+      .length;
+  } catch {
+    return 0;
+  }
+}
+
+const EXIT = { green: 0, amber: 0, red: 1 };
+
+export async function main(argv, cfg) {
+  if (argv.length > 0) {
+    console.error(
+      `nightly:status takes no arguments (got ${argv.join(' ')}). Run: ${cfg.commands.status}`,
+    );
+    return 2;
+  }
+  const { latest, history } = readNightly(nightlyDir());
+  const selects =
+    latest?.status === 'red'
+      ? ((await cfg.selects.load?.()) ?? undefined)
+      : undefined;
+  for (const l of statusLines(
+    {
+      latest,
+      history,
+      queued: queuedCount(),
+      e2eRuns: readE2eRuns(nightlyDir()),
+    },
+    Date.now(),
+    undefined,
+    selects,
+    cfg,
+  ))
+    console.log(l);
+  return latest ? (EXIT[latest.status] ?? 3) : 3;
+}

package/nightly/suites.mjs

@@ -0,0 +1,43 @@
+// The Playwright suite as a runner (the block that lived in run.mjs).
+import { summarizeReport } from '../runners/playwright.mjs';
+
+/** playwrightSuite({ cmd }) -> runner: `cmd` + the suite's args + a json reporter, run in the worktree. */
+export function playwrightSuite({ cmd }) {
+  return {
+    name: 'playwright',
+    async run({ wt, io, args = [], limitS, env = {}, out }) {
+      io.rm(out);
+      const pw = await io.run(
+        cmd[0],
+        [...cmd.slice(1), ...args, '--reporter=json,list'],
+        {
+          cwd: wt,
+          env: { ...env, PLAYWRIGHT_JSON_OUTPUT_NAME: out },
+          limitS,
+        },
+      );
+      let raw = null;
+      if (io.exists(out)) {
+        try {
+          raw = JSON.parse(io.readFile(out));
+        } catch {
+          raw = null;
+        }
+        io.rm(out);
+      }
+      if (pw.timedOut) return { timedOut: true, summary: null, report: null };
+      const summary = raw === null ? null : summarizeReport(raw);
+      const report =
+        summary === null
+          ? null
+          : {
+              playwright: raw,
+              // [{ file, pathnames }]: what each spec visited (the navigation recorder)
+              navigation: Object.entries(summary.navigation).map(
+                ([file, pathnames]) => ({ file, pathnames }),
+              ),
+            };
+      return { timedOut: false, summary, report };
+    },
+  };
+}

package/nightly-config.mjs

@@ -0,0 +1,38 @@
+// The validated `nightly` key of gate.config.mjs: the nightly's one config object with the
+// payloads the packs contribute (their `nightlyPayloads` hook) added after the project's own.
+// Imports the collection half of the pack hooks only, so config.mjs may import this file.
+import { packHooksAll } from './pack-hooks-all.mjs';
+import { defineNightly } from './nightly/define.mjs';
+
+/** The pack hooks that feed the nightly. */
+export const NIGHTLY_HOOKS = Object.freeze(['nightlyPayloads']);
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** The nightly of a config (`defineNightly` output); a bad one fails as `gate.config: nightly: <reason>`. */
+export function nightlyOf(config, fail) {
+  if (!isObject(config.nightly)) fail('nightly', 'must be an object');
+  const payloads = [];
+  const seen = new Map();
+  const add = (by, given) => {
+    for (const p of [].concat(given)) {
+      if (payloads.includes(p)) continue;
+      if (typeof p?.name !== 'string' || p.name === '')
+        fail('nightly', `payload from ${by} must be an object with a string name`);
+      if (seen.has(p.name)) fail('nightly', `payload "${p.name}" is given by ${seen.get(p.name)} and ${by}`);
+      seen.set(p.name, by);
+      payloads.push(p);
+    }
+  };
+  const own = config.nightly.payloads ?? [];
+  if (!Array.isArray(own)) fail('nightly', 'payloads must be an array');
+  for (const p of own) add('gate.config', p);
+  for (const { by, value } of packHooksAll('nightlyPayloads', config)) add(by, value);
+  try {
+    return defineNightly({ ...config.nightly, payloads });
+  } catch (e) {
+    const m = /^nightly config: (.*)$/s.exec(e.message);
+    if (m) fail('nightly', m[1]);
+    throw e;
+  }
+}

package/nightly-window.mjs

@@ -0,0 +1,6 @@
+// The nightly record an affected run may lean on. Import-free so the selection planner can load
+// it while the gate config is still loading (digest.mjs reaches the project config, this does not).
+
+/** D4: the newest nightly an affected run may lean on; equals nightly-status FRESH_MS. */
+export const NIGHTLY_MAX_AGE_MS = 36 * 3600 * 1000;
+export const AFFECTED_NIGHTLY = Object.freeze(['green', 'amber']);

package/pack-hooks-all.mjs

@@ -0,0 +1,15 @@
+// The collection half of the pack hooks, with no import: config.mjs reads pack hooks while it
+// validates a gate, and pack-hooks.mjs imports the project's loaded gate (project.mjs), which
+// imports the config that is being validated. Keeping this function here avoids that cycle.
+
+/**
+ * Every pack's hook of that name, in `packs` order, as `{ by, value }` (`by` is the pack's name).
+ * For hooks that all packs contribute to, such as mutation kinds and harnesses.
+ */
+export function packHooksAll(name, config) {
+  const out = [];
+  for (const pack of config.packs ?? [])
+    if (pack?.[name] !== undefined && pack[name] !== null)
+      out.push({ by: pack.name, value: pack[name] });
+  return out;
+}

package/pack-hooks.mjs

@@ -0,0 +1,26 @@
+// How the engine reaches pack behaviour: only through the named hooks a pack in
+// `GATE.packs` carries (the supabase-next pack documents its own in
+// packs/supabase-next/index.mjs). A missing hook means "no pack does that", and every
+// caller keeps working with a fallback; a config with no packs plans and runs.
+import { packHooksAll as collectHooks } from './pack-hooks-all.mjs';
+import { GATE } from './project.mjs';
+
+/** The first pack's hook of that name, or undefined. */
+export function packHook(name, config = GATE) {
+  for (const pack of config.packs ?? [])
+    if (pack?.[name] !== undefined && pack[name] !== null) return pack[name];
+  return undefined;
+}
+
+/** A hook that may be a function resolving to its object (a pack's lazy load), or an object. */
+export async function packHookAsync(name, config = GATE) {
+  const hook = packHook(name, config);
+  return typeof hook === 'function' ? await hook() : hook;
+}
+
+/**
+ * Every pack's hook of that name, in `packs` order, as `{ by, value }` (`by` is the pack's name).
+ * For hooks that all packs contribute to, such as mutation kinds and harnesses.
+ */
+export const packHooksAll = (name, config = GATE) =>
+  collectHooks(name, config);

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@ticket-gate/engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.1",
+  "description": "A configurable verification gate for agent-driven ticket work.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": { "node": ">=22" },
+  "bin": { "ticket-gate": "bin/ticket-gate.mjs" },
+  "exports": {
+    ".": "./config.mjs",
+    "./*": "./*",
+    "./package.json": "./package.json"
+  },
+  "files": ["*", "!test"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dmitry-prohorov/ticket-gate.git",
+    "directory": "packages/engine"
+  },
+  "publishConfig": { "access": "public", "provenance": true }
+}

package/plan.mjs

@@ -0,0 +1,272 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { GATE } from './project.mjs';
+import { ROOT } from './root.mjs';
+import { globRe, pick } from './config.mjs';
+import { newestLedgerLine } from './ledger.mjs';
+
+// Config-only keys (limitS, reuse, stack, option, units) are read here and never copied
+// onto a plan step, so they cannot reach the ledger or the receipt.
+// A step's `when` is a boolean, a glob list or a function of ctx; `cmd` a string or a
+// function of ctx. `base` is the full sha the mutation step compares against; `exists`
+// says whether a changed path is still on disk (a deleted file is not mutated).
+
+/** The step ids a red step before which stops the stack steps (`string | string[]`). */
+export const stopsOf = (config) => [].concat(config.stopOnRedBefore ?? []);
+
+const globHit = (globs, paths) =>
+  paths.some((p) => globs.some((g) => globRe(g).test(p)));
+const noUnits = (sel) => sel.mode === 'affected' && sel.units.length === 0;
+const selectorFailed = (e) => ({
+  mode: 'full',
+  why: `unit selector failed: ${e.message}`,
+  units: [],
+});
+const unitsCmd = (s, sel) => s.units.cmd(sel.units, sel);
+const healthFn = (stack) => typeof stack.health === 'function';
+
+/** The step whose `units` carry the nightly-backed planner (`units.nightly`), whatever its id; or null. */
+export const nightlyStepOf = (gate) =>
+  gate.steps.find((s) => s.units?.nightly) ?? null;
+
+/** The ctx a step's `when`, `cmd` and `units.select` read. */
+export function planCtx(
+  paths,
+  { base = 'HEAD', exists = (p) => existsSync(join(ROOT, p)) } = {},
+) {
+  const touched = (prefix) => paths.some((p) => p.startsWith(prefix));
+  return { paths, base, exists, touched };
+}
+
+const whenOf = (s, ctx) =>
+  typeof s.when === 'function'
+    ? s.when(ctx)
+    : Array.isArray(s.when)
+      ? globHit(s.when, ctx.paths)
+      : s.when;
+
+/**
+ * Awaits `units.select(ctx)` of every units step whose `when` holds (or whose optional
+ * `units.reaches(ctx)` says the diff reaches it anyway): { stepId: Sel }. A throwing
+ * selector gives a full-mode Sel, never a skipped step. Pass the result to planFor as
+ * `opts.units`.
+ */
+export async function selectUnits(config, ctx) {
+  const out = {};
+  for (const s of config.steps) {
+    if (!s.units) continue;
+    try {
+      const reached = whenOf(s, ctx) || (await s.units.reaches?.(ctx));
+      if (reached) out[s.id] = await s.units.select(ctx);
+    } catch (e) {
+      out[s.id] = selectorFailed(e);
+    }
+  }
+  return out;
+}
+
+const buildPlan = (config, ctx, opts) => {
+  const selOf = (s) => {
+    if (!s.units) return undefined;
+    // A precomputed map is authoritative: a step it does not name has no selection.
+    if (opts.units) return opts.units[s.id];
+    if (!whenOf(s, ctx)) return undefined;
+    let got;
+    try {
+      got = s.units.select(ctx);
+    } catch (e) {
+      return selectorFailed(e);
+    }
+    if (typeof got?.then === 'function') {
+      got.catch(() => {});
+      throw new Error(
+        `units.select of ${s.id} is async: precompute with selectUnits()`,
+      );
+    }
+    return got;
+  };
+  return config.steps.map((s) => {
+    const step = {
+      id: s.id,
+      when: whenOf(s, ctx),
+      why: s.why,
+      cmd: typeof s.cmd === 'function' ? s.cmd(ctx) : s.cmd,
+      notRun: s.notRun,
+      summary: s.summary,
+    };
+    if (s.failSummary) step.failSummary = s.failSummary;
+    if (s.human) step.human = s.human;
+    const sel = selOf(s);
+    if (sel) {
+      step.selection = sel;
+      if (noUnits(sel)) {
+        step.when = false;
+        step.notRun = sel.why;
+      } else {
+        step.when = true;
+        step.cmd = unitsCmd(s, sel);
+        if (sel.prepare) step.prepare = sel.prepare;
+      }
+    }
+    return step;
+  });
+};
+
+/**
+ * Pure planning over `config`: which steps run, in what mode, for these changed paths.
+ * `opts` = { skip?, units?, exists?, base?, digestOf?, ledger?, fresh?, [option]? }.
+ * `steps` are the selected steps in run order; `notRun` the unselected ones;
+ * `notSelected` the valid skip ids whose step the diff did not select (a no-op);
+ * `unknown` the skip ids that are not step ids; `stopBefore` the ids a red step before
+ * which stops the stack steps.
+ */
+export function planFor(config, paths, opts = {}) {
+  const { digestOf, ledger = [], fresh = false } = opts;
+  const skip = new Set(opts.skip ?? []);
+  const stepIds = config.steps.map((s) => s.id);
+  const ctx = planCtx(paths, opts);
+  const plan = buildPlan(config, ctx, opts);
+  const cfg = (id) => config.steps.find((c) => c.id === id);
+  const planned = (id) => plan.find((s) => s.id === id);
+  // main decides an option step's `when`, command and list files
+  // (`prepare`) through opts[step.option]; a plan without the option is today's.
+  for (const s of plan) {
+    const o = opts[cfg(s.id).option];
+    if (o?.when !== undefined) s.when = o.when;
+    if (o?.cmd) s.cmd = o.cmd;
+    if (o?.prepare) s.prepare = o.prepare;
+  }
+  const unknown = [...skip].filter((id) => !stepIds.includes(id));
+  // The newest ledger line on this step's (id, cmd, digest), or undefined.
+  const lastRun = (s) =>
+    newestLedgerLine(ledger, {
+      id: s.id,
+      cmd: s.cmd,
+      digest: digestOf(s.id, s.cmd),
+    });
+  const modeOf = (s) => {
+    if (s.human) return 'human';
+    if (skip.has(s.id)) return 'skip';
+    const c = cfg(s.id);
+    if (digestOf && c.reuse && !fresh) {
+      const last = lastRun(s);
+      // R1, F4: only a full result with no knownRed stands in for a full run.
+      const o =
+        opts[c.option] ??
+        (s.selection && {
+          mode: s.selection.mode,
+          knownRedCount: s.selection.knownRedCount,
+        });
+      // prettier-ignore
+      if (c.reuse.fullOnly && (o?.mode === 'affected' || (last?.mode ?? 'full') !== 'full' || (o?.knownRedCount ?? 0) > 0)) return 'run';
+      if (last?.status === 'pass') return 'reuse';
+    }
+    return 'run';
+  };
+  const withMode = (list) => list.map((s) => ({ ...s, mode: modeOf(s) }));
+
+  // Playwright shares one seed across specs and fails on a used one, so
+  // a step that needs a fresh seed is preceded by exactly one reset: in a
+  // `satisfiedBy` step if that runs, else in the stack's own reset step.
+  const steps0 = withMode(plan.filter((s) => s.when));
+  const runs = (id) => steps0.find((s) => s.id === id)?.mode === 'run';
+  for (const stack of Object.values(config.stacks)) {
+    const { reset } = stack;
+    if (!reset) continue;
+    planned(reset.step).when =
+      reset.before.some(runs) && !reset.satisfiedBy.some(runs);
+  }
+
+  // R4: the health step checks the stack steps that actually run, and nothing else.
+  for (const [name, stack] of Object.entries(config.stacks)) {
+    if (!stack.health || healthFn(stack)) continue;
+    const stackRuns = plan
+      .filter((s) => cfg(s.id).stack === name && s.when && modeOf(s) === 'run')
+      .map((s) => s.id);
+    const health = planned(stack.health.step);
+    health.when = stackRuns.length > 0;
+    health.cmd = stack.health.preflight(stackRuns);
+  }
+
+  const selected = plan.filter((s) => s.when);
+  const steps = withMode(selected);
+
+  // R3: after a reset passes, wait until the services the later stack steps
+  // need are healthy. The step's own cmd is untouched.
+  for (const [name, stack] of Object.entries(config.stacks)) {
+    const { reset } = stack;
+    const runStack = steps.filter(
+      (s) => cfg(s.id).stack === name && s.mode === 'run',
+    );
+    for (const s of steps) {
+      if (
+        !reset ||
+        !stack.health?.ready ||
+        (s.id !== reset.step && !reset.satisfiedBy.includes(s.id))
+      )
+        continue;
+      const after = runStack
+        .slice(runStack.findIndex((r) => r.id === s.id) + 1)
+        .map((r) => r.id);
+      if (s.mode === 'run' && after.length) s.ready = stack.health.ready(after);
+    }
+    if (!reset?.note) continue;
+    const by = reset.satisfiedBy.find(runs) ?? reset.step;
+    for (const s of steps) {
+      if (!reset.note.steps.includes(s.id)) continue;
+      const base = s.summary;
+      s.summary = (out) => `${base(out) ?? 'passed'}; ${reset.note.text(by)}`;
+    }
+  }
+
+  // 4.2 form: a function `health` is the step `<stack>:health`, before the stack's first run step.
+  for (const [name, stack] of Object.entries(config.stacks)) {
+    if (!healthFn(stack)) continue;
+    const onStack = (s) => cfg(s.id)?.stack === name && s.mode === 'run';
+    const at = steps.findIndex(onStack);
+    if (at < 0) continue;
+    steps.splice(at, 0, {
+      id: `${name}:health`,
+      when: true,
+      why: `the ${name} stack must be healthy before its steps run`,
+      cmd: stack.health(steps.filter(onStack).map((s) => s.id)),
+      notRun: `no step needs the ${name} stack`,
+      summary: (out) => pick(out, [/.+/]) ?? `${name} stack ok`,
+      mode: 'run',
+      limitS: 120,
+      health: true,
+    });
+  }
+
+  // Every non-human step carries its digest; a reused one also says where from.
+  const withDigest = (s) => {
+    if (!digestOf || s.human || s.health) return s;
+    const digest = digestOf(s.id, s.cmd);
+    if (s.mode !== 'reuse') return { ...s, digest };
+    const last = lastRun(s);
+    return {
+      ...s,
+      digest,
+      reusedFrom: last.ranAt,
+      reusedSummary: String(last.summary ?? 'passed'),
+    };
+  };
+
+  return {
+    steps: steps.map(withDigest),
+    notRun: plan.filter((s) => !s.when),
+    notSelected: [...skip].filter(
+      (id) => stepIds.includes(id) && !selected.some((s) => s.id === id),
+    ),
+    unknown,
+    stopBefore: stopsOf(config),
+  };
+}
+
+/**
+ * The gate's plan. A plan with no precomputed `opts.units` never calls
+ * a units selector (a selector is async; cli.mjs awaits selectUnits() first), so a
+ * units step runs its own `cmd`, as before units existed.
+ */
+export const planSteps = (paths, skipIds, opts = {}) =>
+  planFor(GATE, paths, { ...opts, skip: skipIds, units: opts.units ?? {} });