@gjsify/cli 0.64.20 → 0.64.22

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,53 @@ 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 IGNORED (not refused) outside
+     * `gjsify ship darwin` — one notice on stderr, exit 0 (ADR 0024 amendment,
+     * 2026-11-06 addendum, beifahrer#203). The shape is still validated on
+     * every layout.
+     */
+    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/oxc-resolve.d.ts

@@ -51,15 +51,51 @@ export interface RunOxcOptions {
     cwd?: string;
     verbose?: boolean;
 }
+export interface OxfmtEngineInputs {
+    isGjs: boolean;
+    /** The `@gjsify/oxfmt-native` bridge loaded and its library opened. */
+    nativeLoadable: boolean;
+    /** The oxfmt release the bridge embeds; `undefined` when the bridge does not say. */
+    embeddedVersion?: string;
+    /** Version of the oxfmt npm package the project resolves; `undefined` when it has none. */
+    projectVersion?: string;
+    /** `GJSIFY_OXFMT`. */
+    override?: string;
+}
+export interface OxfmtEngineDecision {
+    engine: 'native' | 'npm';
+    /** The forced `native` engine runs a different oxfmt than the project's lock. */
+    warning?: string;
+    /** The forced `native` engine cannot be loaded. */
+    error?: string;
+}
+/**
+ * The engine pick as a pure function. Two engines that are not the same build of
+ * oxfmt format some inputs differently (`for (…; cond;) {` vs `for (…; cond; ) {`
+ * between 0.61 and 0.56), so a project that pins its own `oxfmt` must get THAT
+ * build, or `format:check` is green under GJS locally and red under Node in CI.
+ *
+ *   - `npm` override → npm launcher.
+ *   - `native` override → the bridge, an error when it is not loadable, a warning
+ *     when it differs from the project's pinned version.
+ *   - Not GJS, or bridge not loadable → npm launcher.
+ *   - Project resolves no `oxfmt`, or either version is unknown → native (the
+ *     Node-free default; there is nothing to disagree with).
+ *   - Both known → native only when equal, else the project's npm `oxfmt` wins.
+ */
+export declare function decideOxfmtEngine(input: OxfmtEngineInputs): OxfmtEngineDecision;
+/**
+ * Version of the `oxfmt` npm package the project resolves (same walk as
+ * {@link findOxcLauncher}), or `undefined` when there is none.
+ */
+export declare function findProjectOxfmtVersion(cwd?: string): string | undefined;
 /**
- * Engine pick for oxfmt — mirrors `bundler-pick.ts`'s `shouldUseNative()`:
- *   - `GJSIFY_OXFMT=npm` forces the Node launcher.
- *   - `GJSIFY_OXFMT=native` forces the GI bridge and throws when it is not
- *     loadable (instead of silently switching engines).
- *   - Default: native under GJS when loadable (the Node launcher cannot run
- *     without a Node host), npm launcher on Node.
+ * Engine pick for oxfmt — see {@link decideOxfmtEngine} for the rule. This wrapper
+ * gathers the inputs (bridge probe, project version) and applies the outcome:
+ * a forced `native` that cannot load throws, a forced `native` on another version
+ * than the project's warns once per process.
  */
-export declare function shouldUseNativeOxfmt(): Promise<boolean>;
+export declare function shouldUseNativeOxfmt(cwd?: string): Promise<boolean>;
 /**
  * Run an oxc tool (oxlint / oxfmt).
  *

package/lib/utils/oxc-resolve.js

@@ -47,7 +47,7 @@
 // Rust rule subset. Lint stays Node-spawned until that trade-off is decided
 // (tracked in status/open-todos/README.md).
 import { existsSync, readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { hostLibc } from './platform-check.js';
@@ -297,38 +297,93 @@ async function tryLoadNativeOxfmt() {
     })();
     return _nativeOxfmtProbe;
 }
+const normalizeVersion = (v) => v.trim().replace(/^v/, '');
 /**
- * Engine pick for oxfmt — mirrors `bundler-pick.ts`'s `shouldUseNative()`:
- *   - `GJSIFY_OXFMT=npm` forces the Node launcher.
- *   - `GJSIFY_OXFMT=native` forces the GI bridge and throws when it is not
- *     loadable (instead of silently switching engines).
- *   - Default: native under GJS when loadable (the Node launcher cannot run
- *     without a Node host), npm launcher on Node.
+ * The engine pick as a pure function. Two engines that are not the same build of
+ * oxfmt format some inputs differently (`for (…; cond;) {` vs `for (…; cond; ) {`
+ * between 0.61 and 0.56), so a project that pins its own `oxfmt` must get THAT
+ * build, or `format:check` is green under GJS locally and red under Node in CI.
+ *
+ *   - `npm` override → npm launcher.
+ *   - `native` override → the bridge, an error when it is not loadable, a warning
+ *     when it differs from the project's pinned version.
+ *   - Not GJS, or bridge not loadable → npm launcher.
+ *   - Project resolves no `oxfmt`, or either version is unknown → native (the
+ *     Node-free default; there is nothing to disagree with).
+ *   - Both known → native only when equal, else the project's npm `oxfmt` wins.
  */
-export async function shouldUseNativeOxfmt() {
-    const env = globalThis.process?.env ?? {};
-    const choice = env.GJSIFY_OXFMT;
-    if (choice === 'npm')
-        return false;
-    if (choice === 'native') {
-        const native = await tryLoadNativeOxfmt();
-        if (!native) {
-            throw new Error('GJSIFY_OXFMT=native but @gjsify/oxfmt-native is not loadable (no prebuild for this architecture, or not running under GJS).' +
-                (_nativeOxfmtLoadError ? `\n${_nativeOxfmtLoadError.message}` : ''));
+export function decideOxfmtEngine(input) {
+    const { isGjs: gjs, nativeLoadable, embeddedVersion, projectVersion, override } = input;
+    const known = embeddedVersion !== undefined && projectVersion !== undefined;
+    const differs = known && normalizeVersion(embeddedVersion) !== normalizeVersion(projectVersion);
+    if (override === 'npm')
+        return { engine: 'npm' };
+    if (override === 'native') {
+        if (!nativeLoadable) {
+            return {
+                engine: 'native',
+                error: 'GJSIFY_OXFMT=native but @gjsify/oxfmt-native is not loadable (no prebuild for this architecture, or not running under GJS).',
+            };
         }
-        return true;
+        return differs
+            ? {
+                engine: 'native',
+                warning: `GJSIFY_OXFMT=native: @gjsify/oxfmt-native embeds oxfmt ${embeddedVersion} but this project ` +
+                    `pins oxfmt ${projectVersion}; output can differ from the project's own oxfmt (and from CI).`,
+            }
+            : { engine: 'native' };
     }
-    if (!isGjs())
+    if (!gjs || !nativeLoadable)
+        return { engine: 'npm' };
+    return { engine: differs ? 'npm' : 'native' };
+}
+/**
+ * Version of the `oxfmt` npm package the project resolves (same walk as
+ * {@link findOxcLauncher}), or `undefined` when there is none.
+ */
+export function findProjectOxfmtVersion(cwd = process.cwd()) {
+    try {
+        const launcher = findOxcLauncher('oxfmt', cwd);
+        const pkg = JSON.parse(readFileSync(join(dirname(launcher), '..', 'package.json'), 'utf-8'));
+        return typeof pkg?.version === 'string' ? pkg.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+let _engineWarned = false;
+/**
+ * Engine pick for oxfmt — see {@link decideOxfmtEngine} for the rule. This wrapper
+ * gathers the inputs (bridge probe, project version) and applies the outcome:
+ * a forced `native` that cannot load throws, a forced `native` on another version
+ * than the project's warns once per process.
+ */
+export async function shouldUseNativeOxfmt(cwd = process.cwd()) {
+    const env = globalThis.process?.env ?? {};
+    const override = env.GJSIFY_OXFMT;
+    // Nothing to probe when npm is forced or there is no GJS host (and no native override).
+    if (override === 'npm' || (!isGjs() && override !== 'native'))
         return false;
-    const native = (await tryLoadNativeOxfmt()) !== null;
+    const native = await tryLoadNativeOxfmt();
+    const decision = decideOxfmtEngine({
+        isGjs: isGjs(),
+        nativeLoadable: native !== null,
+        embeddedVersion: native?.EMBEDDED_OXFMT_VERSION,
+        projectVersion: findProjectOxfmtVersion(cwd),
+        override,
+    });
+    if (decision.error)
+        throw new Error(decision.error + (_nativeOxfmtLoadError ? `\n${_nativeOxfmtLoadError.message}` : ''));
+    if (decision.warning && !_engineWarned) {
+        _engineWarned = true;
+        console.warn(`[gjsify oxc] ${decision.warning}`);
+    }
     // Falling back to the npm launcher is not an error, so the default path is
     // quiet — but a MEASURED reason why the native bridge would not load is the
     // only place the user hears it, and it is the whole point of measuring.
-    // `GJSIFY_OXFMT=native` above throws with this text; the default earns the
-    // same answer for free.
-    if (!native && _nativeOxfmtLoadError)
+    if (!native && _nativeOxfmtLoadError && decision.engine === 'npm')
         console.debug(_nativeOxfmtLoadError.message);
-    return native;
+    return decision.engine === 'native';
 }
 /**
  * Run an oxc tool (oxlint / oxfmt).

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,19 @@ 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 IGNORED (not
+     * refused) on any layout where this is `''` — `resolveShipNestedBundles`
+     * resolves it to `[]` before `stageSubordinates` ever sees it (ADR 0024
+     * amendment, "nested bundles and helper executables", 2026-11-06 addendum;
+     * 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; `resolveShipNestedBundles` should have ' +
+                'resolved this to `[]` 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; `resolveShipHelperExecutables` should have ' +
+                'resolved this to `[]` 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,
     };
 }