taibai 0.2.0__tar.gz

taibai-0.2.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.3
+Name: taibai
+Version: 0.2.0
+Summary: Fediverse CLI — celestial messenger for the federation.
+Author: marvin8
+Author-email: marvin8 <marvin8@tuta.io>
+License: AGPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications
+Classifier: Topic :: Internet
+Requires-Dist: cyclopts~=4.10.2
+Requires-Dist: httpx[http2,zstd]~=0.28.1
+Requires-Dist: keyring~=25.7.0
+Requires-Dist: longwei~=1.4.0
+Requires-Dist: platformdirs~=4.9.6
+Requires-Dist: rich~=15.0.0
+Requires-Python: >=3.11, <3.15
+Project-URL: Source, https://codeberg.org/MarvinsMastodonTools/taibai
+Project-URL: Issues, https://codeberg.org/MarvinsMastodonTools/taibai/issues
+Description-Content-Type: text/markdown
+
+# taibai
+
+Fediverse CLI tool — celestial messenger for the federation.
+
+**Taibai** (太白金星, Tàibái Jīnxīng — "Gold Star of Venus") is the celestial herald in Chinese
+mythology, tasked with carrying messages between heaven and earth. The name fits a tool that sends
+and receives communications across a federated network, and continues the Chinese mythology theme
+of its companion library [longwei](https://codeberg.org/MarvinsMastodonTools/longwei) (龙威).
+
+Built on [longwei](https://codeberg.org/MarvinsMastodonTools/longwei).
+
+## Install
+
+```sh
+uv tool install taibai
+```
+
+## Usage
+
+```sh
+taibai init                     # authenticate with a Fediverse instance
+taibai whoami                   # display current account
+taibai post "Hello, world!"     # publish a status
+taibai notifications            # show new notifications
+```
+
+Use `--profile` / `-p` (or `TAIBAI_PROFILE` env var) to manage multiple accounts.
+
+## License
+
+[AGPL-3.0-or-later](LICENSE.md)

taibai-0.2.0/README.md

@@ -0,0 +1,31 @@
+# taibai
+
+Fediverse CLI tool — celestial messenger for the federation.
+
+**Taibai** (太白金星, Tàibái Jīnxīng — "Gold Star of Venus") is the celestial herald in Chinese
+mythology, tasked with carrying messages between heaven and earth. The name fits a tool that sends
+and receives communications across a federated network, and continues the Chinese mythology theme
+of its companion library [longwei](https://codeberg.org/MarvinsMastodonTools/longwei) (龙威).
+
+Built on [longwei](https://codeberg.org/MarvinsMastodonTools/longwei).
+
+## Install
+
+```sh
+uv tool install taibai
+```
+
+## Usage
+
+```sh
+taibai init                     # authenticate with a Fediverse instance
+taibai whoami                   # display current account
+taibai post "Hello, world!"     # publish a status
+taibai notifications            # show new notifications
+```
+
+Use `--profile` / `-p` (or `TAIBAI_PROFILE` env var) to manage multiple accounts.
+
+## License
+
+[AGPL-3.0-or-later](LICENSE.md)

taibai-0.2.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "taibai"
+version = "0.2.0"
+description = "Fediverse CLI — celestial messenger for the federation."
+readme = "README.md"
+license = { text = "AGPL-3.0-or-later" }
+authors = [
+  { name = "marvin8", email = "marvin8@tuta.io" },
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Communications",
+  "Topic :: Internet",
+]
+requires-python = ">=3.11, <3.15"
+dependencies = [
+    "cyclopts~=4.10.2",
+    "httpx[http2,zstd]~=0.28.1",
+    "keyring~=25.7.0",
+    "longwei~=1.4.0",
+    "platformdirs~=4.9.6",
+    "rich~=15.0.0",
+]
+
+[project.scripts]
+taibai = "taibai.cli:app"
+
+[project.urls]
+Source = "https://codeberg.org/MarvinsMastodonTools/taibai"
+Issues = "https://codeberg.org/MarvinsMastodonTools/taibai/issues"
+
+[dependency-groups]
+dev = [
+    "bump-my-version~=1.3.0",
+    "complexipy~=5.3.0",
+    "git-cliff~=2.12.0",
+    "nox-uv~=0.7.1",
+    "prek~=0.3.9",
+    "pytest~=9.0.3",
+    "pytest-asyncio~=1.3.0",
+    "pytest-cov~=7.1.0",
+    "pytest-httpx~=0.36.2",
+    "ruff~=0.15.11",
+    "ty~=0.0.31",
+    "uv~=0.11.7",
+]
+docs = [
+    "mkdocs~=1.6.1",
+    "mkdocs-material~=9.7.6",
+    "mkdocstrings~=1.0.4",
+    "mkdocstrings-python~=2.0.3",
+    "mike~=2.2.0",
+]
+[tool.bumpversion]
+commit = true
+tag = true
+tag_name = "{new_version}"
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
+serialize = ["{major}.{minor}.{patch}"]
+message = "bump: version {current_version} → {new_version}"
+pre_commit_hooks = ["uv sync", "git add uv.lock"]
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[tool.pytest.ini_options]
+asyncio_default_fixture_loop_scope = "session"
+asyncio_mode = "auto"

taibai-0.2.0/src/taibai/__init__.py

@@ -0,0 +1 @@
+"""taibai — Fediverse CLI tool."""

taibai-0.2.0/src/taibai/_utils.py

@@ -0,0 +1,20 @@
+"""Shared helpers for taibai commands."""
+
+import asyncio
+from collections.abc import Coroutine
+from typing import Any
+
+from rich.console import Console
+
+err_console = Console(stderr=True)
+
+
+def run_async(coro: Coroutine[Any, Any, Any]) -> Any:
+    """Run an async coroutine from a synchronous command."""
+    return asyncio.run(coro)
+
+
+def die(message: str, exit_code: int = 1) -> None:
+    """Print an error to stderr and exit."""
+    err_console.print(f"[bold red]Error:[/bold red] {message}")
+    raise SystemExit(exit_code)

taibai-0.2.0/src/taibai/cli.py

@@ -0,0 +1,18 @@
+"""Taibai CLI entry point."""
+
+from cyclopts import App
+
+from taibai.commands.init import init_command
+from taibai.commands.notifications import notifications_command
+from taibai.commands.post import post_command
+from taibai.commands.whoami import whoami_command
+
+app = App(
+    name="taibai",
+    help="Fediverse CLI — celestial messenger for the federation.",
+)
+
+app.command(name="init")(init_command)
+app.command(name="post")(post_command)
+app.command(name="notifications")(notifications_command)
+app.command(name="whoami")(whoami_command)

taibai-0.2.0/src/taibai/commands/__init__.py

@@ -0,0 +1 @@
+"""Taibai CLI commands."""

taibai-0.2.0/src/taibai/commands/init.py

@@ -0,0 +1,111 @@
+"""The `init` command: register an app and complete the OAuth flow."""
+
+import sys
+from importlib.metadata import version
+from typing import Annotated
+
+import httpx
+from cyclopts import Parameter
+from longwei import ActivityPubError
+from longwei import APClient
+from longwei import NetworkError
+from longwei import UnauthorizedError
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Confirm
+from rich.prompt import Prompt
+
+from taibai._utils import die
+from taibai._utils import run_async
+from taibai.config import Profile
+from taibai.config import get_profile
+from taibai.config import save_profile
+from taibai.credentials import save_token
+
+console = Console()
+
+_CLIENT_WEBSITE = "https://codeberg.org/MarvinsMastodonTools/taibai"
+_USER_AGENT = f"taibai_v{version('taibai')}_Python_{sys.version.split()[0]}"
+
+
+def init_command(
+    instance: Annotated[str | None, Parameter(name=["--instance", "-i"], help="Fediverse instance URL.")] = None,
+    profile: Annotated[
+        str, Parameter(name=["--profile", "-p"], help="Profile name.", env_var="TAIBAI_PROFILE")
+    ] = "default",
+) -> None:
+    """Register an app with a Fediverse instance and store credentials locally."""
+    if instance is None:
+        instance = Prompt.ask("Instance URL (e.g. https://mastodon.social)")
+
+    instance = instance.rstrip("/")
+    if "://" not in instance:
+        instance = f"https://{instance}"
+
+    existing = get_profile(profile)
+    if existing is not None:
+        confirmed = Confirm.ask(
+            f"Profile '{profile}' already exists ({existing.username} on {existing.instance_url}). Overwrite?"
+        )
+        if not confirmed:
+            raise SystemExit(0)
+
+    try:
+        run_async(_do_init(instance, profile))
+    except NetworkError as exc:
+        die(f"Network error: could not reach {instance}. {exc.message or ''}")
+    except UnauthorizedError:
+        die("Authorization code was rejected. Please try `taibai init` again.")
+    except ActivityPubError as exc:
+        die(f"Fediverse error: {exc.message or str(exc)}")
+    except httpx.ConnectError:
+        die(f"Could not connect to {instance}. Check the URL and your network connection.")
+
+
+async def _do_init(instance_url: str, profile_name: str) -> None:
+    """Perform the OAuth flow and save credentials."""
+    async with httpx.AsyncClient() as http_client:
+        client_id, client_secret = await APClient.create_app(
+            instance_url,
+            http_client,
+            user_agent=_USER_AGENT,
+            client_website=_CLIENT_WEBSITE,
+        )
+
+        auth_url = await APClient.generate_authorization_url(instance_url, client_id)
+
+        console.print(f"\nOpen this URL in your browser:\n\n  [link={auth_url}]{auth_url}[/link]\n")
+
+        code = Prompt.ask("Paste the authorization code")
+        code = code.strip()
+
+        access_token = await APClient.validate_authorization_code(
+            http_client,
+            instance_url,
+            code,
+            client_id,
+            client_secret,
+        )
+
+        ap = await APClient.create(instance_url, http_client, access_token)
+        account = await ap.verify_credentials()
+
+        save_profile(
+            Profile(
+                name=profile_name,
+                instance_url=instance_url,
+                client_id=client_id,
+                client_secret=client_secret,
+                username=account.acct or "",
+            )
+        )
+        save_token(profile_name, access_token)
+
+    console.print(
+        Panel(
+            f"[bold]@{account.acct}[/bold]\n[dim]{instance_url}[/dim]",
+            title="[green]Connected[/green]",
+            border_style="green",
+        )
+    )
+    console.print(f"Profile [bold]{profile_name!r}[/bold] saved.")

taibai-0.2.0/src/taibai/commands/notifications.py

@@ -0,0 +1,130 @@
+"""The `notifications` command: display unread (or all) notifications."""
+
+from html.parser import HTMLParser
+from typing import Annotated
+
+import httpx
+from cyclopts import Parameter
+from longwei import ActivityPubError
+from longwei import APClient
+from longwei import NetworkError
+from longwei import Notification
+from longwei import UnauthorizedError
+from rich.console import Console
+from rich.table import Table
+
+from taibai._utils import die
+from taibai._utils import run_async
+from taibai.config import get_profile
+from taibai.config import update_last_seen_notification
+from taibai.credentials import load_token
+
+console = Console()
+
+
+class _HTMLStripper(HTMLParser):
+    """Minimal HTML tag stripper using stdlib html.parser."""
+
+    def __init__(self) -> None:
+        """Initialise with an empty text buffer."""
+        super().__init__()
+        self._parts: list[str] = []
+
+    def handle_data(self, data: str) -> None:
+        """Accumulate text nodes."""
+        self._parts.append(data)
+
+    def get_text(self) -> str:
+        """Return the accumulated plain text."""
+        return "".join(self._parts)
+
+
+def _strip_html(html: str) -> str:
+    """Strip all HTML tags from a string and return plain text."""
+    stripper = _HTMLStripper()
+    stripper.feed(html)
+    return stripper.get_text()
+
+
+def notifications_command(
+    all_notifications: Annotated[
+        bool, Parameter(name=["--all"], negative="", help="Show all notifications, not just new ones.")
+    ] = False,
+    limit: Annotated[
+        int | None, Parameter(name=["--limit", "-n"], help="Maximum number of notifications to fetch.")
+    ] = None,
+    profile: Annotated[
+        str, Parameter(name=["--profile", "-p"], help="Profile name.", env_var="TAIBAI_PROFILE")
+    ] = "default",
+) -> None:
+    """Show notifications. Defaults to unread only; use --all to show everything."""
+    stored_profile = get_profile(profile)
+    if stored_profile is None:
+        die(f"Profile '{profile}' not found. Run `taibai init --profile {profile}`.")
+        return
+
+    access_token = load_token(profile)
+    if access_token is None:
+        die(f"No credentials for profile '{profile}'. Run `taibai init --profile {profile}`.")
+        return
+
+    since_id = None if all_notifications else stored_profile.last_seen_notification_id
+
+    try:
+        run_async(
+            _do_notifications(
+                stored_profile.instance_url,
+                access_token,
+                profile,
+                since_id=since_id,
+                limit=limit,
+            )
+        )
+    except UnauthorizedError:
+        die(f"Access token rejected. Re-run `taibai init --profile {profile}`.")
+    except NetworkError as exc:
+        die(f"Network error: could not reach {stored_profile.instance_url}. {exc.message or ''}")
+    except ActivityPubError as exc:
+        die(f"Fediverse error: {exc.message or str(exc)}")
+    except httpx.ConnectError:
+        die(f"Could not connect to {stored_profile.instance_url}.")
+
+
+async def _do_notifications(
+    instance_url: str,
+    access_token: str,
+    profile_name: str,
+    since_id: str | None,
+    limit: int | None,
+) -> None:
+    """Fetch and display notifications, updating last-seen state."""
+    async with httpx.AsyncClient() as http_client:
+        ap = await APClient.create(instance_url, http_client, access_token)
+        notifications: list[Notification] = await ap.get_notifications(
+            since_id=since_id,
+            limit=limit,
+        )
+
+    if not notifications:
+        console.print("[dim]No new notifications.[/dim]")
+        return
+
+    table = Table(show_header=True, header_style="bold magenta", show_lines=False)
+    table.add_column("Type", style="cyan", width=14, no_wrap=True)
+    table.add_column("From", style="green", width=28, no_wrap=True)
+    table.add_column("Preview", overflow="fold")
+    table.add_column("Time", style="dim", width=16, no_wrap=True)
+
+    for notif in notifications:
+        from_acct = notif.account.acct if notif.account else "unknown"
+        preview = ""
+        if notif.status is not None and notif.status.content:
+            preview = _strip_html(notif.status.content)[:100]
+        time_str = (notif.created_at[:16] if notif.created_at else "").replace("T", " ")
+        table.add_row(notif.type, f"@{from_acct}", preview, time_str)
+
+    console.print(table)
+
+    # Update last-seen to the first (newest) notification ID.
+    if notifications[0].id is not None:
+        update_last_seen_notification(profile_name, notifications[0].id)

taibai-0.2.0/src/taibai/commands/post.py

@@ -0,0 +1,293 @@
+"""The `post` command: publish a status."""
+
+import mimetypes
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Annotated
+
+import httpx
+from cyclopts import Parameter
+from longwei import ActivityPubError
+from longwei import APClient
+from longwei import NetworkError
+from longwei import RatelimitError
+from longwei import UnauthorizedError
+from longwei import Visibility
+from rich.console import Console
+
+from taibai._utils import die
+from taibai._utils import run_async
+from taibai.config import get_profile
+from taibai.credentials import load_token
+
+console = Console()
+
+
+def _ratelimit_message(exc: RatelimitError) -> str:
+    """Return a human-readable rate-limit error message."""
+    if exc.ratelimit_reset is not None:
+        return f"Rate limit exceeded. Retry after {exc.ratelimit_reset.strftime('%H:%M:%S UTC')}."
+    return "Rate limit exceeded. Please try again later."
+
+
+_VISIBILITY_MAP: dict[str, Visibility] = {
+    "public": Visibility.PUBLIC,
+    "unlisted": Visibility.UNLISTED,
+    "private": Visibility.PRIVATE,
+    "direct": Visibility.DIRECT,
+}
+
+
+def _resolve_text(text: str | None, file: Path | None) -> str:
+    """Resolve status text from positional arg, --file, or stdin.
+
+    Args:
+        text: Positional text argument (None if omitted, '-' for stdin).
+        file: Optional path to a text file containing the status body.
+
+    Returns:
+        The resolved status text string.
+
+    """
+    if file is not None:
+        if text is not None:
+            die("Cannot combine --file with a positional text argument or stdin ('-').")
+        return file.read_text(encoding="utf-8")
+    if text == "-":
+        return sys.stdin.read()
+    if text is not None:
+        return text
+    die("Provide status text, --file PATH, or pipe via stdin ('-').")
+    return ""  # unreachable; die() raises SystemExit
+
+
+def _validate_post_options(poll_options: Sequence[str], attach: Sequence[str], poll_expires: int) -> None:
+    """Validate poll and attachment option combinations.
+
+    Args:
+        poll_options: Poll option strings.
+        attach: File paths to attach.
+        poll_expires: Poll expiry duration in seconds.
+
+    """
+    if len(poll_options) == 1:
+        die("A poll requires at least 2 options.")
+    if len(poll_options) > 4:
+        die("Mastodon supports at most 4 poll options.")
+    if poll_options and attach:
+        die("Cannot combine a poll with media attachments (Mastodon limitation).")
+    if poll_options and poll_expires < 300:
+        die("Poll expiry must be at least 300 seconds (5 minutes).")
+
+
+async def _upload_attachments(
+    ap: APClient,
+    attach: Sequence[str],
+    alt_texts: Sequence[str],
+) -> list[str]:
+    """Upload media attachments and return their IDs.
+
+    Args:
+        ap: Authenticated APClient instance.
+        attach: Local file paths to upload.
+        alt_texts: Alt-text strings, paired positionally with attach.
+
+    Returns:
+        List of media attachment IDs ready to pass to post_status().
+
+    """
+    media_ids: list[str] = []
+    for i, path_str in enumerate(attach):
+        alt: str | None = alt_texts[i] if i < len(alt_texts) else None
+        mime, _ = mimetypes.guess_type(path_str)
+        with Path(path_str).open("rb") as fh:
+            attachment = await ap.post_media(fh, mime_type=mime or "application/octet-stream", description=alt)
+        if attachment.id is None:
+            die(f"Server did not return an ID for attachment '{path_str}'.")
+            return media_ids  # unreachable
+        media_ids.append(attachment.id)
+    return media_ids
+
+
+def _resolve_visibility(visibility: str) -> Visibility:
+    """Resolve a visibility string to a Visibility enum value, dying on invalid input.
+
+    Args:
+        visibility: One of 'public', 'unlisted', 'private', or 'direct'.
+
+    Returns:
+        The matching Visibility enum value.
+
+    """
+    if visibility not in _VISIBILITY_MAP:
+        die(f"Invalid visibility {visibility!r}. Choose from: {', '.join(_VISIBILITY_MAP)}.")
+    return _VISIBILITY_MAP[visibility]  # type: ignore[return-value]
+
+
+def _post_impl(  # noqa: PLR0913
+    text: str | None,
+    file: Path | None,
+    visibility: str,
+    cw: str | None,
+    attach: list[str],
+    alt_text: list[str],
+    sensitive: bool,
+    poll_option: list[str],
+    poll_expires: int,
+    poll_multiple: bool,
+    poll_hide_totals: bool,
+    profile: str,
+) -> None:
+    """Execute post logic: resolve text, validate options, load credentials, run async call.
+
+    Args:
+        text: Raw text argument (may be None or '-').
+        file: Optional path to read status text from.
+        visibility: Visibility string ('public', 'unlisted', etc.).
+        cw: Optional content warning / spoiler text.
+        attach: Local file paths to upload as media.
+        alt_text: Alt texts positionally paired with attach.
+        sensitive: Whether to mark media as sensitive.
+        poll_option: Poll option strings.
+        poll_expires: Poll duration in seconds.
+        poll_multiple: Allow multiple selections.
+        poll_hide_totals: Hide vote totals until closed.
+        profile: Profile name to use.
+
+    """
+    resolved_text = _resolve_text(text, file)
+    _validate_post_options(poll_option, attach, poll_expires)
+    vis = _resolve_visibility(visibility)
+
+    stored_profile = get_profile(profile)
+    if stored_profile is None:
+        die(f"Profile '{profile}' not found. Run `taibai init --profile {profile}`.")
+        return
+
+    access_token = load_token(profile)
+    if access_token is None:
+        die(f"No credentials for profile '{profile}'. Run `taibai init --profile {profile}`.")
+        return
+
+    try:
+        run_async(
+            _do_post(
+                stored_profile.instance_url,
+                access_token,
+                resolved_text,
+                vis,
+                cw,
+                attach=attach,
+                alt_texts=alt_text,
+                sensitive=sensitive,
+                poll_options=poll_option,
+                poll_expires_in=poll_expires,
+                poll_multiple=poll_multiple,
+                poll_hide_totals=poll_hide_totals,
+            )
+        )
+    except OSError as exc:
+        die(f"Could not read attachment: {exc}")
+    except UnauthorizedError:
+        die(f"Access token rejected. Re-run `taibai init --profile {profile}`.")
+    except RatelimitError as exc:
+        die(_ratelimit_message(exc))
+    except NetworkError as exc:
+        die(f"Network error: could not reach {stored_profile.instance_url}. {exc.message or ''}")
+    except ActivityPubError as exc:
+        die(f"Fediverse error: {exc.message or str(exc)}")
+    except httpx.ConnectError:
+        die(f"Could not connect to {stored_profile.instance_url}.")
+
+
+def post_command(  # noqa: PLR0913
+    text: Annotated[
+        str | None, Parameter(help="Text to post. Use '-' to read from stdin.", allow_leading_hyphen=True)
+    ] = None,
+    visibility: Annotated[
+        str, Parameter(name=["--visibility", "-v"], help="Visibility: public, unlisted, private, or direct.")
+    ] = "public",
+    cw: Annotated[str | None, Parameter(name=["--cw"], help="Content warning / subject line.")] = None,
+    file: Annotated[Path | None, Parameter(name=["--file"], help="Read status text from this file.")] = None,
+    attach: Annotated[
+        list[str] | None,
+        Parameter(name=["--attach"], help="Media file to attach (repeatable; server enforces max)."),
+    ] = None,
+    alt_text: Annotated[
+        list[str] | None,
+        Parameter(name=["--alt-text"], help="Alt text for the corresponding --attach (positionally paired)."),
+    ] = None,
+    sensitive: Annotated[bool, Parameter(name=["--sensitive"], help="Mark attached media as sensitive.")] = False,
+    poll_option: Annotated[
+        list[str] | None,
+        Parameter(name=["--poll-option"], help="Add a poll option (repeatable, min 2, max 4)."),
+    ] = None,
+    poll_expires: Annotated[
+        int, Parameter(name=["--poll-expires"], help="Poll duration in seconds (default: 86400, min: 300).")
+    ] = 86400,
+    poll_multiple: Annotated[
+        bool, Parameter(name=["--poll-multiple"], help="Allow voters to select multiple options.")
+    ] = False,
+    poll_hide_totals: Annotated[
+        bool, Parameter(name=["--poll-hide-totals"], help="Hide vote totals until poll closes.")
+    ] = False,
+    profile: Annotated[
+        str, Parameter(name=["--profile", "-p"], help="Profile name.", env_var="TAIBAI_PROFILE")
+    ] = "default",
+) -> None:
+    """Publish a status to the Fediverse."""
+    _post_impl(
+        text=text,
+        file=file,
+        visibility=visibility,
+        cw=cw,
+        attach=attach or [],
+        alt_text=alt_text or [],
+        sensitive=sensitive,
+        poll_option=poll_option or [],
+        poll_expires=poll_expires,
+        poll_multiple=poll_multiple,
+        poll_hide_totals=poll_hide_totals,
+        profile=profile,
+    )
+
+
+async def _do_post(  # noqa: PLR0913
+    instance_url: str,
+    access_token: str,
+    text: str,
+    visibility: Visibility,
+    cw: str | None,
+    *,
+    attach: Sequence[str],
+    alt_texts: Sequence[str],
+    sensitive: bool,
+    poll_options: Sequence[str],
+    poll_expires_in: int,
+    poll_multiple: bool,
+    poll_hide_totals: bool,
+) -> None:
+    """Upload any attachments then post the status and print its URL."""
+    async with httpx.AsyncClient() as http_client:
+        ap = await APClient.create(instance_url, http_client, access_token)
+
+        if len(attach) > ap.max_attachments:
+            die(f"Cannot attach more than {ap.max_attachments} files on this instance.")
+
+        media_ids = await _upload_attachments(ap, attach, alt_texts) if attach else []
+
+        status = await ap.post_status(
+            text,
+            visibility=visibility,
+            spoiler_text=cw,
+            media_ids=media_ids or None,
+            sensitive=sensitive if media_ids else False,
+            poll_options=list(poll_options) if poll_options else None,
+            poll_expires_in=poll_expires_in if poll_options else None,
+            poll_multiple=poll_multiple if poll_options else False,
+            poll_hide_totals=poll_hide_totals if poll_options else False,
+        )
+
+    url = status.url or status.uri
+    console.print(f"Posted: [link={url}]{url}[/link]")

taibai-0.2.0/src/taibai/commands/whoami.py

@@ -0,0 +1,66 @@
+"""The `whoami` command: verify credentials and display the current account."""
+
+from typing import Annotated
+
+import httpx
+from cyclopts import Parameter
+from longwei import ActivityPubError
+from longwei import APClient
+from longwei import NetworkError
+from longwei import UnauthorizedError
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from taibai._utils import die
+from taibai._utils import run_async
+from taibai.config import get_profile
+from taibai.credentials import load_token
+
+console = Console()
+
+
+def whoami_command(
+    profile: Annotated[
+        str, Parameter(name=["--profile", "-p"], help="Profile name.", env_var="TAIBAI_PROFILE")
+    ] = "default",
+) -> None:
+    """Verify stored credentials and display the current account."""
+    stored_profile = get_profile(profile)
+    if stored_profile is None:
+        die(f"Profile '{profile}' not found. Run `taibai init --profile {profile}`.")
+        return
+
+    access_token = load_token(profile)
+    if access_token is None:
+        die(f"No credentials for profile '{profile}'. Run `taibai init --profile {profile}`.")
+        return
+
+    try:
+        run_async(_do_whoami(stored_profile.instance_url, access_token))
+    except UnauthorizedError:
+        die(f"Access token rejected. Re-run `taibai init --profile {profile}`.")
+    except NetworkError as exc:
+        die(f"Network error: could not reach {stored_profile.instance_url}. {exc.message or ''}")
+    except ActivityPubError as exc:
+        die(f"Fediverse error: {exc.message or str(exc)}")
+    except httpx.ConnectError:
+        die(f"Could not connect to {stored_profile.instance_url}.")
+
+
+async def _do_whoami(instance_url: str, access_token: str) -> None:
+    """Fetch and display account info."""
+    async with httpx.AsyncClient() as http_client:
+        ap = await APClient.create(instance_url, http_client, access_token)
+        account = await ap.verify_credentials()
+
+    display = account.display_name or account.username or account.acct
+    text = Text()
+    text.append(f"{display}\n", style="bold")
+    text.append(f"@{account.acct}\n", style="green")
+    text.append(f"{instance_url}\n\n", style="dim")
+    text.append(
+        f"Followers: {account.followers_count}  Following: {account.following_count}  Posts: {account.statuses_count}"
+    )
+
+    console.print(Panel(text, title="Account Info", border_style="blue"))

taibai-0.2.0/src/taibai/config.py

@@ -0,0 +1,96 @@
+"""Profile configuration management for taibai."""
+
+import json
+import os
+from dataclasses import asdict
+from dataclasses import dataclass
+from pathlib import Path
+
+import platformdirs
+
+
+@dataclass
+class Profile:
+    """A named account profile storing instance and app registration data."""
+
+    name: str
+    instance_url: str
+    client_id: str
+    client_secret: str
+    username: str
+    last_seen_notification_id: str | None = None
+
+
+def config_path() -> Path:
+    """Return the path to config.json, creating the parent directory if needed."""
+    config_dir = Path(platformdirs.user_config_dir("taibai", ensure_exists=True))
+    return config_dir / "config.json"
+
+
+def load_config() -> dict:
+    """Load and return the raw config dict. Returns empty dict if file absent."""
+    path = config_path()
+    if not path.exists():
+        return {}
+    with path.open("r", encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def save_config(config: dict) -> None:
+    """Atomically write the config dict to config.json."""
+    path = config_path()
+    tmp = path.with_suffix(".json.tmp")
+    with tmp.open("w", encoding="utf-8") as fh:
+        json.dump(config, fh, indent=2)
+        fh.write("\n")
+    os.replace(tmp, path)
+
+
+def get_profile(name: str) -> Profile | None:
+    """Return the named Profile, or None if it does not exist."""
+    config = load_config()
+    raw = config.get("profiles", {}).get(name)
+    if raw is None:
+        return None
+    return Profile(**raw)
+
+
+def save_profile(profile: Profile) -> None:
+    """Insert or update a profile in config.json."""
+    config = load_config()
+    config.setdefault("profiles", {})[profile.name] = asdict(profile)
+    if "default_profile" not in config:
+        config["default_profile"] = profile.name
+    save_config(config)
+
+
+def delete_profile(name: str) -> None:
+    """Remove a profile from config.json. Silent if not found."""
+    config = load_config()
+    config.get("profiles", {}).pop(name, None)
+    if config.get("default_profile") == name:
+        remaining = list(config.get("profiles", {}).keys())
+        config["default_profile"] = remaining[0] if remaining else None
+    save_config(config)
+
+
+def get_default_profile_name() -> str | None:
+    """Return the name of the default profile, or None if no profiles exist."""
+    config = load_config()
+    return config.get("default_profile")
+
+
+def set_default_profile(name: str) -> None:
+    """Set the named profile as the default."""
+    config = load_config()
+    config["default_profile"] = name
+    save_config(config)
+
+
+def update_last_seen_notification(profile_name: str, notification_id: str) -> None:
+    """Update last_seen_notification_id for a profile."""
+    config = load_config()
+    profiles = config.get("profiles", {})
+    if profile_name in profiles:
+        profiles[profile_name]["last_seen_notification_id"] = notification_id
+        save_config(config)

taibai-0.2.0/src/taibai/credentials.py

@@ -0,0 +1,94 @@
+"""Credential storage for taibai.
+
+Tokens are stored in the OS keyring where available. On headless systems
+(no SecretService / D-Bus), the module falls back to the config file and
+prints a one-time warning. The fallback is plaintext; users can migrate to a
+real keyring at any time by re-running `taibai init`.
+"""
+
+import logging
+
+import keyring
+import keyring.errors
+from rich.console import Console
+
+from taibai.config import config_path
+from taibai.config import load_config
+from taibai.config import save_config
+
+logger = logging.getLogger(__name__)
+
+_KEYRING_SERVICE = "taibai"
+_WARNED: set[str] = set()  # profiles for which the headless warning was printed
+_err = Console(stderr=True)
+
+
+def _key(profile_name: str) -> str:
+    """Return the keyring username key for a profile."""
+    return f"taibai::{profile_name}"
+
+
+def _warn_headless(profile_name: str) -> None:
+    """Print a one-time warning that the file fallback is active."""
+    if profile_name not in _WARNED:
+        _WARNED.add(profile_name)
+        _err.print(
+            "[yellow]Warning:[/yellow] No keyring backend available. "
+            f"Token for profile '{profile_name}' is stored in plaintext at "
+            f"{config_path()} — protect this file accordingly."
+        )
+
+
+# ── file-based fallback ────────────────────────────────────────────────────
+
+
+def _save_fallback(profile_name: str, access_token: str) -> None:
+    """Persist token in config.json under _tokens."""
+    cfg = load_config()
+    cfg.setdefault("_tokens", {})[profile_name] = access_token
+    save_config(cfg)
+
+
+def _load_fallback(profile_name: str) -> str | None:
+    """Load token from config.json fallback store."""
+    return load_config().get("_tokens", {}).get(profile_name)
+
+
+def _delete_fallback(profile_name: str) -> None:
+    """Remove token from config.json fallback store."""
+    cfg = load_config()
+    cfg.get("_tokens", {}).pop(profile_name, None)
+    save_config(cfg)
+
+
+# ── public API ─────────────────────────────────────────────────────────────
+
+
+def save_token(profile_name: str, access_token: str) -> None:
+    """Save an access token to the OS keyring, falling back to config file."""
+    try:
+        keyring.set_password(_KEYRING_SERVICE, _key(profile_name), access_token)
+    except Exception as exc:  # broad catch intentional: covers dbus/headless variants
+        logger.debug("Keyring unavailable for save (%s); using file fallback.", exc)
+        _warn_headless(profile_name)
+        _save_fallback(profile_name, access_token)
+
+
+def load_token(profile_name: str) -> str | None:
+    """Load an access token. Checks keyring first, then config-file fallback."""
+    try:
+        token = keyring.get_password(_KEYRING_SERVICE, _key(profile_name))
+        if token is not None:
+            return token
+    except Exception as exc:  # broad catch intentional: covers dbus/headless variants
+        logger.debug("Keyring unavailable for load (%s); using file fallback.", exc)
+    return _load_fallback(profile_name)
+
+
+def delete_token(profile_name: str) -> None:
+    """Delete an access token from keyring and config-file fallback."""
+    try:
+        keyring.delete_password(_KEYRING_SERVICE, _key(profile_name))
+    except Exception as exc:  # broad catch intentional: covers PasswordDeleteError + dbus variants
+        logger.debug("Keyring delete skipped (%s).", exc)
+    _delete_fallback(profile_name)