@gjsify/cli 0.64.1-next.249 → 0.64.1

package/lib/commands/ship.js

@@ -454,13 +454,21 @@ async function assemble(args) {
             })),
     ];
     // THE APPLICATION ICON, rendered once for the sizes this layout's writers
-    // embed — six for the `.exe`'s resource directory, seven for the `.icns` —
-    // and nothing for a CLI or for Linux, where the theme carries the SVG the
-    // project declared. `resolveAppIcon` REFUSES an app that has no source for a
-    // size rather than staging without it: the released artifacts this closes
-    // shipped for a year with the generic icon on two platforms, and the only
-    // reason was that nothing said so (`utils/ship/icons.ts`).
-    const icon = settings.kind === 'app' && layout.icon !== undefined
+    // embed — six for the `.exe`'s resource directory, seven for the `.icns`,
+    // three for the hicolor theme — and nothing for a CLI. `resolveAppIcon`
+    // REFUSES an app that has no source for a size rather than staging without
+    // it: the released artifacts this closes shipped for a year with the generic
+    // icon on two platforms, and the only reason was that nothing said so
+    // (`utils/ship/icons.ts`).
+    //
+    // …EXCEPT WHERE THE ROW SAYS THE ICON IS NOT REQUIRED, which is Linux and is
+    // not a softening of that rule. An icon-less app there is reported by
+    // `resolveShipSettings`'s warning and then by its own menu entry, so refusing
+    // would stop a project that has not drawn its icon yet from building a `.deb`
+    // over a defect it can already see (`LayoutIcon.required`). The guard belongs
+    // HERE as well as in `iconFor`, because `resolveAppIcon` is the half that
+    // refuses an empty `iconFiles` — reaching it at all is what has to not happen.
+    const icon = settings.kind === 'app' && layout.icon !== undefined && (layout.icon.required || settings.iconFiles.length > 0)
         ? await resolveAppIcon({
             iconFiles: settings.iconFiles,
             appId: settings.appId,

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

@@ -43,6 +43,39 @@ export interface PickedFlatpakBuildKeys {
 export declare function pickFlatpakBuildKeys(preferred: ShipFlatpakOptions | undefined, legacy: ConfigDataFlatpak): PickedFlatpakBuildKeys;
 /** The branch a `ship` Flatpak is exported under when the project names none. */
 export declare const DEFAULT_SHIP_FLATPAK_BRANCH = "stable";
+/**
+ * The scalable icon directory a `kind: 'app'` Flatpak drops before
+ * `appstreamcli compose` reads the tree.
+ *
+ * THE OTHER HALF OF `LAYOUTS.linux.icon`, and the half that cannot live in the
+ * layout: the stage is one payload for four Linux formats (ADR 0024 § 2) and the
+ * `.deb`, the `.rpm` and the AppImage all WANT the SVG — it is the icon GTK
+ * prefers, and `selectAppDirIcon` ranks it above every raster. Only the Flatpak
+ * has a build step that reads the theme, so only the Flatpak removes it, and it
+ * does so inside the sandbox rather than in the tree `ship` staged.
+ *
+ * WHY IT IS REMOVED AT ALL. `flatpak-builder` runs `appstreamcli compose` on the
+ * HOST to produce `/app/share/app-info`; AppStream 1.1.3 decodes icons through
+ * gdk-pixbuf, which reads SVG only through a loader module Fedora 44 no longer
+ * ships (`LAYOUTS.linux.icon` carries the measurement). Three probes: with the
+ * SVG present compose fails whether or not rasters are there, because it PREFERS
+ * the scalable icon and does not fall back; with the SVG gone and the rasters
+ * present it succeeds and emits 64×64 and 128×128 into the catalogue. So the
+ * rasters are necessary and this is what makes them sufficient.
+ *
+ * UNCONDITIONAL, not host-detected, and that is the point. `org.flatpak.Builder`
+ * on Flathub bundles a gdk-pixbuf that CAN read SVG, so probing the host would
+ * make the same source produce a different `.flatpak` depending on where it was
+ * built — the one property ADR 0024 § A2 asks a pack to keep. One tree, every
+ * host, at the cost of a scalable icon inside a sandbox whose only reader
+ * (`Icon=<appId>` in the exported desktop entry) resolves the 256 px raster.
+ *
+ * THE UPSTREAM FIX IS NOT OURS: `libappstream-compose.so.0` already links
+ * `librsvg-2.so.2` and uses it for fonts alone, so AppStream could render the
+ * icon without gdk-pixbuf at all. Reported as an `Upstream (AppStream, file by
+ * hand)` issue rather than filed there (root AGENTS.md).
+ */
+export declare const SCALABLE_ICONS_CLEANUP = "/share/icons/hicolor/scalable";
 export interface ShipFlatpakInput {
     ship: ConfigDataShip;
     flatpak: ConfigDataFlatpak;

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

@@ -88,6 +88,39 @@ export function pickFlatpakBuildKeys(preferred, legacy) {
 }
 /** The branch a `ship` Flatpak is exported under when the project names none. */
 export const DEFAULT_SHIP_FLATPAK_BRANCH = 'stable';
+/**
+ * The scalable icon directory a `kind: 'app'` Flatpak drops before
+ * `appstreamcli compose` reads the tree.
+ *
+ * THE OTHER HALF OF `LAYOUTS.linux.icon`, and the half that cannot live in the
+ * layout: the stage is one payload for four Linux formats (ADR 0024 § 2) and the
+ * `.deb`, the `.rpm` and the AppImage all WANT the SVG — it is the icon GTK
+ * prefers, and `selectAppDirIcon` ranks it above every raster. Only the Flatpak
+ * has a build step that reads the theme, so only the Flatpak removes it, and it
+ * does so inside the sandbox rather than in the tree `ship` staged.
+ *
+ * WHY IT IS REMOVED AT ALL. `flatpak-builder` runs `appstreamcli compose` on the
+ * HOST to produce `/app/share/app-info`; AppStream 1.1.3 decodes icons through
+ * gdk-pixbuf, which reads SVG only through a loader module Fedora 44 no longer
+ * ships (`LAYOUTS.linux.icon` carries the measurement). Three probes: with the
+ * SVG present compose fails whether or not rasters are there, because it PREFERS
+ * the scalable icon and does not fall back; with the SVG gone and the rasters
+ * present it succeeds and emits 64×64 and 128×128 into the catalogue. So the
+ * rasters are necessary and this is what makes them sufficient.
+ *
+ * UNCONDITIONAL, not host-detected, and that is the point. `org.flatpak.Builder`
+ * on Flathub bundles a gdk-pixbuf that CAN read SVG, so probing the host would
+ * make the same source produce a different `.flatpak` depending on where it was
+ * built — the one property ADR 0024 § A2 asks a pack to keep. One tree, every
+ * host, at the cost of a scalable icon inside a sandbox whose only reader
+ * (`Icon=<appId>` in the exported desktop entry) resolves the 256 px raster.
+ *
+ * THE UPSTREAM FIX IS NOT OURS: `libappstream-compose.so.0` already links
+ * `librsvg-2.so.2` and uses it for fonts alone, so AppStream could render the
+ * icon without gdk-pixbuf at all. Reported as an `Upstream (AppStream, file by
+ * hand)` issue rather than filed there (root AGENTS.md).
+ */
+export const SCALABLE_ICONS_CLEANUP = '/share/icons/hicolor/scalable';
 /**
  * Resolve the Flatpak half of `gjsify.ship`, reading the legacy block where the
  * new one is silent, and applying `ship`'s own defaults.
@@ -116,7 +149,13 @@ export function resolveShipFlatpakSettings(input) {
         // extension not being installed.
         appendPath: appendPath ?? (extensions.length > 0 ? deriveAppendPath(extensions) : []),
         finishArgs: finishArgs ?? (input.kind === 'cli' ? DEFAULT_CLI_FINISH_ARGS : DEFAULT_GUI_FINISH_ARGS),
-        cleanup: cleanup ?? [],
+        // APPENDED to what the project declared, not defaulted to — the one entry
+        // here that is not the author's choice. A project with its own `cleanup`
+        // list would otherwise lose the entry that keeps its own Flatpak buildable
+        // (see {@link SCALABLE_ICONS_CLEANUP}), and `??` cannot express "ours as
+        // well as theirs". Deduplicated so a project that already wrote the glob —
+        // the workaround this replaces — gets one, and in ITS position.
+        cleanup: [...new Set([...(cleanup ?? []), ...(input.kind === 'app' ? [SCALABLE_ICONS_CLEANUP] : [])])],
     };
     return { settings, warnings: fromLegacy.length === 0 ? [] : [deprecationWarning(fromLegacy)] };
 }

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

@@ -70,15 +70,44 @@ export interface LayoutMetadataInput extends LayoutIdentity {
  * Declared on the row rather than computed from it because the orchestrator
  * renders the rasters BEFORE the row runs — `resolveAppIcon` is asynchronous (a
  * child GJS) and `Layout.metadata` is not — so the row states its needs up front
- * and receives exactly those sizes. Absent on Linux, deliberately: the hicolor
+ * and receives exactly those sizes.
+ *
+ * ON ALL THREE ROWS, and it was absent from the Linux one until a Flatpak build
+ * measured why that was wrong. The reasoning it was absent for — "the hicolor
  * theme carries the SVG the project declared and GTK renders it itself, so there
- * is nothing to convert and nothing to refuse.
+ * is nothing to convert" — is true of GTK and NOT of the tooling that reads the
+ * same theme at BUILD time: `appstreamcli compose` resolves an SVG through
+ * gdk-pixbuf, which needs an SVG LOADER MODULE, and a host without one fails the
+ * whole compose run rather than falling back to a raster. The same host-packaging
+ * fact `icons.ts` records for the rasterizer, one phase to the right — see
+ * {@link LAYOUTS.linux.icon}.
  */
 export interface LayoutIcon {
     /** Square edge lengths the writer embeds. */
     sizes: readonly number[];
     /** What is written, for the refusal: "the Windows launcher's icon". */
     writes: string;
+    /**
+     * Whether a `kind: 'app'` stage is REFUSED when the project declares no icon
+     * source, or assembled without one.
+     *
+     * REQUIRED on every row, like {@link Layout.metadata} and
+     * {@link Layout.arches}: `false` is an answer, and an optional field is one a
+     * fourth OS forgets and then silently inherits whichever default was typed
+     * first.
+     *
+     * The two answers are different FAILURE MODES, not different strictnesses.
+     * On macOS and Windows the icon lives inside a container — an `.icns` named by
+     * `CFBundleIconFile`, a `.rsrc` in the launcher — and an application that
+     * ships without it shows the generic icon with nothing anywhere saying so:
+     * measured on released artifacts, for a year (`icons.ts`). On Linux the icon
+     * is a FILE in a theme, the desktop entry's `Icon=` names it, and an
+     * icon-less app is visibly icon-less in the menu the first time it is
+     * installed — which `resolveShipSettings` already warns about. Turning that
+     * warning into a refusal would stop a project that has not drawn its icon yet
+     * from building a `.deb` at all, for a defect its own menu entry reports.
+     */
+    required: boolean;
 }
 /** The four places a payload file can belong, as stage-relative directories. */
 export interface LayoutDirs {
@@ -252,6 +281,15 @@ export interface LayoutArches {
     /** What a reader must know to act on the refusal: who blocks it, and where it is tracked. */
     why: string;
 }
+/**
+ * The square sizes the Linux row writes into the hicolor theme.
+ *
+ * Here and not in a writer module like {@link ICO_SIZES} and {@link ICNS_SIZES},
+ * because there is no writer: the rasters ARE the artifact, one file per size,
+ * and the row below is the only thing that names them. See
+ * {@link LAYOUTS.linux.icon} for what asked for each of the three.
+ */
+export declare const HICOLOR_RASTER_SIZES: readonly [64, 128, 256];
 export declare const LAYOUTS: Record<LayoutName, Layout>;
 /** Every layout name, derived from the table so a new row cannot be missed. */
 export declare const LAYOUT_NAMES: LayoutName[];

package/lib/utils/ship/layout.js

@@ -36,6 +36,15 @@ import { SHARE } from './share-dirs.js';
  * `hdiutil` time, which is three milestones away and on another host.
  */
 const BUNDLE_NAME_FORBIDDEN = /[/:\\]/;
+/**
+ * The square sizes the Linux row writes into the hicolor theme.
+ *
+ * Here and not in a writer module like {@link ICO_SIZES} and {@link ICNS_SIZES},
+ * because there is no writer: the rasters ARE the artifact, one file per size,
+ * and the row below is the only thing that names them. See
+ * {@link LAYOUTS.linux.icon} for what asked for each of the three.
+ */
+export const HICOLOR_RASTER_SIZES = [64, 128, 256];
 /**
  * The value `ATSApplicationFontsPath` takes for this bundle, or nothing when the
  * payload carries no face (ADR 0038).
@@ -81,6 +90,10 @@ function iconFor(input, layout) {
     if (input.kind !== 'app')
         return undefined;
     if (input.icon === undefined) {
+        // The row's own answer, not a uniform one — {@link LayoutIcon.required}
+        // carries which failure mode this layout has.
+        if (LAYOUTS[layout].icon?.required !== true)
+            return undefined;
         throw new Error(`gjsify ship: the ${layout} layout writes the application's icon and was given none. ` +
             'A `kind: "app"` stage is rendered its icon by `resolveAppIcon` before the layout runs; ' +
             'reaching this row without one is a caller that skipped that step.');
@@ -105,10 +118,78 @@ export const LAYOUTS = {
             data: 'share',
             other: '',
         }),
+        // THE RASTERS THE BUILD-TIME READERS OF THE THEME NEED, and the one row
+        // whose icon is written as ordinary payload files rather than into a
+        // container. A GNOME app declares one scalable SVG, `planIcons` stages it
+        // at `share/icons/hicolor/scalable/apps/<appId>.svg`, and GTK renders it —
+        // so for three milestones this row wrote nothing.
+        //
+        // WHAT READS THE THEME BEFORE GTK DOES is `appstreamcli compose`, which
+        // `flatpak-builder` runs to produce `/app/share/app-info` — the catalogue
+        // every app store shows the app out of. AppStream 1.1.3 loads an icon
+        // through gdk-pixbuf, gdk-pixbuf reads SVG only through a LOADER MODULE,
+        // and that module is a property of the host's packaging rather than of
+        // this payload: on Fedora 44, workstation and `ghcr.io/gjsify/ci-fedora:44`
+        // alike, `/usr/lib64/gdk-pixbuf-2.0/2.10.0/loaders/` holds the xpm loader
+        // and nothing else, and `dnf provides '*/libpixbufloader-svg.so'` answers
+        // with no package at all — librsvg dropped it. So the compose run dies
+        // `file-read-error` ("image file format unknown") on the SVG and takes the
+        // whole `gjsify ship linux --target flatpak` with it. Exactly the fact
+        // `icons.ts` records for the rasterizer, one phase to the right, and the
+        // reason this is the SAME list of sizes rather than a flatpak-only patch:
+        // a `.deb` installing rasters beside its SVG is what every other GNOME app
+        // does, and the artifact stays one payload.
+        //
+        // IT IS NOT ENOUGH TO ADD THEM, measured in three probes: with the SVG
+        // present appstreamcli PREFERS it and does not fall back, so SVG + 128 and
+        // SVG + 64/128/256 both still fail and PNG-only succeeds. The SVG has to
+        // leave the tree the compose run sees — which is a Flatpak-only move,
+        // because only there is the tree built, and it is the generated manifest's
+        // `cleanup` that makes it (`flatpak-config.ts`).
+        //
+        // 64/128/256 is what a store needs and what the theme spec's own
+        // `index.theme` sizes cover: AppStream asks for 64 and 128 (it emitted
+        // exactly those two from the PNG-only probe), and 256 is the HiDPI entry
+        // Flathub's quality guidelines expect.
+        icon: {
+            sizes: HICOLOR_RASTER_SIZES,
+            writes: "the hicolor theme's raster icons (`share/icons/hicolor/<n>x<n>/apps/<appId>.png`)",
+            // The ONE row that assembles without an icon rather than refusing —
+            // `LayoutIcon.required` carries why.
+            required: false,
+        },
         // A `/usr` prefix has no manifest of its own — everything a Linux package
         // says about itself is in the `.deb`/`.rpm` header or in the freedesktop
-        // files the payload already carries.
-        metadata: () => [],
+        // files the payload already carries. What it owns is the rasters above.
+        //
+        // SKIPPING A SIZE THE PAYLOAD ALREADY STAGES is not an optimisation: a
+        // project shipping its own hand-tuned `data/icons/hicolor/128x128/apps/…`
+        // has it planned by `planIcons` at the identical path, and `placeStage`
+        // REFUSES two sources for one destination (`claim`). The project's file is
+        // the one to keep — it is drawn for that size, which is the whole point of
+        // the hicolor convention (`icons.ts`) — so the row yields rather than
+        // colliding. `resolveAppIcon` has already read that same PNG into the
+        // raster map, so the bytes agree either way; what differs is only which
+        // file the stage records as the source.
+        metadata: (input, payload) => {
+            const icon = iconFor(input, 'linux');
+            if (icon === undefined)
+                return [];
+            const planned = new Set(payload.map((file) => file.path));
+            const out = [];
+            for (const size of [...icon.png.keys()].sort((a, b) => a - b)) {
+                const rel = `${SHARE.icons}/${size}x${size}/apps/${input.appId}.png`;
+                const data = icon.png.get(size);
+                if (data === undefined || planned.has(rel))
+                    continue;
+                out.push({
+                    path: place(LAYOUTS.linux, input, rel),
+                    mode: 0o644,
+                    source: { kind: 'bytes', data },
+                });
+            }
+            return out;
+        },
         // Every architecture Debian and rpm have a name for, which is what
         // `DEBIAN_ARCH`/`RPM_ARCH` already enumerate — the layout adds nothing.
         arches: null,
@@ -213,7 +294,11 @@ export const LAYOUTS = {
         // released 0.8.0 bundle of one app (macOS 15.7, 2026-09-13): no key, no
         // `.icns`, generic icon — the twin of the Windows defect `pe-launcher.ts`
         // records.
-        icon: { sizes: ICNS_SIZES, writes: 'the macOS bundle icon (`Contents/Resources/<binaryName>.icns`)' },
+        icon: {
+            sizes: ICNS_SIZES,
+            writes: 'the macOS bundle icon (`Contents/Resources/<binaryName>.icns`)',
+            required: true,
+        },
         metadata: (input, payload) => {
             const icon = iconFor(input, 'darwin');
             const iconFile = icon === undefined ? undefined : `${input.binaryName}.icns`;
@@ -359,7 +444,11 @@ export const LAYOUTS = {
         // the target's out of its resource directory — so the `.exe` carries the
         // six sizes as `RT_ICON`/`RT_GROUP_ICON` (`ico.ts`, `pe-launcher.ts`) and
         // there is no `.ico` file in the program directory to fall out of sync.
-        icon: { sizes: ICO_SIZES, writes: 'the Windows launcher icon (`.rsrc` of `<binaryName>.exe`)' },
+        icon: {
+            sizes: ICO_SIZES,
+            writes: 'the Windows launcher icon (`.rsrc` of `<binaryName>.exe`)',
+            required: true,
+        },
         metadata: (input) => {
             const icon = iconFor(input, 'windows');
             return input.arch === 'x64'

package/lib/utils/ship/settings.js

@@ -181,9 +181,10 @@ export function resolveShipSettings(input) {
     const description = descriptionParagraphs(metadata.description) ?? [summary];
     const sections = sectionsFor(metadata.categories);
     if (kind === 'app' && discovered.iconFiles.length === 0) {
-        warnings.push(`gjsify ship: no icon found — the installed app will show a placeholder in menus and app stores ` +
-            'on Linux, and the darwin and windows layouts refuse to stage without one. Point ' +
-            '`gjsify.ship.icon` at an SVG (or a directory of sized PNGs).');
+        warnings.push(`gjsify ship: no icon found — the installed app will show a placeholder in menus on Linux, the ` +
+            'Flatpak will carry no catalogue icon for an app store to show, and the darwin and windows ' +
+            'layouts refuse to stage without one. Point `gjsify.ship.icon` at an SVG (or a directory of ' +
+            'sized PNGs).');
     }
     // Resolved here rather than in the packer, because the packer may run on a
     // host with no `package.json` at all (ADR 0024 § A2) — and because the

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.64.1-next.249",
+    "version": "0.64.1",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -142,22 +142,22 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/blueprint": "0.64.1-next.249",
-        "@gjsify/buffer": "0.64.1-next.249",
-        "@gjsify/create-app": "0.64.1-next.249",
-        "@gjsify/node-globals": "0.64.1-next.249",
-        "@gjsify/node-polyfills": "0.64.1-next.249",
-        "@gjsify/npm-registry": "0.64.1-next.249",
-        "@gjsify/resolve-npm": "0.64.1-next.249",
-        "@gjsify/rolldown-plugin-gjsify": "0.64.1-next.249",
-        "@gjsify/vite-plugin-blueprint": "0.64.1-next.249",
-        "@gjsify/rolldown-plugin-pnp": "0.64.1-next.249",
-        "@gjsify/semver": "0.64.1-next.249",
-        "@gjsify/tar": "0.64.1-next.249",
-        "@gjsify/tsc": "0.64.1-next.249",
-        "@gjsify/utils": "0.64.1-next.249",
-        "@gjsify/web-polyfills": "0.64.1-next.249",
-        "@gjsify/workspace": "0.64.1-next.249",
+        "@gjsify/blueprint": "^0.64.1",
+        "@gjsify/buffer": "^0.64.1",
+        "@gjsify/create-app": "^0.64.1",
+        "@gjsify/node-globals": "^0.64.1",
+        "@gjsify/node-polyfills": "^0.64.1",
+        "@gjsify/npm-registry": "^0.64.1",
+        "@gjsify/resolve-npm": "^0.64.1",
+        "@gjsify/rolldown-plugin-gjsify": "^0.64.1",
+        "@gjsify/vite-plugin-blueprint": "^0.64.1",
+        "@gjsify/rolldown-plugin-pnp": "^0.64.1",
+        "@gjsify/semver": "^0.64.1",
+        "@gjsify/tar": "^0.64.1",
+        "@gjsify/tsc": "^0.64.1",
+        "@gjsify/utils": "^0.64.1",
+        "@gjsify/web-polyfills": "^0.64.1",
+        "@gjsify/workspace": "^0.64.1",
         "acorn": "^8.17.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
@@ -166,13 +166,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "0.64.1-next.249",
+        "@gjsify/unit": "^0.64.1",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "0.64.1-next.249",
-        "@gjsify/rolldown-native": "0.64.1-next.249"
+        "@gjsify/oxfmt-native": "^0.64.1",
+        "@gjsify/rolldown-native": "^0.64.1"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {
@@ -191,6 +191,5 @@
     "bugs": {
         "url": "https://github.com/gjsify/gjsify/issues"
     },
-    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/infra/cli#readme",
-    "gitHead": "2e501133bfbe80e44506deef30e911e0c551502f"
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/infra/cli#readme"
 }