@quinteroac/agents-coding-toolkit 0.1.0-preview → 0.2.0

package/src/commands/approve-requirement.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { $ } from "bun";
 
 import { CLI_PATH } from "../cli-path";
+import { assertGuardrail } from "../guardrail";
 import type { Prd } from "../../scaffold/schemas/tmpl_prd";
 import { exists, readState, writeState, FLOW_REL_DIR } from "../state";
 
@@ -154,17 +155,75 @@ function parsePrd(markdown: string): Prd {
 // Main command
 // ---------------------------------------------------------------------------
 
-export async function runApproveRequirement(): Promise<void> {
+interface WriteJsonResult {
+  exitCode: number;
+  stderr: string;
+}
+
+interface ApproveRequirementDeps {
+  existsFn: (path: string) => Promise<boolean>;
+  invokeWriteJsonFn: (
+    projectRoot: string,
+    schemaName: string,
+    outPath: string,
+    data: string,
+  ) => Promise<WriteJsonResult>;
+  nowFn: () => Date;
+  readFileFn: typeof readFile;
+}
+
+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(),
+  };
+}
+
+const defaultDeps: ApproveRequirementDeps = {
+  existsFn: exists,
+  invokeWriteJsonFn: runWriteJsonCommand,
+  nowFn: () => new Date(),
+  readFileFn: readFile,
+};
+
+export async function runApproveRequirement(
+  optsOrDeps: { force?: boolean } | Partial<ApproveRequirementDeps> = {},
+  maybeDeps: Partial<ApproveRequirementDeps> = {},
+): Promise<void> {
+  const isDepsArg =
+    typeof optsOrDeps === "object"
+    && optsOrDeps !== null
+    && (
+      "existsFn" in optsOrDeps
+      || "invokeWriteJsonFn" in optsOrDeps
+      || "nowFn" in optsOrDeps
+      || "readFileFn" in optsOrDeps
+    );
+  const force = isDepsArg ? false : ((optsOrDeps as { force?: boolean }).force ?? false);
   const projectRoot = process.cwd();
   const state = await readState(projectRoot);
+  const deps = isDepsArg ? optsOrDeps : maybeDeps;
+  const mergedDeps: ApproveRequirementDeps = { ...defaultDeps, ...deps };
 
   // --- 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.`,
-    );
-  }
+  await assertGuardrail(
+    state,
+    requirementDefinition.status !== "in_progress",
+    `Cannot approve requirement from status '${requirementDefinition.status}'. Expected in_progress.`,
+    { force },
+  );
 
   const requirementFile = requirementDefinition.file;
   if (!requirementFile) {
@@ -172,26 +231,26 @@ export async function runApproveRequirement(): Promise<void> {
   }
 
   const requirementPath = join(projectRoot, FLOW_REL_DIR, requirementFile);
-  if (!(await exists(requirementPath))) {
+  if (!(await mergedDeps.existsFn(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 markdown = await mergedDeps.readFileFn(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();
+  const result = await mergedDeps.invokeWriteJsonFn(
+    projectRoot,
+    "prd",
+    prdJsonRelPath,
+    JSON.stringify(prdData),
+  );
 
   if (result.exitCode !== 0) {
-    const stderr = result.stderr.toString().trim();
+    const stderr = result.stderr.trim();
     console.error("PRD JSON generation failed. Requirement remains in_progress.");
     if (stderr) {
       console.error(stderr);
@@ -207,7 +266,7 @@ export async function runApproveRequirement(): Promise<void> {
   state.phases.define.prd_generation.status = "completed";
   state.phases.define.prd_generation.file = prdJsonFileName;
 
-  state.last_updated = new Date().toISOString();
+  state.last_updated = mergedDeps.nowFn().toISOString();
   state.updated_by = "nvst:approve-requirement";
 
   await writeState(projectRoot, state);

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

@@ -3,7 +3,7 @@ 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 { TestPlanSchema } from "../../scaffold/schemas/tmpl_test-plan";
 import { readState, writeState } from "../state";
 import { parseTestPlan, runApproveTestPlan } from "./approve-test-plan";
 
@@ -68,7 +68,7 @@ describe("approve test-plan command", () => {
 
     expect(source).toContain('import { runApproveTestPlan } from "./commands/approve-test-plan";');
     expect(source).toContain('if (subcommand === "test-plan") {');
-    expect(source).toContain("await runApproveTestPlan();");
+    expect(source).toContain("await runApproveTestPlan({ force });");
   });
 
   test("requires test_plan.status to be pending_approval", async () => {

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

@@ -3,7 +3,8 @@ import { join } from "node:path";
 import { $ } from "bun";
 
 import { CLI_PATH } from "../cli-path";
-import type { TestPlan } from "../../schemas/test-plan";
+import { assertGuardrail } from "../guardrail";
+import type { TestPlan } from "../../scaffold/schemas/tmpl_test-plan";
 import { exists, FLOW_REL_DIR, readState, writeState } from "../state";
 
 interface WriteJsonResult {
@@ -145,18 +146,31 @@ async function runWriteJsonCommand(
 }
 
 export async function runApproveTestPlan(
-  deps: Partial<ApproveTestPlanDeps> = {},
+  optsOrDeps: { force?: boolean } | Partial<ApproveTestPlanDeps> = {},
+  maybeDeps: Partial<ApproveTestPlanDeps> = {},
 ): Promise<void> {
+  const isDepsArg =
+    typeof optsOrDeps === "object"
+    && optsOrDeps !== null
+    && (
+      "existsFn" in optsOrDeps
+      || "invokeWriteJsonFn" in optsOrDeps
+      || "nowFn" in optsOrDeps
+      || "readFileFn" in optsOrDeps
+    );
+  const force = isDepsArg ? false : ((optsOrDeps as { force?: boolean }).force ?? false);
   const projectRoot = process.cwd();
   const state = await readState(projectRoot);
+  const deps = isDepsArg ? optsOrDeps : maybeDeps;
   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.`,
-    );
-  }
+  await assertGuardrail(
+    state,
+    testPlan.status !== "pending_approval",
+    `Cannot approve test plan from status '${testPlan.status}'. Expected pending_approval.`,
+    { force },
+  );
 
   const testPlanFile = testPlan.file;
   if (!testPlanFile) {

package/src/commands/create-issue.test.ts

@@ -420,8 +420,8 @@ describe("create issue --test-execution-report CLI integration", () => {
     const exitCode = await proc.exited;
     const stderr = await new Response(proc.stderr).text();
     expect(stderr).not.toContain("Missing --agent");
-    if (exitCode !== 0) {
-      expect(stderr).toContain("test-execution-results");
+    if (exitCode !== 0 && stderr) {
+      expect(stderr).toMatch(/test-execution-results|not found|Test execution results/);
     }
   });
 

package/src/commands/create-project-context.ts

@@ -7,44 +7,50 @@ import {
   loadSkill,
   type AgentProvider,
 } from "../agent";
+import { assertGuardrail } from "../guardrail";
 import { exists, readState, writeState } from "../state";
 
 export interface CreateProjectContextOptions {
   provider: AgentProvider;
   mode: "strict" | "yolo";
+  force?: boolean;
 }
 
 export async function runCreateProjectContext(opts: CreateProjectContextOptions): Promise<void> {
-  const { provider, mode } = opts;
+  const { provider, mode, force = false } = opts;
   const projectRoot = process.cwd();
   const state = await readState(projectRoot);
 
-  if (state.phases.define.prd_generation.status !== "completed") {
-    throw new Error(
-      "Cannot create project context: define.prd_generation must be completed first.",
-    );
-  }
+  await assertGuardrail(
+    state,
+    state.phases.define.prd_generation.status !== "completed",
+    "Cannot create project context: define.prd_generation must be completed first.",
+    { force },
+  );
 
   const projectContext = state.phases.prototype.project_context;
-  if (projectContext.status === "pending_approval") {
-    throw new Error(
-      "Cannot create project context: project context is pending approval. " +
-      "Run `bun nvst approve project-context` or `bun nvst refine project-context` first.",
-    );
-  }
-
-  if (projectContext.status === "created") {
-    throw new Error(
-      "Cannot create project context: project context already exists. " +
-      "Use `bun nvst refine project-context` to iterate on it.",
-    );
-  }
-
-  if (projectContext.status !== "pending") {
-    throw new Error(
-      `Cannot create project context from status '${projectContext.status}'. Expected pending.`,
-    );
-  }
+  await assertGuardrail(
+    state,
+    projectContext.status === "pending_approval",
+    "Cannot create project context: project context is pending approval. " +
+    "Run `bun nvst approve project-context` or `bun nvst refine project-context` first.",
+    { force },
+  );
+
+  await assertGuardrail(
+    state,
+    projectContext.status === "created",
+    "Cannot create project context: project context already exists. " +
+    "Use `bun nvst refine project-context` to iterate on it.",
+    { force },
+  );
+
+  await assertGuardrail(
+    state,
+    projectContext.status !== "pending",
+    `Cannot create project context from status '${projectContext.status}'. Expected pending.`,
+    { force },
+  );
 
   const prdFile = state.phases.define.prd_generation.file;
   if (!prdFile) {