code-graph-builder 0.2.0 → 0.3.0

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,199 @@ 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 API Key ---
+  log("── 2/3  LLM API Key (for natural language queries & descriptions) ──");
+  log("");
+  log("  Supported providers (OpenAI-compatible):");
+  log("    - Moonshot / Kimi    https://platform.moonshot.cn");
+  log("    - OpenAI             https://platform.openai.com");
+  log("    - DeepSeek           https://platform.deepseek.com");
+  log("    - Any OpenAI-compatible endpoint");
+  log("");
+
+  if (existing.LLM_API_KEY) {
+    log(`  Current key: ${mask(existing.LLM_API_KEY)}`);
+  }
+
+  const llmKey =
+    (await ask("  LLM API Key (sk-...): ")).trim() || existing.LLM_API_KEY || "";
+
+  let llmBaseUrl = existing.LLM_BASE_URL || "";
+  let llmModel = existing.LLM_MODEL || "";
+
+  if (llmKey) {
+    log("");
+    log("  Detecting provider from key...");
+
+    if (llmKey.startsWith("sk-") && !llmKey.startsWith("sk-ant-")) {
+      // Could be Moonshot, OpenAI, or other
+      const urlInput = (
+        await ask(
+          `  API Base URL [${llmBaseUrl || "https://api.moonshot.cn/v1"}]: `
+        )
+      ).trim();
+      llmBaseUrl = urlInput || llmBaseUrl || "https://api.moonshot.cn/v1";
+
+      if (llmBaseUrl.includes("moonshot")) {
+        llmModel = (await ask(`  Model name [kimi-k2.5]: `)).trim() || "kimi-k2.5";
+      } else if (llmBaseUrl.includes("openai")) {
+        llmModel = (await ask(`  Model name [gpt-4o]: `)).trim() || "gpt-4o";
+      } else if (llmBaseUrl.includes("deepseek")) {
+        llmModel = (await ask(`  Model name [deepseek-chat]: `)).trim() || "deepseek-chat";
+      } else {
+        llmModel =
+          (await ask(`  Model name [${llmModel || "gpt-4o"}]: `)).trim() ||
+          llmModel ||
+          "gpt-4o";
+      }
+    }
+  }
+  log("");
+
+  // --- Embedding API Key ---
+  log("── 3/3  Embedding API Key (for semantic code search) ─────");
+  log("");
+  log("  Used for vector embedding of code (Qwen3 text-embedding-v4).");
+  log("  Get a free key at: https://dashscope.console.aliyun.com");
+  log("");
+
+  if (existing.DASHSCOPE_API_KEY) {
+    log(`  Current key: ${mask(existing.DASHSCOPE_API_KEY)}`);
+  }
+
+  const dashscopeKey =
+    (await ask("  DashScope API Key (sk-...): ")).trim() ||
+    existing.DASHSCOPE_API_KEY ||
+    "";
+
+  rl.close();
+
+  // --- Save ---
+  const config = {
+    CGB_WORKSPACE: workspace,
+    LLM_API_KEY: llmKey,
+    LLM_BASE_URL: llmBaseUrl,
+    LLM_MODEL: llmModel,
+    DASHSCOPE_API_KEY: dashscopeKey,
+    DASHSCOPE_BASE_URL: "https://dashscope.aliyuncs.com/api/v1",
+  };
+
+  saveEnvFile(config);
+
+  log("");
+  log("── Configuration saved ─────────────────────────────────────");
+  log(`  File: ${ENV_FILE}`);
+  log("");
+  log("  LLM:       " + (llmKey ? `${mask(llmKey)} → ${llmModel}` : "not configured (optional)"));
+  log("  Embedding: " + (dashscopeKey ? mask(dashscopeKey) : "not configured (optional)"));
+  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 +246,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.0",
   "description": "Code knowledge graph builder with MCP server for AI-assisted code navigation",
   "license": "MIT",
   "bin": {