fix(release): stamp .version at publish time so CLI reports the real tag (#1239)

[ColinM-sys]

Summary

Closes #1239.

nemoclaw --version currently prints a stale hardcoded value (0.1.0) on every npm-installed copy, regardless of which tag was actually published.

Root cause

getVersion() in src/lib/version.ts tries three sources in order:

1. git describe --tags --match 'v*' — works in dev clones, fails inside an npm install (no .git)
2. .version file at repo root — meant to be stamped at publish time, but nothing ever writes it
3. package.json version — hardcoded to 0.1.0 and not bumped per-release

So in production, steps 1 and 2 always fail and the CLI always reports 0.1.0.

Fix

Two minimal changes to package.json, no source changes:

1. prepublishOnly now stamps .version from git describe --tags --match 'v*' before tsc runs.
2. .version is added to the files array so it ships in the npm tarball.

The existing getVersion() chain already prefers .version over package.json (proven by the existing "prefers .version file over package.json" test), so no runtime code needs to change.

Test plan

• Added a regression test in src/lib/version.test.ts mirroring the issue scenario: stale package.json (0.1.0) + correct .version (0.0.2) → asserts getVersion() returns 0.0.2.
• vitest run src/lib/version.test.ts passes (4/4).
• Manually verified locally: with .version present, getVersion() returns its contents; with it absent, falls through to git describe / package.json as before.

Why this approach over bumping package.json

Stamping a separate .version file:

• Avoids coupling release tags to hand-edited package.json bumps
• Doesn't conflict with whatever release tooling (release-please, semantic-release, etc.) the maintainers may adopt later
• Is the same pattern used by uv, ruff, and other projects with the same git-tag-vs-package-version drift problem
• Requires no changes to version.ts — leverages the fallback chain that already exists

Summary by CodeRabbit

• Chores

  • Package publication process enhanced to automatically generate version metadata from git tags and include that metadata in published distributions, improving version accuracy and consistency across releases.

• Tests

  • Added a regression test to ensure generated version metadata is detected and used when present, preventing stale package manifest versions from being relied upon.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f94322d8-22ed-4e13-bc71-c7cceddd3f65

📥 Commits

Reviewing files that changed from the base of the PR and between b57ce3f and d8e2216.

📒 Files selected for processing (2)

• package.json
• src/lib/version.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/lib/version.test.ts

---

📝 Walkthrough

Walkthrough

Prepublish now writes a .version file from git describe (stripping a leading v) and includes it in the published package. A test was added verifying getVersion() prefers the .version file over package.json when present.

Changes

Cohort / File(s)	Summary
Version Stamping Configuration package.json	prepublishOnly script now runs git describe --tags --match 'v*', strips a leading v, writes the result to .version, requires .version to be non-empty, then continues with the existing build steps; .version added to files for publication.
Version Stamping Tests src/lib/version.test.ts	New Vitest case writes a stale package.json and a .version file ("0.0.2") into the test dir, asserts getVersion({ rootDir }) returns .version contents, then cleans up and restores package.json.

Sequence Diagram(s)

sequenceDiagram
  participant Dev as Developer/CI
  participant Git as Git (tags)
  participant Prepub as prepublishOnly script
  participant NPM as npm publish
  participant Install as Installed package
  participant Runtime as getVersion()

  Dev->>Git: trigger publish
  Git-->>Prepub: git describe --tags --match 'v*'
  Prepub-->>Prepub: strip leading "v", write `.version`, test -s .version
  Prepub->>NPM: build & publish (includes `.version`)
  NPM-->>Install: package tarball (contains `.version`)
  Install->>Runtime: getVersion()
  alt `.version` exists
    Runtime-->>Install: return contents of `.version`
  else no `.version`
    Runtime-->>Install: fall back to `package.json` semver
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐇 I sniffed the tags and found a clue,

I wrote a dot-file, tidy and true.
Now installs hop with versions right,
no stale semver in morning light.
A carrot for the CI crew 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: stamping a .version file at publish time so the CLI reports the correct git tag version instead of the stale package.json version.
Linked Issues check	✅ Passed	The PR directly addresses issue #1239 by implementing the required fix: stamping .version from git describe at publish time and including it in the npm tarball so getVersion() returns the correct tagged version.
Out of Scope Changes check	✅ Passed	All changes are scoped to the version-stamping fix: package.json script/files modifications, a targeted regression test, and a test comment cleanup—no unrelated changes detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@package.json`:
- Line 19: The prepublishOnly script can create an empty .version when `git
describe` fails, causing getVersion() in src/lib/version.ts to fall back to
package.json and produce stale published versions; update the prepublishOnly
pipeline so the publish fails if tag resolution fails by ensuring the git
describe output is non-empty (for example capture output, test it with a shell
conditional and exit non-zero on empty, or append `|| exit 1` after git
describe), so .version is only written when a valid tag is obtained before
continuing with the nemoclaw install and tsc steps.

In `@src/lib/version.test.ts`:
- Line 37: Replace the GitHub URL in the inline comment within
src/lib/version.test.ts (the semver comment) with a plain issue reference like
"See issue `#1239`"; specifically edit the comment that currently reads "//
semver. See https://github.com/NVIDIA/NemoClaw/issues/1239" to remove the
external link and use "See issue `#1239`" (or equivalent plain text) so the test
file complies with the docs-link policy.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9ac3e067-e314-472c-b045-0510dabd7e4e

📥 Commits

Reviewing files that changed from the base of the PR and between bbec268 and a99f7d8.

📒 Files selected for processing (2)

• package.json
• src/lib/version.test.ts

[wscurran]

✨ Thanks for submitting this fix, which proposes a way to ensure the CLI reports the correct version by stamping it during publication.