git-multiverse 0.1.1 → 0.1.2

package/README.md

@@ -12,10 +12,11 @@ npm install -g git-multiverse
 
 ```bash
 git-multiverse setup
-git-multiverse up
-git-multiverse down
+git-multiverse start
+git-multiverse stop
 git-multiverse status
 git-multiverse doctor
+git-multiverse uninstall
 ```
 
 ## State files
@@ -26,16 +27,25 @@ git-multiverse doctor
 
 ## Setup flow
 
-`git-multiverse setup` writes a standalone compose file that uses:
+`git-multiverse setup` writes local runtime files and starts Docker Compose automatically:
 
 - `anhdt5/git-multiverse:<tag>`
-- `neo4j:5.26-community` when using managed Neo4j
+- `neo4j:5.26-community` when using Docker with local database mode
+
+Setup choices:
+
+- runtime: `docker`
+- database mode: `local` or `remote`
+- Docker mode can use either local Neo4j in Compose or a remote Neo4j database
+- Native + remote-database startup is planned, but not available until release
+  binaries are bundled or downloaded automatically
 
 Security defaults:
 
 - host ports bind to `127.0.0.1`
 - `MULTIVERSE_MCP_ALLOW_ANONYMOUS=false`
 - random admin and Neo4j passwords by default
+- remote database URI, user, password, and database are required when using remote database mode
 - secrets stay only in `~/.git-multiverse/.env`
 
 ## Non-interactive example
@@ -43,9 +53,22 @@ Security defaults:
 ```bash
 git-multiverse setup \
   --non-interactive \
-  --neo4j-mode managed \
+  --runtime docker \
+  --db-mode local \
   --workspace /workspace/repos \
-  --admin-password 'replace-me' \
-  --neo4j-password 'replace-me-too' \
   --image-tag latest
 ```
+
+Docker with remote database example:
+
+```bash
+git-multiverse setup \
+  --non-interactive \
+  --runtime docker \
+  --db-mode remote \
+  --workspace /workspace/repos \
+  --neo4j-uri neo4j+s://db.example.com:7687 \
+  --neo4j-user neo4j \
+  --neo4j-password 'replace-me' \
+  --neo4j-database neo4j
+```

package/bin/git-multiverse.mjs

@@ -2,4 +2,7 @@
 
 import { main } from "../lib/app.mjs";
 
-await main(process.argv.slice(2));
+main(process.argv.slice(2)).catch((error) => {
+  console.error(`error: ${error.message}`);
+  process.exitCode = 1;
+});

package/lib/app.mjs

@@ -6,13 +6,15 @@ import process from "node:process";
 import net from "node:net";
 import readline from "node:readline/promises";
 import readlineModule from "node:readline";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 
 export const APP_IMAGE = "anhdt5/git-multiverse";
 export const NEO4J_IMAGE = "neo4j:5.26-community";
 export const DEFAULT_IMAGE_TAG = "latest";
 export const DEFAULT_PORT = "18081";
 export const STATE_DIR_NAME = ".git-multiverse";
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
 export const colors = {
   reset: "\x1b[0m",
@@ -40,15 +42,24 @@ export async function main(argv, overrides = {}) {
       case "setup":
         await cmdSetup(flags, overrides, io);
         break;
-      case "up":
-        await cmdUp(overrides, io);
+      case "start":
+        await cmdStart(overrides, io);
         break;
-      case "down":
-        await cmdDown(overrides, io);
+      case "stop":
+        await cmdStop(overrides, io);
+        break;
+      case "uninstall":
+        await cmdUninstall(overrides, io);
         break;
       case "status":
         await cmdStatus(overrides, io);
         break;
+      case "logs":
+        await cmdLogs(flags, overrides, io);
+        break;
+      case "verify":
+        await cmdVerify(overrides, io);
+        break;
       case "doctor":
         await cmdDoctor(overrides, io);
         break;
@@ -106,18 +117,46 @@ export function getStatePaths(overrides = {}) {
     homeDir,
     stateDir,
     envPath: path.join(stateDir, ".env"),
-    composePath: path.join(stateDir, "docker-compose.yaml")
+    composePath: path.join(stateDir, "docker-compose.yaml"),
+    binDir: path.join(stateDir, "bin"),
+    runDir: path.join(stateDir, "run"),
+    logDir: path.join(stateDir, "logs"),
+    nativeBinPath: path.join(stateDir, "bin", nativeBinaryName()),
+    apiPidPath: path.join(stateDir, "run", "api.pid"),
+    apiLogPath: path.join(stateDir, "logs", "api.log")
   };
 }
 
+export function loadExistingSetupConfig(overrides = {}) {
+  const fsModule = overrides.fsModule || fs;
+  const { envPath } = getStatePaths(overrides);
+  if (!fsModule.existsSync(envPath)) return {};
+  try {
+    return parseEnvFile(fsModule.readFileSync(envPath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export function buildSetupDraft(flags = {}, overrides = {}, currentConfig = {}) {
+  return createSetupConfig(flags, overrides, currentConfig);
+}
+
 export function createSetupConfig(flags = {}, overrides = {}, existingConfig = {}) {
   const env = overrides.env || process.env;
+  const paths = getStatePaths(overrides);
   const workspace = stringFlag(flags.workspace) || existingConfig.MULTIVERSE_HOST_WORKSPACE_DIR || path.join(getStatePaths(overrides).homeDir, "workspace", "repos");
-  const neo4jMode = normalizeNeo4jMode(
-    stringFlag(flags["neo4j-mode"]) || 
-    existingConfig.MULTIVERSE_NEO4J_MODE || 
-    env.GIT_MULTIVERSE_NEO4J_MODE || 
-    "managed"
+  const runtime = normalizeRuntimeMode(
+    stringFlag(flags.runtime) ||
+    existingConfig.MULTIVERSE_RUNTIME_MODE ||
+    env.GIT_MULTIVERSE_RUNTIME ||
+    "docker"
+  );
+  const dbMode = normalizeDbMode(
+    stringFlag(flags["db-mode"]) ||
+    existingConfig.MULTIVERSE_DB_MODE ||
+    legacyNeo4jModeToDbMode(stringFlag(flags["neo4j-mode"]) || existingConfig.MULTIVERSE_NEO4J_MODE || env.GIT_MULTIVERSE_NEO4J_MODE) ||
+    (runtime === "docker" ? "local" : "remote")
   );
   const adminPassword = stringFlag(flags["admin-password"]) || existingConfig.MULTIVERSE_ADMIN_PASSWORD;
   const neo4jPassword = stringFlag(flags["neo4j-password"]) || existingConfig.MULTIVERSE_NEO4J_PASSWORD;
@@ -130,12 +169,13 @@ export function createSetupConfig(flags = {}, overrides = {}, existingConfig = {
     MULTIVERSE_HOST: "0.0.0.0",
     MULTIVERSE_PORT: DEFAULT_PORT,
     MULTIVERSE_API_PORT: DEFAULT_PORT,
+    MULTIVERSE_RUNTIME_MODE: runtime,
     MULTIVERSE_ADMIN_USER: "admin",
-    MULTIVERSE_ADMIN_PASSWORD: adminPassword || "123456",
+    MULTIVERSE_ADMIN_PASSWORD: adminPassword || randomPassword(24, overrides.randomBytesImpl),
     MULTIVERSE_MCP_ALLOW_ANONYMOUS: "false",
-    MULTIVERSE_WORKSPACE_DIR: "/workspace/repos",
+    MULTIVERSE_WORKSPACE_DIR: runtime === "native" ? workspace : "/workspace/repos",
     MULTIVERSE_HOST_WORKSPACE_DIR: workspace,
-    DOCS_STORAGE_PATH: "/workspace/docs",
+    DOCS_STORAGE_PATH: runtime === "native" ? path.join(paths.stateDir, "docs") : "/workspace/docs",
     MULTIVERSE_ENABLE_AI: enableAiFlag !== null ? enableAiFlag : (existingConfig.MULTIVERSE_ENABLE_AI || "false"),
     NINEROUTER_API_BASE_URL: cleanBaseUrl(stringFlag(flags["llm-base-url"]), "llm") || existingConfig.NINEROUTER_API_BASE_URL || "",
     NINEROUTER_MODEL_NAME: stringFlag(flags["llm-model"]) || existingConfig.NINEROUTER_MODEL_NAME || "",
@@ -145,22 +185,25 @@ export function createSetupConfig(flags = {}, overrides = {}, existingConfig = {
     EMBEDDING_MODEL_NAME: stringFlag(flags["embedding-model"]) || existingConfig.EMBEDDING_MODEL_NAME || "",
     EMBEDDING_API_KEY: stringFlag(flags["embedding-key"]) || existingConfig.EMBEDDING_API_KEY || "",
     MULTIVERSE_IMAGE_TAG: imageTag,
-    MULTIVERSE_NEO4J_MODE: neo4jMode,
+    MULTIVERSE_DB_MODE: dbMode,
+    MULTIVERSE_NEO4J_MODE: dbMode === "local" ? "managed" : "external",
     MULTIVERSE_NEO4J_DATABASE: stringFlag(flags["neo4j-database"]) || existingConfig.MULTIVERSE_NEO4J_DATABASE || "neo4j",
     MULTIVERSE_NEO4J_USER: stringFlag(flags["neo4j-user"]) || existingConfig.MULTIVERSE_NEO4J_USER || "neo4j",
     MULTIVERSE_NEO4J_URI: "",
     MULTIVERSE_NEO4J_PASSWORD: ""
   };
 
-  if (neo4jMode === "managed") {
+  if (dbMode === "local") {
     config.MULTIVERSE_NEO4J_URI = "neo4j://neo4j:7687";
-    config.MULTIVERSE_NEO4J_PASSWORD = neo4jPassword || existingConfig.MULTIVERSE_NEO4J_PASSWORD || "123456";
+    config.MULTIVERSE_NEO4J_PASSWORD = neo4jPassword || existingConfig.MULTIVERSE_NEO4J_PASSWORD || randomPassword(24, overrides.randomBytesImpl);
   } else {
     config.MULTIVERSE_NEO4J_URI = stringFlag(flags["neo4j-uri"]) || existingConfig.MULTIVERSE_NEO4J_URI || "";
     config.MULTIVERSE_NEO4J_PASSWORD = neo4jPassword || existingConfig.MULTIVERSE_NEO4J_PASSWORD || "";
   }
 
-  validateConfig(config, { nonInteractive: toBool(flags["non-interactive"]) });
+  if (!overrides.skipValidation) {
+    validateConfig(config, { nonInteractive: toBool(flags["non-interactive"]) });
+  }
   return config;
 }
 
@@ -168,26 +211,32 @@ export function validateConfig(config, options = {}) {
   if (!path.isAbsolute(config.MULTIVERSE_HOST_WORKSPACE_DIR)) {
     throw new Error("Workspace path must be absolute.");
   }
+  if (!["docker", "native"].includes(config.MULTIVERSE_RUNTIME_MODE)) {
+    throw new Error("Runtime mode must be docker or native.");
+  }
   if (!config.MULTIVERSE_ADMIN_PASSWORD) {
     throw new Error("Admin password is required.");
   }
-  if (!["managed", "external"].includes(config.MULTIVERSE_NEO4J_MODE)) {
-    throw new Error("Neo4j mode must be managed or external.");
+  if (!["local", "remote"].includes(config.MULTIVERSE_DB_MODE)) {
+    throw new Error("Database mode must be local or remote.");
+  }
+  if (config.MULTIVERSE_RUNTIME_MODE === "native" && config.MULTIVERSE_DB_MODE !== "remote") {
+    throw new Error("Native runtime requires remote database mode.");
   }
-  if (config.MULTIVERSE_NEO4J_MODE === "managed") {
+  if (config.MULTIVERSE_DB_MODE === "local") {
     if (!config.MULTIVERSE_NEO4J_PASSWORD) {
-      throw new Error("Neo4j password is required for managed mode.");
+      throw new Error("Neo4j password is required for local database mode.");
     }
     return;
   }
   if (!config.MULTIVERSE_NEO4J_URI) {
-    throw new Error("MULTIVERSE_NEO4J_URI is required for external mode.");
+    throw new Error("MULTIVERSE_NEO4J_URI is required for remote database mode.");
   }
   if (!config.MULTIVERSE_NEO4J_USER) {
-    throw new Error("MULTIVERSE_NEO4J_USER is required for external mode.");
+    throw new Error("MULTIVERSE_NEO4J_USER is required for remote database mode.");
   }
-  if (!config.MULTIVERSE_NEO4J_PASSWORD && options.nonInteractive) {
-    throw new Error("MULTIVERSE_NEO4J_PASSWORD is required for external mode.");
+  if (!config.MULTIVERSE_NEO4J_PASSWORD) {
+    throw new Error("MULTIVERSE_NEO4J_PASSWORD is required for remote database mode.");
   }
 }
 
@@ -196,6 +245,7 @@ export function renderEnvFile(config) {
     "MULTIVERSE_HOST",
     "MULTIVERSE_PORT",
     "MULTIVERSE_API_PORT",
+    "MULTIVERSE_RUNTIME_MODE",
     "MULTIVERSE_ADMIN_USER",
     "MULTIVERSE_ADMIN_PASSWORD",
     "MULTIVERSE_MCP_ALLOW_ANONYMOUS",
@@ -211,6 +261,7 @@ export function renderEnvFile(config) {
     "EMBEDDING_MODEL_NAME",
     "EMBEDDING_API_KEY",
     "MULTIVERSE_IMAGE_TAG",
+    "MULTIVERSE_DB_MODE",
     "MULTIVERSE_NEO4J_MODE",
     "MULTIVERSE_NEO4J_URI",
     "MULTIVERSE_NEO4J_USER",
@@ -226,6 +277,9 @@ export function renderEnvFile(config) {
 }
 
 export function renderComposeFile(config) {
+  if (config.MULTIVERSE_RUNTIME_MODE === "native") {
+    return "# Native runtime selected. Docker Compose is not used.\n";
+  }
   const lines = [
     "services:",
     "  multiverse:",
@@ -241,11 +295,11 @@ export function renderComposeFile(config) {
     "  ",
   ];
 
-  if (config.MULTIVERSE_NEO4J_MODE === "managed") {
+  if (config.MULTIVERSE_DB_MODE === "local") {
     lines.push("    depends_on:", "      - neo4j");
   }
 
-  if (config.MULTIVERSE_NEO4J_MODE === "managed") {
+  if (config.MULTIVERSE_DB_MODE === "local") {
     lines.push(
       "  neo4j:",
       `    image: ${NEO4J_IMAGE}`,
@@ -268,6 +322,9 @@ export function writeStateFiles(config, overrides = {}) {
   const fsModule = overrides.fsModule || fs;
   const paths = getStatePaths(overrides);
   fsModule.mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 });
+  fsModule.mkdirSync(paths.binDir, { recursive: true, mode: 0o700 });
+  fsModule.mkdirSync(paths.runDir, { recursive: true, mode: 0o700 });
+  fsModule.mkdirSync(paths.logDir, { recursive: true, mode: 0o700 });
   fsModule.chmodSync(paths.stateDir, 0o700);
   fsModule.writeFileSync(paths.envPath, renderEnvFile(config), { mode: 0o600 });
   fsModule.chmodSync(paths.envPath, 0o600);
@@ -281,7 +338,11 @@ export function loadConfig(overrides = {}) {
   if (!fsModule.existsSync(envPath)) {
     throw new Error(`missing ${envPath}. Run: git-multiverse setup`);
   }
-  return parseEnvFile(fsModule.readFileSync(envPath, "utf8"));
+  const config = parseEnvFile(fsModule.readFileSync(envPath, "utf8"));
+  if (config.MULTIVERSE_RUNTIME_MODE === "non-docker") {
+    config.MULTIVERSE_RUNTIME_MODE = "native";
+  }
+  return config;
 }
 
 export function parseEnvFile(source) {
@@ -300,52 +361,79 @@ export function parseEnvFile(source) {
 
 export async function cmdSetup(flags, overrides = {}, io = createIO(overrides)) {
   const nonInteractive = toBool(flags["non-interactive"]);
-  const fsModule = overrides.fsModule || fs;
   const paths = getStatePaths(overrides);
-  let existingConfig = {};
-  if (fsModule.existsSync(paths.envPath)) {
-    try {
-      existingConfig = parseEnvFile(fsModule.readFileSync(paths.envPath, "utf8"));
-    } catch (e) {
-      // ignore
-    }
-  }
+  const currentConfig = loadExistingSetupConfig(overrides);
 
-  const config = createSetupConfig(flags, overrides, existingConfig);
   const interactive = !nonInteractive && isInteractive(overrides);
+  const config = buildSetupDraft(flags, { ...overrides, skipValidation: interactive }, currentConfig);
   if (interactive) {
     await runWizard(config, flags, overrides, io);
     validateConfig(config);
   }
+  ensureRuntimeSupported(config, overrides);
   writeStateFiles(config, overrides);
   io.log(`${colors.green}✔ Configuration successfully written:${colors.reset}`);
   io.log(`  - Env file: ${colors.cyan}${paths.envPath}${colors.reset} (Mode: 0600)`);
   io.log(`  - Docker Compose: ${colors.cyan}${paths.composePath}${colors.reset}`);
-  io.log(`  - Neo4j Mode: ${colors.cyan}${config.MULTIVERSE_NEO4J_MODE}${colors.reset}`);
+  io.log(`  - Runtime: ${colors.cyan}${config.MULTIVERSE_RUNTIME_MODE}${colors.reset}`);
+  io.log(`  - Database Mode: ${colors.cyan}${config.MULTIVERSE_DB_MODE}${colors.reset}`);
   io.log(`  - Admin password: ${colors.bold}${colors.green}${config.MULTIVERSE_ADMIN_PASSWORD}${colors.reset}`);
-  
-  if (interactive) {
-    io.log(`\n${colors.green}${colors.bold}✔ Setup complete! Starting Multiverse containers automatically...${colors.reset}`);
-    await cmdUp(overrides, io);
-  }
+
+  io.log(`\n${colors.green}${colors.bold}✔ Setup complete. Starting Multiverse automatically...${colors.reset}`);
+  await cmdStart(overrides, io);
+  io.log(`\n${colors.green}${colors.bold}✔ Verifying setup...${colors.reset}`);
+  await cmdVerify(overrides, io);
 }
 
-export async function cmdUp(overrides = {}, io = createIO(overrides)) {
+export async function cmdStart(overrides = {}, io = createIO(overrides)) {
+  const config = loadConfig(overrides);
+  if (config.MULTIVERSE_RUNTIME_MODE === "native") {
+    await startNativeRuntime(config, overrides, io);
+    return;
+  }
   const paths = getStatePaths(overrides);
   ensureDockerAvailable(overrides);
   runDockerCompose(["up", "-d"], overrides, io, paths);
 }
 
-export async function cmdDown(overrides = {}, io = createIO(overrides)) {
+export async function cmdStop(overrides = {}, io = createIO(overrides)) {
+  const config = loadConfig(overrides);
+  if (config.MULTIVERSE_RUNTIME_MODE === "native") {
+    await stopNativeRuntime(overrides, io);
+    return;
+  }
   const paths = getStatePaths(overrides);
   ensureDockerAvailable(overrides);
   runDockerCompose(["down"], overrides, io, paths);
 }
 
+export async function cmdUninstall(overrides = {}, io = createIO(overrides)) {
+  const fsModule = overrides.fsModule || fs;
+  const paths = getStatePaths(overrides);
+  if (fsModule.existsSync(paths.envPath)) {
+    const config = loadConfig(overrides);
+    if (config.MULTIVERSE_RUNTIME_MODE === "native") {
+      await stopNativeRuntime(overrides, io);
+    } else {
+      ensureDockerAvailable(overrides);
+      runDockerCompose(["down", "--volumes"], overrides, io, paths);
+    }
+  }
+  fsModule.rmSync(paths.stateDir, { recursive: true, force: true });
+  io.log(`${colors.green}✔ Removed ${paths.stateDir}${colors.reset}`);
+}
+
 export async function cmdStatus(overrides = {}, io = createIO(overrides)) {
   const paths = getStatePaths(overrides);
-  ensureDockerAvailable(overrides);
-  runDockerCompose(["ps"], overrides, io, paths);
+  const config = loadConfig(overrides);
+  if (config.MULTIVERSE_RUNTIME_MODE !== "native") {
+    ensureDockerAvailable(overrides);
+    runDockerCompose(["ps"], overrides, io, paths);
+  } else {
+    const pid = readPid(paths, overrides);
+    io.log("runtime: native");
+    io.log(`pid: ${pid && isProcessRunning(pid, overrides) ? pid : "not running"}`);
+  }
   const health = await checkHealth("http://127.0.0.1:18081/api/health", overrides.fetchImpl || globalThis.fetch);
   io.log(`health: ${health.ok ? health.message : `unreachable (${health.message})`}`);
   if (!health.ok) {
@@ -354,17 +442,54 @@ export async function cmdStatus(overrides = {}, io = createIO(overrides)) {
   }
 }
 
+export async function cmdVerify(overrides = {}, io = createIO(overrides)) {
+  const paths = getStatePaths(overrides);
+  const config = loadConfig(overrides);
+  validateConfig(config);
+
+  if (config.MULTIVERSE_RUNTIME_MODE === "native") {
+    const pid = readPid(paths, overrides);
+    if (!pid || !isProcessRunning(pid, overrides)) {
+      throw new Error("native runtime is not running");
+    }
+    io.log(`native runtime: running (pid ${pid})`);
+  } else {
+    ensureDockerAvailable(overrides);
+    io.log("docker runtime: configured");
+  }
+
+  const health = await waitForHealth(healthURL(config), overrides.fetchImpl || globalThis.fetch, {
+    healthAttempts: overrides.verifyHealthAttempts || overrides.healthAttempts || 60,
+    healthIntervalMs: overrides.verifyHealthIntervalMs || overrides.healthIntervalMs || 1000
+  });
+  if (!health.ok) {
+    throw new Error(`setup verification failed: API health unreachable (${health.message})`);
+  }
+  io.log(`health: ${health.message}`);
+  io.log(`${colors.green}✔ Setup verified. Multiverse is ready at http://127.0.0.1:${config.MULTIVERSE_API_PORT || DEFAULT_PORT}${colors.reset}`);
+}
+
+export async function cmdLogs(flags = {}, overrides = {}, io = createIO(overrides)) {
+  const config = loadConfig(overrides);
+  if (config.MULTIVERSE_RUNTIME_MODE !== "native") {
+    const paths = getStatePaths(overrides);
+    ensureDockerAvailable(overrides);
+    runDockerCompose(["logs", "--tail", stringFlag(flags.tail) || "200"], overrides, io, paths);
+    return;
+  }
+  const fsModule = overrides.fsModule || fs;
+  const { apiLogPath } = getStatePaths(overrides);
+  if (!fsModule.existsSync(apiLogPath)) {
+    io.log(`No native log file yet: ${apiLogPath}`);
+    return;
+  }
+  io.log(tailText(fsModule.readFileSync(apiLogPath, "utf8"), Number(stringFlag(flags.tail) || 200)));
+}
+
 export async function cmdDoctor(overrides = {}, io = createIO(overrides)) {
   const fsModule = overrides.fsModule || fs;
   const paths = getStatePaths(overrides);
   let failed = false;
-  const docker = checkCommand(["docker", "--version"], overrides);
-  printDoctor(io, "docker", docker.ok, docker.ok ? docker.output : "missing docker CLI");
-  failed ||= !docker.ok;
-  const compose = checkCommand(["docker", "compose", "version"], overrides);
-  printDoctor(io, "docker compose", compose.ok, compose.ok ? compose.output : "missing docker compose plugin");
-  failed ||= !compose.ok;
-
   const envExists = fsModule.existsSync(paths.envPath);
   printDoctor(io, "env file", envExists, envExists ? paths.envPath : "run git-multiverse setup");
   failed ||= !envExists;
@@ -372,12 +497,25 @@ export async function cmdDoctor(overrides = {}, io = createIO(overrides)) {
   let config = null;
   if (envExists) {
     config = parseEnvFile(fsModule.readFileSync(paths.envPath, "utf8"));
+    const dockerRuntime = config.MULTIVERSE_RUNTIME_MODE !== "native";
+    const docker = checkCommand(["docker", "--version"], overrides);
+    printDoctor(io, "docker", !dockerRuntime || docker.ok, dockerRuntime ? (docker.ok ? docker.output : "missing docker CLI") : "not required for native runtime");
+    failed ||= dockerRuntime && !docker.ok;
+    const compose = checkCommand(["docker", "compose", "version"], overrides);
+    printDoctor(io, "docker compose", !dockerRuntime || compose.ok, dockerRuntime ? (compose.ok ? compose.output : "missing docker compose plugin") : "not required for native runtime");
+    failed ||= dockerRuntime && !compose.ok;
     const envMode = fsModule.statSync(paths.envPath).mode & 0o777;
     const isWindows = os.platform() === "win32";
     const modeOk = isWindows || envMode === 0o600;
     printDoctor(io, "env mode", modeOk, `0${envMode.toString(8)}`);
     failed ||= !modeOk;
-    printDoctor(io, "neo4j mode", true, config.MULTIVERSE_NEO4J_MODE);
+    printDoctor(io, "runtime", true, config.MULTIVERSE_RUNTIME_MODE || "docker");
+    if (config.MULTIVERSE_RUNTIME_MODE === "native") {
+      const nativeBinary = resolveNativeBinary(overrides);
+      printDoctor(io, "native binary", nativeBinary.ok, nativeBinary.ok ? nativeBinary.path : nativeBinary.message);
+      failed ||= !nativeBinary.ok;
+    }
+    printDoctor(io, "database mode", true, config.MULTIVERSE_DB_MODE || legacyNeo4jModeToDbMode(config.MULTIVERSE_NEO4J_MODE));
     printDoctor(io, "mcp anonymous", config.MULTIVERSE_MCP_ALLOW_ANONYMOUS === "false", `MULTIVERSE_MCP_ALLOW_ANONYMOUS=${config.MULTIVERSE_MCP_ALLOW_ANONYMOUS}`);
     failed ||= config.MULTIVERSE_MCP_ALLOW_ANONYMOUS !== "false";
     const adminOk = Boolean(config.MULTIVERSE_ADMIN_PASSWORD && config.MULTIVERSE_ADMIN_PASSWORD !== "admin");
@@ -510,7 +648,7 @@ export function runDockerCompose(args, overrides = {}, io = createIO(overrides),
   if (!result.ok) {
     throw new Error(`docker compose ${args.join(" ")} failed`);
   }
-  io.log(`compose ${args.join(" ")} ok (${config.MULTIVERSE_NEO4J_MODE})`);
+  io.log(`compose ${args.join(" ")} ok (${config.MULTIVERSE_DB_MODE || legacyNeo4jModeToDbMode(config.MULTIVERSE_NEO4J_MODE)})`);
 }
 
 export function checkCommand(command, overrides = {}) {
@@ -529,6 +667,140 @@ export function execCommand(command, overrides = {}, options = {}) {
   return { ok: !result?.error && result?.status === 0, output };
 }
 
+export function nativeBinaryName(platform = os.platform()) {
+  return platform === "win32" ? "multiverse-api.exe" : "multiverse-api";
+}
+
+export function nativePlatformDir(platform = os.platform(), arch = os.arch()) {
+  const normalizedArch = arch === "x64" ? "amd64" : arch;
+  return `${platform}-${normalizedArch}`;
+}
+
+export function resolveNativeBinary(overrides = {}) {
+  const fsModule = overrides.fsModule || fs;
+  const paths = getStatePaths(overrides);
+  const candidates = [
+    paths.nativeBinPath,
+    path.join(overrides.packageRoot || PACKAGE_ROOT, "native", nativePlatformDir(overrides.platform || os.platform(), overrides.arch || os.arch()), nativeBinaryName(overrides.platform || os.platform())),
+    path.resolve(overrides.repoRoot || path.join(PACKAGE_ROOT, "..", ".."), "bin", nativeBinaryName(overrides.platform || os.platform()))
+  ];
+  const found = candidates.find((candidate) => fsModule.existsSync(candidate));
+  if (!found) {
+    return { ok: false, message: `missing native API binary for ${nativePlatformDir(overrides.platform || os.platform(), overrides.arch || os.arch())}. Expected ${candidates.join(" or ")}` };
+  }
+  return { ok: true, path: found };
+}
+
+export function installNativeBinary(overrides = {}) {
+  const fsModule = overrides.fsModule || fs;
+  const paths = getStatePaths(overrides);
+  const resolved = resolveNativeBinary(overrides);
+  if (!resolved.ok) throw new Error(resolved.message);
+  fsModule.mkdirSync(paths.binDir, { recursive: true, mode: 0o700 });
+  if (path.resolve(resolved.path) !== path.resolve(paths.nativeBinPath)) {
+    fsModule.copyFileSync(resolved.path, paths.nativeBinPath);
+  }
+  if ((overrides.platform || os.platform()) !== "win32") {
+    fsModule.chmodSync(paths.nativeBinPath, 0o700);
+  }
+  return paths.nativeBinPath;
+}
+
+function healthURL(config) {
+  return `http://127.0.0.1:${config.MULTIVERSE_API_PORT || DEFAULT_PORT}/api/health`;
+}
+
+export async function startNativeRuntime(config, overrides = {}, io = createIO(overrides)) {
+  const fsModule = overrides.fsModule || fs;
+  const paths = getStatePaths(overrides);
+  fsModule.mkdirSync(paths.runDir, { recursive: true, mode: 0o700 });
+  fsModule.mkdirSync(paths.logDir, { recursive: true, mode: 0o700 });
+
+  const existingPid = readPid(paths, overrides);
+  if (existingPid && isProcessRunning(existingPid, overrides)) {
+    io.log(`native runtime already running (pid ${existingPid})`);
+    return;
+  }
+
+  const binaryPath = installNativeBinary(overrides);
+  const env = { ...(overrides.env || process.env), ...config };
+  const logFd = fsModule.openSync(paths.apiLogPath, "a");
+  let child;
+  try {
+    child = (overrides.spawnImpl || spawn)(binaryPath, [], {
+      cwd: paths.stateDir,
+      detached: true,
+      env,
+      stdio: ["ignore", logFd, logFd]
+    });
+  } finally {
+    fsModule.closeSync?.(logFd);
+  }
+  child.unref?.();
+  fsModule.writeFileSync(paths.apiPidPath, `${child.pid}\n`, { mode: 0o600 });
+  io.log(`native runtime started (pid ${child.pid})`);
+  io.log(`logs: ${paths.apiLogPath}`);
+
+  if (!overrides.skipHealthWait) {
+    const health = await waitForHealth(healthURL(config), overrides.fetchImpl || globalThis.fetch, overrides);
+    if (!health.ok) {
+      io.log(`${colors.yellow}health check not ready yet: ${health.message}${colors.reset}`);
+    }
+  }
+}
+
+export async function stopNativeRuntime(overrides = {}, io = createIO(overrides)) {
+  const fsModule = overrides.fsModule || fs;
+  const paths = getStatePaths(overrides);
+  const pid = readPid(paths, overrides);
+  if (!pid) {
+    io.log("native runtime is not running");
+    return;
+  }
+  if (!isProcessRunning(pid, overrides)) {
+    fsModule.rmSync(paths.apiPidPath, { force: true });
+    io.log("removed stale native runtime pid file");
+    return;
+  }
+  const kill = overrides.processKillImpl || process.kill;
+  kill(pid, "SIGTERM");
+  fsModule.rmSync(paths.apiPidPath, { force: true });
+  io.log(`native runtime stopped (pid ${pid})`);
+}
+
+function readPid(paths = getStatePaths(), overrides = {}) {
+  const fsModule = overrides.fsModule || fs;
+  if (!fsModule.existsSync(paths.apiPidPath)) return 0;
+  const pid = Number(fsModule.readFileSync(paths.apiPidPath, "utf8").trim());
+  return Number.isInteger(pid) && pid > 0 ? pid : 0;
+}
+
+function isProcessRunning(pid, overrides = {}) {
+  try {
+    (overrides.processKillImpl || process.kill)(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForHealth(url, fetchImpl, overrides = {}) {
+  const attempts = Number(overrides.healthAttempts || 30);
+  const intervalMs = Number(overrides.healthIntervalMs || 500);
+  let last = { ok: false, message: "not checked" };
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    last = await checkHealth(url, fetchImpl);
+    if (last.ok) return last;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  return last;
+}
+
+function tailText(text, lineCount) {
+  const lines = text.split(/\r?\n/);
+  return lines.slice(Math.max(0, lines.length - Math.max(1, lineCount))).join("\n");
+}
+
 export async function checkHealth(url, fetchImpl = globalThis.fetch) {
   if (typeof fetchImpl !== "function") {
     return { ok: false, message: "fetch unavailable" };
@@ -552,50 +824,69 @@ export async function checkPortStatus(port, netModule = net) {
   });
 }
 
-function showPageHeader(pageNum, title, io) {
+function showPageHeader(pageNum, title, io, context = {}) {
   console.clear();
   io.log(`${colors.cyan}==================================================${colors.reset}`);
-  io.log(`${colors.bold}${colors.cyan}          MULTIVERSE ONBOARDING WIZARD`);
-  io.log(`          [Page ${pageNum} of 5: ${title}]${colors.reset}`);
+  io.log(`${colors.bold}${colors.cyan}          Welcome to Multiverse Setup`);
+  io.log(`          Step ${pageNum} of 5: ${title}${colors.reset}`);
   io.log(`${colors.cyan}==================================================${colors.reset}`);
-  io.log(`${colors.yellow}ℹ Press Enter to keep default values.${colors.reset}`);
+  if (context.envPath) {
+    io.log(`${context.hasExistingConfig ? "Using" : "Creating"} config: ${colors.cyan}${context.envPath}${colors.reset}`);
+  }
+  io.log(`${colors.yellow}Press Enter to keep saved/default values.${colors.reset}`);
   io.log("");
 }
 
 export async function runWizard(config, flags, overrides = {}, io = createIO(overrides)) {
   const rl = readline.createInterface({ input: overrides.stdin || process.stdin, output: overrides.stdout || process.stdout });
+  const paths = getStatePaths(overrides);
+  const wizardContext = {
+    envPath: paths.envPath,
+    hasExistingConfig: (overrides.fsModule || fs).existsSync(paths.envPath)
+  };
   try {
     // ── Page 1: System & Workspace ──────────────────────────────────
-    showPageHeader(1, "System & Workspace", io);
-    if (!flags["neo4j-mode"]) {
-      config.MULTIVERSE_NEO4J_MODE = normalizeNeo4jMode(await prompt(rl, "Neo4j mode (managed/external)", config.MULTIVERSE_NEO4J_MODE));
+    showPageHeader(1, "System & Workspace", io, wizardContext);
+    if (!flags.runtime) {
+      config.MULTIVERSE_RUNTIME_MODE = await promptMenu(rl, "Select runtime mode:", [
+        { name: "Docker Compose (recommended)", value: "docker" }
+      ], "docker", overrides);
+    }
+    if (config.MULTIVERSE_RUNTIME_MODE === "native") {
+      config.MULTIVERSE_DB_MODE = "remote";
+      config.MULTIVERSE_NEO4J_MODE = "external";
+    } else if (!flags["db-mode"] && !flags["neo4j-mode"]) {
+      config.MULTIVERSE_DB_MODE = await promptMenu(rl, "Select database mode:", [
+        { name: "Local Neo4j container", value: "local" },
+        { name: "Remote database", value: "remote" }
+      ], config.MULTIVERSE_DB_MODE, overrides);
+      config.MULTIVERSE_NEO4J_MODE = config.MULTIVERSE_DB_MODE === "local" ? "managed" : "external";
     }
     if (!flags.workspace) {
       config.MULTIVERSE_HOST_WORKSPACE_DIR = await prompt(rl, "Workspace host path", config.MULTIVERSE_HOST_WORKSPACE_DIR);
     }
 
     // ── Page 2: Security & Credentials ──────────────────────────────
-    showPageHeader(2, "Security & Credentials", io);
+    showPageHeader(2, "Security & Credentials", io, wizardContext);
     if (!flags["admin-password"]) {
-      config.MULTIVERSE_ADMIN_PASSWORD = await prompt(rl, "Admin password", config.MULTIVERSE_ADMIN_PASSWORD);
+      config.MULTIVERSE_ADMIN_PASSWORD = await promptSecret(rl, "Admin password", config.MULTIVERSE_ADMIN_PASSWORD, { required: true });
     }
-    if (config.MULTIVERSE_NEO4J_MODE === "managed") {
+    if (config.MULTIVERSE_DB_MODE === "local") {
       if (!flags["neo4j-password"]) {
-        config.MULTIVERSE_NEO4J_PASSWORD = await prompt(rl, "Neo4j password", config.MULTIVERSE_NEO4J_PASSWORD);
+        config.MULTIVERSE_NEO4J_PASSWORD = await promptSecret(rl, "Local Neo4j password", config.MULTIVERSE_NEO4J_PASSWORD, { required: true });
       }
     } else {
       if (!flags["neo4j-uri"]) config.MULTIVERSE_NEO4J_URI = await prompt(rl, "Neo4j URI", config.MULTIVERSE_NEO4J_URI);
       if (!flags["neo4j-user"]) config.MULTIVERSE_NEO4J_USER = await prompt(rl, "Neo4j user", config.MULTIVERSE_NEO4J_USER);
-      if (!flags["neo4j-password"]) config.MULTIVERSE_NEO4J_PASSWORD = await prompt(rl, "Neo4j password", config.MULTIVERSE_NEO4J_PASSWORD);
+      if (!flags["neo4j-password"]) config.MULTIVERSE_NEO4J_PASSWORD = await promptSecret(rl, "Remote Neo4j password", config.MULTIVERSE_NEO4J_PASSWORD, { required: true });
       if (!flags["neo4j-database"]) config.MULTIVERSE_NEO4J_DATABASE = await prompt(rl, "Neo4j database", config.MULTIVERSE_NEO4J_DATABASE);
     }
 
     // ── Page 3: AI Provider (LLM) ───────────────────────────────────
-    showPageHeader(3, "AI Provider (LLM)", io);
+    showPageHeader(3, "AI Provider (LLM)", io, wizardContext);
     if (!hasAny(flags, ["enable-ai", "llm-base-url", "llm-model", "llm-key"])) {
-      const defaultEnable = config.MULTIVERSE_ENABLE_AI === "true" ? "Y" : "N";
-      const answer = await prompt(rl, "Configure AI provider? (y/N)", defaultEnable);
-      if (/^y(es)?$/i.test(answer)) {
+      const answer = await promptMenu(rl, "Configure AI provider?", yesNoOptions(), config.MULTIVERSE_ENABLE_AI === "true" ? "yes" : "no", overrides);
+      if (answer === "yes") {
         config.MULTIVERSE_ENABLE_AI = "true";
         io.log("");
         const providerOptions = [
@@ -620,7 +911,7 @@ export async function runWizard(config, flags, overrides = {}, io = createIO(ove
           else defaultProvider = "custom";
         }
 
-        const provider = await promptMenu(rl, "Select AI Provider (LLM):", providerOptions, defaultProvider);
+        const provider = await promptMenu(rl, "Select AI Provider (LLM):", providerOptions, defaultProvider, overrides);
         io.log("");
         
         let baseUrl = "";
@@ -671,18 +962,17 @@ export async function runWizard(config, flags, overrides = {}, io = createIO(ove
         
         config.NINEROUTER_API_BASE_URL = baseUrl;
         config.NINEROUTER_MODEL_NAME = modelName;
-        config.NINEROUTER_API_KEY = await prompt(rl, "LLM API key", config.NINEROUTER_API_KEY);
+        config.NINEROUTER_API_KEY = await promptSecret(rl, "LLM API key", config.NINEROUTER_API_KEY);
       } else {
         config.MULTIVERSE_ENABLE_AI = "false";
       }
     }
 
     // ── Page 4: Vector Embeddings ───────────────────────────────────
-    showPageHeader(4, "Vector Embeddings", io);
+    showPageHeader(4, "Vector Embeddings", io, wizardContext);
     if (!hasAny(flags, ["enable-embeddings", "embedding-base-url", "embedding-model", "embedding-key"])) {
-      const defaultEnable = config.MULTIVERSE_ENABLE_EMBEDDINGS === "true" ? "Y" : "N";
-      const answer = await prompt(rl, "Configure embedding provider? (y/N)", defaultEnable);
-      if (/^y(es)?$/i.test(answer)) {
+      const answer = await promptMenu(rl, "Configure embedding provider?", yesNoOptions(), config.MULTIVERSE_ENABLE_EMBEDDINGS === "true" ? "yes" : "no", overrides);
+      if (answer === "yes") {
         config.MULTIVERSE_ENABLE_EMBEDDINGS = "true";
         io.log("");
         const embedOptions = [
@@ -699,7 +989,7 @@ export async function runWizard(config, flags, overrides = {}, io = createIO(ove
           else defaultEmbed = "custom";
         }
 
-        const provider = await promptMenu(rl, "Select Vector Embedding Provider:", embedOptions, defaultEmbed);
+        const provider = await promptMenu(rl, "Select Vector Embedding Provider:", embedOptions, defaultEmbed, overrides);
         io.log("");
         
         let baseUrl = "";
@@ -738,23 +1028,22 @@ export async function runWizard(config, flags, overrides = {}, io = createIO(ove
         
         config.EMBEDDING_API_BASE_URL = baseUrl;
         config.EMBEDDING_MODEL_NAME = modelName;
-        config.EMBEDDING_API_KEY = await prompt(rl, "Embedding API key", config.EMBEDDING_API_KEY);
+        config.EMBEDDING_API_KEY = await promptSecret(rl, "Embedding API key", config.EMBEDDING_API_KEY);
       } else {
         config.MULTIVERSE_ENABLE_EMBEDDINGS = "false";
       }
     }
 
     // ── Page 5: Docker Image & Finish ────────────────────────────────
-    showPageHeader(5, "Docker Image & Finish", io);
+    showPageHeader(5, "Docker Image & Finish", io, wizardContext);
     if (!flags["image-tag"]) {
       config.MULTIVERSE_IMAGE_TAG = await prompt(rl, "Multiverse image tag", config.MULTIVERSE_IMAGE_TAG);
     }
-    console.clear();
-    io.log(`${colors.green}==================================================`);
-    io.log("          MULTIVERSE ONBOARDING WIZARD");
-    io.log("                [SETUP COMPLETE]");
-    io.log(`==================================================${colors.reset}`);
-    io.log("");
+    showSetupSummary(config, paths.envPath, io);
+    const confirm = await promptMenu(rl, "Save this configuration and start Multiverse?", yesNoOptions(), "yes", overrides);
+    if (confirm !== "yes") {
+      throw new Error("setup cancelled; existing configuration was not changed");
+    }
   } finally {
     rl.close();
   }
@@ -764,17 +1053,20 @@ export function printHelp(log = console.log) {
   log(`git-multiverse
 
 Commands:
-  git-multiverse setup [--non-interactive] [--neo4j-mode managed|external]
+  git-multiverse setup [--non-interactive] [--runtime docker|native] [--db-mode local|remote]
     [--workspace /absolute/path]
     [--admin-password <password>]
     [--neo4j-uri <uri>] [--neo4j-user <user>] [--neo4j-password <password>] [--neo4j-database <db>]
     [--enable-ai] [--llm-base-url <url>] [--llm-model <name>] [--llm-key <key>]
     [--enable-embeddings] [--embedding-base-url <url>] [--embedding-model <name>] [--embedding-key <key>]
     [--image-tag <tag>]
-  git-multiverse up
-  git-multiverse down
+  git-multiverse start
+  git-multiverse stop
   git-multiverse status
+  git-multiverse logs [--tail 200]
+  git-multiverse verify
   git-multiverse doctor
+  git-multiverse uninstall
   git-multiverse mcp-setup [--editor claude|cursor|codex|opencode|windsurf]
     [--base-url <url>] [--mcp-key <key>]`);
 }
@@ -794,6 +1086,17 @@ function hasAny(flags, keys) {
   return keys.some((key) => Object.prototype.hasOwnProperty.call(flags, key));
 }
 
+function ensureRuntimeSupported(config, overrides = {}) {
+  if (config.MULTIVERSE_RUNTIME_MODE === "native") {
+    const resolved = resolveNativeBinary(overrides);
+    if (!resolved.ok) throw new Error(nativeRuntimeUnavailableMessage(resolved.message));
+  }
+}
+
+function nativeRuntimeUnavailableMessage(detail = "") {
+  return `Native + Remote Database runtime is not available in this package yet. Use Docker Compose mode for now, or install a packaged multiverse-api binary. ${detail}`.trim();
+}
+
 function normalizeNeo4jMode(value) {
   if (value !== "managed" && value !== "external") {
     throw new Error("Use --neo4j-mode managed|external.");
@@ -801,6 +1104,33 @@ function normalizeNeo4jMode(value) {
   return value;
 }
 
+function normalizeRuntimeMode(value) {
+  if (value === "non-docker") return "native";
+  if (value !== "docker" && value !== "native") {
+    throw new Error("Use --runtime docker|native.");
+  }
+  return value;
+}
+
+function normalizeDbMode(value) {
+  if (value !== "local" && value !== "remote") {
+    throw new Error("Use --db-mode local|remote.");
+  }
+  return value;
+}
+
+function legacyNeo4jModeToDbMode(value) {
+  if (!value) return "";
+  return normalizeNeo4jMode(value) === "managed" ? "local" : "remote";
+}
+
+function yesNoOptions() {
+  return [
+    { name: "No", value: "no" },
+    { name: "Yes", value: "yes" }
+  ];
+}
+
 function quoteEnv(value) {
   const stringValue = String(value);
   return /^[A-Za-z0-9_./:@-]*$/.test(stringValue) ? stringValue : JSON.stringify(stringValue);
@@ -848,16 +1178,59 @@ async function prompt(rl, label, defaultValue) {
   return answer.trim() || defaultValue || "";
 }
 
-async function promptMenu(rl, label, options, defaultValue) {
-  const stdin = process.stdin;
-  const stdout = process.stdout;
+async function promptSecret(rl, label, currentValue = "", options = {}) {
+  for (;;) {
+    const suffix = currentValue ? ` [${colors.cyan}configured, press Enter to keep${colors.reset}]` : "";
+    const answer = await rl.question(`${colors.bold}${colors.white}? ${label}${colors.reset}${suffix}: `);
+    const trimmed = answer.trim();
+    if (trimmed) return trimmed;
+    if (currentValue) return currentValue;
+    if (!options.required) return "";
+    console.log(`${colors.yellow}${label} is required.${colors.reset}`);
+  }
+}
+
+async function promptRequired(rl, label) {
+  for (;;) {
+    const answer = await prompt(rl, label, "");
+    if (answer.trim()) return answer.trim();
+    console.log(`${colors.yellow}${label} is required.${colors.reset}`);
+  }
+}
+
+function showSetupSummary(config, envPath, io) {
+  console.clear();
+  io.log(`${colors.cyan}==================================================${colors.reset}`);
+  io.log(`${colors.bold}${colors.cyan}          Review Multiverse Setup${colors.reset}`);
+  io.log(`${colors.cyan}==================================================${colors.reset}`);
+  io.log(`Config: ${colors.cyan}${envPath}${colors.reset}`);
+  io.log(`Runtime: ${colors.cyan}${config.MULTIVERSE_RUNTIME_MODE}${colors.reset}`);
+  io.log(`Database mode: ${colors.cyan}${config.MULTIVERSE_DB_MODE}${colors.reset}`);
+  io.log(`Neo4j URI: ${colors.cyan}${config.MULTIVERSE_NEO4J_URI || "<not set>"}${colors.reset}`);
+  io.log(`Neo4j user: ${colors.cyan}${config.MULTIVERSE_NEO4J_USER || "<not set>"}${colors.reset}`);
+  io.log(`Neo4j password: ${colors.cyan}${config.MULTIVERSE_NEO4J_PASSWORD ? "<configured>" : "<missing>"}${colors.reset}`);
+  io.log(`Workspace path: ${colors.cyan}${config.MULTIVERSE_HOST_WORKSPACE_DIR}${colors.reset}`);
+  io.log(`Admin user: ${colors.cyan}${config.MULTIVERSE_ADMIN_USER}${colors.reset}`);
+  io.log(`Admin password: ${colors.cyan}${config.MULTIVERSE_ADMIN_PASSWORD ? "<configured>" : "<missing>"}${colors.reset}`);
+  io.log(`AI provider: ${colors.cyan}${config.MULTIVERSE_ENABLE_AI === "true" ? "enabled" : "disabled"}${colors.reset}`);
+  io.log(`Embeddings: ${colors.cyan}${config.MULTIVERSE_ENABLE_EMBEDDINGS === "true" ? "enabled" : "disabled"}${colors.reset}`);
+  io.log("");
+}
+
+async function promptMenu(rl, label, options, defaultValue, overrides = {}) {
+  const stdin = overrides.stdin || process.stdin;
+  const stdout = overrides.stdout || process.stdout;
+  if (!stdin.isTTY || !stdout.isTTY) {
+    const defaultOption = options.find((option) => option.name === defaultValue || option.value === defaultValue) || options[0];
+    const answer = await prompt(rl, label, defaultOption.value);
+    return options.find((option) => option.value === answer || option.name === answer)?.value || defaultOption.value;
+  }
   
   rl.pause(); // Pause readline interface to prevent double echoing
   
   readlineModule.emitKeypressEvents(stdin);
-  if (stdin.isTTY) {
-    stdin.setRawMode(true);
-  }
+  stdin.resume();
+  stdin.setRawMode(true);
   
   let activeIdx = options.findIndex(o => o.name === defaultValue || o.value === defaultValue);
   if (activeIdx === -1) activeIdx = 0;
@@ -867,7 +1240,7 @@ async function promptMenu(rl, label, options, defaultValue) {
     stdout.write(`${colors.bold}${colors.magenta}? ${label}${colors.reset}\n`);
     for (let i = 0; i < options.length; i++) {
       if (i === activeIdx) {
-        stdout.write(`  ${colors.cyan}❯ ${options[i].name}${colors.reset}\n`);
+        stdout.write(`  ${colors.cyan}> ${options[i].name}${colors.reset}\n`);
       } else {
         stdout.write(`    ${options[i].name}\n`);
       }
@@ -900,9 +1273,7 @@ async function promptMenu(rl, label, options, defaultValue) {
       } else if (key && (key.name === "return" || key.name === "enter")) {
         stdout.write("\x1B[?25h"); // Show cursor
         stdin.removeListener("keypress", onKeypress);
-        if (stdin.isTTY) {
-          stdin.setRawMode(false);
-        }
+        stdin.setRawMode(false);
         stdout.write(`\n`);
         rl.resume(); // Resume readline interface
         resolve(options[activeIdx].value);

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "git-multiverse",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Clone-free Multiverse Docker Hub launcher.",
   "type": "module",
   "bin": {
     "git-multiverse": "./bin/git-multiverse.mjs"
   },
   "scripts": {
+    "build:native": "node ./scripts/build-native.mjs",
     "test": "node --test",
     "doctor": "node ./bin/git-multiverse.mjs doctor"
   },

package/test/git-multiverse.test.mjs

@@ -1,179 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-import {
-  buildMcpClientConfig,
-  cmdDoctor,
-  cmdMcpSetup,
-  cmdSetup,
-  createSetupConfig,
-  getStatePaths,
-  parseEnvFile,
-  renderComposeFile,
-  renderMcpClientConfig,
-  writeStateFiles
-} from "../lib/app.mjs";
-
-test("writeStateFiles writes env mode 0600 with expected keys", () => {
-  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "git-multiverse-home-"));
-  const config = createSetupConfig({
-    workspace: "/tmp/repos",
-    "admin-password": "admin-secret",
-    "neo4j-password": "neo4j-secret",
-    "image-tag": "test"
-  }, { homeDir });
-
-  const paths = writeStateFiles(config, { homeDir });
-  const envText = fs.readFileSync(paths.envPath, "utf8");
-  const mode = fs.statSync(paths.envPath).mode & 0o777;
-
-  if (os.platform() !== "win32") {
-    assert.equal(mode, 0o600);
-  }
-  assert.match(envText, /^MULTIVERSE_ADMIN_PASSWORD=admin-secret/m);
-  assert.match(envText, /^MULTIVERSE_MCP_ALLOW_ANONYMOUS=false/m);
-  assert.match(envText, /^MULTIVERSE_IMAGE_TAG=test/m);
-});
-
-test("createSetupConfig correctly pre-fills and respects existingConfig", () => {
-  const existing = {
-    MULTIVERSE_HOST_WORKSPACE_DIR: "/my/previous/workspace",
-    MULTIVERSE_NEO4J_MODE: "external",
-    MULTIVERSE_ADMIN_PASSWORD: "my-old-pass",
-    MULTIVERSE_NEO4J_PASSWORD: "neo-old-pass",
-    MULTIVERSE_ENABLE_AI: "true",
-    NINEROUTER_API_BASE_URL: "https://api.custom-ai.com/v1",
-    NINEROUTER_MODEL_NAME: "custom-gpt-5",
-    NINEROUTER_API_KEY: "custom-key",
-    MULTIVERSE_ENABLE_EMBEDDINGS: "true",
-    EMBEDDING_API_BASE_URL: "https://api.custom-embed.com/v1",
-    EMBEDDING_MODEL_NAME: "custom-embed-3",
-    EMBEDDING_API_KEY: "embed-key",
-    MULTIVERSE_NEO4J_URI: "neo4j://old-uri:7687",
-    MULTIVERSE_NEO4J_USER: "old-user"
-  };
-
-  const config = createSetupConfig({}, {}, existing);
-
-  assert.equal(config.MULTIVERSE_HOST_WORKSPACE_DIR, "/my/previous/workspace");
-  assert.equal(config.MULTIVERSE_NEO4J_MODE, "external");
-  assert.equal(config.MULTIVERSE_ADMIN_PASSWORD, "my-old-pass");
-  assert.equal(config.MULTIVERSE_NEO4J_PASSWORD, "neo-old-pass");
-  assert.equal(config.MULTIVERSE_ENABLE_AI, "true");
-  assert.equal(config.NINEROUTER_API_BASE_URL, "https://api.custom-ai.com/v1");
-  assert.equal(config.NINEROUTER_MODEL_NAME, "custom-gpt-5");
-  assert.equal(config.NINEROUTER_API_KEY, "custom-key");
-  assert.equal(config.MULTIVERSE_ENABLE_EMBEDDINGS, "true");
-  assert.equal(config.EMBEDDING_API_BASE_URL, "https://api.custom-embed.com/v1");
-  assert.equal(config.EMBEDDING_MODEL_NAME, "custom-embed-3");
-  assert.equal(config.EMBEDDING_API_KEY, "embed-key");
-  assert.equal(config.MULTIVERSE_NEO4J_URI, "neo4j://old-uri:7687");
-  assert.equal(config.MULTIVERSE_NEO4J_USER, "old-user");
-});
-
-test("renderComposeFile references Docker Hub images and localhost binds", () => {
-  const config = createSetupConfig({
-    workspace: "/tmp/repos",
-    "admin-password": "admin-secret",
-    "neo4j-password": "neo4j-secret"
-  });
-
-  const compose = renderComposeFile(config);
-  assert.match(compose, /image: anhdt5\/git-multiverse:latest/);
-  assert.match(compose, /image: neo4j:5\.26-community/);
-  assert.match(compose, /127\.0\.0\.1:18081:18081/);
-  assert.match(compose, /127\.0\.0\.1:7474:7474/);
-  assert.match(compose, /127\.0\.0\.1:7687:7687/);
-});
-
-test("non-interactive setup produces deterministic files in temp HOME", async () => {
-  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "git-multiverse-home-"));
-  const output = [];
-
-  await cmdSetup({
-    "non-interactive": true,
-    "neo4j-mode": "external",
-    workspace: "/tmp/repos",
-    "admin-password": "admin-secret",
-    "neo4j-uri": "neo4j://db.example:7687",
-    "neo4j-user": "neo4j",
-    "neo4j-password": "neo4j-secret",
-    "neo4j-database": "neo4j",
-    "image-tag": "1.2.3"
-  }, { homeDir, log: (line) => output.push(line) });
-
-  const { envPath, composePath } = getStatePaths({ homeDir });
-  const envText = fs.readFileSync(envPath, "utf8");
-  const composeText = fs.readFileSync(composePath, "utf8");
-  const parsed = parseEnvFile(envText);
-
-  assert.equal(parsed.MULTIVERSE_NEO4J_MODE, "external");
-  assert.equal(parsed.MULTIVERSE_NEO4J_URI, "neo4j://db.example:7687");
-  assert.match(composeText, /image: anhdt5\/git-multiverse:1\.2\.3/);
-  assert.doesNotMatch(composeText, /neo4j:5\.26-community/);
-  assert.ok(output.some((line) => String(line).includes(envPath)));
-});
-
-test("doctor reports missing docker gracefully", async () => {
-  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "git-multiverse-home-"));
-  const config = createSetupConfig({
-    workspace: "/tmp/repos",
-    "admin-password": "admin-secret",
-    "neo4j-password": "neo4j-secret"
-  }, { homeDir });
-  writeStateFiles(config, { homeDir });
-
-  const lines = [];
-  let exitCode = 0;
-  await cmdDoctor({
-    homeDir,
-    log: (line) => lines.push(line),
-    exit: (code) => {
-      exitCode = code;
-    },
-    spawnSyncImpl: () => ({ status: 1, stderr: "not found" })
-  });
-
-  assert.equal(exitCode, 1);
-  assert.ok(lines.some((line) => String(line).includes("FAIL docker: missing docker CLI")));
-  assert.ok(lines.some((line) => String(line).includes("FAIL docker compose: missing docker compose plugin")));
-});
-
-test("buildMcpClientConfig targets the /mcp endpoint with a bearer header", () => {
-  const cursor = buildMcpClientConfig("cursor", "http://127.0.0.1:18081/", "key-123");
-  assert.equal(cursor.kind, "json");
-  assert.equal(cursor.config.mcpServers.multiverse.url, "http://127.0.0.1:18081/mcp");
-  assert.equal(cursor.config.mcpServers.multiverse.headers.Authorization, "Bearer key-123");
-
-  const opencode = buildMcpClientConfig("opencode", "http://127.0.0.1:18081", "key-123");
-  assert.equal(opencode.config.mcp.multiverse.type, "remote");
-  assert.equal(opencode.config.mcp.multiverse.url, "http://127.0.0.1:18081/mcp");
-
-  const claude = buildMcpClientConfig("claude", "http://127.0.0.1:18081", "key-123");
-  assert.equal(claude.kind, "shell");
-  assert.match(claude.command, /claude mcp add --transport http multiverse http:\/\/127\.0\.0\.1:18081\/mcp/);
-  assert.match(claude.command, /Bearer key-123/);
-
-  const codex = buildMcpClientConfig("codex", "http://127.0.0.1:18081", "key-123");
-  assert.equal(codex.kind, "toml");
-  assert.match(codex.config, /\[mcp_servers\.multiverse\]/);
-});
-
-test("buildMcpClientConfig uses placeholder when key is missing and rejects unknown editors", () => {
-  const snippet = renderMcpClientConfig("windsurf", "http://127.0.0.1:18081", "");
-  assert.match(snippet, /Bearer <MCP_KEY>/);
-  assert.throws(() => buildMcpClientConfig("emacs", "http://127.0.0.1:18081", "k"), /Unknown editor/);
-});
-
-test("cmdMcpSetup prints a snippet for every supported editor", async () => {
-  const lines = [];
-  await cmdMcpSetup({ "mcp-key": "key-123" }, { log: (line) => lines.push(line) });
-  const text = lines.join("\n");
-  for (const editor of ["claude", "cursor", "codex", "opencode", "windsurf"]) {
-    assert.ok(text.includes(`# ${editor}`), `expected snippet for ${editor}`);
-  }
-  assert.ok(text.includes("Bearer key-123"));
-});