@nathapp/nax 0.50.3 → 0.51.0

package/src/prd/index.ts

@@ -1,220 +0,0 @@
-/**
- * PRD Operations
- */
-
-import { existsSync, statSync } from "node:fs";
-import type { FailureCategory } from "../tdd/types";
-import { saveJsonFile } from "../utils/json-file";
-import type { PRD, UserStory } from "./types";
-
-export type {
-  PRD,
-  UserStory,
-  StoryRouting,
-  StoryStatus,
-  EscalationAttempt,
-  StructuredFailure,
-  TestFailureContext,
-  VerificationStage,
-} from "./types";
-export { isStalled, markStoryAsBlocked, generateHumanHaltSummary, getContextFiles, getExpectedFiles } from "./types";
-export type { FailureCategory } from "../tdd/types";
-
-/** Maximum PRD file size (5MB) - reject larger PRDs to prevent memory issues */
-export const PRD_MAX_FILE_SIZE = 5 * 1024 * 1024;
-
-/** Load PRD from file */
-export async function loadPRD(path: string): Promise<PRD> {
-  if (!existsSync(path)) {
-    throw new Error(`PRD file not found: ${path}`);
-  }
-
-  // Check file size to prevent loading oversized PRDs
-  const stats = statSync(path);
-  if (stats.size > PRD_MAX_FILE_SIZE) {
-    const sizeMB = (stats.size / (1024 * 1024)).toFixed(2);
-    const limitMB = (PRD_MAX_FILE_SIZE / (1024 * 1024)).toFixed(2);
-    throw new Error(
-      `PRD file is too large (${sizeMB} MB exceeds ${limitMB} MB limit). Split this feature into smaller features or reduce story count.`,
-    );
-  }
-
-  const prd: PRD = await Bun.file(path).json();
-
-  // BUG-21: Normalize story fields to prevent null/undefined arithmetic issues
-  // BUG-004: Auto-default optional PRD fields in-memory (tags, status, acceptanceCriteria, storyPoints)
-  for (const story of prd.userStories) {
-    story.attempts = story.attempts ?? 0;
-    story.priorErrors = story.priorErrors ?? [];
-    story.priorFailures = story.priorFailures ?? [];
-    story.escalations = story.escalations ?? [];
-    story.dependencies = story.dependencies ?? [];
-    story.tags = story.tags ?? [];
-    // Normalize aliases: "open" → "pending", "done" → "passed"
-    const rawStatus = story.status as string;
-    if (rawStatus === "open") story.status = "pending";
-    if (rawStatus === "done") story.status = "passed";
-    story.status = story.status ?? "pending";
-    story.acceptanceCriteria = story.acceptanceCriteria ?? [];
-    story.storyPoints = story.storyPoints ?? 1;
-  }
-
-  return prd;
-}
-
-/** Save PRD to file */
-export async function savePRD(prd: PRD, path: string): Promise<void> {
-  prd.updatedAt = new Date().toISOString();
-  await saveJsonFile(path, prd, "prd");
-}
-
-/**
- * Get the next story to work on.
- *
- * Priority 1 (retry): If `currentStoryId` is provided and that story has
- * `status === "failed"` with `attempts <= maxRetries`, return it immediately
- * so the executor retries the same story before moving on.
- *
- * Priority 2 (normal): First pending story whose dependencies are satisfied.
- *
- * @param prd - PRD containing all stories
- * @param currentStoryId - ID of the story just executed (optional)
- * @param maxRetries - Max retry attempts per story before giving up (optional)
- */
-export function getNextStory(prd: PRD, currentStoryId?: string | null, maxRetries?: number): UserStory | null {
-  // Priority 1: Retry current story if failed but has attempts remaining
-  if (currentStoryId != null && maxRetries != null && maxRetries > 0) {
-    const currentStory = prd.userStories.find((s) => s.id === currentStoryId);
-    if (currentStory && currentStory.status === "failed" && (currentStory.attempts ?? 0) <= maxRetries) {
-      return currentStory;
-    }
-    // BUG-029: After tier escalation, story is set to "pending" (not "failed").
-    // Prioritize current story if it was escalated (pending + has prior attempts).
-    if (currentStory && currentStory.status === "pending" && (currentStory.attempts ?? 0) > 0) {
-      return currentStory;
-    }
-  }
-
-  const completedIds = new Set(
-    prd.userStories.filter((s) => s.passes || s.status === "passed" || s.status === "skipped").map((s) => s.id),
-  );
-
-  return (
-    prd.userStories.find(
-      (s) =>
-        !s.passes &&
-        s.status !== "passed" &&
-        s.status !== "skipped" &&
-        s.status !== "blocked" &&
-        s.status !== "failed" &&
-        s.status !== "paused" &&
-        s.status !== "decomposed" &&
-        s.dependencies.every((dep) => completedIds.has(dep)),
-    ) ?? null
-  );
-}
-
-/**
- * Check if all stories are complete (passed or skipped).
- *
- * @design Does NOT account for blocked/failed stories — a PRD with blocked stories
- * is NOT complete. Use `isStalled()` separately to detect when forward progress
- * is impossible (all remaining stories blocked or depend on blocked).
- */
-export function isComplete(prd: PRD): boolean {
-  return prd.userStories.every((s) => s.passes || s.status === "passed" || s.status === "skipped");
-}
-
-/** Count stories by status */
-export function countStories(prd: PRD): {
-  total: number;
-  passed: number;
-  failed: number;
-  pending: number;
-  skipped: number;
-  blocked: number;
-  paused: number;
-  decomposed: number;
-} {
-  return {
-    total: prd.userStories.length,
-    passed: prd.userStories.filter((s) => s.passes || s.status === "passed").length,
-    failed: prd.userStories.filter((s) => s.status === "failed" || s.status === "regression-failed").length,
-    pending: prd.userStories.filter(
-      (s) =>
-        !s.passes &&
-        s.status !== "passed" &&
-        s.status !== "failed" &&
-        s.status !== "skipped" &&
-        s.status !== "blocked" &&
-        s.status !== "paused" &&
-        s.status !== "regression-failed" &&
-        s.status !== "decomposed",
-    ).length,
-    skipped: prd.userStories.filter((s) => s.status === "skipped").length,
-    blocked: prd.userStories.filter((s) => s.status === "blocked").length,
-    paused: prd.userStories.filter((s) => s.status === "paused").length,
-    decomposed: prd.userStories.filter((s) => s.status === "decomposed").length,
-  };
-}
-
-/** Mark a story as passed */
-export function markStoryPassed(prd: PRD, storyId: string): void {
-  const story = prd.userStories.find((s) => s.id === storyId);
-  if (story) {
-    story.passes = true;
-    story.status = "passed";
-  }
-
-  // If this was a sub-story, check if all siblings have passed — if so, promote the
-  // decomposed parent to 'passed' so that stories depending on it can unblock (DEP-001).
-  const parentId = story?.parentStoryId;
-  if (parentId) {
-    const parent = prd.userStories.find((s) => s.id === parentId);
-    if (parent && parent.status === "decomposed") {
-      const siblings = prd.userStories.filter((s) => s.parentStoryId === parentId);
-      const allSiblingsPassed = siblings.length > 0 && siblings.every((s) => s.passes || s.status === "passed");
-      if (allSiblingsPassed) {
-        parent.passes = true;
-        parent.status = "passed";
-      }
-    }
-  }
-}
-
-/** Mark a story as failed */
-export function markStoryFailed(
-  prd: PRD,
-  storyId: string,
-  failureCategory?: FailureCategory,
-  failureStage?: string,
-): void {
-  const story = prd.userStories.find((s) => s.id === storyId);
-  if (story) {
-    story.status = "failed";
-    story.attempts += 1;
-    if (failureCategory !== undefined) {
-      story.failureCategory = failureCategory;
-    }
-    if (failureStage !== undefined) {
-      story.failureStage = failureStage;
-    }
-  }
-}
-
-/** Mark a story as skipped */
-export function markStorySkipped(prd: PRD, storyId: string): void {
-  const story = prd.userStories.find((s) => s.id === storyId);
-  if (story) {
-    story.status = "skipped";
-  }
-}
-
-/** Mark a story as paused */
-export function markStoryPaused(prd: PRD, storyId: string): void {
-  const story = prd.userStories.find((s) => s.id === storyId);
-  if (story) {
-    story.status = "paused";
-    story.attempts = (story.attempts ?? 0) + 1;
-  }
-}

package/src/prd/schema.ts

@@ -1,268 +0,0 @@
-/**
- * PRD JSON Validation and Schema Enforcement
- *
- * Validates and normalizes LLM-generated PRD JSON output before writing to disk.
- */
-
-import type { Complexity, TestStrategy } from "../config";
-import { resolveTestStrategy } from "../config/test-strategy";
-import type { PRD, UserStory } from "./types";
-import { validateStoryId } from "./validate";
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const VALID_COMPLEXITY: Complexity[] = ["simple", "medium", "complex", "expert"];
-
-/** Pattern matching ST001 → ST-001 style IDs (prefix letters + digits, no separator) */
-const STORY_ID_NO_SEPARATOR = /^([A-Za-z]+)(\d+)$/;
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Extract JSON from a markdown code block.
- *
- * Handles:
- *   ```json ... ```
- *   ``` ... ```
- *
- * Returns the input unchanged if no code block is detected.
- */
-export function extractJsonFromMarkdown(text: string): string {
-  const match = text.match(/```(?:json)?\s*\n([\s\S]*?)\n?\s*```/);
-  if (match) {
-    return match[1] ?? text;
-  }
-  return text;
-}
-
-/**
- * Strip trailing commas before closing braces/brackets to handle a common LLM quirk.
- * e.g. `{"a":1,}` → `{"a":1}`
- */
-function stripTrailingCommas(text: string): string {
-  return text.replace(/,\s*([}\]])/g, "$1");
-}
-
-/**
- * Normalize a story ID: convert e.g. ST001 → ST-001.
- * Leaves IDs that already have separators unchanged.
- */
-function normalizeStoryId(id: string): string {
-  const match = id.match(STORY_ID_NO_SEPARATOR);
-  if (match) {
-    return `${match[1]}-${match[2]}`;
-  }
-  return id;
-}
-
-/**
- * Normalize complexity string (case-insensitive) to a valid Complexity value.
- * Returns null if no match found.
- */
-function normalizeComplexity(raw: string): Complexity | null {
-  const lower = raw.toLowerCase() as Complexity;
-  if ((VALID_COMPLEXITY as string[]).includes(lower)) {
-    return lower;
-  }
-  return null;
-}
-
-/**
- * Validate a single story from raw LLM output.
- * Returns a normalized UserStory or throws with field-level error.
- */
-function validateStory(raw: unknown, index: number, allIds: Set<string>): UserStory {
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-    throw new Error(`[schema] story[${index}] must be an object`);
-  }
-
-  const s = raw as Record<string, unknown>;
-
-  // id
-  const rawId = s.id;
-  if (rawId === undefined || rawId === null || rawId === "") {
-    throw new Error(`[schema] story[${index}].id is required and must be non-empty`);
-  }
-  if (typeof rawId !== "string") {
-    throw new Error(`[schema] story[${index}].id must be a string`);
-  }
-  const id = normalizeStoryId(rawId);
-  validateStoryId(id);
-
-  // title
-  const title = s.title;
-  if (!title || typeof title !== "string" || title.trim() === "") {
-    throw new Error(`[schema] story[${index}].title is required and must be non-empty`);
-  }
-
-  // description
-  const description = s.description;
-  if (!description || typeof description !== "string" || description.trim() === "") {
-    throw new Error(`[schema] story[${index}].description is required and must be non-empty`);
-  }
-
-  // acceptanceCriteria
-  const ac = s.acceptanceCriteria;
-  if (!Array.isArray(ac) || ac.length === 0) {
-    throw new Error(`[schema] story[${index}].acceptanceCriteria is required and must be a non-empty array`);
-  }
-  for (let i = 0; i < ac.length; i++) {
-    if (typeof ac[i] !== "string") {
-      throw new Error(`[schema] story[${index}].acceptanceCriteria[${i}] must be a string`);
-    }
-  }
-
-  // complexity — accept from routing.complexity (PRD format) or top-level complexity (legacy)
-  const routing = typeof s.routing === "object" && s.routing !== null ? (s.routing as Record<string, unknown>) : {};
-  const rawComplexity = routing.complexity ?? s.complexity;
-  if (rawComplexity === undefined || rawComplexity === null) {
-    throw new Error(
-      `[schema] story[${index}] missing complexity. Set routing.complexity to one of: ${VALID_COMPLEXITY.join(", ")}`,
-    );
-  }
-  if (typeof rawComplexity !== "string") {
-    throw new Error(`[schema] story[${index}].routing.complexity must be a string`);
-  }
-  const complexity = normalizeComplexity(rawComplexity);
-  if (complexity === null) {
-    throw new Error(
-      `[schema] story[${index}].routing.complexity "${rawComplexity}" is invalid. Valid values: ${VALID_COMPLEXITY.join(", ")}`,
-    );
-  }
-
-  // testStrategy — accept from routing.testStrategy or top-level testStrategy
-  const rawTestStrategy = routing.testStrategy ?? s.testStrategy;
-  const testStrategy: TestStrategy = resolveTestStrategy(
-    typeof rawTestStrategy === "string" ? rawTestStrategy : undefined,
-  );
-
-  // dependencies
-  const rawDeps = s.dependencies;
-  const dependencies: string[] = Array.isArray(rawDeps) ? (rawDeps as string[]) : [];
-
-  // Validate dependency references (against already-known IDs)
-  for (const dep of dependencies) {
-    if (!allIds.has(dep)) {
-      throw new Error(`[schema] story[${index}].dependencies references unknown story ID "${dep}"`);
-    }
-  }
-
-  // tags
-  const rawTags = s.tags;
-  const tags: string[] = Array.isArray(rawTags) ? (rawTags as string[]) : [];
-
-  // workdir — optional, relative path only, no traversal
-  const rawWorkdir = s.workdir;
-  let workdir: string | undefined;
-  if (rawWorkdir !== undefined && rawWorkdir !== null) {
-    if (typeof rawWorkdir !== "string") {
-      throw new Error(`[schema] story[${index}].workdir must be a string`);
-    }
-    if (rawWorkdir.startsWith("/")) {
-      throw new Error(`[schema] story[${index}].workdir must be relative (no leading /): "${rawWorkdir}"`);
-    }
-    if (rawWorkdir.includes("..")) {
-      throw new Error(`[schema] story[${index}].workdir must not contain '..': "${rawWorkdir}"`);
-    }
-    workdir = rawWorkdir;
-  }
-
-  // contextFiles — optional array of relative file paths from LLM analysis
-  const rawContextFiles = s.contextFiles;
-  const contextFiles: string[] = Array.isArray(rawContextFiles)
-    ? (rawContextFiles as unknown[]).filter((f): f is string => typeof f === "string" && f.trim() !== "")
-    : [];
-
-  return {
-    id,
-    title: title.trim(),
-    description: description.trim(),
-    acceptanceCriteria: ac as string[],
-    tags,
-    dependencies,
-    // Force runtime state — never trust LLM output
-    status: "pending",
-    passes: false,
-    attempts: 0,
-    escalations: [],
-    routing: {
-      complexity,
-      testStrategy,
-      reasoning: "validated from LLM output",
-    },
-    ...(workdir !== undefined ? { workdir } : {}),
-    ...(contextFiles.length > 0 ? { contextFiles } : {}),
-  };
-}
-
-/**
- * Parse raw string input, handling markdown wrapping and trailing commas.
- * Throws with parse error context on failure.
- */
-function parseRawString(text: string): unknown {
-  const extracted = extractJsonFromMarkdown(text);
-  const cleaned = stripTrailingCommas(extracted);
-
-  try {
-    return JSON.parse(cleaned);
-  } catch (err) {
-    const parseErr = err as SyntaxError;
-    throw new Error(`[schema] Failed to parse JSON: ${parseErr.message}`, { cause: parseErr });
-  }
-}
-
-/**
- * Validate and normalize the JSON output from the planning LLM.
- *
- * @param raw - Raw LLM output (string or already-parsed object)
- * @param feature - Feature name for auto-fill
- * @param branch - Branch name for auto-fill
- * @returns Validated PRD object
- */
-export function validatePlanOutput(raw: unknown, feature: string, branch: string): PRD {
-  // Parse string input
-  const parsed: unknown = typeof raw === "string" ? parseRawString(raw) : raw;
-
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new Error("[schema] PRD output must be a JSON object");
-  }
-
-  const obj = parsed as Record<string, unknown>;
-
-  // Validate top-level userStories
-  const rawStories = obj.userStories;
-  if (!Array.isArray(rawStories) || rawStories.length === 0) {
-    throw new Error("[schema] userStories is required and must be a non-empty array");
-  }
-
-  // First pass: collect all story IDs (after normalization) for dependency validation
-  const allIds = new Set<string>();
-  for (const story of rawStories) {
-    if (typeof story === "object" && story !== null && !Array.isArray(story)) {
-      const s = story as Record<string, unknown>;
-      const rawId = s.id;
-      if (typeof rawId === "string" && rawId !== "") {
-        allIds.add(normalizeStoryId(rawId));
-      }
-    }
-  }
-
-  // Second pass: full validation
-  const userStories: UserStory[] = rawStories.map((story, index) => validateStory(story, index, allIds));
-
-  const now = new Date().toISOString();
-
-  return {
-    project: typeof obj.project === "string" && obj.project !== "" ? obj.project : feature,
-    feature,
-    branchName: branch,
-    createdAt: typeof obj.createdAt === "string" ? obj.createdAt : now,
-    updatedAt: now,
-    userStories,
-    ...(typeof obj.analysis === "string" && obj.analysis.trim() !== "" ? { analysis: obj.analysis.trim() } : {}),
-  };
-}