nodeup 0.1.1

Rustup-like Node.js version manager
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

# nodeup

`nodeup` is a Rust-based Node.js version manager with rustup-like commands, deterministic runtime resolution, and managed alias dispatch for `node`, `npm`, and `npx`.

## Overview

- Manage multiple Node.js runtimes from one CLI.
- Resolve active runtime consistently with explicit, override, and default selectors.
- Use human-friendly output for operators and JSON output for automation.
- Run `node`, `npm`, and `npx` through one binary by executable-name dispatch.

## Quick Command Reference

- `nodeup toolchain list [--quiet|--verbose]`
- `nodeup toolchain install <runtime>...`
- `nodeup toolchain uninstall <runtime>...`
- `nodeup toolchain link <name> <path>`
- `nodeup default [runtime]`
- `nodeup show active-runtime`
- `nodeup show home`
- `nodeup update [runtime]...`
- `nodeup check`
- `nodeup override list`
- `nodeup override set <runtime> [--path <path>]`
- `nodeup override unset [--path <path>] [--nonexistent]`
- `nodeup which [--runtime <runtime>] <command>`
- `nodeup run [--install] <runtime> <command>...`
- `nodeup self update`
- `nodeup self uninstall`
- `nodeup self upgrade-data`
- `nodeup completions <shell> [command]`

## Runtime Resolution Precedence

Runtime resolution follows a stable order:

1. Explicit selector (`run <runtime>`, `which --runtime <runtime>`)
2. Directory override (`override set`)
3. Global default (`default`)

If no selector resolves, commands fail with deterministic `not-found` errors.

## Output and Logging

- Global output mode: `--output human|json` (default: `human`)
- `human` mode:
  - command results and logs are written for operators
  - default log filter is `nodeup=info` for management commands
- `json` mode:
  - success payloads are written to stdout as JSON
  - handled failures are written to stderr as JSON envelopes
    - fields: `kind`, `message`, `exit_code`
    - `message` follows `<cause>. Hint: <next action>` for actionable recovery guidance
  - default logging is off unless explicitly enabled via `RUST_LOG`
- `completions` command:
  - always writes raw completion script text to stdout
  - does not wrap completion output in JSON, even when `--output json` is set

Color control:

- `NODEUP_LOG_COLOR=always|auto|never` (default `always`)
- `NO_COLOR` disables color when `NODEUP_LOG_COLOR` is unset or `auto`

## Completions

`nodeup completions` generates shell completion scripts for:

- `bash`
- `zsh`
- `fish`
- `powershell`
- `elvish`

Scope filtering:

- `nodeup completions <shell>` generates completions for all top-level commands.
- `nodeup completions <shell> <command>` accepts only top-level command scopes:
  - `toolchain`, `default`, `show`, `update`, `check`, `override`, `which`, `run`, `self`, `completions`
  - invalid scopes fail with `invalid-input`.

## Testing Strategy

`nodeup` validation combines unit tests and end-to-end CLI integration tests.

- Unit tests cover selectors, resolver, release index cache behavior, logging mode selection, and installer helpers.
- CLI integration tests cover command contracts, JSON error envelopes, selector precedence, override lifecycle, update/check branches, self-management commands, and alias dispatch (`node`, `npm`, `npx`).

Run locally from repository root:

```bash
cargo fmt --all
cargo test -p nodeup
cargo test
```

## Troubleshooting

- Runtime not installed:
  - use `nodeup toolchain install <runtime>` or `nodeup run --install <runtime> ...`
- No selector resolved:
  - set one with `nodeup default <runtime>` or `nodeup override set <runtime>`
- Linked runtime failures:
  - verify `<path>/bin/node` exists before `toolchain link`
- JSON parsing issues in automation:
  - use `--output json` and keep `RUST_LOG` unset (or `off`) to avoid log noise
- Error troubleshooting:
  - follow the `Hint:` action in the error message first, then rerun with `RUST_LOG=nodeup=debug` when deeper diagnostics are needed

## Documentation Links

- Project index: [`docs/project-nodeup.md`](../../docs/project-nodeup.md)
- Runtime contract: [`docs/crates-nodeup-foundation.md`](../../docs/crates-nodeup-foundation.md)
- Public guide: [`apps/public-docs/nodeup.mdx`](../../apps/public-docs/nodeup.mdx)