structured-world
diff --git a/‎src/cli-utils.ts‎
Lines changed: 15 additions & 1 deletion b/‎src/cli-utils.ts‎
Lines changed: 15 additions & 1 deletion
diff --git a/‎src/cli/docker/container-runtime.ts‎
Lines changed: 132 additions & 0 deletions b/‎src/cli/docker/container-runtime.ts‎
Lines changed: 132 additions & 0 deletions
@@ -21,7 +21,11 @@ export interface CliArgs {
   dryRun: boolean;
   /** Git remote name to use (default: origin) */
   remoteName?: string;
-  /** Run init wizard */
+  /** Run unified setup wizard */
+  setup: boolean;
+  /** Setup wizard mode override */
+  setupMode?: "local" | "server" | "configure-existing";
+  /** Run init wizard (alias for setup --mode=local) */
   init: boolean;
   /** Run install command */
   install: boolean;
@@ -45,6 +49,7 @@ export function parseCliArgs(argv: string[] = process.argv): CliArgs {
     showProjectConfig: false,
     auto: false,
     dryRun: false,
+    setup: false,
     init: false,
     install: false,
     installArgs: [],
@@ -55,6 +60,15 @@ export function parseCliArgs(argv: string[] = process.argv): CliArgs {
   // Check for subcommands (first positional arg)
   if (args.length > 0) {
     switch (args[0]) {
+      case "setup":
+        result.setup = true;
+        // Parse setup-specific flags
+        for (const arg of args.slice(1)) {
+          if (arg === "--mode=local") result.setupMode = "local";
+          else if (arg === "--mode=server") result.setupMode = "server";
+          else if (arg === "--mode=configure-existing") result.setupMode = "configure-existing";
+        }
+        return result;
       case "init":
         result.init = true;
         return result;
 
@@ -0,0 +1,132 @@
+/**
+ * Container runtime detection module.
+ * Detects Docker or Podman and their compose variants, caching the result per process.
+ */
+
+import { spawnSync } from "child_process";
+import { ContainerRuntime, ContainerRuntimeInfo } from "./types";
+
+/** Module-level cached runtime info */
+let cachedRuntime: ContainerRuntimeInfo | null = null;
+
+/**
+ * Try running a command and return true if it exits 0.
+ */
+function commandSucceeds(cmd: string, args: string[]): boolean {
+  try {
+    const result = spawnSync(cmd, args, {
+      stdio: "pipe",
+      encoding: "utf8",
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Try running a command and return its stdout if it exits 0, otherwise undefined.
+ */
+function commandOutput(cmd: string, args: string[]): string | undefined {
+  try {
+    const result = spawnSync(cmd, args, {
+      stdio: "pipe",
+      encoding: "utf8",
+    });
+    if (result.status === 0 && result.stdout) {
+      return result.stdout.trim();
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Extract version string from runtime --version output.
+ * e.g. "Docker version 24.0.7, build afdd53b" → "24.0.7"
+ *      "podman version 4.9.3" → "4.9.3"
+ */
+function parseVersion(output: string): string | undefined {
+  const match = output.match(/(\d+\.\d+\.\d+)/);
+  return match?.[1];
+}
+
+/**
+ * Detect the compose command for a given runtime.
+ * Priority for docker: docker compose → docker-compose
+ * Priority for podman: podman compose → podman-compose → docker-compose (fallback)
+ */
+function detectComposeCmd(runtime: ContainerRuntime): string[] | null {
+  const runtimeCmd = runtime;
+
+  // Try "<runtime> compose version" (compose v2 plugin)
+  if (commandSucceeds(runtimeCmd, ["compose", "version"])) {
+    return [runtimeCmd, "compose"];
+  }
+
+  // Try "<runtime>-compose --version" (standalone compose)
+  const standaloneCompose = `${runtimeCmd}-compose`;
+  if (commandSucceeds(standaloneCompose, ["--version"])) {
+    return [standaloneCompose];
+  }
+
+  // Cross-runtime fallback: try docker-compose as last resort
+  if (commandSucceeds("docker-compose", ["--version"])) {
+    return ["docker-compose"];
+  }
+
+  return null;
+}
+
+/**
+ * Perform full container runtime detection.
+ * Priority: docker > podman.
+ * Checks runtime availability, daemon status, and compose command.
+ */
+export function detectContainerRuntime(): ContainerRuntimeInfo {
+  const runtimes: ContainerRuntime[] = ["docker", "podman"];
+
+  for (const runtime of runtimes) {
+    const versionOutput = commandOutput(runtime, ["--version"]);
+    if (versionOutput) {
+      // Runtime binary exists, check if daemon is accessible
+      const runtimeAvailable = commandSucceeds(runtime, ["info"]);
+      const composeCmd = detectComposeCmd(runtime);
+      const runtimeVersion = parseVersion(versionOutput);
+
+      return {
+        runtime,
+        runtimeCmd: runtime,
+        runtimeAvailable,
+        composeCmd,
+        runtimeVersion,
+      };
+    }
+  }
+
+  // No runtime found at all
+  return {
+    runtime: "docker",
+    runtimeCmd: "docker",
+    runtimeAvailable: false,
+    composeCmd: null,
+    runtimeVersion: undefined,
+  };
+}
+
+/**
+ * Get cached container runtime info.
+ * Detects once per process and caches the result.
+ */
+export function getContainerRuntime(): ContainerRuntimeInfo {
+  cachedRuntime ??= detectContainerRuntime();
+  return cachedRuntime;
+}
+
+/**
+ * Reset the runtime cache. Used in tests to allow re-detection.
+ */
+export function resetRuntimeCache(): void {
+  cachedRuntime = null;
+}