@gtkx/cli 1.0.0 → 1.2.0

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

@@ -0,0 +1,29 @@
+import type { ElfInfo } from "./elf.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 assertPortableNode = (info: ElfInfo, source: string): void => {
+    const foreign = info.needed.filter((library) => !PORTABLE_LIBRARIES.has(library));
+
+    if (foreign.length === 0) {
+        return;
+    }
+
+    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.',
+    );
+};
+
+export { assertPortableNode };

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

@@ -0,0 +1,80 @@
+import { info, tryResolveExecutable } from "@gtkx/utils";
+import { chmodSync, copyFileSync, mkdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { DeploySettings, NodeRuntime } from "../types.js";
+import { runCliTool } from "../../internal/run-cli-tool.js";
+import { downloadNode } from "./download.js";
+import { readElfInfo } from "./elf.js";
+import { assertPortableNode } from "./guard.js";
+
+const BYTES_PER_MIB = 1024 * 1024;
+const EXECUTABLE_MODE = 0o755;
+const NODE_FILENAME = "node";
+
+const sourcePathFor = (settings: DeploySettings): string => {
+    const node = settings.deploy.node ?? {};
+    const source = node.source ?? "download";
+
+    if (source === "host") {
+        return process.execPath;
+    }
+
+    if (node.path === undefined) {
+        throw new Error('Cannot resolve the Node.js runtime: `deploy.node.source: "path"` needs `deploy.node.path`');
+    }
+
+    return resolve(settings.paths.root, node.path);
+};
+
+const didStripBinary = (path: string): boolean => {
+    if (tryResolveExecutable("strip") === undefined) {
+        return false;
+    }
+
+    runCliTool({ tool: "strip", args: ["--strip-unneeded", path], target: "the bundled Node.js" });
+
+    return true;
+};
+
+const megabytes = (path: string): string => (statSync(path).size / BYTES_PER_MIB).toFixed(1);
+
+const stageNode = (settings: DeploySettings, sourcePath: string): string => {
+    mkdirSync(settings.paths.runtime, { recursive: true });
+    const staged = join(settings.paths.runtime, NODE_FILENAME);
+    copyFileSync(sourcePath, staged);
+    chmodSync(staged, EXECUTABLE_MODE);
+
+    return staged;
+};
+
+const stageDownloadedNode = async (settings: DeploySettings, version: string): Promise<string> => {
+    const staged = await downloadNode(version, settings.arch.node, settings.paths.runtime);
+    chmodSync(staged, EXECUTABLE_MODE);
+
+    return staged;
+};
+
+const stageFromSource = async (settings: DeploySettings, version: string, source: string): Promise<string> => {
+    if (source === "download") {
+        return stageDownloadedNode(settings, version);
+    }
+
+    const sourcePath = sourcePathFor(settings);
+    assertPortableNode(readElfInfo(sourcePath), source);
+
+    return stageNode(settings, sourcePath);
+};
+
+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 staged = await stageFromSource(settings, version, source);
+    const isStripped = node.shouldStrip === false ? false : didStripBinary(staged);
+    const elf = readElfInfo(staged);
+    info(`Bundled Node.js v${version} (${megabytes(staged)} MiB, glibc >= ${elf.glibcFloor ?? "unknown"})`);
+
+    return { path: staged, version, glibcFloor: elf.glibcFloor, isStripped };
+};
+
+export { resolveNodeRuntime };

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

@@ -0,0 +1,51 @@
+import { chmodSync, copyFileSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import type { StagedFile } from "../types.js";
+import { listFilesRecursive } from "../../internal/list-files.js";
+
+const EXECUTABLE_MODE = 0o755;
+const READABLE_MODE = 0o644;
+const EXECUTABLE_SUFFIXES = [".node", ".so"];
+const MODE_MASK = 0o7777;
+
+const modeFor = (rel: string): number => {
+    const name = rel.split("/").at(-1) ?? rel;
+
+    return EXECUTABLE_SUFFIXES.some((suffix) => name.endsWith(suffix)) ? EXECUTABLE_MODE : READABLE_MODE;
+};
+
+const assertInsideRoot = (root: string, rel: string, abs: string): void => {
+    const escape = relative(root, abs);
+
+    if (escape.length === 0 || escape.startsWith("..") || isAbsolute(escape)) {
+        throw new Error(`Cannot stage "${rel}": it resolves outside the staging directory`);
+    }
+};
+
+const placeFile = (root: string, rel: string, mode: number, write: (target: string) => void): StagedFile => {
+    const abs = join(root, rel);
+    assertInsideRoot(root, rel, abs);
+    mkdirSync(dirname(abs), { recursive: true });
+    write(abs);
+    chmodSync(abs, mode);
+
+    return { rel, abs, mode };
+};
+
+const copyInto = (root: string, rel: string, source: string, mode = modeFor(rel)): StagedFile =>
+    placeFile(root, rel, mode, (target) => {
+        copyFileSync(source, target);
+    });
+
+const writeInto = (root: string, rel: string, contents: string, mode = READABLE_MODE): StagedFile =>
+    placeFile(root, rel, mode, (target) => {
+        writeFileSync(target, contents);
+    });
+
+const sourceMode = (path: string): number => statSync(path).mode & MODE_MASK;
+
+const copyTree = (root: string, relBase: string, sourceDir: string): StagedFile[] =>
+    listFilesRecursive(sourceDir)
+        .map((file) => copyInto(root, join(relBase, file.rel), file.absPath, sourceMode(file.absPath)));
+
+export { copyInto, copyTree, EXECUTABLE_MODE, writeInto };

package/src/deploy/payload/icons.ts

@@ -0,0 +1,80 @@
+import { basename, join } from "node:path";
+import type { DeploySettings, StagedFile } from "../types.js";
+import { listFilesRecursive } from "../../internal/list-files.js";
+import { copyInto } from "./copy-tree.js";
+
+const ICON_EXTENSIONS = [".svg", ".png", ".xpm"];
+const SHARE_ICONS = "share/icons";
+const SCALABLE_DIR = "hicolor/scalable/apps";
+const SIZE_PATTERN = /^(?<width>[1-9]\d{0,3})x(?<height>[1-9]\d{0,3})$/;
+const SIZE_SEPARATORS = /[-_.]/;
+
+const isApplicationIcon = (settings: DeploySettings, rel: string): boolean =>
+    ICON_EXTENSIONS.some((extension) => basename(rel) === `${settings.applicationId}${extension}`);
+
+const getSquareSize = (token: string): number | null => {
+    const groups = SIZE_PATTERN.exec(token)?.groups;
+
+    if (groups === undefined || groups.width !== groups.height) {
+        return null;
+    }
+
+    return Number(groups.width);
+};
+
+const firstSquareSize = (tokens: string[]): number | null =>
+    tokens.map((token) => getSquareSize(token)).find((size) => size !== null) ?? null;
+
+const getIconSize = (rel: string): number | null => firstSquareSize(rel.split("/").slice(0, -1));
+
+const themeDirFor = (file: string): string => {
+    if (file.endsWith(".svg")) {
+        return SCALABLE_DIR;
+    }
+
+    const size = firstSquareSize(basename(file).split(SIZE_SEPARATORS));
+
+    return size === null ? SCALABLE_DIR : `hicolor/${String(size)}x${String(size)}/apps`;
+};
+
+const stageIconTree = (root: string, iconsDir: string): StagedFile[] =>
+    listFilesRecursive(iconsDir).map((file) => copyInto(root, join(SHARE_ICONS, file.rel), file.absPath));
+
+const iconPathFor = (settings: DeploySettings, iconFile: string): string => {
+    const extension = ICON_EXTENSIONS.find((candidate) => iconFile.endsWith(candidate)) ?? ".png";
+
+    return join(themeDirFor(iconFile), `${settings.applicationId}${extension}`);
+};
+
+const stageIconFile = (settings: DeploySettings, root: string, iconFile: string): StagedFile[] =>
+    [copyInto(root, join(SHARE_ICONS, iconPathFor(settings, iconFile)), iconFile)];
+
+const assertApplicationIcon = (settings: DeploySettings, staged: StagedFile[]): void => {
+    if (staged.some((file) => isApplicationIcon(settings, file.rel))) {
+        return;
+    }
+
+    throw new Error(
+        `Cannot deploy without an application icon: no ${settings.applicationId}.svg or ` +
+        `${settings.applicationId}.png under ${settings.paths.iconsDir ?? "the project's icon directory"}. ` +
+        "The desktop entry names " +
+        `"${settings.applicationId}" as its icon, so the file has to match. ` +
+        `Add ${settings.paths.dataDir ?? "data"}/icons/hicolor/scalable/apps/${settings.applicationId}.svg, ` +
+        "or point `deploy.icons` at one.",
+    );
+};
+
+const stageIcons = (settings: DeploySettings, root: string): StagedFile[] => {
+    const { iconsDir, iconFile } = settings.paths;
+
+    if (iconFile !== null) {
+        return stageIconFile(settings, root, iconFile);
+    }
+
+    const staged = iconsDir === null ? [] : stageIconTree(root, iconsDir);
+    assertApplicationIcon(settings, staged);
+
+    return staged;
+};
+
+export { getIconSize, iconPathFor, stageIcons };

package/src/deploy/payload/launcher.ts

@@ -0,0 +1,27 @@
+import type { DeploySettings } from "../types.js";
+import { BUNDLE_FILENAME } from "../../vite-plugins/esm-extension.js";
+
+const NODE_FILENAME = "node";
+
+const compileCacheLines = (binaryName: string): string[] => [
+    "cache_home=${XDG_CACHE_HOME:-${HOME:-/tmp}/.cache}",
+    `NODE_COMPILE_CACHE="$cache_home/${binaryName}/node"`,
+    "export NODE_COMPILE_CACHE",
+];
+
+const renderLauncher = (settings: DeploySettings): string => {
+    const libDir = `$prefix/lib/${settings.binaryName}`;
+    const shouldUseCompileCache = settings.deploy.node?.shouldUseCompileCache !== false;
+
+    return [
+        "#!/bin/sh",
+        "set -e",
+        'self=$(readlink -f "$0")',
+        'prefix=$(dirname "$(dirname "$self")")',
+        ...(shouldUseCompileCache ? compileCacheLines(settings.binaryName) : []),
+        `exec "${libDir}/${NODE_FILENAME}" "${libDir}/${BUNDLE_FILENAME}" "$@"`,
+        "",
+    ].join("\n");
+};
+
+export { NODE_FILENAME, renderLauncher };

package/src/deploy/payload/schemas.ts

@@ -0,0 +1,27 @@
+import { basename, join } from "node:path";
+import type { DeploySettings, StagedFile } from "../types.js";
+import { copyInto } from "./copy-tree.js";
+
+const SHARE_SCHEMAS = "share/glib-2.0/schemas";
+
+const assertSchemaName = (settings: DeploySettings, file: string): void => {
+    const name = basename(file);
+
+    if (name.startsWith(settings.applicationId)) {
+        return;
+    }
+
+    throw new Error(
+        `Cannot install "${name}": every installed GSettings schema shares one system directory, so its file name ` +
+        `has to start with the application id. Rename it to ${settings.applicationId}.gschema.xml.`,
+    );
+};
+
+const stageSchemas = (settings: DeploySettings, root: string): StagedFile[] =>
+    settings.paths.schemaFiles.map((file) => {
+        assertSchemaName(settings, file);
+
+        return copyInto(root, join(SHARE_SCHEMAS, basename(file)), file);
+    });
+
+export { stageSchemas };

package/src/deploy/payload/stage.ts

@@ -0,0 +1,145 @@
+import { sortStringsBy } from "@gtkx/utils";
+import { existsSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { DeploySettings, DeployTargetName, NodeRuntime, StagedFile } from "../types.js";
+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 { renderDesktopEntry } from "../freedesktop/desktop-entry.js";
+import { copyInto, EXECUTABLE_MODE, writeInto } from "./copy-tree.js";
+import { stageIcons } from "./icons.js";
+import { NODE_FILENAME, renderLauncher } from "./launcher.js";
+import { stageSchemas } from "./schemas.js";
+
+type StageRequest = {
+    settings: DeploySettings;
+    node: NodeRuntime | null;
+    metadata: StagedMetadata;
+};
+
+type StagedMetadata = {
+    desktopEntry: string;
+    metainfo: string;
+    mimePackage: string | null;
+};
+
+const DIST_ICONS_DIR = "icons";
+const SHARE_APPLICATIONS = "share/applications";
+const SHARE_METAINFO = "share/metainfo";
+const SHARE_MIME_PACKAGES = "share/mime/packages";
+const SHARE_DOC = "share/doc";
+const SHARE_LICENSES = "share/licenses";
+const SHARE_DBUS_SERVICES = "share/dbus-1/services";
+
+const PREFIX_FOR: Record<DeployTargetName, string> = {
+    appimage: "/usr",
+    deb: "/usr",
+    flatpak: "/app",
+    rpm: "/usr",
+};
+
+const libDirFor = (settings: DeploySettings): string => `lib/${settings.binaryName}`;
+const isIconAsset = (rel: string): boolean => rel === DIST_ICONS_DIR || rel.startsWith(`${DIST_ICONS_DIR}/`);
+
+const stageRuntimeFiles = (settings: DeploySettings, root: string): StagedFile[] => {
+    const dist = settings.paths.dist;
+
+    if (!existsSync(join(dist, BUNDLE_FILENAME))) {
+        throw new Error(`Cannot deploy: ${join(dist, BUNDLE_FILENAME)} is missing. Run \`gtkx build\` first.`);
+    }
+
+    return listFilesRecursive(dist)
+        .filter((file) => !isIconAsset(file.rel))
+        .map((file) => copyInto(root, join(libDirFor(settings), file.rel), file.absPath));
+};
+
+const stageNodeBinary = (settings: DeploySettings, root: string, node: NodeRuntime | null): StagedFile[] =>
+    node === null ? [] : [copyInto(root, join(libDirFor(settings), NODE_FILENAME), node.path, EXECUTABLE_MODE)];
+
+const stageMetadata = (settings: DeploySettings, root: string, metadata: StagedMetadata): StagedFile[] => [
+    writeInto(root, join(SHARE_APPLICATIONS, `${settings.applicationId}.desktop`), metadata.desktopEntry),
+    writeInto(root, join(SHARE_METAINFO, `${settings.applicationId}.metainfo.xml`), metadata.metainfo),
+    ...(metadata.mimePackage === null
+        ? []
+        : [writeInto(root, join(SHARE_MIME_PACKAGES, `${settings.applicationId}.xml`), metadata.mimePackage)]),
+];
+
+const stageExtraFiles = (settings: DeploySettings, root: string): StagedFile[] =>
+    Object.entries(settings.extraFiles).map(([destination, source]) =>
+        copyInto(root, destination, resolve(settings.paths.root, source)));
+
+const byRelativePath = (files: StagedFile[]): StagedFile[] => {
+    const latest: Map<string, StagedFile> = new Map();
+
+    for (const file of files) {
+        latest.set(file.rel, file);
+    }
+
+    return sortStringsBy(latest.values(), (file) => file.rel);
+};
+
+const stagePayload = ({ settings, node, metadata }: StageRequest): StagedFile[] => {
+    const root = settings.paths.stage;
+    rmSync(root, { recursive: true, force: true, maxRetries: 5 });
+
+    return byRelativePath([
+        writeInto(root, join("bin", settings.binaryName), renderLauncher(settings), EXECUTABLE_MODE),
+        ...stageNodeBinary(settings, root, node),
+        ...stageRuntimeFiles(settings, root),
+        ...stageMetadata(settings, root, metadata),
+        ...stageIcons(settings, root),
+        ...stageSchemas(settings, root),
+        ...stageExtraFiles(settings, root),
+    ]);
+};
+
+const stageActivation = (settings: DeploySettings, root: string, target: DeployTargetName): StagedFile[] => {
+    if (!settings.isDbusActivatable) {
+        return [];
+    }
+
+    if (target === "appimage") {
+        return [writeInto(
+            root,
+            join(SHARE_APPLICATIONS, `${settings.applicationId}.desktop`),
+            renderDesktopEntry({ ...settings, isDbusActivatable: false }),
+        )];
+    }
+
+    return [writeInto(
+        root,
+        join(SHARE_DBUS_SERVICES, `${settings.applicationId}.service`),
+        renderDbusService(settings, PREFIX_FOR[target]),
+    )];
+};
+
+const stageOverlay = (settings: DeploySettings, target: DeployTargetName): StagedFile[] => {
+    const root = join(settings.paths.overlay, target);
+    rmSync(root, { recursive: true, force: true, maxRetries: 5 });
+    const licenseFile = settings.paths.licenseFile;
+    const activation = stageActivation(settings, root, target);
+
+    if (target === "deb") {
+        return [
+            ...activation,
+            writeInto(root, join(SHARE_DOC, settings.binaryName, "copyright"), renderCopyright(settings)),
+        ];
+    }
+
+    return [
+        ...activation,
+        ...(licenseFile === null
+            ? []
+            : [copyInto(root, join(SHARE_LICENSES, settings.binaryName, "LICENSE"), licenseFile)]),
+    ];
+};
+
+const stageOverlays = (settings: DeploySettings): Record<DeployTargetName, StagedFile[]> => ({
+    appimage: stageOverlay(settings, "appimage"),
+    deb: stageOverlay(settings, "deb"),
+    flatpak: stageOverlay(settings, "flatpak"),
+    rpm: stageOverlay(settings, "rpm"),
+});
+
+export { type StagedMetadata, stageOverlays, stagePayload };

package/src/deploy/registry.ts

@@ -0,0 +1,40 @@
+import { sortStrings } from "@gtkx/utils";
+import type { DeployTarget, DeployTargetName } from "./types.js";
+import { appimageTarget } from "./targets/appimage.js";
+import { debTarget } from "./targets/deb.js";
+import { flatpakTarget } from "./targets/flatpak.js";
+import { rpmTarget } from "./targets/rpm.js";
+
+const TARGETS: Record<DeployTargetName, DeployTarget> = {
+    appimage: appimageTarget,
+    deb: debTarget,
+    flatpak: flatpakTarget,
+    rpm: rpmTarget,
+};
+
+const DEFAULT_TARGETS: DeployTargetName[] = ["flatpak"];
+const KNOWN_NAMES = sortStrings(Object.keys(TARGETS)).join(", ");
+
+const isTargetName = (name: string): name is DeployTargetName => Object.hasOwn(TARGETS, name);
+
+const assertKnown = (name: string): DeployTargetName => {
+    if (!isTargetName(name)) {
+        throw new Error(`Unknown deploy target "${name}"; known targets are ${KNOWN_NAMES}`);
+    }
+
+    return name;
+};
+
+const targetsFor = (names: string[]): DeployTarget[] => {
+    const requested = [...new Set(names.map((name) => assertKnown(name.trim())))];
+
+    if (requested.length === 0) {
+        throw new Error(`Cannot deploy without a target; choose from ${KNOWN_NAMES}`);
+    }
+
+    return sortStrings(requested).map((name) => TARGETS[assertKnown(name)]);
+};
+
+const parseTargetList = (value: string): string[] => value.split(",").map((name) => name.trim()).filter(Boolean);
+
+export { DEFAULT_TARGETS, KNOWN_NAMES, parseTargetList, targetsFor };