PR #63082: fix(cli): respect ZDOTDIR and XDG_CONFIG_HOME in shell completion pro…

• Repository: openclaw/openclaw
• Author: zh1C
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/63082

Description (problem / solution / changelog)

Summary

• Problem: Shell completion install/check hardcodes ~/.zshrc, ~/.config/fish/config.fish, etc. and ignores $ZDOTDIR, $XDG_CONFIG_HOME, and bash .bash_profile fallback. This causes completion to be written to a file the shell never reads, silently breaking completion for users with non-default shell config directories.
• Why it matters: Users who organize their dotfiles under $ZDOTDIR or $XDG_CONFIG_HOME (a common and well-documented practice) get broken completion on every install/update, and may get an orphan ~/.zshrc created unexpectedly.
• What changed: Unified all profile path resolution into a single getShellProfilePath() function that respects $ZDOTDIR (zsh), $XDG_CONFIG_HOME (fish, PowerShell on non-Windows), and .bashrc/.bash_profile fallback (bash). Removed duplicated path logic from installCompletion(). Updated doctor-completion.ts to use the resolved path in user-facing messages.
• What did NOT change (scope boundary): Completion script generation logic is untouched. No changes to how the cache is generated or where it is stored. PowerShell automated install remains unsupported (was already gated).

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• UI / DX

Linked Issue/PR

• Closes #63069

Root Cause (if applicable)

• Root cause: getShellProfilePath() and installCompletion() independently hardcoded default profile paths ($HOME/.zshrc, $HOME/.config/fish/config.fish) without consulting the shell-specific environment variables that control where dotfiles are actually read from.
• Missing detection / guardrail: No tests existed for non-default profile path resolution. The two functions that computed profile paths (getShellProfilePath for checking, inline logic in installCompletion for writing) were never compared or unified.
• Contributing context: The bash path had an additional inconsistency: getShellProfilePath() returned only ~/.bashrc, while installCompletion() had a .bash_profile fallback — causing check/install to disagree.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• Coverage level that should have caught this:
  • Unit test
• Target test or file: src/cli/completion-cli.test.ts
• Scenario the test should lock in:
  • getShellProfilePath("zsh", { ZDOTDIR: "/custom" }) returns /custom/.zshrc
  • getShellProfilePath("fish", { XDG_CONFIG_HOME: "/custom" }) returns /custom/fish/config.fish
  • getShellProfilePath("bash", ...) returns .bash_profile when .bashrc does not exist
  • getShellProfilePath("powershell", { XDG_CONFIG_HOME: "/custom" }) returns /custom/powershell/... on non-Windows
• Why this is the smallest reliable guardrail: Pure function with env injection — no I/O mocks needed for zsh/fish/powershell; bash uses temp dirs to test filesystem fallback.

User-visible / Behavior Changes

• Shell completion now correctly installs into ${ZDOTDIR:-$HOME}/.zshrc instead of always ~/.zshrc.
• Shell completion now correctly installs into ${XDG_CONFIG_HOME:-~/.config}/fish/config.fish instead of always ~/.config/fish/config.fish.
• Bash completion check and install now consistently prefer .bashrc, falling back to .bash_profile if .bashrc doesn't exist.
• openclaw doctor and openclaw update "source" hints now show the actual resolved profile path instead of a hardcoded ~/.zshrc/~/.bashrc.

Diagram (if applicable)

N/A.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS 15.4

Steps

1. Set ZDOTDIR=/tmp/test-zdotdir and create /tmp/test-zdotdir/.zshrc.
2. Run openclaw completion --install --shell zsh.
3. Verify the source line is written to /tmp/test-zdotdir/.zshrc, not ~/.zshrc.

Expected

• Source line appears in /tmp/test-zdotdir/.zshrc.

Actual

• Source line written to ~/.zshrc; /tmp/test-zdotdir/.zshrc` untouched.

Evidence

Attach at least one:

• Failing test/log before + passing after
• 7 new unit tests in src/cli/completion-cli.test.ts covering all four shells with env var overrides.

Human Verification (required)

• Verified scenarios: zsh with ZDOTDIR, fish with XDG_CONFIG_HOME, bash with only .bash_profile, PowerShell with XDG_CONFIG_HOME
• Edge cases checked: neither .bashrc nor .bash_profile exist (defaults to .bashrc), empty ZDOTDIR (falls back to $HOME)
• What I did not verify: Windows PowerShell path (no Windows environment available), live openclaw update end-to-end flow
• getShellProfilePath("bash", ...) returns .bash_profile when neither .bashrc nor .bash_profile exists (login-shell safety for macOS)

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
  • users who previously had broken completion will get it working on next openclaw update or openclaw completion --install.

Risks and Mitigations

• Risk: existsSync in getShellProfilePath() introduces a synchronous filesystem call for the bash path.- Mitigation: Only called for bash shell (not zsh/fish/powershell which use pure env lookups). The function was already used synchronously by callers. The check is a single stat on two well-known paths in $HOME.

Changed files

• src/cli/completion-cli.test.ts (modified, +78/-1)
• src/cli/completion-cli.ts (modified, +42/-27)
• src/commands/doctor-completion.ts (modified, +5/-2)