diff --git a/aidlc-docs/features/prerendering/aidlc-state.md b/aidlc-docs/features/prerendering/aidlc-state.md index 8eb0254..8991355 100644 --- a/aidlc-docs/features/prerendering/aidlc-state.md +++ b/aidlc-docs/features/prerendering/aidlc-state.md @@ -54,10 +54,10 @@ - [x] Units Generation - SKIP (three units fixed in the plan) ### ๐ŸŸข CONSTRUCTION PHASE -- [ ] Functional Design - EXECUTE (units 1, 2) / SKIP (unit 3): units 1 and 2 approved -- [ ] NFR Requirements - SKIP -- [ ] NFR Design - SKIP -- [ ] Infrastructure Design - EXECUTE (unit 3) +- [x] Functional Design - EXECUTE (units 1, 2) / SKIP (unit 3): units 1 and 2 approved +- [x] NFR Requirements - SKIP +- [x] NFR Design - SKIP +- [x] Infrastructure Design - EXECUTE (unit 3), approved - [x] Code Generation - EXECUTE (per unit): 1 Start migration and script step โœ… (a1d5c1e; continue with Start, owner, 2026-10-31) โ†’ 2 Fade-in, no JavaScript, first photo โœ… (b5fd832) โ†’ 3 Hosting and targets โœ… (2006fa0; CI run 599 green; test deployed in run 598) - [ ] Build and Test - EXECUTE diff --git a/aidlc-docs/features/prerendering/construction/build-and-test/build-and-test-summary.md b/aidlc-docs/features/prerendering/construction/build-and-test/build-and-test-summary.md new file mode 100644 index 0000000..64c436e --- /dev/null +++ b/aidlc-docs/features/prerendering/construction/build-and-test/build-and-test-summary.md @@ -0,0 +1,76 @@ +# Build and Test Summary + +Feature: prerendering. Branch `feature/prerendering`, worktree `AndreaSlopFotografie-prerendering`. +Verified at HEAD `39dc456`. The code is that of `2006fa0` (CI run 599); later commits change only `aidlc-state.md` and `audit.md`. +In this stage no build and no Lighthouse run was made. `pnpm test` was run once (exit 0). The other results come from CI runs 598 and 599, the main session's checks on the test site, and the measurement reports. + +## Build Status +- **Build Tool**: pnpm 12.11.2, `tsc && vite build && node config/externalizeInlineScripts.ts` (Node v24.16.0) +- **Build Status**: Success (the `check` job of CI run 599 is green: lint, format, unit tests, build, audits) +- **Build Artifacts**: `web/dist/client/` (12 HTML files, `sitemap.xml`, assets with the moved scripts; deployed) and `web/dist/server/` (not deployed) +- **Main bundle**: 547,302 bytes raw, 155,603 bytes gzip over the wire (test server) +- **Build Time**: not recorded in this stage + +## Test Execution Summary + +### Unit Tests +- **Total Tests**: 1390 in 132 files (code summary of unit 3; baseline on master 888 in 113 files) +- **Passed**: all; `pnpm test` at HEAD exited 0 in this stage. The "Tests" line was not captured (output read through `tail`), so the count is the code summary's figure. +- **Failed**: 0 +- **Coverage** (v8, this stage): statements 96.1%, branches 94.5%, functions 97.36%, lines 96.6%; thresholds met +- **fast-check seed**: printed on every run (`config/testSeed.ts`); replay with `FC_SEED= pnpm test` +- **Status**: Pass +- **Details**: `unit-test-instructions.md` + +### Integration Tests (browser suite, `pnpm e2e`) +- **Test Scenarios**: 7 (hydration, raw HTML, display fallbacks, nginx rules against the build, server redirect against router, deploy scripts, deployed test site) +- **Passed**: 471 of 471 tests in 12 files (CI run 599), including 198 against real nginx 1.24 (`serverRules.e2e.ts`) and 47 deploy-script tests with the real lftp cases (`deployScripts.e2e.ts`) +- **Failed**: 0 +- **Local run before CI**: 248 passed, 204 skipped (nginx and lftp suites skipped on the PC), 0 failed +- **Status**: Pass +- **Details**: `integration-test-instructions.md` + +### Performance Tests +- **Reference measurement** (author's PC, 3 runs, median, commit `6d4d012`, not re-run): mobile 0.85 to 0.97 on the 12 URLs (master 0.75 to 0.91); desktop 0.99 or 1.00. Every URL meets its target (`/` exactly at 0.85). Accessibility 1, best practices 1. +- **CI run 599** (Pi runner, 1 run): performance mobile 0.47 to 0.66 and desktop 0.71 to 0.81, all warnings, by design (warn-only on the Pi). Accessibility, best practices and SEO assertions pass. +- **Status**: Pass against the reference measurement; CI performance is warn-only and not comparable. +- **Details**: `performance-test-instructions.md` + +### Additional Tests +- **Contract Tests**: N/A (no API; static site) +- **Security Tests**: Pass for the production audit, headers, redirects and deploy-script checks. Development audit: advisories in tools only, non-blocking (23 at unit 3 Step 21). IIS and FTPS unverified. Details: `security-test-instructions.md`. +- **E2E Tests**: Automated suite passes (above). Human check V-D4 (no-JS menu in Firefox, Safari, Chrome on Android) is open. Details: `e2e-test-instructions.md`. + +## Test site check (run 598, commit `79b1a66`) +Deployed to `test.andreaslop.nl` with the post-deploy check green, after the owner placed the new nginx config first. Curl checks by the main session: pages 200; `/over-mij/`, `/Over-Mij`, `/over-mij.html`, `/index.html` give 301; `/bestaat-niet`, `/404`, `/404.html`, `/%5Cevil.example/` give 404; gzip on HTML and JS; security headers present; no e-mail address in the HTML of `/over-mij`. Pi-Main checked the config on nginx 1.30.6 without root. + +## Defects found by the test stages (all fixed) +CI runs 591 to 598 found and fixed: a hydration test race, a case-insensitive nginx `map` key (`/Over-Mij`), an open redirect through `%5C`, harness permissions when nginx runs as root, the PC runner (no `policy.json`, run 597), and a duplicated upload script (run 598). Details are in the code summaries and `audit.md`. + +## Extension Compliance + +### Property-Based Testing (full enforcement) +| Rule | Status | Note | +|---|---|---| +| PBT-08 (shrinking and reproducibility; applicable at this stage) | Compliant | Seed printed on every run and replayable (`FC_SEED`); no shrink override found; both CI jobs log a seed; PBT is in CI | +| PBT-01 to PBT-07, PBT-09, PBT-10 | Not re-evaluated | Evaluated at Functional Design and Code Generation (properties P1 to P25 and P-HST-01 to 11 are listed in the code summaries); outside this stage's scope | + +### Security Baseline +Compliant where applicable: SECURITY-04, 09, 10, 11, 13, 15; others N/A for a static site. Unverified: IIS rules, FTPS against a real host. See `security-test-instructions.md`. + +## Overall Status +- **Build**: Success +- **All Tests**: Pass (471 of 471 browser tests in CI, unit suite green) +- **Ready for Operations**: N/A (Include Operations Phase = No, `aidlc-state.md`) + +## Open Items +1. **V-D4**: the no-JS menu in Firefox, Safari and Chrome on Android. Human task for the owner, on the test site. +2. **IIS**: the rules are generated text and unverified; there is no host yet. `deploy-production` stays dispatch-only. +3. **FTPS** against a real host is untested; lftp is proven against a local `file:` target only. +4. **nginx 1.30.6 on the Pi**: CI proves 1.24.0; the config was checked on 1.30.6 without root. +5. **Lighthouse**: `/` sits exactly at its 0.85 target with `numberOfRuns: 1`, so a slow local run can fail `pnpm check`. zwangerschap and portret keep a 0.85 target because one run is unreliable at 0.90. Responsive photos are the planned fix for the exceptions. +6. **PC runner**: stopped (missing `policy.json`). Restart with `podman start gitea-runner`; the cause is open. +7. **Repository access**: the repository appears to be anonymously readable from the Pi. To be checked by the owner. + +## Next Steps +Build and test passes. Operations is not included, so the workflow completes after this stage once the owner has reviewed the open items above. diff --git a/aidlc-docs/features/prerendering/construction/build-and-test/build-instructions.md b/aidlc-docs/features/prerendering/construction/build-and-test/build-instructions.md new file mode 100644 index 0000000..cdf0af9 --- /dev/null +++ b/aidlc-docs/features/prerendering/construction/build-and-test/build-instructions.md @@ -0,0 +1,63 @@ +# Build Instructions + +Feature: prerendering (branch `feature/prerendering`, worktree `AndreaSlopFotografie-prerendering`). +Verified at HEAD `39dc456`. Only documents changed since `2006fa0`, the commit CI run 599 built (`git diff --stat 2006fa0 HEAD` lists `aidlc-state.md` and `audit.md` only). No build was run in this stage; the build facts come from CI run 599, the test deployment (run 598) and the code summaries. + +## Prerequisites +- **Build Tool**: pnpm 12.11.2 (`packageManager` in `web/package.json`), run from `web/`. Vite with TanStack Start (prerender), TypeScript (`tsc` runs first). +- **Runtime**: Node.js v24.16.0 (the version of the measurements and the local runs). +- **Dependencies**: installed from `web/pnpm-lock.yaml` only (`pnpm install --frozen-lockfile`). The `postinstall` hook runs `chakra typegen ./src/theme.ts`. The feature added exact pins for `@tanstack/react-start` 1.169.4 and `@tanstack/react-router` 1.170.46, a pin for `playwright-core` 1.55.0, and a `zod@4` override (`^4.6.6`) in `pnpm-workspace.yaml` (unit 1 code summary, deviations 1 and 2). +- **Environment Variables**: + - `VITE_RELEASE`: set by CI to the commit SHA for Sentry. Not needed locally. + - `FC_SEED=`: replays a fast-check run (see `unit-test-instructions.md`). + - `CI=true`: makes a missing nginx fail the browser tests instead of skipping the nginx suites (BR-HST-24). + - `LIGHTHOUSE_PERFORMANCE=warn`, `LIGHTHOUSE_CHROME_FLAGS`: Lighthouse only (see `performance-test-instructions.md`). +- **System Requirements**: Windows 11 with Git Bash, or the Ubuntu CI container. The browser tests need Chromium (Playwright 1.55.0). The nginx and lftp suites need `nginx` and `lftp` installed. The CI job installs both; the author's PC has neither, so those suites are skipped there. + +## Build Steps + +### 1. Install Dependencies +```bash +cd web +pnpm install --frozen-lockfile +``` +Expected: lockfile up to date, exit 0. In CI run 599 the install also printed `Lockfile passes supply-chain policies (910 entries)`. + +### 2. Configure Environment +No configuration is needed for a local build. Do not create `.env` files. + +### 3. Build All Units +```bash +cd web +pnpm build +``` +`pnpm build` is `tsc && vite build && node config/externalizeInlineScripts.ts`. The three steps cover all three units together: +- Unit 1 (start migration): Vite builds a client and a server environment and prerenders one HTML file per page. +- Unit 1 (script step): `externalizeInlineScripts.ts` moves every inline executable script into `/assets/inline-.js` and fails the build if an inline script, an `on*=` attribute or a `javascript:` link remains. +- Units 2 and 3 are code and generated text inside the same build (no extra build step). The generated server files `web/deploy/nginx/andreaslop-test.conf` and `web/deploy/iis/web.config` come from `web/config/serverConfig.ts`; a unit test checks that the committed files equal the generator output. + +### 4. Verify Build Success +- **Expected Output**: exit 0. At its Step 31 unit 1 reported "12 pages, 16 scripts moved (28 files written), no violations". +- **Build Artifacts** (gitignored): + - `web/dist/client/`: 12 HTML files (11 pages and `404.html`), `sitemap.xml`, and all assets including the moved scripts. This folder is the CI artifact `dist` and is what gets deployed. + - `web/dist/server/`: a sibling folder, not deployed. +- **Main bundle** (measured on the test server after run 598): 547,302 bytes raw, 155,603 bytes over the wire with gzip. +- **Common Warnings**: Vite's chunk-size warning (main bundle above 500 kB), as on master. Accepted. + +## Troubleshooting + +### Build Fails with Dependency Errors +- **Cause**: lockfile out of date, or `node_modules` from another branch (this feature changed `package.json` and the lockfile). +- **Solution**: run `pnpm install --frozen-lockfile` again. Do not change the lockfile in this stage; report the failure with its output. + +### Build Fails with Compilation Errors +- **Cause**: `tsc` errors. `src/routeTree.gen.ts` is generated by the TanStack plugin. +- **Solution**: read the first `error TS` line. If it is in `routeTree.gen.ts`, run `pnpm exec vite build` once to regenerate it, then `pnpm build`. Do not hand-edit the generated file. + +### Build Fails in the Script Step +- **Cause**: `externalizeInlineScripts.ts` found an inline executable script, an `on*=` attribute or a `javascript:` link in a prerendered page. +- **Solution**: the error names the file. Remove the inline code from the component. The CSP (`script-src 'self'` plus Umami) must not be loosened. + +### Browser Tests Cannot Find `dist/client` +- **Cause**: `pnpm e2e` runs against the build output. +- **Solution**: run `pnpm build` first. diff --git a/aidlc-docs/features/prerendering/construction/build-and-test/e2e-test-instructions.md b/aidlc-docs/features/prerendering/construction/build-and-test/e2e-test-instructions.md new file mode 100644 index 0000000..3b398f5 --- /dev/null +++ b/aidlc-docs/features/prerendering/construction/build-and-test/e2e-test-instructions.md @@ -0,0 +1,32 @@ +# End-to-End Test Instructions + +Feature: prerendering. HEAD `39dc456`. + +## Purpose +The automated end-to-end suite is `pnpm e2e` (Chromium through Playwright, 12 files, 471 tests); its results and scenarios are in `integration-test-instructions.md`. This file covers what the suite cannot: browsers other than Chrome, and a person looking at the test site. Run it after the deploy-test job (done in run 598). + +## Environment +- **Target**: `https://test.andreaslop.nl` (deployed from commit `79b1a66`, run 598). +- **Browsers**: Firefox, Safari, Chrome on Android (the missing ones), plus desktop Chrome or Edge for a quick look. + +## Test Steps + +### 1. Menu without JavaScript (V-D4) - open, human task for the owner +Why: the menu works through `:target` links when JavaScript is off. Chrome keeps the scroll position when the menu opens (verified in the suite); other browsers may jump. +1. Turn JavaScript off in the browser (Firefox: `about:config`, `javascript.enabled` false; Safari: Develop menu; Chrome on Android: Site settings). +2. Open `https://test.andreaslop.nl/` on a narrow screen (mobile width) and open the menu. +3. Expected: the menu opens, the page does not jump to the top, the sub-links of "Soorten fotoshoots" are reachable, and the menu closes again. +4. Repeat on `/over-mij` and `/soorten-fotoshoots/newborn`. +5. Report the browser and what happened. Status in this stage: **not done** (needs a person). + +### 2. Pages look right with JavaScript on +Open `/`, `/over-mij`, `/portfolio`, `/soorten-fotoshoots`, one shoot page and `/contact`. Expected: no empty gaps where photos load, no flash of the light logo when navigating to `/` after the page has loaded, the contact form appears (it is revealed by a moved script), the e-mail address appears in the contact details after load. + +### 3. Pages are readable without JavaScript +With JavaScript off, every page above shows its text and photos; the contact form is not usable without JavaScript, which FR-PR-13 allows. + +### 4. URLs (spot check; curl already done in run 598) +In a browser: `/over-mij/` and `/Over-Mij` end up on `/over-mij`; `/bestaat-niet` shows the 404 page with the site layout. + +## Results in this stage +Steps 2 to 4 are covered by the automated suite and the main session's curl checks (see `integration-test-instructions.md`, scenario 7). Step 1 is the only open human check. diff --git a/aidlc-docs/features/prerendering/construction/build-and-test/integration-test-instructions.md b/aidlc-docs/features/prerendering/construction/build-and-test/integration-test-instructions.md new file mode 100644 index 0000000..6a7c15f --- /dev/null +++ b/aidlc-docs/features/prerendering/construction/build-and-test/integration-test-instructions.md @@ -0,0 +1,118 @@ +# Integration Test Instructions + +Feature: prerendering. HEAD `39dc456`; test results from CI run 599 on `2006fa0` and the test deployment of run 598 on `79b1a66`. + +## Purpose +Test the interactions between the three units: the start migration and script step (unit 1, produces `dist/client`), the display fallbacks (unit 2, what the HTML shows without or before JavaScript) and the hosting and targets (unit 3, the rules that serve the files and the scripts that upload and check them). Unit tests cannot show these: they need the real build output, a real browser, a real nginx and a real lftp. + +There is no service to start by hand. The browser suite (`pnpm e2e`) starts its own preview server and its own nginx, and cleans them up. In this stage no browser run was made locally; the results below are CI run 599. + +```mermaid +graph TD + U1["Unit 1: prerender and script step"] + U2["Unit 2: display fallbacks"] + U3["Unit 3: server rules and deploy scripts"] + DIST["dist/client: 12 HTML files and assets"] + PREV["Preview server"] + NGINX["Real nginx 1.24"] + LFTP["Real lftp 4.9.2"] + BROWSER["Chromium via Playwright"] + TESTHOST["test.andreaslop.nl"] + + U1 -->|"produces"| DIST + U2 -->|"changes HTML of"| DIST + U3 -->|"serves"| DIST + DIST --> PREV + DIST --> NGINX + DIST --> LFTP + PREV --> BROWSER + NGINX --> BROWSER + LFTP -->|"upload in CI run 598"| TESTHOST + + classDef service fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + classDef client fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + classDef gateway fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef external fill:#e9d5ff,stroke:#6b21a8,stroke-width:1px,color:#000; + classDef database fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000; + + class U1,U2,U3 service; + class BROWSER client; + class PREV,NGINX gateway; + class LFTP,TESTHOST external; + class DIST database; +``` + +Text alternative: units 1 to 3 all act on the build output `dist/client`, which the preview server, a real nginx and a real lftp consume; a Chromium browser tests the preview server and nginx, and lftp uploads to the test host. + +## Test Scenarios + +### Scenario 1: Unit 1 (prerendered HTML) โ†’ browser hydration +- **Description**: the prerendered HTML and the client entry must give a hydrated page without console messages or CSP violations, on every page and width, including the `404.html` case (React error #418 race found in unit 1). +- **Setup**: `pnpm build`. The suite starts `config/previewServer.ts`. +- **Test Steps**: Chromium opens every page (hydration at 390 px and other widths), waits for hydration, and records console output and CSP violations. +- **Expected Results**: no console message, no CSP violation, one title per page. +- **Files**: `e2e/hydration.e2e.ts` (48 tests), `e2e/interaction.e2e.ts` (12), `e2e/smoke.e2e.ts` (3). +- **Result (CI run 599)**: all passed. + +### Scenario 2: Unit 1 (script step) โ†’ raw HTML +- **Description**: the moved scripts must leave no inline executable script, no `on*=` attribute and no `javascript:` link, and the e-mail address must be in no output file. +- **Test Steps**: fetch the raw HTML of each page and scan it. +- **Expected Results**: none of the forbidden items; the CSP stays `script-src 'self'` plus Umami. +- **Files**: `e2e/rawHtml.e2e.ts` (14 tests). +- **Result (CI run 599)**: passed. + +### Scenario 3: Unit 1 + unit 2 โ†’ what shows without JavaScript and before hydration +- **Description**: with JavaScript off every page is visible, photos show through `