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

{familiar_cli-0.5.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.5.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.5.0 → familiar_cli-0.5.1}/pyproject.toml

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

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

@@ -14,7 +14,7 @@ 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,
@@ -47,6 +47,27 @@ def _agent_hint() -> str:
     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.
 
@@ -63,7 +84,7 @@ def find_repo_root(start: Path) -> Path:
 def _remove_worktree(repo_root: Path, worktree_path: Path) -> None:
     """Best-effort removal of a git worktree."""
     try:
-        subprocess.run(
+        result = subprocess.run(
             [
                 "git",
                 "-C",
@@ -75,6 +96,12 @@ def _remove_worktree(repo_root: Path, worktree_path: Path) -> None:
             ],
             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
 
@@ -120,11 +147,9 @@ 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=_agent_hint())
-    (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(
@@ -137,16 +162,12 @@ def write_skill(
             hint="use lowercase letters, numbers, underscore, or hyphen",
         )
 
-    try:
-        agent = get_agent(agent_name)
-    except KeyError as e:
-        raise CliError(str(e), hint=_agent_hint())
+    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"
@@ -156,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
 
 
@@ -174,16 +195,12 @@ def write_subagent(
             hint="use lowercase letters, numbers, underscore, or hyphen",
         )
 
-    try:
-        agent = get_agent(agent_name)
-    except KeyError as e:
-        raise CliError(str(e), hint=_agent_hint())
+    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"
@@ -194,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
 
 
@@ -214,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=_agent_hint())
+    agent = _resolve_agent(agent_name)
     try:
         return agent.run(repo_root, prompt, headless, auto=auto)
     except FileNotFoundError:

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

@@ -265,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.5.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):
@@ -155,7 +168,10 @@ def _list_resources(
                 if item.name.startswith("_"):
                     continue
                 key = item.name[: -len(suffix)] if suffix else item.name
-                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[key] = (first_line, False)
     except (FileNotFoundError, TypeError, ModuleNotFoundError):
@@ -171,7 +187,10 @@ def _list_resources(
             if not f.is_file() or f.name.startswith("_"):
                 continue
             key = str(f.relative_to(local_dir)) if recursive else f.stem
-            content = f.read_text(encoding="utf-8")
+            try:
+                content = f.read_text(encoding="utf-8")
+            except (UnicodeDecodeError, PermissionError):
+                continue
             first_line = content.split("\n", 1)[0].strip()
             items[key] = (first_line, True)
 

{familiar_cli-0.5.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.5.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.5.0 → familiar_cli-0.5.1}/tests/test_cli.py

@@ -8,9 +8,14 @@ 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,
@@ -84,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."""
 
@@ -100,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."""
 

{familiar_cli-0.5.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:
@@ -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.5.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."""
@@ -262,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."""
@@ -289,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."""
@@ -414,3 +478,14 @@ class TestListSnippets:
         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