mud_server.admin_tui.app
========================

.. py:module:: mud_server.admin_tui.app

.. autoapi-nested-parse::

   Main application module for PipeWorks Admin TUI.

   This module defines the AdminApp class, which is the main Textual
   application for the admin interface. It manages:
   - Screen navigation (login -> dashboard)
   - API client lifecycle
   - Authentication flow

   Entry Point:
       The main() function serves as the CLI entry point, configured
       in pyproject.toml as the "pipeworks-admin-tui" console script.

   .. admonition:: Example

      # Run from command line
      pipeworks-admin-tui --server http://localhost:8000
      
      # Or programmatically
      from mud_server.admin_tui import AdminApp, Config
      
      config = Config.from_args()
      app = AdminApp(config)
      app.run()



Classes
-------

.. autoapisummary::

   mud_server.admin_tui.app.AdminApp


Functions
---------

.. autoapisummary::

   mud_server.admin_tui.app.main


Module Contents
---------------

.. py:class:: AdminApp(config)

   Bases: :py:obj:`textual.app.App`


   Main Textual application for PipeWorks Admin TUI.

   This application provides a terminal-based interface for administering
   the MUD server. It handles authentication, displays server status,
   and provides administrative actions.

   .. attribute:: config

      Application configuration (server URL, timeout).

   .. attribute:: api_client

      HTTP client for server communication. Created on mount.

   Lifecycle:
       1. on_mount: Creates API client, pushes LoginScreen
       2. do_login: Authenticates, switches to DashboardScreen
       3. do_logout: Clears session, returns to LoginScreen
       4. on_unmount: Closes API client

   Key Bindings (App-level):
       ctrl+c: Quit application (always available)
       ctrl+q: Quit application (always available)

   .. admonition:: Example

      config = Config(server_url="http://localhost:8000", timeout=30.0)
      app = AdminApp(config)
      app.run()

   Initialize the admin application.

   :param config: Application configuration object.


   .. py:attribute:: TITLE
      :value: 'PipeWorks Admin'



   .. py:attribute:: SUB_TITLE
      :value: 'MUD Server Administration'



   .. py:attribute:: BINDINGS


   .. py:attribute:: CSS
      :value: Multiline-String

      .. raw:: html

         <details><summary>Show Value</summary>

      .. code-block:: python

         """
             Screen {
                 background: $surface;
             }
             """

      .. raw:: html

         </details>




   .. py:attribute:: config


   .. py:attribute:: keybindings


   .. py:attribute:: api_client
      :type:  mud_server.admin_tui.api.client.AdminAPIClient | None
      :value: None



   .. py:method:: on_mount()
      :async:


      Called when the application is mounted.

      Creates the API client and pushes the initial login screen.



   .. py:method:: on_unmount()
      :async:


      Called when the application is unmounted.

      Logs out from server (if authenticated) and closes the API client.
      This ensures the session is properly cleaned up on the server side,
      keeping the active player count accurate.



   .. py:method:: do_login(username, password)
      :async:


      Perform login and transition to dashboard.

      Called by LoginScreen when credentials are submitted.

      :param username: The username to authenticate.
      :param password: The user's password.

      :raises AuthenticationError: If login fails.



   .. py:method:: do_logout()
      :async:


      Perform logout and return to login screen.

      Called by DashboardScreen when user requests logout.



.. py:function:: main(args = None)

   Main entry point for the Admin TUI.

   Parses command-line arguments, creates the application,
   and runs the event loop.

   :param args: Command-line arguments. If None, uses sys.argv[1:].

   :returns: Exit code (0 for success, non-zero for errors).

   .. admonition:: Example

      # Normal usage (reads sys.argv)
      sys.exit(main())
      
      # Testing
      main(["--server", "http://localhost:8000"])