forge-cpp-mcp 0.2.1__py3-none-any.whl

forgemcp/toolchain/providers/visual_studio.py

@@ -0,0 +1,202 @@
+"""Windows Visual Studio instances, installation layouts, and VsDevCmd environments."""
+
+import json
+import os
+from itertools import islice
+from pathlib import Path
+from urllib.parse import quote
+
+from forgemcp.process.errors import ProcessError
+from forgemcp.process.models import ProcessEncoding, ProcessTimeout
+from forgemcp.process.service import ProcessService
+
+from ..errors import ToolCommandError
+from ..spec import ToolInfo, Toolset
+
+MAX_INSTANCES = 128
+MAX_LAYOUT_ENTRIES = 512
+
+
+def vswhere_path() -> Path | None:
+    folder = os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")
+    path = Path(folder) / "Microsoft Visual Studio/Installer/vswhere.exe"
+    return path.resolve() if path.is_file() else None
+
+
+async def instance_environment(root: Path, processes: ProcessService) -> dict[str, str]:
+    batch = root / "Common7/Tools/VsDevCmd.bat"
+    if not batch.is_file():
+        raise ToolCommandError("Visual Studio developer environment is unavailable.")
+    # cmd is the explicit interpreter for the batch script. Shell operators here
+    # are provider-owned, not executable arguments supplied by project data.
+    comspec = os.environ.get("COMSPEC", r"C:\Windows\System32\cmd.exe")
+    session = await processes.launch(
+        comspec,
+        (
+            "/u",
+            "/d",
+            "/s",
+            "/c",
+            "call",
+            str(batch),
+            "-no_logo",
+            "-arch=x64",
+            "&&",
+            "set",
+        ),
+        encoding=ProcessEncoding("utf-16-le"),
+        timeout=ProcessTimeout(total=60),
+    )
+    environment: dict[str, str] = {}
+    pending = ""
+    async with session:
+        await session.close_stdin()
+        async for output in session.output():
+            if output.stream != "stdout":
+                continue
+            pending += output.text
+            lines = pending.split("\n")
+            pending = lines.pop()
+            for line in lines:
+                name, separator, value = line.rstrip("\r").partition("=")
+                if separator and name:
+                    environment[name] = value
+        if pending:
+            name, separator, value = pending.rstrip("\r").partition("=")
+            if separator and name:
+                environment[name] = value
+        result = await session.wait()
+    if result != 0 or not environment:
+        raise ToolCommandError("Visual Studio developer environment failed.")
+    return environment
+
+
+def directories(root: Path) -> list[Path]:
+    if not root.is_dir():
+        return []
+    # Only enumerate known shallow layout directories, never a recursive tree scan.
+    return sorted(
+        (path for path in islice(root.iterdir(), MAX_LAYOUT_ENTRIES) if path.is_dir()),
+        reverse=True,
+    )
+
+
+def locate(root: Path, name: str) -> Path | None:
+    candidates: list[Path] = []
+    if name in {"cl", "link"}:
+        for version in directories(root / "VC/Tools/MSVC"):
+            for host in ("Hostx64/x64", "Hostarm64/arm64", "Hostx86/x86"):
+                candidates.append(version / "bin" / host / f"{name}.exe")
+    if name == "msbuild":
+        candidates += [
+            root / "MSBuild/Current/Bin/amd64/MSBuild.exe",
+            root / "MSBuild/Current/Bin/MSBuild.exe",
+        ]
+    if name in {"cmake", "ctest", "ninja"}:
+        relative = "Ninja/ninja.exe" if name == "ninja" else f"CMake/bin/{name}.exe"
+        candidates.append(
+            root / "Common7/IDE/CommonExtensions/Microsoft/CMake" / relative
+        )
+    if name in {
+        "clang",
+        "clang++",
+        "clang-cl",
+        "lld",
+        "lld-link",
+        "clangd",
+        "lldb-dap",
+    }:
+        for folder in (
+            "VC/Tools/Llvm/x64/bin",
+            "VC/Tools/Llvm/ARM64/bin",
+            "VC/Tools/Llvm/bin",
+        ):
+            candidates.append(root / folder / f"{name}.exe")
+    if name == "git":
+        candidates.append(
+            root
+            / "Common7/IDE/CommonExtensions/Microsoft/TeamFoundation/Team Explorer/Git/cmd/git.exe"
+        )
+    if name == "cppvsdbg":
+        for relative in (
+            "Common7/IDE/Extensions/Microsoft/DebugAdapterHost/OpenDebugAD7.exe",
+            "Common7/IDE/CommonExtensions/Microsoft/VC/Debugger/OpenDebugAD7.exe",
+        ):
+            candidates.append(root / relative)
+    return next((path.resolve() for path in candidates if path.is_file()), None)
+
+
+async def discover(
+    specs: tuple[ToolInfo, ...],
+    processes: ProcessService,
+) -> tuple[Toolset, ...]:
+    if os.name != "nt":
+        return ()
+    executable = vswhere_path()
+    if executable is None:
+        return ()
+    try:
+        session = await processes.launch(
+            executable,
+            ("-all", "-prerelease", "-products", "*", "-format", "json", "-utf8"),
+            encoding=ProcessEncoding("utf-8"),
+            timeout=ProcessTimeout(total=30),
+        )
+        async with session:
+            await session.close_stdin()
+            # JSON must be decoded as a document; cap only this discovery listing.
+            document = ""
+            async for output in session.output():
+                if output.stream == "stdout":
+                    if len(document) + len(output.text) > 4 * 1024 * 1024:
+                        raise ToolCommandError(
+                            "Visual Studio instance listing is too large."
+                        )
+                    document += output.text
+            terminal = await session.wait()
+        if terminal != 0:
+            return ()
+        instances = json.loads(document)
+        if not isinstance(instances, list):
+            return ()
+    except (ProcessError, ToolCommandError, ValueError, OSError):
+        return ()
+    found = []
+    seen = set()
+    for instance in instances[:MAX_INSTANCES]:
+        if not isinstance(instance, dict):
+            continue
+        if not all(
+            isinstance(instance.get(key), str) and instance[key]
+            for key in ("instanceId", "installationPath", "displayName")
+        ):
+            continue
+        identifier = "visual-studio-" + quote(instance["instanceId"], safe="")
+        if identifier in seen:
+            continue
+        seen.add(identifier)
+        root = Path(instance["installationPath"])
+        try:
+            environment = await instance_environment(root, processes)
+        except (ProcessError, ToolCommandError, OSError):
+            # Keep a failed instance visible, but don't bind commands to a wrong env.
+            found.append(Toolset(identifier, instance["displayName"], (), None, False))
+            continue
+        bound = []
+        for spec in specs:
+            try:
+                path = locate(root, spec.name)
+                if path is not None:
+                    bound.append(spec.create_spec(path, processes, environment, False))
+            except OSError:
+                continue
+        found.append(
+            Toolset(
+                identifier,
+                instance["displayName"],
+                tuple(bound),
+                environment,
+                False,
+            )
+        )
+    return tuple(found)

forgemcp/toolchain/service.py

@@ -0,0 +1,226 @@
+"""Toolset containers, consumer API, and read-only MCP inspection."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+
+from mcp.server import MCPServer
+from mcp.server.apps import Apps
+from mcp.server.mcpserver import Context
+from mcp.server.mcpserver.exceptions import ResourceNotFoundError, ToolError
+from mcp.types import (
+    Completion,
+    CompletionArgument,
+    CompletionContext,
+    PromptReference,
+    ResourceTemplateReference,
+    ToolAnnotations,
+)
+from pydantic import BaseModel
+
+from forgemcp import markdown
+from forgemcp.assets import IconFile, Widget
+from forgemcp.completion import Complete
+from forgemcp.progress import progress
+from forgemcp.process.service import ProcessService
+
+from . import discovery
+from .errors import ToolCommandError, ToolParserError, ToolsetNotFoundError
+from .spec import ToolKind, Toolset, ToolSpec
+
+
+class ToolsetSummary(BaseModel):
+    id: str
+    name: str
+    tools: list[str]
+
+
+class ToolDetails(BaseModel):
+    name: str
+    kind: ToolKind
+    path: str
+    version: str | None
+
+
+class ToolsetDetails(BaseModel):
+    id: str
+    name: str
+    tools: list[ToolDetails]
+
+
+class ToolchainService:
+    """Toolchain: independent sets of development executables and execution environments.
+
+    Toolsets are discovered once at startup and may be incomplete or empty.
+    No current or preferred toolset is selected; consumers bind an explicit ID.
+    Executable paths are absolute; available versions are queried on demand.
+    A missing version does not imply a missing executable. Toolset results omit
+    execution environments.
+    """
+
+    WIDGET = Widget("assets/toolsets.html")
+    ICON = IconFile("icons/toolchain.svg")
+    LIST_URI = "forgemcp://toolsets"
+    DETAILS_URI = "forgemcp://toolsets/{toolset_id}"
+
+    def __init__(
+        self,
+        processes: ProcessService,
+        definitions: Sequence[Sequence[str]] = (),
+        *,
+        progress_interval: float = 1.0,
+    ) -> None:
+        self.progress_interval = progress_interval
+        self.processes = processes
+        self.definitions = tuple(tuple(group) for group in definitions)
+        self.toolsets: tuple[Toolset, ...] = ()
+        self.initialized = False
+        self.discovery_lock = asyncio.Lock()
+
+    async def initialize(self) -> None:
+        """Discover once and publish the complete collection atomically."""
+        async with self.discovery_lock:
+            if not self.initialized:
+                toolsets = await discovery.discover(self.processes, self.definitions)
+                self.toolsets = toolsets
+                self.initialized = True
+
+    def list_toolsets(self) -> tuple[Toolset, ...]:
+        return self.toolsets
+
+    def get_toolset(self, toolset_id: str) -> Toolset:
+        for toolset in self.toolsets:
+            if toolset.id == toolset_id:
+                return toolset
+        raise ToolsetNotFoundError(f"Unknown toolset ID {toolset_id!r}.")
+
+    def get_tool(self, toolset_id: str, tool_name: str) -> ToolSpec | None:
+        return next(
+            (
+                tool
+                for tool in self.get_toolset(toolset_id).tools
+                if tool.name == tool_name
+            ),
+            None,
+        )
+
+    def register(self, mcp: MCPServer, apps: Apps, complete: Complete) -> None:
+        icon = self.ICON.icon
+        annotations = ToolAnnotations(
+            read_only_hint=True,
+            destructive_hint=False,
+            idempotent_hint=True,
+            open_world_hint=False,
+        )
+
+        async def read_tool(tool: ToolSpec) -> ToolDetails:
+            # Versions belong only to the current MCP response, never the spec.
+            version = None
+            if "version" in tool.methods:
+                try:
+                    version = await tool.methods["version"]()
+                except (ToolCommandError, ToolParserError):
+                    pass
+            return ToolDetails(
+                name=tool.name,
+                kind=tool.kind,
+                path=str(tool.path),
+                version=version,
+            )
+
+        @apps.tool(resource_uri=self.WIDGET.uri, icons=[icon], annotations=annotations)
+        async def toolsets_list(ctx: Context) -> list[ToolsetSummary]:
+            """List all discovered toolsets and the tools available in each."""
+            report_progress = progress(ctx, interval=self.progress_interval)
+            await report_progress(0, total=1, message="Reading toolsets")
+            result = [
+                ToolsetSummary(
+                    id=item.id,
+                    name=item.name,
+                    tools=[tool.name for tool in item.tools],
+                )
+                for item in self.list_toolsets()
+            ]
+            await report_progress(1, total=1, message="Toolsets ready")
+            return result
+
+        @apps.tool(resource_uri=self.WIDGET.uri, icons=[icon], annotations=annotations)
+        async def toolset_get(toolset_id: str, ctx: Context) -> ToolsetDetails:
+            """Read tool paths and kinds, querying available versions for this request."""
+            report_progress = progress(ctx, interval=self.progress_interval)
+            try:
+                toolset = self.get_toolset(toolset_id)
+            except ToolsetNotFoundError as error:
+                raise ToolError(str(error)) from error
+            total = len(toolset.tools)
+            await report_progress(0, total=total, message="Reading tool versions")
+            details = []
+            for index, tool in enumerate(toolset.tools, start=1):
+                details.append(await read_tool(tool))
+                await report_progress(
+                    index,
+                    total=total,
+                    message=f"Read {tool.name}",
+                )
+            return ToolsetDetails(id=toolset.id, name=toolset.name, tools=details)
+
+        apps.add_html_resource(self.WIDGET.uri, self.WIDGET.content)
+
+        @mcp.resource(self.LIST_URI, mime_type="text/markdown", icons=[icon])
+        def toolsets() -> str:
+            """Read a markdown summary of all discovered toolsets."""
+            table = markdown.Table(["ID", "Name", "Tools"])
+            for item in self.list_toolsets():
+                table.add(
+                    [item.id, item.name, ", ".join(tool.name for tool in item.tools)]
+                )
+            return markdown.Document([markdown.Heading("Toolsets"), table]).render()
+
+        @mcp.resource(self.DETAILS_URI, mime_type="text/markdown", icons=[icon])
+        async def toolset_details(toolset_id: str) -> str:
+            """Read executable paths and query available versions of one toolset."""
+            try:
+                toolset = self.get_toolset(toolset_id)
+            except ToolsetNotFoundError as error:
+                raise ResourceNotFoundError(str(error)) from error
+            table = markdown.Table(["Tool", "Kind", "Absolute path", "Version"])
+            for tool in toolset.tools:
+                detail = await read_tool(tool)
+                table.add(
+                    [
+                        detail.name,
+                        detail.kind.value,
+                        detail.path,
+                        detail.version or "Unknown",
+                    ]
+                )
+            return markdown.Document(
+                [
+                    markdown.Heading(toolset.name),
+                    markdown.Paragraph(f"ID: {toolset.id}"),
+                    table,
+                ]
+            ).render()
+
+        async def toolset_completion(
+            ref: PromptReference | ResourceTemplateReference,
+            argument: CompletionArgument,
+            context: CompletionContext | None,
+        ) -> Completion | None:
+            if (
+                not isinstance(ref, ResourceTemplateReference)
+                or ref.uri != self.DETAILS_URI
+                or argument.name != "toolset_id"
+            ):
+                return None
+            values = [
+                item.id for item in self.toolsets if item.id.startswith(argument.value)
+            ]
+            return Completion(
+                values=values[:100],
+                total=len(values),
+                has_more=len(values) > 100,
+            )
+
+        complete.add_completion(toolset_completion)

forgemcp/toolchain/spec.py

@@ -0,0 +1,73 @@
+"""Tool metadata, ready executable specs, and independent toolsets."""
+
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from types import MappingProxyType
+from typing import NotRequired, ReadOnly, TypedDict
+
+from forgemcp.process.service import ProcessService
+
+from .errors import ToolCommandError
+
+
+class ToolKind(StrEnum):
+    BUILD_SYSTEM = "build_system"
+    BUILD_RUNNER = "build_runner"
+    TEST_RUNNER = "test_runner"
+    COMPILER = "compiler"
+    LINKER = "linker"
+    LANGUAGE_SERVER = "language_server"
+    VERSION_CONTROL = "version_control"
+    DEBUGGER = "debugger"
+    OTHER = "other"
+
+
+class ToolMethods(TypedDict):
+    """The subset of tool methods understood by toolchain."""
+
+    version: ReadOnly[NotRequired[Callable[[], Awaitable[str]]]]
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    name: str
+    kind: ToolKind
+    path: Path
+    methods: ToolMethods
+
+
+@dataclass(frozen=True)
+class ToolInfo:
+    """Discovery metadata and a factory for a ready executable spec."""
+
+    name: str
+    kind: ToolKind
+    create_spec: Callable[
+        [Path, ProcessService, Mapping[str, str] | None, bool], ToolSpec
+    ]
+
+
+@dataclass(frozen=True)
+class Toolset:
+    id: str
+    name: str
+    tools: tuple[ToolSpec, ...]
+    environment: Mapping[str, str] | None
+    inherit_environment: bool
+
+    def __post_init__(self) -> None:
+        if len({tool.name for tool in self.tools}) != len(self.tools):
+            raise ToolCommandError("Toolset contains duplicate tool names.")
+        object.__setattr__(
+            self,
+            "tools",
+            tuple(sorted(self.tools, key=lambda tool: tool.name)),
+        )
+        if self.environment is not None:
+            object.__setattr__(
+                self,
+                "environment",
+                MappingProxyType(dict(self.environment)),
+            )

forgemcp/toolchain/tools/__init__.py

@@ -0,0 +1 @@
+"""Each public module exports INFO and its concrete Methods TypedDict."""

forgemcp/toolchain/tools/clang.py

@@ -0,0 +1,61 @@
+"""Typed methods for clang."""
+
+import re
+from collections.abc import Awaitable, Callable, Mapping
+from pathlib import Path
+from typing import TypedDict
+
+from forgemcp.process.errors import ProcessError
+from forgemcp.process.models import ProcessTimeout
+from forgemcp.process.service import ProcessService
+
+from ..errors import ToolCommandError, ToolParserError
+from ..spec import ToolInfo, ToolKind, ToolSpec
+
+
+class Methods(TypedDict):
+    version: Callable[[], Awaitable[str]]
+
+
+def create_spec(
+    path: Path,
+    processes: ProcessService,
+    environment: Mapping[str, str] | None = None,
+    inherit_environment: bool = True,
+) -> ToolSpec:
+    path = path.resolve()
+
+    async def version() -> str:
+        output = {"stdout": "", "stderr": ""}
+        try:
+            async with await processes.launch(
+                path,
+                ('--version',),
+                env=environment,
+                inherit_environment=inherit_environment,
+                timeout=ProcessTimeout(total=15),
+            ) as session:
+                await session.close_stdin()
+                async for chunk in session.output():
+                    # Only the short version banner is needed; drain the rest.
+                    remaining = 4096 - len(output[chunk.stream])
+                    output[chunk.stream] += chunk.text[:remaining]
+                code = await session.wait()
+                if code != 0:
+                    raise ToolCommandError(f"{INFO.name}.version failed (exit {code}).")
+        except ProcessError as error:
+            raise ToolCommandError(f"Cannot read {INFO.name} version.") from error
+        for text in output.values():
+            if match := re.search(
+                'clang version ([0-9][^\\s]*)',
+                text,
+                re.IGNORECASE | re.MULTILINE,
+            ):
+                return match.group(1)
+        raise ToolParserError(f"Cannot parse {INFO.name} version.")
+
+    methods: Methods = {"version": version}
+    return ToolSpec(INFO.name, INFO.kind, path, methods)
+
+
+INFO = ToolInfo(name='clang', kind=ToolKind.COMPILER, create_spec=create_spec)

forgemcp/toolchain/tools/clang_cl.py

@@ -0,0 +1,61 @@
+"""Typed methods for clang-cl."""
+
+import re
+from collections.abc import Awaitable, Callable, Mapping
+from pathlib import Path
+from typing import TypedDict
+
+from forgemcp.process.errors import ProcessError
+from forgemcp.process.models import ProcessTimeout
+from forgemcp.process.service import ProcessService
+
+from ..errors import ToolCommandError, ToolParserError
+from ..spec import ToolInfo, ToolKind, ToolSpec
+
+
+class Methods(TypedDict):
+    version: Callable[[], Awaitable[str]]
+
+
+def create_spec(
+    path: Path,
+    processes: ProcessService,
+    environment: Mapping[str, str] | None = None,
+    inherit_environment: bool = True,
+) -> ToolSpec:
+    path = path.resolve()
+
+    async def version() -> str:
+        output = {"stdout": "", "stderr": ""}
+        try:
+            async with await processes.launch(
+                path,
+                ('--version',),
+                env=environment,
+                inherit_environment=inherit_environment,
+                timeout=ProcessTimeout(total=15),
+            ) as session:
+                await session.close_stdin()
+                async for chunk in session.output():
+                    # Only the short version banner is needed; drain the rest.
+                    remaining = 4096 - len(output[chunk.stream])
+                    output[chunk.stream] += chunk.text[:remaining]
+                code = await session.wait()
+                if code != 0:
+                    raise ToolCommandError(f"{INFO.name}.version failed (exit {code}).")
+        except ProcessError as error:
+            raise ToolCommandError(f"Cannot read {INFO.name} version.") from error
+        for text in output.values():
+            if match := re.search(
+                'clang version ([0-9][^\\s]*)',
+                text,
+                re.IGNORECASE | re.MULTILINE,
+            ):
+                return match.group(1)
+        raise ToolParserError(f"Cannot parse {INFO.name} version.")
+
+    methods: Methods = {"version": version}
+    return ToolSpec(INFO.name, INFO.kind, path, methods)
+
+
+INFO = ToolInfo(name='clang-cl', kind=ToolKind.COMPILER, create_spec=create_spec)