@automaton-labs/aib 0.0.7 → 0.0.9

package/scripts/provision-runtime.cjs

@@ -1,459 +1,411 @@
-#!/usr/bin/env node
-
-const fs = require("node:fs");
-const os = require("node:os");
-const path = require("node:path");
-const crypto = require("node:crypto");
-const http = require("node:http");
-const https = require("node:https");
-const { spawnSync } = require("node:child_process");
-
-const packageRoot = path.resolve(__dirname, "..");
-const runtimesDir = path.join(packageRoot, "runtimes");
-const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
-const platformKey = `${process.platform}-${process.arch}`;
-
-const options = parseArgs(process.argv.slice(2));
-const reporter = createReporter(!options.quiet);
-
-main().catch((error) => {
-  if (!options.quiet) {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-  }
-  process.exitCode = 1;
-});
-
-async function main() {
-  cleanupOldTempDownloads();
-
-  if (runtimeComplete()) {
-    if (!options.quiet) {
-      reporter.info(`aib runtime ready: ${path.relative(process.cwd(), runtimesDir) || runtimesDir}`);
-    }
-    return;
-  }
-
-  const source = options.archive
-    ?? process.env.AIB_RUNTIME_ARCHIVE
-    ?? process.env.npm_config_aib_runtime_archive
-    ?? null;
-  const url = options.url
-    ?? process.env.AIB_RUNTIME_URL
-    ?? process.env.npm_config_aib_runtime_url
-    ?? null;
-  const manifestSource = options.manifest
-    ?? process.env.AIB_RUNTIME_MANIFEST
-    ?? process.env.npm_config_aib_runtime_manifest
-    ?? null;
-  const manifestUrl = options.manifestUrl
-    ?? process.env.AIB_RUNTIME_MANIFEST_URL
-    ?? process.env.npm_config_aib_runtime_manifest_url
-    ?? defaultManifestUrl();
-
-  if (!source && !url && !manifestSource && !manifestUrl) {
-    if (!options.quiet) {
-      reporter.info("aib runtime not provisioned: set AIB_RUNTIME_ARCHIVE, AIB_RUNTIME_URL, AIB_RUNTIME_MANIFEST, or AIB_RUNTIME_MANIFEST_URL");
-    }
-    return;
-  }
-
-  reporter.info(`aib runtime: provisioning ${platformKey}`);
-  const resolution = source || url
-    ? { ...(source ? { archivePath: path.resolve(source), tempDir: null } : await downloadRuntimeArchive(url, "runtime archive")), expectedSha256: options.sha256 ?? process.env.AIB_RUNTIME_SHA256 ?? null }
-    : await resolveFromManifest(manifestSource, manifestUrl);
-  const archivePath = resolution.archivePath;
-  try {
-    if (!fs.existsSync(archivePath)) {
-      throw new Error(`Runtime archive not found: ${archivePath}`);
-    }
-    if (resolution.expectedSha256) {
-      reporter.info("aib runtime: verifying checksum");
-      assertSha256(archivePath, resolution.expectedSha256);
-    }
-
-    fs.mkdirSync(runtimesDir, { recursive: true });
-    reporter.info("aib runtime: extracting archive");
-    extractRuntimeArchive(archivePath);
-
-    if (!runtimeComplete()) {
-      throw new Error(`Runtime archive did not provision a complete runtime under ${runtimesDir}`);
-    }
-  } finally {
-    cleanupOwnedTempDownload(resolution.tempDir);
-  }
-
-  if (!options.quiet) {
-    reporter.info("aib runtime: ready");
-  }
-}
-
-function parseArgs(argv) {
-  const parsed = {
-    archive: null,
-    url: null,
-    manifest: null,
-    manifestUrl: null,
-    sha256: null,
-    quiet: false
-  };
-  for (let index = 0; index < argv.length; index += 1) {
-    const current = argv[index];
-    const next = argv[index + 1];
-    if (current === "--archive" && next) {
-      parsed.archive = next;
-      index += 1;
-      continue;
-    }
-    if (current === "--url" && next) {
-      parsed.url = next;
-      index += 1;
-      continue;
-    }
-    if (current === "--manifest" && next) {
-      parsed.manifest = next;
-      index += 1;
-      continue;
-    }
-    if (current === "--manifest-url" && next) {
-      parsed.manifestUrl = next;
-      index += 1;
-      continue;
-    }
-    if (current === "--sha256" && next) {
-      parsed.sha256 = next;
-      index += 1;
-      continue;
-    }
-    if (current === "--quiet") {
-      parsed.quiet = true;
-      continue;
-    }
-    throw new Error(`Unknown argument: ${current}`);
-  }
-  return parsed;
-}
-
-async function resolveFromManifest(manifestSource, manifestUrl) {
-  reporter.info("aib runtime: resolving manifest");
-  const manifest = manifestSource
-    ? JSON.parse(fs.readFileSync(path.resolve(manifestSource), "utf8"))
-    : await downloadJson(manifestUrl);
-  const artifact = manifest?.artifacts?.[platformKey];
-  if (!artifact || typeof artifact !== "object") {
-    throw new Error(`Runtime manifest does not contain an artifact for ${platformKey}`);
-  }
-  const archivePath = artifact.file && manifestSource
-    ? path.resolve(path.dirname(path.resolve(manifestSource)), String(artifact.file))
-    : null;
-  const downloaded = !archivePath && artifact.url
-    ? await downloadRuntimeArchive(String(artifact.url))
-    : null;
-  const resolvedArchivePath = archivePath ?? downloaded?.archivePath ?? null;
-  const tempDir = downloaded?.tempDir ?? null;
-  if (!resolvedArchivePath) {
-    throw new Error(`Runtime manifest artifact for ${platformKey} has no url or local file.`);
-  }
-  return {
-    archivePath: resolvedArchivePath,
-    tempDir,
-    expectedSha256: typeof artifact.sha256 === "string" ? artifact.sha256 : null
-  };
-}
-
-async function downloadJson(url) {
-  const download = await downloadRuntimeArchive(url, "runtime manifest");
-  try {
-    return JSON.parse(fs.readFileSync(download.archivePath, "utf8"));
-  } finally {
-    cleanupOwnedTempDownload(download.tempDir);
-  }
-}
-
-function cleanupOldTempDownloads() {
-  const cutoffMs = Date.now() - 24 * 60 * 60 * 1000;
-  let entries = [];
-  try {
-    entries = fs.readdirSync(os.tmpdir(), { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    if (!entry.isDirectory() || !entry.name.startsWith("aib-runtime-")) {
-      continue;
-    }
-    const tempDir = path.join(os.tmpdir(), entry.name);
-    try {
-      const stat = fs.statSync(tempDir);
-      if (stat.mtimeMs < cutoffMs) {
-        fs.rmSync(tempDir, { recursive: true, force: true });
-      }
-    } catch {
-      // Best-effort cleanup only.
-    }
-  }
-}
-
-function cleanupOwnedTempDownload(tempDir) {
-  if (!tempDir) {
-    return;
-  }
-  try {
-    const resolvedTemp = path.resolve(tempDir);
-    const resolvedOsTemp = path.resolve(os.tmpdir());
-    const relative = path.relative(resolvedOsTemp, resolvedTemp);
-    if (path.basename(resolvedTemp).startsWith("aib-runtime-")
-      && relative
-      && !relative.startsWith("..")
-      && !path.isAbsolute(relative)) {
-      fs.rmSync(resolvedTemp, { recursive: true, force: true });
-    }
-  } catch {
-    // Best-effort cleanup only.
-  }
-}
-
-function defaultManifestUrl() {
-  const version = packageJson.version;
-  if (!version) {
-    return null;
-  }
-  return `https://github.com/ratiomark/aib-runtime/releases/download/v${version}/aib-runtime-manifest.json`;
-}
-
-function runtimeComplete() {
-  return fs.existsSync(path.join(runtimesDir, "code-server", "node_modules", "code-server", "out", "node", "entry.js"))
-    && Boolean(findPackagedBrowserRuntime())
-    && Boolean(findPackagedNodeRuntime())
-    && runtimePlatformStatus().ok;
-}
-
-function runtimePlatformStatus() {
-  const markerPath = path.join(runtimesDir, ".aib-runtime-platform.json");
-  if (!fs.existsSync(markerPath)) {
-    return { ok: true, reason: "missing", expectedPlatformKey: platformKey, actualPlatformKey: null };
-  }
-  try {
-    const marker = JSON.parse(fs.readFileSync(markerPath, "utf8"));
-    const actualPlatformKey = typeof marker.platformKey === "string"
-      ? marker.platformKey
-      : typeof marker.platform === "string" && typeof marker.arch === "string"
-        ? `${marker.platform}-${marker.arch}`
-        : null;
-    return {
-      ok: actualPlatformKey === platformKey,
-      reason: actualPlatformKey === platformKey ? "ok" : "mismatch",
-      expectedPlatformKey: platformKey,
-      actualPlatformKey
-    };
-  } catch {
-    return { ok: false, reason: "invalid", expectedPlatformKey: platformKey, actualPlatformKey: null };
-  }
-}
-
-function findPackagedNodeRuntime() {
-  const platformDir = nodeRuntimePlatformDir();
-  if (!platformDir) {
-    return null;
-  }
-  const candidate = process.platform === "win32"
-    ? path.join(runtimesDir, "node", platformDir, "node.exe")
-    : path.join(runtimesDir, "node", platformDir, "bin", "node");
-  return fs.existsSync(candidate) ? candidate : null;
-}
-
-function nodeRuntimePlatformDir() {
-  if (process.platform === "win32" && process.arch === "x64") {
-    return "win-x64";
-  }
-  if (process.platform === "linux" && process.arch === "x64") {
-    return "linux-x64";
-  }
-  if (process.platform === "linux" && process.arch === "arm64") {
-    return "linux-arm64";
-  }
-  if (process.platform === "darwin" && process.arch === "x64") {
-    return "darwin-x64";
-  }
-  if (process.platform === "darwin" && process.arch === "arm64") {
-    return "darwin-arm64";
-  }
-  return null;
-}
-
-function findPackagedBrowserRuntime() {
-  const roots = [
-    path.join(runtimesDir, "browser"),
-    path.join(runtimesDir, "chrome"),
-    path.join(runtimesDir, "chromium")
-  ];
-  const executableNames = process.platform === "win32"
-    ? new Set(["chrome.exe", "chromium.exe", "msedge.exe"])
-    : new Set(["chrome", "chromium"]);
-  for (const root of roots) {
-    const found = findFirstExecutable(root, executableNames, 5);
-    if (found) {
-      return found;
-    }
-  }
-  return null;
-}
-
-function findFirstExecutable(root, executableNames, maxDepth) {
-  if (!fs.existsSync(root) || maxDepth < 0) {
-    return null;
-  }
-  let entries;
-  try {
-    entries = fs.readdirSync(root, { withFileTypes: true });
-  } catch {
-    return null;
-  }
-  for (const entry of entries) {
-    const entryPath = path.join(root, entry.name);
-    if (entry.isFile() && executableNames.has(entry.name)) {
-      return entryPath;
-    }
-  }
-  for (const entry of entries) {
-    if (!entry.isDirectory()) {
-      continue;
-    }
-    const found = findFirstExecutable(path.join(root, entry.name), executableNames, maxDepth - 1);
-    if (found) {
-      return found;
-    }
-  }
-  return null;
-}
-
-function extractRuntimeArchive(archivePath) {
-  const result = spawnSync("tar", ["-xzf", archivePath, "-C", packageRoot], {
-    cwd: packageRoot,
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
-    windowsHide: true,
-    timeout: 600_000
-  });
-  if (result.status !== 0) {
-    throw new Error(`Failed to extract runtime archive: ${result.stderr || result.stdout || result.error?.message || `status ${result.status}`}`);
-  }
-}
-
-function assertSha256(filePath, expectedSha256) {
-  const hash = crypto.createHash("sha256");
-  hash.update(fs.readFileSync(filePath));
-  const actual = hash.digest("hex");
-  if (actual.toLowerCase() !== String(expectedSha256).toLowerCase()) {
-    throw new Error(`Runtime archive checksum mismatch: expected ${expectedSha256}, got ${actual}`);
-  }
-}
-
-function downloadRuntimeArchive(url, label = "runtime archive") {
-  return new Promise((resolve, reject) => {
-    if (!url) {
-      reject(new Error("Runtime URL is empty."));
-      return;
-    }
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "aib-runtime-"));
-    const targetPath = path.join(tempDir, path.basename(new URL(url).pathname) || "runtime.tgz");
-    const file = fs.createWriteStream(targetPath);
-    const client = url.startsWith("https:") ? https : http;
-    const request = client.get(url, (response) => {
-      if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
-        file.close();
-        fs.rmSync(targetPath, { force: true });
-        cleanupOwnedTempDownload(tempDir);
-        downloadRuntimeArchive(new URL(response.headers.location, url).toString(), label).then(resolve, reject);
-        return;
-      }
-      if (response.statusCode !== 200) {
-        file.close();
-        fs.rmSync(targetPath, { force: true });
-        cleanupOwnedTempDownload(tempDir);
-        reject(new Error(`Runtime download failed with HTTP ${response.statusCode}: ${url}`));
-        return;
-      }
-      const totalBytes = Number.parseInt(String(response.headers["content-length"] ?? ""), 10);
-      const progress = reporter.startProgress(`aib runtime: downloading ${label}`, Number.isFinite(totalBytes) ? totalBytes : null);
-      response.on("data", (chunk) => progress.add(chunk.length));
-      response.pipe(file);
-      file.on("finish", () => {
-        file.close(() => {
-          progress.done();
-          resolve({ archivePath: targetPath, tempDir });
-        });
-      });
-    });
-    request.on("error", (error) => {
-      file.close();
-      fs.rmSync(targetPath, { force: true });
-      cleanupOwnedTempDownload(tempDir);
-      reject(error);
-    });
-  });
-}
-
-function createReporter(enabled) {
-  const stream = process.stderr;
-  return {
-    info(message) {
-      if (!enabled) {
-        return;
-      }
-      stream.write(`${message}\n`);
-    },
-    startProgress(label, totalBytes) {
-      if (!enabled) {
-        return { add() {}, done() {} };
-      }
-      let downloadedBytes = 0;
-      let ended = false;
-      let nextPercent = 10;
-      const totalKnown = Number.isFinite(totalBytes) && totalBytes > 0;
-      const showPercentProgress = totalKnown && totalBytes >= 1024 * 1024;
-      stream.write(totalKnown
-        ? `${label} ${formatBytes(totalBytes)}\n`
-        : `${label}\n`);
-      const writeProgress = () => {
-        if (!showPercentProgress) {
-          return;
-        }
-        const percent = Math.floor(Math.min(100, (downloadedBytes / totalBytes) * 100));
-        while (percent >= nextPercent && nextPercent <= 100) {
-          const thresholdBytes = Math.min(totalBytes, Math.round((totalBytes * nextPercent) / 100));
-          stream.write(`aib runtime: ${nextPercent}% ${formatBytes(thresholdBytes)} / ${formatBytes(totalBytes)}\n`);
-          nextPercent += 10;
-        }
-      };
-      return {
-        add(byteCount) {
-          downloadedBytes += byteCount;
-          writeProgress();
-        },
-        done() {
-          if (ended) {
-            return;
-          }
-          ended = true;
-          downloadedBytes = Math.max(downloadedBytes, totalBytes ?? downloadedBytes);
-          writeProgress();
-        }
-      };
-    }
-  };
-}
-
-function formatBytes(bytes) {
-  if (!Number.isFinite(bytes) || bytes < 0) {
-    return "0 B";
-  }
-  const units = ["B", "KB", "MB", "GB"];
-  let value = bytes;
-  let unitIndex = 0;
-  while (value >= 1024 && unitIndex < units.length - 1) {
-    value /= 1024;
-    unitIndex += 1;
-  }
-  const digits = value >= 100 || unitIndex === 0 ? 0 : value >= 10 ? 1 : 2;
-  return `${value.toFixed(digits)} ${units[unitIndex]}`;
-}
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const http = require("node:http");
+const https = require("node:https");
+const { spawnSync } = require("node:child_process");
+
+const packageRoot = path.resolve(__dirname, "..");
+const runtimesDir = path.join(packageRoot, "runtimes");
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+const platformKey = `${process.platform}-${process.arch}`;
+
+const options = parseArgs(process.argv.slice(2));
+const reporter = createReporter(!options.quiet);
+
+main().catch((error) => {
+  if (!options.quiet) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  }
+  process.exitCode = 1;
+});
+
+async function main() {
+  cleanupOldTempDownloads();
+
+  if (runtimeComplete()) {
+    if (!options.quiet) {
+      reporter.info(`aib runtime ready: ${path.relative(process.cwd(), runtimesDir) || runtimesDir}`);
+    }
+    return;
+  }
+
+  const source = options.archive
+    ?? process.env.AIB_RUNTIME_ARCHIVE
+    ?? process.env.npm_config_aib_runtime_archive
+    ?? null;
+  const url = options.url
+    ?? process.env.AIB_RUNTIME_URL
+    ?? process.env.npm_config_aib_runtime_url
+    ?? null;
+  const manifestSource = options.manifest
+    ?? process.env.AIB_RUNTIME_MANIFEST
+    ?? process.env.npm_config_aib_runtime_manifest
+    ?? null;
+  const manifestUrl = options.manifestUrl
+    ?? process.env.AIB_RUNTIME_MANIFEST_URL
+    ?? process.env.npm_config_aib_runtime_manifest_url
+    ?? defaultManifestUrl();
+
+  if (!source && !url && !manifestSource && !manifestUrl) {
+    if (!options.quiet) {
+      reporter.info("aib runtime not provisioned: set AIB_RUNTIME_ARCHIVE, AIB_RUNTIME_URL, AIB_RUNTIME_MANIFEST, or AIB_RUNTIME_MANIFEST_URL");
+    }
+    return;
+  }
+
+  reporter.info(`aib runtime: provisioning ${platformKey}`);
+  const resolution = source || url
+    ? { ...(source ? { archivePath: path.resolve(source), tempDir: null } : await downloadRuntimeArchive(url, "runtime archive")), expectedSha256: options.sha256 ?? process.env.AIB_RUNTIME_SHA256 ?? null }
+    : await resolveFromManifest(manifestSource, manifestUrl);
+  const archivePath = resolution.archivePath;
+  try {
+    if (!fs.existsSync(archivePath)) {
+      throw new Error(`Runtime archive not found: ${archivePath}`);
+    }
+    if (resolution.expectedSha256) {
+      reporter.info("aib runtime: verifying checksum");
+      assertSha256(archivePath, resolution.expectedSha256);
+    }
+
+    fs.mkdirSync(runtimesDir, { recursive: true });
+    reporter.info("aib runtime: extracting archive");
+    extractRuntimeArchive(archivePath);
+
+    if (!runtimeComplete()) {
+      throw new Error(`Runtime archive did not provision a complete runtime under ${runtimesDir}`);
+    }
+  } finally {
+    cleanupOwnedTempDownload(resolution.tempDir);
+  }
+
+  if (!options.quiet) {
+    reporter.info("aib runtime: ready");
+  }
+}
+
+function parseArgs(argv) {
+  const parsed = {
+    archive: null,
+    url: null,
+    manifest: null,
+    manifestUrl: null,
+    sha256: null,
+    quiet: false
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const current = argv[index];
+    const next = argv[index + 1];
+    if (current === "--archive" && next) {
+      parsed.archive = next;
+      index += 1;
+      continue;
+    }
+    if (current === "--url" && next) {
+      parsed.url = next;
+      index += 1;
+      continue;
+    }
+    if (current === "--manifest" && next) {
+      parsed.manifest = next;
+      index += 1;
+      continue;
+    }
+    if (current === "--manifest-url" && next) {
+      parsed.manifestUrl = next;
+      index += 1;
+      continue;
+    }
+    if (current === "--sha256" && next) {
+      parsed.sha256 = next;
+      index += 1;
+      continue;
+    }
+    if (current === "--quiet") {
+      parsed.quiet = true;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${current}`);
+  }
+  return parsed;
+}
+
+async function resolveFromManifest(manifestSource, manifestUrl) {
+  reporter.info("aib runtime: resolving manifest");
+  const manifest = manifestSource
+    ? JSON.parse(fs.readFileSync(path.resolve(manifestSource), "utf8"))
+    : await downloadJson(manifestUrl);
+  const artifact = manifest?.artifacts?.[platformKey];
+  if (!artifact || typeof artifact !== "object") {
+    throw new Error(`Runtime manifest does not contain an artifact for ${platformKey}`);
+  }
+  const archivePath = artifact.file && manifestSource
+    ? path.resolve(path.dirname(path.resolve(manifestSource)), String(artifact.file))
+    : null;
+  const downloaded = !archivePath && artifact.url
+    ? await downloadRuntimeArchive(String(artifact.url))
+    : null;
+  const resolvedArchivePath = archivePath ?? downloaded?.archivePath ?? null;
+  const tempDir = downloaded?.tempDir ?? null;
+  if (!resolvedArchivePath) {
+    throw new Error(`Runtime manifest artifact for ${platformKey} has no url or local file.`);
+  }
+  return {
+    archivePath: resolvedArchivePath,
+    tempDir,
+    expectedSha256: typeof artifact.sha256 === "string" ? artifact.sha256 : null
+  };
+}
+
+async function downloadJson(url) {
+  const download = await downloadRuntimeArchive(url, "runtime manifest");
+  try {
+    return JSON.parse(fs.readFileSync(download.archivePath, "utf8"));
+  } finally {
+    cleanupOwnedTempDownload(download.tempDir);
+  }
+}
+
+function cleanupOldTempDownloads() {
+  const cutoffMs = Date.now() - 24 * 60 * 60 * 1000;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(os.tmpdir(), { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.startsWith("aib-runtime-")) {
+      continue;
+    }
+    const tempDir = path.join(os.tmpdir(), entry.name);
+    try {
+      const stat = fs.statSync(tempDir);
+      if (stat.mtimeMs < cutoffMs) {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+      }
+    } catch {
+      // Best-effort cleanup only.
+    }
+  }
+}
+
+function cleanupOwnedTempDownload(tempDir) {
+  if (!tempDir) {
+    return;
+  }
+  try {
+    const resolvedTemp = path.resolve(tempDir);
+    const resolvedOsTemp = path.resolve(os.tmpdir());
+    const relative = path.relative(resolvedOsTemp, resolvedTemp);
+    if (path.basename(resolvedTemp).startsWith("aib-runtime-")
+      && relative
+      && !relative.startsWith("..")
+      && !path.isAbsolute(relative)) {
+      fs.rmSync(resolvedTemp, { recursive: true, force: true });
+    }
+  } catch {
+    // Best-effort cleanup only.
+  }
+}
+
+function defaultManifestUrl() {
+  const version = packageJson.version;
+  if (!version) {
+    return null;
+  }
+  return `https://github.com/ratiomark/aib-runtime/releases/download/v${version}/aib-runtime-manifest.json`;
+}
+
+function runtimeComplete() {
+  return Boolean(findPackagedNodeRuntime())
+    && runtimePlatformStatus().ok;
+}
+
+function runtimePlatformStatus() {
+  const markerPath = path.join(runtimesDir, ".aib-runtime-platform.json");
+  if (!fs.existsSync(markerPath)) {
+    return { ok: true, reason: "missing", expectedPlatformKey: platformKey, actualPlatformKey: null };
+  }
+  try {
+    const marker = JSON.parse(fs.readFileSync(markerPath, "utf8"));
+    const actualPlatformKey = typeof marker.platformKey === "string"
+      ? marker.platformKey
+      : typeof marker.platform === "string" && typeof marker.arch === "string"
+        ? `${marker.platform}-${marker.arch}`
+        : null;
+    return {
+      ok: actualPlatformKey === platformKey,
+      reason: actualPlatformKey === platformKey ? "ok" : "mismatch",
+      expectedPlatformKey: platformKey,
+      actualPlatformKey
+    };
+  } catch {
+    return { ok: false, reason: "invalid", expectedPlatformKey: platformKey, actualPlatformKey: null };
+  }
+}
+
+function findPackagedNodeRuntime() {
+  const platformDir = nodeRuntimePlatformDir();
+  if (!platformDir) {
+    return null;
+  }
+  const candidate = process.platform === "win32"
+    ? path.join(runtimesDir, "node", platformDir, "node.exe")
+    : path.join(runtimesDir, "node", platformDir, "bin", "node");
+  return fs.existsSync(candidate) ? candidate : null;
+}
+
+function nodeRuntimePlatformDir() {
+  if (process.platform === "win32" && process.arch === "x64") {
+    return "win-x64";
+  }
+  if (process.platform === "linux" && process.arch === "x64") {
+    return "linux-x64";
+  }
+  if (process.platform === "linux" && process.arch === "arm64") {
+    return "linux-arm64";
+  }
+  if (process.platform === "darwin" && process.arch === "x64") {
+    return "darwin-x64";
+  }
+  if (process.platform === "darwin" && process.arch === "arm64") {
+    return "darwin-arm64";
+  }
+  return null;
+}
+
+function extractRuntimeArchive(archivePath) {
+  const result = spawnSync("tar", ["-xzf", archivePath, "-C", packageRoot], {
+    cwd: packageRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+    timeout: 600_000
+  });
+  if (result.status !== 0) {
+    throw new Error(`Failed to extract runtime archive: ${result.stderr || result.stdout || result.error?.message || `status ${result.status}`}`);
+  }
+}
+
+function assertSha256(filePath, expectedSha256) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(filePath));
+  const actual = hash.digest("hex");
+  if (actual.toLowerCase() !== String(expectedSha256).toLowerCase()) {
+    throw new Error(`Runtime archive checksum mismatch: expected ${expectedSha256}, got ${actual}`);
+  }
+}
+
+function downloadRuntimeArchive(url, label = "runtime archive") {
+  return new Promise((resolve, reject) => {
+    if (!url) {
+      reject(new Error("Runtime URL is empty."));
+      return;
+    }
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "aib-runtime-"));
+    const targetPath = path.join(tempDir, path.basename(new URL(url).pathname) || "runtime.tgz");
+    const file = fs.createWriteStream(targetPath);
+    const client = url.startsWith("https:") ? https : http;
+    const request = client.get(url, (response) => {
+      if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        file.close();
+        fs.rmSync(targetPath, { force: true });
+        cleanupOwnedTempDownload(tempDir);
+        downloadRuntimeArchive(new URL(response.headers.location, url).toString(), label).then(resolve, reject);
+        return;
+      }
+      if (response.statusCode !== 200) {
+        file.close();
+        fs.rmSync(targetPath, { force: true });
+        cleanupOwnedTempDownload(tempDir);
+        reject(new Error(`Runtime download failed with HTTP ${response.statusCode}: ${url}`));
+        return;
+      }
+      const totalBytes = Number.parseInt(String(response.headers["content-length"] ?? ""), 10);
+      const progress = reporter.startProgress(`aib runtime: downloading ${label}`, Number.isFinite(totalBytes) ? totalBytes : null);
+      response.on("data", (chunk) => progress.add(chunk.length));
+      response.pipe(file);
+      file.on("finish", () => {
+        file.close(() => {
+          progress.done();
+          resolve({ archivePath: targetPath, tempDir });
+        });
+      });
+    });
+    request.on("error", (error) => {
+      file.close();
+      fs.rmSync(targetPath, { force: true });
+      cleanupOwnedTempDownload(tempDir);
+      reject(error);
+    });
+  });
+}
+
+function createReporter(enabled) {
+  const stream = process.stderr;
+  return {
+    info(message) {
+      if (!enabled) {
+        return;
+      }
+      stream.write(`${message}\n`);
+    },
+    startProgress(label, totalBytes) {
+      if (!enabled) {
+        return { add() {}, done() {} };
+      }
+      let downloadedBytes = 0;
+      let ended = false;
+      let nextPercent = 10;
+      const totalKnown = Number.isFinite(totalBytes) && totalBytes > 0;
+      const showPercentProgress = totalKnown && totalBytes >= 1024 * 1024;
+      stream.write(totalKnown
+        ? `${label} ${formatBytes(totalBytes)}\n`
+        : `${label}\n`);
+      const writeProgress = () => {
+        if (!showPercentProgress) {
+          return;
+        }
+        const percent = Math.floor(Math.min(100, (downloadedBytes / totalBytes) * 100));
+        while (percent >= nextPercent && nextPercent <= 100) {
+          const thresholdBytes = Math.min(totalBytes, Math.round((totalBytes * nextPercent) / 100));
+          stream.write(`aib runtime: ${nextPercent}% ${formatBytes(thresholdBytes)} / ${formatBytes(totalBytes)}\n`);
+          nextPercent += 10;
+        }
+      };
+      return {
+        add(byteCount) {
+          downloadedBytes += byteCount;
+          writeProgress();
+        },
+        done() {
+          if (ended) {
+            return;
+          }
+          ended = true;
+          downloadedBytes = Math.max(downloadedBytes, totalBytes ?? downloadedBytes);
+          writeProgress();
+        }
+      };
+    }
+  };
+}
+
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) {
+    return "0 B";
+  }
+  const units = ["B", "KB", "MB", "GB"];
+  let value = bytes;
+  let unitIndex = 0;
+  while (value >= 1024 && unitIndex < units.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+  const digits = value >= 100 || unitIndex === 0 ? 0 : value >= 10 ? 1 : 2;
+  return `${value.toFixed(digits)} ${units[unitIndex]}`;
+}