Commit Graph
3 Commits
Author SHA1 Message Date
timothy 63afc5f743 fix(819): derive the SPA page-size guard's population from the git index
`pageSizeCallSites.guard.test.ts` asserts EXACT completeness over the files it
discovers, but discovered them with `import.meta.glob` over `web/src`. A
directory walk is not an authoritative source: an untracked `.ts`/`.tsx` — a
scratch file, a half-finished component, an editor dropping — entered the
population and failed as unregistered on that checkout, while CI, which only
ever checks out tracked files, stayed green. Developer-red / CI-green, the #778
shape #806 removed from every other guard here.

Witnessed before the fix: planting an untracked `Scratch819Untracked.tsx` with a
`pageSize: 25` literal reddened the guard with
`UNREGISTERED (1) — screens/Scratch819Untracked.tsx:literal:25`.

The glob stays, as the source of file CONTENT. The POPULATION is now
`git ls-files`, read by `web/vite-plugins/trackedSourceFiles.ts` in Vite's own
Node context and handed to the app project as the virtual module
`virtual:etv-tracked-source-files`. That is what reaches the index without
admitting `@types/node` to `tsconfig.app.json` — the obstacle that deferred this
in #818, since wiring those types in was tried and reverted (it leaked Node's
ambient `setTimeout` into the app project and broke three unrelated
`window.setTimeout` mocks).

The plugin fails rather than degrading: a failed or empty `git ls-files` throws,
because answering "could not tell" with the very population the index replaced
is a permanent no-op that reports green (#772's shape). It reads the index
lazily, inside `load()`, so `vite build` — including the Docker image build,
whose context carries no `.git` — never shells out to git. Verified by building
in a copy of `web/` outside any repository.

Proofs, all executed:
- clause mutation: deleting `if (!isTrackedSourcePath(...))` from
  `listSourceFilesFrom` reddens exactly one named test, `EXCLUDES an untracked
  file that matches the scope in every other way (#819)`, and nothing else. The
  pipeline was extracted to take injected inputs precisely so that clause is
  provable — over real source on a clean checkout it removes nothing, so a
  plant-a-real-file check pins nothing, the same argument
  `isScannableSourceFileName` already records.
- negative control: the same planted file, once `git add`ed, is caught again.
  Untracked is ignored, tracked is caught — the guard did not go blind.
- positive control against a clause mutated to reject everything.
- anti-vacuity on the consuming side: the real index is >50 paths and contains
  named known files, so a plugin that stopped being registered cannot pass an
  empty population off as a satisfied one.

Residual, stated rather than implied: a file tracked but DELETED in the working
tree has no content and drops out. Not asserted — an unstaged deletion is a
normal developer state, and a guard red on one gets ignored (#806) — and a
REGISTERED site in such a file still fails loudly on the STALE direction.

fixes #819
2026-08-29 05:12:23 +02:00
timothy d8c0b3e752 feat(445,533): headless Playwright UI-E2E flows + fix e2e-local readiness probe [decisions-edit]
Adds the last deferred #299/#363 follow-up: the flows that CANNOT be expressed
as curl calls. Scope rule (the durable part) — assert only what the curl
harness structurally cannot reach:

  1. client-side form validation (the Setup confirm-password gate is pure React
     state and makes no request, so there is no HTTP contract to assert)
  2. AuthGate's RENDERED states (Setup vs Login vs app)
  3. the session cookie authenticating the SPA's OWN /api XHRs — curl proves the
     cookie works for curl, not that the app sends it
  4. sign-out through the UserMenu back to the login gate

New: web/e2e/boot-gate.spec.ts, web/playwright.config.ts, scripts/e2e-ui.sh
(owns the whole lifecycle: fresh config dir -> boot -> specs -> always kill).

Runs as a second step of the EXISTING advisory `functional-e2e` job rather than
a new job: the dominant cost there is `npm ci` + the Release build, both already
done, so this adds ~5s instead of duplicating a heavy job. It boots its own
fresh instance on port 8410 because the first spec asserts the one-shot Setup
gate that the curl step has already claimed on its config dir.

Determinism (the issue asked for it explicitly): `serial`, `workers: 1`,
`retries: 0` even in CI — a retry would let a flaky flow merge looking green.
Measured 5 consecutive clean runs, ~2s each.

Pins all five `container:` jobs to the toolchain image built by the preceding
commit, which bakes `chromium-headless-shell`.

Non-obvious coupling fixed: vitest's default include glob would have collected
web/e2e/*.spec.ts and run it under jsdom. Excluded `e2e/**` by spreading
`configDefaults.exclude` rather than narrowing `include` to `src/**`, because
web/scripts/ holds a real vitest test an src-only include would silently stop
running.

`RebuildSearchIndexHandler` logs one of two mutually-exclusive lines just before
`SystemStartup.SearchIndexIsReady()`:

  fresh config  -> "Done migrating search index in {Duration}"
  reused config -> "Search index is already version {Version}"

The probe watched only the first, so a reused dir waited out the full 120s
timeout and then killed a perfectly healthy server. Widened to a `grep -Eq`
alternation; the handler's if/else is exhaustive, so the pair covers every path
to readiness.

Verified with a negative control: on a reused dir the server is ready in 2s via
the "already version" line, and the OLD probe string is genuinely ABSENT from
that run's log — so the old code would have hung, i.e. the fix is load-bearing
rather than incidentally passing.

The "prefer a fresh config dir" guidance stays: that guards state bleed, which
is a separate concern from the probe hanging.

- `wait "$PID"` in the cleanup trap was a NO-OP: the server is a grandchild
  (launched in e2e-local.sh's subshell, which then exits), so `wait` fails
  instantly and was swallowed by `|| true` — cleanup did not actually ensure the
  port was released, exactly what its comment claimed. Replaced with a bounded
  `kill -0` poll, then SIGKILL.
- Added a port pre-flight check: previously an occupied port surfaced as a 120s
  readiness timeout that reads like a broken build. Now fails in 0s naming the
  PIDs, and warns against blanket-killing `dotnet ErsatzTV.dll` (that reaps
  other sessions' servers).

- UI-E2E: 5x clean (3 specs, ~2s); back-to-back runs pass with no manual cleanup
- curl harness unaffected by the boot-script change: 45/45 PASS
- web: 983 tests / 105 files green; typecheck + lint clean
- vitest collection verified: excludes web/e2e, still collects web/scripts
- Dockerfile sequence + browser launch validated verbatim in a container on the
  real amd64 base before committing; chromium launches as root with NO sandbox
  opt-out needed
- decisions validator green; catalog regenerated
- docs/decisions.md TOC repaired: it had drifted to 69 of 97 records and held a
  dangling anchor to the #72 record that #415 superseded into archive/.
  Regenerated with a generator validated against the 68 existing anchors (0
  mismatches) -> 97/97, no dangling, no duplicates.

Docs: docs/e2e-local.md (new "UI-E2E harness" section), docs/ci-cd.md (toolchain
image + UI-E2E step), docs/testing.md, docs/README.md, docs/decisions.md
(new `ci.ui-e2e-harness` record; `ci.functional-e2e-harness` amended — its Rule
said "curl-only", now accurate).

Refs #445 #533
2026-07-25 14:03:59 +02:00
timothy b183c6a154 feat(frontend): scaffold ChicoryTV SPA
refs #78
2026-07-02 07:37:00 +02:00