@gjsify/cli 0.43.0 → 0.45.0

package/lib/commands/trust.d.ts

@@ -20,6 +20,12 @@ export interface TrustRequestResult {
     status: number;
     json: unknown;
     text: string;
+    /**
+     * Response headers, so a caller can honour npm's own `Retry-After` on a 429
+     * instead of guessing a backoff. Optional because test doubles construct this
+     * shape by hand and a missing header is a well-defined "it said nothing".
+     */
+    headers?: Headers;
 }
 /** A `(method, url, body?) => TrustRequestResult` function bound to a registry auth + OTP context. */
 export type TrustRequester = (method: string, url: string, body?: unknown) => Promise<TrustRequestResult>;

package/lib/commands/trust.js

@@ -279,7 +279,7 @@ export function createTrustRequester(ctx) {
         catch {
             /* non-JSON body — leave json undefined */
         }
-        return { status: res.status, json, text };
+        return { status: res.status, json, text, headers: res.headers };
     };
 }
 function firstLine(s) {

package/lib/config.js

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

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

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

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

@@ -1,5 +1,5 @@
 import type { RolldownOptions, OutputOptions, RolldownPluginOption } from 'rolldown';
-import type { App } from '@gjsify/rolldown-plugin-gjsify';
+import type { App, SourceDialect } from '@gjsify/rolldown-plugin-gjsify';
 import type { ConfigDataLibrary, ConfigDataTypescript } from './index.js';
 /**
  * Plugin entry resolvable by package name from the project's `node_modules`, so
@@ -82,6 +82,20 @@ export interface ConfigData {
      * working ANSI colors). Default: true.
      */
     consoleShim?: boolean;
+    /**
+     * The dialect the SOURCE is written in (ADR 0032 § 2 + § 8). `'react-native'`
+     * aliases `react-native` onto `@gjsify/react-native` and gates every named
+     * import against the support table at BUILD time. `gjs` and `node` app builds.
+     * Default: unset.
+     *
+     * Opt-in and never inferred from the dependency list: a monorepo with a phone
+     * leg installs the real `react-native` on purpose, and redirecting the
+     * specifier for every build in that tree would change what that leg resolves.
+     *
+     * NOT `gjsify.runtimes['react-native']`, which answers the opposite question —
+     * see the header of `SourceDialect`.
+     */
+    dialect?: SourceDialect;
     /** Comma-separated global identifiers to register. Format: see CliBuildOptions. */
     globals?: string;
     /**
@@ -416,7 +430,15 @@ export interface ConfigDataShip extends AppMetadata {
     release?: string;
     /** `Maintainer:` / `Packager:` as `Name <email>`. Default: `package.json#author`. */
     maintainer?: string;
-    /** Formats to build when `--target` is not given. Default `['deb', 'rpm']`. */
+    /**
+     * Formats to build when `--target` is not given. Default `['deb', 'rpm']`.
+     *
+     * A project-level DEFAULT, so it is filtered to the layout `gjsify ship <os>`
+     * assembles rather than refused against it — a name here that wraps another
+     * OS's layout is dropped, and `gjsify ship` prints which. A `--target` on the
+     * command line is a claim about ONE run and is refused instead. Without that
+     * split, declaring this key made `gjsify ship darwin --stage` impossible.
+     */
     targets?: string[];
     /** Output root, relative to the project. Default `'ship'`. */
     outDir?: string;
@@ -443,6 +465,18 @@ export interface ConfigDataShip extends AppMetadata {
      * start.
      */
     minGjsVersion?: string;
+    /**
+     * Minimum Node major the emitted dependency asks for, when the payload is a
+     * `--app node` bundle. Default `'24'` — the LTS line the
+     * `@gjsify/node-runtime-*` packages bundle for macOS and Windows.
+     *
+     * Lower it only if the bundle genuinely runs on an older Node. The default
+     * excludes every current DEB stable/LTS (trixie 20, Ubuntu 24.04 18, Ubuntu
+     * 26.04 22), so it makes a `.deb` that apt refuses there rather than one that
+     * installs and then dies on the first unsupported syntax — the same trade
+     * `minGjsVersion` makes, and `gjsify ship` warns about it either way.
+     */
+    minNodeVersion?: string;
     /**
      * Runtime dependencies appended to the set derived from the bundle's
      * `gi://` imports — the escape hatch for a namespace the table does not
@@ -496,8 +530,108 @@ export interface ConfigDataShip extends AppMetadata {
     extraFiles?: Record<string, string>;
     /** Arguments the launcher appends before the user's own. */
     execArgs?: string[];
+    /**
+     * How `--target flatpak` builds the app: the runtime it links against and
+     * what the finished app is allowed to do.
+     *
+     * The new home of the `gjsify.flatpak` BUILD keys (ADR 0024 § 8). The old
+     * spelling still resolves and warns — the window, and what deliberately did
+     * NOT move, is `utils/ship/flatpak-config.ts`.
+     */
+    flatpak?: ShipFlatpakOptions;
+    /**
+     * The signing identity this project uses by default, per OS.
+     *
+     * `--sign <identity>` on the command line wins. Absent means unsigned, which
+     * is the default path and a legitimate output (ADR 0024 § A13).
+     */
+    sign?: ShipSignOptions;
+}
+/**
+ * `gjsify.ship.sign` — an IDENTITY per OS, and never a certificate.
+ *
+ * KEYED PER OS, and the two keys must not be one field: a Developer ID string
+ * and an Authenticode subject name live in different namespaces, and the value
+ * that resolves is chosen by the LAYOUT being packed (`FormatDescriptor.layoutOs`
+ * and the stage manifest's `target.os`), not by the host doing the packing
+ * (ADR 0024 § A12).
+ *
+ * `linux` is deliberately absent: a `.deb` and an `.rpm` carry no per-file
+ * signature — the artifact is signed as a whole by the repository that serves
+ * it, with that repository's key. A key here would look like it did something.
+ *
+ * WHAT IS NOT HERE, and each is a decision rather than an omission:
+ *  - a certificate, a `.p12` path or a password. `codesign` and `signtool` are
+ *    handed a NAME and resolve the private key themselves, so `gjsify ship`
+ *    never sees a secret and nothing on this surface has to be redacted from a
+ *    log line (§ A14).
+ *  - an `entitlements` key. § A16 leaves library validation vs. hardened runtime
+ *    explicitly unmeasured, and a config key for an unmeasured mechanism is a
+ *    promise the implementation cannot keep.
+ *  - a notarisation credential. That is a per-RUN account credential, not a
+ *    machine-held identity, and a config key for one is an invitation to commit
+ *    it — `--notarize <keychain-profile>` is the only way to pass it.
+ */
+export interface ShipSignOptions {
+    /** `codesign --sign <identity>`. `'-'` is ad-hoc and needs no developer identity. */
+    darwin?: {
+        identity?: string;
+    };
+    /** `signtool sign /n <identity>` — the certificate's SUBJECT NAME in a Windows store. */
+    win32?: {
+        identity?: string;
+    };
+}
+/**
+ * The Flatpak knobs `gjsify ship` reads. Every one has a derived default.
+ *
+ * There is no `modules` / `extraModules` here, and that is a decision rather
+ * than an omission: under `ship` the module list IS the staged payload
+ * (`buildsystem: simple` + `cp -a stage/.`), and an escape hatch injecting
+ * arbitrary build modules would put the second staging model back in the tree —
+ * the one thing ADR 0024 § 8 gates the whole migration on. A project that has
+ * to BUILD something inside the sandbox still has `gjsify flatpak init` +
+ * `gjsify flatpak build`, unchanged.
+ */
+export interface ShipFlatpakOptions {
+    /**
+     * Runtime family. Default `'gnome'` — a GJS bundle needs GLib/GObject/GIO at
+     * runtime, and no GJS interpreter ships in the Freedesktop runtime.
+     */
+    runtime?: 'gnome' | 'freedesktop';
+    /** Runtime/SDK version, e.g. `'50'` for GNOME or `'24.08'` for Freedesktop. */
+    runtimeVersion?: string;
+    /**
+     * The branch the app is exported under — the last segment of
+     * `app/<id>/<arch>/<branch>`. Default `'stable'`, which is what Flathub
+     * publishes and what `flatpak install` resolves without being told.
+     */
+    branch?: string;
+    /** Extra SDK extensions, e.g. `['org.freedesktop.Sdk.Extension.llvm17']`. */
+    sdkExtensions?: string[];
+    /**
+     * Path components prepended to `PATH` inside the build sandbox. Derived from
+     * `sdkExtensions` when unset, because an extension whose `bin` is not on
+     * PATH is one the build cannot use.
+     */
+    appendPath?: string[];
+    /** Finish-args (capabilities). Default depends on `kind`: GUI args for an app, none for a CLI. */
+    finishArgs?: string[];
+    /** Cleanup globs applied to `/app`, e.g. `['/include', '/lib/pkgconfig']`. */
+    cleanup?: string[];
 }
-/** Flatpak-toolchain config for the `gjsify flatpak` subcommand group. */
+/**
+ * Flatpak-toolchain config for the `gjsify flatpak` subcommand group.
+ *
+ * Six of these keys — `runtime`, `runtimeVersion`, `sdkExtensions`,
+ * `appendPath`, `finishArgs`, `cleanup` — have a second home at
+ * {@link ShipFlatpakOptions}, and `gjsify ship` warns when it reads them from
+ * here (ADR 0024 § 8; the window is `utils/ship/flatpak-config.ts`). They are
+ * NOT marked `@deprecated`: for the subcommands in this group they are still
+ * the only spelling, and those commands have not moved under `ship` yet
+ * (`status/open-todos.md`). Nothing else in this block is deprecated at all —
+ * the {@link AppMetadata} half is a designed alias, not a legacy one.
+ */
 export interface ConfigDataFlatpak extends AppMetadata {
     /** Reverse-DNS app id, e.g. `eu.jumplink.Learn6502`. Defaults to `package.json#name` if it looks like a reverse-DNS id. */
     appId?: string;

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

@@ -0,0 +1,41 @@
+/**
+ * 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[];
+/**
+ * The runtime keys, structurally — not `ConfigDataFlatpak`.
+ *
+ * Two config blocks answer this question now (`gjsify.flatpak` and
+ * `gjsify.ship.flatpak`, § the deprecation window in `utils/ship/flatpak-config.ts`),
+ * and a resolver typed to one of them would have to be duplicated for the other.
+ */
+export interface RuntimeSelection {
+    runtime?: string;
+    runtimeVersion?: string;
+}
+export interface ResolvedRuntime {
+    runtime: 'gnome' | 'freedesktop';
+    runtimeId: string;
+    sdk: string;
+    runtimeVersion: string;
+}
+/**
+ * Pick the runtime + sdk + version triple from config + CLI overrides.
+ * `--runtime` and `--runtime-version` flags win over config values.
+ */
+export declare function resolveRuntime(config: RuntimeSelection | undefined, overrides: RuntimeSelection): ResolvedRuntime;
+/**
+ * `append-path` for the build sandbox, derived from the declared SDK extensions.
+ *
+ * `/app/bin` is appended last so a build command finds the app's own binaries
+ * without knowing where they landed.
+ */
+export declare function deriveAppendPath(sdkExtensions: readonly string[]): string[];

package/lib/utils/flatpak-runtime.js

@@ -0,0 +1,54 @@
+// Which runtime a Flatpak is built against, and what the finished app may do.
+//
+// Lifted out of `commands/flatpak/` when `gjsify ship --target flatpak` became
+// the second caller (ADR 0024 § 8). Same move, same reason, as
+// `utils/app-metadata.ts`: these are facts about the APP, not about whichever
+// command happens to render them, and the second copy is the one that drifts —
+// a `DEFAULT_GNOME_RUNTIME_VERSION` bumped in one place and not the other
+// produces a `ship` Flatpak and a `flatpak init` Flatpak targeting different
+// GNOME releases from the same `package.json`.
+/**
+ * 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 = [];
+/**
+ * Pick the runtime + sdk + version triple from config + CLI overrides.
+ * `--runtime` and `--runtime-version` flags win over config values.
+ */
+export function resolveRuntime(config, overrides) {
+    const runtime = (overrides.runtime ?? config?.runtime ?? 'gnome');
+    if (runtime !== 'gnome' && runtime !== 'freedesktop') {
+        throw new Error(`gjsify flatpak: unknown runtime "${runtime}" (expected "gnome" or "freedesktop")`);
+    }
+    const runtimeVersion = overrides.runtimeVersion ??
+        config?.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 };
+}
+/**
+ * `append-path` for the build sandbox, derived from the declared SDK extensions.
+ *
+ * `/app/bin` is appended last so a build command finds the app's own binaries
+ * without knowing where they landed.
+ */
+export 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;
+}

package/lib/utils/msgfmt-merge.d.ts

@@ -0,0 +1,35 @@
+/** Which of msgfmt's two template writers to run. */
+export type MsgfmtMergeMode = '--desktop' | '--xml';
+/** One catalogue: the language tag msgfmt is TOLD, and the `.po` holding it. */
+export interface MsgfmtCatalogue {
+    /** Passed as `--locale=`. Named explicitly so no `LINGUAS` file is needed — constraint 2. */
+    locale: string;
+    /** Path to a `.po`. msgfmt reads only this format here: a `.mo` gives `syntax error`, exit 1. */
+    po: string;
+}
+export interface MsgfmtMergeOptions {
+    mode: MsgfmtMergeMode;
+    /** The file the FIRST call substitutes into. Every later call substitutes into the previous output. */
+    template: string;
+    /** The suffix every intermediate keeps — load-bearing for `--xml`, see constraint 4. */
+    extension: string;
+    catalogues: readonly MsgfmtCatalogue[];
+    /** A directory this function may fill with intermediates; the caller owns its removal. */
+    workDir: string;
+    /** Called with each msgfmt argv, for `--verbose`. */
+    onCall?: (args: readonly string[]) => void;
+}
+/**
+ * Fold every catalogue into one file, chaining `msgfmt` once per language.
+ *
+ * Returns the PATH of the last file written — the caller decides whether to read
+ * it, post-process it or copy it. With no catalogues that is `template` itself,
+ * so a project with nothing to merge never spawns msgfmt at all.
+ *
+ * `stdio: 'pipe'` so a failure's stderr survives on the thrown error rather than
+ * going to the terminal and leaving the caller with an exit code.
+ *
+ * Throws when two catalogues name the same locale — constraint 5, which msgfmt
+ * itself reports as two successes and one invalid file.
+ */
+export declare function mergeCatalogues(options: MsgfmtMergeOptions): string;

package/lib/utils/msgfmt-merge.js

@@ -0,0 +1,102 @@
+// Merging gettext catalogues INTO a template — the `msgfmt --desktop` / `--xml` half.
+//
+// Two callers need this and they are not variants of each other: `gjsify gettext`
+// substitutes a template a user wrote, `gjsify ship` substitutes metadata it just
+// rendered. What they share is every constraint below, all five measured against
+// GNU gettext 0.26, and each one fails a DIFFERENT way — two of them silently.
+// Written twice, the silent ones are the copies that lose them.
+//
+//  1. `--desktop` and `--xml` REQUIRE `--template`:
+//     `msgfmt: --desktop requires a "--template template" specification`, exit 1.
+//     Neither format can be produced from `.po` files alone, so a caller without a
+//     template has nothing to ask for.
+//
+//  2. The bulk form (`-d <podir>`) fails SILENTLY. With no `LINGUAS` file beside
+//     the `.po` files:
+//         msgfmt --desktop --template=app.desktop.in -d po -o out.desktop
+//         exit 0 · stderr `po/LINGUAS does not exist` · out.desktop UNTRANSLATED
+//     and `desktop-file-validate out.desktop` then exits 0 as well. Exit 0, an
+//     English file and a passing oracle is the worst of the three outcomes, which
+//     is why this module names each language with `--locale=` instead: that form
+//     needs no `LINGUAS` and cannot degrade to a no-op without a non-zero exit.
+//
+//  3. The template and the output must never be the SAME path. msgfmt truncates
+//     `--output-file` before it reads the template, so chaining in place destroys
+//     it: measured, `--desktop` wrote a 0-byte file and exited 0, `--xml` printed
+//     `cannot read <file>: Document is empty` and died on SIGSEGV (exit 139).
+//     Hence the numbered intermediates below rather than one file rewritten.
+//
+//  4. `--xml` finds its ITS rules by FILENAME PATTERN, not by reading the document.
+//     gettext walks `/usr/share/gettext/its/*.loc`, where each rule pairs a glob
+//     with a root element; AppStream's is `pattern="*.metainfo.xml"` +
+//     `localName="component"`, so the same bytes named `foo.xml` die with
+//     `msgfmt: cannot locate ITS rules for foo.xml` (exit 1). `extension` is
+//     therefore part of this function's contract, not a temp-file detail.
+//
+//     Stated as "`--xml` needs a `.metainfo.xml` name" the rule would be wrong in
+//     the direction that matters next: `shared-mime-info.loc` pairs `pattern="*.xml"`
+//     with `localName="mime-info"`, so a MIME package needs no suffix care at all.
+//     The constraint belongs to the AppStream rule, not to `--xml`.
+//
+//  5. A locale may appear at most ONCE in a chain. Two calls naming the same
+//     `--locale` both APPEND — neither replaces the other's key — and the result
+//     is a file BOTH oracles reject, from two exit-0 msgfmt calls:
+//         msgfmt --desktop --template=app.desktop.in --locale=de -o d0 a.po  # 0
+//         msgfmt --desktop --template=d0             --locale=de -o d1 b.po  # 0
+//         desktop-file-validate d1
+//           → error: file contains multiple keys named "Name[de]"            # 1
+//         appstreamcli validate --no-net x1.metainfo.xml   (same shape, --xml)
+//           → E: tag-duplicated name (lang=de) · Validation failed           # 3
+//     So this is worse than constraint 2: not an untranslated file that installs
+//     fine, but an INVALID one, produced without a single non-zero exit. It is
+//     refused here rather than deduplicated here, because the caller holding two
+//     catalogues for one language is the only party that can say which
+//     translation wins — `utils/ship/localize-metadata.ts` answers it with
+//     `msgcat --use-first`.
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+/**
+ * Fold every catalogue into one file, chaining `msgfmt` once per language.
+ *
+ * Returns the PATH of the last file written — the caller decides whether to read
+ * it, post-process it or copy it. With no catalogues that is `template` itself,
+ * so a project with nothing to merge never spawns msgfmt at all.
+ *
+ * `stdio: 'pipe'` so a failure's stderr survives on the thrown error rather than
+ * going to the terminal and leaving the caller with an exit code.
+ *
+ * Throws when two catalogues name the same locale — constraint 5, which msgfmt
+ * itself reports as two successes and one invalid file.
+ */
+export function mergeCatalogues(options) {
+    let current = options.template;
+    // BEFORE the first spawn, so a caller that got this wrong is told rather than
+    // handed a half-written chain to clean up. `seen` is a Set of the locale, not
+    // of the catalogue: the same language reached through two `.po` files is
+    // exactly the case that produces the duplicate key.
+    const seen = new Set();
+    for (const { locale } of options.catalogues) {
+        if (seen.has(locale)) {
+            throw new Error(`mergeCatalogues: two catalogues both claim locale "${locale}". msgfmt APPENDS each ` +
+                `--locale, so the chain would emit a duplicate key (desktop-file-validate: ` +
+                `"multiple keys named Name[${locale}]"; appstreamcli: "tag-duplicated") from two ` +
+                'exit-0 calls. Merge them into one .po first (msgcat --use-first) and pass that.');
+        }
+        seen.add(locale);
+    }
+    for (const [index, catalogue] of options.catalogues.entries()) {
+        const next = join(options.workDir, `${index}${options.extension}`);
+        const args = [
+            options.mode,
+            `--template=${current}`,
+            `--locale=${catalogue.locale}`,
+            `--output-file=${next}`,
+            catalogue.po,
+        ];
+        options.onCall?.(args);
+        execFileSync('msgfmt', args, { stdio: 'pipe' });
+        // Every language after the first merges INTO what the previous one wrote.
+        current = next;
+    }
+    return current;
+}

package/lib/utils/npm-otp.d.ts

@@ -31,6 +31,23 @@ export declare class OtpProvider {
     private cached;
     private readonly promptFn;
     private readonly registry;
+    /**
+     * Bumped every time a NEW code becomes current. Concurrent callers compare the
+     * epoch they last saw against this one to tell "my code was rejected" from
+     * "somebody already replaced it while I was waiting" — the second needs no
+     * prompt, it needs the other one's code.
+     */
+    private generation;
+    /**
+     * The prompt currently on screen, if any. THE fix for a sweep that probes with
+     * concurrency > 1: `promptLine` puts the terminal in RAW mode and echoes each
+     * keystroke by hand (utils/prompt.ts), so two live prompts mean two `data`
+     * listeners on the same stdin and every digit is echoed TWICE. Measured on a
+     * real 703-package sweep at the default concurrency of 4: five prompts stacked
+     * up and the typed code came back as `666644440000999944444444` — four echoes
+     * per keystroke. Whoever arrives second awaits this promise instead.
+     */
+    private pending;
     /**
      * @param seed     Initial cached code (from `--otp`), or undefined.
      * @param promptFn How to read a fresh code. Defaults to the TTY-aware
@@ -41,17 +58,25 @@ export declare class OtpProvider {
     constructor(seed?: string, promptFn?: OtpPromptFn, options?: OtpProviderOptions);
     /** The currently cached OTP code, if any. */
     current(): string | undefined;
+    /**
+     * How many times a new code has become current. Capture it before an attempt
+     * and hand it back to {@link refresh} / {@link invalidate} so a concurrent
+     * caller neither prompts for a code somebody already typed nor throws that
+     * code away on its own stale rejection.
+     */
+    epoch(): number;
     /**
      * Prompt for a fresh code, cache it (in-process + file cache), and return the
      * trimmed input — `''` when nothing was entered, which callers read as "give up".
      */
-    refresh(question?: string): Promise<string>;
+    refresh(question?: string, sinceEpoch?: number): Promise<string>;
+    private promptOnce;
     /**
      * Drop the cached code (in-process AND the cross-invocation file entry) after npm
      * rejects it, so the NEXT command re-prompts instead of replaying a single-use
      * code the registry already burned.
      */
-    invalidate(): void;
+    invalidate(sinceEpoch?: number): void;
 }
 export interface OtpRetryOptions {
     /**