git-multiverse 0.1.1

package/README.md

@@ -0,0 +1,51 @@
+# git-multiverse
+
+Clone-free launcher for Multiverse.
+
+## Install
+
+```bash
+npm install -g git-multiverse
+```
+
+## Commands
+
+```bash
+git-multiverse setup
+git-multiverse up
+git-multiverse down
+git-multiverse status
+git-multiverse doctor
+```
+
+## State files
+
+- `~/.git-multiverse/` (mode `0700`)
+- `~/.git-multiverse/.env` (mode `0600`)
+- `~/.git-multiverse/docker-compose.yaml`
+
+## Setup flow
+
+`git-multiverse setup` writes a standalone compose file that uses:
+
+- `anhdt5/git-multiverse:<tag>`
+- `neo4j:5.26-community` when using managed Neo4j
+
+Security defaults:
+
+- host ports bind to `127.0.0.1`
+- `MULTIVERSE_MCP_ALLOW_ANONYMOUS=false`
+- random admin and Neo4j passwords by default
+- secrets stay only in `~/.git-multiverse/.env`
+
+## Non-interactive example
+
+```bash
+git-multiverse setup \
+  --non-interactive \
+  --neo4j-mode managed \
+  --workspace /workspace/repos \
+  --admin-password 'replace-me' \
+  --neo4j-password 'replace-me-too' \
+  --image-tag latest
+```

package/bin/git-multiverse.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from "../lib/app.mjs";
+
+await main(process.argv.slice(2));

package/lib/app.mjs

@@ -0,0 +1,948 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+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";
+
+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";
+
+export const colors = {
+  reset: "\x1b[0m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  magenta: "\x1b[35m",
+  white: "\x1b[37m",
+  bold: "\x1b[1m",
+  blue: "\x1b[34m"
+};
+
+const SECRET_KEYS = new Set([
+  "MULTIVERSE_ADMIN_PASSWORD",
+  "MULTIVERSE_NEO4J_PASSWORD",
+  "NINEROUTER_API_KEY",
+  "EMBEDDING_API_KEY"
+]);
+
+export async function main(argv, overrides = {}) {
+  const io = createIO(overrides);
+  try {
+    const { command, flags } = parseArgs(argv);
+    switch (command) {
+      case "setup":
+        await cmdSetup(flags, overrides, io);
+        break;
+      case "up":
+        await cmdUp(overrides, io);
+        break;
+      case "down":
+        await cmdDown(overrides, io);
+        break;
+      case "status":
+        await cmdStatus(overrides, io);
+        break;
+      case "doctor":
+        await cmdDoctor(overrides, io);
+        break;
+      case "mcp-setup":
+        await cmdMcpSetup(flags, overrides, io);
+        break;
+      case "help":
+      case "":
+      case undefined:
+        printHelp(io.log);
+        break;
+      default:
+        throw new Error(`Unknown command: ${command}`);
+    }
+  } catch (error) {
+    io.error(`error: ${error.message}`);
+    if (typeof overrides.exit === "function") {
+      overrides.exit(1);
+      return;
+    }
+    process.exitCode = 1;
+  }
+}
+
+export function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) {
+      positionals.push(token);
+      continue;
+    }
+    const stripped = token.slice(2);
+    if (stripped.includes("=")) {
+      const [key, value] = stripped.split(/=(.*)/s);
+      flags[key] = value;
+      continue;
+    }
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      flags[stripped] = true;
+      continue;
+    }
+    flags[stripped] = next;
+    index += 1;
+  }
+  return { command: positionals[0], flags };
+}
+
+export function getStatePaths(overrides = {}) {
+  const homeDir = overrides.homeDir || os.homedir();
+  const stateDir = path.join(homeDir, STATE_DIR_NAME);
+  return {
+    homeDir,
+    stateDir,
+    envPath: path.join(stateDir, ".env"),
+    composePath: path.join(stateDir, "docker-compose.yaml")
+  };
+}
+
+export function createSetupConfig(flags = {}, overrides = {}, existingConfig = {}) {
+  const env = overrides.env || process.env;
+  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 adminPassword = stringFlag(flags["admin-password"]) || existingConfig.MULTIVERSE_ADMIN_PASSWORD;
+  const neo4jPassword = stringFlag(flags["neo4j-password"]) || existingConfig.MULTIVERSE_NEO4J_PASSWORD;
+  const imageTag = stringFlag(flags["image-tag"]) || existingConfig.MULTIVERSE_IMAGE_TAG || env.GIT_MULTIVERSE_IMAGE_TAG || DEFAULT_IMAGE_TAG;
+  
+  const enableAiFlag = flags["enable-ai"] !== undefined ? (toBool(flags["enable-ai"]) ? "true" : "false") : null;
+  const enableEmbeddingsFlag = flags["enable-embeddings"] !== undefined ? (toBool(flags["enable-embeddings"]) ? "true" : "false") : null;
+
+  const config = {
+    MULTIVERSE_HOST: "0.0.0.0",
+    MULTIVERSE_PORT: DEFAULT_PORT,
+    MULTIVERSE_API_PORT: DEFAULT_PORT,
+    MULTIVERSE_ADMIN_USER: "admin",
+    MULTIVERSE_ADMIN_PASSWORD: adminPassword || "123456",
+    MULTIVERSE_MCP_ALLOW_ANONYMOUS: "false",
+    MULTIVERSE_WORKSPACE_DIR: "/workspace/repos",
+    MULTIVERSE_HOST_WORKSPACE_DIR: workspace,
+    DOCS_STORAGE_PATH: "/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 || "",
+    NINEROUTER_API_KEY: stringFlag(flags["llm-key"]) || existingConfig.NINEROUTER_API_KEY || "",
+    MULTIVERSE_ENABLE_EMBEDDINGS: enableEmbeddingsFlag !== null ? enableEmbeddingsFlag : (existingConfig.MULTIVERSE_ENABLE_EMBEDDINGS || "false"),
+    EMBEDDING_API_BASE_URL: cleanBaseUrl(stringFlag(flags["embedding-base-url"]), "embedding") || existingConfig.EMBEDDING_API_BASE_URL || "",
+    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_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") {
+    config.MULTIVERSE_NEO4J_URI = "neo4j://neo4j:7687";
+    config.MULTIVERSE_NEO4J_PASSWORD = neo4jPassword || existingConfig.MULTIVERSE_NEO4J_PASSWORD || "123456";
+  } 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"]) });
+  return config;
+}
+
+export function validateConfig(config, options = {}) {
+  if (!path.isAbsolute(config.MULTIVERSE_HOST_WORKSPACE_DIR)) {
+    throw new Error("Workspace path must be absolute.");
+  }
+  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 (config.MULTIVERSE_NEO4J_MODE === "managed") {
+    if (!config.MULTIVERSE_NEO4J_PASSWORD) {
+      throw new Error("Neo4j password is required for managed mode.");
+    }
+    return;
+  }
+  if (!config.MULTIVERSE_NEO4J_URI) {
+    throw new Error("MULTIVERSE_NEO4J_URI is required for external mode.");
+  }
+  if (!config.MULTIVERSE_NEO4J_USER) {
+    throw new Error("MULTIVERSE_NEO4J_USER is required for external mode.");
+  }
+  if (!config.MULTIVERSE_NEO4J_PASSWORD && options.nonInteractive) {
+    throw new Error("MULTIVERSE_NEO4J_PASSWORD is required for external mode.");
+  }
+}
+
+export function renderEnvFile(config) {
+  const orderedKeys = [
+    "MULTIVERSE_HOST",
+    "MULTIVERSE_PORT",
+    "MULTIVERSE_API_PORT",
+    "MULTIVERSE_ADMIN_USER",
+    "MULTIVERSE_ADMIN_PASSWORD",
+    "MULTIVERSE_MCP_ALLOW_ANONYMOUS",
+    "MULTIVERSE_WORKSPACE_DIR",
+    "MULTIVERSE_HOST_WORKSPACE_DIR",
+    "DOCS_STORAGE_PATH",
+    "MULTIVERSE_ENABLE_AI",
+    "NINEROUTER_API_BASE_URL",
+    "NINEROUTER_MODEL_NAME",
+    "NINEROUTER_API_KEY",
+    "MULTIVERSE_ENABLE_EMBEDDINGS",
+    "EMBEDDING_API_BASE_URL",
+    "EMBEDDING_MODEL_NAME",
+    "EMBEDDING_API_KEY",
+    "MULTIVERSE_IMAGE_TAG",
+    "MULTIVERSE_NEO4J_MODE",
+    "MULTIVERSE_NEO4J_URI",
+    "MULTIVERSE_NEO4J_USER",
+    "MULTIVERSE_NEO4J_PASSWORD",
+    "MULTIVERSE_NEO4J_DATABASE"
+  ];
+  return [
+    "# Generated by git-multiverse setup",
+    "# Local-only secrets file. Do not commit.",
+    ...orderedKeys.map((key) => `${key}=${quoteEnv(config[key] ?? "")}`),
+    ""
+  ].join("\n");
+}
+
+export function renderComposeFile(config) {
+  const lines = [
+    "services:",
+    "  multiverse:",
+    `    image: ${APP_IMAGE}:${config.MULTIVERSE_IMAGE_TAG}`,
+    "    restart: unless-stopped",
+    "    env_file:",
+    "      - ./.env",
+    "    ports:",
+    '      - "127.0.0.1:18081:18081"',
+    "    volumes:",
+    '      - ${MULTIVERSE_HOST_WORKSPACE_DIR}:/workspace/repos',
+    '      - ./docs:/workspace/docs',
+    "  ",
+  ];
+
+  if (config.MULTIVERSE_NEO4J_MODE === "managed") {
+    lines.push("    depends_on:", "      - neo4j");
+  }
+
+  if (config.MULTIVERSE_NEO4J_MODE === "managed") {
+    lines.push(
+      "  neo4j:",
+      `    image: ${NEO4J_IMAGE}`,
+      "    restart: unless-stopped",
+      "    environment:",
+      '      NEO4J_AUTH: neo4j/${MULTIVERSE_NEO4J_PASSWORD}',
+      '      NEO4J_dbms_security_auth__minimum__password__length: "6"',
+      "    ports:",
+      '      - "127.0.0.1:7474:7474"',
+      '      - "127.0.0.1:7687:7687"',
+      "    volumes:",
+      '      - ./neo4j-data:/data'
+    );
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+export function writeStateFiles(config, overrides = {}) {
+  const fsModule = overrides.fsModule || fs;
+  const paths = getStatePaths(overrides);
+  fsModule.mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 });
+  fsModule.chmodSync(paths.stateDir, 0o700);
+  fsModule.writeFileSync(paths.envPath, renderEnvFile(config), { mode: 0o600 });
+  fsModule.chmodSync(paths.envPath, 0o600);
+  fsModule.writeFileSync(paths.composePath, renderComposeFile(config), "utf8");
+  return paths;
+}
+
+export function loadConfig(overrides = {}) {
+  const fsModule = overrides.fsModule || fs;
+  const { envPath } = getStatePaths(overrides);
+  if (!fsModule.existsSync(envPath)) {
+    throw new Error(`missing ${envPath}. Run: git-multiverse setup`);
+  }
+  return parseEnvFile(fsModule.readFileSync(envPath, "utf8"));
+}
+
+export function parseEnvFile(source) {
+  const result = {};
+  for (const line of source.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const index = trimmed.indexOf("=");
+    if (index < 1) continue;
+    const key = trimmed.slice(0, index);
+    const raw = trimmed.slice(index + 1);
+    result[key] = unquoteEnv(raw);
+  }
+  return result;
+}
+
+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 config = createSetupConfig(flags, overrides, existingConfig);
+  const interactive = !nonInteractive && isInteractive(overrides);
+  if (interactive) {
+    await runWizard(config, flags, overrides, io);
+    validateConfig(config);
+  }
+  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(`  - 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);
+  }
+}
+
+export async function cmdUp(overrides = {}, io = createIO(overrides)) {
+  const paths = getStatePaths(overrides);
+  ensureDockerAvailable(overrides);
+  runDockerCompose(["up", "-d"], overrides, io, paths);
+}
+
+export async function cmdDown(overrides = {}, io = createIO(overrides)) {
+  const paths = getStatePaths(overrides);
+  ensureDockerAvailable(overrides);
+  runDockerCompose(["down"], overrides, io, paths);
+}
+
+export async function cmdStatus(overrides = {}, io = createIO(overrides)) {
+  const paths = getStatePaths(overrides);
+  ensureDockerAvailable(overrides);
+  runDockerCompose(["ps"], overrides, io, paths);
+  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) {
+    if (typeof overrides.exit === "function") overrides.exit(1);
+    else process.exitCode = 1;
+  }
+}
+
+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;
+
+  let config = null;
+  if (envExists) {
+    config = parseEnvFile(fsModule.readFileSync(paths.envPath, "utf8"));
+    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, "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");
+    printDoctor(io, "admin password", adminOk, adminOk ? "custom password set" : "default password detected");
+    failed ||= !adminOk;
+  }
+
+  for (const port of [18081, 7474, 7687]) {
+    const status = await checkPortStatus(port, overrides.netModule || net);
+    printDoctor(io, `port ${port}`, true, status);
+  }
+
+  if (failed) {
+    if (typeof overrides.exit === "function") overrides.exit(1);
+    else process.exitCode = 1;
+  }
+}
+
+// ── MCP client setup ──────────────────────────────────────────────────────────
+
+const MCP_EDITORS = ["claude", "cursor", "codex", "opencode", "windsurf"];
+
+// buildMcpClientConfig returns the editor-specific MCP client configuration for
+// connecting to a running git-multiverse server. The server exposes Streamable
+// HTTP MCP at <baseUrl>/mcp and authenticates with a Bearer key (created in
+// Settings → MCP Access Keys or POST /api/settings/mcp-keys). Pure function: no
+// I/O, so it is straightforward to unit-test and stays identical across editors
+// that share a schema.
+export function buildMcpClientConfig(editor, baseUrl, mcpKey) {
+  const url = `${String(baseUrl).replace(/\/+$/, "")}/mcp`;
+  const headerValue = mcpKey ? `Bearer ${mcpKey}` : "Bearer <MCP_KEY>";
+  switch (editor) {
+    case "claude":
+      // claude mcp add expects an http transport with a header flag.
+      return {
+        kind: "shell",
+        command: `claude mcp add --transport http multiverse ${url} --header ${JSON.stringify(`Authorization: ${headerValue}`)}`
+      };
+    case "cursor":
+    case "windsurf":
+      // Cursor (~/.cursor/mcp.json) and Windsurf share the same JSON schema.
+      return {
+        kind: "json",
+        config: {
+          mcpServers: {
+            multiverse: {
+              url,
+              headers: { Authorization: headerValue }
+            }
+          }
+        }
+      };
+    case "opencode":
+      // opencode uses a "remote" MCP type with a headers map.
+      return {
+        kind: "json",
+        config: {
+          mcp: {
+            multiverse: {
+              type: "remote",
+              url,
+              headers: { Authorization: headerValue }
+            }
+          }
+        }
+      };
+    case "codex":
+      // Codex config.toml uses [mcp_servers.<name>] with a url + bearer token.
+      return {
+        kind: "toml",
+        config: `[mcp_servers.multiverse]\nurl = ${JSON.stringify(url)}\nbearer_token = ${JSON.stringify(mcpKey || "<MCP_KEY>")}\n`
+      };
+    default:
+      throw new Error(`Unknown editor: ${editor}. Supported: ${MCP_EDITORS.join(", ")}`);
+  }
+}
+
+// renderMcpClientConfig turns a buildMcpClientConfig result into a printable
+// snippet a user can copy into their editor configuration.
+export function renderMcpClientConfig(editor, baseUrl, mcpKey) {
+  const result = buildMcpClientConfig(editor, baseUrl, mcpKey);
+  switch (result.kind) {
+    case "shell":
+      return result.command;
+    case "toml":
+      return result.config;
+    case "json":
+    default:
+      return JSON.stringify(result.config, null, 2);
+  }
+}
+
+export async function cmdMcpSetup(flags, overrides = {}, io = createIO(overrides)) {
+  const baseUrl = stringFlag(flags["base-url"]) || `http://127.0.0.1:${DEFAULT_PORT}`;
+  const mcpKey = stringFlag(flags["mcp-key"]);
+  const requested = stringFlag(flags.editor);
+  const editors = requested ? [requested] : MCP_EDITORS;
+
+  if (!mcpKey) {
+    io.log("No --mcp-key provided. Create one in the web UI (Settings → MCP Access Keys)");
+    io.log("or via POST /api/settings/mcp-keys, then re-run with --mcp-key <key>.");
+    io.log("Showing config templates with a <MCP_KEY> placeholder:\n");
+  }
+
+  for (const editor of editors) {
+    io.log(`# ${editor}`);
+    io.log(renderMcpClientConfig(editor, baseUrl, mcpKey));
+    io.log("");
+  }
+}
+
+export function ensureDockerAvailable(overrides = {}) {
+  const docker = checkCommand(["docker", "--version"], overrides);
+  if (!docker.ok) throw new Error("Docker CLI not found.");
+  const compose = checkCommand(["docker", "compose", "version"], overrides);
+  if (!compose.ok) throw new Error("Docker Compose plugin not found.");
+}
+
+export function runDockerCompose(args, overrides = {}, io = createIO(overrides), paths = getStatePaths(overrides)) {
+  const config = loadConfig(overrides);
+  const commandArgs = [
+    "compose",
+    "--env-file",
+    paths.envPath,
+    "-f",
+    paths.composePath,
+    ...args
+  ];
+  const result = execCommand(["docker", ...commandArgs], overrides, { inherit: true });
+  if (!result.ok) {
+    throw new Error(`docker compose ${args.join(" ")} failed`);
+  }
+  io.log(`compose ${args.join(" ")} ok (${config.MULTIVERSE_NEO4J_MODE})`);
+}
+
+export function checkCommand(command, overrides = {}) {
+  const result = execCommand(command, overrides, { inherit: false });
+  return { ok: result.ok, output: result.output };
+}
+
+export function execCommand(command, overrides = {}, options = {}) {
+  const runner = overrides.spawnSyncImpl || spawnSync;
+  const [file, ...args] = command;
+  const result = runner(file, args, {
+    encoding: "utf8",
+    stdio: options.inherit ? "inherit" : "pipe"
+  });
+  const output = String(result?.stdout || result?.stderr || result?.error?.message || "").trim();
+  return { ok: !result?.error && result?.status === 0, output };
+}
+
+export async function checkHealth(url, fetchImpl = globalThis.fetch) {
+  if (typeof fetchImpl !== "function") {
+    return { ok: false, message: "fetch unavailable" };
+  }
+  try {
+    const response = await fetchImpl(url);
+    return response.ok ? { ok: true, message: `${response.status} ${response.statusText}` } : { ok: false, message: `${response.status} ${response.statusText}` };
+  } catch (error) {
+    return { ok: false, message: error.message };
+  }
+}
+
+export async function checkPortStatus(port, netModule = net) {
+  return new Promise((resolve) => {
+    const server = netModule.createServer();
+    server.once("error", () => resolve("in use"));
+    server.once("listening", () => {
+      server.close(() => resolve("available"));
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+function showPageHeader(pageNum, title, io) {
+  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.cyan}==================================================${colors.reset}`);
+  io.log(`${colors.yellow}ℹ Press Enter to keep 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 });
+  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));
+    }
+    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);
+    if (!flags["admin-password"]) {
+      config.MULTIVERSE_ADMIN_PASSWORD = await prompt(rl, "Admin password", config.MULTIVERSE_ADMIN_PASSWORD);
+    }
+    if (config.MULTIVERSE_NEO4J_MODE === "managed") {
+      if (!flags["neo4j-password"]) {
+        config.MULTIVERSE_NEO4J_PASSWORD = await prompt(rl, "Neo4j password", config.MULTIVERSE_NEO4J_PASSWORD);
+      }
+    } 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-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);
+    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)) {
+        config.MULTIVERSE_ENABLE_AI = "true";
+        io.log("");
+        const providerOptions = [
+          { name: "OpenAI", value: "openai" },
+          { name: "DeepSeek", value: "deepseek" },
+          { name: "OpenRouter", value: "openrouter" },
+          { name: "Google / Gemini", value: "google" },
+          { name: "Anthropic / Claude", value: "claude" },
+          { name: "Amazon Bedrock", value: "bedrock" },
+          { name: "Custom (Enter URL & Model manually)", value: "custom" }
+        ];
+        
+        let defaultProvider = "openai";
+        const currentUrl = config.NINEROUTER_API_BASE_URL;
+        if (currentUrl) {
+          if (currentUrl.includes("api.openai.com")) defaultProvider = "openai";
+          else if (currentUrl.includes("api.deepseek.com")) defaultProvider = "deepseek";
+          else if (currentUrl.includes("openrouter.ai")) defaultProvider = "openrouter";
+          else if (currentUrl.includes("generativelanguage.googleapis.com")) defaultProvider = "google";
+          else if (currentUrl.includes("api.anthropic.com")) defaultProvider = "claude";
+          else if (currentUrl.includes("amazonaws.com")) defaultProvider = "bedrock";
+          else defaultProvider = "custom";
+        }
+
+        const provider = await promptMenu(rl, "Select AI Provider (LLM):", providerOptions, defaultProvider);
+        io.log("");
+        
+        let baseUrl = "";
+        let presetModel = "";
+        
+        if (provider === "openai") {
+          baseUrl = "https://api.openai.com/v1";
+          presetModel = "gpt-4o";
+        } else if (provider === "deepseek") {
+          baseUrl = "https://api.deepseek.com";
+          presetModel = "deepseek-chat";
+        } else if (provider === "openrouter") {
+          baseUrl = "https://openrouter.ai/api/v1";
+          presetModel = "google/gemini-2.5-flash";
+        } else if (provider === "google") {
+          baseUrl = "https://generativelanguage.googleapis.com/v1beta/openai";
+          presetModel = "gemini-1.5-flash";
+        } else if (provider === "claude") {
+          baseUrl = "https://api.anthropic.com/v1";
+          presetModel = "claude-3-5-sonnet-20241022";
+        } else if (provider === "bedrock") {
+          baseUrl = "https://bedrock-runtime.us-east-1.amazonaws.com";
+          presetModel = "anthropic.claude-3-5-sonnet-20241022-v2:0";
+        }
+        
+        let defaultModel = config.NINEROUTER_MODEL_NAME;
+        if (provider !== "custom") {
+          const deducedPrevProvider = currentUrl ? defaultProvider : null;
+          if (provider !== deducedPrevProvider || !defaultModel) {
+            defaultModel = presetModel;
+          }
+        }
+
+        if (provider === "custom") {
+          const rawUrl = await prompt(rl, "LLM base URL", config.NINEROUTER_API_BASE_URL);
+          baseUrl = cleanBaseUrl(rawUrl, "llm");
+          if (baseUrl !== rawUrl.trim() && rawUrl.trim() !== "") {
+            io.log(`${colors.yellow}ℹ Auto-normalized URL to: ${baseUrl}${colors.reset}`);
+          }
+          if (!defaultModel) {
+            defaultModel = config.NINEROUTER_MODEL_NAME;
+          }
+        } else {
+          io.log(`${colors.green}ℹ Auto-configured URL: ${baseUrl}${colors.reset}`);
+        }
+        
+        const modelName = await prompt(rl, "LLM model", defaultModel);
+        
+        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);
+      } else {
+        config.MULTIVERSE_ENABLE_AI = "false";
+      }
+    }
+
+    // ── Page 4: Vector Embeddings ───────────────────────────────────
+    showPageHeader(4, "Vector Embeddings", io);
+    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)) {
+        config.MULTIVERSE_ENABLE_EMBEDDINGS = "true";
+        io.log("");
+        const embedOptions = [
+          { name: "OpenAI", value: "openai" },
+          { name: "OpenRouter", value: "openrouter" },
+          { name: "Custom (Enter URL & Model manually)", value: "custom" }
+        ];
+        
+        let defaultEmbed = "openai";
+        const currentEmbedUrl = config.EMBEDDING_API_BASE_URL;
+        if (currentEmbedUrl) {
+          if (currentEmbedUrl.includes("api.openai.com")) defaultEmbed = "openai";
+          else if (currentEmbedUrl.includes("openrouter.ai")) defaultEmbed = "openrouter";
+          else defaultEmbed = "custom";
+        }
+
+        const provider = await promptMenu(rl, "Select Vector Embedding Provider:", embedOptions, defaultEmbed);
+        io.log("");
+        
+        let baseUrl = "";
+        let presetModel = "";
+        
+        if (provider === "openai") {
+          baseUrl = "https://api.openai.com/v1";
+          presetModel = "text-embedding-3-small";
+        } else if (provider === "openrouter") {
+          baseUrl = "https://openrouter.ai/api/v1";
+          presetModel = "openai/text-embedding-3-small";
+        }
+        
+        let defaultModel = config.EMBEDDING_MODEL_NAME;
+        if (provider !== "custom") {
+          const deducedPrevProvider = currentEmbedUrl ? defaultEmbed : null;
+          if (provider !== deducedPrevProvider || !defaultModel) {
+            defaultModel = presetModel;
+          }
+        }
+
+        if (provider === "custom") {
+          const rawUrl = await prompt(rl, "Embedding base URL", config.EMBEDDING_API_BASE_URL);
+          baseUrl = cleanBaseUrl(rawUrl, "embedding");
+          if (baseUrl !== rawUrl.trim() && rawUrl.trim() !== "") {
+            io.log(`${colors.yellow}ℹ Auto-normalized URL to: ${baseUrl}${colors.reset}`);
+          }
+          if (!defaultModel) {
+            defaultModel = config.EMBEDDING_MODEL_NAME;
+          }
+        } else {
+          io.log(`${colors.green}ℹ Auto-configured URL: ${baseUrl}${colors.reset}`);
+        }
+        
+        const modelName = await prompt(rl, "Embedding model", defaultModel);
+        
+        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);
+      } else {
+        config.MULTIVERSE_ENABLE_EMBEDDINGS = "false";
+      }
+    }
+
+    // ── Page 5: Docker Image & Finish ────────────────────────────────
+    showPageHeader(5, "Docker Image & Finish", io);
+    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("");
+  } finally {
+    rl.close();
+  }
+}
+
+export function printHelp(log = console.log) {
+  log(`git-multiverse
+
+Commands:
+  git-multiverse setup [--non-interactive] [--neo4j-mode managed|external]
+    [--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 status
+  git-multiverse doctor
+  git-multiverse mcp-setup [--editor claude|cursor|codex|opencode|windsurf]
+    [--base-url <url>] [--mcp-key <key>]`);
+}
+
+function printDoctor(io, label, ok, detail) {
+  io.log(`${ok ? "OK" : "FAIL"} ${label}: ${detail}`);
+}
+
+function createIO(overrides = {}) {
+  return {
+    log: overrides.log || console.log,
+    error: overrides.error || console.error
+  };
+}
+
+function hasAny(flags, keys) {
+  return keys.some((key) => Object.prototype.hasOwnProperty.call(flags, key));
+}
+
+function normalizeNeo4jMode(value) {
+  if (value !== "managed" && value !== "external") {
+    throw new Error("Use --neo4j-mode managed|external.");
+  }
+  return value;
+}
+
+function quoteEnv(value) {
+  const stringValue = String(value);
+  return /^[A-Za-z0-9_./:@-]*$/.test(stringValue) ? stringValue : JSON.stringify(stringValue);
+}
+
+function unquoteEnv(value) {
+  if (value.startsWith('"') && value.endsWith('"')) {
+    return JSON.parse(value);
+  }
+  return value;
+}
+
+function randomPassword(length, randomBytesImpl = randomBytes) {
+  const alphabet = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+  let output = "";
+  while (output.length < length) {
+    for (const byte of randomBytesImpl(length)) {
+      output += alphabet[byte % alphabet.length];
+      if (output.length === length) return output;
+    }
+  }
+  return output;
+}
+
+function stringFlag(value) {
+  if (value === undefined || value === null || value === true) return "";
+  return String(value).trim();
+}
+
+function toBool(value) {
+  if (value === true) return true;
+  if (value === false || value === undefined || value === null || value === "") return false;
+  return ["1", "true", "yes", "y", "on"].includes(String(value).toLowerCase());
+}
+
+function isInteractive(overrides = {}) {
+  const stdin = overrides.stdin || process.stdin;
+  const stdout = overrides.stdout || process.stdout;
+  return Boolean(stdin.isTTY && stdout.isTTY);
+}
+
+async function prompt(rl, label, defaultValue) {
+  const suffix = defaultValue ? ` [${colors.cyan}${defaultValue}${colors.reset}]` : "";
+  const answer = await rl.question(`${colors.bold}${colors.white}? ${label}${colors.reset}${suffix}: `);
+  return answer.trim() || defaultValue || "";
+}
+
+async function promptMenu(rl, label, options, defaultValue) {
+  const stdin = process.stdin;
+  const stdout = process.stdout;
+  
+  rl.pause(); // Pause readline interface to prevent double echoing
+  
+  readlineModule.emitKeypressEvents(stdin);
+  if (stdin.isTTY) {
+    stdin.setRawMode(true);
+  }
+  
+  let activeIdx = options.findIndex(o => o.name === defaultValue || o.value === defaultValue);
+  if (activeIdx === -1) activeIdx = 0;
+  
+  const renderMenu = () => {
+    stdout.write("\x1B[?25l"); // Hide cursor
+    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`);
+      } else {
+        stdout.write(`    ${options[i].name}\n`);
+      }
+    }
+  };
+  
+  const clearMenu = () => {
+    const linesToClear = options.length + 1;
+    for (let i = 0; i < linesToClear; i++) {
+      stdout.write("\x1B[1A\x1B[2K");
+    }
+  };
+  
+  renderMenu();
+  
+  return new Promise((resolve) => {
+    const onKeypress = (str, key) => {
+      if (key && key.ctrl && key.name === "c") {
+        stdout.write("\x1B[?25h"); // Show cursor
+        process.exit(0);
+      }
+      if (key && (key.name === "up" || key.name === "k")) {
+        activeIdx = (activeIdx - 1 + options.length) % options.length;
+        clearMenu();
+        renderMenu();
+      } else if (key && (key.name === "down" || key.name === "j")) {
+        activeIdx = (activeIdx + 1) % options.length;
+        clearMenu();
+        renderMenu();
+      } 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);
+        }
+        stdout.write(`\n`);
+        rl.resume(); // Resume readline interface
+        resolve(options[activeIdx].value);
+      }
+    };
+    stdin.on("keypress", onKeypress);
+  });
+}
+
+export function redactEnvText(text) {
+  const config = parseEnvFile(text);
+  for (const key of Object.keys(config)) {
+    if (SECRET_KEYS.has(key) && config[key]) {
+      config[key] = "<redacted>";
+    }
+  }
+  return renderEnvFile(config);
+}
+
+export function cleanBaseUrl(url, type) {
+  if (!url) return "";
+  let cleaned = String(url).trim();
+  
+  if (type === "llm") {
+    if (cleaned.endsWith("/chat/completions")) {
+      cleaned = cleaned.slice(0, -"/chat/completions".length);
+    } else if (cleaned.endsWith("/chat/completions/")) {
+      cleaned = cleaned.slice(0, -"/chat/completions/".length);
+    }
+  } else if (type === "embedding") {
+    if (cleaned.endsWith("/embeddings")) {
+      cleaned = cleaned.slice(0, -"/embeddings".length);
+    } else if (cleaned.endsWith("/embeddings/")) {
+      cleaned = cleaned.slice(0, -"/embeddings/".length);
+    }
+  }
+  
+  while (cleaned.endsWith("/")) {
+    cleaned = cleaned.slice(0, -1);
+  }
+  
+  return cleaned;
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "git-multiverse",
+  "version": "0.1.1",
+  "description": "Clone-free Multiverse Docker Hub launcher.",
+  "type": "module",
+  "bin": {
+    "git-multiverse": "./bin/git-multiverse.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "doctor": "node ./bin/git-multiverse.mjs doctor"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "Apache-2.0"
+}

package/test/git-multiverse.test.mjs

@@ -0,0 +1,179 @@
+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"));
+});