@parity/product-lab 0.0.1-placeholder → 0.1.0

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

@@ -0,0 +1,365 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { FixtureImportIncompleteError } from "@parity/product-lab/domain";
+import { FIXTURE_SHARING_USAGE, megabytes, runFixtureSharingCommand } from "./fixture-sharing-command.js";
+import { FIXTURE_SOURCE_USAGE, runFixtureSourceCommand } from "./fixture-source-command.js";
+import { FIXTURE_REFRESH_USAGE, runFixtureRefreshCommand } from "./fixture-refresh-command.js";
+import { fileSetupMarkers, unsavedSetupRefusal } from "./fixture-setup-marker.js";
+export const FIXTURE_USAGE = `Usage: product-lab fixture run <name> [feature...] [--config lab.config.ts] [--resave] [--no-sources] [--json <file>]
+       product-lab fixture save <name> [--fresh] [--config lab.config.ts] [--json <file>]
+       product-lab fixture list [--config lab.config.ts] [--json]
+       product-lab fixture delete <name> [--config lab.config.ts]
+${FIXTURE_SHARING_USAGE}
+${FIXTURE_SOURCE_USAGE}
+${FIXTURE_REFRESH_USAGE}
+
+A fixture is a saved state a scenario starts from (defineLab({ fixtures })): the environment's whole state and its
+session's identities after the fixture's setup feature passed, keyed by everything that invalidates it (the setup
+file, lab.lock.json, the declared inputs, each chain's runtime and the environment's state lineage).
+  run      Start the fixture's environment. A saved fixture whose key fits is restored (copy-on-write where the file
+           system supports it). With nothing saved, the lab's fixture sources (defineLab({ fixtureSources })) are
+           read first: a published bundle that fits this checkout and machine is downloaded, checked and imported, and
+           the features start from it; when none fits (each reason is printed) the setup feature runs and, when it
+           passes, the state is saved. --no-sources skips the sources.
+           A saved fixture whose key differs is refused with every reason and nothing runs (--resave runs the setup
+           on the running state and saves it again). Then each feature runs in this process with its actors bound to
+           the fixture's identities by name. The environment stops at the end.
+  save     Start the environment, run the setup feature and save the state (replacing an earlier save).
+           When an earlier setup of the fixture ran on the same state and was never saved (it or its save failed), the
+           setup is not run on it again: the refusal names --fresh, which resets the environment to its clean state
+           first (one that cannot be reset says so).
+  list     Declared fixtures and what is saved; nothing starts, so a saved fixture's key is checked only by run.
+  delete   Remove a saved fixture.
+  --json <file>  write what happened (timings, the fixture report, each feature run's result) as JSON
+  Exit code: 0 when everything passed; 1 on a refusal or a failed setup or feature; 2 on wrong arguments.`;
+function counts(record) {
+    const steps = record.scenarios.flatMap((scenario) => scenario.steps.filter((step) => !step.hidden));
+    const passed = steps.filter((step) => step.status === "passed").length;
+    return `${record.scenarios.length} scenario(s), ${steps.length} step(s) (${passed} passed)`;
+}
+async function runInProcess(runtime, root, path, bindings, out, fixtureSetup) {
+    const handle = await runtime.runFeatures({ paths: [path], inProcess: { bindings, ...(fixtureSetup !== undefined ? { fixtureSetup } : {}) }, label: "fixture", runsDirectory: join(root, ".product-lab", "fixture-runs") });
+    const stop = handle.onOutput((chunk) => out(chunk));
+    try {
+        return await handle.completion;
+    }
+    finally {
+        stop();
+    }
+}
+const seconds = (ms) => `${(ms / 1000).toFixed(1)} s`;
+function describe(report) {
+    const identities = report.identities.map((identity) => identity.name).join(", ") || "none";
+    const prepared = Object.entries(report.prepared ?? {}).map(([identity, character]) => `${identity} (${character})`);
+    return `${report.action} fixture ${report.name} in ${seconds(report.timings.totalMs)} (environment ${seconds(report.timings.environmentMs)}, ${report.copy.environment}; identities' state ${seconds(report.timings.sessionMs)}, ${report.copy.session.join("/") || "none"}); identities: ${identities}${prepared.length ? `; prepares ${prepared.join(", ")}` : ""}; lineage ${report.lineage}`;
+}
+export async function runFixtureCommand(runtime, argv, out = (text) => process.stdout.write(text), now = () => performance.now(), 
+markersOf = fileSetupMarkers, 
+signal = new AbortController().signal) {
+    const stop = () => void runtime.stopEnvironment({ interruptRun: true }).catch((error) => out(`Stopping the environment failed: ${error instanceof Error ? error.message : String(error)}\n`));
+    signal.addEventListener("abort", stop, { once: true });
+    try {
+        return await fixtureCommand(runtime, argv, out, now, markersOf);
+    }
+    finally {
+        signal.removeEventListener("abort", stop);
+    }
+}
+async function fixtureCommand(runtime, argv, out, now, markersOf) {
+    if (["export", "inspect", "import"].includes(argv[0] ?? "") && !argv.includes("--help") && !argv.includes("-h"))
+        return runFixtureSharingCommand(runtime, argv, out, now);
+    if (["sources", "pull", "push"].includes(argv[0] ?? "") && !argv.includes("--help") && !argv.includes("-h"))
+        return runFixtureSourceCommand(runtime, argv, out, now);
+    if (["check", "refresh"].includes(argv[0] ?? "") && !argv.includes("--help") && !argv.includes("-h"))
+        return runFixtureRefreshCommand(runtime, argv, out, now, markersOf);
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                help: { type: "boolean", short: "h" },
+                config: { type: "string" },
+                resave: { type: "boolean" },
+                fresh: { type: "boolean" },
+                "no-sources": { type: "boolean" },
+                json: { type: "string" },
+            },
+        });
+    }
+    catch (error) {
+        out(`${error instanceof Error ? error.message : String(error)}\n${FIXTURE_USAGE}\n`);
+        return 2;
+    }
+    const { values, positionals } = parsed;
+    const [action, name, ...given] = positionals;
+    if (values.help || !action) {
+        out(`${FIXTURE_USAGE}\n`);
+        return values.help ? 0 : 2;
+    }
+    const lab = await runtime.load();
+    if (action === "list") {
+        const statuses = await runtime.fixtures();
+        if (values.json !== undefined)
+            out(`${JSON.stringify(statuses, null, 2)}\n`);
+        else if (!statuses.length)
+            out("The lab declares no fixtures (defineLab({ fixtures })).\n");
+        else
+            for (const status of statuses)
+                out(`${line(status)}\n`);
+        return 0;
+    }
+    if (!name || !["run", "save", "delete"].includes(action)) {
+        out(`${FIXTURE_USAGE}\n`);
+        return 2;
+    }
+    const features = given.map((path) => {
+        const inside = relative(lab.root, resolve(path));
+        return isAbsolute(path) || (!inside.startsWith("..") && inside !== path && !isAbsolute(inside)) ? inside : path;
+    });
+    const declared = (await runtime.fixtures()).find((status) => status.name === name);
+    if (!declared) {
+        out(`The lab declares no fixture ${name}.\n`);
+        return 1;
+    }
+    if (action === "delete") {
+        const removed = await runtime.deleteFixture({ name });
+        out(removed ? `Deleted the saved fixture ${name}.\n` : `Nothing was saved for fixture ${name}.\n`);
+        return 0;
+    }
+    const markers = markersOf(lab.root);
+    const summary = { fixture: name, environment: declared.environment, timings: {}, features: [] };
+    const write = () => {
+        if (values.json)
+            writeFileSync(resolve(values.json), JSON.stringify(summary, null, 2) + "\n");
+    };
+    const started = now();
+    const time = async (label, work) => {
+        const from = now();
+        try {
+            return await work();
+        }
+        finally {
+            summary.timings[label] = Math.round(now() - from);
+        }
+    };
+    const fromSources = async () => {
+        const sharing = runtime.fixtureSharing();
+        const sources = sharing.fixtureSources();
+        if (!sources.length)
+            return undefined;
+        out(`Nothing is saved for fixture ${name} here; looking for a published bundle that fits this checkout in ${sources.map((source) => `${source.id} (${source.location})`).join(", ")}\n`);
+        const unused = (reasons, then) => {
+            summary.shared = { used: false, reasons };
+            out(`No published bundle is used:\n${reasons.map((reason) => `- ${reason}`).join("\n")}\n${then}\n`);
+        };
+        const reasonsOf = (error) => {
+            const reasons = error.reasons;
+            return Array.isArray(reasons) ? reasons.map(String) : [error instanceof Error ? error.message : String(error)];
+        };
+        let download;
+        try {
+            download = await time("downloadMs", () => sharing.downloadFixture({ name }));
+        }
+        catch (error) {
+            unused(reasonsOf(error), "The setup runs instead.");
+            return undefined;
+        }
+        out(`Published bundle from ${download.source.id} (${download.source.location}): ${download.published.index}, saved ${download.published.createdAt}, ${download.published.parts} part(s), ${megabytes(download.published.bytes)}; ${download.cached ? "already in the cache, checked" : "copied and checked"} in ${seconds(download.ms)}\n`);
+        for (const reason of download.skipped)
+            out(`  skipped ${reason}\n`);
+        out(`Starting environment ${declared.environment} for the import\n`);
+        const started = await time("environmentStartMs", () => runtime.startFromFixture({ fixture: name, environment: declared.environment, importing: true, keep: true }));
+        out(`Environment ${declared.environment} ready in ${seconds(summary.timings.environmentStartMs)}\n`);
+        if (started.status.state !== "missing")
+            return { status: started.status, ...(started.restored ? { report: started.restored } : {}) };
+        try {
+            const result = await time("importMs", () => sharing.importFixture({ index: download.index, confirmation: runtime.snapshot().confirmations.restoreFixture }));
+            out(`Imported fixture ${name} in ${seconds(summary.timings.importMs)}: checked and unpacked ${result.files} files (${megabytes(result.compressedBytes)} compressed) in ${seconds(result.unpackMs)}, adopted in ${seconds(result.restored.timings.totalMs)} (environment ${seconds(result.restored.timings.environmentMs)}); identities: ${result.restored.identities.map((identity) => identity.name).join(", ") || "none"}; lineage ${result.lineage}\n`);
+            for (const line of result.remapped)
+                out(`  ${line}\n`);
+            const status = (await runtime.fixtures()).find((item) => item.name === name);
+            summary.shared = { used: true, source: download.source.id, index: download.index };
+            if (status.state !== "fits")
+                throw Object.assign(new Error(`The imported bundle of ${name} does not fit the running environment, so nothing was run:\n${(status.reasons ?? []).map((reason) => `- ${reason}`).join("\n")}\nBuild it here with product-lab fixture save ${name} --fresh.`), { reasons: status.reasons ?? [] });
+            return { status, report: result.restored };
+        }
+        catch (error) {
+            if (summary.shared?.used)
+                throw error;
+            if (error instanceof FixtureImportIncompleteError) {
+                const reasons = reasonsOf(error.cause ?? error);
+                summary.shared = { used: false, reasons };
+                throw Object.assign(new Error(`The published bundle of ${name} could not be imported, and the environment may hold part of its state, so the setup was not run on it:\n${reasons.map((reason) => `- ${reason}`).join("\n")}\nRun the command again to import it again, or build the fixture here with product-lab fixture save ${name} --fresh.`), { reasons });
+            }
+            unused(reasonsOf(error), "The environment is started again and the setup runs instead.");
+            await runtime.stopEnvironment({ interruptRun: true });
+            return undefined;
+        }
+    };
+    const execute = async () => {
+        let code = 0;
+        try {
+            let report;
+            let status;
+            let imported = false;
+            if (action === "run") {
+                const shared = declared.state === "missing" && declared.setup && !values.resave && !values["no-sources"] ? await fromSources() : undefined;
+                if (shared) {
+                    status = shared.status;
+                    report = shared.report;
+                    imported = shared.report !== undefined;
+                }
+                else {
+                    out(`Starting environment ${declared.environment}\n`);
+                    const started = await time("environmentStartMs", () => runtime.startFromFixture({ fixture: name, environment: declared.environment, keep: true }));
+                    status = started.status;
+                    report = started.restored;
+                }
+            }
+            else {
+                out(`Starting environment ${declared.environment}\n`);
+                await time("environmentStartMs", () => runtime.startEnvironment({ environment: declared.environment, keep: true }));
+                status = (await runtime.fixtures()).find((item) => item.name === name);
+            }
+            if (!imported)
+                out(`Environment ${declared.environment} ready in ${seconds(summary.timings.environmentStartMs)}${report ? `, fixture ${name} restored in ${seconds(report.timings.totalMs)}` : ""}\n`);
+            if (status.state === "unsupported") {
+                summary.action = "refused";
+                summary.refused = status.reasons ?? [];
+                out(`Fixture ${name} cannot be saved or restored here:\n${(status.reasons ?? []).map((reason) => `- ${reason}`).join("\n")}\n`);
+                return 1;
+            }
+            if (action === "run" && report && imported) {
+                summary.action = "imported";
+                markers.clearOf(declared.environment);
+            }
+            else if (action === "run" && report) {
+                summary.action = "restored";
+                summary.timings.restoreMs = report.timings.totalMs;
+                markers.clearOf(declared.environment);
+                out(`${describe(report)}\n`);
+            }
+            else if (action === "run" && status.state === "stale" && !values.resave) {
+                summary.action = "refused";
+                summary.refused = status.reasons ?? [];
+                out(`Fixture ${name} is saved but does not fit, so nothing was restored or run:\n${(status.reasons ?? []).map((reason) => `- ${reason}`).join("\n")}\nRun its setup again with --resave (on the running state), or delete it.\n`);
+                return 1;
+            }
+            else if (!status.setup) {
+                summary.action = "refused";
+                summary.refused = status.reasons ?? [`nothing is saved under ${name}`];
+                out(`Fixture ${name} was saved from the running state and has no setup to run again; ${status.state === "stale" ? `it does not fit:\n${(status.reasons ?? []).map((reason) => `- ${reason}`).join("\n")}\nSave the state again in the lab, or delete it.` : "nothing is saved under that name."}\n`);
+                return 1;
+            }
+            else {
+                const setupPath = status.setup;
+                if (action === "save" && values.fresh) {
+                    const { reset, resetUnsupported } = runtime.snapshot().capabilities;
+                    if (!reset) {
+                        summary.action = "refused";
+                        summary.refused = [`environment ${declared.environment} cannot be reset${resetUnsupported ? `: ${resetUnsupported}` : ""}`];
+                        out(`--fresh resets the environment to its clean state, and environment ${declared.environment} offers no reset${resetUnsupported ? ` (${resetUnsupported})` : ""}. Nothing was changed. Remove its saved state by hand, or build the fixture on an environment that can be reset.\n`);
+                        return 1;
+                    }
+                    out(`Resetting environment ${declared.environment} to its clean state (--fresh)\n`);
+                    await time("resetMs", () => runtime.resetEnvironment({ confirmation: runtime.snapshot().confirmations.reset }));
+                    markers.clearOf(declared.environment);
+                    out(`Environment ${declared.environment} reset in ${seconds(summary.timings.resetMs)}\n`);
+                }
+                let bindings = {};
+                if (status.from) {
+                    out(`Restoring fixture ${status.from}, which ${name} is built on\n`);
+                    const below = await time("baseRestoreMs", () => runtime.restoreFixture({ name: status.from, confirmation: runtime.snapshot().confirmations.restoreFixture }));
+                    markers.clearOf(declared.environment);
+                    bindings = below.bindings;
+                    out(`${describe(below)}\n`);
+                }
+                else if (action === "save" && values.fresh) {
+                }
+                else if (!values.resave) {
+                    const unsaved = markers.unsaved(name, runtime.snapshot().provenance);
+                    if (unsaved) {
+                        summary.action = "refused";
+                        summary.refused = [`an earlier setup of ${name} ran on this state (started ${unsaved.startedAt}) and was never saved`];
+                        out(unsavedSetupRefusal(unsaved));
+                        return 1;
+                    }
+                }
+                if (!status.from && !(action === "save" && values.fresh)) {
+                    const held = new Set((runtime.snapshot().actors ?? []).map((actor) => actor.name));
+                    const twice = Object.keys(status.saved?.prepared ?? {}).filter((identity) => held.has(identity));
+                    if (twice.length) {
+                        summary.action = "refused";
+                        summary.refused = [`the running state already holds ${twice.join(", ")}, which the setup of ${name} makes`];
+                        out(`The running state of environment ${declared.environment} already holds ${twice.join(", ")}, which the setup of fixture ${name} makes, so running it here would make ${twice.length === 1 ? "that identity" : "each of them"} a second time. Nothing was run.\n` +
+                            `Build it on a clean state with product-lab fixture save ${name} --fresh.\n`);
+                        return 1;
+                    }
+                }
+                out(`${status.state === "missing" ? "Nothing saved yet" : "Saving again"}: running the setup ${setupPath}\n`);
+                markers.mark({ fixture: name, environment: declared.environment, provenance: runtime.snapshot().provenance, startedAt: new Date().toISOString() });
+                const setup = await time("setupMs", () => runInProcess(runtime, lab.root, setupPath, bindings, out, name));
+                summary.setup = { status: setup.status, summary: counts(setup) };
+                out(`\nSetup ${setup.status}: ${counts(setup)} in ${seconds(summary.timings.setupMs)}\n`);
+                if (setup.status !== "passed") {
+                    out(`${setup.error ?? "The setup did not pass"}; nothing was saved. The environment keeps what the setup did: build it again with product-lab fixture save ${name} --fresh.\n`);
+                    return 1;
+                }
+                try {
+                    report = await time("saveMs", () => runtime.saveFixture({ name }));
+                }
+                catch (error) {
+                    out(`The setup passed, but saving its state failed; the environment keeps what the setup did: build it again with product-lab fixture save ${name} --fresh.\n`);
+                    throw error;
+                }
+                markers.clear(name);
+                summary.action = "saved";
+                out(`${describe(report)}\n`);
+            }
+            summary.report = report;
+            if (action === "run")
+                for (const feature of features) {
+                    const record = await time(`feature:${feature}`, () => runInProcess(runtime, lab.root, feature, report.bindings, out));
+                    summary.features.push({ path: feature, status: record.status, summary: counts(record), ...(record.error ? { error: record.error } : {}) });
+                    out(`\n${feature}: ${record.status}, ${counts(record)} in ${seconds(summary.timings[`feature:${feature}`])}\n`);
+                    if (record.status !== "passed")
+                        code = 1;
+                }
+            return code;
+        }
+        catch (error) {
+            const reasons = error.reasons;
+            if (Array.isArray(reasons)) {
+                summary.action = "refused";
+                summary.refused = reasons.map(String);
+            }
+            out(`${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
+    };
+    let code = await execute();
+    try {
+        await time("environmentStopMs", () => runtime.stopEnvironment({ interruptRun: true }));
+    }
+    catch (error) {
+        out(`Stopping the environment failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        code = 1;
+    }
+    summary.timings.totalMs = Math.round(now() - started);
+    out(`Total ${seconds(summary.timings.totalMs)} (exit ${code})\n`);
+    write();
+    return code;
+}
+function line(status) {
+    const saved = status.saved ? `saved ${status.saved.createdAt}, ${status.saved.identities} identities, lineage ${status.saved.lineage}` : "nothing saved";
+    const reasons = status.reasons?.length ? `\n    ${status.reasons.join("\n    ")}` : "";
+    const prepared = Object.entries(status.saved?.prepared ?? {});
+    const characters = prepared.length ? `\n    prepares ${prepared.map(([identity, character]) => `${identity} (${character})`).join(", ")}` : "";
+    const origin = status.setup ? `setup ${status.setup}` : "saved from the running state";
+    return `${status.name} (${status.environment}, ${origin}): ${status.state}; ${saved}${characters}${reasons}`;
+}

package/entrypoints/cli/src/fixture-refresh-command.d.ts

@@ -0,0 +1,11 @@
+import type { FixtureCheck, LabRuntime } from "@parity/product-lab/ports/driving";
+import { type SetupMarkers } from "./fixture-setup-marker.js";
+export declare const FIXTURE_REFRESH_USAGE = "       product-lab fixture check [--config lab.config.ts] [--json <file>]\n       product-lab fixture refresh <name> [--rebuild] [--config lab.config.ts] [--json <file>]\n\n  check    Each declared fixture against this checkout: missing, fits-checkout (its setup, lab.lock.json and declared\n           inputs are this checkout's; its runtimes and lineage are checked when its environment runs), or stale with\n           every reason. Starts nothing. Exit 1 when one is stale or missing (a nightly job refreshes those). Each also\n           gets a cache key (--json: cacheKey): the sha256 of the parts this checkout decides, for a CI cache (backlog 1d).\n  refresh  Bring saved fixture <name> up to date. When its checkout parts fit, start its environment: a fixture that\n           fits is left alone; one whose runtimes alone differ is restored and upgraded in place where the environment\n           can (Engine: each chain's own upgrade, code hash and migrations checked), then saved again under its new\n           key with an \"upgraded\" history entry. Otherwise (a changed setup, lock or input, another lineage, or an\n           environment that cannot upgrade in place, such as the local dev chain) it is rebuilt: an environment that can be\n           reset is started and reset to its clean state (chain and identities together); one that cannot has its\n           session directories set aside before it starts (deleted once the new fixture is saved, put back when the\n           rebuild fails). A fixture built on another (its \"from\") is rebuilt on that fixture's restored state, its\n           identities bound, as fixture save builds it. Then the setup runs and the state is saved with a \"rebuilt\"\n           entry naming why.\n           --rebuild rebuilds whatever the state.";
+/**
+ * The key a CI cache keeps a fixture's bundle under (backlog 1d): the sha256 of its name, its environment and the parts
+ * of its key this checkout decides (setup, lab.lock.json, declared inputs, the fixtures it is built on). A change to any
+ * of them is another key, so the cache misses and the fixture is built again; its runtimes and lineage are checked when
+ * the bundle is imported.
+ */
+export declare function fixtureCacheKey(check: Pick<FixtureCheck, "name" | "environment" | "checkout">): string | undefined;
+export declare function runFixtureRefreshCommand(runtime: LabRuntime, argv: string[], out: (text: string) => void, now: () => number, markersOf?: (root: string) => SetupMarkers): Promise<number>;

package/entrypoints/cli/src/fixture-refresh-command.js

@@ -0,0 +1,245 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { fileSetupMarkers } from "./fixture-setup-marker.js";
+export const FIXTURE_REFRESH_USAGE = `       product-lab fixture check [--config lab.config.ts] [--json <file>]
+       product-lab fixture refresh <name> [--rebuild] [--config lab.config.ts] [--json <file>]
+
+  check    Each declared fixture against this checkout: missing, fits-checkout (its setup, lab.lock.json and declared
+           inputs are this checkout's; its runtimes and lineage are checked when its environment runs), or stale with
+           every reason. Starts nothing. Exit 1 when one is stale or missing (a nightly job refreshes those). Each also
+           gets a cache key (--json: cacheKey): the sha256 of the parts this checkout decides, for a CI cache (backlog 1d).
+  refresh  Bring saved fixture <name> up to date. When its checkout parts fit, start its environment: a fixture that
+           fits is left alone; one whose runtimes alone differ is restored and upgraded in place where the environment
+           can (Engine: each chain's own upgrade, code hash and migrations checked), then saved again under its new
+           key with an "upgraded" history entry. Otherwise (a changed setup, lock or input, another lineage, or an
+           environment that cannot upgrade in place, such as the local dev chain) it is rebuilt: an environment that can be
+           reset is started and reset to its clean state (chain and identities together); one that cannot has its
+           session directories set aside before it starts (deleted once the new fixture is saved, put back when the
+           rebuild fails). A fixture built on another (its "from") is rebuilt on that fixture's restored state, its
+           identities bound, as fixture save builds it. Then the setup runs and the state is saved with a "rebuilt"
+           entry naming why.
+           --rebuild rebuilds whatever the state.`;
+const seconds = (ms) => `${(ms / 1000).toFixed(1)} s`;
+function counts(record) {
+    const steps = record.scenarios.flatMap((scenario) => scenario.steps.filter((step) => !step.hidden));
+    return `${record.scenarios.length} scenario(s), ${steps.length} step(s) (${steps.filter((step) => step.status === "passed").length} passed)`;
+}
+export function fixtureCacheKey(check) {
+    if (!check.checkout)
+        return undefined;
+    return createHash("sha256").update(JSON.stringify({ fixture: check.name, environment: check.environment, checkout: check.checkout })).digest("hex");
+}
+function describeCheck(check) {
+    const saved = check.saved ? `saved ${check.saved.createdAt}${check.saved.history.length ? `, ${check.saved.history.map((entry) => `${entry.action} ${entry.at}`).join(", ")}` : ""}` : "nothing saved";
+    const key = fixtureCacheKey(check);
+    return `${check.name} (${check.environment}): ${check.state}; ${saved}${key ? `; cache key ${key}` : ""}${check.reasons.map((reason) => `\n    ${reason}`).join("")}`;
+}
+export async function runFixtureRefreshCommand(runtime, argv, out, now, markersOf = fileSetupMarkers) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, allowPositionals: true, strict: true, options: { config: { type: "string" }, rebuild: { type: "boolean" }, json: { type: "string" } } });
+    }
+    catch (error) {
+        out(`${error instanceof Error ? error.message : String(error)}\n${FIXTURE_REFRESH_USAGE}\n`);
+        return 2;
+    }
+    const { values, positionals } = parsed;
+    const [action, name] = positionals;
+    if ((action === "refresh" && !name) || (action === "check" && values.rebuild)) {
+        out(`${FIXTURE_REFRESH_USAGE}\n`);
+        return 2;
+    }
+    const json = values.json !== undefined ? resolve(values.json) : undefined;
+    const write = (value) => {
+        if (json)
+            writeFileSync(json, JSON.stringify(value, null, 2) + "\n");
+    };
+    const lab = await runtime.load();
+    const maintenance = runtime.fixtureMaintenance();
+    let checks;
+    try {
+        checks = await maintenance.check();
+    }
+    catch (error) {
+        out(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    if (action === "check") {
+        write(checks.map((check) => ({ ...check, ...(fixtureCacheKey(check) ? { cacheKey: fixtureCacheKey(check) } : {}) })));
+        if (!checks.length)
+            out("The lab declares no fixtures (defineLab({ fixtures })).\n");
+        for (const check of checks)
+            out(`${describeCheck(check)}\n`);
+        const due = checks.filter((check) => check.state !== "fits-checkout");
+        if (due.length)
+            out(`${due.length} fixture(s) to refresh: ${due.map((check) => `product-lab fixture refresh ${check.name}`).join("; ")}\n`);
+        return due.length ? 1 : 0;
+    }
+    const check = checks.find((item) => item.name === name);
+    if (!check) {
+        out(`The lab declares no fixture ${JSON.stringify(name)}.\n`);
+        return 1;
+    }
+    out(`${describeCheck(check)}\n`);
+    const summary = { fixture: name, environment: check.environment, check, timings: {} };
+    const timings = summary.timings;
+    const started = now();
+    const finish = (code) => {
+        timings.totalMs = Math.round(now() - started);
+        out(`Total ${seconds(timings.totalMs)} (exit ${code})\n`);
+        write(summary);
+        return code;
+    };
+    const start = async () => {
+        out(`Starting environment ${check.environment}\n`);
+        const from = now();
+        await runtime.startEnvironment({ environment: check.environment, keep: true });
+        timings.environmentStartMs = Math.round(now() - from);
+        out(`Environment ${check.environment} ready in ${seconds(timings.environmentStartMs)}\n`);
+    };
+    const stop = async () => {
+        const from = now();
+        await runtime.stopEnvironment({ interruptRun: true });
+        timings.environmentStopMs = Math.round(now() - from);
+    };
+    let reasons = values.rebuild ? ["a rebuild was asked (--rebuild)", ...check.reasons] : check.state === "missing" ? ["nothing was saved yet"] : check.reasons;
+    if (!values.rebuild && check.state === "fits-checkout") {
+        try {
+            await start();
+            const plan = await maintenance.plan(name);
+            summary.plan = plan;
+            if (plan.kind === "fits") {
+                out(`Fixture ${name} fits the running environment: nothing to refresh.\n`);
+                await stop();
+                return finish(0);
+            }
+            if (plan.kind === "upgrade") {
+                out(`Fixture ${name} differs in its runtimes only; upgrading it in place:\n${plan.reasons.map((reason) => `- ${reason}`).join("\n")}\n`);
+                const from = now();
+                const report = await maintenance.upgrade({ name: name, confirmation: runtime.snapshot().confirmations.restoreFixture });
+                timings.upgradeMs = Math.round(now() - from);
+                summary.action = "upgraded";
+                summary.report = report;
+                for (const entry of report.upgrade.upgraded)
+                    out(`  ${entry.chain}: ${entry.from.spec} → ${entry.to.spec} (code ${entry.to.codeHash.slice(0, 10)}…${entry.migrated ? ", migrations ran" : ", migrations did NOT run"})\n`);
+                out(`Upgraded fixture ${name} in place (restore ${seconds(report.timings.restoreMs)}, upgrade ${seconds(report.timings.upgradeMs)}) and saved it under its new key; lineage ${report.report.lineage}.\n`);
+                await stop();
+                return finish(0);
+            }
+            reasons = plan.kind === "rebuild" ? [...plan.reasons, ...plan.why] : ["nothing is saved"];
+            out(`Fixture ${name} is rebuilt:\n${reasons.map((reason) => `- ${reason}`).join("\n")}\n`);
+            await stop();
+        }
+        catch (error) {
+            summary.failed = error instanceof Error ? error.message : String(error);
+            out(`${summary.failed}\n`);
+            await stop().catch((failure) => out(`Stopping the environment failed: ${failure instanceof Error ? failure.message : String(failure)}\n`));
+            return finish(1);
+        }
+    }
+    return finish(await rebuild(runtime, { name: name, environment: check.environment, root: lab.root, reasons, summary, start, stop, out, now, markers: markersOf(lab.root) }));
+}
+async function rebuild(runtime, context) {
+    const { name, out, summary } = context;
+    const timings = summary.timings;
+    let aside = { directories: [], commit: () => { }, rollback: () => { } };
+    let saved = false;
+    let reset = false;
+    let bindings = {};
+    try {
+        const status = (await runtime.fixtures()).find((item) => item.name === name);
+        if (status?.from) {
+            await context.start();
+            out(`Restoring fixture ${status.from}, which ${name} is built on\n`);
+            const from = context.now();
+            const below = await runtime.restoreFixture({ name: status.from, confirmation: runtime.snapshot().confirmations.restoreFixture });
+            timings.baseRestoreMs = Math.round(context.now() - from);
+            context.markers.clearOf(context.environment);
+            bindings = below.bindings;
+            summary.base = status.from;
+            out(`Restored ${status.from} in ${seconds(timings.baseRestoreMs)}\n`);
+        }
+        else {
+            let running = false;
+            try {
+                await context.start();
+                running = true;
+            }
+            catch (error) {
+                out(`The environment did not start on its saved state (${error instanceof Error ? error.message.split("\n")[0] : String(error)}); rebuilding from a fresh session\n`);
+            }
+            if (running && runtime.snapshot().capabilities.reset) {
+                out(`Resetting environment ${context.environment} to its clean state for the rebuild\n`);
+                const from = context.now();
+                await runtime.resetEnvironment({ confirmation: runtime.snapshot().confirmations.reset });
+                timings.resetMs = Math.round(context.now() - from);
+                reset = true;
+                context.markers.clearOf(context.environment);
+                out(`Environment ${context.environment} reset in ${seconds(timings.resetMs)}\n`);
+            }
+            else {
+                if (running)
+                    await context.stop();
+                aside = await runtime.fixtureMaintenance().prepareRebuild(name);
+                if (aside.directories.length)
+                    out(`Set aside for a fresh session (put back if the rebuild fails): ${aside.directories.join(", ")}\n`);
+                await context.start();
+            }
+        }
+        summary.setAside = aside.directories;
+        summary.reset = reset;
+        const setup = status?.setup;
+        if (!setup)
+            throw new Error(`Fixture ${name} has no setup to run: it was saved from the running state, so nothing rebuilds it`);
+        out(`Running the setup ${setup}\n`);
+        context.markers.mark({ fixture: name, environment: context.environment, provenance: runtime.snapshot().provenance, startedAt: new Date().toISOString() });
+        const from = context.now();
+        const handle = await runtime.runFeatures({ paths: [setup], inProcess: { bindings }, label: "fixture", runsDirectory: join(context.root, ".product-lab", "fixture-runs") });
+        const detach = handle.onOutput((chunk) => out(chunk));
+        let record;
+        try {
+            record = await handle.completion;
+        }
+        finally {
+            detach();
+        }
+        timings.setupMs = Math.round(context.now() - from);
+        summary.setup = { status: record.status, summary: counts(record) };
+        out(`\nSetup ${record.status}: ${counts(record)} in ${seconds(timings.setupMs)}\n`);
+        if (record.status !== "passed")
+            throw new Error(`${record.error ?? "The setup did not pass"}; nothing was saved.`);
+        const saving = context.now();
+        const report = await runtime.fixtureMaintenance().saveRebuilt({ name, reasons: context.reasons });
+        timings.saveMs = Math.round(context.now() - saving);
+        saved = true;
+        context.markers.clear(name);
+        aside.commit();
+        summary.action = "rebuilt";
+        summary.report = report;
+        out(`Rebuilt fixture ${name} and saved it (${seconds(report.timings.totalMs)}); identities: ${report.identities.map((identity) => identity.name).join(", ") || "none"}; lineage ${report.lineage}.\n`);
+    }
+    catch (error) {
+        summary.failed = error instanceof Error ? error.message : String(error);
+        out(`${summary.failed}\n`);
+        if (reset)
+            out(`The environment was reset for the rebuild and keeps what the setup did; the fixture saved before is untouched. Build it again with product-lab fixture save ${name} --fresh.\n`);
+    }
+    let code = saved ? 0 : 1;
+    try {
+        await context.stop();
+    }
+    catch (error) {
+        out(`Stopping the environment failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        code = 1;
+    }
+    if (!saved) {
+        aside.rollback();
+        if (aside.directories.length)
+            out("The session directories set aside are back as they were.\n");
+    }
+    return code;
+}

package/entrypoints/cli/src/fixture-setup-marker.d.ts

@@ -0,0 +1,22 @@
+export interface SetupMarker {
+    fixture: string;
+    environment: string;
+    /** The running environment's provenance when the setup began (`LabSnapshot.provenance`). */
+    provenance: Record<string, unknown>;
+    startedAt: string;
+}
+/** Where the fixture commands keep their unsaved-setup markers. */
+export interface SetupMarkers {
+    /** The unsaved setup of `fixture` recorded for exactly this environment state, if any. */
+    unsaved(fixture: string, provenance: Record<string, unknown>): SetupMarker | undefined;
+    /** Record that a fixture's setup is about to change this environment state. */
+    mark(marker: SetupMarker): void;
+    /** The setup's state was saved: nothing is unsaved any more. */
+    clear(fixture: string): void;
+    /** The environment's state was replaced (a restore, an import, a reset): no setup's unsaved state is left on it. */
+    clearOf(environment: string): void;
+}
+/** Markers as files beside the fixture runs of the lab at `root` (`.product-lab/fixture-runs/<fixture>.setup-unsaved.json`). */
+export declare function fileSetupMarkers(root: string): SetupMarkers;
+/** What a refused retry prints: what happened and the one command that cleans the state. */
+export declare function unsavedSetupRefusal(marker: SetupMarker): string;