@quinteroac/agents-coding-toolkit 0.1.0-preview

package/src/commands/approve-requirement.ts

@@ -0,0 +1,217 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { $ } from "bun";
+
+import { CLI_PATH } from "../cli-path";
+import type { Prd } from "../../scaffold/schemas/tmpl_prd";
+import { exists, readState, writeState, FLOW_REL_DIR } from "../state";
+
+// ---------------------------------------------------------------------------
+// Markdown PRD parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parses the Markdown PRD into a structured object matching PrdSchema.
+ *
+ * Expected sections:
+ *   ## Goals          — bullet list of goal strings
+ *   ### US-xxx: Title — user story blocks with **Acceptance Criteria:** sub-list
+ *   ## Functional Requirements — bullet list of "FR-x: description"
+ */
+function parsePrd(markdown: string): Prd {
+  const goals: string[] = [];
+  const userStories: Prd["userStories"] = [];
+  const functionalRequirements: Prd["functionalRequirements"] = [];
+
+  const lines = markdown.split("\n");
+
+  let currentSection: "goals" | "user-stories" | "functional-requirements" | null = null;
+  let currentStory: Prd["userStories"][number] | null = null;
+  let inAcceptanceCriteria = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Detect section headers
+    if (/^## Goals/i.test(trimmed)) {
+      currentSection = "goals";
+      currentStory = null;
+      inAcceptanceCriteria = false;
+      continue;
+    }
+    if (/^## User Stories/i.test(trimmed)) {
+      currentSection = "user-stories";
+      currentStory = null;
+      inAcceptanceCriteria = false;
+      continue;
+    }
+    if (/^## Functional Requirements/i.test(trimmed)) {
+      // Flush any pending user story
+      if (currentStory) {
+        userStories.push(currentStory);
+        currentStory = null;
+      }
+      currentSection = "functional-requirements";
+      inAcceptanceCriteria = false;
+      continue;
+    }
+    // Skip other level-2 sections (e.g. ## Context, ## Non-Goals)
+    if (/^## /.test(trimmed)) {
+      if (currentStory) {
+        userStories.push(currentStory);
+        currentStory = null;
+      }
+      currentSection = null;
+      inAcceptanceCriteria = false;
+      continue;
+    }
+
+    // --- Goals section ---
+    if (currentSection === "goals") {
+      const bulletMatch = trimmed.match(/^[-*]\s+(.+)$/);
+      if (bulletMatch) {
+        goals.push(bulletMatch[1].trim());
+      }
+      continue;
+    }
+
+    // --- User Stories section ---
+    if (currentSection === "user-stories") {
+      // Detect ### US-xxx: Title
+      const storyMatch = trimmed.match(/^###\s+(US-\d+):\s+(.+)$/);
+      if (storyMatch) {
+        // Flush previous story
+        if (currentStory) {
+          userStories.push(currentStory);
+        }
+        currentStory = {
+          id: storyMatch[1],
+          title: storyMatch[2].trim(),
+          description: "",
+          acceptanceCriteria: [],
+        };
+        inAcceptanceCriteria = false;
+        continue;
+      }
+
+      if (!currentStory) continue;
+
+      // Detect **Acceptance Criteria:**
+      if (/\*\*Acceptance Criteria:\*\*/i.test(trimmed)) {
+        inAcceptanceCriteria = true;
+        continue;
+      }
+
+      if (inAcceptanceCriteria) {
+        // Acceptance criteria items: - [ ] text or - [x] text
+        const acMatch = trimmed.match(/^[-*]\s+\[[ x]?\]\s+(.+)$/i);
+        if (acMatch) {
+          const acIndex = currentStory.acceptanceCriteria.length + 1;
+          currentStory.acceptanceCriteria.push({
+            id: `${currentStory.id}-AC${String(acIndex).padStart(2, "0")}`,
+            text: acMatch[1].trim(),
+          });
+        }
+        continue;
+      }
+
+      // Story description lines (between **As a** ... and **Acceptance Criteria:**)
+      if (trimmed.length > 0) {
+        // Strip bold markers for cleaner description
+        const descLine = trimmed.replace(/\*\*/g, "");
+        if (currentStory.description) {
+          currentStory.description += " " + descLine;
+        } else {
+          currentStory.description = descLine;
+        }
+      }
+      continue;
+    }
+
+    // --- Functional Requirements section ---
+    if (currentSection === "functional-requirements") {
+      // Accept both "- FR-1: desc" and "- **FR-1:** desc" (bold id)
+      const frMatch = trimmed.match(/^[-*]\s+(?:\*\*)?(FR-\d+)(?:\*\*)?:\s*(.+)$/);
+      if (frMatch) {
+        functionalRequirements.push({
+          id: frMatch[1],
+          description: frMatch[2].trim(),
+        });
+      }
+      continue;
+    }
+  }
+
+  // Flush last pending story
+  if (currentStory) {
+    userStories.push(currentStory);
+  }
+
+  return { goals, userStories, functionalRequirements };
+}
+
+// ---------------------------------------------------------------------------
+// Main command
+// ---------------------------------------------------------------------------
+
+export async function runApproveRequirement(): Promise<void> {
+  const projectRoot = process.cwd();
+  const state = await readState(projectRoot);
+
+  // --- US-001: Validate status ---
+  const requirementDefinition = state.phases.define.requirement_definition;
+  if (requirementDefinition.status !== "in_progress") {
+    throw new Error(
+      `Cannot approve requirement from status '${requirementDefinition.status}'. Expected in_progress.`,
+    );
+  }
+
+  const requirementFile = requirementDefinition.file;
+  if (!requirementFile) {
+    throw new Error("Cannot approve requirement: define.requirement_definition.file is missing.");
+  }
+
+  const requirementPath = join(projectRoot, FLOW_REL_DIR, requirementFile);
+  if (!(await exists(requirementPath))) {
+    throw new Error(`Cannot approve requirement: file not found at ${requirementPath}`);
+  }
+
+  // --- US-002: Parse PRD markdown and generate JSON ---
+  const markdown = await readFile(requirementPath, "utf-8");
+  const prdData = parsePrd(markdown);
+  const prdJsonFileName = `it_${state.current_iteration}_PRD.json`;
+  const prdJsonRelPath = join(FLOW_REL_DIR, prdJsonFileName);
+
+  // Invoke write-json CLI to validate and write the PRD JSON
+  const prdJsonString = JSON.stringify(prdData);
+  const result =
+    await $`bun ${CLI_PATH} write-json --schema prd --out ${prdJsonRelPath} --data ${prdJsonString}`
+      .cwd(projectRoot)
+      .nothrow()
+      .quiet();
+
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr.toString().trim();
+    console.error("PRD JSON generation failed. Requirement remains in_progress.");
+    if (stderr) {
+      console.error(stderr);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  // --- US-001: Transition status only after successful JSON generation ---
+  requirementDefinition.status = "approved";
+
+  // --- US-002: Record PRD generation in state ---
+  state.phases.define.prd_generation.status = "completed";
+  state.phases.define.prd_generation.file = prdJsonFileName;
+
+  state.last_updated = new Date().toISOString();
+  state.updated_by = "nvst:approve-requirement";
+
+  await writeState(projectRoot, state);
+
+  console.log("Requirement approved.");
+  console.log(`PRD JSON written to ${prdJsonRelPath}`);
+}

package/src/commands/approve-test-plan.test.ts

@@ -0,0 +1,193 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { TestPlanSchema } from "../../schemas/test-plan";
+import { readState, writeState } from "../state";
+import { parseTestPlan, runApproveTestPlan } from "./approve-test-plan";
+
+async function createProjectRoot(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "nvst-approve-test-plan-"));
+}
+
+async function withCwd<T>(cwd: string, fn: () => Promise<T>): Promise<T> {
+  const previous = process.cwd();
+  process.chdir(cwd);
+  try {
+    return await fn();
+  } finally {
+    process.chdir(previous);
+  }
+}
+
+async function seedState(
+  projectRoot: string,
+  status: "pending" | "pending_approval" | "created",
+  file: string | null,
+) {
+  await mkdir(join(projectRoot, ".agents", "flow"), { recursive: true });
+  await writeState(projectRoot, {
+    current_iteration: "000003",
+    current_phase: "prototype",
+    phases: {
+      define: {
+        requirement_definition: { status: "approved", file: "it_000003_product-requirement-document.md" },
+        prd_generation: { status: "completed", file: "it_000003_PRD.json" },
+      },
+      prototype: {
+        project_context: { status: "created", file: ".agents/PROJECT_CONTEXT.md" },
+        test_plan: { status, file },
+        tp_generation: { status: "pending", file: null },
+        prototype_build: { status: "pending", file: null },
+        test_execution: { status: "pending", file: null },
+        prototype_approved: false,
+      },
+      refactor: {
+        evaluation_report: { status: "pending", file: null },
+        refactor_plan: { status: "pending", file: null },
+        refactor_execution: { status: "pending", file: null },
+        changelog: { status: "pending", file: null },
+      },
+    },
+    last_updated: "2026-02-21T00:00:00.000Z",
+    updated_by: "seed",
+    history: [],
+  });
+}
+
+const createdRoots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(createdRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("approve test-plan command", () => {
+  test("registers approve test-plan command in CLI dispatch", async () => {
+    const source = await readFile(join(process.cwd(), "src", "cli.ts"), "utf8");
+
+    expect(source).toContain('import { runApproveTestPlan } from "./commands/approve-test-plan";');
+    expect(source).toContain('if (subcommand === "test-plan") {');
+    expect(source).toContain("await runApproveTestPlan();");
+  });
+
+  test("requires test_plan.status to be pending_approval", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "pending", "it_000003_test-plan.md");
+
+    await withCwd(projectRoot, async () => {
+      await expect(runApproveTestPlan()).rejects.toThrow(
+        "Cannot approve test plan from status 'pending'. Expected pending_approval.",
+      );
+    });
+  });
+
+  test("approves test plan, generates TP JSON via write-json, and updates state fields", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "pending_approval", "it_000003_test-plan.md");
+
+    const testPlanPath = join(projectRoot, ".agents", "flow", "it_000003_test-plan.md");
+    await writeFile(
+      testPlanPath,
+      [
+        "# Test plan - Iteration 000003",
+        "| Test Case ID | Description | Type (unit/integration/e2e) | Mode (automated/manual) | Correlated Requirements (US-XXX, FR-X) | Expected Result |",
+        "|---|---|---|---|---|---|",
+        "| TC-US001-01 | Validate login success | integration | automated | US-001, FR-1 | Login succeeds with valid credentials |",
+        "| TC-US001-02 | Validate login error handling | integration | manual | US-001, FR-2 | Login error is shown for invalid credentials |",
+        "## Scope",
+        "- Validate login",
+        "## Environment and data",
+        "- staging + seeded user",
+      ].join("\n"),
+      "utf8",
+    );
+
+    let capturedSchema = "";
+    let capturedOutPath = "";
+    let capturedPayload = "";
+
+    await withCwd(projectRoot, async () => {
+      await runApproveTestPlan({
+        invokeWriteJsonFn: async (_root, schemaName, outPath, data) => {
+          capturedSchema = schemaName;
+          capturedOutPath = outPath;
+          capturedPayload = data;
+          await writeFile(join(projectRoot, outPath), data, "utf8");
+          return { exitCode: 0, stderr: "" };
+        },
+        nowFn: () => new Date("2026-02-21T05:00:00.000Z"),
+      });
+    });
+
+    expect(capturedSchema).toBe("test-plan");
+    expect(capturedOutPath).toBe(".agents/flow/it_000003_TP.json");
+
+    const parsedPayload = JSON.parse(capturedPayload) as unknown;
+    const validation = TestPlanSchema.safeParse(parsedPayload);
+    expect(validation.success).toBe(true);
+    if (!validation.success) {
+      throw new Error("Expected test-plan payload to be valid");
+    }
+    expect(validation.data.overallStatus).toBe("pending");
+    expect(validation.data.scope).toEqual(["Validate login"]);
+    expect(validation.data.automatedTests).toEqual([
+      {
+        id: "TC-US001-01",
+        description: "Validate login success",
+        status: "pending",
+        correlatedRequirements: ["US-001", "FR-1"],
+      },
+    ]);
+    expect(validation.data.exploratoryManualTests).toEqual([
+      {
+        id: "TC-US001-02",
+        description: "Validate login error handling",
+        status: "pending",
+        correlatedRequirements: ["US-001", "FR-2"],
+      },
+    ]);
+    expect(validation.data.environmentData).toEqual(["staging + seeded user"]);
+
+    const state = await readState(projectRoot);
+    expect(state.phases.prototype.test_plan.status).toBe("created");
+    expect(state.phases.prototype.tp_generation.status).toBe("created");
+    expect(state.phases.prototype.tp_generation.file).toBe("it_000003_TP.json");
+    expect(state.last_updated).toBe("2026-02-21T05:00:00.000Z");
+    expect(state.updated_by).toBe("nvst:approve-test-plan");
+  });
+
+  test("parseTestPlan extracts IDs, correlated requirements, and defaults statuses to pending", () => {
+    const parsed = parseTestPlan(
+      [
+        "# Test plan - Iteration 000004",
+        "| Test Case ID | Description | Type (unit/integration/e2e) | Mode (automated/manual) | Correlated Requirements (US-XXX, FR-X) | Expected Result |",
+        "|---|---|---|---|---|---|",
+        "| TC-US004-01 | Parser maps automated test | unit | automated | us-004, FR-7, INVALID | Entry is captured |",
+        "| TC-US004-02 | Parser maps manual test | integration | manual | FR-8, us-004 | Entry is captured |",
+        "## Scope",
+        "- Parser migration",
+        "## Environment and data",
+        "- local fixtures",
+      ].join("\n"),
+    );
+
+    expect(parsed.overallStatus).toBe("pending");
+    expect(parsed.automatedTests[0]).toEqual({
+      id: "TC-US004-01",
+      description: "Parser maps automated test",
+      status: "pending",
+      correlatedRequirements: ["US-004", "FR-7"],
+    });
+    expect(parsed.exploratoryManualTests[0]).toEqual({
+      id: "TC-US004-02",
+      description: "Parser maps manual test",
+      status: "pending",
+      correlatedRequirements: ["FR-8", "US-004"],
+    });
+    const validation = TestPlanSchema.safeParse(parsed);
+    expect(validation.success).toBe(true);
+  });
+});

package/src/commands/approve-test-plan.ts

@@ -0,0 +1,202 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { $ } from "bun";
+
+import { CLI_PATH } from "../cli-path";
+import type { TestPlan } from "../../schemas/test-plan";
+import { exists, FLOW_REL_DIR, readState, writeState } from "../state";
+
+interface WriteJsonResult {
+  exitCode: number;
+  stderr: string;
+}
+
+interface ApproveTestPlanDeps {
+  existsFn: (path: string) => Promise<boolean>;
+  invokeWriteJsonFn: (
+    projectRoot: string,
+    schemaName: string,
+    outPath: string,
+    data: string,
+  ) => Promise<WriteJsonResult>;
+  nowFn: () => Date;
+  readFileFn: typeof readFile;
+}
+
+const defaultDeps: ApproveTestPlanDeps = {
+  existsFn: exists,
+  invokeWriteJsonFn: runWriteJsonCommand,
+  nowFn: () => new Date(),
+  readFileFn: readFile,
+};
+
+export function parseTestPlan(markdown: string): TestPlan {
+  const scope: string[] = [];
+  const environmentData: string[] = [];
+  const automatedTests: TestPlan["automatedTests"] = [];
+  const exploratoryManualTests: TestPlan["exploratoryManualTests"] = [];
+
+  type Section = "scope" | "environmentData" | null;
+  let currentSection: Section = null;
+  let inTable = false;
+
+  const parseRequirements = (cell: string): string[] =>
+    cell
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter((entry) => /^(US-\d{3}|FR-\d+)$/i.test(entry))
+      .map((entry) => entry.toUpperCase());
+
+  const lines = markdown.split("\n");
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (/^##\s+Scope$/i.test(trimmed)) {
+      currentSection = "scope";
+      inTable = false;
+      continue;
+    }
+    if (/^##\s+Environment\s*(?:and|&)\s*data$/i.test(trimmed)) {
+      currentSection = "environmentData";
+      inTable = false;
+      continue;
+    }
+
+    if (
+      trimmed.startsWith("|")
+      && trimmed.includes("Test Case ID")
+      && trimmed.includes("Correlated Requirements")
+    ) {
+      inTable = true;
+      currentSection = null;
+      continue;
+    }
+
+    if (inTable && trimmed.startsWith("|")) {
+      if (trimmed.includes("---|")) continue;
+
+      const cells = trimmed
+        .split("|")
+        .map((c) => c.trim())
+        .filter((c, i, a) => i > 0 && i < a.length - 1);
+
+      if (cells.length >= 6) {
+        const [id, description, , mode, correlatedRequirementsCell] = cells;
+        if (id === "Test Case ID") continue;
+
+        const item = {
+          id,
+          description,
+          status: "pending" as const,
+          correlatedRequirements: parseRequirements(correlatedRequirementsCell),
+        };
+        if (mode.toLowerCase().includes("automated")) {
+          automatedTests.push(item);
+        } else {
+          exploratoryManualTests.push(item);
+        }
+      }
+      continue;
+    }
+
+    if (inTable && trimmed.length === 0) {
+      inTable = false;
+      continue;
+    }
+
+    if (!currentSection || trimmed.length === 0 || /^<!--/.test(trimmed)) {
+      continue;
+    }
+
+    const bulletMatch = trimmed.match(/^[-*]\s+(.+)$/);
+    const value = bulletMatch ? bulletMatch[1].trim() : trimmed;
+    if (!value) continue;
+
+    if (currentSection === "scope") scope.push(value);
+    if (currentSection === "environmentData") environmentData.push(value);
+  }
+
+  return {
+    overallStatus: "pending",
+    scope,
+    environmentData,
+    automatedTests,
+    exploratoryManualTests,
+  };
+}
+
+async function runWriteJsonCommand(
+  projectRoot: string,
+  schemaName: string,
+  outPath: string,
+  data: string,
+): Promise<WriteJsonResult> {
+  const result =
+    await $`bun ${CLI_PATH} write-json --schema ${schemaName} --out ${outPath} --data ${data}`
+      .cwd(projectRoot)
+      .nothrow()
+      .quiet();
+
+  return {
+    exitCode: result.exitCode,
+    stderr: result.stderr.toString().trim(),
+  };
+}
+
+export async function runApproveTestPlan(
+  deps: Partial<ApproveTestPlanDeps> = {},
+): Promise<void> {
+  const projectRoot = process.cwd();
+  const state = await readState(projectRoot);
+  const mergedDeps: ApproveTestPlanDeps = { ...defaultDeps, ...deps };
+
+  const testPlan = state.phases.prototype.test_plan;
+  if (testPlan.status !== "pending_approval") {
+    throw new Error(
+      `Cannot approve test plan from status '${testPlan.status}'. Expected pending_approval.`,
+    );
+  }
+
+  const testPlanFile = testPlan.file;
+  if (!testPlanFile) {
+    throw new Error("Cannot approve test plan: prototype.test_plan.file is missing.");
+  }
+
+  const testPlanPath = join(projectRoot, FLOW_REL_DIR, testPlanFile);
+  if (!(await mergedDeps.existsFn(testPlanPath))) {
+    throw new Error(`Cannot approve test plan: file not found at ${testPlanPath}`);
+  }
+
+  const markdown = await mergedDeps.readFileFn(testPlanPath, "utf-8");
+  const tpData = parseTestPlan(markdown);
+  const tpJsonFileName = `it_${state.current_iteration}_TP.json`;
+  const tpJsonRelPath = join(FLOW_REL_DIR, tpJsonFileName);
+
+  const writeResult = await mergedDeps.invokeWriteJsonFn(
+    projectRoot,
+    "test-plan",
+    tpJsonRelPath,
+    JSON.stringify(tpData),
+  );
+
+  if (writeResult.exitCode !== 0) {
+    console.error("Test-plan JSON generation failed. Test plan remains pending_approval.");
+    if (writeResult.stderr) {
+      console.error(writeResult.stderr);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  testPlan.status = "created";
+  state.phases.prototype.tp_generation.status = "created";
+  state.phases.prototype.tp_generation.file = tpJsonFileName;
+  state.last_updated = mergedDeps.nowFn().toISOString();
+  state.updated_by = "nvst:approve-test-plan";
+
+  await writeState(projectRoot, state);
+
+  console.log("Test plan approved.");
+  console.log(`Test-plan JSON written to ${tpJsonRelPath}`);
+}