@gtkx/cli 1.0.0 → 1.1.0

package/src/deploy/targets/flatpak-source.ts

@@ -0,0 +1,168 @@
+import { posix, relative } from "node:path";
+import type { DeployPayload, DeploySettings } from "../types.js";
+import { listFilesRecursive } from "../../internal/list-files.js";
+import { BUNDLE_FILENAME } from "../../vite-plugins/esm-extension.js";
+import { renderDbusService } from "../freedesktop/dbus-service.js";
+import { renderDesktopEntry } from "../freedesktop/desktop-entry.js";
+import { renderMetainfo } from "../freedesktop/metainfo.js";
+import { optional } from "../nfpm/optional.js";
+import { iconPathFor } from "../payload/icons.js";
+import { renderLauncher } from "../payload/launcher.js";
+import { DESTINATION, type FlatpakModule, postInstallCommands, validationCommands } from "./flatpak-prebuilt.js";
+import {
+    detectPackageManager,
+    GENERATED_SOURCES,
+    installCommandFor,
+    nodeExtensionPathFor,
+    type PackageManager,
+    resolveGitSource,
+} from "./flatpak-sources.js";
+
+const LAUNCHER_FILENAME = "launcher.sh";
+const MODULE_BUILD_ROOT = "/run/build";
+const RUNTIME_PREFIX = "/app";
+const NPM_CACHE_DIR = "flatpak-node/npm-cache";
+const YARN_MIRROR_DIR = "flatpak-node/yarn-mirror";
+const PLAIN_ARGUMENT = /^[\w./-]+$/;
+const QUOTE_ESCAPE = String.raw`'\''`;
+
+const inlineSource = (fileName: string, contents: string): FlatpakModule => ({
+    type: "inline",
+    "dest-filename": fileName,
+    contents,
+});
+
+const projectRelative = (settings: DeploySettings, path: string): string =>
+    relative(settings.paths.root, path).replaceAll("\\", "/");
+
+const shellArgument = (value: string): string =>
+    PLAIN_ARGUMENT.test(value) ? value : `'${value.split("'").join(QUOTE_ESCAPE)}'`;
+
+const pathArgument = (value: string): string => shellArgument(value.startsWith("-") ? `./${value}` : value);
+
+const installCommand = (source: string, destination: string, mode: string): string =>
+    `install -D${mode} ${pathArgument(source)} ${destination}`;
+
+const runtimeInstallCommands = (settings: DeploySettings, nodeExtensionPath: string): string[] => {
+    const lib = `${DESTINATION}/lib/${settings.binaryName}`;
+
+    return [
+        installCommand(`${nodeExtensionPath}/bin/node`, `${lib}/node`, "m755"),
+        installCommand(`dist/${BUNDLE_FILENAME}`, `${lib}/${BUNDLE_FILENAME}`, "m644"),
+        installCommand("dist/gtkx.node", `${lib}/gtkx.node`, "m755"),
+        "test ! -f dist/gtkx.gresource || " + installCommand("dist/gtkx.gresource", `${lib}/gtkx.gresource`, "m644"),
+        "test ! -f dist/gschemas.compiled || " +
+        installCommand("dist/gschemas.compiled", `${lib}/gschemas.compiled`, "m644"),
+        `test ! -d dist/assets || cp -a dist/assets ${lib}/assets`,
+        installCommand(LAUNCHER_FILENAME, `${DESTINATION}/bin/${settings.binaryName}`, "m755"),
+    ];
+};
+
+const activationSource = (settings: DeploySettings): FlatpakModule[] =>
+    settings.isDbusActivatable
+        ? [inlineSource(`${settings.applicationId}.service`, renderDbusService(settings, RUNTIME_PREFIX))]
+        : [];
+
+const activationInstallCommands = (settings: DeploySettings): string[] =>
+    settings.isDbusActivatable
+        ? [installCommand(
+                `${settings.applicationId}.service`,
+                `${DESTINATION}/share/dbus-1/services/${settings.applicationId}.service`,
+                "m644",
+            )]
+        : [];
+
+const metadataInstallCommands = (settings: DeploySettings): string[] => [
+    installCommand(
+        `${settings.applicationId}.desktop`,
+        `${DESTINATION}/share/applications/${settings.applicationId}.desktop`,
+        "m644",
+    ),
+    installCommand(
+        `${settings.applicationId}.metainfo.xml`,
+        `${DESTINATION}/share/metainfo/${settings.applicationId}.metainfo.xml`,
+        "m644",
+    ),
+    ...activationInstallCommands(settings),
+];
+
+const schemaInstallCommands = (settings: DeploySettings): string[] =>
+    settings.paths.schemaFiles.map((file) => {
+        const name = posix.basename(file);
+
+        return installCommand(
+            projectRelative(settings, file),
+            `${DESTINATION}/share/glib-2.0/schemas/${shellArgument(name)}`,
+            "m644",
+        );
+    });
+
+const iconInstallCommand = (settings: DeploySettings, source: string, rel: string): string =>
+    installCommand(
+        projectRelative(settings, source),
+        `${DESTINATION}/share/icons/${shellArgument(rel.replaceAll("\\", "/"))}`,
+        "m644",
+    );
+
+const iconInstallCommands = (settings: DeploySettings): string[] => {
+    const { iconsDir, iconFile } = settings.paths;
+
+    if (iconFile !== null) {
+        return [iconInstallCommand(settings, iconFile, iconPathFor(settings, iconFile))];
+    }
+
+    if (iconsDir === null) {
+        return [];
+    }
+
+    return listFilesRecursive(iconsDir).map((icon) => iconInstallCommand(settings, icon.absPath, icon.rel));
+};
+
+const offlineEnvFor = (manager: PackageManager, settings: DeploySettings): Record<string, string> => {
+    const moduleDir = `${MODULE_BUILD_ROOT}/${settings.binaryName}`;
+
+    if (manager === "yarn") {
+        return { YARN_OFFLINE_MIRROR: `${moduleDir}/${YARN_MIRROR_DIR}` };
+    }
+
+    return { npm_config_cache: `${moduleDir}/${NPM_CACHE_DIR}`, npm_config_offline: "true" };
+};
+
+const flatpakSourceModule = (payload: DeployPayload): FlatpakModule => {
+    const settings = payload.settings;
+    const manager = detectPackageManager(settings);
+    const postInstall = postInstallCommands(payload);
+    const nodeExtensionPath = nodeExtensionPathFor(settings);
+
+    return {
+        name: settings.binaryName,
+        buildsystem: "simple",
+        "build-options": {
+            "append-path": `${nodeExtensionPath}/bin`,
+            env: { npm_config_nodedir: nodeExtensionPath, ...offlineEnvFor(manager, settings) },
+            strip: false,
+            "no-debuginfo": true,
+        },
+        sources: [
+            resolveGitSource(settings),
+            GENERATED_SOURCES,
+            inlineSource(`${settings.applicationId}.desktop`, renderDesktopEntry(settings)),
+            inlineSource(`${settings.applicationId}.metainfo.xml`, renderMetainfo(settings)),
+            inlineSource(LAUNCHER_FILENAME, renderLauncher(settings)),
+            ...activationSource(settings),
+        ],
+        "build-commands": [
+            installCommandFor(manager),
+            "npx gtkx build",
+            ...runtimeInstallCommands(settings, nodeExtensionPath),
+            ...metadataInstallCommands(settings),
+            ...schemaInstallCommands(settings),
+            ...iconInstallCommands(settings),
+            ...(settings.deploy.flatpak?.buildCommands ?? []),
+            ...validationCommands(settings),
+        ],
+        ...optional("post-install", postInstall.length === 0 ? undefined : postInstall),
+    };
+};
+
+export { flatpakSourceModule };

package/src/deploy/targets/flatpak-sources.ts

@@ -0,0 +1,171 @@
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import type { DeploySettings } from "../types.js";
+import { runCliTool } from "../../internal/run-cli-tool.js";
+import { gitRemoteUrl, runGit } from "../git.js";
+import { optional } from "../nfpm/optional.js";
+
+type PackageManager = "npm" | "pnpm" | "yarn";
+
+type GitSource = {
+    type: "git";
+    url: string;
+    tag?: string;
+    commit?: string;
+};
+
+type GitRevision = {
+    tag?: string;
+    commit?: string;
+};
+
+const GENERATED_SOURCES = "generated-sources.json";
+const GENERATOR = "flatpak-node-generator";
+const FETCHABLE_URL = /^https?:\/\//;
+const DEFAULT_NODE_EXTENSION = "org.freedesktop.Sdk.Extension.node24";
+const NODE_EXTENSION_PREFIX = "org.freedesktop.Sdk.Extension.";
+const SDK_EXTENSION_ROOT = "/usr/lib/sdk";
+
+const LOCKFILE_BY_MANAGER: Record<PackageManager, string> = {
+    npm: "package-lock.json",
+    pnpm: "pnpm-lock.yaml",
+    yarn: "yarn.lock",
+};
+
+const INSTALL_COMMAND: Record<PackageManager, string> = {
+    npm: "npm ci --offline",
+    pnpm: "pnpm install --offline --frozen-lockfile",
+    yarn: "yarn install --offline",
+};
+
+const detectPackageManager = (settings: DeploySettings): PackageManager => {
+    const configured = settings.deploy.flatpak?.packageManager;
+
+    if (configured !== undefined) {
+        return configured;
+    }
+
+    const found = (["pnpm", "yarn", "npm"] as const)
+        .find((manager) => existsSync(join(settings.paths.root, LOCKFILE_BY_MANAGER[manager])));
+
+    if (found === undefined) {
+        throw new Error(
+            "Cannot build a Flathub-ready manifest without a lockfile: the sandbox installs dependencies offline. " +
+            "Commit a package-lock.json, pnpm-lock.yaml, or yarn.lock, or set `deploy.flatpak.packageManager`.",
+        );
+    }
+
+    return found;
+};
+
+const installCommandFor = (manager: PackageManager): string => INSTALL_COMMAND[manager];
+
+const nodeExtensionFor = (settings: DeploySettings): string =>
+    settings.deploy.flatpak?.nodeExtension ?? DEFAULT_NODE_EXTENSION;
+
+const nodeExtensionPathFor = (settings: DeploySettings): string => {
+    const extension = nodeExtensionFor(settings);
+
+    if (!extension.startsWith(NODE_EXTENSION_PREFIX)) {
+        throw new Error(
+            `Cannot resolve where "${extension}" mounts: the sandbox installs Node SDK extensions under ` +
+            `${SDK_EXTENSION_ROOT}, so \`deploy.flatpak.nodeExtension\` has to be an ${NODE_EXTENSION_PREFIX}* id.`,
+        );
+    }
+
+    return `${SDK_EXTENSION_ROOT}/${extension.slice(NODE_EXTENSION_PREFIX.length)}`;
+};
+
+const resolveSourceUrl = (settings: DeploySettings): string => {
+    const url = settings.deploy.flatpak?.source?.url ?? gitRemoteUrl(settings.paths.root);
+
+    if (url === null) {
+        throw new Error(
+            "Cannot build a Flathub-ready manifest without a public source: Flathub builds from a fetchable " +
+            "repository, not from your working tree. Set `deploy.flatpak.source.url`.",
+        );
+    }
+
+    if (!FETCHABLE_URL.test(url)) {
+        throw new Error(
+            `Cannot build a Flathub-ready manifest from "${url}": Flathub's builders clone over HTTPS and have no ` +
+            "credentials, so an SSH remote never resolves there. Set `deploy.flatpak.source.url` to the " +
+            "repository's https:// URL.",
+        );
+    }
+
+    return url;
+};
+
+const configuredRevision = (settings: DeploySettings): GitRevision | null => {
+    const source = settings.deploy.flatpak?.source ?? {};
+
+    if (source.commit !== undefined) {
+        return { ...optional("tag", source.tag), commit: source.commit };
+    }
+
+    return source.tag === undefined ? null : { tag: source.tag };
+};
+
+const workingTreeRevision = (settings: DeploySettings): GitRevision => {
+    const root = settings.paths.root;
+
+    return {
+        ...optional("tag", runGit(root, ["describe", "--tags", "--exact-match"]) ?? undefined),
+        ...optional("commit", runGit(root, ["rev-parse", "HEAD"]) ?? undefined),
+    };
+};
+
+const resolveGitSource = (settings: DeploySettings): GitSource => ({
+    type: "git",
+    url: resolveSourceUrl(settings),
+    ...(configuredRevision(settings) ?? workingTreeRevision(settings)),
+});
+
+const generatedSourcesPath = (settings: DeploySettings): string =>
+    join(settings.paths.targets, "flatpak", GENERATED_SOURCES);
+
+const isolateLockfile = (root: string, lockfile: string): string => {
+    const source = join(root, lockfile);
+
+    if (!existsSync(source)) {
+        throw new Error(`Cannot vendor the offline sources: no ${lockfile} under ${root}`);
+    }
+
+    const manifest = join(dirname(source), "package.json");
+    const dir = mkdtempSync(join(tmpdir(), "gtkx-lockfile-"));
+    copyFileSync(existsSync(manifest) ? manifest : join(root, "package.json"), join(dir, "package.json"));
+    copyFileSync(source, join(dir, basename(lockfile)));
+
+    return dir;
+};
+
+const generateNodeSources = (settings: DeploySettings, manager: PackageManager): void => {
+    const lockfile = settings.deploy.flatpak?.lockfile ?? LOCKFILE_BY_MANAGER[manager];
+    const output = generatedSourcesPath(settings);
+    mkdirSync(dirname(output), { recursive: true });
+    const isolated = isolateLockfile(settings.paths.root, lockfile);
+
+    try {
+        runCliTool({
+            tool: GENERATOR,
+            args: [manager, join(isolated, basename(lockfile)), "-o", output],
+            target: "the offline npm sources",
+            shouldStream: true,
+        });
+    } finally {
+        rmSync(isolated, { recursive: true, force: true, maxRetries: 5 });
+    }
+};
+
+export {
+    detectPackageManager,
+    GENERATED_SOURCES,
+    generateNodeSources,
+    installCommandFor,
+    nodeExtensionFor,
+    nodeExtensionPathFor,
+    type PackageManager,
+    resolveGitSource,
+};

package/src/deploy/targets/flatpak.ts

@@ -0,0 +1,143 @@
+import { errorMessage, info, tryResolveExecutable } from "@gtkx/utils";
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import type { DeployArtifact, DeployManifest, DeployPayload, DeploySettings, DeployTarget } from "../types.js";
+import { runCliTool } from "../../internal/run-cli-tool.js";
+import { APPSTREAMCLI, DESKTOP_FILE_VALIDATE, FLATPAK, FLATPAK_BUILDER } from "../tools.js";
+import { branchFor, renderFlatpakManifest } from "./flatpak-manifest.js";
+import { detectPackageManager, generateNodeSources } from "./flatpak-sources.js";
+
+type BuilderInvocation = {
+    tool: string;
+    prefix: string[];
+};
+
+const PREFIX = "/app";
+const TARGET_DIR = "flatpak";
+const FLATHUB_REPO = "https://dl.flathub.org/repo/flathub.flatpakrepo";
+const BUILDER_REF = "org.flatpak.Builder";
+
+const flatpakTarget: DeployTarget = {
+    name: "flatpak",
+    prefix: PREFIX,
+    tools: [FLATPAK, FLATPAK_BUILDER, DESKTOP_FILE_VALIDATE, APPSTREAMCLI],
+    render: (payload) => renderManifests(payload),
+    pack: (payload) => Promise.try(() => packFlatpak(payload)),
+};
+
+const flatpakDir = (settings: DeploySettings): string => join(settings.paths.targets, TARGET_DIR);
+
+const manifestPathFor = (settings: DeploySettings): string =>
+    join(flatpakDir(settings), `${settings.applicationId}.yml`);
+
+const resolveBuilder = (): BuilderInvocation => {
+    if (tryResolveExecutable(FLATPAK_BUILDER.command) !== undefined) {
+        return { tool: FLATPAK_BUILDER.command, prefix: [] };
+    }
+
+    return { tool: FLATPAK.command, prefix: ["run", BUILDER_REF] };
+};
+
+const isSourceMode = (settings: DeploySettings): boolean => settings.deploy.flatpak?.mode === "source";
+
+const renderManifests = (payload: DeployPayload): DeployManifest[] => {
+    const settings = payload.settings;
+
+    if (isSourceMode(settings)) {
+        generateNodeSources(settings, detectPackageManager(settings));
+    }
+
+    return [{
+        path: manifestPathFor(settings),
+        contents: stringify(renderFlatpakManifest(payload), { lineWidth: 0 }),
+    }];
+};
+
+const builderArgsFor = (settings: DeploySettings, dir: string): string[] => [
+    "--force-clean",
+    "--user",
+    "--install-deps-from=flathub",
+    `--default-branch=${branchFor(settings)}`,
+    ...(settings.deploy.flatpak?.shouldUseRofilesFuse === false ? ["--disable-rofiles-fuse"] : []),
+    `--state-dir=${join(dir, "state")}`,
+    `--repo=${join(dir, "repo")}`,
+    join(dir, "build"),
+    manifestPathFor(settings),
+];
+
+const buildFlatpak = (settings: DeploySettings): void => {
+    const dir = flatpakDir(settings);
+    const builder = resolveBuilder();
+    info("flatpak: running flatpak-builder, this can take several minutes");
+
+    try {
+        runCliTool({
+            tool: builder.tool,
+            args: [...builder.prefix, ...builderArgsFor(settings, dir)],
+            target: "the flatpak",
+            shouldStream: true,
+        });
+    } catch (error) {
+        throw new Error(
+            `${errorMessage(error)}\n\nIf it stopped at "Failure spawning rofiles-fuse", the build is running ` +
+            "somewhere FUSE is unavailable, such as a container. Set `deploy.flatpak.shouldUseRofilesFuse: false` " +
+            "to build without it.",
+            { cause: error },
+        );
+    }
+};
+
+const bundleArgsFor = (settings: DeploySettings, target: string): string[] => {
+    const signing = settings.deploy.signing?.flatpak;
+    const runtimeRepo = settings.deploy.flatpak?.runtimeRepo ?? FLATHUB_REPO;
+
+    return [
+        "build-bundle",
+        join(flatpakDir(settings), "repo"),
+        target,
+        settings.applicationId,
+        branchFor(settings),
+        `--arch=${settings.arch.flatpak}`,
+        `--runtime-repo=${runtimeRepo}`,
+        ...(signing === undefined ? [] : [`--gpg-sign=${signing.gpgKeyId}`]),
+        ...(signing?.gpgHomeDir === undefined ? [] : [`--gpg-homedir=${signing.gpgHomeDir}`]),
+    ];
+};
+
+const bundleFlatpak = (settings: DeploySettings): DeployArtifact => {
+    const output = settings.paths.output;
+    mkdirSync(output, { recursive: true });
+    const version = settings.versions.packageVersion;
+    const target = join(output, `${settings.applicationId}-${version}-${settings.arch.flatpak}.flatpak`);
+    runCliTool({ tool: FLATPAK.command, args: bundleArgsFor(settings, target), target: "the flatpak bundle" });
+
+    if (!existsSync(target)) {
+        throw new Error(`flatpak build-bundle reported success but wrote no bundle at ${target}`);
+    }
+
+    return { path: target, size: statSync(target).size };
+};
+
+const installFlatpak = (settings: DeploySettings): void => {
+    runCliTool({
+        tool: FLATPAK.command,
+        args: ["install", "--user", "--noninteractive", "--reinstall", join(flatpakDir(settings), "repo"),
+            settings.applicationId],
+        target: "the flatpak",
+        shouldStream: true,
+    });
+};
+
+const packFlatpak = (payload: DeployPayload): DeployArtifact[] => {
+    const settings = payload.settings;
+    buildFlatpak(settings);
+
+    if (settings.deploy.flatpak?.shouldInstall === true) {
+        installFlatpak(settings);
+    }
+
+    return settings.deploy.flatpak?.shouldEmitBundle === false ? [] : [bundleFlatpak(settings)];
+};
+
+export { flatpakTarget };

package/src/deploy/targets/nfpm-target.ts

@@ -0,0 +1,33 @@
+import { join } from "node:path";
+import { stringify } from "yaml";
+import type { DeployArtifact, DeployManifest, DeployPayload, DeployTarget } from "../types.js";
+import { type NfpmPackager, renderNfpmConfig } from "../nfpm/config.js";
+import { packWithNfpm } from "../nfpm/pack.js";
+import { TAR } from "../tools.js";
+
+const MANIFEST_FILENAME = "nfpm.yaml";
+const PREFIX = "/usr";
+
+const manifestPathFor = (payload: DeployPayload, packager: NfpmPackager): string =>
+    join(payload.settings.paths.targets, packager, MANIFEST_FILENAME);
+
+const renderManifests = (payload: DeployPayload, packager: NfpmPackager): DeployManifest[] => [
+    {
+        path: manifestPathFor(payload, packager),
+        contents: stringify(renderNfpmConfig(payload, packager), { lineWidth: 0 }),
+    },
+];
+
+const packPackage = async (payload: DeployPayload, packager: NfpmPackager): Promise<DeployArtifact[]> => [
+    await packWithNfpm(payload, packager, manifestPathFor(payload, packager)),
+];
+
+const nfpmTarget = (packager: NfpmPackager): DeployTarget => ({
+    name: packager,
+    prefix: PREFIX,
+    tools: [TAR],
+    render: (payload) => renderManifests(payload, packager),
+    pack: (payload) => packPackage(payload, packager),
+});
+
+export { nfpmTarget };

package/src/deploy/targets/rpm.ts

@@ -0,0 +1,6 @@
+import type { DeployTarget } from "../types.js";
+import { nfpmTarget } from "./nfpm-target.js";
+
+const rpmTarget: DeployTarget = nfpmTarget("rpm");
+
+export { rpmTarget };

package/src/deploy/tools.ts

@@ -0,0 +1,135 @@
+import { tryResolveExecutable, warn } from "@gtkx/utils";
+import { spawnSync } from "node:child_process";
+import type { DeployTool } from "./types.js";
+import { detectPackageFamily, installHints } from "./install-hints.js";
+
+type ToolReport = {
+    missingRequired: DeployTool[];
+    missingOptional: DeployTool[];
+};
+
+const DETAIL_COLUMN = 26;
+const FLATPAK_BUILDER_REF = "org.flatpak.Builder";
+
+const APPSTREAMCLI: DeployTool = {
+    command: "appstreamcli",
+    purpose: "validates the AppStream metainfo",
+    isOptional: false,
+};
+
+const DESKTOP_FILE_VALIDATE: DeployTool = {
+    command: "desktop-file-validate",
+    purpose: "validates the desktop entry",
+    isOptional: false,
+};
+
+const FILE_TOOL: DeployTool = {
+    command: "file",
+    purpose: "required by appimagetool to inspect the payload",
+    isOptional: false,
+};
+
+const FLATPAK: DeployTool = {
+    command: "flatpak",
+    purpose: "installs the runtime and writes the bundle",
+    isOptional: false,
+};
+
+const FLATPAK_BUILDER: DeployTool = {
+    command: "flatpak-builder",
+    purpose: "builds the Flatpak",
+    isOptional: false,
+    isPresent: () =>
+        tryResolveExecutable("flatpak-builder") !== undefined || isFlatpakRefInstalled(FLATPAK_BUILDER_REF),
+};
+
+const FLATPAK_NODE_GENERATOR: DeployTool = {
+    command: "flatpak-node-generator",
+    purpose: "vendors the npm dependencies a Flathub build installs offline",
+    isOptional: false,
+};
+
+const STRIP: DeployTool = {
+    command: "strip",
+    purpose: "would shrink the bundled Node.js by removing its symbols",
+    isOptional: true,
+};
+
+const TAR: DeployTool = {
+    command: "tar",
+    purpose: "unpacks the downloaded Node.js and packaging tools",
+    isOptional: false,
+};
+
+const isFlatpakRefInstalled = (ref: string): boolean => {
+    const flatpak = tryResolveExecutable(FLATPAK.command);
+
+    if (flatpak === undefined) {
+        return false;
+    }
+
+    return spawnSync(flatpak, ["info", ref], { stdio: "ignore" }).status === 0;
+};
+
+const isToolPresent = (tool: DeployTool): boolean =>
+    tool.isPresent === undefined ? tryResolveExecutable(tool.command) !== undefined : tool.isPresent();
+
+const uniqueTools = (tools: DeployTool[]): DeployTool[] =>
+    new Map(tools.map((tool) => [tool.command, tool])).values().toArray();
+
+const probeTools = (tools: DeployTool[]): ToolReport => {
+    const missing = uniqueTools(tools).filter((tool) => !isToolPresent(tool));
+
+    return {
+        missingRequired: missing.filter((tool) => !tool.isOptional),
+        missingOptional: missing.filter((tool) => tool.isOptional),
+    };
+};
+
+const pad = (text: string): string => text.padEnd(DETAIL_COLUMN);
+
+const toolLines = (tool: DeployTool, hints: string[]): string[] => [
+    `  ${pad(tool.command)}${tool.purpose}`,
+    ...hints.map((hint) => `  ${pad("")}${hint}`),
+];
+
+const missingToolsMessage = (report: ToolReport): string => {
+    const family = detectPackageFamily();
+    const required = report.missingRequired.flatMap((tool) => toolLines(tool, installHints(tool.command, family)));
+    const count = report.missingRequired.length;
+    const plural = count === 1 ? "tool is" : "tools are";
+
+    return [
+        `Cannot deploy: ${String(count)} required ${plural} missing.`,
+        "",
+        ...required,
+        "",
+        "Narrow the run with --target if you do not need every package format.",
+    ].join("\n");
+};
+
+const assertTools = (report: ToolReport): void => {
+    if (report.missingRequired.length > 0) {
+        throw new Error(missingToolsMessage(report));
+    }
+};
+
+const warnMissingOptional = (report: ToolReport): void => {
+    for (const tool of report.missingOptional) {
+        warn(`${tool.command} is not installed: it ${tool.purpose}`);
+    }
+};
+
+export {
+    APPSTREAMCLI,
+    FLATPAK_NODE_GENERATOR,
+    assertTools,
+    DESKTOP_FILE_VALIDATE,
+    FILE_TOOL,
+    FLATPAK,
+    FLATPAK_BUILDER,
+    probeTools,
+    STRIP,
+    TAR,
+    warnMissingOptional,
+};