@gjsify/cli 0.44.0 → 0.46.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,16 +88,51 @@ 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 },
         });
     }
+    for (const font of planFonts(settings))
+        files.push(font);
     for (const [dest, source] of Object.entries(settings.extraFiles)) {
         files.push({ path: assertInsidePrefix(dest), mode: 0o644, source: { kind: 'file', path: source } });
     }
     return normalise(files);
 }
+/**
+ * Font faces, under a directory named after the app id (ADR 0038).
+ *
+ * `share/fonts` is shared with every other package on a `/usr` prefix, exactly as
+ * `share/glib-2.0/schemas` and `share/mime/packages` are — so the app id is what
+ * keeps a face called `Regular.ttf` from being one of two files claiming the same
+ * path, with install order deciding the winner. Unlike those two the collision is
+ * not refused by NAME: a font's filename is the foundry's and there is no
+ * convention to hold it to, so the directory carries the id and the basenames are
+ * left alone. fontconfig scans recursively, so nesting them costs nothing —
+ * measured across fontconfig 2.14.1 → 2.18.3.
+ *
+ * A basename appearing twice IS refused, for the reason `planIcons` refuses one:
+ * two source files installing as one path means one of them is silently not
+ * shipped, and a missing face is a substituted typeface rather than an error.
+ */
+function planFonts(settings) {
+    const out = [];
+    const seen = new Map();
+    for (const font of settings.fontFiles) {
+        const path = `${SHARE.fonts}/${settings.appId}/${basename(font)}`;
+        const previous = seen.get(path);
+        if (previous !== undefined) {
+            throw new Error(`gjsify ship: ${font} and ${previous} both install as ${path}. ` +
+                'Two faces cannot share one filename — one would silently not ship, and a missing face ' +
+                'is a substituted typeface rather than an error. Rename one, or point ' +
+                '`gjsify.ship.fonts` at a directory holding only the faces you mean to ship.');
+        }
+        seen.set(path, font);
+        out.push({ path, mode: 0o644, source: { kind: 'file', path: font } });
+    }
+    return out;
+}
 /**
  * The per-format additions. Only the licence differs today, and it differs in
  * BOTH place and shape: Debian policy wants a machine-readable `copyright` in
@@ -178,7 +221,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 +269,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,98 @@
+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.
+ *
+ * A TWELFTH KEY, `ATSApplicationFontsPath`, is emitted when the bundle carries
+ * faces, and it is the first one here NOT cited to `refs/` — so the exception is
+ * stated rather than left to be noticed (ADR 0038). The rule this module opens
+ * with exists against DECORATION: the five absent keys are cosmetic, nothing a
+ * reader here can open contains them, and emitting one would be a guess with no
+ * observable behind it. This key is a MECHANISM, and its citation is Apple's own
+ * *Information Property List Key Reference*, which states the scope in the terms
+ * this command needs: *"If present, macOS activates the fonts at the specified
+ * path for use by the bundled app. The fonts are activated only for the bundled
+ * app and not for the system as a whole."* The value is a path relative to
+ * `Contents/Resources`.
+ *
+ * It is also the only route there is. Pango on macOS is CoreText-backed, GTK is
+ * not built against fontconfig on that platform, and
+ * `pango_font_map_add_font_file()` answers `G_IO_ERROR_NOT_SUPPORTED` on the
+ * CoreText map — so the alternatives are this key or a `CTFontManager` call made
+ * from inside somebody else's application, which is not a packaging command's
+ * business.
+ *
+ * WHAT THE ORACLE CAN AND CANNOT SEE: `plistlib` reads the key back like any
+ * other, so the FILE is checked. That macOS activates the directory, and that
+ * Pango's CoreText map then holds the family, is unverified here — which is what
+ * `Layout.fontGap` says out loud rather than letting a green stage imply.
+ */
+export declare function renderInfoPlist(input: LayoutMetadataInput, fontsPath?: string): 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;
+/**
+ * Render the entitlements plist `codesign --entitlements` takes.
+ *
+ * A SEPARATE FILE FROM `Info.plist` and a separate function, because it is a
+ * different document with a different reader: `Info.plist` describes the bundle
+ * to LaunchServices and ships inside it, while this one is an INPUT to the
+ * signature — `codesign` embeds the claims and the file itself is never staged.
+ *
+ * Every value is `<true/>`. An entitlement of this class is a boolean capability,
+ * and a `<false/>` entry is not "off", it is the same as absent — so a renderer
+ * taking values would offer a spelling with no meaning.
+ *
+ * WHICH KEYS, and why the set is not the reference's, is
+ * `utils/ship/signing.ts`'s decision; this function renders what it is given.
+ */
+export declare function renderEntitlements(keys: readonly string[]): string;

package/lib/utils/ship/plist.js

@@ -0,0 +1,256 @@
+// `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.
+ *
+ * A TWELFTH KEY, `ATSApplicationFontsPath`, is emitted when the bundle carries
+ * faces, and it is the first one here NOT cited to `refs/` — so the exception is
+ * stated rather than left to be noticed (ADR 0038). The rule this module opens
+ * with exists against DECORATION: the five absent keys are cosmetic, nothing a
+ * reader here can open contains them, and emitting one would be a guess with no
+ * observable behind it. This key is a MECHANISM, and its citation is Apple's own
+ * *Information Property List Key Reference*, which states the scope in the terms
+ * this command needs: *"If present, macOS activates the fonts at the specified
+ * path for use by the bundled app. The fonts are activated only for the bundled
+ * app and not for the system as a whole."* The value is a path relative to
+ * `Contents/Resources`.
+ *
+ * It is also the only route there is. Pango on macOS is CoreText-backed, GTK is
+ * not built against fontconfig on that platform, and
+ * `pango_font_map_add_font_file()` answers `G_IO_ERROR_NOT_SUPPORTED` on the
+ * CoreText map — so the alternatives are this key or a `CTFontManager` call made
+ * from inside somebody else's application, which is not a packaging command's
+ * business.
+ *
+ * WHAT THE ORACLE CAN AND CANNOT SEE: `plistlib` reads the key back like any
+ * other, so the FILE is checked. That macOS activates the directory, and that
+ * Pango's CoreText map then holds the family, is unverified here — which is what
+ * `Layout.fontGap` says out loud rather than letting a green stage imply.
+ */
+export function renderInfoPlist(input, fontsPath) {
+    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.
+        //
+        // `ATSApplicationFontsPath` sorts before every `CFBundle*` key, which is
+        // where alphabetical order puts it and also where a reader looks for it.
+        // Absent, not empty, when the bundle carries no face: an empty string is a
+        // path, and macOS would activate the Resources directory itself.
+        ...(fontsPath === undefined ? [] : [stringEntry('ATSApplicationFontsPath', fontsPath)]),
+        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}`;
+}
+/**
+ * Render the entitlements plist `codesign --entitlements` takes.
+ *
+ * A SEPARATE FILE FROM `Info.plist` and a separate function, because it is a
+ * different document with a different reader: `Info.plist` describes the bundle
+ * to LaunchServices and ships inside it, while this one is an INPUT to the
+ * signature — `codesign` embeds the claims and the file itself is never staged.
+ *
+ * Every value is `<true/>`. An entitlement of this class is a boolean capability,
+ * and a `<false/>` entry is not "off", it is the same as absent — so a renderer
+ * taking values would offer a spelling with no meaning.
+ *
+ * WHICH KEYS, and why the set is not the reference's, is
+ * `utils/ship/signing.ts`'s decision; this function renders what it is given.
+ */
+export function renderEntitlements(keys) {
+    const entries = keys.map((key) => `\t<key>${xmlText(key)}</key>\n\t<true/>`).join('\n');
+    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>',
+        entries,
+        '</dict>',
+        '</plist>',
+        '',
+    ].join('\n');
+}

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,23 @@ 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}`,
+    // Owned by `fonts-filesystem` — measured, `rpm -qf /usr/share/fonts` →
+    // `fonts-filesystem-5.0.0-2.fc44`. DERIVED although it is a PARENT rather than a
+    // directory the planner stages into: `plan.ts` writes `share/fonts/<appId>`,
+    // which this package legitimately owns, and the parent happens to BE
+    // `SHARE.fonts` exactly — so deriving it costs nothing and cannot drift the way
+    // the two literal parents above can.
+    `/usr/${SHARE.fonts}`,
     '/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[]>;