cloud-run-and-test-uap-timeline

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   # preferred in CI/agents; npm install also works

• 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):

1. Update this file in the same PR as the workflow change, or immediately after discovering repo-specific behavior worth repeating.
2. Prefer pointing at package.json scripts as the source of truth — duplicate only what agents need day one (command + one-line purpose).
3. Keep sections aligned with areas (src/, content/, scripts/, public/, CI) so the next agent can jump to the right subsection.
4. Mark optional vs required clearly (e.g. yt-dlp, LLM keys) to avoid unnecessary installs in restricted environments.