@gjsify/cli 0.39.0 → 0.41.0

package/lib/utils/ship/deb.js

@@ -0,0 +1,118 @@
+// The `.deb` packer.
+//
+// A Debian package is `debian-binary` + `control.tar.gz` + `data.tar.gz` in an
+// ar container, and every one of those three parts already had a writer in
+// this tree (`utils/ship/ar.ts`, `@gjsify/tar`) or is four bytes long. So no
+// `dpkg-deb`, no vendored Go binary, no download at ship time — which is what
+// lets the packer run under GJS, offline, on a Fedora CI image where dpkg does
+// not exist.
+//
+// Everything below that looks like a detail is a documented dpkg failure mode:
+// the ancestor-directory expansion (dpkg never calls `mkdir -p` and an ENOENT
+// aborts the unpack), the `md5sums` path spelling (no `./`, exactly two
+// spaces), the final newline in `control` (its absence is a parse error), and
+// the gzip header's mtime (not a dpkg failure at all — it silently destroys
+// reproducibility instead).
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+import { createTarball } from '@gjsify/tar';
+import { createArArchive } from './ar.js';
+import { formatDebDepend } from './depends.js';
+import { gzipDeterministic } from './gzip.js';
+import { renderDebScripts } from './scripts.js';
+export async function buildDeb(inputs) {
+    const { settings, 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));
+    const dataEntries = [
+        ...directories.map((name) => ({ name, mode: 0o755, mtime, directory: true })),
+        ...named.map((entry) => ({ name: entry.tarPath, body: entry.data, mode: entry.mode, mtime })),
+    ];
+    const dataTar = await gzipDeterministic(createTarball(dataEntries));
+    // Policy 5.6.20: regular files and symlinks round UP to whole KiB, every
+    // other filesystem object counts as one. Getting the unit wrong (bytes
+    // instead of KiB) is invisible — dpkg never validates this field, apt just
+    // shows the user a wrong number.
+    const installedSize = named.reduce((total, entry) => total + Math.ceil(entry.data.byteLength / 1024), 0) + directories.length;
+    const control = renderControl(inputs, installedSize);
+    const md5sums = named
+        .map((entry) => `${createHash('md5').update(entry.data).digest('hex')}  ${entry.tarPath.slice(2)}\n`)
+        .join('');
+    const controlEntries = [
+        { name: './', mode: 0o755, mtime, directory: true },
+        { name: './control', body: control, mode: 0o644, mtime },
+        { name: './md5sums', body: md5sums, mode: 0o644, mtime },
+    ];
+    const maintainerScripts = renderDebScripts(settings, 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".
+        controlEntries.push({ name: `./${name}`, body, mode: 0o755, mtime });
+    }
+    const controlTar = await gzipDeterministic(createTarball(controlEntries));
+    return createArArchive([
+        { name: 'debian-binary', data: new TextEncoder().encode('2.0\n'), mtime },
+        { name: 'control.tar.gz', data: controlTar, mtime },
+        { name: 'data.tar.gz', data: dataTar, mtime },
+    ]);
+}
+/**
+ * Collapse a value that has to occupy exactly one control line.
+ *
+ * A newline here does not corrupt the file — it FORGES a field: a summary
+ * pasted with a hard wrap turns its second line into whatever that line happens
+ * to start with, and `Pre-Depends: …` is a real thing to end up with by
+ * accident. The extended description already collapses whitespace per
+ * paragraph; these fields did not.
+ */
+function singleLine(value) {
+    return value.replace(/[\r\n]+/g, ' ').trim();
+}
+/**
+ * `./`, `./usr/`, `./usr/bin/`, … for every path in the archive.
+ *
+ * dpkg opens each file with `O_CREAT | O_EXCL` and never creates a parent, so
+ * a missing directory entry is `cannot create '<path>'` mid-unpack — with the
+ * package half-installed.
+ */
+export function ancestorDirectories(paths) {
+    const directories = new Set(['./']);
+    for (const path of paths) {
+        const parts = path.replace(/^\.\//, '').split('/');
+        parts.pop();
+        let current = '.';
+        for (const part of parts) {
+            current = `${current}/${part}`;
+            directories.add(`${current}/`);
+        }
+    }
+    return [...directories].sort();
+}
+function renderControl(inputs, installedSize) {
+    const { settings } = inputs;
+    const fields = [
+        ['Package', settings.binaryName],
+        ['Version', `${settings.version}-${settings.release}`],
+        ['Architecture', inputs.archLabel],
+        ['Maintainer', settings.maintainer],
+        ['Installed-Size', String(installedSize)],
+    ];
+    if (inputs.depends.length > 0)
+        fields.push(['Depends', inputs.depends.map(formatDebDepend).join(', ')]);
+    fields.push(['Section', settings.section], ['Priority', 'optional']);
+    if (settings.homepage)
+        fields.push(['Homepage', settings.homepage]);
+    const lines = fields.map(([key, value]) => `${key}: ${singleLine(value)}`);
+    // The extended description is continuation lines: one leading space per
+    // line, and a lone ` .` for a paragraph break — a truly blank line ends
+    // the field and silently truncates everything after it.
+    lines.push(`Description: ${singleLine(settings.summary)}`);
+    const body = settings.description.filter((paragraph) => paragraph !== settings.summary);
+    body.forEach((paragraph, index) => {
+        if (index > 0)
+            lines.push(' .');
+        lines.push(` ${paragraph}`);
+    });
+    return `${lines.join('\n')}\n`;
+}

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

@@ -0,0 +1,62 @@
+import type { FormatId } from './types.js';
+/**
+ * The GJS the bundles target (root AGENTS.md § Constraints: GJS 1.86 /
+ * SpiderMonkey 140, Rolldown `firefox140`). A `--app gjs` bundle can carry
+ * ES2024 syntax an older SpiderMonkey does not parse, so this is a real floor
+ * and not a formality.
+ *
+ * It is also, today, UNSATISFIABLE ON DEBIAN — measured, not assumed: Debian
+ * went 1.82.3 (trixie) straight to 1.88.1 (forky), skipping 1.84 and 1.86, so
+ * no Debian suite ships a `gjs` that satisfies `>= 1.86`. Emitting the honest
+ * floor means a `.deb` apt REFUSES on trixie; lowering it silently would mean
+ * one apt installs and the app then dies on a syntax error. `warnAboutGjsFloor`
+ * exists so the choice is visible at ship time, and `gjsify.ship.minGjsVersion`
+ * 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 GSettings schemas. */
+    hasSchemas: boolean;
+    /** User-supplied additions for this format. */
+    extra: readonly string[];
+    /** Project-supplied table rows, filling gaps in {@link TYPELIB_PACKAGES}. */
+    typelibPackages?: Record<string, {
+        deb: string;
+        rpm: string;
+    }>;
+    /** Minimum GJS. Default {@link DEFAULT_GJS_FLOOR}. */
+    minGjsVersion?: string;
+}
+/**
+ * The `Depends:` / `Requires:` list for one format.
+ *
+ * @throws when a namespace has no entry in the table — see the module header.
+ */
+export declare function deriveDepends(format: FormatId, inputs: DependsInputs): string[];
+/** One parsed dependency. `relation`/`version` are absent for an unversioned one. */
+export interface ParsedDepend {
+    name: string;
+    relation?: '>=' | '>' | '<=' | '<' | '=';
+    version?: string;
+}
+/** `gjs >= 1.86` → its parts. Both packers need this; only the spelling differs. */
+export declare function parseDepend(depend: string): ParsedDepend;
+/**
+ * Format a dependency for `Depends:`.
+ *
+ * dpkg puts the bound in parentheses and spells strict inequality `<<`/`>>` —
+ * bare `<`/`>` are deprecated aliases for `<=`/`>=`, so emitting them means the
+ * opposite of what it reads like.
+ */
+export declare function formatDebDepend(depend: string): string;
+/** The namespaces the table knows — exported so the unit tests can assert on the set. */
+export declare function knownNamespaces(): string[];

package/lib/utils/ship/depends.js

@@ -0,0 +1,221 @@
+// Runtime dependencies, derived from the artifact rather than declared.
+//
+// The namespaces come out of the BUILT BUNDLE, not out of a config key: the
+// bundle is what ships, so it is the only honest source. A declaration can be
+// stale in a way nothing notices until a user's dynamic linker complains.
+//
+// An unmapped namespace FAILS the build (ADR 0024 § 6). The reference
+// implementation returns `[]` for anything its four-entry table does not know,
+// which produces a package that installs cleanly and dies on first launch —
+// the failure lands on the user's machine, after the download, and reads as an
+// application bug. A table will always be incomplete; what may not stay is the
+// silence — so `gjsify.ship.typelibPackages` lets a project add the row itself
+// and the error prints the exact JSON to paste. That is deliberately a
+// different key from `gjsify.ship.depends`, which appends free-form
+// dependencies and does NOT silence this: a hatch that turns the check off is
+// how the check stops meaning anything.
+//
+// Not to be confused with `utils/check-system-deps.ts`'s `PM_PACKAGES`: that
+// maps BUILD-time `-dev` packages (headers, pkg-config files) for a developer
+// machine. What an installed app needs is the runtime typelib, and on Debian
+// those live in separate `gir1.2-*` packages — the two tables answer different
+// questions and would be wrong as one.
+/**
+ * The GJS the bundles target (root AGENTS.md § Constraints: GJS 1.86 /
+ * SpiderMonkey 140, Rolldown `firefox140`). A `--app gjs` bundle can carry
+ * ES2024 syntax an older SpiderMonkey does not parse, so this is a real floor
+ * and not a formality.
+ *
+ * It is also, today, UNSATISFIABLE ON DEBIAN — measured, not assumed: Debian
+ * went 1.82.3 (trixie) straight to 1.88.1 (forky), skipping 1.84 and 1.86, so
+ * no Debian suite ships a `gjs` that satisfies `>= 1.86`. Emitting the honest
+ * floor means a `.deb` apt REFUSES on trixie; lowering it silently would mean
+ * one apt installs and the app then dies on a syntax error. `warnAboutGjsFloor`
+ * exists so the choice is visible at ship time, and `gjsify.ship.minGjsVersion`
+ * is how a project whose bundle really does run on older GJS lowers it.
+ */
+export const DEFAULT_GJS_FLOOR = '1.86';
+/** 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.
+ */
+export function warnAboutGjsFloor(format, floor) {
+    if (format !== 'deb')
+        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
+    // floors no Debian will satisfy for years.
+    if (compareVersions(floor, '1.82.3') <= 0)
+        return [];
+    if (compareVersions(floor, '1.88.1') === 0)
+        return [];
+    return [
+        `gjsify ship: \`Depends: gjs (>= ${floor})\` is not satisfiable on Debian stable — ${DEBIAN_GJS}. ` +
+            'The package installs on forky/sid and on distributions with a newer GJS. Set ' +
+            '`gjsify.ship.minGjsVersion` if this bundle genuinely runs on an older GJS; do NOT lower it ' +
+            'to make apt happy, because the result is an install that succeeds and an app that does not start.',
+    ];
+}
+/** Numeric dotted-version compare. Enough for `1.82.3` vs `1.86`. */
+function compareVersions(a, b) {
+    const left = a.split('.').map(Number);
+    const right = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * GI namespace → the package that ships its typelib.
+ *
+ * Fedora entries were read off this project's own CI image with
+ * `rpm -qf /usr/lib64/girepository-1.0/<Ns>.typelib`; Debian ships the typelib
+ * in a `gir1.2-*` package separate from the runtime library, which is why the
+ * two columns look nothing alike for the same namespace.
+ */
+const TYPELIB_PACKAGES = {
+    // GLib stack — one package each side covers all four namespaces.
+    'GLib-2.0': { deb: 'gir1.2-glib-2.0', rpm: 'glib2' },
+    'GObject-2.0': { deb: 'gir1.2-glib-2.0', rpm: 'glib2' },
+    'Gio-2.0': { deb: 'gir1.2-glib-2.0', rpm: 'glib2' },
+    'GioUnix-2.0': { deb: 'gir1.2-glib-2.0', rpm: 'glib2' },
+    'GModule-2.0': { deb: 'gir1.2-glib-2.0', rpm: 'glib2' },
+    // GTK4 — Gdk/Gsk/Gtk all live in the same shared object.
+    'Gtk-4.0': { deb: 'gir1.2-gtk-4.0', rpm: 'gtk4' },
+    'Gdk-4.0': { deb: 'gir1.2-gtk-4.0', rpm: 'gtk4' },
+    'Gsk-4.0': { deb: 'gir1.2-gtk-4.0', rpm: 'gtk4' },
+    'Adw-1': { deb: 'gir1.2-adw-1', rpm: 'libadwaita' },
+    'GdkPixbuf-2.0': { deb: 'gir1.2-gdkpixbuf-2.0', rpm: 'gdk-pixbuf2' },
+    'Pango-1.0': { deb: 'gir1.2-pango-1.0', rpm: 'pango' },
+    'PangoCairo-1.0': { deb: 'gir1.2-pango-1.0', rpm: 'pango' },
+    'Graphene-1.0': { deb: 'gir1.2-graphene-1.0', rpm: 'graphene' },
+    // cairo's typelib is packaged with gobject-introspection on Fedora and in
+    // the catch-all gir1.2-freedesktop on Debian.
+    'cairo-1.0': { deb: 'gir1.2-freedesktop', rpm: 'gobject-introspection' },
+    'GtkSource-5': { deb: 'gir1.2-gtksource-5', rpm: 'gtksourceview5' },
+    'WebKit-6.0': { deb: 'gir1.2-webkit-6.0', rpm: 'webkitgtk6.0' },
+    'Soup-3.0': { deb: 'gir1.2-soup-3.0', rpm: 'libsoup3' },
+    'Json-1.0': { deb: 'gir1.2-json-1.0', rpm: 'json-glib' },
+    'Gst-1.0': { deb: 'gir1.2-gstreamer-1.0', rpm: 'gstreamer1' },
+    'Secret-1': { deb: 'gir1.2-secret-1', rpm: 'libsecret' },
+    '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' },
+};
+/**
+ * A typelib the payload CARRIES, rather than one the system provides.
+ *
+ * `@gjsify/*`'s native bridges ship their own `.typelib` inside the package —
+ * `GjsifyHttpSoupBridge`, which `@gjsify/http`'s server pulls in unconditionally,
+ * plus `GjsifyHttp2`, `GjsifySabNative` and the rest of the `*-native` set. No
+ * distribution has ever packaged a `gir1.2-gjsifyhttpsoupbridge` and none can:
+ * the file is in the tarball being built. So these are not a gap in the table.
+ * Mapping one would emit a dependency apt and dnf must fail to resolve, and the
+ * module header's rule — an unmapped namespace FAILS the build — is about a
+ * SYSTEM library nobody declared, which is the opposite situation.
+ *
+ * Excluding them is a precondition for widening the namespace scanner rather
+ * than a refinement of it: without this, `gjsify ship` throws on every project
+ * whose bundle reaches one, which includes every `@gjsify/http` server.
+ */
+const BUNDLED_TYPELIB = /^Gjsify[A-Z]/;
+/**
+ * The `Depends:` / `Requires:` list for one format.
+ *
+ * @throws when a namespace has no entry in the table — see the module header.
+ */
+export function deriveDepends(format, inputs) {
+    const out = [`gjs >= ${inputs.minGjsVersion ?? DEFAULT_GJS_FLOOR}`];
+    const unmapped = [];
+    for (const namespace of [...new Set(inputs.namespaces)].sort()) {
+        if (BUNDLED_TYPELIB.test(namespace))
+            continue;
+        const entry = lookupTypelib(namespace, inputs.typelibPackages);
+        if (entry === undefined) {
+            unmapped.push(namespace);
+            continue;
+        }
+        out.push(entry[format]);
+    }
+    if (unmapped.length > 0) {
+        throw new Error(`gjsify ship: the bundle imports ${unmapped.map((n) => `gi://${n.split('-')[0]}`).join(', ')}, ` +
+            `and no ${format} package is known to ship ${unmapped.length > 1 ? 'those typelibs' : 'that typelib'}. ` +
+            "An undeclared runtime dependency does not fail here — it fails on a user's machine after the " +
+            'download. Fill the gap in package.json:\n' +
+            `  "gjsify": { "ship": { "typelibPackages": { ${JSON.stringify(unmapped[0])}: ` +
+            '{ "deb": "gir1.2-…", "rpm": "…" } } } }\n' +
+            'and please contribute the mapping back to `utils/ship/depends.ts` so the next project does not ' +
+            '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')
+        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
+    // do with compiling ours). Measured: `rpm -qf /usr/bin/glib-compile-schemas`
+    // → glib2; on Debian the binary lives in `libglib2.0-bin`, which none of the
+    // `gir1.2-*` packages pull in. Without it the postinst's `command -v` guard
+    // silently skips, the schema is never compiled, and the first
+    // `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(...inputs.extra);
+    // Set-dedupe keeps first-insertion order, so `gjs` stays first and the
+    // list is stable across runs.
+    return [...new Set(out)];
+}
+/**
+ * Resolve a scanned specifier to a table row.
+ *
+ * `gi://Gtk?version=4.0` arrives as `Gtk-4.0` and matches directly. A bare
+ * `gi://Gtk` arrives as `Gtk` — GJS then loads whichever version the host has,
+ * so the honest answer is the table's single `Gtk-*` row, and an ambiguity
+ * (two rows for one namespace) has to be a build failure rather than a guess:
+ * picking one would silently declare a dependency on a different library than
+ * the one the app will load.
+ */
+function lookupTypelib(specifier, overrides = {}) {
+    // A project row wins over the built-in one: the table here is a snapshot
+    // of what two distributions call things today, and a project that knows
+    // better must not have to wait for a gjsify release to say so.
+    const table = { ...TYPELIB_PACKAGES, ...overrides };
+    const exact = table[specifier];
+    if (exact !== undefined)
+        return exact;
+    if (specifier.includes('-'))
+        return undefined;
+    const candidates = Object.keys(table).filter((key) => key.startsWith(`${specifier}-`));
+    if (candidates.length !== 1)
+        return undefined;
+    return table[candidates[0]];
+}
+/** `gjs >= 1.86` → its parts. Both packers need this; only the spelling differs. */
+export function parseDepend(depend) {
+    const match = /^(\S+)\s*(>=|<=|=|>|<)\s*(\S+)$/.exec(depend);
+    if (!match)
+        return { name: depend.trim() };
+    return { name: match[1], relation: match[2], version: match[3] };
+}
+/**
+ * Format a dependency for `Depends:`.
+ *
+ * dpkg puts the bound in parentheses and spells strict inequality `<<`/`>>` —
+ * bare `<`/`>` are deprecated aliases for `<=`/`>=`, so emitting them means the
+ * opposite of what it reads like.
+ */
+export function formatDebDepend(depend) {
+    const parsed = parseDepend(depend);
+    if (parsed.relation === undefined)
+        return parsed.name;
+    const relation = parsed.relation === '>' ? '>>' : parsed.relation === '<' ? '<<' : parsed.relation;
+    return `${parsed.name} (${relation} ${parsed.version})`;
+}
+/** The namespaces the table knows — exported so the unit tests can assert on the set. */
+export function knownNamespaces() {
+    return Object.keys(TYPELIB_PACKAGES).sort();
+}

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

@@ -0,0 +1,21 @@
+import type { ConfigDataShip } from '../../types/config-data.js';
+import { type DiscoveredPayload, type ShipPackageManifest } from './settings.js';
+export interface DiscoverInput {
+    projectDir: string;
+    pkg: ShipPackageManifest;
+    ship: ConfigDataShip;
+    /** `gjsify.flatpak.icon`, the pre-existing spelling of the same thing. */
+    flatpakIcon?: string;
+    /** The bundle path the project declares. */
+    declaredBundle?: string;
+}
+export declare function discoverPayload(input: DiscoverInput): DiscoveredPayload;
+/**
+ * Every regular file under `dir`, as POSIX-separated relative paths.
+ *
+ * A symlink is refused rather than followed: both package formats can carry
+ * one, but a symlink into the build tree would resolve to a path that does not
+ * exist on the user's machine, and silently copying its TARGET turns one file
+ * into an unexplained duplicate.
+ */
+export declare function listFilesRecursive(dir: string): string[];

package/lib/utils/ship/discover.js

@@ -0,0 +1,129 @@
+// Finding the payload on disk.
+//
+// The half of `gjsify ship` that must touch the filesystem, kept in one module
+// 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 { 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, '..');
+    return {
+        bundlePath,
+        bundleDir,
+        bundleFiles: listFilesRecursive(bundleDir),
+        iconFiles: discoverIcons(projectDir, ship.icon ?? input.flatpakIcon),
+        schemaFiles: discoverSchemas(projectDir, ship.schemas),
+        licenseFile: discoverLicense(projectDir, ship.licenseFile),
+    };
+}
+function resolveBundle(input) {
+    const declared = input.declaredBundle;
+    if (declared === undefined) {
+        throw new Error('gjsify ship: no bundle to ship. Set `gjsify.main` (or `main`) in package.json to the built ' +
+            'bundle, or `gjsify.ship.bundle` to override it.');
+    }
+    const bundlePath = isAbsolute(declared) ? declared : resolve(input.projectDir, declared);
+    if (!existsSync(bundlePath)) {
+        throw new Error(`gjsify ship: the bundle ${declared} does not exist. Build it first (\`gjsify run build\`), ` +
+            'or drop `--skip-build`.');
+    }
+    return bundlePath;
+}
+/**
+ * Icons: an explicit file, an explicit directory, or the GNOME convention.
+ *
+ * A directory is walked rather than globbed because the size lives in the PATH
+ * (`hicolor/128x128/apps/…`) as often as in the filename.
+ */
+function discoverIcons(projectDir, configured) {
+    if (configured !== undefined) {
+        const target = resolve(projectDir, configured);
+        if (!existsSync(target)) {
+            throw new Error(`gjsify ship: the configured icon path ${configured} does not exist.`);
+        }
+        return statSync(target).isDirectory() ? listIcons(target) : [target];
+    }
+    for (const candidate of ['data/icons', 'data/icons/hicolor']) {
+        const target = join(projectDir, candidate);
+        if (existsSync(target) && statSync(target).isDirectory()) {
+            const icons = listIcons(target);
+            if (icons.length > 0)
+                return icons;
+        }
+    }
+    return [];
+}
+function listIcons(dir) {
+    return listFilesRecursive(dir)
+        .filter((rel) => ICON_EXTENSIONS.some((ext) => rel.toLowerCase().endsWith(ext)))
+        .map((rel) => join(dir, rel.split('/').join(sep)))
+        .sort();
+}
+function discoverSchemas(projectDir, configured) {
+    const roots = configured !== undefined ? [resolve(projectDir, configured)] : [join(projectDir, 'data')];
+    for (const root of roots) {
+        if (!existsSync(root)) {
+            if (configured !== undefined) {
+                throw new Error(`gjsify ship: the configured schema path ${configured} does not exist.`);
+            }
+            continue;
+        }
+        if (!statSync(root).isDirectory())
+            return [root];
+        const schemas = listFilesRecursive(root)
+            .filter((rel) => rel.endsWith('.gschema.xml'))
+            .map((rel) => join(root, rel.split('/').join(sep)))
+            .sort();
+        if (schemas.length > 0)
+            return schemas;
+    }
+    return [];
+}
+function discoverLicense(projectDir, configured) {
+    if (configured !== undefined) {
+        const target = resolve(projectDir, configured);
+        if (!existsSync(target)) {
+            throw new Error(`gjsify ship: the configured licence file ${configured} does not exist.`);
+        }
+        return target;
+    }
+    for (const name of LICENSE_FILE_NAMES) {
+        const target = join(projectDir, name);
+        if (existsSync(target))
+            return target;
+    }
+    return undefined;
+}
+/**
+ * Every regular file under `dir`, as POSIX-separated relative paths.
+ *
+ * A symlink is refused rather than followed: both package formats can carry
+ * one, but a symlink into the build tree would resolve to a path that does not
+ * exist on the user's machine, and silently copying its TARGET turns one file
+ * into an unexplained duplicate.
+ */
+export function listFilesRecursive(dir) {
+    const out = [];
+    const walk = (current) => {
+        for (const entry of readdirSync(current, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isSymbolicLink()) {
+                throw new Error(`gjsify ship: ${full} is a symlink. The payload has to be self-contained — replace it ` +
+                    'with the file it points at, or exclude it from the bundle directory.');
+            }
+            else if (entry.isFile()) {
+                out.push(posix.join(...relative(dir, full).split(sep)));
+            }
+        }
+    };
+    walk(dir);
+    return out.sort();
+}

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

@@ -0,0 +1,5 @@
+import type { FormatDescriptor, FormatId } from './types.js';
+export declare const FORMATS: Record<FormatId, FormatDescriptor>;
+export declare const FORMAT_IDS: FormatId[];
+/** Parse `--target deb,rpm` into a sorted, deduplicated descriptor list. */
+export declare function resolveFormats(raw: readonly string[]): FormatDescriptor[];

package/lib/utils/ship/formats.js

@@ -0,0 +1,83 @@
+// The per-format table. Everything that differs between `.deb` and `.rpm`
+// outside the archive container itself lives here as DATA, so a new format is
+// a row rather than an edit across the stager, the overlay builder and the
+// artifact namer.
+// `process.arch` → the format's architecture name. Taken from dpkg's own
+// `data/cputable` and rpm's arch table. `arm` cannot be told apart from
+// `armel` by a running process, and Debian's hard-float port is what anything
+// current actually runs, so `armhf` is the default rather than a guess.
+const DEBIAN_ARCH = {
+    x64: 'amd64',
+    arm64: 'arm64',
+    ia32: 'i386',
+    arm: 'armhf',
+    riscv64: 'riscv64',
+    ppc64: 'ppc64el',
+    s390x: 's390x',
+};
+const RPM_ARCH = {
+    x64: 'x86_64',
+    arm64: 'aarch64',
+    ia32: 'i686',
+    arm: 'armv7hl',
+    riscv64: 'riscv64',
+    ppc64: 'ppc64le',
+    s390x: 's390x',
+};
+function lookupArch(table, arch, label) {
+    const mapped = table[arch];
+    if (!mapped) {
+        throw new Error(`gjsify ship: no ${label} architecture is known for \`process.arch\` "${arch}". ` +
+            `Known: ${Object.keys(table).join(', ')}.`);
+    }
+    return mapped;
+}
+function debArch(arch, archIndependent) {
+    return archIndependent ? 'all' : lookupArch(DEBIAN_ARCH, arch, 'Debian');
+}
+function rpmArch(arch, archIndependent) {
+    return archIndependent ? 'noarch' : lookupArch(RPM_ARCH, arch, 'RPM');
+}
+export const FORMATS = {
+    deb: {
+        id: 'deb',
+        prefix: '/usr',
+        // Debian policy § 12.5: every package ships its copyright in
+        // /usr/share/doc/<package>/copyright, and lintian errors without it.
+        licenseDest: (binaryName) => `share/doc/${binaryName}/copyright`,
+        licenseKind: 'debian-copyright',
+        archName: debArch,
+        fileName: (s, archLabel) => `${s.binaryName}_${s.version}-${s.release}_${archLabel}.deb`,
+    },
+    rpm: {
+        id: 'rpm',
+        prefix: '/usr',
+        licenseDest: (binaryName) => `share/licenses/${binaryName}/LICENSE`,
+        licenseKind: 'plain',
+        archName: rpmArch,
+        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.${archLabel}.rpm`,
+    },
+};
+export const FORMAT_IDS = ['deb', 'rpm'];
+/** Parse `--target deb,rpm` into a sorted, deduplicated descriptor list. */
+export function resolveFormats(raw) {
+    const names = raw
+        .flatMap((entry) => entry.split(','))
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    // `Object.hasOwn`, not `in`: `in` walks the prototype chain, so
+    // `--target constructor` resolved to `Object` and the refusal below never
+    // fired — the run then died somewhere unrelated.
+    const unknown = names.filter((name) => !Object.hasOwn(FORMATS, name));
+    if (unknown.length > 0) {
+        throw new Error(`gjsify ship: unknown target${unknown.length > 1 ? 's' : ''} ${unknown.join(', ')}. ` +
+            `Known targets: ${FORMAT_IDS.join(', ')}.`);
+    }
+    const unique = [...new Set(names)].sort();
+    // An empty list would otherwise stage the payload and pack nothing, exit 0,
+    // and print no artifact line — a success that produced no artifact.
+    if (unique.length === 0) {
+        throw new Error(`gjsify ship: --target named no format. Known targets: ${FORMAT_IDS.join(', ')}.`);
+    }
+    return unique.map((name) => FORMATS[name]);
+}

package/lib/utils/ship/gi-namespaces.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Extract the GI namespaces a bundle imports, as `Ns-Version` when the
+ * specifier pins one and bare `Ns` when it does not.
+ */
+export declare function scanGiNamespaces(source: string): string[];
+/** `gi://Gtk?version=4.0` → `Gtk-4.0`; `gi://Gtk` → `Gtk`; anything else → null. */
+export declare function parseGiSpecifier(specifier: string): string | null;