run-spaceapp 0.1.3 → 0.1.6

package/README.md

@@ -20,10 +20,19 @@ Windows 11 PowerShell:
 npm install -g run-spaceapp; if ($LASTEXITCODE -eq 0) { spaceapp install }
 ```
 
-The launcher requires Node.js 20.11 or newer, 4 CPUs, 8 GB RAM, 15 GiB free
-disk, and Docker Compose. `spaceapp install` initializes, checks, downloads,
-starts, and opens SpaceApp. It selects the `light` profile below 12 GiB RAM and
-the `standard` profile otherwise; override this with `--profile light` or
+The launcher requires Node.js 20.11 or newer, 4 CPUs, 8 GB RAM, and 15 GiB free
+disk. If Docker is missing, `spaceapp install` automatically installs it from
+official Docker sources on Windows, macOS, Ubuntu, Debian, Fedora, RHEL, and
+CentOS, starts it, and waits for Engine and Compose readiness before pulling
+images. Windows prefers Windows Package Manager's hash-pinned Docker Desktop
+manifest and retains a signed direct-download fallback. Docker Desktop license
+acceptance and Linux `docker` group membership require confirmation inside the
+same command. On Windows, approve any UAC prompt required by WSL2 or Docker
+Desktop. If Windows requests one restart, rerun the same command afterward and
+installation continues safely.
+
+The launcher selects the `light` profile below 12 GiB RAM and the `standard`
+profile otherwise; override this with `--profile light` or
 `--profile standard`.
 
 Light mode retains every bundled CLI and the core data/workflow services while

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run-spaceapp",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "Cross-platform Docker launcher for the SpaceApp self-hosted agent workspace",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,7 +29,7 @@
   ],
   "scripts": {
     "test": "node --test tests/*.test.mjs",
-    "check": "node --check bin/spaceapp.mjs && node --check src/index.mjs && node --check src/cli.mjs",
+    "check": "node --check bin/spaceapp.mjs && node --check src/index.mjs && node --check src/cli.mjs && node --check src/prerequisites.mjs",
     "pack:dry-run": "npm pack --dry-run"
   },
   "repository": {
@@ -44,5 +44,6 @@
   "publishConfig": {
     "access": "public",
     "provenance": true
-  }
+  },
+  "gitHead": "81bf4f16666f75cec5b499df28115df3c28e36b8"
 }

package/src/cli.mjs

@@ -20,15 +20,39 @@ import {
   writeRuntimeFiles,
   writeSetupToken
 } from "./index.mjs";
+import {
+  ensureDockerAvailable,
+  windowsPowerShellArgs
+} from "./prerequisites.mjs";
+
+const trustedCommands = new Set([
+  "codesign",
+  "docker",
+  "explorer.exe",
+  "hdiutil",
+  "open",
+  "powershell.exe",
+  "sg",
+  "spctl",
+  "sudo",
+  "winget.exe",
+  "wsl.exe",
+  "xdg-open"
+]);
+const trustedEnvironmentNames = new Set([
+  "SPACEAPP_DOCKER_INSTALLER_PATH"
+]);
 
 export async function run(argv, {
   env = process.env,
   platform = process.platform,
+  arch = process.arch,
   stdout = process.stdout,
   stderr = process.stderr,
   stdin = process.stdin,
   execute = executeCommand,
-  inspectResources = inspectSystemResources
+  inspectResources = inspectSystemResources,
+  ensureDocker = ensureDockerAvailable
 } = {}) {
   const [command = "help", ...args] = argv;
   const root = resolveSpaceAppHome({ env, platform });
@@ -47,11 +71,14 @@ export async function run(argv, {
       root,
       version,
       platform,
+      arch,
+      env,
       stdin,
       stdout,
       stderr,
       execute,
-      inspectResources
+      inspectResources,
+      ensureDocker
     });
   }
   if (command === "init") {
@@ -173,11 +200,14 @@ async function installCommand(args, {
   root,
   version,
   platform,
+  arch,
+  env,
   stdin,
   stdout,
   stderr,
   execute,
-  inspectResources
+  inspectResources,
+  ensureDocker
 }) {
   const { requestedProfile, noOpen } = parseInstallArgs(args);
   const resources = await inspectResources(root);
@@ -193,6 +223,38 @@ async function installCommand(args, {
     stdout.write("Store it temporarily; it expires after first owner setup.\n");
   }
 
+  if (installResourceChecks(resources).some((check) => !check.ok)) {
+    const doctorCode = await doctor({
+      root,
+      platform,
+      stdout,
+      stderr,
+      execute,
+      stdin,
+      inspectResources,
+      resources
+    });
+    stderr.write("Installation stopped before downloading images. Fix the failed checks and run the same command again.\n");
+    return doctorCode;
+  }
+
+  const prerequisiteResult = await ensureDocker({
+    platform,
+    arch,
+    env,
+    stdin,
+    stdout,
+    stderr,
+    execute,
+    installArgs: { requestedProfile, noOpen }
+  });
+  if (prerequisiteResult.reexecuted || prerequisiteResult.code !== 0) {
+    if (prerequisiteResult.code !== 0) {
+      stderr.write("Installation stopped before downloading images. Fix the failed checks and run the same command again.\n");
+    }
+    return prerequisiteResult.code;
+  }
+
   const doctorCode = await doctor({
     root,
     platform,
@@ -201,7 +263,8 @@ async function installCommand(args, {
     execute,
     stdin,
     inspectResources,
-    resources
+    resources,
+    dockerReady: true
   });
   if (doctorCode !== 0) {
     stderr.write("Installation stopped before downloading images. Fix the failed checks and run the same command again.\n");
@@ -392,7 +455,8 @@ async function doctor({
   execute,
   stdin,
   inspectResources,
-  resources
+  resources,
+  dockerReady = false
 }) {
   const detectedResources = resources ?? await inspectResources(root);
   const checks = [
@@ -403,9 +467,12 @@ async function doctor({
   let dockerMissing = false;
   for (const probe of [
     { name: "Docker", command: "docker", args: ["--version"] },
-    { name: "Docker Compose", command: "docker", args: ["compose", "version"] }
+    { name: "Docker Compose", command: "docker", args: ["compose", "version"] },
+    { name: "Docker Engine", command: "docker", args: ["info"] }
   ]) {
-    const code = await execute(probe, { stdin, stdout: null, stderr: null });
+    const code = dockerReady
+      ? 0
+      : await execute(probe, { stdin, stdout: null, stderr: null });
     if (code !== 0) dockerMissing = true;
     checks.push({ name: probe.name, ok: code === 0, detail: code === 0 ? "available" : "missing" });
   }
@@ -462,7 +529,29 @@ export async function readSecret(stdin, stdout, prompt, { mask = true } = {}) {
 
 export function executeCommand(spec, { stdin, stdout, stderr, input } = {}) {
   return new Promise((resolve, reject) => {
-    const child = spawn(spec.command, spec.args, {
+    if (!spec || typeof spec !== "object" || !trustedCommands.has(spec.command)) {
+      reject(new Error("SpaceApp refused to execute an untrusted command."));
+      return;
+    }
+    if (spec.command === "powershell.exe" && (
+      spec.args !== undefined ||
+      typeof spec.operation !== "string"
+    )) {
+      reject(new Error("SpaceApp PowerShell commands must use a trusted operation."));
+      return;
+    }
+    if (spec.command !== "powershell.exe" && (
+      !Array.isArray(spec.args) ||
+      spec.args.some((argument) => typeof argument !== "string")
+    )) {
+      reject(new Error("SpaceApp command arguments must be strings."));
+      return;
+    }
+    const commandEnv = spec.env === undefined
+      ? process.env
+      : validateCommandEnvironment(spec.env);
+    const child = spawnTrustedCommand(spec, {
+      env: commandEnv,
       shell: false,
       stdio: [input === undefined ? (stdin || "inherit") : "pipe", stdout || "ignore", stderr || "ignore"]
     });
@@ -482,12 +571,46 @@ export function executeCommand(spec, { stdin, stdout, stderr, input } = {}) {
   });
 }
 
+function spawnTrustedCommand(spec, options) {
+  const args = spec.args;
+  switch (spec.command) {
+    case "codesign": return spawn("codesign", args, options);
+    case "docker": return spawn("docker", args, options);
+    case "explorer.exe": return spawn("explorer.exe", args, options);
+    case "hdiutil": return spawn("hdiutil", args, options);
+    case "open": return spawn("open", args, options);
+    case "powershell.exe":
+      return spawn("powershell.exe", windowsPowerShellArgs(spec.operation), options);
+    case "sg": return spawn("sg", args, options);
+    case "spctl": return spawn("spctl", args, options);
+    case "sudo": return spawn("sudo", args, options);
+    case "winget.exe": return spawn("winget.exe", args, options);
+    case "wsl.exe": return spawn("wsl.exe", args, options);
+    case "xdg-open": return spawn("xdg-open", args, options);
+    default: throw new Error("SpaceApp refused to execute an untrusted command.");
+  }
+}
+
+function validateCommandEnvironment(commandEnvironment) {
+  if (
+    !commandEnvironment ||
+    typeof commandEnvironment !== "object" ||
+    Array.isArray(commandEnvironment) ||
+    Object.entries(commandEnvironment).some(
+      ([name, value]) => !trustedEnvironmentNames.has(name) || typeof value !== "string"
+    )
+  ) {
+    throw new Error("SpaceApp refused untrusted command environment values.");
+  }
+  return { ...process.env, ...commandEnvironment };
+}
+
 function openBrowser(url, platform, execute, io) {
   if (platform === "darwin") {
     return execute({ command: "open", args: [url] }, io);
   }
   if (platform === "win32") {
-    return execute({ command: "cmd", args: ["/d", "/s", "/c", "start", "", url] }, io);
+    return execute({ command: "explorer.exe", args: [url] }, io);
   }
   return execute({ command: "xdg-open", args: [url] }, io);
 }
@@ -500,12 +623,12 @@ function assertNoArgs(args, command) {
 
 function dockerInstallHelp(platform) {
   if (platform === "win32") {
-    return "Install Docker Desktop with its WSL2 backend, start it, then run spaceapp install again: https://docs.docker.com/desktop/setup/install/windows-install/";
+    return 'Run "spaceapp install" to install and start signed Docker Desktop with WSL2 automatically.';
   }
   if (platform === "darwin") {
-    return "Install and start Docker Desktop for macOS, then run spaceapp install again: https://docs.docker.com/desktop/setup/install/mac-install/";
+    return 'Run "spaceapp install" to install and start signed Docker Desktop automatically.';
   }
-  return "Install Docker Engine and the Docker Compose plugin, then run spaceapp install again: https://docs.docker.com/engine/install/";
+  return 'Run "spaceapp install" to install and start Docker Engine and Compose automatically on supported Linux distributions.';
 }
 
 function formatGigabytes(bytes) {
@@ -524,10 +647,10 @@ Usage: spaceapp <command>
 
   init                              Create a local SpaceApp installation
   install [--profile auto|light|standard] [--no-open]
-                                    Initialize, check, download, start, and open
+                                    Install prerequisites, initialize, and start
   up | down | status | logs         Manage the Docker application
   open                              Open the local web application
-  doctor                            Check Node, Docker, and Compose
+  doctor                            Check resources, Docker, Compose, and engine
   update [version] | rollback       Update or roll back images
   backup | restore                  Back up or restore persistent state
   workspace add <path> [--read-only]

package/src/prerequisites.mjs

@@ -0,0 +1,815 @@
+import { createWriteStream } from "node:fs";
+import { access, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { delimiter, join, posix, win32 } from "node:path";
+import process from "node:process";
+import { createInterface } from "node:readline/promises";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const DOCKER_TERMS_URL = "https://www.docker.com/legal/docker-subscription-service-agreement/";
+const DOWNLOAD_TIMEOUT_MS = 30 * 60 * 1_000;
+const WINDOWS_DOCKER_DOWNLOADS = Object.freeze({
+  x64: "https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe",
+  arm64: "https://desktop.docker.com/win/main/arm64/Docker%20Desktop%20Installer.exe"
+});
+const MAC_DOCKER_DOWNLOADS = Object.freeze({
+  x64: "https://desktop.docker.com/mac/main/amd64/Docker.dmg",
+  arm64: "https://desktop.docker.com/mac/main/arm64/Docker.dmg"
+});
+// Sources:
+// https://learn.microsoft.com/windows/package-manager/winget/install
+// https://github.com/microsoft/winget-pkgs/tree/master/manifests/d/Docker/DockerDesktop
+const WINDOWS_DOCKER_WINGET_ARGS = Object.freeze([
+  "install",
+  "--id", "Docker.DockerDesktop",
+  "--exact",
+  "--source", "winget",
+  "--silent",
+  "--accept-package-agreements",
+  "--accept-source-agreements",
+  "--disable-interactivity"
+]);
+
+export function windowsPowerShellArgs(operation) {
+  const scripts = {
+    "install-wsl": [
+      "$ErrorActionPreference = 'Stop'; try {",
+      "$process = Start-Process -FilePath 'wsl.exe'",
+      "-ArgumentList @('--install','--no-distribution')",
+      "-Verb RunAs -Wait -PassThru",
+      "; exit $process.ExitCode",
+      "} catch { exit 1 }"
+    ].join(" "),
+    "verify-docker-installer": [
+      "$path = $env:SPACEAPP_DOCKER_INSTALLER_PATH",
+      "if ([string]::IsNullOrWhiteSpace($path)) { exit 1 }",
+      "$signature = Get-AuthenticodeSignature -LiteralPath $path",
+      "if ($signature.Status -ne 'Valid' -or $signature.SignerCertificate.Subject -notmatch 'Docker') { exit 1 }"
+    ].join("; "),
+    "install-docker-desktop": [
+      "$path = $env:SPACEAPP_DOCKER_INSTALLER_PATH",
+      "if ([string]::IsNullOrWhiteSpace($path)) { exit 1 }",
+      "$process = Start-Process -FilePath $path -ArgumentList @('install','--user','--quiet','--accept-license') -Wait -PassThru",
+      "exit $process.ExitCode"
+    ].join("; "),
+    "start-docker-desktop": [
+      "$path = $env:SPACEAPP_DOCKER_DESKTOP_PATH",
+      "if ([string]::IsNullOrWhiteSpace($path)) { exit 1 }",
+      "Start-Process -FilePath $path"
+    ].join("; ")
+  };
+  if (!Object.hasOwn(scripts, operation)) {
+    throw new Error("SpaceApp refused an untrusted PowerShell operation.");
+  }
+  return ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", scripts[operation]];
+}
+
+export async function ensureDockerAvailable({
+  platform = process.platform,
+  arch = process.arch,
+  env = process.env,
+  stdin = process.stdin,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  execute,
+  launch = launchDetachedCommand,
+  download = downloadFile,
+  pathExists = fileExists,
+  sleep = wait,
+  osRelease,
+  installArgs
+}) {
+  if (await dockerIsReady(execute)) {
+    return { code: 0, reexecuted: false };
+  }
+  if (platform === "win32") {
+    return ensureWindowsDocker({
+      arch,
+      env,
+      stdin,
+      stdout,
+      stderr,
+      execute,
+      launch,
+      download,
+      pathExists,
+      sleep
+    });
+  }
+  if (platform === "darwin") {
+    return ensureMacDocker({
+      arch,
+      env,
+      stdin,
+      stdout,
+      stderr,
+      execute,
+      launch,
+      download,
+      pathExists,
+      sleep
+    });
+  }
+  return ensureLinuxDocker({
+    arch,
+    env,
+    stdin,
+    stdout,
+    stderr,
+    execute,
+    download,
+    sleep,
+    osRelease,
+    installArgs
+  });
+}
+
+async function ensureWindowsDocker({
+  arch,
+  env,
+  stdin,
+  stdout,
+  stderr,
+  execute,
+  launch,
+  download,
+  pathExists,
+  sleep
+}) {
+  const paths = windowsDockerPaths(env);
+  let application = await firstExisting(paths.applications, pathExists);
+
+  if (!application) {
+    stdout.write("Docker Desktop is required and is not installed.\n");
+    const accepted = await confirmDesktopInstall({ platformName: "Windows", stdin, stdout });
+    if (!accepted) {
+      stderr.write("Docker Desktop installation was cancelled.\n");
+      return { code: 1, reexecuted: false };
+    }
+  }
+
+  const wslCode = await execute(
+    { command: "wsl.exe", args: ["--version"] },
+    { stdin, stdout: null, stderr: null }
+  );
+  if (wslCode !== 0) {
+    stdout.write("Installing the Windows Subsystem for Linux 2 support required by Docker Desktop...\n");
+    const installWslCode = await execute(
+      {
+        command: "powershell.exe",
+        operation: "install-wsl"
+      },
+      { stdin, stdout, stderr }
+    );
+    if (installWslCode !== 0) {
+      stderr.write(
+        "Windows could not enable WSL2 automatically. Run this command from an Administrator terminal, restart Windows if requested, and run it again.\n"
+      );
+      return { code: installWslCode, reexecuted: false };
+    }
+    const installedWslCode = await execute(
+      { command: "wsl.exe", args: ["--version"] },
+      { stdin, stdout: null, stderr: null }
+    );
+    if (installedWslCode !== 0) {
+      stderr.write(
+        "Windows must restart to finish enabling WSL2. Restart Windows, then run the same SpaceApp command again.\n"
+      );
+      return { code: 1, reexecuted: false };
+    }
+  }
+
+  if (!application) {
+    const wingetCode = await execute(
+      { command: "winget.exe", args: ["--version"] },
+      { stdin, stdout: null, stderr: null }
+    );
+    if (wingetCode === 0) {
+      stdout.write(
+        "Installing Docker Desktop through Windows Package Manager with manifest hash verification...\n"
+      );
+      const installCode = await execute(
+        { command: "winget.exe", args: [...WINDOWS_DOCKER_WINGET_ARGS] },
+        { stdin, stdout, stderr }
+      );
+      if (installCode === 0) {
+        application = await firstExisting(paths.applications, pathExists);
+        if (!application) {
+          stderr.write(
+            "Windows Package Manager reported success, but Docker Desktop could not be found.\n"
+          );
+          return { code: 1, reexecuted: false };
+        }
+      } else {
+        stdout.write(
+          "Windows Package Manager could not install Docker Desktop; trying Docker's signed direct installer...\n"
+        );
+      }
+    }
+  }
+
+  if (!application) {
+    const downloadUrl = WINDOWS_DOCKER_DOWNLOADS[arch];
+    if (!downloadUrl) {
+      stderr.write(`Docker Desktop automatic installation does not support Windows architecture "${arch}".\n`);
+      return { code: 1, reexecuted: false };
+    }
+    const temporaryRoot = await mkdtemp(join(tmpdir(), "spaceapp-docker-"));
+    const installer = join(temporaryRoot, "Docker Desktop Installer.exe");
+    const installerEnv = {
+      SPACEAPP_DOCKER_INSTALLER_PATH: installer
+    };
+    try {
+      stdout.write("Downloading Docker Desktop from Docker's official distribution service...\n");
+      await download(downloadUrl, installer);
+      const signatureCode = await execute({
+        command: "powershell.exe",
+        operation: "verify-docker-installer",
+        env: installerEnv
+      }, { stdin, stdout: null, stderr });
+      if (signatureCode !== 0) {
+        stderr.write("The Docker Desktop installer signature is not valid. Installation was stopped.\n");
+        return { code: 1, reexecuted: false };
+      }
+      const installCode = await execute(
+        {
+          command: "powershell.exe",
+          operation: "install-docker-desktop",
+          env: installerEnv
+        },
+        { stdin, stdout, stderr }
+      );
+      if (installCode !== 0) {
+        stderr.write("Docker Desktop installation failed before SpaceApp downloaded any images.\n");
+        return { code: installCode, reexecuted: false };
+      }
+    } finally {
+      await rm(temporaryRoot, { recursive: true, force: true });
+    }
+    application = await firstExisting(paths.applications, pathExists);
+    if (!application) {
+      stderr.write("Docker Desktop reported success, but its application could not be found.\n");
+      return { code: 1, reexecuted: false };
+    }
+  } else {
+    stdout.write("Docker Desktop is installed but is not running. Starting it now...\n");
+  }
+
+  const cliDirectory = await firstExisting(paths.cliDirectories, pathExists);
+  if (cliDirectory) {
+    prependPath(env, cliDirectory);
+  }
+  const launchCode = await launch({
+    operation: "start-docker-desktop",
+    env: {
+      SPACEAPP_DOCKER_DESKTOP_PATH: application
+    }
+  });
+  if (launchCode !== 0) {
+    stderr.write("Docker Desktop is installed, but SpaceApp could not start it.\n");
+    return { code: launchCode, reexecuted: false };
+  }
+  if (await waitForDocker({ execute, sleep })) {
+    stdout.write("Docker Desktop is ready.\n");
+    return { code: 0, reexecuted: false };
+  }
+  stderr.write(
+    "Docker Desktop was installed but did not become ready. Complete any Docker Desktop prompt or restart Windows if requested, then run the same SpaceApp command again.\n"
+  );
+  return { code: 1, reexecuted: false };
+}
+
+async function ensureMacDocker({
+  arch,
+  env,
+  stdin,
+  stdout,
+  stderr,
+  execute,
+  launch,
+  download,
+  pathExists,
+  sleep
+}) {
+  const application = "/Applications/Docker.app";
+  const cliDirectory = posix.join(application, "Contents", "Resources", "bin");
+  let installed = await pathExists(application);
+
+  if (!installed) {
+    stdout.write("Docker Desktop is required and is not installed.\n");
+    const accepted = await confirmDesktopInstall({ platformName: "macOS", stdin, stdout });
+    if (!accepted) {
+      stderr.write("Docker Desktop installation was cancelled.\n");
+      return { code: 1, reexecuted: false };
+    }
+    const downloadUrl = MAC_DOCKER_DOWNLOADS[arch];
+    if (!downloadUrl) {
+      stderr.write(`Docker Desktop automatic installation does not support macOS architecture "${arch}".\n`);
+      return { code: 1, reexecuted: false };
+    }
+    const username = String(env.USER || "");
+    if (!/^[A-Za-z0-9._-]+$/.test(username)) {
+      stderr.write("A valid macOS username is required for Docker Desktop installation.\n");
+      return { code: 1, reexecuted: false };
+    }
+
+    const temporaryRoot = await mkdtemp(join(tmpdir(), "spaceapp-docker-"));
+    const diskImage = join(temporaryRoot, "Docker.dmg");
+    const mountedApplication = "/Volumes/Docker/Docker.app";
+    const installer = posix.join(mountedApplication, "Contents", "MacOS", "install");
+    let mounted = false;
+    try {
+      stdout.write("Downloading Docker Desktop from Docker's official distribution service...\n");
+      await download(downloadUrl, diskImage);
+      const attachCode = await execute(
+        { command: "hdiutil", args: ["attach", "-nobrowse", diskImage] },
+        { stdin, stdout, stderr }
+      );
+      if (attachCode !== 0) {
+        return { code: attachCode, reexecuted: false };
+      }
+      mounted = true;
+      const signatureCode = await execute({
+        command: "codesign",
+        args: ["--verify", "--deep", "--strict", "--verbose=2", mountedApplication]
+      }, { stdin, stdout: null, stderr });
+      if (signatureCode !== 0) {
+        stderr.write("The Docker Desktop application signature is not valid. Installation was stopped.\n");
+        return { code: 1, reexecuted: false };
+      }
+      const gatekeeperCode = await execute({
+        command: "spctl",
+        args: ["--assess", "--type", "execute", "--verbose=4", mountedApplication]
+      }, { stdin, stdout: null, stderr });
+      if (gatekeeperCode !== 0) {
+        stderr.write("macOS Gatekeeper did not accept Docker Desktop. Installation was stopped.\n");
+        return { code: 1, reexecuted: false };
+      }
+      const installCode = await execute({
+        command: "sudo",
+        args: [installer, "--accept-license", `--user=${username}`]
+      }, { stdin, stdout, stderr });
+      if (installCode !== 0) {
+        stderr.write("Docker Desktop installation failed before SpaceApp downloaded any images.\n");
+        return { code: installCode, reexecuted: false };
+      }
+    } finally {
+      if (mounted) {
+        await execute(
+          { command: "hdiutil", args: ["detach", "/Volumes/Docker"] },
+          { stdin, stdout: null, stderr: null }
+        );
+      }
+      await rm(temporaryRoot, { recursive: true, force: true });
+    }
+    installed = await pathExists(application);
+    if (!installed) {
+      stderr.write("Docker Desktop reported success, but /Applications/Docker.app could not be found.\n");
+      return { code: 1, reexecuted: false };
+    }
+  } else {
+    stdout.write("Docker Desktop is installed but is not running. Starting it now...\n");
+  }
+
+  if (await pathExists(cliDirectory)) {
+    prependPath(env, cliDirectory);
+  }
+  const launchCode = await launch({ operation: "open-docker-desktop" });
+  if (launchCode !== 0) {
+    stderr.write("Docker Desktop is installed, but SpaceApp could not start it.\n");
+    return { code: launchCode, reexecuted: false };
+  }
+  if (await waitForDocker({ execute, sleep })) {
+    stdout.write("Docker Desktop is ready.\n");
+    return { code: 0, reexecuted: false };
+  }
+  stderr.write(
+    "Docker Desktop was installed but did not become ready. Complete any Docker Desktop prompt, then run the same SpaceApp command again.\n"
+  );
+  return { code: 1, reexecuted: false };
+}
+
+async function ensureLinuxDocker({
+  arch,
+  env,
+  stdin,
+  stdout,
+  stderr,
+  execute,
+  download,
+  osRelease,
+  installArgs
+}) {
+  const cliAvailable = await dockerCliAndComposeAreAvailable(execute);
+  if (!cliAvailable) {
+    const release = osRelease ?? await readLinuxOsRelease();
+    stdout.write(`Docker Engine is required and is not installed. Installing it for ${release.ID}...\n`);
+    const installCode = await installLinuxDockerEngine({
+      arch,
+      release,
+      stdin,
+      stdout,
+      stderr,
+      execute,
+      download
+    });
+    if (installCode !== 0) {
+      return { code: installCode, reexecuted: false };
+    }
+  } else {
+    stdout.write("Docker Engine is installed but is not ready. Starting it now...\n");
+  }
+
+  const startCode = await execute(
+    { command: "sudo", args: ["systemctl", "enable", "--now", "docker"] },
+    { stdin, stdout, stderr }
+  );
+  if (startCode !== 0) {
+    stderr.write("Docker Engine was installed, but its system service could not be started.\n");
+    return { code: startCode, reexecuted: false };
+  }
+  if (await dockerIsReady(execute)) {
+    stdout.write("Docker Engine is ready.\n");
+    return { code: 0, reexecuted: false };
+  }
+  if (env.SPACEAPP_PREREQUISITES_BOOTSTRAPPED === "1") {
+    stderr.write("Docker Engine is running, but the current user still cannot access it.\n");
+    return { code: 1, reexecuted: false };
+  }
+
+  const username = String(env.SUDO_USER || env.USER || "");
+  if (!/^[A-Za-z0-9._-]+$/.test(username) || username === "root") {
+    stderr.write("A valid non-root Linux username is required for Docker Engine access.\n");
+    return { code: 1, reexecuted: false };
+  }
+  const accepted = await confirmQuestion({
+    stdin,
+    stdout,
+    question: [
+      "Docker's official post-install flow uses the docker group.",
+      "Membership grants root-level privileges on this host.",
+      `Add ${username} to the docker group and continue? [y/N] `
+    ].join("\n")
+  });
+  if (!accepted) {
+    stderr.write("Docker group membership was not changed.\n");
+    return { code: 1, reexecuted: false };
+  }
+  const groupCode = await execute(
+    { command: "sudo", args: ["usermod", "-aG", "docker", username] },
+    { stdin, stdout, stderr }
+  );
+  if (groupCode !== 0) {
+    return { code: groupCode, reexecuted: false };
+  }
+
+  const reentryCommand = linuxReentryCommand(installArgs);
+  stdout.write("Docker Engine is ready. Continuing SpaceApp installation with the new group membership...\n");
+  const reentryCode = await execute(
+    { command: "sg", args: ["docker", "-c", reentryCommand] },
+    { stdin, stdout, stderr }
+  );
+  return { code: reentryCode, reexecuted: true };
+}
+
+async function confirmDesktopInstall({ platformName, stdin, stdout }) {
+  return confirmQuestion({
+    stdin,
+    stdout,
+    question:
+      `Review the Docker Desktop terms at ${DOCKER_TERMS_URL}\n` +
+      `Install Docker Desktop for ${platformName} and accept those terms? [y/N] `
+  });
+}
+
+async function confirmQuestion({ stdin, stdout, question }) {
+  const readline = createInterface({ input: stdin, output: stdout, terminal: Boolean(stdin.isTTY) });
+  try {
+    const answer = await readline.question(question);
+    return /^(?:y|yes)$/i.test(answer.trim());
+  } catch {
+    return false;
+  } finally {
+    readline.close();
+  }
+}
+
+async function dockerCliAndComposeAreAvailable(execute) {
+  for (const spec of [
+    { command: "docker", args: ["--version"] },
+    { command: "docker", args: ["compose", "version"] }
+  ]) {
+    if (await execute(spec, { stdout: null, stderr: null }) !== 0) {
+      return false;
+    }
+  }
+  return true;
+}
+
+async function dockerIsReady(execute) {
+  for (const spec of [
+    { command: "docker", args: ["--version"] },
+    { command: "docker", args: ["compose", "version"] },
+    { command: "docker", args: ["info"] }
+  ]) {
+    if (await execute(spec, { stdout: null, stderr: null }) !== 0) {
+      return false;
+    }
+  }
+  return true;
+}
+
+async function installLinuxDockerEngine({
+  arch,
+  release,
+  stdin,
+  stdout,
+  stderr,
+  execute,
+  download
+}) {
+  const id = String(release?.ID || "").toLowerCase();
+  if (id === "ubuntu" || id === "debian") {
+    return installAptDockerEngine({
+      arch,
+      id,
+      codename: release.VERSION_CODENAME || release.UBUNTU_CODENAME,
+      stdin,
+      stdout,
+      stderr,
+      execute,
+      download
+    });
+  }
+  if (id === "fedora" || id === "rhel" || id === "centos") {
+    return installDnfDockerEngine({ id, stdin, stdout, stderr, execute });
+  }
+  stderr.write(
+    `Automatic Docker Engine installation is not yet supported for Linux distribution "${id || "unknown"}". ` +
+    "Install Docker Engine and the Compose plugin from https://docs.docker.com/engine/install/ and rerun the same command.\n"
+  );
+  return 1;
+}
+
+async function installAptDockerEngine({
+  arch,
+  id,
+  codename,
+  stdin,
+  stdout,
+  stderr,
+  execute,
+  download
+}) {
+  const dockerArch = { x64: "amd64", arm64: "arm64" }[arch];
+  if (!dockerArch || !/^[a-z0-9._-]+$/.test(String(codename || ""))) {
+    stderr.write("This Debian/Ubuntu architecture or release codename is not supported automatically.\n");
+    return 1;
+  }
+  const temporaryRoot = await mkdtemp(join(tmpdir(), "spaceapp-docker-"));
+  const signingKey = join(temporaryRoot, "docker.asc");
+  const repositoryFile = join(temporaryRoot, "docker.list");
+  const repositoryBase = `https://download.docker.com/linux/${id}`;
+  try {
+    await download(`${repositoryBase}/gpg`, signingKey);
+    await writeFile(
+      repositoryFile,
+      `deb [arch=${dockerArch} signed-by=/etc/apt/keyrings/docker.asc] ${repositoryBase} ${codename} stable\n`,
+      { mode: 0o600, flag: "wx" }
+    );
+    for (const spec of [
+      { command: "sudo", args: ["install", "-m", "0755", "-d", "/etc/apt/keyrings"] },
+      { command: "sudo", args: ["install", "-m", "0644", signingKey, "/etc/apt/keyrings/docker.asc"] },
+      {
+        command: "sudo",
+        args: ["install", "-m", "0644", repositoryFile, "/etc/apt/sources.list.d/docker.list"]
+      },
+      { command: "sudo", args: ["apt-get", "update"] },
+      {
+        command: "sudo",
+        args: [
+          "apt-get",
+          "install",
+          "-y",
+          "docker-ce",
+          "docker-ce-cli",
+          "containerd.io",
+          "docker-buildx-plugin",
+          "docker-compose-plugin"
+        ]
+      }
+    ]) {
+      const code = await execute(spec, { stdin, stdout, stderr });
+      if (code !== 0) {
+        return code;
+      }
+    }
+    return 0;
+  } finally {
+    await rm(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
+async function installDnfDockerEngine({ id, stdin, stdout, stderr, execute }) {
+  const repositoryUrl = `https://download.docker.com/linux/${id}/docker-ce.repo`;
+  const repositoryArgs = id === "fedora"
+    ? ["dnf", "config-manager", "addrepo", "--from-repofile", repositoryUrl]
+    : ["dnf", "config-manager", "--add-repo", repositoryUrl];
+  const pluginCode = await execute(
+    { command: "sudo", args: ["dnf", "-y", "install", "dnf-plugins-core"] },
+    { stdin, stdout, stderr }
+  );
+  if (pluginCode !== 0) {
+    return pluginCode;
+  }
+
+  let repositoryCode = await execute(
+    { command: "sudo", args: repositoryArgs },
+    { stdin, stdout, stderr }
+  );
+  if (repositoryCode !== 0 && id === "fedora") {
+    stdout.write("The DNF5 repository command was unavailable; retrying with DNF4 syntax...\n");
+    repositoryCode = await execute(
+      {
+        command: "sudo",
+        args: ["dnf", "config-manager", "--add-repo", repositoryUrl]
+      },
+      { stdin, stdout, stderr }
+    );
+  }
+  if (repositoryCode !== 0) {
+    return repositoryCode;
+  }
+
+  return execute(
+    {
+      command: "sudo",
+      args: [
+        "dnf",
+        "-y",
+        "install",
+        "docker-ce",
+        "docker-ce-cli",
+        "containerd.io",
+        "docker-buildx-plugin",
+        "docker-compose-plugin"
+      ]
+    },
+    { stdin, stdout, stderr }
+  );
+}
+
+async function readLinuxOsRelease() {
+  const content = await readFile("/etc/os-release", "utf8");
+  const values = {};
+  for (const line of content.split(/\r?\n/)) {
+    const match = /^([A-Z_]+)=(.*)$/.exec(line);
+    if (!match) continue;
+    const raw = match[2].trim();
+    values[match[1]] = raw.replace(/^(['"])(.*)\1$/, "$2");
+  }
+  return values;
+}
+
+function linuxReentryCommand({ requestedProfile = "auto", noOpen = false } = {}) {
+  if (!["auto", "light", "standard"].includes(requestedProfile)) {
+    throw new Error("Invalid SpaceApp profile for Docker group re-entry.");
+  }
+  const entrypoint = fileURLToPath(new URL("../bin/spaceapp.mjs", import.meta.url));
+  return [
+    "/usr/bin/env",
+    "SPACEAPP_PREREQUISITES_BOOTSTRAPPED=1",
+    process.execPath,
+    entrypoint,
+    "install",
+    "--profile",
+    requestedProfile,
+    ...(noOpen ? ["--no-open"] : [])
+  ].map(shellQuote).join(" ");
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+async function waitForDocker({ execute, sleep }) {
+  for (let attempt = 0; attempt < 90; attempt += 1) {
+    if (await dockerIsReady(execute)) {
+      return true;
+    }
+    await sleep(2_000);
+  }
+  return false;
+}
+
+function windowsDockerPaths(env) {
+  const localAppData = env.LOCALAPPDATA;
+  const programFiles = env.ProgramFiles || env.PROGRAMFILES;
+  return {
+    applications: [
+      localAppData && win32.join(localAppData, "Programs", "DockerDesktop", "Docker Desktop.exe"),
+      programFiles && win32.join(programFiles, "Docker", "Docker", "Docker Desktop.exe")
+    ].filter(Boolean),
+    cliDirectories: [
+      localAppData && win32.join(localAppData, "Programs", "DockerDesktop", "resources", "bin"),
+      programFiles && win32.join(programFiles, "Docker", "Docker", "resources", "bin")
+    ].filter(Boolean)
+  };
+}
+
+async function firstExisting(paths, pathExists) {
+  for (const path of paths) {
+    if (await pathExists(path)) {
+      return path;
+    }
+  }
+  return null;
+}
+
+function prependPath(env, directory) {
+  const pathKey = Object.keys(env).find((key) => key.toLowerCase() === "path") || "PATH";
+  const entries = String(env[pathKey] || "").split(delimiter).filter(Boolean);
+  if (!entries.includes(directory)) {
+    env[pathKey] = [directory, ...entries].join(delimiter);
+  }
+}
+
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function downloadFile(url, target, {
+  timeoutMs = DOWNLOAD_TIMEOUT_MS
+} = {}) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("Docker download timeout must be a positive number.");
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, {
+      redirect: "follow",
+      signal: controller.signal
+    });
+    if (!response.ok || !response.body) {
+      throw new Error(`Docker download failed with HTTP ${response.status}.`);
+    }
+    await pipeline(
+      Readable.fromWeb(response.body),
+      createWriteStream(target, { flags: "wx", mode: 0o600 }),
+      { signal: controller.signal }
+    );
+  } catch (error) {
+    if (controller.signal.aborted) {
+      throw new Error(
+        `Docker download timed out after ${Math.ceil(timeoutMs / 1_000)} seconds.`,
+        { cause: error }
+      );
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function launchDetachedCommand(spec) {
+  return new Promise((resolve) => {
+    const options = {
+      detached: true,
+      env: spec.env ? { ...process.env, ...spec.env } : process.env,
+      shell: false,
+      stdio: "ignore"
+    };
+    let child;
+    try {
+      if (spec.operation === "start-docker-desktop") {
+        child = spawn("powershell.exe", windowsPowerShellArgs(spec.operation), options);
+      } else if (spec.operation === "open-docker-desktop") {
+        child = spawn("open", ["-a", "Docker"], options);
+      } else {
+        resolve(1);
+        return;
+      }
+    } catch {
+      resolve(1);
+      return;
+    }
+    child.once("error", () => resolve(1));
+    child.once("spawn", () => {
+      child.unref();
+      resolve(0);
+    });
+  });
+}
+
+function wait(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/templates/compose.yml

@@ -3,6 +3,8 @@ services:
     image: ghcr.io/oll4com/spaceapp-core:${SPACEAPP_IMAGE_TAG}
     restart: unless-stopped
     init: true
+    security_opt:
+      - no-new-privileges:true
     mem_limit: "${SPACEAPP_CORE_MEMORY_LIMIT}"
     cpus: "${SPACEAPP_CORE_CPU_LIMIT}"
     environment:
@@ -70,6 +72,8 @@ services:
     image: ghcr.io/oll4com/spaceapp-cli:${SPACEAPP_IMAGE_TAG}
     restart: unless-stopped
     init: true
+    security_opt:
+      - no-new-privileges:true
     mem_limit: "${SPACEAPP_CLI_MEMORY_LIMIT}"
     cpus: "${SPACEAPP_CLI_CPU_LIMIT}"
     environment:
@@ -90,6 +94,8 @@ services:
     profiles: ["standard"]
     restart: unless-stopped
     init: true
+    security_opt:
+      - no-new-privileges:true
     mem_limit: "${SPACEAPP_BROWSER_MEMORY_LIMIT}"
     cpus: "${SPACEAPP_BROWSER_CPU_LIMIT}"
     environment: