@openstrap/utm 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @openstrap/utm
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+UTM provider plugin for OpenStrap. Creates and drives the lifecycle of virtual machines on macOS.
+
+## Status
+
+Working. `provider-contract.live.ts` creates an Ubuntu 24.04 machine on real UTM, boots it and reaches sshd through a forwarded port. The provider was written against what UTM does rather than what its dictionary declares — the dictionary is accurate about what exists and silent about three things that decide whether any of it works.
+
+```bash
+npm run test:live
+```
+
+Needs UTM installed; downloads about 600 MB the first time. There is no fake provider and there will not be one.
+
+## What UTM actually supports
+
+Verified by hand against UTM 4.7.5 (`com.utmapp.UTM`, direct download, sandboxed) on Apple Silicon. Full record: `docs/wiki/grill/utm-scripting-probe.md` in the openstrap repository.
+
+The provider interface the milestone describes stands: disks, network and port forwarding are all configurable through scripting.
+
+- `utmctl` has no `create`. Machines are created with the AppleScript `make` command.
+- `make` accepts the whole scalar configuration in one call: `name`, `architecture`, `memory`, `cpu cores`, `uefi`, `hypervisor`.
+- `update configuration` sets collections too — both `drives` and `network interfaces`.
+- Attaching a disk works. UTM imports the file into the `.utm` package and converts it to qcow2.
+- Port forwarding works, in `mode: emulated`. It does not exist in `shared`, which is the default after `make`.
+
+## Three constraints that only an experiment reveals
+
+1. **Enumerators do not resolve by name.** `protocol:TCP` fails with `-1700`; only the raw code works — `«constant ****TcPp»` for TCP, `«constant ****UdPp»` for UDP. JXA does not help. The provider must build AppleScript with raw constants taken from `UTM.sdef`.
+
+2. **The image file must live inside the UTM sandbox container.** A source under `$HOME` or `/private/tmp` fails with "the file couldn't be opened because it doesn't exist" on a file that plainly exists. From `~/Library/Containers/com.utmapp.UTM/Data/Documents/` it attaches. The image cache therefore lives inside that container.
+
+3. **No mutating command works while the application has no open window** — scripting answers `UTM is not ready to accept commands (-2700)` even though reads succeed. `open -a UTM` clears it.
+
+`qemu additional arguments` is accepted silently and applied not at all, then errors on read. Nothing may be built on it — but nothing needs to be.
+
+## Consequences for the design
+
+The guest is reached through a forwarded port on `127.0.0.1`, so the endpoint is stable and openstrap reserves the host port itself. See ADR 0006 in the openstrap repository. No QEMU guest agent is required for access, so waiting means waiting for sshd, not for an agent.

package/dist/index.js

@@ -0,0 +1,823 @@
+import { createRequire as __openstrapRequire } from 'node:module';
+import { fileURLToPath as __openstrapPath } from 'node:url';
+import { dirname as __openstrapDirname } from 'node:path';
+const require = __openstrapRequire(import.meta.url);
+const __filename = __openstrapPath(import.meta.url);
+const __dirname = __openstrapDirname(__filename);
+
+// src/UTM.ts
+import { homedir } from "node:os";
+import { join as join4 } from "node:path";
+
+// src/images/HostFiles.ts
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { mkdir, rename, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+var HostFiles = class {
+  joinPath(...parts) {
+    return join(...parts);
+  }
+  async createDirectory(path) {
+    await mkdir(path, { recursive: true });
+  }
+  async movePath(from, to) {
+    await rename(from, to);
+  }
+  /** The permissions of a file, or null when there is no such file — which is how presence is asked. */
+  async mode(path) {
+    try {
+      return (await stat(path)).mode & 511;
+    } catch {
+      return null;
+    }
+  }
+  async removePath(path, options) {
+    await rm(path, { force: options?.force ?? false, recursive: true });
+  }
+};
+var HostNetwork = class {
+  async download(url, destination) {
+    const response = await fetch(url);
+    if (!response.ok || !response.body) {
+      throw new Error(`Download of ${url} failed with status ${response.status}`);
+    }
+    const digest = createHash("sha256");
+    let bytes = 0;
+    const counted = Readable.fromWeb(response.body);
+    counted.on("data", (chunk) => {
+      bytes += chunk.length;
+      digest.update(chunk);
+    });
+    await pipeline(counted, createWriteStream(destination));
+    return { bytes, sha256: digest.digest("hex") };
+  }
+};
+
+// src/images/BoxArchive.ts
+import { execFile } from "node:child_process";
+import { mkdir as mkdir2, open, readdir, rename as rename2, rm as rm2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+import { promisify } from "node:util";
+var run = promisify(execFile);
+var qcow2 = Buffer.from([81, 70, 73, 251]);
+var BoxDiskMissingError = class extends Error {
+  constructor(box, contents) {
+    super(
+      `${box} holds no disk image UTM can boot. It contains: ${contents.join(", ")}. A box openstrap can use has a qcow2 disk in it.`
+    );
+    this.name = "BoxDiskMissingError";
+  }
+};
+var BoxArchive = class _BoxArchive {
+  constructor(tar = "tar") {
+    this.tar = tar;
+  }
+  tar;
+  /** Puts the box's disk at `destination`, leaving nothing else of the archive behind. */
+  async diskFrom(box, destination) {
+    const unpacked = `${destination}.unpacking`;
+    await rm2(unpacked, { recursive: true, force: true });
+    await mkdir2(unpacked, { recursive: true });
+    try {
+      await run(this.tar, ["-xf", box, "-C", unpacked]);
+      const disk = await _BoxArchive.diskIn(unpacked);
+      if (!disk) {
+        throw new BoxDiskMissingError(box, await readdir(unpacked));
+      }
+      await rename2(join2(unpacked, disk), destination);
+    } finally {
+      await rm2(unpacked, { recursive: true, force: true });
+    }
+  }
+  static async diskIn(directory) {
+    for (const name of await readdir(directory)) {
+      const handle = await open(join2(directory, name), "r");
+      try {
+        const head = Buffer.alloc(qcow2.length);
+        const { bytesRead } = await handle.read(head, 0, head.length, 0);
+        if (bytesRead === head.length && head.equals(qcow2)) {
+          return name;
+        }
+      } finally {
+        await handle.close();
+      }
+    }
+    return void 0;
+  }
+};
+
+// src/images/ImageCache.ts
+import { createHash as createHash2 } from "node:crypto";
+var ImageChecksumError = class extends Error {
+  constructor(url, expected, actual) {
+    super(`${url} does not match the checksum it was published with. Expected ${expected}, got ${actual}`);
+    this.name = "ImageChecksumError";
+  }
+};
+var ImageCache = class _ImageCache {
+  constructor(directory, fileSystem, network, boxes = new BoxArchive()) {
+    this.directory = directory;
+    this.fileSystem = fileSystem;
+    this.network = network;
+    this.boxes = boxes;
+  }
+  directory;
+  fileSystem;
+  network;
+  boxes;
+  /**
+   * The disk on disk, downloaded once and checked against what it was published as.
+   *
+   * The checksum is openstrap's — the pin, when this target has one — and a file that does not
+   * match it is deleted rather than booted. No signature is checked: what is being trusted is that
+   * these are the bytes published under this name, which is what a checksum served beside them says.
+   */
+  async fetch(image) {
+    const held = image.sha256 ?? _ImageCache.digestOf(image.url);
+    const disk = this.fileSystem.joinPath(this.directory, `${held}.qcow2`);
+    if (await this.fileSystem.mode(disk) !== null) {
+      return { path: disk, sha256: image.sha256, bytes: 0, reused: true };
+    }
+    await this.fileSystem.createDirectory(this.directory);
+    const downloaded = this.fileSystem.joinPath(this.directory, `${held}.download`);
+    const download = await this.network.download(image.url, downloaded);
+    if (image.sha256 !== void 0 && download.sha256 !== image.sha256) {
+      await this.fileSystem.removePath(downloaded, { force: true });
+      throw new ImageChecksumError(image.url, image.sha256, download.sha256);
+    }
+    try {
+      await this.unpack(image.format, downloaded, disk);
+    } finally {
+      await this.fileSystem.removePath(downloaded, { force: true });
+    }
+    return { path: disk, sha256: download.sha256, bytes: download.bytes, reused: false };
+  }
+  /** A name for a file nobody published a checksum for, made from where it came from. */
+  static digestOf(url) {
+    return createHash2("sha256").update(url).digest("hex");
+  }
+  /**
+   * What was downloaded, as a disk.
+   *
+   * A box is an archive with the disk inside it; anything else is taken to be the disk, because a
+   * format this does not recognise is either already one or something UTM will refuse by itself,
+   * and refusing here as well would only be a second opinion about a file nobody has looked at.
+   */
+  async unpack(format, downloaded, disk) {
+    if (format === "vagrant-box") {
+      await this.boxes.diskFrom(downloaded, disk);
+      return;
+    }
+    await this.fileSystem.movePath(downloaded, disk);
+  }
+};
+
+// src/seed/CloudInitSeed.ts
+import { execFile as execFile2 } from "node:child_process";
+import { mkdtemp, rm as rm3, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join as join3 } from "node:path";
+import { promisify as promisify2 } from "node:util";
+var run2 = promisify2(execFile2);
+var CloudInitSeed = class {
+  async build(request) {
+    if (request.publicKey.includes("PRIVATE KEY")) {
+      throw new Error("Refusing to write a private key into a cloud-init seed");
+    }
+    const staging = await mkdtemp(join3(tmpdir(), "openstrap-seed-"));
+    try {
+      await writeFile(join3(staging, "meta-data"), this.metaData(request), "utf8");
+      await writeFile(join3(staging, "user-data"), this.userData(request), "utf8");
+      await rm3(request.destination, { force: true });
+      await run2("hdiutil", [
+        "makehybrid",
+        "-iso",
+        "-joliet",
+        "-default-volume-name",
+        "cidata",
+        "-o",
+        request.destination,
+        staging
+      ]);
+      return request.destination;
+    } finally {
+      await rm3(staging, { force: true, recursive: true });
+    }
+  }
+  metaData(request) {
+    return [
+      `instance-id: ${request.name}`,
+      `local-hostname: ${request.name}`,
+      ""
+    ].join("\n");
+  }
+  userData(request) {
+    return [
+      "#cloud-config",
+      "users:",
+      `  - name: ${request.user}`,
+      "    sudo: 'ALL=(ALL) NOPASSWD:ALL'",
+      "    shell: /bin/bash",
+      "    lock_passwd: true",
+      "    ssh_authorized_keys:",
+      `      - ${request.publicKey.trim()}`,
+      "disable_root: true",
+      "ssh_pwauth: false",
+      "write_files:",
+      "  - path: /etc/ssh/sshd_config.d/60-openstrap.conf",
+      "    permissions: '0644'",
+      "    content: |",
+      "      PasswordAuthentication no",
+      "      KbdInteractiveAuthentication no",
+      "      PermitRootLogin no",
+      ""
+    ].join("\n");
+  }
+};
+
+// src/machine/MachineDidNotStartError.ts
+var MachineDidNotStartError = class extends Error {
+  constructor(name, status) {
+    super(
+      `${name} was told to start and is ${status}. UTM refused to launch it; its own window or \`utmctl start ${name}\` says why.`
+    );
+    this.name = "MachineDidNotStartError";
+  }
+};
+
+// src/machine/MachineDisk.ts
+import { copyFile, rm as rm4, stat as stat2 } from "node:fs/promises";
+import { execFile as execFile3 } from "node:child_process";
+import { promisify as promisify3 } from "node:util";
+var run3 = promisify3(execFile3);
+var MachineDisk = class {
+  constructor(qemuImg = "qemu-img") {
+    this.qemuImg = qemuImg;
+  }
+  qemuImg;
+  /**
+   * A disk for this machine, `bytes` in size, made from the image.
+   *
+   * Returns the image itself when no size was asked for or the image is already at least that big:
+   * qcow2 cannot shrink, and a machine asking for less than its image holds is asking for a machine
+   * that cannot boot.
+   */
+  async of(image, destination, bytes) {
+    if (bytes <= 0 || bytes <= await virtualSize(this.qemuImg, image)) {
+      return image;
+    }
+    await copyFile(image, destination);
+    try {
+      await run3(this.qemuImg, ["resize", destination, String(bytes)]);
+    } catch (error) {
+      await rm4(destination, { force: true });
+      throw new Error(`Could not size the disk for this machine: ${reasonFor(error)}`);
+    }
+    return destination;
+  }
+  /** The copy, once UTM has taken its own. Two of a forty gigabyte disk is not a thing to leave. */
+  async discard(path) {
+    await rm4(path, { force: true });
+  }
+  /**
+   * Whether the tool that resizes a disk is here.
+   *
+   * Asked before it is needed rather than after: a machine that has been created and then cannot be
+   * sized is a machine somebody has to go and delete.
+   */
+  async available() {
+    try {
+      await run3(this.qemuImg, ["--version"]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+async function virtualSize(qemuImg, image) {
+  try {
+    const { stdout } = await run3(qemuImg, ["info", "--output=json", image]);
+    return Number(JSON.parse(stdout)["virtual-size"] ?? 0);
+  } catch {
+    return (await stat2(image)).size;
+  }
+}
+function reasonFor(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("ENOENT") ? "qemu-img is not installed. It comes with QEMU: brew install qemu" : message;
+}
+
+// src/machine/UTMMachines.ts
+import { execFile as execFile6 } from "node:child_process";
+import { promisify as promisify6 } from "node:util";
+
+// src/applescript/AppleScript.ts
+import { execFile as execFile4 } from "node:child_process";
+import { promisify as promisify4 } from "node:util";
+var run4 = promisify4(execFile4);
+var AppleScriptError = class extends Error {
+  constructor(message, script) {
+    super(message);
+    this.script = script;
+    this.name = "AppleScriptError";
+  }
+  script;
+};
+var rawConstant = /* @__PURE__ */ Symbol("rawConstant");
+var posixFile = /* @__PURE__ */ Symbol("posixFile");
+function constant(code) {
+  return { [rawConstant]: code };
+}
+function file(path) {
+  return { [posixFile]: path };
+}
+function literal(value) {
+  if (isRawConstant(value)) {
+    return `\xABconstant ****${value[rawConstant]}\xBB`;
+  }
+  if (isPosixFile(value)) {
+    return `POSIX file ${quote(value[posixFile])}`;
+  }
+  if (Array.isArray(value)) {
+    return `{${value.map(literal).join(", ")}}`;
+  }
+  if (typeof value === "string") {
+    return quote(value);
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  const fields = Object.entries(value).filter((entry) => entry[1] !== void 0).map(([key, field]) => `${key}:${literal(field)}`);
+  return `{${fields.join(", ")}}`;
+}
+function quote(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function isRawConstant(value) {
+  return typeof value === "object" && value !== null && rawConstant in value;
+}
+function isPosixFile(value) {
+  return typeof value === "object" && value !== null && posixFile in value;
+}
+var AppleScript = class {
+  constructor(timeoutSeconds = 120) {
+    this.timeoutSeconds = timeoutSeconds;
+  }
+  timeoutSeconds;
+  async run(body) {
+    const script = `with timeout of ${this.timeoutSeconds} seconds
+${body}
+end timeout`;
+    try {
+      const { stdout } = await run4("osascript", ["-e", script], {
+        maxBuffer: 16 * 1024 * 1024,
+        timeout: (this.timeoutSeconds + 15) * 1e3
+      });
+      return stdout.trim();
+    } catch (error) {
+      throw new AppleScriptError(messageOf(error), script);
+    }
+  }
+};
+function messageOf(error) {
+  if (error && typeof error === "object" && "stderr" in error && typeof error.stderr === "string" && error.stderr.trim()) {
+    return error.stderr.trim();
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/applescript/Automation.ts
+import { execFile as execFile5 } from "node:child_process";
+import { promisify as promisify5 } from "node:util";
+var run5 = promisify5(execFile5);
+var Automation = class {
+  constructor(timeoutSeconds = 60) {
+    this.timeoutSeconds = timeoutSeconds;
+  }
+  timeoutSeconds;
+  async read(expression) {
+    const script = `const utm = Application("UTM"); JSON.stringify(${expression});`;
+    try {
+      const { stdout } = await run5("osascript", ["-l", "JavaScript", "-e", script], {
+        maxBuffer: 16 * 1024 * 1024,
+        timeout: this.timeoutSeconds * 1e3
+      });
+      return JSON.parse(stdout.trim());
+    } catch (error) {
+      throw new AppleScriptError(messageOf2(error), script);
+    }
+  }
+};
+function messageOf2(error) {
+  if (error && typeof error === "object" && "stderr" in error && typeof error.stderr === "string" && error.stderr.trim()) {
+    return error.stderr.trim();
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/machine/UTMMachines.ts
+var run6 = promisify6(execFile6);
+var utmctlPath = "/Applications/UTM.app/Contents/MacOS/utmctl";
+var codes = {
+  tcp: "TcPp",
+  emulated: "EmUd",
+  virtio: "QdIv",
+  usb: "QdIu"
+};
+var UTMMachines = class {
+  constructor(appleScript = new AppleScript(), automation = new Automation()) {
+    this.appleScript = appleScript;
+    this.automation = automation;
+  }
+  appleScript;
+  automation;
+  async installed() {
+    try {
+      await run6(utmctlPath, ["version"]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async version() {
+    try {
+      const { stdout } = await run6(utmctlPath, ["version"]);
+      return stdout.trim();
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Makes UTM ready to accept commands.
+   *
+   * While the application has no open window, scripting answers
+   * "UTM is not ready to accept commands (-2700)" even though reads succeed.
+   */
+  async ready() {
+    await run6("open", ["-a", "UTM"]);
+    for (let attempt = 0; attempt < 40; attempt += 1) {
+      const windows = await this.appleScript.run('tell application "UTM" to return (count of windows) as text').catch(() => "0");
+      if (Number(windows) > 0) {
+        return;
+      }
+      await delay(250);
+    }
+    throw new Error("UTM did not open a window and will not accept commands");
+  }
+  async create(spec) {
+    const configuration = literal({
+      name: spec.name,
+      architecture: spec.architecture,
+      memory: spec.memoryMiB,
+      "cpu cores": spec.cpuCores,
+      uefi: true,
+      hypervisor: true,
+      // A machine with no screen is what UTM makes by default, and what everything openstrap is
+      // normally asked for wants. `virtio-ramfb-gl` is what UTM itself picks for an ARM guest.
+      ...spec.display ? { displays: [{ hardware: "virtio-ramfb-gl" }] } : {}
+    });
+    return this.appleScript.run(
+      `tell application "UTM" to return (id of (make new virtual machine with properties {backend:qemu, configuration:${configuration}})) as text`
+    );
+  }
+  async drives(id) {
+    return this.automation.read(
+      `utm.virtualMachines.byId(${JSON.stringify(id)}).configuration().drives`
+    );
+  }
+  async portForwards(id) {
+    return (await this.networkInterfaces(id)).flatMap((entry) => entry.portForwards);
+  }
+  async networkInterfaces(id) {
+    const interfaces = await this.automation.read(
+      `utm.virtualMachines.byId(${JSON.stringify(id)}).configuration().networkInterfaces`
+    );
+    return interfaces.map((entry, index) => ({
+      index: entry.index ?? index,
+      hardware: entry.hardware ?? "",
+      address: entry.address ?? "",
+      mode: entry.mode ?? "",
+      portForwards: (entry.portForwards ?? []).map((forward) => ({ hostPort: forward.hostPort, guestPort: forward.guestPort }))
+    }));
+  }
+  /**
+   * Replaces the drives of a machine with ones backed by the given images.
+   *
+   * UTM imports each source into the machine package and converts it, so the
+   * cached base image is read and never modified.
+   *
+   * The sources must live inside UTM's sandbox container. UTM reports a source
+   * it cannot reach as a file that does not exist, even when it plainly does.
+   */
+  async attachDrives(id, drives) {
+    const value = literal({
+      drives: drives.map((drive) => ({
+        id: drive.id,
+        source: file(drive.source),
+        interface: constant(drive.removable ? codes.usb : codes.virtio)
+      }))
+    });
+    await this.appleScript.run(`tell application "UTM" to update configuration virtual machine id "${id}" with ${value}`);
+  }
+  /**
+   * Port forwarding requires the emulated network mode; shared does not have it.
+   *
+   * Without `keep` this describes a new card, which is right for a machine being made. For a machine
+   * that exists the card must stay the same one: UTM would otherwise make a new card with a new MAC
+   * address, and a guest that configured its network by that address comes back with none.
+   */
+  async forwardPorts(id, forwards, keep) {
+    const value = literal({
+      "network interfaces": [{
+        ...keep === void 0 ? {} : {
+          index: keep.index,
+          address: keep.address,
+          ...keep.hardware === "" ? {} : { hardware: keep.hardware }
+        },
+        mode: constant(codes.emulated),
+        "port forwards": forwards.map((forward) => ({
+          protocol: constant(codes.tcp),
+          "host port": forward.hostPort,
+          "guest port": forward.guestPort
+        }))
+      }]
+    });
+    await this.appleScript.run(`tell application "UTM" to update configuration virtual machine id "${id}" with ${value}`);
+  }
+  async start(id) {
+    await run6(utmctlPath, ["start", id]);
+  }
+  async stop(id) {
+    await run6(utmctlPath, ["stop", id]);
+  }
+  /** The guest is asked to power down, the way a keypress on the case would, rather than switched off. */
+  async requestShutdown(id) {
+    await run6(utmctlPath, ["stop", "--request", id]);
+  }
+  async status(id) {
+    const { stdout } = await run6(utmctlPath, ["status", id]);
+    return stdout.trim();
+  }
+  async delete(id) {
+    await run6(utmctlPath, ["delete", id]);
+  }
+  async list() {
+    const { stdout } = await run6(utmctlPath, ["list"]);
+    return stdout.split("\n").slice(1).map((line) => line.trim()).filter(Boolean).flatMap((line) => {
+      const match = line.match(/^(\S+)\s+(\S+)\s+(.+)$/);
+      return match ? [{ id: match[1], status: match[2], name: match[3].trim() }] : [];
+    });
+  }
+  async find(name) {
+    return (await this.list()).find((machine) => machine.name === name) ?? null;
+  }
+};
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+// src/UTM.ts
+var utmCacheDirectory = join4(
+  homedir(),
+  "Library/Containers/com.utmapp.UTM/Data/Documents/openstrap-cache"
+);
+var startAttempts = 40;
+var startInterval = 250;
+var shutdownAttempts = 120;
+var shutdownInterval = 500;
+var statuses = {
+  started: "running",
+  running: "running",
+  stopped: "stopped",
+  paused: "suspended",
+  suspended: "suspended"
+};
+var UTM = class {
+  constructor(machines = new UTMMachines(), cacheDirectory = utmCacheDirectory, files = new HostFiles(), network = new HostNetwork()) {
+    this.machines = machines;
+    this.images = new ImageCache(cacheDirectory, files, network, this.boxes);
+    this.cacheDirectory = cacheDirectory;
+  }
+  machines;
+  id = "utm";
+  displayName = "UTM";
+  capabilities = {
+    scopes: ["guest"],
+    types: ["vm"],
+    resize: false,
+    portForward: true
+  };
+  seed = new CloudInitSeed();
+  disk = new MachineDisk();
+  boxes = new BoxArchive();
+  images;
+  cacheDirectory;
+  async detect() {
+    const version = await this.machines.version();
+    if (version === null) {
+      return {
+        available: false,
+        reason: "UTM is not installed",
+        install: {
+          description: "UTM is the hypervisor that runs the machine. openstrap does not install it for you.",
+          command: "brew install --cask utm"
+        }
+      };
+    }
+    if (!await this.disk.available()) {
+      return {
+        available: false,
+        reason: "qemu-img is missing, so a machine cannot be given the disk its blueprint asks for",
+        install: {
+          description: "qemu-img resizes the disk image. It comes with QEMU, which UTM does not install.",
+          command: "brew install qemu"
+        }
+      };
+    }
+    return { available: true, version };
+  }
+  /**
+   * Creates a stopped machine with a disk of the size that was asked for, and the seed attached.
+   *
+   * The cached image is never modified: UTM copies each source into the machine's own package, and
+   * the cache is shared by everything built from that image and addressed by its digest. A machine
+   * that wants a bigger disk gets a copy of its own, grown before it is handed over — the partition
+   * inside it is grown by cloud-init on first boot.
+   */
+  async create(request) {
+    const hostPort = request.hostPort;
+    if (hostPort === void 0) {
+      throw new Error(`No host port was given to forward to SSH on machine "${request.name}"`);
+    }
+    await this.machines.ready();
+    const cached = await this.images.fetch(request.image);
+    const id = await this.machines.create({
+      name: request.name,
+      architecture: architectureFor(request.image.architecture),
+      memoryMiB: Math.round(request.resources.memoryBytes / (1024 * 1024)),
+      cpuCores: request.resources.cpuCores,
+      ...request.display === void 0 ? {} : { display: request.display }
+    });
+    const disk = await this.disk.of(
+      cached.path,
+      join4(this.cacheDirectory, `${request.name}-disk.qcow2`),
+      request.resources.diskBytes
+    );
+    const seedPath = await this.seed.build({
+      name: request.name,
+      user: request.user,
+      publicKey: request.publicKey,
+      destination: join4(this.cacheDirectory, `${request.name}-seed.iso`)
+    });
+    await this.machines.attachDrives(id, [
+      { source: disk },
+      { source: seedPath }
+    ]);
+    if (disk !== cached.path) {
+      await this.disk.discard(disk);
+    }
+    await this.machines.forwardPorts(id, [
+      { hostPort, guestPort: request.guestPort },
+      ...(request.publish ?? []).map((port) => ({ hostPort: port, guestPort: port }))
+    ]);
+    return { id, name: request.name };
+  }
+  /**
+   * Starts the machine and waits until it is running, because being told is not the same as being.
+   *
+   * UTM reports a refusal on its own output and exits zero, so a machine that never launched came
+   * back as started. What openstrap does next — reach it, read it, deliver itself to it — is all
+   * built on the machine being there, and each of those fails further from the reason.
+   */
+  async start(machine) {
+    await this.machines.start(machine.id);
+    for (let attempt = 0; attempt < startAttempts; attempt += 1) {
+      const status = await this.machines.status(machine.id);
+      if (statuses[status] === "running") {
+        return;
+      }
+      await new Promise((wake) => setTimeout(wake, startInterval));
+    }
+    throw new MachineDidNotStartError(machine.name, await this.machines.status(machine.id));
+  }
+  async stop(machine) {
+    await this.machines.stop(machine.id);
+  }
+  async restart(machine) {
+    await this.machines.stop(machine.id);
+    await this.machines.start(machine.id);
+  }
+  /**
+   * Deletes a machine, stopping it first.
+   *
+   * UTM refuses to delete a running machine, and it keeps the name reserved
+   * until the deletion lands — so creating the same target again would fail
+   * with "a virtual machine already exists with this name".
+   */
+  async delete(machine) {
+    if ((await this.inspect(machine)).status === "running") {
+      await this.machines.stop(machine.id).catch(() => void 0);
+    }
+    await this.machines.delete(machine.id);
+    for (let attempt = 0; attempt < 40; attempt += 1) {
+      if (!await this.machines.find(machine.name)) {
+        return;
+      }
+      await delay2(250);
+    }
+    throw new Error(`UTM still lists a machine named "${machine.name}" after deleting it`);
+  }
+  /**
+   * Adds forwards for ports not yet forwarded, on the same number. QEMU's user-mode network is
+   * fixed while it runs, so a running machine is shut down, changed and started again.
+   */
+  async publish(machine, ports) {
+    const card = (await this.machines.networkInterfaces(machine.id))[0];
+    if (card === void 0) {
+      throw new Error(`Machine "${machine.name}" has no network card to forward ports on`);
+    }
+    const added = ports.filter((port) => !card.portForwards.some((forward) => forward.guestPort === port));
+    if (added.length === 0) {
+      return { added, restarted: false };
+    }
+    const running = (await this.inspect(machine)).status === "running";
+    if (running) {
+      await this.shutDown(machine);
+    }
+    await this.machines.forwardPorts(machine.id, [
+      ...card.portForwards,
+      ...added.map((port) => ({ hostPort: port, guestPort: port }))
+    ], { index: card.index, address: card.address, hardware: card.hardware });
+    if (running) {
+      await this.start(machine);
+    }
+    return { added, restarted: running };
+  }
+  /** Asks the guest to power down and waits; pulls the plug only when it has not by the deadline. */
+  async shutDown(machine) {
+    await this.machines.requestShutdown(machine.id);
+    for (let attempt = 0; attempt < shutdownAttempts; attempt += 1) {
+      if ((await this.inspect(machine)).status === "stopped") {
+        return;
+      }
+      await delay2(shutdownInterval);
+    }
+    await this.machines.stop(machine.id);
+    for (let attempt = 0; attempt < startAttempts; attempt += 1) {
+      if ((await this.inspect(machine)).status === "stopped") {
+        return;
+      }
+      await delay2(startInterval);
+    }
+    throw new Error(`UTM did not stop "${machine.name}" when asked to`);
+  }
+  async inspect(machine) {
+    const status = await this.machines.status(machine.id);
+    return { status: statuses[status.toLowerCase()] ?? "unknown" };
+  }
+  async access(machine) {
+    const forwards = await this.machines.portForwards(machine.id);
+    const ssh = forwards.find((forward) => forward.guestPort === 22);
+    if (!ssh) {
+      throw new Error(`Machine "${machine.name}" has no forwarded port for SSH`);
+    }
+    return {
+      transport: "ssh",
+      endpoint: { host: "127.0.0.1", port: ssh.hostPort, user: "openstrap" }
+    };
+  }
+  async find(name) {
+    const machine = await this.machines.find(name);
+    return machine ? { id: machine.id, name: machine.name } : null;
+  }
+};
+function architectureFor(architecture) {
+  return architecture === "arm64" ? "aarch64" : "x86_64";
+}
+function delay2(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+// src/index.ts
+function openstrapUtm() {
+  return {
+    name: "openstrap:utm",
+    setup(api) {
+      api.registerProvider(new UTM());
+    }
+  };
+}
+export {
+  BoxArchive,
+  BoxDiskMissingError,
+  CloudInitSeed,
+  ImageCache,
+  ImageChecksumError,
+  MachineDidNotStartError,
+  UTM,
+  openstrapUtm as default,
+  utmCacheDirectory
+};

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@openstrap/utm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "OpenStrap UTM provider plugin",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && node scripts/bundle.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "test:live": "tsx src/test/provider-contract.live.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@openstrap/plugin-contract": "^0.1.1",
+    "@types/node": "^24.10.1",
+    "esbuild": "0.28.1",
+    "tsx": "^4.23.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.14"
+  }
+}