@gjsify/cli 0.64.23 → 0.64.24

package/lib/commands/ship.js

@@ -430,6 +430,7 @@ async function assemble(args) {
         identity: settings,
         nestedBundles: settings.nestedBundles,
         helperExecutables: settings.helperExecutables,
+        mainExecutable: settings.mainExecutableSource,
     });
     const stageInputs = {
         bundleFiles: discovered.bundleFiles,

package/lib/types/config-data.d.ts

@@ -776,6 +776,20 @@ export interface ConfigDataShip extends AppMetadata {
      * for the same reason as {@link ConfigDataShip.nestedBundles}.
      */
     helperExecutables?: ShipHelperExecutableOptions[];
+    /**
+     * An app-provided prebuilt Mach-O staged as the bundle's MAIN executable
+     * (`Contents/MacOS/<binaryName>`, the `CFBundleExecutable`); the generated
+     * `/bin/sh` launcher moves to `Contents/Resources/<binaryName>-launcher`. Darwin
+     * only — ignored with a stderr notice on other layouts (shape still validated).
+     * The Mach-O must `execv("<dir of its own executable>/../Resources/<binaryName>-launcher", argv)`
+     * for every argv it does not handle itself (ADR 0024, main-executable amendment).
+     */
+    mainExecutable?: ShipMainExecutableOptions;
+}
+/** `gjsify.ship.mainExecutable`. */
+export interface ShipMainExecutableOptions {
+    /** Package-relative path of the prebuilt Mach-O (thin or universal). */
+    source: string;
 }
 /** One entry of `gjsify.ship.nestedBundles`. */
 export interface ShipNestedBundleOptions {

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

@@ -26,6 +26,12 @@ export interface LayoutIdentity {
         name: string;
         gui: boolean;
     }[];
+    /**
+     * The darwin `.app` carries an app-provided Mach-O at `Contents/MacOS/<binaryName>`
+     * (`gjsify.ship.mainExecutable`), so the generated launcher moves to
+     * `Contents/Resources/<binaryName>-launcher`. Ignored by every other layout.
+     */
+    hasMainExecutable?: boolean;
 }
 /**
  * What a layout needs to render the metadata it OWNS.
@@ -346,6 +352,8 @@ export declare const LAYOUTS: Record<LayoutName, Layout>;
 export declare const LAYOUT_NAMES: LayoutName[];
 /** Stage-relative path of the launcher this layout puts in front of the app. */
 export declare function launcherPath(layout: Layout, identity: LayoutIdentity): string;
+/** Stage-relative path of the app-provided Mach-O main executable, the `CFBundleExecutable`. */
+export declare function mainExecutablePath(layout: Layout, identity: LayoutIdentity): string;
 /**
  * Stage-relative path of the windows layout's GUI launcher.
  *

package/lib/utils/ship/layout.js

@@ -563,6 +563,17 @@ export const LAYOUT_NAMES = Object.keys(LAYOUTS);
 const BY_OS = new Map(LAYOUT_NAMES.map((name) => [LAYOUTS[name].os, LAYOUTS[name]]));
 /** Stage-relative path of the launcher this layout puts in front of the app. */
 export function launcherPath(layout, identity) {
+    const dirs = layout.dirs(identity);
+    // Beside an app-provided Mach-O main the sh launcher is a RESOURCE, not nested code: a script in
+    // `Contents/MacOS` that is not the main executable keeps its signature only in an xattr, which our
+    // packers drop, while `Contents/Resources` is sealed by hash and needs no signature of its own.
+    if (layout.name === 'darwin' && identity.hasMainExecutable === true) {
+        return posix.join(dirs.other, `${identity.binaryName}-launcher${layout.launcherExt}`);
+    }
+    return posix.join(dirs.launcher, `${identity.binaryName}${layout.launcherExt}`);
+}
+/** Stage-relative path of the app-provided Mach-O main executable, the `CFBundleExecutable`. */
+export function mainExecutablePath(layout, identity) {
     return posix.join(layout.dirs(identity).launcher, `${identity.binaryName}${layout.launcherExt}`);
 }
 /**
@@ -715,7 +726,7 @@ export function place(layout, identity, rel) {
     // below, which has no extension: a windows `<name>` without `.cmd` is not runnable.
     const further = identity.executables?.find((executable) => rel === `bin/${executable.name}`);
     if (further !== undefined)
-        return launcherPath(layout, { ...identity, binaryName: further.name });
+        return launcherPath(layout, { ...identity, binaryName: further.name, hasMainExecutable: false });
     const libPrefix = `lib/${identity.binaryName}/`;
     const giPrefix = `${libPrefix}gi/`;
     if (rel.startsWith(giPrefix))

package/lib/utils/ship/nested-bundles.d.ts

@@ -1,4 +1,4 @@
-import type { Layout, LayoutIdentity } from './layout.js';
+import { type Layout, type LayoutIdentity } from './layout.js';
 import type { PayloadEntry } from './payload.js';
 import type { RecordedNestedBundle } from './release-record.js';
 import type { SignedSubordinate } from './signing.js';
@@ -22,6 +22,8 @@ export declare function stageSubordinates(input: {
     identity: LayoutIdentity;
     nestedBundles: readonly ShipNestedBundle[];
     helperExecutables: readonly ShipHelperExecutable[];
+    /** Absolute path of the app's own Mach-O main (`gjsify.ship.mainExecutable`), darwin only. */
+    mainExecutable?: string;
 }): StagedSubordinates;
 /**
  * What `signPayload` needs to sign the subordinates `stageSubordinates` staged —

package/lib/utils/ship/nested-bundles.js

@@ -19,6 +19,7 @@
 import { join, posix } from 'node:path';
 import { listFilesRecursive } from './discover.js';
 import { stagedMode } from './app-runtime.js';
+import { mainExecutablePath } from './layout.js';
 /**
  * Stage every `gjsify.ship.nestedBundles` entry and `gjsify.ship.helperExecutables`
  * entry into the layout's `plugins`/`helpers` slots.
@@ -61,6 +62,17 @@ export function stageSubordinates(input) {
         files.push({ path, mode: 0o755, source: { kind: 'file', path: helper.source } });
         helperExecutables.push({ path, entitlements: helper.entitlements });
     }
+    if (input.mainExecutable !== undefined) {
+        if (input.layout.name !== 'darwin') {
+            throw new Error(`gjsify ship: \`gjsify.ship.mainExecutable\` is darwin-only, but the ${input.layout.name} layout was asked ` +
+                'to stage it — report this as a gjsify bug.');
+        }
+        files.push({
+            path: mainExecutablePath(input.layout, input.identity),
+            mode: 0o755,
+            source: { kind: 'file', path: input.mainExecutable },
+        });
+    }
     return { files, nestedBundles, helperExecutables };
 }
 /**

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

@@ -208,6 +208,19 @@ export declare function resolveShipHelperExecutables(input: {
     projectDir: string;
     layoutOs: HostOs;
 }): ShipHelperExecutable[];
+/**
+ * `gjsify.ship.mainExecutable` → the app's own prebuilt Mach-O, staged as the
+ * `.app`'s `CFBundleExecutable`. Needed because macOS 27's
+ * `SFSafariExtensionManager` resolves the host app record only for the process
+ * whose executable IS `CFBundleExecutable` (ADR 0024 amendment). Same split as
+ * {@link resolveShipHelperExecutables}: shape on every host, existence and the
+ * Mach-O check on darwin only; ignored (`undefined`) elsewhere.
+ */
+export declare function resolveShipMainExecutable(input: {
+    declared: unknown;
+    projectDir: string;
+    layoutOs: HostOs;
+}): string | undefined;
 /** The entry one ship target installs, which key named it, and what it must NOT carry. */
 export interface ResolvedShipBundle {
     /** The declared path as written — project-relative or absolute. */

package/lib/utils/ship/settings.js

@@ -10,8 +10,9 @@
 // only) > derived from package.json. Never a yargs `default:`, which is
 // indistinguishable from a value the user typed and would clobber the config.
 import { validateMimeTypes } from './mime.js';
-import { existsSync } from 'node:fs';
+import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
 import { basename, isAbsolute, posix, relative, resolve, sep } from 'node:path';
+import { classifyBinary } from './payload.js';
 import { DEFAULT_GJS_FLOOR, DEFAULT_NODE_FLOOR } from './depends.js';
 import { resolveShipFlatpakSettings } from './flatpak-config.js';
 import { assertRelease, normaliseVersion } from './version.js';
@@ -207,10 +208,22 @@ export function resolveShipSettings(input) {
         projectDir: input.projectDir,
         layoutOs: input.cli.layoutOs,
     });
-    if (input.cli.layoutOs !== 'darwin' &&
-        ((Array.isArray(ship.nestedBundles) && ship.nestedBundles.length > 0) ||
-            (Array.isArray(ship.helperExecutables) && ship.helperExecutables.length > 0))) {
-        warnings.push(`gjsify ship: nestedBundles/helperExecutables apply to darwin only — not staged for ${input.cli.layoutOs}`);
+    const mainExecutableResolved = resolveShipMainExecutable({
+        declared: ship.mainExecutable,
+        projectDir: input.projectDir,
+        layoutOs: input.cli.layoutOs,
+    });
+    if (input.cli.layoutOs !== 'darwin') {
+        const ignored = [
+            ...(Array.isArray(ship.nestedBundles) && ship.nestedBundles.length > 0 ? ['nestedBundles'] : []),
+            ...(Array.isArray(ship.helperExecutables) && ship.helperExecutables.length > 0
+                ? ['helperExecutables']
+                : []),
+            ...(ship.mainExecutable !== undefined ? ['mainExecutable'] : []),
+        ];
+        if (ignored.length > 0) {
+            warnings.push(`gjsify ship: ${ignored.join('/')} apply to darwin only — not staged for ${input.cli.layoutOs}`);
+        }
     }
     const settings = {
         projectDir: input.projectDir,
@@ -250,6 +263,9 @@ export function resolveShipSettings(input) {
         }),
         nestedBundles: nestedBundlesResolved,
         helperExecutables: helperExecutablesResolved,
+        ...(mainExecutableResolved === undefined
+            ? {}
+            : { mainExecutableSource: mainExecutableResolved, hasMainExecutable: true }),
         outDir: input.cli.outDir ?? ship.outDir ?? 'ship',
         arch: input.cli.arch ?? process.arch,
         app,
@@ -455,6 +471,50 @@ export function resolveShipHelperExecutables(input) {
     });
     return input.layoutOs === 'darwin' ? resolved : [];
 }
+/**
+ * `gjsify.ship.mainExecutable` → the app's own prebuilt Mach-O, staged as the
+ * `.app`'s `CFBundleExecutable`. Needed because macOS 27's
+ * `SFSafariExtensionManager` resolves the host app record only for the process
+ * whose executable IS `CFBundleExecutable` (ADR 0024 amendment). Same split as
+ * {@link resolveShipHelperExecutables}: shape on every host, existence and the
+ * Mach-O check on darwin only; ignored (`undefined`) elsewhere.
+ */
+export function resolveShipMainExecutable(input) {
+    const { declared } = input;
+    if (declared === undefined)
+        return undefined;
+    if (typeof declared !== 'object' || declared === null || Array.isArray(declared)) {
+        throw new Error('gjsify ship: `gjsify.ship.mainExecutable` must be an object `{ "source" }`.');
+    }
+    const { source, ...unknown } = declared;
+    const stray = Object.keys(unknown);
+    if (stray.length > 0) {
+        throw new Error(`gjsify ship: \`gjsify.ship.mainExecutable\` has unknown key(s) ${stray.join(', ')}; known: source.`);
+    }
+    if (typeof source !== 'string' || source === '') {
+        throw new Error('gjsify ship: `gjsify.ship.mainExecutable.source` must be the project-relative path of a prebuilt Mach-O executable.');
+    }
+    if (input.layoutOs !== 'darwin')
+        return undefined;
+    const abs = isAbsolute(source) ? source : resolve(input.projectDir, source);
+    if (!existsSync(abs) || !statSync(abs).isFile()) {
+        throw new Error(`gjsify ship: \`gjsify.ship.mainExecutable.source\` ${source} does not exist or is not a file.`);
+    }
+    const head = Buffer.alloc(4);
+    const fd = openSync(abs, 'r');
+    try {
+        readSync(fd, head, 0, 4, 0);
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (classifyBinary(head) !== 'macho') {
+        throw new Error(`gjsify ship: \`gjsify.ship.mainExecutable.source\` ${source} is not a Mach-O binary (thin or universal). ` +
+            'macOS resolves the host app record only for a native main executable, and the Mac App Store refuses a script; ' +
+            'the generated launcher is staged as `Contents/Resources/<binaryName>-launcher`.');
+    }
+    return abs;
+}
 /**
  * The ONE place a ship target's ENTRY is decided — {@link resolveShipApp}'s twin.
  *

package/lib/utils/ship/stage-manifest.js

@@ -143,6 +143,8 @@ export function toPackSettings(settings) {
         executables: settings.executables.map(({ name, gui }) => ({ name, gui })),
         nestedBundles: settings.nestedBundles.map(({ name, entitlements }) => ({ name, entitlements })),
         helperExecutables: settings.helperExecutables.map(({ name, entitlements }) => ({ name, entitlements })),
+        // Only when true: a stage without the setting stays byte-identical.
+        ...(settings.hasMainExecutable === true ? { hasMainExecutable: true } : {}),
     };
 }
 /** Absolute path of a stage's manifest. */
@@ -531,6 +533,15 @@ function readPackSettings(data, at) {
                 entitlements: expectArray(row.entitlements, field(`helperExecutables[${index}].entitlements`)).map((key, keyIndex) => expectString(key, field(`helperExecutables[${index}].entitlements[${keyIndex}]`))),
             };
         }),
+        // OPTIONAL on read: absent in every stage written before `gjsify.ship.mainExecutable`.
+        ...(data.hasMainExecutable === undefined
+            ? {}
+            : (() => {
+                if (typeof data.hasMainExecutable !== 'boolean') {
+                    throw new Error(`gjsify ship: ${field('hasMainExecutable')} must be a boolean.`);
+                }
+                return data.hasMainExecutable ? { hasMainExecutable: true } : {};
+            })()),
     };
 }
 /**

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

@@ -427,6 +427,12 @@ export interface PackSettings {
      * {@link PackSettings.nestedBundles}, one directory over (`dirs.helpers`).
      */
     helperExecutables: ShipHelperExecutableFacts[];
+    /**
+     * `true` when the darwin `.app` carries an app-provided Mach-O as its main executable
+     * (`gjsify.ship.mainExecutable`) and the generated launcher lives at
+     * `Contents/Resources/<binaryName>-launcher`. Absent = `false`.
+     */
+    hasMainExecutable?: boolean;
 }
 /** What the packing host needs to know about one further executable. */
 export interface ShipExecutableFacts {
@@ -584,6 +590,13 @@ export interface ShipSettings extends PackSettings {
      * Darwin-only, like {@link ShipSettings.nestedBundles}.
      */
     helperExecutables: ShipHelperExecutable[];
+    /**
+     * Absolute path of the app's own prebuilt Mach-O main executable
+     * (`gjsify.ship.mainExecutable`), darwin only; absent when none.
+     */
+    mainExecutableSource?: string;
+    /** `true` iff {@link mainExecutableSource} is set. */
+    hasMainExecutable?: boolean;
     /**
      * Absolute paths of the font faces the application ships (`gjsify.ship.fonts`).
      *

package/package.json

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