chore: standardize .version contract with unified parser/writer (lega…

[eva57gr]

…cy + JSON)

[Lightheartdevs]

Review: Standardize .version contract with unified parser/writer

Good intent — centralizing version parsing is the right move. A few things need addressing before this merges.

Blocking

1. python3 hard dependency without fallback. dream-update.sh and migrate-config.sh now exit 1 if python3 is missing. Previously these only needed jq + bash. Adding a mandatory runtime dep that wasn't required before needs either a jq-only fallback path or a clear migration note. On minimal Docker images or fresh installs this could break the update path.

2. No tests for the new shared library. version-file.sh is now a critical contract — it parses both legacy plain-text and JSON formats, handles missing/empty/malformed files, and does semver comparison. The existing test infrastructure (tests/contracts/) should cover this. At minimum: round-trip write/read, legacy format parsing, malformed JSON fallback, semver comparison edge cases.

3. Version source divergence with PR #350. After both merge, version lives in three places with no single source of truth:

   • PR #349: reads/writes .version file (JSON/plain-text)
   • PR #350: reads DREAM_VERSION from .env, falls back to manifest.json

   dream-update.sh check and dream update (from dream-cli) would report different installed versions if .version and .env drift apart. Coordinate with #350 on which is canonical before merging either.

Non-blocking

• Silent Python failures. If the heredoc Python script fails (permission error, etc.), bash functions silently return empty strings. Under set -euo pipefail, empty version strings fed into comparisons could cause unexpected behavior. Surface errors: || { log_error "version parse failed"; return 1; }.
• || true after shift in version_file_upsert_fields — technically violates CLAUDE.md conventions. Use a guard instead.
• Pre-release suffix handling (2.0.0-rc1 → 2.0.0, suffix silently dropped) is reasonable but undocumented.
• cmd_check exit code change (exit 2 for update available) is a behavioral change for any external automation. The help text documents it, but worth a note in PR description.

The version-file abstraction is solid architecture. Just needs tests, the dependency story sorted, and coordination with #350.

[Lightheartdevs]

Review — Good standardization, coordinates with #350 and #358.

What it does

Introduces scripts/version-file.sh as a unified parser/writer for the .version file, handling both legacy plain-text and JSON formats. Refactors dream-update.sh to use these helpers instead of inline jq calls.

Changes

• New version-file.sh with version_file_get_current(), version_file_upsert_fields(), version_file_migrate() — handles legacy text → JSON migration
• dream-update.sh refactored to use the new helpers
• cmd_check gets --json mode for structured output
• Semver comparison refactored to use _semver_triplet() helper
• emit_check_json() for structured check output

Coordination

• #350 (@buddy0323) adds _check_version_compat() to dream-cli which reads .version — should use this PR's parser
• #358 (merged) also writes to .version via jq — would benefit from using this PR's version_file_upsert_fields()
• These three PRs form a cohesive "version management" story

Concern

Adds python3 as a hard dependency for dream-update.sh — was previously optional. Justified since the JSON parsing is more robust, but should be documented.

Has CHANGES_REQUESTED from prior reviewer. Address feedback, then coordinate merge order with #350.

[Lightheartdevs]

Closing per maintainer request. The work here is appreciated — please reopen or create a fresh PR if you'd like to continue this effort.