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

kanibako/rig_source.py

@@ -0,0 +1,245 @@
+"""Source detection + name derivation for the future ``rig add`` command.
+
+Given a *source* string -- a local file path, a registry reference, or a URL --
+these pure helpers decide whether the source describes an OCI **image** (a
+prefab to pull / a saved image tar to load) or a buildable **template**
+(a Containerfile), and derive a sensible default rig name.
+
+The core helpers do **no network I/O**. A raw ``http(s)://`` URL is undecidable
+on its own; the caller is expected to fetch it first via :func:`fetch_to_temp`
+(a thin, separately monkeypatchable wrapper) and then classify the downloaded
+file with :func:`detect_source_kind`.
+"""
+
+from __future__ import annotations
+
+import re
+import tarfile
+import tempfile
+import urllib.request
+from pathlib import Path
+
+# How many leading lines to scan when sniffing a text file for template signals.
+_TEMPLATE_SCAN_LINES = 20
+
+# Header conventions mirrored from templates_image.py. We only need to *detect*
+# their presence here, so a loose prefix match is enough.
+_TEMPLATE_HEADER_RE = re.compile(
+    r"^#\s*kanibako-template(?:-check)?:\s*", re.IGNORECASE
+)
+
+# A leading ``FROM <image>`` directive marks a Containerfile/Dockerfile.
+_FROM_DIRECTIVE_RE = re.compile(r"^\s*FROM\s+\S", re.IGNORECASE)
+
+# Loose OCI registry-reference grammar: ``[registry/]repo[:tag][@digest]``.
+# Lowercased before matching. Allows path segments separated by ``/`` and the
+# usual ``.``/``-``/``_`` separators within a segment, an optional ``:tag`` and
+# an optional ``@sha256:<hex>`` digest.
+_REF_RE = re.compile(
+    r"^[a-z0-9]+([._-][a-z0-9]+)*"  # first segment (registry host or repo)
+    r"(:[0-9]+)?"  # optional :port on the host segment
+    r"(/[a-z0-9]+([._-][a-z0-9]+)*)*"  # further /path segments
+    r"(:[\w][\w.-]*)?"  # optional :tag
+    r"(@sha256:[a-f0-9]+)?$",  # optional @digest
+)
+
+# Members whose presence in a tar marks it as an OCI / docker-save image archive.
+_IMAGE_TAR_MARKERS = ("manifest.json", "oci-layout")
+
+
+def fetch_to_temp(url: str) -> Path:
+    """Download *url* to a temporary file and return its :class:`Path`.
+
+    Thin wrapper over :func:`urllib.request.urlretrieve` so that callers can
+    fetch a remote source before classifying it, and tests can monkeypatch the
+    network hop. The temp file is **not** auto-deleted; the caller owns cleanup.
+    """
+    fd, tmp_name = tempfile.mkstemp(prefix="kanibako-rig-src-")
+    # Close our handle; urlretrieve manages the file by name.
+    import os
+
+    os.close(fd)
+    urllib.request.urlretrieve(url, tmp_name)
+    return Path(tmp_name)
+
+
+def _is_image_tar(path: str) -> bool:
+    """Return True if *path* is a tar whose members mark it as an image archive."""
+    if not tarfile.is_tarfile(path):
+        return False
+    try:
+        with tarfile.open(path) as tar:
+            names = tar.getnames()
+    except (tarfile.TarError, OSError):
+        return False
+    for name in names:
+        norm = name.lstrip("./")
+        if norm in _IMAGE_TAR_MARKERS:
+            return True
+        # A top-level ``blobs/`` directory entry (OCI layout layout).
+        if norm == "blobs" or norm.startswith("blobs/"):
+            return True
+    return False
+
+
+def _has_template_signal(path: Path) -> bool:
+    """Return True if *path* reads like a Containerfile/template."""
+    try:
+        with path.open(encoding="utf-8", errors="replace") as fh:
+            scanned = 0
+            for raw in fh:
+                if scanned >= _TEMPLATE_SCAN_LINES:
+                    break
+                scanned += 1
+                line = raw.rstrip("\n")
+                if _TEMPLATE_HEADER_RE.match(line):
+                    return True
+                stripped = line.strip()
+                if not stripped or stripped.startswith("#"):
+                    continue
+                # First non-empty, non-comment line decides the FROM question.
+                return bool(_FROM_DIRECTIVE_RE.match(line))
+    except OSError:
+        return False
+    return False
+
+
+def detect_source_kind(source: str, *, force: str | None = None) -> str:
+    """Classify *source* as ``"image"`` or ``"template"``.
+
+    Resolution order:
+
+    1. *force* in ``{"image", "template"}`` -> returned directly.
+    2. **Local file** (``Path(source).is_file()``) -> sniffed: an image-tar
+       (manifest.json / oci-layout / blobs/) is ``"image"``; a file with a
+       leading ``FROM`` directive or a ``# kanibako-template[-check]:`` header
+       is ``"template"``. Neither signal -> :class:`ValueError`.
+    3. **Registry reference** (a non-existent path matching the loose ref
+       grammar, e.g. ``ghcr.io/corp/base:1.0`` or ``busybox``) -> ``"image"``.
+
+    A raw ``http(s)://`` URL is **undecidable** here -- fetch it first with
+    :func:`fetch_to_temp`, then classify the downloaded file. Anything that
+    matches none of the above raises :class:`ValueError` with guidance.
+    """
+    if force is not None:
+        if force in ("image", "template"):
+            return force
+        raise ValueError(
+            f"invalid force value '{force}'; expected 'image' or 'template'"
+        )
+
+    path = Path(source)
+    if path.is_file():
+        if _is_image_tar(source):
+            return "image"
+        if _has_template_signal(path):
+            return "template"
+        raise ValueError(
+            f"cannot classify source '{source}'; pass --as image|template"
+        )
+
+    lowered = source.lower()
+    if lowered.startswith(("http://", "https://")):
+        raise ValueError(
+            f"cannot classify URL '{source}' directly; fetch it first "
+            "(fetch_to_temp) then classify the downloaded file."
+        )
+
+    if _REF_RE.match(lowered):
+        return "image"
+
+    raise ValueError(
+        f"cannot classify source '{source}'; expected a local file, an image "
+        "reference, or a fetched URL (pass --as image|template to force)."
+    )
+
+
+def _name_from_containerfile_basename(basename: str) -> str | None:
+    """Derive a rig name from a ``Containerfile.<rest>`` basename, else None."""
+    for prefix in ("Containerfile.", "Dockerfile."):
+        if basename.startswith(prefix):
+            rest = basename[len(prefix):]
+            if not rest:
+                return None
+            if rest.startswith("template-"):
+                rest = rest[len("template-"):]
+            return rest or None
+    return None
+
+
+def _name_from_ref(ref: str) -> str | None:
+    """Return *ref* minus a leading registry-host segment, if any."""
+    if not ref:
+        return None
+    segments = ref.split("/")
+    if len(segments) > 1:
+        first = segments[0]
+        # A leading segment is a registry host if it carries a ``.`` or a port.
+        if "." in first or ":" in first:
+            return "/".join(segments[1:]) or None
+    return ref
+
+
+def _name_from_image_tar(path: str) -> str | None:
+    """Derive a rig name from an image tar's first RepoTag, else its stem."""
+    try:
+        with tarfile.open(path) as tar:
+            try:
+                member = tar.getmember("manifest.json")
+            except KeyError:
+                member = None
+            if member is not None:
+                fh = tar.extractfile(member)
+                if fh is not None:
+                    import json
+
+                    try:
+                        manifest = json.loads(fh.read().decode("utf-8"))
+                    except (ValueError, UnicodeDecodeError):
+                        manifest = None
+                    if isinstance(manifest, list) and manifest:
+                        tags = manifest[0].get("RepoTags")
+                        if isinstance(tags, list) and tags:
+                            first = tags[0]
+                            if isinstance(first, str) and first:
+                                return first
+    except (tarfile.TarError, OSError):
+        pass
+    return Path(path).stem or None
+
+
+def derive_name(source: str, kind: str) -> str | None:
+    """Best-effort default rig name for *source* (of the given *kind*), or None.
+
+    - A Containerfile/Dockerfile path or URL whose basename is
+      ``Containerfile.<rest>`` -> ``<rest>`` with an optional leading
+      ``template-`` stripped (a bare ``Containerfile``/``Dockerfile`` -> None).
+    - An image **reference** -> the ref minus a leading registry-host segment
+      (``ghcr.io/corp/base:1.0`` -> ``corp/base:1.0``; ``busybox`` -> ``busybox``).
+    - An image **tar** (an existing file) -> its first RepoTag, else the stem.
+    - Anything underivable -> None.
+
+    Note: derived image names may legitimately contain ``/`` and ``:`` and are
+    *not* run through :func:`kanibako.templates_image.validate_template_name`.
+    """
+    # A basename-based Containerfile name wins regardless of kind: ``rig add``
+    # of a template URL/path should name itself after the file.
+    basename = source.rsplit("/", 1)[-1]
+    cf_name = _name_from_containerfile_basename(basename)
+    if cf_name is not None:
+        return cf_name
+
+    if kind == "template":
+        return None
+
+    # kind == "image"
+    path = Path(source)
+    if path.is_file():
+        return _name_from_image_tar(source)
+
+    lowered = source.lower()
+    if lowered.startswith(("http://", "https://")):
+        # A URL with no Containerfile-style basename is underivable here.
+        return None
+
+    return _name_from_ref(source)

kanibako/scripts/helper-init.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# helper-init.sh — Default helper entrypoint wrapper (kanibako)
+#
+# This script is copied into every helper's playbook/scripts/ directory
+# by the parent agent.  It runs as the container entrypoint.
+#
+# The parent creates the directory structure (vault, workspace, playbook,
+# peers, broadcast channels) before launching the helper.  This script
+# handles registration with the hub and additional bootstrap, then execs
+# the agent command.
+#
+# Parents can replace this with a custom version in their own
+# playbook/scripts/helper-init.sh — kanibako will use the parent's
+# version if it exists, falling back to this bundled default.
+#
+# Usage: helper-init.sh HELPER_NUM [COMMAND...]
+#   HELPER_NUM — this helper's global agent number
+#   COMMAND    — the agent command to exec (default: claude)
+
+set -euo pipefail
+
+HELPER_NUM="${1:-unknown}"
+shift || true
+
+SOCKET_PATH="$HOME/.kanibako/helper.sock"
+
+# Register with the hub via kanibako CLI (one-shot)
+if [ -S "$SOCKET_PATH" ] && command -v kanibako >/dev/null 2>&1; then
+    kanibako helper register "$HELPER_NUM" 2>/dev/null || true
+fi
+
+# Source parent startup script from broadcast channel if present
+if [ -f "$HOME/all/ro/startup.sh" ]; then
+    # shellcheck disable=SC1091
+    source "$HOME/all/ro/startup.sh"
+fi
+
+echo "Helper $HELPER_NUM initialized." >&2
+
+# Exec the agent command (or claude if none given)
+if [ $# -gt 0 ]; then
+    exec "$@"
+else
+    exec claude
+fi

kanibako/scripts/kanibako-entry

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""Container-side entry point for kanibako CLI.
+
+Bind-mounted into containers at /home/agent/.local/bin/kanibako.
+The kanibako package directory is bind-mounted at /opt/kanibako/kanibako/.
+"""
+import sys
+
+sys.path.insert(0, "/opt/kanibako")
+from kanibako.cli import main  # noqa: E402
+
+sys.exit(main() or 0)

kanibako/settings_resolve.py

@@ -0,0 +1,312 @@
+"""Settings-framework expression resolution engine (pure, additive).
+
+This module is the single home for the settings-framework expression grammar:
+precedence resolution, ``$VAR``/``~``/``@``-ref expansion, and ``host_src:
+guest_dest`` bind splitting.  It operates ONLY on already-parsed nested data
+(passed in as :class:`LevelView` objects and a lookup callback).  It performs
+**no file I/O, no mounting, no global mutable state**, and imports neither
+``config.py`` nor ``paths.py``.  It is intentionally format-agnostic — the
+caller is responsible for parsing TOML/YAML into the simple mappings this
+module consumes.
+
+Precedence model (the design's "unset ≠ '' " distinction)
+---------------------------------------------------------
+:func:`resolve_value` walks the levels ordered MOST-SPECIFIC-FIRST
+(``[box, workset, crab, system]``):
+
+* **Explicit set values beat all declared defaults**, regardless of level.
+* Among set values, the **most-specific** level wins.
+* An explicit ``""`` is a **terminal suppression**: it wins at its level and
+  does NOT fall through to a less-specific default (``terminal=True``).
+* Among defaults (reached only when nothing is set), the most-specific
+  (highest-authority) declared default wins.
+* Nothing set and no default ⇒ :data:`UNSET`.
+
+Expansion is a separate, explicit step (:func:`expand_expr`): the caller takes
+the winning raw literal from :func:`resolve_value` and expands it in the
+appropriate *space* (``"host"`` or ``"guest"``).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Literal
+
+from kanibako.errors import KanibakoError
+
+GUEST_HOME = "/home/agent"
+MAX_REF_DEPTH = 64
+
+_VAR_NAME_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+_REF_NAME_RE = re.compile(r"[A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)*")
+
+
+class SettingsError(KanibakoError):
+    """Raised on unknown variable, unresolvable/cyclic ``@``-ref, or depth-cap."""
+
+
+class _Unset:
+    """Sentinel type for "no value resolved" (distinct from an explicit ``""``)."""
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+
+UNSET = _Unset()
+
+
+@dataclass(frozen=True)
+class ResolveCtx:
+    """Context for variable expansion.
+
+    *xdg* maps XDG variable names (e.g. ``"XDG_DATA_HOME"``) to host paths.
+    The dataclass is frozen; do not mutate *xdg* in place.
+    """
+
+    crab_name: str | None
+    workset_name: str | None
+    host_home: str
+    xdg: dict[str, str]
+
+
+@dataclass(frozen=True)
+class LevelView:
+    """A single precedence level's explicitly-set values and declared defaults.
+
+    *name* is the level name (e.g. ``"box"``).  *values* holds values the user
+    explicitly set at this level; *defaults* holds defaults declared at this
+    level.
+    """
+
+    name: str
+    values: Mapping[str, str]
+    defaults: Mapping[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ResolvedValue:
+    """A resolved (but not yet expanded) value plus its provenance.
+
+    *value* is the raw winning literal (``@``-refs/``$vars``/``~`` intact).
+    *level* names the level that supplied it.  *is_default* is True when the
+    value came from a declared default rather than an explicit set.  *terminal*
+    is True when the winning value was an explicit ``""`` (a terminal
+    suppression that does not fall through to defaults).
+    """
+
+    value: str
+    level: str
+    is_default: bool = False
+    terminal: bool = False
+
+
+def _unescape(s: str) -> str:
+    """Resolve backslash escapes consistently.
+
+    A backslash before any character yields that character literally
+    (``\\:`` → ``:``, ``\\\\`` → ``\\``, ``\\x`` → ``x``).  A trailing lone
+    backslash is kept literal.
+    """
+    out: list[str] = []
+    i = 0
+    n = len(s)
+    while i < n:
+        c = s[i]
+        if c == "\\":
+            if i + 1 < n:
+                out.append(s[i + 1])
+                i += 2
+                continue
+            # Trailing lone backslash: keep literal.
+            out.append("\\")
+            i += 1
+            continue
+        out.append(c)
+        i += 1
+    return "".join(out)
+
+
+def split_bind(value: str) -> tuple[str, str | None]:
+    """Split ``host_src:guest_dest`` into its two halves.
+
+    Scans left-to-right; a backslash escapes the next character (so ``\\:`` is
+    a literal colon, ``\\\\`` a literal backslash).  Splits at the FIRST
+    UNESCAPED ``:``.  With no unescaped colon, returns ``(unescaped(value),
+    None)`` for a plain scalar.  Each returned half has its escapes resolved.
+
+    Linux container paths only — no Windows drive-letter / URI special-casing.
+    Use ``\\:`` to embed a literal colon in either half.
+    """
+    i = 0
+    n = len(value)
+    while i < n:
+        c = value[i]
+        if c == "\\":
+            # Skip the escaped character.
+            i += 2
+            continue
+        if c == ":":
+            host = _unescape(value[:i])
+            guest = _unescape(value[i + 1 :])
+            return host, guest
+        i += 1
+    return _unescape(value), None
+
+
+def expand_expr(
+    expr: str,
+    *,
+    space: Literal["host", "guest"],
+    ctx: ResolveCtx,
+    lookup: Callable[[str, tuple[str, ...]], str],
+    chain: tuple[str, ...] = (),
+) -> str:
+    """Expand a single path/scalar expression (one bind half).
+
+    Single left-to-right scan emitting literal vs expanded segments.  A
+    substituted value is a LEAF — it is not re-scanned (prevents
+    double-expansion / loops).
+
+    Grammar:
+
+    * **Escapes:** ``\\@``→``@``, ``\\$``→``$``, ``\\\\``→``\\``; a backslash
+      before any other char yields that char literally.
+    * **``~``:** ONLY when it is the FIRST character of *expr*.  Expands to
+      ``ctx.host_home`` (``space=="host"``) or :data:`GUEST_HOME`
+      (``space=="guest"``).  A ``~`` elsewhere is literal.
+    * **``$VAR`` / ``${VAR}``:** name = ``[A-Za-z_][A-Za-z0-9_]*``.  ``CRAB`` →
+      ``ctx.crab_name``, ``WORKSET`` → ``ctx.workset_name``, ``XDG_*`` →
+      ``ctx.xdg[name]``.  Unknown names, or known names whose context value is
+      ``None``/missing, raise :class:`SettingsError`.
+    * **``@``-ref:** ``@`` then a dotted name ``[A-Za-z0-9_]+(\\.[...])*``.  The
+      ref name ends at the first char outside that set.  Cycle-guarded against
+      *chain* and capped at :data:`MAX_REF_DEPTH`.  Substitutes
+      ``lookup(ref_name, chain + (ref_name,))``; the result is a leaf.
+    """
+    out: list[str] = []
+    i = 0
+    n = len(expr)
+
+    # Leading ~ → home (only at position 0).
+    if n > 0 and expr[0] == "~":
+        out.append(ctx.host_home if space == "host" else GUEST_HOME)
+        i = 1
+
+    while i < n:
+        c = expr[i]
+        if c == "\\":
+            if i + 1 < n:
+                out.append(expr[i + 1])
+                i += 2
+                continue
+            out.append("\\")
+            i += 1
+            continue
+        if c == "$":
+            seg, i = _expand_var(expr, i, ctx)
+            out.append(seg)
+            continue
+        if c == "@":
+            seg, i = _expand_ref(expr, i, lookup, chain)
+            out.append(seg)
+            continue
+        out.append(c)
+        i += 1
+
+    return "".join(out)
+
+
+def _expand_var(expr: str, i: int, ctx: ResolveCtx) -> tuple[str, int]:
+    """Expand a ``$VAR`` or ``${VAR}`` starting at index *i* (the ``$``)."""
+    n = len(expr)
+    braced = i + 1 < n and expr[i + 1] == "{"
+    name_start = i + 2 if braced else i + 1
+    m = _VAR_NAME_RE.match(expr, name_start)
+    if m is None:
+        raise SettingsError(f"Malformed variable reference at: {expr[i:]!r}")
+    name = m.group(0)
+    end = m.end()
+    if braced:
+        if end >= n or expr[end] != "}":
+            raise SettingsError(f"Unterminated ${{...}} reference: {expr[i:]!r}")
+        end += 1
+    return _resolve_var(name, ctx), end
+
+
+def _resolve_var(name: str, ctx: ResolveCtx) -> str:
+    """Resolve a variable name against the context namespace."""
+    if name == "CRAB":
+        if ctx.crab_name is None:
+            raise SettingsError("Variable $CRAB is not set in this context.")
+        return ctx.crab_name
+    if name == "WORKSET":
+        if ctx.workset_name is None:
+            raise SettingsError("Variable $WORKSET is not set in this context.")
+        return ctx.workset_name
+    if name.startswith("XDG_"):
+        if name not in ctx.xdg:
+            raise SettingsError(f"Variable ${name} is not set in this context.")
+        return ctx.xdg[name]
+    raise SettingsError(f"Unknown variable: ${name}")
+
+
+def _expand_ref(
+    expr: str,
+    i: int,
+    lookup: Callable[[str, tuple[str, ...]], str],
+    chain: tuple[str, ...],
+) -> tuple[str, int]:
+    """Expand an ``@ref`` starting at index *i* (the ``@``)."""
+    m = _REF_NAME_RE.match(expr, i + 1)
+    if m is None:
+        raise SettingsError(f"Malformed @-reference at: {expr[i:]!r}")
+    ref_name = m.group(0)
+    end = m.end()
+    if ref_name in chain:
+        cycle = " -> ".join((*chain, ref_name))
+        raise SettingsError(f"Cyclic @-reference: {cycle}")
+    if len(chain) >= MAX_REF_DEPTH:
+        raise SettingsError(
+            f"@-reference depth cap ({MAX_REF_DEPTH}) exceeded resolving "
+            f"'{ref_name}'."
+        )
+    return lookup(ref_name, (*chain, ref_name)), end
+
+
+def resolve_value(
+    key: str,
+    *,
+    levels: list[LevelView],
+    ctx: ResolveCtx,
+    lookup: Callable[[str, tuple[str, ...]], str],
+) -> ResolvedValue | _Unset:
+    """Resolve *key* by precedence over *levels* (most-specific first).
+
+    Returns the raw winning literal (unexpanded) with provenance, or
+    :data:`UNSET`.  Does NOT expand — the caller expands the result via
+    :func:`expand_expr` with the appropriate *space*.  *ctx*/*lookup* are
+    accepted for signature stability; the pure precedence logic does not use
+    them.
+    """
+    del ctx, lookup  # accepted for signature stability; unused here.
+
+    # Pass 1: explicit set values, most-specific first.
+    for level in levels:
+        if key in level.values:
+            val = level.values[key]
+            if val == "":
+                return ResolvedValue(value="", level=level.name, terminal=True)
+            return ResolvedValue(value=val, level=level.name)
+
+    # Pass 2: declared defaults, most-specific first.
+    for level in levels:
+        if key in level.defaults:
+            return ResolvedValue(
+                value=level.defaults[key], level=level.name, is_default=True
+            )
+
+    return UNSET