code-graph-builder 0.2.0 → 0.3.1

package/bin/cli.mjs

@@ -1,29 +1,30 @@
 #!/usr/bin/env node
 
 /**
- * code-graph-builder MCP server launcher
- *
- * Automatically detects the best way to run the Python MCP server:
- *   1. uvx (fastest, auto-installs in isolated env)
- *   2. pipx (similar to uvx)
- *   3. Direct python3 (requires prior pip install)
+ * code-graph-builder MCP server launcher & setup wizard
  *
  * Usage:
- *   npx code-graph-builder          # auto-detect
- *   npx code-graph-builder --pip    # force pip mode
+ *   npx code-graph-builder              # interactive setup (first run)
+ *   npx code-graph-builder --server     # start MCP server (used by MCP clients)
+ *   npx code-graph-builder --setup      # re-run setup wizard
+ *   npx code-graph-builder --pip        # force python3 direct mode
  */
 
 import { spawn, execFileSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 
 const PYTHON_PACKAGE = "code-graph-builder";
 const MODULE_PATH = "code_graph_builder.mcp.server";
+const WORKSPACE_DIR = join(homedir(), ".code-graph-builder");
+const ENV_FILE = join(WORKSPACE_DIR, ".env");
 
-// Pass through all env vars (CGB_WORKSPACE, API keys, etc.)
-const env = { ...process.env };
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
 
-/**
- * Check if a command exists on PATH.
- */
 function commandExists(cmd) {
   try {
     execFileSync("which", [cmd], { stdio: "pipe" });
@@ -33,9 +34,6 @@ function commandExists(cmd) {
   }
 }
 
-/**
- * Check if the Python package is importable.
- */
 function pythonPackageInstalled() {
   try {
     execFileSync("python3", ["-c", `import ${MODULE_PATH.split(".")[0]}`], {
@@ -47,17 +45,257 @@ function pythonPackageInstalled() {
   }
 }
 
-/**
- * Run a command as the MCP server (replaces this process's stdio).
- */
+function loadEnvFile() {
+  if (!existsSync(ENV_FILE)) return {};
+  const vars = {};
+  for (const line of readFileSync(ENV_FILE, "utf-8").split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let val = trimmed.slice(eq + 1).trim();
+    // Strip surrounding quotes
+    if ((val.startsWith('"') && val.endsWith('"')) ||
+        (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    vars[key] = val;
+  }
+  return vars;
+}
+
+function saveEnvFile(vars) {
+  mkdirSync(WORKSPACE_DIR, { recursive: true });
+  const lines = [
+    "# code-graph-builder configuration",
+    "# Generated by setup wizard. Edit freely.",
+    "",
+  ];
+  for (const [key, val] of Object.entries(vars)) {
+    if (val) lines.push(`${key}=${val}`);
+  }
+  lines.push("");
+  writeFileSync(ENV_FILE, lines.join("\n"), "utf-8");
+}
+
+function mask(s) {
+  if (!s || s.length < 8) return s ? "****" : "(not set)";
+  return s.slice(0, 4) + "****" + s.slice(-4);
+}
+
+// ---------------------------------------------------------------------------
+// Interactive setup wizard (runs on stderr so stdout stays clean)
+// ---------------------------------------------------------------------------
+
+async function runSetup() {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+
+  const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+  const log = (msg) => process.stderr.write(msg + "\n");
+
+  log("");
+  log("╔══════════════════════════════════════════════════════════╗");
+  log("║        code-graph-builder  Setup Wizard                 ║");
+  log("╚══════════════════════════════════════════════════════════╝");
+  log("");
+
+  // Load existing config
+  const existing = loadEnvFile();
+
+  // --- Workspace ---
+  log("── 1/3  Workspace ──────────────────────────────────────────");
+  log(`Workspace stores indexed repos, graphs, and embeddings.`);
+  const workspace =
+    (await ask(`  Workspace path [${WORKSPACE_DIR}]: `)).trim() || WORKSPACE_DIR;
+  log("");
+
+  // --- LLM Provider ---
+  log("── 2/3  LLM Provider (for natural language queries & descriptions) ──");
+  log("");
+  log("  Select your LLM provider:");
+  log("");
+  log("    1) Moonshot / Kimi    https://platform.moonshot.cn");
+  log("    2) OpenAI             https://platform.openai.com");
+  log("    3) DeepSeek           https://platform.deepseek.com");
+  log("    4) OpenRouter         https://openrouter.ai");
+  log("    5) Custom (any OpenAI-compatible endpoint)");
+  log("    6) Skip (configure later)");
+  log("");
+
+  const providers = {
+    "1": { name: "Moonshot",    url: "https://api.moonshot.cn/v1",   model: "kimi-k2.5" },
+    "2": { name: "OpenAI",      url: "https://api.openai.com/v1",    model: "gpt-4o" },
+    "3": { name: "DeepSeek",    url: "https://api.deepseek.com/v1",  model: "deepseek-chat" },
+    "4": { name: "OpenRouter",  url: "https://openrouter.ai/api/v1", model: "anthropic/claude-sonnet-4" },
+  };
+
+  if (existing.LLM_API_KEY) {
+    log(`  Current: ${mask(existing.LLM_API_KEY)} → ${existing.LLM_BASE_URL || "?"}`);
+  }
+
+  const choice = (await ask("  Choose provider [1-6]: ")).trim() || "6";
+
+  let llmKey = existing.LLM_API_KEY || "";
+  let llmBaseUrl = existing.LLM_BASE_URL || "";
+  let llmModel = existing.LLM_MODEL || "";
+
+  if (choice !== "6") {
+    const provider = providers[choice];
+
+    if (provider) {
+      log(`\n  → ${provider.name} selected`);
+      llmBaseUrl = provider.url;
+      llmModel = provider.model;
+    } else {
+      // Choice "5" or invalid → custom
+      log("\n  → Custom provider");
+      llmBaseUrl = (await ask("  API Base URL: ")).trim() || llmBaseUrl;
+      llmModel = (await ask("  Model name: ")).trim() || llmModel || "gpt-4o";
+    }
+
+    llmKey = (await ask(`  API Key (sk-...): `)).trim() || existing.LLM_API_KEY || "";
+
+    if (llmKey) {
+      // Allow overriding URL and model
+      const urlOverride = (await ask(`  Base URL [${llmBaseUrl}]: `)).trim();
+      if (urlOverride) llmBaseUrl = urlOverride;
+      const modelOverride = (await ask(`  Model [${llmModel}]: `)).trim();
+      if (modelOverride) llmModel = modelOverride;
+    }
+  }
+  log("");
+
+  // --- Embedding Provider ---
+  log("── 3/3  Embedding Provider (for semantic code search) ─────");
+  log("");
+  log("  Select your embedding provider:");
+  log("");
+  log("    1) DashScope / Qwen    https://dashscope.console.aliyun.com  (free tier)");
+  log("    2) OpenAI Embeddings   https://platform.openai.com");
+  log("    3) Custom (any OpenAI-compatible embedding endpoint)");
+  log("    4) Skip (configure later)");
+  log("");
+
+  const embedProviders = {
+    "1": { name: "DashScope",  url: "https://dashscope.aliyuncs.com/api/v1", model: "text-embedding-v4", keyEnv: "DASHSCOPE_API_KEY", urlEnv: "DASHSCOPE_BASE_URL" },
+    "2": { name: "OpenAI",     url: "https://api.openai.com/v1",             model: "text-embedding-3-small", keyEnv: "OPENAI_API_KEY", urlEnv: "OPENAI_BASE_URL" },
+  };
+
+  if (existing.DASHSCOPE_API_KEY || existing.EMBED_API_KEY) {
+    const ek = existing.DASHSCOPE_API_KEY || existing.EMBED_API_KEY;
+    log(`  Current: ${mask(ek)} → ${existing.DASHSCOPE_BASE_URL || existing.EMBED_BASE_URL || "?"}`);
+  }
+
+  const embedChoice = (await ask("  Choose provider [1-4]: ")).trim() || "4";
+
+  let embedKey = "";
+  let embedUrl = "";
+  let embedModel = "";
+  let embedKeyEnv = "DASHSCOPE_API_KEY";
+  let embedUrlEnv = "DASHSCOPE_BASE_URL";
+
+  if (embedChoice !== "4") {
+    const ep = embedProviders[embedChoice];
+
+    if (ep) {
+      log(`\n  → ${ep.name} selected`);
+      embedUrl = ep.url;
+      embedModel = ep.model;
+      embedKeyEnv = ep.keyEnv;
+      embedUrlEnv = ep.urlEnv;
+    } else {
+      // Choice "3" or invalid → custom
+      log("\n  → Custom embedding provider");
+      embedUrl = (await ask("  Embedding API Base URL: ")).trim();
+      embedModel = (await ask("  Embedding model name: ")).trim() || "text-embedding-3-small";
+      embedKeyEnv = "EMBED_API_KEY";
+      embedUrlEnv = "EMBED_BASE_URL";
+    }
+
+    embedKey = (await ask(`  API Key: `)).trim() ||
+      existing[embedKeyEnv] || existing.DASHSCOPE_API_KEY || "";
+
+    if (embedKey) {
+      const urlOverride = (await ask(`  Base URL [${embedUrl}]: `)).trim();
+      if (urlOverride) embedUrl = urlOverride;
+      const modelOverride = (await ask(`  Model [${embedModel}]: `)).trim();
+      if (modelOverride) embedModel = modelOverride;
+    }
+  }
+
+  rl.close();
+
+  // --- Save ---
+  const config = {
+    CGB_WORKSPACE: workspace,
+    LLM_API_KEY: llmKey,
+    LLM_BASE_URL: llmBaseUrl,
+    LLM_MODEL: llmModel,
+  };
+
+  // Save embedding config with the correct env var names
+  if (embedKey) {
+    config[embedKeyEnv] = embedKey;
+    config[embedUrlEnv] = embedUrl;
+    if (embedModel) config.EMBED_MODEL = embedModel;
+  }
+
+  saveEnvFile(config);
+
+  const embedDisplay = embedKey
+    ? `${mask(embedKey)} → ${embedModel || embedUrl}`
+    : "not configured (optional)";
+
+  log("");
+  log("── Configuration saved ─────────────────────────────────────");
+  log(`  File: ${ENV_FILE}`);
+  log("");
+  log("  LLM:       " + (llmKey ? `${mask(llmKey)} → ${llmModel}` : "not configured (optional)"));
+  log("  Embedding: " + embedDisplay);
+  log("  Workspace: " + workspace);
+  log("");
+  log("── Next steps ──────────────────────────────────────────────");
+  log("");
+  log("  Add to your MCP client config:");
+  log("");
+  log('  {');
+  log('    "mcpServers": {');
+  log('      "code-graph-builder": {');
+  log('        "command": "npx",');
+  log('        "args": ["-y", "code-graph-builder", "--server"]');
+  log("      }");
+  log("    }");
+  log("  }");
+  log("");
+  log("  Or run directly:  npx code-graph-builder --server");
+  log("");
+}
+
+// ---------------------------------------------------------------------------
+// Start MCP server
+// ---------------------------------------------------------------------------
+
 function runServer(cmd, args) {
+  // Merge .env file into environment
+  const envVars = loadEnvFile();
+  const mergedEnv = { ...process.env, ...envVars };
+
+  // Ensure CGB_WORKSPACE is set
+  if (!mergedEnv.CGB_WORKSPACE) {
+    mergedEnv.CGB_WORKSPACE = WORKSPACE_DIR;
+  }
+
   const child = spawn(cmd, args, {
     stdio: "inherit",
-    env,
+    env: mergedEnv,
   });
 
   child.on("error", (err) => {
-    console.error(`Failed to start MCP server: ${err.message}`);
+    process.stderr.write(`Failed to start MCP server: ${err.message}\n`);
     process.exit(1);
   });
 
@@ -66,44 +304,69 @@ function runServer(cmd, args) {
   });
 }
 
+function startServer(extraArgs = []) {
+  if (commandExists("uvx")) {
+    runServer("uvx", [PYTHON_PACKAGE, ...extraArgs]);
+  } else if (commandExists("uv")) {
+    runServer("uv", ["tool", "run", PYTHON_PACKAGE, ...extraArgs]);
+  } else if (commandExists("pipx")) {
+    runServer("pipx", ["run", PYTHON_PACKAGE, ...extraArgs]);
+  } else if (pythonPackageInstalled()) {
+    runServer("python3", ["-m", MODULE_PATH]);
+  } else {
+    process.stderr.write(
+      `code-graph-builder requires Python 3.10+.\n\n` +
+        `Install options:\n` +
+        `  1. pip install ${PYTHON_PACKAGE}\n` +
+        `  2. curl -LsSf https://astral.sh/uv/install.sh | sh  (installs uv)\n` +
+        `  3. pip install pipx\n\n` +
+        `Then run: npx code-graph-builder --server\n`
+    );
+    process.exit(1);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
 
-const forceMode = process.argv[2];
+const args = process.argv.slice(2);
+const mode = args[0];
 
-if (forceMode === "--pip" || forceMode === "--python") {
-  // Force direct python3 mode
-  if (!pythonPackageInstalled()) {
-    console.error(
-      `Error: Python package '${PYTHON_PACKAGE}' is not installed.\n` +
-        `Run: pip install ${PYTHON_PACKAGE}`
-    );
-    process.exit(1);
+if (mode === "--setup") {
+  // Explicit setup request
+  runSetup();
+} else if (mode === "--server" || mode === "--pip" || mode === "--python") {
+  // Start MCP server directly
+  if (mode === "--pip" || mode === "--python") {
+    if (!pythonPackageInstalled()) {
+      process.stderr.write(
+        `Error: Python package '${PYTHON_PACKAGE}' is not installed.\n` +
+          `Run: pip install ${PYTHON_PACKAGE}\n`
+      );
+      process.exit(1);
+    }
+    runServer("python3", ["-m", MODULE_PATH]);
+  } else {
+    startServer(args.slice(1));
   }
-  runServer("python3", ["-m", MODULE_PATH]);
-} else if (commandExists("uvx")) {
-  // Preferred: uvx auto-installs in isolated env
-  runServer("uvx", [PYTHON_PACKAGE, ...process.argv.slice(2)]);
-} else if (commandExists("uv")) {
-  // uv available but not uvx — use uv tool run
-  runServer("uv", ["tool", "run", PYTHON_PACKAGE, ...process.argv.slice(2)]);
-} else if (commandExists("pipx")) {
-  // pipx: similar to uvx
-  runServer("pipx", ["run", PYTHON_PACKAGE, ...process.argv.slice(2)]);
-} else if (pythonPackageInstalled()) {
-  // Fallback: direct python3
-  runServer("python3", ["-m", MODULE_PATH]);
-} else {
-  // Nothing works — guide the user
-  console.error(
-    `code-graph-builder MCP server requires Python 3.10+.\n\n` +
-      `Install options (pick one):\n` +
-      `  1. pip install ${PYTHON_PACKAGE}    # then: npx code-graph-builder --pip\n` +
-      `  2. Install uv (recommended):         curl -LsSf https://astral.sh/uv/install.sh | sh\n` +
-      `     Then: npx code-graph-builder      # auto-installs via uvx\n` +
-      `  3. Install pipx:                     pip install pipx\n` +
-      `     Then: npx code-graph-builder      # auto-installs via pipx\n`
+} else if (mode === "--help" || mode === "-h") {
+  process.stderr.write(
+    `code-graph-builder - Code knowledge graph MCP server\n\n` +
+      `Usage:\n` +
+      `  npx code-graph-builder            Interactive setup wizard\n` +
+      `  npx code-graph-builder --server   Start MCP server\n` +
+      `  npx code-graph-builder --setup    Re-run setup wizard\n` +
+      `  npx code-graph-builder --help     Show this help\n\n` +
+      `Config: ${ENV_FILE}\n`
   );
-  process.exit(1);
+} else {
+  // No args: auto-detect
+  if (!existsSync(ENV_FILE)) {
+    // First run → setup wizard
+    runSetup();
+  } else {
+    // Config exists → start server
+    startServer(args);
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-graph-builder",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Code knowledge graph builder with MCP server for AI-assisted code navigation",
   "license": "MIT",
   "bin": {