tlnt-cli 1.5.1__py3-none-any.whl

tlnt/cli/main.py

@@ -0,0 +1,163 @@
+"""Typer command-line interface."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from tlnt.cli.commands.attendance import (
+    attendance_approve,
+    attendance_clockin,
+    attendance_clockout,
+    attendance_summary_list,
+    attendance_summary_metrics,
+)
+from tlnt.cli.commands.calendar import (
+    calendar_activity,
+    calendar_birthday,
+    calendar_holiday,
+    calendar_index,
+    calendar_my_birthday,
+    calendar_timeoff,
+)
+from tlnt.cli.commands.login import login
+from tlnt.cli.commands.logout import logout
+from tlnt.cli.commands.mcp import mcp
+from tlnt.cli.commands.notifications import (
+    notification_attendance_list,
+    notification_count,
+    notification_detail,
+    notification_list,
+    notification_timeoff_list,
+)
+from tlnt.cli.commands.timeoff import (
+    timeoff_approve,
+    timeoff_balance,
+    timeoff_cancel,
+    timeoff_delegation_list,
+    timeoff_detail,
+    timeoff_list,
+    timeoff_request,
+    timeoff_types_list,
+)
+from tlnt.cli.commands.profile import profile
+from tlnt.cli.commands.setup import setup
+from tlnt.cli.commands.status import status
+from tlnt.cli.commands import update as update_command
+from tlnt.cli.commands.update import update
+from tlnt.cli.commands.version import print_version
+from tlnt.cli.options import VerboseOption
+from tlnt.core import config, play_store
+from tlnt.core.clients.mekari import constants as mekari_constants
+from tlnt.core.logs import configure_logging
+from tlnt.core.logs import logger
+
+# Define the main app and sub-apps
+app = typer.Typer(
+    no_args_is_help=True,
+    help=(
+        "[bold cyan]tlnt[/] — unofficial CLI for Mekari Talenta.\n\n"
+        "[yellow]Use at your own risk:[/] this tool signs in as you and can "
+        "submit real attendance and time-off requests on your behalf."
+    ),
+    epilog=(
+        "Docs: https://github.com/fathirazarthuro/tlnt — add [cyan]--json[/] for "
+        "machine output."
+    ),
+)
+attendance_app = typer.Typer(no_args_is_help=True, help="Manage attendance.")
+notification_app = typer.Typer(no_args_is_help=True, help="Read notifications.")
+timeoff_app = typer.Typer(no_args_is_help=True, help="Manage time-off data and requests.")
+calendar_app = typer.Typer(no_args_is_help=True, help="Read calendar data.")
+
+# Add root commands to the main app
+app.command(rich_help_panel="Session")(setup)
+app.command(rich_help_panel="Session")(login)
+app.command(rich_help_panel="Session")(logout)
+app.command(rich_help_panel="Session")(status)
+app.command(rich_help_panel="Session")(profile)
+app.command(rich_help_panel="Session")(update)
+app.command(rich_help_panel="Integrations")(mcp)
+
+# Add commands to the attendance sub-app
+attendance_app.command(name="clock-in")(attendance_clockin)
+attendance_app.command(name="clock-out")(attendance_clockout)
+attendance_app.command(name="summary-list")(attendance_summary_list)
+attendance_app.command(name="summary-metrics")(attendance_summary_metrics)
+attendance_app.command(name="approve")(attendance_approve)
+app.add_typer(attendance_app, name="attendance", rich_help_panel="Workflows")
+
+# Add commands to the notification sub-app
+notification_app.command(name="count")(notification_count)
+notification_app.command(name="list")(notification_list)
+notification_app.command(name="attendance-list")(notification_attendance_list)
+notification_app.command(name="timeoff-list")(notification_timeoff_list)
+notification_app.command(name="detail")(notification_detail)
+app.add_typer(notification_app, name="notification", rich_help_panel="Workflows")
+
+timeoff_app.command(name="types-list")(timeoff_types_list)
+timeoff_app.command(name="balance")(timeoff_balance)
+timeoff_app.command(name="delegation-list")(timeoff_delegation_list)
+timeoff_app.command(name="list")(timeoff_list)
+timeoff_app.command(name="detail")(timeoff_detail)
+timeoff_app.command(name="request")(timeoff_request)
+timeoff_app.command(name="cancel")(timeoff_cancel)
+timeoff_app.command(name="approve")(timeoff_approve)
+app.add_typer(timeoff_app, name="timeoff", rich_help_panel="Workflows")
+
+calendar_app.command(name="holiday")(calendar_holiday)
+calendar_app.command(name="timeoff")(calendar_timeoff)
+calendar_app.command(name="index")(calendar_index)
+calendar_app.command(name="my-birthday")(calendar_my_birthday)
+calendar_app.command(name="birthday")(calendar_birthday)
+calendar_app.command(name="activity")(calendar_activity)
+app.add_typer(calendar_app, name="calendar", rich_help_panel="Workflows")
+
+
+_log = logger.bind(component="cli")
+
+@app.callback()
+def main_callback(
+    ctx: typer.Context,
+    config_path: Annotated[
+        Path | None,
+        typer.Option(
+            "--config",
+            help="Use a specific config.json file.",
+        ),
+    ] = None,
+    _version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            help="Show the installed tlnt version and exit.",
+            callback=print_version,
+            is_eager=True,
+        ),
+    ] = False,
+    verbose: VerboseOption = False,
+) -> None:
+    config.set_config_path(config_path)
+    configure_logging(verbose)
+    if ctx.invoked_subcommand not in (None, "mcp", "update"):
+        for warning in (
+            update_command.update_warning(),
+            play_store.app_version_warning(mekari_constants.app_version()),
+        ):
+            if warning:
+                typer.echo(warning, err=True)
+    if ctx.invoked_subcommand is not None:
+        _log.bind(
+            event="command_started",
+            command=ctx.invoked_subcommand,
+        ).debug("command started")
+
+
+def main() -> None:
+    try:
+        app()
+    except Exception:
+        _log.exception("unhandled CLI error")
+        raise

tlnt/cli/options.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from tlnt.core.logs import configure_logging
+
+
+def _enable_verbose_logging(value: bool) -> bool:
+    if value:
+        configure_logging(True)
+    return value
+
+
+VerboseOption = Annotated[
+    bool,
+    typer.Option(
+        "--verbose",
+        help="Emit structured diagnostic logs to stderr.",
+        callback=_enable_verbose_logging,
+        rich_help_panel="Diagnostics",
+    ),
+]
+
+JsonOption = Annotated[
+    bool,
+    typer.Option("--json", help="Emit one JSON result.", rich_help_panel="Output"),
+]
+
+TableOption = Annotated[
+    bool,
+    typer.Option(
+        "--table",
+        help="Accepted for compatibility; tables are now the default.",
+        rich_help_panel="Output",
+    ),
+]
+
+AvatarsOption = Annotated[
+    bool,
+    typer.Option(
+        "--avatars",
+        help="Draw avatar image URLs as terminal thumbnails. Needs a TTY.",
+        rich_help_panel="Output",
+    ),
+]
+
+InteractiveOption = Annotated[
+    bool,
+    typer.Option(
+        "--interactive",
+        help="Prompt for missing values. Needs a TTY; cannot combine with --json.",
+        rich_help_panel="Output",
+    ),
+]

tlnt/cli/output.py

@@ -0,0 +1,321 @@
+from __future__ import annotations
+
+import json
+import re
+import threading
+from contextlib import contextmanager
+from typing import Any, Callable, Iterator
+
+import typer
+from rich import box
+from rich.console import Console, RenderableType
+from rich.highlighter import ReprHighlighter
+from rich.panel import Panel
+from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+from rich.prompt import Confirm
+from rich.table import Table
+from rich.text import Text
+from rich.theme import Theme
+
+from tlnt.cli.avatars import is_avatar_url, thumbnail
+from tlnt.core.logs import logger
+from tlnt.core.models import Result, dig
+
+
+_log = logger.bind(component="cli")
+
+
+class TlntHighlighter(ReprHighlighter):
+    """ReprHighlighter plus tlnt-specific value shapes (dates, times, codes)."""
+
+    highlights = [
+        *ReprHighlighter.highlights,
+        r"(?P<tlnt_date>\b\d{4}-\d{2}-\d{2}\b)",
+        r"(?P<tlnt_time>\b\d{2}:\d{2}(?::\d{2})?\b)",
+        r"(?P<tlnt_code>\b[a-z]+(?:_[a-z]+){2,}\b)",
+    ]
+
+
+THEME = Theme(
+    {
+        "repr.tlnt_date": "bold cyan",
+        "repr.tlnt_time": "cyan",
+        "repr.tlnt_code": "magenta",
+        "success": "green",
+        "error": "red",
+        "warning": "yellow",
+        "field": "bold cyan",
+    }
+)
+
+console = Console(theme=THEME, highlighter=TlntHighlighter())
+err_console = Console(stderr=True, theme=THEME, highlighter=TlntHighlighter())
+
+
+def new_table(**kwargs: Any) -> Table:
+    """Table with the shared tlnt look."""
+    return Table(box=box.SIMPLE_HEAD, header_style="bold cyan", **kwargs)
+
+# result.code -> (dotted path into result.data holding the row list, column keys)
+TABLES: dict[str, tuple[str, tuple[str, ...]]] = {
+    "notification_list_loaded": ("inbox.data", ("id", "message")),
+    "notification_attendance_list_loaded": ("inbox.data", ("id", "message")),
+    "notification_timeoff_list_loaded": ("inbox.data", ("id", "message")),
+    "timeoff_types_list_loaded": ("timeOffPolicies", ("id", "policy_name")),
+    "timeoff_list_loaded": ("time_off_request.data", ("id", "request_id")),
+    "timeoff_delegation_list_loaded": ("data", ("value", "name", "job")),
+    "timeoff_balance_loaded": (
+        "",
+        ("id", "attributes.balance", "attributes.is_unlimited_balance"),
+    ),
+}
+
+_TAG_RE = re.compile(r"<[^>]+>")
+
+
+def _cell(value: Any, avatars: bool = False) -> RenderableType:
+    if avatars and is_avatar_url(value):
+        rendered = thumbnail(value)
+        if rendered is not None:
+            return rendered
+    return " ".join(_TAG_RE.sub("", str(value)).split())
+
+
+def build_table(
+    rows: list[dict[str, Any]],
+    columns: tuple[str, ...],
+    *,
+    index: bool = False,
+    avatars: bool = False,
+) -> Table | None:
+    resolved = (
+        list(columns)
+        if not rows
+        else [c for c in columns if any(dig(row, c) is not None for row in rows)]
+    )
+    if not resolved:
+        return None
+    table = new_table()
+    if index:
+        table.add_column("#")
+    for column in resolved:
+        table.add_column(column)
+    for position, row in enumerate(rows, start=1):
+        cells = [_cell(dig(row, column), avatars) for column in resolved]
+        table.add_row(str(position), *cells) if index else table.add_row(*cells)
+    return table
+
+
+def _flatten(data: dict[str, Any], prefix: str = "") -> dict[str, Any]:
+    flat: dict[str, Any] = {}
+    for key, value in data.items():
+        path = f"{prefix}{key}"
+        if isinstance(value, dict):
+            flat.update(_flatten(value, f"{path}."))
+        else:
+            flat[path] = value
+    return flat
+
+
+def _is_row_list(value: Any) -> bool:
+    """A list of dicts. Empty is allowed: registry columns are known up front."""
+    return isinstance(value, list) and all(isinstance(row, dict) for row in value)
+
+
+def _is_discoverable_rows(value: Any) -> bool:
+    """Non-empty list of dicts: columns must be discovered from the rows."""
+    return _is_row_list(value) and bool(value)
+
+
+def _auto_rows_table(rows: list[dict[str, Any]], avatars: bool = False) -> Table:
+    flat_rows = [_flatten(row) for row in rows]
+    columns = tuple(sorted({key for row in flat_rows for key in row}))
+    return build_table(flat_rows, columns, avatars=avatars)
+
+
+def _field_table(data: dict[str, Any], avatars: bool = False) -> Table:
+    table = new_table()
+    table.add_column("Field", style="field")
+    table.add_column("Value")
+    for key, value in _flatten(data).items():
+        table.add_row(key, _cell(value, avatars))
+    return table
+
+
+def _avatar_keys(rows: list[dict[str, Any]]) -> tuple[str, ...]:
+    """Row keys holding avatar URLs, first-seen order, de-duplicated."""
+    return tuple(
+        dict.fromkeys(
+            key for row in rows for key, value in row.items() if is_avatar_url(value)
+        )
+    )
+
+
+def table_for(result: Result, avatars: bool = False) -> Table | None:
+    """Best table for this payload; None when JSON is the better shape."""
+    spec = TABLES.get(result.code)
+    if spec is not None:
+        path, columns = spec
+        rows = dig(result.data, path)
+        if not _is_row_list(rows):
+            return None
+        if avatars:
+            columns += tuple(k for k in _avatar_keys(rows) if k not in columns)
+        return build_table(rows, columns, avatars=avatars)
+
+    data = result.data
+    if _is_discoverable_rows(data):
+        return _auto_rows_table(data, avatars)
+    if isinstance(data, dict) and data:
+        if len(data) == 1:
+            only = next(iter(data.values()))
+            if _is_discoverable_rows(only):
+                return _auto_rows_table(only, avatars)
+        return _field_table(data, avatars)
+    return None
+
+
+def _print_error(result: Result) -> None:
+    if err_console.is_terminal:
+        err_console.print(
+            Panel(
+                Text(result.message),
+                title=result.code,
+                border_style="error",
+                expand=False,
+            )
+        )
+        return
+    err_console.print(
+        f"{result.code}: {result.message}",
+        style="error",
+        markup=False,
+        highlight=True,
+        soft_wrap=True,
+    )
+
+
+def emit(
+    result: Result,
+    json_output: bool,
+    avatars: bool = False,
+) -> None:
+    _log.bind(
+        event="command_finished",
+        code=result.code,
+        ok=result.ok,
+        json=json_output,
+    ).debug("command finished")
+    if json_output:
+        typer.echo(
+            json.dumps(result.as_dict(), ensure_ascii=False, separators=(",", ":"))
+        )
+    else:
+        out = console if result.ok else err_console
+        if result.ok:
+            out.print(
+                result.message,
+                style="success",
+                markup=False,
+                highlight=True,
+                soft_wrap=True,
+            )
+        else:
+            _print_error(result)
+        if result.data is not None:
+            rendered = table_for(result, avatars and out.is_terminal)
+            out.print(rendered) if rendered is not None else out.print_json(data=result.data)
+    if not result.ok:
+        raise typer.Exit(1)
+
+
+def confirm(question: str, *, default: bool = False, err: bool = False) -> bool | None:
+    """Rich confirm on the stream typer.confirm used. None when stdin is at EOF."""
+    target = err_console if err else console
+    try:
+        return Confirm.ask(question, default=default, console=target)
+    except EOFError:
+        return None
+
+
+def banner(title: str, *lines: str, enabled: bool = True) -> None:
+    if not enabled:
+        return
+    err_console.print(
+        Panel(
+            "\n".join(lines),
+            title=f"[bold cyan]{title}[/]",
+            border_style="cyan",
+            expand=False,
+        )
+    )
+
+
+def action_banner(action: str, enabled: bool = True) -> None:
+    banner(
+        f"tlnt · {action}",
+        "This sends a real request to Talenta.",
+        "Review the details below before confirming.",
+        enabled=enabled,
+    )
+
+
+@contextmanager
+def spinner(label: str, enabled: bool = True) -> Iterator[None]:
+    if not enabled or not err_console.is_terminal:
+        yield
+        return
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[cyan]{task.description}"),
+        TimeElapsedColumn(),
+        console=err_console,
+        transient=True,
+    ) as progress:
+        progress.add_task(label, total=None)
+        yield
+
+
+def run(
+    label: str,
+    action: Callable[[], Result],
+    json_output: bool,
+    verbose: bool,
+    *,
+    avatars: bool = False,
+) -> None:
+    """Run a read action behind a spinner (none with --json or --verbose), then emit."""
+    with spinner(label, enabled=not (json_output or verbose)):
+        result = action()
+    emit(result, json_output, avatars=avatars)
+
+
+@contextmanager
+def deadline_bar(label: str, seconds: int, enabled: bool = True) -> Iterator[None]:
+    if not enabled or not err_console.is_terminal:
+        yield
+        return
+    progress = Progress(
+        SpinnerColumn(),
+        TextColumn("[cyan]{task.description}"),
+        BarColumn(),
+        TimeElapsedColumn(),
+        TextColumn(f"/ {seconds // 60}:{seconds % 60:02d}"),
+        console=err_console,
+        transient=True,
+    )
+    task = progress.add_task(label, total=seconds)
+    stop = threading.Event()
+
+    # ponytail: 1s ticker against a known deadline; swap for a real callback
+    # if the browser layer ever reports progress.
+    def tick() -> None:
+        while not stop.wait(1.0):
+            progress.advance(task, 1)
+
+    with progress:
+        threading.Thread(target=tick, daemon=True).start()
+        try:
+            yield
+        finally:
+            stop.set()

tlnt/cli/prompts.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+from rich.prompt import IntPrompt, Prompt
+
+from tlnt.cli.output import banner, build_table, console
+from tlnt.core.models import Result
+
+
+def stdin_is_tty() -> bool:
+    return sys.stdin.isatty()
+
+
+def guard(json_output: bool, title: str = "") -> Result | None:
+    if json_output:
+        return Result(
+            False,
+            "interactive_unavailable",
+            "--interactive cannot be combined with --json",
+        )
+    if not stdin_is_tty():
+        return Result(
+            False,
+            "interactive_unavailable",
+            "--interactive needs an interactive terminal",
+        )
+    if title:
+        banner(
+            f"tlnt · {title}",
+            "Fill in the values below. Flags you already passed are kept.",
+            "Press Ctrl+C to abort.",
+        )
+    return None
+
+
+def ask_required(label: str, current: str, default: str = "") -> str:
+    if current:
+        return current
+    value = ""
+    while not value:
+        value = Prompt.ask(label, default=default, console=console).strip()
+    return value
+
+
+def ask_optional(label: str, current: str) -> str:
+    if current:
+        return current
+    return Prompt.ask(label, default="", console=console).strip()
+
+
+def ask_path(label: str, current: Path | None) -> Path | None:
+    if current is not None:
+        return current
+    while True:
+        value = Prompt.ask(label, default="", console=console).strip()
+        if not value:
+            return None
+        path = Path(value)
+        if path.is_file():
+            return path
+        console.print(f"No file at {path}", style="error")
+
+
+def pick(rows: list[dict[str, Any]], columns: tuple[str, ...], label: str) -> dict[str, Any]:
+    table = build_table(rows, columns, index=True)
+    console.print(table)
+    choice = IntPrompt.ask(
+        label,
+        choices=[str(n) for n in range(1, len(rows) + 1)],
+        show_choices=False,
+        console=console,
+    )
+    return rows[choice - 1]