@gjsify/cli 0.53.0 → 0.55.0

package/lib/commands/ship.js

@@ -34,6 +34,7 @@ import { isGtkRuntimeTarget, stageAppRuntime } from '../utils/ship/app-runtime.j
 import { discoverPayload } from '../utils/ship/discover.js';
 import { appDirFor, appDirPayload, appImageHostRequirements, appImageRuntimeNotice, buildAppImage, findPinnedRuntime, stampAppDirTimes, } from '../utils/ship/appimage.js';
 import { buildDmgImage, dmgVolumeDir, dmgVolumeName } from '../utils/ship/dmg.js';
+import { assertNoDroppedFlatpakModules } from '../utils/ship/flatpak-config.js';
 import { buildFlatpakBundle } from '../utils/ship/flatpak.js';
 import { iconSizes, resolveAppIcon } from '../utils/ship/icons.js';
 import { localizeMetadata } from '../utils/ship/localize-metadata.js';
@@ -45,7 +46,7 @@ import { compileSchemasForPayload, compileSchemasForStage } from '../utils/ship/
 import { buildMsi, MSI_PAYLOAD_DIR } from '../utils/ship/msi.js';
 import { buildZip, zipEntriesFromPayload } from '../utils/ship/zip.js';
 import { assertEntryRunsUnder } from '../utils/ship/entry-interpreter.js';
-import { scanGiNamespaces } from '../utils/ship/gi-namespaces.js';
+import { scanGiRequirements } from '../utils/ship/gi-namespaces.js';
 import { assertLauncherMatchesInterpreter, assertPayloadMatchesArch, buildTimestamp, isArchIndependent, linuxInstallDependent, readPayloadFacts, } from '../utils/ship/payload.js';
 import { assertOverlayIsLicensed, planOverlay, planStage } from '../utils/ship/plan.js';
 import { assertHostCanSign, notarizeArtifact, stapleArtifact, resolveNotaryPlan, resolveSignPlan, signPayload, } from '../utils/ship/signing.js';
@@ -252,6 +253,10 @@ async function assemble(args) {
                 'thing as an error.');
         }
     }
+    // Under `--stage` too: the stage records the Flatpak settings, and a stage
+    // that quietly omits the project's modules packs without them later.
+    if (formats.some((format) => format.id === 'flatpak'))
+        assertNoDroppedFlatpakModules(flatpak);
     if (!args.stage)
         assertPackable(formats, layout, args.os === undefined ? 'host' : 'positional', unusable);
     // BEFORE the build, beside `assertCanPack` and for the same reason: a
@@ -537,9 +542,20 @@ async function assemble(args) {
     // `gi://` specifiers are what the emitted `Depends:` is derived from
     // (ADR 0024 § 6), and the packing host has the staged copy but no way to
     // tell which staged file is the entry.
-    const namespaces = scanGiNamespaces(bundleSource);
-    if (args.verbose)
+    const gi = scanGiRequirements(bundleSource);
+    const namespaces = gi.namespaces;
+    const optionalNamespaces = gi.optional;
+    if (args.verbose) {
+        const hard = namespaces.filter((ns) => !optionalNamespaces.includes(ns));
         console.log(`${LOG} gi namespaces: ${namespaces.join(', ') || '(none)'}`);
+        // The split is worth its own line whenever it is non-empty: an author who
+        // wrote `&optional` and sees the namespace under the plain list has learned
+        // nothing about whether their package will declare it.
+        if (optionalNamespaces.length > 0) {
+            console.log(`${LOG} gi optional namespaces: ${optionalNamespaces.join(', ')}`);
+            console.log(`${LOG} gi required namespaces: ${hard.join(', ') || '(none)'}`);
+        }
+    }
     // PLACED, like the payload, and through the same map. `planOverlay` answers a
     // question about the FORMAT (`share/doc/<pkg>/copyright` for Debian policy,
     // `share/licenses/<pkg>/LICENSE` for rpm) in the prefix-relative shape every
@@ -578,8 +594,9 @@ async function assemble(args) {
         // into a Debian `Depends:`, at exit 0).
         if (format.depends === null)
             continue;
-        deriveDepends(format.depends, {
+        const derived = deriveDepends(format.depends, {
             namespaces,
+            optionalNamespaces,
             hasIcons: facts.hasIcons,
             hasSchemas: facts.hasSchemas,
             interpreter: settings.app,
@@ -589,6 +606,17 @@ async function assemble(args) {
             minGjsVersion: settings.minGjsVersion,
             minNodeVersion: settings.minNodeVersion,
         });
+        // Reported here and not inside `deriveDepends`, which is also called by
+        // `packOne` on a host that has no project — and this is the only place that
+        // does. An optional namespace nobody mapped produces NO package field, and
+        // the app runs without the typelib either way, so nothing downstream will
+        // ever say so again.
+        for (const namespace of derived.unmappedOptional) {
+            console.warn(`${LOG} gi://${namespace} is imported optionally, but no ${format.depends} package is known ` +
+                'to ship its typelib, so no Recommends entry names it. The package builds and runs ' +
+                `without it. Add the row if the namespace should be recommended: \`gjsify.ship.typelibPackages.` +
+                `${namespace} = { "${format.depends}": "…" }\`.`);
+        }
         // One warning per package, for the interpreter it actually declares. A
         // floor warning about a dependency this package does not emit is noise,
         // and a noisy warning is the one nobody reads when it matters.
@@ -602,7 +630,16 @@ async function assemble(args) {
     // is sometimes packable elsewhere and sometimes not is a worse contract
     // than one that always is, and it is what lets the e2e suite compare the
     // one-process artifact with the two-phase one.
-    const manifest = writeStageManifest({ stageDir, settings, formats, mtime, namespaces, staged, overlay });
+    const manifest = writeStageManifest({
+        stageDir,
+        settings,
+        formats,
+        mtime,
+        namespaces,
+        optionalNamespaces,
+        staged,
+        overlay,
+    });
     if (args.stage) {
         // `(none)` spelled out, because an empty list printed as nothing after
         // "formats " reads as a truncated line rather than as a fact. WHICH fact
@@ -638,6 +675,7 @@ async function assemble(args) {
             stageDir,
             outRoot,
             namespaces,
+            optionalNamespaces,
             mtime,
             sign,
             notarize,
@@ -799,6 +837,9 @@ async function finishFromStage(args, fromStage) {
         for (const file of manifest.staged)
             console.log(`${LOG}   ${file.path}`);
         console.log(`${LOG} gi namespaces: ${manifest.namespaces.join(', ') || '(none)'}`);
+        if ((manifest.optionalNamespaces ?? []).length > 0) {
+            console.log(`${LOG} gi optional namespaces: ${manifest.optionalNamespaces?.join(', ')}`);
+        }
     }
     // The stage's own directory is not written to — `writeStage` wipes what it
     // is pointed at, and pointing it at an arriving stage would delete the
@@ -832,6 +873,7 @@ async function finishFromStage(args, fromStage) {
             stageDir,
             outRoot,
             namespaces: manifest.namespaces,
+            optionalNamespaces: manifest.optionalNamespaces ?? [],
             mtime,
             sign,
             notarize,
@@ -858,10 +900,11 @@ async function packOne(input) {
     // this answers used to be answered from the project's file lists, which are
     // absolute paths on the build host and therefore unavailable here.
     const facts = readPayloadFacts(assembled);
-    const depends = format.depends === null
-        ? []
+    const derived = format.depends === null
+        ? { requires: [], recommends: [], unmappedOptional: [] }
         : deriveDepends(format.depends, {
             namespaces: input.namespaces,
+            optionalNamespaces: input.optionalNamespaces,
             hasIcons: facts.hasIcons,
             hasSchemas: facts.hasSchemas,
             interpreter: settings.app,
@@ -871,6 +914,8 @@ async function packOne(input) {
             minGjsVersion: settings.minGjsVersion,
             minNodeVersion: settings.minNodeVersion,
         });
+    const depends = derived.requires;
+    const recommends = derived.recommends;
     // `--arch` is a CLAIM about the payload and nothing else compared it to one:
     // an x86-64 `.so` staged with `--arch arm64` packed at exit 0 and `rpm -qp
     // --qf %{ARCH}` confirmed `aarch64`, because rpm reads the header and the
@@ -956,7 +1001,9 @@ async function packOne(input) {
         })
         : assembled;
     const archLabel = format.archName(input.arch, isArchIndependent(payload));
-    const common = { settings, payload, prefix: format.prefix, depends, archLabel, mtime };
+    // `recommends` rides the shared input object, so a format that does not write the
+    // field (every non-deb/rpm row) simply ignores an extra property it never reads.
+    const common = { settings, payload, prefix: format.prefix, depends, recommends, archLabel, mtime };
     const outDir = join(outRoot, 'out');
     mkdirSync(outDir, { recursive: true });
     const target = join(outDir, format.fileName(settings, archLabel));
@@ -1010,6 +1057,7 @@ async function packOne(input) {
                 minGjsVersion: settings.minGjsVersion,
                 minNodeVersion: settings.minNodeVersion,
                 namespaces: input.namespaces,
+                optionalNamespaces: input.optionalNamespaces,
                 bundledTypelibs: facts.bundledTypelibs,
             });
             const appDir = appDirFor(outRoot);

package/lib/commands/webext/index.js

@@ -5,7 +5,7 @@
 import { webextBuildCommand, webextDevCommand, webextZipCommand } from './subcommands.js';
 export const webextCommand = {
     command: 'webext <subcommand>',
-    description: 'Browser extensions: build, zip and develop one WebExtension for Chrome, Edge, Firefox and Safari.',
+    description: 'Browser extensions: build, zip and develop one WebExtension for Chrome, Edge, Firefox, Opera and Safari.',
     builder: (yargs) => yargs
         .command(webextBuildCommand.command, webextBuildCommand.description, webextBuildCommand.builder, webextBuildCommand.handler)
         .command(webextZipCommand.command, webextZipCommand.description, webextZipCommand.builder, webextZipCommand.handler)

package/lib/types/config-data.d.ts

@@ -706,6 +706,11 @@ export interface ShipSignOptions {
  * the one thing ADR 0024 § 8 gates the whole migration on. A project that has
  * to BUILD something inside the sandbox still has `gjsify flatpak init` +
  * `gjsify flatpak build`, unchanged.
+ *
+ * Setting `gjsify.flatpak.modules` / `extraModules` and shipping the `flatpak`
+ * target is REFUSED (`assertNoDroppedFlatpakModules`) rather than ignored:
+ * those keys are read by `flatpak init` only, and dropping them at exit 0 hid an
+ * `extra-data` module until the app ran without its downloaded binary.
  */
 export interface ShipFlatpakOptions {
     /**

package/lib/utils/oxc-resolve.js

@@ -41,8 +41,8 @@
 // `GJSIFY_OXFMT=native|npm` is the explicit override (native throws when the
 // prebuild isn't loadable instead of silently switching engines).
 //
-// oxlint has NO native path yet: its JS-plugin host (the internal
-// `gjsify/register-class-order` rule wired via `.oxlintrc.json` jsPlugins)
+// oxlint has NO native path yet: its JS-plugin host (the
+// `@gjsify/oxlint-plugin-gjsify` rules wired via `.oxlintrc.json` jsPlugins)
 // lives in the Node launcher, so a native oxlint bridge could only run the
 // Rust rule subset. Lint stays Node-spawned until that trade-off is decided
 // (tracked in status/open-todos/README.md).
@@ -264,11 +264,13 @@ async function tryLoadNativeOxfmt() {
             // `bundler-pick.ts`'s `tryLoadNative()` gives — so a library that will
             // not load names itself instead of failing inside `runOxfmt()`.
             // Resolved and imported, not statically imported — the reasoning is
-            // at the top of this file. By the time a formatter asks for the
-            // native backend, utils' `lib/esm` is built. `./native-library`
-            // rather than `./core`: `core` re-exports `main-loop`, whose
-            // module-level singleton would then exist twice in a process that
-            // already carries it inlined in the GJS bundle.
+            // at the top of this file. `./native-library` rather than `./core`:
+            // `core` re-exports `main-loop`, whose module-level singleton would
+            // then exist twice in a process that already carries it inlined in the
+            // GJS bundle. Off disk, so the walk follows the WORKSPACE and
+            // `@gjsify/utils build:esm` must precede this call — the same
+            // precondition `bundler-pick.ts` carries, held by rule 5 of
+            // `scripts/check-build-infra-order.mjs`.
             //
             // Its own `try` because the outer one cannot tell this apart from
             // "there is no native backend", and `_nativeOxfmtLoadError` is the

package/lib/utils/ship/app-runtime.d.ts

@@ -102,8 +102,8 @@ export interface ResolvedNodeGiPackage {
  * NOT the published tarball. `files` in node-gi's manifest also lists `src/`,
  * `binding.gyp` and `scripts/install.mjs` — the inputs to `node-gyp`, which a
  * `.app` never runs — and the `.d.ts` declarations, which nothing inside a bundle
- * compiles against. And it lists `prebuilds/`, which this module stages into
- * `Contents/Frameworks` instead, where a `.app` keeps loadable code.
+ * compiles against. And it lists `prebuilds/`, which this module stages under
+ * `Layout.dirs().native`, the directory a `.app` keeps loadable code in.
  *
  * So the rule is what `require('@gjsify/node-gi/<subpath>')` can REACH:
  * `package.json` (the `exports` map is what resolves every subpath), every `.js`
@@ -120,15 +120,17 @@ export declare function resolveNodeGiPackage(options?: ResolveRuntimeOptions): R
  * literals, so the paths the launcher exports and the paths the stager writes
  * cannot drift: they are computed here once and both callers read this result.
  *
- * `Contents/Frameworks/node-gi/prebuilds/<target>/` is node-gi's OWN sibling
- * layout reproduced verbatim inside `dirs.native`. It is not a naming preference:
+ * `<dirs.native>/node-gi/prebuilds/<target>/` is node-gi's OWN sibling layout
+ * reproduced verbatim inside `Layout.dirs().native` (`Contents/Resources/native`
+ * on a `.app` — `layout.ts`'s darwin row carries why that is not
+ * `Contents/Frameworks`). It is not a naming preference:
  * `resolveGtkRuntimeBundle()` probes `<dir>/lib` and `<dir>/girepository-1.0`,
  * the addon's `@rpath` is `@loader_path/gtk/lib`, and `loaders.cache` addresses
  * each pixbuf loader relative to the bundle toplevel. Reproducing the shape is
  * what makes every one of those relations still true after the copy.
  */
 export interface AppRuntimePaths {
-    /** `<App>.app/Contents/Frameworks/node-gi` — the package root the layout imitates. */
+    /** `<App>.app/Contents/Resources/native/node-gi` — the package root the layout imitates. */
     nodeGiRoot: string;
     /**
      * `<App>.app/Contents/Resources/lib/node_modules/@gjsify/node-gi` — where

package/lib/utils/ship/app-runtime.js

@@ -47,11 +47,14 @@
 // THAT directory — so `prebuildAddonPath()` looks for
 // `…/node_modules/@gjsify/node-gi/prebuilds/<target>/node_gi.node` and
 // `resolveGtkRuntimeBundle()`'s candidate 2 for `…/prebuilds/<target>/gtk`, and
-// neither is where a `.app` may keep loadable code: `Contents/Frameworks` is, and
-// it is what `codesign` now reaches (ADR 0024 § A4) — M6 landed, and
-// `utils/ship/signing.ts` re-signs every Mach-O in the payload by magic number,
-// which is most of this closure. Putting it under `Resources` to save two
-// `export` lines would trade a correct bundle for a shorter launcher.
+// neither is where a `.app` may keep loadable code: `Layout.dirs().native` is, and
+// `utils/ship/signing.ts` re-signs every Mach-O in the payload by magic number
+// (ADR 0024 § A4 — M6 landed), which is most of this closure. What `native` may NOT
+// be is `Contents/Frameworks`: `codesign` reads a version-named DIRECTORY there as
+// a nested bundle and refuses the seal, which is the whole reason this file's
+// output went into `Contents/Resources/native` instead — see `layout.ts`'s darwin
+// row for the measurement and `gjsify ship darwin --sign` for what it used to
+// cost.
 //
 // WHY NOT `gjsify.ship.bundledTypelibs`. Because it FLATTENS. `plan.ts` stages
 // each such file as `posix.join(libDir, 'gi', basename(file))`, and
@@ -210,8 +213,8 @@ function resolveStagedPackage(specifier, options) {
  * NOT the published tarball. `files` in node-gi's manifest also lists `src/`,
  * `binding.gyp` and `scripts/install.mjs` — the inputs to `node-gyp`, which a
  * `.app` never runs — and the `.d.ts` declarations, which nothing inside a bundle
- * compiles against. And it lists `prebuilds/`, which this module stages into
- * `Contents/Frameworks` instead, where a `.app` keeps loadable code.
+ * compiles against. And it lists `prebuilds/`, which this module stages under
+ * `Layout.dirs().native`, the directory a `.app` keeps loadable code in.
  *
  * So the rule is what `require('@gjsify/node-gi/<subpath>')` can REACH:
  * `package.json` (the `exports` map is what resolves every subpath), every `.js`
@@ -252,7 +255,7 @@ export function appRuntimePaths(layout, identity, target) {
         addonPath: posix.join(prebuildDir, NODE_GI_ADDON_FILENAME),
         // `Contents/MacOS`, because that is where a `.app` keeps executables and
         // because `$here` — which the launcher already computes — is then the whole
-        // path expression. `Contents/Frameworks` would work for dyld and would make
+        // path expression. `dirs.native` would work for dyld and would make
         // the launcher walk back up for the one file it execs. On Windows
         // `dirs.launcher` is the program directory itself, so the interpreter lands
         // beside the `.cmd` for the same reason.

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

@@ -89,6 +89,15 @@ export declare function appImageHostRequirements(input: {
     minGjsVersion?: string;
     minNodeVersion?: string;
     namespaces: readonly string[];
+    /**
+     * The subset of {@link namespaces} the bundle marks optional (ADR 0087).
+     *
+     * An AppImage has no `Depends:` field, so "optional" cannot become a package
+     * list here — it becomes WORDING instead. That is not cosmetic: an AppRun user
+     * told a typelib is required and lacking it goes looking for another distro
+     * package, while one told it is optional reads the same sentence correctly.
+     */
+    optionalNamespaces?: readonly string[];
     bundledTypelibs?: readonly string[];
 }): string[];
 /**

package/lib/utils/ship/appimage.js

@@ -204,9 +204,10 @@ export function appDirFor(outRoot) {
  */
 export function appImageHostRequirements(input) {
     const floor = interpreterFloor(input);
+    const optional = new Set(input.optionalNamespaces ?? []);
     return [
         `${input.app} (>= ${floor})`,
-        ...hostProvidedNamespaces(input.namespaces, input.bundledTypelibs).map((ns) => `the ${ns} typelib`),
+        ...hostProvidedNamespaces(input.namespaces, input.bundledTypelibs).map((ns) => optional.has(ns) ? `the ${ns} typelib (optional)` : `the ${ns} typelib`),
     ];
 }
 /**

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

@@ -8,6 +8,16 @@ export interface DebInputs {
     prefix: string;
     /** Already-derived dependency list, in `name`/`name >= version` form. */
     depends: readonly string[];
+    /**
+     * Soft dependencies, rendered as `Recommends:`.
+     *
+     * Debian Policy § 7.2: a recommended package is installed by default and
+     * `--no-install-recommends` is the user's way out. That is what an `&optional`
+     * typelib is (ADR 0087) — the app runs without it and loses a feature — so
+     * putting it in `Depends:` would let an optional integration decide whether
+     * the package installs at all.
+     */
+    recommends?: readonly string[];
     /** Debian architecture (`amd64`, `all`, …). */
     archLabel: string;
     /** Unix seconds stamped into every header. */

package/lib/utils/ship/deb.js

@@ -104,6 +104,13 @@ function renderControl(inputs, installedSize) {
     ];
     if (inputs.depends.length > 0)
         fields.push(['Depends', inputs.depends.map(formatDebDepend).join(', ')]);
+    // After `Depends`, which is the field order dpkg-deb --control writes and the
+    // one `grep '^Depends:'` on a control file assumes. Omitted when empty rather
+    // than written as `Recommends:` with nothing after it — a field with an empty
+    // value is a parse error here, the same reason `formatDebDepend` exists.
+    if (inputs.recommends !== undefined && inputs.recommends.length > 0) {
+        fields.push(['Recommends', inputs.recommends.map(formatDebDepend).join(', ')]);
+    }
     fields.push(['Section', settings.section], ['Priority', 'optional']);
     if (settings.homepage)
         fields.push(['Homepage', settings.homepage]);

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

@@ -43,6 +43,17 @@ export declare function warnAboutNodeFloor(format: DistroFormatId, floor: string
 export interface DependsInputs {
     /** GI namespaces the bundle imports, in `Ns-Version` spelling. */
     namespaces: readonly string[];
+    /**
+     * The subset of {@link namespaces} the bundle declares OPTIONAL (ADR 0087 —
+     * `gi://Ns?version=X&optional`): a `Recommends:` entry, never a `Depends:`.
+     *
+     * Kept as its own list rather than filtered out of {@link namespaces}, because
+     * the AppImage has no package list at all and still has to SAY which of its host
+     * requirements are optional — and because a stage manifest written before the
+     * split carries no such field, where answering "everything is hard" is the safe
+     * direction.
+     */
+    optionalNamespaces?: readonly string[];
     /**
      * Whether the payload installs into `share/icons/hicolor/`.
      *
@@ -112,11 +123,34 @@ export interface DependsInputs {
  */
 export declare function hostProvidedNamespaces(namespaces: readonly string[], bundledTypelibs?: readonly string[]): string[];
 /**
- * The `Depends:` / `Requires:` list for one format.
+ * One format's dependency lists, split by how hard the requirement is.
+ *
+ * `requires` is what an absent package makes the app fail over; `recommends` is what
+ * its absence only costs. A namespace the BUNDLE marked optional (ADR 0087) is the
+ * second kind by declaration — the app's own `check()` degrades — and both `.deb`
+ * and `.rpm` have a field for it, so there is no reason to declare it hard.
+ */
+export interface DerivedDepends {
+    /** `Depends:` / `Requires:` — a package the artifact cannot run without. */
+    requires: string[];
+    /** `Recommends:` — installed by default where the format has such a field. */
+    recommends: string[];
+    /**
+     * Optional namespaces no table row is known for.
+     *
+     * REPORTED, never fatal: a `Recommends:` line for a namespace nobody mapped is
+     * the one case where saying nothing is correct — the app runs without the
+     * typelib either way, which is precisely what the flag declared. The HARD
+     * unmapped case still throws, below.
+     */
+    unmappedOptional: string[];
+}
+/**
+ * The `Depends:` / `Requires:` list for one format, plus its `Recommends:`.
  *
- * @throws when a namespace has no entry in the table — see the module header.
+ * @throws when a HARD namespace has no entry in the table — see the module header.
  */
-export declare function deriveDepends(format: DistroFormatId, inputs: DependsInputs): string[];
+export declare function deriveDepends(format: DistroFormatId, inputs: DependsInputs): DerivedDepends;
 /** One parsed dependency. `relation`/`version` are absent for an unversioned one. */
 export interface ParsedDepend {
     name: string;

package/lib/utils/ship/depends.js

@@ -287,9 +287,9 @@ export function hostProvidedNamespaces(namespaces, bundledTypelibs = []) {
     return [...new Set(namespaces)].sort().filter((ns) => !BUNDLED_TYPELIB.test(ns) && !shipped.has(ns));
 }
 /**
- * The `Depends:` / `Requires:` list for one format.
+ * The `Depends:` / `Requires:` list for one format, plus its `Recommends:`.
  *
- * @throws when a namespace has no entry in the table — see the module header.
+ * @throws when a HARD namespace has no entry in the table — see the module header.
  */
 export function deriveDepends(format, inputs) {
     // The interpreter the launcher execs, and nothing else: a package declares ONE.
@@ -297,17 +297,25 @@ export function deriveDepends(format, inputs) {
     // no system Node, so an artifact for those CARRIES one from
     // `@gjsify/node-runtime-<target>`, and that is the whole reason those three
     // packages exist and this one line is their opposite.
-    const out = inputs.interpreter === 'node'
+    const requires = inputs.interpreter === 'node'
         ? [`${NODE_PACKAGE[format]} >= ${inputs.minNodeVersion ?? DEFAULT_NODE_FLOOR}`]
         : [`gjs >= ${inputs.minGjsVersion ?? DEFAULT_GJS_FLOOR}`];
+    const recommends = [];
+    const optional = new Set(inputs.optionalNamespaces ?? []);
     const unmapped = [];
+    const unmappedOptional = [];
     for (const namespace of hostProvidedNamespaces(inputs.namespaces, inputs.bundledTypelibs)) {
         const entry = lookupTypelib(namespace, inputs.typelibPackages);
         if (entry === undefined) {
-            unmapped.push(namespace);
+            (optional.has(namespace) ? unmappedOptional : unmapped).push(namespace);
             continue;
         }
-        out.push(entry[format]);
+        // A namespace imported both ways is a HARD dependency — one importer asked
+        // for it unguarded — and a package manager field may not name it twice.
+        if (optional.has(namespace) && !requires.includes(entry[format]))
+            recommends.push(entry[format]);
+        else
+            requires.push(entry[format]);
     }
     if (unmapped.length > 0) {
         throw new Error(`gjsify ship: the bundle imports ${unmapped.map((n) => `gi://${n.split('-')[0]}`).join(', ')}, ` +
@@ -323,7 +331,7 @@ export function deriveDepends(format, inputs) {
     // The package that owns `/usr/share/icons/hicolor` — so this follows the icons, not the
     // app/cli distinction that used to stand in for them.
     if (inputs.hasIcons)
-        out.push('hicolor-icon-theme');
+        requires.push('hicolor-icon-theme');
     // The package that ships `glib-compile-schemas`, NOT `gsettings-desktop-schemas`
     // (which ships GNOME's own `org.gnome.desktop.*` schemas and has nothing to
     // do with compiling ours). Measured: `rpm -qf /usr/bin/glib-compile-schemas`
@@ -333,11 +341,15 @@ export function deriveDepends(format, inputs) {
     // `Gio.Settings.new()` aborts the app — an install that succeeds and an app
     // that does not start.
     if (inputs.hasSchemas)
-        out.push(SCHEMA_COMPILER_PACKAGE[format]);
-    out.push(...inputs.extra);
+        requires.push(SCHEMA_COMPILER_PACKAGE[format]);
+    requires.push(...inputs.extra);
     // Set-dedupe keeps first-insertion order, so the interpreter stays first and
     // the list is stable across runs.
-    return [...new Set(out)];
+    return {
+        requires: [...new Set(requires)],
+        recommends: [...new Set(recommends)].filter((name) => !requires.includes(name)),
+        unmappedOptional,
+    };
 }
 /**
  * Resolve a scanned specifier to a table row.

package/lib/utils/ship/flatpak-config.d.ts

@@ -64,3 +64,19 @@ export interface ResolvedShipFlatpak {
  * has somewhere else to point at.
  */
 export declare function resolveShipFlatpakSettings(input: ShipFlatpakInput): ResolvedShipFlatpak;
+/**
+ * Refuse a Flatpak ship that would silently drop the project's own modules.
+ *
+ * `gjsify.flatpak.modules` / `extraModules` are read by `gjsify flatpak init`
+ * only; `ship` renders exactly one module, the staged payload (ADR 0024 § 2),
+ * and the keys' absence from {@link ShipFlatpakOptions} is deliberate. The
+ * defect was the silence: a project that moved to `ship` kept the keys, got a
+ * manifest without its `extra-data` module and exit 0, and found out when the
+ * app started without the binary the module downloads. A key `ship` does not
+ * read must not be one it ignores quietly, so the run stops BEFORE the build.
+ *
+ * Called only when `flatpak` is among the formats being made: the same keys
+ * still drive `gjsify flatpak init`, and a `ship --target deb` has nothing to
+ * drop them from.
+ */
+export declare function assertNoDroppedFlatpakModules(flatpak: ConfigDataFlatpak): void;

package/lib/utils/ship/flatpak-config.js

@@ -120,6 +120,32 @@ export function resolveShipFlatpakSettings(input) {
     };
     return { settings, warnings: fromLegacy.length === 0 ? [] : [deprecationWarning(fromLegacy)] };
 }
+/**
+ * Refuse a Flatpak ship that would silently drop the project's own modules.
+ *
+ * `gjsify.flatpak.modules` / `extraModules` are read by `gjsify flatpak init`
+ * only; `ship` renders exactly one module, the staged payload (ADR 0024 § 2),
+ * and the keys' absence from {@link ShipFlatpakOptions} is deliberate. The
+ * defect was the silence: a project that moved to `ship` kept the keys, got a
+ * manifest without its `extra-data` module and exit 0, and found out when the
+ * app started without the binary the module downloads. A key `ship` does not
+ * read must not be one it ignores quietly, so the run stops BEFORE the build.
+ *
+ * Called only when `flatpak` is among the formats being made: the same keys
+ * still drive `gjsify flatpak init`, and a `ship --target deb` has nothing to
+ * drop them from.
+ */
+export function assertNoDroppedFlatpakModules(flatpak) {
+    const dropped = ['modules', 'extraModules'].filter((key) => (flatpak[key]?.length ?? 0) > 0);
+    if (dropped.length === 0)
+        return;
+    const list = dropped.map((key) => `gjsify.flatpak.${key}`).join(' and ');
+    throw new Error(`gjsify ship: ${list} ${dropped.length > 1 ? 'are' : 'is'} set, but the \`flatpak\` target renders ` +
+        'ONE module, the staged payload, and would drop ' +
+        `${dropped.length > 1 ? 'them' : 'it'} (ADR 0024 § 2). Build this Flatpak with ` +
+        '`gjsify flatpak init` + `gjsify flatpak build`, which honour the key, or leave `flatpak` out of ' +
+        '`--target` / `gjsify.ship.targets`.');
+}
 /** One line, naming every key still read from the old block and where each goes. */
 function deprecationWarning(keys) {
     const list = keys.map((key) => `gjsify.flatpak.${key}`).join(', ');

package/lib/utils/ship/formats.js

@@ -132,12 +132,14 @@ function macosArch(arch, _archIndependent) {
 /**
  * `process.arch` → the name Windows and everything that targets it use.
  *
- * ONE ROW, and it is not caution: `wingtk/gvsbuild` hardcodes
- * `self.platform = "x64"` and publishes no arm64 GTK, so there is nothing to build
- * `@gjsify/gtk-runtime-win32-arm64` out of and no GTK for a Windows/ARM artifact
- * to load (#1117). `Layout.arches` refuses the same value one phase earlier, at
- * stage time, with that reason spelled out; this table is the second half — the
- * one that stops a stage assembled by an older gjsify from acquiring a label here.
+ * ONE ROW, and it is not caution: there is no arm64 GTK CLOSURE to put on it yet.
+ * `wingtk/gvsbuild` publishes no arm64 assets, which is why ADR 0089 builds that
+ * prefix from our `gjsify/gvsbuild` fork in CI instead — but what a Windows
+ * artifact stages is `@gjsify/gtk-runtime-*`, and the arm64 one is not built, so
+ * there is nothing for a Windows/ARM artifact to load (#1117). `Layout.arches`
+ * refuses the same value one phase earlier, at stage time, with that reason spelled
+ * out; this table is the second half — the one that stops a stage assembled by an
+ * older gjsify from acquiring a label here.
  *
  * `x64` maps to itself, and unlike the macOS table that is not a coincidence to be
  * caught later: `x64` is the spelling Node's own release archives use
@@ -734,7 +736,8 @@ export const FORMATS = {
     //   * there is no `Info.plist` and no metadata file at all: what a Windows
     //     installer says about an application lives in the `.msi`'s own tables
     //     (#1354 M5), which is why `Layout.metadata` answers `[]` here.
-    //   * `x64` alone, and the blocker is upstream — see `WINDOWS_ARCH`.
+    //   * `x64` alone, and the blocker is a package of ours we have not built —
+    //     see `WINDOWS_ARCH`.
     //
     // NEITHER IS SIGNED BY DEFAULT, and Windows is the softer of the two asymmetries
     // ADR 0024 § A5 records: Gatekeeper BLOCKS an unsigned `.app`, while SmartScreen

package/lib/utils/ship/gi-namespaces.d.ts

@@ -1,7 +1,23 @@
+/**
+ * What a bundle loads, split by whether the host must provide it.
+ *
+ * `namespaces` is the union — the same answer {@link scanGiNamespaces} has always
+ * given — and `optional` is the subset the artifact itself marks optional. A namespace
+ * in both is still a hard dependency as far as anything else is concerned: the
+ * importer asked for it both ways, and only one of those edges degrades.
+ */
+export interface GiRequirements {
+    /** Every GI namespace the bundle loads, `Ns-Version` where a specifier pins one. */
+    namespaces: string[];
+    /** The subset carrying the bundler's optional marker — absent is not fatal. */
+    optional: string[];
+}
 /**
  * Extract the GI namespaces a bundle imports, as `Ns-Version` when the
  * specifier pins one and bare `Ns` when it does not.
  */
 export declare function scanGiNamespaces(source: string): string[];
+/** {@link scanGiNamespaces}, plus which of them the artifact marks optional (ADR 0087). */
+export declare function scanGiRequirements(source: string): GiRequirements;
 /** `gi://Gtk?version=4.0` → `Gtk-4.0`; `gi://Gtk` → `Gtk`; anything else → null. */
 export declare function parseGiSpecifier(specifier: string): string | null;