@gjsify/cli 0.42.0 → 0.44.0

package/lib/commands/ship.js

@@ -5,12 +5,23 @@
 // thin on purpose: every decision worth testing lives in `utils/ship/*` as a
 // pure function, and what is left here is filesystem work and printing.
 //
+// TWO PHASES, one verb each (ADR 0024 § A2). Phase one ASSEMBLES: it resolves
+// the settings, plans the payload, writes `stage/`, and writes the closure that
+// makes that tree packable somewhere else (`.gjsify-ship-stage.json`, see
+// `utils/ship/stage-manifest.ts`). Phase two FINISHES: `--from-stage <dir>`
+// packs a stage that arrived from another host, with no project, no config and
+// no built bundle in reach. With neither flag both phases run in one process,
+// which is what a developer on one machine wants and what the e2e suite
+// compares the split against byte for byte.
+//
 // Scope today is Linux and `--app gjs`: no runtime is bundled, because GJS and
 // GTK come from the distribution and shipping ~100 MiB of them would be cargo
 // cult (ADR 0024 § 4). macOS and Windows layouts, and Flatpak as a target under
-// this command, are the later stages of the same ADR.
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { basename, join, relative, resolve } from 'node:path';
+// 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, 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';
 import { readPackageJson } from '../utils/pkg-json.js';
@@ -18,23 +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 } from '../utils/ship/payload.js';
-import { planOverlay, planStage } from '../utils/ship/plan.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, 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',
@@ -45,6 +64,17 @@ export const shipCommand = {
         type: 'boolean',
         default: false,
         description: 'Produce the staged payload and stop, without packing anything.',
+    })
+        .option('from-stage', {
+        type: 'string',
+        normalize: true,
+        description: 'Pack a staged payload written by an earlier `--stage` run. Needs no project: the stage ' +
+            'carries its own closure.',
+    })
+        .option('expect-target', {
+        type: 'string',
+        description: 'With --from-stage: refuse unless the stage was assembled for this `<os>-<arch>`, e.g. ' +
+            '`linux-arm64`.',
     })
         .option('skip-build', {
         type: 'boolean',
@@ -58,116 +88,336 @@ 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) => {
-        const projectDir = process.cwd();
-        const config = new Config();
-        // No `.catch(() => ({}))` here, unlike the flatpak commands: a config
-        // file that fails to load would silently become "no config", and the
-        // result is a shipped artifact carrying default metadata the author
-        // never chose. An unreadable config is an error worth printing.
-        const configData = await config.forCommand(projectDir);
-        const ship = configData.ship ?? {};
-        const flatpak = configData.flatpak ?? {};
-        assertShippableTarget(configData.app);
-        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);
-        if (!args['skip-build'])
-            await runProjectBuild(projectDir);
-        const discovered = discoverPayload({
-            projectDir,
-            pkg,
-            ship,
-            flatpakIcon: flatpak.icon,
-            declaredBundle: declaredBundlePath(pkg, ship),
-        });
-        const { settings, metadata, warnings } = resolveShipSettings({
-            projectDir,
-            pkg,
-            ship,
-            flatpak,
-            cli: { outDir: args.out, arch: args.arch },
-            discovered,
+        // The two phases share nothing but `packOne`, and the branch is first
+        // so that `--from-stage` never touches the cwd: a finishing host has no
+        // project there, and reading one would make the artifact depend on
+        // whatever directory the job happened to start in.
+        if (args['from-stage'] !== undefined)
+            return await finishFromStage(args, args['from-stage']);
+        await assemble(args);
+    },
+};
+/**
+ * Phase one: resolve, plan, stage, and write the closure — then, unless
+ * `--stage` was passed, pack right here.
+ */
+async function assemble(args) {
+    const projectDir = process.cwd();
+    const config = new Config();
+    // No `.catch(() => ({}))` here, unlike the flatpak commands: a config
+    // file that fails to load would silently become "no config", and the
+    // result is a shipped artifact carrying default metadata the author
+    // never chose. An unreadable config is an error worth printing.
+    const configData = await config.forCommand(projectDir);
+    const ship = configData.ship ?? {};
+    const flatpak = configData.flatpak ?? {};
+    assertShippableTarget(configData.app);
+    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 ?? 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({
+        projectDir,
+        pkg,
+        ship,
+        flatpakIcon: flatpak.icon,
+        declaredBundle: declaredBundlePath(pkg, ship),
+    });
+    const { settings, metadata, warnings } = resolveShipSettings({
+        projectDir,
+        pkg,
+        ship,
+        flatpak,
+        cli: { outDir: args.out, arch: args.arch },
+        discovered,
+    });
+    for (const warning of warnings)
+        console.warn(`${LOG} ${warning}`);
+    const mtime = buildTimestamp(settings.bundlePath);
+    const metadataInputs = {
+        appId: settings.appId,
+        name: settings.name,
+        command: settings.binaryName,
+        kind: settings.kind,
+        metadata,
+        configKey: 'gjsify.ship',
+        copyrightYear: new Date(mtime * 1000).getUTCFullYear(),
+    };
+    // Warn rather than fail: an incomplete AppStream component still
+    // installs and still runs. It is app STORES that will reject it, and
+    // that is a different day's problem than getting the package built.
+    for (const missing of validateAppMetadata(metadataInputs)) {
+        console.warn(`${LOG} ${missing.field} is not set — ${missing.hint}`);
+    }
+    // Printed, not assumed. The text may come from an ancestor — one `LICENSE`
+    // at a monorepo root covers every package under it (see `discoverLicense`)
+    // — and which file was baked into the copyright is not recoverable from the
+    // artifact afterwards without unpacking it.
+    if (settings.licenseFile !== undefined && dirname(settings.licenseFile) !== projectDir) {
+        console.log(`${LOG} licence text from ${relative(projectDir, settings.licenseFile)} ` +
+            '(this package carries none of its own)');
+    }
+    const stageInputs = {
+        bundleFiles: discovered.bundleFiles,
+        launcher: renderLauncher(settings, basename(settings.bundlePath)),
+        metainfo: settings.kind === 'app' ? renderMetainfoApp(metadataInputs) : renderMetainfoCli(metadataInputs),
+        desktopEntry: settings.kind === 'app' ? renderDesktopEntry(metadataInputs) : undefined,
+        licenseText: settings.licenseFile === undefined ? undefined : readFileSync(settings.licenseFile, 'utf-8'),
+    };
+    const outRoot = resolve(projectDir, settings.outDir);
+    const stageDir = join(outRoot, 'stage');
+    const staged = planStage(settings, stageInputs);
+    writeStage(stageDir, staged);
+    console.log(`${LOG} staged ${staged.length} file(s) in ${relative(projectDir, stageDir)}/`);
+    if (args.verbose)
+        for (const file of staged)
+            console.log(`${LOG}   ${file.path}`);
+    // Scanned from the BUILD TREE's bundle, which is why it has to be recorded:
+    // `gi://` specifiers are what the emitted `Depends:` is derived from
+    // (ADR 0024 § 6), and the packing host has the staged copy but no way to
+    // tell which staged file is the entry.
+    const namespaces = scanGiNamespaces(readFileSync(settings.bundlePath, 'utf-8'));
+    if (args.verbose)
+        console.log(`${LOG} gi namespaces: ${namespaces.join(', ') || '(none)'}`);
+    const overlay = new Map();
+    for (const format of formats)
+        overlay.set(format.id, planOverlay(settings, format, stageInputs));
+    // The dependency derivation runs HERE as well, and its result is thrown
+    // away. It is the only check in the pipeline that can refuse a project
+    // (`gi://Nautilus` with no known package, ADR 0024 § 6), and this is the
+    // host that has the `package.json` the refusal tells you to edit — letting
+    // it fire two jobs later, on a machine with no project, would name a fix
+    // nobody there can apply. Facts come from the PLAN, which has the same
+    // paths the payload will have.
+    const facts = readPayloadFacts(staged);
+    for (const format of formats) {
+        // `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.depends],
+            typelibPackages: settings.typelibPackages,
+            bundledTypelibs: facts.bundledTypelibs,
+            minGjsVersion: settings.minGjsVersion,
         });
-        for (const warning of warnings)
+        for (const warning of warnAboutGjsFloor(format.depends, settings.minGjsVersion)) {
             console.warn(`${LOG} ${warning}`);
-        const mtime = buildTimestamp(settings.bundlePath);
-        const metadataInputs = {
-            appId: settings.appId,
-            name: settings.name,
-            command: settings.binaryName,
-            kind: settings.kind,
-            metadata,
-            configKey: 'gjsify.ship',
-            copyrightYear: new Date(mtime * 1000).getUTCFullYear(),
-        };
-        // Warn rather than fail: an incomplete AppStream component still
-        // installs and still runs. It is app STORES that will reject it, and
-        // that is a different day's problem than getting the package built.
-        for (const missing of validateAppMetadata(metadataInputs)) {
-            console.warn(`${LOG} ${missing.field} is not set — ${missing.hint}`);
-        }
-        const stageInputs = {
-            bundleFiles: discovered.bundleFiles,
-            launcher: renderLauncher(settings, basename(settings.bundlePath)),
-            metainfo: settings.kind === 'app' ? renderMetainfoApp(metadataInputs) : renderMetainfoCli(metadataInputs),
-            desktopEntry: settings.kind === 'app' ? renderDesktopEntry(metadataInputs) : undefined,
-            licenseText: settings.licenseFile === undefined ? undefined : readFileSync(settings.licenseFile, 'utf-8'),
-        };
-        const outRoot = resolve(projectDir, settings.outDir);
-        const stageDir = join(outRoot, 'stage');
-        const staged = planStage(settings, stageInputs);
-        writeStage(stageDir, staged);
-        console.log(`${LOG} staged ${staged.length} file(s) in ${relative(projectDir, stageDir)}/`);
-        if (args.verbose)
-            for (const file of staged)
-                console.log(`${LOG}   ${file.path}`);
-        if (args.stage)
-            return;
-        const namespaces = scanGiNamespaces(readFileSync(settings.bundlePath, 'utf-8'));
-        if (args.verbose)
-            console.log(`${LOG} gi namespaces: ${namespaces.join(', ') || '(none)'}`);
-        const artifacts = [];
-        for (const format of formats) {
-            artifacts.push(await packOne({ format, settings, stageInputs, staged, stageDir, outRoot, namespaces, mtime }));
         }
-        for (const artifact of artifacts) {
-            console.log(`${LOG} ${artifact.format}: ${relative(projectDir, artifact.path)} (${artifact.size} bytes)`);
+    }
+    // Written unconditionally, not only under `--stage`: a `ship/stage/` that
+    // is sometimes packable elsewhere and sometimes not is a worse contract
+    // than one that always is, and it is what lets the e2e suite compare the
+    // one-process artifact with the two-phase one.
+    const manifest = writeStageManifest({ stageDir, settings, formats, mtime, namespaces, staged, overlay });
+    if (args.stage) {
+        console.log(`${LOG} stage manifest: ${formatTarget(manifest.target)}, formats ${manifest.formats.join(', ')}`);
+        return;
+    }
+    const artifacts = [];
+    for (const format of formats) {
+        artifacts.push(await packOne({
+            format,
+            settings,
+            arch: settings.arch,
+            staged,
+            overlay: overlay.get(format.id) ?? [],
+            stageDir,
+            outRoot,
+            namespaces,
+            mtime,
+            verbose: args.verbose,
+        }));
+    }
+    printArtifacts(projectDir, artifacts);
+}
+/**
+ * Phase two: pack a stage that was assembled somewhere else.
+ *
+ * Everything this needs is in the stage. Nothing under the cwd is read, and
+ * that is the property under test — `tests/e2e/ship-from-stage` deletes the
+ * project tree between the two phases, because without the deletion every
+ * accidental reach-back succeeds and the suite proves nothing.
+ */
+async function finishFromStage(args, fromStage) {
+    if (args.stage) {
+        throw new Error('gjsify ship: --stage and --from-stage are the two halves of one split and cannot run together. ' +
+            '`--stage` assembles a payload and stops; `--from-stage <dir>` packs one that is already ' +
+            'assembled. Run them as two commands, on the host each belongs on (ADR 0024 § A2).');
+    }
+    if (args['skip-build']) {
+        throw new Error('gjsify ship: --from-stage never runs a build — the payload it packs was built and staged by an ' +
+            'earlier run — so --skip-build has nothing to skip. Drop it.');
+    }
+    if (args.arch !== undefined) {
+        throw new Error('gjsify ship: --arch is decided when the stage is assembled, not when it is packed: the launcher, ' +
+            'the payload and the recorded target were all fixed then. Pass --arch to ' +
+            '`gjsify ship --stage`, and use `--expect-target <os>-<arch>` here to assert which leg you are ' +
+            'packing.');
+    }
+    const cwd = process.cwd();
+    const stageDir = resolve(cwd, fromStage);
+    const manifest = readStageManifest(stageDir);
+    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);
+    for (const warning of warnings)
+        console.warn(`${LOG} ${warning}`);
+    console.log(`${LOG} packing ${manifest.settings.binaryName} ${manifest.settings.version}-${manifest.settings.release} ` +
+        `for ${formatTarget(manifest.target)} from ${relative(cwd, stageDir) || '.'}/`);
+    if (args.verbose) {
+        for (const file of manifest.staged)
+            console.log(`${LOG}   ${file.path}`);
+        console.log(`${LOG} gi namespaces: ${manifest.namespaces.join(', ') || '(none)'}`);
+    }
+    // The stage's own directory is not written to — `writeStage` wipes what it
+    // is pointed at, and pointing it at an arriving stage would delete the
+    // payload. The overlay is the only thing this phase materialises, and it
+    // goes beside the artifacts.
+    const outRoot = args.out === undefined ? dirname(stageDir) : resolve(cwd, args.out);
+    const artifacts = [];
+    for (const format of formats) {
+        if (format.depends !== null) {
+            for (const warning of warnAboutGjsFloor(format.depends, manifest.settings.minGjsVersion)) {
+                console.warn(`${LOG} ${warning}`);
+            }
         }
-    },
-};
+        artifacts.push(await packOne({
+            format,
+            settings: manifest.settings,
+            arch: manifest.target.arch,
+            staged: manifest.staged,
+            overlay: overlayFiles(manifest, format.id),
+            stageDir,
+            outRoot,
+            namespaces: manifest.namespaces,
+            mtime,
+            verbose: args.verbose,
+        }));
+    }
+    printArtifacts(cwd, artifacts);
+}
 async function packOne(input) {
     const { format, settings, stageDir, outRoot, mtime } = input;
-    const overlay = planOverlay(settings, format, input.stageInputs);
+    assertOverlayIsLicensed(format.id, settings.binaryName, input.overlay);
     const overlayDir = join(outRoot, 'overlay', format.id);
-    writeStage(overlayDir, overlay);
-    const payload = readStage([stageDir, overlayDir], [...input.staged, ...overlay]);
-    const depends = deriveDepends(format.id, {
-        namespaces: input.namespaces,
-        kind: settings.kind,
-        hasSchemas: settings.schemaFiles.length > 0,
-        extra: settings.extraDepends[format.id],
-        typelibPackages: settings.typelibPackages,
-        bundledTypelibs: settings.typelibFiles,
-        minGjsVersion: settings.minGjsVersion,
-    });
-    for (const warning of warnAboutGjsFloor(format.id, settings.minGjsVersion))
-        console.warn(`${LOG} ${warning}`);
-    // Before the label is chosen, not after: `archName` collapses an
-    // arch-independent payload to `all`/`noarch`, and a mismatch only matters
-    // for a payload that IS architecture-specific.
-    assertPayloadMatchesArch(payload, settings.arch);
-    const archLabel = format.archName(settings.arch, isArchIndependent(payload));
+    writeStage(overlayDir, input.overlay);
+    const payload = readStage([stageDir, overlayDir], [...input.staged, ...input.overlay]);
+    // What the package installs, read off what it installs. The three questions
+    // 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 = 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
+    // header was written from the claim. Read the two bytes further that settle
+    // it before the label reaches a header. Payload-versus-LABEL, never
+    // payload-versus-HOST — a host check would refuse the cross-host pack this
+    // whole split exists for.
+    //
+    // And BEFORE the label is chosen, not after — this ordering is load-bearing:
+    // `archName` collapses an arch-independent payload to `all`/`noarch`, so
+    // asserting afterwards would compare against a label that no longer names an
+    // architecture, and the mismatch that matters is exactly the one on a payload
+    // that IS architecture-specific.
+    assertPayloadMatchesArch(payload, input.arch);
+    const archLabel = format.archName(input.arch, isArchIndependent(payload));
     const common = { settings, payload, prefix: format.prefix, depends, archLabel, mtime };
-    const bytes = format.id === 'deb' ? await buildDeb(common) : await buildRpm(common);
     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 };
+    // 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.
+    //
+    // 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':
+            writeFileSync(target, await buildDeb(common));
+            break;
+        case 'rpm':
+            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)}".`);
+        }
+    }
+    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.
@@ -181,6 +431,10 @@ async function packOne(input) {
  * An undeclared target is the common case for a GJS app and is allowed: `app`
  * otherwise defaults to the HOST runtime, which would refuse a perfectly good
  * GJS project merely for running this command under Node.
+ *
+ * Phase one only, and nothing checks it again in phase two: a stage can only
+ * exist because this passed, and the staged `bin/<name>` carries the
+ * `exec gjs -m` line that proves it.
  */
 function assertShippableTarget(app) {
     if (app === undefined || app === 'gjs')

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