@gjsify/cli 0.42.0 → 0.43.0

package/lib/actions/build.d.ts

@@ -72,6 +72,12 @@ export declare class BuildAction {
      * natively, `@gjsify/rolldown-native` via `synthRolldownOutput`), and it
      * cannot be fooled by a `node:` specifier quoted inside a string, which a
      * text scan cannot tell from a statement.
+     *
+     * The same list also answers the GENERAL form of the question — any bare
+     * specifier GJS cannot resolve, `node:` or not — which is why the target's
+     * externals predicate and the emitted fileNames are handed over: they are
+     * what separates a declared external and a sibling chunk from a dependency
+     * that simply is not there.
      */
     private assertGjsOutputLoadable;
     /**

package/lib/actions/build.js

@@ -1,5 +1,5 @@
 import { runBundle, runWatch, bundleToChunks } from '../bundler-pick.js';
-import { gjsifyPlugin, textLoaderPlugin, resolveShebangLine, NODE_SHEBANG } from '@gjsify/rolldown-plugin-gjsify';
+import { gjsifyPlugin, textLoaderPlugin, resolveShebangLine, NODE_SHEBANG, createGjsExternalsPredicate, globToEntryPoints, } 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';
@@ -10,7 +10,8 @@ import { chmod, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promis
 import { normalizeBundlerOptions, mergeBundlerOptions } from '../utils/normalize-bundler-options.js';
 import { inputSourceDirs, isOutdirInsideSource, libraryOutputLeakError } from '../utils/library-output.js';
 import { detectHtmlEntry, parseHtmlEntry, emitBrowserHtml, htmlOutPathFor } from '../utils/html-entry.js';
-import { assertGjsBundleLoadable } from '../utils/gjs-bundle-guard.js';
+import { assertGjsBundleLoadable, assertGjsBundleParses } from '../utils/gjs-bundle-guard.js';
+import { collectEntryPaths, describeJsxConfig, findJsxEntryPoint, jsxConfigMissingError } from '../utils/jsx-config.js';
 import { giSystemProbes } from '../utils/gi-runtime-paths.js';
 import { escapeRawNulForGjs } from '../utils/gjs-source-escape.js';
 import { assertNodeBundleGlobalsShimmed } from '../utils/node-bundle-guard.js';
@@ -149,6 +150,21 @@ export class BuildAction {
         const multipleBuilds = moduleOutdir && mainOutdir && moduleOutdir !== mainOutdir;
         const pnp = await buildPnpPlugin();
         const pnpPlugins = pnp ? [pnp] : [];
+        // The same chain `buildApp` assembles, and it was missing here entirely:
+        // a library build resolved NO user plugin and NO user text loader, then
+        // emitted the default transform at exit 0. Configuring
+        // `gjsify.bundler.plugins` and watching it do nothing is the repo's most
+        // expensive failure shape, and `@gjsify/gtk-host` itself builds with
+        // `--library` — which is where it was found.
+        const userTextLoader = textLoaderPlugin({ loaders: this.configData.loaders });
+        const userPlugins = userTextLoader ? [userTextLoader] : [];
+        if (userBundler.plugins?.length) {
+            // Under GJS a plugin module cannot always be imported directly — the
+            // native ESM loader does not follow `package.json#exports` — so the
+            // same bundle-then-import escape the app path uses is passed in here.
+            const resolved = await resolveUserPlugins(userBundler.plugins, process.cwd(), isGjs() ? { loadModule: (pth, name) => this.loadPluginViaGjsBundle(pth, name, verbose) } : {});
+            userPlugins.push(...resolved);
+        }
         const results = [];
         if (multipleBuilds) {
             // Both outdirs are derived from module/main — always guard them
@@ -168,6 +184,7 @@ export class BuildAction {
                 output: { dir: moduleOutdir },
                 userAliases: aliases,
                 pnpPlugins,
+                userPlugins,
             }));
             const mainFormat = mainOutdir.includes('/cjs') || mainOutExt === '.cjs' ? 'cjs' : 'esm';
             results.push(await runOneLibraryBuild({
@@ -182,6 +199,7 @@ export class BuildAction {
                 output: { dir: mainOutdir },
                 userAliases: aliases,
                 pnpPlugins,
+                userPlugins,
             }));
         }
         else {
@@ -207,6 +225,7 @@ export class BuildAction {
                 output: { dir: outdir },
                 userAliases: aliases,
                 pnpPlugins,
+                userPlugins,
             }));
         }
         return results;
@@ -375,10 +394,22 @@ export class BuildAction {
      * natively, `@gjsify/rolldown-native` via `synthRolldownOutput`), and it
      * cannot be fooled by a `node:` specifier quoted inside a string, which a
      * text scan cannot tell from a statement.
+     *
+     * The same list also answers the GENERAL form of the question — any bare
+     * specifier GJS cannot resolve, `node:` or not — which is why the target's
+     * externals predicate and the emitted fileNames are handed over: they are
+     * what separates a declared external and a sibling chunk from a dependency
+     * that simply is not there.
      */
-    assertGjsOutputLoadable(result, outfile, outdir) {
+    assertGjsOutputLoadable(result, outfile, outdir, userExternal) {
         const chunks = (result.output ?? []).filter((item) => item.type === 'chunk');
-        assertGjsBundleLoadable(chunks, outfile ?? outdir ?? 'the GJS bundle');
+        assertGjsBundleLoadable(chunks, outfile ?? outdir ?? 'the GJS bundle', {
+            // The target's OWN predicate, not a second list: `externalsPlugin` enforces
+            // this exact one, so a specifier the build let through as external cannot be
+            // reported as unresolvable here.
+            isExternal: createGjsExternalsPredicate(userExternal ?? []),
+            emitted: (result.output ?? []).map((item) => item.fileName),
+        });
     }
     /**
      * Post-bundle gate for `--app node`: throw when the emitted bundle still
@@ -544,6 +575,21 @@ export class BuildAction {
     async buildApp(app = 'gjs', opts = {}) {
         const { verbose, typescript, exclude, library: pkg, aliases, excludeGlobals } = this.configData;
         const userBundler = normalizeBundlerOptions(this.configData);
+        // Refuse a JSX entry with no JSX policy BEFORE bundling anything — see
+        // `utils/jsx-config.ts` for what the unset default emits and why it can never be
+        // right for this target. The glob expansion is paid only on the failing branch:
+        // when JSX is configured there is nothing to name.
+        const jsxPolicy = describeJsxConfig({
+            transformJsx: userBundler.transform?.jsx,
+            tsconfigJsx: typescript?.compilerOptions?.jsx,
+            tsconfigJsxImportSource: typescript?.compilerOptions?.jsxImportSource,
+        });
+        if (app === 'gjs' && !jsxPolicy.configured) {
+            const entries = collectEntryPaths(await globToEntryPoints(userBundler.input, exclude));
+            const jsxEntry = findJsxEntryPoint(entries);
+            if (jsxEntry !== undefined)
+                throw jsxConfigMissingError(jsxEntry);
+        }
         // --- `--app browser` HTML entry (Vite-style) ---
         // When the entry is an `index.html`, bundle the module its
         // `<script type="module" src>` references (rewrite `input` to that
@@ -746,7 +792,7 @@ export class BuildAction {
             // and appended into `userPlugins` above. Re-emitting the raw
             // entries (which may include `BundlerPluginByName` shapes
             // Rolldown doesn't understand) would crash the build.
-            plugins: [...pnpPlugins, ...userPlugins, ...cfg.plugins],
+            plugins: [...pnpPlugins, ...cfg.prePlugins, ...userPlugins, ...cfg.plugins],
         };
         if (opts.watch) {
             await this.runWatchLoop(finalOpts, app, outfile, outdir, verbose);
@@ -762,9 +808,15 @@ export class BuildAction {
         if ((app === 'gjs' || app === 'node') && this.configData.shebang) {
             await this.applyShebang(app, outfile, verbose);
         }
-        // Refuse to hand back a `--app gjs` bundle stock GJS cannot even load.
+        // Refuse to hand back a `--app gjs` bundle stock GJS cannot even load: one that
+        // imports what the runtime cannot resolve, or — when the transform was told to
+        // keep JSX — one that is not parseable JavaScript at all.
         if (app === 'gjs') {
-            this.assertGjsOutputLoadable(writeResult, outfile, outdir);
+            this.assertGjsOutputLoadable(writeResult, outfile, outdir, userExternal);
+            if (jsxPolicy.preserves) {
+                const chunks = (writeResult.output ?? []).filter((item) => item.type === 'chunk');
+                assertGjsBundleParses(chunks, outfile ?? outdir ?? 'the GJS bundle');
+            }
         }
         // Refuse to hand back a `--app node` bundle that reaches for GJS ambient
         // globals nothing seeds. Only meaningful when the shim was NOT injected:
@@ -882,7 +934,11 @@ async function runOneLibraryBuild(args) {
     const merged = mergeBundlerOptions(cfg.options, args.userBundler);
     const finalOpts = {
         ...merged,
-        plugins: [...args.pnpPlugins, ...cfg.plugins],
+        // Same order as the app path: PnP resolves, then the user transforms,
+        // then gjsify's own chain. `merged.plugins` is deliberately NOT spread —
+        // the user's entries arrive RESOLVED, in `userPlugins`, exactly as
+        // `buildApp` passes them.
+        plugins: [...args.pnpPlugins, ...cfg.prePlugins, ...args.userPlugins, ...cfg.plugins],
     };
     return await runBundle(finalOpts);
 }

package/lib/commands/ship.d.ts

@@ -3,6 +3,8 @@ interface ShipOptions {
     target?: string[];
     out?: string;
     stage: boolean;
+    'from-stage'?: string;
+    'expect-target'?: string;
     'skip-build': boolean;
     arch?: string;
     verbose: boolean;

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.
+// 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 { basename, join, relative, resolve } from 'node:path';
+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';
@@ -20,11 +31,12 @@ 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 { 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, } from '../utils/ship/stage-manifest.js';
 import { readStage, writeStage } from '../utils/ship/stage-writer.js';
 const LOG = '[gjsify ship]';
 export const shipCommand = {
@@ -45,6 +57,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',
@@ -61,114 +84,279 @@ export const shipCommand = {
         description: 'Print each staged file and the GI namespaces the bundle imports.',
     }),
     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 ?? 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,
+    });
+    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) {
+        deriveDepends(format.id, {
+            namespaces,
+            hasIcons: facts.hasIcons,
+            hasSchemas: facts.hasSchemas,
+            extra: settings.extraDepends[format.id],
+            typelibPackages: settings.typelibPackages,
+            bundledTypelibs: facts.bundledTypelibs,
+            minGjsVersion: settings.minGjsVersion,
         });
-        for (const warning of warnings)
+        for (const warning of warnAboutGjsFloor(format.id, 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
+    // 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,
+        }));
+    }
+    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 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) {
+        for (const warning of warnAboutGjsFloor(format.id, manifest.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)`);
         }
-    },
-};
+        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,
+        }));
+    }
+    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]);
+    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 = deriveDepends(format.id, {
         namespaces: input.namespaces,
-        kind: settings.kind,
-        hasSchemas: settings.schemaFiles.length > 0,
+        hasIcons: facts.hasIcons,
+        hasSchemas: facts.hasSchemas,
         extra: settings.extraDepends[format.id],
         typelibPackages: settings.typelibPackages,
-        bundledTypelibs: settings.typelibFiles,
+        bundledTypelibs: facts.bundledTypelibs,
         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));
+    // `--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);
+    // 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;
+    switch (format.id) {
+        case 'deb':
+            bytes = await buildDeb(common);
+            break;
+        case 'rpm':
+            bytes = await buildRpm(common);
+            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 };
 }
+function printArtifacts(base, artifacts) {
+    for (const artifact of artifacts) {
+        console.log(`${LOG} ${artifact.format}: ${relative(base, artifact.path)} (${artifact.size} bytes)`);
+    }
+}
 /**
  * Refuse a build target this command cannot package correctly.
  *
@@ -181,6 +369,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/types/config-data.d.ts

@@ -328,6 +328,38 @@ export interface AppMetadata {
      * https://www.freedesktop.org/software/appstream/docs/sect-Metadata-DesktopApps.html#tag-dapp-kudos
      */
     kudos?: string[];
+    /**
+     * File types this package DEFINES for the whole system — a shared-mime-info
+     * document staged into `share/mime/packages/`.
+     *
+     * Distinct from `provides.mimetypes`, which only says the app HANDLES a type.
+     * For a standard type (`text/plain`, `application/pdf`) handling is all you
+     * need: the distribution already defines it. For a type of your own
+     * (`application/x-bauplan`) handling it is not enough and the failure is
+     * silent — nothing on the system knows the type exists, so a `.bauplan` file
+     * is never recognised as one, `MimeType=` in the desktop entry matches
+     * nothing, and double-clicking the file does nothing at all. No error, no
+     * log line: the association simply never fires.
+     *
+     * Every type declared here is added to the handled set automatically, because
+     * defining a file type in your own package and then not opening it is not a
+     * thing anyone means to do.
+     */
+    mimeTypes?: Array<{
+        /** `<media>/<subtype>`, e.g. `application/x-bauplan`. */
+        type: string;
+        /**
+         * What a file manager shows instead of the raw type string. Required:
+         * a type with no comment is listed to the user as `application/x-bauplan`.
+         */
+        comment: string;
+        /** Filename patterns, e.g. `["*.bauplan"]`. */
+        globs?: string[];
+        /** A registered type to inherit from, e.g. `application/zip` for a zip container. */
+        subClassOf?: string;
+        /** Fallback icon name when no type-specific icon is installed. */
+        genericIcon?: string;
+    }>;
     /**
      * What this app provides to the system. `<binary>` is auto-included with the
      * value of `command` when omitted — AppStream needs it to register the binary