familiar-cli 0.4.0__tar.gz → 0.5.1__tar.gz

{familiar_cli-0.4.0/src/familiar_cli.egg-info → familiar_cli-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: familiar-cli
-Version: 0.4.0
+Version: 0.5.1
 Summary: compose and invoke ai agent prompts from reusable templates
 Author-email: cyberwitchery lab <contact@cyberwitchery.com>
 License-Expression: MIT

{familiar_cli-0.4.0 → familiar_cli-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "familiar-cli"
-version = "0.4.0"
+version = "0.5.1"
 description = "compose and invoke ai agent prompts from reusable templates"
 readme = "readme.md"
 license = "MIT"

familiar_cli-0.5.1/src/familiar/_plugins.py

@@ -0,0 +1,44 @@
+"""Shared plugin loading utilities."""
+
+from __future__ import annotations
+
+import warnings
+from importlib.metadata import entry_points
+from typing import Any, Callable
+
+
+def load_plugins(
+    group: str,
+    validate: Callable[[Any], bool],
+    *,
+    label: str,
+    invalid_msg: str = "validation failed",
+) -> list[Any]:
+    """Load plugins from entry points with validation.
+
+    Args:
+        group: Entry point group name.
+        validate: Predicate that returns True for valid loaded objects.
+        label: Human-readable label for warning messages (e.g. "linter plugin").
+        invalid_msg: Message when validation fails.
+
+    Returns:
+        List of loaded and validated plugin objects.
+    """
+    results: list[Any] = []
+    for ep in entry_points(group=group):
+        try:
+            obj = ep.load()
+            if not validate(obj):
+                warnings.warn(
+                    f"{label} '{ep.name}': {invalid_msg}",
+                    stacklevel=2,
+                )
+                continue
+            results.append(obj)
+        except Exception as e:
+            warnings.warn(
+                f"failed to load {label} '{ep.name}': {e}",
+                stacklevel=2,
+            )
+    return results

{familiar_cli-0.4.0 → familiar_cli-0.5.1}/src/familiar/agents.py

@@ -5,9 +5,10 @@ from __future__ import annotations
 import subprocess
 import warnings
 from abc import ABC, abstractmethod
-from importlib.metadata import entry_points
 from pathlib import Path
 
+from ._plugins import load_plugins
+
 
 class Agent(ABC):
     """Base class for AI coding agents."""
@@ -96,26 +97,22 @@ def load_agents() -> dict[str, Agent]:
         Dictionary mapping agent names to Agent instances.
         Plugins that fail to load are skipped with a warning.
     """
+    plugins = load_plugins(
+        "familiar.agents",
+        lambda cls: isinstance(cls, type) and issubclass(cls, Agent),
+        label="agent plugin",
+        invalid_msg="not a valid Agent subclass",
+    )
     agents: dict[str, Agent] = {}
-    eps = entry_points(group="familiar.agents")
-
-    for ep in eps:
+    for cls in plugins:
         try:
-            cls = ep.load()
-            if not (isinstance(cls, type) and issubclass(cls, Agent)):
-                warnings.warn(
-                    f"agent plugin '{ep.name}': not a valid Agent subclass",
-                    stacklevel=2,
-                )
-                continue
             instance = cls()
             agents[instance.name] = instance
         except Exception as e:
             warnings.warn(
-                f"failed to load agent plugin '{ep.name}': {e}",
+                f"failed to load agent plugin '{cls.__name__}': {e}",
                 stacklevel=2,
             )
-
     return agents
 
 

{familiar_cli-0.4.0 → familiar_cli-0.5.1}/src/familiar/cli.py

@@ -10,9 +10,11 @@ import subprocess
 import sys
 import tempfile
 import traceback
+import warnings
+from importlib.metadata import version
 from pathlib import Path
 
-from .agents import get_agents, get_agent
+from .agents import Agent, get_agents, get_agent
 from .lint import lint_all
 from .render import (
     NotFoundError,
@@ -26,8 +28,7 @@ from .render import (
 EXIT_SUCCESS = 0
 EXIT_ERROR = 1  # general error (agent failed, etc.)
 EXIT_USAGE = 2  # usage error (bad args, missing files, etc.)
-_VALID_SKILL_NAME = re.compile(r"^[a-z0-9_-]+$")
-_VALID_SUBAGENT_NAME = re.compile(r"^[a-z0-9_-]+$")
+_VALID_NAME = re.compile(r"^[a-z0-9_-]+$")
 
 
 class CliError(Exception):
@@ -41,6 +42,32 @@ class CliError(Exception):
         self.exit_code = exit_code
 
 
+def _agent_hint() -> str:
+    """Return a hint string listing valid agent names."""
+    return f"valid agents: {', '.join(get_agents().keys())}"
+
+
+def _resolve_agent(name: str) -> "Agent":
+    """Look up an agent by name, raising CliError on unknown names."""
+    try:
+        return get_agent(name)
+    except KeyError as e:
+        raise CliError(str(e), hint=_agent_hint())
+
+
+def _write_file(path: Path, content: str, label: str = "") -> None:
+    """Write content to path, creating parent dirs. Wraps OSError as CliError."""
+    prefix = f"{label} " if label else ""
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+    except OSError as e:
+        raise CliError(
+            f"cannot write {prefix}{path}: {e}",
+            hint="check file permissions and disk space",
+        )
+
+
 def find_repo_root(start: Path) -> Path:
     """Find the repository root by looking for .git directory.
 
@@ -54,6 +81,31 @@ def find_repo_root(start: Path) -> Path:
     return cur
 
 
+def _remove_worktree(repo_root: Path, worktree_path: Path) -> None:
+    """Best-effort removal of a git worktree."""
+    try:
+        result = subprocess.run(
+            [
+                "git",
+                "-C",
+                str(repo_root),
+                "worktree",
+                "remove",
+                "--force",
+                str(worktree_path),
+            ],
+            capture_output=True,
+        )
+        if result.returncode != 0:
+            stderr = result.stderr.decode(errors="replace").strip()
+            warnings.warn(
+                f"failed to remove worktree {worktree_path}: {stderr}",
+                stacklevel=2,
+            )
+    except FileNotFoundError:
+        pass
+
+
 def create_worktree(repo_root: Path) -> Path:
     """Create a temporary git worktree for the repository."""
     # Ensure it's a git repo
@@ -95,33 +147,27 @@ def create_worktree(repo_root: Path) -> Path:
 
 
 def write_instruction(repo_root: Path, agent_name: str, system: str) -> None:
-    try:
-        agent = get_agent(agent_name)
-    except KeyError as e:
-        raise CliError(str(e), hint=f"valid agents: {', '.join(get_agents().keys())}")
-    (repo_root / agent.output_file).write_text(system.strip() + "\n", encoding="utf-8")
+    agent = _resolve_agent(agent_name)
+    dest = repo_root / agent.output_file
+    _write_file(dest, system.strip() + "\n")
 
 
 def write_skill(
     repo_root: Path, agent_name: str, invocation: str, skill_name: str, prompt: str
 ) -> Path:
     """Write a reusable skill file for supported agents."""
-    if not _VALID_SKILL_NAME.match(skill_name):
+    if not _VALID_NAME.match(skill_name):
         raise CliError(
             f"invalid skill name: {skill_name}",
             hint="use lowercase letters, numbers, underscore, or hyphen",
         )
 
-    try:
-        agent = get_agent(agent_name)
-    except KeyError as e:
-        raise CliError(str(e), hint=f"valid agents: {', '.join(get_agents().keys())}")
+    agent = _resolve_agent(agent_name)
 
     if not agent.supports_skills():
         raise CliError(f"agent does not support skills: {agent_name}")
 
     skill_path = agent.skill_path(repo_root, skill_name)
-    skill_path.parent.mkdir(parents=True, exist_ok=True)
     content = (
         f"# {skill_name}\n\n"
         "use this skill when this recurring task appears in this repository.\n\n"
@@ -131,7 +177,7 @@ def write_skill(
         "## instructions\n\n"
         f"{prompt.strip()}\n"
     )
-    skill_path.write_text(content, encoding="utf-8")
+    _write_file(skill_path, content, label="skill")
     return skill_path
 
 
@@ -143,22 +189,18 @@ def write_subagent(
     system: str,
 ) -> Path:
     """Write a reusable subagent file for supported agents."""
-    if not _VALID_SUBAGENT_NAME.match(subagent_name):
+    if not _VALID_NAME.match(subagent_name):
         raise CliError(
             f"invalid subagent name: {subagent_name}",
             hint="use lowercase letters, numbers, underscore, or hyphen",
         )
 
-    try:
-        agent = get_agent(agent_name)
-    except KeyError as e:
-        raise CliError(str(e), hint=f"valid agents: {', '.join(get_agents().keys())}")
+    agent = _resolve_agent(agent_name)
 
     if not agent.supports_subagents():
         raise CliError(f"agent does not support subagents: {agent_name}")
 
     subagent_path = agent.subagent_path(repo_root, subagent_name)
-    subagent_path.parent.mkdir(parents=True, exist_ok=True)
     profile = ", ".join(conjurings)
     content = (
         f"# {subagent_name}\n\n"
@@ -169,7 +211,7 @@ def write_subagent(
         "## instructions\n\n"
         f"{system.strip()}\n"
     )
-    subagent_path.write_text(content, encoding="utf-8")
+    _write_file(subagent_path, content, label="subagent")
     return subagent_path
 
 
@@ -189,10 +231,7 @@ def parse_kv(pairs: list[str]) -> dict[str, str]:
 def run_agent(
     repo_root: Path, agent_name: str, prompt: str, headless: bool, auto: bool = False
 ) -> int:
-    try:
-        agent = get_agent(agent_name)
-    except KeyError as e:
-        raise CliError(str(e), hint=f"valid agents: {', '.join(get_agents().keys())}")
+    agent = _resolve_agent(agent_name)
     try:
         return agent.run(repo_root, prompt, headless, auto=auto)
     except FileNotFoundError:
@@ -258,8 +297,11 @@ def cmd_invoke(args: argparse.Namespace) -> int:
             instr_file = repo_root / agent.output_file
             if instr_file.exists():
                 shutil.copy2(instr_file, target_dir / agent.output_file)
-        except (OSError, KeyError):
-            pass
+        except (OSError, KeyError) as exc:
+            warnings.warn(
+                f"failed to copy instruction file into worktree: {exc}",
+                stacklevel=2,
+            )
 
     try:
         rc = run_agent(
@@ -271,7 +313,7 @@ def cmd_invoke(args: argparse.Namespace) -> int:
         return rc
     except Exception:
         if args.worktree:
-            print(f"\nworktree remains at: {target_dir}")
+            _remove_worktree(repo_root, target_dir)
         raise
 
 
@@ -357,6 +399,11 @@ def main() -> None:
         "  familiar lint                        # validate prompts\n",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {version('familiar-cli')}",
+    )
     parser.add_argument(
         "--debug", action="store_true", help="show full traceback on error"
     )

{familiar_cli-0.4.0 → familiar_cli-0.5.1}/src/familiar/lint.py

@@ -3,12 +3,12 @@
 from __future__ import annotations
 
 import re
-import warnings
 from dataclasses import dataclass
-from importlib.metadata import entry_points
 from pathlib import Path
 from typing import Callable, Literal
 
+from ._plugins import load_plugins
+
 from .render import _SNIPPET_INCLUDE, NotFoundError, list_items, load_snippet, load_text
 
 
@@ -202,27 +202,12 @@ def load_linters(kind: Literal["conjurings", "invocations"]) -> list[LinterFunc]
     Returns:
         List of linter functions from plugins.
     """
-    linters: list[LinterFunc] = []
-    group = f"familiar.linters.{kind}"
-    eps = entry_points(group=group)
-
-    for ep in eps:
-        try:
-            func = ep.load()
-            if not callable(func):
-                warnings.warn(
-                    f"linter plugin '{ep.name}': not callable",
-                    stacklevel=2,
-                )
-                continue
-            linters.append(func)
-        except Exception as e:
-            warnings.warn(
-                f"failed to load linter plugin '{ep.name}': {e}",
-                stacklevel=2,
-            )
-
-    return linters
+    return load_plugins(
+        f"familiar.linters.{kind}",
+        callable,
+        label="linter plugin",
+        invalid_msg="not callable",
+    )
 
 
 def lint_snippet_references(
@@ -280,7 +265,7 @@ def lint_collection(
                             message=f"plugin linter failed: {e}",
                         )
                     )
-        except Exception as e:
+        except NotFoundError as e:
             messages.append(
                 LintMessage(
                     level="error",

{familiar_cli-0.4.0 → familiar_cli-0.5.1}/src/familiar/render.py

@@ -21,13 +21,23 @@ class NotFoundError(Exception):
     """Raised when a conjuring, invocation, or snippet is not found."""
 
 
+def _safe_read_text(path: Path, label: str) -> str:
+    """Read a UTF-8 text file, converting I/O errors to :class:`NotFoundError`."""
+    try:
+        return path.read_text(encoding="utf-8")
+    except PermissionError:
+        raise NotFoundError(f"cannot read {label}: permission denied on {path}")
+    except UnicodeDecodeError:
+        raise NotFoundError(f"cannot read {label}: {path} is not valid UTF-8")
+
+
 def load_text(repo_root: Path, kind: str, name: str) -> str:
     """Load a conjuring or invocation; local overrides in .familiar override package data."""
     if not _VALID_NAME.match(name):
         raise NotFoundError(f"invalid {kind.rstrip('s')} name: {name}")
     override = repo_root / ".familiar" / kind / f"{name}.md"
     if override.exists():
-        return override.read_text(encoding="utf-8")
+        return _safe_read_text(override, f"{kind.rstrip('s')} '{name}'")
     pkg = f"familiar.data.{kind}"
     try:
         return (resources.files(pkg) / f"{name}.md").read_text(encoding="utf-8")
@@ -47,7 +57,7 @@ def load_snippet(repo_root: Path, path: str) -> str:
 
     override = repo_root / ".familiar" / "snippets" / path
     if override.exists():
-        return override.read_text(encoding="utf-8")
+        return _safe_read_text(override, f"snippet '{path}'")
 
     try:
         ref: Traversable = resources.files("familiar.data.snippets")
@@ -110,7 +120,10 @@ def _walk_traversable(root: Traversable, prefix: str = "") -> list[tuple[str, st
             if item.is_dir():
                 items.extend(_walk_traversable(item, rel))
             elif not item.name.startswith("_"):
-                content = item.read_text(encoding="utf-8")
+                try:
+                    content = item.read_text(encoding="utf-8")
+                except (UnicodeDecodeError, PermissionError):
+                    continue
                 first_line = content.split("\n", 1)[0].strip()
                 items.append((rel, first_line))
     except (FileNotFoundError, TypeError):
@@ -118,71 +131,91 @@ def _walk_traversable(root: Traversable, prefix: str = "") -> list[tuple[str, st
     return items
 
 
-def list_snippets(repo_root: Path) -> list[tuple[str, str, bool]]:
-    """List available snippets.
+def _list_resources(
+    repo_root: Path,
+    pkg: str,
+    local_subdir: str,
+    *,
+    recursive: bool = False,
+    suffix: str = "",
+) -> list[tuple[str, str, bool]]:
+    """List resources from package data and local overrides.
 
-    Returns list of (path, first_line, is_local) tuples, sorted by path.
+    Items from local ``.familiar/{local_subdir}/`` override package builtins.
+
+    Args:
+        repo_root: Repository root path.
+        pkg: Package name to scan for builtins.
+        local_subdir: Subdirectory name under ``.familiar/`` for local overrides.
+        recursive: If True, scan recursively (for nested resources like snippets).
+        suffix: File suffix filter (e.g. ``".md"``). Empty string matches all files.
+
+    Returns:
+        Sorted list of ``(key, first_line, is_local)`` tuples.
     """
     items: dict[str, tuple[str, bool]] = {}
 
-    # built-ins
+    # built-in resources from package data
     try:
-        pkg_root = resources.files("familiar.data.snippets")
-        for rel, first_line in _walk_traversable(pkg_root):
-            items[rel] = (first_line, False)
+        pkg_root = resources.files(pkg)
+        if recursive:
+            for rel, first_line in _walk_traversable(pkg_root):
+                items[rel] = (first_line, False)
+        else:
+            for item in pkg_root.iterdir():
+                if suffix and not item.name.endswith(suffix):
+                    continue
+                if item.name.startswith("_"):
+                    continue
+                key = item.name[: -len(suffix)] if suffix else item.name
+                try:
+                    content = item.read_text(encoding="utf-8")
+                except (UnicodeDecodeError, PermissionError):
+                    continue
+                first_line = content.split("\n", 1)[0].strip()
+                items[key] = (first_line, False)
     except (FileNotFoundError, TypeError, ModuleNotFoundError):
         pass
 
     # local overrides
-    local_dir = repo_root / ".familiar" / "snippets"
+    local_dir = repo_root / ".familiar" / local_subdir
     if local_dir.is_dir():
-        for f in sorted(local_dir.rglob("*")):
-            if f.is_file() and not f.name.startswith("_"):
-                rel = str(f.relative_to(local_dir))
+        files = (
+            sorted(local_dir.rglob("*")) if recursive else local_dir.glob(f"*{suffix}")
+        )
+        for f in files:
+            if not f.is_file() or f.name.startswith("_"):
+                continue
+            key = str(f.relative_to(local_dir)) if recursive else f.stem
+            try:
                 content = f.read_text(encoding="utf-8")
-                first_line = content.split("\n", 1)[0].strip()
-                items[rel] = (first_line, True)
+            except (UnicodeDecodeError, PermissionError):
+                continue
+            first_line = content.split("\n", 1)[0].strip()
+            items[key] = (first_line, True)
 
     return [
-        (path, first_line, is_local)
-        for path, (first_line, is_local) in sorted(items.items())
+        (key, first_line, is_local)
+        for key, (first_line, is_local) in sorted(items.items())
     ]
 
 
-def list_items(repo_root: Path, kind: str) -> list[tuple[str, str, bool]]:
-    """List available conjurings or invocations.
+def list_snippets(repo_root: Path) -> list[tuple[str, str, bool]]:
+    """List available snippets.
 
-    Returns list of (name, first_line, is_local) tuples, sorted by name.
+    Returns list of (path, first_line, is_local) tuples, sorted by path.
     """
-    items: dict[str, tuple[str, bool]] = {}
+    return _list_resources(
+        repo_root, "familiar.data.snippets", "snippets", recursive=True
+    )
 
-    # built-ins
-    pkg = f"familiar.data.{kind}"
-    try:
-        pkg_files = resources.files(pkg)
-        for item in pkg_files.iterdir():
-            if item.name.endswith(".md") and not item.name.startswith("_"):
-                name = item.name[:-3]
-                content = item.read_text(encoding="utf-8")
-                first_line = content.split("\n", 1)[0].strip()
-                items[name] = (first_line, False)
-    except (FileNotFoundError, TypeError):
-        pass
 
-    # local overrides
-    local_dir = repo_root / ".familiar" / kind
-    if local_dir.is_dir():
-        for f in local_dir.glob("*.md"):
-            if not f.name.startswith("_"):
-                name = f.stem
-                content = f.read_text(encoding="utf-8")
-                first_line = content.split("\n", 1)[0].strip()
-                items[name] = (first_line, True)
+def list_items(repo_root: Path, kind: str) -> list[tuple[str, str, bool]]:
+    """List available conjurings or invocations.
 
-    return [
-        (name, first_line, is_local)
-        for name, (first_line, is_local) in sorted(items.items())
-    ]
+    Returns list of (name, first_line, is_local) tuples, sorted by name.
+    """
+    return _list_resources(repo_root, f"familiar.data.{kind}", kind, suffix=".md")
 
 
 def compose_system(repo_root: Path, conjurings: list[str]) -> str:

{familiar_cli-0.4.0 → familiar_cli-0.5.1/src/familiar_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: familiar-cli
-Version: 0.4.0
+Version: 0.5.1
 Summary: compose and invoke ai agent prompts from reusable templates
 Author-email: cyberwitchery lab <contact@cyberwitchery.com>
 License-Expression: MIT

{familiar_cli-0.4.0 → familiar_cli-0.5.1}/src/familiar_cli.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 pyproject.toml
 readme.md
 src/familiar/__init__.py
+src/familiar/_plugins.py
 src/familiar/agents.py
 src/familiar/cli.py
 src/familiar/lint.py

{familiar_cli-0.4.0 → familiar_cli-0.5.1}/tests/test_agents.py

@@ -68,7 +68,7 @@ class TestPluginLoadErrors:
         mock_ep.name = "invalid"
         mock_ep.load.return_value = str  # not an Agent subclass
 
-        with patch("familiar.agents.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="not a valid Agent subclass"):
                 agents = load_agents()
             assert "invalid" not in agents
@@ -79,7 +79,7 @@ class TestPluginLoadErrors:
         mock_ep.name = "broken"
         mock_ep.load.side_effect = ImportError("module not found")
 
-        with patch("familiar.agents.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="failed to load"):
                 agents = load_agents()
             assert "broken" not in agents
@@ -101,7 +101,7 @@ class TestPluginLoadErrors:
         mock_ep.name = "bad"
         mock_ep.load.return_value = BadAgent
 
-        with patch("familiar.agents.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="failed to load"):
                 agents = load_agents()
             assert "bad" not in agents

{familiar_cli-0.4.0 → familiar_cli-0.5.1}/tests/test_cli.py

@@ -8,11 +8,17 @@ from unittest.mock import patch
 import argparse
 
 from familiar.cli import (
+    _remove_worktree,
+    _resolve_agent,
+    _write_file,
     find_repo_root,
     create_worktree,
     write_instruction,
+    write_skill,
+    write_subagent,
     parse_kv,
     run_agent,
+    main,
     cmd_conjure,
     cmd_invoke,
     cmd_list,
@@ -21,6 +27,19 @@ from familiar.cli import (
 )
 
 
+class TestVersion:
+    """tests for --version flag."""
+
+    def test_version_prints_and_exits(self, capsys):
+        with pytest.raises(SystemExit, match="0"):
+            with patch("sys.argv", ["familiar", "--version"]):
+                main()
+        captured = capsys.readouterr()
+        assert "familiar" in captured.out
+        # version string should look like a semver
+        assert any(c.isdigit() for c in captured.out)
+
+
 class TestCreateWorktree:
     """tests for git worktree creation."""
 
@@ -70,6 +89,50 @@ class TestFindRepoRoot:
         assert result == subdir.resolve()
 
 
+class TestResolveAgent:
+    """tests for _resolve_agent helper."""
+
+    def test_returns_known_agent(self):
+        agent = _resolve_agent("claude")
+        assert agent.name == "claude"
+
+    def test_unknown_agent_raises(self):
+        with pytest.raises(CliError, match="unknown agent"):
+            _resolve_agent("nonexistent")
+
+    def test_unknown_agent_includes_hint(self):
+        with pytest.raises(CliError) as exc_info:
+            _resolve_agent("nonexistent")
+        assert exc_info.value.hint is not None
+        assert "valid agents" in exc_info.value.hint
+
+
+class TestWriteFile:
+    """tests for _write_file helper."""
+
+    def test_writes_content(self, tmp_path):
+        dest = tmp_path / "out.txt"
+        _write_file(dest, "hello\n")
+        assert dest.read_text() == "hello\n"
+
+    def test_creates_parent_dirs(self, tmp_path):
+        dest = tmp_path / "a" / "b" / "out.txt"
+        _write_file(dest, "nested\n")
+        assert dest.read_text() == "nested\n"
+
+    def test_oserror_without_label(self, tmp_path):
+        dest = tmp_path / "out.txt"
+        with patch("pathlib.Path.write_text", side_effect=PermissionError("denied")):
+            with pytest.raises(CliError, match="cannot write .*/out.txt"):
+                _write_file(dest, "content")
+
+    def test_oserror_with_label(self, tmp_path):
+        dest = tmp_path / "out.txt"
+        with patch("pathlib.Path.write_text", side_effect=PermissionError("denied")):
+            with pytest.raises(CliError, match="cannot write skill .*/out.txt"):
+                _write_file(dest, "content", label="skill")
+
+
 class TestWriteInstruction:
     """tests for writing instruction files."""
 
@@ -86,6 +149,48 @@ class TestWriteInstruction:
         assert (tmp_path / "CLAUDE.md").read_text() == "content\n"
 
 
+class TestRemoveWorktree:
+    """tests for git worktree removal."""
+
+    def test_warns_on_nonzero_return_code(self, tmp_path):
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = argparse.Namespace(
+                returncode=1, stderr=b"worktree not found"
+            )
+            with pytest.warns(UserWarning, match="failed to remove worktree"):
+                _remove_worktree(tmp_path, tmp_path / "wt")
+
+    def test_no_warning_on_success(self, tmp_path, recwarn):
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = argparse.Namespace(returncode=0, stderr=b"")
+            _remove_worktree(tmp_path, tmp_path / "wt")
+            assert len(recwarn) == 0
+
+    def test_silent_on_missing_git(self, tmp_path, recwarn):
+        with patch("subprocess.run", side_effect=FileNotFoundError):
+            _remove_worktree(tmp_path, tmp_path / "wt")
+            assert len(recwarn) == 0
+
+
+class TestWriteFailures:
+    """tests for write error handling."""
+
+    def test_write_instruction_permission_denied(self, tmp_path):
+        with patch("pathlib.Path.write_text", side_effect=PermissionError("denied")):
+            with pytest.raises(CliError, match="cannot write"):
+                write_instruction(tmp_path, "claude", "content")
+
+    def test_write_skill_permission_denied(self, tmp_path):
+        with patch("pathlib.Path.write_text", side_effect=PermissionError("denied")):
+            with pytest.raises(CliError, match="cannot write skill"):
+                write_skill(tmp_path, "claude", "explain", "my-skill", "prompt")
+
+    def test_write_subagent_permission_denied(self, tmp_path):
+        with patch("pathlib.Path.write_text", side_effect=PermissionError("denied")):
+            with pytest.raises(CliError, match="cannot write subagent"):
+                write_subagent(tmp_path, "claude", ["python"], "my-subagent", "system")
+
+
 class TestParseKv:
     """tests for key-value parsing."""
 
@@ -329,6 +434,27 @@ class TestCmdInvoke:
                     # Check that instruction file was copied
                     mock_copy.assert_called_once()
 
+    def test_invoke_worktree_cleaned_up_on_error(self, tmp_path):
+        with patch("familiar.cli.create_worktree", return_value=tmp_path / "wt"):
+            with patch("familiar.cli.run_agent", side_effect=RuntimeError("boom")):
+                with patch("familiar.cli._remove_worktree") as mock_remove:
+                    args = argparse.Namespace(
+                        agent="claude",
+                        invocation="explain",
+                        into=str(tmp_path),
+                        headless=True,
+                        auto=False,
+                        dry_run=False,
+                        kv=None,
+                        inv_args=[],
+                        worktree=True,
+                        save_skill=False,
+                        skill_name=None,
+                    )
+                    with pytest.raises(RuntimeError, match="boom"):
+                        cmd_invoke(args)
+                    mock_remove.assert_called_once()
+
     def test_invoke_save_skill_claude(self, tmp_path):
         with patch("familiar.cli.run_agent") as mock_run:
             args = argparse.Namespace(

{familiar_cli-0.4.0 → familiar_cli-0.5.1}/tests/test_lint.py

@@ -9,11 +9,13 @@ import pytest
 from familiar.lint import (
     LintMessage,
     lint_all,
+    lint_collection,
     lint_invocation,
     lint_snippet_references,
     lint_template,
     load_linters,
 )
+from familiar.render import NotFoundError
 
 
 class TestLintTemplate:
@@ -225,7 +227,7 @@ class TestLinterPlugins:
         mock_ep.name = "invalid"
         mock_ep.load.return_value = "not a function"
 
-        with patch("familiar.lint.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="not callable"):
                 linters = load_linters("conjurings")
             assert len(linters) == 0
@@ -236,7 +238,7 @@ class TestLinterPlugins:
         mock_ep.name = "broken"
         mock_ep.load.side_effect = ImportError("module not found")
 
-        with patch("familiar.lint.entry_points", return_value=[mock_ep]):
+        with patch("familiar._plugins.entry_points", return_value=[mock_ep]):
             with pytest.warns(UserWarning, match="failed to load"):
                 linters = load_linters("conjurings")
             assert len(linters) == 0
@@ -258,7 +260,7 @@ class TestLinterPlugins:
         templates.mkdir(parents=True)
         (templates / "mytemplate.md").write_text("# test")
 
-        with patch("familiar.lint.entry_points") as mock_entry_points:
+        with patch("familiar._plugins.entry_points") as mock_entry_points:
             # Return our mock for templates, empty for invocations
             def ep_side_effect(group):
                 if group == "familiar.linters.conjurings":
@@ -287,7 +289,7 @@ class TestLinterPlugins:
         templates.mkdir(parents=True)
         (templates / "test.md").write_text("# test")
 
-        with patch("familiar.lint.entry_points") as mock_entry_points:
+        with patch("familiar._plugins.entry_points") as mock_entry_points:
 
             def ep_side_effect(group):
                 if group == "familiar.linters.conjurings":
@@ -301,6 +303,48 @@ class TestLinterPlugins:
         assert len(error_messages) >= 1
 
 
+class TestLintCollectionErrorHandling:
+    """tests for error handling in lint_collection."""
+
+    def test_load_error_produces_lint_error(self, tmp_path):
+        """A NotFoundError from load_text should produce a lint error, not crash."""
+        templates = tmp_path / ".familiar" / "conjurings"
+        templates.mkdir(parents=True)
+        (templates / "broken.md").write_text("# heading")
+
+        from familiar import lint as _lint_mod
+
+        original = _lint_mod.load_text
+
+        def patched(repo_root, kind, name):
+            if name == "broken":
+                raise NotFoundError("simulated read failure")
+            return original(repo_root, kind, name)
+
+        with patch.object(_lint_mod, "load_text", side_effect=patched):
+            messages = lint_collection(tmp_path, "conjurings", lint_template, [])
+
+        load_errors = [
+            m
+            for m in messages
+            if "broken.md" in m.file and "failed to load" in m.message
+        ]
+        assert len(load_errors) == 1
+        assert load_errors[0].level == "error"
+
+    def test_unexpected_linter_error_propagates(self, tmp_path):
+        """Errors not wrapped in NotFoundError should propagate, not be swallowed."""
+        templates = tmp_path / ".familiar" / "conjurings"
+        templates.mkdir(parents=True)
+        (templates / "test.md").write_text("# test")
+
+        def exploding_linter(content: str, name: str) -> list[LintMessage]:
+            raise RuntimeError("unexpected")
+
+        with pytest.raises(RuntimeError, match="unexpected"):
+            lint_collection(tmp_path, "conjurings", exploding_linter, [])
+
+
 class TestLintSnippetReferences:
     """tests for snippet reference validation."""
 

{familiar_cli-0.4.0 → familiar_cli-0.5.1}/tests/test_render.py

@@ -100,6 +100,25 @@ class TestLoadText:
         with pytest.raises(NotFoundError, match="unknown invocation"):
             load_text(tmp_path, "invocations", "nonexistent")
 
+    def test_permission_denied_raises(self, tmp_path):
+        override_dir = tmp_path / ".familiar" / "conjurings"
+        override_dir.mkdir(parents=True)
+        f = override_dir / "locked.md"
+        f.write_text("content")
+        f.chmod(0o000)
+        try:
+            with pytest.raises(NotFoundError, match="permission denied"):
+                load_text(tmp_path, "conjurings", "locked")
+        finally:
+            f.chmod(0o644)
+
+    def test_invalid_utf8_raises(self, tmp_path):
+        override_dir = tmp_path / ".familiar" / "conjurings"
+        override_dir.mkdir(parents=True)
+        (override_dir / "binary.md").write_bytes(b"\xff\xfe invalid utf-8")
+        with pytest.raises(NotFoundError, match="not valid UTF-8"):
+            load_text(tmp_path, "conjurings", "binary")
+
 
 class TestComposeSystem:
     """tests for composing system prompts."""
@@ -121,6 +140,34 @@ class TestComposeSystem:
         # verify order: core, then conjurings in order
         assert system == "CORE\n\nFIRST\n\nSECOND"
 
+    def test_compose_core_only(self, tmp_path):
+        templates = tmp_path / ".familiar" / "conjurings"
+        templates.mkdir(parents=True)
+        (templates / "core.md").write_text("CORE")
+
+        system = compose_system(tmp_path, [])
+        assert system == "CORE"
+
+    def test_compose_multiple_conjurings(self, tmp_path):
+        templates = tmp_path / ".familiar" / "conjurings"
+        templates.mkdir(parents=True)
+        (templates / "core.md").write_text("CORE")
+        (templates / "a.md").write_text("A")
+        (templates / "b.md").write_text("B")
+        (templates / "c.md").write_text("C")
+
+        system = compose_system(tmp_path, ["a", "b", "c"])
+        assert system == "CORE\n\nA\n\nB\n\nC"
+
+    def test_compose_strips_whitespace(self, tmp_path):
+        templates = tmp_path / ".familiar" / "conjurings"
+        templates.mkdir(parents=True)
+        (templates / "core.md").write_text("  CORE  \n")
+        (templates / "pad.md").write_text("\n  PAD  \n\n")
+
+        system = compose_system(tmp_path, ["pad"])
+        assert system == "CORE\n\nPAD"
+
     def test_compose_missing_profile_raises(self, tmp_path):
         with pytest.raises(NotFoundError, match="unknown conjuring"):
             compose_system(tmp_path, ["nonexistent"])
@@ -137,6 +184,36 @@ class TestRenderInvocation:
         result = render_invocation(tmp_path, "greet", ["world"], {"style": "friendly"})
         assert result == "hello world, friendly"
 
+    def test_render_with_snippet_and_args(self, tmp_path):
+        snippets = tmp_path / ".familiar" / "snippets" / "test"
+        snippets.mkdir(parents=True)
+        (snippets / "header.txt").write_text("== $1 ==")
+
+        invocations = tmp_path / ".familiar" / "invocations"
+        invocations.mkdir(parents=True)
+        (invocations / "demo.md").write_text(
+            "{{> snippet:test/header.txt}}\nbody: {{mode}}"
+        )
+
+        result = render_invocation(tmp_path, "demo", ["title"], {"mode": "fast"})
+        assert result == "== title ==\nbody: fast"
+
+    def test_render_no_args(self, tmp_path):
+        invocations = tmp_path / ".familiar" / "invocations"
+        invocations.mkdir(parents=True)
+        (invocations / "plain.md").write_text("no placeholders here")
+
+        result = render_invocation(tmp_path, "plain", [], {})
+        assert result == "no placeholders here"
+
+    def test_render_arguments_placeholder(self, tmp_path):
+        invocations = tmp_path / ".familiar" / "invocations"
+        invocations.mkdir(parents=True)
+        (invocations / "all.md").write_text("run $ARGUMENTS")
+
+        result = render_invocation(tmp_path, "all", ["a", "b", "c"], {})
+        assert result == "run a b c"
+
     def test_render_missing_invocation_raises(self, tmp_path):
         with pytest.raises(NotFoundError, match="unknown invocation"):
             render_invocation(tmp_path, "nonexistent", [], {})
@@ -204,6 +281,32 @@ class TestListItems:
         items = list_items(tmp_path, "conjurings")
         assert len(items) > 0
 
+    def test_list_skips_invalid_utf8_local(self, tmp_path):
+        templates = tmp_path / ".familiar" / "conjurings"
+        templates.mkdir(parents=True)
+        (templates / "good.md").write_text("# good file")
+        (templates / "bad.md").write_bytes(b"\xff\xfe not utf-8")
+
+        items = list_items(tmp_path, "conjurings")
+        names = [name for name, _, _ in items]
+        assert "good" in names
+        assert "bad" not in names
+
+    def test_list_skips_permission_denied_local(self, tmp_path):
+        templates = tmp_path / ".familiar" / "conjurings"
+        templates.mkdir(parents=True)
+        (templates / "good.md").write_text("# good file")
+        locked = templates / "locked.md"
+        locked.write_text("content")
+        locked.chmod(0o000)
+        try:
+            items = list_items(tmp_path, "conjurings")
+            names = [name for name, _, _ in items]
+            assert "good" in names
+            assert "locked" not in names
+        finally:
+            locked.chmod(0o644)
+
 
 class TestLoadSnippet:
     """tests for loading snippets."""
@@ -231,6 +334,25 @@ class TestLoadSnippet:
         with pytest.raises(NotFoundError, match="unknown snippet"):
             load_snippet(tmp_path, "nonexistent/file.txt")
 
+    def test_permission_denied_raises(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        f = snippet_dir / "locked.txt"
+        f.write_text("content")
+        f.chmod(0o000)
+        try:
+            with pytest.raises(NotFoundError, match="permission denied"):
+                load_snippet(tmp_path, "test/locked.txt")
+        finally:
+            f.chmod(0o644)
+
+    def test_invalid_utf8_raises(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "binary.txt").write_bytes(b"\xff\xfe invalid utf-8")
+        with pytest.raises(NotFoundError, match="not valid UTF-8"):
+            load_snippet(tmp_path, "test/binary.txt")
+
 
 class TestResolveIncludes:
     """tests for snippet include resolution."""
@@ -259,6 +381,15 @@ class TestResolveIncludes:
         with pytest.raises(NotFoundError, match="unknown snippet"):
             resolve_includes(tmp_path, text)
 
+    def test_nonexistent_among_valid_raises(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "good.txt").write_text("ok")
+
+        text = "{{> snippet:test/good.txt}} {{> snippet:test/missing.txt}}"
+        with pytest.raises(NotFoundError, match="unknown snippet"):
+            resolve_includes(tmp_path, text)
+
     def test_include_before_substitute(self, tmp_path):
         """Include resolution happens before placeholder substitution."""
         snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
@@ -325,3 +456,36 @@ class TestListSnippets:
         _, first_line, is_local = custom_items[0]
         assert is_local is True
         assert first_line == "first line here"
+
+    def test_local_override_preserves_other_builtins(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "python"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "pyproject.toml").write_text("custom")
+
+        items = list_snippets(tmp_path)
+        lookup = {p: (f, loc) for p, f, loc in items}
+        assert lookup["python/pyproject.toml"][1] is True
+        assert "rust/Cargo.toml" in lookup
+        assert lookup["rust/Cargo.toml"][1] is False
+
+    def test_local_underscore_files_excluded(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "_hidden.txt").write_text("should not appear")
+        (snippet_dir / "visible.txt").write_text("should appear")
+
+        items = list_snippets(tmp_path)
+        paths = [p for p, _, _ in items]
+        assert "test/visible.txt" in paths
+        assert "test/_hidden.txt" not in paths
+
+    def test_list_snippets_skips_invalid_utf8(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "good.txt").write_text("good content")
+        (snippet_dir / "bad.txt").write_bytes(b"\xff\xfe not utf-8")
+
+        items = list_snippets(tmp_path)
+        local_paths = [p for p, _, is_local in items if is_local]
+        assert "test/good.txt" in local_paths
+        assert "test/bad.txt" not in local_paths