flshbd 0.0.9__py3-none-any.whl

flshbd/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2026-present Robert Kormann <rokor@kormann.info>
+#
+# SPDX-License-Identifier: Unlicense
+__version__ = "0.0.9"

flshbd/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: 2026-present Robert Kormann <rokor@kormann.info>
+#
+# SPDX-License-Identifier: Unlicense
+
+from flshbd.core.env import bootstrap
+
+# Load the environment's .env file (if any) before any flshbd submodule is
+# imported -- in particular before flshbd.core.config, whose FLSHBD_* values
+# are read from the environment at import time. No-op under pytest.
+bootstrap()

flshbd/__main__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2026-present Robert Kormann <rokor@kormann.info>
+#
+# SPDX-License-Identifier: Unlicense
+import sys
+
+if __name__ == "__main__":
+    from flshbd.cli import fld
+
+    sys.exit(fld())

flshbd/cli/__init__.py

@@ -0,0 +1,66 @@
+# SPDX-FileCopyrightText: 2026-present Robert Kormann <rokor@kormann.info>
+#
+# SPDX-License-Identifier: Unlicense
+import click
+
+from flshbd.__about__ import __version__
+from flshbd.cli.access import get_access_commands
+from flshbd.cli.dash import get_dash_commands
+from flshbd.cli.db import get_database_commands
+from flshbd.cli.groups import get_group_commands
+from flshbd.cli.site_groups import get_site_group_commands
+from flshbd.cli.sites import get_site_commands
+from flshbd.cli.users import get_user_commands
+
+
+@click.group(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    invoke_without_command=True,
+)
+@click.option(
+    "--env",
+    "-e",
+    "env",
+    default="default",
+    type=click.Choice(["development", "production", "testing", "default"]),
+    help="Environment to use (development, production, testing, default)",
+)
+@click.version_option(version=__version__, prog_name="fld")
+@click.pass_context
+def fld(ctx, env: str):
+    """FlashBoard CLI"""
+    # Set the current config for this process
+    from flshbd.core.config import set_current_config
+
+    set_current_config(env)
+    # Store environment in context for all subcommands
+    ctx.obj = {"env": env}
+
+
+# Add dash subcommands
+dash = get_dash_commands()
+fld.add_command(dash, "dash")
+
+# Add database management commands
+db = get_database_commands()
+fld.add_command(db, "db")
+
+# Add user management commands
+user_cmd = get_user_commands()
+fld.add_command(user_cmd, "user")
+
+# Add group management commands
+group_cmd = get_group_commands()
+fld.add_command(group_cmd, "group")
+
+# Add site management commands
+site_cmd = get_site_commands()
+fld.add_command(site_cmd, "site")
+
+# Add site group management commands
+site_group_cmd = get_site_group_commands()
+fld.add_command(site_group_cmd, "site-group")
+
+# Add access control commands
+access_cmd = get_access_commands()
+fld.add_command(access_cmd, "access")

flshbd/cli/access.py

@@ -0,0 +1,153 @@
+# SPDX-FileCopyrightText: 2026-present Robert Kormann <rokor@kormann.info>
+#
+# SPDX-License-Identifier: Unlicense
+"""
+CLI commands for access control management in FlashBoard
+"""
+
+import sys
+
+import click
+
+from flshbd.cli.utils import format_table
+from flshbd.data.database import get_database
+
+
+def get_db():
+    """Get the configured database instance for the current environment."""
+    return get_database()
+
+
+@click.group()
+@click.pass_context
+def access(ctx):
+    """Access control management commands."""
+    pass
+
+
+@access.command()
+@click.argument("group_name")
+@click.argument("site_group_name")
+@click.pass_context
+def grant(ctx, group_name: str, site_group_name: str):
+    """
+    Grant a user group access to a site group.
+    """
+    db_instance = get_db()
+
+    with db_instance.get_connection() as conn:
+        cursor = conn.cursor()
+
+        # Get group IDs (try both group_id and name)
+        user_group = cursor.execute(
+            "SELECT id FROM user_groups WHERE group_id = ? OR name = ?", (group_name, group_name)
+        ).fetchone()
+
+        if not user_group:
+            click.echo(f"User group '{group_name}' not found.")
+            sys.exit(1)
+
+        site_group = cursor.execute(
+            "SELECT id FROM site_groups WHERE group_id = ? OR name = ?", (site_group_name, site_group_name)
+        ).fetchone()
+
+        if not site_group:
+            click.echo(f"Site group '{site_group_name}' not found.")
+            sys.exit(1)
+
+        # Check if access already exists
+        existing = cursor.execute(
+            """SELECT * FROM group_access
+               WHERE group_id = ? AND site_group_id = ?""",
+            (user_group["id"], site_group["id"]),
+        ).fetchone()
+
+        if existing:
+            click.echo(f"Group '{group_name}' already has access to site group '{site_group_name}'.")
+            sys.exit(0)
+
+        # Grant access
+        cursor.execute(
+            """INSERT INTO group_access (group_id, site_group_id)
+               VALUES (?, ?)""",
+            (user_group["id"], site_group["id"]),
+        )
+
+    click.echo(f"Access granted: '{group_name}' can now access '{site_group_name}'.")
+
+
+@access.command()
+@click.argument("group_name")
+@click.argument("site_group_name")
+@click.pass_context
+def revoke(ctx, group_name: str, site_group_name: str):
+    """
+    Revoke a user group's access to a site group.
+    """
+    db_instance = get_db()
+
+    with db_instance.get_connection() as conn:
+        cursor = conn.cursor()
+
+        # Get group IDs (try both group_id and name)
+        user_group = cursor.execute(
+            "SELECT id FROM user_groups WHERE group_id = ? OR name = ?", (group_name, group_name)
+        ).fetchone()
+
+        if not user_group:
+            click.echo(f"User group '{group_name}' not found.")
+            sys.exit(1)
+
+        site_group = cursor.execute(
+            "SELECT id FROM site_groups WHERE group_id = ? OR name = ?", (site_group_name, site_group_name)
+        ).fetchone()
+
+        if not site_group:
+            click.echo(f"Site group '{site_group_name}' not found.")
+            sys.exit(1)
+
+        # Revoke access
+        cursor.execute(
+            """DELETE FROM group_access
+               WHERE group_id = ? AND site_group_id = ?""",
+            (user_group["id"], site_group["id"]),
+        )
+
+    click.echo(f"Access revoked: '{group_name}' can no longer access '{site_group_name}'.")
+
+
+@access.command()
+@click.pass_context
+def list(ctx):
+    """
+    List all access control rules.
+    """
+    db_instance = get_db()
+
+    with db_instance.get_connection() as conn:
+        cursor = conn.cursor()
+
+        query = """
+        SELECT
+            ug.name as user_group_name,
+            sg.name as site_group_name
+        FROM group_access ga
+        JOIN user_groups ug ON ga.group_id = ug.id
+        JOIN site_groups sg ON ga.site_group_id = sg.id
+        ORDER BY ug.name, sg.name
+        """
+
+        cursor.execute(query)
+        rows = [dict(row) for row in cursor.fetchall()]
+
+    if not rows:
+        click.echo("No access control rules found.")
+        return
+
+    headers = ["user_group_name", "site_group_name"]
+    click.echo(format_table(rows, headers))
+
+
+def get_access_commands():
+    """Get the access command group for registration."""
+    return access

flshbd/cli/dash.py

@@ -0,0 +1,192 @@
+# SPDX-FileCopyrightText: 2026-present Robert Kormann <rokor@kormann.info>
+#
+# SPDX-License-Identifier: Unlicense
+"""
+CLI commands for the FlashBoard
+"""
+
+import sys
+
+import click
+
+from flshbd.cli.process import ProcessManager
+
+
+@click.group()
+def dash():
+    """Dashboard management commands"""
+    pass
+
+
+@dash.command()
+@click.option("--port", "-p", default=5000, type=int, help="Port to run the server on")
+@click.option("--host", "-H", default="localhost", help="Host to bind the server to")
+@click.option(
+    "--server",
+    "-s",
+    "server_type",
+    default="flask",
+    type=click.Choice(["flask", "gunicorn"]),
+    help="Server type to use (flask or gunicorn)",
+)
+@click.pass_context
+def start(ctx, port: int, host: str, server_type: str):
+    """
+    Start the FlashBoard server.
+
+    This command starts the dashboard server with the specified configuration.
+    In development mode with Flask, debug is enabled.
+
+    Examples:
+        fld dash start              # Start Flask in development mode
+        fld --env production dash start  # Start Flask in production mode
+        fld --env production dash start --server gunicorn  # Start with Gunicorn
+        fld dash start --port 8080  # Start on port 8080
+    """
+    # Get current config
+    from flshbd.core.config import get_current_config
+
+    config = get_current_config()
+    env = config.ENV
+
+    # ProcessManager will use the current config set by CLI
+    pm = ProcessManager()
+
+    # Check if server is already running
+    if pm.is_running():
+        click.echo("Dashboard server is already running.")
+        status_info = pm.status()
+        if status_info.get("running"):
+            click.echo(f"PID: {status_info['pid']}")
+            click.echo(f"URL: http://{status_info['host']}:{status_info['port']}")
+        return
+
+    click.echo("Starting FlashBoard server...")
+    click.echo(f"Environment: {env}")
+    click.echo(f"URL: http://{host}:{port}")
+
+    try:
+        if server_type == "gunicorn":
+            if env != "production":
+                click.echo("Warning: Gunicorn is recommended for production only", err=True)
+            pid, log_file = pm.start_gunicorn(env, port, host)
+            click.echo("Server type: Gunicorn")
+        else:
+            debug = env == "development"
+            pid, log_file = pm.start_flask(env, port, host, debug)
+            click.echo("Server type: Flask")
+            if debug:
+                click.echo("Debug mode: enabled (debug pin available in log file)")
+
+        click.echo(f"Dashboard started with PID: {pid}")
+        click.echo(f"Log file: {log_file}")
+        click.echo("Server is running in the background.")
+        click.echo("Use 'fld dash stop' to stop the server.")
+        click.echo("Use 'fld dash status' to check server status.")
+
+    except FileNotFoundError as e:
+        if "gunicorn" in str(e):
+            click.echo("Error: Gunicorn is not installed.", err=True)
+            click.echo("Install it with: pip install flshbd[gunicorn]", err=True)
+        else:
+            click.echo(f"Command not found: {e}", err=True)
+        sys.exit(1)
+    except RuntimeError as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+    except Exception as e:
+        click.echo(f"Error starting server: {e}", err=True)
+        sys.exit(1)
+
+
+@dash.command()
+@click.pass_context
+def stop(ctx):
+    """
+    Stop the running FlashBoard server.
+
+    This command stops the server that was started with 'fld dash start'.
+    It sends a SIGTERM signal for graceful shutdown.
+    """
+    # ProcessManager will use the current config set by CLI
+    pm = ProcessManager()
+
+    if not pm.is_running():
+        click.echo("No dashboard server is running.")
+        return
+
+    status_info = pm.status()
+    click.echo(f"Stopping dashboard server (PID: {status_info['pid']})...")
+
+    if pm.stop():
+        click.echo("Dashboard server stopped.")
+    else:
+        click.echo("Failed to stop dashboard server.", err=True)
+
+
+@dash.command()
+@click.pass_context
+def status(ctx):
+    """
+    Show the status of the FlashBoard server.
+
+    This command displays information about the currently running server,
+    including PID, environment, port, and log file location.
+    """
+    # ProcessManager will use the current config set by CLI
+    pm = ProcessManager()
+    status_info = pm.status()
+
+    if status_info.get("running"):
+        click.echo("Dashboard server is RUNNING")
+        click.echo(f"  PID: {status_info['pid']}")
+        click.echo(f"  Environment: {status_info['env']}")
+        click.echo(f"  URL: http://{status_info['host']}:{status_info['port']}")
+        click.echo(f"  Started: {status_info['start_time']}")
+        click.echo(f"  Log file: {status_info['log_file']}")
+        if status_info.get("debug_pin"):
+            click.echo(f"  Debug pin: {status_info['debug_pin']}")
+        if status_info.get("message"):
+            click.echo(f"  Note: {status_info['message']}")
+    else:
+        click.echo("Dashboard server is NOT RUNNING")
+        if "message" in status_info:
+            click.echo(f"  {status_info['message']}")
+        if "pid" in status_info:
+            click.echo(f"  Last PID: {status_info['pid']}")
+        if "env" in status_info:
+            click.echo(f"  Last environment: {status_info['env']}")
+        if "port" in status_info:
+            click.echo(f"  Last port: {status_info['port']}")
+        if "log_file" in status_info:
+            click.echo(f"  Last log file: {status_info['log_file']}")
+
+
+@dash.command()
+def generate_secret_key():
+    """
+    Generate a new secret key for configuration.
+
+    This generates a cryptographically secure secret key that can be used
+    as the FLSHBD_SECRET_KEY environment variable. When FLSHBD_SECRET_KEY is set via
+    environment variable, ephemeral key generation is disabled and all
+    workers will use this persistent key.
+
+    To use the generated key:
+        export FLSHBD_SECRET_KEY=<generated-key>
+
+    Or add it to your environment configuration file.
+    """
+    import secrets
+
+    key = secrets.token_hex(32)
+    click.echo(f"FLSHBD_SECRET_KEY={key}")
+    click.echo("\nTo use this key, set it as an environment variable:")
+    click.echo(f"  export FLSHBD_SECRET_KEY={key}")
+    click.echo("\nNote: Setting FLSHBD_SECRET_KEY disables ephemeral key generation.")
+    click.echo("      All server restarts will use this key until it is changed.")
+
+
+def get_dash_commands():
+    """Get the dash command group for registration"""
+    return dash

flshbd/cli/db.py

@@ -0,0 +1,195 @@
+# SPDX-FileCopyrightText: 2026-present Robert Kormann <rokor@kormann.info>
+#
+# SPDX-License-Identifier: Unlicense
+"""
+CLI commands for database management in FlashBoard
+
+This module provides CLI commands for database initialization, backup, and restore.
+"""
+
+import os
+import sys
+
+import click
+
+from flshbd.core.config import get_current_config
+from flshbd.data.database import Database, get_database
+
+
+def get_db() -> Database:
+    """Get the configured database instance for the current environment."""
+    return get_database()
+
+
+@click.group()
+@click.pass_context
+def db(ctx):
+    """Database management commands."""
+    pass
+
+
+@db.command()
+@click.option("--force", is_flag=True, help="Overwrite existing database if it exists")
+@click.pass_context
+def init(ctx, force: bool):
+    """
+    Initialize the database with schema.
+
+    Creates all required tables for users, groups, sites, and access control.
+    If the database already exists and --force is not specified, the command
+    will fail.
+    """
+
+    config = get_current_config()
+    db_instance = Database(config.DB_PATH)
+
+    if os.path.exists(db_instance.db_path) and not force:
+        click.echo(f"Database already exists at: {db_instance.db_path}")
+        click.echo("Use --force to overwrite the existing database.")
+        sys.exit(1)
+
+    click.echo(f"Initializing database at: {db_instance.db_path}")
+    db_instance.initialize(force=force)
+    click.echo("Database initialized successfully.")
+
+
+@db.command()
+@click.pass_context
+def migrate(ctx):
+    """
+    Seed the database with the static demo data.
+
+    Populates an empty database with the sample data from the static models
+    (users, groups, sites, site groups, access). Does nothing if the database
+    already contains users. This is the explicit seeding command for a new
+    database; the schema itself is created automatically at server start.
+    """
+    from flshbd.data.models import seed_static_data
+
+    db_instance = get_db()
+
+    # Check if database exists and has tables
+    if not db_instance.table_exists("users"):
+        click.echo("Database not initialized. Running 'db init' first...")
+        db_instance.initialize()
+
+    seed_static_data()
+
+    click.echo("Data migration completed successfully.")
+
+
+@db.command()
+@click.option("--path", "-p", default=None, help="Backup file path. Defaults to timestamped file in same directory.")
+@click.pass_context
+def backup(ctx, path: str | None):
+    """
+    Create a backup of the current database.
+
+    Creates a copy of the database file. If no path is specified,
+    creates a timestamped backup in the same directory as the database.
+    """
+    db_instance = get_db()
+
+    if not os.path.exists(db_instance.db_path):
+        click.echo(f"Database file not found: {db_instance.db_path}")
+        sys.exit(1)
+
+    try:
+        backup_path = db_instance.backup(path)
+        click.echo(f"Backup created at: {backup_path}")
+    except Exception as e:
+        click.echo(f"Failed to create backup: {e}")
+        sys.exit(1)
+
+
+@db.command()
+@click.argument("backup_path")
+@click.pass_context
+def restore(ctx, backup_path: str):
+    """
+    Restore database from a backup file.
+
+    Replaces the current database with the specified backup file.
+    """
+    db_instance = get_db()
+
+    backup_path = os.path.expanduser(backup_path)
+    if not os.path.exists(backup_path):
+        click.echo(f"Backup file not found: {backup_path}")
+        sys.exit(1)
+
+    try:
+        click.echo(f"Restoring database from: {backup_path}")
+        db_instance.restore(backup_path)
+        click.echo("Database restored successfully.")
+    except Exception as e:
+        click.echo(f"Failed to restore database: {e}")
+        sys.exit(1)
+
+
+@db.group()
+@click.pass_context
+def config(ctx):
+    """Manage database configuration key/value pairs."""
+    pass
+
+
+@config.command("get")
+@click.argument("key")
+@click.pass_context
+def config_get(ctx, key: str):
+    """
+    Get a configuration value by key.
+
+    Args:
+        key: The configuration key to retrieve
+    """
+    from flshbd.data.models import get_config_value
+
+    value = get_config_value(key)
+    if value is not None:
+        click.echo(f"{key} = {value}")
+    else:
+        click.echo(f"Configuration key '{key}' not found.")
+        sys.exit(1)
+
+
+@config.command("set")
+@click.argument("key")
+@click.argument("value")
+@click.pass_context
+def config_set(ctx, key: str, value: str):
+    """
+    Set a configuration key/value pair.
+
+    Args:
+        key: The configuration key
+        value: The configuration value
+    """
+    from flshbd.data.models import set_config_value
+
+    if set_config_value(key, value):
+        click.echo(f"Configuration set: {key} = {value}")
+    else:
+        click.echo(f"Failed to set configuration: {key} = {value}")
+        sys.exit(1)
+
+
+@config.command("list")
+@click.pass_context
+def config_list(ctx):
+    """List all configuration entries."""
+    from flshbd.data.models import get_all_config_entries
+
+    entries = get_all_config_entries()
+    if entries:
+        click.echo("Configuration entries:")
+        for entry in entries:
+            click.echo(f"  {entry.key} = {entry.value}")
+    else:
+        click.echo("No configuration entries found.")
+
+
+def get_database_commands():
+    """Get the database command group for registration."""
+    return db