@gjsify/cli 0.44.0 → 0.46.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/commands/upgrade.d.ts

@@ -1,3 +1,4 @@
+import { type DependencyGroup } from '../utils/dep-aggregation.js';
 import type { Command } from '../types/index.js';
 interface UpgradeOptions {
     latest?: boolean;
@@ -8,10 +9,32 @@ interface UpgradeOptions {
     excludeWorkspace?: string;
     align?: boolean;
     check?: boolean;
+    exact?: boolean;
     dryRun?: boolean;
     cwd?: string;
     verbose?: boolean;
     yes?: boolean;
 }
 export declare const upgradeCommand: Command<unknown, UpgradeOptions>;
+/**
+ * `--exact` half of the CI gate: does every matched dep carry a bare version?
+ *
+ * Consistency and exactness are different questions, and the first cannot answer the
+ * second: a repository where every manifest agrees on `^4.1.0` is perfectly consistent
+ * and still lets a minor release move a subpath under a lockfile-less install. That is
+ * the hazard ADR 0029 § Risks 1 names for `@girs/*`, whose `./vocabulary` export is what
+ * `@gjsify/gtk-host` consumes — so the pin has to be the whole version, and something
+ * has to say so on every PR.
+ *
+ * Returns the number of offending declarations so the caller can exit once for both arms.
+ */
+export declare function reportInexactRanges(groups: readonly DependencyGroup[]): number;
+/**
+ * The range a dependency will be WRITTEN at.
+ *
+ * Preview and write share this deliberately. They were two expressions for one decision
+ * for exactly one revision, and `--dry-run --exact` announced `^4.3.0` while the writer
+ * would have produced `4.3.0` — a tool describing a change it was not about to make.
+ */
+export declare function targetRange(prefix: string, version: string, exact: boolean): string;
 export {};

package/lib/commands/upgrade.js

@@ -79,6 +79,11 @@ export const upgradeCommand = {
             description: 'CI gate: exit non-zero when any dep is declared inconsistently across workspaces. Implies offline (no registry calls). Pairs with `--align` as the fix.',
             type: 'boolean',
             default: false,
+        })
+            .option('exact', {
+            description: 'Pin without a range operator. When writing, emits `1.2.3` instead of `^1.2.3`; with `--check`, fails on any matched dep that carries one. Pair with `--filter` — a repository-wide exactness check fails on every ordinary caret dep by design.',
+            type: 'boolean',
+            default: false,
         })
             .option('dry-run', {
             description: 'Print the upgrade plan without writing package.json files.',
@@ -118,7 +123,7 @@ export const upgradeCommand = {
         const groups = groupByDependency(decls);
         // --check: exit non-zero if any inconsistency.
         if (args.check) {
-            return runCheckMode(groups);
+            return runCheckMode(groups, args.exact);
         }
         // --align: offline consistency-only, no registry calls.
         if (args.align) {
@@ -163,10 +168,10 @@ export const upgradeCommand = {
         if (args.dryRun) {
             const fileCount = uniqueLocations(selected).length;
             console.log(`[gjsify upgrade] --dry-run: would update ${selected.length} deps across ${fileCount} package.json file(s).`);
-            printChangePlan(selected);
+            printChangePlan(selected, args.exact);
             return;
         }
-        const files = applyToFiles(selected);
+        const files = applyToFiles(selected, args.exact);
         console.log(`✏️  updated ${selected.length} dep(s) across ${files} package.json file(s). Run \`gjsify install\` to apply.`);
     },
 };
@@ -281,10 +286,53 @@ function splitRange(range) {
     return { prefix, version: parsed?.version ?? null };
 }
 // ─── Modes: --check / --align ──────────────────────────────────────────
-function runCheckMode(groups) {
+/**
+ * `--exact` half of the CI gate: does every matched dep carry a bare version?
+ *
+ * Consistency and exactness are different questions, and the first cannot answer the
+ * second: a repository where every manifest agrees on `^4.1.0` is perfectly consistent
+ * and still lets a minor release move a subpath under a lockfile-less install. That is
+ * the hazard ADR 0029 § Risks 1 names for `@girs/*`, whose `./vocabulary` export is what
+ * `@gjsify/gtk-host` consumes — so the pin has to be the whole version, and something
+ * has to say so on every PR.
+ *
+ * Returns the number of offending declarations so the caller can exit once for both arms.
+ */
+export function reportInexactRanges(groups) {
+    const offenders = groups
+        .map((g) => ({ name: g.name, loose: g.occurrences.filter((o) => o.prefix !== '') }))
+        .filter((entry) => entry.loose.length > 0);
+    if (offenders.length === 0)
+        return 0;
+    const total = offenders.reduce((n, entry) => n + entry.loose.length, 0);
+    console.error(`gjsify upgrade --check --exact: FAIL. ${total} declaration(s) across ${offenders.length} dep(s) carry a range operator:\n`);
+    for (const entry of offenders) {
+        const byRange = new Map();
+        for (const occ of entry.loose) {
+            const list = byRange.get(occ.currentRange) ?? [];
+            list.push(occ.workspace);
+            byRange.set(occ.currentRange, list);
+        }
+        console.error(`  ${ANSI.bold}${entry.name}${ANSI.reset}`);
+        for (const [range, holders] of byRange.entries()) {
+            const shown = holders.length > 6 ? `${holders.slice(0, 6).join(', ')} … +${holders.length - 6}` : holders.join(', ');
+            console.error(`    ${range.padEnd(16)} — ${shown}`);
+        }
+    }
+    return total;
+}
+function runCheckMode(groups, exact = false) {
+    const inexact = exact ? reportInexactRanges(groups) : 0;
     const inconsistencies = findInconsistencies(groups);
+    if (inconsistencies.length === 0 && inexact > 0) {
+        console.error(`\nFix: run \`gjsify upgrade --align --exact\` (offline; drops the operator and keeps the version).`);
+        // `return`, not a bare call: under GJS the process does not halt here, and the
+        // consistency report below would run on top of the exactness one.
+        return process.exit(1);
+    }
     if (inconsistencies.length === 0) {
-        console.log(`gjsify upgrade --check: OK. ${groups.length} dep(s) consistently declared across workspaces.`);
+        console.log(`gjsify upgrade --check: OK. ${groups.length} dep(s) consistently declared across workspaces` +
+            (exact ? `, every declaration pinned exactly.` : `.`));
         return;
     }
     console.error(`gjsify upgrade --check: FAIL. ${inconsistencies.length} dep(s) declared at inconsistent ranges:\n`);
@@ -334,13 +382,13 @@ function runAlignMode(groups, args) {
     console.log(`gjsify upgrade --align: aligning ${updates.length} inconsistent dep(s) to their highest declared version:\n`);
     for (const u of updates) {
         const newPrefix = u.occurrences[0]?.prefix ?? '^';
-        console.log(`  ${u.name.padEnd(28)}  ranges: ${[...u.declaredRanges].join(', ')}  →  ${newPrefix}${u.latestVersion}`);
+        console.log(`  ${u.name.padEnd(28)}  ranges: ${[...u.declaredRanges].join(', ')}  →  ${targetRange(newPrefix, u.latestVersion, args.exact ?? false)}`);
     }
     if (args.dryRun) {
         console.log('\n[gjsify upgrade --align] --dry-run: no files changed.');
         return;
     }
-    const files = applyToFiles(updates);
+    const files = applyToFiles(updates, args.exact);
     console.log(`\n✏️  updated ${updates.length} dep(s) across ${files} package.json file(s).`);
 }
 // ─── Registry resolution (group-aware) ─────────────────────────────────
@@ -491,10 +539,10 @@ function renderDeclaredCell(c) {
         return joined;
     return joined.slice(0, 29) + '…';
 }
-function printChangePlan(selected) {
+function printChangePlan(selected, exact = false) {
     for (const u of selected) {
         for (const occ of u.occurrences) {
-            console.log(`  ${occ.workspace.padEnd(38)}  ${u.name.padEnd(28)}  ${occ.currentRange.padEnd(12)} → ${occ.prefix}${u.latestVersion}`);
+            console.log(`  ${occ.workspace.padEnd(38)}  ${u.name.padEnd(28)}  ${occ.currentRange.padEnd(12)} → ${targetRange(occ.prefix, u.latestVersion, exact)}`);
         }
     }
 }
@@ -543,7 +591,17 @@ async function promptSelection(candidates) {
     }
 }
 // ─── Write-back across all affected workspaces ─────────────────────────
-function applyToFiles(updates) {
+/**
+ * The range a dependency will be WRITTEN at.
+ *
+ * Preview and write share this deliberately. They were two expressions for one decision
+ * for exactly one revision, and `--dry-run --exact` announced `^4.3.0` while the writer
+ * would have produced `4.3.0` — a tool describing a change it was not about to make.
+ */
+export function targetRange(prefix, version, exact) {
+    return exact ? version : `${prefix}${version}`;
+}
+function applyToFiles(updates, exact = false) {
     // Group by workspace.location so each package.json is read + written once.
     const byLocation = new Map();
     for (const u of updates) {
@@ -559,25 +617,50 @@ function applyToFiles(updates) {
         const raw = readFileSync(pkgJsonPath, 'utf-8');
         const pkg = JSON.parse(raw);
         let changed = false;
+        const changedNames = [];
         for (const g of groups) {
             const occ = g.occurrences[0];
             const map = pkg[occ.field];
             if (!map)
                 continue;
-            const next = `${occ.prefix}${g.latestVersion}`;
+            const next = targetRange(occ.prefix, g.latestVersion, exact);
             if (map[g.name] !== next) {
                 map[g.name] = next;
                 changed = true;
+                changedNames.push(g.name);
             }
         }
         if (changed) {
             const indent = detectIndent(raw);
-            writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, indent) + (raw.endsWith('\n') ? '\n' : ''), 'utf-8');
+            const rewritten = JSON.stringify(pkg, null, indent) + (raw.endsWith('\n') ? '\n' : '');
+            writeFileSync(pkgJsonPath, keepUntouchedLines(raw, rewritten, changedNames), 'utf-8');
             touched++;
         }
     }
     return touched;
 }
+/**
+ * Take the re-serialised file, but keep every line that is not about a changed dep.
+ *
+ * A `JSON.parse` → `JSON.stringify` round trip rewrites the WHOLE file, and re-encoding
+ * is not identity: measured on this repository, pinning `@girs/*` decoded `\u2014` into
+ * an em dash inside three `description` fields nobody asked to touch, so a dependency
+ * bump arrived as a diff over unrelated prose. Semantically equal, and still noise a
+ * reviewer has to read past.
+ *
+ * Line-for-line only. Adding or removing a key changes the line count, and then the
+ * mapping is not sound — so that case falls back to the plain re-serialisation rather
+ * than guessing an alignment.
+ */
+function keepUntouchedLines(raw, rewritten, changedNames) {
+    const before = raw.split('\n');
+    const after = rewritten.split('\n');
+    if (before.length !== after.length)
+        return rewritten;
+    return after
+        .map((line, i) => (changedNames.some((name) => line.includes(`"${name}"`)) ? line : before[i]))
+        .join('\n');
+}
 function uniqueLocations(updates) {
     const set = new Set();
     for (const u of updates) {

package/lib/templates/install.mjs.tmpl

@@ -18,8 +18,8 @@
  * GJSIFY_INSTALL_BOOTSTRAP_CACHE.
  */
 
-import GLib from 'gi://GLib';
-import Gio from 'gi://Gio';
+import GLib from 'gi://GLib?version=2.0';
+import Gio from 'gi://Gio?version=2.0';
 import system, { exit } from 'system';
 
 /**

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

@@ -430,7 +430,34 @@ 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']`. */
+    /**
+     * The runtime a shipped artifact runs, PER TARGET — `gjsify.app` is the
+     * default and a key here overrides it for one layout.
+     *
+     * KEYED IN THE `process.platform` SPELLING, like {@link ShipSignOptions} and
+     * for the same reason: the value that resolves is chosen by the LAYOUT being
+     * assembled — `FormatDescriptor.layoutOs` and the stage manifest's `target.os`
+     * — never by the host doing the assembling. `macos` and `windows` are the
+     * `gjsify ship <os>` POSITIONAL's spelling, and both `gjsify ship` and
+     * `manifest-conformance`'s `ship` rule refuse them BY NAME, because a runtime
+     * under a key nothing reads is a target that silently keeps the project-wide
+     * answer.
+     *
+     * `resolveShipApp` (`utils/ship/settings.ts`) is the only reader of this key
+     * or of `gjsify.app`, and holds the rest: what one field could not answer,
+     * the measurement behind it, and why an absent key means `gjsify.app` and
+     * never `Layout.shippedRuntime`.
+     */
+    app?: ShipAppOptions;
+    /**
+     * 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;
@@ -457,6 +484,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
@@ -506,6 +545,30 @@ export interface ConfigDataShip extends AppMetadata {
      * produces a package that installs its translations and shows none of them.
      */
     localeDir?: string;
+    /**
+     * A font file, or a directory of them, the application SHIPS (ADR 0038).
+     * Default: `data/fonts` when it exists.
+     *
+     * Staged into `share/fonts/<appId>/`, which is where fontconfig looks: under a
+     * `/usr` prefix through the stock `fonts.conf`'s unconditional
+     * `<dir>/usr/share/fonts</dir>`, and under every other prefix through
+     * `<dir prefix="xdg">fonts</dir>` plus the `XDG_DATA_DIRS` the launcher already
+     * exports. The app names the FAMILY in its styles and needs no install-layout
+     * knowledge, exactly as it needs none for icons or schemas.
+     *
+     * This is what a branded application needs: on a GNOME host the family is
+     * usually installed anyway, and on macOS, on Windows and on any Linux that is
+     * not GNOME it is not — so without shipping it Pango silently substitutes a
+     * fallback and the app merely looks wrong, at exit 0.
+     *
+     * `.woff` / `.woff2` / `.eot` are REFUSED. Whether FreeType opens a web-font
+     * wrapper is a BUILD option of the FreeType the app runs against (brotli for
+     * woff2, zlib for woff), so it is a property of the host's or the bundle's
+     * closure rather than of the file — and a font that resolves on the developer's
+     * box and not in the shipped bundle is the exact silent substitution this key
+     * exists to prevent. Ship the desktop face.
+     */
+    fonts?: string;
     /** Extra payload entries: prefix-relative destination → project-relative source. */
     extraFiles?: Record<string, string>;
     /** Arguments the launcher appends before the user's own. */
@@ -519,6 +582,69 @@ export interface ConfigDataShip extends AppMetadata {
      * 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.app` — the shipped runtime per OS, overriding `gjsify.app`.
+ *
+ * All three keys are present, which is where this differs from
+ * {@link ShipSignOptions}: `linux` is absent there because a `.deb` carries no
+ * per-file signature, while a Linux artifact very much has a runtime — it is the
+ * one that emits `Depends: gjs (>= 1.86)` or `Depends: nodejs (>= 24)`, and the
+ * whole point of this table is that stating darwin's answer must not move it.
+ *
+ * Only `gjs` and `node` are shippable. `browser` has no process to launch and
+ * `nativescript` ships as an APK/IPA through another pipeline (ADR 0024 § 4), so
+ * either one is refused here exactly as it is on `gjsify.app`.
+ */
+export interface ShipAppOptions {
+    /** What a `.deb`/`.rpm`/Flatpak depends on and what its launcher execs. */
+    linux?: 'gjs' | 'node';
+    /** What a `<App>.app` carries. `node` is the only value the macOS formats accept. */
+    darwin?: 'gjs' | 'node';
+    /** What a Windows program directory carries. `node` is the only value its formats accept. */
+    win32?: 'gjs' | 'node';
+}
+/**
+ * `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.

package/lib/utils/gi-search-path.js

@@ -36,9 +36,17 @@ import { detectNativePackages } from './detect-native-packages.js';
  *
  * `globalThis.imports?.gi` is both the sanctioned GJS probe spelling
  * (`.oxlintrc.json`) and the correct CONDITION, so no `isGjs()` beside it: the
- * question is "is there a GIRepository to prepend to", and a Node host answers
- * no by itself — the required no-op, since on Node the CLI uses the npm
- * `rolldown` crate and never wants a prebuild.
+ * question is "is there a GIRepository to prepend to", and a plain Node process has
+ * none — nothing here to write to, which is the required no-op.
+ *
+ * NOT because a Node host wants no prebuild. That justification stood here and is
+ * false exactly where it matters: on darwin `@gjsify/webkit-native`'s prebuild is
+ * the ONLY WebKit any host has (ADR 0022), and ADR 0024 § 4 puts macOS and Windows
+ * applications on Node + node-gi. What is true is narrower — the CLI on Node uses
+ * the npm `rolldown` crate — and generalising it to "a Node host never wants a
+ * prebuild" is what kept every OTHER Node prebuild env-bound until
+ * `@gjsify/node-gi`'s `native-prebuilds.js` (ADR 0021 § The Node host). The Node
+ * host is covered THERE, in the package that owns a GIRepository, not here.
  *
  * `dup_default()` is GLib >= 2.86, probed as a capability rather than caught:
  * an older GLib simply keeps today's behaviour (the launcher's environment, or

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 {
     /**