contree-cli 0.2.3__py3-none-any.whl

contree_cli/cli/run.py

@@ -0,0 +1,438 @@
+"""Spawn a container instance from the current session image and execute a command.
+
+Uses the image from the active session (set via `contree use IMAGE`).
+Commands are passed after -- separator; without --, the first
+positional arg is the command.
+
+By default the CLI polls until the operation reaches a terminal
+status (SUCCESS, FAILED, CANCELLED) and prints stdout/stderr.
+Use -d/--detach to exit immediately after spawning.
+
+File attachments:
+  Use --file to inject host files into the container before
+  execution. Files are uploaded to the API (with SHA256 dedup)
+  and mounted at the specified instance path. Ownership and
+  permissions default to the host file's stat unless overridden.
+
+  Note: non-disposable runs persist filesystem changes into a
+  new image. Files attached once are already part of that image
+  and do not need re-attachment. Use --disposable to discard
+  changes after execution.
+
+  Format: host_path[:instance_path][:uUID][:gGID][:mMODE]
+
+    host_path                             all defaults from stat
+    host_path:/inst/path                  point a destination path
+    host_path:m0755                       override only mode
+    host_path:/inst/path:u0:g0:m0755      all explicit
+    host_path:uroot:groot                 uid/gid by name (local)
+
+  Tagged options (u/g/m) can appear in any order after host_path.
+  instance_path is detected by its leading /.
+  Note: named uid/gid (e.g. uroot) are resolved locally via
+  pwd/grp — use numeric IDs if unsure about host/container mismatch.
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import logging
+import re
+import sys
+import time
+from dataclasses import dataclass, field
+from datetime import timedelta
+
+from contree_cli import CLIENT, FORMATTER, SESSION_STORE, ArgumentsProtocol, SetupResult
+from contree_cli.client import ApiError, ContreeClient, decode_stream, resolve_image
+from contree_cli.mapped_file import MappedFile
+from contree_cli.output import (
+    DefaultFormatter,
+    OutputFormatter,
+)
+
+logger = logging.getLogger(__name__)
+
+EPILOG = """\
+examples:
+  contree use ubuntu && contree run -- uname -a
+  contree run --shell -- 'echo hello && ls /'
+  contree run -e FOO=bar DEBUG=1 -- ./app
+  contree run --file ./app.py:/app.py --disposable -- python /app.py
+  contree run -d -- sleep 3600
+"""
+
+TERMINAL_STATUSES = frozenset({"SUCCESS", "FAILED", "CANCELLED"})
+
+# Escape sequences that corrupt the terminal when replayed from captured output.
+# Matches CSI sequences that are NOT SGR (colors end with 'm') — cursor movement,
+# screen clearing, mode set/reset, scroll regions, etc. Also matches RIS (\033c),
+# DEC cursor save/restore (\0337/\0338), and OSC sequences (title setting, etc.).
+_BREAKING_ESC_RE = re.compile(
+    r"\033\[\??[0-9;]*[ABCDEFGHJKSTfhlrsu]"  # CSI non-SGR
+    r"|\033c"                                  # RIS (full reset)
+    r"|\0337|\0338"                            # DEC cursor save/restore
+    r"|\033\][^\033\x07]*(?:\033\\|\x07)"      # OSC sequences
+)
+
+
+@dataclass(frozen=True)
+class RunArgs(ArgumentsProtocol):
+    command_args: list[str] = field(default_factory=list)
+    timeout: int | None = None
+    env: list[str] = field(default_factory=list)
+    hostname: str = "linuxkit"
+    disposable: bool = False
+    interpreter: bool = False
+    shell: bool = False
+    file: list[MappedFile] = field(default_factory=list)
+    truncate: int = 65536
+    detach: bool = False
+    cwd: str = ""
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> RunArgs:
+        raw = ns.command_args
+        if raw and raw[0] == "--":
+            raw = raw[1:]
+        return cls(
+            command_args=raw,
+            timeout=ns.timeout,
+            env=ns.env,
+            hostname=ns.hostname,
+            disposable=ns.disposable,
+            interpreter=ns.interpreter,
+            shell=ns.shell,
+            file=[MappedFile.parse(f) for f in ns.file],
+            truncate=ns.truncate,
+            detach=ns.detach,
+            cwd=ns.cwd,
+        )
+
+
+def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
+    p.add_argument(
+        "command_args", nargs=argparse.REMAINDER,
+        help="Command and arguments (after --)",
+    )
+    p.add_argument("-t", "--timeout", type=int, help="Timeout in seconds", default=120)
+    p.add_argument(
+        "-C", "--cwd", default="",
+        help=(
+            "Working directory inside container, absolute path "
+            "or empty string for use container WORKDIR"
+        )
+    )
+    p.add_argument(
+        "-e", "--env", action="append", default=[],
+        help="Environment variable KEY=VALUE (repeatable)",
+    )
+    p.add_argument(
+        "-H", "--hostname", default="linuxkit",
+        help="Container hostname",
+    )
+    p.add_argument(
+        "-D", "--disposable", action="store_true",
+        help="Drop filesystem changes after run",
+    )
+    p.add_argument(
+        "-I", "--interpreter", action="store_true",
+        help=(
+            "Interpreter (shebang) mode. Read the script file given "
+            "as the first argument, strip the #! line, and send the "
+            "body as stdin to /bin/sh -s. "
+            "Usage: #!/usr/bin/env -S contree run -I"
+        ),
+    )
+    p.add_argument(
+        "-s", "--shell", action="store_true",
+        help="Join command args into a single shell expression",
+    )
+    p.add_argument(
+        "-F", "--file", action="append", default=[], metavar="FILE",
+        help=(
+            "Attach file (repeatable). "
+            "Format: host[:inst_path][:uUID][:gGID][:mMODE]. "
+            "Tagged options (u/g/m) in any order; "
+            "uid/gid resolved locally from pwd/grp; defaults"
+            " from host stat."
+        ),
+    )
+    p.add_argument(
+        "-T", "--truncate", type=int, default=65536,
+        help="Truncate output to N bytes",
+    )
+    p.add_argument(
+        "-d", "--detach", "--no-wait",
+        action="store_true",
+        help="Exit immediately after spawning (do not wait for result)",
+    )
+    return cmd_run, RunArgs
+
+
+def _upload_file(
+    client: ContreeClient, mf: MappedFile,
+) -> str:
+    """Upload a host file and return its UUID, reusing if already present."""
+    try:
+        resp = client.get("/v1/files", params={"sha256": mf.sha256()})
+        uuid = json.loads(resp.read())["uuid"]
+        logger.info("File %s already uploaded (%s)", mf.host_path, uuid)
+        return str(uuid)
+    except ApiError as exc:
+        if exc.status != 404:
+            raise
+    with open(mf.host_path, "rb") as fh:
+        data = fh.read()
+    resp = client.request(
+        "POST", "/v1/files",
+        body=data,
+        headers={"Content-Type": "application/octet-stream"},
+    )
+    uuid = json.loads(resp.read())["uuid"]
+    logger.info("Uploaded %s (%s)", mf.host_path, uuid)
+    return str(uuid)
+
+
+def _build_payload(
+    args: RunArgs, image_uuid: str, uploaded: dict[str, str],
+) -> dict[str, object]:
+    """Build the JSON payload for POST /v1/instances."""
+    if args.shell:
+        command = " ".join(args.command_args)
+    else:
+        parts = args.command_args
+        command = parts[0] if parts else ""
+
+    payload: dict[str, object] = {
+        "image": image_uuid,
+        "command": command,
+        "shell": args.shell,
+        "disposable": args.disposable,
+        "hostname": args.hostname,
+        "truncate_output_at": args.truncate,
+    }
+
+    if not args.shell and len(args.command_args) > 1:
+        payload["args"] = args.command_args[1:]
+
+    if args.timeout is not None:
+        payload["timeout"] = args.timeout
+
+    if args.cwd:
+        payload["cwd"] = args.cwd
+
+    if args.env:
+        env_dict: dict[str, str] = {}
+        for item in args.env:
+            key, _, value = item.partition("=")
+            env_dict[key] = value
+        payload["env"] = env_dict
+
+    if uploaded:
+        files: dict[str, object] = {}
+        for mf in args.file:
+            file_uuid = uploaded[mf.host_path]
+            files[mf.instance_path] = {
+                "uuid": file_uuid,
+                "uid": mf.uid,
+                "gid": mf.gid,
+                "mode": f"{mf.mode:04o}",
+            }
+        payload["files"] = files
+
+    return payload
+
+
+def _display_operation(
+    op: dict[str, object], formatter: OutputFormatter,
+) -> None:
+    """Display an operation result using the given formatter."""
+    duration_raw = op.get("duration")
+    duration = (
+        timedelta(seconds=duration_raw)  # type: ignore[arg-type]
+        if duration_raw is not None
+        else None
+    )
+    result = op.get("result") or {}
+    assert isinstance(result, dict)
+    metadata = op.get("metadata") or {}
+    assert isinstance(metadata, dict)
+    instance_result = metadata.get("result") or {}
+    assert isinstance(instance_result, dict)
+
+    exit_code = None
+    state = instance_result.get("state") or {}
+    assert isinstance(state, dict)
+    if state:
+        exit_code = state.get("exit_code")
+
+    if formatter.STREAM:
+        formatter(
+            uuid=op["uuid"],
+            kind=op.get("kind", ""),
+            status=op["status"],
+            duration=duration,
+            exit_code=exit_code,
+            error=op.get("error") or "",
+            image=result.get("image") or "",
+            tag=result.get("tag") or "",
+            stdout=decode_stream(instance_result.get("stdout")),
+            stderr=decode_stream(instance_result.get("stderr")),
+        )
+        formatter.flush()
+        return
+
+    if not isinstance(formatter, DefaultFormatter):
+        raise RuntimeError(f"Unsupported formatter type: {type(formatter).__name__}, "
+                           "only json/json-pretty/default are supported")
+
+    # For DefaultFormatter, just only print stdout/stderr
+    stdout = _BREAKING_ESC_RE.sub("", decode_stream(instance_result.get("stdout")))
+    stderr = _BREAKING_ESC_RE.sub("", decode_stream(instance_result.get("stderr")))
+
+    if stdout:
+        sys.stdout.write(stdout)
+        if not stdout.endswith("\n"):
+            sys.stdout.write("\n")
+    if stderr:
+        sys.stderr.write(stderr)
+        if not stderr.endswith("\n"):
+            sys.stderr.write("\n")
+
+
+def cmd_run(args: RunArgs) -> int | None:
+    client = CLIENT.get()
+    formatter = FORMATTER.get()
+    store = SESSION_STORE.get()
+
+    # 1. Resolve image from active session
+    image_uuid = resolve_image(client, store.current_image)
+
+    # 2. Upload attached files
+    uploaded: dict[str, str] = {}
+    for mf in args.file:
+        uploaded[mf.host_path] = _upload_file(client, mf)
+
+    # 2b. Include pending files from session store
+    pending = store.pending_files()
+
+    # 3. Build and send spawn request
+    payload = _build_payload(args, image_uuid, uploaded)
+
+    # Merge pending files (explicit --file takes priority)
+    if pending:
+        files = payload.get("files", {})
+        assert isinstance(files, dict)
+        for pf in pending:
+            if pf.instance_path not in files:
+                files[pf.instance_path] = {
+                    "uuid": pf.file_uuid,
+                    "uid": pf.uid,
+                    "gid": pf.gid,
+                    "mode": pf.mode,
+                }
+                logger.info(
+                    "Including pending file %s (%s)",
+                    pf.instance_path, pf.file_uuid,
+                )
+        if files:
+            payload["files"] = files
+
+    # Interpreter mode (-I): read script file, strip shebang, send as stdin
+    if args.interpreter and args.command_args:
+        script_path = args.command_args[0]
+        logger.debug("Interpreter mode: reading %s", script_path)
+        with open(script_path, "rb") as f:
+            script_data = f.read()
+        # Strip shebang line
+        shebang_line, _, script_body = script_data.partition(b"\n")
+        logger.debug("Shebang line: %s", shebang_line.decode(errors="replace"))
+        if script_body:
+            payload["stdin"] = {
+                "value": base64.b64encode(script_body).decode(),
+                "encoding": "base64",
+            }
+            logger.debug("Script body: %d bytes", len(script_body))
+        payload["command"] = "/bin/sh"
+        payload["shell"] = True
+        extra_args = args.command_args[1:]
+        if extra_args:
+            payload["args"] = ["-s", "--", *extra_args]
+            logger.debug("Extra args: %s", extra_args)
+        else:
+            payload["args"] = ["-s"]
+
+    # Read piped stdin (skip if shebang already set it)
+    if "stdin" not in payload and not sys.stdin.isatty():
+        logger.debug("Reading piped stdin")
+        stdin_data = sys.stdin.buffer.read()
+        if stdin_data:
+            payload["stdin"] = {
+                "value": base64.b64encode(stdin_data).decode(),
+                "encoding": "base64",
+            }
+            logger.debug("Piped stdin: %d bytes", len(stdin_data))
+
+    resp = client.post_json("/v1/instances", payload)
+    op = json.loads(resp.read())
+    op_uuid: str = op["uuid"]
+
+    logger.info("Spawned operation %s", op_uuid)
+    # 4. Detach mode - exit immediately
+    if args.detach:
+        formatter(uuid=op_uuid, status=op.get("status", "PENDING"))
+        formatter.flush()
+        return None
+
+    # 5. Poll until terminal status
+    sleep_time = 0.5
+    try:
+        time.sleep(sleep_time)
+        sleep_time += sleep_time
+        while True:
+            resp = client.get(f"/v1/operations/{op_uuid}")
+            op = json.loads(resp.read())
+            if op["status"] in TERMINAL_STATUSES:
+                break
+            time.sleep(sleep_time)
+            if sleep_time < 5:
+                sleep_time += sleep_time
+    except KeyboardInterrupt:
+        try:
+            client.delete(f"/v1/operations/{op_uuid}")
+            logger.info("Cancelled operation %s", op_uuid)
+        except (ApiError, KeyboardInterrupt, OSError):
+            pass
+        raise
+
+    # 6. Cache terminal operation result
+    store.cache[(op_uuid, "operation")] = op
+
+    # 7. Display result
+    _display_operation(op, formatter)
+
+    result = op.get("result") or {}
+    assert isinstance(result, dict)
+    new_image = result.get("image")
+    if new_image and op["status"] == "SUCCESS":
+        logger.debug("New image: %s", new_image)
+        if not args.disposable:
+            title = " ".join(args.command_args) if args.command_args else ""
+            store.set_image(
+                str(new_image), kind="run", title=title,
+            )
+
+    metadata = op.get("metadata") or {}
+    assert isinstance(metadata, dict)
+    instance_result = metadata.get("result") or {}
+    assert isinstance(instance_result, dict)
+    state = instance_result.get("state") or {}
+    assert isinstance(state, dict)
+    exit_code = state.get("exit_code")
+    if isinstance(exit_code, int):
+        return exit_code
+    if op["status"] != "SUCCESS":
+        return 1
+    return None