fix: degrade shell-completion EACCES to warning instead of hard exit 1

lwy-2 · claude · lwy-2 · commit c9835c159737 · 2026-07-03T16:19:48.000+08:00
When doctor --fix runs shell-completion install against a read-only rc file (~/.bashrc with mode 444), print a one-line warning and exit 0 instead of throwing Error('Failed to install completion: EACCES...') and exiting 1. Introduces tryInstallCompletion wrapper that catches installCompletion errors, logs a user-facing note, and returns false. Both call sites in doctorShellCompletion (slow-profile upgrade and fresh install) use the wrapper and only emit success messages on actual success. Closes #99237 Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/src/commands/doctor-completion.test.ts b/src/commands/doctor-completion.test.ts
@@ -1,15 +1,20 @@
-// Doctor completion tests cover final doctor status summaries and completion messaging.
+// Doctor completion tests cover final doctor status summaries, completion messaging,
+// and graceful degradation when shell-completion install hits permission errors.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import * as completionRuntime from "../cli/completion-runtime.js";
+import { createNonExitingRuntime } from "../runtime.js";
 import { captureEnv, setTestEnvValue } from "../test-utils/env.js";
 import {
   checkShellCompletionStatus,
+  doctorShellCompletion,
   shellCompletionStatusToHealthFindings,
   shellCompletionStatusToRepairEffects,
   type ShellCompletionStatus,
 } from "./doctor-completion.js";
+import type { DoctorPrompter } from "./doctor-prompter.js";
 
 const originalEnv = captureEnv(["HOME", "OPENCLAW_STATE_DIR", "SHELL"]);
 const tempDirs: string[] = [];
@@ -102,3 +107,42 @@ describe("shell completion health mapping", () => {
     expect(shellCompletionStatusToRepairEffects(current)).toEqual([]);
   });
 });
+
+describe("doctorShellCompletion EACCES degradation", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("degrades to a warning when installCompletion fails with EACCES during slow-profile upgrade", async () => {
+    // Mock the completion-runtime helpers so checkShellCompletionStatus returns
+    // a slow-dynamic status with an existing cache, which reaches the
+    // installCompletion code path without needing cache generation.
+    vi.spyOn(completionRuntime, "usesSlowDynamicCompletion").mockResolvedValue(true);
+    vi.spyOn(completionRuntime, "completionCacheExists").mockResolvedValue(true);
+    vi.spyOn(completionRuntime, "isCompletionInstalled").mockResolvedValue(true);
+    vi.spyOn(completionRuntime, "resolveShellFromEnv").mockReturnValue("bash" as const);
+    const installSpy = vi
+      .spyOn(completionRuntime, "installCompletion")
+      .mockRejectedValue(new Error("EACCES: permission denied, open '/sandbox/.bashrc'"));
+
+    const prompter: DoctorPrompter = {
+      confirm: vi.fn(async () => true),
+      confirmAutoFix: vi.fn(async () => true),
+      confirmAggressiveAutoFix: vi.fn(async () => true),
+      confirmRuntimeRepair: vi.fn(async () => true),
+      select: vi.fn(
+        async (_params: unknown, fallback: unknown) => fallback,
+      ) as DoctorPrompter["select"],
+      shouldRepair: true,
+      shouldForce: false,
+      repairMode: "fix" as const,
+    };
+
+    // Must not throw — the EACCES error must degrade to a warning.
+    await expect(
+      doctorShellCompletion(createNonExitingRuntime(), prompter),
+    ).resolves.toBeUndefined();
+
+    expect(installSpy).toHaveBeenCalledOnce();
+  });
+});
diff --git a/src/commands/doctor-completion.ts b/src/commands/doctor-completion.ts
@@ -15,12 +15,39 @@ import {
   type CompletionShell,
 } from "../cli/completion-runtime.js";
 import type { HealthFinding, HealthRepairEffect } from "../flows/health-checks.js";
+import { formatErrorMessage } from "../infra/errors.js";
 import { resolveOpenClawPackageRoot } from "../infra/openclaw-root.js";
 import type { RuntimeEnv } from "../runtime.js";
 import type { DoctorPrompter } from "./doctor-prompter.js";
 
 const COMPLETION_CACHE_WRITE_TIMEOUT_MS = 30_000;
 
+/**
+ * Wraps installCompletion so that filesystem permission errors (EACCES) and
+ * other non-critical failures degrade to a warning instead of a hard error.
+ * Doctor treats shell-completion installation as optional — an unwritable rc
+ * file must never cause exit code 1.
+ */
+async function tryInstallCompletion(
+  shell: string,
+  yes: boolean,
+  binName: string,
+  cliName: string,
+): Promise<boolean> {
+  try {
+    await installCompletion(shell, yes, binName);
+    return true;
+  } catch (error) {
+    const message = formatErrorMessage(error);
+    note(
+      `Shell completion not installed: ${message}. ` +
+        `Run \`${cliName} completion install\` against a writable rc file manually.`,
+      "Shell completion",
+    );
+    return false;
+  }
+}
+
 export type ShellCompletionStatusOptions = {
   shell?: CompletionShell;
 };
@@ -195,8 +222,9 @@ export async function doctorShellCompletion(
       }
     }
 
-    await installCompletion(status.shell, true, cliName);
-    note(formatCompletionReloadNote(status.shell, "upgraded"), "Shell completion");
+    if (await tryInstallCompletion(status.shell, true, cliName, cliName)) {
+      note(formatCompletionReloadNote(status.shell, "upgraded"), "Shell completion");
+    }
     return;
   }
 
@@ -237,8 +265,9 @@ export async function doctorShellCompletion(
         return;
       }
 
-      await installCompletion(status.shell, true, cliName);
-      note(formatCompletionReloadNote(status.shell, "installed"), "Shell completion");
+      if (await tryInstallCompletion(status.shell, true, cliName, cliName)) {
+        note(formatCompletionReloadNote(status.shell, "installed"), "Shell completion");
+      }
     }
   }
 }
