@overcrow/mcp 0.0.0 → 0.1.0

package/dist/bootstrap/pin.json

@@ -0,0 +1,119 @@
+{
+  "release": "0.6.0-beta.2",
+  "tools": {
+    "linux-x86_64": {
+      "name": "overcrow-creator-tools-0.6.0-beta.2-linux-x86_64.zip",
+      "size": 15485097,
+      "sha256": "cf31486168ef2f7335eebf78453ce2bc4710cf18772c2a9b58dd8f329a50ac3b",
+      "files": [
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-linux-x86_64/README.txt",
+          "size": 1636,
+          "sha256": "36b87cb468f6e70b7b637b8cfec7652268065cf1ca53ea8fb2cbec3f3da1b4d5"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-linux-x86_64/SHA256SUMS",
+          "size": 797,
+          "sha256": "600c2d985e32a3db652cd1f7ff49ba39d069d7300eb59ada1e239855423d9901"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-linux-x86_64/cli.json",
+          "size": 1014,
+          "sha256": "ec1e1bb7fe5b7ce18b64ea41dbfc40c4545c08781158773425dc76077c8db8ce"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-linux-x86_64/overcrow-widget-1.0.0-beta.2-LICENSE.txt",
+          "size": 1071,
+          "sha256": "c159eef41245fe20d4cd29fc33a0e88a85f47b53ac321f266abfb7b707aee8c3"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-linux-x86_64/overcrow-widget-1.0.0-beta.2-THIRD-PARTY-NOTICES.md",
+          "size": 212099,
+          "sha256": "8c679481b61f9fb4c8352bd4d1c3bcfc23acf4d51b8252140ed214b1f5b756c4"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-linux-x86_64/overcrow-widget-1.0.0-beta.2-linux-x86_64",
+          "size": 8872680,
+          "sha256": "22c05cdefc4a9c8fa8efad29451377df19f3e2a8e32af9e14c1a25ffcc055c7e"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-linux-x86_64/overcrow-widget-headless-0.6.0-beta.2-LICENSE.md",
+          "size": 217457,
+          "sha256": "af6a7c90d1fa394bfaf586daa1afba7b65c07caaec83e70f01af2b93266277dd"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-linux-x86_64/overcrow-widget-headless-0.6.0-beta.2-linux-x86_64",
+          "size": 24446088,
+          "sha256": "644d05befead961846b402c5012a1460034cf5ef7bbbe38efcee66e883931d56"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-linux-x86_64/runtimes.json",
+          "size": 774,
+          "sha256": "13917d0506fdc9e91af61a2bdd1ee91adfd5a713807b61ffc94b74557c70914a"
+        }
+      ]
+    },
+    "windows-x86_64": {
+      "name": "overcrow-creator-tools-0.6.0-beta.2-windows-x86_64.zip",
+      "size": 15415211,
+      "sha256": "87a8323de96e987eae8c5d4d8d36b90c4fd4f8fe8b64b499c48b77b4faeb3fe0",
+      "files": [
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-windows-x86_64/README.txt",
+          "size": 1457,
+          "sha256": "a4ca866f352b7e39de434c27242234daa8fbbdfbb9b362bfc148ef398ed65da4"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-windows-x86_64/SHA256SUMS",
+          "size": 809,
+          "sha256": "e6a0c8e6ffde6d2c5a54fc486f6b1b17f225be1d56bf81b6a165f630df08915d"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-windows-x86_64/cli.json",
+          "size": 1014,
+          "sha256": "ec1e1bb7fe5b7ce18b64ea41dbfc40c4545c08781158773425dc76077c8db8ce"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-windows-x86_64/overcrow-widget-1.0.0-beta.2-LICENSE.txt",
+          "size": 1071,
+          "sha256": "c159eef41245fe20d4cd29fc33a0e88a85f47b53ac321f266abfb7b707aee8c3"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-windows-x86_64/overcrow-widget-1.0.0-beta.2-THIRD-PARTY-NOTICES.md",
+          "size": 212099,
+          "sha256": "8c679481b61f9fb4c8352bd4d1c3bcfc23acf4d51b8252140ed214b1f5b756c4"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-windows-x86_64/overcrow-widget-1.0.0-beta.2-windows-x86_64.exe",
+          "size": 8767488,
+          "sha256": "c8408f80e9b634cd3bc5f4cdf240179a6314ec847b7d99e4697f9ea47dae1506"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-windows-x86_64/overcrow-widget-headless-0.6.0-beta.2-LICENSE.md",
+          "size": 217457,
+          "sha256": "af6a7c90d1fa394bfaf586daa1afba7b65c07caaec83e70f01af2b93266277dd"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-windows-x86_64/overcrow-widget-headless-0.6.0-beta.2-windows-x86_64.exe",
+          "size": 25101824,
+          "sha256": "884b783ff37c594812f9203573668e86582b521dc2d9b145f5afc8955757c1ec"
+        },
+        {
+          "path": "overcrow-creator-tools-0.6.0-beta.2-windows-x86_64/runtimes.json",
+          "size": 774,
+          "sha256": "13917d0506fdc9e91af61a2bdd1ee91adfd5a713807b61ffc94b74557c70914a"
+        }
+      ]
+    }
+  },
+  "npm": {
+    "@overcrow/sdk": {
+      "version": "1.0.0",
+      "integrity": "sha512-akyuynS1TN5QbKyLsgoLOFF6JylVzNpUluEoSfz52xSlFg161kQ9QPLhcfGCptZ1x5/pm9/zPe/6LsHqFofnEA=="
+    },
+    "typescript": {
+      "version": "6.0.3",
+      "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw=="
+    }
+  }
+}

package/dist/bootstrap/zip.js

@@ -0,0 +1,258 @@
+// A strict reader of a creator tools ZIP, on the model of the CLI's
+// `cli/src/zipread.rs`. The archive's SHA-256 is checked against the pin
+// before this code sees it; the reader still trusts nothing it declares.
+//
+// Accepted: one disk, no ZIP64, no encryption, no comment, stored or
+// deflated regular files, the central directory right before its end
+// record, local headers that agree with it, entries that do not overlap,
+// and names made of plain components. Refused besides: links, directories,
+// device names Windows reserves, duplicates (case-insensitive) and every
+// byte the format does not account for. Each entry is inflated within its
+// declared size and checked against its CRC-32.
+import { crc32, inflateRawSync } from "node:zlib";
+export class ZipError extends Error {
+    kind;
+    rule;
+    constructor(kind, rule) {
+        super(kind === "unsafe_name"
+            ? `the archive holds an unsafe file name (${rule})`
+            : kind === "too_large"
+                ? `the archive exceeds its size bounds (${rule})`
+                : `invalid archive: ${rule}`);
+        this.kind = kind;
+        this.rule = rule;
+        this.name = "ZipError";
+    }
+}
+const END_SIGNATURE = 0x06054b50;
+const CENTRAL_SIGNATURE = 0x02014b50;
+const LOCAL_SIGNATURE = 0x04034b50;
+const ZIP64_LOCATOR_SIGNATURE = 0x07064b50;
+const END_BYTES = 22;
+const CENTRAL_BYTES = 46;
+const LOCAL_BYTES = 30;
+/** Encryption (bit 0), strong encryption (bit 6), masked headers (bit 13). */
+const ENCRYPTED_FLAGS = 1 | (1 << 6) | (1 << 13);
+/** Deflate options (bits 1-2), data descriptor (bit 3), UTF-8 names (bit 11). */
+const KNOWN_FLAGS = ENCRYPTED_FLAGS | 0b110 | (1 << 3) | (1 << 11);
+const MAX_DIRECTORY_BYTES = 64 * 1024;
+const MAX_NAME_BYTES = 255;
+const U32_MAX = 0xffffffff;
+const U16_MAX = 0xffff;
+const UNIX_HOST = 3;
+const FILE_TYPE_MASK = 0o170000;
+const REGULAR_FILE = 0o100000;
+const DOS_DIRECTORY = 0x10;
+const COMPONENT = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+const WINDOWS_DEVICE = /^(con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³]|conin\$|conout\$)(\..*)?$/i;
+/**
+ * A safe name: relative, components of letters, digits, `.`, `_`, `+` and
+ * `-` that start with a letter or digit, no trailing dot, no name that
+ * Windows maps to a device. Directories are implied, never entries.
+ */
+export function safeName(name) {
+    if (name.length === 0 || Buffer.byteLength(name) > MAX_NAME_BYTES)
+        return false;
+    return name
+        .split("/")
+        .every((component) => COMPONENT.test(component) && !component.endsWith(".") && !WINDOWS_DEVICE.test(component));
+}
+/** Reads and checks the whole directory of `archive`. */
+export function readEntries(archive, limits) {
+    const length = archive.length;
+    if (length < END_BYTES)
+        throw new ZipError("invalid", "too short");
+    const endOffset = length - END_BYTES;
+    if (archive.readUInt32LE(endOffset) !== END_SIGNATURE) {
+        throw new ZipError("invalid", "no end record at the end");
+    }
+    if (archive.readUInt16LE(endOffset + 20) !== 0)
+        throw new ZipError("invalid", "archive comment");
+    const disk = archive.readUInt16LE(endOffset + 4);
+    const directoryDisk = archive.readUInt16LE(endOffset + 6);
+    const diskEntries = archive.readUInt16LE(endOffset + 8);
+    const totalEntries = archive.readUInt16LE(endOffset + 10);
+    const directorySize = archive.readUInt32LE(endOffset + 12);
+    const directoryOffset = archive.readUInt32LE(endOffset + 16);
+    if (diskEntries === U16_MAX ||
+        totalEntries === U16_MAX ||
+        directorySize === U32_MAX ||
+        directoryOffset === U32_MAX) {
+        throw new ZipError("invalid", "ZIP64");
+    }
+    if (endOffset >= 20 && archive.readUInt32LE(endOffset - 20) === ZIP64_LOCATOR_SIGNATURE) {
+        throw new ZipError("invalid", "ZIP64");
+    }
+    if (disk !== 0 || directoryDisk !== 0 || diskEntries !== totalEntries) {
+        throw new ZipError("invalid", "several disks");
+    }
+    if (totalEntries === 0)
+        throw new ZipError("invalid", "no entries");
+    if (totalEntries > limits.maxEntries)
+        throw new ZipError("too_large", "too many entries");
+    if (directorySize > MAX_DIRECTORY_BYTES)
+        throw new ZipError("too_large", "central directory");
+    if (directoryOffset + directorySize !== endOffset) {
+        throw new ZipError("invalid", "central directory not before its end record");
+    }
+    const directory = archive.subarray(directoryOffset, endOffset);
+    const found = [];
+    const seen = new Set();
+    let total = 0;
+    let cursor = 0;
+    for (let index = 0; index < totalEntries; index += 1) {
+        if (cursor + CENTRAL_BYTES > directory.length) {
+            throw new ZipError("invalid", "truncated central directory");
+        }
+        if (directory.readUInt32LE(cursor) !== CENTRAL_SIGNATURE) {
+            throw new ZipError("invalid", "bad central header");
+        }
+        const madeBy = directory.readUInt16LE(cursor + 4);
+        const flags = directory.readUInt16LE(cursor + 8);
+        const method = directory.readUInt16LE(cursor + 10);
+        const crc = directory.readUInt32LE(cursor + 16);
+        const compressed = directory.readUInt32LE(cursor + 20);
+        const size = directory.readUInt32LE(cursor + 24);
+        const nameLength = directory.readUInt16LE(cursor + 28);
+        const extraLength = directory.readUInt16LE(cursor + 30);
+        const commentLength = directory.readUInt16LE(cursor + 32);
+        const diskStart = directory.readUInt16LE(cursor + 34);
+        const externalAttributes = directory.readUInt32LE(cursor + 38);
+        const localOffset = directory.readUInt32LE(cursor + 42);
+        if ((flags & ENCRYPTED_FLAGS) !== 0)
+            throw new ZipError("invalid", "encrypted entry");
+        if ((flags & ~KNOWN_FLAGS) !== 0)
+            throw new ZipError("invalid", "unknown entry flags");
+        if (method !== 0 && method !== 8)
+            throw new ZipError("invalid", "unsupported compression method");
+        if (compressed === U32_MAX || size === U32_MAX || localOffset === U32_MAX) {
+            throw new ZipError("invalid", "ZIP64");
+        }
+        if (diskStart !== 0)
+            throw new ZipError("invalid", "several disks");
+        if (method === 0 && compressed !== size)
+            throw new ZipError("invalid", "stored entry sizes differ");
+        const nameStart = cursor + CENTRAL_BYTES;
+        if (nameStart + nameLength > directory.length) {
+            throw new ZipError("invalid", "truncated central directory");
+        }
+        const nameBytes = Buffer.from(directory.subarray(nameStart, nameStart + nameLength));
+        let name;
+        try {
+            name = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(nameBytes);
+        }
+        catch {
+            // Found by test/fuzz-zip.mjs: a name that is not UTF-8 is refused, not thrown.
+            throw new ZipError("unsafe_name", "not UTF-8");
+        }
+        if (!safeName(name))
+            throw new ZipError("unsafe_name", name.slice(0, 64));
+        // Only regular files: no link, no directory, no device.
+        let mode = null;
+        if (madeBy >> 8 === UNIX_HOST) {
+            const unixMode = externalAttributes >>> 16;
+            const type = unixMode & FILE_TYPE_MASK;
+            if (type !== 0 && type !== REGULAR_FILE)
+                throw new ZipError("unsafe_name", `${name} is not a regular file`);
+            mode = unixMode & 0o7777;
+        }
+        if ((externalAttributes & DOS_DIRECTORY) !== 0) {
+            throw new ZipError("unsafe_name", `${name} is a directory`);
+        }
+        // Case-insensitive file systems would merge two such names.
+        const key = name.toLowerCase();
+        if (seen.has(key))
+            throw new ZipError("invalid", "duplicate entry");
+        seen.add(key);
+        cursor = nameStart + nameLength + extraLength + commentLength;
+        if (cursor > directory.length)
+            throw new ZipError("invalid", "truncated central directory");
+        if (size > limits.maxEntryBytes)
+            throw new ZipError("too_large", "entry size");
+        total += size;
+        if (total > limits.maxTotalBytes)
+            throw new ZipError("too_large", "total size");
+        found.push({
+            localOffset,
+            flags,
+            method,
+            nameBytes,
+            entry: { name, size, mode, compressed, deflated: method === 8, crc32: crc, dataStart: 0 },
+        });
+    }
+    if (cursor !== directory.length)
+        throw new ZipError("invalid", "bytes after the central directory");
+    // Local headers repeat the central directory; entries follow one another
+    // without overlapping, and nothing lies between them.
+    found.sort((a, b) => a.localOffset - b.localOffset);
+    let nextFree = 0;
+    const checked = [];
+    for (const { localOffset, entry, flags, method, nameBytes } of found) {
+        if (localOffset !== nextFree) {
+            throw new ZipError("invalid", localOffset < nextFree ? "overlapping entries" : "bytes between entries");
+        }
+        if (localOffset + LOCAL_BYTES > directoryOffset) {
+            throw new ZipError("invalid", "local header outside the data");
+        }
+        if (archive.readUInt32LE(localOffset) !== LOCAL_SIGNATURE) {
+            throw new ZipError("invalid", "bad local header");
+        }
+        const disagree = new ZipError("invalid", "local header disagrees with the directory");
+        if (archive.readUInt16LE(localOffset + 6) !== flags ||
+            archive.readUInt16LE(localOffset + 8) !== method) {
+            throw disagree;
+        }
+        // A data descriptor (bit 3) is not something the publisher writes.
+        if ((flags & (1 << 3)) !== 0)
+            throw new ZipError("invalid", "data descriptor");
+        if (archive.readUInt32LE(localOffset + 14) !== entry.crc32 ||
+            archive.readUInt32LE(localOffset + 18) !== entry.compressed ||
+            archive.readUInt32LE(localOffset + 22) !== entry.size) {
+            throw disagree;
+        }
+        const nameLength = archive.readUInt16LE(localOffset + 26);
+        const extraLength = archive.readUInt16LE(localOffset + 28);
+        if (nameLength !== nameBytes.length)
+            throw disagree;
+        const localNameEnd = localOffset + LOCAL_BYTES + nameLength;
+        if (localNameEnd > directoryOffset ||
+            !archive.subarray(localOffset + LOCAL_BYTES, localNameEnd).equals(nameBytes)) {
+            throw disagree;
+        }
+        const dataStart = localNameEnd + extraLength;
+        const dataEnd = dataStart + entry.compressed;
+        if (dataEnd > directoryOffset)
+            throw new ZipError("invalid", "entry data outside the archive");
+        nextFree = dataEnd;
+        checked.push({ ...entry, dataStart });
+    }
+    if (nextFree !== directoryOffset)
+        throw new ZipError("invalid", "bytes before the central directory");
+    return checked;
+}
+/**
+ * The uncompressed bytes of `entry`: exactly its declared size, with its
+ * CRC-32. The inflater stops at the declared size, so a bomb never grows.
+ */
+export function extractEntry(archive, entry) {
+    const raw = archive.subarray(entry.dataStart, entry.dataStart + entry.compressed);
+    let data;
+    if (entry.deflated) {
+        try {
+            data = inflateRawSync(raw, { maxOutputLength: Math.max(1, entry.size) });
+        }
+        catch (error) {
+            const tooLarge = error instanceof RangeError || error.code === "ERR_BUFFER_TOO_LARGE";
+            throw new ZipError("invalid", tooLarge ? "entry larger than declared" : "corrupt entry data");
+        }
+    }
+    else {
+        data = Buffer.from(raw);
+    }
+    if (data.length !== entry.size) {
+        throw new ZipError("invalid", data.length > entry.size ? "entry larger than declared" : "entry smaller than declared");
+    }
+    if (crc32(data) !== entry.crc32)
+        throw new ZipError("invalid", "CRC-32 mismatch");
+    return data;
+}

package/dist/cli.js

@@ -0,0 +1,200 @@
+// Calls of the widget CLI (`overcrow-widget`) of the installed creator
+// tools and the reading of its `--format json` output (one JSON object per
+// line). Paths are always absolute: the CLI would read an argument starting
+// with `--` as an option. The CLI never reaches the network here: `test`
+// gets the runtime with `--runtime` and `--offline`. `doctor` and `dev`,
+// which talk to a running OverCrow, are never called.
+import { childEnvironment } from "./env.js";
+import { runProcess } from "./run.js";
+export class CliError extends Error {
+    stderr;
+    constructor(message, stderr) {
+        super(message);
+        this.stderr = stderr;
+        this.name = "CliError";
+    }
+}
+const MINUTE = 60_000;
+export const TIMEOUTS = {
+    version: 15_000,
+    init: MINUTE,
+    check: 6 * MINUTE,
+    package: 6 * MINUTE,
+    admit: 2 * MINUTE,
+    inspect: MINUTE,
+    test: 20 * MINUTE,
+};
+/** Parses the JSON lines of stdout; other lines are ignored. */
+export function jsonLines(stdout, maxLines = 5000) {
+    const out = [];
+    for (const line of stdout.split("\n")) {
+        if (out.length >= maxLines)
+            break;
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("{"))
+            continue;
+        try {
+            const value = JSON.parse(trimmed);
+            if (typeof value === "object" && value !== null && !Array.isArray(value))
+                out.push(value);
+        }
+        catch {
+            // Not a JSON line.
+        }
+    }
+    return out;
+}
+const str = (value) => (typeof value === "string" ? value : null);
+const int = (value) => Number.isSafeInteger(value) ? value : null;
+/** A diagnostic object of the CLI, or undefined for any other line. */
+export function asDiagnostic(value) {
+    if ("type" in value)
+        return undefined;
+    const severity = value.severity;
+    if ((severity !== "error" && severity !== "warning") || typeof value.code !== "string")
+        return undefined;
+    return {
+        severity,
+        code: value.code,
+        file: str(value.file),
+        line: int(value.line),
+        column: int(value.column),
+        message: str(value.message) ?? "",
+        help: str(value.help),
+    };
+}
+export class Cli {
+    tools;
+    constructor(tools) {
+        this.tools = tools;
+    }
+    run(args, cwd, timeoutMs, signal) {
+        return runProcess(this.tools.cli, args, {
+            cwd,
+            env: childEnvironment({ network: false }),
+            timeoutMs,
+            signal,
+        });
+    }
+    static failure(result, what) {
+        if (result.timedOut)
+            return new CliError(`${what} took too long and was stopped`, result.stderr);
+        if (result.cancelled)
+            return new CliError(`${what} was cancelled`, result.stderr);
+        const first = result.stderr.split("\n").find((line) => line.trim() !== "") ?? "";
+        return new CliError(`${what} failed (exit ${result.code})${first ? `: ${first}` : ""}`, result.stderr);
+    }
+    /** `check <dir> --format json`: diagnostics, and whether there is no error. */
+    async check(directory, signal) {
+        const result = await this.run(["check", directory, "--format", "json"], directory, TIMEOUTS.check, signal);
+        if (result.code !== 0 && result.code !== 1)
+            throw Cli.failure(result, "check");
+        const diagnostics = jsonLines(result.stdout)
+            .map(asDiagnostic)
+            .filter((d) => d !== undefined);
+        return { ok: result.code === 0, diagnostics };
+    }
+    /** `package <dir> --out <file> --format json`. */
+    async package(directory, out, signal) {
+        const result = await this.run(["package", directory, `--out=${out}`, "--format", "json"], directory, TIMEOUTS.package, signal);
+        if (result.code !== 0 && result.code !== 1)
+            throw Cli.failure(result, "package");
+        const lines = jsonLines(result.stdout);
+        const diagnostics = lines.map(asDiagnostic).filter((d) => d !== undefined);
+        const summary = lines.find((line) => typeof line.package === "string" && typeof line.sha256 === "string");
+        return {
+            ok: result.code === 0 && summary !== undefined,
+            diagnostics,
+            bytes: int(summary?.bytes),
+            logicBytes: int(summary?.logicBytes),
+            sha256: str(summary?.sha256),
+        };
+    }
+    /** `admit <dir> --format json`: the static admission report, as data. */
+    async admit(directory, signal) {
+        const result = await this.run(["admit", directory, "--format", "json"], directory, TIMEOUTS.admit, signal);
+        if (result.code !== 0 && result.code !== 1)
+            throw Cli.failure(result, "admit");
+        const report = jsonLines(result.stdout).find((line) => line.formatVersion === 1);
+        if (!report)
+            throw Cli.failure(result, "admit");
+        return report;
+    }
+    /** `inspect <file> --format json`. */
+    async inspect(file, cwd, signal) {
+        const result = await this.run(["inspect", file, "--format", "json"], cwd, TIMEOUTS.inspect, signal);
+        if (result.code === 2)
+            throw Cli.failure(result, "inspect");
+        const lines = jsonLines(result.stdout);
+        const diagnostics = lines.map(asDiagnostic).filter((d) => d !== undefined);
+        const report = lines.find((line) => typeof line.id === "string" && typeof line.archive === "object");
+        return { ok: result.code === 0 && report !== undefined, diagnostics, report };
+    }
+    /** `test <dir> --runtime <cached runtime> --offline --format json`. */
+    async test(directory, options, signal) {
+        const args = [
+            "test",
+            directory,
+            `--runtime=${this.tools.runtime}`,
+            "--offline",
+            "--format",
+            "json",
+        ];
+        if (options.scenario)
+            args.push(`--scenario=${options.scenario}`);
+        if (options.update)
+            args.push("--update");
+        const result = await this.run(args, directory, TIMEOUTS.test, signal);
+        if (result.timedOut || result.cancelled)
+            throw Cli.failure(result, "test");
+        const lines = jsonLines(result.stdout);
+        const summary = lines.find((line) => line.type === "summary");
+        if (result.code === 2 ||
+            (result.code !== 0 && !summary && lines.every((line) => line.type !== "scenario"))) {
+            // No scenario ran: a usage, project or runtime problem, said on stderr.
+            const diagnostics = lines.map(asDiagnostic).filter((d) => d !== undefined);
+            if (diagnostics.length === 0 || result.code === 2) {
+                return { ran: false, diagnostics, problem: firstLines(result.stderr, 6) };
+            }
+        }
+        return {
+            ran: true,
+            diagnostics: lines.map(asDiagnostic).filter((d) => d !== undefined),
+            runtime: lines.find((line) => line.type === "runtime"),
+            scenarios: lines.filter((line) => line.type === "scenario"),
+            passed: int(summary?.passed),
+            failed: int(summary?.failed),
+            problem: result.code === 0 ? "" : firstLines(result.stderr, 6),
+        };
+    }
+    /** `init <dir> --template <t> --id <id> --name <name>` (no JSON form). */
+    async init(directory, template, id, name, cwd) {
+        const result = await this.run(["init", directory, `--template=${template}`, `--id=${id}`, `--name=${name}`], cwd, TIMEOUTS.init);
+        return {
+            ok: result.code === 0,
+            code: result.code,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        };
+    }
+}
+function firstLines(text, count) {
+    return text
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .slice(0, count)
+        .join("\n");
+}
+/** The `--version --format json` probe used when installing the tools. */
+export async function probeVersion(cli, cwd) {
+    const result = await runProcess(cli, ["--version", "--format", "json"], {
+        cwd,
+        env: childEnvironment({ network: false }),
+        timeoutMs: TIMEOUTS.version,
+        maxStdoutBytes: 64 * 1024,
+    });
+    if (result.code !== 0)
+        throw new CliError("the CLI did not report its version", result.stderr);
+    const [report] = jsonLines(result.stdout);
+    return report;
+}