@danielblomma/cortex-mcp 0.4.0

package/scaffold/scripts/plan-state-engine.cjs

@@ -0,0 +1,310 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const statePath = process.argv[2];
+const action = process.argv[3] || "show";
+const arg = process.argv[4] || "";
+
+const STEP_DEFS = [
+  {
+    id: "initialize",
+    title: "Initialize repository context",
+    command: "cortex init --bootstrap"
+  },
+  {
+    id: "connect",
+    title: "Connect MCP clients (Codex/Claude)",
+    command: "cortex connect"
+  },
+  {
+    id: "update",
+    title: "Refresh context while coding",
+    command: "cortex update"
+  },
+  {
+    id: "note",
+    title: "Capture decisions and TODOs",
+    command: "cortex note \"title\" \"details\""
+  }
+];
+
+const COMMAND_STEP_MAP = {
+  init: ["initialize"],
+  bootstrap: ["initialize", "update"],
+  connect: ["connect"],
+  update: ["update"],
+  refresh: ["update"],
+  ingest: ["update"],
+  embed: ["update"],
+  "graph-load": ["update"],
+  note: ["note"]
+};
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function createDefaultState(now) {
+  return {
+    version: 1,
+    created_at: now,
+    updated_at: now,
+    last_command: null,
+    current_step: STEP_DEFS[0].title,
+    next_command: STEP_DEFS[0].command,
+    steps: STEP_DEFS.map((step) => ({
+      id: step.id,
+      title: step.title,
+      command: step.command,
+      status: "pending",
+      updated_at: null
+    })),
+    history: [],
+    next_todo_id: 1,
+    todos: []
+  };
+}
+
+function loadState() {
+  if (!fs.existsSync(statePath)) {
+    return null;
+  }
+
+  const parsed = JSON.parse(fs.readFileSync(statePath, "utf8"));
+  if (!Array.isArray(parsed.steps)) {
+    throw new Error("Invalid plan state: steps is missing");
+  }
+
+  if (!Array.isArray(parsed.history)) {
+    parsed.history = [];
+  }
+
+  if (!Array.isArray(parsed.todos)) {
+    parsed.todos = [];
+  }
+
+  if (!Number.isInteger(parsed.next_todo_id) || parsed.next_todo_id < 1) {
+    parsed.next_todo_id = parsed.todos.reduce((max, todo) => Math.max(max, Number(todo.id) || 0), 0) + 1;
+  }
+
+  for (const def of STEP_DEFS) {
+    if (!parsed.steps.find((step) => step.id === def.id)) {
+      parsed.steps.push({
+        id: def.id,
+        title: def.title,
+        command: def.command,
+        status: "pending",
+        updated_at: null
+      });
+    }
+  }
+
+  return parsed;
+}
+
+function saveState(state) {
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  fs.writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+function updateDerivedFields(state) {
+  const nextStep = state.steps.find((step) => step.status !== "completed");
+  if (nextStep) {
+    state.current_step = nextStep.title;
+    state.next_command = nextStep.command;
+    return;
+  }
+
+  state.current_step = "Keep context fresh and capture decisions/TODOs";
+  state.next_command = "cortex update";
+}
+
+function appendHistory(state, command, at) {
+  state.last_command = {
+    name: command,
+    at
+  };
+  state.history.unshift({ command, at });
+  state.history = state.history.slice(0, 100);
+}
+
+function markStepCompleted(state, stepId, at) {
+  const step = state.steps.find((item) => item.id === stepId);
+  if (!step) {
+    return;
+  }
+  step.status = "completed";
+  step.updated_at = at;
+}
+
+function ensureState() {
+  const existing = loadState();
+  if (existing) {
+    return existing;
+  }
+  const now = nowIso();
+  const created = createDefaultState(now);
+  saveState(created);
+  return created;
+}
+
+function parseTodoId(raw) {
+  const cleaned = String(raw || "").trim().replace(/^#/, "");
+  const parsed = Number(cleaned);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    return null;
+  }
+  return parsed;
+}
+
+function printSummary(state) {
+  const openTodos = state.todos.filter((todo) => todo.status === "open");
+  const doneTodos = state.todos.filter((todo) => todo.status === "done");
+  const stepState = state.steps.map((step) => `${step.id}=${step.status}`).join(" ");
+
+  console.log(`[plan] current_step=${state.current_step}`);
+  console.log(`[plan] next_command=${state.next_command}`);
+  console.log(`[plan] steps ${stepState}`);
+
+  if (state.last_command && state.last_command.name) {
+    console.log(`[plan] last_command=${state.last_command.name} at=${state.last_command.at}`);
+  }
+
+  console.log(`[todo] open=${openTodos.length} done=${doneTodos.length}`);
+  if (openTodos.length > 0) {
+    console.log(`[todo] next=#${openTodos[0].id} ${openTodos[0].text}`);
+  }
+}
+
+try {
+  if (action === "ensure") {
+    ensureState();
+    process.exit(0);
+  }
+
+  if (action === "reset") {
+    const now = nowIso();
+    const reset = createDefaultState(now);
+    saveState(reset);
+    console.log(`[plan] reset ${statePath}`);
+    process.exit(0);
+  }
+
+  const state = ensureState();
+  const now = nowIso();
+
+  if (action === "event") {
+    const commandName = arg.trim();
+    if (!commandName) {
+      throw new Error("Usage: plan-state.sh event <command>");
+    }
+
+    const stepsToMark = COMMAND_STEP_MAP[commandName] || [];
+    for (const stepId of stepsToMark) {
+      markStepCompleted(state, stepId, now);
+    }
+
+    appendHistory(state, commandName, now);
+    state.updated_at = now;
+    updateDerivedFields(state);
+    saveState(state);
+    process.exit(0);
+  }
+
+  if (action === "show") {
+    updateDerivedFields(state);
+    printSummary(state);
+    process.exit(0);
+  }
+
+  if (action === "todo-add") {
+    const text = arg.trim();
+    if (!text) {
+      throw new Error('Usage: plan-state.sh todo add "<text>"');
+    }
+
+    const todo = {
+      id: state.next_todo_id,
+      text,
+      status: "open",
+      created_at: now,
+      updated_at: now,
+      completed_at: null
+    };
+
+    state.todos.push(todo);
+    state.next_todo_id += 1;
+    markStepCompleted(state, "note", now);
+    appendHistory(state, "todo:add", now);
+    state.updated_at = now;
+    updateDerivedFields(state);
+    saveState(state);
+    console.log(`[todo] added #${todo.id} ${todo.text}`);
+    process.exit(0);
+  }
+
+  if (action === "todo-list") {
+    const openTodos = state.todos.filter((todo) => todo.status === "open");
+    const doneTodos = state.todos.filter((todo) => todo.status === "done");
+
+    if (openTodos.length === 0 && doneTodos.length === 0) {
+      console.log("[todo] no todos");
+      process.exit(0);
+    }
+
+    for (const todo of openTodos) {
+      console.log(`[todo] [open] #${todo.id} ${todo.text}`);
+    }
+    for (const todo of doneTodos) {
+      console.log(`[todo] [done] #${todo.id} ${todo.text}`);
+    }
+    process.exit(0);
+  }
+
+  if (action === "todo-done" || action === "todo-reopen" || action === "todo-remove") {
+    const todoId = parseTodoId(arg);
+    if (!todoId) {
+      throw new Error("Usage: plan-state.sh todo <done|reopen|remove> <id>");
+    }
+
+    const index = state.todos.findIndex((todo) => Number(todo.id) === todoId);
+    if (index === -1) {
+      throw new Error(`TODO #${todoId} not found`);
+    }
+
+    const todo = state.todos[index];
+    if (action === "todo-remove") {
+      state.todos.splice(index, 1);
+      appendHistory(state, "todo:remove", now);
+      state.updated_at = now;
+      updateDerivedFields(state);
+      saveState(state);
+      console.log(`[todo] removed #${todoId}`);
+      process.exit(0);
+    }
+
+    if (action === "todo-done") {
+      todo.status = "done";
+      todo.completed_at = now;
+      appendHistory(state, "todo:done", now);
+      console.log(`[todo] done #${todoId} ${todo.text}`);
+    } else {
+      todo.status = "open";
+      todo.completed_at = null;
+      appendHistory(state, "todo:reopen", now);
+      console.log(`[todo] reopened #${todoId} ${todo.text}`);
+    }
+
+    todo.updated_at = now;
+    state.updated_at = now;
+    updateDerivedFields(state);
+    saveState(state);
+    process.exit(0);
+  }
+
+  throw new Error(`Unknown plan-state action: ${action}`);
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}

package/scaffold/scripts/plan-state.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLAN_DIR="$REPO_ROOT/.context/plan"
+STATE_FILE="$PLAN_DIR/state.json"
+
+SUBCOMMAND="${1:-show}"
+if [[ $# -gt 0 ]]; then
+  shift
+fi
+
+run_state_tool() {
+  node "$SCRIPT_DIR/plan-state-engine.cjs" "$STATE_FILE" "$@"
+}
+
+mkdir -p "$PLAN_DIR"
+
+case "$SUBCOMMAND" in
+  show)
+    run_state_tool show
+    ;;
+  event)
+    EVENT_NAME="${1:-}"
+    if [[ -z "$EVENT_NAME" ]]; then
+      echo "Usage: plan-state.sh event <command-name>"
+      exit 1
+    fi
+    run_state_tool event "$EVENT_NAME"
+    ;;
+  reset)
+    run_state_tool reset
+    ;;
+  todo)
+    TODO_ACTION="${1:-list}"
+    if [[ $# -gt 0 ]]; then
+      shift
+    fi
+    case "$TODO_ACTION" in
+      add)
+        TODO_TEXT="${*:-}"
+        run_state_tool todo-add "$TODO_TEXT"
+        ;;
+      list)
+        run_state_tool todo-list
+        ;;
+      done)
+        TODO_ID="${1:-}"
+        run_state_tool todo-done "$TODO_ID"
+        ;;
+      reopen)
+        TODO_ID="${1:-}"
+        run_state_tool todo-reopen "$TODO_ID"
+        ;;
+      remove)
+        TODO_ID="${1:-}"
+        run_state_tool todo-remove "$TODO_ID"
+        ;;
+      *)
+        # Keep ergonomic behavior: unknown first token is treated as todo text.
+        run_state_tool todo-add "$TODO_ACTION ${*:-}"
+        ;;
+    esac
+    ;;
+  *)
+    echo "Unknown subcommand: $SUBCOMMAND"
+    echo "Usage: plan-state.sh [show|event <name>|reset|todo <action> [args]]"
+    exit 1
+    ;;
+esac

package/scaffold/scripts/refresh.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+echo "[refresh] running ingestion"
+"$REPO_ROOT/scripts/ingest.sh" "$@"
+
+echo "[refresh] done"

package/scaffold/scripts/status.sh

@@ -0,0 +1,282 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MANIFEST="$REPO_ROOT/.context/cache/manifest.json"
+GRAPH_MANIFEST="$REPO_ROOT/.context/cache/graph-manifest.json"
+EMBED_MANIFEST="$REPO_ROOT/.context/embeddings/manifest.json"
+
+if [[ ! -f "$MANIFEST" ]]; then
+  echo "[status] No ingest manifest found."
+  echo "[status] Run: ./scripts/context.sh ingest"
+  exit 0
+fi
+
+node -e '
+const fs = require("node:fs");
+const manifestPath = process.argv[1];
+const data = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+console.log(`[status] generated_at=${data.generated_at}`);
+console.log(`[status] mode=${data.mode}`);
+console.log(`[status] source_paths=${(data.source_paths || []).join(", ")}`);
+const c = data.counts || {};
+console.log(`[status] files=${c.files ?? 0} adrs=${c.adrs ?? 0} rules=${c.rules ?? 0}`);
+console.log(`[status] rels constrains=${c.relations_constrains ?? 0} implements=${c.relations_implements ?? 0} supersedes=${c.relations_supersedes ?? 0}`);
+const s = data.skipped || {};
+console.log(`[status] skipped unsupported=${s.unsupported ?? 0} too_large=${s.too_large ?? s.tooLarge ?? 0} binary=${s.binary ?? 0}`);
+if (typeof data.incremental_mode === "boolean") {
+  console.log(`[status] incremental_mode=${data.incremental_mode} changed_candidates=${data.changed_candidates ?? 0} deleted_paths=${data.deleted_paths ?? 0}`);
+}
+' "$MANIFEST"
+
+if [[ -f "$GRAPH_MANIFEST" ]]; then
+  node -e '
+const fs = require("node:fs");
+const graphManifestPath = process.argv[1];
+const data = JSON.parse(fs.readFileSync(graphManifestPath, "utf8"));
+const c = data.counts || {};
+console.log(`[status] graph generated_at=${data.generated_at}`);
+console.log(`[status] graph files=${c.files ?? 0} rules=${c.rules ?? 0} adrs=${c.adrs ?? 0}`);
+console.log(`[status] graph rels constrains=${c.constrains ?? 0} implements=${c.implements ?? 0} supersedes=${c.supersedes ?? 0}`);
+' "$GRAPH_MANIFEST"
+else
+  echo "[status] graph manifest missing (run: ./scripts/context.sh graph-load)"
+fi
+
+if [[ -f "$EMBED_MANIFEST" ]]; then
+  node -e '
+const fs = require("node:fs");
+const embedManifestPath = process.argv[1];
+const data = JSON.parse(fs.readFileSync(embedManifestPath, "utf8"));
+const c = data.counts || {};
+console.log(`[status] embeddings generated_at=${data.generated_at}`);
+console.log(`[status] embeddings model=${data.model} dim=${data.dimensions ?? 0}`);
+console.log(`[status] embeddings entities=${c.entities ?? 0} output=${c.output ?? 0} embedded=${c.embedded ?? 0} reused=${c.reused ?? 0} failed=${c.failed ?? 0}`);
+' "$EMBED_MANIFEST"
+else
+  echo "[status] embeddings manifest missing (run: ./scripts/context.sh embed)"
+fi
+
+node -e '
+const fs = require("node:fs");
+const path = require("node:path");
+const { execSync } = require("node:child_process");
+
+const repoRoot = process.argv[1];
+const manifestPath = process.argv[2];
+
+function toPosixPath(value) {
+  return value.split(path.sep).join("/");
+}
+
+function normalizeSource(sourcePath) {
+  const source = toPosixPath(sourcePath).replace(/\/+$/, "");
+  if (source === ".") {
+    return "";
+  }
+  return source;
+}
+
+function hasSourcePrefix(relPath, sourcePaths) {
+  return sourcePaths.some((sourcePath) => {
+    const source = normalizeSource(sourcePath);
+    if (source === "") {
+      return true;
+    }
+    return relPath === source || relPath.startsWith(`${source}/`);
+  });
+}
+
+function parseChangedPaths() {
+  const output = execSync("git status --porcelain", {
+    cwd: repoRoot,
+    stdio: ["ignore", "pipe", "ignore"],
+    encoding: "utf8"
+  });
+
+  const changed = new Set();
+  const deleted = new Set();
+
+  for (const rawLine of output.split(/\r?\n/)) {
+    if (!rawLine) continue;
+    const status = rawLine.slice(0, 2);
+    const payload = rawLine.slice(3).trim();
+    if (!payload) continue;
+
+    if (payload.includes(" -> ")) {
+      const [fromPath, toPath] = payload.split(" -> ");
+      deleted.add(path.resolve(repoRoot, fromPath));
+      changed.add(path.resolve(repoRoot, toPath));
+      continue;
+    }
+
+    const absolutePath = path.resolve(repoRoot, payload);
+    if (status.includes("D")) {
+      deleted.add(absolutePath);
+    } else {
+      changed.add(absolutePath);
+    }
+  }
+
+  return { changed, deleted };
+}
+
+function createBar(ratio, size = 20) {
+  const clamped = Math.max(0, Math.min(1, ratio));
+  const filled = Math.round(clamped * size);
+  return `[${"#".repeat(filled)}${"-".repeat(size - filled)}]`;
+}
+
+try {
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  const sourcePaths = Array.isArray(manifest.source_paths) ? manifest.source_paths : [];
+  const indexedFiles = Number(manifest?.counts?.files ?? 0);
+
+  const { changed, deleted } = parseChangedPaths();
+  let relevantChanged = 0;
+  let relevantDeleted = 0;
+
+  for (const absolutePath of changed) {
+    const relPath = toPosixPath(path.relative(repoRoot, absolutePath));
+    if (!relPath || relPath.startsWith("..")) continue;
+    if (relPath.startsWith(".context/")) continue;
+    if (hasSourcePrefix(relPath, sourcePaths)) {
+      relevantChanged += 1;
+    }
+  }
+
+  for (const absolutePath of deleted) {
+    const relPath = toPosixPath(path.relative(repoRoot, absolutePath));
+    if (!relPath || relPath.startsWith("..")) continue;
+    if (relPath.startsWith(".context/")) continue;
+    if (hasSourcePrefix(relPath, sourcePaths)) {
+      relevantDeleted += 1;
+    }
+  }
+
+  const pending = relevantChanged + relevantDeleted;
+  const baseline = Math.max(indexedFiles, pending, 1);
+  const freshness = Math.max(0, (baseline - pending) / baseline);
+  const freshnessPercent = Math.round(freshness * 100);
+  const bar = createBar(freshness);
+
+  console.log(`[status] freshness ${bar} ${freshnessPercent}%`);
+  if (pending === 0) {
+    console.log("[status] update_needed=no");
+    console.log("[status] context is up to date with current source changes");
+  } else {
+    console.log(`[status] update_needed=yes changed=${relevantChanged} deleted=${relevantDeleted}`);
+    console.log("[status] run: cortex update");
+  }
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.log(`[status] freshness unavailable (${message})`);
+}
+' "$REPO_ROOT" "$MANIFEST"
+
+node -e '
+const path = require("node:path");
+const { execSync } = require("node:child_process");
+
+const repoRoot = process.argv[1];
+const cacheDir = process.argv[2];
+const localVersionEnv = process.argv[3] || "";
+
+function parseVersion(value) {
+  const match = String(value || "").trim().match(/^v?(\d+)\.(\d+)\.(\d+)$/);
+  if (!match) return null;
+  return match.slice(1).map((part) => Number(part));
+}
+
+function compareVersions(a, b) {
+  for (let i = 0; i < 3; i += 1) {
+    if (a[i] > b[i]) return 1;
+    if (a[i] < b[i]) return -1;
+  }
+  return 0;
+}
+
+function getLocalVersion() {
+  const envVersion = String(localVersionEnv || "").trim();
+  if (parseVersion(envVersion)) {
+    return envVersion;
+  }
+
+  try {
+    const output = execSync("cortex --version", {
+      cwd: repoRoot,
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf8",
+      timeout: 1500
+    }).trim();
+    if (parseVersion(output)) {
+      return output;
+    }
+  } catch {
+    // Ignore and report unavailable below.
+  }
+
+  return "";
+}
+
+try {
+  const localVersion = getLocalVersion();
+  if (!localVersion) {
+    console.log("[status] cortex_update_check=unavailable (local version not detected)");
+    process.exit(0);
+  }
+
+  console.log(`[status] cortex_cli_version=${localVersion}`);
+
+  const summarizeError = (error) => {
+    const raw = error instanceof Error ? error.message : String(error);
+    return raw.split(/\r?\n/)[0].trim();
+  };
+
+  const npmCache = path.join(cacheDir, "npm-cache");
+  let latestRaw = "";
+  try {
+    latestRaw = execSync("npm view github:DanielBlomma/cortex version --json", {
+      cwd: repoRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf8",
+      timeout: 2500,
+      env: { ...process.env, NPM_CONFIG_CACHE: npmCache }
+    }).trim();
+  } catch (error) {
+    console.log(`[status] cortex_update_check=unavailable (${summarizeError(error)})`);
+    process.exit(0);
+  }
+
+  const parsedLatest = JSON.parse(latestRaw);
+  const latestVersion = Array.isArray(parsedLatest) ? parsedLatest[parsedLatest.length - 1] : parsedLatest;
+
+  const localParsed = parseVersion(localVersion);
+  const latestParsed = parseVersion(latestVersion);
+  if (!localParsed || !latestParsed) {
+    console.log(`[status] cortex_latest_version=${latestVersion}`);
+    console.log("[status] cortex_update_check=unavailable (unsupported version format)");
+    process.exit(0);
+  }
+
+  const hasUpdate = compareVersions(latestParsed, localParsed) > 0;
+  console.log(`[status] cortex_latest_version=${latestVersion}`);
+
+  if (hasUpdate) {
+    console.log("[status] cortex_update_available=yes");
+    console.log("[status] run: npm i -g github:DanielBlomma/cortex");
+  } else {
+    console.log("[status] cortex_update_available=no");
+  }
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.log(`[status] cortex_update_check=unavailable (${message})`);
+}
+' "$REPO_ROOT" "$REPO_ROOT/.context/cache" "${CORTEX_CLI_VERSION:-}"
+
+PLAN_SCRIPT="$REPO_ROOT/scripts/plan-state.sh"
+if [[ -x "$PLAN_SCRIPT" ]]; then
+  if ! "$PLAN_SCRIPT" show; then
+    echo "[plan] warning: failed to read plan state"
+  fi
+fi

package/scaffold/scripts/update-context.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+echo "[update] ingesting changed files"
+"$REPO_ROOT/scripts/ingest.sh" --changed
+
+echo "[update] embedding changed entities"
+if ! "$REPO_ROOT/scripts/embed.sh" --changed; then
+  echo "[update] warning: embedding generation failed; continuing with lexical search fallback"
+fi
+
+echo "[update] rebuilding graph"
+"$REPO_ROOT/scripts/load-ryu.sh"
+
+echo "[update] status"
+"$REPO_ROOT/scripts/status.sh"