feat: scaffold Astro + Vue migration (phases 0-1)

.github/workflows/a11y-scan.yml

@@ -25,6 +25,8 @@ jobs:
 
       - run: npm ci
 
+      - run: npm run sync
+
       - run: npm run build
 
       - uses: actions/cache@v6

.github/workflows/add-discussion-url.yml

@@ -102,8 +102,8 @@ jobs:
           DISCUSSION_URL: ${{ inputs.discussion_url }}
         run: node scripts/set-discussion-url.mjs
 
-      - name: Regenerate TypeScript
-        run: node scripts/generate-adventures.mjs
+      - name: Validate adventure YAML (Zod content schema)
+        run: npm run sync
 
       - name: Create pull request
         env:
@@ -125,9 +125,6 @@ jobs:
           git add \
             "src/data/adventures/${ADVENTURE_ID}/adventure.yaml" \
             "src/data/adventures/${ADVENTURE_ID}/${LEVEL_ID}-posts.json" \
-            "src/data/adventures/${ADVENTURE_ID}.generated.ts" \
-            "src/data/adventures/index.ts" \
-            "src/data/adventures/summaries.ts" \
             "scripts/refresh-leaderboard.mjs"
 
           HAS_CHANGES=false
@@ -154,8 +151,8 @@ jobs:
 
           - \`adventure.yaml\` — \`community_url\` set on the \`${LEVEL_ID}\` level; \`community_category_id\` set at adventure root if it was missing
           - \`${LEVEL_ID}-posts.json\` — \`discussionUrl\` set and initial posts fetched from Discourse
-          - Generated TypeScript updated (\`${ADVENTURE_ID}.generated.ts\`, \`index.ts\`, \`summaries.ts\`)
           - \`scripts/refresh-leaderboard.mjs\` — \`ADVENTURE_CATEGORIES\` patched with the resolved category ID
+          - (Astro reads the YAML directly — no generated TypeScript to update)
 
           ### Before merging
 

.github/workflows/deploy.yml

@@ -29,17 +29,27 @@ jobs:
           node-version-file: .nvmrc
           cache: npm
 
-      - run: npm ci
+      - uses: actions/cache@v6
+        id: npm-cache
+        with:
+          path: node_modules
+          key: node-modules-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
 
-      - run: npm run build
+      - if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci
 
-      - run: cp dist/client/404/index.html dist/client/404.html
+      - run: npm run sync
+      - run: npm run lint
+
+      # Astro static build → dist/ (not dist/client/). Astro emits dist/404.html
+      # natively, so the old `cp .../404/index.html 404.html` step is gone.
+      - run: npm run build
 
       - name: Deploy to gh-pages
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           branch: gh-pages
-          folder: dist/client
+          folder: dist
           force: false
           clean: true
           clean-exclude: |

.github/workflows/preview.yml

@@ -12,7 +12,7 @@ env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
-  lint:
+  check:
     if: github.event.action != 'closed'
     runs-on: ubuntu-latest
     steps:
@@ -32,6 +32,9 @@ jobs:
       - if: steps.node-cache.outputs.cache-hit != 'true'
         run: npm ci
 
+      # Content validation gate: astro sync runs the Zod collection schema and
+      # fails on invalid adventure YAML.
+      - run: npm run sync
       - run: npm run lint
 
   build:
@@ -56,12 +59,10 @@ jobs:
 
       - run: npm run build
 
-      - run: npm test
-
       - uses: actions/upload-artifact@v7
         with:
-          name: dist-client
-          path: dist/client/
+          name: dist
+          path: dist/
           retention-days: 1
 
   e2e:
@@ -91,8 +92,8 @@ jobs:
 
       - uses: actions/download-artifact@v7
         with:
-          name: dist-client
-          path: dist/client/
+          name: dist
+          path: dist/
 
       - uses: actions/cache@v6
         id: playwright-cache
@@ -106,13 +107,12 @@ jobs:
       - if: steps.playwright-cache.outputs.cache-hit == 'true'
         run: npx playwright install-deps chromium
 
+      # playwright.config webServer runs `astro preview` (serves dist/) itself.
       - run: npm run test:e2e -- --shard=${{ matrix.shard }}/3
 
   preview:
-    needs: [lint, e2e]
-    # Run when both passed (normal PR update), or when build was skipped (PR closed, cleanup).
-    # Never run when tests failed.
-    if: always() && ((needs.lint.result == 'success' && needs.e2e.result == 'success') || needs.lint.result == 'skipped')
+    needs: [check, e2e]
+    if: always() && ((needs.check.result == 'success' && needs.e2e.result == 'success') || needs.check.result == 'skipped')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
@@ -132,27 +132,15 @@ jobs:
       - if: github.event.action != 'closed' && steps.node-cache.outputs.cache-hit != 'true'
         run: npm ci
 
+      # Astro's `base` (from VITE_BASE_PATH) prefixes every asset/link, and public/
+      # assets are copied into dist/ automatically — so the whole dist/ deploys as
+      # the preview with no per-directory asset-copy step. Layout.astro marks
+      # /pr-preview/ builds noindex.
       - if: github.event.action != 'closed'
-        run: VITE_BASE_PATH=/pr-preview/pr-${{ github.event.number }}/ npm run build
-
-      - if: github.event.action != 'closed'
-        run: |
-          PREVIEW_DIR="dist/client/pr-preview/pr-${{ github.event.number }}"
-          cp -r dist/client/assets "${PREVIEW_DIR}/"
-          cp -r dist/client/fonts "${PREVIEW_DIR}/"
-          cp -r dist/client/reveal "${PREVIEW_DIR}/"
-          cp -r dist/client/team "${PREVIEW_DIR}/"
-          cp -r dist/client/speakers "${PREVIEW_DIR}/"
-          cp -r dist/client/brand "${PREVIEW_DIR}/"
-          cp -r dist/client/solutions "${PREVIEW_DIR}/"
-          cp -r dist/client/qr "${PREVIEW_DIR}/"
-          cp -r dist/client/downloads "${PREVIEW_DIR}/"
-          cp -r dist/client/screenshots "${PREVIEW_DIR}/"
-          cp -r dist/client/deck "${PREVIEW_DIR}/"
-          cp -r dist/client/deck-template "${PREVIEW_DIR}/"
-          find dist/client -maxdepth 1 -type f \( -name "*.svg" -o -name "*.png" -o -name "*.ico" -o -name "*.webmanifest" -o -name "*.webp" \) -exec cp {} "${PREVIEW_DIR}/" \;
-          cp "${PREVIEW_DIR}/index.html" "${PREVIEW_DIR}/404.html"
+        env:
+          PR_NUMBER: ${{ github.event.number }}
+        run: VITE_BASE_PATH=/pr-preview/pr-${PR_NUMBER}/ npm run build
 
       - uses: rossjrw/pr-preview-action@v1
         with:
-          source-dir: dist/client/pr-preview/pr-${{ github.event.number }}/
+          source-dir: dist/

.github/workflows/sync-adventure.yml

@@ -5,7 +5,7 @@ on:
     inputs:
       adventure_url:
         description: >
-          GitHub URL of the adventure folder in the challenges repo — any branch works.
+          GitHub URL of the adventure folder in the challenges repo (any branch works).
           main: https://github.com/off-on-dev/open-source-challenges/tree/main/adventures/05-lex-imperfecta
           PR branch: https://github.com/off-on-dev/open-source-challenges/tree/feat/my-branch/adventures/05-lex-imperfecta
         required: true
@@ -73,7 +73,7 @@ jobs:
             if git show "origin/$BRANCH:${YAML_PATH}" > /tmp/pr-adventure.yaml 2>/dev/null && [ -s /tmp/pr-adventure.yaml ]; then
               mkdir -p "src/data/adventures/${SLUG}"
               cp /tmp/pr-adventure.yaml "$YAML_PATH"
-              echo "Restored adventure.yaml from PR branch ${BRANCH} — manual edits (discussion_url, topics, architecture_diagram, diagram_alt, deadline) will be preserved by sync-adventure.mjs"
+              echo "Restored adventure.yaml from PR branch ${BRANCH}; manual edits (discussion_url, topics, architecture_diagram, diagram_alt, deadline) will be preserved by sync-adventure.mjs"
             else
               echo "PR branch ${BRANCH} exists but has no adventure.yaml yet — starting fresh from main"
             fi
@@ -88,14 +88,15 @@ jobs:
           LEVELS_TO_SYNC: ${{ inputs.levels }}
         run: node scripts/sync-adventure.mjs
 
-      - name: Validate and regenerate TypeScript
-        run: node scripts/generate-adventures.mjs
+      - name: Validate adventure YAML (Zod content schema)
+        run: npm run sync
 
       - name: Create pull request
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
           ADVENTURE_URL: ${{ inputs.adventure_url }}
         run: |
+          set -euo pipefail
           SLUG=$(cat /tmp/adventure-slug)
           NAME=$(cat /tmp/adventure-name)
           LEVELS=$(cat /tmp/adventure-levels)
@@ -112,27 +113,21 @@ jobs:
           git fetch origin "$BRANCH" 2>/dev/null || true
 
           git checkout -b "$BRANCH" 2>/dev/null || git checkout "$BRANCH"
+          # Astro reads the YAML directly (Zod content collection) — no generated
+          # TS, prerender array, or sitemap region to commit. Routes come from
+          # getStaticPaths at build time.
           git add \
             src/data/adventures/${SLUG}/ \
-            src/data/adventures/${SLUG}.generated.ts \
-            src/data/adventures/index.ts \
-            src/data/adventures/summaries.ts \
-            src/data/adventures/types.ts \
             src/assets/diagrams/ \
-            public/sitemap.xml \
-            react-router.config.ts \
-            scripts/refresh-leaderboard.mjs \
-            e2e/smoke.spec.ts \
-            src/test/seo.test.ts \
-            src/test/prerender.test.ts
+            scripts/refresh-leaderboard.mjs
           git commit -m "feat: sync adventure ${SLUG} from challenges repo (${MODE})"
 
           # The branch is owned by this workflow, so a plain --force is safe here and
           # avoids the "stale info" failure mode of --force-with-lease without a ref.
           git push --force origin "$BRANCH"
 
           if [ "$MODE" = "update" ]; then
-            PR_TITLE="feat(adventure): add levels to ${NAME} — ${LEVELS}"
+            PR_TITLE="feat(adventure): add levels to ${NAME}: ${LEVELS}"
           else
             PR_TITLE="feat(adventure): add ${NAME}"
           fi
@@ -157,23 +152,18 @@ jobs:
 
           ### Manual steps (only if needed)
 
-          - [ ] If a level's \`architecture_diagram\` SVG was not auto-fetched (check the sync logs for a warning), add the SVG manually to \`src/assets/diagrams/\` and add \`architecture_diagram: <file>.svg\` to that level in \`adventure.yaml\`, then run \`npm run generate\`
-          - [ ] If a level has an \`architecture_diagram\` but no \`diagram_alt\`, add \`diagram_alt:\` to that level in \`adventure.yaml\` with a one-sentence description of the diagram, then run \`npm run generate\`
-          - [ ] Run \`node scripts/refresh-discussions.mjs\` after \`discussionUrl\` values are set
+          - [ ] If a level's \`architecture_diagram\` SVG was not auto-fetched (check the sync logs for a warning), add the SVG manually to \`src/assets/diagrams/\` and add \`architecture_diagram: <file>.svg\` to that level in \`adventure.yaml\`          - [ ] If a level has an \`architecture_diagram\` but no \`diagram_alt\`, add \`diagram_alt:\` to that level in \`adventure.yaml\` with a one-sentence description of the diagram          - [ ] Run \`node scripts/refresh-discussions.mjs\` after \`discussionUrl\` values are set
 
-          ### Auto-generated (do not edit by hand)
+          ### Routes & sitemap
 
-          The following are kept in sync with \`adventure.yaml\` by \`npm run generate\` (prebuild hook):
-          - \`public/sitemap.xml\` (GENERATED:adventures region)
-          - \`react-router.config.ts\` prerender (GENERATED:adventures region)
-          - \`e2e/smoke.spec.ts\` and \`src/test/seo.test.ts\` route arrays
-          - \`src/test/prerender.test.ts\` pages array
-          - \`scripts/refresh-leaderboard.mjs\` ADVENTURE_CATEGORIES
+          Routes are generated from \`adventure.yaml\` by the Astro content collection
+          at build time (\`getStaticPaths\`) — there is nothing to regenerate or commit.
+          Only \`scripts/refresh-leaderboard.mjs\` ADVENTURE_CATEGORIES is hand-maintained.
 
           ### Checks
 
           \`\`\`sh
-          npm run lint && npm test && npm run build && npm run test:e2e
+          npm run sync && npm run build && npm run test:e2e
           \`\`\`
           EOF
           else
@@ -198,32 +188,26 @@ jobs:
               about: "One sentence bio."
             \`\`\`
           - [ ] Confirm \`month:\` is correct for the planned release
-          - [ ] Set \`community_category_id:\` in \`src/data/adventures/${SLUG}/adventure.yaml\` (look up at https://community.offon.dev/categories.json), then run \`npm run generate\`
-          - [ ] Update \`rewards.deadline:\` from \`TODO\` to ISO 8601 (e.g. \`2026-07-01T23:59:00+01:00\`)
+          - [ ] Set \`community_category_id:\` in \`src/data/adventures/${SLUG}/adventure.yaml\` (look up at https://community.offon.dev/categories.json)          - [ ] Update \`rewards.deadline:\` from \`TODO\` to ISO 8601 (e.g. \`2026-07-01T23:59:00+01:00\`)
           - [ ] Review \`topics:\` on each level, auto-set to all adventure tags, refine to level-specific subset if needed
           - [ ] Update \`discussion_url:\` in each level once the Discourse threads are created
           - [ ] Update \`discussionUrl\` in each \`*-posts.json\` stub
 
           ### Manual steps (only if needed)
 
-          - [ ] If a level's \`architecture_diagram\` SVG was not auto-fetched (check the sync logs for a warning), add the SVG manually to \`src/assets/diagrams/\` and add \`architecture_diagram: <file>.svg\` to that level in \`adventure.yaml\`, then run \`npm run generate\`
-          - [ ] If a level has an \`architecture_diagram\` but no \`diagram_alt\`, add \`diagram_alt:\` to that level in \`adventure.yaml\` with a one-sentence description of the diagram, then run \`npm run generate\`
-          - [ ] Run \`node scripts/refresh-leaderboard.mjs\` after \`community_category_id\` is set
+          - [ ] If a level's \`architecture_diagram\` SVG was not auto-fetched (check the sync logs for a warning), add the SVG manually to \`src/assets/diagrams/\` and add \`architecture_diagram: <file>.svg\` to that level in \`adventure.yaml\`          - [ ] If a level has an \`architecture_diagram\` but no \`diagram_alt\`, add \`diagram_alt:\` to that level in \`adventure.yaml\` with a one-sentence description of the diagram          - [ ] Run \`node scripts/refresh-leaderboard.mjs\` after \`community_category_id\` is set
           - [ ] Run \`node scripts/refresh-discussions.mjs\` after \`discussionUrl\` values are set
 
-          ### Auto-generated (do not edit by hand)
+          ### Routes & sitemap
 
-          The following are kept in sync with \`adventure.yaml\` by \`npm run generate\` (prebuild hook):
-          - \`public/sitemap.xml\` (GENERATED:adventures region)
-          - \`react-router.config.ts\` prerender (GENERATED:adventures region)
-          - \`e2e/smoke.spec.ts\` and \`src/test/seo.test.ts\` route arrays
-          - \`src/test/prerender.test.ts\` pages array
-          - \`scripts/refresh-leaderboard.mjs\` ADVENTURE_CATEGORIES
+          Routes are generated from \`adventure.yaml\` by the Astro content collection
+          at build time (\`getStaticPaths\`) — there is nothing to regenerate or commit.
+          Only \`scripts/refresh-leaderboard.mjs\` ADVENTURE_CATEGORIES is hand-maintained.
 
           ### Checks
 
           \`\`\`sh
-          npm run lint && npm test && npm run build && npm run test:e2e
+          npm run sync && npm run build && npm run test:e2e
           \`\`\`
           EOF
           fi