@gjsify/cli 0.43.0 → 0.45.0

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

@@ -1,4 +1,4 @@
-import type { FormatId } from './types.js';
+import type { DistroFormatId } from './types.js';
 /**
  * The GJS the bundles target (root AGENTS.md § Constraints: GJS 1.86 /
  * SpiderMonkey 140, Rolldown `firefox140`). A `--app gjs` bundle can carry
@@ -14,7 +14,32 @@ import type { FormatId } from './types.js';
  * is how a project whose bundle really does run on older GJS lowers it.
  */
 export declare const DEFAULT_GJS_FLOOR = "1.86";
-export declare function warnAboutGjsFloor(format: FormatId, floor: string): string[];
+/**
+ * The Node the `--app node` bundles target, as a MAJOR.
+ *
+ * Node 24 is the LTS line `@gjsify/node-runtime-*` bundles for macOS and
+ * Windows, and this is the Linux half of the same decision: where an
+ * interpreter is bundled, the floor is what was bundled; where it is depended
+ * on, the floor is what the bundle needs.
+ *
+ * It excludes EVERY current DEB stable/LTS — Debian 13 trixie 20, Ubuntu 24.04
+ * LTS 18, Ubuntu 26.04 LTS 22; only Debian 14 forky has 24. `warnAboutNodeFloor`
+ * is what makes that visible at ship time, and `gjsify.ship.minNodeVersion` is
+ * how a project whose bundle really does run on an older Node lowers it. The
+ * same honest-floor-plus-warning answer as {@link DEFAULT_GJS_FLOOR}, one axis
+ * over — and it will fire far more often.
+ */
+export declare const DEFAULT_NODE_FLOOR = "24";
+export declare function warnAboutGjsFloor(format: DistroFormatId, floor: string): string[];
+/**
+ * Warn when the Node floor cannot be satisfied by a released Debian or Ubuntu.
+ * Returns the warning lines; empty when the floor is fine.
+ *
+ * Only reached when the payload actually needs an interpreter — a `--app gjs`
+ * package declares no Node dependency, so warning about its floor would be
+ * noise attached to a line that is never emitted.
+ */
+export declare function warnAboutNodeFloor(format: DistroFormatId, floor: string): string[];
 export interface DependsInputs {
     /** GI namespaces the bundle imports, in `Ns-Version` spelling. */
     namespaces: readonly string[];
@@ -29,13 +54,33 @@ export interface DependsInputs {
     hasIcons: boolean;
     /** Whether the payload installs GSettings schemas. */
     hasSchemas: boolean;
+    /**
+     * The interpreter the launcher execs — `settings.app`, the SAME field
+     * `renderLauncher` branches on.
+     *
+     * Not a payload fact, and the attempt to make it one is worth keeping: the
+     * first cut derived it from a staged FILENAME (`*.node.mjs`), which is wrong
+     * in both directions. `discoverPayload` stages the whole directory beside
+     * the bundle and `dist/<name>.gjs.js` next to `dist/<name>.node.mjs` is the
+     * documented normal layout, so a pure `--app gjs` project that also builds a
+     * Node bundle declared a Node dependency it never execs — and with a `>= 24`
+     * floor that `.deb` is REFUSED by apt on trixie, Ubuntu 24.04 and Ubuntu
+     * 26.04. A working package made uninstallable is not "one extra package
+     * installed".
+     *
+     * The honest source is the one thing that decides both the launcher and this
+     * list. `assertLauncherMatchesInterpreter` re-reads the staged launcher and
+     * refuses a package where the two disagree, which is the check a payload
+     * heuristic could never be.
+     *
+     * macOS and Windows never reach here: there the interpreter is CARRIED, from
+     * `@gjsify/node-runtime-<target>`.
+     */
+    interpreter: 'gjs' | 'node';
     /** User-supplied additions for this format. */
     extra: readonly string[];
     /** Project-supplied table rows, filling gaps in {@link TYPELIB_PACKAGES}. */
-    typelibPackages?: Record<string, {
-        deb: string;
-        rpm: string;
-    }>;
+    typelibPackages?: Record<string, Record<DistroFormatId, 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.
@@ -43,13 +88,15 @@ export interface DependsInputs {
     bundledTypelibs?: readonly string[];
     /** Minimum GJS. Default {@link DEFAULT_GJS_FLOOR}. */
     minGjsVersion?: string;
+    /** Minimum Node major, when one is depended on. Default {@link DEFAULT_NODE_FLOOR}. */
+    minNodeVersion?: string;
 }
 /**
  * The `Depends:` / `Requires:` list for one format.
  *
  * @throws when a namespace has no entry in the table — see the module header.
  */
-export declare function deriveDepends(format: FormatId, inputs: DependsInputs): string[];
+export declare function deriveDepends(format: DistroFormatId, inputs: DependsInputs): string[];
 /** One parsed dependency. `relation`/`version` are absent for an unversioned one. */
 export interface ParsedDepend {
     name: string;

package/lib/utils/ship/depends.js

@@ -35,13 +35,77 @@
  * is how a project whose bundle really does run on older GJS lowers it.
  */
 export const DEFAULT_GJS_FLOOR = '1.86';
+/**
+ * The Node the `--app node` bundles target, as a MAJOR.
+ *
+ * Node 24 is the LTS line `@gjsify/node-runtime-*` bundles for macOS and
+ * Windows, and this is the Linux half of the same decision: where an
+ * interpreter is bundled, the floor is what was bundled; where it is depended
+ * on, the floor is what the bundle needs.
+ *
+ * It excludes EVERY current DEB stable/LTS — Debian 13 trixie 20, Ubuntu 24.04
+ * LTS 18, Ubuntu 26.04 LTS 22; only Debian 14 forky has 24. `warnAboutNodeFloor`
+ * is what makes that visible at ship time, and `gjsify.ship.minNodeVersion` is
+ * how a project whose bundle really does run on an older Node lowers it. The
+ * same honest-floor-plus-warning answer as {@link DEFAULT_GJS_FLOOR}, one axis
+ * over — and it will fire far more often.
+ */
+export const DEFAULT_NODE_FLOOR = '24';
+/**
+ * The package providing a Node interpreter, per format.
+ *
+ * ⚠️ THE TWO STRINGS ARE NOT THE SAME NAME, and getting rpm's wrong is silent.
+ * `Requires: nodejs >= 24` is a NO-OP on Fedora. Measured with `dnf repoquery`
+ * on Fedora 44:
+ *
+ *     --whatprovides 'nodejs >= 24'          → nodejs22-1:22.23.1-2.fc44
+ *     --whatprovides 'nodejs(engine) >= 24'  → nodejs24-1:24.18.0-1.fc44
+ *
+ * F44 has no real `nodejs` package at all — the name is a virtual Provide of the
+ * stream packages, which carry **Epoch 1**. A bare `>= 24` desugars to `0:24`,
+ * and `1:22.23.1` beats it on epoch alone, so the floor admits the very version
+ * it was written to exclude. `nodejs(engine)` carries no epoch and compares as
+ * written. (Streams 20/22/24 are parallel-installable, which is why the name has
+ * to be a Provide in the first place.) The spelling appears nowhere in the
+ * Fedora packaging guideline's own source — it comes from real spec files.
+ *
+ * No `/usr/bin/node` file dependency beside it — right answer, and the FIRST
+ * reason written here for it was wrong, so both are recorded. It is not that
+ * `nodejs24` pulls the symlink in: `/usr/bin/node` is provided by `nodejs20-bin`,
+ * `nodejs22-bin` AND `nodejs24-bin`, all three of which
+ * `Provides`/`Conflicts: alternative-for(nodejs-bin)` and are therefore mutually
+ * exclusive. `nodejs24` itself installs `/usr/bin/node-24`. So the file
+ * dependency is satisfied by ANY stream's `-bin`, which makes it worthless as a
+ * version constraint — that is why it is not emitted.
+ *
+ * ⚠️ AND THAT LEAVES A REAL HOLE, which no dependency this writer can emit
+ * closes. Measured on Fedora 44:
+ *
+ *     dnf install --assumeno nodejs22-bin 'nodejs(engine) >= 24'
+ *       → installs nodejs22-bin, nodejs22, nodejs24, nodejs24-libs
+ *       → and NOT nodejs24-bin
+ *
+ * Every requirement is met and `node` on `PATH` is still 22. rpm's alternatives
+ * scheme has no vocabulary for "the stream that owns the symlink must be at
+ * least 24", so an app that must have 24 on `PATH` has to check at runtime; a
+ * package cannot ask for it. Recorded here because the gap is invisible from the
+ * emitted `Requires:` line, which looks correct and is.
+ *
+ * (`nodejs24` carries no bare `nodejs` Provide at all — only `nodejs22` does on
+ * F44, which is the other half of why the epoch trap above bites.)
+ *
+ * A `Record`, for the reason {@link SCHEMA_COMPILER_PACKAGE} records: a ternary
+ * reads as a two-way choice and is really "deb, or ELSE rpm's name", and a third
+ * format silently inheriting rpm's spelling has happened here before, at exit 0.
+ */
+const NODE_PACKAGE = { deb: 'nodejs', rpm: 'nodejs(engine)' };
 /**
  * The package providing `glib-compile-schemas`, per format.
  *
  * A record, not `format === 'deb' ? … : …`. The ternary reads as a two-way
  * choice and is really "deb, or ELSE rpm's package name" — measured on a third
  * format, `dmg` got `glib2`, at exit 0, in the `Depends:` of a package that has
- * no such thing. Adding a `FormatId` now fails to build here instead.
+ * no such thing. Adding a `DistroFormatId` now fails to build here instead.
  */
 const SCHEMA_COMPILER_PACKAGE = { deb: 'libglib2.0-bin', rpm: 'glib2' };
 /** Debian's `gjs` versions per suite, as measured 2026-08-15 — see {@link warnAboutGjsFloor}. */
@@ -53,10 +117,10 @@ const DEBIAN_GJS = 'trixie ships 1.82.3 and forky 1.88.1; 1.84 and 1.86 were ski
 /**
  * Which formats this Debian-suite warning is ABOUT.
  *
- * A `Record<FormatId, …>` and not `format !== 'deb'`: the negative form answers
+ * A `Record<DistroFormatId, …>` and not `format !== 'deb'`: the negative form answers
  * for every format that will ever exist, and answers "stay quiet" — so a third
  * format would inherit silence about a floor nobody has checked for its distro,
- * with no compile error. As a record, adding a `FormatId` fails to build until
+ * with no compile error. As a record, adding a `DistroFormatId` fails to build until
  * someone decides. `rpm` is false because Fedora ships a current GJS, which is a
  * measured fact about Fedora, not a default.
  */
@@ -78,6 +142,49 @@ export function warnAboutGjsFloor(format, floor) {
             'to make apt happy, because the result is an install that succeeds and an app that does not start.',
     ];
 }
+/**
+ * Node majors per DEB suite, as measured 2026-08-28 — see {@link warnAboutNodeFloor}.
+ */
+const DEBIAN_NODE = 'trixie ships 20, forky 24; Ubuntu 24.04 LTS ships 18 and 26.04 LTS 22';
+/**
+ * Which formats the Node-floor warning is ABOUT.
+ *
+ * `rpm` is false, and it is a measured fact about Fedora rather than a default:
+ * F43/44/45 default to Node 22 but ship `nodejs24` in the base repository,
+ * parallel-installable, so `nodejs(engine) >= 24` resolves without an extra
+ * repository. Debian and Ubuntu have no such stream packages — one `nodejs` per
+ * suite, and it is older than 24 in every current stable/LTS.
+ *
+ * A `Record` and not `format !== 'deb'`, for the reason
+ * {@link GJS_FLOOR_IS_DEBIAN_NEWS} spells out: the negative form answers "stay
+ * quiet" for every format that will ever exist, including ones nobody has
+ * checked a distribution for.
+ */
+const NODE_FLOOR_IS_DEBIAN_NEWS = { deb: true, rpm: false };
+/**
+ * Warn when the Node floor cannot be satisfied by a released Debian or Ubuntu.
+ * Returns the warning lines; empty when the floor is fine.
+ *
+ * Only reached when the payload actually needs an interpreter — a `--app gjs`
+ * package declares no Node dependency, so warning about its floor would be
+ * noise attached to a line that is never emitted.
+ */
+export function warnAboutNodeFloor(format, floor) {
+    if (!NODE_FLOOR_IS_DEBIAN_NEWS[format])
+        return [];
+    // Ubuntu 26.04 LTS's 22 is the newest a current DEB stable/LTS carries;
+    // trixie's 20 is older still. A floor of 22 or below is satisfiable
+    // somewhere released and stays quiet.
+    if (compareVersions(floor, '22') <= 0)
+        return [];
+    return [
+        `gjsify ship: \`Depends: nodejs (>= ${floor})\` is not satisfiable on any current DEB stable/LTS — ` +
+            `${DEBIAN_NODE}. The package installs on forky/sid and on distributions with a newer Node. Set ` +
+            '`gjsify.ship.minNodeVersion` if this bundle genuinely runs on an older Node; do NOT lower it ' +
+            'to make apt happy, because the result is an install that succeeds and an app that dies on the ' +
+            'first syntax or API the older interpreter does not have.',
+    ];
+}
 /** Numeric dotted-version compare. Enough for `1.82.3` vs `1.86`. */
 function compareVersions(a, b) {
     const left = a.split('.').map(Number);
@@ -155,7 +262,14 @@ const BUNDLED_TYPELIB = /^Gjsify[A-Z]/;
  * @throws when a namespace has no entry in the table — see the module header.
  */
 export function deriveDepends(format, inputs) {
-    const out = [`gjs >= ${inputs.minGjsVersion ?? DEFAULT_GJS_FLOOR}`];
+    // The interpreter the launcher execs, and nothing else: a package declares ONE.
+    // Linux is the only place this is a dependency at all — macOS and Windows have
+    // no system Node, so an artifact for those CARRIES one from
+    // `@gjsify/node-runtime-<target>`, and that is the whole reason those three
+    // packages exist and this one line is their opposite.
+    const out = inputs.interpreter === 'node'
+        ? [`${NODE_PACKAGE[format]} >= ${inputs.minNodeVersion ?? DEFAULT_NODE_FLOOR}`]
+        : [`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
@@ -206,8 +320,8 @@ export function deriveDepends(format, inputs) {
     if (inputs.hasSchemas)
         out.push(SCHEMA_COMPILER_PACKAGE[format]);
     out.push(...inputs.extra);
-    // Set-dedupe keeps first-insertion order, so `gjs` stays first and the
-    // list is stable across runs.
+    // Set-dedupe keeps first-insertion order, so the interpreter stays first and
+    // the list is stable across runs.
     return [...new Set(out)];
 }
 /**

package/lib/utils/ship/discover.js

@@ -52,7 +52,24 @@ function discoverTypelibs(projectDir, dirs) {
                 '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))
+            // Every shared-library spelling, not only ELF's. A typelib is
+            // useless without its library on macOS and Windows too, and the
+            // `.so`-only test dropped `libgwebgl.dylib` and `gwebgl-0.dll` while
+            // staging the `.typelib` beside them — a package that installs and
+            // dies at the first import, with nothing in the output saying so.
+            // The layout axis (ADR 0024 § 2) is what put those two files in
+            // reach: they land in `Contents/Frameworks` and in the program
+            // directory's `lib\`.
+            // Case-insensitive for the extensions that come off case-preserving-
+            // but-INSENSITIVE filesystems — `LIBFOO.DLL` and `Foo.Dylib` are
+            // ordinary names on macOS and Windows, and a lowercase-only test drops
+            // them into exactly the silent failure the paragraph above describes.
+            //
+            // NOT for `.so`, and the asymmetry is the reason rather than an
+            // oversight: ELF sonames come off case-SENSITIVE filesystems where
+            // `libfoo.so` is the only spelling, and `/i` there additionally makes
+            // `README.SO` a shared library. One rationale, one scope.
+            if (/\.(typelib|dylib|dll)$/i.test(file) || /\.so(\.\d+)*$/.test(file))
                 out.push(join(root, file));
         }
     }

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

@@ -0,0 +1,71 @@
+import type { PackSettings } from './types.js';
+/** The tool this packer execs. One spelling, read by this module AND by the format row. */
+export declare const DMG_TOOL = "hdiutil";
+/**
+ * What the mounted image is called in the Finder's sidebar.
+ *
+ * The DISPLAY name, like the `.app` inside it — the volume and the bundle are
+ * the two things a user reads during the one interaction this format has, and
+ * spelling them differently (`Ship Demo.app` inside `ship-demo-1.2.3`) makes the
+ * window look like somebody else's download. The FILE keeps the versioned,
+ * space-free name, because that one lands in a downloads folder beside others;
+ * `FormatDescriptor.fileName` is where that split lives, exactly as it does for
+ * the `.app` and its zip.
+ *
+ * EMPTY IS REFUSED, and it is not defensive: `resolveShipSettings` derives the
+ * name as `metadata.name ?? titleCase(binaryName)` and `??` passes `''` straight
+ * through — the same hole `windowsProgramDirName` documents. `hdiutil` answers an
+ * empty `-volname` by calling the volume `untitled`, at exit 0, so the image
+ * would build and mount under a name nothing in the project ever chose.
+ */
+export declare function dmgVolumeName(settings: PackSettings): string;
+export interface DmgCreateInput {
+    /** The volume label — see {@link dmgVolumeName}. */
+    volumeName: string;
+    /** The directory whose CONTENTS become the volume root; it holds `<App>.app` and nothing else. */
+    sourceDir: string;
+    /** Absolute path the finished `.dmg` is written to. */
+    target: string;
+}
+/**
+ * The exact `hdiutil` invocation, as data.
+ *
+ * Pure, so every flag is unit-testable from Linux — which is the only kind of
+ * host this project's contributors and its `e2e` job have. Same split as
+ * `renderShipFlatpakManifest`: what the tool is TOLD is checkable everywhere,
+ * what the tool DOES is checkable on the one OS that has it, and the two are not
+ * the same test.
+ *
+ * `-srcfolder` and not `-srcdevice`/`-size`: the folder's contents become the
+ * volume root, so `hdiutil` sizes the image itself. Passing a `-size` instead is
+ * how a `.dmg` build starts failing on the day the payload grows past a number
+ * somebody typed once.
+ */
+export declare function hdiutilCreateArgs(input: DmgCreateInput): string[];
+export interface DmgPackInput extends DmgCreateInput {
+    verbose: boolean;
+    /** Working root, so the log can name the directory that became the volume. */
+    workDir: string;
+}
+/**
+ * Build the image at `input.target`.
+ *
+ * Unlike the Flatpak packer's tool, this one cannot be installed where it is
+ * missing: `hdiutil` ships with macOS and exists nowhere else. So the `notFound` branch does not say "install
+ * it"; it says which host this belongs on and how the payload gets there, which
+ * is the same two-phase sentence `assertHostCanFinish` prints one step earlier.
+ * Reaching this branch at all means `process.platform` said darwin and `hdiutil`
+ * was still absent, so the honest advice is "this macOS installation is broken",
+ * not a package name.
+ */
+export declare function buildDmgImage(input: DmgPackInput): Promise<void>;
+/**
+ * Where the volume is assembled before `hdiutil` turns it into an image.
+ *
+ * A directory of its own under the run's output root, never `out/` itself: the
+ * volume root holds the `.app` and NOTHING ELSE, because `-srcfolder` copies
+ * whatever it finds — a stray sibling would ride into the image, and the reader
+ * that would catch it is the same listing comparison that would then have to be
+ * relaxed to allow it.
+ */
+export declare function dmgVolumeDir(outRoot: string): string;

package/lib/utils/ship/dmg.js

@@ -0,0 +1,181 @@
+// The `.dmg` packer — ADR 0024 § A1/§ A6, issue #1354 M4.
+//
+// THE FIRST FORMAT THAT IS HOST-BOUND IN THE `HostRequirement` SENSE, and the
+// distinction ADR 0024 § A3 drew between its two refusals is what this row is
+// the first subject of. A Flatpak is `finishOn: ['linux']` because flatpak runs
+// on Linux — the format is bound the way the application is. A `.dmg` is bound
+// by the CONTAINER: it is a UDIF image over a real HFS+/APFS volume, no
+// HFS+/APFS writer exists anywhere in this tree, and `hdiutil` is macOS-only.
+// So `assertHostCanFinish` refuses it off darwin and `assertToolsInstalled`
+// names `hdiutil` on a darwin host that somehow lacks it — two failures with
+// two different fixes, which is exactly why they are two functions.
+//
+// A HAND-WRITTEN UDIF WRITER STAYS REJECTED (§ A6), in that section's own
+// words: 1200-2000 lines against a whole existing packer surface of ~1243, and
+// every mistake silent, because the Finder mounts the image and shows an empty
+// window. What we would buy is an independent reader, and 7-Zip already
+// advertises `Dmg`, `HFS` and `APFS` handlers regardless of who wrote the file.
+//
+// WHICH MAKES THE ORACLE THE INTERESTING PART, because `hdiutil verify` is
+// `hdiutil` reading what `hdiutil` wrote. The reader is a chain that runs on
+// LINUX — `7z l` (7-Zip 23.01 on ubuntu-24.04 carries `Dmg`, `HFS` and `APFS`),
+// `7z t` to inflate what it stores, then `dmg2img` to a raw volume and
+// `fsck.hfsplus -f -n` over that — driven by `.github/ship-oracle/verify-dmg.py`
+// and compared against the stage manifest by name, size and MODE. Three
+// implementations, none of them Apple's and none of them ours.
+//
+// TWO hdiutil FLAGS ARE DECISIONS AND NOT DEFAULTS:
+//
+//   * `-fs HFS+J`. APFS is what a modern `hdiutil` reaches for when nothing says
+//     otherwise, and the whole Linux reader chain above is an HFS+ chain —
+//     `dmg2img` writes a raw volume and `fsck.hfsplus` is an HFS+ fsck. An APFS
+//     image would leave 7-Zip's handler as the only reader, i.e. one reader for
+//     the negative control to fool. Journaling costs a read-only image nothing
+//     and `fsck.hfsplus` reads it: measured on ubuntu-24.04 / hfsprogs
+//     540.1.linux3-5build3 against a `mkfs.hfsplus -J` volume, "** Checking
+//     Journaled HFS Plus volume … appears to be OK", exit 0.
+//   * `-format UDZO`, i.e. zlib. The alternatives are ULFO (LZFSE) and ULMO
+//     (LZMA), and the reader that would have to decode them is the OLD one:
+//     ubuntu-24.04 ships 7-Zip 23.01, not this workstation's 26.02. zlib is the
+//     method its `Dmg` handler has read since long before either.
+//
+// WHAT THIS PACKER DOES NOT PUT IN THE VOLUME: an `/Applications` symlink, the
+// drag-here convention. `writePayload` writes regular files and nothing else —
+// which is a property `tests/e2e/ship` and the `ship-stage` job both assert, and
+// a symlink is also what `actions/upload-artifact` silently dereferences. The
+// artifact is still draggable out of the mounted volume; what it lacks is the
+// arrow. Unblocker: a staged-symlink concept with a reader that can see one, at
+// which point the link and its oracle land together.
+import { join } from 'node:path';
+import { describeExit, spawnToCompletion } from '../spawn.js';
+/** The tool this packer execs. One spelling, read by this module AND by the format row. */
+export const DMG_TOOL = 'hdiutil';
+/**
+ * Characters an HFS+ volume name may not contain.
+ *
+ * Two of the three `layout.ts` refuses in a bundle DIRECTORY name — its
+ * `BUNDLE_NAME_FORBIDDEN` is `/[/:\\]/` — and for the same measured reason: `/`
+ * is the POSIX separator and `:` is HFS+'s, and the Finder shows a stored `:` as
+ * a `/` and vice versa. A volume called `Ship/Demo` mounts as `Ship:Demo`, so the
+ * name a user is told to look for is not the name they see. `\` is the one that
+ * is NOT here: it is an ordinary character in a volume name, while a bundle
+ * directory refuses it too and `windowsProgramDirName` refuses it for Windows'
+ * own reasons.
+ */
+const VOLUME_NAME_FORBIDDEN = /[/:]/;
+/**
+ * What the mounted image is called in the Finder's sidebar.
+ *
+ * The DISPLAY name, like the `.app` inside it — the volume and the bundle are
+ * the two things a user reads during the one interaction this format has, and
+ * spelling them differently (`Ship Demo.app` inside `ship-demo-1.2.3`) makes the
+ * window look like somebody else's download. The FILE keeps the versioned,
+ * space-free name, because that one lands in a downloads folder beside others;
+ * `FormatDescriptor.fileName` is where that split lives, exactly as it does for
+ * the `.app` and its zip.
+ *
+ * EMPTY IS REFUSED, and it is not defensive: `resolveShipSettings` derives the
+ * name as `metadata.name ?? titleCase(binaryName)` and `??` passes `''` straight
+ * through — the same hole `windowsProgramDirName` documents. `hdiutil` answers an
+ * empty `-volname` by calling the volume `untitled`, at exit 0, so the image
+ * would build and mount under a name nothing in the project ever chose.
+ */
+export function dmgVolumeName(settings) {
+    const name = settings.name;
+    if (name.trim() === '') {
+        throw new Error('gjsify ship: the macOS image has no name to call its volume — `gjsify.ship.name` (or the ' +
+            'package name it is derived from) is empty. `hdiutil` would accept that and mount the ' +
+            'image as `untitled`, which is the name every nameless disk image on the machine has.');
+    }
+    if (VOLUME_NAME_FORBIDDEN.test(name)) {
+        throw new Error(`gjsify ship: the macOS image would mount a volume called "${name}", and HFS+ cannot hold it: ` +
+            'the Finder shows a stored ":" as a "/" and a stored "/" as a ":", so the volume would not ' +
+            'be the one this project named. Set `gjsify.ship.name` to the display name you want.');
+    }
+    return name;
+}
+/**
+ * The exact `hdiutil` invocation, as data.
+ *
+ * Pure, so every flag is unit-testable from Linux — which is the only kind of
+ * host this project's contributors and its `e2e` job have. Same split as
+ * `renderShipFlatpakManifest`: what the tool is TOLD is checkable everywhere,
+ * what the tool DOES is checkable on the one OS that has it, and the two are not
+ * the same test.
+ *
+ * `-srcfolder` and not `-srcdevice`/`-size`: the folder's contents become the
+ * volume root, so `hdiutil` sizes the image itself. Passing a `-size` instead is
+ * how a `.dmg` build starts failing on the day the payload grows past a number
+ * somebody typed once.
+ */
+export function hdiutilCreateArgs(input) {
+    return [
+        'create',
+        // Read-only + zlib. See the header: the alternatives are decodable only
+        // by a newer 7-Zip than the reader leg has.
+        '-format',
+        'UDZO',
+        // HFS+ EXPLICITLY, because the default is the thing the reader chain
+        // cannot read. See the header.
+        '-fs',
+        'HFS+J',
+        '-volname',
+        input.volumeName,
+        '-srcfolder',
+        input.sourceDir,
+        // hdiutil REFUSES an existing target rather than replacing it, and
+        // `packOne` writes into `out/` which a previous run may have filled. The
+        // failure without this is a pack that dies on its second invocation only.
+        '-ov',
+        // Progress on a TTY is a spinner; in a CI log it is thousands of lines.
+        '-quiet',
+        input.target,
+    ];
+}
+/**
+ * Build the image at `input.target`.
+ *
+ * Unlike the Flatpak packer's tool, this one cannot be installed where it is
+ * missing: `hdiutil` ships with macOS and exists nowhere else. So the `notFound` branch does not say "install
+ * it"; it says which host this belongs on and how the payload gets there, which
+ * is the same two-phase sentence `assertHostCanFinish` prints one step earlier.
+ * Reaching this branch at all means `process.platform` said darwin and `hdiutil`
+ * was still absent, so the honest advice is "this macOS installation is broken",
+ * not a package name.
+ */
+export async function buildDmgImage(input) {
+    const args = hdiutilCreateArgs(input);
+    if (input.verbose)
+        console.log(`[gjsify ship] ${DMG_TOOL} ${args.join(' ')}`);
+    // `completion: 'return'`, matching the Flatpak packer: `ship` packs the
+    // remaining formats and prints the artifact list afterwards, so it cannot end
+    // in `process.exit()`. Under GJS that selects the blocking path, which
+    // captures the child's output and re-emits it — the documented cost of a
+    // spawn a caller has to return from (`utils/spawn.ts`), and why `--verbose`
+    // prints the invocation before the silence starts.
+    const result = await spawnToCompletion(DMG_TOOL, args, {
+        completion: 'return',
+        cwd: input.workDir,
+        stdio: 'inherit',
+        notFound: () => new Error(`gjsify ship: ${DMG_TOOL} is not on PATH. It ships with macOS and cannot be installed ` +
+            'anywhere else, so this is either a broken macOS installation or a host that is not ' +
+            'macOS at all. A `.dmg` is packed on darwin (ADR 0024 § A1); from anywhere else the ' +
+            'route is `gjsify ship darwin --stage` here and `gjsify ship --from-stage <dir> ' +
+            '--target macos-app-dmg` there.'),
+    });
+    if (result.code !== 0) {
+        throw new Error(`gjsify ship: ${DMG_TOOL} failed with ${describeExit(result)}.`);
+    }
+}
+/**
+ * Where the volume is assembled before `hdiutil` turns it into an image.
+ *
+ * A directory of its own under the run's output root, never `out/` itself: the
+ * volume root holds the `.app` and NOTHING ELSE, because `-srcfolder` copies
+ * whatever it finds — a stray sibling would ride into the image, and the reader
+ * that would catch it is the same listing comparison that would then have to be
+ * relaxed to allow it.
+ */
+export function dmgVolumeDir(outRoot) {
+    return join(outRoot, 'dmg', 'volume');
+}

package/lib/utils/ship/flatpak-config.d.ts

@@ -0,0 +1,66 @@
+import type { ConfigDataFlatpak, ConfigDataShip, ShipFlatpakOptions } from '../../types/config-data.js';
+import type { ShipFlatpakSettings } from './types.js';
+/**
+ * The release that stops reading `gjsify.flatpak` for the keys below.
+ *
+ * A major, not the next minor: the block is in published releases and in
+ * downstream `package.json`s that this repository does not control, and a
+ * window measured in weeks is a window nobody notices before it closes.
+ */
+export declare const LEGACY_FLATPAK_KEYS_REMOVED_IN = "1.0.0";
+/** The keys whose new home is `gjsify.ship.flatpak`, in the order the warning lists them. */
+export declare const MIGRATED_FLATPAK_KEYS: readonly ["runtime", "runtimeVersion", "sdkExtensions", "appendPath", "finishArgs", "cleanup"];
+export type MigratedFlatpakKey = (typeof MIGRATED_FLATPAK_KEYS)[number];
+/** The six keys as a reader sees them, before any default is applied. */
+export type MigratedFlatpakValues = {
+    [K in MigratedFlatpakKey]: ConfigDataFlatpak[K];
+};
+export interface PickedFlatpakBuildKeys {
+    values: MigratedFlatpakValues;
+    /** Keys that came from `gjsify.flatpak`, in {@link MIGRATED_FLATPAK_KEYS} order. */
+    fromLegacy: MigratedFlatpakKey[];
+}
+/**
+ * `gjsify.ship.flatpak.<key>` when set, else `gjsify.flatpak.<key>` — per KEY,
+ * noting which side answered.
+ *
+ * Per-key and not per-block: a project migrating one key at a time must not
+ * lose the five it has not moved yet. That is also what makes the warning
+ * actionable — it names the keys still coming from the old block, so the reader
+ * knows what to edit rather than being told a block is deprecated.
+ *
+ * A LOOP over {@link MIGRATED_FLATPAK_KEYS}, not six hand-written picks. Written
+ * out, the list was the one unbound copy of this vocabulary: a key added to it
+ * with no `pick` call behind it compiled fine, went missing from the window, and
+ * the only test that mentioned the constant compared it to a literal copy of
+ * itself. Reading the keys off the constant is what makes "this list IS the
+ * window" true rather than asserted.
+ *
+ * NO default is applied here. The defaults differ per reader — `ship` derives
+ * `finishArgs` from `kind`, `flatpak init` also merges `--sdk-extension` flags —
+ * and a default applied here would be a third answer neither of them chose.
+ */
+export declare function pickFlatpakBuildKeys(preferred: ShipFlatpakOptions | undefined, legacy: ConfigDataFlatpak): PickedFlatpakBuildKeys;
+/** The branch a `ship` Flatpak is exported under when the project names none. */
+export declare const DEFAULT_SHIP_FLATPAK_BRANCH = "stable";
+export interface ShipFlatpakInput {
+    ship: ConfigDataShip;
+    flatpak: ConfigDataFlatpak;
+    /** Decides the finish-args default: a GUI app needs a display, a CLI does not. */
+    kind: 'app' | 'cli';
+}
+export interface ResolvedShipFlatpak {
+    settings: ShipFlatpakSettings;
+    warnings: string[];
+}
+/**
+ * Resolve the Flatpak half of `gjsify.ship`, reading the legacy block where the
+ * new one is silent, and applying `ship`'s own defaults.
+ *
+ * The per-key fallback itself is {@link pickFlatpakBuildKeys}, shared with
+ * `gjsify flatpak init`/`ci`; what is `ship`-specific and stays here is the
+ * defaulting — `branch`, the `kind`-dependent finish-args, the derived
+ * `appendPath` — plus the warning, which only `ship` prints because only `ship`
+ * has somewhere else to point at.
+ */
+export declare function resolveShipFlatpakSettings(input: ShipFlatpakInput): ResolvedShipFlatpak;