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

{familiar_cli-0.5.0/src/familiar_cli.egg-info → familiar_cli-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: familiar-cli
-Version: 0.5.0
+Version: 0.5.2
 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.2}/pyproject.toml

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

{familiar_cli-0.5.0 → familiar_cli-0.5.2}/src/familiar/_plugins.py

@@ -1,4 +1,4 @@
-"""Shared plugin loading utilities."""
+"""shared plugin loading utilities."""
 
 from __future__ import annotations
 
@@ -14,16 +14,16 @@ def load_plugins(
     label: str,
     invalid_msg: str = "validation failed",
 ) -> list[Any]:
-    """Load plugins from entry points with validation.
+    """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.
+        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.
+        list of loaded and validated plugin objects.
     """
     results: list[Any] = []
     for ep in entry_points(group=group):

{familiar_cli-0.5.0 → familiar_cli-0.5.2}/src/familiar/agents.py

@@ -1,4 +1,4 @@
-"""Agent implementations for familiar."""
+"""agent implementations for familiar."""
 
 from __future__ import annotations
 
@@ -11,7 +11,7 @@ from ._plugins import load_plugins
 
 
 class Agent(ABC):
-    """Base class for AI coding agents."""
+    """base class for AI coding agents."""
 
     name: str
     output_file: str
@@ -24,24 +24,24 @@ class Agent(ABC):
     def run(
         self, repo_root: Path, prompt: str, headless: bool, auto: bool = False
     ) -> int:
-        """Run the agent with the given prompt."""
+        """run the agent with the given prompt."""
 
     def supports_skills(self) -> bool:
-        """Whether this agent supports reusable skill files."""
+        """whether this agent supports reusable skill files."""
         return self.skill_dir is not None
 
     def skill_path(self, repo_root: Path, skill_name: str) -> Path:
-        """Build the skill path for a given skill name."""
+        """build the skill path for a given skill name."""
         if self.skill_dir is None:
             raise ValueError(f"agent does not support skills: {self.name}")
         return repo_root / self.skill_dir / skill_name / self.skill_file
 
     def supports_subagents(self) -> bool:
-        """Whether this agent supports reusable subagent files."""
+        """whether this agent supports reusable subagent files."""
         return self.subagent_dir is not None
 
     def subagent_path(self, repo_root: Path, subagent_name: str) -> Path:
-        """Build the subagent path for a given subagent name."""
+        """build the subagent path for a given subagent name."""
         if self.subagent_dir is None:
             raise ValueError(f"agent does not support subagents: {self.name}")
         return repo_root / self.subagent_dir / subagent_name / self.subagent_file
@@ -91,11 +91,11 @@ class ClaudeAgent(Agent):
 
 
 def load_agents() -> dict[str, Agent]:
-    """Load all registered agent plugins via entry points.
+    """load all registered agent plugins via entry points.
 
     Returns:
-        Dictionary mapping agent names to Agent instances.
-        Plugins that fail to load are skipped with a warning.
+        dictionary mapping agent names to Agent instances.
+        plugins that fail to load are skipped with a warning.
     """
     plugins = load_plugins(
         "familiar.agents",
@@ -120,9 +120,9 @@ _agents_cache: dict[str, Agent] | None = None
 
 
 def get_agents() -> dict[str, Agent]:
-    """Get all available agents.
+    """get all available agents.
 
-    Returns a cached dictionary of agent name -> Agent instance.
+    returns a cached dictionary of agent name -> Agent instance.
     """
     global _agents_cache
     if _agents_cache is None:
@@ -131,7 +131,7 @@ def get_agents() -> dict[str, Agent]:
 
 
 def get_agent(name: str) -> Agent:
-    """Get an agent by name.
+    """get an agent by name.
 
     Raises:
         KeyError: if the agent name is not recognized.

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

@@ -1,4 +1,4 @@
-"""Command-line interface for familiar."""
+"""command-line interface for familiar."""
 
 from __future__ import annotations
 
@@ -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,
@@ -24,7 +24,6 @@ from .render import (
     render_invocation,
 )
 
-# exit codes
 EXIT_SUCCESS = 0
 EXIT_ERROR = 1  # general error (agent failed, etc.)
 EXIT_USAGE = 2  # usage error (bad args, missing files, etc.)
@@ -43,14 +42,35 @@ class CliError(Exception):
 
 
 def _agent_hint() -> str:
-    """Return a hint string listing valid agent names."""
+    """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.
+    """find the repository root by looking for .git directory.
 
-    Walks up from start directory. Falls back to start directory itself
+    walks up from start directory. falls back to start directory itself
     if no .git is found, allowing use outside of git repositories.
     """
     cur = start.resolve()
@@ -61,9 +81,9 @@ def find_repo_root(start: Path) -> Path:
 
 
 def _remove_worktree(repo_root: Path, worktree_path: Path) -> None:
-    """Best-effort removal of a git worktree."""
+    """best-effort removal of a git worktree."""
     try:
-        subprocess.run(
+        result = subprocess.run(
             [
                 "git",
                 "-C",
@@ -75,13 +95,18 @@ 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
 
 
 def create_worktree(repo_root: Path) -> Path:
-    """Create a temporary git worktree for the repository."""
-    # Ensure it's a git repo
+    """create a temporary git worktree for the repository."""
     try:
         subprocess.run(
             ["git", "-C", str(repo_root), "rev-parse", "--is-inside-work-tree"],
@@ -95,7 +120,7 @@ def create_worktree(repo_root: Path) -> Path:
 
     tmpdir = tempfile.mkdtemp(prefix="familiar-")
     # git worktree add requires the directory to NOT exist.
-    # mkdtemp creates it. Let's remove it and let git create it.
+    # mkdtemp creates it. let's remove it and let git create it.
     os.rmdir(tmpdir)
 
     try:
@@ -120,33 +145,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=_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(
     repo_root: Path, agent_name: str, invocation: str, skill_name: str, prompt: str
 ) -> Path:
-    """Write a reusable skill file for supported agents."""
+    """write a reusable skill file for supported agents."""
     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=_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 +175,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
 
 
@@ -167,23 +186,19 @@ def write_subagent(
     subagent_name: str,
     system: str,
 ) -> Path:
-    """Write a reusable subagent file for supported agents."""
+    """write a reusable subagent file for supported agents."""
     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=_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 +209,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 +229,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:
@@ -277,7 +289,7 @@ def cmd_invoke(args: argparse.Namespace) -> int:
         target_dir = create_worktree(repo_root)
         print(f"created worktree at {target_dir}")
 
-        # Best-effort copy of instruction file into the worktree
+        # best-effort copy of instruction file into the worktree
         try:
             agent = get_agent(args.agent)
             instr_file = repo_root / agent.output_file
@@ -318,7 +330,6 @@ def cmd_list(args: argparse.Namespace) -> int:
     repo_root = find_repo_root(Path(args.into or os.getcwd()))
 
     if args.kind is None:
-        # list all
         conjurings = list_items(repo_root, "conjurings")
         invocations = list_items(repo_root, "invocations")
         snippets = list_snippets(repo_root)
@@ -349,7 +360,6 @@ def cmd_lint(args: argparse.Namespace) -> int:
 
     messages = lint_all(repo_root)
 
-    # Filter by level if requested
     if args.errors_only:
         messages = [m for m in messages if m.level == "error"]
 
@@ -357,7 +367,6 @@ def cmd_lint(args: argparse.Namespace) -> int:
         print("all checks passed")
         return EXIT_SUCCESS
 
-    # Group by level for output
     errors = [m for m in messages if m.level == "error"]
     warnings = [m for m in messages if m.level == "warning"]
 

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

@@ -1,4 +1,4 @@
-"""Linting for familiar conjurings and invocations."""
+"""linting for familiar conjurings and invocations."""
 
 from __future__ import annotations
 
@@ -14,7 +14,7 @@ from .render import _SNIPPET_INCLUDE, NotFoundError, list_items, load_snippet, l
 
 @dataclass
 class LintMessage:
-    """A lint message."""
+    """a lint message."""
 
     level: Literal["error", "warning"]
     file: str
@@ -28,17 +28,15 @@ class LintMessage:
         return f"{self.level}: {loc}: {self.message}"
 
 
-# Regex patterns for placeholders
 _POSITIONAL_PLACEHOLDER = re.compile(r"\$(\d+|ARGUMENTS)")
 _NAMED_PLACEHOLDER = re.compile(r"\{\{(\w+)\}\}")
 
-# Section patterns for invocations
-# Accept various task verbs as first line
+# accept various task verbs as first line
 _TASK_LINE = re.compile(
     r"^(task|explain|review|analyze|check|audit|describe|create|generate|refactor|bootstrap|implement|add|fix)(\s|:)",
     re.IGNORECASE,
 )
-# Accept inputs, input, arguments as input sections (with or without ## heading)
+# accept inputs, input, arguments as input sections (with or without ## heading)
 _INPUTS_SECTION = re.compile(
     r"^(##\s+)?(inputs?|arguments?)(\s*\([^)]+\))?:?\s*$", re.IGNORECASE | re.MULTILINE
 )
@@ -48,10 +46,10 @@ _OUTPUT_SECTION = re.compile(
 
 
 def lint_template(content: str, name: str) -> list[LintMessage]:
-    """Lint a template (conjuring) file.
+    """lint a template (conjuring) file.
 
-    Templates should:
-    - Start with a markdown heading
+    templates should:
+    - start with a markdown heading
     """
     messages: list[LintMessage] = []
     lines = content.split("\n")
@@ -82,13 +80,13 @@ def lint_template(content: str, name: str) -> list[LintMessage]:
 
 
 def lint_invocation(content: str, name: str) -> list[LintMessage]:
-    """Lint an invocation file.
+    """lint an invocation file.
 
-    Invocations should:
-    - Start with a task: line (or similar verb)
-    - Have an inputs section (warning if missing)
-    - Have an output section (warning if missing)
-    - Document all placeholders used
+    invocations should:
+    - start with a task: line (or similar verb)
+    - have an inputs section (warning if missing)
+    - have an output section (warning if missing)
+    - document all placeholders used
     """
     messages: list[LintMessage] = []
     lines = content.split("\n")
@@ -104,7 +102,6 @@ def lint_invocation(content: str, name: str) -> list[LintMessage]:
         )
         return messages
 
-    # Check first line is a task line
     first_line = lines[0].strip()
     if not _TASK_LINE.match(first_line):
         messages.append(
@@ -116,7 +113,6 @@ def lint_invocation(content: str, name: str) -> list[LintMessage]:
             )
         )
 
-    # Check for inputs section
     if not _INPUTS_SECTION.search(content):
         messages.append(
             LintMessage(
@@ -127,7 +123,6 @@ def lint_invocation(content: str, name: str) -> list[LintMessage]:
             )
         )
 
-    # Check for output section
     if not _OUTPUT_SECTION.search(content):
         messages.append(
             LintMessage(
@@ -138,16 +133,14 @@ def lint_invocation(content: str, name: str) -> list[LintMessage]:
             )
         )
 
-    # Find all placeholders and check if they're documented
     positional = set(_POSITIONAL_PLACEHOLDER.findall(content))
     named = set(_NAMED_PLACEHOLDER.findall(content))
 
-    # Check if placeholders are mentioned in content (loose check)
-    # Prefer checking the inputs section if it exists
+    # loose check: prefer the inputs section if it exists, else the whole file
     inputs_match = _INPUTS_SECTION.search(content)
     if inputs_match:
         start = inputs_match.end()
-        # Look ahead for the next markdown heading or end of file
+        # look ahead for the next markdown heading or end of file
         next_heading = re.search(r"^#", content[start:], re.MULTILINE)
         search_area = (
             content[start : start + next_heading.start()]
@@ -158,10 +151,14 @@ def lint_invocation(content: str, name: str) -> list[LintMessage]:
         search_area = content.lower()
 
     for placeholder in named:
-        # Check if placeholder name appears in search area
-        if placeholder.lower() not in search_area.replace(
-            f"{{{{{placeholder.lower()}}}}}", ""
-        ):
+        tag = f"{{{{{placeholder.lower()}}}}}"
+        stripped = search_area.replace(tag, "")
+        # accept the placeholder as documented if its bare name appears as a
+        # standalone word (after stripping {{…}} syntax) OR if the {{…}} tag
+        # itself appears in the inputs section (the common "- {{name}}: …"
+        # documentation pattern).
+        bare_match = re.search(r"\b" + re.escape(placeholder.lower()) + r"\b", stripped)
+        if not bare_match and tag not in search_area:
             messages.append(
                 LintMessage(
                     level="warning",
@@ -171,7 +168,6 @@ def lint_invocation(content: str, name: str) -> list[LintMessage]:
                 )
             )
 
-    # Check for undocumented positional args
     for p in positional:
         if p == "ARGUMENTS":
             continue
@@ -189,18 +185,17 @@ def lint_invocation(content: str, name: str) -> list[LintMessage]:
     return messages
 
 
-# Type alias for linter functions
 LinterFunc = Callable[[str, str], list[LintMessage]]
 
 
 def load_linters(kind: Literal["conjurings", "invocations"]) -> list[LinterFunc]:
-    """Load linter plugins for the given kind.
+    """load linter plugins for the given kind.
 
     Args:
-        kind: Either "conjurings" or "invocations".
+        kind: either "conjurings" or "invocations".
 
     Returns:
-        List of linter functions from plugins.
+        list of linter functions from plugins.
     """
     return load_plugins(
         f"familiar.linters.{kind}",
@@ -213,7 +208,7 @@ def load_linters(kind: Literal["conjurings", "invocations"]) -> list[LinterFunc]
 def lint_snippet_references(
     repo_root: Path, content: str, name: str
 ) -> list[LintMessage]:
-    """Check that all snippet includes reference existing snippets."""
+    """check that all snippet includes reference existing snippets."""
     messages: list[LintMessage] = []
     for i, line in enumerate(content.split("\n"), 1):
         for m in _SNIPPET_INCLUDE.finditer(line):
@@ -238,7 +233,7 @@ def lint_collection(
     builtin_linter: LinterFunc,
     plugin_linters: list[LinterFunc],
 ) -> list[LintMessage]:
-    """Lint a collection of items (conjurings or invocations)."""
+    """lint a collection of items (conjurings or invocations)."""
     messages: list[LintMessage] = []
     for name, _, is_local in list_items(repo_root, kind):
         try:
@@ -248,11 +243,8 @@ def lint_collection(
                 if is_local
                 else f"(builtin) {kind}/{name}.md"
             )
-            # Built-in linter
             messages.extend(builtin_linter(content, prefix))
-            # Snippet reference validation
             messages.extend(lint_snippet_references(repo_root, content, prefix))
-            # Plugin linters
             for linter in plugin_linters:
                 try:
                     messages.extend(linter(content, prefix))
@@ -265,7 +257,7 @@ def lint_collection(
                             message=f"plugin linter failed: {e}",
                         )
                     )
-        except Exception as e:
+        except NotFoundError as e:
             messages.append(
                 LintMessage(
                     level="error",
@@ -278,24 +270,20 @@ def lint_collection(
 
 
 def lint_all(repo_root: Path) -> list[LintMessage]:
-    """Lint all conjurings and invocations.
+    """lint all conjurings and invocations.
 
-    Runs built-in linters and any plugin linters registered via entry points.
+    runs built-in linters and any plugin linters registered via entry points.
 
-    Returns a list of lint messages (errors and warnings).
+    returns a list of lint messages (errors and warnings).
     """
     messages: list[LintMessage] = []
 
-    # Load plugin linters
     conjuring_linters = load_linters("conjurings")
     invocation_linters = load_linters("invocations")
 
-    # Lint conjurings
     messages.extend(
         lint_collection(repo_root, "conjurings", lint_template, conjuring_linters)
     )
-
-    # Lint invocations
     messages.extend(
         lint_collection(repo_root, "invocations", lint_invocation, invocation_linters)
     )