@gjsify/cli 0.44.0 → 0.46.0

package/lib/utils/ship/layout.js

@@ -0,0 +1,504 @@
+// WHERE a payload's files land, per operating system (ADR 0024 § 2, § A2).
+//
+// The payload is produced ONCE and is identical everywhere; what differs is the
+// layout. Up to here that difference was a single string — `FormatDescriptor.prefix`,
+// `/usr` for deb and rpm, `/app` for a Flatpak — because every Linux format keeps
+// the same `bin/`, `lib/<name>/`, `share/…` shape underneath it. `Contents/MacOS`
+// is the first layout that is NOT a prefix substitution: the launcher, the bundle,
+// the shared libraries and the data tree each move somewhere different, and on
+// macOS the native files leave the bundle directory altogether for
+// `Contents/Frameworks`.
+//
+// So the layout is a MAP from the prefix-relative plan to a stage-relative path,
+// and `planStage` keeps producing the prefix-relative plan for all three. That
+// split is what makes the claim checkable: one payload, three layouts, and the
+// file SET has to be identical modulo this map (`tests/e2e/ship-layout`).
+//
+// It also draws the line a third-party app author needs. Everything structural
+// here belongs to the OS — `Contents/MacOS` is Apple's, `%~dp0` is cmd.exe's.
+// Everything with a NAME in it comes from the consumer's own `gjsify.ship` block:
+// the `<App>.app` directory is `name`, the launcher inside it is `binaryName`, and
+// the data tree is addressed by `appId`. Nothing here is derived from gjsify's own
+// tree, and nothing here has a gjsify-specific default.
+import { posix } from 'node:path';
+import { buildGuiLauncher } from './pe-launcher.js';
+import { BUNDLE_INFO_PLIST, BUNDLE_PKGINFO, renderInfoPlist, renderPkgInfo } from './plist.js';
+import { SHARE } from './share-dirs.js';
+/**
+ * Characters a `<App>.app` directory name may not contain.
+ *
+ * `/` is the POSIX separator and `:` is HFS+'s — the Finder shows a stored `:` as
+ * a `/` and vice versa, so a name carrying either produces a bundle whose
+ * directory is not the one its own metadata names. Refused here rather than at
+ * `hdiutil` time, which is three milestones away and on another host.
+ */
+const BUNDLE_NAME_FORBIDDEN = /[/:\\]/;
+/**
+ * The value `ATSApplicationFontsPath` takes for this bundle, or nothing when the
+ * payload carries no face (ADR 0038).
+ *
+ * DERIVED THROUGH `place()`, over a file the payload actually holds, rather than
+ * written out as `share/fonts/<appId>`. The key is documented as a path relative
+ * to `Contents/Resources`, which is this layout's `dirs.other` — so running the
+ * real map on a real entry and taking the Resources prefix back off is the one
+ * spelling that cannot come apart from where the faces were staged. A literal
+ * would keep pointing at the old directory the day `dirs` changes, and macOS
+ * reports an empty font directory the way it reports everything else here: not at
+ * all.
+ */
+function darwinFontsPath(identity, payload) {
+    const dir = `${SHARE.fonts}/${identity.appId}`;
+    const face = payload.find((file) => file.path.startsWith(`${dir}/`));
+    if (face === undefined)
+        return undefined;
+    const dirs = LAYOUTS.darwin.dirs(identity);
+    return posix.relative(dirs.other, posix.dirname(place(LAYOUTS.darwin, identity, face.path)));
+}
+function appBundleDir(identity) {
+    if (BUNDLE_NAME_FORBIDDEN.test(identity.name)) {
+        throw new Error(`gjsify ship: the macOS layout would put this app in "${identity.name}.app", and a bundle ` +
+            'directory may contain no "/", "\\" or ":" — HFS+ and the Finder swap the first two, so the ' +
+            'bundle would not be the one its own metadata names. Set `gjsify.ship.name` to the display ' +
+            'name you want on disk.');
+    }
+    return `${identity.name}.app`;
+}
+export const LAYOUTS = {
+    linux: {
+        name: 'linux',
+        os: 'linux',
+        shippedRuntime: 'gjs',
+        launcherExt: '',
+        root: () => '',
+        // The app id in the directory name is what makes `/usr/lib/<pkg>/` a
+        // directory the PACKAGE owns — the prefix is shared with every other
+        // package on the system. Inside a `.app` or a program directory nothing
+        // is shared, which is why the other two rows drop it.
+        dirs: (identity) => ({
+            launcher: 'bin',
+            bundle: `lib/${identity.binaryName}`,
+            native: `lib/${identity.binaryName}/gi`,
+            data: 'share',
+            other: '',
+        }),
+        // A `/usr` prefix has no manifest of its own — everything a Linux package
+        // says about itself is in the `.deb`/`.rpm` header or in the freedesktop
+        // files the payload already carries.
+        metadata: () => [],
+        // Every architecture Debian and rpm have a name for, which is what
+        // `DEBIAN_ARCH`/`RPM_ARCH` already enumerate — the layout adds nothing.
+        arches: null,
+    },
+    darwin: {
+        name: 'darwin',
+        os: 'darwin',
+        shippedRuntime: 'node',
+        // GJS does exist on macOS — Homebrew ships it and the `macos` CI leg runs
+        // `test:gjs` on both arches — so a launcher naming it is true of a
+        // developer's machine and NOT of a `.app` a stranger downloads:
+        // `packages/node-gi/scripts/build-gtk-runtime-darwin.mjs` records that GJS
+        // ships no relocation, which is why § 4 derives Node here.
+        runtimeGap: 'the staged launcher execs an interpreter off `PATH`, which a downloaded `.app` cannot assume — ' +
+            'macOS ships no Node, and there is no RELOCATABLE GJS (`build-gtk-runtime-darwin.mjs`: "GJS ' +
+            'ships no relocation"), so ADR 0024 § 4 derives Node here. A self-contained bundle needs `@gjsify/node-runtime-darwin-<arch>` and a ' +
+            '`--app node` payload (#1354 M0), or `@gjsify/gjs-runtime-darwin-<arch>` (ADR 0024 stage 7).',
+        // THE ONE LAYOUT WHERE THE ENV VARIABLE IS NOT THE MECHANISM, and assuming it
+        // was is the mistake this comment exists to stop being made again. macOS Pango
+        // is CORETEXT, not fontconfig: GTK's own `meson.build` carries
+        // `fontconfig_dep = []  # only used in x11 backend` and Homebrew's gtk4 formula
+        // builds `-Dx11-backend=false -Dmacos-backend=true`, while cairo's `quartz`
+        // option defaults to `auto` and auto-enables on darwin — so a `fonts.conf`
+        // inside a `.app` would be inert twice over, wrong Pango backend AND no
+        // GTK-side fontconfig. `XDG_DATA_DIRS` still carries the icons and the schemas
+        // here; it does not carry the faces.
+        //
+        // What does is `ATSApplicationFontsPath`, emitted into `Info.plist` by
+        // `metadata` above — Apple's own per-app activation, and the ORDERING is why it
+        // beats a runtime call rather than merely being tidier:
+        // `pango_core_text_font_map_changed()` only bumps a serial, there is no
+        // `kCTFontManagerRegisteredFontsChangedNotification` observer and no re-scan
+        // path in `pangocoretext-fontmap.c`, so a face registered after the font map
+        // initialises is not recoverable by poking it. The system activates this key's
+        // directory at LAUNCH, before any of the app's code runs.
+        fontGap: 'the faces are staged in `share/fonts/<appId>` and `Info.plist` carries `ATSApplicationFontsPath` ' +
+            "at it, which is macOS's own per-app activation — NOT the XDG_DATA_DIRS path, because Pango on " +
+            'macOS is CoreText-backed and GTK is not built against fontconfig there. That the activation ' +
+            "reaches Pango's CoreText font map is UNVERIFIED: no leg in this repository runs a `.app`. " +
+            'Confirm with `PangoCairo.FontMap.get_default().list_families()` in the shipped bundle, and ' +
+            '`PANGOCAIRO_BACKEND=bogus` to print which backend it was built with.',
+        launcherExt: '',
+        root: appBundleDir,
+        // Apple's, all four. `Contents/MacOS` holds executables, `Contents/Resources`
+        // everything that is not, and `Contents/Frameworks` the dylibs — which is
+        // the split that makes this more than a prefix: the `gi/` directory that
+        // sits INSIDE `lib/<name>/` on Linux leaves the bundle directory entirely.
+        dirs: (identity) => {
+            const app = appBundleDir(identity);
+            return {
+                launcher: `${app}/Contents/MacOS`,
+                bundle: `${app}/Contents/Resources/lib`,
+                native: `${app}/Contents/Frameworks`,
+                data: `${app}/Contents/Resources/share`,
+                other: `${app}/Contents/Resources`,
+            };
+        },
+        // The two files that make the directory a BUNDLE. Without `Info.plist`
+        // nothing tells LaunchServices which file under `Contents/MacOS` to exec,
+        // and a `*.app` with no `Info.plist` is a folder with a suffix — which is
+        // exactly what M1 staged. `plist.ts` carries the per-key citations.
+        metadata: (input, payload) => [
+            {
+                path: `${appBundleDir(input)}/${BUNDLE_INFO_PLIST}`,
+                mode: 0o644,
+                source: { kind: 'text', text: renderInfoPlist(input, darwinFontsPath(input, payload)) },
+            },
+            {
+                path: `${appBundleDir(input)}/${BUNDLE_PKGINFO}`,
+                mode: 0o644,
+                source: { kind: 'text', text: renderPkgInfo() },
+            },
+        ],
+        // The two architectures macOS runs on, which is also exactly what
+        // `@gjsify/gtk-runtime-darwin-*` and `@gjsify/node-runtime-darwin-*` are
+        // published for. Nothing upstream blocks a third; there is no third.
+        arches: {
+            only: ['x64', 'arm64'],
+            why: 'macOS runs on x86_64 and Apple silicon and nothing else, so those are the two ' +
+                '`@gjsify/gtk-runtime-darwin-*` and `@gjsify/node-runtime-darwin-*` targets that exist',
+        },
+    },
+    windows: {
+        name: 'windows',
+        os: 'win32',
+        shippedRuntime: 'node',
+        // The stronger of the two gaps, and not a relocation question: there is
+        // no GJS host on Windows AT ALL, so nothing on that OS can run a
+        // `--app gjs` payload until M0's bundled Node exists and the payload is
+        // built for it. Cited to ADR 0024 § 4, which is where the fact is
+        // established — an earlier version of this string cited
+        // `docs/ci-selective.md`, which contains no occurrence of it and whose
+        // four `gjs` mentions are all about the affected-classifier bundle. The
+        // bad citation came in from the ADR's own § 4 table and was promoted into
+        // a user-visible string, which is the worst place for one.
+        runtimeGap: 'the staged launcher execs an interpreter off `PATH`, which a downloaded program directory ' +
+            'cannot assume — Windows ships neither, and there is NO GJS host on Windows at all ' +
+            '(ADR 0024 § 4), so § 4 derives Node here. A self-contained directory needs ' +
+            '`@gjsify/node-runtime-win32-x64` and a `--app node` payload (#1354 M3).',
+        // THE ONE LAYOUT WITH NO DECLARATIVE ANSWER AT ALL, and the three obvious
+        // candidates are each dead for a different reason — written down because each
+        // one looks right until it is read. The first is now dead by MEASUREMENT
+        // rather than by reading (ADR 0038 § W1-W3, Windows 11 / GTK 4.22.4).
+        //
+        //  * FONTCONFIG. gvsbuild does build it and pango links it
+        //    (`-Dfontconfig=enabled`), but `pangocairo-fontmap.c` picks the first
+        //    backend COMPILED IN, in the order coretext → win32 → fc, and cairo's
+        //    meson adds `cairo-win32` unconditionally on a Windows host. So the fc
+        //    font map is built and never selected, and the whole `etc/fonts` +
+        //    `FONTCONFIG_PATH` arrangement `@gjsify/gtk-runtime-win32-x64` ships is
+        //    inert. `APPSHAREFONTDIR` even resolves to exactly this layout
+        //    (`<exe dir>\..\share\fonts`) and feeds the map nothing reads. RUN: with
+        //    a `FONTCONFIG_FILE` naming the face's directory beside WINDOWSFONTDIR
+        //    the default map stays at 82 families without it — and stays at 82 when
+        //    that directory is the ONLY one configured, which is the row that shows
+        //    the map is not reading a misconfigured fontconfig but no fontconfig.
+        //    The control that makes that a finding: a `PangoFT2.FontMap` from the
+        //    SAME config in the SAME process goes 76 → 77 WITH the face, and to 5
+        //    families exclusively. The bundle also ships no `fc-cache.exe`.
+        //  * XDG_DATA_DIRS, which carries the faces on Linux. `FcConfigXdgDataDirs()`
+        //    splits on a HARDCODED colon (its own comment says the spec asks for one),
+        //    while `FC_SEARCH_PATH_SEPARATOR` is `;` here — so `C:\App\share` splits
+        //    into `C` and `\App\share`. The Linux measurement does not carry over.
+        //  * `AddFontResourceEx(..., FR_PRIVATE)`. It registers with GDI, and
+        //    `pango_win32_font_map_init()` has exactly one population call —
+        //    `pango_win32_dwrite_font_map_populate()` — with no `EnumFontFamilies` and
+        //    no `AddFontResource` anywhere in the backend. A GDI-private font cannot
+        //    reach GTK4 text.
+        //
+        // What is left is a runtime call, which a packaging command has no business
+        // making inside somebody's application — so the launcher hands over the
+        // directory (`GJSIFY_FONT_DIR`) and this string names the call. That the call
+        // WORKS is measured too, and on GTK's own map rather than a loose Pango
+        // object: `label.get_pango_context().get_font_map()` IS the default map
+        // there, `add_font_file` on it answers true, families go 82 → 83 and the
+        // family then loads. With the discriminator that keeps "resolved" honest — an
+        // invented family renders as Tahoma at different metrics with a Pango
+        // warning, which is exactly what the probe family did BEFORE the call.
+        fontGap: 'the faces are staged in `share/fonts/<appId>` and the launcher exports GJSIFY_FONT_DIR at it, ' +
+            'but WINDOWS HAS NO DECLARATIVE FONT ACTIVATION and nothing here reaches a bundled face on its ' +
+            'own: GTK4 uses pangowin32, whose font map is populated from DirectWrite and never from ' +
+            'fontconfig or from GDI. MEASURED on Windows 11 / GTK 4.22.4 rather than inferred (ADR 0038 ' +
+            'W1-W5): a FONTCONFIG_FILE naming the staged directory moves the default font map by nothing ' +
+            'even when it is the ONLY configuration present — that map does not read fontconfig, and exposes ' +
+            'no config_changed or set_config with which to make it — while add_font_file on the same map a ' +
+            'Gtk.Label renders through does register the family. So register them at startup: ' +
+            '`PangoCairo.FontMap.get_default().add_font_file(path)` (Pango 1.56+, in the typelib), or the ' +
+            'app renders in a substituted family with no error.',
+        // `.cmd`, not `.bat`: the two differ in whether a failing built-in (`set`,
+        // `path`, `append`) sets ERRORLEVEL, and `.cmd` is the one where it does.
+        launcherExt: '.cmd',
+        root: () => '',
+        // A program directory has no imposed shape, so this one is chosen for the
+        // LOADER: `lib/` is what the launcher prepends to `PATH`, because Windows
+        // has no rpath — a DLL is found on `PATH`, in the directory of the image
+        // that loaded it, or not at all.
+        dirs: () => ({ launcher: '', bundle: 'app', native: 'lib', data: 'share', other: '' }),
+        // NO METADATA, and one PROGRAM. A Windows installer's metadata lives in the
+        // `.msi`'s own tables, not in a file inside the program directory —
+        // `msi.ts` puts every such fact in the `Product`/`Package` attributes of the
+        // document it renders — so this row still owns no manifest, and the field is
+        // not a macOS detail wearing a general name.
+        //
+        // What it DOES own is the GUI-subsystem launcher beside the `.cmd`, and it
+        // arrives through this seam rather than through a branch in the stager,
+        // which is exactly what the field's contract says a fourth row should do.
+        //
+        // A SECOND LAUNCHER, NOT A REPLACEMENT. The `.cmd` makes every environment
+        // decision, is what `assertLauncherMatchesInterpreter` and
+        // `.github/ship-oracle/verify-program-dir.py` read back, and is the right
+        // entry point in a terminal. The `.exe` is the entry point for a
+        // double-click and for the shortcut an `.msi` writes — the two launches
+        // Windows gives a console window today, because `cmd.exe` is a
+        // console-subsystem image (ADR 0024 § M3). It RUNS the `.cmd`.
+        //
+        // AND ONLY FOR THE ARCHITECTURE IT IS. The stub is x86-64 machine code, so
+        // staging it into a tree labelled `arm64` would have
+        // `assertPayloadMatchesArch` refuse the STAGE over a file the author never
+        // named — turning "this layout has no arm64 runtime" (a warning, with
+        // `Layout.arches.why` to act on) into "your payload is mislabelled" (a
+        // refusal, about our own file). `arches.only` already says there is no
+        // other Windows architecture; a stage for one stays assemblable and stays
+        // unpackable, which is the split `Layout.runtimeGap` draws everywhere else.
+        metadata: (input) => input.arch === 'x64'
+            ? [
+                {
+                    path: windowsGuiLauncherPath(input),
+                    mode: 0o755,
+                    source: { kind: 'bytes', data: buildGuiLauncher({ logLeaf: windowsLaunchLogLeaf(input) }) },
+                },
+            ]
+            : [],
+        // ONE, and the blocker is a project we do not own. `wingtk/gvsbuild`
+        // hardcodes `self.platform = "x64"` in `utils/base_project.py` and its last
+        // five releases publish exactly two assets each, both x64 — so there is no
+        // arm64 GTK to build `@gjsify/gtk-runtime-win32-arm64` OUT OF, and on
+        // Windows that bundle is the only GTK there is. `@gjsify/node-gi` declares
+        // `win32-x64` only for the same reason. Tracked in #1117, which also
+        // records why an exploratory arm64 leg must NOT be added: its first step
+        // downloads a ZIP that does not exist, so it would be red by construction.
+        arches: {
+            only: ['x64'],
+            why: 'gvsbuild publishes no arm64 GTK (it hardcodes `self.platform = "x64"`), so there is nothing ' +
+                'to build `@gjsify/gtk-runtime-win32-arm64` out of and no GTK for a Windows/ARM artifact to ' +
+                'load — the blocker is upstream and is tracked in gjsify/gjsify#1117',
+        },
+    },
+};
+/** Every layout name, derived from the table so a new row cannot be missed. */
+export const LAYOUT_NAMES = Object.keys(LAYOUTS);
+/**
+ * `HostOs` → the layout for it.
+ *
+ * Derived rather than a second table: `LAYOUTS` is already total over
+ * `LayoutName`, so reading its rows back means a fourth OS cannot be added to one
+ * list and forgotten in the other.
+ */
+const BY_OS = new Map(LAYOUT_NAMES.map((name) => [LAYOUTS[name].os, LAYOUTS[name]]));
+/** Stage-relative path of the launcher this layout puts in front of the app. */
+export function launcherPath(layout, identity) {
+    return posix.join(layout.dirs(identity).launcher, `${identity.binaryName}${layout.launcherExt}`);
+}
+/**
+ * Stage-relative path of the windows layout's GUI launcher.
+ *
+ * IT MUST BE `<launcherPath minus `.cmd`>.exe` AND THE STUB DEPENDS ON IT:
+ * `buildGuiLauncher` finds its `.cmd` by overwriting the last three characters of
+ * its own module filename, which is a three-character store instead of a path
+ * search only because the two names differ in exactly those bytes. Deriving both
+ * from `LAYOUTS.windows.launcherExt` here is what keeps that true — renaming the
+ * batch launcher to `.bat` would otherwise leave a stub looking for a file that
+ * is not there, at exit 0, with a window that never appears.
+ */
+export function windowsGuiLauncherPath(identity) {
+    const layout = LAYOUTS.windows;
+    if (layout.launcherExt.length !== 4) {
+        throw new Error(`gjsify ship: the windows launcher extension is "${layout.launcherExt}" and the GUI stub can only ` +
+            'reach a four-character one — it rewrites the last three characters of its own filename rather ' +
+            'than searching for a path (`utils/ship/pe-launcher.ts`).');
+    }
+    return posix.join(layout.dirs(identity).launcher, `${identity.binaryName}.exe`);
+}
+/**
+ * What the windows GUI launcher calls the file it writes under `%TEMP%`.
+ *
+ * Named after the binary rather than the display name: `%TEMP%` is shared by
+ * every application on the machine, and `binaryName` is the one identifier this
+ * project already refuses to let collide.
+ */
+export function windowsLaunchLogLeaf(identity) {
+    return `${identity.binaryName}.launch.log`;
+}
+/**
+ * The layout for one `process.platform` token, refusing every alias.
+ *
+ * STRICT, and that is the difference from {@link resolveLayout}, which is for a
+ * word a human typed. This one is for the stage manifest's `target.os` — a
+ * cross-host WIRE FORMAT with exactly one legal spelling per OS. Accepting
+ * `"windows"` there and silently comparing it as `win32` would mean
+ * `--expect-target win32-x64` no longer compares against the file's content:
+ * two manifests with different bytes in that field would both match, and the
+ * flag's whole job is to catch a job that downloaded the wrong artifact.
+ */
+export function layoutForOs(os) {
+    const layout = BY_OS.get(os);
+    if (layout === undefined) {
+        throw new Error(`"${os}" is not a \`process.platform\` token this gjsify has a layout for. ` +
+            `Known: ${LAYOUT_NAMES.map((name) => LAYOUTS[name].os).join(', ')} — the ` +
+            '`${process.platform}-${process.arch}` spelling, so `win32` and never `windows`.');
+    }
+    return layout;
+}
+/**
+ * Resolve the positional to a layout.
+ *
+ * Accepts BOTH vocabularies (`windows` and `win32`) for the reason
+ * {@link LayoutName} records: the ADR writes one and `--expect-target` prints the
+ * other, and refusing whichever the user has in front of them is a papercut with
+ * no upside. The canonical answer is a single `Layout`, so nothing downstream has
+ * two spellings to reconcile. NOT for the stage manifest — see {@link layoutForOs}.
+ */
+export function resolveLayout(raw) {
+    const name = raw.trim().toLowerCase();
+    if (Object.hasOwn(LAYOUTS, name))
+        return LAYOUTS[name];
+    const byOs = BY_OS.get(name);
+    if (byOs !== undefined)
+        return byOs;
+    throw new Error(`gjsify ship: "${raw}" is not an operating system this command has a layout for. ` +
+        `Known: ${LAYOUT_NAMES.join(', ')} (\`win32\` is accepted for \`windows\`, because that is the ` +
+        'spelling `--expect-target <os>-<arch>` uses).');
+}
+/**
+ * The layout for the host this process is running on.
+ *
+ * What `gjsify ship` picks when the positional is absent, so a bare `gjsify ship`
+ * on Linux keeps assembling the Linux layout and packing `.deb` + `.rpm` exactly
+ * as before. A host whose platform has no layout is refused BY NAME rather than
+ * silently treated as Linux — a payload laid out for `/usr` and labelled for a
+ * FreeBSD would install and not run.
+ */
+export function hostLayout(platform = process.platform) {
+    const layout = BY_OS.get(platform);
+    if (layout === undefined) {
+        throw new Error(`gjsify ship: this host is ${platform}, which has no layout. Name the one you want — ` +
+            `\`gjsify ship <${LAYOUT_NAMES.join('|')}> --stage\` — assembly is not host-bound ` +
+            '(ADR 0024 § A1).');
+    }
+    return layout;
+}
+/**
+ * Refuse an architecture this layout cannot be assembled for, naming the blocker.
+ *
+ * AT STAGE TIME, which is the whole point — see {@link Layout.arches}. The
+ * message carries the row's own `why` rather than a generic "unsupported", because
+ * the two refusals a reader can act on are different jobs: `x64` is what a Windows
+ * artifact is built for TODAY, and `win32-arm64` is blocked in a repository we do
+ * not own. Telling an author "unknown architecture" for the second one would send
+ * them to look for a flag.
+ *
+ * `process.arch` spelling on both sides, so the value quoted back is the one the
+ * user typed after `--arch`.
+ */
+export function assertLayoutSupportsArch(layout, arch) {
+    const arches = layout.arches;
+    if (arches === null || arches.only.includes(arch))
+        return;
+    throw new Error(`gjsify ship: the ${layout.name} layout is not assemblable for \`--arch ${arch}\` — ` +
+        `${arches.only.length === 1 ? 'the only architecture it has' : 'the architectures it has'} ` +
+        `${arches.only.length === 1 ? 'is' : 'are'} ${arches.only.join(', ')}.\n` +
+        `    ${arches.why}.\n` +
+        '    `--arch` names the architecture the PAYLOAD was built for and cross-compiles nothing, so ' +
+        'there is no\n' +
+        '    flag that makes this work — the artifact would carry a runtime that does not exist.');
+}
+/**
+ * Map one PREFIX-RELATIVE planned path to where this layout keeps it.
+ *
+ * The plan is written once, in the Linux/XDG shape, and this is the only place
+ * that knows any other. Order matters: `lib/<name>/gi/` is tested before
+ * `lib/<name>/`, because on macOS those two go to different directories.
+ */
+export function place(layout, identity, rel) {
+    const dirs = layout.dirs(identity);
+    if (rel === `bin/${identity.binaryName}`)
+        return launcherPath(layout, identity);
+    const libPrefix = `lib/${identity.binaryName}/`;
+    const giPrefix = `${libPrefix}gi/`;
+    if (rel.startsWith(giPrefix))
+        return posix.join(dirs.native, rel.slice(giPrefix.length));
+    if (rel.startsWith(libPrefix))
+        return posix.join(dirs.bundle, rel.slice(libPrefix.length));
+    if (rel.startsWith('bin/'))
+        return posix.join(dirs.launcher, rel.slice('bin/'.length));
+    if (rel.startsWith('share/'))
+        return posix.join(dirs.data, rel.slice('share/'.length));
+    return posix.join(dirs.other, rel);
+}
+/**
+ * Apply a layout to a whole planned payload, and add what the layout itself owns.
+ *
+ * THREE SOURCES, one destination namespace. The mapped files come from
+ * `planStage`'s prefix-relative plan; {@link Layout.metadata} adds the files that
+ * have no prefix-relative counterpart at all (`Contents/Info.plist`); `carried`
+ * adds the runtime the artifact ships inside itself (#1354 M2b — the interpreter,
+ * the relocated GTK closure, the node-gi addon). All three go through the same
+ * uniqueness check, which is what makes the other two safe: an `extraFiles`
+ * destination that maps onto a metadata path is refused by name instead of
+ * silently replacing the file that makes the bundle a bundle.
+ *
+ * `carried` is already stage-relative and deliberately NOT mapped. A relocated
+ * closure's every internal relation is relative — `@loader_path/<leaf>` install
+ * names, `@loader_path/../../..` in `loaders.cache`, `@loader_path/gtk/lib` on the
+ * addon — so the tree survives the copy only if it is copied as a tree. Routing it
+ * through the prefix-relative plan would put it through
+ * `gjsify.ship.bundledTypelibs`'s flattening (`plan.ts`: `posix.join(libDir, 'gi',
+ * basename(file))`), which destroys all three at once.
+ *
+ * The uniqueness check is not decoration for the mapped half either. `planStage`
+ * deduplicates on the PREFIX-RELATIVE path — that is how `gjsify.ship.extraFiles`
+ * is documented to override a default — but the MAP can bring two distinct
+ * prefix-relative paths together: on Windows the launcher becomes
+ * `<binaryName>.cmd` at the program root, which an `extraFiles` destination can
+ * name directly. Without this the second one silently wins and which one that is
+ * depends on plan order — the "installs cleanly, does nothing" class this command
+ * is built against.
+ */
+export function placeStage(layout, identity, files, carried = []) {
+    const byPlaced = new Map();
+    const out = [];
+    const claim = (path, from, file) => {
+        const previous = byPlaced.get(path);
+        if (previous !== undefined) {
+            throw new Error(`gjsify ship: in the ${layout.name} layout both ${previous} and ${from} install as ` +
+                `${path}. Two payload files cannot share one destination — one would silently replace the ` +
+                'other. Rename the `gjsify.ship.extraFiles` destination that collides.');
+        }
+        byPlaced.set(path, from);
+        out.push({ ...file, path });
+    };
+    for (const file of files)
+        claim(place(layout, identity, file.path), file.path, file);
+    // The layout's own files are ALREADY stage-relative — they were never in the
+    // prefix-relative plan, so there is nothing to map. `<layout> metadata` rather
+    // than a path as the origin label, because a collision message naming
+    // `Contents/Info.plist` as both sides would say nothing.
+    for (const file of layout.metadata(identity, files)) {
+        claim(file.path, `the ${layout.name} layout's own metadata`, file);
+    }
+    // A THIRD source, and stage-relative like the second: the runtime the bundle
+    // CARRIES (`utils/ship/app-runtime.ts`). It goes through `claim` for the reason
+    // the metadata does — an `extraFiles` destination landing on a staged dylib
+    // would otherwise replace it silently, and the bundle would look complete.
+    for (const file of carried)
+        claim(file.path, `the runtime staged into the ${layout.name} artifact`, file);
+    return out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}

package/lib/utils/ship/localize-metadata.d.ts

@@ -0,0 +1,22 @@
+/** The generated metadata, before or after translation. */
+export interface LocalizableMetadata {
+    /** The rendered AppStream MetaInfo XML. */
+    metainfo: string;
+    /** The rendered desktop entry — `undefined` for `kind: 'cli'`. */
+    desktopEntry?: string;
+}
+/** A staged catalogue, in the `<lang>/LC_MESSAGES/<domain>.mo` shape `discoverLocales` guarantees. */
+export interface StagedCatalogue {
+    rel: string;
+    abs: string;
+}
+/**
+ * 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 declare function localizeMetadata(metadata: LocalizableMetadata, localeFiles: readonly StagedCatalogue[]): LocalizableMetadata;

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}`;
+}