@danielblomma/cortex-mcp 2.4.1 → 2.4.2

package/bin/cli/hooks.mjs

@@ -0,0 +1,199 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { resolveHookEntry } from "./project-runtime.mjs";
+
+const HOOK_DEFS = [
+  {
+    event: "PreToolUse",
+    matcher: "Edit|Write|Bash|MultiEdit",
+    name: "pre-tool-use",
+  },
+  { event: "Stop", matcher: undefined, name: "stop" },
+  { event: "SessionStart", matcher: undefined, name: "session-start" },
+  { event: "SessionEnd", matcher: undefined, name: "session-end" },
+  {
+    event: "UserPromptSubmit",
+    matcher: undefined,
+    name: "user-prompt-submit",
+  },
+  { event: "PreCompact", matcher: undefined, name: "pre-compact" },
+];
+
+export async function runHookShim(args) {
+  const name = args[0];
+  if (!name) {
+    throw new Error("Usage: cortex hook <name>");
+  }
+  const entry = resolveHookEntry(name);
+  if (!fs.existsSync(entry)) {
+    throw new Error(`Hook script not found: ${entry}`);
+  }
+  const child = spawn(process.execPath, [entry], { stdio: "inherit" });
+  await new Promise((resolve) => {
+    child.on("exit", (code) => {
+      process.exit(code ?? 0);
+      resolve(undefined);
+    });
+  });
+}
+
+function managedClaudeSettingsPath() {
+  if (process.platform === "darwin") {
+    return "/Library/Application Support/ClaudeCode/managed-settings.json";
+  }
+  if (process.platform === "linux") {
+    return "/etc/claude-code/managed-settings.json";
+  }
+  return null;
+}
+
+function settingsPathFor(scope) {
+  if (scope === "project") {
+    return path.join(process.cwd(), ".claude", "settings.json");
+  }
+  let home = process.env.HOME || "";
+  const isRoot = process.getuid && process.getuid() === 0;
+  if (isRoot) {
+    const sudoUidRaw = process.env.SUDO_UID;
+    const sudoUid = sudoUidRaw ? parseInt(sudoUidRaw, 10) : NaN;
+    if (Number.isFinite(sudoUid)) {
+      try {
+        home = os.userInfo({ uid: sudoUid }).homedir;
+      } catch {
+        // Fall back to HOME below.
+      }
+    }
+  }
+  return path.join(home, ".claude", "settings.json");
+}
+
+function readJsonSafe(file) {
+  if (!fs.existsSync(file)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function hookInstalledInSettings(settings, def) {
+  const rows = settings.hooks?.[def.event] || [];
+  return rows.some((row) =>
+    (row.hooks?.[0]?.command || "").startsWith(`cortex hook ${def.name}`),
+  );
+}
+
+function readManagedClaudeSettings() {
+  const file = managedClaudeSettingsPath();
+  if (!file) return { file: null, settings: {} };
+  return { file, settings: readJsonSafe(file) };
+}
+
+export function hasManagedClaudeHooks() {
+  const { settings } = readManagedClaudeSettings();
+  if (settings.allowManagedHooksOnly !== true) return false;
+  return HOOK_DEFS.every((def) => hookInstalledInSettings(settings, def));
+}
+
+function writeJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+export async function runHooksCommand(args) {
+  const sub = args[0] || "status";
+  const scope = args.includes("--project") ? "project" : "user";
+  const target = settingsPathFor(scope);
+
+  if (sub === "install") {
+    const settings = readJsonSafe(target);
+    settings.hooks = settings.hooks || {};
+    for (const def of HOOK_DEFS) {
+      const entry = {
+        ...(def.matcher ? { matcher: def.matcher } : {}),
+        hooks: [{ type: "command", command: `cortex hook ${def.name}` }],
+      };
+      const existing = settings.hooks[def.event] || [];
+      const filtered = existing.filter((row) => {
+        const cmd = row.hooks?.[0]?.command || "";
+        return !cmd.startsWith("cortex hook ");
+      });
+      settings.hooks[def.event] = [...filtered, entry];
+    }
+    writeJson(target, settings);
+    console.log(`Installed cortex hooks into ${target}`);
+    console.log(`Hooks: ${HOOK_DEFS.map((def) => def.name).join(", ")}`);
+    return;
+  }
+  if (sub === "uninstall") {
+    const settings = readJsonSafe(target);
+    if (settings.hooks) {
+      for (const event of Object.keys(settings.hooks)) {
+        settings.hooks[event] = (settings.hooks[event] || []).filter((row) => {
+          const cmd = row.hooks?.[0]?.command || "";
+          return !cmd.startsWith("cortex hook ");
+        });
+        if (settings.hooks[event].length === 0) {
+          delete settings.hooks[event];
+        }
+      }
+      if (Object.keys(settings.hooks).length === 0) {
+        delete settings.hooks;
+      }
+    }
+    writeJson(target, settings);
+    console.log(`Removed cortex hooks from ${target}`);
+    return;
+  }
+  if (sub === "status") {
+    const settings = readJsonSafe(target);
+    const managed =
+      scope === "user"
+        ? readManagedClaudeSettings()
+        : { file: null, settings: {} };
+    const installed = [];
+    for (const def of HOOK_DEFS) {
+      const userFound = hookInstalledInSettings(settings, def);
+      const managedFound =
+        scope === "user"
+          ? hookInstalledInSettings(managed.settings, def)
+          : false;
+      const found = userFound || managedFound;
+      let source = "";
+      if (userFound && managedFound) source = "user+managed";
+      else if (userFound) source = "user";
+      else if (managedFound) source = "managed";
+      installed.push({
+        name: def.name,
+        event: def.event,
+        found,
+        source,
+      });
+    }
+    console.log(`Settings file: ${target}`);
+    if (scope === "user" && managed.file) {
+      console.log(`Managed settings: ${managed.file}`);
+    }
+    for (const row of installed) {
+      console.log(
+        `  ${row.found ? "✓" : "✗"} ${row.event} → ${row.name}${
+          row.source ? ` (${row.source})` : ""
+        }`,
+      );
+    }
+    if (
+      scope === "user" &&
+      managed.settings.allowManagedHooksOnly === true
+    ) {
+      console.log(
+        "  note: managed Claude hooks are authoritative; user hooks may be intentionally absent",
+      );
+    }
+    return;
+  }
+  throw new Error(
+    `Unknown hooks subcommand: ${sub}. Try install|uninstall|status`,
+  );
+}

package/bin/cli/mcp-command.mjs

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import path from "node:path";
+import { normalizeProjectRoot } from "../wsl.mjs";
+import {
+  maybeMigrateScaffold,
+  runContextCommand,
+} from "./context-passthrough.mjs";
+import { MCP_PROJECT_REL } from "./paths.mjs";
+import { runCommand } from "./process.mjs";
+import {
+  canAutoInitialize,
+  ensureProjectInitialized,
+  ensureScaffoldExists,
+  initializeScaffold,
+  installAssistantHelpers,
+  isScaffoldOutOfDate,
+  isTruthyEnv,
+  maybeInstallGitHooks,
+} from "./scaffold.mjs";
+
+async function ensureProjectInitializedForMcp(targetDir) {
+  const mcpPackageJson = path.join(
+    targetDir,
+    MCP_PROJECT_REL,
+    "package.json",
+  );
+  const serverEntry = path.join(
+    targetDir,
+    MCP_PROJECT_REL,
+    "dist",
+    "server.js",
+  );
+
+  if (fs.existsSync(mcpPackageJson) && fs.existsSync(serverEntry)) return;
+
+  if (isScaffoldOutOfDate(targetDir)) {
+    await maybeMigrateScaffold(targetDir, "mcp");
+    if (fs.existsSync(mcpPackageJson) && fs.existsSync(serverEntry)) return;
+  }
+
+  if (!isTruthyEnv(process.env.CORTEX_AUTO_BOOTSTRAP_ON_MCP)) {
+    ensureProjectInitialized(targetDir);
+    return;
+  }
+
+  if (!fs.existsSync(mcpPackageJson)) {
+    if (!canAutoInitialize(targetDir)) {
+      throw new Error(
+        `Cannot auto-initialize Cortex in ${targetDir}: scaffold paths already exist. Run 'cortex init --bootstrap' manually.`,
+      );
+    }
+    ensureScaffoldExists();
+    fs.mkdirSync(targetDir, { recursive: true });
+    initializeScaffold(targetDir, false);
+    installAssistantHelpers(targetDir);
+    await maybeInstallGitHooks(targetDir);
+    console.log(`[cortex] auto-init completed in ${targetDir}`);
+  }
+
+  if (!fs.existsSync(serverEntry)) {
+    console.log("[cortex] auto-bootstrap: running initial bootstrap for MCP");
+    await runContextCommand(targetDir, ["bootstrap"]);
+  }
+}
+
+export async function runMcpCommand() {
+  const rawTarget = process.env.CORTEX_PROJECT_ROOT || process.cwd();
+  const target = path.resolve(normalizeProjectRoot(rawTarget));
+  process.env.CORTEX_PROJECT_ROOT = target;
+  await ensureProjectInitializedForMcp(target);
+  ensureProjectInitialized(target);
+  const serverEntry = path.join(
+    target,
+    MCP_PROJECT_REL,
+    "dist",
+    "server.js",
+  );
+  if (!fs.existsSync(serverEntry)) {
+    throw new Error(
+      `Missing ${serverEntry}. Run 'cortex bootstrap' in ${target} first.`,
+    );
+  }
+  process.stderr.write(
+    `[cortex] starting MCP stdio server from ${serverEntry}\n`,
+  );
+  await runCommand("node", [serverEntry], target);
+}

package/bin/cli/paths.mjs

@@ -0,0 +1,14 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const CLI_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+export const PACKAGE_ROOT = path.resolve(CLI_DIR, "../..");
+export const SCAFFOLD_ROOT = path.join(PACKAGE_ROOT, "scaffold");
+export const PACKAGE_JSON_PATH = path.join(PACKAGE_ROOT, "package.json");
+
+// The project runtime keeps the .context/mcp compatibility name even though
+// it now serves the full local context surface.
+export const MCP_PROJECT_REL = path.join(".context", "mcp");
+export const CONTEXT_RUNTIME_REL = MCP_PROJECT_REL;
+export const CONTEXT_SCRIPTS_REL = path.join(".context", "scripts");

package/bin/cli/process.mjs

@@ -0,0 +1,49 @@
+import { spawn } from "node:child_process";
+
+export function runCommand(command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: "inherit",
+      env: process.env,
+    });
+
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`${command} exited with code ${code ?? "unknown"}`));
+      }
+    });
+  });
+}
+
+export function runCommandResult(command, args, cwd, stdio = "ignore") {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (result) => {
+      if (done) return;
+      done = true;
+      resolve(result);
+    };
+
+    const child = spawn(command, args, {
+      cwd,
+      stdio,
+      env: process.env,
+    });
+
+    child.on("error", (error) => finish({ ok: false, code: null, error }));
+    child.on("exit", (code) => finish({ ok: code === 0, code, error: null }));
+  });
+}
+
+export function toErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export async function commandExists(command, cwd) {
+  const result = await runCommandResult(command, ["--version"], cwd, "ignore");
+  return result.ok;
+}

package/bin/cli/project-commands.mjs

@@ -0,0 +1,237 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseConnectArgs, parseInitArgs } from "./arguments.mjs";
+import { runContextCommand } from "./context-passthrough.mjs";
+import { restartDaemonAfterRuntimeUpgrade } from "./daemon.mjs";
+import { printBanner } from "./help.mjs";
+import { MCP_PROJECT_REL } from "./paths.mjs";
+import {
+  commandExists,
+  runCommand,
+  runCommandResult,
+  toErrorMessage,
+} from "./process.mjs";
+import {
+  ensureProjectInitialized,
+  ensureScaffoldExists,
+  hardenEnterpriseConfigPermissions,
+  initializeScaffold,
+  installAssistantHelpers,
+  maybeInstallGitHooks,
+} from "./scaffold.mjs";
+
+function normalizeName(value) {
+  const cleaned = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return cleaned || "repo";
+}
+
+async function connectCodex(targetDir, serverEntry) {
+  if (!(await commandExists("codex", targetDir))) {
+    console.log(
+      "[cortex] codex CLI not found, skipping Codex MCP registration",
+    );
+    return false;
+  }
+
+  const repoName = normalizeName(path.basename(targetDir));
+  const serverName = `cortex-${repoName}`;
+  await runCommandResult(
+    "codex",
+    ["mcp", "remove", serverName],
+    targetDir,
+    "ignore",
+  );
+  await runCommand(
+    "codex",
+    ["mcp", "add", serverName, "--", "node", serverEntry],
+    targetDir,
+  );
+  console.log(`[cortex] connected Codex MCP server: ${serverName}`);
+  return true;
+}
+
+async function connectClaude(targetDir) {
+  if (!(await commandExists("claude", targetDir))) {
+    console.log(
+      "[cortex] claude CLI not found, skipping Claude Code MCP registration",
+    );
+    return false;
+  }
+
+  const serverName = "cortex";
+  const projectServerEntry = path.join(
+    MCP_PROJECT_REL,
+    "dist",
+    "server.js",
+  );
+  await runCommandResult(
+    "claude",
+    ["mcp", "remove", "-s", "project", serverName],
+    targetDir,
+    "ignore",
+  );
+  await runCommand(
+    "claude",
+    [
+      "mcp",
+      "add",
+      "-s",
+      "project",
+      serverName,
+      "--",
+      "node",
+      projectServerEntry,
+    ],
+    targetDir,
+  );
+  console.log(
+    "[cortex] connected Claude Code MCP server: cortex (project scope)",
+  );
+  return true;
+}
+
+async function connectMcpClients(targetDir, options = {}) {
+  const { skipBuild = false } = options;
+  const mcpDir = path.join(targetDir, MCP_PROJECT_REL);
+  const packageJson = path.join(mcpDir, "package.json");
+  const nodeModules = path.join(mcpDir, "node_modules");
+  const serverEntry = path.join(mcpDir, "dist", "server.js");
+
+  if (!fs.existsSync(packageJson)) {
+    throw new Error(`Missing ${packageJson}. Run 'cortex init' first.`);
+  }
+
+  if (!skipBuild && fs.existsSync(nodeModules)) {
+    try {
+      await runCommand(
+        "npm",
+        ["--prefix", mcpDir, "run", "build", "--silent"],
+        targetDir,
+      );
+    } catch (error) {
+      console.log(
+        `[cortex] MCP build failed, continuing with existing dist output: ${toErrorMessage(error)}`,
+      );
+    }
+  } else if (!skipBuild) {
+    console.log(
+      "[cortex] .context/mcp/node_modules not found, skipping build (run cortex bootstrap first)",
+    );
+  }
+
+  if (!fs.existsSync(serverEntry)) {
+    console.log(
+      `[cortex] warning: ${serverEntry} not found yet; run cortex bootstrap before first MCP call`,
+    );
+  }
+
+  let connected = 0;
+
+  try {
+    if (await connectCodex(targetDir, serverEntry)) connected += 1;
+  } catch (error) {
+    console.log(
+      `[cortex] failed to connect Codex MCP: ${toErrorMessage(error)}`,
+    );
+  }
+
+  try {
+    if (await connectClaude(targetDir)) connected += 1;
+  } catch (error) {
+    console.log(
+      `[cortex] failed to connect Claude MCP: ${toErrorMessage(error)}`,
+    );
+  }
+
+  if (connected === 0) {
+    console.log("[cortex] no MCP clients connected");
+  }
+
+  return connected;
+}
+
+export async function runInitCommand(args) {
+  ensureScaffoldExists();
+  const { target, force, bootstrap, connect, watch } = parseInitArgs(args);
+  printBanner("Cortex initializes repo-scoped context for AI coding agents.");
+  fs.mkdirSync(target, { recursive: true });
+  initializeScaffold(target, force);
+  hardenEnterpriseConfigPermissions(target);
+  const helpers = installAssistantHelpers(target);
+  await maybeInstallGitHooks(target);
+
+  console.log(`[cortex] initialized in ${target}`);
+  console.log(
+    "[cortex] scaffold copied: .context/, .context/scripts/, context runtime (.context/mcp compatibility path), .githooks/, docs/",
+  );
+  console.log(
+    `[cortex] Claude commands ready: /context-update (${helpers.claude.total} files)`,
+  );
+  if (helpers.codex.changed) {
+    console.log("[cortex] Codex workflow instructions added to AGENTS.md");
+  } else {
+    console.log(
+      "[cortex] Codex workflow instructions already up to date in AGENTS.md",
+    );
+  }
+
+  if (bootstrap) {
+    console.log(
+      "[cortex] bootstrap: install deps -> ingest -> embeddings -> graph",
+    );
+  } else {
+    console.log("[cortex] next: cortex bootstrap");
+  }
+
+  if (connect) {
+    console.log(
+      "[cortex] MCP connect: Codex + Claude Code (if CLIs are installed)",
+    );
+  } else {
+    console.log(
+      "[cortex] MCP connect skipped (run 'cortex connect' or init with --connect)",
+    );
+  }
+
+  if (watch) {
+    if (bootstrap) {
+      console.log("[cortex] background sync: cortex watch start");
+    } else {
+      console.log(
+        "[cortex] background sync pending: run cortex watch start after bootstrap",
+      );
+    }
+  } else {
+    console.log("[cortex] background sync skipped (--no-watch)");
+  }
+
+  if (!bootstrap) console.log("");
+
+  if (bootstrap) {
+    await runContextCommand(target, ["bootstrap"]);
+    await restartDaemonAfterRuntimeUpgrade(target);
+  }
+
+  if (connect) {
+    await connectMcpClients(target);
+  }
+
+  if (watch && bootstrap) {
+    await runContextCommand(target, ["watch", "start"]);
+  }
+}
+
+export async function runConnectCommand(args) {
+  const { target, skipBuild } = parseConnectArgs(args);
+  ensureProjectInitialized(target);
+  const helpers = installAssistantHelpers(target);
+  if (helpers.claude.changed > 0 || helpers.codex.changed) {
+    console.log(
+      "[cortex] assistant helpers updated (.claude/commands + AGENTS.md)",
+    );
+  }
+  await connectMcpClients(target, { skipBuild });
+}

package/bin/cli/project-runtime.mjs

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { CONTEXT_RUNTIME_REL } from "./paths.mjs";
+
+export function resolveProjectRuntimeDist(projectRoot) {
+  const target =
+    projectRoot ||
+    process.env.CORTEX_PROJECT_ROOT?.trim() ||
+    process.cwd();
+  return path.join(target, CONTEXT_RUNTIME_REL, "dist");
+}
+
+export function resolveDaemonEntry(projectRoot) {
+  return path.join(resolveProjectRuntimeDist(projectRoot), "daemon", "main.js");
+}
+
+export function resolveHookEntry(name) {
+  return path.join(resolveProjectRuntimeDist(), "hooks", `${name}.js`);
+}
+
+export function resolveCliEntry(name) {
+  return path.join(resolveProjectRuntimeDist(), "cli", `${name}.js`);
+}
+
+export async function loadProjectCliModule(name) {
+  const entry = resolveCliEntry(name);
+  if (!fs.existsSync(entry)) {
+    throw new Error(
+      `Build the project's context runtime first (missing ${entry}). Run 'cortex bootstrap' in the project root.`,
+    );
+  }
+  return import(pathToFileURL(entry).href);
+}

package/bin/cli/query-command.mjs

@@ -0,0 +1,18 @@
+import path from "node:path";
+import { loadProjectCliModule } from "./project-runtime.mjs";
+
+export const QUERY_COMMANDS = new Set([
+  "search",
+  "related",
+  "impact",
+  "rules",
+  "explain",
+  "pattern-evidence",
+]);
+
+export async function runQueryCommandShim(command, args) {
+  const target = process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
+  process.env.CORTEX_PROJECT_ROOT = path.resolve(target);
+  const mod = await loadProjectCliModule("query");
+  await mod.runQueryCommand([command, ...args]);
+}

package/bin/cli/router.mjs

@@ -0,0 +1,66 @@
+import {
+  PASSTHROUGH_COMMANDS,
+  runPassthroughCommand,
+} from "./context-passthrough.mjs";
+import { runDaemonCommand } from "./daemon.mjs";
+import { runEnterpriseCommand } from "./enterprise.mjs";
+import { printHelp, readCliVersion } from "./help.mjs";
+import { runHookShim, runHooksCommand } from "./hooks.mjs";
+import { runMcpCommand } from "./mcp-command.mjs";
+import {
+  runConnectCommand,
+  runInitCommand,
+} from "./project-commands.mjs";
+import {
+  QUERY_COMMANDS,
+  runQueryCommandShim,
+} from "./query-command.mjs";
+import { runRunCommand } from "./run-command.mjs";
+import { runStageCommandShim } from "./stage-command.mjs";
+import { runTelemetryCommand } from "./telemetry-command.mjs";
+
+const COMMAND_HANDLERS = new Map([
+  ["init", runInitCommand],
+  ["connect", runConnectCommand],
+  ["mcp", runMcpCommand],
+  ["daemon", runDaemonCommand],
+  ["hook", runHookShim],
+  ["hooks", runHooksCommand],
+  ["telemetry", runTelemetryCommand],
+  ["enterprise", runEnterpriseCommand],
+  ["run", runRunCommand],
+  ["stage", runStageCommandShim],
+]);
+
+export async function runCli(argv = process.argv.slice(2)) {
+  const cliVersion = readCliVersion();
+  process.env.CORTEX_CLI_VERSION = cliVersion;
+
+  const [rawCommand, ...rest] = argv;
+  const command = rawCommand ?? "help";
+
+  if (command === "version" || command === "--version" || command === "-V") {
+    console.log(cliVersion);
+    return;
+  }
+
+  if (command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  const handler = COMMAND_HANDLERS.get(command);
+  if (handler) {
+    return handler(rest);
+  }
+
+  if (QUERY_COMMANDS.has(command)) {
+    return runQueryCommandShim(command, rest);
+  }
+
+  if (PASSTHROUGH_COMMANDS.has(command)) {
+    return runPassthroughCommand(command, rest);
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}