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

kanibako/targets/__init__.py

@@ -0,0 +1,173 @@
+"""Target plugin discovery and resolution."""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import logging
+import pkgutil
+from importlib.metadata import entry_points
+from pathlib import Path
+
+from kanibako.targets.base import AgentInstall, Mount, ResourceMapping, ResourceScope, Target, TargetSetting
+from kanibako.targets.no_agent import NoAgentTarget
+
+__all__ = [
+    "AgentInstall", "Mount", "NoAgentTarget", "ResourceMapping", "ResourceScope",
+    "Target", "TargetSetting",
+    "discover_targets", "get_target", "resolve_target",
+]
+
+logger = logging.getLogger(__name__)
+
+
+def _scan_plugin_modules(targets: dict[str, type[Target]]) -> None:
+    """Scan ``kanibako.plugins.*`` for Target subclasses (bind-mount fallback).
+
+    Entry points rely on dist-info metadata which doesn't travel via
+    bind-mount.  This fallback imports all sub-packages of
+    ``kanibako.plugins`` and collects any ``Target`` subclasses found,
+    keyed by their ``name`` property.
+
+    Already-discovered targets (from entry points) are not overwritten.
+    """
+    try:
+        import kanibako.plugins as plugins_pkg
+    except ImportError:
+        return
+
+    for finder, module_name, ispkg in pkgutil.walk_packages(
+        plugins_pkg.__path__, prefix="kanibako.plugins."
+    ):
+        if module_name in ("kanibako.plugins",):
+            continue
+        try:
+            mod = importlib.import_module(module_name)
+        except Exception:
+            logger.debug("Failed to import plugin module %s", module_name, exc_info=True)
+            continue
+
+        for attr_name in dir(mod):
+            attr = getattr(mod, attr_name, None)
+            if (
+                isinstance(attr, type)
+                and issubclass(attr, Target)
+                and attr is not Target
+                and attr is not NoAgentTarget
+            ):
+                try:
+                    instance = attr()
+                    name = instance.name
+                except Exception:
+                    continue
+                if name not in targets:
+                    targets[name] = attr
+
+
+def _scan_directory_plugins(directory: Path, targets: dict[str, type[Target]]) -> None:
+    """Scan a directory for .py files containing Target subclasses.
+
+    Files starting with ``_`` are skipped.  Later directories in the
+    discovery chain override earlier ones (same target name replaces).
+    """
+    if not directory.is_dir():
+        return
+    for py_file in sorted(directory.glob("*.py")):
+        if py_file.name.startswith("_"):
+            continue
+        try:
+            spec = importlib.util.spec_from_file_location(
+                f"kanibako_plugin_{py_file.stem}", py_file,
+            )
+            if spec is None or spec.loader is None:
+                continue
+            mod = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(mod)  # type: ignore[union-attr]
+        except Exception:
+            logger.debug("Failed to load plugin %s", py_file, exc_info=True)
+            continue
+        for attr_name in dir(mod):
+            attr = getattr(mod, attr_name, None)
+            if (
+                isinstance(attr, type)
+                and issubclass(attr, Target)
+                and attr is not Target
+                and attr is not NoAgentTarget
+            ):
+                try:
+                    instance = attr()
+                    name = instance.name
+                except Exception:
+                    continue
+                targets[name] = attr  # later overrides earlier
+
+
+def discover_targets(project_path: Path | None = None) -> dict[str, type[Target]]:
+    """Scan entry points, plugin modules, and directories for targets.
+
+    Discovery order (later overrides earlier):
+
+    1. Entry points (pip-installed packages)
+    2. ``kanibako.plugins.*`` module scan (bind-mount fallback)
+    3. User directory (``~/.local/share/kanibako/plugins/``)
+    4. Project directory (``{project}/.kanibako/plugins/``)
+    """
+    targets: dict[str, type[Target]] = {}
+    # Group is agent-domain (a registry of agent adapters) → "kanibako.agents".
+    # NB: distinct from the crab-domain `kanibako.crabs` module; do not "unify".
+    eps = entry_points(group="kanibako.agents")
+    for ep in eps:
+        cls = ep.load()
+        targets[ep.name] = cls
+
+    # Fallback: scan kanibako.plugins.* for bind-mounted plugins
+    _scan_plugin_modules(targets)
+
+    # User-level file-drop plugins
+    from kanibako.paths import xdg
+
+    data_home = xdg("XDG_DATA_HOME", ".local/share")
+    _scan_directory_plugins(data_home / "kanibako" / "plugins", targets)
+
+    # Project-level file-drop plugins
+    if project_path is not None:
+        _scan_directory_plugins(project_path / ".kanibako" / "plugins", targets)
+
+    return targets
+
+
+def get_target(name: str, project_path: Path | None = None) -> type[Target]:
+    """Look up a target class by name.
+
+    Raises ``KeyError`` if no target with that name is registered.
+    """
+    targets = discover_targets(project_path)
+    if name not in targets:
+        available = ", ".join(sorted(targets)) or "(none)"
+        raise KeyError(f"Unknown target '{name}'. Available: {available}")
+    return targets[name]
+
+
+def resolve_target(
+    name: str | None = None, project_path: Path | None = None,
+) -> Target:
+    """Instantiate a target by name, or auto-detect.
+
+    If *name* is given, looks it up via entry points.
+    If *name* is None, iterates all discovered targets and returns the first
+    one whose ``detect()`` succeeds.
+
+    Raises ``KeyError`` if no matching target is found.
+    """
+    if name:
+        cls = get_target(name, project_path)
+        return cls()
+
+    # Auto-detect: try each target's detect() and return the first match.
+    targets = discover_targets(project_path)
+    for target_name, cls in targets.items():
+        instance = cls()
+        if instance.detect() is not None:
+            return instance
+
+    return NoAgentTarget()

kanibako/targets/base.py

@@ -0,0 +1,243 @@
+"""Target base classes: ABC for agent targets, Mount and AgentInstall dataclasses."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from kanibako.crabs import CrabConfig
+
+
+class ResourceScope(Enum):
+    """How an agent resource is shared across projects."""
+
+    SHARED = "shared"    # Shared across a workset (or the default workset)
+    PROJECT = "project"  # Per-project, starts fresh
+    SEEDED = "seeded"    # Per-project, seeded from workset template at creation
+
+
+@dataclass(frozen=True)
+class ResourceMapping:
+    """Maps an agent resource path to its sharing scope."""
+
+    path: str                    # Relative path within agent home (e.g. "plugins/")
+    scope: ResourceScope         # How this resource is shared
+    description: str = ""        # Human-readable description
+
+
+@dataclass(frozen=True)
+class TargetSetting:
+    """Declares a runtime setting that a target plugin supports.
+
+    Used by ``setting_descriptors()`` to advertise what settings exist,
+    their defaults, and (optionally) valid choices.
+    """
+
+    key: str                     # Setting key in agent state dict (e.g. "model")
+    description: str             # Human-readable description
+    default: str = ""            # Default value when not overridden
+    choices: tuple[str, ...] = ()  # Valid values; empty = freeform
+
+
+@dataclass(frozen=True)
+class Mount:
+    """A volume mount for a container."""
+
+    source: Path
+    destination: str
+    options: str = ""  # e.g. "ro"
+
+    def to_volume_arg(self) -> str:
+        """Return the -v argument string for podman/docker."""
+        base = f"{self.source}:{self.destination}"
+        return f"{base}:{self.options}" if self.options else base
+
+
+@dataclass
+class AgentInstall:
+    """Information about an agent installation on the host."""
+
+    name: str  # e.g. "claude"
+    binary: Path  # host symlink/path to agent binary
+    install_dir: Path  # root of agent installation
+
+
+class Target(ABC):
+    """Abstract base class for agent targets.
+
+    A target encapsulates all agent-specific logic: detection, binary mounting,
+    home directory initialization, credential management, and CLI argument
+    building.  Kanibako's core is agent-agnostic; all agent knowledge lives
+    in Target implementations.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Short identifier for this target (e.g. 'claude')."""
+        ...
+
+    @property
+    @abstractmethod
+    def display_name(self) -> str:
+        """Human-readable name (e.g. 'Claude Code')."""
+        ...
+
+    @abstractmethod
+    def detect(self) -> AgentInstall | None:
+        """Detect the agent installation on the host.
+
+        Returns an AgentInstall if found, or None if the agent is not installed.
+        """
+        ...
+
+    @abstractmethod
+    def binary_mounts(self, install: AgentInstall) -> list[Mount]:
+        """Return volume mounts needed to make the agent binary available in the container."""
+        ...
+
+    @abstractmethod
+    def init_home(self, home: Path, *, group_auth: bool = True) -> None:
+        """Initialize agent-specific files in the project home directory.
+
+        Called after kanibako core creates .bashrc/.profile.  The target
+        should create its own config directories and files (e.g. .claude/).
+
+        *group_auth* is ``True`` (copy credentials from host) or ``False``
+        (skip credential copy — project manages its own credentials).
+        """
+        ...
+
+    @property
+    def has_binary(self) -> bool:
+        """Whether this target requires a host-installed binary."""
+        return True
+
+    def check_auth(self) -> bool:
+        """Check if the agent is authenticated. Returns True if ok."""
+        return True
+
+    def resource_mappings(self) -> list[ResourceMapping]:
+        """Declare how agent resources are shared across projects.
+
+        Returns a list of ResourceMapping entries describing which paths
+        within the agent's home directory are shared, project-scoped, or
+        seeded from workset defaults.
+
+        The default returns an empty list, meaning all agent resources
+        are treated as project-scoped (the current behavior).
+
+        Paths are relative to the agent's config directory within the
+        project shell (e.g. ".claude/" for ClaudeTarget).
+        """
+        return []
+
+    def default_shares(self) -> dict[str, str]:
+        """Declare default scoped shares for this agent's crab.
+
+        Returns a mapping of full scoped-share keys
+        ({scope}.path.share_{ro,rw}.{name}) to host_src:guest_dest bind
+        expressions. These become the CRAB level's *declared defaults* in the
+        share resolver — a user can override or suppress (terminal "") any of
+        them at a more-specific level. The default returns {} (no shares).
+        """
+        return {}
+
+    def default_seeds(self) -> dict[str, str]:
+        """Declare default copy-once-at-init seeds for this agent's crab.
+
+        Returns a mapping of full seed keys ({scope}.path.seeded.{name}) to
+        host_src:guest_dest expressions, injected as the CRAB level's declared
+        defaults in the seed resolver. A user can override or suppress (terminal
+        "" or the "empty" sentinel) any of them at a more-specific level. The
+        default returns {} (no seeds). No target ships a default seed yet.
+        """
+        return {}
+
+    def setting_descriptors(self) -> list[TargetSetting]:
+        """Declare what runtime settings this target supports.
+
+        Returns a list of TargetSetting entries describing the key name,
+        default value, valid choices, and human-readable description.
+
+        The default returns an empty list (no declared settings).
+        """
+        return []
+
+    def generate_crab_config(self) -> CrabConfig:
+        """Return a default CrabConfig for this target.
+
+        Subclasses should override to provide agent-specific defaults
+        (template variant, state knobs, shared caches, etc.).
+        """
+        from kanibako.crabs import CrabConfig as _CrabConfig
+
+        return _CrabConfig(name=self.display_name)
+
+    def apply_state(self, state: dict[str, str]) -> tuple[list[str], dict[str, str]]:
+        """Translate crab-state values into CLI args and env vars.
+
+        Returns ``(cli_args, env_vars)``.  Base implementation ignores all
+        state keys.  Subclasses override to handle known keys.
+        """
+        return [], {}
+
+    @property
+    def default_entrypoint(self) -> str | None:
+        """Binary name for container entrypoint. None = use bash."""
+        return None
+
+    def should_retry_new_session(self, output: str) -> bool:
+        """Check if agent output indicates ``--continue`` failed and a new session should be started."""
+        return False
+
+    @property
+    def config_dir_name(self) -> str:
+        """Agent config dir relative to home (e.g. '.claude'). Default: '.{name}'."""
+        return f".{self.name}"
+
+    def instruction_files(self) -> list[str]:
+        """Return filenames that should be layered across template levels.
+
+        These files are merged (concatenated with section markers) from
+        three layers: kanibako base, template, and user project.  Each
+        filename is relative to the agent's config dir within the shell
+        directory (e.g. ``"CLAUDE.md"`` lives at ``shell/.claude/CLAUDE.md``).
+
+        The default returns an empty list (no instruction files merged).
+        """
+        return []
+
+    def credential_check_path(self, home: Path) -> Path | None:
+        """Path to check for credential existence, or None."""
+        return None
+
+    def invalidate_credentials(self, home: Path) -> None:
+        """Remove credential files when switching to distinct auth. Default: no-op."""
+
+    @abstractmethod
+    def refresh_credentials(self, home: Path) -> None:
+        """Refresh agent credentials from host into the project home."""
+        ...
+
+    @abstractmethod
+    def writeback_credentials(self, home: Path) -> None:
+        """Write back credentials from project home to host."""
+        ...
+
+    @abstractmethod
+    def build_cli_args(
+        self,
+        *,
+        safe_mode: bool,
+        resume_mode: bool,
+        new_session: bool,
+        is_new_project: bool,
+        extra_args: list[str],
+    ) -> list[str]:
+        """Build command-line arguments for the agent entrypoint."""
+        ...

kanibako/targets/no_agent.py

@@ -0,0 +1,58 @@
+"""NoAgentTarget: built-in fallback target that runs a plain shell."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from kanibako.targets.base import AgentInstall, Mount, Target
+
+if TYPE_CHECKING:
+    from kanibako.crabs import CrabConfig
+
+
+class NoAgentTarget(Target):
+    """Fallback target that launches /bin/sh without any agent binary."""
+
+    @property
+    def name(self) -> str:
+        return "no_agent"
+
+    @property
+    def display_name(self) -> str:
+        return "Shell"
+
+    @property
+    def has_binary(self) -> bool:
+        return False
+
+    def detect(self) -> AgentInstall | None:
+        return None
+
+    def binary_mounts(self, install: AgentInstall) -> list[Mount]:
+        return []
+
+    def init_home(self, home: Path, *, group_auth: bool = True) -> None:
+        pass
+
+    def refresh_credentials(self, home: Path) -> None:
+        pass
+
+    def writeback_credentials(self, home: Path) -> None:
+        pass
+
+    def build_cli_args(
+        self,
+        *,
+        safe_mode: bool,
+        resume_mode: bool,
+        new_session: bool,
+        is_new_project: bool,
+        extra_args: list[str],
+    ) -> list[str]:
+        return []
+
+    def generate_crab_config(self) -> CrabConfig:
+        from kanibako.crabs import CrabConfig as _CrabConfig
+
+        return _CrabConfig(name="Shell")

kanibako/templates.py

@@ -0,0 +1,60 @@
+"""Shell template resolution and application."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+
+def resolve_template(
+    templates_base: Path,
+    agent_name: str,
+    template_name: str = "standard",
+) -> Path | None:
+    """Return the path to the resolved template directory, or None for 'empty'.
+
+    Resolution order:
+      1. {templates_base}/{agent_name}/{template_name}/
+      2. {templates_base}/general/{template_name}/
+      3. None (empty template — no files applied)
+    """
+    if template_name == "empty":
+        return None
+
+    agent_dir = templates_base / agent_name / template_name
+    if agent_dir.is_dir():
+        return agent_dir
+
+    general_dir = templates_base / "general" / template_name
+    if general_dir.is_dir():
+        return general_dir
+
+    return None
+
+
+def apply_shell_template(
+    shell_path: Path,
+    templates_base: Path,
+    agent_name: str,
+    template_name: str = "standard",
+) -> None:
+    """Apply base + resolved template to a shell directory.
+
+    Layering:
+      1. general/base/* is copied first (common skeleton)
+      2. The resolved template overlays on top
+
+    No-op if the resolved template is None (the ``"empty"`` sentinel or no
+    template dirs exist on disk).
+    """
+    resolved = resolve_template(templates_base, agent_name, template_name)
+    if resolved is None:
+        return
+
+    # Layer 1: general/base (if it exists)
+    base_dir = templates_base / "general" / "base"
+    if base_dir.is_dir():
+        shutil.copytree(str(base_dir), str(shell_path), dirs_exist_ok=True)
+
+    # Layer 2: resolved template
+    shutil.copytree(str(resolved), str(shell_path), dirs_exist_ok=True)