sf-m3-cli 0.2.0__py3-none-any.whl

m3_cli/__init__.py

@@ -0,0 +1,5 @@
+"""The standalone M3 command line interface."""
+
+from .main import main
+
+__all__ = ["main"]

m3_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Module entry point for ``python -m m3_cli``."""
+
+from .main import main
+
+raise SystemExit(main())

m3_cli/branding.py

@@ -0,0 +1,10 @@
+"""Shared M3 CLI branding."""
+
+M3_ASCII_ART = """\
+███╗   ███╗  ███████╗░
+████╗ ████║       ██║░
+██╔████╔██║  ███████║░
+██║╚██╔╝██║       ██║░
+██║ ╚═╝ ██║  ███████║░
+╚═╝     ╚═╝  ╚══════╝░
+ ░░░░░░░░░░░░░░░░░░░░"""

m3_cli/control_plane.py

@@ -0,0 +1,278 @@
+"""Report uploader library for a future explicit CLI command.
+
+No CLI command or pytest hook imports this module in normal operation.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+import time
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+from urllib import error, request
+from urllib.parse import quote, urlparse
+
+from m3.feedback import Feedback, project_test_attempts
+from m3.storage import SQLiteExecutionStore
+from m3_app.api.report_payloads import (
+    build_execution_envelope,
+    build_report_envelope,
+)
+from m3_app.api.wire import neutralize_response
+from m3_app.services.execution_service import project_test_results
+
+_RETRIES = 3
+_MAX_UPLOAD_BYTES = 16 << 20
+_SAFE_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$")
+
+
+def _id_value(value: Any) -> str:
+    return str(getattr(value, "root", value))
+
+
+class _NoRedirect(request.HTTPRedirectHandler):
+    def redirect_request(
+        self,
+        req: request.Request,
+        fp: Any,
+        code: int,
+        msg: str,
+        headers: Any,
+        newurl: str,
+    ) -> None:
+        raise RuntimeError("control-plane redirect rejected")
+
+
+def _json_bytes(value: Any) -> bytes:
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        allow_nan=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+
+
+def _post(url: str, token: str, body: bytes) -> None:
+    _validate_body(body, token)
+    last: Exception | None = None
+    for attempt in range(_RETRIES):
+        try:
+            req = request.Request(
+                url,
+                data=body,
+                method="POST",
+                headers={
+                    "Authorization": "Bearer " + token,
+                    "Content-Type": "application/json",
+                    "Content-Length": str(len(body)),
+                },
+            )
+            with _OPENER.open(req, timeout=30) as response:
+                if 200 <= response.status < 300:
+                    return
+                if response.status < 500 and response.status != 429:
+                    raise RuntimeError("control-plane upload rejected")
+        except (
+            error.HTTPError,
+            error.URLError,
+            TimeoutError,
+            OSError,
+            RuntimeError,
+        ) as exc:
+            last = exc
+            if isinstance(exc, error.HTTPError) and exc.code < 500 and exc.code != 429:
+                break
+            if attempt + 1 < _RETRIES:
+                time.sleep(0.25 * (2**attempt))
+    raise RuntimeError("control-plane upload failed") from last
+
+
+def _validate_body(body: bytes, token: str) -> None:
+    if len(body) > _MAX_UPLOAD_BYTES:
+        raise RuntimeError("control-plane upload is too large")
+    if token and token.encode("utf-8") in body:
+        raise RuntimeError("control-plane upload contains credential material")
+
+
+def _execution_payload(store: SQLiteExecutionStore, snapshot: Any) -> dict[str, Any]:
+    execution_id = snapshot.execution_id.root
+    report = store.get_report(execution_id, event_limit=None, artifact_limit=None)
+    if report is None:
+        raise RuntimeError("execution data unavailable")
+    if snapshot.lifecycle.value != "finished" or snapshot.outcome is None:
+        raise RuntimeError("execution is not terminal")
+    if (
+        report.snapshot.execution_id != snapshot.execution_id
+        or report.snapshot.lifecycle.value != "finished"
+        or report.snapshot.outcome != snapshot.outcome
+    ):
+        raise RuntimeError("execution report identity is invalid")
+    if report.events_truncated or report.artifacts_truncated:
+        raise RuntimeError("execution report is truncated")
+    if report.event_count != len(report.events) or report.artifact_count != len(
+        report.artifacts
+    ):
+        raise RuntimeError("execution report is incomplete")
+    trace = store.get_trace_view(execution_id)
+    if trace is None:
+        raise RuntimeError("trace data unavailable")
+    spec = store.get_execution_spec(execution_id)
+    project_name = None
+    project_id = snapshot.project_id.root if snapshot.project_id is not None else None
+    get_project = getattr(store, "get_project", None)
+    if project_id is not None and callable(get_project):
+        project = get_project(project_id)
+        project_name = project[1] if project is not None else None
+    test_results: tuple[dict[str, Any], ...] = ()
+    if snapshot.run_id is not None:
+        test_results = tuple(
+            asdict(item)
+            for item in project_test_results(
+                project_test_attempts(store, snapshot.run_id.root), execution_id
+            )
+        )
+    public = build_report_envelope(execution_id, spec, report, trace, test_results)
+    public_execution = build_execution_envelope(snapshot, spec, project_name)
+    public_snapshot = public_execution["snapshot"]
+    return {
+        "transport_version": 1,
+        "snapshot": public_snapshot,
+        "execution": public_execution,
+        "report": public,
+        "sort_at": snapshot.created_at.isoformat(),
+        "lifecycle": snapshot.lifecycle.value,
+        "outcome": snapshot.outcome.value if snapshot.outcome is not None else None,
+        "project_id": project_id,
+        "project_name": project_name,
+    }
+
+
+def upload_current_run(
+    feedback: Feedback,
+    store: SQLiteExecutionStore,
+    directory: str | os.PathLike[str],
+    *,
+    base_url: str,
+    token: str,
+) -> None:
+    """Upload summary, complete current-run executions, then publish.
+
+    Every body is cached before its first request, making retries byte-identical.
+    """
+    parsed = urlparse(base_url)
+    if (
+        parsed.scheme != "https"
+        or not parsed.netloc
+        or parsed.path not in ("", "/")
+        or parsed.query
+        or parsed.fragment
+    ):
+        raise RuntimeError("control-plane URL must be HTTPS")
+    if parsed.username is not None or parsed.password is not None:
+        raise RuntimeError("control-plane URL must not contain credentials")
+    if not token.startswith("m3pat_"):
+        raise RuntimeError("control-plane token must be a personal access token")
+    root = Path(directory) / "control-plane"
+    if root.exists() and root.is_symlink():
+        raise RuntimeError("upload cache path is a symlink")
+    root.mkdir(parents=True, exist_ok=True, mode=0o700)
+    os.chmod(root, 0o700)
+    execution_cache = root / "executions"
+    if execution_cache.is_symlink():
+        raise RuntimeError("upload cache path is a symlink")
+    execution_cache.mkdir(parents=True, exist_ok=True, mode=0o700)
+    os.chmod(execution_cache, 0o700)
+    run_id = _id_value(feedback.run_id)
+    if not _SAFE_ID.fullmatch(run_id) or ".." in run_id:
+        raise RuntimeError("invalid run ID")
+    snapshots: list[Any] = []
+    offset = 0
+    while True:
+        page = store.list_executions(run_id=run_id, limit=100, offset=offset)
+        snapshots.extend(page.items)
+        offset += len(page.items)
+        if not page.items or offset >= page.total:
+            break
+    snapshots = [
+        item
+        for item in snapshots
+        if item.run_id is not None and item.run_id.root == run_id
+    ]
+    execution_ids = [item.execution_id.root for item in snapshots]
+    if any(not _SAFE_ID.fullmatch(item) or ".." in item for item in execution_ids):
+        raise RuntimeError("invalid execution ID")
+    exported = json.loads(
+        (Path(directory) / "feedback.json").read_text(encoding="utf-8")
+    )
+    if not isinstance(exported, dict):
+        raise RuntimeError("feedback export is invalid")
+    summary = {
+        "transport_version": 1,
+        "execution_ids": execution_ids,
+        "baseline_run_id": _id_value(feedback.comparison.baseline_run_id)
+        if feedback.comparison is not None
+        else None,
+        "feedback": {
+            "version": "v2",
+            "feedback": neutralize_response("/api/v2/feedback/{run_id}", exported),
+        },
+    }
+    summary_path = root / "summary.json"
+    if summary_path.is_symlink():
+        raise RuntimeError("upload cache file is a symlink")
+    summary_bytes = (
+        summary_path.read_bytes() if summary_path.is_file() else _json_bytes(summary)
+    )
+    _validate_body(summary_bytes, token)
+    if len(summary_bytes) > 1 << 20:
+        raise RuntimeError("control-plane summary is too large")
+    if not summary_path.is_file():
+        _cache(summary_path, summary_bytes)
+    base = base_url.rstrip("/") + "/v1/runs/" + quote(run_id, safe="")
+    _post(base + "/report", token, summary_bytes)
+    for snapshot in snapshots:
+        execution_id = snapshot.execution_id.root
+        path = execution_cache / (execution_id + ".json")
+        if path.is_symlink():
+            raise RuntimeError("upload cache file is a symlink")
+        body = (
+            path.read_bytes()
+            if path.is_file()
+            else _json_bytes(_execution_payload(store, snapshot))
+        )
+        _validate_body(body, token)
+        if not path.is_file():
+            _cache(path, body)
+        _post(
+            base + "/executions/" + quote(execution_id, safe="") + "/report",
+            token,
+            body,
+        )
+    _post(base + "/publish", token, _json_bytes({"transport_version": 1}))
+
+
+def _cache(path: Path, data: bytes) -> None:
+    fd, temp = tempfile.mkstemp(prefix=".upload-", dir=path.parent)
+    try:
+        os.fchmod(fd, 0o600)
+        with os.fdopen(fd, "wb") as stream:
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temp, path)
+        os.chmod(path, 0o600)
+    finally:
+        try:
+            os.unlink(temp)
+        except FileNotFoundError:
+            pass
+
+
+__all__ = ["upload_current_run"]
+
+_OPENER = request.build_opener(_NoRedirect())

m3_cli/doctor.py

@@ -0,0 +1,376 @@
+"""Implementation of the safe ``m3 doctor`` command."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from dotenv import dotenv_values
+
+from m3.configuration import ConfigError, load_config
+from m3.services.probes import ProbeKind, ProbeRequest, Probes
+
+from .errors import CLIError
+
+_TRANSPORT_MODULES = {
+    "stdio": "mcp.client.stdio",
+    "streamable_http": "mcp.client.streamable_http",
+}
+_STORAGE_MODULES = {"sqlite": "sqlalchemy"}
+_ENV_PREFIX = "M3_"
+
+
+class DoctorCLIError(CLIError):
+    """A user-facing doctor argument or configuration error."""
+
+
+class DoctorArgumentError(DoctorCLIError):
+    """A safe diagnostic for an invalid doctor argument combination."""
+
+
+class DoctorProjectPythonError(DoctorCLIError):
+    """A safe diagnostic for an unavailable or mismatched project Python."""
+
+
+class DoctorConfigurationError(DoctorCLIError):
+    """A value-free configuration diagnostic at the CLI boundary."""
+
+    def __init__(self, error: ConfigError) -> None:
+        self.configuration_error = error
+        super().__init__("invalid configuration")
+
+
+def _configuration_error_payload(error: ConfigError) -> dict[str, str]:
+    return {
+        "code": str(error.code),
+        "field": str(error.field),
+        "origin": str(error.origin),
+        "reason": str(error.reason),
+    }
+
+
+def _read_selected_environment(path: Path | None) -> dict[str, str] | None:
+    if path is None:
+        return None
+    try:
+        if not path.is_file():
+            raise DoctorCLIError("environment file unavailable")
+        # No interpolation through ambient variables: the selected file is an
+        # explicit source, while ambient M3_* values override it below.
+        values = dotenv_values(path, interpolate=False)
+        selected = {
+            key: value
+            for key, value in values.items()
+            if key.startswith(_ENV_PREFIX) and isinstance(value, str)
+        }
+        selected.update(
+            {
+                key: value
+                for key, value in os.environ.items()
+                if key.startswith(_ENV_PREFIX)
+            }
+        )
+        return selected
+    except (OSError, TypeError, ValueError):
+        raise DoctorCLIError("environment file unavailable") from None
+
+
+def _parse_requirement(value: str) -> tuple[str, str | None]:
+    if value == "config":
+        return "config", None
+    if value.startswith("config:"):
+        field = value.partition(":")[2]
+        if field in {"artifact_policy", "protocol_revision", "telemetry_enabled"}:
+            return "config", field
+        raise DoctorCLIError("invalid requirement")
+    try:
+        kind, target = value.split(":", 1)
+    except ValueError:
+        raise DoctorCLIError("invalid requirement") from None
+    if not target or kind not in {
+        "binary",
+        "harness",
+        "protocol",
+        "transport",
+        "storage",
+    }:
+        raise DoctorCLIError("invalid requirement")
+    if kind == "transport" and target not in _TRANSPORT_MODULES:
+        raise DoctorCLIError("invalid requirement")
+    if kind == "storage" and target not in {"memory", "sqlite"}:
+        raise DoctorCLIError("invalid requirement")
+    return kind, target
+
+
+def _probe_label(kind: str, target: str) -> str:
+    """Use a useful fixed/allowlisted result name without arbitrary targets."""
+
+    if kind in {"binary", "harness", "protocol"}:
+        return kind
+    return target
+
+
+def _requests(requirements: list[tuple[str, str | None]]) -> list[ProbeRequest]:
+    requests: list[ProbeRequest] = []
+    for kind, target in requirements:
+        if kind == "config":
+            continue
+        assert target is not None
+        if kind == "transport":
+            requests.append(
+                ProbeRequest(
+                    ProbeKind.TRANSPORT,
+                    _probe_label(kind, target),
+                    transport=target,
+                    module=_TRANSPORT_MODULES[target],
+                )
+            )
+        elif kind == "storage":
+            requests.append(
+                ProbeRequest(
+                    ProbeKind.STORAGE,
+                    _probe_label(kind, target),
+                    module=_STORAGE_MODULES.get(target),
+                )
+            )
+        else:
+            requests.append(
+                ProbeRequest(
+                    getattr(ProbeKind, kind.upper()),
+                    _probe_label(kind, target),
+                    executable=target,
+                )
+            )
+    return requests
+
+
+def _requirement_label(kind: str, target: str | None) -> str:
+    """Return a fixed or allowlisted label that never contains executable targets."""
+
+    if target is None:
+        return kind
+    return kind if kind in {"binary", "harness", "protocol"} else f"{kind}:{target}"
+
+
+def _json_value(value: Any) -> Any:
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json")
+    return value
+
+
+def _redact_requirement_targets(value: Any, targets: set[str]) -> Any:
+    if isinstance(value, str):
+        for target in targets:
+            if target:
+                value = value.replace(target, "[REDACTED]")
+        return value
+    if isinstance(value, list):
+        return [_redact_requirement_targets(item, targets) for item in value]
+    if isinstance(value, dict):
+        return {
+            key: _redact_requirement_targets(item, targets)
+            for key, item in value.items()
+        }
+    return value
+
+
+def _safe_probe_results(
+    results: list[Any], requirements: list[tuple[str, str | None]]
+) -> list[dict[str, Any]]:
+    """Project probe results without exposing executable paths or arguments."""
+
+    targets = {
+        target
+        for kind, target in requirements
+        if kind in {"binary", "harness", "protocol"} and target
+    }
+    safe_results: list[dict[str, Any]] = []
+    for result in results:
+        safe = _redact_requirement_targets(_json_value(result), targets)
+        if not isinstance(safe, dict):
+            safe_results.append(safe)
+            continue
+        evidence = safe.get("evidence")
+        if isinstance(evidence, dict):
+            evidence["resolved_executable"] = None
+            details = evidence.get("details")
+            if isinstance(details, dict):
+                details.pop("resolved_executable", None)
+        safe_results.append(safe)
+    return safe_results
+
+
+def run(args: Any) -> tuple[int, dict[str, Any]]:
+    requirements = [_parse_requirement(value) for value in args.require]
+    if not requirements:
+        requirements = [("config", None), ("storage", "memory")]
+    if args.env_file is not None and not any(
+        kind == "config" for kind, _ in requirements
+    ):
+        raise DoctorArgumentError("--env-file requires a config requirement")
+    environment = _read_selected_environment(args.env_file)
+    if args.project_root is not None:
+        try:
+            if not args.project_root.is_dir():
+                raise DoctorCLIError("project root unavailable")
+        except OSError:
+            raise DoctorCLIError("project root unavailable") from None
+    configuration: dict[str, Any] | None = None
+    project_python: dict[str, Any] | None = None
+    from .supervisor import (
+        ProjectPythonError,
+        resolve_project_python,
+        validate_project_python,
+    )
+
+    root = (args.project_root or Path.cwd()).resolve()
+    try:
+        cli_version = importlib.metadata.version("sf-m3-cli")
+        bundled_sdk_version = importlib.metadata.version("sf-m3")
+    except importlib.metadata.PackageNotFoundError:
+        raise DoctorCLIError(
+            "the CLI installation is incomplete; reinstall sf-m3-cli"
+        ) from None
+    cli = {
+        "status": "ready" if cli_version == bundled_sdk_version else "not ready",
+        "version": cli_version,
+        "sdk_version": bundled_sdk_version,
+    }
+    cli_ready = cli["status"] == "ready"
+    source = None
+    selected_path = None
+
+    try:
+        selected = resolve_project_python(
+            getattr(args, "python", None),
+            project_root=root,
+            fallback_to_system=False,
+        )
+        selected_path = selected
+        if getattr(args, "python", None) is not None:
+            source = "--python"
+        elif os.environ.get("VIRTUAL_ENV"):
+            source = "VIRTUAL_ENV"
+        elif os.environ.get("CONDA_PREFIX"):
+            source = "CONDA_PREFIX"
+        else:
+            source = "project .venv"
+        version = validate_project_python(
+            selected,
+            cli_sdk_version=bundled_sdk_version,
+            project_root=root,
+        )
+    except ProjectPythonError as error:
+        reason = str(error)
+        if reason.startswith("no project environment is configured"):
+            project_python = {"status": "not ready", "reason": reason}
+        elif (
+            "missing required M3 packages" in reason
+            or "does not match CLI SDK" in reason
+            or "distribution version could not be determined" in reason
+        ):
+            project_python = {"status": "not ready", "reason": reason, "source": source}
+        else:
+            raise DoctorProjectPythonError(reason) from None
+    else:
+        project_python = {
+            "status": "ready",
+            "version": version,
+            "source": source,
+            "executable": str(selected_path) if selected_path is not None else None,
+        }
+    include_config = any(kind == "config" for kind, _ in requirements)
+    if include_config:
+        try:
+            config = load_config(env=environment, cwd=args.project_root)
+        except ConfigError as error:
+            raise DoctorConfigurationError(error) from None
+        except (OSError, TypeError, ValueError):
+            raise DoctorCLIError("invalid configuration") from None
+        configuration = {"status": "ready", "settings": _json_value(config)}
+    probe_report = Probes().probe_requested(_requests(requirements))
+    results = _safe_probe_results(list(probe_report.results), requirements)
+    ready = (
+        cli_ready
+        and project_python["status"] == "ready"
+        and (configuration is None or configuration["status"] == "ready")
+        and probe_report.readiness.ready
+    )
+    report = {
+        "ready": ready,
+        "cli": cli,
+        "project_root": str(root),
+        "requirements": [
+            _requirement_label(kind, target) for kind, target in requirements
+        ],
+        "configuration": configuration,
+        "project_python": project_python,
+        "results": results,
+    }
+    return (0 if ready else 1), report
+
+
+def print_human(report: dict[str, Any]) -> None:
+    print(f"m3 doctor: {'ready' if report['ready'] else 'not ready'}")
+    cli = report.get("cli")
+    if cli is not None:
+        print(f"M3 CLI {cli.get('version')}: {cli.get('status')}")
+        if cli.get("sdk_version") != cli.get("version"):
+            print(f"bundled SDK: {cli.get('sdk_version')}")
+    project_python = report.get("project_python")
+    if project_python is not None:
+        detail = (
+            f" (m3 {project_python['version']})"
+            if project_python.get("version")
+            else ""
+        )
+        print(f"project environment: {project_python['status']}{detail}")
+        if project_python.get("source"):
+            print(f"project environment source: {project_python['source']}")
+        if project_python.get("executable"):
+            print(f"project Python: {project_python['executable']}")
+        if project_python.get("reason"):
+            print(f"reason: {project_python['reason']}")
+    if report.get("configuration") is not None:
+        print(f"config: {report['configuration']['status']}")
+    for result in report["results"]:
+        capability = result["capability"]
+        reason = capability.get("reason")
+        print(
+            f"{capability['name']}: {capability['status']}"
+            + (f" ({reason})" if reason else "")
+        )
+    if not report.get("ready"):
+        if cli := report.get("cli"):
+            if cli.get("status") != "ready":
+                print("Next: reinstall sf-m3-cli")
+                return
+        if project_python is not None and project_python.get("status") != "ready":
+            print("Next: m3 setup")
+        else:
+            print("Next: m3 doctor")
+
+
+def print_configuration_error(error: ConfigError) -> None:
+    details = _configuration_error_payload(error)
+    print(
+        "m3 doctor: configuration error "
+        f"(code={details['code']} field={details['field']} "
+        f"origin={details['origin']} reason={details['reason']})",
+        file=sys.stderr,
+    )
+
+
+__all__ = [
+    "DoctorArgumentError",
+    "DoctorCLIError",
+    "DoctorConfigurationError",
+    "DoctorProjectPythonError",
+    "_read_selected_environment",
+    "print_configuration_error",
+    "print_human",
+    "run",
+]

m3_cli/errors.py

@@ -0,0 +1,10 @@
+"""Safe errors shared by command-line subcommands."""
+
+from __future__ import annotations
+
+
+class CLIError(ValueError):
+    """A user-facing CLI error whose message contains no untrusted values."""
+
+
+__all__ = ["CLIError"]