feat: catalog api

[sorodrigo]

feat: convention-driven catalog API (replaces /meta)

Summary

Replaces the hand-curated metadata layer with a convention-driven catalog derived from ixmp4 variable names, served by a new Hono/Cloudflare-Workers + D1 API in api/. The old /meta god-endpoint is gone — the catalog is split into cost-scoped slices (/geographies, /catalog, curation) that load only on the pages that use them.

What changed

API (api/) — four layers, edges-do-I/O, core-is-pure:

• routes/* thin HTTP adapters → views/* per-chart resolvers (impact-time, scenarios, unavoidable-risk) → conventions.ts/tabulate.ts/util.ts (pure language) → platform.ts/instances.ts (ixmp4 connection).
• Geographies come from D1 (Drizzle); indicators + scenarios are derived live from the ixmp4 variable-name convention (Indicator | Period | Temporal | Spatial | Value) — no curation.

Endpoints (no more /meta):

• /geographies (+ /geographies/types) — selectable place tree (D1, cheap)
• /catalog — indicators + parameter dimensions + scenario universe (the expensive ixmp4 scan)
• /study-locations, /likelihoods — transitional curation
• /impact-time, /scenarios, /indicators, /tags, /unavoidable-risk (stub)

Frontend — the data slices load per section (impacts, adaptation, methodology/key-terms, embed, and the landing quick-start), not on the global layout, so static pages no longer pay for the ixmp4 scan. Stores read $page.data.geographies / .catalog / .curation via loadGeographies / loadCatalog / loadCuration.

DB migrations — adds 0002_past_blink.sql (geo_id column on geographies, ISO3 for countries) bridging the name-based catalog to map geo-shapes. Local + remote provide-catalog D1 have been migrated through 0002 and reseeded.

Running locally

Prereqs: Node, Bun, and Wrangler (npm i -g wrangler or via npx). Then npm install.

1. Environment files

cp .env.example .env            # frontend (Vite) vars — see table below
cp .dev.vars.example .dev.vars  # API secrets (ixmp4 creds)

2. Set up the local D1 (new — required)

npm run db:migrate   # applies 0000→0002 to local provide-catalog (creates geo_id column)
npm run db:seed      # imports geographies + ISO3 geoIds, then loads api/db/seed.sql

3. Run the API (pick one)

• Workers runtime (recommended, matches prod): npm run dev:api → Wrangler on :8787, local D1. Set VITE_API_URL=http://localhost:8787/api.
• Bun runtime: npm run dev:api:node → server.ts on :8080 (uses bun:sqlite, auto-applies migrations on boot, reads .dev.vars). Set VITE_API_URL=http://localhost:8080/api.

4. Run the frontend

npm run dev          # Vite (mode=staging) on :5173

5. Tests

npm test             # bun test api/  (routes + pure view/convention functions)
npx svelte-check     # frontend type/markup check

Environment variables

Frontend (.env)

Var	Purpose
VITE_API_URL	New catalog API base — point at the runtime you chose (http://localhost:8787/api for Wrangler, :8080 for Bun). What the catalog/geographies/scenarios calls hit.
VITE_DATA_API_URL	Legacy Climate Analytics API (impact-time, unavoidable-risk, geo-shape, avoiding-*) — still used.
VITE_HEROKU_URL	Strapi CMS base (editorial indicator/scenario descriptions).
VITE_STRAPI_LOCALE	Strapi content locale (en).
VITE_MAPBOX_STYLE_*, VITE_APP_URL	Mapbox styles / app URL for the map + embed views (set if exercising maps).

API secrets (.dev.vars) — consumed by the Worker / server.ts

Var	Purpose
IXMP4_USERNAME / IXMP4_PASSWORD	Credentials for the ixmp4 provide-internal instance the catalog reads from.

The D1 binding (provide-catalog, binding: DB) lives in wrangler.jsonc; migrations_dir is ./api/db/migrations.

Notes / follow-ups

• unavoidable-risk is a stub (ensemble data not yet on provide-internal); GMT band is an interim reuse of the chart's own region (no World region in ixmp4 yet).
• Landing-page stories/caseStudies resolution is dead/legacy and slated for a separate cleanup.