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

kanibako/templates_image.py

@@ -0,0 +1,224 @@
+"""Template image management: create, list, delete user templates."""
+
+from __future__ import annotations
+
+import importlib.resources
+import re
+from pathlib import Path
+from typing import NamedTuple, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from kanibako.container import ContainerRuntime
+
+_TEMPLATE_PREFIX = "kanibako-template-"
+_RIG_PREFIX = "kanibako-rig-"
+_VALID_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
+
+# Bundled template Containerfiles follow this naming convention. Only files
+# named exactly ``Containerfile.template-<name>`` (with a valid <name>) are
+# treated as shipped templates -- this excludes ``Containerfile.kanibako``
+# (the buildable base) and any non-matching files for free.
+_TEMPLATE_FILE_PREFIX = "Containerfile.template-"
+
+# Optional description header inside a template Containerfile, e.g.
+#   # kanibako-template: Java, Kotlin, Maven (JVM toolchain)
+_DESC_HEADER_RE = re.compile(r"^#\s*kanibako-template:\s*(.+?)\s*$")
+
+# Read at most this many lines looking for the description header.
+_DESC_HEADER_SCAN_LINES = 10
+
+# Optional smoke-check header(s) inside a template Containerfile, e.g.
+#   # kanibako-template-check: java -version
+# Zero or more per file; each captured command is one non-interactive smoke
+# test that must exit 0 in the built image.
+_CHECK_HEADER_RE = re.compile(r"^#\s*kanibako-template-check:\s*(.+?)\s*$")
+
+# Backstop: never scan past this many lines looking for check headers.
+_CHECK_HEADER_SCAN_LINES = 30
+
+
+def validate_template_name(name: str) -> None:
+    """Raise *ValueError* if *name* contains invalid characters.
+
+    Template names must start with a lowercase letter or digit and contain
+    only lowercase letters, digits, hyphens, and underscores.
+    """
+    if not _VALID_NAME_RE.match(name):
+        raise ValueError(
+            f"Invalid template name '{name}': must contain only lowercase "
+            "letters, digits, hyphens, and underscores, and must start with "
+            "a letter or digit."
+        )
+
+
+def template_image_name(name: str) -> str:
+    """Return the OCI image name for a template.
+
+    Raises *ValueError* if *name* is invalid.
+    """
+    validate_template_name(name)
+    return f"{_TEMPLATE_PREFIX}{name}"
+
+
+def rig_image_name(name: str) -> str:
+    """Return the OCI image name for an *extended* rig.
+
+    Extended rigs (interactively built, non-reproducible) live under the
+    ``kanibako-rig-`` prefix, distinct from the ``kanibako-template-`` prefix
+    used for buildable templates. Validates *name* the same way
+    :func:`template_image_name` does.
+
+    Raises *ValueError* if *name* is invalid.
+    """
+    validate_template_name(name)
+    return f"{_RIG_PREFIX}{name}"
+
+
+class BundledTemplate(NamedTuple):
+    """A template Containerfile available to kanibako.
+
+    *source* is ``"bundled"`` for templates shipped with kanibako and
+    ``"user"`` for templates dropped into the user-override directory.
+    """
+
+    name: str
+    description: str
+    source: str = "bundled"
+
+
+def _bundled_containers_dir() -> Path | None:
+    """Return the path to kanibako's shipped ``containers/`` directory.
+
+    Returns ``None`` if the package data cannot be resolved as a real
+    filesystem path (e.g. running from a zip import).
+    """
+    try:
+        traversable = importlib.resources.files("kanibako.containers")
+        path = Path(str(traversable))
+    except (TypeError, FileNotFoundError):
+        return None
+    return path if path.is_dir() else None
+
+
+def _read_template_description(containerfile: Path, name: str) -> str:
+    """Return the ``# kanibako-template:`` header text, or a fallback label."""
+    try:
+        with containerfile.open(encoding="utf-8") as fh:
+            for _, line in zip(range(_DESC_HEADER_SCAN_LINES), fh):
+                match = _DESC_HEADER_RE.match(line)
+                if match:
+                    return match.group(1)
+    except OSError:
+        pass
+    return f"{name} template"
+
+
+def read_template_checks(containerfile: Path) -> tuple[str, ...]:
+    """Return the ``# kanibako-template-check:`` commands from *containerfile*.
+
+    Each ``# kanibako-template-check: <command>`` header in the file's leading
+    comment block declares one non-interactive smoke command (expected to exit
+    0 in the built image). Commands are returned in file order so they can be
+    run top-to-bottom.
+
+    Only the leading comment block is scanned: scanning starts at line 1 and
+    stops at the first line that is neither blank nor a ``#`` comment (i.e. the
+    first directive such as ``ARG``/``FROM``). As a backstop the scan also
+    stops after :data:`_CHECK_HEADER_SCAN_LINES` lines. Returns an empty tuple
+    when no check headers are present or the file cannot be read.
+    """
+    checks: list[str] = []
+    try:
+        with containerfile.open(encoding="utf-8") as fh:
+            for _, line in zip(range(_CHECK_HEADER_SCAN_LINES), fh):
+                stripped = line.strip()
+                if stripped and not stripped.startswith("#"):
+                    break
+                match = _CHECK_HEADER_RE.match(line)
+                if match:
+                    checks.append(match.group(1))
+    except OSError:
+        return ()
+    return tuple(checks)
+
+
+def _scan_template_dir(
+    containers_dir: Path | None, source: str
+) -> list[BundledTemplate]:
+    """Scan *containers_dir* for ``Containerfile.template-<name>`` files.
+
+    Returns a list of :class:`BundledTemplate` tagged with *source*. Invalid
+    names and non-matching files are skipped. Order is the raw iteration order
+    (the caller is responsible for any sorting/merging).
+    """
+    if containers_dir is None or not containers_dir.is_dir():
+        return []
+
+    templates: list[BundledTemplate] = []
+    for entry in containers_dir.iterdir():
+        if not entry.is_file():
+            continue
+        if not entry.name.startswith(_TEMPLATE_FILE_PREFIX):
+            continue
+        name = entry.name[len(_TEMPLATE_FILE_PREFIX):]
+        if not _VALID_NAME_RE.match(name):
+            continue
+        description = _read_template_description(entry, name)
+        templates.append(
+            BundledTemplate(name=name, description=description, source=source)
+        )
+    return templates
+
+
+def list_bundled_templates(
+    containers_dir: Path | None = None,
+    *,
+    override_dir: Path | None = None,
+) -> list[BundledTemplate]:
+    """Discover template Containerfiles, merging bundled and user overrides.
+
+    Scans *containers_dir* (defaulting to kanibako's bundled ``containers/``
+    directory) non-recursively for files named exactly
+    ``Containerfile.template-<name>`` where ``<name>`` is a valid template
+    name (source ``"bundled"``). The ``archive/`` subdirectory and
+    non-matching files (such as ``Containerfile.kanibako``) are excluded.
+
+    If *override_dir* is a directory, it is scanned the same way for
+    user-dropped templates (source ``"user"``). A user template with the same
+    ``<name>`` as a bundled one *overrides* it -- mirroring
+    :func:`kanibako.containerfiles.get_containerfile`'s override-first
+    precedence -- so the result carries the user file's description and
+    ``source="user"``.
+
+    Each template's description is taken from a ``# kanibako-template: <desc>``
+    header comment near the top of the file, falling back to ``"<name>
+    template"`` when absent. Results are sorted by name.
+    """
+    if containers_dir is None:
+        containers_dir = _bundled_containers_dir()
+
+    merged: dict[str, BundledTemplate] = {}
+    for tmpl in _scan_template_dir(containers_dir, "bundled"):
+        merged[tmpl.name] = tmpl
+    for tmpl in _scan_template_dir(override_dir, "user"):
+        merged[tmpl.name] = tmpl
+
+    return sorted(merged.values(), key=lambda t: t.name)
+
+
+def list_templates(runtime: ContainerRuntime) -> list[tuple[str, str, str]]:
+    """Return (short_name, full_image, size) for all local template images."""
+    images = runtime.list_local_images()
+    result = []
+    for repo, size in images:
+        # Strip tag if present for matching
+        bare = repo.split(":")[0] if ":" in repo else repo
+        if bare.startswith(_TEMPLATE_PREFIX):
+            short = bare[len(_TEMPLATE_PREFIX):]
+            result.append((short, bare, size))
+    return result
+
+
+def delete_template(runtime: ContainerRuntime, name: str) -> None:
+    """Delete a template image by short name."""
+    runtime.remove_image(template_image_name(name))

kanibako/tweakcc.py

@@ -0,0 +1,140 @@
+"""tweakcc integration: config merging and patched binary caching.
+
+tweakcc customises Claude Code by patching its cli.js bundle.  Kanibako
+manages the patching lifecycle — config merging, binary caching on tmpfs,
+flock-based reference counting — so that patched variants are transparent
+to the user and shared across projects with identical configs.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from kanibako.log import get_logger
+
+logger = get_logger("tweakcc")
+
+
+@dataclass
+class TweakccConfig:
+    """Resolved tweakcc configuration for a launch.
+
+    Produced by merging agent-level defaults, an optional external config
+    file, and per-project inline overrides.
+    """
+
+    enabled: bool = False
+    config_path: str | None = None  # path to external tweakcc config.json
+    overrides: dict = field(default_factory=dict)  # inline [tweakcc] overrides
+
+
+def load_tweakcc_section(data: dict) -> dict:
+    """Extract the ``[tweakcc]`` section from parsed TOML data.
+
+    Returns a plain dict.  Missing section → empty dict.
+    """
+    return dict(data.get("tweakcc", {}))
+
+
+def resolve_tweakcc_config(
+    agent_tweakcc: dict,
+    project_tweakcc: dict | None = None,
+) -> TweakccConfig:
+    """Merge agent and project tweakcc sections into a resolved config.
+
+    Resolution order (highest wins):
+      1. Project ``[tweakcc]`` overrides
+      2. Agent ``[tweakcc]`` defaults
+
+    The ``enabled`` and ``config`` keys are extracted; everything else is
+    treated as inline overrides passed through to tweakcc.
+    """
+    merged = dict(agent_tweakcc)
+    if project_tweakcc:
+        merged.update(project_tweakcc)
+
+    enabled = bool(merged.pop("enabled", False))
+    config_path = merged.pop("config", None)
+    if config_path is not None:
+        config_path = str(config_path)
+
+    return TweakccConfig(
+        enabled=enabled,
+        config_path=config_path,
+        overrides=merged,
+    )
+
+
+def load_external_config(config_path: str | None) -> dict:
+    """Load an external tweakcc config.json file.
+
+    Returns empty dict if *config_path* is None or the file doesn't exist.
+    """
+    if not config_path:
+        return {}
+
+    path = Path(config_path).expanduser()
+    if not path.is_file():
+        logger.debug("External tweakcc config not found: %s", path)
+        return {}
+
+    try:
+        with open(path) as f:
+            data = json.load(f)
+        logger.debug("Loaded external tweakcc config: %s", path)
+        return data if isinstance(data, dict) else {}
+    except (json.JSONDecodeError, OSError) as e:
+        logger.warning("Failed to load tweakcc config %s: %s", path, e)
+        return {}
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    """Recursively merge *override* into *base*, returning a new dict."""
+    result = dict(base)
+    for key, val in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(val, dict):
+            result[key] = _deep_merge(result[key], val)
+        else:
+            result[key] = val
+    return result
+
+
+def build_merged_config(
+    tweakcc_cfg: TweakccConfig,
+    kanibako_defaults: dict | None = None,
+) -> dict:
+    """Build the final tweakcc config dict for ``tweakcc --apply``.
+
+    Merge order (highest wins):
+      1. Inline overrides from ``tweakcc_cfg.overrides``
+      2. External config file (``tweakcc_cfg.config_path``)
+      3. Kanibako's own defaults (``kanibako_defaults``)
+
+    Returns a dict ready to be serialized as config.json.
+    """
+    result: dict = {}
+
+    # Layer 1: kanibako defaults (lowest priority)
+    if kanibako_defaults:
+        result = _deep_merge(result, kanibako_defaults)
+
+    # Layer 2: external config file
+    external = load_external_config(tweakcc_cfg.config_path)
+    if external:
+        result = _deep_merge(result, external)
+
+    # Layer 3: inline overrides (highest priority)
+    if tweakcc_cfg.overrides:
+        result = _deep_merge(result, tweakcc_cfg.overrides)
+
+    return result
+
+
+def write_merged_config(config: dict, output_path: Path) -> None:
+    """Write the merged tweakcc config to a JSON file."""
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(output_path, "w") as f:
+        json.dump(config, f, indent=2)
+    logger.debug("Wrote merged tweakcc config: %s", output_path)

kanibako/tweakcc_cache.py

@@ -0,0 +1,171 @@
+"""tweakcc binary cache with flock-based reference counting.
+
+Patched Claude Code binaries are cached to avoid redundant tweakcc runs.
+The cache directory can be on tmpfs (for RAM speed and auto-cleanup on
+reboot) or regular disk — kanibako doesn't care.
+
+Usage::
+
+    cache = TweakccCache(Path("~/.cache/kanibako/tweakcc"))
+    key = cache.cache_key(binary_hash, cfg_hash)
+    entry = cache.get(key)
+    if entry is None:
+        def patch_fn(staging_dir, binary_path):
+            subprocess.run(["podman", "run", "--rm", ...], check=True)
+        entry = cache.put(key, source_binary, patch_fn)
+    # ... use entry.path as the patched binary ...
+    cache.release(entry)
+"""
+
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import json
+import os
+import shutil
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from kanibako.log import get_logger
+
+logger = get_logger("tweakcc_cache")
+
+
+class TweakccCacheError(Exception):
+    """Error during tweakcc cache operations."""
+
+
+@dataclass
+class CacheEntry:
+    """A locked reference to a cached patched binary."""
+
+    path: Path
+    fd: int
+
+
+def config_hash(config: dict) -> str:
+    """SHA-256 hex digest of a config dict (deterministic JSON)."""
+    serialized = json.dumps(config, sort_keys=True, separators=(",", ":")).encode()
+    return hashlib.sha256(serialized).hexdigest()
+
+
+class TweakccCache:
+    """Cache for tweakcc-patched binaries with flock reference counting.
+
+    Each cached binary is identified by a key derived from the source
+    binary's cli.js hash and the tweakcc config hash.  Active users hold
+    shared flocks; cleanup happens when no shared locks remain.
+    """
+
+    def __init__(self, cache_dir: Path) -> None:
+        self.cache_dir = cache_dir
+
+    def ensure_dir(self) -> None:
+        """Create the cache directory if it doesn't exist."""
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def cache_key(self, cli_js_hash: str, cfg_hash: str) -> str:
+        """Derive a short cache key from binary and config hashes."""
+        combined = f"{cli_js_hash}:{cfg_hash}"
+        return hashlib.sha256(combined.encode()).hexdigest()[:16]
+
+    def _entry_path(self, key: str) -> Path:
+        return self.cache_dir / key
+
+    def get(self, key: str) -> CacheEntry | None:
+        """Look up a cached binary and acquire a shared lock.
+
+        Returns *None* on cache miss (file missing or unlockable).
+        """
+        path = self._entry_path(key)
+        try:
+            fd = os.open(str(path), os.O_RDONLY)
+        except FileNotFoundError:
+            return None
+
+        try:
+            fcntl.flock(fd, fcntl.LOCK_SH | fcntl.LOCK_NB)
+            logger.debug("Cache hit: %s", key)
+            return CacheEntry(path=path, fd=fd)
+        except OSError:
+            os.close(fd)
+            return None
+
+    def put(
+        self,
+        key: str,
+        source_binary: Path,
+        patch_fn: Callable[[Path, Path], None],
+    ) -> CacheEntry:
+        """Copy *source_binary* to a staging dir, patch it, cache the result.
+
+        *patch_fn(staging_dir, binary_path)* is called with the staging
+        directory and the path to the copied binary within it.  The callable
+        must modify the binary in-place (it may create temp files in
+        *staging_dir*).
+
+        Raises :class:`TweakccCacheError` if *patch_fn* raises.
+        """
+        self.ensure_dir()
+        entry_path = self._entry_path(key)
+        staging_dir = self.cache_dir / f".staging-{key}-{os.getpid()}"
+
+        try:
+            staging_dir.mkdir(parents=True)
+            staging_binary = staging_dir / source_binary.name
+            shutil.copy2(str(source_binary), str(staging_binary))
+            staging_binary.chmod(0o755)
+
+            # Delegate patching to the caller-supplied function
+            logger.debug("Running patch_fn in staging dir: %s", staging_dir)
+            patch_fn(staging_dir, staging_binary)
+
+            # Move patched binary to cache entry
+            os.rename(str(staging_binary), str(entry_path))
+            logger.debug("Cached patched binary: %s", key)
+
+            # Acquire shared lock on the cached entry
+            fd = os.open(str(entry_path), os.O_RDONLY)
+            fcntl.flock(fd, fcntl.LOCK_SH)
+            return CacheEntry(path=entry_path, fd=fd)
+
+        except TweakccCacheError:
+            raise
+        except Exception as exc:
+            raise TweakccCacheError(f"Cache put failed: {exc}") from exc
+        finally:
+            # Clean up staging directory
+            if staging_dir.exists():
+                shutil.rmtree(staging_dir, ignore_errors=True)
+
+    def release(self, entry: CacheEntry) -> bool:
+        """Release a cache entry.  Unlinks the file if no other users remain.
+
+        Returns *True* if the file was unlinked, *False* otherwise.
+        The fd is always closed.
+        """
+        os.close(entry.fd)
+
+        # Best-effort cleanup: try exclusive lock on the file
+        try:
+            fd = os.open(str(entry.path), os.O_RDONLY)
+        except FileNotFoundError:
+            return True  # already gone
+
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            # We're the only one — safe to unlink
+            try:
+                os.unlink(str(entry.path))
+                logger.debug("Cleaned up cache entry: %s", entry.path.name)
+                return True
+            except FileNotFoundError:
+                return True
+            finally:
+                os.close(fd)
+        except OSError:
+            # Another process holds a lock — leave it
+            os.close(fd)
+            return False

kanibako/utils.py

@@ -0,0 +1,136 @@
+"""Utility functions: cp_if_newer, confirm_prompt, short_hash, path encoding, container naming."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from kanibako.errors import UserCancelled
+
+if TYPE_CHECKING:
+    from kanibako.paths import ProjectPaths
+
+
+def cp_if_newer(src: str | os.PathLike, dst: str | os.PathLike) -> bool:
+    """Copy *src* to *dst* only if *src* is strictly newer (by mtime).
+
+    Creates parent directories for *dst* if needed.
+    Returns True if the copy was performed.
+    """
+    src_s = str(src)
+    dst_s = str(dst)
+    if not os.path.isfile(src_s):
+        return False
+    do_copy = (
+        not os.path.isfile(dst_s)
+        or os.stat(src_s).st_mtime > os.stat(dst_s).st_mtime
+    )
+    if do_copy:
+        os.makedirs(os.path.dirname(dst_s) or ".", exist_ok=True)
+        shutil.copy2(src_s, dst_s)
+    return do_copy
+
+
+def confirm_prompt(message: str) -> None:
+    """Print *message*, read a line, raise UserCancelled unless it is 'yes'."""
+    print(message, end="", flush=True)
+    try:
+        response = input()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        raise UserCancelled("Aborted.")
+    if response.strip() != "yes":
+        raise UserCancelled("Aborted.")
+
+
+def short_hash(full_hash: str, length: int = 8) -> str:
+    """Return the first *length* characters of *full_hash*."""
+    return full_hash[:length]
+
+
+def container_name_for(proj: ProjectPaths) -> str:
+    """Deterministic container name for a project.
+
+    - Local with name: ``kanibako-{name}``
+    - Local without name (legacy): ``kanibako-{short_hash}``
+    - Workset: ``kanibako-{short_hash}`` (name-based pending workset naming)
+    - Standalone: ``kanibako-ronin-{escape_path(project_path)}``
+    """
+    if proj.mode.value == "standalone":
+        return f"kanibako-ronin-{escape_path(str(proj.project_path))}"
+    if proj.name:
+        return f"kanibako-{proj.name}"
+    return f"kanibako-{short_hash(proj.project_hash)}"
+
+
+def project_hash(project_path: str) -> str:
+    """SHA-256 hex digest of the project path string."""
+    return hashlib.sha256(project_path.encode()).hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# Standalone path encoding (for container names)
+# ---------------------------------------------------------------------------
+
+_DASH_ESCAPE = "-."
+
+
+def escape_path(path: str) -> str:
+    """Encode a filesystem path for use in container names.
+
+    - Drop leading ``/``
+    - Escape literal ``-`` → ``-.`` (dash-dot)
+    - Replace ``/`` → ``-``
+
+    Example: ``/home/user/my-project/app`` → ``home-user-my.-project-app``
+    """
+    path = path.lstrip("/")
+    path = path.replace("-", _DASH_ESCAPE)
+    path = path.replace("/", "-")
+    return path
+
+
+def unescape_path(encoded: str) -> str:
+    """Decode a container-name-encoded path back to a filesystem path.
+
+    Reverses ``escape_path``: ``-.`` → ``-``, lone ``-`` → ``/``,
+    prepends ``/``.
+    """
+    # Use a sentinel to avoid double-replacement.
+    sentinel = "\x00"
+    result = encoded.replace(_DASH_ESCAPE, sentinel)
+    result = result.replace("-", "/")
+    result = result.replace(sentinel, "-")
+    return "/" + result
+
+
+# ---------------------------------------------------------------------------
+# Project .gitignore helper
+# ---------------------------------------------------------------------------
+
+_GITIGNORE_ENTRIES = [".kanibako/"]
+
+
+def write_project_gitignore(project_path: Path) -> None:
+    """Append .kanibako/ to the project's root .gitignore."""
+    gitignore = project_path / ".gitignore"
+    existing = ""
+    if gitignore.is_file():
+        existing = gitignore.read_text()
+
+    lines_to_add = [
+        entry for entry in _GITIGNORE_ENTRIES
+        if entry not in existing.splitlines()
+    ]
+
+    if not lines_to_add:
+        return
+
+    with open(gitignore, "a") as f:
+        if existing and not existing.endswith("\n"):
+            f.write("\n")
+        for line in lines_to_add:
+            f.write(line + "\n")