diff options
| author | Dennis Fink | 2026-11-12 19:57:08 +0100 |
|---|---|---|
| committer | Dennis Fink | 2026-11-12 19:57:08 +0100 |
| commit | 4bd1d9e348918b2e55db47a1ac3489d035cf55e2 (patch) | |
| tree | f7ed41a374a8a4136792039a262dc62aa8cf8c59 /webmentions_ssg/cli.py | |
| parent | 7035e9f9467684cccae2b7ff3faaa62e6a9f91aa (diff) | |
| download | webmentions-ssg-4bd1d9e348918b2e55db47a1ac3489d035cf55e2.tar.gz webmentions-ssg-4bd1d9e348918b2e55db47a1ac3489d035cf55e2.zip | |
refactor(core): split modules by responsibility
Break up monolithic views, task helpers, networking, CLI, and
application extension setup so each module owns a focused concern.
Reorganize the test suite around the new boundaries while preserving
existing Webmention behavior and coverage.
Diffstat (limited to 'webmentions_ssg/cli.py')
| -rw-r--r-- | webmentions_ssg/cli.py | 199 |
1 files changed, 199 insertions, 0 deletions
diff --git a/webmentions_ssg/cli.py b/webmentions_ssg/cli.py new file mode 100644 index 0000000..0387ba6 --- /dev/null +++ b/webmentions_ssg/cli.py @@ -0,0 +1,199 @@ +# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me> +# +# SPDX-License-Identifier: BSD-3-Clause + +"""Manage users, mail settings, and database migrations.""" + +import click +import sqlalchemy as sa +from flask import current_app +from flask.cli import AppGroup +from flask_mail import Message +from flask_migrate import upgrade as migrate_upgrade +from sqlalchemy import inspect +from sqlalchemy.exc import IntegrityError + +from .auth import validate_password +from .extensions import DATABASE, MAIL +from .models import User + +USERS_CLI = AppGroup("users", help="Manage users.") + + +def _require_user(username: str): + """Return a user by username or report a CLI-friendly error.""" + + user = DATABASE.session.scalar(sa.select(User).where(User.username == username)) + if user is None: + raise click.ClickException(f"User {username!r} does not exist.") + return user + + +@USERS_CLI.command("create", help="Create a user.") +@click.option("--username", prompt="Username", help="Username for the new user.") +@click.password_option(confirmation_prompt=True) +def create_user(username: str, password: str) -> None: + """ + Create a user with a securely hashed password. + + :param username: Username for the new user. + :param password: Plain-text password to hash and store. + :raises click.ClickException: If the credentials are invalid or the user exists. + """ + + username = username.strip() + if not username: + raise click.ClickException("Username must not be empty.") + + try: + validate_password(password) + except ValueError as exc: + raise click.ClickException(str(exc)) from exc + + if DATABASE.session.scalar(sa.select(User).where(User.username == username)): + raise click.ClickException(f"User {username!r} already exists.") + + DATABASE.session.add(User(username=username, password=password)) + try: + DATABASE.session.commit() + except IntegrityError as exc: + DATABASE.session.rollback() + raise click.ClickException(f"User {username!r} already exists.") from exc + + click.echo(f"Created user {username!r}.") + + +@USERS_CLI.command("list", help="List registered users.") +def list_users() -> None: + """List user IDs and usernames in alphabetical order.""" + + users = DATABASE.session.scalars(sa.select(User).order_by(User.username)).all() + if not users: + click.echo("No users found.") + return + + click.echo("ID\tUSERNAME") + for user in users: + click.echo(f"{user.id}\t{user.username}") + + +@USERS_CLI.command("set-password", help="Reset a user's password.") +@click.argument("username") +@click.password_option(confirmation_prompt=True) +def set_user_password(username: str, password: str) -> None: + """ + Change a user's password without displaying it. + + :param username: Username of the account to update. + :param password: New plain-text password to hash and store. + :raises click.ClickException: If the account is missing or the password is invalid. + """ + try: + validate_password(password) + except ValueError as exc: + raise click.ClickException(str(exc)) from exc + + user = _require_user(username) + user.password = password + DATABASE.session.commit() + click.echo(f"Updated password for user {username!r}.") + + +@USERS_CLI.command("delete", help="Delete a user.") +@click.argument("username") +@click.option("-y", "--yes", is_flag=True, help="Skip the deletion confirmation.") +def delete_user(username: str, yes: bool) -> None: + """ + Permanently delete a user after confirmation, unless --yes is passed. + + :param username: Username of the account to remove. + :param yes: Whether to skip the confirmation prompt. + :raises click.ClickException: If the account does not exist. + """ + user = _require_user(username) + if not yes: + click.confirm(f"Delete user {username!r}?", abort=True) + + DATABASE.session.delete(user) + DATABASE.session.commit() + click.echo(f"Deleted user {username!r}.") + + +MAIL_CLI = AppGroup("mail", help="Handle mail") + + +@MAIL_CLI.command("test", help="Send an email to test the SMTP configuration") +@click.option( + "--to", "recipient", help="Recipient address (defaults to NOTIFICATION_EMAIL)." +) +def send_test_mail(recipient: str | None) -> None: + """ + Send a test email using the configured SMTP server. + + :param recipient: Optional recipient overriding NOTIFICATION_EMAIL. + :raises click.ClickException: If configuration is missing or sending fails. + """ + recipient = recipient or current_app.config.get("NOTIFICATION_EMAIL") + if not recipient: + raise click.ClickException( + "No recipient specified. Set NOTIFICATION_EMAIL or pass --to." + ) + + sender = current_app.config.get("MAIL_DEFAULT_SENDER") + if not sender: + raise click.ClickException("MAIL_DEFAULT_SENDER is not configured.") + + message = Message( + subject="webmentions-ssg: test email", + sender=sender, + recipients=[recipient], + body=( + "This is a test email from webmentions-ssg.\n\n" + "If you received this message, the outgoing mail configuration works.\n" + ), + ) + + try: + MAIL.send(message) + except Exception as exc: + raise click.ClickException(f"Could not send test email: {exc}") from exc + + click.echo(f"Test email sent to {recipient}.") + + +DB_CLI = AppGroup("db", help="Handle database") + + +def _table_names() -> set[str]: + """Return existing table names without modifying the database schema.""" + with DATABASE.engine.connect() as connection: + return set(inspect(connection).get_table_names()) + + +@DB_CLI.command("create-db", help="Create a new database using all migrations") +def create_db() -> None: + """Initialize an empty database and record its Alembic revision.""" + if _table_names(): + raise click.ClickException( + "The database already contains tables. " + "Use 'flask db upgrade' for an existing migrated database." + ) + + # Applying migrations (rather than create_all()) keeps alembic_version in sync. + migrate_upgrade() + click.echo("Database created at the latest migration revision.") + + +@DB_CLI.command("upgrade", help="Upgrade an existing database to the latest revision") +def upgrade_db() -> None: + """Apply pending migrations to a previously initialized database.""" + if "alembic_version" not in _table_names(): + raise click.ClickException( + "No Flask-Migrate revision table found. " + "For a new, empty database run 'flask db create-db'. " + "For a legacy database, inspect its schema and use " + "'flask migrate stamp' only if appropriate." + ) + + migrate_upgrade() + click.echo("Database upgraded to the latest migration revision.") |
