From f4cb2c950ee9b52ff6160acf38c4851c7701fee9 Mon Sep 17 00:00:00 2001 From: dipto0321 Date: Fri, 3 Jul 2026 12:14:31 +0600 Subject: [PATCH] docs: refresh CLAUDE.md to match current state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three concrete inaccuracies and one bonus cleanup in CLAUDE.md: - Known-bugs entry described an already-fixed bug (LTSCodename *string with custom UnmarshalJSON, shipped per CHANGELOG.md Unreleased). Reworded to describe the FIXED shape and warn against "fixing" it back to a plain bool. - Phase-status table listed Phases 5-6 as Not started; both are merged. Updated Phases 4-6 to Done, Phase 7 to In progress, Phase 8 to In progress (blocked on #17/#18). - Architecture diagram pointed at a non-existent restore.go; both Restore and RestoreFromSnapshot live in snapshot.go. Replaced. - Bonus: yaml.v3 is in go.mod (core dep); gjson was never added — removed from the planned list. CHANGELOG entry added under [Unreleased] / ### Fixed. Closes #54 --- CHANGELOG.md | 23 +++++++++++++++++++++++ CLAUDE.md | 22 ++++++++++++++-------- 2 files changed, 37 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ff6182a..b4ba494 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -646,6 +646,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 the buggy double-prompt behavior) are updated to assert the new correct behavior; `TestCleanupPrompt_DeleteAllSkipsPerVersionPrompt` is the explicit regression test for #76. Closes #76. +- `CLAUDE.md`: refresh the stale sections that have drifted out + of sync with the actual code and with `README.md` / + `CHANGELOG.md`. The "Known bugs (do not re-introduce)" entry + used to describe a `ManifestVersion.LTS bool` + useless + `TS string \`json:"ts"\`` fallback — but the actual code at + `internal/node/dist.go:25-62` already uses `LTSCodename *string` + with a custom `UnmarshalJSON` that handles the nodejs.org `lts` + JSON union correctly. The pre-fix shape is gone; the doc would + have misled a future contributor or AI assistant into + "fixing" something that isn't broken. The phase-status table + listed Phase 5 (Config subsystem) and Phase 6 (Cross-platform + polish) as "Not started" — both are fully implemented per the + CHANGELOG's Unreleased section and per `README.md`'s own + Project-status table, which marks Phases 1-6 done. Updated + Phases 4-6 to "Done" and Phase 7 to "In progress" (the + GoReleaser / brew / scoop / npm distribution work tracked by + #17 / #18 is genuinely outstanding). The architecture + diagram listed `internal/packages/restore.go` for `Restore` + — that file doesn't exist; `Restore` and the additional + `RestoreFromSnapshot` both live in `snapshot.go`. The + dependencies line listed `gjson` and `yaml.v3` as "planned + but not yet in go.mod" — `yaml.v3` is in go.mod (used by + the config subsystem), `gjson` was never added. Closes #54. ## [0.0.0] - 2024-07-01 diff --git a/CLAUDE.md b/CLAUDE.md index 8875d83..24e2227 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -30,7 +30,8 @@ internal/node/ dist.go nodejs.org/dist/index.json client + 24h TTL cache internal/packages/ npm global snapshot / restore / migrate (merged in PR #19) snapshot.go Snapshot(ctx, managerName, version) → ~/.../snapshots/-.json - restore.go Restore(ctx, managerName, version) + Restore(ctx, managerName, version) + RestoreFromSnapshot(ctx, path) internal/platform/ platform.go DataDir(), SnapshotsDir(), CacheDir(), LockPath(), IsWindows(), … shell.go RunShell() — all shell exec goes here @@ -49,7 +50,7 @@ internal/ui/ (planned, not yet implemented) all user-facing output **Platform-specific code:** Use `//go:build windows` build tags on `*_windows.go` files. Files without build tags must compile on all three OSes. -**Dependencies:** No new dependencies without a rationale line in the PR body. Core runtime deps: `cobra`, `Masterminds/semver/v3`. Planned but not yet in `go.mod`: `huh`, `bubbletea`, `lipgloss`, `gjson`, `yaml.v3`. +**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). **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,7 +58,12 @@ internal/ui/ (planned, not yet implemented) all user-facing output ## Known bugs (do not re-introduce) -`ManifestVersion.LTS` in `internal/node/dist.go:22` is typed `bool`, but the nodejs.org API returns a union: `false` for Current releases and a string codename (e.g. `"Iron"`) for LTS releases. The fallback `TS string \`json:"ts"\`` on line 23 does not help because the real JSON key is `lts`, not `ts`. Fix requires a custom `UnmarshalJSON` or `json.RawMessage` on the `LTS` field. This is a latent bug activated by `upgrade.go` calling `FetchManifest()`. Tracked in PR #20 review. +`ManifestVersion.LTS` in `internal/node/dist.go:25-62` is now properly +typed as `LTSCodename *string` with a custom `UnmarshalJSON` that +handles the nodejs.org `lts` JSON union (Current releases have +`lts: false`, LTS releases have `lts: ""`). The pre-fix +shape (typed `bool` with a useless `TS string \`json:"ts"\`` fallback) +is gone. Don't "fix" this back to a plain `bool`. ## Commit & PR conventions @@ -116,11 +122,11 @@ orchestrator. | 1 — Detector engine | Done | merged | | 2 — Node version API | Done | merged | | 3 — Package snapshot/restore | Done | merged (PR #19) | -| 4 — Upgrade command + UI | In progress | `feat/upgrade/end-to-end` / PR #20 | -| 5 — Config subsystem | Not started | — | -| 6 — Cross-platform polish | Not started | — | -| 7 — Distribution packaging | Not started | — | -| 8 — v1.0.0 release | Not started | — | +| 4 — Upgrade command + UI | Done | merged | +| 5 — Config subsystem | Done | merged | +| 6 — Cross-platform polish | Done | merged (interrupted-upgrade sentinel, `QuotePath`, system-node classifier) | +| 7 — Distribution packaging | In progress | partial — post-upgrade cleanup prompt merged; GoReleaser/brew/scoop/npm tracked by #17 / #18 | +| 8 — v1.0.0 release | In progress | blocked on Phase 7 distribution (#17 / #18) | ## On-disk data layout