@gjsify/cli 0.40.0 → 0.42.0

package/lib/utils/run-node.js

@@ -15,12 +15,12 @@
 //
 // The node binary is `process.execPath` when the CLI runs under Node, else PATH `node` — under
 // the GJS bundle `process.execPath` is `gjs`, which cannot run a `--app node` bundle.
-import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { computeNativeEnvForBundle } from './run-gjs.js';
 import { RUNTIMES } from './runtimes.js';
+import { describeExit, spawnToCompletion } from './spawn.js';
 /**
  * Walk up from `startDir` for `<node_modules>/@gjsify/node-gi`, returning its package directory
  * or null. A plain fs walk because Node's own resolver is not available under the GJS-bundled CLI.
@@ -60,7 +60,7 @@ export function nodeBinary() {
  * Run a `--app node` bundle on Node.js with the native typelib env set (same detection as
  * {@link runGjsBundle}). Throws when `@gjsify/node-gi` is not resolvable.
  */
-export async function runNodeBundle(bundlePath, extraArgs = [], options = {}) {
+export async function runNodeBundle(bundlePath, extraArgs = [], options) {
     const cwd = process.cwd();
     if (!resolveNodeGiForBundle(bundlePath, cwd)) {
         throw new Error('Cannot run the storybook on Node: `@gjsify/node-gi` is not installed.\n' +
@@ -74,27 +74,28 @@ export async function runNodeBundle(bundlePath, extraArgs = [], options = {}) {
     // Echo on stderr, so a child speaking a protocol on stdout stays uncontaminated.
     const cmd = [nodeBin, ...nodeArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
     console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${cmd}`);
-    const child = spawn(nodeBin, nodeArgs, { env, stdio: 'inherit' });
-    await new Promise((resolvePromise, reject) => {
-        child.on('close', (code) => {
-            if (code !== 0)
-                reject(new Error(`node exited with code ${code}`));
-            else
-                resolvePromise();
-        });
-        child.on('error', reject);
-    }).catch((err) => {
+    let result;
+    try {
+        result = await spawnToCompletion(nodeBin, nodeArgs, { completion: options.completion, env });
+    }
+    catch (err) {
         console.error(err.message);
-        process.exit(1);
-    });
+        return process.exit(1);
+    }
+    if (result.code !== 0) {
+        console.error(`node exited with ${describeExit(result)}`);
+        return process.exit(result.code ?? 1);
+    }
     if (options.exitOnSuccess)
-        process.exit(0);
+        return process.exit(0);
 }
 /**
  * Whether a `--app node` bundle actually consumes `@gjsify/node-gi` — kept EXTERNAL, so a bundle
  * using gi:// imports the shim by name. A plain Node app does NOT, and must run on node/bun/deno
- * WITHOUT node-gi installed, which is why the check is conditional here and not unconditional
- * like the storybook path.
+ * WITHOUT node-gi installed, which is why the check is conditional rather than a flat "this is a
+ * node bundle, demand node-gi". The supervised launcher (`utils/watch-loop.ts`) asks the same
+ * question for the same reason: `gjsify dev` on a web-server template builds a node bundle that
+ * never reaches a typelib.
  */
 export function bundleRequiresNodeGi(bundlePath) {
     try {
@@ -112,7 +113,7 @@ export function bundleRequiresNodeGi(bundlePath) {
  *
  * `gjs` is intentionally NOT handled here — the caller dispatches it to {@link runGjsBundle}.
  */
-export async function runRuntimeBundle(runtime, bundlePath, extraArgs = [], options = {}) {
+export async function runRuntimeBundle(runtime, bundlePath, extraArgs = [], options) {
     const cwd = process.cwd();
     const resolvedBundle = resolve(bundlePath);
     if (bundleRequiresNodeGi(resolvedBundle) && !resolveNodeGiForBundle(resolvedBundle, cwd)) {
@@ -131,32 +132,24 @@ export async function runRuntimeBundle(runtime, bundlePath, extraArgs = [], opti
     const shown = [cmd, ...launchArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
     if (!options.quiet)
         console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${shown}`);
-    const child = spawn(cmd, launchArgs, { env, stdio: 'inherit' });
     // Re-raise the CHILD's own code rather than a blanket 1 — a script run through
     // `--node-script` reports its status through this path, and a caller reading `$?` needs
-    // the real one.
-    let failed = false;
-    let childCode = 1;
-    await new Promise((resolvePromise, reject) => {
-        child.on('close', (code) => {
-            if (code !== 0) {
-                childCode = code ?? 1;
-                reject(new Error(`${runtime} exited with code ${code}`));
-            }
-            else
-                resolvePromise();
-        });
-        child.on('error', reject);
-    }).catch((err) => {
+    // the real one. A spawn failure has no code of its own and falls back to 1.
+    const failed = (code) => {
+        process.exitCode = code;
+        return process.exit(code);
+    };
+    let result;
+    try {
+        result = await spawnToCompletion(cmd, launchArgs, { completion: options.completion, env });
+    }
+    catch (err) {
         console.error(err.message);
-        failed = true;
-    });
-    // `return process.exit(…)`, and a flag rather than an exit inside the `catch`: under GJS
-    // `process.exit()` is deferred and RETURNS, so a bare call in the catch fell through to the
-    // `exitOnSuccess` line below and scheduled a second exit.
-    if (failed) {
-        process.exitCode = childCode;
-        return process.exit(childCode);
+        return failed(1);
+    }
+    if (result.code !== 0) {
+        console.error(`${runtime} exited with ${describeExit(result)}`);
+        return failed(result.code ?? 1);
     }
     if (options.exitOnSuccess)
         return process.exit(0);

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

@@ -33,6 +33,11 @@ export interface DependsInputs {
         deb: string;
         rpm: string;
     }>;
+    /**
+     * Paths of typelib files the payload carries itself. The namespaces they cover need no distro
+     * dependency — and are derived from these filenames, never declared separately.
+     */
+    bundledTypelibs?: readonly string[];
     /** Minimum GJS. Default {@link DEFAULT_GJS_FLOOR}. */
     minGjsVersion?: string;
 }

package/lib/utils/ship/depends.js

@@ -105,7 +105,30 @@ const TYPELIB_PACKAGES = {
     'Notify-0.7': { deb: 'gir1.2-notify-0.7', rpm: 'libnotify' },
     'Vte-3.91': { deb: 'gir1.2-vte-3.91', rpm: 'vte291-gtk4' },
     'Manette-0.2': { deb: 'gir1.2-manette-0.2', rpm: 'libmanette' },
+    // libgda — what `@gjsify/sqlite` binds, so every project with a local database lands here.
+    // The rpm name is measured on this machine (`rpm -qf …/Gda-6.0.typelib` → libgda); the deb name
+    // follows the `gir1.2-<name>-<version>` convention every row above uses and is NOT verified
+    // against a Debian system. Said plainly because a wrong name fails at `apt install` with a
+    // clear error, while no row at all fails the BUILD of every such project.
+    'Gda-6.0': { deb: 'gir1.2-gda-6.0', rpm: 'libgda' },
 };
+/**
+ * A typelib the payload CARRIES, rather than one the system provides.
+ *
+ * `@gjsify/*`'s native bridges ship their own `.typelib` inside the package —
+ * `GjsifyHttpSoupBridge`, which `@gjsify/http`'s server pulls in unconditionally,
+ * plus `GjsifyHttp2`, `GjsifySabNative` and the rest of the `*-native` set. No
+ * distribution has ever packaged a `gir1.2-gjsifyhttpsoupbridge` and none can:
+ * the file is in the tarball being built. So these are not a gap in the table.
+ * Mapping one would emit a dependency apt and dnf must fail to resolve, and the
+ * module header's rule — an unmapped namespace FAILS the build — is about a
+ * SYSTEM library nobody declared, which is the opposite situation.
+ *
+ * Excluding them is a precondition for widening the namespace scanner rather
+ * than a refinement of it: without this, `gjsify ship` throws on every project
+ * whose bundle reaches one, which includes every `@gjsify/http` server.
+ */
+const BUNDLED_TYPELIB = /^Gjsify[A-Z]/;
 /**
  * The `Depends:` / `Requires:` list for one format.
  *
@@ -114,7 +137,22 @@ const TYPELIB_PACKAGES = {
 export function deriveDepends(format, inputs) {
     const out = [`gjs >= ${inputs.minGjsVersion ?? DEFAULT_GJS_FLOOR}`];
     const unmapped = [];
+    // Namespaces the package SHIPS ITSELF, read off the staged filenames rather than from a
+    // separate declaration: `Gwebgl-0.1.typelib` → `Gwebgl-0.1` and `Gwebgl`. Deriving it is the
+    // point — a project that declared a namespace bundled without the file being there would get
+    // a package that installs and dies at the first import, which is exactly what this check
+    // exists to prevent.
+    const shipped = new Set();
+    for (const file of inputs.bundledTypelibs ?? []) {
+        const match = /([A-Za-z0-9]+)-([\d.]+)\.typelib$/.exec(file);
+        if (!match)
+            continue;
+        shipped.add(`${match[1]}-${match[2]}`);
+        shipped.add(match[1]);
+    }
     for (const namespace of [...new Set(inputs.namespaces)].sort()) {
+        if (BUNDLED_TYPELIB.test(namespace) || shipped.has(namespace))
+            continue;
         const entry = lookupTypelib(namespace, inputs.typelibPackages);
         if (entry === undefined) {
             unmapped.push(namespace);

package/lib/utils/ship/discover.js

@@ -12,15 +12,120 @@ export function discoverPayload(input) {
     const { projectDir, ship } = input;
     const bundlePath = resolveBundle(input);
     const bundleDir = resolve(bundlePath, '..');
+    const localeFiles = discoverLocales(projectDir, ship.localeDir);
     return {
         bundlePath,
         bundleDir,
-        bundleFiles: listFilesRecursive(bundleDir),
+        // Everything beside the bundle, MINUS the locale tree when it lives there.
+        //
+        // `dist/locale/` sits next to `dist/app.gjs.mjs` in the layout
+        // `@gjsify/vite-plugin-gettext` writes by default, and the wholesale bundle staging would
+        // then put every catalogue in `lib/<binary>/locale/` as well as in `share/locale/`.
+        // Measured on a probe package: the same `.mo` appeared at both paths. The `lib/` copy is
+        // dead weight — nothing looks there — and it is the same failure that once shipped the test
+        // suite: whatever is beside the bundle gets carried whether or not it belongs in a package.
+        bundleFiles: withoutLocaleTree(listFilesRecursive(bundleDir), bundleDir, projectDir, ship.localeDir),
         iconFiles: discoverIcons(projectDir, ship.icon ?? input.flatpakIcon),
         schemaFiles: discoverSchemas(projectDir, ship.schemas),
+        typelibFiles: discoverTypelibs(projectDir, ship.bundledTypelibs),
+        localeFiles,
         licenseFile: discoverLicense(projectDir, ship.licenseFile),
     };
 }
+/**
+ * Typelibs (and their shared libraries) the PROJECT ships itself.
+ *
+ * Necessary because gjsify's own GI libraries — `Gwebgl` for the WebGL bridge, the GTK runtime
+ * bundles, the napi host — arrive as npm prebuilds, not as distro packages. An app using one has
+ * no `gir1.2-…` to depend on: it must carry the files, and something must point GI at them.
+ *
+ * A directory rather than a list of files, because a typelib is never alone: `Gwebgl-0.1.typelib`
+ * is useless without `libgwebgl.so`, and staging one without the other produces a package that
+ * installs and then fails at the first import.
+ */
+function discoverTypelibs(projectDir, dirs) {
+    const out = [];
+    for (const dir of dirs ?? []) {
+        const root = resolve(projectDir, dir);
+        if (!existsSync(root)) {
+            throw new Error(`gjsify ship: \`gjsify.ship.bundledTypelibs\` names ${dir}, which does not exist. ` +
+                'A missing directory here means the package would install without the typelib it promises.');
+        }
+        for (const file of listFilesRecursive(root)) {
+            if (/\.typelib$|\.so(\.\d+)*$/.test(file))
+                out.push(join(root, file));
+        }
+    }
+    return out;
+}
+/**
+ * Drop the declared locale tree from the wholesale bundle staging.
+ *
+ * Only when it actually lies inside the bundle directory — a `localeDir` elsewhere in the project
+ * was never part of `bundleFiles` and there is nothing to subtract.
+ */
+function withoutLocaleTree(bundleFiles, bundleDir, projectDir, localeDir) {
+    if (localeDir === undefined)
+        return bundleFiles;
+    const localeRoot = resolve(projectDir, localeDir);
+    const rel = relative(bundleDir, localeRoot);
+    // Outside the bundle dir: `relative` climbs out (`..`) or returns an absolute path.
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel))
+        return bundleFiles;
+    // Only `rel` needs normalising: it comes from `relative`, so it is host-shaped, while
+    // `bundleFiles` is POSIX by `listFilesRecursive`'s contract. Comparing a host-shaped prefix
+    // against POSIX entries matches nothing on Windows — and matching nothing here means the
+    // catalogues quietly ship twice again, on that platform only.
+    const prefix = `${rel.split(sep).join(posix.sep)}${posix.sep}`;
+    return bundleFiles.filter((file) => !`${file}${posix.sep}`.startsWith(prefix));
+}
+/**
+ * Compiled gettext catalogues the project ships (`gjsify.ship.localeDir`).
+ *
+ * Only `.mo` files, and only in the layout `bindtextdomain` actually reads —
+ * `<lang>/LC_MESSAGES/<domain>.mo`. Both refusals cover the same failure, which is the quiet kind:
+ * a catalogue in the wrong place, or left as `.po`, installs perfectly and the app then shows the
+ * untranslated msgid forever. That is indistinguishable from "no translation exists", so it is not
+ * something a user or a maintainer would ever report as a packaging bug.
+ */
+function discoverLocales(projectDir, dir) {
+    if (dir === undefined)
+        return [];
+    const root = resolve(projectDir, dir);
+    if (!existsSync(root)) {
+        throw new Error(`gjsify ship: \`gjsify.ship.localeDir\` names ${dir}, which does not exist. ` +
+            'Compile the catalogues first (msgfmt, or @gjsify/vite-plugin-gettext) — a missing ' +
+            'directory here means the package would install without the translations it promises.');
+    }
+    const out = [];
+    const strays = [];
+    for (const rel of listFilesRecursive(root)) {
+        if (rel.endsWith('.po') || rel.endsWith('.pot')) {
+            strays.push(`${rel} (a .po source; bindtextdomain reads .mo only)`);
+            continue;
+        }
+        if (!rel.endsWith('.mo'))
+            continue;
+        // `listFilesRecursive` normalises to POSIX, so one separator is all there is to split on.
+        const parts = rel.split(posix.sep);
+        if (parts.length !== 3 || parts[1] !== 'LC_MESSAGES') {
+            strays.push(`${rel} (expected <lang>/LC_MESSAGES/<domain>.mo)`);
+            continue;
+        }
+        out.push({ rel: parts.join('/'), abs: join(root, rel) });
+    }
+    if (strays.length > 0) {
+        throw new Error(`gjsify ship: \`gjsify.ship.localeDir\` (${dir}) holds files no catalogue lookup will find:\n` +
+            strays.map((s) => `  ${s}`).join('\n') +
+            '\nA misplaced catalogue installs and then shows nothing, which reads exactly like having ' +
+            'no translation at all. Lay them out as <lang>/LC_MESSAGES/<domain>.mo.');
+    }
+    if (out.length === 0) {
+        throw new Error(`gjsify ship: \`gjsify.ship.localeDir\` (${dir}) contains no \`.mo\` catalogue. ` +
+            'Declaring a locale directory that ships nothing is a promise the package does not keep.');
+    }
+    return out;
+}
 function resolveBundle(input) {
     const declared = input.declaredBundle;
     if (declared === undefined) {

package/lib/utils/ship/launcher.js

@@ -23,7 +23,7 @@ function shellQuote(value) {
 export function renderLauncher(settings, bundleRelPath) {
     const lib = `"$prefix"/lib/${settings.binaryName}`;
     const args = settings.execArgs.map(shellQuote).join(' ');
-    return [
+    const lines = [
         '#!/bin/sh',
         '# Generated by `gjsify ship` — do not edit.',
         'set -e',
@@ -31,7 +31,30 @@ export function renderLauncher(settings, bundleRelPath) {
         'prefix=$(dirname "$(dirname "$self")")',
         'XDG_DATA_DIRS="$prefix/share:${XDG_DATA_DIRS:-/usr/local/share:/usr/share}"',
         'export XDG_DATA_DIRS',
-        `exec gjs -m ${lib}/${bundleRelPath}${args ? ` ${args}` : ''} "$@"`,
-        '',
-    ].join('\n');
+    ];
+    // Typelibs the package carries itself (see `gjsify.ship.bundledTypelibs`). PREPENDED, not
+    // replacing: an app that ships `Gwebgl` still needs the system `Gtk`, and clobbering the path
+    // would trade one missing namespace for all the others. Only emitted when something was
+    // actually staged — an empty `GI_TYPELIB_PATH` entry makes GI search a directory that is not
+    // there, on every import, forever.
+    if (settings.typelibFiles.length > 0) {
+        const giDir = '"$prefix"/lib/' + settings.binaryName + '/gi';
+        for (const variable of ['GI_TYPELIB_PATH', 'LD_LIBRARY_PATH']) {
+            // `${VAR:+:$VAR}` appends the existing value with a separator ONLY when it is set —
+            // a plain `:$VAR` leaves a trailing colon, which both loaders read as "and the current
+            // directory", and a package that silently adds `.` to a library path is a bad package.
+            lines.push(`${variable}=${giDir}\${${variable}:+:$${variable}}`, `export ${variable}`);
+        }
+    }
+    // Where the app's gettext catalogues landed. `bindtextdomain` takes a DIRECTORY and there is no
+    // standard environment variable it reads on its own (`TEXTDOMAINDIR` is honoured by the gettext
+    // command-line tools, not by the library), so the prefix has to reach the app somehow. Passing
+    // it from the launcher keeps the app free of install-layout knowledge, exactly as XDG_DATA_DIRS
+    // above does for icons and schemas — a baked `/usr/share/locale` would be wrong in a Flatpak
+    // and in any `--prefix` tree.
+    if (settings.localeFiles.length > 0) {
+        lines.push('GJSIFY_LOCALE_DIR="$prefix"/share/locale', 'export GJSIFY_LOCALE_DIR');
+    }
+    lines.push(`exec gjs -m ${lib}/${bundleRelPath}${args ? ` ${args}` : ''} "$@"`, '');
+    return lines.join('\n');
 }

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

@@ -28,3 +28,38 @@ export declare function buildTimestamp(bundlePath: string, env?: Record<string,
  * does not run.
  */
 export declare function isArchIndependent(payload: readonly PayloadEntry[]): boolean;
+/**
+ * The `process.arch` token an image says it is built for, or `null` when the
+ * question cannot be answered from the bytes.
+ *
+ * `null` covers three different things on purpose, and all three must stay
+ * silent: a file that is not a native binary at all (most of a payload), a PE
+ * (whose COFF machine field this tree has never parsed — `isNativeBinary` reads
+ * `MZ` and stops), and a Mach-O fat archive, which carries several
+ * architectures and therefore matches any label a caller could pass.
+ */
+export declare function readBinaryArch(data: Uint8Array): string | null;
+/**
+ * Refuse a payload whose binaries disagree with the label the package will carry.
+ *
+ * THE INCIDENT, measured on 0.41.0 before this existed. A project whose payload
+ * carries one x86-64 `.so`, packed on this x86-64 host:
+ *
+ *     gjsify ship --skip-build --arch arm64
+ *     → xarch-demo_1.2.3-1_arm64.deb, xarch-demo-1.2.3-1.aarch64.rpm
+ *     rpm -qp --qf '%{ARCH}'  → aarch64
+ *     the .so inside it       → ELF e_machine 0x3e (x86-64)
+ *
+ * `--arch` LABELS the payload; it does not cross-compile it, and nothing
+ * compared the two. The result installs on an arm64 machine — apt and dnf both
+ * believe the header — and then fails to load, which is this tree's most
+ * expensive failure class with an independent oracle actively confirming the
+ * lie: `rpm` reads the header, and the header was written from the caller's
+ * claim.
+ *
+ * Payload against LABEL, never payload against HOST. Assembling an arm64
+ * artifact on an x64 machine is a supported path — the packers are pure
+ * JavaScript and ADR 0024 § A1 turns it into a design commitment — so a host
+ * comparison would refuse the very case the split exists to allow.
+ */
+export declare function assertPayloadMatchesArch(payload: readonly PayloadEntry[], arch: string): void;

package/lib/utils/ship/payload.js

@@ -40,6 +40,90 @@ export function buildTimestamp(bundlePath, env = process.env) {
 export function isArchIndependent(payload) {
     return !payload.some((entry) => isNativeBinary(entry.data));
 }
+// `process.arch` tokens, keyed by what the image records about itself. Only the
+// values this repository can actually produce are listed; an unknown one reads
+// as "cannot tell" rather than as a mismatch, because refusing an artifact over
+// a machine constant nobody here emits would be a guess wearing a gate's clothes.
+const ELF_MACHINE_TO_ARCH = {
+    0x03: 'ia32',
+    0x15: 'ppc64',
+    0x16: 's390x',
+    0x28: 'arm',
+    0x3e: 'x64',
+    0xb7: 'arm64',
+    0xf3: 'riscv64',
+};
+const MACHO_CPUTYPE_TO_ARCH = {
+    0x00000007: 'ia32',
+    0x0000000c: 'arm',
+    0x01000007: 'x64',
+    0x0100000c: 'arm64',
+};
+/**
+ * The `process.arch` token an image says it is built for, or `null` when the
+ * question cannot be answered from the bytes.
+ *
+ * `null` covers three different things on purpose, and all three must stay
+ * silent: a file that is not a native binary at all (most of a payload), a PE
+ * (whose COFF machine field this tree has never parsed — `isNativeBinary` reads
+ * `MZ` and stops), and a Mach-O fat archive, which carries several
+ * architectures and therefore matches any label a caller could pass.
+ */
+export function readBinaryArch(data) {
+    if (data.byteLength < 20)
+        return null;
+    const magic = ((data[0] << 24) | (data[1] << 16) | (data[2] << 8) | data[3]) >>> 0;
+    if (magic === 0x7f454c46) {
+        // ELF: EI_DATA at offset 5 says which end e_machine (offset 18) is written from.
+        const littleEndian = data[5] === 1;
+        const machine = littleEndian ? data[18] | (data[19] << 8) : (data[18] << 8) | data[19];
+        return ELF_MACHINE_TO_ARCH[machine] ?? null;
+    }
+    if (magic === 0xfeedface || magic === 0xfeedfacf) {
+        return MACHO_CPUTYPE_TO_ARCH[((data[4] << 24) | (data[5] << 16) | (data[6] << 8) | data[7]) >>> 0] ?? null;
+    }
+    if (magic === 0xcefaedfe || magic === 0xcffaedfe) {
+        return MACHO_CPUTYPE_TO_ARCH[((data[7] << 24) | (data[6] << 16) | (data[5] << 8) | data[4]) >>> 0] ?? null;
+    }
+    return null;
+}
+/**
+ * Refuse a payload whose binaries disagree with the label the package will carry.
+ *
+ * THE INCIDENT, measured on 0.41.0 before this existed. A project whose payload
+ * carries one x86-64 `.so`, packed on this x86-64 host:
+ *
+ *     gjsify ship --skip-build --arch arm64
+ *     → xarch-demo_1.2.3-1_arm64.deb, xarch-demo-1.2.3-1.aarch64.rpm
+ *     rpm -qp --qf '%{ARCH}'  → aarch64
+ *     the .so inside it       → ELF e_machine 0x3e (x86-64)
+ *
+ * `--arch` LABELS the payload; it does not cross-compile it, and nothing
+ * compared the two. The result installs on an arm64 machine — apt and dnf both
+ * believe the header — and then fails to load, which is this tree's most
+ * expensive failure class with an independent oracle actively confirming the
+ * lie: `rpm` reads the header, and the header was written from the caller's
+ * claim.
+ *
+ * Payload against LABEL, never payload against HOST. Assembling an arm64
+ * artifact on an x64 machine is a supported path — the packers are pure
+ * JavaScript and ADR 0024 § A1 turns it into a design commitment — so a host
+ * comparison would refuse the very case the split exists to allow.
+ */
+export function assertPayloadMatchesArch(payload, arch) {
+    for (const entry of payload) {
+        const found = readBinaryArch(entry.data);
+        if (found === null || found === arch)
+            continue;
+        throw new Error(`gjsify ship: the payload is ${found}, but the package would be labelled ${arch} — ` +
+            `${entry.path} is built for ${found}.\n` +
+            '    `--arch` names the architecture the PAYLOAD was built for; it does not cross-compile ' +
+            'anything.\n' +
+            `    A package labelled ${arch} installs on ${arch} and then fails to load. Build the payload ` +
+            `for ${arch}\n` +
+            '    (its own prebuild), or drop `--arch` and label the payload you actually have.');
+    }
+}
 /** ELF, Mach-O (both endiannesses, both widths, and a fat archive) or PE. */
 function isNativeBinary(data) {
     if (data.byteLength < 4)

package/lib/utils/ship/plan.js

@@ -54,6 +54,26 @@ export function planStage(settings, inputs) {
             source: { kind: 'file', path: schema },
         });
     }
+    // The typelibs the package carries itself, beside the bundle in `gi/`. The launcher points
+    // GI_TYPELIB_PATH and LD_LIBRARY_PATH here — see renderLauncher.
+    for (const file of settings.typelibFiles) {
+        files.push({
+            path: posix.join(libDir, 'gi', basename(file)),
+            // A shared library must be executable; a typelib need not be, but one mode for both
+            // keeps the staged tree free of a distinction nothing downstream reads.
+            mode: 0o755,
+            source: { kind: 'file', path: file },
+        });
+    }
+    // Compiled gettext catalogues, layout preserved: `share/locale/<lang>/LC_MESSAGES/<domain>.mo`
+    // is where `bindtextdomain` looks, and nowhere else.
+    for (const locale of settings.localeFiles) {
+        files.push({
+            path: posix.join('share/locale', locale.rel),
+            mode: 0o644,
+            source: { kind: 'file', path: locale.abs },
+        });
+    }
     for (const [dest, source] of Object.entries(settings.extraFiles)) {
         files.push({ path: assertInsidePrefix(dest), mode: 0o644, source: { kind: 'file', path: source } });
     }

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

@@ -27,6 +27,13 @@ export interface DiscoveredPayload {
     bundleFiles: string[];
     iconFiles: string[];
     schemaFiles: string[];
+    /** Absolute paths of the typelibs + shared libraries the project ships itself. */
+    typelibFiles: string[];
+    /** Compiled gettext catalogues, each with its `<lang>/LC_MESSAGES/<domain>.mo` path. */
+    localeFiles: {
+        rel: string;
+        abs: string;
+    }[];
     licenseFile?: string;
 }
 export interface SettingsInput {
@@ -53,7 +60,7 @@ export declare function declaredBundlePath(pkg: ShipPackageManifest, ship: Confi
 /** npm package name → a package/binary name both dpkg and rpm accept. */
 export declare function deriveBinaryName(pkgName: string | undefined): string;
 /** AppStream description (string or blocks) → plain paragraphs for deb/rpm. */
-export declare function descriptionParagraphs(description: string | DescriptionBlock[] | undefined): string[] | undefined;
+export declare function descriptionParagraphs(description: string | Array<DescriptionBlock | string> | undefined): string[] | undefined;
 /** `LICENSE`, `LICENSE.md`, … — the names a licence file actually has. */
 export declare const LICENSE_FILE_NAMES: readonly ["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING", "COPYING.md"];
 /** The bundle's own basename, used as the launcher's exec target. */

package/lib/utils/ship/settings.js

@@ -81,6 +81,8 @@ export function resolveShipSettings(input) {
         bundleDir: discovered.bundleDir,
         iconFiles: discovered.iconFiles,
         schemaFiles: discovered.schemaFiles,
+        typelibFiles: discovered.typelibFiles,
+        localeFiles: discovered.localeFiles,
         extraFiles: ship.extraFiles ?? {},
         execArgs: ship.execArgs ?? [],
         outDir: input.cli.outDir ?? ship.outDir ?? 'ship',
@@ -165,7 +167,17 @@ export function descriptionParagraphs(description) {
     }
     const out = [];
     for (const block of description) {
-        if ('p' in block) {
+        // A plain string in the array is what a person writes when they mean one paragraph, and it
+        // used to reach `'p' in block` and throw a bare TypeError — "cannot use 'in' operator to
+        // search for \"p\" in \"Bauplaner rechnet…\"", which names neither the field nor the fix.
+        // Accepting it is unambiguous: the AppStream blocks are objects, so a string can only mean
+        // a paragraph.
+        if (typeof block === 'string') {
+            const text = block.trim().replace(/\s+/g, ' ');
+            if (text)
+                out.push(text);
+        }
+        else if ('p' in block) {
             out.push(block.p.trim().replace(/\s+/g, ' '));
         }
         else {

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

@@ -101,6 +101,25 @@ export interface ShipSettings {
     iconFiles: string[];
     /** Absolute paths of `*.gschema.xml` files to install. */
     schemaFiles: string[];
+    /**
+     * Typelibs + shared libraries the package carries itself (`gjsify.ship.bundledTypelibs`).
+     *
+     * gjsify's own GI libraries arrive as npm prebuilds, not distro packages, so an app using one
+     * has nothing to depend on and must ship the files — with the launcher pointing GI at them.
+     */
+    typelibFiles: string[];
+    /**
+     * Compiled gettext catalogues (`gjsify.ship.localeDir`), each keeping its
+     * `<lang>/LC_MESSAGES/<domain>.mo` path so `share/locale/` comes out in the layout
+     * `bindtextdomain` reads.
+     *
+     * `rel` rather than a bare list of absolute paths, because the LAYOUT is the whole point here:
+     * a `.mo` staged by basename alone lands where no catalogue lookup will ever look at it.
+     */
+    localeFiles: {
+        rel: string;
+        abs: string;
+    }[];
     /** `<dest relative to prefix>` → absolute source path. */
     extraFiles: Record<string, string>;
     /** Arguments appended to the launcher's `exec` line. */

package/lib/utils/simple-command.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tokenize `cmd`, or return `null` if the string contains anything the shell
+ * would treat specially — operators (`&& | ; < > &`), substitutions (`$(...)` /
+ * backticks / `$VAR`), unquoted globs/expansions (`* ? { } [ ] ~`), comments
+ * (`#`), or an unterminated quote — in which case the caller MUST use the real
+ * shell instead. Quotes are honoured so a quoted glob (`'src/**'`) survives as a
+ * single literal token, exactly as the shell would hand it to `gjsify` (which
+ * does its own glob expansion).
+ */
+export declare function tokenizeSimpleCommand(cmd: string): string[] | null;
+/**
+ * The argv of a script that is a single `gjsify <subcommand> …` command — i.e.
+ * the tokens after `gjsify` — or `null` when it is anything else. `null` is the
+ * signal to hand the literal to a shell.
+ */
+export declare function gjsifyCommandArgv(literal: string): string[] | null;