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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forge-cpp-mcp
-Version: 0.2.3
+Version: 0.2.5
 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.5-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.5
 ```
 
 ## Setup from source
@@ -319,6 +322,36 @@ no source preview because explicit external reads require confirmation.
 
 ## CMake profiles
 
+CMake owns which configurations can supply clangd compilation contexts. After a
+successful configure/generate, ForgeMCP reads `cmakeFiles-v1` from a new CMake
+File API reply and records SHA-256 hashes of that build directory's configuration
+inputs in `project/` and `storage/`. Hashes and dependency lists live in memory;
+restart the server and run `cmake_configure` to confirm contexts again. Existing
+File API replies and `compile_commands.json` alone do not confirm current inputs.
+
+Workspace writes, edits, moves, deletions, and directory creation check known
+inputs at the operation boundary. Actual input changes withdraw affected contexts
+and notify clangd through the CMake subscription; identical content and ordinary
+source/header edits keep contexts available unless those files are CMake inputs.
+Known preset files are treated conservatively without resolving preset inheritance
+or includes. CONFIGURE_DEPENDS globs conservatively invalidate on structural
+changes; older File API replies without glob information use this policy for all
+configurations. No project-wide dependency scan or CMake/glob parser is used.
+
+Run `cmake_configure` to restore outdated or unknown contexts. `cmake_build` is
+also allowed for outdated configurations: a new successful File API generation
+can restore them even when later compilation fails. A successful build without
+regeneration does not refresh the input baseline. Failed configure/generate cannot
+reactivate old artifacts, and invalidation leaves build trees and databases intact.
+Unchanged contexts and database contents retain their clangd sessions.
+
+Checks occur only during Workspace mutations, configure, and build. There are no
+filesystem watchers, polling, or background scans, and no guarantee of detecting
+external editor/process changes. External `root/` dependencies are omitted from
+hash tracking without elicitation or reads; changes to those inputs require an
+explicit configure. Native preset contexts still require a known managed build
+directory and a compilation database.
+
 `cmake_profiles` lists profiles. `cmake_configure`, `cmake_build`, and `cmake_test`
 operate on all profiles unless a nonempty `profiles` list selects a subset.
 Configuration must precede building, and building must precede testing. Profiles
@@ -332,6 +365,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.5}/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.5-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.5
 ```
 
 ## Setup from source
@@ -294,6 +297,36 @@ no source preview because explicit external reads require confirmation.
 
 ## CMake profiles
 
+CMake owns which configurations can supply clangd compilation contexts. After a
+successful configure/generate, ForgeMCP reads `cmakeFiles-v1` from a new CMake
+File API reply and records SHA-256 hashes of that build directory's configuration
+inputs in `project/` and `storage/`. Hashes and dependency lists live in memory;
+restart the server and run `cmake_configure` to confirm contexts again. Existing
+File API replies and `compile_commands.json` alone do not confirm current inputs.
+
+Workspace writes, edits, moves, deletions, and directory creation check known
+inputs at the operation boundary. Actual input changes withdraw affected contexts
+and notify clangd through the CMake subscription; identical content and ordinary
+source/header edits keep contexts available unless those files are CMake inputs.
+Known preset files are treated conservatively without resolving preset inheritance
+or includes. CONFIGURE_DEPENDS globs conservatively invalidate on structural
+changes; older File API replies without glob information use this policy for all
+configurations. No project-wide dependency scan or CMake/glob parser is used.
+
+Run `cmake_configure` to restore outdated or unknown contexts. `cmake_build` is
+also allowed for outdated configurations: a new successful File API generation
+can restore them even when later compilation fails. A successful build without
+regeneration does not refresh the input baseline. Failed configure/generate cannot
+reactivate old artifacts, and invalidation leaves build trees and databases intact.
+Unchanged contexts and database contents retain their clangd sessions.
+
+Checks occur only during Workspace mutations, configure, and build. There are no
+filesystem watchers, polling, or background scans, and no guarantee of detecting
+external editor/process changes. External `root/` dependencies are omitted from
+hash tracking without elicitation or reads; changes to those inputs require an
+explicit configure. Native preset contexts still require a known managed build
+directory and a compilation database.
+
 `cmake_profiles` lists profiles. `cmake_configure`, `cmake_build`, and `cmake_test`
 operate on all profiles unless a nonempty `profiles` list selects a subset.
 Configuration must precede building, and building must precede testing. Profiles
@@ -307,6 +340,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.5/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.5}/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.5/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.5}/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.5}/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.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forge-cpp-mcp"
-version = "0.2.3"
+version = "0.2.5"
 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.5}/src/forgemcp/__init__.py

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

{forge_cpp_mcp-0.2.3 → forge_cpp_mcp-0.2.5}/src/forgemcp/clangd/service.py

@@ -273,21 +273,32 @@ class ClangdService(ResultProvider[WorkspaceContext]):
     async def configurations(self) -> list[CompilationContext]:
         """Return independent copies of currently usable compilation contexts."""
         self.check_ready()
-        return [context.model_copy(deep=True) for context in self.contexts.values()]
+        current = {context.id: context for context in await self.cmake.compilation_contexts()}
+        return [
+            context.model_copy(deep=True)
+            for context in self.contexts.values()
+            if current.get(context.id) == context
+        ]
 
     async def selection(self, configurations: Sequence[str]) -> list[CompilationContext]:
         """Validate requested configuration IDs, using all contexts for an empty selection."""
         contexts = await self.configurations()
-        unknown = set(configurations) - self.contexts.keys()
+        unknown = set(configurations) - {context.id for context in contexts}
         if unknown:
-            raise ClangdError(f"Unavailable clangd configurations: {', '.join(sorted(unknown))}.")
+            raise ClangdError(
+                f"Unavailable clangd configurations: {', '.join(sorted(unknown))}. "
+                "CMake inputs may be outdated or unconfirmed; run cmake_configure."
+            )
         selected = [
             context
             for context in contexts
             if not configurations or context.id in configurations
         ]
         if not selected:
-            raise ClangdError("No CMake configuration has both a compilation database and clangd.")
+            raise ClangdError(
+                "No confirmed CMake configuration has both a compilation database and clangd. "
+                "CMake inputs may be outdated or unconfirmed; run cmake_configure."
+            )
         return selected
 
     @asynccontextmanager
@@ -867,7 +878,9 @@ class ClangdService(ResultProvider[WorkspaceContext]):
         databases = {context.compilation_database for context in self.contexts.values()}
         if any(change.path in databases for change in changes):
             await self.cmake.publish_configurations(refresh=True)
-            await self.update_configurations(await self.cmake.compilation_contexts())
+        # CMake's provider may still be checking this mutation. It never waits
+        # for analysis while holding its operation lock, so this order is safe.
+        await self.update_configurations(await self.cmake.compilation_contexts())
         notifications: list[JsonValue] = [
             {
                 "uri": self.workspace.resolve_workspace_path(change.path).as_uri(),

forge_cpp_mcp-0.2.5/src/forgemcp/cmake/build_tree.py

@@ -0,0 +1,67 @@
+"""Managed CMake build trees and direct test execution paths."""
+
+import os
+import shutil
+from pathlib import Path
+
+from forgemcp.workspace.path import WorkspacePath
+
+from .errors import CMakeError
+
+
+def clear_build_directory(
+    directory: Path,
+    root: Path,
+    storage: Path,
+    protected: set[Path],
+) -> None:
+    """Remove an owned tree only after root, protected subtree, and link checks succeed."""
+    if (
+        directory == root
+        or not directory.resolve().is_relative_to(root)
+        or storage.is_relative_to(directory)
+        or any(path.is_relative_to(directory) for path in protected)
+    ):
+        raise CMakeError(
+            "Build directory contains a protected path or escaped its root."
+        )
+
+    def raise_walk_error(error: OSError) -> None:
+        """Reject incomplete pre-removal inspection rather than ignoring traversal failures."""
+        raise error
+
+    try:
+        if not directory.exists():
+            return
+        for parent, directories, files in os.walk(
+            directory,
+            followlinks=False,
+            onerror=raise_walk_error,
+        ):
+            for name in (*directories, *files):
+                item = Path(parent) / name
+                if item.is_symlink() or item.is_junction():
+                    raise CMakeError("Build directory contains a link or junction.")
+        if not directory.resolve().is_relative_to(root):
+            raise CMakeError("Build directory escaped its root.")
+        shutil.rmtree(directory)
+    except OSError as error:
+        raise CMakeError("Cannot clear build directory.") from error
+
+
+def execution_path(reference: WorkspacePath, project: Path, storage: Path) -> 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 = project if reference.area == "project" else storage
+    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

forge_cpp_mcp-0.2.5/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.5/src/forgemcp/cmake/file_api.py

@@ -0,0 +1,229 @@
+"""Read bounded CMake-owned replies and fingerprint managed configuration inputs."""
+
+import hashlib
+import json
+import os
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from forgemcp.workspace.path import WorkspacePath
+
+from .errors import CMakeError
+
+MAX_REPLY_BYTES = 16 * 1024 * 1024
+MAX_INPUTS = 100_000
+
+
+@dataclass
+class WorkspaceChange:
+    """Known input hashes and path kinds needed to verify one controlled mutation."""
+
+    inputs: dict[WorkspacePath, str | None]
+    kinds: dict[WorkspacePath, str]
+
+
+@dataclass
+class ConfigurationInputs:
+    """One generation's input hashes and conservative structural invalidation policy."""
+
+    checksums: dict[WorkspacePath, str | None] = field(default_factory=dict)
+    structural: bool = False
+    current: bool = False
+
+    def verify(self, project: Path, storage: Path) -> None:
+        """Withdraw a confirmed baseline when an input changes or cannot safely be read."""
+        if not self.current:
+            return
+        try:
+            self.current = self.checksums == input_checksums(
+                self.checksums,
+                project,
+                storage,
+            )
+        except (CMakeError, OSError):
+            self.current = False
+
+
+def managed_path(path: Path, project: Path, storage: Path) -> WorkspacePath | None:
+    """Qualify a path only when both its lexical and resolved targets stay managed."""
+    for area, base in (("storage", storage), ("project", project)):
+        if path.is_relative_to(base) and path.resolve().is_relative_to(base):
+            relative = path.relative_to(base).as_posix()
+            return WorkspacePath(f"{area}/{'' if relative == '.' else relative}")
+    return None
+
+
+def checksum(path: Path) -> str | None:
+    """Hash a file incrementally, representing a missing input without retaining contents."""
+    try:
+        with path.open("rb") as stream:
+            return hashlib.file_digest(stream, "sha256").hexdigest()
+    except FileNotFoundError:
+        return None
+
+
+def read_reply(path: Path, project: Path, storage: Path) -> dict:
+    """Read a size-bounded managed JSON reply without following references outside the roots."""
+    if managed_path(path, project, storage) is None:
+        raise CMakeError("CMake File API reply is outside managed roots.")
+    with path.open("rb") as stream:
+        data = stream.read(MAX_REPLY_BYTES + 1)
+    if len(data) > MAX_REPLY_BYTES:
+        raise CMakeError("CMake File API reply exceeds the size limit.")
+    value = json.loads(data)
+    if not isinstance(value, dict):
+        raise CMakeError("Expected a CMake File API object.")
+    return value
+
+
+def generation(directory: Path) -> str | None:
+    """Identify the latest successful index, rejecting a newer CMake 4.1 error index."""
+    try:
+        reply = directory / ".cmake/api/v1/reply"
+        current = reply
+        while current != directory:
+            if current.is_symlink() or current.is_junction():
+                raise CMakeError("CMake File API cannot traverse links or junctions.")
+            current = current.parent
+        if not reply.exists():
+            return None
+        indexes = []
+        errors = []
+        for count, path in enumerate(reply.iterdir()):
+            if count >= MAX_INPUTS:
+                raise CMakeError("Too many CMake File API reply files.")
+            if path.name.startswith("index-") and path.suffix == ".json":
+                indexes.append(path.name)
+            elif path.name.startswith("error-") and path.suffix == ".json":
+                errors.append(path.name)
+        latest = max(indexes, default=None)
+        if latest is None or (errors and max(errors)[6:] >= latest[6:]):
+            return None
+        return latest
+    except OSError as error:
+        raise CMakeError("Cannot inspect CMake File API generation.") from error
+
+
+def read_inputs(
+    directory: Path,
+    index: str,
+    project: Path,
+    storage: Path,
+) -> ConfigurationInputs:
+    """Follow cmakeFiles-v1 from this generation and hash only project/storage inputs."""
+    try:
+        reply = directory / ".cmake/api/v1/reply"
+        reference = read_reply(reply / index, project, storage)["reply"][
+            "client-forgemcp"
+        ]["cmakeFiles-v1"]
+        filename = reference["jsonFile"]
+        if not isinstance(filename, str) or Path(filename).name != filename:
+            raise CMakeError("Invalid CMake File API reply reference.")
+        files = read_reply(reply / filename, project, storage)
+        if files["kind"] != "cmakeFiles" or files["version"]["major"] != 1:
+            raise CMakeError("Unsupported CMake configuration inputs reply.")
+        if (
+            Path(files["paths"]["source"]).resolve() != project
+            or Path(files["paths"]["build"]).resolve() != directory.resolve()
+        ):
+            raise CMakeError(
+                "CMake File API reply belongs to a different source/build tree."
+            )
+        inputs = files["inputs"]
+        if not isinstance(inputs, list) or not inputs or len(inputs) > MAX_INPUTS:
+            raise CMakeError("Invalid or excessive CMake configuration inputs.")
+        checksums = {}
+        for item in inputs:
+            native = Path(item["path"])
+            if not native.is_absolute():
+                native = project / native
+            native = Path(os.path.abspath(native))
+            qualified = managed_path(native, project, storage)
+            if qualified is not None:
+                checksums[qualified] = checksum(native)
+        for filename in ("CMakePresets.json", "CMakeUserPresets.json"):
+            native = project / filename
+            qualified = managed_path(native, project, storage)
+            if qualified is not None:
+                checksums[qualified] = checksum(native)
+        # Older replies cannot tell us whether CONFIGURE_DEPENDS globs exist.
+        return ConfigurationInputs(
+            checksums,
+            structural=files["version"].get("minor", 0) < 1
+            or bool(files.get("globsDependent")),
+            current=True,
+        )
+    except (OSError, ValueError, KeyError, TypeError) as error:
+        raise CMakeError(
+            "Cannot confirm CMake configuration inputs; run cmake_configure."
+        ) from error
+
+
+def input_path(reference: WorkspacePath, project: Path, storage: Path) -> Path:
+    """Resolve an input within its selected managed root without accessing external targets."""
+    if reference.area == "root":
+        raise CMakeError("Configuration inputs must be managed paths.")
+    base = project if reference.area == "project" else storage
+    path = base / reference.relative
+    if not path.resolve().is_relative_to(base):
+        raise CMakeError(f"Configuration input escaped its root: {reference}.")
+    return path
+
+
+def input_checksums(
+    paths: Iterable[WorkspacePath],
+    project: Path,
+    storage: Path,
+) -> dict[WorkspacePath, str | None]:
+    """Capture only hashes for the supplied managed input names."""
+    return {path: checksum(input_path(path, project, storage)) for path in paths}
+
+
+def path_kind(path: Path) -> str:
+    """Capture a mutation target's existence and kind without traversing its subtree."""
+    if path.is_dir():
+        return "directory"
+    return "file" if path.exists() else "missing"
+
+
+def prepare_queries(query: Path) -> None:
+    """Create owned File API queries in a validated build-tree directory."""
+    try:
+        query.mkdir(parents=True, exist_ok=True)
+        for name in ("codemodel-v2", "cache-v2", "toolchains-v1", "cmakeFiles-v1"):
+            target = query / name
+            if target.is_symlink() or target.is_junction():
+                raise CMakeError("CMake File API queries cannot be links.")
+            target.write_text("", encoding="utf-8")
+    except OSError as error:
+        raise CMakeError("Cannot prepare CMake File API queries.") from error
+
+
+def compilation_database(
+    directory: WorkspacePath,
+    native: Path,
+) -> WorkspacePath | None:
+    """Return the qualified compilation database name when that build tree contains one."""
+    path = native / "compile_commands.json"
+    return (
+        WorkspacePath(f"{directory}/compile_commands.json") if path.is_file() else None
+    )
+
+
+def read_generation(
+    directory: Path,
+    previous: str | None,
+    project: Path,
+    storage: Path,
+) -> ConfigurationInputs | None:
+    """Read inputs only when a command produced a new successful File API index."""
+    try:
+        latest = generation(directory)
+        if latest is None or latest == previous:
+            return None
+        return read_inputs(directory, latest, project, storage)
+    except OSError as error:
+        raise CMakeError(
+            "Cannot inspect CMake generation; run cmake_configure."
+        ) from error