@quinteroac/agents-coding-toolkit 0.1.0-preview → 0.1.1-preview.0

package/src/commands/refine-refactor-plan.ts

@@ -0,0 +1,95 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  buildPrompt,
+  invokeAgent,
+  loadSkill,
+  type AgentInvokeOptions,
+  type AgentProvider,
+  type AgentResult,
+} from "../agent";
+import { assertGuardrail } from "../guardrail";
+import { exists, FLOW_REL_DIR, readState } from "../state";
+
+export interface RefineRefactorPlanOptions {
+  provider: AgentProvider;
+  challenge: boolean;
+  force?: boolean;
+}
+
+interface RefineRefactorPlanDeps {
+  existsFn: (path: string) => Promise<boolean>;
+  invokeAgentFn: (options: AgentInvokeOptions) => Promise<AgentResult>;
+  loadSkillFn: (projectRoot: string, skillName: string) => Promise<string>;
+  readFileFn: typeof readFile;
+}
+
+const defaultDeps: RefineRefactorPlanDeps = {
+  existsFn: exists,
+  invokeAgentFn: invokeAgent,
+  loadSkillFn: loadSkill,
+  readFileFn: readFile,
+};
+
+export async function runRefineRefactorPlan(
+  opts: RefineRefactorPlanOptions,
+  deps: Partial<RefineRefactorPlanDeps> = {},
+): Promise<void> {
+  const { provider, challenge, force = false } = opts;
+  const projectRoot = process.cwd();
+  const state = await readState(projectRoot);
+  const mergedDeps: RefineRefactorPlanDeps = { ...defaultDeps, ...deps };
+
+  const refactorPlan = state.phases.refactor.refactor_plan;
+  await assertGuardrail(
+    state,
+    refactorPlan.status !== "pending_approval",
+    `Cannot refine refactor plan from status '${refactorPlan.status}'. Expected pending_approval.`,
+    { force },
+  );
+
+  const refactorPlanFile = refactorPlan.file;
+  if (!refactorPlanFile) {
+    throw new Error("Cannot refine refactor plan: refactor.refactor_plan.file is missing.");
+  }
+
+  const refactorPlanPath = join(projectRoot, FLOW_REL_DIR, refactorPlanFile);
+  if (!(await mergedDeps.existsFn(refactorPlanPath))) {
+    throw new Error(`Cannot refine refactor plan: file not found at ${refactorPlanPath}`);
+  }
+
+  let skillBody: string;
+  try {
+    skillBody = await mergedDeps.loadSkillFn(projectRoot, "refine-refactor-plan");
+  } catch {
+    throw new Error(
+      "Required skill missing: expected .agents/skills/refine-refactor-plan/SKILL.md.",
+    );
+  }
+
+  const refactorPlanContent = await mergedDeps.readFileFn(refactorPlanPath, "utf8");
+  const context: Record<string, string> = {
+    current_iteration: state.current_iteration,
+    refactor_plan_file: refactorPlanFile,
+    refactor_plan_content: refactorPlanContent,
+  };
+
+  if (challenge) {
+    context.mode = "challenger";
+  }
+
+  const prompt = buildPrompt(skillBody, context);
+  const result = await mergedDeps.invokeAgentFn({
+    provider,
+    prompt,
+    cwd: projectRoot,
+    interactive: true,
+  });
+
+  if (result.exitCode !== 0) {
+    throw new Error(`Agent invocation failed with exit code ${result.exitCode}.`);
+  }
+
+  console.log("Refactor plan refined.");
+}

package/src/commands/refine-requirement.ts

@@ -2,24 +2,27 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 
 import { buildPrompt, invokeAgent, loadSkill, type AgentProvider } from "../agent";
+import { assertGuardrail } from "../guardrail";
 import { exists, readState, FLOW_REL_DIR } from "../state";
 
 export interface RefineRequirementOptions {
   provider: AgentProvider;
   challenge: boolean;
+  force?: boolean;
 }
 
 export async function runRefineRequirement(opts: RefineRequirementOptions): Promise<void> {
-  const { provider, challenge } = opts;
+  const { provider, challenge, force = false } = opts;
   const projectRoot = process.cwd();
   const state = await readState(projectRoot);
 
   const requirementDefinition = state.phases.define.requirement_definition;
-  if (requirementDefinition.status !== "in_progress") {
-    throw new Error(
-      `Cannot refine requirement from status '${requirementDefinition.status}'. Expected in_progress.`,
-    );
-  }
+  await assertGuardrail(
+    state,
+    requirementDefinition.status !== "in_progress",
+    `Cannot refine requirement from status '${requirementDefinition.status}'. Expected in_progress.`,
+    { force },
+  );
 
   const requirementFile = requirementDefinition.file;
   if (!requirementFile) {

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

@@ -69,8 +69,8 @@ describe("refine test-plan command", () => {
 
     expect(source).toContain('import { runRefineTestPlan } from "./commands/refine-test-plan";');
     expect(source).toContain('if (subcommand === "test-plan") {');
-    expect(source).toContain('const challenge = postAgentArgs.includes("--challenge");');
-    expect(source).toContain("await runRefineTestPlan({ provider, challenge });");
+    expect(source).toContain('const challenge = postForceArgs.includes("--challenge");');
+    expect(source).toContain("await runRefineTestPlan({ provider, challenge, force });");
   });
 
   test("loads refine-test-plan skill, reads test plan file context, invokes agent interactively, and does not update state", async () => {

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

@@ -9,11 +9,13 @@ import {
   type AgentProvider,
   type AgentResult,
 } from "../agent";
+import { assertGuardrail } from "../guardrail";
 import { exists, FLOW_REL_DIR, readState } from "../state";
 
 export interface RefineTestPlanOptions {
   provider: AgentProvider;
   challenge: boolean;
+  force?: boolean;
 }
 
 interface RefineTestPlanDeps {
@@ -34,17 +36,18 @@ export async function runRefineTestPlan(
   opts: RefineTestPlanOptions,
   deps: Partial<RefineTestPlanDeps> = {},
 ): Promise<void> {
-  const { provider, challenge } = opts;
+  const { provider, challenge, force = false } = opts;
   const projectRoot = process.cwd();
   const state = await readState(projectRoot);
   const mergedDeps: RefineTestPlanDeps = { ...defaultDeps, ...deps };
 
   const testPlan = state.phases.prototype.test_plan;
-  if (testPlan.status !== "pending_approval") {
-    throw new Error(
-      `Cannot refine test plan from status '${testPlan.status}'. Expected pending_approval.`,
-    );
-  }
+  await assertGuardrail(
+    state,
+    testPlan.status !== "pending_approval",
+    `Cannot refine test plan from status '${testPlan.status}'. Expected pending_approval.`,
+    { force },
+  );
 
   const testPlanFile = testPlan.file;
   if (!testPlanFile) {

package/src/commands/write-json.ts

@@ -5,6 +5,8 @@ import type { ZodSchema } from "zod";
 import { StateSchema } from "../../scaffold/schemas/tmpl_state";
 import { ProgressSchema } from "../../scaffold/schemas/tmpl_progress";
 import { PrdSchema } from "../../scaffold/schemas/tmpl_prd";
+import { RefactorPrdSchema } from "../../scaffold/schemas/tmpl_refactor-prd";
+import { RefactorExecutionProgressSchema } from "../../scaffold/schemas/tmpl_refactor-execution-progress";
 import { TestPlanSchema } from "../../scaffold/schemas/tmpl_test-plan";
 import { IssuesSchema } from "../../scaffold/schemas/tmpl_issues";
 
@@ -12,11 +14,13 @@ import { IssuesSchema } from "../../scaffold/schemas/tmpl_issues";
 // Schema registry — maps CLI name → Zod schema
 // ---------------------------------------------------------------------------
 const SCHEMA_REGISTRY: Record<string, ZodSchema> = {
-    state: StateSchema,
-    progress: ProgressSchema,
-    prd: PrdSchema,
-    "test-plan": TestPlanSchema,
-    issues: IssuesSchema,
+  state: StateSchema,
+  progress: ProgressSchema,
+  prd: PrdSchema,
+  "refactor-prd": RefactorPrdSchema,
+  "refactor-execution-progress": RefactorExecutionProgressSchema,
+  "test-plan": TestPlanSchema,
+  issues: IssuesSchema,
 };
 
 const SUPPORTED_SCHEMAS = Object.keys(SCHEMA_REGISTRY).join(", ");
@@ -25,112 +29,113 @@ const SUPPORTED_SCHEMAS = Object.keys(SCHEMA_REGISTRY).join(", ");
 // Argument parsing helpers
 // ---------------------------------------------------------------------------
 function extractFlag(args: string[], flag: string): { value: string | null; remaining: string[] } {
-    const idx = args.indexOf(flag);
-    if (idx === -1) return { value: null, remaining: args };
-    if (idx + 1 >= args.length) {
-        throw new Error(`Missing value for ${flag}`);
-    }
-    const value = args[idx + 1];
-    const remaining = [...args.slice(0, idx), ...args.slice(idx + 2)];
-    return { value, remaining };
+  const idx = args.indexOf(flag);
+  if (idx === -1) return { value: null, remaining: args };
+  if (idx + 1 >= args.length) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  const value = args[idx + 1];
+  const remaining = [...args.slice(0, idx), ...args.slice(idx + 2)];
+  return { value, remaining };
 }
 
 // ---------------------------------------------------------------------------
 // Read JSON payload from stdin (non-blocking, returns null if nothing piped)
 // ---------------------------------------------------------------------------
 async function readStdin(): Promise<string> {
-    const chunks: Buffer[] = [];
-    const reader = Bun.stdin.stream().getReader();
-    while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        chunks.push(Buffer.from(value));
-    }
-    return Buffer.concat(chunks).toString("utf-8");
+  const chunks: Buffer[] = [];
+  const reader = Bun.stdin.stream().getReader();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(Buffer.from(value));
+  }
+  return Buffer.concat(chunks).toString("utf-8");
 }
 
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
 export interface WriteJsonOptions {
-    args: string[];
+  args: string[];
 }
 
 export async function runWriteJson({ args }: WriteJsonOptions): Promise<void> {
-    // --- Parse --schema ---
-    const { value: schemaName, remaining: afterSchema } = extractFlag(args, "--schema");
-    if (!schemaName) {
-        console.error("Error: --schema <name> is required.");
-        console.error(`Supported schemas: ${SUPPORTED_SCHEMAS}`);
-        process.exitCode = 1;
-        return;
-    }
-
-    const schema = SCHEMA_REGISTRY[schemaName];
-    if (!schema) {
-        console.error(`Error: Unknown schema "${schemaName}".`);
-        console.error(`Supported schemas: ${SUPPORTED_SCHEMAS}`);
-        process.exitCode = 1;
-        return;
-    }
-
-    // --- Parse --out ---
-    const { value: outPath, remaining: afterOut } = extractFlag(afterSchema, "--out");
-    if (!outPath) {
-        console.error("Error: --out <path> is required.");
-        process.exitCode = 1;
-        return;
-    }
-
-    // --- Parse --data (optional) ---
-    const { value: dataArg, remaining: afterData } = extractFlag(afterOut, "--data");
-
-    // Reject unknown args
-    if (afterData.length > 0) {
-        console.error(`Error: Unknown option(s): ${afterData.join(" ")}`);
-        process.exitCode = 1;
-        return;
+  // --- Parse --schema ---
+  const { value: schemaName, remaining: afterSchema } = extractFlag(args, "--schema");
+  if (!schemaName) {
+    console.error("Error: --schema <name> is required.");
+    console.error(`Supported schemas: ${SUPPORTED_SCHEMAS}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const schema = SCHEMA_REGISTRY[schemaName];
+  if (!schema) {
+    console.error(`Error: Unknown schema "${schemaName}".`);
+    console.error(`Supported schemas: ${SUPPORTED_SCHEMAS}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // --- Parse --out ---
+  const { value: outPath, remaining: afterOut } = extractFlag(afterSchema, "--out");
+  if (!outPath) {
+    console.error("Error: --out <path> is required.");
+    process.exitCode = 1;
+    return;
+  }
+
+  // --- Parse --data (optional) ---
+  const { value: dataArg, remaining: afterData } = extractFlag(afterOut, "--data");
+  const unknownArgs = afterData.filter((arg) => arg !== "--force");
+
+  // Reject unknown args
+  if (unknownArgs.length > 0) {
+    console.error(`Error: Unknown option(s): ${unknownArgs.join(" ")}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // --- Obtain JSON payload ---
+  let rawJson: string;
+  if (dataArg) {
+    rawJson = dataArg;
+  } else {
+    // Read from stdin
+    rawJson = await readStdin();
+    if (!rawJson.trim()) {
+      console.error("Error: No JSON payload provided. Use --data '<json>' or pipe via stdin.");
+      process.exitCode = 1;
+      return;
     }
-
-    // --- Obtain JSON payload ---
-    let rawJson: string;
-    if (dataArg) {
-        rawJson = dataArg;
-    } else {
-        // Read from stdin
-        rawJson = await readStdin();
-        if (!rawJson.trim()) {
-            console.error("Error: No JSON payload provided. Use --data '<json>' or pipe via stdin.");
-            process.exitCode = 1;
-            return;
-        }
-    }
-
-    // --- Parse JSON string ---
-    let parsed: unknown;
-    try {
-        parsed = JSON.parse(rawJson);
-    } catch (err) {
-        console.error("Error: Invalid JSON input.");
-        console.error((err as Error).message);
-        process.exitCode = 1;
-        return;
-    }
-
-    // --- Validate against schema ---
-    const result = schema.safeParse(parsed);
-    if (!result.success) {
-        const formatted = result.error.format();
-        console.error(JSON.stringify({ ok: false, schema: schemaName, errors: formatted }, null, 2));
-        process.exitCode = 1;
-        return;
-    }
-
-    // --- Write file ---
-    const resolvedPath = resolve(process.cwd(), outPath);
-    await mkdir(dirname(resolvedPath), { recursive: true });
-    const content = `${JSON.stringify(result.data, null, 2)}\n`;
-    await writeFile(resolvedPath, content, "utf-8");
-
-    console.log(`Written: ${outPath}`);
+  }
+
+  // --- Parse JSON string ---
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawJson);
+  } catch (err) {
+    console.error("Error: Invalid JSON input.");
+    console.error((err as Error).message);
+    process.exitCode = 1;
+    return;
+  }
+
+  // --- Validate against schema ---
+  const result = schema.safeParse(parsed);
+  if (!result.success) {
+    const formatted = result.error.format();
+    console.error(JSON.stringify({ ok: false, schema: schemaName, errors: formatted }, null, 2));
+    process.exitCode = 1;
+    return;
+  }
+
+  // --- Write file ---
+  const resolvedPath = resolve(process.cwd(), outPath);
+  await mkdir(dirname(resolvedPath), { recursive: true });
+  const content = `${JSON.stringify(result.data, null, 2)}\n`;
+  await writeFile(resolvedPath, content, "utf-8");
+
+  console.log(`Written: ${outPath}`);
 }

package/src/force-flag.test.ts

@@ -0,0 +1,144 @@
+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 type { State } from "../scaffold/schemas/tmpl_state";
+import { runApproveProjectContext } from "./commands/approve-project-context";
+
+const createdRoots: string[] = [];
+
+function buildState(flow_guardrail: "strict" | "relaxed"): State {
+  return {
+    current_iteration: "000015",
+    current_phase: "prototype",
+    flow_guardrail,
+    phases: {
+      define: {
+        requirement_definition: { status: "approved", file: "it_000015_product-requirement-document.md" },
+        prd_generation: { status: "completed", file: "it_000015_PRD.json" },
+      },
+      prototype: {
+        project_context: { status: "pending", file: ".agents/PROJECT_CONTEXT.md" },
+        test_plan: { status: "pending", file: null },
+        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-01-01T00:00:00.000Z",
+    updated_by: "test",
+  };
+}
+
+async function seedProject(flowGuardrail: "strict" | "relaxed"): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "nvst-force-"));
+  createdRoots.push(root);
+  await mkdir(join(root, ".agents", "flow"), { recursive: true });
+  await writeFile(
+    join(root, ".agents", "state.json"),
+    `${JSON.stringify(buildState(flowGuardrail), null, 2)}\n`,
+    "utf8",
+  );
+  await writeFile(join(root, ".agents", "PROJECT_CONTEXT.md"), "# Project Context\n", "utf8");
+  return root;
+}
+
+afterEach(async () => {
+  await Promise.all(createdRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("US-002 --force support", () => {
+  test("US-002-AC01: cli forwards --force to phase/status-validated command handlers", async () => {
+    const source = await readFile(join(import.meta.dir, "cli.ts"), "utf8");
+    expect(source).toContain("await runCreateProjectContext({ provider, mode, force })");
+    expect(source).toContain("await runDefineRequirement({ provider, force })");
+    expect(source).toContain("await runDefineRefactorPlan({ provider, force })");
+    expect(source).toContain("await runRefineRequirement({ provider, challenge, force })");
+    expect(source).toContain("await runRefineProjectContext({ provider, challenge, force })");
+    expect(source).toContain("await runRefineTestPlan({ provider, challenge, force })");
+    expect(source).toContain("await runRefineRefactorPlan({ provider, challenge, force })");
+    expect(source).toContain("await runApproveRequirement({ force })");
+    expect(source).toContain("await runApproveProjectContext({ force })");
+    expect(source).toContain("await runApproveTestPlan({ force })");
+    expect(source).toContain("await runApproveRefactorPlan({ force })");
+    expect(source).toContain("await runCreatePrototype({ provider, iterations, retryOnFail, stopOnCritical, force })");
+    expect(source).toContain("await runExecuteTestPlan({ provider, force })");
+    expect(source).toContain("await runExecuteRefactor({ provider, force })");
+  });
+
+  test("US-002-AC02/AC03: strict mode + --force warns and bypasses prompt", async () => {
+    const root = await seedProject("strict");
+    const previousCwd = process.cwd();
+    const messages: string[] = [];
+    const originalWrite = process.stderr.write.bind(process.stderr);
+    process.stderr.write = ((chunk: unknown) => {
+      messages.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write;
+
+    try {
+      process.chdir(root);
+      await runApproveProjectContext({ force: true });
+    } finally {
+      process.stderr.write = originalWrite;
+      process.chdir(previousCwd);
+    }
+
+    const state = JSON.parse(
+      await readFile(join(root, ".agents", "state.json"), "utf8"),
+    ) as State;
+    expect(state.phases.prototype.project_context.status).toBe("created");
+    expect(messages.join("")).toContain(
+      "Warning: Cannot approve project context from status 'pending'. Expected pending_approval.",
+    );
+    expect(messages.join("")).not.toContain("Proceed anyway? [y/N]");
+  });
+
+  test("US-002-AC03: relaxed mode + --force also bypasses prompt", async () => {
+    const root = await seedProject("relaxed");
+    const previousCwd = process.cwd();
+    const messages: string[] = [];
+    const originalWrite = process.stderr.write.bind(process.stderr);
+    process.stderr.write = ((chunk: unknown) => {
+      messages.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write;
+
+    try {
+      process.chdir(root);
+      await runApproveProjectContext({ force: true });
+    } finally {
+      process.stderr.write = originalWrite;
+      process.chdir(previousCwd);
+    }
+
+    expect(messages.join("")).toContain(
+      "Warning: Cannot approve project context from status 'pending'. Expected pending_approval.",
+    );
+    expect(messages.join("")).not.toContain("Proceed anyway? [y/N]");
+  });
+
+  test("US-002-AC04: commands without guardrail checks ignore --force when successful", async () => {
+    const root = await mkdtemp(join(tmpdir(), "nvst-force-cli-"));
+    createdRoots.push(root);
+    const cliPath = join(import.meta.dir, "cli.ts");
+    const proc = Bun.spawn(["bun", cliPath, "init", "--force"], {
+      cwd: root,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const exitCode = await proc.exited;
+    const stderrText = await new Response(proc.stderr).text();
+
+    expect(exitCode).toBe(0);
+    expect(stderrText).toBe("");
+  });
+});