@gjsify/cli 0.50.0 → 0.51.0

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,108 @@ 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 ABSENT here, unlike the two windows rows and
+            // for the `.dmg`'s reason inverted: this layout HAS an install step in
+            // every other format, and inside an AppImage it does not — there is no
+            // `postinst` to run `glib-compile-schemas` in a read-only squashfs. But
+            // `compileSchemasForStage` has already run at ASSEMBLY time and
+            // `gschemas.compiled` is in the payload, so declaring the compiler on
+            // the PACK path would refuse a `--from-stage` pack that works.
+            requiredTools: [APPIMAGE_TOOL],
+            // 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.
+            installHint: 'no distribution packages it — 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',
+            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 +1125,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 +1156,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/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 {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.50.0",
+    "version": "0.51.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -142,21 +142,21 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.50.0",
-        "@gjsify/create-app": "^0.50.0",
-        "@gjsify/node-globals": "^0.50.0",
-        "@gjsify/node-polyfills": "^0.50.0",
-        "@gjsify/npm-registry": "^0.50.0",
-        "@gjsify/resolve-npm": "^0.50.0",
-        "@gjsify/rolldown-plugin-gjsify": "^0.50.0",
-        "@gjsify/vite-plugin-blueprint": "^0.50.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.50.0",
-        "@gjsify/semver": "^0.50.0",
-        "@gjsify/tar": "^0.50.0",
-        "@gjsify/tsc": "^0.50.0",
-        "@gjsify/utils": "^0.50.0",
-        "@gjsify/web-polyfills": "^0.50.0",
-        "@gjsify/workspace": "^0.50.0",
+        "@gjsify/buffer": "^0.51.0",
+        "@gjsify/create-app": "^0.51.0",
+        "@gjsify/node-globals": "^0.51.0",
+        "@gjsify/node-polyfills": "^0.51.0",
+        "@gjsify/npm-registry": "^0.51.0",
+        "@gjsify/resolve-npm": "^0.51.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.51.0",
+        "@gjsify/vite-plugin-blueprint": "^0.51.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.51.0",
+        "@gjsify/semver": "^0.51.0",
+        "@gjsify/tar": "^0.51.0",
+        "@gjsify/tsc": "^0.51.0",
+        "@gjsify/utils": "^0.51.0",
+        "@gjsify/web-polyfills": "^0.51.0",
+        "@gjsify/workspace": "^0.51.0",
         "acorn": "^8.17.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
@@ -165,13 +165,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.50.0",
+        "@gjsify/unit": "^0.51.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.50.0",
-        "@gjsify/rolldown-native": "^0.50.0"
+        "@gjsify/oxfmt-native": "^0.51.0",
+        "@gjsify/rolldown-native": "^0.51.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {