contree-cli 0.5.1__tar.gz → 0.6.0__tar.gz

{contree_cli-0.5.1 → contree_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: contree-cli
-Version: 0.5.1
+Version: 0.6.0
 Summary: CLI client for the ConTree sandbox platform
 Keywords: sandbox,cli,vm,ai-agent,contree
 Author: Dmitry Orlov

{contree_cli-0.5.1 → contree_cli-0.6.0}/contree_cli/agent.md

@@ -134,7 +134,28 @@ Tag conventions:
 Always search before building:
   contree images --prefix=python-dev
 
-More: contree images --help, contree tag --help
+Building from a Dockerfile:
+  When a project already ships a Dockerfile, prefer `contree build`
+  over hand-running each step. It executes FROM/RUN/COPY/WORKDIR/ENV
+  /ARG/USER against the API and caches every layer as a branch so
+  rebuilds are fast.
+
+  Layer cache is keyed by abspath(context), shared across invocations:
+    contree build .                     build ./Dockerfile, no tag
+    contree build . --tag myapp:dev     build + tag the final image
+    contree build ./app --dockerfile ./app/Dockerfile.prod --tag svc:prod
+    contree build . --build-arg VERSION=1.2
+    contree build . --no-cache          force rebuild
+
+  Supported directives: FROM, RUN, COPY, ADD (local paths only),
+  WORKDIR, ENV, ARG, USER. CMD/ENTRYPOINT/LABEL/EXPOSE/VOLUME/etc.
+  are parsed but skipped with a warning. Multi-stage (AS / --from)
+  is not yet supported.
+
+  .dockerignore is applied to every COPY/ADD walk on top of the
+  default exclude list (.git, __pycache__, node_modules, etc.).
+
+More: contree build --help, contree images --help, contree tag --help
 
 Files and directories
 =====================
@@ -177,6 +198,32 @@ Pending files are injected into the next non-disposable run.
 Explicit --file takes priority over pending files at same path.
 Pending files are branch-aware.
 
+Listing uploaded files:
+  contree file ls                 list all uploaded files in the project
+  contree file ls --since 1d      narrow by upload time
+  contree file ls -q              uuid + sha256 + source only (quiet)
+  contree -f json file ls         JSON output for jq
+
+  Output joins remote files (uuid, sha256, size, created_at) with the
+  local upload cache. The SOURCE column shows whatever this machine
+  used to produce the file:
+    - absolute host path for files uploaded via `run --file` / `COPY`;
+    - https://... URL for files fetched via `ADD URL`.
+
+  IMPORTANT: SOURCE is resolved ONLY for files uploaded from this
+  specific machine. The mapping lives in the local SQLite cache (per
+  profile, under $CONTREE_HOME/cli/sessions/<profile>.db) keyed by
+  path+inode+mtime+size (for host paths) or by the URL itself (for
+  URL fetches), and is NOT shared between hosts. Rows show empty
+  SOURCE when:
+    - the file was uploaded from a different machine or by a teammate;
+    - the host file has been moved, renamed, or its inode/mtime/size
+      changed since upload (the cache key no longer matches);
+    - the upload happened before tracking landed (older entries
+      backfill on the next match).
+  An agent must not assume SOURCE is authoritative across hosts;
+  for cross-machine identity always use the remote UUID or sha256.
+
 More: contree run --help, contree file --help
 
 Execution modes
@@ -211,10 +258,31 @@ Piped stdin:
 Detached mode (-d):
   contree run -d -- long-running-task
   contree ps                              check status
+  contree ps -a -S FAILED --since=1h      recent failures
   contree show UUID                       view result
   contree session wait                    block until done
   contree session wait UUID1 UUID2        wait for specific ops
 
+Monitoring background operations:
+  Use the `operation` namespace (alias `op`) when juggling several
+  detached runs. `op ls` is `ps`; `op show` and `op cancel` accept
+  multiple UUIDs in one call.
+
+  contree op ls                           list operations (= ps)
+  contree op ls -a -S EXECUTING           filter active runs
+  contree op show UUID1 UUID2 UUID3       inspect a batch in one call
+  contree op cancel UUID1 UUID2           cancel selected operations
+  contree op cancel --all                 cancel every active op (rare)
+
+  Fan-out + join pattern:
+    A=$(contree run -d -- make -C /work/a build | jq -r .uuid)
+    B=$(contree run -d -- make -C /work/b build | jq -r .uuid)
+    contree session wait "$A" "$B"
+    contree op show "$A" "$B"
+
+  Background checks are cheap: terminal results are cached locally,
+  so repeated `op show` / `show` calls do not re-hit the API.
+
 Disposable mode (-D) — no image checkpoint:
   contree run -D -- rm -rf /tmp/*
   contree run -D -- cat /etc/passwd
@@ -352,11 +420,16 @@ All commands
 
   use [IMAGE]             Set or show session image (aliases: ci)
   run [-- CMD]            Spawn sandbox instance (aliases: r)
+  build [CONTEXT]         Build image from Dockerfile (aliases: bd)
   images                  List/import images (aliases: i, img)
   tag [IMAGE] TAG         Tag image (aliases: t)
   ps                      List operations
   kill UUID               Cancel operation
   show UUID               Show operation result
+  operation list          List operations (aliases: op ls)
+  operation show UUID...  Show one or more operation results (aliases: op)
+  operation cancel UUID...
+                          Cancel one or more operations (or --all)
   ls [PATH]               List files in image (no VM)
   cat PATH                Show file content (no VM)
   cp PATH DEST            Download file from image
@@ -364,6 +437,7 @@ All commands
   env [KEY=VALUE ...]     Session env vars (-d to unset)
   file edit PATH          Edit remote file via $EDITOR
   file cp SRC DEST        Stage local file for next run
+  file ls [-q]            List uploaded files + local path (aliases: list)
   session list            List sessions (aliases: ls)
   session branch [NAME]   Create/list branches (aliases: br)
   session checkout BRANCH Switch branch (aliases: co)

{contree_cli-0.5.1 → contree_cli-0.6.0}/contree_cli/arguments.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from contree_cli.cli import (
     agent,
     auth,
+    build,
     cat,
     cd,
     cp,
@@ -14,6 +15,7 @@ from contree_cli.cli import (
     images,
     kill,
     ls,
+    operation,
     ps,
     run,
     session,
@@ -44,6 +46,9 @@ examples:
   contree run --file ./src:/app/src -- make -C /app/src
   contree images --prefix=ubuntu
   contree ps -q
+  contree op ls                       same as `contree ps`
+  contree op show UUID1 UUID2         multi-UUID show
+  contree op cancel UUID1 UUID2       multi-UUID cancel (or --all)
   contree show OPERATION_UUID
   contree tag IMAGE_UUID latest
   contree ls /etc                    list files in session image
@@ -206,11 +211,18 @@ def register(
 
 register("use", "Set or show current session image", use.setup_parser, aliases=["ci"])
 register("run", "Spawn a sandbox instance", run.setup_parser, aliases=["r"])
+register("build", "Build image from Dockerfile", build.setup_parser, aliases=["bd"])
 register("images", "List and import images", images.setup_parser, aliases=["i", "img"])
 register("tag", "Tag an image", tag.setup_parser, aliases=["t"])
 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(
+    "operation",
+    "Manage operations (list/show/cancel)",
+    operation.setup_parser,
+    aliases=["op"],
+)
 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)

contree_cli-0.6.0/contree_cli/cli/build.py

@@ -0,0 +1,224 @@
+"""Build an image from a Dockerfile.
+
+Reads the Dockerfile at the given path (default ``<CONTEXT>/Dockerfile``)
+and applies each directive against an isolated build session keyed by
+the absolute path of the context directory. Successful layers are
+materialised as branches named ``layer:<chain-hash>`` so that
+re-running the same Dockerfile reuses prior work.
+
+Supported directives (MVP): FROM, RUN, COPY, ADD (without URL/tar),
+WORKDIR, ENV, ARG, USER. Other Dockerfile directives parse cleanly
+but are skipped with a warning (CMD, ENTRYPOINT, LABEL, EXPOSE,
+VOLUME, STOPSIGNAL, MAINTAINER, HEALTHCHECK, ONBUILD, SHELL).
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from contree_cli import (
+    CLIENT,
+    FORMATTER,
+    PROFILE,
+    SESSION_STORE,
+    ArgumentsProtocol,
+    SetupResult,
+)
+from contree_cli.docker import (
+    ArgKeyword,
+    BuildContext,
+    DockerKeyword,
+    FromKeyword,
+    LocalContext,
+    RunKeyword,
+    parse_dockerfile,
+)
+from contree_cli.docker.context import BUILD_TIMEOUT_DEFAULT
+from contree_cli.session import SessionStore
+from contree_cli.types import FLAGS
+
+logger = logging.getLogger(__name__)
+
+EPILOG = """\
+examples:
+  contree build .
+  contree build . --tag myimage:latest
+  contree build --dockerfile ./Dockerfile.test ./app
+  contree build --build-arg VERSION=1.2 .
+  contree build --no-cache .
+
+for coding agents:
+  mutating command, may create operations against the API
+  layer cache is per-context (session keyed by abspath(context))
+  use --no-cache to bypass cached layers and rebuild from scratch
+"""
+
+
+@dataclass(frozen=True)
+class BuildArgs(ArgumentsProtocol):
+    context: str = "."
+    dockerfile: str = ""
+    tag: str = ""
+    build_args: tuple[str, ...] = field(default_factory=tuple)
+    no_cache: bool = False
+    timeout: int = BUILD_TIMEOUT_DEFAULT
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> BuildArgs:
+        return cls(
+            context=ns.context or ".",
+            dockerfile=ns.dockerfile or "",
+            tag=ns.tag or "",
+            build_args=tuple(ns.build_arg or ()),
+            no_cache=bool(ns.no_cache),
+            timeout=ns.timeout,
+        )
+
+
+def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
+    p.add_argument(
+        "context",
+        nargs="?",
+        default=".",
+        help="Build context directory",
+    )
+    p.add_argument(
+        *FLAGS["dockerfile"],
+        default="",
+        metavar="PATH",
+        help="Dockerfile path (default: <context>/Dockerfile)",
+    )
+    p.add_argument(
+        *FLAGS["tag_name"],
+        default="",
+        metavar="NAME[:TAG]",
+        help="Tag the final image",
+    )
+    p.add_argument(
+        *FLAGS["build_arg"],
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+        help="Build-time variable (repeatable)",
+    )
+    p.add_argument(
+        *FLAGS["no_cache"],
+        action="store_true",
+        help="Ignore cached layers and rebuild",
+    )
+    p.add_argument(
+        *FLAGS["timeout"],
+        type=int,
+        default=BUILD_TIMEOUT_DEFAULT,
+        help="Timeout in seconds for each RUN step",
+    )
+    return cmd_build, BuildArgs
+
+
+def cmd_build(args: BuildArgs) -> int | None:
+    context_dir = Path(args.context).expanduser().resolve()
+    if not context_dir.is_dir():
+        logger.error("context %s is not a directory", context_dir)
+        return 1
+
+    dockerfile_path = (
+        Path(args.dockerfile).expanduser()
+        if args.dockerfile
+        else context_dir / "Dockerfile"
+    )
+    if not dockerfile_path.is_file():
+        logger.error("Dockerfile %s not found", dockerfile_path)
+        return 1
+
+    text = dockerfile_path.read_text()
+    try:
+        directives = parse_dockerfile(text)
+    except ValueError as exc:
+        logger.error("Dockerfile parse error: %s", exc)
+        return 1
+
+    if not validate_first_directive(directives):
+        logger.error("Dockerfile must contain a FROM directive")
+        return 1
+
+    build_args = parse_build_args(args.build_args)
+
+    profile = PROFILE.get()
+    client = CLIENT.get()
+    session_key = make_session_key(context_dir)
+    store = SessionStore(profile.session_db_path, session_key)
+    SESSION_STORE.set(store)
+
+    ctx = BuildContext(
+        client=client,
+        store=store,
+        local=LocalContext.from_dir(context_dir),
+        build_args=build_args,
+        no_cache=args.no_cache,
+        timeout=args.timeout,
+    )
+
+    try:
+        for kw in directives:
+            kw.execute(ctx)
+        finalize_pending(ctx)
+    except Exception as exc:
+        logger.error("build failed: %s", exc)
+        return 1
+
+    if not ctx.last_image:
+        logger.error("build produced no image")
+        return 1
+
+    if args.tag:
+        client.patch_json(
+            f"/v1/images/{ctx.last_image}/tag",
+            {"tag": args.tag},
+        )
+        logger.info("tagged %s as %s", ctx.last_image, args.tag)
+
+    formatter = FORMATTER.get()
+    formatter(
+        image=ctx.last_image,
+        tag=args.tag,
+        session=session_key,
+    )
+    formatter.flush()
+    return None
+
+
+def validate_first_directive(directives: list[DockerKeyword]) -> bool:
+    for d in directives:
+        if isinstance(d, FromKeyword):
+            return True
+        if isinstance(d, ArgKeyword):
+            continue
+        return False
+    return False
+
+
+def parse_build_args(items: tuple[str, ...]) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for item in items:
+        if "=" not in item:
+            raise ValueError(f"--build-arg expected KEY=VALUE, got {item!r}")
+        k, _, v = item.partition("=")
+        out[k] = v
+    return out
+
+
+def make_session_key(context_dir: Path) -> str:
+    digest = hashlib.sha256(str(context_dir).encode()).hexdigest()
+    return f"build:{digest[:16]}"
+
+
+def finalize_pending(ctx: BuildContext) -> None:
+    """If COPY/ADD left files pending, commit them via a trivial RUN."""
+    if not ctx.pending:
+        return
+    closer = RunKeyword(parts=(":",), shell_form=True)
+    closer.execute(ctx)

{contree_cli-0.5.1 → contree_cli-0.6.0}/contree_cli/cli/file.py

@@ -23,13 +23,26 @@ import shlex
 import subprocess
 import tempfile
 from dataclasses import dataclass
+from datetime import datetime
 from pathlib import Path
 
-from contree_cli import CLIENT, SESSION_STORE, ArgumentsProtocol, SetupResult
+from contree_cli import (
+    CLIENT,
+    FORMATTER,
+    SESSION_STORE,
+    ArgumentsProtocol,
+    SetupResult,
+)
 from contree_cli.client import ApiError, ContreeClient, resolve_image, stream_response
 from contree_cli.config import EDITOR
 from contree_cli.session import SessionStore
-from contree_cli.types import FLAGS
+from contree_cli.types import (
+    FLAGS,
+    isoformat_datetime,
+    parse_datetime,
+    parse_interval,
+    positive_int,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -61,6 +74,27 @@ class FileCpArgs(ArgumentsProtocol):
         return cls(src=ns.src, dest=ns.dest)
 
 
+FILE_LIST_LIMIT_DEFAULT = 1000
+FILE_LIST_PAGE_SIZE = 1000
+
+
+@dataclass(frozen=True)
+class FileListArgs(ArgumentsProtocol):
+    since: datetime | None = None
+    until: datetime | None = None
+    limit: int = FILE_LIST_LIMIT_DEFAULT
+    quiet: bool = False
+
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> FileListArgs:
+        return cls(
+            since=getattr(ns, "since", None),
+            until=getattr(ns, "until", None),
+            limit=getattr(ns, "limit", FILE_LIST_LIMIT_DEFAULT),
+            quiet=bool(getattr(ns, "quiet", False)),
+        )
+
+
 def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
     sub = p.add_subparsers(dest="file_action", required=True)
     edit_p = sub.add_parser(
@@ -102,6 +136,58 @@ def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
     cp_p.add_argument("dest", help="Destination path inside image")
     cp_p.set_defaults(handler=cmd_file_cp, load_args=FileCpArgs)
 
+    ls_p = sub.add_parser(
+        "ls",
+        aliases=["list"],
+        help="List uploaded files (joined with local cache)",
+        description=(
+            "List remote files uploaded to the project and, when present in"
+            " the local upload cache, show what produced them under the"
+            " 'source' column: either an absolute host path (for run --file"
+            " / COPY uploads) or a URL (for ADD URL).\n"
+            "\n"
+            "source is THIS-MACHINE ONLY: the mapping lives in the local"
+            " CLI cache ($CONTREE_HOME/cli/sessions/<profile>.db) and is"
+            " never synced. Files uploaded from a different host, by a"
+            " teammate, or before tracking landed will show an empty source"
+            " -- that is expected, not a bug. Use the remote uuid or sha256"
+            " for cross-machine identity."
+        ),
+        epilog=(
+            "examples:\n"
+            "  contree file ls\n"
+            "  contree file ls --since 1d\n"
+            "  contree file ls --limit 5000\n"
+            "  contree file ls -q              # uuid + sha256 + source\n"
+            "  contree -f json file ls\n"
+        ),
+    )
+    ls_p.add_argument(
+        *FLAGS["since"],
+        type=parse_interval,
+        help=parse_interval.__doc__,
+    )
+    ls_p.add_argument(
+        *FLAGS["until"],
+        type=parse_interval,
+        help="Show files before. " + str(parse_interval.__doc__),
+    )
+    ls_p.add_argument(
+        *FLAGS["limit"],
+        type=positive_int,
+        default=FILE_LIST_LIMIT_DEFAULT,
+        help="Stop after this many files and warn if more are available",
+    )
+    ls_p.add_argument(
+        *FLAGS["quiet"],
+        action="store_true",
+        help=(
+            "Emit only uuid, sha256, and source columns. source is populated"
+            " only for files uploaded from this very machine."
+        ),
+    )
+    ls_p.set_defaults(handler=cmd_file_ls, load_args=FileListArgs)
+
     return cmd_file_edit, FileEditArgs
 
 
@@ -123,7 +209,7 @@ def _upload_and_record(
     """Upload a local file (with dedup) and record as pending."""
     sha = _file_sha256(local_path)
     try:
-        resp = client.get("/v1/files", params={"sha256": sha})
+        resp = client.get(f"/v1/files/{sha}")
         file_uuid = json.loads(resp.read())["uuid"]
         logger.info("File already exists on server (%s)", file_uuid)
     except ApiError as exc:
@@ -222,3 +308,63 @@ def cmd_file_cp(args: FileCpArgs) -> int | None:
         title=f"Change file {args.dest}",
     )
     return None
+
+
+def cmd_file_ls(args: FileListArgs) -> int | None:
+    client = CLIENT.get()
+    store = SESSION_STORE.get()
+    formatter = FORMATTER.get()
+
+    sources = store.cache.local_file_paths()
+
+    params: dict[str, str] = {}
+    if args.since is not None:
+        params["since"] = isoformat_datetime(args.since)
+    if args.until is not None:
+        params["until"] = isoformat_datetime(args.until)
+
+    offset = 0
+    emitted = 0
+    while emitted < args.limit:
+        page_size = min(FILE_LIST_PAGE_SIZE, args.limit - emitted)
+        page = {**params, "offset": str(offset), "limit": str(page_size)}
+        resp = client.get("/v1/files", params=page)
+        data = json.loads(resp.read())
+        files = data.get("files", [])
+        if not files:
+            return None
+        for entry in files:
+            uuid_str = entry.get("uuid")
+            source = sources.get(uuid_str, "") if isinstance(uuid_str, str) else ""
+            if args.quiet:
+                formatter(
+                    uuid=uuid_str,
+                    sha256=entry.get("sha256", ""),
+                    source=source,
+                )
+                continue
+            row: dict[str, object] = {}
+            for key, value in entry.items():
+                if isinstance(value, (dict, list)):
+                    continue
+                if key in {"created_at", "updated_at"} and isinstance(value, str):
+                    value = parse_datetime(value)
+                row[key] = value
+            row["source"] = source
+            formatter(**row)
+        emitted += len(files)
+        if len(files) < page_size:
+            return None
+        offset += len(files)
+
+    probe = {**params, "offset": str(offset), "limit": "1"}
+    resp = client.get("/v1/files", params=probe)
+    data = json.loads(resp.read())
+    if data.get("files"):
+        formatter.flush()
+        logger.warning(
+            "Output truncated at --limit=%d files; more results are"
+            " available. Raise --limit or narrow with --since/--until.",
+            args.limit,
+        )
+    return None

{contree_cli-0.5.1 → contree_cli-0.6.0}/contree_cli/cli/images.py

@@ -202,7 +202,8 @@ def _add_list_args(p: argparse.ArgumentParser) -> None:
 
 
 def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
-    # Parent-level args for backward compat (contree images --prefix …)
+    # Parent-level list args mirror the subcommand so `contree images
+    # --prefix …` works without typing `list`.
     _add_list_args(p)
 
     sub = p.add_subparsers(dest="images_action")
@@ -286,12 +287,16 @@ def cmd_images(args: ImagesArgs) -> None:
         if not images:
             return
         for image in images:
-            created_at = parse_datetime(image["created_at"])
-            formatter(
-                uuid=image["uuid"],
-                created_at=created_at,
-                tag=image.get("tag") or "",
-            )
+            row: dict[str, object] = {}
+            for key, value in image.items():
+                if isinstance(value, (dict, list)):
+                    continue
+                if key == "created_at" and isinstance(value, str):
+                    value = parse_datetime(value)
+                if key == "tag" and value is None:
+                    value = ""
+                row[key] = value
+            formatter(**row)
         emitted += len(images)
         if len(images) < page_size:
             return