[Bug]: bundle update suggests unsupported --force after extension refresh failure

[grafvonb]

Bug Description

specify bundle update --all can fail when a bundle owns an already-installed extension, then suggests retrying with --force.

However, specify bundle update does not support --force, so the suggested recovery path is invalid.

This looks like a mismatch between bundle refresh semantics and lower-level extension install semantics.

Steps to Reproduce

1. Have a Spec Kit project with an installed bundle that owns the git extension.

2. Run:

   specify bundle update --all

3. Observe that the command fails because git is already installed.

4. Follow the suggested recovery and run:

   specify bundle update --all --force

5. Observe that --force is rejected because bundle update has no such option.

Expected Behavior

specify bundle update --all should refresh bundle-owned installed components successfully.

If refresh cannot proceed, the error should provide a valid bundle-level recovery path and should not suggest --force unless bundle update actually supports it.

Actual Behavior

The first command fails with an extension-level duplicate-install error:

Error: Failed to install bundle 'basic-speckit-c8volt-stack': Extension 'git' is already installed. Use 'specify extension remove git' first, or retry with --force to overwrite.. No changes were recorded.

Retrying with the suggested --force flag fails because bundle update does not expose that option:

Usage: specify bundle update [OPTIONS] [BUNDLE_ID]
Try 'specify bundle update --help' for help.
╭─ Error ─────────────────────────────────────────────────────────────────╮
│ No such option: --force                                                 │
╰─────────────────────────────────────────────────────────────────────────╯

Specify CLI Version

0.12.8

AI Agent

GitHub Copilot

Operating System

macOS Tahoe 26.5.1

Python Version

3.13.5

Error Logs

❯ specify bundle update --all
Error: Failed to install bundle 'basic-speckit-c8volt-stack': Extension 'git' is already installed. Use 'specify extension remove git' first, or retry
with --force to overwrite.. No changes were recorded.

❯ specify bundle update --all --force
Usage: specify bundle update [OPTIONS] [BUNDLE_ID]
Try 'specify bundle update --help' for help.
╭─ Error ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ No such option: --force                                                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Additional Context

From local inspection, bundle update calls install_bundle(..., refresh=True). For owned existing components, _refresh_component() prefers a primitive refresh() hook, but DefaultPrimitiveInstaller currently does not implement one, so it falls back to installer.install(...).

For extensions, plain install rejects already-installed extensions unless force=True, producing the leaked extension-level message.

This appears broader than wording: bundle update documents refresh semantics, but the real default primitive adapter can fall back to duplicate install semantics for extensions.

[github-actions]

Bug assessment — bundle-update-force-mislead: Valid · severity medium

---

Bug Assessment: bundle update suggests unsupported --force after extension refresh failure

• Slug: bundle-update-force-mislead
• Created: 2026-07-09T16:02:23Z
• Source: issue [Bug]: bundle update suggests unsupported --force after extension refresh failure #3424
• Verdict: valid
• Severity: medium

Report (summarized)

Reported by @grafvonb. Running specify bundle update --all on a project whose bundle owns the git extension fails with an extension-level error that suggests retrying with --force. However, specify bundle update has no --force option, so the suggested recovery path is invalid and leaves the user stuck.

Symptom

specify bundle update --all raises a BundlerError that contains an extension-level message advising --force, which bundle update does not support; the user has no valid bundle-level recovery path and the update silently makes no changes.

Reproduction

1. Create a Spec Kit project with a bundle installed that owns the git extension (e.g. basic-speckit-c8volt-stack).
2. Run specify bundle update --all.
3. Observe the error: Failed to install bundle '...': Extension 'git' is already installed. Use 'specify extension remove git' first, or retry with --force to overwrite.. No changes were recorded.
4. Follow the suggested recovery and run specify bundle update --all --force.
5. Observe: No such option: --force — bundle update rejects the flag.

Suspected Code Paths

• src/specify_cli/bundler/services/installer.py:206-220 — _refresh_component(): tries installer.refresh attribute; falls back to installer.install() when none is found. This fallback is the trigger.
• src/specify_cli/bundler/services/installer.py:155-163 — install_bundle() except Exception handler: wraps any raised exception verbatim into BundlerError, propagating the extension-level --force hint unchanged.
• src/specify_cli/bundler/services/adapters.py:164-197 — DefaultPrimitiveInstaller: implements is_installed, install, and remove on the PrimitiveInstaller protocol, but has no refresh method, so _refresh_component()'s getattr(installer, "refresh", None) resolves to None and the fallback path is always taken.
• src/specify_cli/bundler/services/primitives.py:226-280 — _ExtensionKindManager.install(): delegates to ExtensionManager.install_from_directory(..., force=False) (default), which raises ExtensionError when the extension is already installed and force is False.
• src/specify_cli/extensions/__init__.py:1354-1361 — ExtensionManager.install_from_directory(): the guarded block that raises ExtensionError with the --force advice when not force and is_installed.

Root Cause Hypothesis

Confidence: high.

_refresh_component() is designed to prefer a refresh hook on the installer and fall back to install(). The unit test test_refresh_falls_back_to_install_without_hook validates this path using FakeInstaller, whose install() is idempotent (does not raise on double-install). In production, DefaultPrimitiveInstaller has no refresh method, so the fallback fires — but DefaultPrimitiveInstaller.install() is not idempotent for extensions: it ultimately calls ExtensionManager.install_from_directory() with force=False, which raises ExtensionError when the extension is already present. The BundlerError wrapping in install_bundle() then surfaces that error verbatim, embedding the extension-level --force hint in a message that appears to be actionable via bundle update, which does not support --force.

There are two overlapping defects:

1. Functional: DefaultPrimitiveInstaller lacks a refresh method that passes force=True (or equivalent) to the underlying primitives, making bundle refresh semantically broken for extensions.
2. UX: the leaked extension-level error message suggests an option that bundle update does not expose.

Proposed Remediation

Preferred: Add a refresh() method to DefaultPrimitiveInstaller (in adapters.py) that delegates to a refresh() method on each kind manager. Each kind manager then calls the underlying primitive with the equivalent of force=True:

• _ExtensionKindManager.refresh() → calls install_from_directory(..., force=True) or install_from_zip(..., force=True) (both already accept force: bool = False). This path is already exercised by ExtensionManager — adding force=True at the bundler adapter layer is the minimal and safe change.
• _PresetKindManager.refresh() → the preset install_from_directory() does not expose a force parameter; a minimal approach is remove() then install(), or add force to PresetManager.install_from_directory() first.
• _WorkflowKindManager.refresh() and _StepKindManager.refresh() — they delegate to CLI command callables; their underlying workflow_add / workflow_step_add likely handle idempotency already, so the fallback-to-install path may already work, but should be verified.

Once the refresh hook exists on DefaultPrimitiveInstaller, _refresh_component() will call it instead of install(), and the --force hint will never surface in the bundle context.

Alternatives:

• Change _refresh_component() fallback to remove() + install(): Avoids adding force everywhere, but introduces atomicity risk — if remove() succeeds and install() fails, the component is gone. More complex rollback would be needed.
• Suppress or rewrite the error message in install_bundle(): A cosmetic fix that replaces the extension-level --force hint with a bundle-level message (e.g. "re-run specify bundle update"). This unblocks users with a helpful message but does not fix the underlying failure.
• Add --force to bundle update: Surfaces the ability to force-refresh to users, but this exposes more surface area and would require plumbing force through install_bundle() and down to each kind manager anyway.

Files likely to change:

• src/specify_cli/bundler/services/adapters.py — add refresh() to DefaultPrimitiveInstaller
• src/specify_cli/bundler/services/primitives.py — add refresh() to _ExtensionKindManager (and verify/add for other kind managers)
• src/specify_cli/presets/__init__.py — may need force parameter added to install_from_directory() if the preferred approach is used for presets
• tests/unit/test_bundler_primitives.py — add tests for the new refresh() paths
• tests/integration/test_bundler_install_flow.py — strengthen the existing test_refresh_falls_back_to_install_without_hook or add a new integration test that exercises the real DefaultPrimitiveInstaller refresh path

Tests to add or update:

• Unit test: _ExtensionKindManager.refresh() calls install_from_directory with force=True
• Integration test: bundle update with an already-installed bundle-owned extension completes without error (uses DefaultPrimitiveInstaller against a real extension on disk)
• Regression test: the leaked --force hint no longer appears in BundlerError messages from bundle update

Risks & Considerations

• Preset force-overwrite: PresetManager.install_from_directory() does not currently accept force. If the preferred fix is applied to presets via remove()+install(), test atomicity carefully.
• Workflow/step idempotency: _WorkflowKindManager.install() and _StepKindManager.install() delegate to CLI callables; verify those callables are idempotent for already-installed items before relying on the existing install() fallback.
• No API breakage: PrimitiveInstaller is a Protocol; adding refresh to DefaultPrimitiveInstaller is backwards compatible. _KindManager is also a Protocol; adding refresh is non-breaking for existing test fakes.
• Test isolation: existing test test_refresh_falls_back_to_install_without_hook uses FakeInstaller with refresh = None; this test should continue to pass (the fallback path is still valid for custom installers without a refresh hook), but the production path will now exercise the new refresh method.

Open Questions

• [NEEDS CLARIFICATION: Does PresetManager.install_from_directory() silently overwrite an existing preset, or does it also reject double-installs? This determines whether presets are affected by the same root cause or only extensions.]
• [NEEDS CLARIFICATION: Are workflow_add and workflow_step_add idempotent when the workflow/step is already installed? If so, the fallback-to-install path already works for those kinds and only extensions (and possibly presets) need the fix.]

Generated by 🐛 Assess Bug from Labeled Issue for issue #3424 · 258.1 AIC · ⌖ 31.3 AIC · ⊞ 31.8K · ◷