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
   - import-policy-artifact: Import a published artifact into canonical policy DB rows
   - run: Start the MUD server (API and web UI)

   Usage:
       mud-server init-db
       mud-server init-db --skip-policy-import
       mud-server create-superuser
       mud-server import-policy-artifact --artifact-path PATH
       mud-server run [--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)



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_import_policy_artifact
   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.

   Initializes schema and, by default, imports/activates canonical world
   policy objects for discovered world packages. This avoids runtime reliance
   on startup-time legacy file bootstrap.

   :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_import_policy_artifact(args)

   Import one publish artifact into canonical DB policy state.


.. py:function:: cmd_run(args)

   Run the MUD server (API + WebUI).

   This is the main entry point for starting the MUD server. It initializes
   the database if needed, then starts the API server. The WebUI is served
   directly by FastAPI.

   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

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

   :param args: Parsed command-line arguments from argparse. Expected attributes:
                - port (int | None): API server port override
                - host (str | None): Host interface to bind the server

   :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 port
      mud-server run --port 9000

   .. note:: The API server runs in the main process.


.. py:function:: main()

   Main entry point for the CLI.