kanibako-cli 1.5.0.dev14__py3-none-any.whl

kanibako/plugins/__init__.py

@@ -0,0 +1,10 @@
+"""Namespace package for kanibako plugins.
+
+Uses pkgutil.extend_path so that plugin packages installed in separate
+source trees (e.g. editable installs from packages/agent-claude/src/)
+merge into a single kanibako.plugins namespace.
+"""
+
+import pkgutil
+
+__path__ = pkgutil.extend_path(__path__, __name__)

kanibako/registry.py

@@ -0,0 +1,71 @@
+"""OCI Distribution API client for querying remote image digests (stdlib only)."""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+import urllib.error
+
+_TIMEOUT = 5
+
+
+def get_remote_digest(image: str) -> str | None:
+    """Return the remote manifest digest for *image*, or None on any failure."""
+    try:
+        registry, repo, tag = _parse_image_ref(image)
+        token = _get_anonymous_token(registry, repo)
+        return _fetch_manifest_digest(registry, repo, tag, token)
+    except Exception:
+        return None
+
+
+def _parse_image_ref(image: str) -> tuple[str, str, str]:
+    """Split ``registry/owner/name:tag`` into ``(registry, owner/name, tag)``.
+
+    Raises ``ValueError`` if the format is unrecognised.
+    """
+    # Strip tag
+    if ":" in image.rsplit("/", 1)[-1]:
+        ref, tag = image.rsplit(":", 1)
+    else:
+        ref, tag = image, "latest"
+
+    parts = ref.split("/")
+    if len(parts) < 3:
+        raise ValueError(f"Cannot parse image reference: {image}")
+    registry = parts[0]
+    repo = "/".join(parts[1:])
+    return registry, repo, tag
+
+
+def _get_anonymous_token(registry: str, repo: str) -> str | None:
+    """Obtain a bearer token for anonymous pulls (GHCR only for now)."""
+    if registry != "ghcr.io":
+        return None
+
+    url = f"https://ghcr.io/token?scope=repository:{repo}:pull"
+    req = urllib.request.Request(url, headers={"User-Agent": "kanibako"})
+    with urllib.request.urlopen(req, timeout=_TIMEOUT) as resp:
+        data = json.loads(resp.read())
+    return data.get("token")
+
+
+def _fetch_manifest_digest(
+    registry: str, repo: str, tag: str, token: str | None,
+) -> str | None:
+    """HEAD the manifest to read ``Docker-Content-Digest``."""
+    url = f"https://{registry}/v2/{repo}/manifests/{tag}"
+    headers: dict[str, str] = {
+        "User-Agent": "kanibako",
+        "Accept": (
+            "application/vnd.docker.distribution.manifest.v2+json, "
+            "application/vnd.oci.image.index.v1+json"
+        ),
+    }
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    req = urllib.request.Request(url, method="HEAD", headers=headers)
+    with urllib.request.urlopen(req, timeout=_TIMEOUT) as resp:
+        digest = resp.headers.get("Docker-Content-Digest")
+    return digest

kanibako/rig_bundle.py

@@ -0,0 +1,121 @@
+"""The ``.rig.tgz`` export bundle for *extended* rigs.
+
+Extended rigs have no external source to re-pull or rebuild from, so they
+travel as a single self-contained bundle. A bundle is a gzip tar containing:
+
+* ``rig.yaml``      -- the in-image :class:`~kanibako.rig_meta.RigMeta` metadata
+* ``image.tar``     -- a ``podman save`` of the rig image
+* ``Containerfile`` -- optional, informational build recipe
+
+Packing and unpacking use the stdlib :mod:`tarfile` (gzip) only -- no shelling
+out. Extraction is path-traversal-safe.
+"""
+
+from __future__ import annotations
+
+import tarfile
+from pathlib import Path
+
+from kanibako.rig_meta import RigMeta, load_rig_meta
+
+BUNDLE_SUFFIX = ".rig.tgz"
+
+_META_ARCNAME = "rig.yaml"
+_IMAGE_ARCNAME = "image.tar"
+_CONTAINERFILE_ARCNAME = "Containerfile"
+
+
+def pack_bundle(
+    out: Path,
+    rig_yaml: Path,
+    image_tar: Path,
+    containerfile: Path | None = None,
+) -> None:
+    """Pack *rig_yaml* + *image_tar* (+ optional *containerfile*) into *out*.
+
+    *out* is created as a gzip tar with the metadata stored as ``rig.yaml``,
+    the saved image as ``image.tar`` and, when supplied, the build recipe as
+    ``Containerfile``. Raises :class:`FileNotFoundError` if *rig_yaml* or
+    *image_tar* is missing.
+    """
+    if not rig_yaml.is_file():
+        raise FileNotFoundError(f"rig metadata not found: {rig_yaml}")
+    if not image_tar.is_file():
+        raise FileNotFoundError(f"image tarball not found: {image_tar}")
+
+    with tarfile.open(out, "w:gz") as tar:
+        tar.add(rig_yaml, arcname=_META_ARCNAME)
+        tar.add(image_tar, arcname=_IMAGE_ARCNAME)
+        if containerfile is not None:
+            tar.add(containerfile, arcname=_CONTAINERFILE_ARCNAME)
+
+
+def _is_safe_member(name: str) -> bool:
+    """Return True if *name* is a safe, in-tree relative arcname.
+
+    Rejects absolute paths and any path that escapes the destination via a
+    ``..`` component (guarding against tar path-traversal attacks).
+    """
+    member = Path(name)
+    if member.is_absolute():
+        return False
+    return ".." not in member.parts
+
+
+def unpack_bundle(tgz: Path, dest_dir: Path) -> dict[str, Path]:
+    """Extract bundle *tgz* into *dest_dir*, returning the member paths.
+
+    Extraction is path-traversal-safe: any member whose name is absolute or
+    contains a ``..`` component is rejected (raises :class:`ValueError`). The
+    returned dict maps ``"rig_yaml"`` / ``"image_tar"`` to their extracted
+    paths, plus ``"containerfile"`` only when one was present. Raises
+    :class:`ValueError` if the required ``rig.yaml`` or ``image.tar`` members
+    are absent.
+    """
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    with tarfile.open(tgz, "r:gz") as tar:
+        members = tar.getmembers()
+        names = {m.name for m in members}
+
+        for member in members:
+            if not _is_safe_member(member.name):
+                raise ValueError(
+                    f"unsafe member name in bundle: {member.name!r}"
+                )
+
+        if _META_ARCNAME not in names:
+            raise ValueError(f"bundle is missing required '{_META_ARCNAME}'")
+        if _IMAGE_ARCNAME not in names:
+            raise ValueError(f"bundle is missing required '{_IMAGE_ARCNAME}'")
+
+        for member in members:
+            tar.extract(member, path=dest_dir, filter="data")
+
+    result: dict[str, Path] = {
+        "rig_yaml": dest_dir / _META_ARCNAME,
+        "image_tar": dest_dir / _IMAGE_ARCNAME,
+    }
+    if _CONTAINERFILE_ARCNAME in names:
+        result["containerfile"] = dest_dir / _CONTAINERFILE_ARCNAME
+    return result
+
+
+def read_bundle_meta(tgz: Path) -> RigMeta:
+    """Read just the ``rig.yaml`` member of *tgz* and return its :class:`RigMeta`.
+
+    Reads the metadata directly out of the tar without extracting the
+    (potentially large) ``image.tar``. Raises :class:`ValueError` if the
+    ``rig.yaml`` member is absent.
+    """
+    with tarfile.open(tgz, "r:gz") as tar:
+        try:
+            handle = tar.extractfile(_META_ARCNAME)
+        except KeyError:
+            handle = None
+        if handle is None:
+            raise ValueError(f"bundle is missing required '{_META_ARCNAME}'")
+        with handle:
+            text = handle.read().decode("utf-8")
+
+    return load_rig_meta(text)

kanibako/rig_meta.py

@@ -0,0 +1,92 @@
+"""Truth-in-image metadata for *extended* rigs (``/etc/kanibako/rig.yaml``).
+
+An extended rig is an interactively-built, non-reproducible image: there is no
+external source to re-pull or rebuild from, so its identity must travel *inside*
+the image itself. This module defines that in-image metadata file and its
+serialization.
+
+Because the metadata lives at a fixed path inside the rootfs, it rides
+``podman save`` / ``load`` / ``push`` natively -- whoever ends up with the image
+also ends up with its ``rig.yaml``, no side-channel required.
+
+All on-disk serialization goes through PyYAML (``yaml.safe_load`` /
+``yaml.safe_dump``); there is no hand-rolled serializer here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from pathlib import Path
+
+import yaml  # type: ignore[import-untyped]
+
+
+@dataclass
+class RigMeta:
+    """In-image metadata for an extended rig.
+
+    ``name`` is the short rig name; ``parent`` and ``foundation_source`` are
+    arbitrary image references / source descriptors (not validated here).
+    ``recipe`` is an optional captured shell history of the steps that built
+    the rig (informational only -- extended rigs are not reproducible).
+    """
+
+    name: str
+    kind: str = "extended"
+    parent: str | None = None
+    foundation_source: str | None = None
+    reproducible: bool = False
+    created: str | None = None
+    recipe: list[str] | None = None
+
+
+# Field names in a stable, file-friendly order, used to filter unknown keys on
+# load and to drive the ordered dump below.
+_FIELD_NAMES: tuple[str, ...] = tuple(f.name for f in fields(RigMeta))
+
+# Fields that are always emitted, even when falsy (False / empty).
+_ALWAYS: frozenset[str] = frozenset({"name", "kind", "reproducible"})
+
+
+def dump_rig_meta(meta: RigMeta) -> str:
+    """Serialize *meta* to a YAML string.
+
+    ``name``, ``kind`` and ``reproducible`` are always emitted. The remaining
+    fields are omitted when ``None`` so the file stays clean (in particular
+    ``recipe`` disappears entirely when unset). Field order is stable and
+    readable (``sort_keys=False``).
+    """
+    data: dict[str, object] = {}
+    for field_name in _FIELD_NAMES:
+        value = getattr(meta, field_name)
+        if field_name not in _ALWAYS and value is None:
+            continue
+        data[field_name] = value
+    return yaml.safe_dump(data, sort_keys=False)
+
+
+def write_rig_meta(meta: RigMeta, path: Path) -> None:
+    """Write *meta* to *path*, creating the parent directory if needed."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(dump_rig_meta(meta))
+
+
+def load_rig_meta(source: str | Path) -> RigMeta:
+    """Load a :class:`RigMeta` from a file *path* or a raw YAML *string*.
+
+    A :class:`~pathlib.Path` is read from disk; a ``str`` is parsed directly as
+    YAML text. Unknown keys are ignored defensively (only known fields are
+    passed to the constructor). Raises :class:`ValueError` if the document is
+    empty/invalid or is missing the required ``name`` field.
+    """
+    text = source.read_text() if isinstance(source, Path) else source
+
+    data = yaml.safe_load(text)
+    if not isinstance(data, dict):
+        raise ValueError("rig.yaml must be a non-empty YAML mapping")
+
+    kwargs = {k: v for k, v in data.items() if k in _FIELD_NAMES}
+    if not kwargs.get("name"):
+        raise ValueError("rig.yaml is missing the required 'name' field")
+
+    return RigMeta(**kwargs)

kanibako/rig_registry.py

@@ -0,0 +1,132 @@
+"""Host-side rig registry stored in a single ``rigs.yaml`` file.
+
+Pure load/save/query helpers for "added" rig records, keyed by rig name.
+Rig names may contain ``/`` and ``:`` (e.g. ``"corp/base:1.0"``); they are
+emitted as plain YAML mapping keys (PyYAML quotes them as needed).
+
+Reads and writes go through PyYAML (``yaml.safe_load`` / ``yaml.safe_dump``).
+PyYAML handles all escaping and quoting, so there is no hand-rolled
+serializer here.
+
+No network, no global state: the registry path is always passed in.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import yaml
+
+if TYPE_CHECKING:
+    from kanibako.paths import StandardPaths
+
+
+@dataclass
+class RigRecord:
+    """A single "added" rig record.
+
+    ``name`` is also the registry key; the remaining fields are optional and
+    carry whatever metadata is relevant to the rig's kind (prefab / extended).
+    """
+
+    name: str
+    kind: str
+    source: str | None = None
+    source_type: str | None = None
+    image: str | None = None
+    parent: str | None = None
+    foundation_source: str | None = None
+    reproducible: bool | None = None
+    created: str | None = None
+    added: str | None = None
+
+
+# Fields stored *inside* the table (i.e. everything except ``name``, which is
+# the mapping key) in a stable, file-friendly order.
+_INNER_FIELDS: tuple[str, ...] = tuple(
+    f.name for f in fields(RigRecord) if f.name != "name"
+)
+
+
+def registry_path(std: StandardPaths) -> Path:
+    """Return the path to ``rigs.yaml`` under the standard data directory."""
+    return std.data_path / "rigs.yaml"
+
+
+def load_registry(path: Path) -> dict[str, RigRecord]:
+    """Load all rig records from *path*, keyed by rig name.
+
+    A missing or empty file yields an empty dict.  The file is shaped as a
+    top-level ``rigs:`` mapping whose keys are rig names::
+
+        rigs:
+          corp/base:1.0:
+            kind: prefab
+            ...
+    """
+    if not path.exists():
+        return {}
+
+    data = yaml.safe_load(path.read_text())
+    if not data:
+        return {}
+
+    rigs = data.get("rigs", {})
+    records: dict[str, RigRecord] = {}
+    for name, table in rigs.items():
+        kwargs: dict[str, object] = {"name": name}
+        for field_name in _INNER_FIELDS:
+            if field_name in table:
+                kwargs[field_name] = table[field_name]
+        records[name] = RigRecord(**kwargs)  # type: ignore[arg-type]
+    return records
+
+
+def save_registry(path: Path, records: dict[str, RigRecord]) -> None:
+    """Write *records* to *path* as a ``rigs:`` mapping (one entry per record).
+
+    ``None``-valued fields are omitted so the file stays clean.  ``name`` is the
+    mapping key and is not duplicated inside the entry.  The parent directory is
+    created if needed.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    rigs: dict[str, dict[str, object]] = {}
+    for name, record in records.items():
+        table: dict[str, object] = {}
+        for field_name in _INNER_FIELDS:
+            value = getattr(record, field_name)
+            if value is None:
+                continue
+            table[field_name] = value
+        rigs[name] = table
+
+    data = {"rigs": rigs}
+    path.write_text(yaml.safe_dump(data, sort_keys=False))
+
+
+def upsert(path: Path, record: RigRecord) -> None:
+    """Insert *record* (or overwrite the existing record with the same name)."""
+    records = load_registry(path)
+    records[record.name] = record
+    save_registry(path, records)
+
+
+def remove(path: Path, name: str) -> bool:
+    """Remove the record named *name*.
+
+    Returns ``True`` if a record was removed, ``False`` if it was absent.
+    """
+    records = load_registry(path)
+    if name not in records:
+        return False
+    del records[name]
+    save_registry(path, records)
+    return True
+
+
+def get(path: Path, name: str) -> RigRecord | None:
+    """Return the record named *name*, or ``None`` if it is not registered."""
+    return load_registry(path).get(name)

kanibako/rig_resolve.py

@@ -0,0 +1,182 @@
+"""Pure rig-name resolution: classify a rig name into kind + prep action.
+
+A *rig* is a container image a box can start from. This module answers the
+question "given a name the user typed, what kind of rig is it and what (if
+anything) must happen before it can be used?" -- WITHOUT performing any side
+effects. It never pulls, builds, or commits; that is :func:`prep`'s job in a
+later increment. Resolution only inspects the local image store, the bundled /
+user-override template Containerfiles, and (eventually) the rig registry.
+
+Kinds:
+    ``"prefab"``    -- a published/base image, made ready by pulling.
+    ``"template"``  -- a buildable ``Containerfile.template-<name>``.
+    ``"extended"``  -- an interactively built, non-reproducible image.
+
+Prep actions:
+    ``"none"``     -- already prepped (the image exists locally).
+    ``"pull"``     -- pull from a registry to prep.
+    ``"build"``    -- build a Containerfile to prep.
+    ``"missing"``  -- cannot be resolved (reserved; not produced yet).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from kanibako.containerfiles import get_containerfile
+from kanibako.templates_image import (
+    list_bundled_templates,
+    rig_image_name,
+    template_image_name,
+)
+
+if TYPE_CHECKING:
+    from kanibako.config import KanibakoConfig
+    from kanibako.container import ContainerRuntime
+    from kanibako.paths import StandardPaths
+    from kanibako.rig_registry import RigRecord
+
+
+@dataclass(frozen=True)
+class RigResolution:
+    """The classification of a rig name.
+
+    *kind* is one of ``"prefab"``, ``"template"``, ``"extended"``.
+    *prep_action* is one of ``"pull"``, ``"build"``, ``"none"``, ``"missing"``.
+    *image* is the OCI reference a prepped rig is (or will be) stored under.
+    *containerfile* is set for buildable templates that need building.
+    *source_ref* carries the original/source reference for prefabs (reserved).
+    """
+
+    name: str
+    kind: str
+    image: str
+    prep_action: str
+    containerfile: Path | None = None
+    source_ref: str | None = None
+
+
+def resolve_rig(
+    name: str,
+    runtime: ContainerRuntime,
+    std: StandardPaths,
+    merged: KanibakoConfig,
+    *,
+    registry: dict[str, RigRecord] | None = None,
+) -> RigResolution:
+    """Classify rig *name* into a :class:`RigResolution`. Pure -- no side effects.
+
+    Precedence:
+
+    1. **Already-prepped local image.** If a ``kanibako-template-<name>`` or
+       ``kanibako-rig-<name>`` image exists locally, it is already prepped
+       (``prep_action="none"``) with kind ``"template"`` / ``"extended"``.
+    2. **Discovered template.** If *name* matches a bundled or user-override
+       ``Containerfile.template-<name>``, it is a buildable template
+       (``prep_action="build"``).
+    3. **Resolvable reference / prefab.** Otherwise defer to
+       :func:`resolve_image_reference`; the rig is a ``"prefab"`` made ready by
+       ``"pull"`` (or ``"none"`` if the resolved image already exists locally).
+
+    Between steps 1 and 2, if *registry* is provided and contains *name*, the
+    matching record decides the result: an ``"extended"`` record resolves to its
+    recorded image (``"none"`` if present locally, else ``"missing"``); any other
+    (prefab) record resolves to its image / source reference made ready by
+    ``"pull"`` (or ``"none"`` if already local). Passing ``None`` skips this step.
+    """
+    # --- (a) Already-prepped local image -------------------------------
+    # rig_image_name / template_image_name raise on names that aren't valid
+    # short template names (e.g. anything with '/' or ':'); those can't be a
+    # locally-prepped template/extended image, so just skip this step for them.
+    try:
+        extended_image = rig_image_name(name)
+        template_image = template_image_name(name)
+    except ValueError:
+        extended_image = None
+        template_image = None
+
+    if template_image is not None and runtime.image_exists(template_image):
+        return RigResolution(
+            name=name,
+            kind="template",
+            image=template_image,
+            prep_action="none",
+        )
+    if extended_image is not None and runtime.image_exists(extended_image):
+        return RigResolution(
+            name=name,
+            kind="extended",
+            image=extended_image,
+            prep_action="none",
+        )
+
+    # --- (a2) Host registry (added rigs: prefabs / imported extended) --
+    if registry is not None and name in registry:
+        record = registry[name]
+        if record.kind == "extended":
+            # Extended rigs normally carry their recorded image and a valid
+            # short name (so extended_image is set). Guard the malformed case
+            # -- no recorded image AND a name that isn't a valid default-image
+            # name (extended_image is None) -- by falling back to the name
+            # itself, rather than re-calling rig_image_name(name) which would
+            # raise the same ValueError that already nulled extended_image.
+            img = record.image or extended_image or name
+            action = "none" if runtime.image_exists(img) else "missing"
+            return RigResolution(
+                name=name,
+                kind="extended",
+                image=img,
+                prep_action=action,
+                source_ref=record.source,
+            )
+        # prefab (or any other registry kind): pull-based.
+        if record.image:
+            img = record.image
+        else:
+            # Lazy import to avoid a circular import (see step (c)).
+            from kanibako.commands.image import resolve_image_reference
+
+            img = resolve_image_reference(
+                record.source or name, runtime, merged.box_image
+            )
+        action = "none" if runtime.image_exists(img) else "pull"
+        return RigResolution(
+            name=name,
+            kind=record.kind,
+            image=img,
+            prep_action=action,
+            source_ref=record.source,
+        )
+
+    # --- (b) Discovered template (buildable Containerfile) -------------
+    containers_dir = std.data_path / "containers"
+    discovered = {t.name for t in list_bundled_templates(override_dir=containers_dir)}
+    if name in discovered:
+        containerfile = get_containerfile(f"template-{name}", containers_dir)
+        return RigResolution(
+            name=name,
+            # template_image is non-None here: a discovered template name is a
+            # valid short name, so template_image_name didn't raise above.
+            kind="template",
+            image=template_image or template_image_name(name),
+            prep_action="build",
+            containerfile=containerfile,
+        )
+
+    # --- (c) Known base / resolvable reference (prefab) ---------------
+    # Imported lazily to avoid a circular import: commands.image imports
+    # resolve_rig (from Increment 2 onward), and this module would otherwise
+    # import commands.image at load time.
+    from kanibako.commands.image import resolve_image_reference
+
+    resolved = resolve_image_reference(name, runtime, merged.box_image)
+    prep_action = "none" if runtime.image_exists(resolved) else "pull"
+    return RigResolution(
+        name=name,
+        kind="prefab",
+        image=resolved,
+        prep_action=prep_action,
+        source_ref=name,
+    )