@gtkx/cli 1.0.0-rc.4 → 1.1.0

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

package/src/deploy/types.ts

@@ -0,0 +1,174 @@
+import type { Config } from "@gtkx/config";
+
+type DeployConfig = NonNullable<Config["deploy"]>;
+type DeployTargetName = NonNullable<DeployConfig["targets"]>[number];
+type PackageFamily = "arch" | "debian" | "fedora" | "suse" | "unknown";
+
+type DeployTool = {
+    command: string;
+    purpose: string;
+    isOptional: boolean;
+    isPresent?: () => boolean;
+};
+
+type StagedFile = {
+    rel: string;
+    abs: string;
+    mode: number;
+};
+
+type NodeRuntime = {
+    path: string;
+    version: string;
+    glibcFloor: string | null;
+    isStripped: boolean;
+};
+
+type DeployDeveloper = {
+    id: string | null;
+    name: string;
+    email: string | null;
+};
+
+type DeployScreenshot = {
+    url: string;
+    caption: string | null;
+    isDefault: boolean;
+};
+
+type DeployRelease = {
+    version: string;
+    date: string;
+    type: string | null;
+    urgency: string | null;
+    notes: string[];
+    url: string | null;
+};
+
+type DeployFileAssociation = {
+    extension: string;
+    mimeType: string;
+    description: string | null;
+};
+
+type DeployDesktopAction = {
+    id: string;
+    name: string;
+    args: string[];
+    icon: string | null;
+};
+
+type DeployVersions = {
+    upstream: string;
+    packageVersion: string;
+    debRevision: string;
+    rpmRelease: string;
+    epoch: number | null;
+};
+
+type DeployArch = {
+    deb: string;
+    rpm: string;
+    flatpak: string;
+    appimage: string;
+    node: string;
+};
+
+type DeployPaths = {
+    root: string;
+    dist: string;
+    outDir: string;
+    metadata: string;
+    runtime: string;
+    stage: string;
+    overlay: string;
+    targets: string;
+    output: string;
+    dataDir: string | null;
+    iconsDir: string | null;
+    iconFile: string | null;
+    licenseFile: string | null;
+    schemaFiles: string[];
+};
+
+type DeploySettings = {
+    applicationId: string;
+    binaryName: string;
+    name: string;
+    genericName: string | null;
+    summary: string;
+    description: string[];
+    keywords: string[];
+    categories: string[];
+    mimeTypes: string[];
+    developer: DeployDeveloper;
+    license: string;
+    metadataLicense: string;
+    copyright: string;
+    homepage: string | null;
+    urls: Record<string, string>;
+    screenshots: DeployScreenshot[];
+    branding: { light: string; dark: string } | null;
+    contentRating: Record<string, string>;
+    releases: DeployRelease[];
+    execArgs: string[];
+    execToken: string | null;
+    fileAssociations: DeployFileAssociation[];
+    protocols: string[];
+    desktopActions: DeployDesktopAction[];
+    desktopEntry: Record<string, string>;
+    isDbusActivatable: boolean;
+    extraFiles: Record<string, string>;
+    versions: DeployVersions;
+    arch: DeployArch;
+    paths: DeployPaths;
+    libraries: string[];
+    deploy: DeployConfig;
+};
+
+type DeployPayload = {
+    settings: DeploySettings;
+    node: NodeRuntime | null;
+    stage: StagedFile[];
+    overlays: Record<DeployTargetName, StagedFile[]>;
+};
+
+type DeployManifest = {
+    path: string;
+    contents: string;
+};
+
+type DeployArtifact = {
+    path: string;
+    size: number;
+};
+
+type DeployTarget = {
+    name: DeployTargetName;
+    prefix: string;
+    tools: DeployTool[];
+    render: (payload: DeployPayload) => DeployManifest[];
+    pack: (payload: DeployPayload, manifests: DeployManifest[]) => Promise<DeployArtifact[]>;
+};
+
+export type {
+    DeployArch,
+    DeployArtifact,
+    DeployConfig,
+    DeployDesktopAction,
+    DeployDeveloper,
+    DeployFileAssociation,
+    DeployManifest,
+    DeployPaths,
+    DeployPayload,
+    DeployRelease,
+    DeployScreenshot,
+    DeploySettings,
+    DeployTarget,
+    DeployTargetName,
+    DeployTool,
+    DeployVersions,
+    NodeRuntime,
+    PackageFamily,
+    StagedFile,
+};

package/src/deploy/vendored/appimagetool.ts

@@ -0,0 +1,57 @@
+import { join } from "node:path";
+import { cacheDir, downloadFile } from "../download.js";
+
+type AppimageTooling = {
+    tool: string;
+    runtime: string;
+};
+
+const APPIMAGETOOL_VERSION = "1.9.1";
+const RUNTIME_VERSION = "20251108";
+const APPIMAGETOOL_URL = `https://github.com/AppImage/appimagetool/releases/download/${APPIMAGETOOL_VERSION}`;
+const RUNTIME_URL = `https://github.com/AppImage/type2-runtime/releases/download/${RUNTIME_VERSION}`;
+const EXECUTABLE_MODE = 0o755;
+
+const APPIMAGETOOL_DIGESTS: Record<string, string> = {
+    aarch64: "f0837e7448a0c1e4e650a93bb3e85802546e60654ef287576f46c71c126a9158",
+    x86_64: "ed4ce84f0d9caff66f50bcca6ff6f35aae54ce8135408b3fa33abfc3cb384eb0",
+};
+
+const RUNTIME_DIGESTS: Record<string, string> = {
+    aarch64: "00cbdfcf917cc6c0ff6d3347d59e0ca1f7f45a6df1a428a0d6d8a78664d87444",
+    x86_64: "2fca8b443c92510f1483a883f60061ad09b46b978b2631c807cd873a47ec260d",
+};
+
+const digestFor = (digests: Record<string, string>, arch: string, subject: string): string => {
+    const digest = digests[arch];
+
+    if (digest === undefined) {
+        throw new Error(`${subject} has no pinned build for ${arch}`);
+    }
+
+    return digest;
+};
+
+const resolveAppimageTooling = async (arch: string): Promise<AppimageTooling> => {
+    const dir = cacheDir(["appimage", `${APPIMAGETOOL_VERSION}-${RUNTIME_VERSION}`]);
+
+    const tool = await downloadFile({
+        url: `${APPIMAGETOOL_URL}/appimagetool-${arch}.AppImage`,
+        dest: join(dir, `appimagetool-${arch}`),
+        label: `appimagetool ${APPIMAGETOOL_VERSION}`,
+        sha256: digestFor(APPIMAGETOOL_DIGESTS, arch, "appimagetool"),
+        mode: EXECUTABLE_MODE,
+    });
+
+    const runtime = await downloadFile({
+        url: `${RUNTIME_URL}/runtime-${arch}`,
+        dest: join(dir, `runtime-${arch}`),
+        label: `the AppImage runtime ${RUNTIME_VERSION}`,
+        sha256: digestFor(RUNTIME_DIGESTS, arch, "the AppImage runtime"),
+        mode: EXECUTABLE_MODE,
+    });
+
+    return { tool, runtime };
+};
+
+export { resolveAppimageTooling };

package/src/deploy/vendored/nfpm.ts

@@ -0,0 +1,79 @@
+import { mkdtempSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { runCliTool } from "../../internal/run-cli-tool.js";
+import { cacheDir, downloadFile } from "../download.js";
+
+const NFPM_VERSION = "2.47.0";
+const NFPM_BASE_URL = `https://github.com/goreleaser/nfpm/releases/download/v${NFPM_VERSION}`;
+
+const NFPM_ASSET_ARCH: Record<string, string> = {
+    arm64: "arm64",
+    x64: "x86_64",
+};
+
+const NFPM_DIGESTS: Record<string, string> = {
+    arm64: "1c0f5f2999b9a974bfb04fdb0cc3306096de530ac5dbb25d739cc5f5219c919c",
+    x86_64: "0660ca602b2d2d2ae4781a06c692b3eeb9d437ffea05b831d76e41f4a3188783",
+};
+
+const assetArchFor = (arch: string): string => {
+    const assetArch = NFPM_ASSET_ARCH[arch];
+
+    if (assetArch === undefined) {
+        throw new Error(`nfpm has no Linux build for ${arch}`);
+    }
+
+    return assetArch;
+};
+
+const assetNameFor = (arch: string): string => `nfpm_${NFPM_VERSION}_Linux_${assetArchFor(arch)}.tar.gz`;
+
+const digestFor = (arch: string): string => {
+    const digest = NFPM_DIGESTS[assetArchFor(arch)];
+
+    if (digest === undefined) {
+        throw new Error(`nfpm ${NFPM_VERSION} has no pinned digest for ${arch}`);
+    }
+
+    return digest;
+};
+
+const extractNfpm = (archive: string, binary: string): void => {
+    const dir = mkdtempSync(`${binary}-`);
+
+    try {
+        runCliTool({ tool: "tar", args: ["-xzf", archive, "-C", dir, "nfpm"], target: assetNameFor(process.arch) });
+        renameSync(join(dir, "nfpm"), binary);
+    } finally {
+        rmSync(dir, { recursive: true, force: true, maxRetries: 5 });
+    }
+};
+
+const downloadNfpm = async (dir: string, binary: string): Promise<string> => {
+    const assetName = assetNameFor(process.arch);
+
+    const archive = await downloadFile({
+        url: `${NFPM_BASE_URL}/${assetName}`,
+        dest: join(dir, assetName),
+        label: `nfpm ${NFPM_VERSION}`,
+        sha256: digestFor(process.arch),
+    });
+
+    extractNfpm(archive, binary);
+
+    return binary;
+};
+
+const resolveNfpm = async (): Promise<string> => {
+    const override = process.env.GTKX_NFPM;
+
+    if (override !== undefined && override.length > 0) {
+        return override;
+    }
+
+    const dir = cacheDir(["nfpm", NFPM_VERSION]);
+
+    return downloadNfpm(dir, join(dir, "nfpm"));
+};
+
+export { resolveNfpm };

package/src/dev/change-queue.ts

@@ -0,0 +1,59 @@
+import type { DevServerWatchEvent } from "./vite-dev-server.js";
+
+type WatchedChange = {
+    event: DevServerWatchEvent;
+    path: string;
+};
+
+type ChangeQueue = {
+    enqueue: (change: WatchedChange) => void;
+};
+
+type QueueState = {
+    queued: WatchedChange[];
+    isDraining: boolean;
+    run: (change: WatchedChange) => Promise<void>;
+};
+
+const isSameChange = (left: WatchedChange, right: WatchedChange): boolean =>
+    left.event === right.event && left.path === right.path;
+
+const drainQueue = async (state: QueueState): Promise<void> => {
+    state.isDraining = true;
+
+    try {
+        await Promise.resolve();
+        let change = state.queued.shift();
+
+        while (change !== undefined) {
+            await state.run(change);
+            change = state.queued.shift();
+        }
+    } finally {
+        state.isDraining = false;
+    }
+};
+
+const enqueueChange = (state: QueueState, change: WatchedChange): void => {
+    if (state.queued.some((queued) => isSameChange(queued, change))) {
+        return;
+    }
+
+    state.queued.push(change);
+
+    if (!state.isDraining) {
+        void drainQueue(state);
+    }
+};
+
+const createChangeQueue = (run: (change: WatchedChange) => Promise<void>): ChangeQueue => {
+    const state: QueueState = { queued: [], isDraining: false, run };
+
+    return {
+        enqueue: (change) => {
+            enqueueChange(state, change);
+        },
+    };
+};
+
+export { createChangeQueue, type WatchedChange };

package/src/dev/entry-env.ts

@@ -0,0 +1,3 @@
+const DEV_ENTRY_ENV = "GTKX_DEV_ENTRY";
+
+export { DEV_ENTRY_ENV };