@gjsify/cli 0.64.15 → 0.64.17-next.292

package/lib/actions/build.d.ts

@@ -2,6 +2,7 @@ import type { ConfigData } from '../types/index.js';
 import type { App } from '@gjsify/rolldown-plugin-gjsify';
 import type { RolldownOutput } from 'rolldown';
 import { type RunBundleOptions } from '../bundler-pick.js';
+import { WorkerEntries } from '@gjsify/rolldown-plugin-gjsify';
 export declare class BuildAction {
     readonly configData: ConfigData;
     constructor(configData?: ConfigData);
@@ -229,7 +230,16 @@ export declare class BuildAction {
         preserveDefaultExport?: boolean;
         toolchainAnchor?: string;
         onWatchFiles?: RunBundleOptions['onWatchFiles'];
+        /** Set by the top-level build for its nested worker builds, so names and "already built" are shared. */
+        workers?: WorkerEntries;
     }): Promise<RolldownOutput[]>;
+    /**
+     * Build every worker script the main bundle (or an earlier worker) names by
+     * `new Worker(new URL('./x', import.meta.url))`, each as its own app build beside the
+     * output, under the main build's config. Rounds, not recursion: a nested build registers
+     * what ITS workers need, and the shared registry hands each source out once.
+     */
+    private buildWorkers;
     /**
      * Drive `rolldown.watch(...)`: rebuild on source change, apply the
      * post-bundle shebang hook on each successful build, surface errors

package/lib/actions/build.js

@@ -1,5 +1,5 @@
 import { runBundle, runWatch, bundleToChunks } from '../bundler-pick.js';
-import { gjsifyPlugin, textLoaderPlugin, resolveShebangLine, NODE_SHEBANG, createGjsExternalsPredicate, globToEntryPoints, scanGiNamespaces, planGiSelection, } from '@gjsify/rolldown-plugin-gjsify';
+import { gjsifyPlugin, textLoaderPlugin, resolveShebangLine, NODE_SHEBANG, createGjsExternalsPredicate, globToEntryPoints, scanGiNamespaces, planGiSelection, WorkerEntries, bundleSuffix, } from '@gjsify/rolldown-plugin-gjsify';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { resolveUserPlugins } from '../utils/resolve-plugin-by-name.js';
 import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals, detectNodeGiGlobals, } from '@gjsify/rolldown-plugin-gjsify/globals';
@@ -715,6 +715,15 @@ export class BuildAction {
             ...(opts.preserveDefaultExport ? { preserveDefaultExport: true } : {}),
             ...(opts.toolchainAnchor !== undefined ? { toolchainAnchor: opts.toolchainAnchor } : {}),
         };
+        // `new Worker(new URL('./x', import.meta.url))` targets are built beside the bundle after it
+        // (see `buildWorkers`). Needs a concrete output location and a one-file app target.
+        const ownsWorkers = opts.workers === undefined;
+        const workers = opts.workers ??
+            (app !== 'nativescript' && !opts.watch && (outfile || outdir)
+                ? new WorkerEntries(outfile ? bundleSuffix(outfile) : '.js')
+                : undefined);
+        if (workers)
+            pluginOpts.workers = workers;
         const { autoMode, extras } = this.parseGlobalsValue(globals);
         const pnp = await buildPnpPlugin();
         const pnpPlugins = pnp ? [pnp] : [];
@@ -916,8 +925,33 @@ export class BuildAction {
         if (app === 'browser' && htmlEntry && outfile) {
             await this.applyBrowserHtml(htmlEntry, outfile, verbose);
         }
+        if (workers && ownsWorkers) {
+            await this.buildWorkers(workers, app, dirname(resolve(outfile ?? join(outdir, 'x'))), opts);
+        }
         return [writeResult];
     }
+    /**
+     * Build every worker script the main bundle (or an earlier worker) names by
+     * `new Worker(new URL('./x', import.meta.url))`, each as its own app build beside the
+     * output, under the main build's config. Rounds, not recursion: a nested build registers
+     * what ITS workers need, and the shared registry hands each source out once.
+     */
+    async buildWorkers(workers, app, outDir, opts) {
+        const { esbuild: _legacy, ...rest } = this.configData;
+        const bundler = normalizeBundlerOptions(this.configData);
+        for (let round = workers.takePending(); round.length > 0; round = workers.takePending()) {
+            for (const { source, fileName } of round) {
+                if (this.configData.verbose)
+                    console.debug(`[gjsify] bundling worker ${source} → ${fileName}`);
+                const { dir: _dir, ...output } = bundler.output ?? {};
+                await new BuildAction({
+                    ...rest,
+                    shebang: false,
+                    bundler: { ...bundler, input: source, output: { ...output, file: join(outDir, fileName) } },
+                }).buildApp(app, { ...opts, workers });
+            }
+        }
+    }
     /**
      * Drive `rolldown.watch(...)`: rebuild on source change, apply the
      * post-bundle shebang hook on each successful build, surface errors

package/lib/commands/ship.js

@@ -39,7 +39,7 @@ import { resolveNodeModulesClosure, stageNodeModules } from '../utils/ship/node-
 import { acquireGtkRuntime } from '../utils/ship/gtk-runtime-acquire.js';
 import { discoverPayload } from '../utils/ship/discover.js';
 import { appDirFor, appDirPayload, appImageHostRequirements, appImageRuntimeNotice, buildAppImage, findPinnedRuntime, stampAppDirTimes, } from '../utils/ship/appimage.js';
-import { addApplicationsLink, buildDmgImage, dmgVolumeDir, dmgVolumeName, signDmgImage } from '../utils/ship/dmg.js';
+import { addApplicationsLink, buildDmgImage, dmgVolumeDir, dmgVolumeName, signDmgImage, stapleBundleBeforeImage, } from '../utils/ship/dmg.js';
 import { assertNoDroppedFlatpakModules } from '../utils/ship/flatpak-config.js';
 import { buildFlatpakBundle } from '../utils/ship/flatpak.js';
 import { iconSizes, resolveAppIcon } from '../utils/ship/icons.js';
@@ -422,6 +422,10 @@ async function assemble(args) {
     const stageInputs = {
         bundleFiles: discovered.bundleFiles,
         launcher: renderLauncher(settings, basename(settings.bundlePath), layout, runtime.launcher),
+        executableLaunchers: Object.fromEntries(settings.executables.map((executable) => [
+            executable.name,
+            renderLauncher(settings, executable.entry, layout, runtime.launcher),
+        ])),
         metainfo: translated.metainfo,
         desktopEntry: translated.desktopEntry,
         licenseText: settings.licenseFile === undefined ? undefined : readFileSync(settings.licenseFile, 'utf-8'),
@@ -1262,6 +1266,29 @@ async function packOne(input) {
             // mounts showing `Contents/` — a window with no application in it.
             const volumeDir = dmgVolumeDir(outRoot);
             writePayload(volumeDir, payload, '');
+            // THE BUNDLE'S OWN TICKET, before the image exists (#162): a `.app` dragged
+            // out of a volume carries only what was stapled to IT. Nothing signs after
+            // this point except the image, which is a different object.
+            if (input.notarize.kind === 'notarize') {
+                const notarizePlan = input.notarize;
+                const bundleDir = join(volumeDir, `${settings.name}.app`);
+                const archive = join(dirname(volumeDir), 'bundle-notarize.zip');
+                await stapleBundleBeforeImage({
+                    writeArchive: () => writeFileSync(archive, buildZip(zipEntriesFromPayload(payload), mtime)),
+                    notarize: () => notarizeArtifact({
+                        plan: notarizePlan,
+                        artifact: archive,
+                        verbose: input.verbose,
+                        log: (line) => console.log(`${LOG} ${line}`),
+                    }),
+                    staple: () => stapleArtifact({
+                        notary: notarizePlan.notary,
+                        artifact: bundleDir,
+                        verbose: input.verbose,
+                        log: (line) => console.log(`${LOG} ${line}`),
+                    }),
+                });
+            }
             addApplicationsLink(volumeDir);
             await buildDmgImage({
                 volumeName: dmgVolumeName(settings),

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

@@ -702,6 +702,15 @@ export interface ConfigDataShip extends AppMetadata {
     extraFiles?: Record<string, string>;
     /** Arguments the launcher appends before the user's own. */
     execArgs?: string[];
+    /**
+     * Further executables of the SAME package, beside the primary one `gjsify.main` names.
+     *
+     * Each is one more launcher over the one shared bundle directory: the primary stays
+     * `bin/<binaryName>` (and `CFBundleExecutable` on macOS), these are `bin/<name>`.
+     * Absent means one executable, which is what every package shipped before this key.
+     * See `docs/ship-formats.md` for what each format does with them.
+     */
+    executables?: ShipExecutableOptions[];
     /**
      * How `--target flatpak` builds the app: the runtime it links against and
      * what the finished app is allowed to do.
@@ -719,6 +728,22 @@ export interface ConfigDataShip extends AppMetadata {
      */
     sign?: ShipSignOptions;
 }
+/** One entry of `gjsify.ship.executables`. */
+export interface ShipExecutableOptions {
+    /**
+     * The command name — `bin/<name>`, `Contents/MacOS/<name>`, `<name>.cmd`. Lower-case
+     * `[a-z0-9][a-z0-9._+-]*`, unique, and not the package's own `binaryName`.
+     */
+    name: string;
+    /** The built entry, project-relative, inside the directory `gjsify.main` lives in. */
+    entry: string;
+    /**
+     * Windows only: also stage a GUI-subsystem `<name>.exe` beside the `<name>.cmd`, so a
+     * double-click or shortcut opens no console window. Default `false` — a command-line
+     * tool wants the console.
+     */
+    gui?: boolean;
+}
 /**
  * `gjsify.ship.app` — the shipped runtime per OS, overriding `gjsify.app`.
  *
@@ -919,8 +944,8 @@ export interface ConfigDataFlatpak extends AppMetadata {
     lockfile?: string;
     /**
      * GitHub-Actions container image override for `gjsify flatpak ci`. Default is
-     * derived from runtime + runtimeVersion, e.g. gnome+50 →
-     * `ghcr.io/flathub-infra/flatpak-github-actions:gnome-50`.
+     * derived from runtime + runtimeVersion, e.g. gnome+51 →
+     * `ghcr.io/flathub-infra/flatpak-github-actions:gnome-51`.
      */
     ciContainer?: string;
     /** Branches the generated workflow triggers on. Default `['main']`. */

package/lib/utils/flatpak-runtime.d.ts

@@ -1,9 +1,9 @@
 /**
  * Default GNOME-Platform runtime version. Bumped per release window.
- * GNOME 50 = April 2026 stable; tracked in
+ * GNOME 51 = September 2026 stable (on Freedesktop 26.08); tracked in
  * https://docs.flathub.org/docs/for-app-authors/requirements.
  */
-export declare const DEFAULT_GNOME_RUNTIME_VERSION = "50";
+export declare const DEFAULT_GNOME_RUNTIME_VERSION = "51";
 /** Default Freedesktop-Platform runtime version (LTS-ish). */
 export declare const DEFAULT_FREEDESKTOP_RUNTIME_VERSION = "24.08";
 /** Permissive GUI defaults for GTK4 + Adwaita apps. */

package/lib/utils/flatpak-runtime.js

@@ -9,10 +9,10 @@
 // GNOME releases from the same `package.json`.
 /**
  * Default GNOME-Platform runtime version. Bumped per release window.
- * GNOME 50 = April 2026 stable; tracked in
+ * GNOME 51 = September 2026 stable (on Freedesktop 26.08); tracked in
  * https://docs.flathub.org/docs/for-app-authors/requirements.
  */
-export const DEFAULT_GNOME_RUNTIME_VERSION = '50';
+export const DEFAULT_GNOME_RUNTIME_VERSION = '51';
 /** Default Freedesktop-Platform runtime version (LTS-ish). */
 export const DEFAULT_FREEDESKTOP_RUNTIME_VERSION = '24.08';
 /** Permissive GUI defaults for GTK4 + Adwaita apps. */

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

@@ -117,3 +117,26 @@ export declare function signDmgImage(input: DmgSignInput & {
     verbose: boolean;
     workDir: string;
 }): Promise<void>;
+export interface BundleTicketSteps {
+    /** Write the archive `notarytool` submits (it takes no directory). */
+    writeArchive: () => void;
+    /** Submit the archive and wait for the verdict. */
+    notarize: () => Promise<void>;
+    /** Attach the ticket to the bundle ON DISK, the one the image is built from. */
+    staple: () => Promise<void>;
+}
+/**
+ * Notarise and staple the `.app` BEFORE the image is built from it (#162).
+ *
+ * Notarising only the `.dmg` clears the image and, online, the app inside it —
+ * but the ticket is stapled to the container, so an `.app` dragged out of the
+ * volume carries none and asks Gatekeeper over the network on every first launch.
+ * Apple's rule for the order (`stapler(1)`): staple after signing and notarising,
+ * and never `codesign` afterwards — stapling does not invalidate the signature,
+ * re-signing does invalidate the ticket. So the sequence is fixed:
+ * sign bundle → notarise bundle → staple bundle → build image → sign image →
+ * notarise image → staple image. This function owns the middle three and is a
+ * sequence of injected steps so the ORDER is unit-testable off macOS, where none
+ * of the tools run.
+ */
+export declare function stapleBundleBeforeImage(steps: BundleTicketSteps): Promise<void>;

package/lib/utils/ship/dmg.js

@@ -243,3 +243,22 @@ export async function signDmgImage(input) {
         throw new Error(`gjsify ship: ${DMG_SIGN_TOOL} failed on the image with ${describeExit(result)}.`);
     }
 }
+/**
+ * Notarise and staple the `.app` BEFORE the image is built from it (#162).
+ *
+ * Notarising only the `.dmg` clears the image and, online, the app inside it —
+ * but the ticket is stapled to the container, so an `.app` dragged out of the
+ * volume carries none and asks Gatekeeper over the network on every first launch.
+ * Apple's rule for the order (`stapler(1)`): staple after signing and notarising,
+ * and never `codesign` afterwards — stapling does not invalidate the signature,
+ * re-signing does invalidate the ticket. So the sequence is fixed:
+ * sign bundle → notarise bundle → staple bundle → build image → sign image →
+ * notarise image → staple image. This function owns the middle three and is a
+ * sequence of injected steps so the ORDER is unit-testable off macOS, where none
+ * of the tools run.
+ */
+export async function stapleBundleBeforeImage(steps) {
+    steps.writeArchive();
+    await steps.notarize();
+    await steps.staple();
+}

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

@@ -18,6 +18,14 @@ export interface LayoutIdentity {
     binaryName: string;
     /** Human-readable display name — the `<App>.app` directory a user sees in Finder. */
     name: string;
+    /**
+     * The package's further executables (`gjsify.ship.executables`), absent or empty for one.
+     * `bin/<name>` is each one's planned launcher; the layout decides where it lands.
+     */
+    executables?: readonly {
+        name: string;
+        gui: boolean;
+    }[];
 }
 /**
  * What a layout needs to render the metadata it OWNS.

package/lib/utils/ship/layout.js

@@ -509,6 +509,20 @@ export const LAYOUTS = {
                         }),
                     },
                 },
+                // A further executable that asked for a GUI subsystem gets the same stub
+                // under its own name, so its `.exe` finds its own `.cmd` and logs to its
+                // own leaf. The application's icon, since it is one application.
+                ...guiExecutables(input).map((executable) => ({
+                    path: windowsGuiLauncherPath({ ...input, binaryName: executable.name }),
+                    mode: 0o755,
+                    source: {
+                        kind: 'bytes',
+                        data: buildGuiLauncher({
+                            logLeaf: windowsLaunchLogLeaf({ ...input, binaryName: executable.name }),
+                            ...(icon === undefined ? {} : { icon: iconResources(icon) }),
+                        }),
+                    },
+                })),
             ];
         },
         // TWO now. `wingtk/gvsbuild` still hardcodes `self.platform = "x64"` and
@@ -570,7 +584,16 @@ export function windowsGuiLauncherPath(identity) {
  * for an OS with no such file.
  */
 export function payloadArchExemptions(os, identity) {
-    return os === 'win32' ? new Set([windowsGuiLauncherPath(identity)]) : undefined;
+    if (os !== 'win32')
+        return undefined;
+    return new Set([
+        windowsGuiLauncherPath(identity),
+        ...guiExecutables(identity).map((executable) => windowsGuiLauncherPath({ ...identity, binaryName: executable.name })),
+    ]);
+}
+/** The further executables that want a GUI-subsystem stub. */
+function guiExecutables(identity) {
+    return (identity.executables ?? []).filter((executable) => executable.gui);
 }
 /**
  * What the windows GUI launcher calls the file it writes under `%TEMP%`.
@@ -676,6 +699,12 @@ export function place(layout, identity, rel) {
     const dirs = layout.dirs(identity);
     if (rel === `bin/${identity.binaryName}`)
         return launcherPath(layout, identity);
+    // A further executable's launcher is placed exactly like the primary one — in the
+    // launcher directory, with the layout's extension — and not by the generic `bin/*` rule
+    // 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 });
     const libPrefix = `lib/${identity.binaryName}/`;
     const giPrefix = `${libPrefix}gi/`;
     if (rel.startsWith(giPrefix))

package/lib/utils/ship/msi.js

@@ -396,6 +396,12 @@ export function renderWxs(input) {
         // behind empty by an uninstall.
         `                <Directory Id="INSTALLDIR" Name="${xmlEscape(programDirName)}">`,
         ...lines,
+        `                    <Component Id="AddToPathComponent" Guid="${msiComponentGuid(settings, ':path')}" ` +
+            `Win64="${win64 ? 'yes' : 'no'}">`,
+        '                        <CreateFolder />',
+        '                        <Environment Id="GjsifyPath" Name="PATH" Action="set" Part="last" System="yes" ' +
+            'Permanent="no" Value="[INSTALLDIR]" />',
+        '                    </Component>',
         '                </Directory>',
         '            </Directory>',
         // Declared and left empty: the shortcut reaches it by `Directory=`, so this
@@ -406,6 +412,15 @@ export function renderWxs(input) {
         `        <Feature Id="Main" Title="${xmlEscape(settings.name)}" Level="1">`,
         ...componentIds.map((id) => `            <ComponentRef Id="${id}" />`),
         '        </Feature>',
+        // OPTIONAL and OFF by default (Level 2 is above the default install level of 1):
+        // appending the install directory to the MACHINE `PATH` changes every
+        // program on the box, so a user asks for it. Silent opt-in:
+        // `msiexec /i app.msi ADDTOPATH=1` or `ADDLOCAL=Main,AddToPath`. The
+        // `Environment` row is removed again on uninstall (`Permanent="no"`).
+        `        <Feature Id="AddToPath" Title="Add ${xmlEscape(settings.name)} to PATH" Level="2">`,
+        '            <ComponentRef Id="AddToPathComponent" />',
+        '            <Condition Level="1">ADDTOPATH=1</Condition>',
+        '        </Feature>',
         '    </Product>',
         '</Wix>',
         '',

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

@@ -5,6 +5,8 @@ export interface StageInputs {
     bundleFiles: readonly string[];
     /** The rendered launcher script. */
     launcher: string;
+    /** One rendered launcher per `settings.executables` entry, by name. Absent means none. */
+    executableLaunchers?: Readonly<Record<string, string>>;
     /** The rendered AppStream MetaInfo XML. */
     metainfo: string;
     /** The rendered desktop entry — required for `kind: 'app'`, unused for `'cli'`. */

package/lib/utils/ship/plan.js

@@ -27,6 +27,14 @@ export function planStage(settings, inputs) {
     const files = [];
     const libDir = `lib/${settings.binaryName}`;
     files.push({ path: `bin/${settings.binaryName}`, mode: 0o755, source: { kind: 'text', text: inputs.launcher } });
+    for (const executable of settings.executables) {
+        const text = inputs.executableLaunchers?.[executable.name];
+        if (text === undefined || !inputs.bundleFiles.includes(executable.entry)) {
+            throw new Error(`gjsify ship: \`gjsify.ship.executables\` "${executable.name}" runs ${executable.entry}, which is ` +
+                `not in ${settings.bundleDir} — build it before shipping, or the launcher would point at nothing.`);
+        }
+        files.push({ path: `bin/${executable.name}`, mode: 0o755, source: { kind: 'text', text } });
+    }
     for (const rel of inputs.bundleFiles) {
         files.push({
             path: posix.join(libDir, rel),

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, ShipSettings } from './types.js';
+import type { HostOs, ShipExecutable, ShipSettings } from './types.js';
 /** The subset of `package.json` the resolver reads. */
 export interface ShipPackageManifest {
     name?: string;
@@ -161,6 +161,22 @@ export interface ResolvedSettings {
  */
 export declare function resolveShipKind(ship: ConfigDataShip, flatpak: ConfigDataFlatpak): 'app' | 'cli';
 export declare function resolveShipSettings(input: SettingsInput): ResolvedSettings;
+/**
+ * `gjsify.ship.executables` → the further launchers of one package.
+ *
+ * REFUSED rather than normalised, for each rule: a name collision between two entries
+ * is one launcher silently replacing the other (`placeStage` would catch the Linux
+ * case and miss a Windows `Foo.cmd`/`foo.cmd` pair on a case-insensitive disk), an
+ * entry outside the bundle directory is a file the stage does not carry, and a name
+ * with a path separator or a space escapes `bin/`. All three install cleanly and
+ * start nothing, which is the class this command is built against.
+ */
+export declare function resolveShipExecutables(input: {
+    declared: unknown;
+    binaryName: string;
+    projectDir: string;
+    bundleDir: string;
+}): ShipExecutable[];
 /** 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,7 +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 { basename } from 'node:path';
+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';
 import { assertRelease, normaliseVersion } from './version.js';
@@ -221,6 +221,12 @@ export function resolveShipSettings(input) {
         fontFiles: discovered.fontFiles,
         extraFiles: ship.extraFiles ?? {},
         execArgs: ship.execArgs ?? [],
+        executables: resolveShipExecutables({
+            declared: ship.executables,
+            binaryName,
+            projectDir: input.projectDir,
+            bundleDir: discovered.bundleDir,
+        }),
         outDir: input.cli.outDir ?? ship.outDir ?? 'ship',
         arch: input.cli.arch ?? process.arch,
         app,
@@ -231,6 +237,61 @@ export function resolveShipSettings(input) {
     };
     return { settings, metadata, warnings };
 }
+/** A command name is a file name on every layout and a command a person types. */
+const EXECUTABLE_NAME = /^[a-z0-9][a-z0-9._+-]*$/;
+/**
+ * `gjsify.ship.executables` → the further launchers of one package.
+ *
+ * REFUSED rather than normalised, for each rule: a name collision between two entries
+ * is one launcher silently replacing the other (`placeStage` would catch the Linux
+ * case and miss a Windows `Foo.cmd`/`foo.cmd` pair on a case-insensitive disk), an
+ * entry outside the bundle directory is a file the stage does not carry, and a name
+ * with a path separator or a space escapes `bin/`. All three install cleanly and
+ * start nothing, which is the class this command is built against.
+ */
+export function resolveShipExecutables(input) {
+    const { declared } = input;
+    if (declared === undefined)
+        return [];
+    if (!Array.isArray(declared)) {
+        throw new Error('gjsify ship: `gjsify.ship.executables` must be a list of `{ "name", "entry", "gui"? }` objects.');
+    }
+    const seen = new Set([input.binaryName]);
+    return declared.map((row, index) => {
+        const at = `gjsify.ship.executables[${index}]`;
+        if (typeof row !== 'object' || row === null || Array.isArray(row)) {
+            throw new Error(`gjsify ship: \`${at}\` must be an object with \`name\` and \`entry\`.`);
+        }
+        const { name, entry, gui, ...unknown } = row;
+        const stray = Object.keys(unknown);
+        if (stray.length > 0) {
+            throw new Error(`gjsify ship: \`${at}\` has unknown key(s) ${stray.join(', ')}; known: name, entry, gui.`);
+        }
+        if (typeof name !== 'string' || !EXECUTABLE_NAME.test(name)) {
+            throw new Error(`gjsify ship: \`${at}.name\` must match ${EXECUTABLE_NAME} — it becomes \`bin/<name>\`, ` +
+                `\`Contents/MacOS/<name>\` and \`<name>.cmd\`, so it is lower-case with no path separator or space.`);
+        }
+        if (seen.has(name)) {
+            throw new Error(`gjsify ship: \`${at}.name\` "${name}" is already taken — by the package's own \`binaryName\` ` +
+                'or by an earlier entry. Two launchers cannot share one file name.');
+        }
+        seen.add(name);
+        if (typeof entry !== 'string' || entry === '') {
+            throw new Error(`gjsify ship: \`${at}.entry\` must be the project-relative path of a built bundle.`);
+        }
+        if (gui !== undefined && typeof gui !== 'boolean') {
+            throw new Error(`gjsify ship: \`${at}.gui\` must be a boolean.`);
+        }
+        const abs = isAbsolute(entry) ? entry : resolve(input.projectDir, entry);
+        const rel = relative(input.bundleDir, abs);
+        if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+            throw new Error(`gjsify ship: \`${at}.entry\` ${entry} is outside ${input.bundleDir}, the directory \`gjsify.main\` ` +
+                'lives in — only that directory is staged, so the launcher would point at a file the package ' +
+                'does not carry. Build the entries into one directory.');
+        }
+        return { name, entry: rel.split(sep).join(posix.sep), gui: gui === true };
+    });
+}
 /**
  * The ONE place a ship target's ENTRY is decided — {@link resolveShipApp}'s twin.
  *

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

@@ -140,6 +140,7 @@ export function toPackSettings(settings) {
         minGjsVersion: settings.minGjsVersion,
         minNodeVersion: settings.minNodeVersion,
         flatpak: settings.flatpak,
+        executables: settings.executables.map(({ name, gui }) => ({ name, gui })),
     };
 }
 /** Absolute path of a stage's manifest. */
@@ -499,6 +500,18 @@ function readPackSettings(data, at) {
         minGjsVersion: expectString(data.minGjsVersion, field('minGjsVersion')),
         minNodeVersion: expectString(data.minNodeVersion, field('minNodeVersion')),
         flatpak: readFlatpakSettings(record(data.flatpak, field('flatpak')), field('flatpak')),
+        // OPTIONAL on read and NOT a schema bump: a stage written before
+        // `gjsify.ship.executables` is a one-executable stage, `[]` is exactly
+        // right for it, and an older reader meeting a newer stage refuses the
+        // extra `.exe` stubs by name in its architecture check rather than
+        // dropping them silently.
+        executables: expectArray(data.executables ?? [], field('executables')).map((entry, index) => {
+            const row = record(entry, field(`executables[${index}]`));
+            if (typeof row.gui !== 'boolean') {
+                throw new Error(`gjsify ship: ${field(`executables[${index}].gui`)} must be a boolean.`);
+            }
+            return { name: expectString(row.name, field(`executables[${index}].name`)), gui: row.gui };
+        }),
     };
 }
 /**

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

@@ -69,7 +69,7 @@ export type FormatId = 'deb' | 'rpm' | 'flatpak' | 'appimage' | 'macos-app' | 'm
  * instead of being rediscovered per call site. A `.deb` says
  * `Depends: gir1.2-gtk-4.0`, an `.rpm` says `Requires: gtk4`, and both are
  * package names in a distribution's namespace. A Flatpak has no such field: it
- * declares ONE dependency, its runtime (`org.gnome.Platform//50`), in the
+ * declares ONE dependency, its runtime (`org.gnome.Platform//51`), in the
  * manifest — and inside that runtime a typelib is either present or nothing on
  * the system provides it, so there is no package to name and no gap a name
  * could close.
@@ -408,6 +408,24 @@ export interface PackSettings {
     minNodeVersion: string;
     /** The Flatpak manifest's non-payload half, fully defaulted at stage time. */
     flatpak: ShipFlatpakSettings;
+    /**
+     * The package's FURTHER executables (`gjsify.ship.executables`); `[]` for a single-executable
+     * package. Name and subsystem only: the entry each one runs is already inside its staged
+     * launcher, and the packing host needs the names for the Windows arch exemption.
+     */
+    executables: ShipExecutableFacts[];
+}
+/** What the packing host needs to know about one further executable. */
+export interface ShipExecutableFacts {
+    /** The command name — `bin/<name>`, `Contents/MacOS/<name>`, `<name>.cmd`. */
+    name: string;
+    /** Whether the windows layout stages a GUI-subsystem `<name>.exe` for it. */
+    gui: boolean;
+}
+/** One further executable, as resolved from `gjsify.ship.executables`. */
+export interface ShipExecutable extends ShipExecutableFacts {
+    /** Its entry inside {@link ShipSettings.bundleDir}, POSIX-separated. */
+    entry: string;
 }
 /**
  * What the generated Flatpak manifest says about everything that is not the payload.
@@ -507,6 +525,8 @@ export interface ShipSettings extends PackSettings {
     extraFiles: Record<string, string>;
     /** Arguments appended to the launcher's `exec` line. */
     execArgs: string[];
+    /** The further executables with their entries; narrows {@link PackSettings.executables}. */
+    executables: ShipExecutable[];
     /** Output root; `stage/`, `overlay/` and `out/` hang under it. */
     outDir: string;
     /** Target architecture in `process.arch` spelling. */