Session Handoff

#!/usr/bin/env python3
"""
Set up a test environment for evaluating the session-handoff skill.

Creates a mock project with:
- Git repository with commit history
- Sample source files
- Sample handoffs (fresh and stale)

Usage:
    python setup_test_env.py [--path /tmp/handoff-test]
    python setup_test_env.py --clean  # Remove test environment
"""

import argparse
import os
import shutil
import subprocess
from datetime import datetime, timedelta
from pathlib import Path


DEFAULT_TEST_PATH = "/tmp/handoff-eval-project"


def run_cmd(cmd: list[str], cwd: str = None) -> bool:
    """Run a command and return success status."""
    try:
        subprocess.run(cmd, cwd=cwd, capture_output=True, check=True)
        return True
    except subprocess.CalledProcessError:
        return False


def create_test_project(base_path: str):
    """Create a mock project structure."""
    path = Path(base_path)

    # Clean if exists
    if path.exists():
        shutil.rmtree(path)

    # Create directories
    (path / "src").mkdir(parents=True)
    (path / "tests").mkdir()
    (path / "config").mkdir()

    # Create sample files
    (path / "README.md").write_text("""# Test Project

A sample project for testing the session-handoff skill.

## Features
- User authentication
- API endpoints
- Database integration
""")

    (path / "src" / "index.js").write_text("""// Main entry point
const express = require('express');
const app = express();

app.get('/', (req, res) => {
    res.send('Hello World');
});

module.exports = app;
""")

    (path / "src" / "auth.js").write_text("""// Authentication module
const jwt = require('jsonwebtoken');

function validateToken(token) {
    // TODO: Implement token validation
    return true;
}

function generateToken(user) {
    return jwt.sign({ id: user.id }, process.env.JWT_SECRET);
}

module.exports = { validateToken, generateToken };
""")

    (path / "src" / "database.js").write_text("""// Database connection
const mongoose = require('mongoose');

async function connect() {
    await mongoose.connect(process.env.DATABASE_URL);
}

module.exports = { connect };
""")

    (path / "tests" / "auth.test.js").write_text("""// Auth tests
describe('Authentication', () => {
    test('validates tokens', () => {
        expect(true).toBe(true);
    });
});
""")

    (path / "config" / "default.json").write_text("""{
    "port": 3000,
    "database": {
        "host": "localhost",
        "name": "testdb"
    }
}
""")

    (path / "package.json").write_text("""{
    "name": "test-project",
    "version": "1.0.0",
    "main": "src/index.js",
    "scripts": {
        "start": "node src/index.js",
        "test": "jest"
    }
}
""")

    print(f"Created project structure at {path}")
    return path


def init_git_repo(path: Path):
    """Initialize git repo with commit history."""
    # Initialize
    run_cmd(["git", "init"], cwd=str(path))
    run_cmd(["git", "config", "user.email", "test@example.com"], cwd=str(path))
    run_cmd(["git", "config", "user.name", "Test User"], cwd=str(path))

    # Initial commit
    run_cmd(["git", "add", "."], cwd=str(path))
    run_cmd(["git", "commit", "-m", "Initial commit: project setup"], cwd=str(path))

    # Add more commits to simulate history
    commits = [
        ("src/auth.js", "// Added validation logic\n", "Add token validation"),
        ("src/database.js", "// Added connection pooling\n", "Implement connection pooling"),
        ("tests/auth.test.js", "// More tests\n", "Add authentication tests"),
        ("src/index.js", "// Added middleware\n", "Add auth middleware"),
        ("README.md", "\n## API Docs\n", "Update documentation"),
    ]

    for file, content, message in commits:
        file_path = path / file
        with open(file_path, "a") as f:
            f.write(content)
        run_cmd(["git", "add", file], cwd=str(path))
        run_cmd(["git", "commit", "-m", message], cwd=str(path))

    print(f"Initialized git repo with {len(commits) + 1} commits")


def create_sample_handoffs(path: Path):
    """Create sample handoff documents for testing."""
    handoffs_dir = path / ".cursor" / "handoffs"
    handoffs_dir.mkdir(parents=True)

    # Fresh handoff (today)
    now = datetime.now()
    fresh_name = now.strftime("%Y-%m-%d-%H%M%S") + "-auth-implementation.md"
    fresh_content = f"""# Handoff: Implementing User Authentication

## Session Metadata
- Created: {now.strftime("%Y-%m-%d %H:%M:%S")}
- Project: {path}
- Branch: main
- Session duration: 2 hours

## Handoff Chain

- **Continues from**: None (fresh start)
- **Supersedes**: None

## Current State Summary

Working on implementing JWT-based authentication for the API. Successfully added token generation and basic validation. The middleware integration is partially complete.

## Codebase Understanding

### Architecture Overview

Express.js application with modular structure. Auth logic separated into src/auth.js, database connection in src/database.js.

### Critical Files

| File | Purpose | Relevance |
|------|---------|-----------|
| src/auth.js | Authentication logic | Main file being modified |
| src/index.js | App entry point | Needs middleware integration |

### Key Patterns Discovered

- Using environment variables for secrets (JWT_SECRET, DATABASE_URL)
- Jest for testing

## Work Completed

### Tasks Finished

- [x] Set up JWT token generation
- [x] Create basic validation function
- [ ] Integrate middleware (in progress)

### Files Modified

| File | Changes | Rationale |
|------|---------|-----------|
| src/auth.js | Added validateToken, generateToken | Core auth functionality |

### Decisions Made

| Decision | Options Considered | Rationale |
|----------|-------------------|-----------|
| Use JWT over sessions | JWT, Sessions, OAuth | Stateless, scales better for API |

## Pending Work

### Immediate Next Steps

1. Complete middleware integration in src/index.js
2. Add refresh token logic
3. Write comprehensive tests

### Blockers/Open Questions

- [ ] Need to decide on token expiry time (1h vs 24h)

### Deferred Items

- OAuth integration (future sprint)

## Context for Resuming Agent

### Important Context

The validateToken function in src/auth.js currently returns true always - this is a placeholder that needs real implementation. The JWT_SECRET env var must be set.

### Assumptions Made

- Using HS256 algorithm for JWT
- Tokens should be passed in Authorization header

### Potential Gotchas

- Don't forget to set JWT_SECRET environment variable
- Database connection must be established before auth checks

## Environment State

### Tools/Services Used

- Node.js with Express
- JWT library (jsonwebtoken)

### Active Processes

- None currently running

### Environment Variables

- JWT_SECRET
- DATABASE_URL

## Related Resources

- JWT documentation: https://jwt.io
- Express middleware guide
"""
    (handoffs_dir / fresh_name).write_text(fresh_content)

    # Stale handoff (2 weeks ago)
    old_date = now - timedelta(days=14)
    stale_name = old_date.strftime("%Y-%m-%d-%H%M%S") + "-database-setup.md"
    stale_content = f"""# Handoff: Database Setup

## Session Metadata
- Created: {old_date.strftime("%Y-%m-%d %H:%M:%S")}
- Project: {path}
- Branch: main
- Session duration: 1 hour

## Handoff Chain

- **Continues from**: None (fresh start)
- **Supersedes**: None

## Current State Summary

Set up initial database connection with MongoDB. Basic schema defined but not fully implemented.

## Codebase Understanding

### Architecture Overview

MongoDB database with Mongoose ODM.

### Critical Files

| File | Purpose | Relevance |
|------|---------|-----------|
| src/database.js | DB connection | Main database file |
| src/old-file.js | Legacy code | Was being refactored |

## Pending Work

### Immediate Next Steps

1. Define user schema
2. Add connection pooling
3. Implement error handling

## Context for Resuming Agent

### Important Context

Using MongoDB Atlas for hosting. Connection string in DATABASE_URL.

### Assumptions Made

- MongoDB version 5.x
- Mongoose 7.x

## Environment State

### Environment Variables

- DATABASE_URL
"""
    (handoffs_dir / stale_name).write_text(stale_content)

    # Incomplete handoff (with TODOs)
    incomplete_name = now.strftime("%Y-%m-%d-%H%M%S") + "-incomplete-test.md"
    incomplete_content = f"""# Handoff: [TASK_TITLE - replace this]

## Session Metadata
- Created: {now.strftime("%Y-%m-%d %H:%M:%S")}
- Project: {path}
- Branch: main
- Session duration: [estimate how long you worked]

## Current State Summary

[TODO: Write one paragraph describing what was being worked on]

## Codebase Understanding

### Architecture Overview

[TODO: Document key architectural insights]

## Pending Work

### Immediate Next Steps

1. [TODO: Most critical next action]
2. [TODO: Second priority]

## Context for Resuming Agent

### Important Context

[TODO: This is the MOST IMPORTANT section]
"""
    (handoffs_dir / incomplete_name).write_text(incomplete_content)

    print(f"Created 3 sample handoffs:")
    print(f"  - {fresh_name} (fresh)")
    print(f"  - {stale_name} (stale, 14 days old)")
    print(f"  - {incomplete_name} (incomplete, has TODOs)")


def clean_test_env(path: str):
    """Remove test environment."""
    if Path(path).exists():
        shutil.rmtree(path)
        print(f"Cleaned up test environment at {path}")
    else:
        print(f"No test environment found at {path}")


def main():
    parser = argparse.ArgumentParser(
        description="Set up test environment for session-handoff skill"
    )
    parser.add_argument(
        "--path",
        default=DEFAULT_TEST_PATH,
        help=f"Path for test project (default: {DEFAULT_TEST_PATH})"
    )
    parser.add_argument(
        "--clean",
        action="store_true",
        help="Remove test environment instead of creating"
    )

    args = parser.parse_args()

    if args.clean:
        clean_test_env(args.path)
    else:
        path = create_test_project(args.path)
        init_git_repo(path)
        create_sample_handoffs(path)
        print(f"\nTest environment ready at: {args.path}")
        print(f"\nTo test, run:")
        print(f"  cd {args.path}")
        print(f"  # Then use coding agent with the session-handoff skill")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Check staleness of a handoff document compared to current project state.

Analyzes:
- Time since handoff was created
- Git commits since handoff
- Files that changed since handoff
- Branch divergence
- Modified files status

Usage:
    python check_staleness.py <handoff-file>
    python check_staleness.py .cursor/handoffs/2024-01-15-143022-auth.md
"""

import os
import re
import subprocess
import sys
from datetime import datetime
from pathlib import Path


def run_cmd(cmd: list[str], cwd: str = None) -> tuple[bool, str]:
    """Run a command and return (success, output)."""
    try:
        result = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            cwd=cwd,
            timeout=10
        )
        return result.returncode == 0, result.stdout.strip()
    except (subprocess.TimeoutExpired, FileNotFoundError):
        return False, ""


def parse_handoff_metadata(filepath: str) -> dict:
    """Extract metadata from a handoff file."""
    content = Path(filepath).read_text()
    metadata = {
        "created": None,
        "branch": None,
        "project_path": None,
        "modified_files": [],
    }

    # Parse Created timestamp
    match = re.search(r'Created:\s*(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2})', content)
    if match:
        try:
            metadata["created"] = datetime.strptime(match.group(1), "%Y-%m-%d %H:%M:%S")
        except ValueError:
            pass

    # Parse Branch
    match = re.search(r'Branch:\s*(\S+)', content)
    if match:
        branch = match.group(1)
        if branch and not branch.startswith('['):
            metadata["branch"] = branch

    # Parse Project path
    match = re.search(r'Project:\s*(.+?)(?:\n|$)', content)
    if match:
        metadata["project_path"] = match.group(1).strip()

    # Parse modified files from table
    table_matches = re.findall(r'\|\s*([a-zA-Z0-9_\-./]+\.[a-zA-Z]+)\s*\|', content)
    for f in table_matches:
        if '/' in f and not f.startswith('['):
            metadata["modified_files"].append(f)

    return metadata


def get_commits_since(timestamp: datetime, project_path: str) -> list[str]:
    """Get list of commits since a given timestamp."""
    if not timestamp:
        return []

    iso_time = timestamp.strftime("%Y-%m-%dT%H:%M:%S")
    success, output = run_cmd(
        ["git", "log", f"--since={iso_time}", "--oneline", "--no-decorate"],
        cwd=project_path
    )

    if success and output:
        return output.split("\n")
    return []


def get_current_branch(project_path: str) -> str | None:
    """Get current git branch."""
    success, branch = run_cmd(
        ["git", "branch", "--show-current"],
        cwd=project_path
    )
    return branch if success else None


def get_changed_files_since(timestamp: datetime, project_path: str) -> list[str]:
    """Get files that changed since timestamp."""
    if not timestamp:
        return []

    iso_time = timestamp.strftime("%Y-%m-%dT%H:%M:%S")
    success, output = run_cmd(
        ["git", "diff", "--name-only", f"--since={iso_time}", "HEAD"],
        cwd=project_path
    )

    # Fallback: get files changed in commits since timestamp
    if not output:
        success, output = run_cmd(
            ["git", "log", f"--since={iso_time}", "--name-only", "--pretty=format:"],
            cwd=project_path
        )

    if success and output:
        files = [f.strip() for f in output.split("\n") if f.strip()]
        return list(set(files))  # Deduplicate
    return []


def check_files_exist(files: list[str], project_path: str) -> tuple[list[str], list[str]]:
    """Check which files from handoff still exist."""
    existing = []
    missing = []

    for f in files:
        full_path = Path(project_path) / f
        if full_path.exists():
            existing.append(f)
        else:
            missing.append(f)

    return existing, missing


def calculate_staleness_level(
    days_old: float,
    commits_since: int,
    files_changed: int,
    branch_matches: bool,
    files_missing: int
) -> tuple[str, str, list[str]]:
    """Calculate staleness level and provide recommendations.

    Staleness scoring rationale:
    - Each factor adds 1-3 points based on severity
    - Thresholds based on typical development patterns:
      - Age: 1 day (active work), 7 days (sprint), 30 days (stale)
      - Commits: 5 (minor changes), 20 (feature work), 50 (major changes)
      - Files: 5 (localized), 20 (widespread changes)
    - Final score: 0=FRESH, 1-2=SLIGHTLY_STALE, 3-4=STALE, 5+=VERY_STALE
    """
    issues = []

    # Scoring
    staleness_score = 0

    # Age thresholds: 1 day = active, 7 days = sprint boundary, 30 days = likely stale
    if days_old > 30:
        staleness_score += 3  # Over a month: high risk of outdated context
        issues.append(f"Handoff is {int(days_old)} days old")
    elif days_old > 7:
        staleness_score += 2  # Over a week: moderate staleness
        issues.append(f"Handoff is {int(days_old)} days old")
    elif days_old > 1:
        staleness_score += 1  # Over a day: minor staleness

    # Commit thresholds: 5 = routine, 20 = feature work, 50 = major development
    if commits_since > 50:
        staleness_score += 3  # Major changes likely invalidate handoff context
        issues.append(f"{commits_since} commits since handoff - significant changes")
    elif commits_since > 20:
        staleness_score += 2  # Substantial work done since handoff
        issues.append(f"{commits_since} commits since handoff")
    elif commits_since > 5:
        staleness_score += 1  # Some changes, worth reviewing

    # Branch mismatch: likely working on different feature/context
    if not branch_matches:
        staleness_score += 2  # Different branch = different context
        issues.append("Current branch differs from handoff branch")

    # Missing files: 5+ suggests significant restructuring
    if files_missing > 5:
        staleness_score += 2  # Many refs broken = codebase restructured
        issues.append(f"{files_missing} referenced files no longer exist")
    elif files_missing > 0:
        staleness_score += 1  # Some refs broken
        issues.append(f"{files_missing} referenced file(s) missing")

    # Changed files: 5 = localized, 20 = widespread
    if files_changed > 20:
        staleness_score += 2  # Widespread changes affect handoff relevance
        issues.append(f"{files_changed} files changed since handoff")
    elif files_changed > 5:
        staleness_score += 1  # Some files changed

    # Staleness levels: 0=fresh, 1-2=slight, 3-4=stale, 5+=very stale
    if staleness_score == 0:
        level = "FRESH"
        recommendation = "Safe to resume - minimal changes since handoff"
    elif staleness_score <= 2:
        level = "SLIGHTLY_STALE"
        recommendation = "Generally safe to resume - review changes before continuing"
    elif staleness_score <= 4:
        level = "STALE"
        recommendation = "Proceed with caution - significant changes may affect context"
    else:
        level = "VERY_STALE"
        recommendation = "Consider creating new handoff - too many changes since original"

    return level, recommendation, issues


def check_staleness(handoff_path: str) -> dict:
    """Run staleness check on a handoff file."""
    path = Path(handoff_path)

    if not path.exists():
        return {"error": f"Handoff file not found: {handoff_path}"}

    # Parse handoff
    metadata = parse_handoff_metadata(handoff_path)

    # Determine project path
    project_path = metadata.get("project_path")
    if not project_path or not Path(project_path).exists():
        # Fallback: assume handoff is in .cursor/handoffs/ within project
        project_path = str(path.parent.parent.parent)

    # Check if git repo
    success, _ = run_cmd(["git", "rev-parse", "--git-dir"], cwd=project_path)
    is_git_repo = success

    result = {
        "handoff_file": str(path),
        "project_path": project_path,
        "is_git_repo": is_git_repo,
        "created": metadata["created"],
        "handoff_branch": metadata["branch"],
    }

    # Calculate age
    if metadata["created"]:
        age = datetime.now() - metadata["created"]
        result["days_old"] = age.total_seconds() / 86400
        result["hours_old"] = age.total_seconds() / 3600
    else:
        result["days_old"] = None
        result["hours_old"] = None

    if is_git_repo:
        # Git-based checks
        result["current_branch"] = get_current_branch(project_path)
        result["branch_matches"] = (
            result["current_branch"] == metadata["branch"]
            if metadata["branch"] else True
        )

        commits = get_commits_since(metadata["created"], project_path)
        result["commits_since"] = len(commits)
        result["recent_commits"] = commits[:5]  # Show first 5

        changed_files = get_changed_files_since(metadata["created"], project_path)
        result["files_changed_count"] = len(changed_files)
        result["files_changed"] = changed_files[:10]  # Show first 10

        # Check if handoff's modified files still exist
        existing, missing = check_files_exist(metadata["modified_files"], project_path)
        result["referenced_files_exist"] = len(existing)
        result["referenced_files_missing"] = missing

        # Calculate staleness
        level, recommendation, issues = calculate_staleness_level(
            result.get("days_old", 0) or 0,
            result["commits_since"],
            result["files_changed_count"],
            result["branch_matches"],
            len(missing)
        )
        result["staleness_level"] = level
        result["recommendation"] = recommendation
        result["issues"] = issues
    else:
        # Non-git checks (limited)
        result["staleness_level"] = "UNKNOWN"
        result["recommendation"] = "Not a git repo - unable to detect changes"
        result["issues"] = ["Project is not a git repository"]

    return result


def print_report(result: dict):
    """Print staleness report."""
    if "error" in result:
        print(f"Error: {result['error']}")
        return

    print(f"\n{'='*60}")
    print(f"Handoff Staleness Report")
    print(f"{'='*60}")
    print(f"File: {result['handoff_file']}")
    print(f"Project: {result['project_path']}")

    if result["created"]:
        print(f"Created: {result['created'].strftime('%Y-%m-%d %H:%M:%S')}")
        if result["days_old"] is not None:
            if result["days_old"] < 1:
                print(f"Age: {result['hours_old']:.1f} hours")
            else:
                print(f"Age: {result['days_old']:.1f} days")

    print(f"\n{'='*60}")
    print(f"Staleness Level: {result['staleness_level']}")
    print(f"{'='*60}")
    print(f"\nRecommendation: {result['recommendation']}")

    if result.get("issues"):
        print(f"\nIssues detected:")
        for issue in result["issues"]:
            print(f"  - {issue}")

    if result.get("is_git_repo"):
        print(f"\n--- Git Status ---")
        print(f"Handoff branch: {result.get('handoff_branch', 'Unknown')}")
        print(f"Current branch: {result.get('current_branch', 'Unknown')}")
        print(f"Branch matches: {'Yes' if result.get('branch_matches') else 'No'}")
        print(f"Commits since handoff: {result.get('commits_since', 0)}")
        print(f"Files changed: {result.get('files_changed_count', 0)}")

        if result.get("recent_commits"):
            print(f"\nRecent commits:")
            for commit in result["recent_commits"][:5]:
                print(f"  {commit}")

        if result.get("referenced_files_missing"):
            print(f"\nMissing referenced files:")
            for f in result["referenced_files_missing"][:5]:
                print(f"  - {f}")

    print(f"\n{'='*60}")

    # Color-coded verdict (using text indicators)
    level = result.get("staleness_level", "UNKNOWN")
    if level == "FRESH":
        print("Verdict: [OK] Safe to resume")
    elif level == "SLIGHTLY_STALE":
        print("Verdict: [OK] Review changes, then resume")
    elif level == "STALE":
        print("Verdict: [CAUTION] Verify context before resuming")
    elif level == "VERY_STALE":
        print("Verdict: [WARNING] Consider creating fresh handoff")
    else:
        print("Verdict: [UNKNOWN] Manual verification needed")


def main():
    if len(sys.argv) < 2:
        print("Usage: python check_staleness.py <handoff-file>")
        print("Example: python check_staleness.py .cursor/handoffs/2024-01-15-auth.md")
        sys.exit(1)

    handoff_path = sys.argv[1]
    result = check_staleness(handoff_path)
    print_report(result)

    # Exit code based on staleness
    level = result.get("staleness_level", "UNKNOWN")
    if level in ["FRESH", "SLIGHTLY_STALE"]:
        sys.exit(0)
    elif level == "STALE":
        sys.exit(1)
    else:
        sys.exit(2)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Smart scaffold generator for handoff documents.

Creates a new handoff document with auto-detected metadata:
- Current timestamp
- Project path
- Git branch (if available)
- Recent git log
- Modified/staged files
- Handoff chain linking

Usage:
    python create_handoff.py [task-slug] [--continues-from <previous-handoff>]
    python create_handoff.py "implementing-auth"
    python create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md
    python create_handoff.py  # auto-generates slug from timestamp
"""

import argparse
import os
import re
import subprocess
import sys
from datetime import datetime
from pathlib import Path


def run_cmd(cmd: list[str], cwd: str = None) -> tuple[bool, str]:
    """Run a command and return (success, output)."""
    try:
        result = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            cwd=cwd,
            timeout=10
        )
        return result.returncode == 0, result.stdout.strip()
    except (subprocess.TimeoutExpired, FileNotFoundError):
        return False, ""


def get_git_info(project_path: str) -> dict:
    """Gather git information from the project."""
    info = {
        "is_git_repo": False,
        "branch": None,
        "recent_commits": [],
        "modified_files": [],
        "staged_files": [],
    }

    # Check if git repo
    success, _ = run_cmd(["git", "rev-parse", "--git-dir"], cwd=project_path)
    if not success:
        return info

    info["is_git_repo"] = True

    # Get current branch
    success, branch = run_cmd(["git", "branch", "--show-current"], cwd=project_path)
    if success and branch:
        info["branch"] = branch

    # Get recent commits (last 5)
    success, log = run_cmd(
        ["git", "log", "--oneline", "-5", "--no-decorate"],
        cwd=project_path
    )
    if success and log:
        info["recent_commits"] = log.split("\n")

    # Get modified files (unstaged)
    success, modified = run_cmd(
        ["git", "diff", "--name-only"],
        cwd=project_path
    )
    if success and modified:
        info["modified_files"] = modified.split("\n")

    # Get staged files
    success, staged = run_cmd(
        ["git", "diff", "--name-only", "--cached"],
        cwd=project_path
    )
    if success and staged:
        info["staged_files"] = staged.split("\n")

    return info


def find_previous_handoffs(project_path: str) -> list[dict]:
    """Find existing handoffs in the project."""
    handoffs_dir = Path(project_path) / ".cursor" / "handoffs"
    if not handoffs_dir.exists():
        return []

    handoffs = []
    for filepath in handoffs_dir.glob("*.md"):
        # Extract title from file
        try:
            content = filepath.read_text()
            match = re.search(r'^#\s+(?:Handoff:\s*)?(.+)$', content, re.MULTILINE)
            title = match.group(1).strip() if match else filepath.stem
        except Exception:
            title = filepath.stem

        # Parse date from filename
        date_match = re.match(r'(\d{4}-\d{2}-\d{2})-(\d{6})', filepath.name)
        if date_match:
            try:
                date = datetime.strptime(
                    f"{date_match.group(1)} {date_match.group(2)}",
                    "%Y-%m-%d %H%M%S"
                )
            except ValueError:
                date = None
        else:
            date = None

        handoffs.append({
            "filename": filepath.name,
            "path": str(filepath),
            "title": title,
            "date": date,
        })

    # Sort by date, most recent first
    handoffs.sort(key=lambda x: x["date"] or datetime.min, reverse=True)
    return handoffs


def get_previous_handoff_info(project_path: str, continues_from: str = None) -> dict:
    """Get information about the previous handoff for chaining."""
    handoffs = find_previous_handoffs(project_path)

    if continues_from:
        # Find specific handoff
        for h in handoffs:
            if continues_from in h["filename"]:
                return {
                    "exists": True,
                    "filename": h["filename"],
                    "title": h["title"],
                }
        return {"exists": False, "filename": continues_from, "title": "Not found"}

    elif handoffs:
        # Suggest most recent
        most_recent = handoffs[0]
        return {
            "exists": True,
            "filename": most_recent["filename"],
            "title": most_recent["title"],
            "suggested": True,
        }

    return {"exists": False}


def generate_handoff(
    project_path: str,
    slug: str = None,
    continues_from: str = None
) -> str:
    """Generate a handoff document with pre-filled metadata."""

    # Generate timestamp and filename
    now = datetime.now()
    timestamp = now.strftime("%Y-%m-%d %H:%M:%S")
    file_timestamp = now.strftime("%Y-%m-%d-%H%M%S")

    if not slug:
        slug = "handoff"

    # Sanitize slug
    slug = slug.lower().replace(" ", "-").replace("_", "-")
    slug = "".join(c for c in slug if c.isalnum() or c == "-")

    filename = f"{file_timestamp}-{slug}.md"

    # Create handoffs directory
    handoffs_dir = Path(project_path) / ".cursor" / "handoffs"
    handoffs_dir.mkdir(parents=True, exist_ok=True)

    filepath = handoffs_dir / filename

    # Gather git info
    git_info = get_git_info(project_path)

    # Get previous handoff info for chaining
    prev_handoff = get_previous_handoff_info(project_path, continues_from)

    # Build pre-filled sections
    branch_line = git_info["branch"] if git_info["branch"] else "[not a git repo or detached HEAD]"

    # Recent commits section
    if git_info["recent_commits"]:
        commits_section = "\n".join(f"  - {c}" for c in git_info["recent_commits"])
    else:
        commits_section = "  - [no recent commits or not a git repo]"

    # Modified files section
    all_modified = list(set(git_info["modified_files"] + git_info["staged_files"]))
    if all_modified:
        modified_section = "\n".join(f"| {f} | [describe changes] | [why changed] |" for f in all_modified[:10])
        if len(all_modified) > 10:
            modified_section += f"\n| ... and {len(all_modified) - 10} more files | | |"
    else:
        modified_section = "| [no modified files detected] | | |"

    # Handoff chain section
    if prev_handoff.get("exists"):
        chain_section = f"""## Handoff Chain

- **Continues from**: [{prev_handoff['filename']}](./{prev_handoff['filename']})
  - Previous title: {prev_handoff.get('title', 'Unknown')}
- **Supersedes**: [list any older handoffs this replaces, or "None"]

> Review the previous handoff for full context before filling this one."""
    else:
        chain_section = """## Handoff Chain

- **Continues from**: None (fresh start)
- **Supersedes**: None

> This is the first handoff for this task."""

    # Generate the document
    content = f"""# Handoff: [TASK_TITLE - replace this]

## Session Metadata
- Created: {timestamp}
- Project: {project_path}
- Branch: {branch_line}
- Session duration: [estimate how long you worked]

### Recent Commits (for context)
{commits_section}

{chain_section}

## Current State Summary

[TODO: Write one paragraph describing what was being worked on, current status, and where things left off]

## Codebase Understanding

### Architecture Overview

[TODO: Document key architectural insights discovered during this session]

### Critical Files

| File | Purpose | Relevance |
|------|---------|-----------|
| [TODO: Add critical files] | | |

### Key Patterns Discovered

[TODO: Document important patterns, conventions, or idioms found in this codebase]

## Work Completed

### Tasks Finished

- [ ] [TODO: List completed tasks]

### Files Modified

| File | Changes | Rationale |
|------|---------|-----------|
{modified_section}

### Decisions Made

| Decision | Options Considered | Rationale |
|----------|-------------------|-----------|
| [TODO: Document key decisions] | | |

## Pending Work

### Immediate Next Steps

1. [TODO: Most critical next action]
2. [TODO: Second priority]
3. [TODO: Third priority]

### Blockers/Open Questions

- [ ] [TODO: List any blockers or open questions]

### Deferred Items

- [TODO: Items deferred and why]

## Context for Resuming Agent

### Important Context

[TODO: This is the MOST IMPORTANT section - write critical information the next agent MUST know]

### Assumptions Made

- [TODO: List assumptions made during this session]

### Potential Gotchas

- [TODO: Document things that might trip up a new agent]

## Environment State

### Tools/Services Used

- [TODO: List relevant tools and their configuration]

### Active Processes

- [TODO: Note any running processes, servers, etc.]

### Environment Variables

- [TODO: List relevant env var NAMES only - NEVER include actual values/secrets]

## Related Resources

- [TODO: Add links to relevant docs and files]

---

**Security Reminder**: Before finalizing, run `validate_handoff.py` to check for accidental secret exposure.
"""

    # Write the file
    filepath.write_text(content)

    return str(filepath)


def main():
    parser = argparse.ArgumentParser(
        description="Create a new handoff document with smart scaffolding"
    )
    parser.add_argument(
        "slug",
        nargs="?",
        default=None,
        help="Short identifier for the handoff (e.g., 'implementing-auth')"
    )
    parser.add_argument(
        "--continues-from",
        dest="continues_from",
        help="Filename of previous handoff this continues from"
    )

    args = parser.parse_args()

    # Get project path (current working directory)
    project_path = os.getcwd()

    # Check for existing handoffs to suggest chaining
    if not args.continues_from:
        prev_handoffs = find_previous_handoffs(project_path)
        if prev_handoffs:
            print(f"Found {len(prev_handoffs)} existing handoff(s).")
            print(f"Most recent: {prev_handoffs[0]['filename']}")
            print(f"Use --continues-from <filename> to link handoffs.\n")

    # Generate handoff
    filepath = generate_handoff(project_path, args.slug, args.continues_from)

    print(f"Created handoff document: {filepath}")
    print(f"\nNext steps:")
    print(f"1. Open {filepath}")
    print(f"2. Replace [TODO: ...] placeholders with actual content")
    print(f"3. Focus especially on 'Important Context' and 'Immediate Next Steps'")
    print(f"4. Run: python validate_handoff.py {filepath}")
    print(f"   (Checks for completeness and accidental secrets)")

    return filepath


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
List available handoff documents in the current project.

Searches for handoff documents in .cursor/handoffs/ and displays:
- Filename with date
- Title extracted from document
- Status (if marked complete)

Usage:
    python list_handoffs.py           # List handoffs in current project
    python list_handoffs.py /path     # List handoffs in specified path
"""

import os
import re
import sys
from datetime import datetime
from pathlib import Path


def extract_title(filepath: Path) -> str:
    """Extract the title from a handoff document."""
    try:
        content = filepath.read_text()
        # Look for first H1 header
        match = re.search(r'^#\s+(?:Handoff:\s*)?(.+)$', content, re.MULTILINE)
        if match:
            title = match.group(1).strip()
            # Clean up placeholder text
            if title.startswith("[") and title.endswith("]"):
                return "[Untitled - needs completion]"
            return title[:50] + "..." if len(title) > 50 else title
    except Exception:
        pass
    return "[Unable to read title]"


def check_completion_status(filepath: Path) -> str:
    """Check if handoff appears complete or has TODOs remaining."""
    try:
        content = filepath.read_text()
        todo_count = content.count("[TODO:")
        if todo_count == 0:
            return "Complete"
        elif todo_count <= 3:
            return f"In Progress ({todo_count} TODOs)"
        else:
            return f"Needs Work ({todo_count} TODOs)"
    except Exception:
        return "Unknown"


def parse_date_from_filename(filename: str) -> datetime | None:
    """Extract date from filename like 2024-01-15-143022-slug.md"""
    match = re.match(r'(\d{4}-\d{2}-\d{2})-(\d{6})', filename)
    if match:
        try:
            date_str = match.group(1)
            time_str = match.group(2)
            return datetime.strptime(f"{date_str} {time_str}", "%Y-%m-%d %H%M%S")
        except ValueError:
            pass
    return None


def list_handoffs(project_path: str) -> list[dict]:
    """List all handoff documents in a project."""
    handoffs_dir = Path(project_path) / ".cursor" / "handoffs"

    if not handoffs_dir.exists():
        return []

    handoffs = []
    for filepath in handoffs_dir.glob("*.md"):
        parsed_date = parse_date_from_filename(filepath.name)
        handoffs.append({
            "path": str(filepath),
            "filename": filepath.name,
            "title": extract_title(filepath),
            "status": check_completion_status(filepath),
            "date": parsed_date,
            "size": filepath.stat().st_size,
        })

    # Sort by date, most recent first
    handoffs.sort(key=lambda x: x["date"] or datetime.min, reverse=True)

    return handoffs


def format_date(dt: datetime | None) -> str:
    """Format datetime for display."""
    if dt is None:
        return "Unknown date"
    return dt.strftime("%Y-%m-%d %H:%M")


def main():
    # Get project path
    project_path = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()

    handoffs = list_handoffs(project_path)

    if not handoffs:
        print(f"No handoffs found in {project_path}/.cursor/handoffs/")
        print("\nTo create a handoff, run: python create_handoff.py [task-slug]")
        return

    print(f"Found {len(handoffs)} handoff(s) in {project_path}/.cursor/handoffs/\n")
    print("-" * 80)

    for h in handoffs:
        print(f"  Date: {format_date(h['date'])}")
        print(f"  Title: {h['title']}")
        print(f"  Status: {h['status']}")
        print(f"  File: {h['filename']}")
        print("-" * 80)

    print(f"\nTo resume from a handoff, read the document and follow the resume checklist.")
    print(f"Most recent: {handoffs[0]['path']}")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Validate a handoff document for completeness and quality.

Checks:
- No TODO placeholders remaining
- Required sections present and populated
- No potential secrets detected
- Referenced files exist
- Quality scoring

Usage:
    python validate_handoff.py <handoff-file>
    python validate_handoff.py .cursor/handoffs/2024-01-15-143022-auth.md
"""

import os
import re
import sys
from pathlib import Path

# Secret detection patterns
SECRET_PATTERNS = [
    (r'["\']?[a-zA-Z_]*api[_-]?key["\']?\s*[:=]\s*["\'][^"\']{10,}["\']', "API key"),
    (r'["\']?[a-zA-Z_]*password["\']?\s*[:=]\s*["\'][^"\']+["\']', "Password"),
    (r'["\']?[a-zA-Z_]*secret["\']?\s*[:=]\s*["\'][^"\']{10,}["\']', "Secret"),
    (r'["\']?[a-zA-Z_]*token["\']?\s*[:=]\s*["\'][^"\']{20,}["\']', "Token"),
    (r'["\']?[a-zA-Z_]*private[_-]?key["\']?\s*[:=]', "Private key"),
    (r'-----BEGIN [A-Z]+ PRIVATE KEY-----', "PEM private key"),
    (r'mongodb(\+srv)?://[^/\s]+:[^@\s]+@', "MongoDB connection string with password"),
    (r'postgres://[^/\s]+:[^@\s]+@', "PostgreSQL connection string with password"),
    (r'mysql://[^/\s]+:[^@\s]+@', "MySQL connection string with password"),
    (r'Bearer\s+[a-zA-Z0-9_\-\.]+', "Bearer token"),
    (r'ghp_[a-zA-Z0-9]{36}', "GitHub personal access token"),
    (r'sk-[a-zA-Z0-9]{48}', "OpenAI API key"),
    (r'xox[baprs]-[a-zA-Z0-9-]+', "Slack token"),
]

# Required sections for a complete handoff
REQUIRED_SECTIONS = [
    "Current State Summary",
    "Important Context",
    "Immediate Next Steps",
]

# Recommended sections
RECOMMENDED_SECTIONS = [
    "Architecture Overview",
    "Critical Files",
    "Files Modified",
    "Decisions Made",
    "Assumptions Made",
    "Potential Gotchas",
]


def check_todos(content: str) -> tuple[bool, list[str]]:
    """Check for remaining TODO placeholders."""
    todos = re.findall(r'\[TODO:[^\]]*\]', content)
    return len(todos) == 0, todos


def check_required_sections(content: str) -> tuple[bool, list[str]]:
    """Check that required sections exist and have content."""
    missing = []
    for section in REQUIRED_SECTIONS:
        # Look for section header at any level (#, ##, ###, etc.) to match template
        pattern = rf'(?:^|\n)#+\s*{re.escape(section)}'
        match = re.search(pattern, content, re.IGNORECASE)
        if not match:
            missing.append(f"{section} (missing)")
        else:
            # Check if section has meaningful content (not just placeholder)
            section_start = match.end()
            # Next section is any markdown header (one or more #) so content boundary is correct
            next_section = re.search(r'\n#+\s+', content[section_start:])
            section_end = section_start + next_section.start() if next_section else len(content)
            section_content = content[section_start:section_end].strip()

            # 50 chars minimum: roughly 1-2 sentences, enough to convey meaningful context
            if len(section_content) < 50 or '[TODO' in section_content:
                missing.append(f"{section} (incomplete)")

    return len(missing) == 0, missing


def check_recommended_sections(content: str) -> list[str]:
    """Check which recommended sections are missing."""
    missing = []
    for section in RECOMMENDED_SECTIONS:
        pattern = rf'(?:^|\n)##?\s*{re.escape(section)}'
        if not re.search(pattern, content, re.IGNORECASE):
            missing.append(section)
    return missing


def scan_for_secrets(content: str) -> list[tuple[str, str]]:
    """Scan content for potential secrets."""
    findings = []
    for pattern, description in SECRET_PATTERNS:
        matches = re.findall(pattern, content, re.IGNORECASE)
        if matches:
            findings.append((description, f"Found {len(matches)} potential match(es)"))
    return findings


def check_file_references(content: str, base_path: str) -> tuple[list[str], list[str]]:
    """Check if referenced files exist."""
    # Extract file paths from content (look for common patterns)
    # Pattern 1: | path/to/file | in tables
    # Pattern 2: `path/to/file` in code
    # Pattern 3: path/to/file:123 with line numbers

    patterns = [
        r'\|\s*([a-zA-Z0-9_\-./]+\.[a-zA-Z]+)\s*\|',  # Table cells
        r'`([a-zA-Z0-9_\-./]+\.[a-zA-Z]+(?::\d+)?)`',  # Inline code
        r'(?:^|\s)([a-zA-Z0-9_\-./]+\.[a-zA-Z]+:\d+)',  # With line numbers
    ]

    found_files = set()
    for pattern in patterns:
        matches = re.findall(pattern, content)
        for match in matches:
            # Remove line numbers
            filepath = match.split(':')[0]
            # Skip obvious non-files
            if filepath and not filepath.startswith('http') and '/' in filepath:
                found_files.add(filepath)

    existing = []
    missing = []

    for filepath in found_files:
        full_path = Path(base_path) / filepath
        if full_path.exists():
            existing.append(filepath)
        else:
            missing.append(filepath)

    return existing, missing


def calculate_quality_score(
    todos_clear: bool,
    required_complete: bool,
    missing_required: list,
    missing_recommended: list,
    secrets_found: list,
    files_missing: list
) -> tuple[int, str]:
    """Calculate overall quality score (0-100).

    Scoring rationale:
    - Start at 100, deduct for issues
    - TODOs remaining (-30): Indicates incomplete work, major blocker
    - Missing required sections (-10 each): Core context gaps
    - Secrets detected (-20): Security risk, must be fixed
    - Missing file refs (-5 each, max -20): Stale references
    - Missing recommended (-2 each): Nice-to-have completeness
    """
    score = 100

    # Deductions with justifications
    if not todos_clear:
        # -30: TODOs indicate unfinished work; next agent will lack critical info
        score -= 30
    if not required_complete:
        # -10 per section: Required sections are essential for handoff continuity
        score -= 10 * len(missing_required)
    if secrets_found:
        # -20: Security risk; handoffs may be shared or stored in repos
        score -= 20
    if files_missing:
        # -5 per file (max 4): Indicates stale refs; cap at -20 to avoid over-penalizing
        score -= 5 * min(len(files_missing), 4)

    # -2 per section: Recommended but not critical; minor impact on handoff quality
    score -= 2 * len(missing_recommended)

    score = max(0, score)

    # Rating thresholds based on handoff usability:
    # 90+: Comprehensive, ready to use immediately
    # 70-89: Usable with minor gaps
    # 50-69: Needs work before reliable handoff
    # <50: Too incomplete to be useful
    if score >= 90:
        rating = "Excellent - Ready for handoff"
    elif score >= 70:
        rating = "Good - Minor improvements suggested"
    elif score >= 50:
        rating = "Fair - Needs attention before handoff"
    else:
        rating = "Poor - Significant work needed"

    return score, rating


def validate_handoff(filepath: str) -> dict:
    """Run all validations on a handoff file."""
    path = Path(filepath)

    if not path.exists():
        return {"error": f"File not found: {filepath}"}

    content = path.read_text()
    base_path = path.parent.parent.parent  # Go up from .cursor/handoffs/

    # Run checks
    todos_clear, remaining_todos = check_todos(content)
    required_complete, missing_required = check_required_sections(content)
    missing_recommended = check_recommended_sections(content)
    secrets_found = scan_for_secrets(content)
    existing_files, missing_files = check_file_references(content, str(base_path))

    # Calculate score
    score, rating = calculate_quality_score(
        todos_clear, required_complete, missing_required,
        missing_recommended, secrets_found, missing_files
    )

    return {
        "filepath": str(path),
        "score": score,
        "rating": rating,
        "todos_clear": todos_clear,
        "remaining_todos": remaining_todos[:5],  # Limit output
        "todo_count": len(remaining_todos) if not todos_clear else 0,
        "required_complete": required_complete,
        "missing_required": missing_required,
        "missing_recommended": missing_recommended,
        "secrets_found": secrets_found,
        "files_verified": len(existing_files),
        "files_missing": missing_files[:5],  # Limit output
    }


def print_report(result: dict):
    """Print a formatted validation report."""
    if "error" in result:
        print(f"Error: {result['error']}")
        return False

    print(f"\n{'='*60}")
    print(f"Handoff Validation Report")
    print(f"{'='*60}")
    print(f"File: {result['filepath']}")
    print(f"\nQuality Score: {result['score']}/100 - {result['rating']}")
    print(f"{'='*60}")

    # TODOs
    if result['todos_clear']:
        print("\n[PASS] No TODO placeholders remaining")
    else:
        print(f"\n[FAIL] {result['todo_count']} TODO placeholders found:")
        for todo in result['remaining_todos']:
            print(f"       - {todo[:50]}...")

    # Required sections
    if result['required_complete']:
        print("\n[PASS] All required sections complete")
    else:
        print("\n[FAIL] Missing/incomplete required sections:")
        for section in result['missing_required']:
            print(f"       - {section}")

    # Secrets
    if not result['secrets_found']:
        print("\n[PASS] No potential secrets detected")
    else:
        print("\n[WARN] Potential secrets detected:")
        for secret_type, detail in result['secrets_found']:
            print(f"       - {secret_type}: {detail}")

    # File references
    if result['files_missing']:
        print(f"\n[WARN] {len(result['files_missing'])} referenced file(s) not found:")
        for f in result['files_missing']:
            print(f"       - {f}")
    else:
        print(f"\n[INFO] {result['files_verified']} file reference(s) verified")

    # Recommended sections
    if result['missing_recommended']:
        print(f"\n[INFO] Consider adding these sections:")
        for section in result['missing_recommended']:
            print(f"       - {section}")

    print(f"\n{'='*60}")

    # Final verdict
    if result['score'] >= 70 and not result['secrets_found']:
        print("Verdict: READY for handoff")
        return True
    elif result['secrets_found']:
        print("Verdict: BLOCKED - Remove secrets before handoff")
        return False
    else:
        print("Verdict: NEEDS WORK - Complete required sections")
        return False


def main():
    if len(sys.argv) < 2:
        print("Usage: python validate_handoff.py <handoff-file>")
        print("Example: python validate_handoff.py .cursor/handoffs/2024-01-15-auth.md")
        sys.exit(1)

    filepath = sys.argv[1]
    result = validate_handoff(filepath)
    success = print_report(result)

    sys.exit(0 if success else 1)


if __name__ == "__main__":
    main()