feat: add state file versioning

[angelorc]

Summary

• Add stateVersion field to VmState interface (current version: 1)
• Auto-migrate legacy alpha state files (v0 → v1) on load
• New VMs are created with stateVersion: 1 from the start

Changes

• src/lib/vm-state.ts — version field, migration logic in load(), version stamp in save()
• src/commands/create/state.ts — include stateVersion in buildInitialVmState()
• src/stores/memory.ts — stamp stateVersion in MemoryVmStateStore.save()

Test plan

• bun run test — 10 tests pass
• bun run lint — clean
• Old alpha.26 state files load and auto-upgrade to v1
• New state files include stateVersion: 1

Summary by CodeRabbit

• New Features
  • Introduced state file versioning with automatic migration support. Legacy state files are automatically migrated to the current version when accessed, ensuring seamless compatibility and enabling future state structure updates without manual intervention.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
vmsan	Ignored		Mar 7, 2026 3:18pm

[coderabbitai]

📝 Walkthrough

Walkthrough

The changes introduce a state versioning mechanism for VM state storage with automatic migration support. A new constant CURRENT_STATE_VERSION and stateVersion field are added to the VM state interface. State files are now versioned on save operations, and legacy state files without version information are automatically migrated when loaded.

Changes

Cohort / File(s)	Summary
Changelog Documentation .changeset/state-versioning.md	Changeset entry documenting a minor version change for the introduction of state file versioning support.
Core Versioning Logic src/lib/vm-state.ts	Introduces CURRENT_STATE_VERSION constant, adds stateVersion field to VmState interface, implements automatic migration of legacy state files (v0 → v1) on load, and re-saves migrated state.
Versioning Integration src/commands/create/state.ts, src/stores/memory.ts	Apply CURRENT_STATE_VERSION to the stateVersion field when building and saving VM state instances.
Test Coverage tests/unit/vm-state.test.ts	Expands tests with legacy state handling, auto-migration verification, temporary filesystem management for file-based store testing, and updates existing test data to include stateVersion field.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A version to remember, in files so grand,
Migration magic, by careful hand,
Legacy states find their way to v1,
Hopping through time, the versioning's done! 🌟

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: add state file versioning' directly and clearly describes the main change in the PR: introducing state file versioning to the VM state store.

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

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/state-versioning

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

🧹 Nitpick comments (1)

src/stores/memory.ts (1)

12-15: Versioning stamp looks good, but consider migration parity with FileVmStateStore.

The save() correctly stamps stateVersion before cloning and storing. However, unlike FileVmStateStore.load() (which migrates legacy states without stateVersion), MemoryVmStateStore.load() does not perform migration.

This is likely acceptable since MemoryVmStateStore is primarily used for testing and legacy states wouldn't naturally exist in memory. However, if you ever load raw JSON test fixtures directly into the map, they won't be auto-migrated.

🤖 Prompt for AI Agents

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

In `@src/stores/memory.ts` around lines 12 - 15, MemoryVmStateStore.save()
currently stamps stateVersion but MemoryVmStateStore.load() lacks the migration
logic present in FileVmStateStore.load(); update MemoryVmStateStore.load() to
detect legacy VmState objects missing stateVersion and run the same
migration/path-upgrade routine used by FileVmStateStore.load() (reuse the
migration helper or extraction logic) so in-memory fixtures or raw JSON states
get auto-migrated before being returned or used.

🤖 Prompt for all review comments with AI agents

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

Nitpick comments:
In `@src/stores/memory.ts`:
- Around line 12-15: MemoryVmStateStore.save() currently stamps stateVersion but
MemoryVmStateStore.load() lacks the migration logic present in
FileVmStateStore.load(); update MemoryVmStateStore.load() to detect legacy
VmState objects missing stateVersion and run the same migration/path-upgrade
routine used by FileVmStateStore.load() (reuse the migration helper or
extraction logic) so in-memory fixtures or raw JSON states get auto-migrated
before being returned or used.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a1c6c13e-4b43-4ef1-a583-a2cd4ca25706

📥 Commits

Reviewing files that changed from the base of the PR and between 7d39364 and 2b174a6.

📒 Files selected for processing (5)

• .changeset/state-versioning.md
• src/commands/create/state.ts
• src/lib/vm-state.ts
• src/stores/memory.ts
• tests/unit/vm-state.test.ts