💫 Toolkit to help you get started with SDD or any other process!
fix(cli): align integration guidance with available output (#5041)
Manfred Riemf90f7ddf4fa1
diff --git a/docs/integrations/cli.md b/docs/integrations/cli.mdindex 0815a1028..c320a0f5e 100644--- a/docs/integrations/cli.md+++ b/docs/integrations/cli.md@@ -45,6 +45,11 @@ specify integration listShows built-in and trusted installed external integrations, their setuprequirements, and their multi-install safety declarations. Installedintegrations and the default are marked separately.+The `CLI Required` column reports the agent CLI requirement declared by+`config.requires_cli`, not whether the integration is IDE-only. External adapters+can separately require executables through their descriptor's `requires.tools`;+installation and `specify check` validate those tool requirements even when+`CLI Required` is `no`.## Search Available Integrations@@ -530,6 +535,11 @@ work through the IDE itself and may not require a separate CLI for setup.Workflow dispatch can have additional CLI requirements; see your integration'sguide. `specify integration list` shows each integration's setup requirements.+If an integration has no command templates, `specify init` keeps the+project-directory guidance and shows how to choose an integration with+`specify integration list` and switch to it with `specify integration switch <key>`,+rather than recommending unavailable agent commands.+### When should I use `upgrade` vs `switch`?Use `upgrade` when you've upgraded Spec Kit and want to refresh an installed integration's managed files. Use `switch` when you want to replace the current default with another integration; if the target is already installed, `switch` behaves like `use`.diff --git a/src/specify_cli/command_check.py b/src/specify_cli/command_check.pyindex d595709bb..9162bbb6e 100644--- a/src/specify_cli/command_check.py+++ b/src/specify_cli/command_check.py@@ -30,7 +30,7 @@ def _check_external_tools(args = integration.build_exec_args("test", project_root=project_root)tools = [args[0] if args else integration._resolve_executable()]if not tools:- tracker.skip(key, "IDE-based, no CLI check")+ tracker.skip(key, "no CLI required")return Falsetools = list(dict.fromkeys(tools))missing = [tool for tool in tools if shutil.which(tool) is None]@@ -90,7 +90,7 @@ def check() -> None:elif requires_cli:agent_results[agent_key] = check_tool(agent_key, tracker=tracker)else:- tracker.skip(agent_key, "IDE-based, no CLI check")+ tracker.skip(agent_key, "no CLI required")agent_results[agent_key] = Falsetracker.add("code", "Visual Studio Code")diff --git a/src/specify_cli/command_init.py b/src/specify_cli/command_init.pyindex ea21fb1a5..7d1536d4b 100644--- a/src/specify_cli/command_init.py+++ b/src/specify_cli/command_init.py@@ -1057,6 +1057,24 @@ def register(app: typer.Typer) -> None:steps_lines.append("1. You're already in the project directory!")step_num = 2+ if not resolved_integration.list_command_templates():+ steps_lines.append(+ f"{step_num}. Choose an integration: [cyan]specify integration list[/cyan]"+ )+ steps_lines.append(+ f"{step_num + 1}. Switch this project to it: [cyan]specify integration switch <key>[/cyan]"+ )+ console.print()+ console.print(+ Panel(+ "\n".join(steps_lines),+ title="Next Steps",+ border_style="cyan",+ padding=(1, 2),+ )+ )+ return+_is_skills_integration = resolved_integration.is_skills_mode(integration_parsed_options or None, project_root=project_path)diff --git a/src/specify_cli/integrations/command_list.py b/src/specify_cli/integrations/command_list.pyindex 540de82d3..30f977440 100644--- a/src/specify_cli/integrations/command_list.py+++ b/src/specify_cli/integrations/command_list.py@@ -102,7 +102,7 @@ def integration_list(status = "[green]installed[/green]"else:status = ""- cli_req = "yes" if requires_cli else "no (IDE)"+ cli_req = "yes" if requires_cli else "no"safe = "yes" if getattr(integration, "multi_install_safe", False) else "no"table.add_row(key, escape(str(name)), status, cli_req, safe)diff --git a/tests/specify_cli/integrations/test_command_list.py b/tests/specify_cli/integrations/test_command_list.pyindex 5d11931a3..ad169feef 100644--- a/tests/specify_cli/integrations/test_command_list.py+++ b/tests/specify_cli/integrations/test_command_list.py@@ -24,6 +24,20 @@ from tests.specify_cli.integrations._helpers import ()class TestIntegrationList:+ def test_cli_requirement_does_not_imply_ide_classification(self, tmp_path, monkeypatch):+ from types import SimpleNamespace+ from specify_cli.integrations import INTEGRATION_REGISTRY++ project = _init_project(tmp_path, "copilot")+ monkeypatch.setitem(INTEGRATION_REGISTRY, "artifact-free", SimpleNamespace(+ config={"name": "Artifact-free", "requires_cli": False},+ ))+ result = _run_in_project(project, ["integration", "list"])+ assert result.exit_code == 0, result.output+ assert _integration_list_row_cells(result.output, "artifact-free")[-2] == "no"+ assert _integration_list_row_cells(result.output, "claude")[-2] == "yes"+ assert "(IDE)" not in result.output+def test_list_requires_speckit_project(self, tmp_path):old_cwd = os.getcwd()try:diff --git a/tests/specify_cli/integrations/test_installed_adapters.py b/tests/specify_cli/integrations/test_installed_adapters.pyindex 6f8fbadd9..0c1bb0a60 100644--- a/tests/specify_cli/integrations/test_installed_adapters.py+++ b/tests/specify_cli/integrations/test_installed_adapters.py@@ -3803,7 +3803,8 @@ def test_check_skips_optional_tools_for_external_ide_adapter(tmp_path, server, massert KEY not in probesassert "optional-helper" not in probesassert "Sample Agent" in result.output- assert "IDE-based, no CLI check" in result.output+ assert "no CLI required" in result.output+ assert "IDE-based" not in result.output@pytest.mark.parametrize("error_type", ["ValueError", "OSError", "NotImplementedError"])diff --git a/tests/specify_cli/test_command_check.py b/tests/specify_cli/test_command_check.pyindex 2a49b64cc..7026db27f 100644--- a/tests/specify_cli/test_command_check.py+++ b/tests/specify_cli/test_command_check.py@@ -2,6 +2,7 @@from unittest.mock import patch+import pytestfrom typer.testing import CliRunnerfrom specify_cli import app@@ -11,6 +12,36 @@ from tests.conftest import strip_ansirunner = CliRunner()[email protected]("external", [False, True])+def test_no_cli_requirement_is_not_classified_as_ide(tmp_path, monkeypatch, external):+ from specify_cli.command_check import _check_external_tools+ from specify_cli._console import StepTracker++ if external:+ tracker = StepTracker("Tools")+ tracker.add("generic", "Generic")+ with patch("specify_cli.command_check.shutil.which") as which:+ assert not _check_external_tools(+ tmp_path, "generic", {"requires": {}}, False, tracker,+ )+ which.assert_not_called()+ from rich.console import Console+ console = Console(width=120)+ with console.capture() as capture:+ console.print(tracker.render())+ output = capture.get()+ else:+ monkeypatch.chdir(tmp_path)+ with patch("specify_cli.check_tool", return_value=True) as check_tool:+ result = runner.invoke(app, ["check"])+ assert result.exit_code == 0, result.output+ assert "none" not in [call.args[0] for call in check_tool.call_args_list]+ output = strip_ansi(result.output)+ assert "None (shared scaffolding only) (no CLI required)" in output+ assert "no CLI required" in output+ assert "IDE-based" not in output++class TestCheckTip:"""`specify check` should point users to the existing version check."""diff --git a/tests/specify_cli/test_command_init.py b/tests/specify_cli/test_command_init.pyindex 33ad48aa0..e35344587 100644--- a/tests/specify_cli/test_command_init.py+++ b/tests/specify_cli/test_command_init.py@@ -209,3 +209,66 @@ def test_shell_quote_arg_is_host_appropriate():assert quoted == '"my project"'else:assert quoted == "'my project'"++[email protected]("here", [False, True])+def test_output_free_init_recommends_switching_integrations(tmp_path, monkeypatch, here):+ from specify_cli.integrations.generic import GenericIntegration++ monkeypatch.setattr(GenericIntegration, "list_command_templates", lambda self: [])+ monkeypatch.chdir(tmp_path)+ result = CliRunner().invoke(+ app,+ [+ "init", *(["--here"] if here else ["proj"]),+ "--integration", "generic",+ "--integration-options", "--commands-dir .agent/commands",+ "--ignore-agent-tools",+ ],+ )+ assert result.exit_code == 0, result.output+ output = _strip(result.output)+ assert "Next Steps" in output+ if here:+ assert "You're already in the project directory!" in output+ else:+ assert "cd proj" in output+ assert "specify integration switch <key>" in output+ assert "Switch this project to it:" in output+ assert "Add it to this project:" not in output+ assert "specify integration list" in output+ assert "Start using" not in output+ assert "speckit." not in output+ assert "Enhancement Commands" not in output+ assert "Enhancement Skills" not in output+ project = tmp_path if here else tmp_path / "proj"+ assert not (project / ".agent" / "commands").exists()+++def test_rendering_init_preserves_command_guidance(tmp_path):+ result = _init(tmp_path, "proj")+ assert result.exit_code == 0, result.output+ output = _strip(result.output)+ assert "Start using slash commands" in output+ for command in ("constitution", "specify", "plan", "tasks", "implement", "converge",+ "clarify", "analyze", "checklist"):+ assert f"/speckit.{command}" in output+ assert (tmp_path / "proj" / ".agent" / "commands" / f"speckit.{command}.md").is_file()+ assert "Enhancement Commands" in output+ assert "specify integration switch <key>" not in output+++def test_rendering_init_preserves_skill_guidance(tmp_path, monkeypatch):+ monkeypatch.chdir(tmp_path)+ result = CliRunner().invoke(+ app, ["init", "proj", "--integration", "copilot", "--ignore-agent-tools"],+ )+ assert result.exit_code == 0, result.output+ output = _strip(result.output)+ assert "Start using skills" in output+ assert "Enhancement Skills" in output+ assert "specify integration switch <key>" not in output+ for command in ("constitution", "specify", "plan", "tasks", "implement", "converge",+ "clarify", "analyze", "checklist"):+ assert f"/speckit-{command}" in output+ assert (tmp_path / "proj" / ".github" / "skills" / f"speckit-{command}" / "SKILL.md").is_file()