fix(install): configure npm for user-local installs to avoid EACCES on Linux

[MauroDruwel]

Summary

On standard Linux systems where Node.js is installed via the system package
manager (apt, dnf, pacman, etc.), the npm global prefix defaults to /usr or
/usr/local — directories that require root to write to. This causes npm link
to fail with EACCES: permission denied and leaves the installer with a cryptic
error message and no recovery path. This PR adds a fix_npm_permissions step
(matching the pattern already used in the upstream OpenClaw installer) that
detects the condition before npm link runs and silently redirects the prefix
to ~/.npm-global, eliminating the failure entirely without requiring sudo.

Related Issue

Related to #364
The npm EACCES permission error is one of the common installation failures
documented in that issue. This PR fixes the root cause in the installer so
users on system-managed Node.js no longer hit the error at all.

Changes

• Added fix_npm_permissions() function in install.sh that:
  • Runs only on Linux (no-op on macOS).
  • Checks whether the current npm config get prefix is user-writable.
  • If not writable (e.g. /usr, /usr/local), redirects the npm global
    prefix to ~/.npm-global.
  • Appends export PATH="$HOME/.npm-global/bin:$PATH" to ~/.bashrc and
    ~/.zshrc (only if the file exists and the entry is not already present).
  • Exports the updated PATH for the current installer session.
• Called fix_npm_permissions in main() immediately before install_nemoclaw
  so the correct prefix is always in place before npm link runs.

Type of Change

• Code change for a new feature, bug fix, or refactor.

Testing

• npx prek run --all-files passes (or equivalently make check).
• npm test passes.
• make docs builds without warnings. (for doc-only changes)

Manual reproduction:

# Reproduce on Ubuntu 22.04 with system Node.js (npm prefix = /usr)
node --version   # v20.x via apt
npm config get prefix  # /usr  ← not writable without root

curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
# Before this PR: fails with EACCES at "Linking NemoClaw CLI"
# After  this PR: installer prints "[INFO] npm global prefix '/usr' is not
#                 writable — configuring user-local installs" and completes
#                 successfully.

Tested on:

OS	Node.js source	npm prefix before	Result
Ubuntu 22.04	apt	/usr	✅ Fixed — prefix redirected to ~/.npm-global
Ubuntu 24.04	nvm	~/.nvm/… (writable)	✅ No change in behavior
macOS 14	brew	/opt/homebrew	✅ No-op (Linux-only guard)

Checklist

General

• I have read and followed the contributing guide.
• I have read and followed the style guide. (for doc-only changes)

Code Changes

• Formatters applied — npx prek run --all-files auto-fixes formatting (or make format for targeted runs).
• Tests added or updated for new or changed behavior.
• No secrets, API keys, or credentials committed.
• Doc pages updated for any user-facing behavior changes (new commands, changed defaults, new features, bug fixes that contradict existing docs).

Doc Changes

• Follows the style guide.
• New pages include SPDX license header and frontmatter, if creating a new page.
• Cross-references and links verified.

---

Prior art / comparison

Two earlier PRs attempted to fix this:

	PR #91	PR #517	This PR
Approach	sudo npm link	Permission check → retry with sudo	Prefix redirect to ~/.npm-global
Works without root	❌	❌	✅
Works in CI / Docker	❌ (sudo prompts / missing)	❌	✅
Elevated privileges	✅ required	✅ required	❌ not needed
Side-effects	Writes to system paths	Writes to system paths	Writes only to ~/
Upstream precedent	—	—	✅ Same pattern as OpenClaw installer

This approach is the one recommended in NemoClaw's own troubleshooting docs
and is already used verbatim in the upstream OpenClaw installer. It avoids
elevated privileges entirely, works in any non-interactive environment, and
has no impact on users who already have a writable prefix (nvm, fnm, Volta,
or a manually configured ~/.npm-global).

Summary by CodeRabbit

• Bug Fixes
  • Installer now detects and fixes npm global permission issues on Linux by configuring a user-writable npm location, updating the PATH in common shell profiles when needed, and applying the adjusted environment before installing the CLI. This reduces installation failures and ensures globally installed tools are usable immediately after setup.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 85923c73-a32f-497c-8f8d-f4f4b0d2e50d

📥 Commits

Reviewing files that changed from the base of the PR and between 005c554 and 53e25ce.

📒 Files selected for processing (1)

• install.sh

🚧 Files skipped from review as they are similar to previous changes (1)

• install.sh

---

📝 Walkthrough

Walkthrough

Added a Linux-only fix_npm_permissions() to install.sh that ensures npm global operations use a user-writable prefix (~/.npm-global), updates npm’s prefix and PATH, and appends PATH exports to ~/.bashrc/~/.zshrc when needed. main() now calls this before install_nemoclaw.

Changes

Cohort / File(s)

Summary

NPM Permissions Fix install.sh

Added fix_npm_permissions() (Linux-only) to check npm config get prefix writability, create ~/.npm-global if needed, set npm prefix, prepend ~/.npm-global/bin to PATH for the current process, and append an "Added by NemoClaw installer" PATH export block to ~/.bashrc and ~/.zshrc when those files exist and don't already reference .npm-global. Updated main() to call fix_npm_permissions before install_nemoclaw.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Installer as "install.sh"
    participant npm as "npm config"
    participant Shell as "shell rc files"

    User->>Installer: run install script
    Installer->>npm: npm config get prefix
    alt prefix not writable
        Installer->>Installer: mkdir ~/.npm-global
        Installer->>npm: npm config set prefix ~/.npm-global
        Installer->>Installer: export PATH=~/.npm-global/bin:$PATH (current proc)
        Installer->>Shell: append export block to ~/.bashrc / ~/.zshrc if missing
    else prefix writable
        Installer->>Installer: no-op
    end
    Installer->>Installer: call install_nemoclaw (uses adjusted env)

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I hopped in to tweak your npm trail,
Made ~/.npm-global safe and hale,
PATH set right, no more sudo chase,
Installer hums with calmer pace —
Hooray for tidy package sail! 🥕✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding npm configuration to prevent EACCES permission errors on Linux systems during installation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wscurran]

✨ Thanks for submitting this PR, it addresses a bug that could cause issues during installation on Linux systems.