@gjsify/cli 0.43.0 → 0.45.0

package/lib/utils/ship/localize-metadata.js

@@ -0,0 +1,126 @@
+// Folding the staged gettext catalogues into the generated freedesktop metadata.
+//
+// `gjsify ship` already discovered, validated and staged the compiled `.mo`
+// catalogues, and `app-metadata.ts` already rendered a `.desktop` entry and an
+// AppStream component. The two never met: no `Name[xx]=` and no `xml:lang=` was
+// emitted anywhere, so a fully translated app still showed an English name in
+// the GNOME app menu and in Software. Nobody reported it because both files
+// stay VALID without the translations — `desktop-file-validate` and
+// `appstreamcli validate` pass an untranslated file at exit 0, which is why the
+// tests for this assert the localised keys are PRESENT rather than trusting a
+// validator to notice they are gone.
+//
+// The msgfmt constraints this rests on live in `../msgfmt-merge.ts`, which runs
+// the chain for `gjsify gettext` too. Two more are local to here, both from what
+// a STAGED locale tree may hold that a `po/` directory cannot:
+//
+//   * The catalogues reach us as `.mo` and msgfmt reads `.po` — handing it a
+//     `.mo` gives `de.mo:1:2: syntax error`, exit 1. `msgunfmt` converts back,
+//     and the round trip is exact for the msgid/msgstr pairs these two formats
+//     consume.
+//   * One language may arrive as SEVERAL catalogues, because the tree is keyed by
+//     `<lang>/LC_MESSAGES/<domain>.mo` and a package may ship more than one text
+//     domain. `msgcat --use-first` folds those into one before the chain sees
+//     them — the alternative is `msgfmt-merge.ts` constraint 5, an invalid file
+//     out of nothing but exit-0 calls.
+//
+// Both tools are in the same `gettext` package as `msgfmt`, so neither adds a
+// dependency the fold did not already have.
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { mergeCatalogues } from '../msgfmt-merge.js';
+/**
+ * The locale a staged catalogue path declares.
+ *
+ * Read rather than re-validated: `discoverLocales` has already refused anything
+ * that is not `<lang>/LC_MESSAGES/<domain>.mo`, and a second validator here would
+ * be a second definition of the layout.
+ */
+function localeOf(rel) {
+    return rel.split('/')[0] ?? '';
+}
+/** Chain one metadata file through every catalogue, and read the result back. */
+function fold(mode, source, extension, catalogues, workDir) {
+    // The source is a STRING, so it has to become a file before msgfmt can be its
+    // template — and that file needs `extension` for the same reason the
+    // intermediates do (`msgfmt-merge.ts`, constraint 4).
+    const template = join(workDir, `source${extension}`);
+    writeFileSync(template, source);
+    return readFileSync(mergeCatalogues({ mode, template, extension, catalogues, workDir }), 'utf-8');
+}
+/**
+ * Translate the generated metadata with the catalogues the package ships.
+ *
+ * Returns the input unchanged when there is nothing to fold in, so a project
+ * without a `localeDir` never needs the gettext tools. A project WITH catalogues
+ * that lacks them is REFUSED rather than shipped in English: an untranslated
+ * `.desktop` is indistinguishable from a correct one at install time, and the
+ * package would have promised translations it does not deliver.
+ */
+export function localizeMetadata(metadata, localeFiles) {
+    if (localeFiles.length === 0)
+        return metadata;
+    const workDir = mkdtempSync(join(tmpdir(), 'gjsify-ship-l10n-'));
+    try {
+        // Sorted so the emitted `Name[xx]=` order — and therefore the artifact's
+        // bytes — does not depend on directory-read order. `listFilesRecursive`
+        // already sorts; relying on that from here would put the determinism of this
+        // file's output in another module's keeping. The sort ALSO fixes which
+        // domain wins below, so `--use-first` is a choice and not a coin toss.
+        const sorted = [...localeFiles].sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+        // Grouped by LOCALE, not one entry per file. `discoverLocales` accepts every
+        // `<lang>/LC_MESSAGES/<domain>.mo`, and a package that ships two text domains
+        // (its own plus a bundled library's) therefore hands us two catalogues for one
+        // language. Chained as-is that is `msgfmt-merge.ts` constraint 5: two exit-0
+        // calls and a file both validators reject — `multiple keys named "Name[de]"`
+        // (exit 1) and `tag-duplicated name (lang=de)` (exit 3). Measured.
+        const byLocale = new Map();
+        for (const [index, file] of sorted.entries()) {
+            const po = join(workDir, `${index}.po`);
+            execFileSync('msgunfmt', [file.abs, '--output-file', po], { stdio: 'pipe' });
+            const locale = localeOf(file.rel);
+            byLocale.set(locale, [...(byLocale.get(locale) ?? []), po]);
+        }
+        const catalogues = [...byLocale].map(([locale, files]) => ({
+            locale,
+            // `--use-first` rather than a plain concatenation: two domains translating
+            // the same source string is not an error a packager can act on, and the
+            // alternatives are both worse. msgfmt given both files at once refuses
+            // outright (`duplicate message definition`, 2 fatal errors, exit 1), and a
+            // plain `msgcat` writes `#-#-#-#-#` conflict markers straight into the
+            // `Name=` a user reads. First in the sort above wins, deterministically.
+            po: files.length === 1 ? files[0] : msgcat(files, join(workDir, `${locale}.merged.po`)),
+        }));
+        return {
+            metainfo: fold('--xml', metadata.metainfo, '.metainfo.xml', catalogues, workDir),
+            desktopEntry: metadata.desktopEntry === undefined
+                ? undefined
+                : fold('--desktop', metadata.desktopEntry, '.desktop', catalogues, workDir),
+        };
+    }
+    catch (error) {
+        throw new Error(describeFailure(error, localeFiles.length));
+    }
+    finally {
+        rmSync(workDir, { recursive: true, force: true });
+    }
+}
+/** Fold several `.po` for ONE language into one, first translation wins. Returns its path. */
+function msgcat(files, out) {
+    execFileSync('msgcat', ['--use-first', '--output-file', out, ...files], { stdio: 'pipe' });
+    return out;
+}
+/** One actionable line for a failed merge, naming the tool the host is missing. */
+function describeFailure(error, count) {
+    const e = error;
+    if (e?.code === 'ENOENT') {
+        return ('gjsify ship: `msgfmt`/`msgunfmt`/`msgcat` are not on PATH, but the package stages ' +
+            `${count} gettext catalogue(s). Install them (package: gettext) — shipping the metadata ` +
+            'untranslated would install an English app menu entry for a translated app, which nothing ' +
+            'downstream can detect.');
+    }
+    const stderr = e?.stderr === undefined ? '' : `\n${String(e.stderr).trim()}`;
+    return `gjsify ship: could not fold the gettext catalogues into the freedesktop metadata.${stderr}`;
+}

package/lib/utils/ship/mime.js

@@ -9,15 +9,7 @@
 //
 // So a project that invents a type also ships a shared-mime-info document, and the package refreshes
 // the MIME cache on install (see `scripts.ts`) — an unrefreshed cache is the same silence again.
-/** XML text escaping. Only the five that matter in element content and attributes. */
-function esc(value) {
-    return value
-        .replace(/&/g, '&')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&apos;');
-}
+import { xmlEscape as esc } from './xml.js';
 const TYPE_RE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/;
 /**
  * Validate the declared types, throwing on anything that would install and then not work.

package/lib/utils/ship/msi.d.ts

@@ -0,0 +1,126 @@
+import type { HostOs, PackSettings } from './types.js';
+/**
+ * The UUID namespace every GUID in a generated `.msi` is derived under.
+ *
+ * A CONSTANT, and changing it is a breaking change rather than a cosmetic one:
+ * the `UpgradeCode` derived from it is how Windows Installer recognises an
+ * already-installed copy of the same product, so a new namespace makes every
+ * future release a SECOND product that installs beside the old one instead of
+ * over it. Written down here rather than passed in for that reason — a knob would
+ * be a knob that silently forks a product line.
+ */
+export declare const MSI_UUID_NAMESPACE = "7b3a1f6e-0c4d-4a2b-9e51-3d8c6f2a0b14";
+/** RFC 4122 § 4.3 name-based UUID, SHA-1 flavour. */
+export declare function uuid5(namespace: string, name: string): string;
+/**
+ * The code that identifies the PRODUCT LINE, stable across every version.
+ *
+ * Derived from the app id alone. That is what `MajorUpgrade` compares, so it must
+ * NOT move when the version does — an `UpgradeCode` that changed per release would
+ * leave every old version installed beside the new one, silently, with two entries
+ * in Add/Remove Programs and two copies on disk.
+ */
+export declare function msiUpgradeCode(settings: PackSettings): string;
+/**
+ * The code that identifies THIS build, and it has to move when the version does.
+ *
+ * The exact inverse of {@link msiUpgradeCode}: Windows Installer refuses to
+ * install a second package carrying a `ProductCode` it already has, so a code that
+ * did not change per version would make an upgrade a no-op. The arch is in the
+ * material because an x64 and a (future) arm64 build of one version are two
+ * products, not one.
+ */
+export declare function msiProductCode(settings: PackSettings, archLabel: string): string;
+/** A component's GUID, stable for as long as its path is. */
+export declare function msiComponentGuid(settings: PackSettings, path: string): string;
+/**
+ * MSI's `ProductVersion`, which is a much smaller vocabulary than npm's.
+ *
+ * `major.minor.build`, with `major`/`minor` at most 255 and `build` at most 65535 —
+ * anything outside that is not a version Windows Installer will compare, and the
+ * fourth field it accepts is IGNORED by upgrade detection, which is why nothing is
+ * ever put there.
+ *
+ * A PRERELEASE IS REFUSED rather than truncated, and that is the interesting case.
+ * `normaliseVersion` turns `1.2.0-rc.1` into `1.2.0~rc.1` because dpkg and rpm sort
+ * a `~` before the release; MSI has no such spelling, so the only two options were
+ * to drop the suffix or to say no. Dropping it makes `1.2.0~rc.1` and `1.2.0` the
+ * same `ProductVersion` — two products `MajorUpgrade` cannot tell apart, so
+ * installing the release over the candidate leaves BOTH on the machine. That is
+ * the "installs cleanly, does the wrong thing" class, produced by the field meant
+ * to prevent it.
+ */
+export declare function msiProductVersion(version: string): string;
+/**
+ * An MSI `Identifier`: `[A-Za-z_][A-Za-z0-9_.]{0,71}`.
+ *
+ * The readable tail is not decoration — `msiinfo export <msi> File` is the oracle,
+ * and an id of pure hash makes a mismatch unreadable. The digest is what makes it
+ * UNIQUE: it is taken over the full path, so two files whose last 57 characters
+ * agree still differ. `renderWxs` asserts uniqueness anyway rather than trusting
+ * 48 bits, because the failure of a collision is two files fighting over one row.
+ */
+export declare function msiIdentifier(prefix: string, path: string): string;
+/** One payload file, as the installer will address it. */
+export interface MsiFile {
+    /** Program-directory-relative path, POSIX-separated. */
+    path: string;
+    /**
+     * Where the bytes are, RELATIVE to the directory holding the `.wxs` and
+     * POSIX-separated — see measurement 2 in this file's header. An absolute path
+     * would make the document unusable on the second machine that compiles it.
+     */
+    source: string;
+}
+/** Where {@link buildMsi} writes the payload, and therefore what `Source=` is relative to. */
+export declare const MSI_PAYLOAD_DIR = "root";
+export interface WxsInput {
+    settings: PackSettings;
+    /** Everything the program directory carries, in any order. */
+    files: readonly MsiFile[];
+    /** The directory the installer lays down — `windowsProgramDirName(settings)`. */
+    programDirName: string;
+    /** The format's spelling of the architecture, e.g. `x64`. */
+    archLabel: string;
+}
+/**
+ * Render the installer's source document.
+ *
+ * PURE — a string in, a string out, no filesystem and no compiler — which is what
+ * makes every decision above unit-testable on a machine with neither backend
+ * installed. The one thing it cannot answer is whether a compiler accepts what it
+ * wrote, and that is what the two legs are for.
+ */
+export declare function renderWxs(input: WxsInput): string;
+/** Which compiler a host has. */
+export type MsiBackend = 'wixl' | 'wix3';
+/**
+ * The backend for one host.
+ *
+ * A FUNCTION of the host and nothing else, so the choice is testable from either
+ * OS. `assertHostCanFinish` has already refused anything but these two by the time
+ * this runs — the throw is for the caller that forgets to.
+ */
+export declare function msiBackendFor(host: string): MsiBackend;
+export interface MsiPackInput {
+    settings: PackSettings;
+    files: readonly MsiFile[];
+    programDirName: string;
+    archLabel: string;
+    /** Working root for the rendered document and the compiler's intermediates. */
+    workDir: string;
+    /** Absolute path the finished `.msi` is written to. */
+    target: string;
+    verbose: boolean;
+    /** Injected so the dispatch is testable off the host it selects for. */
+    host?: HostOs;
+}
+/**
+ * Render the document and compile it into `input.target`.
+ *
+ * The `.wxs` is KEPT in `workDir` rather than written to a temporary file, and
+ * that is deliberate: it is the one artifact of this milestone a human can read,
+ * it is what a bug report should carry, and it is what the Windows leg compiles a
+ * SECOND time with WiX to produce the file the Linux oracle reads back.
+ */
+export declare function buildMsi(input: MsiPackInput): Promise<string>;