@danielblomma/cortex-mcp 2.4.1 → 2.4.2

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 2.4.2 — 2026-07-30
+
+### Changed
+
+- Split the Cortex CLI into cohesive command modules behind the existing
+  executable, preserving command names, arguments, streams, exit behavior,
+  JSON envelopes, Enterprise trust resolution, and `.context/mcp`
+  compatibility.
+- Established `scaffold/scripts/lib/ingest/` as the single canonical ingest
+  implementation for development and packaged entrypoints. Deterministic
+  output, worker fallback, trace checkpoints, and bounded result retention
+  remain unchanged.
+- Added versioned scaffold ownership and installed fingerprints. Forced
+  upgrades remove only unmodified obsolete Cortex-managed files, reject
+  modified or unsafe collisions, and preserve unknown files, configuration,
+  rules, ontology changes, Enterprise secrets, and agent instructions.
+- Extended release synchronization to keep the shipped MCP registry package
+  and Node runtime requirement aligned with `package.json`.
+
+### Upgrade
+
+- Upgrade the npm package, then run `cortex init --force`, `cortex bootstrap`,
+  and `cortex update`. Projects created before ownership state existed are
+  migrated only from hash-verified Cortex 2.4.1 scaffold files.
+
 ## 2.4.1 — 2026-07-28
 
 ### Security

package/README.md

@@ -108,6 +108,11 @@ per-user daemon; `cortex bootstrap` performs the verified restart.
 
 Version-specific notes (see [CHANGELOG.md](CHANGELOG.md) for details):
 
+- **2.4.2**: `cortex init --force` now uses versioned ownership metadata to
+  remove only unmodified obsolete Cortex-managed files. Unknown files and
+  protected configuration, rules, ontology, Enterprise, and agent-instruction
+  content remain user-owned; modified obsolete files and unsafe collisions
+  fail the upgrade instead of being overwritten or deleted.
 - **2.4.1**: enterprise onboarding no longer accepts API keys as positional
   arguments. Pipe the key to
   `sudo cortex enterprise install --api-key-stdin`. Enterprise endpoints must

package/bin/cli/arguments.mjs

@@ -0,0 +1,60 @@
+import path from "node:path";
+
+export function parseInitArgs(args) {
+  let target = process.cwd();
+  let force = false;
+  let bootstrap = false;
+  let connect = false;
+  let watch = true;
+
+  for (const arg of args) {
+    if (arg === "--force") {
+      force = true;
+      continue;
+    }
+    if (arg === "--bootstrap") {
+      bootstrap = true;
+      continue;
+    }
+    if (arg === "--connect") {
+      connect = true;
+      continue;
+    }
+    if (arg === "--no-connect") {
+      connect = false;
+      continue;
+    }
+    if (arg === "--watch") {
+      watch = true;
+      continue;
+    }
+    if (arg === "--no-watch") {
+      watch = false;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown init option: ${arg}`);
+    }
+    target = path.resolve(arg);
+  }
+
+  return { target, force, bootstrap, connect, watch };
+}
+
+export function parseConnectArgs(args) {
+  let target = process.cwd();
+  let skipBuild = false;
+
+  for (const arg of args) {
+    if (arg === "--skip-build") {
+      skipBuild = true;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown connect option: ${arg}`);
+    }
+    target = path.resolve(arg);
+  }
+
+  return { target, skipBuild };
+}

package/bin/cli/context-passthrough.mjs

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+import { restartDaemonAfterRuntimeUpgrade } from "./daemon.mjs";
+import { CONTEXT_SCRIPTS_REL } from "./paths.mjs";
+import { runCommand } from "./process.mjs";
+import {
+  ensureScaffoldExists,
+  hardenEnterpriseConfigPermissions,
+  initializeScaffold,
+  installAssistantHelpers,
+  isScaffoldOutOfDate,
+  isTruthyEnv,
+  maybeInstallGitHooks,
+} from "./scaffold.mjs";
+
+export const PASSTHROUGH_COMMANDS = new Set([
+  "bootstrap",
+  "update",
+  "status",
+  "ingest",
+  "embed",
+  "graph-load",
+  "dashboard",
+  "watch",
+  "refresh",
+  "memory-compile",
+  "memory-lint",
+  "doctor",
+]);
+
+const INDEX_MUTATING_COMMANDS = new Set([
+  "bootstrap",
+  "update",
+  "refresh",
+  "ingest",
+  "embed",
+  "graph-load",
+]);
+
+function invalidateSessionStatusCache(cwd) {
+  try {
+    fs.rmSync(
+      path.join(cwd, ".context", "cache", "session-status.json"),
+      { force: true },
+    );
+  } catch {
+    // Best effort: a stale cache only delays the status refresh.
+  }
+}
+
+export async function runContextCommand(cwd, contextArgs) {
+  const contextScript = path.join(cwd, CONTEXT_SCRIPTS_REL, "context.sh");
+  if (!fs.existsSync(contextScript)) {
+    throw new Error(`Missing ${contextScript}. Run 'cortex init' first.`);
+  }
+  try {
+    await runCommand("bash", [contextScript, ...contextArgs], cwd);
+  } finally {
+    if (INDEX_MUTATING_COMMANDS.has(contextArgs[0])) {
+      invalidateSessionStatusCache(cwd);
+    }
+  }
+}
+
+async function confirmPrompt(message) {
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+  try {
+    const answer = (await rl.question(message)).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+export async function maybeMigrateScaffold(targetDir, command) {
+  if (!isScaffoldOutOfDate(targetDir)) return;
+
+  const autoYes = isTruthyEnv(process.env.CORTEX_AUTO_MIGRATE);
+  const interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+
+  console.error(
+    `[cortex] scaffold in ${targetDir} is out of date ` +
+      `(missing .context/scripts/doctor.sh, context runtime package.json, doctor subcommand in context.sh, ` +
+      `or carries a legacy mcp/ directory at the project root).`,
+  );
+
+  let proceed = autoYes;
+  if (!autoYes) {
+    if (!interactive) {
+      throw new Error(
+        `Cortex CLI ${process.env.CORTEX_CLI_VERSION ?? ""} needs an updated scaffold to run '${command}'. ` +
+          `Run 'cortex init --bootstrap' to upgrade, or re-run with CORTEX_AUTO_MIGRATE=true.`,
+      );
+    }
+    proceed = await confirmPrompt(
+      "[cortex] Upgrade scaffold now (runs 'cortex init --bootstrap')? [y/N] ",
+    );
+  }
+
+  if (!proceed) {
+    throw new Error(
+      "Scaffold upgrade declined. Run 'cortex init --bootstrap' manually to continue.",
+    );
+  }
+
+  console.error(`[cortex] migrating scaffold in ${targetDir}`);
+  ensureScaffoldExists();
+  initializeScaffold(targetDir, true);
+  installAssistantHelpers(targetDir);
+  await maybeInstallGitHooks(targetDir);
+  await runContextCommand(targetDir, ["bootstrap"]);
+  console.error(`[cortex] scaffold upgraded; continuing with '${command}'`);
+}
+
+export async function runPassthroughCommand(command, rest) {
+  const cwd = process.cwd();
+  await maybeMigrateScaffold(cwd, command);
+  if (command === "bootstrap") {
+    hardenEnterpriseConfigPermissions(cwd);
+  }
+  await runContextCommand(cwd, [command, ...rest]);
+  if (command === "bootstrap") {
+    await restartDaemonAfterRuntimeUpgrade(cwd);
+  }
+}

package/bin/cli/daemon.mjs

@@ -0,0 +1,157 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import {
+  callDaemon,
+  probeVerifiedDaemon,
+  stopVerifiedDaemon,
+} from "../daemon-control.mjs";
+import { resolveDaemonEntry } from "./project-runtime.mjs";
+
+function daemonDirPath() {
+  return path.join(process.env.HOME || os.homedir(), ".cortex");
+}
+
+function daemonPidFilePath() {
+  return path.join(daemonDirPath(), "daemon.pid");
+}
+
+function pidFileExists() {
+  return fs.existsSync(daemonPidFilePath());
+}
+
+function readPid() {
+  try {
+    const raw = fs.readFileSync(daemonPidFilePath(), "utf8").trim();
+    const pid = Number.parseInt(raw, 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function isPidAlive(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err && typeof err === "object" && err.code === "EPERM") {
+      return true;
+    }
+    return false;
+  }
+}
+
+async function daemonControlDeps() {
+  return {
+    readPid,
+    isPidAlive,
+    call: callDaemon,
+  };
+}
+
+async function waitForVerifiedDaemon(deps, timeoutMs = 5_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const probe = await probeVerifiedDaemon(deps, 250);
+    if (probe.verified) return probe;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  return probeVerifiedDaemon(deps, 250);
+}
+
+export async function runDaemonCommand(args, options = {}) {
+  const sub = args[0] || "status";
+  const projectRoot = options.projectRoot || process.cwd();
+  const deps = await daemonControlDeps();
+  if (sub === "start") {
+    const existing = await probeVerifiedDaemon(deps);
+    if (existing.verified) {
+      console.log("Daemon already running.");
+      return;
+    }
+    if (existing.running) {
+      throw new Error(
+        `Refusing to replace unverified live pid ${existing.pid} (${existing.reason}).`,
+      );
+    }
+    const daemonDir = daemonDirPath();
+    fs.mkdirSync(daemonDir, { recursive: true });
+    const entry = resolveDaemonEntry(projectRoot);
+    if (!fs.existsSync(entry)) {
+      throw new Error(`Daemon entry not found: ${entry}. Build cortex first.`);
+    }
+    const logFd = fs.openSync(path.join(daemonDir, "daemon.log"), "a");
+    const child = spawn(process.execPath, [entry], {
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+      cwd: projectRoot,
+      env: { ...process.env, CORTEX_PROJECT_ROOT: projectRoot },
+    });
+    child.unref();
+    fs.closeSync(logFd);
+    const started = await waitForVerifiedDaemon(deps);
+    if (!started.verified) {
+      throw new Error(
+        `Daemon did not complete its verified socket handshake (${started.reason}).`,
+      );
+    }
+    console.log(
+      `Daemon started (pid=${started.pid}). Log: ${path.join(daemonDir, "daemon.log")}`,
+    );
+    return;
+  }
+  if (sub === "stop") {
+    const result = await stopVerifiedDaemon(deps);
+    if (!result.stopped) {
+      console.log("Daemon not running.");
+      return;
+    }
+    console.log(`Daemon stopped (verified pid=${result.pid}).`);
+    return;
+  }
+  if (sub === "restart") {
+    await stopVerifiedDaemon(deps);
+    await runDaemonCommand(["start"], { projectRoot });
+    return;
+  }
+  if (sub === "status") {
+    const probe = await probeVerifiedDaemon(deps);
+    if (probe.verified) {
+      console.log(`Daemon running (verified pid=${probe.pid})`);
+    } else if (probe.running) {
+      console.log(
+        `Daemon state unsafe: live pid=${probe.pid}, identity not verified (${probe.reason}).`,
+      );
+    } else {
+      console.log("Daemon not running.");
+      if (pidFileExists()) {
+        console.log(`(stale pid file at ${daemonPidFilePath()})`);
+      }
+    }
+    return;
+  }
+  throw new Error(
+    `Unknown daemon subcommand: ${sub}. Try start|stop|restart|status`,
+  );
+}
+
+export async function restartDaemonAfterRuntimeUpgrade(projectRoot) {
+  const daemonEntry = resolveDaemonEntry(projectRoot);
+  if (!fs.existsSync(daemonEntry)) return;
+  const deps = await daemonControlDeps();
+  const probe = await probeVerifiedDaemon(deps);
+  if (!probe.running) return;
+  if (!probe.verified) {
+    throw new Error(
+      `Runtime upgraded, but live pid ${probe.pid} could not be verified. ` +
+        "Refusing to signal it; stop it manually after confirming ownership.",
+    );
+  }
+  console.log(
+    `[cortex] restarting verified daemon pid=${probe.pid} to activate the upgraded runtime`,
+  );
+  await runDaemonCommand(["restart"], { projectRoot });
+}