@gtkx/cli 1.0.0-rc.4 → 1.1.0

package/src/deploy/settings/version.ts

@@ -0,0 +1,59 @@
+import { warn } from "@gtkx/utils";
+import type { DeployVersions } from "../types.js";
+
+type VersionRequest = {
+    version: string;
+    release: string | undefined;
+    epoch: number | undefined;
+};
+
+const DEFAULT_RELEASE = "1";
+const BUILD_METADATA_SEPARATOR = "+";
+const LEADING_V = /^v/;
+const PRERELEASE_SEPARATOR = "-";
+const UPSTREAM_PATTERN = /^\d[\d.]*$/;
+const PACKAGE_VERSION_PATTERN = /^\d[\w.+~]*$/;
+const RELEASE_PATTERN = /^\w[\w.+~]*$/;
+
+const stripBuildMetadata = (version: string): string => {
+    const index = version.indexOf(BUILD_METADATA_SEPARATOR);
+
+    if (index === -1) {
+        return version;
+    }
+
+    const stripped = version.slice(0, index);
+
+    warn(
+        `Dropping the build metadata from version "${version}": Debian and RPM cannot express it. ` +
+        `Packaging ${stripped} instead; set \`deploy.release\` to distinguish rebuilds.`,
+    );
+
+    return stripped;
+};
+
+const packageVersionFor = (upstream: string, prerelease: string | undefined): string =>
+    prerelease === undefined ? upstream : `${upstream}~${prerelease.replaceAll("-", ".")}`;
+
+const assertMatches = (value: string, pattern: RegExp, subject: string, key: string): void => {
+    if (!pattern.test(value)) {
+        throw new Error(
+            `Cannot package "${value}" as ${subject}: it does not match ${String(pattern)}. Set \`${key}\`.`,
+        );
+    }
+};
+
+const resolveVersions = ({ version, release, epoch }: VersionRequest): DeployVersions => {
+    const normalized = stripBuildMetadata(version.trim().replace(LEADING_V, ""));
+    const [upstream = "", ...rest] = normalized.split(PRERELEASE_SEPARATOR);
+    const prerelease = rest.length > 0 ? rest.join(PRERELEASE_SEPARATOR) : undefined;
+    assertMatches(upstream, UPSTREAM_PATTERN, "an upstream version", "deploy.version");
+    const packageVersion = packageVersionFor(upstream, prerelease);
+    assertMatches(packageVersion, PACKAGE_VERSION_PATTERN, "a package version", "deploy.version");
+    const revision = release ?? DEFAULT_RELEASE;
+    assertMatches(revision, RELEASE_PATTERN, "a packaging revision", "deploy.release");
+
+    return { upstream, packageVersion, debRevision: revision, rpmRelease: revision, epoch: epoch ?? null };
+};
+
+export { resolveVersions };

package/src/deploy/targets/appimage.ts

@@ -0,0 +1,140 @@
+import { existsSync, mkdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type {
+    DeployArtifact,
+    DeployManifest,
+    DeployPayload,
+    DeploySettings,
+    DeployTarget,
+    StagedFile,
+} from "../types.js";
+import { runCliTool } from "../../internal/run-cli-tool.js";
+import { copyInto, copyTree, EXECUTABLE_MODE, writeInto } from "../payload/copy-tree.js";
+import { getIconSize } from "../payload/icons.js";
+import { FILE_TOOL } from "../tools.js";
+import { resolveAppimageTooling } from "../vendored/appimagetool.js";
+
+const PREFIX = "/usr";
+const TARGET_DIR = "appimage";
+const APPRUN_FILENAME = "AppRun";
+const APPDIR_NAME = "AppDir";
+const USR_DIR = "usr";
+const ICON_EXTENSIONS = [".svg", ".png", ".xpm"];
+const EXTRACT_AND_RUN = "APPIMAGE_EXTRACT_AND_RUN";
+const SCALABLE_RANK = Number.MAX_SAFE_INTEGER;
+
+const appimageTarget: DeployTarget = {
+    name: "appimage",
+    prefix: PREFIX,
+    tools: [FILE_TOOL],
+    render: (payload) => renderManifests(payload),
+    pack: (payload) => packAppImage(payload),
+};
+
+const appimageDir = (settings: DeploySettings): string => join(settings.paths.targets, TARGET_DIR);
+const appDirFor = (settings: DeploySettings): string => join(appimageDir(settings), APPDIR_NAME);
+const appRunPathFor = (settings: DeploySettings): string => join(appimageDir(settings), APPRUN_FILENAME);
+
+const renderAppRun = (settings: DeploySettings): string =>
+    [
+        "#!/bin/sh",
+        "set -e",
+        'here=$(dirname "$(readlink -f "$0")")',
+        'XDG_DATA_DIRS="$here/usr/share:${XDG_DATA_DIRS:-/usr/local/share:/usr/share}"',
+        "export XDG_DATA_DIRS",
+        `exec "$here/usr/bin/${settings.binaryName}" "$@"`,
+        "",
+    ].join("\n");
+
+const renderManifests = (payload: DeployPayload): DeployManifest[] => [
+    { path: appRunPathFor(payload.settings), contents: renderAppRun(payload.settings) },
+];
+
+const iconRank = (file: StagedFile): number =>
+    file.rel.endsWith(".svg") ? SCALABLE_RANK : (getIconSize(file.rel) ?? 0);
+
+const largestIcon = (icons: StagedFile[]): StagedFile | undefined => {
+    let best: StagedFile | undefined;
+
+    for (const file of icons) {
+        if (best === undefined || iconRank(file) > iconRank(best)) {
+            best = file;
+        }
+    }
+
+    return best;
+};
+
+const rootIconFor = (payload: DeployPayload): { rel: string; abs: string } => {
+    const { applicationId } = payload.settings;
+    const names = new Set(ICON_EXTENSIONS.map((extension) => `${applicationId}${extension}`));
+    const icon = largestIcon(payload.stage.filter((file) => names.has(file.rel.split("/").at(-1) ?? "")));
+
+    if (icon === undefined) {
+        throw new Error(`Cannot build an AppImage without a ${applicationId} icon in the staged icon tree`);
+    }
+
+    return { rel: icon.rel.split("/").at(-1) ?? "", abs: icon.abs };
+};
+
+const buildAppDir = (payload: DeployPayload): string => {
+    const settings = payload.settings;
+    const appDir = appDirFor(settings);
+    rmSync(appDir, { recursive: true, force: true, maxRetries: 5 });
+    copyTree(appDir, USR_DIR, settings.paths.stage);
+    copyTree(appDir, USR_DIR, join(settings.paths.overlay, TARGET_DIR));
+    writeInto(appDir, APPRUN_FILENAME, renderAppRun(settings), EXECUTABLE_MODE);
+
+    copyInto(appDir, `${settings.applicationId}.desktop`, join(appDir, USR_DIR, "share/applications",
+        `${settings.applicationId}.desktop`));
+
+    const icon = rootIconFor(payload);
+    copyInto(appDir, icon.rel, icon.abs);
+
+    return appDir;
+};
+
+const artifactNameFor = (settings: DeploySettings): string =>
+    settings.deploy.appimage?.fileName ??
+    `${settings.name.replaceAll(" ", "_")}-${settings.versions.packageVersion}-${settings.arch.appimage}.AppImage`;
+
+const toolArgsFor = (settings: DeploySettings, runtime: string, appDir: string, target: string): string[] => {
+    const appimage = settings.deploy.appimage ?? {};
+    const signing = settings.deploy.signing?.appimage;
+
+    return [
+        "--no-appstream",
+        "--runtime-file",
+        appimage.runtimeFile ?? runtime,
+        ...(appimage.compression === undefined ? [] : ["--comp", appimage.compression]),
+        ...(appimage.updateInformation === undefined ? [] : ["-u", appimage.updateInformation]),
+        ...(signing === undefined ? [] : ["-s", "--sign-key", signing.gpgKeyId]),
+        appDir,
+        target,
+    ];
+};
+
+const packAppImage = async (payload: DeployPayload): Promise<DeployArtifact[]> => {
+    const settings = payload.settings;
+    const tooling = await resolveAppimageTooling(settings.arch.appimage);
+    const appDir = buildAppDir(payload);
+    const output = settings.paths.output;
+    mkdirSync(output, { recursive: true });
+    const target = join(output, artifactNameFor(settings));
+
+    runCliTool({
+        tool: tooling.tool,
+        args: toolArgsFor(settings, tooling.runtime, appDir, target),
+        target: "the AppImage",
+        shouldStream: true,
+        options: { env: { ...process.env, ARCH: settings.arch.appimage, [EXTRACT_AND_RUN]: "1" } },
+    });
+
+    if (!existsSync(target)) {
+        throw new Error(`appimagetool reported success but wrote no AppImage at ${target}`);
+    }
+
+    return [{ path: target, size: statSync(target).size }];
+};
+
+export { appimageTarget };

package/src/deploy/targets/deb.ts

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

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

@@ -0,0 +1,61 @@
+import type { DeployPayload, DeploySettings } from "../types.js";
+import { optional } from "../nfpm/optional.js";
+import { flatpakPrebuiltModule } from "./flatpak-prebuilt.js";
+import { flatpakSourceModule } from "./flatpak-source.js";
+import { nodeExtensionFor } from "./flatpak-sources.js";
+
+type FlatpakManifest = Record<string, unknown>;
+
+const DEFAULT_BRANCH = "stable";
+const DEFAULT_RUNTIME = "org.gnome.Platform";
+const DEFAULT_RUNTIME_VERSION = "50";
+const DEFAULT_SDK = "org.gnome.Sdk";
+const DEFAULT_FINISH_ARGS = ["--share=ipc", "--socket=wayland", "--socket=fallback-x11", "--device=dri"];
+const DEFAULT_CLEANUP = ["/include", "/share/pkgconfig", "*.la", "*.a"];
+
+const branchFor = (settings: DeploySettings): string => settings.deploy.flatpak?.branch ?? DEFAULT_BRANCH;
+const isSourceMode = (settings: DeploySettings): boolean => settings.deploy.flatpak?.mode === "source";
+
+const sdkExtensionsFor = (settings: DeploySettings): string[] => {
+    const flatpak = settings.deploy.flatpak ?? {};
+    const nodeExtension = isSourceMode(settings) ? [nodeExtensionFor(settings)] : [];
+
+    return [...nodeExtension, ...(flatpak.sdkExtensions ?? [])];
+};
+
+const modulesFor = (payload: DeployPayload): unknown[] => {
+    const settings = payload.settings;
+    const own = isSourceMode(settings) ? flatpakSourceModule(payload) : flatpakPrebuiltModule(payload);
+
+    return [...(settings.deploy.flatpak?.modules ?? []), own];
+};
+
+const runtimeKeys = (settings: DeploySettings): FlatpakManifest => {
+    const flatpak = settings.deploy.flatpak ?? {};
+    const extensions = sdkExtensionsFor(settings);
+
+    return {
+        runtime: flatpak.runtime ?? DEFAULT_RUNTIME,
+        "runtime-version": flatpak.runtimeVersion ?? DEFAULT_RUNTIME_VERSION,
+        sdk: flatpak.sdk ?? DEFAULT_SDK,
+        ...optional("base", flatpak.base),
+        ...optional("base-version", flatpak.baseVersion),
+        ...optional("sdk-extensions", extensions.length === 0 ? undefined : extensions),
+    };
+};
+
+const renderFlatpakManifest = (payload: DeployPayload): FlatpakManifest => {
+    const settings = payload.settings;
+    const flatpak = settings.deploy.flatpak ?? {};
+
+    return {
+        id: settings.applicationId,
+        ...runtimeKeys(settings),
+        command: settings.binaryName,
+        "finish-args": flatpak.finishArgs ?? DEFAULT_FINISH_ARGS,
+        cleanup: flatpak.cleanup ?? DEFAULT_CLEANUP,
+        modules: modulesFor(payload),
+    };
+};
+
+export { branchFor, renderFlatpakManifest };

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

@@ -0,0 +1,59 @@
+import type { DeployPayload, DeploySettings } from "../types.js";
+import { optional } from "../nfpm/optional.js";
+
+type FlatpakModule = Record<string, unknown>;
+
+const DESTINATION = "${FLATPAK_DEST}";
+const STAGE_SOURCE_PATH = "../../stage";
+const OVERLAY_SOURCE_PATH = "../../overlay/flatpak";
+
+const validationCommands = (settings: DeploySettings): string[] => {
+    if (settings.deploy.flatpak?.mode !== "source") {
+        return [];
+    }
+
+    const metainfo = `${DESTINATION}/share/metainfo/${settings.applicationId}.metainfo.xml`;
+
+    return [
+        `desktop-file-validate ${DESTINATION}/share/applications/${settings.applicationId}.desktop`,
+        `appstreamcli validate --no-net --explain ${metainfo}`,
+    ];
+};
+
+const permissionCommands = (settings: DeploySettings): string[] => [
+    `chmod 755 ${DESTINATION}/bin/${settings.binaryName} ${DESTINATION}/lib/${settings.binaryName}/node`,
+    `find ${DESTINATION}/lib/${settings.binaryName} -name '*.node' -exec chmod 755 {} +`,
+];
+
+const overlaySources = (payload: DeployPayload): FlatpakModule[] =>
+    payload.overlays.flatpak.length === 0 ? [] : [{ type: "dir", path: OVERLAY_SOURCE_PATH, dest: "overlay" }];
+
+const overlayCommands = (payload: DeployPayload): string[] =>
+    payload.overlays.flatpak.length === 0 ? [] : [`cp -a overlay/. ${DESTINATION}/`];
+
+const postInstallCommands = (payload: DeployPayload): string[] =>
+    payload.settings.paths.schemaFiles.length === 0
+        ? []
+        : [`glib-compile-schemas ${DESTINATION}/share/glib-2.0/schemas`];
+
+const flatpakPrebuiltModule = (payload: DeployPayload): FlatpakModule => {
+    const settings = payload.settings;
+    const postInstall = postInstallCommands(payload);
+
+    return {
+        name: settings.binaryName,
+        buildsystem: "simple",
+        "build-options": { strip: false, "no-debuginfo": true },
+        sources: [{ type: "dir", path: STAGE_SOURCE_PATH, dest: "stage" }, ...overlaySources(payload)],
+        "build-commands": [
+            `cp -a stage/. ${DESTINATION}/`,
+            ...overlayCommands(payload),
+            ...permissionCommands(settings),
+            ...(settings.deploy.flatpak?.buildCommands ?? []),
+            ...validationCommands(settings),
+        ],
+        ...optional("post-install", postInstall.length === 0 ? undefined : postInstall),
+    };
+};
+
+export { DESTINATION, type FlatpakModule, flatpakPrebuiltModule, postInstallCommands, validationCommands };

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