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>
2.4 KiB
2.4 KiB
name, description
| name | description |
|---|---|
| astro-page | 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:
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
cp .agents/templates/pages/chapter.astro src/pages/models.astro
Then, in order:
- Move markup into the layout + components. Reuse existing components before creating new ones.
- Move copy into
src/content/. Bothenandpt, copied literally — never retyped. - Move page CSS into component
<style>blocks. Do not portresponsive.csswholesale; take what this page needs and prove the rest dead. - Keep every
data-*hook.verify.mjsasserts many of them by name (data-phase,data-tree,data-route,data-model-provider, …). - 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
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.
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.