mgraphctl 0.1.0__py3-none-any.whl

mgraphctl/commands/todo.py

@@ -0,0 +1,253 @@
+"""Microsoft To Do commands: lists and tasks (spec §8.15)."""
+
+from typing import Annotated
+
+import typer
+
+from mgraphctl.cli import (
+    AllFlag,
+    DryRunFlag,
+    JsonFlag,
+    LimitOpt,
+    graph_command,
+    make_noun_app,
+    page_bounds,
+)
+from mgraphctl.errors import UsageError
+from mgraphctl.graph import todo
+from mgraphctl.http import GraphClient
+from mgraphctl.render import (
+    Column,
+    DryRunResult,
+    ListResult,
+    ObjectResult,
+    WriteResult,
+    fmt_dtz,
+    parse_dt,
+)
+
+app = make_noun_app("Microsoft To Do lists and tasks.")
+
+SCOPES = ["Tasks.ReadWrite"]
+SCOPES_FROM_MAIL = ["Tasks.ReadWrite", "Mail.Read"]
+DEFAULT_LIMIT = 50
+
+LIST_COLUMNS = [
+    Column("id", "id"),
+    Column("wellknown", lambda item: item.get("wellknownListName") or ""),
+    Column("name", "displayName"),
+]
+
+
+def _task_columns(tz: str) -> list[Column]:
+    return [
+        Column("id", "id"),
+        Column("status", "status"),
+        Column("importance", "importance"),
+        Column("due", lambda t: fmt_dtz(t.get("dueDateTime"), tz)),
+        Column("title", "title"),
+    ]
+
+
+@app.command("lists")
+@graph_command(scopes=SCOPES)
+def lists(client: GraphClient, json_: JsonFlag = False):
+    """List your To Do lists."""
+    return ListResult(items=todo.list_lists(client), columns=LIST_COLUMNS)
+
+
+@app.command("tasks")
+@graph_command(scopes=SCOPES)
+def tasks(
+    client: GraphClient,
+    list_ref: Annotated[str, typer.Argument(metavar="LIST")],
+    include_completed: Annotated[bool, typer.Option("--include-completed")] = False,
+    limit: LimitOpt = None,
+    all_: AllFlag = False,
+    json_: JsonFlag = False,
+):
+    """List the tasks of a To Do list."""
+    bounded_limit, bounded_all = page_bounds(limit, all_, default=DEFAULT_LIMIT)
+    resolved = todo.resolve_list(client, list_ref)
+    page = todo.list_tasks(
+        client,
+        resolved["id"],
+        include_completed=include_completed,
+        limit=bounded_limit,
+        all_=bounded_all,
+    )
+    return ListResult(
+        items=page.items,
+        page=page,
+        hit_cap=todo.CAP_TASKS if bounded_all else None,
+        columns=_task_columns(client.tz),
+    )
+
+
+@app.command("task")
+@graph_command(scopes=SCOPES)
+def task(
+    client: GraphClient,
+    list_ref: Annotated[str, typer.Argument(metavar="LIST")],
+    task_id: Annotated[str, typer.Argument(metavar="ID")],
+    json_: JsonFlag = False,
+):
+    """Show one task."""
+    resolved = todo.resolve_list(client, list_ref)
+    obj = todo.get_task(client, resolved["id"], task_id)
+    fields = [
+        ("Title", "title"),
+        ("Status", "status"),
+        ("Importance", "importance"),
+        ("Due", lambda o: fmt_dtz(o.get("dueDateTime"), client.tz)),
+    ]
+    return ObjectResult(obj=obj, fields=fields)
+
+
+def _create_opts(
+    *,
+    title,
+    due,
+    body,
+    importance,
+    reminder,
+    start,
+    tz,
+) -> dict:
+    return dict(
+        title=title,
+        due=parse_dt(due, tz) if due is not None else None,
+        body_text=body,
+        importance=importance,
+        reminder=parse_dt(reminder, tz) if reminder is not None else None,
+        start=parse_dt(start, tz) if start is not None else None,
+        tz=tz,
+    )
+
+
+@app.command("create")
+@graph_command(scopes=SCOPES)
+def create(
+    client: GraphClient,
+    list_ref: Annotated[str, typer.Argument(metavar="LIST")],
+    title: Annotated[str, typer.Option("--title")],
+    due: Annotated[str | None, typer.Option("--due")] = None,
+    body: Annotated[str | None, typer.Option("--body")] = None,
+    importance: Annotated[str | None, typer.Option("--importance")] = None,
+    reminder: Annotated[str | None, typer.Option("--reminder")] = None,
+    start: Annotated[str | None, typer.Option("--start")] = None,
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Create a task."""
+    resolved = todo.resolve_list(client, list_ref)
+    opts = _create_opts(
+        title=title,
+        due=due,
+        body=body,
+        importance=importance,
+        reminder=reminder,
+        start=start,
+        tz=client.tz,
+    )
+    if dry_run:
+        return DryRunResult(todo.plan_create(client, resolved["id"], **opts))
+    obj = todo.run_create(client, resolved["id"], **opts)
+    return WriteResult(obj=obj, message=f"Created task {obj.get('id')}.")
+
+
+@app.command("update")
+@graph_command(scopes=SCOPES)
+def update(
+    client: GraphClient,
+    list_ref: Annotated[str, typer.Argument(metavar="LIST")],
+    task_id: Annotated[str, typer.Argument(metavar="ID")],
+    title: Annotated[str | None, typer.Option("--title")] = None,
+    due: Annotated[str | None, typer.Option("--due")] = None,
+    body: Annotated[str | None, typer.Option("--body")] = None,
+    importance: Annotated[str | None, typer.Option("--importance")] = None,
+    reminder: Annotated[str | None, typer.Option("--reminder")] = None,
+    start: Annotated[str | None, typer.Option("--start")] = None,
+    status: Annotated[str | None, typer.Option("--status")] = None,
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Update a task."""
+    if not any([title, due, body, importance, reminder, start, status]):
+        raise UsageError("USAGE", "give at least one field to update")
+    resolved = todo.resolve_list(client, list_ref)
+    opts = _create_opts(
+        title=title,
+        due=due,
+        body=body,
+        importance=importance,
+        reminder=reminder,
+        start=start,
+        tz=client.tz,
+    )
+    opts["status"] = status
+    if dry_run:
+        return DryRunResult(todo.plan_update(client, resolved["id"], task_id, **opts))
+    obj = todo.run_update(client, resolved["id"], task_id, **opts)
+    return WriteResult(obj=obj, message=f"Updated task {task_id}.")
+
+
+@app.command("complete")
+@graph_command(scopes=SCOPES)
+def complete(
+    client: GraphClient,
+    list_ref: Annotated[str, typer.Argument(metavar="LIST")],
+    task_id: Annotated[str, typer.Argument(metavar="ID")],
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Mark a task complete."""
+    resolved = todo.resolve_list(client, list_ref)
+    if dry_run:
+        return DryRunResult(todo.plan_complete(client, resolved["id"], task_id, tz=client.tz))
+    obj = todo.run_complete(client, resolved["id"], task_id, tz=client.tz)
+    return WriteResult(obj=obj, message=f"Completed task {task_id}.")
+
+
+@app.command("delete")
+@graph_command(scopes=SCOPES)
+def delete(
+    client: GraphClient,
+    list_ref: Annotated[str, typer.Argument(metavar="LIST")],
+    task_id: Annotated[str, typer.Argument(metavar="ID")],
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Delete a task."""
+    resolved = todo.resolve_list(client, list_ref)
+    if dry_run:
+        return DryRunResult(todo.plan_delete(client, resolved["id"], task_id))
+    todo.run_delete(client, resolved["id"], task_id)
+    return WriteResult(obj={"status": "deleted", "id": task_id}, message=f"Deleted task {task_id}.")
+
+
+@app.command("from-mail")
+@graph_command(scopes=SCOPES_FROM_MAIL)
+def from_mail(
+    client: GraphClient,
+    list_ref: Annotated[str, typer.Argument(metavar="LIST")],
+    message_id: Annotated[str, typer.Argument(metavar="MSGID")],
+    title: Annotated[str | None, typer.Option("--title")] = None,
+    due: Annotated[str | None, typer.Option("--due")] = None,
+    importance: Annotated[str | None, typer.Option("--importance")] = None,
+    dry_run: DryRunFlag = False,
+    json_: JsonFlag = False,
+):
+    """Create a task linked to a mail message."""
+    resolved = todo.resolve_list(client, list_ref)
+    message = todo.fetch_message_for_task(client, message_id)
+    opts = dict(
+        title=title,
+        due=parse_dt(due, client.tz) if due is not None else None,
+        importance=importance,
+        tz=client.tz,
+    )
+    if dry_run:
+        return DryRunResult(todo.plan_from_mail(client, resolved["id"], message, **opts))
+    obj = todo.run_from_mail(client, resolved["id"], message, **opts)
+    return WriteResult(obj=obj, message=f"Created task {obj.get('id')}.")

mgraphctl/commands/top.py

@@ -0,0 +1,284 @@
+"""login, logout, status, claims, me and version (spec §4.2, §4.3, §4.6, §8.1)."""
+
+import importlib.metadata
+import platform
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Annotated
+from zoneinfo import ZoneInfo
+
+import typer
+
+from mgraphctl import __version__, auth, config, errors, render
+from mgraphctl.cli import Globals, JsonFlag, graph_command, open_client
+from mgraphctl.errors import AuthError
+from mgraphctl.graph import users
+from mgraphctl.http import GraphClient
+from mgraphctl.render import FileResult, ObjectResult, TextResult, WriteResult, fmt_size
+
+LOGIN_SELECT = "id,displayName,userPrincipalName"
+
+ME_FIELDS = [
+    ("Name", "displayName"),
+    ("UPN", "userPrincipalName"),
+    ("Mail", "mail"),
+    ("Title", "jobTitle"),
+    ("Dept", "department"),
+    ("Office", "officeLocation"),
+    ("Phones", lambda u: ", ".join(u.get("businessPhones") or [])),
+    ("Mobile", "mobilePhone"),
+    ("Lang", "preferredLanguage"),
+    ("User id", "id"),
+]
+
+NO_DEVICE_NOTE = (
+    "none (Conditional Access policies that require a compliant device will fail without it)"
+)
+
+
+def _iso_local(epoch: object, tz: str) -> str | None:
+    """An `exp`/`iat` epoch rendered in `tz` with seconds, or None."""
+    if epoch is None:
+        return None
+    return datetime.fromtimestamp(int(epoch), ZoneInfo(tz)).isoformat(timespec="seconds")
+
+
+# --------------------------------------------------------------------------- login / logout
+
+
+def _already_logged_in(wanted: list[str], name: str) -> TextResult | None:
+    """The current token, when it already carries every requested scope (spec §4.2)."""
+    try:
+        result = auth.acquire_silent()
+    except AuthError:
+        return None
+    claims = auth.decode_jwt(result["access_token"])
+    held = auth.expand_scopes(claims.get("scp", "").split())
+    if any(s not in held for s in config.msal_scopes(wanted)):
+        return None
+    upn = auth.account_upn() or claims.get("upn") or claims.get("unique_name")
+    text = (
+        f"Already logged in as: {upn}\n"
+        "Use --force to re-authenticate, --scopes extended to add permissions."
+    )
+    store = auth.store_info()
+    payload = dict(
+        account=upn,
+        scopes=wanted,
+        scopeSet=name,
+        cache=store.label,
+        store=store.kind,
+        alreadyLoggedIn=True,
+    )
+    return TextResult(text=text, json_obj=payload)
+
+
+def login(
+    ctx: typer.Context,
+    scopes: Annotated[
+        str,
+        typer.Option(
+            "--scopes",
+            envvar="MGRAPHCTL_SCOPES",
+            help="default, extended, or a space/comma-separated scope list"
+            " (else MGRAPHCTL_SCOPES, the config file).",
+        ),
+    ] = "",
+    scope: Annotated[
+        list[str] | None,
+        typer.Option("--scope", help="Ask for one extra scope on demand (repeatable)."),
+    ] = None,
+    force: Annotated[
+        bool, typer.Option("--force", help="Sign in again even when a token is cached.")
+    ] = False,
+    device_code: Annotated[
+        bool, typer.Option("--device-code", help="Use the device code flow (no browser).")
+    ] = False,
+    json_: JsonFlag = False,
+) -> None:
+    """Sign in and cache the token. The only command that may open a browser."""
+    g: Globals = ctx.find_root().obj
+    s = config.settings()
+    name, wanted = config.resolve_scopes(scopes or s.scope_spec, scope or [])
+    if not force:
+        already = _already_logged_in(wanted, name)
+        if already is not None:
+            render.emit(already, json_mode=json_)
+            return
+    sent = config.msal_scopes(wanted)
+    if device_code:
+        auth.login_device_code(sent)
+    else:
+        auth.login_interactive(sent, force=force)
+    with open_client(g, []) as client:
+        me_obj = client.get("/me", params={"$select": LOGIN_SELECT})
+    account = me_obj.get("userPrincipalName")
+    display = me_obj.get("displayName")
+    # Asked after signing in: a keychain that failed by now has been swapped for the file.
+    store = auth.store_info()
+    text = (
+        f"Logged in as: {display} <{account}>\nScopes: {name} ({len(wanted)})\nCache: {store.label}"
+    )
+    payload = dict(
+        account=account,
+        displayName=display,
+        userId=me_obj.get("id"),
+        scopes=wanted,
+        scopeSet=name,
+        cache=store.label,
+        store=store.kind,
+    )
+    render.emit(TextResult(text=text, json_obj=payload), json_mode=json_)
+
+
+def logout(json_: JsonFlag = False) -> None:
+    """Delete the cached sign-in."""
+    store, removed = auth.logout()
+    message = (
+        f"Logged out. Cache removed: {store.label}" if removed else "No cached credentials found."
+    )
+    payload = dict(loggedOut=removed, cache=store.label if removed else None, store=store.kind)
+    render.emit(WriteResult(obj=payload, message=message), json_mode=json_)
+
+
+# --------------------------------------------------------------------------- status / claims
+
+
+def status(ctx: typer.Context, json_: JsonFlag = False) -> None:
+    """Report whether a cached sign-in is usable, and until when (spec §4.6)."""
+    g: Globals = ctx.find_root().obj
+    s = config.settings()
+    try:
+        result = auth.acquire_silent()
+    except AuthError:
+        # JSON callers parse stdout without checking the exit code first (spec §4.6).
+        if json_:
+            store = auth.store_info()
+            out = dict(
+                loggedIn=False,
+                account=None,
+                expiresAt=None,
+                scopeSet=s.scope_set,
+                scopes=s.scopes,
+                cache=store.label,
+                store=store.kind,
+            )
+            render.emit(TextResult(text="", json_obj=out), json_mode=True)
+        raise
+    claims = auth.decode_jwt(result["access_token"])
+    account = auth.account_upn() or claims.get("upn") or claims.get("unique_name")
+    expires = _iso_local(claims.get("exp"), g.tz)
+    store = auth.store_info()
+    text = (
+        f"Logged in as: {account}\n"
+        f"Token expires: {expires}\n"
+        f"Scopes: {s.scope_set} ({len(s.scopes)})\n"
+        f"Cache: {store.label}"
+    )
+    payload = dict(
+        loggedIn=True,
+        account=account,
+        expiresAt=expires,
+        scopeSet=s.scope_set,
+        scopes=s.scopes,
+        cache=store.label,
+        store=store.kind,
+    )
+    render.emit(TextResult(text=text, json_obj=payload), json_mode=json_)
+
+
+def _expiry_note(exp: object) -> str:
+    if exp is None:
+        return ""
+    remaining = int(exp) - int(time.time())
+    return "EXPIRED" if remaining <= 0 else f"expires in {remaining // 60}m"
+
+
+def _section(title: str, rows: list[tuple[str, str]]) -> list[str]:
+    width = max((len(label) for label, _ in rows), default=0)
+    body = [f"  {label:<{width}} : {value}" for label, value in rows]
+    return [title] + body
+
+
+def _claims_text(payload: dict, tz: str) -> str:
+    """The IDENTITY / DEVICE / AUTH METHODS / SCOPES report of spec §4.6."""
+    exp = payload.get("exp")
+    expires = _iso_local(exp, tz) or "N/A"
+    note = _expiry_note(exp)
+    identity = [
+        ("UPN", str(payload.get("upn") or payload.get("unique_name") or "N/A")),
+        ("Object id", str(payload.get("oid") or "N/A")),
+        ("Tenant id", str(payload.get("tid") or "N/A")),
+        ("Issued", _iso_local(payload.get("iat"), tz) or "N/A"),
+        ("Expires", f"{expires} ({note})" if note else expires),
+    ]
+    device = [
+        ("Device id", str(payload.get("deviceid") or NO_DEVICE_NOTE)),
+        ("Join type", str(payload.get("join_type") or "N/A")),
+    ]
+    amr = payload.get("amr") or []
+    methods = ", ".join(str(a) for a in amr) if amr else "N/A"
+    lines = _section("IDENTITY", identity) + [""]
+    lines += _section("DEVICE", device) + [""]
+    lines += ["AUTH METHODS", f"  {methods}", ""]
+    lines += ["SCOPES"] + [f"  {s}" for s in sorted(payload.get("scp", "").split())]
+    return "\n".join(lines)
+
+
+def claims(ctx: typer.Context, json_: JsonFlag = False) -> None:
+    """Decode the cached access token locally. No network call (spec §4.6)."""
+    g: Globals = ctx.find_root().obj
+    token = auth.cached_access_token()
+    if not token:
+        raise AuthError("NOT_LOGGED_IN", "no cached token", hint=errors.HINTS["NOT_LOGGED_IN"])
+    payload = auth.decode_jwt(token)
+    render.emit(TextResult(text=_claims_text(payload, g.tz), json_obj=payload), json_mode=json_)
+
+
+# --------------------------------------------------------------------------- me / version
+
+
+@graph_command(scopes=["User.Read"])
+def me(
+    client: GraphClient,
+    photo: Annotated[
+        Path | None, typer.Option("--photo", help="Save the profile photo to this file.")
+    ] = None,
+    json_: JsonFlag = False,
+):
+    """Show the signed-in user's profile, or save their photo."""
+    if photo is not None:
+        got = client.download("/me/photo/$value", photo)
+        return FileResult(
+            path=got.path,
+            bytes=got.bytes,
+            meta=dict(contentType=got.content_type),
+            message=f"Downloaded photo ({fmt_size(got.bytes)}) to {got.path}",
+        )
+    return ObjectResult(obj=users.get_me(client), fields=list(ME_FIELDS))
+
+
+def version(json_: JsonFlag = False) -> None:
+    """Show the versions of mgraphctl and the libraries it runs on."""
+    python_version = platform.python_version()
+    msal_version = importlib.metadata.version("msal")
+    httpx_version = importlib.metadata.version("httpx")
+    text = (
+        f"mgraphctl {__version__} (python {python_version},"
+        f" msal {msal_version}, httpx {httpx_version})"
+    )
+    payload = dict(
+        version=__version__, python=python_version, msal=msal_version, httpx=httpx_version
+    )
+    render.emit(TextResult(text=text, json_obj=payload), json_mode=json_)
+
+
+def register(root: typer.Typer) -> None:
+    """Attach the top-level verbs to the root app."""
+    root.command("login")(login)
+    root.command("logout")(logout)
+    root.command("status")(status)
+    root.command("claims")(claims)
+    root.command("me")(me)
+    root.command("version")(version)