@gjsify/cli 0.64.20 → 0.64.21

package/lib/commands/ship.js

@@ -35,6 +35,7 @@ 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 { recordedNestedBundles, signedSubordinatesFor, stageSubordinates } from '../utils/ship/nested-bundles.js';
 import { resolveNodeModulesClosure, stageNodeModules } from '../utils/ship/node-modules.js';
 import { acquireGtkRuntime } from '../utils/ship/gtk-runtime-acquire.js';
 import { discoverPayload } from '../utils/ship/discover.js';
@@ -419,6 +420,17 @@ async function assemble(args) {
     // distribution update ever patches.
     const runtime = await resolveCarriedRuntime(layout, settings, projectDir);
     carryNodeModules(runtime, layout, settings, projectDir, ship.nodeModules, ship.nodeModulesExclude);
+    // The nested bundles and helper executables ADR 0026 § 6 needed by hand —
+    // staged like the runtime above (tree-preserving, stage-relative, through
+    // `placeStage`'s `carried` seam), and never through `gjsify.ship.bundledTypelibs`'s
+    // flattening map for the reason `app-runtime.ts`'s header gives: a `.appex`'s
+    // internal relations survive only if its tree is copied as a tree.
+    const subordinates = stageSubordinates({
+        layout,
+        identity: settings,
+        nestedBundles: settings.nestedBundles,
+        helperExecutables: settings.helperExecutables,
+    });
     const stageInputs = {
         bundleFiles: discovered.bundleFiles,
         launcher: renderLauncher(settings, basename(settings.bundlePath), layout, runtime.launcher),
@@ -489,7 +501,7 @@ async function assemble(args) {
         : undefined;
     if (icon !== undefined)
         console.log(`${LOG} icon: ${iconSizes(icon).join('/')} px, ${icon.source}`);
-    const staged = placeStage(layout, { ...settings, icon }, planned, runtime.files);
+    const staged = placeStage(layout, { ...settings, icon }, planned, [...runtime.files, ...subordinates.files]);
     writeStage(stageDir, staged);
     console.log(`${LOG} staged ${staged.length} file(s) for ${layout.name} in ${relative(projectDir, stageDir)}/`);
     if (args.verbose)
@@ -1078,6 +1090,12 @@ async function packOne(input) {
     // `signed/<id>/` is scratch this function owns. The arriving stage is never
     // written to: `writeStage` wipes what it is pointed at, and a re-signed file
     // in it would fail the very `readStage` above on the next run.
+    // DERIVED, not carried: the stage-relative path of a nested bundle or helper
+    // executable is `layout.dirs(settings).plugins`/`.helpers` joined with its
+    // name, computable from `settings` alone on either host — see
+    // `nested-bundles.ts`'s `signedSubordinatesFor` header for why that is what
+    // keeps this call and `stageSubordinates` from disagreeing about a path.
+    const subordinates = signedSubordinatesFor(layout, settings, settings);
     const payload = input.sign.kind === 'sign'
         ? await signPayload({
             payload: assembled,
@@ -1091,6 +1109,8 @@ async function packOne(input) {
             // with the payload, so an entitlements plist written into it would
             // read as a file `codesign` added.
             entitlementsPath: join(outRoot, 'signed', `${format.id}.entitlements.plist`),
+            nestedBundles: subordinates.nestedBundles,
+            helperExecutables: subordinates.helperExecutables,
             verbose: input.verbose,
             log: (line) => console.log(`${LOG} ${line}`),
         })
@@ -1429,6 +1449,7 @@ async function packOne(input) {
             signature: recordedSignature(input.sign.kind === 'sign' ? input.sign.identity : undefined, ADHOC_IDENTITY),
             notarized,
             stapled,
+            nestedBundles: recordedNestedBundles(payload, subordinates.nestedBundles),
             generator: `@gjsify/cli ${cliVersion()}`,
         });
         if (input.verbose)

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

@@ -753,6 +753,51 @@ export interface ConfigDataShip extends AppMetadata {
      * is the default path and a legitimate output (ADR 0024 § A13).
      */
     sign?: ShipSignOptions;
+    /**
+     * Further BUNDLES this package's darwin container embeds — e.g. a Safari Web
+     * Extension `.appex` built by `xcrun safari-web-extension-packager`. Each is
+     * copied wholesale into `Contents/PlugIns/` and signed+sealed as its OWN
+     * bundle, with its OWN entitlements, before the outer `.app` is sealed
+     * (ADR 0024 § A12-§ A17; the beifahrer ADR this answers: 0026 § 6).
+     *
+     * `Contents/PlugIns` is Apple's own nested-code location (`codesign(1)`'s
+     * bundle format, beside `Frameworks`/`Helpers`/`XPCServices`); no other
+     * layout has an equivalent slot, so this is refused outside
+     * `gjsify ship darwin`.
+     */
+    nestedBundles?: ShipNestedBundleOptions[];
+    /**
+     * Prebuilt helper EXECUTABLES this package carries beside the carried
+     * interpreter, in `Contents/Helpers/` — e.g. a small Swift binary with no GI
+     * binding (`SafariServices` has none), execed via `Gio.Subprocess`. Signed
+     * with its OWN entitlements before the outer `.app` is sealed. Darwin only,
+     * for the same reason as {@link ConfigDataShip.nestedBundles}.
+     */
+    helperExecutables?: ShipHelperExecutableOptions[];
+}
+/** One entry of `gjsify.ship.nestedBundles`. */
+export interface ShipNestedBundleOptions {
+    /** Project-relative directory holding the built bundle (e.g. the `.appex`). */
+    source: string;
+    /** Destination leaf under `Contents/PlugIns/` — keep the source's own extension. */
+    name: string;
+    /**
+     * Entitlements this bundle is signed and sealed with, REPLACING the outer
+     * signer's own set rather than adding to it: a sandboxed extension keeps the
+     * sandbox entitlements its packager wrote (`com.apple.security.app-sandbox`,
+     * file access) and must not inherit the host app's JIT/dyld-environment
+     * grants (ADR 0026 § 5). Absent or `[]` signs with none.
+     */
+    entitlements?: string[];
+}
+/** One entry of `gjsify.ship.helperExecutables`. */
+export interface ShipHelperExecutableOptions {
+    /** Project-relative path of the prebuilt executable. */
+    source: string;
+    /** Destination leaf under `Contents/Helpers/`. */
+    name: string;
+    /** Entitlements this helper is signed with. Absent or `[]` signs with none. */
+    entitlements?: string[];
 }
 /** One entry of `gjsify.ship.executables`. */
 export interface ShipExecutableOptions {

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

@@ -233,3 +233,24 @@ export interface StageAppRuntimeInput {
  * under `gtk/` on the other side of the copy.
  */
 export declare function stageAppRuntime(input: StageAppRuntimeInput): StagedAppRuntime;
+/**
+ * The mode one staged closure file gets.
+ *
+ * THREE tests, and each covers a case the others do not:
+ *
+ *  * the source's own execute bit — the truth when the closure came off a real
+ *    filesystem, and the ONLY thing that knows `libexec/gstreamer-1.0/gst-plugin-scanner`
+ *    is a program (it has no extension, and GStreamer forks it out-of-process so a
+ *    plugin that crashes on load cannot take the app down with it);
+ *  * the shared-library spelling, shared with `plan.ts` rather than restated —
+ *    load-bearing because `actions/upload-artifact` stores NO POSIX mode, so a
+ *    closure that arrived through a CI artifact has 0644 on every file and the
+ *    source-mode test above is blind on exactly the path this milestone's own CI
+ *    leg takes;
+ *  * `libexec/` and `bin/`, for the same reason applied to the extensionless
+ *    programs the artifact round trip flattened.
+ *
+ * A dylib does not need the execute bit to be `dlopen`'d, so this is not about
+ * making the closure loadable — it is about the two files that are EXEC'd.
+ */
+export declare function stagedMode(rel: string, abs: string): number;

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

@@ -445,7 +445,7 @@ function discoveryOptions(input) {
  * A dylib does not need the execute bit to be `dlopen`'d, so this is not about
  * making the closure loadable — it is about the two files that are EXEC'd.
  */
-function stagedMode(rel, abs) {
+export function stagedMode(rel, abs) {
     if (isExecutableAsset(rel))
         return 0o755;
     if (rel.startsWith('libexec/') || rel.startsWith('bin/'))

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

@@ -145,6 +145,17 @@ export interface LayoutDirs {
      * first place, so its interpreter stays beside the `.cmd`.
      */
     helpers: string;
+    /**
+     * macOS only: where a NESTED BUNDLE lives — `Contents/PlugIns`, Apple's own
+     * slot for a `.appex` (`codesign(1)`'s bundle format, beside `Frameworks`,
+     * `Helpers`, `XPCServices`). `''` on linux and windows, where neither a
+     * prefix nor a program directory has an equivalent: a Flatpak sandbox has no
+     * App Extension model and a Windows program directory has nothing Apple's
+     * extension points name. `gjsify.ship.nestedBundles` is refused outright on
+     * any layout where this is `''` (ADR 0024 amendment, "nested bundles and
+     * helper executables"; the beifahrer ADR this answers: 0026 § 6).
+     */
+    plugins: string;
 }
 /**
  * One operating system's layout.

package/lib/utils/ship/layout.js

@@ -140,6 +140,7 @@ export const LAYOUTS = {
             data: 'share',
             other: '',
             helpers: '',
+            plugins: '',
         }),
         // 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
@@ -319,6 +320,8 @@ export const LAYOUTS = {
                 // file there named `<BinaryName>` collides with it bytewise even
                 // when the casing differs.
                 helpers: `${app}/Contents/Helpers`,
+                // Apple's own slot for a nested `.appex` — see `LayoutDirs.plugins`.
+                plugins: `${app}/Contents/PlugIns`,
             };
         },
         // The two files that make the directory a BUNDLE. Without `Info.plist`
@@ -450,7 +453,15 @@ 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: '', helpers: '' }),
+        dirs: () => ({
+            launcher: '',
+            bundle: 'app',
+            native: 'lib',
+            data: 'share',
+            other: '',
+            helpers: '',
+            plugins: '',
+        }),
         // 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

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

@@ -0,0 +1,60 @@
+import type { Layout, LayoutIdentity } from './layout.js';
+import type { PayloadEntry } from './payload.js';
+import type { RecordedNestedBundle } from './release-record.js';
+import type { SignedSubordinate } from './signing.js';
+import type { ShipHelperExecutable, ShipHelperExecutableFacts, ShipNestedBundle, ShipNestedBundleFacts, StagedFile } from './types.js';
+/** The staged files, and what `signPayload` needs to sign them with their OWN entitlements. */
+export interface StagedSubordinates {
+    files: StagedFile[];
+    nestedBundles: SignedSubordinate[];
+    helperExecutables: SignedSubordinate[];
+}
+/**
+ * Stage every `gjsify.ship.nestedBundles` entry and `gjsify.ship.helperExecutables`
+ * entry into the layout's `plugins`/`helpers` slots.
+ *
+ * `[]` for both inputs is the common case and produces `{ files: [], ... }` —
+ * cheap enough that `commands/ship.ts` can call this unconditionally rather than
+ * branching on whether a project declares either key.
+ */
+export declare function stageSubordinates(input: {
+    layout: Layout;
+    identity: LayoutIdentity;
+    nestedBundles: readonly ShipNestedBundle[];
+    helperExecutables: readonly ShipHelperExecutable[];
+}): StagedSubordinates;
+/**
+ * What `signPayload` needs to sign the subordinates `stageSubordinates` staged —
+ * DERIVED from the layout and the facts alone, never carried as a separate
+ * closure.
+ *
+ * This is what lets `PackSettings` carry only `{ name, entitlements }` (see
+ * `types.ts`): the stage-relative PATH is `layout.dirs(settings).plugins` (or
+ * `.helpers`) joined with the name, which both the assembling host (which also
+ * has the absolute `source`) and a `--from-stage` finishing host (which has
+ * neither) can compute from data they already hold. Calling this twice — once
+ * in `assemble()`, once in `packOne` — can therefore never disagree with where
+ * {@link stageSubordinates} put the bytes.
+ */
+export declare function signedSubordinatesFor(layout: Layout, identity: LayoutIdentity, facts: {
+    nestedBundles: readonly ShipNestedBundleFacts[];
+    helperExecutables: readonly ShipHelperExecutableFacts[];
+}): {
+    nestedBundles: SignedSubordinate[];
+    helperExecutables: SignedSubordinate[];
+};
+/**
+ * What the release record says about each nested bundle, read off its OWN
+ * `Info.plist` rather than off `gjsify.ship.nestedBundles` — the declaration
+ * names a `source` directory and an entitlements list, neither of which is the
+ * bundle identifier or its extension point, and both of THOSE only exist inside
+ * the `.appex` the project built.
+ *
+ * `extensionPoint` comes from `NSExtension.NSExtensionPointIdentifier`, Apple's
+ * own nesting for every extension point (`com.apple.Safari.web-extension` is
+ * one value among several, not a special case this reader has to know). A
+ * nested bundle that is not an extension at all — or whose `Info.plist` this
+ * reader cannot find or parse — simply omits the key, which is the same
+ * additive contract the field's own doc states (`release-record.ts`).
+ */
+export declare function recordedNestedBundles(payload: readonly PayloadEntry[], nestedBundles: readonly SignedSubordinate[]): RecordedNestedBundle[];

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

@@ -0,0 +1,140 @@
+// Staging darwin's nested bundles and helper executables into the payload
+// (ADR 0024 amendment, "nested bundles and helper executables"; the beifahrer
+// ADR this answers: 0026 § 6).
+//
+// A consumer whose Xcode-built shell was discarded in favour of ADR 0026's "one
+// app" decision still has ONE bundle `gjsify ship darwin` cannot carry on its
+// own: a Safari Web Extension `.appex`, which macOS registers only when it
+// sits under the PARENT app's `Contents/PlugIns/`. This module is the staging
+// half of that gap — copy the built `.appex` (or any other nested bundle) and
+// any prebuilt helper executable into the layout's own slots for them
+// (`Layout.dirs().plugins` / `.helpers`), tree-preserving for the former and
+// flat for the latter, because a bundle is a DIRECTORY and a helper is a FILE.
+//
+// SIGNING is a separate concern, in `signing.ts`: this module only decides
+// WHERE the bytes land, never how they are signed. `stagedSubordinates` hands
+// back the stage-relative paths `commands/ship.ts` passes to `signPayload` as
+// `nestedBundles`/`helperExecutables`, so the two modules cannot drift on what
+// a "nested bundle" or a "helper executable" even IS.
+import { join, posix } from 'node:path';
+import { listFilesRecursive } from './discover.js';
+import { stagedMode } from './app-runtime.js';
+/**
+ * Stage every `gjsify.ship.nestedBundles` entry and `gjsify.ship.helperExecutables`
+ * entry into the layout's `plugins`/`helpers` slots.
+ *
+ * `[]` for both inputs is the common case and produces `{ files: [], ... }` —
+ * cheap enough that `commands/ship.ts` can call this unconditionally rather than
+ * branching on whether a project declares either key.
+ */
+export function stageSubordinates(input) {
+    const dirs = input.layout.dirs(input.identity);
+    const files = [];
+    const nestedBundles = [];
+    const helperExecutables = [];
+    for (const bundle of input.nestedBundles) {
+        if (dirs.plugins === '') {
+            throw new Error(`gjsify ship: the ${input.layout.name} layout has no \`Contents/PlugIns\` equivalent, so ` +
+                `the nested bundle "${bundle.name}" has nowhere to go. ` +
+                '`gjsify.ship.nestedBundles` is darwin-only; `resolveShipSettings` should have refused ' +
+                'this already — report this as a gjsify bug if it did not.');
+        }
+        const bundleRoot = posix.join(dirs.plugins, bundle.name);
+        for (const rel of listFilesRecursive(bundle.source)) {
+            const abs = join(bundle.source, ...rel.split(posix.sep));
+            files.push({
+                path: posix.join(bundleRoot, rel),
+                mode: stagedMode(rel, abs),
+                source: { kind: 'file', path: abs },
+            });
+        }
+        nestedBundles.push({ path: bundleRoot, entitlements: bundle.entitlements });
+    }
+    for (const helper of input.helperExecutables) {
+        if (dirs.helpers === '') {
+            throw new Error(`gjsify ship: the ${input.layout.name} layout has no \`Contents/Helpers\` equivalent, so ` +
+                `the helper executable "${helper.name}" has nowhere to go. ` +
+                '`gjsify.ship.helperExecutables` is darwin-only; `resolveShipSettings` should have refused ' +
+                'this already — report this as a gjsify bug if it did not.');
+        }
+        const path = posix.join(dirs.helpers, helper.name);
+        files.push({ path, mode: 0o755, source: { kind: 'file', path: helper.source } });
+        helperExecutables.push({ path, entitlements: helper.entitlements });
+    }
+    return { files, nestedBundles, helperExecutables };
+}
+/**
+ * What `signPayload` needs to sign the subordinates `stageSubordinates` staged —
+ * DERIVED from the layout and the facts alone, never carried as a separate
+ * closure.
+ *
+ * This is what lets `PackSettings` carry only `{ name, entitlements }` (see
+ * `types.ts`): the stage-relative PATH is `layout.dirs(settings).plugins` (or
+ * `.helpers`) joined with the name, which both the assembling host (which also
+ * has the absolute `source`) and a `--from-stage` finishing host (which has
+ * neither) can compute from data they already hold. Calling this twice — once
+ * in `assemble()`, once in `packOne` — can therefore never disagree with where
+ * {@link stageSubordinates} put the bytes.
+ */
+export function signedSubordinatesFor(layout, identity, facts) {
+    const dirs = layout.dirs(identity);
+    return {
+        nestedBundles: facts.nestedBundles.map((bundle) => ({
+            path: posix.join(dirs.plugins, bundle.name),
+            entitlements: bundle.entitlements,
+        })),
+        helperExecutables: facts.helperExecutables.map((helper) => ({
+            path: posix.join(dirs.helpers, helper.name),
+            entitlements: helper.entitlements,
+        })),
+    };
+}
+/**
+ * One `<key>NAME</key>` entry's string value, read with a REGEX rather than a
+ * plist parser — the same tradeoff this tree already makes in `plist.ts`
+ * (renders XML by string template, never parses it): a release record is
+ * additive metadata, not a signature the pack path depends on, so a plist this
+ * reader cannot follow degrades to an absent field rather than a build failure.
+ */
+function plistStringValue(xml, key) {
+    const match = new RegExp(`<key>${key}</key>\\s*<string>([^<]*)</string>`).exec(xml);
+    return match?.[1];
+}
+/**
+ * The `Info.plist` of one nested bundle, read back off the PACKED payload —
+ * after `signPayload` has run, so this sees exactly the bytes the artifact
+ * ships, never the assembling host's copy.
+ */
+function nestedBundlePlist(payload, bundlePath) {
+    const entry = payload.find((file) => file.path === posix.join(bundlePath, 'Contents', 'Info.plist'));
+    return entry === undefined ? undefined : new TextDecoder().decode(entry.data);
+}
+/**
+ * What the release record says about each nested bundle, read off its OWN
+ * `Info.plist` rather than off `gjsify.ship.nestedBundles` — the declaration
+ * names a `source` directory and an entitlements list, neither of which is the
+ * bundle identifier or its extension point, and both of THOSE only exist inside
+ * the `.appex` the project built.
+ *
+ * `extensionPoint` comes from `NSExtension.NSExtensionPointIdentifier`, Apple's
+ * own nesting for every extension point (`com.apple.Safari.web-extension` is
+ * one value among several, not a special case this reader has to know). A
+ * nested bundle that is not an extension at all — or whose `Info.plist` this
+ * reader cannot find or parse — simply omits the key, which is the same
+ * additive contract the field's own doc states (`release-record.ts`).
+ */
+export function recordedNestedBundles(payload, nestedBundles) {
+    return nestedBundles.map((bundle) => {
+        const name = posix.basename(bundle.path);
+        const xml = nestedBundlePlist(payload, bundle.path);
+        if (xml === undefined)
+            return { name };
+        const bundleId = plistStringValue(xml, 'CFBundleIdentifier');
+        const extensionPoint = plistStringValue(xml, 'NSExtensionPointIdentifier');
+        return {
+            name,
+            ...(bundleId === undefined ? {} : { bundleId }),
+            ...(extensionPoint === undefined ? {} : { extensionPoint }),
+        };
+    });
+}

package/lib/utils/ship/release-record.d.ts

@@ -24,9 +24,37 @@ export interface ReleaseRecord {
     signature: RecordedSignature;
     notarized: boolean;
     stapled: boolean;
+    /**
+     * Bundles embedded under `Contents/PlugIns/` (`gjsify.ship.nestedBundles`) —
+     * `[]` for an artifact with none. ADDITIVE and backward-compatible: an older
+     * record with no such key is still a valid `schema: 1` record, because this
+     * is the first consumer of the field and nothing reads its absence as a
+     * claim. Named rather than counted, for `@gjsify/site` to tell a Safari
+     * extension apart from an unrelated nested bundle a future consumer adds —
+     * `extensionPoint` is what lets it do that without parsing `Info.plist`
+     * itself.
+     */
+    nestedBundles: RecordedNestedBundle[];
     /** `@gjsify/cli <version>` — who wrote this record. */
     generator: string;
 }
+/**
+ * One nested bundle this artifact's `Contents/PlugIns/` carries, as the site
+ * needs to know it — e.g. a Safari Web Extension's `com.apple.Safari.web-extension`.
+ */
+export interface RecordedNestedBundle {
+    /** Leaf under `Contents/PlugIns/` — `gjsify.ship.nestedBundles[].name`. */
+    name: string;
+    /** `CFBundleIdentifier` from the bundle's own `Info.plist`, when it has one. */
+    bundleId?: string;
+    /**
+     * `NSExtension.NSExtensionPointIdentifier` from `Info.plist`, when the
+     * bundle declares an extension point — `com.apple.Safari.web-extension` for
+     * a Safari Web Extension. Absent for a nested bundle that is not an
+     * extension at all.
+     */
+    extensionPoint?: string;
+}
 export interface ReleaseRecordInput {
     /** Absolute path of the finished artifact file. */
     file: string;
@@ -36,6 +64,8 @@ export interface ReleaseRecordInput {
     signature: RecordedSignature;
     notarized: boolean;
     stapled: boolean;
+    /** `[]` for an artifact with no nested bundle. */
+    nestedBundles: RecordedNestedBundle[];
     generator: string;
 }
 export declare function releaseRecordPath(artifact: string): string;

package/lib/utils/ship/release-record.js

@@ -44,6 +44,7 @@ export function buildReleaseRecord(input) {
         signature: input.signature,
         notarized: input.notarized,
         stapled: input.stapled,
+        nestedBundles: input.nestedBundles,
         generator: input.generator,
     };
 }

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

@@ -1,5 +1,5 @@
 import type { AppMetadata, ConfigDataFlatpak, ConfigDataShip, DescriptionBlock, ShipAppOptions } from '../../types/config-data.js';
-import type { HostOs, ShipExecutable, ShipSettings } from './types.js';
+import type { HostOs, ShipExecutable, ShipHelperExecutable, ShipNestedBundle, ShipSettings } from './types.js';
 /** The subset of `package.json` the resolver reads. */
 export interface ShipPackageManifest {
     name?: string;
@@ -177,6 +177,31 @@ export declare function resolveShipExecutables(input: {
     projectDir: string;
     bundleDir: string;
 }): ShipExecutable[];
+/**
+ * `gjsify.ship.nestedBundles` → the further bundles the darwin container embeds
+ * under `Contents/PlugIns/` — e.g. a Safari Web Extension `.appex`.
+ *
+ * Darwin-only by construction: `layoutOs !== 'darwin'` refuses a non-empty list
+ * rather than silently dropping it, because `Contents/PlugIns` has no
+ * equivalent on the other two layouts (ADR 0024 amendment, "nested bundles and
+ * helper executables"; the beifahrer ADR this answers: 0026 § 6).
+ */
+export declare function resolveShipNestedBundles(input: {
+    declared: unknown;
+    projectDir: string;
+    layoutOs: HostOs;
+}): ShipNestedBundle[];
+/**
+ * `gjsify.ship.helperExecutables` → prebuilt executables staged into
+ * `Contents/Helpers/` beside the carried interpreter — e.g. a small Swift
+ * helper with no GI binding. Darwin-only, for the same reason as
+ * {@link resolveShipNestedBundles}.
+ */
+export declare function resolveShipHelperExecutables(input: {
+    declared: unknown;
+    projectDir: string;
+    layoutOs: HostOs;
+}): ShipHelperExecutable[];
 /** 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. */