## Summary
Fix the dev-VM bootstrap so `node` and `pnpm` are on `PATH` in zsh sessions. On a fresh VM provisioned with `docs/setup/scripts/`, a freshly-cloned checkout fails to run anything (`command not found: pnpm`, and `node` too) because the nvm init never reaches the interactive shell.
## Root cause
Two setup scripts interact badly:
- `20-zsh.sh` patches `~/.bashrc` with an `exec zsh -l` hand-off on interactive shells (chsh is blocked on the corp VM, so this is how zsh becomes the effective shell), and patches `~/.zshrc` with theme/plugins/fzf only.
- `40-node.sh` runs the upstream nvm installer, which appends its init block to **`~/.bashrc`** (its default target).
Because `20-zsh.sh` runs first, the `exec zsh -l` guard sits **above** the nvm block in `~/.bashrc`. On every interactive shell, bash execs into zsh before reaching the nvm block — so it never runs — and `~/.zshrc` has no nvm init at all. Net result: zsh sessions have neither `node` nor `pnpm` on `PATH`, even though nvm + Node + corepack installed correctly.
This is a procedure bug, not a one-off: every VM built from these scripts hits it.
## Fix
`40-node.sh` now mirrors the nvm init block into `~/.zshrc` after enabling corepack — idempotent via a managed marker, same pattern `20-zsh.sh` already uses for its `~/.bashrc` patch:
```sh
# Managed by docs/setup/scripts/40-node.sh — nvm init for zsh.
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
```
`docs/setup/01-dev-debian-vm-setup.md` — the `40-node.sh` row in the bootstrap table now notes the `~/.zshrc` patch and why it is needed.
## What lands
| File | Change |
| --- | --- |
| `docs/setup/scripts/40-node.sh` | Append an idempotent nvm-init block to `~/.zshrc` after corepack enable. |
| `docs/setup/01-dev-debian-vm-setup.md` | Document the `~/.zshrc` nvm patch in the `40-node.sh` table row. |
## Manual remediation for already-provisioned VMs
VMs built before this fix won't be retroactively patched (the scripts are idempotent and skip already-installed nvm). On those, run once:
```sh
cat >> ~/.zshrc <<'EOF'
# nvm
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
EOF
exec zsh -l
```
(Or re-run `40-node.sh` once this lands — the marker check makes it safe; it will add the block and skip the rest.)
## Test plan
- [x] `bash -n docs/setup/scripts/40-node.sh` — syntax valid.
- [x] Manual remediation block verified on the affected VM: after appending + `exec zsh -l`, `node --version` (v24) and `pnpm --version` (10.34.1) both resolve.
- [ ] Next fresh VM bootstrap: `node` + `pnpm` resolve in the first zsh session with no manual step.
- [ ] Re-running `40-node.sh` on an already-set-up VM is a no-op on the nvm install and adds the `~/.zshrc` block exactly once (marker idempotency).
## Related
- `docs/setup/01-dev-debian-vm-setup.md` — dev-VM bootstrap procedure.
- `20-zsh.sh` — owns the `.bashrc` → zsh hand-off this fix complements.
---------
Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr>
Reviewed-on: #255
Step-by-step setup procedures for new contributors. Each file is self-contained and idempotent — they document the state a developer should reach, not the order in which it must be done.
Default — a dev who has just received a fresh dev VM from the infra team. Covers the full path: zsh + Oh My Zsh + Powerlevel10k, modern CLI tooling, Node via nvm, Docker CE, system tuning, optional VM hardening, project clones, the two IDE flows (VSCode Remote-SSH and Devcontainer), the hybrid (local + VM) mode.
Reference notes on the Angular + Nx workspace layout.
scripts/
Modular setup scripts called from the doc above. Each is idempotent, each can be re-run safely. Run via the orchestrator (bootstrap.sh) or individually.
Symlinks docs/setup/dotfiles/aliases.zsh → ~/.oh-my-zsh/custom/aliases.zsh. Copies docs/setup/dotfiles/gitconfig.txt to ~/.gitconfig with prompted identity.
dotfiles/
Project-wide dotfile templates installed by 80-dotfiles.sh. Versioned so a fresh clone has everything it needs — notes/ is gitignored and was the wrong home for these.
Base ~/.gitconfig template (aliases, colour, default branch, editor). Identity (user.name / user.email) is prompted at install and overlaid via git config --global.
julien
645f81a443