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

{familiar_cli-0.5.1/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.1
+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.1 → familiar_cli-0.5.2}/pyproject.toml

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

{familiar_cli-0.5.1 → 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.1 → 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.1 → 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
 
@@ -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."""
+    """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(
             [
@@ -107,8 +106,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"],
@@ -122,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:
@@ -155,7 +153,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 +186,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 +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
@@ -332,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)
@@ -363,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"]
 
@@ -371,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.1 → 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))
@@ -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)
     )

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

@@ -1,4 +1,4 @@
-"""Render system and user prompts from conjurings and invocations."""
+"""render system and user prompts from conjurings and invocations."""
 
 from __future__ import annotations
 
@@ -15,14 +15,15 @@ from pathlib import Path
 _VALID_NAME = re.compile(r"^[a-z0-9_-]+$")
 _VALID_SNIPPET_PATH = re.compile(r"^[a-zA-Z0-9_.-]+(/[a-zA-Z0-9_.-]+)+$")
 _SNIPPET_INCLUDE = re.compile(r"{{>\s*snippet:([^}]+?)\s*}}")
+_MAX_INCLUDE_DEPTH = 50
 
 
 class NotFoundError(Exception):
-    """Raised when a conjuring, invocation, or snippet is not found."""
+    """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`."""
+    """read a UTF-8 text file, converting I/O errors to :class:`NotFoundError`."""
     try:
         return path.read_text(encoding="utf-8")
     except PermissionError:
@@ -32,7 +33,7 @@ def _safe_read_text(path: Path, label: str) -> str:
 
 
 def load_text(repo_root: Path, kind: str, name: str) -> str:
-    """Load a conjuring or invocation; local overrides in .familiar override package data."""
+    """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"
@@ -48,7 +49,7 @@ def load_text(repo_root: Path, kind: str, name: str) -> str:
 
 
 def load_snippet(repo_root: Path, path: str) -> str:
-    """Load a snippet by path; local overrides in .familiar/snippets/ win."""
+    """load a snippet by path; local overrides in .familiar/snippets/ win."""
     path = path.strip()
     if ".." in path.split("/"):
         raise NotFoundError(f"invalid snippet path: {path}")
@@ -70,16 +71,33 @@ def load_snippet(repo_root: Path, path: str) -> str:
 
 
 def resolve_includes(repo_root: Path, text: str) -> str:
-    """Resolve {{> snippet:path}} includes by replacing them with snippet content."""
+    """resolve {{> snippet:path}} includes, expanding nested includes recursively.
 
-    def repl(m: re.Match[str]) -> str:
-        return load_snippet(repo_root, m.group(1))
+    a snippet may include other snippets. include cycles (self-includes or
+    a -> b -> a) raise :class:`NotFoundError` naming the chain; a max-depth
+    backstop guards against pathologically deep nesting.
+    """
+
+    def expand(text: str, chain: list[str]) -> str:
+        def repl(m: re.Match[str]) -> str:
+            path = m.group(1).strip()
+            if path in chain:
+                trail = " -> ".join([*chain, path])
+                raise NotFoundError(f"snippet include cycle: {trail}")
+            if len(chain) >= _MAX_INCLUDE_DEPTH:
+                trail = " -> ".join([*chain, path])
+                raise NotFoundError(
+                    f"snippet include depth exceeded ({_MAX_INCLUDE_DEPTH}): {trail}"
+                )
+            return expand(load_snippet(repo_root, path), [*chain, path])
+
+        return _SNIPPET_INCLUDE.sub(repl, text)
 
-    return _SNIPPET_INCLUDE.sub(repl, text)
+    return expand(text, [])
 
 
 def substitute(text: str, args: list[str], kv: dict[str, str]) -> str:
-    """Substitute $1, $2, ... $ARGUMENTS and {{key}} placeholders in a single pass."""
+    """substitute $1, $2, ... $ARGUMENTS and {{key}} placeholders in a single pass."""
     missing: list[str] = []
 
     def repl(m: re.Match[str]) -> str:
@@ -96,13 +114,16 @@ def substitute(text: str, args: list[str], kv: dict[str, str]) -> str:
             return ""
 
         if named_ident:
-            return kv.get(named_ident, m.group(0))
+            if named_ident in kv:
+                return kv[named_ident]
+            missing.append(m.group(0))
+            return m.group(0)
 
         return m.group(0)
 
-    # Combined regex for both types of placeholders:
-    # Group 1: \$(ARGUMENTS|\d+)
-    # Group 2: {{(\w+)}}
+    # combined regex for both types of placeholders:
+    # group 1: \$(ARGUMENTS|\d+)
+    # group 2: {{(\w+)}}
     pattern = re.compile(r"\$(ARGUMENTS|\d+)|{{(\w+)}}")
     text = pattern.sub(repl, text)
 
@@ -112,7 +133,7 @@ def substitute(text: str, args: list[str], kv: dict[str, str]) -> str:
 
 
 def _walk_traversable(root: Traversable, prefix: str = "") -> list[tuple[str, str]]:
-    """Recursively walk a Traversable, returning (relative_path, first_line) pairs."""
+    """recursively walk a Traversable, returning (relative_path, first_line) pairs."""
     items: list[tuple[str, str]] = []
     try:
         for item in sorted(root.iterdir(), key=lambda x: x.name):
@@ -139,23 +160,22 @@ def _list_resources(
     recursive: bool = False,
     suffix: str = "",
 ) -> list[tuple[str, str, bool]]:
-    """List resources from package data and local overrides.
+    """list resources from package data and local overrides.
 
-    Items from local ``.familiar/{local_subdir}/`` override package builtins.
+    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.
+        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.
+        sorted list of ``(key, first_line, is_local)`` tuples.
     """
     items: dict[str, tuple[str, bool]] = {}
 
-    # built-in resources from package data
     try:
         pkg_root = resources.files(pkg)
         if recursive:
@@ -177,7 +197,6 @@ def _list_resources(
     except (FileNotFoundError, TypeError, ModuleNotFoundError):
         pass
 
-    # local overrides
     local_dir = repo_root / ".familiar" / local_subdir
     if local_dir.is_dir():
         files = (
@@ -201,9 +220,9 @@ def _list_resources(
 
 
 def list_snippets(repo_root: Path) -> list[tuple[str, str, bool]]:
-    """List available snippets.
+    """list available snippets.
 
-    Returns list of (path, first_line, is_local) tuples, sorted by path.
+    returns list of (path, first_line, is_local) tuples, sorted by path.
     """
     return _list_resources(
         repo_root, "familiar.data.snippets", "snippets", recursive=True
@@ -211,15 +230,15 @@ def list_snippets(repo_root: Path) -> list[tuple[str, str, bool]]:
 
 
 def list_items(repo_root: Path, kind: str) -> list[tuple[str, str, bool]]:
-    """List available conjurings or invocations.
+    """list available conjurings or invocations.
 
-    Returns list of (name, first_line, is_local) tuples, sorted by name.
+    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:
-    """Compose system instructions from core + selected conjurings."""
+    """compose system instructions from core + selected conjurings."""
     core = load_text(repo_root, "conjurings", "core").strip()
     parts: list[str] = [core]
     for name in conjurings:
@@ -230,7 +249,7 @@ def compose_system(repo_root: Path, conjurings: list[str]) -> str:
 def render_invocation(
     repo_root: Path, invocation: str, args: list[str], kv: dict[str, str]
 ) -> str:
-    """Render an invocation with snippet inclusion and argument substitution."""
+    """render an invocation with snippet inclusion and argument substitution."""
     inv = load_text(repo_root, "invocations", invocation).strip()
     inv = resolve_includes(repo_root, inv)
     return substitute(inv, args, kv)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: familiar-cli
-Version: 0.5.1
+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.1 → familiar_cli-0.5.2}/tests/test_cli.py

@@ -321,7 +321,6 @@ class TestCmdInvoke:
             )
             result = cmd_invoke(args)
             assert result == 0
-            # check that the prompt is the rendered invocation
             call_args = mock_run.call_args
             prompt = call_args[0][2]
             assert "explain" in prompt.lower()
@@ -344,7 +343,6 @@ class TestCmdInvoke:
             cmd_invoke(args)
 
     def test_kv_args_passed(self, tmp_path):
-        # create custom invocation that uses kv
         inv_dir = tmp_path / ".familiar" / "invocations"
         inv_dir.mkdir(parents=True)
         (inv_dir / "custom.md").write_text("value is {{mykey}}")
@@ -410,7 +408,6 @@ class TestCmdInvoke:
         ) as mock_wt:
             with patch("familiar.cli.run_agent", return_value=0) as mock_run:
                 with patch("shutil.copy2") as mock_copy:
-                    # Create instruction file to be copied
                     (tmp_path / "CLAUDE.md").write_text("instr")
 
                     args = argparse.Namespace(
@@ -429,9 +426,7 @@ class TestCmdInvoke:
                     result = cmd_invoke(args)
                     assert result == 0
                     mock_wt.assert_called_once()
-                    # Check that run_agent was called with the worktree path
                     assert mock_run.call_args[0][0] == tmp_path / "wt"
-                    # Check that instruction file was copied
                     mock_copy.assert_called_once()
 
     def test_invoke_worktree_cleaned_up_on_error(self, tmp_path):
@@ -571,7 +566,6 @@ class TestCmdList:
         )
         cmd_list(args)
         captured = capsys.readouterr()
-        # verbose mode includes first line after colon
         assert ":" in captured.out
 
     def test_list_local_marked(self, tmp_path, capsys):

{familiar_cli-0.5.1 → familiar_cli-0.5.2}/tests/test_integration.py

@@ -223,7 +223,6 @@ class TestListIntegration:
             text=True,
         )
         assert result.returncode == 0
-        # verbose includes description after colon
         assert ":" in result.stdout
 
     def test_list_with_local_override(self, tmp_path):
@@ -267,7 +266,6 @@ class TestSnippetIntegration:
         from familiar.render import render_invocation
 
         result = render_invocation(tmp_path, "bootstrap-python", ["myapp", "cli"], {})
-        # The snippet content should be inlined
         assert "[project]" in result
         assert "pyproject.toml" not in result or "snippet:" not in result
 
@@ -276,7 +274,6 @@ class TestSnippetIntegration:
         from familiar.render import render_invocation
 
         result = render_invocation(tmp_path, "add-ci", ["github", "python"], {})
-        # Should contain inlined workflow, not the snippet directive
         assert "{{> snippet:" not in result
         assert "actions/checkout" in result
 

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

@@ -177,12 +177,38 @@ output
         placeholder_warnings = [m for m in messages if "{{myarg}}" in m.message]
         assert placeholder_warnings == []
 
+    def test_placeholder_substring_in_other_word_warns(self):
+        content = """task: process {{name}}
+
+inputs
+- filename (required): the file to process
+
+output
+- results
+"""
+        messages = lint_invocation(content, "test.md")
+        placeholder_warnings = [m for m in messages if "{{name}}" in m.message]
+        assert len(placeholder_warnings) == 1
+        assert placeholder_warnings[0].level == "warning"
+
+    def test_placeholder_tag_in_inputs_section_no_warning(self):
+        content = """task: implement {{spec}}
+
+inputs
+- {{spec}} (required): feature specification
+
+output
+- results
+"""
+        messages = lint_invocation(content, "test.md")
+        placeholder_warnings = [m for m in messages if "{{spec}}" in m.message]
+        assert placeholder_warnings == []
+
 
 class TestLintAll:
     """tests for linting all conjurings and invocations."""
 
     def test_lint_all_builtins(self, tmp_path):
-        # should lint all built-ins without errors
         messages = lint_all(tmp_path)
         errors = [m for m in messages if m.level == "error"]
         assert errors == [], f"Unexpected errors: {errors}"
@@ -255,13 +281,12 @@ class TestLinterPlugins:
         mock_ep.name = "test"
         mock_ep.load.return_value = mock_linter
 
-        # Create a local template to lint
         templates = tmp_path / ".familiar" / "conjurings"
         templates.mkdir(parents=True)
         (templates / "mytemplate.md").write_text("# test")
 
         with patch("familiar._plugins.entry_points") as mock_entry_points:
-            # Return our mock for templates, empty for invocations
+            # return the mock for conjurings, empty for invocations
             def ep_side_effect(group):
                 if group == "familiar.linters.conjurings":
                     return [mock_ep]
@@ -270,7 +295,6 @@ class TestLinterPlugins:
             mock_entry_points.side_effect = ep_side_effect
             lint_all(tmp_path)
 
-        # Should have been called for the local template
         local_calls = [c for c in calls if "mytemplate" in c[1]]
         assert len(local_calls) == 1
 
@@ -284,7 +308,6 @@ class TestLinterPlugins:
         mock_ep.name = "bad"
         mock_ep.load.return_value = bad_linter
 
-        # Create a local template
         templates = tmp_path / ".familiar" / "conjurings"
         templates.mkdir(parents=True)
         (templates / "test.md").write_text("# test")

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

@@ -5,6 +5,7 @@ from __future__ import annotations
 import pytest
 
 from familiar.render import (
+    _MAX_INCLUDE_DEPTH,
     NotFoundError,
     compose_system,
     list_items,
@@ -62,6 +63,27 @@ class TestSubstitute:
         result = substitute(text, ["first", "second"], {})
         assert result == "second before first"
 
+    def test_missing_named_warns(self, capsys):
+        text = "spec: {{spec}}"
+        result = substitute(text, [], {})
+        assert result == "spec: {{spec}}"
+        captured = capsys.readouterr()
+        assert "warning: missing arguments: {{spec}}" in captured.err
+
+    def test_present_named_no_warning(self, capsys):
+        text = "spec: {{spec}}"
+        result = substitute(text, [], {"spec": "caching"})
+        assert result == "spec: caching"
+        captured = capsys.readouterr()
+        assert captured.err == ""
+
+    def test_missing_mixed_reports_both(self, capsys):
+        text = "$1 and {{spec}} and $2"
+        result = substitute(text, ["only_one"], {})
+        assert result == "only_one and {{spec}} and "
+        captured = capsys.readouterr()
+        assert "warning: missing arguments: {{spec}}, $2" in captured.err
+
 
 class TestLoadText:
     """tests for loading conjurings and invocations."""
@@ -129,7 +151,6 @@ class TestComposeSystem:
         assert "python" in system.lower()
 
     def test_compose_order(self, tmp_path):
-        # create local overrides to control content
         templates = tmp_path / ".familiar" / "conjurings"
         templates.mkdir(parents=True)
         (templates / "core.md").write_text("CORE")
@@ -137,7 +158,6 @@ class TestComposeSystem:
         (templates / "second.md").write_text("SECOND")
 
         system = compose_system(tmp_path, ["first", "second"])
-        # verify order: core, then conjurings in order
         assert system == "CORE\n\nFIRST\n\nSECOND"
 
     def test_compose_core_only(self, tmp_path):
@@ -417,6 +437,63 @@ class TestResolveIncludes:
         result = resolve_includes(tmp_path, text)
         assert result == "content"
 
+    def test_nested_include_resolves(self, tmp_path):
+        """a snippet that includes another snippet is expanded fully."""
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "outer.txt").write_text("outer[{{> snippet:test/inner.txt}}]")
+        (snippet_dir / "inner.txt").write_text("INNER")
+
+        result = resolve_includes(tmp_path, "{{> snippet:test/outer.txt}}")
+        assert result == "outer[INNER]"
+        assert "{{> snippet" not in result
+
+    def test_deeply_nested_include_resolves(self, tmp_path):
+        """nested includes resolve through several levels."""
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "a.txt").write_text("a({{> snippet:test/b.txt}})")
+        (snippet_dir / "b.txt").write_text("b({{> snippet:test/c.txt}})")
+        (snippet_dir / "c.txt").write_text("c")
+
+        result = resolve_includes(tmp_path, "{{> snippet:test/a.txt}}")
+        assert result == "a(b(c))"
+
+    def test_self_include_raises_cycle(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "loop.txt").write_text("{{> snippet:test/loop.txt}}")
+
+        with pytest.raises(NotFoundError, match="snippet include cycle") as exc:
+            resolve_includes(tmp_path, "{{> snippet:test/loop.txt}}")
+        assert "test/loop.txt -> test/loop.txt" in str(exc.value)
+
+    def test_mutual_include_raises_cycle(self, tmp_path):
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        (snippet_dir / "a.txt").write_text("{{> snippet:test/b.txt}}")
+        (snippet_dir / "b.txt").write_text("{{> snippet:test/a.txt}}")
+
+        with pytest.raises(NotFoundError, match="snippet include cycle") as exc:
+            resolve_includes(tmp_path, "{{> snippet:test/a.txt}}")
+        assert "test/a.txt" in str(exc.value)
+        assert "test/b.txt" in str(exc.value)
+
+    def test_include_depth_backstop(self, tmp_path):
+        """an over-deep acyclic chain raises rather than recursing without bound."""
+        snippet_dir = tmp_path / ".familiar" / "snippets" / "test"
+        snippet_dir.mkdir(parents=True)
+        chain_len = _MAX_INCLUDE_DEPTH + 2
+        for i in range(chain_len):
+            if i < chain_len - 1:
+                body = "{{> snippet:test/s" + str(i + 1) + ".txt}}"
+            else:
+                body = "end"
+            (snippet_dir / f"s{i}.txt").write_text(body)
+
+        with pytest.raises(NotFoundError, match="depth exceeded"):
+            resolve_includes(tmp_path, "{{> snippet:test/s0.txt}}")
+
 
 class TestListSnippets:
     """tests for listing snippets."""