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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "familiar-cli"
-version = "0.5.2"
+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.2 → 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.2 → 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.2 → familiar_cli-0.6.0}/src/familiar/_plugins.py

@@ -3,8 +3,9 @@
 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(
@@ -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.2 → familiar_cli-0.6.0}/src/familiar/agents.py

@@ -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"]
@@ -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,

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

@@ -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,
@@ -46,7 +46,7 @@ def _agent_hint() -> str:
     return f"valid agents: {', '.join(get_agents().keys())}"
 
 
-def _resolve_agent(name: str) -> "Agent":
+def _resolve_agent(name: str) -> Agent:
     """look up an agent by name, raising CliError on unknown names."""
     try:
         return get_agent(name)
@@ -94,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()
@@ -119,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:
@@ -509,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)

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

@@ -3,13 +3,22 @@
 from __future__ import annotations
 
 import re
+from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Callable, Literal
+from typing import Literal
 
 from ._plugins import load_plugins
-
-from .render import _SNIPPET_INCLUDE, NotFoundError, list_items, load_snippet, load_text
+from .render import (
+    _SNIPPET_INCLUDE,
+    NotFoundError,
+    _expand_includes,
+    list_items,
+    list_snippets,
+    load_snippet,
+    load_text,
+    resolve_includes,
+)
 
 
 @dataclass
@@ -41,7 +50,7 @@ _INPUTS_SECTION = re.compile(
     r"^(##\s+)?(inputs?|arguments?)(\s*\([^)]+\))?:?\s*$", re.IGNORECASE | re.MULTILINE
 )
 _OUTPUT_SECTION = re.compile(
-    r"^(##\s+)?(output|deliverables?):?\s*$", re.IGNORECASE | re.MULTILINE
+    r"^(##\s+)?(outputs?|deliverables?):?\s*$", re.IGNORECASE | re.MULTILINE
 )
 
 
@@ -79,6 +88,61 @@ def lint_template(content: str, name: str) -> list[LintMessage]:
     return messages
 
 
+def _check_placeholder_docs(
+    positional: set[str], named: set[str], doc_content: str, name: str
+) -> list[LintMessage]:
+    """warn about placeholders not documented in ``doc_content``'s inputs section."""
+    messages: list[LintMessage] = []
+
+    # loose check: prefer the inputs section if it exists, else the whole file
+    inputs_match = _INPUTS_SECTION.search(doc_content)
+    if inputs_match:
+        start = inputs_match.end()
+        # look ahead for the next markdown heading or end of file
+        next_heading = re.search(r"^#", doc_content[start:], re.MULTILINE)
+        search_area = (
+            doc_content[start : start + next_heading.start()]
+            if next_heading
+            else doc_content[start:]
+        ).lower()
+    else:
+        search_area = doc_content.lower()
+
+    for placeholder in named:
+        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",
+                    file=name,
+                    line=None,
+                    message=f"placeholder '{{{{{placeholder}}}}}' may not be documented in inputs",
+                )
+            )
+
+    for p in positional:
+        if p == "ARGUMENTS":
+            continue
+        pattern = rf"(\w+[:\s]+\${p}|\${p}\s+[`\w]|\${p}\s*\()"
+        if not re.search(pattern, search_area):
+            messages.append(
+                LintMessage(
+                    level="warning",
+                    file=name,
+                    line=None,
+                    message=f"placeholder '${p}' may not be documented in inputs",
+                )
+            )
+
+    return messages
+
+
 def lint_invocation(content: str, name: str) -> list[LintMessage]:
     """lint an invocation file.
 
@@ -135,52 +199,7 @@ def lint_invocation(content: str, name: str) -> list[LintMessage]:
 
     positional = set(_POSITIONAL_PLACEHOLDER.findall(content))
     named = set(_NAMED_PLACEHOLDER.findall(content))
-
-    # 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
-        next_heading = re.search(r"^#", content[start:], re.MULTILINE)
-        search_area = (
-            content[start : start + next_heading.start()]
-            if next_heading
-            else content[start:]
-        ).lower()
-    else:
-        search_area = content.lower()
-
-    for placeholder in named:
-        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",
-                    file=name,
-                    line=None,
-                    message=f"placeholder '{{{{{placeholder}}}}}' may not be documented in inputs",
-                )
-            )
-
-    for p in positional:
-        if p == "ARGUMENTS":
-            continue
-        pattern = rf"(\w+[:\s]+\${p}|\${p}\s+[`\w]|\${p}\s*\()"
-        if not re.search(pattern, search_area):
-            messages.append(
-                LintMessage(
-                    level="warning",
-                    file=name,
-                    line=None,
-                    message=f"placeholder '${p}' may not be documented in inputs",
-                )
-            )
+    messages.extend(_check_placeholder_docs(positional, named, content, name))
 
     return messages
 
@@ -208,13 +227,19 @@ 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 snippet includes resolve, following them transitively.
+
+    each top-level ``{{> snippet:path}}`` directive is validated along with
+    every snippet it pulls in, mirroring how the renderer expands includes at
+    conjure/invoke time. a broken reference, an include cycle, or an over-deep
+    chain is reported against the line of the top-level directive.
+    """
     messages: list[LintMessage] = []
     for i, line in enumerate(content.split("\n"), 1):
         for m in _SNIPPET_INCLUDE.finditer(line):
             snippet_path = m.group(1).strip()
             try:
-                load_snippet(repo_root, snippet_path)
+                body = load_snippet(repo_root, snippet_path)
             except NotFoundError:
                 messages.append(
                     LintMessage(
@@ -224,9 +249,74 @@ def lint_snippet_references(
                         message=f"snippet not found: {snippet_path}",
                     )
                 )
+                continue
+            try:
+                _expand_includes(repo_root, body, [snippet_path])
+            except NotFoundError as e:
+                messages.append(
+                    LintMessage(
+                        level="error",
+                        file=name,
+                        line=i,
+                        message=str(e),
+                    )
+                )
     return messages
 
 
+def lint_snippet_collection(repo_root: Path) -> list[LintMessage]:
+    """lint every snippet body for broken, cyclic, or over-deep includes.
+
+    a snippet may include other snippets; a bad snippet->snippet include stays
+    invisible until something transitively pulls it in. each snippet is checked
+    against its own path.
+    """
+    messages: list[LintMessage] = []
+    for path, _, is_local in list_snippets(repo_root):
+        prefix = (
+            f".familiar/snippets/{path}" if is_local else f"(builtin) snippets/{path}"
+        )
+        try:
+            content = load_snippet(repo_root, path)
+        except NotFoundError as e:
+            messages.append(
+                LintMessage(
+                    level="error",
+                    file=prefix,
+                    line=None,
+                    message=f"failed to load: {e}",
+                )
+            )
+            continue
+        messages.extend(lint_snippet_references(repo_root, content, prefix))
+    return messages
+
+
+def lint_snippet_placeholders(
+    repo_root: Path, content: str, name: str
+) -> list[LintMessage]:
+    """check placeholders that included snippets contribute to an invocation.
+
+    the renderer expands includes before substituting, so a ``$1``/``{{key}}``
+    inside an included snippet is live at invoke time but invisible to the
+    raw-text check in :func:`lint_invocation`. only the snippet-contributed
+    delta is checked here; broken or cyclic includes are left to
+    :func:`lint_snippet_references`.
+    """
+    try:
+        expanded = resolve_includes(repo_root, content)
+    except NotFoundError:
+        return []
+
+    positional = set(_POSITIONAL_PLACEHOLDER.findall(expanded)) - set(
+        _POSITIONAL_PLACEHOLDER.findall(content)
+    )
+    named = set(_NAMED_PLACEHOLDER.findall(expanded)) - set(
+        _NAMED_PLACEHOLDER.findall(content)
+    )
+    return _check_placeholder_docs(positional, named, content, name)
+
+
 def lint_collection(
     repo_root: Path,
     kind: Literal["conjurings", "invocations"],
@@ -245,10 +335,13 @@ def lint_collection(
             )
             messages.extend(builtin_linter(content, prefix))
             messages.extend(lint_snippet_references(repo_root, content, prefix))
+            if kind == "invocations":
+                messages.extend(lint_snippet_placeholders(repo_root, content, prefix))
             for linter in plugin_linters:
                 try:
                     messages.extend(linter(content, prefix))
-                except Exception as e:
+                # a broken plugin linter is reported, not fatal to the run
+                except Exception as e:  # noqa: BLE001
                     messages.append(
                         LintMessage(
                             level="error",
@@ -287,5 +380,6 @@ def lint_all(repo_root: Path) -> list[LintMessage]:
     messages.extend(
         lint_collection(repo_root, "invocations", lint_invocation, invocation_linters)
     )
+    messages.extend(lint_snippet_collection(repo_root))
 
     return messages

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

@@ -70,6 +70,32 @@ def load_snippet(repo_root: Path, path: str) -> str:
         raise NotFoundError(f"unknown snippet: {path}")
 
 
+def _expand_includes(repo_root: Path, text: str, chain: list[str]) -> str:
+    """recursively expand {{> snippet:path}} includes in ``text``.
+
+    ``chain`` is the stack of ancestor snippet paths currently being expanded,
+    used to detect include cycles and cap nesting depth. shared by
+    :func:`resolve_includes` and the linter so both agree on exactly what
+    resolves, cycles, or exceeds depth.
+    """
+
+    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_includes(
+            repo_root, load_snippet(repo_root, path), [*chain, path]
+        )
+
+    return _SNIPPET_INCLUDE.sub(repl, text)
+
+
 def resolve_includes(repo_root: Path, text: str) -> str:
     """resolve {{> snippet:path}} includes, expanding nested includes recursively.
 
@@ -77,23 +103,7 @@ def resolve_includes(repo_root: Path, text: str) -> str:
     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 expand(text, [])
+    return _expand_includes(repo_root, text, [])
 
 
 def substitute(text: str, args: list[str], kv: dict[str, str]) -> str:
@@ -238,11 +248,18 @@ def list_items(repo_root: Path, kind: str) -> list[tuple[str, str, bool]]:
 
 
 def compose_system(repo_root: Path, conjurings: list[str]) -> str:
-    """compose system instructions from core + selected conjurings."""
+    """compose system instructions from core + selected conjurings.
+
+    snippet includes ({{> snippet:path}}) in the core text and in each
+    conjuring are expanded, mirroring :func:`render_invocation`. conjurings
+    receive no placeholder substitution, so any $N/{{key}} in an included
+    snippet is left verbatim.
+    """
     core = load_text(repo_root, "conjurings", "core").strip()
-    parts: list[str] = [core]
+    parts: list[str] = [resolve_includes(repo_root, core)]
     for name in conjurings:
-        parts.append(load_text(repo_root, "conjurings", name).strip())
+        text = load_text(repo_root, "conjurings", name).strip()
+        parts.append(resolve_includes(repo_root, text))
     return "\n\n".join(parts)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: familiar-cli
-Version: 0.5.2
+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.2 → familiar_cli-0.6.0}/src/familiar_cli.egg-info/requires.txt

@@ -1,6 +1,6 @@
 
 [dev]
-ruff
+ruff==0.16.1
 mypy
 pytest
 pytest-cov

{familiar_cli-0.5.2 → familiar_cli-0.6.0}/tests/test_agents.py

@@ -2,17 +2,18 @@
 
 from __future__ import annotations
 
+from unittest.mock import MagicMock, patch
+
 import pytest
-from unittest.mock import patch, MagicMock
 
 import familiar.agents as agents_module
 from familiar.agents import (
     Agent,
-    CodexAgent,
     ClaudeAgent,
-    load_agents,
-    get_agents,
+    CodexAgent,
     get_agent,
+    get_agents,
+    load_agents,
 )