runtime-sdk 0.4.49__py3-none-win_arm64.whl

runtime_sdk/computers.py

@@ -0,0 +1,578 @@
+from __future__ import annotations
+
+import argparse
+import difflib
+import sys
+import time
+from typing import Any, Callable
+from urllib.parse import urlparse
+
+from runtime_sdk import arguments, output as cli_output, terminal
+from runtime_sdk.auth import authenticated_client
+from runtime_sdk.client import RuntimeAPIError, RuntimeClient
+from runtime_sdk.config import RuntimeConfig
+
+
+def close_matches(ref: str, candidates: list[str], limit: int = 3) -> list[str]:
+    """Return up to `limit` candidates that look similar to ref."""
+    ref = (ref or "").strip()
+    if not ref:
+        return []
+    pool = [c for c in candidates if c]
+    return difflib.get_close_matches(ref, pool, n=limit, cutoff=0.4)
+
+
+def computer_power_state(c: dict[str, Any]) -> str:
+    power = c.get("power_state")
+    if power is not None:
+        return str(power or "?")
+    status = str(c.get("status") or "?")
+    if status in ("warm", "cold"):
+        return status
+    if status == "deleted":
+        return "cold"
+    return "warm"
+
+
+def computer_internal_status(c: dict[str, Any]) -> str:
+    internal = c.get("internal_status")
+    if internal is not None:
+        return str(internal or "?")
+    return str(c.get("status") or "?")
+
+
+def computer_status_label(c: dict[str, Any]) -> str:
+    power = computer_power_state(c)
+    internal = computer_internal_status(c)
+    if power == internal:
+        return power
+    if power == "warm" and internal == "running":
+        return power
+    if internal in {"creating", "archiving", "restoring", "orphaned"}:
+        return internal
+    return power
+
+
+def _computer_matches_ref(c: dict[str, Any], ref: str) -> bool:
+    ref = ref.strip()
+    if not ref:
+        return False
+
+    candidates = {
+        str(c.get("id") or "").strip(),
+        str(c.get("slug") or "").strip(),
+        str(c.get("hostname") or "").strip(),
+        str(c.get("public_url") or "").strip(),
+    }
+
+    public_url = str(c.get("public_url") or "").strip()
+    if public_url:
+        parsed = urlparse(public_url)
+        if parsed.netloc:
+            candidates.add(parsed.netloc)
+            first_label = parsed.netloc.split(".", 1)[0].strip()
+            if first_label:
+                candidates.add(first_label)
+
+    return ref in {value for value in candidates if value}
+
+
+def resolve_computer_ref(client: RuntimeClient, ref: str) -> str:
+    ref = ref.strip()
+    if not ref:
+        raise RuntimeAPIError("computer id is required")
+    if ref.startswith("cmp_"):
+        return ref
+
+    try:
+        payload = client.list_computers()
+    except RuntimeAPIError:
+        return ref
+
+    computers = payload.get("computers") or []
+    if not isinstance(computers, list):
+        computers = []
+
+    matches = [
+        c for c in computers if isinstance(c, dict) and _computer_matches_ref(c, ref)
+    ]
+    if len(matches) == 1:
+        resolved = str(matches[0].get("id") or "").strip()
+        return resolved or ref
+    if len(matches) > 1:
+        raise RuntimeAPIError(
+            f"multiple computers matched {ref!r}; use the exact computer id"
+        )
+
+    slugs = [str(c.get("slug") or "").strip() for c in computers if isinstance(c, dict)]
+    suggestions = close_matches(ref, [s for s in slugs if s])
+    if suggestions:
+        hint = ", ".join(repr(s) for s in suggestions)
+        raise RuntimeAPIError(f"computer {ref!r} not found. Did you mean {hint}?")
+    raise RuntimeAPIError(f"computer {ref!r} not found")
+
+
+def _computer_name(c: dict[str, Any]) -> str:
+    return str(c.get("slug") or c.get("id") or "?")
+
+
+def _computer_email_address(c: dict[str, Any]) -> str:
+    explicit = str(c.get("email_address") or "").strip()
+    if explicit:
+        return explicit
+    slug = str(c.get("slug") or "").strip()
+    public_url = str(c.get("public_url") or "").strip()
+    if not slug or not public_url:
+        return ""
+    host = urlparse(public_url).netloc
+    if not host:
+        return ""
+    suffix = host.removeprefix(slug + ".")
+    if suffix == host or not suffix:
+        return ""
+    return f"{slug}@mail.{suffix}"
+
+
+def with_computer_email(payload: dict[str, Any]) -> dict[str, Any]:
+    if payload.get("email_address"):
+        return payload
+    email_address = _computer_email_address(payload)
+    if not email_address:
+        return payload
+    enriched = dict(payload)
+    enriched["email_address"] = email_address
+    return enriched
+
+
+def _computer_sort_key(c: dict[str, Any]) -> tuple[int, str, str]:
+    status = computer_status_label(c)
+    priority = 1
+    if "warm" in status or "running" in status:
+        priority = 0
+    elif "cold" in status:
+        priority = 1
+    elif "restoring" in status or "creating" in status:
+        priority = 2
+    else:
+        priority = 3
+    return (priority, _computer_name(c).lower(), str(c.get("id") or ""))
+
+
+def pick_computer(
+    config: RuntimeConfig,
+    prompt: str,
+    predicate: Callable[[dict[str, Any]], bool] | None = None,
+) -> dict[str, Any] | None:
+    client = authenticated_client(config)
+    payload = client.list_computers()
+    computers = payload.get("computers") or []
+    if not isinstance(computers, list):
+        computers = []
+    if predicate is not None:
+        computers = [c for c in computers if isinstance(c, dict) and predicate(c)]
+    computers = sorted(computers, key=_computer_sort_key)
+    if not computers:
+        print("no matching computers found", file=sys.stderr)
+        return None
+
+    for index, computer in enumerate(computers, start=1):
+        print(
+            f"{index}. {_computer_name(computer)} ({computer_status_label(computer)})"
+        )
+    selection = cli_output.prompt_text(f"{prompt} [1-{len(computers)}]")
+    if selection is None:
+        return None
+    try:
+        index = int(selection) - 1
+    except ValueError:
+        print("selection must be a number", file=sys.stderr)
+        return None
+    if index < 0 or index >= len(computers):
+        print("selection is out of range", file=sys.stderr)
+        return None
+    return computers[index]
+
+
+def required_computer_id(config: RuntimeConfig, computer_id: str | None) -> str | int:
+    if computer_id is not None:
+        return computer_id
+    if not cli_output.interactive():
+        return cli_output.report_error("computer id is required")
+    picked = pick_computer(config, "Pick a computer")
+    if picked is None:
+        return 0
+    value = str(picked.get("id") or picked.get("slug") or "").strip()
+    if not value:
+        return cli_output.report_error("computer is missing an id")
+    return value
+
+
+def handle_create(
+    config: RuntimeConfig,
+    name: str | None,
+    startup_command: str | None,
+    cwd: str | None,
+    port: int | None,
+    network_mode: str | None = None,
+    allowed_hosts: list[str] | None = None,
+) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+
+    if name is None and cli_output.interactive():
+        name = cli_output.prompt_text("Name your computer")
+
+    if startup_command is None and port is not None:
+        return cli_output.report_error(
+            "startup command is required when port is provided"
+        )
+    if startup_command is not None and port is None:
+        return cli_output.report_error(
+            "port is required when startup command is provided"
+        )
+    allowed_hosts = allowed_hosts or []
+    network_error = _validate_network_policy(
+        network_mode, allowed_hosts, allow_default=True
+    )
+    if network_error:
+        return cli_output.report_error(network_error)
+
+    client = authenticated_client(config)
+    try:
+        started_at = time.perf_counter()
+        create_args: dict[str, Any] = {
+            "slug": name,
+            "command": startup_command,
+            "cwd": cwd,
+            "port": port,
+        }
+        if network_mode is not None:
+            create_args["network_mode"] = network_mode
+            create_args["allowed_hosts"] = allowed_hosts
+        result = client.create_computer(**create_args)
+        result["creation_duration_ms"] = int(
+            round((time.perf_counter() - started_at) * 1000)
+        )
+    except RuntimeAPIError as exc:
+        if (
+            exc.status_code == 409
+            and (
+                "slug already in use" in str(exc)
+                or "computer name or email address already in use" in str(exc)
+            )
+            and name
+        ):
+            return cli_output.report_error(
+                f"computer name {name!r} is unavailable. Names are public URL slugs and VM email addresses; an active/cold computer or reserved email address already owns it.",
+                status_code=exc.status_code,
+            )
+        raise
+
+    result = with_computer_email(result)
+    code = cli_output.report_success(result)
+    if code != 0 or not cli_output.interactive():
+        return code
+
+    computer_id = result.get("id") or result.get("slug")
+    if not computer_id:
+        return code
+    return terminal.enter_computer(config, str(computer_id))
+
+
+def handle_network(config: RuntimeConfig, args: argparse.Namespace) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+    client = authenticated_client(config)
+    if args.network_action == "default":
+        action = args.network_default_action
+        if action == "show":
+            return cli_output.report_success(
+                {"network_policy": client.get_default_network()}
+            )
+        hosts = args.hosts if action == "allowlist" else []
+        return cli_output.report_success(
+            {"network_policy": client.set_default_network(action, hosts)}
+        )
+    if args.network_action == "show":
+        computer_id = required_computer_id(config, args.id)
+        if isinstance(computer_id, int):
+            return computer_id
+        computer_id = resolve_computer_ref(client, computer_id)
+        return cli_output.report_success(client.get_computer_network(computer_id))
+    if args.network_action == "denials":
+        computer_id = required_computer_id(config, args.id)
+        if isinstance(computer_id, int):
+            return computer_id
+        computer_id = resolve_computer_ref(client, computer_id)
+        return cli_output.report_success(client.list_network_denials(computer_id))
+    if args.network_action == "set":
+        error = _validate_network_policy(args.mode, args.hosts)
+        if error:
+            return cli_output.report_error(error)
+        computer_id = required_computer_id(config, args.id)
+        if isinstance(computer_id, int):
+            return computer_id
+        computer_id = resolve_computer_ref(client, computer_id)
+        return cli_output.report_success(
+            client.set_computer_network(computer_id, args.mode, args.hosts)
+        )
+    return cli_output.report_error("unknown network command")
+
+
+def _validate_network_policy(
+    mode: str | None, hosts: list[str], *, allow_default: bool = False
+) -> str | None:
+    if mode is None:
+        if hosts:
+            return "--allow-host requires --network allowlist"
+        return None if allow_default else "network mode is required"
+    if mode == "allowlist" and not hosts:
+        return "allowlist mode requires at least one host"
+    if mode != "allowlist" and hosts:
+        return "hosts can only be used with allowlist mode"
+    return None
+
+
+def handle_info(config: RuntimeConfig, computer_id: str | None) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+
+    if computer_id is None:
+        if not cli_output.interactive():
+            return cli_output.report_error("computer id is required")
+        picked = pick_computer(config, "Pick a computer")
+        if picked is None:
+            return 0
+        computer_id = picked.get("id") or picked.get("slug")
+        if not computer_id:
+            return cli_output.report_error("computer is missing an id")
+
+    client = authenticated_client(config)
+    computer_id = resolve_computer_ref(client, computer_id)
+    result = client.get_computer(computer_id)
+    return cli_output.report_success(result)
+
+
+def handle_url(config: RuntimeConfig, computer_id: str | None) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+
+    if computer_id is None:
+        if not cli_output.interactive():
+            return cli_output.report_error("computer id is required")
+        picked = pick_computer(config, "Pick a computer")
+        if picked is None:
+            return 0
+        computer_id = picked.get("id") or picked.get("slug")
+        if not computer_id:
+            return cli_output.report_error("computer is missing an id")
+
+    client = authenticated_client(config)
+    computer_id = resolve_computer_ref(client, computer_id)
+    result = client.get_computer_network(computer_id)
+    return cli_output.report_success(result)
+
+
+def handle_share(
+    config: RuntimeConfig, visibility: str | None, computer_id: str | None
+) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+    if visibility not in ("public", "private"):
+        return cli_output.report_error("share target must be public or private")
+
+    if computer_id is None:
+        if not cli_output.interactive():
+            return cli_output.report_error("computer id is required")
+        picked = pick_computer(config, "Pick a computer")
+        if picked is None:
+            return 0
+        computer_id = picked.get("id") or picked.get("slug")
+        if not computer_id:
+            return cli_output.report_error("computer is missing an id")
+
+    client = authenticated_client(config)
+    computer_id = resolve_computer_ref(client, computer_id)
+    result = client.set_visibility(computer_id, visibility)
+
+    return cli_output.report_success(result)
+
+
+def handle_start(config: RuntimeConfig, computer_id: str | None) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+
+    if computer_id is None:
+        if not cli_output.interactive():
+            return cli_output.report_error("computer id is required")
+        picked = pick_computer(
+            config,
+            "Pick a cold computer to wake",
+            lambda c: computer_power_state(c) == "cold",
+        )
+        if picked is None:
+            return 0
+        computer_id = picked.get("id") or picked.get("slug")
+        if not computer_id:
+            return cli_output.report_error("computer is missing an id")
+
+    client = authenticated_client(config)
+    computer_id = resolve_computer_ref(client, computer_id)
+    result = client.start_computer(computer_id)
+
+    return cli_output.report_success(result)
+
+
+def handle_enter(
+    config: RuntimeConfig,
+    computer_id: str | None,
+    command_parts: list[str] | None = None,
+) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+    if not cli_output.interactive():
+        return cli_output.report_error("enter requires an interactive terminal")
+
+    command = arguments.command_from_remainder(command_parts)
+
+    if computer_id is None:
+        picked = pick_computer(
+            config,
+            "Pick a computer to enter",
+            lambda c: computer_internal_status(c) in ("running", "cold"),
+        )
+        if picked is None:
+            return 0
+        computer_id = picked.get("id") or picked.get("slug")
+        if not computer_id:
+            return cli_output.report_error("computer is missing an id")
+
+    client = authenticated_client(config)
+    computer_id = resolve_computer_ref(client, str(computer_id))
+    if command:
+        return terminal.enter_computer(config, str(computer_id), command=command)
+    return terminal.enter_computer(config, str(computer_id))
+
+
+def handle_delete(
+    config: RuntimeConfig, computer_id: str | None, *, force: bool = False
+) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+
+    if computer_id is None:
+        if not cli_output.interactive():
+            return cli_output.report_error("computer id is required")
+        picked = pick_computer(config, "Pick a computer to delete")
+        if picked is None:
+            return 0
+        computer_id = picked.get("id") or picked.get("slug")
+        if not computer_id:
+            return cli_output.report_error("computer is missing an id")
+
+    # In TTY mode, require the user to retype the slug as confirmation
+    # unless --force was passed. Non-TTY callers stay script-friendly.
+    if cli_output.interactive() and not force:
+        if not cli_output.prompt_typed_confirm(
+            f"Delete {computer_id}? This permanently destroys filesystem, service, and public URL.",
+            str(computer_id),
+        ):
+            print("cancelled")
+            return 0
+
+    client = authenticated_client(config)
+    display_ref = computer_id
+    computer_id = resolve_computer_ref(client, computer_id)
+    client.delete_computer(computer_id)
+
+    return cli_output.report_success({"message": f"computer {display_ref} deleted"})
+
+
+def handle_run(
+    config: RuntimeConfig,
+    computer_id: str | None,
+    command: str | None,
+    uid: int | None,
+    gid: int | None,
+    cwd: str | None,
+    shell: str | None,
+) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+
+    if computer_id is None:
+        if not cli_output.interactive():
+            return cli_output.report_error("computer id is required")
+        picked = pick_computer(
+            config,
+            "Pick a computer",
+            lambda c: computer_internal_status(c) == "running",
+        )
+        if picked is None:
+            return 0
+        computer_id = picked.get("id") or picked.get("slug")
+        if not computer_id:
+            return cli_output.report_error("computer is missing an id")
+
+    if command is None:
+        if not cli_output.interactive():
+            return cli_output.report_error("command is required")
+        command = cli_output.prompt_text("Command to run")
+        if not command:
+            return cli_output.report_error("command is required")
+
+    client = authenticated_client(config)
+    computer_id = resolve_computer_ref(client, computer_id)
+    result = client.run_command(
+        computer_id, command, uid=uid, gid=gid, cwd=cwd, shell=shell
+    )
+    return cli_output.report_success(result)
+
+
+def handle_publish(
+    config: RuntimeConfig,
+    computer_id: str | None,
+    port: int | None,
+    command_parts: list[str] | None = None,
+) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+
+    if computer_id is None:
+        if not cli_output.interactive():
+            return cli_output.report_error("computer id is required")
+        picked = pick_computer(
+            config,
+            "Pick a computer",
+            lambda c: computer_internal_status(c) == "running",
+        )
+        if picked is None:
+            return 0
+        computer_id = picked.get("id") or picked.get("slug")
+        if not computer_id:
+            return cli_output.report_error("computer is missing an id")
+
+    if port is None:
+        if not cli_output.interactive():
+            return cli_output.report_error("port is required")
+        port_text = cli_output.prompt_text("Port to publish", default="3000")
+        if not port_text:
+            return cli_output.report_error("port is required")
+        try:
+            port = int(port_text)
+        except ValueError:
+            return cli_output.report_error("port must be a number")
+
+    if port <= 0 or port > 65535:
+        return cli_output.report_error("port must be between 1 and 65535")
+
+    command = arguments.command_from_remainder(command_parts)
+    if not command:
+        return cli_output.report_error(
+            f"publish requires -- <command...>, for example: runtime publish {computer_id} {port} -- npm run dev -- --host 0.0.0.0"
+        )
+
+    client = authenticated_client(config)
+    computer_id = resolve_computer_ref(client, computer_id)
+    result = client.publish_port(computer_id, port, command=command)
+    return cli_output.report_success(result)