bladekit 4.5.0__py3-none-any.whl

bladekit/_image.py

@@ -0,0 +1,577 @@
+"""``bladekit.Image`` — chained, immutable image-definition DSL.
+
+Each builder method returns a NEW ``Image`` with one extra layer appended; an
+``Image`` is never mutated in place, so the same base can branch safely::
+
+    base = bladekit.Image.debian_slim(python_version="3.12").apt_install("git")
+    a = base.pip_install("torch")
+    b = base.pip_install("jax")          # `base` unchanged
+
+The canonical JSON serialization and the ``definition_hash`` are STRICTLY the
+ones specified in contracts/image-dsl.md §2/§3:
+
+- canonical bytes = ``json.dumps(d, sort_keys=True, separators=(",", ":"),
+  ensure_ascii=False)`` encoded UTF-8;
+- absent/empty optional fields are dropped before hashing (one representation
+  per definition);
+- array order is preserved (layers, packages) — never sorted;
+- ``definition_hash`` = lowercase-hex sha256 of those bytes.
+
+The hash is computed locally only for display / dedup hints; the server
+recomputes it and is authoritative (image-dsl.md §3). ``hashlib`` / ``json`` are
+stdlib, so importing this module stays cheap (no heavy top-level import) — it is
+imported lazily from ``bladekit.__init__`` only when first referenced is not
+required, but it is light enough to import eagerly.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import ipaddress
+import json
+import re
+from typing import Any, Dict, List, Mapping, Optional, Sequence
+from urllib.parse import urlsplit
+
+from . import exceptions as exc
+
+# Limits — contracts/conventions.md §6 and image-dsl.md §2.
+_DEFINITION_VERSION = 1
+_MAX_LAYERS = 64
+_MAX_PACKAGES_PER_LAYER = 256
+_MAX_COMMANDS_PER_LAYER = 64
+_MAX_ENV_VARS_PER_LAYER = 64
+_CANONICAL_MAX_BYTES = 64 * 1024  # 64 KiB
+# from_dockerfile limits (docs/specs/image-from-dockerfile.md §3).
+_MAX_DOCKERFILE_BYTES = 32 * 1024
+_MAX_BUILD_ARGS = 32
+_MAX_BUILD_ARGS_BYTES = 4 * 1024
+
+_PYTHON_VERSION_RE = re.compile(r"^3\.[0-9]+$")
+# env keys: ^[A-Z_][A-Z0-9_]*$, never FABRIC_/FORGE_-prefixed (reserved for runtime).
+_ENV_KEY_RE = re.compile(r"^[A-Z_][A-Z0-9_]*$")
+# catalog alias (from_catalog): a catalogue name like "fabric/torch" — not a
+# registry URL. No tag/digest: the server resolves the alias to the real ref.
+_CATALOG_ALIAS_RE = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9._/-]*$")
+# Env prefixes the runtime owns (bladekit._env.RESERVED_PREFIXES, inlined so
+# this module keeps importing nothing but exceptions).
+RESERVED_ENV_PREFIXES = ("FABRIC_", "FORGE_")
+
+# Catalog aliases are written ``fabric/<name>`` (PAAS-771). The control plane only
+# knows them as ``forge/<name>`` today, so the SDK rewrites the prefix on the wire
+# and the server never sees ``fabric/``. Remove the rewrite once the server
+# accepts both spellings (PAAS-771, server half). ``forge/<name>`` keeps working
+# unchanged.
+CATALOG_PREFIX = "fabric/"
+WIRE_CATALOG_PREFIX = "forge/"
+
+
+def to_wire_image(ref: Any) -> Any:
+    """Map a ``fabric/<name>`` catalog alias to the ``forge/<name>`` the server knows.
+
+    Anything else — ``forge/<name>``, a registry ref with a tag or digest, a
+    non-string — is returned unchanged.
+    """
+    if (
+        isinstance(ref, str)
+        and ref.startswith(CATALOG_PREFIX)
+        and _CATALOG_ALIAS_RE.match(ref)
+    ):
+        return WIRE_CATALOG_PREFIX + ref[len(CATALOG_PREFIX):]
+    return ref
+
+
+def to_display_image(ref: Any) -> Any:
+    """Inverse of :func:`to_wire_image`, for showing a server alias to the user."""
+    if (
+        isinstance(ref, str)
+        and ref.startswith(WIRE_CATALOG_PREFIX)
+        and _CATALOG_ALIAS_RE.match(ref)
+    ):
+        return CATALOG_PREFIX + ref[len(WIRE_CATALOG_PREFIX):]
+    return ref
+
+
+# Dockerfile ARG names (same charset docker accepts).
+_BUILD_ARG_KEY_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+# pip index URL policy (PAAS-265) — client-side mirror of the server's
+# authoritative check (control-plane/internal/imagedsl checkIndexURL). The
+# server validates too, but client-side rejection gives an immediate, actionable
+# error rather than a build failure minutes later.
+#
+#   * https:// is the only scheme accepted for a public host: a plaintext index
+#     lets a network attacker substitute packages during the BuildKit build.
+#   * http:// is tolerated ONLY for a loopback / RFC 1918 / link-local host or a
+#     bare "localhost" (a dev mirror reachable from the builder alone). Names
+#     other than "localhost" are never resolved and count as public.
+#   * Everything else (file:, ftp://, ssh://, git+, scheme-less, ...) is
+#     rejected — a positive allowlist, not a blocklist.
+
+
+def _is_private_index_host(host: str) -> bool:
+    if host.lower() == "localhost":
+        return True
+    try:
+        ip = ipaddress.ip_address(host.strip("[]"))
+    except ValueError:
+        return False
+    return ip.is_loopback or ip.is_private or ip.is_link_local
+
+
+def _check_index_url(op: str, param: str, url: str) -> None:
+    """Raise unless *url* is https://, or http:// to a loopback/private host."""
+    parsed = urlsplit(url)
+    scheme = parsed.scheme.lower()
+    host = parsed.hostname or ""
+    if scheme not in ("https", "http") or not host:
+        raise _invalid(
+            f"{op}: {param} uses a disallowed scheme; only https:// is "
+            f"accepted (got {url!r})"
+        )
+    if scheme == "http" and not _is_private_index_host(host):
+        raise _invalid(
+            f"{op}: {param} uses plaintext http://; only https:// is allowed "
+            f"for non-local hosts — a plaintext index lets a network attacker "
+            f"substitute packages during the build (got {url!r})"
+        )
+
+
+def _dockerfile_reads_context(text: str) -> bool:
+    """Heuristic: does the Dockerfile COPY/ADD from the local build context?
+
+    Client-side mirror of the server's authoritative check (which uses the
+    real BuildKit parser): merges backslash line continuations, skips
+    comments, then looks for a ``COPY`` without ``--from=`` or an ``ADD``
+    whose source is not a remote URL. A false positive is harmless (pass
+    context_dir); the server re-validates either way.
+    """
+    logical: List[str] = []
+    pending = ""
+    for raw in text.splitlines():
+        line = raw.rstrip()
+        stripped = line.strip()
+        if not pending and (not stripped or stripped.startswith("#")):
+            continue
+        if line.endswith("\\") and not line.endswith("\\\\"):
+            pending += line[:-1] + " "
+            continue
+        logical.append((pending + line).strip())
+        pending = ""
+    if pending.strip():
+        logical.append(pending.strip())
+    for inst in logical:
+        parts = inst.split()
+        if not parts:
+            continue
+        op = parts[0].upper()
+        if op == "COPY":
+            if not any(a.lower().startswith("--from=") for a in parts[1:]):
+                return True
+        elif op == "ADD":
+            args = [a for a in parts[1:] if not a.startswith("--")]
+            for a in args[:-1]:  # last arg is the destination
+                low = a.lower()
+                if not low.startswith(("http://", "https://", "git@")):
+                    return True
+    return False
+
+
+def _invalid(message: str) -> exc.InvalidArgumentError:
+    """Local validation error — mirrors the server's 400 IMAGE_DEFINITION_INVALID.
+
+    Raised eagerly at DSL-construction time so the user gets a clear, immediate
+    message at the offending ``.pip_install(...)`` call instead of a late 400.
+    """
+    return exc.InvalidArgumentError("IMAGE_DEFINITION_INVALID", message)
+
+
+class Image:
+    """An immutable image definition: a base plus an ordered list of layers.
+
+    Construct with one of the base factories
+    (:meth:`debian_slim` / :meth:`from_registry`) then chain layer methods.
+    """
+
+    __slots__ = ("_base", "_layers", "_context_data")
+
+    def __init__(
+        self,
+        base: Dict[str, Any],
+        layers: Sequence[Dict[str, Any]],
+        context_data: Optional[bytes] = None,
+    ) -> None:
+        # Private: use the factories. ``layers`` is copied to keep immutability.
+        self._base = base
+        self._layers: List[Dict[str, Any]] = list(layers)
+        # from_dockerfile build context (tar.gz bytes) — uploaded as a bundle
+        # when the build is created; its sha256 is in the base and thus in the
+        # hash, the bytes themselves never are (content-addressed identity).
+        self._context_data = context_data
+
+    # -- base factories -----------------------------------------------------
+
+    @classmethod
+    def debian_slim(cls, python_version: str = "3.12") -> "Image":
+        """Platform-maintained Debian slim base with the given Python.
+
+        ``python_version`` is ``major.minor`` (e.g. ``"3.12"``). The exact base
+        image digest is a server config, NOT part of the hash (image-dsl.md §5).
+        """
+        if not isinstance(python_version, str) or not _PYTHON_VERSION_RE.match(
+            python_version
+        ):
+            raise _invalid(
+                f"python_version must match '3.<minor>' (e.g. '3.12'), got "
+                f"{python_version!r}"
+            )
+        return cls({"kind": "debian_slim", "python_version": python_version}, [])
+
+    @classmethod
+    def mac_native(cls, python_version: str = "3.13") -> "Image":
+        """Native macOS (Apple Silicon) environment base — mac-nodes.md §4.2.
+
+        The "image" is a relocatable Python venv assembled with ``uv`` ON a
+        darwin/arm64 Mac node (no Docker involved) and distributed through the
+        registry as a darwin/arm64 artifact. Functions using it schedule on
+        Mac nodes only (e.g. ``gpu="M4"``).
+
+        Only :meth:`pip_install` layers can follow: there is no ``apt`` on
+        macOS (common system packages — ffmpeg, git, cmake — are preinstalled
+        on Mac nodes), no shell layer, and no baked env vars in v1.
+        """
+        if not isinstance(python_version, str) or not _PYTHON_VERSION_RE.match(
+            python_version
+        ):
+            raise _invalid(
+                f"python_version must match '3.<minor>' (e.g. '3.13'), got "
+                f"{python_version!r}"
+            )
+        return cls({"kind": "mac_native", "python_version": python_version}, [])
+
+    @classmethod
+    def from_registry(cls, ref: str) -> "Image":
+        """Base from an existing registry image (must carry an explicit tag/digest).
+
+        Same rule as run refs: no implicit ``latest``. The image must be
+        Linux and ship a Python if pip layers follow (else the build fails — a
+        user error, image-dsl.md §2).
+        """
+        if not isinstance(ref, str) or not ref:
+            raise _invalid("from_registry(ref): ref must be a non-empty string")
+        if ":" not in ref and "@" not in ref:
+            raise _invalid(
+                f"from_registry({ref!r}): ref needs an explicit tag (':') or "
+                "digest ('@') — no implicit 'latest'."
+            )
+        return cls({"kind": "registry", "ref": ref}, [])
+
+    @classmethod
+    def from_catalog(cls, alias: str) -> "Image":
+        """Base from an AI Fabric catalog image, by its alias (e.g. ``"fabric/torch"``).
+
+        Unlike :meth:`from_registry`, you pass the *catalog alias* — the same
+        string you'd use in ``image="fabric/torch"`` — NOT a registry URL. The
+        control plane resolves the alias to the real registry ref at build time,
+        so the underlying registry (and its host) never leaks into your code and
+        can move (e.g. to an external registry) without changing tutorials.
+
+        The alias is resolved server-side against the enabled catalogue; an
+        unknown or disabled alias fails the build with a clear error.
+        """
+        if not isinstance(alias, str) or not alias:
+            raise _invalid("from_catalog(alias): alias must be a non-empty string")
+        if not _CATALOG_ALIAS_RE.match(alias):
+            raise _invalid(
+                f"from_catalog({alias!r}): alias must look like a catalog name "
+                "(e.g. 'fabric/torch') — letters, digits, '.', '_', '-', '/'. "
+                "Pass a registry URL to from_registry() instead."
+            )
+        # Stored in its wire form, so fabric/x and forge/x hash (and cache) alike.
+        return cls({"kind": "catalog", "ref": to_wire_image(alias)}, [])
+
+    @classmethod
+    def from_dockerfile(
+        cls,
+        path: Any,
+        *,
+        context_dir: Any = None,
+        build_args: Optional[Mapping[str, str]] = None,
+    ) -> "Image":
+        """Base built from a local Dockerfile (docs/specs/image-from-dockerfile.md).
+
+        The Dockerfile is read EAGERLY (the returned ``Image`` stays immutable
+        and hashable; later edits to the file do not affect it). Layer methods
+        (:meth:`pip_install`, :meth:`env`, …) chain after it and are applied on
+        top of the Dockerfile's final stage.
+
+        ``context_dir`` is required iff the Dockerfile ``COPY``/``ADD``s local
+        files: the directory is packed (honoring a ``.dockerignore`` at its
+        root) and uploaded when the build is created. ``build_args`` are the
+        Dockerfile ``ARG`` values; they are part of the image identity.
+
+        Platform notes (same rules as :meth:`from_registry`): linux/amd64
+        only; the final stage must ship Python + pip (AI Fabric appends its
+        runtime layer there); your ``ENTRYPOINT``/``CMD`` is overridden by the
+        AI Fabric runtime entrypoint; the container runs as root.
+
+        Never put a secret in the Dockerfile or ``build_args`` — the
+        definition is stored in clear and hashed. Use :class:`bladekit.Secret`.
+        """
+        from pathlib import Path
+
+        p = Path(path)
+        try:
+            text = p.read_text(encoding="utf-8")
+        except OSError as e:
+            raise _invalid(f"from_dockerfile({str(path)!r}): cannot read Dockerfile: {e}")
+        if not text.strip():
+            raise _invalid(f"from_dockerfile({str(path)!r}): the Dockerfile is empty")
+        if len(text.encode("utf-8")) > _MAX_DOCKERFILE_BYTES:
+            raise _invalid(
+                f"from_dockerfile({str(path)!r}): Dockerfile exceeds the "
+                f"{_MAX_DOCKERFILE_BYTES}-byte (32 KiB) limit"
+            )
+
+        base: Dict[str, Any] = {"kind": "dockerfile", "dockerfile": text}
+
+        if build_args:
+            if not isinstance(build_args, Mapping):
+                raise _invalid("from_dockerfile: build_args must be a mapping of strings")
+            if len(build_args) > _MAX_BUILD_ARGS:
+                raise _invalid(
+                    f"from_dockerfile: too many build_args ({len(build_args)} > {_MAX_BUILD_ARGS})"
+                )
+            clean: Dict[str, str] = {}
+            total = 0
+            for k, v in build_args.items():
+                if not isinstance(k, str) or not _BUILD_ARG_KEY_RE.match(k):
+                    raise _invalid(
+                        f"from_dockerfile: invalid build arg name {k!r}; must match "
+                        "'^[A-Za-z_][A-Za-z0-9_]*$'"
+                    )
+                if not isinstance(v, str):
+                    raise _invalid(f"from_dockerfile: build arg {k!r} value must be a string")
+                total += len(k.encode("utf-8")) + len(v.encode("utf-8"))
+                clean[k] = v
+            if total > _MAX_BUILD_ARGS_BYTES:
+                raise _invalid(
+                    f"from_dockerfile: build_args exceed {_MAX_BUILD_ARGS_BYTES} total bytes"
+                )
+            base["build_args"] = clean
+
+        context_data: Optional[bytes] = None
+        if context_dir is not None:
+            ctx = Path(context_dir)
+            if not ctx.is_dir():
+                raise _invalid(
+                    f"from_dockerfile: context_dir {str(context_dir)!r} is not a directory"
+                )
+            from ._bundle import build_context_bundle
+
+            context_data, context_sha, _ = build_context_bundle(ctx)
+            base["context_sha256"] = context_sha
+        elif _dockerfile_reads_context(text):
+            # Client-side mirror of the server's dockerfile_needs_context 400:
+            # an immediate, actionable error at the constructor call site.
+            raise _invalid(
+                f"from_dockerfile({str(path)!r}): the Dockerfile COPY/ADDs local "
+                "files but no build context was given — pass "
+                "context_dir=<directory containing those files>"
+            )
+
+        return cls(base, [], context_data)
+
+    # -- layer builders (return a new Image) --------------------------------
+
+    def _with_layer(self, layer: Dict[str, Any]) -> "Image":
+        if len(self._layers) >= _MAX_LAYERS:
+            raise _invalid(
+                f"too many layers (max {_MAX_LAYERS}); collapse steps or use "
+                "run_commands."
+            )
+        return Image(self._base, [*self._layers, layer], self._context_data)
+
+    def _reject_on_mac_native(self, op: str, hint: str) -> None:
+        """Mirror the server-side mac_native restriction (mac-nodes.md §4.2).
+
+        A native macOS env build understands pip layers only; rejecting the
+        other verbs at the offending call gives an immediate, actionable error
+        instead of a 400 at build submission.
+        """
+        if self._base.get("kind") == "mac_native":
+            raise _invalid(f"{op}: not supported on a mac_native base — {hint}")
+
+    @staticmethod
+    def _check_packages(op: str, packages: Sequence[str]) -> List[str]:
+        pkgs = list(packages)
+        if not pkgs:
+            raise _invalid(f"{op}: at least one package is required")
+        if len(pkgs) > _MAX_PACKAGES_PER_LAYER:
+            raise _invalid(
+                f"{op}: too many packages ({len(pkgs)} > {_MAX_PACKAGES_PER_LAYER})"
+            )
+        for p in pkgs:
+            if not isinstance(p, str) or not p:
+                raise _invalid(f"{op}: package names must be non-empty strings")
+        return pkgs
+
+    def apt_install(self, *packages: str) -> "Image":
+        """Append an ``apt_install`` layer (Debian package names, no shell)."""
+        self._reject_on_mac_native(
+            "apt_install",
+            "there is no apt on macOS; common system packages (ffmpeg, git, "
+            "cmake) are preinstalled on Mac nodes",
+        )
+        pkgs = self._check_packages("apt_install", packages)
+        return self._with_layer({"op": "apt_install", "packages": pkgs})
+
+    def pip_install(
+        self,
+        *packages: str,
+        index_url: Optional[str] = None,
+        extra_index_urls: Optional[Sequence[str]] = None,
+    ) -> "Image":
+        """Append a ``pip_install`` layer (PEP 508 specifiers).
+
+        Pinning versions is recommended: two builds of the same hash can resolve
+        differently otherwise (assumed, image-dsl.md §5).
+        """
+        pkgs = self._check_packages("pip_install", packages)
+        layer: Dict[str, Any] = {"op": "pip_install", "packages": pkgs}
+        if index_url is not None:
+            if not isinstance(index_url, str) or not index_url:
+                raise _invalid("pip_install: index_url must be a non-empty string")
+            _check_index_url("pip_install", "index_url", index_url)
+            layer["index_url"] = index_url
+        if extra_index_urls:
+            urls = list(extra_index_urls)
+            for u in urls:
+                if not isinstance(u, str) or not u:
+                    raise _invalid(
+                        "pip_install: extra_index_urls must be non-empty strings"
+                    )
+                _check_index_url("pip_install", "extra_index_urls", u)
+            layer["extra_index_urls"] = urls
+        return self._with_layer(layer)
+
+    def env(self, vars: Mapping[str, str]) -> "Image":
+        """Append an ``env`` layer. Keys ``^[A-Z_][A-Z0-9_]*$``, never ``FABRIC_*``/``FORGE_*``.
+
+        Never put a secret here: the definition is stored in clear and hashed —
+        use :class:`bladekit.Secret` (image-dsl.md §2).
+        """
+        self._reject_on_mac_native(
+            "env",
+            "baked env vars are not supported in v1; set environment "
+            "variables via bladekit.Secret or the function definition instead",
+        )
+        if not isinstance(vars, Mapping) or not vars:
+            raise _invalid("env(vars): a non-empty mapping is required")
+        if len(vars) > _MAX_ENV_VARS_PER_LAYER:
+            raise _invalid(
+                f"env: too many vars ({len(vars)} > {_MAX_ENV_VARS_PER_LAYER})"
+            )
+        clean: Dict[str, str] = {}
+        for k, v in vars.items():
+            if not isinstance(k, str) or not _ENV_KEY_RE.match(k):
+                raise _invalid(
+                    f"env: invalid key {k!r}; must match '^[A-Z_][A-Z0-9_]*$'"
+                )
+            # FABRIC_ too, client-side: the SDK reads FABRIC_* before FORGE_*, so a
+            # baked FABRIC_API_URL would shadow what the control plane injects.
+            reserved = next((p for p in RESERVED_ENV_PREFIXES if k.startswith(p)), None)
+            if reserved:
+                raise _invalid(
+                    f"env: key {k!r} is reserved ({reserved} prefix is runtime-only)"
+                )
+            if not isinstance(v, str):
+                raise _invalid(f"env: value for {k!r} must be a string")
+            clean[k] = v
+        return self._with_layer({"op": "env", "vars": clean})
+
+    def run_commands(self, *commands: str) -> "Image":
+        """Append a ``run_commands`` layer (each command is one ``RUN`` / cache step)."""
+        self._reject_on_mac_native(
+            "run_commands",
+            "a mac env build runs uv commands only, not arbitrary shell",
+        )
+        cmds = list(commands)
+        if not cmds:
+            raise _invalid("run_commands: at least one command is required")
+        if len(cmds) > _MAX_COMMANDS_PER_LAYER:
+            raise _invalid(
+                f"run_commands: too many commands ({len(cmds)} > "
+                f"{_MAX_COMMANDS_PER_LAYER})"
+            )
+        for c in cmds:
+            if not isinstance(c, str) or not c:
+                raise _invalid("run_commands: commands must be non-empty strings")
+            if "\n" in c or "\r" in c:
+                raise _invalid(
+                    "run_commands: commands must not contain newline characters "
+                    "(\\n or \\r); each command is a single shell line"
+                )
+        return self._with_layer({"op": "run_commands", "commands": cmds})
+
+    # -- serialization & hash (NORMATIVE — image-dsl.md §2/§3) --------------
+
+    def to_definition(self, *, sandbox: bool = False) -> Dict[str, Any]:
+        """Return the definition object (version, base, layers).
+
+        Optional/empty fields are already absent (the builders never add empties),
+        so this is the pre-hash representation per §3 rule 5.
+
+        ``sandbox=True`` marks the build as a SANDBOX image: the server injects
+        forge-sandboxd as PID 1 / entrypoint instead of forge-runner
+        (sandbox-protocol.md §3). It is part of the canonical JSON (and thus the
+        hash), so a sandbox build never collides with the function build of the
+        same base/layers.
+        """
+        if sandbox and self._base.get("kind") == "mac_native":
+            # Mirrors the server rule: sandboxes are Linux containers
+            # (runc/runsc) — a native mac env can never back one.
+            raise _invalid(
+                "sandbox images are not supported on a mac_native base "
+                "(sandboxes are Linux containers)"
+            )
+        d: Dict[str, Any] = {
+            "version": _DEFINITION_VERSION,
+            "base": dict(self._base),
+            "layers": [dict(layer) for layer in self._layers],
+        }
+        if sandbox:
+            d["sandbox"] = True
+        return d
+
+    def canonical_json(self, *, sandbox: bool = False) -> str:
+        """Canonical JSON string (image-dsl.md §3): sorted keys, no spaces, UTF-8."""
+        return json.dumps(
+            self.to_definition(sandbox=sandbox),
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        )
+
+    def definition_hash(self, *, sandbox: bool = False) -> str:
+        """Lowercase-hex sha256 of the canonical JSON bytes (image-dsl.md §3)."""
+        data = self.canonical_json(sandbox=sandbox).encode("utf-8")
+        if len(data) > _CANONICAL_MAX_BYTES:
+            raise _invalid(
+                f"image definition is {len(data)} bytes, over the "
+                f"{_CANONICAL_MAX_BYTES}-byte (64 KiB) limit (conventions.md §6)."
+            )
+        return hashlib.sha256(data).hexdigest()
+
+    def __repr__(self) -> str:
+        kind = self._base.get("kind")
+        return f"<bladekit.Image base={kind!r} layers={len(self._layers)} hash={self.definition_hash()[:12]}…>"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Image):
+            return NotImplemented
+        return self.canonical_json() == other.canonical_json()
+
+    def __hash__(self) -> int:
+        return hash(self.canonical_json())

bladekit/_loader.py

@@ -0,0 +1,79 @@
+"""Load a user script as a module so its ``bladekit.App`` and decorators register.
+
+``blade run script.py`` must:
+- set the bundle root to the script's directory,
+- import the script under its file-stem module name (so the remote runner can
+  import the same module from the bundle root — see App._module_for),
+- discover the App and its @app.local_entrypoint.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import List, Tuple
+
+from . import exceptions as exc
+from ._app import App
+
+
+def load_script(script_path: Path) -> Tuple[ModuleType, str, Path]:
+    """Import ``script_path`` and return ``(module, module_name, bundle_root)``.
+
+    ``module_name`` is the file stem (the name the bundle root will expose), and
+    ``bundle_root`` is the script's parent directory.
+    """
+    script_path = script_path.resolve()
+    if not script_path.exists():
+        raise exc.FabricError(f"script not found: {script_path}")
+
+    bundle_root = script_path.parent
+    module_name = script_path.stem
+
+    # Make sibling modules importable both locally and consistently with the
+    # remote runner (which inserts the bundle root on sys.path).
+    if str(bundle_root) not in sys.path:
+        sys.path.insert(0, str(bundle_root))
+
+    # Remove any stale cached module under this name (e.g. from a prior
+    # load_script() call in the same process — common in tests). Leaving the
+    # old module in sys.modules would cause importlib to skip re-execution and
+    # return the stale object instead of the freshly-loaded one.
+    sys.modules.pop(module_name, None)
+
+    spec = importlib.util.spec_from_file_location(module_name, script_path)
+    if spec is None or spec.loader is None:
+        raise exc.FabricError(f"cannot import {script_path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module, module_name, bundle_root
+
+
+def find_apps(module: ModuleType) -> List[App]:
+    return [v for v in vars(module).values() if isinstance(v, App)]
+
+
+def select_app_and_entrypoint(module: ModuleType):
+    """Return ``(app, entrypoint)`` from a loaded module.
+
+    Requires exactly one App with at least one @app.local_entrypoint for
+    ``blade run``.
+    """
+    apps = find_apps(module)
+    if not apps:
+        raise exc.FabricError("no bladekit.App found in script")
+    if len(apps) > 1:
+        raise exc.FabricError(
+            f"multiple bladekit.App objects found ({len(apps)}); only one is supported per script"
+        )
+    app = apps[0]
+    if not app.local_entrypoints:
+        raise exc.FabricError(
+            "no @app.local_entrypoint found; `blade run` needs one to invoke"
+        )
+    if len(app.local_entrypoints) > 1:
+        raise exc.FabricError("multiple @app.local_entrypoint found; expected one")
+    return app, app.local_entrypoints[0]