@gtkx/cli 1.0.0-rc.4 → 1.1.0

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

package/src/deploy/run-deploy.ts

@@ -0,0 +1,235 @@
+import { loadConfig } from "@gtkx/config";
+import { info, warn } from "@gtkx/utils";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import type {
+    DeployArtifact,
+    DeployManifest,
+    DeployPayload,
+    DeploySettings,
+    DeployTarget,
+    DeployTool,
+} from "./types.js";
+import { build as buildApp } from "../builder.js";
+import { ensureGenerated } from "../codegen/run-codegen.js";
+import { renderDesktopEntry } from "./freedesktop/desktop-entry.js";
+import { renderMetainfo } from "./freedesktop/metainfo.js";
+import { renderMimePackage } from "./freedesktop/mime-package.js";
+import { validateDesktopEntry, validateMetainfo } from "./freedesktop/validate.js";
+import { resolveNodeRuntime } from "./node-runtime/index.js";
+import { type StagedMetadata, stageOverlays, stagePayload } from "./payload/stage.js";
+import { DEFAULT_TARGETS, parseTargetList, targetsFor } from "./registry.js";
+import { resolveDeploySettings } from "./settings/index.js";
+import { readPackageManifest } from "./settings/package-manifest.js";
+import { missingDeployError } from "./settings/starter.js";
+import {
+    APPSTREAMCLI,
+    assertTools,
+    DESKTOP_FILE_VALIDATE,
+    FLATPAK_NODE_GENERATOR,
+    probeTools,
+    STRIP,
+    TAR,
+    warnMissingOptional,
+} from "./tools.js";
+
+type DeployOptions = {
+    entry: string;
+    cwd: string;
+    targets?: string | undefined;
+    outDir?: string | undefined;
+    shouldPrintManifests: boolean;
+    shouldSkipBuild: boolean;
+};
+
+const BUILD_MODE = "production";
+const BYTES_PER_MIB = 1024 * 1024;
+const WEBKIT_LIBRARY = "WebKit-6.0";
+const NETWORK_ARG = "--share=network";
+
+const displayPath = (settings: DeploySettings, path: string): string => relative(settings.paths.root, path);
+const megabytes = (size: number): string => (size / BYTES_PER_MIB).toFixed(1);
+
+const writeManifest = (manifest: DeployManifest): void => {
+    mkdirSync(dirname(manifest.path), { recursive: true });
+    writeFileSync(manifest.path, manifest.contents);
+};
+
+const renderMetadata = (settings: DeploySettings): StagedMetadata => ({
+    desktopEntry: renderDesktopEntry(settings),
+    metainfo: renderMetainfo(settings),
+    mimePackage: renderMimePackage(settings),
+});
+
+const isFlathubSubmission = (settings: DeploySettings, targets: DeployTarget[]): boolean =>
+    settings.deploy.flatpak?.mode === "source" && targets.some((target) => target.name === "flatpak");
+
+const validateMetadata = (settings: DeploySettings, metadata: StagedMetadata, areWarningsFatal: boolean): void => {
+    const dir = settings.paths.metadata;
+    mkdirSync(dir, { recursive: true });
+    const desktopPath = join(dir, `${settings.applicationId}.desktop`);
+    const metainfoPath = join(dir, `${settings.applicationId}.metainfo.xml`);
+    writeFileSync(desktopPath, metadata.desktopEntry);
+    writeFileSync(metainfoPath, metadata.metainfo);
+    validateDesktopEntry(desktopPath);
+    validateMetainfo(metainfoPath, areWarningsFatal);
+    info("Validated the desktop entry and the metainfo");
+};
+
+const warnMissingNetwork = (settings: DeploySettings): void => {
+    const finishArgs = settings.deploy.flatpak?.finishArgs;
+
+    if (finishArgs === undefined || finishArgs.includes(NETWORK_ARG)) {
+        return;
+    }
+
+    if (!settings.libraries.includes(WEBKIT_LIBRARY)) {
+        return;
+    }
+
+    warn(`This app declares ${WEBKIT_LIBRARY} but its flatpak permissions omit ${NETWORK_ARG}, so pages will not load`);
+};
+
+const sourceModeTools = (targets: DeployTarget[], settings: DeploySettings): DeployTool[] => {
+    const isFlatpakSource = settings.deploy.flatpak?.mode === "source";
+
+    return isFlatpakSource && targets.some((target) => target.name === "flatpak") ? [FLATPAK_NODE_GENERATOR] : [];
+};
+
+const isNodeRequired = (targets: DeployTarget[], settings: DeploySettings): boolean =>
+    !(settings.deploy.flatpak?.mode === "source" && targets.every((target) => target.name === "flatpak"));
+
+const runtimeToolsFor = (targets: DeployTarget[], settings: DeploySettings): DeployTool[] => {
+    if (!isNodeRequired(targets, settings)) {
+        return [];
+    }
+
+    const node = settings.deploy.node ?? {};
+    const archiveTools = (node.source ?? "download") === "download" ? [TAR] : [];
+
+    return node.shouldStrip === false ? archiveTools : [...archiveTools, STRIP];
+};
+
+const preflight = (targets: DeployTarget[], settings: DeploySettings, shouldPrintManifests: boolean): void => {
+    const packagerTools = shouldPrintManifests
+        ? []
+        : [...runtimeToolsFor(targets, settings), ...targets.flatMap((target) => target.tools)];
+
+    const required = [DESKTOP_FILE_VALIDATE, APPSTREAMCLI, ...sourceModeTools(targets, settings)];
+    const report = probeTools([...required, ...packagerTools]);
+    assertTools(report);
+    warnMissingOptional(report);
+    warnMissingNetwork(settings);
+};
+
+const resolveTargetNames = (options: DeployOptions, settings: DeploySettings): string[] => {
+    if (options.targets !== undefined) {
+        return parseTargetList(options.targets);
+    }
+
+    return settings.deploy.targets ?? DEFAULT_TARGETS;
+};
+
+const loadSettings = async (options: DeployOptions): Promise<DeploySettings> => {
+    const { config, root } = await loadConfig(options.cwd, { mode: BUILD_MODE });
+
+    if (config.deploy === undefined) {
+        throw missingDeployError(config.applicationId, readPackageManifest(root));
+    }
+
+    return resolveDeploySettings({ root, config, outDirOverride: options.outDir });
+};
+
+const buildPayload = async (
+    options: DeployOptions,
+    settings: DeploySettings,
+    targets: DeployTarget[],
+): Promise<DeployPayload> => {
+    const metadata = renderMetadata(settings);
+    validateMetadata(settings, metadata, isFlathubSubmission(settings, targets));
+
+    if (!options.shouldSkipBuild) {
+        info(`Building ${options.entry}`);
+        await buildApp({ entry: options.entry, vite: { root: options.cwd } });
+    }
+
+    const node = options.shouldPrintManifests || !isNodeRequired(targets, settings)
+        ? null
+        : await resolveNodeRuntime(settings);
+
+    const stage = stagePayload({ settings, node, metadata });
+    info(`Staged ${String(stage.length)} files into ${displayPath(settings, settings.paths.stage)}`);
+
+    return { settings, node, stage, overlays: stageOverlays(settings) };
+};
+
+const renderTargetManifests = (
+    targets: DeployTarget[],
+    payload: DeployPayload,
+): Map<DeployTarget, DeployManifest[]> => {
+    const rendered: Map<DeployTarget, DeployManifest[]> = new Map();
+
+    for (const target of targets) {
+        const manifests = target.render(payload);
+
+        for (const manifest of manifests) {
+            writeManifest(manifest);
+            info(`Wrote ${displayPath(payload.settings, manifest.path)}`);
+        }
+
+        rendered.set(target, manifests);
+    }
+
+    return rendered;
+};
+
+const packTargets = async (
+    rendered: Map<DeployTarget, DeployManifest[]>,
+    payload: DeployPayload,
+): Promise<DeployArtifact[]> => {
+    const artifacts: DeployArtifact[] = [];
+
+    for (const [target, manifests] of rendered) {
+        const built = await target.pack(payload, manifests);
+
+        for (const artifact of built) {
+            info(`Built ${displayPath(payload.settings, artifact.path)} (${megabytes(artifact.size)} MiB)`);
+        }
+
+        artifacts.push(...built);
+    }
+
+    return artifacts;
+};
+
+const announce = (settings: DeploySettings, targets: DeployTarget[]): void => {
+    const names = targets.map((target) => target.name).join(", ");
+    const version = `${settings.versions.packageVersion}-${settings.versions.debRevision}`;
+    info(`Deploying ${settings.name} ${version} as ${settings.binaryName} (${settings.arch.rpm}) to ${names}`);
+};
+
+const runDeploy = async (options: DeployOptions): Promise<void> => {
+    if (!options.shouldSkipBuild) {
+        await ensureGenerated(options.cwd, { shouldAnnounce: true, mode: BUILD_MODE });
+    }
+
+    const settings = await loadSettings(options);
+    const targets = targetsFor(resolveTargetNames(options, settings));
+    announce(settings, targets);
+    preflight(targets, settings, options.shouldPrintManifests);
+    const payload = await buildPayload(options, settings, targets);
+    const rendered = renderTargetManifests(targets, payload);
+
+    if (options.shouldPrintManifests) {
+        const count = rendered.values().toArray().flat().length;
+        info(`Wrote ${String(count)} manifests, 0 packages built`);
+
+        return;
+    }
+
+    const artifacts = await packTargets(rendered, payload);
+    const output = displayPath(settings, settings.paths.output);
+    info(`Deploy complete: ${String(artifacts.length)} artifacts in ${output}`);
+};
+
+export { runDeploy };

package/src/deploy/settings/arch.ts

@@ -0,0 +1,18 @@
+import type { DeployArch } from "../types.js";
+
+const ARCH_TABLE: Record<string, DeployArch> = {
+    arm64: { deb: "arm64", rpm: "aarch64", flatpak: "aarch64", appimage: "aarch64", node: "arm64" },
+    x64: { deb: "amd64", rpm: "x86_64", flatpak: "x86_64", appimage: "x86_64", node: "x64" },
+};
+
+const resolveArch = (arch: string = process.arch): DeployArch => {
+    const resolved = ARCH_TABLE[arch];
+
+    if (resolved === undefined) {
+        throw new Error(`Cannot deploy for ${arch}: only ${Object.keys(ARCH_TABLE).join(" and ")} are supported`);
+    }
+
+    return resolved;
+};
+
+export { resolveArch };

package/src/deploy/settings/categories.ts

@@ -0,0 +1,39 @@
+type CategoryMapping = {
+    section: string;
+    group: string;
+};
+
+const DEFAULT_MAPPING: CategoryMapping = { section: "misc", group: "Applications/System" };
+
+const MAPPING_BY_CATEGORY: Record<string, CategoryMapping> = {
+    Audio: { section: "sound", group: "Applications/Multimedia" },
+    AudioVideo: { section: "sound", group: "Applications/Multimedia" },
+    Development: { section: "devel", group: "Development/Tools" },
+    Education: { section: "education", group: "Applications/Education" },
+    Game: { section: "games", group: "Amusements/Games" },
+    Graphics: { section: "graphics", group: "Applications/Multimedia" },
+    Network: { section: "net", group: "Applications/Internet" },
+    Office: { section: "gnome", group: "Applications/Productivity" },
+    Science: { section: "science", group: "Applications/Engineering" },
+    Settings: { section: "gnome", group: "Applications/System" },
+    System: { section: "admin", group: "Applications/System" },
+    Utility: { section: "utils", group: "Applications/Utilities" },
+    Video: { section: "video", group: "Applications/Multimedia" },
+};
+
+const mappingForCategories = (categories: string[]): CategoryMapping => {
+    for (const category of categories) {
+        const mapping = MAPPING_BY_CATEGORY[category];
+
+        if (mapping !== undefined) {
+            return mapping;
+        }
+    }
+
+    return DEFAULT_MAPPING;
+};
+
+const sectionForCategories = (categories: string[]): string => mappingForCategories(categories).section;
+const groupForCategories = (categories: string[]): string => mappingForCategories(categories).group;
+
+export { groupForCategories, sectionForCategories };

package/src/deploy/settings/exec.ts

@@ -0,0 +1,29 @@
+import type { DeployConfig, DeployFileAssociation } from "../types.js";
+
+const SCHEME_HANDLER_PREFIX = "x-scheme-handler/";
+
+const resolveFileAssociations = (deploy: DeployConfig): DeployFileAssociation[] =>
+    (deploy.fileAssociations ?? []).map((entry) => ({
+        extension: entry.extension,
+        mimeType: entry.mimeType,
+        description: entry.description ?? null,
+    }));
+
+const resolveMimeTypes = (deploy: DeployConfig): string[] => {
+    const fromAssociations = (deploy.fileAssociations ?? []).map((entry) => entry.mimeType);
+    const fromProtocols = (deploy.protocols ?? []).map((scheme) => `${SCHEME_HANDLER_PREFIX}${scheme}`);
+
+    return [...new Set([...(deploy.mimeTypes ?? []), ...fromAssociations, ...fromProtocols])];
+};
+
+const resolveExecToken = (deploy: DeployConfig): string | null => {
+    const mimeTypes = resolveMimeTypes(deploy);
+
+    if (mimeTypes.length === 0) {
+        return null;
+    }
+
+    return mimeTypes.some((mimeType) => mimeType.startsWith(SCHEME_HANDLER_PREFIX)) ? "%U" : "%F";
+};
+
+export { resolveExecToken, resolveFileAssociations, resolveMimeTypes };