@pennyfarthing/core 11.3.3 → 11.3.4

package/pennyfarthing_scripts/hooks/schema_validation.py

@@ -1,202 +0,0 @@
-"""
-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 pennyfarthing_scripts.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_scripts/hooks/session_start.py

@@ -1,294 +0,0 @@
-"""
-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 pennyfarthing_scripts.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 pennyfarthing_scripts.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 pennyfarthing_scripts.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()

package/pennyfarthing_scripts/hooks/sprint_yaml_validation.py

@@ -1,97 +0,0 @@
-"""
-Sprint YAML validation hook (PostToolUse) — validate sprint YAML after edits.
-
-Validates that sprint YAML files are compatible with the yaml npm package
-used by Cyclist's SprintPanel (strict YAML 1.2). When validation fails,
-returns additionalContext prompting the agent to fix the format.
-"""
-
-from __future__ import annotations
-
-import json
-import re
-import subprocess
-import sys
-
-from pennyfarthing_scripts.hooks import (
-    HookResponse,
-    output_hook_response,
-)
-
-
-def main() -> None:
-    """Main entry point for sprint YAML validation hook."""
-    try:
-        raw = sys.stdin.read()
-        try:
-            input_data = json.loads(raw)
-        except (json.JSONDecodeError, ValueError):
-            sys.exit(0)
-
-        tool_name = input_data.get("tool_name", "")
-        tool_input = input_data.get("tool_input", {})
-        file_path = tool_input.get("file_path", "")
-
-        # Only process Edit/Write on sprint YAML files
-        if tool_name not in ("Edit", "Write"):
-            sys.exit(0)
-
-        if not re.search(r'sprint/.*\.(yaml|yml)$', file_path):
-            sys.exit(0)
-
-        from pathlib import Path
-        if not Path(file_path).is_file():
-            sys.exit(0)
-
-        # Validate using Node.js yaml package (same parser Cyclist uses)
-        validation_script = """
-import { parse } from 'yaml';
-import { readFileSync } from 'fs';
-try {
-  const content = readFileSync(process.argv[1], 'utf-8');
-  parse(content);
-  process.exit(0);
-} catch (e) {
-  console.error(e.message);
-  process.exit(1);
-}
-"""
-        try:
-            result = subprocess.run(
-                ["node", "--input-type=module", "-e", validation_script, file_path],
-                capture_output=True,
-                text=True,
-                timeout=10,
-            )
-        except (subprocess.TimeoutExpired, FileNotFoundError):
-            sys.exit(0)
-
-        if result.returncode == 0:
-            sys.exit(0)
-
-        # Validation failed
-        error_text = result.stderr.strip().replace('"', '\\"').replace('\n', ' ')
-        escaped_path = file_path.replace('"', '\\"')
-
-        output_hook_response(HookResponse(
-            event_name="PostToolUse",
-            additional_context=(
-                f"SPRINT YAML VALIDATION FAILED\n\n"
-                f"File: {escaped_path}\n"
-                f"Error: {error_text}\n\n"
-                f"The sprint YAML file has invalid syntax that will break the Cyclist SprintPanel.\n\n"
-                f"Common fix: Single-quoted strings cannot contain blank lines in YAML 1.2.\n"
-                f"Use literal block scalars (|) for multiline strings instead."
-            ),
-        ))
-
-    except SystemExit:
-        raise
-    except Exception:
-        pass
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()