@gjsify/cli 0.44.0 → 0.45.0

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.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)}.`);
     }
 }

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

@@ -1,9 +1,40 @@
-import type { FormatDescriptor, FormatId } from './types.js';
+import { type Layout } from './layout.js';
+import type { FormatDescriptor, FormatId, HostOs, PackSettings, RequiredTools } from './types.js';
+/**
+ * The directory `windows-dir` produces, and the top level `windows-dir-zip` puts
+ * its entries under.
+ *
+ * ONE function with TWO readers, deliberately: the zip has to expand to the same
+ * directory the other row writes, and two literals would be two names a user is
+ * asked to believe are one.
+ */
+export declare function windowsProgramDirName(settings: PackSettings): string;
+/**
+ * The tools ONE host needs for a format, whichever shape the row declares.
+ *
+ * The one place the union in {@link RequiredTools} is opened, so a caller cannot
+ * read the map and get `undefined.filter` or read the array on a row that has a
+ * map. An OS the map does not name answers `[]` — not because nothing is needed
+ * there, but because {@link assertHostCanFinish} has already refused that host by
+ * the time this is asked, and inventing a tool list for a host that cannot finish
+ * the format would answer a question nobody may ask.
+ */
+export declare function requiredToolsOn(tools: RequiredTools, host: string): readonly string[];
+/**
+ * Every tool any host could need for a format — the question `installHint`'s
+ * presence is gated on.
+ *
+ * Deliberately NOT what {@link assertToolsInstalled} checks. "Does this row need a
+ * hint at all" is a property of the ROW; "is this tool here" is a question about
+ * one machine, and answering the first with the second would let a row declare a
+ * Windows-only tool and no hint, because the gate happened to run on Linux.
+ */
+export declare function allRequiredTools(tools: RequiredTools): readonly string[];
 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.
+ * What `gjsify ship <os>` builds when nothing said otherwise — every format that
+ * wraps THAT OS's layout and 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
@@ -14,8 +45,22 @@ export declare const FORMAT_IDS: FormatId[];
  * 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.
+ *
+ * `layoutOs` is the SECOND criterion, and it is what the layout axis needed: a
+ * `.app` and its zip and a Windows program directory are all `finishOn: 'any'`,
+ * so on the one criterion a bare `gjsify ship` on Linux would start emitting
+ * five artifacts (ADR 0024 issue #1354, open question 3). Answered with § A2's
+ * positional rather than instead of it — the positional picks the layout, this
+ * picks the formats that wrap it, and `gjsify ship` on Linux keeps emitting
+ * exactly `deb` and `rpm`.
+ *
+ * An EMPTY answer is legal and is what darwin and windows give today: their
+ * layouts assemble (`--stage`) and no format wraps them yet. `assemble` refuses
+ * a pack with nothing to pack rather than exiting 0 having produced no artifact.
  */
-export declare const DEFAULT_FORMAT_IDS: FormatId[];
+export declare function defaultFormatIds(layoutOs: HostOs): FormatId[];
+/** Every format that wraps one OS's layout, tool-bound ones included. */
+export declare function formatIdsFor(layoutOs: HostOs): FormatId[];
 /**
  * Refuse a format this host cannot finish, BEFORE anything is built or written.
  *
@@ -35,6 +80,39 @@ export declare function assertHostCanFinish(format: FormatDescriptor, host?: str
  * 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[];
+export declare function assertToolsInstalled(format: FormatDescriptor, present?: (cmd: string) => boolean, host?: string): void;
+/**
+ * Parse an explicit `--target deb,rpm` into a sorted, deduplicated descriptor list.
+ *
+ * A format belonging to another layout is an ERROR here, not a filter:
+ * `gjsify ship darwin --target deb` is a mistake worth naming, and dropping it
+ * silently would stage the darwin layout, pack nothing and exit 0 — the shape
+ * the empty-list refusal above already exists to prevent, arriving through a
+ * different door.
+ *
+ * The FLAG is what makes that the right answer, and it is the whole difference
+ * from {@link configuredFormats}: a value typed on this command line is a claim
+ * about THIS run.
+ */
+export declare function resolveFormats(raw: readonly string[], layout: Layout): FormatDescriptor[];
+/**
+ * The same names from `gjsify.ship.targets`, FILTERED to the current layout.
+ *
+ * A configured list is a project-level DEFAULT — "when I ship this, build these"
+ * — written once and read by every run, so it cannot be a claim about a layout
+ * the author had not heard of when they wrote it. Refusing it the way
+ * {@link resolveFormats} refuses a flag makes the new positional unusable in
+ * every project that has the key, and this repository is the proof: with
+ * `targets: ["deb", "rpm"]` in `packages/infra/cli/package.json`,
+ * `gjsify ship darwin --stage` exited 1 telling the author to run
+ * `gjsify ship darwin --stage`. There was no `--target` value that got a darwin
+ * stage out of such a project at all.
+ *
+ * Filtering is safe HERE and only here, because an empty result is not a silent
+ * success: `assemble` refuses a PACK with nothing to pack, and a `--stage` run
+ * legitimately wants exactly this — assemble the layout, wrap nothing.
+ */
+export declare function configuredFormats(raw: readonly string[], layout: Layout): {
+    formats: FormatDescriptor[];
+    dropped: FormatId[];
+};