@pennyfarthing/core 11.2.0 → 11.2.2

package/pennyfarthing_scripts/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 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/session_stop.py

@@ -0,0 +1,111 @@
+"""
+Session stop hook — save checkpoint for cross-session continuity.
+
+Writes session state (agent, story, phase, git SHA, session ID) to
+checkpoints.log so the next session can detect drift.
+
+Replaces session-stop.sh + checkpoint.sh logic.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+
+def _checkpoint_save(project_dir: Path, label: str, data: str) -> None:
+    """Save a checkpoint entry to checkpoints.log."""
+    try:
+        checkpoint_file = project_dir / ".session" / "checkpoints.log"
+        checkpoint_file.parent.mkdir(parents=True, exist_ok=True)
+        timestamp = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+        with open(checkpoint_file, "a") as f:
+            f.write(f"{timestamp}|{label}|{data}\n")
+    except OSError:
+        pass
+
+
+def main() -> None:
+    """Main entry point for session stop hook."""
+    try:
+        raw = sys.stdin.read()
+        try:
+            input_data = json.loads(raw)
+        except (json.JSONDecodeError, ValueError):
+            input_data = {}
+
+        session_id = input_data.get("session_id", "unknown")
+        project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()))
+
+        # Get current agent
+        agent = ""
+        agent_file = project_dir / ".session" / "agents" / session_id
+        if agent_file.is_file():
+            try:
+                agent = agent_file.read_text().strip()
+            except OSError:
+                pass
+
+        # Find active story from session files
+        story = ""
+        phase = ""
+        session_dir = project_dir / ".session"
+        if session_dir.is_dir():
+            session_files = sorted(
+                session_dir.glob("*-session.md"),
+                key=lambda f: f.stat().st_mtime,
+                reverse=True,
+            )
+            if session_files:
+                session_file = session_files[0]
+                # Extract story ID from filename (e.g., 8-3-session.md -> 8-3)
+                story = re.sub(r'-session\.md$', '', session_file.name)
+                # Extract phase from session file
+                try:
+                    content = session_file.read_text()
+                    phase_match = re.search(r'^- Phase:\s*(\S+)', content, re.MULTILINE | re.IGNORECASE)
+                    if phase_match:
+                        phase = phase_match.group(1)
+                except OSError:
+                    pass
+
+        # Get current git SHA
+        git_sha = ""
+        try:
+            result = subprocess.run(
+                ["git", "rev-parse", "--short", "HEAD"],
+                capture_output=True,
+                text=True,
+                cwd=str(project_dir),
+                timeout=5,
+            )
+            git_sha = result.stdout.strip()
+        except (subprocess.TimeoutExpired, OSError):
+            pass
+
+        # Build and save checkpoint
+        checkpoint_data = f"agent={agent};story={story};phase={phase};sha={git_sha};session={session_id}"
+        _checkpoint_save(project_dir, "session_state", checkpoint_data)
+
+        # Log session end
+        try:
+            timestamp = datetime.now(UTC).isoformat()
+            log_file = session_dir / "session-log.txt"
+            with open(log_file, "a") as f:
+                f.write(f"{timestamp} | Session end: {session_id} (agent={agent}, story={story})\n")
+        except OSError:
+            pass
+
+    except Exception:
+        pass
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/pennyfarthing_scripts/hooks/sprint_yaml_validation.py

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