@quinteroac/agents-coding-toolkit 0.1.0-preview

package/src/commands/start-iteration.ts

@@ -0,0 +1,101 @@
+import { mkdir, readdir, rename } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { State } from "../../scaffold/schemas/tmpl_state";
+import { exists, readState, writeState, STATE_REL_PATH, FLOW_REL_DIR } from "../state";
+
+const ARCHIVED_DIR = join(FLOW_REL_DIR, "archived");
+
+function createInitialState(nowIso: string): State {
+  return {
+    current_iteration: "000001",
+    current_phase: "define",
+    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: nowIso,
+    history: [],
+  };
+}
+
+function nextIteration(iteration: string): string {
+  return String(Number.parseInt(iteration, 10) + 1).padStart(6, "0");
+}
+
+export async function runStartIteration(): Promise<void> {
+  const projectRoot = process.cwd();
+  const statePath = join(projectRoot, STATE_REL_PATH);
+  const flowDir = join(projectRoot, FLOW_REL_DIR);
+  const nowIso = new Date().toISOString();
+
+  await mkdir(flowDir, { recursive: true });
+
+  if (!(await exists(statePath))) {
+    await writeState(projectRoot, createInitialState(nowIso));
+    console.log("Iteration 000001 started (phase: define)");
+    return;
+  }
+
+  const parsedState = await readState(projectRoot);
+
+  const currentIteration = parsedState.current_iteration;
+  const flowEntries = await readdir(flowDir, { withFileTypes: true });
+  const filePrefix = `it_${currentIteration}_`;
+  const filesToArchive = flowEntries
+    .filter((entry) => entry.isFile() && entry.name.startsWith(filePrefix))
+    .map((entry) => entry.name);
+
+  const iterationArchiveDir = join(ARCHIVED_DIR, currentIteration);
+  const iterationArchiveAbsDir = join(projectRoot, iterationArchiveDir);
+  await mkdir(iterationArchiveAbsDir, { recursive: true });
+
+  for (const fileName of filesToArchive) {
+    await rename(join(flowDir, fileName), join(iterationArchiveAbsDir, fileName));
+  }
+
+  const updatedHistory = [
+    ...(parsedState.history ?? []),
+    {
+      iteration: currentIteration,
+      archived_at: nowIso,
+      archived_path: `.agents/flow/archived/${currentIteration}`,
+    },
+  ];
+
+  const nextState = createInitialState(nowIso);
+  nextState.current_iteration = nextIteration(currentIteration);
+  nextState.history = updatedHistory;
+
+  // Preserve project_context when already created (immutable across iterations)
+  const prevProjectContext = parsedState.phases?.prototype?.project_context;
+  if (prevProjectContext?.status === "created" && prevProjectContext?.file) {
+    nextState.phases.prototype.project_context = {
+      status: "created",
+      file: prevProjectContext.file,
+    };
+  }
+
+  await writeState(projectRoot, nextState);
+
+  console.log(
+    `Archived ${filesToArchive.length} file(s) to .agents/flow/archived/${currentIteration}`,
+  );
+  console.log(`Iteration ${nextState.current_iteration} started (phase: define)`);
+}

package/src/commands/write-json.ts

@@ -0,0 +1,136 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+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 { TestPlanSchema } from "../../scaffold/schemas/tmpl_test-plan";
+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,
+};
+
+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 };
+}
+
+// ---------------------------------------------------------------------------
+// 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");
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+export interface WriteJsonOptions {
+    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;
+    }
+
+    // --- 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}`);
+}

package/src/install.test.ts

@@ -0,0 +1,124 @@
+import { afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const PROJECT_ROOT = join(import.meta.dir, "..");
+const PACKAGE_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_PATH = join(PROJECT_ROOT, TARBALL_BASENAME);
+
+const tempProjectRoots: string[] = [];
+
+async function createTempProject(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "nvst-install-test-"));
+  tempProjectRoots.push(root);
+  await writeFile(
+    join(root, "package.json"),
+    JSON.stringify({ name: "test-consumer", version: "1.0.0", private: true }),
+    "utf-8",
+  );
+  return root;
+}
+
+function bunAdd(cwd: string, spec: string): { exitCode: number | null; stdout: string; stderr: string } {
+  const result = spawnSync("bun", ["add", spec], {
+    cwd,
+    encoding: "utf-8",
+  });
+  return {
+    exitCode: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  };
+}
+
+function runNvst(cwd: string, args: string[]): { exitCode: number | null; stdout: string; stderr: string } {
+  const result = spawnSync("bunx", ["--bun", "nvst", ...args], {
+    cwd,
+    encoding: "utf-8",
+  });
+  return {
+    exitCode: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  };
+}
+
+beforeAll(() => {
+  const packResult = spawnSync("bun", ["run", "package"], {
+    cwd: PROJECT_ROOT,
+    encoding: "utf-8",
+  });
+  if (packResult.status !== 0) {
+    throw new Error(`Pre-test package failed: ${packResult.stderr}`);
+  }
+});
+
+afterEach(async () => {
+  await Promise.all(
+    tempProjectRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })),
+  );
+});
+
+describe("install package", () => {
+  test("US-002-AC03: CLI --version outputs packaged version (run from source)", () => {
+    const result = spawnSync("bun", [join(PROJECT_ROOT, "src", "cli.ts"), "--version"], {
+      cwd: PROJECT_ROOT,
+      encoding: "utf-8",
+    });
+    expect(result.status).toBe(0);
+    expect(result.stdout?.trim()).toBe(PACKAGE_VERSION);
+  });
+
+  test("US-002-AC01: user can install the package from the local file system or registry", async () => {
+    const tempRoot = await createTempProject();
+
+    const { exitCode, stderr } = bunAdd(tempRoot, PROJECT_ROOT);
+    expect(exitCode).toBe(0);
+    expect(stderr).not.toContain("error");
+
+    const nodeModules = join(tempRoot, "node_modules", "@quinteroac", "agents-coding-toolkit");
+    const entries = await readdir(join(tempRoot, "node_modules"));
+    expect(entries).toContain("@quinteroac");
+
+    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.bin).toBeDefined();
+    expect(pkg.bin?.nvst).toBeDefined();
+  });
+
+  test("US-002-AC01: user can install from packed tarball", async () => {
+    const tempRoot = await createTempProject();
+
+    const { exitCode, stderr } = bunAdd(tempRoot, TARBALL_PATH);
+    expect(exitCode).toBe(0);
+    expect(stderr).not.toContain("error");
+
+    const entries = await readdir(join(tempRoot, "node_modules"));
+    expect(entries).toContain("@quinteroac");
+  });
+
+  test("US-002-AC02: after installation, the nvst command is available in the shell", async () => {
+    const tempRoot = await createTempProject();
+    bunAdd(tempRoot, PROJECT_ROOT);
+
+    const { exitCode, stdout } = runNvst(tempRoot, ["--help"]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("Usage: nvst <command> [options]");
+    expect(stdout).toContain("init");
+    expect(stdout).toContain("destroy");
+  });
+
+  test("US-002-AC03: installed version matches the packaged version", async () => {
+    const tempRoot = await createTempProject();
+    bunAdd(tempRoot, PROJECT_ROOT);
+
+    const { exitCode, stdout } = runNvst(tempRoot, ["--version"]);
+    expect(exitCode).toBe(0);
+    expect(stdout.trim()).toBe(PACKAGE_VERSION);
+  });
+});

package/src/pack.test.ts

@@ -0,0 +1,103 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const PROJECT_ROOT = join(import.meta.dir, "..");
+const PACKAGE_VERSION = "0.1.0";
+// Scoped packages: npm pack produces scope-package-version.tgz
+const TARBALL_BASENAME = `quinteroac-agents-coding-toolkit-${PACKAGE_VERSION}.tgz`;
+
+function runPackageScript(): { exitCode: number | null; stdout: string; stderr: string } {
+  const result = spawnSync("bun", ["run", "package"], {
+    cwd: PROJECT_ROOT,
+    encoding: "utf-8",
+  });
+  return {
+    exitCode: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  };
+}
+
+function listTarballContents(tarballPath: string): string[] {
+  const result = spawnSync("tar", ["-tf", tarballPath], {
+    encoding: "utf-8",
+  });
+  if (result.status !== 0) {
+    throw new Error(`tar -tf failed: ${result.stderr}`);
+  }
+  return (result.stdout ?? "").trim().split("\n").filter(Boolean);
+}
+
+function extractFileFromTarball(tarballPath: string, memberPath: string): string {
+  const result = spawnSync("tar", ["-xOf", tarballPath, memberPath], {
+    encoding: "utf-8",
+  });
+  if (result.status !== 0) {
+    throw new Error(`tar -xOf failed: ${result.stderr}`);
+  }
+  return result.stdout ?? "";
+}
+
+afterEach(async () => {
+  const tarballPath = join(PROJECT_ROOT, TARBALL_BASENAME);
+  try {
+    await rm(tarballPath, { force: true });
+  } catch {
+    // ignore if file does not exist
+  }
+});
+
+describe("package command", () => {
+  test("US-001-AC01: running package command produces a valid .tgz file", async () => {
+    const { exitCode } = runPackageScript();
+    expect(exitCode).toBe(0);
+
+    const tarballPath = join(PROJECT_ROOT, TARBALL_BASENAME);
+    const entries = await readdir(PROJECT_ROOT);
+    const hasTgz = entries.some((e) => e === TARBALL_BASENAME);
+    expect(hasTgz).toBe(true);
+
+    const stat = await Bun.file(tarballPath).exists();
+    expect(stat).toBe(true);
+
+    const contents = listTarballContents(tarballPath);
+    expect(contents.length).toBeGreaterThan(0);
+    expect(contents.some((p) => p.includes("package.json"))).toBe(true);
+  });
+
+  test("US-001-AC02: package includes all necessary dependencies and source files", async () => {
+    runPackageScript();
+
+    const tarballPath = join(PROJECT_ROOT, TARBALL_BASENAME);
+    const contents = listTarballContents(tarballPath);
+
+    const packageJsonPath = contents.find((p) => p.endsWith("package.json"));
+    expect(packageJsonPath).toBeDefined();
+
+    const baseDir = packageJsonPath!.replace(/\/package\.json$/, "");
+    const requiredPaths = [
+      `${baseDir}/package.json`,
+      `${baseDir}/src/cli.ts`,
+      `${baseDir}/src/state.ts`,
+      `${baseDir}/scaffold`,
+      `${baseDir}/schemas`,
+    ];
+    for (const required of requiredPaths) {
+      const found = contents.some((p) => p === required || p.startsWith(required + "/"));
+      expect(found).toBe(true);
+    }
+
+    const pkgContent = extractFileFromTarball(tarballPath, "package/package.json");
+    const pkg = JSON.parse(pkgContent);
+    expect(pkg.dependencies).toBeDefined();
+    expect(pkg.dependencies.zod).toBeDefined();
+  });
+
+  test("US-001-AC03: build process completes without errors", () => {
+    const { exitCode, stderr } = runPackageScript();
+    expect(exitCode).toBe(0);
+    expect(stderr).not.toMatch(/\b(Error|ERR!)\b/);
+  });
+});

package/src/state.test.ts

@@ -0,0 +1,66 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { ZodError } from "zod";
+
+import { readState, STATE_REL_PATH } from "./state";
+
+async function createTempProjectRoot(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "nvst-state-test-"));
+}
+
+async function writeStateFile(projectRoot: string, content: string): Promise<void> {
+  const statePath = join(projectRoot, STATE_REL_PATH);
+  await mkdir(join(projectRoot, ".agents"), { recursive: true });
+  await writeFile(statePath, content, "utf8");
+}
+
+const createdProjectRoots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    createdProjectRoots.splice(0).map((projectRoot) => rm(projectRoot, { recursive: true, force: true })),
+  );
+});
+
+describe("readState", () => {
+  test("uses StateSchema.safeParse in source", async () => {
+    const source = await readFile(join(process.cwd(), "src", "state.ts"), "utf8");
+    expect(source).toContain("StateSchema.safeParse");
+    expect(source).not.toContain("StateSchema.parse(");
+  });
+
+  test("returns schema validation failure with safeParse error as cause", async () => {
+    const projectRoot = await createTempProjectRoot();
+    createdProjectRoots.push(projectRoot);
+
+    await writeStateFile(projectRoot, JSON.stringify({ current_iteration: "000001" }));
+
+    await expect(readState(projectRoot)).rejects.toMatchObject({
+      message: expect.stringContaining("failed schema validation"),
+      cause: expect.any(ZodError),
+    });
+  });
+
+  test("surfaces descriptive ENOENT message when state file is missing", async () => {
+    const projectRoot = await createTempProjectRoot();
+    createdProjectRoots.push(projectRoot);
+
+    await expect(readState(projectRoot)).rejects.toThrow(
+      `State file not found at ${join(projectRoot, STATE_REL_PATH)}.`,
+    );
+  });
+
+  test("surfaces descriptive malformed JSON message", async () => {
+    const projectRoot = await createTempProjectRoot();
+    createdProjectRoots.push(projectRoot);
+
+    await writeStateFile(projectRoot, "{");
+
+    await expect(readState(projectRoot)).rejects.toThrow(
+      `Malformed JSON in state file at ${join(projectRoot, STATE_REL_PATH)}.`,
+    );
+  });
+});

package/src/state.ts

@@ -0,0 +1,52 @@
+import { access, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { StateSchema, type State } from "../scaffold/schemas/tmpl_state";
+
+export const STATE_REL_PATH = join(".agents", "state.json");
+export const FLOW_REL_DIR = join(".agents", "flow");
+
+export async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readState(projectRoot: string): Promise<State> {
+  const statePath = join(projectRoot, STATE_REL_PATH);
+  try {
+    const raw = await readFile(statePath, "utf8");
+    let json: unknown;
+
+    try {
+      json = JSON.parse(raw);
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        throw new Error(`Malformed JSON in state file at ${statePath}.`, { cause: error });
+      }
+      throw error;
+    }
+
+    const parsed = StateSchema.safeParse(json);
+    if (!parsed.success) {
+      throw new Error(`State file at ${statePath} failed schema validation.`, {
+        cause: parsed.error,
+      });
+    }
+
+    return parsed.data;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`State file not found at ${statePath}.`, { cause: error });
+    }
+    throw error;
+  }
+}
+
+export async function writeState(projectRoot: string, state: State): Promise<void> {
+  const statePath = join(projectRoot, STATE_REL_PATH);
+  await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext"],
+    "types": ["node", "bun-types"],
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "."
+  },
+  "include": ["scaffold/schemas/**/*.ts", "src/**/*.ts"],
+  "exclude": ["scaffold/schemas/node-shims.d.ts"]
+}