Christmas TV archive (Vánoční program)

A single-page app for browsing the Czech Christmas TV schedule of ČT1, ČT2, Nova and Prima on 24, 25 and 26 December across the years. The release ships the finished data set in data/program.json; show metadata and links come from ČSFD (cached in data/csfd-cache.json).

Live: https://vanocni-program.tomlabs.xyz · health: https://vanocni-program.tomlabs.xyz/health

Layout

Running locally

npm run dev

The site runs on http://127.0.0.1:8132/. The version shown in the footer comes from package.json and is injected by the server.

Rebuilding the data

npm run prepare:release

Builds the archive from the local sources (data/sources, not committed), applies the stored ČSFD cache, validates the data set and checks the JavaScript. New ČSFD metadata is fetched separately with npm run enrich:csfd.

ČSFD posters

npm run enrich:csfd looks up every title that is a film or may be one (type film, děti or untyped) that is not in data/csfd-cache.json yet, through the ČSFD API wrapper at csfd-api.tomlabs.xyz. It is polite by design: about one request per second (--delay), a descriptive User-Agent, every result cached (also misses, so a title is never asked twice), the cache saved every 10 titles and on Ctrl+C, so the run can be stopped and resumed. Matches that are not a film or TV film are recorded as not_film and skipped. npm run apply:csfd writes the cache into program.json. npm run validate:data prints the picture coverage. Posters are hotlinked from ČSFD, never copied into the repository.

Adding the current year

Requires Node 22+, Windows PowerShell, and Python 3 with lxml (python -m pip install lxml). npm test and npm run check also run the offline Python fixture tests (on Linux: python3 with lxml). Start from a clean working tree with the committed archive and ČSFD cache. Each December run:

npm run update:year                 # defaults to the current year
npm test
npm run check
git diff --stat
git diff -- data/program.json data/csfd-cache.json

The command downloads only 24–26 December of that year from Česká televize (ČT1, ČT2) and Program.sk (Nova, Prima), at the existing 150 ms pause between source requests. All six pages must identify the requested date and contain full-day coverage for all four channels: at least eight shows per channel/day, a morning start by 09:00, a late-evening start at or after 21:00, a prime-time start between 18:00 and 22:00, and no gap over six hours. Invalid times or duplicate show IDs also stop the update. These conservative guards catch empty and truncated pages; they cannot certify the broadcaster's editorial completeness.

If the schedule is not published yet, or a page is partial, the command exits with code 1 and reports each affected channel/day. The archive, source cache and ČSFD cache stay unchanged. Retry when the broadcasters publish the missing days (usually a few weeks before Christmas). Other HTTP/network errors also fail without publishing staged files.

After the checks, only previously uncached film-like titles are looked up through the existing ČSFD matcher, with its one-second delay and retry policy. Existing cache entries, including misses and errors, are preserved. The cache is applied only to the selected year. The merged archive is validated before sources, new cache entries and data are replaced locally. An interrupted lookup or validation failure leaves the published files unchanged; lookups staged in that failed attempt will need repeating. An interrupted process may leave data/.update-year.lock; remove it only after confirming no update is running.

Re-run the command to pick up schedule corrections until broadcast. The UI labels that year's programme preliminary until 27 December. An unchanged parsed/enriched programme retains its original provenance and timestamp, even when advertising markup changes the HTML size. Other years are preserved, including the legacy Christmas Eve snapshot. Explicit years from 2023 through the current year are supported:

npm run update:year -- -Year 2025

Review the diff, update the release version and changelog as appropriate, and commit locally. Have the Software Architect review and merge; push and deployment still require Tomáš's explicit approval. Do not run prepare:release as part of this routine: it rebuilds all historical years and needs their local sources. The full source fetch keeps its previous-year default; an explicit range can include the current year:

npm run fetch:sources -- -StartYear 2026 -EndYear 2026

See ADR 0005 for the staging and replacement decision.

Configuration

Health

GET /health answers { "status": "Healthy", "version": "0.9.0", "name": "vanocni-program", "entries": { … } }. archive is Unhealthy when data/program.json cannot be loaded; log is Degraded when log files cannot be written.

Deployment

azure-pipelines.yml checks the code and data, builds the Docker image, smoke-tests it and on master ships the image to the VPS, where deploy/deploy-vps.sh swaps the container, waits for /health (rolling back when the new build is not healthy) and installs the nginx site. After a successful deploy the pipeline updates the catalogue entry on https://apps.tomlabs.cz.

• Variable group vanocni-program-deployment: VPS_SSH_PRIVATE_KEY_B64 or VPS_SSH_PRIVATE_KEY.
• Variable group appstore-publish: APPSTORE_TOKEN.
• On the VPS, /opt/vanocni-program/.env holds ADMIN_PASSWORD; logs are in /opt/vanocni-program/logs.

Release: bump version in package.json and add its section to CHANGELOG.md in the same commit.