fix(web): retire the stale homelab-era copy — neutral, accurate defaults on every page

Fixed: index.html meta description, empty-state sub and composer placeholder (A1); app/config.py default suggestion chips → the four neutral A2 defaults (BOR_SUGGESTIONS override unchanged); sources.html KB page-sub → the current source model (git repos + local dirs + uploaded archives, Sync pulls/imports); git-sources.html example URL → your-repo.git (A3); all 9 footers → neutral default in span.footer-text (the phase-62 hook); E2E/unit conftests force the code defaults so a local .env cannot leak corpus copy into tests; new unit text pins + dedicated E2E suite. Task 02 verification read-through — no change needed: - sources.html sync result/error copy (matches the real sync behavior) - tuning.html page-sub (accurate as written) - history.html page-sub (accurate as written) - doc-edit.html page-sub (accurate as written) - git-sources.html page-sub (accurate as written) - #sources-gate anonymous copy (accurate as written)
2026-09-01 10:54:50 -04:00
parent 4971e2859d
commit baefcde668
16 changed files with 344 additions and 23 deletions
@@ -263,10 +263,10 @@ class Settings(BaseSettings):
    # Suggested questions (onboarding + empty state).
    suggestions: list[str] = [
-        "How is my Kubernetes cluster set up?",
+        "What documents are in the knowledge base?",
-        "What's my backup strategy?",
+        "Which source does each answer come from?",
-        "How do I deploy a new service?",
+        "How do I add a new source?",
-        "What's currently running in the homelab?",
+        "Summarize the most recent document.",
    ]
    @property
@@ -115,7 +115,7 @@
  <footer class="app-footer">
    <div class="container footer-inner">
-      <span>Powered by Reese's self-hosted models</span>
+      <span class="footer-text">Powered by self-hosted models</span>
    </div>
  </footer>
@@ -147,7 +147,7 @@
  <footer class="app-footer">
    <div class="container footer-inner">
-      <span>Powered by Reese's self-hosted models</span>
+      <span class="footer-text">Powered by self-hosted models</span>
    </div>
  </footer>
@@ -172,7 +172,7 @@
            type="text"
            maxlength="500"
            autocomplete="off"
-            placeholder="https://github.com/you/homelab.git"
+            placeholder="https://github.com/you/your-repo.git"
            required
          >
          <button type="submit" id="git-source-add">Add source</button>
@@ -240,7 +240,7 @@
  <footer class="app-footer">
    <div class="container footer-inner">
-      <span>Powered by Reese's self-hosted models</span>
+      <span class="footer-text">Powered by self-hosted models</span>
    </div>
  </footer>
@@ -170,7 +170,7 @@
  <footer class="app-footer">
    <div class="container footer-inner">
-      <span>Powered by Reese's self-hosted models</span>
+      <span class="footer-text">Powered by self-hosted models</span>
      <span class="footer-version" id="app-version"></span>
    </div>
  </footer>
@@ -3,7 +3,7 @@
 <head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
-  <meta name="description" content="Ask Brain of Reese anything about the homelab and deployments.">
+  <meta name="description" content="Ask anything about your indexed documents — every answer cites the exact doc.">
  <title>Brain of Reese</title>
  <link rel="icon" href="data:image/svg+xml,%3Csvg%20xmlns=%22http://www.w3.org/2000/svg%22%20viewBox=%220%200%2064%2064%22%3E%3Cpath%20d=%22M32%204%2055%2018v28L32%2060%209%2046V18Z%22%20fill=%22%231a0f0f%22%20stroke=%22%23f43f5e%22%20stroke-width=%224%22%20stroke-linejoin=%22round%22/%3E%3Ccircle%20cx=%2232%22%20cy=%2232%22%20r=%226.5%22%20fill=%22%23f43f5e%22/%3E%3Cpath%20d=%22M32%2025.5V16M32%2048v-9.5M25.5%2032H16M48%2032h-9.5%22%20stroke=%22%23fca5a5%22%20stroke-width=%223%22%20stroke-linecap=%22round%22/%3E%3C/svg%3E">
  <link rel="stylesheet" href="/assets/styles.css">
@@ -197,7 +197,7 @@
          </div>
          <h1 class="empty-state-title">Hey! I'm Brain of Reese.</h1>
          <p class="empty-state-sub">
-            I've read through the homelab and deployment notes — ask me anything,
+            I've read through your documents — ask me anything,
            and I'll point you at the exact doc. You've got this.
          </p>
          <div class="suggestions" id="suggestions" role="list" aria-label="Suggested questions">
@@ -228,7 +228,7 @@
          id="message-input"
          name="message"
          rows="1"
-          placeholder="Ask me about the homelab…"
+          placeholder="Ask me anything…"
          autocomplete="off"
        ></textarea>
        <button type="submit" class="send-btn" id="send-btn">
@@ -242,7 +242,7 @@
  <footer class="app-footer">
    <div class="container footer-inner">
-      <span>Powered by Reese's self-hosted models</span>
+      <span class="footer-text">Powered by self-hosted models</span>
      <span class="footer-version" id="app-version"></span>
    </div>
  </footer>
@@ -128,7 +128,7 @@
  <footer class="app-footer">
    <div class="container footer-inner">
-      <span>Powered by Reese's self-hosted models</span>
+      <span class="footer-text">Powered by self-hosted models</span>
    </div>
  </footer>
@@ -144,7 +144,7 @@
  <footer class="app-footer">
    <div class="container footer-inner">
-      <span>Powered by Reese's self-hosted models</span>
+      <span class="footer-text">Powered by self-hosted models</span>
      <span class="footer-version" id="app-version"></span>
    </div>
  </footer>
@@ -108,9 +108,9 @@
          </button>
        </div>
        <p class="page-sub">
-          Every <code>*.md</code> file indexed from <code>~/Homelab</code> and
+          Every file indexed from your configured sources — git repositories,
-          <code>~/Deployments</code>. Press <strong>Sync sources</strong> to clone
+          local directories, and uploaded archives. Press <strong>Sync sources</strong>
-          the repos and re-import.
+          to pull the latest and re-import.
        </p>
      </div>
      <!-- #sync-result is the aria-live announcer for the last sync
@@ -183,7 +183,7 @@
  <footer class="app-footer">
    <div class="container footer-inner">
-      <span>Powered by Reese's self-hosted models</span>
+      <span class="footer-text">Powered by self-hosted models</span>
    </div>
  </footer>
@@ -145,7 +145,7 @@
  <footer class="app-footer">
    <div class="container footer-inner">
-      <span>Powered by Reese's self-hosted models</span>
+      <span class="footer-text">Powered by self-hosted models</span>
    </div>
  </footer>
@@ -1,6 +1,7 @@
 """Shared fixtures for unit + integration tests."""
 from __future__ import annotations
 import json
 import os
 from collections.abc import Iterator
@@ -23,6 +24,20 @@ SESSION_SECRET = "test-session-secret-0123456789abcdef0123456789abcdef"
 os.environ.setdefault("BOR_ADMIN_PASSWORD", ADMIN_PASSWORD)
 os.environ.setdefault("BOR_SESSION_SECRET", SESSION_SECRET)
 # Phase 61 (defect fix): the app under test must see the code DEFAULTS,
 # not an operator's local (gitignored) ``.env`` — ``Settings`` loads
 # ``env_file=".env"`` from the repo root, and a machine-specific corpus
 # (e.g. ``BOR_SUGGESTIONS``, ``BOR_DOCS_REPO``) leaked into the tests
 # broke the default-metadata pins. pydantic-settings ranks process env
 # vars ABOVE the ``.env`` file, so force the defaults explicitly here,
 # before ``app.main`` (below) caches settings. The suggestions default
 # is derived from the class field so this can never drift from
 # ``app/config.py``; docs-push stays inert (empty repo).
 from app.config import Settings as _Settings  # noqa: E402
 os.environ["BOR_DOCS_REPO"] = ""
 os.environ["BOR_SUGGESTIONS"] = json.dumps(_Settings.model_fields["suggestions"].default)
 from app.db import SessionLocal, db_available  # noqa: E402
 from app.main import app as fastapi_app  # noqa: E402
@@ -14,6 +14,7 @@ Prerequisite for story tests that touch the database:
 """
 from __future__ import annotations
 import json
 import os
 import subprocess
 import sys
@@ -25,6 +26,8 @@ import httpx
 import pytest
 from playwright.sync_api import Browser, Page, sync_playwright
 from app.config import Settings as _Settings
 REPO = Path(__file__).resolve().parents[2]
 APP_PORT = int(os.environ.get("E2E_APP_PORT", "8123"))
 MOCK_PORT = int(os.environ.get("E2E_MOCK_PORT", "8901"))
@@ -99,6 +102,16 @@ def app_server(mock_llm: int) -> Iterator[str]:
    # Phase 16: admin auth must be set or create_app() refuses to boot.
    env["BOR_ADMIN_PASSWORD"] = ADMIN_PASSWORD
    env["BOR_SESSION_SECRET"] = SESSION_SECRET
    # Phase 61 (defect fix): force the code DEFAULTS so an operator's local
    # (gitignored) ``.env`` — loaded by pydantic-settings from ``cwd=REPO``
    # — cannot leak corpus-specific chips / a docs repo into the app under
    # test: process env ranks above the ``.env`` file. The suggestions
    # default is derived from the class field (never drifts from
    # ``app/config.py``); docs-push stays inert (empty repo).
    env["BOR_DOCS_REPO"] = ""
    env["BOR_SUGGESTIONS"] = json.dumps(
        _Settings.model_fields["suggestions"].default
    )
    proc = subprocess.Popen(
        [sys.executable, "-m", "uvicorn", "app.main:app",
         "--host", "127.0.0.1", "--port", str(APP_PORT), "--log-level", "warning"],
@@ -216,6 +216,11 @@ def _spawn_app(port: int, mock_port: int, docs_env: dict[str, str] | None) -> su
            "BOR_DOCS_WORK_DIR",
        ):
            env.pop(var, None)
        # Phase 61 (defect fix): the pop only clears the process env —
        # pydantic-settings would still pick up ``BOR_DOCS_REPO`` from an
        # operator's local (gitignored) ``.env`` (``cwd=REPO``). Force
        # empty so the "unconfigured" boot really is the inert default.
        env["BOR_DOCS_REPO"] = ""
    else:
        env.update(docs_env)
    return subprocess.Popen(
@@ -0,0 +1,117 @@
 """Phase 61 E2E (Playwright): the retired homelab-era copy is gone — the
 visitor SEES the locked neutral copy on the shared default server.
 Story: n/a (TODO-derived — TODO.md L4 "Clean up the UI, there's text
 that references old features…"). Run in isolation (DB must be up:
 ``podman compose up -d db``):
    uv run pytest tests/e2e/test_stale_ui_copy.py -v --no-cov
 The shared conftest server boots with the default env — and the code
 defaults are exactly this phase's locked copy (A1/A2; the conftest
 forces ``BOR_SUGGESTIONS`` from the ``Settings`` field so an operator's
 local ``.env`` cannot leak corpus-specific chips). Every assertion is a
 settled-state check: static HTML + one ``GET /api/suggestions`` fetch;
 Playwright's ``expect`` retries ride out the chip rendering.
 Test → lock mapping (Playwright Mapping Rule):
 1. ``test_chat_page_placeholder_meta_footer_are_the_locked_copy``
 2. ``test_chat_page_shows_no_homelab_or_deployment_text``
 3. ``test_chat_page_suggestion_chips_are_the_locked_list``
 4. ``test_sources_page_sub_describes_the_current_source_model``
 5. ``test_git_sources_example_url_is_neutral``
 """
 from __future__ import annotations
 from playwright.sync_api import Page, expect
 # The locked replacement copy (owner-locked A1 / A2 / A3 — same literals
 # as tests/unit/test_stale_ui_copy.py; the unit pins guard the files,
 # this suite guards what the visitor actually sees).
 META = "Ask anything about your indexed documents — every answer cites the exact doc."
 PLACEHOLDER = "Ask me anything…"
 FOOTER = "Powered by self-hosted models"
 GIT_EXAMPLE = "https://github.com/you/your-repo.git"
 CHIPS = [
    "What documents are in the knowledge base?",
    "Which source does each answer come from?",
    "How do I add a new source?",
    "Summarize the most recent document.",
 ]
 def test_chat_page_placeholder_meta_footer_are_the_locked_copy(
    page: Page, app_url: str, db_ready: None
 ) -> None:
    """The composer placeholder, the <meta description> content and the
    footer span all read the locked (A1) copy — read from the DOM a
    visitor gets."""
    page.goto(f"{app_url}/")
    expect(page.locator("#message-input")).to_have_attribute(
        "placeholder", PLACEHOLDER
    )
    meta = page.eval_on_selector('meta[name="description"]', "el => el.content")
    assert meta == META, "the rendered meta description must be the locked copy"
    expect(page.locator(".footer-text").first).to_have_text(FOOTER)
 def test_chat_page_shows_no_homelab_or_deployment_text(
    page: Page, app_url: str, db_ready: None
 ) -> None:
    """The entire rendered chat page (nav, empty state, composer, footer)
    shows no homelab-era text — the empty-state sub AND the four
    rendered suggestion chips are covered by this body scan (case-
    insensitive; a fresh page context has no saved chats, so the empty
    state is what renders)."""
    page.goto(f"{app_url}/")
    expect(page.locator("#suggestions .suggestion-chip")).to_have_count(len(CHIPS))
    body = page.evaluate("() => document.body.innerText.toLowerCase()")
    assert "homelab" not in body, f"homelab-era text rendered on the chat page: {body!r}"
    assert "deployment" not in body, (
        f"homelab-era text rendered on the chat page: {body!r}"
    )
 def test_chat_page_suggestion_chips_are_the_locked_list(
    page: Page, app_url: str, db_ready: None
 ) -> None:
    """The four rendered empty-state chips (from ``GET
    /api/suggestions``, the code default) are the locked (A2) list, in
    order."""
    page.goto(f"{app_url}/")
    chips = page.locator("#suggestions .suggestion-chip")
    expect(chips).to_have_count(len(CHIPS))
    for i, chip in enumerate(CHIPS):
        expect(chips.nth(i)).to_have_text(chip)
 def test_sources_page_sub_describes_the_current_source_model(
    page: Page, app_url: str, db_ready: None
 ) -> None:
    """The KB page-sub (the string the TODO cited by name) no longer
    names ~/Homelab or ~/Deployments and describes the current source
    model. The page is anonymously viewable — the catalog gate hides
    the table, not the page-head."""
    page.goto(f"{app_url}/sources.html")
    sub = page.locator(".page-sub").first
    expect(sub).to_be_visible()
    text = sub.inner_text().lower()
    assert "homelab" not in text, f"retired copy in the page-sub: {text!r}"
    assert "deployments" not in text, f"retired copy in the page-sub: {text!r}"
    assert "configured sources" in text, (
        f"the page-sub must name the current source model: {text!r}"
    )
 def test_git_sources_example_url_is_neutral(
    page: Page, app_url: str, db_ready: None
 ) -> None:
    """The repo-URL form example (A3) is the neutral your-repo.git —
    read from the DOM; the element exists even while
    ``#git-sources-content`` is hidden for an anonymous visitor (no
    sign-in needed)."""
    page.goto(f"{app_url}/git-sources.html")
    expect(page.locator("#git-source-url")).to_have_attribute(
        "placeholder", GIT_EXAMPLE
    )
@@ -0,0 +1,166 @@
 """Unit: phase-61 text pins — the retired homelab-era copy is GONE, the
 locked neutral replacements are PRESENT (house pattern: read the files
 as text, assert substrings — no browser, cf. test_frontend_brand.py).
 The browser-visible layer is gated by the story suite
 (``tests/e2e/test_stale_ui_copy.py``); these pins catch a silent
 regression in the templates / the ``Settings`` defaults without it.
 """
 from __future__ import annotations
 import re
 from pathlib import Path
 FRONTEND = Path(__file__).resolve().parents[2] / "frontend"
 ROOT = FRONTEND.parent
 CONFIG_PY = ROOT / "app" / "config.py"
 #: Every page in the app ships a footer (the phase-39 ``HTML_PAGES``
 #: tuple, repeated here so this file stands alone).
 HTML_PAGES = (
    "index.html",
    "sources.html",
    "tuning.html",
    "document.html",
    "login.html",
    "git-sources.html",
    "history.html",
    "shared.html",
    "doc-edit.html",
 )
 # --- the locked replacement copy (owner-locked A1 / A2) ----------------
 META = "Ask anything about your indexed documents — every answer cites the exact doc."
 EMPTY_SUB = (
    "I've read through your documents — ask me anything, and I'll point "
    "you at the exact doc. You've got this."
 )
 PLACEHOLDER = "Ask me anything…"
 PAGE_SUB = (
    "Every file indexed from your configured sources — git repositories, "
    "local directories, and uploaded archives. Press <strong>Sync "
    "sources</strong> to pull the latest and re-import."
 )
 FOOTER = "Powered by self-hosted models"
 CHIPS = [
    "What documents are in the knowledge base?",
    "Which source does each answer come from?",
    "How do I add a new source?",
    "Summarize the most recent document.",
 ]
 # --- the retired homelab-era copy (must be nowhere) --------------------
 OLD_META_FRAG = "the homelab and deployments"
 OLD_SUB_FRAG = "the homelab and deployment notes"
 OLD_PLACEHOLDER_FRAG = "Ask me about the homelab"
 OLD_FOOTER = "Reese's self-hosted models"
 OLD_GIT_EXAMPLE = "github.com/you/homelab"
 OLD_CHIPS = [
    "How is my Kubernetes cluster set up?",
    "What's my backup strategy?",
    "How do I deploy a new service?",
    "What's currently running in the homelab?",
 ]
 def _text(path: Path) -> str:
    return path.read_text(encoding="utf-8")
 def _norm(text: str) -> str:
    """Collapse whitespace runs — the templates wrap long lines, so the
    locked copy is pinned against the normalized text."""
    return re.sub(r"\s+", " ", text).strip()
 def test_chat_page_old_copy_is_gone() -> None:
    """index.html: the old meta fragment, the old empty-state sub
    fragment, the old composer placeholder and the old footer are all
    retired. (The L176 code comment still says 'homelab' — A3: comments
    are not user-visible and stay untouched, so only the exact old
    user-visible strings are pinned.)"""
    html = _text(FRONTEND / "index.html")
    for frag in (OLD_META_FRAG, OLD_SUB_FRAG, OLD_PLACEHOLDER_FRAG, OLD_FOOTER):
        assert frag not in html, f"retired chat copy still present: {frag!r}"
 def test_sources_page_old_copy_is_gone() -> None:
    """sources.html: the ~/Homelab + ~/Deployments page-sub citations and
    the old footer are retired."""
    html = _text(FRONTEND / "sources.html")
    for frag in ("~/Homelab", "~/Deployments", OLD_FOOTER):
        assert frag not in html, f"retired sources copy still present: {frag!r}"
 def test_git_sources_page_old_copy_is_gone() -> None:
    """git-sources.html: the old example repo URL (A3) and the old
    footer are retired."""
    html = _text(FRONTEND / "git-sources.html")
    for frag in (OLD_GIT_EXAMPLE, OLD_FOOTER):
        assert frag not in html, f"retired git-sources copy still present: {frag!r}"
 def test_chat_page_locked_copy_present_exactly_once() -> None:
    """The three locked (A1) chat strings, each exactly once in
    index.html (a second copy could drift out of sync)."""
    html = _norm(_text(FRONTEND / "index.html"))
    assert html.count(META) == 1, "the locked meta description"
    assert html.count(EMPTY_SUB) == 1, "the locked empty-state sub"
    assert html.count(PLACEHOLDER) == 1, "the locked composer placeholder"
 def test_sources_page_sub_is_the_locked_copy() -> None:
    """The KB .page-sub (the string the TODO cited by name) reads the
    locked (A1) copy, including the <strong> around Sync sources —
    pinned inside the .page-sub element, not anywhere in the file."""
    html = _text(FRONTEND / "sources.html")
    m = re.search(r'<p class="page-sub">(.*?)</p>', html, re.DOTALL)
    assert m, "sources.html must keep the .page-sub"
    assert _norm(m.group(1)) == PAGE_SUB
 def test_all_nine_footers_are_the_locked_neutral_default() -> None:
    """Every page carries the locked (A1) footer inside exactly one
    ``class="footer-text"`` span (the stable hook phase 62's
    BOR_FOOTER_TEXT env var drives)."""
    span = f'<span class="footer-text">{FOOTER}</span>'
    for page in HTML_PAGES:
        html = _text(FRONTEND / page)
        assert html.count('class="footer-text"') == 1, (
            f"{page}: exactly one .footer-text span"
        )
        assert html.count(span) == 1, f"{page}: the locked neutral footer"
 def test_config_default_chips_are_the_locked_list_in_order() -> None:
    """The ``Settings.suggestions`` default (app/config.py) is exactly
    the four locked (A2) chips, in order (the E2E conftest derives the
    app-under-test env from this field — it can never drift)."""
    config = _text(CONFIG_PY)
    m = re.search(r"suggestions: list\[str\] = \[(.*?)\]", config, re.DOTALL)
    assert m, "the suggestions default list must exist in app/config.py"
    block = m.group(1)
    positions = []
    for chip in CHIPS:
        assert f'"{chip}"' in block, f"locked chip missing from the default: {chip!r}"
        positions.append(block.index(f'"{chip}"'))
    assert positions == sorted(positions), "the chips must keep the locked order"
 def test_old_chips_are_retired_not_relocated() -> None:
    """The four old default chips are retired, not relocated: they must
    appear NOWHERE in the app source (app/ + frontend/) — config.py
    included (the scan covers it)."""
    for base in (ROOT / "app", FRONTEND):
        for path in sorted(base.rglob("*")):
            if not path.is_file() or "__pycache__" in path.parts:
                continue
            text = path.read_text(encoding="utf-8")
            for chip in OLD_CHIPS:
                assert chip not in text, (
                    f"retired chip {chip!r} relocated to {path.relative_to(ROOT)}"
                )
@@ -102,13 +102,18 @@ def test_sync_error_banner_is_a_hidden_alert() -> None:
 def test_page_sub_copy_mentions_the_button() -> None:
-    """The page-sub copy names the button as the one-click way to clone
+    """The page-sub copy names the button as the one-click way to pull
-    the repos and re-import (the import CLI docs live elsewhere)."""
+    the latest and re-import (the import CLI docs live elsewhere).
    Phase 61: the copy describes the current source model (git repos +
    local directories + uploaded archives), not the old ~/Homelab +
    ~/Deployments clone."""
    sub = re.search(r'<p class="page-sub">(.*?)</p>', _text(SOURCES_HTML), re.DOTALL)
    assert sub, "sources.html must keep the .page-sub copy"
    copy = re.sub(r"\s+", " ", sub.group(1))  # the markup wraps lines
    assert "Press <strong>Sync sources</strong>" in copy
-    assert "clone the repos and re-import" in copy
+    assert "pull the latest and re-import" in copy
    assert "git repositories," in copy
    assert "local directories, and uploaded archives" in copy
 def test_sources_page_stays_cdn_free() -> None: