@gjsify/cli 0.39.0 → 0.40.0

package/lib/utils/ship/rpm.js

@@ -0,0 +1,377 @@
+// The `.rpm` packer.
+//
+// Hand-written for the same reason as the `.deb` one, and with a better
+// oracle: `rpm` itself is on every Fedora image this project's CI runs on, and
+// it is a strict, independent parser. `rpm -qp --info`, `rpm -qpl`,
+// `rpm -qp --requires` and `rpm -K` between them read the lead, both headers,
+// every tag this file writes and the payload digest — so the e2e suite checks
+// the artifact with code that shares nothing with the writer.
+//
+// `rpmbuild` was the alternative and is the wrong dependency: it is not in the
+// CI image, adding it there would gate this PR on an image rebuild, and it
+// cannot run under GJS at all. What it would have bought is the header
+// encoding in `rpm-header.ts`, which is 180 lines.
+import { createHash } from 'node:crypto';
+import { concatBytes } from './bytes.js';
+import { createCpioArchive, S_IFDIR, S_IFREG } from './cpio.js';
+import { parseDepend } from './depends.js';
+import { buildRpmHeader, buildRpmLead, padToEight, RpmType, RPM_TAG_HEADERIMMUTABLE, RPM_TAG_HEADERSIGNATURES, } from './rpm-header.js';
+import { gzipDeterministic } from './gzip.js';
+import { renderRpmScriptlets } from './scripts.js';
+// Header tags. Named rather than inlined because a wrong NUMBER produces a
+// package that parses and is quietly wrong, which is the hardest kind to spot.
+const TAG = {
+    HEADERI18NTABLE: 100,
+    NAME: 1000,
+    VERSION: 1001,
+    RELEASE: 1002,
+    SUMMARY: 1004,
+    DESCRIPTION: 1005,
+    BUILDTIME: 1006,
+    BUILDHOST: 1007,
+    SIZE: 1009,
+    LICENSE: 1014,
+    GROUP: 1016,
+    URL: 1020,
+    OS: 1021,
+    ARCH: 1022,
+    POSTIN: 1024,
+    POSTUN: 1026,
+    FILESIZES: 1028,
+    FILEMODES: 1030,
+    FILERDEVS: 1033,
+    FILEMTIMES: 1034,
+    FILEDIGESTS: 1035,
+    FILELINKTOS: 1036,
+    FILEFLAGS: 1037,
+    FILEUSERNAME: 1039,
+    FILEGROUPNAME: 1040,
+    SOURCERPM: 1044,
+    FILEVERIFYFLAGS: 1045,
+    PROVIDENAME: 1047,
+    REQUIREFLAGS: 1048,
+    REQUIRENAME: 1049,
+    REQUIREVERSION: 1050,
+    RPMVERSION: 1064,
+    POSTINPROG: 1086,
+    POSTUNPROG: 1088,
+    FILEDEVICES: 1095,
+    FILEINODES: 1096,
+    FILELANGS: 1097,
+    PROVIDEFLAGS: 1112,
+    PROVIDEVERSION: 1113,
+    DIRINDEXES: 1116,
+    BASENAMES: 1117,
+    DIRNAMES: 1118,
+    PAYLOADFORMAT: 1124,
+    PAYLOADCOMPRESSOR: 1125,
+    PAYLOADFLAGS: 1126,
+    FILEDIGESTALGO: 5011,
+    ENCODING: 5062,
+    PAYLOADDIGEST: 5092,
+    PAYLOADDIGESTALGO: 5093,
+    PAYLOADDIGESTALT: 5097,
+};
+const SIGTAG = { SIZE: 1000, MD5: 1004, PAYLOADSIZE: 1007, SHA1HEADER: 269, SHA256HEADER: 273 };
+const SENSE = {
+    LESS: 1 << 1,
+    GREATER: 1 << 2,
+    EQUAL: 1 << 3,
+    INTERP: 1 << 8,
+    SCRIPT_POST: 1 << 10,
+    SCRIPT_POSTUN: 1 << 12,
+    RPMLIB: 1 << 24,
+};
+/** SHA-256 in rpm's digest-algorithm numbering (PGP hash algorithm ids). */
+const DIGEST_ALGO_SHA256 = 8;
+/**
+ * The rpmlib features this writer's output depends on.
+ *
+ * These are not optional decoration: `CompressedFileNames` is what declares
+ * the DIRNAMES/BASENAMES/DIRINDEXES split, `FileDigests` that FILEDIGESTS is
+ * a digest rather than an MD5, and `PayloadFilesHavePrefix` that the cpio
+ * names carry a `./`. An rpm too old for one of them must refuse the package
+ * rather than misread it.
+ */
+const RPMLIB_REQUIRES = [
+    ['rpmlib(CompressedFileNames)', '3.0.4-1'],
+    ['rpmlib(FileDigests)', '4.6.0-1'],
+    ['rpmlib(PayloadFilesHavePrefix)', '4.0-1'],
+];
+/**
+ * Directories a base system already owns.
+ *
+ * An rpm that claims nothing leaves its own `/usr/lib/<app>` unowned, which
+ * `rpm -e` then leaves behind. Listing the base-system directories it must not
+ * claim is the middle ground.
+ *
+ * Deliberately not exhaustive, and that is affordable: rpm treats directory
+ * CO-ownership as normal (`rpm -qf /usr/share/icons/hicolor` names three
+ * packages on this machine), so a directory missing from this list costs
+ * rpmlint noise, not a broken install. The entries that matter are the ones a
+ * package would otherwise claim on every install.
+ */
+const SYSTEM_OWNED_DIRECTORIES = new Set([
+    '/usr',
+    '/usr/bin',
+    '/usr/lib',
+    '/usr/lib64',
+    '/usr/libexec',
+    '/usr/sbin',
+    '/usr/share',
+    '/usr/share/applications',
+    '/usr/share/doc',
+    '/usr/share/icons',
+    '/usr/share/licenses',
+    '/usr/share/man',
+    '/usr/share/metainfo',
+    // Owned by glib2 — an app that installs a schema must not claim the
+    // directory the whole system's schemas live in. Verified with `rpm -qf`.
+    '/usr/share/glib-2.0',
+    '/usr/share/glib-2.0/schemas',
+    '/etc',
+    '/opt',
+    '/var',
+]);
+export async function buildRpm(inputs) {
+    const { settings, mtime } = inputs;
+    const prefix = `/${inputs.prefix.replace(/^\/+|\/+$/g, '')}`;
+    const files = collectFiles(inputs, prefix);
+    const cpio = createCpioArchive(files.map((file, index) => ({
+        name: `.${file.path}`,
+        mode: file.mode,
+        data: file.data,
+        mtime,
+        ino: index + 1,
+    })));
+    const compressed = await gzipDeterministic(cpio);
+    const header = buildRpmHeader(mainHeaderEntries(inputs, files, cpio, compressed), RPM_TAG_HEADERIMMUTABLE);
+    const body = concatBytes([header, compressed]);
+    const signature = padToEight(buildRpmHeader([
+        { tag: SIGTAG.SHA1HEADER, type: RpmType.STRING, value: hashHex('sha1', header) },
+        { tag: SIGTAG.SHA256HEADER, type: RpmType.STRING, value: hashHex('sha256', header) },
+        { tag: SIGTAG.SIZE, type: RpmType.INT32, value: [body.byteLength] },
+        { tag: SIGTAG.MD5, type: RpmType.BIN, value: hashBytes('md5', body) },
+        { tag: SIGTAG.PAYLOADSIZE, type: RpmType.INT32, value: [cpio.byteLength] },
+    ], RPM_TAG_HEADERSIGNATURES));
+    const lead = buildRpmLead(`${settings.binaryName}-${settings.version}-${settings.release}`);
+    return concatBytes([lead, signature, body]);
+}
+/** The payload plus the directories this package should own, in install order. */
+function collectFiles(inputs, prefix) {
+    const files = inputs.payload.map((entry) => {
+        if (entry.data.byteLength > 0xffffffff) {
+            throw new Error(`gjsify ship: ${entry.path} is larger than 4 GiB, which needs rpm's LONGFILESIZES tag. ` +
+                'That is not implemented — split the payload.');
+        }
+        return {
+            path: `${prefix}/${entry.path}`,
+            mode: S_IFREG | (entry.mode & 0o7777),
+            data: entry.data,
+            isDirectory: false,
+        };
+    });
+    const owned = new Set();
+    for (const file of files) {
+        const parts = file.path.split('/').slice(1);
+        parts.pop();
+        let current = '';
+        for (const part of parts) {
+            current = `${current}/${part}`;
+            if (!SYSTEM_OWNED_DIRECTORIES.has(current))
+                owned.add(current);
+        }
+    }
+    for (const directory of owned) {
+        files.push({ path: directory, mode: S_IFDIR | 0o755, data: new Uint8Array(0), isDirectory: true });
+    }
+    // rpm reads the file list positionally across a dozen parallel arrays, so
+    // ONE order has to serve all of them; sorting here is what guarantees a
+    // directory is listed before what lives in it.
+    return files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+function mainHeaderEntries(inputs, files, cpio, compressed) {
+    const { settings } = inputs;
+    const evr = `${settings.version}-${settings.release}`;
+    const dirNames = [];
+    const dirIndexes = [];
+    const baseNames = [];
+    for (const file of files) {
+        const slash = file.path.lastIndexOf('/');
+        const dir = `${file.path.slice(0, slash)}/`;
+        let index = dirNames.indexOf(dir);
+        if (index === -1)
+            index = dirNames.push(dir) - 1;
+        dirIndexes.push(index);
+        baseNames.push(file.path.slice(slash + 1));
+    }
+    const scripts = renderRpmScriptlets(settings, inputs.prefix);
+    const requires = buildRequires(inputs.depends, scripts);
+    const entries = [
+        { tag: TAG.HEADERI18NTABLE, type: RpmType.STRING_ARRAY, value: ['C'] },
+        { tag: TAG.NAME, type: RpmType.STRING, value: settings.binaryName },
+        { tag: TAG.VERSION, type: RpmType.STRING, value: settings.version },
+        { tag: TAG.RELEASE, type: RpmType.STRING, value: settings.release },
+        { tag: TAG.SUMMARY, type: RpmType.I18NSTRING, value: [settings.summary] },
+        { tag: TAG.DESCRIPTION, type: RpmType.I18NSTRING, value: [settings.description.join('\n\n')] },
+        { tag: TAG.BUILDTIME, type: RpmType.INT32, value: [inputs.mtime] },
+        // Not the real hostname: it would put the build machine's name in
+        // every artifact and make two builds of the same source differ.
+        { tag: TAG.BUILDHOST, type: RpmType.STRING, value: 'localhost' },
+        {
+            tag: TAG.SIZE,
+            type: RpmType.INT32,
+            value: [files.reduce((total, file) => total + file.data.byteLength, 0)],
+        },
+        { tag: TAG.LICENSE, type: RpmType.STRING, value: settings.license },
+        { tag: TAG.GROUP, type: RpmType.I18NSTRING, value: [settings.group] },
+        { tag: TAG.OS, type: RpmType.STRING, value: 'linux' },
+        { tag: TAG.ARCH, type: RpmType.STRING, value: inputs.archLabel },
+        { tag: TAG.SOURCERPM, type: RpmType.STRING, value: `${settings.binaryName}-${evr}.src.rpm` },
+        { tag: TAG.RPMVERSION, type: RpmType.STRING, value: '4.20.0' },
+        { tag: TAG.ENCODING, type: RpmType.STRING, value: 'utf-8' },
+        { tag: TAG.FILESIZES, type: RpmType.INT32, value: files.map((file) => file.data.byteLength) },
+        { tag: TAG.FILEMODES, type: RpmType.INT16, value: files.map((file) => file.mode) },
+        { tag: TAG.FILERDEVS, type: RpmType.INT16, value: files.map(() => 0) },
+        { tag: TAG.FILEMTIMES, type: RpmType.INT32, value: files.map(() => inputs.mtime) },
+        {
+            tag: TAG.FILEDIGESTS,
+            type: RpmType.STRING_ARRAY,
+            // A directory has no contents to digest, and rpm expects the empty
+            // string there rather than the digest of zero bytes.
+            value: files.map((file) => (file.isDirectory ? '' : hashHex('sha256', file.data))),
+        },
+        { tag: TAG.FILELINKTOS, type: RpmType.STRING_ARRAY, value: files.map(() => '') },
+        { tag: TAG.FILEFLAGS, type: RpmType.INT32, value: files.map(() => 0) },
+        { tag: TAG.FILEUSERNAME, type: RpmType.STRING_ARRAY, value: files.map(() => 'root') },
+        { tag: TAG.FILEGROUPNAME, type: RpmType.STRING_ARRAY, value: files.map(() => 'root') },
+        { tag: TAG.FILEVERIFYFLAGS, type: RpmType.INT32, value: files.map(() => 0xffffffff) },
+        { tag: TAG.FILEDEVICES, type: RpmType.INT32, value: files.map(() => 1) },
+        { tag: TAG.FILEINODES, type: RpmType.INT32, value: files.map((_, index) => index + 1) },
+        { tag: TAG.FILELANGS, type: RpmType.STRING_ARRAY, value: files.map(() => '') },
+        { tag: TAG.FILEDIGESTALGO, type: RpmType.INT32, value: [DIGEST_ALGO_SHA256] },
+        { tag: TAG.DIRINDEXES, type: RpmType.INT32, value: dirIndexes },
+        { tag: TAG.BASENAMES, type: RpmType.STRING_ARRAY, value: baseNames },
+        { tag: TAG.DIRNAMES, type: RpmType.STRING_ARRAY, value: dirNames },
+        { tag: TAG.PROVIDENAME, type: RpmType.STRING_ARRAY, value: [settings.binaryName] },
+        { tag: TAG.PROVIDEFLAGS, type: RpmType.INT32, value: [SENSE.EQUAL] },
+        { tag: TAG.PROVIDEVERSION, type: RpmType.STRING_ARRAY, value: [evr] },
+        { tag: TAG.REQUIRENAME, type: RpmType.STRING_ARRAY, value: requires.names },
+        { tag: TAG.REQUIREFLAGS, type: RpmType.INT32, value: requires.flags },
+        { tag: TAG.REQUIREVERSION, type: RpmType.STRING_ARRAY, value: requires.versions },
+        { tag: TAG.PAYLOADFORMAT, type: RpmType.STRING, value: 'cpio' },
+        { tag: TAG.PAYLOADCOMPRESSOR, type: RpmType.STRING, value: 'gzip' },
+        // Write-side metadata only — no reader acts on it (rpm-format.md § 6.5).
+        // `9` is what rpmbuild writes; the Web `CompressionStream` this packer
+        // uses exposes no level to report, so the honest reading of this field
+        // is "gzip, default settings" rather than a measured level.
+        { tag: TAG.PAYLOADFLAGS, type: RpmType.STRING, value: '9' },
+        { tag: TAG.PAYLOADDIGEST, type: RpmType.STRING_ARRAY, value: [hashHex('sha256', compressed)] },
+        { tag: TAG.PAYLOADDIGESTALGO, type: RpmType.INT32, value: [DIGEST_ALGO_SHA256] },
+        { tag: TAG.PAYLOADDIGESTALT, type: RpmType.STRING_ARRAY, value: [hashHex('sha256', cpio)] },
+    ];
+    assertParallelFileArrays(entries, files.length);
+    if (settings.homepage)
+        entries.push({ tag: TAG.URL, type: RpmType.STRING, value: settings.homepage });
+    if (scripts.post !== undefined) {
+        entries.push({ tag: TAG.POSTIN, type: RpmType.STRING, value: scripts.post });
+        entries.push({ tag: TAG.POSTINPROG, type: RpmType.STRING, value: '/bin/sh' });
+    }
+    if (scripts.postun !== undefined) {
+        entries.push({ tag: TAG.POSTUN, type: RpmType.STRING, value: scripts.postun });
+        entries.push({ tag: TAG.POSTUNPROG, type: RpmType.STRING, value: '/bin/sh' });
+    }
+    return entries;
+}
+/**
+ * Every per-file tag is one column of the same table.
+ *
+ * rpm reads them POSITIONALLY and never checks that they agree: a short
+ * FILEMODES array is not an error, it is a package whose later files install
+ * with whatever value happened to sit at that index. The lengths are trivially
+ * checkable here and effectively uncheckable afterwards, so they are checked
+ * here.
+ */
+function assertParallelFileArrays(entries, fileCount) {
+    const perFileTags = new Set([
+        TAG.FILESIZES,
+        TAG.FILEMODES,
+        TAG.FILERDEVS,
+        TAG.FILEMTIMES,
+        TAG.FILEDIGESTS,
+        TAG.FILELINKTOS,
+        TAG.FILEFLAGS,
+        TAG.FILEUSERNAME,
+        TAG.FILEGROUPNAME,
+        TAG.FILEVERIFYFLAGS,
+        TAG.FILEDEVICES,
+        TAG.FILEINODES,
+        TAG.FILELANGS,
+        TAG.DIRINDEXES,
+        TAG.BASENAMES,
+    ]);
+    for (const entry of entries) {
+        if (!perFileTags.has(entry.tag))
+            continue;
+        const length = Array.isArray(entry.value) ? entry.value.length : 1;
+        if (length !== fileCount) {
+            throw new Error(`gjsify ship: internal error — rpm tag ${entry.tag} has ${length} values for ${fileCount} files.`);
+        }
+    }
+}
+/**
+ * The three parallel `Requires` arrays.
+ *
+ * A scriptlet's interpreter is a dependency like any other and rpm expects it
+ * declared with the matching `SCRIPT_*` sense bit — without it, a system
+ * without `/bin/sh` installs the package and then fails inside `%post`.
+ */
+function buildRequires(depends, scripts) {
+    const names = [];
+    const flags = [];
+    const versions = [];
+    for (const depend of depends) {
+        const parsed = parseDepend(depend);
+        names.push(parsed.name);
+        flags.push(senseFor(parsed.relation));
+        versions.push(parsed.version ?? '');
+    }
+    if (scripts.post !== undefined) {
+        names.push('/bin/sh');
+        flags.push(SENSE.INTERP | SENSE.SCRIPT_POST);
+        versions.push('');
+    }
+    if (scripts.postun !== undefined) {
+        names.push('/bin/sh');
+        flags.push(SENSE.INTERP | SENSE.SCRIPT_POSTUN);
+        versions.push('');
+    }
+    for (const [name, version] of RPMLIB_REQUIRES) {
+        names.push(name);
+        flags.push(SENSE.RPMLIB | SENSE.LESS | SENSE.EQUAL);
+        versions.push(version);
+    }
+    return { names, flags, versions };
+}
+function senseFor(relation) {
+    switch (relation) {
+        case '>=':
+            return SENSE.GREATER | SENSE.EQUAL;
+        case '>':
+            return SENSE.GREATER;
+        case '<=':
+            return SENSE.LESS | SENSE.EQUAL;
+        case '<':
+            return SENSE.LESS;
+        case '=':
+            return SENSE.EQUAL;
+        default:
+            return 0;
+    }
+}
+function hashHex(algorithm, data) {
+    return createHash(algorithm).update(data).digest('hex');
+}
+function hashBytes(algorithm, data) {
+    return new Uint8Array(createHash(algorithm).update(data).digest());
+}

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

@@ -0,0 +1,31 @@
+import type { ShipSettings } from './types.js';
+/**
+ * The cache refreshes this payload makes necessary, each guarded by the tool's
+ * presence and `|| true`.
+ *
+ * The caches belong to the distribution, not to us: on removal the helper may
+ * already be gone, and a maintainer script that fails during a purge leaves a
+ * package the user cannot uninstall.
+ */
+export declare function cacheRefreshCommands(settings: ShipSettings, prefix: string): string[];
+/**
+ * dpkg maintainer scripts, keyed by their `control.tar` filename.
+ *
+ * `postrm` guards on `remove` alone: dpkg also calls it for `purge`, `upgrade`
+ * and several abort paths, and on an upgrade the incoming package's `postinst`
+ * refreshes the caches anyway.
+ */
+export declare function renderDebScripts(settings: ShipSettings, prefix: string): Record<string, string>;
+/**
+ * rpm scriptlets, for the `POSTIN` / `POSTUN` header tags.
+ *
+ * No action guard: rpm's `$1` is a COUNT, and both the install and the upgrade
+ * case want the refresh. `%postun` runs it unconditionally too — on an upgrade
+ * the incoming package's `%post` has already run, so a second refresh is wasted
+ * work rather than a wrong result, where guarding on `[ $1 -eq 0 ]` would be
+ * one more place to get the convention backwards.
+ */
+export declare function renderRpmScriptlets(settings: ShipSettings, prefix: string): {
+    post?: string;
+    postun?: string;
+};

package/lib/utils/ship/scripts.js

@@ -0,0 +1,76 @@
+// The post-install / post-remove work, and the two very different envelopes it
+// travels in.
+//
+// The BODY is shared — refresh the desktop database, the icon cache and the
+// compiled GSettings schemas, because those are system-wide caches our files
+// changed. The GUARD is not, and assuming it was is the bug this file exists to
+// prevent: dpkg passes `configure` / `remove` as `$1`, rpm passes the NUMBER of
+// instances that will remain (1 on install, 0 on final erase). A dpkg-shaped
+// `[ "$1" = "configure" ]` inside an rpm scriptlet is never true, so the
+// package installs, the scriptlet runs, and nothing happens. Measured by
+// reading `rpm -qp --scripts` on the first artifact this packer produced —
+// which is exactly the class of defect a rendered-output assertion would have
+// waved through.
+/**
+ * The cache refreshes this payload makes necessary, each guarded by the tool's
+ * presence and `|| true`.
+ *
+ * The caches belong to the distribution, not to us: on removal the helper may
+ * already be gone, and a maintainer script that fails during a purge leaves a
+ * package the user cannot uninstall.
+ */
+export function cacheRefreshCommands(settings, prefix) {
+    const refreshes = [];
+    if (settings.kind === 'app') {
+        refreshes.push({
+            probe: 'update-desktop-database',
+            run: `update-desktop-database -q ${prefix}/share/applications`,
+        });
+    }
+    if (settings.iconFiles.length > 0) {
+        refreshes.push({
+            probe: 'gtk-update-icon-cache',
+            run: `gtk-update-icon-cache -q -t -f ${prefix}/share/icons/hicolor`,
+        });
+    }
+    if (settings.schemaFiles.length > 0) {
+        refreshes.push({
+            probe: 'glib-compile-schemas',
+            run: `glib-compile-schemas ${prefix}/share/glib-2.0/schemas`,
+        });
+    }
+    return refreshes.map(({ probe, run }) => `if command -v ${probe} >/dev/null 2>&1; then ${run} || true; fi`);
+}
+/**
+ * dpkg maintainer scripts, keyed by their `control.tar` filename.
+ *
+ * `postrm` guards on `remove` alone: dpkg also calls it for `purge`, `upgrade`
+ * and several abort paths, and on an upgrade the incoming package's `postinst`
+ * refreshes the caches anyway.
+ */
+export function renderDebScripts(settings, prefix) {
+    const commands = cacheRefreshCommands(settings, prefix);
+    if (commands.length === 0)
+        return {};
+    const body = commands.map((line) => `    ${line}`).join('\n');
+    return {
+        postinst: ['#!/bin/sh', 'set -e', 'if [ "$1" = "configure" ]; then', body, 'fi', ''].join('\n'),
+        postrm: ['#!/bin/sh', 'set -e', 'if [ "$1" = "remove" ]; then', body, 'fi', ''].join('\n'),
+    };
+}
+/**
+ * rpm scriptlets, for the `POSTIN` / `POSTUN` header tags.
+ *
+ * No action guard: rpm's `$1` is a COUNT, and both the install and the upgrade
+ * case want the refresh. `%postun` runs it unconditionally too — on an upgrade
+ * the incoming package's `%post` has already run, so a second refresh is wasted
+ * work rather than a wrong result, where guarding on `[ $1 -eq 0 ]` would be
+ * one more place to get the convention backwards.
+ */
+export function renderRpmScriptlets(settings, prefix) {
+    const commands = cacheRefreshCommands(settings, prefix);
+    if (commands.length === 0)
+        return {};
+    const body = `${commands.join('\n')}\n`;
+    return { post: body, postun: body };
+}

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

@@ -0,0 +1,60 @@
+import type { AppMetadata, ConfigDataFlatpak, ConfigDataShip, DescriptionBlock } from '../../types/config-data.js';
+import type { ShipSettings } from './types.js';
+/** The subset of `package.json` the resolver reads. */
+export interface ShipPackageManifest {
+    name?: string;
+    version?: string;
+    description?: string;
+    license?: string;
+    homepage?: string;
+    author?: string | {
+        name?: string;
+        email?: string;
+        url?: string;
+    };
+    main?: string;
+    gjsify?: {
+        main?: string;
+    };
+}
+/** Paths the caller has already found on disk. */
+export interface DiscoveredPayload {
+    /** Absolute path to the built bundle. */
+    bundlePath: string;
+    /** Absolute path to the directory staged into `lib/<binaryName>/`. */
+    bundleDir: string;
+    /** Bundle-dir-relative paths, POSIX-separated. */
+    bundleFiles: string[];
+    iconFiles: string[];
+    schemaFiles: string[];
+    licenseFile?: string;
+}
+export interface SettingsInput {
+    projectDir: string;
+    pkg: ShipPackageManifest;
+    ship: ConfigDataShip;
+    /** Metadata fallback — `gjsify.flatpak` already carries these fields for many projects. */
+    flatpak: ConfigDataFlatpak;
+    cli: {
+        outDir?: string;
+        arch?: string;
+    };
+    discovered: DiscoveredPayload;
+}
+export interface ResolvedSettings {
+    settings: ShipSettings;
+    /** The merged metadata the renderers read. */
+    metadata: AppMetadata;
+    warnings: string[];
+}
+export declare function resolveShipSettings(input: SettingsInput): ResolvedSettings;
+/** The bundle path a project declares, in the order the rest of the CLI reads them. */
+export declare function declaredBundlePath(pkg: ShipPackageManifest, ship: ConfigDataShip): string | undefined;
+/** npm package name → a package/binary name both dpkg and rpm accept. */
+export declare function deriveBinaryName(pkgName: string | undefined): string;
+/** AppStream description (string or blocks) → plain paragraphs for deb/rpm. */
+export declare function descriptionParagraphs(description: string | DescriptionBlock[] | undefined): string[] | undefined;
+/** `LICENSE`, `LICENSE.md`, … — the names a licence file actually has. */
+export declare const LICENSE_FILE_NAMES: readonly ["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING", "COPYING.md"];
+/** The bundle's own basename, used as the launcher's exec target. */
+export declare function bundleEntryName(bundlePath: string): string;