@gjsify/cli 0.42.0 → 0.44.0

package/lib/utils/ship/payload.js

@@ -16,6 +16,12 @@ import { statSync } from 'node:fs';
  * what `rpm -qi` then shows a user, and an artifact that looks broken is a
  * support question. The mtime keeps the property that matters (pack the same
  * build twice, get the same bytes) while saying something true.
+ *
+ * Only the ASSEMBLING host runs this. A stage records the answer it got
+ * (`.gjsify-ship-stage.json` → `mtime`) and the packing host reuses it: an
+ * artifact upload does not carry mtimes, so re-stat'ing the stage there would
+ * stamp every header with "whenever the download finished" and quietly destroy
+ * the reproducibility this function exists to protect.
  */
 export function buildTimestamp(bundlePath, env = process.env) {
     const raw = env.SOURCE_DATE_EPOCH;
@@ -28,6 +34,72 @@ export function buildTimestamp(bundlePath, env = process.env) {
     }
     return Math.floor(statSync(bundlePath).mtimeMs / 1000);
 }
+/**
+ * Read {@link PayloadFacts} off a payload or off a plan.
+ *
+ * Takes anything with a `path`, so the assembling phase can ask the same
+ * question of the PLAN (before the tree is read back) that the packing phase
+ * asks of the payload. One function, so the two phases cannot disagree about
+ * whether a package installs a schema.
+ */
+export function readPayloadFacts(entries) {
+    const paths = entries.map((entry) => entry.path);
+    return {
+        hasDesktopEntry: paths.some((path) => path.startsWith('share/applications/') && path.endsWith('.desktop')),
+        hasIcons: paths.some((path) => path.startsWith('share/icons/hicolor/')),
+        hasSchemas: paths.some((path) => path.startsWith('share/glib-2.0/schemas/') && path.endsWith('.gschema.xml')),
+        hasMimeTypes: paths.some((path) => path.startsWith('share/mime/packages/') && path.endsWith('.xml')),
+        // Anywhere in the payload, not only `lib/<name>/gi/`: `gjsify.ship.extraFiles` can place
+        // one elsewhere, and a typelib the package carries is a typelib the package must not also
+        // declare a distro dependency for, wherever it sits.
+        bundledTypelibs: paths.filter((path) => path.endsWith('.typelib')),
+    };
+}
+/**
+ * The interpreters the payload's own executables need, read off their shebangs.
+ *
+ * An interpreter is a dependency like any other, and rpm expects it declared:
+ * `rpmbuild`'s file-based generator emits one `Requires` per executable
+ * shebang, with the `RPMSENSE_FIND_REQUIRES` sense that says "derived, not
+ * declared". Measured on Fedora 44 against a package whose only file is a
+ * `#!/bin/sh` script: `rpm -qp --requires` → `/usr/bin/sh 16384`.
+ *
+ * The LITERAL path, not a resolved one. `rpmbuild` prints `/usr/bin/sh` there
+ * because it resolved `/bin` through the symlink of the usrmerged host it ran
+ * on; this writer has no target host to resolve against (ADR 0024 § A1 — the
+ * packers are pure JavaScript and run anywhere), and `/bin/sh` is satisfied on
+ * both layouts: measured on Fedora 44, `rpm -q --whatprovides /bin/sh` and
+ * `/usr/bin/sh` both answer `bash`. It is also the spelling the scriptlet
+ * requirements already use.
+ *
+ * EXECUTABLE files only, which is the same rule `rpmbuild` applies. A GJS
+ * bundle staged 0644 carries `#!/usr/bin/env -S gjs -m` for the days it is run
+ * directly, but nothing in the installed package executes it as a program — the
+ * launcher `exec`s `gjs` with it as an argument — so declaring `/usr/bin/env`
+ * for it would be a dependency on a path this package never uses.
+ */
+export function readShebangInterpreters(payload) {
+    const found = new Set();
+    for (const entry of payload) {
+        if ((entry.mode & 0o111) === 0)
+            continue;
+        const interpreter = readShebang(entry.data);
+        if (interpreter !== null)
+            found.add(interpreter);
+    }
+    return [...found].sort();
+}
+/** The absolute interpreter path of a `#!` line, or `null` when there is none to read. */
+function readShebang(data) {
+    if (data[0] !== 0x23 || data[1] !== 0x21)
+        return null; // `#!`
+    // A shebang is one LINE; reading further would let a long file's contents
+    // decide how much work this does. 256 bytes is above every real one and is
+    // what Linux itself truncates at (BINPRM_BUF_SIZE).
+    const line = new TextDecoder().decode(data.subarray(2, Math.min(data.byteLength, 256))).split('\n')[0] ?? '';
+    const interpreter = line.trim().split(/\s+/)[0] ?? '';
+    return interpreter.startsWith('/') ? interpreter : null;
+}
 /**
  * Does the payload contain anything architecture-specific?
  *
@@ -44,6 +116,23 @@ export function isArchIndependent(payload) {
 // 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.
+// The machine values this project actually ships packages for — no more. A value
+// missing here makes `readBinaryArch` return null, and null is SILENT, so an
+// absent row costs nothing but a check that does not fire.
+//
+// `EM_MIPS` (0x08) is absent for that reason and no other. An earlier version of
+// this comment claimed it was absent because one value covers `mips` and
+// `mipsel` and the row would have to guess; that was wrong three times over, and
+// is corrected here rather than deleted because it is the kind of reasoning that
+// gets re-derived: (1) `mipsel` IS little-endian MIPS, so the discriminator is
+// `EI_DATA`, which `readBinaryArch` reads four lines below; (2) it could not
+// "refuse a correct pack" either way, because `formats.ts` has no `mips` row in
+// `DEBIAN_ARCH`/`RPM_ARCH`, so `archName` throws before any label is written;
+// and (3) the principle it invoked is already broken one row down — `0x16` maps
+// to `s390x`, but `EM_S390` is emitted by 31-bit `s390` too, and its
+// discriminator is `EI_CLASS` at offset 4, which this function does NOT read.
+// That row is the ambiguous one. Unreachable today (nothing here builds s390),
+// but it is the row to fix first if this table ever grows.
 const ELF_MACHINE_TO_ARCH = {
     0x03: 'ia32',
     0x15: 'ppc64',
@@ -121,7 +210,8 @@ export function assertPayloadMatchesArch(payload, arch) {
             '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.');
+            '    (its own prebuild), or assemble the stage without `--arch` and label the payload you ' +
+            'actually have.');
     }
 }
 /** ELF, Mach-O (both endiannesses, both widths, and a fat archive) or PE. */

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

@@ -1,4 +1,4 @@
-import type { FormatDescriptor, ShipSettings, StagedFile } from './types.js';
+import type { FormatDescriptor, FormatId, ShipSettings, StagedFile } from './types.js';
 /** Everything the planner needs that it cannot derive from the settings alone. */
 export interface StageInputs {
     /** Paths inside `settings.bundleDir`, relative and POSIX-separated. */
@@ -24,8 +24,37 @@ export declare function planStage(settings: ShipSettings, inputs: StageInputs):
  * The per-format additions. Only the licence differs today, and it differs in
  * BOTH place and shape: Debian policy wants a machine-readable `copyright` in
  * `share/doc/<pkg>/`, RPM wants the licence text under `share/licenses/<pkg>/`.
+ *
+ * A project with no licence file is REFUSED here rather than packaged without
+ * one. Debian Policy § 12.5 makes the copyright file mandatory and lintian
+ * raises `no-copyright-file` as an error, but nothing between this function and
+ * the installed package says so: an empty overlay produced a `.deb` whose
+ * control file `dpkg-deb --info` prints cleanly, that `dpkg -i` installs, and
+ * that is simply unlicensed. That is what gjsify's own package was, every
+ * release of it, until the first CI leg that read one with a real `dpkg` said
+ * so on its eighth assertion.
+ *
+ * It throws on the host that can act on it. This runs during `--stage` as well
+ * as during a one-shot `ship`, so the refusal lands where the project — and the
+ * missing `LICENSE` — actually is; {@link assertOverlayIsLicensed} repeats it at
+ * pack time for a stage that arrived from somewhere else.
  */
 export declare function planOverlay(settings: ShipSettings, format: FormatDescriptor, inputs: StageInputs): StagedFile[];
+/**
+ * The same refusal, at pack time.
+ *
+ * `planOverlay` cannot cover `--from-stage`: that path never plans anything, it
+ * rehydrates the closure the assembling host wrote. A manifest whose
+ * `overlay.deb` is `[]` passes every structural check in `readStageManifest`
+ * — the key is present, the value is an array of the right shape — and the
+ * silent unlicensed package comes back. The stage manifest's own header lists
+ * "no `overlay`" among the omissions that fail at exit 0 with an artifact that
+ * installs; this is where that stops being a comment.
+ *
+ * Cheap enough to run on both paths, so it does, and a stage written by this
+ * version can no longer reach it.
+ */
+export declare function assertOverlayIsLicensed(formatId: FormatId, binaryName: string, overlay: readonly StagedFile[]): void;
 /**
  * The hicolor subdirectory for an icon: `scalable` for SVG, otherwise the
  * pixel size read from a `<n>x<n>` path component or a trailing number in the

package/lib/utils/ship/plan.js

@@ -2,6 +2,7 @@
 // case (including the ones that must be REFUSED) is unit-testable. Same split
 // as `utils/copy-targets.ts`, and for the same reason: a stager that discovers
 // its own inputs can only be tested by building a real project.
+import { renderMimePackage } from './mime.js';
 import { basename, extname, posix } from 'node:path';
 /**
  * Build the prefix-relative payload.
@@ -65,6 +66,16 @@ export function planStage(settings, inputs) {
             source: { kind: 'file', path: file },
         });
     }
+    // A shared-mime-info document, when the project DEFINES a type rather than only handling one.
+    // `share/mime/packages/` is shared between packages, so the app id is the filename for the same
+    // reason it is for the GSettings schema: a generic name collides with another package's file.
+    if (settings.mimeTypes.length > 0) {
+        files.push({
+            path: `share/mime/packages/${settings.appId}.xml`,
+            mode: 0o644,
+            source: { kind: 'text', text: renderMimePackage(settings.mimeTypes) },
+        });
+    }
     // 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) {
@@ -83,15 +94,56 @@ export function planStage(settings, inputs) {
  * The per-format additions. Only the licence differs today, and it differs in
  * BOTH place and shape: Debian policy wants a machine-readable `copyright` in
  * `share/doc/<pkg>/`, RPM wants the licence text under `share/licenses/<pkg>/`.
+ *
+ * A project with no licence file is REFUSED here rather than packaged without
+ * one. Debian Policy § 12.5 makes the copyright file mandatory and lintian
+ * raises `no-copyright-file` as an error, but nothing between this function and
+ * the installed package says so: an empty overlay produced a `.deb` whose
+ * control file `dpkg-deb --info` prints cleanly, that `dpkg -i` installs, and
+ * that is simply unlicensed. That is what gjsify's own package was, every
+ * release of it, until the first CI leg that read one with a real `dpkg` said
+ * so on its eighth assertion.
+ *
+ * It throws on the host that can act on it. This runs during `--stage` as well
+ * as during a one-shot `ship`, so the refusal lands where the project — and the
+ * missing `LICENSE` — actually is; {@link assertOverlayIsLicensed} repeats it at
+ * pack time for a stage that arrived from somewhere else.
  */
 export function planOverlay(settings, format, inputs) {
-    if (inputs.licenseText === undefined)
-        return [];
+    if (inputs.licenseText === undefined) {
+        throw new Error(`gjsify ship: no licence file found, so the ${format.id} package would ship no ` +
+            `${format.licenseDest(settings.binaryName)}. Debian Policy § 12.5 requires it and lintian ` +
+            'errors without it, and neither dpkg nor rpm will tell you it is missing. Add a LICENSE file ' +
+            `to ${settings.projectDir} or to the root of its repository, or point ` +
+            '`gjsify.ship.licenseFile` at the one this package ships under.');
+    }
     const text = format.licenseKind === 'debian-copyright'
         ? renderDebianCopyright(settings, inputs.licenseText)
         : inputs.licenseText;
     return [{ path: format.licenseDest(settings.binaryName), mode: 0o644, source: { kind: 'text', text } }];
 }
+/**
+ * The same refusal, at pack time.
+ *
+ * `planOverlay` cannot cover `--from-stage`: that path never plans anything, it
+ * rehydrates the closure the assembling host wrote. A manifest whose
+ * `overlay.deb` is `[]` passes every structural check in `readStageManifest`
+ * — the key is present, the value is an array of the right shape — and the
+ * silent unlicensed package comes back. The stage manifest's own header lists
+ * "no `overlay`" among the omissions that fail at exit 0 with an artifact that
+ * installs; this is where that stops being a comment.
+ *
+ * Cheap enough to run on both paths, so it does, and a stage written by this
+ * version can no longer reach it.
+ */
+export function assertOverlayIsLicensed(formatId, binaryName, overlay) {
+    if (overlay.length > 0)
+        return;
+    throw new Error(`gjsify ship: this stage carries no ${formatId} licence overlay, so the package would ship no ` +
+        `licence file for ${binaryName} — Debian Policy § 12.5 requires one and lintian errors without ` +
+        'it. The fix is on the assembling host, not this one: give that project a LICENSE (or set ' +
+        '`gjsify.ship.licenseFile`) and re-run the `--stage` phase.');
+}
 /**
  * Debian machine-readable copyright, format 1.0. The licence text is indented
  * by one space and its blank lines become ` .` — a bare blank line ends the

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

@@ -1,7 +1,7 @@
-import type { PayloadEntry } from './payload.js';
-import type { ShipSettings } from './types.js';
+import { type PayloadEntry } from './payload.js';
+import type { PackSettings } from './types.js';
 export interface RpmInputs {
-    settings: ShipSettings;
+    settings: PackSettings;
     payload: readonly PayloadEntry[];
     prefix: string;
     depends: readonly string[];

package/lib/utils/ship/rpm.js

@@ -15,6 +15,7 @@ import { createHash } from 'node:crypto';
 import { concatBytes } from './bytes.js';
 import { createCpioArchive, S_IFDIR, S_IFREG } from './cpio.js';
 import { parseDepend } from './depends.js';
+import { readPayloadFacts, readShebangInterpreters } from './payload.js';
 import { buildRpmHeader, buildRpmLead, padToEight, RpmType, RPM_TAG_HEADERIMMUTABLE, RPM_TAG_HEADERSIGNATURES, } from './rpm-header.js';
 import { gzipDeterministic } from './gzip.js';
 import { renderRpmScriptlets } from './scripts.js';
@@ -80,6 +81,9 @@ const SENSE = {
     INTERP: 1 << 8,
     SCRIPT_POST: 1 << 10,
     SCRIPT_POSTUN: 1 << 12,
+    // "This one was derived from the payload, not declared by the packager" —
+    // the sense `rpmbuild`'s own dependency generator uses (measured: 16384).
+    FIND_REQUIRES: 1 << 14,
     RPMLIB: 1 << 24,
 };
 /** SHA-256 in rpm's digest-algorithm numbering (PGP hash algorithm ids). */
@@ -205,8 +209,9 @@ function mainHeaderEntries(inputs, files, cpio, compressed) {
         dirIndexes.push(index);
         baseNames.push(file.path.slice(slash + 1));
     }
-    const scripts = renderRpmScriptlets(settings, inputs.prefix);
-    const requires = buildRequires(inputs.depends, scripts);
+    // From the PAYLOAD, not the settings — see the same call in `deb.ts`.
+    const scripts = renderRpmScriptlets(readPayloadFacts(inputs.payload), inputs.prefix);
+    const requires = buildRequires(inputs.depends, scripts, readShebangInterpreters(inputs.payload));
     const entries = [
         { tag: TAG.HEADERI18NTABLE, type: RpmType.STRING_ARRAY, value: ['C'] },
         { tag: TAG.NAME, type: RpmType.STRING, value: settings.binaryName },
@@ -325,8 +330,15 @@ function assertParallelFileArrays(entries, fileCount) {
  * A scriptlet's interpreter is a dependency like any other and rpm expects it
  * declared with the matching `SCRIPT_*` sense bit — without it, a system
  * without `/bin/sh` installs the package and then fails inside `%post`.
+ *
+ * The payload's own executables need the same treatment, and until the first
+ * real `rpm -qp --requires` ran against this writer nothing here said so: every
+ * `.rpm` it produced installed a `#!/bin/sh` launcher and declared no shell.
+ * The two senses are not redundant and rpm emits both — a package can need a
+ * shell to CONFIGURE (`Requires(post)`) and to RUN (a plain requirement), and
+ * dropping either is a different broken system.
  */
-function buildRequires(depends, scripts) {
+function buildRequires(depends, scripts, interpreters) {
     const names = [];
     const flags = [];
     const versions = [];
@@ -346,6 +358,11 @@ function buildRequires(depends, scripts) {
         flags.push(SENSE.INTERP | SENSE.SCRIPT_POSTUN);
         versions.push('');
     }
+    for (const interpreter of interpreters) {
+        names.push(interpreter);
+        flags.push(SENSE.FIND_REQUIRES);
+        versions.push('');
+    }
     for (const [name, version] of RPMLIB_REQUIRES) {
         names.push(name);
         flags.push(SENSE.RPMLIB | SENSE.LESS | SENSE.EQUAL);

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

@@ -1,4 +1,4 @@
-import type { ShipSettings } from './types.js';
+import type { PayloadFacts } from './payload.js';
 /**
  * The cache refreshes this payload makes necessary, each guarded by the tool's
  * presence and `|| true`.
@@ -6,8 +6,18 @@ import type { ShipSettings } from './types.js';
  * The caches belong to the distribution, not to us: on removal the helper may
  * already be gone, and a maintainer script that fails during a purge leaves a
  * package the user cannot uninstall.
+ *
+ * Keyed on the PAYLOAD, not on the settings. Each line refreshes exactly one
+ * directory, so the honest precondition is "did this package install anything
+ * into that directory" — which the payload answers and a project's file lists
+ * only approximate. They came apart in one measured case: a `kind: 'cli'`
+ * project with a `data/icons/` folder staged no icon at all (icons are an
+ * `'app'` thing in `planStage`) while `settings.iconFiles` was non-empty, so
+ * the postinst refreshed an icon cache for files that were never installed.
+ * The second reason is ADR 0024 § A2: those lists are absolute BUILD-host
+ * paths, and this code now also runs on a host that has only the staged tree.
  */
-export declare function cacheRefreshCommands(settings: ShipSettings, prefix: string): string[];
+export declare function cacheRefreshCommands(facts: PayloadFacts, prefix: string): string[];
 /**
  * dpkg maintainer scripts, keyed by their `control.tar` filename.
  *
@@ -15,7 +25,7 @@ export declare function cacheRefreshCommands(settings: ShipSettings, prefix: str
  * and several abort paths, and on an upgrade the incoming package's `postinst`
  * refreshes the caches anyway.
  */
-export declare function renderDebScripts(settings: ShipSettings, prefix: string): Record<string, string>;
+export declare function renderDebScripts(facts: PayloadFacts, prefix: string): Record<string, string>;
 /**
  * rpm scriptlets, for the `POSTIN` / `POSTUN` header tags.
  *
@@ -25,7 +35,7 @@ export declare function renderDebScripts(settings: ShipSettings, prefix: string)
  * work rather than a wrong result, where guarding on `[ $1 -eq 0 ]` would be
  * one more place to get the convention backwards.
  */
-export declare function renderRpmScriptlets(settings: ShipSettings, prefix: string): {
+export declare function renderRpmScriptlets(facts: PayloadFacts, prefix: string): {
     post?: string;
     postun?: string;
 };

package/lib/utils/ship/scripts.js

@@ -18,22 +18,40 @@
  * The caches belong to the distribution, not to us: on removal the helper may
  * already be gone, and a maintainer script that fails during a purge leaves a
  * package the user cannot uninstall.
+ *
+ * Keyed on the PAYLOAD, not on the settings. Each line refreshes exactly one
+ * directory, so the honest precondition is "did this package install anything
+ * into that directory" — which the payload answers and a project's file lists
+ * only approximate. They came apart in one measured case: a `kind: 'cli'`
+ * project with a `data/icons/` folder staged no icon at all (icons are an
+ * `'app'` thing in `planStage`) while `settings.iconFiles` was non-empty, so
+ * the postinst refreshed an icon cache for files that were never installed.
+ * The second reason is ADR 0024 § A2: those lists are absolute BUILD-host
+ * paths, and this code now also runs on a host that has only the staged tree.
  */
-export function cacheRefreshCommands(settings, prefix) {
+export function cacheRefreshCommands(facts, prefix) {
     const refreshes = [];
-    if (settings.kind === 'app') {
+    if (facts.hasDesktopEntry) {
         refreshes.push({
             probe: 'update-desktop-database',
             run: `update-desktop-database -q ${prefix}/share/applications`,
         });
     }
-    if (settings.iconFiles.length > 0) {
+    if (facts.hasIcons) {
         refreshes.push({
             probe: 'gtk-update-icon-cache',
             run: `gtk-update-icon-cache -q -t -f ${prefix}/share/icons/hicolor`,
         });
     }
-    if (settings.schemaFiles.length > 0) {
+    if (facts.hasMimeTypes) {
+        // Without this the document is installed and the type still does not exist: detection runs
+        // off the compiled cache in `share/mime/`, not off the packages directory.
+        refreshes.push({
+            probe: 'update-mime-database',
+            run: `update-mime-database ${prefix}/share/mime`,
+        });
+    }
+    if (facts.hasSchemas) {
         refreshes.push({
             probe: 'glib-compile-schemas',
             run: `glib-compile-schemas ${prefix}/share/glib-2.0/schemas`,
@@ -48,8 +66,8 @@ export function cacheRefreshCommands(settings, prefix) {
  * and several abort paths, and on an upgrade the incoming package's `postinst`
  * refreshes the caches anyway.
  */
-export function renderDebScripts(settings, prefix) {
-    const commands = cacheRefreshCommands(settings, prefix);
+export function renderDebScripts(facts, prefix) {
+    const commands = cacheRefreshCommands(facts, prefix);
     if (commands.length === 0)
         return {};
     const body = commands.map((line) => `    ${line}`).join('\n');
@@ -67,8 +85,8 @@ export function renderDebScripts(settings, prefix) {
  * work rather than a wrong result, where guarding on `[ $1 -eq 0 ]` would be
  * one more place to get the convention backwards.
  */
-export function renderRpmScriptlets(settings, prefix) {
-    const commands = cacheRefreshCommands(settings, prefix);
+export function renderRpmScriptlets(facts, prefix) {
+    const commands = cacheRefreshCommands(facts, prefix);
     if (commands.length === 0)
         return {};
     const body = `${commands.join('\n')}\n`;

package/lib/utils/ship/settings.js

@@ -9,8 +9,10 @@
 // Precedence is uniform: CLI flag > `gjsify.ship` > `gjsify.flatpak` (metadata
 // only) > derived from package.json. Never a yargs `default:`, which is
 // indistinguishable from a value the user typed and would clobber the config.
+import { validateMimeTypes } from './mime.js';
 import { basename } from 'node:path';
 import { DEFAULT_GJS_FLOOR } from './depends.js';
+import { resolveShipFlatpakSettings } from './flatpak-config.js';
 import { assertRelease, normaliseVersion } from './version.js';
 /** Freedesktop main category → deb `Section:` / rpm `Group:`. First match wins. */
 const CATEGORY_SECTIONS = [
@@ -32,6 +34,17 @@ export function resolveShipSettings(input) {
     // `gjsify.flatpak` key-by-key is exactly the fallback ADR 0024 § 8 asks
     // for. The non-metadata keys each block carries ride along unread.
     const metadata = { ...flatpak, ...definedOnly(ship) };
+    // A type this package DEFINES is also a type it handles. Folding it into `provides.mimetypes`
+    // here means the desktop entry and the metainfo need no knowledge of `mimeTypes` at all: they
+    // already render `MimeType=` (with the `%f` field code) and `<mediatype>` from that one field.
+    // Doing it the other way — leaving the two lists independent — makes "defined but not handled"
+    // a state you can reach by omission, and that state installs cleanly and does nothing.
+    const mimeTypes = ship.mimeTypes ?? [];
+    if (mimeTypes.length > 0) {
+        validateMimeTypes(mimeTypes);
+        const handled = new Set([...(metadata.provides?.mimetypes ?? []), ...mimeTypes.map((m) => m.type)]);
+        metadata.provides = { ...metadata.provides, mimetypes: [...handled] };
+    }
     const binaryName = ship.binaryName ?? deriveBinaryName(pkg.name);
     const appId = ship.appId ?? flatpak.appId ?? reverseDnsOrThrow(pkg.name, binaryName);
     const name = metadata.name ?? titleCase(binaryName);
@@ -59,6 +72,11 @@ export function resolveShipSettings(input) {
         warnings.push(`gjsify ship: no icon found — the installed app will show a placeholder in menus and app stores. ` +
             'Point `gjsify.ship.icon` at an SVG (or a directory of sized PNGs).');
     }
+    // Resolved here rather than in the packer, because the packer may run on a
+    // host with no `package.json` at all (ADR 0024 § A2) — and because the
+    // finish-args default depends on `kind`, which is a project fact.
+    const flatpakSettings = resolveShipFlatpakSettings({ ship, flatpak, kind });
+    warnings.push(...flatpakSettings.warnings);
     const settings = {
         projectDir: input.projectDir,
         appId,
@@ -75,6 +93,7 @@ export function resolveShipSettings(input) {
         section: ship.section ?? sections.section,
         group: ship.group ?? sections.group,
         kind,
+        mimeTypes,
         extraDepends: { deb: ship.depends?.deb ?? [], rpm: ship.depends?.rpm ?? [] },
         typelibPackages: ship.typelibPackages ?? {},
         bundlePath: discovered.bundlePath,
@@ -88,6 +107,7 @@ export function resolveShipSettings(input) {
         outDir: input.cli.outDir ?? ship.outDir ?? 'ship',
         arch: input.cli.arch ?? process.arch,
         minGjsVersion: ship.minGjsVersion ?? DEFAULT_GJS_FLOOR,
+        flatpak: flatpakSettings.settings,
     };
     return { settings, metadata, warnings };
 }

package/lib/utils/ship/stage-manifest.d.ts

@@ -0,0 +1,163 @@
+import type { FormatDescriptor, FormatId, PackSettings, ShipSettings, StagedFile, StagedMode } from './types.js';
+/** The one file a stage carries that is not payload. Lives at the stage ROOT. */
+export declare const STAGE_MANIFEST_FILE = ".gjsify-ship-stage.json";
+/**
+ * The schema this CLI writes and the only one it reads.
+ *
+ * A stage is a short-lived intermediate between two jobs of ONE run, not an
+ * archive, so there is no migration path in either direction and both
+ * mismatches are refused rather than guessed at — see {@link readStageManifest}.
+ * Bump it whenever a field's MEANING changes, not when one is added that an
+ * older reader would simply ignore; a reader that ignores a field it does not
+ * know is exactly how a mode plan silently loses an entry.
+ *
+ * 2 added `settings.appId` and `settings.flatpak` for the Flatpak target. That
+ * is the second case and not the first: an older reader ignoring
+ * `settings.flatpak` would not skip a field, it would pack a Flatpak against
+ * whatever runtime IT defaults to — a different `org.gnome.Platform` version
+ * than the project asked for, at exit 0.
+ */
+export declare const STAGE_SCHEMA_VERSION = 2;
+/**
+ * The OS whose layout `planStage` produces.
+ *
+ * A constant rather than a measurement, because it is a property of the PLAN
+ * (`bin/`, `lib/<name>/`, `share/…` is the Linux/XDG layout), not of the host
+ * that ran it — assembling is cross-platform (ADR 0024 § A1). When
+ * `gjsify ship darwin --stage` lands this becomes the positional's value, and
+ * this constant is where the compiler will point.
+ */
+export declare const STAGE_LAYOUT_OS = "linux";
+/** What this stage was assembled FOR, in the repo-wide `${process.platform}-${process.arch}` spelling. */
+export interface StageTarget {
+    os: string;
+    arch: string;
+}
+/** One staged path, its planned mode, and the size it had when the stage was written. */
+export interface StageFileRecord extends StagedMode {
+    bytes: number;
+}
+/** One pre-rendered overlay file. Text only — see {@link writeStageManifest}. */
+export interface StageOverlayFile extends StagedMode {
+    text: string;
+}
+export interface StageManifest {
+    schema: number;
+    /** The tool that assembled the stage, so a mixed-version pipeline is answerable after the fact. */
+    tool: {
+        name: string;
+        version: string;
+    };
+    target: StageTarget;
+    /** The formats phase 1 rendered an overlay closure for. */
+    formats: FormatId[];
+    /** The one build stamp every header and every rendered file shares. */
+    mtime: number;
+    /** GI namespaces the bundle imports, `Ns-Version` where the specifier pins one. */
+    namespaces: string[];
+    settings: PackSettings;
+    staged: StageFileRecord[];
+    overlay: Partial<Record<FormatId, StageOverlayFile[]>>;
+}
+export interface StageManifestInput {
+    /** Absolute path of the stage root, already written. */
+    stageDir: string;
+    settings: ShipSettings;
+    formats: readonly FormatDescriptor[];
+    mtime: number;
+    namespaces: readonly string[];
+    staged: readonly StagedFile[];
+    /** Per-format overlay, as `planOverlay` produced it. */
+    overlay: ReadonlyMap<FormatId, readonly StagedFile[]>;
+}
+/**
+ * The half of {@link ShipSettings} that crosses the host boundary.
+ *
+ * Written out field by field rather than spread: a spread would carry
+ * `projectDir`, `bundlePath`, `bundleDir`, `iconFiles`, `schemaFiles`,
+ * `extraFiles` and `licenseFile` — seven absolute paths from the assembling
+ * host — into a file whose whole purpose is to be read somewhere else. The
+ * explicit list is also what makes adding a field a decision: see the comment
+ * on {@link PackSettings} for what belongs on each side. `appId` and `flatpak`
+ * were that decision for the Flatpak target, and the `--from-stage` e2e is
+ * where an omission would have shown: it deletes the project, so a field the
+ * packer needs and the manifest lacks has nowhere to be read from.
+ */
+export declare function toPackSettings(settings: ShipSettings): PackSettings;
+/** Absolute path of a stage's manifest. */
+export declare function stageManifestPath(stageDir: string): string;
+/** `linux-x64`. One spelling repo-wide (root AGENTS.md § Runtime & platform model). */
+export declare function formatTarget(target: StageTarget): string;
+/**
+ * Write the manifest at the stage root, AFTER the tree itself.
+ *
+ * `bytes` is stat'ed off the written tree rather than taken from the plan: the
+ * plan holds a source path or a string, and what the packing host will compare
+ * against is what actually landed on disk here.
+ */
+export declare function writeStageManifest(input: StageManifestInput): StageManifest;
+/**
+ * Read and validate a stage's manifest.
+ *
+ * Every field is checked, because this file is the only thing standing between
+ * "a directory someone pointed us at" and a signed-looking `.deb`. A missing
+ * `staged` entry would reach `readStage` as a mode nobody planned; a `mode` that
+ * arrived as a string would reach `chmod` as `NaN`.
+ */
+export declare function readStageManifest(stageDir: string): StageManifest;
+/** The overlay for one format, in the shape `writeStage` takes. */
+export declare function overlayFiles(manifest: StageManifest, format: FormatId): StagedFile[];
+/**
+ * Refuse a stage that is not the one this job was told to pack.
+ *
+ * WHAT THIS IS: a matrix-leg mix-up check. It catches a finish job that
+ * downloaded the wrong artifact — the leg that forgot to route — and nothing
+ * more. It is opt-in (no flag, no check) and it compares two strings the same
+ * pipeline wrote one job apart, so treat a green run as "this is the stage I
+ * asked for", never as "this stage is correctly labelled".
+ *
+ * WHAT THIS IS NOT: the guard its precedent
+ * (`packages/node-gi/scripts/verify-bundle-manifest.mjs --expect-host-target`)
+ * provides. That script compares a bundle to `process.platform`/`process.arch`
+ * because the runner BUILT it, so the machine is the right second opinion.
+ * Here the stage arrives from another host by design, so a host comparison
+ * would refuse a legal use — measured: an `arm64`-labelled stage packs on this
+ * x64 host at exit 0 with correct bytes, because both packers are pure JS.
+ *
+ * The class that precedent guards — a label and the bytes under it disagreeing
+ * — is NOT guarded here, and `target.arch` cannot guard it: it is defaulted
+ * from `process.arch` only when `--arch` is absent, so the moment an operator
+ * says which leg they are on, `target.arch` is that operator's claim and
+ * nothing compares it to a machine or to a byte. Measured BEFORE
+ * {@link assertPayloadMatchesArch} existed: a stage carrying an x86-64 `.so`,
+ * assembled `--stage --arch arm64` and packed `--expect-target linux-arm64`,
+ * exited 0 and produced an `aarch64` rpm whose only `.so` was `e_machine=0x3e`.
+ * The same command in this tree now exits 1 and writes nothing — kept in the
+ * past tense because it is the reason the guard below it exists, not a
+ * description of what this function does.
+ *
+ * That class is guarded one layer down instead, where the oracle is free and
+ * cannot be wrong about a machine it never saw: {@link assertPayloadMatchesArch}
+ * in `payload.ts` reads ELF `e_machine` / Mach-O `cputype` out of the payload
+ * and refuses a label the bytes contradict. Payload-versus-label goes red on
+ * the mislabelled stage AND stays green on the legitimate cross-host pack;
+ * host-versus-label can only do one of the two.
+ */
+export declare function assertExpectedTarget(manifest: StageManifest, expected: string | undefined): void;
+/** Refuse a format the stage carries no overlay closure for. */
+export declare function assertFormatsStaged(manifest: StageManifest, formats: readonly FormatDescriptor[]): void;
+/**
+ * The build stamp the packing host uses: the stage's, always.
+ *
+ * A `SOURCE_DATE_EPOCH` set only in the finish job would silently produce a
+ * different artifact than the same stage packed on the assembling host, which
+ * is the one property the two-phase split has to keep. It is a warning rather
+ * than a refusal because the honest fix ("set it in both jobs or in neither")
+ * is the caller's, and refusing would break a runner that exports it globally.
+ */
+export declare function resolveStageMtime(manifest: StageManifest, env?: Record<string, string | undefined>): {
+    mtime: number;
+    warnings: string[];
+};
+/** One actionable line when the two phases ran different gjsify versions. */
+export declare function warnOnToolSkew(manifest: StageManifest): string[];