@gjsify/cli 0.50.0 → 0.51.1

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

@@ -91,6 +91,26 @@ export interface DependsInputs {
     /** Minimum Node major, when one is depended on. Default {@link DEFAULT_NODE_FLOOR}. */
     minNodeVersion?: string;
 }
+/**
+ * The namespaces the bundle imports that the HOST has to provide — scanned set
+ * minus everything the payload carries itself.
+ *
+ * LIFTED OUT OF {@link deriveDepends} because a second caller appeared and the
+ * question is not a `.deb`'s. `appimage.ts` asks it to write the one sentence an
+ * AppImage owes its user — *this file carries the application, and takes these
+ * from your system* — and an AppImage has no `Depends:` field, so it cannot go
+ * through the package-name table below. A copied filter would drift in the
+ * direction that is invisible: the drifted copy would still produce a plausible
+ * list, just one that no longer matches the dependencies the `.deb` beside it
+ * declares from the same payload.
+ *
+ * Deriving the carried set from the staged FILENAMES is the point, and it is
+ * `deriveDepends`' reasoning unchanged: `Gwebgl-0.1.typelib` answers for both
+ * `Gwebgl-0.1` and `Gwebgl`, so a project that declared a namespace bundled
+ * without the file being there gets an artifact that names its real requirement
+ * instead of one that installs and dies at the first import.
+ */
+export declare function hostProvidedNamespaces(namespaces: readonly string[], bundledTypelibs?: readonly string[]): string[];
 /**
  * The `Depends:` / `Requires:` list for one format.
  *

package/lib/utils/ship/depends.js

@@ -256,6 +256,36 @@ const TYPELIB_PACKAGES = {
  * whose bundle reaches one, which includes every `@gjsify/http` server.
  */
 const BUNDLED_TYPELIB = /^Gjsify[A-Z]/;
+/**
+ * The namespaces the bundle imports that the HOST has to provide — scanned set
+ * minus everything the payload carries itself.
+ *
+ * LIFTED OUT OF {@link deriveDepends} because a second caller appeared and the
+ * question is not a `.deb`'s. `appimage.ts` asks it to write the one sentence an
+ * AppImage owes its user — *this file carries the application, and takes these
+ * from your system* — and an AppImage has no `Depends:` field, so it cannot go
+ * through the package-name table below. A copied filter would drift in the
+ * direction that is invisible: the drifted copy would still produce a plausible
+ * list, just one that no longer matches the dependencies the `.deb` beside it
+ * declares from the same payload.
+ *
+ * Deriving the carried set from the staged FILENAMES is the point, and it is
+ * `deriveDepends`' reasoning unchanged: `Gwebgl-0.1.typelib` answers for both
+ * `Gwebgl-0.1` and `Gwebgl`, so a project that declared a namespace bundled
+ * without the file being there gets an artifact that names its real requirement
+ * instead of one that installs and dies at the first import.
+ */
+export function hostProvidedNamespaces(namespaces, bundledTypelibs = []) {
+    const shipped = new Set();
+    for (const file of bundledTypelibs) {
+        const match = /([A-Za-z0-9]+)-([\d.]+)\.typelib$/.exec(file);
+        if (!match)
+            continue;
+        shipped.add(`${match[1]}-${match[2]}`);
+        shipped.add(match[1]);
+    }
+    return [...new Set(namespaces)].sort().filter((ns) => !BUNDLED_TYPELIB.test(ns) && !shipped.has(ns));
+}
 /**
  * The `Depends:` / `Requires:` list for one format.
  *
@@ -271,22 +301,7 @@ export function deriveDepends(format, inputs) {
         ? [`${NODE_PACKAGE[format]} >= ${inputs.minNodeVersion ?? DEFAULT_NODE_FLOOR}`]
         : [`gjs >= ${inputs.minGjsVersion ?? DEFAULT_GJS_FLOOR}`];
     const unmapped = [];
-    // Namespaces the package SHIPS ITSELF, read off the staged filenames rather than from a
-    // separate declaration: `Gwebgl-0.1.typelib` → `Gwebgl-0.1` and `Gwebgl`. Deriving it is the
-    // point — a project that declared a namespace bundled without the file being there would get
-    // a package that installs and dies at the first import, which is exactly what this check
-    // exists to prevent.
-    const shipped = new Set();
-    for (const file of inputs.bundledTypelibs ?? []) {
-        const match = /([A-Za-z0-9]+)-([\d.]+)\.typelib$/.exec(file);
-        if (!match)
-            continue;
-        shipped.add(`${match[1]}-${match[2]}`);
-        shipped.add(match[1]);
-    }
-    for (const namespace of [...new Set(inputs.namespaces)].sort()) {
-        if (BUNDLED_TYPELIB.test(namespace) || shipped.has(namespace))
-            continue;
+    for (const namespace of hostProvidedNamespaces(inputs.namespaces, inputs.bundledTypelibs)) {
         const entry = lookupTypelib(namespace, inputs.typelibPackages);
         if (entry === undefined) {
             unmapped.push(namespace);

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

@@ -138,4 +138,13 @@ export declare function configuredFormats(raw: readonly string[], layout: Layout
  * the two questions are separate, and a `.app` is precisely the item Apple's
  * remedy above tells you to staple after submitting the archive around it.
  */
+/**
+ * Refuse a project whose `kind` no chosen container can hold.
+ *
+ * DERIVED FROM THE TABLE (`FormatDescriptor.requiresDesktopEntry`), never from a
+ * list of format ids here — a fourth format that also needs an entry would
+ * otherwise be refused by appimagetool's own "Desktop file not found, aborting"
+ * after a full build, which is the message this replaced.
+ */
+export declare function assertKindCanPack(formats: readonly FormatDescriptor[], kind: 'app' | 'cli'): void;
 export declare function canCarryTicket(id: FormatId): boolean;

package/lib/utils/ship/formats.js

@@ -8,6 +8,7 @@
 // and one filename. What it also proved is what the design did NOT predict —
 // a format can be host-bound (§ A3), so `host` is a descriptor field now.
 import { isOnPath } from '../check-system-deps.js';
+import { APPIMAGE_TOOL } from './appimage.js';
 import { DMG_TOOL } from './dmg.js';
 import { LAYOUTS, LAYOUT_NAMES } from './layout.js';
 import { SCHEMA_COMPILER, SCHEMA_COMPILER_HINT } from './schemas.js';
@@ -72,6 +73,33 @@ function rpmArch(arch, archIndependent) {
 function flatpakArch(arch, _archIndependent) {
     return lookupArch(FLATPAK_ARCH, arch, 'Flatpak');
 }
+/**
+ * `process.arch` → the name appimagetool uses, which is `uname -m`'s.
+ *
+ * A TABLE OF ITS OWN even though it currently equals `RPM_ARCH` on every row it
+ * has, and the reason is that the two answer different questions: rpm's is a
+ * package-manager namespace with `noarch`, `i686` and `ppc64le` in it, while this
+ * one is the string appimagetool puts in `$ARCH` and matches against the runtimes
+ * it can embed. Sharing the table would make an rpm row addition silently claim
+ * an AppImage architecture that has no runtime — `ppc64le` is exactly that case
+ * today. So the short list is the honest one, and an arch not in it is REFUSED
+ * rather than guessed, which is `FLATPAK_ARCH`'s rule for `FLATPAK_ARCH`'s reason:
+ * the value ends up in a filename a user is asked to download.
+ *
+ * `archIndependent` is IGNORED, like Flatpak's and unlike deb's and rpm's. There
+ * is no `noarch` AppImage: the file BEGINS with an ELF runtime, so a payload of
+ * pure JavaScript still ships in an x86-64 executable and labelling it otherwise
+ * would name a file nothing can run.
+ */
+const APPIMAGE_ARCH = {
+    x64: 'x86_64',
+    arm64: 'aarch64',
+    ia32: 'i686',
+    arm: 'armhf',
+};
+function appImageArch(arch, _archIndependent) {
+    return lookupArch(APPIMAGE_ARCH, arch, 'AppImage');
+}
 /**
  * `process.arch` → the name Apple's tools use.
  *
@@ -344,6 +372,141 @@ export const FORMATS = {
         fileName: (s, archLabel) => `${s.appId}-${s.version}-${s.release}.${archLabel}.flatpak`,
         artifactKind: 'file',
     },
+    // THE FOURTH CONTAINER OVER THE LINUX TREE, and the first row added to this
+    // table that needed NOTHING staged: `deb`, `rpm` and `flatpak` already wrap
+    // this exact payload, so ADR 0024 § 2's "one payload, a handful of layouts"
+    // is here a row plus a packer and no change to `plan.ts` at all. ADR 0024
+    // § 9 deferred it and § A24 lifts the deferral; `appimage.ts`'s header
+    // carries the argument, and the short form is that the two promises an
+    // AppImage can keep with no relocatable Linux closure — no install, no root
+    // — are the two nothing else in this table offers, and the third is
+    // DECLARED rather than implied.
+    appimage: {
+        id: 'appimage',
+        layoutOs: 'linux',
+        // `/usr`, exactly as the `.deb` — and that is the whole layout difference
+        // between the two formats. An AppImage mounts its squashfs and the AppDir's
+        // `usr/` becomes the prefix, which the staged launcher computes for itself
+        // (ADR 0024 § 3): `readlink -f "$0"` then two `dirname`s, measured inside a
+        // mount as `/tmp/.mount_xxxx/usr`. So the same `bin/<name>` works under
+        // `/usr`, under `/app` and under a mountpoint nobody chose.
+        prefix: '/usr',
+        host: {
+            // Linux-bound the way the Flatpak row is, and NOT the way the `.dmg`
+            // is: the container is an ELF runtime for Linux with a Linux filesystem
+            // behind it, so the format is bound the way the application is.
+            finishOn: ['linux'],
+            // THE SCHEMA COMPILER IS DECLARED HERE, and this row is the one place
+            // in the table where it sits on a PACK path. It used to be absent, on
+            // an argument that read well and was false: "this layout has an install
+            // step in every other format, and `compileSchemasForStage` has already
+            // run at assembly time, so declaring the compiler here would refuse a
+            // `--from-stage` pack that works." The second clause never held.
+            // `compileSchemasForStage` is skipped for `layout.os === 'linux'` —
+            // deliberately, because the Linux stage is SHARED with the `.deb` and
+            // the `.rpm`, whose `share/glib-2.0/schemas` is the SYSTEM directory
+            // that a postinst compiles and that our cache must never be installed
+            // over. So no Linux stage carries `gschemas.compiled`, a `--from-stage`
+            // AppImage pack has to produce it, and this row needs the tool.
+            //
+            // MEASURED, not reasoned: Learn6502 0.8.0's first CI-built AppImage
+            // shipped `eu.jumplink.Learn6502.gschema.xml` with nothing beside it
+            // and died at `Gio.Settings.new()` on the first line it ran.
+            //
+            // AND ONLY THIS ONE OF THE FOUR, which is the question the fix had to
+            // answer next and which is measured rather than argued.
+            // `cacheRefreshCommands` (`scripts.ts`) names four install-time steps,
+            // and an AppImage runs none of them. Three DEGRADE and one ABORTS:
+            //
+            //   * `glib-compile-schemas` — ABORTS. GSettings refuses a schema
+            //     directory holding a source with no cache; there is no fallback.
+            //   * `gtk-update-icon-cache` — does not. Measured against the rebuilt
+            //     0.8.0 image on GTK 4 / glib 2.88.3: with `XDG_DATA_DIRS` pointing
+            //     at the mounted `usr/share` and no `icon-theme.cache` anywhere,
+            //     `Gtk.IconTheme.has_icon('eu.jumplink.Learn6502')` is `true` — and
+            //     `false` for a name that is not there, so the probe discriminates.
+            //     GTK scans the directory; the cache is a lookup optimisation.
+            //   * `update-desktop-database`, `update-mime-database` — about a
+            //     SYSTEM database an install writes into. An AppImage is not
+            //     installed, so there is nothing for them to update: what a desktop
+            //     reads is the entry at the AppDir root, via the runtime's own
+            //     integration.
+            //
+            // `share/locale` needs no step on any layout — the launcher exports
+            // `GJSIFY_LOCALE_DIR` and gettext reads the `.mo` directly.
+            requiredTools: [APPIMAGE_TOOL, SCHEMA_COMPILER],
+            // A URL AND NOT A PACKAGE NAME, and it is the first hint in this table
+            // that has to be. `flatpak-builder` and `msitools` are in Fedora and in
+            // Debian; `appimagetool` is in neither, so pointing at a distro would
+            // send the reader to an `E: Unable to locate package`. The `--stage`
+            // half is repeated here because it is the answer for a CI image that is
+            // not going to grow a hand-installed binary. The compiler IS packaged,
+            // so its half of the hint is the ordinary one.
+            installHint: 'no distribution packages appimagetool — take the release from ' +
+                'https://github.com/AppImage/appimagetool/releases, `chmod +x` it and put it on PATH as ' +
+                '`appimagetool`; or assemble here with `gjsify ship linux --stage` and pack where it is. ' +
+                `The schema compiler is packaged: ${SCHEMA_COMPILER_HINT}`,
+            oracle: {
+                // TWO READERS, NEITHER OF THEM appimagetool AND NEITHER OF THEM THE
+                // ARTIFACT'S OWN RUNTIME — which is what `--appimage-offset` and
+                // `--appimage-extract` would be, the format reading what the format
+                // wrote (ADR 0024 § A3).
+                //
+                //   * CPython reads the ELF SECTION-HEADER TABLE for the offset the
+                //     filesystem starts at — `e_shoff + e_shnum * e_shentsize`,
+                //     twelve bytes of `struct.unpack_from`, straight out of the ELF
+                //     specification. Measured against `--appimage-offset` on a real
+                //     artifact: 944632 both ways. That agreement is the
+                //     discriminator for the whole container, because a truncated or
+                //     empty image has no squashfs superblock there. `python3` and
+                //     NOT `readelf`, which the first draft of this row declared and
+                //     `verify-appimage.py` never execs — the field names the tools
+                //     the oracle RUNS, and binutils is not one of them here. Same
+                //     reader family the two `macos-app` rows already declare.
+                //   * `unsquashfs` (squashfs-tools) then lists the filesystem at
+                //     that offset with names, modes and sizes, which
+                //     `.github/ship-oracle/verify-appimage.py` compares against the
+                //     stage manifest. A different PROGRAM from the bundled
+                //     mksquashfs appimagetool packs with, and the leg that runs it
+                //     is the Linux one that already reads the `.deb`.
+                readWith: ['python3', 'unsquashfs'],
+                readOn: ['linux'],
+                selfReading: false,
+            },
+        },
+        // No `Depends:` FIELD — which is not the same as no dependencies, and this
+        // row is the one place in the table where that distinction has teeth. A
+        // `.deb` declares `gir1.2-gtk-4.0` and apt refuses to install without it;
+        // an AppImage has nowhere to write that down, so `appImageHostRequirements`
+        // derives the same set from the same scan and `ship` PRINTS it while
+        // `AppRun` carries the interpreter half as a refusal. See `depends.ts`'s
+        // `DistroFormatId`: this is `null` because there is no field, never because
+        // there is nothing to say.
+        depends: null,
+        // BOTH, like `deb` and `rpm` and for the same reason: the interpreter comes
+        // from the machine. The difference from those two is that nothing declares
+        // it — see the `depends` note above and `interpreterGap` below.
+        interpreters: ['gjs', 'node'],
+        interpreterGap: 'an AppImage carries the application and takes its interpreter from the host, exactly as a distro ' +
+            'package does — but with no dependency field to declare it in, so the requirement is printed at ' +
+            'pack time and checked by `AppRun` at launch instead',
+        licenseDest: SHARE_LICENSE_DEST,
+        licenseKind: 'plain',
+        archName: appImageArch,
+        // The BINARY name, like the `.dmg` and the two zips and for their reason:
+        // this artifact is a DOWNLOAD that lands in a browser's folder beside other
+        // files, so it carries the version and the architecture and avoids the
+        // spaces a display name may contain. Not the app id, which is the Flatpak's
+        // convention because a Flatpak ref IS the id; an AppImage installs as
+        // nothing and is addressed by its path.
+        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.${archLabel}.AppImage`,
+        artifactKind: 'file',
+        // THE ONLY ROW THAT SETS IT. appimagetool refuses an AppDir with no
+        // `.desktop` at its root, and `kind: 'cli'` stages none by design — a
+        // refusal `gjsify.ship.kind` decides on its own, so it belongs before the
+        // build beside the tool gate rather than after it inside the packer.
+        requiresDesktopEntry: true,
+    },
     // ── macOS (#1354 M2a) ────────────────────────────────────────────────
     //
     // TWO ROWS FOR ONE TREE, and the pair is what `layoutOs` was added for. The
@@ -995,6 +1158,25 @@ export function configuredFormats(raw, layout) {
  * the two questions are separate, and a `.app` is precisely the item Apple's
  * remedy above tells you to staple after submitting the archive around it.
  */
+/**
+ * Refuse a project whose `kind` no chosen container can hold.
+ *
+ * DERIVED FROM THE TABLE (`FormatDescriptor.requiresDesktopEntry`), never from a
+ * list of format ids here — a fourth format that also needs an entry would
+ * otherwise be refused by appimagetool's own "Desktop file not found, aborting"
+ * after a full build, which is the message this replaced.
+ */
+export function assertKindCanPack(formats, kind) {
+    if (kind === 'app')
+        return;
+    const needsEntry = formats.filter((format) => format.requiresDesktopEntry);
+    if (needsEntry.length === 0)
+        return;
+    throw new Error(`gjsify ship: ${needsEntry.map((format) => format.id).join(', ')} cannot package a ` +
+        '`kind: "cli"` project — the container needs a desktop entry at its root and a CLI stages none ' +
+        'by design. Set `gjsify.ship.kind` to "app" if this is a GUI application, or ship it as a `.deb`, ' +
+        'an `.rpm` or a Flatpak, none of which need one.');
+}
 export function canCarryTicket(id) {
     switch (id) {
         case 'macos-app':
@@ -1007,6 +1189,7 @@ export function canCarryTicket(id) {
         case 'deb':
         case 'rpm':
         case 'flatpak':
+        case 'appimage':
         case 'windows-dir':
         case 'windows-dir-zip':
         case 'msi':

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

@@ -59,3 +59,49 @@ export interface CompileSchemasInput {
  * anyone claims otherwise.
  */
 export declare function compileSchemasForStage(input: CompileSchemasInput): Promise<StagedFile[]>;
+/**
+ * The same compile, driven from a PAYLOAD instead of from the project's files.
+ *
+ * WHY A SECOND ENTRY POINT AND NOT A SECOND CALLER OF THE FIRST. The AppImage is
+ * the one format whose LAYOUT has an install step and whose ARTIFACT does not
+ * (`formats.ts`, the `appimage` row), so the compile cannot move to the place
+ * {@link compileSchemasForStage} runs: the Linux stage is SHARED with the `.deb`
+ * and the `.rpm`, whose `share/glib-2.0/schemas` is the SYSTEM directory. A cache
+ * staged there is our 700 bytes installed over every other package's schemas —
+ * regenerated by the postinst on dpkg, and REMOVED from the system on `rpm -e`.
+ * So the cache is produced on the AppImage's own pack path, into the AppDir, and
+ * nowhere else.
+ *
+ * FROM THE PAYLOAD AND NOT FROM `settings.schemaFiles`, which is the input that
+ * makes `--from-stage` work: a stage that crossed from another host carries the
+ * `.gschema.xml` bytes and not the project directory they came from. The same
+ * argument `packOne`'s header already makes for every other container here.
+ *
+ * `undefined` RATHER THAN AN EMPTY LIST when the payload has no schema, because
+ * the caller has to tell "nothing to compile" from "a cache is expected" — see
+ * `assertAppImageIsPackable`, which refuses the second case.
+ */
+export declare function compileSchemasForPayload(input: {
+    payload: readonly {
+        path: string;
+        data: Uint8Array;
+    }[];
+    workDir: string;
+}): Promise<{
+    path: string;
+    mode: number;
+    data: Uint8Array;
+} | undefined>;
+/**
+ * Whether a prefix-relative payload path is a GSettings schema SOURCE.
+ *
+ * Exported because two modules ask it of the same payload and a second spelling
+ * would let them disagree: this module decides what to compile, and
+ * `assertAppImageIsPackable` decides whether a compiled cache was owed.
+ *
+ * The extension is `glib-compile-schemas`'s own — it reads `*.gschema.xml` from
+ * the directory it is given and ignores everything else — so a payload that
+ * staged `foo.xml` under `share/glib-2.0/schemas` is a file GSettings never reads
+ * and this correctly says nothing about it.
+ */
+export declare function isSchemaSource(path: string): boolean;

package/lib/utils/ship/schemas.js

@@ -10,6 +10,19 @@
 // installs and does not start, which is the class this whole command exists
 // against.
 //
+// AND THE PREDICATE IS THE ARTIFACT, NOT THE LAYOUT — which is what the first
+// version of this module got wrong and what the AppImage measured. The condition
+// was written as `layout.os === 'linux' ? [] : compile` (`commands/ship.ts`), and
+// it stood for a year because on Linux every format DID have an install step.
+// An AppImage has none — that is the entire point of the format — so it inherited
+// the Linux layout, inherited the skip, and shipped an artifact that died on
+// `Gio.Settings.new()` at its first line. Learn6502 0.8.0's AppImage, measured:
+//
+//     JS ERROR: Error: GSettings schema eu.jumplink.Learn6502 not found
+//
+// A layout is not a claim about install steps. {@link compileSchemasForPayload}
+// is what the format that has none calls for itself.
+//
 // AT STAGE TIME, not at pack time, and that is the decision worth stating.
 // A stage is a deliverable in its own right — it is what crosses to the host
 // that finishes a `.dmg` or an `.msi` — and the warning `gjsify ship` prints
@@ -25,8 +38,8 @@
 // declare it: they wrap a tree that is already assembled, so a `--from-stage`
 // pack of one needs no GLib at all (the `macos-app-dmg` row says so).
 import { execFile } from 'node:child_process';
-import { basename, join } from 'node:path';
-import { copyFileSync, mkdirSync, rmSync } from 'node:fs';
+import { basename, join, posix } from 'node:path';
+import { copyFileSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { promisify } from 'node:util';
 import { SHARE } from './share-dirs.js';
 const execFileAsync = promisify(execFile);
@@ -90,13 +103,88 @@ export async function compileSchemasForStage(input) {
     mkdirSync(input.workDir, { recursive: true });
     for (const schema of input.schemaFiles)
         copyFileSync(schema, join(input.workDir, basename(schema)));
+    await runSchemaCompiler(input.workDir);
+    return [
+        {
+            path: SCHEMA_CACHE,
+            mode: 0o644,
+            source: { kind: 'file', path: join(input.workDir, 'gschemas.compiled') },
+        },
+    ];
+}
+/**
+ * The same compile, driven from a PAYLOAD instead of from the project's files.
+ *
+ * WHY A SECOND ENTRY POINT AND NOT A SECOND CALLER OF THE FIRST. The AppImage is
+ * the one format whose LAYOUT has an install step and whose ARTIFACT does not
+ * (`formats.ts`, the `appimage` row), so the compile cannot move to the place
+ * {@link compileSchemasForStage} runs: the Linux stage is SHARED with the `.deb`
+ * and the `.rpm`, whose `share/glib-2.0/schemas` is the SYSTEM directory. A cache
+ * staged there is our 700 bytes installed over every other package's schemas —
+ * regenerated by the postinst on dpkg, and REMOVED from the system on `rpm -e`.
+ * So the cache is produced on the AppImage's own pack path, into the AppDir, and
+ * nowhere else.
+ *
+ * FROM THE PAYLOAD AND NOT FROM `settings.schemaFiles`, which is the input that
+ * makes `--from-stage` work: a stage that crossed from another host carries the
+ * `.gschema.xml` bytes and not the project directory they came from. The same
+ * argument `packOne`'s header already makes for every other container here.
+ *
+ * `undefined` RATHER THAN AN EMPTY LIST when the payload has no schema, because
+ * the caller has to tell "nothing to compile" from "a cache is expected" — see
+ * `assertAppImageIsPackable`, which refuses the second case.
+ */
+export async function compileSchemasForPayload(input) {
+    const sources = input.payload.filter((entry) => isSchemaSource(entry.path));
+    if (sources.length === 0)
+        return undefined;
+    rmSync(input.workDir, { recursive: true, force: true, maxRetries: 5 });
+    mkdirSync(input.workDir, { recursive: true });
+    for (const source of sources) {
+        // `posix.basename` AND NOT `basename`, which the function above correctly
+        // uses one screen up. The two take different kinds of string: that one is
+        // handed a path read off THIS filesystem, where the host is the authority;
+        // this one is handed a `PayloadEntry.path`, which is POSIX-separated by its
+        // own type contract and built with `posix.join`. On win32 the host-aware
+        // `basename` also separates on `\`, so a Linux schema whose filename
+        // legitimately contains a backslash would be silently truncated while
+        // assembling a payload that is not the host's.
+        writeFileSync(join(input.workDir, posix.basename(source.path)), source.data);
+    }
+    await runSchemaCompiler(input.workDir);
+    return { path: SCHEMA_CACHE, mode: 0o644, data: readFileSync(join(input.workDir, 'gschemas.compiled')) };
+}
+/**
+ * Whether a prefix-relative payload path is a GSettings schema SOURCE.
+ *
+ * Exported because two modules ask it of the same payload and a second spelling
+ * would let them disagree: this module decides what to compile, and
+ * `assertAppImageIsPackable` decides whether a compiled cache was owed.
+ *
+ * The extension is `glib-compile-schemas`'s own — it reads `*.gschema.xml` from
+ * the directory it is given and ignores everything else — so a payload that
+ * staged `foo.xml` under `share/glib-2.0/schemas` is a file GSettings never reads
+ * and this correctly says nothing about it.
+ */
+export function isSchemaSource(path) {
+    return path.startsWith(`${SHARE.schemas}/`) && path.endsWith('.gschema.xml');
+}
+/**
+ * `glib-compile-schemas --strict` over a directory, with the two failures named.
+ *
+ * Split out when the AppImage needed the same compile from different bytes. The
+ * MESSAGES are the reason it is one function rather than two copies: they are the
+ * whole value of this module over a bare `execFile`, and an ENOENT that named the
+ * package on one path and not the other is the drift this shape cannot have.
+ */
+async function runSchemaCompiler(workDir) {
     try {
-        await execFileAsync(SCHEMA_COMPILER, ['--strict', `--targetdir=${input.workDir}`, input.workDir]);
+        await execFileAsync(SCHEMA_COMPILER, ['--strict', `--targetdir=${workDir}`, workDir]);
     }
     catch (error) {
         const failure = error;
         if (failure.code === 'ENOENT') {
-            throw new Error(`gjsify ship: this layout has no install step, so \`${SCHEMA_COMPILER}\` has to run HERE to ` +
+            throw new Error(`gjsify ship: this artifact has no install step, so \`${SCHEMA_COMPILER}\` has to run HERE to ` +
                 `turn the payload's schemas into \`${SCHEMA_CACHE}\` — and it is not on PATH. ` +
                 `Install it (${SCHEMA_COMPILER_HINT}). Without the compiled cache the launcher points ` +
                 'XDG_DATA_DIRS at a schema directory GSettings aborts on, so the bundle would build and ' +
@@ -108,11 +196,4 @@ export async function compileSchemasForStage(input) {
             'cache\n    is written without it, so the app still aborts on the schema that was dropped. ' +
             'Fix the\n    file it names, or drop it from `gjsify.ship.schemas`.');
     }
-    return [
-        {
-            path: SCHEMA_CACHE,
-            mode: 0o644,
-            source: { kind: 'file', path: join(input.workDir, 'gschemas.compiled') },
-        },
-    ];
 }

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

@@ -144,6 +144,20 @@ export interface ResolvedSettings {
     metadata: AppMetadata;
     warnings: string[];
 }
+/**
+ * `gjsify.ship.kind`, falling back to `gjsify.flatpak`'s and then to `'app'`.
+ *
+ * LIFTED OUT because a second caller appeared BEFORE this file runs: `ship`
+ * refuses a `kind: 'cli'` project asking for a format whose container needs a
+ * desktop entry, and it does that ahead of the project's build, where
+ * `resolveShipSettings` has not run and its `discovered` input does not exist
+ * yet. The fallback chain is `{ ...flatpak, ...definedOnly(ship) }`'s for exactly
+ * this key, and a second spelling of it is the kind that stays right until
+ * somebody changes the first one — here with the artifact-shaped consequence that
+ * a project would be refused before the build for a `kind` the stage then
+ * resolves differently.
+ */
+export declare function resolveShipKind(ship: ConfigDataShip, flatpak: ConfigDataFlatpak): 'app' | 'cli';
 export declare function resolveShipSettings(input: SettingsInput): ResolvedSettings;
 /** The entry one ship target installs, which key named it, and what it must NOT carry. */
 export interface ResolvedShipBundle {

package/lib/utils/ship/settings.js

@@ -111,6 +111,22 @@ const CATEGORY_SECTIONS = [
     ['System', { section: 'admin', group: 'Applications/System' }],
     ['Utility', { section: 'utils', group: 'Applications/System' }],
 ];
+/**
+ * `gjsify.ship.kind`, falling back to `gjsify.flatpak`'s and then to `'app'`.
+ *
+ * LIFTED OUT because a second caller appeared BEFORE this file runs: `ship`
+ * refuses a `kind: 'cli'` project asking for a format whose container needs a
+ * desktop entry, and it does that ahead of the project's build, where
+ * `resolveShipSettings` has not run and its `discovered` input does not exist
+ * yet. The fallback chain is `{ ...flatpak, ...definedOnly(ship) }`'s for exactly
+ * this key, and a second spelling of it is the kind that stays right until
+ * somebody changes the first one — here with the artifact-shaped consequence that
+ * a project would be refused before the build for a `kind` the stage then
+ * resolves differently.
+ */
+export function resolveShipKind(ship, flatpak) {
+    return ship.kind ?? flatpak.kind ?? 'app';
+}
 export function resolveShipSettings(input) {
     const warnings = [];
     const { pkg, ship, flatpak, discovered } = input;
@@ -132,7 +148,9 @@ export function resolveShipSettings(input) {
     const binaryName = ship.binaryName ?? deriveBinaryName(pkg.name);
     const appId = ship.appId ?? flatpak.appId ?? reverseDnsOrThrow(pkg.name, binaryName);
     const name = metadata.name ?? titleCase(binaryName);
-    const kind = metadata.kind ?? 'app';
+    // Through the shared resolver, so the PRE-BUILD gate and this function cannot
+    // answer "is this a GUI application" differently — see {@link resolveShipKind}.
+    const kind = resolveShipKind(ship, flatpak);
     // NOT resolved here: `resolveShipApp` already did, before the format list was
     // decided from it. A second defaulting rule in this function would be the
     // second path those two answers could come apart on.

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

@@ -61,7 +61,7 @@ export interface ShipArtifact {
  * TEXTUALLY and fails if a comment gives it a second match, which is why this one
  * describes the union without quoting its head.
  */
-export type FormatId = 'deb' | 'rpm' | 'flatpak' | 'macos-app' | 'macos-app-zip' | 'macos-app-dmg' | 'windows-dir' | 'windows-dir-zip' | 'msi';
+export type FormatId = 'deb' | 'rpm' | 'flatpak' | 'appimage' | 'macos-app' | 'macos-app-zip' | 'macos-app-dmg' | 'windows-dir' | 'windows-dir-zip' | 'msi';
 /**
  * The formats whose ARTIFACT carries a distro dependency list.
  *
@@ -264,6 +264,22 @@ export interface FormatDescriptor {
      * makes this a property of the CONTAINER rather than "macOS is special".
      */
     artifactKind: 'file' | 'directory';
+    /**
+     * This container cannot hold a `kind: 'cli'` project at all.
+     *
+     * A ROW'S FACT, so the refusal fires BEFORE the project's build like
+     * `assertCanPack`'s two do, and for the identical reason: `gjsify.ship.kind`
+     * is configuration, so the answer is knowable up front and discovering it
+     * after `runProjectBuild` costs the whole build for a refusal nothing learned
+     * from building. `appimage` is the only row that sets it — appimagetool
+     * refuses an AppDir with no `.desktop` at its root, and a CLI project stages
+     * none by design. A `.deb`, an `.rpm` and a Flatpak all ship a CLI perfectly.
+     *
+     * NOT the same question as the ICON half of `assertAppImageIsPackable`, which
+     * stays on the pack path: an icon is DISCOVERED, and discovery legitimately
+     * reads files the build produces.
+     */
+    requiresDesktopEntry?: true;
 }
 /** One shared-mime-info type definition (`gjsify.ship.mimeTypes`). */
 export interface ShipMimeType {