@gjsify/cli 0.39.0 → 0.41.0

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
+    }
+}

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

@@ -0,0 +1,34 @@
+import type { FormatDescriptor, ShipSettings, StagedFile } from './types.js';
+/** Everything the planner needs that it cannot derive from the settings alone. */
+export interface StageInputs {
+    /** Paths inside `settings.bundleDir`, relative and POSIX-separated. */
+    bundleFiles: readonly string[];
+    /** The rendered launcher script. */
+    launcher: string;
+    /** The rendered AppStream MetaInfo XML. */
+    metainfo: string;
+    /** The rendered desktop entry — required for `kind: 'app'`, unused for `'cli'`. */
+    desktopEntry?: string;
+    /** Contents of the project's licence file, when one was found. */
+    licenseText?: string;
+}
+/**
+ * Build the prefix-relative payload.
+ *
+ * The result is deduplicated by path (last write wins, so `extraFiles` can
+ * override anything the defaults staged) and sorted, which makes the tree —
+ * and therefore every artifact built from it — deterministic.
+ */
+export declare function planStage(settings: ShipSettings, inputs: StageInputs): StagedFile[];
+/**
+ * The per-format additions. Only the licence differs today, and it differs in
+ * BOTH place and shape: Debian policy wants a machine-readable `copyright` in
+ * `share/doc/<pkg>/`, RPM wants the licence text under `share/licenses/<pkg>/`.
+ */
+export declare function planOverlay(settings: ShipSettings, format: FormatDescriptor, inputs: StageInputs): StagedFile[];
+/**
+ * The hicolor subdirectory for an icon: `scalable` for SVG, otherwise the
+ * pixel size read from a `<n>x<n>` path component or a trailing number in the
+ * filename.
+ */
+export declare function iconSizeDir(iconPath: string): string;

package/lib/utils/ship/plan.js

@@ -0,0 +1,167 @@
+// Which file lands where — decided without touching the filesystem, so every
+// case (including the ones that must be REFUSED) is unit-testable. Same split
+// as `utils/copy-targets.ts`, and for the same reason: a stager that discovers
+// its own inputs can only be tested by building a real project.
+import { basename, extname, posix } from 'node:path';
+/**
+ * Build the prefix-relative payload.
+ *
+ * The result is deduplicated by path (last write wins, so `extraFiles` can
+ * override anything the defaults staged) and sorted, which makes the tree —
+ * and therefore every artifact built from it — deterministic.
+ */
+export function planStage(settings, inputs) {
+    const files = [];
+    const libDir = `lib/${settings.binaryName}`;
+    files.push({ path: `bin/${settings.binaryName}`, mode: 0o755, source: { kind: 'text', text: inputs.launcher } });
+    for (const rel of inputs.bundleFiles) {
+        files.push({
+            path: posix.join(libDir, rel),
+            mode: isExecutableAsset(rel) ? 0o755 : 0o644,
+            source: { kind: 'file', path: posix.join(settings.bundleDir, rel) },
+        });
+    }
+    files.push({
+        path: `share/metainfo/${settings.appId}.metainfo.xml`,
+        mode: 0o644,
+        source: { kind: 'text', text: inputs.metainfo },
+    });
+    if (settings.kind === 'app') {
+        if (inputs.desktopEntry === undefined) {
+            throw new Error('gjsify ship: internal error — a desktop entry is required for `kind: "app"`.');
+        }
+        files.push({
+            path: `share/applications/${settings.appId}.desktop`,
+            mode: 0o644,
+            source: { kind: 'text', text: inputs.desktopEntry },
+        });
+        for (const icon of planIcons(settings))
+            files.push(icon);
+    }
+    for (const schema of settings.schemaFiles) {
+        const name = basename(schema);
+        // Every installed schema shares ONE system directory
+        // (`/usr/share/glib-2.0/schemas`), so a generic name is a collision
+        // with whatever else the distro installed there — and the loser is
+        // decided by install order.
+        if (!name.startsWith(settings.appId)) {
+            throw new Error(`gjsify ship: the GSettings schema ${name} must be named \`${settings.appId}[.…].gschema.xml\`. ` +
+                'Every installed schema shares one system directory, so the app id is what keeps it unique.');
+        }
+        files.push({
+            path: `share/glib-2.0/schemas/${name}`,
+            mode: 0o644,
+            source: { kind: 'file', path: schema },
+        });
+    }
+    for (const [dest, source] of Object.entries(settings.extraFiles)) {
+        files.push({ path: assertInsidePrefix(dest), mode: 0o644, source: { kind: 'file', path: source } });
+    }
+    return normalise(files);
+}
+/**
+ * The per-format additions. Only the licence differs today, and it differs in
+ * BOTH place and shape: Debian policy wants a machine-readable `copyright` in
+ * `share/doc/<pkg>/`, RPM wants the licence text under `share/licenses/<pkg>/`.
+ */
+export function planOverlay(settings, format, inputs) {
+    if (inputs.licenseText === undefined)
+        return [];
+    const text = format.licenseKind === 'debian-copyright'
+        ? renderDebianCopyright(settings, inputs.licenseText)
+        : inputs.licenseText;
+    return [{ path: format.licenseDest(settings.binaryName), mode: 0o644, source: { kind: 'text', text } }];
+}
+/**
+ * Debian machine-readable copyright, format 1.0. The licence text is indented
+ * by one space and its blank lines become ` .` — a bare blank line ends the
+ * field, which silently truncates the licence to its first paragraph.
+ */
+function renderDebianCopyright(settings, licenseText) {
+    const body = licenseText
+        .trimEnd()
+        .split('\n')
+        .map((line) => (line.trim() === '' ? ' .' : ` ${line}`))
+        .join('\n');
+    return [
+        'Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/',
+        `Upstream-Name: ${settings.name}`,
+        ...(settings.homepage ? [`Source: ${settings.homepage}`] : []),
+        '',
+        'Files: *',
+        `Copyright: ${settings.maintainer}`,
+        `License: ${settings.license}`,
+        body,
+        '',
+    ].join('\n');
+}
+/**
+ * Icons land in the hicolor theme, named after the app id — that name is what
+ * the desktop entry's `Icon=` and the MetaInfo `<id>` both point at, so a file
+ * keeping its source basename installs an icon nothing ever looks up.
+ */
+function planIcons(settings) {
+    const out = [];
+    const seen = new Map();
+    for (const icon of settings.iconFiles) {
+        const ext = extname(icon);
+        const dir = iconSizeDir(icon);
+        const path = `share/icons/hicolor/${dir}/apps/${settings.appId}${ext}`;
+        const previous = seen.get(path);
+        if (previous !== undefined) {
+            throw new Error(`gjsify ship: ${icon} and ${previous} both install as ${path}. ` +
+                'Icon size is read from the path (`.../128x128/...`) or the filename (`icon-128.png`); ' +
+                'give them distinguishable sizes or point `gjsify.ship.icon` at a single file.');
+        }
+        seen.set(path, icon);
+        out.push({ path, mode: 0o644, source: { kind: 'file', path: icon } });
+    }
+    return out;
+}
+/**
+ * The hicolor subdirectory for an icon: `scalable` for SVG, otherwise the
+ * pixel size read from a `<n>x<n>` path component or a trailing number in the
+ * filename.
+ */
+export function iconSizeDir(iconPath) {
+    if (extname(iconPath).toLowerCase() === '.svg')
+        return 'scalable';
+    const square = /(?:^|[\\/])(\d{1,4})x\1(?:[\\/]|$)/.exec(iconPath);
+    if (square)
+        return `${square[1]}x${square[1]}`;
+    const tokens = basename(iconPath, extname(iconPath)).split(/[-_.]/);
+    for (let i = tokens.length - 1; i >= 0; i--) {
+        const token = tokens[i];
+        if (token !== undefined && /^\d{1,4}$/.test(token))
+            return `${token}x${token}`;
+    }
+    throw new Error(`gjsify ship: cannot tell what size ${iconPath} is. ` +
+        'Put it in a `<size>x<size>/` directory, end its name with the size (`icon-128.png`), or ship an SVG.');
+}
+/** A staged path must stay under the prefix — no absolute paths, no `..`. */
+function assertInsidePrefix(dest) {
+    const normalised = posix.normalize(dest);
+    if (posix.isAbsolute(normalised) || normalised === '..' || normalised.startsWith('../')) {
+        throw new Error(`gjsify ship: \`gjsify.ship.extraFiles\` destination "${dest}" escapes the install prefix. ` +
+            'Destinations are relative to the prefix, e.g. `share/applications/extra.desktop`.');
+    }
+    return normalised;
+}
+/**
+ * A native module inside the payload has to keep its executable bit.
+ *
+ * By NAME here, unlike `isArchIndependent`, which reads the file's magic: the
+ * planner is pure and has no bytes to look at. The two answer different
+ * questions — "should this be 0755" versus "is this package portable" — and
+ * getting this one wrong costs a mode bit, not an unusable package.
+ */
+function isExecutableAsset(rel) {
+    return /\.(so|node|dylib)(\.\d+)*$/.test(rel);
+}
+/** Last write wins, then sort — deterministic output for a deterministic artifact. */
+function normalise(files) {
+    const byPath = new Map();
+    for (const file of files)
+        byPath.set(file.path, file);
+    return [...byPath.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}

package/lib/utils/ship/rpm-header.d.ts

@@ -0,0 +1,29 @@
+export declare const RPM_TAG_HEADERSIGNATURES = 62;
+export declare const RPM_TAG_HEADERIMMUTABLE = 63;
+export declare enum RpmType {
+    INT16 = 3,
+    INT32 = 4,
+    STRING = 6,
+    BIN = 7,
+    STRING_ARRAY = 8,
+    I18NSTRING = 9
+}
+export type RpmValue = string | string[] | number | number[] | Uint8Array;
+export interface RpmEntry {
+    tag: number;
+    type: RpmType;
+    value: RpmValue;
+}
+/** Build a complete header blob, magic included. */
+export declare function buildRpmHeader(entries: readonly RpmEntry[], regionTag: number): Uint8Array;
+/**
+ * The 96-byte lead.
+ *
+ * Legacy: modern rpm validates the magic and the major version and takes
+ * everything else from the headers, which is why the name field is allowed to
+ * be truncated. It is written because the magic is how `file(1)`, and rpm's
+ * own first read, recognise the format at all.
+ */
+export declare function buildRpmLead(nevr: string): Uint8Array;
+/** Pad a signature header to the 8-byte boundary the main header starts on. */
+export declare function padToEight(bytes: Uint8Array): Uint8Array;

package/lib/utils/ship/rpm-header.js

@@ -0,0 +1,170 @@
+// The RPM header structure — an index of typed entries over a shared store.
+//
+// Both headers in an RPM (the signature and the main one) are this same
+// structure, which is why it is its own module: `rpm.ts` decides WHICH tags to
+// write, this file decides how a header is spelled.
+//
+// The one genuinely surprising part is the REGION. `rpm` does not read the
+// index as a flat list: the first index entry is a region trailer pointer with
+// tag 62 (signatures) or 63 (immutable), whose store payload is a second,
+// 16-byte index entry carrying a NEGATIVE offset — the byte distance back to
+// the start of the index. Getting that offset wrong does not corrupt anything
+// visibly; `rpm -qp` simply reports "region trailer" errors or silently sees a
+// header with no tags in it.
+const HEADER_MAGIC = Uint8Array.from([0x8e, 0xad, 0xe8, 0x01, 0x00, 0x00, 0x00, 0x00]);
+const INDEX_ENTRY_SIZE = 16;
+/** The region trailer is one index entry, and rpm checks the count literally. */
+const REGION_COUNT = 16;
+export const RPM_TAG_HEADERSIGNATURES = 62;
+export const RPM_TAG_HEADERIMMUTABLE = 63;
+export var RpmType;
+(function (RpmType) {
+    RpmType[RpmType["INT16"] = 3] = "INT16";
+    RpmType[RpmType["INT32"] = 4] = "INT32";
+    RpmType[RpmType["STRING"] = 6] = "STRING";
+    RpmType[RpmType["BIN"] = 7] = "BIN";
+    RpmType[RpmType["STRING_ARRAY"] = 8] = "STRING_ARRAY";
+    RpmType[RpmType["I18NSTRING"] = 9] = "I18NSTRING";
+})(RpmType || (RpmType = {}));
+/** Store alignment per type — rpm reads INT32s with an aligned load. */
+const ALIGNMENT = {
+    [RpmType.INT16]: 2,
+    [RpmType.INT32]: 4,
+    [RpmType.STRING]: 1,
+    [RpmType.BIN]: 1,
+    [RpmType.STRING_ARRAY]: 1,
+    [RpmType.I18NSTRING]: 1,
+};
+/** Build a complete header blob, magic included. */
+export function buildRpmHeader(entries, regionTag) {
+    // rpm expects the index sorted by tag; the store is laid out in the same
+    // order, which is not required but makes a hexdump readable next to a real
+    // package's.
+    const sorted = [...entries].sort((a, b) => a.tag - b.tag);
+    const index = [];
+    const chunks = [];
+    let storeSize = 0;
+    for (const entry of sorted) {
+        if (entry.tag < 100) {
+            throw new Error(`gjsify ship: rpm tag ${entry.tag} is below 100 and would be rejected by hdrchkTag.`);
+        }
+        const { data, count } = encodeValue(entry.type, entry.value, entry.tag);
+        const alignment = ALIGNMENT[entry.type];
+        const padding = (alignment - (storeSize % alignment)) % alignment;
+        if (padding > 0) {
+            chunks.push(new Uint8Array(padding));
+            storeSize += padding;
+        }
+        index.push({ tag: entry.tag, type: entry.type, offset: storeSize, count });
+        chunks.push(data);
+        storeSize += data.byteLength;
+    }
+    const trailerOffset = storeSize;
+    const indexCount = index.length + 1; // the region entry counts itself
+    chunks.push(indexEntry(regionTag, RpmType.BIN, -(INDEX_ENTRY_SIZE * indexCount), REGION_COUNT));
+    storeSize += INDEX_ENTRY_SIZE;
+    const header = new Uint8Array(HEADER_MAGIC.byteLength + 8 + indexCount * INDEX_ENTRY_SIZE + storeSize);
+    const view = new DataView(header.buffer);
+    header.set(HEADER_MAGIC, 0);
+    view.setUint32(8, indexCount);
+    view.setUint32(12, storeSize);
+    let offset = 16;
+    header.set(indexEntry(regionTag, RpmType.BIN, trailerOffset, REGION_COUNT), offset);
+    offset += INDEX_ENTRY_SIZE;
+    for (const item of index) {
+        header.set(indexEntry(item.tag, item.type, item.offset, item.count), offset);
+        offset += INDEX_ENTRY_SIZE;
+    }
+    for (const chunk of chunks) {
+        header.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return header;
+}
+function indexEntry(tag, type, offset, count) {
+    const bytes = new Uint8Array(INDEX_ENTRY_SIZE);
+    const view = new DataView(bytes.buffer);
+    view.setInt32(0, tag);
+    view.setInt32(4, type);
+    view.setInt32(8, offset);
+    view.setInt32(12, count);
+    return bytes;
+}
+function encodeValue(type, value, tag) {
+    const encoder = new TextEncoder();
+    switch (type) {
+        case RpmType.STRING: {
+            if (typeof value !== 'string')
+                throw typeMismatch(tag, 'a string');
+            return { data: encoder.encode(`${value}\0`), count: 1 };
+        }
+        case RpmType.STRING_ARRAY:
+        case RpmType.I18NSTRING: {
+            const list = typeof value === 'string' ? [value] : value;
+            if (!Array.isArray(list))
+                throw typeMismatch(tag, 'a string array');
+            // rpm rejects a zero count, so an empty array is a bug rather than
+            // "no value" — the caller must omit the tag instead.
+            if (list.length === 0)
+                throw new Error(`gjsify ship: rpm tag ${tag} has an empty array; omit it instead.`);
+            return { data: encoder.encode(list.map((item) => `${item}\0`).join('')), count: list.length };
+        }
+        case RpmType.BIN: {
+            if (!(value instanceof Uint8Array))
+                throw typeMismatch(tag, 'binary data');
+            return { data: value, count: value.byteLength };
+        }
+        case RpmType.INT16:
+        case RpmType.INT32: {
+            const list = typeof value === 'number' ? [value] : value;
+            if (!Array.isArray(list))
+                throw typeMismatch(tag, 'a number array');
+            if (list.length === 0)
+                throw new Error(`gjsify ship: rpm tag ${tag} has an empty array; omit it instead.`);
+            const width = type === RpmType.INT16 ? 2 : 4;
+            const data = new Uint8Array(list.length * width);
+            const view = new DataView(data.buffer);
+            list.forEach((item, i) => {
+                if (type === RpmType.INT16)
+                    view.setUint16(i * width, item & 0xffff);
+                else
+                    view.setUint32(i * width, item >>> 0);
+            });
+            return { data, count: list.length };
+        }
+    }
+}
+function typeMismatch(tag, expected) {
+    return new Error(`gjsify ship: internal error — rpm tag ${tag} expects ${expected}.`);
+}
+/**
+ * The 96-byte lead.
+ *
+ * Legacy: modern rpm validates the magic and the major version and takes
+ * everything else from the headers, which is why the name field is allowed to
+ * be truncated. It is written because the magic is how `file(1)`, and rpm's
+ * own first read, recognise the format at all.
+ */
+export function buildRpmLead(nevr) {
+    const lead = new Uint8Array(96);
+    const view = new DataView(lead.buffer);
+    lead.set([0xed, 0xab, 0xee, 0xdb], 0);
+    lead[4] = 3; // major
+    lead[5] = 0; // minor
+    view.setInt16(6, 0); // type: binary package
+    view.setInt16(8, 0); // archnum — informational; the header's ARCH is authoritative
+    const name = new TextEncoder().encode(nevr).slice(0, 65);
+    lead.set(name, 10);
+    view.setInt16(76, 0); // osnum — same story as archnum
+    view.setInt16(78, 5); // signature type: header-style signatures
+    return lead;
+}
+/** Pad a signature header to the 8-byte boundary the main header starts on. */
+export function padToEight(bytes) {
+    const padding = (8 - (bytes.byteLength % 8)) % 8;
+    if (padding === 0)
+        return bytes;
+    const out = new Uint8Array(bytes.byteLength + padding);
+    out.set(bytes, 0);
+    return out;
+}

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

@@ -0,0 +1,12 @@
+import type { PayloadEntry } from './payload.js';
+import type { ShipSettings } from './types.js';
+export interface RpmInputs {
+    settings: ShipSettings;
+    payload: readonly PayloadEntry[];
+    prefix: string;
+    depends: readonly string[];
+    /** RPM architecture (`x86_64`, `noarch`, …). */
+    archLabel: string;
+    mtime: number;
+}
+export declare function buildRpm(inputs: RpmInputs): Promise<Uint8Array>;