@gjsify/site 0.0.0-stage → 0.62.0

package/lib/site-data/load.js

@@ -0,0 +1,164 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { parseSiteConfig } from './config.js';
+import { buildDownloadTargets } from './downloads.js';
+import { fetchFlathubStats, fetchFlathubSummary } from './flathub.js';
+import { fetchLatestRelease } from './github.js';
+import { parseMetainfo } from './metainfo.js';
+import { minimumAge } from './oars.js';
+import { completeLocalized, languageCandidates, parseCatalog } from './po.js';
+import { resolveScreenshots } from './screenshots.js';
+/** Reads `<dir>/<lang>.po` for every language, trying `pt-BR` and `pt_BR` spellings; missing files are skipped. */
+export async function loadCatalogs(dir, languages) {
+    const catalogs = {};
+    for (const language of languages) {
+        for (const candidate of languageCandidates(language)) {
+            const file = join(dir, `${candidate}.po`);
+            if (existsSync(file)) {
+                catalogs[language] = parseCatalog(await readFile(file, 'utf8'));
+                break;
+            }
+        }
+    }
+    return catalogs;
+}
+/**
+ * The page's own strings are always translated; the app's text only when the metainfo or a
+ * catalogue brings a translation. Say so once per language instead of silently showing English.
+ */
+function warnMissingTranslations(config, metainfo, complete, warn) {
+    const texts = [
+        metainfo.name,
+        metainfo.summary,
+        ...metainfo.description.flatMap((block) => (block.type === 'paragraph' ? [block.text] : block.items)),
+    ];
+    for (const language of config.languages) {
+        if (language === config.sourceLanguage)
+            continue;
+        const missing = texts.filter((text) => complete(text).byLanguage[language] === undefined).length;
+        if (missing > 0) {
+            const hint = config.translations
+                ? ''
+                : ' (set "gjsify.site.translations" to a directory of .po catalogues)';
+            warn(`${missing} of ${texts.length} app texts have no "${language}" translation and show the source text${hint}`);
+        }
+    }
+}
+/** Collects everything the pages need into one object. Network failures degrade to warnings. */
+export async function loadSiteData(options) {
+    const warnings = [];
+    const warn = (message) => {
+        warnings.push(message);
+        options.warn?.(message);
+    };
+    const manifest = JSON.parse(await readFile(join(options.root, 'package.json'), 'utf8'));
+    const config = parseSiteConfig(manifest);
+    const version = manifest.version ?? '';
+    const metainfoPath = resolve(options.root, config.metainfo);
+    if (!existsSync(metainfoPath))
+        throw new Error(`gjsify.site.metainfo points to "${config.metainfo}", which does not exist`);
+    const metainfo = parseMetainfo(await readFile(metainfoPath, 'utf8'));
+    const appCatalogs = config.translations
+        ? await loadCatalogs(resolve(options.root, config.translations), config.languages)
+        : {};
+    const complete = (text) => completeLocalized(text, config.languages, config.sourceLanguage, appCatalogs);
+    const completeBlocks = (blocks) => blocks.map((block) => block.type === 'paragraph'
+        ? { type: 'paragraph', text: complete(block.text) }
+        : { type: 'list', items: block.items.map(complete) });
+    warnMissingTranslations(config, metainfo, complete, warn);
+    const screenshots = (await resolveScreenshots(metainfo, {
+        root: options.root,
+        repository: config.repository,
+        cacheDir: options.screenshotCacheDir,
+        offline: options.offline,
+        network: options.network,
+        warn,
+    })).map((screenshot) => ({
+        ...screenshot,
+        caption: screenshot.caption ? complete(screenshot.caption) : null,
+    }));
+    const icon = config.icon ?? manifest.gjsify?.flatpak?.icon ?? manifest.gjsify?.ship?.icon;
+    if (icon && !existsSync(resolve(options.root, icon)))
+        throw new Error(`The app icon "${icon}" does not exist`);
+    let latestRelease = null;
+    let hasReleases = true;
+    let flathubSize;
+    const stats = {};
+    if (!options.offline) {
+        const network = options.network ?? {};
+        const [release, flathub, summary] = await Promise.allSettled([
+            fetchLatestRelease(config.repository, options.githubToken, network),
+            config.flathub ? fetchFlathubStats(config.flathub, network) : Promise.resolve(undefined),
+            config.flathub ? fetchFlathubSummary(config.flathub, network) : Promise.resolve(undefined),
+        ]);
+        if (release.status === 'fulfilled') {
+            latestRelease = release.value;
+            hasReleases = latestRelease !== null;
+            if (latestRelease) {
+                stats.githubDownloads = latestRelease.assets.reduce((sum, asset) => sum + asset.downloadCount, 0);
+            }
+        }
+        else {
+            warn(`Could not fetch the latest GitHub release (${String(release.reason)}); linking to the releases page instead`);
+        }
+        if (flathub.status === 'fulfilled' && flathub.value) {
+            stats.flathubInstalls = flathub.value.installsTotal;
+            stats.flathubInstallsLastMonth = flathub.value.installsLastMonth;
+        }
+        else if (flathub.status === 'rejected') {
+            warn(`Could not fetch Flathub statistics (${String(flathub.reason)}); omitting install counts`);
+        }
+        if (summary.status === 'fulfilled') {
+            flathubSize = summary.value?.downloadSize;
+        }
+        else {
+            warn(`Could not fetch the Flathub summary (${String(summary.reason)}); falling back to the bundle size`);
+        }
+    }
+    const age = metainfo.contentRating
+        ? minimumAge(metainfo.contentRating.type, metainfo.contentRating.attributes)
+        : undefined;
+    const developer = metainfo.developer.name
+        ? metainfo.developer
+        : { id: manifest.gjsify?.flatpak?.developer?.id, name: manifest.gjsify?.flatpak?.developer?.name ?? '' };
+    const releases = metainfo.releases.map((release) => ({
+        ...release,
+        description: completeBlocks(release.description),
+    }));
+    return {
+        config,
+        version,
+        app: {
+            id: metainfo.id,
+            name: complete(metainfo.name),
+            summary: complete(metainfo.summary),
+            developer,
+            description: completeBlocks(metainfo.description),
+            license: metainfo.projectLicense,
+            contentLicense: metainfo.metadataLicense,
+            keywords: metainfo.keywords.map(complete),
+            categories: metainfo.categories,
+            urls: metainfo.urls,
+            branding: metainfo.branding,
+            ageRating: age === undefined ? undefined : { minAge: age },
+            icon,
+        },
+        screenshots,
+        releases,
+        latestRelease,
+        downloads: {
+            targets: buildDownloadTargets({
+                assets: config.releaseAssets ? (latestRelease?.assets ?? []) : [],
+                configured: config.downloads,
+                flathub: config.flathub,
+                flathubSize,
+                webAppUrl: config.webApp ? `${config.base}${config.webApp.replace(/^\//, '')}` : undefined,
+            }),
+            releasesUrl: `https://github.com/${config.repository}/releases`,
+            hasReleases,
+        },
+        stats,
+        warnings,
+    };
+}

package/lib/site-data/metainfo.d.ts

@@ -0,0 +1,9 @@
+import type { Localized, Metainfo } from './types.js';
+import { type XmlElement } from './xml.js';
+/**
+ * Pairs sibling elements into texts: an element without `xml:lang` opens a new text, the ones with
+ * `xml:lang` that follow translate it. This is how `msgfmt --xml` writes translated metainfo.
+ */
+export declare function groupLocalized(elements: readonly XmlElement[]): Localized[];
+/** Reads the parts of an AppStream `<component>` the landing page needs. */
+export declare function parseMetainfo(xml: string): Metainfo;

package/lib/site-data/metainfo.js

@@ -0,0 +1,142 @@
+import { child, childrenNamed, parseXml } from './xml.js';
+const XML_LANG = 'xml:lang';
+/**
+ * Pairs sibling elements into texts: an element without `xml:lang` opens a new text, the ones with
+ * `xml:lang` that follow translate it. This is how `msgfmt --xml` writes translated metainfo.
+ */
+export function groupLocalized(elements) {
+    const groups = [];
+    for (const element of elements) {
+        const language = element.attrs[XML_LANG];
+        if (language === undefined) {
+            groups.push({ source: element.text, byLanguage: {} });
+        }
+        else {
+            const current = groups.at(-1);
+            if (current)
+                current.byLanguage[language] = element.text;
+        }
+    }
+    return groups;
+}
+function singleLocalized(parent, name) {
+    return groupLocalized(childrenNamed(parent, name))[0];
+}
+function parseBlocks(description) {
+    const blocks = [];
+    if (!description)
+        return blocks;
+    let paragraphGroup = [];
+    const flushParagraphs = () => {
+        for (const text of groupLocalized(paragraphGroup))
+            blocks.push({ type: 'paragraph', text });
+        paragraphGroup = [];
+    };
+    // Translations of a paragraph follow it directly, so consecutive `<p>` elements are grouped and
+    // split again whenever a list interrupts them.
+    for (const element of description.children) {
+        if (element.name === 'p') {
+            paragraphGroup.push(element);
+        }
+        else if (element.name === 'ul' || element.name === 'ol') {
+            flushParagraphs();
+            blocks.push({ type: 'list', items: groupLocalized(childrenNamed(element, 'li')) });
+        }
+    }
+    flushParagraphs();
+    return blocks;
+}
+function parseReleases(releases) {
+    if (!releases)
+        return [];
+    return childrenNamed(releases, 'release').map((release) => {
+        const timestamp = release.attrs.timestamp;
+        const date = release.attrs.date ?? (timestamp ? new Date(Number(timestamp) * 1000).toISOString().slice(0, 10) : '');
+        return {
+            version: release.attrs.version ?? '',
+            date,
+            type: release.attrs.type,
+            description: parseBlocks(child(release, 'description')),
+        };
+    });
+}
+/** The colours land in an inline `<style>`, so only plain hex values pass. */
+const HEX_COLOR = /^#[0-9a-f]{3,8}$/i;
+function parseBranding(branding) {
+    const result = {};
+    if (!branding)
+        return result;
+    for (const color of childrenNamed(branding, 'color')) {
+        if (color.attrs.type !== 'primary' || !HEX_COLOR.test(color.text))
+            continue;
+        if (color.attrs.scheme_preference === 'light')
+            result.light = color.text;
+        else if (color.attrs.scheme_preference === 'dark')
+            result.dark = color.text;
+    }
+    return result;
+}
+const URL_KEYS = {
+    homepage: 'homepage',
+    bugtracker: 'bugtracker',
+    'vcs-browser': 'vcsBrowser',
+    translate: 'translate',
+    donation: 'donation',
+    help: 'help',
+    faq: 'faq',
+    contact: 'contact',
+    contribute: 'contribute',
+};
+/** Links are rendered as `href`, so `javascript:` and friends are dropped. */
+const SAFE_URL = /^(https?:|mailto:)/i;
+function parseUrls(component) {
+    const urls = {};
+    for (const url of childrenNamed(component, 'url')) {
+        const key = URL_KEYS[url.attrs.type ?? ''];
+        if (key && SAFE_URL.test(url.text))
+            urls[key] = url.text;
+    }
+    return urls;
+}
+/** Reads the parts of an AppStream `<component>` the landing page needs. */
+export function parseMetainfo(xml) {
+    const component = parseXml(xml);
+    if (component.name !== 'component')
+        throw new Error(`Metainfo root must be <component>, got <${component.name}>`);
+    const id = child(component, 'id')?.text;
+    if (!id)
+        throw new Error('Metainfo has no <id>');
+    const name = singleLocalized(component, 'name');
+    if (!name)
+        throw new Error('Metainfo has no <name>');
+    const summary = singleLocalized(component, 'summary') ?? { source: '', byLanguage: {} };
+    const developer = child(component, 'developer');
+    const developerName = developer ? child(developer, 'name')?.text : undefined;
+    const screenshots = childrenNamed(child(component, 'screenshots') ?? component, 'screenshot').map((screenshot) => {
+        const images = childrenNamed(screenshot, 'image');
+        const image = images.find((candidate) => candidate.attrs.type === 'source') ?? images[0];
+        return { url: image?.text ?? '', caption: singleLocalized(screenshot, 'caption') ?? null };
+    });
+    const contentRating = child(component, 'content_rating');
+    const attributes = {};
+    for (const attribute of contentRating ? childrenNamed(contentRating, 'content_attribute') : []) {
+        if (attribute.attrs.id)
+            attributes[attribute.attrs.id] = attribute.text;
+    }
+    return {
+        id,
+        name,
+        summary,
+        developer: { id: developer?.attrs.id, name: developerName ?? '' },
+        description: parseBlocks(child(component, 'description')),
+        screenshots,
+        releases: parseReleases(child(component, 'releases')),
+        branding: parseBranding(child(component, 'branding')),
+        urls: parseUrls(component),
+        keywords: groupLocalized(childrenNamed(child(component, 'keywords') ?? component, 'keyword')),
+        categories: childrenNamed(child(component, 'categories') ?? component, 'category').map((category) => category.text),
+        projectLicense: child(component, 'project_license')?.text,
+        metadataLicense: child(component, 'metadata_license')?.text,
+        contentRating: contentRating ? { type: contentRating.attrs.type ?? '', attributes } : undefined,
+    };
+}

package/lib/site-data/network.d.ts

@@ -0,0 +1,32 @@
+export type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+    /** Only the callers that want bytes need this; a JSON-only fake may leave it out. */
+    arrayBuffer?(): Promise<ArrayBuffer>;
+}>;
+export interface NetworkOptions {
+    fetch?: FetchLike;
+    /** When set, responses are stored here and reused for `cacheTtlMs`; a stale copy also serves as the offline fallback. */
+    cacheDir?: string;
+    cacheTtlMs?: number;
+    timeoutMs?: number;
+}
+/** A response outside 2xx; callers that treat a status as an answer (a 404 for "no release yet") read `status`. */
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, url: string);
+}
+/**
+ * GETs JSON, optionally through an on-disk cache. Throws when the network fails and no cached copy
+ * exists, so callers decide how to degrade.
+ */
+export declare function fetchJson(url: string, headers: Record<string, string>, options?: NetworkOptions): Promise<unknown>;
+/**
+ * GETs bytes. Not cached here: the caller writes the file it asked for and finds it again by name,
+ * which is also what makes a later `--offline` build work.
+ */
+export declare function fetchBinary(url: string, options?: NetworkOptions): Promise<Uint8Array>;

package/lib/site-data/network.js

@@ -0,0 +1,67 @@
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+/** A response outside 2xx; callers that treat a status as an answer (a 404 for "no release yet") read `status`. */
+export class HttpError extends Error {
+    status;
+    constructor(status, url) {
+        super(`HTTP ${status} for ${url}`);
+        this.status = status;
+    }
+}
+const DEFAULT_TTL_MS = 60 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 15_000;
+async function readCache(file) {
+    try {
+        const [text, info] = await Promise.all([readFile(file, 'utf8'), stat(file)]);
+        return { data: JSON.parse(text), ageMs: Date.now() - info.mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * GETs JSON, optionally through an on-disk cache. Throws when the network fails and no cached copy
+ * exists, so callers decide how to degrade.
+ */
+export async function fetchJson(url, headers, options = {}) {
+    const file = options.cacheDir
+        ? join(options.cacheDir, `${createHash('sha256').update(url).digest('hex').slice(0, 16)}.json`)
+        : undefined;
+    const cached = file ? await readCache(file) : null;
+    if (cached && cached.ageMs < (options.cacheTtlMs ?? DEFAULT_TTL_MS))
+        return cached.data;
+    try {
+        const doFetch = options.fetch ?? ((target, init) => fetch(target, init));
+        const response = await doFetch(url, {
+            headers,
+            signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            throw new HttpError(response.status, url);
+        const data = await response.json();
+        if (file && options.cacheDir) {
+            await mkdir(options.cacheDir, { recursive: true });
+            await writeFile(file, JSON.stringify(data));
+        }
+        return data;
+    }
+    catch (error) {
+        if (cached)
+            return cached.data;
+        throw error;
+    }
+}
+/**
+ * GETs bytes. Not cached here: the caller writes the file it asked for and finds it again by name,
+ * which is also what makes a later `--offline` build work.
+ */
+export async function fetchBinary(url, options = {}) {
+    const doFetch = options.fetch ?? ((target, init) => fetch(target, init));
+    const response = await doFetch(url, { signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS) });
+    if (!response.ok)
+        throw new HttpError(response.status, url);
+    if (!response.arrayBuffer)
+        throw new Error(`This fetch implementation cannot read bytes (${url})`);
+    return new Uint8Array(await response.arrayBuffer());
+}

package/lib/site-data/oars.d.ts

@@ -0,0 +1,15 @@
+/**
+ * OARS content rating → minimum age.
+ *
+ * Ported from libappstream's `as_content_rating_attribute_to_csm_age()` (the Common Sense Media
+ * table) and `as_content_rating_get_minimum_age()`, which is what GNOME Software and Flathub show:
+ * https://github.com/ximion/appstream/blob/master/src/as-content-rating.c
+ * Unknown attributes count as 0, like upstream.
+ */
+export type OarsValue = 'none' | 'mild' | 'moderate' | 'intense';
+export declare function attributeToCsmAge(attribute: string, value: string): number;
+/**
+ * The highest per-attribute age (`as_content_rating_get_minimum_age()`); 0 means "all ages".
+ * Returns `undefined` for rating systems other than OARS 1.0/1.1, where upstream gives no answer.
+ */
+export declare function minimumAge(kind: string, attributes: Readonly<Record<string, string>>): number | undefined;

package/lib/site-data/oars.js

@@ -0,0 +1,62 @@
+/**
+ * OARS content rating → minimum age.
+ *
+ * Ported from libappstream's `as_content_rating_attribute_to_csm_age()` (the Common Sense Media
+ * table) and `as_content_rating_get_minimum_age()`, which is what GNOME Software and Flathub show:
+ * https://github.com/ximion/appstream/blob/master/src/as-content-rating.c
+ * Unknown attributes count as 0, like upstream.
+ */
+const VALUE_INDEX = { none: 0, mild: 1, moderate: 2, intense: 3 };
+/** Minimum age per attribute for `[none, mild, moderate, intense]`. */
+const CSM_AGE = {
+    'violence-cartoon': [0, 3, 4, 6],
+    'violence-fantasy': [0, 3, 7, 8],
+    'violence-realistic': [0, 4, 9, 14],
+    'violence-bloodshed': [0, 9, 11, 18],
+    'violence-sexual': [0, 18, 18, 18],
+    'drugs-alcohol': [0, 11, 13, 16],
+    'drugs-narcotics': [0, 12, 14, 17],
+    'drugs-tobacco': [0, 10, 13, 13],
+    'sex-nudity': [0, 12, 14, 14],
+    'sex-themes': [0, 13, 14, 15],
+    'language-profanity': [0, 8, 11, 14],
+    'language-humor': [0, 3, 8, 14],
+    'language-discrimination': [0, 9, 10, 11],
+    'money-advertising': [0, 7, 8, 10],
+    'money-gambling': [0, 7, 10, 18],
+    'money-purchasing': [0, 12, 14, 15],
+    'social-chat': [0, 4, 10, 13],
+    'social-audio': [0, 15, 15, 15],
+    'social-contacts': [0, 12, 12, 12],
+    'social-info': [0, 0, 13, 13],
+    'social-location': [0, 13, 13, 13],
+    'sex-homosexuality': [0, 13, 14, 15],
+    'sex-prostitution': [0, 12, 14, 18],
+    'sex-adultery': [0, 8, 10, 18],
+    'sex-appearance': [0, 10, 10, 15],
+    'violence-worship': [0, 13, 15, 18],
+    'violence-desecration': [0, 13, 15, 18],
+    'violence-slavery': [0, 13, 15, 18],
+};
+function isOarsValue(value) {
+    return value in VALUE_INDEX;
+}
+export function attributeToCsmAge(attribute, value) {
+    const row = CSM_AGE[attribute];
+    if (!row || !isOarsValue(value))
+        return 0;
+    return row[VALUE_INDEX[value]];
+}
+/**
+ * The highest per-attribute age (`as_content_rating_get_minimum_age()`); 0 means "all ages".
+ * Returns `undefined` for rating systems other than OARS 1.0/1.1, where upstream gives no answer.
+ */
+export function minimumAge(kind, attributes) {
+    if (kind !== 'oars-1.0' && kind !== 'oars-1.1')
+        return undefined;
+    let age = 0;
+    for (const [attribute, value] of Object.entries(attributes)) {
+        age = Math.max(age, attributeToCsmAge(attribute, value));
+    }
+    return age;
+}

package/lib/site-data/po.d.ts

@@ -0,0 +1,40 @@
+import type { Localized } from './types.js';
+/** A parsed gettext catalogue: msgid → msgstr, context-free, untranslated and fuzzy entries dropped. */
+export type Catalog = ReadonlyMap<string, string>;
+export interface PoEntry {
+    msgctxt?: string;
+    msgid: string;
+    msgstr: string;
+    fuzzy: boolean;
+    references: string[];
+}
+/** Parses a `.po`/`.pot` file; plural forms are not needed for web copy and are skipped. */
+export declare function parsePo(text: string): PoEntry[];
+/** Builds a lookup from parsed entries, skipping the header, empty, fuzzy and context-bound entries. */
+export declare function catalogFromEntries(entries: readonly PoEntry[]): Catalog;
+export declare function parseCatalog(text: string): Catalog;
+/** Layers catalogues by language; a later one wins per msgid, so an overlay can correct a base. */
+export declare function mergeCatalogs(...layers: ReadonlyArray<Readonly<Record<string, Catalog>>>): Record<string, Catalog>;
+/** Escapes a string for a `.po` file value. */
+export declare function quotePo(value: string): string;
+/**
+ * Language tags the metainfo (`pt-BR`, BCP 47) and gettext (`pt_BR`) spell differently, from most to
+ * least specific: `pt-BR`, `pt_BR`, `pt`.
+ */
+export declare function languageCandidates(language: string): string[];
+/** Finds the entry for a language in a map keyed by either spelling. */
+export declare function pickByLanguage<T>(byLanguage: Readonly<Record<string, T>>, language: string): T | undefined;
+/**
+ * Resolves a text for a language. Precedence: the metainfo's own `xml:lang` translation, then the
+ * app catalogue (msgid = the source text), then the source text itself.
+ */
+export declare function resolveLocalized(text: Localized, language: string, catalog?: Catalog): string;
+/** The page strings are English msgids, so English needs no catalogue. */
+export declare const UI_SOURCE_LANGUAGE = "en";
+/** A translator bound to one catalogue; unknown msgids come back unchanged, which is gettext's contract. */
+export declare function translator(catalog: Catalog | undefined): (msgid: string) => string;
+/**
+ * Fills in the translations a text lacks for the site's languages, from the app catalogues
+ * (keyed by language). Translations the metainfo already carries win; other metainfo languages are dropped.
+ */
+export declare function completeLocalized(text: Localized, languages: readonly string[], sourceLanguage: string, catalogs: Readonly<Record<string, Catalog>>): Localized;