makefile-mcp 0.1.0__py3-none-any.whl

makefile_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Makefile MCP package."""
+
+from makefile_mcp.version import __version__
+
+__all__ = ["__version__"]

makefile_mcp/app.py

@@ -0,0 +1,125 @@
+"""Small composition root and protocol-agnostic application facade."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from makefile_mcp.catalog import Catalog, Contexts
+from makefile_mcp.config import load_config_state
+from makefile_mcp.doctor import run_doctor
+from makefile_mcp.errors import ConfigurationError
+from makefile_mcp.execution import TaskExecutor
+from makefile_mcp.filesystem import (
+    FileContextLock,
+    Fingerprint,
+    detect_repository_root,
+    fingerprint,
+)
+from makefile_mcp.makefile import StaticMakeInspector
+from makefile_mcp.models import DoctorResult, MakefileMcpConfig, TaskDefinition, TaskResult
+from makefile_mcp.process import SubprocessRunner
+
+
+@dataclass(frozen=True)
+class Application:
+    """Protocol-independent facade over catalog, diagnostics, and task execution."""
+
+    root: Path
+    config: MakefileMcpConfig
+    contexts: Contexts
+    catalog: Catalog
+    executor: TaskExecutor
+    governed: bool
+    policy_fingerprint: Fingerprint
+
+    def _ensure_policy_current(self) -> None:
+        """Fail closed if the authorization policy changed since application startup."""
+        try:
+            current = fingerprint([self.root / ".makefile-mcp.yaml"])
+        except (OSError, RuntimeError) as exc:
+            raise ConfigurationError(f"could not verify .makefile-mcp.yaml state: {exc}") from exc
+        if current != self.policy_fingerprint:
+            raise ConfigurationError(
+                ".makefile-mcp.yaml changed since startup; "
+                "restart makefile-mcp to apply policy safely"
+            )
+
+    def list_contexts(self) -> list[str]:
+        """Return all configured execution-context names, including ``root``."""
+        self._ensure_policy_current()
+        return self.contexts.names()
+
+    def list_tasks(self, context: str = "root") -> list[TaskDefinition]:
+        """Return callable tasks for one context in stable name order."""
+        self._ensure_policy_current()
+        return self.catalog.list(context)
+
+    def describe_task(self, task: str, context: str = "root") -> TaskDefinition:
+        """Return the callable contract for one task/context pair."""
+        self._ensure_policy_current()
+        return self.catalog.describe(task, context)
+
+    def resolve_capability(self, capability: str, context: str = "root") -> TaskDefinition:
+        """Resolve a semantic capability to its callable task in one context."""
+        self._ensure_policy_current()
+        return self.catalog.resolve_capability(capability, context)
+
+    def list_capabilities(self, context: str = "root") -> dict[str, str]:
+        """Return capability mappings whose target is callable in one context."""
+        self._ensure_policy_current()
+        exposed = {task.name for task in self.catalog.list(context)}
+        return {
+            name: target for name, target in self.config.capabilities.items() if target in exposed
+        }
+
+    async def run_task(
+        self,
+        task: str,
+        variables: dict[str, str] | None = None,
+        context: str = "root",
+        *,
+        preview: bool = False,
+    ) -> TaskResult:
+        """Execute or preview one callable task through the shared bounded executor."""
+        self._ensure_policy_current()
+        return await self.executor.run(task, variables, context, preview=preview)
+
+    def doctor(self) -> DoctorResult:
+        """Run read-only diagnostics against repository, policy, and discovery state."""
+        self._ensure_policy_current()
+        return run_doctor(
+            root=self.root,
+            config=self.config,
+            contexts=self.contexts,
+            catalog=self.catalog,
+            governed=self.governed,
+        )
+
+
+def build_application(start: Path | None = None) -> Application:
+    """Compose one application instance rooted at *start* or the current directory."""
+    root = detect_repository_root(start or Path.cwd())
+    loaded = load_config_state(root)
+    contexts = Contexts(root, loaded.config)
+    catalog = Catalog(
+        config=loaded.config,
+        contexts=contexts,
+        inspector=StaticMakeInspector(root),
+        governed=loaded.governed,
+    )
+    executor = TaskExecutor(
+        root=root,
+        config=loaded.config,
+        contexts=contexts,
+        catalog=catalog,
+        runner=SubprocessRunner(),
+        lock=FileContextLock(root),
+    )
+    return Application(
+        root=root,
+        config=loaded.config,
+        contexts=contexts,
+        catalog=catalog,
+        executor=executor,
+        governed=loaded.governed,
+        policy_fingerprint=loaded.policy_fingerprint,
+    )

makefile_mcp/catalog.py

@@ -0,0 +1,146 @@
+"""Resolve contexts and build the authorized public task catalog."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from makefile_mcp.errors import ContextNotFound, MakeInspectionError, TaskNotExposed, TaskNotFound
+from makefile_mcp.filesystem import Fingerprint, ensure_within_root, fingerprint
+from makefile_mcp.makefile import StaticMakeInspector
+from makefile_mcp.models import MakefileMcpConfig, ProjectContext, TaskDefinition, TaskRisk
+
+
+def _fingerprint(paths: list[Path]) -> Fingerprint:
+    """Normalize filesystem fingerprint failures into the discovery error boundary."""
+    try:
+        return fingerprint(paths)
+    except (OSError, RuntimeError) as exc:
+        raise MakeInspectionError(f"could not fingerprint Make discovery inputs: {exc}") from exc
+
+
+class Contexts:
+    """Resolve configured context names to confined repository directories."""
+
+    def __init__(self, root: Path, config: MakefileMcpConfig):
+        """Create a context resolver for one repository/configuration pair."""
+        self.root = root
+        self.config = config
+
+    def resolve(self, name: str = "root") -> ProjectContext:
+        """Resolve one context name to a repository-confined directory."""
+        if name == "root":
+            return ProjectContext(directory=self.root)
+        spec = self.config.contexts.get(name)
+        if spec is None:
+            raise ContextNotFound(f"unknown context: {name}")
+        directory = ensure_within_root(self.root, self.root / spec.directory, must_exist=True)
+        if not directory.is_dir():
+            raise ContextNotFound(f"context is not a directory: {name}")
+        return ProjectContext(directory=directory)
+
+    def names(self) -> list[str]:
+        """Return ``root`` plus configured context names in stable order."""
+        return ["root", *sorted(self.config.contexts)]
+
+
+@dataclass(frozen=True)
+class CatalogSnapshot:
+    """Cached discovery/exposure view for one context."""
+
+    tasks: dict[str, TaskDefinition]
+    discovered_targets: set[str]
+    warnings: list[str]
+    tracked_files: list[Path]
+
+
+class Catalog:
+    """Cache Make discovery and apply auto/governed exposure policy."""
+
+    def __init__(
+        self,
+        *,
+        config: MakefileMcpConfig,
+        contexts: Contexts,
+        inspector: StaticMakeInspector,
+        governed: bool,
+    ):
+        """Create a catalog over one immutable configuration/exposure mode."""
+        self.config = config
+        self.contexts = contexts
+        self.inspector = inspector
+        self.governed = governed
+        self._cache: dict[str, tuple[Fingerprint, CatalogSnapshot]] = {}
+
+    def snapshot(self, context_name: str = "root") -> CatalogSnapshot:
+        """Return the current cached-or-refreshed catalog snapshot for one context."""
+        context = self.contexts.resolve(context_name)
+        base_paths = [context.directory / "Makefile"]
+        cached = self._cache.get(context_name)
+        if cached and cached[0] == _fingerprint(base_paths + cached[1].tracked_files):
+            return cached[1]
+
+        raw = self.inspector.discover(directory=context.directory)
+        tasks: dict[str, TaskDefinition] = {}
+        for name, target in raw.targets.items():
+            if not self.governed:
+                # Auto mode mirrors lightweight Makefile MCP servers: every target our conservative
+                # inspector can identify is callable. Inputs stay parameterless because there is
+                # no operator-declared variable contract.
+                tasks[name] = TaskDefinition(
+                    name=name,
+                    description=target.description,
+                    context=context_name,
+                    risk=TaskRisk.UNKNOWN,
+                    timeout_seconds=self.config.defaults.timeout_seconds,
+                )
+                continue
+
+            task_config = self.config.tasks.get(name)
+            # Governed mode is deny-by-default. Discovery is broader than authorization and a
+            # target is public only when config enables it for this exact context.
+            if (
+                task_config is None
+                or not task_config.enabled
+                or context_name not in task_config.contexts
+            ):
+                continue
+
+            timeout = task_config.timeout_seconds or self.config.defaults.timeout_seconds
+            tasks[name] = TaskDefinition(
+                name=name,
+                description=task_config.description or target.description,
+                context=context_name,
+                risk=task_config.risk or TaskRisk.UNKNOWN,
+                timeout_seconds=timeout,
+                variables=task_config.variables,
+            )
+
+        snapshot = CatalogSnapshot(
+            tasks=tasks,
+            discovered_targets=set(raw.targets),
+            warnings=raw.warnings,
+            tracked_files=[Path(path) for path in raw.tracked_files],
+        )
+        self._cache[context_name] = (_fingerprint(base_paths + snapshot.tracked_files), snapshot)
+        return snapshot
+
+    def list(self, context: str = "root") -> list[TaskDefinition]:
+        """Return callable tasks in one context, sorted by target name."""
+        tasks = self.snapshot(context).tasks
+        return [tasks[name] for name in sorted(tasks)]
+
+    def describe(self, task: str, context: str = "root") -> TaskDefinition:
+        """Return one callable task or distinguish hidden from unknown targets."""
+        snapshot = self.snapshot(context)
+        definition = snapshot.tasks.get(task)
+        if definition:
+            return definition
+        if task in snapshot.discovered_targets:
+            raise TaskNotExposed(f"target exists but is not exposed in context {context!r}: {task}")
+        raise TaskNotFound(f"unknown Make target: {task}")
+
+    def resolve_capability(self, capability: str, context: str = "root") -> TaskDefinition:
+        """Resolve a semantic capability name to a callable target in one context."""
+        target = self.config.capabilities.get(capability)
+        if not target:
+            raise TaskNotFound(f"unknown capability: {capability}")
+        return self.describe(target, context)

makefile_mcp/cli.py

@@ -0,0 +1,219 @@
+"""Typer CLI. All task policy and execution remain in the application modules."""
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Annotated, Any, Never
+
+import typer
+from pydantic import BaseModel
+
+from makefile_mcp.app import Application, build_application
+from makefile_mcp.errors import MakefileMcpError
+from makefile_mcp.mcp import McpPresentation
+from makefile_mcp.version import __version__
+
+cli = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    help="Expose Make targets over CLI and MCP with optional governance.",
+)
+
+
+class State:
+    """Mutable CLI process state shared by Typer command callbacks."""
+
+    root: Path | None = None
+    application: Application | None = None
+
+
+state = State()
+
+
+def _app() -> Application:
+    if state.application is None:
+        state.application = build_application(state.root)
+    return state.application
+
+
+def _data(value: Any) -> Any:
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if isinstance(value, list):
+        return [_data(item) for item in value]
+    return value
+
+
+def _json(value: Any) -> None:
+    typer.echo(json.dumps(_data(value), indent=2, sort_keys=True))
+
+
+def _fail(exc: MakefileMcpError) -> Never:
+    typer.echo(f"error: {exc}", err=True)
+    raise typer.Exit(code=2)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@cli.callback()
+def callback(
+    root: Annotated[
+        Path | None,
+        typer.Option("--root", help="Repository path; defaults to auto-detection."),
+    ] = None,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show the Makefile MCP version and exit.",
+        ),
+    ] = False,
+) -> None:
+    """Set the repository root used by subsequent CLI commands."""
+    state.root = root
+    state.application = None
+
+
+@cli.command("list")
+def list_command(
+    context: Annotated[str, typer.Option("--context", "-c")] = "root",
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """List callable tasks in one context."""
+    try:
+        tasks = _app().list_tasks(context)
+    except MakefileMcpError as exc:
+        _fail(exc)
+    if json_output:
+        _json(tasks)
+        return
+    for task in tasks:
+        description = f" — {task.description}" if task.description else ""
+        typer.echo(f"{task.name:<24} [{task.risk}] {description}".rstrip())
+
+
+@cli.command("describe")
+def describe_command(
+    task: str,
+    context: Annotated[str, typer.Option("--context", "-c")] = "root",
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Describe one callable task and its governed input contract."""
+    try:
+        definition = _app().describe_task(task, context)
+    except MakefileMcpError as exc:
+        _fail(exc)
+    if json_output:
+        _json(definition)
+        return
+    typer.echo(f"Task: {definition.name}")
+    typer.echo(f"Context: {definition.context}")
+    typer.echo(f"Risk: {definition.risk}")
+    typer.echo(f"Timeout: {definition.timeout_seconds}s")
+    if definition.description:
+        typer.echo(f"Description: {definition.description}")
+    if definition.variables:
+        typer.echo("Variables:")
+        for name, spec in definition.variables.items():
+            marker = "required" if spec.required else "optional"
+            typer.echo(f"  {name}: {spec.type} ({marker})")
+
+
+@cli.command("run")
+def run_command(
+    task: str,
+    assignments: Annotated[
+        list[str] | None,
+        typer.Argument(help="Declared KEY=VALUE task variables."),
+    ] = None,
+    context: Annotated[str, typer.Option("--context", "-c")] = "root",
+    preview: Annotated[
+        bool,
+        typer.Option(
+            "--preview",
+            help="Ask GNU Make for a --dry-run preview; this is not a side-effect-free sandbox.",
+        ),
+    ] = False,
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Execute or preview one callable task with optional declared ``KEY=VALUE`` inputs."""
+    variables: dict[str, str] = {}
+    for item in assignments or []:
+        if "=" not in item:
+            typer.echo(f"error: variable must use KEY=VALUE syntax: {item}", err=True)
+            raise typer.Exit(code=2)
+        key, value = item.split("=", 1)
+        if key in variables:
+            typer.echo(f"error: duplicate variable: {key}", err=True)
+            raise typer.Exit(code=2)
+        variables[key] = value
+    try:
+        result = asyncio.run(_app().run_task(task, variables, context, preview=preview))
+    except MakefileMcpError as exc:
+        _fail(exc)
+    if json_output:
+        _json(result)
+    else:
+        mode = "preview" if result.preview else "run"
+        typer.echo(f"{result.task}: {result.status} [{mode}] ({result.duration_ms} ms)")
+        if result.stdout:
+            typer.echo(result.stdout, nl=not result.stdout.endswith("\n"))
+        if result.stderr:
+            typer.echo(result.stderr, err=True, nl=not result.stderr.endswith("\n"))
+        if result.truncated:
+            typer.echo("[output truncated]", err=True)
+    if result.status != "passed":
+        raise typer.Exit(code=1)
+
+
+@cli.command("doctor")
+def doctor_command(json_output: Annotated[bool, typer.Option("--json")] = False) -> None:
+    """Run read-only repository diagnostics."""
+    try:
+        result = _app().doctor()
+    except MakefileMcpError as exc:
+        _fail(exc)
+    if json_output:
+        _json(result)
+    else:
+        typer.echo("doctor: ok" if result.ok else "doctor: problems found")
+        for finding in result.findings:
+            scope = "/".join(part for part in [finding.context, finding.task] if part)
+            suffix = f" ({scope})" if scope else ""
+            typer.echo(f"[{finding.severity}] {finding.code}{suffix}: {finding.message}")
+    if not result.ok:
+        raise typer.Exit(code=1)
+
+
+@cli.command("serve")
+def serve_command(
+    tools: Annotated[
+        McpPresentation,
+        typer.Option(
+            "--tools",
+            help="MCP presentation: direct per-target tools, generic list/describe/run, or both.",
+        ),
+    ] = McpPresentation.DIRECT,
+) -> None:
+    """Run the MCP stdio server using the selected presentation mode."""
+    from makefile_mcp.mcp.server import run_stdio_server
+
+    try:
+        run_stdio_server(_app(), presentation=tools)
+    except MakefileMcpError as exc:
+        _fail(exc)
+
+
+def main() -> None:
+    """Run the Makefile MCP command-line interface."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

makefile_mcp/config.py

@@ -0,0 +1,74 @@
+"""Load optional metadata-only Makefile MCP configuration."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError
+
+from makefile_mcp.errors import ConfigurationError
+from makefile_mcp.filesystem import Fingerprint, fingerprint
+from makefile_mcp.models import MakefileMcpConfig
+
+
+@dataclass(frozen=True)
+class LoadedConfig:
+    """Validated repository policy together with its exposure-mode decision."""
+
+    config: MakefileMcpConfig
+    governed: bool
+    policy_fingerprint: Fingerprint
+
+
+def load_config_state(repository_root: Path) -> LoadedConfig:
+    """Load repository policy and decide auto/governed mode from one filesystem observation.
+
+    Args:
+        repository_root: Detected trusted repository root.
+
+    Returns:
+        Validated configuration, exposure mode, and the policy-file fingerprint used by the
+        application to fail closed if authorization policy changes while it is running.
+
+    Raises:
+        ConfigurationError: If the policy file exists but cannot be parsed or validated, or if
+            it changes while being loaded.
+    """
+    path = repository_root / ".makefile-mcp.yaml"
+    try:
+        before = fingerprint([path])
+        if not path.exists():
+            after = fingerprint([path])
+            if before != after:
+                raise ConfigurationError(
+                    ".makefile-mcp.yaml changed while configuration was loaded"
+                )
+            return LoadedConfig(
+                config=MakefileMcpConfig(),
+                governed=False,
+                policy_fingerprint=after,
+            )
+        raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        after = fingerprint([path])
+        if before != after:
+            raise ConfigurationError(".makefile-mcp.yaml changed while configuration was loaded")
+        if not isinstance(raw, dict):
+            raise ConfigurationError(".makefile-mcp.yaml must contain a mapping")
+        return LoadedConfig(
+            config=MakefileMcpConfig.model_validate(raw),
+            governed=True,
+            policy_fingerprint=after,
+        )
+    except ConfigurationError:
+        raise
+    except (OSError, RuntimeError, yaml.YAMLError, ValidationError) as exc:
+        raise ConfigurationError(f"invalid .makefile-mcp.yaml: {exc}") from exc
+
+
+def load_config(repository_root: Path) -> MakefileMcpConfig:
+    """Load only the validated repository configuration.
+
+    This compatibility convenience delegates to :func:`load_config_state`; the application
+    composition root uses the state form so config contents and exposure mode share one source.
+    """
+    return load_config_state(repository_root).config