Migrate from Click to Typer + Rich

Python tools:
- Replace click with typer for CLI framework
- Use 'from rich import print' in all tools (shadows builtin)
- Remove Console usage, just use print() for everything
- Update all 9 Python scripts

CI hooks:
- Rename check_no_argparse.py -> check_typer_cli.py (bans argparse AND click)
- Delete check_no_print.py (we now use print from rich)
- Add check_rich_print.py (enforces 'from rich import print')

Docs:
- Update python/README.md with typer patterns and conventions
- Update pyproject.toml comments
- Update ci/README.md

Author: crypdick

.pre-commit-config.yaml

@@ -55,16 +55,16 @@ repos:
         exclude: ^(python/README\.md|bash/README\.md)
 
       # Custom repository standards
-      - id: check-no-argparse
-        name: check no argparse (use click)
-        entry: uv run --no-project python ci/check_no_argparse.py
+      - id: check-typer-cli
+        name: check typer CLI (no argparse/click)
+        entry: uv run --no-project python ci/check_typer_cli.py
         language: system
         types: [python]
         files: ^python/
 
-      - id: check-no-print
-        name: check no print() (use click.echo)
-        entry: uv run --no-project python ci/check_no_print.py
+      - id: check-rich-print
+        name: check 'from rich import print'
+        entry: uv run --no-project python ci/check_rich_print.py
         language: system
         types: [python]
         files: ^python/

ci/README.md

@@ -4,11 +4,10 @@
 
 ### Python Tools
 - `check_executable.py` - Scripts must be executable
-- `check_no_argparse.py` - Use `click`, not `argparse`
-- `check_no_print.py` - Use `click.echo()`, not `print()`
+- `check_typer_cli.py` - Use `typer`, not `argparse` or `click`
+- `check_rich_print.py` - Require `from rich import print`
 - `check_main_guard.py` - Require `if __name__ == "__main__":`
 - `check_no_any.py` - Ban `typing.Any`
-- `check_help.py` - Ensure scripts support `--help`
 
 ### HTML Tools
 - `check_html_metadata.py` - Require frontmatter with category, `<title>`, and `<p class="subtitle">`
@@ -20,7 +19,8 @@
 uvx pre-commit run --all-files
 
 # Test individual hook
-python ci/check_no_argparse.py python/tool.py
+python ci/check_typer_cli.py python/tool.py
+python ci/check_rich_print.py python/tool.py
 ```
 
 All hooks run automatically via `.pre-commit-config.yaml`.

ci/check_no_argparse.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Check that Python tools import print from rich."""
+
+import ast
+import sys
+from pathlib import Path
+
+
+def has_rich_print_import(tree: ast.Module) -> bool:
+    """Check if file has 'from rich import print' statement."""
+    for node in tree.body:
+        if (
+            isinstance(node, ast.ImportFrom)
+            and node.module == "rich"
+            and any(alias.name == "print" for alias in node.names)
+        ):
+            return True
+    return False
+
+
+def check_file(filepath: Path) -> bool:
+    """Check if file imports print from rich."""
+    try:
+        content = filepath.read_text()
+        tree = ast.parse(content, filename=str(filepath))
+
+        if not has_rich_print_import(tree):
+            print(f"{filepath}: missing 'from rich import print'")
+            return False
+
+        return True
+    except SyntaxError as e:
+        print(f"{filepath}: syntax error: {e}")
+        return False
+
+
+def main() -> int:
+    """Check all Python tool files passed as arguments."""
+    files = [Path(f) for f in sys.argv[1:]]
+    # Only check files in python/ directory
+    python_tools = [
+        f
+        for f in files
+        if f.suffix == ".py"
+        and f.is_file()
+        and "python/" in str(f)
+        and not f.name.startswith("test_")
+    ]
+
+    if not python_tools:
+        return 0
+
+    all_good = True
+    for filepath in python_tools:
+        if not check_file(filepath):
+            all_good = False
+
+    return 0 if all_good else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+

ci/check_no_print.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Check that Python files use typer instead of argparse or click."""
+
+import ast
+import sys
+from pathlib import Path
+
+BANNED_MODULES = {
+    "argparse": "use typer instead",
+    "click": "use typer instead",
+}
+
+
+def check_file(filepath: Path) -> bool:
+    """Check if file imports banned CLI modules."""
+    try:
+        content = filepath.read_text()
+        tree = ast.parse(content, filename=str(filepath))
+
+        all_good = True
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    if alias.name in BANNED_MODULES:
+                        reason = BANNED_MODULES[alias.name]
+                        print(f"{filepath}:{node.lineno}: imports {alias.name} ({reason})")
+                        all_good = False
+            elif isinstance(node, ast.ImportFrom) and node.module in BANNED_MODULES:
+                reason = BANNED_MODULES[node.module]
+                print(f"{filepath}:{node.lineno}: imports from {node.module} ({reason})")
+                all_good = False
+
+        return all_good
+    except SyntaxError as e:
+        print(f"{filepath}: syntax error: {e}")
+        return False
+
+
+def main() -> int:
+    """Check all Python files passed as arguments."""
+    files = [Path(f) for f in sys.argv[1:]]
+    # Only check files in python/ directory (not ci/ scripts)
+    python_files = [
+        f
+        for f in files
+        if f.suffix == ".py"
+        and f.is_file()
+        and "python/" in str(f)
+    ]
+
+    if not python_files:
+        return 0
+
+    all_good = True
+    for filepath in python_files:
+        if not check_file(filepath):
+            all_good = False
+
+    return 0 if all_good else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ci/check_rich_print.py

@@ -26,8 +26,8 @@ strict_concatenate = true
 
 # Explicitly ban Any
 disallow_any_unimported = true
-disallow_any_expr = false  # Too strict, would break click decorators
-disallow_any_decorated = false  # Too strict for click
+disallow_any_expr = false  # Too strict, would break typer Annotated types
+disallow_any_decorated = false  # Too strict for typer
 disallow_any_explicit = true  # Ban explicit Any usage
 
 # Additional strictness