@antelopejs/dms 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # Changelog
 
+## v0.12.0
+
+[compare changes](https://github.com/AntelopeJS/dms/compare/v0.11.1...v0.12.0)
+
+### 🚀 Enhancements
+
+- **interface-dms:** Expose stable default data type subpaths ([#475](https://github.com/AntelopeJS/dms/pull/475))
+- **frontend:** Enforce the backend boundary in production builds ([#501](https://github.com/AntelopeJS/dms/pull/501))
+- **skills:** Add the verify-dms verification skill, dms-control and formal checks ([#529](https://github.com/AntelopeJS/dms/pull/529))
+- **iface:** Layer interface-dms folders into one acyclic stack ([#539](https://github.com/AntelopeJS/dms/pull/539))
+
+### 🩹 Fixes
+
+- **relation:** Build cyclic relations and label rows without a label ([#471](https://github.com/AntelopeJS/dms/pull/471))
+- **iface:** Use the fallback when an error message is not a string ([#502](https://github.com/AntelopeJS/dms/pull/502))
+- **iface:** Pass consistent Date bounds from IsBetween ([#503](https://github.com/AntelopeJS/dms/pull/503))
+- **iface:** Normalize Action permissions when registering categories ([#504](https://github.com/AntelopeJS/dms/pull/504))
+- **iface:** Keep the original invite validation failure when the thrown value is null ([#505](https://github.com/AntelopeJS/dms/pull/505))
+- **frontend:** Propagate fetched ChartCard series during fresh SSR ([#506](https://github.com/AntelopeJS/dms/pull/506))
+- **iface:** Release a replaced page's component permission identities ([#507](https://github.com/AntelopeJS/dms/pull/507))
+- **dms:** Encode preview cache keys unambiguously ([#508](https://github.com/AntelopeJS/dms/pull/508))
+- **iface:** Keep a page's default permission when its Action is unbound ([#509](https://github.com/AntelopeJS/dms/pull/509))
+- **dms:** Skip persisted presence entries that miss required fields ([#510](https://github.com/AntelopeJS/dms/pull/510))
+- **iface:** Reject malformed footer summary rule operands ([#511](https://github.com/AntelopeJS/dms/pull/511))
+- **iface:** Refuse to build a notification without its required fields ([#512](https://github.com/AntelopeJS/dms/pull/512))
+- **frontend:** Add missing English member-status and form labels ([#513](https://github.com/AntelopeJS/dms/pull/513))
+- **frontend:** Attach native and create to $authFetch ([#514](https://github.com/AntelopeJS/dms/pull/514))
+- **iface:** Describe non-string Zod literals accurately ([#515](https://github.com/AntelopeJS/dms/pull/515))
+- **iface:** Narrow isPrimitive to primitive values ([#516](https://github.com/AntelopeJS/dms/pull/516))
+- **iface:** Reject symbol property keys in Searchable ([#517](https://github.com/AntelopeJS/dms/pull/517))
+- **dms:** Fail verify on recorded formal findings only when covered behaviour changes ([#540](https://github.com/AntelopeJS/dms/pull/540))
+
+### 💅 Refactors
+
+- **backend:** Remove ordinary comments ([#457](https://github.com/AntelopeJS/dms/pull/457))
+- **backend:** Derive types from their owners ([#458](https://github.com/AntelopeJS/dms/pull/458))
+- **backend:** Route dependencies through module entries ([#459](https://github.com/AntelopeJS/dms/pull/459))
+- **backend:** Split page implementation and oversize suites ([#460](https://github.com/AntelopeJS/dms/pull/460))
+- **frontend:** Remove implementation commentary ([#462](https://github.com/AntelopeJS/dms/pull/462))
+- **frontend:** Tighten types and lint ([#463](https://github.com/AntelopeJS/dms/pull/463))
+- **frontend:** Move shared services behind layer entries ([#469](https://github.com/AntelopeJS/dms/pull/469))
+- **frontend:** Split setup responsibilities and remove structural debt ([#470](https://github.com/AntelopeJS/dms/pull/470))
+- **playground:** Remove narrative comments ([#464](https://github.com/AntelopeJS/dms/pull/464))
+- **playground:** Derive types from demo contracts ([#465](https://github.com/AntelopeJS/dms/pull/465))
+- **playground:** Split feature catalogs and fixture literals ([#467](https://github.com/AntelopeJS/dms/pull/467))
+- **iface:** Remove comment debt without changing emit ([#453](https://github.com/AntelopeJS/dms/pull/453))
+- **iface:** Reduce type and lint debt ([#472](https://github.com/AntelopeJS/dms/pull/472))
+- **iface:** Extract private implementation bodies ([#473](https://github.com/AntelopeJS/dms/pull/473))
+- **iface:** Split table-view option type owners ([#474](https://github.com/AntelopeJS/dms/pull/474))
+- **iface:** Keep native async metadata orchestration ([#476](https://github.com/AntelopeJS/dms/pull/476))
+- Finish the dms cleanup and delete the ratchet ([#478](https://github.com/AntelopeJS/dms/pull/478))
+- **backend:** Remove type assertions in routes and pages ([#522](https://github.com/AntelopeJS/dms/pull/522))
+- **backend:** Remove type assertions in auth and table-view implementations ([#523](https://github.com/AntelopeJS/dms/pull/523))
+- **backend:** Remove type assertions in hooks, attachments, automation and fixtures ([#524](https://github.com/AntelopeJS/dms/pull/524))
+- **iface:** Remove type assertions in interface-dms ([#530](https://github.com/AntelopeJS/dms/pull/530))
+
+### 📦 Build
+
+- **playground:** Mark the playground package private ([#468](https://github.com/AntelopeJS/dms/pull/468))
+- Upgrade the guardrail pack to 0.2.6 for the cleanup stacks ([#452](https://github.com/AntelopeJS/dms/pull/452))
+- **playground:** Enforce source import boundaries ([#466](https://github.com/AntelopeJS/dms/pull/466))
+- Adopt the suppression budget from tooling-configs 0.2.7 ([#500](https://github.com/AntelopeJS/dms/pull/500))
+- **deps:** Adopt @antelopejs/interface-data-api 0.5.0 ([#521](https://github.com/AntelopeJS/dms/pull/521))
+
+### 🏡 Chore
+
+- **release:** @antelopejs/interface-dms v0.10.0 ([404c8fb2](https://github.com/AntelopeJS/dms/commit/404c8fb2))
+
+### ✅ Tests
+
+- **backend:** Replace test debt with behavioral checks ([#456](https://github.com/AntelopeJS/dms/pull/456))
+- **frontend:** Replace source-text assertions and module mocks ([#461](https://github.com/AntelopeJS/dms/pull/461))
+- **skills:** Add eval cases for the dms skills ([#499](https://github.com/AntelopeJS/dms/pull/499))
+- **frontend:** Hold the identity refresh until the OAuth page remounts ([#518](https://github.com/AntelopeJS/dms/pull/518))
+- **frontend:** Import the URL preview and password panel subjects at file load ([#519](https://github.com/AntelopeJS/dms/pull/519))
+
+### ❤️ Contributors
+
+- Antony Rizzitelli ([@Upd4ting](http://github.com/Upd4ting))
+- Thomas ([@Thomasims](http://github.com/Thomasims))
+
 ## v0.11.1
 
 [compare changes](https://github.com/AntelopeJS/dms/compare/v0.11.0...v0.11.1)

package/bin/control/base.mjs

@@ -0,0 +1,78 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, relative } from "node:path";
+import { git } from "./git.mjs";
+import { runToEnd } from "./processes.mjs";
+import { saveRun } from "./run-state.mjs";
+import { runPrepare } from "./verify/skill.mjs";
+import {
+  cliPaths,
+  ENVIRONMENT,
+  layOutCopy,
+  restartBackend,
+  spec,
+} from "./stack.mjs";
+
+const READY_MARK = ".dms-control-ready";
+
+function baseCache() {
+  const cacheHome = process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+  return join(cacheHome, "dms-control", "base");
+}
+
+/**
+ * A prepared worktree of the run's base ref, built once per commit under
+ * `~/.cache/dms-control/base/<sha>` with the skill's `prepare` commands.
+ *
+ * @param {Record<string, any>} state The run
+ * @param {Record<string, any>} skill The skill
+ * @returns {{ sha: string, dir: string }} The base commit and its worktree
+ */
+function baseCheckout(state, skill) {
+  const sha = git(["rev-parse", `${state.baseRef}^{commit}`], state.repo);
+  const dir = join(baseCache(), sha);
+  if (existsSync(join(dir, READY_MARK))) return { sha, dir };
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(baseCache(), { recursive: true });
+  git(["worktree", "prune"], state.repo);
+  git(["worktree", "add", "--detach", "--force", dir, sha], state.repo);
+  runPrepare(skill, dir);
+  writeFileSync(join(dir, READY_MARK), `${sha}\n`);
+  return { sha, dir };
+}
+
+/**
+ * Runs `action` while the backend is the base version's, on the run's
+ * current database, then starts the run's own backend again. A Format
+ * containment journey writes data with the base version inside `action`
+ * and reads it back with the head version after it.
+ *
+ * @param {Record<string, any>} state The run
+ * @param {Record<string, any>} skill The skill, whose `prepare` builds the base
+ * @param {(sha: string) => Promise<void>} action What to do against the base backend
+ * @returns {Promise<string>} The base commit
+ */
+export async function withBaseBackend(state, skill, action) {
+  const base = baseCheckout(state, skill);
+  const playground = join(base.dir, relative(state.repo, state.playground));
+  state.baseRoot = join(state.dir, "base-root");
+  rmSync(state.baseRoot, { recursive: true, force: true });
+  const cwd = layOutCopy(playground, base.dir, state.baseRoot);
+  saveRun(state);
+  await runToEnd(
+    spec(
+      state,
+      "base-project-build",
+      cliPaths(playground).ajs,
+      ["project", "build", "-e", ENVIRONMENT],
+      cwd,
+    ),
+  );
+  await restartBackend(state, { playground, cwd });
+  try {
+    await action(base.sha);
+  } finally {
+    await restartBackend(state);
+  }
+  return base.sha;
+}

package/bin/control/browser-client.mjs

@@ -0,0 +1,44 @@
+import { CONTROL_BIN } from "./stack.mjs";
+import { freePort, isAlive, startDetached, waitForOk } from "./processes.mjs";
+import { saveRun } from "./run-state.mjs";
+import { nextFolder } from "./session.mjs";
+
+const READY_TIMEOUT_MS = 60_000;
+
+async function browserServer(state) {
+  if (state.browser && isAlive(state.browser.pid)) return state.browser;
+  const port = await freePort();
+  const started = startDetached({
+    name: "browser",
+    program: process.execPath,
+    args: [CONTROL_BIN, "serve-browser", state.dir, String(port)],
+    cwd: state.dir,
+    env: process.env,
+    logs: state.logs,
+  });
+  state.browser = { ...started, port };
+  saveRun(state);
+  await waitForOk(`http://127.0.0.1:${port}/`, started, READY_TIMEOUT_MS);
+  return state.browser;
+}
+
+/**
+ * Runs one browser action in the run's long-lived browser, starting it on
+ * first use. Each account has its own context and each tab name its own
+ * page, both kept between commands. The action, the URL, the ARIA snapshot
+ * and a screenshot go to `<run>/evidence/browser/NN-<label>/`.
+ *
+ * @param {Record<string, any>} state The run
+ * @param {Record<string, any>} request The action: `do`, `account`, `tab`, and the action's target, value, key or path
+ * @param {string} label What the step does
+ * @returns {Promise<{ ok: boolean, url: string, error: string | null, aria: string, folder: string }>} The outcome
+ */
+export async function browserCommand(state, request, label) {
+  const server = await browserServer(state);
+  const folder = nextFolder(state, "browser", label);
+  const response = await fetch(`http://127.0.0.1:${server.port}/`, {
+    method: "POST",
+    body: JSON.stringify({ ...request, folder }),
+  });
+  return { ...(await response.json()), folder };
+}

package/bin/control/browser.mjs

@@ -0,0 +1,291 @@
+import { writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import { importFrom } from "./mongo.mjs";
+import { loadRun } from "./run-state.mjs";
+
+const ACTION_TIMEOUT_MS = 15_000;
+const NAVIGATION_TIMEOUT_MS = 60_000;
+const SETTLE_MS = 400;
+const VIEWPORT = { width: 1280, height: 900 };
+
+/**
+ * Launches the headless Chromium that playwright-core pins.
+ *
+ * @param {string[]} from Folders to resolve playwright-core from
+ * @returns {Promise<any>} The Playwright browser
+ */
+export async function launchBrowser(from) {
+  const { chromium } = await importFrom("playwright-core", from);
+  return chromium.launch({ headless: true });
+}
+
+/**
+ * A new browser context: one per account, so cookies never leak between
+ * the users a journey plays.
+ *
+ * @param {any} browser The Playwright browser
+ * @returns {Promise<any>} The context
+ */
+export function newContext(browser) {
+  return browser.newContext({
+    viewport: VIEWPORT,
+    locale: "en-US",
+    colorScheme: "light",
+  });
+}
+
+/**
+ * What an action targets: an ARIA role and accessible name, optionally
+ * inside another one (`within`), or the n-th of several matches.
+ *
+ * @typedef {{ role: string, name?: string, exact?: boolean, nth?: number, within?: { role: string, name?: string } }} Target
+ */
+
+/**
+ * The locator of a target, by role and accessible name, as a user finds it.
+ *
+ * @param {any} page The Playwright page
+ * @param {Target} target What to find
+ * @returns {any} The locator
+ */
+export function locate(page, target) {
+  const scope = target.within
+    ? page
+        .getByRole(target.within.role, {
+          name: target.within.name,
+          exact: target.within.exact,
+        })
+        .first()
+    : page;
+  const found = scope.getByRole(target.role, {
+    name: target.name,
+    exact: target.exact,
+  });
+  return target.nth === undefined ? found : found.nth(target.nth);
+}
+
+/**
+ * How a target reads in evidence and checks, such as `button "Invite"`.
+ *
+ * @param {Target} target The target
+ * @returns {string} The description
+ */
+export function describeTarget(target) {
+  const own = `${target.role}${target.name === undefined ? "" : ` "${target.name}"`}${target.nth === undefined ? "" : ` #${target.nth}`}`;
+  return target.within ? `${own} in ${describeTarget(target.within)}` : own;
+}
+
+const ACTIONS = {
+  goto: (page, action) =>
+    page.goto(new URL(action.path, action.baseUrl).href, {
+      waitUntil: "load",
+      timeout: NAVIGATION_TIMEOUT_MS,
+    }),
+  reload: (page) =>
+    page.reload({ waitUntil: "load", timeout: NAVIGATION_TIMEOUT_MS }),
+  click: (page, action) =>
+    locate(page, action.target).click({ timeout: ACTION_TIMEOUT_MS }),
+  fill: (page, action) =>
+    locate(page, action.target).fill(action.value, {
+      timeout: ACTION_TIMEOUT_MS,
+    }),
+  select: (page, action) =>
+    locate(page, action.target).selectOption(
+      { label: action.value },
+      { timeout: ACTION_TIMEOUT_MS },
+    ),
+  check: (page, action) =>
+    locate(page, action.target).check({ timeout: ACTION_TIMEOUT_MS }),
+  uncheck: (page, action) =>
+    locate(page, action.target).uncheck({ timeout: ACTION_TIMEOUT_MS }),
+  hover: (page, action) =>
+    locate(page, action.target).hover({ timeout: ACTION_TIMEOUT_MS }),
+  press: (page, action) =>
+    action.target
+      ? locate(page, action.target).press(action.key, {
+          timeout: ACTION_TIMEOUT_MS,
+        })
+      : page.keyboard.press(action.key),
+  snapshot: () => undefined,
+  screenshot: () => undefined,
+  wait: (page, action) =>
+    locate(page, action.target).waitFor({
+      state: action.state ?? "visible",
+      timeout: action.timeoutMs ?? ACTION_TIMEOUT_MS,
+    }),
+};
+
+/** The action names `perform` accepts. */
+export const ACTION_NAMES = Object.keys(ACTIONS);
+
+/**
+ * Writes what the page shows into `folder`: `url.txt`, `aria.yml` (the ARIA
+ * snapshot of the body) and `screenshot.png`.
+ *
+ * @param {any} page The Playwright page
+ * @param {string} folder The evidence folder
+ * @returns {Promise<string>} The ARIA snapshot
+ */
+export async function capture(page, folder) {
+  writeFileSync(join(folder, "url.txt"), `${page.url()}\n`);
+  const aria = await page
+    .locator("body")
+    .ariaSnapshot({ timeout: ACTION_TIMEOUT_MS })
+    .catch((error) => `snapshot failed: ${error.message}`);
+  writeFileSync(join(folder, "aria.yml"), `${aria}\n`);
+  await page
+    .screenshot({
+      path: join(folder, "screenshot.png"),
+      fullPage: true,
+      timeout: ACTION_TIMEOUT_MS,
+    })
+    .catch(() => undefined);
+  return aria;
+}
+
+/**
+ * Runs one action on a page, then captures the page into `folder`. A target
+ * that is missing, hidden or disabled past the timeout fails the action.
+ *
+ * @param {any} page The Playwright page
+ * @param {{ do: string, baseUrl: string, target?: Target, value?: string, key?: string, path?: string, state?: string, timeoutMs?: number }} action What to do
+ * @param {string} folder The evidence folder
+ * @returns {Promise<{ ok: boolean, url: string, error: string | null, aria: string }>} The outcome
+ */
+export async function perform(page, action, folder) {
+  const run = ACTIONS[action.do];
+  if (!run)
+    throw new Error(
+      `Unknown browser action ${action.do}; expected one of ${ACTION_NAMES.join(", ")}`,
+    );
+  writeFileSync(
+    join(folder, "action.json"),
+    `${JSON.stringify({ ...action, target: action.target && describeTarget(action.target) }, null, 2)}\n`,
+  );
+  let error = null;
+  try {
+    await run(page, action);
+    await page
+      .waitForLoadState("load", { timeout: NAVIGATION_TIMEOUT_MS })
+      .catch(() => undefined);
+    await page.waitForTimeout(SETTLE_MS);
+  } catch (failure) {
+    error = String(failure?.message ?? failure).split("\n")[0];
+  }
+  const aria = await capture(page, folder);
+  return { ok: error === null, url: page.url(), error, aria };
+}
+
+/**
+ * Signs an account in through the sign-in form, the way a user does.
+ *
+ * @param {any} page The Playwright page
+ * @param {{ email: string, password: string }} credentials The account
+ * @param {{ baseUrl: string, folder: (label: string) => string }} options Where the frontend is and where evidence goes
+ * @returns {Promise<{ ok: boolean, url: string, error: string | null, aria: string }>} The outcome of the last step
+ */
+export async function signInThroughForm(page, credentials, options) {
+  const steps = [
+    { do: "goto", path: "/auth" },
+    {
+      do: "fill",
+      target: { role: "textbox", name: "Email address" },
+      value: credentials.email,
+    },
+    {
+      do: "fill",
+      target: { role: "textbox", name: "Password", exact: true },
+      value: credentials.password,
+    },
+    { do: "click", target: { role: "button", name: "Login", exact: true } },
+  ];
+  let outcome = { ok: true, url: page.url(), error: null, aria: "" };
+  for (const step of steps) {
+    outcome = await perform(
+      page,
+      { ...step, baseUrl: options.baseUrl },
+      options.folder(`sign in ${step.do} ${step.target?.name ?? step.path}`),
+    );
+    if (!outcome.ok) return outcome;
+  }
+  await page
+    .waitForURL((url) => !url.pathname.startsWith("/auth"), {
+      timeout: NAVIGATION_TIMEOUT_MS,
+    })
+    .catch(() => undefined);
+  return {
+    ...outcome,
+    url: page.url(),
+    ok: !new URL(page.url()).pathname.startsWith("/auth"),
+  };
+}
+
+/**
+ * Serves the run's browser for `dms-control browser`: one context per
+ * account and one page per tab name, kept between commands, driven by JSON
+ * posted to a loopback port. A GET answers 200 once it listens. It exits
+ * when the browser closes, which Playwright does on SIGTERM.
+ *
+ * @param {string} dir The run folder
+ * @param {string[]} from Folders to resolve playwright-core from
+ * @param {number} port The loopback port
+ * @returns {Promise<void>} Resolves once listening
+ */
+export async function serveBrowser(dir, from, port) {
+  const browser = await launchBrowser(from);
+  browser.on("disconnected", () => process.exit(0));
+  const contexts = new Map();
+  const pages = new Map();
+  const pageFor = async (account, tab) => {
+    const key = `${account}/${tab}`;
+    if (!pages.has(key)) {
+      if (!contexts.has(account))
+        contexts.set(account, await newContext(browser));
+      pages.set(key, await contexts.get(account).newPage());
+    }
+    return pages.get(key);
+  };
+  const handle = async (request) => {
+    const state = loadRun(dir);
+    const page = await pageFor(request.account, request.tab);
+    if (request.do === "login") {
+      const credentials = state.accounts?.[request.account];
+      if (!credentials)
+        return {
+          ok: false,
+          url: page.url(),
+          error: `no account ${request.account}; run dms-control onboard first`,
+          aria: "",
+        };
+      return signInThroughForm(page, credentials, {
+        baseUrl: state.webUrl,
+        folder: () => request.folder,
+      });
+    }
+    return perform(page, { ...request, baseUrl: state.webUrl }, request.folder);
+  };
+  const server = createServer((incoming, outgoing) => {
+    if (incoming.method !== "POST") {
+      outgoing.end("ok");
+      return;
+    }
+    const chunks = [];
+    incoming.on("data", (chunk) => chunks.push(chunk));
+    incoming.on("end", () => {
+      handle(JSON.parse(Buffer.concat(chunks).toString("utf8")))
+        .then((result) => outgoing.end(JSON.stringify(result)))
+        .catch((error) =>
+          outgoing.end(
+            JSON.stringify({
+              ok: false,
+              url: "",
+              error: String(error?.message ?? error),
+              aria: "",
+            }),
+          ),
+        );
+    });
+  });
+  await new Promise((resolve) => server.listen(port, "127.0.0.1", resolve));
+}

package/bin/control/commands-stack.mjs

@@ -0,0 +1,191 @@
+import { writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { browserCommand } from "./browser-client.mjs";
+import { ACTION_NAMES, describeTarget, serveBrowser } from "./browser.mjs";
+import { doctor } from "./doctor.mjs";
+import { capturedMail, serveMail } from "./mail.mjs";
+import { loadRun } from "./run-state.mjs";
+import { apiRequest, isOk, onboard } from "./session.mjs";
+import { down, freshDatabase, resolutionFolders, up } from "./stack.mjs";
+import { loadSkill, runPrepare } from "./verify/skill.mjs";
+
+const BROWSER_ACTIONS = [...ACTION_NAMES, "login"];
+
+/**
+ * Writes `text` to stdout with a trailing newline.
+ *
+ * @param {string} text The output
+ */
+export function print(text) {
+  process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+
+async function defaultPlayground(values) {
+  if (values.playground) return values.playground;
+  const skill = await loadSkill(values.skill, process.cwd()).catch(() => null);
+  if (skill) return join(skill.repo, skill.config.playground);
+  return "playground";
+}
+
+async function commandUp(values) {
+  const skill = values.skill ? resolve(values.skill) : undefined;
+  if (values.prepare) {
+    const loaded = await loadSkill(skill, process.cwd());
+    runPrepare(loaded, loaded.repo);
+  }
+  const state = await up({
+    playground: await defaultPlayground(values),
+    runs: values.runs,
+    mongoUrl: values["mongo-url"],
+    env: values.env,
+    base: values.base,
+    skill,
+  });
+  print(state.dir);
+  return 0;
+}
+
+async function commandDoctor(dir, values) {
+  const state = loadRun(dir);
+  const lines = await doctor(state);
+  writeFileSync(
+    join(state.evidence, "doctor.json"),
+    `${JSON.stringify(lines, null, 2)}\n`,
+  );
+  for (const line of lines.filter((entry) => values.verbose || !entry.ok)) {
+    print(`${line.ok ? "ok  " : "FAIL"} ${line.check}: ${line.detail}`);
+  }
+  return lines.every((line) => line.ok) ? 0 : 1;
+}
+
+async function commandOnboard(dir, values) {
+  const state = loadRun(dir);
+  const answer = await onboard(state, {
+    platformName: values["platform-name"],
+  });
+  if (!isOk(answer.register) || !isOk(answer.login ?? { status: null })) {
+    print(
+      `onboarding failed: register ${answer.register.status} ${JSON.stringify(answer.register.body)}, login ${answer.login?.status ?? "not tried"}`,
+    );
+    return 1;
+  }
+  print(state.accounts.admin.email);
+  return 0;
+}
+
+function browserTarget(values) {
+  if (!values.role) return undefined;
+  const within = values["within-role"]
+    ? { role: values["within-role"], name: values["within-name"] }
+    : undefined;
+  return {
+    role: values.role,
+    name: values.name,
+    exact: values.exact,
+    nth: values.nth === undefined ? undefined : Number(values.nth),
+    within,
+  };
+}
+
+async function commandBrowser(dir, action, values) {
+  if (!BROWSER_ACTIONS.includes(action)) {
+    print(
+      `Unknown browser action ${action}; expected one of ${BROWSER_ACTIONS.join(", ")}`,
+    );
+    return 2;
+  }
+  const state = loadRun(dir);
+  const target = browserTarget(values);
+  const request = {
+    do: action,
+    account: values.as ?? "admin",
+    tab: values.tab ?? "main",
+    target,
+    value: values.value,
+    key: values.key,
+    path: values.path,
+  };
+  const label = `${values.tab ?? "main"} ${action} ${target ? describeTarget(target) : (values.path ?? "")}`;
+  const outcome = await browserCommand(state, request, label);
+  if (!outcome.ok) {
+    print(
+      `FAIL ${label}: ${outcome.error} (at ${outcome.url}; evidence ${outcome.folder})`,
+    );
+    return 1;
+  }
+  if (action === "snapshot") print(outcome.aria);
+  if (action === "screenshot") print(join(outcome.folder, "screenshot.png"));
+  return 0;
+}
+
+async function commandApi(dir, method, path, values) {
+  const state = loadRun(dir);
+  const body = values.body === undefined ? undefined : JSON.parse(values.body);
+  const answer = await apiRequest(state, {
+    method: method.toUpperCase(),
+    path,
+    body,
+    as: values.as ?? "admin",
+  });
+  print(`${answer.status ?? answer.error}`);
+  print(JSON.stringify(answer.body, null, 2) ?? "");
+  return isOk(answer) ? 0 : 1;
+}
+
+async function commandDown(dir) {
+  const state = loadRun(dir);
+  const lines = await down(state);
+  for (const line of lines.filter((entry) => entry.startsWith("could not")))
+    print(line);
+  print(state.evidence);
+  return 0;
+}
+
+/**
+ * Runs a command that drives the product: `up`, `doctor`, `onboard`,
+ * `browser`, `api`, `mail`, `down`, and the two services `up` starts.
+ *
+ * @param {string} command The command
+ * @param {string[]} rest Its positional arguments
+ * @param {Record<string, any>} values Its options
+ * @returns {Promise<number | undefined>} The exit code, or undefined for a command it does not own; the two services keep the process alive
+ */
+export async function runStackCommand(command, rest, values) {
+  switch (command) {
+    case "up":
+      return commandUp(values);
+    case "doctor":
+      return commandDoctor(rest[0], values);
+    case "onboard":
+      return commandOnboard(rest[0], values);
+    case "browser":
+      return commandBrowser(rest[0], rest[1], values);
+    case "api":
+      return commandApi(rest[0], rest[1], rest[2], values);
+    case "mail":
+      print(JSON.stringify(capturedMail(loadRun(rest[0]).mail), null, 2));
+      return 0;
+    case "down":
+      return commandDown(rest[0]);
+    case "reset": {
+      const state = loadRun(rest[0]);
+      state.resetCount = (state.resetCount ?? 0) + 1;
+      print(await freshDatabase(state, `r${state.resetCount}`));
+      return 0;
+    }
+    case "serve-mail": {
+      const state = loadRun(rest[0]);
+      await serveMail(state.mail, state.smtpPort);
+      return 0;
+    }
+    case "serve-browser":
+      await serveBrowser(
+        rest[0],
+        resolutionFolders(loadRun(rest[0])),
+        Number(rest[1]),
+      );
+      return 0;
+    default:
+      return undefined;
+  }
+}