feat(admin): one-click sources sync — admin-only button triggers git clone/pull + re-import + KB overview refresh with polled live status

2026-08-25 21:39:38 -04:00
parent 0654b304e1
commit 52136fe307
13 changed files with 1621 additions and 2 deletions
@@ -0,0 +1,325 @@
+"""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 sources.js sync state machine
+(2 s poll, 202 start / 409 adoption / 403 hide, terminal labels,
+the aria-live result, the single-poll-loop guard, no client-side hard
+timeout), 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 (querySelector + hidden = !admin) — one cached whoami,
+    no extra whoami call; anonymous users never leave the hidden
+    default."""
+    js = _text(HEADER_JS)
+    fn = js.find("function initSharedHeader")
+    assert fn != -1
+    body = js[fn : js.find("\n}", fn)]
+    assert 'querySelector("#sync-btn")' in body, "#sync-btn must join the admin reveal"
+    assert "syncBtn.hidden = !admin" in body
+    # The reveal must not introduce a second whoami call site.
+    assert js.count('fetch("/api/whoami")') == 1
+
+
+# ---------- sources.js: the sync state machine ----------
+
+
+def test_sources_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(SOURCES_JS)
+    assert 'fetch("/api/sync", { method: "POST" })' in js
+    assert 'fetch("/api/sync/status")' in js
+
+
+def test_sources_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(SOURCES_JS)
+    assert "SYNC_POLL_MS = 2000" in js
+    assert "setTimeout(tick, SYNC_POLL_MS)" in js
+    assert "setInterval" not in js
+
+
+def test_sources_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(SOURCES_JS)
+    assert "r.status === 202 || r.status === 409" in js
+    idx = js.find("r.status === 202 || r.status === 409")
+    branch = js[idx : idx + 200]
+    assert "enterRunningState()" in branch
+    assert "startSyncPolling()" in branch
+
+
+def test_sources_js_hides_the_button_on_403() -> None:
+    """A 403 anywhere (POST or poll) is treated as not-admin: the
+    button hides — defense in depth behind header.js's whoami reveal."""
+    js = _text(SOURCES_JS)
+    for occurrence in re.finditer(r"r\.status === 403", js):
+        window = js[occurrence.start() : occurrence.start() + 400]
+        assert "syncBtn.hidden = true" in window, "every 403 branch must hide the button"
+    assert len(re.findall(r"r\.status === 403", js)) >= 3, (
+        "POST, the status poll, and the load re-attach must all handle 403"
+    )
+
+
+def test_sources_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)."""
+    js = _text(SOURCES_JS)
+    fn = js.find("function enterRunningState")
+    assert fn != -1
+    body = js[fn : js.find("\n}", fn)]
+    assert "syncBtn.disabled = true" in body
+    assert 'syncBtn.setAttribute("aria-busy", "true")' in body
+    assert "syncIcon.classList.add(\"is-spinning\")" in body
+    assert '"Syncing…"' in body
+
+
+def test_sources_js_terminal_states() -> None:
+    """Terminal rendering: success → enabled + 'Synced HH:MM' (local
+    time of finished_at) + the last-result counts ('added' always
+    announced, zero terms omitted — a no-op re-sync reads '0 added ·
+    1 unchanged', never an empty live region) + a live catalog refresh
+    (the KB just changed — never a stale table); failed → enabled +
+    retry-ready 'Sync sources' label + the role='alert' banner with
+    the error; the result is cleared on a failure."""
+    js = _text(SOURCES_JS)
+
+    success = _body(js, "applySyncSuccess")
+    assert '"Synced"' in success and "fmtSyncTime(status.finished_at)" in success
+    assert "fmtSyncResult(status.detail)" in success
+    # A successful sync just changed the KB: the catalog re-fetches live
+    # (table / stats / empty state never sit stale under "Synced").
+    assert "loadDocs()" in success
+
+    failure = _body(js, "applySyncFailure")
+    assert 'settleSyncButton("Sync sources")' in failure  # retry-ready
+    assert "showSyncError(status.error)" in failure
+
+    result = _body(js, "fmtSyncResult")
+    # "added" is the always-announced headline term; "unchanged" covers
+    # the no-op case ("0 added · 1 unchanged"); updated/pruned are
+    # zero-omitted.
+    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_sources_js_settles_the_button_on_terminal() -> None:
+    """settleSyncButton re-enables the control, drops aria-busy, and
+    un-spins the icon — the button can never sit disabled after a run
+    reaches a terminal state (failed included: retry-ready)."""
+    js = _text(SOURCES_JS)
+    fn = js.find("function settleSyncButton")
+    assert fn != -1
+    body = js[fn : js.find("\n}", fn)]
+    assert "syncBtn.disabled = false" in body
+    assert 'syncBtn.removeAttribute("aria-busy")' in body
+    assert "syncIcon.classList.remove(\"is-spinning\")" in body
+
+
+def test_sources_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(SOURCES_JS)
+    fn = js.find("function startSyncPolling")
+    assert fn != -1
+    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_sources_js_has_no_client_side_hard_timeout() -> None:
+    """Phase locked decision: a sync can legitimately run for minutes,
+    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(SOURCES_JS)
+    assert "TURN_TIMEOUT" not in js
+    assert "120" not in js[js.find("Phase 32") :], (
+        "no turn-timeout constant in the sync section"
+    )
+
+
+def test_sources_js_reattaches_on_load() -> None:
+    """initSyncButton (run from the IIFE on the admin path, after
+    initSharedHeader) fetches the status once and re-enters the running
+    state on 'running' (reload mid-sync) or renders the last result on
+    a terminal state; the click binding wires startSync to the button."""
+    js = _text(SOURCES_JS)
+    fn = js.find("function initSyncButton")
+    assert fn != -1
+    body = js[fn : js.find("\n}\n", fn)]
+    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
+    # The IIFE runs it on the admin path only (after the whoami gate).
+    iife = js[js.find("(async () => {") :]
+    admin_idx = iife.find("await isAdmin()")
+    init_idx = iife.find("initSyncButton();")
+    assert -1 < admin_idx < init_idx, "re-attach must run only for the admin"
+
+
+# ---------- 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)