clockin-tracker 0.1.0__py3-none-any.whl

clockin/__init__.py

@@ -0,0 +1,8 @@
+AUTHOR = "markosnarinian"
+APP_NAME = "clockin"
+
+
+def main() -> None:
+    from clockin.main import app
+
+    app()

clockin/configuration.py

@@ -0,0 +1,104 @@
+import json
+from collections.abc import Mapping
+from typing import Any
+
+import platformdirs
+
+from clockin import APP_NAME, AUTHOR
+
+CONFIGURATION = "config.json"
+DEFAULT_CONFIGURATION: dict[str, Any] = {
+    "styles": {
+        "default": {
+            "started": ("green", "✓", "Started session"),
+            "stopped": ("red", "■", "Stopped session"),
+            "resumed": ("green", "▶", "Resumed session"),
+            "stopped_updated": ("red", "■", "Updated stopped session"),
+            "canceled": ("red", "×", "Canceled session"),
+            "restored": ("green", "↺", "Restored session"),
+            "restored_stopped": ("red", "↺", "Restored session"),
+            "restored_stopped_note": (
+                "red",
+                "↳",
+                "stopped_at set to the cancellation time",
+            ),
+            "warning": ("yellow", "!"),
+            "active_title": ("green", "▶", "Active session"),
+            "canceled_title": ("red", "×", "Canceled session"),
+            "no_active": ("yellow", "!", "No active session"),
+            "report_title": ("yellow", "▤", "Report"),
+            "no_sessions": ("yellow", "!", "No sessions to report"),
+        },
+        "quirky": {
+            "started": ("green", "🚀", "Blast off! Session started"),
+            "stopped": ("red", "🛑", "Whoa there! Session stopped"),
+            "resumed": ("green", "🎬", "And we're back! Session resumed"),
+            "stopped_updated": ("red", "📝", "Tweaked that stopped session"),
+            "canceled": ("red", "🙅", "Nope! Session canceled"),
+            "restored": ("green", "🪄", "Ta-da! Session restored"),
+            "restored_stopped": ("red", "🪄", "Poof! Stopped session restored"),
+            "restored_stopped_note": (
+                "red",
+                "🕰️",
+                "stopped_at set to the cancellation time",
+            ),
+            "warning": ("yellow", "🤔"),
+            "active_title": ("green", "⏱️", "Clock's ticking!"),
+            "canceled_title": ("red", "🚫", "Canceled session"),
+            "no_active": ("yellow", "😴", "Nothing running... take a break?"),
+            "report_title": ("yellow", "📊", "Here's the tea"),
+            "no_sessions": ("yellow", "🤷", "Nothing to report yet"),
+        },
+    },
+    "default_project": None,
+    "style": "default",
+    "require_project": True,
+}
+INITIAL_CONFIGURATION: dict[str, Any] = {
+    "default_project": None,
+    "style": "default",
+    "require_project": True,
+}
+
+configuration_path = (
+    platformdirs.user_config_path(
+        appauthor=AUTHOR,
+        appname=APP_NAME,
+        ensure_exists=True,
+    )
+    / CONFIGURATION
+)
+
+
+def _write_configuration(configuration: dict[str, Any]) -> None:
+    configuration_path.write_text(
+        json.dumps(configuration, indent=2) + "\n",
+        encoding="utf-8",
+    )
+
+
+def _initialize_configuration() -> None:
+    _write_configuration(INITIAL_CONFIGURATION)
+
+
+def load_user_configuration() -> dict[str, Any]:
+    return json.loads(configuration_path.read_text(encoding="utf-8"))
+
+
+def load_configuration() -> dict[str, Any]:
+    if not configuration_path.exists() or not configuration_path.is_file():
+        _initialize_configuration()
+    configuration = DEFAULT_CONFIGURATION.copy()
+    configuration.update(load_user_configuration())
+    return configuration
+
+
+def update_configuration(configuration: Mapping[str, Any]) -> dict[str, Any]:
+    updated_configuration = load_configuration()
+    updated_configuration.update(configuration)
+    _write_configuration(updated_configuration)
+    return updated_configuration
+
+
+def reset_configuration() -> None:
+    _initialize_configuration()

clockin/db.py

@@ -0,0 +1,409 @@
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Any
+from uuid import uuid4
+
+import platformdirs
+
+from clockin import APP_NAME, AUTHOR
+from clockin.exceptions import (
+    ActiveSessionError,
+    NoActiveSessionError,
+    NoCanceledSessionError,
+    NoStoppedSessionError,
+)
+from clockin.utils import to_timestamp
+
+SCHEMA_VERSION = "1.0"
+SCHEMA = """
+CREATE TABLE sessions (
+    id TEXT PRIMARY KEY UNIQUE,
+    project TEXT,
+    started_at INTEGER,
+    stopped_at INTEGER,
+    canceled_at INTEGER
+)
+"""
+DATABASE = f"clockin.v{SCHEMA_VERSION}.db"
+
+
+@dataclass(frozen=True)
+class Session:
+    id: str
+    project: str | None
+    started_at: datetime
+    stopped_at: datetime | None
+    canceled_at: datetime | None
+
+
+class Connection:
+    def __init__(self, close_on_exit: bool = True):
+        user_data_path = platformdirs.user_data_path(
+            appauthor=AUTHOR,
+            appname=APP_NAME,
+            ensure_exists=True,
+        )
+        database_path = user_data_path / DATABASE
+        database_exists = database_path.exists() and database_path.is_file()
+        self.__close_on_exit = close_on_exit
+        self._connection = sqlite3.connect(database_path)
+        if not database_exists:
+            self._connection.executescript(SCHEMA)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        if exc_type is None:
+            self._connection.commit()
+        else:
+            self._connection.rollback()
+
+        if self.__close_on_exit:
+            self.close()
+        return False
+
+    def _remove_canceled_sessions(self):
+        self._connection.execute(
+            """
+            DELETE FROM sessions
+            WHERE canceled_at IS NOT NULL
+            """
+        )
+
+    def _active_session_id(self) -> str | None:
+        cursor = self._connection.execute(
+            """
+            SELECT id
+            FROM sessions
+            WHERE stopped_at IS NULL
+            AND canceled_at IS NULL
+            ORDER BY started_at DESC
+            LIMIT 1
+            """
+        )
+        row = cursor.fetchone()
+        if row is None:
+            return None
+        return row[0]
+
+    def _canceled_session_id(self) -> str | None:
+        cursor = self._connection.execute(
+            """
+            SELECT id
+            FROM sessions
+            WHERE canceled_at IS NOT NULL
+            AND stopped_at IS NULL
+            ORDER BY started_at DESC
+            LIMIT 1
+            """
+        )
+        row = cursor.fetchone()
+        if row is None:
+            return None
+        return row[0]
+
+    def _stopped_session_id(self) -> str | None:
+        cursor = self._connection.execute(
+            """
+            SELECT id
+            FROM sessions
+            WHERE stopped_at IS NOT NULL
+            AND canceled_at IS NULL
+            ORDER BY stopped_at DESC
+            LIMIT 1
+            """
+        )
+        row = cursor.fetchone()
+        if row is None:
+            return None
+        return row[0]
+
+    def active_session(self) -> Session | None:
+        cursor = self._connection.execute(
+            """
+            SELECT id, project, started_at, stopped_at, canceled_at
+            FROM sessions
+            WHERE stopped_at IS NULL
+            AND canceled_at IS NULL
+            ORDER BY started_at DESC
+            LIMIT 1
+            """
+        )
+        row = cursor.fetchone()
+        if row is None:
+            return None
+        return Session(
+            id=row[0],
+            project=row[1],
+            started_at=datetime.fromtimestamp(row[2]),
+            stopped_at=datetime.fromtimestamp(row[3]) if row[3] is not None else None,
+            canceled_at=datetime.fromtimestamp(row[4]) if row[4] is not None else None,
+        )
+
+    def canceled_session(self) -> Session | None:
+        cursor = self._connection.execute(
+            """
+            SELECT id, project, started_at, stopped_at, canceled_at
+            FROM sessions
+            WHERE canceled_at IS NOT NULL
+            AND stopped_at IS NULL
+            ORDER BY started_at DESC
+            LIMIT 1
+            """
+        )
+        row = cursor.fetchone()
+        if row is None:
+            return None
+        return Session(
+            id=row[0],
+            project=row[1],
+            started_at=datetime.fromtimestamp(row[2]),
+            stopped_at=datetime.fromtimestamp(row[3]) if row[3] is not None else None,
+            canceled_at=datetime.fromtimestamp(row[4]) if row[4] is not None else None,
+        )
+
+    def sessions(self, project: str | None = None) -> list[Session]:
+        query = """
+            SELECT id, project, started_at, stopped_at, canceled_at
+            FROM sessions
+            WHERE canceled_at IS NULL
+        """
+        parameters: tuple[str, ...] = ()
+        if project is not None:
+            query += " AND project = ?"
+            parameters = (project,)
+        query += " ORDER BY started_at ASC"
+
+        cursor = self._connection.execute(query, parameters)
+        return [
+            Session(
+                id=row[0],
+                project=row[1],
+                started_at=datetime.fromtimestamp(row[2]),
+                stopped_at=datetime.fromtimestamp(row[3]) if row[3] is not None else None,
+                canceled_at=datetime.fromtimestamp(row[4]) if row[4] is not None else None,
+            )
+            for row in cursor.fetchall()
+        ]
+
+    def close(self):
+        self._connection.close()
+
+    def start_session(
+        self,
+        project: str | None,
+        datetime: datetime | timedelta | None = None,
+    ):
+        if self._active_session_id() is not None:
+            raise ActiveSessionError("A session is already running")
+
+        self._remove_canceled_sessions()
+        cursor = self._connection.execute(
+            """
+            INSERT INTO sessions (id, project, started_at)
+            VALUES (?, ?, ?)
+            RETURNING id
+            """,
+            (str(uuid4()), project, to_timestamp(datetime)),
+        )
+        return cursor.fetchone()[0]
+
+    def stop_session(
+        self,
+        datetime: datetime | timedelta | None = None,
+    ):
+        session_id = self._active_session_id()
+        if session_id is None:
+            raise NoActiveSessionError("No active session")
+
+        self._connection.execute(
+            """
+            UPDATE sessions
+            SET stopped_at = ?
+            WHERE id = ?
+            """,
+            (to_timestamp(datetime), session_id),
+        )
+        return session_id
+
+    def resume_session(
+        self,
+        stop_now: bool = False,
+    ):
+        if self._active_session_id() is not None:
+            raise ActiveSessionError("A session is already running")
+
+        session_id = self._stopped_session_id()
+        if session_id is None:
+            raise NoStoppedSessionError("No stopped session")
+
+        if stop_now:
+            self._connection.execute(
+                """
+                UPDATE sessions
+                SET stopped_at = ?
+                WHERE id = ?
+                """,
+                (to_timestamp(None), session_id),
+            )
+        else:
+            self._connection.execute(
+                """
+                UPDATE sessions
+                SET stopped_at = NULL
+                WHERE id = ?
+                """,
+                (session_id,),
+            )
+        return session_id
+
+    def cancel_session(
+        self,
+    ):
+        session_id = self._active_session_id()
+        if session_id is None:
+            raise NoActiveSessionError("No active session")
+
+        self._connection.execute(
+            """
+            UPDATE sessions
+            SET canceled_at = ?
+            WHERE id = ?
+            """,
+            (to_timestamp(None), session_id),
+        )
+        return session_id
+
+    def restore_session(
+        self,
+        stopped: bool = False,
+    ):
+        session_id = self._canceled_session_id()
+        if session_id is None:
+            raise NoCanceledSessionError("No canceled session")
+
+        if stopped:
+            self._connection.execute(
+                """
+                UPDATE sessions
+                SET stopped_at = canceled_at,
+                    canceled_at = NULL
+                WHERE id = ?
+                """,
+                (session_id,),
+            )
+            return session_id
+
+        self._connection.execute(
+            """
+            UPDATE sessions
+            SET canceled_at = NULL
+            WHERE id = ?
+            """,
+            (session_id,),
+        )
+        return session_id
+
+    def _validate_import_session(
+        self,
+        session: Any,
+        index: int,
+    ) -> dict[str, Any]:
+        if not isinstance(session, dict):
+            raise ValueError(f"Session {index}: must be an object")
+
+        session_id = session.get("id")
+        if not isinstance(session_id, str) or session_id == "":
+            raise ValueError(f"Session {index}: id must be a non-empty string")
+
+        project = session.get("project")
+        if project is not None and not isinstance(project, str):
+            raise ValueError(f"Session {index}: project must be a string or null")
+
+        started_at = session.get("started_at")
+        stopped_at = session.get("stopped_at")
+        canceled_at = session.get("canceled_at")
+
+        if not isinstance(started_at, int) or isinstance(started_at, bool):
+            raise ValueError(f"Session {index}: started_at must be an integer timestamp")
+        if stopped_at is not None and (
+            not isinstance(stopped_at, int) or isinstance(stopped_at, bool)
+        ):
+            raise ValueError(f"Session {index}: stopped_at must be an integer timestamp or null")
+        if canceled_at is not None and (
+            not isinstance(canceled_at, int) or isinstance(canceled_at, bool)
+        ):
+            raise ValueError(f"Session {index}: canceled_at must be an integer timestamp or null")
+
+        if stopped_at is not None and canceled_at is not None:
+            raise ValueError(f"Session {index}: canceled sessions must have stopped_at set to null")
+        if stopped_at is not None and started_at > stopped_at:
+            raise ValueError(f"Session {index}: started_at cannot be after stopped_at")
+        if canceled_at is not None and started_at > canceled_at:
+            raise ValueError(f"Session {index}: started_at cannot be after canceled_at")
+
+        return {
+            "id": session_id,
+            "project": project,
+            "started_at": started_at,
+            "stopped_at": stopped_at,
+            "canceled_at": canceled_at,
+        }
+
+    def import_sessions(self, sessions: list[dict[str, Any]]) -> tuple[int, int]:
+        if not isinstance(sessions, list):
+            raise ValueError("Import sessions must be a list")
+
+        sessions = [
+            self._validate_import_session(session, index)
+            for index, session in enumerate(sessions, start=1)
+        ]
+
+        active_count = sum(
+            session.get("stopped_at") is None and session.get("canceled_at") is None
+            for session in sessions
+        )
+        canceled_count = sum(
+            session.get("canceled_at") is not None for session in sessions
+        )
+
+        if active_count > 1:
+            raise ActiveSessionError("Import contains more than one active session")
+        if active_count == 1 and self._active_session_id() is not None:
+            raise ActiveSessionError("A session is already running")
+        if canceled_count > 1:
+            raise NoCanceledSessionError(
+                "Import contains more than one canceled session"
+            )
+        if canceled_count == 1 and self._canceled_session_id() is not None:
+            raise NoCanceledSessionError("A canceled session already exists")
+
+        imported = 0
+        skipped = 0
+        for session in sessions:
+            cursor = self._connection.execute(
+                """
+                INSERT OR IGNORE INTO sessions (
+                    id,
+                    project,
+                    started_at,
+                    stopped_at,
+                    canceled_at
+                )
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                (
+                    session["id"],
+                    session.get("project"),
+                    session["started_at"],
+                    session.get("stopped_at"),
+                    session.get("canceled_at"),
+                ),
+            )
+            if cursor.rowcount == 0:
+                skipped += 1
+            else:
+                imported += 1
+        return imported, skipped

clockin/exceptions.py

@@ -0,0 +1,18 @@
+class ClockinError(Exception):
+    pass
+
+
+class ActiveSessionError(ClockinError):
+    pass
+
+
+class NoActiveSessionError(ClockinError):
+    pass
+
+
+class NoCanceledSessionError(ClockinError):
+    pass
+
+
+class NoStoppedSessionError(ClockinError):
+    pass

clockin/main.py

@@ -0,0 +1,519 @@
+import json
+import os
+import shlex
+import subprocess
+from datetime import date, datetime, time, timedelta
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+import typer
+from rich.console import Console, Group
+from rich.json import JSON
+from rich.markup import escape
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from clockin.configuration import (
+    DEFAULT_CONFIGURATION,
+    configuration_path,
+    load_configuration,
+    load_user_configuration,
+    reset_configuration,
+)
+from clockin.db import Connection
+from clockin.exceptions import (
+    ActiveSessionError,
+    NoActiveSessionError,
+    NoCanceledSessionError,
+    NoStoppedSessionError,
+)
+
+app = typer.Typer()
+config_app = typer.Typer()
+app.add_typer(config_app, name="config")
+console = Console()
+error_console = Console(stderr=True)
+configuration = load_configuration()
+style = configuration["styles"][configuration["style"]]
+
+
+def _print_session_feedback(key: str, session_id: str):
+    color, glyph, message = style[key]
+    console.print(
+        f"[bold {color}]{glyph} {message}[/bold {color}] [dim]{session_id}[/dim]"
+    )
+
+
+def _print_warning(error: Exception):
+    color, glyph = style["warning"]
+    error_console.print(f"[bold {color}]{glyph} {escape(str(error))}[/bold {color}]")
+
+
+def _parse_import_timestamp(value: Any, field: str, index: int) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        raise ValueError(
+            f"Session {index}: {field} must be a timestamp or ISO datetime"
+        )
+    if isinstance(value, int | float):
+        return int(value)
+    if isinstance(value, str):
+        value = value.strip()
+        if not value:
+            raise ValueError(f"Session {index}: {field} cannot be empty")
+        try:
+            return int(float(value))
+        except ValueError:
+            pass
+        try:
+            return int(datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp())
+        except ValueError as error:
+            raise ValueError(
+                f"Session {index}: {field} must be a timestamp or ISO datetime"
+            ) from error
+    raise ValueError(f"Session {index}: {field} must be a timestamp or ISO datetime")
+
+
+def _load_import_sessions(json_file: Path) -> list[dict[str, Any]]:
+    payload = json.loads(json_file.read_text(encoding="utf-8"))
+    if isinstance(payload, dict):
+        payload = payload.get("sessions")
+    if not isinstance(payload, list):
+        raise ValueError(
+            "Import file must contain a JSON array or an object with sessions"
+        )
+
+    sessions = []
+    for index, session in enumerate(payload, start=1):
+        if not isinstance(session, dict):
+            raise ValueError(f"Session {index}: must be an object")
+
+        started_at = _parse_import_timestamp(
+            session.get("started_at"), "started_at", index
+        )
+        if started_at is None:
+            raise ValueError(f"Session {index}: started_at is required")
+        stopped_at = _parse_import_timestamp(
+            session.get("stopped_at"), "stopped_at", index
+        )
+        canceled_at = _parse_import_timestamp(
+            session.get("canceled_at"), "canceled_at", index
+        )
+        if stopped_at is not None and canceled_at is not None:
+            raise ValueError(
+                f"Session {index}: canceled sessions must have stopped_at set to null"
+            )
+
+        session_id = session.get("id") or str(uuid4())
+        if not isinstance(session_id, str):
+            raise ValueError(f"Session {index}: id must be a string")
+        project = session.get("project")
+        if project is not None and not isinstance(project, str):
+            raise ValueError(f"Session {index}: project must be a string or null")
+
+        sessions.append(
+            {
+                "id": session_id,
+                "project": project,
+                "started_at": started_at,
+                "stopped_at": stopped_at,
+                "canceled_at": canceled_at,
+            }
+        )
+    return sessions
+
+
+@config_app.command("show")
+def config_show(
+    show_full: bool = typer.Option(False, "--full"),
+    show_default: bool = typer.Option(False, "--default"),
+):
+    configuration = load_user_configuration()
+    if show_full:
+        configuration = load_configuration()
+    if show_default:
+        configuration = DEFAULT_CONFIGURATION
+    console.print(JSON(json.dumps(configuration, indent=2)))
+
+
+@config_app.command("edit")
+def config_edit():
+    load_configuration()
+    editor = os.environ.get("VISUAL") or os.environ.get("EDITOR")
+    if editor is None:
+        _print_warning(RuntimeError("Set VISUAL or EDITOR to edit configuration"))
+        raise typer.Exit(1)
+
+    try:
+        result = subprocess.run(
+            [*shlex.split(editor), str(configuration_path)],
+            check=False,
+        )
+    except OSError as error:
+        _print_warning(error)
+        raise typer.Exit(1) from error
+
+    if result.returncode != 0:
+        _print_warning(RuntimeError(f"Editor exited with {result.returncode}"))
+        raise typer.Exit(result.returncode)
+
+    console.print(
+        f"[bold green]✓ Edited configuration[/bold green] [white dim]{configuration_path}[/white dim]"
+    )
+
+
+@config_app.command("reset")
+def config_reset():
+    reset_configuration()
+    console.print(
+        f"[bold green]✓ Reset configuration[/bold green] [white dim]{configuration_path}[/white dim]"
+    )
+
+
+@app.command()
+def start(project: str | None = typer.Argument(None)):
+    try:
+        with Connection() as connection:
+            session_id = connection.start_session(project)
+    except ActiveSessionError as error:
+        _print_warning(error)
+        raise typer.Exit(1) from error
+
+    _print_session_feedback("started", session_id)
+
+
+@app.command()
+def stop():
+    try:
+        with Connection() as connection:
+            session_id = connection.stop_session()
+    except NoActiveSessionError as error:
+        _print_warning(error)
+        raise typer.Exit(1) from error
+
+    _print_session_feedback("stopped", session_id)
+
+
+@app.command()
+def resume(stop_now: bool = typer.Option(False, "--stop-now")):
+    try:
+        with Connection() as connection:
+            session_id = connection.resume_session(stop_now=stop_now)
+    except (ActiveSessionError, NoStoppedSessionError) as error:
+        _print_warning(error)
+        raise typer.Exit(1) from error
+
+    if stop_now:
+        _print_session_feedback("stopped_updated", session_id)
+        return
+
+    _print_session_feedback("resumed", session_id)
+
+
+@app.command()
+def cancel():
+    try:
+        with Connection() as connection:
+            session_id = connection.cancel_session()
+    except NoActiveSessionError as error:
+        _print_warning(error)
+        raise typer.Exit(1) from error
+
+    _print_session_feedback("canceled", session_id)
+
+
+@app.command()
+def restore(stopped: bool = typer.Option(False, "--stopped")):
+    try:
+        with Connection() as connection:
+            session_id = connection.restore_session(stopped=stopped)
+    except (ActiveSessionError, NoCanceledSessionError) as error:
+        _print_warning(error)
+        raise typer.Exit(1) from error
+
+    if stopped:
+        color, glyph, message = style["restored_stopped"]
+        note_color, note_glyph, note = style["restored_stopped_note"]
+        console.print(
+            f"[bold {color}]{glyph} {message}[/bold {color}] [dim]{session_id}[/dim]\n"
+            f"[{note_color}]{note_glyph}[/{note_color}] [dim]{note}[/dim]"
+        )
+        return
+
+    _print_session_feedback("restored", session_id)
+
+
+@app.command("import")
+def import_sessions(json_file: Path = typer.Argument(..., exists=True, dir_okay=False)):
+    try:
+        sessions = _load_import_sessions(json_file)
+        with Connection() as connection:
+            imported, skipped = connection.import_sessions(sessions)
+            active_session = connection.active_session()
+            canceled_session = connection.canceled_session()
+    except (
+        OSError,
+        ValueError,
+        ActiveSessionError,
+        NoCanceledSessionError,
+    ) as error:
+        _print_warning(error)
+        raise typer.Exit(1) from error
+
+    color, glyph = "yellow", "!"
+    if active_session is not None:
+        color, glyph = "green", "✓"
+    elif canceled_session is not None:
+        color, glyph = "red", "×"
+
+    console.print(
+        f"[bold {color}]{glyph} Imported {imported} session{'s' if imported != 1 else ''}[/bold {color}]"
+        f" [dim]({skipped} skipped)[/dim]"
+    )
+
+
+@app.command()
+def status():
+    with Connection() as connection:
+        session = connection.active_session()
+        canceled_session = connection.canceled_session()
+
+    if session is None:
+        if canceled_session is not None:
+            title_color, title_glyph, title = style["canceled_title"]
+            table = Table.grid(padding=(0, 2))
+            table.add_column(style="bold cyan")
+            table.add_column()
+            table.add_row("Session", f"[dim]{canceled_session.id}[/dim]")
+            if canceled_session.project is not None:
+                table.add_row("Project", escape(canceled_session.project))
+            table.add_row("Started", f"{canceled_session.started_at:%Y-%m-%d %H:%M:%S}")
+            if canceled_session.canceled_at is not None:
+                table.add_row(
+                    "Canceled",
+                    f"[bold red]{canceled_session.canceled_at:%Y-%m-%d %H:%M:%S}[/bold red]",
+                )
+
+            console.print(
+                Panel(
+                    table,
+                    title=f"[bold {title_color}]{title_glyph} {title}[/bold {title_color}]",
+                    border_style=title_color,
+                )
+            )
+            return
+
+        color, glyph, message = style["no_active"]
+        console.print(f"[bold {color}]{glyph} {message}[/bold {color}]")
+        return
+
+    elapsed = datetime.now() - session.started_at
+
+    table = Table.grid(padding=(0, 2))
+    table.add_column(style="bold cyan")
+    table.add_column()
+    table.add_row("Session", f"[dim]{session.id}[/dim]")
+    if session.project is not None:
+        table.add_row("Project", escape(session.project))
+    table.add_row("Started", f"{session.started_at:%Y-%m-%d %H:%M:%S}")
+    table.add_row("Elapsed", f"[bold green]{_format_duration(elapsed)}[/bold green]")
+
+    title_color, title_glyph, title = style["active_title"]
+    console.print(
+        Panel(
+            table,
+            title=f"[bold {title_color}]{title_glyph} {title}[/bold {title_color}]",
+            border_style=title_color,
+        )
+    )
+
+
+WEEKDAY_LABELS = ("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")
+WEEKDAY_NAMES = (
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday",
+    "Sunday",
+)
+HEATMAP_EMPTY_COLOR = "grey27"
+HEATMAP_GLYPH = "■"
+
+
+def _format_duration(elapsed: timedelta) -> str:
+    total_seconds = int(elapsed.total_seconds())
+    hours, remainder = divmod(total_seconds, 3600)
+    minutes, seconds = divmod(remainder, 60)
+    return f"{hours:02d}:{minutes:02d}:{seconds:02d}"
+
+
+def _split_by_day(
+    started_at: datetime, ended_at: datetime
+) -> list[tuple[date, timedelta]]:
+    segments = []
+    current = started_at
+    while current < ended_at:
+        next_midnight = datetime.combine(current.date() + timedelta(days=1), time.min)
+        segment_end = min(ended_at, next_midnight)
+        segments.append((current.date(), segment_end - current))
+        current = segment_end
+    return segments
+
+
+def _green_shade(ratio: float) -> str:
+    ratio = max(0.0, min(ratio, 1.0))
+    green = round(70 + (255 - 70) * ratio)
+    return f"#00{green:02x}00"
+
+
+def _heatmap_color(seconds: float, max_seconds: float) -> str:
+    if seconds <= 0 or max_seconds <= 0:
+        return HEATMAP_EMPTY_COLOR
+    return _green_shade(seconds / max_seconds)
+
+
+def _render_heatmap(daily_totals: dict[date, timedelta], weeks: int) -> Text:
+    end_date = date.today()
+    start_date = end_date - timedelta(days=weeks * 7 - 1)
+    grid = [
+        [start_date + timedelta(days=column * 7 + row) for row in range(7)]
+        for column in range(weeks)
+    ]
+    max_seconds = max(
+        (
+            daily_totals.get(day, timedelta()).total_seconds()
+            for column in grid
+            for day in column
+        ),
+        default=0.0,
+    )
+
+    heatmap = Text()
+    for row in range(7):
+        heatmap.append(f"{WEEKDAY_LABELS[grid[0][row].weekday()]} ", style="dim")
+        for column in grid:
+            seconds = daily_totals.get(column[row], timedelta()).total_seconds()
+            heatmap.append(
+                f"{HEATMAP_GLYPH} ", style=_heatmap_color(seconds, max_seconds)
+            )
+        heatmap.append("\n")
+
+    heatmap.append("    Less ", style="dim")
+    heatmap.append(f"{HEATMAP_GLYPH} ", style=HEATMAP_EMPTY_COLOR)
+    for ratio in (0.25, 0.5, 0.75, 1.0):
+        heatmap.append(f"{HEATMAP_GLYPH} ", style=_green_shade(ratio))
+    heatmap.append("More", style="dim")
+    return heatmap
+
+
+@app.command()
+def report(
+    project: str | None = typer.Option(None, "--project"),
+    weeks: int = typer.Option(20, "--weeks"),
+):
+    weeks = max(weeks, 1)
+
+    with Connection() as connection:
+        sessions = connection.sessions(project=project)
+
+    if not sessions:
+        color, glyph, message = style["no_sessions"]
+        console.print(f"[bold {color}]{glyph} {message}[/bold {color}]")
+        return
+
+    now = datetime.now()
+    project_totals: dict[str | None, tuple[int, timedelta]] = {}
+    daily_totals: dict[date, timedelta] = {}
+    weekday_totals: dict[int, timedelta] = {}
+    hour_totals: dict[int, timedelta] = {}
+
+    for session in sessions:
+        effective_end = session.stopped_at or now
+        elapsed = effective_end - session.started_at
+
+        count, total = project_totals.get(session.project, (0, timedelta()))
+        project_totals[session.project] = (count + 1, total + elapsed)
+
+        hour_totals[session.started_at.hour] = (
+            hour_totals.get(session.started_at.hour, timedelta()) + elapsed
+        )
+
+        for day, duration in _split_by_day(session.started_at, effective_end):
+            daily_totals[day] = daily_totals.get(day, timedelta()) + duration
+            weekday_totals[day.weekday()] = (
+                weekday_totals.get(day.weekday(), timedelta()) + duration
+            )
+
+    grand_count = sum(count for count, _ in project_totals.values())
+    grand_total = sum((total for _, total in project_totals.values()), timedelta())
+
+    table = Table.grid(padding=(0, 2))
+    table.add_column(style="bold cyan")
+    table.add_column(justify="right")
+    table.add_column(justify="right")
+    table.add_column(justify="right")
+    table.add_column(justify="right")
+    table.add_row(
+        "[dim]Project[/dim]",
+        "[dim]Sessions[/dim]",
+        "[dim]Total[/dim]",
+        "[dim]Avg[/dim]",
+        "[dim]%[/dim]",
+    )
+
+    for session_project, (count, total) in sorted(
+        project_totals.items(), key=lambda item: item[1][1], reverse=True
+    ):
+        percentage = total / grand_total * 100 if grand_total else 0.0
+        label = (
+            escape(session_project)
+            if session_project is not None
+            else "[dim](no project)[/dim]"
+        )
+        table.add_row(
+            label,
+            f"{count} session{'s' if count != 1 else ''}",
+            _format_duration(total),
+            _format_duration(total / count),
+            f"{percentage:.1f}%",
+        )
+
+    table.add_row(
+        "[bold]Total[/bold]",
+        f"[bold]{grand_count} session{'s' if grand_count != 1 else ''}[/bold]",
+        f"[bold]{_format_duration(grand_total)}[/bold]",
+        f"[bold]{_format_duration(grand_total / grand_count)}[/bold]",
+        "[bold]100.0%[/bold]",
+    )
+
+    insights = Text()
+    if weekday_totals:
+        busiest_weekday = max(weekday_totals, key=weekday_totals.get)
+        insights.append("Busiest day    ", style="bold cyan")
+        insights.append(
+            f"{WEEKDAY_NAMES[busiest_weekday]} · "
+            f"{_format_duration(weekday_totals[busiest_weekday])}\n"
+        )
+    if hour_totals:
+        busiest_hour = max(hour_totals, key=hour_totals.get)
+        insights.append("Busiest hour   ", style="bold cyan")
+        insights.append(
+            f"{busiest_hour:02d}:00-{(busiest_hour + 1) % 24:02d}:00 · "
+            f"{_format_duration(hour_totals[busiest_hour])}"
+        )
+
+    heatmap = _render_heatmap(daily_totals, weeks)
+
+    title_color, title_glyph, title = style["report_title"]
+    console.print(
+        Panel(
+            Group(table, "", insights, "", heatmap),
+            title=f"[bold {title_color}]{title_glyph} {title}[/bold {title_color}]",
+            border_style=title_color,
+        )
+    )

clockin/utils.py

@@ -0,0 +1,10 @@
+from datetime import datetime, timedelta
+
+
+def to_timestamp(value: datetime | timedelta | None) -> int:
+    if value is None:
+        return int(datetime.now().timestamp())
+    if isinstance(value, datetime):
+        return int(value.timestamp())
+    if isinstance(value, timedelta):
+        return int((datetime.now() + value).timestamp())

clockin_tracker-0.1.0.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.3
+Name: clockin-tracker
+Version: 0.1.0
+Summary: Add your description here
+Author: Markos Narinian
+Author-email: Markos Narinian <manarinian@gmail.com>
+Requires-Dist: platformdirs>=4.10.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.26.8
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# clockin
+
+[![Upload Python Package](https://github.com/markosnarinian/clockin/actions/workflows/python-publish.yml/badge.svg)](https://github.com/markosnarinian/clockin/actions/workflows/python-publish.yml)
+
+**Time to (c)lock in!**
+
+Welcome to a micro-project of mine!
+I've wanted to build a time tracker for a while. It annoys me that every time tracker I've tried is either built for professionals/freelancers, or, in the case of TUI time trackers, built for devs tracking tasks (who cares!). I do a loooot of things and have backlogs full of hundreds of ideas. This is why I want to track time spent working on my projects vs working out/relaxing/reading vs sleeping vs wasting time, along with % time allocation by activity type and by project. And who doesn't like an activity heatmap?
+It took me this long to build because I wanted to create proper apps for all platforms, but I decided I need this now — so I put it under micro-projects on my priorities list and built it as a terminal application (full TUI coming, relatively soon!).
+
+## Installation
+
+clockin is published on PyPI as `clockin-tracker`.
+
+**uv (recommended)**
+
+```sh
+# Install it as a standalone CLI tool
+uv tool install clockin-tracker
+
+# ...or run it without installing anything
+uvx clockin-tracker clockin --help
+```
+
+**pipx**
+
+```sh
+pipx install clockin-tracker
+```
+
+**From source (for development/testing)**
+
+```sh
+git clone https://github.com/markosnarinian/clockin
+cd clockin
+uv sync
+uv run clockin --help
+```
+
+## Quick start
+
+```sh
+$ clockin start clockin
+✓ Started session 3f9a1c2e-...
+
+$ clockin status
+╭─ ▶ Active session ─────────────╮
+│ Session   3f9a1c2e-...         │
+│ Project   clockin              │
+│ Started   2026-07-08 09:00:00  │
+│ Elapsed   00:12:34             │
+╰────────────────────────────────╯
+
+$ clockin stop
+■ Stopped session 3f9a1c2e-...
+```
+
+Prefer emoji over checkmarks? Switch to the built-in `quirky` style — see [Configuration](#configuration).
+
+## Commands
+
+| Command                                             | Description                                                                                                           |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `clockin start [PROJECT]`                           | Start a new session, optionally tagged with a project name. Fails if a session is already running.                    |
+| `clockin stop`                                      | Stop the active session.                                                                                              |
+| `clockin status`                                    | Show the active session (with elapsed time) or a pending canceled session.                                            |
+| `clockin resume [--stop-now]`                       | Resume the most recently stopped session. With `--stop-now`, immediately re-stops it (e.g. to backdate a correction). |
+| `clockin cancel`                                    | Cancel the active session instead of stopping it.                                                                     |
+| `clockin restore [--stopped]`                       | Restore the pending canceled session. With `--stopped`, restore it as stopped instead of active.                      |
+| `clockin import FILE`                               | Bulk-import sessions from a JSON file. See [Importing sessions](#importing-sessions).                                 |
+| `clockin config show [--full] [--default]`          | Print your configuration, the full merged configuration, or the built-in defaults.                                   |
+| `clockin config edit`                               | Open the config file in `$VISUAL`/`$EDITOR`.                                                                          |
+| `clockin config reset`                              | Reset configuration to defaults.                                                                                      |
+
+## Session lifecycle
+
+At most one session can be active at a time, and at most one canceled session can be pending restoration at a time:
+
+```
+start ──▶ active ──stop──▶ stopped ──resume──▶ active
+             │
+           cancel
+             │
+             ▼
+          canceled ──restore──▶ active
+             │
+             └──restore --stopped──▶ stopped
+```
+
+Starting a new session discards any pending canceled session, so restore it first if you want to keep it.
+
+## Importing sessions
+
+`clockin import FILE` reads a JSON array of sessions, or an object with a `sessions` array (see [sample.json](sample.json)):
+
+```json
+{
+  "sessions": [
+    {
+      "id": "work-session-001",
+      "project": "clockin",
+      "started_at": "2026-01-01T09:00:00Z",
+      "stopped_at": "2026-01-01T10:30:00Z",
+      "canceled_at": null
+    }
+  ]
+}
+```
+
+- `started_at` is required; `stopped_at`/`canceled_at` are optional but mutually exclusive.
+- Timestamps accept a Unix timestamp or an ISO-8601 datetime string.
+- `id` is optional (a UUID is generated if omitted); `project` is optional.
+- At most one imported session may be active, and at most one may be canceled — and only if you don't already have one of that kind.
+- Sessions with an `id` that already exists are skipped, so imports are safe to re-run.
+
+### Importing from other software
+
+When moving history from another time tracker, calendar, spreadsheet, or database, convert the source export into clockin's import JSON first. Use stable IDs from the original software when possible, optionally prefixed with the source name (for example, `toggl-123456`), so you can safely re-run the same import without duplicating sessions.
+
+Map each source entry to one clockin session state:
+
+- completed entries become stopped sessions with `started_at` and `stopped_at` set;
+- one open/running entry may become an active session with both `stopped_at` and `canceled_at` set to `null`;
+- deleted or voided entries should usually be skipped unless you intentionally want one represented as the single pending canceled session.
+
+Prefer ISO-8601 timestamps with explicit timezones (`2026-01-01T09:00:00-05:00` or `2026-01-01T14:00:00Z`) when converting from software that exports local times. If the source only has a duration, compute `stopped_at` from `started_at + duration`.
+
+Agents helping with imports should use the project skill in [`skills/importing-sessions/SKILL.md`](skills/importing-sessions/SKILL.md) for the full conversion workflow, validation checklist, and safety guidance before running `clockin import`.
+
+## Configuration
+
+clockin stores its config as JSON in a per-OS config directory. Run `clockin config edit` to open it in `$VISUAL`/`$EDITOR`, or `clockin config reset` to restore the defaults.
+
+| Key               | Default     | Description                                                                                    |
+| ----------------- | ----------- | ---------------------------------------------------------------------------------------------- |
+| `style`           | `"default"` | Which output style to use: `"default"` (plain glyphs) or `"quirky"` (emoji, more personality). |
+| `default_project` | `null`      | Reserved for a future default project on `clockin start`. Not enforced yet.                    |
+| `require_project` | `true`      | Reserved for making `clockin start` require a project. Not enforced yet.                       |
+
+Run `clockin config show --default` to see the full built-in configuration, including the `styles` definitions themselves (colors, glyphs, and messages per state) if you want to customize them.
+
+## Data storage
+
+Sessions are stored in a SQLite database in a per-OS data directory, versioned by schema (currently `clockin.v1.0.db`). Back it up like any other file — there's no built-in export command yet, but `clockin import` can be used in reverse by reading the database directly with any SQLite client.
+
+## Development
+
+```sh
+git clone https://github.com/markosnarinian/clockin
+cd clockin
+uv sync
+uv run pytest
+uv run ruff check .
+uv run ruff format .
+uv run clockin --help
+```
+
+## License
+
+[AGPL-3.0](LICENSE)

clockin_tracker-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+clockin/__init__.py,sha256=V_dR1LcNzya-t5vSHLiwz1_LUvyloTdMrnWIuAlC64A,113
+clockin/configuration.py,sha256=VVfZsXjAPl2NJ61PFldfAoq9Uubqq9_uEEiXCJhzvts,3714
+clockin/db.py,sha256=vsz2325XDpMoN-8jOzwIMnhY0oJv4cHBdL4LvaSU2W8,12680
+clockin/exceptions.py,sha256=3RrlcDwH-rnyD5moMrONkGZNjNT5zrHiPxs4ttT0ZYc,253
+clockin/main.py,sha256=rzwqG4sRLp3pZlSzyk8hQNPPrMoKAKRBR5LMib_Gpjc,16891
+clockin/utils.py,sha256=bj9A_3BwpOcarezOlMS5Q-vHTQTxePAOEmHPCFnH1qE,341
+clockin_tracker-0.1.0.dist-info/WHEEL,sha256=CoDSoyhtC_eO_tlxRYzsTraPv1fPJRXFx91k6ISeAvA,81
+clockin_tracker-0.1.0.dist-info/entry_points.txt,sha256=Nlh9EIsIVPScXTXW79Kfl6sHw3z492Hq7Q9IuSJlRHw,42
+clockin_tracker-0.1.0.dist-info/METADATA,sha256=q4cTLOEZ41VyBhrtUIVk4TSp2CWRmxa33LDzwku2CTQ,8736
+clockin_tracker-0.1.0.dist-info/RECORD,,

clockin_tracker-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.28
+Root-Is-Purelib: true
+Tag: py3-none-any

clockin_tracker-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+clockin = clockin:main
+