timing-cli 0.1.0__py3-none-any.whl

timing_cli/db.py

@@ -0,0 +1,287 @@
+"""Read-only access to the local Timing.app SQLite database.
+
+Timing stores its automatically recorded app activity in a Core-Data SQLite
+store (``SQLite.db``). We open it strictly read-only so we never interfere with
+Timing's own writes or its sync engine.
+
+Key schema facts (Timing2):
+  * ``AppActivity(startDate, endDate, applicationID, titleID, pathID, projectID,
+    isDeleted)`` — one row per automatically tracked activity slice.
+  * ``startDate`` / ``endDate`` are **Unix epoch seconds** (REAL), NOT Core-Data
+    reference dates. Verified empirically: adding the 978307200 NSDate offset
+    shifts timestamps ~31 years into the future.
+  * ``Application(bundleIdentifier, executable, title)``, ``Title(stringValue)``
+    and ``Path(stringValue)`` are normalized lookup tables.
+  * ``Project(id, title, parentID, color, productivityScore, isArchived)``.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+
+from timing_cli.models import AppUsage, Project
+from timing_cli.timing_predicates import TimingPredicateRule, decode_timing_predicate
+
+
+class TimingDatabaseError(RuntimeError):
+    """Raised when the local Timing database cannot be opened or read."""
+
+
+def _epoch_to_local(value: float) -> datetime:
+    """Convert a Timing Unix-epoch timestamp to an aware local datetime."""
+    return datetime.fromtimestamp(value).astimezone()
+
+
+@contextmanager
+def open_db(db_path: Path) -> Iterator[sqlite3.Connection]:
+    """Open the Timing database read-only.
+
+    We deliberately do NOT copy the database. A read-only URI connection reads
+    the live WAL without taking a write lock, so Timing keeps running normally.
+    """
+    if not db_path.exists():
+        raise TimingDatabaseError(
+            f"Timing database not found at {db_path}. Is Timing.app installed? "
+            "Set db_path in ~/.config/timing-cli/config.toml if it lives elsewhere."
+        )
+    uri = f"file:{db_path}?mode=ro"
+    try:
+        conn = sqlite3.connect(uri, uri=True, timeout=5.0)
+    except sqlite3.OperationalError as exc:  # pragma: no cover - environment specific
+        raise TimingDatabaseError(f"Could not open Timing database read-only: {exc}") from exc
+    conn.row_factory = sqlite3.Row
+    try:
+        yield conn
+    finally:
+        conn.close()
+
+
+def list_projects(conn: sqlite3.Connection, include_archived: bool = True) -> list[Project]:
+    """Return all local projects, ordered by hierarchy position."""
+    if include_archived:
+        query = """
+        SELECT id, title, parentID, isArchived, color, productivityScore
+        FROM Project
+        ORDER BY parentID IS NOT NULL, listPosition
+        """
+    else:
+        query = """
+        SELECT id, title, parentID, isArchived, color, productivityScore
+        FROM Project
+        WHERE isArchived = 0
+        ORDER BY parentID IS NOT NULL, listPosition
+        """
+    rows = conn.execute(query).fetchall()
+    return [
+        Project(
+            id=r["id"],
+            title=r["title"],
+            parent_id=r["parentID"],
+            is_archived=bool(r["isArchived"]),
+            color=r["color"],
+            productivity_score=r["productivityScore"] or 0.0,
+        )
+        for r in rows
+    ]
+
+
+def _project_title_chains(
+    conn: sqlite3.Connection,
+    project_ids: set[int],
+) -> dict[int, list[str]]:
+    """Return local project title chains keyed by local project id."""
+    projects: dict[int, tuple[str, int | None]] = {}
+
+    def fetch(project_id: int) -> tuple[str, int | None] | None:
+        if project_id in projects:
+            return projects[project_id]
+
+        row = conn.execute(
+            "SELECT title, parentID FROM Project WHERE id = ?",
+            (project_id,),
+        ).fetchone()
+        if row is None:
+            return None
+        project = (row["title"], row["parentID"])
+        projects[project_id] = project
+        return project
+
+    chains: dict[int, list[str]] = {}
+
+    def build(project_id: int) -> list[str]:
+        if project_id in chains:
+            return chains[project_id]
+
+        seen: set[int] = set()
+        chain: list[str] = []
+        current: int | None = project_id
+        while current is not None and current not in seen:
+            seen.add(current)
+            project = fetch(current)
+            if project is None:
+                break
+            title, parent_id = project
+            chain.append(title)
+            current = parent_id
+
+        chain.reverse()
+        chains[project_id] = chain
+        return chain
+
+    return {project_id: build(project_id) for project_id in project_ids}
+
+
+def list_app_usage(
+    conn: sqlite3.Connection,
+    start: datetime,
+    end: datetime,
+    project_id: int | None = None,
+) -> list[AppUsage]:
+    """Return automatically tracked app usage overlapping ``[start, end)``.
+
+    A slice is included when it overlaps the window at all (its start is before
+    ``end`` and its end is after ``start``).
+    """
+    if end <= start:
+        return []
+
+    params: list[float | int] = [end.timestamp(), start.timestamp()]
+    if project_id is None:
+        query = """
+        SELECT
+            a.id            AS id,
+            a.startDate     AS start_ts,
+            a.endDate       AS end_ts,
+            a.applicationID  AS application_id,
+            a.projectID     AS project_id,
+            p.title         AS project_title,
+            app.title       AS app_title,
+            app.bundleIdentifier AS bundle_id,
+            app.executable  AS executable,
+            t.stringValue   AS window_title,
+            pa.stringValue  AS doc_path
+        FROM AppActivity a
+        JOIN Application app ON app.id = a.applicationID
+        LEFT JOIN Title   t  ON t.id  = a.titleID
+        LEFT JOIN Path    pa ON pa.id = a.pathID
+        LEFT JOIN Project p  ON p.id  = a.projectID
+        WHERE a.isDeleted = 0
+          AND a.startDate < ?
+          AND a.endDate   > ?
+        ORDER BY a.startDate
+        """
+    else:
+        query = """
+        SELECT
+            a.id            AS id,
+            a.startDate     AS start_ts,
+            a.endDate       AS end_ts,
+            a.applicationID  AS application_id,
+            a.projectID     AS project_id,
+            p.title         AS project_title,
+            app.title       AS app_title,
+            app.bundleIdentifier AS bundle_id,
+            app.executable  AS executable,
+            t.stringValue   AS window_title,
+            pa.stringValue  AS doc_path
+        FROM AppActivity a
+        JOIN Application app ON app.id = a.applicationID
+        LEFT JOIN Title   t  ON t.id  = a.titleID
+        LEFT JOIN Path    pa ON pa.id = a.pathID
+        LEFT JOIN Project p  ON p.id  = a.projectID
+        WHERE a.isDeleted = 0
+          AND a.startDate < ?
+          AND a.endDate   > ?
+          AND a.projectID = ?
+        ORDER BY a.startDate
+        """
+        params.append(project_id)
+
+    rows = conn.execute(query, params).fetchall()
+
+    project_ids = {r["project_id"] for r in rows if r["project_id"] is not None}
+    title_chains = _project_title_chains(conn, project_ids)
+    usage: list[AppUsage] = []
+    for r in rows:
+        app_name = r["app_title"] or r["bundle_id"] or r["executable"] or "Unknown"
+        clipped_start = max(_epoch_to_local(r["start_ts"]), start)
+        clipped_end = min(_epoch_to_local(r["end_ts"]), end)
+        if clipped_end <= clipped_start:
+            continue
+        project_title_chain = title_chains.get(r["project_id"], [])
+        project_title = r["project_title"]
+        if project_title and not project_title_chain:
+            project_title_chain = [project_title]
+        usage.append(
+            AppUsage(
+                id=r["id"],
+                start=clipped_start,
+                end=clipped_end,
+                application_id=r["application_id"],
+                app=app_name,
+                bundle_id=r["bundle_id"],
+                title=r["window_title"],
+                path=r["doc_path"],
+                project_id=r["project_id"],
+                project_title=project_title,
+                project_title_chain=project_title_chain,
+            )
+        )
+    return usage
+
+
+def list_timing_predicate_rules(
+    conn: sqlite3.Connection,
+    include_archived: bool = False,
+) -> list[TimingPredicateRule]:
+    """Return decoded Timing project predicate rules from the local database."""
+    project_columns = {r["name"] for r in conn.execute("PRAGMA table_info(Project)")}
+    if "predicate" not in project_columns:
+        return []
+
+    if include_archived:
+        query = """
+        SELECT id, title, predicate
+        FROM Project
+        WHERE predicate IS NOT NULL
+        ORDER BY ruleListPosition, listPosition
+        """
+    else:
+        query = """
+        SELECT id, title, predicate
+        FROM Project
+        WHERE predicate IS NOT NULL AND isArchived = 0
+        ORDER BY ruleListPosition, listPosition
+        """
+
+    rows = conn.execute(query).fetchall()
+    title_chains = _project_title_chains(conn, {r["id"] for r in rows})
+    rules: list[TimingPredicateRule] = []
+    for row in rows:
+        conditions = decode_timing_predicate(row["predicate"])
+        if not conditions:
+            continue
+        title_chain = tuple(title_chains.get(row["id"], [row["title"]]))
+        rules.append(
+            TimingPredicateRule(
+                project_id=row["id"],
+                project_title=row["title"],
+                project_title_chain=title_chain,
+                conditions=conditions,
+            )
+        )
+    return rules
+
+
+def date_range(conn: sqlite3.Connection) -> tuple[datetime, datetime] | None:
+    """Return the (earliest start, latest end) of recorded activity, or None."""
+    row = conn.execute(
+        "SELECT MIN(startDate) AS lo, MAX(endDate) AS hi FROM AppActivity WHERE isDeleted = 0"
+    ).fetchone()
+    if row is None or row["lo"] is None:
+        return None
+    return _epoch_to_local(row["lo"]), _epoch_to_local(row["hi"])

timing_cli/models.py

@@ -0,0 +1,89 @@
+"""Pydantic models shared across the CLI, DB layer, analysis and MCP server."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class Project(BaseModel):
+    """A Timing project, as read from the local database."""
+
+    id: int
+    title: str
+    parent_id: int | None = None
+    is_archived: bool = False
+    color: str | None = None
+    productivity_score: float = 0.0
+
+    @property
+    def api_ref(self) -> str:
+        """Self-reference used by the Timing Web API (e.g. ``/projects/1``).
+
+        NOTE: the local database ``id`` and the Web-API project id are NOT the
+        same namespace. This helper only builds the API path shape; callers that
+        push to the API must map local titles to remote project ids first (see
+        ``timing_cli.api.TimingApiClient.resolve_project_ref``).
+        """
+        return f"/projects/{self.id}"
+
+
+class AppUsage(BaseModel):
+    """A single automatically recorded app-activity slice from the local DB."""
+
+    id: int
+    start: datetime
+    end: datetime
+    application_id: int | None = None
+    app: str = Field(description="Human-readable app name or bundle identifier")
+    bundle_id: str | None = None
+    title: str | None = Field(default=None, description="Window title")
+    path: str | None = Field(default=None, description="Document / file path")
+    project_id: int | None = Field(default=None, description="Local Timing project id, if assigned")
+    project_title: str | None = None
+    project_title_chain: list[str] = Field(default_factory=list)
+
+    @property
+    def duration_seconds(self) -> float:
+        return (self.end - self.start).total_seconds()
+
+
+class TimeEntrySuggestion(BaseModel):
+    """An aggregated block of app usage, ready to become a Timing time entry."""
+
+    day: str = Field(description="ISO date (YYYY-MM-DD, local) the block belongs to")
+    start: datetime
+    end: datetime
+    project_id: int | None = None
+    project_title: str = "Unassigned"
+    project_title_chain: list[str] = Field(default_factory=list)
+    title: str = ""
+    notes: str = ""
+    source_count: int = 0
+    top_apps: list[str] = Field(default_factory=list)
+
+    @property
+    def duration_seconds(self) -> float:
+        return (self.end - self.start).total_seconds()
+
+    @property
+    def duration_minutes(self) -> float:
+        return self.duration_seconds / 60.0
+
+
+class ProjectSummary(BaseModel):
+    """Aggregated time per project for a reporting window."""
+
+    project_id: int | None = None
+    project_title: str = "Unassigned"
+    seconds: float = 0.0
+    entries: int = 0
+
+    @property
+    def minutes(self) -> float:
+        return self.seconds / 60.0
+
+    @property
+    def hours(self) -> float:
+        return self.seconds / 3600.0

timing_cli/output.py

@@ -0,0 +1,78 @@
+"""Rich-based rendering helpers for the CLI."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.table import Table
+
+from timing_cli.models import AppUsage, ProjectSummary, TimeEntrySuggestion
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _fmt_duration(seconds: float) -> str:
+    total = int(round(seconds))
+    hours, rem = divmod(total, 3600)
+    minutes, secs = divmod(rem, 60)
+    if hours:
+        return f"{hours}h {minutes:02d}m"
+    if minutes:
+        return f"{minutes}m {secs:02d}s"
+    return f"{secs}s"
+
+
+def render_usage(usage: list[AppUsage]) -> None:
+    table = Table(title="App usage", show_lines=False)
+    table.add_column("Start", style="cyan", no_wrap=True)
+    table.add_column("Dur", justify="right")
+    table.add_column("App", style="green")
+    table.add_column("Title")
+    table.add_column("Project", style="magenta")
+    for u in usage:
+        table.add_row(
+            u.start.strftime("%H:%M:%S"),
+            _fmt_duration(u.duration_seconds),
+            u.app,
+            (u.title or "")[:50],
+            u.project_title or "",
+        )
+    console.print(table)
+
+
+def render_summary(summaries: list[ProjectSummary], title: str = "Project summary") -> None:
+    table = Table(title=title)
+    table.add_column("Project", style="magenta")
+    table.add_column("Time", justify="right")
+    table.add_column("Slices", justify="right", style="dim")
+    total = 0.0
+    for s in summaries:
+        table.add_row(s.project_title, _fmt_duration(s.seconds), str(s.entries))
+        total += s.seconds
+    table.add_section()
+    table.add_row("[bold]Total[/bold]", f"[bold]{_fmt_duration(total)}[/bold]", "")
+    console.print(table)
+
+
+def render_suggestions(suggestions: list[TimeEntrySuggestion]) -> None:
+    table = Table(title="Suggested time entries")
+    table.add_column("Day", style="cyan", no_wrap=True)
+    table.add_column("Start", no_wrap=True)
+    table.add_column("End", no_wrap=True)
+    table.add_column("Dur", justify="right")
+    table.add_column("Project", style="magenta")
+    table.add_column("Title")
+    total = 0.0
+    for s in suggestions:
+        table.add_row(
+            s.day,
+            s.start.strftime("%H:%M"),
+            s.end.strftime("%H:%M"),
+            _fmt_duration(s.duration_seconds),
+            s.project_title,
+            (s.title or "")[:50],
+        )
+        total += s.duration_seconds
+    table.add_section()
+    table.add_row("", "", "", f"[bold]{_fmt_duration(total)}[/bold]", "", "")
+    console.print(table)

timing_cli/rules.py

@@ -0,0 +1,101 @@
+"""Classify app usage onto projects.
+
+Only ~15% of raw app activity is auto-assigned to a project by Timing's own
+predicate rules. To generate useful time entries we layer our own rules on top:
+
+  1. If Timing already assigned a project to the slice, keep it.
+  2. Otherwise, apply the user's configured rules (first match wins).
+  3. Otherwise, the slice is left "Unassigned".
+
+Rules match on app name / bundle id (case-insensitive substring) and on window
+title / document path (regex). See ``timing_cli.config.Rule``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from timing_cli.config import Rule
+from timing_cli.models import AppUsage
+from timing_cli.timing_predicates import TimingPredicateRule
+
+
+@dataclass(frozen=True)
+class Classification:
+    """The project a slice was classified into and where the decision came from."""
+
+    project_title: str
+    project_id: int | None
+    source: str  # "timing" | "rule" | "unassigned"
+    project_title_chain: tuple[str, ...] = ()
+
+
+UNASSIGNED = "Unassigned"
+
+
+class _CompiledRule:
+    __slots__ = ("rule", "_title_re", "_path_re")
+
+    def __init__(self, rule: Rule) -> None:
+        self.rule = rule
+        self._title_re = re.compile(rule.title, re.IGNORECASE) if rule.title else None
+        self._path_re = re.compile(rule.path, re.IGNORECASE) if rule.path else None
+
+    def matches(self, usage: AppUsage) -> bool:
+        r = self.rule
+        if r.app and r.app.lower() not in (usage.app or "").lower():
+            return False
+        if r.bundle_id and r.bundle_id.lower() not in (usage.bundle_id or "").lower():
+            return False
+        if self._title_re and not self._title_re.search(usage.title or ""):
+            return False
+        if self._path_re and not self._path_re.search(usage.path or ""):
+            return False
+        # A rule with no criteria at all should never match everything.
+        return any((r.app, r.bundle_id, r.title, r.path))
+
+
+class Classifier:
+    """Apply project classification rules.
+
+    Order is deliberate: already-assigned Timing slices win, then explicit user
+    config rules, then decoded Timing project predicate rules, then Unassigned.
+    """
+
+    def __init__(
+        self,
+        rules: list[Rule],
+        timing_rules: list[TimingPredicateRule] | None = None,
+    ) -> None:
+        self._compiled = [_CompiledRule(r) for r in rules]
+        self._timing_rules = timing_rules or []
+
+    def classify(self, usage: AppUsage) -> Classification:
+        # 1. Trust Timing's own project assignment when present.
+        if usage.project_id is not None and usage.project_title:
+            chain = tuple(usage.project_title_chain or [usage.project_title])
+            return Classification(usage.project_title, usage.project_id, "timing", chain)
+
+        # 2. First matching user rule wins.
+        for compiled in self._compiled:
+            if compiled.matches(usage):
+                return Classification(
+                    compiled.rule.project,
+                    None,
+                    "rule",
+                    (compiled.rule.project,),
+                )
+
+        # 3. Reuse Timing's own project predicate rules from the local DB.
+        for timing_rule in self._timing_rules:
+            if timing_rule.matches(usage):
+                return Classification(
+                    timing_rule.project_title,
+                    timing_rule.project_id,
+                    "timing_predicate",
+                    timing_rule.project_title_chain,
+                )
+
+        # 4. Fall back to unassigned.
+        return Classification(UNASSIGNED, None, "unassigned", (UNASSIGNED,))