93 lines
5.3 KiB
Markdown
93 lines
5.3 KiB
Markdown
# Story: Admin Sync Button (One-Click Doc Import Sync)
|
|
|
|
**Phase:** `32_admin_sync_button.md` · **E2E:** `tests/e2e/test_sync_button.py`
|
|
|
|
## Narrative
|
|
|
|
As **the admin (owner)**, I don't want to SSH in and hand-run the import
|
|
script every time my notes repos move. I want **a button that only I can
|
|
see** — on the Sources page — that **triggers a doc import sync by
|
|
cloning the relevant repos and then running the import script**, with
|
|
live feedback so I always know whether it is running, what it changed,
|
|
or why it failed.
|
|
|
|
- **Given** `BOR_GIT_SOURCES` is set (the git repos) and I am signed in
|
|
as the admin
|
|
- **When** I click **Sync sources** on the Sources page
|
|
- **Then** the app clones/pulls each repo, re-imports with prune (the
|
|
`--prune` equivalent — the canonical "mirror the repos" action), and
|
|
refreshes the KB overview when anything changed — while the button
|
|
reports the whole lifecycle (**Syncing…** → **Synced HH:MM** + counts,
|
|
or an error banner naming the failure) and never sits stale or stuck.
|
|
Anonymous visitors never see the button, and the sync endpoints answer
|
|
them with 403.
|
|
|
|
## Acceptance criteria
|
|
1. **Admin-only visibility.** The button ships `hidden` in
|
|
`sources.html` (anonymous-safe) and `header.js` reveals it for the
|
|
admin on the SAME cached whoami that reveals `#nav-sources` /
|
|
`#nav-tuning` (one fetch, no extra whoami call); anonymous users
|
|
never see it.
|
|
2. **The sync API (A10 extended, A12 in-process).** `POST /api/sync`
|
|
(admin only) starts one background task — `clone_or_pull` each
|
|
`BOR_GIT_SOURCES` repo (phase 28, reused) → `import_sources(prune=True)`
|
|
→ `regenerate_overview` when the KB changed (phase 31) — and returns
|
|
`202`. A second trigger while a run is in flight returns
|
|
`409 {"detail": "a sync is already running"}` (one sync at a time).
|
|
`GET /api/sync/status` (admin only) reports `idle | running |
|
|
success | failed` with ISO-8601 timestamps and the run's `detail` /
|
|
`error`. Both endpoints answer anonymous callers with 403.
|
|
3. **Loud failure.** An unset/empty `BOR_GIT_SOURCES` fails the sync with
|
|
"no git sources configured (BOR_GIT_SOURCES)" (manual `--source` dirs
|
|
have no repo to clone); a `GitSyncError` fails the run with git's
|
|
stderr (the repo named, credentials masked) before any import.
|
|
4. **The §7.4 "never stale" lifecycle.** Click → `202` → button disabled
|
|
with **Syncing…** (spinning icon, `aria-busy`) + a 2 s poll of the
|
|
status endpoint — the ONLY feedback timer; there is no client-side
|
|
hard timeout (a sync can legitimately run for minutes; the server
|
|
state is authoritative). Success → enabled, **Synced HH:MM** (local
|
|
time of `finished_at`) + the last result in `#sync-result`
|
|
(`role="status"` / `aria-live="polite"`; "added" always announced,
|
|
zero terms omitted, a no-op run reads `0 added · 1 unchanged`).
|
|
Failure → enabled, retry-ready **Sync sources** + the `role="alert"`
|
|
banner naming the error. A `409` adopts the in-flight run (never a
|
|
second poll loop); a reload mid-sync re-attaches to the running run;
|
|
a `403` hides the button (defense in depth).
|
|
5. **Idempotent.** Re-syncing an unchanged repo is a fast-forward pull +
|
|
sha256 hash skip — nothing re-embedded, the overview left alone
|
|
(change-gated), the result `0 added · 1 unchanged`.
|
|
6. **Quality gates.** Integration (`tests/integration/test_sync_api.py`):
|
|
anonymous 403s; idle → running → success/failed transitions with git +
|
|
import + overview mocked; 409 double trigger; `GitSyncError` →
|
|
`failed` with the repo named and the import never called; `prune=True`
|
|
asserted. Unit (`tests/unit/test_sync_button.py`, frontend-assertion):
|
|
the ship-hidden markup, the header reveal, the state machine (2 s
|
|
poll, 202/409/403 branches, terminal labels, single-poll guard, no
|
|
client timeout), the CSS states (spin + reduced-motion opt-out,
|
|
disabled, focus-visible, contrast ≥ 4.5:1, 44 px touch floor).
|
|
Coverage `app/` > 90 % (`app/api/sync.py` fully covered).
|
|
7. **E2E (this story's gate).** `tests/e2e/test_sync_button.py`, run in
|
|
isolation: a real local `file://` git fixture repo (deterministic, no
|
|
network — git is a documented environment prerequisite, phase 28) with
|
|
the mock LLM proves the admin-only visibility, the full lifecycle
|
|
against the REAL clone → import → overview path (including the
|
|
idempotent second run and the fresh `kb_overview` row), and the 409
|
|
double trigger.
|
|
|
|
## Playwright Mapping Rule
|
|
`tests/e2e/test_sync_button.py` — run in isolation (Chromium +
|
|
`podman compose up -d db` + git on PATH; mock LLM, no live aipi). The
|
|
module overrides the session app fixture with per-module env
|
|
(`BOR_GIT_SOURCES=file://<fixture repo>`, its own `BOR_SOURCES_DIR`) and
|
|
truncates the KB tables before each test (the E2E isolation pattern):
|
|
|
|
1. `test_anonymous_sees_no_button` → AC 1 + 2 (the button never leaves
|
|
`hidden`; both endpoints 403).
|
|
2. `test_admin_sync_lifecycle` → AC 2 + 4 + 5 (button visible for the
|
|
admin; click → **Syncing…** (disabled) → **Synced HH:MM** +
|
|
`1 added`; the fixture path `notes/sync-fixture.md` in the Sources
|
|
table; the `kb_overview` row fresh and non-empty (DB check); the
|
|
idempotent second run → `0 added · 1 unchanged`).
|
|
3. `test_double_trigger_409` → AC 2 (second trigger while running → 409
|
|
with the exact detail; the single in-flight run still completes).
|