ralph-review 0.1.5 → 0.1.7

package/README.md

@@ -131,11 +131,14 @@ Treats review findings as untrusted input — verifies every claim against actua
 ## Installation
 
 ```bash
-# Homebrew
+# Homebrew (install or update)
 brew install kenryu42/tap/ralph-review
 
-# npm
+# npm (install or update)
 npm install -g ralph-review
+
+# Or let ralph-review detect the install method and update itself
+rr update
 ```
 
 ---
@@ -174,9 +177,14 @@ rrr
 | `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.5",
+  "version": "0.1.7",
   "description": "Orchestrating coding agents for code review, verification and fixing via the ralph loop.",
   "license": "MIT",
   "type": "module",

package/src/cli-core.ts

@@ -150,6 +150,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,7 @@ export interface CliDeps {
   runDashboard: typeof runDashboard;
   runDoctor: typeof runDoctor;
   runList: typeof runList;
+  runUpdate: typeof runUpdate;
   log: (message: string) => void;
   logError: (message: string) => void;
   logMessage: (message: string) => void;
@@ -69,6 +71,7 @@ const DEFAULT_CLI_DEPS: CliDeps = {
   runDashboard,
   runDoctor,
   runList,
+  runUpdate,
   log: CONSOLE_LOG,
   logError: CLACK_ERROR,
   logMessage: CLACK_MESSAGE,
@@ -165,6 +168,10 @@ export async function runCli(
         await cliDeps.runDoctor(commandArgs);
         break;
 
+      case "update":
+        await cliDeps.runUpdate(commandArgs);
+        break;
+
       case "list":
         await cliDeps.runList();
         break;

package/src/commands/init.ts

@@ -211,11 +211,12 @@ const DEFAULT_MAX_ITERATIONS = 5;
 const DEFAULT_ITERATION_TIMEOUT_MINUTES = 30;
 
 const REVIEWER_AGENT_PRIORITY: readonly AgentType[] = ["codex", "droid", "claude", "gemini"];
-const FIXER_AGENT_PRIORITY: readonly AgentType[] = ["claude", "codex", "droid", "gemini"];
-const SIMPLIFIER_AGENT_PRIORITY: readonly AgentType[] = ["claude", "codex", "droid", "gemini"];
+const FIXER_AGENT_PRIORITY: readonly AgentType[] = ["codex", "claude", "droid", "gemini"];
+const SIMPLIFIER_AGENT_PRIORITY: readonly AgentType[] = ["codex", "claude", "droid", "gemini"];
 
 const MODEL_PRIORITY_MATCHERS: Record<ConfiguredRole, readonly ((model: string) => boolean)[]> = {
   reviewer: [
+    (model) => matchesModelId(model, "gpt-5.4"),
     (model) => matchesModelId(model, "gpt-5.3-codex"),
     (model) => matchesModelId(model, "gpt-5.2"),
     (model) => matchesModelId(model, "gpt-5.2-codex"),
@@ -223,11 +224,13 @@ const MODEL_PRIORITY_MATCHERS: Record<ConfiguredRole, readonly ((model: string)
     (model) => matchesModelId(model, "gemini-3-pro-preview"),
   ],
   fixer: [
-    (model) => matchesModelId(model, "claude-opus-4-6"),
+    (model) => matchesModelId(model, "gpt-5.4"),
     (model) => matchesModelId(model, "gpt-5.3-codex"),
+    (model) => matchesModelId(model, "claude-opus-4-6"),
     (model) => matchesModelId(model, "gemini-3-pro-preview"),
   ],
   "code-simplifier": [
+    (model) => matchesModelId(model, "gpt-5.4"),
     (model) => matchesModelId(model, "claude-opus-4-6"),
     (model) => matchesModelId(model, "gpt-5.3-codex"),
     (model) => isClaudeOpus45Model(model),

package/src/commands/update.ts

@@ -0,0 +1,125 @@
+import * as p from "@clack/prompts";
+import { getCommandDef } from "@/cli";
+import { type CommandDef, parseCommand } from "@/lib/cli-parser";
+import {
+  getDefaultSelfUpdateDependencies,
+  isUpdateManager,
+  performSelfUpdate,
+  type SelfUpdateDependencies,
+  SelfUpdateError,
+  type SelfUpdateOptions,
+  type SelfUpdateResult,
+} from "@/lib/self-update";
+
+interface UpdateRuntime extends SelfUpdateDependencies {
+  getCommandDef: (name: string) => CommandDef | undefined;
+  parseCommand: typeof parseCommand;
+  performSelfUpdate: typeof performSelfUpdate;
+  log: {
+    error: (message: string) => void;
+    info: (message: string) => void;
+    message: (message: string) => void;
+    success: (message: string) => void;
+  };
+  exit: (code: number) => void;
+}
+
+export interface UpdateRuntimeOverrides extends Partial<Omit<UpdateRuntime, "log">> {
+  log?: Partial<UpdateRuntime["log"]>;
+}
+
+function createUpdateRuntime(overrides: UpdateRuntimeOverrides = {}): UpdateRuntime {
+  const baseDeps = getDefaultSelfUpdateDependencies(overrides.cliPath);
+
+  return {
+    ...baseDeps,
+    ...overrides,
+    getCommandDef: overrides.getCommandDef ?? getCommandDef,
+    parseCommand: overrides.parseCommand ?? parseCommand,
+    performSelfUpdate: overrides.performSelfUpdate ?? performSelfUpdate,
+    log: {
+      error: overrides.log?.error ?? p.log.error,
+      info: overrides.log?.info ?? p.log.info,
+      message: overrides.log?.message ?? p.log.message,
+      success: overrides.log?.success ?? p.log.success,
+    },
+    exit: overrides.exit ?? process.exit.bind(process),
+  };
+}
+
+function managerLabel(manager: SelfUpdateResult["manager"]): string {
+  return manager === "brew" ? "Homebrew" : "npm";
+}
+
+function renderSelfUpdateResult(result: SelfUpdateResult, runtime: UpdateRuntime): void {
+  switch (result.status) {
+    case "up-to-date":
+      runtime.log.success(
+        `ralph-review is already up to date via ${managerLabel(result.manager)} (${result.currentVersion}).`
+      );
+      return;
+
+    case "update-available":
+      if (result.latestVersion) {
+        runtime.log.info(
+          `Update available via ${managerLabel(result.manager)}: ${result.currentVersion} -> ${result.latestVersion}`
+        );
+        return;
+      }
+
+      runtime.log.info(
+        `Update available via ${managerLabel(result.manager)}. Current version: ${result.currentVersion}`
+      );
+      return;
+
+    case "updated":
+      runtime.log.success(
+        `Updated ralph-review via ${managerLabel(result.manager)}: ${result.previousVersion} -> ${result.finalVersion}`
+      );
+      return;
+  }
+}
+
+export async function runUpdate(
+  argv: string[],
+  overrides: UpdateRuntimeOverrides = {}
+): Promise<void> {
+  const runtime = createUpdateRuntime(overrides);
+  const commandDef = runtime.getCommandDef("update");
+  if (!commandDef) {
+    runtime.log.error("Internal error: update command definition not found");
+    runtime.exit(1);
+    return;
+  }
+
+  const parsed = runtime.parseCommand<{ check: boolean; manager?: string }>(commandDef, argv);
+  const managerValue = parsed.values.manager;
+  if (managerValue !== undefined && !isUpdateManager(managerValue)) {
+    runtime.log.error(`Invalid value for --manager: "${managerValue}"`);
+    runtime.log.message("Valid values: npm, brew");
+    runtime.exit(1);
+    return;
+  }
+
+  const options: SelfUpdateOptions = {
+    checkOnly: parsed.values.check ?? false,
+    manager: managerValue,
+  };
+
+  try {
+    const result = await runtime.performSelfUpdate(options, runtime);
+
+    renderSelfUpdateResult(result, runtime);
+  } catch (error) {
+    if (error instanceof SelfUpdateError) {
+      runtime.log.error(error.message);
+      for (const note of error.notes) {
+        runtime.log.message(note);
+      }
+    } else {
+      runtime.log.error(`${error}`);
+    }
+
+    runtime.exit(1);
+  }
+}

package/src/lib/agents/models.ts

@@ -17,6 +17,7 @@ export const claudeModelOptions = [
 ] as const;
 
 export const codexModelOptions = [
+  { value: "gpt-5.4", label: "GPT-5.4" },
   { value: "gpt-5.3-codex", label: "GPT-5.3 Codex" },
   { value: "gpt-5.2-codex", label: "GPT-5.2 Codex" },
   { value: "gpt-5.2", label: "GPT-5.2" },
@@ -37,6 +38,7 @@ export const droidModelOptions = [
   { value: "gpt-5.2", label: "GPT-5.2" },
   { value: "gpt-5.2-codex", label: "GPT-5.2-Codex" },
   { value: "gpt-5.3-codex", label: "GPT-5.3-Codex" },
+  { value: "gpt-5.4", label: "GPT-5.4" },
   { value: "gemini-3-pro-preview", label: "Gemini 3 Pro" },
   { value: "gemini-3.1-pro-preview", label: "Gemini 3.1 Pro" },
   { value: "gemini-3-flash-preview", label: "Gemini 3 Flash" },
@@ -63,6 +65,7 @@ const droidReasoningLevelsByModel: Record<string, readonly ReasoningLevel[]> = {
   "gpt-5.2": ["low", "medium", "high", "xhigh"],
   "gpt-5.2-codex": ["low", "medium", "high", "xhigh"],
   "gpt-5.3-codex": ["low", "medium", "high", "xhigh"],
+  "gpt-5.4": ["low", "medium", "high", "xhigh"],
   "claude-sonnet-4-5-20250929": ["low", "medium", "high"],
   "claude-sonnet-4-6": ["low", "medium", "high"],
   "claude-opus-4-5-20251101": ["low", "medium", "high"],

package/src/lib/self-update.ts

@@ -0,0 +1,573 @@
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+export type UpdateManager = "npm" | "brew";
+
+export interface CommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface SelfUpdateDependencies {
+  cliPath: string;
+  getCurrentVersion: () => string | Promise<string>;
+  which: (command: string) => string | null;
+  runText: (command: string[]) => Promise<CommandResult>;
+  runInteractive: (command: string[]) => Promise<number>;
+}
+
+export interface SelfUpdateOptions {
+  checkOnly: boolean;
+  manager?: UpdateManager;
+}
+
+export type SelfUpdateResult =
+  | {
+      status: "up-to-date";
+      manager: UpdateManager;
+      currentVersion: string;
+      latestVersion?: string;
+    }
+  | {
+      status: "update-available";
+      manager: UpdateManager;
+      currentVersion: string;
+      latestVersion?: string;
+    }
+  | {
+      status: "updated";
+      manager: UpdateManager;
+      previousVersion: string;
+      finalVersion: string;
+      latestVersion?: string;
+    };
+
+const PACKAGE_NAME = "ralph-review";
+const BREW_TAP_FORMULA = "kenryu42/tap/ralph-review";
+const NPM_INSTALL_COMMAND = ["npm", "install", "-g", `${PACKAGE_NAME}@latest`] as const;
+const BREW_INSTALL_COMMAND = ["brew", "install", BREW_TAP_FORMULA] as const;
+const BREW_INSTALLED_VERSION_ERROR =
+  "Could not determine the installed Homebrew version for ralph-review.";
+const BREW_LATEST_VERSION_ERROR =
+  "Could not determine the latest Homebrew version for ralph-review.";
+const NPM_INSTALLED_VERSION_ERROR =
+  "Could not determine the installed npm version for ralph-review.";
+const VERSION_COMPARE_ERROR =
+  "Could not compare the installed and latest versions for ralph-review.";
+
+export class SelfUpdateError extends Error {
+  constructor(
+    message: string,
+    public readonly notes: string[] = []
+  ) {
+    super(message);
+    this.name = "SelfUpdateError";
+  }
+}
+
+export function isUpdateManager(value: unknown): value is UpdateManager {
+  return value === "npm" || value === "brew";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function normalizePath(filePath: string): string {
+  return resolve(filePath);
+}
+
+function isPathWithin(filePath: string, parentPath: string): boolean {
+  const relativePath = relative(parentPath, filePath);
+  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+
+function buildDetectionNotes(): string[] {
+  return [
+    "Run: rr update --manager npm",
+    "Run: rr update --manager brew",
+    `Run: ${NPM_INSTALL_COMMAND.join(" ")}`,
+    `Run: ${BREW_INSTALL_COMMAND.join(" ")}`,
+  ];
+}
+
+function buildSourceNotes(): string[] {
+  return ["Update with git pull, or install globally to enable self-update."];
+}
+
+function commandDisplay(command: readonly string[]): string {
+  return command.join(" ");
+}
+
+function managerDisplay(manager: UpdateManager): string {
+  switch (manager) {
+    case "brew":
+      return "Homebrew";
+    case "npm":
+      return "npm";
+  }
+}
+
+function managerManualCommand(manager: UpdateManager): string {
+  switch (manager) {
+    case "brew":
+      return commandDisplay(BREW_INSTALL_COMMAND);
+    case "npm":
+      return commandDisplay(NPM_INSTALL_COMMAND);
+  }
+}
+
+async function readTextOutput(
+  deps: Pick<SelfUpdateDependencies, "runText">,
+  command: string[],
+  errorMessage: string
+): Promise<string> {
+  const result = await deps.runText(command);
+  if (result.exitCode !== 0) {
+    const notes = result.stderr.trim() ? [result.stderr.trim()] : [];
+    throw new SelfUpdateError(errorMessage, notes);
+  }
+  return result.stdout.trim();
+}
+
+function getPackageJsonPath(cliPath: string): string {
+  const resolvedCliPath = normalizePath(cliPath);
+  return join(dirname(dirname(resolvedCliPath)), "package.json");
+}
+
+async function readPackageVersion(cliPath: string): Promise<string> {
+  const packageJsonPath = getPackageJsonPath(cliPath);
+  const pkg = (await Bun.file(packageJsonPath).json()) as { version?: unknown };
+  if (typeof pkg.version !== "string" || pkg.version.trim().length === 0) {
+    throw new Error(`Could not determine version from ${packageJsonPath}`);
+  }
+  return pkg.version.trim();
+}
+
+async function readSpawnStream(
+  stream: ReadableStream<Uint8Array> | null | undefined
+): Promise<string> {
+  if (!stream) {
+    return "";
+  }
+
+  return new Response(stream).text();
+}
+
+export function getDefaultSelfUpdateDependencies(
+  cliPath: string = process.argv[1] ?? resolve(import.meta.dir, "../cli.ts")
+): SelfUpdateDependencies {
+  return {
+    cliPath,
+    getCurrentVersion: () => readPackageVersion(cliPath),
+    which: Bun.which,
+    runText: async (command: string[]) => {
+      const proc = Bun.spawn(command, {
+        stdout: "pipe",
+        stderr: "pipe",
+        stdin: "ignore",
+      });
+
+      const [exitCode, stdout, stderr] = await Promise.all([
+        proc.exited,
+        readSpawnStream(proc.stdout),
+        readSpawnStream(proc.stderr),
+      ]);
+
+      return {
+        stdout,
+        stderr,
+        exitCode,
+      };
+    },
+    runInteractive: async (command: string[]) => {
+      const proc = Bun.spawn(command, {
+        stdout: "inherit",
+        stderr: "inherit",
+        stdin: "inherit",
+      });
+
+      return proc.exited;
+    },
+  };
+}
+
+async function detectNpmMatch(deps: SelfUpdateDependencies, cliPath: string): Promise<boolean> {
+  if (!deps.which("npm")) {
+    return false;
+  }
+
+  const result = await deps.runText(["npm", "prefix", "-g"]);
+  if (result.exitCode !== 0) {
+    return false;
+  }
+
+  const prefix = result.stdout.trim();
+  if (!prefix) {
+    return false;
+  }
+
+  const npmPackageDir = join(prefix, "lib", "node_modules", PACKAGE_NAME);
+
+  return isPathWithin(cliPath, npmPackageDir);
+}
+
+async function detectBrewMatch(deps: SelfUpdateDependencies, cliPath: string): Promise<boolean> {
+  if (!deps.which("brew")) {
+    return false;
+  }
+
+  const result = await deps.runText(["brew", "--prefix", "--installed", PACKAGE_NAME]);
+  if (result.exitCode !== 0) {
+    return false;
+  }
+
+  const formulaPrefix = result.stdout.trim();
+  if (!formulaPrefix) {
+    return false;
+  }
+
+  const brewRoot = dirname(dirname(formulaPrefix));
+  const brewBinDir = join(brewRoot, "bin");
+  const cellarDir = join(brewRoot, "Cellar", PACKAGE_NAME);
+
+  return (
+    isPathWithin(cliPath, brewBinDir) ||
+    isPathWithin(cliPath, formulaPrefix) ||
+    isPathWithin(cliPath, cellarDir)
+  );
+}
+
+async function isSourceCheckout(
+  deps: Pick<SelfUpdateDependencies, "runText" | "which">,
+  cliPath: string
+): Promise<boolean> {
+  if (!deps.which("git")) {
+    return false;
+  }
+
+  const projectRoot = dirname(dirname(cliPath));
+  const result = await deps.runText([
+    "git",
+    "-C",
+    projectRoot,
+    "rev-parse",
+    "--is-inside-work-tree",
+  ]);
+  return result.exitCode === 0 && result.stdout.trim() === "true";
+}
+
+export async function detectUpdateManager(deps: SelfUpdateDependencies): Promise<UpdateManager> {
+  const cliPath = normalizePath(deps.cliPath);
+  const matches: UpdateManager[] = [];
+
+  if (await detectNpmMatch(deps, cliPath)) {
+    matches.push("npm");
+  }
+
+  if (await detectBrewMatch(deps, cliPath)) {
+    matches.push("brew");
+  }
+
+  const detectedManager = matches[0];
+  if (matches.length === 1 && detectedManager) {
+    return detectedManager;
+  }
+
+  if (matches.length > 1) {
+    throw new SelfUpdateError(
+      "Could not determine whether ralph-review was installed with npm or Homebrew.",
+      buildDetectionNotes()
+    );
+  }
+
+  if (await isSourceCheckout(deps, cliPath)) {
+    throw new SelfUpdateError(
+      "Self-update is not available when running from source.",
+      buildSourceNotes()
+    );
+  }
+
+  throw new SelfUpdateError(
+    "Could not determine how ralph-review was installed.",
+    buildDetectionNotes()
+  );
+}
+
+function ensureManagerAvailable(manager: UpdateManager, deps: SelfUpdateDependencies): void {
+  if (deps.which(manager)) {
+    return;
+  }
+
+  throw new SelfUpdateError(
+    `${managerDisplay(manager)} is not installed or not available in PATH.`,
+    [`Run: ${managerManualCommand(manager)}`]
+  );
+}
+
+async function getNpmVersions(
+  deps: SelfUpdateDependencies
+): Promise<{ currentVersion: string; latestVersion: string }> {
+  const currentVersion = await getNpmInstalledVersion(deps);
+  const latestVersion = await readTextOutput(
+    deps,
+    ["npm", "view", PACKAGE_NAME, "version"],
+    "Failed to fetch the latest npm version for ralph-review."
+  );
+
+  return {
+    currentVersion,
+    latestVersion,
+  };
+}
+
+function parseNpmInstalledVersion(output: string): string {
+  const parsed = JSON.parse(output) as unknown;
+  if (!isRecord(parsed) || !isRecord(parsed.dependencies)) {
+    throw new SelfUpdateError(NPM_INSTALLED_VERSION_ERROR);
+  }
+
+  const dependency = parsed.dependencies[PACKAGE_NAME];
+  if (!isRecord(dependency)) {
+    throw new SelfUpdateError(NPM_INSTALLED_VERSION_ERROR);
+  }
+
+  if (typeof dependency.version !== "string" || dependency.version.trim().length === 0) {
+    throw new SelfUpdateError(NPM_INSTALLED_VERSION_ERROR);
+  }
+
+  return dependency.version.trim();
+}
+
+async function getNpmInstalledVersion(deps: SelfUpdateDependencies): Promise<string> {
+  const output = await readTextOutput(
+    deps,
+    ["npm", "list", "-g", PACKAGE_NAME, "--json", "--depth=0"],
+    "Failed to read the installed npm version for ralph-review."
+  );
+
+  return parseNpmInstalledVersion(output);
+}
+
+function hasNewerVersion(currentVersion: string, latestVersion: string): boolean {
+  try {
+    return compareVersions(latestVersion, currentVersion) === 1;
+  } catch {
+    throw new SelfUpdateError(VERSION_COMPARE_ERROR, [
+      `Installed version: ${currentVersion}`,
+      `Latest version: ${latestVersion}`,
+    ]);
+  }
+}
+
+function parseVersionRevision(version: string): { version: string; revision: number } {
+  const trimmed = version.trim();
+  const [baseVersion, revisionSuffix, ...extraSegments] = trimmed.split("_");
+  if (!baseVersion || extraSegments.length > 0) {
+    throw new Error(`Invalid version: ${version}`);
+  }
+
+  if (revisionSuffix === undefined) {
+    return { version: baseVersion, revision: 0 };
+  }
+
+  if (!/^\d+$/.test(revisionSuffix)) {
+    throw new Error(`Invalid revisioned version: ${version}`);
+  }
+
+  return { version: baseVersion, revision: Number.parseInt(revisionSuffix, 10) };
+}
+
+function compareVersions(leftVersion: string, rightVersion: string): number {
+  const left = parseVersionRevision(leftVersion);
+  const right = parseVersionRevision(rightVersion);
+  const versionOrder = Bun.semver.order(left.version, right.version);
+
+  if (versionOrder !== 0) {
+    return versionOrder;
+  }
+
+  if (left.revision > right.revision) {
+    return 1;
+  }
+
+  if (left.revision < right.revision) {
+    return -1;
+  }
+
+  return 0;
+}
+
+function formatBrewVersion(version: string, revision: number): string {
+  return revision > 0 ? `${version}_${revision}` : version;
+}
+
+function parseBrewVersions(output: string): { currentVersion: string; latestVersion: string } {
+  const parsed = JSON.parse(output) as unknown;
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new SelfUpdateError(BREW_INSTALLED_VERSION_ERROR);
+  }
+
+  const formula = parsed[0];
+  if (!isRecord(formula) || !Array.isArray(formula.installed)) {
+    throw new SelfUpdateError(BREW_INSTALLED_VERSION_ERROR);
+  }
+
+  let currentVersion = "";
+
+  const linkedKeg = typeof formula.linked_keg === "string" ? formula.linked_keg.trim() : "";
+  if (linkedKeg) {
+    for (const installed of formula.installed) {
+      if (
+        isRecord(installed) &&
+        typeof installed.version === "string" &&
+        installed.version.trim() === linkedKeg
+      ) {
+        currentVersion = linkedKeg;
+        break;
+      }
+    }
+  }
+
+  if (!currentVersion) {
+    for (const installed of formula.installed) {
+      if (
+        isRecord(installed) &&
+        typeof installed.version === "string" &&
+        installed.version.trim()
+      ) {
+        currentVersion = installed.version.trim();
+        break;
+      }
+    }
+  }
+
+  if (!currentVersion) {
+    throw new SelfUpdateError(BREW_INSTALLED_VERSION_ERROR);
+  }
+
+  if (
+    !isRecord(formula.versions) ||
+    typeof formula.versions.stable !== "string" ||
+    !formula.versions.stable.trim()
+  ) {
+    throw new SelfUpdateError(BREW_LATEST_VERSION_ERROR);
+  }
+
+  const stableVersion = (formula.versions.stable as string).trim();
+  const revision =
+    typeof formula.revision === "number" && formula.revision > 0 ? formula.revision : 0;
+  const latestVersion = formatBrewVersion(stableVersion, revision);
+
+  return { currentVersion, latestVersion };
+}
+
+async function getBrewVersions(
+  deps: SelfUpdateDependencies
+): Promise<{ currentVersion: string; latestVersion: string }> {
+  const output = await readTextOutput(
+    deps,
+    ["brew", "info", "--json=v1", PACKAGE_NAME],
+    "Failed to read Homebrew formula info for ralph-review."
+  );
+
+  return parseBrewVersions(output);
+}
+
+async function performNpmSelfUpdate(
+  options: SelfUpdateOptions,
+  deps: SelfUpdateDependencies
+): Promise<SelfUpdateResult> {
+  ensureManagerAvailable("npm", deps);
+
+  const { currentVersion, latestVersion } = await getNpmVersions(deps);
+  if (!hasNewerVersion(currentVersion, latestVersion)) {
+    return {
+      status: "up-to-date",
+      manager: "npm",
+      currentVersion,
+      latestVersion,
+    };
+  }
+
+  if (options.checkOnly) {
+    return {
+      status: "update-available",
+      manager: "npm",
+      currentVersion,
+      latestVersion,
+    };
+  }
+
+  const exitCode = await deps.runInteractive([...NPM_INSTALL_COMMAND]);
+  if (exitCode !== 0) {
+    throw new SelfUpdateError(
+      `${commandDisplay(NPM_INSTALL_COMMAND)} exited with code ${exitCode}.`
+    );
+  }
+
+  const finalVersion = await getNpmInstalledVersion(deps);
+  return {
+    status: "updated",
+    manager: "npm",
+    previousVersion: currentVersion,
+    finalVersion,
+    latestVersion,
+  };
+}
+
+async function performBrewSelfUpdate(
+  options: SelfUpdateOptions,
+  deps: SelfUpdateDependencies
+): Promise<SelfUpdateResult> {
+  ensureManagerAvailable("brew", deps);
+
+  const { currentVersion, latestVersion } = await getBrewVersions(deps);
+  if (!hasNewerVersion(currentVersion, latestVersion)) {
+    return {
+      status: "up-to-date",
+      manager: "brew",
+      currentVersion,
+      latestVersion,
+    };
+  }
+
+  if (options.checkOnly) {
+    return {
+      status: "update-available",
+      manager: "brew",
+      currentVersion,
+      latestVersion,
+    };
+  }
+
+  const exitCode = await deps.runInteractive([...BREW_INSTALL_COMMAND]);
+  if (exitCode !== 0) {
+    throw new SelfUpdateError(
+      `${commandDisplay(BREW_INSTALL_COMMAND)} exited with code ${exitCode}.`
+    );
+  }
+
+  const { currentVersion: finalVersion } = await getBrewVersions(deps);
+  return {
+    status: "updated",
+    manager: "brew",
+    previousVersion: currentVersion,
+    finalVersion,
+    latestVersion,
+  };
+}
+
+export async function performSelfUpdate(
+  options: SelfUpdateOptions,
+  deps: SelfUpdateDependencies
+): Promise<SelfUpdateResult> {
+  const manager = options.manager ?? (await detectUpdateManager(deps));
+
+  switch (manager) {
+    case "npm":
+      return performNpmSelfUpdate(options, deps);
+    case "brew":
+      return performBrewSelfUpdate(options, deps);
+  }
+}