Group J: pipx + npm global package channel

[thompsonson]

Structural gap. Today the install script has no pattern for installing pipx-managed Python tools or globally-installed npm packages, which leaves several in-use tools uncaptured and makes it awkward to land #25 (prek migration) cleanly.

Current state on pop-mini (2026-04-23)

Installed manually, not in dotfiles:

• pipx: git-filter-repo, pre-commit, reveal-cli
• npm globals: @mermaid-js/mermaid-cli

Changes

run_once_install-packages.sh.tmpl — new sections

pipx tools (cross-platform, after pipx is installed). Add near the existing OpenHands/uv block:

if command -v pipx >/dev/null 2>&1; then
  echo 'Installing pipx tools'
  for tool in git-filter-repo reveal-cli; do
    if ! pipx list --short 2>/dev/null | grep -q "^$tool "; then
      pipx install "$tool" || echo "Failed to install $tool — continuing"
    fi
  done
fi

Idempotent via pipx list --short check. || echo instead of || true so failures are visible in the output.

pre-commit deliberately excluded here — tracked by #25 (prek migration). Whichever of pre-commit/prek wins there plugs into this same loop.

npm globals (cross-platform, after fnm + Node.js LTS is set up):

if command -v npm >/dev/null 2>&1; then
  echo 'Installing npm global tools'
  npm_globals=(
    \"@mermaid-js/mermaid-cli\"
  )
  for pkg in \"${npm_globals[@]}\"; do
    if ! npm list -g --depth=0 \"$pkg\" >/dev/null 2>&1; then
      npm install -g \"$pkg\" || echo \"Failed to install $pkg — continuing\"
    fi
  done
fi

dot_local/bin/executable_sysup — doctor entries

• tools_dev: add git-filter-repo, reveal, mmdc
• get_version() cases:
  • git-filter-repo --version
  • reveal --version (reveal-cli binary)
  • mmdc --version (mermaid-cli binary)

dot_local/bin/executable_sysup — upgrade command (ties to #32, Group G)

Add handlers:

if command -v pipx >/dev/null 2>&1; then
  echo \"==> pipx\"
  pipx upgrade-all
fi

if command -v npm >/dev/null 2>&1; then
  echo \"==> npm -g\"
  npm update -g
fi

Order: after brew/apt, before rustup/nix. Cheap-ish — a few HTTP calls per tool.

CLAUDE.md — Package Management Workflow section

Add two new subsections under "Package Management Workflow → 1. Install Script":

### pipx tools (Python CLIs with isolated venvs)
Add to the `pipx install` loop in `run_once_install-packages.sh.tmpl`. Use pipx when the tool is a standalone Python CLI that shouldn't pollute the system Python environment.

### npm globals
Add to the `npm_globals` array in `run_once_install-packages.sh.tmpl`. Reserved for CLI tools with no better channel — if something is available via brew/apt, prefer that.

Verification checklist

• chezmoi execute-template renders cleanly on Linux and macOS.
• Fresh Linux VM after Node.js + pipx are set up: git-filter-repo --version, reveal --version, mmdc --version all work.
• sysup doctor reports the new tools with versions.
• sysup upgrade invokes pipx upgrade-all and npm update -g in order when both are present.
• Re-apply on a complete box: pipx/npm loops detect existing installs and skip.
• Tool failure in the loop (simulate with a bogus package name) does not abort the rest of the install script.

Scope notes

• The || echo fallback is deliberate — if a single pipx install fails transiently (PyPI hiccup), the next chezmoi apply or manual sysup upgrade picks it up.
• Not using corepack for package manager pinning — out of scope; npm-global is simpler and matches current usage.

Related

• Unblocks Add prek for pre-commit hooks (migrate from manual test runner) #25 (prek migration) — provides the pipx install path so prek/pre-commit can slot in without inventing a new pattern.
• Ties to Group G: sysup upgrade coverage for new toolchains #32 (Group G, sysup upgrade coverage) for the upgrade handlers.
• No dependency on Group A: Nix + devenv bootstrap (Linux-first) #26 (Group A, Nix) — pipx works independently.