@pennyfarthing/core 11.4.0 → 12.0.0

package/pennyfarthing-dist/src/pf/doctor/checks.py

@@ -0,0 +1,180 @@
+"""Individual health check functions.
+
+Story 126-8: Reduce doctor to ~10 health checks with --fix mode.
+
+Each check function takes a project root Path and returns a CheckResult.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+import yaml
+
+from pf.doctor.models import CheckResult
+
+# Expected symlink target directories under .pennyfarthing/
+_SYMLINK_DIRS = (
+    "agents", "commands", "guides", "personas", "scripts",
+    "skills", "workflows", "templates", "output-styles",
+)
+
+
+def check_python_install(root: Path) -> CheckResult:
+    """Check that pf CLI is installed and accessible."""
+    if shutil.which("pf"):
+        return CheckResult(name="python_install", status="pass", detail="pf CLI found on PATH")
+    return CheckResult(
+        name="python_install",
+        status="fail",
+        detail="pf CLI not found on PATH",
+    )
+
+
+def check_pennyfarthing_dir(root: Path) -> CheckResult:
+    """Check .pennyfarthing/ directory exists with required structure."""
+    pf_dir = root / ".pennyfarthing"
+    if pf_dir.is_dir():
+        return CheckResult(name="pennyfarthing_dir", status="pass", detail=".pennyfarthing/ exists")
+    return CheckResult(
+        name="pennyfarthing_dir",
+        status="fail",
+        detail=".pennyfarthing/ directory missing",
+        fix_fn=lambda: _fix_mkdir(pf_dir),
+    )
+
+
+def check_config_file(root: Path) -> CheckResult:
+    """Check config.local.yaml exists and is valid YAML."""
+    config = root / ".pennyfarthing" / "config.local.yaml"
+    if not config.is_file():
+        return CheckResult(
+            name="config_file",
+            status="fail",
+            detail="config.local.yaml missing",
+            fix_fn=lambda: _fix_default_config(config),
+        )
+    try:
+        yaml.safe_load(config.read_text())
+    except yaml.YAMLError:
+        return CheckResult(name="config_file", status="fail", detail="config.local.yaml has invalid YAML")
+    return CheckResult(name="config_file", status="pass", detail="config.local.yaml valid")
+
+
+def check_settings_hooks(root: Path) -> CheckResult:
+    """Check settings.local.json has required Claude Code hooks."""
+    settings_file = root / ".claude" / "settings.local.json"
+    if not settings_file.is_file():
+        return CheckResult(name="settings_hooks", status="fail", detail="settings.local.json missing")
+    try:
+        data = json.loads(settings_file.read_text())
+    except (json.JSONDecodeError, OSError):
+        return CheckResult(name="settings_hooks", status="fail", detail="settings.local.json unreadable")
+    hooks = data.get("hooks", {})
+    if not hooks:
+        return CheckResult(name="settings_hooks", status="fail", detail="No hooks configured")
+    return CheckResult(name="settings_hooks", status="pass", detail="Settings hooks present")
+
+
+def check_symlinks(root: Path) -> CheckResult:
+    """Check .pennyfarthing/ symlinks point to valid targets."""
+    pf_dir = root / ".pennyfarthing"
+    if not pf_dir.is_dir():
+        return CheckResult(name="symlinks", status="fail", detail=".pennyfarthing/ missing")
+    missing = [d for d in _SYMLINK_DIRS if not (pf_dir / d).exists()]
+    if missing:
+        return CheckResult(
+            name="symlinks",
+            status="fail",
+            detail=f"Missing: {', '.join(missing)}",
+        )
+    return CheckResult(name="symlinks", status="pass", detail="All symlink targets present")
+
+
+def check_commands(root: Path) -> CheckResult:
+    """Check .claude/commands/ has expected pf-* command files."""
+    cmd_dir = root / ".claude" / "commands"
+    if not cmd_dir.is_dir():
+        return CheckResult(name="commands", status="fail", detail=".claude/commands/ missing")
+    pf_cmds = list(cmd_dir.glob("pf-*"))
+    if not pf_cmds:
+        return CheckResult(name="commands", status="fail", detail="No pf-* commands found")
+    return CheckResult(name="commands", status="pass", detail=f"{len(pf_cmds)} pf-* commands found")
+
+
+def check_skills(root: Path) -> CheckResult:
+    """Check .claude/skills/ has expected pf-* skill directories."""
+    skills_dir = root / ".claude" / "skills"
+    if not skills_dir.is_dir():
+        return CheckResult(name="skills", status="fail", detail=".claude/skills/ missing")
+    pf_skills = [d for d in skills_dir.iterdir() if d.is_dir() and d.name.startswith("pf-")]
+    if not pf_skills:
+        return CheckResult(name="skills", status="fail", detail="No pf-* skills found")
+    return CheckResult(name="skills", status="pass", detail=f"{len(pf_skills)} pf-* skills found")
+
+
+def check_node_packages(root: Path) -> CheckResult:
+    """Check Node packages are installed (node_modules exists)."""
+    if (root / "node_modules").is_dir():
+        return CheckResult(name="node_packages", status="pass", detail="node_modules/ present")
+    return CheckResult(name="node_packages", status="warn", detail="node_modules/ missing — run npm install")
+
+
+def check_git_hooks(root: Path) -> CheckResult:
+    """Check git hooks dispatcher is installed."""
+    hooks_dir = root / ".git" / "hooks"
+    if not hooks_dir.is_dir():
+        return CheckResult(name="git_hooks", status="warn", detail=".git/hooks/ missing")
+    if not list(hooks_dir.iterdir()):
+        return CheckResult(name="git_hooks", status="warn", detail="No git hooks installed")
+    return CheckResult(name="git_hooks", status="pass", detail="Git hooks present")
+
+
+def check_theme(root: Path) -> CheckResult:
+    """Check active theme is valid and persona files exist."""
+    config = root / ".pennyfarthing" / "config.local.yaml"
+    if not config.is_file():
+        return CheckResult(name="theme", status="fail", detail="config.local.yaml missing — no theme set")
+    try:
+        data = yaml.safe_load(config.read_text()) or {}
+    except yaml.YAMLError:
+        return CheckResult(name="theme", status="fail", detail="config.local.yaml invalid")
+    theme = data.get("theme")
+    if not theme:
+        return CheckResult(name="theme", status="fail", detail="No theme set in config")
+    return CheckResult(name="theme", status="pass", detail=f"Theme: {theme}")
+
+
+# ---------------------------------------------------------------------------
+# Fix helpers
+# ---------------------------------------------------------------------------
+
+def _fix_mkdir(path: Path) -> bool:
+    path.mkdir(parents=True, exist_ok=True)
+    return path.is_dir()
+
+
+def _fix_default_config(path: Path) -> bool:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("theme: discworld\n")
+    return path.is_file()
+
+
+# ---------------------------------------------------------------------------
+# Check registry
+# ---------------------------------------------------------------------------
+
+CHECKS: list[tuple[str, str]] = [
+    ("python_install", "pf CLI is installed and accessible"),
+    ("pennyfarthing_dir", ".pennyfarthing/ directory exists"),
+    ("config_file", "config.local.yaml is valid"),
+    ("settings_hooks", "Claude Code hooks configured"),
+    ("symlinks", "Symlink targets present"),
+    ("commands", "pf-* commands installed"),
+    ("skills", "pf-* skills installed"),
+    ("node_packages", "Node packages installed"),
+    ("git_hooks", "Git hooks dispatcher installed"),
+    ("theme", "Active theme is valid"),
+]

package/pennyfarthing-dist/src/pf/doctor/cli.py

@@ -0,0 +1,52 @@
+"""Doctor CLI — pf doctor command.
+
+Story 126-8: Reduce doctor to ~10 health checks with --fix mode.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+
+from pf.common.config import get_project_root
+
+
+@click.command()
+@click.option("--fix", is_flag=True, help="Attempt to fix failed checks")
+@click.option("--json", "json_output", is_flag=True, help="Output as JSON")
+def doctor(fix: bool, json_output: bool) -> None:
+    """Run Pennyfarthing health checks.
+
+    Checks Python install, config, hooks, symlinks, commands,
+    skills, node packages, git hooks, and theme.
+    """
+    from pf.doctor.core import run_doctor
+
+    root = get_project_root()
+    report = run_doctor(root, fix=fix)
+
+    if json_output:
+        data = {
+            "success": report.success,
+            "checks": [
+                {"name": c.name, "status": c.status, "detail": c.detail}
+                for c in report.checks
+            ],
+            "fixed": report.fixed,
+        }
+        click.echo(json.dumps(data, indent=2))
+    else:
+        for c in report.checks:
+            icon = {"pass": "OK", "warn": "!!", "fail": "FAIL"}[c.status]
+            click.echo(f"  [{icon}] {c.name}: {c.detail}")
+        if report.fixed:
+            click.echo(f"\nFixed {report.fixed} issue(s).")
+        if report.success:
+            click.echo("\nAll checks passed.")
+        else:
+            click.echo("\nSome checks failed.")
+
+    if not report.success:
+        sys.exit(1)

package/pennyfarthing-dist/src/pf/doctor/core.py

@@ -0,0 +1,63 @@
+"""Core doctor logic — run checks, apply fixes.
+
+Story 126-8: Reduce doctor to ~10 health checks with --fix mode.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pf.doctor.checks import (
+    CHECKS,
+    check_commands,
+    check_config_file,
+    check_git_hooks,
+    check_node_packages,
+    check_pennyfarthing_dir,
+    check_python_install,
+    check_settings_hooks,
+    check_skills,
+    check_symlinks,
+    check_theme,
+)
+from pf.doctor.models import DoctorReport
+
+# Map check names to their functions
+_CHECK_FNS = {
+    "python_install": check_python_install,
+    "pennyfarthing_dir": check_pennyfarthing_dir,
+    "config_file": check_config_file,
+    "settings_hooks": check_settings_hooks,
+    "symlinks": check_symlinks,
+    "commands": check_commands,
+    "skills": check_skills,
+    "node_packages": check_node_packages,
+    "git_hooks": check_git_hooks,
+    "theme": check_theme,
+}
+
+
+def run_doctor(root: Path, *, fix: bool = False) -> DoctorReport:
+    """Run all health checks and optionally apply fixes.
+
+    Args:
+        root: Project root directory.
+        fix: If True, attempt to fix failed checks.
+
+    Returns:
+        DoctorReport with results of all checks.
+    """
+    report = DoctorReport()
+    fixed_count = 0
+
+    for name, _desc in CHECKS:
+        fn = _CHECK_FNS[name]
+        result = fn(root)
+        if fix and result.status == "fail" and result.fix_fn is not None:
+            result.fix_fn()
+            fixed_count += 1
+        report.checks.append(result)
+
+    report.fixed = fixed_count
+    report.success = all(c.status != "fail" for c in report.checks)
+    return report

package/pennyfarthing-dist/src/pf/doctor/models.py

@@ -0,0 +1,29 @@
+"""Data models for doctor health checks.
+
+Story 126-8: Reduce doctor to ~10 health checks with --fix mode.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+
+@dataclass
+class CheckResult:
+    """Result of a single health check."""
+
+    name: str
+    status: str  # "pass", "warn", "fail"
+    detail: str = ""
+    fix_fn: Callable[[], bool] | None = None
+
+
+@dataclass
+class DoctorReport:
+    """Aggregate report from all health checks. Follows ADR-0008."""
+
+    success: bool = False
+    checks: list[CheckResult] = field(default_factory=list)
+    fixed: int = 0
+    error: str | None = None

package/pennyfarthing-dist/src/pf/git/hooks_installer.py

@@ -0,0 +1,152 @@
+"""
+Git hooks installer — Python replacement for install-git-hooks.sh (145 lines).
+
+Creates .d/ dispatcher directories, symlinks pennyfarthing hooks,
+and migrates existing user hooks.
+
+Usage via CLI:
+    pf git install-hooks
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from pf.common.config import get_dist_root, get_project_root
+
+DISPATCHER_MARKER = "pennyfarthing-dispatcher"
+PF_PREFIX = "10"
+MIGRATED_PREFIX = "50"
+
+# Hook source file → git hook name
+HOOKS = [
+    ("pre-commit.sh", "pre-commit"),
+    ("pre-push.sh", "pre-push"),
+    ("post-merge.sh", "post-merge"),
+]
+
+
+def _generate_dispatcher(template_path: Path, hook_name: str) -> str:
+    """Generate a dispatcher script from the template."""
+    template = template_path.read_text()
+    return template.replace("__HOOK_NAME__", hook_name)
+
+
+def install_git_hooks(project_root: Path | None = None) -> int:
+    """Install git hooks with .d/ dispatcher pattern.
+
+    Creates .d/ directories for each hook, installs dispatcher scripts,
+    and symlinks pennyfarthing hooks into the .d/ directories.
+    Existing non-pennyfarthing hooks are migrated into .d/.
+
+    Args:
+        project_root: Project root. Auto-detected if not provided.
+
+    Returns:
+        0 on success, 1 on error
+    """
+    if project_root is None:
+        project_root = get_project_root()
+
+    pf_dist = get_dist_root(project_root=project_root)
+    if pf_dist is None or not pf_dist.is_dir():
+        print("Error: pennyfarthing-dist not found")
+        print("       End-user projects should use: pf setup")
+        return 1
+
+    git_dir = project_root / ".git"
+    if not git_dir.is_dir():
+        print("Error: Not a git repository")
+        return 1
+
+    hooks_source = pf_dist / "scripts" / "hooks"
+    hooks_dest = git_dir / "hooks"
+    hooks_dest.mkdir(exist_ok=True)
+
+    dispatcher_template = hooks_source / "dispatcher-template.sh"
+    if not dispatcher_template.is_file():
+        print(f"Error: dispatcher-template.sh not found at {dispatcher_template}")
+        return 1
+
+    print("Installing git hooks with .d/ dispatcher pattern...")
+    print("  Source: pennyfarthing-dist/scripts/hooks/")
+    print("  Dest:   .git/hooks/")
+    print()
+
+    for source_file, dest_name in HOOKS:
+        source_path = hooks_source / source_file
+        dest_path = hooks_dest / dest_name
+        d_dir = hooks_dest / f"{dest_name}.d"
+        pf_hook_name = f"{PF_PREFIX}-pennyfarthing-{dest_name}.sh"
+        pf_hook_path = d_dir / pf_hook_name
+
+        if not source_path.is_file():
+            print(f"  SKIP {dest_name} (source not found)")
+            continue
+
+        # Create .d/ directory
+        d_dir.mkdir(exist_ok=True)
+
+        # Handle existing hook at dest path
+        if dest_path.exists():
+            if dest_path.is_file():
+                content = dest_path.read_text()
+                if DISPATCHER_MARKER in content:
+                    print(f"  OK   {dest_name} dispatcher (already installed)")
+                elif dest_path.is_symlink():
+                    # Old-style symlink — replace with dispatcher
+                    dest_path.unlink()
+                    dest_path.write_text(_generate_dispatcher(dispatcher_template, dest_name))
+                    dest_path.chmod(0o755)
+                    print(f"  UPD  {dest_name} -> dispatcher")
+                elif "pennyfarthing" in content:
+                    # Old pennyfarthing single-file hook — replace
+                    dest_path.write_text(_generate_dispatcher(dispatcher_template, dest_name))
+                    dest_path.chmod(0o755)
+                    print(f"  UPD  {dest_name} -> dispatcher (was single-file pf hook)")
+                else:
+                    # Non-pennyfarthing hook — migrate into .d/
+                    migrated_name = f"{MIGRATED_PREFIX}-migrated-{dest_name}.sh"
+                    migrated_path = d_dir / migrated_name
+                    if not migrated_path.exists():
+                        dest_path.rename(migrated_path)
+                        migrated_path.chmod(0o755)
+                        print(f"  MIG  {dest_name} -> {dest_name}.d/{migrated_name}")
+                    dest_path.write_text(_generate_dispatcher(dispatcher_template, dest_name))
+                    dest_path.chmod(0o755)
+                    print(f"  NEW  {dest_name} dispatcher")
+            elif dest_path.is_symlink():
+                dest_path.unlink()
+                dest_path.write_text(_generate_dispatcher(dispatcher_template, dest_name))
+                dest_path.chmod(0o755)
+                print(f"  UPD  {dest_name} -> dispatcher")
+        else:
+            # No existing hook — install fresh dispatcher
+            dest_path.write_text(_generate_dispatcher(dispatcher_template, dest_name))
+            dest_path.chmod(0o755)
+            print(f"  NEW  {dest_name} dispatcher")
+
+        # Symlink pennyfarthing hook into .d/
+        # Compute relative path from .git/hooks/{hook}.d/ to the hooks source
+        relative_path = Path(os.path.relpath(hooks_source / source_file, d_dir))
+
+        if pf_hook_path.is_symlink():
+            current_target = pf_hook_path.readlink()
+            if current_target == relative_path:
+                print(f"  OK   {dest_name}.d/{pf_hook_name} (already linked)")
+            else:
+                pf_hook_path.unlink()
+                pf_hook_path.symlink_to(relative_path)
+                print(f"  UPD  {dest_name}.d/{pf_hook_name} -> {relative_path}")
+        elif pf_hook_path.is_file():
+            pf_hook_path.unlink()
+            pf_hook_path.symlink_to(relative_path)
+            print(f"  UPD  {dest_name}.d/{pf_hook_name} -> {relative_path} (was copy)")
+        else:
+            pf_hook_path.symlink_to(relative_path)
+            print(f"  NEW  {dest_name}.d/{pf_hook_name} -> {relative_path}")
+
+    print()
+    print("Done. Verify with: ls -la .git/hooks/*.d/")
+    return 0

package/pennyfarthing-dist/src/pf/handoff/gate_file.py

@@ -0,0 +1,109 @@
+"""Gate file discovery and resolution.
+
+Resolves gate file references (e.g., "gates/tests-pass") to actual file paths.
+Resolution order:
+  1. .pennyfarthing/gates/{name}.md  (project-local override)
+  2. pennyfarthing-dist/gates/{name}.md  (built-in fallback)
+
+Non-existent files return an error result with status "blocked".
+
+Story: 106-4 (Gate File Discovery and Resolution)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pf.common.config import get_dist_root
+
+
+def resolve_gate_file(
+    gate_ref: str,
+    project_root: Path | None = None,
+) -> dict:
+    """Resolve a gate file reference to an absolute file path.
+
+    Args:
+        gate_ref: Gate reference string (e.g., "gates/tests-pass" or "tests-pass")
+        project_root: Project root path. Auto-detected if None.
+
+    Returns:
+        dict with keys:
+            status: "found" | "not_found"
+            path: str | None  (absolute path if found)
+            error: str | None (error message if not found)
+    """
+    if project_root is None:
+        project_root = _find_project_root()
+
+    name = _sanitize_gate_name(gate_ref)
+    if name is None:
+        return _result(
+            status="not_found",
+            error=f"Invalid gate reference: {gate_ref!r}",
+        )
+
+    # Resolution order: local first, built-in fallback
+    search_paths = [
+        project_root / ".pennyfarthing" / "gates" / f"{name}.md",
+    ]
+    dist_root = get_dist_root(project_root=project_root)
+    if dist_root:
+        search_paths.append(dist_root / "gates" / f"{name}.md")
+
+    for candidate in search_paths:
+        if candidate.is_file():
+            return _result(status="found", path=str(candidate.resolve()))
+
+    return _result(
+        status="not_found",
+        error=f"Gate file not found: {name}",
+    )
+
+
+def _sanitize_gate_name(gate_ref: str) -> str | None:
+    """Extract a clean gate name from a reference string.
+
+    Strips 'gates/' prefix and '.md' suffix. Rejects empty names
+    and path traversal attempts.
+    """
+    if not gate_ref:
+        return None
+
+    name = gate_ref
+    # Strip gates/ prefix
+    if name.startswith("gates/"):
+        name = name[len("gates/"):]
+    # Strip .md suffix
+    if name.endswith(".md"):
+        name = name[: -len(".md")]
+
+    if not name:
+        return None
+
+    # Reject path traversal
+    if ".." in name or "/" in name:
+        return None
+
+    return name
+
+
+def _result(
+    status: str,
+    path: str | None = None,
+    error: str | None = None,
+) -> dict:
+    return {
+        "status": status,
+        "path": path,
+        "error": error,
+    }
+
+
+def _find_project_root() -> Path:
+    """Walk up from cwd looking for .pennyfarthing/ directory."""
+    cwd = Path.cwd()
+    for parent in [cwd, *cwd.parents]:
+        if (parent / ".pennyfarthing").is_dir():
+            return parent
+    return cwd