@gtkx/cli 1.6.0 → 2.0.0-beta.10

package/src/deploy/node-runtime/elf.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { closeSync, openSync, readFileSync, readSync } from "node:fs";
 
 type ElfSection = {
     name: string;
@@ -7,6 +7,7 @@ type ElfSection = {
 };
 
 type ElfInfo = {
+    machine: number;
     needed: string[];
     glibcMinimum: string | null;
 };
@@ -17,10 +18,12 @@ type DynamicEntry = {
 };
 
 const ELF_MAGIC = "ELF";
+const ELF_MAGIC_SIZE = 4;
 const CLASS_64 = 2;
 const LITTLE_ENDIAN = 1;
 const OFFSET_CLASS = 4;
 const OFFSET_DATA = 5;
+const OFFSET_MACHINE = 0x12;
 const OFFSET_SECTION_HEADERS = 0x28;
 const OFFSET_SECTION_ENTRY_SIZE = 0x3A;
 const OFFSET_SECTION_COUNT = 0x3C;
@@ -35,8 +38,11 @@ const DYNAMIC_VALUE_OFFSET = 8;
 const GLIBC_VERSION = /GLIBC_(\d+)\.(\d+)/g;
 const VERSION_RADIX = 1000;
 
+const hasElfMagic = (buffer: Buffer): boolean =>
+    buffer.length >= OFFSET_CLASS && buffer.subarray(0, 4).toString("latin1") === ELF_MAGIC;
+
 const assertElf64 = (buffer: Buffer, path: string): void => {
-    if (buffer.length < OFFSET_SECTION_NAME_INDEX || buffer.subarray(0, 4).toString("latin1") !== ELF_MAGIC) {
+    if (buffer.length < OFFSET_SECTION_NAME_INDEX || !hasElfMagic(buffer)) {
         throw new Error(`Cannot read ${path}: it is not an ELF binary`);
     }
 
@@ -130,16 +136,51 @@ const readGlibcMinimum = (strings: Buffer): string | null => {
 const stringTable = (buffer: Buffer, dynstr: ElfSection | undefined): Buffer =>
     dynstr === undefined ? Buffer.alloc(0) : buffer.subarray(dynstr.offset, dynstr.offset + dynstr.size);
 
-const readElfInfo = (path: string): ElfInfo => {
-    const buffer = readFileSync(path);
+const readElfBuffer = (buffer: Buffer, path: string): ElfInfo => {
     assertElf64(buffer, path);
     const sections = readSections(buffer);
     const strings = stringTable(buffer, sectionFor(sections, ".dynstr"));
 
     return {
+        machine: buffer.readUInt16LE(OFFSET_MACHINE),
         needed: readNeeded(buffer, sectionFor(sections, ".dynamic"), strings),
         glibcMinimum: readGlibcMinimum(strings),
     };
 };
 
-export { type ElfInfo, readElfInfo };
+const readElfInfo = (path: string): ElfInfo => readElfBuffer(readFileSync(path), path);
+
+const readFilePrefix = (descriptor: number, size: number): Buffer => {
+    const buffer = Buffer.alloc(size);
+    const bytesRead = readSync(descriptor, buffer, 0, size, 0);
+
+    return buffer.subarray(0, bytesRead);
+};
+
+const readOptionalElfInfo = (path: string): ElfInfo | null => {
+    const descriptor = openSync(path, "r");
+
+    try {
+        const prefix = readFilePrefix(descriptor, ELF_MAGIC_SIZE);
+
+        return hasElfMagic(prefix) ? readElfBuffer(readFileSync(descriptor), path) : null;
+    } finally {
+        closeSync(descriptor);
+    }
+};
+
+const glibcMinimumForFiles = (paths: Iterable<string>): string | null => {
+    const versions: number[][] = [];
+
+    for (const path of paths) {
+        const minimum = readOptionalElfInfo(path)?.glibcMinimum;
+
+        if (minimum !== undefined && minimum !== null) {
+            versions.push(minimum.split(".").map(Number));
+        }
+    }
+
+    return formatVersion(highestVersion(versions));
+};
+
+export { type ElfInfo, glibcMinimumForFiles, readElfInfo, readOptionalElfInfo };

package/src/deploy/node-runtime/guard.ts

@@ -1,19 +1,16 @@
 import type { ElfInfo } from "./elf.js";
+import { RUNTIME_SONAMES } from "./sonames.js";
 
-const PORTABLE_LIBRARIES = new Set([
-    "ld-linux-aarch64.so.1",
-    "ld-linux-x86-64.so.2",
-    "libc.so.6",
-    "libdl.so.2",
-    "libgcc_s.so.1",
-    "libm.so.6",
-    "libpthread.so.0",
-    "librt.so.1",
-    "libstdc++.so.6",
-]);
+const DOWNLOAD_REMEDY =
+    "The packages GTKX generates declare the libraries an official release links against, and this release " +
+    "links against more. Report it to GTKX, and pin `deploy.node.version` to a release it already packages.";
+
+const SOURCE_REMEDY = 'Use `deploy.node.source: "download"` to fetch an official self-contained build instead.';
+
+const remedyFor = (source: string): string => (source === "download" ? DOWNLOAD_REMEDY : SOURCE_REMEDY);
 
 const assertPortableNode = (info: ElfInfo, source: string): void => {
-    const foreign = info.needed.filter((library) => !PORTABLE_LIBRARIES.has(library));
+    const foreign = info.needed.filter((library) => !RUNTIME_SONAMES.has(library));
 
     if (foreign.length === 0) {
         return;
@@ -21,8 +18,7 @@ const assertPortableNode = (info: ElfInfo, source: string): void => {
 
     throw new Error(
         `Cannot bundle this Node.js binary: \`deploy.node.source: "${source}"\` picked one linked against ` +
-        `${foreign.join(", ")}, which the target machine will not have. ` +
-        'Use `deploy.node.source: "download"` to fetch an official self-contained build instead.',
+        `${foreign.join(", ")}, which the packages GTKX generates do not require. ${remedyFor(source)}`,
     );
 };
 

package/src/deploy/node-runtime/index.ts

@@ -1,10 +1,13 @@
-import { info, tryResolveExecutable } from "@gtkx/utils";
-import { chmodSync, copyFileSync, mkdirSync, statSync } from "node:fs";
+import { MINIMUM_NODE_VERSION } from "@gtkx/config/internal";
+import { info, tryResolveExecutable, warn } from "@gtkx/utils";
+import { execFileSync } from "node:child_process";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
-import type { DeploySettings, NodeRuntime } from "../types.js";
+import type { DeployConfig, DeploySettings, NodeRuntime } from "../types.js";
 import { runCliTool } from "../../internal/run-cli-tool.js";
+import { elfMachineFor, hostArchName } from "../settings/arch.js";
 import { downloadNode } from "./download.js";
-import { readElfInfo } from "./elf.js";
+import { type ElfInfo, readElfInfo, readOptionalElfInfo } from "./elf.js";
 import { assertPortableNode } from "./guard.js";
 import { licenseBesideNode } from "./license.js";
 
@@ -13,13 +16,92 @@ type StagedRuntime = {
     licenseFile: string | null;
 };
 
+type NodeSource = "download" | "host" | "path";
+
 const BYTES_PER_MIB = 1024 * 1024;
 const EXECUTABLE_MODE = 0o755;
 const NODE_FILENAME = "node";
+const NODE_VERSION_PATTERN = /^v?(\d+)\.(\d+)\.(\d+)$/;
+const VERSION_PROBE_TIMEOUT_MS = 10_000;
+const VERSION_PROBE_MAX_BUFFER = 1024;
+
+const nodeSourceFor = (settings: DeploySettings): NodeSource => settings.deploy.node?.source ?? "download";
+
+const parseNodeVersion = (value: string, subject: string): { parts: number[]; version: string } => {
+    const match = NODE_VERSION_PATTERN.exec(value.trim());
+
+    if (match === null) {
+        throw new Error(`Cannot determine the Node.js version for ${subject}: expected a version such as 26.7.0`);
+    }
+
+    const parts = match.slice(1).map(Number);
+
+    return { parts, version: parts.map(String).join(".") };
+};
+
+const compareVersions = (left: number[], right: number[]): number => {
+    for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+        const difference = (left[index] ?? 0) - (right[index] ?? 0);
+
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+
+    return 0;
+};
+
+const supportedNodeVersion = (value: string, subject: string): string => {
+    const parsed = parseNodeVersion(value, subject);
+    const minimum = parseNodeVersion(MINIMUM_NODE_VERSION, "GTKX");
+
+    if (compareVersions(parsed.parts, minimum.parts) < 0) {
+        throw new Error(
+            `Cannot bundle Node.js ${parsed.version} for ${subject}: GTKX requires ${MINIMUM_NODE_VERSION} or newer`,
+        );
+    }
+
+    return parsed.version;
+};
+
+const probeNodeVersion = (path: string): string => {
+    try {
+        const output = execFileSync(path, ["--version"], {
+            encoding: "utf8",
+            env: { ...process.env, NODE_OPTIONS: "" },
+            maxBuffer: VERSION_PROBE_MAX_BUFFER,
+            timeout: VERSION_PROBE_TIMEOUT_MS,
+        });
+
+        return supportedNodeVersion(output, path);
+    } catch (error) {
+        if (error instanceof Error && error.message.startsWith("Cannot bundle Node.js")) {
+            throw error;
+        }
+
+        throw new Error(`Cannot determine the Node.js version from ${path}`, { cause: error });
+    }
+};
+
+const assertExpectedVersion = (configured: string | undefined, actual: string, source: NodeSource): string => {
+    if (configured === undefined) {
+        return actual;
+    }
+
+    const expected = parseNodeVersion(configured, `deploy.node.source: "${source}"`).version;
+
+    if (expected !== actual) {
+        throw new Error(
+            `The Node.js runtime from deploy.node.source "${source}" is ${actual}, not the configured ${expected}`,
+        );
+    }
+
+    return actual;
+};
 
 const sourcePathFor = (settings: DeploySettings): string => {
     const node = settings.deploy.node ?? {};
-    const source = node.source ?? "download";
+    const source = nodeSourceFor(settings);
 
     if (source === "host") {
         return process.execPath;
@@ -32,6 +114,36 @@ const sourcePathFor = (settings: DeploySettings): string => {
     return resolve(settings.paths.root, node.path);
 };
 
+const assertPortableRuntimeSource = (settings: DeploySettings): void => {
+    const source = nodeSourceFor(settings);
+
+    if (source === "download") {
+        return;
+    }
+
+    const sourcePath = sourcePathFor(settings);
+    const elf = existsSync(sourcePath) ? readOptionalElfInfo(sourcePath) : null;
+
+    if (elf !== null) {
+        assertPortableNode(elf, source);
+    }
+};
+
+const resolveNodeVersion = (settings: DeploySettings): string => {
+    const node = settings.deploy.node ?? {};
+    const source = nodeSourceFor(settings);
+
+    if (source === "download") {
+        return supportedNodeVersion(node.version ?? MINIMUM_NODE_VERSION, 'deploy.node.source: "download"');
+    }
+
+    const actual = source === "host"
+        ? supportedNodeVersion(process.versions.node, 'deploy.node.source: "host"')
+        : probeNodeVersion(sourcePathFor(settings));
+
+    return assertExpectedVersion(node.version, actual, source);
+};
+
 const didStripBinary = (path: string): boolean => {
     if (tryResolveExecutable("strip") === undefined) {
         return false;
@@ -60,27 +172,51 @@ const stageDownloadedNode = async (settings: DeploySettings, version: string): P
     return downloaded;
 };
 
-const stageFromSource = async (settings: DeploySettings, version: string, source: string): Promise<StagedRuntime> => {
+const stageFromSource = async (
+    settings: DeploySettings,
+    version: string,
+    source: NodeSource,
+): Promise<StagedRuntime> => {
     if (source === "download") {
         return stageDownloadedNode(settings, version);
     }
 
     const sourcePath = sourcePathFor(settings);
-    assertPortableNode(readElfInfo(sourcePath), source);
 
     return { path: stageNode(settings, sourcePath), licenseFile: licenseBesideNode(sourcePath) };
 };
 
+type DeployNodeConfig = NonNullable<DeployConfig["node"]>;
+
+const shouldStripRuntime = (settings: DeploySettings, node: DeployNodeConfig, elf: ElfInfo): boolean => {
+    if (node.shouldStrip === false) {
+        return false;
+    }
+
+    if (elf.machine === elfMachineFor(hostArchName())) {
+        return true;
+    }
+
+    warn(
+        `Skipping \`strip\` on the bundled Node.js: it was built for ${settings.arch.node} and \`strip\` reads ` +
+        `only ${hostArchName()}. The ${settings.arch.node} packages carry an unstripped runtime.`,
+    );
+
+    return false;
+};
+
 const resolveNodeRuntime = async (settings: DeploySettings): Promise<NodeRuntime> => {
     const node = settings.deploy.node ?? {};
-    const source = node.source ?? "download";
-    const version = node.version ?? process.versions.node;
+    const source = nodeSourceFor(settings);
+    const version = resolveNodeVersion(settings);
     const staged = await stageFromSource(settings, version, source);
-    const isStripped = node.shouldStrip === false ? false : didStripBinary(staged.path);
     const elf = readElfInfo(staged.path);
-    info(`Bundled Node.js v${version} (${megabytes(staged.path)} MiB, glibc >= ${elf.glibcMinimum ?? "unknown"})`);
+    assertPortableNode(elf, source);
+    const isStripped = shouldStripRuntime(settings, node, elf) && didStripBinary(staged.path);
+    const glibcMinimum = elf.glibcMinimum ?? "unknown";
+    info(`Bundled Node.js v${version} (${megabytes(staged.path)} MiB, runtime glibc >= ${glibcMinimum})`);
 
     return { ...staged, version, glibcMinimum: elf.glibcMinimum, isStripped };
 };
 
-export { resolveNodeRuntime, sourcePathFor };
+export { assertPortableRuntimeSource, resolveNodeRuntime, resolveNodeVersion, sourcePathFor };

package/src/deploy/node-runtime/license.ts

@@ -1,5 +1,5 @@
-import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { readLicenseText } from "../notices/text.js";
 
 const LICENSE_FILENAME = "LICENSE";
 const NODE_MARKER = "Node.js";
@@ -10,13 +10,7 @@ const licenseCandidates = (binary: string): string[] => {
     return [join(dir, LICENSE_FILENAME), join(dir, "..", LICENSE_FILENAME)];
 };
 
-const isNodeLicense = (path: string): boolean => {
-    try {
-        return readFileSync(path, "utf8").includes(NODE_MARKER);
-    } catch {
-        return false;
-    }
-};
+const isNodeLicense = (path: string): boolean => readLicenseText(path)?.includes(NODE_MARKER) === true;
 
 const licenseBesideNode = (binary: string): string | null =>
     licenseCandidates(binary).find((candidate) => isNodeLicense(candidate)) ?? null;

package/src/deploy/node-runtime/sonames.ts

@@ -0,0 +1,17 @@
+const GLIBC_SONAMES = [
+    "ld-linux-aarch64.so.1",
+    "ld-linux-x86-64.so.2",
+    "libc.so.6",
+    "libdl.so.2",
+    "libm.so.6",
+    "libpthread.so.0",
+    "librt.so.1",
+] as const;
+
+const PACKAGED_SONAMES = ["libatomic.so.1", "libgcc_s.so.1", "libstdc++.so.6"] as const;
+
+type PackagedSoname = (typeof PACKAGED_SONAMES)[number];
+
+const RUNTIME_SONAMES: Set<string> = new Set([...GLIBC_SONAMES, ...PACKAGED_SONAMES]);
+
+export { PACKAGED_SONAMES, type PackagedSoname, RUNTIME_SONAMES };

package/src/deploy/notices/node-runtime.ts

@@ -1,6 +1,6 @@
 import { warn } from "@gtkx/utils";
 import type { DeploySettings, NodeRuntime, NoticeSection } from "../types.js";
-import { sourcePathFor } from "../node-runtime/index.js";
+import { resolveNodeVersion, sourcePathFor } from "../node-runtime/index.js";
 import { licenseBesideNode } from "../node-runtime/license.js";
 import { NODE_FILENAME } from "../payload/launcher.js";
 import { nodeLicenseDestination } from "../payload/stage.js";
@@ -32,7 +32,7 @@ const MISSING_LICENSE =
 const isSourceMode = (settings: DeploySettings): boolean => settings.deploy.flatpak?.mode === "source";
 
 const versionFor = (settings: DeploySettings, node: NodeRuntime | null): string =>
-    node?.version ?? settings.deploy.node?.version ?? process.versions.node;
+    node?.version ?? resolveNodeVersion(settings);
 
 const licenseFileFor = (settings: DeploySettings, node: NodeRuntime | null): string | null => {
     if (node !== null) {

package/src/deploy/notices/packages.ts

@@ -1,4 +1,5 @@
 import { sortStringsBy, warn } from "@gtkx/utils";
+import hostedGitInfo from "hosted-git-info";
 import { existsSync, realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
 import type { RecordedPackage } from "../../internal/build-manifest.js";
@@ -17,10 +18,6 @@ type BundledPackage = {
 };
 
 const MANIFEST_FILENAME = "package.json";
-const GIT_PREFIX = /^git\+/;
-const GIT_SUFFIX = /\.git$/;
-const GIT_SCHEME = /^git:\/\//;
-const GITHUB_SLUG = /^(?:github:)?(?<slug>[\w.-]+\/[\w.-]+)$/;
 
 const realPath = (path: string): string => {
     try {
@@ -47,14 +44,9 @@ const sourceUrl = (manifest: PackageManifest): string | null => {
         return null;
     }
 
-    const url = configured.replace(GIT_PREFIX, "").replace(GIT_SUFFIX, "").replace(GIT_SCHEME, "https://");
-    const slug = GITHUB_SLUG.exec(url)?.groups?.slug;
+    const url = configured.replace(/^git\+/, "").replace(/\.git$/, "").replace(/^git:\/\//, "https://");
 
-    if (slug !== undefined) {
-        return `https://github.com/${slug}`;
-    }
-
-    return url.startsWith("http") ? url : null;
+    return hostedGitInfo.fromUrl(url)?.browse() ?? (url.startsWith("http") ? url : null);
 };
 
 const missingPackage = (entry: RecordedPackage): BundledPackage => ({

package/src/deploy/payload/copy-tree.ts

@@ -1,5 +1,6 @@
+import { isPathInside } from "@gtkx/utils";
 import { chmodSync, copyFileSync, mkdirSync, statSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, relative } from "node:path";
+import { dirname, join } from "node:path";
 import type { StagedFile } from "../types.js";
 import { listFilesRecursive } from "../../internal/list-files.js";
 
@@ -16,9 +17,7 @@ const modeFor = (rel: string): number => {
 };
 
 const assertInsideRoot = (root: string, rel: string, abs: string): void => {
-    const escape = relative(root, abs);
-
-    if (escape.length === 0 || escape.startsWith("..") || isAbsolute(escape)) {
+    if (!isPathInside(root, abs)) {
         throw new Error(`Cannot stage "${rel}": it resolves outside the staging directory`);
     }
 };

package/src/deploy/payload/launcher.ts

@@ -2,6 +2,8 @@ import type { DeploySettings } from "../types.js";
 import { BUNDLE_FILENAME } from "../../vite-plugins/esm-extension.js";
 
 const NODE_FILENAME = "node";
+const SHELL_SINGLE_QUOTE = "'";
+const SHELL_SINGLE_QUOTE_ESCAPE = "'\"'\"'";
 
 const compileCacheLines = (binaryName: string): string[] => [
     "cache_home=${XDG_CACHE_HOME:-${HOME:-/tmp}/.cache}",
@@ -9,6 +11,22 @@ const compileCacheLines = (binaryName: string): string[] => [
     "export NODE_COMPILE_CACHE",
 ];
 
+const shellQuote = (value: string): string =>
+    SHELL_SINGLE_QUOTE + value.split(SHELL_SINGLE_QUOTE).join(SHELL_SINGLE_QUOTE_ESCAPE) + SHELL_SINGLE_QUOTE;
+
+const launcherEnvLines = (settings: DeploySettings): string[] =>
+    Object.entries(settings.deploy.launcherEnv ?? {})
+        .toSorted(([left], [right]) => left.localeCompare(right))
+        .map(([name, value]) => `export ${name}=${shellQuote(value)}`);
+
+const launcherCommand = (settings: DeploySettings, libDir: string): string =>
+    [
+        `"${libDir}/${NODE_FILENAME}"`,
+        ...(settings.deploy.nodeFlags ?? []).map((flag) => shellQuote(flag)),
+        `"${libDir}/${BUNDLE_FILENAME}"`,
+        '"$@"',
+    ].join(" ");
+
 const renderLauncher = (settings: DeploySettings): string => {
     const libDir = `$prefix/lib/${settings.binaryName}`;
     const shouldUseCompileCache = settings.deploy.node?.shouldUseCompileCache !== false;
@@ -21,7 +39,8 @@ const renderLauncher = (settings: DeploySettings): string => {
         'GTKX_LOCALE_DIR="$prefix/share/locale"',
         "export GTKX_LOCALE_DIR",
         ...(shouldUseCompileCache ? compileCacheLines(settings.binaryName) : []),
-        `exec "${libDir}/${NODE_FILENAME}" "${libDir}/${BUNDLE_FILENAME}" "$@"`,
+        ...launcherEnvLines(settings),
+        `exec ${launcherCommand(settings, libDir)}`,
         "",
     ].join("\n");
 };

package/src/deploy/payload/stage.ts

@@ -1,4 +1,4 @@
-import { sortStringsBy } from "@gtkx/utils";
+import { sortStringsBy, warn } from "@gtkx/utils";
 import { existsSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
 import type { DeploySettings, DeployTargetName, NodeRuntime, NoticeSection, StagedFile } from "../types.js";
@@ -8,7 +8,10 @@ import { listFilesRecursive } from "../../internal/list-files.js";
 import { BUNDLE_FILENAME } from "../../vite-plugins/esm-extension.js";
 import { renderCopyright } from "../freedesktop/copyright.js";
 import { renderDbusService } from "../freedesktop/dbus-service.js";
+import { BINDING_FILENAME } from "../native-addon.js";
+import { readOptionalElfInfo } from "../node-runtime/elf.js";
 import { renderNotices } from "../notices/render.js";
+import { elfMachineFor } from "../settings/arch.js";
 import { copyInto, EXECUTABLE_MODE, executableModeFor, writeInto } from "./copy-tree.js";
 import { stageIcons } from "./icons.js";
 import { NODE_FILENAME, renderLauncher } from "./launcher.js";
@@ -17,6 +20,7 @@ import { stageSchemas } from "./schemas.js";
 type StageRequest = {
     settings: DeploySettings;
     node: NodeRuntime | null;
+    addon: string | null;
     metadata: StagedMetadata;
 };
 
@@ -27,7 +31,6 @@ type StagedMetadata = {
 };
 
 const DIST_ICONS_DIR = "icons";
-const LEGACY_PACKAGES_MANIFEST_FILENAME = "gtkx-packages.json";
 const NOTICES_FILENAME = "THIRD-PARTY-NOTICES";
 const NODE_LICENSE_FILENAME = "LICENSE";
 const SHARE_APPLICATIONS = "share/applications";
@@ -50,10 +53,6 @@ const licenseDirFor = (settings: DeploySettings): string => `${SHARE_LICENSES}/$
 const licenseDestination = (settings: DeploySettings): string => `${licenseDirFor(settings)}/LICENSE`;
 const noticesDestination = (settings: DeploySettings): string => `${licenseDirFor(settings)}/${NOTICES_FILENAME}`;
 const isIconAsset = (rel: string): boolean => rel === DIST_ICONS_DIR || rel.startsWith(`${DIST_ICONS_DIR}/`);
-
-const isBuildMetadata = (rel: string): boolean =>
-    rel === BUILD_MANIFEST_FILENAME || rel === LEGACY_PACKAGES_MANIFEST_FILENAME;
-
 const isLocaleAsset = (rel: string): boolean => rel === LOCALE_DIRNAME || rel.startsWith(`${LOCALE_DIRNAME}/`);
 
 const nodeLicenseDestination = (settings: DeploySettings): string =>
@@ -67,10 +66,34 @@ const stageRuntimeFiles = (settings: DeploySettings, root: string): StagedFile[]
     }
 
     return listFilesRecursive(dist)
-        .filter((file) => !isIconAsset(file.rel) && !isBuildMetadata(file.rel) && !isLocaleAsset(file.rel))
+        .filter((file) =>
+            !isIconAsset(file.rel) && file.rel !== BUILD_MANIFEST_FILENAME && !isLocaleAsset(file.rel))
         .map((file) => copyInto(root, join(libDirFor(settings), file.rel), file.absPath));
 };
 
+const stageAddon = (settings: DeploySettings, root: string, addon: string | null): StagedFile[] =>
+    addon === null ? [] : [copyInto(root, join(libDirFor(settings), BINDING_FILENAME), addon)];
+
+const architectureMismatch = (settings: DeploySettings, file: StagedFile): Error =>
+    new Error(
+        `Cannot deploy ${file.rel} for ${settings.arch.node}: it was built for another architecture. ` +
+        "Run `gtkx build` again, or drop --skip-build.",
+    );
+
+const assertStagedArchitecture = (settings: DeploySettings, staged: StagedFile[]): void => {
+    const expected = elfMachineFor(settings.arch.node);
+    const lib = libDirFor(settings);
+    const checked = new Set([join(lib, BINDING_FILENAME), join(lib, NODE_FILENAME)]);
+
+    const binaries = staged.filter((entry) => checked.has(entry.rel));
+
+    for (const file of binaries) {
+        if (readOptionalElfInfo(file.abs)?.machine !== expected) {
+            throw architectureMismatch(settings, file);
+        }
+    }
+};
+
 const stageCatalogs = (settings: DeploySettings, root: string): StagedFile[] =>
     listFilesRecursive(join(settings.paths.dist, LOCALE_DIRNAME))
         .map((file) => copyInto(root, join(SHARE_LOCALE, file.rel), file.absPath));
@@ -86,9 +109,48 @@ const stageMetadata = (settings: DeploySettings, root: string, metadata: StagedM
         : [writeInto(root, join(SHARE_MIME_PACKAGES, `${settings.applicationId}.xml`), metadata.mimePackage)]),
 ];
 
-const stageExtraFiles = (settings: DeploySettings, root: string): StagedFile[] =>
+const generatedMetadataKind = (
+    settings: DeploySettings,
+    metadata: StagedMetadata,
+    destination: string,
+): string | null => {
+    if (destination === join(SHARE_APPLICATIONS, `${settings.applicationId}.desktop`)) {
+        return "desktop entry";
+    }
+
+    if (destination === join(SHARE_METAINFO, `${settings.applicationId}.metainfo.xml`)) {
+        return "metainfo";
+    }
+
+    if (
+        metadata.mimePackage !== null &&
+        destination === join(SHARE_MIME_PACKAGES, `${settings.applicationId}.xml`)
+    ) {
+        return "MIME package";
+    }
+
+    return null;
+};
+
+const warnMetadataCollision = (
+    settings: DeploySettings,
+    metadata: StagedMetadata,
+    file: DeploySettings["extraFiles"][number],
+): void => {
+    const kind = generatedMetadataKind(settings, metadata, file.destination);
+
+    if (kind !== null) {
+        warn(
+            `extraFiles source "${file.source}" targeting "${file.destination}" is overridden by the ` +
+            `GTKX-generated ${kind}`,
+        );
+    }
+};
+
+const stageExtraFiles = (settings: DeploySettings, root: string, metadata: StagedMetadata): StagedFile[] =>
     settings.extraFiles.map((file) => {
         const source = resolve(settings.paths.root, file.source);
+        warnMetadataCollision(settings, metadata, file);
 
         return copyInto(root, file.destination, source, file.mode ?? executableModeFor(source));
     });
@@ -103,20 +165,25 @@ const byRelativePath = (files: StagedFile[]): StagedFile[] => {
     return sortStringsBy(latest.values(), (file) => file.rel);
 };
 
-const stagePayload = ({ settings, node, metadata }: StageRequest): StagedFile[] => {
+const stagePayload = ({ settings, node, addon, metadata }: StageRequest): StagedFile[] => {
     const root = settings.paths.stage;
     rmSync(root, { recursive: true, force: true, maxRetries: 5 });
 
-    return byRelativePath([
+    const staged = byRelativePath([
         writeInto(root, join("bin", settings.binaryName), renderLauncher(settings), EXECUTABLE_MODE),
         ...stageNodeBinary(settings, root, node),
         ...stageRuntimeFiles(settings, root),
+        ...stageAddon(settings, root, addon),
         ...stageCatalogs(settings, root),
+        ...stageExtraFiles(settings, root, metadata),
         ...stageMetadata(settings, root, metadata),
         ...stageIcons(settings, root),
         ...stageSchemas(settings, root),
-        ...stageExtraFiles(settings, root),
     ]);
+
+    assertStagedArchitecture(settings, staged);
+
+    return staged;
 };
 
 const withoutDbusActivation = (desktopEntry: string): string =>