@gjsify/cli 0.64.19 → 0.64.21

package/lib/utils/ship/settings.js

@@ -10,6 +10,7 @@
 // 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 { basename, isAbsolute, posix, relative, resolve, sep } from 'node:path';
 import { DEFAULT_GJS_FLOOR, DEFAULT_NODE_FLOOR } from './depends.js';
 import { resolveShipFlatpakSettings } from './flatpak-config.js';
@@ -227,6 +228,16 @@ export function resolveShipSettings(input) {
             projectDir: input.projectDir,
             bundleDir: discovered.bundleDir,
         }),
+        nestedBundles: resolveShipNestedBundles({
+            declared: ship.nestedBundles,
+            projectDir: input.projectDir,
+            layoutOs: input.cli.layoutOs,
+        }),
+        helperExecutables: resolveShipHelperExecutables({
+            declared: ship.helperExecutables,
+            projectDir: input.projectDir,
+            layoutOs: input.cli.layoutOs,
+        }),
         outDir: input.cli.outDir ?? ship.outDir ?? 'ship',
         arch: input.cli.arch ?? process.arch,
         app,
@@ -292,6 +303,143 @@ export function resolveShipExecutables(input) {
         return { name, entry: rel.split(sep).join(posix.sep), gui: gui === true };
     });
 }
+/** A `Contents/PlugIns` or `Contents/Helpers` leaf: no path separator, no NUL, not empty. */
+function assertUsableBundleLeaf(name, at, under) {
+    if (name === '' ||
+        name === '.' ||
+        name === '..' ||
+        name.includes('/') ||
+        name.includes('\\') ||
+        name.includes('\u0000')) {
+        throw new Error(`gjsify ship: \`${at}.name\` "${name}" is not usable as a leaf under \`${under}\` — empty and ` +
+            '".", "..", and anything containing "/", "\\" or a NUL byte are refused.');
+    }
+    return name;
+}
+/**
+ * `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 function resolveShipNestedBundles(input) {
+    const { declared } = input;
+    if (declared === undefined)
+        return [];
+    if (!Array.isArray(declared)) {
+        throw new Error('gjsify ship: `gjsify.ship.nestedBundles` must be a list of `{ "source", "name", "entitlements"? }` ' +
+            'objects.');
+    }
+    if (declared.length > 0 && input.layoutOs !== 'darwin') {
+        throw new Error(`gjsify ship: \`gjsify.ship.nestedBundles\` is set and this run assembles the ${input.layoutOs} ` +
+            'layout, which has no `Contents/PlugIns` or equivalent — a Flatpak sandbox has no App ' +
+            "Extension model and a Windows program directory has nothing Apple's extension points name. " +
+            'Nested bundles are staged only for `gjsify ship darwin`.');
+    }
+    const seen = new Set();
+    return declared.map((row, index) => {
+        const at = `gjsify.ship.nestedBundles[${index}]`;
+        if (typeof row !== 'object' || row === null || Array.isArray(row)) {
+            throw new Error(`gjsify ship: \`${at}\` must be an object with \`source\` and \`name\`.`);
+        }
+        const { source, name, entitlements, ...unknown } = row;
+        const stray = Object.keys(unknown);
+        if (stray.length > 0) {
+            throw new Error(`gjsify ship: \`${at}\` has unknown key(s) ${stray.join(', ')}; known: source, name, entitlements.`);
+        }
+        if (typeof source !== 'string' || source === '') {
+            throw new Error(`gjsify ship: \`${at}.source\` must be the project-relative directory of a built bundle.`);
+        }
+        if (typeof name !== 'string') {
+            throw new Error(`gjsify ship: \`${at}.name\` must be a string — the leaf under \`Contents/PlugIns/\`.`);
+        }
+        assertUsableBundleLeaf(name, at, 'Contents/PlugIns');
+        if (seen.has(name)) {
+            throw new Error(`gjsify ship: \`${at}.name\` "${name}" is already taken by an earlier nested bundle.`);
+        }
+        seen.add(name);
+        const abs = isAbsolute(source) ? source : resolve(input.projectDir, source);
+        if (!existsSync(abs)) {
+            throw new Error(`gjsify ship: \`${at}.source\` ${source} does not exist.`);
+        }
+        if (entitlements !== undefined && !Array.isArray(entitlements)) {
+            throw new Error(`gjsify ship: \`${at}.entitlements\` must be a list of strings.`);
+        }
+        return {
+            source: abs,
+            name,
+            entitlements: (entitlements ?? []).map((key, keyIndex) => {
+                if (typeof key !== 'string') {
+                    throw new Error(`gjsify ship: \`${at}.entitlements[${keyIndex}]\` must be a string.`);
+                }
+                return key;
+            }),
+        };
+    });
+}
+/**
+ * `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 function resolveShipHelperExecutables(input) {
+    const { declared } = input;
+    if (declared === undefined)
+        return [];
+    if (!Array.isArray(declared)) {
+        throw new Error('gjsify ship: `gjsify.ship.helperExecutables` must be a list of `{ "source", "name", ' +
+            '"entitlements"? }` objects.');
+    }
+    if (declared.length > 0 && input.layoutOs !== 'darwin') {
+        throw new Error(`gjsify ship: \`gjsify.ship.helperExecutables\` is set and this run assembles the ` +
+            `${input.layoutOs} layout, which has no \`Contents/Helpers\` or equivalent. Helper ` +
+            'executables are staged only for `gjsify ship darwin`.');
+    }
+    const seen = new Set();
+    return declared.map((row, index) => {
+        const at = `gjsify.ship.helperExecutables[${index}]`;
+        if (typeof row !== 'object' || row === null || Array.isArray(row)) {
+            throw new Error(`gjsify ship: \`${at}\` must be an object with \`source\` and \`name\`.`);
+        }
+        const { source, name, entitlements, ...unknown } = row;
+        const stray = Object.keys(unknown);
+        if (stray.length > 0) {
+            throw new Error(`gjsify ship: \`${at}\` has unknown key(s) ${stray.join(', ')}; known: source, name, entitlements.`);
+        }
+        if (typeof source !== 'string' || source === '') {
+            throw new Error(`gjsify ship: \`${at}.source\` must be the project-relative path of a prebuilt executable.`);
+        }
+        if (typeof name !== 'string') {
+            throw new Error(`gjsify ship: \`${at}.name\` must be a string — the leaf under \`Contents/Helpers/\`.`);
+        }
+        assertUsableBundleLeaf(name, at, 'Contents/Helpers');
+        if (seen.has(name)) {
+            throw new Error(`gjsify ship: \`${at}.name\` "${name}" is already taken by an earlier helper executable.`);
+        }
+        seen.add(name);
+        const abs = isAbsolute(source) ? source : resolve(input.projectDir, source);
+        if (!existsSync(abs)) {
+            throw new Error(`gjsify ship: \`${at}.source\` ${source} does not exist.`);
+        }
+        if (entitlements !== undefined && !Array.isArray(entitlements)) {
+            throw new Error(`gjsify ship: \`${at}.entitlements\` must be a list of strings.`);
+        }
+        return {
+            source: abs,
+            name,
+            entitlements: (entitlements ?? []).map((key, keyIndex) => {
+                if (typeof key !== 'string') {
+                    throw new Error(`gjsify ship: \`${at}.entitlements[${keyIndex}]\` must be a string.`);
+                }
+                return key;
+            }),
+        };
+    });
+}
 /**
  * The ONE place a ship target's ENTRY is decided — {@link resolveShipApp}'s twin.
  *

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

@@ -156,17 +156,25 @@ export declare function assertHostCanSign(signer: SignerDescriptor): void;
  * host. Everything else about a bundle seal needs `codesign`, which this
  * repository has on exactly one CI leg; this function needs nothing.
  *
- * `sealPrefix` absent means "this signer seals nothing", and then EVERY addition
- * is unexpected — which is what the file did before ADR 0040 and is still the
- * right answer for `signtool`.
+ * `sealPrefixes` empty or absent means "this signer seals nothing", and then
+ * EVERY addition is unexpected — which is what the file did before ADR 0040
+ * and is still the right answer for `signtool`.
  */
 export declare function partitionSignedFileSet(input: {
     /** Paths found under the scratch directory after the tool ran. */
     arrived: readonly string[];
     /** Paths the payload had before it. */
     planned: readonly string[];
-    /** Directory prefix the seal is allowed to write into, when there is one. */
-    sealPrefix?: string;
+    /**
+     * Directory prefixes a seal is allowed to write into — one per bundle sealed
+     * this run. A plain array rather than a single optional string, because a
+     * darwin run with nested bundles (ADR 0024 amendment, "nested bundles and
+     * helper executables") seals MORE than one directory: the outer `.app` and
+     * every embedded `.appex`, each writing its own `_CodeSignature/`. `[]` and
+     * absent mean the same thing — "no seal this run" — so a caller with
+     * nothing to add may still pass `[]` rather than reaching for `undefined`.
+     */
+    sealPrefixes?: readonly string[];
 }): {
     sealed: string[];
     unexpected: string[];
@@ -195,6 +203,20 @@ export interface SignArgs {
 }
 /** `codesign --sign -`: the one identity value that names no identity at all. */
 export declare const ADHOC_IDENTITY = "-";
+/**
+ * One nested bundle or helper executable the darwin signer signs with its OWN
+ * entitlements, before the outer seal (ADR 0024 amendment, "nested bundles and
+ * helper executables"; the beifahrer ADR this answers: 0026 § 6).
+ */
+export interface SignedSubordinate {
+    /** Payload-relative path — a bundle DIRECTORY for a nested bundle, a FILE for a helper. */
+    path: string;
+    /**
+     * Entitlements this subordinate is signed with, REPLACING the outer signer's
+     * own set — never unioned with it. `[]` signs with none.
+     */
+    entitlements: readonly string[];
+}
 export interface SignPayloadInput {
     /** What `readStage` returned — the PRE-sign tree, already held against the manifest. */
     payload: readonly PayloadEntry[];
@@ -218,6 +240,24 @@ export interface SignPayloadInput {
      * read as a file the signer added.
      */
     entitlementsPath: string;
+    /**
+     * Nested BUNDLES this run embeds — e.g. a Safari Web Extension `.appex` under
+     * `Contents/PlugIns/`. Signed INSIDE OUT: every Mach-O under each one's path,
+     * then that bundle's own seal, ALL of it before the outer bundle's images or
+     * seal — because the outer seal's `CodeResources` hashes every file under its
+     * tree, nested bundles included, so resigning one afterwards would invalidate
+     * a hash the outer seal already recorded. `[]` for a layout or project with
+     * none. `sealsBundle` must be `true` on {@link signer} for a non-empty list —
+     * `signtool` has no bundle concept to nest one inside.
+     */
+    nestedBundles?: readonly SignedSubordinate[];
+    /**
+     * Helper EXECUTABLES this run embeds with their own entitlements — e.g. a
+     * small Swift binary with no GI binding. Signed before the outer images and
+     * seal, for the same reason as {@link nestedBundles}: a loose file's bytes
+     * are hashed into the outer seal too. `[]` for none.
+     */
+    helperExecutables?: readonly SignedSubordinate[];
     /** Print every invocation. */
     verbose: boolean;
     log: (line: string) => void;

package/lib/utils/ship/signing.js

@@ -341,18 +341,19 @@ export function assertHostCanSign(signer) {
  * host. Everything else about a bundle seal needs `codesign`, which this
  * repository has on exactly one CI leg; this function needs nothing.
  *
- * `sealPrefix` absent means "this signer seals nothing", and then EVERY addition
- * is unexpected — which is what the file did before ADR 0040 and is still the
- * right answer for `signtool`.
+ * `sealPrefixes` empty or absent means "this signer seals nothing", and then
+ * EVERY addition is unexpected — which is what the file did before ADR 0040
+ * and is still the right answer for `signtool`.
  */
 export function partitionSignedFileSet(input) {
     const planned = new Set(input.planned);
     const arrived = new Set(input.arrived);
     const added = [...arrived].filter((path) => !planned.has(path)).sort();
-    const prefix = input.sealPrefix;
+    const prefixes = input.sealPrefixes ?? [];
+    const underAnyPrefix = (path) => prefixes.some((prefix) => path.startsWith(prefix));
     return {
-        sealed: prefix === undefined ? [] : added.filter((path) => path.startsWith(prefix)),
-        unexpected: prefix === undefined ? added : added.filter((path) => !path.startsWith(prefix)),
+        sealed: prefixes.length === 0 ? [] : added.filter(underAnyPrefix),
+        unexpected: prefixes.length === 0 ? added : added.filter((path) => !underAnyPrefix(path)),
         removed: [...planned].filter((path) => !arrived.has(path)).sort(),
     };
 }
@@ -381,16 +382,30 @@ export const ADHOC_IDENTITY = '-';
  */
 export async function signPayload(input) {
     const { payload, signer, workDir } = input;
+    const nestedBundles = input.nestedBundles ?? [];
+    const helperExecutables = input.helperExecutables ?? [];
+    if ((nestedBundles.length > 0 || helperExecutables.length > 0) && !signer.sealsBundle) {
+        throw new Error(`gjsify ship: this payload declares a nested bundle or helper executable, and the ` +
+            `${signer.layoutOs} signer has no bundle to embed one in — \`signtool\` signs loose images, ` +
+            'never a bundle tree. Nested bundles and helper executables are a darwin-only feature.');
+    }
     writePayload(workDir, payload, '');
     const adhoc = input.identity === ADHOC_IDENTITY;
-    let entitlements;
-    const granted = signer.entitlements(adhoc);
-    if (granted.length > 0) {
-        mkdirSync(dirname(input.entitlementsPath), { recursive: true });
-        writeFileSync(input.entitlementsPath, renderEntitlements(granted));
-        entitlements = input.entitlementsPath;
-    }
-    const run = async (file, what, seal) => {
+    const entitlementsCache = new Map();
+    /** Write (or reuse) the entitlements plist for one KEYED set of grants, `[]` meaning none. */
+    const entitlementsFileFor = (key, granted) => {
+        if (granted.length === 0)
+            return undefined;
+        const cached = entitlementsCache.get(key);
+        if (cached !== undefined)
+            return cached;
+        const path = key === '' ? input.entitlementsPath : `${input.entitlementsPath}.${key}.plist`;
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, renderEntitlements(granted));
+        entitlementsCache.set(key, path);
+        return path;
+    };
+    const run = async (file, what, seal, entitlements) => {
         const args = signer.args({
             identity: input.identity,
             file,
@@ -412,7 +427,38 @@ export async function signPayload(input) {
                 'signed installs and is refused at first launch, which is worse than not shipping.');
         }
     };
-    const signable = payload.filter((entry) => classifyBinary(entry.data) === signer.signs);
+    const outerEntitlements = entitlementsFileFor('', signer.entitlements(adhoc));
+    // Every path this run signs with its OWN entitlements rather than the outer
+    // signer's default — excluded from the generic loop below so neither set of
+    // files is signed twice with two different entitlement lists.
+    const subordinatePrefixes = nestedBundles.map((bundle) => `${bundle.path}/`);
+    const helperPaths = new Set(helperExecutables.map((helper) => helper.path));
+    const underSubordinate = (path) => subordinatePrefixes.some((prefix) => path.startsWith(prefix));
+    // INSIDE OUT, and before anything else: the outer seal's `CodeResources`
+    // hashes every file under its tree, nested bundles and helpers included, so
+    // each one has to be in its FINAL signed form before that hash is taken —
+    // resigning afterwards would invalidate a digest the outer seal already
+    // recorded. Order WITHIN this block does not matter; order relative to the
+    // generic loop and the outer seal below does.
+    const nestedSealPrefixes = [];
+    let nestedImagesSigned = 0;
+    for (const bundle of nestedBundles) {
+        const entitlements = entitlementsFileFor(bundle.path, bundle.entitlements);
+        const images = payload.filter((entry) => entry.path.startsWith(`${bundle.path}/`) && classifyBinary(entry.data) === signer.signs);
+        for (const entry of images) {
+            await run(join(workDir, entry.path.split('/').join(sep)), entry.path, false, entitlements);
+        }
+        nestedImagesSigned += images.length;
+        await run(join(workDir, bundle.path.split('/').join(sep)), `${bundle.path} (nested bundle seal)`, true, entitlements);
+        nestedSealPrefixes.push(signer.sealAddPrefix(bundle.path));
+    }
+    for (const helper of helperExecutables) {
+        const entitlements = entitlementsFileFor(helper.path, helper.entitlements);
+        await run(join(workDir, helper.path.split('/').join(sep)), helper.path, false, entitlements);
+    }
+    const signable = payload.filter((entry) => classifyBinary(entry.data) === signer.signs &&
+        !underSubordinate(entry.path) &&
+        !helperPaths.has(entry.path));
     if (signable.length === 0 && !signer.sealsBundle) {
         // NOT silent, and not an error either. A `--app gjs` payload really is
         // JavaScript and a launcher, so there is nothing for the loader to
@@ -428,7 +474,7 @@ export async function signPayload(input) {
         return [...payload];
     }
     for (const entry of signable) {
-        await run(join(workDir, entry.path.split('/').join(sep)), entry.path, false);
+        await run(join(workDir, entry.path.split('/').join(sep)), entry.path, false, outerEntitlements);
     }
     // THE IMAGES FIRST, THE SEAL LAST, and the order is not stylistic: a bundle
     // seal hashes the files it seals, so sealing before the closure is signed
@@ -442,28 +488,32 @@ export async function signPayload(input) {
                 'stage would sign the payload of every other format beside it.');
         }
         sealPrefix = signer.sealAddPrefix(input.bundleRoot);
-        await run(join(workDir, input.bundleRoot.split('/').join(sep)), `${input.bundleRoot} (bundle seal)`, true);
+        await run(join(workDir, input.bundleRoot.split('/').join(sep)), `${input.bundleRoot} (bundle seal)`, true, outerEntitlements);
     }
-    // THE FILE SET MAY ONLY GROW WHERE THE SEAL WRITES. Both tools rewrite an
-    // image in place, so any other new path means something else ran — and a file
-    // that appeared unnoticed would be packed with no mode from the plan, while
-    // one that vanished would be packed as absent.
+    // THE FILE SET MAY ONLY GROW WHERE A SEAL WRITES — the outer one, or one of
+    // the nested bundles signed above. Both tools rewrite an image in place, so
+    // any other new path means something else ran — and a file that appeared
+    // unnoticed would be packed with no mode from the plan, while one that
+    // vanished would be packed as absent.
+    const sealPrefixes = [...(sealPrefix === undefined ? [] : [sealPrefix]), ...nestedSealPrefixes];
     const changes = partitionSignedFileSet({
         arrived: listFilesRecursive(workDir),
         planned: payload.map((entry) => entry.path),
-        ...(sealPrefix === undefined ? {} : { sealPrefix }),
+        sealPrefixes,
     });
     if (changes.unexpected.length > 0 || changes.removed.length > 0) {
         throw new Error(`gjsify ship: ${signer.tool} changed the payload's file set — ` +
             `${changes.unexpected.length} added (${changes.unexpected.slice(0, 3).join(', ') || '—'}), ` +
             `${changes.removed.length} removed (${changes.removed.slice(0, 3).join(', ') || '—'}). ` +
             'Signing is a mutation of the files that are already in the payload (ADR 0024 § A4), plus ' +
-            `exactly the seal's own directory${sealPrefix === undefined ? '' : ` (\`${sealPrefix}\`)`}.`);
+            `exactly each seal's own directory${sealPrefixes.length === 0 ? '' : ` (${sealPrefixes.map((prefix) => `\`${prefix}\``).join(', ')})`}.`);
     }
     const sealed = changes.sealed;
-    input.log(`${signer.tool} signed ${signable.length} of ${payload.length} payload file(s) as ` +
+    input.log(`${signer.tool} signed ${signable.length + nestedImagesSigned + helperExecutables.length} of ` +
+        `${payload.length} payload file(s) as ` +
         `${adhoc ? 'ad-hoc (`-`)' : `\`${input.identity}\``}` +
         `${sealPrefix === undefined ? '' : ` and sealed ${input.bundleRoot} (${sealed.length} seal file(s))`}` +
+        `${nestedBundles.length === 0 ? '' : `, nested: ${nestedBundles.map((bundle) => bundle.path).join(', ')}`}` +
         ` — ${signer.gap}.`);
     // Modes come from the PLAN, exactly as `readStage` insists: the signer
     // rewrites bytes and this re-read must not turn a 0755 launcher into

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

@@ -141,6 +141,8 @@ export function toPackSettings(settings) {
         minNodeVersion: settings.minNodeVersion,
         flatpak: settings.flatpak,
         executables: settings.executables.map(({ name, gui }) => ({ name, gui })),
+        nestedBundles: settings.nestedBundles.map(({ name, entitlements }) => ({ name, entitlements })),
+        helperExecutables: settings.helperExecutables.map(({ name, entitlements }) => ({ name, entitlements })),
     };
 }
 /** Absolute path of a stage's manifest. */
@@ -512,6 +514,23 @@ function readPackSettings(data, at) {
             }
             return { name: expectString(row.name, field(`executables[${index}].name`)), gui: row.gui };
         }),
+        // OPTIONAL on read, same reason as `executables`: a stage written before
+        // `gjsify.ship.nestedBundles`/`helperExecutables` existed carries neither,
+        // and `[]` is exactly right for it.
+        nestedBundles: expectArray(data.nestedBundles ?? [], field('nestedBundles')).map((entry, index) => {
+            const row = record(entry, field(`nestedBundles[${index}]`));
+            return {
+                name: expectString(row.name, field(`nestedBundles[${index}].name`)),
+                entitlements: expectArray(row.entitlements, field(`nestedBundles[${index}].entitlements`)).map((key, keyIndex) => expectString(key, field(`nestedBundles[${index}].entitlements[${keyIndex}]`))),
+            };
+        }),
+        helperExecutables: expectArray(data.helperExecutables ?? [], field('helperExecutables')).map((entry, index) => {
+            const row = record(entry, field(`helperExecutables[${index}]`));
+            return {
+                name: expectString(row.name, field(`helperExecutables[${index}].name`)),
+                entitlements: expectArray(row.entitlements, field(`helperExecutables[${index}].entitlements`)).map((key, keyIndex) => expectString(key, field(`helperExecutables[${index}].entitlements[${keyIndex}]`))),
+            };
+        }),
     };
 }
 /**

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

@@ -414,6 +414,19 @@ export interface PackSettings {
      * launcher, and the packing host needs the names for the Windows arch exemption.
      */
     executables: ShipExecutableFacts[];
+    /**
+     * Further bundles the darwin container embeds (`gjsify.ship.nestedBundles`); `[]` for a
+     * package with none. Name and entitlements only — the packing host derives each one's
+     * stage-relative path from `layoutForOs('darwin').dirs(settings).plugins` and signs it
+     * there; the SOURCE directory stays assembling-host-only (it is staged, not re-read).
+     */
+    nestedBundles: ShipNestedBundleFacts[];
+    /**
+     * Prebuilt helper executables staged into `Contents/Helpers/`
+     * (`gjsify.ship.helperExecutables`); `[]` for a package with none. Same shape as
+     * {@link PackSettings.nestedBundles}, one directory over (`dirs.helpers`).
+     */
+    helperExecutables: ShipHelperExecutableFacts[];
 }
 /** What the packing host needs to know about one further executable. */
 export interface ShipExecutableFacts {
@@ -427,6 +440,53 @@ export interface ShipExecutable extends ShipExecutableFacts {
     /** Its entry inside {@link ShipSettings.bundleDir}, POSIX-separated. */
     entry: string;
 }
+/**
+ * What the packing host needs to know about one nested bundle, to sign it.
+ *
+ * `name` rather than a stage-relative path, mirroring {@link ShipExecutableFacts}:
+ * the PATH is derived — `posix.join(layoutForOs(format.layoutOs).dirs(settings).plugins,
+ * name)` — from data every packing host already has (the layout, `PackSettings`),
+ * so this closure carries nothing a stage-relative string would duplicate.
+ */
+export interface ShipNestedBundleFacts {
+    /** Destination leaf under `Contents/PlugIns/`. */
+    name: string;
+    /**
+     * Entitlements this bundle is signed and sealed with, REPLACING the outer
+     * signer's own set — a sandboxed extension keeps the sandbox entitlements
+     * its own packager wrote and must not inherit the host app's grants.
+     */
+    entitlements: readonly string[];
+}
+/**
+ * One nested bundle a darwin container embeds, as resolved from
+ * `gjsify.ship.nestedBundles` — e.g. a Safari Web Extension `.appex`.
+ *
+ * Darwin-only (ADR 0024 § A12-§ A17 amendment, "nested bundles and helper
+ * executables"; the beifahrer ADR this answers: 0026 § 6): `Contents/PlugIns`
+ * is Apple's own nested-code location and no other layout has an equivalent
+ * slot, so `resolveShipSettings` refuses a non-empty list for any other OS.
+ */
+export interface ShipNestedBundle extends ShipNestedBundleFacts {
+    /** Absolute path of the source directory — the built `.appex` tree. */
+    source: string;
+}
+/** What the packing host needs to know about one helper executable, to sign it. */
+export interface ShipHelperExecutableFacts {
+    /** Destination leaf under `Contents/Helpers/`. */
+    name: string;
+    /** Entitlements this helper is signed with. */
+    entitlements: readonly string[];
+}
+/**
+ * One prebuilt helper executable staged into `Contents/Helpers/`, as resolved
+ * from `gjsify.ship.helperExecutables`. Darwin-only, for the same reason as
+ * {@link ShipNestedBundle}.
+ */
+export interface ShipHelperExecutable extends ShipHelperExecutableFacts {
+    /** Absolute path of the prebuilt executable. */
+    source: string;
+}
 /**
  * What the generated Flatpak manifest says about everything that is not the payload.
  *
@@ -511,6 +571,19 @@ export interface ShipSettings extends PackSettings {
         rel: string;
         abs: string;
     }[];
+    /**
+     * Further bundles the darwin container embeds under `Contents/PlugIns/`
+     * (`gjsify.ship.nestedBundles`) — `[]` for a package with none. Ignored on
+     * every other layout; `resolveShipSettings` refuses a non-empty list there
+     * rather than silently dropping it.
+     */
+    nestedBundles: ShipNestedBundle[];
+    /**
+     * Prebuilt helper executables staged into `Contents/Helpers/`
+     * (`gjsify.ship.helperExecutables`) — `[]` for a package with none.
+     * Darwin-only, like {@link ShipSettings.nestedBundles}.
+     */
+    helperExecutables: ShipHelperExecutable[];
     /**
      * 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.19",
+    "version": "0.64.21",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -142,22 +142,22 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/blueprint": "^0.64.19",
-        "@gjsify/buffer": "^0.64.19",
-        "@gjsify/create-app": "^0.64.19",
-        "@gjsify/node-globals": "^0.64.19",
-        "@gjsify/node-polyfills": "^0.64.19",
-        "@gjsify/npm-registry": "^0.64.19",
-        "@gjsify/resolve-npm": "^0.64.19",
-        "@gjsify/rolldown-plugin-gjsify": "^0.64.19",
-        "@gjsify/vite-plugin-blueprint": "^0.64.19",
-        "@gjsify/rolldown-plugin-pnp": "^0.64.19",
-        "@gjsify/semver": "^0.64.19",
-        "@gjsify/tar": "^0.64.19",
-        "@gjsify/tsc": "^0.64.19",
-        "@gjsify/utils": "^0.64.19",
-        "@gjsify/web-polyfills": "^0.64.19",
-        "@gjsify/workspace": "^0.64.19",
+        "@gjsify/blueprint": "^0.64.21",
+        "@gjsify/buffer": "^0.64.21",
+        "@gjsify/create-app": "^0.64.21",
+        "@gjsify/node-globals": "^0.64.21",
+        "@gjsify/node-polyfills": "^0.64.21",
+        "@gjsify/npm-registry": "^0.64.21",
+        "@gjsify/resolve-npm": "^0.64.21",
+        "@gjsify/rolldown-plugin-gjsify": "^0.64.21",
+        "@gjsify/vite-plugin-blueprint": "^0.64.21",
+        "@gjsify/rolldown-plugin-pnp": "^0.64.21",
+        "@gjsify/semver": "^0.64.21",
+        "@gjsify/tar": "^0.64.21",
+        "@gjsify/tsc": "^0.64.21",
+        "@gjsify/utils": "^0.64.21",
+        "@gjsify/web-polyfills": "^0.64.21",
+        "@gjsify/workspace": "^0.64.21",
         "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.19",
+        "@gjsify/unit": "^0.64.21",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.64.19",
-        "@gjsify/rolldown-native": "^0.64.19"
+        "@gjsify/oxfmt-native": "^0.64.21",
+        "@gjsify/rolldown-native": "^0.64.21"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {