diff --git a/docs/operations-guide.md b/docs/operations-guide.md index 19dde7a..8fae0cf 100644 --- a/docs/operations-guide.md +++ b/docs/operations-guide.md @@ -54,8 +54,8 @@ flowchart LR E[Edit main] --> V[pnpm run gate] V --> C[Commit] C --> P[Push main] - P --> G[Gitea Actions: gate + build] - G --> B[Force-push dist to pages] + P --> G[Gitea Actions: gate] + G -.manual dispatch.-> B[Build + force-push dist to pages] B --> S[Gitea Pages Server] S --> L[Live URL] ``` @@ -108,9 +108,16 @@ committing. ### 5. CI publication and its manual fallback -On a successful `main` push, Gitea Actions builds `dist/` and force-pushes it to -`pages`. This force-push is intentional: `pages` is machine-owned generated -output, and no person or other workflow may write it. +Gitea Actions builds `dist/` and force-pushes it to `pages`. This force-push is +intentional: `pages` is machine-owned generated output, and no person or other +workflow may write it. + +**For the duration of the Astro migration, publication is manual.** The +`publish` job runs only from a `workflow_dispatch` with its `publish` input set +to true — a push to `main` runs the gate and stops there. The reason: `dist/` +currently holds three HTML files (`/summary/` plus the two `hands-on/` fixtures) +against the ten pages the live branch serves, so publishing on every push would +take the site down to a stub. Task 20 (cutover) makes it automatic again. This Gitea's act-runner registration is kept in an `emptyDir`. A pod restart silently removes the registration; if a site does not update, check and @@ -135,7 +142,7 @@ git worktree remove /tmp/ai-for-dummies-pages ```bash curl -sS -o /dev/null -w '%{http_code}\n' \ - "https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/summary/?v=$(git rev-parse --short HEAD)" + "https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/summary/" ``` Also check a nested static asset; base-path problems usually appear on assets @@ -143,9 +150,17 @@ first: ```bash curl -sS -o /dev/null -w '%{http_code}\n' \ - "https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/hands-on/starter/?v=$(git rev-parse --short HEAD)" + "https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/hands-on/starter/" ``` +**The Pages Server caches for ten minutes** (`x-pages-cache: true`, +`cache-control: public, max-age=600`), and the cache is keyed on the _path_. A +`?v=$(git rev-parse …)` query string does **not** bust it — that idiom used to +be in this guide and it never worked. After a publish, a URL can keep serving +the previous content, or keep serving a file you just deleted, for up to ten +minutes. Budget for that before concluding a deploy failed. Check +`last-modified` and `etag` with `curl -I` to tell fresh from cached. + The correct URL pattern is **owner subdomain + repository path**: ```text diff --git a/plans/astro-refactor/HANDOVER.md b/plans/astro-refactor/HANDOVER.md index 5160b4f..45132a3 100644 --- a/plans/astro-refactor/HANDOVER.md +++ b/plans/astro-refactor/HANDOVER.md @@ -78,10 +78,11 @@ tasks 05 and 06. ## Still open from task 01's own report -- Real-host smoke test of `/ai-for-dummies/summary/` never ran — the branch is - not merged and CI has not published. **This is the #1 production-only failure - mode in the whole migration.** Do it before trusting any page work. -- No Playwright locally, so screenshot comparison could not run in CI. +- ~~Real-host smoke test of `/ai-for-dummies/summary/`~~ — **done**, see + "Resolved: the base path serves correctly on the real host" above. +- No Playwright locally, so screenshot comparison still cannot run anywhere. + `visual-regression.mjs` also has no compare mode, so it is out of CI until it + grows one. See `.agents/rules/gates.md`. ## The decision that is still yours @@ -94,24 +95,44 @@ external-CSS assertion. See `.agents/context/design-system.md`. ## Next steps, in order -1. **Decide the font question** (see below). It blocks task 19 and it is the +1. **Decide the font question** (see below). It blocks task 19 and it is now the only thing here that needs a human. -2. Push `main` — nothing has left this machine yet. Safe now: the `publish` job - is `workflow_dispatch`-only, so pushing no longer overwrites the live site. - Watch that first CI run; the act-runner has never executed a job. -3. Once CI is green, do the real-host smoke test of `/ai-for-dummies/summary/`. - **This is still the #1 production-only failure mode in the migration** and it - has not been done. Publish manually via the workflow's `publish` input, on a - throwaway basis, or accept the risk until task 20. -4. Clean up the four merged worktrees and branches. -5. Fan out phase 1 and 2: +2. Fan out phase 1 and 2: ```bash .agents/scripts/launch.sh 05 content-guide --base main .agents/scripts/launch.sh 06 content-review --base main .agents/scripts/launch.sh 07 primitives --base main ``` All three are unblocked now that 02 and 04 are in `main`. After 07 lands, - 08–11 run four at a time. + 08-11 run four at a time. **Task 07 is the routing calibration point** - + judge it before committing to MiniMax for the other twelve. +3. Clean up the four merged worktrees and branches in `~/Projects/af-task-0*`. + `~/Projects/af-task-02/before/` holds 29 MB of misplaced untracked + screenshots; delete or move them first. + +## Resolved: the base path serves correctly on the real host + +This was the #1 production-only failure mode and it is now **verified against +the live Pages Server**, not just `pnpm run preview`. + +Method, which is reusable and costs no downtime: the Astro `dist/` was published +to the `pages` branch **additively** — `_astro/` plus a single page at +`_verify/summary/`, both paths previously unused, so no existing file was +touched and all ten live pages stayed up throughout. Results: + +- `/ai-for-dummies/_verify/summary/` → 200, and it really is the Astro page + (`AI For Dummies — Route map`), not a 200-ing error page. +- `/ai-for-dummies/_astro/chapters.PwjFDHFw.css` → 200 `text/css`. **This is the + actual base-path proof**: Astro emits base-prefixed _absolute_ asset URLs, and + the server resolves them. +- `/ai-for-dummies/_verify/summary` (no trailing slash) → 307 to the slashed + form, which matches `trailingSlash: 'always'`. + +The probe was force-pushed away immediately; `pages` is back at `37a1e48`. + +Note for whoever publishes next: **the Pages Server caches for ten minutes**, +keyed on path. A deleted file keeps serving 200 until the cache expires, and a +`?v=` query does not bust it. See `docs/operations-guide.md` step 6. ## Carried over from the phase 0 review