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

kanibako/image_sharing.py

@@ -0,0 +1,133 @@
+"""Nested container image sharing: mount host image storage read-only into child containers.
+
+When kanibako runs inside a container (LXC/VM), nested podman pulls images
+separately, duplicating hundreds of MB.  This module provides opt-in sharing
+of the host's image storage via podman's ``additionalImageStores`` mechanism.
+
+The host's overlay storage is bind-mounted **read-only** into the child
+container at a well-known path, and a ``storage.conf`` snippet is generated
+so the child's podman can find the shared layers.
+
+**Known limitations**:
+
+- UID mapping: if host and child rootless podman use different subuid ranges,
+  layer files may be inaccessible.  Works best when the child container runs
+  with ``--userns=keep-id`` (which kanibako already uses).
+- The shared store is read-only; the child can pull new images on top but
+  cannot modify or delete shared layers.
+- Only overlay storage driver is supported (the default for rootless podman).
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from kanibako.log import get_logger
+from kanibako.targets.base import Mount
+
+logger = get_logger("image_sharing")
+
+# Well-known mount point inside child containers.
+SHARED_STORE_CONTAINER_PATH = "/var/lib/shared-images"
+
+# Container-side storage.conf path (rootless podman).
+_STORAGE_CONF_CONTAINER_PATH = "/home/agent/.config/containers/storage.conf"
+
+
+def detect_graph_root(runtime_cmd: str) -> Path | None:
+    """Detect the host podman/docker graph root (image storage directory).
+
+    Returns the ``GraphRoot`` path from ``podman info`` / ``docker info``,
+    or *None* if detection fails.
+    """
+    try:
+        result = subprocess.run(
+            [runtime_cmd, "info", "--format", "{{.Store.GraphRoot}}"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if result.returncode != 0:
+            logger.debug(
+                "Failed to detect graph root: %s", result.stderr.strip(),
+            )
+            return None
+        graph_root = result.stdout.strip()
+        if not graph_root:
+            return None
+        path = Path(graph_root)
+        if not path.is_dir():
+            logger.debug("Graph root does not exist: %s", path)
+            return None
+        return path
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as exc:
+        logger.debug("Graph root detection failed: %s", exc)
+        return None
+
+
+def generate_storage_conf(shared_store_path: str) -> str:
+    """Generate a ``storage.conf`` snippet for podman's additionalImageStores.
+
+    The generated config tells the child's podman to use the overlay driver
+    and look for additional (read-only) image layers at *shared_store_path*.
+
+    Parameters
+    ----------
+    shared_store_path:
+        The container-side path where the host's graph root is mounted
+        (typically ``/var/lib/shared-images``).
+    """
+    return (
+        "[storage]\n"
+        '  driver = "overlay"\n'
+        "  [storage.options]\n"
+        f'    additionalimagestores = ["{shared_store_path}"]\n'
+    )
+
+
+def build_image_sharing_mounts(
+    runtime_cmd: str,
+    staging_dir: Path,
+) -> list[Mount]:
+    """Build the bind-mounts needed for image sharing.
+
+    Returns a list of mounts (may be empty if detection fails or the
+    storage path doesn't exist).  On success returns two mounts:
+
+    1. Host graph root -> ``/var/lib/shared-images`` (read-only)
+    2. Generated ``storage.conf`` -> child's config dir (read-only)
+
+    Parameters
+    ----------
+    runtime_cmd:
+        Path to the container runtime binary (``podman`` or ``docker``).
+    staging_dir:
+        A host-side directory where the generated ``storage.conf`` will be
+        written.  Should be under the project's metadata or cache path.
+    """
+    graph_root = detect_graph_root(runtime_cmd)
+    if graph_root is None:
+        logger.info("Image sharing: could not detect host graph root, skipping")
+        return []
+
+    logger.info("Image sharing: host graph root at %s", graph_root)
+
+    # Generate the storage.conf snippet
+    storage_conf_content = generate_storage_conf(SHARED_STORE_CONTAINER_PATH)
+    staging_dir.mkdir(parents=True, exist_ok=True)
+    storage_conf_path = staging_dir / "storage.conf"
+    storage_conf_path.write_text(storage_conf_content)
+
+    return [
+        Mount(
+            source=graph_root,
+            destination=SHARED_STORE_CONTAINER_PATH,
+            options="ro",
+        ),
+        Mount(
+            source=storage_conf_path,
+            destination=_STORAGE_CONF_CONTAINER_PATH,
+            options="ro",
+        ),
+    ]

kanibako/instructions.py

@@ -0,0 +1,160 @@
+"""Layered instruction file merging.
+
+Merges instruction files (e.g. CLAUDE.md) from three layers:
+  1. **Kanibako base** — container environment documentation
+  2. **Template** — shell template instructions
+  3. **User project** — user's own instructions (highest priority, shown last)
+
+Each layer is concatenated with section markers so the agent can see
+where each part comes from.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kanibako.log import get_logger
+
+logger = get_logger("instructions")
+
+# Section markers used to delimit layers in merged instruction files.
+_MARKER_BASE = "# --- kanibako base ---"
+_MARKER_TEMPLATE = "# --- template: {name} ---"
+_MARKER_PROJECT = "# --- project ---"
+
+# Sentinel that marks the end of managed sections.  Content after this
+# marker is preserved verbatim (not touched by future merges).
+_MARKER_END = "# --- end managed ---"
+
+
+def _read_layer(path: Path) -> str | None:
+    """Read a file and return its stripped content, or None if missing/empty."""
+    if not path.is_file():
+        return None
+    content = path.read_text().strip()
+    return content if content else None
+
+
+def merge_instruction_content(
+    *,
+    base_content: str | None = None,
+    template_content: str | None = None,
+    template_name: str = "",
+    user_content: str | None = None,
+) -> str | None:
+    """Merge instruction file layers into a single string.
+
+    Returns the merged content with section markers, or None if all
+    layers are empty/missing.
+
+    Layer order (top to bottom):
+      1. kanibako base
+      2. template
+      3. user project (last = highest visibility)
+    """
+    sections: list[str] = []
+
+    if base_content:
+        sections.append(f"{_MARKER_BASE}\n\n{base_content}")
+
+    if template_content:
+        marker = _MARKER_TEMPLATE.format(name=template_name or "default")
+        sections.append(f"{marker}\n\n{template_content}")
+
+    if user_content:
+        sections.append(f"{_MARKER_PROJECT}\n\n{user_content}")
+
+    if not sections:
+        return None
+
+    return "\n\n".join(sections) + "\n"
+
+
+def merge_instruction_files(
+    *,
+    shell_path: Path,
+    config_dir_name: str,
+    instruction_files: list[str],
+    templates_base: Path | None = None,
+    agent_name: str = "",
+    template_name: str = "standard",
+) -> None:
+    """Merge instruction files from base/template/user layers.
+
+    For each filename in *instruction_files*:
+      1. Read base content from ``templates_base/general/base/{config_dir_name}/{filename}``
+      2. Read template content from the resolved template dir ``{config_dir_name}/{filename}``
+      3. Read user content already in ``shell_path/{config_dir_name}/{filename}``
+         (placed there by template application or pre-existing)
+
+    The merged result replaces the file at ``shell_path/{config_dir_name}/{filename}``.
+
+    If the file only has content from a single layer, it is written without
+    section markers (clean output for the common case).
+    """
+    if not instruction_files:
+        return
+
+    config_dir = shell_path / config_dir_name
+
+    for filename in instruction_files:
+        dest = config_dir / filename
+
+        # Layer 1: kanibako base — from general/base/{config_dir}/{filename}
+        base_content: str | None = None
+        if templates_base:
+            base_path = templates_base / "general" / "base" / config_dir_name / filename
+            base_content = _read_layer(base_path)
+
+        # Layer 2: template — from resolved template dir
+        # The template was already applied by apply_shell_template() which
+        # copied all files including instruction files.  We need to read
+        # the template's *original* version before it was overlaid.
+        template_content: str | None = None
+        if templates_base:
+            from kanibako.templates import resolve_template
+
+            resolved = resolve_template(templates_base, agent_name, template_name)
+            if resolved:
+                tmpl_path = resolved / config_dir_name / filename
+                template_content = _read_layer(tmpl_path)
+
+        # Layer 3: user project — whatever is at the destination *now*.
+        # After apply_shell_template(), this is the template's version of
+        # the file (which we already captured above).  We need to detect
+        # whether the current content is identical to the template layer
+        # to avoid duplicating it.
+        user_content: str | None = None
+        current_content = _read_layer(dest)
+        if current_content:
+            # If the current file matches the template content exactly,
+            # it's not user content — the template just put it there.
+            # Same for base content.
+            if current_content != template_content and current_content != base_content:
+                user_content = current_content
+            elif template_content is None and base_content is None:
+                # File exists but no template/base layers — treat as user content.
+                user_content = current_content
+
+        # Count non-None layers to decide whether to use markers.
+        layers = [x for x in (base_content, template_content, user_content) if x]
+
+        if not layers:
+            # No content from any layer — skip (don't create empty file).
+            continue
+
+        if len(layers) == 1:
+            # Single layer — write without markers for clean output.
+            merged: str | None = layers[0] + "\n"
+        else:
+            merged = merge_instruction_content(
+                base_content=base_content,
+                template_content=template_content,
+                template_name=template_name,
+                user_content=user_content,
+            )
+
+        if merged:
+            config_dir.mkdir(parents=True, exist_ok=True)
+            dest.write_text(merged)
+            logger.debug("Merged instruction file: %s (%d layers)", dest, len(layers))

kanibako/log.py

@@ -0,0 +1,31 @@
+"""Logging setup for kanibako."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+
+def setup_logging(verbose: bool = False) -> None:
+    """Configure the ``kanibako`` root logger.
+
+    Normal mode: WARNING+ to stderr.
+    Verbose mode: DEBUG+ to stderr with ``kanibako: <message>`` format.
+    """
+    logger = logging.getLogger("kanibako")
+    logger.handlers.clear()
+
+    handler = logging.StreamHandler(sys.stderr)
+    if verbose:
+        logger.setLevel(logging.DEBUG)
+        handler.setFormatter(logging.Formatter("kanibako: %(message)s"))
+    else:
+        logger.setLevel(logging.WARNING)
+
+    handler.setLevel(logging.DEBUG)
+    logger.addHandler(handler)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Return a child logger under ``kanibako``."""
+    return logging.getLogger(f"kanibako.{name}")

kanibako/names.py

@@ -0,0 +1,248 @@
+"""Project name registry (names.yaml).
+
+Central index at ``{data_path}/names.yaml`` mapping human-readable names to
+project paths (for default-mode projects) and workset roots (for worksets).
+Standalone projects are intentionally excluded — they have no central
+registration.
+
+The file has two sections::
+
+    projects:
+      myapp: /home/user/projects/myapp
+
+    worksets:
+      clientwork: /home/user/worksets/client
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kanibako.config_io import dump_doc, load_doc
+from kanibako.errors import ProjectError
+
+
+# ---------------------------------------------------------------------------
+# I/O helpers
+# ---------------------------------------------------------------------------
+
+def _names_path(data_path: Path) -> Path:
+    return data_path / "names.yaml"
+
+
+def _load(data_path: Path) -> dict[str, dict[str, str]]:
+    """Load names.yaml and return raw sections."""
+    path = _names_path(data_path)
+    if not path.is_file():
+        return {"projects": {}, "worksets": {}}
+    data = load_doc(path)
+    return {
+        "projects": {k: str(v) for k, v in data.get("projects", {}).items()},
+        "worksets": {k: str(v) for k, v in data.get("worksets", {}).items()},
+    }
+
+
+def _save(data_path: Path, names: dict[str, dict[str, str]]) -> None:
+    """Write names.yaml from sections dict."""
+    path = _names_path(data_path)
+    data: dict = {}
+    for section in ("projects", "worksets"):
+        entries = names.get(section, {})
+        data[section] = {name: entries[name] for name in sorted(entries)}
+    dump_doc(path, data)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def read_names(data_path: Path) -> dict[str, dict[str, str]]:
+    """Load names.yaml.
+
+    Returns ``{"projects": {name: path, ...}, "worksets": {name: path, ...}}``.
+    """
+    return _load(data_path)
+
+
+def register_name(
+    data_path: Path,
+    name: str,
+    path: str,
+    section: str = "projects",
+) -> None:
+    """Register a name → path mapping.
+
+    Raises ``ProjectError`` if *name* is already registered in either section,
+    or if *path* resolves to ``$HOME``.
+    """
+    # Guard: never register $HOME as a project path.
+    if Path(path).resolve() == Path.home().resolve():
+        raise ProjectError(
+            "Refusing to register $HOME as a project path — this would "
+            "mount your entire home directory as the workspace."
+        )
+    names = _load(data_path)
+    # Check for duplicates across both sections.
+    for sec in ("projects", "worksets"):
+        if name in names[sec]:
+            raise ProjectError(
+                f"Name '{name}' is already registered"
+                f" ({sec}: {names[sec][name]})"
+            )
+    names[section][name] = path
+    _save(data_path, names)
+
+
+def update_name_path(
+    data_path: Path,
+    name: str,
+    new_path: str,
+    section: str = "projects",
+) -> bool:
+    """Update the path for an existing registered name.
+
+    Returns True if the name was found and updated, False otherwise.
+    Raises ``ProjectError`` if *new_path* resolves to ``$HOME``.
+    """
+    if Path(new_path).resolve() == Path.home().resolve():
+        raise ProjectError(
+            "Refusing to register $HOME as a project path — this would "
+            "mount your entire home directory as the workspace."
+        )
+    names = _load(data_path)
+    if name not in names.get(section, {}):
+        return False
+    names[section][name] = new_path
+    _save(data_path, names)
+    return True
+
+
+def unregister_name(
+    data_path: Path,
+    name: str,
+    section: str = "projects",
+) -> bool:
+    """Remove a name from the registry.
+
+    Returns True if the name was found and removed, False otherwise.
+    """
+    names = _load(data_path)
+    if name not in names.get(section, {}):
+        return False
+    del names[section][name]
+    _save(data_path, names)
+    return True
+
+
+def lookup_by_path(
+    data_path: Path,
+    path: str,
+) -> tuple[str, str] | None:
+    """Find a registered name by its path value.
+
+    Returns ``(name, section)`` if found, ``None`` otherwise.
+    """
+    resolved = str(Path(path).resolve())
+    names = _load(data_path)
+    for section in ("projects", "worksets"):
+        for name, registered_path in names[section].items():
+            if str(Path(registered_path).resolve()) == resolved:
+                return name, section
+    return None
+
+
+def resolve_name(
+    data_path: Path,
+    name: str,
+    cwd: Path | None = None,
+) -> tuple[str, str]:
+    """Look up a bare name and return ``(path, kind)``.
+
+    Resolution order:
+
+    1. If *cwd* is inside a workset → check that workset's projects first
+    2. ``[projects]`` section (default-mode projects)
+    3. ``[worksets]`` section (workset names)
+
+    *kind* is ``"project"`` or ``"workset"``.
+    Raises ``ProjectError`` if no match is found.
+    """
+    names = _load(data_path)
+
+    # 1. Context-aware: if cwd is inside a registered workset, check its
+    #    projects first.
+    if cwd is not None:
+        cwd_str = str(cwd.resolve())
+        for ws_name, ws_root in names["worksets"].items():
+            if cwd_str == ws_root or cwd_str.startswith(ws_root + "/"):
+                # cwd is inside this workset — check if name matches a
+                # workspace subdir.
+                ws_path = Path(ws_root)
+                candidate = ws_path / "workspaces" / name
+                if candidate.is_dir():
+                    return str(candidate), "project"
+
+    # 2. Default-mode projects.
+    if name in names["projects"]:
+        return names["projects"][name], "project"
+
+    # 3. Worksets.
+    if name in names["worksets"]:
+        return names["worksets"][name], "workset"
+
+    raise ProjectError(f"Unknown project or workset: '{name}'")
+
+
+def resolve_qualified_name(
+    data_path: Path,
+    qualified: str,
+) -> tuple[str, str]:
+    """Resolve a qualified name (``workset/project``).
+
+    Returns ``(project_workspace_path, workset_name)``.
+    Raises ``ProjectError`` if the workset or project is not found.
+    """
+    if "/" not in qualified:
+        raise ProjectError(
+            f"Not a qualified name (expected workset/project): '{qualified}'"
+        )
+    ws_name, proj_name = qualified.split("/", 1)
+    names = _load(data_path)
+
+    if ws_name not in names["worksets"]:
+        raise ProjectError(f"Unknown workset: '{ws_name}'")
+
+    ws_root = Path(names["worksets"][ws_name])
+    candidate = ws_root / "workspaces" / proj_name
+    if not candidate.is_dir():
+        raise ProjectError(
+            f"Project '{proj_name}' not found in workset '{ws_name}'"
+        )
+    return str(candidate), ws_name
+
+
+def assign_name(
+    data_path: Path,
+    path: str,
+    section: str = "projects",
+) -> str:
+    """Auto-assign a name from the basename of *path*.
+
+    Handles collisions by appending a number: ``name``, ``name2``, ``name3``, ...
+    Registers the name and returns it.
+    """
+    base = Path(path).name
+    if not base:
+        base = "project"
+
+    names = _load(data_path)
+    all_names = set(names["projects"]) | set(names["worksets"])
+
+    candidate = base
+    n = 2
+    while candidate in all_names:
+        candidate = f"{base}{n}"
+        n += 1
+
+    register_name(data_path, candidate, path, section=section)
+    return candidate