contree-cli 0.2.3__py3-none-any.whl

contree_cli/cli/session.py

@@ -0,0 +1,282 @@
+"""Manage session branches and history.
+
+Without a subcommand, shows the current session info (key, branch,
+image, last operation).
+
+Subcommands:
+  list (ls)       List all sessions
+  use KEY         Import another session's current image
+  branch (br)     List or create branches (--from to fork)
+  checkout (co)   Switch active branch
+  rollback (rb)   Roll back N steps in history
+  show            Display the session history DAG
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from dataclasses import dataclass
+
+from contree_cli import FORMATTER, SESSION_STORE, ArgumentsProtocol, SetupResult
+from contree_cli.output import DefaultFormatter
+
+
+@dataclass(frozen=True)
+class SessionInfoArgs(ArgumentsProtocol):
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> SessionInfoArgs:
+        return cls()
+
+
+@dataclass(frozen=True)
+class ListArgs(ArgumentsProtocol):
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> ListArgs:
+        return cls()
+
+
+@dataclass(frozen=True)
+class UseSessionArgs(ArgumentsProtocol):
+    name: str
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> UseSessionArgs:
+        return cls(name=ns.session_name)
+
+
+@dataclass(frozen=True)
+class BranchArgs(ArgumentsProtocol):
+    name: str | None
+    from_branch: str | None
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> BranchArgs:
+        return cls(
+            name=getattr(ns, "branch_name", None),
+            from_branch=getattr(ns, "from_branch", None),
+        )
+
+
+@dataclass(frozen=True)
+class RollbackArgs(ArgumentsProtocol):
+    n: int
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> RollbackArgs:
+        return cls(n=ns.n)
+
+
+@dataclass(frozen=True)
+class CheckoutArgs(ArgumentsProtocol):
+    name: str
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> CheckoutArgs:
+        return cls(name=ns.checkout_branch)
+
+
+@dataclass(frozen=True)
+class ShowArgs(ArgumentsProtocol):
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> ShowArgs:
+        return cls()
+
+
+def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
+    sub = p.add_subparsers(dest="session_action")
+
+    # session list
+    list_p = sub.add_parser(
+        "list", aliases=["ls"],
+        help="List all sessions",
+    )
+    list_p.set_defaults(handler=cmd_list, load_args=ListArgs)
+
+    # session use SESSION
+    use_p = sub.add_parser("use", help="Import another session's image")
+    use_p.add_argument("session_name", help="Session key or suffix to match")
+    use_p.set_defaults(handler=cmd_use_session, load_args=UseSessionArgs)
+
+    # session branch [NAME] [--from BRANCH]
+    branch_p = sub.add_parser(
+        "branch", aliases=["br"],
+        help="List or create branches",
+    )
+    branch_p.add_argument(
+        "branch_name", nargs="?", default=None,
+        help="New branch name",
+    )
+    branch_p.add_argument(
+        "--from", dest="from_branch", default=None,
+        help="Source branch (default: active branch)",
+    )
+    branch_p.set_defaults(handler=cmd_branch, load_args=BranchArgs)
+
+    # session checkout BRANCH
+    co_p = sub.add_parser(
+        "checkout", aliases=["co"],
+        help="Switch active branch",
+    )
+    co_p.add_argument("checkout_branch", help="Branch to switch to")
+    co_p.set_defaults(
+        handler=cmd_checkout, load_args=CheckoutArgs,
+    )
+
+    # session rollback [N]
+    rollback_p = sub.add_parser(
+        "rollback", aliases=["rb"],
+        help="Roll back N steps",
+    )
+    rollback_p.add_argument(
+        "n", nargs="?", type=int, default=1,
+        help="Steps to rollback",
+    )
+    rollback_p.set_defaults(handler=cmd_rollback, load_args=RollbackArgs)
+
+    # session show
+    show_p = sub.add_parser("show", help="Show session history")
+    show_p.set_defaults(handler=cmd_show, load_args=ShowArgs)
+
+    return cmd_session_info, SessionInfoArgs
+
+
+def cmd_session_info(_: SessionInfoArgs) -> int | None:
+    store = SESSION_STORE.get()
+    session = store.session
+    if session is None:
+        print(
+            "No active session. Run `contree use IMAGE` to start one.",
+            file=sys.stderr,
+        )
+        return 1
+    formatter = FORMATTER.get()
+    formatter(
+        session_key=session.session_key,
+        active_branch=session.active_branch,
+        current_image=session.current_image,
+        last_kind=session.last_kind,
+        last_title=session.last_title,
+        updated_at=session.updated_at,
+    )
+    return None
+
+
+def cmd_list(_: ListArgs) -> int | None:
+    store = SESSION_STORE.get()
+    sessions = store.list_sessions()
+    if not sessions:
+        print("No sessions found.", file=sys.stderr)
+        return None
+    formatter = FORMATTER.get()
+    current_key = store.session_key
+    for s in sessions:
+        active = s.session_key == current_key
+        formatter(
+            active=active,
+            session_key=s.session_key,
+            active_branch=s.active_branch,
+            current_image=s.current_image,
+            updated_at=s.updated_at,
+        )
+    return None
+
+
+def cmd_use_session(args: UseSessionArgs) -> int | None:
+    store = SESSION_STORE.get()
+    try:
+        target = store.find_session(args.name)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    store.set_image(
+        target.current_image,
+        kind="session use",
+        title=target.session_key,
+    )
+    formatter = FORMATTER.get()
+    formatter(
+        image=target.current_image,
+        from_session=target.session_key,
+    )
+    return None
+
+
+def cmd_branch(args: BranchArgs) -> int | None:
+    store = SESSION_STORE.get()
+    if args.name is None:
+        # List branches
+        branches = store.list_branches()
+        if not branches:
+            print("No branches (no active session).", file=sys.stderr)
+            return None
+        formatter = FORMATTER.get()
+        for name, is_active in branches:
+            if isinstance(formatter, DefaultFormatter):
+                marker = "* " if is_active else "  "
+                formatter(marker=marker, branch=name)
+            else:
+                formatter(branch=name, active=is_active)
+        return None
+
+    # Create branch
+    try:
+        store.create_branch(args.name, args.from_branch)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(f"Created branch {args.name!r}")
+    return None
+
+
+def cmd_checkout(args: CheckoutArgs) -> int | None:
+    store = SESSION_STORE.get()
+    try:
+        entry = store.switch_branch(args.name)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    formatter = FORMATTER.get()
+    formatter(
+        branch=args.name,
+        image=entry.image_uuid,
+    )
+    return None
+
+
+def cmd_rollback(args: RollbackArgs) -> int | None:
+    store = SESSION_STORE.get()
+    try:
+        entry = store.rollback(args.n)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    formatter = FORMATTER.get()
+    formatter(
+        image=entry.image_uuid,
+        kind=entry.kind,
+        title=entry.title,
+        created_at=entry.created_at,
+    )
+    return None
+
+
+def cmd_show(_: ShowArgs) -> int | None:
+    store = SESSION_STORE.get()
+    entries, branch_map = store.history_dag()
+    if not entries:
+        print("No history.", file=sys.stderr)
+        return None
+
+    formatter = FORMATTER.get()
+    for entry in entries:
+        branches = branch_map.get(entry.id, [])
+        formatter(
+            id=entry.id,
+            image=entry.image_uuid,
+            parent_id=entry.parent_id,
+            kind=entry.kind,
+            title=entry.title,
+            created_at=entry.created_at,
+            branches=", ".join(branches) if branches else "",
+        )
+    return None

contree_cli/cli/show.py

@@ -0,0 +1,97 @@
+"""Show the result of an operation.
+
+Fetches the operation by UUID and displays its status, duration, exit
+code, result image, and captured stdout/stderr. Terminal operations
+(SUCCESS, FAILED, CANCELLED) are cached locally to avoid redundant API
+calls.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import Any, cast
+
+from contree_cli import CLIENT, FORMATTER, SESSION_STORE, ArgumentsProtocol, SetupResult
+from contree_cli.client import decode_stream
+from contree_cli.output import DefaultFormatter, JSONFormatter, JSONPrettyFormatter
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ShowArgs(ArgumentsProtocol):
+    uuid: str
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> ShowArgs:
+        return cls(uuid=ns.uuid)
+
+
+def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
+    p.add_argument("uuid", help="Operation UUID")
+    return cmd_show, ShowArgs
+
+
+_TERMINAL = frozenset({"SUCCESS", "FAILED", "CANCELLED"})
+
+
+def cmd_show(args: ShowArgs) -> None:
+    client = CLIENT.get()
+    formatter = FORMATTER.get()
+    store = SESSION_STORE.get()
+
+    cache_key = (args.uuid, "operation")
+    cached = store.cache.get(cache_key)
+    if cached is not None:
+        op = cast(dict[str, Any], cached)
+    else:
+        resp = client.get(f"/v1/operations/{args.uuid}")
+        op = json.loads(resp.read())
+        if op.get("status") in _TERMINAL:
+            store.cache[cache_key] = op
+
+    duration = (
+        timedelta(seconds=op["duration"])
+        if op.get("duration") is not None
+        else None
+    )
+    result = op.get("result") or {}
+    metadata = op.get("metadata") or {}
+    instance_result = metadata.get("result") or {}
+
+    exit_code = None
+    state = instance_result.get("state") or {}
+    if state:
+        exit_code = state.get("exit_code")
+
+    formatter(
+        uuid=op["uuid"],
+        kind=op["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 "",
+    )
+    formatter.flush()
+
+    _STREAM_FMTS = (DefaultFormatter, JSONFormatter, JSONPrettyFormatter)
+    if not isinstance(formatter, _STREAM_FMTS):
+        return
+
+    stdout = decode_stream(instance_result.get("stdout"))
+    stderr = 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")

contree_cli/cli/tag.py

@@ -0,0 +1,50 @@
+"""Assign or remove a tag from an image.
+
+Tags provide human-readable names for image UUIDs, making them easier
+to reference in commands like `contree use tag:NAME`.
+
+Use -d/--delete to remove a tag instead of assigning one.
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+from dataclasses import dataclass
+
+from contree_cli import CLIENT, ArgumentsProtocol, SetupResult
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class TagArgs(ArgumentsProtocol):
+    uuid: str
+    tag: str | None = None
+    delete: bool = False
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> TagArgs:
+        return cls(uuid=ns.uuid, tag=ns.tag, delete=ns.delete)
+
+
+def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
+    p.add_argument("uuid", help="Image UUID")
+    p.add_argument("tag", help="Tag to assign")
+    p.add_argument(
+        "-d", "--delete", action="store_true",
+        help="Remove tag from image",
+    )
+    return cmd_tag, TagArgs
+
+
+def cmd_tag(args: TagArgs) -> int | None:
+    client = CLIENT.get()
+
+    if args.delete:
+        client.delete(f"/v1/images/{args.uuid}/tag?tag={args.tag}")
+        logger.info("Removed tag from image %s", args.uuid)
+        return None
+
+    client.patch_json(f"/v1/images/{args.uuid}/tag", {"tag": args.tag})
+    logger.info("Tagged image %s as %s", args.uuid, args.tag)
+    return None

contree_cli/cli/use.py

@@ -0,0 +1,119 @@
+"""Set or show the current session image.
+
+With an IMAGE argument, resolves it (UUID or tag:NAME) and sets it as
+the active session image. Prints a shell export line so that the
+session key can be captured with eval:
+
+  eval $(contree use tag:ubuntu:latest)
+
+Without arguments, displays the current session info (image, branch,
+last operation).
+
+Use -N/--new to start a fresh session instead of resuming the current
+one. The new session key is printed as an export line.
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+import uuid
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from contree_cli import (
+    CLIENT,
+    FORMATTER,
+    IN_SHELL,
+    SESSION_STORE,
+    ArgumentsProtocol,
+    SetupResult,
+)
+from contree_cli.client import resolve_image
+from contree_cli.session import SessionStore, get_db_path
+
+log = logging.getLogger(__name__)
+
+
+def _shell_name() -> str:
+    return PurePosixPath(os.getenv("SHELL", "/bin/sh")).name
+
+
+def _print_shell_export(key: str, value: str) -> None:
+    if _shell_name() == "fish":
+        sys.stdout.write(f"set -gx {key} {value}\n")
+    else:
+        sys.stdout.write(f"export {key}={value}\n")
+
+
+@dataclass(frozen=True)
+class UseArgs(ArgumentsProtocol):
+    image: str | None
+    new: bool
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> UseArgs:
+        return cls(image=ns.image, new=ns.new)
+
+
+def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
+    p.add_argument("image", nargs="?", default=None, help="Image UUID or tag")
+    p.add_argument(
+        "--new", "-N", action="store_true", default=False,
+        help="Start a new session instead of resuming the current one",
+    )
+    return cmd_use, UseArgs
+
+
+def cmd_use(args: UseArgs) -> int | None:
+    store = SESSION_STORE.get()
+
+    if args.new:
+        if args.image is None:
+            print(
+                "--new requires an IMAGE argument.",
+                file=sys.stderr,
+            )
+            return 1
+        new_key = str(uuid.uuid4())
+        store = SessionStore(get_db_path(), new_key)
+        SESSION_STORE.set(store)
+
+    if args.image is not None:
+        client = CLIENT.get()
+        image_uuid = resolve_image(client, args.image)
+        store.set_image(image_uuid, kind="use", title=args.image)
+        if not IN_SHELL.get(False):
+            _print_shell_export("CONTREE_SESSION", store.session_key)
+            if args.new and sys.stdout.isatty():
+                if _shell_name() == "fish":
+                    eval_hint = "eval (contree use -N IMAGE)"
+                else:
+                    eval_hint = "eval $(contree use -N IMAGE)"
+                log.warning(
+                    "Session is not active until exported. "
+                    "Either paste the line above, or use: %s",
+                    eval_hint,
+                )
+        return None
+
+    session = store.session
+    if session is None:
+        print(
+            "No active session. Run `contree use IMAGE` to start one.",
+            file=sys.stderr,
+        )
+        return 1
+
+    formatter = FORMATTER.get()
+
+    formatter(
+        session_key=session.session_key,
+        active_branch=session.active_branch,
+        current_image=session.current_image,
+        last_kind=session.last_kind,
+        last_title=session.last_title,
+        updated_at=session.updated_at,
+    )
+    return None