@gjsify/cli 0.51.0 → 0.52.0

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

@@ -2,6 +2,8 @@ import type { LayoutMetadataInput } from './layout.js';
 /** Where the two files live inside a bundle. Apple's names, not ours. */
 export declare const BUNDLE_INFO_PLIST = "Contents/Info.plist";
 export declare const BUNDLE_PKGINFO = "Contents/PkgInfo";
+/** Where `CFBundleIconFile` is resolved: the bundle's resources directory, and nowhere else. */
+export declare const BUNDLE_RESOURCES = "Contents/Resources";
 /**
  * Render `Contents/Info.plist`.
  *
@@ -30,19 +32,12 @@ export declare const BUNDLE_PKGINFO = "Contents/PkgInfo";
  * release). Emitting `version` twice would throw the distinction away on the one
  * OS that has a field for it.
  *
- * KEYS DELIBERATELY ABSENT are listed in this module's header. `CFBundleIconFile`
- * is the one a reader will reach for first, and it is absent for a reason that
- * outlives the key: M2a ships NO icon. `png2icns`, `icnsutil` and `iconutil` are
- * all absent from this workstation and from the CI image, so an `.icns` written
- * here could only be read back by a reader written here — `selfReading: true`,
- * which `flatpak.spec.ts` reds. The unblocker is an independent Linux ICNS reader
- * entering the CI image; until one does, the hicolor PNG/SVG the payload already
- * carries stays the only icon, unread on macOS.
+ * KEYS DELIBERATELY ABSENT are listed in this module's header.
  *
  * A TWELFTH KEY, `ATSApplicationFontsPath`, is emitted when the bundle carries
  * faces, and it is the first one here NOT cited to `refs/` — so the exception is
  * stated rather than left to be noticed (ADR 0038). The rule this module opens
- * with exists against DECORATION: the five absent keys are cosmetic, nothing a
+ * with exists against DECORATION: the four absent keys are cosmetic, nothing a
  * reader here can open contains them, and emitting one would be a guess with no
  * observable behind it. This key is a MECHANISM, and its citation is Apple's own
  * *Information Property List Key Reference*, which states the scope in the terms
@@ -51,6 +46,21 @@ export declare const BUNDLE_PKGINFO = "Contents/PkgInfo";
  * app and not for the system as a whole."* The value is a path relative to
  * `Contents/Resources`.
  *
+ * A THIRTEENTH, `CFBundleIconFile`, is the same shape of exception and closes the
+ * gap the previous version of this comment recorded: M2a shipped NO icon because
+ * nothing on Linux could read an `.icns` back. Two things changed. `icns.ts` now
+ * writes the container from rasters `icons.ts` renders through librsvg, and the
+ * readers were measured rather than assumed: CPython `struct` walks the element
+ * table in `verify-app-plist.py` (in CI), Pillow 12.3 opens all ten elements (on
+ * the workstation), `icns2png` reads three of ten and is NOT relied on, and
+ * `iconutil` on macOS is the reader with authority — a VM run, recorded with the
+ * change that lands this key. The citation is the same key reference: *"The name
+ * of the bundle's icon file, located in the Resources folder"*, and the
+ * measurement that motivates it is the released 0.8.0 bundle of one app on macOS
+ * 15.7 with no key, no `.icns` and the generic Finder icon. `CFBundleIconName` is
+ * NOT emitted: it names an asset-catalog entry (`Assets.car`), which this tree
+ * does not produce, and a name with no catalog is a dangling reference.
+ *
  * It is also the only route there is. Pango on macOS is CoreText-backed, GTK is
  * not built against fontconfig on that platform, and
  * `pango_font_map_add_font_file()` answers `G_IO_ERROR_NOT_SUPPORTED` on the
@@ -63,7 +73,7 @@ export declare const BUNDLE_PKGINFO = "Contents/PkgInfo";
  * Pango's CoreText map then holds the family, is unverified here — which is what
  * `Layout.fontGap` says out loud rather than letting a green stage imply.
  */
-export declare function renderInfoPlist(input: LayoutMetadataInput, fontsPath?: string): string;
+export declare function renderInfoPlist(input: LayoutMetadataInput, fontsPath?: string, iconFile?: string): string;
 /**
  * Render `Contents/PkgInfo`: the package type and the signature, eight bytes, no
  * newline.

package/lib/utils/ship/plist.js

@@ -14,8 +14,10 @@
 // (`.github/ship-oracle/verify-modes.py`), and it parses the XML form.
 //
 // EVERY KEY BELOW IS CITED to a file in `refs/` that a real macOS toolchain
-// produced or consumes. Keys that are merely plausible — `CFBundleIconFile`,
-// `LSMinimumSystemVersion`, `NSHighResolutionCapable`, `LSApplicationCategoryType`,
+// produced or consumes, or — for the two MECHANISM keys, `ATSApplicationFontsPath`
+// and `CFBundleIconFile` — to Apple's own key reference plus a measurement on a
+// Mac. Keys that are merely plausible — `LSMinimumSystemVersion`,
+// `NSHighResolutionCapable`, `LSApplicationCategoryType`,
 // `NSHumanReadableCopyright` — are not emitted, because nothing a reader here can
 // open contains them.
 //
@@ -32,6 +34,8 @@
 /** Where the two files live inside a bundle. Apple's names, not ours. */
 export const BUNDLE_INFO_PLIST = 'Contents/Info.plist';
 export const BUNDLE_PKGINFO = 'Contents/PkgInfo';
+/** Where `CFBundleIconFile` is resolved: the bundle's resources directory, and nowhere else. */
+export const BUNDLE_RESOURCES = 'Contents/Resources';
 /**
  * The four-character bundle type of an application, and the signature that says
  * "none".
@@ -139,19 +143,12 @@ function arrayEntry(key, values) {
  * release). Emitting `version` twice would throw the distinction away on the one
  * OS that has a field for it.
  *
- * KEYS DELIBERATELY ABSENT are listed in this module's header. `CFBundleIconFile`
- * is the one a reader will reach for first, and it is absent for a reason that
- * outlives the key: M2a ships NO icon. `png2icns`, `icnsutil` and `iconutil` are
- * all absent from this workstation and from the CI image, so an `.icns` written
- * here could only be read back by a reader written here — `selfReading: true`,
- * which `flatpak.spec.ts` reds. The unblocker is an independent Linux ICNS reader
- * entering the CI image; until one does, the hicolor PNG/SVG the payload already
- * carries stays the only icon, unread on macOS.
+ * KEYS DELIBERATELY ABSENT are listed in this module's header.
  *
  * A TWELFTH KEY, `ATSApplicationFontsPath`, is emitted when the bundle carries
  * faces, and it is the first one here NOT cited to `refs/` — so the exception is
  * stated rather than left to be noticed (ADR 0038). The rule this module opens
- * with exists against DECORATION: the five absent keys are cosmetic, nothing a
+ * with exists against DECORATION: the four absent keys are cosmetic, nothing a
  * reader here can open contains them, and emitting one would be a guess with no
  * observable behind it. This key is a MECHANISM, and its citation is Apple's own
  * *Information Property List Key Reference*, which states the scope in the terms
@@ -160,6 +157,21 @@ function arrayEntry(key, values) {
  * app and not for the system as a whole."* The value is a path relative to
  * `Contents/Resources`.
  *
+ * A THIRTEENTH, `CFBundleIconFile`, is the same shape of exception and closes the
+ * gap the previous version of this comment recorded: M2a shipped NO icon because
+ * nothing on Linux could read an `.icns` back. Two things changed. `icns.ts` now
+ * writes the container from rasters `icons.ts` renders through librsvg, and the
+ * readers were measured rather than assumed: CPython `struct` walks the element
+ * table in `verify-app-plist.py` (in CI), Pillow 12.3 opens all ten elements (on
+ * the workstation), `icns2png` reads three of ten and is NOT relied on, and
+ * `iconutil` on macOS is the reader with authority — a VM run, recorded with the
+ * change that lands this key. The citation is the same key reference: *"The name
+ * of the bundle's icon file, located in the Resources folder"*, and the
+ * measurement that motivates it is the released 0.8.0 bundle of one app on macOS
+ * 15.7 with no key, no `.icns` and the generic Finder icon. `CFBundleIconName` is
+ * NOT emitted: it names an asset-catalog entry (`Assets.car`), which this tree
+ * does not produce, and a name with no catalog is a dangling reference.
+ *
  * It is also the only route there is. Pango on macOS is CoreText-backed, GTK is
  * not built against fontconfig on that platform, and
  * `pango_font_map_add_font_file()` answers `G_IO_ERROR_NOT_SUPPORTED` on the
@@ -172,7 +184,7 @@ function arrayEntry(key, values) {
  * Pango's CoreText map then holds the family, is unverified here — which is what
  * `Layout.fontGap` says out loud rather than letting a green stage imply.
  */
-export function renderInfoPlist(input, fontsPath) {
+export function renderInfoPlist(input, fontsPath, iconFile) {
     const name = assertPlistText(input.name, 'CFBundleName', 'gjsify.ship.name');
     const executable = assertPlistText(input.binaryName, 'CFBundleExecutable', 'gjsify.ship.binaryName');
     const appId = assertPlistText(input.appId, 'CFBundleIdentifier', 'gjsify.ship.appId');
@@ -195,6 +207,11 @@ export function renderInfoPlist(input, fontsPath) {
         stringEntry('CFBundleDevelopmentRegion', 'en'),
         stringEntry('CFBundleDisplayName', name),
         stringEntry('CFBundleExecutable', executable),
+        // Between Executable and Identifier is where the alphabet puts it. Absent,
+        // not empty, for a bundle that carries no icon (`kind: 'cli'`): an empty
+        // name is a file lookup that fails, which macOS answers with the same
+        // generic icon and no diagnostic.
+        ...(iconFile === undefined ? [] : [stringEntry('CFBundleIconFile', iconFile)]),
         stringEntry('CFBundleIdentifier', appId),
         stringEntry('CFBundleInfoDictionaryVersion', '6.0'),
         stringEntry('CFBundleName', name),

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.js

@@ -175,8 +175,9 @@ 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. ` +
-            '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 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).');
     }
     // 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.51.0",
+    "version": "0.52.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -131,7 +131,7 @@
         "build:test:node": "node lib/index.js build src/test.mts --app node --outfile dist/test.node.mjs",
         "test:node": "node dist/test.node.mjs",
         "test:bun": "bun dist/test.node.mjs",
-        "test:deno": "deno run -A --no-lock --node-modules-dir=none dist/test.node.mjs",
+        "test:deno": "deno run -A --no-lock --node-modules-dir=none --min-dep-age=0 dist/test.node.mjs",
         "test:cross-runtime": "gjsify run build:test:node && gjsify run test:node && gjsify run test:bun && gjsify run test:deno",
         "test": "gjsify run build:test:node && gjsify run test:node"
     },
@@ -142,21 +142,21 @@
         "cli"
     ],
     "dependencies": {
-        "@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",
+        "@gjsify/buffer": "^0.52.0",
+        "@gjsify/create-app": "^0.52.0",
+        "@gjsify/node-globals": "^0.52.0",
+        "@gjsify/node-polyfills": "^0.52.0",
+        "@gjsify/npm-registry": "^0.52.0",
+        "@gjsify/resolve-npm": "^0.52.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.52.0",
+        "@gjsify/vite-plugin-blueprint": "^0.52.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.52.0",
+        "@gjsify/semver": "^0.52.0",
+        "@gjsify/tar": "^0.52.0",
+        "@gjsify/tsc": "^0.52.0",
+        "@gjsify/utils": "^0.52.0",
+        "@gjsify/web-polyfills": "^0.52.0",
+        "@gjsify/workspace": "^0.52.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.51.0",
+        "@gjsify/unit": "^0.52.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.51.0",
-        "@gjsify/rolldown-native": "^0.51.0"
+        "@gjsify/oxfmt-native": "^0.52.0",
+        "@gjsify/rolldown-native": "^0.52.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {