@gjsify/cli 0.44.0 → 0.46.0

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

@@ -14,7 +14,32 @@ import type { DistroFormatId } 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";
+/**
+ * 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,6 +54,29 @@ 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}. */
@@ -40,6 +88,8 @@ 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.

package/lib/utils/ship/depends.js

@@ -35,6 +35,70 @@
  * 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.
  *
@@ -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

@@ -8,6 +8,30 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 import { LICENSE_FILE_NAMES } from './settings.js';
 const ICON_EXTENSIONS = ['.svg', '.png'];
+/**
+ * The face formats every FreeType opens, with no build option deciding it.
+ *
+ * TrueType, OpenType and their collections. Deliberately short: the point of the
+ * set is that a file in it resolves inside the app's OWN runtime closure as well
+ * as it does on the machine that packaged it.
+ */
+const FONT_EXTENSIONS = ['.ttf', '.otf', '.ttc', '.otc'];
+/**
+ * Web-font wrappers, refused BY NAME rather than filtered away.
+ *
+ * They are the mistake worth a diagnostic. An `OFL.txt` beside the faces is
+ * ignored the way a stray file in an icon directory is; a `.woff2` is a font
+ * somebody put there on purpose, and dropping it silently costs the same as
+ * staging it — the app ships without the family and Pango substitutes, at exit 0.
+ *
+ * Measured in BOTH directions, which is why this is a refusal rather than a
+ * warning: `fc-query` reads a `.woff2`'s family fine on Fedora 44 (fontconfig
+ * 2.17.0, FreeType built with brotli), and that support is
+ * `FT_CONFIG_OPTION_USE_BROTLI` — a property of whichever FreeType the shipped
+ * artifact loads, which for a `.app` or a Windows program directory is the one
+ * inside `@gjsify/gtk-runtime-<target>` and not this host's.
+ */
+const WEB_FONT_EXTENSIONS = ['.woff', '.woff2', '.eot'];
 export function discoverPayload(input) {
     const { projectDir, ship } = input;
     const bundlePath = resolveBundle(input);
@@ -29,6 +53,7 @@ export function discoverPayload(input) {
         schemaFiles: discoverSchemas(projectDir, ship.schemas),
         typelibFiles: discoverTypelibs(projectDir, ship.bundledTypelibs),
         localeFiles,
+        fontFiles: discoverFonts(projectDir, ship.fonts),
         licenseFile: discoverLicense(projectDir, ship.licenseFile),
     };
 }
@@ -52,7 +77,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));
         }
     }
@@ -169,6 +211,66 @@ function listIcons(dir) {
         .map((rel) => join(dir, rel.split('/').join(sep)))
         .sort();
 }
+/**
+ * Font faces the application SHIPS (`gjsify.ship.fonts`), or the GNOME-shaped
+ * default `data/fonts` when it exists.
+ *
+ * A FILE or a DIRECTORY, like `icon`, and a directory is walked rather than
+ * globbed because a family arrives as several faces and often with its licence
+ * beside them.
+ *
+ * The refusals are the interesting half, and both cover the same failure: a font
+ * that installs and is never found. Pango does not report a missing family — it
+ * substitutes, so the app renders in the wrong typeface with no error, no exit
+ * code and nothing for CI to see. That is why a configured path holding no usable
+ * face fails here rather than staging an empty directory, and why a web-font
+ * wrapper is named rather than filtered (see {@link WEB_FONT_EXTENSIONS}).
+ */
+function discoverFonts(projectDir, configured) {
+    const declared = configured ?? 'data/fonts';
+    const root = configured === undefined ? join(projectDir, 'data', 'fonts') : resolve(projectDir, configured);
+    if (!existsSync(root)) {
+        if (configured === undefined)
+            return [];
+        throw new Error(`gjsify ship: the configured font path ${configured} does not exist.`);
+    }
+    if (!statSync(root).isDirectory()) {
+        assertNotWebFont(root, declared);
+        if (!FONT_EXTENSIONS.some((ext) => root.toLowerCase().endsWith(ext))) {
+            throw new Error(`gjsify ship: \`gjsify.ship.fonts\` names ${configured}, which is not a font face ` +
+                `fontconfig will open (${FONT_EXTENSIONS.join(', ')}). ` +
+                'A file it cannot read installs and is never found, and Pango substitutes a fallback ' +
+                'family rather than reporting anything.');
+        }
+        return [root];
+    }
+    const out = [];
+    for (const rel of listFilesRecursive(root)) {
+        assertNotWebFont(rel, declared);
+        if (FONT_EXTENSIONS.some((ext) => rel.toLowerCase().endsWith(ext))) {
+            out.push(join(root, rel.split('/').join(sep)));
+        }
+    }
+    if (out.length === 0 && configured !== undefined) {
+        throw new Error(`gjsify ship: \`gjsify.ship.fonts\` (${configured}) holds no font face ` +
+            `(${FONT_EXTENSIONS.join(', ')}). Declaring fonts that ship nothing is a promise the ` +
+            'package does not keep — and its symptom is a substituted family, not an error.');
+    }
+    return out.sort();
+}
+/** A `.woff`/`.woff2`/`.eot` is named, never dropped — {@link WEB_FONT_EXTENSIONS} carries the reason. */
+function assertNotWebFont(path, where) {
+    const lower = path.toLowerCase();
+    const wrapper = WEB_FONT_EXTENSIONS.find((ext) => lower.endsWith(ext));
+    if (wrapper === undefined)
+        return;
+    throw new Error(`gjsify ship: \`gjsify.ship.fonts\` (${where}) carries ${path}, and \`${wrapper}\` is a web-font ` +
+        'wrapper whose support is a FreeType BUILD option — brotli for woff2, zlib for woff. Whether it ' +
+        'opens is therefore a property of the FreeType the SHIPPED artifact loads (inside ' +
+        '`@gjsify/gtk-runtime-<target>` for a `.app` or a Windows program directory), not of the machine ' +
+        `that packaged it. Ship the desktop face instead (${FONT_EXTENSIONS.join(', ')}); a font that ` +
+        'fails to open is not an error, it is Pango quietly substituting a different typeface.');
+}
 function discoverSchemas(projectDir, configured) {
     const roots = configured !== undefined ? [resolve(projectDir, configured)] : [join(projectDir, 'data')];
     for (const root of roots) {

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.js

@@ -143,6 +143,6 @@ async function run(cmd, args, input, notFoundHint) {
         notFound: () => new Error(`gjsify ship: ${notFoundHint}`),
     });
     if (result.code !== 0) {
-        throw new Error(`gjsify ship: ${cmd} failed${describeExit(result)}.`);
+        throw new Error(`gjsify ship: ${cmd} failed with ${describeExit(result)}.`);
     }
 }