mud_server.cli
==============

.. py:module:: mud_server.cli

.. autoapi-nested-parse::

   Command-line interface for PipeWorks MUD Server.

   Provides CLI commands for server management:
   - init-db: Initialize the database schema
   - create-superuser: Create a superuser account interactively or via environment variables
   - run: Start the MUD server (API and web UI)

   Usage:
       mud-server init-db
       mud-server create-superuser
       mud-server run [--port PORT] [--ui-port PORT] [--host HOST]

   Environment Variables:
       MUD_ADMIN_USER: Username for superuser (used by init-db if set)
       MUD_ADMIN_PASSWORD: Password for superuser (used by init-db if set)
       MUD_HOST: Host to bind API server (default: 0.0.0.0)
       MUD_PORT: Port for API server (default: 8000, auto-discovers if in use)
       MUD_UI_HOST: Host to bind UI server (default: 0.0.0.0)
       MUD_UI_PORT: Port for UI server (default: 7860, auto-discovers if in use)



Functions
---------

.. autoapisummary::

   mud_server.cli.get_superuser_credentials_from_env
   mud_server.cli.prompt_for_credentials
   mud_server.cli.cmd_init_db
   mud_server.cli.cmd_create_superuser
   mud_server.cli.cmd_run
   mud_server.cli.main


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

.. py:function:: get_superuser_credentials_from_env()

   Get superuser credentials from environment variables.

   :returns: Tuple of (username, password) if both MUD_ADMIN_USER and MUD_ADMIN_PASSWORD are set.
             None if either is missing.


.. py:function:: prompt_for_credentials()

   Interactively prompt for superuser credentials with password policy enforcement.

   This function guides the user through creating secure credentials by:
   1. Validating username length (2-20 characters)
   2. Displaying password requirements before input
   3. Validating password against the STANDARD security policy
   4. Requiring password confirmation

   The STANDARD password policy requires:
   - Minimum 12 characters
   - Not a commonly used password
   - No sequential characters (abc, 123)
   - No excessive repeated characters (aaa)

   :returns: Tuple of (username, password) that meet security requirements.

   :raises SystemExit: If the user cancels (Ctrl+C) during input.

   .. seealso:: mud_server.api.password_policy: Full policy configuration details.


.. py:function:: cmd_init_db(args)

   Initialize the database schema.

   If MUD_ADMIN_USER and MUD_ADMIN_PASSWORD environment variables are set,
   creates a superuser with those credentials. Otherwise, just creates the
   schema and prints instructions for creating a superuser.

   :returns: 0 on success, 1 on error


.. py:function:: cmd_create_superuser(args)

   Create a superuser account.

   Checks for MUD_ADMIN_USER and MUD_ADMIN_PASSWORD environment variables first.
   If not set, prompts interactively for credentials.

   :returns: 0 on success, 1 on error


.. py:function:: cmd_run(args)

   Run the MUD server (both API and client).

   This is the main entry point for starting the MUD server. It initializes
   the database if needed, then starts the API server and optionally the
   Gradio UI client in parallel processes.

   Port Auto-Discovery:
       If the configured port is already in use, the server will automatically
       find an available port in a predefined range:
       - API server: 8000-8099
       - UI client: 7860-7899

       IMPORTANT: When both servers are started together, the API port is
       discovered first and communicated to the UI client via the MUD_SERVER_URL
       environment variable. This ensures the UI always knows where to find
       the API server, even when using auto-discovered ports.

   Configuration Priority:
       1. CLI arguments (--port, --ui-port, --host)
       2. Environment variables (MUD_PORT, MUD_UI_PORT, MUD_HOST, MUD_UI_HOST)
       3. Default values (8000 for API, 7860 for UI, 0.0.0.0 for host)

   :param args: Parsed command-line arguments from argparse. Expected attributes:
                - port (int | None): API server port override
                - ui_port (int | None): UI server port override
                - host (str | None): Host interface to bind both servers
                - api_only (bool): If True, only start API server (no Gradio UI)

   :returns: 0 on successful execution or clean shutdown (Ctrl+C)
             1 on error during startup

   .. admonition:: Example

      # Start with default ports
      mud-server run
      
      # Specify custom ports
      mud-server run --port 9000 --ui-port 8080
      
      # Start API server only
      mud-server run --api-only

   .. note::

      Both servers run as separate processes using multiprocessing.Process.
      This allows them to run truly in parallel and handle their own signals.
      The main process waits for both to complete (join).


.. py:function:: main()

   Main entry point for the CLI.