pllla-connect 0.1.0

package/dist/main.js

@@ -0,0 +1,397 @@
+#!/usr/bin/env node
+/**
+ * pllla-connect — the one command a PLLLA connect card hands out, and the
+ * child process the desktop app runs to make "+ → Create → first greeting"
+ * take zero user actions (docs/agent/EXTERNAL_RUNTIME.md §6):
+ *
+ *   npx pllla-connect pair_live_xxx --server https://pllla.com [--runtime openclaw]
+ *                                   [--account agent-1a2b3c4d] [--json]
+ *
+ * Flow (§6.4): catalog → detect → [found: node → bridge]
+ *                                 / [missing: node → install → onboard → bridge]
+ *              → pair (the plugin does it at gateway start) → done.
+ *
+ * Three principles the flow never bends: the user's system Node / global npm
+ * is never touched (§6.1); detection never trusts PATH alone (§6.2); with no
+ * model login on the machine it stops honestly with `needs_model_auth`
+ * instead of lending a starter brain (§6.5).
+ */
+import { homedir } from "node:os";
+import { dirname } from "node:path";
+import { deriveAccountId, isValidAccountId, PAIRING_TOKEN_PREFIX, } from "./account.js";
+import { fetchRuntimeCatalog } from "./catalog.js";
+import { detectRuntimes, privateRuntimePrefix, probeRuntimeVersion, } from "./detect.js";
+import { shellQuote } from "./exec.js";
+import { defaultNodeRoot, ensurePrivateNode, scanPrivateNodes, } from "./nodeProvision.js";
+import { resolveNodeForRuntime } from "./nodeResolve.js";
+import { bridgeExisting, buildManualOnboardCommand, buildRuntimeEnv, installFresh, onboardFresh, resolveAuthChoice, } from "./openclaw.js";
+import { ConnectError, createProgressReporter, toConnectError, } from "./progress.js";
+import { compareVersions } from "./version.js";
+const SUPPORTED_CONTRACT_VERSION = 1;
+/** Exit codes: 0 done · 1 failed · 2 stopped honestly (`needs_model_auth`). */
+const EXIT_NEEDS_MODEL_AUTH = 2;
+function parseArgs(argv) {
+    const positional = [];
+    let serverOrigin = "https://pllla.com";
+    let runtimeId = null;
+    let accountId = null;
+    let json = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--server") {
+            serverOrigin = argv[index + 1] ?? "";
+            index += 1;
+        }
+        else if (arg === "--runtime") {
+            runtimeId = argv[index + 1] ?? null;
+            index += 1;
+        }
+        else if (arg === "--account") {
+            accountId = argv[index + 1] ?? null;
+            index += 1;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    const pairingToken = positional[0] ?? "";
+    if (!pairingToken.startsWith(PAIRING_TOKEN_PREFIX)) {
+        // Usage on the error path goes to stderr — stdout is the NDJSON channel.
+        printHelp(process.stderr);
+        throw new Error("A pairing token (pair_live_…) is required — copy the command from your agent's connect card in PLLLA.");
+    }
+    if (!/^https?:\/\//.test(serverOrigin)) {
+        throw new Error(`--server must be an http(s) origin, got "${serverOrigin}".`);
+    }
+    if (accountId !== null && !isValidAccountId(accountId)) {
+        throw new Error(`--account must be 1–64 letters, digits, "-" or "_" (got "${accountId}").`);
+    }
+    return {
+        pairingToken,
+        serverOrigin: serverOrigin.replace(/\/+$/, ""),
+        runtimeId,
+        accountId,
+        json,
+    };
+}
+function printHelp(stream = process.stdout) {
+    stream.write(`
+pllla-connect — connect a self-hosted agent runtime to a PLLLA agent
+
+Usage:
+  npx pllla-connect <pair_live_token> [--server <origin>] [--runtime <id>]
+                                      [--account <id>] [--json]
+
+  --server   PLLLA origin the agent lives on (default https://pllla.com)
+  --runtime  Runtime id from the server catalog (default: whatever is detected)
+  --account  Bridge account id (default: derived from the token)
+  --json     Machine progress: one JSON object per line on stdout
+
+The pairing token comes from the connect card in your PLLLA agent's chat.
+Exit codes: 0 connected · 1 failed · 2 stopped — sign in to a model first.
+
+`);
+}
+function buildConnectCommand(args) {
+    const parts = [
+        "npx pllla-connect",
+        args.pairingToken,
+        "--server",
+        args.serverOrigin,
+    ];
+    if (args.runtimeId)
+        parts.push("--runtime", args.runtimeId);
+    if (args.accountId)
+        parts.push("--account", args.accountId);
+    return parts.join(" ");
+}
+function pickTarget(detections, runtimeId) {
+    const detected = detections.find((detection) => detection.binaryPath) ??
+        detections.find((detection) => detection.stateDirFound || detection.gatewayLive);
+    if (detected)
+        return detected;
+    if (detections.length === 1)
+        return detections[0];
+    throw new ConnectError({
+        phase: "detect",
+        code: "unsupported_runtime",
+        message: runtimeId
+            ? `Runtime "${runtimeId}" was not detected.`
+            : `No runtime is installed and the catalog lists several (${detections
+                .map((detection) => detection.runtime.id)
+                .join(", ")}) — pass --runtime <id> to choose which one to install.`,
+    });
+}
+async function loadCatalog(args, reporter) {
+    reporter.progress("catalog", `Loading runtime catalog from ${args.serverOrigin}…`);
+    let catalog;
+    try {
+        catalog = await fetchRuntimeCatalog(args.serverOrigin);
+    }
+    catch (error) {
+        throw toConnectError(error, "catalog");
+    }
+    if (catalog.contractVersion !== SUPPORTED_CONTRACT_VERSION) {
+        throw new ConnectError({
+            phase: "catalog",
+            code: "unsupported_runtime",
+            message: `This pllla-connect build speaks contract v${SUPPORTED_CONTRACT_VERSION}, but the server speaks v${catalog.contractVersion}. Run the latest: npx pllla-connect@latest`,
+        });
+    }
+    const candidates = args.runtimeId
+        ? catalog.runtimes.filter((runtime) => runtime.id === args.runtimeId)
+        : catalog.runtimes;
+    if (candidates.length === 0) {
+        throw new ConnectError({
+            phase: "catalog",
+            code: "unsupported_runtime",
+            message: args.runtimeId
+                ? `Unknown runtime "${args.runtimeId}". Known: ${catalog.runtimes
+                    .map((runtime) => runtime.id)
+                    .join(", ")}`
+                : "The server's runtime catalog is empty.",
+        });
+    }
+    reporter.emit({
+        phase: "catalog",
+        status: "done",
+        message: `Catalog: ${candidates.map((runtime) => runtime.label).join(", ")}`,
+    });
+    return candidates;
+}
+async function connect(args, reporter) {
+    const home = homedir();
+    const log = reporter.log;
+    const candidates = await loadCatalog(args, reporter);
+    reporter.progress("detect", "Detecting installed runtimes…");
+    const detections = await detectRuntimes(candidates, {
+        home,
+        extraBinDirs: scanPrivateNodes(defaultNodeRoot(home)).map((node) => node.nodeBinDir),
+    });
+    const target = pickTarget(detections, args.runtimeId);
+    const runtime = target.runtime;
+    if (runtime.id !== "openclaw") {
+        throw new ConnectError({
+            phase: "detect",
+            code: "unsupported_runtime",
+            message: `This pllla-connect build has no bridge adapter for "${runtime.id}" yet. Run the latest: npx pllla-connect@latest`,
+        });
+    }
+    if (!target.binaryPath && (target.stateDirFound || target.gatewayLive)) {
+        // Installed somewhere we cannot see — a second install is exactly the
+        // trap §6.2 forbids, so stop and let a shell with the real PATH finish.
+        throw new ConnectError({
+            phase: "detect",
+            code: "bridge_failed",
+            message: `${runtime.label} looks installed (${[
+                target.stateDirFound ? "state dir found" : "",
+                target.gatewayLive ? "gateway answering" : "",
+            ]
+                .filter(Boolean)
+                .join(", ")}) but its CLI was not found in any known location. Open a terminal where \`${runtime.detect.commands[0]}\` works and run the connect command there.`,
+            manualCommand: buildConnectCommand(args),
+        });
+    }
+    const assertVersion = (binaryPath, version) => {
+        if (version && compareVersions(version, runtime.runtime.minVersion) < 0) {
+            throw new ConnectError({
+                phase: "detect",
+                code: "version_too_old",
+                message: `${runtime.label} ${version} is older than ${runtime.runtime.minVersion}, the first version with the PLLLA bridge extension point. Update it yourself (PLLLA never updates your install), then re-run.`,
+                manualCommand: `${shellQuote(binaryPath)} update`,
+            });
+        }
+    };
+    const accountId = args.accountId ?? deriveAccountId(args.pairingToken);
+    const nodeProgress = (message) => reporter.progress("node", message);
+    if (target.binaryPath) {
+        const binaryPath = target.binaryPath;
+        assertVersion(binaryPath, target.version);
+        reporter.emit({
+            phase: "detect",
+            status: "done",
+            message: `Found ${runtime.label} ${target.version ?? "(version unknown)"} at ${binaryPath}${target.gatewayLive ? " (gateway running)" : ""}.`,
+        });
+        reporter.progress("node", `Checking for a Node ${runtime.label} accepts…`);
+        const node = await resolveNodeForRuntime({
+            nodeRange: runtime.runtime.nodeRange,
+            provisionNodeMajor: runtime.runtime.provisionNodeMajor,
+            home,
+            preferredDirs: [dirname(binaryPath)],
+            log,
+            progress: nodeProgress,
+        });
+        reporter.emit({
+            phase: "node",
+            status: "done",
+            message: `Node ${node.version} (${node.source}).`,
+        });
+        if (!target.version) {
+            // Detection could not run the CLI (no node on the GUI PATH); now that
+            // a qualifying Node is known, read the version before touching config.
+            const version = probeRuntimeVersion(binaryPath, buildRuntimeEnv({ nodeBinDir: node.nodeBinDir, binaryPath, home }));
+            assertVersion(binaryPath, version);
+            if (!version) {
+                log(`Could not read ${runtime.label}'s version — continuing; the bridge step will surface a real incompatibility.`);
+            }
+        }
+        await runBridge({
+            reporter,
+            args,
+            runtime,
+            binaryPath,
+            nodeBinDir: node.nodeBinDir,
+            accountId,
+            home,
+        });
+        return accountId;
+    }
+    reporter.emit({
+        phase: "detect",
+        status: "done",
+        message: `${runtime.label} is not installed — PLLLA will install a private copy.`,
+    });
+    reporter.progress("node", `Preparing private Node ${runtime.runtime.provisionNodeMajor}…`);
+    const node = await ensurePrivateNode({
+        nodeRange: runtime.runtime.nodeRange,
+        provisionNodeMajor: runtime.runtime.provisionNodeMajor,
+        root: defaultNodeRoot(home),
+        log,
+        progress: nodeProgress,
+    });
+    reporter.emit({
+        phase: "node",
+        status: "done",
+        message: `Private Node ${node.version} ready.`,
+    });
+    reporter.progress("install", `Installing ${runtime.label}…`);
+    const installed = await installFresh({
+        nodeBin: node.nodeBin,
+        npmCli: node.npmCli,
+        prefix: privateRuntimePrefix(home, runtime.id),
+        home,
+        log,
+    });
+    reporter.emit({
+        phase: "install",
+        status: "done",
+        message: `${runtime.label} installed at ${installed.binaryPath}.`,
+    });
+    reporter.progress("onboard", "Looking for a model login on this machine…");
+    const auth = await resolveAuthChoice({
+        home,
+        nodeBinDir: node.nodeBinDir,
+        log,
+    });
+    if (!auth) {
+        throw new ConnectError({
+            phase: "onboard",
+            code: "needs_model_auth",
+            message: `${runtime.label} is installed but this machine has no model login: Claude Code is not signed in and Ollama has no models. Run the command below in a terminal, approve the device code it shows, then re-run this connect command.`,
+            manualCommand: buildManualOnboardCommand({
+                binaryPath: installed.binaryPath,
+                nodeBinDir: node.nodeBinDir,
+            }),
+        });
+    }
+    log(auth.detail);
+    if (auth.warning)
+        log(`Warning: ${auth.warning}`);
+    reporter.progress("onboard", `Setting up the brain (${auth.choice})…`);
+    await onboardFresh({
+        binaryPath: installed.binaryPath,
+        authChoice: auth.choice,
+        nodeBinDir: node.nodeBinDir,
+        home,
+        log,
+    });
+    reporter.emit({
+        phase: "onboard",
+        status: "done",
+        message: `Brain ready (${auth.choice}).`,
+    });
+    await runBridge({
+        reporter,
+        args,
+        runtime,
+        binaryPath: installed.binaryPath,
+        nodeBinDir: node.nodeBinDir,
+        accountId,
+        home,
+    });
+    return accountId;
+}
+async function runBridge(params) {
+    const { reporter, args, runtime, binaryPath, nodeBinDir, accountId, home } = params;
+    reporter.progress("bridge", `Connecting ${runtime.label} to PLLLA…`);
+    let bridged;
+    try {
+        bridged = await bridgeExisting({
+            binaryPath,
+            nodeBinDir,
+            accountId,
+            pairingToken: args.pairingToken,
+            serverOrigin: args.serverOrigin,
+            bridgePackage: runtime.bridge.package,
+            home,
+            log: reporter.log,
+        });
+    }
+    catch (error) {
+        throw toConnectError(error, "bridge", "bridge_failed");
+    }
+    reporter.emit({
+        phase: "bridge",
+        status: "done",
+        message: bridged.gatewayRestarted
+            ? "Bridge configured; gateway restarted."
+            : "Bridge configured; start the gateway to pair.",
+    });
+    reporter.progress("pair", "The bridge pairs with PLLLA when the gateway starts — the connect card flips to Connected and the agent sends its first greeting.");
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const reporter = createProgressReporter({ json: argv.includes("--json") });
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (error) {
+        reporter.log(`pllla-connect: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+    try {
+        const account = await connect(args, reporter);
+        reporter.emit({
+            phase: "done",
+            status: "done",
+            account,
+            message: "Watch the agent's chat in PLLLA for the first greeting.",
+        });
+        return 0;
+    }
+    catch (error) {
+        const failure = toConnectError(error, "bridge");
+        reporter.emit({
+            phase: failure.phase,
+            status: "error",
+            code: failure.code,
+            message: failure.message,
+            manualCommand: failure.manualCommand,
+        });
+        return failure.code === "needs_model_auth" ? EXIT_NEEDS_MODEL_AUTH : 1;
+    }
+}
+main().then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    console.error(`\npllla-connect crashed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+    process.exitCode = 1;
+});

package/dist/nodeProvision.js

@@ -0,0 +1,269 @@
+/**
+ * Private Node provisioning (docs/agent/EXTERNAL_RUNTIME.md §6.1).
+ *
+ * PLLLA never upgrades or touches the user's system Node / global npm — that
+ * breaks their other projects. A runtime that needs a newer Node gets its own
+ * copy under `~/.pllla/runtimes/node/<version>/`, straight from the official
+ * nodejs.org tarball with SHASUMS256 verification. Electron-as-node is not an
+ * option here: the runtime's native modules (koffi, tree-sitter, …) need a
+ * real Node ABI.
+ *
+ * Which major to provision (`provisionNodeMajor`) and which versions qualify
+ * (`nodeRange`) are server-decided catalog fields. Network and filesystem
+ * work is isolated in `ensurePrivateNode`; everything it decides with is a
+ * pure function below so it can be unit-tested without a download.
+ */
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { createWriteStream, existsSync, mkdirSync, readdirSync, renameSync, rmSync, } from "node:fs";
+import { once } from "node:events";
+import { finished } from "node:stream/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { runCommand } from "./exec.js";
+import { ConnectError } from "./progress.js";
+import { compareVersions, formatVersion, parseVersion, satisfiesNodeRange, } from "./version.js";
+export const NODE_DIST_ORIGIN = "https://nodejs.org/dist";
+export function defaultNodeRoot(home = homedir()) {
+    return join(home, ".pllla", "runtimes", "node");
+}
+export function toDistPlatform(platform) {
+    if (platform === "darwin" || platform === "linux")
+        return platform;
+    return null;
+}
+export function toDistArch(arch) {
+    if (arch === "arm64" || arch === "x64")
+        return arch;
+    return null;
+}
+/** `node-v26.0.0-darwin-arm64.tar.gz` */
+export function tarballName(version, platform, arch) {
+    const parsed = parseVersion(version);
+    if (!parsed)
+        throw new Error(`Not a Node version: "${version}"`);
+    return `node-v${formatVersion(parsed)}-${platform}-${arch}.tar.gz`;
+}
+/** The `files` key nodejs.org lists for a platform tarball (`osx-arm64-tar`, `linux-x64`). */
+export function distFileKey(platform, arch) {
+    return platform === "darwin" ? `osx-${arch}-tar` : `linux-${arch}`;
+}
+/**
+ * Highest release of `major` from the dist index (optionally only releases
+ * that ship `requiredFile`). The index lists releases only, so "highest" is
+ * "latest stable"; null when the major has no matching release.
+ */
+export function pickLatestOfMajor(entries, major, requiredFile) {
+    let best = null;
+    for (const entry of entries) {
+        const parsed = parseVersion(entry.version);
+        if (!parsed || parsed.major !== major)
+            continue;
+        if (requiredFile && !(entry.files ?? []).includes(requiredFile))
+            continue;
+        if (!best || compareVersions(parsed, best.parsed) > 0) {
+            best = { entry, parsed };
+        }
+    }
+    return best?.entry ?? null;
+}
+/** `SHASUMS256.txt` → filename → sha256 (hex, lowercase). */
+export function parseShasums(text) {
+    const map = new Map();
+    for (const line of text.split("\n")) {
+        const match = /^([0-9a-fA-F]{64})\s+\*?(\S+)\s*$/.exec(line.trim());
+        if (match)
+            map.set(match[2], match[1].toLowerCase());
+    }
+    return map;
+}
+/** Complete installs under `<root>` (a `bin/node` exists), newest first. */
+export function scanPrivateNodes(root) {
+    let names;
+    try {
+        names = readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of names) {
+        const parsed = parseVersion(name);
+        if (!parsed)
+            continue;
+        const dir = join(root, name);
+        const nodeBinDir = join(dir, "bin");
+        const nodeBin = join(nodeBinDir, "node");
+        if (!existsSync(nodeBin))
+            continue;
+        found.push({
+            version: formatVersion(parsed),
+            dir,
+            nodeBin,
+            nodeBinDir,
+            npmCli: join(dir, "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+        });
+    }
+    return found.sort((a, b) => compareVersions(b.version, a.version));
+}
+/** The newest installed private Node that satisfies `nodeRange`. */
+export function pickPrivateNode(installed, nodeRange) {
+    return (installed
+        .filter((node) => satisfiesNodeRange(node.version, nodeRange))
+        .sort((a, b) => compareVersions(b.version, a.version))[0] ?? null);
+}
+async function fetchText(url) {
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status} for ${url}`);
+    return response.text();
+}
+/** Streams `url` to `dest`, hashing on the fly. Returns the sha256 hex. */
+async function downloadToFile(url, dest, onProgress) {
+    const response = await fetch(url);
+    if (!response.ok || !response.body) {
+        throw new Error(`HTTP ${response.status} for ${url}`);
+    }
+    const total = Number(response.headers.get("content-length") ?? 0);
+    const hash = createHash("sha256");
+    const reader = response.body.getReader();
+    const out = createWriteStream(dest);
+    let received = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            hash.update(value);
+            received += value.byteLength;
+            if (!out.write(value))
+                await once(out, "drain");
+            onProgress(received, total);
+        }
+    }
+    finally {
+        out.end();
+    }
+    await finished(out);
+    return hash.digest("hex");
+}
+function provisionError(message, cause) {
+    return new ConnectError({
+        phase: "node",
+        code: "node_provision_failed",
+        message,
+        cause,
+    });
+}
+function formatMegabytes(bytes) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * Reuses a private Node that satisfies `nodeRange`, otherwise downloads the
+ * newest release of `provisionNodeMajor` into `<root>/<version>/` (staged as
+ * `<version>.partial` and renamed only after the checksum, extraction, and a
+ * `--version` sanity run all pass, so a crashed download never masquerades
+ * as an install). Windows is refused honestly — no tar.gz layout there.
+ */
+export async function ensurePrivateNode(params) {
+    const { nodeRange, provisionNodeMajor, log, progress } = params;
+    const root = params.root ?? defaultNodeRoot();
+    const reusable = pickPrivateNode(scanPrivateNodes(root), nodeRange);
+    if (reusable) {
+        log(`Reusing private Node ${reusable.version} at ${reusable.dir}.`);
+        return reusable;
+    }
+    const platform = toDistPlatform(params.platform ?? process.platform);
+    const arch = toDistArch(params.arch ?? process.arch);
+    if (!platform || !arch) {
+        throw provisionError(`Private Node provisioning supports macOS and Linux (arm64/x64) only — this machine is ${params.platform ?? process.platform}/${params.arch ?? process.arch}. Install Node ${provisionNodeMajor} yourself and re-run.`);
+    }
+    progress(`Preparing private Node ${provisionNodeMajor}…`);
+    let index;
+    try {
+        const parsed = JSON.parse(await fetchText(`${NODE_DIST_ORIGIN}/index.json`));
+        if (!Array.isArray(parsed))
+            throw new Error("index.json is not a list");
+        index = parsed;
+    }
+    catch (error) {
+        throw provisionError(`Could not read the Node release index from nodejs.org: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+    const release = pickLatestOfMajor(index, provisionNodeMajor, distFileKey(platform, arch));
+    if (!release) {
+        throw provisionError(`nodejs.org lists no Node ${provisionNodeMajor} release for ${platform}-${arch}.`);
+    }
+    const version = formatVersion(parseVersion(release.version));
+    if (!satisfiesNodeRange(version, nodeRange)) {
+        throw provisionError(`The server asks for Node ${provisionNodeMajor} (found ${version}) but its own range "${nodeRange}" rejects it — catalog misconfiguration.`);
+    }
+    const archive = tarballName(version, platform, arch);
+    const releaseUrl = `${NODE_DIST_ORIGIN}/v${version}`;
+    const finalDir = join(root, version);
+    const stagingDir = `${finalDir}.partial`;
+    const downloadsDir = join(root, ".downloads");
+    const archivePath = join(downloadsDir, archive);
+    mkdirSync(downloadsDir, { recursive: true });
+    rmSync(stagingDir, { recursive: true, force: true });
+    rmSync(archivePath, { force: true });
+    try {
+        progress(`Downloading Node ${version} (${archive})…`);
+        const shasums = parseShasums(await fetchText(`${releaseUrl}/SHASUMS256.txt`));
+        const expected = shasums.get(archive);
+        if (!expected) {
+            throw new Error(`SHASUMS256.txt has no entry for ${archive}`);
+        }
+        let lastPercent = -1;
+        let lastBytes = 0;
+        const actual = await downloadToFile(`${releaseUrl}/${archive}`, archivePath, (received, total) => {
+            if (total > 0) {
+                const percent = Math.floor((received / total) * 20) * 5;
+                if (percent !== lastPercent) {
+                    lastPercent = percent;
+                    progress(`Downloading Node ${version}… ${percent}%`);
+                }
+            }
+            else if (received - lastBytes >= 8 * 1024 * 1024) {
+                lastBytes = received;
+                progress(`Downloading Node ${version}… ${formatMegabytes(received)}`);
+            }
+        });
+        if (actual !== expected) {
+            throw new Error(`Checksum mismatch for ${archive} (expected ${expected}, got ${actual})`);
+        }
+        progress(`Extracting Node ${version}…`);
+        mkdirSync(stagingDir, { recursive: true });
+        await runCommand({
+            file: "tar",
+            args: ["-xzf", archivePath, "-C", stagingDir, "--strip-components=1"],
+            timeoutMs: 10 * 60_000,
+            onLine: log,
+        });
+        const nodeBin = join(stagingDir, "bin", "node");
+        const reported = execFileSync(nodeBin, ["--version"], {
+            encoding: "utf8",
+            timeout: 20_000,
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+        if (reported !== `v${version}`) {
+            throw new Error(`Extracted node reports ${reported || "nothing"}, expected v${version}`);
+        }
+        rmSync(finalDir, { recursive: true, force: true });
+        renameSync(stagingDir, finalDir);
+    }
+    catch (error) {
+        rmSync(stagingDir, { recursive: true, force: true });
+        throw provisionError(`Private Node ${version} could not be provisioned: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+    finally {
+        rmSync(archivePath, { force: true });
+    }
+    log(`Private Node ${version} ready at ${finalDir}.`);
+    return {
+        version,
+        dir: finalDir,
+        nodeBin: join(finalDir, "bin", "node"),
+        nodeBinDir: join(finalDir, "bin"),
+        npmCli: join(finalDir, "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+    };
+}