fix: require explicit refresh for bundle version changes

[rksharma-owg]

Refs #4434

Description

A normal bundle install could advance an existing bundle record to a new version while leaving its owned components unchanged. Version-changing normal installs now fail before primitive work; same-version installs remain idempotent.

Local bundles have an explicit upgrade route: specify bundle install <path> --refresh --offline. The path can be a manifest file, directory, or ZIP. The flag uses the existing refresh implementation, reapplies owned components before advancing the record, and reports refreshed and removed counts. Catalog bundles can continue using specify bundle update <id>.

This addresses the existing-bundle version-change case in #4434. Independently installed components remain untouched and unowned under the existing no-collateral-removal policy; the independently-installed-components case remains open for a separate follow-up. Refresh retains the existing bounded rollback contract: previously installed components modified before a failure are not rolled back.

Related changes

Checked #4466–#4470. Only #4469 changes the same installer and lifecycle-test files; it moves record persistence into the rollback boundary, while this PR guards version changes and exposes the existing refresh path. Its patch passes git apply --check against this working tree. The other four PRs change separate reference, manifest, workflow, and primitive-version-validation paths.

Testing

• 86 focused install-flow, local-source, and bundle CLI tests passed.
• New CLI regressions cover manifest, directory, and ZIP upgrades. They fail on the prior commit because --refresh is unavailable, verify ordinary installs preserve the record and installed versions, and verify refresh applies all owned pins before advancing the record.
• uvx ruff@0.15.0 check src tests: passed.
• npx --yes markdownlint-cli2 docs/reference/bundles.md: passed.
• .venv/bin/specify bundle install --help: passed; the refresh option is visible.
• git diff --check: passed.
• Full suite: 7,525 passed, 195 skipped, 11 failed. The failures are in the PowerShell launcher and composed-template parity tests, the same local environment/platform categories reported before this update; the full local suite is not completely green.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance

OpenAI Codex worked autonomously on behalf of @rksharma-owg to investigate the feedback, implement the refresh option and regression tests, check related PRs, and run validation. The changes have not received human line-by-line review from the contributor.

[mnriem]

Thanks — this correctly fixes the primary #4434 failure (a version-changing normal install advancing the record past stale components), with a clean guard and regression test, and the disclosure is appreciated. One thing before merge: #4434 reported a second case that this doesn't cover — components installed individually before the bundle, where every primitive is classified "already present" so the new bundle record ends up with no contributed-component entries. As written, Closes #4434 would auto-close the issue while that half remains. Please either extend this to handle the individually-installed case (with a test), or change Closes #4434 to Refs #4434 and I'll keep the issue open for a follow-up. Also heads-up: #4466–#4470 ([@marcelsafin](https://github.com/marcelsafin)) touch the same installer.py version-integrity path — worth confirming no overlap. I'll trigger the automated review in parallel.

[Copilot]

🟡 Changes recommended

Local bundles cannot use the recommended update command, leaving them without an upgrade path.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Prevents normal bundle installs from advancing records across bundle-version changes while components remain stale.

Changes:

• Rejects version-changing installs unless refresh mode is enabled.
• Adds regression coverage ensuring records and primitives remain unchanged.

File summaries

File	Description
src/specify_cli/bundler/services/installer.py	Adds the version-change guard and guidance.
tests/integration/test_bundler_install_flow.py	Tests rejection and preserved state.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.