@gjsify/site 0.0.0-stage → 0.62.0

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# @gjsify/site
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Static landing page generator for a GNOME-style app. Everything on the page comes from files the
+project already has — the AppStream metainfo, the root `package.json`, the app's gettext
+catalogues, a screenshot directory — plus, at build time, the GitHub release and Flathub APIs.
+Nothing about any particular app is compiled in: all app-specific values come from a
+`gjsify.site` block.
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS
+(GNOME JavaScript).
+
+The output works without JavaScript. Two small web components (`<app-download>`,
+`<screenshot-carousel>`) only enhance what is already in the HTML.
+
+## Installation
+
+```bash
+gjsify install -D @gjsify/site
+
+# npm or yarn also work:
+npm install -D @gjsify/site
+```
+
+Runs on whichever runtime your `gjsify` runs on — GJS, Node, Bun or Deno. The screenshot
+renditions go through GdkPixbuf, reached natively under GJS and through
+[`@gjsify/node-gi`](../../node-gi/node-gi) otherwise, so add that package if you build the page on
+Node, Bun or Deno. A site build also needs the gdk-pixbuf AVIF and WebP loaders, which current
+GNOME ships; if one is missing the build says so and names the format.
+
+## Use
+
+```sh
+gjsify site build                       # render ./dist from ./package.json's gjsify.site
+gjsify site build --root <repo> --out <dir>
+gjsify site i18n                        # update the page catalogues of <root>
+gjsify site i18n --check                # fail instead of writing
+gjsify site build --runtime node        # build and run on a specific runtime
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--root <path>` | Repository to work on — a checkout whose root `package.json` has `gjsify.site`. Default: the working directory. |
+| `--out <dir>` | Output directory, emptied first. Default: `<root>/dist`. |
+| `--offline` | Skip every network call. The page then links to the releases page and omits the counts. |
+| `--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`. |
+| `--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. |
+
+`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 same thing from a script:
+
+```ts
+import { buildSite, syncSiteI18n } from '@gjsify/site';
+
+const { languages, screenshots } = await buildSite({ root, out, warn: console.warn });
+```
+
+## `gjsify.site`
+
+Lives in the root `package.json`, next to `ship` and `flatpak`.
+
+| Key | Meaning |
+| --- | --- |
+| `metainfo` | AppStream file, relative to the repo root. Source of name, summary, description, releases, URLs, branding, keywords, age rating. |
+| `base` / `url` | URL path the site is served under, and its absolute origin + path (canonical, `hreflang`, `og:image`). |
+| `languages` / `defaultLanguage` / `sourceLanguage` | Languages to render (`/en/`, `/de/`). `defaultLanguage` is where `/` lands when the visitor's languages match none (default: the first). `sourceLanguage` is the language of the metainfo's untranslated text (default `en`); the others are looked up in `translations`. |
+| `repository` | `owner/name`; release assets and counts come from its latest GitHub release. |
+| `flathub` | Flathub app id: adds the Flathub download and install count. Optional. |
+| `webApp` | Path of a web app below `base`; adds "Try in browser". Optional. |
+| `translations` | Directory of the app's `<lang>.po` catalogues, used when the metainfo lacks a translation. Optional. |
+| `pageTranslations` | Directory of `<lang>.po` catalogues for the *page's own* strings, overlaying this package's `po/`. Optional, see below. |
+| `icon` | Icon (SVG or PNG) for the header, hero and favicon; overrides the Flatpak/ship icon. Optional. |
+| `downloads` | `[{platform, format, url?, label?, available?}]`: targets the release assets do not cover, e.g. browser stores or a source install. `platform` is an OS or `firefox` / `chromium`; `format` adds `store`, `xpi`, `source`. `url` is required unless `available` is `false`, which lists the target as "Not yet available" and never recommends it. |
+| `releaseAssets` | `false` ignores the GitHub release assets, so `downloads` is the whole list. Default `true`. |
+| `support`, `legal` | `support`: `{kind, url}` links, or `{kind: "sepa", name, iban, bic?, reference?}`, a bank transfer shown as IBAN plus an EPC QR code. `legal`: `{label, url}` links. Both empty by default: nothing is invented. |
+
+A `sepa` entry carries no amount, and its IBAN is checked when the config loads — length per
+country, alphabet, and the mod-97 checksum — so a typo fails the build instead of printing a QR
+code that moves money nowhere.
+
+### Screenshots
+
+Nothing to configure: the page shows the metainfo `<screenshots>`, in document order, with their
+captions — the same artwork Flathub shows, so the page doubles as a preview of the store listing.
+
+Each `<image>` is located before it is processed. A `raw.githubusercontent.com` URL into
+`repository` is read from the checkout being built, so a metainfo pinned to a tag still shows the
+artwork of the working tree. Anything else is downloaded once into the build cache, which is what
+makes a later `--offline` build find it again. A screenshot whose file cannot be found or fetched
+is skipped with a warning naming it — one image missing beats no page.
+
+Two things happen to the artwork:
+
+- **Fully transparent rows and columns are cropped away.** A window shot is saved on a canvas
+  large enough for the window's own shadow, and how much empty space is left around it is up to
+  whoever took the shot; the page would otherwise frame that emptiness. The threshold is "not one
+  pixel painted at all", so the shadow itself survives.
+- **Renditions go up to 2560px and the display width is capped at 1280.** That settles what a "2×"
+  source is without asking the metainfo: a 2560px screenshot fills a 1280 CSS px box at
+  device-pixel-ratio 2 and stays crisp, a narrower one is shown at its natural width. Nothing is
+  ever upscaled.
+
+The `<picture>` carries AVIF, WebP and PNG, each with a `srcset` of 640px, 1280px and 2560px
+renditions up to the source's own width.
+
+### Colour
+
+Also nothing to configure: the metainfo's `<branding>` colour for the page's scheme paints the
+masthead — the bar, the icon and title, the install button, the facts row and the screenshots, all
+one surface. The text on it is not assumed to be white; the build measures the brand colour's
+relative luminance and writes near-black or white into `--band-fg`, whichever the eye can read.
+Everything below the masthead keeps the site's own neutral palette, so a pale brand colour cannot
+make the description unreadable. An app without `<branding>` gets the default blue.
+
+## Translations
+
+Two catalogue sets meet on the page, and they have different owners.
+
+- **Page strings** — "Download", "Release notes", the download labels — are gettext msgids in
+  English and ship with this package, in `po/`. Nothing to do to get them.
+- **App text** — name, summary, description, release notes — is looked up per language: the
+  metainfo's own `xml:lang` element, then `translations/<lang>.po` (msgid = the source text), then
+  the source text.
+- **Consumer page strings** — any page string a consumer wants to word differently — live in
+  `pageTranslations`. That directory
+  overlays `po/`: an entry there wins, everything else falls back. `gjsify site i18n` regenerates
+  it from the strings the build can emit and warns about each one still untranslated; `--check`
+  turns that into a failure for CI.
+
+`gjsify site i18n --package` is the other mode: it syncs *this package's* `po/site.pot` and
+`po/<lang>.po` from `src/render`, and is what `gjsify workspace @gjsify/site run i18n` calls. No
+`xgettext` needed in either mode — the msgids are read from the sources directly.
+
+## Development
+
+```sh
+gjsify workspace @gjsify/site build
+gjsify workspace @gjsify/site check       # typecheck + catalogues in sync
+gjsify workspace @gjsify/site test             # the node leg, then the gjs leg
+gjsify workspace @gjsify/site test:cross-runtime  # the GI-free suites on node + bun + deno
+gjsify workspace @gjsify/site test:gjs-on-node    # the image suite via @gjsify/node-gi
+```
+
+The client bundle and the stylesheet are built once, here, into `lib/client/`. A site build only
+content-hashes them and copies them to `<out>/assets/site-<hash>.{js,css}`, so a consumer needs no
+bundler of its own.
+
+`src/test.mts` holds the suites that need no GI and runs anywhere — `test:cross-runtime` runs that
+one bundle on node, bun and deno. `src/test.gjs.mts` adds the image suites, which need GdkPixbuf,
+and is the gjs leg. `src/test.node-gi.mts` registers the image suite alone and `test:gjs-on-node`
+builds it `--app node`, so the same `src/render/image-backend.ts` encodes under Node through
+`@gjsify/node-gi` — which is what proves the one image backend really is one.
+
+## Design
+
+[ADR 0109](../../../docs/adr/0109-a-static-site-generator-reads-an-app-from-its-metainfo.md) —
+why the page is derived from the metainfo, why the config is a union rather than a template, why
+the entry point is a `gjsify` subcommand rather than a `bin` with a shebang, and why GdkPixbuf is
+the only image backend.
+
+## License
+
+MIT

package/lib/cli.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Runs one `gjsify site` invocation and answers the process exit code. Never
+ * exits the process itself: under GJS `process.exit` does not halt
+ * synchronously, so the decision belongs to the generated entry.
+ */
+export declare function runSiteCli(argv: readonly string[]): Promise<number>;

package/lib/cli.js

@@ -0,0 +1,91 @@
+// Argv parsing over `site.ts`; every decision worth testing lives there.
+//
+// No shebang and no top-level run: this is a LIBRARY entry point. `gjsify site`
+// generates a tiny module that calls `runSiteCli`, bundles it for the runtime
+// the CLI itself is on, and runs it — so there is no `gjsify-site` bin bound to
+// one runtime. See `packages/infra/cli/src/commands/site.ts`.
+import { join, resolve } from 'node:path';
+import { buildSite, syncSiteI18n } from './site.js';
+const USAGE = `Usage: gjsify site <command> [options]
+
+  build [options]    Render the static pages of a repository
+  i18n [options]     Update the page catalogues from the strings the build can emit
+
+Options:
+  --root <path>      Repository to work on (default: the working directory)
+  --out <dir>        Output directory, emptied first (default: <root>/dist)
+  --offline          Skip every network call
+  --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)
+  --check            i18n: report what is out of date instead of writing it
+  --package          i18n: sync this package's own catalogues instead of a consumer's
+  --package-dir <d>  Where @gjsify/site is installed; the client bundle and the
+                     shipped catalogues are read from there (default: derived
+                     from this module's own location)
+  -h, --help         Show this text
+
+Environment: GITHUB_TOKEN raises the GitHub API rate limit.`;
+/** The value after `--name`, or `undefined` when the flag is absent. */
+function flagValue(flags, name) {
+    const index = flags.indexOf(name);
+    if (index === -1)
+        return undefined;
+    const value = flags[index + 1];
+    if (value === undefined || value.startsWith('--'))
+        throw new Error(`${name} needs a value`);
+    return value;
+}
+function cacheOption(flags) {
+    if (flags.includes('--no-cache'))
+        return false;
+    return flagValue(flags, '--cache-dir');
+}
+async function build(flags) {
+    const root = resolve(flagValue(flags, '--root') ?? process.cwd());
+    const result = await buildSite({
+        root,
+        out: resolve(flagValue(flags, '--out') ?? join(root, 'dist')),
+        offline: flags.includes('--offline'),
+        cacheDir: cacheOption(flags),
+        packageDir: flagValue(flags, '--package-dir'),
+        githubToken: process.env.GITHUB_TOKEN || undefined,
+        warn: (message) => console.warn(`warning: ${message}`),
+    });
+    console.log(`Built ${result.languages.length} pages and ${result.screenshots} screenshots`);
+    return 0;
+}
+async function i18n(flags) {
+    const check = flags.includes('--check');
+    const root = flags.includes('--package') ? undefined : resolve(flagValue(flags, '--root') ?? process.cwd());
+    const { stale, untranslated } = await syncSiteI18n({
+        root,
+        check,
+        packageDir: flagValue(flags, '--package-dir'),
+    });
+    for (const file of stale)
+        console.log(check ? `${file} is out of date; run \`gjsify site i18n\`` : `updated ${file}`);
+    for (const message of untranslated)
+        console.error(message);
+    return untranslated.length > 0 || (check && stale.length > 0) ? 1 : 0;
+}
+/**
+ * Runs one `gjsify site` invocation and answers the process exit code. Never
+ * exits the process itself: under GJS `process.exit` does not halt
+ * synchronously, so the decision belongs to the generated entry.
+ */
+export async function runSiteCli(argv) {
+    const [command, ...flags] = argv;
+    try {
+        if (command === 'build')
+            return await build(flags);
+        if (command === 'i18n')
+            return await i18n(flags);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        return 1;
+    }
+    console.error(USAGE);
+    return command === '--help' || command === '-h' ? 0 : 2;
+}