flowmodoro.py

#!/usr/bin/env python3
"""
Flowmodoro CLI — A minimalist productivity timer based on flowmodoro technique
(work + break cycles, with adaptive break durations).

Usage:
    flowmodoro start     # Start a work session
    flowmodoro break     # End work and begin a proportional break
    flowmodoro status    # Show current session status

Author: Luis RodVar
License: MIT
"""

import argparse
import json
import sys
import time
from datetime import timedelta
from pathlib import Path

# Path to the temporary state file
STATE_FILE = Path("/tmp/flowmodoro_state.json")


def save_state(state: dict) -> None:
    """Save the current session state to a temporary file."""
    STATE_FILE.write_text(json.dumps(state))


def delete_state() -> None:
    """Delete the session state file if it exists."""
    if STATE_FILE.exists():
        STATE_FILE.unlink()


def load_state() -> dict | None:
    """
    Load the session state from the JSON file.

    Returns:
        dict: The current session state if valid.
        None: If the file does not exist or is invalid.
    """
    if not STATE_FILE.exists():
        return None
    try:
        content = STATE_FILE.read_text().strip()
        if not content:
            raise json.JSONDecodeError("Empty file", "", 0)
        return json.loads(content)
    except (json.JSONDecodeError, OSError):
        delete_state()
        return None


def format_duration(seconds: float) -> str:
    """Convert seconds to a HH:MM:SS formatted string."""
    return str(timedelta(seconds=int(seconds)))


def start() -> None:
    """Start a new work session."""
    now = time.time()
    save_state({"mode": "work", "start": now})
    print("Work session started.")


def take_break() -> None:
    """
    End the current work session and calculate a break duration
    based on time worked. Saves the new break state.
    """
    state = load_state()
    if state is None:
        print("No active session.")
        return

    if state.get("mode") != "work":
        print("Not in work mode.", file=sys.stderr)
        return

    start_time = state["start"]
    now = time.time()
    minutes_worked = (now - start_time) / 60

    # Break duration is 20% of time worked, minimum 1 minute
    break_minutes = max(1, int(minutes_worked * 0.2))
    break_seconds = break_minutes * 60

    save_state({
        "mode": "break",
        "break_start": now,
        "break_duration": break_seconds
    })

    print(f"Work session ended. Duration: {int(minutes_worked)} minutes")
    print(f"Starting break for {break_minutes} minutes.")


def status() -> None:
    """
    Display the current session status:
    - If in work mode, show time worked.
    - If in break mode, show time remaining.
    - If break is over, clear the session.
    """
    state = load_state()
    if state is None:
        print("No active session.")
        return

    now = time.time()

    if state["mode"] == "work":
        elapsed = now - state["start"]
        print("mode=work")
        print(f"worked_seconds={int(elapsed)}")
        print(f"worked_hms={format_duration(elapsed)}")

    elif state["mode"] == "break":
        elapsed = now - state["break_start"]
        remaining = max(0, state["break_duration"] - elapsed)

        if remaining == 0:
            delete_state()
            print("Break ended.")
            return

        print("mode=break")
        print(f"remaining_seconds={int(remaining)}")
        print(f"remaining_hms={format_duration(remaining)}")

    else:
        print("Unknown state.", file=sys.stderr)


def main() -> None:
    """Parse command-line arguments and dispatch to the appropriate handler."""
    parser = argparse.ArgumentParser(description="Flowmodoro timer CLI")
    parser.add_argument(
        "command",
        choices=["start", "break", "status"],
        help="Command to execute"
    )
    args = parser.parse_args()

    match args.command:
        case "start":
            start()
        case "break":
            take_break()
        case "status":
            status()


if __name__ == "__main__":
    main()