run-spaceapp 0.1.11 → 0.1.13

package/README.md

@@ -5,7 +5,7 @@ Cross-platform Docker launcher for SpaceApp.
 Run the same command in Linux, macOS, or Windows 11 Command Prompt:
 
 ```bash
-npx --yes run-spaceapp install
+npx --yes run-spaceapp@latest install
 ```
 
 To keep a global `spaceapp` command for later operations, install it
@@ -16,10 +16,12 @@ npm install -g run-spaceapp
 ```
 
 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
+disk. Keep `@latest` in the command so npm resolves the current release instead
+of matching an existing local launcher. If Docker is missing, the universal
+install command 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
@@ -33,9 +35,9 @@ resume and asks before scheduling it. Sign back in after Windows restarts; the
 same install continues automatically in Command Prompt without entering a
 second command.
 
-The launcher defaults to the `light` profile on every system. Select
-`--profile standard` explicitly when managed Chromium is required and the host
-has the recommended resources.
+The launcher defaults to the `light` profile on every system. Run
+`npx --yes run-spaceapp@latest install --profile standard` explicitly when
+managed Chromium is required and the host has the recommended resources.
 
 Light mode retains every bundled CLI and the core data/workflow services while
 omitting managed Chromium. Resource limits are maximums, not immediate RAM or
@@ -57,24 +59,34 @@ Claude Code is not redistributed in SpaceApp images. Install the reviewed
 package as an explicit owner action with:
 
 ```bash
-spaceapp provider install claude
+npx --yes run-spaceapp@latest provider install claude
 ```
 
-Run `spaceapp help` for the complete command list. Full documentation:
+Run `npx --yes run-spaceapp@latest help` for the complete command list. Full
+documentation:
 
 - [Getting started](https://github.com/oll4com/spaceapp/blob/main/docs/getting-started.md)
 - [CLI providers](https://github.com/oll4com/spaceapp/blob/main/docs/cli-providers.md)
 - [Operations](https://github.com/oll4com/spaceapp/blob/main/docs/operations.md)
 - [Security model](https://github.com/oll4com/spaceapp/blob/main/docs/security-model.md)
 
-After the stack passes readiness checks, `spaceapp install` prints the fresh
+After the stack passes readiness checks, the install command prints the fresh
 15-minute token to paste into the browser's **One-time setup token** field. If
 it expires before the owner is created, run:
 
 ```bash
-spaceapp owner rotate-setup-token
+npx --yes run-spaceapp@latest owner rotate-setup-token
 ```
 
-`spaceapp uninstall` removes the runtime while retaining data by default and
-prints the separate `npm uninstall -g run-spaceapp` command for removing the
-global launcher.
+Common follow-up commands use the same reliable launcher prefix:
+
+```bash
+npx --yes run-spaceapp@latest doctor
+npx --yes run-spaceapp@latest status
+npx --yes run-spaceapp@latest credentials list
+npx --yes run-spaceapp@latest uninstall
+```
+
+Uninstall retains data by default and prints the separate
+`npm uninstall -g run-spaceapp` command for removing an optional global
+launcher.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run-spaceapp",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Cross-platform Docker launcher for the SpaceApp self-hosted agent workspace",
   "license": "Apache-2.0",
   "type": "module",
@@ -46,5 +46,5 @@
     "access": "public",
     "provenance": true
   },
-  "gitHead": "c53e6dd08441f3a517f21f7b0ca6f82ec36a1761"
+  "gitHead": "14a0f1117141c24c3436768c23e819f482eaed70"
 }

package/src/cli.mjs

@@ -1,9 +1,12 @@
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import process from "node:process";
 import {
   addWorkspace,
+  commitInstallation,
   composeCommand,
   credentialProviders,
   initializeInstallation,
@@ -12,6 +15,7 @@ import {
   loadConfig,
   removeCredential,
   removeWorkspace,
+  prepareInstallation,
   resolveInstallProfile,
   resolveSpaceAppHome,
   saveConfig,
@@ -30,10 +34,10 @@ const APPLICATION_READY_WAIT_MS = 3 * 60 * 1_000;
 const APPLICATION_READY_POLL_MS = 2_000;
 const APPLICATION_READY_MAX_ATTEMPTS = APPLICATION_READY_WAIT_MS / APPLICATION_READY_POLL_MS;
 const SETUP_STATUS_TIMEOUT_MS = 10_000;
+const UNIVERSAL_COMMAND = "npx --yes run-spaceapp@latest";
 const trustedCommands = new Set([
   "codesign",
   "docker",
-  "explorer.exe",
   "hdiutil",
   "open",
   "powershell.exe",
@@ -47,6 +51,7 @@ const trustedCommands = new Set([
 ]);
 const trustedEnvironmentNames = new Set([
   "SPACEAPP_DOCKER_INSTALLER_PATH",
+  "SPACEAPP_OPEN_URL",
   "SPACEAPP_RESUME_SCRIPT_PATH"
 ]);
 
@@ -104,7 +109,9 @@ export async function run(argv, {
       stdout.write(`One-time setup token: ${result.setupToken}\n`);
       stdout.write("Store it temporarily; it expires after first owner setup.\n");
     }
-    stdout.write("Next: spaceapp doctor && spaceapp up && spaceapp open\n");
+    stdout.write(
+      `Next: ${UNIVERSAL_COMMAND} doctor && ${UNIVERSAL_COMMAND} up && ${UNIVERSAL_COMMAND} open\n`
+    );
     return 0;
   }
 
@@ -243,10 +250,10 @@ export async function run(argv, {
       }
       return code;
     }
-    throw new Error("Usage: spaceapp uninstall [--purge-data]");
+    throw new Error(`Usage: ${UNIVERSAL_COMMAND} uninstall [--purge-data]`);
   }
 
-  throw new Error(`Unknown command "${command}". Run "spaceapp help".`);
+  throw new Error(`Unknown command "${command}". Run "${UNIVERSAL_COMMAND} help".`);
 }
 
 async function installCommand(args, {
@@ -268,8 +275,19 @@ async function installCommand(args, {
   const { requestedProfile, noOpen } = parseInstallArgs(args);
   const resources = await inspectResources(root);
   const profile = resolveInstallProfile(requestedProfile, resources.totalMemoryBytes);
-  const result = await initializeInstallation(root, { version, profile });
+  const existingConfig = await loadExistingInstallation(root);
+  const result = await prepareInstallation(root, { version, profile });
 
+  stdout.write(`Launcher version: ${version}\n`);
+  stdout.write(
+    `SpaceApp version: ${existingConfig?.version ?? "not installed"} -> ${result.config.version}\n`
+  );
+  stdout.write(
+    `Profile: ${existingConfig?.profile ?? "not configured"} -> ${result.config.profile}\n`
+  );
+  stdout.write(existingConfig
+    ? "Preserved existing data, workspaces, credentials, secrets, and persistent Docker volumes.\n"
+    : "Future refreshes preserve data, workspaces, credentials, secrets, and persistent Docker volumes.\n");
   stdout.write(
     `Selected profile: ${profile} (${formatGigabytes(resources.totalMemoryBytes)} GB system memory detected).\n`
   );
@@ -285,7 +303,9 @@ async function installCommand(args, {
       inspectResources,
       resources
     });
-    stderr.write("Installation stopped before downloading images. Fix the failed checks and run the same command again.\n");
+    stderr.write(
+      `Installation stopped before downloading images. Fix the failed checks and run "${UNIVERSAL_COMMAND} install" again.\n`
+    );
     return doctorCode;
   }
 
@@ -301,7 +321,9 @@ async function installCommand(args, {
   });
   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");
+      stderr.write(
+        `Installation stopped before downloading images. Fix the failed checks and run "${UNIVERSAL_COMMAND} install" again.\n`
+      );
     }
     return prerequisiteResult.code;
   }
@@ -318,95 +340,108 @@ async function installCommand(args, {
     dockerReady: true
   });
   if (doctorCode !== 0) {
-    stderr.write("Installation stopped before downloading images. Fix the failed checks and run the same command again.\n");
-    return doctorCode;
-  }
-  const pullCode = await executeWithDockerDiagnostics(
-    execute,
-    composeCommand("pull", root, { profile }),
-    { stdin, stdout, stderr },
-    { platform, stderr }
-  );
-  if (pullCode !== 0) return pullCode;
-  const upCode = await executeWithDockerDiagnostics(
-    execute,
-    composeCommand("up", root, { profile }),
-    { stdin, stdout, stderr },
-    { platform, stderr }
-  );
-  if (upCode !== 0) return upCode;
-
-  const url = `http://${result.config.bindHost}:${result.config.port}`;
-  stdout.write("Waiting for SpaceApp services to become ready...\n");
-  const ready = await waitForApplicationReady({
-    url,
-    request,
-    sleep
-  });
-  if (!ready) {
     stderr.write(
-      "SpaceApp containers started, but the application did not become ready within 3 minutes.\n" +
-      'Run "spaceapp status" and "spaceapp logs", then run "spaceapp install" again.\n'
+      `Installation stopped before downloading images. Fix the failed checks and run "${UNIVERSAL_COMMAND} install" again.\n`
     );
-    return 1;
+    return doctorCode;
   }
-
-  let setupStatus;
+  const stagedStateRoot = await mkdtemp(join(tmpdir(), "run-spaceapp-install-"));
   try {
-    setupStatus = await requestSetupStatus({ url, request });
-  } catch (error) {
-    stderr.write(
-      `SpaceApp is ready, but owner setup status could not be verified: ${error?.message || String(error)}\n` +
-      'Run "spaceapp status" and "spaceapp logs", then run "spaceapp install" again.\n'
+    await commitInstallation(stagedStateRoot, result.config);
+    const stagedComposeCommand = (action) =>
+      composeCommand(action, root, { profile, stateRoot: stagedStateRoot });
+    const pullCode = await executeWithDockerDiagnostics(
+      execute,
+      stagedComposeCommand("pull"),
+      { stdin, stdout, stderr },
+      { platform, stderr }
     );
-    return 1;
-  }
-
-  let setupToken = null;
-  if (setupStatus.setupRequired) {
-    setupToken = randomBytes(32).toString("base64url");
-    const rotateCode = await executeWithDockerDiagnostics(
+    if (pullCode !== 0) return pullCode;
+    const upCode = await executeWithDockerDiagnostics(
       execute,
-      composeCommand("rotateOwnerSetupToken", root, { profile }),
-      {
-        stdin,
-        stdout,
-        stderr,
-        input: `${setupToken}\n`
-      },
+      stagedComposeCommand("up"),
+      { stdin, stdout, stderr },
       { platform, stderr }
     );
-    if (rotateCode !== 0) {
+    if (upCode !== 0) return upCode;
+
+    const url = `http://${result.config.bindHost}:${result.config.port}`;
+    stdout.write("Waiting for SpaceApp services to become ready...\n");
+    const ready = await waitForApplicationReady({
+      url,
+      request,
+      sleep
+    });
+    if (!ready) {
       stderr.write(
-        'SpaceApp is ready, but a fresh owner setup token could not be created. Run "spaceapp owner rotate-setup-token".\n'
+        "SpaceApp containers started, but the application did not become ready within 3 minutes.\n" +
+        `Run "${UNIVERSAL_COMMAND} status" and "${UNIVERSAL_COMMAND} logs", then run "${UNIVERSAL_COMMAND} install" again.\n`
       );
-      return rotateCode;
+      return 1;
     }
+
+    let setupStatus;
     try {
-      await persistSetupToken(root, setupToken);
-    } catch {
+      setupStatus = await requestSetupStatus({ url, request });
+    } catch (error) {
       stderr.write(
-        "SpaceApp accepted a new setup token, but it could not be saved locally.\n" +
-        'Run "spaceapp owner rotate-setup-token" to obtain a usable token.\n'
+        `SpaceApp is ready, but owner setup status could not be verified: ${error?.message || String(error)}\n` +
+        `Run "${UNIVERSAL_COMMAND} status" and "${UNIVERSAL_COMMAND} logs", then run "${UNIVERSAL_COMMAND} install" again.\n`
       );
       return 1;
     }
-  }
 
-  stdout.write(`SpaceApp is ready at ${url}\n`);
-  if (setupToken) {
-    stdout.write(`One-time setup token: ${setupToken}\n`);
-    stdout.write('Paste it into the "One-time setup token" field in the page that opens.\n');
-    stdout.write("It expires in 15 minutes and stops working after the first owner is created.\n");
-    stdout.write("If it expires, run: spaceapp owner rotate-setup-token\n");
-  }
-  stdout.write('Next: add CLI credentials with "spaceapp credentials set <provider>".\n');
-  if (noOpen) return 0;
-  const openCode = await openBrowser(url, platform, execute, { stdin, stdout, stderr });
-  if (openCode !== 0) {
-    stderr.write(`Could not open SpaceApp automatically. Open ${url} manually.\n`);
+    let setupToken = null;
+    if (setupStatus.setupRequired) {
+      setupToken = randomBytes(32).toString("base64url");
+      const rotateCode = await executeWithDockerDiagnostics(
+        execute,
+        stagedComposeCommand("rotateOwnerSetupToken"),
+        {
+          stdin,
+          stdout,
+          stderr,
+          input: `${setupToken}\n`
+        },
+        { platform, stderr }
+      );
+      if (rotateCode !== 0) {
+        stderr.write(
+          `SpaceApp is ready, but a fresh owner setup token could not be created. Run "${UNIVERSAL_COMMAND} owner rotate-setup-token".\n`
+        );
+        return rotateCode;
+      }
+      try {
+        await persistSetupToken(root, setupToken);
+      } catch {
+        stderr.write(
+          "SpaceApp accepted a new setup token, but it could not be saved locally.\n" +
+          `Run "${UNIVERSAL_COMMAND} owner rotate-setup-token" to obtain a usable token.\n`
+        );
+        return 1;
+      }
+    }
+
+    await commitInstallation(root, result.config);
+    stdout.write(`SpaceApp is ready at ${url}\n`);
+    if (setupToken) {
+      stdout.write(`One-time setup token: ${setupToken}\n`);
+      stdout.write('Paste it into the "One-time setup token" field in the page that opens.\n');
+      stdout.write("It expires in 15 minutes and stops working after the first owner is created.\n");
+      stdout.write(`If it expires, run: ${UNIVERSAL_COMMAND} owner rotate-setup-token\n`);
+    }
+    stdout.write(
+      `Next: add CLI credentials with "${UNIVERSAL_COMMAND} credentials set <provider>".\n`
+    );
+    if (noOpen) return 0;
+    const openCode = await openBrowser(url, platform, execute, { stdin, stdout, stderr });
+    if (openCode !== 0) {
+      stderr.write(`Could not open SpaceApp automatically. Open ${url} manually.\n`);
+    }
+    return 0;
+  } finally {
+    await rm(stagedStateRoot, { recursive: true, force: true });
   }
-  return 0;
 }
 
 function parseInstallArgs(args) {
@@ -427,19 +462,36 @@ function parseInstallArgs(args) {
       requestedProfile = argument.slice("--profile=".length);
       continue;
     }
-    throw new Error("Usage: spaceapp install [--profile auto|light|standard] [--no-open]");
+    throw new Error(
+      `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|light|standard] [--no-open]`
+    );
   }
   if (!["auto", "light", "standard"].includes(requestedProfile)) {
-    throw new Error("Usage: spaceapp install [--profile auto|light|standard] [--no-open]");
+    throw new Error(
+      `Usage: ${UNIVERSAL_COMMAND} install [--profile auto|light|standard] [--no-open]`
+    );
   }
   return { requestedProfile, noOpen };
 }
 
+async function loadExistingInstallation(root) {
+  try {
+    return await loadConfig(root);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
 async function workspaceCommand(args, { root, config, stdout }) {
   const [action, identity, ...rest] = args;
   if (action === "add") {
     if (!identity || rest.some((arg) => arg !== "--read-only")) {
-      throw new Error("Usage: spaceapp workspace add <absolute-path> [--read-only]");
+      throw new Error(
+        `Usage: ${UNIVERSAL_COMMAND} workspace add <absolute-path> [--read-only]`
+      );
     }
     const updated = await addWorkspace(config, identity, { readOnly: rest.includes("--read-only") });
     await saveConfig(root, updated);
@@ -449,7 +501,9 @@ async function workspaceCommand(args, { root, config, stdout }) {
   }
   if (action === "remove") {
     if (!identity || rest.length > 0) {
-      throw new Error("Usage: spaceapp workspace remove <id-or-absolute-path>");
+      throw new Error(
+        `Usage: ${UNIVERSAL_COMMAND} workspace remove <id-or-absolute-path>`
+      );
     }
     const updated = removeWorkspace(config, identity);
     await saveConfig(root, updated);
@@ -461,7 +515,7 @@ async function workspaceCommand(args, { root, config, stdout }) {
     stdout.write(`${JSON.stringify(config.workspaces, null, 2)}\n`);
     return 0;
   }
-  throw new Error("Usage: spaceapp workspace <add|remove|list>");
+  throw new Error(`Usage: ${UNIVERSAL_COMMAND} workspace <add|remove|list>`);
 }
 
 async function credentialsCommand(args, { root, config, stdin, stdout, stderr, execute }) {
@@ -472,7 +526,9 @@ async function credentialsCommand(args, { root, config, stdin, stdout, stderr, e
   }
   if (action === "set") {
     if (!provider || rest.length > 0) {
-      throw new Error("Usage: spaceapp credentials set <provider> (the value is read from stdin)");
+      throw new Error(
+        `Usage: ${UNIVERSAL_COMMAND} credentials set <provider> (the value is read from stdin)`
+      );
     }
     const value = await readSecret(stdin, stdout, `Enter ${provider} credential: `);
     await writeCredential(root, provider, value);
@@ -489,7 +545,7 @@ async function credentialsCommand(args, { root, config, stdin, stdout, stderr, e
   }
   if (action === "remove") {
     if (!provider || rest.length > 0) {
-      throw new Error("Usage: spaceapp credentials remove <provider>");
+      throw new Error(`Usage: ${UNIVERSAL_COMMAND} credentials remove <provider>`);
     }
     const removed = await removeCredential(root, provider);
     const syncCode = await execute(
@@ -503,12 +559,12 @@ async function credentialsCommand(args, { root, config, stdin, stdout, stderr, e
     stdout.write(removed ? `Credential removed and applied for ${provider}.\n` : `No credential stored for ${provider}.\n`);
     return syncCode;
   }
-  throw new Error("Usage: spaceapp credentials <set|remove|list>");
+  throw new Error(`Usage: ${UNIVERSAL_COMMAND} credentials <set|remove|list>`);
 }
 
 async function providerCommand(args, { root, config, stdin, stdout, stderr, execute }) {
   if (args.length !== 2 || args[0] !== "install" || args[1] !== "claude") {
-    throw new Error("Usage: spaceapp provider install claude");
+    throw new Error(`Usage: ${UNIVERSAL_COMMAND} provider install claude`);
   }
   stdout.write("Installing Claude Code from Anthropic into this installation's private provider volume.\n");
   return execute(composeCommand("installClaude", root, { profile: config.profile }), { stdin, stdout, stderr });
@@ -530,7 +586,9 @@ async function ownerCommand(args, { root, config, stdin, stdout, stderr, execute
     return 0;
   }
   if (args.length !== 1 || args[0] !== "reset-password") {
-    throw new Error("Usage: spaceapp owner <reset-password|rotate-setup-token>");
+    throw new Error(
+      `Usage: ${UNIVERSAL_COMMAND} owner <reset-password|rotate-setup-token>`
+    );
   }
   const password = await readSecret(stdin, stdout, "New owner password: ");
   if (password.length < 12) {
@@ -546,7 +604,7 @@ async function ownerCommand(args, { root, config, stdin, stdout, stderr, execute
 
 async function updateCommand(args, { root, config, version, stdin, stdout, stderr, execute }) {
   if (args.length > 1) {
-    throw new Error("Usage: spaceapp update [version]");
+    throw new Error(`Usage: ${UNIVERSAL_COMMAND} update [version]`);
   }
   const targetVersion = args[0] || version;
   const updated = {
@@ -812,7 +870,6 @@ function spawnTrustedCommand(spec, options) {
   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":
@@ -847,14 +904,18 @@ function openBrowser(url, platform, execute, io) {
     return execute({ command: "open", args: [url] }, io);
   }
   if (platform === "win32") {
-    return execute({ command: "explorer.exe", args: [url] }, io);
+    return execute({
+      command: "powershell.exe",
+      operation: "open-spaceapp-browser",
+      env: { SPACEAPP_OPEN_URL: url }
+    }, io);
   }
   return execute({ command: "xdg-open", args: [url] }, io);
 }
 
 function assertNoArgs(args, command) {
   if (args.length > 0) {
-    throw new Error(`Usage: spaceapp ${command}`);
+    throw new Error(`Usage: ${UNIVERSAL_COMMAND} ${command}`);
   }
 }
 
@@ -884,19 +945,19 @@ function commandNeedsRuntimeFiles(command, args) {
 
 function dockerInstallHelp(platform) {
   if (platform === "win32") {
-    return 'Run "spaceapp install" to install and start signed Docker Desktop with WSL2 automatically.';
+    return `Run "${UNIVERSAL_COMMAND} install" to install and start signed Docker Desktop with WSL2 automatically.`;
   }
   if (platform === "darwin") {
-    return 'Run "spaceapp install" to install and start signed Docker Desktop automatically.';
+    return `Run "${UNIVERSAL_COMMAND} install" to install and start signed Docker Desktop automatically.`;
   }
-  return 'Run "spaceapp install" to install and start Docker Engine and Compose automatically on supported Linux distributions.';
+  return `Run "${UNIVERSAL_COMMAND} install" to install and start Docker Engine and Compose automatically on supported Linux distributions.`;
 }
 
 function dockerEngineHelp(platform) {
   if (platform === "win32" || platform === "darwin") {
-    return 'Open Docker Desktop, complete any first-run prompt, then run "spaceapp doctor" again.';
+    return `Open Docker Desktop, complete any first-run prompt, then run "${UNIVERSAL_COMMAND} doctor" again.`;
   }
-  return 'Start Docker Engine, verify the current user can access it, then run "spaceapp doctor" again.';
+  return `Start Docker Engine, verify the current user can access it, then run "${UNIVERSAL_COMMAND} doctor" again.`;
 }
 
 function formatGigabytes(bytes) {
@@ -915,7 +976,8 @@ async function packageVersion() {
 function helpText() {
   return `SpaceApp self-hosted launcher
 
-Usage: spaceapp <command>
+Usage: ${UNIVERSAL_COMMAND} <command>
+       spaceapp <command>             Optional global launcher
 
   init                              Create a local SpaceApp installation
   install [--profile auto|light|standard] [--no-open]

package/src/index.mjs

@@ -1,7 +1,6 @@
 import { createHash, randomBytes } from "node:crypto";
 import {
   chmod,
-  copyFile,
   mkdir,
   readFile,
   readdir,
@@ -354,6 +353,8 @@ export function renderWorkspaceCompose(config) {
 
 export function composeCommand(action, root, options = {}) {
   validateHome(root);
+  const stateRoot = options.stateRoot ?? root;
+  validateHome(stateRoot);
   const profile = options.profile ?? "standard";
   if (profile !== "light" && profile !== "standard") {
     throw new Error("Compose profile must be light or standard.");
@@ -362,9 +363,9 @@ export function composeCommand(action, root, options = {}) {
     "compose",
     "--project-name", composeProjectName(root),
     "--project-directory", root,
-    "--env-file", join(root, "runtime.env"),
-    "-f", join(root, "compose.yml"),
-    "-f", join(root, "compose.workspaces.yml"),
+    "--env-file", join(stateRoot, "runtime.env"),
+    "-f", join(stateRoot, "compose.yml"),
+    "-f", join(stateRoot, "compose.workspaces.yml"),
     ...(profile === "standard" ? ["--profile", "standard"] : [])
   ];
   const actions = {
@@ -459,7 +460,9 @@ export async function selectLatestBackupId(root) {
     .sort()
     .at(-1);
   if (!backupId) {
-    throw new Error('No portable backup exists. Run "spaceapp backup" before restore.');
+    throw new Error(
+      'No portable backup exists. Run "npx --yes run-spaceapp@latest backup" before restore.'
+    );
   }
   return backupId;
 }
@@ -472,9 +475,8 @@ export async function writeRuntimeFiles(root, config) {
   await atomicWrite(join(root, "compose.workspaces.yml"), renderWorkspaceCompose(config));
 }
 
-export async function initializeInstallation(root, {
+export async function prepareInstallation(root, {
   version,
-  templateDir = defaultTemplateDir(),
   profile
 }) {
   validateHome(root);
@@ -505,10 +507,7 @@ export async function initializeInstallation(root, {
   if (resolvedProfile !== undefined) {
     config = { ...config, profile: resolvedProfile };
   }
-  await saveConfig(root, config);
-  await copyFile(join(templateDir, "compose.yml"), join(root, "compose.yml"));
-  await chmod(join(root, "compose.yml"), 0o600);
-  await writeRuntimeFiles(root, config);
+  validateConfig(config);
 
   const postgresPasswordPath = join(root, "secrets", "postgres-password");
   let postgresPassword;
@@ -559,6 +558,26 @@ export async function initializeInstallation(root, {
   return { config, setupToken };
 }
 
+export async function commitInstallation(root, config, {
+  templateDir = defaultTemplateDir()
+} = {}) {
+  validateHome(root);
+  validateConfig(config);
+  const composeTemplate = await readFile(join(templateDir, "compose.yml"), "utf8");
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  await atomicWrite(join(root, "compose.yml"), composeTemplate);
+  await writeRuntimeFiles(root, config);
+  await saveConfig(root, config);
+}
+
+export async function initializeInstallation(root, options) {
+  const result = await prepareInstallation(root, options);
+  await commitInstallation(root, result.config, {
+    templateDir: options.templateDir
+  });
+  return result;
+}
+
 function validateWorkspace(workspace) {
   if (!workspace || typeof workspace !== "object") {
     throw new Error("Invalid workspace entry.");

package/src/prerequisites.mjs

@@ -11,6 +11,7 @@ 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 UNIVERSAL_INSTALL_COMMAND = "npx --yes run-spaceapp@latest install";
 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"
@@ -73,6 +74,17 @@ export function windowsPowerShellArgs(operation) {
       "$path = $env:SPACEAPP_DOCKER_DESKTOP_PATH",
       "if ([string]::IsNullOrWhiteSpace($path)) { exit 1 }",
       "Start-Process -FilePath $path"
+    ].join("; "),
+    "open-spaceapp-browser": [
+      "$ErrorActionPreference = 'Stop'",
+      "$url = $env:SPACEAPP_OPEN_URL",
+      "$uri = $null",
+      "if ([string]::IsNullOrWhiteSpace($url) -or -not [Uri]::TryCreate($url, [UriKind]::Absolute, [ref]$uri)) { exit 1 }",
+      "if ($uri.Scheme -ne 'http' -or @('127.0.0.1','0.0.0.0') -notcontains $uri.Host -or $uri.Port -lt 1024 -or $uri.Port -gt 65535) { exit 1 }",
+      "$roots = @([Environment]::GetEnvironmentVariable('ProgramFiles(x86)'), [Environment]::GetEnvironmentVariable('ProgramFiles'), [Environment]::GetEnvironmentVariable('LOCALAPPDATA')) | Where-Object { -not [string]::IsNullOrWhiteSpace($_) }",
+      "$edge = $roots | ForEach-Object { Join-Path $_ 'Microsoft\\Edge\\Application\\msedge.exe' } | Where-Object { Test-Path -LiteralPath $_ -PathType Leaf } | Select-Object -First 1",
+      "if ($edge) { Start-Process -FilePath $edge -ArgumentList @('--no-first-run','--no-default-browser-check',$url); exit 0 }",
+      "Start-Process -FilePath 'explorer.exe' -ArgumentList @($url)"
     ].join("; ")
   };
   if (!Object.hasOwn(scripts, operation)) {
@@ -210,7 +222,7 @@ async function ensureWindowsDocker({
     );
     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"
+        `Windows could not enable WSL2 automatically. Run "${UNIVERSAL_INSTALL_COMMAND}" from an Administrator Command Prompt, restart Windows if requested, and run it again.\n`
       );
       return { code: installWslCode, reexecuted: false };
     }
@@ -232,7 +244,7 @@ async function ensureWindowsDocker({
     if (scheduleCode !== 0) {
       stderr.write(
         "Windows must restart to finish WSL2, but SpaceApp could not schedule automatic continuation.\n" +
-        "Restart Windows, then run the same SpaceApp command again.\n"
+        `Restart Windows, then run "${UNIVERSAL_INSTALL_COMMAND}" again.\n`
       );
       return { code: scheduleCode, reexecuted: false };
     }
@@ -375,7 +387,7 @@ async function ensureWindowsDocker({
     return { code: 0, reexecuted: false };
   }
   stderr.write(
-    "Docker Desktop did not become ready after 10 minutes. Open Docker Desktop and complete its first-run setup (select \"Skip\" on \"Welcome to Docker\" or sign in), restart Windows if requested, then run \"spaceapp install\" again.\n"
+    `Docker Desktop did not become ready after 10 minutes. Open Docker Desktop and complete its first-run setup (select "Skip" on "Welcome to Docker" or sign in), restart Windows if requested, then run "${UNIVERSAL_INSTALL_COMMAND}" again.\n`
   );
   return { code: 1, reexecuted: false };
 }
@@ -483,7 +495,7 @@ async function ensureMacDocker({
     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"
+    `Docker Desktop was installed but did not become ready. Complete any Docker Desktop prompt, then run "${UNIVERSAL_INSTALL_COMMAND}" again.\n`
   );
   return { code: 1, reexecuted: false };
 }