| name | cloud-run-and-test-uap-timeline |
| description | Run, validate, and manually test the ufo-website (UAP Timeline) Astro static site — setup, URLs, scripts, and area-specific workflows for Cloud agents. |
Cloud agents: run and test this codebase
Minimal runbook for ufo-website — an Astro static site (bilingual FR/EN) deployed to GitHub Pages.
Quick facts
- No login or accounts — there is nothing to authenticate against in this repo.
- No feature-flag system — toggling behavior means changing code or JSON under
content/, not env-based flags.
import.meta.env.BASE_URL comes from astro.config.mjs (base: '/uap_timeline'). Links and asset prefixes rely on it.
Setup
From the repository root:
npm ci
- Node:
.github/workflows/deploy.yml uses Node 22.
- Optional tooling for data scripts:
yt-dlp (pip install yt-dlp) when refreshing YouTube-derived JSON.
Start the app
npm run dev
| Item | Value |
|---|
| Dev server | http://localhost:4321 (Astro default) |
| First URL to open | http://localhost:4321/uap_timeline/ — base is /uap_timeline, so the app lives under that path, not at /. |
| English routes | Prefix with /en/ → e.g. http://localhost:4321/uap_timeline/en/timeline/ |
Aliases: npm run start runs the same as npm run dev.
Production-like run
npm run build
npm run preview
Use the same /uap_timeline/... paths when clicking through the preview server.
Automated checks
npx astro check
Runs Astro + TypeScript checks (project includes @astrojs/check). Use after touching .astro, src/**/*.ts, or checked scripts. There is no npm test script in package.json — browser/manual verification is the default.
If astro check reports pre-existing diagnostics, fix only what your task requires unless asked to clean the tree.
Environment variables (narrow scope)
| Variable | Where | Purpose |
|---|
| (none required for dev/build) | — | Normal local dev needs no .env. |
OPENAI_API_KEY / ANTHROPIC_API_KEY | scripts/generate-dird-analyses.js | Optional LLM generation for DIRD analyses — skip unless running that script. |
RSS/Sentinel refresh scripts use public URLs; no API key for normal npm run update-sentinel-news.
“Flags” and toggles (practical equivalents)
astro.config.mjs → base: Changes deployed path (/uap_timeline). Affects every import.meta.env.BASE_URL consumer.- Dev translation reload:
src/lib/content-loader.ts clears translation cache when import.meta.env.DEV is true — edit content/translations-en.json without restarting dev for EN overlay updates.
- Sentinel News live refresh:
sentinel-news pages optionally call https://api.rss2json.com from the browser to refresh the list. If the API is down or rate-limited, the page still renders from content/sentinel-news-feed.json (refresh locally with npm run update-sentinel-news).
By codebase area — what to run and how to test
1. Routes, layouts, components (src/pages/, src/layouts/, src/components/)
Run: npm run dev (and npx astro check after edits).
Test: Open the French URL and the mirrored /en/... route for the same feature. Smoke-test navigation, language switch, and any interactive widget on the touched page(s).
Examples — FR vs EN:
- Home:
/uap_timeline/ ↔ /uap_timeline/en/
- Timeline:
/uap_timeline/timeline/ ↔ /uap_timeline/en/timeline/
- People detail:
/uap_timeline/people/<id>/ ↔ /uap_timeline/en/people/<id>/
Use npm run build if you changed imports, props, or layout-wide dependencies.
2. Content & i18n (content/*.json, content/translations-en.json)
Run: Dev server; optionally npm run build to catch JSON syntax errors at build time.
Test: Edit data → reload the listing/detail pages that consume that file. For EN strings, verify /en/... after updating translations-en.json.
3. Client scripts & embedded <script> (timeline interactions, Sentinel UI, readers)
Run: npm run dev; exercise behavior in the browser.
Test: Interactions (sort, search inputs, optional live RSS refresh on Sentinel). Assume network may fail — confirm graceful fallback to static content where implemented.
4. Static assets (public/ — docs, audio, images, PDFs)
Run: npm run dev or npm run preview after build.
Test: Hit a few asset URLs under /uap_timeline/... (matches production base path). Large files: spot-check one representative link.
5. Data update scripts (scripts/)
When to use: Refreshing feeds or external lists — network-heavy; not required for ordinary UI fixes.
| Command | Purpose | Notes |
|---|
npm run update-all-data | YouTube tops, Congress list, Metabunk RSS, Sentinel RSS, etc. | Needs yt-dlp for YouTube-related steps; other parts still run if yt-dlp is missing (per script behavior / README). |
npm run update-sentinel-news | Sentinel RSS → content/sentinel-news-feed.json | Lighter than full update. |
npm run copy-docs, npm run sync-people-refs | Docs / cross-references | Run only when task touches those pipelines. |
npm run fetch-geipan-cas-d | GEIPAN data | Network-dependent. |
Test: Diff the generated JSON and load the corresponding pages; avoid committing accidental bulk refreshes unless the task requires updated fixtures.
6. CI / deploy alignment
Run: npm run build — must pass for Deploy to GitHub Pages (.github/workflows/deploy.yml).
Test: Compare local preview with expectations for static output; there is no server-side runtime in production.
Maintaining this skill
When you learn something new (new npm script, port change, env var, mock strategy, flaky external API, or test shortcut):
- Update this file in the same PR as the workflow change, or immediately after discovering repo-specific behavior worth repeating.
- Prefer pointing at
package.json scripts as the source of truth — duplicate only what agents need day one (command + one-line purpose).
- Keep sections aligned with areas (
src/, content/, scripts/, public/, CI) so the next agent can jump to the right subsection.
- Mark optional vs required clearly (e.g.
yt-dlp, LLM keys) to avoid unnecessary installs in restricted environments.
