@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/cli/src/fixture-setup-marker.js

@@ -0,0 +1,52 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const directory = (root) => join(root, ".product-lab", "fixture-runs");
+const file = (root, fixture) => join(directory(root), `${fixture}.setup-unsaved.json`);
+function read(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    return JSON.parse(text);
+}
+export function fileSetupMarkers(root) {
+    return {
+        unsaved(fixture, provenance) {
+            const marker = read(file(root, fixture));
+            return marker && JSON.stringify(marker.provenance) === JSON.stringify(provenance) ? marker : undefined;
+        },
+        mark(marker) {
+            mkdirSync(directory(root), { recursive: true });
+            writeFileSync(file(root, marker.fixture), JSON.stringify(marker, null, 2) + "\n");
+        },
+        clear(fixture) {
+            rmSync(file(root, fixture), { force: true });
+        },
+        clearOf(environment) {
+            let names;
+            try {
+                names = readdirSync(directory(root));
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return;
+                throw error;
+            }
+            for (const name of names)
+                if (name.endsWith(".setup-unsaved.json") && read(join(directory(root), name))?.environment === environment)
+                    rmSync(join(directory(root), name), { force: true });
+        },
+    };
+}
+export function unsavedSetupRefusal(marker) {
+    return (`An earlier setup of fixture ${marker.fixture} ran on this state of environment ${marker.environment} (started ${marker.startedAt}) and the state was never saved: the setup or the save failed. ` +
+        "Running the setup on that state again would repeat what it already did (its identities would exist twice), so nothing was run.\n" +
+        `Reset the environment to its clean state and build the fixture again with:\n  product-lab fixture save ${marker.fixture} --fresh\n`);
+}

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

@@ -0,0 +1,16 @@
+import type { LabRuntime } from "@parity/product-lab/ports/driving";
+export declare const FIXTURE_SHARING_USAGE = "       product-lab fixture export <name> [--out <file>] [--part-size <size>] [--level <n>] [--config lab.config.ts] [--json <file>]\n       product-lab fixture inspect <index> [--config lab.config.ts] [--json <file>]\n       product-lab fixture import <index> [--config lab.config.ts] [--json <file>]\n\n  export   Write saved fixture <name> as one bundle: <file> (default ./<name>.fixture.json), the index, and its parts\n           beside it (<name>.fixture.tar.zst.001, \u2026): a zstd-compressed tar of the record, the environment's state and\n           the identities' wallets and host state, cut into parts of at most --part-size (default 1.9G, below GitHub's\n           2 GiB release asset limit), with the key, the platform, the provenance and a sha256 per part and per file.\n           The bundle holds test keys. Nothing starts.\n  inspect  Read a bundle's index and say whether it fits this checkout (setup, lab.lock.json, declared inputs) and\n           machine (platform), and why not. Nothing starts or is written.\n  import   Refuse a bundle that does not fit (every reason, nothing started); otherwise start the fixture's\n           environment, check every part and file while unpacking into .product-lab/fixtures, move the session's\n           directories to this lab, and have the environment adopt the state (a restore that brings the bundle's\n           lineage; the environment moves its directory and port block where it can and says what it moved, or\n           refuses naming what it cannot). The environment stops at the end; the fixture then fits (fixture run).\n  --json <file>  also write what happened as JSON";
+/** `1.9G`, `500M`, `1048576` → bytes; undefined when it is not a size. */
+export declare function parseSize(text: string): number | undefined;
+export declare const megabytes: (bytes: number) => string;
+export declare const seconds: (ms: number) => string;
+export declare function runFixtureSharingCommand(runtime: LabRuntime, argv: string[], out: (text: string) => void, now?: () => number): Promise<number>;
+/**
+ * Inspect `index`, start the fixture's environment (or wait for `environmentStart`, already under way: `fixture pull`
+ * starts it while downloading), import, report whether it fits, stop the environment.
+ */
+export declare function importBundle(runtime: LabRuntime, index: string, json: string | undefined, out: (text: string) => void, now: () => number, options?: {
+    readonly environmentStart?: Promise<number>;
+    readonly summary?: Record<string, unknown>;
+    readonly started?: number;
+}): Promise<number>;

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

@@ -0,0 +1,192 @@
+// 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 FIXTURE_SHARING_USAGE = `       product-lab fixture export <name> [--out <file>] [--part-size <size>] [--level <n>] [--config lab.config.ts] [--json <file>]
+       product-lab fixture inspect <index> [--config lab.config.ts] [--json <file>]
+       product-lab fixture import <index> [--config lab.config.ts] [--json <file>]
+
+  export   Write saved fixture <name> as one bundle: <file> (default ./<name>.fixture.json), the index, and its parts
+           beside it (<name>.fixture.tar.zst.001, …): a zstd-compressed tar of the record, the environment's state and
+           the identities' wallets and host state, cut into parts of at most --part-size (default 1.9G, below GitHub's
+           2 GiB release asset limit), with the key, the platform, the provenance and a sha256 per part and per file.
+           The bundle holds test keys. Nothing starts.
+  inspect  Read a bundle's index and say whether it fits this checkout (setup, lab.lock.json, declared inputs) and
+           machine (platform), and why not. Nothing starts or is written.
+  import   Refuse a bundle that does not fit (every reason, nothing started); otherwise start the fixture's
+           environment, check every part and file while unpacking into .product-lab/fixtures, move the session's
+           directories to this lab, and have the environment adopt the state (a restore that brings the bundle's
+           lineage; the environment moves its directory and port block where it can and says what it moved, or
+           refuses naming what it cannot). The environment stops at the end; the fixture then fits (fixture run).
+  --json <file>  also write what happened as JSON`;
+const UNITS = { "": 1, K: 1024, M: 1024 ** 2, G: 1024 ** 3 };
+export function parseSize(text) {
+    const match = /^(\d+(?:\.\d+)?)\s*([KMG]?)(?:i?B)?$/i.exec(text.trim());
+    if (!match)
+        return undefined;
+    const bytes = Math.floor(Number(match[1]) * UNITS[match[2].toUpperCase()]);
+    return Number.isFinite(bytes) && bytes > 0 ? bytes : undefined;
+}
+export const megabytes = (bytes) => (bytes >= 1024 ** 3 ? `${(bytes / 1024 ** 3).toFixed(2)} GiB` : `${(bytes / 1024 ** 2).toFixed(1)} MiB`);
+export const seconds = (ms) => `${(ms / 1000).toFixed(1)} s`;
+function describeCheck(check) {
+    const lines = [
+        `Fixture ${check.name} (environment ${check.environment}), saved ${check.savedAt} on ${check.platform.os}/${check.platform.arch}`,
+        `  ${check.parts} part(s), ${megabytes(check.compressedBytes)} compressed, ${megabytes(check.bytes)} archived; identities: ${check.identities.join(", ") || "none"}`,
+        `  lineage ${check.lineage}; runtimes ${Object.entries(check.runtimes).map(([chain, code]) => `${chain} ${code.slice(0, 10)}…`).join(", ")}`,
+        `  ${check.notice}`,
+    ];
+    lines.push(check.reasons.length ? `It cannot be imported here:\n${check.reasons.map((reason) => `- ${reason}`).join("\n")}` : "It fits this checkout and machine.");
+    return lines.join("\n");
+}
+export async function runFixtureSharingCommand(runtime, argv, out, now = () => performance.now()) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                config: { type: "string" },
+                out: { type: "string" },
+                "part-size": { type: "string" },
+                level: { type: "string" },
+                json: { type: "string" },
+            },
+        });
+    }
+    catch (error) {
+        out(`${error instanceof Error ? error.message : String(error)}\n${FIXTURE_SHARING_USAGE}\n`);
+        return 2;
+    }
+    const { values, positionals } = parsed;
+    const [action, subject] = positionals;
+    if (!subject) {
+        out(`${FIXTURE_SHARING_USAGE}\n`);
+        return 2;
+    }
+    await runtime.load();
+    const sharing = runtime.fixtureSharing();
+    const json = values.json !== undefined ? resolve(values.json) : undefined;
+    const write = (value) => {
+        if (json)
+            writeFileSync(json, JSON.stringify(value, null, 2) + "\n");
+    };
+    try {
+        if (action === "export") {
+            const partBytes = values["part-size"] !== undefined ? parseSize(values["part-size"]) : undefined;
+            if (values["part-size"] !== undefined && partBytes === undefined) {
+                out(`--part-size must be a size such as 1.9G, 500M or 1048576, not ${values["part-size"]}\n`);
+                return 2;
+            }
+            const level = values.level !== undefined ? Number(values.level) : undefined;
+            if (level !== undefined && (!Number.isInteger(level) || level < 1 || level > 19)) {
+                out("--level must be a zstd level from 1 to 19\n");
+                return 2;
+            }
+            const report = await sharing.exportFixture({ name: subject, out: resolve(values.out ?? `${subject}.fixture.json`), ...(partBytes ? { partBytes } : {}), ...(level ? { level } : {}) });
+            write(report);
+            {
+                out(`Exported fixture ${report.name} (environment ${report.environment}) in ${seconds(report.ms)}: ${report.files} files, ${megabytes(report.bytes)} archived, ${megabytes(report.compressedBytes)} compressed in ${report.parts.length} part(s)\n`);
+                out(`  index ${report.index}\n${report.parts.map((part) => `  part  ${part.file} ${megabytes(part.bytes)} sha256 ${part.sha256}`).join("\n")}\n`);
+                out(`  ${report.notice}\n`);
+                for (const warning of report.warnings)
+                    out(`  warning: ${warning}\n`);
+            }
+            return 0;
+        }
+        if (action === "inspect") {
+            const check = await sharing.inspectBundle(resolve(subject));
+            write(check);
+            out(`${describeCheck(check)}\n`);
+            return check.reasons.length ? 1 : 0;
+        }
+        if (action !== "import") {
+            out(`${FIXTURE_SHARING_USAGE}\n`);
+            return 2;
+        }
+    }
+    catch (error) {
+        out(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    return importBundle(runtime, resolve(subject), json, out, now);
+}
+export async function importBundle(runtime, index, json, out, now, options = {}) {
+    const sharing = runtime.fixtureSharing();
+    const summary = { ...options.summary, index, timings: { ...(options.summary?.timings ?? {}) } };
+    const timings = summary.timings;
+    const started = options.started ?? now();
+    const stopStarted = async () => {
+        if (options.environmentStart && (await options.environmentStart.then(() => true, () => false)))
+            await runtime.stopEnvironment({ interruptRun: true });
+    };
+    const check = await sharing.inspectBundle(index).catch((error) => {
+        out(`${error instanceof Error ? error.message : String(error)}\n`);
+        return undefined;
+    });
+    if (!check) {
+        await stopStarted();
+        return 1;
+    }
+    summary.check = check;
+    out(`${describeCheck(check)}\n`);
+    if (check.reasons.length) {
+        await stopStarted();
+        if (json)
+            writeFileSync(json, JSON.stringify(summary, null, 2) + "\n");
+        return 1;
+    }
+    let code = 0;
+    try {
+        if (options.environmentStart) {
+            timings.environmentStartMs = await options.environmentStart;
+        }
+        else {
+            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 importing = now();
+        const report = await sharing.importFixture({ index, confirmation: runtime.snapshot().confirmations.restoreFixture });
+        timings.importMs = Math.round(now() - importing);
+        summary.report = report;
+        out(`Imported fixture ${report.name}: checked and unpacked ${report.files} files (${megabytes(report.compressedBytes)} compressed) in ${seconds(report.unpackMs)}; adopted in ${seconds(report.restored.timings.totalMs)} (environment ${seconds(report.restored.timings.environmentMs)}); lineage ${report.lineage}\n`);
+        for (const entry of report.relocated)
+            out(`  moved ${entry.from} → ${entry.to}\n`);
+        for (const line of report.remapped)
+            out(`  ${line}\n`);
+        const status = (await runtime.fixtures()).find((item) => item.name === report.name);
+        summary.status = status;
+        if (status?.state === "fits")
+            out(`Fixture ${report.name} fits the running environment: product-lab fixture run ${report.name} restores it.\n`);
+        else {
+            code = 1;
+            out(`Fixture ${report.name} was imported but does not fit the running environment (${status?.state ?? "unknown"}):\n${(status?.reasons ?? []).map((reason) => `- ${reason}`).join("\n")}\n`);
+        }
+    }
+    catch (error) {
+        code = 1;
+        const reasons = error.reasons;
+        if (Array.isArray(reasons))
+            summary.refused = reasons.map(String);
+        out(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    try {
+        const from = now();
+        await runtime.stopEnvironment({ interruptRun: true });
+        timings.environmentStopMs = Math.round(now() - from);
+    }
+    catch (error) {
+        out(`Stopping the environment failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        code = 1;
+    }
+    timings.totalMs = Math.round(now() - started);
+    out(`Total ${seconds(timings.totalMs)} (exit ${code})\n`);
+    if (json)
+        writeFileSync(json, JSON.stringify(summary, null, 2) + "\n");
+    return code;
+}

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

@@ -0,0 +1,3 @@
+import type { LabRuntime } from "@parity/product-lab/ports/driving";
+export declare const FIXTURE_SOURCE_USAGE = "       product-lab fixture sources [--config lab.config.ts] [--json <file>]\n       product-lab fixture pull <name> [--source <id>] [--download-only] [--config lab.config.ts] [--json <file>]\n       product-lab fixture push <name> [--source <id>] [--part-size <size>] [--level <n>] [--config lab.config.ts] [--json <file>]\n\n  sources  List the lab's fixture sources (defineLab({ fixtureSources })). Reads nothing from them.\n  pull     Read each source's catalog (manifest.json) in order and pick the newest published bundle of <name> that fits\n           this checkout (setup, lab.lock.json, declared inputs) and machine; say why each other one does not fit.\n           Download it into <PRODUCT_LAB_CACHE_DIR>/fixtures (each file's size and sha256 checked, a cached file that\n           checks out kept; a GitHub release's build attestation verified with gh when one is published) while the\n           fixture's environment starts, then import it as fixture import does, and stop the environment.\n           --download-only fetches and checks it and starts nothing.\n  push     Export saved fixture <name> into .product-lab/fixture-bundles/<name>/ with the source's catalog updated\n           beside it, then publish both to a directory source; for a GitHub release, print the gh release upload\n           command a person runs (the release must exist; an upload by hand carries no build attestation).\n           Nothing is ever uploaded by product-lab.\n  --json <file>  also write what happened as JSON";
+export declare function runFixtureSourceCommand(runtime: LabRuntime, argv: string[], out: (text: string) => void, now: () => number): Promise<number>;

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

@@ -0,0 +1,161 @@
+// 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";
+import { importBundle, megabytes, parseSize, seconds } from "./fixture-sharing-command.js";
+export const FIXTURE_SOURCE_USAGE = `       product-lab fixture sources [--config lab.config.ts] [--json <file>]
+       product-lab fixture pull <name> [--source <id>] [--download-only] [--config lab.config.ts] [--json <file>]
+       product-lab fixture push <name> [--source <id>] [--part-size <size>] [--level <n>] [--config lab.config.ts] [--json <file>]
+
+  sources  List the lab's fixture sources (defineLab({ fixtureSources })). Reads nothing from them.
+  pull     Read each source's catalog (manifest.json) in order and pick the newest published bundle of <name> that fits
+           this checkout (setup, lab.lock.json, declared inputs) and machine; say why each other one does not fit.
+           Download it into <PRODUCT_LAB_CACHE_DIR>/fixtures (each file's size and sha256 checked, a cached file that
+           checks out kept; a GitHub release's build attestation verified with gh when one is published) while the
+           fixture's environment starts, then import it as fixture import does, and stop the environment.
+           --download-only fetches and checks it and starts nothing.
+  push     Export saved fixture <name> into .product-lab/fixture-bundles/<name>/ with the source's catalog updated
+           beside it, then publish both to a directory source; for a GitHub release, print the gh release upload
+           command a person runs (the release must exist; an upload by hand carries no build attestation).
+           Nothing is ever uploaded by product-lab.
+  --json <file>  also write what happened as JSON`;
+function describeDownload(report) {
+    const attestation = report.attestation.status === "verified" ? `attestation verified${report.attestation.signerWorkflow ? ` (${report.attestation.signerWorkflow})` : ""}` : `attestation ${report.attestation.status}${report.attestation.reason ? `: ${report.attestation.reason}` : ""}`;
+    return [
+        `Fixture ${report.name} from ${report.source.id} (${report.source.location}): ${report.published.index}, saved ${report.published.createdAt}, ${report.published.parts} part(s), ${megabytes(report.published.bytes)}`,
+        `  ${report.cached ? "already in the cache, checked" : `downloaded ${megabytes(report.fetchedBytes)} and checked`} in ${seconds(report.ms)}: ${report.index}`,
+        `  ${attestation}`,
+        ...report.skipped.map((reason) => `  skipped ${reason}`),
+    ].join("\n");
+}
+export async function runFixtureSourceCommand(runtime, argv, out, now) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                config: { type: "string" },
+                source: { type: "string" },
+                "download-only": { type: "boolean" },
+                "part-size": { type: "string" },
+                level: { type: "string" },
+                json: { type: "string" },
+            },
+        });
+    }
+    catch (error) {
+        out(`${error instanceof Error ? error.message : String(error)}\n${FIXTURE_SOURCE_USAGE}\n`);
+        return 2;
+    }
+    const { values, positionals } = parsed;
+    const [action, name] = positionals;
+    if (action !== "sources" && !name) {
+        out(`${FIXTURE_SOURCE_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");
+    };
+    await runtime.load();
+    const sharing = runtime.fixtureSharing();
+    const source = values.source !== undefined ? { source: values.source } : {};
+    if (action === "sources") {
+        try {
+            const sources = sharing.fixtureSources();
+            write(sources);
+            out(sources.length ? `${sources.map((item) => `${item.id}  ${item.kind}  ${item.location}`).join("\n")}\n` : "The lab declares no fixture sources (defineLab({ fixtureSources })).\n");
+            return 0;
+        }
+        catch (error) {
+            out(`${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
+    }
+    if (action === "push") {
+        const partBytes = values["part-size"] !== undefined ? parseSize(values["part-size"]) : undefined;
+        if (values["part-size"] !== undefined && partBytes === undefined) {
+            out(`--part-size must be a size such as 1.9G, 500M or 1048576, not ${values["part-size"]}\n`);
+            return 2;
+        }
+        const level = values.level !== undefined ? Number(values.level) : undefined;
+        if (level !== undefined && (!Number.isInteger(level) || level < 1 || level > 19)) {
+            out("--level must be a zstd level from 1 to 19\n");
+            return 2;
+        }
+        try {
+            const report = await sharing.pushFixture({ name: name, ...source, ...(partBytes ? { partBytes } : {}), ...(level ? { level } : {}) });
+            write(report);
+            out(`Exported fixture ${report.name} in ${seconds(report.exported.ms)}: ${report.exported.files} files, ${megabytes(report.exported.compressedBytes)} in ${report.exported.parts.length} part(s)\n  index   ${report.exported.index}\n  catalog ${report.catalog}\n  ${report.notice}\n`);
+            if (report.published)
+                out(`Published to ${report.source.id} (${report.source.location}):\n${report.published.map((file) => `  ${file}`).join("\n")}\n`);
+            if (report.commands) {
+                out(`product-lab does not upload to ${report.source.location}. To publish this bundle by hand, run:\n${report.commands.map((command) => `  ${command}`).join("\n")}\n`);
+                out("The release must exist already. A bundle uploaded by hand carries no build attestation; a product's CI publishes one with it (tools/ci/templates/product-fixtures.yml, docs/ci.md).\n");
+            }
+            return 0;
+        }
+        catch (error) {
+            out(`${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
+    }
+    if (action !== "pull") {
+        out(`${FIXTURE_SOURCE_USAGE}\n`);
+        return 2;
+    }
+    const started = now();
+    const downloadOnly = values["download-only"] === true;
+    const status = downloadOnly ? undefined : (await runtime.fixtures()).find((item) => item.name === name);
+    if (!downloadOnly && !status) {
+        out(`The lab declares no fixture ${JSON.stringify(name)}\n`);
+        return 1;
+    }
+    let environmentStart;
+    const startEnvironment = () => {
+        if (environmentStart)
+            return environmentStart;
+        const environment = status.environment;
+        out(`Starting environment ${environment} while the bundle downloads\n`);
+        const from = now();
+        environmentStart = runtime.startEnvironment({ environment, keep: true }).then(() => {
+            const ms = Math.round(now() - from);
+            out(`Environment ${environment} ready in ${seconds(ms)}\n`);
+            return ms;
+        });
+        environmentStart.catch(() => undefined);
+        return environmentStart;
+    };
+    let reported = 0;
+    const progress = (bytes) => {
+        if (!downloadOnly)
+            void startEnvironment();
+        if (bytes - reported < 256 * 1024 ** 2)
+            return;
+        reported = bytes;
+        out(`  downloaded ${megabytes(bytes)}\n`);
+    };
+    out(`Looking for a published bundle of ${name} that fits this checkout\n`);
+    const download = sharing.downloadFixture({ name: name, ...source, progress });
+    let report;
+    try {
+        report = await download;
+    }
+    catch (error) {
+        out(`${error instanceof Error ? error.message : String(error)}\n`);
+        if (environmentStart && (await environmentStart.then(() => true, () => false)))
+            await runtime.stopEnvironment({ interruptRun: true });
+        write({ refused: error.reasons ?? [String(error)] });
+        return 1;
+    }
+    out(`${describeDownload(report)}\n`);
+    if (downloadOnly) {
+        write({ download: report });
+        return 0;
+    }
+    return importBundle(runtime, report.index, json, out, now, { environmentStart: startEnvironment(), started, summary: { download: report, timings: { downloadMs: report.ms } } });
+}

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

@@ -0,0 +1,5 @@
+import type { LabRuntime } from "@parity/product-lab/ports/driving";
+export declare const HOST_USAGE = "Usage: product-lab host verify --host <id> --config <targets.ts> [--only a,b] [--environment <name>] [--json] [--out report.json]\n       product-lab host fetch [--host <kind>] [--config <tools.ts>] [adapter flags] [--json] [--out file]\n       product-lab host build [--host <kind>] [--config <tools.ts>] [adapter flags] [--json] [--out file]\n       product-lab host rebase-check --to <ref> [--host <kind>] [--config <tools.ts>] [adapter flags] [--json] [--out file]\n\nverify  Run the host conformance kit against one host adapter. Contracts for\n        capabilities the adapter does not declare are reported as unsupported.\n  --host <id>        host id defined in the targets module\n  --config <file>    module whose default export is defineHostVerifications([...])\n  --only <ids>       run only these contract ids (the rest are reported skipped)\n  --environment <name>\n                     run on this environment of the lab's chains: started for the\n                     run and stopped after (a public network is refused). Without\n                     it the targets module starts or attaches to its own chain.\n  --json             print the full report as JSON\n  --out <file>       also write the JSON report to a file\n  Exit code: 0 when every declared contract passed, 1 otherwise.\n\nfetch   Make a verified copy of a host available (the host adapter's fetch).\nbuild   In product-lab's own checkout only: build a host from source (the host\n        adapter's build). A product runs released hosts; there it is refused.\nrebase-check\n        In product-lab's own checkout only: check whether the host adapter's\n        patches still apply to another upstream commit, without building (the\n        host adapter's checkPatches). Exit code: 0\n        when every patch applies or is already upstream (a 3-way merge is flagged\n        \"needs refresh\"), 1 on a conflict or a skipped patch, 2 on invalid input.\n  --host <kind>      a host adapter kind of the tools module (default: its first)\n  --config <file>    tools module whose default export is the host adapter factories\n                     (default: the host adapters the composition root constructs)\n  --json             print the result as JSON\n  --out <file>       also write the JSON result to a file\n  Each host adapter adds its own flags (listed below).";
+/** Why a product's `host build`, `host rebase-check` or `host fetch --patches` is refused: it runs released hosts only. */
+export declare const PRODUCT_HOST_TOOLS_REFUSAL: string;
+export declare function runHostCommand(runtime: LabRuntime, argv: string[], signal?: AbortSignal, checkout?: boolean): Promise<number>;

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

@@ -0,0 +1,213 @@
+// 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";
+import { MissingHostToolsError } from "@parity/product-lab/domain";
+import { CLI_HOST_UPSTREAM, insideProductLabCheckout } from "./checkout.js";
+export const HOST_USAGE = `Usage: product-lab host verify --host <id> --config <targets.ts> [--only a,b] [--environment <name>] [--json] [--out report.json]
+       product-lab host fetch [--host <kind>] [--config <tools.ts>] [adapter flags] [--json] [--out file]
+       product-lab host build [--host <kind>] [--config <tools.ts>] [adapter flags] [--json] [--out file]
+       product-lab host rebase-check --to <ref> [--host <kind>] [--config <tools.ts>] [adapter flags] [--json] [--out file]
+
+verify  Run the host conformance kit against one host adapter. Contracts for
+        capabilities the adapter does not declare are reported as unsupported.
+  --host <id>        host id defined in the targets module
+  --config <file>    module whose default export is defineHostVerifications([...])
+  --only <ids>       run only these contract ids (the rest are reported skipped)
+  --environment <name>
+                     run on this environment of the lab's chains: started for the
+                     run and stopped after (a public network is refused). Without
+                     it the targets module starts or attaches to its own chain.
+  --json             print the full report as JSON
+  --out <file>       also write the JSON report to a file
+  Exit code: 0 when every declared contract passed, 1 otherwise.
+
+fetch   Make a verified copy of a host available (the host adapter's fetch).
+build   In product-lab's own checkout only: build a host from source (the host
+        adapter's build). A product runs released hosts; there it is refused.
+rebase-check
+        In product-lab's own checkout only: check whether the host adapter's
+        patches still apply to another upstream commit, without building (the
+        host adapter's checkPatches). Exit code: 0
+        when every patch applies or is already upstream (a 3-way merge is flagged
+        "needs refresh"), 1 on a conflict or a skipped patch, 2 on invalid input.
+  --host <kind>      a host adapter kind of the tools module (default: its first)
+  --config <file>    tools module whose default export is the host adapter factories
+                     (default: the host adapters the composition root constructs)
+  --json             print the result as JSON
+  --out <file>       also write the JSON result to a file
+  Each host adapter adds its own flags (listed below).`;
+const COMMANDS = ["verify", "fetch", "build", "rebase-check"];
+function hostUsage(tools, file) {
+    if (!tools)
+        return `${HOST_USAGE}\n\n(No tools module at ${file}: pass --config <tools.ts> to list its adapters' flags.)`;
+    const lines = [HOST_USAGE, "", `Host adapters in ${tools.source}:`];
+    for (const host of tools.hosts) {
+        lines.push(`  ${host.kind}: ${host.label}${host.fetch ? "" : " (no fetch)"}${host.build ? "" : " (no build)"}${host.checkPatches ? "" : " (no rebase-check)"}`);
+        for (const flag of host.flags)
+            lines.push(`    ${`--${flag.name}${flag.value ? ` ${flag.value}` : ""}`.padEnd(22)} ${flag.description}${flag.commands ? ` [${flag.commands.join(", ")}]` : ""}${flag.requiredFor?.length ? ` (required for ${flag.requiredFor.join(", ")})` : ""}`);
+    }
+    return lines.join("\n");
+}
+function flagValue(argv, name) {
+    for (const [index, arg] of argv.entries()) {
+        if (arg === `--${name}`)
+            return argv[index + 1];
+        if (arg.startsWith(`--${name}=`))
+            return arg.slice(name.length + 3);
+    }
+    return undefined;
+}
+async function runVerify(runtime, argv, signal) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            help: { type: "boolean", short: "h" },
+            host: { type: "string" },
+            config: { type: "string" },
+            json: { type: "boolean" },
+            out: { type: "string" },
+            only: { type: "string" },
+            environment: { type: "string" },
+        },
+    });
+    if (values.help) {
+        console.log(HOST_USAGE);
+        return 0;
+    }
+    if (positionals.length !== 1 || positionals[0] !== "verify" || !values.host || !values.config) {
+        console.error(HOST_USAGE);
+        return 2;
+    }
+    const log = values.json ? (line) => console.error(line) : (line) => console.log(line);
+    const only = values.only ? values.only.split(",").map((id) => id.trim()).filter(Boolean) : undefined;
+    const verified = await runtime.verifyHost({ targets: resolve(values.config), host: values.host, ...(only ? { only } : {}), ...(values.environment ? { environment: values.environment } : {}), log, signal });
+    if (values.out)
+        writeFileSync(values.out, JSON.stringify(verified.report, null, 2) + "\n");
+    console.log(values.json ? JSON.stringify(verified.report, null, 2) : `\n${verified.text}`);
+    return verified.conforms ? 0 : 1;
+}
+export const PRODUCT_HOST_TOOLS_REFUSAL = "A product runs released hosts only: the truAPI WASM test host @parity/product-lab installs (defaultHost: \"truapi-wasm\"), and the truAPI CLI host's " +
+    `locked official release (product-lab host fetch caches it; it runs on a local environment once the release takes the lab's local endpoints, ${CLI_HOST_UPSTREAM}). ` +
+    "Building hosts and their patches is for working on product-lab itself, in its own checkout.";
+export async function runHostCommand(runtime, argv, signal = new AbortController().signal, checkout = insideProductLabCheckout()) {
+    const command = argv.find((arg) => COMMANDS.includes(arg));
+    const help = argv.includes("--help") || argv.includes("-h");
+    if (command === "verify")
+        return runVerify(runtime, argv, signal);
+    if (!checkout && !help && (command === "build" || command === "rebase-check" || (command === "fetch" && argv.some((arg) => arg === "--patches" || arg.startsWith("--patches="))))) {
+        console.error(`product-lab host ${command}: ${PRODUCT_HOST_TOOLS_REFUSAL}`);
+        return 2;
+    }
+    if (!command && !help) {
+        console.error(HOST_USAGE);
+        return 2;
+    }
+    const configured = flagValue(argv, "config");
+    const file = configured ? resolve(configured) : undefined;
+    let tools;
+    try {
+        tools = await runtime.hostTools(file);
+    }
+    catch (error) {
+        if (!command && file && error instanceof MissingHostToolsError) {
+            console.log(hostUsage(undefined, file));
+            return 0;
+        }
+        throw error;
+    }
+    if (!command) {
+        console.log(hostUsage(tools, file));
+        return 0;
+    }
+    const hostId = flagValue(argv, "host") ?? tools.hosts[0]?.kind;
+    if (!hostId)
+        throw new Error(`${tools.source} defines no host adapters`);
+    const host = tools.hosts.find((item) => item.kind === hostId);
+    if (!host)
+        throw new Error(`Unknown host ${hostId}. Defined: ${tools.hosts.map((item) => item.kind).join(", ") || "none"}`);
+    const flags = host.flags.filter((flag) => !flag.commands || flag.commands.includes(command));
+    const generic = {
+        help: { type: "boolean", short: "h" },
+        host: { type: "string" },
+        config: { type: "string" },
+        json: { type: "boolean" },
+        out: { type: "string" },
+    };
+    const adapterOptions = {};
+    for (const flag of flags) {
+        if (flag.name in generic)
+            throw new Error(`The ${hostId} host adapter declares --${flag.name}, which host ${command} already defines`);
+        adapterOptions[flag.name] = { type: flag.type, ...(flag.multiple ? { multiple: true } : {}) };
+    }
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { ...generic, ...adapterOptions } });
+    if (values.help) {
+        console.log(hostUsage(tools, file));
+        return 0;
+    }
+    if (positionals.length !== 1) {
+        console.error(hostUsage(tools, file));
+        return 2;
+    }
+    const given = values;
+    const missing = flags.filter((flag) => flag.requiredFor?.includes(command) && given[flag.name] === undefined);
+    if (missing.length) {
+        console.error(`host ${command} needs ${missing.map((flag) => `--${flag.name}`).join(", ")}\n${hostUsage(tools, file)}`);
+        return 2;
+    }
+    const log = values.json ? (line) => console.error(line) : (line) => console.log(line);
+    if (!(command === "fetch" ? host.fetch : command === "build" ? host.build : host.checkPatches))
+        throw new Error(`${hostId} does not support host ${command}`);
+    const result = await runtime.acquireHost({
+        ...(file ? { module: file } : {}),
+        kind: hostId,
+        command,
+        values: Object.fromEntries(flags.map((flag) => [flag.name, given[flag.name]])),
+        log,
+        signal,
+    });
+    if (values.out)
+        writeFileSync(values.out, JSON.stringify(result, null, 2) + "\n");
+    if (command === "rebase-check") {
+        const checked = result;
+        const exitCode = checked.exitCode === 0 || checked.exitCode === 1 || checked.exitCode === 2 ? checked.exitCode : 1;
+        console.log(values.json ? JSON.stringify(result, null, 2) : typeof checked.text === "string" ? checked.text : JSON.stringify(result, null, 2));
+        return exitCode;
+    }
+    console.log(values.json ? JSON.stringify(result, null, 2) : summarize(command, result));
+    return 0;
+}
+function summarize(command, result) {
+    const value = result;
+    if (value.hosts) {
+        const locked = value.locked
+            ? [`Locked release ${value.locked.release}: ${value.locked.cached ? "cached" : "not cached"}; provides ${value.locked.provides.join(", ") || "nothing beyond the release"}`]
+            : [];
+        if (!value.hosts.length)
+            return [...locked, `No cached hosts in ${value.cacheDir}`].join("\n");
+        return [
+            ...locked,
+            ...value.hosts.map((h) => `${h.label.padEnd(44)} ${h.origin.padEnd(12)} ${h.target.padEnd(28)} archive ${h.archive.sha256.slice(0, 16)}… attestation ${h.attestation.status}`),
+        ].join("\n");
+    }
+    const host = value.host;
+    if (!host)
+        return JSON.stringify(result, null, 2);
+    const lines = [
+        `${host.label} (${host.origin}${host.cached && command === "fetch" ? ", cached" : ""})`,
+        `  binary      ${host.binary}`,
+        `  sha256      binary ${host.binarySha256}${host.archiveSha256 ? `, archive ${host.archiveSha256}` : ""}`,
+        `  attestation ${host.attestation.status}${host.attestation.reason ? ` (${host.attestation.reason})` : ""}`,
+    ];
+    if (value.steps)
+        lines.push(`  steps       ${value.steps.map((s) => `${s.name} ${(s.ms / 1000).toFixed(1)} s`).join(", ")}`);
+    if (value.tests?.summary)
+        lines.push(`  tests       ${value.tests.summary}`);
+    if (value.totalMs !== undefined)
+        lines.push(`  total       ${(value.totalMs / 1000).toFixed(1)} s`);
+    if (value.logFile)
+        lines.push(`  log         ${value.logFile}`);
+    return lines.join("\n");
+}