trackwright 0.3.0__py3-none-any.whl

trackwright/__init__.py

@@ -0,0 +1,13 @@
+"""Trackwright: an MCP server that inspects and controls Cubase through a MIDI Remote script."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("trackwright")
+except PackageNotFoundError:  # pragma: no cover - only when running from a raw source tree
+    __version__ = "0.0.0"
+
+SERVER_NAME = "trackwright"
+"""Identifier of the MCP server."""
+
+__all__ = ["SERVER_NAME", "__version__"]

trackwright/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m trackwright`` is the same as the ``trackwright`` executable."""
+
+import sys
+
+from trackwright.cli import main
+
+sys.exit(main())

trackwright/bridge.py

@@ -0,0 +1,323 @@
+"""Bridge daemon and its local IPC client.
+
+The bridge is a long-running process that owns the virtual MIDI ports and the
+:class:`~trackwright.host.HostClient`. MCP servers (one per client session) talk to it over a
+Unix domain socket in a private per-user directory (mode 0700, socket 0600). No network port is
+ever opened.
+
+IPC: one JSON line per connection, at most 64 KiB::
+
+    request:  {"op": str, "p": {...}, "timeout": 0.05..30}
+    response: {"ok": true, "result": {...}, "meta": {...}}
+              {"ok": false, "error": {"code": str, "message": str, "details": {...}}}
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import socket
+import socketserver
+import stat
+import threading
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Protocol
+
+from loguru import logger
+
+from trackwright.config import BridgeConfig
+from trackwright.errors import (
+    BridgeUnavailableError,
+    ProtocolError,
+    RequestTimeoutError,
+    TrackwrightError,
+)
+from trackwright.host import Reply
+from trackwright.ops import ALL_OPS, WRITE_OPS
+from trackwright.transport import Transport
+
+MAX_LINE = 64 * 1024
+MIN_TIMEOUT = 0.05
+MAX_TIMEOUT = 30.0
+LOCAL_OPS = frozenset({"bridge.status"})
+JsonObject = dict[str, Any]
+
+
+class HostBackend(Protocol):
+    """The part of :class:`~trackwright.host.HostClient` the bridge needs (a fake in tests)."""
+
+    session_id: str | None
+
+    def call(self, op: str, params: JsonObject | None = None, *, timeout: float | None = None) -> Reply: ...
+
+    def stats(self) -> JsonObject: ...
+
+
+# ---------------------------------------------------------------------------- validation
+def validate_request(obj: object) -> tuple[str, JsonObject, float]:
+    """Validate one IPC request; return ``(op, params, timeout)``."""
+    if not isinstance(obj, dict):
+        raise ProtocolError("IPC request must be a JSON object")
+    op = obj.get("op")
+    if not isinstance(op, str) or (op not in ALL_OPS and op not in LOCAL_OPS):
+        raise ProtocolError(f"operation not allowed: {op!r}")
+    params = obj.get("p") or {}
+    if not isinstance(params, dict):
+        raise ProtocolError("'p' must be a JSON object")
+    timeout = obj.get("timeout", 3.0)
+    if isinstance(timeout, bool) or not isinstance(timeout, int | float) or not MIN_TIMEOUT <= timeout <= MAX_TIMEOUT:
+        raise ProtocolError(f"timeout must be a number within [{MIN_TIMEOUT}, {MAX_TIMEOUT}] seconds")
+    return op, params, float(timeout)
+
+
+# ---------------------------------------------------------------------------- socket directory
+def prepare_socket_dir(directory: Path) -> Path:
+    """Create the private socket directory (0700) and refuse it if another user could use it."""
+    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    info = directory.stat()
+    if info.st_uid != os.getuid():
+        raise BridgeUnavailableError(f"socket directory {directory} belongs to another user")
+    if stat.S_IMODE(info.st_mode) & 0o077:
+        directory.chmod(0o700)
+        if stat.S_IMODE(directory.stat().st_mode) & 0o077:
+            raise BridgeUnavailableError(f"cannot make {directory} private (mode 0700)")
+    return directory
+
+
+def _socket_is_alive(path: Path) -> bool:
+    try:
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as probe:
+            probe.settimeout(0.5)
+            probe.connect(str(path))
+    except ConnectionRefusedError, FileNotFoundError, TimeoutError, OSError:
+        return False
+    return True
+
+
+# ---------------------------------------------------------------------------- daemon
+class Bridge:
+    """Request dispatcher, independent of sockets so it can be unit tested."""
+
+    def __init__(self, host: HostBackend) -> None:
+        self.host = host
+        self.started_at = time.time()
+        self.requests = 0
+        self.errors = 0
+
+    def status(self) -> JsonObject:
+        return {
+            "pid": os.getpid(),
+            "uptime_s": round(time.time() - self.started_at, 1),
+            "requests": self.requests,
+            "errors": self.errors,
+            "host": self.host.stats(),
+        }
+
+    def handle(self, obj: object) -> JsonObject:
+        self.requests += 1
+        started = time.monotonic()
+        try:
+            op, params, timeout = validate_request(obj)
+            if op == "bridge.status":
+                return {"ok": True, "result": self.status()}
+            reply = self.host.call(op, params, timeout=timeout)
+        except TrackwrightError as exc:
+            self.errors += 1
+            logger.debug("request failed: {}", exc)
+            return {"ok": False, "error": exc.to_dict(), "meta": self._meta(started)}
+        except Exception as exc:
+            self.errors += 1
+            logger.exception("unexpected error handling {}", obj)
+            op_name = obj.get("op") if isinstance(obj, dict) else None
+            outcome = "unknown" if op_name in WRITE_OPS else "not_executed_or_lost"
+            error = TrackwrightError(
+                f"internal bridge error: {exc}", code="INTERNAL_ERROR", details={"op": op_name, "outcome": outcome}
+            )
+            return {"ok": False, "error": error.to_dict(), "meta": self._meta(started)}
+        logger.debug("{} ok in {:.1f} ms (via {})", op, reply.duration_ms, reply.via)
+        meta = self._meta(started) | {"rid": reply.rid, "via": reply.via, "duplicate": reply.duplicate}
+        return {"ok": True, "result": reply.result, "meta": meta}
+
+    def _meta(self, started: float) -> JsonObject:
+        return {"duration_ms": round((time.monotonic() - started) * 1000, 2), "session_id": self.host.session_id}
+
+
+class _Handler(socketserver.StreamRequestHandler):
+    bridge: Bridge
+
+    def handle(self) -> None:
+        line = self.rfile.readline(MAX_LINE + 1)
+        if not line:
+            return  # a liveness probe: connected and closed without a request
+        if len(line) > MAX_LINE:
+            response: JsonObject = {"ok": False, "error": ProtocolError("IPC line too long").to_dict()}
+        else:
+            try:
+                response = self.bridge.handle(json.loads(line))
+            except ValueError as exc:
+                response = {"ok": False, "error": ProtocolError(f"invalid JSON: {exc}").to_dict()}
+        try:
+            self.wfile.write((json.dumps(response) + "\n").encode())
+        except BrokenPipeError:
+            logger.warning("IPC client disconnected before the response")
+
+
+class BridgeServer:
+    """Unix socket server around a :class:`Bridge`."""
+
+    def __init__(self, bridge: Bridge, socket_path: Path) -> None:
+        self.bridge = bridge
+        self.socket_path = socket_path
+        self._server: socketserver.ThreadingUnixStreamServer | None = None
+
+    def start(self) -> None:
+        prepare_socket_dir(self.socket_path.parent)
+        if self.socket_path.exists():
+            if _socket_is_alive(self.socket_path):
+                raise BridgeUnavailableError(f"another bridge is already listening on {self.socket_path}")
+            self.socket_path.unlink()
+        handler = type("BoundHandler", (_Handler,), {"bridge": self.bridge})
+        previous = os.umask(0o077)
+        try:
+            self._server = socketserver.ThreadingUnixStreamServer(str(self.socket_path), handler)
+        finally:
+            os.umask(previous)
+        self._server.daemon_threads = True
+        self.socket_path.chmod(0o600)
+        logger.info("bridge listening on {}", self.socket_path)
+
+    def serve_forever(self) -> None:
+        if self._server is None:
+            self.start()
+        assert self._server is not None
+        self._server.serve_forever(poll_interval=0.2)
+
+    def serve_in_thread(self) -> threading.Thread:
+        """Start serving in a daemon thread (used by tests)."""
+        if self._server is None:
+            self.start()
+        thread = threading.Thread(target=self.serve_forever, name="trackwright-bridge", daemon=True)
+        thread.start()
+        return thread
+
+    def stop(self) -> None:
+        if self._server is not None:
+            self._server.shutdown()
+            self._server.server_close()
+            self._server = None
+        self.socket_path.unlink(missing_ok=True)
+        logger.info("bridge stopped")
+
+
+# ---------------------------------------------------------------------------- client
+def error_from_dict(error: JsonObject) -> TrackwrightError:
+    from trackwright import errors as module  # noqa: PLC0415 - small local lookup table
+
+    code = str(error.get("code", "BRIDGE_ERROR"))
+    message = str(error.get("message", ""))
+    details = error.get("details") if isinstance(error.get("details"), dict) else None
+    if code == "TIMEOUT":
+        outcome_unknown = bool(details and details.get("outcome") == "unknown")
+        return RequestTimeoutError(message, outcome_unknown=outcome_unknown, details=details)
+    if code == "STALE_SESSION":
+        return module.StaleSessionError(message, details=details)
+    return TrackwrightError(message, code=code, details=details)
+
+
+class BridgeClient:
+    """Client used by the MCP server and the CLI to reach the bridge."""
+
+    def __init__(self, socket_path: Path, *, connect: Callable[[], socket.socket] | None = None) -> None:
+        self.socket_path = socket_path
+        self._connect = connect or (lambda: socket.socket(socket.AF_UNIX, socket.SOCK_STREAM))
+
+    def request(self, op: str, params: JsonObject | None = None, *, timeout: float = 3.0) -> JsonObject:
+        """Send one request; return the full response (``ok``, ``result`` or ``error``, ``meta``)."""
+        line = json.dumps({"op": op, "p": params or {}, "timeout": timeout}) + "\n"
+        buffer = b""
+        try:
+            with self._connect() as sock:
+                sock.settimeout(timeout + 2.0)
+                sock.connect(str(self.socket_path))
+                sock.sendall(line.encode())
+                while not buffer.endswith(b"\n"):
+                    chunk = sock.recv(65536)
+                    if not chunk:
+                        break
+                    buffer += chunk
+        except FileNotFoundError as exc:
+            raise BridgeUnavailableError(
+                f"bridge socket not found at {self.socket_path}: start it with 'trackwright bridge'",
+                details={"sent": False},
+            ) from exc
+        except ConnectionRefusedError as exc:
+            raise BridgeUnavailableError(
+                f"bridge is not accepting connections at {self.socket_path}", details={"sent": False}
+            ) from exc
+        except TimeoutError as exc:
+            raise RequestTimeoutError(
+                f"no answer from the bridge for {op}", outcome_unknown=True, details={"op": op}
+            ) from exc
+        if not buffer:
+            raise BridgeUnavailableError("the bridge closed the connection without answering")
+        try:
+            response = json.loads(buffer)
+        except ValueError as exc:
+            raise ProtocolError(f"invalid response from the bridge: {exc}") from exc
+        if not isinstance(response, dict):
+            raise ProtocolError("the bridge response is not a JSON object")
+        return response
+
+    def call(self, op: str, params: JsonObject | None = None, *, timeout: float = 3.0) -> JsonObject:
+        """Like :meth:`request` but return ``result`` or raise the error it carries."""
+        response = self.request(op, params, timeout=timeout)
+        if not response.get("ok"):
+            error = response.get("error")
+            raise error_from_dict(error if isinstance(error, dict) else {})
+        result = response.get("result")
+        return result if isinstance(result, dict) else {}
+
+
+# ---------------------------------------------------------------------------- entry point
+def make_transport(settings: BridgeConfig, *, system: str | None = None) -> Transport:
+    """The configured MIDI transport (TW-1302): CoreMIDI through ctypes on macOS by default."""
+    backend = settings.backend
+    if backend == "auto":
+        backend = "coremidi" if (system or platform.system()) == "Darwin" else "rtmidi"
+    if backend == "coremidi":
+        from trackwright.coremidi import CoreMidiTransport  # noqa: PLC0415
+
+        return CoreMidiTransport(settings.to_cubase_port, settings.from_cubase_port)
+    from trackwright.transport import MidiTransport  # noqa: PLC0415 - needs mido + python-rtmidi installed
+
+    return MidiTransport(settings.to_cubase_port, settings.from_cubase_port)
+
+
+def run_bridge(
+    settings: BridgeConfig, *, transport: Transport | None = None, stop: threading.Event | None = None
+) -> None:
+    """Run the bridge until ``stop`` is set or SIGINT/SIGTERM arrives."""
+    import signal  # noqa: PLC0415 - only needed by the daemon
+
+    from trackwright.host import HostClient  # noqa: PLC0415
+
+    stop_event = stop or threading.Event()
+    host = HostClient(
+        transport or make_transport(settings),
+        default_timeout=settings.request_timeout,
+    )
+    host.open()
+    server = BridgeServer(Bridge(host), settings.socket_path)
+    try:
+        server.serve_in_thread()
+        if threading.current_thread() is threading.main_thread():
+            for signum in (signal.SIGINT, signal.SIGTERM):
+                signal.signal(signum, lambda *_: stop_event.set())
+        logger.info("bridge ready; waiting for Cubase on '{}'", settings.to_cubase_port)
+        stop_event.wait()
+    finally:
+        server.stop()
+        host.close()

trackwright/cli.py

@@ -0,0 +1,203 @@
+"""Command line entry point: ``trackwright <command>``.
+
+Commands print JSON on stdout (so they can be scripted) and log to stderr. ``serve`` is the
+exception: stdout belongs to the MCP stdio protocol, so it prints nothing itself.
+Heavy modules are imported inside each handler to keep ``--help`` fast.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+from trackwright import __version__
+from trackwright.config import Settings, config_path, load_settings
+from trackwright.errors import TrackwrightError
+from trackwright.logs import configure_logging
+
+Handler = Callable[[argparse.Namespace, Settings], int]
+
+
+def emit(payload: Any) -> None:
+    """Print a JSON document on stdout."""
+    sys.stdout.write(json.dumps(payload, indent=2, ensure_ascii=False, default=str) + "\n")
+
+
+def cmd_version(_args: argparse.Namespace, _settings: Settings) -> int:
+    emit({"trackwright": __version__})
+    return 0
+
+
+def cmd_config(_args: argparse.Namespace, settings: Settings) -> int:
+    data = settings.model_dump(mode="json")
+    data["bridge"]["socket_path"] = str(settings.bridge.socket_path)
+    emit(data)
+    return 0
+
+
+def cmd_bridge(_args: argparse.Namespace, settings: Settings) -> int:
+    from trackwright.bridge import run_bridge  # noqa: PLC0415
+
+    run_bridge(settings.bridge)
+    return 0
+
+
+def cmd_bridge_status(_args: argparse.Namespace, settings: Settings) -> int:
+    from trackwright.bridge import BridgeClient  # noqa: PLC0415
+
+    emit(BridgeClient(settings.bridge.socket_path).call("bridge.status", timeout=settings.bridge.request_timeout))
+    return 0
+
+
+def cmd_ping(args: argparse.Namespace, settings: Settings) -> int:
+    from trackwright.bridge import BridgeClient  # noqa: PLC0415
+
+    client = BridgeClient(settings.bridge.socket_path)
+    timeout = settings.bridge.request_timeout
+    hello = client.call("hello", timeout=timeout)
+    pong = client.request("ping", {"echo": args.echo}, timeout=timeout)
+    emit({"ok": bool(pong.get("ok")), "hello": hello, "ping": pong})
+    return 0 if pong.get("ok") else 1
+
+
+def cmd_script(args: argparse.Namespace, settings: Settings) -> int:
+    from trackwright.cubase import SCRIPT_PATH, install_script, script_status  # noqa: PLC0415
+
+    install_dir = args.dir or settings.script.install_dir
+    source = args.file.resolve() if args.file else SCRIPT_PATH
+    if args.action == "status":
+        emit(script_status(install_dir, source).to_dict())
+        return 0
+    status, written = install_script(install_dir, apply=args.apply, source=source)
+    payload = {**status.to_dict(), "written": written, "dry_run": not args.apply}
+    if not args.apply and status.state != "up_to_date":
+        payload["next_step"] = "re-run with --apply to copy the script, then restart Cubase"
+    elif written:
+        payload["next_step"] = "restart Cubase (it does not reload changed scripts by itself)"
+    emit(payload)
+    return 0
+
+
+def make_service(settings: Settings, *, simulate: bool) -> Any:
+    """The Cubase service backed by the bridge, or by the simulator with ``simulate``."""
+    from trackwright.core.policy import WritePolicy  # noqa: PLC0415
+    from trackwright.core.service import CubaseService  # noqa: PLC0415
+
+    policy = WritePolicy.from_config(settings.writes)
+    if simulate:
+        from trackwright.fake import FakeCubase, FakeExports, FakeLauncher  # noqa: PLC0415
+
+        cubase = FakeCubase()
+        return CubaseService(cubase, policy, launcher=FakeLauncher(cubase), exports=FakeExports())  # type: ignore[arg-type]
+    from trackwright.bridge import BridgeClient  # noqa: PLC0415
+    from trackwright.hostport import BridgeHost  # noqa: PLC0415
+    from trackwright.launcher import BridgeLauncher, CubaseLauncher  # noqa: PLC0415
+
+    bridge_launcher = BridgeLauncher(settings.bridge, config_path=settings.source)
+    host = BridgeHost(
+        BridgeClient(settings.bridge.socket_path),
+        read_timeout=settings.bridge.request_timeout,
+        write_timeout=settings.bridge.write_timeout,
+        ensure_bridge=bridge_launcher.ensure if settings.bridge.autostart else None,
+    )
+    return CubaseService(host, policy, launcher=CubaseLauncher(settings.cubase))
+
+
+def cmd_serve(args: argparse.Namespace, settings: Settings) -> int:
+    from trackwright.server import build_server  # noqa: PLC0415
+
+    server = build_server(make_service(settings, simulate=args.simulate))
+    logger.info("MCP server '{}' on stdio (simulate={})", server.name, args.simulate)
+    server.run(transport="stdio")
+    return 0
+
+
+def cmd_doctor(_args: argparse.Namespace, settings: Settings) -> int:
+    """Check every link of the chain and say what to do next."""
+    from trackwright.doctor import run_doctor  # noqa: PLC0415
+
+    report = run_doctor(settings)
+    emit(report)
+    return 0 if report["ok"] else 1
+
+
+def cmd_setup(args: argparse.Namespace, settings: Settings) -> int:
+    """Guided installation (TW-1301): every step is shown and confirmed before it is applied."""
+    from trackwright.installer import ConsolePrompter, Setup  # noqa: PLC0415
+
+    config_file, _explicit = config_path(args.config)
+    result = Setup(
+        settings, config_file, ConsolePrompter(), assume_yes=args.yes, writes=args.writes, save=args.save
+    ).run()
+    emit(result)
+    return 0 if result["ok"] else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="trackwright", description="Trackwright: MCP server for Cubase.")
+    parser.add_argument("--config", type=Path, help="configuration file (default: $TRACKWRIGHT_CONFIG or ~/.config)")
+    parser.add_argument("--log-level", help="override the configured log level")
+    sub = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+    sub.add_parser("version", help="print the version").set_defaults(handler=cmd_version)
+    sub.add_parser("config", help="print the effective configuration").set_defaults(handler=cmd_config)
+    sub.add_parser("bridge", help="run the bridge daemon (keep it running)").set_defaults(handler=cmd_bridge)
+    sub.add_parser("bridge-status", help="show the bridge status").set_defaults(handler=cmd_bridge_status)
+    serve = sub.add_parser("serve", help="run the MCP server on stdio (started by the MCP client)")
+    serve.add_argument("--simulate", action="store_true", help="answer from the built-in Cubase simulator")
+    serve.set_defaults(handler=cmd_serve)
+    sub.add_parser("doctor", help="diagnose the whole chain and suggest fixes").set_defaults(handler=cmd_doctor)
+    setup = sub.add_parser("setup", help="guided installation: Cubase script, configuration, Claude Code, doctor")
+    setup.add_argument(
+        "--yes",
+        action="append",
+        default=[],
+        choices=["script", "config", "claude"],
+        metavar="STEP",
+        help="apply STEP (script, config or claude) without asking; repeat it for several steps",
+    )
+    setup.add_argument(
+        "--writes", action=argparse.BooleanOptionalAction, help="new configuration: allow writes (default: ask; no)"
+    )
+    setup.add_argument(
+        "--save", action=argparse.BooleanOptionalAction, help="new configuration: allow saving (default: ask; no)"
+    )
+    setup.set_defaults(handler=cmd_setup)
+    script = sub.add_parser("script", help="install or check the Cubase MIDI Remote script")
+    script.add_argument("action", choices=["status", "install"])
+    script.add_argument("--dir", type=Path, help="override [script] install_dir")
+    script.add_argument("--apply", action="store_true", help="really copy the file (default: dry run)")
+    script.add_argument("--file", type=Path, help="install this script instead of the packaged one (experiments)")
+    script.set_defaults(handler=cmd_script)
+    ping = sub.add_parser("ping", help="check the round trip Python -> Cubase -> Python")
+    ping.add_argument("--echo", default="hola-ñ-✓", help="text echoed back by the script")
+    ping.set_defaults(handler=cmd_ping)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        settings = load_settings(args.config, missing_ok=args.command == "setup")
+    except TrackwrightError as exc:
+        configure_logging("INFO")
+        logger.error("{}", exc)
+        emit({"ok": False, "error": exc.to_dict()})
+        return 2
+    configure_logging(args.log_level or settings.logging.level, settings.logging.file)
+    handler: Handler = args.handler
+    try:
+        return handler(args, settings)
+    except TrackwrightError as exc:
+        logger.error("{}", exc)
+        emit({"ok": False, "error": exc.to_dict()})
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())