π« Toolkit to help you get started with SDD or any other process!
fix(cursor-agent): enable headless CLI dispatch end-to-end (-p --trust --approve-mcps --force + Windows .cmd shim resolution) (#2631)
One-TheOnly8e5643d4ffa4
diff --git a/src/specify_cli/integrations/base.py b/src/specify_cli/integrations/base.pyindex 4742a37ca..c03dc4058 100644--- a/src/specify_cli/integrations/base.py+++ b/src/specify_cli/integrations/base.py@@ -270,6 +270,16 @@ class IntegrationBase(ABC):)raise NotImplementedError(msg)+ # Windows: ``subprocess.run`` calls ``CreateProcess`` which does not+ # consult ``PATHEXT``, so a bare command name like ``cursor-agent``+ # that resolves to ``cursor-agent.cmd`` fails with ``WinError 2``.+ # Resolve via ``shutil.which`` (which does honor ``PATHEXT``) so+ # ``.cmd``/``.bat`` shims work transparently. On POSIX this is a+ # no-op for absolute paths and a harmless lookup otherwise.+ resolved = shutil.which(exec_args[0])+ if resolved:+ exec_args = [resolved, *exec_args[1:]]+cwd = str(project_root) if project_root else Noneif stream:diff --git a/src/specify_cli/integrations/cursor_agent/__init__.py b/src/specify_cli/integrations/cursor_agent/__init__.pyindex 70af454ce..5d3788feb 100644--- a/src/specify_cli/integrations/cursor_agent/__init__.py+++ b/src/specify_cli/integrations/cursor_agent/__init__.py@@ -2,6 +2,12 @@Cursor Agent uses the ``.cursor/skills/speckit-<name>/SKILL.md`` layout.Commands are deprecated; ``--skills`` defaults to ``True``.++The IDE/skills flow is the primary path and works without the+``cursor-agent`` CLI being installed (``requires_cli=False``). Workflow+dispatch via ``cursor-agent -p --trust --approve-mcps --force <prompt>``+is offered as an opt-in capability β the presence of ``build_exec_args()``+is what indicates dispatch support, mirroring ``CopilotIntegration``."""from __future__ import annotations@@ -15,7 +21,12 @@ class CursorAgentIntegration(SkillsIntegration):"name": "Cursor","folder": ".cursor/","commands_subdir": "skills",- "install_url": None,+ "install_url": "https://docs.cursor.com/en/cli/overview",+ # IDE-first integration: ``specify init --ai cursor-agent`` must+ # work without the ``cursor-agent`` CLI installed (the IDE flow+ # uses skills directly). Workflow dispatch additionally requires+ # the CLI on PATH, but that's enforced at dispatch time via+ # ``shutil.which`` rather than as a hard ``specify init`` precheck."requires_cli": False,}registrar_config = {@@ -28,6 +39,50 @@ class CursorAgentIntegration(SkillsIntegration):context_file = ".cursor/rules/specify-rules.mdc"multi_install_safe = True+ def build_exec_args(+ self,+ prompt: str,+ *,+ model: str | None = None,+ output_json: bool = True,+ ) -> list[str] | None:+ """Build CLI arguments for non-interactive ``cursor-agent`` execution.++ Always returns argv (no ``requires_cli`` guard) so workflow+ dispatch is supported even though the integration's ``config``+ sets ``requires_cli=False`` to keep the IDE-only flow unblocked.+ This mirrors ``CopilotIntegration``: dispatch support is signalled+ by overriding ``build_exec_args()``, not by the ``requires_cli``+ flag (which is reserved for the ``specify init`` precheck).++ Mandatory headless flags:++ * ``-p`` β print/headless mode (access to all tools)+ * ``--trust`` β bypass Workspace Trust prompt (CLI exits non-zero+ otherwise)+ * ``--approve-mcps`` β auto-approve MCP server loading (otherwise+ MCP servers stay ``not loaded (needs approval)`` and tool calls+ to them are silently dropped)+ * ``--force`` β auto-approve tool invocations (shell/write/MCP),+ matching the implicit "trusted environment" semantics that other+ integrations (``claude -p``, ``codex --exec``) get by default++ Together these are the minimum set required to make+ ``specify workflow run speckit --input integration=cursor-agent``+ behave the same way as it does for ``claude`` / ``codex``.+ Verified locally: with ``--approve-mcps --force`` the agent can+ call any configured MCP server (e.g. ``dingtalk-doc``) and write+ files during ``/speckit-*`` skill execution; without them the run+ either drops tool calls or exits non-zero on the first approval+ prompt.+ """+ args = [self.key, "-p", "--trust", "--approve-mcps", "--force", prompt]+ if model:+ args.extend(["--model", model])+ if output_json:+ args.extend(["--output-format", "json"])+ return args+@classmethoddef options(cls) -> list[IntegrationOption]:return [diff --git a/tests/integrations/test_integration_cursor_agent.py b/tests/integrations/test_integration_cursor_agent.pyindex 352a0475b..241f816a0 100644--- a/tests/integrations/test_integration_cursor_agent.py+++ b/tests/integrations/test_integration_cursor_agent.py@@ -1,6 +1,7 @@"""Tests for CursorAgentIntegration."""from pathlib import Path+from urllib.parse import urlparsefrom specify_cli.integrations import get_integrationfrom specify_cli.integrations.manifest import IntegrationManifest@@ -106,3 +107,157 @@ class TestCursorAgentAutoPromote:assert result.exit_code == 0, f"init --ai cursor-agent failed: {result.output}"assert (target / ".cursor" / "skills" / "speckit-plan" / "SKILL.md").exists()++class TestCursorAgentCliDispatch:+ """Verify the CLI dispatch path for cursor-agent (issue #2629).++ The ``cursor-agent`` CLI supports headless execution via ``-p`` (with+ full tool access including write/shell) and requires ``--trust`` to+ bypass the Workspace Trust prompt. These tests pin the exact argv+ shape that the workflow runner will use.+ """++ def test_requires_cli_is_false_for_ide_first_flow(self):+ """``requires_cli`` must stay False so the IDE-only flow keeps working.++ ``specify init --ai cursor-agent`` (without ``--ignore-agent-tools``)+ treats ``requires_cli=True`` as a hard precheck and fails when the+ ``cursor-agent`` CLI isn't on PATH β even though the Cursor IDE+ / skills flow can run without it. Workflow dispatch support is+ signalled by overriding ``build_exec_args()`` instead, mirroring+ ``CopilotIntegration``.+ """+ i = get_integration("cursor-agent")+ assert i.config.get("requires_cli") is False++ def test_install_url_is_set(self):+ i = get_integration("cursor-agent")+ url = i.config.get("install_url")+ assert url is not None+ # CodeQL: use a hostname comparison instead of a substring check+ # to avoid the "Incomplete URL substring sanitization" warning+ # (substring "cursor.com" can also appear in attacker-controlled+ # positions of an arbitrary URL).+ host = (urlparse(url).hostname or "").lower()+ assert host == "cursor.com" or host.endswith(".cursor.com")++ def test_build_exec_args_default_includes_headless_flags_and_json(self):+ """Default argv emits the full headless flag set: -p --trust+ --approve-mcps --force, then prompt, then --output-format json.+ """+ i = get_integration("cursor-agent")+ args = i.build_exec_args("/speckit-specify some-feature")+ assert args == [+ "cursor-agent", "-p", "--trust", "--approve-mcps", "--force",+ "/speckit-specify some-feature",+ "--output-format", "json",+ ]++ def test_build_exec_args_text_output_omits_format(self):+ i = get_integration("cursor-agent")+ args = i.build_exec_args("/speckit-plan", output_json=False)+ assert args == [+ "cursor-agent", "-p", "--trust", "--approve-mcps", "--force",+ "/speckit-plan",+ ]++ def test_build_exec_args_with_model(self):+ i = get_integration("cursor-agent")+ args = i.build_exec_args(+ "/speckit-specify", model="sonnet-4-thinking", output_json=False+ )+ assert args == [+ "cursor-agent", "-p", "--trust", "--approve-mcps", "--force",+ "/speckit-specify",+ "--model", "sonnet-4-thinking",+ ]++ def test_build_exec_args_contains_mandatory_headless_flags(self):+ """The four headless flags must always appear together.++ ``--approve-mcps`` is required so MCP servers (e.g. dingtalk-doc)+ actually load in headless mode; ``--force`` is required so the+ agent doesn't block on tool-call approval prompts during the+ speckit workflow. Together with ``-p`` and ``--trust`` they+ bring cursor-agent's headless behaviour in line with+ ``claude -p`` / ``codex --exec`` from spec-kit's perspective.+ """+ i = get_integration("cursor-agent")+ args = i.build_exec_args("/speckit-implement", output_json=False)+ for flag in ("-p", "--trust", "--approve-mcps", "--force"):+ assert flag in args, f"missing mandatory headless flag: {flag}"++ def test_build_exec_args_supports_dispatch_without_requires_cli(self):+ """``build_exec_args`` must return argv even though ``requires_cli``+ is ``False``.++ ``CursorAgentIntegration`` opts out of the ``requires_cli`` hard+ precheck (so ``specify init`` doesn't fail when the CLI isn't on+ PATH) but still supports workflow dispatch. The presence of a+ non-``None`` argv from ``build_exec_args()`` is what the engine+ keys off β pin that invariant.+ """+ i = get_integration("cursor-agent")+ assert i.config.get("requires_cli") is False+ argv = i.build_exec_args("/speckit-plan", output_json=False)+ assert argv is not None+ assert argv[0] == "cursor-agent"++ def test_build_command_invocation_uses_hyphenated_skill_name(self):+ """SkillsIntegration: /speckit-plan (not /speckit.plan)."""+ i = get_integration("cursor-agent")+ assert i.build_command_invocation("speckit.plan", "feature-x") == "/speckit-plan feature-x"+ assert i.build_command_invocation("plan") == "/speckit-plan"++ def test_dispatch_command_resolves_cmd_shim_for_subprocess(self):+ """``.cmd`` shims must be resolved to their full path before ``subprocess.run``.++ ``cursor-agent`` (and other npm-installed CLIs on Windows) ship as+ ``cursor-agent.cmd`` wrappers. ``shutil.which`` honors ``PATHEXT``+ and finds them, but Python's ``subprocess.run`` calls+ ``CreateProcess`` which does **not** consult ``PATHEXT`` and fails+ with ``WinError 2`` on a bare ``["cursor-agent", ...]`` argv. The+ fix in ``base.py::dispatch_command`` resolves ``exec_args[0]`` via+ ``shutil.which`` so the full ``.cmd`` path is what reaches+ ``CreateProcess``.+ """+ from unittest.mock import patch, MagicMock+ i = get_integration("cursor-agent")++ mock_result = MagicMock()+ mock_result.returncode = 0+ mock_result.stdout = "ok"+ mock_result.stderr = ""++ fake_path = r"C:\Users\foo\AppData\Local\cursor-agent\cursor-agent.CMD"+ with patch(+ "specify_cli.integrations.base.shutil.which", return_value=fake_path+ ), patch("subprocess.run", return_value=mock_result) as mock_run:+ result = i.dispatch_command(+ "speckit.plan", args="feature-x", stream=False, timeout=5+ )++ assert result["exit_code"] == 0+ argv = mock_run.call_args[0][0]+ assert argv[0] == fake_path, f"expected resolved .CMD path, got: {argv[0]!r}"+ assert argv[1:6] == ["-p", "--trust", "--approve-mcps", "--force", "/speckit-plan feature-x"]++ def test_dispatch_command_passthrough_when_shutil_which_finds_nothing(self):+ """If ``shutil.which`` returns ``None``, leave argv unchanged so the+ existing ``FileNotFoundError`` path remains observable to callers."""+ from unittest.mock import patch, MagicMock+ i = get_integration("cursor-agent")++ mock_result = MagicMock()+ mock_result.returncode = 0+ mock_result.stdout = ""+ mock_result.stderr = ""++ with patch(+ "specify_cli.integrations.base.shutil.which", return_value=None+ ), patch("subprocess.run", return_value=mock_result) as mock_run:+ i.dispatch_command("speckit.plan", stream=False, timeout=5)++ argv = mock_run.call_args[0][0]+ assert argv[0] == "cursor-agent"+diff --git a/tests/test_workflows.py b/tests/test_workflows.pyindex 26b3caa58..e85c2d729 100644--- a/tests/test_workflows.py+++ b/tests/test_workflows.py@@ -601,15 +601,18 @@ class TestCommandStep:mock_result.stderr = ""with patch("specify_cli.workflows.steps.command.shutil.which", return_value="/usr/local/bin/claude"), \+ patch("specify_cli.integrations.base.shutil.which", return_value="/usr/local/bin/claude"), \patch("subprocess.run", return_value=mock_result) as mock_run:result = step.execute(config, ctx)assert result.status == StepStatus.COMPLETEDassert result.output["dispatched"] is Trueassert result.output["exit_code"] == 0- # Verify the CLI was called with -p and the skill invocation+ # Verify the CLI was called with the resolved path (via shutil.which,+ # which honors PATHEXT for ``.cmd``/``.bat`` shims on Windows), then+ # ``-p`` and the skill invocation.call_args = mock_run.call_args- assert call_args[0][0][0] == "claude"+ assert call_args[0][0][0] == "/usr/local/bin/claude"assert call_args[0][0][1] == "-p"# Claude is a SkillsIntegration so uses /speckit-specifyassert "/speckit-specify login" in call_args[0][0][2]@@ -638,6 +641,7 @@ class TestCommandStep:mock_result.stderr = "API error"with patch("specify_cli.workflows.steps.command.shutil.which", return_value="/usr/local/bin/claude"), \+ patch("specify_cli.integrations.base.shutil.which", return_value="/usr/local/bin/claude"), \patch("subprocess.run", return_value=mock_result):result = step.execute(config, ctx)