ralphctl 0.1.0

package/src/interactive/wizard.ts

@@ -0,0 +1,221 @@
+import { confirm } from '@inquirer/prompts';
+import { colors } from '@src/theme/index.ts';
+import {
+  emoji,
+  icons,
+  log,
+  printHeader,
+  printSeparator,
+  progressBar,
+  showSuccess,
+  showWarning,
+} from '@src/theme/ui.ts';
+import { sprintCreateCommand } from '@src/commands/sprint/create.ts';
+import { addSingleTicketInteractive } from '@src/commands/ticket/add.ts';
+import { sprintRefineCommand } from '@src/commands/sprint/refine.ts';
+import { sprintPlanCommand } from '@src/commands/sprint/plan.ts';
+import { sprintStartCommand } from '@src/commands/sprint/start.ts';
+import { getCurrentSprint } from '@src/store/config.ts';
+import { getSprint } from '@src/store/sprint.ts';
+
+const TOTAL_STEPS = 5;
+
+/**
+ * Display a step progress indicator with a progress bar.
+ */
+function showStepProgress(step: number, title: string): void {
+  const bar = progressBar(step - 1, TOTAL_STEPS, { width: 10, showPercent: false });
+  log.newline();
+  printSeparator();
+  console.log(`  ${colors.highlight(`Step ${String(step)} of ${String(TOTAL_STEPS)}`)}  ${bar}  ${title}`);
+  log.newline();
+}
+
+/**
+ * Run the sprint setup wizard -- a multi-step guided flow that walks the user
+ * through creating a sprint, adding tickets, refining, planning, and starting.
+ */
+export async function runWizard(): Promise<void> {
+  try {
+    printHeader('Sprint Setup Wizard', emoji.donut);
+    log.dim('This wizard will guide you through setting up a new sprint.');
+    log.dim('You can skip optional steps along the way.');
+    log.newline();
+
+    // ── Step 1: Create Sprint ──────────────────────────────────────────────
+    showStepProgress(1, 'Create Sprint');
+
+    try {
+      await sprintCreateCommand({ interactive: true });
+    } catch (err) {
+      if (err instanceof Error) {
+        log.error(`Sprint creation failed: ${err.message}`);
+      }
+      log.newline();
+      showWarning('Cannot continue without a sprint. Wizard aborted.');
+      return;
+    }
+
+    const sprintId = await getCurrentSprint();
+    if (!sprintId) {
+      showWarning('No current sprint set. Wizard aborted.');
+      return;
+    }
+
+    // ── Step 2: Add Tickets ────────────────────────────────────────────────
+    showStepProgress(2, 'Add Tickets');
+
+    let ticketCount = 0;
+    let addMore = true;
+
+    while (addMore) {
+      try {
+        const ticket = await addSingleTicketInteractive({});
+        if (ticket) {
+          ticketCount++;
+        } else {
+          // No ticket created (no projects, or unrecoverable error) — exit loop
+          break;
+        }
+      } catch (err) {
+        if (err instanceof Error) {
+          log.error(`Failed to add ticket: ${err.message}`);
+        }
+      }
+
+      log.newline();
+      addMore = await confirm({
+        message: `${emoji.donut} Add another ticket?`,
+        default: true,
+      });
+    }
+
+    if (ticketCount === 0) {
+      log.newline();
+      showWarning('No tickets added. You can add them later with: ralphctl ticket add');
+    }
+
+    // ── Step 3: Refine Requirements ────────────────────────────────────────
+    showStepProgress(3, 'Refine Requirements');
+
+    if (ticketCount === 0) {
+      log.dim('Skipped -- no tickets to refine.');
+    } else {
+      const shouldRefine = await confirm({
+        message: `${emoji.donut} Refine requirements now?`,
+        default: true,
+      });
+
+      if (shouldRefine) {
+        try {
+          await sprintRefineCommand([]);
+        } catch (err) {
+          if (err instanceof Error) {
+            log.error(`Refinement failed: ${err.message}`);
+          }
+          log.dim('You can refine later with: ralphctl sprint refine');
+        }
+      } else {
+        log.dim('Skipped. You can refine later with: ralphctl sprint refine');
+      }
+    }
+
+    // ── Step 4: Plan Tasks ─────────────────────────────────────────────────
+    showStepProgress(4, 'Plan Tasks');
+
+    // Check if refinement was completed (all requirements approved)
+    let canPlan = false;
+    try {
+      const sprint = await getSprint(sprintId);
+      const hasTickets = sprint.tickets.length > 0;
+      const allApproved = hasTickets && sprint.tickets.every((t) => t.requirementStatus === 'approved');
+      canPlan = allApproved;
+
+      if (!hasTickets) {
+        log.dim('Skipped -- no tickets to plan.');
+      } else if (!allApproved) {
+        log.dim('Skipped -- not all requirements are approved yet.');
+        log.dim('Refine first with: ralphctl sprint refine');
+      }
+    } catch {
+      log.dim('Skipped -- could not read sprint state.');
+    }
+
+    if (canPlan) {
+      const shouldPlan = await confirm({
+        message: `${emoji.donut} Generate tasks now?`,
+        default: true,
+      });
+
+      if (shouldPlan) {
+        try {
+          await sprintPlanCommand([]);
+        } catch (err) {
+          if (err instanceof Error) {
+            log.error(`Planning failed: ${err.message}`);
+          }
+          log.dim('You can plan later with: ralphctl sprint plan');
+        }
+      } else {
+        log.dim('Skipped. You can plan later with: ralphctl sprint plan');
+      }
+    }
+
+    // ── Step 5: Start Execution ────────────────────────────────────────────
+    showStepProgress(5, 'Start Execution');
+
+    const shouldStart = await confirm({
+      message: `${emoji.donut} Start execution now?`,
+      default: false,
+    });
+
+    if (shouldStart) {
+      try {
+        // Note: sprintStartCommand may call process.exit() on completion
+        await sprintStartCommand([]);
+      } catch (err) {
+        if (err instanceof Error) {
+          log.error(`Execution failed: ${err.message}`);
+        }
+      }
+      return;
+    }
+
+    // ── Completion Summary ─────────────────────────────────────────────────
+    log.newline();
+    printSeparator();
+    showSuccess('Wizard complete!');
+    log.newline();
+
+    try {
+      const sprint = await getSprint(sprintId);
+      log.info(`Sprint "${sprint.name}" is ready.`);
+      log.item(`${icons.ticket}  ${String(sprint.tickets.length)} ticket(s)`);
+
+      const approvedCount = sprint.tickets.filter((t) => t.requirementStatus === 'approved').length;
+      if (sprint.tickets.length > 0) {
+        log.item(`${icons.success}  ${String(approvedCount)}/${String(sprint.tickets.length)} requirements approved`);
+      }
+    } catch {
+      // Sprint read failed, skip summary details
+    }
+
+    log.newline();
+    log.dim('Next steps:');
+    if (ticketCount === 0) {
+      log.item('ralphctl ticket add --project <name>');
+    }
+    log.item('ralphctl sprint refine');
+    log.item('ralphctl sprint plan');
+    log.item('ralphctl sprint start');
+    log.newline();
+  } catch (err) {
+    if ((err as Error).name === 'ExitPromptError') {
+      log.newline();
+      showWarning('Wizard cancelled');
+      log.newline();
+      return;
+    }
+    throw err;
+  }
+}

package/src/providers/claude.ts

@@ -0,0 +1,53 @@
+import type { ProviderAdapter, RateLimitInfo } from '@src/providers/types.ts';
+
+/**
+ * Claude Code CLI adapter.
+ *
+ * Maps to the `claude` binary with `--permission-mode acceptEdits`.
+ */
+export const claudeAdapter: ProviderAdapter = {
+  name: 'claude',
+  displayName: 'Claude',
+  binary: 'claude',
+  baseArgs: ['--permission-mode', 'acceptEdits'],
+
+  experimental: false,
+
+  buildInteractiveArgs(prompt: string, extraArgs: string[] = []): string[] {
+    return [...this.baseArgs, ...extraArgs, '--', prompt];
+  },
+
+  buildHeadlessArgs(extraArgs: string[] = []): string[] {
+    return ['-p', '--output-format', 'json', ...this.baseArgs, ...extraArgs];
+  },
+
+  parseJsonOutput(stdout: string): { result: string; sessionId: string | null } {
+    try {
+      const parsed = JSON.parse(stdout) as {
+        result?: string;
+        session_id?: string;
+      };
+      return {
+        result: parsed.result ?? stdout,
+        sessionId: parsed.session_id ?? null,
+      };
+    } catch {
+      return { result: stdout, sessionId: null };
+    }
+  },
+
+  detectRateLimit(stderr: string): RateLimitInfo {
+    const patterns = [/rate.?limit/i, /\b429\b/, /too many requests/i, /overloaded/i, /\b529\b/];
+    const isRateLimited = patterns.some((p) => p.test(stderr));
+    if (!isRateLimited) {
+      return { rateLimited: false, retryAfterMs: null };
+    }
+    const retryMatch = /retry.?after:?\s*(\d+)/i.exec(stderr);
+    const retryAfterMs = retryMatch?.[1] ? parseInt(retryMatch[1], 10) * 1000 : null;
+    return { rateLimited: true, retryAfterMs };
+  },
+
+  getSpawnEnv(): Record<string, string> {
+    return { CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: '1' };
+  },
+};

package/src/providers/copilot.ts

@@ -0,0 +1,86 @@
+import { lstat, readdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { ProviderAdapter, RateLimitInfo } from '@src/providers/types.ts';
+
+/**
+ * GitHub Copilot CLI adapter.
+ *
+ * Maps to the `copilot` binary with `--allow-all-tools`.
+ *
+ * Key differences from Claude Code CLI:
+ * - Interactive mode uses `-i PROMPT` (not `-- PROMPT`)
+ * - No `--output-format json`; uses `-s` (silent) for clean stdout
+ * - Headless output is plain text — session_id is not in stdout, but can be
+ *   captured via `--share` which writes `./copilot-session-<ID>.md` on exit
+ * - Requires `--autopilot` for autonomous continuation in headless mode
+ * - Requires `--no-ask-user` to suppress interactive prompts in headless mode
+ * - Status: public preview (experimental: true)
+ */
+export const copilotAdapter: ProviderAdapter = {
+  name: 'copilot',
+  displayName: 'Copilot',
+  binary: 'copilot',
+  experimental: true,
+  baseArgs: ['--allow-all-tools'],
+
+  buildInteractiveArgs(prompt: string, extraArgs: string[] = []): string[] {
+    return [...this.baseArgs, ...extraArgs, '-i', prompt];
+  },
+
+  buildHeadlessArgs(extraArgs: string[] = []): string[] {
+    // -p: execute prompt programmatically (exits after completion)
+    // -s: silent — output only the agent response (no usage stats)
+    // --autopilot: enable autonomous continuation without user intervention
+    // --no-ask-user: disable ask_user tool so agent doesn't block waiting for input
+    // --share: write session to ./copilot-session-<ID>.md so we can capture the session ID
+    return ['-p', '-s', '--autopilot', '--no-ask-user', '--share', ...this.baseArgs, ...extraArgs];
+  },
+
+  parseJsonOutput(stdout: string): { result: string; sessionId: string | null } {
+    // Copilot CLI outputs plain text (no JSON mode), so return as-is.
+    // Session ID is captured separately via extractSessionId (--share output file).
+    return { result: stdout.trim(), sessionId: null };
+  },
+
+  async extractSessionId(cwd: string): Promise<string | null> {
+    // --share writes ./copilot-session-<ID>.md in the CWD when the process exits.
+    // Glob for the file, extract the ID from the filename, then clean it up.
+    try {
+      const files = await readdir(cwd);
+      // Session ID must start with alphanumeric/underscore (not hyphen) to prevent argument injection
+      const shareFile = files.find((f) => /^copilot-session-[a-zA-Z0-9_][a-zA-Z0-9_-]*\.md$/.test(f));
+      if (!shareFile) return null;
+      const match = /^copilot-session-([a-zA-Z0-9_][a-zA-Z0-9_-]{0,127})\.md$/.exec(shareFile);
+      if (!match?.[1]) return null;
+      // Only delete regular files — refuse symlinks to prevent TOCTOU attacks
+      const filePath = join(cwd, shareFile);
+      const stat = await lstat(filePath).catch(() => null);
+      if (stat?.isFile()) {
+        await unlink(filePath).catch(() => {
+          // Best-effort cleanup — don't fail session ID capture if unlink fails
+        });
+      }
+      return match[1];
+    } catch {
+      return null;
+    }
+  },
+
+  detectRateLimit(stderr: string): RateLimitInfo {
+    // TODO: These patterns are borrowed from the Claude adapter and have not been validated
+    // against real Copilot CLI rate-limit error messages. If Copilot CLI produces different
+    // error output (e.g. GitHub API 429 responses), add patterns here based on real observations.
+    const patterns = [/rate.?limit/i, /\b429\b/, /too many requests/i, /overloaded/i, /\b529\b/];
+    const isRateLimited = patterns.some((p) => p.test(stderr));
+    if (!isRateLimited) {
+      return { rateLimited: false, retryAfterMs: null };
+    }
+    const retryMatch = /retry.?after:?\s*(\d+)/i.exec(stderr);
+    const retryAfterMs = retryMatch?.[1] ? parseInt(retryMatch[1], 10) * 1000 : null;
+    return { rateLimited: true, retryAfterMs };
+  },
+
+  getSpawnEnv(): Record<string, string> {
+    return {};
+  },
+};

package/src/providers/index.ts

@@ -0,0 +1,43 @@
+import type { AiProvider } from '@src/schemas/index.ts';
+import type { ProviderAdapter } from '@src/providers/types.ts';
+import { claudeAdapter } from '@src/providers/claude.ts';
+import { copilotAdapter } from '@src/providers/copilot.ts';
+import { resolveProvider } from '@src/utils/provider.ts';
+import { showWarning } from '@src/theme/ui.ts';
+
+export type { ProviderAdapter } from '@src/providers/types.ts';
+export type {
+  HeadlessSpawnOptions,
+  RateLimitInfo,
+  SpawnAsyncOptions,
+  SpawnInteractiveResult,
+  SpawnResult,
+  SpawnSyncOptions,
+} from '@src/providers/types.ts';
+
+/**
+ * Get the adapter for a specific provider.
+ */
+export function getProvider(provider: AiProvider): ProviderAdapter {
+  switch (provider) {
+    case 'claude':
+      return claudeAdapter;
+    case 'copilot':
+      return copilotAdapter;
+  }
+}
+
+/**
+ * Resolve the active provider from config (prompting on first use)
+ * and return its adapter.
+ *
+ * Prints a warning when the resolved provider is marked experimental.
+ */
+export async function getActiveProvider(): Promise<ProviderAdapter> {
+  const provider = await resolveProvider();
+  const adapter = getProvider(provider);
+  if (adapter.experimental) {
+    showWarning(`${adapter.displayName} provider is in public preview — some features may not work as expected.`);
+  }
+  return adapter;
+}

package/src/providers/types.ts

@@ -0,0 +1,85 @@
+import type { AiProvider } from '@src/schemas/index.ts';
+
+// ============================================================================
+// Spawn options & results (provider-agnostic)
+// ============================================================================
+
+export interface SpawnSyncOptions {
+  cwd: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+export interface SpawnAsyncOptions {
+  cwd: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+export interface HeadlessSpawnOptions extends SpawnAsyncOptions {
+  prompt?: string;
+  resumeSessionId?: string;
+}
+
+export interface SpawnResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  /** Session ID from CLI (available with --output-format json) */
+  sessionId: string | null;
+}
+
+export interface SpawnInteractiveResult {
+  code: number;
+  error?: string;
+}
+
+// ============================================================================
+// Rate limit detection
+// ============================================================================
+
+export interface RateLimitInfo {
+  rateLimited: boolean;
+  retryAfterMs: number | null;
+}
+
+// ============================================================================
+// Provider adapter interface
+// ============================================================================
+
+export interface ProviderAdapter {
+  readonly name: AiProvider;
+  readonly displayName: string;
+  readonly binary: string;
+
+  /** Base CLI args for permission/tool access. */
+  readonly baseArgs: string[];
+
+  /**
+   * Whether this provider is experimental (not fully stable).
+   * Copilot CLI is in public preview; Claude Code is GA.
+   */
+  readonly experimental: boolean;
+
+  /** Build args for interactive mode (inherits stdio). */
+  buildInteractiveArgs(prompt: string, extraArgs?: string[]): string[];
+
+  /** Build args for headless/print mode (captures stdout). */
+  buildHeadlessArgs(extraArgs?: string[]): string[];
+
+  /** Parse JSON output from --output-format json. */
+  parseJsonOutput(stdout: string): { result: string; sessionId: string | null };
+
+  /**
+   * Extract a session ID after a headless process completes.
+   * Called when parseJsonOutput returns sessionId: null.
+   * Copilot: parses the --share output file; Claude: not needed (JSON output has it).
+   */
+  extractSessionId?(cwd: string): Promise<string | null>;
+
+  /** Detect rate limit signals in stderr. */
+  detectRateLimit(stderr: string): RateLimitInfo;
+
+  /** Provider-specific env vars to set for a spawn. Claude-only example: CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD */
+  getSpawnEnv(): Record<string, string>;
+}

package/src/schemas/index.ts

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+
+// Sprint statuses (one-way transitions: draft → active → closed)
+export const SprintStatusSchema = z.enum(['draft', 'active', 'closed']);
+export type SprintStatus = z.infer<typeof SprintStatusSchema>;
+
+// Task statuses (kanban flow: todo → in_progress → done)
+export const TaskStatusSchema = z.enum(['todo', 'in_progress', 'done']);
+export type TaskStatus = z.infer<typeof TaskStatusSchema>;
+
+// Requirement status for tickets (pending → approved)
+export const RequirementStatusSchema = z.enum(['pending', 'approved']);
+export type RequirementStatus = z.infer<typeof RequirementStatusSchema>;
+
+// Repository schema (a single repository within a project)
+export const RepositorySchema = z.object({
+  name: z.string().min(1), // Auto-derived from basename(path)
+  path: z.string().min(1), // Absolute path
+  checkScript: z.string().optional(), // e.g., "pnpm install && pnpm typecheck && pnpm lint && pnpm test"
+});
+export type Repository = z.infer<typeof RepositorySchema>;
+
+// Project schema (multi-repo project definition)
+export const ProjectSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .regex(/^[a-z0-9-]+$/, 'Project name must be a slug (lowercase, numbers, hyphens only)'),
+  displayName: z.string().min(1),
+  repositories: z.array(RepositorySchema).min(1),
+  description: z.string().optional(),
+});
+export type Project = z.infer<typeof ProjectSchema>;
+
+// Projects array schema
+export const ProjectsSchema = z.array(ProjectSchema);
+export type Projects = z.infer<typeof ProjectsSchema>;
+
+// Ticket schema (ticket to be planned)
+export const TicketSchema = z.object({
+  id: z.string().min(1), // Internal UUID8 (auto-generated)
+  title: z.string().min(1),
+  description: z.string().optional(),
+  link: z.url().optional(),
+  projectName: z.string().min(1), // References Project.name
+  affectedRepositories: z.array(z.string()).optional(), // Repository paths selected during planning
+  requirementStatus: RequirementStatusSchema.default('pending'),
+  requirements: z.string().optional(), // Refined requirements (set during sprint refine)
+});
+export type Ticket = z.infer<typeof TicketSchema>;
+
+// Task schema
+export const TaskSchema = z.object({
+  id: z.string().min(1), // UUID8
+  name: z.string().min(1),
+  description: z.string().optional(),
+  steps: z.array(z.string()).default([]),
+  status: TaskStatusSchema.default('todo'),
+  order: z.number().int().positive(),
+  ticketId: z.string().optional(), // References Ticket.id (internal)
+  blockedBy: z.array(z.string()).default([]),
+  projectPath: z.string().min(1), // Single path for execution
+  verified: z.boolean().default(false), // Whether verification passed
+  verificationOutput: z.string().optional(), // Output from verification run
+});
+export type Task = z.infer<typeof TaskSchema>;
+
+// Tasks array schema
+export const TasksSchema = z.array(TaskSchema);
+export type Tasks = z.infer<typeof TasksSchema>;
+
+// Import task schema (for task import from CLI or planning)
+export const ImportTaskSchema = z.object({
+  id: z.string().optional(), // Local ID for referencing in blockedBy
+  name: z.string().min(1), // Required
+  description: z.string().optional(),
+  steps: z.array(z.string()).optional(),
+  ticketId: z.string().optional(),
+  blockedBy: z.array(z.string()).optional(),
+  projectPath: z.string().min(1), // Required - execution directory
+});
+export type ImportTask = z.infer<typeof ImportTaskSchema>;
+
+// Import tasks array schema
+export const ImportTasksSchema = z.array(ImportTaskSchema);
+export type ImportTasks = z.infer<typeof ImportTasksSchema>;
+
+// Refined requirement schema (for requirements refinement output)
+export const RefinedRequirementSchema = z.object({
+  ref: z.string().min(1),
+  requirements: z.string().min(1),
+});
+export type RefinedRequirement = z.infer<typeof RefinedRequirementSchema>;
+
+// Refined requirements array schema
+export const RefinedRequirementsSchema = z.array(RefinedRequirementSchema);
+export type RefinedRequirements = z.infer<typeof RefinedRequirementsSchema>;
+
+// Ideate output schema (combined requirements + tasks from sprint ideate)
+export const IdeateOutputSchema = z.object({
+  requirements: z.string().min(1),
+  tasks: ImportTasksSchema,
+});
+export type IdeateOutput = z.infer<typeof IdeateOutputSchema>;
+
+// Sprint schema (was Scope)
+export const SprintSchema = z.object({
+  id: z.string().regex(/^\d{8}-\d{6}-[a-z0-9-]+$/, 'Invalid sprint ID format'),
+  name: z.string().min(1),
+  status: SprintStatusSchema.default('draft'),
+  createdAt: z.iso.datetime(),
+  activatedAt: z.iso.datetime().nullable().default(null),
+  closedAt: z.iso.datetime().nullable().default(null),
+  tickets: z.array(TicketSchema).default([]),
+  checkRanAt: z.record(z.string(), z.iso.datetime()).default({}),
+  branch: z.string().nullable().default(null),
+});
+export type Sprint = z.infer<typeof SprintSchema>;
+
+// AI provider enum
+export const AiProviderSchema = z.enum(['claude', 'copilot']);
+export type AiProvider = z.infer<typeof AiProviderSchema>;
+
+// Config schema (root level configuration)
+export const ConfigSchema = z.object({
+  currentSprint: z.string().nullable().default(null),
+  aiProvider: AiProviderSchema.nullable().default(null),
+  editor: z.string().nullable().default(null),
+});
+export type Config = z.infer<typeof ConfigSchema>;

package/src/store/config.ts

@@ -0,0 +1,74 @@
+import { getConfigPath } from '@src/utils/paths.ts';
+import { fileExists, readValidatedJson, writeValidatedJson } from '@src/utils/storage.ts';
+import { type AiProvider, type Config, ConfigSchema } from '@src/schemas/index.ts';
+
+const DEFAULT_CONFIG: Config = {
+  currentSprint: null,
+  aiProvider: null,
+  editor: null,
+};
+
+export async function getConfig(): Promise<Config> {
+  const configPath = getConfigPath();
+  if (!(await fileExists(configPath))) {
+    return DEFAULT_CONFIG;
+  }
+  return readValidatedJson(configPath, ConfigSchema);
+}
+
+export async function saveConfig(config: Config): Promise<void> {
+  await writeValidatedJson(getConfigPath(), config, ConfigSchema);
+}
+
+/**
+ * Get the current sprint ID (which sprint commands target).
+ */
+export async function getCurrentSprint(): Promise<string | null> {
+  const config = await getConfig();
+  return config.currentSprint;
+}
+
+/**
+ * Set the current sprint ID.
+ */
+export async function setCurrentSprint(sprintId: string | null): Promise<void> {
+  const config = await getConfig();
+  config.currentSprint = sprintId;
+  await saveConfig(config);
+}
+
+/**
+ * Get the configured AI provider (claude or copilot).
+ * Returns null if not yet configured (first-run).
+ */
+export async function getAiProvider(): Promise<AiProvider | null> {
+  const config = await getConfig();
+  return config.aiProvider ?? null;
+}
+
+/**
+ * Set the AI provider.
+ */
+export async function setAiProvider(provider: AiProvider): Promise<void> {
+  const config = await getConfig();
+  config.aiProvider = provider;
+  await saveConfig(config);
+}
+
+/**
+ * Get the configured editor command (e.g., "subl -w", "code --wait", "vim").
+ * Returns null if not yet configured (first-run).
+ */
+export async function getEditor(): Promise<string | null> {
+  const config = await getConfig();
+  return config.editor ?? null;
+}
+
+/**
+ * Set the editor command.
+ */
+export async function setEditor(editor: string): Promise<void> {
+  const config = await getConfig();
+  config.editor = editor;
+  await saveConfig(config);
+}