@gjsify/cli 0.39.0 → 0.40.0

package/lib/utils/ship/depends.js

@@ -0,0 +1,202 @@
+// 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' },
+};
+/**
+ * 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()) {
+        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;

package/lib/utils/ship/gi-namespaces.js

@@ -0,0 +1,49 @@
+// Which GI namespaces does this bundle actually load?
+//
+// Read off the emitted `--app gjs` bundle, because that is the file that gets
+// installed. `gi://` is a real module protocol under GJS, so the bundler keeps
+// those specifiers in the output verbatim (`rolldown-plugin-gjsify`'s externals
+// plugin) — the artifact carries its own dependency list and nothing has to be
+// declared twice.
+//
+// PARSED, not pattern-matched, and the first version of this file is why. A
+// regex over the bundle text got it wrong in both directions at once:
+//
+//   * it missed `import "gi://Soup?version=3.0"` — the bare side-effect form,
+//     which is exactly what `@gjsify/fetch` puts at the top of every bundle
+//     that pulls it. The package would have shipped without libsoup, installed
+//     cleanly, and died at the first request.
+//   * it matched `gi://…` inside a diagnostic STRING containing the word
+//     `from`, and since an unmapped namespace fails the build, that made a
+//     correct project unbuildable.
+//
+// `moduleSpecifiers` answers the question exactly, and it is the same acorn
+// pass the CLI already uses to compute its own runtime closure — so there is
+// one definition of "what does this file import" rather than two.
+import { moduleSpecifiers } from '../cli-runtime-closure.js';
+/**
+ * Extract the GI namespaces a bundle imports, as `Ns-Version` when the
+ * specifier pins one and bare `Ns` when it does not.
+ */
+export function scanGiNamespaces(source) {
+    const found = new Set();
+    for (const specifier of moduleSpecifiers(source)) {
+        const key = parseGiSpecifier(specifier);
+        if (key !== null)
+            found.add(key);
+    }
+    return [...found].sort();
+}
+/** `gi://Gtk?version=4.0` → `Gtk-4.0`; `gi://Gtk` → `Gtk`; anything else → null. */
+export function parseGiSpecifier(specifier) {
+    if (!specifier.startsWith('gi://'))
+        return null;
+    const rest = specifier.slice('gi://'.length);
+    const [namespace, query] = rest.split('?', 2);
+    if (namespace === undefined || !/^[A-Za-z][A-Za-z0-9_]*$/.test(namespace))
+        return null;
+    if (query === undefined)
+        return namespace;
+    const version = /(?:^|&)version=([^&]+)/.exec(query)?.[1];
+    return version === undefined ? namespace : `${namespace}-${version}`;
+}

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

@@ -0,0 +1,2 @@
+/** gzip with the header's timestamp zeroed and the OS byte pinned to Unix. */
+export declare function gzipDeterministic(input: Uint8Array): Promise<Uint8Array>;

package/lib/utils/ship/gzip.js

@@ -0,0 +1,21 @@
+// Deterministic gzip.
+//
+// The gzip header carries its own modification time in bytes 4-7 and the
+// compressing OS in byte 9. Leaving them alone makes two runs over identical
+// input produce different bytes — which no test notices, because every test
+// compares the DECOMPRESSED content. It is the single most-missed
+// reproducibility bug in package writers, and it costs nothing to close.
+import { gzip } from '@gjsify/tar';
+/** gzip with the header's timestamp zeroed and the OS byte pinned to Unix. */
+export async function gzipDeterministic(input) {
+    const out = await gzip(input);
+    if (out.byteLength < 10 || out[0] !== 0x1f || out[1] !== 0x8b) {
+        throw new Error('gjsify ship: internal error — gzip did not produce a gzip stream.');
+    }
+    out[4] = 0;
+    out[5] = 0;
+    out[6] = 0;
+    out[7] = 0;
+    out[9] = 3;
+    return out;
+}

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

@@ -0,0 +1,7 @@
+import type { ShipSettings } from './types.js';
+/**
+ * Render the launcher for a GJS application.
+ *
+ * `bundleRelPath` is the bundle's path inside `lib/<binaryName>/`.
+ */
+export declare function renderLauncher(settings: ShipSettings, bundleRelPath: string): string;

package/lib/utils/ship/launcher.js

@@ -0,0 +1,37 @@
+// The `bin/<name>` entry a package installs.
+//
+// It derives its own prefix at runtime instead of having one baked in. That is
+// what lets ONE staged payload become a `.deb` under `/usr`, an `.rpm` under
+// `/usr` and a Flatpak under `/app` (ADR 0024 § 3) — a baked path would force a
+// payload per format and collapse the whole design back into N packagers.
+//
+// `XDG_DATA_DIRS` is prepended for the same reason. Under `/usr` it is already
+// on the list and the line is a no-op; installed anywhere else (`/opt`, a
+// `--prefix=$HOME/.local` tree, a relocated Flatpak) it is what makes the
+// staged icons, the desktop entry and the compiled GSettings schemas findable.
+// Getting that from the launcher rather than from the app keeps the app free of
+// install-layout knowledge.
+/** POSIX-shell single-quote: the only escape inside `'…'` is `'\''`. */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Render the launcher for a GJS application.
+ *
+ * `bundleRelPath` is the bundle's path inside `lib/<binaryName>/`.
+ */
+export function renderLauncher(settings, bundleRelPath) {
+    const lib = `"$prefix"/lib/${settings.binaryName}`;
+    const args = settings.execArgs.map(shellQuote).join(' ');
+    return [
+        '#!/bin/sh',
+        '# Generated by `gjsify ship` — do not edit.',
+        'set -e',
+        'self=$(readlink -f "$0")',
+        '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');
+}

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

@@ -0,0 +1,30 @@
+/** One file in the payload, with its bytes. */
+export interface PayloadEntry {
+    /** Prefix-relative path, POSIX-separated, e.g. `bin/learn6502`. */
+    path: string;
+    /** POSIX mode bits. */
+    mode: number;
+    data: Uint8Array;
+}
+/**
+ * The build stamp every header gets.
+ *
+ * `SOURCE_DATE_EPOCH` is the cross-ecosystem convention and wins when it is
+ * set. Without it the stamp is the BUNDLE's mtime — never `Date.now()`, which
+ * is the one input guaranteeing that packing the same tree twice produces
+ * different bytes, and never a fixed 0 either: `Build Date: 1 Jan 1970` is
+ * what `rpm -qi` then shows a user, and an artifact that looks broken is a
+ * support question. The mtime keeps the property that matters (pack the same
+ * build twice, get the same bytes) while saying something true.
+ */
+export declare function buildTimestamp(bundlePath: string, env?: Record<string, string | undefined>): number;
+/**
+ * Does the payload contain anything architecture-specific?
+ *
+ * Decided from the file's MAGIC, not from its name. A bundled runtime is just
+ * called `node`, a stripped helper may have no extension at all, and an
+ * extension list that misses one of them produces `Architecture: all` on an
+ * x86-64 payload — which apt and dnf will happily install on arm64, where it
+ * does not run.
+ */
+export declare function isArchIndependent(payload: readonly PayloadEntry[]): boolean;

package/lib/utils/ship/payload.js

@@ -0,0 +1,59 @@
+// The payload the packers see.
+//
+// One shape, read back off the staged tree rather than carried in memory from
+// the planner. That is deliberate: it makes `gjsify ship --stage` and
+// `gjsify ship --target deb` provably the same payload, because the second
+// reads what the first wrote. A packer fed straight from the planner could
+// drift from the staged tree and nothing would notice.
+import { statSync } from 'node:fs';
+/**
+ * The build stamp every header gets.
+ *
+ * `SOURCE_DATE_EPOCH` is the cross-ecosystem convention and wins when it is
+ * set. Without it the stamp is the BUNDLE's mtime — never `Date.now()`, which
+ * is the one input guaranteeing that packing the same tree twice produces
+ * different bytes, and never a fixed 0 either: `Build Date: 1 Jan 1970` is
+ * what `rpm -qi` then shows a user, and an artifact that looks broken is a
+ * support question. The mtime keeps the property that matters (pack the same
+ * build twice, get the same bytes) while saying something true.
+ */
+export function buildTimestamp(bundlePath, env = process.env) {
+    const raw = env.SOURCE_DATE_EPOCH;
+    if (raw !== undefined) {
+        const parsed = Number(raw);
+        if (!Number.isInteger(parsed) || parsed < 0) {
+            throw new Error(`gjsify ship: SOURCE_DATE_EPOCH must be a non-negative integer, got "${raw}".`);
+        }
+        return parsed;
+    }
+    return Math.floor(statSync(bundlePath).mtimeMs / 1000);
+}
+/**
+ * Does the payload contain anything architecture-specific?
+ *
+ * Decided from the file's MAGIC, not from its name. A bundled runtime is just
+ * called `node`, a stripped helper may have no extension at all, and an
+ * extension list that misses one of them produces `Architecture: all` on an
+ * x86-64 payload — which apt and dnf will happily install on arm64, where it
+ * does not run.
+ */
+export function isArchIndependent(payload) {
+    return !payload.some((entry) => isNativeBinary(entry.data));
+}
+/** ELF, Mach-O (both endiannesses, both widths, and a fat archive) or PE. */
+function isNativeBinary(data) {
+    if (data.byteLength < 4)
+        return false;
+    const magic = (data[0] << 24) | (data[1] << 16) | (data[2] << 8) | data[3];
+    switch (magic >>> 0) {
+        case 0x7f454c46: // \x7fELF
+        case 0xfeedface: // Mach-O 32
+        case 0xfeedfacf: // Mach-O 64
+        case 0xcefaedfe: // Mach-O 32, byte-swapped
+        case 0xcffaedfe: // Mach-O 64, byte-swapped
+        case 0xcafebabe: // Mach-O universal binary
+            return true;
+        default:
+            return data[0] === 0x4d && data[1] === 0x5a; // MZ — PE/COFF
+    }
+}