@gjsify/cli 0.42.0 → 0.44.0

package/lib/utils/ship/flatpak.js

@@ -0,0 +1,148 @@
+// The Flatpak packer — ADR 0024 § 8, stage 6.
+//
+// This is a MOVE, not a second implementation. `gjsify flatpak` has emitted
+// Flatpak manifests since long before `ship` existed; what it emitted was a
+// `buildsystem: meson` module, which made every app carry meson glue whose only
+// job was to call `gjsify build` and copy the result into a prefix — 158 lines
+// of it in Learn6502, 66 of them `GI_TYPELIB_PATH`/`LD_LIBRARY_PATH` plumbing.
+// `ship` already produces that prefix. So the module becomes:
+//
+//     buildsystem: simple
+//     build-commands: mkdir -p /app; cp -a stage/. /app/; cp -a overlay/. /app/
+//
+// and meson leaves the sandbox. Nothing else about the payload changes — the
+// launcher derives its own prefix at runtime (§ 3), which is exactly why one
+// staged tree can be `/usr` in a `.deb` and `/app` here.
+//
+// FOUR THINGS ABOUT flatpak-builder 1.4.10 WERE MEASURED before this file was
+// written, because each had a plausible wrong answer and flatpak-builder reports
+// none of them: an absolute `dir` source `path` works, `skip` works and is what
+// keeps the stage's own sidecar out of `/app`, `cp -a` preserves the mode, and
+// `--show-manifest` is NOT a validator (it accepted an unknown source property
+// and `buildsystem: "nonsense"` at exit 0, so it must never be used as a gate).
+// The numbers, the commands and the oracle that replaces `--show-manifest`:
+// `docs/ship-formats.md`.
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describeExit, spawnToCompletion } from '../spawn.js';
+/**
+ * The generated Flatpak manifest, as a plain object.
+ *
+ * Pure, so every field is unit-testable without flatpak tooling — and the
+ * suite that needs that is the one running in CI, where there is none.
+ *
+ * The app id is what makes this legal Flatpak: every file flatpak EXPORTS out
+ * of `/app/share` has to be named after it, and `planStage` already enforces
+ * exactly that for its own reasons — the desktop entry, the metainfo, the icon,
+ * the GSettings schema and the shared-mime-info document are all
+ * `<appId>[.…].<ext>`, because `share/glib-2.0/schemas/` and
+ * `share/mime/packages/` are directories shared between packages. Two
+ * independent constraints, one naming rule.
+ */
+export function renderShipFlatpakManifest(input) {
+    const { settings, stageDir, overlayDir } = input;
+    const flatpak = settings.flatpak;
+    const manifest = {
+        id: settings.appId,
+        runtime: flatpak.runtime,
+        'runtime-version': flatpak.runtimeVersion,
+        sdk: flatpak.sdk,
+        branch: flatpak.branch,
+        // `bin/<binaryName>`, which is the one executable the stage plans. NOT
+        // the app id, which is what `gjsify flatpak init` defaults to: under
+        // `ship` the launcher's name is decided by `gjsify.ship.binaryName`, and
+        // a `command` naming a file that is not in `/app/bin` produces an app
+        // that installs and cannot be launched.
+        command: settings.binaryName,
+        'finish-args': flatpak.finishArgs,
+    };
+    if (flatpak.sdkExtensions.length > 0)
+        manifest['sdk-extensions'] = flatpak.sdkExtensions;
+    if (flatpak.appendPath.length > 0) {
+        manifest['build-options'] = { 'append-path': flatpak.appendPath.join(':') };
+    }
+    if (flatpak.cleanup.length > 0)
+        manifest.cleanup = flatpak.cleanup;
+    manifest.modules = [
+        {
+            name: settings.binaryName,
+            buildsystem: 'simple',
+            // `mkdir -p /app` first: flatpak-builder creates the app directory,
+            // but a module whose only command is a `cp` into a path that does
+            // not exist yet is one refactor away from failing, and the mkdir is
+            // free. `stage/.` and not `stage` — `cp -a stage /app/` would
+            // create `/app/stage`, which installs cleanly and puts the whole
+            // payload one directory too deep.
+            'build-commands': ['mkdir -p /app', 'cp -a stage/. /app/', 'cp -a overlay/. /app/'],
+            sources: [
+                { type: 'dir', path: stageDir, dest: 'stage', skip: [input.stageManifestFile] },
+                { type: 'dir', path: overlayDir, dest: 'overlay' },
+            ],
+        },
+    ];
+    return manifest;
+}
+/**
+ * Build the app and export a single-file bundle at `input.target`.
+ *
+ * The only packer in this tree that execs anything, and the descriptor says so
+ * (`FORMATS.flatpak.host.requiredTools`). ADR 0024 § A3 is explicit that this
+ * costs the independent oracle the hand-written deb/rpm writers bought: what
+ * pays it back here is that a `.flatpak` is an OSTree static delta, so
+ * `flatpak build-import-bundle` + `ostree ls -R` read the artifact back with
+ * code this tree did not write.
+ */
+export async function buildFlatpakBundle(input) {
+    const { settings, workDir, archLabel } = input;
+    const manifestPath = join(workDir, `${settings.appId}.json`);
+    const buildDir = join(workDir, 'build');
+    const repoDir = join(workDir, 'repo');
+    // Kept between runs: it is flatpak-builder's own ostree cache, and dropping
+    // it turns every re-pack into a full rebuild of every module.
+    const stateDir = join(workDir, 'state');
+    mkdirSync(workDir, { recursive: true });
+    // The repo is wiped, the state dir is not. A repo that survives holds the
+    // PREVIOUS commit on the same ref, and `build-bundle` would happily export
+    // it if this run's export failed for any reason that did not fail the
+    // build — a stale artifact wearing the new version's filename.
+    rmSync(repoDir, { recursive: true, force: true, maxRetries: 5 });
+    writeFileSync(manifestPath, `${JSON.stringify(renderShipFlatpakManifest(input), null, 2)}\n`);
+    await run('flatpak-builder', [
+        '--force-clean',
+        // Needed wherever FUSE is unavailable — containers, most CI runners.
+        // It only disables a read-only-bind optimisation, and a build that
+        // cannot start is worse than one that copies a few more bytes.
+        '--disable-rofiles-fuse',
+        '--delete-build-dirs',
+        `--state-dir=${stateDir}`,
+        `--arch=${archLabel}`,
+        `--repo=${repoDir}`,
+        buildDir,
+        manifestPath,
+    ], input, 'flatpak-builder not found. Install it (Fedora: `sudo dnf install flatpak-builder`).');
+    // The branch is passed explicitly even though the manifest declares it: the
+    // two have to name the same ref, and `build-bundle`'s default is `master`
+    // while a manifest that sets `branch` exports somewhere else. Leaving it
+    // implicit is how this exports nothing and says "ref not found".
+    await run('flatpak', ['build-bundle', `--arch=${archLabel}`, repoDir, input.target, settings.appId, settings.flatpak.branch], input, 'flatpak not found. Install it via your distro: see https://flathub.org/setup.');
+}
+async function run(cmd, args, input, notFoundHint) {
+    if (input.verbose)
+        console.log(`[gjsify ship] ${cmd} ${args.join(' ')}`);
+    // `completion: 'return'` because `ship` packs the remaining formats and
+    // prints the artifact list afterwards, so it cannot end in `process.exit()`
+    // the way `gjsify flatpak build` does. Under GJS that selects the blocking
+    // path, which captures the child's output and re-emits it at the end
+    // instead of streaming it — the documented cost of a spawn a caller has to
+    // return from (see utils/spawn.ts), and the reason `--verbose` prints the
+    // invocation before the silence starts.
+    const result = await spawnToCompletion(cmd, args, {
+        completion: 'return',
+        cwd: input.workDir,
+        stdio: 'inherit',
+        notFound: () => new Error(`gjsify ship: ${notFoundHint}`),
+    });
+    if (result.code !== 0) {
+        throw new Error(`gjsify ship: ${cmd} failed${describeExit(result)}.`);
+    }
+}

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

@@ -1,5 +1,40 @@
 import type { FormatDescriptor, FormatId } from './types.js';
 export declare const FORMATS: Record<FormatId, FormatDescriptor>;
 export declare const FORMAT_IDS: FormatId[];
+/**
+ * What `gjsify ship` builds when nothing said otherwise — every format that
+ * needs no tool and no particular host.
+ *
+ * A SECOND derivation from the same table, and it has to be one: `FORMAT_IDS`
+ * used to be both "every format that exists" and "every format to build by
+ * default", which was the same list only while every format was `finishOn:
+ * 'any'`. Adding Flatpak to `FORMAT_IDS` alone would have made a bare
+ * `gjsify ship` demand `flatpak-builder` of every project that ever packaged a
+ * `.deb` — and on a host without it, of every `release-cut.yml` run, which
+ * packs `@gjsify/cli` itself on a bare ubuntu runner. A host-bound format is
+ * opt-in through `--target` or `gjsify.ship.targets`; `--help` still lists all
+ * of them.
+ */
+export declare const DEFAULT_FORMAT_IDS: FormatId[];
+/**
+ * Refuse a format this host cannot finish, BEFORE anything is built or written.
+ *
+ * `host` is injected so both branches are unit-testable from any machine — the
+ * same reason `resolvePrebuildDirName` and `checkTypeSkew`'s readers are pure.
+ * The message names the two-phase split rather than just saying no: the answer
+ * to "I am on macOS and want a Flatpak" is `--stage` here and `--from-stage` on
+ * a Linux runner, and a refusal that does not say so reads as "unsupported".
+ */
+export declare function assertHostCanFinish(format: FormatDescriptor, host?: string): void;
+/**
+ * Refuse a format whose tools are not installed, with the tool named.
+ *
+ * Separate from {@link assertHostCanFinish} because the two failures have
+ * different fixes — one needs a different machine, the other needs a package —
+ * and separate from the packer's own `notFound` handler because it fires BEFORE
+ * a build: `gjsify ship` runs the project's `build` script first, and finding
+ * out afterwards that `flatpak-builder` is absent costs the whole build.
+ */
+export declare function assertToolsInstalled(format: FormatDescriptor, present?: (cmd: string) => boolean): void;
 /** Parse `--target deb,rpm` into a sorted, deduplicated descriptor list. */
 export declare function resolveFormats(raw: readonly string[]): FormatDescriptor[];

package/lib/utils/ship/formats.js

@@ -1,7 +1,13 @@
-// The per-format table. Everything that differs between `.deb` and `.rpm`
-// outside the archive container itself lives here as DATA, so a new format is
-// a row rather than an edit across the stager, the overlay builder and the
-// artifact namer.
+// The per-format table. Everything that differs between the formats outside the
+// archive container itself lives here as DATA, so a new format is a row rather
+// than an edit across the stager, the overlay builder and the artifact namer.
+//
+// Flatpak is the row that proves the claim: ADR 0024 § 2 predicted "the whole
+// difference between a Flatpak and an `.rpm` is a four-line prefix map", and
+// this file is where that turned out to be one `prefix: '/app'`, one arch table
+// and one filename. What it also proved is what the design did NOT predict —
+// a format can be host-bound (§ A3), so `host` is a descriptor field now.
+import { isOnPath } from '../check-system-deps.js';
 // `process.arch` → the format's architecture name. Taken from dpkg's own
 // `data/cputable` and rpm's arch table. `arm` cannot be told apart from
 // `armel` by a running process, and Debian's hard-float port is what anything
@@ -32,16 +38,49 @@ function lookupArch(table, arch, label) {
     }
     return mapped;
 }
+// Flatpak's own vocabulary, which is ostree's: `flatpak --supported-arches` on
+// x86_64 answers `x86_64` then `i386`, and a ref is `app/<id>/<arch>/<branch>`.
+// Deliberately short — a name this table does not know is refused rather than
+// guessed, because the arch is not a label here, it is part of the ref the
+// bundle is exported under and installed from.
+const FLATPAK_ARCH = {
+    x64: 'x86_64',
+    arm64: 'aarch64',
+    ia32: 'i386',
+    arm: 'arm',
+};
 function debArch(arch, archIndependent) {
     return archIndependent ? 'all' : lookupArch(DEBIAN_ARCH, arch, 'Debian');
 }
 function rpmArch(arch, archIndependent) {
     return archIndependent ? 'noarch' : lookupArch(RPM_ARCH, arch, 'RPM');
 }
+/**
+ * Flatpak has no `noarch`, so `archIndependent` is ignored — and that is a
+ * measured difference, not an oversight.
+ *
+ * `all`/`noarch` exist because apt and dnf REFUSE a package whose architecture
+ * is not the machine's. Flatpak asks the opposite question: every ref names an
+ * arch, `flatpak install` resolves the one matching the host, and an app with no
+ * arch is not installable at all. So a payload of pure JavaScript still ships as
+ * `app/<id>/x86_64/stable` — which is also what Flathub does for every
+ * interpreted app it hosts.
+ */
+function flatpakArch(arch, _archIndependent) {
+    return lookupArch(FLATPAK_ARCH, arch, 'Flatpak');
+}
+/** `.deb` and `.rpm` are written by this tree, so they exec nothing and read back with GNU tools. */
+const WRITTEN_HERE = (readWith) => ({
+    finishOn: 'any',
+    requiredTools: [],
+    oracle: { readWith, readOn: ['linux'], selfReading: false },
+});
 export const FORMATS = {
     deb: {
         id: 'deb',
         prefix: '/usr',
+        host: WRITTEN_HERE(['ar', 'tar', 'dpkg-deb', 'lintian']),
+        depends: 'deb',
         // Debian policy § 12.5: every package ships its copyright in
         // /usr/share/doc/<package>/copyright, and lintian errors without it.
         licenseDest: (binaryName) => `share/doc/${binaryName}/copyright`,
@@ -52,13 +91,121 @@ export const FORMATS = {
     rpm: {
         id: 'rpm',
         prefix: '/usr',
+        host: WRITTEN_HERE(['rpm', 'rpm2cpio', 'cpio']),
+        depends: 'rpm',
         licenseDest: (binaryName) => `share/licenses/${binaryName}/LICENSE`,
         licenseKind: 'plain',
         archName: rpmArch,
         fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.${archLabel}.rpm`,
     },
+    flatpak: {
+        id: 'flatpak',
+        // The one-line difference ADR 0024 § 2 promised. Nothing in the payload
+        // changes: the launcher derives its prefix at runtime (§ 3), so the same
+        // staged `bin/<name>` works under /usr and under /app.
+        prefix: '/app',
+        host: {
+            // A single-file bundle is an OSTree static delta, and the only writer
+            // of one is `flatpak build-bundle`. Unlike the `.dmg` (§ A6) that is
+            // not an OS restriction: flatpak runs on Linux, so the format is
+            // Linux-bound the way the app itself is.
+            finishOn: ['linux'],
+            requiredTools: ['flatpak-builder', 'flatpak'],
+            installHint: 'Fedora: `sudo dnf install flatpak flatpak-builder`, Debian/Ubuntu: ' +
+                '`sudo apt install flatpak flatpak-builder`',
+            oracle: {
+                // `flatpak build-import-bundle` into a FRESH repo, then
+                // `ostree ls -R`: ostree parses the delta this tree never wrote,
+                // and prints a path + mode + size per file. Measured on this
+                // workstation — that listing is what the e2e suite compares
+                // against the staged payload.
+                readWith: ['flatpak', 'ostree'],
+                readOn: ['linux'],
+                selfReading: false,
+            },
+        },
+        // A Flatpak's one dependency is its runtime, named in the manifest. See
+        // `DistroFormatId`: there is no `Depends:` field here to under-declare,
+        // which also means the unmapped-namespace refusal ADR 0024 § 6 built for
+        // deb and rpm has nothing to say about this format.
+        depends: null,
+        // No policy demands a location, so this follows rpm's — one fewer shape
+        // for a reader to learn, and `/app/share/licenses/<name>/LICENSE` is
+        // where the equivalent file sits in the `.rpm` built from the same stage.
+        licenseDest: (binaryName) => `share/licenses/${binaryName}/LICENSE`,
+        licenseKind: 'plain',
+        archName: flatpakArch,
+        // Named after the APP ID, not the binary: the id is the ref the file
+        // installs as, and it is what `flatpak install ./file.flatpak` prints.
+        fileName: (s, archLabel) => `${s.appId}-${s.version}-${s.release}.${archLabel}.flatpak`,
+    },
 };
-export const FORMAT_IDS = ['deb', 'rpm'];
+// DERIVED, never a second list. `FORMATS` is `Record<FormatId, …>`, so the
+// compiler already refuses a `FormatId` with no descriptor — reading the keys
+// back inherits that guarantee for free. Written out by hand this was the one
+// unbound copy of the vocabulary: adding a format to `FormatId` and `FORMATS`
+// compiled fine and left this list short, which would have made the new format
+// missing from `--help` and REFUSED by `readStage` as an unknown id.
+// Insertion order is stable for string keys, and `resolveFormats` sorts anyway.
+export const FORMAT_IDS = Object.keys(FORMATS);
+/**
+ * What `gjsify ship` builds when nothing said otherwise — every format that
+ * needs no tool and no particular host.
+ *
+ * A SECOND derivation from the same table, and it has to be one: `FORMAT_IDS`
+ * used to be both "every format that exists" and "every format to build by
+ * default", which was the same list only while every format was `finishOn:
+ * 'any'`. Adding Flatpak to `FORMAT_IDS` alone would have made a bare
+ * `gjsify ship` demand `flatpak-builder` of every project that ever packaged a
+ * `.deb` — and on a host without it, of every `release-cut.yml` run, which
+ * packs `@gjsify/cli` itself on a bare ubuntu runner. A host-bound format is
+ * opt-in through `--target` or `gjsify.ship.targets`; `--help` still lists all
+ * of them.
+ */
+export const DEFAULT_FORMAT_IDS = FORMAT_IDS.filter((id) => FORMATS[id].host.finishOn === 'any');
+/**
+ * Refuse a format this host cannot finish, BEFORE anything is built or written.
+ *
+ * `host` is injected so both branches are unit-testable from any machine — the
+ * same reason `resolvePrebuildDirName` and `checkTypeSkew`'s readers are pure.
+ * The message names the two-phase split rather than just saying no: the answer
+ * to "I am on macOS and want a Flatpak" is `--stage` here and `--from-stage` on
+ * a Linux runner, and a refusal that does not say so reads as "unsupported".
+ */
+export function assertHostCanFinish(format, host = process.platform) {
+    const { finishOn } = format.host;
+    if (finishOn === 'any' || finishOn.includes(host))
+        return;
+    throw new Error(`gjsify ship: a ${format.id} artifact is packed on ${finishOn.join(' or ')} and ` +
+        `this host is ${host} (ADR 0024 § A1: a container is produced where its format's tool lives). ` +
+        'Assembly is not host-bound, so the way across is the two-phase split: run ' +
+        '`gjsify ship --stage` here, move `ship/stage/` to a ' +
+        `${finishOn.join('/')} runner, and finish with ` +
+        `\`gjsify ship --from-stage <dir> --target ${format.id}\`.`);
+}
+/**
+ * Refuse a format whose tools are not installed, with the tool named.
+ *
+ * Separate from {@link assertHostCanFinish} because the two failures have
+ * different fixes — one needs a different machine, the other needs a package —
+ * and separate from the packer's own `notFound` handler because it fires BEFORE
+ * a build: `gjsify ship` runs the project's `build` script first, and finding
+ * out afterwards that `flatpak-builder` is absent costs the whole build.
+ */
+export function assertToolsInstalled(format, present = isOnPath) {
+    const missing = format.host.requiredTools.filter((tool) => !present(tool));
+    if (missing.length === 0)
+        return;
+    // The install instruction is the DESCRIPTOR's, not this function's: hardcoded
+    // here it was `dnf install flatpak flatpak-builder` for every format that
+    // will ever need a tool, which is the branch this table exists to avoid.
+    const hint = format.host.installHint;
+    throw new Error(`gjsify ship: packing a ${format.id} needs ${format.host.requiredTools.join(' and ')}, and ` +
+        `${missing.join(', ')} ${missing.length > 1 ? 'are' : 'is'} not on PATH. ` +
+        `${hint === undefined ? 'Install it' : `Install it (${hint})`}, or drop this target — the other ` +
+        `formats need no tools at all. \`gjsify ship --stage\` also works without ${missing.join('/')}: ` +
+        'the payload is assembled by this CLI and only the container needs them.');
+}
 /** Parse `--target deb,rpm` into a sorted, deduplicated descriptor list. */
 export function resolveFormats(raw) {
     const names = raw

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

@@ -0,0 +1,19 @@
+import type { ShipMimeType } from './types.js';
+/**
+ * Validate the declared types, throwing on anything that would install and then not work.
+ *
+ * Each refusal is a silent failure made loud:
+ *  - a malformed type name is written into the XML and ignored by `update-mime-database`;
+ *  - a glob without `*.` never matches (`bauplan` matches only a file called exactly that);
+ *  - a type with no glob and no parent type can never be DETECTED, so it is registered and unused;
+ *  - a duplicate definition makes which comment wins depend on document order.
+ */
+export declare function validateMimeTypes(types: readonly ShipMimeType[]): void;
+/**
+ * The shared-mime-info document for `types`.
+ *
+ * One file per package, named after the app id, because `share/mime/packages/` is shared: a generic
+ * name is a collision with whatever another package put there — the same reason the schema staging
+ * uses the app id.
+ */
+export declare function renderMimePackage(types: readonly ShipMimeType[]): string;

package/lib/utils/ship/mime.js

@@ -0,0 +1,89 @@
+// Defining a file type for the system — the half `MimeType=` cannot do on its own.
+//
+// A desktop entry's `MimeType=` says "I open this type". It does NOT say the type EXISTS. For a
+// standard type that is fine, because the distribution's shared-mime-info already defines it; for a
+// type of the project's own it is not, and the failure is the quietest kind there is: nothing knows
+// what a `.bauplan` file is, so the file manager never assigns the type, `MimeType=` matches
+// nothing, and a double-click does nothing at all. No error is printed and no log line is written —
+// the association simply never fires, which is indistinguishable from "the app is not installed".
+//
+// So a project that invents a type also ships a shared-mime-info document, and the package refreshes
+// the MIME cache on install (see `scripts.ts`) — an unrefreshed cache is the same silence again.
+/** XML text escaping. Only the five that matter in element content and attributes. */
+function esc(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+const TYPE_RE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/;
+/**
+ * Validate the declared types, throwing on anything that would install and then not work.
+ *
+ * Each refusal is a silent failure made loud:
+ *  - a malformed type name is written into the XML and ignored by `update-mime-database`;
+ *  - a glob without `*.` never matches (`bauplan` matches only a file called exactly that);
+ *  - a type with no glob and no parent type can never be DETECTED, so it is registered and unused;
+ *  - a duplicate definition makes which comment wins depend on document order.
+ */
+export function validateMimeTypes(types) {
+    const seen = new Set();
+    for (const entry of types) {
+        if (!TYPE_RE.test(entry.type)) {
+            throw new Error(`gjsify ship: \`gjsify.ship.mimeTypes\` has an invalid type "${entry.type}". ` +
+                'Expected `<media>/<subtype>`, e.g. `application/x-bauplan` — update-mime-database ' +
+                'ignores a malformed name, so the type would install and never resolve.');
+        }
+        if (seen.has(entry.type)) {
+            throw new Error(`gjsify ship: \`gjsify.ship.mimeTypes\` defines ${entry.type} twice. ` +
+                'Which comment and glob set win would depend on document order.');
+        }
+        seen.add(entry.type);
+        if (entry.comment.trim() === '') {
+            throw new Error(`gjsify ship: ${entry.type} has an empty \`comment\`. A file manager then shows the ` +
+                'user the raw type string instead of a name.');
+        }
+        for (const glob of entry.globs ?? []) {
+            if (!glob.includes('*') && !glob.includes('?') && !glob.includes('[')) {
+                throw new Error(`gjsify ship: ${entry.type} has the glob "${glob}", which matches only a file ` +
+                    `named exactly that. A suffix pattern is written \`*.${glob.replace(/^\.+/, '')}\`.`);
+            }
+        }
+        if ((entry.globs ?? []).length === 0 && entry.subClassOf === undefined) {
+            throw new Error(`gjsify ship: ${entry.type} declares neither \`globs\` nor \`subClassOf\`, so nothing ` +
+                'can ever match it. The type would be registered and then never assigned to a file.');
+        }
+    }
+}
+/**
+ * The shared-mime-info document for `types`.
+ *
+ * One file per package, named after the app id, because `share/mime/packages/` is shared: a generic
+ * name is a collision with whatever another package put there — the same reason the schema staging
+ * uses the app id.
+ */
+export function renderMimePackage(types) {
+    const body = types
+        .map((entry) => {
+        const lines = [`  <mime-type type="${esc(entry.type)}">`, `    <comment>${esc(entry.comment)}</comment>`];
+        if (entry.subClassOf !== undefined) {
+            lines.push(`    <sub-class-of type="${esc(entry.subClassOf)}"/>`);
+        }
+        for (const glob of entry.globs ?? []) {
+            lines.push(`    <glob pattern="${esc(glob)}"/>`);
+        }
+        if (entry.genericIcon !== undefined) {
+            lines.push(`    <generic-icon name="${esc(entry.genericIcon)}"/>`);
+        }
+        lines.push('  </mime-type>');
+        return lines.join('\n');
+    })
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
+${body}
+</mime-info>
+`;
+}

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

@@ -16,8 +16,84 @@ export interface PayloadEntry {
  * 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 declare function buildTimestamp(bundlePath: string, env?: Record<string, string | undefined>): number;
+/**
+ * What the payload itself says about what it installs.
+ *
+ * Every field here used to be answered from the SETTINGS — `settings.iconFiles.length > 0`,
+ * `settings.schemaFiles.length > 0`, `settings.typelibFiles` — i.e. from lists of absolute paths
+ * on the BUILD host. Two things were wrong with that, and the second is why this function exists
+ * at all:
+ *
+ *  1. It answered a different question than the one being asked. `cacheRefreshCommands` emits
+ *     `gtk-update-icon-cache <prefix>/share/icons/hicolor` — the honest precondition is "did this
+ *     package install anything into that directory", not "did the project have icon files lying
+ *     around". They come apart for a `kind: 'cli'` project with a `data/icons/` folder: the
+ *     planner stages no icon (icons are an `'app'` thing), the settings still listed them, and the
+ *     postinst refreshed a cache for files that were never installed.
+ *  2. An absolute build-host path cannot cross to the host that packs the artifact
+ *     (ADR 0024 § A2). Carrying `iconFiles: ["/home/…/icon.svg"]` in a stage manifest so that
+ *     `.length > 0` can be read on another machine is authoring a value that is measurable right
+ *     there in the tree.
+ *
+ * Path-only, on purpose — `isArchIndependent` is the sibling that reads BYTES, and the two answer
+ * different questions from the same payload. The same split as `plan.ts`'s `isExecutableAsset`
+ * (by name) versus this module's magic sniffing (by content).
+ */
+export interface PayloadFacts {
+    /** The payload installs a `share/applications/*.desktop`. */
+    hasDesktopEntry: boolean;
+    /** The payload installs into `share/icons/hicolor/`. */
+    hasIcons: boolean;
+    /** The payload installs a compiled-on-install `share/glib-2.0/schemas/*.gschema.xml`. */
+    hasSchemas: boolean;
+    /** The payload installs a `share/mime/packages/*.xml`, so the mime cache needs rebuilding. */
+    hasMimeTypes: boolean;
+    /** Prefix-relative paths of the typelibs the payload carries itself. */
+    bundledTypelibs: string[];
+}
+/**
+ * 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 declare function readPayloadFacts(entries: readonly {
+    path: string;
+}[]): PayloadFacts;
+/**
+ * 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 declare function readShebangInterpreters(payload: readonly PayloadEntry[]): string[];
 /**
  * Does the payload contain anything architecture-specific?
  *