@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/cli/src/tui/scroll.js

@@ -0,0 +1,29 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createElement as h, useEffect, useRef, useState } from "react";
+import { Box, Text, measureElement } from "ink";
+import { KEEP_ABOUT, KEEP_TITLE } from "@parity/product-lab/shell/words";
+import { Heading } from "./frame.js";
+export function useBodyScroll(view) {
+    const outer = useRef(null);
+    const inner = useRef(null);
+    const room = useRef(0);
+    const [moved, setMoved] = useState({ view, offset: 0 });
+    useEffect(() => {
+        if (outer.current && inner.current)
+            room.current = Math.max(0, measureElement(inner.current).height - measureElement(outer.current).height);
+    });
+    const offset = moved.view === view ? Math.min(moved.offset, room.current) : 0;
+    const scroll = (by) => setMoved((last) => ({ view, offset: Math.max(0, Math.min(room.current, (last.view === view ? last.offset : 0) + by)) }));
+    return { outer, inner, offset, scroll };
+}
+export function Logs({ source, sources, index, lines, filter, filtering, height, back = 0 }) {
+    const size = Math.max(5, height);
+    const end = Math.max(Math.min(size, lines.length), lines.length - back);
+    const shown = lines.slice(Math.max(0, end - size), end);
+    return h(Box, { flexDirection: "column" }, h(Heading, { title: "LOGS", right: "↑↓ scroll   ←→ source   / filter   esc back" }), h(Text, { wrap: "wrap" }, "Source: ", h(Text, { bold: true }, source), h(Text, { dimColor: true }, `  (${index + 1} of ${sources})`)), filtering || filter ? h(Text, null, "Filter: ", h(Text, { color: "cyan" }, filter), filtering ? h(Text, { dimColor: true }, "▏ (⏎ keeps it, esc clears it)") : null) : null, end > shown.length ? h(Text, { dimColor: true }, `… ${end - shown.length} earlier lines`) : null, shown.length ? h(Box, { flexDirection: "column" }, ...shown.map((line, at) => h(Text, { key: at, wrap: "wrap" }, line))) : h(Text, { dimColor: true }, filter ? "No line matches the filter." : "Nothing yet."), end < lines.length ? h(Text, { dimColor: true }, `… ${lines.length - end} later lines (↓)`) : null);
+}
+export const logsBackLimit = (lines, height) => Math.max(0, lines - Math.max(5, height));
+export function Help({ short }) {
+    return h(Box, { flexDirection: "column", rowGap: short ? 0 : 1 }, h(Heading, { title: "HELP", right: "↑↓ scroll   esc back" }), h(Text, { wrap: "wrap" }, "This is the lab running in your terminal: the same chains, people and runs as the lab window, live. Each key opens a screen; esc comes back here. The wheel scrolls; Option+drag selects text."), h(Box, { flexDirection: "column" }, h(Text, null, h(Text, { bold: true }, "c"), " chains: which chains run, their blocks, saved states; switch or reset"), h(Text, null, h(Text, { bold: true }, "p"), " people: who exists, on which host, where they came from; make or remove one"), h(Text, null, h(Text, { bold: true }, "r"), " run: the latest run step by step, with each step's screen and chain checks and what it wrote"), h(Text, null, h(Text, { bold: true }, "s"), " scenarios: every one, who it needs and where it runs; / filters, ⏎ shows its steps, r runs it"), h(Text, null, h(Text, { bold: true }, "h"), " history: this session's runs; ⏎ opens one in Run (← → walks through them there)"), h(Text, null, h(Text, { bold: true }, "g"), " config: what this lab turns on, and the lines that turn on the rest"), h(Text, null, h(Text, { bold: true }, "l"), " logs: the lab's own lines, then each chain's, host's and app's log file; ← → picks one, / filters"), h(Text, null, h(Text, { bold: true }, "o"), " the lab window   ", h(Text, { bold: true }, "q"), " stop the lab (asks first; Ctrl-C stops at once)")), h(Text, { wrap: "wrap" }, h(Text, { bold: true }, `${KEEP_TITLE} (k on Chains): `), KEEP_ABOUT), h(Text, { dimColor: true, wrap: "wrap" }, "Not in a terminal, or with CI set, or with --plain, the lab prints plain lines instead."));
+}

package/entrypoints/cli/src/tui/start.d.ts

@@ -0,0 +1,54 @@
+import type { LabRuntime } from "@parity/product-lab/ports/driving";
+import type { LabWindow } from "@parity/product-lab/shell/visible";
+import { StartProgressView } from "../start-progress.js";
+import type { StartView } from "./starting.js";
+import type { AgentLauncher } from "../agents.js";
+/** The app on the terminal, from before the lab is read until the command ends. */
+export interface TerminalSession {
+    /** The start's checklist, for `startDev` (`DevOptions.progress`): each change redraws the Starting screen. */
+    readonly progress: StartProgressView;
+    /** A line of the command's own for Logs (hot reload's). */
+    log(line: string): void;
+    /** The lab runs: the app shows it (Home and every screen). `attached`: it is another process's window (B1 e). */
+    running(lab: {
+        url: string;
+        window?: LabWindow;
+        attached?: boolean;
+    }): void;
+    /** Ask a question the start waits on, inside the app (its lines split on "\n"); leaving the app answers no. */
+    ask(question: string): Promise<boolean>;
+    /** Nothing runs: the app says why until the person leaves it (q, Ctrl-C) or `until` resolves (a signal). */
+    failed(error: unknown, until: Promise<void>): Promise<void>;
+    /** Resolves when the person leaves the app: q (then y while something runs) or Ctrl-C. */
+    readonly left: Promise<void>;
+    /** Leave the alternate screen, give the console back and print what was printed meanwhile; throws a crash's error. */
+    close(): void;
+}
+/**
+ * What the app shows once its lab is over before it ran here: why, and whether it ran and ended (the lab window an
+ * attached app followed closed: `ended`, backlog 236) or did not start.
+ */
+export declare function failedStart(progress: Pick<StartView, "phases" | "notes">, error: unknown): StartView;
+/**
+ * The runtime as the app uses it: with the lab's own window open (`window`), a run the app starts goes through the
+ * window's runner, so each person acts and is read in their tile as in a run from the window's Run (runtime-routes.ts
+ * does the same for a run another process starts). With none (--browser, or another process's window) the runtime runs it.
+ */
+export declare function throughWindow<R extends Pick<LabRuntime, "runFeatures" | "runScenario">>(runtime: R, window: () => LabWindow["runner"]["outside"] | undefined): R;
+/** Take the terminal: the alternate screen, the app, the title. The lab need not be loaded yet. */
+export declare function openTerminalApp(options: {
+    runtime: LabRuntime;
+    hostLog?: string;
+    agents?: AgentLauncher;
+}): TerminalSession;
+/**
+ * Show the app over a running lab until the person quits it (q, then y; or Ctrl-C) or `until` resolves (the lab
+ * window closed, a signal). Resolves once the app is gone and the terminal is back.
+ */
+export declare function runTerminalApp(options: {
+    runtime: LabRuntime;
+    url: string;
+    window?: LabWindow;
+    until: Promise<void>;
+    hostLog?: string;
+}): Promise<void>;

package/entrypoints/cli/src/tui/start.js

@@ -0,0 +1,168 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { format } from "node:util";
+import React from "react";
+import { render } from "ink";
+import { StartProgressView } from "../start-progress.js";
+import { LabApp } from "./app.js";
+import { MouseCapture, terminalGone } from "./mouse.js";
+import { LabWindowClosed } from "../lab-window-closed.js";
+const message = (error) => (error instanceof Error ? error.message : String(error));
+export function failedStart(progress, error) {
+    return { phases: progress.phases, notes: progress.notes, failure: message(error), ...(error instanceof LabWindowClosed ? { ended: true } : {}) };
+}
+export function throughWindow(runtime, window) {
+    return new Proxy(runtime, {
+        get: (target, key) => {
+            const outside = window();
+            if (outside && key === "runFeatures")
+                return outside.feature;
+            if (outside && key === "runScenario")
+                return outside.scenario;
+            const value = Reflect.get(target, key, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
+export function openTerminalApp(options) {
+    const runtime = options.runtime;
+    let lab;
+    const openWindow = async () => {
+        if (lab?.attached)
+            return `The lab window is another process's: it is at ${lab.url}.`;
+        if (lab?.window) {
+            await lab.window.page.bringToFront();
+            return "The lab window is in front.";
+        }
+        return lab ? `No lab window with --browser: open ${lab.url} in your browser.` : "The lab window opens once the lab runs.";
+    };
+    const printed = [];
+    const own = [];
+    const original = { log: console.log, info: console.info, warn: console.warn, error: console.error, debug: console.debug };
+    const keep = (...args) => {
+        printed.push({ at: Date.now(), line: format(...args) });
+        if (printed.length > 1000)
+            printed.splice(0, printed.length - 1000);
+    };
+    Object.assign(console, { log: keep, info: keep, warn: keep, error: keep, debug: keep });
+    const log = () => [...own, ...printed];
+    let quit = () => undefined;
+    const quitting = new Promise((resolve) => { quit = resolve; });
+    const stdout = process.stdout;
+    let titled = stdout.isTTY;
+    let title = "";
+    const setTitle = () => {
+        const next = runtime.lab?.name ? `product-lab · ${runtime.lab.name}` : "product-lab";
+        if (!titled || next === title)
+            return;
+        title = next;
+        stdout.write(`\x1b]0;${next}\x07`);
+    };
+    const restoreTitle = () => {
+        if (!titled)
+            return;
+        titled = false;
+        try {
+            stdout.write("\x1b]0;\x07\x1b[23;0t");
+        }
+        catch (error) {
+            if (!terminalGone(error))
+                throw error;
+        }
+    };
+    if (titled) {
+        stdout.write("\x1b[22;0t");
+        setTitle();
+        process.once("exit", restoreTitle);
+    }
+    const appRuntime = throughWindow(runtime, () => lab?.window?.runner.outside);
+    let start;
+    const mouse = stdout.isTTY && process.stdin.isTTY ? new MouseCapture(process.stdin, stdout) : undefined;
+    const element = () => React.createElement(LabApp, { runtime: appRuntime, lab: runtime.lab?.name ?? "lab", url: lab?.url ?? "", openWindow, quit, log, ...(mouse ? { mouse } : {}), ...(lab?.attached ? { attached: true } : {}), ...(start ? { start } : {}), ...(options.hostLog ? { hostLog: options.hostLog } : {}), ...(options.agents ? { agents: options.agents } : {}), ...(stdout.isTTY ? { size: { columns: stdout.columns, rows: stdout.rows } } : {}) });
+    let app;
+    let closed = false;
+    const refresh = () => {
+        if (!app || closed)
+            return;
+        setTitle();
+        app.rerender(element());
+    };
+    const progress = new StartProgressView({ out: { write: () => true }, mode: "plain", colour: false, onChange: refresh });
+    start = { phases: progress.phases, notes: progress.notes };
+    const shown = render(element(), { alternateScreen: true, exitOnCtrlC: true, patchConsole: false });
+    app = shown;
+    const resized = () => {
+        shown.clear();
+        stdout.write("\x1b[2J\x1b[H");
+        shown.rerender(element());
+    };
+    if (stdout.isTTY)
+        stdout.prependListener("resize", resized);
+    let crash;
+    const left = Promise.race([quitting, shown.waitUntilExit()]).then(() => undefined, (error) => { crash = { error }; });
+    return {
+        progress,
+        left,
+        log: (line) => {
+            own.push({ at: Date.now(), line });
+            if (own.length > 1000)
+                own.splice(0, own.length - 1000);
+        },
+        ask: (question) => new Promise((resolve) => {
+            const answer = (yes) => {
+                start = { phases: progress.phases, notes: progress.notes };
+                refresh();
+                resolve(yes);
+            };
+            start = { phases: progress.phases, notes: progress.notes, question: { lines: question.trimEnd().split("\n"), answer } };
+            refresh();
+            void left.then(() => resolve(false));
+        }),
+        running: (running) => {
+            lab = running;
+            start = undefined;
+            refresh();
+        },
+        failed: async (error, until) => {
+            start = failedStart(progress, error);
+            refresh();
+            await Promise.race([left, until]);
+        },
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            let failure = crash;
+            stdout.off("resize", resized);
+            mouse?.stop();
+            try {
+                shown.unmount();
+            }
+            catch (error) {
+                if (!terminalGone(error))
+                    failure ??= { error };
+            }
+            restoreTitle();
+            process.off("exit", restoreTitle);
+            Object.assign(console, original);
+            for (const { line } of printed) {
+                try {
+                    original.log(line);
+                }
+                catch (error) {
+                    if (!terminalGone(error))
+                        failure ??= { error };
+                    break;
+                }
+            }
+            if (failure)
+                throw failure.error;
+        },
+    };
+}
+export async function runTerminalApp(options) {
+    const session = openTerminalApp({ runtime: options.runtime, ...(options.hostLog ? { hostLog: options.hostLog } : {}) });
+    session.running({ url: options.url, ...(options.window ? { window: options.window } : {}) });
+    await Promise.race([session.left, options.until]);
+    session.close();
+}

package/entrypoints/cli/src/tui/starting.d.ts

@@ -0,0 +1,52 @@
+import { type ReactElement } from "react";
+import { type Key } from "ink";
+import type { EnvironmentState } from "@parity/product-lab/ports/driving";
+import { type PhaseView } from "../start-progress.js";
+/** What the app shows until the lab runs. */
+export interface StartView {
+    /** The start's phases, as the plain checklist has them (`StartProgressView.phases`). */
+    readonly phases: readonly PhaseView[];
+    /** Its one-line stages (`StartProgressView.notes`). */
+    readonly notes: readonly string[];
+    /** Why nothing runs: the start (or reading the lab) failed. The app waits for the person to read it. */
+    readonly failure?: string;
+    /**
+     * With `failure`: the lab ran and has ended (the lab window an attached app followed closed, backlog 236), so the app
+     * says that, not that the lab did not start.
+     */
+    readonly ended?: boolean;
+    /** A question the start waits on (a kept chain whose day ended: replace it?), its lines, and how to answer it. */
+    readonly question?: {
+        readonly lines: readonly string[];
+        readonly answer: (yes: boolean) => void;
+    };
+}
+export declare function Starting({ start, now }: {
+    start: StartView;
+    now: number;
+}): ReactElement;
+/** The key bar while the lab starts: only its lines and leaving mean anything. */
+export declare function startKeys<T extends readonly [string, string, unknown]>(keys: readonly T[], start: StartView): (readonly [string, string, T[2]])[];
+/** The header while the lab starts ("starting" until the runtime says more) or after it did not start. */
+export declare function startingHeader<T extends {
+    environment: string;
+    state: string;
+    mark: string;
+}>(shown: T, start: StartView): T;
+/** The keys while the lab starts: l and Logs' own keys, esc, and q (asks before stopping a start; leaves a failed one). */
+export declare function startInput(input: string, key: Key, app: {
+    start: StartView;
+    screen: string;
+    setScreen: (screen: "home" | "logs") => void;
+    setFiltering: (on: boolean) => void;
+    setLogIndex: (index: number) => void;
+    logSource: number;
+    logSources: number;
+    quit: () => void;
+    ask: (prompt: {
+        question: string;
+        yes: () => Promise<string | undefined>;
+    }) => void;
+}): void;
+/** The environment's state, or stopped while the lab is not read yet (the app shows before its config is read). */
+export declare function stateBeforeLoad(read: () => EnvironmentState): EnvironmentState;

package/entrypoints/cli/src/tui/starting.js

@@ -0,0 +1,67 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createElement as h } from "react";
+import { Box, Text } from "ink";
+import { checklistRow } from "../start-progress.js";
+const COLOUR = { done: "green", cached: "green", failed: "red", active: "cyan", skipped: "gray" };
+const NOTES = 4;
+export function Starting({ start, now }) {
+    const titleWidth = Math.min(28, Math.max(0, ...start.phases.map((phase) => phase.title.length)));
+    const frame = Math.floor(now / 250);
+    return h(Box, { flexDirection: "column", rowGap: 1 }, h(Text, { bold: true, color: start.failure ? "red" : undefined }, start.failure ? (start.ended ? "THE LAB WINDOW CLOSED" : "THE LAB DID NOT START") : "STARTING"), start.phases.length
+        ? h(Box, { flexDirection: "column" }, ...start.phases.map((phase) => {
+            const row = checklistRow(phase, now, frame, titleWidth);
+            return h(Text, { key: phase.id, wrap: "truncate-end", dimColor: phase.state === "pending" }, row.slice(0, 2), h(Text, { color: COLOUR[phase.state] }, row[2]), row.slice(3));
+        }))
+        : h(Text, { dimColor: true }, start.failure ? (start.ended ? "The lab it followed has ended." : "Nothing started.") : "Reading the lab and getting the chain ready…"), start.notes.length && !start.failure
+        ? h(Box, { flexDirection: "column" }, ...start.notes.slice(-NOTES).map((note, index) => h(Text, { key: index, dimColor: true, wrap: "truncate-end" }, note)))
+        : null, start.question && !start.failure
+        ? h(Box, { flexDirection: "column", borderStyle: "round", borderColor: "yellow", paddingX: 1 }, ...start.question.lines.map((line, index) => h(Text, { key: index, wrap: "wrap", bold: index === start.question.lines.length - 1 }, line)), h(Text, { dimColor: true, wrap: "wrap" }, "y replaces it · n, Enter or esc keeps it, and the start stops."))
+        : start.failure
+            ? h(Box, { flexDirection: "column", borderStyle: "round", borderColor: "red", paddingX: 1 }, h(Text, { wrap: "wrap" }, start.failure), h(Text, { dimColor: true, wrap: "wrap" }, "q leaves and prints this under your shell's history; l shows the lab's lines."))
+            : h(Text, { dimColor: true }, "q stops the start · l shows the lab's lines"));
+}
+export function startKeys(keys, start) {
+    if (start.question && !start.failure)
+        return [["y", "replace it", undefined], ["n", "keep it and stop", undefined]];
+    return keys.filter(([key]) => key === "l" || key === "q").map(([key, label, target]) => [key, key === "q" ? (start.failure ? "quit" : "stop the start") : label, target]);
+}
+export function startingHeader(shown, start) {
+    if (start.failure)
+        return start.ended ? { ...shown, state: "ended", mark: "off" } : { ...shown, state: "did not start", mark: "failed" };
+    return shown.mark === "off" ? { ...shown, environment: "", state: "starting", mark: "busy" } : shown;
+}
+export function startInput(input, key, app) {
+    if (app.start.question && !app.start.failure) {
+        if (input === "y" || input === "Y")
+            return app.start.question.answer(true);
+        if (input === "n" || input === "N" || key.return || key.escape)
+            return app.start.question.answer(false);
+        return;
+    }
+    if (app.screen === "logs") {
+        if (input === "/")
+            return app.setFiltering(true);
+        if (key.leftArrow)
+            return app.setLogIndex(Math.max(0, app.logSource - 1));
+        if (key.rightArrow)
+            return app.setLogIndex(Math.min(app.logSources - 1, app.logSource + 1));
+    }
+    if (key.escape)
+        return app.setScreen("home");
+    if (input === "l")
+        return app.setScreen(app.screen === "logs" ? "home" : "logs");
+    if (input !== "q")
+        return;
+    if (app.start.failure)
+        return app.quit();
+    app.ask({ question: "Stop the start? What it started so far stops too. y stops, any other key stays.", yes: async () => { app.quit(); return "Stopping the start…"; } });
+}
+export function stateBeforeLoad(read) {
+    try {
+        return read();
+    }
+    catch {
+        return { state: "stopped" };
+    }
+}

package/entrypoints/cli/src/versions-command.d.ts

@@ -0,0 +1,22 @@
+import type { LabRuntime } from "@parity/product-lab/ports/driving";
+export declare const VERSIONS_USAGE = "Usage: product-lab versions [--available] [--json] [--config lab.config.ts]\n       product-lab versions update [<component>\u2026] [--to <selector>] [--json]\n       product-lab versions pin <component> <version> [--json]\n       product-lab versions verify [--json]\n       product-lab versions propose --from <suite-dir> --row <candidate-row> --control <control-row>\n                                    [--write | --dry-run] [--body <file>] [--json]\n\nThe lab's version selectors (defineLab({ versions: { policy } })) against lab.lock.json.\n  versions         Each component: its selector, the locked version and source, and its status\n                   (locked, unlocked, not-selected, resolved-at-run-start). --available also resolves\n                   what each selector (latest-release for a locked one) gives now.\n  update           Resolve and rewrite the lock (all or nothing): each component with --to, else the\n                   lab's selector, else latest-release. Exit 1 when a version does not resolve (nothing\n                   written) or the lock changed meanwhile (run it again).\n  pin              Lock an explicit version, release:<owner/repo>@<tag> or git:<repo>@<ref>.\n  verify           Fetch every locked component again and compare digests. Exit 0 when the lock is\n                   verified, 1 when it failed (a mismatch, or a locked selection with no entry), 2 when\n                   something could not be verified. Suited to CI after checkout.\n  propose          Propose a lock update from a suite run's sealed execution receipts\n                   (product-lab test --suite nightly --report-dir <suite-dir>): the exact versions candidate row\n                   --row ran and passed with, against control row --control that ran the current lock and passed.\n                   Nothing is resolved again. Dry run by default (prints the change and a pull request body);\n                   --write writes lab.lock.json (compare-and-swap: refused if the lock changed since the suite).\n                   --body writes the Markdown body to a file. Exit 0 proposed, 1 refused (the refusal's code says\n                   why: failed, dry-run, unsupported, stale-lock, a digest mismatch, \u2026). Opens no pull request;\n                   local receipts are consistency checks, not an attestation against a hostile producer.\nComponents are <kind>:<name> (runtime:people, host:truapi-cli); a bare kind (host) names the lab's only\ncomponent of that kind. Selectors: locked, deployed, latest-release, 0.20.0, release:owner/repo@tag,\ngit:<repo>@<ref>. A run tries other versions without touching the lock: product-lab test --candidate host@latest-release.";
+/** Split `--candidate <component>@<selector>` at the first `@`: component ids never contain `@`, selectors may. */
+export declare function parseCandidates(values: readonly string[] | undefined): Record<string, string>;
+/** A component argument: `<kind>:<name>`, or a bare kind when the lab has exactly one component of it. */
+export declare function componentId(argument: string, known: readonly string[]): string;
+/** Candidates with bare kinds expanded against the lab's components. */
+export declare function resolveCandidates(runtime: LabRuntime, values: readonly string[] | undefined): Promise<Record<string, string>>;
+export declare function runVersionsCommand(runtime: LabRuntime, argv: string[], out?: (line: string) => void): Promise<number>;
+/**
+ * At `product-lab test`'s start: resolve the lab's versions once, with any
+ * `--candidate` selectors, and record the resolution as a run manifest (the
+ * lock is untouched). Skipped when the lab declares no version policy and no
+ * candidate is given. Returns the variables that pass the resolution on: the
+ * Cucumber process's environment start reuses it instead of resolving again.
+ */
+export declare function resolveRunVersions(runtime: LabRuntime, options: {
+    environment?: string;
+    candidates?: readonly string[];
+}, out?: (line: string) => void, 
+/** Backlog 186: the plain output's line: each component and its version, without the workspace and manifest paths. */
+plain?: boolean): Promise<Record<string, string>>;

package/entrypoints/cli/src/versions-command.js

@@ -0,0 +1,230 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+export const VERSIONS_USAGE = `Usage: product-lab versions [--available] [--json] [--config lab.config.ts]
+       product-lab versions update [<component>…] [--to <selector>] [--json]
+       product-lab versions pin <component> <version> [--json]
+       product-lab versions verify [--json]
+       product-lab versions propose --from <suite-dir> --row <candidate-row> --control <control-row>
+                                    [--write | --dry-run] [--body <file>] [--json]
+
+The lab's version selectors (defineLab({ versions: { policy } })) against lab.lock.json.
+  versions         Each component: its selector, the locked version and source, and its status
+                   (locked, unlocked, not-selected, resolved-at-run-start). --available also resolves
+                   what each selector (latest-release for a locked one) gives now.
+  update           Resolve and rewrite the lock (all or nothing): each component with --to, else the
+                   lab's selector, else latest-release. Exit 1 when a version does not resolve (nothing
+                   written) or the lock changed meanwhile (run it again).
+  pin              Lock an explicit version, release:<owner/repo>@<tag> or git:<repo>@<ref>.
+  verify           Fetch every locked component again and compare digests. Exit 0 when the lock is
+                   verified, 1 when it failed (a mismatch, or a locked selection with no entry), 2 when
+                   something could not be verified. Suited to CI after checkout.
+  propose          Propose a lock update from a suite run's sealed execution receipts
+                   (product-lab test --suite nightly --report-dir <suite-dir>): the exact versions candidate row
+                   --row ran and passed with, against control row --control that ran the current lock and passed.
+                   Nothing is resolved again. Dry run by default (prints the change and a pull request body);
+                   --write writes lab.lock.json (compare-and-swap: refused if the lock changed since the suite).
+                   --body writes the Markdown body to a file. Exit 0 proposed, 1 refused (the refusal's code says
+                   why: failed, dry-run, unsupported, stale-lock, a digest mismatch, …). Opens no pull request;
+                   local receipts are consistency checks, not an attestation against a hostile producer.
+Components are <kind>:<name> (runtime:people, host:truapi-cli); a bare kind (host) names the lab's only
+component of that kind. Selectors: locked, deployed, latest-release, 0.20.0, release:owner/repo@tag,
+git:<repo>@<ref>. A run tries other versions without touching the lock: product-lab test --candidate host@latest-release.`;
+export function parseCandidates(values) {
+    const candidates = {};
+    for (const value of values ?? []) {
+        const at = value.indexOf("@");
+        if (at <= 0 || at === value.length - 1)
+            throw new Error(`--candidate takes <component>@<selector> (for example host:truapi-cli@latest-release), not ${value}`);
+        candidates[value.slice(0, at)] = value.slice(at + 1);
+    }
+    return candidates;
+}
+export function componentId(argument, known) {
+    if (argument.includes(":"))
+        return argument;
+    const matching = known.filter((id) => id.startsWith(`${argument}:`));
+    if (matching.length === 1)
+        return matching[0];
+    throw new Error(matching.length
+        ? `${argument} is ambiguous: the lab has ${matching.join(", ")}; name one`
+        : `The lab has no ${argument} component (known: ${known.join(", ") || "none"}); name it as <kind>:<name>`);
+}
+export async function resolveCandidates(runtime, values) {
+    const candidates = parseCandidates(values);
+    if (!Object.keys(candidates).length)
+        return candidates;
+    const known = (await runtime.versions()).components.map((row) => row.id);
+    return Object.fromEntries(Object.entries(candidates).map(([component, selector]) => [componentId(component, known), selector]));
+}
+const selectorText = (selector) => (selector === undefined ? "-" : typeof selector === "string" ? selector : JSON.stringify(selector));
+function renderVersions(report, out) {
+    out(`Lock: ${report.lock.location} (${report.lock.present ? report.lock.digest : "none"})`);
+    if (!report.components.length) {
+        out("The lab selects no versions and the lock is empty; declare defineLab({ versions: { policy } }).");
+        return;
+    }
+    for (const row of report.components) {
+        const locked = row.locked ? `${row.locked.version} (${sourceText(row.locked.source)})` : "-";
+        let line = `${row.id.padEnd(24)} ${selectorText(row.selector).padEnd(16)} ${locked.padEnd(48)} ${row.status}`;
+        if (row.available)
+            line += "error" in row.available
+                ? `; ${selectorText(row.available.selector)}: ${row.available.error}`
+                : `; ${selectorText(row.available.selector)} gives ${row.available.version}${row.available.sameAsLocked === undefined ? "" : row.available.sameAsLocked ? " (the locked artifact)" : " (differs from the lock)"}`;
+        out(line);
+    }
+}
+function sourceText(source) {
+    if (source.type === "github-release")
+        return `${source.repository}@${source.tag}`;
+    if (source.type === "git")
+        return `${source.repository}@${String(source.commit).slice(0, 12)}`;
+    if (source.type === "network")
+        return `${source.network}/${source.chain} #${source.block.number}`;
+    if (source.type === "npm")
+        return `npm ${String(source.package)}`;
+    return source.type;
+}
+function renderProposal(report, out) {
+    if (report.status === "refused") {
+        out(`Refused (${report.refusal.code})${report.refusal.row ? `, row ${report.refusal.row}` : ""}: ${report.refusal.message}`);
+        out("Nothing was written.");
+        return;
+    }
+    out(report.title);
+    for (const item of report.promoted) {
+        out(`changed  ${item.id}: ${item.from.version} -> ${item.to.version} (selector ${selectorText(item.selector)}, ${item.observed === "matched" ? "observed by the run" : "not observed by the run"})`);
+        for (const [name, digest] of Object.entries(item.to.digests))
+            if (item.from.digests[name] !== digest)
+                out(`         ${name} ${item.from.digests[name] ?? "-"} -> ${digest}`);
+    }
+    for (const row of report.rows)
+        out(`${row.role.padEnd(9)} ${row.id}: run ${row.runId}, ${row.scenarios} scenario(s) passed, receipt ${row.receipt.sha256}`);
+    out(report.lock.written
+        ? `Lock ${report.lock.location}: ${report.lock.before} -> ${report.lock.after}; written`
+        : `Lock ${report.lock.location}: ${report.lock.before}; dry run, nothing written (--write to write it)`);
+}
+function renderWrite(report, out) {
+    for (const change of report.changes) {
+        const from = change.from ? change.from.version : "-";
+        const to = change.to ? change.to.version : "-";
+        out(`${change.change.padEnd(8)} ${change.id}: ${from} -> ${to}`);
+        for (const [name, digest] of Object.entries(change.to?.digests ?? {}))
+            if (change.from?.digests[name] !== digest)
+                out(`         ${name} ${change.from?.digests[name] ?? "-"} -> ${digest}`);
+    }
+    out(`Lock ${report.location}: ${report.before ?? "none"} -> ${report.after}; ${report.written ? "written" : "unchanged (nothing to write)"}`);
+}
+export async function runVersionsCommand(runtime, argv, out = (line) => console.log(line)) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        strict: true,
+        options: {
+            help: { type: "boolean", short: "h" },
+            config: { type: "string" },
+            available: { type: "boolean" },
+            json: { type: "boolean" },
+            to: { type: "string" },
+            from: { type: "string" },
+            row: { type: "string" },
+            control: { type: "string" },
+            write: { type: "boolean" },
+            "dry-run": { type: "boolean" },
+            body: { type: "string" },
+        },
+    });
+    if (values.help) {
+        out(VERSIONS_USAGE);
+        return 0;
+    }
+    const [sub, ...rest] = positionals;
+    await runtime.load();
+    const json = (value) => out(JSON.stringify(value, null, 2));
+    const known = async () => (await runtime.versions()).components.map((row) => row.id);
+    if (sub === undefined) {
+        const report = await runtime.versions({ ...(values.available ? { available: true } : {}) });
+        if (values.json)
+            json(report);
+        else
+            renderVersions(report, out);
+        return 0;
+    }
+    if (sub === "update") {
+        const ids = rest.length ? await known() : [];
+        const report = await runtime.updateLock({
+            ...(rest.length ? { components: rest.map((argument) => componentId(argument, ids)) } : {}),
+            ...(values.to ? { to: values.to } : {}),
+        });
+        if (values.json)
+            json(report);
+        else
+            renderWrite(report, out);
+        return 0;
+    }
+    if (sub === "pin") {
+        if (rest.length !== 2)
+            throw new Error(`versions pin takes <component> <version>\n${VERSIONS_USAGE}`);
+        const report = await runtime.pinVersion({ component: componentId(rest[0], await known()), version: rest[1] });
+        if (values.json)
+            json(report);
+        else
+            renderWrite(report, out);
+        return 0;
+    }
+    if (sub === "verify") {
+        const report = await runtime.verifyLock();
+        if (values.json)
+            json(report);
+        else {
+            out(`Lock ${report.location}: ${report.present ? report.digest : "none"}`);
+            for (const row of report.components) {
+                out(`${row.id.padEnd(24)} ${row.status}${row.version ? ` ${row.version}` : ""}${row.reason ? `: ${row.reason}` : ""}`);
+                for (const item of row.mismatched ?? [])
+                    out(`  ${item.name}: expected ${item.expected}, actual ${item.actual}`);
+                for (const note of row.notes ?? [])
+                    out(`  note: ${note}`);
+            }
+            out(report.ok ? "verified" : report.failed ? "FAILED" : "not verified (something could not be fetched)");
+        }
+        return report.ok ? 0 : report.failed ? 1 : 2;
+    }
+    if (sub === "propose") {
+        if (rest.length || !values.from || !values.row || !values.control)
+            throw new Error(`versions propose takes --from <suite-dir> --row <candidate-row> --control <control-row>\n${VERSIONS_USAGE}`);
+        if (values.write && values["dry-run"])
+            throw new Error("versions propose: --write and --dry-run contradict each other; the default is a dry run");
+        const report = await runtime.proposeLock({ directory: resolve(values.from), candidate: values.row, control: values.control, ...(values.write ? { write: true } : {}) });
+        if (values.body && report.status === "proposed")
+            writeFileSync(resolve(values.body), report.body);
+        if (values.json)
+            json(report);
+        else {
+            renderProposal(report, out);
+            if (values.body && report.status === "proposed")
+                out(`Body: ${resolve(values.body)}`);
+        }
+        return report.status === "proposed" ? 0 : 1;
+    }
+    throw new Error(`Unknown versions command ${sub}\n${VERSIONS_USAGE}`);
+}
+export async function resolveRunVersions(runtime, options, out = (line) => console.log(line), 
+plain = false) {
+    const lab = await runtime.load();
+    const declared = Object.keys(lab.catalog?.versions()?.policy ?? {}).length > 0;
+    if (!declared && !options.candidates?.length)
+        return {};
+    const candidates = await resolveCandidates(runtime, options.candidates);
+    const environment = options.environment ?? lab.defaultEnvironment;
+    const report = await runtime.resolveVersions({ ...(environment ? { environment } : {}), candidates });
+    const components = Object.entries(report.resolution.components).map(([id, item]) => `${id}=${item.resolved.version}${item.candidate ? " (candidate)" : ""}`);
+    if (plain) {
+        const versions = Object.entries(report.resolution.components).map(([id, item]) => `${id.replace(/^[a-z]+:/, "")} ${item.resolved.version}${item.candidate ? " (candidate)" : ""}`);
+        out(`Versions: ${versions.join(", ") || "none"} (lab.lock.json untouched)`);
+    }
+    else
+        out(`Versions: ${components.join(", ") || "none"}; workspace ${report.workspace}${report.manifest ? `; recorded in ${report.manifest}` : ""}; lock untouched`);
+    return report.manifest ? { PRODUCT_LAB_VERSIONS_RESOLUTION: report.manifest } : {};
+}

package/entrypoints/cli/src/what-if-command.d.ts

@@ -0,0 +1,7 @@
+import type { LabRuntime, WhatIfBranchReport, WhatIfReport } from "@parity/product-lab/ports/driving";
+export declare const WHAT_IF_USAGE = "Usage: product-lab what-if <feature> [--scenario <name>]... [--probe \"<assertion>\"]... [--environment <id>]\n                         [--report-dir <dir>] [--config lab.config.ts] [--json]\n\n\"What if\" branches: the feature's Background is the trunk and runs once; its state is saved, and each scenario (each\nExamples row of an outline) runs from that state as a branch, the state restored after it. At each branch's end every\ninvariant the lab's integrations declare is checked for every actor it knows, and each --probe. The branches are\ncompared: each one's result, checks and time, beside the trunk's one-time cost, and what differs between them.\nThe same file under `product-lab test` means the same thing (it runs the Background before every scenario).\nNeeds an environment that saves and restores its state (the local dev chain, fast, whose chain what-if keeps\nbetween starts, or a saved local copy); a public network is refused.\n  --scenario <name>     only this scenario (repeatable; an outline gives one branch per Examples row)\n  --probe \"<step>\"      an assertion step checked at every branch's end (repeatable), as \"Ada's list shows 2 notes\"\n  --environment <id>    the environment to start (default: the lab's default)\n  --report-dir <dir>    write report.json and report.md here (default: <lab>/.product-lab/what-if/<run>/)\n  --config <file|dir>   lab.config.ts (default: ./lab.config.ts)\n  --json                print the report as JSON\n  Exit code: 0 every branch ran (passed or failed: that is the comparison), 1 the trunk failed, a branch did not run\n  or plan, or the lab does not start; 2 a usage error.";
+/** A branch as the report names it: an outline row with its values. */
+export declare function branchLabel(branch: Pick<WhatIfBranchReport, "name" | "example">): string;
+/** The comparison as Markdown: the trunk's cost, one row per branch, the checks per branch, then what differs. */
+export declare function whatIfMarkdown(report: WhatIfReport): string;
+export declare function runWhatIfCommand(runtime: LabRuntime, argv: string[], signal: AbortSignal, out?: (text: string) => void): Promise<number>;