ralphctl 0.1.0 → 0.1.2

package/src/commands/sprint/refine.ts

@@ -1,359 +0,0 @@
-import { mkdir, readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { confirm } from '@inquirer/prompts';
-import { colors, info } from '@src/theme/index.ts';
-import {
-  createSpinner,
-  emoji,
-  field,
-  fieldMultiline,
-  icons,
-  log,
-  printHeader,
-  printSeparator,
-  progressBar,
-  renderCard,
-  showError,
-  showSuccess,
-  showTip,
-  showWarning,
-} from '@src/theme/ui.ts';
-import { assertSprintStatus, getSprint, resolveSprintId, saveSprint } from '@src/store/sprint.ts';
-import { getPendingRequirements } from '@src/store/ticket.ts';
-import { getProject } from '@src/store/project.ts';
-import { buildTicketRefinePrompt } from '@src/ai/prompts/index.ts';
-import { fileExists } from '@src/utils/storage.ts';
-import { getRefinementDir, getSchemaPath, getSprintDir } from '@src/utils/paths.ts';
-import { IssueFetchError, fetchIssueFromUrl, formatIssueContext } from '@src/utils/issue-fetch.ts';
-import { type RefinedRequirement } from '@src/schemas/index.ts';
-import { exportRequirementsToMarkdown } from '@src/utils/requirements-export.ts';
-import { resolveProvider, providerDisplayName } from '@src/utils/provider.ts';
-import { formatTicketForPrompt, parseRequirementsFile, runAiSession } from '@src/commands/ticket/refine-utils.ts';
-
-interface RefineOptions {
-  project?: string;
-}
-
-function parseArgs(args: string[]): { sprintId?: string; options: RefineOptions } {
-  const options: RefineOptions = {};
-  let sprintId: string | undefined;
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    const nextArg = args[i + 1];
-
-    if (arg === '--project') {
-      options.project = nextArg;
-      i++;
-    } else if (!arg?.startsWith('-')) {
-      sprintId = arg;
-    }
-  }
-
-  return { sprintId, options };
-}
-
-export async function sprintRefineCommand(args: string[]): Promise<void> {
-  const { sprintId, options } = parseArgs(args);
-
-  let id: string;
-  try {
-    id = await resolveSprintId(sprintId);
-  } catch {
-    showWarning('No sprint specified and no current sprint set.');
-    showTip('Specify a sprint ID or create one first.');
-    log.newline();
-    return;
-  }
-
-  const sprint = await getSprint(id);
-
-  // Check sprint status - must be draft to refine
-  try {
-    assertSprintStatus(sprint, ['draft'], 'refine');
-  } catch (err) {
-    if (err instanceof Error) {
-      showError(err.message);
-      log.newline();
-    }
-    return;
-  }
-
-  if (sprint.tickets.length === 0) {
-    showWarning('No tickets in sprint.');
-    showTip('Add tickets first: ralphctl ticket add --project <project-name>');
-    log.newline();
-    return;
-  }
-
-  // Get pending tickets (filter by project if specified)
-  let pendingTickets = getPendingRequirements(sprint.tickets);
-  if (options.project) {
-    pendingTickets = pendingTickets.filter((t) => t.projectName === options.project);
-    if (pendingTickets.length === 0) {
-      showWarning(`No pending tickets for project: ${options.project}`);
-      log.newline();
-      return;
-    }
-  }
-
-  if (pendingTickets.length === 0) {
-    showSuccess('All tickets already have approved requirements!');
-    showTip('Run "ralphctl sprint plan" to generate tasks.');
-    log.newline();
-    return;
-  }
-
-  // Show initial summary
-  printHeader('Requirements Refinement', icons.ticket);
-  console.log(field('Sprint', sprint.name));
-  console.log(field('ID', sprint.id));
-  console.log(field('Pending', `${String(pendingTickets.length)} ticket(s)`));
-  log.newline();
-
-  // Load schema once before processing tickets
-  const schemaPath = getSchemaPath('requirements-output.schema.json');
-  const schema = await readFile(schemaPath, 'utf-8');
-
-  // Resolve AI provider for display names
-  const providerName = providerDisplayName(await resolveProvider());
-
-  // Process tickets one by one
-  let approved = 0;
-  let skipped = 0;
-
-  for (let i = 0; i < pendingTickets.length; i++) {
-    const ticket = pendingTickets[i];
-    if (!ticket) continue;
-
-    const ticketNum = i + 1;
-    const totalTickets = pendingTickets.length;
-
-    // Show ticket card
-    printSeparator(60);
-    console.log('');
-    console.log(`  ${icons.ticket}  ${info(`Ticket ${String(ticketNum)} of ${String(totalTickets)}`)}`);
-    console.log(
-      `  ${progressBar(i, totalTickets, {
-        width: 15,
-        showPercent: false,
-      })} ${colors.muted(`${String(ticketNum)}/${String(totalTickets)}`)}`
-    );
-    console.log('');
-    console.log(field('Title', ticket.title, 14));
-    console.log(field('Project', ticket.projectName, 14));
-    if (ticket.link) {
-      console.log(field('Link', ticket.link, 14));
-    }
-    if (ticket.description) {
-      console.log(fieldMultiline('Description', ticket.description, 14));
-    }
-    log.newline();
-
-    // Validate project exists
-    try {
-      await getProject(ticket.projectName);
-    } catch {
-      showWarning(`Project '${ticket.projectName}' not found.`);
-      log.dim('Skipping this ticket.');
-      log.newline();
-      skipped++;
-      continue;
-    }
-
-    // Confirm before starting AI session
-    const proceed = await confirm({
-      message: `${emoji.donut} Start ${providerName} refinement session for this ticket?`,
-      default: true,
-    });
-
-    if (!proceed) {
-      log.dim('Skipped. You can refine this ticket later.');
-      log.newline();
-      skipped++;
-      continue;
-    }
-
-    // Fetch live issue data if ticket has an issue link
-    let issueContext = '';
-    if (ticket.link) {
-      const fetchSpinner = createSpinner('Fetching issue data...');
-      fetchSpinner.start();
-      try {
-        const issueData = fetchIssueFromUrl(ticket.link);
-        if (issueData) {
-          issueContext = formatIssueContext(issueData);
-          fetchSpinner.succeed(`Issue data fetched (${String(issueData.comments.length)} comment(s))`);
-        } else {
-          fetchSpinner.stop();
-        }
-      } catch (err) {
-        fetchSpinner.fail('Could not fetch issue data');
-        if (err instanceof IssueFetchError) {
-          showWarning(`${err.message} — continuing without issue context`);
-        } else if (err instanceof Error) {
-          showWarning(`${err.message} — continuing without issue context`);
-        }
-      }
-    }
-
-    // Prepare AI session - use sprint's refinement directory
-    const refineDir = getRefinementDir(id, ticket.id);
-    await mkdir(refineDir, { recursive: true });
-    const outputFile = join(refineDir, 'requirements.json');
-    const ticketContent = formatTicketForPrompt(ticket);
-    const prompt = buildTicketRefinePrompt(ticketContent, outputFile, schema, issueContext);
-
-    log.dim(`Working directory: ${refineDir}`);
-    log.dim(`Requirements output: ${outputFile}`);
-    log.newline();
-
-    const spinner = createSpinner(`Starting ${providerName} session...`);
-    spinner.start();
-
-    try {
-      await runAiSession(refineDir, prompt, ticket.title);
-      spinner.succeed(`${providerName} session completed`);
-    } catch (err) {
-      spinner.fail(`${providerName} session failed`);
-      if (err instanceof Error) {
-        showError(err.message);
-      }
-      log.newline();
-      skipped++;
-      continue;
-    }
-
-    log.newline();
-
-    // Process the requirements file
-    if (await fileExists(outputFile)) {
-      let content: string;
-      try {
-        content = await readFile(outputFile, 'utf-8');
-      } catch {
-        showError(`Failed to read requirements file: ${outputFile}`);
-        log.newline();
-        skipped++;
-        continue;
-      }
-
-      let refinedRequirements: RefinedRequirement[];
-      try {
-        refinedRequirements = parseRequirementsFile(content);
-      } catch (err) {
-        if (err instanceof Error) {
-          showError(`Failed to parse requirements file: ${err.message}`);
-        }
-        log.newline();
-        skipped++;
-        continue;
-      }
-
-      if (refinedRequirements.length === 0) {
-        showWarning('No requirements found in output file.');
-        log.newline();
-        skipped++;
-        continue;
-      }
-
-      // Find all matching requirements (Claude may output multiple for one ticket)
-      const matchingRequirements = refinedRequirements.filter((r) => r.ref === ticket.id || r.ref === ticket.title);
-
-      if (matchingRequirements.length === 0) {
-        showWarning('Requirement reference does not match this ticket.');
-        log.newline();
-        skipped++;
-        continue;
-      }
-
-      // Combine multiple requirements into one (safety net for split outputs)
-      const requirement: RefinedRequirement =
-        matchingRequirements.length === 1
-          ? {
-              ref: matchingRequirements[0]?.ref ?? '',
-              requirements: matchingRequirements[0]?.requirements ?? '',
-            }
-          : {
-              ref: matchingRequirements[0]?.ref ?? '',
-              requirements: matchingRequirements
-                .map((r, idx) => {
-                  const text = r.requirements.trim();
-                  if (/^#\s/.test(text)) return text;
-                  return `# ${String(idx + 1)}. Section ${String(idx + 1)}\n\n${text}`;
-                })
-                .join('\n\n---\n\n'),
-            };
-
-      // Show requirement for review
-      const reqLines = requirement.requirements.split('\n');
-      console.log(renderCard(`${icons.ticket} Refined Requirements`, reqLines));
-      log.newline();
-
-      const approveRequirement = await confirm({
-        message: `${emoji.donut} Approve these requirements?`,
-        default: true,
-      });
-
-      if (approveRequirement) {
-        // Save requirements to ticket
-        const ticketIdx = sprint.tickets.findIndex((t) => t.id === ticket.id);
-        const ticketToSave = sprint.tickets[ticketIdx];
-        if (ticketIdx !== -1 && ticketToSave) {
-          ticketToSave.requirements = requirement.requirements;
-          ticketToSave.requirementStatus = 'approved';
-        }
-        await saveSprint(sprint);
-        showSuccess('Requirements approved and saved!');
-        approved++;
-      } else {
-        log.dim('Requirements not approved. You can refine this ticket later.');
-        skipped++;
-      }
-    } else {
-      showWarning('No requirements file found from AI session.');
-      log.dim('You can refine this ticket later.');
-      skipped++;
-    }
-
-    log.newline();
-  }
-
-  // Final summary
-  printSeparator(60);
-  log.newline();
-  printHeader('Summary', icons.success);
-  console.log(field('Approved', String(approved)));
-  console.log(field('Skipped', String(skipped)));
-  console.log(field('Total', String(pendingTickets.length)));
-  log.newline();
-
-  // Re-read sprint to get the latest state after all saves
-  const updatedSprint = await getSprint(id);
-  const remainingPending = getPendingRequirements(updatedSprint.tickets);
-
-  if (remainingPending.length === 0) {
-    showSuccess('All requirements approved!');
-
-    // Auto-export requirements to sprint directory
-    const sprintDir = getSprintDir(id);
-    const outputPath = join(sprintDir, 'requirements.md');
-
-    try {
-      await exportRequirementsToMarkdown(updatedSprint, outputPath);
-      log.dim(`Requirements saved to: ${outputPath}`);
-    } catch (err) {
-      if (err instanceof Error) {
-        showError(`Failed to write requirements: ${err.message}`);
-      } else {
-        showError('Failed to write requirements: Unknown error');
-      }
-    }
-
-    showTip('Run "ralphctl sprint plan" to generate tasks.');
-  } else {
-    log.info(`${String(remainingPending.length)} ticket(s) still pending.`);
-    showTip('Continue refinement with: ralphctl sprint refine');
-  }
-  log.newline();
-}

package/src/commands/sprint/requirements.ts

@@ -1,58 +0,0 @@
-import { join } from 'node:path';
-import { getSprint, resolveSprintId } from '@src/store/sprint.ts';
-import { getSprintDir } from '@src/utils/paths.ts';
-import { exportRequirementsToMarkdown } from '@src/utils/requirements-export.ts';
-import { field, icons, log, printHeader, showEmpty, showError, showSuccess, showWarning } from '@src/theme/ui.ts';
-import { selectSprint } from '@src/interactive/selectors.ts';
-
-export async function sprintRequirementsCommand(args: string[] = []): Promise<void> {
-  const sprintId = args.find((a) => !a.startsWith('-'));
-
-  let id: string;
-  try {
-    id = await resolveSprintId(sprintId);
-  } catch {
-    const selected = await selectSprint('Select sprint to export requirements from:');
-    if (!selected) return;
-    id = selected;
-  }
-
-  const sprint = await getSprint(id);
-
-  if (sprint.tickets.length === 0) {
-    showEmpty('tickets in this sprint', 'Add tickets first: ralphctl ticket add --project <name>');
-    return;
-  }
-
-  const approvedTickets = sprint.tickets.filter((t) => t.requirementStatus === 'approved');
-  if (approvedTickets.length === 0) {
-    showWarning('No approved requirements to export.');
-    log.dim('Refine requirements first: ralphctl sprint refine');
-    log.newline();
-    return;
-  }
-
-  printHeader('Export Requirements', icons.sprint);
-  console.log(field('Sprint', sprint.name));
-  console.log(field('Tickets', `${String(sprint.tickets.length)} total, ${String(approvedTickets.length)} approved`));
-  log.newline();
-
-  // Export to sprint directory
-  const sprintDir = getSprintDir(id);
-  const outputPath = join(sprintDir, 'requirements.md');
-
-  try {
-    await exportRequirementsToMarkdown(sprint, outputPath);
-    showSuccess('Requirements written to:');
-    log.item(outputPath);
-  } catch (err) {
-    if (err instanceof Error) {
-      showError(`Failed to write requirements: ${err.message}`);
-    } else {
-      showError('Failed to write requirements: Unknown error');
-    }
-    return;
-  }
-
-  log.newline();
-}

package/src/commands/sprint/show.ts

@@ -1,140 +0,0 @@
-import { colors, muted } from '@src/theme/index.ts';
-import { getSprint, resolveSprintId } from '@src/store/sprint.ts';
-import { listTasks } from '@src/store/task.ts';
-import { getCurrentSprint } from '@src/store/config.ts';
-import { formatTicketDisplay, getPendingRequirements, groupTicketsByProject } from '@src/store/ticket.ts';
-import {
-  badge,
-  formatSprintStatus,
-  formatTaskStatus,
-  horizontalLine,
-  icons,
-  labelValue,
-  log,
-  printCountSummary,
-  renderCard,
-  showNextStep,
-} from '@src/theme/ui.ts';
-import { selectSprint } from '@src/interactive/selectors.ts';
-
-export async function sprintShowCommand(args: string[]): Promise<void> {
-  const sprintId = args[0];
-
-  let id: string;
-  try {
-    id = await resolveSprintId(sprintId);
-  } catch {
-    const selected = await selectSprint('Select sprint to show:');
-    if (!selected) return;
-    id = selected;
-  }
-
-  const sprint = await getSprint(id);
-  const tasks = await listTasks(id);
-  const currentSprintId = await getCurrentSprint();
-  const isCurrent = sprint.id === currentSprintId;
-
-  // Sprint info card
-  const infoLines: string[] = [
-    labelValue('ID', sprint.id + (isCurrent ? ' ' + badge('current', 'success') : '')),
-    labelValue('Status', formatSprintStatus(sprint.status)),
-    labelValue('Created', new Date(sprint.createdAt).toLocaleString()),
-  ];
-  if (sprint.activatedAt) {
-    infoLines.push(labelValue('Activated', new Date(sprint.activatedAt).toLocaleString()));
-  }
-  if (sprint.closedAt) {
-    infoLines.push(labelValue('Closed', new Date(sprint.closedAt).toLocaleString()));
-  }
-  if (sprint.branch) {
-    infoLines.push(labelValue('Branch', sprint.branch));
-  }
-
-  log.newline();
-  console.log(renderCard(`${icons.sprint} ${sprint.name}`, infoLines));
-
-  // Tickets card
-  log.newline();
-  const ticketLines: string[] = [];
-
-  if (sprint.tickets.length === 0) {
-    ticketLines.push(muted('No tickets yet'));
-    ticketLines.push(muted(`${icons.tip} Add with: ralphctl ticket add`));
-  } else {
-    const ticketsByProject = groupTicketsByProject(sprint.tickets);
-    let first = true;
-    for (const [projectName, tickets] of ticketsByProject) {
-      if (!first) ticketLines.push('');
-      first = false;
-      ticketLines.push(`${colors.info(icons.project)} ${colors.info(projectName)}`);
-      for (const ticket of tickets) {
-        const reqBadge =
-          ticket.requirementStatus === 'approved' ? badge('approved', 'success') : badge('pending', 'warning');
-        ticketLines.push(`  ${icons.bullet} ${formatTicketDisplay(ticket)} ${reqBadge}`);
-      }
-    }
-  }
-
-  console.log(renderCard(`${icons.ticket} Tickets (${String(sprint.tickets.length)})`, ticketLines));
-
-  // Tasks card
-  log.newline();
-  const taskLines: string[] = [];
-
-  const tasksByStatus = {
-    todo: tasks.filter((t) => t.status === 'todo').length,
-    in_progress: tasks.filter((t) => t.status === 'in_progress').length,
-    done: tasks.filter((t) => t.status === 'done').length,
-  };
-
-  if (tasks.length === 0) {
-    taskLines.push(muted('No tasks yet'));
-    taskLines.push(muted(`${icons.tip} Plan with: ralphctl sprint plan`));
-  } else {
-    // Status summary row
-    taskLines.push(
-      `${formatTaskStatus('todo')} ${String(tasksByStatus.todo)}   ` +
-        `${formatTaskStatus('in_progress')} ${String(tasksByStatus.in_progress)}   ` +
-        `${formatTaskStatus('done')} ${String(tasksByStatus.done)}`
-    );
-    taskLines.push(colors.muted(horizontalLine(40, 'rounded')));
-
-    // Task list
-    for (const task of tasks) {
-      const statusIcon =
-        task.status === 'done' ? icons.success : task.status === 'in_progress' ? icons.active : icons.inactive;
-      const statusColor = task.status === 'done' ? 'success' : task.status === 'in_progress' ? 'warning' : 'muted';
-      taskLines.push(`${muted(String(task.order) + '.')} ${badge(statusIcon, statusColor)} ${task.name}`);
-    }
-  }
-
-  console.log(renderCard(`${icons.task} Tasks (${String(tasks.length)})`, taskLines));
-
-  // Progress summary (outside card for consistent formatting)
-  if (tasks.length > 0) {
-    printCountSummary('Progress', tasksByStatus.done, tasks.length);
-  }
-
-  // State-aware next steps
-  log.newline();
-  if (sprint.status === 'draft') {
-    const pendingCount = getPendingRequirements(sprint.tickets).length;
-    if (sprint.tickets.length === 0) {
-      showNextStep('ralphctl ticket add --project <name>', 'add tickets to this sprint');
-    } else if (pendingCount > 0) {
-      showNextStep('ralphctl sprint refine', 'refine ticket requirements');
-    } else if (tasks.length === 0) {
-      showNextStep('ralphctl sprint plan', 'generate tasks from tickets');
-    } else {
-      showNextStep('ralphctl sprint start', 'begin implementation');
-    }
-  } else if (sprint.status === 'active') {
-    if (tasksByStatus.done === tasks.length && tasks.length > 0) {
-      showNextStep('ralphctl sprint close', 'all tasks done — close the sprint');
-    } else {
-      showNextStep('ralphctl sprint start', 'continue implementation');
-    }
-  }
-
-  log.newline();
-}

package/src/commands/sprint/start.ts

@@ -1,119 +0,0 @@
-import { type RunnerOptions, runSprint } from '@src/ai/runner.ts';
-import { SprintNotFoundError, SprintStatusError } from '@src/store/sprint.ts';
-import { EXIT_ERROR, EXIT_NO_TASKS, exitWithCode } from '@src/utils/exit-codes.ts';
-import { log, showError, showNextStep, showWarning } from '@src/theme/ui.ts';
-
-function parseArgs(args: string[]): { sprintId?: string; options: RunnerOptions } {
-  const options: RunnerOptions = {
-    step: false,
-    count: null,
-    session: false,
-    noCommit: false,
-  };
-  let sprintId: string | undefined;
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-
-    if (arg === '-t' || arg === '--step') {
-      options.step = true;
-    } else if (arg === '-s' || arg === '--session') {
-      options.session = true;
-    } else if (arg === '--no-commit') {
-      options.noCommit = true;
-    } else if (arg === '-c' || arg === '--count') {
-      const countStr = args[++i];
-      if (!countStr) {
-        throw new Error('--count requires a number');
-      }
-      const count = parseInt(countStr, 10);
-      if (isNaN(count) || count < 1 || count > 10000) {
-        throw new Error('--count must be an integer between 1 and 10000');
-      }
-      options.count = count;
-    } else if (arg === '--concurrency') {
-      const concStr = args[++i];
-      if (!concStr) {
-        throw new Error('--concurrency requires a number');
-      }
-      const conc = parseInt(concStr, 10);
-      if (isNaN(conc) || conc < 1 || conc > 10) {
-        throw new Error('--concurrency must be an integer between 1 and 10');
-      }
-      options.concurrency = conc;
-    } else if (arg === '--max-retries') {
-      const retryStr = args[++i];
-      if (!retryStr) {
-        throw new Error('--max-retries requires a number');
-      }
-      const retries = parseInt(retryStr, 10);
-      if (isNaN(retries) || retries < 0 || retries > 20) {
-        throw new Error('--max-retries must be an integer between 0 and 20');
-      }
-      options.maxRetries = retries;
-    } else if (arg === '--fail-fast') {
-      options.failFast = true;
-    } else if (arg === '--no-fail-fast') {
-      options.failFast = false;
-    } else if (arg === '-f' || arg === '--force') {
-      options.force = true;
-    } else if (arg === '--refresh-check') {
-      options.refreshCheck = true;
-    } else if (arg === '-b' || arg === '--branch') {
-      options.branch = true;
-    } else if (arg === '--branch-name') {
-      const nameStr = args[++i];
-      if (!nameStr) {
-        throw new Error('--branch-name requires a value');
-      }
-      options.branchName = nameStr;
-    } else if (!arg?.startsWith('-')) {
-      sprintId = arg;
-    }
-  }
-
-  return { sprintId, options };
-}
-
-export async function sprintStartCommand(args: string[]): Promise<void> {
-  let sprintId: string | undefined;
-  let options: RunnerOptions;
-
-  try {
-    const parsed = parseArgs(args);
-    sprintId = parsed.sprintId;
-    options = parsed.options;
-  } catch (err) {
-    if (err instanceof Error) {
-      showError(err.message);
-      log.newline();
-    }
-    exitWithCode(EXIT_ERROR);
-  }
-
-  try {
-    const summary = await runSprint(sprintId, options);
-
-    // Exit with appropriate code based on execution summary
-    if (summary) {
-      exitWithCode(summary.exitCode);
-    }
-  } catch (err) {
-    if (err instanceof SprintNotFoundError) {
-      showError(`Sprint not found: ${sprintId ?? 'unknown'}`);
-      log.newline();
-      exitWithCode(EXIT_ERROR);
-    } else if (err instanceof SprintStatusError) {
-      showError(err.message);
-      log.newline();
-      exitWithCode(EXIT_ERROR);
-    } else if (err instanceof Error && err.message.includes('No sprint specified')) {
-      showWarning('No sprint specified and no active sprint set.');
-      showNextStep('ralphctl sprint start <id>', 'specify a sprint ID');
-      log.newline();
-      exitWithCode(EXIT_NO_TASKS);
-    } else {
-      throw err;
-    }
-  }
-}

package/src/commands/sprint/switch.ts

@@ -1,20 +0,0 @@
-import { setCurrentSprint } from '@src/store/config.ts';
-import { getSprint } from '@src/store/sprint.ts';
-import { selectSprint } from '@src/interactive/selectors.ts';
-import { log, showSuccess } from '@src/theme/ui.ts';
-
-/**
- * Quick sprint switcher for interactive mode
- */
-export async function sprintSwitchCommand(): Promise<void> {
-  const selectedId = await selectSprint('Select sprint to switch to:');
-  if (!selectedId) return;
-
-  await setCurrentSprint(selectedId);
-  const sprint = await getSprint(selectedId);
-  showSuccess('Switched to sprint!', [
-    ['ID', sprint.id],
-    ['Name', sprint.name],
-  ]);
-  log.newline();
-}