humanish 0.112.0 → 0.114.0

package/dist/substrates/local/runtime-host.js

@@ -4,6 +4,8 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 import { cli } from "../../cli/invocation.js";
+import { defaultVmSize, machineSize, vmSizeProblem, } from "./capacity.js";
+import { plural } from "../../run/text.js";
 const exec = promisify(execFile);
 export const LIMA_INSTANCE = "humanish-runtime";
 export const usesLima = (options = {}) => (options.platform ?? process.platform) === "darwin";
@@ -44,12 +46,12 @@ export async function runtimeDocker(args, options = {}, timeout = 15_000) {
 }
 // No host mounts, agent forwarding or automatic app-port discovery. Per-study
 // OpenSSH forwards grant just the selected app and browser-control sockets.
-const LIMA_TEMPLATE = `minimumLimaVersion: 2.2.0
+const limaTemplate = (size) => `minimumLimaVersion: 2.2.0
 vmType: vz
 arch: aarch64
 nestedVirtualization: true
-cpus: 6
-memory: 8GiB
+cpus: ${size.cpus}
+memory: ${size.memoryGiB}GiB
 disk: 80GiB
 images:
   - location: https://cloud.debian.org/images/cloud/trixie/20260712-2537/debian-13-genericcloud-arm64-20260712-2537.qcow2
@@ -101,16 +103,44 @@ export async function limaStatus(options = {}) {
     if (instance &&
         (instance.name !== LIMA_INSTANCE || instance.vmType !== "vz" || instance.arch !== "aarch64"))
         throw new Error(`The existing ${LIMA_INSTANCE} Lima instance is incompatible. humanish will not replace it.`);
+    // `limactl list --json` reports the instance's configured memory in bytes.
+    const size = Number.isInteger(instance?.cpus) && Number.isFinite(instance?.memory)
+        ? { cpus: instance.cpus, memoryBytes: instance.memory }
+        : undefined;
     return {
         ready: instance?.status === "Running",
         exists: !!instance,
+        ...(size === undefined ? {} : { size }),
         message: instance
             ? `The humanish Lima host is stopped. Run ${cli("runtime setup")} to start it.`
             : `Run ${cli("runtime setup")} to create the humanish Lima host and install the browser runtime.`,
     };
 }
+/**
+ * Start the humanish Lima VM, creating it at `size` (or the default size) when it does not exist.
+ * An existing VM keeps its size unless `size` differs, in which case it is stopped, resized and
+ * started again.
+ */
 export async function prepareLima(options = {}, progress) {
     const status = await limaStatus(options);
+    const mac = machineSize(options.machine);
+    const current = status.size === undefined
+        ? defaultVmSize(mac)
+        : { memoryGiB: status.size.memoryBytes / 1024 ** 3, cpus: status.size.cpus };
+    const size = { ...current, ...options.size };
+    if (options.size !== undefined) {
+        const problem = vmSizeProblem(size, mac);
+        if (problem !== undefined)
+            throw new Error(problem);
+    }
+    // An existing VM whose size Lima did not list gets the asked-for size without a comparison.
+    const differs = status.size === undefined
+        ? options.size !== undefined
+        : size.cpus !== current.cpus || size.memoryGiB !== current.memoryGiB;
+    if (status.exists && differs) {
+        await resizeLima(size, status.ready, options, progress);
+        return;
+    }
     if (status.ready)
         return;
     progress?.(status.exists
@@ -123,7 +153,7 @@ export async function prepareLima(options = {}, progress) {
         const work = await mkdtemp(path.join(tmpdir(), "humanish-lima-"));
         try {
             const file = path.join(work, "host.yaml");
-            await writeFile(file, LIMA_TEMPLATE, { mode: 0o600 });
+            await writeFile(file, limaTemplate(size), { mode: 0o600 });
             await hostExec("limactl", ["start", "--tty=false", "--name", LIMA_INSTANCE, file], options, 15 * 60_000);
         }
         finally {
@@ -131,6 +161,21 @@ export async function prepareLima(options = {}, progress) {
         }
     }
 }
+/** Lima changes the memory and CPUs of a stopped instance only. Running desktops keep it running. */
+async function resizeLima(size, running, options, progress) {
+    if (running) {
+        const desktops = (await runtimeDocker(["ps", "--quiet", "--filter", "label=to.humanish.runtime.api=1"], options)).stdout
+            .split("\n")
+            .filter((line) => line.trim() !== "");
+        if (desktops.length > 0)
+            throw new Error(`${plural(desktops.length, "participant desktop")} ${desktops.length === 1 ? "is" : "are"} running in the humanish Lima VM, so it was not resized. Wait for the study to finish, then run ${cli(`runtime setup --memory ${size.memoryGiB} --cpus ${size.cpus}`)} again.`);
+        progress?.("Stopping the humanish Lima VM to resize it…");
+        await hostExec("limactl", ["stop", LIMA_INSTANCE], options, 5 * 60_000);
+    }
+    progress?.(`Resizing the humanish Lima VM to ${size.memoryGiB} GiB and ${size.cpus} CPUs…`);
+    await hostExec("limactl", ["edit", "--cpus", String(size.cpus), "--memory", String(size.memoryGiB), LIMA_INSTANCE], options);
+    await hostExec("limactl", ["start", "--tty=false", LIMA_INSTANCE], options, 15 * 60_000);
+}
 /** Copy across the OS boundary explicitly; shared folders cannot carry sockets. */
 export async function loadRuntimeArchive(archive, options) {
     if (!usesLima(options)) {

package/dist/substrates/local/runtime.d.ts

@@ -1,4 +1,5 @@
 import type { LocalFirecrackerAssets } from "./firecracker-desktop.js";
+import { type LocalCapacity, type VmSize } from "./capacity.js";
 import { type RuntimeHostOptions } from "./runtime-host.js";
 export interface LocalRuntimeRelease {
     url: string;
@@ -11,13 +12,22 @@ export interface LocalRuntimeStatus {
     installed: boolean;
     message: string;
     assets?: LocalFirecrackerAssets;
+    /** How many desktops fit, when the VM or this machine could be read. */
+    capacity?: LocalCapacity;
 }
 interface RuntimeOptions extends RuntimeHostOptions {
     media?: boolean;
+    /** The Lima VM size `runtime setup --memory --cpus` asks for. Macs only. */
+    size?: Partial<VmSize>;
     progress?: (message: string) => void;
     /** Explicit source-build/test override; never provided by a participant. */
     release?: LocalRuntimeRelease;
 }
+/**
+ * How many desktops the local runtime holds, read without starting anything. Undefined when the
+ * host cannot be read, such as a Mac without Lima: preparing the runtime reports that.
+ */
+export declare function localRuntimeCapacity(options?: RuntimeHostOptions): Promise<LocalCapacity | undefined>;
 /** Read-only host and cache inspection. Never pulls an image or starts a container. */
 export declare function localRuntimeStatus(options?: RuntimeOptions): Promise<LocalRuntimeStatus>;
 /** Docker owns the installed image/cache. The archive is verified before docker load. */

package/dist/substrates/local/runtime.js

@@ -6,30 +6,67 @@ import path from "node:path";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { LOCAL_MEDIA_RUNTIME_RELEASES, LOCAL_RUNTIME_RELEASES } from "./runtime-release.js";
+import { defaultVmSize, localCapacity, machineSize, } from "./capacity.js";
 import { limaStatus, loadRuntimeArchive, prepareLima, runtimeArchitecture, runtimeDocker, runtimeExec, usesLima, } from "./runtime-host.js";
 import { cli } from "../../cli/invocation.js";
 const docker = async (args, options) => (await runtimeDocker(args, options)).stdout.trim();
 const runtimeRelease = (options) => options.release ??
     (options.media ? LOCAL_MEDIA_RUNTIME_RELEASES : LOCAL_RUNTIME_RELEASES)[runtimeArchitecture(options) ?? "amd64"];
+/** Desktops the existing Lima VM holds, the VM setup would create, or this Linux machine. */
+function runtimeCapacity(options, lima) {
+    if (lima === undefined)
+        return localCapacity("linux-host", machineSize(options.machine));
+    const machine = machineSize(options.machine);
+    if (lima.size !== undefined)
+        return localCapacity("lima-vm", lima.size, { machine });
+    // An existing VM whose size Lima did not list has an unknown size, which no default replaces.
+    if (lima.exists)
+        return undefined;
+    const planned = defaultVmSize(machine);
+    return localCapacity("lima-vm", { memoryBytes: planned.memoryGiB * 1024 ** 3, cpus: planned.cpus }, { planned: true, machine });
+}
+/**
+ * How many desktops the local runtime holds, read without starting anything. Undefined when the
+ * host cannot be read, such as a Mac without Lima: preparing the runtime reports that.
+ */
+export async function localRuntimeCapacity(options = {}) {
+    if (runtimeArchitecture(options) === undefined)
+        return undefined;
+    if (!usesLima(options))
+        return runtimeCapacity(options, undefined);
+    try {
+        return runtimeCapacity(options, await limaStatus(options));
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Read-only host and cache inspection. Never pulls an image or starts a container. */
 export async function localRuntimeStatus(options = {}) {
-    const architecture = runtimeArchitecture(options), lima = usesLima(options);
+    const architecture = runtimeArchitecture(options);
     if (!architecture)
         return {
             ok: false,
             installed: false,
             message: "Local browsers need Linux x64 or an M3-or-newer Mac with Lima.",
         };
-    if (lima) {
+    let lima;
+    if (usesLima(options)) {
         try {
-            const status = await limaStatus(options);
-            if (!status.ready)
-                return { ok: true, installed: false, message: status.message };
+            lima = await limaStatus(options);
         }
         catch (error) {
             return { ok: false, installed: false, message: error.message };
         }
     }
+    const capacity = runtimeCapacity(options, lima);
+    const sized = capacity === undefined ? {} : { capacity };
+    if (lima !== undefined && !lima.ready)
+        return { ok: true, installed: false, message: lima.message, ...sized };
+    return { ...(await engineStatus(options, architecture, lima !== undefined)), ...sized };
+}
+/** The Docker engine, devices and cached image the desktops run on. */
+async function engineStatus(options, architecture, lima) {
     const env = options.env ?? process.env;
     if (!lima && env.DOCKER_HOST && !env.DOCKER_HOST.startsWith("unix://")) {
         return {
@@ -142,6 +179,8 @@ export async function localRuntimeStatus(options = {}) {
 export async function prepareLocalRuntime(options = {}) {
     if (!runtimeArchitecture(options))
         throw new Error((await localRuntimeStatus(options)).message);
+    if (options.size !== undefined && !usesLima(options))
+        throw new Error("--memory and --cpus size the humanish Lima VM, which runs only on a Mac. On Linux, desktops use this machine's memory and CPUs directly.");
     if (usesLima(options))
         await prepareLima(options, options.progress);
     const before = await localRuntimeStatus(options);