💫 Toolkit to help you get started with SDD or any other process!
feat(workflows): expose installed workflow listing through MCP (#5115)
Nishanth B749a177202ed
diff --git a/docs/reference/mcp.md b/docs/reference/mcp.mdindex b5665f9aa..ddf1efa75 100644--- a/docs/reference/mcp.md+++ b/docs/reference/mcp.md@@ -25,6 +25,7 @@ read-only, local-only (no network access), and reject unexpected arguments.| `specify_version` | Return the installed CLI version, runtime, system, and feature capabilities. Takes no arguments. || `specify_artifact_list` | Return one paginated page of a project's artifact inventory (`command`, `template`, `script`, `hook`) || `specify_artifact_info` | Return one artifact and its complete composition stack |+| `specify_workflow_list` | List installed workflows and skipped-entry warnings in registry order |The artifact tools take an optional absolute `project_directory`; it defaultsto the directory the server was launched from.@@ -50,7 +51,47 @@ tool error.| `specify_run_command` | Run one supported command through the real Specify CLI |The server does not expose mutations, installation or update operations,-workflows, confirmations, or access tiers.+workflow execution, confirmations, or access tiers.++## Installed workflow list++`specify_workflow_list` accepts an optional absolute `project_directory`+(default: the server launch directory) and `limit` (1–1000, default 100).+It reads only the installed workflow registry; it never loads custom steps,+fetches catalogs, repairs files, or executes workflows.++The result has ordered `items` and a `truncated` boolean. Workflow items have+`kind: "workflow"`, `id`, `name`, `version`, nullable `description`, and `enabled`.+Malformed individual registry entries produce `kind: "warning"` items with+`code: "invalid_registry_entry"`, `workflow_id`, and `message` in their original+positions. The limit counts both workflows and warnings. `truncated: true`+explicitly indicates omitted entries; increase `limit` to retrieve more, up to+1000. There is no continuation cursor. The CLI retains its complete listing.++Missing registry files produce an empty list. Corrupt or unreadable registry+files produce `workflow_registry_read_failed`; unsafe storage produces+`unsafe_workflow_storage`. Other expected errors are `invalid_project_directory`+and `not_a_spec_kit_project`. Errors contain `code`, `message`,+`details`, and `retryable` under `error`, with `isError: true`.+Unexpected failures use sanitized `internal_error`; invalid operation outcomes+use `invalid_operation_result`. Responses exceeding 1 MiB produce a retryable+`response_too_large` error instead of partial success; retry with a smaller+limit. Registry exception details are not exposed through MCP.++Out-of-range `limit` values are rejected before the operation runs and produce+text-only input-validation errors with no structured content; see+[Input validation errors](#input-validation-errors).++Workflow listing reads registry content through the selected project's+`FileHelper` policy owner, rejecting Windows junctions and unsupported reparse+points at the read boundary. Ordinary workflow registry symlinks remain+disallowed. Other workflow registry callers are not migrated by this tool.+These checks do not provide an OS sandbox or race-free filesystem confinement;+the registry is still parsed in full before the entry limit is applied.++Operation outcomes exceeding the requested entry limit, or claiming truncation+without filling that limit, are rejected as `invalid_operation_result`. The+output schema also caps `items` at 1000.## Input validation errorsdiff --git a/src/specify_cli/mcp_server/server.py b/src/specify_cli/mcp_server/server.pyindex c7b5b6dae..708410c79 100644--- a/src/specify_cli/mcp_server/server.py+++ b/src/specify_cli/mcp_server/server.py@@ -10,6 +10,7 @@ from mcp.types import CallToolResult, TextContentfrom ..artifacts._mcp import register as register_artifactsfrom ..mcp_version import register as register_version+from ..workflows._mcp import register as register_workflowsfrom .catalog import (CommandAdapterError,CommandDescription,@@ -89,6 +90,7 @@ def create_server(register_version(server)register_artifacts(server, launch_directory=server_launch_directory)+ register_workflows(server, launch_directory=server_launch_directory)return serverdiff --git a/src/specify_cli/workflows/_commands.py b/src/specify_cli/workflows/_commands.pyindex 30fcbd305..c1fb716f7 100644--- a/src/specify_cli/workflows/_commands.py+++ b/src/specify_cli/workflows/_commands.py@@ -183,16 +183,13 @@ def _reject_unsafe_dir(path: Path, label: str) -> None:def _reject_unsafe_workflow_storage(project_root: Path) -> None:"""Refuse symlinked workflow storage directories before workflow commands run."""- _reject_unsafe_dir(project_root / ".specify", ".specify")- _reject_unsafe_dir(project_root / ".specify" / "workflows", ".specify/workflows")- _reject_unsafe_dir(- project_root / ".specify" / "workflows" / "runs",- ".specify/workflows/runs",- )- _reject_unsafe_dir(- project_root / ".specify" / "workflows" / "overlays",- ".specify/workflows/overlays",- )+ from ._storage import WorkflowStorageError, validate_workflow_storage++ try:+ validate_workflow_storage(project_root)+ except WorkflowStorageError as exc:+ err_console.print(f"[red]Error:[/red] {exc}")+ raise typer.Exit(1) from excdef _resolve_installed_workflow_ownership(diff --git a/src/specify_cli/workflows/_mcp.py b/src/specify_cli/workflows/_mcp.pyindex 4477c00d7..fd0f3d75d 100644--- a/src/specify_cli/workflows/_mcp.py+++ b/src/specify_cli/workflows/_mcp.py@@ -1,7 +1,7 @@"""Explicit MCP dispositions for the complete ``specify workflow`` hierarchy.-No workflow adapter is registered yet. These records describe the conservative-union of the current CLI paths, not a promise of a future MCP contract.+Only workflow.list has a shared operation and adapter. Unavailable records+describe the conservative union of CLI paths, not a future MCP contract.Effect boundaries worth retaining when adapters are introduced:@@ -23,8 +23,14 @@ they do not expand MCP discovery or the legacy server command catalog.from __future__ import annotationsfrom dataclasses import dataclass+from pathlib import Pathfrom typing import Literal+from mcp.server import MCPServer++from ._operation_list import WORKFLOW_LIST_OPERATION+from .mcp_list import register as register_list+WorkflowDisposition = Literal["available", "unavailable", "excluded"]WorkflowCapability = Literal["local-read", "project-write", "execution", "self-modifying"@@ -101,12 +107,11 @@ WORKFLOW_TOOLS = (operation_id="workflow.list",cli_path="specify workflow list",mcp_tool_name="specify_workflow_list",- disposition_reason=(- "WorkflowRegistry.list returns registry dictionaries rendered by the CLI; "- "no shared typed list outcome or MCP adapter."- ),- capabilities=_LOCAL_READ,- network_access="none",+ disposition_reason=None,+ disposition="available",+ contract_version=WORKFLOW_LIST_OPERATION.contract_version,+ capabilities=WORKFLOW_LIST_OPERATION.capabilities,+ network_access=WORKFLOW_LIST_OPERATION.network_access,),WorkflowToolInventory(operation_id="workflow.remove",@@ -375,3 +380,14 @@ WORKFLOW_TOOLS = (network_access="none",),)+++def register(server: MCPServer, *, launch_directory: Path) -> None:+ """Register only the workflow list operation from its owning hierarchy."""+ record = next(+ item for item in WORKFLOW_TOOLS if item.operation_id == "workflow.list"+ )+ if record.disposition == "available":+ register_list(+ server, launch_directory=launch_directory, tool_name=record.mcp_tool_name+ )diff --git a/src/specify_cli/workflows/_operation_list.py b/src/specify_cli/workflows/_operation_list.pynew file mode 100644index 000000000..3f0fa902d--- /dev/null+++ b/src/specify_cli/workflows/_operation_list.py@@ -0,0 +1,149 @@+"""Shared, read-only application operation for installed workflow listing."""++from __future__ import annotations++from dataclasses import dataclass+from itertools import islice+from pathlib import Path+import stat+from typing import Literal++from .._file_policy import ProjectPolicyError, project_files+from ._storage import WorkflowStorageError, validate_workflow_storage+from .catalog import WorkflowRegistry++WORKFLOW_LIST_MAX_LIMIT = 1000+++@dataclass(frozen=True)+class WorkflowListRequest:+ project_directory: Path+ # CLI retains its complete listing. MCP supplies an explicit bounded limit.+ limit: int | None = None+++@dataclass(frozen=True)+class WorkflowListEntry:+ id: str+ name: str+ version: str+ description: str | None+ enabled: bool+ kind: Literal["workflow"] = "workflow"+++@dataclass(frozen=True)+class WorkflowListWarning:+ workflow_id: str+ message: str+ code: Literal["invalid_registry_entry"] = "invalid_registry_entry"+ kind: Literal["warning"] = "warning"+++@dataclass(frozen=True)+class WorkflowListResult:+ # Warnings stay in registry order, including an all-invalid registry.+ items: tuple[WorkflowListEntry | WorkflowListWarning, ...]+ truncated: bool = False+++class WorkflowListError(Exception):+ """Expected operation failure; adapters own presentation and sanitization."""++ def __init__(self, code: str, message: str) -> None:+ self.code = code+ self.details: dict[str, str] = {}+ self.retryable = False+ super().__init__(message)+++@dataclass(frozen=True)+class WorkflowListOperationDescriptor:+ operation_id: Literal["workflow.list"]+ contract_version: Literal["1"]+ request_type: type[WorkflowListRequest]+ result_type: type[WorkflowListResult]+ warning_types: tuple[type[WorkflowListWarning], ...]+ error_types: tuple[type[WorkflowListError], ...]+ capabilities: frozenset[Literal["local-read"]]+ network_access: Literal["none"]+++WORKFLOW_LIST_OPERATION = WorkflowListOperationDescriptor(+ operation_id="workflow.list",+ contract_version="1",+ request_type=WorkflowListRequest,+ result_type=WorkflowListResult,+ warning_types=(WorkflowListWarning,),+ error_types=(WorkflowListError,),+ capabilities=frozenset({"local-read"}),+ network_access="none",+)+++def list_workflows(request: WorkflowListRequest) -> WorkflowListResult:+ """Read the registry without importing custom steps or repairing its contents."""+ root = request.project_directory+ if not isinstance(root, Path) or not root.is_absolute():+ raise WorkflowListError(+ "invalid_project_directory", "project_directory must be an absolute path"+ )+ limit = request.limit+ if limit is not None and (+ type(limit) is not int or not 1 <= limit <= WORKFLOW_LIST_MAX_LIMIT+ ):+ raise WorkflowListError(+ "invalid_limit", f"limit must be between 1 and {WORKFLOW_LIST_MAX_LIMIT}"+ )+ try:+ # Unlike is_dir(), stat() preserves permission errors on Python 3.14.+ try:+ root_is_directory = stat.S_ISDIR(root.stat().st_mode)+ except (FileNotFoundError, NotADirectoryError, ValueError):+ root_is_directory = False+ if not root_is_directory:+ raise WorkflowListError(+ "not_a_spec_kit_project",+ "Not a Spec Kit project (no .specify/ directory)",+ )+ files = project_files(root)+ if not (root / ".specify").is_dir():+ raise WorkflowListError(+ "not_a_spec_kit_project",+ "Not a Spec Kit project (no .specify/ directory)",+ )+ validate_workflow_storage(root)+ except (ProjectPolicyError, WorkflowStorageError, OSError) as exc:+ raise WorkflowListError("unsafe_workflow_storage", str(exc)) from exc++ try:+ installed = WorkflowRegistry(root, read_files=files).list()+ except OSError as exc:+ raise WorkflowListError(+ "workflow_registry_read_failed", f"Failed to read workflow registry: {exc}"+ ) from exc++ items: list[WorkflowListEntry | WorkflowListWarning] = []+ selected = installed.items() if limit is None else islice(installed.items(), limit)+ for workflow_id, metadata in selected:+ if not isinstance(metadata, dict):+ items.append(+ WorkflowListWarning(+ workflow_id=workflow_id,+ message=f"Skipping corrupted registry entry '{workflow_id}'.",+ )+ )+ continue+ description = metadata.get("description", "")+ items.append(+ WorkflowListEntry(+ id=workflow_id,+ name=str(metadata.get("name", workflow_id)),+ version=str(metadata.get("version", "?")),+ description=str(description) if description else None,+ enabled=bool(metadata.get("enabled", True)),+ )+ )+ return WorkflowListResult(+ items=tuple(items), truncated=limit is not None and len(installed) > limit+ )diff --git a/src/specify_cli/workflows/_storage.py b/src/specify_cli/workflows/_storage.pynew file mode 100644index 000000000..f33f3daf0--- /dev/null+++ b/src/specify_cli/workflows/_storage.py@@ -0,0 +1,22 @@+"""Transport-neutral validation of existing workflow storage boundaries."""++from pathlib import Path+++class WorkflowStorageError(ValueError):+ """A workflow storage directory is symlinked or has the wrong type."""+++def validate_workflow_storage(project_root: Path) -> None:+ """Check storage without creating directories or following child symlinks."""+ for suffix in (+ ".specify",+ ".specify/workflows",+ ".specify/workflows/runs",+ ".specify/workflows/overlays",+ ):+ path = project_root / suffix+ if path.is_symlink():+ raise WorkflowStorageError(f"Refusing to use symlinked {suffix} path")+ if path.exists() and not path.is_dir():+ raise WorkflowStorageError(f"{suffix} path exists but is not a directory")diff --git a/src/specify_cli/workflows/catalog/_domain.py b/src/specify_cli/workflows/catalog/_domain.pyindex cc29a0b0c..4aaf82532 100644--- a/src/specify_cli/workflows/catalog/_domain.py+++ b/src/specify_cli/workflows/catalog/_domain.py@@ -26,6 +26,7 @@ from ..._download_security import (MAX_JSON_CATALOG_BYTES as MAX_JSON_CATALOG_BYTES,read_response_limited,)+from ...file_helper import FileHelper, FileHelperErrorfrom .._catalog_cache import read_cache_json, write_cache_jsonlogger = logging.getLogger(__name__)@@ -82,10 +83,15 @@ class WorkflowRegistry:REGISTRY_FILE = "workflow-registry.json"SCHEMA_VERSION = "1.0"- def __init__(self, project_root: Path) -> None:+ def __init__(+ self, project_root: Path, *, read_files: FileHelper | None = None+ ) -> None:self.project_root = project_rootself.workflows_dir = project_root / ".specify" / "workflows"self.registry_path = self.workflows_dir / self.REGISTRY_FILE+ # Optional read-policy handoff for workflow.list. Existing callers and+ # all mutation paths retain their established behavior.+ self._read_files = read_filesself.data = self._load()def _has_symlinked_parent(self) -> bool:@@ -116,14 +122,22 @@ class WorkflowRegistry:f"Refusing to read workflow registry at {self.registry_path}: ""a parent directory or the registry file itself is a symlink")- if self.registry_path.exists():+ if self._read_files is not None or self.registry_path.exists():try:- with open(self.registry_path, encoding="utf-8") as f:- data = json.load(f)- except OSError as exc:- # The real data may still be intact on disk. Fail closed at- # construction rather than fabricating an empty registry that- # a read-only caller could mistake for "nothing installed."+ if self._read_files is None:+ with open(self.registry_path, encoding="utf-8") as f:+ data = json.load(f)+ else:+ try:+ text = self._read_files.read_text(self.registry_path)+ except FileNotFoundError:+ return default_registry+ # Match the legacy text stream's universal-newline handling,+ # including JSON error offsets for malformed CRLF files.+ text = text.replace("\r\n", "\n").replace("\r", "\n")+ data = json.loads(text)+ except (OSError, FileHelperError) as exc:+ # Do not fabricate an empty registry on access/policy failures.raise OSError(f"Failed to read workflow registry at {self.registry_path}: {exc}") from excdiff --git a/src/specify_cli/workflows/command_list.py b/src/specify_cli/workflows/command_list.pyindex 69cc3be39..d803a2f91 100644--- a/src/specify_cli/workflows/command_list.py+++ b/src/specify_cli/workflows/command_list.py@@ -3,34 +3,38 @@from __future__ import annotationsfrom . import _commands as cli+from . import _operation_list as operation@cli.workflow_app.command("list")def workflow_list():"""List installed workflows."""project_root = cli._require_specify_project()- registry = cli._open_workflow_registry(project_root)- installed = registry.list()+ try:+ result = operation.list_workflows(operation.WorkflowListRequest(project_root))+ except operation.WorkflowListError as exc:+ cli.console.print(f"[red]Error:[/red] {cli._escape_markup(str(exc))}")+ raise cli.typer.Exit(1) from exc- if not installed:+ if not result.items:cli.console.print("[yellow]No workflows installed.[/yellow]")cli.console.print("\nInstall a workflow with:")cli.console.print(" [cyan]specify workflow add <workflow-id>[/cyan]")returncli.console.print("\n[bold cyan]Installed Workflows:[/bold cyan]\n")- for wf_id, wf_data in installed.items():- safe_id = cli._escape_markup(wf_id)- if not isinstance(wf_data, dict):+ for item in result.items:+ if isinstance(item, operation.WorkflowListWarning):cli.console.print(- f" [yellow]Warning:[/yellow] Skipping corrupted registry entry '{safe_id}'.\n"+ f" [yellow]Warning:[/yellow] {cli._escape_markup(item.message)}\n")continue- marker = "" if wf_data.get("enabled", True) else " [red]\\[disabled][/red]"- name = cli._escape_markup(str(wf_data.get("name", wf_id)))- version = cli._escape_markup(str(wf_data.get("version", "?")))+ safe_id = cli._escape_markup(item.id)+ marker = "" if item.enabled else " [red]\\[disabled][/red]"+ name = cli._escape_markup(item.name)+ version = cli._escape_markup(item.version)cli.console.print(f" [bold]{name}[/bold] ({safe_id}) v{version}{marker}")- desc = wf_data.get("description", "")+ desc = item.descriptionif desc:cli.console.print(f" {cli._escape_markup(str(desc))}")cli.console.print()diff --git a/src/specify_cli/workflows/mcp_list.py b/src/specify_cli/workflows/mcp_list.pynew file mode 100644index 000000000..9c5bcd5e5--- /dev/null+++ b/src/specify_cli/workflows/mcp_list.py@@ -0,0 +1,230 @@+"""Strict MCP projection of the shared installed-workflow list operation."""++from __future__ import annotations++import logging+from collections.abc import Callable+from dataclasses import asdict+from pathlib import Path+from typing import Annotated, Any, Literal++from mcp.server import MCPServer+from mcp.types import CallToolResult, TextContent, ToolAnnotations+from pydantic import BaseModel, ConfigDict, Field++from . import _operation_list as operation++logger = logging.getLogger(__name__)+_MAX_WIRE_RESPONSE_BYTES = 1024 * 1024+_WIRE_ENVELOPE_RESERVE_BYTES = 1024+WorkflowListLimit = Annotated[+ int, Field(strict=True, ge=1, le=operation.WORKFLOW_LIST_MAX_LIMIT)+]+WorkflowProjectDirectory = Annotated[str, Field(strict=True)]+++class WorkflowListToolInput(BaseModel):+ model_config = ConfigDict(extra="forbid", strict=True)+ project_directory: WorkflowProjectDirectory | None = None+ limit: WorkflowListLimit = 100+++class WorkflowEntryResult(BaseModel):+ model_config = ConfigDict(extra="forbid", strict=True)+ kind: Literal["workflow"]+ id: str+ name: str+ version: str+ description: str | None+ enabled: bool+++class WorkflowWarningResult(BaseModel):+ model_config = ConfigDict(extra="forbid", strict=True)+ kind: Literal["warning"]+ code: Literal["invalid_registry_entry"]+ workflow_id: str+ message: str+++class WorkflowListToolResult(BaseModel):+ model_config = ConfigDict(extra="forbid", strict=True)+ items: list[+ Annotated[+ WorkflowEntryResult | WorkflowWarningResult, Field(discriminator="kind")+ ]+ ] = Field(max_length=operation.WORKFLOW_LIST_MAX_LIMIT)+ truncated: bool+++WorkflowListCallResult = Annotated[CallToolResult, WorkflowListToolResult]+WorkflowListTool = Callable[[str | None, int], CallToolResult]+++class _InvalidOperationResult(Exception):+ """The shared outcome does not match the declared result contract."""+++def _convert_result(+ result: operation.WorkflowListResult,+ *,+ requested_limit: int,+) -> WorkflowListToolResult:+ try:+ if not isinstance(result, operation.WorkflowListResult):+ raise TypeError("Expected WorkflowListResult")+ if len(result.items) > requested_limit:+ raise ValueError("Operation exceeded requested limit")+ if result.truncated and len(result.items) != requested_limit:+ raise ValueError("Truncated result must fill the requested limit")+ return WorkflowListToolResult.model_validate(+ {+ "items": [asdict(item) for item in result.items],+ "truncated": result.truncated,+ },+ strict=True,+ )+ except (TypeError, ValueError, AttributeError) as exc:+ raise _InvalidOperationResult from exc+++def _tool_error(code: str, message: str, *, retryable: bool = False) -> CallToolResult:+ return CallToolResult(+ content=[TextContent(type="text", text=f"{code}: {message}")],+ structured_content={+ "error": {+ "code": code,+ "message": message,+ "details": {},+ "retryable": retryable,+ }+ },+ is_error=True,+ )+++def _wire_response_size(result: CallToolResult) -> int:+ return (+ len(result.model_dump_json(by_alias=True, exclude_none=True).encode("utf-8"))+ + _WIRE_ENVELOPE_RESERVE_BYTES+ )+++def _response_too_large() -> CallToolResult:+ return _tool_error(+ "response_too_large",+ "Workflow list response exceeds the byte limit; retry with a smaller limit.",+ retryable=True,+ )+++def create_workflow_list_tool(+ *,+ launch_directory: Path,+ max_wire_response_bytes: int = _MAX_WIRE_RESPONSE_BYTES,+) -> WorkflowListTool:+ """Bind the default project once; never change process cwd for requests."""+ launch_directory = Path(launch_directory)+ if not launch_directory.is_absolute():+ raise ValueError("MCP server launch directory must be absolute")+ if _wire_response_size(_response_too_large()) > max_wire_response_bytes:+ raise ValueError(+ "MCP response-size limit cannot hold the bounded error response"+ )++ def specify_workflow_list(+ project_directory: WorkflowProjectDirectory | None = None,+ limit: WorkflowListLimit = 100,+ ) -> WorkflowListCallResult:+ """List installed workflows and skipped-entry warnings in registry order."""+ tool_input = WorkflowListToolInput.model_validate(+ {"project_directory": project_directory, "limit": limit}, strict=True+ )+ try:+ result = operation.list_workflows(+ operation.WorkflowListRequest(+ project_directory=(+ launch_directory+ if tool_input.project_directory is None+ else Path(tool_input.project_directory)+ ),+ limit=tool_input.limit,+ )+ )+ payload = _convert_result(result, requested_limit=tool_input.limit)+ response = CallToolResult(+ content=[+ TextContent(type="text", text=payload.model_dump_json(indent=2))+ ],+ structured_content=payload.model_dump(mode="json"),+ is_error=False,+ )+ except operation.WorkflowListError as exc:+ # Registry/OS exception strings can contain paths or untrusted data.+ # CLI retains its established diagnostics; MCP never exposes them.+ messages = {+ "invalid_project_directory": "project_directory must be an absolute path.",+ "not_a_spec_kit_project": "The selected directory is not a Spec Kit project.",+ "unsafe_workflow_storage": "The selected workflow storage is unsafe or unreadable.",+ "workflow_registry_read_failed": "Unable to read the workflow registry.",+ "invalid_limit": "The workflow list limit is invalid.",+ }+ response = _tool_error(+ exc.code, messages.get(exc.code, "Unable to list workflows.")+ )+ except _InvalidOperationResult:+ response = _tool_error(+ "invalid_operation_result", "The workflow list result is invalid."+ )+ except Exception:+ logger.exception("Unexpected failure in the workflow list MCP adapter.")+ response = _tool_error(+ "internal_error", "Unable to list installed workflows."+ )+ if _wire_response_size(response) > max_wire_response_bytes:+ return _response_too_large()+ return response++ return specify_workflow_list+++def _lookup_registered_tool(server: MCPServer, name: str) -> Any:+ try:+ return server._tool_manager.get_tool(name)+ except Exception as exc:+ raise RuntimeError(+ "MCP SDK compatibility error: registered tool lookup failed"+ ) from exc+++def register(+ server: MCPServer,+ *,+ launch_directory: Path,+ tool_name: str = "specify_workflow_list",+) -> None:+ """Register once, closing SDK argument validation as well as discovery."""+ if _lookup_registered_tool(server, tool_name) is not None:+ raise ValueError(f"MCP tool name collision: {tool_name}")+ server.add_tool(+ create_workflow_list_tool(launch_directory=launch_directory),+ name=tool_name,+ description=(+ "List installed workflows and warnings without execution or network access. "+ "limit bounds registry entries, including warnings; truncated reports omitted entries."+ ),+ annotations=ToolAnnotations(+ read_only_hint=True, idempotent_hint=True, open_world_hint=False+ ),+ structured_output=True,+ )+ try:+ tool = _lookup_registered_tool(server, tool_name)+ argument_model = tool.fn_metadata.arg_model+ argument_model.model_config["extra"] = "forbid"+ argument_model.model_rebuild(force=True)+ tool.parameters = argument_model.model_json_schema(by_alias=True)+ except Exception as exc:+ raise RuntimeError(+ "MCP SDK compatibility error while closing workflow list arguments"+ ) from excdiff --git a/tests/specify_cli/mcp_server/test_server.py b/tests/specify_cli/mcp_server/test_server.pyindex efea3b588..a0998fce2 100644--- a/tests/specify_cli/mcp_server/test_server.py+++ b/tests/specify_cli/mcp_server/test_server.py@@ -33,6 +33,7 @@ def test_tool_discovery_exposes_first_class_and_transitional_tools(tmp_path):"specify_version","specify_artifact_list","specify_artifact_info",+ "specify_workflow_list",]schemas = {tool.name: tool.input_schema for tool in tools}assert schemas["specify_list_commands"]["properties"] == {}diff --git a/tests/specify_cli/mcp_server/test_stdio.py b/tests/specify_cli/mcp_server/test_stdio.pyindex 377ddb2cd..bd1553bcc 100644--- a/tests/specify_cli/mcp_server/test_stdio.py+++ b/tests/specify_cli/mcp_server/test_stdio.py@@ -11,7 +11,9 @@ _READ_TIMEOUT_SECONDS = 10_TEST_TIMEOUT_SECONDS = 30-def test_real_stdio_server_initializes_discovers_and_calls_first_class_tools():+def test_real_stdio_server_initializes_discovers_and_calls_first_class_tools(tmp_path):+ (tmp_path / ".specify").mkdir()+async def exercise() -> None:repo_root = Path(__file__).resolve().parents[3]parameters = StdioServerParameters(@@ -34,6 +36,12 @@ def test_real_stdio_server_initializes_discovers_and_calls_first_class_tools():tools = await session.list_tools()listed = await session.call_tool("specify_list_commands", {})version = await session.call_tool("specify_version", {})+ workflows = await session.call_tool(+ "specify_workflow_list", {"project_directory": str(tmp_path)}+ )+ workflow_failure = await session.call_tool(+ "specify_workflow_list", {"project_directory": "relative"}+ )artifacts = await session.call_tool("specify_artifact_list", {})artifact = await session.call_tool("specify_artifact_info",@@ -65,6 +73,7 @@ def test_real_stdio_server_initializes_discovers_and_calls_first_class_tools():"specify_version","specify_artifact_list","specify_artifact_info",+ "specify_workflow_list",]assert listed.structured_content["commands"][0]["command"] == "version"assert set(version.structured_content) == {@@ -74,6 +83,13 @@ def test_real_stdio_server_initializes_discovers_and_calls_first_class_tools():"features",}assert version.is_error is False+ assert workflows.is_error is False+ assert workflows.structured_content == {"items": [], "truncated": False}+ assert workflow_failure.is_error is True+ assert (+ workflow_failure.structured_content["error"]["code"]+ == "invalid_project_directory"+ )assert artifacts.is_error is Falseassert isinstance(artifacts.structured_content["rows"], list)assert artifacts.structured_content["rows"]diff --git a/tests/specify_cli/workflows/test_command_list.py b/tests/specify_cli/workflows/test_command_list.pyindex 18e42cf5c..404a1d6be 100644--- a/tests/specify_cli/workflows/test_command_list.py+++ b/tests/specify_cli/workflows/test_command_list.py@@ -4,11 +4,43 @@ from __future__ import annotationsimport jsonimport os-from pathlib import Pathimport pytest[email protected]("entries,expected", [+ ({}, "No workflows installed.\n\nInstall a workflow with:\n specify workflow add <workflow-id>\n"),+ ({"bad": None}, "\nInstalled Workflows:\n\n Warning: Skipping corrupted registry entry 'bad'.\n\n"),+ ({"z": {"enabled": False}, "bad": 1, "a": {"name": "[Name]", "description": "[desc]"}},+ "\nInstalled Workflows:\n\n z (z) v? [disabled]\n\n Warning: Skipping corrupted registry entry 'bad'.\n\n [Name] (a) v?\n [desc]\n\n"),+])+def test_list_preserves_complete_cli_text(tmp_path, monkeypatch, entries, expected):+ from typer.testing import CliRunner+ from specify_cli import app++ directory = tmp_path / ".specify" / "workflows"+ directory.mkdir(parents=True)+ (directory / "workflow-registry.json").write_text(json.dumps({"workflows": entries}), encoding="utf-8")+ monkeypatch.setenv("SPECIFY_INIT_DIR", str(tmp_path))+ result = CliRunner().invoke(app, ["workflow", "list"])+ assert result.exit_code == 0, result.output+ assert result.output == expected+++def test_cli_does_not_adopt_mcp_entry_limit(tmp_path, monkeypatch):+ from typer.testing import CliRunner+ from specify_cli import app++ directory = tmp_path / ".specify" / "workflows"+ directory.mkdir(parents=True)+ entries = {f"workflow-{i}": {} for i in range(1001)}+ (directory / "workflow-registry.json").write_text(json.dumps({"workflows": entries}), encoding="utf-8")+ monkeypatch.setenv("SPECIFY_INIT_DIR", str(tmp_path))+ result = CliRunner().invoke(app, ["workflow", "list"])+ assert result.exit_code == 0, result.output+ assert "workflow-1000 (workflow-1000) v?" in result.output++class TestWorkflowAddSymlinkGuard:@pytest.mark.skipif(not hasattr(os, "symlink"), reason="symlinks are unavailable")@@ -96,7 +128,7 @@ steps:is exactly the fail-open state a caller could otherwise mistake for"safe to (re)install", overwriting real files. Covers the read/queryboundary fix required at every WorkflowRegistry call site."""- import builtins+ from specify_cli.file_helper import FileHelperfrom typer.testing import CliRunnerfrom specify_cli import appfrom specify_cli.workflows.catalog import WorkflowRegistry@@ -106,14 +138,14 @@ steps:self._install_dev(runner, app, project_dir)registry_path = WorkflowRegistry(project_dir).registry_path.resolve()- real_open = builtins.open+ real_read = FileHelper.read_bytes- def _raising_open(file, mode="r", *args, **kwargs):- if Path(file).resolve() == registry_path and "r" in mode:+ def _raising_read(files, file):+ if (files.root / file).resolve() == registry_path:raise OSError("simulated read failure")- return real_open(file, mode, *args, **kwargs)+ return real_read(files, file)- monkeypatch.setattr(builtins, "open", _raising_open)+ monkeypatch.setattr(FileHelper, "read_bytes", _raising_read)result = runner.invoke(app, ["workflow", "list"])assert result.exit_code != 0assert result.exception is None or isinstance(result.exception, SystemExit)diff --git a/tests/specify_cli/workflows/test_mcp.py b/tests/specify_cli/workflows/test_mcp.pyindex ff5676789..3136ba89c 100644--- a/tests/specify_cli/workflows/test_mcp.py+++ b/tests/specify_cli/workflows/test_mcp.py@@ -26,6 +26,8 @@ from specify_cli.mcp_server.catalog import ()from specify_cli.mcp_server.server import create_serverfrom specify_cli.workflows import _commands, _mcp+from specify_cli.workflows._operation_list import WORKFLOW_LIST_OPERATION+from specify_cli.workflows.mcp_list import WorkflowListToolInput, WorkflowListToolResultfrom specify_cli.workflows.step import catalog as step_catalog@@ -68,13 +70,7 @@ def _assert_inventory(cli_paths: Sequence[str],tools: Sequence[Tool],) -> None:- """Validate accounting and fail closed for available workflow records.-- No shared workflow operation descriptors exist yet. Real available records- must fail closed until operation-specific assertions bind their descriptor,- version, effects and adapter schemas, as in the artifact inventory tests.- A matching name and object schemas alone cannot establish that binding.- """+ """Bind the one implemented contract; fail closed for all other operations."""for label, values in (("operation IDs", [item.operation_id for item in records]),("CLI paths", [item.cli_path for item in records]),@@ -127,9 +123,17 @@ def _assert_inventory(f"Available reason: {item.operation_id}")_assert_synthetic_discovery_shape(item, tools)- raise AssertionError(+ assert item.operation_id == WORKFLOW_LIST_OPERATION.operation_id, (f"No workflow operation contract evidence: {item.operation_id}")+ assert item.contract_version == WORKFLOW_LIST_OPERATION.contract_version+ assert item.capabilities == WORKFLOW_LIST_OPERATION.capabilities+ assert item.network_access == WORKFLOW_LIST_OPERATION.network_access+ tool = matching[0]+ expected_input = WorkflowListToolInput.model_json_schema()+ assert tool.input_schema["properties"] == expected_input["properties"]+ assert tool.input_schema["additionalProperties"] is False+ assert tool.output_schema == WorkflowListToolResult.model_json_schema()else:assert item.contract_version is None, (f"Nonavailable tool has contract version: {item.operation_id}"@@ -397,13 +401,14 @@ def test_uninventoried_workflow_tool_is_rejected(available_record_and_tool):_assert_inventory([], [], [tool])-def test_existing_server_and_legacy_catalog_are_unchanged(tmp_path):+def test_server_adds_only_workflow_list_and_preserves_legacy_catalog(tmp_path):tools = asyncio.run(create_server(launch_directory=tmp_path).list_tools())assert Counter(tool.name for tool in tools) == Counter({"specify_version": 1,"specify_artifact_list": 1,"specify_artifact_info": 1,+ "specify_workflow_list": 1,"specify_list_commands": 1,"specify_describe_command": 1,"specify_run_command": 1,@@ -414,6 +419,11 @@ def test_existing_server_and_legacy_catalog_are_unchanged(tmp_path):with pytest.raises(CommandAdapterError) as exc:describe_command("workflow.run")assert exc.value.code == "unavailable_command"+ assert [+ item.operation_id+ for item in _mcp.WORKFLOW_TOOLS+ if item.disposition == "available"+ ] == ["workflow.list"]@pytest.mark.parametrize("operation_id", ["workflow.run", "workflow.resume"])diff --git a/tests/specify_cli/workflows/test_mcp_list.py b/tests/specify_cli/workflows/test_mcp_list.pynew file mode 100644index 000000000..44a0eda3b--- /dev/null+++ b/tests/specify_cli/workflows/test_mcp_list.py@@ -0,0 +1,423 @@+"""Strict schemas, dispatch, bounds and discovery for workflow.list."""++import asyncio+import json+from concurrent.futures import ThreadPoolExecutor+from dataclasses import replace+from pathlib import Path++import pytest+import anyio+from mcp import ClientSession+from mcp.server import MCPServer+from mcp.server.mcpserver.exceptions import ToolError+from mcp.shared.memory import create_client_server_memory_streams+from pydantic import ValidationError+from typer.testing import CliRunner++from specify_cli import app+from specify_cli.mcp_server.server import create_server+from specify_cli.workflows import _mcp, _operation_list as operation, mcp_list+++def _run(coro):+ return asyncio.run(coro)+++def _project(root, entries):+ directory = root / ".specify" / "workflows"+ directory.mkdir(parents=True)+ (directory / "workflow-registry.json").write_text(+ json.dumps({"workflows": entries}), encoding="utf-8"+ )+ return root+++def test_actual_discovery_schema_annotations_and_collision(tmp_path):+ server = MCPServer(name="test")+ _mcp.register(server, launch_directory=tmp_path)+ tools = _run(server.list_tools())+ assert len(tools) == 1+ tool = tools[0]+ assert tool.name == "specify_workflow_list"+ assert (+ tool.input_schema["properties"]+ == mcp_list.WorkflowListToolInput.model_json_schema()["properties"]+ )+ assert tool.input_schema["additionalProperties"] is False+ assert set(tool.input_schema["properties"]) == {"project_directory", "limit"}+ assert tool.input_schema["properties"]["limit"] == {+ "type": "integer",+ "title": "Limit",+ "default": 100,+ "minimum": 1,+ "maximum": 1000,+ }+ assert tool.output_schema == mcp_list.WorkflowListToolResult.model_json_schema()+ assert set(tool.output_schema["properties"]) == {"items", "truncated"}+ assert set(tool.output_schema["required"]) == {"items", "truncated"}+ assert set(tool.output_schema["$defs"]["WorkflowEntryResult"]["properties"]) == {+ "kind",+ "id",+ "name",+ "version",+ "description",+ "enabled",+ }+ assert (+ tool.output_schema["$defs"]["WorkflowEntryResult"]["additionalProperties"]+ is False+ )+ assert tool.annotations.read_only_hint is True+ assert tool.annotations.idempotent_hint is True+ assert tool.annotations.open_world_hint is False+ with pytest.raises(ValueError, match="collision"):+ _mcp.register(server, launch_directory=tmp_path)+ assert len(_run(server.list_tools())) == 1+++def test_shared_operation_used_by_both_adapters(tmp_path, monkeypatch):+ (tmp_path / ".specify").mkdir()+ monkeypatch.setenv("SPECIFY_INIT_DIR", str(tmp_path))+ requests = []+ result = operation.WorkflowListResult(+ (operation.WorkflowListEntry("id", "Name", "1", None, True),)+ )++ def collect(request):+ requests.append(request)+ return result++ monkeypatch.setattr(operation, "list_workflows", collect)+ cli = CliRunner().invoke(app, ["workflow", "list"])+ assert cli.exit_code == 0, cli.output+ assert "Name (id) v1" in cli.output+ server = create_server(launch_directory=tmp_path)+ response = _run(server.call_tool("specify_workflow_list", {}))+ assert response.is_error is False+ assert response.structured_content["items"][0]["name"] == "Name"+ assert requests == [+ operation.WorkflowListRequest(tmp_path),+ operation.WorkflowListRequest(tmp_path, 100),+ ]+++ "arguments",+ [+ {"extra": True},+ {"limit": 0},+ {"limit": 1001},+ {"limit": True},+ {"limit": "1"},+ {"limit": 1.5},+ {"limit": None},+ {"project_directory": 4},+ ],+)+def test_sdk_rejects_invalid_input_before_operation(tmp_path, monkeypatch, arguments):+ monkeypatch.setattr(+ operation, "list_workflows", lambda *a: pytest.fail("Unexpected dispatch")+ )+ # The SDK's direct server API raises ToolError; the protocol layer converts+ # that into a text-only error response (exercised separately below).+ with pytest.raises(ToolError):+ _run(+ create_server(launch_directory=tmp_path).call_tool(+ "specify_workflow_list", arguments+ )+ )+++def test_real_registry_result_warnings_and_limit(tmp_path):+ _project(tmp_path, {"z": {"enabled": False}, "bad": [], "a": {}})+ server = create_server(launch_directory=tmp_path)+ response = _run(server.call_tool("specify_workflow_list", {"limit": 2}))+ assert response.is_error is False+ data = response.structured_content+ assert [item["kind"] for item in data["items"]] == ["workflow", "warning"]+ assert data["items"][0]["enabled"] is False+ assert data["items"][1]["code"] == "invalid_registry_entry"+ assert data["truncated"] is True+ assert json.loads(response.content[0].text) == data++[email protected]("kind", ["missing", "file"])+def test_invalid_project_roots_return_not_a_project(tmp_path, kind):+ root = tmp_path / "not-a-project"+ if kind == "file":+ root.write_text("not a directory", encoding="utf-8")+ server = create_server(launch_directory=tmp_path)+ response = _run(+ server.call_tool("specify_workflow_list", {"project_directory": str(root)})+ )+ assert response.is_error is True+ assert response.structured_content["error"]["code"] == "not_a_spec_kit_project"+ assert str(root) not in response.model_dump_json()+++def test_absolute_project_path_with_embedded_nul_returns_not_a_project(tmp_path):+ root = tmp_path / "invalid\x00project"+ assert root.is_absolute()+ response = _run(+ create_server(launch_directory=tmp_path).call_tool(+ "specify_workflow_list", {"project_directory": str(root)}+ )+ )+ assert response.is_error is True+ assert response.structured_content["error"]["code"] == "not_a_spec_kit_project"++[email protected]("kind", ["policy", "storage"])+def test_unsafe_project_storage_keeps_structured_error(tmp_path, kind):+ root = _project(tmp_path / "project", {})+ if kind == "policy":+ path = root / ".specify" / "init-options.json"+ path.write_text('{"allow_symlinks": "yes"}', encoding="utf-8")+ else:+ path = root / ".specify" / "workflows" / "runs"+ path.write_text("not a directory", encoding="utf-8")+ response = _run(+ create_server(launch_directory=tmp_path).call_tool(+ "specify_workflow_list", {"project_directory": str(root)}+ )+ )+ assert response.is_error is True+ assert response.structured_content["error"]["code"] == "unsafe_workflow_storage"+ assert str(root) not in response.model_dump_json()+++def test_launch_directory_captured_and_explicit_projects_are_independent(+ tmp_path, monkeypatch+):+ first = _project(tmp_path / "first", {"one": {}})+ second = _project(tmp_path / "second", {"two": {}})+ tool = mcp_list.create_workflow_list_tool(launch_directory=first)+ monkeypatch.chdir(second)+ monkeypatch.setenv("SPECIFY_INIT_DIR", str(second))+ assert tool().structured_content["items"][0]["id"] == "one"+ with ThreadPoolExecutor(max_workers=2) as pool:+ results = list(pool.map(lambda root: tool(str(root), 100), [first, second]))+ assert [r.structured_content["items"][0]["id"] for r in results] == ["one", "two"]+ assert Path.cwd() == second+ relative = tool("relative", 100)+ assert relative.structured_content["error"]["code"] == "invalid_project_directory"+++ "error",+ [+ operation.WorkflowListError(+ "workflow_registry_read_failed", "secret /private/path"+ ),+ RuntimeError("secret /private/path"),+ TypeError("secret /private/path"),+ ],+)+def test_error_mapping_never_exposes_exception_details(tmp_path, monkeypatch, error):+ def fail(request):+ raise error++ monkeypatch.setattr(operation, "list_workflows", fail)+ response = mcp_list.create_workflow_list_tool(launch_directory=tmp_path)()+ assert response.is_error is True+ code = (+ "workflow_registry_read_failed"+ if isinstance(error, operation.WorkflowListError)+ else "internal_error"+ )+ assert response.structured_content["error"]["code"] == code+ assert "secret" not in response.model_dump_json()+ assert "/private/path" not in response.model_dump_json()+++ "result",+ [+ None,+ {"items": []},+ operation.WorkflowListResult(("bad",)),+ operation.WorkflowListResult(+ (operation.WorkflowListEntry("id", "n", "v", None, "yes"),)+ ),+ ],+)+def test_invalid_operation_outcomes_are_rejected(tmp_path, monkeypatch, result):+ monkeypatch.setattr(operation, "list_workflows", lambda request: result)+ response = mcp_list.create_workflow_list_tool(launch_directory=tmp_path)()+ assert response.is_error is True+ assert response.structured_content["error"]["code"] == "invalid_operation_result"+++ "limit,count,truncated",+ [+ (1, 2, False),+ (100, 101, True),+ (1000, 1001, False),+ (100, 0, True),+ (100, 99, True),+ (1000, 999, True),+ ],+)+def test_operation_result_must_obey_requested_limit_and_truncation(+ tmp_path,+ monkeypatch,+ limit,+ count,+ truncated,+):+ items = tuple(+ operation.WorkflowListEntry(str(i), "N", "1", None, True) for i in range(count)+ )+ monkeypatch.setattr(+ operation,+ "list_workflows",+ lambda request: operation.WorkflowListResult(items, truncated),+ )+ response = mcp_list.create_workflow_list_tool(launch_directory=tmp_path)(+ None, limit+ )+ assert response.is_error is True+ assert response.structured_content["error"]["code"] == "invalid_operation_result"++[email protected]("limit", [100, 1000])[email protected]("extra", [0, 1])+def test_real_result_boundaries_preserve_order_and_warnings(tmp_path, limit, extra):+ entries = {str(i): (None if i == 1 else {}) for i in range(limit + extra)}+ _project(tmp_path, entries)+ tool = mcp_list.create_workflow_list_tool(launch_directory=tmp_path)+ response = tool() if limit == 100 else tool(None, limit)+ assert response.is_error is False+ payload = response.structured_content+ assert len(payload["items"]) == limit+ assert [+ item.get("id", item.get("workflow_id")) for item in payload["items"]+ ] == list(entries)[:limit]+ assert payload["items"][1]["kind"] == "warning"+ assert payload["truncated"] is bool(extra)+++def test_output_schema_enforces_static_entry_ceiling():+ schema = mcp_list.WorkflowListToolResult.model_json_schema()+ assert schema["properties"]["items"]["maxItems"] == 1000+ row = {+ "kind": "workflow",+ "id": "id",+ "name": "N",+ "version": "1",+ "description": None,+ "enabled": True,+ }+ with pytest.raises(ValidationError):+ mcp_list.WorkflowListToolResult.model_validate(+ {"items": [row] * 1001, "truncated": False}+ )+++def test_response_byte_budget_and_constructor_bounds(tmp_path, monkeypatch):+ result = operation.WorkflowListResult(+ (operation.WorkflowListEntry("id", "é" * 2000, "v", None, True),)+ )+ monkeypatch.setattr(operation, "list_workflows", lambda request: result)+ tool = mcp_list.create_workflow_list_tool(+ launch_directory=tmp_path, max_wire_response_bytes=2000+ )+ response = tool()+ assert response.structured_content["error"]["code"] == "response_too_large"+ assert mcp_list._wire_response_size(response) <= 2000+ assert response.structured_content["error"]["retryable"] is True+ with pytest.raises(ValueError, match="bounded error response"):+ mcp_list.create_workflow_list_tool(+ launch_directory=tmp_path, max_wire_response_bytes=10+ )+ with pytest.raises(ValueError, match="absolute"):+ mcp_list.create_workflow_list_tool(launch_directory=Path("relative"))+++ "field,value",+ [+ ("contract_version", "999-fabricated"),+ ("network_access", "optional"),+ ("capabilities", frozenset({"execution"})),+ ],+)+def test_real_available_inventory_must_match_descriptor(tmp_path, field, value):+ from .test_mcp import _assert_inventory, _workflow_cli_paths++ records = [+ replace(r, **{field: value}) if r.operation_id == "workflow.list" else r+ for r in _mcp.WORKFLOW_TOOLS+ ]+ tools = _run(create_server(launch_directory=tmp_path).list_tools())+ with pytest.raises(AssertionError):+ _assert_inventory(records, _workflow_cli_paths(), tools)+++def test_output_schema_rejects_extra_fields_and_wrong_types():+ with pytest.raises(ValidationError):+ mcp_list.WorkflowListToolResult.model_validate({"items": [], "truncated": "no"})+ with pytest.raises(ValidationError):+ mcp_list.WorkflowListToolResult.model_validate(+ {"items": [], "truncated": False, "extra": 1}+ )++[email protected]("field", ["input_schema", "output_schema"])+def test_correct_tool_name_with_unrelated_schema_fails_parity(tmp_path, field):+ from .test_mcp import _assert_inventory, _workflow_cli_paths++ tools = _run(create_server(launch_directory=tmp_path).list_tools())+ tools = [+ tool.model_copy(+ update={+ field: {+ "type": "object",+ "properties": {"unrelated": {"type": "string"}},+ }+ }+ )+ if tool.name == "specify_workflow_list"+ else tool+ for tool in tools+ ]+ with pytest.raises(AssertionError):+ _assert_inventory(_mcp.WORKFLOW_TOOLS, _workflow_cli_paths(), tools)+++def test_in_memory_protocol_success_expected_error_and_schema_error(tmp_path):+ _project(tmp_path, {"installed": {}})++ async def exercise():+ server = create_server(launch_directory=tmp_path)+ async with (+ create_client_server_memory_streams() as (client, streams),+ anyio.create_task_group() as tasks,+ ):+ tasks.start_soon(+ server._lowlevel_server.run,+ streams[0],+ streams[1],+ server._lowlevel_server.create_initialization_options(),+ )+ async with ClientSession(*client) as session:+ await session.initialize()+ success = await session.call_tool("specify_workflow_list", {})+ error = await session.call_tool(+ "specify_workflow_list", {"project_directory": "relative"}+ )+ invalid = await session.call_tool(+ "specify_workflow_list", {"unexpected": True}+ )+ tasks.cancel_scope.cancel()+ return success, error, invalid++ success, error, invalid = _run(exercise())+ assert success.is_error is False+ assert success.structured_content["items"][0]["id"] == "installed"+ assert error.is_error is True+ assert error.structured_content["error"]["code"] == "invalid_project_directory"+ assert invalid.is_error is True+ assert invalid.structured_content is Nonediff --git a/tests/specify_cli/workflows/test_operation_list.py b/tests/specify_cli/workflows/test_operation_list.pynew file mode 100644index 000000000..c2730dcb2--- /dev/null+++ b/tests/specify_cli/workflows/test_operation_list.py@@ -0,0 +1,342 @@+"""Transport-neutral installed-workflow contract and effect boundaries."""++import builtins+import errno+import io+import json+import os+import subprocess+from dataclasses import FrozenInstanceError+from pathlib import Path++import pytest++from specify_cli.workflows import _operation_list as operation+from specify_cli.file_helper import FileHelper+++def _registry(root, entries):+ directory = root / ".specify" / "workflows"+ directory.mkdir(parents=True)+ path = directory / "workflow-registry.json"+ path.write_text(json.dumps({"workflows": entries}), encoding="utf-8")+ return path+++def test_registry_order_defaults_and_warnings(tmp_path):+ _registry(+ tmp_path,+ {+ "z": {"description": ["old", "metadata"], "enabled": 0},+ "broken[entry]": None,+ "a": {"name": None, "version": 7},+ },+ )+ result = operation.list_workflows(operation.WorkflowListRequest(tmp_path))+ assert result == operation.WorkflowListResult(+ (+ operation.WorkflowListEntry("z", "z", "?", "['old', 'metadata']", False),+ operation.WorkflowListWarning(+ "broken[entry]", "Skipping corrupted registry entry 'broken[entry]'."+ ),+ operation.WorkflowListEntry("a", "None", "7", None, True),+ )+ )+ with pytest.raises(FrozenInstanceError):+ result.truncated = True+++def test_missing_registry_is_empty_without_creating_storage(tmp_path):+ (tmp_path / ".specify").mkdir()+ assert operation.list_workflows(operation.WorkflowListRequest(tmp_path)).items == ()+ assert list((tmp_path / ".specify").iterdir()) == []++[email protected]("contents", ["{", "[]", '{"workflows": []}', "\udcff"])+def test_corrupt_registry_fails_closed(tmp_path, contents):+ path = _registry(tmp_path, {})+ path.write_bytes(contents.encode("utf-8", errors="surrogateescape"))+ with pytest.raises(operation.WorkflowListError) as exc:+ operation.list_workflows(operation.WorkflowListRequest(tmp_path))+ assert exc.value.code == "workflow_registry_read_failed"++[email protected]("limit", [0, -1, 1001, True, "2", 1.5])+def test_invalid_limit_is_rejected_before_io(tmp_path, monkeypatch, limit):+ monkeypatch.setattr(+ operation,+ "project_files",+ lambda *a: pytest.fail("IO before validation"),+ )+ with pytest.raises(operation.WorkflowListError) as exc:+ operation.list_workflows(operation.WorkflowListRequest(tmp_path, limit))+ assert exc.value.code == "invalid_limit"+++def test_limit_counts_warnings_and_explicitly_reports_omissions(tmp_path):+ _registry(tmp_path, {"broken": 1, "ok": {}, "last": {}})+ request = operation.WorkflowListRequest(tmp_path, 2)+ result = operation.list_workflows(request)+ assert len(result.items) == 2+ assert result.truncated is True+ assert isinstance(result.items[0], operation.WorkflowListWarning)+ assert (+ operation.list_workflows(operation.WorkflowListRequest(tmp_path, 3)).truncated+ is False+ )+ assert (+ len(operation.list_workflows(operation.WorkflowListRequest(tmp_path)).items)+ == 3+ )+++def test_relative_and_nonproject_directories_are_rejected(tmp_path):+ with pytest.raises(operation.WorkflowListError) as exc:+ operation.list_workflows(operation.WorkflowListRequest(Path("relative")))+ assert exc.value.code == "invalid_project_directory"+ with pytest.raises(operation.WorkflowListError) as exc:+ operation.list_workflows(operation.WorkflowListRequest(tmp_path))+ assert exc.value.code == "not_a_spec_kit_project"++[email protected]("kind", ["missing", "file"])+def test_invalid_project_roots_are_rejected_before_policy_loading(+ tmp_path, monkeypatch, kind+):+ root = tmp_path / "not-a-project"+ if kind == "file":+ root.write_text("not a directory", encoding="utf-8")+ policy_calls = []+ original = operation.project_files++ def load_policy(path):+ policy_calls.append(path)+ return original(path)++ monkeypatch.setattr(operation, "project_files", load_policy)+ with pytest.raises(operation.WorkflowListError) as exc:+ operation.list_workflows(operation.WorkflowListRequest(root))+ assert exc.value.code == "not_a_spec_kit_project"+ assert policy_calls == []++[email protected]("boundary", ["root", "policy", "storage"])+def test_project_access_errors_remain_unsafe_storage(tmp_path, monkeypatch, boundary):+ (tmp_path / ".specify").mkdir()++ def denied(*args, **kwargs):+ raise PermissionError("private filesystem details")++ if boundary == "root":+ original_stat = Path.stat++ def root_stat(path, *args, **kwargs):+ if path == tmp_path:+ return denied()+ return original_stat(path, *args, **kwargs)++ monkeypatch.setattr(Path, "stat", root_stat)+ else:+ name = "project_files" if boundary == "policy" else "validate_workflow_storage"+ monkeypatch.setattr(operation, name, denied)+ with pytest.raises(operation.WorkflowListError) as exc:+ operation.list_workflows(operation.WorkflowListRequest(tmp_path))+ assert exc.value.code == "unsafe_workflow_storage"+++def test_invalid_project_policy_remains_unsafe_storage(tmp_path):+ (tmp_path / ".specify").mkdir()+ (tmp_path / ".specify" / "init-options.json").write_text(+ '{"allow_symlinks": "yes"}', encoding="utf-8"+ )+ with pytest.raises(operation.WorkflowListError) as exc:+ operation.list_workflows(operation.WorkflowListRequest(tmp_path))+ assert exc.value.code == "unsafe_workflow_storage"+++ "suffix",+ [+ ".specify",+ ".specify/workflows",+ ".specify/workflows/runs",+ ".specify/workflows/overlays",+ ],+)+def test_nondirectory_storage_is_rejected(tmp_path, suffix):+ target = tmp_path / suffix+ target.parent.mkdir(parents=True, exist_ok=True)+ target.write_text("not a directory", encoding="utf-8")+ with pytest.raises(operation.WorkflowStorageError) as storage_error:+ operation.validate_workflow_storage(tmp_path)+ assert str(storage_error.value) == f"{suffix} path exists but is not a directory"+ with pytest.raises(operation.WorkflowListError) as exc:+ operation.list_workflows(operation.WorkflowListRequest(tmp_path))+ assert exc.value.code == "unsafe_workflow_storage"+++ "suffix",+ [+ ".specify",+ ".specify/workflows",+ ".specify/workflows/runs",+ ".specify/workflows/overlays",+ ".specify/workflows/workflow-registry.json",+ ],+)+def test_symlinked_storage_is_rejected(tmp_path, suffix):+ root = tmp_path / "project"+ target = root / suffix+ target.parent.mkdir(parents=True, exist_ok=True)+ outside = tmp_path / "outside"+ is_file = suffix.endswith(".json")+ if is_file:+ outside.write_text('{"workflows": {}}', encoding="utf-8")+ else:+ outside.mkdir()+ try:+ target.symlink_to(outside, target_is_directory=not is_file)+ except OSError as exc:+ if exc.errno in {+ errno.EPERM,+ errno.ENOSYS,+ errno.ENOTSUP,+ errno.EOPNOTSUPP,+ } or getattr(exc, "winerror", None) in {50, 1314}:+ pytest.skip(f"Host cannot create symlinks: {exc}")+ raise+ with pytest.raises(operation.WorkflowListError) as exc:+ operation.list_workflows(operation.WorkflowListRequest(root))+ expected = "workflow_registry_read_failed" if is_file else "unsafe_workflow_storage"+ assert exc.value.code == expected+++def test_operation_has_no_writes_network_execution_or_rendering(+ tmp_path, monkeypatch, capsys+):+ from specify_cli.authentication import http+ from specify_cli.integrations import installer+ from specify_cli import workflows++ path = _registry(tmp_path, {"ok": {}})+ before = path.read_bytes()+ original_open = builtins.open+ original_io_open = io.open++ def read_only_open(file, mode="r", *args, **kwargs):+ assert not any(flag in mode for flag in "wax+")+ return original_open(file, mode, *args, **kwargs)++ def unexpected(*args, **kwargs):+ pytest.fail("Listing must not write, fetch, import custom steps or execute")++ monkeypatch.setattr(builtins, "open", read_only_open)++ def read_only_io_open(file, mode="r", *args, **kwargs):+ assert not any(flag in mode for flag in "wax+")+ return original_io_open(file, mode, *args, **kwargs)++ monkeypatch.setattr(io, "open", read_only_io_open)+ monkeypatch.setattr(Path, "mkdir", unexpected)+ monkeypatch.setattr(Path, "write_text", unexpected)+ monkeypatch.setattr(Path, "write_bytes", unexpected)+ monkeypatch.setattr(operation.WorkflowRegistry, "save", unexpected)+ monkeypatch.setattr(http, "open_url", unexpected)+ monkeypatch.setattr(subprocess, "run", unexpected)+ monkeypatch.setattr(workflows, "load_custom_steps", unexpected)+ monkeypatch.setattr(installer, "load_installed_integrations", unexpected)+ result = operation.list_workflows(operation.WorkflowListRequest(tmp_path))+ assert len(result.items) == 1+ assert path.read_bytes() == before+ assert capsys.readouterr() == ("", "")+++def test_unreadable_registry_is_not_empty_success(tmp_path, monkeypatch):+ path = _registry(tmp_path, {})+ original = FileHelper.read_bytes++ def denied(files, file):+ if files.root / file == path:+ raise PermissionError("private registry details")+ return original(files, file)++ monkeypatch.setattr(FileHelper, "read_bytes", denied)+ with pytest.raises(operation.WorkflowListError) as exc:+ operation.list_workflows(operation.WorkflowListRequest(tmp_path))+ assert exc.value.code == "workflow_registry_read_failed"++[email protected](os.name != "nt", reason="Windows directory junction regression")[email protected]("registry_present", [False, True])+def test_list_rejects_junction_at_registry_read_boundary(+ tmp_path, monkeypatch, registry_present+):+ from typer.testing import CliRunner+ from specify_cli import app+ from specify_cli.workflows import mcp_list++ root = tmp_path / "project"+ (root / ".specify").mkdir(parents=True)+ outside = tmp_path / "outside"+ outside.mkdir()+ registry = outside / "workflow-registry.json"+ if registry_present:+ registry.write_text('{"workflows": {"outside-secret": {}}}', encoding="utf-8")+ before = registry.read_bytes() if registry_present else None+ junction = root / ".specify" / "workflows"+ created = subprocess.run(+ ["cmd", "/c", "mklink", "/J", str(junction), str(outside)],+ capture_output=True,+ text=True,+ check=False,+ )+ assert created.returncode == 0, created.stderr+ assert not junction.is_symlink()+ opened = []+ original_open = io.open++ def track(file, *args, **kwargs):+ if Path(file).name == "workflow-registry.json":+ opened.append(file)+ return original_open(file, *args, **kwargs)++ monkeypatch.setattr(io, "open", track)+ with pytest.raises(operation.WorkflowListError) as error:+ operation.list_workflows(operation.WorkflowListRequest(root))+ assert error.value.code == "workflow_registry_read_failed"+ response = mcp_list.create_workflow_list_tool(launch_directory=root)()+ assert response.is_error is True+ assert (+ response.structured_content["error"]["code"] == "workflow_registry_read_failed"+ )+ monkeypatch.setenv("SPECIFY_INIT_DIR", str(root))+ cli = CliRunner().invoke(app, ["workflow", "list"])+ assert cli.exit_code == 1+ assert "Failed to read workflow registry" in cli.output+ assert "outside-secret" not in cli.output+ assert opened == []+ monkeypatch.setattr(io, "open", original_open)+ if registry_present:+ assert registry.read_bytes() == before+ else:+ assert not registry.exists()+++def test_unexpected_symlink_setup_errors_are_not_skipped(tmp_path, monkeypatch):+ def missing_parent(*args, **kwargs):+ raise FileNotFoundError(errno.ENOENT, "unexpected fixture setup failure")++ monkeypatch.setattr(Path, "symlink_to", missing_parent)+ with pytest.raises(FileNotFoundError, match="unexpected fixture setup failure"):+ test_symlinked_storage_is_rejected(tmp_path, ".specify/workflows")+++def test_policy_reader_preserves_legacy_json_error_offsets(tmp_path):+ path = _registry(tmp_path, {})+ path.write_bytes(b'{\r\n "workflows":\r\n broken\r\n}')+ with pytest.raises(OSError) as legacy:+ operation.WorkflowRegistry(tmp_path)+ with pytest.raises(operation.WorkflowListError) as current:+ operation.list_workflows(operation.WorkflowListRequest(tmp_path))+ assert str(current.value) == f"Failed to read workflow registry: {legacy.value}"