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

{familiar_cli-0.5.1 → familiar_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: familiar-cli
-Version: 0.5.1
+Version: 0.6.0
 Summary: compose and invoke ai agent prompts from reusable templates
 Author-email: cyberwitchery lab <contact@cyberwitchery.com>
 License-Expression: MIT
@@ -20,7 +20,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: dev
-Requires-Dist: ruff; extra == "dev"
+Requires-Dist: ruff==0.16.1; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -46,18 +46,21 @@ pip install familiar-cli
 ## usage
 
 ```
-usage: familiar [-h] {conjure,invoke,list} ...
+usage: familiar [-h] [--version] [--debug] {conjure,invoke,list,lint} ...
 
 conjure and invoke familiars
 
 positional arguments:
-  {conjure,invoke,list}
+  {conjure,invoke,list,lint}
     conjure             compose system instructions for an agent
     invoke              render an invocation and run the agent
-    list                list available conjurings or invocations
+    list                list available conjurings and invocations
+    lint                lint conjurings and invocations
 
 options:
   -h, --help            show this help message and exit
+  --version             show program's version number and exit
+  --debug               show full traceback on error
 ```
 
 conjure conjurings to create system instructions for an agent:
@@ -98,6 +101,12 @@ list available conjurings and invocations:
 familiar list
 ```
 
+lint conjurings and invocations, including local `.familiar/` overrides:
+
+```
+familiar lint
+```
+
 ## customization
 
 add your own conjurings and invocations by creating files in `.familiar/` in your repo:

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

@@ -1,6 +1,6 @@
 [project]
 name = "familiar-cli"
-version = "0.5.1"
+version = "0.6.0"
 description = "compose and invoke ai agent prompts from reusable templates"
 readme = "readme.md"
 license = "MIT"
@@ -36,7 +36,7 @@ claude = "familiar.agents:ClaudeAgent"
 package-dir = {"" = "src"}
 
 [project.optional-dependencies]
-dev = ["ruff", "mypy", "pytest", "pytest-cov", "bandit"]
+dev = ["ruff==0.16.1", "mypy", "pytest", "pytest-cov", "bandit"]
 
 [tool.setuptools.package-data]
 "familiar.data.conjurings" = ["*.md"]

{familiar_cli-0.5.1 → familiar_cli-0.6.0}/readme.md

@@ -17,18 +17,21 @@ pip install familiar-cli
 ## usage
 
 ```
-usage: familiar [-h] {conjure,invoke,list} ...
+usage: familiar [-h] [--version] [--debug] {conjure,invoke,list,lint} ...
 
 conjure and invoke familiars
 
 positional arguments:
-  {conjure,invoke,list}
+  {conjure,invoke,list,lint}
     conjure             compose system instructions for an agent
     invoke              render an invocation and run the agent
-    list                list available conjurings or invocations
+    list                list available conjurings and invocations
+    lint                lint conjurings and invocations
 
 options:
   -h, --help            show this help message and exit
+  --version             show program's version number and exit
+  --debug               show full traceback on error
 ```
 
 conjure conjurings to create system instructions for an agent:
@@ -69,6 +72,12 @@ list available conjurings and invocations:
 familiar list
 ```
 
+lint conjurings and invocations, including local `.familiar/` overrides:
+
+```
+familiar lint
+```
+
 ## customization
 
 add your own conjurings and invocations by creating files in `.familiar/` in your repo:

{familiar_cli-0.5.1 → familiar_cli-0.6.0}/src/familiar/__init__.py

@@ -2,6 +2,6 @@
 
 from importlib.metadata import version
 
-__all__ = ["agents", "render", "cli"]
+__all__ = ["agents", "cli", "render"]
 
 __version__ = version("familiar-cli")

{familiar_cli-0.5.1 → familiar_cli-0.6.0}/src/familiar/_plugins.py

@@ -1,10 +1,11 @@
-"""Shared plugin loading utilities."""
+"""shared plugin loading utilities."""
 
 from __future__ import annotations
 
 import warnings
+from collections.abc import Callable
 from importlib.metadata import entry_points
-from typing import Any, Callable
+from typing import Any
 
 
 def load_plugins(
@@ -14,16 +15,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):
@@ -36,7 +37,8 @@ def load_plugins(
                 )
                 continue
             results.append(obj)
-        except Exception as e:
+        # a broken third-party entry point must not take down the cli
+        except Exception as e:  # noqa: BLE001
             warnings.warn(
                 f"failed to load {label} '{ep.name}': {e}",
                 stacklevel=2,

{familiar_cli-0.5.1 → familiar_cli-0.6.0}/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
@@ -61,7 +61,7 @@ class CodexAgent(Agent):
             if auto:
                 cmd.append("--full-auto")
             cmd.extend(["exec", "--skip-git-repo-check", "-C", str(repo_root), "-"])
-            proc = subprocess.run(cmd, input=prompt, text=True)
+            proc = subprocess.run(cmd, input=prompt, text=True, check=False)
             return proc.returncode
         else:
             cmd = ["codex"]
@@ -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",
@@ -108,7 +108,8 @@ def load_agents() -> dict[str, Agent]:
         try:
             instance = cls()
             agents[instance.name] = instance
-        except Exception as e:
+        # a broken agent plugin must not take down the cli
+        except Exception as e:  # noqa: BLE001
             warnings.warn(
                 f"failed to load agent plugin '{cls.__name__}': {e}",
                 stacklevel=2,
@@ -120,9 +121,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 +132,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.1 → familiar_cli-0.6.0}/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 Agent, get_agents, get_agent
+from .agents import Agent, get_agent, get_agents
 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,12 +42,12 @@ 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."""
+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:
@@ -56,7 +55,7 @@ def _resolve_agent(name: str) -> "Agent":
 
 
 def _write_file(path: Path, content: str, label: str = "") -> None:
-    """Write content to path, creating parent dirs. Wraps OSError as CliError."""
+    """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)
@@ -69,9 +68,9 @@ def _write_file(path: Path, content: str, label: str = "") -> None:
 
 
 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()
@@ -82,7 +81,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."""
+    """best-effort removal of a git worktree."""
     try:
         result = subprocess.run(
             [
@@ -95,6 +94,7 @@ def _remove_worktree(repo_root: Path, worktree_path: Path) -> None:
                 str(worktree_path),
             ],
             capture_output=True,
+            check=False,
         )
         if result.returncode != 0:
             stderr = result.stderr.decode(errors="replace").strip()
@@ -107,8 +107,7 @@ def _remove_worktree(repo_root: Path, worktree_path: Path) -> None:
 
 
 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"],
@@ -121,8 +120,8 @@ 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.
+    # git worktree add requires the target to not exist, so remove the
+    # mkdtemp-created directory and let git create it
     os.rmdir(tmpdir)
 
     try:
@@ -155,7 +154,7 @@ def write_instruction(repo_root: Path, agent_name: str, system: str) -> None:
 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}",
@@ -188,7 +187,7 @@ 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}",
@@ -291,7 +290,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
@@ -332,7 +331,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)
@@ -363,7 +361,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"]
 
@@ -371,7 +368,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"]
 
@@ -514,7 +510,8 @@ def main() -> None:
         if e.hint:
             print(f"hint: {e.hint}", file=sys.stderr)
         raise SystemExit(e.exit_code)
-    except Exception as e:
+    # top-level handler: any unexpected error becomes an exit code, not a traceback
+    except Exception as e:  # noqa: BLE001
         if args.debug:
             traceback.print_exc()
         print(f"error: {e}", file=sys.stderr)