@gjsify/cli 0.44.0 → 0.46.0

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

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

@@ -1,5 +1,5 @@
-import type { AppMetadata, ConfigDataFlatpak, ConfigDataShip, DescriptionBlock } from '../../types/config-data.js';
-import type { ShipSettings } from './types.js';
+import type { AppMetadata, ConfigDataFlatpak, ConfigDataShip, DescriptionBlock, ShipAppOptions } from '../../types/config-data.js';
+import type { HostOs, ShipSettings } from './types.js';
 /** The subset of `package.json` the resolver reads. */
 export interface ShipPackageManifest {
     name?: string;
@@ -34,6 +34,8 @@ export interface DiscoveredPayload {
         rel: string;
         abs: string;
     }[];
+    /** Absolute paths of the font faces the application ships itself. */
+    fontFiles: string[];
     licenseFile?: string;
 }
 export interface SettingsInput {
@@ -42,12 +44,99 @@ export interface SettingsInput {
     ship: ConfigDataShip;
     /** Metadata fallback — `gjsify.flatpak` already carries these fields for many projects. */
     flatpak: ConfigDataFlatpak;
+    /**
+     * What the command line decided before any config was read.
+     *
+     * `layoutOs` is REQUIRED, unlike its two neighbours, and the asymmetry is the
+     * point: `outDir` and `arch` have derived defaults that are correct when
+     * nobody says anything, while the layout is chosen by `gjsify ship <os>` (or
+     * by the host) before this function is reached. Making it optional would put
+     * a fourth default for it in here, and a second place that decides the layout
+     * is how the manifest's `target.os` and the staged paths come apart.
+     */
     cli: {
         outDir?: string;
         arch?: string;
+        layoutOs: HostOs;
     };
     discovered: DiscoveredPayload;
+    /**
+     * THIS TARGET's runtime, as {@link resolveShipApp} resolved it — never the
+     * raw `gjsify.app`.
+     *
+     * The TYPE is the enforcement: a caller handing the project field straight
+     * through no longer compiles. That is exactly the regression this field used
+     * to carry in silence, since every generator downstream reads `settings.app`.
+     */
+    app: 'gjs' | 'node';
 }
+/** The runtime one ship target runs, and which key decided it. */
+export interface ResolvedShipApp {
+    /** What the launcher execs, what the package depends on, and which formats can wrap it. */
+    app: 'gjs' | 'node';
+    /** The config key the answer came from — named in the refusal and in the notice. */
+    key: string;
+    /** Whether a per-target key overrode the project default. */
+    overridden: boolean;
+}
+/**
+ * The ONE place a ship target's runtime is decided: `gjsify.app` as the DEFAULT,
+ * `gjsify.ship.app.<os>` as this target's override.
+ *
+ * WHY IT IS PER TARGET, measured on a GTK4 application rather than derived from
+ * the schema: with one field, `gjsify ship darwin` refused its formats until
+ * `gjsify.app` was `"node"` — and setting it turned the LINUX `.deb`'s
+ * `Depends: gjs (>= 1.86)` into `Depends: nodejs (>= 24)`, which apt refuses on
+ * trixie, Ubuntu 24.04 and Ubuntu 26.04. A macOS decision made the Linux package
+ * uninstallable, because every generator read the PROJECT field instead of the
+ * resolved runtime of its OWN target (#1486, ADR 0024 § A22). Nothing downstream
+ * reads either key; they all read `settings.app`, which is this result.
+ *
+ * NOT PER LAYOUT BY DEFAULT, and the first cut of the layout axis got this
+ * exactly backwards. Reading ADR § 4's runtime table as a per-layout
+ * REQUIREMENT refused `gjsify.app: "gjs"` for the macOS layout — the entire
+ * audience of that command — while a project with no `gjsify.app` key sailed
+ * through and staged a launcher naming `node` in front of a GJS bundle. § 4
+ * derives the runtime a shipped artifact CARRIES, which is
+ * `Layout.shippedRuntime`; what an artifact runs is what its author says, which
+ * is this. So an absent override means the project field and never the layout's
+ * derived answer.
+ *
+ * MUST NOT be fed `Config.forBuild`'s resolution, whose fallback is the HOST
+ * runtime. That fallback is right for a build (`gjsify build` under Node should
+ * produce a Node bundle by default) and catastrophic for a package: running this
+ * command under Node would silently turn every undeclared GJS project into one
+ * whose launcher execs `node`. An undeclared target is the common case for a GJS
+ * app, and it means GJS.
+ *
+ * TWO REFUSALS, and each is here because the alternative to refusing is SILENT.
+ * A `browser` or `nativescript` value has no artifact to be — no process to
+ * start, an APK/IPA through another pipeline (§ 4) — and would otherwise leave
+ * here as a `.deb` a stranger installs and cannot run, with no gate between here
+ * and their machine; `Layout.runtimeGap` only WARNS because what it describes is
+ * a staged tree rather than an artifact, and the per-FORMAT half of the question
+ * is `assertFormatCanRunInterpreter`, which asks what a container can EXECUTE.
+ * A key outside {@link SHIP_APP_OSES} — `windows`, the `gjsify ship <os>`
+ * POSITIONAL's spelling — would resolve to nothing and leave that target on the
+ * project-wide answer with every gate green, which is why the author who typed
+ * it reads the result as gjsify not supporting the split at all. Both refusals
+ * name the KEY that carried the value: with two keys, "this project declares" no
+ * longer locates it.
+ *
+ * `gjsify ship --from-stage` reads neither key and needs neither: the stage
+ * manifest records the RESOLVED value, so the packing host reads an answer
+ * rather than a default, and `assertLauncherMatchesInterpreter` still compares
+ * the staged `bin/<name>`'s own `exec` line against the dependency about to be
+ * written.
+ */
+export declare function resolveShipApp(input: {
+    /** `gjsify.app` as DECLARED — `undefined` when the project declares nothing. */
+    project?: string;
+    /** `gjsify.ship.app`, the per-layout override table. */
+    perTarget?: ShipAppOptions;
+    /** The layout this run assembles. */
+    layoutOs: HostOs;
+}): ResolvedShipApp;
 export interface ResolvedSettings {
     settings: ShipSettings;
     /** The merged metadata the renderers read. */

package/lib/utils/ship/settings.js

@@ -11,9 +11,93 @@
 // indistinguishable from a value the user typed and would clobber the config.
 import { validateMimeTypes } from './mime.js';
 import { basename } from 'node:path';
-import { DEFAULT_GJS_FLOOR } from './depends.js';
+import { DEFAULT_GJS_FLOOR, DEFAULT_NODE_FLOOR } from './depends.js';
 import { resolveShipFlatpakSettings } from './flatpak-config.js';
 import { assertRelease, normaliseVersion } from './version.js';
+/**
+ * The OS keys `gjsify.ship.app` may carry — {@link HostOs}, the
+ * `process.platform` spelling.
+ *
+ * `satisfies Record<HostOs, true>` rather than a bare list: a fourth layout
+ * cannot arrive without this object failing to compile, so the accepted set
+ * stays total without a second place to remember to update.
+ */
+const SHIP_APP_OSES = { linux: true, darwin: true, win32: true };
+/**
+ * The ONE place a ship target's runtime is decided: `gjsify.app` as the DEFAULT,
+ * `gjsify.ship.app.<os>` as this target's override.
+ *
+ * WHY IT IS PER TARGET, measured on a GTK4 application rather than derived from
+ * the schema: with one field, `gjsify ship darwin` refused its formats until
+ * `gjsify.app` was `"node"` — and setting it turned the LINUX `.deb`'s
+ * `Depends: gjs (>= 1.86)` into `Depends: nodejs (>= 24)`, which apt refuses on
+ * trixie, Ubuntu 24.04 and Ubuntu 26.04. A macOS decision made the Linux package
+ * uninstallable, because every generator read the PROJECT field instead of the
+ * resolved runtime of its OWN target (#1486, ADR 0024 § A22). Nothing downstream
+ * reads either key; they all read `settings.app`, which is this result.
+ *
+ * NOT PER LAYOUT BY DEFAULT, and the first cut of the layout axis got this
+ * exactly backwards. Reading ADR § 4's runtime table as a per-layout
+ * REQUIREMENT refused `gjsify.app: "gjs"` for the macOS layout — the entire
+ * audience of that command — while a project with no `gjsify.app` key sailed
+ * through and staged a launcher naming `node` in front of a GJS bundle. § 4
+ * derives the runtime a shipped artifact CARRIES, which is
+ * `Layout.shippedRuntime`; what an artifact runs is what its author says, which
+ * is this. So an absent override means the project field and never the layout's
+ * derived answer.
+ *
+ * MUST NOT be fed `Config.forBuild`'s resolution, whose fallback is the HOST
+ * runtime. That fallback is right for a build (`gjsify build` under Node should
+ * produce a Node bundle by default) and catastrophic for a package: running this
+ * command under Node would silently turn every undeclared GJS project into one
+ * whose launcher execs `node`. An undeclared target is the common case for a GJS
+ * app, and it means GJS.
+ *
+ * TWO REFUSALS, and each is here because the alternative to refusing is SILENT.
+ * A `browser` or `nativescript` value has no artifact to be — no process to
+ * start, an APK/IPA through another pipeline (§ 4) — and would otherwise leave
+ * here as a `.deb` a stranger installs and cannot run, with no gate between here
+ * and their machine; `Layout.runtimeGap` only WARNS because what it describes is
+ * a staged tree rather than an artifact, and the per-FORMAT half of the question
+ * is `assertFormatCanRunInterpreter`, which asks what a container can EXECUTE.
+ * A key outside {@link SHIP_APP_OSES} — `windows`, the `gjsify ship <os>`
+ * POSITIONAL's spelling — would resolve to nothing and leave that target on the
+ * project-wide answer with every gate green, which is why the author who typed
+ * it reads the result as gjsify not supporting the split at all. Both refusals
+ * name the KEY that carried the value: with two keys, "this project declares" no
+ * longer locates it.
+ *
+ * `gjsify ship --from-stage` reads neither key and needs neither: the stage
+ * manifest records the RESOLVED value, so the packing host reads an answer
+ * rather than a default, and `assertLauncherMatchesInterpreter` still compares
+ * the staged `bin/<name>`'s own `exec` line against the dependency about to be
+ * written.
+ */
+export function resolveShipApp(input) {
+    const perTarget = input.perTarget ?? {};
+    // The WHOLE table, not only this run's key: a mis-keyed override is silent by
+    // construction, so `gjsify ship linux` is the run that has to say `windows` is
+    // not a key. Checking only the resolving key would leave the typo to be found
+    // by the `gjsify ship windows` that already reads as unsupported.
+    for (const os of Object.keys(perTarget)) {
+        if (Object.hasOwn(SHIP_APP_OSES, os))
+            continue;
+        throw new Error(`gjsify ship: \`gjsify.ship.app.${os}\` is not an OS this command assembles for. Known: ` +
+            `${Object.keys(SHIP_APP_OSES).join(', ')} — the \`process.platform\` spelling, not the ` +
+            "`gjsify ship <os>` positional's. A runtime under a key nothing reads leaves that target on " +
+            '`gjsify.app` with nothing to say so.');
+    }
+    const override = perTarget[input.layoutOs];
+    const overridden = override !== undefined;
+    const key = overridden ? `gjsify.ship.app.${input.layoutOs}` : 'gjsify.app';
+    const declared = overridden ? override : input.project;
+    if (declared !== undefined && declared !== 'gjs' && declared !== 'node') {
+        throw new Error(`gjsify ship: \`${key}\` is "${declared}", and only \`gjs\` and \`node\` can be ` +
+            'packaged. A browser bundle has no process to launch, and a NativeScript app ships as an APK/IPA ' +
+            'through a different pipeline. ADR 0024 § 4 has the runtime-per-OS table.');
+    }
+    return { app: declared === 'node' ? 'node' : 'gjs', key, overridden };
+}
 /** Freedesktop main category → deb `Section:` / rpm `Group:`. First match wins. */
 const CATEGORY_SECTIONS = [
     ['Development', { section: 'devel', group: 'Development/Tools' }],
@@ -49,6 +133,10 @@ export function resolveShipSettings(input) {
     const appId = ship.appId ?? flatpak.appId ?? reverseDnsOrThrow(pkg.name, binaryName);
     const name = metadata.name ?? titleCase(binaryName);
     const kind = metadata.kind ?? 'app';
+    // NOT resolved here: `resolveShipApp` already did, before the format list was
+    // decided from it. A second defaulting rule in this function would be the
+    // second path those two answers could come apart on.
+    const app = input.app;
     const rawVersion = ship.version ?? pkg.version;
     if (!rawVersion) {
         throw new Error('gjsify ship: no version — set `version` in package.json or `gjsify.ship.version`.');
@@ -102,11 +190,15 @@ export function resolveShipSettings(input) {
         schemaFiles: discovered.schemaFiles,
         typelibFiles: discovered.typelibFiles,
         localeFiles: discovered.localeFiles,
+        fontFiles: discovered.fontFiles,
         extraFiles: ship.extraFiles ?? {},
         execArgs: ship.execArgs ?? [],
         outDir: input.cli.outDir ?? ship.outDir ?? 'ship',
         arch: input.cli.arch ?? process.arch,
+        app,
+        layoutOs: input.cli.layoutOs,
         minGjsVersion: ship.minGjsVersion ?? DEFAULT_GJS_FLOOR,
+        minNodeVersion: ship.minNodeVersion ?? DEFAULT_NODE_FLOOR,
         flatpak: flatpakSettings.settings,
     };
     return { settings, metadata, warnings };

package/lib/utils/ship/share-dirs.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Each entry is a directory the freedesktop/GNOME stack looks in BY NAME. None of
+ * them is ours to choose: `bindtextdomain` reads `share/locale/<lang>/LC_MESSAGES`,
+ * `glib-compile-schemas` compiles `share/glib-2.0/schemas`, and the icon theme
+ * spec fixes `share/icons/hicolor`. That is also why this is a closed set rather
+ * than a convention — a typo in any of them installs a file nothing ever reads.
+ */
+export declare const SHARE: {
+    /** freedesktop desktop entries. */
+    readonly applications: "share/applications";
+    /** The hicolor icon theme, whose cache `gtk-update-icon-cache` builds. */
+    readonly icons: "share/icons/hicolor";
+    /** GSettings schema sources, compiled into `gschemas.compiled` at install. */
+    readonly schemas: "share/glib-2.0/schemas";
+    /** shared-mime-info documents, folded into the mime cache at install. */
+    readonly mime: "share/mime/packages";
+    /** AppStream components. */
+    readonly metainfo: "share/metainfo";
+    /** Compiled gettext catalogues, read directly — no install step. */
+    readonly locale: "share/locale";
+    /**
+     * Font faces the application ships — ONE directory, and three different things
+     * reach it (ADR 0038). No install step on any of them.
+     *
+     * On LINUX fontconfig scans it, by two rules that are both the stock
+     * `fonts.conf`'s rather than ours: `<dir>/usr/share/fonts</dir>` unconditionally,
+     * which covers a `.deb`/`.rpm`, and `<dir prefix="xdg">fonts</dir>`, which
+     * fontconfig expands over `XDG_DATA_DIRS` as well as `XDG_DATA_HOME` — so the
+     * variable the launcher already exports covers `/app` in a Flatpak and any other
+     * prefix. `fonts-conf(5)` documents only `XDG_DATA_HOME` there; the expansion was
+     * measured in EIGHT independently built fontconfigs (2.14.1 through 2.18.3), in
+     * every list position, recursively, with a cold cache and a negative control.
+     * Behaviour, not documentation — which is why it is written here and in ADR 0038
+     * § *What was measured* rather than re-derived from the man page.
+     *
+     * On MACOS none of that applies and the directory is the same: Pango there is
+     * CoreText-backed and GTK is not built against fontconfig, so `Info.plist`'s
+     * `ATSApplicationFontsPath` points at this directory instead (`layout.ts`).
+     *
+     * On WINDOWS nothing reaches it by configuration at all — measured there, not
+     * inferred: the default font map does not read fontconfig even when the staged
+     * directory is the ONLY configuration it is given, while `add_font_file` on that
+     * same map does register the family. So the launcher's `GJSIFY_FONT_DIR` hands
+     * the directory to the app to register. `Layout.fontGap` carries the numbers and
+     * the three candidates that look like they would work and do not.
+     *
+     * That the PATH is one while the mechanisms are three is the point: `planStage`
+     * keeps emitting one payload, and every per-OS answer is a layout decision.
+     */
+    readonly fonts: "share/fonts";
+};
+/** Is `path` inside `dir`? Directory-boundary aware, so `share/mimetypes` is not inside `share/mime`. */
+export declare function isUnder(path: string, dir: string): boolean;

package/lib/utils/ship/share-dirs.js

@@ -0,0 +1,76 @@
+// The `share/` subdirectories a payload installs into — ONE definition.
+//
+// WHY THIS FILE EXISTS, and it is a repair rather than a tidy-up. Four call
+// sites answer questions about the same directories and every one of them spelled
+// them out again: `plan.ts` stages a file there, `readPayloadFacts` asks whether
+// the payload put anything there, `cacheRefreshCommands` emits the install step
+// that makes it WORK, and `linuxInstallDependent` names the ones a non-Linux
+// layout carries without that step. `share/glib-2.0/schemas` alone existed as
+// five independent string literals across the tree.
+//
+// A comment claiming they "cannot drift" was measured FALSE: pointing one rule in
+// `linuxInstallDependent` at a directory that matches nothing silently dropped a
+// file from the warning `gjsify ship` prints, and the whole suite stayed green at
+// exit 0. The prose was the mechanism, which is to say there was none. Importing
+// one constant makes the compiler the mechanism instead.
+//
+// PREFIX-RELATIVE and POSIX-separated, like every path in the plan. The layout
+// map (`layout.ts`) is what turns these into `Contents/Resources/share/…` or a
+// Windows program directory's `share\`; nothing here knows about that, and
+// nothing here is absolute — `scripts.ts` prepends the format's install prefix,
+// which is `/usr` for a `.deb` and `/app` for a Flatpak.
+/**
+ * Each entry is a directory the freedesktop/GNOME stack looks in BY NAME. None of
+ * them is ours to choose: `bindtextdomain` reads `share/locale/<lang>/LC_MESSAGES`,
+ * `glib-compile-schemas` compiles `share/glib-2.0/schemas`, and the icon theme
+ * spec fixes `share/icons/hicolor`. That is also why this is a closed set rather
+ * than a convention — a typo in any of them installs a file nothing ever reads.
+ */
+export const SHARE = {
+    /** freedesktop desktop entries. */
+    applications: 'share/applications',
+    /** The hicolor icon theme, whose cache `gtk-update-icon-cache` builds. */
+    icons: 'share/icons/hicolor',
+    /** GSettings schema sources, compiled into `gschemas.compiled` at install. */
+    schemas: 'share/glib-2.0/schemas',
+    /** shared-mime-info documents, folded into the mime cache at install. */
+    mime: 'share/mime/packages',
+    /** AppStream components. */
+    metainfo: 'share/metainfo',
+    /** Compiled gettext catalogues, read directly — no install step. */
+    locale: 'share/locale',
+    /**
+     * Font faces the application ships — ONE directory, and three different things
+     * reach it (ADR 0038). No install step on any of them.
+     *
+     * On LINUX fontconfig scans it, by two rules that are both the stock
+     * `fonts.conf`'s rather than ours: `<dir>/usr/share/fonts</dir>` unconditionally,
+     * which covers a `.deb`/`.rpm`, and `<dir prefix="xdg">fonts</dir>`, which
+     * fontconfig expands over `XDG_DATA_DIRS` as well as `XDG_DATA_HOME` — so the
+     * variable the launcher already exports covers `/app` in a Flatpak and any other
+     * prefix. `fonts-conf(5)` documents only `XDG_DATA_HOME` there; the expansion was
+     * measured in EIGHT independently built fontconfigs (2.14.1 through 2.18.3), in
+     * every list position, recursively, with a cold cache and a negative control.
+     * Behaviour, not documentation — which is why it is written here and in ADR 0038
+     * § *What was measured* rather than re-derived from the man page.
+     *
+     * On MACOS none of that applies and the directory is the same: Pango there is
+     * CoreText-backed and GTK is not built against fontconfig, so `Info.plist`'s
+     * `ATSApplicationFontsPath` points at this directory instead (`layout.ts`).
+     *
+     * On WINDOWS nothing reaches it by configuration at all — measured there, not
+     * inferred: the default font map does not read fontconfig even when the staged
+     * directory is the ONLY configuration it is given, while `add_font_file` on that
+     * same map does register the family. So the launcher's `GJSIFY_FONT_DIR` hands
+     * the directory to the app to register. `Layout.fontGap` carries the numbers and
+     * the three candidates that look like they would work and do not.
+     *
+     * That the PATH is one while the mechanisms are three is the point: `planStage`
+     * keeps emitting one payload, and every per-OS answer is a layout decision.
+     */
+    fonts: 'share/fonts',
+};
+/** Is `path` inside `dir`? Directory-boundary aware, so `share/mimetypes` is not inside `share/mime`. */
+export function isUnder(path, dir) {
+    return path.startsWith(`${dir}/`);
+}