timer.py

#!/usr/bin/env python3
"""
timer -- Track time on tasks from the CLI. Zero deps.

Start/stop timers, log your work, see reports. File-backed, offline, private.

Usage:
    py timer.py start "Working on feature X" -t coding
    py timer.py stop                           # Stop current timer
    py timer.py status                         # Is a timer running?
    py timer.py log                            # Today's entries
    py timer.py log --date 2024-01-15          # Specific date
    py timer.py report                         # This week's summary
    py timer.py report --month                 # Monthly summary
    py timer.py add "Meeting" 09:00 10:30      # Add manual entry
    py timer.py rm 3                           # Delete entry
    py timer.py export                         # CSV export
    py timer.py tags                           # List tags with totals
"""

import argparse
import json
import os
import sys
from datetime import datetime, timedelta
from pathlib import Path

TIMER_FILE = ".timesheet.json"

RESET = "\033[0m"
BOLD = "\033[1m"
DIM = "\033[2m"
GREEN = "\033[32m"
YELLOW = "\033[33m"
CYAN = "\033[36m"
RED = "\033[31m"
MAGENTA = "\033[35m"


def color_supported() -> bool:
    if os.environ.get("NO_COLOR"):
        return False
    if sys.platform == "win32":
        return bool(os.environ.get("TERM") or os.environ.get("WT_SESSION"))
    return hasattr(sys.stdout, "isatty") and sys.stdout.isatty()


USE_COLOR = color_supported()


def c(code: str, text: str) -> str:
    return f"{code}{text}{RESET}" if USE_COLOR else text


def get_path() -> Path:
    local = Path(TIMER_FILE)
    if local.exists():
        return local
    home = Path.home() / TIMER_FILE
    if home.exists():
        return home
    return home


def load() -> dict:
    p = get_path()
    if not p.exists():
        return {"entries": [], "current": None}
    try:
        return json.loads(p.read_text(encoding="utf-8"))
    except (json.JSONDecodeError, Exception):
        return {"entries": [], "current": None}


def save(data: dict):
    get_path().write_text(json.dumps(data, indent=2, default=str) + "\n", encoding="utf-8")


def fmt_duration(seconds: float) -> str:
    """Format seconds as HH:MM."""
    if seconds < 0:
        return "0:00"
    h = int(seconds // 3600)
    m = int((seconds % 3600) // 60)
    return f"{h}:{m:02d}"


def fmt_duration_long(seconds: float) -> str:
    """Format with h/m labels."""
    h = int(seconds // 3600)
    m = int((seconds % 3600) // 60)
    if h > 0:
        return f"{h}h {m}m"
    return f"{m}m"


def parse_time(s: str) -> datetime | None:
    """Parse HH:MM time string for today."""
    try:
        parts = s.split(":")
        h, m = int(parts[0]), int(parts[1]) if len(parts) > 1 else 0
        now = datetime.now()
        return now.replace(hour=h, minute=m, second=0, microsecond=0)
    except (ValueError, IndexError):
        return None


def bar(value: float, max_val: float, width: int = 20) -> str:
    if max_val <= 0:
        return ""
    filled = int(width * value / max_val)
    return "#" * filled


# --- Commands ---

def cmd_start(args):
    data = load()
    if data.get("current"):
        cur = data["current"]
        elapsed = (datetime.now() - datetime.fromisoformat(cur["start"])).total_seconds()
        print(c(YELLOW, f"  Timer already running: {cur['desc']} ({fmt_duration_long(elapsed)})"))
        print(c(DIM, "  Stop it first: py timer.py stop"))
        return

    data["current"] = {
        "desc": args.desc,
        "tag": args.tag or "",
        "start": datetime.now().isoformat(),
    }
    save(data)
    print(f"  {c(GREEN, 'Started')} {c(BOLD, args.desc)}" +
          (f" {c(MAGENTA, f'[{args.tag}]')}" if args.tag else "") +
          f" at {c(DIM, datetime.now().strftime('%H:%M'))}")


def cmd_stop(args):
    data = load()
    if not data.get("current"):
        print(c(DIM, "  No timer running."))
        return

    cur = data["current"]
    start = datetime.fromisoformat(cur["start"])
    end = datetime.now()
    elapsed = (end - start).total_seconds()

    entry = {
        "id": max((e.get("id", 0) for e in data["entries"]), default=0) + 1,
        "desc": cur["desc"],
        "tag": cur.get("tag", ""),
        "start": cur["start"],
        "end": end.isoformat(),
        "seconds": round(elapsed),
        "date": start.strftime("%Y-%m-%d"),
    }
    data["entries"].append(entry)
    data["current"] = None
    save(data)

    print(f"  {c(RED, 'Stopped')} {c(BOLD, entry['desc'])}  "
          f"{c(CYAN, fmt_duration_long(elapsed))}  "
          f"({start.strftime('%H:%M')}-{end.strftime('%H:%M')})")


def cmd_status(args):
    data = load()
    if data.get("current"):
        cur = data["current"]
        start = datetime.fromisoformat(cur["start"])
        elapsed = (datetime.now() - start).total_seconds()
        tag_val = cur.get("tag", "")
        tag = f" {c(MAGENTA, '[' + tag_val + ']')}" if tag_val else ""
        print(f"\n  {c(GREEN, 'Running:')} {c(BOLD, cur['desc'])}{tag}")
        print(f"  Started:  {start.strftime('%H:%M')}")
        print(f"  Elapsed:  {c(CYAN, fmt_duration_long(elapsed))}\n")
    else:
        print(c(DIM, "  No timer running."))


def cmd_log(args):
    data = load()
    target_date = args.date or datetime.now().strftime("%Y-%m-%d")
    entries = [e for e in data["entries"] if e.get("date") == target_date]

    if not entries:
        print(c(DIM, f"  No entries for {target_date}."))
        # Show running timer
        if data.get("current"):
            cur = data["current"]
            elapsed = (datetime.now() - datetime.fromisoformat(cur["start"])).total_seconds()
            print(f"  {c(GREEN, 'Running:')} {cur['desc']} ({fmt_duration_long(elapsed)})")
        return

    total = sum(e.get("seconds", 0) for e in entries)
    print(f"\n  {c(BOLD, target_date)}  ({len(entries)} entries, {c(CYAN, fmt_duration_long(total))} total)\n")

    for e in entries:
        start = datetime.fromisoformat(e["start"]).strftime("%H:%M")
        end = datetime.fromisoformat(e["end"]).strftime("%H:%M") if e.get("end") else "??:??"
        dur = fmt_duration(e.get("seconds", 0))
        tag_val = e.get("tag", "")
        tag = f" {c(MAGENTA, '[' + tag_val + ']')}" if tag_val else ""
        eid = e.get("id", "?")
        print(f"  {c(DIM, f'#{eid:<3}')} {start}-{end}  {c(CYAN, dur):>8}  {e['desc']}{tag}")

    # Show running timer too
    if data.get("current"):
        cur = data["current"]
        start = datetime.fromisoformat(cur["start"])
        if start.strftime("%Y-%m-%d") == target_date:
            elapsed = (datetime.now() - start).total_seconds()
            tag_val = cur.get("tag", "")
            tag = f" {c(MAGENTA, '[' + tag_val + ']')}" if tag_val else ""
            print(f"  {c(GREEN, '>>>')}  {start.strftime('%H:%M')}-...   {c(CYAN, fmt_duration(elapsed)):>8}  {cur['desc']}{tag}  {c(GREEN, '(running)')}")

    print()


def cmd_report(args):
    data = load()
    entries = data["entries"]

    if not entries:
        print(c(DIM, "  No entries to report."))
        return

    # Determine date range
    now = datetime.now()
    if args.month:
        start_date = now.replace(day=1)
        label = now.strftime("%B %Y")
    elif args.all:
        start_date = datetime.fromisoformat(entries[0]["date"])
        label = "All time"
    else:
        # This week (Monday start)
        start_date = now - timedelta(days=now.weekday())
        start_date = start_date.replace(hour=0, minute=0, second=0)
        label = f"Week of {start_date.strftime('%Y-%m-%d')}"

    start_str = start_date.strftime("%Y-%m-%d")
    filtered = [e for e in entries if e.get("date", "") >= start_str]

    if not filtered:
        print(c(DIM, f"  No entries for {label}."))
        return

    # Group by date
    by_date: dict[str, float] = {}
    by_tag: dict[str, float] = {}
    for e in filtered:
        d = e.get("date", "unknown")
        by_date[d] = by_date.get(d, 0) + e.get("seconds", 0)
        tag = e.get("tag") or "(untagged)"
        by_tag[tag] = by_tag.get(tag, 0) + e.get("seconds", 0)

    total = sum(e.get("seconds", 0) for e in filtered)
    max_daily = max(by_date.values()) if by_date else 1

    print(f"\n  {c(BOLD, label)}  ({len(filtered)} entries, {c(CYAN, fmt_duration_long(total))} total)\n")

    print(f"  {c(DIM, 'By day:')}")
    for date in sorted(by_date):
        secs = by_date[date]
        b = bar(secs, max_daily, 25)
        dow = datetime.strptime(date, "%Y-%m-%d").strftime("%a")
        print(f"    {date} {c(DIM, dow)}  {c(CYAN, fmt_duration(secs)):>7}  {b}")

    if by_tag:
        max_tag = max(by_tag.values())
        print(f"\n  {c(DIM, 'By tag:')}")
        for tag in sorted(by_tag, key=lambda t: -by_tag[t]):
            secs = by_tag[tag]
            b = bar(secs, max_tag, 25)
            print(f"    {c(MAGENTA, tag):<20}  {c(CYAN, fmt_duration(secs)):>7}  {b}")

    print(f"\n  {c(DIM, f'Daily avg: {fmt_duration_long(total / len(by_date))}')}") if by_date else None
    print()


def cmd_add(args):
    data = load()
    start = parse_time(args.start)
    end = parse_time(args.end)
    if not start or not end:
        print(c(RED, "  Invalid time format. Use HH:MM."))
        return

    elapsed = (end - start).total_seconds()
    if elapsed <= 0:
        print(c(RED, "  End time must be after start time."))
        return

    entry = {
        "id": max((e.get("id", 0) for e in data["entries"]), default=0) + 1,
        "desc": args.desc,
        "tag": args.tag or "",
        "start": start.isoformat(),
        "end": end.isoformat(),
        "seconds": round(elapsed),
        "date": start.strftime("%Y-%m-%d"),
    }
    data["entries"].append(entry)
    save(data)
    print(f"  {c(GREEN, 'Added')} #{entry['id']}: {entry['desc']} ({fmt_duration_long(elapsed)})")


def cmd_rm(args):
    data = load()
    before = len(data["entries"])
    data["entries"] = [e for e in data["entries"] if e.get("id") != args.id]
    if len(data["entries"]) == before:
        print(c(RED, f"  Entry #{args.id} not found."))
        return
    save(data)
    print(c(GREEN, f"  Removed entry #{args.id}."))


def cmd_export(args):
    data = load()
    import csv as csv_mod
    writer = csv_mod.writer(sys.stdout, lineterminator="\n")
    writer.writerow(["id", "date", "start", "end", "duration_min", "desc", "tag"])
    for e in data["entries"]:
        start = datetime.fromisoformat(e["start"]).strftime("%H:%M")
        end = datetime.fromisoformat(e["end"]).strftime("%H:%M") if e.get("end") else ""
        dur = round(e.get("seconds", 0) / 60, 1)
        writer.writerow([e.get("id", ""), e.get("date", ""), start, end, dur, e["desc"], e.get("tag", "")])


def cmd_tags(args):
    data = load()
    by_tag: dict[str, dict] = {}
    for e in data["entries"]:
        tag = e.get("tag") or "(untagged)"
        if tag not in by_tag:
            by_tag[tag] = {"seconds": 0, "count": 0}
        by_tag[tag]["seconds"] += e.get("seconds", 0)
        by_tag[tag]["count"] += 1

    if not by_tag:
        print(c(DIM, "  No entries yet."))
        return

    print(f"\n  {c(BOLD, 'Tags')}\n")
    for tag in sorted(by_tag, key=lambda t: -by_tag[t]["seconds"]):
        info = by_tag[tag]
        print(f"  {c(MAGENTA, tag):<20} {c(CYAN, fmt_duration_long(info['seconds'])):>10}  ({info['count']} entries)")
    print()


def main():
    parser = argparse.ArgumentParser(
        description="timer -- track time on tasks from the CLI",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    sub = parser.add_subparsers(dest="command")

    p = sub.add_parser("start", help="Start a timer")
    p.add_argument("desc", help="Task description")
    p.add_argument("-t", "--tag", help="Tag/category")

    sub.add_parser("stop", help="Stop current timer")
    sub.add_parser("status", help="Show running timer")

    p = sub.add_parser("log", help="Show entries for a day")
    p.add_argument("--date", help="Date (YYYY-MM-DD, default: today)")

    p = sub.add_parser("report", help="Summary report")
    p.add_argument("--month", action="store_true", help="Monthly report")
    p.add_argument("--all", action="store_true", help="All-time report")

    p = sub.add_parser("add", help="Add a manual entry")
    p.add_argument("desc", help="Description")
    p.add_argument("start", help="Start time (HH:MM)")
    p.add_argument("end", help="End time (HH:MM)")
    p.add_argument("-t", "--tag", help="Tag")

    p = sub.add_parser("rm", help="Delete an entry")
    p.add_argument("id", type=int, help="Entry ID")

    sub.add_parser("export", help="Export as CSV")
    sub.add_parser("tags", help="List tags with time totals")

    args = parser.parse_args()
    cmds = {
        "start": cmd_start, "stop": cmd_stop, "status": cmd_status,
        "log": cmd_log, "report": cmd_report, "add": cmd_add,
        "rm": cmd_rm, "export": cmd_export, "tags": cmd_tags,
    }

    if args.command in cmds:
        cmds[args.command](args)
    else:
        # Default: status then today's log
        cmd_status(argparse.Namespace())
        cmd_log(argparse.Namespace(date=None))


if __name__ == "__main__":
    main()