@ricsam/r5d-macos-vm 0.0.0 → 0.0.55

package/dist/mjs/cli.mjs

@@ -0,0 +1,144 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import {
+  findPackageRoot,
+  findPackageVersion,
+  readNativeArtifactManifest
+} from "./artifact-manifest.mjs";
+import { readHostInformation, validateHostInformation } from "./host.mjs";
+import { defaultCacheRoot, ensureNativeRuntime, pruneObsoleteNativeRuntimes } from "./native-runtime.mjs";
+function defaultModulePath() {
+  if (typeof __filename === "string") return __filename;
+  return fileURLToPath(import.meta.url);
+}
+const HELP = `Usage: r5d-macos-vm <command> [options]
+
+Commands:
+  doctor [--json]                 Check host and native virtualization support
+  create [name] [...]             Download macOS from Apple and create a VM
+  list [--json]                   List locally managed VMs
+  status [name] [--json]          Show VM state
+  start [name] [--json]           Start a VM in its window
+  run [name] [--json]             Alias for start
+  stop [name] [--force]           Stop a VM
+  delete <name> --yes [--purge]   Move a VM to Trash, or permanently purge it
+  cache prune                     Remove restore images and old native runners
+  --version                       Show the package version
+
+`;
+function findBootstrapDirectory(modulePath) {
+  const packageRoot = findPackageRoot(modulePath);
+  const candidate = packageRoot ? path.join(packageRoot, "bootstrap") : null;
+  if (candidate && fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) return candidate;
+  throw new Error("The guest bootstrap assets are missing. Reinstall @ricsam/r5d-macos-vm.");
+}
+const NAMED_COMMANDS = /* @__PURE__ */ new Set(["create", "run", "start", "status", "stop", "delete", "delete-check"]);
+function validateVmName(name) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$/.test(name)) {
+    throw new Error("VM names must start with a letter or number and contain at most 63 letters, numbers, dots, underscores, or hyphens.");
+  }
+}
+function findCommandIndex(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--json") continue;
+    if (args[index] === "--state-root") {
+      index += 1;
+      continue;
+    }
+    return index;
+  }
+  return -1;
+}
+function normalizeNativeArguments(args, bootstrapDir) {
+  const normalized = [...args];
+  const commandIndex = findCommandIndex(normalized);
+  if (commandIndex < 0) return normalized;
+  const command = normalized[commandIndex];
+  if (NAMED_COMMANDS.has(command)) {
+    const nameOptionIndex = normalized.indexOf("--name");
+    if (nameOptionIndex >= 0) {
+      const name = normalized[nameOptionIndex + 1];
+      if (!name || name.startsWith("-")) throw new Error("Missing value for --name.");
+      validateVmName(name);
+    } else {
+      let positionalIndex = commandIndex + 1;
+      while (normalized[positionalIndex] === "--json" || normalized[positionalIndex] === "--state-root") {
+        if (normalized[positionalIndex] === "--state-root") positionalIndex += 2;
+        else positionalIndex += 1;
+      }
+      const positionalName = normalized[positionalIndex];
+      if (positionalName && !positionalName.startsWith("-")) {
+        validateVmName(positionalName);
+        normalized.splice(positionalIndex, 1, "--name", positionalName);
+      }
+    }
+  }
+  if (command === "create" && !normalized.includes("--bootstrap-dir")) {
+    normalized.push("--bootstrap-dir", bootstrapDir);
+  }
+  return normalized;
+}
+const invokeNativeProcess = (executable, args) => new Promise((resolve, reject) => {
+  const child = spawn(executable, [...args], { stdio: "inherit", shell: false });
+  const forwardSignal = (signal) => child.kill(signal);
+  const onSigint = () => forwardSignal("SIGINT");
+  const onSigterm = () => forwardSignal("SIGTERM");
+  process.once("SIGINT", onSigint);
+  process.once("SIGTERM", onSigterm);
+  child.once("error", reject);
+  child.once("close", (code, signal) => {
+    process.off("SIGINT", onSigint);
+    process.off("SIGTERM", onSigterm);
+    if (signal) resolve(128 + (signal === "SIGINT" ? 2 : 15));
+    else resolve(code ?? 1);
+  });
+});
+function resolveManifestPath(modulePath, explicitPath) {
+  if (explicitPath) return path.resolve(explicitPath);
+  const packageRoot = findPackageRoot(modulePath);
+  const candidate = packageRoot ? path.join(packageRoot, "native-artifact.json") : null;
+  if (!candidate || !fs.existsSync(candidate)) {
+    throw new Error("The native artifact manifest is missing. Reinstall @ricsam/r5d-macos-vm.");
+  }
+  return candidate;
+}
+async function runCli(args, dependencies = {}) {
+  const modulePath = dependencies.modulePath ?? defaultModulePath();
+  const stdout = dependencies.stdout ?? process.stdout;
+  const packageVersion = dependencies.packageVersion ?? findPackageVersion(modulePath);
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
+    stdout.write(HELP);
+    return 0;
+  }
+  if (args[0] === "--version" || args[0] === "-v" || args[0] === "version") {
+    stdout.write(`r5d-macos-vm ${packageVersion}
+`);
+    return 0;
+  }
+  validateHostInformation(dependencies.hostInformation ?? await readHostInformation());
+  const manifest = readNativeArtifactManifest(resolveManifestPath(modulePath, dependencies.manifestPath), packageVersion);
+  const executable = await (dependencies.ensureRuntime ?? ensureNativeRuntime)(manifest, dependencies.runtime);
+  const bootstrapDir = dependencies.bootstrapDir ?? findBootstrapDirectory(modulePath);
+  const nativeArgs = normalizeNativeArguments(args, bootstrapDir);
+  const exitCode = await (dependencies.invokeNative ?? invokeNativeProcess)(executable, nativeArgs);
+  const commandIndex = findCommandIndex(nativeArgs);
+  if (exitCode === 0 && commandIndex >= 0 && nativeArgs[commandIndex] === "cache" && nativeArgs[commandIndex + 1] === "prune") {
+    await (dependencies.pruneRuntimes ?? pruneObsoleteNativeRuntimes)(
+      executable,
+      dependencies.runtime?.cacheRoot ?? defaultCacheRoot()
+    );
+  }
+  return exitCode;
+}
+function getHelpText() {
+  return HELP;
+}
+export {
+  getHelpText,
+  invokeNativeProcess,
+  normalizeNativeArguments,
+  runCli,
+  validateVmName
+};

package/dist/mjs/host.mjs

@@ -0,0 +1,37 @@
+import { spawn } from "node:child_process";
+function runSwVers() {
+  return new Promise((resolve, reject) => {
+    const child = spawn("/usr/bin/sw_vers", ["-productVersion"], {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, LANG: "C", LC_ALL: "C" }
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk) => stdout += chunk);
+    child.stderr.setEncoding("utf8").on("data", (chunk) => stderr += chunk);
+    child.once("error", reject);
+    child.once("close", (code) => {
+      if (code === 0) resolve(stdout.trim());
+      else reject(new Error(`sw_vers failed (${code ?? "signal"}): ${stderr.trim()}`));
+    });
+  });
+}
+async function readHostInformation() {
+  return {
+    platform: process.platform,
+    architecture: process.arch,
+    macOSVersion: process.platform === "darwin" ? await runSwVers() : "unknown"
+  };
+}
+function validateHostInformation(host) {
+  if (host.platform !== "darwin") throw new Error("r5d-macos-vm requires macOS.");
+  if (host.architecture !== "arm64") throw new Error("r5d-macos-vm requires an Apple silicon Mac (arm64).");
+  const match = /^(\d+)(?:\.(\d+))?/.exec(host.macOSVersion);
+  if (!match || Number(match[1]) < 14) {
+    throw new Error(`r5d-macos-vm requires macOS 14 or newer (found ${host.macOSVersion}).`);
+  }
+}
+export {
+  readHostInformation,
+  validateHostInformation
+};

package/dist/mjs/main.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runCli } from "./cli.mjs";
+runCli(process.argv.slice(2)).then((exitCode) => {
+  process.exitCode = exitCode;
+}).catch((error) => {
+  process.stderr.write(`r5d-macos-vm: ${error instanceof Error ? error.message : String(error)}
+`);
+  process.exitCode = 1;
+});

package/dist/mjs/native-runtime.mjs

@@ -0,0 +1,421 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+const LOCK_OWNER_FILE = "owner.json";
+const TEMPORARY_ARCHIVE_SUFFIX = ".download";
+async function ensurePrivateDirectory(directory, description) {
+  try {
+    await fs.promises.mkdir(directory, { recursive: true, mode: 448 });
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+  }
+  const stat = await fs.promises.lstat(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error(`Refusing to use ${description} because it is not a regular directory: ${directory}`);
+  }
+  const currentUid = process.getuid?.();
+  if (currentUid !== void 0 && stat.uid !== currentUid) {
+    throw new Error(`Refusing to use ${description} because it is not owned by the current user: ${directory}`);
+  }
+  await fs.promises.chmod(directory, 448);
+}
+function defaultCacheRoot() {
+  return path.join(os.homedir(), "Library", "Caches", "dev.r5d.macos-vm");
+}
+function runtimeDirectory(cacheRoot, manifest) {
+  return path.join(cacheRoot, "runtimes", manifest.packageVersion);
+}
+function nativeExecutablePath(runtimeDir, manifest) {
+  return path.join(runtimeDir, manifest.appName, "Contents", "MacOS", manifest.executableName);
+}
+async function pruneObsoleteNativeRuntimes(currentExecutable, cacheRoot = defaultCacheRoot()) {
+  const runtimesRoot = path.resolve(cacheRoot, "runtimes");
+  const currentRuntime = path.resolve(currentExecutable, "../../../../");
+  if (path.dirname(currentRuntime) !== runtimesRoot) {
+    throw new Error("Refusing to prune native runtimes because the active runtime is outside the managed cache.");
+  }
+  await ensurePrivateDirectory(path.resolve(cacheRoot), "native runtime cache");
+  await ensurePrivateDirectory(runtimesRoot, "native runtimes directory");
+  let entries;
+  try {
+    entries = await fs.promises.readdir(runtimesRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  const removed = [];
+  const runtimeNamePattern = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.isSymbolicLink() || !runtimeNamePattern.test(entry.name)) continue;
+    const candidate = path.resolve(runtimesRoot, entry.name);
+    if (candidate === currentRuntime || path.dirname(candidate) !== runtimesRoot) continue;
+    const quarantine = path.join(runtimesRoot, `.prune-${process.pid}-${crypto.randomUUID()}`);
+    try {
+      await fs.promises.rename(candidate, quarantine);
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw error;
+    }
+    await fs.promises.rm(quarantine, { recursive: true, force: true });
+    removed.push(entry.name);
+  }
+  return removed;
+}
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function removeStaleLock(lockPath, staleLockMs) {
+  let stat;
+  try {
+    stat = await fs.promises.stat(lockPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return true;
+    throw error;
+  }
+  if (Date.now() - stat.mtimeMs < staleLockMs) return false;
+  let ownerPid = null;
+  try {
+    const owner = JSON.parse(await fs.promises.readFile(path.join(lockPath, LOCK_OWNER_FILE), "utf8"));
+    if (Number.isSafeInteger(owner.pid) && owner.pid > 0) ownerPid = owner.pid;
+  } catch {
+  }
+  if (ownerPid !== null) {
+    try {
+      process.kill(ownerPid, 0);
+      return false;
+    } catch (error) {
+      if (error.code === "EPERM") return false;
+    }
+  }
+  const stalePath = `${lockPath}.stale-${process.pid}-${crypto.randomUUID()}`;
+  try {
+    await fs.promises.rename(lockPath, stalePath);
+  } catch (error) {
+    if (error.code === "ENOENT") return true;
+    return false;
+  }
+  await fs.promises.rm(stalePath, { recursive: true, force: true });
+  return true;
+}
+async function withDirectoryLock(lockPath, action, options) {
+  const startedAt = Date.now();
+  await ensurePrivateDirectory(path.dirname(lockPath), "native runtime lock directory");
+  while (true) {
+    try {
+      await fs.promises.mkdir(lockPath, { mode: 448 });
+      await fs.promises.chmod(lockPath, 448);
+      await fs.promises.writeFile(
+        path.join(lockPath, LOCK_OWNER_FILE),
+        `${JSON.stringify({ pid: process.pid, createdAt: (/* @__PURE__ */ new Date()).toISOString() })}
+`,
+        { mode: 384 }
+      );
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if (await removeStaleLock(lockPath, options.staleLockMs)) continue;
+      if (Date.now() - startedAt >= options.timeoutMs) {
+        throw new Error(`Timed out waiting for native runtime installation lock at ${lockPath}.`);
+      }
+      await delay(options.pollMs);
+    }
+  }
+  try {
+    return await action();
+  } finally {
+    await fs.promises.rm(lockPath, { recursive: true, force: true });
+  }
+}
+const runCommand = (executable, args) => new Promise((resolve, reject) => {
+  const child = spawn(executable, [...args], {
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, LANG: "C", LC_ALL: "C" },
+    shell: false
+  });
+  let stdout = "";
+  let stderr = "";
+  child.stdout.setEncoding("utf8").on("data", (chunk) => stdout += chunk);
+  child.stderr.setEncoding("utf8").on("data", (chunk) => stderr += chunk);
+  child.once("error", reject);
+  child.once("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr }));
+});
+async function requireSuccessfulCommand(runner, executable, args, description) {
+  const result = await runner(executable, args);
+  if (result.exitCode !== 0) {
+    const detail = `${result.stdout}
+${result.stderr}`.trim();
+    throw new Error(`${description} failed${detail ? `: ${detail}` : "."}`);
+  }
+  return result;
+}
+async function downloadNativeArtifact(manifest, destination) {
+  const temporaryDestination = `${destination}${TEMPORARY_ARCHIVE_SUFFIX}`;
+  await fs.promises.rm(temporaryDestination, { force: true });
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5 * 6e4);
+  let response;
+  try {
+    response = await fetch(manifest.url, {
+      signal: controller.signal,
+      redirect: "follow",
+      headers: { "user-agent": `@ricsam/r5d-macos-vm/${manifest.packageVersion}` }
+    });
+  } catch (error) {
+    clearTimeout(timeout);
+    throw new Error(`Unable to download the native runtime: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  try {
+    if (!response.ok || !response.body) throw new Error(`Native runtime download returned HTTP ${response.status}.`);
+    const contentLength = response.headers.get("content-length");
+    if (contentLength !== null && Number(contentLength) !== manifest.byteLength) {
+      throw new Error(`Native runtime download length ${contentLength} does not match expected ${manifest.byteLength}.`);
+    }
+    const file = await fs.promises.open(temporaryDestination, "wx", 384);
+    const hash = crypto.createHash("sha256");
+    let byteLength = 0;
+    try {
+      for await (const value of response.body) {
+        const chunk = Buffer.from(value);
+        byteLength += chunk.byteLength;
+        if (byteLength > manifest.byteLength) throw new Error("Native runtime download exceeded its signed byte length.");
+        hash.update(chunk);
+        await file.write(chunk);
+      }
+    } finally {
+      await file.close();
+    }
+    if (byteLength !== manifest.byteLength) {
+      throw new Error(`Native runtime download contained ${byteLength} bytes; expected ${manifest.byteLength}.`);
+    }
+    const digest = hash.digest("hex");
+    if (!crypto.timingSafeEqual(Buffer.from(digest, "hex"), Buffer.from(manifest.sha256, "hex"))) {
+      throw new Error("Native runtime checksum verification failed.");
+    }
+    await fs.promises.rename(temporaryDestination, destination);
+  } finally {
+    clearTimeout(timeout);
+    await fs.promises.rm(temporaryDestination, { force: true });
+  }
+}
+function decodePackedVersion(value) {
+  const major = value >>> 16;
+  const minor = value >>> 8 & 255;
+  const patch = value & 255;
+  return patch === 0 ? `${major}.${minor}` : `${major}.${minor}.${patch}`;
+}
+function inspectMachOExecutable(filePath) {
+  const data = fs.readFileSync(filePath);
+  if (data.byteLength < 32 || data.readUInt32LE(0) !== 4277009103) {
+    throw new Error("Native runtime executable is not a thin 64-bit Mach-O file.");
+  }
+  if (data.readInt32LE(4) !== 16777228) throw new Error("Native runtime executable is not arm64.");
+  if (data.readUInt32LE(12) !== 2) throw new Error("Native runtime Mach-O is not an executable.");
+  const commandCount = data.readUInt32LE(16);
+  const commandBytes = data.readUInt32LE(20);
+  if (32 + commandBytes > data.byteLength) throw new Error("Native runtime Mach-O load commands are truncated.");
+  let offset = 32;
+  let minimumMacOSVersion = null;
+  for (let index = 0; index < commandCount; index += 1) {
+    if (offset + 8 > data.byteLength) throw new Error("Native runtime Mach-O load command is truncated.");
+    const command = data.readUInt32LE(offset);
+    const commandSize = data.readUInt32LE(offset + 4);
+    if (commandSize < 8 || offset + commandSize > data.byteLength) throw new Error("Native runtime Mach-O load command is invalid.");
+    if (command === 50) {
+      if (commandSize < 24) throw new Error("Native runtime LC_BUILD_VERSION command is invalid.");
+      if (data.readUInt32LE(offset + 8) !== 1) throw new Error("Native runtime was not built for macOS.");
+      minimumMacOSVersion = decodePackedVersion(data.readUInt32LE(offset + 12));
+    } else if (command === 36 && minimumMacOSVersion === null) {
+      if (commandSize < 16) throw new Error("Native runtime LC_VERSION_MIN_MACOSX command is invalid.");
+      minimumMacOSVersion = decodePackedVersion(data.readUInt32LE(offset + 8));
+    }
+    offset += commandSize;
+  }
+  if (minimumMacOSVersion === null) throw new Error("Native runtime does not declare a minimum macOS version.");
+  return { architecture: "arm64", minimumMacOSVersion };
+}
+function normalizeVersion(value) {
+  const parts = value.trim().split(".").map(Number);
+  while (parts.length > 2 && parts.at(-1) === 0) parts.pop();
+  return parts.join(".");
+}
+function requireRegularFile(filePath, description) {
+  const stat = fs.lstatSync(filePath);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`${description} is not a regular file.`);
+}
+function parseSigningValue(output, key) {
+  const line = output.split(/\r?\n/).find((candidate) => candidate.startsWith(`${key}=`));
+  return line ? line.slice(key.length + 1).trim() : null;
+}
+function codeSignatureUsesHardenedRuntime(output) {
+  const codeDirectoryLine = output.split(/\r?\n/).find((line) => line.startsWith("CodeDirectory "));
+  if (!codeDirectoryLine) return false;
+  const flags = /\bflags=0x[0-9a-f]+\(([^)]*)\)/i.exec(codeDirectoryLine)?.[1];
+  return flags?.split(",").some((flag) => flag.trim() === "runtime") ?? false;
+}
+async function verifyNativeApp(appPath, manifest, runner = runCommand) {
+  const appStat = fs.lstatSync(appPath);
+  if (!appStat.isDirectory() || appStat.isSymbolicLink()) throw new Error("Native runtime app is not a regular bundle directory.");
+  const infoPlistPath = path.join(appPath, "Contents", "Info.plist");
+  const executablePath = path.join(appPath, "Contents", "MacOS", manifest.executableName);
+  requireRegularFile(infoPlistPath, "Native runtime Info.plist");
+  requireRegularFile(executablePath, "Native runtime executable");
+  const machO = inspectMachOExecutable(executablePath);
+  if (machO.architecture !== manifest.architecture) throw new Error("Native runtime architecture does not match its manifest.");
+  if (normalizeVersion(machO.minimumMacOSVersion) !== normalizeVersion(manifest.minimumMacOSVersion)) {
+    throw new Error(`Native runtime minimum macOS version ${machO.minimumMacOSVersion} does not match ${manifest.minimumMacOSVersion}.`);
+  }
+  const identifier = await requireSuccessfulCommand(
+    runner,
+    "/usr/bin/plutil",
+    ["-extract", "CFBundleIdentifier", "raw", "-o", "-", infoPlistPath],
+    "Reading native runtime bundle identifier"
+  );
+  if (identifier.stdout.trim() !== manifest.bundleIdentifier) throw new Error("Native runtime bundle identifier is invalid.");
+  const minimumVersion = await requireSuccessfulCommand(
+    runner,
+    "/usr/bin/plutil",
+    ["-extract", "LSMinimumSystemVersion", "raw", "-o", "-", infoPlistPath],
+    "Reading native runtime deployment target"
+  );
+  if (normalizeVersion(minimumVersion.stdout) !== normalizeVersion(manifest.minimumMacOSVersion)) {
+    throw new Error("Native runtime Info.plist deployment target is invalid.");
+  }
+  await requireSuccessfulCommand(
+    runner,
+    "/usr/bin/codesign",
+    ["--verify", "--deep", "--strict", "--verbose=2", appPath],
+    "Native runtime code-signature verification"
+  );
+  const signature = await requireSuccessfulCommand(
+    runner,
+    "/usr/bin/codesign",
+    ["--display", "--verbose=4", appPath],
+    "Reading native runtime code signature"
+  );
+  const signatureOutput = `${signature.stdout}
+${signature.stderr}`;
+  if (parseSigningValue(signatureOutput, "Identifier") !== manifest.bundleIdentifier) {
+    throw new Error("Native runtime code-signing identifier is invalid.");
+  }
+  if (parseSigningValue(signatureOutput, "TeamIdentifier") !== manifest.teamIdentifier) {
+    throw new Error("Native runtime Apple Team ID is invalid.");
+  }
+  if (!codeSignatureUsesHardenedRuntime(signatureOutput)) {
+    throw new Error("Native runtime is not signed with the hardened runtime.");
+  }
+  if (parseSigningValue(signatureOutput, "Notarization Ticket") !== "stapled") {
+    throw new Error("Native runtime does not contain a stapled notarization ticket.");
+  }
+  const entitlements = await requireSuccessfulCommand(
+    runner,
+    "/usr/bin/codesign",
+    ["--display", "--entitlements", ":-", appPath],
+    "Reading native runtime entitlements"
+  );
+  const entitlementOutput = `${entitlements.stdout}
+${entitlements.stderr}`;
+  const entitlementKeys = [...entitlementOutput.matchAll(/<key>([^<]+)<\/key>/g)].map((match) => match[1]);
+  if (entitlementKeys.length !== 1 || entitlementKeys[0] !== "com.apple.security.virtualization") {
+    throw new Error("Native runtime contains entitlements other than com.apple.security.virtualization.");
+  }
+  if (!/<key>com\.apple\.security\.virtualization<\/key>\s*<true\s*\/>/s.test(entitlementOutput)) {
+    throw new Error("Native runtime is missing the virtualization entitlement.");
+  }
+  const gatekeeper = await requireSuccessfulCommand(
+    runner,
+    "/usr/sbin/spctl",
+    ["--assess", "--type", "execute", "--verbose=4", appPath],
+    "Native runtime Gatekeeper assessment"
+  );
+  const gatekeeperOutput = `${gatekeeper.stdout}
+${gatekeeper.stderr}`;
+  if (!/source=Notarized Developer ID/.test(gatekeeperOutput)) {
+    throw new Error("Native runtime does not have an accepted Apple notarization assessment.");
+  }
+}
+async function installRuntime(runtimeDir, manifest, dependencies) {
+  const runtimesRoot = path.dirname(runtimeDir);
+  await ensurePrivateDirectory(runtimesRoot, "native runtimes directory");
+  const workDir = await fs.promises.mkdtemp(path.join(runtimesRoot, ".install-"));
+  try {
+    const archivePath = path.join(workDir, manifest.archiveName);
+    await dependencies.download(manifest, archivePath);
+    const extractDir = path.join(workDir, "extract");
+    await fs.promises.mkdir(extractDir, { mode: 448 });
+    await requireSuccessfulCommand(
+      dependencies.commandRunner,
+      "/usr/bin/ditto",
+      ["-x", "-k", "--noqtn", archivePath, extractDir],
+      "Extracting native runtime"
+    );
+    const entries = await fs.promises.readdir(extractDir);
+    if (entries.length !== 1 || entries[0] !== manifest.appName) {
+      throw new Error(`Native runtime archive must contain only ${manifest.appName}.`);
+    }
+    const extractedApp = path.join(extractDir, manifest.appName);
+    await verifyNativeApp(extractedApp, manifest, dependencies.commandRunner);
+    const readyDir = path.join(workDir, "ready");
+    await fs.promises.mkdir(readyDir, { mode: 448 });
+    await fs.promises.rename(extractedApp, path.join(readyDir, manifest.appName));
+    await fs.promises.writeFile(
+      path.join(readyDir, "runtime.json"),
+      `${JSON.stringify({ packageVersion: manifest.packageVersion, sha256: manifest.sha256 }, null, 2)}
+`,
+      { mode: 384 }
+    );
+    await fs.promises.rename(readyDir, runtimeDir);
+  } finally {
+    await fs.promises.rm(workDir, { recursive: true, force: true });
+  }
+}
+async function cachedRuntimeIsValid(runtimeDir, manifest, runner) {
+  try {
+    const marker = JSON.parse(await fs.promises.readFile(path.join(runtimeDir, "runtime.json"), "utf8"));
+    if (marker.packageVersion !== manifest.packageVersion || marker.sha256 !== manifest.sha256) return false;
+    await verifyNativeApp(path.join(runtimeDir, manifest.appName), manifest, runner);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function ensureNativeRuntime(manifest, dependencies = {}) {
+  const cacheRoot = dependencies.cacheRoot ?? defaultCacheRoot();
+  const commandRunner = dependencies.commandRunner ?? runCommand;
+  const download = dependencies.download ?? downloadNativeArtifact;
+  const destination = runtimeDirectory(cacheRoot, manifest);
+  await ensurePrivateDirectory(cacheRoot, "native runtime cache");
+  await ensurePrivateDirectory(path.dirname(destination), "native runtimes directory");
+  if (await cachedRuntimeIsValid(destination, manifest, commandRunner)) {
+    return nativeExecutablePath(destination, manifest);
+  }
+  const lockPath = path.join(cacheRoot, "locks", `${manifest.packageVersion}.lock`);
+  return withDirectoryLock(
+    lockPath,
+    async () => {
+      if (!await cachedRuntimeIsValid(destination, manifest, commandRunner)) {
+        await fs.promises.rm(destination, { recursive: true, force: true });
+        await installRuntime(destination, manifest, { commandRunner, download });
+      }
+      return nativeExecutablePath(destination, manifest);
+    },
+    {
+      pollMs: dependencies.lockPollMs ?? 100,
+      timeoutMs: dependencies.lockTimeoutMs ?? 5 * 6e4,
+      staleLockMs: dependencies.staleLockMs ?? 10 * 6e4
+    }
+  );
+}
+export {
+  codeSignatureUsesHardenedRuntime,
+  defaultCacheRoot,
+  downloadNativeArtifact,
+  ensureNativeRuntime,
+  inspectMachOExecutable,
+  nativeExecutablePath,
+  pruneObsoleteNativeRuntimes,
+  runCommand,
+  runtimeDirectory,
+  verifyNativeApp
+};

package/dist/mjs/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@ricsam/r5d-macos-vm",
+  "version": "0.0.55",
+  "type": "module"
+}

package/dist/types/artifact-manifest.d.ts

@@ -0,0 +1,33 @@
+export declare const MACOS_VM_PACKAGE_NAME = "@ricsam/r5d-macos-vm";
+export declare const NATIVE_ARCHIVE_NAME = "R5DMacOSVM.app.zip";
+export declare const NATIVE_APP_NAME = "R5DMacOSVM.app";
+export declare const NATIVE_EXECUTABLE_NAME = "R5DMacOSVM";
+export declare const NATIVE_BUNDLE_IDENTIFIER = "dev.r5d.macos-vm";
+export declare const NATIVE_MINIMUM_MACOS_VERSION = "14.0";
+export declare const NATIVE_ARTIFACT_HOST = "downloads.r5d.dev";
+export type NativeArtifactManifest = {
+    schemaVersion: 1;
+    packageVersion: string;
+    url: string;
+    sha256: string;
+    byteLength: number;
+    archiveName: typeof NATIVE_ARCHIVE_NAME;
+    appName: typeof NATIVE_APP_NAME;
+    executableName: typeof NATIVE_EXECUTABLE_NAME;
+    bundleIdentifier: typeof NATIVE_BUNDLE_IDENTIFIER;
+    teamIdentifier: string;
+    architecture: "arm64";
+    minimumMacOSVersion: typeof NATIVE_MINIMUM_MACOS_VERSION;
+};
+export declare function expectedArtifactUrl(version: string): string;
+/**
+ * Identify Apple restore media and machine-specific VM state that must never be
+ * shipped in either the npm package or the separately hosted native archive.
+ */
+export declare function isForbiddenVirtualMachineArtifactPath(filePath: string): boolean;
+export declare function findForbiddenVirtualMachineArtifactPaths(paths: readonly string[]): string[];
+export declare function parseNativeArtifactManifest(value: unknown, expectedPackageVersion: string): NativeArtifactManifest;
+export declare function readNativeArtifactManifest(filePath: string, expectedPackageVersion: string): NativeArtifactManifest;
+export declare function findFileUpward(startPath: string, fileName: string): string | null;
+export declare function findPackageRoot(startPath: string): string | null;
+export declare function findPackageVersion(startPath: string): string;

package/dist/types/cli.d.ts

@@ -0,0 +1,23 @@
+import { type NativeArtifactManifest } from "./artifact-manifest";
+import { type HostInformation } from "./host";
+import { type RuntimeDependencies } from "./native-runtime";
+type CliDependencies = {
+    modulePath?: string;
+    packageVersion?: string;
+    manifestPath?: string;
+    bootstrapDir?: string;
+    hostInformation?: HostInformation;
+    runtime?: RuntimeDependencies;
+    ensureRuntime?: (manifest: NativeArtifactManifest, dependencies?: RuntimeDependencies) => Promise<string>;
+    invokeNative?: (executable: string, args: readonly string[]) => Promise<number>;
+    pruneRuntimes?: (currentExecutable: string, cacheRoot?: string) => Promise<string[]>;
+    stdout?: {
+        write: (value: string) => unknown;
+    };
+};
+export declare function validateVmName(name: string): void;
+export declare function normalizeNativeArguments(args: readonly string[], bootstrapDir: string): string[];
+export declare const invokeNativeProcess: (executable: string, args: readonly string[]) => Promise<number>;
+export declare function runCli(args: readonly string[], dependencies?: CliDependencies): Promise<number>;
+export declare function getHelpText(): string;
+export {};