@danielblomma/cortex-mcp 2.0.4 → 2.0.6

package/scaffold/mcp/src/cli/stage.ts

@@ -0,0 +1,325 @@
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import {
+  composeStageEnvelope,
+  createRun,
+  advanceStage,
+  getRunState,
+  type StageStatus,
+  type WorkflowDefinition,
+} from "../core/workflow/index.js";
+import { DEFAULT_WORKFLOWS } from "../core/workflow/default-workflows.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.
+ */
+
+export async function runStageCommand(args: string[]): Promise<void> {
+  const sub = args[0] ?? "help";
+  const rest = args.slice(1);
+
+  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(): void {
+  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>]",
+    "  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(): string {
+  return process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
+}
+
+function resolveWorkflow(workflowId: string): WorkflowDefinition {
+  const wf = DEFAULT_WORKFLOWS[workflowId];
+  if (!wf) {
+    throw new Error(
+      `Unknown workflow_id: ${workflowId}. Available: ${
+        Object.keys(DEFAULT_WORKFLOWS).join(", ") || "<none>"
+      }`,
+    );
+  }
+  return wf;
+}
+
+type Flags = Record<string, string | boolean>;
+
+function parseFlags(args: string[]): { flags: Flags; rest: string[] } {
+  const flags: Flags = {};
+  const rest: string[] = [];
+  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: Flags, name: string): string {
+  const value = flags[name];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Missing required flag: --${name}`);
+  }
+  return value;
+}
+
+function emitJson(data: unknown): void {
+  process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+}
+
+async function runStart(args: string[]): Promise<void> {
+  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 workflow = resolveWorkflow(workflowId);
+  const state = createRun({
+    cwd: projectRoot(),
+    taskId,
+    workflow,
+    taskDescription: description,
+  });
+  const envelope = composeStageEnvelope({
+    cwd: projectRoot(),
+    taskId,
+    workflow,
+  });
+  emitJson({ state, envelope });
+}
+
+async function runStatus(args: string[]): Promise<void> {
+  const { flags } = parseFlags(args);
+  const taskId = requireFlag(flags, "task-id");
+  const state = getRunState(projectRoot(), taskId);
+  emitJson({ state });
+}
+
+async function runEnvelope(args: string[]): Promise<void> {
+  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 = resolveWorkflow(state.workflow_id);
+  const envelope = composeStageEnvelope({
+    cwd: projectRoot(),
+    taskId,
+    workflow,
+    stageName,
+  });
+  emitJson({ envelope });
+}
+
+async function runAdvance(args: string[]): Promise<void> {
+  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 as StageStatus) : undefined;
+
+  const body = readFileSync(bodyPath, "utf8");
+  const frontmatter: Record<string, unknown> = frontmatterPath
+    ? parseJsonObject(frontmatterPath)
+    : {};
+  const outcome = outcomePath ? parseJsonObject(outcomePath) : 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 = resolveWorkflow(state.workflow_id);
+  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: StageStatus = statusFlag ?? "complete";
+  const next = advanceStage({
+    cwd: projectRoot(),
+    taskId,
+    workflow,
+    stageName,
+    artifactName: stage.artifact,
+    frontmatter: {
+      ...frontmatter,
+      stage: stageName,
+      status: finalStatus,
+      references:
+        (Array.isArray((frontmatter as Record<string, unknown>).references)
+          ? ((frontmatter as Record<string, unknown>).references as unknown[])
+              .filter((v): v is string => typeof v === "string")
+          : null) ?? deriveReferencesFromReads(stage.reads, workflow),
+    },
+    body,
+    status: finalStatus,
+    outcome,
+  });
+
+  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: string): Record<string, unknown> {
+  const raw = readFileSync(filePath, "utf8");
+  let value: unknown;
+  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 as Record<string, unknown>;
+}
+
+function deriveReferencesFromReads(
+  reads: string[],
+  workflow: WorkflowDefinition,
+): string[] {
+  const refs: string[] = [];
+  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: string[]): Promise<void> {
+  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<void>((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/src/core/workflow/artifact-io.ts

@@ -0,0 +1,156 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import * as yaml from "js-yaml";
+import {
+  runStateSchema,
+  stageArtifactFrontmatterSchema,
+  type RunState,
+  type StageArtifactFrontmatter,
+} from "./schemas.js";
+
+/**
+ * Filesystem layout for one workflow run:
+ *
+ *   <cwd>/.agents/<task-id>/
+ *     plan.md
+ *     review.md
+ *     ...
+ *     state.json
+ *
+ * All paths in this module are relative to the project's <cwd>. The caller
+ * is responsible for choosing cwd; we never assume process.cwd() here so
+ * tests can target a tmp directory.
+ */
+
+export const AGENTS_DIR = ".agents";
+export const STATE_FILENAME = "state.json";
+
+export function runDir(cwd: string, taskId: string): string {
+  return join(cwd, AGENTS_DIR, taskId);
+}
+
+export function stateFilePath(cwd: string, taskId: string): string {
+  return join(runDir(cwd, taskId), STATE_FILENAME);
+}
+
+export function artifactPath(
+  cwd: string,
+  taskId: string,
+  artifactName: string,
+): string {
+  return join(runDir(cwd, taskId), artifactName);
+}
+
+const FRONTMATTER_OPEN = /^---\s*\r?\n/;
+const FRONTMATTER_CLOSE = /\r?\n---\s*\r?\n/;
+
+export type ParsedArtifact = {
+  frontmatter: StageArtifactFrontmatter;
+  body: string;
+};
+
+export function parseStageArtifact(text: string): ParsedArtifact {
+  if (!FRONTMATTER_OPEN.test(text)) {
+    throw new Error("Stage artifact is missing YAML frontmatter (--- ... ---)");
+  }
+  const afterOpen = text.replace(FRONTMATTER_OPEN, "");
+  const closeMatch = afterOpen.match(FRONTMATTER_CLOSE);
+  if (!closeMatch || closeMatch.index === undefined) {
+    throw new Error("Stage artifact frontmatter is not terminated (--- ... ---)");
+  }
+  const yamlText = afterOpen.slice(0, closeMatch.index);
+  const body = afterOpen
+    .slice(closeMatch.index + closeMatch[0].length)
+    .replace(/^\s+/, "")
+    .replace(/\s+$/, "");
+
+  let raw: unknown;
+  try {
+    raw = yaml.load(yamlText);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse stage artifact frontmatter as YAML: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+
+  const parsed = stageArtifactFrontmatterSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new Error(
+      `Stage artifact frontmatter does not match schema: ${parsed.error.message}`,
+    );
+  }
+  return { frontmatter: parsed.data, body };
+}
+
+export function readStageArtifact(
+  cwd: string,
+  taskId: string,
+  artifactName: string,
+): ParsedArtifact {
+  const path = artifactPath(cwd, taskId, artifactName);
+  const text = readFileSync(path, "utf8");
+  return parseStageArtifact(text);
+}
+
+export function renderStageArtifact(
+  frontmatter: StageArtifactFrontmatter,
+  body: string,
+): string {
+  const yamlText = yaml.dump(frontmatter, {
+    lineWidth: 100,
+    noRefs: true,
+    sortKeys: false,
+  });
+  const trimmedBody = body.trim();
+  return `---\n${yamlText}---\n\n${trimmedBody}\n`;
+}
+
+export function writeStageArtifact(
+  cwd: string,
+  taskId: string,
+  artifactName: string,
+  frontmatter: StageArtifactFrontmatter,
+  body: string,
+): string {
+  const dir = runDir(cwd, taskId);
+  mkdirSync(dir, { recursive: true });
+  const path = artifactPath(cwd, taskId, artifactName);
+  writeFileSync(path, renderStageArtifact(frontmatter, body), "utf8");
+  return path;
+}
+
+export function readRunState(cwd: string, taskId: string): RunState | null {
+  const path = stateFilePath(cwd, taskId);
+  if (!existsSync(path)) return null;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new Error(
+      `Failed to parse run state at ${path}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+  const parsed = runStateSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new Error(`Run state at ${path} does not match schema: ${parsed.error.message}`);
+  }
+  return parsed.data;
+}
+
+export function writeRunState(cwd: string, state: RunState): string {
+  const validated = runStateSchema.parse(state);
+  const dir = runDir(cwd, validated.task_id);
+  mkdirSync(dir, { recursive: true });
+  const path = stateFilePath(cwd, validated.task_id);
+  writeFileSync(path, JSON.stringify(validated, null, 2) + "\n", "utf8");
+  return path;
+}

package/scaffold/mcp/src/core/workflow/capabilities.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+
+/**
+ * Capability registry for the harness. A capability is a least-privilege
+ * profile referenced by a workflow stage's `capability` field. The
+ * pre-tool-use hook reads the active stage's capability and uses it to
+ * gate the agent's tool calls.
+ *
+ * The capability defines:
+ *   - read_globs    paths the agent may read (empty = no restriction)
+ *   - write_globs   paths the agent may modify (empty = read-only)
+ *   - tools_allowed which tool names the agent may call (empty = all)
+ *
+ * Glob patterns use minimatch syntax. The harness ships a default set
+ * keyed by the names referenced in default-workflows.ts; orgs can ship
+ * additional capabilities later via cortex-web sync.
+ */
+
+const slugSchema = z
+  .string()
+  .min(1)
+  .max(80)
+  .regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$/);
+
+export const capabilityDefinitionSchema = z.object({
+  name: slugSchema,
+  description: z.string().min(1).max(500),
+  read_globs: z.array(z.string().min(1)).default([]),
+  write_globs: z.array(z.string().min(1)).default([]),
+  tools_allowed: z.array(z.string().min(1)).default([]),
+});
+
+export type CapabilityDefinition = z.infer<typeof capabilityDefinitionSchema>;
+
+/**
+ * Default capability profiles that ship with Cortex. Names match the
+ * `capability` fields referenced by SECURE_BUILD_WORKFLOW.
+ *
+ * tools_allowed is intentionally empty for most profiles to mean
+ * "no per-tool restriction beyond what the file globs already imply".
+ * The hook layer checks file paths first, tool name second.
+ */
+export const DEFAULT_CAPABILITIES: Record<string, CapabilityDefinition> = {
+  planner: {
+    name: "planner",
+    description:
+      "Read-only profile for stages that produce planning artifacts. " +
+      "Can read the whole repo and call context tools, cannot modify any files.",
+    read_globs: ["**"],
+    write_globs: [],
+    tools_allowed: [],
+  },
+  reviewer: {
+    name: "reviewer",
+    description:
+      "Read-only profile for review stages. Same access as planner; the " +
+      "review artifact itself is written by the harness, not by an Edit tool.",
+    read_globs: ["**"],
+    write_globs: [],
+    tools_allowed: [],
+  },
+  builder: {
+    name: "builder",
+    description:
+      "Build profile. May edit source and test files but not config, " +
+      "lockfiles, CI workflows, or anything outside the obvious app surface.",
+    read_globs: ["**"],
+    write_globs: ["src/**", "tests/**", "test/**", "lib/**", "app/**", "components/**"],
+    tools_allowed: [],
+  },
+  tester: {
+    name: "tester",
+    description:
+      "Mutation/test profile. Read-only on production code, may edit only " +
+      "test files. Used by mutation-testing or coverage-improvement stages.",
+    read_globs: ["**"],
+    write_globs: ["tests/**", "test/**", "**/*.test.ts", "**/*.test.tsx", "**/*.test.mjs", "**/*.spec.ts"],
+    tools_allowed: [],
+  },
+  "security-reviewer": {
+    name: "security-reviewer",
+    description:
+      "Security review profile. Read-only across the repo. Produces a " +
+      "report artifact; no source modifications allowed.",
+    read_globs: ["**"],
+    write_globs: [],
+    tools_allowed: [],
+  },
+  human: {
+    name: "human",
+    description:
+      "Sentinel capability for human approval stages. The harness does not " +
+      "invoke an agent for this stage; the human writes the artifact directly. " +
+      "If a tool call somehow reaches the hook under this capability, it is " +
+      "blocked because no automation should be running.",
+    read_globs: [],
+    write_globs: [],
+    tools_allowed: [],
+  },
+};

package/scaffold/mcp/src/core/workflow/default-workflows.ts

@@ -0,0 +1,83 @@
+import type { WorkflowDefinition } from "./schemas.js";
+
+/**
+ * The default secure-build workflow that ships with Cortex. Organizations
+ * can override this from cortex-web later (Phase 2 of the harness rollout);
+ * until then this is the workflow every project gets out of the box.
+ */
+export const SECURE_BUILD_WORKFLOW: WorkflowDefinition = {
+  id: "secure-build",
+  description:
+    "Plan → Review → Build → Review → Mutation Tests → Security Review → Human Approval. " +
+    "The default Cortex Harness workflow for AI-driven development on production code.",
+  version: 1,
+  stages: [
+    {
+      name: "plan",
+      artifact: "plan.md",
+      reads: [],
+      required_fields: ["files_targeted", "constraints"],
+      capability: "planner",
+      description:
+        "Produce a step-by-step implementation plan grounded in the repo's rules and memory.",
+    },
+    {
+      name: "plan-review",
+      artifact: "plan-review.md",
+      reads: ["plan"],
+      required_fields: ["approved", "blocking_comments"],
+      capability: "reviewer",
+      description:
+        "Review the plan for architectural fit and rule compliance before any code is written.",
+    },
+    {
+      name: "build",
+      artifact: "changes.md",
+      reads: ["plan", "plan-review"],
+      required_fields: ["files_changed"],
+      capability: "builder",
+      description:
+        "Implement the approved plan. Produces the diff manifest used by the downstream reviewers.",
+    },
+    {
+      name: "build-review",
+      artifact: "build-review.md",
+      reads: ["plan", "changes"],
+      required_fields: ["approved", "blocking_comments"],
+      capability: "reviewer",
+      description:
+        "Review the implementation against the plan and the project's rules.",
+    },
+    {
+      name: "mutation",
+      artifact: "mutation-report.md",
+      reads: ["changes"],
+      required_fields: ["score", "survived"],
+      capability: "tester",
+      description:
+        "Run mutation tests on the changed files. Report score + surviving mutants.",
+    },
+    {
+      name: "security",
+      artifact: "security-report.md",
+      reads: ["changes"],
+      required_fields: ["findings", "severity_summary"],
+      capability: "security-reviewer",
+      description:
+        "Security review focused on the diff: injection, authn/authz, secrets, dependency risk.",
+    },
+    {
+      name: "approval",
+      artifact: "approval.md",
+      reads: ["plan", "changes", "build-review", "mutation", "security"],
+      required_fields: ["approved", "approver"],
+      capability: "human",
+      description:
+        "Human sign-off. Pulls every prior artifact for the approver to read; the approver writes the artifact.",
+    },
+  ],
+};
+
+export const DEFAULT_WORKFLOWS: Record<string, WorkflowDefinition> = {
+  [SECURE_BUILD_WORKFLOW.id]: SECURE_BUILD_WORKFLOW,
+};