fix: tighten integration switch semantics

Author: PascalThuet

docs/reference/integrations.md

@@ -89,9 +89,9 @@ specify integration switch <key>
 | ------------------------ | ------------------------------------------------------------------------ |
 | `--script sh\|ps`        | Script type: `sh` (bash/zsh) or `ps` (PowerShell)                        |
 | `--force`                | Force removal of modified files during uninstall; when the target is already installed, overwrite managed shared templates while changing the default |
-| `--integration-options`  | Options for the target integration                                       |
+| `--integration-options`  | Options for the target integration when it is not already installed      |
 
-If the target integration is not already installed, equivalent to running `uninstall` followed by `install` in a single step. In this mode, `--force` controls whether modified files from the removed integration are deleted. If the target integration is already installed, `switch` only changes the default integration, like `use`; in this mode, `--force` controls whether managed shared templates are overwritten while the default changes.
+If the target integration is not already installed, equivalent to running `uninstall` followed by `install` in a single step. In this mode, `--force` controls whether modified files from the removed integration are deleted. If the target integration is already installed, `switch` only changes the default integration, like `use`; in this mode, `--force` controls whether managed shared templates are overwritten while the default changes. `--integration-options` is rejected for already-installed targets because changing integration options requires reinstalling managed files; run `upgrade <key> --integration-options ...` first, then `use <key>`.
 
 ## Use an Installed Integration
 

src/specify_cli/__init__.py

@@ -2158,8 +2158,8 @@ def integration_install(
     if key in installed_keys:
         console.print(f"[yellow]Integration '{key}' is already installed.[/yellow]")
         console.print(
-            "Run [cyan]specify integration upgrade[/cyan] to reinstall managed files, "
-            "or [cyan]specify integration uninstall[/cyan] first."
+            f"Run [cyan]specify integration upgrade {key}[/cyan] to reinstall managed files, "
+            f"or [cyan]specify integration uninstall {key}[/cyan] first."
         )
         raise typer.Exit(0)
 
@@ -2528,10 +2528,49 @@ def integration_switch(
     installed_key = _default_integration_key(current)
 
     if installed_key == target:
-        console.print(f"[yellow]Integration '{target}' is already installed. Nothing to switch.[/yellow]")
+        if integration_options is not None:
+            console.print(
+                "[red]Error:[/red] --integration-options cannot be used when switching "
+                "to an already installed integration."
+            )
+            console.print(
+                f"Run [cyan]specify integration upgrade {target} --integration-options ...[/cyan] "
+                "to update managed files/options."
+            )
+            raise typer.Exit(1)
+        if force:
+            raw_options, parsed_options = _resolve_integration_options(
+                target_integration, current, target, None
+            )
+            _set_default_integration(
+                project_root,
+                current,
+                target,
+                target_integration,
+                installed_keys,
+                raw_options=raw_options,
+                parsed_options=parsed_options,
+                refresh_templates_force=True,
+            )
+            console.print(
+                f"\n[green]✓[/green] Default integration remains [bold]{target}[/bold]; "
+                "managed shared templates refreshed."
+            )
+            raise typer.Exit(0)
+        console.print(f"[yellow]Integration '{target}' is already the default integration. Nothing to switch.[/yellow]")
         raise typer.Exit(0)
 
     if target in installed_keys:
+        if integration_options is not None:
+            console.print(
+                "[red]Error:[/red] --integration-options cannot be used when switching "
+                "to an already installed integration."
+            )
+            console.print(
+                f"Run [cyan]specify integration upgrade {target} --integration-options ...[/cyan] "
+                f"to update managed files/options, then [cyan]specify integration use {target}[/cyan]."
+            )
+            raise typer.Exit(1)
         raw_options, parsed_options = _resolve_integration_options(
             target_integration, current, target, None
         )

src/specify_cli/integration_state.py

@@ -57,8 +57,8 @@ def normalize_integration_settings(settings: Any) -> dict[str, dict[str, Any]]:
             clean["parsed_options"] = parsed_options
 
         invoke_separator = value.get("invoke_separator")
-        if isinstance(invoke_separator, str) and invoke_separator:
-            clean["invoke_separator"] = invoke_separator
+        if isinstance(invoke_separator, str) and invoke_separator.strip():
+            clean["invoke_separator"] = invoke_separator.strip()
 
         if clean:
             normalized[key.strip()] = clean

tests/integrations/test_integration_state.py

@@ -5,6 +5,7 @@
 from specify_cli.integration_state import INTEGRATION_JSON
 from specify_cli.integration_state import (
     default_integration_key,
+    integration_setting,
     normalize_integration_state,
     write_integration_json,
 )
@@ -42,6 +43,21 @@ def test_default_integration_key_strips_raw_state_values():
     assert default_integration_key({"integration": " codex "}) == "codex"
 
 
+def test_integration_settings_strip_invoke_separator():
+    setting = integration_setting(
+        {
+            "integration_settings": {
+                "claude": {
+                    "invoke_separator": " - ",
+                }
+            }
+        },
+        "claude",
+    )
+
+    assert setting["invoke_separator"] == "-"
+
+
 def test_write_integration_json_strips_integration_key(tmp_path):
     write_integration_json(
         tmp_path,

tests/integrations/test_integration_subcommand.py

@@ -127,7 +127,9 @@ def test_install_already_installed(self, tmp_path):
             os.chdir(old_cwd)
         assert result.exit_code == 0
         assert "already installed" in result.output
-        assert "uninstall" in result.output
+        normalized = " ".join(result.output.split())
+        assert "specify integration upgrade copilot" in normalized
+        assert "specify integration uninstall copilot" in normalized
 
     def test_install_different_when_one_exists(self, tmp_path):
         project = _init_project(tmp_path, "copilot")
@@ -569,7 +571,48 @@ def test_switch_same_noop(self, tmp_path):
         finally:
             os.chdir(old_cwd)
         assert result.exit_code == 0
-        assert "already installed" in result.output
+        assert "already the default integration" in result.output
+
+    def test_switch_same_force_refreshes_shared_templates(self, tmp_path):
+        project = _init_project(tmp_path, "claude")
+        template = project / ".specify" / "templates" / "plan-template.md"
+        template.write_text("# custom shared template\n", encoding="utf-8")
+
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            result = runner.invoke(app, [
+                "integration", "switch", "claude",
+                "--force",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0, result.output
+        assert "managed shared templates refreshed" in result.output
+        assert "/speckit-plan" in template.read_text(encoding="utf-8")
+
+    def test_switch_installed_target_rejects_integration_options(self, tmp_path):
+        project = _init_project(tmp_path, "claude")
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(project)
+            install = runner.invoke(app, [
+                "integration", "install", "codex",
+                "--script", "sh",
+            ], catch_exceptions=False)
+            assert install.exit_code == 0, install.output
+
+            result = runner.invoke(app, [
+                "integration", "switch", "codex",
+                "--integration-options", "--bogus",
+            ])
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code != 0
+        assert "--integration-options cannot be used" in result.output
+
+        data = json.loads((project / ".specify" / "integration.json").read_text(encoding="utf-8"))
+        assert data["default_integration"] == "claude"
 
     def test_switch_between_integrations(self, tmp_path):
         project = _init_project(tmp_path, "claude")