@gjsify/cli 0.46.0 → 0.48.0

package/lib/utils/ship/entry-interpreter.d.ts

@@ -0,0 +1,44 @@
+import type { HostOs } from './types.js';
+/** What a shipped artifact's `bin/<name>` can exec. */
+export type ShipInterpreter = 'gjs' | 'node';
+/** The specifiers in an entry that only ONE of the two hosts can resolve. */
+export interface EntryEvidence {
+    /** `gi://…` and the bare GJS built-ins — resolvable under GJS, refused by node. */
+    gi: string[];
+    /** `node:…` specifiers — resolvable under Node, refused by GJS's loader. */
+    node: string[];
+}
+/** Host-only specifiers of `source`, deduplicated and sorted. */
+export declare function entryEvidence(source: string): EntryEvidence;
+/** Everything the refusal names, so it can point at the key that decides each half. */
+export interface EntryCheckInput {
+    /** The resolved interpreter of THIS target. */
+    interpreter: ShipInterpreter;
+    /** The entry's source, as it will be installed. */
+    source: string;
+    /** How the entry is spelled in the project, for the message. */
+    entry: string;
+    /** The config key the interpreter came from — `gjsify.app` or `gjsify.ship.app.<os>`. */
+    appKey: string;
+    /** The config key the entry came from — `gjsify.main`, `gjsify.ship.bundle[.<os>]`, … */
+    bundleKey: string;
+    /**
+     * The layout being assembled, which is the key a per-target fix goes under.
+     *
+     * {@link HostOs} and not `string`: an OS spelling this command does not
+     * assemble for is the silent defect the two resolvers refuse by name, and a
+     * message that offers `gjsify.ship.bundle.<whatever-was-passed>` as the fix
+     * would be the one place that hands the reader the typo back.
+     */
+    layoutOs: HostOs;
+}
+/**
+ * Refuse a payload the target's own interpreter cannot load.
+ *
+ * ASYMMETRIC LIKE `assertLauncherMatchesInterpreter`, and for the same reason:
+ * evidence FOR the wrong host is a refusal, absence of evidence is not. A bundle
+ * that imports neither scheme — a pure-JS CLI, a bundle whose GI reach is all
+ * dynamic — passes, because nothing here observed a contradiction. This function
+ * reports what it read, never what it failed to read.
+ */
+export declare function assertEntryRunsUnder(input: EntryCheckInput): void;

package/lib/utils/ship/entry-interpreter.js

@@ -0,0 +1,109 @@
+// Can the interpreter this target execs load the entry this target ships?
+//
+// THE DEFECT (#1545, measured on a React-Native-on-GTK application at 0.47.0).
+// `gjsify ship` chose the runtime and the payload independently and never
+// compared them. `gjsify.ship.app.darwin: "node"` made the `.app`'s launcher
+// `exec node`, while the payload came from the project's `main`, which for a
+// project whose primary target is Linux is its `--app gjs` bundle. The run
+// printed one line on the subject and it read as CONFIRMATION —
+// "runtime for darwin: node — `gjsify.ship.app.darwin` overrides `gjsify.app`" —
+// then produced an artifact that dies before a line of application code:
+//
+//     Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only URLs with a scheme in: file,
+//     data, and node are supported by the default ESM loader. Received protocol 'gi:'
+//
+// So the artifact is built, reported as built, and cannot start. That is the
+// class this repository pays most for: a step that reports success while having
+// measured nothing.
+//
+// THE DISCRIMINATOR IS THE SPECIFIER THE OTHER HOST'S LOADER REFUSES, and it is
+// exact in both directions — measured on this machine, GJS 1.86 / Node 24:
+//
+//     node   ← `import … from 'gi://Gtk?version=4.0'`
+//              ERR_UNSUPPORTED_ESM_URL_SCHEME … Received protocol 'gi:'
+//     node   ← `import system from 'system'`
+//              ERR_MODULE_NOT_FOUND — a GJS built-in is not a package
+//     gjs    ← `import … from 'node:fs'`
+//              ImportError: Unsupported URI scheme for importing: node
+//
+// None is a heuristic about how the bundle was built: it is the specifier the
+// running loader rejects, read out of the file that will be installed. And none
+// can appear in a bundle the OTHER target built for itself — `--app node`
+// rewrites every `gi://` into `requireGi()` and every bare GJS built-in into an
+// `@gjsify/node-gi` shim (`gjs-gi-node.ts`), `--app gjs` resolves every `node:`
+// builtin to its `@gjsify/*` implementation — so the evidence is present exactly
+// when the pair is wrong.
+//
+// THE BARE BUILT-INS ARE NOT DECORATION. A GJS bundle that reaches GI through the
+// legacy `imports.gi` object carries no `gi://` at all, and a `--app gjs` build of
+// one imports `system` and nothing else this reader would have seen — so #1545's
+// own pair (a GJS payload under a node launcher) passed the guard written for it
+// until they were added. What is deliberately NOT read is the ambient `imports`
+// object itself: node fails on it at the first USE, not at load, so a refusal
+// citing it would be making a claim this file cannot keep.
+//
+// WHY A REFUSAL AND NOT A WARNING. There is no reading of this artifact under
+// which it works. A warning at the end of a `ship` run competes with the
+// artifact path printed beside it, and the artifact is what gets uploaded.
+import { importedSpecifier, walkModuleAst } from '../cli-runtime-closure.js';
+/**
+ * The GJS built-in modules, which are bare specifiers rather than a scheme.
+ *
+ * `cairo` is deliberately absent: it is also an ordinary npm package name, so a
+ * node bundle can legitimately import it and refusing that would fail a working
+ * artifact. `system` and `gettext` have no npm counterpart a real project
+ * imports, which is what makes them evidence rather than a guess.
+ */
+const GJS_BUILTINS = new Set(['system', 'gettext']);
+/** Host-only specifiers of `source`, deduplicated and sorted. */
+export function entryEvidence(source) {
+    const gi = new Set();
+    const node = new Set();
+    walkModuleAst(source, (astNode) => {
+        const specifier = importedSpecifier(astNode);
+        if (specifier === null)
+            return;
+        if (specifier.startsWith('gi://') || GJS_BUILTINS.has(specifier))
+            gi.add(specifier);
+        else if (specifier.startsWith('node:'))
+            node.add(specifier);
+    });
+    return { gi: [...gi].sort(), node: [...node].sort() };
+}
+/**
+ * Refuse a payload the target's own interpreter cannot load.
+ *
+ * ASYMMETRIC LIKE `assertLauncherMatchesInterpreter`, and for the same reason:
+ * evidence FOR the wrong host is a refusal, absence of evidence is not. A bundle
+ * that imports neither scheme — a pure-JS CLI, a bundle whose GI reach is all
+ * dynamic — passes, because nothing here observed a contradiction. This function
+ * reports what it read, never what it failed to read.
+ */
+export function assertEntryRunsUnder(input) {
+    const evidence = entryEvidence(input.source);
+    const refused = input.interpreter === 'node' ? evidence.gi : evidence.node;
+    if (refused.length === 0)
+        return;
+    const other = input.interpreter === 'node' ? 'gjs' : 'node';
+    // The error the reader will actually see, which differs WITHIN the node case:
+    // a `gi:` specifier is refused as an unknown URL scheme, a bare GJS built-in
+    // as a package that does not exist. Naming the wrong one sends them looking
+    // for the wrong thing in a log they have not opened yet.
+    const loader = input.interpreter === 'gjs'
+        ? 'GJS\'s loader refuses it: ImportError, "Unsupported URI scheme for importing: node"'
+        : refused.some((specifier) => specifier.startsWith('gi://'))
+            ? 'node\'s ESM loader refuses it: ERR_UNSUPPORTED_ESM_URL_SCHEME, "Only URLs with a scheme in: ' +
+                'file, data, and node are supported by the default ESM loader"'
+            : "node's ESM loader refuses it: ERR_MODULE_NOT_FOUND — a GJS built-in is not a package";
+    const shown = refused.slice(0, 3).join(', ');
+    const more = refused.length > 3 ? `, and ${refused.length - 3} more` : '';
+    throw new Error(`gjsify ship: this target execs \`${input.interpreter}\` (\`${input.appKey}\`), and the entry it ` +
+        `would ship — ${input.entry} (\`${input.bundleKey}\`) — imports ${shown}${more}.\n` +
+        `    ${loader}, before a line of application code runs.\n` +
+        '    The artifact would be built, reported as built, and fail at launch on every machine.\n' +
+        `    Either ship this target the \`--app ${input.interpreter}\` build of the app — ` +
+        `\`gjsify.ship.bundle.${input.layoutOs}\` selects the entry per target, the way ` +
+        `\`gjsify.ship.app.${input.layoutOs}\` selects the runtime —\n` +
+        `    or set \`gjsify.ship.app.${input.layoutOs}\` to "${other}" if this bundle is the one ` +
+        'that should ship.');
+}

package/lib/utils/ship/formats.js

@@ -275,6 +275,11 @@ export const FORMATS = {
         // /usr/share/doc/<package>/copyright, and lintian errors without it.
         licenseDest: (binaryName) => `share/doc/${binaryName}/copyright`,
         licenseKind: 'debian-copyright',
+        // Debian Policy § 4.4. `.Debian` and not plain `changelog` because
+        // `deb.ts` writes `Version: <version>-<release>`, i.e. a Debian
+        // revision, i.e. a non-native package — which is the half of lintian's
+        // `no-changelog … (non-native package)` that names the FILE.
+        changelogDest: (binaryName) => `share/doc/${binaryName}/changelog.Debian.gz`,
         archName: debArch,
         fileName: (s, archLabel) => `${s.binaryName}_${s.version}-${s.release}_${archLabel}.deb`,
         artifactKind: 'file',

package/lib/utils/ship/gi-namespaces.js

@@ -1,10 +1,24 @@
 // Which GI namespaces does this bundle actually load?
 //
-// Read off the emitted `--app gjs` bundle, because that is the file that gets
-// installed. `gi://` is a real module protocol under GJS, so the bundler keeps
-// those specifiers in the output verbatim (`rolldown-plugin-gjsify`'s externals
-// plugin) — the artifact carries its own dependency list and nothing has to be
-// declared twice.
+// Read off the EMITTED bundle, because that is the file that gets installed —
+// and the emitted form is not one form but two, which is the correction this
+// header carries. Under `--app gjs`, `gi://` is a real module protocol, so the
+// bundler keeps those specifiers in the output verbatim
+// (`rolldown-plugin-gjsify`'s externals plugin) and the artifact carries its own
+// dependency list. Under `--app node` there is no such protocol:
+// `gjsGiNodePlugin` rewrites every `gi://Ns?version=X` into a shim whose body is
+// `require('@gjsify/node-gi/gi').requireGi("Ns", "X")`, so the specifier this
+// scanner was written to find is gone from the file by construction.
+//
+// WHAT THAT COST, and why reading one form is not "mostly right": these
+// namespaces are what `depends.ts` maps to `gir1.2-gtk-4.0` and friends
+// (ADR 0024 § 6). A `--app node` project therefore derived an EMPTY typelib
+// dependency set — the package installed cleanly and died at its first GI call,
+// which is the same failure the bare-side-effect-import fix below was written to
+// prevent, arriving again through the other build target. Nothing caught it
+// because every ship fixture's "node bundle" was hand-written with `gi://`
+// imports in it: a shape `gjsify build --app node` cannot emit and node cannot
+// run.
 //
 // PARSED, not pattern-matched, and the first version of this file is why. A
 // regex over the bundle text got it wrong in both directions at once:
@@ -17,18 +31,65 @@
 //     `from`, and since an unmapped namespace fails the build, that made a
 //     correct project unbuildable.
 //
-// `moduleSpecifiers` answers the question exactly, and it is the same acorn
-// pass the CLI already uses to compute its own runtime closure — so there is
-// one definition of "what does this file import" rather than two.
-import { moduleSpecifiers } from '../cli-runtime-closure.js';
+// `walkModuleAst` answers both questions in ONE pass, and it is the same acorn
+// pass the CLI already uses to compute its own runtime closure — so there is one
+// definition of "what does this file import" rather than two.
+import { importedSpecifier, staticStringValue, walkModuleAst, } from '../cli-runtime-closure.js';
+/** The module a `--app node` bundle reaches GI through. */
+const NODE_GI_MODULE = '@gjsify/node-gi/gi';
+/** Namespaces are GI identifiers; anything else is a call this reader misread. */
+const NAMESPACE = /^[A-Za-z][A-Za-z\d_]*$/;
 /**
  * Extract the GI namespaces a bundle imports, as `Ns-Version` when the
  * specifier pins one and bare `Ns` when it does not.
  */
 export function scanGiNamespaces(source) {
     const found = new Set();
-    for (const specifier of moduleSpecifiers(source)) {
-        const key = parseGiSpecifier(specifier);
+    // TWO SETS, because the two kinds of binding are not interchangeable and
+    // treating them as one over-approximated on a real minified bundle. A
+    // namespace object (`import * as gi`) and a required module object are only
+    // ever the OBJECT of `.requireGi(…)`: calling a module namespace is a
+    // TypeError, so a bare `gi(…)` is never one of ours. Only `requireGi` itself
+    // — the named import, or the default export, which IS `requireGi` — is
+    // callable on its own.
+    //
+    // Measured on `gjsify build --app node` (minify is the DEFAULT): a file with
+    // `import * as gi from '@gjsify/node-gi/gi'` and a callback parameter emitted
+    // as `function render(e,t){return e(t)+e(\`Zzqfoo\`)}` — where the minifier
+    // gave the import and the parameter the SAME short name in different scopes.
+    // Read as one set, `e(\`Zzqfoo\`)` became the namespace `Zzqfoo`, and
+    // `deriveDepends` then refused to package a correct project.
+    const callable = new Set();
+    const objects = new Set();
+    const calls = [];
+    walkModuleAst(source, (node) => {
+        const specifier = importedSpecifier(node);
+        if (specifier !== null) {
+            const key = parseGiSpecifier(specifier);
+            if (key !== null)
+                found.add(key);
+            if (node.type === 'ImportDeclaration' && specifier === NODE_GI_MODULE) {
+                collectNodeGiBindings(node, callable, objects);
+            }
+            return;
+        }
+        if (node.type === 'VariableDeclarator' && loadsNodeGiModule(node.init)) {
+            const id = node.id;
+            // An OBJECT: `const gi = require('@gjsify/node-gi/gi')` is the module,
+            // reached as `gi.requireGi(…)` and never called directly.
+            if (id?.type === 'Identifier' && typeof id.name === 'string')
+                objects.add(id.name);
+            return;
+        }
+        // Collected rather than resolved in place: a call can precede the
+        // `require` that binds its callee (the shim's `load()` is hoisted above
+        // nothing, but a minifier is free to reorder declarations), so the
+        // binding set has to be complete before any call is judged.
+        if (node.type === 'CallExpression')
+            calls.push(node);
+    });
+    for (const call of calls) {
+        const key = requireGiNamespace(call, callable, objects);
         if (key !== null)
             found.add(key);
     }
@@ -40,10 +101,112 @@ export function parseGiSpecifier(specifier) {
         return null;
     const rest = specifier.slice('gi://'.length);
     const [namespace, query] = rest.split('?', 2);
-    if (namespace === undefined || !/^[A-Za-z][A-Za-z0-9_]*$/.test(namespace))
+    if (namespace === undefined || !NAMESPACE.test(namespace))
         return null;
     if (query === undefined)
         return namespace;
     const version = /(?:^|&)version=([^&]+)/.exec(query)?.[1];
     return version === undefined ? namespace : `${namespace}-${version}`;
 }
+/**
+ * What an `import … from '@gjsify/node-gi/gi'` binds, split by what it can BE.
+ *
+ * All three spellings appear in real code and the default export IS `requireGi`
+ * (`packages/node-gi/node-gi/gi.d.ts`), so the named import (under any local
+ * name — `import { requireGi as gi }` renames it) and the default import are
+ * CALLABLE. A namespace import is not: calling a module namespace object throws,
+ * so it can only ever be the object of `.requireGi(…)`, and putting it in the
+ * callable set is what let a minified callback parameter of the same name be
+ * read as a `requireGi` call.
+ */
+function collectNodeGiBindings(node, callable, objects) {
+    const specifiers = node.specifiers ?? [];
+    for (const specifier of specifiers) {
+        const local = specifier.local;
+        if (local?.type !== 'Identifier' || typeof local.name !== 'string')
+            continue;
+        const imported = specifier.imported;
+        if (specifier.type === 'ImportNamespaceSpecifier')
+            objects.add(local.name);
+        else if (specifier.type === 'ImportDefaultSpecifier')
+            callable.add(local.name);
+        else if (imported?.type === 'Identifier' && imported.name === 'requireGi')
+            callable.add(local.name);
+    }
+}
+/**
+ * A call that LOADS `@gjsify/node-gi/gi` — recognised by its argument, never by
+ * the name of the callee.
+ *
+ * THE CALLEE NAME DOES NOT SURVIVE BUNDLING, and reading it is how the first cut
+ * of this function passed its own tests while answering `[]` for every real
+ * artifact. Measured on `gjsify build --app node` output for a two-import app,
+ * which is the exact input this module exists to read:
+ *
+ *     unminified   const require$1 = createRequire(import.meta.url);
+ *                  … require$1("@gjsify/node-gi/gi").requireGi("Gtk", "4.0")
+ *     minified     const n = e(import.meta.url);
+ *                  … n(`@gjsify/node-gi/gi`).requireGi(`Gtk`, `4.0`)
+ *
+ * Two shims in one bundle means two `require` bindings, so the second is renamed
+ * even without `--minify` (which is the DEFAULT). A reader keyed on the
+ * identifier `require` therefore loses one namespace unminified and both
+ * minified — silently, since an empty namespace list is a legal answer.
+ *
+ * The module STRING is what survives every rename, and it is a precise
+ * discriminator: a call taking `'@gjsify/node-gi/gi'` as its first argument is a
+ * load of that module under any name a bundler gives the loader.
+ */
+function loadsNodeGiModule(node) {
+    if (!node || typeof node !== 'object')
+        return false;
+    const call = node;
+    if (call.type !== 'CallExpression')
+        return false;
+    const args = call.arguments ?? [];
+    return staticStringValue(args[0]) === NODE_GI_MODULE;
+}
+/**
+ * The namespace a `requireGi(…)` call names, or `null` when this is not one.
+ *
+ * BINDING-TRACED rather than name-matched, and the asymmetry is deliberate: a
+ * bare `.requireGi(…)` on any object would over-approximate, and
+ * over-approximating is NOT the harmless direction here — an unmapped namespace
+ * fails the build, so a foreign method sharing the name would make a correct
+ * project unpackageable. Every accepted shape traces back to an import or
+ * require of `@gjsify/node-gi/gi` in this same file, which is what a bundle
+ * always has: the shim carries its own `require`, and a hand-written node-gi app
+ * carries its own import.
+ *
+ * Shadowing is the one gap left, and the split above is what makes it small.
+ * This reader has no scope analysis, so a local binding that reuses the name of
+ * the CALLABLE import — `requireGi` itself, or the default import — and is called
+ * with a GI-shaped string literal would still be read as one. A minifier can
+ * manufacture exactly that collision, which is why the two shapes it produces
+ * most (the namespace object and the required module object) are the two that no
+ * longer count as callees.
+ */
+function requireGiNamespace(call, callable, objects) {
+    const callee = call.callee;
+    let reached = false;
+    if (callee?.type === 'Identifier') {
+        reached = typeof callee.name === 'string' && callable.has(callee.name);
+    }
+    else if (callee?.type === 'MemberExpression' && callee.computed !== true) {
+        const property = callee.property;
+        if (property?.type !== 'Identifier' || property.name !== 'requireGi')
+            return null;
+        const object = callee.object;
+        reached =
+            loadsNodeGiModule(object) ||
+                (object?.type === 'Identifier' && typeof object.name === 'string' && objects.has(object.name));
+    }
+    if (!reached)
+        return null;
+    const args = call.arguments ?? [];
+    const namespace = staticStringValue(args[0]);
+    if (namespace === null || !NAMESPACE.test(namespace))
+        return null;
+    const version = staticStringValue(args[1]);
+    return version === null ? namespace : `${namespace}-${version}`;
+}

package/lib/utils/ship/layout.js

@@ -125,7 +125,9 @@ export const LAYOUTS = {
             'macOS is CoreText-backed and GTK is not built against fontconfig there. That the activation ' +
             "reaches Pango's CoreText font map is UNVERIFIED: no leg in this repository runs a `.app`. " +
             'Confirm with `PangoCairo.FontMap.get_default().list_families()` in the shipped bundle, and ' +
-            '`PANGOCAIRO_BACKEND=bogus` to print which backend it was built with.',
+            '`PANGOCAIRO_BACKEND=bogus` to print which backend it was built with. An app that calls ' +
+            '`initFonts()` from `@gjsify/gtk-host/fonts` for the Windows row needs no branch around it: the ' +
+            'CoreText map answers G_IO_ERROR_NOT_SUPPORTED and that call deliberately does nothing here.',
         launcherExt: '',
         root: appBundleDir,
         // Apple's, all four. `Contents/MacOS` holds executables, `Contents/Resources`
@@ -230,9 +232,11 @@ export const LAYOUTS = {
             'W1-W5): a FONTCONFIG_FILE naming the staged directory moves the default font map by nothing ' +
             'even when it is the ONLY configuration present — that map does not read fontconfig, and exposes ' +
             'no config_changed or set_config with which to make it — while add_font_file on the same map a ' +
-            'Gtk.Label renders through does register the family. So register them at startup: ' +
-            '`PangoCairo.FontMap.get_default().add_font_file(path)` (Pango 1.56+, in the typelib), or the ' +
-            'app renders in a substituted family with no error.',
+            'Gtk.Label renders through does register the family. So register them at startup, with one call ' +
+            "from the GTK host layer: `import { initFonts } from '@gjsify/gtk-host/fonts'`, then `initFonts()` " +
+            'before the first window — it reads GJSIFY_FONT_DIR itself, registers every face it holds, and ' +
+            'no-ops on the operating systems that already activated them. Without it the app renders in a ' +
+            'substituted family with no error.',
         // `.cmd`, not `.bat`: the two differ in whether a failing built-in (`set`,
         // `path`, `append`) sets ERRORLEVEL, and `.cmd` is the one where it does.
         launcherExt: '.cmd',

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

@@ -11,6 +11,10 @@ export interface StageInputs {
     desktopEntry?: string;
     /** Contents of the project's licence file, when one was found. */
     licenseText?: string;
+    /** Contents of the project's own changelog, when one was found. */
+    changelogText?: string;
+    /** The build stamp every header and every rendered file shares — the changelog's date. */
+    mtime: number;
 }
 /**
  * Build the prefix-relative payload.
@@ -46,7 +50,7 @@ export declare function planStage(settings: ShipSettings, inputs: StageInputs):
  * missing `LICENSE` — actually is; {@link assertOverlayIsLicensed} repeats it at
  * pack time for a stage that arrived from somewhere else.
  */
-export declare function planOverlay(settings: ShipSettings, format: FormatDescriptor, inputs: StageInputs): StagedFile[];
+export declare function planOverlay(settings: ShipSettings, format: FormatDescriptor, inputs: StageInputs): Promise<StagedFile[]>;
 /**
  * The same refusal, at pack time.
  *

package/lib/utils/ship/plan.js

@@ -2,6 +2,8 @@
 // case (including the ones that must be REFUSED) is unit-testable. Same split
 // 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 { renderDebianChangelog } from './changelog.js';
+import { gzipDeterministic } from './gzip.js';
 import { renderMimePackage } from './mime.js';
 import { SHARE } from './share-dirs.js';
 import { basename, extname, posix } from 'node:path';
@@ -152,7 +154,7 @@ function planFonts(settings) {
  * missing `LICENSE` — actually is; {@link assertOverlayIsLicensed} repeats it at
  * pack time for a stage that arrived from somewhere else.
  */
-export function planOverlay(settings, format, inputs) {
+export async function planOverlay(settings, format, inputs) {
     if (inputs.licenseText === undefined) {
         throw new Error(`gjsify ship: no licence file found, so the ${format.id} package would ship no ` +
             `${format.licenseDest(settings.binaryName)}. Debian Policy § 12.5 requires it and lintian ` +
@@ -163,7 +165,24 @@ export function planOverlay(settings, format, inputs) {
     const text = format.licenseKind === 'debian-copyright'
         ? renderDebianCopyright(settings, inputs.licenseText)
         : inputs.licenseText;
-    return [{ path: format.licenseDest(settings.binaryName), mode: 0o644, source: { kind: 'text', text } }];
+    const files = [
+        { path: format.licenseDest(settings.binaryName), mode: 0o644, source: { kind: 'text', text } },
+    ];
+    // COMPRESSED HERE, not at pack time, and that is what makes the two-phase
+    // handoff sound: `--from-stage` rehydrates the overlay out of the sidecar and
+    // packs it, so the assembling host's bytes have to BE the shipped bytes. A
+    // gzip performed on the packing host would put a second compressor's output in
+    // an artifact whose every other byte came from the first. `gzipDeterministic`
+    // zeroes the header stamp for the usual reason (utils/ship/gzip.ts).
+    if (format.changelogDest !== undefined) {
+        const changelog = renderDebianChangelog(settings, inputs.changelogText, inputs.mtime);
+        files.push({
+            path: format.changelogDest(settings.binaryName),
+            mode: 0o644,
+            source: { kind: 'bytes', data: await gzipDeterministic(new TextEncoder().encode(changelog)) },
+        });
+    }
+    return files;
 }
 /**
  * The same refusal, at pack time.

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

@@ -37,6 +37,7 @@ export interface DiscoveredPayload {
     /** Absolute paths of the font faces the application ships itself. */
     fontFiles: string[];
     licenseFile?: string;
+    changelogFile?: string;
 }
 export interface SettingsInput {
     projectDir: string;
@@ -144,13 +145,58 @@ export interface ResolvedSettings {
     warnings: string[];
 }
 export declare function resolveShipSettings(input: SettingsInput): ResolvedSettings;
-/** The bundle path a project declares, in the order the rest of the CLI reads them. */
-export declare function declaredBundlePath(pkg: ShipPackageManifest, ship: ConfigDataShip): string | undefined;
+/** The entry one ship target installs, which key named it, and what it must NOT carry. */
+export interface ResolvedShipBundle {
+    /** The declared path as written — project-relative or absolute. */
+    declared?: string;
+    /** 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 entries OTHER targets declared, as written.
+     *
+     * Not decoration: `discoverPayload` stages the whole directory the entry
+     * lives in, so a project that keeps `dist/app.gjs.mjs` beside
+     * `dist/app.node.mjs` ships both to both targets. One of them is a bundle
+     * that target's interpreter cannot load, in an artifact advertising that it
+     * can — and on macOS it is inside the signed bundle.
+     */
+    foreign: string[];
+}
+/**
+ * The ONE place a ship target's ENTRY is decided — {@link resolveShipApp}'s twin.
+ *
+ * The two are twins because they answer one question between them, and #1545 is
+ * what answering only half of it costs: `gjsify.ship.app.darwin: "node"` moved
+ * the launcher to `node` while the payload stayed `gjsify.main`, which for a
+ * project whose primary target is Linux is its `--app gjs` bundle. Both keys
+ * were honoured, they contradicted each other, and the `.app` died on its first
+ * import with the only line of output on the subject reading as confirmation.
+ *
+ * A DECLARATION rather than a derivation, and both alternatives were considered
+ * where the issue raised them. Deriving the entry from the runtime by filename
+ * convention (`app.node.mjs` beside `app.gjs.mjs`) is a heuristic on an output
+ * name the project owns — the same guess `tests/e2e/ship`'s fixture exists to
+ * refuse. Having ship invoke `gjsify build --app <runtime>` itself cannot work
+ * for the phase that needs it most: `--from-stage` packs on a host with no
+ * project, no bundler and no sources (ADR 0024 § A2).
+ *
+ * Fall-through, not requirement: a target with no key keeps `gjsify.main`, so
+ * every single-host project is unaffected and nothing new is mandatory.
+ */
+export declare function resolveShipBundle(input: {
+    pkg: ShipPackageManifest;
+    ship: ConfigDataShip;
+    layoutOs: HostOs;
+}): ResolvedShipBundle;
 /** npm package name → a package/binary name both dpkg and rpm accept. */
 export declare function deriveBinaryName(pkgName: string | undefined): string;
 /** AppStream description (string or blocks) → plain paragraphs for deb/rpm. */
 export declare function descriptionParagraphs(description: string | Array<DescriptionBlock | string> | undefined): string[] | undefined;
 /** `LICENSE`, `LICENSE.md`, … — the names a licence file actually has. */
 export declare const LICENSE_FILE_NAMES: readonly ["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING", "COPYING.md"];
+/** `CHANGELOG.md`, … — the names a project's own changelog actually has. */
+export declare const CHANGELOG_FILE_NAMES: readonly ["CHANGELOG.md", "CHANGELOG", "CHANGELOG.txt", "NEWS.md", "NEWS"];
 /** The bundle's own basename, used as the launcher's exec target. */
 export declare function bundleEntryName(bundlePath: string): string;

package/lib/utils/ship/settings.js

@@ -177,6 +177,7 @@ export function resolveShipSettings(input) {
         description,
         license,
         licenseFile: discovered.licenseFile,
+        changelogFile: discovered.changelogFile,
         homepage: metadata.homepageUrl ?? pkg.homepage,
         section: ship.section ?? sections.section,
         group: ship.group ?? sections.group,
@@ -203,9 +204,66 @@ export function resolveShipSettings(input) {
     };
     return { settings, metadata, warnings };
 }
-/** The bundle path a project declares, in the order the rest of the CLI reads them. */
-export function declaredBundlePath(pkg, ship) {
-    return ship.bundle ?? pkg.gjsify?.main ?? pkg.main;
+/**
+ * The ONE place a ship target's ENTRY is decided — {@link resolveShipApp}'s twin.
+ *
+ * The two are twins because they answer one question between them, and #1545 is
+ * what answering only half of it costs: `gjsify.ship.app.darwin: "node"` moved
+ * the launcher to `node` while the payload stayed `gjsify.main`, which for a
+ * project whose primary target is Linux is its `--app gjs` bundle. Both keys
+ * were honoured, they contradicted each other, and the `.app` died on its first
+ * import with the only line of output on the subject reading as confirmation.
+ *
+ * A DECLARATION rather than a derivation, and both alternatives were considered
+ * where the issue raised them. Deriving the entry from the runtime by filename
+ * convention (`app.node.mjs` beside `app.gjs.mjs`) is a heuristic on an output
+ * name the project owns — the same guess `tests/e2e/ship`'s fixture exists to
+ * refuse. Having ship invoke `gjsify build --app <runtime>` itself cannot work
+ * for the phase that needs it most: `--from-stage` packs on a host with no
+ * project, no bundler and no sources (ADR 0024 § A2).
+ *
+ * Fall-through, not requirement: a target with no key keeps `gjsify.main`, so
+ * every single-host project is unaffected and nothing new is mandatory.
+ */
+export function resolveShipBundle(input) {
+    const declaredTable = input.ship.bundle;
+    const perTarget = typeof declaredTable === 'object' && declaredTable !== null ? declaredTable : {};
+    // The WHOLE table, for the reason `resolveShipApp` gives: a mis-keyed
+    // override is silent by construction, so the run that must report `windows`
+    // is the one assembling some OTHER layout.
+    for (const os of Object.keys(perTarget)) {
+        if (Object.hasOwn(SHIP_APP_OSES, os))
+            continue;
+        throw new Error(`gjsify ship: \`gjsify.ship.bundle.${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. An entry under a key nothing reads leaves that target on " +
+            '`gjsify.main` with nothing to say so.');
+    }
+    const projectWide = typeof declaredTable === 'string' ? declaredTable : undefined;
+    const fallback = input.pkg.gjsify?.main ?? input.pkg.main;
+    const entryFor = (os) => perTarget[os] ?? projectWide ?? fallback;
+    const override = perTarget[input.layoutOs];
+    const declared = entryFor(input.layoutOs);
+    const key = override !== undefined
+        ? `gjsify.ship.bundle.${input.layoutOs}`
+        : projectWide !== undefined
+            ? 'gjsify.ship.bundle'
+            : input.pkg.gjsify?.main !== undefined
+                ? 'gjsify.main'
+                : 'main';
+    // RESOLVED per OS, not read off the table — because the entry another target
+    // ships is as often the FALL-THROUGH as it is a declared one, and that is
+    // #1545's own project shape: `main` is the GJS bundle, only darwin declares
+    // its own, and reading the table alone leaves the GJS bundle sitting inside
+    // the signed `.app` with nothing to name it. When nothing is keyed per OS
+    // every target resolves the same entry and this set is empty by construction.
+    const foreign = [
+        ...new Set(Object.keys(SHIP_APP_OSES)
+            .filter((os) => os !== input.layoutOs)
+            .map(entryFor)
+            .filter((entry) => entry !== undefined && entry !== declared)),
+    ];
+    return { declared, key, overridden: override !== undefined, foreign };
 }
 /** npm package name → a package/binary name both dpkg and rpm accept. */
 export function deriveBinaryName(pkgName) {
@@ -302,6 +360,8 @@ export function descriptionParagraphs(description) {
 }
 /** `LICENSE`, `LICENSE.md`, … — the names a licence file actually has. */
 export const LICENSE_FILE_NAMES = ['LICENSE', 'LICENSE.md', 'LICENSE.txt', 'COPYING', 'COPYING.md'];
+/** `CHANGELOG.md`, … — the names a project's own changelog actually has. */
+export const CHANGELOG_FILE_NAMES = ['CHANGELOG.md', 'CHANGELOG', 'CHANGELOG.txt', 'NEWS.md', 'NEWS'];
 /** The bundle's own basename, used as the launcher's exec target. */
 export function bundleEntryName(bundlePath) {
     return basename(bundlePath);