lean-runtime 2.3.0__tar.gz → 2.4.0__tar.gz

{lean_runtime-2.3.0/lean_runtime.egg-info → lean_runtime-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lean-runtime
-Version: 2.3.0
+Version: 2.4.0
 Summary: Run Lean 4 proofs from Python or standalone files
 Author: Alejandro Radisic
 License-Expression: Apache-2.0

{lean_runtime-2.3.0 → lean_runtime-2.4.0}/lean_runtime/__init__.py

@@ -13,6 +13,7 @@ from .environments import (
     InteractiveSession,
 )
 from .errors import (
+    DownloadLimitExceeded,
     DownloadUnavailable,
     EnvironmentError,
     LeanCheckError,
@@ -76,6 +77,7 @@ __all__ = [
     "ComparisonEntry",
     "PortableCopyInfo",
     "DownloadCleanupReport",
+    "DownloadLimitExceeded",
     "DEFAULT_ENVIRONMENT_LIBRARIES",
     "DependencyInput",
     "DiscoveredPackage",

{lean_runtime-2.3.0 → lean_runtime-2.4.0}/lean_runtime/cli.py

@@ -6,19 +6,22 @@ import argparse
 import json
 import sys
 import time
+from datetime import datetime
 from pathlib import Path
 from typing import Any
 
+from .console import styler_for
 from .environments import ExecutionCapture
 from .errors import LeanRuntimeError, MaterializationError, ResolutionError
 from .events import RuntimeEvent
 from .lockfiles import EnvironmentLock
 from .matrix import load_matrix
 from .models import ExecutionResult, PhaseTiming
-from .policies import ExecutionPolicy
+from .policies import ExecutionPolicy, format_byte_size
 from .projects import discover_project, project_publication_workflow
 from .runtime import Runtime
 from .specs import EnvironmentSpec
+from .store import CleanupReport, DownloadCleanupReport, StoreStatus
 from .timings import render_timings
 from .wire import (
     envelope,
@@ -46,6 +49,105 @@ def _json(value: Any) -> None:
     print(json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True))
 
 
+def _relative_age(timestamp: str | None) -> str:
+    if not timestamp:
+        return "unknown"
+    try:
+        moment = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+    except ValueError:
+        return "unknown"
+    seconds = max(0.0, time.time() - moment.timestamp())
+    for unit_seconds, label in ((31_536_000, "y"), (2_592_000, "mo"), (86_400, "d"), (3_600, "h")):
+        if seconds >= unit_seconds:
+            return f"{int(seconds // unit_seconds)}{label} ago"
+    return "recent"
+
+
+def _render_storage(status: StoreStatus) -> None:
+    style = styler_for(sys.stdout)
+    print(f"{style.bold('Store')}  {status.home}")
+    print()
+    rows = (
+        ("Environments", status.environments, status.environments_bytes),
+        ("Sources", status.sources, status.sources_bytes),
+        ("Download cache", status.oci_blobs, status.oci_blobs_bytes),
+        ("Toolchains", None, status.toolchains_bytes),
+        ("Executions", status.executions, status.executions_bytes),
+    )
+    for label, count, bytes_used in rows:
+        counted = f"{count:>5}" if count is not None else "     "
+        size_column = style.cyan(f"{format_byte_size(bytes_used):>10}")
+        print(f"  {label:<15}{counted}  {size_column}")
+    total_label = style.bold(f"{'Total':<15}")
+    total_size = style.bold(f"{format_byte_size(status.bytes_used):>10}")
+    free_note = style.dim(f"({format_byte_size(status.bytes_free)} free on disk)")
+    print(f"  {total_label}       {total_size}  {free_note}")
+    if status.environment_usage:
+        print()
+        print(style.bold("Largest environments"))
+        for usage in status.environment_usage[:5]:
+            name = ", ".join(usage.aliases) if usage.aliases else usage.environment_id[:16] + "…"
+            details = " · ".join(
+                part
+                for part in (usage.toolchain, f"last used {_relative_age(usage.last_used_at)}")
+                if part
+            )
+            size_column = style.cyan(f"{format_byte_size(usage.bytes_used):>10}")
+            print(f"  {size_column}  {name}  {style.dim(details)}")
+    print()
+    print(style.dim("Reclaim space: lean-runtime clean            (preview, keeps recent/named)"))
+    print(style.dim("               lean-runtime clean --execute --include-downloads"))
+
+
+def _render_cleanup(environments: CleanupReport, downloads: DownloadCleanupReport | None) -> None:
+    style = styler_for(sys.stdout)
+    retained_note = style.dim(
+        f"Retained {len(environments.retained)} environment(s) (named, recent, or in use)."
+    )
+    if environments.dry_run:
+        anything = False
+        if environments.candidates:
+            anything = True
+            print(
+                style.bold(
+                    f"Would remove {len(environments.candidates)} unused environment(s) · "
+                    f"{format_byte_size(environments.candidate_bytes)}"
+                )
+            )
+            for name in environments.candidates:
+                print(f"  {style.dim(name)}")
+        else:
+            print("No unused environments to remove.")
+        if downloads is not None:
+            if downloads.candidates:
+                anything = True
+                print(
+                    style.bold(
+                        f"Would remove {len(downloads.candidates)} cached download(s) · "
+                        f"{format_byte_size(downloads.candidate_bytes)}"
+                    )
+                )
+            else:
+                print("No unreferenced cached downloads to remove.")
+        print(retained_note)
+        if anything:
+            print()
+            print("This was a preview. Re-run with --execute to delete.")
+        return
+    reclaimed = environments.reclaimed_bytes + (downloads.reclaimed_bytes if downloads else 0)
+    removed = len(environments.removed) + (len(downloads.removed) if downloads else 0)
+    if removed:
+        parts = [f"{len(environments.removed)} environment(s)"]
+        if downloads is not None:
+            parts.append(f"{len(downloads.removed)} cached download(s)")
+        print(
+            style.green(f"Removed {' and '.join(parts)} · reclaimed {format_byte_size(reclaimed)}")
+        )
+    else:
+        print("Nothing needed cleaning.")
+    print(retained_note)
+
+
 def _progress(event: RuntimeEvent) -> None:
     package = f" [{event.data['package']}]" if "package" in event.data else ""
     print(f"lean-runtime: {event.kind}{package}: {event.message}", file=sys.stderr)
@@ -266,7 +368,8 @@ def parser() -> argparse.ArgumentParser:
     inspect.add_argument("--explain", action="store_true", help="explain identity and reuse")
 
     commands.add_parser("environments", help="list ready environments")
-    commands.add_parser("storage", help="show downloaded and built storage usage")
+    storage = commands.add_parser("storage", help="show downloaded and built storage usage")
+    storage.add_argument("--json", action="store_true")
     commands.add_parser("doctor", help="check local prerequisites and environment storage")
 
     verify = commands.add_parser("verify", help="verify a lock or published environment")
@@ -316,6 +419,7 @@ def parser() -> argparse.ArgumentParser:
     gc.add_argument(
         "--include-downloads", action="store_true", help="also clean unused downloaded files"
     )
+    gc.add_argument("--json", action="store_true")
 
     raw = commands.add_parser(
         "check-file", help="check a file, discovering its local Lake project when possible"
@@ -640,7 +744,11 @@ def main(argv: list[str] | None = None) -> int:
             _json(list(runtime.list_environments()))
             return 0
         if args.command == "storage":
-            _json(runtime.store_status().to_dict())
+            status = runtime.store_status()
+            if args.json:
+                _json(status.to_dict())
+            else:
+                _render_storage(status)
             return 0
         if args.command == "toolchain-slim":
             manifest = runtime.toolchains.materialize_slim(args.toolchain)
@@ -734,22 +842,28 @@ def main(argv: list[str] | None = None) -> int:
                 dry_run=not args.execute,
                 minimum_age_seconds=args.minimum_age_hours * 3600,
             )
-            gc_payload: dict[str, Any] = {
-                "environments": gc_report.to_dict(),
-                "downloaded_files": None,
-            }
-            if args.include_downloads:
-                gc_payload["downloaded_files"] = runtime.clean_downloads(
+            gc_downloads = (
+                runtime.clean_downloads(
                     dry_run=not args.execute,
                     minimum_age_seconds=args.minimum_age_hours * 3600,
-                ).to_dict()
-            _json(
-                envelope(
-                    "lean-runtime.cleanup/v1",
-                    ok=True,
-                    data=gc_payload,
                 )
+                if args.include_downloads
+                else None
             )
+            if args.json:
+                gc_payload: dict[str, Any] = {
+                    "environments": gc_report.to_dict(),
+                    "downloaded_files": gc_downloads.to_dict() if gc_downloads else None,
+                }
+                _json(
+                    envelope(
+                        "lean-runtime.cleanup/v1",
+                        ok=True,
+                        data=gc_payload,
+                    )
+                )
+            else:
+                _render_cleanup(gc_report, gc_downloads)
             return 0
         if args.command == "check":
             if args.package_refs:

lean_runtime-2.4.0/lean_runtime/console.py

@@ -0,0 +1,246 @@
+"""Terminal rendering of structured runtime progress events."""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from typing import Any, Literal, TextIO
+
+from .events import RuntimeEvent
+from .policies import format_byte_size
+
+RenderMode = Literal["tty", "plain", "quiet"]
+
+_BAR_WIDTH = 20
+_TTY_REDRAW_SECONDS = 0.1
+_PLAIN_CHECKPOINT_PERCENT = 25
+
+
+def select_mode(*, quiet: bool = False, stream: TextIO | None = None) -> RenderMode:
+    if quiet:
+        return "quiet"
+    stream = stream if stream is not None else sys.stderr
+    return "tty" if stream.isatty() else "plain"
+
+
+class Styler:
+    """Minimal ANSI styling that degrades to plain text when disabled."""
+
+    def __init__(self, enabled: bool) -> None:
+        self.enabled = enabled
+
+    def _wrap(self, code: str, text: str) -> str:
+        return f"\x1b[{code}m{text}\x1b[0m" if self.enabled else text
+
+    def bold(self, text: str) -> str:
+        return self._wrap("1", text)
+
+    def dim(self, text: str) -> str:
+        return self._wrap("2", text)
+
+    def red(self, text: str) -> str:
+        return self._wrap("31", text)
+
+    def green(self, text: str) -> str:
+        return self._wrap("32", text)
+
+    def yellow(self, text: str) -> str:
+        return self._wrap("33", text)
+
+    def cyan(self, text: str) -> str:
+        return self._wrap("36", text)
+
+
+def styler_for(stream: TextIO | None = None) -> Styler:
+    """Style only real terminals, honoring the NO_COLOR convention."""
+    stream = stream if stream is not None else sys.stderr
+    isatty = getattr(stream, "isatty", None)
+    enabled = bool(isatty and isatty()) and "NO_COLOR" not in os.environ
+    return Styler(enabled)
+
+
+class ConsoleRenderer:
+    """Render runtime events as terse, single-purpose progress output.
+
+    Warm runs stay silent; cold acquisitions get one context line and one
+    aggregate progress line. Everything else is behind ``verbose``.
+    """
+
+    def __init__(
+        self,
+        stream: TextIO | None = None,
+        *,
+        mode: RenderMode | None = None,
+        verbose: bool = False,
+        color: bool | None = None,
+        clock: Any = time.monotonic,
+    ) -> None:
+        self.stream = stream if stream is not None else sys.stderr
+        self.mode: RenderMode = mode if mode is not None else select_mode(stream=self.stream)
+        self.verbose = verbose
+        self.style = Styler(color) if color is not None else styler_for(self.stream)
+        self._clock = clock
+        self._download_total: int | None = None
+        self._layer_bytes: dict[str, int] = {}
+        self._line_length = 0
+        self._last_redraw: float | None = None
+        self._next_checkpoint = _PLAIN_CHECKPOINT_PERCENT
+        self._download_finished = False
+
+    def __call__(self, event: RuntimeEvent) -> None:
+        if self.mode == "quiet":
+            return
+        if self.verbose:
+            self._verbose_line(event)
+            return
+        handler = getattr(self, "_render_" + event.kind.replace(".", "_"), None)
+        if handler is not None:
+            handler(event)
+
+    def note(self, message: str) -> None:
+        """Print one renderer-owned status line."""
+        if self.mode == "quiet":
+            return
+        self._print(message)
+
+    def close(self) -> None:
+        """Terminate any in-place progress line before final output."""
+        self._end_progress_line()
+
+    # -- individual event renderings ------------------------------------
+
+    def _render_package_reference_started(self, event: RuntimeEvent) -> None:
+        reference = event.data.get("reference", "")
+        self._print(f"Resolving {reference}".rstrip())
+
+    def _render_discovery_candidate_started(self, event: RuntimeEvent) -> None:
+        candidate = event.data.get("candidate", "candidate")
+        toolchain = event.data.get("toolchain")
+        suffix = f" · {toolchain}" if toolchain else ""
+        self._print(f"Trying {candidate}{suffix}")
+
+    def _render_toolchain_install_started(self, event: RuntimeEvent) -> None:
+        toolchain = event.data.get("toolchain", "toolchain")
+        self._print(f"Installing Lean toolchain {toolchain} (one-time, can take minutes)")
+
+    def _render_acquisition_planned(self, event: RuntimeEvent) -> None:
+        download = event.data.get("download_bytes")
+        cached = event.data.get("cached_bytes")
+        if not isinstance(download, int) or download <= 0:
+            return
+        self._download_total = download
+        self._layer_bytes.clear()
+        self._next_checkpoint = _PLAIN_CHECKPOINT_PERCENT
+        self._download_finished = False
+        self._last_redraw = None
+        suffix = (
+            f" ({format_byte_size(cached)} already cached)"
+            if isinstance(cached, int) and cached > 0
+            else ""
+        )
+        self._print(f"Downloading environment: {format_byte_size(download)}{suffix}")
+
+    def _render_library_layer_progress(self, event: RuntimeEvent) -> None:
+        digest = str(event.data.get("digest", ""))
+        if event.current_bytes is None or self._download_total is None:
+            return
+        self._layer_bytes[digest] = event.current_bytes
+        done = min(sum(self._layer_bytes.values()), self._download_total)
+        if self.mode == "tty":
+            now = self._clock()
+            if (
+                self._last_redraw is not None
+                and done < self._download_total
+                and now - self._last_redraw < _TTY_REDRAW_SECONDS
+            ):
+                return
+            self._last_redraw = now
+            self._draw_bar(done, self._download_total)
+        else:
+            percent = done * 100 // self._download_total
+            while self._next_checkpoint <= percent:
+                self._print(f"Downloaded {self._next_checkpoint}%")
+                self._next_checkpoint += _PLAIN_CHECKPOINT_PERCENT
+
+    def _render_library_layer_download_started(self, event: RuntimeEvent) -> None:
+        resumed = event.data.get("resumed_bytes")
+        if isinstance(resumed, int) and resumed > 0:
+            self._print(f"Resuming interrupted download from {format_byte_size(resumed)}")
+
+    def _render_library_layer_download_retry(self, event: RuntimeEvent) -> None:
+        self._print("Retrying download after integrity verification failed")
+
+    def _render_library_verified(self, event: RuntimeEvent) -> None:
+        if self._download_total is None or self._download_finished:
+            return
+        self._download_finished = True
+        if self.mode == "tty":
+            self._draw_bar(self._download_total, self._download_total)
+        self._end_progress_line()
+        self._print(self.style.green("Downloaded and verified environment"))
+
+    def _render_source_fetch_started(self, event: RuntimeEvent) -> None:
+        package = event.data.get("package", "sources")
+        self._print(f"Fetching {package} source")
+
+    def _render_artifact_hydration_started(self, event: RuntimeEvent) -> None:
+        package = event.data.get("package", "artifacts")
+        self._print(f"Hydrating build artifacts for {package}")
+
+    def _render_availability_fallback(self, event: RuntimeEvent) -> None:
+        library = event.data.get("library", "environment library")
+        reason = event.data.get("reason_code") or event.data.get("reason") or "unavailable"
+        self._print(
+            self.style.yellow(
+                f"WARNING: downloadable environment unavailable from {library} ({reason})"
+            )
+        )
+
+    def _render_environment_build_started(self, event: RuntimeEvent) -> None:
+        self._print(
+            "Building environment from source (large dependencies such as Mathlib can take "
+            "30+ minutes; pass --no-source-build to fail fast instead)"
+        )
+
+    def _render_capability_required(self, event: RuntimeEvent) -> None:
+        self._print(event.message)
+
+    # -- low-level output -----------------------------------------------
+
+    def _verbose_line(self, event: RuntimeEvent) -> None:
+        parts = [f"{event.kind}: {event.message}"]
+        if event.current_bytes is not None and event.total_bytes is not None:
+            parts.append(
+                f"[{format_byte_size(event.current_bytes)}/{format_byte_size(event.total_bytes)}]"
+            )
+        if event.data:
+            details = " ".join(f"{key}={value}" for key, value in sorted(event.data.items()))
+            parts.append(f"({details})")
+        self._print(" ".join(parts))
+
+    def _draw_bar(self, done: int, total: int) -> None:
+        filled = _BAR_WIDTH * done // total if total else _BAR_WIDTH
+        bar = "█" * filled + "░" * (_BAR_WIDTH - filled)
+        percent = done * 100 // total if total else 100
+        sizes = f"{format_byte_size(done)}/{format_byte_size(total)}"
+        plain = f"Downloading [{bar}] {percent}% · {sizes}"
+        line = (
+            f"Downloading [{self.style.cyan(bar)}] "
+            f"{self.style.bold(f'{percent}%')} · {self.style.dim(sizes)}"
+        )
+        padding = " " * max(0, self._line_length - len(plain))
+        self.stream.write("\r" + line + padding)
+        self.stream.flush()
+        self._line_length = len(plain)
+
+    def _end_progress_line(self) -> None:
+        if self._line_length:
+            self.stream.write("\n")
+            self.stream.flush()
+            self._line_length = 0
+
+    def _print(self, message: str) -> None:
+        self._end_progress_line()
+        self.stream.write(message + "\n")
+        self.stream.flush()

{lean_runtime-2.3.0 → lean_runtime-2.4.0}/lean_runtime/discovery/probe.py

@@ -78,6 +78,14 @@ class LeanRuntimeProbe:
         cancel: threading.Event,
     ) -> AcquiredCandidate:
         event_offset = len(self.events) if self.events is not None else 0
+        emitter = getattr(self.runtime, "events", None)
+        if emitter is not None:
+            emitter.emit(
+                "discovery.candidate_started",
+                f"Trying {candidate.entry.id}",
+                candidate=candidate.entry.id,
+                toolchain=candidate.entry.toolchain,
+            )
         try:
             environment = self.runtime.open_exact(
                 candidate.entry.lock,

{lean_runtime-2.3.0 → lean_runtime-2.4.0}/lean_runtime/errors.py

@@ -64,6 +64,15 @@ class DownloadUnavailable(EnvironmentError):
     """A prebuilt cache had no usable artifact or could not be reached."""
 
 
+class DownloadLimitExceeded(EnvironmentError):
+    """An acquisition needs more bytes than the configured download limit.
+
+    Deliberately not a :class:`DownloadUnavailable`: exceeding a policy limit
+    must fail the operation instead of silently falling back to another
+    library or a source build.
+    """
+
+
 class MaterializationError(EnvironmentError):
     """Locked sources or build artifacts could not be materialized."""
 

{lean_runtime-2.3.0 → lean_runtime-2.4.0}/lean_runtime/events.py

@@ -16,9 +16,16 @@ class RuntimeEvent:
     message: str
     data: dict[str, Any] = field(default_factory=dict)
     timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    phase: str | None = None
+    current_bytes: int | None = None
+    total_bytes: int | None = None
 
     def to_dict(self) -> dict[str, Any]:
-        return asdict(self)
+        value = asdict(self)
+        for key in ("phase", "current_bytes", "total_bytes"):
+            if value[key] is None:
+                del value[key]
+        return value
 
 
 EventCallback = Callable[[RuntimeEvent], None]
@@ -30,6 +37,24 @@ class EventEmitter:
     def __init__(self, callback: EventCallback | None = None) -> None:
         self.callback = callback
 
-    def emit(self, kind: str, message: str, **data: Any) -> None:
+    def emit(
+        self,
+        kind: str,
+        message: str,
+        *,
+        phase: str | None = None,
+        current_bytes: int | None = None,
+        total_bytes: int | None = None,
+        **data: Any,
+    ) -> None:
         if self.callback is not None:
-            self.callback(RuntimeEvent(kind=kind, message=message, data=data))
+            self.callback(
+                RuntimeEvent(
+                    kind=kind,
+                    message=message,
+                    data=data,
+                    phase=phase,
+                    current_bytes=current_bytes,
+                    total_bytes=total_bytes,
+                )
+            )