@gjsify/site 0.64.25 → 0.64.26

package/README.md

@@ -46,6 +46,7 @@ gjsify site build --runtime node        # build and run on a specific runtime
 | `--drafts` | `build`: include blog posts marked `draft: true`. |
 | `--no-cache` | Ignore the one-hour HTTP response cache. |
 | `--cache-dir <dir>` | Where the response cache and the image renditions live. Default: `<root>/node_modules/.cache/gjsify-site`. |
+| `--release-tag <tag>` | `build`: take the download links from this GitHub release (`releases/tags/<tag>`) instead of `releases/latest`, which can lag a fresh publish by minutes. Default: `$GJSIFY_SITE_RELEASE_TAG`. |
 | `--check` | `i18n`: report what is out of date instead of writing it. |
 | `--runtime <r>` | `gjs` \| `node` \| `bun` \| `deno`. Default: the runtime the CLI itself is on. |
 
@@ -166,6 +167,11 @@ shared package can derive.
 `GITHUB_TOKEN` is optional and only raises the API rate limit. When a lookup fails the build
 warns rather than failing: a release API outage is not a reason to have no page.
 
+The build logs which release it used (tag, publish date, asset count) and warns when that release's
+version differs from the version the page shows. A deploy triggered by `release: published` should
+pass `--release-tag "$GITHUB_REF_NAME"` (or set `GJSIFY_SITE_RELEASE_TAG`): `releases/latest` can still
+answer with the previous release for a few minutes.
+
 The same thing from a script:
 
 ```ts

package/lib/cli.js

@@ -22,6 +22,9 @@ Options:
   --no-cache         Ignore the one-hour HTTP response cache
   --cache-dir <dir>  Where to keep the response cache and image renditions
                      (default: <root>/node_modules/.cache/gjsify-site)
+  --release-tag <t>  build: take the download links from this GitHub release
+                     instead of \`releases/latest\`, which lags a fresh publish
+                     (default: $GJSIFY_SITE_RELEASE_TAG)
   --check            i18n: report what is out of date instead of writing it
   --store <s>        listing: cws | edge | amo | all (default: all)
   --metainfo <path>  listing: AppStream metainfo, overriding the configured one
@@ -33,7 +36,8 @@ Options:
                      from this module's own location)
   -h, --help         Show this text
 
-Environment: GITHUB_TOKEN raises the GitHub API rate limit.`;
+Environment: GITHUB_TOKEN raises the GitHub API rate limit.
+             GJSIFY_SITE_RELEASE_TAG is the default of --release-tag.`;
 /** The value after `--name`, or `undefined` when the flag is absent. */
 function flagValue(flags, name) {
     const index = flags.indexOf(name);
@@ -59,6 +63,8 @@ async function build(flags) {
         cacheDir: cacheOption(flags),
         packageDir: flagValue(flags, '--package-dir'),
         githubToken: process.env.GITHUB_TOKEN || undefined,
+        releaseTag: flagValue(flags, '--release-tag') ?? (process.env.GJSIFY_SITE_RELEASE_TAG || undefined),
+        log: (message) => console.log(message),
         warn: (message) => console.warn(`warning: ${message}`),
     });
     console.log(`Built the pages in ${result.languages.length} languages and ${result.screenshots} screenshots`);

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

@@ -11,5 +11,9 @@ export declare function fetchReleaseRecords(assets: readonly ReleaseAsset[], opt
 /**
  * Fetches the latest published (non-draft, non-prerelease) release; `null` when the repository has
  * none yet, which is a state and not an error. `token` raises the rate limit.
+ *
+ * With `tag`, fetches exactly that release instead. `releases/latest` lags a fresh publish by
+ * minutes, so a deploy triggered by the release itself must be able to name it; a pinned tag that
+ * does not exist is an error, not "no release yet".
  */
-export declare function fetchLatestRelease(repository: string, token: string | undefined, options: NetworkOptions): Promise<LatestRelease | null>;
+export declare function fetchLatestRelease(repository: string, token: string | undefined, options: NetworkOptions, tag?: string): Promise<LatestRelease | null>;

package/lib/site-data/github.js

@@ -55,8 +55,12 @@ export async function fetchReleaseRecords(assets, options, warn) {
 /**
  * Fetches the latest published (non-draft, non-prerelease) release; `null` when the repository has
  * none yet, which is a state and not an error. `token` raises the rate limit.
+ *
+ * With `tag`, fetches exactly that release instead. `releases/latest` lags a fresh publish by
+ * minutes, so a deploy triggered by the release itself must be able to name it; a pinned tag that
+ * does not exist is an error, not "no release yet".
  */
-export async function fetchLatestRelease(repository, token, options) {
+export async function fetchLatestRelease(repository, token, options, tag) {
     const headers = {
         Accept: 'application/vnd.github+json',
         'User-Agent': `${repository.replace('/', '-')}-website`,
@@ -64,11 +68,14 @@ export async function fetchLatestRelease(repository, token, options) {
     if (token)
         headers.Authorization = `Bearer ${token}`;
     try {
-        return parseLatestRelease(await fetchJson(`https://api.github.com/repos/${repository}/releases/latest`, headers, options));
+        return parseLatestRelease(await fetchJson(`https://api.github.com/repos/${repository}/releases/${tag ? `tags/${encodeURIComponent(tag)}` : 'latest'}`, headers, options));
     }
     catch (error) {
-        if (error instanceof HttpError && error.status === 404)
+        if (error instanceof HttpError && error.status === 404) {
+            if (tag)
+                throw new Error(`GitHub has no release tagged ${tag} in ${repository}`);
             return null;
+        }
         throw error;
     }
 }

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

@@ -9,7 +9,10 @@ export interface LoadOptions {
     /** Skip every network call (release assets, stats, screenshots hosted elsewhere). */
     offline?: boolean;
     githubToken?: string;
+    /** Use this release tag instead of `releases/latest`, which lags a fresh publish by minutes. */
+    releaseTag?: string;
     network?: NetworkOptions;
+    log?: (message: string) => void;
     warn?: (message: string) => void;
 }
 /** Reads `<dir>/<lang>.po` for every language, trying `pt-BR` and `pt_BR` spellings; missing files are skipped. */

package/lib/site-data/load.js

@@ -90,7 +90,7 @@ export async function loadSiteData(options) {
     if (!options.offline) {
         const network = options.network ?? {};
         const [release, flathub, summary] = await Promise.allSettled([
-            fetchLatestRelease(config.repository, options.githubToken, network),
+            fetchLatestRelease(config.repository, options.githubToken, network, options.releaseTag),
             config.flathub ? fetchFlathubStats(config.flathub, network) : Promise.resolve(undefined),
             config.flathub ? fetchFlathubSummary(config.flathub, network) : Promise.resolve(undefined),
         ]);
@@ -98,6 +98,11 @@ export async function loadSiteData(options) {
             latestRelease = release.value;
             hasReleases = latestRelease !== null;
             if (latestRelease) {
+                options.log?.(`Using GitHub release ${latestRelease.tag} (published ${latestRelease.publishedAt || 'unknown'}, ${latestRelease.assets.length} assets)${options.releaseTag ? ' as pinned' : ''}`);
+                const shown = version || metainfo.releases[0]?.version || '';
+                if (shown && latestRelease.tag.replace(/^v/, '') !== shown) {
+                    warn(`The release ${latestRelease.tag} does not match the version ${shown} the page shows; download links point to ${latestRelease.tag}${options.releaseTag ? '' : ' (releases/latest may lag a fresh publish; pin it with --release-tag)'}`);
+                }
                 // A release record is fetched by every site build, not by a person installing.
                 stats.githubDownloads = latestRelease.assets
                     .filter((asset) => recordedArtifact(asset.name) === undefined)
@@ -107,7 +112,7 @@ export async function loadSiteData(options) {
             }
         }
         else {
-            warn(`Could not fetch the latest GitHub release (${String(release.reason)}); linking to the releases page instead`);
+            warn(`Could not fetch the ${options.releaseTag ? `GitHub release ${options.releaseTag}` : 'latest GitHub release'} (${String(release.reason)}); linking to the releases page instead`);
         }
         if (flathub.status === 'fulfilled' && flathub.value) {
             stats.flathubInstalls = flathub.value.installsTotal;

package/lib/site.d.ts

@@ -20,6 +20,8 @@ export interface SiteBuildOptions extends SiteTarget {
     cacheDir?: string | false;
     /** Raises the GitHub API rate limit. Optional — the public limit is enough for a single build. */
     githubToken?: string;
+    /** Pin the GitHub release the download links come from, instead of `releases/latest`. */
+    releaseTag?: string;
     log?: (message: string) => void;
     warn?: (message: string) => void;
     /**

package/lib/site.js

@@ -212,7 +212,9 @@ async function buildAppSite(build) {
         screenshotCacheDir: join(cacheDir ?? defaultCacheDir(target.root), 'screenshots'),
         offline: options.offline ?? false,
         githubToken: options.githubToken,
+        releaseTag: options.releaseTag,
         network: cacheDir ? { cacheDir: join(cacheDir, 'http') } : {},
+        log: options.log,
         warn: options.warn,
     });
     const images = await processScreenshots(data, target, cacheDir ?? defaultCacheDir(target.root));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/site",
-    "version": "0.64.25",
+    "version": "0.64.26",
     "description": "Static landing page generator for a GNOME-style app, rendered from its AppStream metainfo — downloads, screenshots, release notes, support links, no JavaScript required.",
     "type": "module",
     "main": "lib/index.js",
@@ -54,21 +54,21 @@
     "license": "MIT",
     "dependencies": {
         "@girs/gdkpixbuf-2.0": "5.4.0",
-        "@gjsify/console": "^0.64.25",
-        "@gjsify/crypto": "^0.64.25",
-        "@gjsify/fs": "^0.64.25",
-        "@gjsify/module": "^0.64.25",
-        "@gjsify/os": "^0.64.25",
-        "@gjsify/path": "^0.64.25",
-        "@gjsify/process": "^0.64.25",
-        "@gjsify/url": "^0.64.25",
+        "@gjsify/console": "^0.64.26",
+        "@gjsify/crypto": "^0.64.26",
+        "@gjsify/fs": "^0.64.26",
+        "@gjsify/module": "^0.64.26",
+        "@gjsify/os": "^0.64.26",
+        "@gjsify/path": "^0.64.26",
+        "@gjsify/process": "^0.64.26",
+        "@gjsify/url": "^0.64.26",
         "fast-xml-parser": "^5.11.2",
         "qrcode-generator": "^2.0.4"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.64.25",
+        "@gjsify/cli": "^0.64.26",
         "@gjsify/node-gi": "file:../../node-gi/node-gi",
-        "@gjsify/unit": "^0.64.25",
+        "@gjsify/unit": "^0.64.26",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },