@gjsify/cli 0.64.5 → 0.64.7

package/lib/commands/ship.js

@@ -44,7 +44,7 @@ import { buildFlatpakBundle } from '../utils/ship/flatpak.js';
 import { iconSizes, resolveAppIcon } from '../utils/ship/icons.js';
 import { localizeMetadata } from '../utils/ship/localize-metadata.js';
 import { assertHostCanFinish, assertKindCanPack, assertToolsInstalled, canCarryTicket, configuredFormats, defaultFormatIds, formatIdsFor, resolveFormats, windowsProgramDirName, FORMAT_IDS, FORMATS, } from '../utils/ship/formats.js';
-import { assertLayoutSupportsArch, hostLayout, layoutForOs, place, placeStage, resolveLayout, LAYOUT_NAMES, } from '../utils/ship/layout.js';
+import { assertLayoutSupportsArch, hostLayout, layoutForOs, place, placeStage, resolveLayout, windowsGuiLauncherPath, LAYOUT_NAMES, LAYOUTS, } from '../utils/ship/layout.js';
 import { isNodeRuntimeTarget, resolveNodeRuntime } from '../utils/ship/node-runtime.js';
 import { isUnder, SHARE } from '../utils/ship/share-dirs.js';
 import { compileSchemasForPayload, compileSchemasForStage } from '../utils/ship/schemas.js';
@@ -501,7 +501,17 @@ async function assemble(args) {
     // `packOne` reads it again. That is the price of checking the tree that is
     // shipped rather than the bytes that happen to be in memory, and it is the
     // same reason `readStage` exists at all.
-    assertPayloadMatchesArch(readStage([stageDir], staged), settings.arch);
+    //
+    // ONE NAMED EXEMPTION: the windows GUI-launcher stub is x86-64 machine code
+    // on every windows arch by design (`pe-launcher.ts`'s `MACHINE_AMD64`
+    // comment) — it only `exec`s the sibling `.cmd`, which hands off to the
+    // arch-correct `node.exe` the stage carries, and Windows-on-ARM runs x64
+    // code through Prism for exactly this path. `layout.windows` now emits that
+    // stub unconditionally (it used to skip arm64 entirely), so an arm64 stage
+    // legitimately carries one x64 PE beside its arm64 payload.
+    assertPayloadMatchesArch(readStage([stageDir], staged), settings.arch, {
+        exempt: layout === LAYOUTS.windows ? new Set([windowsGuiLauncherPath(settings)]) : undefined,
+    });
     // What the map carried into a layout that has no install step for it.
     //
     // NOT a warning about this command's output being wrong — the files are the

package/lib/commands/showcase.js

@@ -268,7 +268,7 @@ function resolveLocalShowcaseDir(showcase) {
  */
 function gtkRuntimeSpecs(cliVersion) {
     const target = `${process.platform}-${process.arch}`;
-    const shipped = ['win32-x64', 'darwin-arm64', 'darwin-x64'];
+    const shipped = ['win32-x64', 'win32-arm64', 'darwin-arm64', 'darwin-x64'];
     if (!shipped.includes(target))
         return [];
     const name = `@gjsify/gtk-runtime-${target}`;

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';
 /**
@@ -10,7 +10,7 @@ import type { StagedFile } from './types.js';
  * deriving one from the other would make a future Linux GTK bundle silently imply
  * a bundled Linux interpreter (which `node-runtime.ts` refuses on purpose).
  */
-export declare const GTK_RUNTIME_TARGETS: readonly ["darwin-arm64", "darwin-x64", "win32-x64"];
+export declare const GTK_RUNTIME_TARGETS: readonly ["darwin-arm64", "darwin-x64", "win32-x64", "win32-arm64"];
 export type GtkRuntimeTarget = (typeof GTK_RUNTIME_TARGETS)[number];
 /** Is this `<platform>-<arch>` one of the published GTK-closure targets? */
 export declare function isGtkRuntimeTarget(target: string): target is GtkRuntimeTarget;
@@ -161,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). */

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';
@@ -92,7 +93,7 @@ import { resolveInstalledPackage } from '../resolve-npm-package.js';
  * deriving one from the other would make a future Linux GTK bundle silently imply
  * a bundled Linux interpreter (which `node-runtime.ts` refuses on purpose).
  */
-export const GTK_RUNTIME_TARGETS = ['darwin-arm64', 'darwin-x64', 'win32-x64'];
+export const GTK_RUNTIME_TARGETS = ['darwin-arm64', 'darwin-x64', 'win32-x64', 'win32-arm64'];
 /** Is this `<platform>-<arch>` one of the published GTK-closure targets? */
 export function isGtkRuntimeTarget(target) {
     return GTK_RUNTIME_TARGETS.includes(target);
@@ -264,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`.
         //
-        // 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)),
+        // 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.
+        //
+        // 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`

package/lib/utils/ship/formats.js

@@ -132,23 +132,19 @@ function macosArch(arch, _archIndependent) {
 /**
  * `process.arch` → the name Windows and everything that targets it use.
  *
- * ONE ROW, and it is not caution: there is no arm64 GTK CLOSURE to put on it yet.
- * `wingtk/gvsbuild` publishes no arm64 assets, which is why ADR 0089 builds that
- * prefix from our `gjsify/gvsbuild` fork in CI instead — but what a Windows
- * artifact stages is `@gjsify/gtk-runtime-*`, and the arm64 one is not built, so
- * there is nothing for a Windows/ARM artifact to load (#1117). `Layout.arches`
- * refuses the same value one phase earlier, at stage time, with that reason spelled
- * out; this table is the second half — the one that stops a stage assembled by an
- * older gjsify from acquiring a label here.
+ * TWO ROWS now. `wingtk/gvsbuild` still publishes x64 assets only, but ADR 0089
+ * builds the arm64 GTK prefix from our `gjsify/gvsbuild` fork in CI, and
+ * `@gjsify/gtk-runtime-win32-arm64` + `@gjsify/node-runtime-win32-arm64` exist —
+ * the two packages a Windows/ARM artifact stages (#1117, closed by this row).
  *
- * `x64` maps to itself, and unlike the macOS table that is not a coincidence to be
- * caught later: `x64` is the spelling Node's own release archives use
- * (`node-v24.20.0-win-x64.zip`), the spelling gvsbuild's assets use
- * (`GTK4_Gvsbuild_<v>_x64.zip`), and the spelling a `windows-latest x64` runner
- * label uses. `%PROCESSOR_ARCHITECTURE%` says `AMD64` and nothing a user downloads
- * is named after it.
+ * `x64` and `arm64` map to themselves, and unlike the macOS table that is not a
+ * coincidence to be caught later: both are the spelling Node's own release
+ * archives use (`node-v24.20.0-win-{x64,arm64}.zip`), the spelling a
+ * `windows-11-arm` runner's architecture is, and the spelling `--arch` already
+ * accepts everywhere else in this command. `%PROCESSOR_ARCHITECTURE%` says
+ * `AMD64`/`ARM64` and nothing a user downloads is named after that spelling.
  */
-const WINDOWS_ARCH = { x64: 'x64' };
+const WINDOWS_ARCH = { x64: 'x64', arm64: 'arm64' };
 function windowsArch(arch, _archIndependent) {
     return lookupArch(WINDOWS_ARCH, arch, 'Windows');
 }

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[];

package/lib/utils/ship/layout.js

@@ -75,6 +75,28 @@ function appBundleDir(identity) {
     }
     return `${identity.name}.app`;
 }
+/**
+ * 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 function assertUsableAsHelperName(name) {
+    if (name === '' || name === '.' || name === '..' || BUNDLE_NAME_FORBIDDEN.test(name) || name.includes('\u0000')) {
+        throw new Error(`gjsify ship: the macOS layout would name the carried interpreter "${name}" under ` +
+            '`Contents/Helpers`, and that is not usable as a file name — empty, ".", ".." and anything ' +
+            'containing "/", ":", "\\" or a NUL byte are refused. Set `gjsify.ship.name` to the display ' +
+            'name you want.');
+    }
+    return name;
+}
 /**
  * The rasters a row writes its icon from, or nothing for a CLI — and a refusal
  * for an application that arrives without them.
@@ -117,6 +139,7 @@ export const LAYOUTS = {
             native: `lib/${identity.binaryName}/gi`,
             data: 'share',
             other: '',
+            helpers: '',
         }),
         // 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
@@ -280,6 +303,14 @@ export const LAYOUTS = {
                 native: `${app}/Contents/Resources/native`,
                 data: `${app}/Contents/Resources/share`,
                 other: `${app}/Contents/Resources`,
+                // Apple's own nested-code location (alongside `Frameworks`,
+                // `PlugIns`, `XPCServices` — `codesign(1)`'s bundle format), and the
+                // one place `appRuntimePaths` can put the interpreter under a name
+                // that is not `binaryName`: `Contents/MacOS` already holds the
+                // launcher, and APFS is case-insensitive by default, so a second
+                // file there named `<BinaryName>` collides with it bytewise even
+                // when the casing differs.
+                helpers: `${app}/Contents/Helpers`,
             };
         },
         // The two files that make the directory a BUNDLE. Without `Info.plist`
@@ -411,7 +442,7 @@ export const LAYOUTS = {
         // LOADER: `lib/` is what the launcher prepends to `PATH`, because Windows
         // has no rpath — a DLL is found on `PATH`, in the directory of the image
         // that loaded it, or not at all.
-        dirs: () => ({ launcher: '', bundle: 'app', native: 'lib', data: 'share', other: '' }),
+        dirs: () => ({ launcher: '', bundle: 'app', native: 'lib', data: 'share', other: '', helpers: '' }),
         // NO METADATA, and one PROGRAM. A Windows installer's metadata lives in the
         // `.msi`'s own tables, not in a file inside the program directory —
         // `msi.ts` puts every such fact in the `Product`/`Package` attributes of the
@@ -450,39 +481,40 @@ export const LAYOUTS = {
             required: true,
         },
         metadata: (input) => {
+            // Unconditional on `input.arch` — see `pe-launcher.ts`'s `MACHINE_AMD64`
+            // comment for why: the stub is x86-64 machine code on EVERY windows arch,
+            // because all it does is `exec` the sibling `.cmd`, which hands off to the
+            // native `node.exe` the layout staged for that arch. This used to read
+            // `input.arch === 'x64'`, which silently emitted NO launcher stub — and
+            // therefore no icon and no `.exe` for the MSI shortcut to point at — on
+            // arm64, the one arch `arches.only` now admits besides x64.
             const icon = iconFor(input, 'windows');
-            return input.arch === 'x64'
-                ? [
-                    {
-                        path: windowsGuiLauncherPath(input),
-                        mode: 0o755,
-                        source: {
-                            kind: 'bytes',
-                            data: buildGuiLauncher({
-                                logLeaf: windowsLaunchLogLeaf(input),
-                                ...(icon === undefined ? {} : { icon: iconResources(icon) }),
-                            }),
-                        },
+            return [
+                {
+                    path: windowsGuiLauncherPath(input),
+                    mode: 0o755,
+                    source: {
+                        kind: 'bytes',
+                        data: buildGuiLauncher({
+                            logLeaf: windowsLaunchLogLeaf(input),
+                            ...(icon === undefined ? {} : { icon: iconResources(icon) }),
+                        }),
                     },
-                ]
-                : [];
+                },
+            ];
         },
-        // ONE, and the blocker is OURS now. `wingtk/gvsbuild` hardcodes
-        // `self.platform = "x64"` and publishes x64 assets only — but we stopped
-        // waiting for it: ADR 0089 builds the arm64 GTK prefix from
-        // `gjsify/gvsbuild` in our own CI and `@gjsify/node-gi` declares
-        // `win32-arm64` against it (#2003). What is missing is
-        // `@gjsify/gtk-runtime-win32-arm64`, the closure this layout stages and on
-        // Windows the only GTK there is, so a Windows/ARM artifact still has
-        // nothing to load. Adding arm64 to `only` is the PR that builds that
-        // package, not this one.
+        // TWO now. `wingtk/gvsbuild` still hardcodes `self.platform = "x64"` and
+        // publishes x64 assets only, but ADR 0089 builds the arm64 GTK prefix from
+        // our `gjsify/gvsbuild` fork in CI, `@gjsify/node-gi` ships a win32-arm64
+        // prebuild against it (#2003), and `@gjsify/gtk-runtime-win32-arm64` +
+        // `@gjsify/node-runtime-win32-arm64` now exist — the two packages this
+        // layout stages. Tracked in gjsify/gjsify#1117; remaining gaps (gstsoup,
+        // webgl, gamepad, WebView2 on arm64) are `status/open-todos/windows.md`
+        // § win32-arm64, not a reason to withhold the architecture.
         arches: {
-            only: ['x64'],
-            why: 'the arm64 GTK closure `@gjsify/gtk-runtime-win32-arm64` does not exist yet — the prefix it ' +
-                'would be built from is no longer missing, because ADR 0089 builds it from our `gjsify/gvsbuild` ' +
-                'fork in CI and `@gjsify/node-gi` ships a win32-arm64 prebuild against it — so what is left is ' +
-                'the runtime package this layout would stage, ordered in `status/open-todos/windows.md` and ' +
-                'tracked in gjsify/gjsify#1117',
+            only: ['x64', 'arm64'],
+            why: 'win32 runs on x64 natively and on arm64 via the MSVC closure ADR 0089 builds — both have a ' +
+                '`@gjsify/gtk-runtime-win32-*` and `@gjsify/node-runtime-win32-*` to stage',
         },
     },
 };