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. 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>. Local sources supply manifests, not component payloads: catalog-backed components still need network access. Offline failures now identify the component and instruct users to retry without --offline, rather than suggesting an ineffective pre-install workaround.

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

• 115 focused primitive, install-flow, local-source, and bundle CLI tests passed. New manifest/directory/ZIP cases use the real extension installer with mocked catalog I/O, prove offline failure leaves the existing payload and record unchanged, and prove a retry refreshes the catalog-backed component and record to the requested version.
• 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.
• Earlier full-suite run (not repeated for this review update): 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.

[mnriem]

The automated review surfaced a bigger issue than my earlier note: rejecting a version-changing bundle install and pointing users to bundle update breaks the exact case #4434 was reported for — local bundles. bundle update only resolves catalog bundles; it can't update a local/path-installed bundle (_local_manifest_source), and the original repro was bundle install <local bundle.yml> --offline. So as written, local-bundle users go from "silent stale record" to "no upgrade path at all," which is worse for them.

Please make the local-bundle case work end to end — either extend bundle update to accept a local path/manifest, or have the version-change guard perform the refresh for local bundles rather than just rejecting. And (from before) confirm whether #4434's second case is in scope — individually-installed components producing a record with no contributed-component entries; if not, change Closes #4434 to Refs #4434 so the issue stays open. Re-request once addressed.

[mnriem]

Thanks — --refresh for local sources is exactly the right fix; the per-source-type error message pointing to bundle update <id> vs install <path> --refresh resolves the dead-end cleanly. (My 17:16 comment crossed with your 15:00 commit — you'd already addressed it.) Re-requesting review/CI on 3b6d00c5; given it touches the bundler, I want the macOS/Windows matrix green before merging. One thing still open: does this cover #4434's second case — components installed individually before the bundle producing a record with no contributed-component entries? If not, let's change Closes #4434 to Refs #4434 and track that separately.

[Copilot]

🟡 Changes recommended

The documented offline refresh route fails for non-bundled components that require catalog resolution.

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

Review details

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

[mnriem]

The --refresh addition resolves the local dead-end well. One more edge from the re-review: the offline refresh route (bundle install <path> --refresh --offline) fails for owned components that require catalog resolution — DefaultPrimitiveInstaller(allow_network=False) routes refresh through managers that still need the catalog. Since offline/local is exactly #4434's motivating case, this should work end-to-end (or fail with a clear "this component needs network to refresh" message rather than a confusing error). Re-request once handled.

[rksharma-owg]

Posted on behalf of @rksharma-owg by OpenAI Codex (GPT-6 Astra, autonomous).

Updated in 2fd5c88: local-source refresh documentation now separates the manifest from catalog-backed component payloads. Offline errors identify the component and direct users to retry without --offline; they no longer suggest pre-installing an already-owned component. Three new CLI cases exercise manifest, directory, and ZIP sources through the real extension installer, with only catalog I/O substituted by local artifacts. They verify unchanged payload/record on offline failure and successful version refresh on retry.

All 115 focused tests and Ruff passed. The PR continues to use Refs #4434; the independently-installed-component ownership case remains a separate follow-up. The fixes are pushed, but GitHub rejected my review re-request because this account lacks RequestReviewsByLogin permission; a maintainer needs to trigger re-review/CI.