@gjsify/cli 0.43.0 → 0.44.0

package/lib/actions/build.js

@@ -630,7 +630,7 @@ export class BuildAction {
             throw new Error('gjsify build: an .html entry needs an explicit --outfile ' +
                 '(e.g. --outfile dist-app/app.js); the emitted index.html is written beside it.');
         }
-        const { consoleShim, globals } = this.configData;
+        const { consoleShim, globals, dialect } = this.configData;
         const userExternal = Array.isArray(userBundler.external) ? userBundler.external : undefined;
         const userBanner = typeof userBundler.output?.banner === 'string' ? userBundler.output.banner : undefined;
         const pluginOpts = {
@@ -640,6 +640,7 @@ export class BuildAction {
             exclude,
             reflection: typescript?.reflection,
             consoleShim,
+            ...(dialect !== undefined ? { dialect } : {}),
             ...(aliases ? { aliases } : {}),
             ...(opts.preserveDefaultExport ? { preserveDefaultExport: true } : {}),
             ...(opts.toolchainAnchor !== undefined ? { toolchainAnchor: opts.toolchainAnchor } : {}),

package/lib/commands/affected-classify.js

@@ -85,11 +85,13 @@ const IGNORE = [
     /^docs\//,
     ...OTHER_WORKFLOW_INPUTS,
     // Neither `@gjsify/node-gi` (the Node-native GI engine) nor `@gjsify/napi` (the
-    // N-API host over SpiderMonkey) is a gjsify workspace member: the GJS-first
-    // install/foreach tooling cannot build their node-gyp addons or Vala+C++/meson
-    // shim, so `main.yml` neither builds nor tests them and their own workflows are
-    // the source of truth. Without the carve-outs their files map to no workspace,
-    // land in `unmatched`, and force a full run on every node-gi/napi PR.
+    // N-API host over SpiderMonkey) is a gjsify workspace member — WHY is ADR 0031,
+    // which this comment used to carry alone. The short of it: node-gi's `build` is
+    // `node-gyp rebuild`, so a member would enter `foreach build` in a container with
+    // no GTK/GI toolchain. `main.yml` therefore neither builds nor tests them and
+    // their own workflows are the source of truth. Without the carve-outs their files
+    // map to no workspace, land in `unmatched`, and force a full run on every
+    // node-gi/napi PR.
     /^packages\/node-gi\//,
     /^packages\/napi\//,
     // Flatpak build/distribution tooling (SDK-extension manifest + metainfo). No

package/lib/commands/build.js

@@ -1,5 +1,6 @@
 import { Config } from '../config.js';
 import { BuildAction } from '../actions/build.js';
+import { SOURCE_DIALECTS } from '@gjsify/rolldown-plugin-gjsify';
 // NO `normalize: true` ON THE GLOB-BEARING OPTIONS — `entry-points` and
 // `exclude` are PATTERNS, not paths.
 //
@@ -106,6 +107,11 @@ export const buildCommand = {
             type: 'string',
             choices: ['silent', 'error', 'warning', 'info', 'debug', 'verbose'],
             default: 'warning',
+        })
+            .option('dialect', {
+            description: "The dialect the SOURCE is written in. 'react-native' aliases 'react-native' onto '@gjsify/react-native' and fails the build on an import whose ADR 0032 support-table status is not supported/partial. GJS and Node app builds. This is NOT gjsify.runtimes['react-native'], which declares the runtime a package RUNS on — the two answer opposite questions.",
+            type: 'string',
+            choices: [...SOURCE_DIALECTS],
         })
             .option('console-shim', {
             description: 'Inject a console shim into GJS builds for clean output without the GLib prefix and with working ANSI colors. Use --no-console-shim to disable. Only applies to GJS app builds.',

package/lib/commands/flatpak/ci.js

@@ -9,7 +9,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { Config } from '../../config.js';
-import { defaultCiContainer, looksLikeAppId, readPackageJson, resolveRuntime } from './utils.js';
+import { defaultCiContainer, looksLikeAppId, readPackageJson } from './utils.js';
+import { resolveRuntime } from '../../utils/flatpak-runtime.js';
+import { pickFlatpakBuildKeys } from '../../utils/ship/flatpak-config.js';
 export const flatpakCiCommand = {
     command: 'ci',
     description: 'Scaffold .github/workflows/flatpak.yml using the flathub-infra container + flatpak-builder@v6 action.',
@@ -68,7 +70,13 @@ export const flatpakCiCommand = {
         }
         const manifest = args.manifest ?? `${appId}.json`;
         const bundle = args.bundle ?? `${appId}.flatpak`;
-        const { runtime, runtimeVersion } = resolveRuntime(flatpak, {});
+        // Through the deprecation window, not straight off `gjsify.flatpak`: a
+        // project told to move these keys to `gjsify.ship.flatpak` must not lose
+        // them here — the CI container tag is derived from the runtime, so
+        // reading the old block alone scaffolds a workflow against the default
+        // GNOME release rather than the pinned one.
+        const buildKeys = pickFlatpakBuildKeys(configData.ship?.flatpak, flatpak).values;
+        const { runtime, runtimeVersion } = resolveRuntime(buildKeys, {});
         const runtimeImage = args.runtimeImage ??
             flatpak.ciContainer ??
             defaultCiContainer(runtime, runtimeVersion);

package/lib/commands/flatpak/init.js

@@ -13,7 +13,9 @@
 //     with `skip-icons-check`.
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { DEFAULT_CLI_FINISH_ARGS, DEFAULT_GUI_FINISH_ARGS, looksLikeAppId, readPackageJson, resolveRuntime, } from './utils.js';
+import { looksLikeAppId, readPackageJson } from './utils.js';
+import { DEFAULT_CLI_FINISH_ARGS, DEFAULT_GUI_FINISH_ARGS, deriveAppendPath, resolveRuntime, } from '../../utils/flatpak-runtime.js';
+import { pickFlatpakBuildKeys } from '../../utils/ship/flatpak-config.js';
 import { renderDesktop, renderFlathubJson, renderMetainfoApp, renderMetainfoCli, validateScaffoldInputs, } from './scaffold.js';
 import { Config } from '../../config.js';
 import { OxcNotFoundError, hasOxcDevDep, runOxfmt } from '../../utils/oxc-resolve.js';
@@ -109,17 +111,24 @@ export const flatpakInitCommand = {
                 'or rename the package to a reverse-DNS id like org.example.MyApp.');
         }
         const kind = args.kind ?? flatpak.kind ?? (args.cliOnly ? 'cli' : 'app');
-        const { runtime, runtimeId, sdk, runtimeVersion } = resolveRuntime(flatpak, {
+        // The six BUILD keys come through the deprecation window
+        // (`utils/ship/flatpak-config.ts`), not straight off `gjsify.flatpak`.
+        // These commands did NOT move, but the keys did: a project that followed
+        // `ship`'s own advice and moved them would otherwise lose them here and
+        // get a committed manifest against a different runtime version with
+        // different finish-args, silently, at exit 0.
+        const buildKeys = pickFlatpakBuildKeys(configData.ship?.flatpak, flatpak).values;
+        const { runtime, runtimeId, sdk, runtimeVersion } = resolveRuntime(buildKeys, {
             runtime: args.runtime,
             runtimeVersion: args.runtimeVersion,
         });
-        const sdkExtensions = mergeArrays(flatpak.sdkExtensions, args.sdkExtension);
-        const appendPath = flatpak.appendPath ?? (sdkExtensions?.length ? deriveAppendPath(sdkExtensions) : undefined);
+        const sdkExtensions = mergeArrays(buildKeys.sdkExtensions, args.sdkExtension);
+        const appendPath = buildKeys.appendPath ?? (sdkExtensions?.length ? deriveAppendPath(sdkExtensions) : undefined);
         const command = args.command ?? flatpak.command ?? appId;
         const explicitFinishArgs = args.finishArg;
         const finishArgs = explicitFinishArgs !== undefined
             ? explicitFinishArgs
-            : (flatpak.finishArgs ?? (kind === 'cli' ? DEFAULT_CLI_FINISH_ARGS : DEFAULT_GUI_FINISH_ARGS));
+            : (buildKeys.finishArgs ?? (kind === 'cli' ? DEFAULT_CLI_FINISH_ARGS : DEFAULT_GUI_FINISH_ARGS));
         const manifest = {
             id: appId,
             runtime: runtimeId,
@@ -133,7 +142,7 @@ export const flatpakInitCommand = {
         }
         manifest.command = command;
         manifest['finish-args'] = finishArgs;
-        const cleanup = flatpak.cleanup;
+        const cleanup = buildKeys.cleanup;
         if (cleanup?.length)
             manifest.cleanup = cleanup;
         // Module assembly. Two precedence rules:
@@ -253,16 +262,6 @@ function mergeArrays(a, b) {
         return undefined;
     return [...(a ?? []), ...(b ?? [])];
 }
-function deriveAppendPath(sdkExtensions) {
-    const out = [];
-    for (const ext of sdkExtensions) {
-        const m = /^org\.freedesktop\.Sdk\.Extension\.([A-Za-z0-9-]+)$/.exec(ext);
-        if (m)
-            out.push(`/usr/lib/sdk/${m[1]}/bin`);
-    }
-    out.push('/app/bin');
-    return out;
-}
 function deriveModuleName(appId) {
     const parts = appId.split('.');
     return parts[parts.length - 1] || appId;

package/lib/commands/flatpak/utils.d.ts

@@ -1,32 +1,6 @@
-import type { ConfigDataFlatpak } from '../../types/config-data.js';
-/**
- * Default GNOME-Platform runtime version. Bumped per release window.
- * GNOME 50 = April 2026 stable; tracked in
- * https://docs.flathub.org/docs/for-app-authors/requirements.
- */
-export declare const DEFAULT_GNOME_RUNTIME_VERSION = "50";
-/** Default Freedesktop-Platform runtime version (LTS-ish). */
-export declare const DEFAULT_FREEDESKTOP_RUNTIME_VERSION = "24.08";
-/** Permissive GUI defaults for GTK4 + Adwaita apps. */
-export declare const DEFAULT_GUI_FINISH_ARGS: string[];
-/** Lean defaults for headless CLI tools — no display, no GPU. */
-export declare const DEFAULT_CLI_FINISH_ARGS: string[];
 /** Read package.json from a directory. Throws a helpful error if missing/invalid. */
 export declare function readPackageJson(dir: string): Record<string, unknown>;
 /** True if a name string looks like a reverse-DNS Flatpak app id. */
 export declare function looksLikeAppId(value: unknown): value is string;
-/**
- * Pick the runtime + sdk + version triple from config + CLI overrides.
- * `--runtime` and `--runtime-version` flags win over config values.
- */
-export declare function resolveRuntime(flatpak: ConfigDataFlatpak | undefined, overrides: {
-    runtime?: string;
-    runtimeVersion?: string;
-}): {
-    runtime: 'gnome' | 'freedesktop';
-    runtimeId: string;
-    sdk: string;
-    runtimeVersion: string;
-};
 /** Default container image for the GitHub Actions workflow. */
 export declare function defaultCiContainer(runtime: 'gnome' | 'freedesktop', runtimeVersion: string): string;

package/lib/commands/flatpak/utils.js

@@ -1,18 +1,10 @@
 // Shared helpers for the `gjsify flatpak <sub>` subcommand group.
+//
+// The runtime/SDK/finish-args half moved to `utils/flatpak-runtime.ts` when
+// `gjsify ship --target flatpak` became its second caller — see that file's
+// header. What is left here is what only these subcommands ask.
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-/**
- * Default GNOME-Platform runtime version. Bumped per release window.
- * GNOME 50 = April 2026 stable; tracked in
- * https://docs.flathub.org/docs/for-app-authors/requirements.
- */
-export const DEFAULT_GNOME_RUNTIME_VERSION = '50';
-/** Default Freedesktop-Platform runtime version (LTS-ish). */
-export const DEFAULT_FREEDESKTOP_RUNTIME_VERSION = '24.08';
-/** Permissive GUI defaults for GTK4 + Adwaita apps. */
-export const DEFAULT_GUI_FINISH_ARGS = ['--device=dri', '--share=ipc', '--socket=fallback-x11', '--socket=wayland'];
-/** Lean defaults for headless CLI tools — no display, no GPU. */
-export const DEFAULT_CLI_FINISH_ARGS = [];
 /** Read package.json from a directory. Throws a helpful error if missing/invalid. */
 export function readPackageJson(dir) {
     const path = resolve(dir, 'package.json');
@@ -34,23 +26,6 @@ export function readPackageJson(dir) {
 export function looksLikeAppId(value) {
     return typeof value === 'string' && /^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z][A-Za-z0-9_-]*){2,}$/.test(value);
 }
-/**
- * Pick the runtime + sdk + version triple from config + CLI overrides.
- * `--runtime` and `--runtime-version` flags win over config values.
- */
-export function resolveRuntime(flatpak, overrides) {
-    const runtime = (overrides.runtime ?? flatpak?.runtime ?? 'gnome');
-    if (runtime !== 'gnome' && runtime !== 'freedesktop') {
-        throw new Error(`gjsify flatpak: unknown runtime "${runtime}" (expected "gnome" or "freedesktop")`);
-    }
-    const runtimeVersion = overrides.runtimeVersion ??
-        flatpak?.runtimeVersion ??
-        (runtime === 'gnome' ? DEFAULT_GNOME_RUNTIME_VERSION : DEFAULT_FREEDESKTOP_RUNTIME_VERSION);
-    if (runtime === 'gnome') {
-        return { runtime, runtimeId: 'org.gnome.Platform', sdk: 'org.gnome.Sdk', runtimeVersion };
-    }
-    return { runtime, runtimeId: 'org.freedesktop.Platform', sdk: 'org.freedesktop.Sdk', runtimeVersion };
-}
 /** Default container image for the GitHub Actions workflow. */
 export function defaultCiContainer(runtime, runtimeVersion) {
     const tag = `${runtime}-${runtimeVersion}`;

package/lib/commands/ship.js

@@ -20,7 +20,7 @@
 // this command, are the later stages of the same ADR — and they are the reason
 // the split exists at all: a `.dmg` is a UDIF image over a real HFS+/APFS
 // volume and no Linux host in this tree can write one (§ A1).
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { Config } from '../config.js';
 import { renderDesktopEntry, renderMetainfoApp, renderMetainfoCli, validateAppMetadata, } from '../utils/app-metadata.js';
@@ -29,24 +29,31 @@ import { describeExit, spawnToCompletion } from '../utils/spawn.js';
 import { buildDeb } from '../utils/ship/deb.js';
 import { deriveDepends, warnAboutGjsFloor } from '../utils/ship/depends.js';
 import { discoverPayload } from '../utils/ship/discover.js';
-import { resolveFormats, FORMAT_IDS } from '../utils/ship/formats.js';
+import { buildFlatpakBundle } from '../utils/ship/flatpak.js';
+import { assertHostCanFinish, assertToolsInstalled, resolveFormats, DEFAULT_FORMAT_IDS, FORMAT_IDS, } from '../utils/ship/formats.js';
 import { scanGiNamespaces } from '../utils/ship/gi-namespaces.js';
 import { assertPayloadMatchesArch, buildTimestamp, isArchIndependent, readPayloadFacts, } from '../utils/ship/payload.js';
 import { assertOverlayIsLicensed, planOverlay, planStage } from '../utils/ship/plan.js';
 import { renderLauncher } from '../utils/ship/launcher.js';
 import { buildRpm } from '../utils/ship/rpm.js';
 import { declaredBundlePath, resolveShipSettings } from '../utils/ship/settings.js';
-import { assertExpectedTarget, assertFormatsStaged, formatTarget, overlayFiles, readStageManifest, resolveStageMtime, warnOnToolSkew, writeStageManifest, } from '../utils/ship/stage-manifest.js';
+import { assertExpectedTarget, assertFormatsStaged, formatTarget, overlayFiles, readStageManifest, resolveStageMtime, warnOnToolSkew, writeStageManifest, STAGE_MANIFEST_FILE, } from '../utils/ship/stage-manifest.js';
 import { readStage, writeStage } from '../utils/ship/stage-writer.js';
 const LOG = '[gjsify ship]';
 export const shipCommand = {
     command: 'ship',
     description: `Build installable artifacts (${FORMAT_IDS.join(', ')}) from the current project.`,
+    // `DEFAULT_FORMAT_IDS` in the flag text, `FORMAT_IDS` in the description:
+    // one of them answers "what can this build", the other "what will it build
+    // if I say nothing", and they stopped being the same list when a host-bound
+    // format arrived.
     builder: (yargs) => yargs
         .option('target', {
         type: 'string',
         array: true,
-        description: `Formats to build, comma-separated or repeated. Default: ${FORMAT_IDS.join(',')}.`,
+        description: `Formats to build, comma-separated or repeated. Default: ${DEFAULT_FORMAT_IDS.join(',')}. ` +
+            `Also available, and opt-in because it needs tooling this CLI does not carry: ` +
+            `${FORMAT_IDS.filter((id) => !DEFAULT_FORMAT_IDS.includes(id)).join(', ')}.`,
     })
         .option('out', {
         type: 'string',
@@ -81,7 +88,8 @@ export const shipCommand = {
         .option('verbose', {
         type: 'boolean',
         default: false,
-        description: 'Print each staged file and the GI namespaces the bundle imports.',
+        description: 'Print each staged file, the GI namespaces the bundle imports, and every tool a ' +
+            'host-bound packer invokes.',
     }),
     handler: async (args) => {
         // The two phases share nothing but `packOne`, and the branch is first
@@ -111,7 +119,15 @@ async function assemble(args) {
     const pkg = (readPackageJson(join(projectDir, 'package.json')) ?? {});
     // Resolved before anything is built or written: a typo'd `--target`
     // should not cost a build and leave a half-written `ship/stage/`.
-    const formats = resolveFormats(args.target ?? ship.targets ?? FORMAT_IDS);
+    const formats = resolveFormats(args.target ?? ship.targets ?? DEFAULT_FORMAT_IDS);
+    // BEFORE the build, not before the pack. `gjsify ship` runs the project's
+    // own `build` script first, so discovering a missing `flatpak-builder`
+    // afterwards costs the whole build for a refusal that was knowable up
+    // front. Skipped under `--stage`, which is precisely the phase that does
+    // NOT need the format's tooling — that asymmetry is the point of the split.
+    if (!args.stage)
+        for (const format of formats)
+            assertCanPack(format);
     if (!args['skip-build'])
         await runProjectBuild(projectDir);
     const discovered = discoverPayload({
@@ -189,17 +205,26 @@ async function assemble(args) {
     // paths the payload will have.
     const facts = readPayloadFacts(staged);
     for (const format of formats) {
-        deriveDepends(format.id, {
+        // `format.depends`, not `format.id`: a Flatpak has no package
+        // dependency list at all, and asking for one would either invent a
+        // third column in the typelib table or silently reuse rpm's — which is
+        // the exact defect `check-ship-format-vocabulary.mjs`'s header records
+        // from the other direction (a third format taking rpm's package name
+        // into a Debian `Depends:`, at exit 0).
+        if (format.depends === null)
+            continue;
+        deriveDepends(format.depends, {
             namespaces,
             hasIcons: facts.hasIcons,
             hasSchemas: facts.hasSchemas,
-            extra: settings.extraDepends[format.id],
+            extra: settings.extraDepends[format.depends],
             typelibPackages: settings.typelibPackages,
             bundledTypelibs: facts.bundledTypelibs,
             minGjsVersion: settings.minGjsVersion,
         });
-        for (const warning of warnAboutGjsFloor(format.id, settings.minGjsVersion))
+        for (const warning of warnAboutGjsFloor(format.depends, settings.minGjsVersion)) {
             console.warn(`${LOG} ${warning}`);
+        }
     }
     // Written unconditionally, not only under `--stage`: a `ship/stage/` that
     // is sometimes packable elsewhere and sometimes not is a worse contract
@@ -222,6 +247,7 @@ async function assemble(args) {
             outRoot,
             namespaces,
             mtime,
+            verbose: args.verbose,
         }));
     }
     printArtifacts(projectDir, artifacts);
@@ -256,6 +282,8 @@ async function finishFromStage(args, fromStage) {
     assertExpectedTarget(manifest, args['expect-target']);
     const formats = resolveFormats(args.target ?? manifest.formats);
     assertFormatsStaged(manifest, formats);
+    for (const format of formats)
+        assertCanPack(format);
     for (const warning of warnOnToolSkew(manifest))
         console.warn(`${LOG} ${warning}`);
     const { mtime, warnings } = resolveStageMtime(manifest);
@@ -275,8 +303,10 @@ async function finishFromStage(args, fromStage) {
     const outRoot = args.out === undefined ? dirname(stageDir) : resolve(cwd, args.out);
     const artifacts = [];
     for (const format of formats) {
-        for (const warning of warnAboutGjsFloor(format.id, manifest.settings.minGjsVersion)) {
-            console.warn(`${LOG} ${warning}`);
+        if (format.depends !== null) {
+            for (const warning of warnAboutGjsFloor(format.depends, manifest.settings.minGjsVersion)) {
+                console.warn(`${LOG} ${warning}`);
+            }
         }
         artifacts.push(await packOne({
             format,
@@ -288,6 +318,7 @@ async function finishFromStage(args, fromStage) {
             outRoot,
             namespaces: manifest.namespaces,
             mtime,
+            verbose: args.verbose,
         }));
     }
     printArtifacts(cwd, artifacts);
@@ -302,15 +333,17 @@ async function packOne(input) {
     // this answers used to be answered from the project's file lists, which are
     // absolute paths on the build host and therefore unavailable here.
     const facts = readPayloadFacts(payload);
-    const depends = deriveDepends(format.id, {
-        namespaces: input.namespaces,
-        hasIcons: facts.hasIcons,
-        hasSchemas: facts.hasSchemas,
-        extra: settings.extraDepends[format.id],
-        typelibPackages: settings.typelibPackages,
-        bundledTypelibs: facts.bundledTypelibs,
-        minGjsVersion: settings.minGjsVersion,
-    });
+    const depends = format.depends === null
+        ? []
+        : deriveDepends(format.depends, {
+            namespaces: input.namespaces,
+            hasIcons: facts.hasIcons,
+            hasSchemas: facts.hasSchemas,
+            extra: settings.extraDepends[format.depends],
+            typelibPackages: settings.typelibPackages,
+            bundledTypelibs: facts.bundledTypelibs,
+            minGjsVersion: settings.minGjsVersion,
+        });
     // `--arch` is a CLAIM about the payload and nothing else compared it to one:
     // an x86-64 `.so` staged with `--arch arm64` packed at exit 0 and `rpm -qp
     // --qf %{ARCH}` confirmed `aarch64`, because rpm reads the header and the
@@ -327,36 +360,65 @@ async function packOne(input) {
     assertPayloadMatchesArch(payload, input.arch);
     const archLabel = format.archName(input.arch, isArchIndependent(payload));
     const common = { settings, payload, prefix: format.prefix, depends, archLabel, mtime };
+    const outDir = join(outRoot, 'out');
+    mkdirSync(outDir, { recursive: true });
+    const target = join(outDir, format.fileName(settings, archLabel));
     // A SWITCH with a `never` guard, not a ternary. `format.id === 'deb' ? deb : rpm`
     // read as a dispatch and behaved as one only while there were exactly two
     // formats: a third would have taken the else-branch and written an RPM under a
     // `.dmg` name, at exit 0. This is the same closed-vocabulary hazard the format
     // list has, one level worse — a wrong ARTIFACT rather than a rejected
     // declaration — so the compiler owns it now.
-    let bytes;
+    //
+    // Each branch WRITES `target` rather than returning bytes. It used to return
+    // them, which is the right shape only while every packer is a byte writer: a
+    // Flatpak is produced by `flatpak build-bundle`, so its bytes exist as a file
+    // before this process could hold them, and reading a bundle back into memory
+    // to hand it to one `writeFileSync` would be a copy for the sake of a
+    // signature. The size is stat'ed off what landed, for every format.
     switch (format.id) {
         case 'deb':
-            bytes = await buildDeb(common);
+            writeFileSync(target, await buildDeb(common));
             break;
         case 'rpm':
-            bytes = await buildRpm(common);
+            writeFileSync(target, await buildRpm(common));
+            break;
+        case 'flatpak':
+            await buildFlatpakBundle({
+                settings,
+                stageDir,
+                overlayDir,
+                stageManifestFile: STAGE_MANIFEST_FILE,
+                workDir: join(outRoot, 'flatpak'),
+                target,
+                archLabel,
+                verbose: input.verbose,
+            });
             break;
         default: {
             const unhandled = format.id;
             throw new Error(`gjsify ship: no packer is wired for format "${String(unhandled)}".`);
         }
     }
-    const outDir = join(outRoot, 'out');
-    mkdirSync(outDir, { recursive: true });
-    const target = join(outDir, format.fileName(settings, archLabel));
-    writeFileSync(target, bytes);
-    return { format: format.id, path: target, size: bytes.byteLength };
+    return { format: format.id, path: target, size: statSync(target).size };
 }
 function printArtifacts(base, artifacts) {
     for (const artifact of artifacts) {
         console.log(`${LOG} ${artifact.format}: ${relative(base, artifact.path)} (${artifact.size} bytes)`);
     }
 }
+/**
+ * Refuse a format this host cannot finish, and say which half is missing.
+ *
+ * Two checks and not one, because the fixes differ: the wrong OS needs another
+ * machine, an absent tool needs a package. Both run on the pack path only —
+ * `--stage` deliberately needs neither, which is what makes a Flatpak
+ * assemblable on a host that cannot build one (ADR 0024 § A1).
+ */
+function assertCanPack(format) {
+    assertHostCanFinish(format);
+    assertToolsInstalled(format);
+}
 /**
  * Refuse a build target this command cannot package correctly.
  *

package/lib/config.js

@@ -4,6 +4,7 @@ import { basename, dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isGjs, hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { buildAppForRuntime } from './utils/runtimes.js';
+import { DIALECT_APPS, isSourceDialect, SOURCE_DIALECTS } from '@gjsify/rolldown-plugin-gjsify';
 /**
  * Does the failed `import()` of a config look like a MODULE-RESOLUTION failure
  * (the config imports something GJS's ESM loader can't resolve for an external
@@ -268,6 +269,18 @@ export class Config {
         configData.exclude = cliArgs.exclude || [];
         if (cliArgs.consoleShim !== undefined)
             configData.consoleShim = cliArgs.consoleShim;
+        // `--dialect` narrows here rather than at the call site. yargs `choices`
+        // already rejects an unknown value typed on the command line, but a
+        // `gjsify.dialect` in package.json or `.gjsifyrc.*` never passes through
+        // yargs — so the one place both spellings meet is the one place that
+        // checks, and it names the alternatives instead of silently ignoring.
+        if (cliArgs.dialect !== undefined) {
+            if (!isSourceDialect(cliArgs.dialect)) {
+                throw new Error(`gjsify build: "${cliArgs.dialect}" is not a source dialect. Known: ${SOURCE_DIALECTS.join(', ')}. ` +
+                    'This is the dialect the SOURCE is written in — not gjsify.runtimes, which declares the runtime a package RUNS on.');
+            }
+            configData.dialect = cliArgs.dialect;
+        }
         // Default `--app` FOLLOWS the host runtime the CLI executes in: gjs when
         // run under gjs, node when run under node/bun/deno (both consume the
         // `--app node` bundle). Applied post-merge (not as a yargs `default:`)
@@ -278,6 +291,18 @@ export class Config {
         if (cliArgs.app !== undefined)
             configData.app = cliArgs.app;
         configData.app ??= buildAppForRuntime(hostRuntime());
+        // A dialect only composes on the targets that have a plugin for it, and
+        // saying so is the whole point: `--dialect react-native --app browser`
+        // parses, resolves and then composes NOTHING, so the alias never happens,
+        // the support gate never runs, and the build succeeds while doing none of
+        // what was asked. That is the shape this repo keeps paying for — a flag
+        // accepted and ignored. Checked here rather than in the plugin because the
+        // plugin only ever sees the targets it was composed on.
+        if (configData.dialect !== undefined && !DIALECT_APPS.has(configData.app)) {
+            throw new Error(`gjsify build: --dialect ${configData.dialect} has no effect on --app ${configData.app}. ` +
+                `It composes on ${[...DIALECT_APPS].join(' and ')} only. ` +
+                'Drop the dialect, or build one of those targets.');
+        }
         if (cliArgs.globals !== undefined)
             configData.globals = cliArgs.globals;
         // Fallback applied post-merge (not as a yargs `default:`) so a

package/lib/types/cli-build-options.d.ts

@@ -25,6 +25,17 @@ export interface CliBuildOptions {
      * working ANSI colors). Disable with `--no-console-shim`. Default: true.
      */
     consoleShim?: boolean;
+    /**
+     * The dialect the SOURCE is written in — `--dialect react-native` (ADR 0032):
+     * alias `react-native` onto `@gjsify/react-native` and fail the build on an
+     * import whose support-table status is not `supported` or `partial`. `gjs` and
+     * `node` targets. Default: unset — a tree with a phone leg has the real
+     * `react-native` on purpose.
+     *
+     * A `string` here and a `SourceDialect` in `ConfigData`: yargs hands back
+     * whatever was typed, and the narrowing happens once, where the value is read.
+     */
+    dialect?: string;
     /**
      * Comma-separated global identifiers the code needs, e.g.
      * `"fetch,Buffer,process,URL,crypto"`. Each maps to the corresponding

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

@@ -1,5 +1,5 @@
 import type { RolldownOptions, OutputOptions, RolldownPluginOption } from 'rolldown';
-import type { App } from '@gjsify/rolldown-plugin-gjsify';
+import type { App, SourceDialect } from '@gjsify/rolldown-plugin-gjsify';
 import type { ConfigDataLibrary, ConfigDataTypescript } from './index.js';
 /**
  * Plugin entry resolvable by package name from the project's `node_modules`, so
@@ -82,6 +82,20 @@ export interface ConfigData {
      * working ANSI colors). Default: true.
      */
     consoleShim?: boolean;
+    /**
+     * The dialect the SOURCE is written in (ADR 0032 § 2 + § 8). `'react-native'`
+     * aliases `react-native` onto `@gjsify/react-native` and gates every named
+     * import against the support table at BUILD time. `gjs` and `node` app builds.
+     * Default: unset.
+     *
+     * Opt-in and never inferred from the dependency list: a monorepo with a phone
+     * leg installs the real `react-native` on purpose, and redirecting the
+     * specifier for every build in that tree would change what that leg resolves.
+     *
+     * NOT `gjsify.runtimes['react-native']`, which answers the opposite question —
+     * see the header of `SourceDialect`.
+     */
+    dialect?: SourceDialect;
     /** Comma-separated global identifiers to register. Format: see CliBuildOptions. */
     globals?: string;
     /**
@@ -496,8 +510,66 @@ export interface ConfigDataShip extends AppMetadata {
     extraFiles?: Record<string, string>;
     /** Arguments the launcher appends before the user's own. */
     execArgs?: string[];
+    /**
+     * How `--target flatpak` builds the app: the runtime it links against and
+     * what the finished app is allowed to do.
+     *
+     * The new home of the `gjsify.flatpak` BUILD keys (ADR 0024 § 8). The old
+     * spelling still resolves and warns — the window, and what deliberately did
+     * NOT move, is `utils/ship/flatpak-config.ts`.
+     */
+    flatpak?: ShipFlatpakOptions;
 }
-/** Flatpak-toolchain config for the `gjsify flatpak` subcommand group. */
+/**
+ * The Flatpak knobs `gjsify ship` reads. Every one has a derived default.
+ *
+ * There is no `modules` / `extraModules` here, and that is a decision rather
+ * than an omission: under `ship` the module list IS the staged payload
+ * (`buildsystem: simple` + `cp -a stage/.`), and an escape hatch injecting
+ * arbitrary build modules would put the second staging model back in the tree —
+ * the one thing ADR 0024 § 8 gates the whole migration on. A project that has
+ * to BUILD something inside the sandbox still has `gjsify flatpak init` +
+ * `gjsify flatpak build`, unchanged.
+ */
+export interface ShipFlatpakOptions {
+    /**
+     * Runtime family. Default `'gnome'` — a GJS bundle needs GLib/GObject/GIO at
+     * runtime, and no GJS interpreter ships in the Freedesktop runtime.
+     */
+    runtime?: 'gnome' | 'freedesktop';
+    /** Runtime/SDK version, e.g. `'50'` for GNOME or `'24.08'` for Freedesktop. */
+    runtimeVersion?: string;
+    /**
+     * The branch the app is exported under — the last segment of
+     * `app/<id>/<arch>/<branch>`. Default `'stable'`, which is what Flathub
+     * publishes and what `flatpak install` resolves without being told.
+     */
+    branch?: string;
+    /** Extra SDK extensions, e.g. `['org.freedesktop.Sdk.Extension.llvm17']`. */
+    sdkExtensions?: string[];
+    /**
+     * Path components prepended to `PATH` inside the build sandbox. Derived from
+     * `sdkExtensions` when unset, because an extension whose `bin` is not on
+     * PATH is one the build cannot use.
+     */
+    appendPath?: string[];
+    /** Finish-args (capabilities). Default depends on `kind`: GUI args for an app, none for a CLI. */
+    finishArgs?: string[];
+    /** Cleanup globs applied to `/app`, e.g. `['/include', '/lib/pkgconfig']`. */
+    cleanup?: string[];
+}
+/**
+ * Flatpak-toolchain config for the `gjsify flatpak` subcommand group.
+ *
+ * Six of these keys — `runtime`, `runtimeVersion`, `sdkExtensions`,
+ * `appendPath`, `finishArgs`, `cleanup` — have a second home at
+ * {@link ShipFlatpakOptions}, and `gjsify ship` warns when it reads them from
+ * here (ADR 0024 § 8; the window is `utils/ship/flatpak-config.ts`). They are
+ * NOT marked `@deprecated`: for the subcommands in this group they are still
+ * the only spelling, and those commands have not moved under `ship` yet
+ * (`status/open-todos.md`). Nothing else in this block is deprecated at all —
+ * the {@link AppMetadata} half is a designed alias, not a legacy one.
+ */
 export interface ConfigDataFlatpak extends AppMetadata {
     /** Reverse-DNS app id, e.g. `eu.jumplink.Learn6502`. Defaults to `package.json#name` if it looks like a reverse-DNS id. */
     appId?: string;