ralphctl 0.1.0

package/src/completion/resolver.ts

@@ -0,0 +1,241 @@
+import type { Command } from 'commander';
+import type { CompletionItem } from 'tabtab';
+
+export interface CompletionContext {
+  /** The full line typed so far */
+  line: string;
+  /** The last word (what the user is currently typing) */
+  last: string;
+  /** The word before the last word */
+  prev: string;
+}
+
+type DynamicResolver = () => Promise<CompletionItem[]>;
+
+const dynamicResolvers: Record<string, DynamicResolver> = {
+  '--project': async () => {
+    try {
+      const { listProjects } = await import('@src/store/project.ts');
+      const projects = await listProjects();
+      return projects.map((p) => ({ name: p.name, description: p.displayName }));
+    } catch {
+      return [];
+    }
+  },
+  '--status': () => {
+    // Context-dependent but we return all possible values — shell filtering handles partial match
+    return Promise.resolve([
+      { name: 'draft', description: 'Draft sprints' },
+      { name: 'active', description: 'Active sprints' },
+      { name: 'closed', description: 'Closed sprints' },
+      { name: 'todo', description: 'Todo tasks' },
+      { name: 'in_progress', description: 'In-progress tasks' },
+      { name: 'done', description: 'Done tasks' },
+      { name: 'pending', description: 'Pending requirements' },
+      { name: 'approved', description: 'Approved requirements' },
+    ]);
+  },
+};
+
+/**
+ * Resolve the value completions for `config set <key>` and `config set <key> <value>`.
+ */
+const configKeyCompletions: CompletionItem[] = [
+  { name: 'provider', description: 'AI provider (claude or copilot)' },
+  { name: 'editor', description: 'External editor for multiline input' },
+];
+
+const configValueCompletions: Record<string, CompletionItem[]> = {
+  provider: [
+    { name: 'claude', description: 'Claude Code CLI' },
+    { name: 'copilot', description: 'GitHub Copilot CLI' },
+  ],
+};
+
+/**
+ * Try to load sprint IDs for positional completion.
+ */
+async function getSprintCompletions(): Promise<CompletionItem[]> {
+  try {
+    const { listSprints } = await import('@src/store/sprint.ts');
+    const sprints = await listSprints();
+    return sprints.map((s) => ({
+      name: s.id,
+      description: `${s.name} (${s.status})`,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Get all commands from a Commander command (direct children).
+ */
+function getSubcommands(cmd: Command): CompletionItem[] {
+  return cmd.commands.map((sub: Command) => ({
+    name: sub.name(),
+    description: sub.description(),
+  }));
+}
+
+/**
+ * Get all options from a Commander command.
+ */
+function getOptions(cmd: Command): CompletionItem[] {
+  const items: CompletionItem[] = [];
+  for (const opt of cmd.options) {
+    // Prefer long flag, fall back to short
+    const flag = opt.long ?? opt.short;
+    if (flag) {
+      items.push({ name: flag, description: opt.description });
+    }
+  }
+  return items;
+}
+
+/**
+ * Find a subcommand by name.
+ */
+function findSubcommand(cmd: Command, name: string): Command | undefined {
+  return cmd.commands.find((sub: Command) => sub.name() === name);
+}
+
+/**
+ * Check whether the given option expects a value argument (not boolean).
+ */
+function optionExpectsValue(cmd: Command, flag: string): boolean {
+  const opt = cmd.options.find((o) => o.long === flag || o.short === flag);
+  if (!opt) return false;
+  // Commander: boolean flags (--force) have required=false and optional=false
+  return opt.required || opt.optional;
+}
+
+/**
+ * Parse words out of the completion line (skipping the program name).
+ */
+function parseWords(line: string): string[] {
+  return line.trim().split(/\s+/).slice(1);
+}
+
+/**
+ * Resolve completions for the current input context by introspecting a Commander program.
+ */
+export async function resolveCompletions(program: Command, ctx: CompletionContext): Promise<CompletionItem[]> {
+  const words = parseWords(ctx.line);
+
+  // Walk the Commander tree to find the deepest matching command
+  let currentCmd = program;
+  let wordIndex = 0;
+
+  while (wordIndex < words.length) {
+    const word = words[wordIndex];
+    if (!word) break;
+
+    // Skip flags and their values during traversal
+    if (word.startsWith('-')) {
+      wordIndex++;
+      // If the flag expects a value, skip the next word too
+      if (optionExpectsValue(currentCmd, word) && wordIndex < words.length) {
+        wordIndex++;
+      }
+      continue;
+    }
+
+    const sub = findSubcommand(currentCmd, word);
+    if (sub) {
+      currentCmd = sub;
+      wordIndex++;
+    } else {
+      break;
+    }
+  }
+
+  // Special case: `config set` positional args
+  const cmdPath = getCommandPath(currentCmd);
+  if (cmdPath === 'config set') {
+    return resolveConfigSetCompletions(words, ctx);
+  }
+
+  // If the previous word is a flag that expects a value → resolve that value
+  if (ctx.prev.startsWith('-')) {
+    // Check for dynamic resolver
+    const resolver = dynamicResolvers[ctx.prev];
+    if (resolver) {
+      return resolver();
+    }
+
+    // If the option expects a value but we have no resolver, return empty (let user type)
+    if (optionExpectsValue(currentCmd, ctx.prev)) {
+      return [];
+    }
+  }
+
+  // If the user is typing a flag (starts with -)
+  if (ctx.last.startsWith('-')) {
+    return getOptions(currentCmd);
+  }
+
+  // If the command has subcommands, offer those
+  const subs = getSubcommands(currentCmd);
+  if (subs.length > 0) {
+    return subs;
+  }
+
+  // For commands that accept a positional [id] argument (sprint subcommands), offer sprint IDs
+  if (cmdPath.startsWith('sprint ') && acceptsPositionalArg(currentCmd)) {
+    return getSprintCompletions();
+  }
+
+  return [];
+}
+
+/**
+ * Get the full command path (e.g. "sprint start", "config set").
+ */
+function getCommandPath(cmd: Command): string {
+  const parts: string[] = [];
+  let current: Command | null = cmd;
+  while (current?.parent) {
+    parts.unshift(current.name());
+    current = current.parent as Command | null;
+  }
+  return parts.join(' ');
+}
+
+/**
+ * Check whether a command accepts positional arguments (has [id] or similar in usage).
+ */
+function acceptsPositionalArg(cmd: Command): boolean {
+  // Commander stores registered args
+  return cmd.registeredArguments.length > 0;
+}
+
+/**
+ * Handle completions for `config set <key> [value]`.
+ */
+function resolveConfigSetCompletions(words: string[], ctx: CompletionContext): Promise<CompletionItem[]> {
+  const setIndex = words.indexOf('set');
+
+  if (setIndex === -1) {
+    return Promise.resolve(configKeyCompletions);
+  }
+
+  // Positional args after "set" (excluding flags)
+  const argsAfterSet = words.slice(setIndex + 1).filter((w) => !w.startsWith('-'));
+
+  // No args yet, or typing a partial key → suggest keys
+  if (argsAfterSet.length === 0) {
+    return Promise.resolve(configKeyCompletions);
+  }
+
+  // One arg present and user is still typing it (last word matches the arg) → suggest keys
+  if (argsAfterSet.length === 1 && ctx.last !== '') {
+    return Promise.resolve(configKeyCompletions);
+  }
+
+  // One arg present and cursor moved past it (last is empty) → suggest values for that key
+  // OR two args present (user is typing the value) → suggest values for the first arg
+  const key = argsAfterSet[0];
+  const values = key ? configValueCompletions[key] : undefined;
+  return Promise.resolve(values ?? []);
+}

package/src/interactive/dashboard.ts

@@ -0,0 +1,268 @@
+import { getAiProvider, getCurrentSprint } from '@src/store/config.ts';
+import { getSprint } from '@src/store/sprint.ts';
+import { getTasks } from '@src/store/task.ts';
+import { getPendingRequirements } from '@src/store/ticket.ts';
+import { colors, getQuoteForContext } from '@src/theme/index.ts';
+import { boxChars, emoji, formatSprintStatus, icons, progressBar } from '@src/theme/ui.ts';
+import type { Sprint, Tasks } from '@src/schemas/index.ts';
+
+// ============================================================================
+// STATUS DASHBOARD
+// ============================================================================
+
+export interface DashboardData {
+  sprint: Sprint;
+  tasks: Tasks;
+  approvedCount: number;
+  pendingCount: number;
+  blockedCount: number;
+  /** Number of tickets that have at least one associated task */
+  plannedTicketCount: number;
+  /** Current AI provider setting */
+  aiProvider: string | null;
+}
+
+/**
+ * Load dashboard data from the current sprint.
+ * Returns null if no current sprint is set.
+ */
+export async function loadDashboardData(): Promise<DashboardData | null> {
+  const sprintId = await getCurrentSprint();
+  if (!sprintId) return null;
+
+  try {
+    const sprint = await getSprint(sprintId);
+    const tasks = await getTasks(sprintId);
+
+    const pendingTickets = getPendingRequirements(sprint.tickets);
+    const pendingCount = pendingTickets.length;
+    const approvedCount = sprint.tickets.length - pendingCount;
+
+    // Count tasks that are blocked (not done, and have unresolved blockers)
+    const doneIds = new Set(tasks.filter((t) => t.status === 'done').map((t) => t.id));
+    const blockedCount = tasks.filter(
+      (t) => t.status !== 'done' && t.blockedBy.length > 0 && !t.blockedBy.every((id) => doneIds.has(id))
+    ).length;
+
+    // Count tickets that have at least one associated task
+    const ticketIdsWithTasks = new Set(tasks.map((t) => t.ticketId).filter(Boolean));
+    const plannedTicketCount = sprint.tickets.filter((t) => ticketIdsWithTasks.has(t.id)).length;
+
+    const aiProvider = await getAiProvider();
+
+    return { sprint, tasks, approvedCount, pendingCount, blockedCount, plannedTicketCount, aiProvider };
+  } catch {
+    return null;
+  }
+}
+
+export interface NextAction {
+  label: string;
+  description: string;
+  group: string;
+  subCommand: string;
+}
+
+/**
+ * Determine the suggested next action based on sprint state.
+ */
+export function getNextAction(data: DashboardData): NextAction | null {
+  const { sprint, tasks, pendingCount, approvedCount } = data;
+  const ticketCount = sprint.tickets.length;
+  const totalTasks = tasks.length;
+  const allDone = totalTasks > 0 && tasks.every((t) => t.status === 'done');
+
+  if (sprint.status === 'draft') {
+    if (ticketCount === 0) {
+      return { label: 'Add Ticket', description: 'No tickets yet', group: 'ticket', subCommand: 'add' };
+    }
+    if (pendingCount > 0) {
+      return {
+        label: 'Refine Requirements',
+        description: `${String(pendingCount)} ticket${pendingCount !== 1 ? 's' : ''} pending`,
+        group: 'sprint',
+        subCommand: 'refine',
+      };
+    }
+    if (approvedCount > 0 && totalTasks === 0) {
+      return { label: 'Plan Tasks', description: 'Requirements approved', group: 'sprint', subCommand: 'plan' };
+    }
+    // Draft with tasks but unplanned tickets — suggest re-plan
+    if (totalTasks > 0 && data.plannedTicketCount < ticketCount) {
+      const unplanned = ticketCount - data.plannedTicketCount;
+      return {
+        label: 'Re-Plan Tasks',
+        description: `${String(unplanned)} unplanned ticket${unplanned !== 1 ? 's' : ''}`,
+        group: 'sprint',
+        subCommand: 'plan',
+      };
+    }
+    if (totalTasks > 0) {
+      return {
+        label: 'Start Sprint',
+        description: `${String(totalTasks)} task${totalTasks !== 1 ? 's' : ''} ready`,
+        group: 'sprint',
+        subCommand: 'start',
+      };
+    }
+  }
+
+  if (sprint.status === 'active') {
+    if (allDone) {
+      return { label: 'Close Sprint', description: 'All tasks done', group: 'sprint', subCommand: 'close' };
+    }
+    return {
+      label: 'Continue Work',
+      description: `${String(totalTasks - tasks.filter((t) => t.status === 'done').length)} task${totalTasks - tasks.filter((t) => t.status === 'done').length !== 1 ? 's' : ''} remaining`,
+      group: 'sprint',
+      subCommand: 'start',
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Render a compact 2-3 line status header for display above the main menu.
+ * Returns an array of lines, or empty array if no data.
+ */
+export function renderStatusHeader(data: DashboardData | null): string[] {
+  if (!data) return [];
+
+  const { sprint, tasks, approvedCount, aiProvider } = data;
+  const totalTasks = tasks.length;
+  const ticketCount = sprint.tickets.length;
+
+  const lines: string[] = [];
+
+  // Line 1: sprint name, status, counts, provider
+  const sprintLabel = colors.highlight(sprint.name);
+  const statusBadge = formatSprintStatus(sprint.status);
+  const ticketPart = `${String(ticketCount)} ticket${ticketCount !== 1 ? 's' : ''}`;
+  const taskPart = `${String(totalTasks)} task${totalTasks !== 1 ? 's' : ''}`;
+  const providerPart = aiProvider === 'claude' ? 'Claude' : aiProvider === 'copilot' ? 'Copilot' : null;
+  const providerSuffix = providerPart ? `  |  ${providerPart}` : '';
+  lines.push(
+    `  ${icons.sprint} ${sprintLabel}  ${statusBadge}  ${colors.muted(`|  ${ticketPart}  |  ${taskPart}${providerSuffix}`)}`
+  );
+
+  // Line 2: task progress (active/closed) or refined/planned counts (draft)
+  if ((sprint.status === 'active' || sprint.status === 'closed') && totalTasks > 0) {
+    const doneCount = tasks.filter((t) => t.status === 'done').length;
+    const bar = progressBar(doneCount, totalTasks, { width: 15 });
+    const inProgressCount = tasks.filter((t) => t.status === 'in_progress').length;
+    const todoCount = tasks.filter((t) => t.status === 'todo').length;
+    lines.push(
+      `  ${bar}  ${colors.muted(`${String(doneCount)} done, ${String(inProgressCount)} active, ${String(todoCount)} todo`)}`
+    );
+  } else if (sprint.status === 'draft' && ticketCount > 0) {
+    const refinedColor = approvedCount === ticketCount ? colors.success : colors.warning;
+    const refinedPart = refinedColor(`Refined: ${String(approvedCount)}/${String(ticketCount)}`);
+    const plannedColor = data.plannedTicketCount === ticketCount ? colors.success : colors.muted;
+    const plannedPart = plannedColor(`Planned: ${String(data.plannedTicketCount)}/${String(ticketCount)}`);
+    lines.push(`  ${refinedPart}  ${colors.muted('|')}  ${plannedPart}`);
+  }
+
+  return lines;
+}
+
+/**
+ * Render the status dashboard showing current sprint info and task progress.
+ * Returns an array of lines to display.
+ */
+function renderDashboard(data: DashboardData): string[] {
+  const { sprint, tasks, approvedCount, blockedCount } = data;
+  const chars = boxChars.rounded;
+
+  const todoCount = tasks.filter((t) => t.status === 'todo').length;
+  const inProgressCount = tasks.filter((t) => t.status === 'in_progress').length;
+  const doneCount = tasks.filter((t) => t.status === 'done').length;
+  const totalTasks = tasks.length;
+  const ticketCount = sprint.tickets.length;
+
+  // Build content lines
+  const lines: string[] = [];
+
+  // Sprint info line
+  const sprintLabel = colors.highlight(sprint.name);
+  const statusBadge = formatSprintStatus(sprint.status);
+  lines.push(`  ${icons.sprint} ${sprintLabel}  ${statusBadge}`);
+
+  // Tickets & tasks summary
+  const ticketSummary = `${String(ticketCount)} ticket${ticketCount !== 1 ? 's' : ''}`;
+  const taskSummary = `${String(totalTasks)} task${totalTasks !== 1 ? 's' : ''}`;
+  lines.push(`  ${colors.muted(`${ticketSummary} ${chars.vertical} ${taskSummary}`)}`);
+
+  // Task progress bar
+  if (totalTasks > 0) {
+    const bar = progressBar(doneCount, totalTasks);
+    const detail = colors.muted(
+      `${String(doneCount)} done, ${String(inProgressCount)} active, ${String(todoCount)} todo`
+    );
+    lines.push(`  ${bar}  ${detail}`);
+  }
+
+  // Ticket requirement status (draft only — not relevant for active/closed)
+  if (sprint.status === 'draft' && ticketCount > 0) {
+    const refinedColor = approvedCount === ticketCount ? colors.success : colors.warning;
+    const refinedPart = refinedColor(`Refined: ${String(approvedCount)}/${String(ticketCount)}`);
+    const plannedColor = data.plannedTicketCount === ticketCount ? colors.success : colors.muted;
+    const plannedPart = plannedColor(`Planned: ${String(data.plannedTicketCount)}/${String(ticketCount)}`);
+    lines.push(`  ${refinedPart}  ${colors.muted('|')}  ${plannedPart}`);
+  }
+
+  // Blocked task alerts
+  if (blockedCount > 0) {
+    lines.push(
+      `  ${colors.warning(icons.warning)} ${colors.warning(`${String(blockedCount)} blocked task${blockedCount !== 1 ? 's' : ''}`)}`
+    );
+  }
+
+  // Next action suggestion
+  const nextAction = getNextAction(data);
+  if (nextAction) {
+    lines.push(
+      `  ${colors.muted(icons.tip)} ${colors.muted(nextAction.label + ':')} ${colors.highlight(nextAction.description)}`
+    );
+  }
+
+  return lines;
+}
+
+/**
+ * Render a friendly empty state when no sprint exists.
+ */
+function renderEmptyDashboard(): string[] {
+  const quote = getQuoteForContext('idle');
+  return [
+    `  ${emoji.donut}  ${colors.muted('No current sprint')}`,
+    `  ${colors.muted(`"${quote}"`)}`,
+    '',
+    `  ${colors.muted(icons.tip)} ${colors.muted('Get started:')}`,
+    `    ${colors.muted('1.')} ${colors.muted('Add a project:')}  ${colors.highlight('ralphctl project add')}`,
+    `    ${colors.muted('2.')} ${colors.muted('Create a sprint:')} ${colors.highlight('ralphctl sprint create')}`,
+  ];
+}
+
+/**
+ * Display the status dashboard.
+ * Shows current sprint info, task progress, and recent activity.
+ * Falls back to a friendly empty state when no sprint exists.
+ */
+export async function showDashboard(): Promise<void> {
+  const data = await loadDashboardData();
+
+  console.log('');
+  if (data) {
+    const lines = renderDashboard(data);
+    for (const line of lines) {
+      console.log(line);
+    }
+  } else {
+    const lines = renderEmptyDashboard();
+    for (const line of lines) {
+      console.log(line);
+    }
+  }
+  console.log('');
+}

package/src/interactive/escapable.ts

@@ -0,0 +1,81 @@
+import readline from 'node:readline';
+import { select } from '@inquirer/prompts';
+import { bold, dim } from 'colorette';
+
+type SelectConfig<Value> = Parameters<typeof select<Value>>[0];
+
+/**
+ * Default keysHelpTip renderer matching @inquirer/select's built-in format.
+ * Used as fallback when the caller doesn't provide a custom keysHelpTip.
+ */
+function defaultKeysHelpTip(keys: [string, string][]): string {
+  return keys.map(([key, action]) => `${bold(key)} ${dim(action)}`).join(dim(' \u2022 '));
+}
+
+/**
+ * Augment a select config's theme to append an "esc back" hint to the key help line.
+ */
+type KeysHelpTip = (keys: [string, string][]) => string | undefined;
+
+function withEscapeHint<Value>(config: SelectConfig<Value>, escLabel = 'back'): SelectConfig<Value> {
+  const originalTip = config.theme?.style?.keysHelpTip as KeysHelpTip | undefined;
+
+  return {
+    ...config,
+    theme: {
+      ...config.theme,
+      style: {
+        ...config.theme?.style,
+        keysHelpTip: (keys: [string, string][]) => {
+          const allKeys: [string, string][] = [...keys, ['esc', escLabel]];
+          return originalTip ? originalTip(allKeys) : defaultKeysHelpTip(allKeys);
+        },
+      },
+    },
+  };
+}
+
+/**
+ * Escape-aware wrapper around @inquirer/prompts select().
+ *
+ * Listens for the Escape key and aborts the prompt, returning null.
+ * Ctrl+C (ExitPromptError) propagates unchanged so callers can handle it.
+ * Appends an "esc <label>" hint to the bottom help line.
+ *
+ * Uses duck-typing for AbortPromptError to avoid depending on @inquirer/core directly.
+ *
+ * @param config - select prompt config
+ * @param options.escLabel - hint label shown next to "esc" (default: "back")
+ * @returns the selected value, or null if the user pressed Escape
+ */
+export async function escapableSelect<Value>(
+  config: SelectConfig<Value>,
+  options?: { escLabel?: string }
+): Promise<Value | null> {
+  const controller = new AbortController();
+
+  // Ensure stdin emits 'keypress' events (idempotent — safe to call multiple times)
+  readline.emitKeypressEvents(process.stdin);
+
+  const onKeypress = (_ch: string, key: { name: string } | undefined) => {
+    if (key?.name === 'escape') {
+      controller.abort();
+    }
+  };
+
+  process.stdin.on('keypress', onKeypress);
+
+  try {
+    const result = await select(withEscapeHint(config, options?.escLabel ?? 'back'), {
+      signal: controller.signal,
+    });
+    return result;
+  } catch (err) {
+    if (err instanceof Error && err.name === 'AbortPromptError') {
+      return null;
+    }
+    throw err;
+  } finally {
+    process.stdin.removeListener('keypress', onKeypress);
+  }
+}