Skip to content

Commit c4e6259

Browse files
authored
docs: refresh CLAUDE.md + SPEC §T after fix-wave (#116)
Closes #106. Squash-merged per CONTRIBUTING.md.
1 parent 8f8d433 commit c4e6259

2 files changed

Lines changed: 42 additions & 34 deletions

File tree

‎CLAUDE.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ go test ./internal/detector/... -run TestNvm # single test
2121
cmd/nodeup/main.go entrypoint; injects version/commit/date via ldflags
2222
internal/cli/ cobra command wiring — thin layer, delegates to internal/
2323
root.go NewRootCmd; registers all subcommands
24-
upgrade.go nodeup upgrade (Phase 4, PR #20 open)
24+
upgrade.go nodeup upgrade (Phase 4, merged)
2525
check.go / list.go / packages.go / config.go / version.go
2626
internal/detector/ Manager interface + one file per manager
2727
detector.go DetectAll(), ResolveManager()
@@ -30,12 +30,14 @@ internal/node/
3030
dist.go nodejs.org/dist/index.json client + 24h TTL cache
3131
internal/packages/ npm global snapshot / restore / migrate (merged in PR #19)
3232
snapshot.go Snapshot(ctx, managerName, version) → ~/.../snapshots/<mgr>-<ver>.json
33-
Restore(ctx, managerName, version)
34-
RestoreFromSnapshot(ctx, path)
33+
Restore(ctx, managerName, version) ([]PackageResult, error)
34+
RestoreFromSnapshot(ctx, path) ([]PackageResult, error)
35+
report.go MigrationReport: per-package results, Save() → ~/.../reports/migration-<ts>.json
36+
sentinel.go UpgradeSentinel: in-progress marker for interrupted-upgrade replay
3537
internal/platform/
3638
platform.go DataDir(), SnapshotsDir(), CacheDir(), LockPath(), IsWindows(), …
3739
shell.go RunShell() — all shell exec goes here
38-
internal/ui/ (planned, not yet implemented) all user-facing output
40+
internal/ui/ scaffold (mode.go + theme.go + writer.go) merged via #74 PR1; spinners/huh/full migration tracked by #105
3941
```
4042

4143
## Key invariants — read before writing code
@@ -50,9 +52,9 @@ internal/ui/ (planned, not yet implemented) all user-facing output
5052

5153
**Platform-specific code:** Use `//go:build windows` build tags on `*_windows.go` files. Files without build tags must compile on all three OSes.
5254

53-
**Dependencies:** No new dependencies without a rationale line in the PR body. Core runtime deps: `cobra`, `Masterminds/semver/v3`, `yaml.v3`. Planned but not yet in `go.mod`: `huh`, `bubbletea`, `lipgloss` (the Charm stack for `internal/ui` — see #74).
55+
**Dependencies:** No new dependencies without a rationale line in the PR body. Core runtime deps: `cobra`, `Masterminds/semver/v3`, `yaml.v3`, `lipgloss` (for `internal/ui` — see #74). Planned but not yet in `go.mod`: `huh`, `bubbletea` (the remaining Charm stack for `internal/ui` spinners + prompts — see #105).
5456

55-
**Manager detection order:** `--manager` flag → `~/.nodeup/config.yaml` → auto-detect (env vars → PATH → well-known dirs). `DetectAll()` returns a `Registry`; `ResolveManager(reg, preferred)` picks one or errors. When multiple managers found and no preference, the caller should use `ResolveInteractive` (not yet implemented).
57+
**Manager detection order:** `--manager` flag → `~/.nodeup/config.yaml` → auto-detect (env vars → PATH → well-known dirs). `DetectAll()` returns a `Registry`; `ResolveManager(reg, preferred)` picks one or errors. When multiple managers found and no preference, the caller should use `ResolveInteractive` (planned under #105 as part of the `huh` migration).
5658

5759
**Packages to skip during migration:** `npm`, `corepack`, `npx` — these are bundled with Node and must not be migrated.
5860

@@ -125,8 +127,8 @@ orchestrator.
125127
| 4 — Upgrade command + UI | Done | merged |
126128
| 5 — Config subsystem | Done | merged |
127129
| 6 — Cross-platform polish | Done | merged (interrupted-upgrade sentinel, `QuotePath`, system-node classifier) |
128-
| 7 — Distribution packaging | In progress | partial — post-upgrade cleanup prompt merged; GoReleaser/brew/scoop/npm tracked by #17 / #18 |
129-
| 8 — v1.0.0 release | In progress | blocked on Phase 7 distribution (#17 / #18) |
130+
| 7 — Distribution packaging | Done | GoReleaser, brew/scoop/npm wrappers all shipped (#17, #18); manual v1.0.0 npm publish tracked by #35 |
131+
| 8 — v1.0.0 release | Done | `nodeupx@1.0.1` live on npm (closes #35); trusted-publisher OIDC flow in place for future tags |
130132

131133
## On-disk data layout
132134

‎SPEC.md‎

Lines changed: 32 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# SPEC — nodeup
22

33
Distilled from code (README, CLAUDE.md, CONTRIBUTING.md, docs/*, and
4-
`internal/*` source) on 2026-07-02, post-merge of PR #56 (`5ddbe43`).
4+
`internal/*` source). Last refresh: 2026-07-05 (post #103 fix-wave;
5+
§C/V2 + §T updated to match current state).
56
Caveman encoding per FORMAT.md convention (not present at repo root —
67
using shapes from the caveman skill).
78

@@ -25,9 +26,8 @@ manual steps, single static binary, no Node runtime dependency.
2526
`/` or `\`.
2627
- `*_windows.go` → `//go:build windows`; other files compile ∀ 3 OS
2728
(macOS, Linux, Windows).
28-
- ∀ user-facing output → `internal/ui` (? not yet implemented — currently
29-
direct `cmd.Printf`/`fmt.Fprintf` throughout `internal/cli`, tolerated
30-
as pre-`ui`-package debt).
29+
- ∀ user-facing output → `internal/ui` (scaffold merged via #74 PR1;
30+
spinners + huh prompts + full call-site migration tracked by #105).
3131
- packages `{npm, corepack, npx}` ⊥ migrate (bundled w/ Node itself).
3232
- Manager resolution order: `--manager` flag → `~/.nodeup/config.yaml` →
3333
env vars → PATH → well-known dirs.
@@ -38,15 +38,16 @@ manual steps, single static binary, no Node runtime dependency.
3838

3939
- cmd: `nodeup upgrade [--lts|--current|--dry-run|--yes|--no-migrate|--no-cleanup|--cleanup|--cleanup-version <v>|--manager <name>]`
4040
- cmd: `nodeup check [--json]`
41-
- cmd: `nodeup list [--json]` (? stub only, ⊥ implemented — see T4)
41+
- cmd: `nodeup list [--json]`
4242
- cmd: `nodeup packages {snapshot|restore [--from <path>]|diff}`
4343
- cmd: `nodeup config {show|get <key>|set <key> <val>|init [--force]}`
4444
- cmd: `nodeup version`
4545
- api: `GET https://nodejs.org/dist/index.json` → `Manifest ([]ManifestVersion)`
4646
- file: `~/.nodeup/config.yaml` (override: `$NODEUP_CONFIG`; home override: `$NODEUP_HOME`)
4747
- file: `<DataDir>/snapshots/<manager>-<node-version>.json`
48+
- file: `<DataDir>/reports/migration-<timestamp>.json` (one per upgrade, success or partial)
4849
- file: `<DataDir>/upgrade-in-progress.json` (sentinel)
49-
- file: `<DataDir>/nodeup.lock` (? built, ⊥ wired — see T3)
50+
- file: `<DataDir>/nodeup.lock`
5051
- env: `NODEUP_MANAGER`, `NODEUP_TRACK_LTS`, `NODEUP_TRACK_CURRENT`,
5152
`NODEUP_PACKAGES_MIGRATE`, `NODEUP_PACKAGES_STRATEGY`,
5253
`NODEUP_CACHE_TTL`, `NODEUP_CONFIG`, `NODEUP_HOME`
@@ -61,7 +62,9 @@ manual steps, single static binary, no Node runtime dependency.
6162
## §V Invariants
6263

6364
- V1: ∀ shell exec → `platform.RunShell()` | `RunShellScript()` (never raw `os/exec`).
64-
- V2: ∀ user-facing string → `internal/ui` (? aspirational, see §C).
65+
- V2: ∀ user-facing string → `internal/ui` (partial — scaffold via #74 PR1;
66+
full migration tracked by #105; cmd.Printf still present in upgrade/check/
67+
list/packages/config/cleanup).
6568
- V3: ∀ error return → handled, wrapped w/ `%w` for context.
6669
- V4: ∀ cobra `RunE` → `cmd.Context()`, ⊥ `context.Background()`.
6770
- V5: ∀ path → `filepath.Join()`, ⊥ hardcoded separators.
@@ -91,29 +94,32 @@ manual steps, single static binary, no Node runtime dependency.
9194
so version strings are safe as shell args by construction.
9295
- V21: lock file (`<DataDir>/nodeup.lock`) ! held around any critical
9396
section that mutates installed Node versions or the config file
94-
concurrently (? built but not wired — see T3).
97+
concurrently.
9598

9699
## §T Tasks
97100

98101
id|status|task|cites
99-
T1|.|fix snapshot/restore version-key mismatch in upgrade flow|V13,#42
100-
T2|.|fix NVM_DIR shell-injection surface (QuotePath doesn't escape `$`/backtick)|V15,#43
101-
T3|.|wire AcquireLock/Release into upgrade + config set/init|V21,#44
102-
T4|.|implement `nodeup list` (currently a stub)|I.list,#45
103-
T5|.|fix installPackages abort-on-first-failure; wire or delete MigrationReport|V19,#46
104-
T6|.|fix sentinel lifecycle (deleted on restore failure; never cleared after manual restore)|#47
105-
T7|.|add HTTP timeout/retry/context + atomic cache write to node manifest fetch|#48
106-
T8|.|fix `context.Background()` → `cmd.Context()` in internal/cli/packages.go|V4,#49
107-
T9|.|fix asdf ASDF_DIR vs ASDF_DATA_DIR inconsistency (docs + system_node.go)|V7,#50
108-
T10|.|validate manager-name arg against allowlist in packages restore/diff|V5,#51
109-
T11|.|add context.Context param to Manager interface methods|V4,#53
110-
T12|.|refresh CLAUDE.md known-bugs section + phase-status table|#54
111-
T13|.|fix `--yes` silently overriding `--no-cleanup`|V16,V18,#57
112-
T14|.|fail closed (not open) when Current() errors during cleanup|V14,#58
113-
T15|.|verify/fix `n` manager's reliance on `n current` subcommand|#59
114-
T16|.|fix cleanup docs inaccuracies (CHANGELOG issue ref, nvm-windows note, PATH failure mode, Phase 7 conflict)|#60
115-
T17|.|dead-code cleanup: report.go, FileOverlay(), confirm var, fnm.go error wrap, nvm Current() test gap|#61
116-
T18|.|design + implement internal/ui output layer|V2,#74
102+
T1|x|fix snapshot/restore version-key mismatch in upgrade flow|V13,#42,#77
103+
T2|x|fix NVM_DIR shell-injection surface (QuotePath doesn't escape `$`/backtick)|V15,#43,#78
104+
T3|x|wire AcquireLock/Release into upgrade + config set/init|V21,#44,#79
105+
T4|x|implement `nodeup list` (currently a stub)|I.list,#45,#80
106+
T5|x|fix installPackages abort-on-first-failure; wire or delete MigrationReport|V19,#46,#103
107+
T6|x|fix sentinel lifecycle (deleted on restore failure; never cleared after manual restore)|#47,#81
108+
T7|x|add HTTP timeout/retry/context + atomic cache write to node manifest fetch|#48,#82
109+
T8|x|fix `context.Background()` → `cmd.Context()` in internal/cli/packages.go|V4,#49,#83
110+
T9|x|fix asdf ASDF_DIR vs ASDF_DATA_DIR inconsistency (docs + system_node.go)|V7,#50,#84
111+
T10|x|validate manager-name arg against allowlist in packages restore/diff|V5,#51,#85
112+
T11|x|add context.Context param to Manager interface methods|V4,#53,#101
113+
T12|x|refresh CLAUDE.md known-bugs section + phase-status table|#54,#96
114+
T13|x|fix `--yes` silently overriding `--no-cleanup`|V16,V18,#57,#86
115+
T14|x|fail closed (not open) when Current() errors during cleanup|V14,#58,#87
116+
T15|x|verify/fix `n` manager's reliance on `n current` subcommand|#59,#88
117+
T16|x|fix cleanup docs inaccuracies (CHANGELOG issue ref, nvm-windows note, PATH failure mode, Phase 7 conflict)|#60,#97
118+
T17|x|dead-code cleanup: report.go, FileOverlay(), confirm var, fnm.go error wrap, nvm Current() test gap|#61,#98
119+
T18|.|design + implement internal/ui output layer|V2,#74,#105
120+
T19|.|fix double-prompt + sticky-no-override at cleanup decision point|#76,#95
121+
T20|x|rest of cleanup/chore/ci/release batch|#62-#69,#89-#94,#99,#100,#107-#109
122+
T21|.|doc drift: CLAUDE.md ui/lipgloss/phase-table stale; SPEC §T stale|#106
117123

118124
## §B Bugs
119125

0 commit comments

Comments
 (0)