Marcos Paulo
580293867d
Deletes the pre-Astro pages, scripts, and stylesheets that the migration replaced, and moves the ones it did not replace out of the way. Deleted (32 files): app.js, responsive.css, landing.css, rules/app.js, rules/styles.css, skills/app.js, the ten route index.html files, and the root hands-on/ copy, which is byte-identical to public/hands-on/ -- the one the build actually ships. Moved to legacy/ (12 files): styles.css, full-guide/audit.css, chapters.css, skills/styles.css, skills-review/styles.css, skills-review/change-lens.css, and the skills-review/app.js module graph. These are not dead. The Astro pages import them and the build fails without them, which the plan had not accounted for. They go to legacy/ rather than src/ because check-tokens.mjs sweeps src, and these files are full of raw hex and unnamed breakpoints: moving one into src/ should mean migrating it to tokens in the same change, not adding a scan exclusion. The prettier, stylelint, and eslint ignore lists that already named these files at their old paths now name legacy/ instead. verify.mjs no longer reads app.js. The 102 Portuguese strings were extracted from its translations.pt object before deletion into .agents/snapshots/full-guide-pt.json -- a legacy capture, not a snapshot of the Astro build, so the assertion still compares against an independent source. The brace-matching helper's assertion is replaced by one that rejects an empty snapshot entry, without which trimming the snapshot would make the presence check pass vacuously. Count stays at 84. audit-ui.mjs reads the ten pages from dist/ and resolves Astro's base-absolute hrefs against it. Before deleting anything, rendered-text-diff was run across all ten routes plus both Portuguese pages: every one at parity, 0 missing and 0 extra. That comparison is not repeatable once the legacy files are gone. computed-style-diff on /full-guide/ stays at 32 differences, so the moves are style-neutral. Docs updated to match: README, AGENTS.md, GATES.md, the architecture context, the operations guide's lab instructions, and the three skills that told you to serve the vanilla site. Publishing is not part of this commit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
74 lines
2.4 KiB
Markdown
74 lines
2.4 KiB
Markdown
---
|
|
name: astro-page
|
|
description:
|
|
Migrate one hand-written HTML page of the ai-for-dummies site to an Astro
|
|
route without changing its URL, content, or JS budget. Use for any page-level
|
|
migration task.
|
|
---
|
|
|
|
# Migrating a page to Astro
|
|
|
|
## Snapshot first, migrate second
|
|
|
|
The snapshot is the only objective evidence that no content was lost.
|
|
|
|
The vanilla site was deleted at cutover. To compare against it, check the
|
|
pre-cutover tree out into a scratch worktree first:
|
|
|
|
```bash
|
|
git worktree add /tmp/vanilla <pre-cutover-sha>
|
|
(cd /tmp/vanilla && python3 -m http.server 4173) &
|
|
node .agents/scripts/snapshot-route.mjs http://localhost:4173/models/ \
|
|
> .agents/snapshots/models.txt
|
|
```
|
|
|
|
Screenshot the same route at 560 / 800 / 1100 / 1600 px as well.
|
|
|
|
## Migrate
|
|
|
|
```bash
|
|
cp .agents/templates/pages/chapter.astro src/pages/models.astro
|
|
```
|
|
|
|
Then, in order:
|
|
|
|
1. Move markup into the layout + components. Reuse existing components before
|
|
creating new ones.
|
|
2. Move copy into `src/content/`. Both `en` and `pt`, copied literally — never
|
|
retyped.
|
|
3. Move page CSS into component `<style>` blocks. Do **not** port
|
|
`responsive.css` wholesale; take what this page needs and prove the rest
|
|
dead.
|
|
4. Keep every `data-*` hook. `verify.mjs` asserts many of them by name
|
|
(`data-phase`, `data-tree`, `data-route`, `data-model-provider`, …).
|
|
5. Keep every ARIA attribute and the `<title>` / `<meta name="description">`.
|
|
|
|
## The URL must not change
|
|
|
|
Served from `/ai-for-dummies/`, so `base` is set in `astro.config.mjs`. Never
|
|
hand-write an internal absolute path; use `import.meta.env.BASE_URL`.
|
|
|
|
Trailing slashes matter. `/models/` must not become `/models`.
|
|
|
|
If the page honours query params (the review desk uses `?author=`, `?skill=`,
|
|
`?view=`, `?file=`, `?compare=`, `?render=`), they must still work — they are
|
|
documented in the page footer and shared externally.
|
|
|
|
## Prove it
|
|
|
|
```bash
|
|
pnpm run build
|
|
node .agents/scripts/snapshot-route.mjs dist/models/index.html > /tmp/after.txt
|
|
diff .agents/snapshots/models.txt /tmp/after.txt # empty, or justify every line
|
|
node scripts/audit-ui.mjs
|
|
pnpm run verify
|
|
```
|
|
|
|
Then screenshots at the same four widths, and
|
|
[`../../checklists/before-page.md`](../../checklists/before-page.md).
|
|
|
|
## JS budget
|
|
|
|
A page that shipped zero JS must still ship zero. Check the build output. If
|
|
your migration added a `client:load` to a static page, you did it wrong.
|