@arvorco/relentless 0.1.0

package/src/prd/issues.ts

@@ -0,0 +1,249 @@
+/**
+ * GitHub Issues Generator
+ *
+ * Converts user stories to GitHub issues via gh CLI
+ */
+
+import type { PRD, UserStory } from "./types";
+import { inferStoryType } from "./types";
+import chalk from "chalk";
+
+/**
+ * Validate git remote matches expected repository
+ */
+async function validateGitRemote(): Promise<{ owner: string; repo: string }> {
+  const proc = Bun.spawn(["git", "remote", "get-url", "origin"]);
+  const output = await new Response(proc.stdout).text();
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0) {
+    throw new Error(`Failed to get git remote: exit code ${exitCode}`);
+  }
+
+  const url = output.trim();
+
+  // Parse GitHub remote URL
+  // Supports: git@github.com:owner/repo.git and https://github.com/owner/repo.git
+  const sshMatch = url.match(/git@github\.com:(.+?)\/(.+?)(?:\.git)?$/);
+  const httpsMatch = url.match(/https:\/\/github\.com\/(.+?)\/(.+?)(?:\.git)?$/);
+
+  const match = sshMatch || httpsMatch;
+  if (!match) {
+    throw new Error(`Invalid GitHub remote URL: ${url}`);
+  }
+
+  return { owner: match[1], repo: match[2] };
+}
+
+/**
+ * Infer labels from story content
+ */
+function inferLabels(story: UserStory): string[] {
+  const labels: string[] = [];
+  const type = inferStoryType(story);
+
+  // Add primary type label
+  if (type !== "general") {
+    labels.push(type);
+  }
+
+  // Add priority label
+  if (story.priority <= 3) {
+    labels.push("priority:high");
+  } else if (story.priority <= 6) {
+    labels.push("priority:medium");
+  } else {
+    labels.push("priority:low");
+  }
+
+  // Add phase label if present
+  if (story.phase) {
+    labels.push(`phase:${story.phase.toLowerCase()}`);
+  }
+
+  // Add research label if required
+  if (story.research) {
+    labels.push("research");
+  }
+
+  return labels;
+}
+
+/**
+ * Format story as GitHub issue body
+ */
+function formatIssueBody(story: UserStory): string {
+  const parts: string[] = [];
+
+  // Description
+  parts.push("## Description");
+  parts.push("");
+  parts.push(story.description);
+  parts.push("");
+
+  // Acceptance Criteria
+  parts.push("## Acceptance Criteria");
+  parts.push("");
+  for (const criterion of story.acceptanceCriteria) {
+    parts.push(`- [ ] ${criterion}`);
+  }
+  parts.push("");
+
+  // Dependencies (if any)
+  if (story.dependencies && story.dependencies.length > 0) {
+    parts.push("## Dependencies");
+    parts.push("");
+    parts.push("This story depends on:");
+    for (const depId of story.dependencies) {
+      parts.push(`- ${depId}`);
+    }
+    parts.push("");
+  }
+
+  // Phase (if present)
+  if (story.phase) {
+    parts.push(`**Phase:** ${story.phase}`);
+    parts.push("");
+  }
+
+  // Parallel (if applicable)
+  if (story.parallel) {
+    parts.push("**Can be executed in parallel** with other stories");
+    parts.push("");
+  }
+
+  // Research (if required)
+  if (story.research) {
+    parts.push("⚠️ **Research Phase Required**: This story requires a research phase before implementation.");
+    parts.push("");
+  }
+
+  // Notes (if present)
+  if (story.notes && story.notes.trim() !== "") {
+    parts.push("## Notes");
+    parts.push("");
+    parts.push(story.notes);
+    parts.push("");
+  }
+
+  return parts.join("\n");
+}
+
+/**
+ * Create a GitHub issue for a user story
+ */
+async function createIssue(story: UserStory, labels: string[]): Promise<string> {
+  const title = `[${story.id}] ${story.title}`;
+  const body = formatIssueBody(story);
+
+  // Build gh command
+  const args = [
+    "issue",
+    "create",
+    "--title",
+    title,
+    "--body",
+    body,
+  ];
+
+  // Add labels
+  if (labels.length > 0) {
+    args.push("--label");
+    args.push(labels.join(","));
+  }
+
+  const proc = Bun.spawn(["gh", ...args]);
+  const output = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0) {
+    throw new Error(`Failed to create issue for ${story.id}: ${stderr}`);
+  }
+
+  // Extract issue URL from output (gh returns the URL)
+  return output.trim();
+}
+
+/**
+ * Check if gh CLI is installed
+ */
+async function checkGhCLI(): Promise<boolean> {
+  try {
+    const proc = Bun.spawn(["gh", "--version"]);
+    const exitCode = await proc.exited;
+    return exitCode === 0;
+  } catch (error) {
+    // Log unexpected errors (not just "command not found")
+    if (error instanceof Error && !error.message.includes("ENOENT")) {
+      console.warn(`Unexpected error checking gh CLI: ${error.message}`);
+    }
+    return false;
+  }
+}
+
+/**
+ * Convert PRD user stories to GitHub issues
+ */
+export async function generateGitHubIssues(
+  prd: PRD,
+  options: {
+    dryRun?: boolean;
+    onlyIncomplete?: boolean;
+  } = {}
+): Promise<{ created: number; skipped: number; errors: string[] }> {
+  const { dryRun = false, onlyIncomplete = true } = options;
+
+  // Check gh CLI
+  const hasGh = await checkGhCLI();
+  if (!hasGh) {
+    throw new Error("GitHub CLI (gh) is not installed. Install it from: https://cli.github.com/");
+  }
+
+  // Validate git remote
+  console.log(chalk.dim("Validating git remote..."));
+  const remote = await validateGitRemote();
+  console.log(chalk.dim(`Repository: ${remote.owner}/${remote.repo}`));
+
+  // Filter stories
+  const stories = onlyIncomplete
+    ? prd.userStories.filter((s) => !s.passes)
+    : prd.userStories;
+
+  if (stories.length === 0) {
+    console.log(chalk.yellow("No stories to convert to issues."));
+    return { created: 0, skipped: 0, errors: [] };
+  }
+
+  console.log(chalk.dim(`Found ${stories.length} stories to convert\n`));
+
+  let created = 0;
+  let skipped = 0;
+  const errors: string[] = [];
+
+  for (const story of stories) {
+    const labels = inferLabels(story);
+
+    if (dryRun) {
+      console.log(chalk.cyan(`[DRY RUN] ${story.id}: ${story.title}`));
+      console.log(chalk.dim(`  Labels: ${labels.join(", ")}`));
+      if (story.dependencies && story.dependencies.length > 0) {
+        console.log(chalk.dim(`  Dependencies: ${story.dependencies.join(", ")}`));
+      }
+      created++;
+    } else {
+      try {
+        const issueUrl = await createIssue(story, labels);
+        console.log(chalk.green(`✓ ${story.id}: ${story.title}`));
+        console.log(chalk.dim(`  ${issueUrl}`));
+        created++;
+      } catch (error) {
+        console.log(chalk.red(`✗ ${story.id}: ${story.title}`));
+        console.log(chalk.dim(`  ${(error as Error).message}`));
+        errors.push(`${story.id}: ${(error as Error).message}`);
+      }
+    }
+  }
+
+  return { created, skipped, errors };
+}

package/src/prd/parser.ts

@@ -0,0 +1,281 @@
+/**
+ * PRD Parser
+ *
+ * Parses PRD markdown files and converts them to prd.json format
+ */
+
+import { PRDSchema, type PRD, type UserStory } from "./types";
+
+/**
+ * Check if a criterion line is valid (not a file path, divider, etc.)
+ */
+function isValidCriterion(text: string): boolean {
+  // Skip if it looks like a file path
+  if (text.match(/^`[^`]+\.(ts|tsx|js|jsx|css|json|md)`$/)) {
+    return false;
+  }
+  // Skip if it's just a section marker
+  if (text.startsWith("**")) {
+    return false;
+  }
+  // Skip if it's empty or too short
+  if (text.length < 3) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Parse a PRD markdown file into structured format
+ *
+ * Supports multiple story formats:
+ * - ### US-001: Title
+ * - ### Story 1: Title
+ * - ### 1. Title
+ *
+ * Supports multiple acceptance criteria formats:
+ * - [ ] Criterion
+ * - [x] Criterion
+ * - Criterion (plain bullet)
+ */
+export function parsePRDMarkdown(content: string): Partial<PRD> {
+  const lines = content.split("\n");
+  const prd: Partial<PRD> = {
+    userStories: [],
+  };
+
+  let currentSection = "";
+  let currentStory: Partial<UserStory> | null = null;
+  let storyCount = 0;
+  let inAcceptanceCriteria = false;
+  let descriptionLines: string[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Parse title (# PRD: Title or # Title)
+    if (trimmed.startsWith("# ") && !trimmed.startsWith("## ") && !trimmed.startsWith("### ")) {
+      prd.project = trimmed.replace(/^#\s*(PRD:\s*)?/, "").trim();
+      continue;
+    }
+
+    // Parse section headers (## Section)
+    if (trimmed.startsWith("## ")) {
+      currentSection = trimmed.replace("## ", "").toLowerCase();
+      inAcceptanceCriteria = false;
+      continue;
+    }
+
+    // Parse user stories - multiple formats supported
+    // ### US-001: Title
+    // ### Story 1: Title
+    // ### 1. Title
+    const storyMatch = trimmed.match(/^###\s+(?:US-(\d+)|Story\s+(\d+)|(\d+)\.?)\s*:?\s*(.*)$/i);
+    if (storyMatch) {
+      // Save previous story
+      if (currentStory && currentStory.id) {
+        if (descriptionLines.length > 0 && !currentStory.description) {
+          currentStory.description = descriptionLines.join(" ").trim();
+        }
+        prd.userStories!.push(currentStory as UserStory);
+      }
+
+      storyCount++;
+      const storyNum = storyMatch[1] || storyMatch[2] || storyMatch[3] || String(storyCount);
+      currentStory = {
+        id: `US-${storyNum.padStart(3, "0")}`,
+        title: storyMatch[4]?.trim() || "",
+        description: "",
+        acceptanceCriteria: [],
+        priority: storyCount,
+        passes: false,
+        notes: "",
+        dependencies: undefined,
+        parallel: undefined,
+        phase: undefined,
+      };
+      inAcceptanceCriteria = false;
+      descriptionLines = [];
+      continue;
+    }
+
+    // Check for acceptance criteria section header
+    if (currentStory && trimmed.match(/^\*\*Acceptance Criteria:?\*\*$/i)) {
+      inAcceptanceCriteria = true;
+      continue;
+    }
+
+    // Parse story description (single line after **Description:**)
+    if (currentStory && trimmed.startsWith("**Description:**")) {
+      currentStory.description = trimmed.replace("**Description:**", "").trim();
+      inAcceptanceCriteria = false;
+      continue;
+    }
+
+    // Parse dependencies (Dependencies: US-001, US-002)
+    if (currentStory && trimmed.match(/^\*\*Dependencies:?\*\*/i)) {
+      const deps = trimmed
+        .replace(/^\*\*Dependencies:?\*\*/i, "")
+        .trim()
+        .split(/[,;]/)
+        .map((d) => d.trim())
+        .filter(Boolean);
+      if (deps.length > 0) {
+        currentStory.dependencies = deps;
+      }
+      inAcceptanceCriteria = false;
+      continue;
+    }
+
+    // Parse parallel flag (Parallel: true/yes)
+    if (currentStory && trimmed.match(/^\*\*Parallel:?\*\*/i)) {
+      const value = trimmed.replace(/^\*\*Parallel:?\*\*/i, "").trim().toLowerCase();
+      currentStory.parallel = value === "true" || value === "yes";
+      inAcceptanceCriteria = false;
+      continue;
+    }
+
+    // Parse phase (Phase: Setup)
+    if (currentStory && trimmed.match(/^\*\*Phase:?\*\*/i)) {
+      const phase = trimmed.replace(/^\*\*Phase:?\*\*/i, "").trim();
+      if (phase) {
+        currentStory.phase = phase;
+      }
+      inAcceptanceCriteria = false;
+      continue;
+    }
+
+    // Parse research flag (Research: true/yes)
+    if (currentStory && trimmed.match(/^\*\*Research:?\*\*/i)) {
+      const value = trimmed.replace(/^\*\*Research:?\*\*/i, "").trim().toLowerCase();
+      currentStory.research = value === "true" || value === "yes";
+      inAcceptanceCriteria = false;
+      continue;
+    }
+
+    // Check for section headers within story that end acceptance criteria
+    if (currentStory && trimmed.match(/^\*\*(Files|Note|Technical|Design)/i)) {
+      inAcceptanceCriteria = false;
+      continue;
+    }
+
+    // Parse acceptance criteria - multiple formats
+    // - [ ] Criterion
+    // - [x] Criterion
+    // - Criterion (plain bullet, only in acceptance criteria section)
+    if (currentStory && trimmed.startsWith("-")) {
+      // Skip dividers like "---"
+      if (trimmed.match(/^-+$/)) {
+        inAcceptanceCriteria = false;
+        continue;
+      }
+
+      // Checkbox format
+      if (trimmed.match(/^-\s*\[.\]/)) {
+        const criterion = trimmed.replace(/^-\s*\[.\]\s*/, "").trim();
+        if (criterion && isValidCriterion(criterion)) {
+          currentStory.acceptanceCriteria!.push(criterion);
+        }
+        inAcceptanceCriteria = true;
+        continue;
+      }
+      // Plain bullet format (only if we're in acceptance criteria section)
+      if (inAcceptanceCriteria) {
+        const criterion = trimmed.replace(/^-\s*/, "").trim();
+        if (criterion && isValidCriterion(criterion)) {
+          currentStory.acceptanceCriteria!.push(criterion);
+        }
+        continue;
+      }
+    }
+
+    // Collect description lines (paragraphs after story header, before acceptance criteria)
+    if (currentStory && !inAcceptanceCriteria && trimmed && !trimmed.startsWith("**") && !trimmed.startsWith("#")) {
+      descriptionLines.push(trimmed);
+    }
+
+    // Parse description if in introduction/overview section (for PRD description)
+    if ((currentSection === "introduction" || currentSection === "overview") && !currentStory) {
+      if (trimmed && !prd.description && !trimmed.startsWith("**")) {
+        prd.description = trimmed;
+      }
+    }
+  }
+
+  // Save last story
+  if (currentStory && currentStory.id) {
+    if (descriptionLines.length > 0 && !currentStory.description) {
+      currentStory.description = descriptionLines.join(" ").trim();
+    }
+    prd.userStories!.push(currentStory as UserStory);
+  }
+
+  return prd;
+}
+
+/**
+ * Generate branch name from project name
+ */
+export function generateBranchName(projectName: string, featureName?: string): string {
+  let kebab = projectName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+
+  // If featureName has a number prefix (NNN-name), prepend it to branch name
+  if (featureName) {
+    const match = featureName.match(/^(\d{3})-/);
+    if (match) {
+      const numberPrefix = match[1];
+      kebab = `${numberPrefix}-${kebab}`;
+    }
+  }
+
+  return `ralph/${kebab}`;
+}
+
+/**
+ * Convert parsed PRD to complete PRD with defaults
+ */
+export function createPRD(parsed: Partial<PRD>, featureName?: string): PRD {
+  const project = parsed.project ?? "Unnamed Project";
+  const prd: PRD = {
+    project,
+    branchName: parsed.branchName ?? generateBranchName(project, featureName),
+    description: parsed.description ?? "",
+    userStories: (parsed.userStories ?? []).map((story, index) => ({
+      id: story.id ?? `US-${String(index + 1).padStart(3, "0")}`,
+      title: story.title ?? "",
+      description: story.description ?? "",
+      acceptanceCriteria: story.acceptanceCriteria ?? [],
+      priority: story.priority ?? index + 1,
+      passes: story.passes ?? false,
+      notes: story.notes ?? "",
+      dependencies: story.dependencies,
+      parallel: story.parallel,
+      phase: story.phase,
+      research: story.research,
+    })),
+  };
+
+  // Validate
+  return PRDSchema.parse(prd);
+}
+
+/**
+ * Load PRD from JSON file
+ */
+export async function loadPRD(path: string): Promise<PRD> {
+  const content = await Bun.file(path).text();
+  const json = JSON.parse(content);
+  return PRDSchema.parse(json);
+}
+
+/**
+ * Save PRD to JSON file
+ */
+export async function savePRD(prd: PRD, path: string): Promise<void> {
+  const validated = PRDSchema.parse(prd);
+  const content = JSON.stringify(validated, null, 2);
+  await Bun.write(path, content);
+}