@gjsify/cli 0.44.0 → 0.45.0

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

@@ -18,6 +18,13 @@ export interface StageInputs {
  * The result is deduplicated by path (last write wins, so `extraFiles` can
  * override anything the defaults staged) and sorted, which makes the tree —
  * and therefore every artifact built from it — deterministic.
+ *
+ * ONE plan, in the Linux/XDG shape, for every OS. Where those paths end up is
+ * `utils/ship/layout.ts`'s `placeStage`, applied afterwards by the caller, and
+ * keeping the two steps apart is what makes ADR 0024 § 2's "one payload, a
+ * handful of layouts" checkable: `tests/e2e/ship-layout` asserts the three
+ * staged trees agree modulo that map. A planner that took the layout would have
+ * three code paths to keep in agreement instead.
  */
 export declare function planStage(settings: ShipSettings, inputs: StageInputs): StagedFile[];
 /**
@@ -61,3 +68,17 @@ export declare function assertOverlayIsLicensed(formatId: FormatId, binaryName:
  * filename.
  */
 export declare function iconSizeDir(iconPath: string): string;
+/**
+ * A native module inside the payload has to keep its executable bit.
+ *
+ * By NAME here, unlike `isArchIndependent`, which reads the file's magic: the
+ * planner is pure and has no bytes to look at. The two answer different
+ * questions — "should this be 0755" versus "is this package portable" — and
+ * getting this one wrong costs a mode bit, not an unusable package.
+ *
+ * EXPORTED for `utils/ship/app-runtime.ts`, which stages a relocated GTK closure
+ * that never passes through this plan and needs the same answer for the same
+ * files. A second copy of the pattern there would be a second answer to "is this
+ * a shared library", and the drifted one is the one that stages a `.dylib` 0644.
+ */
+export declare function isExecutableAsset(rel: string): boolean;

package/lib/utils/ship/plan.js

@@ -3,6 +3,7 @@
 // as `utils/copy-targets.ts`, and for the same reason: a stager that discovers
 // its own inputs can only be tested by building a real project.
 import { renderMimePackage } from './mime.js';
+import { SHARE } from './share-dirs.js';
 import { basename, extname, posix } from 'node:path';
 /**
  * Build the prefix-relative payload.
@@ -10,6 +11,13 @@ import { basename, extname, posix } from 'node:path';
  * The result is deduplicated by path (last write wins, so `extraFiles` can
  * override anything the defaults staged) and sorted, which makes the tree —
  * and therefore every artifact built from it — deterministic.
+ *
+ * ONE plan, in the Linux/XDG shape, for every OS. Where those paths end up is
+ * `utils/ship/layout.ts`'s `placeStage`, applied afterwards by the caller, and
+ * keeping the two steps apart is what makes ADR 0024 § 2's "one payload, a
+ * handful of layouts" checkable: `tests/e2e/ship-layout` asserts the three
+ * staged trees agree modulo that map. A planner that took the layout would have
+ * three code paths to keep in agreement instead.
  */
 export function planStage(settings, inputs) {
     const files = [];
@@ -23,7 +31,7 @@ export function planStage(settings, inputs) {
         });
     }
     files.push({
-        path: `share/metainfo/${settings.appId}.metainfo.xml`,
+        path: `${SHARE.metainfo}/${settings.appId}.metainfo.xml`,
         mode: 0o644,
         source: { kind: 'text', text: inputs.metainfo },
     });
@@ -32,7 +40,7 @@ export function planStage(settings, inputs) {
             throw new Error('gjsify ship: internal error — a desktop entry is required for `kind: "app"`.');
         }
         files.push({
-            path: `share/applications/${settings.appId}.desktop`,
+            path: `${SHARE.applications}/${settings.appId}.desktop`,
             mode: 0o644,
             source: { kind: 'text', text: inputs.desktopEntry },
         });
@@ -50,7 +58,7 @@ export function planStage(settings, inputs) {
                 'Every installed schema shares one system directory, so the app id is what keeps it unique.');
         }
         files.push({
-            path: `share/glib-2.0/schemas/${name}`,
+            path: `${SHARE.schemas}/${name}`,
             mode: 0o644,
             source: { kind: 'file', path: schema },
         });
@@ -71,7 +79,7 @@ export function planStage(settings, inputs) {
     // reason it is for the GSettings schema: a generic name collides with another package's file.
     if (settings.mimeTypes.length > 0) {
         files.push({
-            path: `share/mime/packages/${settings.appId}.xml`,
+            path: `${SHARE.mime}/${settings.appId}.xml`,
             mode: 0o644,
             source: { kind: 'text', text: renderMimePackage(settings.mimeTypes) },
         });
@@ -80,7 +88,7 @@ export function planStage(settings, inputs) {
     // is where `bindtextdomain` looks, and nowhere else.
     for (const locale of settings.localeFiles) {
         files.push({
-            path: posix.join('share/locale', locale.rel),
+            path: posix.join(SHARE.locale, locale.rel),
             mode: 0o644,
             source: { kind: 'file', path: locale.abs },
         });
@@ -178,7 +186,7 @@ function planIcons(settings) {
     for (const icon of settings.iconFiles) {
         const ext = extname(icon);
         const dir = iconSizeDir(icon);
-        const path = `share/icons/hicolor/${dir}/apps/${settings.appId}${ext}`;
+        const path = `${SHARE.icons}/${dir}/apps/${settings.appId}${ext}`;
         const previous = seen.get(path);
         if (previous !== undefined) {
             throw new Error(`gjsify ship: ${icon} and ${previous} both install as ${path}. ` +
@@ -226,8 +234,13 @@ function assertInsidePrefix(dest) {
  * planner is pure and has no bytes to look at. The two answer different
  * questions — "should this be 0755" versus "is this package portable" — and
  * getting this one wrong costs a mode bit, not an unusable package.
+ *
+ * EXPORTED for `utils/ship/app-runtime.ts`, which stages a relocated GTK closure
+ * that never passes through this plan and needs the same answer for the same
+ * files. A second copy of the pattern there would be a second answer to "is this
+ * a shared library", and the drifted one is the one that stages a `.dylib` 0644.
  */
-function isExecutableAsset(rel) {
+export function isExecutableAsset(rel) {
     return /\.(so|node|dylib)(\.\d+)*$/.test(rel);
 }
 /** Last write wins, then sort — deterministic output for a deterministic artifact. */

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

@@ -0,0 +1,58 @@
+import type { LayoutMetadataInput } from './layout.js';
+/** Where the two files live inside a bundle. Apple's names, not ours. */
+export declare const BUNDLE_INFO_PLIST = "Contents/Info.plist";
+export declare const BUNDLE_PKGINFO = "Contents/PkgInfo";
+/**
+ * Render `Contents/Info.plist`.
+ *
+ * The eleven keys, each with the file in `refs/` it was read off (all paths
+ * relative to the repository root, all read-only submodules):
+ *
+ * | key | value | citation |
+ * |---|---|---|
+ * | `CFBundleExecutable` | `binaryName` | `refs/node/test/fixtures/macos-app-sandbox/Info.plist:5` |
+ * | `CFBundleIdentifier` | `appId` | same file, line 7 |
+ * | `CFBundleInfoDictionaryVersion` | `6.0` | same file, line 9 |
+ * | `CFBundleName` | `name` | same file, line 11 |
+ * | `CFBundlePackageType` | `APPL` | same file, line 13 |
+ * | `CFBundleShortVersionString` | `version` | same file, line 15 |
+ * | `CFBundleSupportedPlatforms` | `["MacOSX"]` | same file, lines 17-20 |
+ * | `CFBundleVersion` | `version-release` | same file, line 21 |
+ * | `CFBundleDevelopmentRegion` | `en` | `refs/node/deps/v8/gni/Info.plist:5` |
+ * | `CFBundleDisplayName` | `name` | same file, line 7 |
+ * | `CFBundleSignature` | `????` | same file, line 21 |
+ *
+ * `CFBundleVersion` carries the RELEASE and `CFBundleShortVersionString` does
+ * not, which is the one place the two differ. Apple's rule is that the short
+ * string is the marketing version a user sees and `CFBundleVersion` is the build
+ * — and this command already has that exact pair: `version` is upstream's,
+ * `release` is the packaging revision within it (the deb revision, the rpm
+ * release). Emitting `version` twice would throw the distinction away on the one
+ * OS that has a field for it.
+ *
+ * KEYS DELIBERATELY ABSENT are listed in this module's header. `CFBundleIconFile`
+ * is the one a reader will reach for first, and it is absent for a reason that
+ * outlives the key: M2a ships NO icon. `png2icns`, `icnsutil` and `iconutil` are
+ * all absent from this workstation and from the CI image, so an `.icns` written
+ * here could only be read back by a reader written here — `selfReading: true`,
+ * which `flatpak.spec.ts` reds. The unblocker is an independent Linux ICNS reader
+ * entering the CI image; until one does, the hicolor PNG/SVG the payload already
+ * carries stays the only icon, unread on macOS.
+ */
+export declare function renderInfoPlist(input: LayoutMetadataInput): string;
+/**
+ * Render `Contents/PkgInfo`: the package type and the signature, eight bytes, no
+ * newline.
+ *
+ * `refs/node/tools/gyp/pylib/gyp/mac_tool.py:236-245` is the whole
+ * specification — "eight characters, representing the bundle type and bundle
+ * signature, each four characters" — and its
+ * `fp.write(f"{package_type}{signature_code}")` writes no terminator. A trailing
+ * newline would make the file nine bytes, which is the kind of difference
+ * nothing complains about and every byte comparison notices.
+ *
+ * Redundant with `Info.plist` by design: it is the pre-plist Carbon record that
+ * LaunchServices still reads, and gyp writes both from one source for exactly
+ * the same reason this function takes none — both values are constants here.
+ */
+export declare function renderPkgInfo(): string;

package/lib/utils/ship/plist.js

@@ -0,0 +1,198 @@
+// `Contents/Info.plist` and `Contents/PkgInfo` — what makes a `*.app` directory
+// an application BUNDLE rather than a directory whose name ends in `.app`.
+//
+// M1 staged `<Name>.app/Contents/{MacOS,Resources}` with no `Info.plist` at all.
+// LaunchServices reads that file to learn which file under `Contents/MacOS` to
+// exec and what identity to register the bundle under, so without it the tree is
+// a directory the Finder shows as a folder — the hole #1354 M2a closes.
+//
+// XML, never the binary variant, and that is an ORACLE decision rather than a
+// taste one. `plistlib` reads both, but a binary plist this tree wrote and then
+// read back with a reader this tree also wrote is `selfReading: true` — ADR 0024
+// § A3 calls that legal to declare and illegal to release. CPython's `plistlib`
+// is a different implementation family and is already precedent here
+// (`.github/ship-oracle/verify-modes.py`), and it parses the XML form.
+//
+// EVERY KEY BELOW IS CITED to a file in `refs/` that a real macOS toolchain
+// produced or consumes. Keys that are merely plausible — `CFBundleIconFile`,
+// `LSMinimumSystemVersion`, `NSHighResolutionCapable`, `LSApplicationCategoryType`,
+// `NSHumanReadableCopyright` — are not emitted, because nothing a reader here can
+// open contains them.
+//
+// AND THE SCOPE OF THAT MEASUREMENT IS PART OF IT, because `grep -r … refs/` is a
+// command that answers cheerfully after reading almost nothing: 89 of the 95
+// submodules `.gitmodules` declares are not checked out in a working tree, and an
+// empty directory produces zero hits with no error. Measured on a checkout with
+// SIX of them present (`cambalache`, `gtkx`, `libadwaita`, `metro`, `node`,
+// `peachy`): 0 files for each of the five keys above, against 3 files for
+// `CFBundleSignature` as the CONTROL — a string known to be there, which is what
+// makes the zeros mean anything. So the claim is "absent from the six pools a
+// reader can open", not "absent from the pool", and a key that turns up in a
+// seventh is a citation waiting to be written, not a contradiction.
+/** Where the two files live inside a bundle. Apple's names, not ours. */
+export const BUNDLE_INFO_PLIST = 'Contents/Info.plist';
+export const BUNDLE_PKGINFO = 'Contents/PkgInfo';
+/**
+ * The four-character bundle type of an application, and the signature that says
+ * "none".
+ *
+ * `refs/node/tools/gyp/pylib/gyp/mac_tool.py:232` reads `CFBundlePackageType` and
+ * writes a `PkgInfo` only when it is `APPL`; line 239 defaults
+ * `CFBundleSignature` to `????` and line 240 resets a signature of the wrong
+ * length to the same four question marks. `refs/node/deps/v8/gni/Info.plist:22`
+ * spells `????` out.
+ */
+const PACKAGE_TYPE = 'APPL';
+const SIGNATURE = '????';
+/**
+ * The one XML escape set a plist needs.
+ *
+ * `&` first, or the ampersands introduced by the later replacements get escaped
+ * twice and `CFBundleName` comes out as `Ship &amp;amp; Co`. `<` and `>` are the
+ * element delimiters; `"` and `'` are not special in element CONTENT, which is
+ * the only place this function's output ever lands, so they are left alone
+ * rather than turned into entities a human reading the file has to decode.
+ */
+function xmlText(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/**
+ * Refuse a value a plist cannot carry, naming the field.
+ *
+ * XML 1.0 has no escape for most C0 control characters — they are not
+ * representable in a document at all, not merely inconvenient — so a name
+ * carrying one produces a file `plistlib` and `CFPropertyList` both reject. The
+ * refusal is here rather than at parse time on a Mac three milestones away.
+ *
+ * C0 MINUS TAB/LF/CR, AND NOTHING ELSE — measured against the oracle rather than
+ * reasoned from the spec, because the first cut of this guard also refused DEL
+ * and the C1 range on the stated grounds that XML forbids them, and XML 1.0 does
+ * not. Probed through `plistlib` on CPython 3.14, one code point per document:
+ *
+ *     U+0001, U+0008, U+000B   ExpatError: not well-formed (invalid token)
+ *     U+0009 (TAB)             accepted
+ *     U+007F (DEL)             accepted
+ *     U+0085, U+009F (C1)      accepted
+ *
+ * So refusing those four would reject a name every reader in the chain reads
+ * back correctly — a guard that turns working packages into failures, which buys
+ * nothing over the defect it prevents. The rule that survives is the measured
+ * one; the reason that did not is recorded here rather than quietly dropped,
+ * because a rule carrying an invented reason is one that gets "simplified" back
+ * into the bug.
+ */
+function assertPlistText(value, field, configKey) {
+    // A SCAN rather than a character class, and not only to keep `no-control-regex`
+    // quiet: the code point is what the message needs, and lifting it back out of
+    // a match is a second step that can disagree with the first.
+    let point = -1;
+    for (const char of value) {
+        const code = char.codePointAt(0) ?? 0;
+        // Tab, LF and CR are the three C0 code points XML 1.0 does carry.
+        if (code < 0x20 && code !== 0x09 && code !== 0x0a && code !== 0x0d) {
+            point = code;
+            break;
+        }
+    }
+    if (point !== -1) {
+        throw new Error(`gjsify ship: ${field} would carry the control character ` +
+            `U+${point.toString(16).padStart(4, '0').toUpperCase()}, and XML has no escape for it — the ` +
+            'Info.plist would be unparseable by every reader macOS has. Set ' +
+            `\`${configKey}\` to a value without it.`);
+    }
+    return value;
+}
+/** One `<key>…</key><string>…</string>` pair, indented to sit inside the top-level `<dict>`. */
+function stringEntry(key, value) {
+    return `\t<key>${key}</key>\n\t<string>${xmlText(value)}</string>`;
+}
+/** `CFBundleSupportedPlatforms` is the one array here — see the key table below. */
+function arrayEntry(key, values) {
+    const items = values.map((value) => `\t\t<string>${xmlText(value)}</string>`).join('\n');
+    return `\t<key>${key}</key>\n\t<array>\n${items}\n\t</array>`;
+}
+/**
+ * Render `Contents/Info.plist`.
+ *
+ * The eleven keys, each with the file in `refs/` it was read off (all paths
+ * relative to the repository root, all read-only submodules):
+ *
+ * | key | value | citation |
+ * |---|---|---|
+ * | `CFBundleExecutable` | `binaryName` | `refs/node/test/fixtures/macos-app-sandbox/Info.plist:5` |
+ * | `CFBundleIdentifier` | `appId` | same file, line 7 |
+ * | `CFBundleInfoDictionaryVersion` | `6.0` | same file, line 9 |
+ * | `CFBundleName` | `name` | same file, line 11 |
+ * | `CFBundlePackageType` | `APPL` | same file, line 13 |
+ * | `CFBundleShortVersionString` | `version` | same file, line 15 |
+ * | `CFBundleSupportedPlatforms` | `["MacOSX"]` | same file, lines 17-20 |
+ * | `CFBundleVersion` | `version-release` | same file, line 21 |
+ * | `CFBundleDevelopmentRegion` | `en` | `refs/node/deps/v8/gni/Info.plist:5` |
+ * | `CFBundleDisplayName` | `name` | same file, line 7 |
+ * | `CFBundleSignature` | `????` | same file, line 21 |
+ *
+ * `CFBundleVersion` carries the RELEASE and `CFBundleShortVersionString` does
+ * not, which is the one place the two differ. Apple's rule is that the short
+ * string is the marketing version a user sees and `CFBundleVersion` is the build
+ * — and this command already has that exact pair: `version` is upstream's,
+ * `release` is the packaging revision within it (the deb revision, the rpm
+ * release). Emitting `version` twice would throw the distinction away on the one
+ * OS that has a field for it.
+ *
+ * KEYS DELIBERATELY ABSENT are listed in this module's header. `CFBundleIconFile`
+ * is the one a reader will reach for first, and it is absent for a reason that
+ * outlives the key: M2a ships NO icon. `png2icns`, `icnsutil` and `iconutil` are
+ * all absent from this workstation and from the CI image, so an `.icns` written
+ * here could only be read back by a reader written here — `selfReading: true`,
+ * which `flatpak.spec.ts` reds. The unblocker is an independent Linux ICNS reader
+ * entering the CI image; until one does, the hicolor PNG/SVG the payload already
+ * carries stays the only icon, unread on macOS.
+ */
+export function renderInfoPlist(input) {
+    const name = assertPlistText(input.name, 'CFBundleName', 'gjsify.ship.name');
+    const executable = assertPlistText(input.binaryName, 'CFBundleExecutable', 'gjsify.ship.binaryName');
+    const appId = assertPlistText(input.appId, 'CFBundleIdentifier', 'gjsify.ship.appId');
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        '<dict>',
+        // Alphabetical, because both cited files are: `macos-app-sandbox/Info.plist`
+        // runs Executable → Identifier → InfoDictionaryVersion → Name → PackageType
+        // → ShortVersionString → SupportedPlatforms → Version, and `v8/gni`'s
+        // CFBundle keys sort the same way. Matching them keeps a diff against a
+        // real bundle readable; no claim is made about what Xcode emits.
+        stringEntry('CFBundleDevelopmentRegion', 'en'),
+        stringEntry('CFBundleDisplayName', name),
+        stringEntry('CFBundleExecutable', executable),
+        stringEntry('CFBundleIdentifier', appId),
+        stringEntry('CFBundleInfoDictionaryVersion', '6.0'),
+        stringEntry('CFBundleName', name),
+        stringEntry('CFBundlePackageType', PACKAGE_TYPE),
+        stringEntry('CFBundleShortVersionString', input.version),
+        stringEntry('CFBundleSignature', SIGNATURE),
+        arrayEntry('CFBundleSupportedPlatforms', ['MacOSX']),
+        stringEntry('CFBundleVersion', `${input.version}-${input.release}`),
+        '</dict>',
+        '</plist>',
+        '',
+    ].join('\n');
+}
+/**
+ * Render `Contents/PkgInfo`: the package type and the signature, eight bytes, no
+ * newline.
+ *
+ * `refs/node/tools/gyp/pylib/gyp/mac_tool.py:236-245` is the whole
+ * specification — "eight characters, representing the bundle type and bundle
+ * signature, each four characters" — and its
+ * `fp.write(f"{package_type}{signature_code}")` writes no terminator. A trailing
+ * newline would make the file nine bytes, which is the kind of difference
+ * nothing complains about and every byte comparison notices.
+ *
+ * Redundant with `Info.plist` by design: it is the pre-plist Carbon record that
+ * LaunchServices still reads, and gyp writes both from one source for exactly
+ * the same reason this function takes none — both values are constants here.
+ */
+export function renderPkgInfo() {
+    return `${PACKAGE_TYPE}${SIGNATURE}`;
+}

package/lib/utils/ship/rpm.js

@@ -19,6 +19,7 @@ import { readPayloadFacts, readShebangInterpreters } from './payload.js';
 import { buildRpmHeader, buildRpmLead, padToEight, RpmType, RPM_TAG_HEADERIMMUTABLE, RPM_TAG_HEADERSIGNATURES, } from './rpm-header.js';
 import { gzipDeterministic } from './gzip.js';
 import { renderRpmScriptlets } from './scripts.js';
+import { SHARE } from './share-dirs.js';
 // Header tags. Named rather than inlined because a wrong NUMBER produces a
 // package that parses and is quietly wrong, which is the hardest kind to spot.
 const TAG = {
@@ -115,6 +116,11 @@ const RPMLIB_REQUIRES = [
  * rpmlint noise, not a broken install. The entries that matter are the ones a
  * package would otherwise claim on every install.
  */
+// The three that name a directory `plan.ts` actually stages into are DERIVED, so
+// they cannot drift from it. The rest stay literal on purpose: they are PARENTS
+// (`/usr/share/icons`, `/usr/share/glib-2.0`) or directories this packer never
+// writes (`/etc`, `/opt`, `/var`, `/usr/share/man`), which is a different question
+// from "where does the payload install" and would be wrong to fold into one list.
 const SYSTEM_OWNED_DIRECTORIES = new Set([
     '/usr',
     '/usr/bin',
@@ -123,16 +129,16 @@ const SYSTEM_OWNED_DIRECTORIES = new Set([
     '/usr/libexec',
     '/usr/sbin',
     '/usr/share',
-    '/usr/share/applications',
+    `/usr/${SHARE.applications}`,
     '/usr/share/doc',
     '/usr/share/icons',
     '/usr/share/licenses',
     '/usr/share/man',
-    '/usr/share/metainfo',
+    `/usr/${SHARE.metainfo}`,
     // Owned by glib2 — an app that installs a schema must not claim the
     // directory the whole system's schemas live in. Verified with `rpm -qf`.
     '/usr/share/glib-2.0',
-    '/usr/share/glib-2.0/schemas',
+    `/usr/${SHARE.schemas}`,
     '/etc',
     '/opt',
     '/var',

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

@@ -0,0 +1,61 @@
+import type { StagedFile } from './types.js';
+/** The one spelling of the tool, read by this module AND by the format rows. */
+export declare const SCHEMA_COMPILER = "glib-compile-schemas";
+/**
+ * How to install it, in the two distributions' words.
+ *
+ * The same two package names `depends.ts`'s `SCHEMA_COMPILER_PACKAGE` emits into
+ * a `Depends:`/`Requires:`, so the advice a user gets here and the dependency a
+ * `.deb` declares cannot name different packages.
+ */
+export declare const SCHEMA_COMPILER_HINT = "Fedora: `sudo dnf install glib2`, Debian/Ubuntu: `sudo apt install libglib2.0-bin`";
+/** The compiled cache's prefix-relative path — one definition, several readers. */
+export declare const SCHEMA_CACHE: string;
+export interface CompileSchemasInput {
+    /** Absolute paths of the project's `*.gschema.xml` files. */
+    schemaFiles: readonly string[];
+    /** A scratch directory this function owns; wiped and rewritten on every run. */
+    workDir: string;
+}
+/**
+ * Compile the payload's schemas and return the cache as ONE prefix-relative
+ * planned file, or nothing when the payload has no schema.
+ *
+ * PREFIX-RELATIVE, so `place()` maps it into `Contents/Resources/share/…` or a
+ * Windows `share\` with no rule of its own. That is the whole reason this returns
+ * a `StagedFile` rather than writing into the stage directly: the layout map stays
+ * the single place that knows where `share/` goes, and the e2e's hand-written map
+ * needs no new entry to cover it.
+ *
+ * `--strict` IS LOAD-BEARING and was measured, not assumed. Against a schema whose
+ * `path` attribute lacks its leading slash, on glib 2.88.3 — the observable is the
+ * exit code and the file, not the wording, because the diagnostic is translated
+ * and was read here in German:
+ *
+ *     glib-compile-schemas in --targetdir out            → exit 0, warns that the
+ *                                                          whole file was ignored,
+ *                                                          gschemas.compiled WRITTEN
+ *     glib-compile-schemas in --targetdir out --strict   → exit 1, nothing written
+ *
+ * Without the flag a broken schema is skipped at exit 0 and a cache is produced
+ * that simply does not contain it — so the stage looks compiled, the warning goes
+ * away, and `g_settings_new()` still aborts on the schema that was dropped. That
+ * is a green that checked nothing, produced by the step meant to close the hole.
+ *
+ * A DIRECTORY, because that is the only input the tool takes: the schemas are
+ * copied into `workDir` under their own basenames first. `plan.ts` has already
+ * refused any basename not prefixed with the app id, so two schemas cannot
+ * collide here.
+ *
+ * ENDIANNESS, stated rather than assumed away. The output is GVDB, and the file
+ * this tree produces is HOST-endian — measured on x86-64 with glib 2.88.3: in a
+ * 256-byte `gschemas.compiled` compiled from one schema with one key, the eight
+ * bytes at offset 16 read `18 00 00 00 58 00 00 00`, i.e. the pointer pair 24 and
+ * 88 stored little-endian. Whether GLib's reader byte-swaps a foreign-endian
+ * cache is UNVERIFIED here — nothing in this tree tested it and nothing below
+ * assumes an answer. It does not bite today: both darwin targets (x64, arm64) and
+ * every runner in this project's CI are little-endian, so no cache yet crosses
+ * that boundary. A big-endian assembling host is the case to measure before
+ * anyone claims otherwise.
+ */
+export declare function compileSchemasForStage(input: CompileSchemasInput): Promise<StagedFile[]>;

package/lib/utils/ship/schemas.js

@@ -0,0 +1,118 @@
+// Compiling `gschemas.compiled` into a stage that has no install step.
+//
+// THE DEFECT THIS CLOSES is not cosmetic and `payload.ts` already named it:
+// every launcher form exports `XDG_DATA_DIRS` at the staged `share/`, and
+// GSettings ABORTS on a schema directory holding a `.gschema.xml` with no
+// `gschemas.compiled` beside it. On Linux the `.deb`/`.rpm` postinst runs
+// `glib-compile-schemas` at install (`scripts.ts`); a `.app` has no postinst and
+// nothing else was going to run it. So `gjsify ship darwin --stage` produced a
+// bundle whose first `Gio.Settings.new()` kills the process — an artifact that
+// installs and does not start, which is the class this whole command exists
+// against.
+//
+// AT STAGE TIME, not at pack time, and that is the decision worth stating.
+// A stage is a deliverable in its own right — it is what crosses to the host
+// that finishes a `.dmg` or an `.msi` — and the warning `gjsify ship` prints
+// about it is a claim about the TREE. Leaving the compile to a packer would keep
+// `--stage` producing an aborting bundle while the message said otherwise.
+//
+// The cost is that assembly now execs one tool for a non-Linux layout with
+// schemas in the payload. That does not make assembly host-BOUND (ADR 0024 § A1):
+// `glib-compile-schemas` is GLib's and runs on all three OSes, which is why the
+// four rows that ASSEMBLE a non-Linux tree — the `.app`, its zip, the Windows
+// program directory and its zip — stay `finishOn: 'any'` and declare the tool
+// through `requiredTools` instead. The `.dmg` and the `.msi` deliberately do not
+// declare it: they wrap a tree that is already assembled, so a `--from-stage`
+// pack of one needs no GLib at all (the `macos-app-dmg` row says so).
+import { execFile } from 'node:child_process';
+import { basename, join } from 'node:path';
+import { copyFileSync, mkdirSync, rmSync } from 'node:fs';
+import { promisify } from 'node:util';
+import { SHARE } from './share-dirs.js';
+const execFileAsync = promisify(execFile);
+/** The one spelling of the tool, read by this module AND by the format rows. */
+export const SCHEMA_COMPILER = 'glib-compile-schemas';
+/**
+ * How to install it, in the two distributions' words.
+ *
+ * The same two package names `depends.ts`'s `SCHEMA_COMPILER_PACKAGE` emits into
+ * a `Depends:`/`Requires:`, so the advice a user gets here and the dependency a
+ * `.deb` declares cannot name different packages.
+ */
+export const SCHEMA_COMPILER_HINT = 'Fedora: `sudo dnf install glib2`, Debian/Ubuntu: `sudo apt install libglib2.0-bin`';
+/** The compiled cache's prefix-relative path — one definition, several readers. */
+export const SCHEMA_CACHE = `${SHARE.schemas}/gschemas.compiled`;
+/**
+ * Compile the payload's schemas and return the cache as ONE prefix-relative
+ * planned file, or nothing when the payload has no schema.
+ *
+ * PREFIX-RELATIVE, so `place()` maps it into `Contents/Resources/share/…` or a
+ * Windows `share\` with no rule of its own. That is the whole reason this returns
+ * a `StagedFile` rather than writing into the stage directly: the layout map stays
+ * the single place that knows where `share/` goes, and the e2e's hand-written map
+ * needs no new entry to cover it.
+ *
+ * `--strict` IS LOAD-BEARING and was measured, not assumed. Against a schema whose
+ * `path` attribute lacks its leading slash, on glib 2.88.3 — the observable is the
+ * exit code and the file, not the wording, because the diagnostic is translated
+ * and was read here in German:
+ *
+ *     glib-compile-schemas in --targetdir out            → exit 0, warns that the
+ *                                                          whole file was ignored,
+ *                                                          gschemas.compiled WRITTEN
+ *     glib-compile-schemas in --targetdir out --strict   → exit 1, nothing written
+ *
+ * Without the flag a broken schema is skipped at exit 0 and a cache is produced
+ * that simply does not contain it — so the stage looks compiled, the warning goes
+ * away, and `g_settings_new()` still aborts on the schema that was dropped. That
+ * is a green that checked nothing, produced by the step meant to close the hole.
+ *
+ * A DIRECTORY, because that is the only input the tool takes: the schemas are
+ * copied into `workDir` under their own basenames first. `plan.ts` has already
+ * refused any basename not prefixed with the app id, so two schemas cannot
+ * collide here.
+ *
+ * ENDIANNESS, stated rather than assumed away. The output is GVDB, and the file
+ * this tree produces is HOST-endian — measured on x86-64 with glib 2.88.3: in a
+ * 256-byte `gschemas.compiled` compiled from one schema with one key, the eight
+ * bytes at offset 16 read `18 00 00 00 58 00 00 00`, i.e. the pointer pair 24 and
+ * 88 stored little-endian. Whether GLib's reader byte-swaps a foreign-endian
+ * cache is UNVERIFIED here — nothing in this tree tested it and nothing below
+ * assumes an answer. It does not bite today: both darwin targets (x64, arm64) and
+ * every runner in this project's CI are little-endian, so no cache yet crosses
+ * that boundary. A big-endian assembling host is the case to measure before
+ * anyone claims otherwise.
+ */
+export async function compileSchemasForStage(input) {
+    if (input.schemaFiles.length === 0)
+        return [];
+    rmSync(input.workDir, { recursive: true, force: true, maxRetries: 5 });
+    mkdirSync(input.workDir, { recursive: true });
+    for (const schema of input.schemaFiles)
+        copyFileSync(schema, join(input.workDir, basename(schema)));
+    try {
+        await execFileAsync(SCHEMA_COMPILER, ['--strict', `--targetdir=${input.workDir}`, input.workDir]);
+    }
+    catch (error) {
+        const failure = error;
+        if (failure.code === 'ENOENT') {
+            throw new Error(`gjsify ship: this layout has no install step, so \`${SCHEMA_COMPILER}\` has to run HERE to ` +
+                `turn the payload's schemas into \`${SCHEMA_CACHE}\` — and it is not on PATH. ` +
+                `Install it (${SCHEMA_COMPILER_HINT}). Without the compiled cache the launcher points ` +
+                'XDG_DATA_DIRS at a schema directory GSettings aborts on, so the bundle would build and ' +
+                'then die at its first `Gio.Settings.new()`.');
+        }
+        throw new Error(`gjsify ship: \`${SCHEMA_COMPILER} --strict\` refused this project's schemas.\n` +
+            `${(failure.stderr ?? '').trimEnd()}\n` +
+            '    `--strict` is deliberate: without it a malformed schema is SKIPPED at exit 0 and a ' +
+            'cache\n    is written without it, so the app still aborts on the schema that was dropped. ' +
+            'Fix the\n    file it names, or drop it from `gjsify.ship.schemas`.');
+    }
+    return [
+        {
+            path: SCHEMA_CACHE,
+            mode: 0o644,
+            source: { kind: 'file', path: join(input.workDir, 'gschemas.compiled') },
+        },
+    ];
+}

package/lib/utils/ship/scripts.js

@@ -11,6 +11,7 @@
 // reading `rpm -qp --scripts` on the first artifact this packer produced —
 // which is exactly the class of defect a rendered-output assertion would have
 // waved through.
+import { SHARE } from './share-dirs.js';
 /**
  * The cache refreshes this payload makes necessary, each guarded by the tool's
  * presence and `|| true`.
@@ -34,13 +35,13 @@ export function cacheRefreshCommands(facts, prefix) {
     if (facts.hasDesktopEntry) {
         refreshes.push({
             probe: 'update-desktop-database',
-            run: `update-desktop-database -q ${prefix}/share/applications`,
+            run: `update-desktop-database -q ${prefix}/${SHARE.applications}`,
         });
     }
     if (facts.hasIcons) {
         refreshes.push({
             probe: 'gtk-update-icon-cache',
-            run: `gtk-update-icon-cache -q -t -f ${prefix}/share/icons/hicolor`,
+            run: `gtk-update-icon-cache -q -t -f ${prefix}/${SHARE.icons}`,
         });
     }
     if (facts.hasMimeTypes) {
@@ -48,13 +49,16 @@ export function cacheRefreshCommands(facts, prefix) {
         // off the compiled cache in `share/mime/`, not off the packages directory.
         refreshes.push({
             probe: 'update-mime-database',
+            // The PARENT of `SHARE.mime`, not that directory: `update-mime-database` is
+            // given the mime ROOT and reads `packages/` inside it. Deriving it from
+            // `SHARE.mime` would pass the wrong path, so it stays spelled out.
             run: `update-mime-database ${prefix}/share/mime`,
         });
     }
     if (facts.hasSchemas) {
         refreshes.push({
             probe: 'glib-compile-schemas',
-            run: `glib-compile-schemas ${prefix}/share/glib-2.0/schemas`,
+            run: `glib-compile-schemas ${prefix}/${SHARE.schemas}`,
         });
     }
     return refreshes.map(({ probe, run }) => `if command -v ${probe} >/dev/null 2>&1; then ${run} || true; fi`);