erk 0.4.5__py3-none-any.whl

erk/cli/commands/exec/scripts/list_sessions.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""List Claude Code sessions for the current project with metadata.
+
+This command discovers sessions in the Claude Code project directory,
+extracts metadata (timestamps, summaries), and provides branch context
+for intelligent session selection.
+
+Usage:
+    erk exec list-sessions
+
+Output:
+    JSON object with success status, branch context, and session list
+
+Exit Codes:
+    0: Success
+    1: Error (project directory not found or other error)
+
+Examples:
+    $ erk exec list-sessions
+    {
+      "success": true,
+      "branch_context": {
+        "current_branch": "feature-xyz",
+        "trunk_branch": "master",
+        "is_on_trunk": false
+      },
+      "current_session_id": "abc123-def456",
+      "sessions": [...],
+      "project_dir": "claude-code-project"
+    }
+"""
+
+import json
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import click
+
+from erk_shared.context.helpers import require_claude_installation, require_cwd, require_git
+from erk_shared.extraction.claude_installation import ClaudeInstallation, Session
+from erk_shared.extraction.session_schema import extract_first_user_message_text
+from erk_shared.git.abc import Git
+
+
+@dataclass(frozen=True)
+class BranchContext:
+    """Git branch context for session selection behavior."""
+
+    current_branch: str
+    trunk_branch: str
+    is_on_trunk: bool
+
+
+@dataclass(frozen=True)
+class SessionInfo:
+    """Metadata for a session log file."""
+
+    session_id: str
+    mtime_display: str
+    mtime_relative: str
+    mtime_unix: float
+    size_bytes: int
+    summary: str
+    is_current: bool
+
+
+@dataclass(frozen=True)
+class ListSessionsResult:
+    """Success result with session list and context."""
+
+    success: bool
+    branch_context: dict[str, str | bool]
+    current_session_id: str | None
+    sessions: list[dict[str, str | float | int | bool]]
+    project_dir: str
+    filtered_count: int  # Count of sessions filtered by --min-size
+
+
+@dataclass(frozen=True)
+class ListSessionsError:
+    """Error result when listing sessions fails."""
+
+    success: bool
+    error: str
+    help: str
+
+
+def get_branch_context(git: Git, cwd: Path) -> BranchContext:
+    """Get git branch context for determining session selection behavior.
+
+    Args:
+        git: Git interface for branch operations
+        cwd: Current working directory
+
+    Returns:
+        BranchContext with current branch, trunk branch, and trunk status
+    """
+    current_branch = git.get_current_branch(cwd) or ""
+    trunk_branch = git.detect_trunk_branch(cwd)
+
+    return BranchContext(
+        current_branch=current_branch,
+        trunk_branch=trunk_branch,
+        is_on_trunk=current_branch == trunk_branch,
+    )
+
+
+def format_relative_time(mtime: float) -> str:
+    """Format modification time as human-readable relative time.
+
+    Args:
+        mtime: Unix timestamp (seconds since epoch)
+
+    Returns:
+        Human-readable relative time string
+
+    Examples:
+        >>> format_relative_time(time.time() - 10)
+        'just now'
+        >>> format_relative_time(time.time() - 180)
+        '3m ago'
+        >>> format_relative_time(time.time() - 7200)
+        '2h ago'
+    """
+    now = time.time()
+    delta = now - mtime
+
+    if delta < 30:
+        return "just now"
+    if delta < 3600:  # < 1 hour
+        minutes = int(delta / 60)
+        return f"{minutes}m ago"
+    if delta < 86400:  # < 24 hours
+        hours = int(delta / 3600)
+        return f"{hours}h ago"
+    if delta < 604800:  # < 7 days
+        days = int(delta / 86400)
+        return f"{days}d ago"
+    # >= 7 days: show absolute date
+    return format_display_time(mtime)
+
+
+def format_display_time(mtime: float) -> str:
+    """Format modification time as display string.
+
+    Args:
+        mtime: Unix timestamp (seconds since epoch)
+
+    Returns:
+        Formatted date string like "Dec 3, 11:38 AM"
+    """
+    import datetime
+
+    dt = datetime.datetime.fromtimestamp(mtime)
+    return dt.strftime("%b %-d, %-I:%M %p")
+
+
+def _list_sessions_from_store(
+    claude_installation: ClaudeInstallation,
+    cwd: Path,
+    current_session_id: str | None,
+    limit: int,
+    min_size: int,
+) -> tuple[list[SessionInfo], int]:
+    """List sessions from claude installation sorted by modification time.
+
+    Args:
+        claude_installation: Claude installation to query
+        cwd: Current working directory (project identifier)
+        current_session_id: Current session ID (for marking)
+        limit: Maximum number of sessions to return
+        min_size: Minimum session size in bytes (filters out tiny sessions)
+
+    Returns:
+        Tuple of (sessions list, count of sessions filtered by min_size)
+    """
+    # Check if project exists
+    if not claude_installation.has_project(cwd):
+        return [], 0
+
+    # Get all sessions first to count filtered
+    all_sessions = claude_installation.find_sessions(
+        cwd,
+        current_session_id=current_session_id,
+        min_size=0,
+        limit=1000,
+        include_agents=False,
+    )
+
+    # Filter by size
+    filtered_sessions: list[Session]
+    if min_size > 0:
+        filtered_sessions = [s for s in all_sessions if s.size_bytes >= min_size]
+        filtered_count = len(all_sessions) - len(filtered_sessions)
+    else:
+        filtered_sessions = all_sessions
+        filtered_count = 0
+
+    # Apply limit
+    limited_sessions = filtered_sessions[:limit]
+
+    # Convert to SessionInfo with summaries
+    session_infos: list[SessionInfo] = []
+    for session in limited_sessions:
+        # Read session content for summary extraction
+        content = claude_installation.read_session(cwd, session.session_id, include_agents=False)
+        summary = ""
+        if content is not None:
+            summary = extract_first_user_message_text(content.main_content, max_length=60)
+
+        # Determine if this is the current session
+        is_current = session.session_id == current_session_id
+
+        session_infos.append(
+            SessionInfo(
+                session_id=session.session_id,
+                mtime_display=format_display_time(session.modified_at),
+                mtime_relative=format_relative_time(session.modified_at),
+                mtime_unix=session.modified_at,
+                size_bytes=session.size_bytes,
+                summary=summary,
+                is_current=is_current,
+            )
+        )
+
+    return session_infos, filtered_count
+
+
+@click.command(name="list-sessions")
+@click.option(
+    "--limit",
+    default=10,
+    type=int,
+    help="Maximum number of sessions to list",
+)
+@click.option(
+    "--min-size",
+    default=0,
+    type=int,
+    help="Minimum session size in bytes (filters out tiny sessions)",
+)
+@click.option(
+    "--session-id",
+    default=None,
+    type=str,
+    help="Current session ID (for marking the current session)",
+)
+@click.pass_context
+def list_sessions(ctx: click.Context, limit: int, min_size: int, session_id: str | None) -> None:
+    """List Claude Code sessions with metadata for the current project.
+
+    Discovers sessions in the project directory, extracts metadata
+    (timestamps, summaries), and provides branch context.
+    """
+    git = require_git(ctx)
+    claude_installation = require_claude_installation(ctx)
+    cwd = require_cwd(ctx)
+
+    # Check if project exists
+    if not claude_installation.has_project(cwd):
+        error = ListSessionsError(
+            success=False,
+            error=f"No Claude Code project found for: {cwd}",
+            help="Make sure you're in a directory with Claude Code sessions",
+        )
+        click.echo(json.dumps(asdict(error), indent=2))
+        raise SystemExit(1)
+
+    # Get branch context
+    branch_context = get_branch_context(git, cwd)
+
+    # List sessions from store
+    sessions, filtered_count = _list_sessions_from_store(
+        claude_installation,
+        cwd,
+        session_id,
+        limit=limit,
+        min_size=min_size,
+    )
+
+    # Build result
+    result = ListSessionsResult(
+        success=True,
+        branch_context={
+            "current_branch": branch_context.current_branch,
+            "trunk_branch": branch_context.trunk_branch,
+            "is_on_trunk": branch_context.is_on_trunk,
+        },
+        current_session_id=session_id,
+        sessions=[asdict(s) for s in sessions],
+        project_dir="claude-code-project",  # Abstract - don't expose filesystem paths
+        filtered_count=filtered_count,
+    )
+
+    click.echo(json.dumps(asdict(result), indent=2))

erk/cli/commands/exec/scripts/mark_impl_ended.py

@@ -0,0 +1,188 @@
+"""Mark implementation ended by updating GitHub issue metadata.
+
+This exec command updates the plan-header metadata block in a GitHub issue
+with the appropriate event fields based on the execution environment:
+- Local machine: Updates last_local_impl_* fields (timestamp, event="ended", session, user)
+- GitHub Actions: Updates last_remote_impl_at field
+
+Also writes .impl/local-run-state.json for fast local access (no GitHub API needed).
+
+Usage:
+    erk exec mark-impl-ended
+
+Output:
+    JSON with success status or error information
+    Always exits with code 0 (graceful degradation for || true pattern)
+
+Exit Codes:
+    0: Always (even on error, to support || true pattern)
+
+Examples:
+    $ erk exec mark-impl-ended
+    {"success": true, "issue_number": 123}
+
+    $ erk exec mark-impl-ended
+    {"success": false, "error_type": "no_issue_reference", "message": "..."}
+"""
+
+import getpass
+import json
+import os
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+
+import click
+
+from erk_shared.context.helpers import (
+    require_cwd,
+    require_repo_root,
+)
+from erk_shared.context.helpers import (
+    require_issues as require_github_issues,
+)
+from erk_shared.env import in_github_actions
+from erk_shared.github.metadata.plan_header import (
+    update_plan_header_local_impl_event,
+    update_plan_header_remote_impl,
+)
+from erk_shared.impl_folder import read_issue_reference, write_local_run_state
+
+
+@dataclass(frozen=True)
+class MarkImplSuccess:
+    """Success response for mark impl ended."""
+
+    success: bool
+    issue_number: int
+
+
+@dataclass(frozen=True)
+class MarkImplError:
+    """Error response for mark impl ended."""
+
+    success: bool
+    error_type: str
+    message: str
+
+
+@click.command(name="mark-impl-ended")
+@click.pass_context
+def mark_impl_ended(ctx: click.Context) -> None:
+    """Update implementation ended event in GitHub issue and local state file.
+
+    Reads issue number from .impl/issue.json, fetches the issue from GitHub,
+    updates the plan-header block with current event metadata, and posts back.
+
+    Also writes .impl/local-run-state.json for fast local access.
+
+    Detects execution environment:
+    - Local machine: Updates last_local_impl_* fields (timestamp, event="ended", session, user)
+    - GitHub Actions: Updates last_remote_impl_at field
+
+    Gracefully fails with exit code 0 to support || true pattern in slash commands.
+    """
+    # Get dependencies from context
+    repo_root = require_repo_root(ctx)
+    cwd = require_cwd(ctx)
+
+    # Read issue reference from .impl/issue.json
+    impl_dir = cwd / ".impl"
+    issue_ref = read_issue_reference(impl_dir)
+    if issue_ref is None:
+        result = MarkImplError(
+            success=False,
+            error_type="no-issue-reference",
+            message="No issue reference found in .impl/issue.json",
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0)
+
+    # Capture metadata
+    timestamp = datetime.now(UTC).isoformat()
+    session_id = os.environ.get("CLAUDE_CODE_SESSION_ID")
+    user = getpass.getuser()
+
+    # Write local state file first (fast, no network)
+    try:
+        write_local_run_state(
+            impl_dir=impl_dir,
+            last_event="ended",
+            timestamp=timestamp,
+            user=user,
+            session_id=session_id,
+        )
+    except (FileNotFoundError, ValueError) as e:
+        result = MarkImplError(
+            success=False,
+            error_type="local-state-write-failed",
+            message=f"Failed to write local state: {e}",
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0) from None
+
+    # Get GitHub Issues from context
+    try:
+        github_issues = require_github_issues(ctx)
+    except SystemExit:
+        result = MarkImplError(
+            success=False,
+            error_type="context-not-initialized",
+            message="Context not initialized",
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0) from None
+
+    # Fetch current issue
+    try:
+        issue = github_issues.get_issue(repo_root, issue_ref.issue_number)
+    except RuntimeError as e:
+        result = MarkImplError(
+            success=False,
+            error_type="issue-not-found",
+            message=f"Issue #{issue_ref.issue_number} not found: {e}",
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0) from None
+
+    # Update impl event based on environment
+    try:
+        if in_github_actions():
+            updated_body = update_plan_header_remote_impl(
+                issue_body=issue.body,
+                remote_impl_at=timestamp,
+            )
+        else:
+            updated_body = update_plan_header_local_impl_event(
+                issue_body=issue.body,
+                local_impl_at=timestamp,
+                event="ended",
+                session_id=session_id,
+                user=user,
+            )
+    except ValueError as e:
+        # plan-header block not found (old format issue)
+        result = MarkImplError(
+            success=False,
+            error_type="no-plan-header-block",
+            message=str(e),
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0) from None
+
+    # Update issue body
+    try:
+        github_issues.update_issue_body(repo_root, issue_ref.issue_number, updated_body)
+    except RuntimeError as e:
+        result = MarkImplError(
+            success=False,
+            error_type="github-api-failed",
+            message=f"Failed to update issue body: {e}",
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0) from None
+
+    result_success = MarkImplSuccess(
+        success=True,
+        issue_number=issue_ref.issue_number,
+    )
+    click.echo(json.dumps(asdict(result_success), indent=2))

erk/cli/commands/exec/scripts/mark_impl_started.py

@@ -0,0 +1,188 @@
+"""Mark implementation started by updating GitHub issue metadata.
+
+This exec command updates the plan-header metadata block in a GitHub issue
+with the appropriate event fields based on the execution environment:
+- Local machine: Updates last_local_impl_* fields (timestamp, event, session, user)
+- GitHub Actions: Updates last_remote_impl_at field
+
+Also writes .impl/local-run-state.json for fast local access (no GitHub API needed).
+
+Usage:
+    erk exec mark-impl-started
+
+Output:
+    JSON with success status or error information
+    Always exits with code 0 (graceful degradation for || true pattern)
+
+Exit Codes:
+    0: Always (even on error, to support || true pattern)
+
+Examples:
+    $ erk exec mark-impl-started
+    {"success": true, "issue_number": 123}
+
+    $ erk exec mark-impl-started
+    {"success": false, "error_type": "no_issue_reference", "message": "..."}
+"""
+
+import getpass
+import json
+import os
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+
+import click
+
+from erk_shared.context.helpers import (
+    require_cwd,
+    require_repo_root,
+)
+from erk_shared.context.helpers import (
+    require_issues as require_github_issues,
+)
+from erk_shared.env import in_github_actions
+from erk_shared.github.metadata.plan_header import (
+    update_plan_header_local_impl_event,
+    update_plan_header_remote_impl,
+)
+from erk_shared.impl_folder import read_issue_reference, write_local_run_state
+
+
+@dataclass(frozen=True)
+class MarkImplSuccess:
+    """Success response for mark impl started."""
+
+    success: bool
+    issue_number: int
+
+
+@dataclass(frozen=True)
+class MarkImplError:
+    """Error response for mark impl started."""
+
+    success: bool
+    error_type: str
+    message: str
+
+
+@click.command(name="mark-impl-started")
+@click.pass_context
+def mark_impl_started(ctx: click.Context) -> None:
+    """Update implementation started event in GitHub issue and local state file.
+
+    Reads issue number from .impl/issue.json, fetches the issue from GitHub,
+    updates the plan-header block with current event metadata, and posts back.
+
+    Also writes .impl/local-run-state.json for fast local access.
+
+    Detects execution environment:
+    - Local machine: Updates last_local_impl_* fields (timestamp, event, session, user)
+    - GitHub Actions: Updates last_remote_impl_at field
+
+    Gracefully fails with exit code 0 to support || true pattern in slash commands.
+    """
+    # Get dependencies from context
+    repo_root = require_repo_root(ctx)
+    cwd = require_cwd(ctx)
+
+    # Read issue reference from .impl/issue.json
+    impl_dir = cwd / ".impl"
+    issue_ref = read_issue_reference(impl_dir)
+    if issue_ref is None:
+        result = MarkImplError(
+            success=False,
+            error_type="no-issue-reference",
+            message="No issue reference found in .impl/issue.json",
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0)
+
+    # Capture metadata
+    timestamp = datetime.now(UTC).isoformat()
+    session_id = os.environ.get("CLAUDE_CODE_SESSION_ID")
+    user = getpass.getuser()
+
+    # Write local state file first (fast, no network)
+    try:
+        write_local_run_state(
+            impl_dir=impl_dir,
+            last_event="started",
+            timestamp=timestamp,
+            user=user,
+            session_id=session_id,
+        )
+    except (FileNotFoundError, ValueError) as e:
+        result = MarkImplError(
+            success=False,
+            error_type="local-state-write-failed",
+            message=f"Failed to write local state: {e}",
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0) from None
+
+    # Get GitHub Issues from context
+    try:
+        github_issues = require_github_issues(ctx)
+    except SystemExit:
+        result = MarkImplError(
+            success=False,
+            error_type="context-not-initialized",
+            message="Context not initialized",
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0) from None
+
+    # Fetch current issue
+    try:
+        issue = github_issues.get_issue(repo_root, issue_ref.issue_number)
+    except RuntimeError as e:
+        result = MarkImplError(
+            success=False,
+            error_type="issue-not-found",
+            message=f"Issue #{issue_ref.issue_number} not found: {e}",
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0) from None
+
+    # Update impl event based on environment
+    try:
+        if in_github_actions():
+            updated_body = update_plan_header_remote_impl(
+                issue_body=issue.body,
+                remote_impl_at=timestamp,
+            )
+        else:
+            updated_body = update_plan_header_local_impl_event(
+                issue_body=issue.body,
+                local_impl_at=timestamp,
+                event="started",
+                session_id=session_id,
+                user=user,
+            )
+    except ValueError as e:
+        # plan-header block not found (old format issue)
+        result = MarkImplError(
+            success=False,
+            error_type="no-plan-header-block",
+            message=str(e),
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0) from None
+
+    # Update issue body
+    try:
+        github_issues.update_issue_body(repo_root, issue_ref.issue_number, updated_body)
+    except RuntimeError as e:
+        result = MarkImplError(
+            success=False,
+            error_type="github-api-failed",
+            message=f"Failed to update issue body: {e}",
+        )
+        click.echo(json.dumps(asdict(result), indent=2))
+        raise SystemExit(0) from None
+
+    result_success = MarkImplSuccess(
+        success=True,
+        issue_number=issue_ref.issue_number,
+    )
+    click.echo(json.dumps(asdict(result_success), indent=2))