run-spaceapp 1.0.2 → 1.0.31

package/src/prompt-controller.mjs

@@ -0,0 +1,344 @@
+import { createWriteStream, readFileSync } from "node:fs";
+
+export class PromptController {
+  constructor({
+    stdin = process.stdin,
+    stdout = process.stdout,
+    stderr = process.stderr,
+    logFile = null,
+    nonInteractive = false,
+    answersFile = null,
+    answers = null,
+    planMode = false,
+    jsonMode = false
+  } = {}) {
+    this.stdin = stdin;
+    this.stdout = stdout;
+    this.stderr = stderr;
+    this.nonInteractive = nonInteractive;
+    this.planMode = planMode;
+    this.jsonMode = jsonMode;
+    this.logStream = logFile ? createWriteStream(logFile, { flags: "a" }) : null;
+    this.answers = answers ? { ...answers } : {};
+    this._sawCr = false;
+
+    if (answersFile) {
+      try {
+        const content = answersFile.trim().startsWith("{") ? answersFile : readFileSync(answersFile, "utf8");
+        const parsed = JSON.parse(content);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Answers must be a JSON object");
+        this.answers = { ...this.answers, ...parsed };
+      } catch (err) {
+        throw new Error(`Failed to parse answers file ${answersFile}: ${err.message}`);
+      }
+    }
+
+    if (!stdin._spaceappBuffer) {
+      stdin._spaceappBuffer = "";
+    }
+  }
+
+  log(message, { secret = false } = {}) {
+    if (this.logStream && !secret) {
+      this.logStream.write(`[${new Date().toISOString()}] ${message}\n`);
+    }
+  }
+
+  write(text, { secret = false } = {}) {
+    if (!this.jsonMode) {
+      this.stdout.write(text);
+    }
+    this.log(text.replace(/\r?\n$/, ""), { secret });
+  }
+
+  writeError(text) {
+    this.stderr.write(text);
+    this.log(`ERROR: ${text.replace(/\r?\n$/, "")}`);
+  }
+
+  isInteractive() {
+    return Boolean(this.stdin?.isTTY && typeof this.stdin?.setRawMode === "function");
+  }
+
+  async readLine(promptText, { mask = false, answerKey = null, defaultValue = "" } = {}) {
+    if (answerKey && this.answers[answerKey] !== undefined) {
+      const val = String(this.answers[answerKey]);
+      this.write(`${promptText}${mask ? "******" : val}\n`, { secret: mask });
+      return val;
+    }
+
+    if (this.nonInteractive) {
+      if (defaultValue !== undefined && defaultValue !== "") {
+        this.write(`${promptText}${defaultValue} (non-interactive default)\n`);
+        return defaultValue;
+      }
+      throw new Error(`Non-interactive execution refused prompt without answer: ${promptText.trim()}`);
+    }
+
+    this.write(promptText, { secret: false });
+
+    // Handle split CRLF from previous read: if previous ended with \r, strip leading \n
+    let buf = this.stdin._spaceappBuffer || "";
+    if (this._sawCr && buf.length > 0) {
+      if (buf.startsWith("\n")) {
+        buf = buf.slice(1);
+        this.stdin._spaceappBuffer = buf;
+      }
+      this._sawCr = false;
+    }
+
+    // 1. Check if unconsumed characters in buffer already contain a newline
+    const nlIdx = buf.search(/\r\n|\n|\r/);
+    if (nlIdx !== -1) {
+      const line = buf.slice(0, nlIdx);
+      if (buf[nlIdx] === "\r") {
+        if (buf.length > nlIdx + 1 && buf[nlIdx + 1] === "\n") {
+          this.stdin._spaceappBuffer = buf.slice(nlIdx + 2);
+        } else {
+          this.stdin._spaceappBuffer = buf.slice(nlIdx + 1);
+          this._sawCr = true;
+        }
+      } else {
+        this.stdin._spaceappBuffer = buf.slice(nlIdx + 1);
+      }
+      if (!mask) {
+        this.write(`${line}\n`);
+      } else {
+        this.write("\n", { secret: true });
+      }
+      return line;
+    }
+
+    // 2. Non-TTY / Piped stream (where setRawMode or isTTY is missing)
+    if (!this.stdin.isTTY || typeof this.stdin.setRawMode !== "function") {
+      return await new Promise((resolve, reject) => {
+        let current = this.stdin._spaceappBuffer || "";
+        this.stdin._spaceappBuffer = "";
+
+        const finish = (result) => {
+          cleanup();
+          this.write("\n", { secret: mask });
+          resolve(result);
+        };
+
+        const processBuffer = () => {
+          if (this._sawCr && current.length > 0) {
+            if (current.startsWith("\n")) {
+              current = current.slice(1);
+            }
+            this._sawCr = false;
+          }
+          const m = current.search(/\r\n|\n|\r/);
+          if (m !== -1) {
+            const res = current.slice(0, m);
+            if (current[m] === "\r") {
+              if (current.length > m + 1 && current[m + 1] === "\n") {
+                this.stdin._spaceappBuffer = current.slice(m + 2);
+              } else {
+                this.stdin._spaceappBuffer = current.slice(m + 1);
+                this._sawCr = true;
+              }
+            } else {
+              this.stdin._spaceappBuffer = current.slice(m + 1);
+            }
+            finish(res);
+            return true;
+          }
+          return false;
+        };
+
+        const onReadable = () => {
+          let chunk;
+          while ((chunk = this.stdin.read()) !== null) {
+            current += String(chunk);
+            if (processBuffer()) {
+              return;
+            }
+          }
+        };
+
+        const onEnd = () => finish(current);
+        const onClose = () => finish(current);
+        const onError = (err) => {
+          cleanup();
+          reject(err);
+        };
+
+        const cleanup = () => {
+          if (typeof this.stdin.off === "function") {
+            this.stdin.off("readable", onReadable);
+            this.stdin.off("end", onEnd);
+            this.stdin.off("close", onClose);
+            this.stdin.off("error", onError);
+          }
+        };
+
+        if (typeof this.stdin.read === "function" && typeof this.stdin.on === "function") {
+          this.stdin.on("readable", onReadable);
+          this.stdin.once("end", onEnd);
+          this.stdin.once("close", onClose);
+          this.stdin.once("error", onError);
+          onReadable();
+        } else if (typeof this.stdin[Symbol.asyncIterator] === "function") {
+          (async () => {
+            try {
+              const iterator = this.stdin[Symbol.asyncIterator]();
+              for (;;) {
+                const step = await iterator.next();
+                if (step.done) {
+                  finish(current);
+                  return;
+                }
+                current += String(step.value);
+                if (processBuffer()) {
+                  return;
+                }
+              }
+            } catch {
+              finish(current);
+            }
+          })();
+        } else {
+          finish(current);
+        }
+      });
+    }
+
+    // 3. Interactive TTY stream (Real TTY or test mock implementing isTTY + setRawMode)
+    if (typeof this.stdin.setRawMode === "function") {
+      this.stdin.setRawMode(true);
+    }
+    if (typeof this.stdin.resume === "function") {
+      this.stdin.resume();
+    }
+    if (typeof this.stdin.setEncoding === "function") {
+      this.stdin.setEncoding("utf8");
+    }
+    let value = "";
+    try {
+      const iterator = this.stdin[Symbol.asyncIterator]();
+      for (;;) {
+        const step = await iterator.next();
+        if (step.done) break;
+        const chars = Array.from(String(step.value));
+        for (let i = 0; i < chars.length; i++) {
+          const character = chars[i];
+          if (this._sawCr && character === "\n") {
+            this._sawCr = false;
+            continue;
+          }
+          this._sawCr = false;
+          if (character === "\u0003") {
+            throw new Error("Input cancelled.");
+          }
+          if (character === "\r" || character === "\n") {
+            if (character === "\r") {
+              this._sawCr = true;
+            }
+            if (i + 1 < chars.length) {
+              let rest = chars.slice(i + 1).join("");
+              if (character === "\r" && rest.startsWith("\n")) {
+                rest = rest.slice(1);
+                this._sawCr = false;
+              }
+              this.stdin._spaceappBuffer = (this.stdin._spaceappBuffer || "") + rest;
+            }
+            this.write("\n", { secret: mask });
+            return value;
+          }
+          if (character === "\u007f" || character === "\u0008") {
+            if (value.length > 0) {
+              value = value.slice(0, -1);
+              this.stdout.write("\b \b");
+            }
+            continue;
+          }
+          value += character;
+          if (mask) {
+            this.stdout.write("*");
+          } else {
+            this.stdout.write(character);
+          }
+        }
+      }
+      this.write("\n", { secret: mask });
+      return value;
+    } finally {
+      if (typeof this.stdin.setRawMode === "function") {
+        this.stdin.setRawMode(false);
+      }
+      if (typeof this.stdin.pause === "function") {
+        this.stdin.pause();
+      }
+    }
+  }
+
+  async promptYesNo(question, { defaultYes = false, answerKey = null } = {}) {
+    for (;;) {
+      const raw = await this.readLine(
+        `${question} [${defaultYes ? "Y/n" : "y/N"}] `,
+        { mask: false, answerKey, defaultValue: defaultYes ? "y" : "n" }
+      );
+      const answer = raw.trim().toLowerCase();
+      if (answer === "") {
+        return defaultYes;
+      }
+      if (answer === "y" || answer === "yes" || answer === "true" || answer === "1") {
+        return true;
+      }
+      if (answer === "n" || answer === "no" || answer === "false" || answer === "0") {
+        return false;
+      }
+      this.write("Please answer y or n.\n");
+    }
+  }
+
+  async promptChoice(question, options, { defaultIndex = 0, answerKey = null } = {}) {
+    this.write(`${question}\n`);
+    options.forEach((option, index) => {
+      this.write(`  [${index + 1}] ${option.label}\n`);
+    });
+    for (;;) {
+      const raw = await this.readLine(
+        `Select 1-${options.length} [${defaultIndex + 1}]: `,
+        { mask: false, answerKey, defaultValue: String(defaultIndex + 1) }
+      );
+      const answer = raw.trim();
+      if (answer === "") {
+        return options[defaultIndex].value;
+      }
+      const matched = options.find(
+        (o) =>
+          String(o.value).toLowerCase() === answer.toLowerCase() ||
+          o.label.toLowerCase() === answer.toLowerCase()
+      );
+      if (matched) {
+        return matched.value;
+      }
+      const index = Number.parseInt(answer, 10);
+      if (Number.isInteger(index) && index >= 1 && index <= options.length) {
+        return options[index - 1].value;
+      }
+      this.write(`Invalid choice. Enter a number between 1 and ${options.length}.\n`);
+    }
+  }
+
+  async finalConfirmation(lines, { answerKey = "approvePlan" } = {}) {
+    this.write("SpaceApp setup plan:\n");
+    for (const line of lines) {
+      this.write(`  - ${line}\n`);
+    }
+    const approved = await this.promptYesNo("Apply this plan?", { defaultYes: false, answerKey });
+    if (!approved) {
+      this.write("Cancelled. No changes were made.\n");
+    }
+    return approved;
+  }
+
+  async close() {
+    if (this.logStream) {
+      await new Promise((resolve) => this.logStream.end(resolve));
+      this.logStream = null;
+    }
+  }
+}

package/src/storage.mjs

@@ -0,0 +1,159 @@
+import { Writable } from "node:stream";
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { composeCommand, profileRuntimeSettings, PROFILE_REQUIREMENTS } from "./index.mjs";
+
+const GiB = 1024 ** 3;
+const MiB = 1024 ** 2;
+// Upper bounds include extraction/transfer headroom, not the size of existing data.
+const imageReserve = { core: 1.4 * GiB, cli: 3.8 * GiB, browser: 2.2 * GiB, postgres: 700 * MiB, temporal: 800 * MiB };
+
+export async function captureProbe(execute, spec) {
+  let output = "";
+  const stdout = new Writable({ write(chunk, _encoding, done) {
+    if (output.length < 1024 * 1024) output += chunk.toString();
+    done();
+  } });
+  try {
+    const code = await execute({ ...spec, timeoutMs: 15000 }, { stdout, stderr: null });
+    return code === 0 ? output.trim() : null;
+  } catch { return null; }
+}
+
+async function configurationBytes(root) {
+  let bytes = 0;
+  // Checkpoints copy configuration and secrets; workspaces/volumes are retained in place.
+  async function walk(path) {
+    for (const entry of await readdir(path, { withFileTypes: true }).catch(() => [])) {
+      const child = join(path, entry.name);
+      if (entry.isDirectory()) await walk(child);
+      else if (entry.isFile()) bytes += (await stat(child)).size;
+    }
+  }
+  await walk(join(root, "secrets"));
+  for (const file of ["config.json", "runtime.env", "compose.yml", "compose.workspaces.yml", "compose.host-access.yml"]) {
+    bytes += (await stat(join(root, file)).catch(() => ({ size: 0 }))).size;
+  }
+  return bytes;
+}
+
+export function calculateStoragePlan({ operation, profile, missingImageBytes = 0, databaseBytes = 0, configBytes = 0, databaseSizeKnown = true }) {
+  const checkpointBytes = operation === "upgrade"
+    ? Math.max(64 * MiB, databaseSizeKnown ? databaseBytes * 3 + configBytes : 512 * MiB + configBytes)
+    : 0;
+  return {
+    operation, missingImageBytes, checkpointBytes, databaseSizeKnown,
+    requiredDiskBytes: Math.ceil(missingImageBytes + checkpointBytes + 512 * MiB),
+    freshDiskBytes: PROFILE_REQUIREMENTS[profile].freshDiskBytes
+  };
+}
+
+export function estimateMissingLayers(layers, diffIds, cachedLayers) {
+  if (!Array.isArray(layers) || layers.length !== diffIds?.length) throw new Error("Invalid image layer metadata.");
+  let bytes = 0;
+  for (let i = 0; i < layers.length; i++) {
+    if (cachedLayers.has(diffIds[i])) continue;
+    if (!Number.isSafeInteger(layers[i].size) || layers[i].size < 0) throw new Error("Invalid image layer size.");
+    bytes += Math.max(64 * MiB, layers[i].size * 5);
+  }
+  return bytes;
+}
+
+async function registryLayers(image, arch, fetch) {
+  const match = /^ghcr\.io\/(oll4com\/spaceapp-(?:core|cli|browser)):([0-9]+\.[0-9]+\.[0-9]+)$/.exec(image);
+  if (!match) return null;
+  const repository = match[1], tag = match[2];
+  const requestJson = async (url, headers = {}) => {
+    const response = await fetch(url, { headers, signal: AbortSignal.timeout(8000), redirect: "follow" });
+    if (!response.ok) throw new Error("Public image metadata unavailable.");
+    const text = await response.text();
+    if (text.length > 2 * 1024 * 1024) throw new Error("Oversized image metadata.");
+    return JSON.parse(text);
+  };
+  const credentials = await requestJson(`https://ghcr.io/token?service=ghcr.io&scope=repository:${repository}:pull`);
+  if (typeof credentials.token !== "string") return null;
+  const headers = { authorization: `Bearer ${credentials.token}`, accept: "application/vnd.oci.image.index.v1+json, application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.oci.image.manifest.v1+json, application/vnd.docker.distribution.manifest.v2+json" };
+  let manifest = await requestJson(`https://ghcr.io/v2/${repository}/manifests/${tag}`, headers);
+  if (manifest.manifests) {
+    const descriptor = manifest.manifests.find((item) => item.platform?.os === "linux" && item.platform?.architecture === arch);
+    if (!/^sha256:[a-f0-9]{64}$/.test(descriptor?.digest ?? "")) return null;
+    manifest = await requestJson(`https://ghcr.io/v2/${repository}/manifests/${descriptor.digest}`, headers);
+  }
+  if (!/^sha256:[a-f0-9]{64}$/.test(manifest.config?.digest ?? "")) return null;
+  const config = await requestJson(`https://ghcr.io/v2/${repository}/blobs/${manifest.config.digest}`, headers);
+  return { layers: manifest.layers, diffIds: config.rootfs?.diff_ids };
+}
+
+export async function inspectStoragePlan({ root, config, existingConfig, resources, execute, operation, fetch = globalThis.fetch }) {
+  const dockerInfo = await captureProbe(execute, { command: "docker", args: ["info", "--format", "{{json .}}"] });
+  let engine = null;
+  try { engine = JSON.parse(dockerInfo); } catch { /* Conservative reserve when the engine is unavailable. */ }
+  const cachedLayers = new Set();
+  if (engine && existingConfig) {
+    for (const type of ["core", "cli", "browser"]) {
+      const output = await captureProbe(execute, { command: "docker", args: ["image", "inspect", "--format", "{{json .RootFS.Layers}}", `ghcr.io/oll4com/spaceapp-${type}:${existingConfig.version}`] });
+      try { for (const layer of JSON.parse(output)) cachedLayers.add(layer); } catch {}
+    }
+  }
+  const settings = profileRuntimeSettings(config.profile);
+  const images = [
+    ["core", `ghcr.io/oll4com/spaceapp-core:${config.version}`],
+    ["cli", `ghcr.io/oll4com/spaceapp-cli:${config.version}`],
+    ["postgres", "pgvector/pgvector:0.8.3-pg17-trixie"],
+    ...(settings.browserEnabled ? [["browser", `ghcr.io/oll4com/spaceapp-browser:${config.version}`]] : []),
+    ...(settings.temporalEnabled ? [["temporal", "temporalio/auto-setup:1.29.1"]] : []),
+    ...(config.companionsEnabled ? [["companion", "ghcr.io/soju06/codex-lb:1.22.0"], ["companion", "ghcr.io/oll4com/headroom-codex-lb:code"]] : [])
+  ];
+  let missingImageBytes = 0;
+  const missingImages = [];
+  let sharedLayersEstimated = false;
+  for (const [type, image] of images) {
+    const cached = await captureProbe(execute, { command: "docker", args: ["image", "inspect", "--format", "{{.Id}}", image] });
+    if (!/^sha256:[a-f0-9]{64}$/.test(cached ?? "")) {
+      missingImages.push(image);
+      let reserve = imageReserve[type] ?? GiB;
+      if (engine && existingConfig && cachedLayers.size && typeof fetch === "function") {
+        try {
+          const metadata = await registryLayers(image, /arm|aarch64/.test(engine.Architecture ?? "") ? "arm64" : "amd64", fetch);
+          if (metadata) { reserve = estimateMissingLayers(metadata.layers, metadata.diffIds, cachedLayers); sharedLayersEstimated = true; }
+        } catch { /* Offline/private registry: retain the full conservative reserve. */ }
+      }
+      missingImageBytes += reserve;
+    }
+  }
+  let databaseBytes = 0, databaseSizeKnown = true;
+  if (operation === "upgrade") {
+    const size = await captureProbe(execute, composeCommand("databaseSize", root, existingConfig ?? config));
+    databaseSizeKnown = /^\d+$/.test(size ?? "");
+    if (databaseSizeKnown) databaseBytes = Number(size);
+  }
+  const plan = calculateStoragePlan({ operation, profile: config.profile, missingImageBytes, databaseBytes,
+    configBytes: await configurationBytes(root), databaseSizeKnown });
+  let dockerFreeDiskBytes = null;
+  if (existingConfig) {
+    const free = await captureProbe(execute, composeCommand("storageFree", root, existingConfig));
+    if (/^\d+$/.test(free ?? "")) dockerFreeDiskBytes = Number(free);
+  }
+  // Linux can measure the Docker filesystem directly even on a fresh install.
+  if (engine?.DockerRootDir && process.platform === "linux") {
+    const { inspectSystemResources } = await import("./index.mjs");
+    try { dockerFreeDiskBytes = (await inspectSystemResources(engine.DockerRootDir)).freeDiskBytes; } catch {}
+  }
+  return { ...plan, missingImages, sharedLayersEstimated, dockerFreeDiskBytes,
+    resources: { ...resources,
+      freeDiskBytes: dockerFreeDiskBytes === null ? resources.freeDiskBytes : Math.min(resources.freeDiskBytes, dockerFreeDiskBytes),
+      engineCpuCount: engine?.NCPU,
+      engineMemoryBytes: engine?.MemTotal
+    } };
+}
+
+export function storageChecks(plan, resources) {
+  const checks = [{ name: "Free disk", ok: resources.freeDiskBytes >= plan.requiredDiskBytes,
+    detail: `${gib(resources.freeDiskBytes)} GiB available; ${gib(plan.requiredDiskBytes)} GiB required additionally for ${plan.operation} (images ${gib(plan.missingImageBytes)}, checkpoint ${gib(plan.checkpointBytes)}, reserve 0.5)` }];
+  if (plan.dockerFreeDiskBytes !== null) checks.push({ name: "Docker storage", ok: plan.dockerFreeDiskBytes >= plan.requiredDiskBytes,
+    detail: `${gib(plan.dockerFreeDiskBytes)} GiB available; ${gib(plan.requiredDiskBytes)} GiB required additionally` });
+  else checks.push({ name: "Docker storage", ok: true, detail: "Separate engine disk capacity unavailable; host estimate used. Docker ENOSPC will stop the operation before cutover." });
+  return checks;
+}
+
+function gib(bytes) { return (bytes / GiB).toFixed(2); }

package/src/support-manifest.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "version": "1.0.0",
+  "generatedAt": "2026-09-28T14:00:00Z",
+  "launcher": {
+    "name": "run-spaceapp",
+    "minNodeVersion": ">=20.11",
+    "recommendedNode": "22.x",
+    "ltsLines": ["20.x", "22.x"]
+  },
+  "runtime": {
+    "profiles": [
+      {
+        "id": "light",
+        "description": "Minimal memory footprint, essential services only (spaceapp-core, spaceapp-cli, postgres, temporal)",
+        "minMemoryMb": 4096,
+        "recommendedMemoryMb": 8192
+      },
+      {
+        "id": "standard",
+        "description": "Full desktop & browser workspace capability (+ automated browser host, companions)",
+        "minMemoryMb": 8192,
+        "recommendedMemoryMb": 16384
+      }
+    ],
+    "companionsToggle": true,
+    "telemetryToggle": true
+  },
+  "platforms": {
+    "windows": {
+      "supported": true,
+      "variants": [
+        {
+          "id": "win11-x64",
+          "os": "Windows 11",
+          "arch": "x64",
+          "shells": ["cmd", "powershell5", "powershell7"],
+          "terminals": ["conhost", "windowsterminal"],
+          "docker": {
+            "type": "Docker Desktop",
+            "minVersion": "4.30.0",
+            "backend": "WSL2"
+          },
+          "executionPolicyBypass": "npx.cmd / spaceapp.cmd (no machine policy change)"
+        },
+        {
+          "id": "win11-arm64",
+          "os": "Windows 11",
+          "arch": "arm64",
+          "docker": {
+            "type": "Docker Desktop",
+            "minVersion": "4.30.0",
+            "backend": "WSL2 ARM64"
+          }
+        }
+      ]
+    },
+    "macos": {
+      "supported": true,
+      "variants": [
+        {
+          "id": "macos-intel",
+          "os": "macOS 13+ (Ventura / Sonoma / Sequoia)",
+          "arch": "x64",
+          "shells": ["zsh", "bash"],
+          "docker": {
+            "type": "Docker Desktop",
+            "minVersion": "4.30.0"
+          }
+        },
+        {
+          "id": "macos-apple-silicon",
+          "os": "macOS 13+ (Ventura / Sonoma / Sequoia)",
+          "arch": "arm64",
+          "shells": ["zsh", "bash"],
+          "docker": {
+            "type": "Docker Desktop",
+            "minVersion": "4.30.0"
+          }
+        }
+      ]
+    },
+    "linux": {
+      "supported": true,
+      "variants": [
+        {
+          "id": "ubuntu-debian-x64",
+          "families": ["Ubuntu 22.04 LTS", "Ubuntu 24.04 LTS", "Debian 12 Bookworm"],
+          "arch": "x64",
+          "packageManagers": ["apt"],
+          "docker": {
+            "type": "Docker Engine / Compose v2",
+            "installMethod": "official-docker-apt-repo"
+          }
+        },
+        {
+          "id": "ubuntu-debian-arm64",
+          "families": ["Ubuntu 22.04 LTS", "Ubuntu 24.04 LTS", "Debian 12 Bookworm"],
+          "arch": "arm64",
+          "packageManagers": ["apt"],
+          "docker": {
+            "type": "Docker Engine / Compose v2",
+            "installMethod": "official-docker-apt-repo"
+          }
+        },
+        {
+          "id": "fedora-rhel-x64",
+          "families": ["Fedora 39+", "RHEL 9", "CentOS Stream 9"],
+          "arch": "x64",
+          "packageManagers": ["dnf5", "dnf"],
+          "docker": {
+            "type": "Docker Engine / Compose v2",
+            "installMethod": "official-docker-dnf-repo"
+          }
+        },
+        {
+          "id": "arch-cachyos-x64",
+          "families": ["Arch Linux", "CachyOS"],
+          "arch": "x64",
+          "packageManagers": ["pacman"],
+          "docker": {
+            "type": "Docker Engine / Compose v2",
+            "installMethod": "pacman-official-repo"
+          }
+        }
+      ]
+    }
+  },
+  "fixtures": [
+    {
+      "id": "clean_os",
+      "description": "Base OS without Node.js or Docker"
+    },
+    {
+      "id": "node_only",
+      "description": "Node.js LTS installed, Docker missing or inactive"
+    },
+    {
+      "id": "prereqs_ready",
+      "description": "Node.js and Docker active and ready"
+    },
+    {
+      "id": "existing_install",
+      "description": "Previous SpaceApp install with database, test user, workspace markers"
+    }
+  ]
+}