ralph-review 0.1.6 → 0.1.8

package/README.md

@@ -136,6 +136,9 @@ brew install kenryu42/tap/ralph-review
 
 # npm (install or update)
 npm install -g ralph-review
+
+# Or let ralph-review detect the install method and update itself
+rr update
 ```
 
 ---
@@ -159,6 +162,7 @@ rrr
 
 | Command | Description |
 |---------|-------------|
+| `rr` | Interactive Mode |
 | `rr init` | Configure reviewer, fixer, and simplifier agents (auto-detects installed CLIs) |
 | `rr run` | Start review cycle in a tmux session |
 | `rr run --base main` | Review changes against a base branch |
@@ -169,14 +173,18 @@ rrr
 | `rr config show` | Print full configuration |
 | `rr config set KEY VAL` | Update a config value (e.g. `rr config set maxIterations 8`) |
 | `rr list` | List active review sessions |
-| `rr status` | Show current review status |
 | `rr stop` | Stop running review session (`--all` to stop all) |
 | `rr log` | View review logs (`-n 5` for last 5, `--json` for JSON output) |
 | `rr dashboard` | Open review dashboard in browser |
 | `rr doctor` | Run environment and configuration diagnostics (`--fix` to auto-resolve) |
+| `rr update` | Check for and install a newer `ralph-review` version |
 
 The `rrr` command is a shorthand alias for `rr run` -- all flags work the same.
 
+For update checks without installing, run `rr update --check`. If install-source detection is
+ambiguous, force the package manager with `rr update --manager npm` or
+`rr update --manager brew`.
+
 ---
 
 ## Supported Coding Agents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-review",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Orchestrating coding agents for code review, verification and fixing via the ralph loop.",
   "license": "MIT",
   "type": "module",

package/src/cli-core.ts

@@ -81,18 +81,18 @@ export const COMMANDS: CommandDef[] = [
         description: "Disable finish sound for this run (override config)",
       },
       {
-        name: "watch",
+        name: "interactive",
         type: "boolean",
-        description: "Open Session Panel after starting the run (override config)",
+        description: "Launch Interactive Mode after starting the run (override config)",
       },
       {
-        name: "no-watch",
+        name: "no-interactive",
         type: "boolean",
-        description: "Start run without opening Session Panel (override config)",
+        description: "Start run without launching Interactive Mode (override config)",
       },
       SIMPLIFIER_OPTION,
     ],
-    examples: ["rr run", "rr run --base main", "rr run --no-watch"],
+    examples: ["rr run", "rr run --base main", "rr run --no-interactive"],
   },
   {
     name: "list",
@@ -104,6 +104,7 @@ export const COMMANDS: CommandDef[] = [
     name: "status",
     description: "Show review status",
     examples: ["rr status"],
+    hidden: true,
   },
   {
     name: "stop",
@@ -150,6 +151,29 @@ export const COMMANDS: CommandDef[] = [
     ],
     examples: ["rr doctor", "rr doctor --fix"],
   },
+  {
+    name: "update",
+    description: "Check for and install a newer ralph-review version",
+    options: [
+      {
+        name: "check",
+        type: "boolean",
+        description: "Check for an update without installing it",
+      },
+      {
+        name: "manager",
+        type: "string",
+        placeholder: "npm|brew",
+        description: "Override install-source detection",
+      },
+    ],
+    examples: [
+      "rr update",
+      "rr update --check",
+      "rr update --manager npm",
+      "rr update --manager brew",
+    ],
+  },
   {
     name: "_run-foreground",
     description: "Internal: run review cycle in tmux foreground",

package/src/cli.ts

@@ -11,6 +11,7 @@ import { runLog } from "./commands/log";
 import { runForeground, startReview } from "./commands/run";
 import { runStatus } from "./commands/status";
 import { runStop } from "./commands/stop";
+import { runUpdate } from "./commands/update";
 import { CliError, type CommandDef, parseCommand } from "./lib/cli-parser";
 
 export {
@@ -41,6 +42,8 @@ export interface CliDeps {
   runDashboard: typeof runDashboard;
   runDoctor: typeof runDoctor;
   runList: typeof runList;
+  runUpdate: typeof runUpdate;
+  isInteractiveTerminal: () => boolean;
   log: (message: string) => void;
   logError: (message: string) => void;
   logMessage: (message: string) => void;
@@ -51,6 +54,8 @@ const CONSOLE_LOG = console.log.bind(console) as (message: string) => void;
 const CLACK_ERROR = p.log.error.bind(p.log) as (message: string) => void;
 const CLACK_MESSAGE = p.log.message.bind(p.log) as (message: string) => void;
 const PROCESS_EXIT = process.exit.bind(process) as (code: number) => void;
+const IS_INTERACTIVE_TERMINAL = (): boolean =>
+  process.stdin.isTTY === true && process.stdout.isTTY === true;
 
 const DEFAULT_CLI_DEPS: CliDeps = {
   parseArgs,
@@ -69,6 +74,8 @@ const DEFAULT_CLI_DEPS: CliDeps = {
   runDashboard,
   runDoctor,
   runList,
+  runUpdate,
+  isInteractiveTerminal: IS_INTERACTIVE_TERMINAL,
   log: CONSOLE_LOG,
   logError: CLACK_ERROR,
   logMessage: CLACK_MESSAGE,
@@ -79,6 +86,11 @@ function buildCliDeps(overrides: Partial<CliDeps>): CliDeps {
   return { ...DEFAULT_CLI_DEPS, ...overrides };
 }
 
+function reportCliError(cliDeps: CliDeps, error: unknown): void {
+  cliDeps.logError(`Error: ${error}`);
+  cliDeps.exit(1);
+}
+
 export async function runCli(
   args: string[] = process.argv.slice(2),
   deps: Partial<CliDeps> = {}
@@ -91,11 +103,25 @@ export async function runCli(
     return;
   }
 
-  if (!command) {
+  if (showHelp && !command) {
     cliDeps.log(cliDeps.printUsage());
     return;
   }
 
+  if (!command) {
+    if (commandArgs.length > 0 || !cliDeps.isInteractiveTerminal()) {
+      cliDeps.log(cliDeps.printUsage());
+      return;
+    }
+
+    try {
+      await cliDeps.runStatus();
+    } catch (error) {
+      reportCliError(cliDeps, error);
+    }
+    return;
+  }
+
   if (showHelp) {
     const commandHelp = cliDeps.printCommandHelp(command);
     if (commandHelp) {
@@ -165,6 +191,10 @@ export async function runCli(
         await cliDeps.runDoctor(commandArgs);
         break;
 
+      case "update":
+        await cliDeps.runUpdate(commandArgs);
+        break;
+
       case "list":
         await cliDeps.runList();
         break;
@@ -176,8 +206,7 @@ export async function runCli(
         return;
     }
   } catch (error) {
-    cliDeps.logError(`Error: ${error}`);
-    cliDeps.exit(1);
+    reportCliError(cliDeps, error);
   }
 }
 

package/src/commands/config.ts

@@ -4,7 +4,9 @@ import {
   configExists,
   ensureConfigDir,
   loadConfig,
+  loadConfigWithDiagnostics,
   parseConfig,
+  parseConfigWithDiagnostics,
   saveConfig,
 } from "@/lib/config";
 import {
@@ -41,7 +43,9 @@ export type ConfigCommandDeps = {
   configExists: typeof configExists;
   ensureConfigDir: typeof ensureConfigDir;
   loadConfig: typeof loadConfig;
+  loadConfigWithDiagnostics: typeof loadConfigWithDiagnostics;
   parseConfig: typeof parseConfig;
+  parseConfigWithDiagnostics: typeof parseConfigWithDiagnostics;
   saveConfig: typeof saveConfig;
   spawn: ConfigCommandSpawner;
   env: Record<string, string | undefined>;
@@ -68,7 +72,7 @@ const CONFIG_KEYS = [
   "defaultReview.type",
   "defaultReview.branch",
   "run.simplifier",
-  "run.watch",
+  "run.interactive",
   "retry.maxRetries",
   "retry.baseDelayMs",
   "retry.maxDelayMs",
@@ -251,7 +255,7 @@ export function parseConfigValue(key: ConfigKey, rawValue: string): ConfigValue
       return rawValue;
 
     case "run.simplifier":
-    case "run.watch":
+    case "run.interactive":
       if (rawValue !== "true" && rawValue !== "false") {
         throw new Error(`Value for "${key}" must be "true" or "false".`);
       }
@@ -306,8 +310,8 @@ export function getConfigValue(config: Config, key: ConfigKey): unknown {
       return config.defaultReview.type === "base" ? config.defaultReview.branch : undefined;
     case "run.simplifier":
       return config.run?.simplifier;
-    case "run.watch":
-      return config.run?.watch;
+    case "run.interactive":
+      return config.run?.interactive;
     case "retry.maxRetries":
       return config.retry?.maxRetries;
     case "retry.baseDelayMs":
@@ -490,13 +494,13 @@ export function setConfigValue(config: Config, key: ConfigKey, value: ConfigValu
       if (typeof value !== "boolean") {
         throw new Error(`Value for "${key}" must be "true" or "false".`);
       }
-      next.run = { simplifier: value, watch: next.run?.watch ?? true };
+      next.run = { simplifier: value, interactive: next.run?.interactive ?? true };
       return next;
-    case "run.watch":
+    case "run.interactive":
       if (typeof value !== "boolean") {
         throw new Error(`Value for "${key}" must be "true" or "false".`);
       }
-      next.run = { simplifier: next.run?.simplifier ?? false, watch: value };
+      next.run = { simplifier: next.run?.simplifier ?? false, interactive: value };
       return next;
     case "retry.maxRetries":
       next.retry = next.retry ? { ...next.retry } : { ...DEFAULT_RETRY_CONFIG };
@@ -591,26 +595,55 @@ export function validateConfigInvariants(config: Config): string[] {
   if (config.run && typeof config.run.simplifier !== "boolean") {
     errors.push("run.simplifier must be a boolean.");
   }
-  if (config.run && typeof config.run.watch !== "boolean") {
-    errors.push("run.watch must be a boolean.");
+  if (config.run && typeof config.run.interactive !== "boolean") {
+    errors.push("run.interactive must be a boolean.");
   }
 
   return errors;
 }
 
+function formatConfigValidationMessage(header: string, errors: string[], footer?: string): string {
+  const uniqueErrors = [...new Set(errors)];
+  const lines = [header];
+  for (const error of uniqueErrors) {
+    lines.push(`- ${error}`);
+  }
+  if (footer) {
+    lines.push(footer);
+  }
+  return lines.join("\n");
+}
+
+function collectConfigValidationErrors(config: Config | null, errors: string[]): string[] {
+  const combined = [...errors];
+  if (config) {
+    combined.push(...validateConfigInvariants(config));
+  }
+  return [...new Set(combined)];
+}
+
 async function loadExistingConfig(deps: ConfigCommandDeps): Promise<Config> {
   if (!(await deps.configExists())) {
     throw new Error('Configuration not found. Run "rr init" first.');
   }
 
-  const config = await deps.loadConfig();
-  if (!config) {
+  const loaded = await deps.loadConfigWithDiagnostics();
+  if (!loaded.exists) {
+    throw new Error('Configuration not found. Run "rr init" first.');
+  }
+
+  const errors = collectConfigValidationErrors(loaded.config, loaded.errors);
+  if (!loaded.config || errors.length > 0) {
     throw new Error(
-      `Configuration exists but is invalid: ${deps.configPath}. Run "rr init" or fix the file manually.`
+      formatConfigValidationMessage(
+        `Invalid configuration: ${deps.configPath}`,
+        errors.length > 0 ? errors : ["Configuration format is invalid."],
+        'Run "rr init" to regenerate the file, or fix it manually.'
+      )
     );
   }
 
-  return config;
+  return loaded.config;
 }
 
 async function runShow(args: string[], deps: ConfigCommandDeps): Promise<void> {
@@ -650,17 +683,18 @@ async function runSet(args: string[], deps: ConfigCommandDeps): Promise<void> {
   const current = await loadExistingConfig(deps);
   const updated = setConfigValue(current, key, parsedValue);
 
-  const invariantErrors = validateConfigInvariants(updated);
-  if (invariantErrors.length > 0) {
-    throw new Error(invariantErrors.join("\n"));
-  }
-
-  const normalized = deps.parseConfig(updated as unknown);
-  if (!normalized) {
-    throw new Error("Updated configuration is invalid.");
+  const normalized = deps.parseConfigWithDiagnostics(updated as unknown);
+  const validationErrors = collectConfigValidationErrors(normalized.config, normalized.errors);
+  if (!normalized.config || validationErrors.length > 0) {
+    throw new Error(
+      formatConfigValidationMessage(
+        "Updated configuration is invalid.",
+        validationErrors.length > 0 ? validationErrors : ["Configuration format is invalid."]
+      )
+    );
   }
 
-  await deps.saveConfig(normalized);
+  await deps.saveConfig(normalized.config);
   deps.log.success(`Updated "${key}" to ${formatValue(parsedValue)}.`);
 }
 
@@ -695,15 +729,20 @@ async function runEdit(args: string[], deps: ConfigCommandDeps): Promise<void> {
     return;
   }
 
-  const config = await deps.loadConfig();
-  if (!config) {
+  const loaded = await deps.loadConfigWithDiagnostics();
+  const errors = collectConfigValidationErrors(loaded.config, loaded.errors);
+  if (!loaded.config || errors.length > 0) {
     deps.log.warn(
-      `Configuration exists but is invalid: ${deps.configPath}. Run "rr init" or fix it manually.`
+      formatConfigValidationMessage(
+        `Invalid configuration: ${deps.configPath}`,
+        errors.length > 0 ? errors : ["Configuration format is invalid."],
+        'Run "rr init" to regenerate the file, or fix it manually.'
+      )
     );
     return;
   }
 
-  await deps.saveConfig(config);
+  await deps.saveConfig(loaded.config);
 }
 
 const DEFAULT_CONFIG_COMMAND_DEPS: ConfigCommandDeps = {
@@ -711,7 +750,9 @@ const DEFAULT_CONFIG_COMMAND_DEPS: ConfigCommandDeps = {
   configExists,
   ensureConfigDir,
   loadConfig,
+  loadConfigWithDiagnostics,
   parseConfig,
+  parseConfigWithDiagnostics,
   saveConfig,
   spawn: Bun.spawn as unknown as ConfigCommandSpawner,
   env: process.env as Record<string, string | undefined>,
@@ -731,7 +772,7 @@ function resolveConfigCommandDeps(overrides?: Partial<ConfigCommandDeps>): Confi
     return DEFAULT_CONFIG_COMMAND_DEPS;
   }
 
-  return {
+  const deps: ConfigCommandDeps = {
     ...DEFAULT_CONFIG_COMMAND_DEPS,
     ...overrides,
     log: {
@@ -739,6 +780,30 @@ function resolveConfigCommandDeps(overrides?: Partial<ConfigCommandDeps>): Confi
       ...overrides.log,
     },
   };
+
+  const loadConfigOverride = overrides.loadConfig;
+  if (loadConfigOverride && !overrides.loadConfigWithDiagnostics) {
+    deps.loadConfigWithDiagnostics = async (path = deps.configPath) => {
+      const config = (await loadConfigOverride(path)) ?? null;
+      return {
+        exists: config !== null,
+        config,
+        errors: config ? [] : ["Configuration format is invalid."],
+      };
+    };
+  }
+
+  if (overrides.parseConfig && !overrides.parseConfigWithDiagnostics) {
+    deps.parseConfigWithDiagnostics = (value) => {
+      const config = overrides.parseConfig?.(value) ?? null;
+      return {
+        config,
+        errors: config ? [] : ["Configuration format is invalid."],
+      };
+    };
+  }
+
+  return deps;
 }
 
 export function createRunConfig(overrides?: Partial<ConfigCommandDeps>) {

package/src/commands/init.ts

@@ -53,7 +53,7 @@ interface InitInput {
   defaultReviewType: "uncommitted" | "base";
   defaultReviewBranch?: string;
   runSimplifierByDefault: boolean;
-  runWatchByDefault: boolean;
+  runInteractiveByDefault: boolean;
   soundNotificationsEnabled: boolean;
 }
 
@@ -319,7 +319,7 @@ export function buildConfig(input: InitInput): Config {
     ),
     run: {
       simplifier: input.runSimplifierByDefault,
-      watch: input.runWatchByDefault,
+      interactive: input.runInteractiveByDefault,
     },
     maxIterations: input.maxIterations,
     iterationTimeout: input.iterationTimeoutMinutes * 60 * 1000,
@@ -537,7 +537,7 @@ function formatConfigDisplay(config: Config): string {
     `  Iteration timeout:   ${config.iterationTimeout / 1000 / 60} minutes`,
     `  Default review:      ${defaultReviewDisplay}`,
     `  Run simplifier:      ${config.run?.simplifier ? "enabled" : "disabled"}`,
-    `  Run watch panel:     ${(config.run?.watch ?? true) ? "enabled" : "disabled"}`,
+    `  Interactive Mode:    ${(config.run?.interactive ?? true) ? "enabled" : "disabled"}`,
     `  Sound notify:        ${config.notifications.sound.enabled ? "enabled" : "disabled"}`,
   ].join("\n");
 }
@@ -757,7 +757,7 @@ export async function buildAutoInitInput(
       iterationTimeoutMinutes,
       defaultReviewType: "uncommitted",
       runSimplifierByDefault: false,
-      runWatchByDefault: true,
+      runInteractiveByDefault: true,
       soundNotificationsEnabled: true,
     },
     skippedAgents,
@@ -919,14 +919,17 @@ async function promptForCustomInitInput(
     defaultReviewType: defaultReviewType as "uncommitted" | "base",
     defaultReviewBranch: defaultReviewBranch as string | undefined,
     runSimplifierByDefault: runSimplifierByDefault as boolean,
-    runWatchByDefault: DEFAULT_CONFIG.run?.watch ?? true,
+    runInteractiveByDefault: DEFAULT_CONFIG.run?.interactive ?? true,
     soundNotificationsEnabled: DEFAULT_CONFIG.notifications?.sound.enabled ?? true,
   } satisfies InitInput;
 }
 
-async function promptForRunWatch(runtime: InitRuntime, defaultValue: boolean): Promise<boolean> {
+async function promptForRunInteractive(
+  runtime: InitRuntime,
+  defaultValue: boolean
+): Promise<boolean> {
   const shouldEnable = await runtime.prompt.confirm({
-    message: "Open Session Panel automatically after 'rr run'?",
+    message: "Launch Interactive Mode automatically after 'rr run'?",
     initialValue: defaultValue,
   });
   handleCancel(runtime, shouldEnable);
@@ -1050,12 +1053,15 @@ export async function runInitWithRuntime(
     setupMode === "auto"
       ? {
           ...resolvedInput,
-          runWatchByDefault: true,
+          runInteractiveByDefault: true,
           soundNotificationsEnabled: true,
         }
       : {
           ...resolvedInput,
-          runWatchByDefault: await promptForRunWatch(runtime, resolvedInput.runWatchByDefault),
+          runInteractiveByDefault: await promptForRunInteractive(
+            runtime,
+            resolvedInput.runInteractiveByDefault
+          ),
           soundNotificationsEnabled: await promptForSoundNotifications(
             runtime,
             resolvedInput.soundNotificationsEnabled

package/src/commands/run.ts

@@ -33,8 +33,8 @@ export interface RunOptions {
   commit?: string;
   custom?: string;
   simplifier?: boolean;
-  watch?: boolean;
-  "no-watch"?: boolean;
+  interactive?: boolean;
+  "no-interactive"?: boolean;
   sound?: boolean;
   "no-sound"?: boolean;
 }
@@ -82,20 +82,20 @@ export function resolveRunSimplifierEnabled(options: RunOptions, config: Config
   return options.simplifier === true || config?.run?.simplifier === true;
 }
 
-export function resolveRunWatchEnabled(options: RunOptions, config: Config | null): boolean {
-  if (options.watch && options["no-watch"]) {
-    throw new Error("Cannot use --watch and --no-watch together");
+export function resolveRunInteractiveEnabled(options: RunOptions, config: Config | null): boolean {
+  if (options.interactive && options["no-interactive"]) {
+    throw new Error("Cannot use --interactive and --no-interactive together");
   }
 
-  if (options.watch) {
+  if (options.interactive) {
     return true;
   }
 
-  if (options["no-watch"]) {
+  if (options["no-interactive"]) {
     return false;
   }
 
-  return config?.run?.watch ?? true;
+  return config?.run?.interactive ?? true;
 }
 
 export function formatRunAgentsNote(config: Config, reviewOptions: ReviewOptions): string {
@@ -377,7 +377,7 @@ async function runInBackground(
     runtime.prompt.log.success(`Review started in background session: ${sessionName}`);
     const reviewOptions: ReviewOptions = { baseBranch, commitSha, customInstructions, simplifier };
     runtime.prompt.note(formatRunAgentsNote(config, reviewOptions), "Agents");
-    runtime.prompt.note("rr status  - Check status\n" + "rr stop    - Stop the review", "Commands");
+    runtime.prompt.note("rr         - Check status\n" + "rr stop    - Stop the review", "Commands");
   } catch (error) {
     await runtime.lockfile.removeLockfile(undefined, projectPath, { expectedSessionId: sessionId });
     runtime.prompt.log.error(`Failed to start background session: ${error}`);
@@ -385,9 +385,9 @@ async function runInBackground(
   }
 }
 
-function logWatchReconnectHint(runtime: RunRuntime): void {
-  runtime.prompt.log.message("Session Panel closed.");
-  runtime.prompt.log.message("Re-open panel: rr status");
+function logInteractiveReconnectHint(runtime: RunRuntime): void {
+  runtime.prompt.log.message("Interactive Mode closed.");
+  runtime.prompt.log.message("Launch Interactive Mode: rr");
   runtime.prompt.log.message("Stop session:   rr stop");
 }
 
@@ -692,17 +692,17 @@ export async function startReview(
   }
 
   const runSimplifier = resolveRunSimplifierEnabled(options, config);
-  let runWatch: boolean;
+  let runInteractive: boolean;
   try {
-    runWatch = resolveRunWatchEnabled(options, config);
+    runInteractive = resolveRunInteractiveEnabled(options, config);
   } catch (error) {
     runtime.prompt.log.error(`${error}`);
     runtime.process.exit(1);
     return;
   }
-  if (runWatch && !runtime.process.stdoutIsTTY) {
-    runtime.prompt.log.warn("Watch mode is disabled because stdout is not a TTY.");
-    runWatch = false;
+  if (runInteractive && !runtime.process.stdoutIsTTY) {
+    runtime.prompt.log.warn("Interactive Mode is disabled because stdout is not a TTY.");
+    runInteractive = false;
   }
 
   // Check if inside tmux - warn about nesting
@@ -722,7 +722,7 @@ export async function startReview(
     soundOverride
   );
 
-  if (!runWatch) {
+  if (!runInteractive) {
     return;
   }
 
@@ -731,8 +731,8 @@ export async function startReview(
     const branch = await runtime.getGitBranch(projectPath);
     await runtime.openSessionPanel(projectPath, branch ?? undefined);
   } catch (error) {
-    runtime.prompt.log.warn(`Could not open Session Panel: ${error}`);
+    runtime.prompt.log.warn(`Could not launch Interactive Mode: ${error}`);
   }
 
-  logWatchReconnectHint(runtime);
+  logInteractiveReconnectHint(runtime);
 }

package/src/commands/stop.ts

@@ -118,7 +118,7 @@ async function stopCurrentSession(): Promise<void> {
     if (allSessions.length > 0) {
       p.log.message(`\nThere are ${allSessions.length} other session(s) running.`);
       p.log.message(
-        'Use "rr stop --all" to stop all running review sessions, or "rr status" to see details.'
+        'Use "rr stop --all" to stop all running review sessions, or "rr" to see details.'
       );
     }
     return;