brain-of-reese/tests/unit/test_sync_button.py

"""Unit: the admin "Sync sources" button contract (phase 32, task 02).

The browser behavior is E2E-covered (tests/e2e/test_sync_button.py,
task 03); here we pin the source-level wiring — the anonymous-safe
ship-hidden button markup, the header.js admin reveal on the SAME
cached whoami (no extra fetch), the header.js sync state machine
(moved here from sources.js in phase 34 task 02: 2 s poll, 202 start
/ 409 adoption / 403 hide, terminal labels, the "bor:sync-status"
event with the status object as detail, the single-poll-loop guard, no
client-side hard timeout), the Sources page's event-driven
#sync-result line + #sync-error-banner, and the §7.4 never-stale CSS
(spin + reduced-motion opt-out,
disabled state, 44px floor, contrast pair) — so a silent regression is
caught without a browser.
"""
from __future__ import annotations

import re
from pathlib import Path

FRONTEND = Path(__file__).resolve().parents[2] / "frontend"
ASSETS = FRONTEND / "assets"

HEADER_JS = ASSETS / "header.js"
SOURCES_JS = ASSETS / "sources.js"
STYLES_CSS = ASSETS / "styles.css"
SOURCES_HTML = FRONTEND / "sources.html"


def _text(path: Path) -> str:
    assert path.is_file(), f"missing frontend file: {path}"
    return path.read_text(encoding="utf-8")


def _body(js: str, fn_name: str) -> str:
    """The source of the first top-level `function <fn_name>` in js."""
    fn = js.find(f"function {fn_name}")
    assert fn != -1, f"{fn_name} must be defined"
    return js[fn : js.find("\n}", fn)]


# ---------- sources.html: anonymous-safe ship-hidden markup ----------


def test_sync_button_ships_hidden_and_labeled() -> None:
    """#sync-btn SHIPS with the hidden attribute (anonymous-safe —
    header.js reveals it for the admin), is a real <button type=
    "button">, and carries aria-label="Sync sources" so the accessible
    name stays stable across the label states."""
    tag = re.search(r"<button[^>]*id=\"sync-btn\"[^>]*>", _text(SOURCES_HTML))
    assert tag, "sources.html must carry the #sync-btn button"
    attrs = tag.group(0)
    assert 'class="sync-btn"' in attrs
    assert 'type="button"' in attrs
    assert re.search(r"\bhidden\b", attrs), "#sync-btn must ship hidden"
    assert 'aria-label="Sync sources"' in attrs


def test_sync_button_has_icon_and_label_span() -> None:
    """The button body is a refresh-cycle svg (aria-hidden — decorative,
    the spin is the visible running state) + the #sync-label span with
    the idle text, so the label can be swapped by sources.js."""
    text = _text(SOURCES_HTML)
    btn = text[text.find('id="sync-btn"') : text.find("</button>", text.find('id="sync-btn"'))]
    assert re.search(r'<svg[^>]*class="sync-icon"[^>]*aria-hidden="true"', btn)
    assert 'id="sync-label"' in btn
    assert re.search(r'<span[^>]*id="sync-label"[^>]*>Sync sources</span>', btn)


def test_sync_result_is_the_aria_live_announcer() -> None:
    """#sync-result sits right after the button and is a polite live
    region (role="status" + aria-live="polite") — the last-result /
    counts announcement for screen readers."""
    text = _text(SOURCES_HTML)
    tag = re.search(r'<span[^>]*id="sync-result"[^>]*>', text)
    assert tag, "sources.html must carry the #sync-result announcer"
    attrs = tag.group(0)
    assert 'role="status"' in attrs
    assert 'aria-live="polite"' in attrs
    assert text.find('id="sync-result"') > text.find("</button>", text.find('id="sync-btn"'))


def test_sync_error_banner_is_a_hidden_alert() -> None:
    """The failure banner uses the chat error-banner markup style
    (kb-banner + is-error) and role="alert", shipping hidden —
    sources.js un-hides it with the error text on a failed run."""
    text = _text(SOURCES_HTML)
    tag = re.search(r'<div[^>]*id="sync-error-banner"[^>]*>', text)
    assert tag, "sources.html must carry the #sync-error-banner"
    attrs = tag.group(0)
    assert "kb-banner" in attrs and "is-error" in attrs
    assert 'role="alert"' in attrs
    assert re.search(r"\bhidden\b", attrs)
    assert 'id="sync-error-text"' in text
    # The banner lives in the page content, not the 64px header bar.
    assert text.find('id="sync-error-banner"') > text.find('<main id="main"')


def test_page_sub_copy_mentions_the_button() -> None:
    """The page-sub copy still points at the import CLI and now names
    the header button as the one-click alternative (task 02 step 1)."""
    sub = re.search(r'<p class="page-sub">(.*?)</p>', _text(SOURCES_HTML), re.DOTALL)
    assert sub, "sources.html must keep the .page-sub copy"
    assert "Re-run the import" in sub.group(1)
    assert "Sync sources" in sub.group(1)
    assert "header" in sub.group(1)


def test_sources_page_stays_cdn_free() -> None:
    """No-CDN rule (PLAN §7.3, A11): the new button markup adds no
    external references — same-origin assets only (the integration
    test_index_html_served_locally re-checks this on the served page)."""
    text = _text(SOURCES_HTML)
    assert 'src="https://' not in text
    assert 'href="https://' not in text


# ---------- header.js: the admin reveal ----------


def test_header_reveals_sync_btn_on_the_admin_branch() -> None:
    """initSharedHeader reveals #sync-btn in the SAME admin branch as
    #nav-sources (hidden = !admin) — one cached whoami, no extra
    whoami call; anonymous users never leave the hidden default. The
    ref is the module-level one — the state machine shares it."""
    js = _text(HEADER_JS)
    assert 'querySelector("#sync-btn")' in js, "module-level #sync-btn ref"
    fn = js.find("function initSharedHeader")
    assert fn != -1
    body = js[fn : js.find("\n}", fn)]
    assert "syncBtn.hidden = !admin" in body, "#sync-btn must join the admin reveal"
    # The reveal must not introduce a second whoami call site.
    assert js.count('fetch("/api/whoami")') == 1


# ---------- header.js: the sync state machine (moved here from
# ---------- sources.js in phase 34 task 02) ----------


def test_header_js_owns_the_sync_button_elements() -> None:
    """The button refs are module-level and null-safe: #sync-btn,
    #sync-label, the .sync-icon inside the button — a page without the
    markup is a complete no-op, exactly like the rest of the module."""
    js = _text(HEADER_JS)
    assert 'querySelector("#sync-btn")' in js
    assert 'querySelector("#sync-label")' in js
    assert 'syncBtn.querySelector(".sync-icon")' in js


def test_header_js_calls_the_sync_api() -> None:
    """The click posts to POST /api/sync and the poll loop GETs
    /api/sync/status — both through the same-origin API (A10)."""
    js = _text(HEADER_JS)
    assert 'fetch("/api/sync", { method: "POST" })' in js
    assert 'fetch("/api/sync/status")' in js


def test_header_js_polls_every_2000ms() -> None:
    """The feedback loop is a 2000 ms poll of the status endpoint,
    re-scheduled one tick at a time (setTimeout, not setInterval — an
    in-flight fetch can never overlap the next tick)."""
    js = _text(HEADER_JS)
    assert "SYNC_POLL_MS = 2000" in js
    assert "setTimeout(tick, SYNC_POLL_MS)" in js
    assert "setInterval" not in js


def test_header_js_adopts_409_and_starts_on_202() -> None:
    """202 (started) and 409 (a run started elsewhere — e.g. a second
    tab) both enter the running state and start polling: the UI never
    starts a second run, it adopts the in-flight one."""
    js = _text(HEADER_JS)
    assert "r.status === 202 || r.status === 409" in js
    idx = js.find("r.status === 202 || r.status === 409")
    branch = js[idx : idx + 400]
    assert "enterSyncRunningState()" in branch
    assert "startSyncPolling()" in branch


def test_header_js_hides_the_button_on_403() -> None:
    """A 403 anywhere (POST, the status poll, the load re-attach) is
    treated as not-admin: the button hides — defense in depth behind
    the whoami reveal (the primary gate)."""
    js = _text(HEADER_JS)
    assert len(re.findall(r"r\.status === 403", js)) >= 3, (
        "POST, the status poll, and the load re-attach must all handle 403"
    )
    assert js.count("syncBtn.hidden = true") >= 3, (
        "every 403 branch must hide the button"
    )


def test_header_js_running_state_is_never_stale() -> None:
    """Entering the running state disables the button, sets aria-busy,
    spins the icon, and swaps the label to 'Syncing…' (the §7.4
    feedback while the poll waits) — and a fresh run starts clean: the
    previous failure's title / aria-label / .is-error come off NOW,
    not when the run settles."""
    js = _text(HEADER_JS)
    body = _body(js, "enterSyncRunningState")
    assert "syncBtn.disabled = true" in body
    assert 'syncBtn.setAttribute("aria-busy", "true")' in body
    assert 'syncBtn.removeAttribute("title")' in body
    assert 'syncBtn.setAttribute("aria-label", "Sync sources")' in body
    assert "syncBtn.classList.remove(\"is-error\")" in body
    assert "syncIcon.classList.add(\"is-spinning\")" in body
    assert '"Syncing…"' in body


def test_header_js_terminal_states() -> None:
    """Terminal rendering: success → enabled + 'Synced HH:MM' (local
    time of finished_at); failed → enabled + retry-ready 'Sync sources'
    label + the sanitized error in the button's title + aria-label +
    the .is-error class (non-Sources pages: that is where the failure
    is visible). The counts formatting (fmtSyncResult) lives here and
    is EXPORTED for the Sources page ('added' always announced, zero
    terms omitted — a no-op re-sync reads '0 added · 1 unchanged')."""
    js = _text(HEADER_JS)

    success = _body(js, "applySyncSuccess")
    assert '"Synced"' in success and "fmtSyncTime(status.finished_at)" in success

    failure = _body(js, "applySyncFailure")
    assert 'settleSyncButton("Sync sources")' in failure  # retry-ready
    assert "syncBtn.title = error" in failure
    assert 'syncBtn.setAttribute("aria-label", error)' in failure
    assert "syncBtn.classList.add(\"is-error\")" in failure
    assert "sanitizeSyncError(status.error)" in failure

    result = _body(js, "fmtSyncResult")
    assert "added" in result and "unchanged" in result
    assert " · " in result
    assert "> 0" in result, "zero terms must be omitted"

    time = _body(js, "fmtSyncTime")
    assert "getHours()" in time and "getMinutes()" in time, "local HH:MM of finished_at"


def test_header_js_failed_error_is_sanitized() -> None:
    """The button's title/aria-label error is sanitized for the
    attributes: the server already masks credentials (sync.py
    _sanitize_error); the module collapses whitespace to a single line
    and caps the length, and a missing error still names a failure."""
    js = _text(HEADER_JS)
    body = _body(js, "sanitizeSyncError")
    assert "replace(/\\s+/g, \" \")" in body, "single line for the attributes"
    assert "200" in body, "long errors (chatty git stderr) are capped"
    assert '"The sync failed."' in body


def test_header_js_settles_the_button_on_terminal() -> None:
    """settleSyncButton re-enables the control, drops aria-busy, the
    title, and the failed affordances, and un-spins the icon — the
    button can never sit disabled after a run reaches a terminal state
    (failed included: retry-ready)."""
    js = _text(HEADER_JS)
    body = _body(js, "settleSyncButton")
    assert "syncBtn.disabled = false" in body
    assert 'syncBtn.removeAttribute("aria-busy")' in body
    assert 'syncBtn.removeAttribute("title")' in body
    assert 'syncBtn.setAttribute("aria-label", "Sync sources")' in body
    assert "syncIcon.classList.remove(\"is-spinning\")" in body


def test_header_js_never_starts_a_second_poll_loop() -> None:
    """startSyncPolling is guarded by the module-level timer: a 409
    adoption, a reload re-attach, or a stray call can never run two
    poll loops at once (phase completion criterion)."""
    js = _text(HEADER_JS)
    fn = js.find("function startSyncPolling")
    head = js[fn : js.find("const tick", fn)]
    assert re.search(r"if\s*\(\s*syncPollTimer\s*!==\s*null\s*\)\s*return", head), (
        "the single-loop guard must be the first statement"
    )
    assert "clearTimeout(syncPollTimer)" in _body(js, "stopSyncPolling")


def test_header_js_has_no_client_side_hard_timeout() -> None:
    """Phase locked decision: a sync can legitimately run for minutes
    (and outlive the page), so there is NO client-side hard timeout —
    the 2 s poll is the feedback loop and the server state is
    authoritative (the 120 s LLM-turn guard must not leak into the
    sync path)."""
    js = _text(HEADER_JS)
    assert "TURN_TIMEOUT" not in js
    sync_start = js.find("sync sources (phase 32")
    assert sync_start != -1, "the sync section marker comment"
    assert "120" not in js[sync_start:]


def test_header_js_reattaches_on_load_admin_only() -> None:
    """initSyncButton (run at module import, button pages only) awaits
    the SAME cached whoami — ADMIN ONLY (non-admins never poll, the
    status endpoint is admin-only): a running run re-enters the
    running state (reload mid-sync), a terminal run renders its last
    result, idle settles retry-ready; the click binding wires
    startSync to the button."""
    js = _text(HEADER_JS)
    fn = js.find("function initSyncButton")
    assert fn != -1
    body = js[fn : js.find("\n}\n", fn)]
    assert "await fetchIsAdmin()" in body, "admin-only boot (no extra fetch)"
    assert 'fetch("/api/sync/status")' in body
    assert 'status.state === "running"' in body
    assert 'status.state === "success"' in body
    assert 'status.state === "failed"' in body
    assert "syncBtn.addEventListener(\"click\", startSync)" in js
    tail = js[js.rfind("if (syncBtn)") :]
    assert "initSyncButton()" in tail, "boot re-attach runs at module import"


def test_header_js_emits_bor_sync_status_on_state_changes() -> None:
    """Every state change dispatches window 'bor:sync-status' with the
    status object as detail — the channel the Sources page's
    banner/result line subscribe to. The click path emits the
    synthetic running frame IMMEDIATELY (no 2 s poll lag — the exact
    old enterRunningState clear behavior, now event-driven)."""
    js = _text(HEADER_JS)
    assert (
        'window.dispatchEvent(new CustomEvent("bor:sync-status", { detail: status }))'
        in js
    )
    for fn in ("applySyncSuccess", "applySyncFailure", "applySyncIdle"):
        assert "emitSyncStatus" in _body(js, fn), f"{fn} must emit its frame"
    # the running frame: synthetic on click, the real object on boot
    assert 'emitSyncStatus({ state: "running" })' in js
    assert "emitSyncStatus(status)" in _body(js, "initSyncButton")


# ---------- sources.js: the event-driven result line + banner ----------


def test_sources_js_renders_off_the_sync_status_event() -> None:
    """The Sources page keeps ONLY its page-specific rendering:
    #sync-result (aria-live) + #sync-error-banner (role=alert), driven
    by the module's 'bor:sync-status' event (detail = the status
    object): running → clear + hide; success → the counts (the
    imported fmtSyncResult) + a live catalog refresh; failed → the
    banner with the error; idle → hide + clear."""
    js = _text(SOURCES_JS)
    assert 'window.addEventListener("bor:sync-status"' in js
    assert 'status.state === "running"' in js
    assert 'status.state === "success"' in js
    assert 'status.state === "failed"' in js
    assert "fmtSyncResult(status.detail)" in js
    assert "loadDocs()" in js, "the catalog re-fetches live on a successful sync"
    assert "showSyncError(status.error)" in js
    assert "syncResult.textContent" in js


def test_sources_js_no_longer_owns_the_sync_machine() -> None:
    """The state machine is GONE from sources.js (header.js owns it):
    no button refs, no POST, no status poll, no button-state helpers,
    no click binding, no load re-attach."""
    js = _text(SOURCES_JS)
    for gone in (
        "SYNC_POLL_MS",
        "syncPollTimer",
        "startSyncPolling",
        "stopSyncPolling",
        "enterRunningState",
        "settleSyncButton",
        "applySyncSuccess",
        "applySyncFailure",
        "applySyncIdle",
        "initSyncButton",
        "startSync",
        'fetch("/api/sync", { method: "POST" })',
        'fetch("/api/sync/status")',
        'querySelector("#sync-btn")',
        'querySelector("#sync-label")',
        'querySelector(".sync-icon")',
    ):
        assert gone not in js, f"{gone!r} must be gone from sources.js (header.js owns it)"


# ---------- styles.css: the §7.4 states ----------


def test_sync_button_css_ghost_pill_and_disabled_state() -> None:
    """.sync-btn is the same ghost pill as .new-chat-btn (contrast pair
    ink-soft on surface ≈6.9:1 ≥ 4.5:1), with a ≥44px touch floor and a
    :disabled state (never stale — the busy look is visible)."""
    css = _text(STYLES_CSS)
    block = re.search(r"\.sync-btn\s*\{([^}]*)\}", css)
    assert block, "styles.css must define .sync-btn"
    body = block.group(1)
    assert "min-height: 44px" in body
    assert "color: var(--ink-soft)" in body
    assert "border-radius: 999px" in body
    disabled = re.search(r"\.sync-btn:disabled\s*\{([^}]*)\}", css)
    assert disabled, ".sync-btn:disabled must be styled"
    assert "cursor: wait" in disabled.group(1)


def test_sync_icon_spins_and_respects_reduced_motion() -> None:
    """The running state spins the refresh icon on the shared spin
    keyframes (1s linear infinite), and prefers-reduced-motion stills
    it — the existing opt-out pattern."""
    css = _text(STYLES_CSS)
    spin = re.search(r"\.sync-btn \.sync-icon\.is-spinning\s*\{([^}]*)\}", css)
    assert spin, "the .is-spinning state must be styled"
    assert "animation: spin 1s linear infinite" in spin.group(1)
    spinner = r"\.sync-btn \.sync-icon\.is-spinning\s*\{([^}]*)\}"
    reduced = re.search(r"@media \(prefers-reduced-motion: reduce\)\s*\{\s*" + spinner, css)
    assert reduced, "the spin must opt out under prefers-reduced-motion"
    assert "animation: none" in reduced.group(1)
    assert "@keyframes spin" in css, "the spin keyframes are shared (pre-existing)"


def test_sync_result_is_styled() -> None:
    """#sync-result (the aria-live last-result line) is styled in the
    theme tokens — soft ink, small mono, no wrap in the header bar."""
    css = _text(STYLES_CSS)
    block = re.search(r"\.sync-result\s*\{([^}]*)\}", css)
    assert block, "styles.css must define .sync-result"
    assert "var(--ink-soft)" in block.group(1)