@pennyfarthing/core 11.3.2 → 11.3.4

package/pennyfarthing-dist/pf/hooks/cyclist_pretooluse.py

@@ -0,0 +1,129 @@
+"""
+Cyclist PreToolUse Hook — route tool approval through WheelHub.
+
+When Cyclist is running, sends approval requests to WheelHub's /api/hook-request
+endpoint. Falls back to Claude Code's built-in permissions when Cyclist is not active.
+
+Consolidates pretooluse_hook.py into the hooks subpackage.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from pf.hooks import (
+    HookResponse,
+    find_project_root,
+    get_context_state,
+    is_cyclist_running,
+    load_settings,
+    output_hook_response,
+    read_stdin_json,
+    send_to_cyclist,
+)
+
+
+def _resolve_agent(session_id: str | None, project_root: Path | None) -> str | None:
+    """Resolve agent name from session file."""
+    if not project_root:
+        return None
+
+    agents_dir = project_root / ".session" / "agents"
+    if not agents_dir.is_dir():
+        return None
+
+    if session_id:
+        agent_file = agents_dir / session_id
+        if agent_file.is_file():
+            try:
+                return agent_file.read_text().strip() or None
+            except OSError:
+                pass
+
+    try:
+        agent_files = sorted(
+            (f for f in agents_dir.iterdir() if f.is_file()),
+            key=lambda f: f.stat().st_mtime,
+            reverse=True,
+        )
+        if agent_files:
+            return agent_files[0].read_text().strip() or None
+    except OSError:
+        pass
+
+    return None
+
+
+def main() -> None:
+    """Main entry point for PreToolUse hook."""
+    try:
+        tool_data = read_stdin_json()
+        tool_name = tool_data.get("tool_name", "")
+        tool_id = tool_data.get("tool_use_id", "")
+        tool_input = tool_data.get("tool_input", {})
+        session_id = tool_data.get("session_id")
+
+        project_root = find_project_root()
+        agent_name = _resolve_agent(session_id, project_root)
+
+        if not is_cyclist_running(project_root):
+            sys.exit(0)
+
+        settings = load_settings(project_root)
+        if settings.permission_mode == "accept":
+            output_hook_response(HookResponse(
+                event_name="PreToolUse",
+                decision="allow",
+                reason="Auto-accept mode enabled",
+            ))
+            sys.exit(0)
+
+        context = get_context_state(project_root)
+        request_data = {
+            "toolName": tool_name,
+            "toolId": tool_id,
+            "input": tool_input,
+            "sessionId": session_id,
+            "context": {
+                "percentage": context.percentage,
+                "isHigh": context.is_high,
+                "isCritical": context.is_critical,
+            },
+        }
+        if agent_name:
+            request_data["agent"] = agent_name
+
+        response = send_to_cyclist(
+            endpoint="/api/hook-request",
+            data=request_data,
+            project_root=project_root,
+        )
+
+        if response is None:
+            output_hook_response(HookResponse(
+                event_name="PreToolUse",
+                decision="ask",
+                reason="Could not connect to WheelHub",
+            ))
+            sys.exit(0)
+
+        decision = response.get("decision", "ask")
+        reason = response.get("reason", "")
+        data = response.get("data")
+
+        output_hook_response(HookResponse(
+            event_name="PreToolUse",
+            decision=decision,
+            reason=reason,
+            updated_input=data,
+        ))
+        sys.exit(0)
+
+    except Exception as e:
+        print(f"[pretooluse-hook] Error: {e}", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/pennyfarthing-dist/pf/hooks/schema_validation.py

@@ -0,0 +1,202 @@
+"""
+Schema validation hook (PreToolUse) — validate XML schema on Write operations.
+
+Validates session, skill, and workflow step files to ensure they have
+required tags and attributes. Blocks the Write if validation fails.
+
+Consolidates schema_validation_hook.py into the hooks subpackage.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+
+from pf.hooks import (
+    HookResponse,
+    output_hook_response,
+    read_stdin_json,
+)
+
+# =============================================================================
+# File Type Detection
+# =============================================================================
+
+SKILL_REQUIRED_TAGS = ["run", "output"]
+STEP_REQUIRED_TAGS = ["purpose", "instructions", "output"]
+STEP_META_FIELDS = ["step", "workflow", "agent", "next"]
+
+
+def _is_session_file(file_path: str) -> bool:
+    return file_path.endswith("-session.md") and ".session/" in file_path
+
+
+def _is_skill_file(file_path: str) -> bool:
+    return file_path.endswith("/SKILL.md") and "/skills/" in file_path
+
+
+def _is_step_file(file_path: str) -> bool:
+    from pathlib import Path
+    path = Path(file_path)
+    return (
+        path.name.startswith("step-")
+        and path.name.endswith(".md")
+        and "/workflows/" in file_path
+        and "/steps/" in file_path
+    )
+
+
+def _get_file_type(file_path: str) -> str | None:
+    if _is_session_file(file_path):
+        return "session"
+    elif _is_skill_file(file_path):
+        return "skill"
+    elif _is_step_file(file_path):
+        return "step"
+    return None
+
+
+def _has_tag(content: str, tag: str) -> bool:
+    return f"<{tag}>" in content or f"<{tag} " in content
+
+
+def _validate_session(content: str) -> list[str]:
+    errors = []
+    if "<session" not in content:
+        return []  # Old markdown format — warn but don't block
+    if not re.search(r'<session\s+story="[^"]+"', content):
+        errors.append("Missing story attribute on <session>")
+    if not re.search(r'<session[^>]+workflow="[^"]+"', content):
+        errors.append("Missing workflow attribute on <session>")
+    if not _has_tag(content, "meta"):
+        errors.append("Missing <meta> section")
+    else:
+        if "<jira>" not in content:
+            errors.append("Missing <jira> in <meta>")
+        if "<started>" not in content:
+            errors.append("Missing <started> in <meta>")
+    if not _has_tag(content, "status"):
+        errors.append("Missing <status> element")
+    elif 'phase="' not in content:
+        errors.append("Missing phase attribute on <status>")
+    return errors
+
+
+def _validate_skill(content: str) -> list[str]:
+    errors = []
+    if not content.startswith("---\n"):
+        errors.append("Missing YAML frontmatter")
+    else:
+        parts = content.split("---", 2)
+        if len(parts) >= 2:
+            frontmatter = parts[1]
+            if "name:" not in frontmatter:
+                errors.append("Missing 'name' in frontmatter")
+            if "description:" not in frontmatter:
+                errors.append("Missing 'description' in frontmatter")
+    for tag in SKILL_REQUIRED_TAGS:
+        if not _has_tag(content, tag):
+            errors.append(f"Missing <{tag}> tag (required)")
+    return errors
+
+
+def _validate_step(content: str) -> list[str]:
+    errors = []
+    for tag in STEP_REQUIRED_TAGS:
+        if not _has_tag(content, tag):
+            errors.append(f"Missing <{tag}> tag")
+    if _has_tag(content, "step-meta"):
+        meta_match = re.search(r"<step-meta>(.+?)</step-meta>", content, re.DOTALL)
+        if meta_match:
+            meta_content = meta_match.group(1)
+            for field_name in STEP_META_FIELDS:
+                if f"{field_name}:" not in meta_content:
+                    errors.append(f"Missing '{field_name}' in step-meta")
+    return errors
+
+
+def _validate_content(file_path: str, content: str) -> list[str]:
+    file_type = _get_file_type(file_path)
+    if file_type == "session":
+        return _validate_session(content)
+    elif file_type == "skill":
+        return _validate_skill(content)
+    elif file_type == "step":
+        return _validate_step(content)
+    return []
+
+
+# =============================================================================
+# Entry Point
+# =============================================================================
+
+
+def main() -> None:
+    """Main entry point for schema validation hook."""
+    try:
+        tool_data = read_stdin_json()
+        tool_name = tool_data.get("tool_name", "")
+        tool_input = tool_data.get("tool_input", {})
+
+        if tool_name not in ("Write", "Edit"):
+            output_hook_response(HookResponse(
+                event_name="PreToolUse",
+                decision="allow",
+                reason="Not a Write/Edit operation",
+            ))
+            sys.exit(0)
+
+        file_path = tool_input.get("file_path", "")
+        if not file_path:
+            output_hook_response(HookResponse(
+                event_name="PreToolUse",
+                decision="allow",
+                reason="No file path",
+            ))
+            sys.exit(0)
+
+        file_type = _get_file_type(file_path)
+        if not file_type:
+            output_hook_response(HookResponse(
+                event_name="PreToolUse",
+                decision="allow",
+                reason="Not a session/skill/step file",
+            ))
+            sys.exit(0)
+
+        if tool_name == "Write":
+            content = tool_input.get("content", "")
+        else:
+            output_hook_response(HookResponse(
+                event_name="PreToolUse",
+                decision="allow",
+                reason="Edit operations validated post-hoc",
+            ))
+            sys.exit(0)
+
+        errors = _validate_content(file_path, content)
+        if errors:
+            error_msg = f"Schema validation failed for {file_type} file:\n"
+            error_msg += "\n".join(f"  - {e}" for e in errors)
+            error_msg += f"\n\nFile: {file_path}"
+            output_hook_response(HookResponse(
+                event_name="PreToolUse",
+                decision="deny",
+                reason=error_msg,
+            ))
+            sys.exit(0)
+
+        output_hook_response(HookResponse(
+            event_name="PreToolUse",
+            decision="allow",
+            reason=f"Schema validation passed for {file_type} file",
+        ))
+        sys.exit(0)
+
+    except Exception as e:
+        print(f"[schema-validation-hook] Error: {e}", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/pennyfarthing-dist/pf/hooks/session_start.py

@@ -0,0 +1,294 @@
+"""
+SessionStart hook — initialize environment for Claude Code session.
+
+Consolidates session_start_hook.py and welcome_hook.py into a single module.
+
+Handles:
+1. Session directory setup and logging
+2. Checkpoint validation (cross-session drift detection)
+3. WheelHub auto-start (ensure BikeRack server is running)
+4. OTEL auto-configuration via CLAUDE_ENV_FILE
+5. Welcome message display (CLI ASCII art or Cyclist API)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pf.hooks import (
+    is_cyclist_running,
+    load_settings,
+    send_to_cyclist,
+)
+
+# =============================================================================
+# Session Setup
+# =============================================================================
+
+
+def _read_input() -> dict:
+    """Read JSON from stdin (hook protocol)."""
+    raw = sys.stdin.read()
+    try:
+        return json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return {}
+
+
+def _setup_session_dir(project_dir: Path, session_id: str, source_type: str) -> None:
+    """Ensure .session directory exists and log session start."""
+    session_dir = project_dir / ".session"
+    session_dir.mkdir(parents=True, exist_ok=True)
+    (session_dir / "agents").mkdir(exist_ok=True)
+
+    timestamp = datetime.now(UTC).isoformat()
+    log_file = session_dir / "session-log.txt"
+    with open(log_file, "a") as f:
+        f.write(f"{timestamp} | Session {source_type}: {session_id}\n")
+
+
+# =============================================================================
+# Checkpoint Validation
+# =============================================================================
+
+
+def _validate_checkpoint(project_dir: Path) -> None:
+    """Validate previous session checkpoint for cross-session drift detection."""
+    try:
+        checkpoint_file = project_dir / ".session" / "checkpoints.log"
+        if not checkpoint_file.exists():
+            return
+
+        # Read the last session_state checkpoint
+        prev_state = ""
+        with open(checkpoint_file) as f:
+            for line in f:
+                if "|session_state|" in line:
+                    prev_state = line.strip().split("|", 2)[-1] if "|" in line else ""
+
+        if not prev_state:
+            return
+
+        # Parse checkpoint data
+        fields = {}
+        for part in prev_state.split(";"):
+            if "=" in part:
+                k, v = part.split("=", 1)
+                fields[k] = v
+
+        prev_sha = fields.get("sha", "")
+        if not prev_sha:
+            return
+
+        # Get current git SHA
+        result = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            capture_output=True,
+            text=True,
+            cwd=str(project_dir),
+            timeout=5,
+        )
+        current_sha = result.stdout.strip()
+        if not current_sha or current_sha == prev_sha:
+            return
+
+        # Log drift
+        timestamp = datetime.now(UTC).isoformat()
+        session_dir = project_dir / ".session"
+
+        warning = f"CROSS_SESSION_DRIFT: Git changed (was: {prev_sha}, now: {current_sha})"
+        if fields.get("story"):
+            warning += f" | Story: {fields['story']}"
+        if fields.get("agent"):
+            warning += f" | Agent: {fields['agent']}"
+
+        with open(session_dir / "session-log.txt", "a") as f:
+            f.write(f"{timestamp} | {warning}\n")
+
+        drift_entry = f"{timestamp} | prev_sha={prev_sha} | current_sha={current_sha}"
+        for key in ("story", "agent", "phase"):
+            if fields.get(key):
+                drift_entry += f" | {key}={fields[key]}"
+        with open(session_dir / "drift-log.txt", "a") as f:
+            f.write(drift_entry + "\n")
+
+    except Exception:
+        pass
+
+
+# =============================================================================
+# WheelHub Auto-Start
+# =============================================================================
+
+
+def _ensure_wheelhub(project_dir: Path) -> int | None:
+    """Auto-start WheelHub if not already running. Returns port or None."""
+    from pf.bikerack.launcher import (
+        is_already_running,
+        poll_for_port_file,
+        start_wheelhub,
+        write_pid_file,
+    )
+
+    # Skip if full Cyclist is running
+    cyclist_port_file = project_dir / ".bikerack-port"
+    if cyclist_port_file.exists():
+        try:
+            return int(cyclist_port_file.read_text().strip())
+        except (ValueError, OSError):
+            return None
+
+    # Check if BikeRack WheelHub is already running
+    running, _pid, port = is_already_running(project_dir)
+    if running:
+        return port
+
+    # Start WheelHub
+    try:
+        proc = start_wheelhub(project_dir)
+        write_pid_file(project_dir, proc.pid)
+        return poll_for_port_file(project_dir)
+    except Exception:
+        return None
+
+
+# =============================================================================
+# Environment File
+# =============================================================================
+
+
+def _write_env_file(project_dir: Path, session_id: str, otel_port: int | None) -> None:
+    """Write environment variables to CLAUDE_ENV_FILE."""
+    env_file = os.environ.get("CLAUDE_ENV_FILE")
+    if not env_file:
+        return
+
+    lines = [
+        "# Pennyfarthing core environment",
+        f'export PROJECT_ROOT="{project_dir}"',
+        f'export SESSION_ID="{session_id}"',
+    ]
+
+    if otel_port is not None:
+        from pf.bikerack.launcher import build_otel_env
+
+        lines.append("# OTEL auto-configuration for Cyclist/WheelHub")
+        for key, value in build_otel_env(otel_port).items():
+            lines.append(f'export {key}="{value}"')
+
+    with open(env_file, "a") as f:
+        f.write("\n".join(lines) + "\n")
+
+
+# =============================================================================
+# Welcome Message
+# =============================================================================
+
+
+def _get_welcome_lock_path(project_root: Path) -> Path:
+    """Get path to welcome shown lock file."""
+    session_id = os.environ.get("CLAUDE_SESSION_ID", str(os.getpid()))
+    session_dir = project_root / ".session"
+    session_dir.mkdir(parents=True, exist_ok=True)
+    return session_dir / f".welcome-shown-{session_id}"
+
+
+def _get_project_name(project_root: Path) -> str:
+    """Get project name from package.json or directory name."""
+    package_json = project_root / "package.json"
+    if package_json.exists():
+        try:
+            with open(package_json) as f:
+                data = json.load(f)
+                name = data.get("name")
+                if name:
+                    return name
+        except (json.JSONDecodeError, OSError):
+            pass
+    return project_root.name
+
+
+def _display_cli_welcome(project_name: str, theme: str | None) -> None:
+    """Display ASCII art welcome for CLI mode."""
+    print("""
+       ___
+      /   \\
+     |     |     Welcome to
+     |     |    \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
+      \\___/     \u2551   \u2554\u2550\u2557\u2554\u2550\u2557\u2554\u2557\u2554\u2554\u2557\u2554\u2566\u2550\u2557\u2554\u2550\u2557\u2554\u2550\u2557\u2554\u2550\u2557\u2566\u2554\u2550\u2557   \u2551
+        \u2551       \u2551   \u2560\u2550\u2569\u2551\u2563 \u2551\u2551\u2551\u2551\u2551\u2551 \u2560\u2563 \u2560\u2550\u2563\u2560\u2566\u2569 \u2551 \u2560\u2550\u2563   \u2551
+        \u2551       \u2551   \u2569  \u255a\u2550\u255d\u255d\u255a\u255d\u255d\u255a\u255d\u2569  \u2569 \u2569\u2569\u255a\u2550 \u2569 \u2569 \u2569   \u2551
+      \u2554\u2550\u2569\u2550\u2557     \u255a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255d
+     /     \\
+    \u2502   O   \u2502   Agent-powered development with style
+     \\     /
+      \u255a\u2550\u2550\u2550\u255d
+""")
+
+    if project_name:
+        print(f"    Project: {project_name}")
+    if theme:
+        print(f"    Theme:   {theme}")
+    print()
+
+
+def _show_welcome(project_dir: Path) -> None:
+    """Show welcome message (once per session)."""
+    lock_path = _get_welcome_lock_path(project_dir)
+    if lock_path.exists():
+        return
+
+    lock_path.touch()
+
+    project_name = _get_project_name(project_dir)
+    settings = load_settings(project_dir)
+    theme = settings.theme
+
+    if is_cyclist_running(project_dir):
+        try:
+            send_to_cyclist(
+                endpoint="/api/welcome",
+                data={"project": project_name or "", "theme": theme or ""},
+                project_root=project_dir,
+                timeout=5,
+            )
+        except Exception:
+            pass
+    else:
+        _display_cli_welcome(project_name, theme)
+
+
+# =============================================================================
+# Entry Point
+# =============================================================================
+
+
+def main() -> None:
+    """Entry point for SessionStart hook."""
+    try:
+        input_data = _read_input()
+        session_id = input_data.get("session_id", "unknown")
+        source_type = input_data.get("source", "unknown")
+
+        project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()))
+
+        _setup_session_dir(project_dir, session_id, source_type)
+        _validate_checkpoint(project_dir)
+
+        otel_port = _ensure_wheelhub(project_dir)
+        _write_env_file(project_dir, session_id, otel_port)
+        _show_welcome(project_dir)
+
+    except Exception:
+        pass
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()