@gjsify/cli 0.43.0 → 0.45.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/gettext.d.ts

@@ -1,10 +1,11 @@
 import type { Command } from '../types/index.js';
-type GettextFormat = 'mo' | 'xml' | 'desktop' | 'json';
+type GettextFormat = 'mo' | 'xml' | 'desktop';
 interface GettextOptions {
     poDir: string;
     outDir: string;
     domain: string;
     format?: GettextFormat;
+    template?: string;
     metainfo?: string;
     filename?: string;
     removeXmlComments?: boolean;

package/lib/commands/gettext.js

@@ -1,7 +1,9 @@
 import { execFile } from 'node:child_process';
-import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import { basename, join, resolve } from 'node:path';
 import { promisify } from 'node:util';
+import { mergeCatalogues } from '../utils/msgfmt-merge.js';
 const execFileAsync = promisify(execFile);
 async function listLanguages(poDir) {
     const entries = await readdir(poDir);
@@ -25,40 +27,79 @@ async function fileExists(path) {
         return false;
     }
 }
-async function compileBulkXml(opts) {
+/**
+ * Fold every catalogue into ONE template.
+ *
+ * The chain, and the four measured msgfmt constraints that shape it, live in
+ * `utils/msgfmt-merge.ts` — `gjsify ship` folds the catalogues it stages into the
+ * metadata it generates through the same function, and a second copy of those
+ * constraints here would be the copy that drifts.
+ *
+ * What is local to this command: the output keeps the CALLER's `--filename`,
+ * while every INTERMEDIATE is named after the TEMPLATE. Those have to be two
+ * different names, because msgfmt finds its ITS rules by filename pattern
+ * (constraint 4 over there) and from the second catalogue on the intermediates
+ * ARE templates. Named after `--filename` instead, the command's answer depended
+ * on how many catalogues there were: measured, `--format xml --template
+ * app.metainfo.xml.in --filename out.xml` wrote a translated file for a one-language
+ * `po/` and died on a two-language one with `cannot locate ITS rules for
+ * <tmpdir>/0-out.xml` — naming an internal path over a rule the user could act on.
+ * The template's suffix is what msgfmt validated for call 1, so it is the one
+ * suffix known to work for calls 2..n.
+ */
+async function compileMerged(opts) {
+    const languages = await listLanguages(opts.poDir);
+    if (languages.length === 0) {
+        console.warn(`[gjsify gettext] no .po files found in ${opts.poDir}`);
+        return;
+    }
     const outputFile = join(opts.outDir, opts.filename);
     await ensureDir(opts.outDir);
-    const args = [`--output-file=${outputFile}`, '--xml', `--template=${opts.template}`, '-d', opts.poDir];
-    if (opts.verbose) {
-        console.log(`[gjsify gettext] msgfmt ${args.join(' ')}`);
+    const workDir = await mkdtemp(join(tmpdir(), 'gjsify-gettext-'));
+    try {
+        const merged = await readFile(mergeCatalogues({
+            mode: `--${opts.format}`,
+            template: opts.template,
+            // The TEMPLATE's name, minus the `.in` convention — see the header.
+            // `basename`, so an intermediate stays inside `workDir` rather than
+            // following the directory part of the path the user passed.
+            extension: `-${basename(opts.template).replace(/\.in$/, '')}`,
+            catalogues: languages.map((lang) => ({ locale: lang, po: join(opts.poDir, `${lang}.po`) })),
+            workDir,
+            onCall: opts.verbose ? (args) => console.log(`[gjsify gettext] msgfmt ${args.join(' ')}`) : undefined,
+        }), 'utf-8');
+        await writeFile(outputFile, opts.removeXmlComments && opts.format === 'xml' ? stripXmlComments(merged) : merged);
     }
-    await execFileAsync('msgfmt', args);
-    if (opts.removeXmlComments) {
-        const content = await readFile(outputFile, 'utf-8');
-        await writeFile(outputFile, stripXmlComments(content));
+    finally {
+        await rm(workDir, { recursive: true, force: true });
     }
     if (opts.verbose) {
-        console.log(`[gjsify gettext] wrote ${outputFile}`);
+        console.log(`[gjsify gettext] merged ${languages.length} language(s) into ${outputFile}`);
     }
 }
-async function compilePerLanguage(opts) {
+/**
+ * Compile each `<lang>.po` into `<outDir>/<lang>/LC_MESSAGES/<filename>`.
+ *
+ * `mo` only. The other two formats SUBSTITUTE a template rather than producing a
+ * catalogue, and there is no per-language file for them to write — which is the
+ * defect this signature now makes unrepresentable: the old shared loop passed
+ * `--desktop`/`--xml` with no `--template`, and msgfmt refuses that outright
+ * (`--desktop requires a "--template template" specification`, exit 1). Every
+ * `gjsify gettext --format=desktop` invocation had therefore always failed; the
+ * only e2e coverage passes `--format mo`, so nothing ever ran the other branch.
+ */
+async function compileCatalogues(opts) {
     const languages = await listLanguages(opts.poDir);
     if (languages.length === 0) {
         console.warn(`[gjsify gettext] no .po files found in ${opts.poDir}`);
         return;
     }
     for (const lang of languages) {
-        const poFile = join(opts.poDir, `${lang}.po`);
-        const langDir = opts.format === 'mo' ? join(opts.outDir, lang, 'LC_MESSAGES') : join(opts.outDir, lang);
+        const langDir = join(opts.outDir, lang, 'LC_MESSAGES');
         await ensureDir(langDir);
-        const outputFile = join(langDir, opts.filename);
-        // msgfmt produces the binary .mo format by default — there is no
-        // `--mo` flag (only --xml, --desktop, --properties-output, ...).
-        const args = [`--output-file=${outputFile}`];
-        if (opts.format !== 'mo') {
-            args.push(`--${opts.format}`);
-        }
-        args.push(poFile);
+        // msgfmt produces the binary .mo format by default — there is no `--mo`
+        // flag (only --xml, --desktop, --properties-output, ...).
+        const args = [`--output-file=${join(langDir, opts.filename)}`, join(opts.poDir, `${lang}.po`)];
         if (opts.verbose) {
             console.log(`[gjsify gettext] msgfmt ${args.join(' ')}`);
         }
@@ -68,24 +109,22 @@ async function compilePerLanguage(opts) {
         console.log(`[gjsify gettext] compiled ${languages.length} language(s) into ${opts.outDir}`);
     }
 }
-function defaultFilename(domain, format, metainfoTemplate) {
+function defaultFilename(domain, format, template) {
     switch (format) {
         case 'mo':
             return `${domain}.mo`;
-        case 'json':
-            return `${domain}.json`;
         case 'desktop':
             return `${domain}.desktop`;
         case 'xml': {
             // Mirror the template filename but without the trailing `.in` (convention for
             // pre-processed metainfo templates: `org.foo.Bar.metainfo.xml.in`).
-            if (metainfoTemplate) {
+            if (template) {
                 // `basename`, not a hand-rolled `lastIndexOf('/')`: this is a path the USER
                 // passed, and on win32 it separates with `\`, which the slice read as part
                 // of the name (#1143). `node:path` is the right owner for host tooling —
                 // though it only answers correctly under Node until #1146 makes
                 // `@gjsify/path` select win32 per host.
-                return basename(metainfoTemplate.replace(/\.in$/, ''));
+                return basename(template.replace(/\.in$/, ''));
             }
             return `${domain}.xml`;
         }
@@ -93,7 +132,8 @@ function defaultFilename(domain, format, metainfoTemplate) {
 }
 export const gettextCommand = {
     command: 'gettext <poDir> <outDir>',
-    description: 'Compile gettext .po files to .mo (per-language locale tree) or substitute a metainfo template via msgfmt --xml.',
+    description: 'Compile gettext .po files to .mo (per-language locale tree), or merge every catalogue into a ' +
+        '.desktop / AppStream template via msgfmt --desktop / --xml.',
     builder: (yargs) => {
         return yargs
             .positional('poDir', {
@@ -103,7 +143,7 @@ export const gettextCommand = {
             demandOption: true,
         })
             .positional('outDir', {
-            description: 'Output directory (locale tree for --format=mo, plain dir for xml/desktop/json)',
+            description: 'Output directory (locale tree for --format=mo, plain dir for xml/desktop)',
             type: 'string',
             normalize: true,
             demandOption: true,
@@ -117,13 +157,21 @@ export const gettextCommand = {
             .option('format', {
             description: 'Output format',
             type: 'string',
-            choices: ['mo', 'xml', 'desktop', 'json'],
+            choices: ['mo', 'xml', 'desktop'],
             default: 'mo',
+        })
+            .option('template', {
+            description: 'Required for --format=xml|desktop: the file msgfmt substitutes into. Its SUFFIX matters — ' +
+                'msgfmt --xml finds its ITS rules by filename pattern, so an AppStream template must be ' +
+                'named `*.metainfo.xml[.in]`.',
+            type: 'string',
+            normalize: true,
         })
             .option('metainfo', {
-            description: 'For --format=xml: path to the template (`.metainfo.xml.in`) used as msgfmt --template',
+            description: 'Deprecated alias for --template.',
             type: 'string',
             normalize: true,
+            hidden: true,
         })
             .option('filename', {
             description: 'Override the output filename (defaults to <domain>.<ext>)',
@@ -146,8 +194,12 @@ export const gettextCommand = {
         const outDir = resolve(args.outDir);
         const domain = args.domain;
         const format = args.format ?? 'mo';
-        const metainfo = args.metainfo ? resolve(args.metainfo) : undefined;
-        const filename = args.filename ?? defaultFilename(domain, format, metainfo);
+        // `--metainfo` predates the option being useful for `.desktop` too. Kept as a
+        // hidden alias rather than removed: it is the spelling `cli-reference.md`
+        // documented, so removing it would break the invocation the docs taught.
+        const templateArg = args.template ?? args.metainfo;
+        const template = templateArg ? resolve(templateArg) : undefined;
+        const filename = args.filename ?? defaultFilename(domain, format, template);
         const verbose = !!args.verbose;
         const removeXmlComments = !!args['remove-xml-comments'];
         if (!(await fileExists(poDir))) {
@@ -155,28 +207,34 @@ export const gettextCommand = {
             process.exitCode = 1;
             return;
         }
+        // REFUSED, not worked around. `--xml` and `--desktop` substitute into a
+        // template, and msgfmt rejects both without one (`--desktop requires a
+        // "--template template" specification`, exit 1). The old code fell back to a
+        // per-language loop that passed no template at all, so the fallback could only
+        // ever reproduce that same error one layer further down — with the user's
+        // `--format` reported as the thing that failed rather than the missing template.
+        if (format !== 'mo' && template === undefined) {
+            console.error(`[gjsify gettext] --format=${format} needs a template to substitute into: pass ` +
+                '`--template <file>`. msgfmt has no way to produce this format from .po files alone.' +
+                (format === 'xml'
+                    ? ' Name it `*.metainfo.xml[.in]` — msgfmt --xml finds its ITS rules by filename pattern.'
+                    : ''));
+            process.exitCode = 1;
+            return;
+        }
         try {
-            if (format === 'xml' && metainfo) {
-                await compileBulkXml({
-                    poDir,
-                    outDir,
-                    domain,
-                    template: metainfo,
-                    filename,
-                    removeXmlComments,
-                    verbose,
-                });
+            if (format === 'mo') {
+                await compileCatalogues({ poDir, outDir, filename, verbose });
             }
             else {
-                if (format === 'xml') {
-                    console.warn('[gjsify gettext] --format=xml without --metainfo: falling back to per-language XML files');
-                }
-                await compilePerLanguage({
+                await compileMerged({
                     poDir,
                     outDir,
-                    domain,
                     format,
+                    // Narrowed by the refusal above.
+                    template: template,
                     filename,
+                    removeXmlComments,
                     verbose,
                 });
             }

package/lib/commands/onboard.d.ts

@@ -6,6 +6,13 @@ interface OnboardOptions {
     registry?: string;
     otp?: string;
     concurrency: number;
+    'write-concurrency': number;
+    packages?: string[];
+    include?: string[];
+    exclude?: string[];
+    access: string;
+    build: boolean;
+    verbose?: boolean;
     'dry-run'?: boolean;
     json?: boolean;
     yes?: boolean;