Fix 500 on setup wizard when username already exists in target DB

If an admin pointed the wizard at a MongoDB that already contained a
user with the chosen username (e.g. recovering after losing the local
solisdash.toml), `create_user` raised `DuplicateKeyError` from the
`username_unique` index and FastAPI returned a 500.

The wizard now probes the target users collection for the requested
username before writing the toml and renders a friendly inline error
pointing the admin at /login. A try/except around `create_user` covers
the index race for completeness.

Also adds an initial CHANGELOG.md covering 0.1.x through 0.7.1.

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

Author: jdrumgoole

CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to **Solisdash** are documented here. Version numbers
+follow [Semantic Versioning](https://semver.org/). The package is published
+to PyPI on every `vX.Y.Z` tag push.
+
+## 0.7.1 — 2026-05-16
+
+### Fixed
+- Submitting the setup wizard against a MongoDB that already contained a
+  user with the chosen username raised `DuplicateKeyError` and returned a
+  500. The wizard now probes for a username collision before persisting
+  anything and renders a friendly inline error pointing the user at
+  `/login`. A `DuplicateKeyError` fallback covers the index race.
+
+## 0.7.0 — 2026-05-16
+
+### Changed
+- All configuration now lives inside the webview. The CLI no longer prompts
+  for anything — `solisdash` boots straight into the pywebview window and
+  silently generates `SESSION_SECRET` on first run.
+
+### Added
+- First-run **setup wizard** at `/setup`: a single-page form with three
+  sections (MongoDB, SolisCloud, Administrator account). Each section has
+  an HTMX **Test** button that probes the value inline before save. After
+  save the user is auto-signed-in and dropped on the dashboard.
+- **Settings page** at `/settings` (linked from the nav as ⚙ Settings):
+  re-edit the same values, re-test, or reset the configuration. Reset
+  wipes `solisdash.toml` and re-runs the wizard; MongoDB data
+  (users, samples, alarms, daily totals) is left alone.
+- **`~/.config/solisdash/solisdash.toml`** as the persisted config store,
+  XDG-aware and chmodded to `0600`. Loaded via pydantic-settings'
+  `TomlConfigSettingsSource`. Environment variables still take precedence
+  over the file, and a project-local `.env` is still read for dev.
+
+### Removed
+- The interactive CLI setup helpers (`solisdash setup`, prompts on first
+  boot). The `add-user` subcommand stays for post-install user management.
+
+## 0.6.2 — 2026-05-15
+
+### Changed
+- Dropped `invoke` as a runtime dependency — it was unused in `src/` and
+  shipped only because the build tasks lived in the package. Now in the
+  `dev` extra.
+
+## 0.6.1 — 2026-05-15
+
+### Fixed
+- Signing in on a freshly-installed instance with empty SolisCloud
+  credentials raised `RuntimeError` from `get_solis_client`, producing a
+  500. The client now constructs even with empty creds; live-tile
+  requests fall back to a friendly "SolisCloud rejected the call" alert
+  that nudges the admin to finish configuration.
+
+## 0.6.0 — 2026-05-15
+
+### Added
+- First-run onboarding: when no `.env` is present and stdin is a TTY,
+  the CLI prompts the admin to enter Mongo + SolisCloud creds and writes
+  them to a user-level config file. Superseded by the in-browser wizard
+  in 0.7.0.
+
+## 0.5.0 — 2026-05-15
+
+### Added
+- First-run setup wizard at `/setup` (server-side, no Mongo creds yet)
+  so a fresh install can create its admin account from the browser
+  instead of the CLI.
+- `solisdash add-user` CLI subcommand for creating additional accounts
+  post-install.
+
+## 0.4.0 — 2026-05-15
+
+### Changed
+- Lowered the minimum Python version from 3.12 to **3.10** so the
+  package installs on the broader range of LTS Pythons. `tomli` is
+  pulled in as a fallback for `tomllib` on 3.10.
+
+## 0.3.2 — 2026-05-15
+
+### Removed
+- The obsolete `pymongo[srv]` extra. Recent `pymongo` releases bundle
+  SRV resolution by default; the extra was a no-op causing a pip
+  warning.
+
+## 0.3.1 — 2026-05-15
+
+### Added
+- GitHub Actions release workflow (`.github/workflows/release.yml`):
+  pushing a `vX.Y.Z` tag builds with `uv build` and publishes the sdist
+  + wheel to PyPI via OIDC trusted publishing. No API tokens, no local
+  `uv publish`.
+
+## 0.2.x — 2026-05-13 → 2026-05-14
+
+Pre-release scaffolding. Highlights from the run-up to the first
+PyPI-published version:
+
+- `solisdash` CLI launcher with native pywebview window + menu.
+- AGPL-3.0-or-later license.
+- GitHub Actions CI (ruff, mypy, pytest with a `mongo:7` service).
+- Public README and CI badge.
+
+## 0.1.x — 2026-05-13
+
+Initial development. Highlights:
+
+- FastAPI app scaffold, session-cookie auth, Jinja shell.
+- SolisCloud client with HMAC-SHA1 signing (bare `application/json`
+  Content-Type, no separate `KeyId` header, `alarmList` unwrapping
+  fixed).
+- MongoDB layer with per-worker test fixture.
+- Live-tile dashboard with HTMX polling and station-samples fallback.
+- Poller + APScheduler + token-bucket rate limiter, with `poll-once`
+  and `backfill` invoke tasks.
+- History charts: day, month, year, all-time (Mongo-only, no SolisCloud
+  calls).
+- Alarm feed, CSV export, dark-mode toggle, `/ready` probe.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "solisdash"
-version = "0.7.0"
+version = "0.7.1"
 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.7.0"
+__version__ = "0.7.1"

src/solisdash/app.py

@@ -17,6 +17,7 @@
 from fastapi.templating import Jinja2Templates
 from pymongo import AsyncMongoClient
 from pymongo.asynchronous.database import AsyncDatabase
+from pymongo.errors import DuplicateKeyError
 from starlette.middleware.sessions import SessionMiddleware
 
 from solisdash import __version__
@@ -520,24 +521,42 @@ def _err(msg: str, **extras: str) -> HTMLResponse:
     if not password:
         return _err("Password must not be empty.")
 
-    # Verify the supplied URI works before we persist anything.
+    target_uri = mongo_uri.strip()
+    target_db = mongo_db.strip() or "solis"
+    target_username = username.strip()
+
+    # Verify the supplied URI works AND check for a username collision
+    # *before* we persist anything. Without this guard, pointing the wizard
+    # at an already-populated database (e.g. recovering after losing the
+    # local toml) raises DuplicateKeyError as a 500 once we hit the index.
     try:
         probe: AsyncMongoClient[dict[str, Any]] = AsyncMongoClient(
-            mongo_uri, serverSelectionTimeoutMS=4000
+            target_uri, serverSelectionTimeoutMS=4000
         )
         try:
-            await probe[mongo_db].command("ping")
+            probe_db = probe[target_db]
+            await probe_db.command("ping")
+            collision = await probe_db["users"].find_one(
+                {"username": target_username}, projection={"_id": 1}
+            )
         finally:
             await probe.close()
     except Exception as exc:
         return _err(f"MongoDB connection failed: {type(exc).__name__}: {exc}")
 
+    if collision is not None:
+        return _err(
+            f"A user named “{target_username}” already exists in this database. "
+            "Pick a different username, or sign in to the existing account "
+            "from the /login page after saving."
+        )
+
     # Persist everything that's non-empty.
     settings = get_settings()
     write_toml(
         {
-            "SOLIS_MONGODB_URI": mongo_uri.strip(),
-            "SOLIS_MONGODB_DB": mongo_db.strip() or "solis",
+            "SOLIS_MONGODB_URI": target_uri,
+            "SOLIS_MONGODB_DB": target_db,
             "SOLIS_API_URL": solis_api_url.strip() or settings.SOLIS_API_URL,
             "SOLIS_KEY_ID": solis_key_id.strip(),
             "SOLIS_KEYSECRET": solis_keysecret,
@@ -550,12 +569,19 @@ def _err(msg: str, **extras: str) -> HTMLResponse:
     # Create the first admin in the freshly-configured Mongo.
     db = await get_db(request)
     await ensure_indexes(db)
-    await create_user(
-        db, username=username.strip(), password=password, role="admin"
-    )
+    try:
+        await create_user(db, username=target_username, password=password, role="admin")
+    except DuplicateKeyError:
+        # Pre-check above usually catches this; the index also enforces it,
+        # so handle the race anyway rather than 500ing.
+        return _err(
+            f"A user named “{target_username}” already exists in this database. "
+            "Pick a different username, or sign in to the existing account "
+            "from the /login page."
+        )
 
     # Auto-sign-in — saves the user re-typing the password they just chose.
-    session_login(request, {"username": username.strip(), "role": "admin"})
+    session_login(request, {"username": target_username, "role": "admin"})
     return redirect_to("/")
 
 

tests/test_app_setup.py

@@ -254,6 +254,50 @@ async def _not_done() -> bool:
     assert "MongoDB connection failed" in r.text
 
 
+async def test_setup_post_rejects_existing_username_in_target_db(
+    auth_client: httpx.AsyncClient,
+    clean_db: AsyncDatabase[dict[str, Any]],
+    mongo_uri: str,
+    test_db_name: str,
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Any,
+) -> None:
+    """Pointing the wizard at a DB that already has the chosen username
+    must render a friendly error, not blow up with DuplicateKeyError."""
+
+    async def _not_done() -> bool:
+        return False
+
+    monkeypatch.setattr(app_module, "_setup_done", _not_done)
+    # Keep any toml writes off the user's real home directory.
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path))
+
+    # Seed the target DB with a user the form will collide with.
+    await create_user(clean_db, username="jdrumgoole", password="x", role="admin")
+
+    r = await auth_client.post(
+        "/setup",
+        data={
+            "mongo_uri": mongo_uri,
+            "mongo_db": test_db_name,
+            "solis_api_url": "https://api/",
+            "solis_key_id": "",
+            "solis_keysecret": "",
+            "username": "jdrumgoole",
+            "password": "hunter2",
+            "confirm": "hunter2",
+        },
+        follow_redirects=False,
+    )
+    assert r.status_code == 400
+    assert "already exists" in r.text
+    assert "jdrumgoole" in r.text
+    # Pre-check fires before write_toml, so the toml was not written.
+    assert not (tmp_path / "solisdash" / "solisdash.toml").exists()
+    # And the seeded user remains untouched.
+    assert await clean_db["users"].count_documents({"username": "jdrumgoole"}) == 1
+
+
 # --- /settings page -------------------------------------------------------