ttd-ledger 0.0.0__py3-none-any.whl

ttd/__init__.py

@@ -0,0 +1,3 @@
+"""TTD — terminal-native billable ledger."""
+
+__version__ = "0.1.0"

ttd/api/app.py

@@ -0,0 +1,38 @@
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from litestar import Litestar, get
+
+from ttd.core.db import close_db, init_db
+from ttd.core.services import health
+
+
+@get("/health")
+async def health_route() -> dict[str, str]:
+    result = await health.ping()
+    return {"status": result["status"], "db_path": result["db_path"]}
+
+
+@asynccontextmanager
+async def lifespan(_app: Litestar) -> AsyncIterator[None]:
+    await init_db()
+    try:
+        yield
+    finally:
+        await close_db()
+
+
+def create_app() -> Litestar:
+    return Litestar(route_handlers=[health_route], lifespan=[lifespan])
+
+
+def run() -> None:
+    import uvicorn
+
+    uvicorn.run(
+        "ttd.api.app:create_app",
+        factory=True,
+        host="127.0.0.1",
+        port=8000,
+        log_level="info",
+    )

ttd/cli/client_cmds.py

@@ -0,0 +1,88 @@
+"""`ttd client` commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+from uuid import UUID
+
+from cyclopts import App, Parameter
+
+from ttd.cli.console import success
+from ttd.cli.errors import cli_exit
+from ttd.cli.output import print_clients
+from ttd.cli.runtime import ensure_db, parse_decimal
+from ttd.core.schemas import CreateClient, UpdateClient
+from ttd.core.services import clients as client_service
+
+app = App(name="client", help="Manage clients.")
+
+
+@app.command
+async def add(
+    name: str,
+    *,
+    rate: Annotated[str, Parameter(name="--rate", help="Default hourly rate.")],
+    currency: Annotated[str, Parameter(name="--currency")] = "USD",
+) -> None:
+    """Add a client."""
+    try:
+        await ensure_db()
+        client = await client_service.create_client(
+            CreateClient(
+                name=name,
+                default_hourly_rate=parse_decimal(rate),
+                currency=currency,
+            )
+        )
+        success(f"Created client {_short(client.id)} ({client.name})")
+    except BaseException as exc:
+        cli_exit(exc)
+
+
+@app.command(name="list")
+async def list_clients() -> None:
+    """List clients."""
+    try:
+        await ensure_db()
+        print_clients(await client_service.list_clients())
+    except BaseException as exc:
+        cli_exit(exc)
+
+
+@app.command
+async def update(
+    client_id: UUID,
+    *,
+    name: str | None = None,
+    rate: Annotated[str | None, Parameter(name="--rate")] = None,
+    currency: Annotated[str | None, Parameter(name="--currency")] = None,
+) -> None:
+    """Update a client."""
+    try:
+        await ensure_db()
+        client = await client_service.update_client(
+            client_id,
+            UpdateClient(
+                name=name,
+                default_hourly_rate=parse_decimal(rate) if rate is not None else None,
+                currency=currency,
+            ),
+        )
+        success(f"Updated client {_short(client.id)} ({client.name})")
+    except BaseException as exc:
+        cli_exit(exc)
+
+
+@app.command
+async def delete(client_id: UUID) -> None:
+    """Delete a client (only when it has no projects)."""
+    try:
+        await ensure_db()
+        await client_service.delete_client(client_id)
+        success(f"Deleted client {_short(client_id)}")
+    except BaseException as exc:
+        cli_exit(exc)
+
+
+def _short(client_id: UUID | None) -> str:
+    return str(client_id)[:8] if client_id is not None else "--------"

ttd/cli/console.py

@@ -0,0 +1,28 @@
+"""Shared Rich console for CLI output."""
+
+from __future__ import annotations
+
+from rich.console import Console
+
+stdout = Console()
+stderr = Console(stderr=True)
+
+
+def success(message: str) -> None:
+    """Print a success line to stdout."""
+    stdout.print(f"[green]✓[/green] {message}")
+
+
+def info(message: str) -> None:
+    """Print a neutral informational line to stdout."""
+    stdout.print(message)
+
+
+def muted(message: str) -> None:
+    """Print dim placeholder text (e.g. empty lists)."""
+    stdout.print(f"[dim]{message}[/dim]")
+
+
+def error(message: str) -> None:
+    """Print an error line to stderr."""
+    stderr.print(f"[bold red]Error:[/bold red] {message}")

ttd/cli/entries_cmds.py

@@ -0,0 +1,164 @@
+"""`ttd entries` — list and correct time entries."""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Annotated
+from uuid import UUID
+
+from cyclopts import App, Parameter
+
+from ttd.cli.console import info, success
+from ttd.cli.errors import cli_exit
+from ttd.cli.output import print_entries, print_entry
+from ttd.cli.runtime import (
+    ensure_db,
+    parse_clock_on_date,
+    parse_date,
+    parse_decimal,
+    require_id,
+    resolve_client,
+    resolve_project,
+)
+from ttd.core.models.enums import EntryMode
+from ttd.core.models.time_entry import TimeEntry
+from ttd.core.schemas import UpdateDurationEntry, UpdateIntervalEntry
+from ttd.core.services import time_entries as entry_service
+
+app = App(name="entries", help="List and edit time entries.")
+
+
+def _filter_by_period(
+    entries: list[TimeEntry],
+    *,
+    from_date: date | None,
+    to_date: date | None,
+) -> list[TimeEntry]:
+    filtered = entries
+    if from_date is not None:
+        filtered = [e for e in filtered if e.work_date >= from_date]
+    if to_date is not None:
+        filtered = [e for e in filtered if e.work_date <= to_date]
+    return filtered
+
+
+@app.command(name="list")
+async def list_entries(
+    *,
+    client: Annotated[str | None, Parameter(name="--client")] = None,
+    project: Annotated[str | None, Parameter(name="--project")] = None,
+    project_id: Annotated[UUID | None, Parameter(name="--project-id")] = None,
+    from_date: Annotated[
+        str | None, Parameter(name="--from", help="Start date (YYYY-MM-DD).")
+    ] = None,
+    to_date: Annotated[
+        str | None, Parameter(name="--to", help="End date (YYYY-MM-DD).")
+    ] = None,
+) -> None:
+    """List entries for a project, optionally filtered by work date."""
+    try:
+        await ensure_db()
+        owner = (
+            await resolve_client(client_id=None, client_name=client)
+            if client is not None
+            else None
+        )
+        resolved = await resolve_project(
+            project_id=project_id,
+            client=owner,
+            project_name=project,
+        )
+        entries = await entry_service.list_time_entries_for_project(
+            require_id(resolved.id, "project")
+        )
+        period_start = parse_date(from_date) if from_date is not None else None
+        period_end = parse_date(to_date) if to_date is not None else None
+        print_entries(
+            _filter_by_period(entries, from_date=period_start, to_date=period_end)
+        )
+    except BaseException as exc:
+        cli_exit(exc)
+
+
+@app.command
+async def edit(
+    entry_id: UUID,
+    *,
+    work_date: Annotated[str | None, Parameter(name="--date")] = None,
+    hours: Annotated[str | None, Parameter(name="--hours")] = None,
+    time_from: Annotated[str | None, Parameter(name="--from")] = None,
+    time_to: Annotated[str | None, Parameter(name="--to")] = None,
+    note: str | None = None,
+    non_billable: Annotated[bool | None, Parameter(name="--no-billable")] = None,
+    billable: Annotated[bool | None, Parameter(name="--billable")] = None,
+) -> None:
+    """Edit a time entry (fields depend on duration vs interval mode)."""
+    try:
+        await ensure_db()
+        entry = await entry_service.get_time_entry(entry_id)
+        if non_billable is True and billable is not None:
+            from ttd.core.exceptions import ValidationError
+
+            raise ValidationError("Use only one of --billable or --no-billable")
+        billable_flag: bool | None = None
+        if non_billable is True:
+            billable_flag = False
+        elif billable is not None:
+            billable_flag = billable
+
+        day = parse_date(work_date) if work_date is not None else None
+
+        if entry.entry_mode == EntryMode.DURATION:
+            if time_from is not None or time_to is not None:
+                from ttd.core.exceptions import ValidationError
+
+                raise ValidationError("Duration entries use --hours, not --from/--to")
+            updated = await entry_service.update_duration_entry(
+                entry_id,
+                UpdateDurationEntry(
+                    work_date=day,
+                    billable_hours=parse_decimal(hours) if hours else None,
+                    billable=billable_flag,
+                    note=note,
+                ),
+            )
+        else:
+            if hours is not None:
+                from ttd.core.exceptions import ValidationError
+
+                raise ValidationError("Interval entries use --from/--to, not --hours")
+            started = (
+                parse_clock_on_date(day or entry.work_date, time_from)
+                if time_from
+                else None
+            )
+            ended = (
+                parse_clock_on_date(day or entry.work_date, time_to)
+                if time_to
+                else None
+            )
+            updated = await entry_service.update_interval_entry(
+                entry_id,
+                UpdateIntervalEntry(
+                    work_date=day,
+                    started_at=started,
+                    ended_at=ended,
+                    billable=billable_flag,
+                    note=note,
+                ),
+            )
+        info("Updated entry:")
+        print_entry(updated)
+    except BaseException as exc:
+        cli_exit(exc)
+
+
+@app.command
+async def delete(entry_id: UUID) -> None:
+    """Delete a time entry."""
+    try:
+        await ensure_db()
+        await entry_service.delete_time_entry(entry_id)
+        success(f"Deleted entry {str(entry_id)[:8]}")
+    except BaseException as exc:
+        cli_exit(exc)

ttd/cli/errors.py

@@ -0,0 +1,19 @@
+"""Map core exceptions to CLI exit codes."""
+
+from __future__ import annotations
+
+from ttd.cli.console import error as print_error
+from ttd.core.exceptions import NotFoundError, TTDError, ValidationError
+
+
+def cli_exit(exc: BaseException) -> None:
+    if isinstance(exc, NotFoundError):
+        print_error(str(exc))
+        raise SystemExit(1) from exc
+    if isinstance(exc, ValidationError):
+        print_error(str(exc))
+        raise SystemExit(2) from exc
+    if isinstance(exc, TTDError):
+        print_error(str(exc))
+        raise SystemExit(1) from exc
+    raise exc

ttd/cli/log_cmds.py

@@ -0,0 +1,105 @@
+"""`ttd log` — fast retroactive time capture."""
+
+from __future__ import annotations
+
+from datetime import date
+from typing import Annotated
+from uuid import UUID
+
+from cyclopts import App, Parameter
+
+from ttd.cli.console import info
+from ttd.cli.errors import cli_exit
+from ttd.cli.output import print_entry
+from ttd.cli.runtime import (
+    ensure_db,
+    parse_clock_on_date,
+    parse_date,
+    parse_decimal,
+    require_id,
+    resolve_client,
+    resolve_project,
+)
+from ttd.core.schemas import CreateDurationEntry, CreateIntervalEntry
+from ttd.core.services import time_entries as entry_service
+
+app = App(name="log", help="Log retroactive time on a project.")
+
+
+@app.default
+async def log_entry(
+    *,
+    client: Annotated[str | None, Parameter(name="--client")] = None,
+    project: Annotated[str | None, Parameter(name="--project")] = None,
+    project_id: Annotated[
+        str | None, Parameter(name="--project-id", help="Project UUID.")
+    ] = None,
+    work_date: Annotated[
+        str | None,
+        Parameter(name="--date", help="Work date (YYYY-MM-DD). Defaults to today."),
+    ] = None,
+    hours: Annotated[
+        str | None, Parameter(name="--hours", help="Duration in hours.")
+    ] = None,
+    time_from: Annotated[
+        str | None, Parameter(name="--from", help="Interval start (HH:MM UTC).")
+    ] = None,
+    time_to: Annotated[
+        str | None, Parameter(name="--to", help="Interval end (HH:MM UTC).")
+    ] = None,
+    note: str | None = None,
+    non_billable: Annotated[bool, Parameter(name="--no-billable")] = False,
+) -> None:
+    """Log time by duration (--hours) or interval (--from/--to)."""
+    try:
+        await ensure_db()
+        pid = UUID(project_id) if project_id is not None else None
+        owner = (
+            await resolve_client(client_id=None, client_name=client)
+            if client is not None
+            else None
+        )
+        resolved = await resolve_project(
+            project_id=pid,
+            client=owner,
+            project_name=project,
+        )
+        day = parse_date(work_date) if work_date is not None else date.today()
+        billable = not non_billable
+
+        if hours is not None:
+            if time_from is not None or time_to is not None:
+                from ttd.core.exceptions import ValidationError
+
+                raise ValidationError("Use --hours or --from/--to, not both")
+            entry = await entry_service.create_duration_entry(
+                CreateDurationEntry(
+                    project_id=require_id(resolved.id, "project"),
+                    work_date=day,
+                    billable_hours=parse_decimal(hours),
+                    billable=billable,
+                    note=note,
+                )
+            )
+        elif time_from is not None and time_to is not None:
+            started = parse_clock_on_date(day, time_from)
+            ended = parse_clock_on_date(day, time_to)
+            entry = await entry_service.create_interval_entry(
+                CreateIntervalEntry(
+                    project_id=require_id(resolved.id, "project"),
+                    work_date=day,
+                    started_at=started,
+                    ended_at=ended,
+                    billable=billable,
+                    note=note,
+                )
+            )
+        else:
+            from ttd.core.exceptions import ValidationError
+
+            raise ValidationError("Provide --hours or both --from and --to")
+
+        info("Logged entry:")
+        print_entry(entry)
+    except BaseException as exc:
+        cli_exit(exc)

ttd/cli/main.py

@@ -0,0 +1,27 @@
+from cyclopts import App
+from rich.table import Table
+
+from ttd.cli import client_cmds, entries_cmds, log_cmds, project_cmds
+from ttd.cli.console import stdout
+from ttd.core.services import health
+
+app = App(name="ttd", help="Terminal-native billable ledger.")
+
+app.command(client_cmds.app)
+app.command(project_cmds.app)
+app.command(log_cmds.app)
+app.command(entries_cmds.app)
+
+
+@app.default
+async def health_cmd() -> None:
+    """Check service and database connectivity."""
+    result = await health.ping()
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_row("[bold]status[/bold]", f"[green]{result['status']}[/green]")
+    table.add_row("[bold]db[/bold]", str(result["db_path"]))
+    stdout.print(table)
+
+
+def main() -> None:
+    app()

ttd/cli/output.py

@@ -0,0 +1,105 @@
+"""Rich formatters for CLI list and detail views."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from uuid import UUID
+
+from rich.table import Table
+
+from ttd.cli.console import muted, stdout
+from ttd.core.models.client import Client
+from ttd.core.models.enums import BillingMode, enum_value
+from ttd.core.models.project import Project
+from ttd.core.models.time_entry import TimeEntry
+
+
+def _short_id(value: UUID | None) -> str:
+    return str(value)[:8] if value is not None else "--------"
+
+
+def format_hours(hours: Decimal) -> str:
+    return f"{hours.quantize(Decimal('0.01'))}h"
+
+
+def print_clients(clients: list[Client]) -> None:
+    if not clients:
+        muted("No clients.")
+        return
+    table = Table(title="Clients", show_header=True, header_style="bold")
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Name")
+    table.add_column("Rate", justify="right")
+    table.add_column("Currency", justify="center")
+    for client in clients:
+        table.add_row(
+            _short_id(client.id),
+            client.name,
+            str(client.default_hourly_rate),
+            client.currency,
+        )
+    stdout.print(table)
+
+
+def print_projects(projects: list[Project]) -> None:
+    if not projects:
+        muted("No projects.")
+        return
+    table = Table(title="Projects", show_header=True, header_style="bold")
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Client", style="cyan", no_wrap=True)
+    table.add_column("Name")
+    table.add_column("Mode")
+    table.add_column("Billing", overflow="fold")
+    for project in projects:
+        mode = enum_value(project.billing_mode)
+        if mode == BillingMode.HOURLY:
+            billing = "hourly (inherits client rate unless overridden)"
+        else:
+            billing = f"fixed {project.contract_total} {project.currency}"
+        table.add_row(
+            _short_id(project.id),
+            _short_id(project.client_id),
+            project.name,
+            mode,
+            billing,
+        )
+    stdout.print(table)
+
+
+def print_entries(entries: list[TimeEntry]) -> None:
+    if not entries:
+        muted("No entries.")
+        return
+    table = Table(title="Time entries", show_header=True, header_style="bold")
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Project", style="cyan", no_wrap=True)
+    table.add_column("Date", no_wrap=True)
+    table.add_column("Hours", justify="right", no_wrap=True)
+    table.add_column("Capture")
+    table.add_column("Billable", no_wrap=True)
+    table.add_column("Note", overflow="fold")
+    for entry in sorted(entries, key=lambda e: (e.work_date, e.id)):
+        mode = enum_value(entry.entry_mode)
+        if mode == "interval" and entry.started_at and entry.ended_at:
+            span = (
+                f"{entry.started_at.strftime('%H:%M')}-"
+                f"{entry.ended_at.strftime('%H:%M')} UTC"
+            )
+        else:
+            span = mode
+        billable = "[green]yes[/green]" if entry.billable else "[dim]no[/dim]"
+        table.add_row(
+            _short_id(entry.id),
+            _short_id(entry.project_id),
+            str(entry.work_date),
+            format_hours(entry.billable_hours),
+            span,
+            billable,
+            entry.note or "",
+        )
+    stdout.print(table)
+
+
+def print_entry(entry: TimeEntry) -> None:
+    print_entries([entry])