env-checkup

Env Checkup

Audit and optimize a user's shell + developer dotfiles safely. Follow the five steps in order. The backup is mandatory and must precede every edit.

Non-negotiable safety rules

• Back up before ANY edit. No exceptions. Create a timestamped local backup; also run the user's backup tool (e.g. mackup backup) only if its storage is mounted.
• Never print secrets. Do not cat token files, .npmrc auth lines, SSH keys, or history files. When you must read a file that may contain secrets, redact values (sed -E 's/(=")[^"]*(")/\1<redacted>\2/g') or check length/SET, never the value.
• Confirm before flagging. An "orphan" is only an orphan after grep proves it's sourced nowhere. A tool's config stays only if the tool exists (command -v).
• Move, don't delete. Put removed orphans in <backup>/removed-orphans/.
• Leave intentional settings alone — flag, don't change (e.g. strict-ssl=false in .npmrc, a deliberate JAVA_HOME). Report them; let the user decide.
• Context-anchored edits only. Never wholesale-rewrite a dotfile.

Step 1 — Inventory & Step 2 — Triple-check (read-only)

Run the bundled audit script — it does both, prints no secrets, and detects the shell:

bash "$CLAUDE_SKILL_DIR/scripts/audit.sh"   # or the absolute path to scripts/audit.sh

It reports: shell + load order, which standard dotfiles exist, Mackup config and whether its storage is mounted, tool existence (incl. git-lfs), stale .zcompdump*, a load-order grep audit, orphan candidates, and a live PATH-duplicate/nvm/NODE_OPTIONS measurement from a fresh login+interactive shell. Read each shell file in load order (zsh: .zshenv → .zprofile → .zshrc → .zlogin) and specifically hunt for:

• Duplicate compinit — vendor snippets (Docker Desktop) append a second autoload -Uz compinit; compinit. Collapse to one.
• Completion fpath additions placed AFTER compinit — they must come before it.
• Broken cache-age check using ${ZDOTDIR} instead of ${ZDOTDIR:-$HOME} (with ZDOTDIR unset it tests /.zcompdump, never matches → never rebuilds). Note: the glob qualifier (#qN.mh+24) does expand inside [[ -n … ]] in zsh.
• Vars that should be exported but aren't (e.g. NODE_OPTIONS). If the var is set but not exported, export it. If it isn't defined anywhere, do NOT fabricate one.
• nvm loaded redundantly in both .zprofile and .zshrc without a guard; guard a genuine second load with command -v nvm >/dev/null ||. (Often there is no real second load — confirm before "fixing".)
• PATH duplication — e.g. nvm.sh/antigravity/orbstack raw PATH= prepends running after a typeset -U path dedup. Measure: total vs unique.
• Orphans sourced nowhere (.zenv, .node_path, .zshrc.pre-oh-my-zsh, stale .bashrc/.profile with conflicting JAVA_HOME/SDK paths). Confirm with grep.
• Stale accumulated .zcompdump* caches.

Step 3 — Back up (mandatory, before any edit)

BK="$HOME/dotfiles-backup-$(date +%Y%m%d-%H%M%S)"; mkdir -p "$BK/removed-orphans"
for f in .zshrc .zshenv .zprofile .zlogin .bashrc .bash_profile .profile \
         .gitconfig .npmrc .mackup.cfg .config/fish/config.fish; do
  [ -e "$HOME/$f" ] && cp -p "$HOME/$f" "$BK/"; done
mkdir -p "$BK/zcompdump-cache"; cp -p "$HOME"/.zcompdump* "$BK/zcompdump-cache/" 2>/dev/null
# Mackup ONLY if storage mounted (audit reports this); else rely on local backup and say so.
command -v mackup >/dev/null && mackup backup --force
echo "$BK"

Step 4 — Optimize (precise, anchored edits)

• Collapse to a single compinit; move all completion fpath=(…) additions above it.
• Fix the cache path to ${ZDOTDIR:-$HOME}/.zcompdump.
• Export NODE_OPTIONS only if it already exists unexported.
• Guard a real second nvm load with command -v nvm >/dev/null ||.
• After the tool initializers (nvm/antigravity/orbstack), re-assert dedup at the END of .zshrc: typeset -U path PATH; path=($path).
• To make nvm a single PATH entry, after nvm use drop the redundant symlink path: path=(${path:#$NVM_DIR/current/bin}) (keep current/bin in .zshenv for non-interactive shells — they never run .zshrc).
• Move confirmed orphans → <backup>/removed-orphans/; clear stale .zcompdump*.

Extracting secrets to ~/.zsh_secrets (common request)

Move plaintext credential export lines out of .zshrc into ~/.zsh_secrets (chmod 600), and source it: [[ -f "$HOME/.zsh_secrets" ]] && source "$HOME/.zsh_secrets". Do the move with a script that never echoes values (awk by block marker, redirect into the 600 file). ~/.zsh_secrets is naturally not Mackup-synced (the zsh app config covers only .zshrc/.zshenv/.zprofile).

Step 5 — Verify

zsh -lic '
  print "rc loaded ok"
  print "PATH total=${#path} unique=$(printf "%s\n" $path | sort -u | wc -l)"
  print "nvm entries=$(printf "%s\n" $path | grep -c "\.nvm")"
  command -v node nvm starship >/dev/null && print "tools resolve"
  [[ -n $NODE_OPTIONS ]] && print "NODE_OPTIONS exported"
'
git config --list >/dev/null && echo "gitconfig parses"

Prove: fresh login+interactive shell loads with no errors; node/nvm/starship resolve; PATH total == unique; nvm appears once; .gitconfig parses. Report verification results.

Then report: backup location, issues found, exact fixes applied, what was left untouched intentionally (and why), and the verification results.

Gotchas learned the hard way

• mv -i/cp -i/rm -i safety aliases silently turn a script mv into an interactive prompt that defaults to "no" → your edit looks applied but isn't. Use command mv -f (or cat tmp > file) for non-interactive overwrites in scripts, and always re-grep the target to confirm the change landed.
• Mackup symlinks / stale storage copies. Mackup's default engine may symlink a dotfile into its storage. If you ran mackup backup before extracting secrets, the storage copy still holds them — re-run mackup backup after the edit so storage gets the clean file, and verify the storage copy has 0 secrets. Also: overwriting a mackup-symlinked file with mv -f replaces the symlink with a regular file (breaks the link) — check [ -L file ] first.
• Non-zsh shells: detect with echo "$SHELL"; adapt the same five steps (bash: .bashrc/.bash_profile/.profile, bash -lic; fish: ~/.config/fish/config.fish, fish -lc). If there's no nvm, skip the nvm items.