contree-cli 0.2.3__py3-none-any.whl

contree_cli/__init__.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from contree_cli.client import ContreeClient
+    from contree_cli.config import ConfigProfile
+    from contree_cli.output import OutputFormatter
+    from contree_cli.session import SessionStore
+
+PROFILE: ContextVar[ConfigProfile] = ContextVar("PROFILE")
+CLIENT: ContextVar[ContreeClient] = ContextVar("CLIENT")
+FORMATTER: ContextVar[OutputFormatter] = ContextVar("FORMATTER")
+SESSION_STORE: ContextVar[SessionStore] = ContextVar("SESSION_STORE")
+IN_SHELL: ContextVar[bool] = ContextVar("IN_SHELL", default=False)
+
+
+class ArgumentsProtocol(Protocol):
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> ArgumentsProtocol: ...
+
+
+Handler = Callable[..., int | None]
+SetupResult = tuple[Handler, type[ArgumentsProtocol]]

contree_cli/__main__.py

@@ -0,0 +1,62 @@
+import contextvars
+import logging
+from collections.abc import Callable
+
+import contree_cli.config as config_mod
+from contree_cli import CLIENT, FORMATTER, PROFILE, SESSION_STORE, ArgumentsProtocol
+from contree_cli.arguments import parser
+from contree_cli.client import ApiError, ContreeClient
+from contree_cli.config import load_config
+from contree_cli.log import setup_logging
+from contree_cli.output import FORMATTERS
+from contree_cli.session import SessionStore, get_db_path, get_session_key
+
+log = logging.getLogger(__name__)
+
+
+def main() -> None:
+    args = parser.parse_args()
+    setup_logging(level=getattr(logging, args.log_level.upper(), logging.INFO))
+
+    config_mod.CONFIG_FILE = args.config_path
+    config_mod.CONFIG_DIR = args.config_path.parent
+
+    profile = load_config()
+
+    token = args.token or profile.token
+    url = args.url or profile.url
+    client = ContreeClient(url, token)
+
+    formatter = FORMATTERS[args.output_format]()
+
+    session_key = get_session_key(profile.name)
+    db_path = get_db_path()
+    store = SessionStore(db_path, session_key)
+
+    PROFILE.set(profile)
+    CLIENT.set(client)
+    FORMATTER.set(formatter)
+    SESSION_STORE.set(store)
+    ctx = contextvars.copy_context()
+
+    loader: type[ArgumentsProtocol] = args.load_args
+    handler: Callable[[ArgumentsProtocol], int | None] = args.handler
+
+    try:
+        exit_code = ctx.run(handler, loader.from_args(args))
+    except ApiError as exc:
+        log.error("%s", exc)
+        exit(1)
+    except KeyboardInterrupt:
+        log.error("User interrupted")
+        exit(1)
+    finally:
+        store.close()
+        formatter.flush()
+
+    exit(exit_code or 0)
+
+
+
+if __name__ == "__main__":
+    main()

contree_cli/arguments.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from contree_cli.cli import (
+    auth,
+    cat,
+    cd,
+    cp,
+    file,
+    images,
+    kill,
+    ls,
+    ps,
+    run,
+    session,
+    show,
+    tag,
+    use,
+)
+from contree_cli.config import CONFIG_FILE
+from contree_cli.output import FORMATTERS
+from contree_cli.shell import setup_parser as shell_setup_parser
+from contree_cli.types import (
+    COMMAND_REGISTRY,
+    ArgumentsFormatter,
+    SetupFn,
+    get_command_docs,
+)
+
+EPILOG = """\
+examples:
+  contree use tag:ubuntu:latest       set session image
+  eval $(contree use tag:ubuntu:latest)  set + export env var
+  contree run -- uname -a            run command in session image
+  contree run --shell -- 'echo hi'   shell mode
+  contree run --file ./app.py:/app.py --disposable -- python /app.py
+  contree images --prefix=ubuntu
+  contree ps -q
+  contree show OPERATION_UUID
+  contree tag IMAGE_UUID latest
+  contree ls /etc                    list files in session image
+  contree cat /etc/os-release        show file from session image
+  contree auth                       save token (secure prompt)
+  contree auth switch staging
+
+environment variables:
+  CONTREE_TOKEN      API bearer token (overrides config file)
+  CONTREE_URL        API base URL (overrides config file)
+  CONTREE_PROFILE    Active config profile (overrides config file)
+  CONTREE_SESSION    Explicit session name (for multi-terminal workflows)
+  CONTREE_SESSION_DB Path to session SQLite database
+"""
+
+DESCRIPTION = """\
+Contree CLI - command-line client for the Contree container platform.
+
+Run containers, manage images, inspect filesystems, and track operations
+through the Contree REST API (https://contree.dev).
+
+Authentication:
+  All API calls require a bearer token. Provide it via --token or set the
+  CONTREE_TOKEN environment variable. Tokens are issued per-project and
+  grant scoped permissions.
+
+  Use `contree auth --help` to configure persistent credentials.
+"""
+
+parser = argparse.ArgumentParser(
+    description=DESCRIPTION,
+    epilog=EPILOG,
+    formatter_class=ArgumentsFormatter,
+)
+parser.add_argument(
+    "--token", default=None, help="API token (overrides config and env)",
+)
+parser.add_argument(
+    "--url", default=None, help="API base URL (overrides config and env)",
+)
+
+parser.add_argument(
+    "-c", "--config",
+    type=Path,
+    default=CONFIG_FILE,
+    dest="config_path",
+    help="Config file path",
+)
+parser.add_argument(
+    "-L", "--log-level",
+    default="info",
+    choices=("debug", "info", "warning", "error", "critical"),
+    help="Logging level",
+)
+parser.add_argument(
+    "-f", "--format",
+    default="default",
+    choices=sorted(FORMATTERS),
+    dest="output_format",
+    help="Output format",
+)
+subparsers = parser.add_subparsers(dest="command", required=True)
+
+
+def register(
+    name: str, help: str,
+    setup_fn: SetupFn,
+    aliases: list[str] | None = None,
+) -> None:
+    aliases_list = aliases or []
+    COMMAND_REGISTRY.append((name, help, setup_fn, aliases_list))
+    description, epilog = get_command_docs(setup_fn)
+    p = subparsers.add_parser(
+        name, help=help,
+        aliases=aliases_list,
+        description=description,
+        epilog=epilog,
+        formatter_class=ArgumentsFormatter,
+    )
+    handler, loader = setup_fn(p)
+    p.set_defaults(handler=handler, load_args=loader)
+
+
+register("use", "Set or show current session image", use.setup_parser, aliases=["ci"])
+register("run", "Spawn a container instance", run.setup_parser)
+register("images", "List images", images.setup_parser, aliases=["img"])
+register("tag", "Tag an image", tag.setup_parser)
+register("ps", "List operations/instances", ps.setup_parser)
+register("kill", "Cancel an operation", kill.setup_parser)
+register("show", "Show operation result", show.setup_parser)
+register("ls", "List files in image", ls.setup_parser)
+register("cat", "Show file content from image", cat.setup_parser)
+register("cp", "Copy file from image to local path", cp.setup_parser)
+register("file", "Manage files in session image", file.setup_parser)
+register(
+    "session", "Manage session branches and history",
+    session.setup_parser, aliases=["s"],
+)
+register("auth", "Configure authentication", auth.setup_parser)
+register("cd", "Change working directory", cd.setup_parser)
+register("shell", "Interactive shell mode", shell_setup_parser)

contree_cli/cli/auth.py

@@ -0,0 +1,124 @@
+"""Configure authentication credentials.
+
+Validates a token against the API (GET /v1/whoami) and saves it to the
+config file under the specified profile. The token is prompted securely
+via getpass if --token is not provided.
+
+Subcommands:
+  profiles    List saved profiles (* marks active)
+  switch NAME Switch the active profile
+"""
+from __future__ import annotations
+
+import argparse
+import getpass
+import logging
+from dataclasses import dataclass
+
+from contree_cli import FORMATTER, ArgumentsProtocol, SetupResult
+from contree_cli.client import ApiError, ContreeClient
+from contree_cli.config import (
+    DEFAULT_URL,
+    list_profiles,
+    profile_exists,
+    save_profile,
+    switch_profile,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class AuthArgs(ArgumentsProtocol):
+    token: str
+    url: str = DEFAULT_URL
+    profile: str = "default"
+    force: bool = False
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> AuthArgs:
+        return cls(
+            token=ns.auth_token or getpass.getpass("Token: "),
+            url=ns.auth_url or DEFAULT_URL,
+            profile=ns.profile or "default",
+            force=ns.force,
+        )
+
+
+@dataclass(frozen=True)
+class ProfilesArgs(ArgumentsProtocol):
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> ProfilesArgs:
+        return cls()
+
+
+@dataclass(frozen=True)
+class SwitchArgs(ArgumentsProtocol):
+    profile_name: str
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> SwitchArgs:
+        return cls(profile_name=ns.profile_name)
+
+
+def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
+    p.add_argument("--token", dest="auth_token", help="API token (prompted if omitted)")
+    p.add_argument("--url", dest="auth_url", help="API base URL", default=DEFAULT_URL)
+    p.add_argument("--profile", help="Profile name", default="default")
+    p.add_argument(
+        "--force", action="store_true",
+        help="Overwrite existing profile without confirmation",
+    )
+
+    auth_sub = p.add_subparsers(dest="auth_action")
+
+    profiles_parser = auth_sub.add_parser(
+        "profiles", help="List saved profiles",
+    )
+    profiles_parser.set_defaults(
+        handler=cmd_profiles, load_args=ProfilesArgs,
+    )
+
+    switch_parser = auth_sub.add_parser(
+        "switch", help="Switch active profile",
+    )
+    switch_parser.set_defaults(handler=cmd_switch, load_args=SwitchArgs)
+    switch_parser.add_argument("profile_name", help="Profile to activate")
+    return cmd_auth, AuthArgs
+
+
+def cmd_auth(args: AuthArgs) -> int | None:
+    client = ContreeClient(args.url, args.token)
+    try:
+        client.get("/v1/whoami")
+    except ApiError as exc:
+        logger.error("Token verification failed: %s", exc)
+        return 1
+
+    if not args.force and profile_exists(args.profile):
+        answer = input(
+            f"Profile {args.profile!r} already exists."
+            " Overwrite? [y/N] ",
+        )
+        if answer.lower() != "y":
+            print("Aborted.")
+            return 1
+    save_profile(args.profile, args.token, args.url)
+    logger.info("Saved profile %r", args.profile)
+    return None
+
+
+def cmd_profiles(_: ProfilesArgs) -> None:
+    profiles = list_profiles()
+    logger.info("Configured profiles (* stands for active)")
+    if not profiles:
+        print("No profiles configured.")
+        return
+    formatter = FORMATTER.get()
+    for name, active in profiles:
+        formatter(name=name, active=active)
+
+
+def cmd_switch(args: SwitchArgs) -> None:
+    switch_profile(args.profile_name)
+    logger.info("Switched to profile %r", args.profile_name)

contree_cli/cli/cat.py

@@ -0,0 +1,74 @@
+"""Show file content from the session image.
+
+Downloads and displays a file from the current session image via the
+/inspect/ API without spawning an instance. Binary files are refused
+when stdout is a terminal — use shell redirection or `contree cp` to
+save them locally.
+
+Results are cached per (image, path) so repeated reads are instant.
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import logging
+import sys
+from dataclasses import dataclass
+from typing import cast
+
+from contree_cli import CLIENT, FORMATTER, SESSION_STORE, ArgumentsProtocol, SetupResult
+from contree_cli.client import resolve_image
+from contree_cli.output import DefaultFormatter
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class CatArgs(ArgumentsProtocol):
+    path: str
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> CatArgs:
+        return cls(path=ns.path)
+
+
+def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
+    p.add_argument("path", help="Path inside image")
+    return cmd_cat, CatArgs
+
+
+def cmd_cat(args: CatArgs) -> int | None:
+    client = CLIENT.get()
+    formatter = FORMATTER.get()
+    if not isinstance(formatter, DefaultFormatter):
+        logger.warning("cat always outputs raw content; --format is ignored")
+
+    store = SESSION_STORE.get()
+    image = store.current_image
+    path = store.resolve_path(args.path)
+    uuid = resolve_image(client, image)
+
+    cache_key = (uuid, f"download:{path}")
+    cached = store.cache.get(cache_key)
+    if cached is not None:
+        data = base64.b64decode(cast(str, cached))
+    else:
+        resp = client.get(f"/v1/inspect/{uuid}/download", params={"path": path})
+        data = resp.read()
+        store.cache[cache_key] = base64.b64encode(data).decode("ascii")
+
+    if not sys.stdout.isatty():
+        sys.stdout.buffer.write(data)
+        return None
+
+    try:
+        data.decode("utf-8")
+    except UnicodeDecodeError:
+        logger.error(
+            "Binary content - refusing to write to terminal. "
+            "Use shell redirection or `contree cp`.",
+        )
+        return 1
+
+    sys.stdout.buffer.write(data)
+    return None

contree_cli/cli/cd.py

@@ -0,0 +1,49 @@
+"""Change the working directory in the current session.
+
+Sets the session's cwd used by subsequent commands (run, ls, cat).
+Relative paths are resolved against the current cwd. Without an
+argument, prints the current working directory.
+
+Note: the path is not validated against the image filesystem — errors
+surface only when the next command uses the invalid cwd.
+"""
+from __future__ import annotations
+
+import argparse
+import posixpath
+from dataclasses import dataclass
+
+from contree_cli import SESSION_STORE, ArgumentsProtocol, SetupResult
+
+
+def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
+    p.add_argument("path", nargs="?", default=None, help="Target directory")
+    return cmd_cd, CdArgs
+
+
+@dataclass(frozen=True)
+class CdArgs(ArgumentsProtocol):
+    path: str | None
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> CdArgs:
+        return cls(path=ns.path)
+
+
+def cmd_cd(args: CdArgs) -> None:
+    store = SESSION_STORE.get()
+
+    if args.path is None:
+        cwd = store.get_cwd()
+        print(cwd or "/")
+        return
+
+    target = args.path
+    current = store.get_cwd() or "/"
+
+    if target.startswith("/"):
+        new_cwd = posixpath.normpath(target)
+    else:
+        new_cwd = posixpath.normpath(posixpath.join(current, target))
+
+    store.set_cwd(new_cwd)

contree_cli/cli/cp.py

@@ -0,0 +1,107 @@
+"""Copy a file from the session image to a local path.
+
+Downloads the file at PATH inside the current session image and writes
+it to DEST on the local filesystem. Progress is logged for large files.
+Unlike `cat`, this command handles binary content and does not require
+a terminal.
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from contree_cli import CLIENT, FORMATTER, SESSION_STORE, ArgumentsProtocol, SetupResult
+from contree_cli.client import resolve_image, stream_response
+from contree_cli.output import DefaultFormatter
+
+logger = logging.getLogger(__name__)
+
+LOG_INTERVAL = 5.0  # seconds between progress logs
+
+
+def fmt_size(n: int | float) -> str:
+    for unit in ("B", "KiB", "MiB", "GiB"):
+        if abs(n) < 1024:
+            return f"{n:.1f} {unit}"
+        n /= 1024
+    return f"{n:.1f} TiB"
+
+
+def fmt_duration(seconds: float) -> str:
+    if seconds < 60:
+        return f"{seconds:.0f}s"
+    minutes, secs = divmod(int(seconds), 60)
+    if minutes < 60:
+        return f"{minutes}m{secs:02d}s"
+    hours, minutes = divmod(minutes, 60)
+    return f"{hours}h{minutes:02d}m{secs:02d}s"
+
+
+@dataclass(frozen=True)
+class CpArgs(ArgumentsProtocol):
+    path: str
+    dest: str
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> CpArgs:
+        return cls(path=ns.path, dest=ns.dest)
+
+
+def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
+    p.add_argument("path", help="Path inside image")
+    p.add_argument("dest", help="Local destination path")
+    return cmd_cp, CpArgs
+
+
+def cmd_cp(args: CpArgs) -> int | None:
+    client = CLIENT.get()
+    formatter = FORMATTER.get()
+    if not isinstance(formatter, DefaultFormatter):
+        logger.warning("cp always outputs raw content; --format is ignored")
+
+    store = SESSION_STORE.get()
+    image = store.current_image
+    path = store.resolve_path(args.path)
+    uuid = resolve_image(client, image)
+    resp = client.get(f"/v1/inspect/{uuid}/download", params={"path": path})
+
+    total: int | None = None
+    cl = resp.getheader("Content-Length")
+    if cl is not None:
+        total = int(cl)
+
+    downloaded = 0
+    start = time.monotonic()
+    last_log = start
+
+    with Path(args.dest).open("wb") as f:
+        for chunk in stream_response(resp):
+            f.write(chunk)
+            downloaded += len(chunk)
+
+            now = time.monotonic()
+            if now - last_log >= LOG_INTERVAL:
+                last_log = now
+                elapsed = now - start
+                speed = downloaded / elapsed if elapsed > 0 else 0
+                parts = [f"{fmt_size(downloaded)} downloaded"]
+                if total:
+                    pct = downloaded / total * 100
+                    remaining = (
+                        (total - downloaded) / speed if speed > 0 else 0
+                    )
+                    parts.append(f"{pct:.0f}%")
+                    parts.append(f"ETA {fmt_duration(remaining)}")
+                parts.append(f"{fmt_size(speed)}/s")
+                logger.info("%s", " | ".join(parts))
+
+    elapsed = time.monotonic() - start
+    speed = downloaded / elapsed if elapsed > 0 else 0
+    logger.info(
+        "Written %s to %s (%s/s)",
+        fmt_size(downloaded), args.dest, fmt_size(speed),
+    )
+    return None