@gjsify/cli 0.41.0 → 0.43.0

package/lib/utils/run-node.d.ts

@@ -1,4 +1,5 @@
 import { type ExampleRuntime } from './runtimes.js';
+import { type SpawnCompletionContract } from './spawn.js';
 /**
  * Walk up from `startDir` for `<node_modules>/@gjsify/node-gi`, returning its package directory
  * or null. A plain fs walk because Node's own resolver is not available under the GJS-bundled CLI.
@@ -19,6 +20,8 @@ export declare function resolveNodeGiForBundle(bundlePath: string, cwd: string):
 /** Pick the node executable: the current one when on Node, else PATH `node`. */
 export declare function nodeBinary(): string;
 export interface RunNodeBundleOptions {
+    /** The caller's teardown contract — see `RunGjsBundleOptions.completion`. */
+    completion: SpawnCompletionContract;
     /** Exit this process with code 0 once the child succeeds (terminal callers). */
     exitOnSuccess?: boolean;
     /** Suppress the `$ <env> node …` echo — see `RunGjsBundleOptions.quiet`. */
@@ -28,12 +31,14 @@ export interface RunNodeBundleOptions {
  * Run a `--app node` bundle on Node.js with the native typelib env set (same detection as
  * {@link runGjsBundle}). Throws when `@gjsify/node-gi` is not resolvable.
  */
-export declare function runNodeBundle(bundlePath: string, extraArgs?: string[], options?: RunNodeBundleOptions): Promise<void>;
+export declare function runNodeBundle(bundlePath: string, extraArgs: string[] | undefined, options: RunNodeBundleOptions): Promise<void>;
 /**
  * Whether a `--app node` bundle actually consumes `@gjsify/node-gi` — kept EXTERNAL, so a bundle
  * using gi:// imports the shim by name. A plain Node app does NOT, and must run on node/bun/deno
- * WITHOUT node-gi installed, which is why the check is conditional here and not unconditional
- * like the storybook path.
+ * WITHOUT node-gi installed, which is why the check is conditional rather than a flat "this is a
+ * node bundle, demand node-gi". The supervised launcher (`utils/watch-loop.ts`) asks the same
+ * question for the same reason: `gjsify dev` on a web-server template builds a node bundle that
+ * never reaches a typelib.
  */
 export declare function bundleRequiresNodeGi(bundlePath: string): boolean;
 /**
@@ -44,4 +49,4 @@ export declare function bundleRequiresNodeGi(bundlePath: string): boolean;
  *
  * `gjs` is intentionally NOT handled here — the caller dispatches it to {@link runGjsBundle}.
  */
-export declare function runRuntimeBundle(runtime: Exclude<ExampleRuntime, 'gjs'>, bundlePath: string, extraArgs?: string[], options?: RunNodeBundleOptions): Promise<void>;
+export declare function runRuntimeBundle(runtime: Exclude<ExampleRuntime, 'gjs'>, bundlePath: string, extraArgs: string[] | undefined, options: RunNodeBundleOptions): Promise<void>;

package/lib/utils/run-node.js

@@ -15,12 +15,12 @@
 //
 // The node binary is `process.execPath` when the CLI runs under Node, else PATH `node` — under
 // the GJS bundle `process.execPath` is `gjs`, which cannot run a `--app node` bundle.
-import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { computeNativeEnvForBundle } from './run-gjs.js';
 import { RUNTIMES } from './runtimes.js';
+import { describeExit, spawnToCompletion } from './spawn.js';
 /**
  * Walk up from `startDir` for `<node_modules>/@gjsify/node-gi`, returning its package directory
  * or null. A plain fs walk because Node's own resolver is not available under the GJS-bundled CLI.
@@ -60,7 +60,7 @@ export function nodeBinary() {
  * Run a `--app node` bundle on Node.js with the native typelib env set (same detection as
  * {@link runGjsBundle}). Throws when `@gjsify/node-gi` is not resolvable.
  */
-export async function runNodeBundle(bundlePath, extraArgs = [], options = {}) {
+export async function runNodeBundle(bundlePath, extraArgs = [], options) {
     const cwd = process.cwd();
     if (!resolveNodeGiForBundle(bundlePath, cwd)) {
         throw new Error('Cannot run the storybook on Node: `@gjsify/node-gi` is not installed.\n' +
@@ -74,27 +74,28 @@ export async function runNodeBundle(bundlePath, extraArgs = [], options = {}) {
     // Echo on stderr, so a child speaking a protocol on stdout stays uncontaminated.
     const cmd = [nodeBin, ...nodeArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
     console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${cmd}`);
-    const child = spawn(nodeBin, nodeArgs, { env, stdio: 'inherit' });
-    await new Promise((resolvePromise, reject) => {
-        child.on('close', (code) => {
-            if (code !== 0)
-                reject(new Error(`node exited with code ${code}`));
-            else
-                resolvePromise();
-        });
-        child.on('error', reject);
-    }).catch((err) => {
+    let result;
+    try {
+        result = await spawnToCompletion(nodeBin, nodeArgs, { completion: options.completion, env });
+    }
+    catch (err) {
         console.error(err.message);
-        process.exit(1);
-    });
+        return process.exit(1);
+    }
+    if (result.code !== 0) {
+        console.error(`node exited with ${describeExit(result)}`);
+        return process.exit(result.code ?? 1);
+    }
     if (options.exitOnSuccess)
-        process.exit(0);
+        return process.exit(0);
 }
 /**
  * Whether a `--app node` bundle actually consumes `@gjsify/node-gi` — kept EXTERNAL, so a bundle
  * using gi:// imports the shim by name. A plain Node app does NOT, and must run on node/bun/deno
- * WITHOUT node-gi installed, which is why the check is conditional here and not unconditional
- * like the storybook path.
+ * WITHOUT node-gi installed, which is why the check is conditional rather than a flat "this is a
+ * node bundle, demand node-gi". The supervised launcher (`utils/watch-loop.ts`) asks the same
+ * question for the same reason: `gjsify dev` on a web-server template builds a node bundle that
+ * never reaches a typelib.
  */
 export function bundleRequiresNodeGi(bundlePath) {
     try {
@@ -112,7 +113,7 @@ export function bundleRequiresNodeGi(bundlePath) {
  *
  * `gjs` is intentionally NOT handled here — the caller dispatches it to {@link runGjsBundle}.
  */
-export async function runRuntimeBundle(runtime, bundlePath, extraArgs = [], options = {}) {
+export async function runRuntimeBundle(runtime, bundlePath, extraArgs = [], options) {
     const cwd = process.cwd();
     const resolvedBundle = resolve(bundlePath);
     if (bundleRequiresNodeGi(resolvedBundle) && !resolveNodeGiForBundle(resolvedBundle, cwd)) {
@@ -131,32 +132,24 @@ export async function runRuntimeBundle(runtime, bundlePath, extraArgs = [], opti
     const shown = [cmd, ...launchArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
     if (!options.quiet)
         console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${shown}`);
-    const child = spawn(cmd, launchArgs, { env, stdio: 'inherit' });
     // Re-raise the CHILD's own code rather than a blanket 1 — a script run through
     // `--node-script` reports its status through this path, and a caller reading `$?` needs
-    // the real one.
-    let failed = false;
-    let childCode = 1;
-    await new Promise((resolvePromise, reject) => {
-        child.on('close', (code) => {
-            if (code !== 0) {
-                childCode = code ?? 1;
-                reject(new Error(`${runtime} exited with code ${code}`));
-            }
-            else
-                resolvePromise();
-        });
-        child.on('error', reject);
-    }).catch((err) => {
+    // the real one. A spawn failure has no code of its own and falls back to 1.
+    const failed = (code) => {
+        process.exitCode = code;
+        return process.exit(code);
+    };
+    let result;
+    try {
+        result = await spawnToCompletion(cmd, launchArgs, { completion: options.completion, env });
+    }
+    catch (err) {
         console.error(err.message);
-        failed = true;
-    });
-    // `return process.exit(…)`, and a flag rather than an exit inside the `catch`: under GJS
-    // `process.exit()` is deferred and RETURNS, so a bare call in the catch fell through to the
-    // `exitOnSuccess` line below and scheduled a second exit.
-    if (failed) {
-        process.exitCode = childCode;
-        return process.exit(childCode);
+        return failed(1);
+    }
+    if (result.code !== 0) {
+        console.error(`${runtime} exited with ${describeExit(result)}`);
+        return failed(result.code ?? 1);
     }
     if (options.exitOnSuccess)
         return process.exit(0);

package/lib/utils/ship/deb.d.ts

@@ -1,7 +1,7 @@
-import type { PayloadEntry } from './payload.js';
-import type { ShipSettings } from './types.js';
+import { type PayloadEntry } from './payload.js';
+import type { PackSettings } from './types.js';
 export interface DebInputs {
-    settings: ShipSettings;
+    settings: PackSettings;
     /** The staged payload, prefix-relative. */
     payload: readonly PayloadEntry[];
     /** Install prefix, e.g. `/usr`. */

package/lib/utils/ship/deb.js

@@ -20,8 +20,9 @@ import { createArArchive } from './ar.js';
 import { formatDebDepend } from './depends.js';
 import { gzipDeterministic } from './gzip.js';
 import { renderDebScripts } from './scripts.js';
+import { readPayloadFacts } from './payload.js';
 export async function buildDeb(inputs) {
-    const { settings, payload, mtime } = inputs;
+    const { payload, mtime } = inputs;
     const prefix = inputs.prefix.replace(/^\/+/, '');
     const named = payload.map((entry) => ({ ...entry, tarPath: `./${posix.join(prefix, entry.path)}` }));
     const directories = ancestorDirectories(named.map((entry) => entry.tarPath));
@@ -44,7 +45,10 @@ export async function buildDeb(inputs) {
         { name: './control', body: control, mode: 0o644, mtime },
         { name: './md5sums', body: md5sums, mode: 0o644, mtime },
     ];
-    const maintainerScripts = renderDebScripts(settings, inputs.prefix);
+    // From the PAYLOAD, not the settings: the maintainer scripts refresh exactly the
+    // directories this package wrote into, and since ADR 0024 § A2 this packer also runs on a
+    // host that has the staged tree and no project to ask.
+    const maintainerScripts = renderDebScripts(readPayloadFacts(payload), inputs.prefix);
     for (const [name, body] of Object.entries(maintainerScripts)) {
         // dpkg refuses a maintainer script outside 0555–0775 with the mode in
         // the error, so this is 0755 rather than "whatever the source had".

package/lib/utils/ship/depends.d.ts

@@ -14,16 +14,19 @@ import type { FormatId } from './types.js';
  * is how a project whose bundle really does run on older GJS lowers it.
  */
 export declare const DEFAULT_GJS_FLOOR = "1.86";
-/**
- * Warn when the derived floor cannot be satisfied by a released Debian.
- * Returns the warning lines; empty when the floor is fine.
- */
 export declare function warnAboutGjsFloor(format: FormatId, floor: string): string[];
 export interface DependsInputs {
     /** GI namespaces the bundle imports, in `Ns-Version` spelling. */
     namespaces: readonly string[];
-    /** `'app'` installs a desktop entry and icons; `'cli'` does not. */
-    kind: 'app' | 'cli';
+    /**
+     * Whether the payload installs into `share/icons/hicolor/`.
+     *
+     * Was `kind: 'app' | 'cli'`, which is a proxy for the question and not the question:
+     * `hicolor-icon-theme` is depended on because it OWNS that directory, so an app that
+     * installs no icon used to declare a dependency it never touched. Derived from the payload
+     * (`readPayloadFacts`), which is also the only thing the packing host has (ADR 0024 § A2).
+     */
+    hasIcons: boolean;
     /** Whether the payload installs GSettings schemas. */
     hasSchemas: boolean;
     /** User-supplied additions for this format. */
@@ -33,6 +36,11 @@ export interface DependsInputs {
         deb: string;
         rpm: string;
     }>;
+    /**
+     * Paths of typelib files the payload carries itself. The namespaces they cover need no distro
+     * dependency — and are derived from these filenames, never declared separately.
+     */
+    bundledTypelibs?: readonly string[];
     /** Minimum GJS. Default {@link DEFAULT_GJS_FLOOR}. */
     minGjsVersion?: string;
 }

package/lib/utils/ship/depends.js

@@ -35,14 +35,34 @@
  * is how a project whose bundle really does run on older GJS lowers it.
  */
 export const DEFAULT_GJS_FLOOR = '1.86';
+/**
+ * The package providing `glib-compile-schemas`, per format.
+ *
+ * A record, not `format === 'deb' ? … : …`. The ternary reads as a two-way
+ * choice and is really "deb, or ELSE rpm's package name" — measured on a third
+ * format, `dmg` got `glib2`, at exit 0, in the `Depends:` of a package that has
+ * no such thing. Adding a `FormatId` now fails to build here instead.
+ */
+const SCHEMA_COMPILER_PACKAGE = { deb: 'libglib2.0-bin', rpm: 'glib2' };
 /** Debian's `gjs` versions per suite, as measured 2026-08-15 — see {@link warnAboutGjsFloor}. */
 const DEBIAN_GJS = 'trixie ships 1.82.3 and forky 1.88.1; 1.84 and 1.86 were skipped';
 /**
  * Warn when the derived floor cannot be satisfied by a released Debian.
  * Returns the warning lines; empty when the floor is fine.
  */
+/**
+ * Which formats this Debian-suite warning is ABOUT.
+ *
+ * A `Record<FormatId, …>` and not `format !== 'deb'`: the negative form answers
+ * for every format that will ever exist, and answers "stay quiet" — so a third
+ * format would inherit silence about a floor nobody has checked for its distro,
+ * with no compile error. As a record, adding a `FormatId` fails to build until
+ * someone decides. `rpm` is false because Fedora ships a current GJS, which is a
+ * measured fact about Fedora, not a default.
+ */
+const GJS_FLOOR_IS_DEBIAN_NEWS = { deb: true, rpm: false };
 export function warnAboutGjsFloor(format, floor) {
-    if (format !== 'deb')
+    if (!GJS_FLOOR_IS_DEBIAN_NEWS[format])
         return [];
     // Only a floor forky ACTUALLY satisfies is quiet. The first cut tested
     // `>= 1.88.1` and therefore went silent for 1.90 and 2.0 as well — the
@@ -105,6 +125,12 @@ const TYPELIB_PACKAGES = {
     'Notify-0.7': { deb: 'gir1.2-notify-0.7', rpm: 'libnotify' },
     'Vte-3.91': { deb: 'gir1.2-vte-3.91', rpm: 'vte291-gtk4' },
     'Manette-0.2': { deb: 'gir1.2-manette-0.2', rpm: 'libmanette' },
+    // libgda — what `@gjsify/sqlite` binds, so every project with a local database lands here.
+    // The rpm name is measured on this machine (`rpm -qf …/Gda-6.0.typelib` → libgda); the deb name
+    // follows the `gir1.2-<name>-<version>` convention every row above uses and is NOT verified
+    // against a Debian system. Said plainly because a wrong name fails at `apt install` with a
+    // clear error, while no row at all fails the BUILD of every such project.
+    'Gda-6.0': { deb: 'gir1.2-gda-6.0', rpm: 'libgda' },
 };
 /**
  * A typelib the payload CARRIES, rather than one the system provides.
@@ -131,8 +157,21 @@ const BUNDLED_TYPELIB = /^Gjsify[A-Z]/;
 export function deriveDepends(format, inputs) {
     const out = [`gjs >= ${inputs.minGjsVersion ?? DEFAULT_GJS_FLOOR}`];
     const unmapped = [];
+    // Namespaces the package SHIPS ITSELF, read off the staged filenames rather than from a
+    // separate declaration: `Gwebgl-0.1.typelib` → `Gwebgl-0.1` and `Gwebgl`. Deriving it is the
+    // point — a project that declared a namespace bundled without the file being there would get
+    // a package that installs and dies at the first import, which is exactly what this check
+    // exists to prevent.
+    const shipped = new Set();
+    for (const file of inputs.bundledTypelibs ?? []) {
+        const match = /([A-Za-z0-9]+)-([\d.]+)\.typelib$/.exec(file);
+        if (!match)
+            continue;
+        shipped.add(`${match[1]}-${match[2]}`);
+        shipped.add(match[1]);
+    }
     for (const namespace of [...new Set(inputs.namespaces)].sort()) {
-        if (BUNDLED_TYPELIB.test(namespace))
+        if (BUNDLED_TYPELIB.test(namespace) || shipped.has(namespace))
             continue;
         const entry = lookupTypelib(namespace, inputs.typelibPackages);
         if (entry === undefined) {
@@ -152,7 +191,9 @@ export function deriveDepends(format, inputs) {
             'have to. (`gjsify.ship.depends.<format>` is for dependencies that are not typelibs at all — it ' +
             'appends, and deliberately does not silence this.)');
     }
-    if (inputs.kind === 'app')
+    // The package that owns `/usr/share/icons/hicolor` — so this follows the icons, not the
+    // app/cli distinction that used to stand in for them.
+    if (inputs.hasIcons)
         out.push('hicolor-icon-theme');
     // The package that ships `glib-compile-schemas`, NOT `gsettings-desktop-schemas`
     // (which ships GNOME's own `org.gnome.desktop.*` schemas and has nothing to
@@ -163,7 +204,7 @@ export function deriveDepends(format, inputs) {
     // `Gio.Settings.new()` aborts the app — an install that succeeds and an app
     // that does not start.
     if (inputs.hasSchemas)
-        out.push(format === 'deb' ? 'libglib2.0-bin' : 'glib2');
+        out.push(SCHEMA_COMPILER_PACKAGE[format]);
     out.push(...inputs.extra);
     // Set-dedupe keeps first-insertion order, so `gjs` stays first and the
     // list is stable across runs.

package/lib/utils/ship/discover.js

@@ -4,23 +4,128 @@
 // so `settings.ts` and `plan.ts` can stay pure. Every probe has a configured
 // override; the probes exist so a project that follows the GNOME convention
 // (`data/icons/hicolor/…`, `data/*.gschema.xml`) needs no configuration at all.
-import { existsSync, readdirSync, statSync } from 'node:fs';
-import { isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 import { LICENSE_FILE_NAMES } from './settings.js';
 const ICON_EXTENSIONS = ['.svg', '.png'];
 export function discoverPayload(input) {
     const { projectDir, ship } = input;
     const bundlePath = resolveBundle(input);
     const bundleDir = resolve(bundlePath, '..');
+    const localeFiles = discoverLocales(projectDir, ship.localeDir);
     return {
         bundlePath,
         bundleDir,
-        bundleFiles: listFilesRecursive(bundleDir),
+        // Everything beside the bundle, MINUS the locale tree when it lives there.
+        //
+        // `dist/locale/` sits next to `dist/app.gjs.mjs` in the layout
+        // `@gjsify/vite-plugin-gettext` writes by default, and the wholesale bundle staging would
+        // then put every catalogue in `lib/<binary>/locale/` as well as in `share/locale/`.
+        // Measured on a probe package: the same `.mo` appeared at both paths. The `lib/` copy is
+        // dead weight — nothing looks there — and it is the same failure that once shipped the test
+        // suite: whatever is beside the bundle gets carried whether or not it belongs in a package.
+        bundleFiles: withoutLocaleTree(listFilesRecursive(bundleDir), bundleDir, projectDir, ship.localeDir),
         iconFiles: discoverIcons(projectDir, ship.icon ?? input.flatpakIcon),
         schemaFiles: discoverSchemas(projectDir, ship.schemas),
+        typelibFiles: discoverTypelibs(projectDir, ship.bundledTypelibs),
+        localeFiles,
         licenseFile: discoverLicense(projectDir, ship.licenseFile),
     };
 }
+/**
+ * Typelibs (and their shared libraries) the PROJECT ships itself.
+ *
+ * Necessary because gjsify's own GI libraries — `Gwebgl` for the WebGL bridge, the GTK runtime
+ * bundles, the napi host — arrive as npm prebuilds, not as distro packages. An app using one has
+ * no `gir1.2-…` to depend on: it must carry the files, and something must point GI at them.
+ *
+ * A directory rather than a list of files, because a typelib is never alone: `Gwebgl-0.1.typelib`
+ * is useless without `libgwebgl.so`, and staging one without the other produces a package that
+ * installs and then fails at the first import.
+ */
+function discoverTypelibs(projectDir, dirs) {
+    const out = [];
+    for (const dir of dirs ?? []) {
+        const root = resolve(projectDir, dir);
+        if (!existsSync(root)) {
+            throw new Error(`gjsify ship: \`gjsify.ship.bundledTypelibs\` names ${dir}, which does not exist. ` +
+                'A missing directory here means the package would install without the typelib it promises.');
+        }
+        for (const file of listFilesRecursive(root)) {
+            if (/\.typelib$|\.so(\.\d+)*$/.test(file))
+                out.push(join(root, file));
+        }
+    }
+    return out;
+}
+/**
+ * Drop the declared locale tree from the wholesale bundle staging.
+ *
+ * Only when it actually lies inside the bundle directory — a `localeDir` elsewhere in the project
+ * was never part of `bundleFiles` and there is nothing to subtract.
+ */
+function withoutLocaleTree(bundleFiles, bundleDir, projectDir, localeDir) {
+    if (localeDir === undefined)
+        return bundleFiles;
+    const localeRoot = resolve(projectDir, localeDir);
+    const rel = relative(bundleDir, localeRoot);
+    // Outside the bundle dir: `relative` climbs out (`..`) or returns an absolute path.
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel))
+        return bundleFiles;
+    // Only `rel` needs normalising: it comes from `relative`, so it is host-shaped, while
+    // `bundleFiles` is POSIX by `listFilesRecursive`'s contract. Comparing a host-shaped prefix
+    // against POSIX entries matches nothing on Windows — and matching nothing here means the
+    // catalogues quietly ship twice again, on that platform only.
+    const prefix = `${rel.split(sep).join(posix.sep)}${posix.sep}`;
+    return bundleFiles.filter((file) => !`${file}${posix.sep}`.startsWith(prefix));
+}
+/**
+ * Compiled gettext catalogues the project ships (`gjsify.ship.localeDir`).
+ *
+ * Only `.mo` files, and only in the layout `bindtextdomain` actually reads —
+ * `<lang>/LC_MESSAGES/<domain>.mo`. Both refusals cover the same failure, which is the quiet kind:
+ * a catalogue in the wrong place, or left as `.po`, installs perfectly and the app then shows the
+ * untranslated msgid forever. That is indistinguishable from "no translation exists", so it is not
+ * something a user or a maintainer would ever report as a packaging bug.
+ */
+function discoverLocales(projectDir, dir) {
+    if (dir === undefined)
+        return [];
+    const root = resolve(projectDir, dir);
+    if (!existsSync(root)) {
+        throw new Error(`gjsify ship: \`gjsify.ship.localeDir\` names ${dir}, which does not exist. ` +
+            'Compile the catalogues first (msgfmt, or @gjsify/vite-plugin-gettext) — a missing ' +
+            'directory here means the package would install without the translations it promises.');
+    }
+    const out = [];
+    const strays = [];
+    for (const rel of listFilesRecursive(root)) {
+        if (rel.endsWith('.po') || rel.endsWith('.pot')) {
+            strays.push(`${rel} (a .po source; bindtextdomain reads .mo only)`);
+            continue;
+        }
+        if (!rel.endsWith('.mo'))
+            continue;
+        // `listFilesRecursive` normalises to POSIX, so one separator is all there is to split on.
+        const parts = rel.split(posix.sep);
+        if (parts.length !== 3 || parts[1] !== 'LC_MESSAGES') {
+            strays.push(`${rel} (expected <lang>/LC_MESSAGES/<domain>.mo)`);
+            continue;
+        }
+        out.push({ rel: parts.join('/'), abs: join(root, rel) });
+    }
+    if (strays.length > 0) {
+        throw new Error(`gjsify ship: \`gjsify.ship.localeDir\` (${dir}) holds files no catalogue lookup will find:\n` +
+            strays.map((s) => `  ${s}`).join('\n') +
+            '\nA misplaced catalogue installs and then shows nothing, which reads exactly like having ' +
+            'no translation at all. Lay them out as <lang>/LC_MESSAGES/<domain>.mo.');
+    }
+    if (out.length === 0) {
+        throw new Error(`gjsify ship: \`gjsify.ship.localeDir\` (${dir}) contains no \`.mo\` catalogue. ` +
+            'Declaring a locale directory that ships nothing is a promise the package does not keep.');
+    }
+    return out;
+}
 function resolveBundle(input) {
     const declared = input.declaredBundle;
     if (declared === undefined) {
@@ -84,6 +189,34 @@ function discoverSchemas(projectDir, configured) {
     }
     return [];
 }
+/**
+ * The licence text this package ships — searched UP the tree, not just beside
+ * `package.json`.
+ *
+ * A monorepo package does not carry its own copy. `packages/infra/cli`
+ * declares `"license": "MIT"` and the text lives one `LICENSE` up at the
+ * repository root, shared by sixty-odd packages; searching `projectDir` alone
+ * found nothing, `planOverlay` turned "nothing" into an empty overlay, and the
+ * `.deb` shipped without the `/usr/share/doc/<pkg>/copyright` that Debian
+ * Policy § 12.5 requires. Nothing downstream noticed: `dpkg-deb --info` prints
+ * a clean control file and `dpkg -i` installs it. It took the first leg that
+ * ran a real `lintian` to say so.
+ *
+ * WHERE THE SEARCH STOPS is the whole design. It climbs to the first ancestor
+ * that is a project root — one holding `.git`, or a `package.json` declaring
+ * `workspaces` — and searches that directory too, then stops. Above that line
+ * a `LICENSE` belongs to some unrelated tree that happens to be a parent
+ * directory (`~/Projekte/LICENSE` is not yours), and packaging its text would
+ * make a specific false legal claim. When NO marker is found the search is the
+ * project directory alone: without a marker there is no way to tell where the
+ * project ends, and guessing wrong is the same false claim.
+ *
+ * What this cannot check is whether the inherited text is the RIGHT licence
+ * for this package — an Apache-2.0 package inside an MIT monorepo would
+ * inherit the wrong one. Reading an SPDX identifier out of licence prose is
+ * not something to guess at, so the caller PRINTS the inherited path instead
+ * (see `commands/ship.ts`), and `gjsify.ship.licenseFile` overrides it.
+ */
 function discoverLicense(projectDir, configured) {
     if (configured !== undefined) {
         const target = resolve(projectDir, configured);
@@ -92,13 +225,51 @@ function discoverLicense(projectDir, configured) {
         }
         return target;
     }
-    for (const name of LICENSE_FILE_NAMES) {
-        const target = join(projectDir, name);
-        if (existsSync(target))
-            return target;
+    for (const dir of licenseSearchDirs(projectDir)) {
+        for (const name of LICENSE_FILE_NAMES) {
+            const target = join(dir, name);
+            if (existsSync(target))
+                return target;
+        }
     }
     return undefined;
 }
+/** `projectDir` first, then each ancestor up to and including the project root. */
+function licenseSearchDirs(projectDir) {
+    const dirs = [];
+    for (let current = projectDir;;) {
+        dirs.push(current);
+        if (isProjectRoot(current))
+            return dirs;
+        const parent = dirname(current);
+        if (parent === current)
+            return [projectDir];
+        current = parent;
+    }
+}
+/**
+ * Is this the top of the tree the project belongs to?
+ *
+ * `.git` is tested with `existsSync` rather than `statSync().isDirectory()`
+ * because in a git WORKTREE it is a file, and this repository is developed in
+ * worktrees.
+ */
+function isProjectRoot(dir) {
+    if (existsSync(join(dir, '.git')))
+        return true;
+    const manifest = join(dir, 'package.json');
+    if (!existsSync(manifest))
+        return false;
+    try {
+        return JSON.parse(readFileSync(manifest, 'utf-8')).workspaces !== undefined;
+    }
+    catch {
+        // A malformed `package.json` in some ancestor is not this command's
+        // business, and it must not turn a licence search into a ship failure.
+        // Not a root, then: the climb continues and `.git` still stops it.
+        return false;
+    }
+}
 /**
  * Every regular file under `dir`, as POSIX-separated relative paths.
  *

package/lib/utils/ship/formats.js

@@ -58,7 +58,15 @@ export const FORMATS = {
         fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.${archLabel}.rpm`,
     },
 };
-export const FORMAT_IDS = ['deb', 'rpm'];
+// DERIVED, never a second list. `FORMATS` is `Record<FormatId, …>`, so the
+// compiler already refuses a `FormatId` with no descriptor — reading the keys
+// back inherits that guarantee for free. Written out by hand this was the one
+// unbound copy of the vocabulary: adding a format to `FormatId` and `FORMATS`
+// compiled fine and left this list short, which would have made the new format
+// absent from the default targets (`ship.ts` uses it as the `??` fallback),
+// missing from `--help`, and REFUSED by `readStage` as an unknown id.
+// Insertion order is stable for string keys, and `resolveFormats` sorts anyway.
+export const FORMAT_IDS = Object.keys(FORMATS);
 /** Parse `--target deb,rpm` into a sorted, deduplicated descriptor list. */
 export function resolveFormats(raw) {
     const names = raw

package/lib/utils/ship/launcher.js

@@ -23,7 +23,7 @@ function shellQuote(value) {
 export function renderLauncher(settings, bundleRelPath) {
     const lib = `"$prefix"/lib/${settings.binaryName}`;
     const args = settings.execArgs.map(shellQuote).join(' ');
-    return [
+    const lines = [
         '#!/bin/sh',
         '# Generated by `gjsify ship` — do not edit.',
         'set -e',
@@ -31,7 +31,30 @@ export function renderLauncher(settings, bundleRelPath) {
         'prefix=$(dirname "$(dirname "$self")")',
         'XDG_DATA_DIRS="$prefix/share:${XDG_DATA_DIRS:-/usr/local/share:/usr/share}"',
         'export XDG_DATA_DIRS',
-        `exec gjs -m ${lib}/${bundleRelPath}${args ? ` ${args}` : ''} "$@"`,
-        '',
-    ].join('\n');
+    ];
+    // Typelibs the package carries itself (see `gjsify.ship.bundledTypelibs`). PREPENDED, not
+    // replacing: an app that ships `Gwebgl` still needs the system `Gtk`, and clobbering the path
+    // would trade one missing namespace for all the others. Only emitted when something was
+    // actually staged — an empty `GI_TYPELIB_PATH` entry makes GI search a directory that is not
+    // there, on every import, forever.
+    if (settings.typelibFiles.length > 0) {
+        const giDir = '"$prefix"/lib/' + settings.binaryName + '/gi';
+        for (const variable of ['GI_TYPELIB_PATH', 'LD_LIBRARY_PATH']) {
+            // `${VAR:+:$VAR}` appends the existing value with a separator ONLY when it is set —
+            // a plain `:$VAR` leaves a trailing colon, which both loaders read as "and the current
+            // directory", and a package that silently adds `.` to a library path is a bad package.
+            lines.push(`${variable}=${giDir}\${${variable}:+:$${variable}}`, `export ${variable}`);
+        }
+    }
+    // Where the app's gettext catalogues landed. `bindtextdomain` takes a DIRECTORY and there is no
+    // standard environment variable it reads on its own (`TEXTDOMAINDIR` is honoured by the gettext
+    // command-line tools, not by the library), so the prefix has to reach the app somehow. Passing
+    // it from the launcher keeps the app free of install-layout knowledge, exactly as XDG_DATA_DIRS
+    // above does for icons and schemas — a baked `/usr/share/locale` would be wrong in a Flatpak
+    // and in any `--prefix` tree.
+    if (settings.localeFiles.length > 0) {
+        lines.push('GJSIFY_LOCALE_DIR="$prefix"/share/locale', 'export GJSIFY_LOCALE_DIR');
+    }
+    lines.push(`exec gjs -m ${lib}/${bundleRelPath}${args ? ` ${args}` : ''} "$@"`, '');
+    return lines.join('\n');
 }

package/lib/utils/ship/mime.d.ts

@@ -0,0 +1,19 @@
+import type { ShipMimeType } from './types.js';
+/**
+ * Validate the declared types, throwing on anything that would install and then not work.
+ *
+ * Each refusal is a silent failure made loud:
+ *  - a malformed type name is written into the XML and ignored by `update-mime-database`;
+ *  - a glob without `*.` never matches (`bauplan` matches only a file called exactly that);
+ *  - a type with no glob and no parent type can never be DETECTED, so it is registered and unused;
+ *  - a duplicate definition makes which comment wins depend on document order.
+ */
+export declare function validateMimeTypes(types: readonly ShipMimeType[]): void;
+/**
+ * The shared-mime-info document for `types`.
+ *
+ * One file per package, named after the app id, because `share/mime/packages/` is shared: a generic
+ * name is a collision with whatever another package put there — the same reason the schema staging
+ * uses the app id.
+ */
+export declare function renderMimePackage(types: readonly ShipMimeType[]): string;