familiar-cli 0.0.5__py3-none-any.whl

familiar/__init__.py

@@ -0,0 +1,7 @@
+"""familiar - compose and invoke ai agent prompts."""
+
+from importlib.metadata import version
+
+__all__ = ["agents", "render", "cli"]
+
+__version__ = version("familiar-cli")

familiar/agents.py

@@ -0,0 +1,63 @@
+"""Agent implementations for familiar."""
+
+from __future__ import annotations
+
+import subprocess
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+
+class Agent(ABC):
+    """Base class for AI coding agents."""
+
+    name: str
+    output_file: str
+
+    @abstractmethod
+    def run(self, repo_root: Path, prompt: str, headless: bool) -> int:
+        """Run the agent with the given prompt."""
+
+
+class CodexAgent(Agent):
+    name = "codex"
+    output_file = "AGENTS.md"
+
+    def run(self, repo_root: Path, prompt: str, headless: bool) -> int:
+        if headless:
+            cmd = ["codex", "exec", "-C", str(repo_root), "-"]
+            proc = subprocess.run(cmd, input=prompt, text=True)
+            return proc.returncode
+        else:
+            cmd = ["codex", "-C", str(repo_root), prompt]
+            return subprocess.call(cmd)
+
+
+class ClaudeAgent(Agent):
+    name = "claude"
+    output_file = "CLAUDE.md"
+
+    def run(self, repo_root: Path, prompt: str, headless: bool) -> int:
+        # claude cli doesn't support a working directory flag like codex's -C;
+        # it uses cwd automatically, so repo_root is unused here
+        if headless:
+            cmd = ["claude", "-p", prompt]
+        else:
+            cmd = ["claude", prompt]
+        return subprocess.call(cmd)
+
+
+AGENTS: dict[str, Agent] = {
+    "codex": CodexAgent(),
+    "claude": ClaudeAgent(),
+}
+
+
+def get_agent(name: str) -> Agent:
+    """Get an agent by name.
+
+    Raises:
+        KeyError: if the agent name is not recognized.
+    """
+    if name not in AGENTS:
+        raise KeyError(f"unknown agent: {name}")
+    return AGENTS[name]

familiar/cli.py

@@ -0,0 +1,278 @@
+"""Command-line interface for familiar."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import traceback
+from pathlib import Path
+
+from .agents import AGENTS, get_agent
+from .lint import lint_all
+from .render import render_invocation, compose_system, list_items, NotFoundError
+
+# exit codes
+EXIT_SUCCESS = 0
+EXIT_ERROR = 1  # general error (agent failed, etc.)
+EXIT_USAGE = 2  # usage error (bad args, missing files, etc.)
+
+
+class CliError(Exception):
+    """CLI error with optional hint."""
+
+    def __init__(
+        self, message: str, hint: str | None = None, exit_code: int = EXIT_USAGE
+    ):
+        super().__init__(message)
+        self.hint = hint
+        self.exit_code = exit_code
+
+
+def find_repo_root(start: Path) -> Path:
+    """Find the repository root by looking for .git directory.
+
+    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()
+    for p in [cur] + list(cur.parents):
+        if (p / ".git").exists():
+            return p
+    return cur
+
+
+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=f"valid agents: {', '.join(AGENTS.keys())}")
+    (repo_root / agent.output_file).write_text(system.strip() + "\n", encoding="utf-8")
+
+
+def parse_kv(pairs: list[str]) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for p in pairs:
+        if "=" not in p:
+            raise CliError(
+                f"invalid argument: {p}",
+                hint="use key=value format, e.g. --kv name=myproject",
+            )
+        k, v = p.split("=", 1)
+        out[k.strip()] = v.strip()
+    return out
+
+
+def run_agent(repo_root: Path, agent_name: str, prompt: str, headless: bool) -> int:
+    try:
+        agent = get_agent(agent_name)
+    except KeyError as e:
+        raise CliError(str(e), hint=f"valid agents: {', '.join(AGENTS.keys())}")
+    try:
+        return agent.run(repo_root, prompt, headless)
+    except FileNotFoundError:
+        raise CliError(
+            f"{agent_name} not found in PATH",
+            hint=f"install {agent_name} or check your PATH environment variable",
+        )
+
+
+def cmd_conjure(args: argparse.Namespace) -> int:
+    repo_root = find_repo_root(Path(args.into or os.getcwd()))
+    try:
+        system = compose_system(repo_root, args.conjurings)
+    except NotFoundError as e:
+        raise CliError(
+            str(e),
+            hint="run 'familiar list conjurings' to see available options",
+        )
+    write_instruction(repo_root, args.agent, system)
+    print(f"wrote instructions for {args.agent}")
+    return EXIT_SUCCESS
+
+
+def cmd_invoke(args: argparse.Namespace) -> int:
+    repo_root = find_repo_root(Path(args.into or os.getcwd()))
+    kv = parse_kv(args.kv or [])
+    try:
+        prompt = render_invocation(repo_root, args.invocation, args.inv_args or [], kv)
+    except NotFoundError as e:
+        raise CliError(
+            str(e),
+            hint="run 'familiar list invocations' to see available options",
+        )
+    return run_agent(repo_root, args.agent, prompt, headless=args.headless)
+
+
+def _print_items(
+    items: list[tuple[str, str, bool]], verbose: bool, indent: str = ""
+) -> None:
+    for name, first_line, is_local in items:
+        marker = " (local)" if is_local else ""
+        if verbose:
+            print(f"{indent}{name}{marker}: {first_line}")
+        else:
+            print(f"{indent}{name}{marker}")
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    repo_root = find_repo_root(Path(args.into or os.getcwd()))
+
+    if args.kind is None:
+        # list both
+        conjurings = list_items(repo_root, "templates")
+        invocations = list_items(repo_root, "invocations")
+        print("conjurings:")
+        _print_items(conjurings, args.verbose, indent="  ")
+        print("\ninvocations:")
+        _print_items(invocations, args.verbose, indent="  ")
+        return EXIT_SUCCESS
+
+    # map CLI names to internal names; "conjurings" is the user-facing term
+    # for what are stored internally as "templates"
+    kind = "templates" if args.kind == "conjurings" else args.kind
+    items = list_items(repo_root, kind)
+
+    if not items:
+        print(f"no {args.kind} found")
+        return EXIT_SUCCESS
+
+    _print_items(items, args.verbose)
+    return EXIT_SUCCESS
+
+
+def cmd_lint(args: argparse.Namespace) -> int:
+    repo_root = find_repo_root(Path(args.into or os.getcwd()))
+
+    messages = lint_all(repo_root)
+
+    # Filter by level if requested
+    if args.errors_only:
+        messages = [m for m in messages if m.level == "error"]
+
+    if not messages:
+        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"]
+
+    for msg in errors:
+        print(msg, file=sys.stderr)
+    for msg in warnings:
+        print(msg, file=sys.stderr)
+
+    if errors:
+        print(f"\n{len(errors)} error(s), {len(warnings)} warning(s)", file=sys.stderr)
+        return EXIT_ERROR
+
+    print(f"\n{len(warnings)} warning(s)", file=sys.stderr)
+    return EXIT_SUCCESS
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="familiar",
+        description="conjure and invoke familiars",
+        epilog="examples:\n"
+        "  familiar conjure codex rust sec      # create AGENTS.md\n"
+        "  familiar invoke codex bootstrap-rust # run invocation\n"
+        "  familiar list                        # show all options\n"
+        "  familiar lint                        # validate prompts\n",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--debug", action="store_true", help="show full traceback on error"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    agent_choices = list(AGENTS.keys())
+
+    conjure = sub.add_parser(
+        "conjure",
+        help="compose system instructions for an agent",
+        epilog="example: familiar conjure codex rust infra sec",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    conjure.add_argument("agent", choices=agent_choices)
+    conjure.add_argument(
+        "conjurings", nargs="+", help="conjuring names, e.g. rust infra sec"
+    )
+    conjure.add_argument("--into", help="target repo path (default: current directory)")
+    conjure.set_defaults(func=cmd_conjure)
+
+    invoke = sub.add_parser(
+        "invoke",
+        help="render an invocation and run the agent",
+        epilog="example: familiar invoke codex bootstrap-rust myapp bin 1.78 mit",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    invoke.add_argument("agent", choices=agent_choices)
+    invoke.add_argument("invocation")
+    invoke.add_argument("--into", help="target repo path (default: current directory)")
+    invoke.add_argument(
+        "--headless", action="store_true", help="run without interactive UI"
+    )
+    invoke.add_argument("--kv", nargs="*", help="named arguments as key=value pairs")
+    invoke.add_argument(
+        "inv_args", nargs="*", help="positional arguments for the invocation"
+    )
+    invoke.set_defaults(func=cmd_invoke)
+
+    list_cmd = sub.add_parser(
+        "list",
+        help="list available conjurings and invocations",
+        epilog="example: familiar list conjurings -v",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    list_cmd.add_argument(
+        "kind",
+        nargs="?",
+        choices=["conjurings", "invocations"],
+        help="what to list (default: both)",
+    )
+    list_cmd.add_argument(
+        "--into", help="target repo path (default: current directory)"
+    )
+    list_cmd.add_argument(
+        "-v", "--verbose", action="store_true", help="show first line of each file"
+    )
+    list_cmd.set_defaults(func=cmd_list)
+
+    lint_cmd = sub.add_parser(
+        "lint",
+        help="lint templates and invocations",
+        epilog="example: familiar lint --errors-only",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    lint_cmd.add_argument(
+        "--into", help="target repo path (default: current directory)"
+    )
+    lint_cmd.add_argument(
+        "--errors-only", action="store_true", help="show only errors, not warnings"
+    )
+    lint_cmd.set_defaults(func=cmd_lint)
+
+    args = parser.parse_args()
+
+    try:
+        rc = args.func(args)
+    except CliError as e:
+        if args.debug:
+            traceback.print_exc()
+        print(f"error: {e}", file=sys.stderr)
+        if e.hint:
+            print(f"hint: {e.hint}", file=sys.stderr)
+        raise SystemExit(e.exit_code)
+    except Exception as e:
+        if args.debug:
+            traceback.print_exc()
+        print(f"error: {e}", file=sys.stderr)
+        raise SystemExit(EXIT_ERROR)
+
+    raise SystemExit(rc)
+
+
+if __name__ == "__main__":
+    main()

familiar/data/invocations/__noop__.md

@@ -0,0 +1 @@
+<!-- noop invocation for conjure command -->

familiar/data/invocations/add-tests.md

@@ -0,0 +1,68 @@
+task: add tests for existing code.
+
+## inputs
+
+- $ARGUMENTS (required): file path, function name, class name, or module to test.
+
+## preconditions
+
+STOP and ask if:
+- the target is unclear or cannot be located
+- you're unsure what behavior to test
+- the code has no clear contract or expected behavior
+
+before starting:
+- read the code to understand its contract
+- check if tests already exist (don't duplicate)
+- identify the testing framework used in the project
+
+## constraints
+
+- **match project conventions**: use the same test framework, file locations, and naming patterns.
+- **no behavior changes**: you're adding tests, not fixing bugs (note bugs separately).
+- **minimal mocking**: only mock external dependencies; prefer real objects when possible.
+
+## what to test
+
+write tests covering:
+1. **happy path**: the main success scenario
+2. **edge case**: boundary conditions, empty inputs, large inputs
+3. **error case**: invalid inputs, expected failures
+
+## test quality checklist
+
+each test should be:
+- [ ] **deterministic**: no flakiness from time, network, or random values
+- [ ] **isolated**: can run independently of other tests
+- [ ] **fast**: no unnecessary I/O or sleeps
+- [ ] **readable**: clear what's being tested and why
+- [ ] **focused**: one behavior per test
+
+## steps
+
+1. **locate**: find the code to test and understand its contract.
+2. **check**: verify no duplicate tests exist.
+3. **plan**: list the test cases you will write.
+4. **write**: implement tests, preferring parametrized/table-driven style.
+5. **run**: execute the test suite and confirm all tests pass.
+
+## output
+
+```
+## unit under test
+<file:function or class being tested>
+
+## test cases
+1. <test name>: <what it verifies>
+2. <test name>: <what it verifies>
+3. <test name>: <what it verifies>
+
+## changes
+<diff of new test file or additions>
+
+## verification
+<exact test command>
+
+## notes (optional)
+<bugs noticed, edge cases not covered, etc.>
+```

familiar/data/invocations/bootstrap-python.md

@@ -0,0 +1,102 @@
+task: bootstrap a new python project with modern tooling.
+
+## inputs
+
+- $1 `package_name` (required): name of the package (e.g., `myapp`)
+- $2 `package_type` (required): `cli` or `lib`
+- $3 `python_version` (optional): minimum python version (default: `3.10`)
+- $4 `license` (optional): license identifier (e.g., `MIT`, `Apache-2.0`)
+
+## preconditions
+
+STOP and ask if:
+- package_name is missing or invalid (not a valid python identifier)
+- package_type is not `cli` or `lib`
+- the target directory already exists (ask: abort, overwrite, or integrate?)
+
+## what gets created
+
+```
+<package_name>/
+├── pyproject.toml       # modern python packaging with ruff, mypy, pytest
+├── README.md            # one-line description + quickstart
+├── src/
+│   └── <package_name>/
+│       ├── __init__.py  # version and public API
+│       ├── main.py      # (cli) entry point with argument parsing
+│       └── core.py      # (lib) core module placeholder
+└── tests/
+    ├── __init__.py
+    └── test_<package_name>.py  # minimal test
+```
+
+## steps
+
+1. **validate**: confirm inputs are valid and directory doesn't conflict.
+2. **create**: set up directory structure with src layout.
+3. **configure**: create pyproject.toml with metadata and tool configs.
+4. **readme**: create README.md with purpose and quickstart.
+5. **code**: add minimal implementation with type hints.
+6. **test**: add a minimal passing test.
+7. **verify**: run format, lint, type check, and tests.
+
+## pyproject.toml structure
+
+```toml
+[project]
+name = "<package_name>"
+version = "0.1.0"
+description = "TODO: add description"
+requires-python = ">=<python_version>"
+license = "<license>"  # if provided
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["ruff", "mypy", "pytest", "pytest-cov"]
+
+[project.scripts]  # cli only
+<package_name> = "<package_name>.main:main"
+
+[tool.ruff]
+target-version = "py<python_version_short>"
+line-length = 88
+
+[tool.mypy]
+python_version = "<python_version>"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+```
+
+## acceptance criteria
+
+all must pass:
+```
+ruff format --check .
+ruff check .
+mypy .
+pytest -q
+```
+
+## output
+
+```
+## project created
+<package_name> (<package_type>)
+
+## files
+<list of files created with brief description>
+
+## changes
+<diff of all created files>
+
+## setup
+pip install -e ".[dev]"
+
+## verification
+ruff format --check . && ruff check . && mypy . && pytest -q
+
+## next steps
+<suggested next actions: add dependencies, implement features, publish, etc.>
+```

familiar/data/invocations/bootstrap-rust.md

@@ -0,0 +1,81 @@
+task: bootstrap a new rust crate with best practices.
+
+## inputs
+
+- $1 `crate_name` (required): name of the crate (e.g., `myapp`)
+- $2 `crate_type` (required): `bin` or `lib`
+- $3 `msrv` (optional): minimum supported rust version (e.g., `1.75`)
+- $4 `license` (optional): license identifier (e.g., `MIT`, `Apache-2.0`)
+
+## preconditions
+
+STOP and ask if:
+- crate_name is missing or invalid (not a valid rust identifier)
+- crate_type is not `bin` or `lib`
+- the target directory already exists (ask: abort, overwrite, or integrate?)
+
+## what gets created
+
+```
+<crate_name>/
+├── Cargo.toml          # with metadata, msrv, license if provided
+├── README.md           # one-line description + quickstart
+├── src/
+│   ├── main.rs         # (bin) minimal main with error handling
+│   └── lib.rs          # (lib) minimal module with doc comment
+└── tests/              # (lib only) integration test placeholder
+    └── integration.rs
+```
+
+## steps
+
+1. **validate**: confirm inputs are valid and directory doesn't conflict.
+2. **create**: run `cargo new <crate_name> --<crate_type>`.
+3. **configure**: update Cargo.toml with metadata, msrv, and license.
+4. **readme**: create README.md with purpose and quickstart.
+5. **test**: add a minimal test if not present.
+6. **verify**: run format, clippy, and tests.
+
+## cargo.toml structure
+
+```toml
+[package]
+name = "<crate_name>"
+version = "0.1.0"
+edition = "2021"
+rust-version = "<msrv>"  # if provided
+license = "<license>"    # if provided
+description = "TODO: add description"
+
+[dependencies]
+
+[dev-dependencies]
+```
+
+## acceptance criteria
+
+all must pass:
+```
+cargo fmt --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all-features
+```
+
+## output
+
+```
+## crate created
+<crate_name> (<crate_type>)
+
+## files
+<list of files created with brief description>
+
+## changes
+<diff of all created/modified files>
+
+## verification
+cargo fmt --check && cargo clippy --all-targets --all-features -- -D warnings && cargo test --all-features
+
+## next steps
+<suggested next actions: add dependencies, implement features, etc.>
+```

familiar/data/invocations/code-review.md

@@ -0,0 +1,80 @@
+task: review code for quality, correctness, and maintainability.
+
+## inputs
+
+- $ARGUMENTS (optional): file path, function name, or scope to review. if empty, review recent changes or staged diff.
+
+## preconditions
+
+if no target is specified and no recent changes exist:
+- ask what to review
+- do not review arbitrary code
+
+## review checklist
+
+examine the code for:
+
+**correctness**
+- does it do what it claims to do?
+- are edge cases handled?
+- are error conditions handled properly?
+- are there potential null/undefined issues?
+
+**clarity**
+- is the code easy to understand?
+- are names descriptive and consistent?
+- is the logic straightforward or needlessly complex?
+- are there comments where needed (and only where needed)?
+
+**maintainability**
+- is the code modular and testable?
+- does it follow project conventions?
+- would a new team member understand it?
+- is there duplication that should be extracted?
+
+**performance** (only if relevant)
+- are there obvious inefficiencies?
+- is there unnecessary work in hot paths?
+
+## how to give feedback
+
+- **be specific**: reference file:line, quote the code
+- **be actionable**: say what to change, not just what's wrong
+- **be proportionate**: don't nitpick style in a bugfix review
+- **acknowledge good work**: note well-written code too
+
+## severity levels
+
+- **blocker**: must fix before merge (bugs, security issues, data loss risks)
+- **major**: should fix before merge (design issues, missing tests, unclear logic)
+- **minor**: consider fixing (style, naming, minor improvements)
+- **nit**: optional, take or leave (personal preferences)
+
+## output
+
+```
+## scope
+<what was reviewed: files, functions, commit range>
+
+## summary
+<1-2 sentence overall assessment>
+
+## findings
+
+### blockers
+- [file:line] <issue>
+  - suggestion: <how to fix>
+
+### major
+- [file:line] <issue>
+  - suggestion: <how to fix>
+
+### minor
+- [file:line] <issue>
+
+### positive
+- <what was done well>
+
+## verdict
+<approve / request changes / needs discussion>
+```