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

package/src/guardrail.test.ts

@@ -0,0 +1,411 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import type { State } from "../scaffold/schemas/tmpl_state";
+import { assertGuardrail, GuardrailAbortError } from "./guardrail";
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+function makeState(flow_guardrail?: "strict" | "relaxed"): State {
+  return {
+    current_iteration: "000001",
+    current_phase: "define",
+    flow_guardrail,
+    phases: {
+      define: {
+        requirement_definition: { status: "pending", file: null },
+        prd_generation: { status: "pending", file: null },
+      },
+      prototype: {
+        project_context: { status: "pending", file: null },
+        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",
+  };
+}
+
+/** Captures stderr writes without calling the real process.stderr.write. */
+function makeStderrCapture(): { messages: string[]; fn: (msg: string) => void } {
+  const messages: string[] = [];
+  return {
+    messages,
+    fn: (msg: string) => messages.push(msg),
+  };
+}
+
+afterEach(() => {
+  // Reset exitCode after each test so tests don't bleed into each other
+  process.exitCode = 0;
+});
+
+// ---------------------------------------------------------------------------
+// No violation — no-op
+// ---------------------------------------------------------------------------
+
+describe("assertGuardrail – no violation", () => {
+  test("returns immediately without side-effects when violated is false", async () => {
+    const stderr = makeStderrCapture();
+    const state = makeState("relaxed");
+
+    await assertGuardrail(state, false, "should not appear", {
+      readLineFn: async () => null,
+      stderrWriteFn: stderr.fn,
+    });
+
+    expect(stderr.messages).toHaveLength(0);
+    expect(process.exitCode).toBeFalsy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Strict mode (default)
+// ---------------------------------------------------------------------------
+
+describe("assertGuardrail – strict mode", () => {
+  test("US-003-AC03: strict mode throws the same violation message and never prompts", async () => {
+    const state = makeState("strict");
+    let promptCalled = false;
+
+    await expect(
+      assertGuardrail(state, true, "current_phase is 'prototype' but 'define' is required.", {
+        readLineFn: async () => {
+          promptCalled = true;
+          return "y";
+        },
+        stderrWriteFn: () => {},
+      }),
+    ).rejects.toThrow("current_phase is 'prototype' but 'define' is required.");
+    expect(promptCalled).toBe(false);
+  });
+
+  test("throws Error (not GuardrailAbortError) in strict mode", async () => {
+    const state = makeState("strict");
+
+    await expect(
+      assertGuardrail(state, true, "some violation", {
+        stderrWriteFn: () => {},
+      }),
+    ).rejects.not.toBeInstanceOf(GuardrailAbortError);
+  });
+
+  test("US-003-AC04: absent flow_guardrail defaults to strict hard-error behavior", async () => {
+    const state = makeState(undefined);
+    let promptCalled = false;
+
+    await expect(
+      assertGuardrail(state, true, "strict default violation", {
+        readLineFn: async () => {
+          promptCalled = true;
+          return "y";
+        },
+        stderrWriteFn: () => {},
+      }),
+    ).rejects.toThrow("strict default violation");
+    expect(promptCalled).toBe(false);
+  });
+
+  test("does not print warning to stderr in strict mode without force", async () => {
+    const stderr = makeStderrCapture();
+    const state = makeState("strict");
+
+    await assertGuardrail(state, true, "msg", {
+      stderrWriteFn: stderr.fn,
+    }).catch(() => {});
+
+    expect(stderr.messages).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Relaxed mode — US-001-AC01, AC02, AC06
+// ---------------------------------------------------------------------------
+
+describe("assertGuardrail – relaxed mode, warning and prompt", () => {
+  // US-001-AC01: warning to stderr
+  test("US-001-AC01: prints 'Warning: <message>' to stderr first", async () => {
+    const stderr = makeStderrCapture();
+    const state = makeState("relaxed");
+
+    await assertGuardrail(
+      state,
+      true,
+      "current_phase is 'prototype' but 'define' is required.",
+      {
+        readLineFn: async () => "y",
+        stderrWriteFn: stderr.fn,
+      },
+    );
+
+    expect(stderr.messages[0]).toBe(
+      "Warning: current_phase is 'prototype' but 'define' is required.",
+    );
+  });
+
+  // US-001-AC02: confirmation prompt after warning
+  test("US-001-AC02: prints 'Proceed anyway? [y/N]' immediately after the warning", async () => {
+    const stderr = makeStderrCapture();
+    const state = makeState("relaxed");
+
+    await assertGuardrail(state, true, "violation msg", {
+      readLineFn: async () => "y",
+      stderrWriteFn: stderr.fn,
+    });
+
+    expect(stderr.messages[1]).toBe("Proceed anyway? [y/N]");
+  });
+
+  // US-001-AC06: output goes to stderr (tested implicitly via stderrWriteFn being the only channel)
+  test("US-001-AC06: warning and prompt are sent to stderrWriteFn (stderr), not stdout", async () => {
+    const stderr = makeStderrCapture();
+    const state = makeState("relaxed");
+
+    await assertGuardrail(state, true, "msg", {
+      readLineFn: async () => "y",
+      stderrWriteFn: stderr.fn,
+    });
+
+    // stderrWriteFn was called with warning and prompt
+    expect(stderr.messages).toContain("Warning: msg");
+    expect(stderr.messages).toContain("Proceed anyway? [y/N]");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Relaxed mode — confirmed (US-001-AC03)
+// ---------------------------------------------------------------------------
+
+describe("assertGuardrail – relaxed mode, confirmed", () => {
+  test("US-001-AC03: resolves without error when user enters 'y'", async () => {
+    const state = makeState("relaxed");
+
+    await expect(
+      assertGuardrail(state, true, "msg", {
+        readLineFn: async () => "y",
+        stderrWriteFn: () => {},
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  test("US-001-AC03: resolves without error when user enters 'Y'", async () => {
+    const state = makeState("relaxed");
+
+    await expect(
+      assertGuardrail(state, true, "msg", {
+        readLineFn: async () => "Y",
+        stderrWriteFn: () => {},
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  test("US-001-AC03: does not print 'Aborted.' when confirmed", async () => {
+    const stderr = makeStderrCapture();
+    const state = makeState("relaxed");
+
+    await assertGuardrail(state, true, "msg", {
+      readLineFn: async () => "y",
+      stderrWriteFn: stderr.fn,
+    });
+
+    expect(stderr.messages).not.toContain("Aborted.");
+  });
+
+  test("US-001-AC03: does not set process.exitCode when confirmed", async () => {
+    const state = makeState("relaxed");
+
+    await assertGuardrail(state, true, "msg", {
+      readLineFn: async () => "y",
+      stderrWriteFn: () => {},
+    });
+
+    expect(process.exitCode).toBeFalsy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Relaxed mode — aborted (US-001-AC04)
+// ---------------------------------------------------------------------------
+
+describe("assertGuardrail – relaxed mode, aborted", () => {
+  test("US-001-AC04: throws GuardrailAbortError when user enters 'n'", async () => {
+    const state = makeState("relaxed");
+
+    await expect(
+      assertGuardrail(state, true, "msg", {
+        readLineFn: async () => "n",
+        stderrWriteFn: () => {},
+      }),
+    ).rejects.toBeInstanceOf(GuardrailAbortError);
+  });
+
+  test("US-001-AC04: throws GuardrailAbortError when user presses Enter (empty input)", async () => {
+    const state = makeState("relaxed");
+
+    await expect(
+      assertGuardrail(state, true, "msg", {
+        readLineFn: async () => "",
+        stderrWriteFn: () => {},
+      }),
+    ).rejects.toBeInstanceOf(GuardrailAbortError);
+  });
+
+  test("US-001-AC04: throws GuardrailAbortError for any non-y/Y input", async () => {
+    const state = makeState("relaxed");
+
+    for (const input of ["no", "yes", "1", " ", "N"]) {
+      await expect(
+        assertGuardrail(state, true, "msg", {
+          readLineFn: async () => input,
+          stderrWriteFn: () => {},
+        }),
+      ).rejects.toBeInstanceOf(GuardrailAbortError);
+    }
+  });
+
+  test("US-001-AC04: prints 'Aborted.' to stderr when user does not confirm", async () => {
+    const stderr = makeStderrCapture();
+    const state = makeState("relaxed");
+
+    await assertGuardrail(state, true, "msg", {
+      readLineFn: async () => "n",
+      stderrWriteFn: stderr.fn,
+    }).catch(() => {});
+
+    expect(stderr.messages).toContain("Aborted.");
+  });
+
+  test("US-001-AC04: sets process.exitCode to 1 when user does not confirm", async () => {
+    const state = makeState("relaxed");
+
+    await assertGuardrail(state, true, "msg", {
+      readLineFn: async () => "n",
+      stderrWriteFn: () => {},
+    }).catch(() => {});
+
+    expect(process.exitCode).toBe(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Relaxed mode — stdin closed / not a TTY (US-001-AC05)
+// ---------------------------------------------------------------------------
+
+describe("assertGuardrail – relaxed mode, stdin closed", () => {
+  test("US-001-AC05: throws GuardrailAbortError when readLineFn returns null (stdin closed)", async () => {
+    const state = makeState("relaxed");
+
+    await expect(
+      assertGuardrail(state, true, "msg", {
+        readLineFn: async () => null,
+        stderrWriteFn: () => {},
+      }),
+    ).rejects.toBeInstanceOf(GuardrailAbortError);
+  });
+
+  test("US-001-AC05: prints 'Aborted.' to stderr when stdin is closed", async () => {
+    const stderr = makeStderrCapture();
+    const state = makeState("relaxed");
+
+    await assertGuardrail(state, true, "msg", {
+      readLineFn: async () => null,
+      stderrWriteFn: stderr.fn,
+    }).catch(() => {});
+
+    expect(stderr.messages).toContain("Aborted.");
+  });
+
+  test("US-001-AC05: sets process.exitCode to 1 when stdin is closed", async () => {
+    const state = makeState("relaxed");
+
+    await assertGuardrail(state, true, "msg", {
+      readLineFn: async () => null,
+      stderrWriteFn: () => {},
+    }).catch(() => {});
+
+    expect(process.exitCode).toBe(1);
+  });
+
+  test("US-001-AC05: treats readLineFn throwing as closed stdin (abort)", async () => {
+    const state = makeState("relaxed");
+
+    await expect(
+      assertGuardrail(state, true, "msg", {
+        readLineFn: async () => {
+          throw new Error("stdin read error");
+        },
+        stderrWriteFn: () => {},
+      }),
+    ).rejects.toBeInstanceOf(GuardrailAbortError);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// force option — skips prompt (partial US-002 surface, verified by AC05 wording)
+// ---------------------------------------------------------------------------
+
+describe("assertGuardrail – force option", () => {
+  test("with force=true and relaxed: prints warning but does not prompt or abort", async () => {
+    const stderr = makeStderrCapture();
+    const state = makeState("relaxed");
+
+    await assertGuardrail(state, true, "forced violation", {
+      force: true,
+      readLineFn: async () => {
+        throw new Error("should not be called");
+      },
+      stderrWriteFn: stderr.fn,
+    });
+
+    expect(stderr.messages).toContain("Warning: forced violation");
+    expect(stderr.messages).not.toContain("Proceed anyway? [y/N]");
+    expect(stderr.messages).not.toContain("Aborted.");
+    expect(process.exitCode).toBeFalsy();
+  });
+
+  test("with force=true and strict: prints warning and continues without throwing", async () => {
+    const stderr = makeStderrCapture();
+    const state = makeState("strict");
+
+    await expect(
+      assertGuardrail(state, true, "forced strict violation", {
+        force: true,
+        stderrWriteFn: stderr.fn,
+      }),
+    ).resolves.toBeUndefined();
+
+    expect(stderr.messages).toContain("Warning: forced strict violation");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// GuardrailAbortError identity
+// ---------------------------------------------------------------------------
+
+describe("GuardrailAbortError", () => {
+  test("is an instance of Error", () => {
+    const err = new GuardrailAbortError();
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  test("has message 'Aborted.'", () => {
+    const err = new GuardrailAbortError();
+    expect(err.message).toBe("Aborted.");
+  });
+
+  test("has name 'GuardrailAbortError'", () => {
+    const err = new GuardrailAbortError();
+    expect(err.name).toBe("GuardrailAbortError");
+  });
+});

package/src/guardrail.ts

@@ -0,0 +1,82 @@
+import type { State } from "../scaffold/schemas/tmpl_state";
+
+import { defaultReadLine } from "./readline";
+
+export class GuardrailAbortError extends Error {
+  constructor() {
+    super("Aborted.");
+    this.name = "GuardrailAbortError";
+  }
+}
+
+export type ReadLineFn = () => Promise<string | null>;
+export type StderrWriteFn = (message: string) => void;
+
+export interface GuardrailOptions {
+  force?: boolean;
+  readLineFn?: ReadLineFn;
+  stderrWriteFn?: StderrWriteFn;
+}
+
+function defaultStderrWrite(message: string): void {
+  process.stderr.write(`${message}\n`);
+}
+
+/**
+ * Enforces the flow guardrail for phase/status violations.
+ *
+ * - strict (default): throws Error with `message` when `violated` is true and `force` is false
+ * - relaxed: prints warning + confirmation prompt to stderr; aborts (exitCode=1) unless user confirms
+ * - force: prints warning but skips the confirmation prompt regardless of guardrail mode
+ *
+ * When not violated, returns immediately without side effects.
+ */
+export async function assertGuardrail(
+  state: State,
+  violated: boolean,
+  message: string,
+  opts: GuardrailOptions = {},
+): Promise<void> {
+  if (!violated) {
+    return;
+  }
+
+  const guardrail = state.flow_guardrail ?? "strict";
+  const {
+    force = false,
+    readLineFn = defaultReadLine,
+    stderrWriteFn = defaultStderrWrite,
+  } = opts;
+
+  if (guardrail === "strict" && !force) {
+    throw new Error(message);
+  }
+
+  // Print warning to stderr (AC01, AC06)
+  stderrWriteFn(`Warning: ${message}`);
+
+  if (force) {
+    // With --force: warn but skip the confirmation prompt (US-002)
+    return;
+  }
+
+  // Relaxed mode without --force: prompt for confirmation (AC02, AC06)
+  stderrWriteFn("Proceed anyway? [y/N]");
+
+  let line: string | null;
+  try {
+    line = await readLineFn();
+  } catch {
+    line = null;
+  }
+
+  // Only "y" or "Y" is treated as confirmation (AC03, AC04, AC05)
+  if (line !== null && (line.trim() === "y" || line.trim() === "Y")) {
+    return;
+  }
+
+  // User aborted or stdin was closed (AC04, AC05)
+  stderrWriteFn("Aborted.");
+  process.exitCode = 1;
+  throw new GuardrailAbortError();
+}

package/src/install.test.ts

@@ -5,9 +5,11 @@ import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 
 const PROJECT_ROOT = join(import.meta.dir, "..");
-const PACKAGE_VERSION = "0.1.0";
+const PACKAGE_VERSION =
+  (await Bun.file(join(PROJECT_ROOT, "package.json")).json()) as { version?: string };
+const PACKAGE_VERSION_STR = PACKAGE_VERSION?.version ?? "0.1.0";
 // Scoped packages: npm pack produces scope-package-version.tgz
-const TARBALL_BASENAME = `quinteroac-agents-coding-toolkit-${PACKAGE_VERSION}.tgz`;
+const TARBALL_BASENAME = `quinteroac-agents-coding-toolkit-${PACKAGE_VERSION_STR}.tgz`;
 const TARBALL_PATH = join(PROJECT_ROOT, TARBALL_BASENAME);
 
 const tempProjectRoots: string[] = [];
@@ -70,7 +72,7 @@ describe("install package", () => {
       encoding: "utf-8",
     });
     expect(result.status).toBe(0);
-    expect(result.stdout?.trim()).toBe(PACKAGE_VERSION);
+    expect(result.stdout?.trim()).toBe(PACKAGE_VERSION_STR);
   });
 
   test("US-002-AC01: user can install the package from the local file system or registry", async () => {
@@ -86,7 +88,7 @@ describe("install package", () => {
 
     const pkgJsonPath = join(nodeModules, "package.json");
     const pkg = (await Bun.file(pkgJsonPath).json()) as { version?: string; bin?: Record<string, string> };
-    expect(pkg.version).toBe(PACKAGE_VERSION);
+    expect(pkg.version).toBe(PACKAGE_VERSION_STR);
     expect(pkg.bin).toBeDefined();
     expect(pkg.bin?.nvst).toBeDefined();
   });
@@ -119,6 +121,6 @@ describe("install package", () => {
 
     const { exitCode, stdout } = runNvst(tempRoot, ["--version"]);
     expect(exitCode).toBe(0);
-    expect(stdout.trim()).toBe(PACKAGE_VERSION);
+    expect(stdout.trim()).toBe(PACKAGE_VERSION_STR);
   });
 });

package/src/pack.test.ts

@@ -4,7 +4,8 @@ import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 
 const PROJECT_ROOT = join(import.meta.dir, "..");
-const PACKAGE_VERSION = "0.1.0";
+const pkg = (await Bun.file(join(PROJECT_ROOT, "package.json")).json()) as { version?: string };
+const PACKAGE_VERSION = pkg?.version ?? "0.1.0";
 // Scoped packages: npm pack produces scope-package-version.tgz
 const TARBALL_BASENAME = `quinteroac-agents-coding-toolkit-${PACKAGE_VERSION}.tgz`;
 

package/src/progress-utils.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared utilities for ID matching and progress entry state updates.
+ *
+ * Centralises logic used across create-prototype, execute-test-plan, and
+ * execute-refactor so that matching rules and timestamp semantics stay
+ * consistent.
+ */
+
+export function sortedValues(values: string[]): string[] {
+  return [...values].sort((a, b) => a.localeCompare(b));
+}
+
+export function idsMatchExactly(left: string[], right: string[]): boolean {
+  if (left.length !== right.length) {
+    return false;
+  }
+
+  for (let i = 0; i < left.length; i += 1) {
+    if (left[i] !== right[i]) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export function applyStatusUpdate<S extends string>(
+  entry: { status: S; updated_at: string },
+  status: S,
+  timestamp: string,
+): void {
+  entry.status = status;
+  entry.updated_at = timestamp;
+}

package/src/readline.ts

@@ -0,0 +1,23 @@
+import { createInterface } from "node:readline";
+
+export async function defaultReadLine(): Promise<string | null> {
+  return new Promise((resolve) => {
+    const rl = createInterface({
+      input: process.stdin,
+      terminal: false,
+    });
+
+    let settled = false;
+
+    const settle = (value: string | null): void => {
+      if (!settled) {
+        settled = true;
+        rl.close();
+        resolve(value);
+      }
+    };
+
+    rl.once("line", settle);
+    rl.once("close", () => settle(null));
+  });
+}

package/src/write-json-artifact.ts

@@ -0,0 +1,33 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { ZodSchema } from "zod";
+
+export type WriteJsonArtifactFn = (
+  absolutePath: string,
+  schema: ZodSchema,
+  data: unknown,
+) => Promise<void>;
+
+/**
+ * Schema-validated JSON artifact writer.
+ *
+ * Validates `data` against `schema` then writes pretty-printed JSON to
+ * `absolutePath`, creating parent directories as needed.  This is the
+ * in-process equivalent of `nvst write-json` for commands that need to
+ * write iteration-scoped `.agents/flow/` artifacts without spawning a
+ * subprocess.
+ */
+export async function writeJsonArtifact(
+  absolutePath: string,
+  schema: ZodSchema,
+  data: unknown,
+): Promise<void> {
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    throw new Error(
+      `writeJsonArtifact: schema validation failed for ${absolutePath}.\n${JSON.stringify(result.error.format(), null, 2)}`,
+    );
+  }
+  await mkdir(dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, `${JSON.stringify(result.data, null, 2)}\n`, "utf-8");
+}

package/scaffold/.agents/flow/tmpl_README.md

@@ -1,7 +0,0 @@
-# Flow directory (scaffold)
-
-<!-- TODO: Complete. All content in English. -->
-
-- **What lives here:** TBD — Iteration artifacts `it_<6 digits>_*` (e.g. product-requirement-document.md, PRD.json, progress.json, test-plan.md, evaluation-report.md, refactor_plan.md).
-- **Naming:** Prefix `it_` + 6-digit iteration number (e.g. `it_000001_`, `it_000042_`). No spaces.
-- **What gets archived:** When starting the next iteration, current iteration files move to `.agents/flow/archived/<iteration>/` (e.g. `archived/000001/`).

package/scaffold/.agents/flow/tmpl_iteration_close_checklist.example.md

@@ -1,11 +0,0 @@
-# Iteration close checklist (scaffold)
-
-<!-- TODO: Complete. All content in English. Use when closing an iteration (before running start next iteration / archive). -->
-
-- [ ] **prototype_approved** — Prototype has been approved (`phases.prototype.prototype_approved === true`).
-- [ ] **Full tests** — Tests for all use cases of the iteration (original + refactor/regression) have been run and pass (or documented exceptions).
-- [ ] **PROJECT_CONTEXT.md** — Updated with newly implemented features; summary mechanism applied so file does not exceed 250 lines.
-- [ ] **CHANGELOG.md** — Iteration summary recorded (requirements, refactorings, fixes).
-- [ ] **Archive** — Ready to run “start iteration” (move `it_<iteration>_*` to `.agents/flow/archived/<iteration>/`, update state.history, reset phase for next iteration).
-
-TBD — Add any project-specific items.

package/schemas/test-plan.ts

@@ -1,20 +0,0 @@
-import { z } from "zod";
-
-const TestStatusSchema = z.enum(["pending", "passed", "failed", "skipped"]);
-
-const TestItemSchema = z.object({
-  id: z.string(),
-  description: z.string(),
-  status: TestStatusSchema,
-  correlatedRequirements: z.array(z.string()),
-});
-
-export const TestPlanSchema = z.object({
-  overallStatus: TestStatusSchema,
-  scope: z.array(z.string()),
-  environmentData: z.array(z.string()),
-  automatedTests: z.array(TestItemSchema),
-  exploratoryManualTests: z.array(TestItemSchema),
-});
-
-export type TestPlan = z.infer<typeof TestPlanSchema>;