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

m3_cli/init.py

@@ -0,0 +1,236 @@
+"""Project scaffolding for the standalone M3 CLI."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import typing
+import uuid
+from pathlib import Path
+
+if typing.TYPE_CHECKING:
+    import tomli as _tomllib
+elif sys.version_info >= (3, 11):
+    import tomllib as _tomllib
+else:  # pragma: no cover - exercised by Python 3.10
+    import tomli as _tomllib
+
+DEFAULT_SUITE = "mcp-behavior"
+_ENV_EXAMPLE = """# Copy to .env if it does not exist; otherwise add the keys you need.
+# Keep real keys out of .env.example and ensure .env is gitignored.
+
+# Agent model providers
+OPENCODE_API_KEY=
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+
+# LLMJudge(model=...) reads this key by default.
+M3_JUDGE_API_KEY=
+"""
+
+
+def _project_root(value: Path | None) -> Path:
+    if value is not None:
+        return value.expanduser().resolve()
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except (OSError, subprocess.CalledProcessError):
+        return Path.cwd().resolve()
+    return Path(result.stdout.strip()).resolve()
+
+
+def _validate(value: str, label: str) -> str:
+    value = value.strip()
+    if not value:
+        raise ValueError(f"{label} must not be blank")
+    if len(value) > 256:
+        raise ValueError(f"{label} must be at most 256 characters")
+    if any(ord(char) < 32 or ord(char) == 127 for char in value):
+        raise ValueError(f"{label} must not contain control characters")
+    return value
+
+
+def _toml_string(value: str) -> str:
+    return (
+        '"' + value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n") + '"'
+    )
+
+
+def _starter(suite: str) -> str:
+    return f'''import pytest
+
+
+@pytest.mark.m3(suite_name={_toml_string(suite)})
+@pytest.mark.skip(reason="TODO: implement this test for your MCP project")
+def test_mcp_behavior() -> None:
+    """Verify the MCP behavior this suite is meant to protect."""
+    # TODO: connect to your MCP server with MCPTestKit, or add the
+    # agent fixture to test how an agent uses the server.
+    # TODO: assert the expected result or captured tool call.
+    pytest.fail("Replace this starter with a real M3 assertion")
+'''
+
+
+def _identity(config: Path) -> dict[str, object] | None:
+    try:
+        data = _tomllib.loads(config.read_text(encoding="utf-8"))
+        project_id = data.get("project_id")
+        project_name = data.get("project_name")
+        if (
+            type(data.get("schema_version")) is not int
+            or data["schema_version"] != 1
+            or not isinstance(project_id, str)
+            or not isinstance(project_name, str)
+            or _validate(project_name, "project name") != project_name
+            or str(uuid.UUID(project_id)) != project_id
+        ):
+            return None
+        return data
+    except (OSError, UnicodeError, ValueError, TypeError):
+        return None
+
+
+def _style(value: str, code: str) -> str:
+    if sys.stdout.isatty() and "NO_COLOR" not in os.environ:
+        return f"\x1b[{code}m{value}\x1b[0m"
+    return value
+
+
+def _create_env_example(path: Path) -> bool:
+    if path.exists() or path.is_symlink():
+        return False
+    with path.open("x", encoding="utf-8", newline="\n") as stream:
+        try:
+            stream.write(_ENV_EXAMPLE)
+        except OSError:
+            path.unlink(missing_ok=True)
+            raise
+    return True
+
+
+def run(args: object) -> int:
+    root = _project_root(getattr(args, "project_root", None))
+    if not root.is_dir():
+        print("m3 init: project root is unavailable", file=sys.stderr)
+        return 2
+    config = root / "m3.toml"
+    starter = root / "tests" / "test_m3_starter.py"
+    env_example = root / ".env.example"
+    config_present = config.exists() or config.is_symlink()
+    starter_present = starter.exists() or starter.is_symlink()
+    data = (
+        _identity(config)
+        if config_present and config.is_file() and not config.is_symlink()
+        else None
+    )
+    if (
+        data is not None
+        and starter_present
+        and starter.is_file()
+        and not starter.is_symlink()
+    ):
+        try:
+            created_example = _create_env_example(env_example)
+        except OSError:
+            print("m3 init: could not create .env.example", file=sys.stderr)
+            return 2
+        print(f"m3 is already initialized at {root}")
+        print(f"Project: {data['project_name']}")
+        print(f"Files: {config}, {starter}")
+        if created_example:
+            print(f"Created {env_example}")
+            print("Existing project files unchanged; supplied names were not applied.")
+        else:
+            print("Nothing changed; supplied names were not applied.")
+        print("Edit project_name in m3.toml to rename the project; keep project_id.")
+        return 0
+    if config_present or starter_present:
+        print(
+            f"m3 init: partial initialization found at {root}; "
+            "repair m3.toml and tests/test_m3_starter.py, then retry.",
+            file=sys.stderr,
+        )
+        return 2
+
+    print(_style("M3 init", "1;36"))
+    project_arg = getattr(args, "project_name", None)
+    suite_arg = getattr(args, "suite", None)
+    interactive = sys.stdin.isatty()
+    try:
+        if project_arg is None:
+            if not interactive:
+                raise ValueError(
+                    "--project-name is required when stdin is not interactive"
+                )
+            default = root.name or "project"
+            answer = input(f"Project name [{default}]: ").strip()
+            project_arg = answer or default
+        if suite_arg is None:
+            if not interactive:
+                raise ValueError("--suite is required when stdin is not interactive")
+            answer = input(f"Suite name [{DEFAULT_SUITE}]: ").strip()
+            suite_arg = answer or DEFAULT_SUITE
+        project_name = _validate(str(project_arg), "project name")
+        suite_name = _validate(str(suite_arg), "suite name")
+    except (EOFError, KeyboardInterrupt):
+        print("m3 init: cancelled", file=sys.stderr)
+        return 130
+    except ValueError as exc:
+        print(f"m3 init: {exc}", file=sys.stderr)
+        return 2
+
+    config_text = (
+        "# M3 project identity. Keep project_id stable when renaming.\n"
+        "schema_version = 1\n"
+        f"project_id = {_toml_string(str(uuid.uuid4()))}\n"
+        f"project_name = {_toml_string(project_name)}\n"
+    )
+    created: list[Path] = []
+    tests_dir = starter.parent
+    created_tests_dir = False
+    try:
+        if tests_dir.is_symlink():
+            raise OSError("tests path is a symlink")
+        if not tests_dir.exists():
+            tests_dir.mkdir()
+            created_tests_dir = True
+        with config.open("x", encoding="utf-8", newline="\n") as stream:
+            created.append(config)
+            stream.write(config_text)
+        with starter.open("x", encoding="utf-8", newline="\n") as stream:
+            created.append(starter)
+            stream.write(_starter(suite_name))
+        if _create_env_example(env_example):
+            created.append(env_example)
+    except OSError:
+        for path in reversed(created):
+            try:
+                path.unlink()
+            except OSError:
+                pass
+        if created_tests_dir:
+            try:
+                tests_dir.rmdir()
+            except OSError:
+                pass
+        print("m3 init: could not create project files", file=sys.stderr)
+        return 2
+    print(_style(f"Initialized M3 project {project_name!r} at {root}", "32"))
+    print(f"Created {config}")
+    print(f"Created {starter}")
+    if env_example in created:
+        print(f"Created {env_example}")
+    print("Next: m3 setup")
+    print(
+        "For agent or judge tests, add the keys you use to .env (copy .env.example if needed)."
+    )
+    print("Pass --env-file .env to m3 test to load those keys.")
+    print("Then implement and unskip the test, and run:")
+    print(f"  m3 test --suite {suite_name} -- tests/test_m3_starter.py")
+    return 0

m3_cli/main.py

@@ -0,0 +1,271 @@
+"""Argument parsing and command dispatch for the standalone CLI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+from . import doctor, init, runtime, setup
+from .branding import M3_ASCII_ART
+from .errors import CLIError
+
+
+class _RedactingArgumentParser(argparse.ArgumentParser):
+    def error(self, _message: str) -> NoReturn:
+        raise CLIError("invalid command or configuration")
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = _RedactingArgumentParser(
+        prog="m3",
+        description=M3_ASCII_ART,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    subparsers = parser.add_subparsers(
+        dest="command", required=True, parser_class=_RedactingArgumentParser
+    )
+    doctor_parser = subparsers.add_parser(
+        "doctor", help="check explicitly requested SDK capabilities"
+    )
+    doctor_parser.add_argument(
+        "--require",
+        action="append",
+        default=[],
+        metavar="KIND:TARGET",
+        help=(
+            "require config, binary:<exe>, harness:<exe>, protocol:<exe>, "
+            "transport:<stdio|streamable_http>, or storage:<memory|sqlite>"
+        ),
+    )
+    doctor_parser.add_argument(
+        "--project-root", type=Path, help="project root used for pyproject discovery"
+    )
+    doctor_parser.add_argument(
+        "--python", type=Path, metavar="PATH", help="Python used for project checks"
+    )
+    doctor_parser.add_argument(
+        "--env-file", type=Path, help="explicit dotenv file; cwd .env is never searched"
+    )
+    doctor_parser.add_argument(
+        "--json", action="store_true", help="emit a machine-readable report"
+    )
+
+    setup_parser = subparsers.add_parser(
+        "setup", help="install the SDK into a project environment"
+    )
+    setup_parser.add_argument(
+        "--project-root", type=Path, help="project root used for environment setup"
+    )
+
+    init_parser = subparsers.add_parser(
+        "init", help="create a project identity and pytest starter test"
+    )
+    init_parser.add_argument("--project-root", type=Path, help="project root")
+    init_parser.add_argument(
+        "--project-name", help="project name (prompts when omitted)"
+    )
+    init_parser.add_argument(
+        "--suite", help="starter suite name (prompts when omitted)"
+    )
+    setup_parser.add_argument(
+        "--python",
+        type=Path,
+        metavar="PATH",
+        help="isolated Python environment to update",
+    )
+
+    test = subparsers.add_parser("test", help="run pytest")
+    test.add_argument(
+        "--python", type=Path, metavar="PATH", help="Python used to run pytest"
+    )
+    test.add_argument(
+        "--project-root", type=Path, help="project root used for pytest and M3 state"
+    )
+    test.add_argument(
+        "--results-db", type=Path, metavar="PATH", help="SQLite history database"
+    )
+    test.add_argument(
+        "--baseline", metavar="RUN_ID", help="compare feedback with a previous run"
+    )
+    test.add_argument("--runtime", choices=("system", "managed"), default="system")
+    test.add_argument(
+        "--harness",
+        action="append",
+        default=[],
+        metavar="KIND[@VERSION]=MODEL[,MODEL...]",
+    )
+    test.add_argument("--harness-cache-dir", type=Path, default=None, metavar="PATH")
+    test.add_argument("--trials", type=int, default=None, metavar="N")
+    test.add_argument("--suite", type=str, default=None, metavar="NAME")
+    test.add_argument(
+        "--execution-timeout",
+        type=float,
+        default=None,
+        metavar="SECONDS",
+        help="deadline for each selected agent execution",
+    )
+    test.add_argument("--judge-max-requests", type=int, default=None, metavar="N")
+    test.add_argument(
+        "--credential-env",
+        action="append",
+        default=[],
+        metavar="[KIND:]TARGET=SOURCE",
+    )
+    test.add_argument("--env-file", type=Path, default=None, metavar="PATH")
+    test.add_argument(
+        "--ui", action="store_true", help="serve the bundled UI after pytest"
+    )
+    test.add_argument("--port", type=int, default=8000, metavar="PORT", help="UI port")
+
+    runtime_parser = subparsers.add_parser(
+        "runtime", help="manage managed runtime caches"
+    )
+    runtime_sub = runtime_parser.add_subparsers(
+        dest="runtime_command", required=True, parser_class=_RedactingArgumentParser
+    )
+    cache_parser = runtime_sub.add_parser("cache", help="manage managed harness cache")
+    cache_sub = cache_parser.add_subparsers(
+        dest="cache_command", required=True, parser_class=_RedactingArgumentParser
+    )
+    for action in ("list", "prune"):
+        command = cache_sub.add_parser(action, help=f"{action} managed harness cache")
+        command.add_argument(
+            "--cache-dir",
+            "--harness-cache-dir",
+            type=Path,
+            default=None,
+            metavar="PATH",
+        )
+        command.add_argument("--project-root", type=Path, default=None, metavar="PATH")
+    return parser
+
+
+def _command_error_message(command: str) -> str:
+    return f"m3 {command}: invalid command or configuration"
+
+
+def main(argv: list[str] | None = None) -> int:
+    effective_argv = list(sys.argv[1:] if argv is None else argv)
+    command_name = (
+        effective_argv[0]
+        if effective_argv
+        and effective_argv[0] in {"doctor", "setup", "test", "init", "runtime"}
+        else "doctor"
+    )
+    pytest_args: list[str] = []
+    try:
+        if effective_argv and effective_argv[0] == "test" and "--" in effective_argv:
+            separator = effective_argv.index("--")
+            pytest_args = effective_argv[separator + 1 :]
+            effective_argv = effective_argv[:separator]
+        try:
+            args = _parser().parse_args(effective_argv)
+        except SystemExit as exc:
+            return exc.code if isinstance(exc.code, int) else 2
+        if args.command == "test":
+            from .supervisor import run_test
+
+            return run_test(
+                python=args.python,
+                project_root=args.project_root,
+                pytest_args=pytest_args,
+                database=args.results_db,
+                ui=args.ui,
+                port=args.port,
+                baseline=args.baseline,
+                harnesses=args.harness,
+                trials=args.trials,
+                suite=args.suite,
+                credential_env=args.credential_env,
+                env_file=args.env_file,
+                execution_timeout=args.execution_timeout,
+                judge_max_requests=args.judge_max_requests,
+                runtime=args.runtime,
+                harness_cache_dir=args.harness_cache_dir,
+            )
+        if args.command == "runtime":
+            return runtime.cache_command(
+                args.cache_command,
+                args.cache_dir,
+                project_root=args.project_root,
+            )
+        if args.command == "setup":
+            try:
+                return setup.run(args)
+            except setup.SetupError as exc:
+                print(f"m3 setup: {exc}", file=sys.stderr)
+                return 2
+        if args.command == "init":
+            return init.run(args)
+        code, report = doctor.run(args)
+        if args.json:
+            print(json.dumps(report, indent=2, sort_keys=True))
+        else:
+            doctor.print_human(report)
+        return code
+    except doctor.DoctorConfigurationError as exc:
+        if "--json" in effective_argv:
+            print(
+                json.dumps(
+                    {
+                        "ready": False,
+                        "error": doctor._configuration_error_payload(
+                            exc.configuration_error
+                        ),
+                    }
+                )
+            )
+        else:
+            doctor.print_configuration_error(exc.configuration_error)
+        return 2
+    except doctor.DoctorArgumentError as exc:
+        if "--json" in effective_argv:
+            print(json.dumps({"ready": False, "error": str(exc)}))
+        else:
+            print(f"m3 doctor: {exc}", file=sys.stderr)
+        return 2
+    except doctor.DoctorProjectPythonError as exc:
+        if "--json" in effective_argv:
+            print(
+                json.dumps(
+                    {
+                        "ready": False,
+                        "error": {
+                            "code": "project_python_unavailable",
+                            "reason": str(exc),
+                        },
+                    }
+                )
+            )
+        else:
+            print(f"m3 doctor: {exc}", file=sys.stderr)
+        return 2
+    except doctor.DoctorCLIError as exc:
+        print(f"m3 doctor: {exc}", file=sys.stderr)
+        return 2
+    except CLIError:
+        if "--json" in effective_argv:
+            print(
+                json.dumps(
+                    {"ready": False, "error": "invalid command or configuration"}
+                )
+            )
+        else:
+            print(_command_error_message(command_name), file=sys.stderr)
+        return 2
+    except Exception:
+        if "--json" in effective_argv:
+            print(
+                json.dumps(
+                    {"ready": False, "error": "invalid command or configuration"}
+                )
+            )
+        else:
+            print(_command_error_message(command_name), file=sys.stderr)
+        return 2
+
+
+__all__ = ["main"]

m3_cli/runtime.py

@@ -0,0 +1,123 @@
+"""CLI access to the managed runtime cache service."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from m3.runtime import list_cache as _sdk_list_cache
+from m3.runtime import prune_cache as _sdk_prune_cache
+from m3.runtime import resolve_cache_root as _sdk_resolve_cache_root
+
+
+def resolve_cache_root(
+    override: str | os.PathLike[str] | None = None, *, project_root: Path | None = None
+) -> Path:
+    return (
+        _sdk_resolve_cache_root(
+            project_root or Path.cwd(),
+            cli_override=Path(override).expanduser() if override is not None else None,
+        )
+        .expanduser()
+        .absolute()
+    )
+
+
+def list_cache(root: Path) -> list[dict[str, Any]]:
+    entries = list(_sdk_list_cache(root))
+
+    def project(item: Mapping[str, Any]) -> dict[str, str]:
+        provenance = item.get("provenance")
+        values = provenance if isinstance(provenance, dict) else item
+        path = Path(str(item.get("path", "")))
+        return {
+            "kind": str(values.get("kind", "")),
+            "version": str(values.get("version", "")),
+            "target": str(values.get("target", "")),
+            "digest": str(values.get("sha256", "")),
+            "status": "in_use"
+            if any(path.glob("lease-*"))
+            else str(item.get("status", "ready")),
+        }
+
+    projected = [project(item) for item in entries]
+    return sorted(
+        projected,
+        key=lambda item: tuple(
+            item[field] for field in ("kind", "version", "target", "digest")
+        ),
+    )
+
+
+def _entry_paths(root: Path) -> list[Path]:
+    return [
+        Path(str(item["path"]))
+        for item in _sdk_list_cache(root)
+        if isinstance(item.get("path"), str)
+    ]
+
+
+def _entry_size(path: Path) -> int:
+    """Return bytes occupied by regular files in a cache entry.
+
+    Cache entries are trusted only after the SDK has validated them.  Still,
+    avoid following links here so reporting a prune cannot traverse outside
+    the selected cache if an entry is concurrently modified.
+    """
+    total = 0
+    try:
+        for current, directories, files in os.walk(path, followlinks=False):
+            directories[:] = [
+                name for name in directories if not (Path(current) / name).is_symlink()
+            ]
+            for name in files:
+                candidate = Path(current) / name
+                try:
+                    if not candidate.is_symlink():
+                        total += candidate.stat().st_size
+                except OSError:
+                    continue
+    except OSError:
+        return 0
+    return total
+
+
+def prune_cache(root: Path) -> list[Path]:
+    deadline = time.monotonic() + 10.0
+    removed: list[Path] = []
+    while True:
+        removed.extend(_sdk_prune_cache(root))
+        if not _entry_paths(root):
+            return removed
+        if time.monotonic() >= deadline:
+            raise RuntimeError("runtime cache entries are still in use")
+        time.sleep(0.1)
+
+
+def cache_command(
+    action: str,
+    override: str | os.PathLike[str] | None = None,
+    *,
+    project_root: Path | None = None,
+) -> int:
+    try:
+        root = resolve_cache_root(override, project_root=project_root)
+        if action == "list":
+            print(json.dumps(list_cache(root), sort_keys=True))
+        else:
+            sizes = {path: _entry_size(path) for path in _entry_paths(root)}
+            removed = prune_cache(root)
+            bytes_removed = sum(sizes.get(path, 0) for path in removed)
+            print(
+                f"pruned runtime cache: {root} "
+                f"({len(removed)} entries, {bytes_removed} bytes removed)"
+            )
+        return 0
+    except (OSError, ValueError, RuntimeError) as exc:
+        print(f"m3 runtime: {exc}", file=sys.stderr)
+        return 2