@danielblomma/cortex-mcp 2.0.5 → 2.0.7

package/scaffold/mcp/tests/workflow-envelope.test.mjs

@@ -0,0 +1,247 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { composeStageEnvelope } from "../dist/core/workflow/envelope.js";
+import { createRun, advanceStage } from "../dist/core/workflow/run-lifecycle.js";
+
+function makeWorkspace() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "cortex-envelope-"));
+}
+
+const TINY_WORKFLOW = {
+  id: "tiny",
+  description: "Two-stage workflow used for tests",
+  version: 1,
+  stages: [
+    {
+      name: "plan",
+      artifact: "plan.md",
+      reads: [],
+      required_fields: ["files_targeted"],
+      capability: "planner",
+      description: "Produce a step-by-step plan.",
+    },
+    {
+      name: "review",
+      artifact: "review.md",
+      reads: ["plan"],
+      required_fields: ["approved", "blocking_comments"],
+      capability: "reviewer",
+      description: "Review the plan for soundness.",
+    },
+  ],
+};
+
+function startRun(cwd, taskId) {
+  return createRun({
+    cwd,
+    taskId,
+    workflow: TINY_WORKFLOW,
+    taskDescription: "Wire up the new dashboard endpoint.",
+  });
+}
+
+function completePlanStage(cwd, taskId) {
+  return advanceStage({
+    cwd,
+    taskId,
+    workflow: TINY_WORKFLOW,
+    stageName: "plan",
+    artifactName: "plan.md",
+    frontmatter: {
+      stage: "plan",
+      status: "complete",
+      references: [],
+      files_targeted: ["src/foo.ts"],
+    },
+    body: "# Plan\n\n1. Add endpoint\n2. Wire route",
+  });
+}
+
+test("composeStageEnvelope: first stage has no handoffs and labels first-stage explicitly", () => {
+  const cwd = makeWorkspace();
+  const taskId = "envelope-first";
+  startRun(cwd, taskId);
+
+  const envelope = composeStageEnvelope({ cwd, taskId, workflow: TINY_WORKFLOW });
+
+  assert.equal(envelope.expectedArtifact, "plan.md");
+  assert.deepEqual(envelope.requiredFields, ["files_targeted"]);
+  assert.equal(envelope.capability, "planner");
+  assert.match(envelope.prompt, /# TASK/);
+  assert.match(envelope.prompt, /Wire up the new dashboard endpoint\./);
+  assert.match(envelope.prompt, /# STAGE: plan/);
+  assert.match(envelope.prompt, /Running under capability: `planner`/);
+  assert.match(envelope.prompt, /No prior-stage artifacts/);
+  assert.match(envelope.prompt, /# OUTPUT/);
+  assert.match(envelope.prompt, /`files_targeted`/);
+});
+
+test("composeStageEnvelope: mid-flow stage inlines prior artifact verbatim", () => {
+  const cwd = makeWorkspace();
+  const taskId = "envelope-mid";
+  startRun(cwd, taskId);
+  completePlanStage(cwd, taskId);
+
+  const envelope = composeStageEnvelope({ cwd, taskId, workflow: TINY_WORKFLOW });
+
+  assert.equal(envelope.expectedArtifact, "review.md");
+  assert.deepEqual(envelope.requiredFields, ["approved", "blocking_comments"]);
+  assert.match(envelope.prompt, /# STAGE: review/);
+  // Handoff section uses fenced markers and contains the planning frontmatter + body.
+  assert.match(envelope.prompt, /--- handoff:plan \(plan\.md\) ---/);
+  assert.match(envelope.prompt, /--- end handoff:plan ---/);
+  assert.match(envelope.prompt, /stage: plan/);
+  assert.match(envelope.prompt, /1\. Add endpoint/);
+});
+
+test("composeStageEnvelope: explicit stageName overrides current_stage for dry-run", () => {
+  const cwd = makeWorkspace();
+  const taskId = "envelope-explicit";
+  startRun(cwd, taskId);
+
+  const envelope = composeStageEnvelope({
+    cwd,
+    taskId,
+    workflow: TINY_WORKFLOW,
+    stageName: "plan",
+  });
+  assert.match(envelope.prompt, /# STAGE: plan/);
+});
+
+test("composeStageEnvelope: throws when run hasn't been created", () => {
+  const cwd = makeWorkspace();
+  assert.throws(
+    () => composeStageEnvelope({ cwd, taskId: "ghost", workflow: TINY_WORKFLOW }),
+    /No run state/,
+  );
+});
+
+test("composeStageEnvelope: throws when stage not in workflow", () => {
+  const cwd = makeWorkspace();
+  const taskId = "envelope-unknown";
+  startRun(cwd, taskId);
+
+  assert.throws(
+    () =>
+      composeStageEnvelope({
+        cwd,
+        taskId,
+        workflow: TINY_WORKFLOW,
+        stageName: "nonexistent",
+      }),
+    /not defined in workflow/,
+  );
+});
+
+test("composeStageEnvelope: throws when prior handoff artifact hasn't been produced", () => {
+  const cwd = makeWorkspace();
+  const taskId = "envelope-missing";
+  startRun(cwd, taskId);
+  // Skip the plan stage — go straight to asking for a review envelope. Plan
+  // is still pending so its artifact doesn't exist.
+  assert.throws(
+    () =>
+      composeStageEnvelope({
+        cwd,
+        taskId,
+        workflow: TINY_WORKFLOW,
+        stageName: "review",
+      }),
+    /requires artifact from plan, but it has not been produced yet/,
+  );
+});
+
+test("composeStageEnvelope: throws when stage declares reads from unknown stage", () => {
+  const cwd = makeWorkspace();
+  const taskId = "envelope-bad-reads";
+  const broken = {
+    ...TINY_WORKFLOW,
+    stages: [
+      TINY_WORKFLOW.stages[0],
+      { ...TINY_WORKFLOW.stages[1], reads: ["does-not-exist"] },
+    ],
+  };
+  createRun({
+    cwd,
+    taskId,
+    workflow: broken,
+    taskDescription: "Test bad reads",
+  });
+  advanceStage({
+    cwd,
+    taskId,
+    workflow: broken,
+    stageName: "plan",
+    artifactName: "plan.md",
+    frontmatter: { stage: "plan", status: "complete", references: [] },
+    body: "# Plan",
+  });
+
+  assert.throws(
+    () =>
+      composeStageEnvelope({
+        cwd,
+        taskId,
+        workflow: broken,
+        stageName: "review",
+      }),
+    /declares reads from unknown stage/,
+  );
+});
+
+test("composeStageEnvelope: surfaces lack of capability gracefully", () => {
+  const cwd = makeWorkspace();
+  const taskId = "envelope-no-capability";
+  const noCapability = {
+    ...TINY_WORKFLOW,
+    stages: [
+      { ...TINY_WORKFLOW.stages[0], capability: undefined },
+      TINY_WORKFLOW.stages[1],
+    ],
+  };
+  createRun({
+    cwd,
+    taskId,
+    workflow: noCapability,
+    taskDescription: "Test no capability",
+  });
+
+  const envelope = composeStageEnvelope({
+    cwd,
+    taskId,
+    workflow: noCapability,
+  });
+  assert.equal(envelope.capability, null);
+  assert.match(envelope.prompt, /No capability constraint declared/);
+});
+
+test("composeStageEnvelope: throws when run is already finished", () => {
+  const cwd = makeWorkspace();
+  const taskId = "envelope-finished";
+  startRun(cwd, taskId);
+  completePlanStage(cwd, taskId);
+  advanceStage({
+    cwd,
+    taskId,
+    workflow: TINY_WORKFLOW,
+    stageName: "review",
+    artifactName: "review.md",
+    frontmatter: {
+      stage: "review",
+      status: "complete",
+      references: ["plan.md"],
+      approved: true,
+      blocking_comments: 0,
+    },
+    body: "# Review\n\nLooks good.",
+  });
+
+  assert.throws(
+    () => composeStageEnvelope({ cwd, taskId, workflow: TINY_WORKFLOW }),
+    /not at any stage/,
+  );
+});

package/scaffold/mcp/tests/workflow-mcp-tools.test.mjs

@@ -0,0 +1,293 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  WorkflowStartInput,
+  WorkflowAdvanceInput,
+  WorkflowStatusInput,
+  WorkflowEnvelopeInput,
+  runWorkflowStart,
+  runWorkflowAdvance,
+  runWorkflowStatus,
+  runWorkflowEnvelope,
+} from "../dist/core/workflow/mcp-tools.js";
+import { SECURE_BUILD_WORKFLOW } from "../dist/core/workflow/default-workflows.js";
+
+function makeWorkspace() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "cortex-mcp-tools-"));
+}
+
+const TINY_WORKFLOW = {
+  id: "tiny",
+  description: "Two-stage tests workflow",
+  version: 1,
+  stages: [
+    {
+      name: "plan",
+      artifact: "plan.md",
+      reads: [],
+      required_fields: [],
+      capability: "planner",
+      description: "Produce a plan.",
+    },
+    {
+      name: "review",
+      artifact: "review.md",
+      reads: ["plan"],
+      required_fields: ["approved"],
+      capability: "reviewer",
+      description: "Review the plan.",
+    },
+  ],
+};
+
+const TINY_REGISTRY = { tiny: TINY_WORKFLOW };
+
+test("input schemas: workflow_id defaults to secure-build", () => {
+  const parsed = WorkflowStartInput.parse({
+    task_id: "abc",
+    task_description: "y",
+  });
+  assert.equal(parsed.workflow_id, "secure-build");
+});
+
+test("input schemas: advance requires stage + body", () => {
+  assert.throws(() => WorkflowAdvanceInput.parse({ task_id: "abc" }));
+  assert.throws(() =>
+    WorkflowAdvanceInput.parse({ task_id: "abc", stage: "plan", body: "" }),
+  );
+});
+
+test("input schemas: status accepts only task_id", () => {
+  const parsed = WorkflowStatusInput.parse({ task_id: "abc" });
+  assert.equal(parsed.task_id, "abc");
+});
+
+test("input schemas: envelope stage is optional", () => {
+  const parsed = WorkflowEnvelopeInput.parse({ task_id: "abc" });
+  assert.equal(parsed.stage, undefined);
+});
+
+test("runWorkflowStart: creates run and returns the first envelope", () => {
+  const cwd = makeWorkspace();
+  const result = runWorkflowStart(
+    {
+      task_id: "task-1",
+      task_description: "Add login flow",
+      workflow_id: "tiny",
+    },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+
+  assert.equal(result.state.task_id, "task-1");
+  assert.equal(result.state.current_stage, "plan");
+  assert.equal(result.state.outcome, "in_progress");
+  assert.equal(result.envelope.expectedArtifact, "plan.md");
+  assert.match(result.envelope.prompt, /# STAGE: plan/);
+
+  // state.json persisted under .agents/<task-id>/
+  const statePath = path.join(cwd, ".agents", "task-1", "state.json");
+  assert.ok(fs.existsSync(statePath));
+});
+
+test("runWorkflowStart: rejects unknown workflow_id", () => {
+  const cwd = makeWorkspace();
+  assert.throws(
+    () =>
+      runWorkflowStart(
+        { task_id: "task-1", task_description: "x", workflow_id: "nope" },
+        { cwd, workflows: TINY_REGISTRY },
+      ),
+    /Unknown workflow_id/,
+  );
+});
+
+test("runWorkflowStart: defaults to bundled DEFAULT_WORKFLOWS when no registry given", () => {
+  const cwd = makeWorkspace();
+  const result = runWorkflowStart(
+    {
+      task_id: "task-1",
+      task_description: "Use the default workflow",
+      workflow_id: SECURE_BUILD_WORKFLOW.id,
+    },
+    { cwd },
+  );
+  assert.equal(result.state.workflow_id, "secure-build");
+  assert.equal(result.envelope.expectedArtifact, "plan.md");
+});
+
+test("runWorkflowAdvance: writes artifact + state, returns next envelope while in_progress", () => {
+  const cwd = makeWorkspace();
+  runWorkflowStart(
+    { task_id: "task-2", task_description: "Multi-stage", workflow_id: "tiny" },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+
+  const advance = runWorkflowAdvance(
+    {
+      task_id: "task-2",
+      stage: "plan",
+      frontmatter: {},
+      body: "# Plan\n\nDetailed plan body.",
+    },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+
+  assert.equal(advance.state.current_stage, "review");
+  assert.equal(advance.state.outcome, "in_progress");
+  assert.equal(advance.state.stages[0].status, "complete");
+  assert.equal(advance.state.stages[0].artifact, "plan.md");
+  assert.ok(advance.next_envelope);
+  assert.equal(advance.next_envelope.expectedArtifact, "review.md");
+  // The handoff renders the plan artifact inline.
+  assert.match(advance.next_envelope.prompt, /--- handoff:plan \(plan\.md\) ---/);
+});
+
+test("runWorkflowAdvance: returns next_envelope=null when run completes", () => {
+  const cwd = makeWorkspace();
+  runWorkflowStart(
+    { task_id: "task-3", task_description: "x", workflow_id: "tiny" },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+  runWorkflowAdvance(
+    { task_id: "task-3", stage: "plan", frontmatter: {}, body: "# Plan" },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+
+  const finalAdvance = runWorkflowAdvance(
+    {
+      task_id: "task-3",
+      stage: "review",
+      frontmatter: { approved: true },
+      body: "# Review\n\nLooks good.",
+      outcome: { approved: true },
+    },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+
+  assert.equal(finalAdvance.state.current_stage, null);
+  assert.equal(finalAdvance.state.outcome, "complete");
+  assert.equal(finalAdvance.next_envelope, null);
+});
+
+test("runWorkflowAdvance: blocked status halts the run and returns null envelope", () => {
+  const cwd = makeWorkspace();
+  runWorkflowStart(
+    { task_id: "task-4", task_description: "x", workflow_id: "tiny" },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+
+  const result = runWorkflowAdvance(
+    {
+      task_id: "task-4",
+      stage: "plan",
+      frontmatter: {},
+      body: "# Plan blocked\n\nMissing context.",
+      status: "blocked",
+    },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+
+  assert.equal(result.state.outcome, "blocked");
+  assert.equal(result.state.current_stage, null);
+  assert.equal(result.next_envelope, null);
+});
+
+test("runWorkflowAdvance: rejects when no run exists", () => {
+  const cwd = makeWorkspace();
+  assert.throws(
+    () =>
+      runWorkflowAdvance(
+        {
+          task_id: "ghost",
+          stage: "plan",
+          frontmatter: {},
+          body: "# Plan",
+        },
+        { cwd, workflows: TINY_REGISTRY },
+      ),
+    /No run state/,
+  );
+});
+
+test("runWorkflowAdvance: auto-derives references from stage.reads when caller omits them", () => {
+  const cwd = makeWorkspace();
+  runWorkflowStart(
+    { task_id: "task-5", task_description: "x", workflow_id: "tiny" },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+  runWorkflowAdvance(
+    { task_id: "task-5", stage: "plan", frontmatter: {}, body: "# Plan" },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+  runWorkflowAdvance(
+    {
+      task_id: "task-5",
+      stage: "review",
+      frontmatter: { approved: false },
+      body: "# Review",
+    },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+
+  const reviewArtifact = path.join(cwd, ".agents", "task-5", "review.md");
+  const text = fs.readFileSync(reviewArtifact, "utf8");
+  assert.match(text, /references:/);
+  assert.match(text, /- plan\.md/);
+});
+
+test("runWorkflowStatus: returns state for an active run", () => {
+  const cwd = makeWorkspace();
+  runWorkflowStart(
+    { task_id: "task-6", task_description: "x", workflow_id: "tiny" },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+
+  const result = runWorkflowStatus({ task_id: "task-6" }, { cwd, workflows: TINY_REGISTRY });
+  assert.equal(result.state?.task_id, "task-6");
+  assert.equal(result.state?.current_stage, "plan");
+});
+
+test("runWorkflowStatus: returns null state when nothing exists", () => {
+  const cwd = makeWorkspace();
+  const result = runWorkflowStatus({ task_id: "no-run" }, { cwd, workflows: TINY_REGISTRY });
+  assert.equal(result.state, null);
+});
+
+test("runWorkflowEnvelope: returns current envelope without mutating state", () => {
+  const cwd = makeWorkspace();
+  runWorkflowStart(
+    { task_id: "task-7", task_description: "x", workflow_id: "tiny" },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+
+  const before = runWorkflowStatus({ task_id: "task-7" }, { cwd, workflows: TINY_REGISTRY });
+  const envelope = runWorkflowEnvelope(
+    { task_id: "task-7" },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+  const after = runWorkflowStatus({ task_id: "task-7" }, { cwd, workflows: TINY_REGISTRY });
+
+  assert.equal(envelope.envelope.expectedArtifact, "plan.md");
+  assert.deepEqual(before.state, after.state);
+});
+
+test("runWorkflowEnvelope: explicit stage overrides current_stage for dry-run", () => {
+  const cwd = makeWorkspace();
+  runWorkflowStart(
+    { task_id: "task-8", task_description: "x", workflow_id: "tiny" },
+    { cwd, workflows: TINY_REGISTRY },
+  );
+
+  // Dry-run review even though we're at plan — should fail because review
+  // requires plan's artifact to exist.
+  assert.throws(() =>
+    runWorkflowEnvelope(
+      { task_id: "task-8", stage: "review" },
+      { cwd, workflows: TINY_REGISTRY },
+    ),
+  );
+});