@gjsify/cli 0.47.0 → 0.48.0

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

@@ -0,0 +1,56 @@
+import type { PackSettings } from './types.js';
+/**
+ * `Thu, 04 Sep 2026 12:34:56 +0000` — the trailer format Policy § 4.4 requires.
+ *
+ * Always UTC, and the offset is written out rather than derived: the build stamp is
+ * Unix seconds, so there is no zone to preserve, and a package built in two places
+ * must not differ by a timezone.
+ *
+ * @param unixSeconds the build stamp every header in the artifact shares
+ */
+export declare function rfc822(unixSeconds: number): string;
+/**
+ * The bullet lines a project's own changelog carries for ONE version.
+ *
+ * Reads the Markdown release-note shape `release-it`'s conventional-changelog
+ * preset writes — `## [0.47.0](compare-url) (2026-09-03)`, or a bare `## 0.47.0`
+ * for a first release — and takes the `*`/`-` bullets under it up to the next
+ * version heading. Category subheadings (`### Bug Fixes`) are dropped: a Debian
+ * change block is a flat list, and a heading rendered as a bullet reads as a change
+ * that was made.
+ *
+ * Markdown links collapse to their text (`[#1510](https://…)` → `#1510`) and bold
+ * scopes lose their asterisks, because the destination is plain text that `apt
+ * changelog` prints to a terminal.
+ *
+ * @returns one string per bullet, empty when the file does not name this version
+ */
+export declare function changelogEntriesFor(version: string, source: string): string[];
+/**
+ * The whole `changelog.Debian` file: one entry, for the version being packaged.
+ *
+ * `unstable` is the distribution and `medium` the urgency — the values `dh_make`
+ * seeds a package with, and the only honest ones for an artifact built outside any
+ * Debian suite: this package targets no release, and claiming one would put a
+ * specific false statement in a field `apt` reads.
+ *
+ * The trailer's spacing is load-bearing and is the usual way this file is got
+ * wrong: exactly one leading space, then `--`, one space, the maintainer, and TWO
+ * spaces before the date.
+ *
+ * TWO lintian tags this file still raises, both measured on lintian 2.117 against
+ * gjsify's own `.deb` and both left alone deliberately:
+ *
+ *  - `initial-upload-closes-no-bugs`, because the Debian revision is `-1` and the
+ *    entry closes no bug. It is a statement about the Debian ARCHIVE's ITP
+ *    workflow — the first upload of a new source package should close its ITP bug
+ *    — and a package built by `gjsify ship` is never uploaded there. There is no
+ *    bug number that would be true to write, so the tag is inapplicable rather
+ *    than unmet.
+ *  - `changelog-not-compressed-with-max-compression`. Policy asks for `gzip -9`
+ *    and neither `CompressionStream` nor `@gjsify/zlib` takes a level, so
+ *    `gzipDeterministic` cannot ask for one. Ledgered in `status/open-todos.md`:
+ *    the fix is a capability in the core, and stamping the header's XFL byte to
+ *    claim max compression we did not use is not one.
+ */
+export declare function renderDebianChangelog(settings: PackSettings, source: string | undefined, mtime: number): string;

package/lib/utils/ship/changelog.js

@@ -0,0 +1,166 @@
+// `/usr/share/doc/<package>/changelog.Debian.gz` — Debian Policy § 4.4.
+//
+// WHY IT EXISTS AT ALL. Every `.deb` this writer produced shipped without one,
+// which the first real lintian this project ever ran named as the only
+// error-severity tag left once the copyright landed:
+//
+//   E: gjsify: no-changelog usr/share/doc/gjsify/changelog.Debian.gz (non-native package)
+//
+// "non-native" is not a coincidence: `deb.ts` writes `Version: <version>-<release>`,
+// and a version carrying a Debian revision is by definition a non-native package,
+// whose changelog is `changelog.Debian.gz` rather than `changelog.gz`.
+//
+// WHAT THE ENTRY SAYS — the open question the ledger left, decided here.
+//
+// ONE ENTRY, for the version being packaged, and that is not a truncation. Policy
+// § 4.4's file is the DEBIAN changelog: it records the packaging, not upstream's
+// development. `gjsify ship` performs exactly one packaging event per version, so
+// one entry is the whole history there is to tell. The upstream history has its own
+// (optional) file, `changelog.gz`, and this writer does not claim to produce it.
+//
+// The BODY comes from the project's own changelog when one is found — `CHANGELOG.md`
+// beside the project or up at its repository root, the same search the licence uses,
+// overridable with `gjsify.ship.changelogFile`. That was the choice worth making:
+// the GitHub release body says the same thing and is not reachable from a packing
+// host that may be offline (ADR 0024 § A2), while `CHANGELOG.md` is in the tree the
+// stage is assembled from. When nothing there names this version, the entry says so
+// in one line rather than inventing content.
+//
+// AND ONLY THE PACKAGED VERSION GETS A DATE. A Debian entry needs a distribution, an
+// urgency and an RFC822 timestamp; this writer has a real timestamp for exactly one
+// of them — `mtime`, the build stamp every other header in the artifact already
+// shares. Rendering the older versions would mean stamping each with a fabricated
+// time, since `CHANGELOG.md` dates them to the DAY, and a Debian changelog is read
+// by tools that compare those stamps.
+//
+// Deterministic by construction: the date is the build stamp, and the month and day
+// names are spelled out here rather than taken from `toLocaleString`, which answers
+// in the host's locale.
+const DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+/**
+ * `Thu, 04 Sep 2026 12:34:56 +0000` — the trailer format Policy § 4.4 requires.
+ *
+ * Always UTC, and the offset is written out rather than derived: the build stamp is
+ * Unix seconds, so there is no zone to preserve, and a package built in two places
+ * must not differ by a timezone.
+ *
+ * @param unixSeconds the build stamp every header in the artifact shares
+ */
+export function rfc822(unixSeconds) {
+    const at = new Date(unixSeconds * 1000);
+    const pad = (n) => String(n).padStart(2, '0');
+    return (`${DAYS[at.getUTCDay()]}, ${pad(at.getUTCDate())} ${MONTHS[at.getUTCMonth()]} ${at.getUTCFullYear()} ` +
+        `${pad(at.getUTCHours())}:${pad(at.getUTCMinutes())}:${pad(at.getUTCSeconds())} +0000`);
+}
+/**
+ * The bullet lines a project's own changelog carries for ONE version.
+ *
+ * Reads the Markdown release-note shape `release-it`'s conventional-changelog
+ * preset writes — `## [0.47.0](compare-url) (2026-09-03)`, or a bare `## 0.47.0`
+ * for a first release — and takes the `*`/`-` bullets under it up to the next
+ * version heading. Category subheadings (`### Bug Fixes`) are dropped: a Debian
+ * change block is a flat list, and a heading rendered as a bullet reads as a change
+ * that was made.
+ *
+ * Markdown links collapse to their text (`[#1510](https://…)` → `#1510`) and bold
+ * scopes lose their asterisks, because the destination is plain text that `apt
+ * changelog` prints to a terminal.
+ *
+ * @returns one string per bullet, empty when the file does not name this version
+ */
+export function changelogEntriesFor(version, source) {
+    const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const heading = new RegExp(`^##+[ \\t]+\\[?${escaped}\\]?[^\\n]*$`, 'm');
+    const start = heading.exec(source);
+    if (start === null)
+        return [];
+    const rest = source.slice(start.index + start[0].length);
+    // The next VERSION heading, not the next heading of any depth: `### Features`
+    // is inside this release, `## [0.46.0]` is the next one.
+    const end = /^##[ \t]+\[?\d/m.exec(rest);
+    const body = end === null ? rest : rest.slice(0, end.index);
+    const entries = [];
+    for (const line of body.split('\n')) {
+        const bullet = /^[*-][ \t]+(.*\S)\s*$/.exec(line);
+        if (bullet === null)
+            continue;
+        entries.push(bullet[1]
+            .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+            .replace(/\*\*([^*]+)\*\*/g, '$1')
+            .replace(/\s+/g, ' ')
+            .trim());
+    }
+    return entries;
+}
+/**
+ * One bullet, wrapped so no line exceeds {@link WIDTH}.
+ *
+ * MEASURED, not stylistic: lintian raises `debian-changelog-line-too-long` past 80
+ * columns, and a conventional-commit subject plus its scope, its PR link and its
+ * `closes` list goes well past it. Continuation lines are indented to sit under the
+ * bullet text — Debian's change block only requires at least two leading spaces, and
+ * anything less than four would read as a new item.
+ *
+ * A single word longer than the width is left on its own line rather than broken: a
+ * URL is the usual case, and a hyphenated URL is worse than a long one.
+ */
+function wrapEntry(entry) {
+    const lines = [];
+    let line = '  *';
+    for (const word of entry.split(/\s+/)) {
+        if (word === '')
+            continue;
+        if (line.length + 1 + word.length > WIDTH && line !== '  *' && line !== '   ') {
+            lines.push(line);
+            line = '   ';
+        }
+        line += ` ${word}`;
+    }
+    lines.push(line);
+    return lines;
+}
+/** lintian's `debian-changelog-line-too-long` threshold. */
+const WIDTH = 80;
+/**
+ * The whole `changelog.Debian` file: one entry, for the version being packaged.
+ *
+ * `unstable` is the distribution and `medium` the urgency — the values `dh_make`
+ * seeds a package with, and the only honest ones for an artifact built outside any
+ * Debian suite: this package targets no release, and claiming one would put a
+ * specific false statement in a field `apt` reads.
+ *
+ * The trailer's spacing is load-bearing and is the usual way this file is got
+ * wrong: exactly one leading space, then `--`, one space, the maintainer, and TWO
+ * spaces before the date.
+ *
+ * TWO lintian tags this file still raises, both measured on lintian 2.117 against
+ * gjsify's own `.deb` and both left alone deliberately:
+ *
+ *  - `initial-upload-closes-no-bugs`, because the Debian revision is `-1` and the
+ *    entry closes no bug. It is a statement about the Debian ARCHIVE's ITP
+ *    workflow — the first upload of a new source package should close its ITP bug
+ *    — and a package built by `gjsify ship` is never uploaded there. There is no
+ *    bug number that would be true to write, so the tag is inapplicable rather
+ *    than unmet.
+ *  - `changelog-not-compressed-with-max-compression`. Policy asks for `gzip -9`
+ *    and neither `CompressionStream` nor `@gjsify/zlib` takes a level, so
+ *    `gzipDeterministic` cannot ask for one. Ledgered in `status/open-todos.md`:
+ *    the fix is a capability in the core, and stamping the header's XFL byte to
+ *    claim max compression we did not use is not one.
+ */
+export function renderDebianChangelog(settings, source, mtime) {
+    const entries = source === undefined ? [] : changelogEntriesFor(settings.version, source);
+    const fallback = settings.homepage
+        ? `Release ${settings.version}. See ${settings.homepage} for the upstream changes.`
+        : `Release ${settings.version}.`;
+    const body = (entries.length > 0 ? entries : [fallback]).flatMap(wrapEntry);
+    return [
+        `${settings.binaryName} (${settings.version}-${settings.release}) unstable; urgency=medium`,
+        '',
+        ...body,
+        '',
+        ` -- ${settings.maintainer}  ${rfc822(mtime)}`,
+        '',
+    ].join('\n');
+}

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

@@ -6,8 +6,17 @@ export interface DiscoverInput {
     ship: ConfigDataShip;
     /** `gjsify.flatpak.icon`, the pre-existing spelling of the same thing. */
     flatpakIcon?: string;
-    /** The bundle path the project declares. */
+    /** The bundle path the project declares FOR THIS TARGET. */
     declaredBundle?: string;
+    /**
+     * The entries other targets declare, which this one must not carry.
+     *
+     * See {@link withoutForeignEntries} — same class as the locale tree below,
+     * with a sharper edge: a foreign entry is not merely dead weight, it is a
+     * bundle this target's interpreter cannot load, inside an artifact that says
+     * it can.
+     */
+    foreignBundles?: readonly string[];
 }
 export declare function discoverPayload(input: DiscoverInput): DiscoveredPayload;
 /**

package/lib/utils/ship/discover.js

@@ -6,7 +6,7 @@
 // (`data/icons/hicolor/…`, `data/*.gschema.xml`) needs no configuration at all.
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
-import { LICENSE_FILE_NAMES } from './settings.js';
+import { CHANGELOG_FILE_NAMES, LICENSE_FILE_NAMES, } from './settings.js';
 const ICON_EXTENSIONS = ['.svg', '.png'];
 /**
  * The face formats every FreeType opens, with no build option deciding it.
@@ -48,13 +48,14 @@ export function discoverPayload(input) {
         // Measured on a probe package: the same `.mo` appeared at both paths. The `lib/` copy is
         // dead weight — nothing looks there — and it is the same failure that once shipped the test
         // suite: whatever is beside the bundle gets carried whether or not it belongs in a package.
-        bundleFiles: withoutLocaleTree(listFilesRecursive(bundleDir), bundleDir, projectDir, ship.localeDir),
+        bundleFiles: withoutForeignEntries(withoutLocaleTree(listFilesRecursive(bundleDir), bundleDir, projectDir, ship.localeDir), bundleDir, projectDir, input.foreignBundles ?? [], bundlePath),
         iconFiles: discoverIcons(projectDir, ship.icon ?? input.flatpakIcon),
         schemaFiles: discoverSchemas(projectDir, ship.schemas),
         typelibFiles: discoverTypelibs(projectDir, ship.bundledTypelibs),
         localeFiles,
         fontFiles: discoverFonts(projectDir, ship.fonts),
         licenseFile: discoverLicense(projectDir, ship.licenseFile),
+        changelogFile: discoverChangelog(projectDir, ship.changelogFile),
     };
 }
 /**
@@ -168,6 +169,45 @@ function discoverLocales(projectDir, dir) {
     }
     return out;
 }
+/**
+ * Drop the entries declared for OTHER targets from this target's payload.
+ *
+ * `gjsify.ship.bundle` is per OS (#1545), so a project with two hosts builds
+ * `dist/app.gjs.mjs` and `dist/app.node.mjs` into ONE directory — and staging
+ * that directory wholesale hands each artifact the other's bundle. It is not
+ * dead weight like the locale copy: on macOS it lands inside the signed `.app`,
+ * and it is a file whose only property is that this artifact's interpreter
+ * cannot load it.
+ *
+ * Only the declared entries themselves, never a guess at what else belongs to
+ * them: a bundle's shared chunks are indistinguishable from the application's
+ * own files, and dropping one would break the artifact this list exists to keep
+ * whole.
+ */
+function withoutForeignEntries(bundleFiles, bundleDir, projectDir, foreign, bundlePath) {
+    if (foreign.length === 0)
+        return bundleFiles;
+    const dropped = new Set();
+    for (const entry of foreign) {
+        const abs = isAbsolute(entry) ? entry : resolve(projectDir, entry);
+        // THIS TARGET'S OWN ENTRY, under another spelling. The foreign set is
+        // compared as declared STRINGS, and `./dist/app.mjs`, `dist/../dist/app.mjs`
+        // and an absolute path are three spellings of one file — dropping it would
+        // stage a launcher whose bundle is not in the payload, which is a worse
+        // artifact than the one this exclusion exists to prevent. Paths are the
+        // only comparison that cannot be spelled around.
+        if (abs === bundlePath)
+            continue;
+        const rel = relative(bundleDir, abs);
+        // Outside this payload — another target may build somewhere else entirely,
+        // and then there is nothing here to subtract. Same shape as the locale
+        // tree above, including the POSIX normalisation Windows needs.
+        if (rel === '' || rel.startsWith('..') || isAbsolute(rel))
+            continue;
+        dropped.add(rel.split(sep).join(posix.sep));
+    }
+    return bundleFiles.filter((file) => !dropped.has(file));
+}
 function resolveBundle(input) {
     const declared = input.declaredBundle;
     if (declared === undefined) {
@@ -336,6 +376,40 @@ function discoverLicense(projectDir, configured) {
     }
     return undefined;
 }
+/**
+ * The project's own changelog — the prose the `.deb`'s `changelog.Debian.gz` is
+ * rendered from (Debian Policy § 4.4).
+ *
+ * SAME SEARCH AS THE LICENCE, deliberately, and for the same reason: a package
+ * inside a monorepo does not carry its own copy. `packages/infra/cli` has no
+ * CHANGELOG.md and the release train writes one at the repository root, so a
+ * `projectDir`-only search would find nothing for the one in-tree project that
+ * declares `gjsify.ship`. {@link licenseSearchDirs} stops at the first ancestor
+ * that is a project root, which is what keeps an unrelated parent directory's
+ * file out.
+ *
+ * Absence is NOT an error here, unlike the licence: Policy § 4.4 requires the
+ * FILE, not a particular history, and `renderDebianChangelog` writes a
+ * one-line entry naming the version when there is no prose to quote. Refusing
+ * would make a changelog a precondition for packaging anything.
+ */
+function discoverChangelog(projectDir, configured) {
+    if (configured !== undefined) {
+        const target = resolve(projectDir, configured);
+        if (!existsSync(target)) {
+            throw new Error(`gjsify ship: the configured changelog file ${configured} does not exist.`);
+        }
+        return target;
+    }
+    for (const dir of licenseSearchDirs(projectDir)) {
+        for (const name of CHANGELOG_FILE_NAMES) {
+            const target = join(dir, name);
+            if (existsSync(target))
+                return target;
+        }
+    }
+    return undefined;
+}
 /** `projectDir` first, then each ancestor up to and including the project root. */
 function licenseSearchDirs(projectDir) {
     const dirs = [];

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',