@gjsify/cli 0.64.4 → 0.64.6

package/lib/commands/ship.js

@@ -26,12 +26,16 @@ import { CHANNELS, CHANNEL_ENV, parseDeclaredChannel } from '../utils/channel.js
 import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { Config } from '../config.js';
+import { ensurePkgDir } from './dlx.js';
 import { renderDesktopEntry, renderMetainfoApp, renderMetainfoCli, validateAppMetadata, } from '../utils/app-metadata.js';
 import { readPackageJson } from '../utils/pkg-json.js';
+import { parseSpec } from '../utils/parse-spec.js';
+import { cliVersion } from '../utils/publish-headers.js';
 import { describeExit, spawnToCompletion } from '../utils/spawn.js';
 import { buildDeb } from '../utils/ship/deb.js';
 import { deriveDepends, warnAboutGjsFloor, warnAboutNodeFloor } from '../utils/ship/depends.js';
 import { isGtkRuntimeTarget, stageAppRuntime } from '../utils/ship/app-runtime.js';
+import { acquireGtkRuntime } from '../utils/ship/gtk-runtime-acquire.js';
 import { discoverPayload } from '../utils/ship/discover.js';
 import { appDirFor, appDirPayload, appImageHostRequirements, appImageRuntimeNotice, buildAppImage, findPinnedRuntime, stampAppDirTimes, } from '../utils/ship/appimage.js';
 import { buildDmgImage, dmgVolumeDir, dmgVolumeName } from '../utils/ship/dmg.js';
@@ -411,7 +415,7 @@ async function assemble(args) {
     // `.deb`/`.rpm` `Depends:` is the promise that `node` or `gjs` is on `PATH`, and
     // carrying a second copy inside the payload would be a private interpreter no
     // distribution update ever patches.
-    const runtime = resolveCarriedRuntime(layout, settings, projectDir);
+    const runtime = await resolveCarriedRuntime(layout, settings, projectDir);
     const stageInputs = {
         bundleFiles: discovered.bundleFiles,
         launcher: renderLauncher(settings, basename(settings.bundlePath), layout, runtime.launcher),
@@ -761,21 +765,35 @@ function announceSigning(sign, notarize) {
  * thing to make non-vacuous on this layout, since a JavaScript bundle has no
  * cputype to disagree with.
  */
-function resolveCarriedRuntime(layout, settings, projectDir) {
+async function resolveCarriedRuntime(layout, settings, projectDir) {
     const empty = { files: [], launcher: {}, found: [], missing: [] };
     if (layout.os === 'linux' || settings.app !== 'node')
         return empty;
     const target = `${layout.os}-${settings.arch}`;
     if (!isGtkRuntimeTarget(target))
         return empty;
+    // The closure is fetched, not installed: a project that lists it puts a second
+    // GLib next to Homebrew's in its dev tree (see `gtk-runtime-acquire.ts`).
+    const acquired = await acquireGtkRuntime({
+        target,
+        version: cliVersion(),
+        discovery: { cwd: projectDir },
+        ensure: async (spec) => (await ensurePkgDir(parseSpec(spec), { verbose: false, cacheMaxAge: DLX_CACHE_MAX_AGE_MIN, frozen: false }))
+            .pkgDir,
+        log: (message) => console.log(`${LOG} ${message}`),
+    });
     return stageAppRuntime({
         layout,
         identity: settings,
         target,
         cwd: projectDir,
         interpreter: isNodeRuntimeTarget(target) ? resolveNodeRuntime(target, { cwd: projectDir }) : null,
+        ...(acquired.kind === 'fetched' ? { fetchedGtkRuntimeDir: acquired.dir } : {}),
+        ...(acquired.kind === 'failed' ? { gtkFetchFailure: acquired.reason } : {}),
     });
 }
+/** How long a fetched runtime stays in the dlx cache — the same week `gjsify showcase` uses. */
+const DLX_CACHE_MAX_AGE_MIN = 60 * 24 * 7;
 /**
  * Phase two: pack a stage that was assembled somewhere else.
  *

package/lib/utils/bin-shim.d.ts

@@ -173,12 +173,23 @@ export declare function buildNativeEnvPreamble(scanRoot: string, bakedDirs?: rea
  * cannot go stale the way baking `systemGiLibraryDirs()` in would (a launcher is
  * routinely written before `brew install gtk4`), and it re-derives nothing —
  * four literals from `dyld(1)`, shared with {@link dyldDefaultFallbackDirs}.
- * An inherited value stays AHEAD of it; the export only ADDS BACK what dyld
- * would have searched on its own.
+ * An inherited value stays AHEAD of it.
  *
- * NOT the host's GI libdirs: `/opt/homebrew/lib` was never in dyld's default
- * either, so an ARM Mac has that gap with or without gjsify —
- * `status/open-todos/README.md`.
+ * NOT SUFFICIENT ON ITS OWN, so the `lib/` beside the `gjs` this shim execs is
+ * appended: "set to the documented default" is NOT "unset". Measured on macOS 27 / arm64 with Homebrew
+ * gjs 1.88.1 and a fresh glib keg: `gjs -c "imports.gi.Gio"` loads with the
+ * variable unset and dies with the documented default exported —
+ * `Failed to load shared library 'libgjs.0.dylib' referenced by the typelib`,
+ * then `Unsupported type void` from Gio's override `_init`. `GjsPrivate-1.0`
+ * names GJS's own library by bare leaf, and once the variable is SET dyld only
+ * finds it in a listed directory; `gjs`'s rpath names GLib's keg, not its own.
+ * That broke every `gjsify` command on an Apple-silicon Mac, `--version`
+ * included, until a symlink was planted in GLib's keg by hand (the CI step
+ * `Make libgjs resolvable without a DYLD_ variable`) — and a `brew upgrade glib`
+ * silently removes it again. `<dir of gjs>/../lib` is where every prefix
+ * (Homebrew on either arch, MacPorts) links `libgjs`, resolved at LAUNCH from
+ * the same `PATH` lookup the `exec` uses, so it cannot go stale either. It goes
+ * LAST: it only has to catch what the defaults miss.
  */
 export declare function dyldFallbackPreamble(platform: string): string;
 /** POSIX `sh` single-quoting for a launcher's target path. */

package/lib/utils/bin-shim.js

@@ -444,12 +444,23 @@ export function buildNativeEnvPreamble(scanRoot, bakedDirs = [], target = {}) {
  * cannot go stale the way baking `systemGiLibraryDirs()` in would (a launcher is
  * routinely written before `brew install gtk4`), and it re-derives nothing —
  * four literals from `dyld(1)`, shared with {@link dyldDefaultFallbackDirs}.
- * An inherited value stays AHEAD of it; the export only ADDS BACK what dyld
- * would have searched on its own.
+ * An inherited value stays AHEAD of it.
  *
- * NOT the host's GI libdirs: `/opt/homebrew/lib` was never in dyld's default
- * either, so an ARM Mac has that gap with or without gjsify —
- * `status/open-todos/README.md`.
+ * NOT SUFFICIENT ON ITS OWN, so the `lib/` beside the `gjs` this shim execs is
+ * appended: "set to the documented default" is NOT "unset". Measured on macOS 27 / arm64 with Homebrew
+ * gjs 1.88.1 and a fresh glib keg: `gjs -c "imports.gi.Gio"` loads with the
+ * variable unset and dies with the documented default exported —
+ * `Failed to load shared library 'libgjs.0.dylib' referenced by the typelib`,
+ * then `Unsupported type void` from Gio's override `_init`. `GjsPrivate-1.0`
+ * names GJS's own library by bare leaf, and once the variable is SET dyld only
+ * finds it in a listed directory; `gjs`'s rpath names GLib's keg, not its own.
+ * That broke every `gjsify` command on an Apple-silicon Mac, `--version`
+ * included, until a symlink was planted in GLib's keg by hand (the CI step
+ * `Make libgjs resolvable without a DYLD_ variable`) — and a `brew upgrade glib`
+ * silently removes it again. `<dir of gjs>/../lib` is where every prefix
+ * (Homebrew on either arch, MacPorts) links `libgjs`, resolved at LAUNCH from
+ * the same `PATH` lookup the `exec` uses, so it cannot go stale either. It goes
+ * LAST: it only has to catch what the defaults miss.
  */
 export function dyldFallbackPreamble(platform) {
     if (platform !== 'darwin')
@@ -457,7 +468,10 @@ export function dyldFallbackPreamble(platform) {
     // `HOME: '$HOME'` on purpose — the shim must expand it at LAUNCH, not bake
     // the writing machine's home directory into every launcher.
     const dirs = dyldDefaultFallbackDirs({ HOME: '$HOME' }).join(':');
-    return (`DYLD_FALLBACK_LIBRARY_PATH="\${DYLD_FALLBACK_LIBRARY_PATH:+$DYLD_FALLBACK_LIBRARY_PATH:}${dirs}"\n` +
+    return (`gjsify_gjs=$(command -v gjs 2>/dev/null)\n` +
+        `DYLD_FALLBACK_LIBRARY_PATH="\${DYLD_FALLBACK_LIBRARY_PATH:+$DYLD_FALLBACK_LIBRARY_PATH:}${dirs}` +
+        `\${gjsify_gjs:+:\${gjsify_gjs%/*}/../lib}"\n` +
+        `unset gjsify_gjs\n` +
         `export DYLD_FALLBACK_LIBRARY_PATH\n`);
 }
 /** POSIX `sh` single-quoting for a launcher's target path. */

package/lib/utils/install-backend-native.js

@@ -72,7 +72,7 @@ import { getCachedPackument, putCachedPackument } from './install-packument-cach
 import { assertNativeBackendNodeVersion } from './node-version.js';
 import { buildCmdShim, buildLauncherShims, buildNativeEnvPreamble, buildShLauncher, isGjsBundlePath, parseShebang, pickBinMap, } from './bin-shim.js';
 import { detectNativePackages } from './detect-native-packages.js';
-import { findExtraneous, formatExtraneousError } from './install-extraneous.js';
+import { droppedInstallPaths, findExtraneous, formatExtraneousError } from './install-extraneous.js';
 import { devLinkPath, devLinkRoot } from './dev-link.js';
 import { scanPrefix } from './prune-prefix.js';
 import { badPlatformError, checkPlatform, declaresPlatform, describePlatformTarget, readPlatformForce, resolveHostPlatform, } from './platform-check.js';
@@ -293,6 +293,12 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     await downloadAndExtractAll(installable, opts.prefix, npmrc, log, opts.signal, progress);
     await linkBins(installable, opts.prefix, log);
     warnMissingNativeBuilds(installable, opts.prefix, log);
+    // Only after a resolve that rewrote the lockfile: that is when a placement can
+    // be dropped, and the previous lockfile is the record of what this installer
+    // put there. After the extract, so a failed download leaves the tree as it was.
+    if (resolved && opts.lockfile && existingLock) {
+        removeDroppedPackages(opts.prefix, droppedInstallPaths(Object.keys(existingLock.packages), nodes), new Set([...(opts.workspaceNames ?? []), ...(opts.linkedNames ?? [])]), log);
+    }
     log('install: done');
     // Top-level requested packages only, so callers can write the resolved version
     // back into package.json (`npm install --save`). From `nodes`, NEVER from
@@ -300,6 +306,38 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     // downloaded", and a provided package is installed.
     return topLevelResolutions(opts.specs, nodes);
 }
+/**
+ * Remove what {@link droppedInstallPaths} planned, and say so in one line.
+ *
+ * A symlink is never removed (a workspace or `gjsify link` checkout, i.e. the user's
+ * sources), and neither is a name a workspace or a dev link provides, whatever its
+ * path: the same two guards `extractOne` applies before it overwrites anything.
+ */
+function removeDroppedPackages(prefix, installPaths, providedNames, log) {
+    const removed = [];
+    for (const installPath of installPaths) {
+        if (providedNames.has(nameFromInstallPath(installPath)))
+            continue;
+        const dir = path.join(prefix, installPath);
+        let stat;
+        try {
+            stat = fs.lstatSync(dir);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        fs.rmSync(dir, { recursive: true, force: true });
+        removed.push(installPath);
+    }
+    if (removed.length === 0)
+        return;
+    log('install: removed %d dropped placement(s): %s', removed.length, removed.join(', '));
+    const names = removed.map(nameFromInstallPath);
+    const shown = names.slice(0, 5).join(', ') + (names.length > 5 ? `, … ${names.length - 5} more` : '');
+    console.log(`gjsify: removed ${removed.length} package(s) the lockfile no longer names (${shown})`);
+}
 /**
  * `--immutable` only: refuse a `node_modules` holding packages the lockfile does not
  * describe, naming every one of them.

package/lib/utils/install-extraneous.d.ts

@@ -91,3 +91,28 @@ export declare const EXTRANEOUS_REPORT_LIMIT = 20;
  * hand them a command that changes nothing and a refusal that repeats verbatim.
  */
 export declare function formatExtraneousError(entries: readonly ExtraneousPackage[], prefix: string): string;
+/**
+ * Install paths the PREVIOUS lockfile placed and a fresh resolve no longer does —
+ * what a plain install DROPPED, and the only thing it removes.
+ *
+ * THE INCIDENT (2026-10-22). A project removed `@gjsify/gtk-runtime-darwin-*` from its
+ * `optionalDependencies`; `gjsify install` rewrote the lockfile without them and left
+ * the 0.64.2 copies in `node_modules`. On a Mac every darwin prebuild's rpath prefers
+ * that bundle's GLib over Homebrew's, so every build kept dying with `No signal
+ * 'context_response' on object 'GVolumeMonitor'` — after the fix, from a dependency
+ * the project no longer declared. npm removes such a package; this installer only
+ * ever added.
+ *
+ * WHY THE LOCKFILE DIFF, and not "everything {@link findExtraneous} reports". The tree
+ * legitimately holds packages no lockfile names: `ensureProjectGjsEngine` lays the GJS
+ * bundler engine down after the install and on purpose keeps it out of the lockfile.
+ * Sweeping the undescribed set would delete that engine on every install and fetch it
+ * again. A path some earlier lockfile of THIS project placed is this installer's own
+ * output, so removing it cannot take anything another writer put there.
+ *
+ * Nested placements under a dropped root collapse into the root, like
+ * {@link findExtraneous}, so the caller removes each directory once.
+ */
+export declare function droppedInstallPaths(previous: Iterable<string>, next: readonly {
+    installPath: string;
+}[]): string[];

package/lib/utils/install-extraneous.js

@@ -129,3 +129,44 @@ export function formatExtraneousError(entries, prefix) {
             'In CI this usually means a cache entry was restored from a DIFFERENT lockfile.',
     ].join('\n');
 }
+/**
+ * Install paths the PREVIOUS lockfile placed and a fresh resolve no longer does —
+ * what a plain install DROPPED, and the only thing it removes.
+ *
+ * THE INCIDENT (2026-10-22). A project removed `@gjsify/gtk-runtime-darwin-*` from its
+ * `optionalDependencies`; `gjsify install` rewrote the lockfile without them and left
+ * the 0.64.2 copies in `node_modules`. On a Mac every darwin prebuild's rpath prefers
+ * that bundle's GLib over Homebrew's, so every build kept dying with `No signal
+ * 'context_response' on object 'GVolumeMonitor'` — after the fix, from a dependency
+ * the project no longer declared. npm removes such a package; this installer only
+ * ever added.
+ *
+ * WHY THE LOCKFILE DIFF, and not "everything {@link findExtraneous} reports". The tree
+ * legitimately holds packages no lockfile names: `ensureProjectGjsEngine` lays the GJS
+ * bundler engine down after the install and on purpose keeps it out of the lockfile.
+ * Sweeping the undescribed set would delete that engine on every install and fetch it
+ * again. A path some earlier lockfile of THIS project placed is this installer's own
+ * output, so removing it cannot take anything another writer put there.
+ *
+ * Nested placements under a dropped root collapse into the root, like
+ * {@link findExtraneous}, so the caller removes each directory once.
+ */
+export function droppedInstallPaths(previous, next) {
+    const kept = new Set(next.map((n) => normalizePath(n.installPath)));
+    const dropped = [...new Set([...previous].map(normalizePath))]
+        .filter((p) => p.startsWith('node_modules/') && !kept.has(p))
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const keptList = [...kept];
+    const roots = [];
+    for (const p of dropped) {
+        const parent = roots[roots.length - 1];
+        if (parent && p.startsWith(`${parent}/`))
+            continue;
+        // A directory still holding a kept placement is not removed whole; its own
+        // dropped descendants are still listed, one by one.
+        if (keptList.some((k) => k.startsWith(`${p}/`)))
+            continue;
+        roots.push(p);
+    }
+    return roots;
+}

package/lib/utils/ship/app-runtime.d.ts

@@ -1,4 +1,4 @@
-import type { Layout, LayoutIdentity } from './layout.js';
+import { type Layout, type LayoutIdentity } from './layout.js';
 import { type ResolveInstalledPackageOptions } from '../resolve-npm-package.js';
 import type { StagedFile } from './types.js';
 /**
@@ -49,6 +49,13 @@ export interface ResolveRuntimeOptions {
      * is Bun's global-cache behaviour, which is otherwise unreachable from Node.
      */
     resolve?: ResolveInstalledPackageOptions['resolve'];
+    /**
+     * The directory of a `@gjsify/gtk-runtime-<target>` package that
+     * {@link acquireGtkRuntime} fetched for THIS run — the last candidate, after
+     * everything the author installed or pointed at. See `gtk-runtime-acquire.ts`
+     * for why it is fetched rather than installed.
+     */
+    fetchedGtkRuntimeDir?: string;
 }
 /**
  * Locate the relocated GTK closure for `target`, or `null`.
@@ -68,7 +75,11 @@ export interface ResolveRuntimeOptions {
  *     for a ship run.
  *  3. the sibling monorepo directory `../gtk-runtime-<target>/gtk`, which is what
  *     an in-repo `npm run build:bundle` writes.
- *  4. the published `@gjsify/gtk-runtime-<target>` package's `gtk/`.
+ *  4. the published `@gjsify/gtk-runtime-<target>` package's `gtk/`, when the
+ *     author installed it.
+ *  5. the same package fetched for this run (`fetchedGtkRuntimeDir`) — NOT in
+ *     node-gi's probe, because node-gi never fetches: it finds the closure inside
+ *     the `.app` this function put it in, and the layout there is the same.
  *
  * A candidate counts only when it holds BOTH the loadable-code directory and the
  * typelib directory — node-gi's own probe, restated here rather than weakened,
@@ -150,8 +161,11 @@ export interface AppRuntimePaths {
     /** `<prebuildDir>/node_gi.node` — what `NODE_GI_NATIVE` pins. */
     addonPath: string;
     /**
-     * `<App>.app/Contents/MacOS/node`, or `<program dir>/node.exe` — beside the
-     * launcher that execs it, under the name the target's own release uses.
+     * `<App>.app/Contents/Helpers/<display name>`, or `<program dir>/node.exe`
+     * beside the launcher — darwin names it after the app (`layout.ts`'s
+     * `dirs.helpers`) so Activity Monitor and System Events show the app
+     * instead of `node`; Windows keeps the interpreter's own release name
+     * beside the `.cmd`, where nothing reads a process list by file name.
      */
     interpreterPath: string;
     /** Node's own LICENSE, under `Contents/Resources` (macOS) or `share/` (Windows). */
@@ -195,6 +209,10 @@ export interface StageAppRuntimeInput {
         nodePath: string;
         licensePath: string;
     } | null;
+    /** See {@link ResolveRuntimeOptions.fetchedGtkRuntimeDir}. */
+    fetchedGtkRuntimeDir?: string;
+    /** Why the fetch produced nothing — named in the `missing` line, so the cause is not guessed at. */
+    gtkFetchFailure?: string;
 }
 /**
  * Stage the interpreter, the GTK closure and the addon into one bundle.

package/lib/utils/ship/app-runtime.js

@@ -80,6 +80,7 @@
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join, posix, sep } from 'node:path';
 import { listFilesRecursive } from './discover.js';
+import { assertUsableAsHelperName } from './layout.js';
 import { nodeRuntimeBinaryName } from './node-runtime.js';
 import { isExecutableAsset } from './plan.js';
 import { resolveInstalledPackage } from '../resolve-npm-package.js';
@@ -123,7 +124,11 @@ export const NODE_GI_PACKAGE = '@gjsify/node-gi';
  *     for a ship run.
  *  3. the sibling monorepo directory `../gtk-runtime-<target>/gtk`, which is what
  *     an in-repo `npm run build:bundle` writes.
- *  4. the published `@gjsify/gtk-runtime-<target>` package's `gtk/`.
+ *  4. the published `@gjsify/gtk-runtime-<target>` package's `gtk/`, when the
+ *     author installed it.
+ *  5. the same package fetched for this run (`fetchedGtkRuntimeDir`) — NOT in
+ *     node-gi's probe, because node-gi never fetches: it finds the closure inside
+ *     the `.app` this function put it in, and the layout there is the same.
  *
  * A candidate counts only when it holds BOTH the loadable-code directory and the
  * typelib directory — node-gi's own probe, restated here rather than weakened,
@@ -155,6 +160,12 @@ export function resolveGtkRuntime(target, options = {}) {
     const entry = resolveStagedPackage(packageName, options);
     if (entry !== null)
         candidates.push({ source: packageName, dir: join(dirname(entry), 'gtk') });
+    if (options.fetchedGtkRuntimeDir !== undefined) {
+        candidates.push({
+            source: `${packageName} (fetched for this ship run)`,
+            dir: join(options.fetchedGtkRuntimeDir, 'gtk'),
+        });
+    }
     for (const candidate of candidates) {
         const libDir = join(candidate.dir, nativeSubdir);
         const typelibDir = join(candidate.dir, 'girepository-1.0');
@@ -254,20 +265,34 @@ export function appRuntimePaths(layout, identity, target) {
         prebuildDir,
         gtkDir: posix.join(prebuildDir, 'gtk'),
         addonPath: posix.join(prebuildDir, NODE_GI_ADDON_FILENAME),
-        // `Contents/MacOS`, because that is where a `.app` keeps executables and
-        // because `$here` — which the launcher already computes — is then the whole
-        // path expression. `dirs.native` would work for dyld and would make
-        // the launcher walk back up for the one file it execs. On Windows
-        // `dirs.launcher` is the program directory itself, so the interpreter lands
-        // beside the `.cmd` for the same reason.
+        // ON DARWIN, `Contents/Helpers/<display name>` — NEVER `Contents/MacOS`,
+        // because that directory already holds the launcher at `binaryName`, and
+        // APFS is case-insensitive by default: `stamped` and `Stamped` are the
+        // same file there, so no capitalisation of `binaryName` can share the
+        // directory with it. `Contents/Helpers` is one of Apple's own
+        // nested-code locations (`codesign(1)`'s bundle format, beside
+        // `Frameworks`, `PlugIns`, `XPCServices`), and naming the leaf after
+        // `identity.name` rather than `binaryName` is the whole point: Activity
+        // Monitor and System Events read a Mach-O process's name off its own
+        // FILE NAME, not off `exec -a` or any argv — measured by hand-editing a
+        // released `.app`, moving its interpreter to `Contents/Helpers/<App>`
+        // and rewriting the launcher's `exec` line, after which `ps -o comm` and
+        // System Events both read the app's name instead of `node`.
+        //
+        // Derived from the LAYOUT (`dirs.helpers !== ''`) rather than from
+        // `layout.name === 'darwin'`: only the darwin row sets `helpers` to a
+        // real directory (`layout.ts`), so this branch is "does this layout have
+        // a helpers seam", not a second darwin-specific fact typed out here.
         //
-        // THE LEAF COMES FROM `node-runtime.ts`, which is the module that already
-        // decided it for the SOURCE file — `node.exe` on win32, `node` elsewhere,
-        // read off the TARGET and never `process.platform` (assembling a Windows
-        // program directory on Linux is the supported path). Restating the rule here
-        // would let the two drift into a stage that copies `node.exe` to `node` and a
-        // launcher that execs neither.
-        interpreterPath: posix.join(dirs.launcher, nodeRuntimeBinaryName(target)),
+        // ON WINDOWS AND LINUX, unchanged: `dirs.launcher` and the leaf
+        // `node-runtime.ts` already decided for the SOURCE file — `node.exe` on
+        // win32, read off the TARGET and never `process.platform` (assembling a
+        // Windows program directory on Linux is the supported path). A Windows
+        // program directory has no launcher-collision to dodge in the first
+        // place, so its interpreter stays beside the `.cmd`.
+        interpreterPath: dirs.helpers === ''
+            ? posix.join(dirs.launcher, nodeRuntimeBinaryName(target))
+            : posix.join(dirs.helpers, assertUsableAsHelperName(identity.name)),
         // rpm's `share/licenses/<name>/LICENSE` shape, which the `macos-app` row
         // already uses for the app's own licence — one layout for a reader to learn,
         // and `node` is a name no `binaryName` can collide with silently: `placeStage`
@@ -340,8 +365,10 @@ export function stageAppRuntime(input) {
         // resolver then refuses -- a hint that is wrong is worse than none,
         // because it costs the reader the time to follow it first.
         const nativeSubdir = input.target.startsWith('win32-') ? 'bin' : 'lib';
-        missing.push(`no GTK closure — install \`${gtkRuntimePackageName(input.target)}\` (or point ` +
-            `\`GJSIFY_GTK_RUNTIME\` at a bundle directory holding \`${nativeSubdir}/\` and \`girepository-1.0/\`)`);
+        const why = input.gtkFetchFailure === undefined ? '' : ` — fetching it failed: ${input.gtkFetchFailure}`;
+        missing.push(`no GTK closure${why} — point \`GJSIFY_GTK_RUNTIME\` at a bundle directory holding ` +
+            `\`${nativeSubdir}/\` and \`girepository-1.0/\`, or install \`${gtkRuntimePackageName(input.target)}\` ` +
+            'where the build can reach it');
     }
     // node-gi's JavaScript, which the bundle `require`s by name. Staged whenever
     // the package is resolvable and reported separately from the addon: a bundle
@@ -394,6 +421,8 @@ function discoveryOptions(input) {
         options.env = input.env;
     if (input.resolve !== undefined)
         options.resolve = input.resolve;
+    if (input.fetchedGtkRuntimeDir !== undefined)
+        options.fetchedGtkRuntimeDir = input.fetchedGtkRuntimeDir;
     return options;
 }
 /**

package/lib/utils/ship/gtk-runtime-acquire.d.ts

@@ -0,0 +1,36 @@
+import { type GtkRuntimeTarget, type ResolveRuntimeOptions } from './app-runtime.js';
+export type AcquiredGtkRuntime = 
+/** Something already resolves — nothing was fetched, and nothing will be. */
+{
+    kind: 'present';
+}
+/** Fetched; `dir` is the PACKAGE directory, holding `gtk/`. */
+ | {
+    kind: 'fetched';
+    dir: string;
+}
+/** Could not be had; `reason` is what to tell the person, verbatim. */
+ | {
+    kind: 'failed';
+    reason: string;
+};
+export interface AcquireGtkRuntimeInput {
+    target: GtkRuntimeTarget;
+    /** The version to fetch: the CLI's own, because addon and closure are a matched pair. */
+    version: string;
+    /** The same discovery options the staging step will use — so "present" means what it will mean there. */
+    discovery?: ResolveRuntimeOptions;
+    /**
+     * Fetch a package spec into a cache and return its directory. Injected: the
+     * real one is `ensurePkgDir`, and a test must not touch a registry.
+     */
+    ensure: (spec: string) => Promise<string>;
+    /** One progress line. The closure is ~100 MB, so a silent first run looks like a hang. */
+    log?: (message: string) => void;
+}
+/**
+ * Make sure a GTK closure is reachable for `target`, fetching it only if nothing
+ * else provides one. Never throws: a ship run with no closure is a PARTIAL result
+ * that `stageAppRuntime` reports, not an error (see its doc).
+ */
+export declare function acquireGtkRuntime(input: AcquireGtkRuntimeInput): Promise<AcquiredGtkRuntime>;

package/lib/utils/ship/gtk-runtime-acquire.js

@@ -0,0 +1,59 @@
+// Getting the GTK closure for a ship run when the project does not carry it.
+//
+// WHY IT IS FETCHED AND NOT INSTALLED. `@gjsify/gtk-runtime-<target>` is 100 MB of
+// GLib, GObject, GTK and friends, and a project that lists it — as
+// `optionalDependencies`, which the `os`/`cpu` gate turns into "installed on every
+// Mac" — gets it into its own `node_modules`. On macOS that breaks every build and
+// every run that goes through a Homebrew GJS. Every darwin prebuild
+// carries the rpath `@loader_path` → `…/gtk-runtime-darwin-<arch>/gtk/lib` →
+// `<brew>/lib` (ADR 0023: bundle before system, `docs/prebuilds.md`), so the first
+// `dlopen` out of `node_modules/@gjsify/*-native-darwin-*` finds the bundle's
+// GLib/GObject beside the one `gjs` already loaded from Homebrew: two GObject type
+// registries in one process, which shows as `No signal 'context_response' on
+// object 'GVolumeMonitor'` and a segfault, or as `GNotificationCenterDelegate is
+// implemented in both …`. The invariant ADR 0023 names — one registry per process
+// — is violated by the dev tree itself.
+//
+// The closure is only ever needed at the moment it is COPIED into a bundle, so it
+// is acquired then: into the dlx cache (`ensurePkgDir`, the same machinery
+// `gjsify showcase` already uses for the same package), never into the project.
+// What this does NOT change: the search order in `resolveGtkRuntime()` keeps its
+// four existing candidates, so a project that still installs the package ships
+// exactly as before — it merely stays exposed to the dev-tree failure above until
+// it drops the dependency.
+//
+// EXACT VERSION, no range and no fallback. The addon's `@rpath` is
+// `@loader_path/gtk/lib` — addon and closure are a matched pair published from the
+// same release — so "the nearest published version" would be a guess about GTK ABI
+// that `assertPayloadMatchesArch` cannot check. A CLI version with no published
+// runtime (a dev or `next` build) fails with the reason named, and
+// `GJSIFY_GTK_RUNTIME` is the way past it.
+import { gtkRuntimePackageName, resolveGtkRuntime, } from './app-runtime.js';
+/**
+ * Make sure a GTK closure is reachable for `target`, fetching it only if nothing
+ * else provides one. Never throws: a ship run with no closure is a PARTIAL result
+ * that `stageAppRuntime` reports, not an error (see its doc).
+ */
+export async function acquireGtkRuntime(input) {
+    const discovery = input.discovery ?? {};
+    if (resolveGtkRuntime(input.target, discovery) !== null)
+        return { kind: 'present' };
+    const name = gtkRuntimePackageName(input.target);
+    const spec = `${name}@${input.version}`;
+    input.log?.(`${name} is not installed here, and is not meant to be — fetching ${spec} into the cache ` +
+        '(about 100 MB, once)');
+    let dir;
+    try {
+        dir = await input.ensure(spec);
+    }
+    catch (error) {
+        return { kind: 'failed', reason: error instanceof Error ? error.message : String(error) };
+    }
+    // The same completeness probe the staging step applies, so a package that
+    // resolved but holds no `gtk/` (an unpopulated checkout, a truncated cache
+    // entry) is reported HERE, with its name, instead of as a bare "no GTK closure".
+    if (resolveGtkRuntime(input.target, { ...discovery, fetchedGtkRuntimeDir: dir }) === null) {
+        return { kind: 'failed', reason: `${spec} was fetched to ${dir} but holds no complete gtk/ closure` };
+    }
+    return { kind: 'fetched', dir };
+}

package/lib/utils/ship/launcher.js

@@ -181,7 +181,16 @@ function renderPrefixLauncher(settings, bundleRelPath, layout) {
  * IT EXECS WHAT THE BUNDLE CARRIES. `runtime` comes from
  * `utils/ship/app-runtime.ts` and names the interpreter, the relocated GTK
  * closure and the node-gi addon staged inside `Contents/` — so the exec line is
- * `"$here/node"` and the two locators below point into `dirs.native`.
+ * `"$here/../Helpers/<display name>"` and the two locators below point into
+ * `dirs.native`. The interpreter is staged under `Contents/Helpers`, not
+ * `Contents/MacOS` beside this very script, and named after `identity.name`
+ * rather than kept as `node`: Activity Monitor and System Events read a
+ * process's name off the FILE NAME of the Mach-O that is running, not off argv
+ * or any `exec -a`, so a bundle whose carried interpreter is still called `node`
+ * shows up as `node` everywhere a user looks for it (`layout.ts`'s `dirs.helpers`,
+ * `app-runtime.ts`'s `appRuntimePaths`). `beside()` computes the relative hop
+ * from the actual two directories rather than assuming a sibling, so this
+ * function needs no special case for the rename.
  * When the stage carries none of them every line here is byte-identical to what
  * M2a wrote, which is what keeps a bundle assembled without the runtime packages
  * exactly as (un)usable as it was rather than differently broken.
@@ -308,10 +317,14 @@ function renderAppBundleLauncher(settings, bundleRelPath, layout, runtime) {
     if (settings.fontFiles.length > 0) {
         lines.push(`GJSIFY_FONT_DIR="$contents/${stagedFontDir(under(dirs.data), settings.appId)}"`, 'export GJSIFY_FONT_DIR');
     }
-    // `"$here/node"`, not `node`. The bare name is true of a developer's machine
-    // and false of a `.app` a stranger downloads, and the difference is not a
-    // degraded experience: macOS ships no Node at all, so the launcher's first act
-    // would be `exec: node: not found`.
+    // `"$here/../Helpers/<display name>"`, not a bare `node`. The bare name is
+    // true of a developer's machine and false of a `.app` a stranger downloads,
+    // and the difference is not a degraded experience: macOS ships no Node at
+    // all, so the launcher's first act would be `exec: node: not found`. The path
+    // is relative rather than the literal `../Helpers/…` written out, because
+    // `beside()` already carries the relation between `dirs.launcher` and
+    // wherever `appRuntimePaths` staged the interpreter — this function does not
+    // need to know that the leaf changed from `node` to `identity.name`.
     const interpreter = runtime.interpreter === undefined ? undefined : `"$here/${beside(runtime.interpreter)}"`;
     lines.push(`exec ${execLine(layout, `"$contents/${under(dirs.bundle)}/${bundleRelPath}"`, settings, interpreter)} "$@"`, '');
     return lines.join('\n');
@@ -462,8 +475,8 @@ function windowsPath(rel) {
  * `@gjsify/node-runtime-<target>` exists for; this comment used to say "the day a
  * stage carries one, THIS is the line that names it by a layout-relative path
  * instead", and #1354 M2b is that day — `utils/ship/app-runtime.ts` stages the
- * interpreter into `Contents/MacOS/node` and the `.app` launcher execs
- * `"$here/node"`.
+ * interpreter into `Contents/Helpers/<display name>` and the `.app` launcher
+ * execs `"$here/../Helpers/<display name>"`.
  *
  * #1354 M3 is the same day one OS over: the Windows layout stages `node.exe` into
  * the program directory and its `.cmd` runs `"%HERE%node.exe"`.

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

@@ -128,6 +128,15 @@ export interface LayoutDirs {
      * bundle can address it and `codesign` later refuses the bundle.
      */
     other: string;
+    /**
+     * macOS only: where a carried interpreter lives when it must NOT be named
+     * `binaryName` inside {@link LayoutDirs.launcher} — see
+     * `utils/ship/app-runtime.ts`'s `appRuntimePaths`. `''` on linux and windows,
+     * where nothing reads it: Linux takes its interpreter from the distribution,
+     * and a Windows program directory has no launcher-collision to dodge in the
+     * first place, so its interpreter stays beside the `.cmd`.
+     */
+    helpers: string;
 }
 /**
  * One operating system's layout.
@@ -290,6 +299,20 @@ export interface LayoutArches {
  * {@link LAYOUTS.linux.icon} for what asked for each of the three.
  */
 export declare const HICOLOR_RASTER_SIZES: readonly [64, 128, 256];
+/**
+ * Refuse an `identity.name` that cannot be the carried interpreter's own file
+ * name under `Contents/Helpers` (`dirs.helpers`) — `appRuntimePaths` in
+ * `utils/ship/app-runtime.ts` is the only caller.
+ *
+ * A SUPERSET of {@link BUNDLE_NAME_FORBIDDEN}, not a restatement: the bundle
+ * directory wraps the same string in `.app`, so a name of "." or ".." becomes
+ * "..app" or "....app" — both ordinary directory names — while this leaf is
+ * `identity.name` taken LITERALLY, where "." and ".." name the directory
+ * itself and its parent. An empty name and a NUL byte are refused for the same
+ * reason `windowsProgramDirName` refuses them one OS over: neither is a name a
+ * filesystem can hold.
+ */
+export declare function assertUsableAsHelperName(name: string): string;
 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[];