@danielblomma/cortex-mcp 2.2.5 → 2.4.1

package/scaffold/mcp/dist/cli/stage.js

@@ -0,0 +1,308 @@
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { composeStageEnvelope, createRun, advanceStage, getRunState, } from "../core/workflow/index.js";
+import { resolveWorkflowDefinition } from "../core/workflow/resolution.js";
+import { isEnforcedMode, isEnterpriseProject } from "../hooks/shared.js";
+/**
+ * `cortex stage` CLI surface. Each subcommand is a thin shell wrapper
+ * around the workflow primitives, mirroring the cortex.workflow.* MCP
+ * tools so shell scripts and CI can drive the harness without an MCP
+ * client.
+ *
+ * Subcommands:
+ *   start --task-id <id> --description "..." [--workflow <id>]
+ *   status --task-id <id>
+ *   envelope --task-id <id> [--stage <name>]
+ *   advance --task-id <id> --stage <name> --body-file <path>
+ *           [--frontmatter-file <path>] [--status <complete|blocked|failed>]
+ *   run --task-id <id> -- <command> [args...]
+ *     Sets CORTEX_ACTIVE_TASK_ID and execs the command. Use this to
+ *     spawn an agent that runs under the harness's pre-tool-use gate.
+ *
+ * All commands resolve cwd from CORTEX_PROJECT_ROOT (preferred) or
+ * process.cwd() so they work both inside an MCP server context and as
+ * standalone shell calls.
+ */
+const ENTERPRISE_REQUIRED_MESSAGE = "cortex stage is part of the Cortex Harness — an enterprise-only feature. " +
+    "This project does not have an enterprise license configured (no enterprise.api_key " +
+    "in .context/enterprise.yml). Run 'cortex enterprise install --api-key-stdin' to enable it, or " +
+    "contact your org admin.";
+export async function runStageCommand(args) {
+    const sub = args[0] ?? "help";
+    const rest = args.slice(1);
+    // help is allowed in community mode so users can discover the feature exists.
+    if (sub !== "help" && sub !== "--help" && sub !== "-h") {
+        if (!isEnterpriseProject(projectRoot())) {
+            throw new Error(ENTERPRISE_REQUIRED_MESSAGE);
+        }
+    }
+    switch (sub) {
+        case "start":
+            return runStart(rest);
+        case "status":
+            return runStatus(rest);
+        case "envelope":
+            return runEnvelope(rest);
+        case "advance":
+            return runAdvance(rest);
+        case "run":
+            return runRun(rest);
+        case "help":
+        case "--help":
+        case "-h":
+            printHelp();
+            return;
+        default:
+            printHelp();
+            throw new Error(`Unknown stage subcommand: ${sub}`);
+    }
+}
+function printHelp() {
+    const lines = [
+        "Usage:",
+        "  cortex stage start    --task-id <id> --description \"...\" [--workflow <id>]",
+        "  cortex stage status   --task-id <id>",
+        "  cortex stage envelope --task-id <id> [--stage <name>]",
+        "  cortex stage advance  --task-id <id> --stage <name> --body-file <path>",
+        "                        [--frontmatter-file <path>] [--status <s>] [--outcome-file <path>]",
+        "                        [--validators-passed <id1,id2,...>]",
+        "                        [--override-reason \"...\"] [--override-skipped-validators <id1,id2>]",
+        "  cortex stage run      --task-id <id> -- <command> [args...]",
+        "",
+        "Status values: complete (default) | blocked | failed",
+        "All commands operate on .agents/<task-id>/ in the current project root.",
+    ];
+    process.stdout.write(lines.join("\n") + "\n");
+}
+function projectRoot() {
+    return process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
+}
+function parseFlags(args) {
+    const flags = {};
+    const rest = [];
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg === "--") {
+            rest.push(...args.slice(i + 1));
+            break;
+        }
+        if (arg.startsWith("--")) {
+            const next = args[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                flags[arg.slice(2)] = true;
+                i += 1;
+            }
+            else {
+                flags[arg.slice(2)] = next;
+                i += 2;
+            }
+            continue;
+        }
+        rest.push(arg);
+        i += 1;
+    }
+    return { flags, rest };
+}
+function requireFlag(flags, name) {
+    const value = flags[name];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Missing required flag: --${name}`);
+    }
+    return value;
+}
+function emitJson(data) {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+}
+async function runStart(args) {
+    const { flags } = parseFlags(args);
+    const taskId = requireFlag(flags, "task-id");
+    const description = requireFlag(flags, "description");
+    const workflowId = typeof flags.workflow === "string" ? flags.workflow : "secure-build";
+    const resolved = resolveWorkflowDefinition(workflowId, {
+        cwd: projectRoot(),
+        emitBundledFallbackWarning: true,
+        bundledFallbackPolicy: isEnforcedMode(projectRoot()) ? "block" : "warn",
+    });
+    const workflow = resolved.workflow;
+    const state = createRun({
+        cwd: projectRoot(),
+        taskId,
+        workflow,
+        taskDescription: description,
+    });
+    const envelope = composeStageEnvelope({
+        cwd: projectRoot(),
+        taskId,
+        workflow,
+    });
+    emitJson({
+        state,
+        envelope,
+        workflow_source: resolved.source,
+        warnings: resolved.warnings,
+    });
+}
+async function runStatus(args) {
+    const { flags } = parseFlags(args);
+    const taskId = requireFlag(flags, "task-id");
+    const state = getRunState(projectRoot(), taskId);
+    emitJson({ state });
+}
+async function runEnvelope(args) {
+    const { flags } = parseFlags(args);
+    const taskId = requireFlag(flags, "task-id");
+    const stageName = typeof flags.stage === "string" ? flags.stage : undefined;
+    const state = getRunState(projectRoot(), taskId);
+    if (!state) {
+        throw new Error(`No run state for task ${taskId}. Start one with 'cortex stage start'.`);
+    }
+    const workflow = resolveWorkflowDefinition(state.workflow_id, {
+        cwd: projectRoot(),
+    }).workflow;
+    const envelope = composeStageEnvelope({
+        cwd: projectRoot(),
+        taskId,
+        workflow,
+        stageName,
+    });
+    emitJson({ envelope });
+}
+async function runAdvance(args) {
+    const { flags } = parseFlags(args);
+    const taskId = requireFlag(flags, "task-id");
+    const stageName = requireFlag(flags, "stage");
+    const bodyPath = requireFlag(flags, "body-file");
+    const frontmatterPath = typeof flags["frontmatter-file"] === "string"
+        ? flags["frontmatter-file"]
+        : null;
+    const outcomePath = typeof flags["outcome-file"] === "string" ? flags["outcome-file"] : null;
+    const statusFlag = typeof flags.status === "string" ? flags.status : undefined;
+    const validatorsRaw = typeof flags["validators-passed"] === "string"
+        ? flags["validators-passed"]
+        : null;
+    const overrideReason = typeof flags["override-reason"] === "string"
+        ? flags["override-reason"]
+        : null;
+    const overrideSkippedRaw = typeof flags["override-skipped-validators"] === "string"
+        ? flags["override-skipped-validators"]
+        : null;
+    const body = readFileSync(bodyPath, "utf8");
+    const frontmatter = frontmatterPath
+        ? parseJsonObject(frontmatterPath)
+        : {};
+    const outcome = outcomePath ? parseJsonObject(outcomePath) : undefined;
+    const validatorsPassed = validatorsRaw
+        ? validatorsRaw.split(",").map((s) => s.trim()).filter(Boolean)
+        : undefined;
+    const override = overrideReason
+        ? {
+            reason: overrideReason,
+            skipped_validators: overrideSkippedRaw
+                ? overrideSkippedRaw.split(",").map((s) => s.trim()).filter(Boolean)
+                : [],
+            skipped_requirements: [],
+        }
+        : undefined;
+    const state = getRunState(projectRoot(), taskId);
+    if (!state) {
+        throw new Error(`No run state for task ${taskId}. Start one with 'cortex stage start'.`);
+    }
+    const workflow = resolveWorkflowDefinition(state.workflow_id, {
+        cwd: projectRoot(),
+    }).workflow;
+    const stage = workflow.stages.find((s) => s.name === stageName);
+    if (!stage) {
+        throw new Error(`Stage ${stageName} is not defined in workflow ${workflow.id}`);
+    }
+    const finalStatus = statusFlag ?? "complete";
+    const next = advanceStage({
+        cwd: projectRoot(),
+        taskId,
+        workflow,
+        stageName,
+        artifactName: stage.artifact,
+        frontmatter: {
+            ...frontmatter,
+            stage: stageName,
+            status: finalStatus,
+            references: (Array.isArray(frontmatter.references)
+                ? frontmatter.references
+                    .filter((v) => typeof v === "string")
+                : null) ?? deriveReferencesFromReads(stage.reads, workflow),
+        },
+        body,
+        status: finalStatus,
+        outcome,
+        validatorsPassed,
+        override,
+    });
+    let nextEnvelope = null;
+    if (next.outcome === "in_progress" && next.current_stage) {
+        nextEnvelope = composeStageEnvelope({
+            cwd: projectRoot(),
+            taskId,
+            workflow,
+        });
+    }
+    emitJson({ state: next, next_envelope: nextEnvelope });
+}
+function parseJsonObject(filePath) {
+    const raw = readFileSync(filePath, "utf8");
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse JSON in ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`Expected JSON object in ${filePath}, got ${typeof value}`);
+    }
+    return value;
+}
+function deriveReferencesFromReads(reads, workflow) {
+    const refs = [];
+    for (const readName of reads) {
+        const stage = workflow.stages.find((s) => s.name === readName);
+        if (stage)
+            refs.push(stage.artifact);
+    }
+    return refs;
+}
+async function runRun(args) {
+    const { flags, rest } = parseFlags(args);
+    const taskId = requireFlag(flags, "task-id");
+    if (rest.length === 0) {
+        throw new Error("cortex stage run requires a command after --, e.g. 'cortex stage run --task-id task-1 -- claude'");
+    }
+    const state = getRunState(projectRoot(), taskId);
+    if (!state) {
+        throw new Error(`No run state for task ${taskId}. Start one with 'cortex stage start'.`);
+    }
+    if (state.outcome !== "in_progress" || !state.current_stage) {
+        throw new Error(`Run ${taskId} is not in progress (outcome=${state.outcome}). Cannot spawn agent.`);
+    }
+    const [command, ...commandArgs] = rest;
+    const child = spawn(command, commandArgs, {
+        stdio: "inherit",
+        env: {
+            ...process.env,
+            CORTEX_ACTIVE_TASK_ID: taskId,
+        },
+    });
+    await new Promise((resolve, reject) => {
+        child.on("error", reject);
+        child.on("exit", (code, signal) => {
+            if (signal) {
+                reject(new Error(`spawned process terminated by signal ${signal}`));
+                return;
+            }
+            if (code !== 0) {
+                reject(new Error(`spawned process exited with code ${code}`));
+                return;
+            }
+            resolve();
+        });
+    });
+}

package/scaffold/mcp/dist/cli/telemetry-test.js

@@ -0,0 +1,141 @@
+import { basename, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { hostname, platform, arch } from "node:os";
+import { loadEnterpriseConfig, resolveEnterpriseActivation, } from "../core/config.js";
+import { telemetryStatePath } from "../core/telemetry/state-dir.js";
+import { pushMetrics } from "../enterprise/telemetry/sync.js";
+/**
+ * Smoke-test the telemetry pipeline end-to-end.
+ *
+ *   $ cortex telemetry test
+ *
+ * Reads .context/enterprise.yml, builds a synthetic-but-valid metrics
+ * payload, sends it to the configured endpoint, and reports the result
+ * with actionable diagnostics on failure.
+ *
+ * This exists because the silent-failure path (push fails, dashboard
+ * stays empty, no error surfaces anywhere) was the original v2.0.0
+ * motivator. The smoke-test gives users a single command to verify
+ * their entire pipeline.
+ */
+function readMachineId(contextDir) {
+    const path = telemetryStatePath(contextDir, "machine_id");
+    if (existsSync(path)) {
+        try {
+            const id = readFileSync(path, "utf8").trim();
+            if (id)
+                return id;
+        }
+        catch {
+            // fall through to compute one
+        }
+    }
+    return createHash("sha256")
+        .update(`${hostname()}|${platform()}|${arch()}|test`)
+        .digest("hex")
+        .slice(0, 16);
+}
+function buildSyntheticMetrics(instanceId, version) {
+    const now = new Date();
+    const periodStart = new Date(now.getTime() - 60_000).toISOString();
+    const periodEnd = now.toISOString();
+    return {
+        period_start: periodStart,
+        period_end: periodEnd,
+        total_tool_calls: 1,
+        successful_tool_calls: 1,
+        failed_tool_calls: 0,
+        total_duration_ms: 100,
+        session_starts: 1,
+        session_ends: 1,
+        session_duration_ms_total: 100,
+        searches: 1,
+        related_lookups: 0,
+        caller_lookups: 0,
+        trace_lookups: 0,
+        impact_analyses: 0,
+        rule_lookups: 0,
+        reloads: 0,
+        total_results_returned: 1,
+        estimated_tokens_saved: 100,
+        estimated_tokens_total: 500,
+        client_version: version,
+        instance_id: instanceId,
+        tool_metrics: {
+            "telemetry.test": {
+                calls: 1,
+                failures: 0,
+                total_duration_ms: 100,
+                total_results_returned: 1,
+                estimated_tokens_saved: 100,
+            },
+        },
+    };
+}
+export async function runTelemetryTest() {
+    const projectRoot = process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
+    const contextDir = join(projectRoot, ".context");
+    if (!existsSync(contextDir)) {
+        console.error(`No .context directory at ${projectRoot}`);
+        console.error(`Run 'cortex init --bootstrap' first.`);
+        return 1;
+    }
+    const config = loadEnterpriseConfig(contextDir);
+    const activation = resolveEnterpriseActivation(config);
+    console.log(`Project:           ${projectRoot}`);
+    console.log(`Enterprise active: ${activation.active} (${activation.reason})`);
+    if (!activation.active) {
+        console.error("");
+        console.error("Cannot run telemetry test in community mode.");
+        console.error("Configure .context/enterprise.yml with valid api_key + endpoint.");
+        return 1;
+    }
+    if (!config.telemetry.enabled) {
+        console.error("");
+        console.error("telemetry.enabled is false in enterprise.yml");
+        return 1;
+    }
+    console.log(`Endpoint:          ${config.telemetry.endpoint}`);
+    console.log(`API key prefix:    ${config.telemetry.api_key.slice(0, 8)}...`);
+    const instanceId = readMachineId(contextDir);
+    const version = process.env.CORTEX_VERSION ?? "telemetry-test";
+    const metrics = buildSyntheticMetrics(instanceId, version);
+    console.log("");
+    console.log("Sending synthetic metrics...");
+    const start = Date.now();
+    const result = await pushMetrics(metrics, config.telemetry.endpoint, config.telemetry.api_key, { repo: basename(projectRoot) });
+    const elapsed = Date.now() - start;
+    if (result.success) {
+        console.log("");
+        console.log(`✓ Push succeeded in ${elapsed}ms (HTTP ${result.status})`);
+        console.log("");
+        console.log("Next: open the dashboard. The synthetic event should appear within 60s.");
+        console.log("If it does not, the issue is on the server (ingest or read path),");
+        console.log("not the client.");
+        return 0;
+    }
+    console.error("");
+    console.error(`✗ Push failed after ${elapsed}ms: ${result.error ?? "unknown"}`);
+    console.error("");
+    if (result.status === 401) {
+        console.error("  → API key was rejected. Check that the key in enterprise.yml");
+        console.error("    matches a row in cortex-web's api_keys table and is not");
+        console.error("    revoked or expired.");
+    }
+    else if (result.status === 403) {
+        console.error("  → API key lacks 'telemetry' scope. Add the scope in cortex-web.");
+    }
+    else if (result.status === 400) {
+        console.error("  → Payload schema rejected. Likely a client/server version skew.");
+        console.error("    Check telemetryPushSchema vs TelemetryMetrics.");
+    }
+    else if (result.status && result.status >= 500) {
+        console.error("  → Server error. Check cortex-web logs and DB connectivity.");
+    }
+    else {
+        console.error("  → Network error. Verify endpoint is reachable from this machine.");
+        console.error(`     curl -I ${config.telemetry.endpoint}`);
+    }
+    return 1;
+}

package/scaffold/mcp/dist/cli/ungoverned-detector.js

@@ -0,0 +1,133 @@
+import { execSync } from "node:child_process";
+import { basename } from "node:path";
+import { hostname, userInfo } from "node:os";
+export const DEFAULT_AI_BINARIES = [
+    "claude",
+    "codex",
+    "copilot",
+    "gemini-cli",
+    "gemini",
+    "aider",
+    "cursor",
+];
+const PS_LINE_RE = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s*(.*)$/;
+export function listProcesses() {
+    try {
+        const out = execSync("ps -axo pid,ppid,user,comm,args", {
+            encoding: "utf8",
+            timeout: 5000,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        const lines = out.trim().split("\n").slice(1);
+        return lines
+            .map(parseProcessLine)
+            .filter((p) => p !== null);
+    }
+    catch {
+        return [];
+    }
+}
+export function parseProcessLine(line) {
+    const m = line.match(PS_LINE_RE);
+    if (!m)
+        return null;
+    const pid = parseInt(m[1], 10);
+    const ppid = parseInt(m[2], 10);
+    if (!Number.isFinite(pid) || !Number.isFinite(ppid))
+        return null;
+    return {
+        pid,
+        ppid,
+        user: m[3],
+        comm: m[4],
+        args: m[5] ?? "",
+    };
+}
+export function isCortexAncestor(args) {
+    if (!args)
+        return false;
+    // Accept invocations whose command line shows cortex orchestration:
+    //  - `cortex run ...`     → wrapper spawned the AI CLI (Tier 2 governed)
+    //  - `cortex enterprise`  → install-time orchestration
+    //  - `cortex daemon`      → daemon-supervised
+    //  - any path ending in `cortex.mjs` or named `cortex` followed by space/EOL
+    if (/\bcortex\s+run\b/.test(args))
+        return true;
+    if (/\bcortex\s+enterprise\b/.test(args))
+        return true;
+    if (/\bcortex\s+daemon\b/.test(args))
+        return true;
+    if (/\bcortex\s+hook\b/.test(args))
+        return true;
+    if (/\bcortex(\s|$)/.test(args))
+        return true;
+    if (/cortex\.mjs/.test(args))
+        return true;
+    return false;
+}
+function findCli(comm, knownBinaries) {
+    const base = basename(comm);
+    return knownBinaries.includes(base) ? base : null;
+}
+export function detectUngoverned(options = {}) {
+    const known = options.knownBinaries ?? DEFAULT_AI_BINARIES;
+    const procs = options.processes ?? listProcesses();
+    const byPid = new Map();
+    for (const p of procs)
+        byPid.set(p.pid, p);
+    const hostId = options.hostId ?? hostname();
+    const findings = [];
+    for (const proc of procs) {
+        const cli = findCli(proc.comm, known);
+        if (!cli)
+            continue;
+        if (isCortexAncestor(proc.args))
+            continue;
+        const chain = [proc.pid];
+        let current = byPid.get(proc.ppid);
+        let governed = false;
+        let depth = 0;
+        while (current && current.pid > 1 && depth < 32) {
+            chain.push(current.pid);
+            if (isCortexAncestor(current.args)) {
+                governed = true;
+                break;
+            }
+            const next = byPid.get(current.ppid);
+            if (!next || next.pid === current.pid)
+                break;
+            current = next;
+            depth += 1;
+        }
+        if (!governed) {
+            findings.push({
+                pid: proc.pid,
+                ppid: proc.ppid,
+                user: proc.user,
+                cli,
+                binary: proc.comm,
+                args: proc.args,
+                parent_chain: chain,
+                detected_at: new Date().toISOString(),
+                host_id: hostId,
+            });
+        }
+    }
+    return findings;
+}
+export function enforceFinding(finding, options) {
+    if (options.mode !== "enforced")
+        return "logged";
+    const me = options.currentUser ?? userInfo().username;
+    if (finding.user !== me) {
+        return "skipped_cross_user";
+    }
+    const send = options.sendSignal ?? ((pid, sig) => process.kill(pid, sig));
+    try {
+        send(finding.pid, "SIGTERM");
+    }
+    catch {
+        // process exited between detection and signal — best-effort
+    }
+    return "sigterm";
+}