@quinteroac/agents-coding-toolkit 0.1.0-preview

package/src/cli.ts

@@ -0,0 +1,578 @@
+#!/usr/bin/env bun
+
+import { join } from "node:path";
+import { parseAgentArg } from "./agent";
+import { runApproveProjectContext } from "./commands/approve-project-context";
+import { runApproveRequirement } from "./commands/approve-requirement";
+import { runApproveTestPlan } from "./commands/approve-test-plan";
+import { runCreateIssue, runCreateIssueFromTestReport } from "./commands/create-issue";
+import { runCreateProjectContext } from "./commands/create-project-context";
+import { runCreatePrototype } from "./commands/create-prototype";
+import { runCreateTestPlan } from "./commands/create-test-plan";
+import { runDefineRequirement } from "./commands/define-requirement";
+import { runDestroy } from "./commands/destroy";
+import { runExecuteAutomatedFix } from "./commands/execute-automated-fix";
+import { runExecuteManualFix } from "./commands/execute-manual-fix";
+import { runExecuteTestPlan } from "./commands/execute-test-plan";
+import { runInit } from "./commands/init";
+import { runRefineProjectContext } from "./commands/refine-project-context";
+import { runRefineRequirement } from "./commands/refine-requirement";
+import { runRefineTestPlan } from "./commands/refine-test-plan";
+import { runStartIteration } from "./commands/start-iteration";
+import { runWriteJson } from "./commands/write-json";
+
+function parseMode(args: string[]): { mode: "strict" | "yolo"; remainingArgs: string[] } {
+  const idx = args.indexOf("--mode");
+  if (idx === -1) {
+    return { mode: "strict", remainingArgs: args };
+  }
+  if (idx + 1 >= args.length) {
+    throw new Error("Missing value for --mode. Expected: strict or yolo.");
+  }
+
+  const mode = args[idx + 1];
+  if (mode !== "strict" && mode !== "yolo") {
+    throw new Error(`Invalid --mode '${mode}'. Expected: strict or yolo.`);
+  }
+
+  const remainingArgs = [...args.slice(0, idx), ...args.slice(idx + 2)];
+  return { mode, remainingArgs };
+}
+
+function extractFlagValue(args: string[], flag: string): { value: string | null; remainingArgs: string[] } {
+  const idx = args.indexOf(flag);
+  if (idx === -1) {
+    return { value: null, remainingArgs: args };
+  }
+
+  if (idx + 1 >= args.length) {
+    throw new Error(`Missing value for ${flag}.`);
+  }
+
+  const value = args[idx + 1];
+  return {
+    value,
+    remainingArgs: [...args.slice(0, idx), ...args.slice(idx + 2)],
+  };
+}
+
+function parseOptionalIntegerFlag(
+  args: string[],
+  flag: "--iterations" | "--retry-on-fail",
+  min: number,
+): { value: number | undefined; remainingArgs: string[] } {
+  const { value, remainingArgs } = extractFlagValue(args, flag);
+  if (value === null) {
+    return { value: undefined, remainingArgs };
+  }
+
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < min) {
+    throw new Error(
+      `Invalid ${flag} value '${value}'. Expected an integer >= ${min}.`,
+    );
+  }
+
+  return { value: parsed, remainingArgs };
+}
+
+function printUsage() {
+  console.log(`Usage: nvst <command> [options]
+
+Commands:
+  init               Initialize toolkit files in the current directory
+  start iteration    Start a new iteration (archives previous if exists)
+  create project-context --agent <provider> [--mode strict|yolo]
+                     Generate/update .agents/PROJECT_CONTEXT.md via agent
+  create test-plan --agent <provider> [--force]
+                     Generate test plan document for current iteration
+  create prototype --agent <provider> [--iterations <N>] [--retry-on-fail <N>] [--stop-on-critical]
+                     Initialize prototype build for current iteration
+  create issue --agent <provider>
+                     Create issues interactively via agent
+  create issue --test-execution-report
+                     Derive issues from test execution results
+  approve project-context
+                     Mark project context as approved
+  approve test-plan
+                     Mark test plan as approved and generate structured TP JSON
+  refine project-context --agent <provider> [--challenge]
+                     Refine project context via agent (editor or challenge mode)
+  define requirement --agent <provider>
+                     Create requirement document via agent
+  refine requirement --agent <provider> [--challenge]
+                     Refine requirement document via agent
+  refine test-plan --agent <provider> [--challenge]
+                     Refine test plan document via agent
+  execute test-plan --agent <provider>
+                     Execute approved structured test-plan JSON via agent
+  execute automated-fix --agent <provider> [--iterations <N>] [--retry-on-fail <N>]
+                     Attempt automated fixes for open issues in current iteration
+  execute manual-fix --agent <provider>
+                     Find manual-fix issues for current iteration and confirm execution
+  approve requirement
+                     Mark requirement definition as approved
+  write-json --schema <name> --out <path> [--data '<json>']
+                     Write a schema-validated JSON file (payload via --data or stdin)
+  destroy [--clean]  Remove files generated by nvst
+
+Options:
+  --agent            Agent provider (claude, codex, gemini, cursor) for agent-backed commands
+  --mode             Create mode for project-context (strict or yolo)
+  --iterations       Maximum prototype passes (integer >= 1)
+  --retry-on-fail    Retry attempts per failed story (integer >= 0)
+  --stop-on-critical Stop execution after critical failures
+  --force            Overwrite output file without confirmation
+  --challenge        Run refine in challenger mode
+  --clean            When used with destroy, also removes .agents/flow/archived
+  -h, --help         Show this help message
+  -v, --version      Print version and exit`);
+}
+
+async function printVersion(): Promise<void> {
+  const pkgPath = join(import.meta.dir, "..", "package.json");
+  try {
+    const pkg = (await Bun.file(pkgPath).json()) as { version?: string };
+    console.log(pkg?.version ?? "unknown");
+  } catch {
+    console.log("unknown");
+  }
+}
+
+async function main() {
+  const [, , command, ...args] = process.argv;
+
+  if (command === "-v" || command === "--version") {
+    await printVersion();
+    return;
+  }
+
+  if (!command || command === "-h" || command === "--help" || command === "help") {
+    printUsage();
+    return;
+  }
+
+  if (command === "init") {
+    if (args.length > 0) {
+      console.error(`Unknown option(s) for init: ${args.join(" ")}`);
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+    await runInit();
+    return;
+  }
+
+  if (command === "destroy") {
+    const clean = args.includes("--clean");
+    const unknownArgs = args.filter((arg) => arg !== "--clean");
+    if (unknownArgs.length > 0) {
+      console.error(`Unknown option(s) for destroy: ${unknownArgs.join(" ")}`);
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+    await runDestroy({ clean });
+    return;
+  }
+
+  if (command === "start") {
+    if (args[0] !== "iteration" || args.length !== 1) {
+      console.error(`Usage for start: nvst start iteration`);
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+    await runStartIteration();
+    return;
+  }
+
+  if (command === "create") {
+    if (args.length === 0) {
+      console.error(
+        `Usage for create: nvst create <project-context|test-plan|prototype|issue> --agent <provider> [options]`,
+      );
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+
+    const subcommand = args[0];
+
+    if (subcommand === "project-context") {
+      try {
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+        const { mode, remainingArgs: postModeArgs } = parseMode(postAgentArgs);
+
+        if (postModeArgs.length > 0) {
+          console.error(`Unknown option(s) for create project-context: ${postModeArgs.join(" ")}`);
+          printUsage();
+          process.exitCode = 1;
+          return;
+        }
+
+        await runCreateProjectContext({ provider, mode });
+        return;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    if (subcommand === "prototype") {
+      try {
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+
+        const {
+          value: iterations,
+          remainingArgs: postIterationsArgs,
+        } = parseOptionalIntegerFlag(postAgentArgs, "--iterations", 1);
+        const {
+          value: retryOnFail,
+          remainingArgs: postRetryArgs,
+        } = parseOptionalIntegerFlag(postIterationsArgs, "--retry-on-fail", 0);
+
+        const stopOnCritical = postRetryArgs.includes("--stop-on-critical");
+        const unknownArgs = postRetryArgs.filter((arg) => arg !== "--stop-on-critical");
+        if (unknownArgs.length > 0) {
+          console.error(`Unknown option(s) for create prototype: ${unknownArgs.join(" ")}`);
+          printUsage();
+          process.exitCode = 1;
+          return;
+        }
+
+        await runCreatePrototype({ provider, iterations, retryOnFail, stopOnCritical });
+        return;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    if (subcommand === "test-plan") {
+      try {
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+        const force = postAgentArgs.includes("--force");
+        const unknownArgs = postAgentArgs.filter((arg) => arg !== "--force");
+
+        if (unknownArgs.length > 0) {
+          console.error(`Unknown option(s) for create test-plan: ${unknownArgs.join(" ")}`);
+          printUsage();
+          process.exitCode = 1;
+          return;
+        }
+
+        await runCreateTestPlan({ provider, force });
+        return;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    if (subcommand === "issue") {
+      const subArgs = args.slice(1);
+
+      // Check for --help before parsing
+      if (subArgs.includes("--help") || subArgs.includes("-h")) {
+        console.log(`Usage for create issue:
+  nvst create issue --agent <provider>           Create issues interactively via agent
+  nvst create issue --test-execution-report      Derive issues from test execution results
+
+Providers: claude, codex, gemini, cursor`);
+        printUsage();
+        return;
+      }
+
+      try {
+        // Check for --test-execution-report flag
+        if (subArgs.includes("--test-execution-report")) {
+          const remaining = subArgs.filter((a) => a !== "--test-execution-report");
+          if (remaining.length > 0) {
+            console.error(`Unknown option(s) for create issue --test-execution-report: ${remaining.join(" ")}`);
+            printUsage();
+            process.exitCode = 1;
+            return;
+          }
+          await runCreateIssueFromTestReport();
+          return;
+        }
+
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(subArgs);
+
+        if (postAgentArgs.length > 0) {
+          console.error(`Unknown option(s) for create issue: ${postAgentArgs.join(" ")}`);
+          printUsage();
+          process.exitCode = 1;
+          return;
+        }
+
+        await runCreateIssue({ provider });
+        return;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    console.error(`Unknown create subcommand: ${subcommand}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  if (command === "define") {
+    if (args.length === 0 || args[0] !== "requirement") {
+      console.error(`Usage for define: nvst define requirement --agent <provider>`);
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+
+    try {
+      const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+
+      if (postAgentArgs.length > 0) {
+        console.error(`Unknown option(s) for define requirement: ${postAgentArgs.join(" ")}`);
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+
+      await runDefineRequirement({ provider });
+      return;
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  if (command === "refine") {
+    if (args.length === 0) {
+      console.error(
+        `Usage for refine: nvst refine <requirement|project-context|test-plan> --agent <provider> [--challenge]`,
+      );
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+
+    const subcommand = args[0];
+
+    if (subcommand === "requirement") {
+      try {
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+        const challenge = postAgentArgs.includes("--challenge");
+        const unknownArgs = postAgentArgs.filter((arg) => arg !== "--challenge");
+
+        if (unknownArgs.length > 0) {
+          console.error(`Unknown option(s) for refine requirement: ${unknownArgs.join(" ")}`);
+          printUsage();
+          process.exitCode = 1;
+          return;
+        }
+
+        await runRefineRequirement({ provider, challenge });
+        return;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    if (subcommand === "project-context") {
+      try {
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+        const challenge = postAgentArgs.includes("--challenge");
+        const unknownArgs = postAgentArgs.filter((arg) => arg !== "--challenge");
+
+        if (unknownArgs.length > 0) {
+          console.error(
+            `Unknown option(s) for refine project-context: ${unknownArgs.join(" ")}`,
+          );
+          printUsage();
+          process.exitCode = 1;
+          return;
+        }
+
+        await runRefineProjectContext({ provider, challenge });
+        return;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    if (subcommand === "test-plan") {
+      try {
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+        const challenge = postAgentArgs.includes("--challenge");
+        const unknownArgs = postAgentArgs.filter((arg) => arg !== "--challenge");
+
+        if (unknownArgs.length > 0) {
+          console.error(`Unknown option(s) for refine test-plan: ${unknownArgs.join(" ")}`);
+          printUsage();
+          process.exitCode = 1;
+          return;
+        }
+
+        await runRefineTestPlan({ provider, challenge });
+        return;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    console.error(`Unknown refine subcommand: ${subcommand}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  if (command === "approve") {
+    if (args.length !== 1) {
+      console.error(`Usage for approve: nvst approve <requirement|project-context|test-plan>`);
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+
+    const subcommand = args[0];
+
+    if (subcommand === "requirement") {
+      await runApproveRequirement();
+      return;
+    }
+
+    if (subcommand === "project-context") {
+      await runApproveProjectContext();
+      return;
+    }
+
+    if (subcommand === "test-plan") {
+      await runApproveTestPlan();
+      return;
+    }
+
+    console.error(`Unknown approve subcommand: ${subcommand}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  if (command === "execute") {
+    if (args.length === 0) {
+      console.error(`Usage for execute: nvst execute <test-plan|automated-fix|manual-fix> --agent <provider>`);
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+
+    const subcommand = args[0];
+
+    if (subcommand === "test-plan") {
+      try {
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+        if (postAgentArgs.length > 0) {
+          console.error(`Unknown option(s) for execute test-plan: ${postAgentArgs.join(" ")}`);
+          printUsage();
+          process.exitCode = 1;
+          return;
+        }
+
+        await runExecuteTestPlan({ provider });
+        return;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    if (subcommand === "automated-fix") {
+      try {
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+        const {
+          value: iterations,
+          remainingArgs: postIterationsArgs,
+        } = parseOptionalIntegerFlag(postAgentArgs, "--iterations", 1);
+        const {
+          value: retryOnFail,
+          remainingArgs: postRetryArgs,
+        } = parseOptionalIntegerFlag(postIterationsArgs, "--retry-on-fail", 0);
+
+        if (postRetryArgs.length > 0) {
+          console.error(`Unknown option(s) for execute automated-fix: ${postRetryArgs.join(" ")}`);
+          printUsage();
+          process.exitCode = 1;
+          return;
+        }
+
+        await runExecuteAutomatedFix({ provider, iterations, retryOnFail });
+        return;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    if (subcommand === "manual-fix") {
+      try {
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+        if (postAgentArgs.length > 0) {
+          console.error(`Unknown option(s) for execute manual-fix: ${postAgentArgs.join(" ")}`);
+          printUsage();
+          process.exitCode = 1;
+          return;
+        }
+
+        await runExecuteManualFix({ provider });
+        return;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    console.error(`Unknown execute subcommand: ${subcommand}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  if (command === "write-json") {
+    await runWriteJson({ args });
+    return;
+  }
+
+  console.error(`Unknown command: ${command}`);
+  printUsage();
+  process.exitCode = 1;
+}
+
+main().catch((error) => {
+  console.error("nvst failed:", error);
+  process.exitCode = 1;
+});

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

@@ -0,0 +1,37 @@
+import { join } from "node:path";
+
+import { exists, readState, writeState } from "../state";
+
+export async function runApproveProjectContext(): Promise<void> {
+    const projectRoot = process.cwd();
+    const state = await readState(projectRoot);
+
+    // US-002-AC01: Validate status is pending_approval
+    const projectContext = state.phases.prototype.project_context;
+    if (projectContext.status !== "pending_approval") {
+        throw new Error(
+            `Cannot approve project context from status '${projectContext.status}'. Expected pending_approval.`,
+        );
+    }
+
+    // US-002-AC01: Validate project context file exists
+    const contextFile = projectContext.file;
+    if (!contextFile) {
+        throw new Error("Cannot approve project context: project_context.file is missing.");
+    }
+
+    const contextPath = join(projectRoot, contextFile);
+    if (!(await exists(contextPath))) {
+        throw new Error(`Cannot approve project context: file not found at ${contextPath}`);
+    }
+
+    // US-002-AC02: Transition status to created
+    projectContext.status = "created";
+    state.last_updated = new Date().toISOString();
+    state.updated_by = "nvst:approve-project-context";
+
+    await writeState(projectRoot, state);
+
+    // US-002-AC03: Clear feedback
+    console.log("Project context approved.");
+}