@gjsify/cli 0.39.0 → 0.40.0

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>;