First-run setup wizard + solisdash add-user CLI subcommand

Two complementary paths for "I just did `pip install solisdash` and
need a way to log in":

1. **Browser wizard at `/setup`.** Shown once, on the first visit
   to a fresh install. `/login` redirects to `/setup` when the
   `users` collection is empty; `/setup` redirects to `/login` once
   any account exists. Both `GET` and `POST` are gated, so a stray
   `POST /setup` after the first admin exists can never create a
   second account. The created account gets `role=admin`.

2. **`solisdash add-user --username NAME [--role admin|user]`.**
   The CLI is now a subcommand parser:
   - `solisdash` / `solisdash run` — open the dashboard (unchanged).
   - `solisdash add-user` — prompt for password (via getpass, never
     on the command line), seed an account. Reads `SOLIS_MONGODB_URI`
     from env / `.env`. Returns non-zero on bad role / missing
     config / password mismatch / duplicate username.
   Top-level run flags (`--port`, `--no-window`, `--debug`, etc.)
   still work without a subcommand, so the v0.4.0 invocation is
   preserved.

Tests (+14):
- 5 in `tests/test_cli.py` for the new subparser shape (defaults,
  `run` flags, `add-user` username/role parsing, role validation).
- 9 in `tests/test_app_setup.py` covering: wizard renders when no
  users, `/login` redirects to `/setup` when no users, `/login`
  renders normally once a user exists, `/setup` POST creates an
  admin and redirects to `/login`, password mismatch / empty
  password / empty username re-render with errors and don't create
  a user, and the "lock after first user" invariant on both
  `GET /setup` and `POST /setup`.

Browser smoke against the live setup confirmed:
GET / on a fresh install → 303 /login → 303 /setup, wizard form
renders; POST /setup creates the admin and redirects to /login; a
second POST /setup redirects without creating a duplicate; /login
now renders the sign-in form.

Bump to 0.5.0 (new user-facing surface).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jdrumgoole

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "solisdash"
-version = "0.4.0"
+version = "0.5.0"
 description = "Self-hosted dashboard for the SolisCloud (Ginlong Solis) platform"
 readme = "README.md"
 requires-python = ">=3.10"

src/solisdash/__init__.py

@@ -1 +1 @@
-__version__ = "0.4.0"
+__version__ = "0.5.0"

src/solisdash/app.py

@@ -23,6 +23,7 @@
 from solisdash.alarms import ALARM_STATE_LABELS, AlarmService
 from solisdash.auth import (
     authenticate,
+    create_user,
     get_current_user,
     redirect_to,
     require_user,
@@ -334,16 +335,74 @@ async def tiles_fragment(
     )
 
 
+async def _users_exist(db: AsyncDatabase[dict[str, Any]]) -> bool:
+    """True once any user has been created. The setup wizard is locked
+    behind this — once a user exists, `/setup` returns to `/login` forever."""
+    return await db["users"].count_documents({}, limit=1) > 0
+
+
 @app.get("/login", response_class=HTMLResponse, response_model=None)
 async def login_form(
     request: Request,
     user: dict[str, Any] | None = Depends(get_current_user),
+    db: AsyncDatabase[dict[str, Any]] = Depends(get_db),
 ) -> HTMLResponse | RedirectResponse:
     if user is not None:
         return redirect_to("/")
+    if not await _users_exist(db):
+        return redirect_to("/setup")
     return templates.TemplateResponse(request, "login.html", {"error": None})
 
 
+@app.get("/setup", response_class=HTMLResponse, response_model=None)
+async def setup_form(
+    request: Request,
+    db: AsyncDatabase[dict[str, Any]] = Depends(get_db),
+) -> HTMLResponse | RedirectResponse:
+    """First-run admin-creation wizard. Locked once any account exists."""
+    if await _users_exist(db):
+        return redirect_to("/login")
+    return templates.TemplateResponse(
+        request, "setup.html", {"error": None, "username": ""}
+    )
+
+
+@app.post("/setup", response_class=HTMLResponse, response_model=None)
+async def setup_submit(
+    request: Request,
+    username: str = Form(...),
+    password: str = Form(...),
+    confirm: str = Form(...),
+    db: AsyncDatabase[dict[str, Any]] = Depends(get_db),
+) -> HTMLResponse | RedirectResponse:
+    if await _users_exist(db):
+        # Race or replay — someone else already created the first user.
+        return redirect_to("/login")
+    if not username.strip():
+        return templates.TemplateResponse(
+            request,
+            "setup.html",
+            {"error": "Username must not be empty.", "username": username},
+            status_code=400,
+        )
+    if password != confirm:
+        return templates.TemplateResponse(
+            request,
+            "setup.html",
+            {"error": "Passwords do not match.", "username": username},
+            status_code=400,
+        )
+    if not password:
+        return templates.TemplateResponse(
+            request,
+            "setup.html",
+            {"error": "Password must not be empty.", "username": username},
+            status_code=400,
+        )
+    await create_user(db, username=username.strip(), password=password, role="admin")
+    return redirect_to("/login")
+
+
 @app.post("/login", response_class=HTMLResponse, response_model=None)
 async def login_submit(
     request: Request,

src/solisdash/cli.py

@@ -1,21 +1,26 @@
-"""`solisdash` CLI: run the FastAPI app inside a native pywebview window.
+"""`solisdash` CLI: run the dashboard, or manage users.
 
-The CLI is for "desktop app" runs on the developer's machine. For a
-real deployment use `uv run python -m invoke start`; for tests use
-`pytest`. This entry point keeps the same FastAPI app, just hides
-the browser shell behind a Cocoa/GTK/EdgeWebView2 window with a
-native menu and the sun icon.
+Subcommands:
+- (no subcommand) / `run` — open the dashboard inside a pywebview window
+- `add-user`             — seed an account (the only path before login works)
+
+Both end up calling the same `solisdash.app` and `solisdash.auth` code that
+`uv run python -m invoke …` uses; they're just here so anyone who installed
+the package from PyPI doesn't need a dev checkout to bootstrap.
 """
 
 from __future__ import annotations
 
 import argparse
+import asyncio
+import getpass
 import logging
 import socket
 import sys
 import threading
 import time
 import webbrowser
+from collections.abc import Callable
 from importlib.resources import files
 from pathlib import Path
 
@@ -173,48 +178,10 @@ def launch_webview(base_url: str, *, debug: bool = False) -> None:
     webview.start(**start_kwargs)  # type: ignore[arg-type]
 
 
-def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        prog="solisdash",
-        description="Run Solisdash inside a native window (pywebview).",
-    )
-    parser.add_argument(
-        "--host",
-        default="127.0.0.1",
-        help="Address uvicorn binds to. Default: 127.0.0.1 (loopback only).",
-    )
-    parser.add_argument(
-        "--port",
-        type=int,
-        default=0,
-        help="Port to bind. 0 (default) picks a free one.",
-    )
-    parser.add_argument(
-        "--no-window",
-        action="store_true",
-        help="Run uvicorn without opening pywebview (useful for ssh / headless smoke).",
-    )
-    parser.add_argument(
-        "--debug",
-        action="store_true",
-        help="Open pywebview's dev tools and use uvicorn debug logging.",
-    )
-    parser.add_argument(
-        "--version",
-        action="version",
-        version=f"solisdash {__version__}",
-    )
-    parser.add_argument(
-        "--timeout",
-        type=float,
-        default=15.0,
-        help="Seconds to wait for the app to become healthy before giving up.",
-    )
-    return parser.parse_args(argv)
+# --- subcommand: run -------------------------------------------------------
 
 
-def main(argv: list[str] | None = None) -> int:
-    args = parse_args(argv)
+def cmd_run(args: argparse.Namespace) -> int:
     logging.basicConfig(
         level=logging.DEBUG if args.debug else logging.INFO,
         format="%(asctime)s %(levelname)s %(name)s: %(message)s",
@@ -248,5 +215,161 @@ def main(argv: list[str] | None = None) -> int:
     return 0
 
 
+# --- subcommand: add-user --------------------------------------------------
+
+
+def _prompt_password(getpass_fn: Callable[[str], str] = getpass.getpass) -> str | None:
+    """Prompt for a password twice; return the value or `None` on mismatch/empty.
+
+    Indirection on `getpass.getpass` is so tests can inject a stub.
+    """
+    pw1 = getpass_fn("Password: ")
+    pw2 = getpass_fn("Confirm:  ")
+    if pw1 != pw2:
+        print("passwords do not match", file=sys.stderr)
+        return None
+    if not pw1:
+        print("password must not be empty", file=sys.stderr)
+        return None
+    return pw1
+
+
+def cmd_add_user(args: argparse.Namespace) -> int:
+    """Create a user in the configured Mongo. Prompts for the password."""
+    from pymongo import AsyncMongoClient
+    from pymongo.errors import DuplicateKeyError
+
+    from solisdash.auth import ROLES, create_user
+    from solisdash.config import get_settings
+    from solisdash.db import ensure_indexes
+
+    if args.role not in ROLES:
+        print(f"role must be one of {ROLES}, got {args.role!r}", file=sys.stderr)
+        return 2
+
+    settings = get_settings()
+    if not settings.SOLIS_MONGODB_URI:
+        print("SOLIS_MONGODB_URI is not set", file=sys.stderr)
+        return 2
+
+    password = _prompt_password()
+    if password is None:
+        return 2
+
+    async def _go() -> int:
+        client: AsyncMongoClient[dict[str, object]] = AsyncMongoClient(
+            settings.SOLIS_MONGODB_URI
+        )
+        try:
+            db = client[settings.SOLIS_MONGODB_DB]
+            await ensure_indexes(db)
+            try:
+                await create_user(
+                    db, username=args.username, password=password, role=args.role
+                )
+            except DuplicateKeyError:
+                print(f"user {args.username!r} already exists", file=sys.stderr)
+                return 1
+            print(f"created {args.role} {args.username!r}")
+            return 0
+        finally:
+            await client.close()
+
+    return asyncio.run(_go())
+
+
+# --- argparse plumbing -----------------------------------------------------
+
+
+def _add_run_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Address uvicorn binds to. Default: 127.0.0.1 (loopback only).",
+    )
+    p.add_argument(
+        "--port",
+        type=int,
+        default=0,
+        help="Port to bind. 0 (default) picks a free one.",
+    )
+    p.add_argument(
+        "--no-window",
+        action="store_true",
+        help="Run uvicorn without opening pywebview (useful for ssh / headless smoke).",
+    )
+    p.add_argument(
+        "--debug",
+        action="store_true",
+        help="Open pywebview's dev tools and use uvicorn debug logging.",
+    )
+    p.add_argument(
+        "--timeout",
+        type=float,
+        default=15.0,
+        help="Seconds to wait for the app to become healthy before giving up.",
+    )
+
+
+def _make_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="solisdash",
+        description=(
+            "Solisdash CLI. With no subcommand, runs the dashboard in a "
+            "native pywebview window."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"solisdash {__version__}",
+    )
+    # The run-mode flags are also accepted at the top level so
+    # `solisdash --port 9000` keeps working without an explicit subcommand.
+    _add_run_args(parser)
+
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    run_p = subparsers.add_parser(
+        "run",
+        help="Run the dashboard in a pywebview window (default).",
+        description="Run the dashboard. Equivalent to `solisdash` with no subcommand.",
+    )
+    _add_run_args(run_p)
+
+    add_p = subparsers.add_parser(
+        "add-user",
+        help="Create a Solisdash account (prompts for password).",
+        description=(
+            "Create a Solisdash account in the configured MongoDB. Reads "
+            "SOLIS_MONGODB_URI from environment / .env. Prompts for the "
+            "password — it's never accepted on the command line."
+        ),
+    )
+    add_p.add_argument(
+        "--username", required=True, help="Username for the new account."
+    )
+    add_p.add_argument(
+        "--role",
+        default="user",
+        choices=("admin", "user"),
+        help="Account role (default: user).",
+    )
+
+    return parser
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    return _make_parser().parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    if args.command == "add-user":
+        return cmd_add_user(args)
+    # Both `solisdash` and `solisdash run` end up here.
+    return cmd_run(args)
+
+
 if __name__ == "__main__":
     sys.exit(main())

src/solisdash/templates/setup.html

@@ -0,0 +1,51 @@
+{% extends "base.html" %}
+{% block title %}Welcome · Solisdash{% endblock %}
+{% block content %}
+<article class="login-card">
+  <hgroup>
+    <h2>Welcome to Solisdash</h2>
+    <p>
+      No accounts exist yet. Create the first administrator below.
+      This page is shown only on a fresh install — once any account
+      exists, it stops working.
+    </p>
+  </hgroup>
+
+  {% if error %}
+    <p role="alert" class="error">{{ error }}</p>
+  {% endif %}
+
+  <form method="post" action="/setup">
+    <label for="username">Username</label>
+    <input
+      id="username"
+      name="username"
+      type="text"
+      autocomplete="username"
+      value="{{ username|default('') }}"
+      required
+      autofocus
+    />
+
+    <label for="password">Password</label>
+    <input
+      id="password"
+      name="password"
+      type="password"
+      autocomplete="new-password"
+      required
+    />
+
+    <label for="confirm">Confirm password</label>
+    <input
+      id="confirm"
+      name="confirm"
+      type="password"
+      autocomplete="new-password"
+      required
+    />
+
+    <button type="submit">Create administrator</button>
+  </form>
+</article>
+{% endblock %}