@danielblomma/cortex-mcp 2.4.0 → 2.4.1

package/scaffold/mcp/dist/enterprise/tools/harness.js

@@ -0,0 +1,40 @@
+import { isEnforcedMode } from "../../hooks/shared.js";
+import { WorkflowAdvanceInput, WorkflowEnvelopeInput, WorkflowStartInput, WorkflowStatusInput, resolveProjectRoot, runWorkflowAdvance, runWorkflowEnvelope, runWorkflowStart, runWorkflowStatus, } from "../../core/workflow/mcp-tools.js";
+export function registerHarnessTools(server) {
+    server.registerTool("cortex.workflow.start", {
+        description: "Start a Cortex Harness workflow run for a task. Creates .agents/<task_id>/state.json and returns the first stage's envelope (the prompt the agent should answer). Enterprise-only.",
+        inputSchema: WorkflowStartInput,
+    }, async (input) => buildResult(runWorkflowStart(WorkflowStartInput.parse(input ?? {}), {
+        cwd: resolveProjectRoot(),
+        bundledFallbackPolicy: isEnforcedMode(resolveProjectRoot()) ? "block" : "allow",
+    })));
+    server.registerTool("cortex.workflow.advance", {
+        description: "Complete the current stage of a workflow run by writing its artifact and advancing the run pointer. Returns the new run state plus the next stage's envelope (or null when the run is finished, blocked, or failed). Enterprise-only.",
+        inputSchema: WorkflowAdvanceInput,
+    }, async (input) => buildResult(runWorkflowAdvance(WorkflowAdvanceInput.parse(input ?? {}), {
+        cwd: resolveProjectRoot(),
+    })));
+    server.registerTool("cortex.workflow.status", {
+        description: "Read the current run state for a task (current stage, completed stages, outcome). Returns null state when no run exists for the given task_id. Enterprise-only.",
+        inputSchema: WorkflowStatusInput,
+    }, async (input) => buildResult(runWorkflowStatus(WorkflowStatusInput.parse(input ?? {}), {
+        cwd: resolveProjectRoot(),
+    })));
+    server.registerTool("cortex.workflow.envelope", {
+        description: "Compose the prompt envelope for a workflow stage without advancing the run. Defaults to the run's current_stage; pass `stage` to dry-run a different stage. Enterprise-only.",
+        inputSchema: WorkflowEnvelopeInput,
+    }, async (input) => buildResult(runWorkflowEnvelope(WorkflowEnvelopeInput.parse(input ?? {}), {
+        cwd: resolveProjectRoot(),
+    })));
+}
+function buildResult(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+        structuredContent: data,
+    };
+}

package/scaffold/mcp/dist/enterprise/tools/walk.js

@@ -0,0 +1,73 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+// Directories skipped while walking the project for a scope=all review.
+// Common build/vendor conventions across JS/Python/Go/Rust/C#/Java
+// ecosystems; keep permissive enough that individual validators still do
+// their own per-language filtering.
+const EXCLUDED_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    "target",
+    "bin",
+    "obj",
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".nuxt",
+    "vendor",
+    ".terraform",
+    "coverage",
+    ".cache",
+    ".turbo",
+]);
+const TEXT_EXT_RE = /\.(?:ts|tsx|js|jsx|mjs|cjs|json|ya?ml|toml|ini|env|config|xml|properties|tf|tfvars|sh|ps1|py|cs|vb|java|go|rs|rb|php|sql|md|txt|html?|css|scss|less)$/i;
+// Extensionless text files the secrets validator cares about: dotenv
+// variants and .NET appsettings.*
+const PATH_EXTRA_RE = /(?:^|\/)\.env(?:\.|$)|(?:^|\/)appsettings(?:\.|$)/i;
+const DEFAULT_MAX_FILES = 10_000;
+// Recursively list project-relative text file paths under `root`. Used as
+// the file set for scope=all reviews and as a fallback when scope=changed
+// cannot resolve a git diff (non-git working copy, git missing, etc.).
+export function walkProjectFiles(root, options = {}) {
+    const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+    const results = [];
+    function walk(dir) {
+        if (results.length >= maxFiles)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            if (results.length >= maxFiles)
+                return;
+            if (EXCLUDED_DIRS.has(name))
+                continue;
+            const abs = join(dir, name);
+            let st;
+            try {
+                st = statSync(abs);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                walk(abs);
+            }
+            else if (st.isFile()) {
+                const rel = relative(root, abs).split(sep).join("/");
+                if (TEXT_EXT_RE.test(rel) || PATH_EXTRA_RE.test(rel)) {
+                    results.push(rel);
+                }
+            }
+        }
+    }
+    walk(root);
+    return results;
+}

package/scaffold/mcp/dist/enterprise/violations/push.js

@@ -0,0 +1,77 @@
+/**
+ * Push policy violations to the Cortex Cloud API.
+ *
+ * Uses the same endpoint/api_key as policy sync since
+ * violations require the "policy" scope.
+ */
+import { isAllowedEnterpriseEndpoint } from "../../core/secure-endpoint.js";
+const pending = [];
+let activeContext = {};
+export function setViolationPushContext(context) {
+    activeContext = { ...context };
+}
+/**
+ * Queue a violation for the next push.
+ */
+export function queueViolation(item) {
+    pending.push(item);
+}
+/**
+ * Push all queued violations to cortex-web.
+ * Fire-and-forget — errors are logged but do not throw.
+ */
+export async function pushViolations(baseUrl, apiKey) {
+    if (pending.length === 0) {
+        return { success: true, count: 0 };
+    }
+    if (!baseUrl || !apiKey) {
+        return { success: false, count: 0, error: "endpoint or api_key not configured" };
+    }
+    if (!isAllowedEnterpriseEndpoint(baseUrl)) {
+        return {
+            success: false,
+            count: 0,
+            error: "insecure or invalid enterprise endpoint",
+        };
+    }
+    const violationsUrl = `${baseUrl.replace(/\/$/, "")}/api/v1/violations/push`;
+    const batch = pending.splice(0, 100); // max 100 per push
+    try {
+        const response = await fetch(violationsUrl, {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            body: JSON.stringify({
+                repo: activeContext.repo,
+                instance_id: activeContext.instance_id,
+                session_id: activeContext.session_id,
+                violations: batch,
+            }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            // Put them back so they can be retried
+            pending.unshift(...batch);
+            return { success: false, count: 0, error: `HTTP ${response.status}` };
+        }
+        return { success: true, count: batch.length };
+    }
+    catch (err) {
+        // Put them back for retry
+        pending.unshift(...batch);
+        return {
+            success: false,
+            count: 0,
+            error: err instanceof Error ? err.message : "unknown error",
+        };
+    }
+}
+/**
+ * Return the current queue length (for diagnostics).
+ */
+export function pendingCount() {
+    return pending.length;
+}

package/scaffold/mcp/dist/enterprise/workflow/push.js

@@ -0,0 +1,44 @@
+import { isAllowedEnterpriseEndpoint } from "../../core/secure-endpoint.js";
+let activeContext = {};
+export function setWorkflowPushContext(context) {
+    activeContext = { ...context };
+}
+export async function pushWorkflowSnapshot(baseUrl, apiKey, workflow) {
+    if (!baseUrl || !apiKey) {
+        return { success: false, error: "endpoint or api_key not configured" };
+    }
+    if (!isAllowedEnterpriseEndpoint(baseUrl)) {
+        return {
+            success: false,
+            error: "insecure or invalid enterprise endpoint",
+        };
+    }
+    const workflowUrl = `${baseUrl.replace(/\/$/, "")}/api/v1/workflow/push`;
+    try {
+        const response = await fetch(workflowUrl, {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            body: JSON.stringify({
+                repo: activeContext.repo,
+                instance_id: activeContext.instance_id,
+                session_id: activeContext.session_id,
+                workflow,
+            }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            return { success: false, status: response.status, error: `HTTP ${response.status}` };
+        }
+        return { success: true, status: response.status };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: err instanceof Error ? err.message : "unknown error",
+        };
+    }
+}

package/scaffold/mcp/dist/enterprise/workflow/state.js

@@ -0,0 +1,329 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+function nowIso() {
+    return new Date().toISOString();
+}
+function workflowDir(contextDir) {
+    return join(contextDir, "workflow");
+}
+function workflowStatePath(contextDir) {
+    return join(workflowDir(contextDir), "state.json");
+}
+export function hasWorkflowState(contextDir) {
+    return existsSync(workflowStatePath(contextDir));
+}
+function workflowReviewsDir(contextDir) {
+    return join(workflowDir(contextDir), "reviews");
+}
+function initialState() {
+    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: [],
+        review_trust: null,
+    };
+}
+function ensureWorkflowDirs(contextDir) {
+    mkdirSync(workflowReviewsDir(contextDir), { recursive: true });
+}
+function clampHistory(history) {
+    return history.slice(-100);
+}
+function blockersFor(state) {
+    const blockers = [];
+    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, preserveApproved = false) {
+    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, state, touchUpdatedAt = true) {
+    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) {
+    ensureWorkflowDirs(contextDir);
+    const statePath = workflowStatePath(contextDir);
+    if (!existsSync(statePath)) {
+        return writeState(contextDir, initialState());
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(statePath, "utf8"));
+        return withRecalculatedApproval(parsed, true);
+    }
+    catch {
+        return writeState(contextDir, initialState());
+    }
+}
+function addHistory(state, event, details) {
+    state.history.push({
+        at: nowIso(),
+        event,
+        details,
+    });
+}
+export function setWorkflowPlan(contextDir, input) {
+    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, input) {
+    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) {
+    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, input) {
+    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 = {
+        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, input) {
+    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 setWorkflowReviewTrust(contextDir, reviewTrust) {
+    if (!hasWorkflowState(contextDir)) {
+        const state = initialState();
+        state.review_trust = reviewTrust;
+        return writeState(contextDir, withRecalculatedApproval(state, true));
+    }
+    const state = loadWorkflowState(contextDir);
+    state.review_trust = reviewTrust;
+    return writeState(contextDir, withRecalculatedApproval(state, true));
+}
+export function addWorkflowNote(contextDir, input) {
+    const state = loadWorkflowState(contextDir);
+    const note = {
+        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, input) {
+    const state = loadWorkflowState(contextDir);
+    const now = nowIso();
+    const todo = {
+        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, todoId) {
+    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, notes) {
+    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/dist/frontmatter.js

@@ -0,0 +1,33 @@
+export function parseFrontmatter(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---") {
+        return { fields: new Map(), body: markdown };
+    }
+    const fields = new Map();
+    let index = 1;
+    for (; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line.trim() === "---") {
+            index += 1;
+            break;
+        }
+        const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!match) {
+            continue;
+        }
+        fields.set(match[1].toLowerCase(), match[2].trim());
+    }
+    return {
+        fields,
+        body: lines.slice(index).join("\n").trim()
+    };
+}
+export function parseStringList(value) {
+    if (!value || !value.trim()) {
+        return [];
+    }
+    return value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}