@danielblomma/cortex-mcp 1.7.2 → 2.0.3

package/scaffold/mcp/src/enterprise/workflow/state.ts

@@ -0,0 +1,535 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import type {
+  ReviewOutput,
+  ReviewResult,
+  ReviewSummary,
+} from "../../core/validators/engine.js";
+
+export type WorkflowPhase =
+  | "planning"
+  | "plan_review"
+  | "implementation_pending"
+  | "implementation"
+  | "iterating"
+  | "reviewed"
+  | "approved";
+
+export type WorkflowPlanStatus =
+  | "missing"
+  | "pending_review"
+  | "changes_requested"
+  | "approved";
+
+export type WorkflowReviewStatus = "not_run" | "failed" | "passed";
+export type WorkflowApprovalStatus = "blocked" | "ready" | "approved";
+
+export type WorkflowBlocker = {
+  code:
+    | "plan_missing"
+    | "plan_not_approved"
+    | "implementation_not_started"
+    | "code_review_required"
+    | "review_failed";
+  message: string;
+};
+
+export type WorkflowPlan = {
+  title: string | null;
+  summary: string | null;
+  tasks: string[];
+  status: WorkflowPlanStatus;
+  updated_at: string | null;
+  reviewed_at: string | null;
+  review_notes: string | null;
+};
+
+export type WorkflowReviewSnapshot = {
+  status: WorkflowReviewStatus;
+  scope: "all" | "changed" | null;
+  reviewed_at: string | null;
+  artifact_path: string | null;
+  summary: ReviewSummary | null;
+  failed_policies: string[];
+  warning_policies: string[];
+  reviewed_files: WorkflowReviewedFileSnapshot[] | null;
+};
+
+export type WorkflowApproval = {
+  status: WorkflowApprovalStatus;
+  approved_at: string | null;
+  notes: string | null;
+};
+
+export type WorkflowNote = {
+  id: number;
+  title: string;
+  details: string;
+  created_at: string;
+};
+
+export type WorkflowTodo = {
+  id: number;
+  title: string;
+  details: string;
+  status: "open" | "done";
+  created_at: string;
+  updated_at: string;
+};
+
+export type WorkflowHistoryEntry = {
+  at: string;
+  event:
+    | "plan_set"
+    | "plan_reviewed"
+    | "implementation_started"
+    | "review_recorded"
+    | "workflow_updated"
+    | "workflow_approved"
+    | "note_added"
+    | "todo_added"
+    | "todo_completed";
+  details?: Record<string, unknown>;
+};
+
+export type WorkflowState = {
+  version: 1;
+  created_at: string;
+  updated_at: string;
+  phase: WorkflowPhase;
+  blocked_reasons: WorkflowBlocker[];
+  plan: WorkflowPlan;
+  last_review: WorkflowReviewSnapshot;
+  approval: WorkflowApproval;
+  next_note_id: number;
+  next_todo_id: number;
+  notes: WorkflowNote[];
+  todos: WorkflowTodo[];
+  history: WorkflowHistoryEntry[];
+};
+
+export type WorkflowMutationResult = {
+  ok: boolean;
+  state: WorkflowState;
+  error?: string;
+};
+
+type WorkflowReviewArtifact = {
+  recorded_at: string;
+  scope: "all" | "changed";
+  summary: ReviewSummary;
+  results: ReviewResult[];
+  reviewed_files: WorkflowReviewedFileSnapshot[] | null;
+};
+
+export type WorkflowReviewedFileSnapshot = {
+  path: string;
+  exists: boolean;
+  hash: string | null;
+};
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function workflowDir(contextDir: string): string {
+  return join(contextDir, "workflow");
+}
+
+function workflowStatePath(contextDir: string): string {
+  return join(workflowDir(contextDir), "state.json");
+}
+
+function workflowReviewsDir(contextDir: string): string {
+  return join(workflowDir(contextDir), "reviews");
+}
+
+function initialState(): WorkflowState {
+  const now = nowIso();
+  return {
+    version: 1,
+    created_at: now,
+    updated_at: now,
+    phase: "planning",
+    blocked_reasons: [
+      {
+        code: "plan_missing",
+        message: "A plan must be created before implementation can begin.",
+      },
+      {
+        code: "code_review_required",
+        message: "A passing code review is required before approval.",
+      },
+    ],
+    plan: {
+      title: null,
+      summary: null,
+      tasks: [],
+      status: "missing",
+      updated_at: null,
+      reviewed_at: null,
+      review_notes: null,
+    },
+    last_review: {
+      status: "not_run",
+      scope: null,
+      reviewed_at: null,
+      artifact_path: null,
+      summary: null,
+      failed_policies: [],
+      warning_policies: [],
+      reviewed_files: null,
+    },
+    approval: {
+      status: "blocked",
+      approved_at: null,
+      notes: null,
+    },
+    next_note_id: 1,
+    next_todo_id: 1,
+    notes: [],
+    todos: [],
+    history: [],
+  };
+}
+
+function ensureWorkflowDirs(contextDir: string): void {
+  mkdirSync(workflowReviewsDir(contextDir), { recursive: true });
+}
+
+function clampHistory(history: WorkflowHistoryEntry[]): WorkflowHistoryEntry[] {
+  return history.slice(-100);
+}
+
+function blockersFor(state: WorkflowState): WorkflowBlocker[] {
+  const blockers: WorkflowBlocker[] = [];
+
+  if (!state.plan.title || state.plan.status === "missing") {
+    blockers.push({
+      code: "plan_missing",
+      message: "A plan must be created before implementation can begin.",
+    });
+  }
+
+  if (state.plan.status !== "approved") {
+    blockers.push({
+      code: "plan_not_approved",
+      message: "The plan must be reviewed and approved before approval.",
+    });
+  }
+
+  if (!state.history.some((entry) => entry.event === "implementation_started")) {
+    blockers.push({
+      code: "implementation_not_started",
+      message: "Implementation has not started yet.",
+    });
+  }
+
+  if (state.last_review.status === "not_run") {
+    blockers.push({
+      code: "code_review_required",
+      message: "A passing code review is required before approval.",
+    });
+  }
+
+  if (state.last_review.status === "failed") {
+    blockers.push({
+      code: "review_failed",
+      message: "The latest code review failed and must be resolved before approval.",
+    });
+  }
+
+  return blockers;
+}
+
+function withRecalculatedApproval(
+  state: WorkflowState,
+  preserveApproved = false
+): WorkflowState {
+  const blockers = blockersFor(state);
+  state.blocked_reasons = blockers;
+
+  if (blockers.length > 0) {
+    state.approval = {
+      status: "blocked",
+      approved_at: null,
+      notes: null,
+    };
+    return state;
+  }
+
+  if (preserveApproved && state.approval.status === "approved") {
+    state.approval.status = "approved";
+    return state;
+  }
+
+  state.approval = {
+    status: "ready",
+    approved_at: null,
+    notes: null,
+  };
+  return state;
+}
+
+function writeState(
+  contextDir: string,
+  state: WorkflowState,
+  touchUpdatedAt = true
+): WorkflowState {
+  ensureWorkflowDirs(contextDir);
+  if (touchUpdatedAt) {
+    state.updated_at = nowIso();
+  }
+  state.history = clampHistory(state.history);
+  writeFileSync(workflowStatePath(contextDir), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+  return state;
+}
+
+export function loadWorkflowState(contextDir: string): WorkflowState {
+  ensureWorkflowDirs(contextDir);
+  const statePath = workflowStatePath(contextDir);
+  if (!existsSync(statePath)) {
+    return writeState(contextDir, initialState());
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(statePath, "utf8")) as WorkflowState;
+    return withRecalculatedApproval(parsed, true);
+  } catch {
+    return writeState(contextDir, initialState());
+  }
+}
+
+function addHistory(
+  state: WorkflowState,
+  event: WorkflowHistoryEntry["event"],
+  details?: Record<string, unknown>
+): void {
+  state.history.push({
+    at: nowIso(),
+    event,
+    details,
+  });
+}
+
+export function setWorkflowPlan(
+  contextDir: string,
+  input: { title: string; summary: string; tasks?: string[] }
+): WorkflowState {
+  const state = loadWorkflowState(contextDir);
+  state.phase = "plan_review";
+  state.plan = {
+    title: input.title,
+    summary: input.summary,
+    tasks: input.tasks?.filter(Boolean) ?? [],
+    status: "pending_review",
+    updated_at: nowIso(),
+    reviewed_at: null,
+    review_notes: null,
+  };
+  state.last_review = {
+    status: "not_run",
+    scope: null,
+    reviewed_at: null,
+    artifact_path: null,
+    summary: null,
+    failed_policies: [],
+    warning_policies: [],
+    reviewed_files: null,
+  };
+  addHistory(state, "plan_set", {
+    title: input.title,
+    task_count: state.plan.tasks.length,
+  });
+  return writeState(contextDir, withRecalculatedApproval(state));
+}
+
+export function reviewWorkflowPlan(
+  contextDir: string,
+  input: { approved: boolean; notes?: string }
+): WorkflowMutationResult {
+  const state = loadWorkflowState(contextDir);
+  if (!state.plan.title) {
+    return { ok: false, state, error: "No plan exists to review" };
+  }
+
+  state.plan.status = input.approved ? "approved" : "changes_requested";
+  state.plan.reviewed_at = nowIso();
+  state.plan.review_notes = input.notes?.trim() || null;
+  state.phase = input.approved ? "implementation_pending" : "planning";
+  addHistory(state, "plan_reviewed", {
+    approved: input.approved,
+  });
+  return { ok: true, state: writeState(contextDir, withRecalculatedApproval(state)) };
+}
+
+export function startWorkflowImplementation(
+  contextDir: string
+): WorkflowMutationResult {
+  const state = loadWorkflowState(contextDir);
+  if (state.plan.status !== "approved") {
+    return {
+      ok: false,
+      state,
+      error: "Plan must be approved before implementation can start",
+    };
+  }
+
+  state.phase = "implementation";
+  addHistory(state, "implementation_started");
+  return { ok: true, state: writeState(contextDir, withRecalculatedApproval(state)) };
+}
+
+export function recordWorkflowReview(
+  contextDir: string,
+  input: {
+    scope: "all" | "changed";
+    output: ReviewOutput;
+    reviewed_files?: WorkflowReviewedFileSnapshot[] | null;
+  }
+): WorkflowState {
+  const state = loadWorkflowState(contextDir);
+  const recordedAt = nowIso();
+  const blockingFailures = input.output.results.filter(
+    (result) => !result.pass && result.severity === "error"
+  );
+  const warningFailures = input.output.results.filter(
+    (result) => !result.pass && result.severity === "warning"
+  );
+  const hasBlockingFailures = blockingFailures.length > 0;
+  const fileName = `review-${recordedAt.replace(/[:.]/g, "-")}.json`;
+  const relativeArtifactPath = `.context/workflow/reviews/${fileName}`;
+  const artifact: WorkflowReviewArtifact = {
+    recorded_at: recordedAt,
+    scope: input.scope,
+    summary: input.output.summary,
+    results: input.output.results,
+    reviewed_files: input.reviewed_files ?? null,
+  };
+
+  ensureWorkflowDirs(contextDir);
+  writeFileSync(
+    join(workflowReviewsDir(contextDir), fileName),
+    `${JSON.stringify(artifact, null, 2)}\n`,
+    "utf8"
+  );
+
+  state.last_review = {
+    status: hasBlockingFailures ? "failed" : "passed",
+    scope: input.scope,
+    reviewed_at: recordedAt,
+    artifact_path: relativeArtifactPath,
+    summary: input.output.summary,
+    failed_policies: blockingFailures.map((result) => result.policy_id),
+    warning_policies: warningFailures.map((result) => result.policy_id),
+    reviewed_files: input.reviewed_files ?? null,
+  };
+  state.phase = hasBlockingFailures ? "iterating" : "reviewed";
+  addHistory(state, "review_recorded", {
+    scope: input.scope,
+    total: input.output.summary.total,
+    failed: blockingFailures.length,
+    warnings: warningFailures.length,
+  });
+  return writeState(contextDir, withRecalculatedApproval(state));
+}
+
+export function recordWorkflowUpdate(
+  contextDir: string,
+  input: { summary: string; phase?: "implementation" | "iterating" | "plan_review" }
+): WorkflowState {
+  const state = loadWorkflowState(contextDir);
+  if (input.phase) {
+    state.phase = input.phase;
+  }
+  addHistory(state, "workflow_updated", {
+    summary: input.summary,
+    phase: input.phase ?? state.phase,
+  });
+  return writeState(
+    contextDir,
+    withRecalculatedApproval(state, input.phase === undefined)
+  );
+}
+
+export function addWorkflowNote(
+  contextDir: string,
+  input: { title: string; details: string }
+): WorkflowState {
+  const state = loadWorkflowState(contextDir);
+  const note: WorkflowNote = {
+    id: state.next_note_id++,
+    title: input.title,
+    details: input.details,
+    created_at: nowIso(),
+  };
+  state.notes.push(note);
+  addHistory(state, "note_added", { note_id: note.id, title: note.title });
+  return writeState(contextDir, withRecalculatedApproval(state, true));
+}
+
+export function addWorkflowTodo(
+  contextDir: string,
+  input: { title: string; details?: string }
+): WorkflowState {
+  const state = loadWorkflowState(contextDir);
+  const now = nowIso();
+  const todo: WorkflowTodo = {
+    id: state.next_todo_id++,
+    title: input.title,
+    details: input.details?.trim() || "",
+    status: "open",
+    created_at: now,
+    updated_at: now,
+  };
+  state.todos.push(todo);
+  addHistory(state, "todo_added", { todo_id: todo.id, title: todo.title });
+  return writeState(contextDir, withRecalculatedApproval(state, true));
+}
+
+export function completeWorkflowTodo(
+  contextDir: string,
+  todoId: number
+): WorkflowMutationResult {
+  const state = loadWorkflowState(contextDir);
+  const todo = state.todos.find((item) => item.id === todoId);
+  if (!todo) {
+    return { ok: false, state, error: `Todo ${todoId} was not found` };
+  }
+
+  todo.status = "done";
+  todo.updated_at = nowIso();
+  addHistory(state, "todo_completed", { todo_id: todo.id });
+  return { ok: true, state: writeState(contextDir, withRecalculatedApproval(state, true)) };
+}
+
+export function approveWorkflow(
+  contextDir: string,
+  notes?: string
+): WorkflowMutationResult {
+  const state = loadWorkflowState(contextDir);
+  const blockers = blockersFor(state);
+  if (blockers.length > 0) {
+    const refreshed = writeState(contextDir, withRecalculatedApproval(state));
+    return {
+      ok: false,
+      state: refreshed,
+      error: blockers.map((blocker) => blocker.message).join(" "),
+    };
+  }
+
+  state.phase = "approved";
+  state.blocked_reasons = [];
+  state.approval = {
+    status: "approved",
+    approved_at: nowIso(),
+    notes: notes?.trim() || null,
+  };
+  addHistory(state, "workflow_approved");
+  return { ok: true, state: writeState(contextDir, state) };
+}

package/scaffold/mcp/src/hooks/pre-compact.ts

@@ -0,0 +1,54 @@
+import { call } from "../daemon/client.js";
+import type { AuditLogPayload, AuditLogResult } from "../daemon/protocol.js";
+import {
+  ensureDaemon,
+  parseInput,
+  readStdin,
+  resolveDaemonEntry,
+} from "./shared.js";
+
+/**
+ * PreCompact hook. Fires just before Claude Code compresses session
+ * context. Ideal moment to snapshot session-summary for audit so we
+ * preserve a record of activity that's about to be truncated from
+ * Claude's working memory.
+ */
+
+type ClaudePreCompactInput = {
+  session_id?: string;
+  cwd?: string;
+  // Claude Code may send context size hints; we record what we get.
+  context_size_tokens?: number;
+};
+
+async function main(): Promise<void> {
+  const raw = await readStdin();
+  const input = parseInput(raw) as ClaudePreCompactInput;
+  const cwd = input.cwd ?? process.cwd();
+
+  ensureDaemon(resolveDaemonEntry(import.meta.url));
+
+  const payload: AuditLogPayload = {
+    cwd,
+    entry: {
+      timestamp: new Date().toISOString(),
+      tool: "session.pre_compact",
+      input: {
+        session_id: input.session_id ?? null,
+        context_size_tokens: input.context_size_tokens ?? null,
+      },
+      event_type: "session",
+      evidence_level: "diagnostic",
+      resource_type: "session",
+      session_id: input.session_id,
+      metadata: {
+        context_size_tokens: input.context_size_tokens ?? null,
+      },
+    },
+  };
+
+  await call<AuditLogResult>("audit.log", payload, { timeoutMs: 3000 });
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/scaffold/mcp/src/hooks/pre-tool-use.ts

@@ -0,0 +1,96 @@
+import { call } from "../daemon/client.js";
+import type { PolicyCheckPayload, PolicyCheckResult } from "../daemon/protocol.js";
+import {
+  ensureDaemon,
+  isEnterpriseProject,
+  parseInput,
+  readStdin,
+  resolveDaemonEntry,
+  sendHeartbeat,
+} from "./shared.js";
+
+/**
+ * PreToolUse hook for Claude Code.
+ *
+ * Reads the tool invocation from stdin, asks the daemon if policy permits,
+ * exits 0 (allow) or 2 (block).
+ *
+ * Failure modes (Alt A, beslutat 2026-04-30):
+ *   community + daemon down → fail-open (exit 0)
+ *   enterprise + daemon down → fail-closed (exit 2)
+ */
+
+type ClaudePreToolUseInput = {
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  cwd?: string;
+  session_id?: string;
+};
+
+async function main(): Promise<void> {
+  const raw = await readStdin();
+  const input = parseInput(raw) as ClaudePreToolUseInput;
+  const cwd = input.cwd || process.cwd();
+  const tool = input.tool_name || "unknown";
+  const enterprise = isEnterpriseProject(cwd);
+
+  // Try to bring the daemon up if it's not already.
+  ensureDaemon(resolveDaemonEntry(import.meta.url));
+
+  if (input.session_id) {
+    void sendHeartbeat({
+      cli: "claude",
+      hook: "PreToolUse",
+      session_id: input.session_id,
+      cwd,
+    });
+  }
+
+  const payload: PolicyCheckPayload = {
+    tool,
+    cwd,
+    input: input.tool_input ?? {},
+  };
+
+  const res = await call<PolicyCheckResult>("policy.check", payload, {
+    timeoutMs: 5000,
+  });
+
+  if (res.ok) {
+    if (res.result.allow) {
+      process.exit(0);
+    } else {
+      // Hook spec: exit 2 + stderr message → Claude Code blocks the tool.
+      process.stderr.write(
+        `[cortex] Blocked by policy: ${res.result.reason ?? "unspecified"}\n`,
+      );
+      process.exit(2);
+    }
+  }
+
+  // Daemon unreachable — apply split fail-mode.
+  if (enterprise) {
+    process.stderr.write(
+      `[cortex] Enterprise daemon unreachable (${res.error}). Blocking tool per fail-closed policy.\n`,
+    );
+    process.stderr.write(
+      "[cortex] Start the daemon with: cortex daemon start\n",
+    );
+    process.exit(2);
+  } else {
+    process.stderr.write(
+      `[cortex] Daemon unreachable (${res.error}). Allowing tool (community mode).\n`,
+    );
+    process.exit(0);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(
+    `[cortex pre-tool-use] error: ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+  // Hook errors should not block the user — fail-open on internal exceptions
+  // regardless of mode. The split fail-mode applies only to the explicit
+  // "daemon unreachable" path above.
+  process.exit(0);
+});