forge-cpp-mcp 0.2.3__tar.gz → 0.2.4__tar.gz

{forge_cpp_mcp-0.2.3 → forge_cpp_mcp-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forge-cpp-mcp
-Version: 0.2.3
+Version: 0.2.4
 Summary: A safe MCP server for structured C++ project development workflows.
 Project-URL: Homepage, https://github.com/hardened-steel/ForgeMCP
 Project-URL: Repository, https://github.com/hardened-steel/ForgeMCP
@@ -44,7 +44,8 @@ debugger modules are planned.
   configuration selections use all available contexts.
 - No prompts are currently registered.
 - CMake tools list operator profiles, configure projects, build targets, and run
-  CTest. Each tool has its own widget with profile filters, Fields/JSON views,
+  CTest. `cmake_run_test` directly runs a project/storage test executable with
+  literal command-line arguments. Each tool has its own widget with Fields/JSON views,
   copying and per-test results. Command logs are available through `process_get`. CMake syntax highlighting remains deferred.
 - Tool `processes_overview` shows running and completed external development tools,
   including exit codes and timeout interruptions. `process_get(process_id)` returns
@@ -75,7 +76,9 @@ without making additional tool calls. Process times are readable to seconds; JSO
 copying preserve the original precision. A toolsets list shows summaries, while a
 `toolset_get` result shows the details returned by that call.
 
-ForgeMCP does not expose arbitrary command execution over MCP. Feature services use
+ForgeMCP can directly run an explicitly selected test executable inside the
+project or storage root; it does not expose shell commands or external executable
+paths over MCP. Feature services use
 the shared process service internally; its public MCP surface is read-only.
 
 ## Requirements
@@ -93,7 +96,7 @@ and install it in a virtual environment:
 
 ```powershell
 python -m venv .venv
-.\.venv\Scripts\python.exe -m pip install .\forge_cpp_mcp-0.2.3-py3-none-any.whl
+.\.venv\Scripts\python.exe -m pip install .\forge_cpp_mcp-0.2.4-py3-none-any.whl
 .\.venv\Scripts\forgemcp.exe --help
 ```
 
@@ -105,7 +108,7 @@ The distribution name is `forge-cpp-mcp`; the Python module and server command a
 After the package is published to PyPI, the install command can instead be:
 
 ```powershell
-.\.venv\Scripts\python.exe -m pip install forge-cpp-mcp==0.2.3
+.\.venv\Scripts\python.exe -m pip install forge-cpp-mcp==0.2.4
 ```
 
 ## Setup from source
@@ -332,6 +335,30 @@ Full process transcripts remain in the process module; CMake results contain no
 transcript links. The default command timeout is 600 seconds per execution and
 can be overridden with the existing `ProcessTimeout` shape (`total`, `idle`).
 
+`cmake_run_test(executable, arguments=null, cwd="project/", timeout={"total":600})`
+runs one already-built test executable directly, without a profile or CTest
+registration. Executable and working-directory paths use `project/...` or
+`storage/...` and must resolve inside their respective roots. The working directory
+must exist; storage is not created automatically. On Windows, batch files are not
+supported. Arguments are a list of literal strings, preserving spaces and empty
+strings; NUL is rejected. For example:
+
+```json
+{
+  "executable": "project/build/ninja-debug/fixture_tests.exe",
+  "arguments": ["--fail"],
+  "cwd": "project/build/ninja-debug",
+  "timeout": {"total": 30}
+}
+```
+
+The process inherits the server environment, closes stdin, and waits for completion.
+It does not replay toolset/preset environments or CTest properties such as
+`WILL_FAIL`, fixtures, or per-test timeouts. Exit zero means success; a nonzero
+exit or process failure is reported in `error`. The single structured result
+contains `executable`, `arguments`, `cwd`, `error`, and `process_id`; logs are read
+through `process_get`. No JUnit or framework case report is inferred from output.
+
 With no explicit profiles:
 
 - If `CMakePresets.json` or `CMakeUserPresets.json` exists, the automatic `presets`

{forge_cpp_mcp-0.2.3 → forge_cpp_mcp-0.2.4}/README.md

@@ -19,7 +19,8 @@ debugger modules are planned.
   configuration selections use all available contexts.
 - No prompts are currently registered.
 - CMake tools list operator profiles, configure projects, build targets, and run
-  CTest. Each tool has its own widget with profile filters, Fields/JSON views,
+  CTest. `cmake_run_test` directly runs a project/storage test executable with
+  literal command-line arguments. Each tool has its own widget with Fields/JSON views,
   copying and per-test results. Command logs are available through `process_get`. CMake syntax highlighting remains deferred.
 - Tool `processes_overview` shows running and completed external development tools,
   including exit codes and timeout interruptions. `process_get(process_id)` returns
@@ -50,7 +51,9 @@ without making additional tool calls. Process times are readable to seconds; JSO
 copying preserve the original precision. A toolsets list shows summaries, while a
 `toolset_get` result shows the details returned by that call.
 
-ForgeMCP does not expose arbitrary command execution over MCP. Feature services use
+ForgeMCP can directly run an explicitly selected test executable inside the
+project or storage root; it does not expose shell commands or external executable
+paths over MCP. Feature services use
 the shared process service internally; its public MCP surface is read-only.
 
 ## Requirements
@@ -68,7 +71,7 @@ and install it in a virtual environment:
 
 ```powershell
 python -m venv .venv
-.\.venv\Scripts\python.exe -m pip install .\forge_cpp_mcp-0.2.3-py3-none-any.whl
+.\.venv\Scripts\python.exe -m pip install .\forge_cpp_mcp-0.2.4-py3-none-any.whl
 .\.venv\Scripts\forgemcp.exe --help
 ```
 
@@ -80,7 +83,7 @@ The distribution name is `forge-cpp-mcp`; the Python module and server command a
 After the package is published to PyPI, the install command can instead be:
 
 ```powershell
-.\.venv\Scripts\python.exe -m pip install forge-cpp-mcp==0.2.3
+.\.venv\Scripts\python.exe -m pip install forge-cpp-mcp==0.2.4
 ```
 
 ## Setup from source
@@ -307,6 +310,30 @@ Full process transcripts remain in the process module; CMake results contain no
 transcript links. The default command timeout is 600 seconds per execution and
 can be overridden with the existing `ProcessTimeout` shape (`total`, `idle`).
 
+`cmake_run_test(executable, arguments=null, cwd="project/", timeout={"total":600})`
+runs one already-built test executable directly, without a profile or CTest
+registration. Executable and working-directory paths use `project/...` or
+`storage/...` and must resolve inside their respective roots. The working directory
+must exist; storage is not created automatically. On Windows, batch files are not
+supported. Arguments are a list of literal strings, preserving spaces and empty
+strings; NUL is rejected. For example:
+
+```json
+{
+  "executable": "project/build/ninja-debug/fixture_tests.exe",
+  "arguments": ["--fail"],
+  "cwd": "project/build/ninja-debug",
+  "timeout": {"total": 30}
+}
+```
+
+The process inherits the server environment, closes stdin, and waits for completion.
+It does not replay toolset/preset environments or CTest properties such as
+`WILL_FAIL`, fixtures, or per-test timeouts. Exit zero means success; a nonzero
+exit or process failure is reported in `error`. The single structured result
+contains `executable`, `arguments`, `cwd`, `error`, and `process_id`; logs are read
+through `process_get`. No JUnit or framework case report is inferred from output.
+
 With no explicit profiles:
 
 - If `CMakePresets.json` or `CMakeUserPresets.json` exists, the automatic `presets`

forge_cpp_mcp-0.2.4/frontend/cmake-run-test.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Test executable result</title>
+  </head>
+  <body>
+    <main id="widget" aria-label="Test executable result"></main>
+    <script type="module" src="/src/cmake-run-test.js"></script>
+  </body>
+</html>

{forge_cpp_mcp-0.2.3 → forge_cpp_mcp-0.2.4}/frontend/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "build": "vite build --mode workspace && vite build --mode file && vite build --mode search && vite build --mode result && vite build --mode process && vite build --mode process-details && vite build --mode toolsets && vite build --mode cmake-profiles && vite build --mode cmake-configure && vite build --mode cmake-build && vite build --mode cmake-test && vite build --mode clangd",
+    "build": "vite build --mode workspace && vite build --mode file && vite build --mode search && vite build --mode result && vite build --mode process && vite build --mode process-details && vite build --mode toolsets && vite build --mode cmake-profiles && vite build --mode cmake-configure && vite build --mode cmake-build && vite build --mode cmake-test && vite build --mode cmake-run-test && vite build --mode clangd",
     "test": "node --test tests/*.test.js"
   },
   "dependencies": {

forge_cpp_mcp-0.2.4/frontend/src/cmake-run-test.js

@@ -0,0 +1,8 @@
+import { connectWidget } from "./shared/app.js";
+import { cmakePresentation, renderCMakeValue } from "./cmake-view.js";
+
+await connectWidget({
+  toolName: "cmake_run_test",
+  describe: (data) => cmakePresentation(data, "cmake_run_test"),
+  renderValue: renderCMakeValue,
+});

{forge_cpp_mcp-0.2.3 → forge_cpp_mcp-0.2.4}/frontend/vite.config.js

@@ -15,6 +15,7 @@ const widgets = {
   "cmake-configure": "cmake-configure",
   "cmake-build": "cmake-build",
   "cmake-test": "cmake-test",
+  "cmake-run-test": "cmake-run-test",
   clangd: "clangd-result",
 };
 

{forge_cpp_mcp-0.2.3 → forge_cpp_mcp-0.2.4}/hatch_build.py

@@ -31,7 +31,7 @@ class CustomBuildHook(BuildHookInterface):
             Path(self.root) / "src" / "forgemcp" / "assets" / "clangd-result.html",
             *(
                 Path(self.root) / "src" / "forgemcp" / "assets" / f"cmake-{kind}.html"
-                for kind in ("profiles", "configure", "build", "test")
+                for kind in ("profiles", "configure", "build", "test", "run-test")
             ),
         ]
         artifacts = build_data.setdefault("artifacts", [])

{forge_cpp_mcp-0.2.3 → forge_cpp_mcp-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forge-cpp-mcp"
-version = "0.2.3"
+version = "0.2.4"
 description = "A safe MCP server for structured C++ project development workflows."
 readme = "README.md"
 requires-python = ">=3.13"

{forge_cpp_mcp-0.2.3 → forge_cpp_mcp-0.2.4}/src/forgemcp/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.3"
+__version__ = "0.2.4"

forge_cpp_mcp-0.2.4/src/forgemcp/cmake/errors.py

@@ -0,0 +1,5 @@
+"""Expected CMake configuration and operation errors."""
+
+
+class CMakeError(Exception):
+    """Invalid profiles, execution paths, unavailable tools, or unusable build metadata."""

{forge_cpp_mcp-0.2.3 → forge_cpp_mcp-0.2.4}/src/forgemcp/cmake/models.py

@@ -72,3 +72,16 @@ class CMakeTestResult(BaseModel):
         description="Null on success; failure explanation otherwise.",
     )
     process_id: int | None = None
+
+
+class CMakeRunTestResult(BaseModel):
+    """One direct executable run with its command inputs, error, and process reference."""
+
+    executable: WorkspacePath
+    arguments: list[str] = Field(default_factory=list)
+    cwd: WorkspacePath
+    error: str | None = Field(
+        default=None,
+        description="Null on success; failure explanation otherwise.",
+    )
+    process_id: int | None = None

{forge_cpp_mcp-0.2.3 → forge_cpp_mcp-0.2.4}/src/forgemcp/cmake/service.py

@@ -20,8 +20,9 @@ from pydantic import Field
 
 from forgemcp.assets import IconFile, Widget
 from forgemcp.completion import Complete
-from forgemcp.process.errors import ProcessError
+from forgemcp.process.errors import ProcessError, ProcessStartError
 from forgemcp.process.models import ProcessTimeout
+from forgemcp.process.service import ProcessService
 from forgemcp.progress import progress
 from forgemcp.text import tool_result
 from forgemcp.toolchain.errors import ToolchainError
@@ -38,8 +39,9 @@ from .models import (
     CMakeConfigureResult,
     CMakeBuildResult,
     CMakeTestResult,
+    CMakeRunTestResult,
 )
-from .text import render_executions, render_profiles
+from .text import render_executions, render_profiles, render_run_test
 
 
 class CMakeService:
@@ -57,6 +59,11 @@ class CMakeService:
     Configure before building; build before testing. Diagnose with a subset,
     then verify all profiles. Each execution reports error (null means success)
     and, when launched, process_id for its command log.
+
+    cmake_run_test runs an explicit project/storage test executable with literal
+    arguments and a working directory, inheriting the server environment.
+    It requires no profile or CTest registration. Zero exit means success;
+    CTest properties, preset environments, and framework case reports do not apply.
     """
 
     ICON = IconFile("icons/cmake.svg")
@@ -64,10 +71,12 @@ class CMakeService:
     CONFIGURE_WIDGET = Widget("assets/cmake-configure.html")
     BUILD_WIDGET = Widget("assets/cmake-build.html")
     TEST_WIDGET = Widget("assets/cmake-test.html")
+    RUN_TEST_WIDGET = Widget("assets/cmake-run-test.html")
 
     def __init__(
         self,
         toolchains: ToolchainService,
+        processes: ProcessService,
         profiles: tuple[ProfileDefinition, ...] = (),
         *,
         project_root: Path,
@@ -81,6 +90,7 @@ class CMakeService:
         self.storage_root = storage_root.resolve()
         self.protected_paths = protected_paths
         self.toolchains = toolchains
+        self.processes = processes
         self.definitions = profiles
         self.default_toolset = default_toolset
         self.progress_interval = progress_interval
@@ -477,6 +487,23 @@ class CMakeService:
                 queue.put_nowait(snapshot)
                 self.configuration_subscribers[queue] = signature
 
+    def execution_path(self, reference: WorkspacePath) -> Path:
+        """Resolve a test executable or working directory without escaping its managed root."""
+        if reference.area == "root":
+            raise CMakeError("Test execution paths must be inside project/ or storage/.")
+        base = self.project_root if reference.area == "project" else self.storage_root
+        try:
+            if os.name == "nt" and any(
+                os.path.isreserved(part) for part in Path(reference.relative).parts
+            ):
+                raise CMakeError(f"Test execution path contains a reserved name: {reference}.")
+            path = (base / reference.relative).resolve()
+            if not path.is_relative_to(base):
+                raise CMakeError(f"Test execution path resolves outside its root: {reference}.")
+            return path
+        except OSError as error:
+            raise CMakeError(f"Cannot resolve test execution path: {reference}.") from error
+
     def register(self, mcp: MCPServer, apps: Apps, complete: Complete) -> None:
         """Register profile inspection, configure, build, and test tools with their widgets."""
         icon = self.ICON.icon
@@ -862,10 +889,76 @@ class CMakeService:
                     await report_status(result.error or "Completed successfully")
             return tool_result(results, render_executions(results, "CTest"))
 
+        @apps.tool(
+            resource_uri=self.RUN_TEST_WIDGET.uri,
+            icons=[icon],
+            annotations=changes_files,
+        )
+        async def cmake_run_test(
+            executable: WorkspacePath,
+            ctx: Context,
+            arguments: list[str] | None = None,
+            cwd: WorkspacePath = WorkspacePath("project/"),
+            timeout: ProcessTimeout = ProcessTimeout(total=600),
+        ) -> Annotated[CallToolResult, CMakeRunTestResult]:
+            """Run one project/storage test executable directly with literal command-line arguments.
+
+            Inherits the server environment; cwd defaults to project/. Zero exit
+            means success. No profiles, CTest properties, or case reports are used.
+            Read output through process_get with the returned process_id.
+            """
+            report = progress(ctx, interval=self.progress_interval)
+            await report(0, message="Preparing test executable")
+            values = arguments if arguments is not None else []
+            if any("\0" in value for value in values):
+                raise ToolError("Test arguments cannot contain NUL.")
+            try:
+                program = self.execution_path(executable)
+                directory = self.execution_path(cwd)
+                if not program.is_file():
+                    raise CMakeError(f"Test executable is not a file: {executable}.")
+                if not directory.is_dir():
+                    raise CMakeError(f"Test working directory does not exist: {cwd}.")
+                if os.name == "nt" and program.suffix.lower() in (".bat", ".cmd"):
+                    raise CMakeError("Test executable must be a native program, not a batch file.")
+            except CMakeError as error:
+                raise ToolError(str(error)) from error
+            except OSError as error:
+                raise ToolError("Cannot inspect test executable or working directory.") from error
+            result = CMakeRunTestResult(
+                executable=executable,
+                arguments=values,
+                cwd=cwd,
+            )
+            updates = 1
+            await report(updates, message="Starting test executable")
+            try:
+                async with await self.processes.launch(
+                    program,
+                    values,
+                    cwd=directory,
+                    timeout=timeout,
+                ) as session:
+                    result.process_id = session.process_id
+                    await session.close_stdin()
+                    async for _ in session.output():
+                        updates += 1
+                        await report(updates, message="Receiving test output")
+                    code = await session.wait()
+                    if code != 0:
+                        result.error = f"Test executable exited with {code}."
+            except ProcessStartError:
+                result.error = f"Cannot start test executable: {executable}."
+            except ProcessError as error:
+                result.error = str(error)
+            await report(updates + 1, message=result.error or "Completed successfully")
+            return tool_result(result, render_run_test(result))
+
         for widget in (
             self.PROFILES_WIDGET,
             self.CONFIGURE_WIDGET,
             self.BUILD_WIDGET,
             self.TEST_WIDGET,
+            self.RUN_TEST_WIDGET,
         ):
             apps.add_html_resource(widget.uri, widget.content)

{forge_cpp_mcp-0.2.3 → forge_cpp_mcp-0.2.4}/src/forgemcp/cmake/text.py

@@ -1,5 +1,6 @@
 """Plain-text CMake settings, execution outcomes, and complete CTest cases."""
 
+import json
 from typing import Literal
 
 from forgemcp.toolchain.tools import ctest
@@ -9,6 +10,7 @@ from .models import (
     CMakeConfigureResult,
     CMakeBuildResult,
     CMakeTestResult,
+    CMakeRunTestResult,
 )
 
 
@@ -96,3 +98,20 @@ def render_test_cases(tests: list[ctest.TestCase]) -> list[str]:
         if test.message is not None:
             lines.append("      " + test.message.replace("\n", "\n      "))
     return lines
+
+
+def render_run_test(result: CMakeRunTestResult) -> str:
+    """Describe a direct run and preserve argument boundaries without copying its transcript."""
+    lines = [
+        f"Test executable: {result.executable}",
+        f"  Arguments: {json.dumps(result.arguments, ensure_ascii=False)}",
+        f"  Working directory: {result.cwd}",
+        f"  Outcome: {'Succeeded' if result.error is None else 'Failed'}",
+    ]
+    if result.error is not None:
+        lines.append("  Error: " + result.error.replace("\n", "\n    "))
+    if result.process_id is not None:
+        lines.append(f"  Command output: process_get(process_id={result.process_id})")
+    else:
+        lines.append("  Process: not available")
+    return "\n".join(lines)

{forge_cpp_mcp-0.2.3 → forge_cpp_mcp-0.2.4}/src/forgemcp/process/service.py

@@ -324,7 +324,8 @@ class ProcessService:
 
     Feature results identify commands by process_id. Process state and ordered
     stdin/stdout/stderr logs are retained in memory until the server stops.
-    Arbitrary command execution is unavailable through the public surface.
+    This service exposes no command execution tools. cmake_run_test can launch an
+    explicit test executable inside project/storage through the CMake surface.
     """
 
     WIDGET = Widget("assets/process-overview.html")

{forge_cpp_mcp-0.2.3 → forge_cpp_mcp-0.2.4}/src/forgemcp/server.py

@@ -63,6 +63,7 @@ def create_server(
     )
     builds = CMakeService(
         toolchains,
+        processes,
         profiles,
         project_root=workspace.root,
         storage_root=workspace.storage_root,

forge_cpp_mcp-0.2.3/src/forgemcp/cmake/errors.py

@@ -1,5 +0,0 @@
-"""Expected CMake configuration and operation errors."""
-
-
-class CMakeError(Exception):
-    """Invalid profiles, unavailable tools, or unusable CMake build metadata."""