From 654ab78280105c556927ced3101bb81076b0840c Mon Sep 17 00:00:00 2001 From: franciscogdeveloper Date: Wed, 4 Nov 2026 17:06:46 -0300 Subject: [PATCH 1/2] feat(workflows): expose workflow catalog sources through MCP Add a typed, read-only workflow.catalog.list operation shared by the CLI and a new specify_workflow_catalog_list MCP tool, and mark only this command as available in the workflow inventory. The MCP result removes userinfo, query strings and fragments from catalog URLs, because they can carry credentials, and its errors never quote configured values. The CLI keeps printing URLs as configured. Reading through the shared operation means the CLI now also rejects unsafe workflow storage and a symlinked project catalog config unless the project policy allows symlinks, matching workflow list. Refs #4913 Assisted-by: Claude Code (model: Claude Opus 5.5, autonomous) Co-Authored-By: Claude Opus 5.5 --- docs/overview/core.md | 7 +- docs/overview/mcp.md | 29 ++ src/specify_cli/workflows/_mcp.py | 38 +- src/specify_cli/workflows/catalog/_domain.py | 24 +- .../workflows/catalog/_operation_list.py | 122 ++++++ .../workflows/catalog/command_list.py | 26 +- src/specify_cli/workflows/catalog/mcp_list.py | 208 ++++++++++ tests/specify_cli/mcp_server/test_server.py | 1 + tests/specify_cli/mcp_server/test_stdio.py | 16 + .../workflows/catalog/test_command_list.py | 48 +++ .../workflows/catalog/test_mcp_list.py | 383 ++++++++++++++++++ .../workflows/catalog/test_operation_list.py | 256 ++++++++++++ tests/specify_cli/workflows/test_mcp.py | 45 +- tests/specify_cli/workflows/test_mcp_list.py | 8 +- 14 files changed, 1162 insertions(+), 49 deletions(-) create mode 100644 src/specify_cli/workflows/catalog/_operation_list.py create mode 100644 src/specify_cli/workflows/catalog/mcp_list.py create mode 100644 tests/specify_cli/workflows/catalog/test_mcp_list.py create mode 100644 tests/specify_cli/workflows/catalog/test_operation_list.py diff --git a/docs/overview/core.md b/docs/overview/core.md index b2f2222cc9..2e466c948d 100644 --- a/docs/overview/core.md +++ b/docs/overview/core.md @@ -175,7 +175,8 @@ specify mcp Starts the experimental stdio-only MCP server. Its first-class read-only tools expose version information (`specify_version`), artifact inventory and composition -(`specify_artifact_list`, `specify_artifact_info`), and installed workflows -(`specify_workflow_list`). The generic list, describe, and run tools support only -the stable `version` JSON command. See the [MCP Server reference](mcp.md) for the +(`specify_artifact_list`, `specify_artifact_info`), installed workflows +(`specify_workflow_list`), and workflow catalog sources +(`specify_workflow_catalog_list`). The generic list, describe, and run tools +support only the stable `version` JSON command. See the [MCP Server reference](mcp.md) for the tool names, result contracts, and current limitations. diff --git a/docs/overview/mcp.md b/docs/overview/mcp.md index ddf1efa75d..068445c821 100644 --- a/docs/overview/mcp.md +++ b/docs/overview/mcp.md @@ -26,6 +26,7 @@ read-only, local-only (no network access), and reject unexpected 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 | +| `specify_workflow_catalog_list` | List active workflow catalog sources in priority order | The artifact tools take an optional absolute `project_directory`; it defaults to the directory the server was launched from. @@ -93,6 +94,34 @@ 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. +## Workflow catalog list + +`specify_workflow_catalog_list` accepts an optional absolute +`project_directory` (default: the server launch directory) and `limit` (1–1000, +default 100). It resolves the same catalog stack as +`specify workflow catalog list`: the `SPECKIT_WORKFLOW_CATALOG_URL` override, the +project's `.specify/workflow-catalogs.yml`, the user's +`~/.specify/workflow-catalogs.yml`, then the built-in defaults. The override and +the user config come from the server process, not the selected project. The tool +never fetches catalogs or writes caches. + +The result has `items` in priority order and a `truncated` boolean. Each item has +`name`, `url`, `priority`, `install_allowed`, and nullable `description`. +`truncated: true` indicates omitted sources; increase `limit` to retrieve more, up +to 1000. There is no continuation cursor. + +Returned URLs contain only the scheme, host, port, and path. Userinfo, query +strings, and fragments are removed because they can carry credentials, so a +returned URL may not be fetchable as is, and a secret placed in the URL path is +not detected. The CLI still prints URLs as configured. + +Expected errors are `invalid_project_directory`, `not_a_spec_kit_project`, +`unsafe_workflow_storage` (including a symlinked project catalog config), and +`invalid_catalog_config`. Error messages never quote configured values. +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. + ## Input validation errors The first-class tools validate arguments against their input schema before diff --git a/src/specify_cli/workflows/_mcp.py b/src/specify_cli/workflows/_mcp.py index a6b6278393..cc4d8c4aa4 100644 --- a/src/specify_cli/workflows/_mcp.py +++ b/src/specify_cli/workflows/_mcp.py @@ -1,7 +1,8 @@ """Explicit MCP dispositions for the complete ``specify workflow`` hierarchy. -Only workflow.list has a shared operation and adapter. Unavailable records -describe the conservative union of CLI paths, not a future MCP contract. +Only workflow.list and workflow.catalog.list have 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: @@ -29,6 +30,8 @@ from mcp.server import MCPServer from ._operation_list import WORKFLOW_LIST_OPERATION +from .catalog._operation_list import WORKFLOW_CATALOG_LIST_OPERATION +from .catalog.mcp_list import register as register_catalog_list from .mcp_list import register as register_list WorkflowDisposition = Literal["available", "unavailable", "excluded"] @@ -218,12 +221,11 @@ class WorkflowToolInventory: operation_id="workflow.catalog.list", cli_path="specify workflow catalog list", mcp_tool_name="specify_workflow_catalog_list", - disposition_reason=( - "WorkflowCatalog.get_catalog_configs returns dictionaries rendered by the " - "CLI; no shared typed catalog-list outcome or MCP adapter." - ), - capabilities=_LOCAL_READ, - network_access="none", + disposition_reason=None, + disposition="available", + contract_version=WORKFLOW_CATALOG_LIST_OPERATION.contract_version, + capabilities=WORKFLOW_CATALOG_LIST_OPERATION.capabilities, + network_access=WORKFLOW_CATALOG_LIST_OPERATION.network_access, ), WorkflowToolInventory( operation_id="workflow.catalog.remove", @@ -395,11 +397,15 @@ class WorkflowToolInventory: 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 - ) + """Register the available workflow operations from their owning hierarchy.""" + adapters = { + "workflow.list": register_list, + "workflow.catalog.list": register_catalog_list, + } + for record in WORKFLOW_TOOLS: + if record.disposition == "available": + adapters[record.operation_id]( + server, + launch_directory=launch_directory, + tool_name=record.mcp_tool_name, + ) diff --git a/src/specify_cli/workflows/catalog/_domain.py b/src/specify_cli/workflows/catalog/_domain.py index 4aaf82532a..26a08ad60a 100644 --- a/src/specify_cli/workflows/catalog/_domain.py +++ b/src/specify_cli/workflows/catalog/_domain.py @@ -321,10 +321,15 @@ class WorkflowCatalog: ) CACHE_DURATION = 3600 # 1 hour - def __init__(self, project_root: Path) -> None: + def __init__( + self, project_root: Path, *, read_files: FileHelper | None = None + ) -> None: self.project_root = project_root self.workflows_dir = project_root / ".specify" / "workflows" self.cache_dir = self.workflows_dir / ".cache" + # Optional read-policy handoff for workflow.catalog.list. Existing callers + # and all mutation paths retain their established behavior. + self._read_files = read_files # -- Catalog resolution ----------------------------------------------- @@ -360,13 +365,20 @@ def _validate_catalog_url(self, url: str) -> None: ) def _load_catalog_config( - self, config_path: Path + self, config_path: Path, *, read_files: FileHelper | None = None ) -> list[WorkflowCatalogEntry] | None: """Load catalog stack configuration from a YAML file.""" - if not config_path.exists(): + if read_files is None and not config_path.exists(): return None try: - data = yaml.safe_load(config_path.read_text(encoding="utf-8")) + if read_files is None: + text = config_path.read_text(encoding="utf-8") + else: + try: + text = read_files.read_text(config_path) + except FileNotFoundError: + return None + data = yaml.safe_load(text) except (yaml.YAMLError, OSError, UnicodeError) as exc: raise WorkflowValidationError( f"Failed to read catalog config {config_path}: {exc}" @@ -492,7 +504,9 @@ def get_active_catalogs(self) -> list[WorkflowCatalogEntry]: # 2. Project-level config project_config = self.project_root / ".specify" / "workflow-catalogs.yml" - project_entries = self._load_catalog_config(project_config) + project_entries = self._load_catalog_config( + project_config, read_files=self._read_files + ) if project_entries is not None: return project_entries diff --git a/src/specify_cli/workflows/catalog/_operation_list.py b/src/specify_cli/workflows/catalog/_operation_list.py new file mode 100644 index 0000000000..c52be36d0d --- /dev/null +++ b/src/specify_cli/workflows/catalog/_operation_list.py @@ -0,0 +1,122 @@ +"""Shared, read-only application operation for configured workflow catalogs.""" + +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path +import stat +from typing import Literal + +from ..._file_policy import ProjectPolicyError, project_files +from ...file_helper import FileHelperError +from .._storage import WorkflowStorageError, validate_workflow_storage +from ._domain import WorkflowCatalog, WorkflowCatalogError + +WORKFLOW_CATALOG_LIST_MAX_LIMIT = 1000 + + +@dataclass(frozen=True) +class WorkflowCatalogListRequest: + project_directory: Path + # CLI retains its complete listing. MCP supplies an explicit bounded limit. + limit: int | None = None + + +@dataclass(frozen=True) +class WorkflowCatalogSource: + name: str + # Exactly as configured, so adapters decide what they may disclose. + url: str + priority: int + install_allowed: bool + description: str | None + + +@dataclass(frozen=True) +class WorkflowCatalogListResult: + items: tuple[WorkflowCatalogSource, ...] + truncated: bool = False + + +class WorkflowCatalogListError(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 WorkflowCatalogListOperationDescriptor: + operation_id: Literal["workflow.catalog.list"] + contract_version: Literal["1"] + request_type: type[WorkflowCatalogListRequest] + result_type: type[WorkflowCatalogListResult] + error_types: tuple[type[WorkflowCatalogListError], ...] + capabilities: frozenset[Literal["local-read"]] + network_access: Literal["none"] + + +WORKFLOW_CATALOG_LIST_OPERATION = WorkflowCatalogListOperationDescriptor( + operation_id="workflow.catalog.list", + contract_version="1", + request_type=WorkflowCatalogListRequest, + result_type=WorkflowCatalogListResult, + error_types=(WorkflowCatalogListError,), + capabilities=frozenset({"local-read"}), + network_access="none", +) + + +def list_catalog_sources( + request: WorkflowCatalogListRequest, +) -> WorkflowCatalogListResult: + """Resolve the active catalog stack without fetching or caching catalogs.""" + root = request.project_directory + if not isinstance(root, Path) or not root.is_absolute(): + raise WorkflowCatalogListError( + "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_CATALOG_LIST_MAX_LIMIT + ): + raise WorkflowCatalogListError( + "invalid_limit", + f"limit must be between 1 and {WORKFLOW_CATALOG_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 or not (root / ".specify").is_dir(): + raise WorkflowCatalogListError( + "not_a_spec_kit_project", + "Not a Spec Kit project (no .specify/ directory)", + ) + files = project_files(root) + validate_workflow_storage(root) + configs = WorkflowCatalog(root, read_files=files).get_catalog_configs() + except (ProjectPolicyError, WorkflowStorageError, FileHelperError, OSError) as exc: + raise WorkflowCatalogListError("unsafe_workflow_storage", str(exc)) from exc + except WorkflowCatalogError as exc: + raise WorkflowCatalogListError("invalid_catalog_config", str(exc)) from exc + + selected = configs if limit is None else configs[:limit] + return WorkflowCatalogListResult( + items=tuple( + WorkflowCatalogSource( + name=config["name"], + url=config["url"], + priority=config["priority"], + install_allowed=config["install_allowed"], + description=config["description"] or None, + ) + for config in selected + ), + truncated=limit is not None and len(configs) > limit, + ) diff --git a/src/specify_cli/workflows/catalog/command_list.py b/src/specify_cli/workflows/catalog/command_list.py index d3084739e2..2ca060dda4 100644 --- a/src/specify_cli/workflows/catalog/command_list.py +++ b/src/specify_cli/workflows/catalog/command_list.py @@ -3,36 +3,36 @@ from __future__ import annotations from .. import _commands as cli +from . import _operation_list as operation from . import catalog_app @catalog_app.command("list") def workflow_catalog_list(): """List configured workflow catalog sources.""" - from . import WorkflowCatalog, WorkflowCatalogError - project_root = cli._require_specify_project() - catalog = WorkflowCatalog(project_root) try: - configs = catalog.get_catalog_configs() - except WorkflowCatalogError as exc: - cli.console.print(f"[red]Error:[/red] {exc}") - raise cli.typer.Exit(1) + result = operation.list_catalog_sources( + operation.WorkflowCatalogListRequest(project_root) + ) + except operation.WorkflowCatalogListError as exc: + cli.console.print(f"[red]Error:[/red] {cli._escape_markup(str(exc))}") + raise cli.typer.Exit(1) from exc cli.console.print("\n[bold cyan]Workflow Catalog Sources:[/bold cyan]\n") - for i, cfg in enumerate(configs): + for i, source in enumerate(result.items): install_status = ( "[green]install allowed[/green]" - if cfg["install_allowed"] + if source.install_allowed else "[yellow]discovery only[/yellow]" ) cli.console.print( - f" [{i}] [bold]{cli._escape_markup(str(cfg['name']))}[/bold] — {install_status}" + f" [{i}] [bold]{cli._escape_markup(str(source.name))}[/bold] — {install_status}" ) - cli.console.print(f" {cli._escape_markup(str(cfg['url']))}") - if cfg.get("description"): + cli.console.print(f" {cli._escape_markup(str(source.url))}") + if source.description: cli.console.print( - f" [dim]{cli._escape_markup(str(cfg['description']))}[/dim]" + f" [dim]{cli._escape_markup(str(source.description))}[/dim]" ) cli.console.print() diff --git a/src/specify_cli/workflows/catalog/mcp_list.py b/src/specify_cli/workflows/catalog/mcp_list.py new file mode 100644 index 0000000000..582d540dd9 --- /dev/null +++ b/src/specify_cli/workflows/catalog/mcp_list.py @@ -0,0 +1,208 @@ +"""Strict MCP projection of the shared workflow catalog list operation.""" + +from __future__ import annotations + +import logging +from collections.abc import Callable +from pathlib import Path +from typing import Annotated +from urllib.parse import urlsplit, urlunsplit + +from mcp.server import MCPServer +from mcp.types import CallToolResult, TextContent, ToolAnnotations +from pydantic import BaseModel, ConfigDict, Field + +from ..mcp_list import _lookup_registered_tool, _tool_error, _wire_response_size +from . import _operation_list as operation + +logger = logging.getLogger(__name__) +_MAX_WIRE_RESPONSE_BYTES = 1024 * 1024 +WorkflowCatalogListLimit = Annotated[ + int, Field(strict=True, ge=1, le=operation.WORKFLOW_CATALOG_LIST_MAX_LIMIT) +] +WorkflowCatalogProjectDirectory = Annotated[str, Field(strict=True)] + + +class WorkflowCatalogListToolInput(BaseModel): + model_config = ConfigDict(extra="forbid", strict=True) + project_directory: WorkflowCatalogProjectDirectory | None = None + limit: WorkflowCatalogListLimit = 100 + + +class WorkflowCatalogSourceResult(BaseModel): + model_config = ConfigDict(extra="forbid", strict=True) + name: str + url: str + priority: int + install_allowed: bool + description: str | None + + +class WorkflowCatalogListToolResult(BaseModel): + model_config = ConfigDict(extra="forbid", strict=True) + items: list[WorkflowCatalogSourceResult] = Field( + max_length=operation.WORKFLOW_CATALOG_LIST_MAX_LIMIT + ) + truncated: bool + + +WorkflowCatalogListCallResult = Annotated[CallToolResult, WorkflowCatalogListToolResult] +WorkflowCatalogListTool = Callable[[str | None, int], CallToolResult] + + +class _InvalidOperationResult(Exception): + """The shared outcome does not match the declared result contract.""" + + +def _disclosable_url(url: str) -> str: + """Drop the URL parts that can carry credentials before leaving the process.""" + parts = urlsplit(url) + host = parts.netloc.rpartition("@")[2] + return urlunsplit((parts.scheme, host, parts.path, "", "")) + + +def _convert_result( + result: operation.WorkflowCatalogListResult, + *, + requested_limit: int, +) -> WorkflowCatalogListToolResult: + try: + if not isinstance(result, operation.WorkflowCatalogListResult): + raise TypeError("Expected WorkflowCatalogListResult") + 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 WorkflowCatalogListToolResult.model_validate( + { + "items": [ + { + "name": item.name, + "url": _disclosable_url(item.url), + "priority": item.priority, + "install_allowed": item.install_allowed, + "description": item.description, + } + for item in result.items + ], + "truncated": result.truncated, + }, + strict=True, + ) + except (TypeError, ValueError, AttributeError) as exc: + raise _InvalidOperationResult from exc + + +def _response_too_large() -> CallToolResult: + return _tool_error( + "response_too_large", + "Workflow catalog list response exceeds the byte limit; retry with a smaller limit.", + retryable=True, + ) + + +def create_workflow_catalog_list_tool( + *, + launch_directory: Path, + max_wire_response_bytes: int = _MAX_WIRE_RESPONSE_BYTES, +) -> WorkflowCatalogListTool: + """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_catalog_list( + project_directory: WorkflowCatalogProjectDirectory | None = None, + limit: WorkflowCatalogListLimit = 100, + ) -> WorkflowCatalogListCallResult: + """List active workflow catalog sources in priority order.""" + tool_input = WorkflowCatalogListToolInput.model_validate( + {"project_directory": project_directory, "limit": limit}, strict=True + ) + try: + result = operation.list_catalog_sources( + operation.WorkflowCatalogListRequest( + 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.WorkflowCatalogListError as exc: + # Config errors can quote a configured URL, including its credentials. + # 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.", + "invalid_catalog_config": "The workflow catalog configuration is invalid.", + "invalid_limit": "The workflow catalog list limit is invalid.", + } + response = _tool_error( + exc.code, messages.get(exc.code, "Unable to list workflow catalogs.") + ) + except _InvalidOperationResult: + response = _tool_error( + "invalid_operation_result", + "The workflow catalog list result is invalid.", + ) + except Exception: + logger.exception( + "Unexpected failure in the workflow catalog list MCP adapter." + ) + response = _tool_error( + "internal_error", "Unable to list workflow catalogs." + ) + if _wire_response_size(response) > max_wire_response_bytes: + return _response_too_large() + return response + + return specify_workflow_catalog_list + + +def register( + server: MCPServer, + *, + launch_directory: Path, + tool_name: str = "specify_workflow_catalog_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_catalog_list_tool(launch_directory=launch_directory), + name=tool_name, + description=( + "List active workflow catalog sources in priority order without fetching them. " + "URLs omit userinfo, query strings and fragments. " + "limit bounds the sources returned; truncated reports omitted sources." + ), + 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 catalog list arguments" + ) from exc diff --git a/tests/specify_cli/mcp_server/test_server.py b/tests/specify_cli/mcp_server/test_server.py index a0998fce2b..84f95240e1 100644 --- a/tests/specify_cli/mcp_server/test_server.py +++ b/tests/specify_cli/mcp_server/test_server.py @@ -34,6 +34,7 @@ def test_tool_discovery_exposes_first_class_and_transitional_tools(tmp_path): "specify_artifact_list", "specify_artifact_info", "specify_workflow_list", + "specify_workflow_catalog_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.py index bd1553bccc..3c52cd78a3 100644 --- a/tests/specify_cli/mcp_server/test_stdio.py +++ b/tests/specify_cli/mcp_server/test_stdio.py @@ -42,6 +42,14 @@ async def exercise() -> None: workflow_failure = await session.call_tool( "specify_workflow_list", {"project_directory": "relative"} ) + catalogs = await session.call_tool( + "specify_workflow_catalog_list", + {"project_directory": str(tmp_path)}, + ) + catalog_failure = await session.call_tool( + "specify_workflow_catalog_list", + {"project_directory": "relative"}, + ) artifacts = await session.call_tool("specify_artifact_list", {}) artifact = await session.call_tool( "specify_artifact_info", @@ -74,6 +82,7 @@ async def exercise() -> None: "specify_artifact_list", "specify_artifact_info", "specify_workflow_list", + "specify_workflow_catalog_list", ] assert listed.structured_content["commands"][0]["command"] == "version" assert set(version.structured_content) == { @@ -90,6 +99,13 @@ async def exercise() -> None: workflow_failure.structured_content["error"]["code"] == "invalid_project_directory" ) + assert catalogs.is_error is False + assert catalogs.structured_content["items"] + assert catalog_failure.is_error is True + assert ( + catalog_failure.structured_content["error"]["code"] + == "invalid_project_directory" + ) assert artifacts.is_error is False assert isinstance(artifacts.structured_content["rows"], list) assert artifacts.structured_content["rows"] diff --git a/tests/specify_cli/workflows/catalog/test_command_list.py b/tests/specify_cli/workflows/catalog/test_command_list.py index 4f1196f274..f6001c2063 100644 --- a/tests/specify_cli/workflows/catalog/test_command_list.py +++ b/tests/specify_cli/workflows/catalog/test_command_list.py @@ -22,6 +22,7 @@ def test_catalog_list_escapes_rich_markup(self, project_dir, monkeypatch): "url": "https://example.com/[cat].json", "description": "desc [with] brackets", "install_allowed": True, + "priority": 1, }, ] monkeypatch.setattr( @@ -35,3 +36,50 @@ def test_catalog_list_escapes_rich_markup(self, project_dir, monkeypatch): assert "Bracket [Catalog]" in result.output assert "https://example.com/[cat].json" in result.output assert "desc [with] brackets" in result.output + + def test_catalog_list_output_and_configured_urls_are_unchanged( + self, project_dir, monkeypatch + ): + """The human listing keeps its layout and prints URLs as configured.""" + from typer.testing import CliRunner + from specify_cli import app + + monkeypatch.chdir(project_dir) + monkeypatch.delenv("SPECKIT_WORKFLOW_CATALOG_URL", raising=False) + (project_dir / ".specify" / "workflow-catalogs.yml").write_text( + "catalogs:\n" + " - name: private\n" + " url: https://user:token@e.example/c.json?key=value\n" + " install_allowed: true\n" + " description: Private source\n" + " - name: public\n" + " url: https://p.example/c.json\n", + encoding="utf-8", + ) + result = CliRunner().invoke( + app, ["workflow", "catalog", "list"], env={"COLUMNS": "200"} + ) + assert result.exit_code == 0, result.output + assert [line.strip() for line in result.output.splitlines() if line.strip()] == [ + "Workflow Catalog Sources:", + "[0] private — install allowed", + "https://user:token@e.example/c.json?key=value", + "Private source", + "[1] public — discovery only", + "https://p.example/c.json", + ] + + def test_catalog_list_reports_invalid_config_and_exits_nonzero( + self, project_dir, monkeypatch + ): + from typer.testing import CliRunner + from specify_cli import app + + monkeypatch.chdir(project_dir) + monkeypatch.delenv("SPECKIT_WORKFLOW_CATALOG_URL", raising=False) + (project_dir / ".specify" / "workflow-catalogs.yml").write_text( + "catalogs: 5\n", encoding="utf-8" + ) + result = CliRunner().invoke(app, ["workflow", "catalog", "list"]) + assert result.exit_code == 1 + assert "'catalogs' must be a list" in result.output diff --git a/tests/specify_cli/workflows/catalog/test_mcp_list.py b/tests/specify_cli/workflows/catalog/test_mcp_list.py new file mode 100644 index 0000000000..504914cbfa --- /dev/null +++ b/tests/specify_cli/workflows/catalog/test_mcp_list.py @@ -0,0 +1,383 @@ +"""Strict schemas, dispatch, URL disclosure and bounds for workflow.catalog.list.""" + +import asyncio +import json +from concurrent.futures import ThreadPoolExecutor +from pathlib import Path + +import anyio +import pytest +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.catalog import _operation_list as operation +from specify_cli.workflows.catalog import mcp_list + +TOOL = "specify_workflow_catalog_list" + + +@pytest.fixture(autouse=True) +def isolated_layers(tmp_path, monkeypatch): + monkeypatch.delenv("SPECKIT_WORKFLOW_CATALOG_URL", raising=False) + home = tmp_path / "home" + home.mkdir() + monkeypatch.setattr(Path, "home", lambda: home) + + +def _run(coro): + return asyncio.run(coro) + + +def _project(root, config=None): + (root / ".specify").mkdir(parents=True) + if config is not None: + (root / ".specify" / "workflow-catalogs.yml").write_text( + config, encoding="utf-8" + ) + return root + + +def _source(name="n", url="https://e.example/c.json", priority=1): + return operation.WorkflowCatalogSource(name, url, priority, True, None) + + +def _call(root, arguments=None): + server = create_server(launch_directory=root) + return _run(server.call_tool(TOOL, arguments or {})) + + +def test_actual_discovery_schema_annotations_and_collision(tmp_path): + server = MCPServer(name="test") + mcp_list.register(server, launch_directory=tmp_path) + tools = _run(server.list_tools()) + assert [tool.name for tool in tools] == [TOOL] + tool = tools[0] + assert ( + tool.input_schema["properties"] + == mcp_list.WorkflowCatalogListToolInput.model_json_schema()["properties"] + ) + assert tool.input_schema["additionalProperties"] is False + assert set(tool.input_schema["properties"]) == {"project_directory", "limit"} + assert tool.output_schema == mcp_list.WorkflowCatalogListToolResult.model_json_schema() + assert set(tool.output_schema["required"]) == {"items", "truncated"} + assert set( + tool.output_schema["$defs"]["WorkflowCatalogSourceResult"]["properties"] + ) == {"name", "url", "priority", "install_allowed", "description"} + 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_list.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.WorkflowCatalogListResult((_source("Shared"),)) + + def collect(request): + requests.append(request) + return result + + monkeypatch.setattr(operation, "list_catalog_sources", collect) + cli = CliRunner().invoke(app, ["workflow", "catalog", "list"]) + assert cli.exit_code == 0, cli.output + assert "Shared" in cli.output + response = _call(tmp_path) + assert response.is_error is False + assert response.structured_content["items"][0]["name"] == "Shared" + assert requests == [ + operation.WorkflowCatalogListRequest(tmp_path), + operation.WorkflowCatalogListRequest(tmp_path, 100), + ] + + +def test_adapters_agree_on_real_sources_and_order(tmp_path, monkeypatch): + _project( + tmp_path, + "catalogs:\n" + " - name: second\n url: https://s.example/c.json\n priority: 2\n" + " - name: first\n url: https://f.example/c.json\n priority: 1\n", + ) + monkeypatch.setenv("SPECIFY_INIT_DIR", str(tmp_path)) + cli = CliRunner().invoke(app, ["workflow", "catalog", "list"]) + assert cli.exit_code == 0, cli.output + names = [item["name"] for item in _call(tmp_path).structured_content["items"]] + assert names == ["first", "second"] + assert cli.output.index("first") < cli.output.index("second") + + +@pytest.mark.parametrize( + "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_catalog_sources", lambda *a: pytest.fail("Unexpected dispatch") + ) + with pytest.raises(ToolError): + _call(tmp_path, arguments) + + +@pytest.mark.parametrize( + "configured,disclosed", + [ + ("https://e.example/c.json", "https://e.example/c.json"), + ("https://e.example:8443/a/c.json", "https://e.example:8443/a/c.json"), + ("https://user:s3cret@e.example/c.json", "https://e.example/c.json"), + ("https://s3cret@e.example:8443/c.json", "https://e.example:8443/c.json"), + ("https://e.example/c.json?token=s3cret", "https://e.example/c.json"), + ("https://e.example/c.json#s3cret", "https://e.example/c.json"), + ("https://u:s3cret@e.example/c.json?k=s3cret#s3cret", "https://e.example/c.json"), + ("http://user:s3cret@localhost:9/c.json", "http://localhost:9/c.json"), + ("https://user:s3cret@[::1]:9/c.json", "https://[::1]:9/c.json"), + ], +) +def test_credential_bearing_url_parts_never_reach_the_client( + tmp_path, configured, disclosed +): + _project(tmp_path, f'catalogs:\n - name: c\n url: "{configured}"\n') + response = _call(tmp_path) + assert response.is_error is False + assert response.structured_content["items"][0]["url"] == disclosed + assert "s3cret" not in response.model_dump_json() + assert json.loads(response.content[0].text) == response.structured_content + + +def test_environment_override_url_is_also_stripped(tmp_path, monkeypatch): + _project(tmp_path) + monkeypatch.setenv( + "SPECKIT_WORKFLOW_CATALOG_URL", "https://user:s3cret@e.example/c.json" + ) + response = _call(tmp_path) + assert response.structured_content["items"][0]["url"] == "https://e.example/c.json" + assert "s3cret" not in response.model_dump_json() + + +@pytest.mark.parametrize( + "config", + [ + 'catalogs:\n - name: c\n url: "https://user:s3cret@[::1"\n', + 'catalogs:\n - name: c\n url: "ftp://user:s3cret@e.example/c.json"\n', + 'catalogs:\n - name: s3cret\n url: https://e.example/c\n priority: high\n', + ], +) +def test_config_errors_do_not_quote_configured_values(tmp_path, config): + _project(tmp_path, config) + response = _call(tmp_path) + assert response.is_error is True + assert response.structured_content["error"]["code"] == "invalid_catalog_config" + assert "s3cret" not in response.model_dump_json() + assert str(tmp_path) not in response.model_dump_json() + + +@pytest.mark.parametrize("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") + response = _call(tmp_path, {"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() + + +@pytest.mark.parametrize("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: + (root / ".specify" / "workflows").write_text("not a dir", encoding="utf-8") + response = _call(tmp_path, {"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 +): + def config(name): + return f"catalogs:\n - name: {name}\n url: https://{name}.example/c.json\n" + + first = _project(tmp_path / "first", config("one")) + second = _project(tmp_path / "second", config("two")) + tool = mcp_list.create_workflow_catalog_list_tool(launch_directory=first) + monkeypatch.chdir(second) + monkeypatch.setenv("SPECIFY_INIT_DIR", str(second)) + assert tool().structured_content["items"][0]["name"] == "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]["name"] for r in results] == ["one", "two"] + assert Path.cwd() == second + relative = tool("relative", 100) + assert relative.structured_content["error"]["code"] == "invalid_project_directory" + + +@pytest.mark.parametrize( + "error,code", + [ + ( + operation.WorkflowCatalogListError( + "invalid_catalog_config", "s3cret /private/path" + ), + "invalid_catalog_config", + ), + (RuntimeError("s3cret /private/path"), "internal_error"), + (TypeError("s3cret /private/path"), "internal_error"), + ], +) +def test_error_mapping_never_exposes_exception_details( + tmp_path, monkeypatch, error, code +): + def fail(request): + raise error + + monkeypatch.setattr(operation, "list_catalog_sources", fail) + response = mcp_list.create_workflow_catalog_list_tool(launch_directory=tmp_path)() + assert response.is_error is True + assert response.structured_content["error"]["code"] == code + assert "s3cret" not in response.model_dump_json() + assert "/private/path" not in response.model_dump_json() + + +@pytest.mark.parametrize( + "result", + [ + None, + {"items": []}, + operation.WorkflowCatalogListResult(("bad",)), + operation.WorkflowCatalogListResult((_source(priority="1"),)), + operation.WorkflowCatalogListResult((_source(url="https://[::1"),)), + ], +) +def test_invalid_operation_outcomes_are_rejected(tmp_path, monkeypatch, result): + monkeypatch.setattr(operation, "list_catalog_sources", lambda request: result) + response = mcp_list.create_workflow_catalog_list_tool(launch_directory=tmp_path)() + assert response.is_error is True + assert response.structured_content["error"]["code"] == "invalid_operation_result" + + +@pytest.mark.parametrize( + "limit,count,truncated", + [(1, 2, False), (100, 101, True), (100, 0, True), (100, 99, True)], +) +def test_operation_result_must_obey_requested_limit_and_truncation( + tmp_path, monkeypatch, limit, count, truncated +): + items = tuple(_source(str(i)) for i in range(count)) + monkeypatch.setattr( + operation, + "list_catalog_sources", + lambda request: operation.WorkflowCatalogListResult(items, truncated), + ) + response = mcp_list.create_workflow_catalog_list_tool(launch_directory=tmp_path)( + None, limit + ) + assert response.structured_content["error"]["code"] == "invalid_operation_result" + + +def test_real_limit_reports_omitted_sources(tmp_path): + entries = "".join( + f" - name: c{i}\n url: https://c{i}.example/c.json\n priority: {i}\n" + for i in range(3) + ) + _project(tmp_path, f"catalogs:\n{entries}") + response = _call(tmp_path, {"limit": 2}) + assert [i["name"] for i in response.structured_content["items"]] == ["c0", "c1"] + assert response.structured_content["truncated"] is True + + +def test_output_schema_enforces_ceiling_and_rejects_extras(): + row = { + "name": "n", + "url": "https://e.example/c.json", + "priority": 1, + "install_allowed": True, + "description": None, + } + schema = mcp_list.WorkflowCatalogListToolResult.model_json_schema() + assert schema["properties"]["items"]["maxItems"] == 1000 + with pytest.raises(ValidationError): + mcp_list.WorkflowCatalogListToolResult.model_validate( + {"items": [row] * 1001, "truncated": False} + ) + with pytest.raises(ValidationError): + mcp_list.WorkflowCatalogListToolResult.model_validate( + {"items": [], "truncated": False, "extra": 1} + ) + + +def test_response_byte_budget_and_constructor_bounds(tmp_path, monkeypatch): + result = operation.WorkflowCatalogListResult((_source("é" * 2000),)) + monkeypatch.setattr(operation, "list_catalog_sources", lambda request: result) + tool = mcp_list.create_workflow_catalog_list_tool( + launch_directory=tmp_path, max_wire_response_bytes=2000 + ) + response = tool() + assert response.structured_content["error"]["code"] == "response_too_large" + assert response.structured_content["error"]["retryable"] is True + assert mcp_list._wire_response_size(response) <= 2000 + with pytest.raises(ValueError, match="bounded error response"): + mcp_list.create_workflow_catalog_list_tool( + launch_directory=tmp_path, max_wire_response_bytes=10 + ) + with pytest.raises(ValueError, match="absolute"): + mcp_list.create_workflow_catalog_list_tool(launch_directory=Path("relative")) + + +def test_in_memory_protocol_success_expected_error_and_schema_error(tmp_path): + _project( + tmp_path, + "catalogs:\n - name: c\n url: https://user:s3cret@e.example/c.json\n", + ) + + 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(TOOL, {}) + error = await session.call_tool( + TOOL, {"project_directory": "relative"} + ) + invalid = await session.call_tool(TOOL, {"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]["url"] == "https://e.example/c.json" + assert "s3cret" not in success.model_dump_json() + 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 None diff --git a/tests/specify_cli/workflows/catalog/test_operation_list.py b/tests/specify_cli/workflows/catalog/test_operation_list.py new file mode 100644 index 0000000000..d260c4fb3e --- /dev/null +++ b/tests/specify_cli/workflows/catalog/test_operation_list.py @@ -0,0 +1,256 @@ +"""Transport-neutral workflow catalog list contract and effect boundaries.""" + +import errno +import socket +from dataclasses import FrozenInstanceError +from pathlib import Path + +import pytest + +from specify_cli.file_helper import FileHelper, SymlinkDeniedError +from specify_cli.workflows.catalog import WorkflowCatalog +from specify_cli.workflows.catalog import _operation_list as operation + + +@pytest.fixture(autouse=True) +def isolated_layers(tmp_path, monkeypatch): + """Keep the environment and the real user config out of the catalog stack.""" + monkeypatch.delenv("SPECKIT_WORKFLOW_CATALOG_URL", raising=False) + home = tmp_path / "home" + home.mkdir() + monkeypatch.setattr(Path, "home", lambda: home) + return home + + +def _project(tmp_path, config=None): + root = tmp_path / "project" + (root / ".specify").mkdir(parents=True) + if config is not None: + (root / ".specify" / "workflow-catalogs.yml").write_text( + config, encoding="utf-8" + ) + return root + + +def _list(root, limit=None): + return operation.list_catalog_sources( + operation.WorkflowCatalogListRequest(root, limit) + ) + + +def _tree(root): + return sorted(str(path.relative_to(root)) for path in root.rglob("*")) + + +def test_builtin_defaults_when_nothing_is_configured(tmp_path): + result = _list(_project(tmp_path)) + assert [item.name for item in result.items] == ["default", "community"] + assert [item.priority for item in result.items] == [1, 2] + assert [item.install_allowed for item in result.items] == [True, False] + assert result.truncated is False + with pytest.raises(FrozenInstanceError): + result.truncated = True + + +def test_project_config_is_ordered_and_normalized(tmp_path): + root = _project( + tmp_path, + "catalogs:\n" + " - name: second\n" + " url: https://second.example/catalog.json\n" + " priority: 20\n" + " - name: first\n" + " url: https://first.example/catalog.json\n" + " priority: 10\n" + " install_allowed: true\n" + " description: First source\n", + ) + assert _list(root).items == ( + operation.WorkflowCatalogSource( + "first", "https://first.example/catalog.json", 10, True, "First source" + ), + operation.WorkflowCatalogSource( + "second", "https://second.example/catalog.json", 20, False, None + ), + ) + + +def test_operation_keeps_the_configured_url_for_adapters_to_project(tmp_path): + url = "https://user:token@host.example/catalog.json?key=value" + root = _project(tmp_path, f"catalogs:\n - name: private\n url: {url}\n") + assert _list(root).items[0].url == url + + +def test_environment_override_takes_precedence(tmp_path, monkeypatch): + root = _project( + tmp_path, "catalogs:\n - name: project\n url: https://p.example/c.json\n" + ) + monkeypatch.setenv("SPECKIT_WORKFLOW_CATALOG_URL", "https://env.example/c.json") + assert [item.name for item in _list(root).items] == ["env-override"] + + +def test_user_config_applies_when_project_has_none(tmp_path, isolated_layers): + (isolated_layers / ".specify").mkdir() + (isolated_layers / ".specify" / "workflow-catalogs.yml").write_text( + "catalogs:\n - name: user\n url: https://user.example/c.json\n", + encoding="utf-8", + ) + assert [item.name for item in _list(_project(tmp_path)).items] == ["user"] + + +@pytest.mark.parametrize( + "limit,names,truncated", + [ + (1, ["default"], True), + (2, ["default", "community"], False), + (1000, ["default", "community"], False), + (None, ["default", "community"], False), + ], +) +def test_limit_bounds_sources_and_reports_truncation( + tmp_path, limit, names, truncated +): + result = _list(_project(tmp_path), limit) + assert [item.name for item in result.items] == names + assert result.truncated is truncated + + +@pytest.mark.parametrize("limit", [0, -1, 1001, True, 1.5, "1"]) +def test_invalid_limit_is_rejected(tmp_path, limit): + with pytest.raises(operation.WorkflowCatalogListError) as exc: + _list(_project(tmp_path), limit) + assert exc.value.code == "invalid_limit" + + +def test_relative_project_directory_is_rejected(): + with pytest.raises(operation.WorkflowCatalogListError) as exc: + _list(Path("relative")) + assert exc.value.code == "invalid_project_directory" + + +@pytest.mark.parametrize("kind", ["missing", "file", "no-specify", "nul"]) +def test_non_project_roots_are_rejected(tmp_path, kind): + root = tmp_path / "candidate" + if kind == "file": + root.write_text("not a directory", encoding="utf-8") + elif kind == "no-specify": + root.mkdir() + elif kind == "nul": + root = tmp_path / "invalid\x00project" + with pytest.raises(operation.WorkflowCatalogListError) as exc: + _list(root) + assert exc.value.code == "not_a_spec_kit_project" + + +@pytest.mark.parametrize( + "config", + [ + "catalogs: [", + "- not\n- a mapping\n", + "catalogs: 5\n", + "catalogs:\n - name: no-url\n", + "catalogs:\n - name: plain\n url: http://example.com/c.json\n", + "catalogs:\n - name: bad\n url: https://[::1\n", + "catalogs:\n - name: p\n url: https://e.example/c\n priority: high\n", + ], +) +def test_malformed_config_fails_closed(tmp_path, config): + with pytest.raises(operation.WorkflowCatalogListError) as exc: + _list(_project(tmp_path, config)) + assert exc.value.code == "invalid_catalog_config" + + +def test_undecodable_config_fails_closed(tmp_path): + root = _project(tmp_path) + (root / ".specify" / "workflow-catalogs.yml").write_bytes(b"\xff\xfe\xff") + with pytest.raises(operation.WorkflowCatalogListError) as exc: + _list(root) + assert exc.value.code == "invalid_catalog_config" + + +def test_invalid_environment_override_fails_closed(tmp_path, monkeypatch): + monkeypatch.setenv("SPECKIT_WORKFLOW_CATALOG_URL", "http://example.com/c.json") + with pytest.raises(operation.WorkflowCatalogListError) as exc: + _list(_project(tmp_path)) + assert exc.value.code == "invalid_catalog_config" + + +@pytest.mark.parametrize("kind", ["policy", "storage"]) +def test_unsafe_project_storage_is_rejected(tmp_path, kind): + root = _project(tmp_path) + if kind == "policy": + path = root / ".specify" / "init-options.json" + path.write_text('{"allow_symlinks": "yes"}', encoding="utf-8") + else: + (root / ".specify" / "workflows").write_text("not a dir", encoding="utf-8") + with pytest.raises(operation.WorkflowCatalogListError) as exc: + _list(root) + assert exc.value.code == "unsafe_workflow_storage" + + +def test_symlinked_project_config_is_not_followed(tmp_path): + root = _project(tmp_path) + outside = tmp_path / "outside.yml" + outside.write_text( + "catalogs:\n - name: outside\n url: https://outside.example/c.json\n", + encoding="utf-8", + ) + link = root / ".specify" / "workflow-catalogs.yml" + try: + link.symlink_to(outside) + except OSError as exc: + if getattr(exc, "winerror", None) == 1314 or exc.errno in { + errno.EPERM, + errno.ENOTSUP, + }: + pytest.skip(f"Host cannot create symlinks: {exc}") + raise + with pytest.raises(operation.WorkflowCatalogListError) as error: + _list(root) + assert error.value.code == "unsafe_workflow_storage" + + +def test_project_config_read_goes_through_the_file_policy(tmp_path, monkeypatch): + """Runs without symlink privileges, unlike the real-symlink test above.""" + root = _project( + tmp_path, "catalogs:\n - name: project\n url: https://p.example/c.json\n" + ) + + def deny(self, path, *, encoding="utf-8"): + raise SymlinkDeniedError(f"Denied: {path}") + + monkeypatch.setattr(FileHelper, "read_text", deny) + with pytest.raises(operation.WorkflowCatalogListError) as exc: + _list(root) + assert exc.value.code == "unsafe_workflow_storage" + + +def test_existing_catalog_callers_keep_their_read_behavior(tmp_path): + """The read-policy handoff stays opt-in for mutation paths and other callers.""" + root = _project( + tmp_path, "catalogs:\n - name: project\n url: https://p.example/c.json\n" + ) + configs = WorkflowCatalog(root).get_catalog_configs() + assert [config["name"] for config in configs] == ["project"] + + +def test_no_network_access_or_filesystem_writes(tmp_path, monkeypatch): + root = _project( + tmp_path, "catalogs:\n - name: project\n url: https://p.example/c.json\n" + ) + before = _tree(tmp_path) + + def refuse(*args, **kwargs): + raise AssertionError("workflow.catalog.list must not open a socket") + + monkeypatch.setattr(socket, "socket", refuse) + assert _list(root).items[0].name == "project" + assert _tree(tmp_path) == before + + +def test_descriptor_declares_read_only_local_effects(): + descriptor = operation.WORKFLOW_CATALOG_LIST_OPERATION + assert descriptor.operation_id == "workflow.catalog.list" + assert descriptor.capabilities == frozenset({"local-read"}) + assert descriptor.network_access == "none" + assert descriptor.result_type is operation.WorkflowCatalogListResult diff --git a/tests/specify_cli/workflows/test_mcp.py b/tests/specify_cli/workflows/test_mcp.py index 3136ba89c6..9bec632d5c 100644 --- a/tests/specify_cli/workflows/test_mcp.py +++ b/tests/specify_cli/workflows/test_mcp.py @@ -27,9 +27,30 @@ from specify_cli.mcp_server.server import create_server from specify_cli.workflows import _commands, _mcp from specify_cli.workflows._operation_list import WORKFLOW_LIST_OPERATION +from specify_cli.workflows.catalog._operation_list import ( + WORKFLOW_CATALOG_LIST_OPERATION, +) +from specify_cli.workflows.catalog.mcp_list import ( + WorkflowCatalogListToolInput, + WorkflowCatalogListToolResult, +) from specify_cli.workflows.mcp_list import WorkflowListToolInput, WorkflowListToolResult from specify_cli.workflows.step import catalog as step_catalog +# Implemented operations and the contract evidence each inventory record must match. +_IMPLEMENTED_CONTRACTS = { + WORKFLOW_LIST_OPERATION.operation_id: ( + WORKFLOW_LIST_OPERATION, + WorkflowListToolInput, + WorkflowListToolResult, + ), + WORKFLOW_CATALOG_LIST_OPERATION.operation_id: ( + WORKFLOW_CATALOG_LIST_OPERATION, + WorkflowCatalogListToolInput, + WorkflowCatalogListToolResult, + ), +} + def _workflow_cli_paths() -> list[str]: """Walk the registered CLI, including future nested groups, without dispatch.""" @@ -70,7 +91,7 @@ def _assert_inventory( cli_paths: Sequence[str], tools: Sequence[Tool], ) -> None: - """Bind the one implemented contract; fail closed for all other operations.""" + """Bind the implemented contracts; 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]), @@ -123,17 +144,20 @@ def _assert_inventory( f"Available reason: {item.operation_id}" ) _assert_synthetic_discovery_shape(item, tools) - assert item.operation_id == WORKFLOW_LIST_OPERATION.operation_id, ( + assert item.operation_id in _IMPLEMENTED_CONTRACTS, ( 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 + descriptor, input_model, output_model = _IMPLEMENTED_CONTRACTS[ + item.operation_id + ] + assert item.contract_version == descriptor.contract_version + assert item.capabilities == descriptor.capabilities + assert item.network_access == descriptor.network_access tool = matching[0] - expected_input = WorkflowListToolInput.model_json_schema() + expected_input = input_model.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() + assert tool.output_schema == output_model.model_json_schema() else: assert item.contract_version is None, ( f"Nonavailable tool has contract version: {item.operation_id}" @@ -401,7 +425,9 @@ def test_uninventoried_workflow_tool_is_rejected(available_record_and_tool): _assert_inventory([], [], [tool]) -def test_server_adds_only_workflow_list_and_preserves_legacy_catalog(tmp_path): +def test_server_adds_only_available_workflow_tools_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( { @@ -409,6 +435,7 @@ def test_server_adds_only_workflow_list_and_preserves_legacy_catalog(tmp_path): "specify_artifact_list": 1, "specify_artifact_info": 1, "specify_workflow_list": 1, + "specify_workflow_catalog_list": 1, "specify_list_commands": 1, "specify_describe_command": 1, "specify_run_command": 1, @@ -423,7 +450,7 @@ def test_server_adds_only_workflow_list_and_preserves_legacy_catalog(tmp_path): item.operation_id for item in _mcp.WORKFLOW_TOOLS if item.disposition == "available" - ] == ["workflow.list"] + ] == ["workflow.list", "workflow.catalog.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.py index 44a0eda3b0..9b6852abfc 100644 --- a/tests/specify_cli/workflows/test_mcp_list.py +++ b/tests/specify_cli/workflows/test_mcp_list.py @@ -37,9 +37,11 @@ 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 + assert [tool.name for tool in tools] == [ + "specify_workflow_list", + "specify_workflow_catalog_list", + ] tool = tools[0] - assert tool.name == "specify_workflow_list" assert ( tool.input_schema["properties"] == mcp_list.WorkflowListToolInput.model_json_schema()["properties"] @@ -73,7 +75,7 @@ def test_actual_discovery_schema_annotations_and_collision(tmp_path): 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 + assert len(_run(server.list_tools())) == 2 def test_shared_operation_used_by_both_adapters(tmp_path, monkeypatch): From d0f6f53663c198df5a4aece027aa7d6cd1bf39e9 Mon Sep 17 00:00:00 2001 From: franciscogdeveloper Date: Wed, 4 Nov 2026 19:34:28 -0300 Subject: [PATCH 2/2] fix(workflows): bound catalog config YAML and address review feedback - Measure catalog configs with aliases unfolded before constructing them, covering nested aliases, merge keys, recursive aliases and deep nesting - Keep the shared invalid_catalog_config message free of configured values; the CLI keeps its local diagnostics through the exception cause - Load the project policy before classifying .specify, matching workflow.list - Declare warning_types on the workflow.catalog.list descriptor - Document the symlink policy difference between catalog list and other catalog readers, and qualify the MCP error wording - Cover contained config symlinks under both policies and tighten the file-policy and default-read tests Co-Authored-By: Claude Opus 5.5 --- docs/overview/mcp.md | 3 +- docs/workflows/catalogs.md | 2 + src/specify_cli/workflows/catalog/_domain.py | 64 +++++- .../workflows/catalog/_operation_list.py | 14 +- .../workflows/catalog/command_list.py | 5 +- src/specify_cli/workflows/catalog/mcp_list.py | 3 +- .../workflows/catalog/test_command_list.py | 19 ++ .../workflows/catalog/test_operation_list.py | 204 ++++++++++++++++-- 8 files changed, 287 insertions(+), 27 deletions(-) diff --git a/docs/overview/mcp.md b/docs/overview/mcp.md index 068445c821..c3d2a27b33 100644 --- a/docs/overview/mcp.md +++ b/docs/overview/mcp.md @@ -116,7 +116,8 @@ returned URL may not be fetchable as is, and a secret placed in the URL path is not detected. The CLI still prints URLs as configured. Expected errors are `invalid_project_directory`, `not_a_spec_kit_project`, -`unsafe_workflow_storage` (including a symlinked project catalog config), and +`unsafe_workflow_storage` (including a project catalog config symlink that the +project's `allow_symlinks` policy denies), and `invalid_catalog_config`. Error messages never quote configured values. Unexpected failures use sanitized `internal_error`; invalid operation outcomes use `invalid_operation_result`. Responses exceeding 1 MiB produce a retryable diff --git a/docs/workflows/catalogs.md b/docs/workflows/catalogs.md index 962ebbda04..ea3d10a55c 100644 --- a/docs/workflows/catalogs.md +++ b/docs/workflows/catalogs.md @@ -12,6 +12,8 @@ discovery continues using the fetched catalog. > **A project's `.specify/workflow-catalogs.yml` can point `add` and `search` at a catalog you didn't choose.** Before running a workflow from an unfamiliar project, run `specify workflow catalog list` (and `specify workflow step catalog list` for the step catalogs its steps can pull in) — a project supplying that config is not evidence its workflows or steps were vetted. Maintainers do not audit workflow code; review both `run` and `env` in its shell steps yourself, including strict steps (see [Reviewing shell execution](steps.md#reviewing-shell-execution) and [Who maintains workflows?](overview.md#who-maintains-workflows)). +`specify workflow catalog list` applies the project's symlink policy to `.specify/workflow-catalogs.yml`: it refuses a symlinked config unless `allow_symlinks` is `true` in `.specify/init-options.json`, and even then it only follows links to regular files inside the project. Other commands, including `search`, `add`, and `catalog remove`, do not apply this check and still read through the link. If `catalog list` refuses the config, it can't show the sources or the indexes `catalog remove` expects, so inspect the link and its target yourself before running those commands. + ## Discovery and trust Workflow catalogs advertise `workflow.yml` files or complete packages. Step catalogs advertise executable Python packages through individual file URLs. They are independent stacks with built-in `default` (installation allowed) and `community` (discovery-only) sources. Users must vet sources before installation and use; maintainers do not audit or endorse component code. diff --git a/src/specify_cli/workflows/catalog/_domain.py b/src/specify_cli/workflows/catalog/_domain.py index 26a08ad60a..bcebf88821 100644 --- a/src/specify_cli/workflows/catalog/_domain.py +++ b/src/specify_cli/workflows/catalog/_domain.py @@ -52,6 +52,62 @@ class WorkflowValidationError(WorkflowCatalogError): """Validation error for catalog config or workflow data.""" +# --------------------------------------------------------------------------- +# Config YAML +# --------------------------------------------------------------------------- + +# How far aliases may unfold a catalog config beyond the document's own length. +_MAX_CONFIG_ALIAS_EXPANSION = 1024 * 1024 + + +def _expanded_size(node: yaml.Node, sizes: dict[int, int], active: set[int]) -> int: + """Measure a composed node with aliases unfolded, visiting shared nodes once.""" + if isinstance(node, yaml.ScalarNode): + return len(node.value) + key = id(node) + if key in sizes: + return sizes[key] + if key in active: + raise WorkflowValidationError( + "Catalog config must not contain recursive YAML aliases." + ) + active.add(key) + if isinstance(node, yaml.MappingNode): + children = [child for pair in node.value for child in pair] + else: + children = node.value + size = 1 + sum(_expanded_size(child, sizes, active) for child in children) + active.remove(key) + sizes[key] = size + return size + + +def _safe_load_catalog_config(text: str) -> Any: + """``yaml.safe_load`` that refuses documents whose aliases unfold without bound. + + An alias shares its anchor's node, so a few hundred bytes can describe + terabytes that merge keys or a later ``str()`` would materialize. The size is + checked before anything is constructed; a document without aliases never + reaches the limit. + """ + loader = yaml.SafeLoader(text) + try: + node = loader.get_single_node() + if node is None: + return None + if _expanded_size(node, {}, set()) > len(text) + _MAX_CONFIG_ALIAS_EXPANSION: + raise WorkflowValidationError( + "Catalog config expands beyond the size limit through YAML aliases." + ) + return loader.construct_document(node) + except RecursionError: + raise WorkflowValidationError( + "Catalog config is nested too deeply." + ) from None + finally: + loader.dispose() + + # --------------------------------------------------------------------------- # CatalogEntry # --------------------------------------------------------------------------- @@ -378,7 +434,7 @@ def _load_catalog_config( text = read_files.read_text(config_path) except FileNotFoundError: return None - data = yaml.safe_load(text) + data = _safe_load_catalog_config(text) except (yaml.YAMLError, OSError, UnicodeError) as exc: raise WorkflowValidationError( f"Failed to read catalog config {config_path}: {exc}" @@ -789,7 +845,9 @@ def add_catalog(self, url: str, name: str | None = None) -> str: data: dict[str, Any] = {"catalogs": []} if config_path.exists(): try: - raw = yaml.safe_load(config_path.read_text(encoding="utf-8")) + raw = _safe_load_catalog_config( + config_path.read_text(encoding="utf-8") + ) except (yaml.YAMLError, OSError, UnicodeDecodeError) as exc: raise WorkflowValidationError( f"Catalog config file is unreadable or malformed: {exc}" @@ -874,7 +932,7 @@ def remove_catalog(self, index: int) -> str: raise WorkflowValidationError("No catalog config file found.") try: - data = yaml.safe_load(config_path.read_text(encoding="utf-8")) + data = _safe_load_catalog_config(config_path.read_text(encoding="utf-8")) except (yaml.YAMLError, OSError, UnicodeDecodeError) as exc: raise WorkflowValidationError( f"Catalog config file is unreadable or malformed: {exc}" diff --git a/src/specify_cli/workflows/catalog/_operation_list.py b/src/specify_cli/workflows/catalog/_operation_list.py index c52be36d0d..b075a82981 100644 --- a/src/specify_cli/workflows/catalog/_operation_list.py +++ b/src/specify_cli/workflows/catalog/_operation_list.py @@ -54,6 +54,7 @@ class WorkflowCatalogListOperationDescriptor: contract_version: Literal["1"] request_type: type[WorkflowCatalogListRequest] result_type: type[WorkflowCatalogListResult] + warning_types: tuple[type[object], ...] error_types: tuple[type[WorkflowCatalogListError], ...] capabilities: frozenset[Literal["local-read"]] network_access: Literal["none"] @@ -64,6 +65,7 @@ class WorkflowCatalogListOperationDescriptor: contract_version="1", request_type=WorkflowCatalogListRequest, result_type=WorkflowCatalogListResult, + warning_types=(), error_types=(WorkflowCatalogListError,), capabilities=frozenset({"local-read"}), network_access="none", @@ -93,18 +95,26 @@ def list_catalog_sources( root_is_directory = stat.S_ISDIR(root.stat().st_mode) except (FileNotFoundError, NotADirectoryError, ValueError): root_is_directory = False - if not root_is_directory or not (root / ".specify").is_dir(): + if not root_is_directory: raise WorkflowCatalogListError( "not_a_spec_kit_project", "Not a Spec Kit project (no .specify/ directory)", ) files = project_files(root) + if not (root / ".specify").is_dir(): + raise WorkflowCatalogListError( + "not_a_spec_kit_project", + "Not a Spec Kit project (no .specify/ directory)", + ) validate_workflow_storage(root) configs = WorkflowCatalog(root, read_files=files).get_catalog_configs() except (ProjectPolicyError, WorkflowStorageError, FileHelperError, OSError) as exc: raise WorkflowCatalogListError("unsafe_workflow_storage", str(exc)) from exc except WorkflowCatalogError as exc: - raise WorkflowCatalogListError("invalid_catalog_config", str(exc)) from exc + # Parser and URL diagnostics can quote a configured URL with its credentials. + raise WorkflowCatalogListError( + "invalid_catalog_config", "The workflow catalog configuration is invalid." + ) from exc selected = configs if limit is None else configs[:limit] return WorkflowCatalogListResult( diff --git a/src/specify_cli/workflows/catalog/command_list.py b/src/specify_cli/workflows/catalog/command_list.py index 2ca060dda4..b286651549 100644 --- a/src/specify_cli/workflows/catalog/command_list.py +++ b/src/specify_cli/workflows/catalog/command_list.py @@ -17,7 +17,10 @@ def workflow_catalog_list(): operation.WorkflowCatalogListRequest(project_root) ) except operation.WorkflowCatalogListError as exc: - cli.console.print(f"[red]Error:[/red] {cli._escape_markup(str(exc))}") + # The CLI keeps its established local diagnostics; the shared message is + # deliberately free of configured values. + diagnostic = str(exc.__cause__ or exc) + cli.console.print(f"[red]Error:[/red] {cli._escape_markup(diagnostic)}") raise cli.typer.Exit(1) from exc cli.console.print("\n[bold cyan]Workflow Catalog Sources:[/bold cyan]\n") diff --git a/src/specify_cli/workflows/catalog/mcp_list.py b/src/specify_cli/workflows/catalog/mcp_list.py index 582d540dd9..cf6bd695e7 100644 --- a/src/specify_cli/workflows/catalog/mcp_list.py +++ b/src/specify_cli/workflows/catalog/mcp_list.py @@ -143,8 +143,7 @@ def specify_workflow_catalog_list( is_error=False, ) except operation.WorkflowCatalogListError as exc: - # Config errors can quote a configured URL, including its credentials. - # CLI retains its established diagnostics; MCP never exposes them. + # Shared messages can name local paths, so MCP sends fixed text only. 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.", diff --git a/tests/specify_cli/workflows/catalog/test_command_list.py b/tests/specify_cli/workflows/catalog/test_command_list.py index f6001c2063..ab35b5e730 100644 --- a/tests/specify_cli/workflows/catalog/test_command_list.py +++ b/tests/specify_cli/workflows/catalog/test_command_list.py @@ -83,3 +83,22 @@ def test_catalog_list_reports_invalid_config_and_exits_nonzero( result = CliRunner().invoke(app, ["workflow", "catalog", "list"]) assert result.exit_code == 1 assert "'catalogs' must be a list" in result.output + + def test_catalog_list_keeps_local_diagnostics_for_malformed_urls( + self, project_dir, monkeypatch + ): + """The shared message is secret-free; the CLI still names what to repair.""" + from typer.testing import CliRunner + from specify_cli import app + + monkeypatch.chdir(project_dir) + monkeypatch.delenv("SPECKIT_WORKFLOW_CATALOG_URL", raising=False) + (project_dir / ".specify" / "workflow-catalogs.yml").write_text( + 'catalogs:\n - name: bad\n url: "https://user:token@[::1"\n', + encoding="utf-8", + ) + result = CliRunner().invoke( + app, ["workflow", "catalog", "list"], env={"COLUMNS": "200"} + ) + assert result.exit_code == 1 + assert "Catalog URL is malformed: https://user:token@[::1" in result.output diff --git a/tests/specify_cli/workflows/catalog/test_operation_list.py b/tests/specify_cli/workflows/catalog/test_operation_list.py index d260c4fb3e..f1ef1c3a9c 100644 --- a/tests/specify_cli/workflows/catalog/test_operation_list.py +++ b/tests/specify_cli/workflows/catalog/test_operation_list.py @@ -1,6 +1,7 @@ """Transport-neutral workflow catalog list contract and effect boundaries.""" import errno +import json import socket from dataclasses import FrozenInstanceError from pathlib import Path @@ -42,6 +43,36 @@ def _tree(root): return sorted(str(path.relative_to(root)) for path in root.rglob("*")) +def _symlink_or_skip(link, target): + try: + link.symlink_to(target) + except OSError as exc: + if getattr(exc, "winerror", None) == 1314 or exc.errno in { + errno.EPERM, + errno.ENOTSUP, + }: + pytest.skip(f"Host cannot create symlinks: {exc}") + raise + + +def _allow_symlinks(root, allow): + (root / ".specify" / "init-options.json").write_text( + json.dumps({"allow_symlinks": allow}), encoding="utf-8" + ) + + +def _alias_chain(depth): + """Anchors that each repeat the previous one nine times.""" + lines = ["a0: &a0 [x, x, x, x, x, x, x, x, x]"] + for level in range(1, depth): + aliases = ", ".join([f"*a{level - 1}"] * 9) + lines.append(f"a{level}: &a{level} [{aliases}]") + return "\n".join(lines) + "\n" + + +URL_LINE = " url: https://e.example/c.json\n" + + def test_builtin_defaults_when_nothing_is_configured(tmp_path): result = _list(_project(tmp_path)) assert [item.name for item in result.items] == ["default", "community"] @@ -160,6 +191,94 @@ def test_malformed_config_fails_closed(tmp_path, config): assert exc.value.code == "invalid_catalog_config" +@pytest.mark.parametrize( + "entry", + [ + f" - name: *a6\n{URL_LINE}", + f" - name: n\n{URL_LINE} description: *a6\n", + " - name: n\n url: *a6\n", + f" - name: n\n{URL_LINE} priority: *a6\n", + ], + ids=["name", "description", "url", "priority"], +) +def test_nested_aliases_are_rejected_before_text_coercion(tmp_path, entry): + config = _alias_chain(7) + "catalogs:\n" + entry + assert len(config) < 1024 + with pytest.raises(operation.WorkflowCatalogListError) as exc: + _list(_project(tmp_path, config), 1) + assert exc.value.code == "invalid_catalog_config" + assert "size limit" in str(exc.value.__cause__) + + +def test_nested_merge_keys_are_rejected_before_construction(tmp_path): + lines = ["a0: &a0 {k: v}"] + for level in range(1, 7): + aliases = ", ".join([f"*a{level - 1}"] * 9) + lines.append(f"a{level}: &a{level} {{<<: [{aliases}]}}") + config = "\n".join(lines) + f"\ncatalogs:\n - name: n\n{URL_LINE}" + with pytest.raises(operation.WorkflowCatalogListError) as exc: + _list(_project(tmp_path, config)) + assert exc.value.code == "invalid_catalog_config" + assert "size limit" in str(exc.value.__cause__) + + +@pytest.mark.parametrize( + "config", + [ + f"r: &r [*r]\ncatalogs:\n - name: *r\n{URL_LINE}", + "[" * 5000, + ], + ids=["recursive-alias", "deep-nesting"], +) +def test_unbounded_yaml_structures_fail_closed(tmp_path, config): + with pytest.raises(operation.WorkflowCatalogListError) as exc: + _list(_project(tmp_path, config)) + assert exc.value.code == "invalid_catalog_config" + + +def test_ordinary_aliases_and_merge_keys_still_load(tmp_path): + root = _project( + tmp_path, + "base: &base {install_allowed: true, description: &text Shared text}\n" + "catalogs:\n" + " - {<<: *base, name: one, url: https://one.example/c.json}\n" + " - {name: two, url: https://two.example/c.json, description: *text}\n", + ) + items = _list(root).items + assert [(item.name, item.install_allowed) for item in items] == [ + ("one", True), + ("two", False), + ] + assert [item.description for item in items] == ["Shared text", "Shared text"] + + +def test_large_config_without_aliases_is_not_limited(tmp_path): + description = "x" * (2 * 1024 * 1024) + root = _project( + tmp_path, + f"catalogs:\n - name: big\n{URL_LINE} description: {description}\n", + ) + assert _list(root).items[0].description == description + + +@pytest.mark.parametrize( + "config", + [ + 'catalogs:\n - name: c\n url: "https://user:s3cret@[::1"\n', + 'catalogs:\n - name: c\n url: "https://user:s3cret@e.example/c\n', + "catalogs:\n - name: c\n url: https://e.example/c\n priority: s3cret\n", + ], + ids=["malformed-url", "yaml-parser", "priority"], +) +def test_shared_config_error_message_holds_no_configured_values(tmp_path, config): + with pytest.raises(operation.WorkflowCatalogListError) as exc: + _list(_project(tmp_path, config)) + assert exc.value.code == "invalid_catalog_config" + assert "s3cret" not in str(exc.value) + assert str(tmp_path) not in str(exc.value) + assert "s3cret" in str(exc.value.__cause__) + + def test_undecodable_config_fails_closed(tmp_path): root = _project(tmp_path) (root / ".specify" / "workflow-catalogs.yml").write_bytes(b"\xff\xfe\xff") @@ -175,14 +294,17 @@ def test_invalid_environment_override_fails_closed(tmp_path, monkeypatch): assert exc.value.code == "invalid_catalog_config" -@pytest.mark.parametrize("kind", ["policy", "storage"]) +@pytest.mark.parametrize("kind", ["policy", "storage", "specify-file"]) def test_unsafe_project_storage_is_rejected(tmp_path, kind): root = _project(tmp_path) if kind == "policy": path = root / ".specify" / "init-options.json" path.write_text('{"allow_symlinks": "yes"}', encoding="utf-8") - else: + elif kind == "storage": (root / ".specify" / "workflows").write_text("not a dir", encoding="utf-8") + else: + (root / ".specify").rmdir() + (root / ".specify").write_text("not a dir", encoding="utf-8") with pytest.raises(operation.WorkflowCatalogListError) as exc: _list(root) assert exc.value.code == "unsafe_workflow_storage" @@ -195,41 +317,86 @@ def test_symlinked_project_config_is_not_followed(tmp_path): "catalogs:\n - name: outside\n url: https://outside.example/c.json\n", encoding="utf-8", ) - link = root / ".specify" / "workflow-catalogs.yml" - try: - link.symlink_to(outside) - except OSError as exc: - if getattr(exc, "winerror", None) == 1314 or exc.errno in { - errno.EPERM, - errno.ENOTSUP, - }: - pytest.skip(f"Host cannot create symlinks: {exc}") - raise + _symlink_or_skip(root / ".specify" / "workflow-catalogs.yml", outside) with pytest.raises(operation.WorkflowCatalogListError) as error: _list(root) assert error.value.code == "unsafe_workflow_storage" -def test_project_config_read_goes_through_the_file_policy(tmp_path, monkeypatch): - """Runs without symlink privileges, unlike the real-symlink test above.""" +def test_contained_config_symlink_requires_the_project_opt_in(tmp_path): + root = _project(tmp_path) + target = root / "shared-catalogs.yml" + target.write_text( + "catalogs:\n - name: contained\n url: https://c.example/c.json\n", + encoding="utf-8", + ) + _symlink_or_skip(root / ".specify" / "workflow-catalogs.yml", target) + + with pytest.raises(operation.WorkflowCatalogListError) as error: + _list(root) + assert error.value.code == "unsafe_workflow_storage" + + _allow_symlinks(root, True) + assert [item.name for item in _list(root).items] == ["contained"] + + +def test_config_symlink_leaving_the_project_is_denied_even_with_the_opt_in(tmp_path): + root = _project(tmp_path) + _allow_symlinks(root, True) + outside = tmp_path / "outside.yml" + outside.write_text( + "catalogs:\n - name: outside\n url: https://outside.example/c.json\n", + encoding="utf-8", + ) + _symlink_or_skip(root / ".specify" / "workflow-catalogs.yml", outside) + with pytest.raises(operation.WorkflowCatalogListError) as error: + _list(root) + assert error.value.code == "unsafe_workflow_storage" + + +def test_dangling_specify_symlink_is_unsafe_storage(tmp_path): + root = tmp_path / "project" + root.mkdir() + _symlink_or_skip(root / ".specify", tmp_path / "missing") + with pytest.raises(operation.WorkflowCatalogListError) as error: + _list(root) + assert error.value.code == "unsafe_workflow_storage" + + +@pytest.mark.parametrize("allow", [True, False]) +def test_project_config_read_goes_through_the_file_policy(tmp_path, monkeypatch, allow): + """Runs without symlink privileges, unlike the real-symlink tests above.""" root = _project( tmp_path, "catalogs:\n - name: project\n url: https://p.example/c.json\n" ) - - def deny(self, path, *, encoding="utf-8"): + _allow_symlinks(root, allow) + read_text = FileHelper.read_text + denied = [] + + def deny_catalog_config(self, path, *, encoding="utf-8"): + if Path(path).name != "workflow-catalogs.yml": + return read_text(self, path, encoding=encoding) + denied.append(self.allow_symlinks) raise SymlinkDeniedError(f"Denied: {path}") - monkeypatch.setattr(FileHelper, "read_text", deny) + monkeypatch.setattr(FileHelper, "read_text", deny_catalog_config) with pytest.raises(operation.WorkflowCatalogListError) as exc: _list(root) assert exc.value.code == "unsafe_workflow_storage" + assert denied == [allow] -def test_existing_catalog_callers_keep_their_read_behavior(tmp_path): +def test_existing_catalog_callers_keep_their_read_behavior(tmp_path, monkeypatch): """The read-policy handoff stays opt-in for mutation paths and other callers.""" root = _project( tmp_path, "catalogs:\n - name: project\n url: https://p.example/c.json\n" ) + + def refuse(*args, **kwargs): + raise AssertionError("Default catalog reads must not use FileHelper") + + monkeypatch.setattr(FileHelper, "read_bytes", refuse) + monkeypatch.setattr(FileHelper, "read_text", refuse) configs = WorkflowCatalog(root).get_catalog_configs() assert [config["name"] for config in configs] == ["project"] @@ -254,3 +421,4 @@ def test_descriptor_declares_read_only_local_effects(): assert descriptor.capabilities == frozenset({"local-read"}) assert descriptor.network_access == "none" assert descriptor.result_type is operation.WorkflowCatalogListResult + assert descriptor.warning_types == ()