ralph-review 0.2.2 → 0.2.3

package/src/commands/config-model.ts

@@ -8,6 +8,7 @@ import {
   isAgentType,
   isReasoningLevel,
   type ReasoningLevel,
+  type RetryOverrideConfig,
 } from "@/lib/types";
 
 type ConfigRole = "reviewer" | "fixer";
@@ -116,6 +117,40 @@ function parseInteger(value: string, key: ConfigKey): number {
   return parsed;
 }
 
+function parseBoundedIntegerUpdate(
+  key: ParsedScalarConfigUpdate["key"],
+  rawValue: string,
+  minimum: number
+): ParsedScalarConfigUpdate {
+  const parsed = parseInteger(requireNonNullRawValue(key, rawValue), key);
+  if (parsed < minimum) {
+    throw new Error(`Value for "${key}" must be greater than or equal to ${minimum}.`);
+  }
+  return { key, value: parsed } as ParsedScalarConfigUpdate;
+}
+
+function requireNumberConfigValue(key: ConfigKey, value: ConfigValue, requirement: string): number {
+  if (typeof value === "number") {
+    return value;
+  }
+
+  throw new Error(`Value for "${key}" must be an integer ${requirement}.`);
+}
+
+function requirePiRoleSettings<T extends AgentSettings | AgentOverrideSettings>(
+  current: T | undefined,
+  role: ConfigRole,
+  command: string
+): T {
+  if (!current || current.agent !== "pi") {
+    throw new Error(
+      `Cannot set "${role}.agent" to "pi" in a single-key update. Run "${command}" for pi setup.`
+    );
+  }
+
+  return current;
+}
+
 function requireNonNullRawValue(key: ConfigKey, rawValue: string): string {
   if (rawValue === "null") {
     throw new Error(`Value "null" is not allowed for "${key}".`);
@@ -205,36 +240,20 @@ export function parseConfigUpdate(key: ConfigKey, rawValue: string): ParsedConfi
       return createRoleReasoningUpdate(key, rawValue);
 
     case "maxIterations": {
-      const parsed = parseInteger(requireNonNullRawValue(key, rawValue), key);
-      if (parsed <= 0) {
-        throw new Error(`Value for "${key}" must be greater than 0.`);
-      }
-      return { key, value: parsed };
+      return parseBoundedIntegerUpdate(key, rawValue, 1);
     }
 
     case "iterationTimeout": {
-      const parsed = parseInteger(requireNonNullRawValue(key, rawValue), key);
-      if (parsed <= 0) {
-        throw new Error(`Value for "${key}" must be greater than 0.`);
-      }
-      return { key, value: parsed };
+      return parseBoundedIntegerUpdate(key, rawValue, 1);
     }
 
     case "retry.maxRetries": {
-      const parsed = parseInteger(requireNonNullRawValue(key, rawValue), key);
-      if (parsed < 0) {
-        throw new Error(`Value for "${key}" must be greater than or equal to 0.`);
-      }
-      return { key, value: parsed };
+      return parseBoundedIntegerUpdate(key, rawValue, 0);
     }
 
     case "retry.baseDelayMs":
     case "retry.maxDelayMs": {
-      const parsed = parseInteger(requireNonNullRawValue(key, rawValue), key);
-      if (parsed <= 0) {
-        throw new Error(`Value for "${key}" must be greater than 0.`);
-      }
-      return { key, value: parsed };
+      return parseBoundedIntegerUpdate(key, rawValue, 1);
     }
 
     case "defaultReview.type":
@@ -329,18 +348,9 @@ function ensureRoleForMutation(
 function applyRoleAgentUpdate(config: Config, role: ConfigRole, nextAgent: AgentType): Config {
   const current = readRoleSettings(role, config);
   if (nextAgent === "pi") {
-    if (!current || current.agent !== "pi") {
-      throw new Error(
-        `Cannot set "${role}.agent" to "pi" in a single-key update. Run "rr init" for pi setup.`
-      );
-    }
+    const piSettings = requirePiRoleSettings(current, role, "rr init");
 
-    writeRoleSettings(role, config, {
-      agent: "pi",
-      provider: current.provider,
-      model: current.model,
-      reasoning: current.reasoning,
-    });
+    writeRoleSettings(role, config, piSettings);
     return config;
   }
 
@@ -362,6 +372,86 @@ function applyRoleAgentUpdate(config: Config, role: ConfigRole, nextAgent: Agent
   return config;
 }
 
+function setRequiredRetryValue(
+  config: Config,
+  field: keyof typeof DEFAULT_RETRY_CONFIG,
+  value: number
+): void {
+  config.retry = config.retry ? { ...config.retry } : { ...DEFAULT_RETRY_CONFIG };
+  config.retry[field] = value;
+}
+
+function setOverrideRetryValue(
+  config: ConfigOverride,
+  field: keyof RetryOverrideConfig,
+  value: number
+): void {
+  config.retry = {
+    ...(config.retry && config.retry !== null ? config.retry : {}),
+    [field]: value,
+  };
+}
+
+function applyRoleProviderUpdate(
+  settings: AgentSettings | AgentOverrideSettings,
+  role: ConfigRole,
+  key: RoleConfigKey,
+  value: ConfigValue,
+  clearNonPiProvider: boolean
+): void {
+  if (value === null) {
+    if (settings.agent !== "pi") {
+      if (clearNonPiProvider) {
+        delete settings.provider;
+      }
+      return;
+    }
+    throw new Error(`Cannot unset "${role}.provider" while "${role}.agent" is "pi".`);
+  }
+
+  if (typeof value !== "string") {
+    throw new Error(`Value for "${key}" must be a string or null.`);
+  }
+
+  if (settings.agent !== "pi") {
+    throw new Error(`"${role}.provider" is only valid when "${role}.agent" is "pi".`);
+  }
+
+  settings.provider = value;
+}
+
+function applyRoleModelUpdate(
+  settings: AgentSettings | AgentOverrideSettings,
+  role: ConfigRole,
+  key: RoleConfigKey,
+  value: ConfigValue,
+  assignNullForNonPi: boolean
+): void {
+  if (settings.agent === "pi") {
+    if (value === null || typeof value !== "string") {
+      throw new Error(`Cannot unset "${role}.model" while "${role}.agent" is "pi".`);
+    }
+    settings.model = value;
+    return;
+  }
+
+  if (value === null) {
+    if (assignNullForNonPi) {
+      settings.model = value;
+      return;
+    }
+    delete settings.model;
+    return;
+  }
+
+  if (typeof value === "string") {
+    settings.model = value;
+    return;
+  }
+
+  throw new Error(`Value for "${key}" must be a string or null.`);
+}
+
 export function setConfigValue(config: Config, key: ConfigKey, value: ConfigValue): Config {
   const next = structuredClone(config) as Config;
 
@@ -385,49 +475,12 @@ export function setConfigValue(config: Config, key: ConfigKey, value: ConfigValu
     const settings = ensureRoleForMutation(next, role, field);
 
     if (field === "provider") {
-      if (value === null) {
-        if (settings.agent !== "pi") {
-          return next;
-        }
-        throw new Error(`Cannot unset "${role}.provider" while "${role}.agent" is "pi".`);
-      }
-      if (typeof value !== "string") {
-        throw new Error(`Value for "${key}" must be a string or null.`);
-      }
-      if (settings.agent !== "pi") {
-        throw new Error(`"${role}.provider" is only valid when "${role}.agent" is "pi".`);
-      }
-      settings.provider = value;
+      applyRoleProviderUpdate(settings, role, key as RoleConfigKey, value, false);
       return next;
     }
 
     if (field === "model") {
-      if (settings.agent === "pi") {
-        if (value === null || typeof value !== "string") {
-          throw new Error(`Cannot unset "${role}.model" while "${role}.agent" is "pi".`);
-        }
-        settings.model = value;
-        return next;
-      }
-
-      if (value === null) {
-        delete settings.model;
-      } else if (typeof value === "string") {
-        settings.model = value;
-      } else {
-        throw new Error(`Value for "${key}" must be a string or null.`);
-      }
-      return next;
-    }
-
-    if (settings.agent === "pi") {
-      if (value === null) {
-        delete settings.reasoning;
-      } else if (typeof value === "string" && isReasoningLevel(value)) {
-        settings.reasoning = value;
-      } else {
-        throw new Error(`Value for "${key}" must be one of: low, medium, high, xhigh, max.`);
-      }
+      applyRoleModelUpdate(settings, role, key as RoleConfigKey, value, false);
       return next;
     }
 
@@ -479,25 +532,25 @@ export function setConfigValue(config: Config, key: ConfigKey, value: ConfigValu
       next.defaultReview = { type: "base", branch: value };
       return next;
     case "retry.maxRetries":
-      next.retry = next.retry ? { ...next.retry } : { ...DEFAULT_RETRY_CONFIG };
-      if (typeof value !== "number") {
-        throw new Error(`Value for "${key}" must be an integer greater than or equal to 0.`);
-      }
-      next.retry.maxRetries = value;
+      setRequiredRetryValue(
+        next,
+        "maxRetries",
+        requireNumberConfigValue(key, value, "greater than or equal to 0")
+      );
       return next;
     case "retry.baseDelayMs":
-      next.retry = next.retry ? { ...next.retry } : { ...DEFAULT_RETRY_CONFIG };
-      if (typeof value !== "number") {
-        throw new Error(`Value for "${key}" must be an integer greater than 0.`);
-      }
-      next.retry.baseDelayMs = value;
+      setRequiredRetryValue(
+        next,
+        "baseDelayMs",
+        requireNumberConfigValue(key, value, "greater than 0")
+      );
       return next;
     case "retry.maxDelayMs":
-      next.retry = next.retry ? { ...next.retry } : { ...DEFAULT_RETRY_CONFIG };
-      if (typeof value !== "number") {
-        throw new Error(`Value for "${key}" must be an integer greater than 0.`);
-      }
-      next.retry.maxDelayMs = value;
+      setRequiredRetryValue(
+        next,
+        "maxDelayMs",
+        requireNumberConfigValue(key, value, "greater than 0")
+      );
       return next;
     case "notifications.sound.enabled":
       if (typeof value !== "boolean") {
@@ -552,17 +605,13 @@ function applyOverrideRoleAgentUpdate(
 ): ConfigOverride {
   const current = readOverrideRoleSettings(role, config);
   if (nextAgent === "pi") {
-    if (!current || current.agent !== "pi") {
-      throw new Error(
-        `Cannot set "${role}.agent" to "pi" in a single-key update. Run "rr init --local" for pi setup.`
-      );
-    }
+    const piSettings = requirePiRoleSettings(current, role, "rr init --local");
 
     writeOverrideRoleSettings(role, config, {
       agent: "pi",
-      provider: current.provider,
-      model: current.model,
-      reasoning: current.reasoning,
+      provider: piSettings.provider,
+      model: piSettings.model,
+      reasoning: piSettings.reasoning,
     });
     return config;
   }
@@ -600,30 +649,12 @@ export function setConfigOverrideValue(
     const settings = ensureOverrideRoleForMutation(next, role);
 
     if (field === "provider") {
-      if (value === null) {
-        if (settings.agent !== "pi") {
-          delete settings.provider;
-          return next;
-        }
-        throw new Error(`Cannot unset "${role}.provider" while "${role}.agent" is "pi".`);
-      }
-      if (settings.agent !== "pi") {
-        throw new Error(`"${role}.provider" is only valid when "${role}.agent" is "pi".`);
-      }
-      settings.provider = value;
+      applyRoleProviderUpdate(settings, role, update.key, value, true);
       return next;
     }
 
     if (field === "model") {
-      if (settings.agent === "pi") {
-        if (value === null) {
-          throw new Error(`Cannot unset "${role}.model" while "${role}.agent" is "pi".`);
-        }
-        settings.model = value;
-        return next;
-      }
-
-      settings.model = value;
+      applyRoleModelUpdate(settings, role, update.key, value, true);
       return next;
     }
 
@@ -657,22 +688,13 @@ export function setConfigOverrideValue(
       next.defaultReview = { type: "base", branch: update.value };
       return next;
     case "retry.maxRetries":
-      next.retry = {
-        ...(next.retry && next.retry !== null ? next.retry : {}),
-        maxRetries: update.value,
-      };
+      setOverrideRetryValue(next, "maxRetries", update.value);
       return next;
     case "retry.baseDelayMs":
-      next.retry = {
-        ...(next.retry && next.retry !== null ? next.retry : {}),
-        baseDelayMs: update.value,
-      };
+      setOverrideRetryValue(next, "baseDelayMs", update.value);
       return next;
     case "retry.maxDelayMs":
-      next.retry = {
-        ...(next.retry && next.retry !== null ? next.retry : {}),
-        maxDelayMs: update.value,
-      };
+      setOverrideRetryValue(next, "maxDelayMs", update.value);
       return next;
     case "notifications.sound.enabled":
       next.notifications = {

package/src/commands/doctor.ts

@@ -1,4 +1,5 @@
 import * as p from "@clack/prompts";
+import type { SpinnerFactory } from "@/cli-io";
 import { runDiagnostics } from "@/lib/diagnostics";
 import type { FixResult, RemediationDependencies } from "@/lib/diagnostics/remediation";
 import { applyFixes as defaultApplyFixes, isFixable } from "@/lib/diagnostics/remediation";
@@ -17,10 +18,7 @@ interface DoctorRuntime {
   ) => Promise<FixResult[]>;
   intro: (message: string) => void;
   note: (message: string, title: string) => void;
-  spinner: () => {
-    start: (message: string) => void;
-    stop: (message: string) => void;
-  };
+  spinner: SpinnerFactory;
   log: {
     error: (message: string) => void;
     warn: (message: string) => void;

package/src/commands/fix.ts

@@ -12,7 +12,10 @@ import {
 } from "@/lib/priority-list";
 import { loadFindingsArtifactBySessionId } from "@/lib/review-workflow/findings/artifact";
 import type { FindingId, FindingsArtifact } from "@/lib/review-workflow/findings/types";
-import { runFixSession } from "@/lib/review-workflow/remediation/run-fix-session";
+import {
+  promptForFixSelection,
+  runFixSession,
+} from "@/lib/review-workflow/remediation/run-fix-session";
 import {
   createSessionState,
   HEARTBEAT_INTERVAL_MS,
@@ -67,30 +70,19 @@ export interface FixCommandDeps {
   exit: (code: number) => void;
 }
 
-function defaultPromptForSelection(artifact: FindingsArtifact): Promise<FindingId[] | null> {
-  return p
-    .multiselect({
-      message: "Choose findings to fix",
-      options: artifact.findings.map((finding) => ({
-        value: finding.id,
-        label: `${finding.id} [${finding.priority}] ${finding.title}`,
-        hint: `${finding.filePath}:${finding.startLine}-${finding.endLine}`,
-      })),
-      required: false,
-    })
-    .then((selection) => {
-      if (p.isCancel(selection)) {
-        return null;
-      }
+interface LoadedFixArtifact {
+  parsed: ParsedFixCommandOptions;
+  artifact: FindingsArtifact;
+}
 
-      return (selection as FindingId[]) ?? [];
-    });
+interface PreparedFixCommand extends LoadedFixArtifact {
+  commandDeps: FixCommandDeps;
 }
 
 const DEFAULT_FIX_COMMAND_DEPS: FixCommandDeps = {
   loadConfig: loadEffectiveConfig,
   loadFindingsArtifactBySessionId,
-  promptForSelection: defaultPromptForSelection,
+  promptForSelection: promptForFixSelection,
   runFixSession,
   isTTY: () => process.stdout.isTTY === true,
   isTmuxInstalled,
@@ -332,31 +324,69 @@ export function parseFixCommandOptions(args: string[]): ParsedFixCommandOptions
   };
 }
 
-export async function runFix(
-  args: string[] = [],
-  deps: Partial<FixCommandDeps> = {}
-): Promise<void> {
-  const commandDeps = { ...DEFAULT_FIX_COMMAND_DEPS, ...deps };
-
+async function loadFixCommandArtifact(
+  args: string[],
+  commandDeps: FixCommandDeps
+): Promise<LoadedFixArtifact | null> {
   let parsed: ParsedFixCommandOptions;
   try {
     parsed = parseFixCommandOptions(args);
   } catch (error) {
     commandDeps.logError(`${error}`);
     commandDeps.exit(1);
-    return;
+    return null;
   }
 
   const artifact = await commandDeps.loadFindingsArtifactBySessionId(CONFIG_DIR, parsed.sessionId);
   if (!artifact) {
     commandDeps.logError(`Findings artifact not found for session ${parsed.sessionId}`);
     commandDeps.exit(1);
+    return null;
+  }
+
+  return { parsed, artifact };
+}
+
+async function prepareFixCommand(
+  args: string[],
+  deps: Partial<FixCommandDeps>
+): Promise<PreparedFixCommand | null> {
+  const commandDeps = { ...DEFAULT_FIX_COMMAND_DEPS, ...deps };
+  const loaded = await loadFixCommandArtifact(args, commandDeps);
+  return loaded ? { commandDeps, ...loaded } : null;
+}
+
+async function withPreparedFixCommand(
+  args: string[],
+  deps: Partial<FixCommandDeps>,
+  run: (prepared: PreparedFixCommand) => Promise<void>
+): Promise<void> {
+  const prepared = await prepareFixCommand(args, deps);
+  if (!prepared) {
     return;
   }
 
-  if (!(await commandDeps.loadConfig(artifact.projectPath))) {
+  await run(prepared);
+}
+
+async function loadRequiredFixConfig(
+  commandDeps: FixCommandDeps,
+  projectPath: string
+): ReturnType<FixCommandDeps["loadConfig"]> {
+  const config = await commandDeps.loadConfig(projectPath);
+  if (!config) {
     commandDeps.logError("Failed to load configuration");
     commandDeps.exit(1);
+  }
+  return config;
+}
+
+async function runPreparedFix({
+  commandDeps,
+  parsed,
+  artifact,
+}: PreparedFixCommand): Promise<void> {
+  if (!(await loadRequiredFixConfig(commandDeps, artifact.projectPath))) {
     return;
   }
 
@@ -423,33 +453,18 @@ export async function runFix(
   }
 }
 
-export async function runFixForeground(
-  args: string[] = [],
-  deps: Partial<FixCommandDeps> = {}
-): Promise<void> {
-  const commandDeps = { ...DEFAULT_FIX_COMMAND_DEPS, ...deps };
-
-  let parsed: ParsedFixCommandOptions;
-  try {
-    parsed = parseFixCommandOptions(args);
-  } catch (error) {
-    commandDeps.logError(`${error}`);
-    commandDeps.exit(1);
-    return;
-  }
-
-  const artifact = await commandDeps.loadFindingsArtifactBySessionId(CONFIG_DIR, parsed.sessionId);
-  if (!artifact) {
-    commandDeps.logError(`Findings artifact not found for session ${parsed.sessionId}`);
-    commandDeps.exit(1);
-    return;
-  }
+export function runFix(args: string[] = [], deps: Partial<FixCommandDeps> = {}): Promise<void> {
+  return withPreparedFixCommand(args, deps, runPreparedFix);
+}
 
+async function runPreparedFixForeground({
+  commandDeps,
+  parsed,
+  artifact,
+}: PreparedFixCommand): Promise<void> {
   const projectPath = commandDeps.env.RR_PROJECT_PATH || artifact.projectPath || commandDeps.cwd();
-  const config = await commandDeps.loadConfig(projectPath);
+  const config = await loadRequiredFixConfig(commandDeps, projectPath);
   if (!config) {
-    commandDeps.logError("Failed to load configuration");
-    commandDeps.exit(1);
     return;
   }
 
@@ -593,3 +608,10 @@ export async function runFixForeground(
     });
   }
 }
+
+export function runFixForeground(
+  args: string[] = [],
+  deps: Partial<FixCommandDeps> = {}
+): Promise<void> {
+  return withPreparedFixCommand(args, deps, runPreparedFixForeground);
+}

package/src/commands/handoff-selection.ts

@@ -2,6 +2,10 @@ import * as p from "@clack/prompts";
 import type { PendingHandoffArtifact } from "@/lib/handoff";
 
 type HandoffAction = "apply" | "discard";
+type HandoffSelect = (input: {
+  message: string;
+  options: Array<{ value: string; label: string; hint: string }>;
+}) => Promise<unknown>;
 
 interface SelectableHandoff {
   handoffId: string;
@@ -14,10 +18,7 @@ interface ResolvePendingHandoffSelectionOptions {
   selector?: string;
   action: HandoffAction;
   isTTY: boolean;
-  select?: (input: {
-    message: string;
-    options: Array<{ value: string; label: string; hint: string }>;
-  }) => Promise<unknown>;
+  select?: HandoffSelect;
   isCancel?: (value: unknown) => boolean;
 }
 
@@ -105,10 +106,7 @@ async function resolveHandoffSelection<T extends SelectableHandoff>(options: {
   action: HandoffAction;
   isTTY: boolean;
   multipleHandoffsMessage: string;
-  select?: (input: {
-    message: string;
-    options: Array<{ value: string; label: string; hint: string }>;
-  }) => Promise<unknown>;
+  select?: HandoffSelect;
   isCancel?: (value: unknown) => boolean;
 }): Promise<HandoffSelectionResult<T>> {
   if (options.selector) {

package/src/commands/interactive-deps.ts

@@ -0,0 +1,18 @@
+import * as p from "@clack/prompts";
+import { getCommandDef } from "@/cli";
+
+export interface InteractiveCommandDeps {
+  getCommandDef: typeof getCommandDef;
+  logError: (message: string) => void;
+  exit: (code: number) => void;
+  isTTY: () => boolean;
+}
+
+export function createInteractiveCommandDeps(): InteractiveCommandDeps {
+  return {
+    getCommandDef,
+    logError: (message) => p.log.error(message),
+    exit: (code) => process.exit(code),
+    isTTY: () => process.stdout.isTTY === true,
+  };
+}

package/src/commands/log.ts

@@ -82,6 +82,16 @@ function isUnknownEmptySession(session: SessionStats): boolean {
   return session.status === "unknown" && session.iterations === 0;
 }
 
+function printNoProjectSessions(projectName: string, json: boolean): void {
+  if (json) {
+    console.log(JSON.stringify({ project: projectName, sessions: [] }, null, 2));
+    return;
+  }
+
+  p.log.info("No review sessions found for current working directory.");
+  p.log.message('Start a review with "rr run" first.');
+}
+
 function formatDate(timestamp: number): string {
   return new Date(timestamp).toLocaleString();
 }
@@ -412,12 +422,7 @@ export async function runLog(args: string[]): Promise<void> {
   const projectSessions = await listProjectLogSessions(CONFIG_DIR, currentProjectPath);
 
   if (projectSessions.length === 0) {
-    if (options.json) {
-      console.log(JSON.stringify({ project: projectName, sessions: [] }, null, 2));
-    } else {
-      p.log.info("No review sessions found for current working directory.");
-      p.log.message('Start a review with "rr run" first.');
-    }
+    printNoProjectSessions(projectName, options.json);
     return;
   }
 
@@ -451,12 +456,7 @@ export async function runLog(args: string[]): Promise<void> {
   }
 
   if (sessionStats.length === 0) {
-    if (options.json) {
-      console.log(JSON.stringify({ project: projectName, sessions: [] }, null, 2));
-    } else {
-      p.log.info("No review sessions found for current working directory.");
-      p.log.message('Start a review with "rr run" first.');
-    }
+    printNoProjectSessions(projectName, options.json);
     return;
   }