Skip to content

πŸ’« 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.py
index 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 None
if stream:
diff --git a/src/specify_cli/integrations/cursor_agent/__init__.py b/src/specify_cli/integrations/cursor_agent/__init__.py
index 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
+
@classmethod
def options(cls) -> list[IntegrationOption]:
return [
diff --git a/tests/integrations/test_integration_cursor_agent.py b/tests/integrations/test_integration_cursor_agent.py
index 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 urlparse
from specify_cli.integrations import get_integration
from 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.py
index 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.COMPLETED
assert result.output["dispatched"] is True
assert 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-specify
assert "/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)