@gtkx/cli 1.0.0 → 1.2.0

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

@@ -0,0 +1,115 @@
+import type { DeploySettings } from "../types.js";
+import type { FlatpakModule } from "./flatpak-prebuilt.js";
+import { readPackageManifest } from "../settings/package-manifest.js";
+
+type PnpmPin = {
+    version: string;
+    major: number;
+    minor: number;
+    sha512: string;
+};
+
+const PNPM_VERSION = "11.21.0";
+const PNPM_MAJOR = 11;
+const PNPM_MINOR = 21;
+
+const PNPM_SHA512 = "521705bce689924eac72f5a3587122f362689ef6571e55ba80076fd637c11132ecffada26" +
+    "fad4ea79c485bfddbfd3d5a2a5b05805a77e893de71ec8a6cca3bb1";
+
+const PNPM_DIR = "flatpak-pnpm";
+const PNPM_COMMAND = "pnpm";
+const PNPM_PREFIX = "pnpm@";
+const PNPM_TARBALL_URL = "https://registry.npmjs.org/pnpm/-/pnpm-";
+const PNPM_INSTALL = "pnpm install --offline --frozen-lockfile";
+const TRUST_LOCKFILE = "--trust-lockfile";
+const STORE_V10 = "v10";
+const STORE_V11 = "v11";
+const STORE_V10_MAJOR = 10;
+const STORE_V11_MAJOR = 11;
+const TRUST_LOCKFILE_MINOR = 3;
+
+const DEFAULT_PIN: PnpmPin = {
+    version: PNPM_VERSION,
+    major: PNPM_MAJOR,
+    minor: PNPM_MINOR,
+    sha512: PNPM_SHA512,
+};
+
+const PNPM_PIN_FIELD =
+    /^pnpm@(?<version>(?<major>\d+)\.(?<minor>\d+)\.\d+)\+sha512\.(?<sha512>[\da-f]{128})$/;
+
+const pinFromGroups = (groups: Record<string, string | undefined>): PnpmPin | null => {
+    const { major, minor, sha512, version } = groups;
+
+    if (major === undefined || minor === undefined || sha512 === undefined || version === undefined) {
+        return null;
+    }
+
+    return { version, major: Number(major), minor: Number(minor), sha512 };
+};
+
+const isSupportedPin = (pin: PnpmPin): boolean =>
+    pin.major === STORE_V10_MAJOR || (pin.major === STORE_V11_MAJOR && pin.minor >= TRUST_LOCKFILE_MINOR);
+
+const resolvePnpmPin = (settings: DeploySettings): PnpmPin => {
+    const field = readPackageManifest(settings.paths.root).packageManager;
+
+    if (field === null) {
+        return DEFAULT_PIN;
+    }
+
+    if (!field.startsWith(PNPM_PREFIX)) {
+        throw new Error(
+            `Cannot vendor pnpm for the Flathub sandbox: "packageManager" is "${field}" but the offline install ` +
+            "resolves from a pnpm lockfile. Run `corepack use pnpm@<version>` to pin it to pnpm, or point " +
+            "`deploy.flatpak.packageManager` at the manager whose lockfile the build should install from.",
+        );
+    }
+
+    const pin = pinFromGroups(PNPM_PIN_FIELD.exec(field)?.groups ?? {});
+
+    if (pin === null) {
+        throw new Error(
+            `Cannot vendor pnpm for the Flathub sandbox: "packageManager" is "${field}", which carries no sha512 ` +
+            "integrity digest, and every source in a Flathub build has to be hash-pinned. Run " +
+            "`corepack use pnpm@<version>` to rewrite it with its digest.",
+        );
+    }
+
+    if (!isSupportedPin(pin)) {
+        throw new Error(
+            `Cannot vendor pnpm ${pin.version} for the Flathub sandbox: the offline install runs on pnpm 10, or on ` +
+            "pnpm 11 from 11.3.0 on, where `--trust-lockfile` exists. Earlier pnpm 11 releases reach the registry " +
+            'during the supply-chain check and the sandbox has no network. Pin "packageManager" to one of those.',
+        );
+    }
+
+    return pin;
+};
+
+const pnpmPathFor = (moduleDir: string): string => `${moduleDir}/${PNPM_DIR}`;
+
+const pnpmSources = (pin: PnpmPin, moduleDir: string): FlatpakModule[] => [
+    { type: "archive", url: `${PNPM_TARBALL_URL}${pin.version}.tgz`, sha512: pin.sha512, dest: PNPM_DIR },
+    {
+        type: "script",
+        dest: PNPM_DIR,
+        "dest-filename": PNPM_COMMAND,
+        commands: [`exec node ${pnpmPathFor(moduleDir)}/bin/pnpm.cjs "$@"`],
+    },
+];
+
+const pnpmInstallCommand = (pin: PnpmPin): string =>
+    pin.major === STORE_V11_MAJOR ? `${PNPM_INSTALL} ${TRUST_LOCKFILE}` : PNPM_INSTALL;
+
+const pnpmStoreVersionFor = (pin: PnpmPin): string =>
+    pin.major === STORE_V10_MAJOR ? STORE_V10 : STORE_V11;
+
+export {
+    pnpmInstallCommand,
+    pnpmPathFor,
+    type PnpmPin,
+    pnpmSources,
+    pnpmStoreVersionFor,
+    resolvePnpmPin,
+};

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,181 @@
+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 { pnpmPathFor, type PnpmPin, pnpmSources } from "./flatpak-pnpm.js";
+import { DESTINATION, type FlatpakModule, postInstallCommands, validationCommands } from "./flatpak-prebuilt.js";
+import {
+    detectPackageManager,
+    GENERATED_SOURCES,
+    installCommandFor,
+    nodeExtensionPathFor,
+    type PackageManager,
+    pnpmPinFor,
+    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 moduleDirFor = (settings: DeploySettings): string => `${MODULE_BUILD_ROOT}/${settings.binaryName}`;
+
+const offlineEnvFor = (manager: PackageManager, settings: DeploySettings): Record<string, string> => {
+    if (manager === "pnpm") {
+        return {};
+    }
+
+    if (manager === "yarn") {
+        return { YARN_OFFLINE_MIRROR: `${moduleDirFor(settings)}/${YARN_MIRROR_DIR}` };
+    }
+
+    return { npm_config_cache: `${moduleDirFor(settings)}/${NPM_CACHE_DIR}`, npm_config_offline: "true" };
+};
+
+const appendPathFor = (settings: DeploySettings, pin: PnpmPin | null, nodeExtensionPath: string): string =>
+    pin === null
+        ? `${nodeExtensionPath}/bin`
+        : `${pnpmPathFor(moduleDirFor(settings))}:${nodeExtensionPath}/bin`;
+
+const flatpakSourceModule = (payload: DeployPayload): FlatpakModule => {
+    const settings = payload.settings;
+    const manager = detectPackageManager(settings);
+    const pin = pnpmPinFor(settings, manager);
+    const postInstall = postInstallCommands(payload);
+    const nodeExtensionPath = nodeExtensionPathFor(settings);
+
+    return {
+        name: settings.binaryName,
+        buildsystem: "simple",
+        "build-options": {
+            "append-path": appendPathFor(settings, pin, nodeExtensionPath),
+            env: { npm_config_nodedir: nodeExtensionPath, ...offlineEnvFor(manager, settings) },
+            strip: false,
+            "no-debuginfo": true,
+        },
+        sources: [
+            resolveGitSource(settings),
+            ...(pin === null ? [] : pnpmSources(pin, moduleDirFor(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(settings, 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,198 @@
+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";
+import { FLATPAK_NODE_GENERATOR, GENERATOR_PNPM_OPTION } from "../tools.js";
+import { pnpmInstallCommand, type PnpmPin, pnpmStoreVersionFor, resolvePnpmPin } from "./flatpak-pnpm.js";
+
+type PackageManager = "npm" | "pnpm" | "yarn";
+type VendoredManager = Exclude<PackageManager, "pnpm">;
+
+type GitSource = {
+    type: "git";
+    url: string;
+    tag?: string;
+    commit?: string;
+};
+
+type GitRevision = {
+    tag?: string;
+    commit?: string;
+};
+
+const GENERATED_SOURCES = "generated-sources.json";
+const COMMIT_PEEL = "^{commit}";
+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<VendoredManager, string> = {
+    npm: "npm ci --offline",
+    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 pnpmPinFor = (settings: DeploySettings, manager: PackageManager): PnpmPin | null =>
+    manager === "pnpm" ? resolvePnpmPin(settings) : null;
+
+const installCommandFor = (settings: DeploySettings, manager: PackageManager): string =>
+    manager === "pnpm" ? pnpmInstallCommand(resolvePnpmPin(settings)) : 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 commitForTag = (root: string, tag: string): string => {
+    const commit = runGit(root, ["rev-parse", `${tag}${COMMIT_PEEL}`]);
+
+    if (commit === null) {
+        throw new Error(
+            `Cannot pin the Flathub source to "${tag}": Flathub builds a fixed tree, not a movable tag, and that ` +
+            `tag does not resolve in ${root}. Create or fetch it, or set \`deploy.flatpak.source.commit\`.`,
+        );
+    }
+
+    return commit;
+};
+
+const configuredRevision = (settings: DeploySettings): GitRevision | null => {
+    const source = settings.deploy.flatpak?.source ?? {};
+
+    if (source.commit !== undefined) {
+        return { ...optional("tag", source.tag), commit: source.commit };
+    }
+
+    if (source.tag === undefined) {
+        return null;
+    }
+
+    return { tag: source.tag, commit: commitForTag(settings.paths.root, 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 storeVersionArgs = (pin: PnpmPin | null): string[] =>
+    pin === null ? [] : [GENERATOR_PNPM_OPTION, pnpmStoreVersionFor(pin)];
+
+const generateNodeSources = (settings: DeploySettings, manager: PackageManager, pin: PnpmPin | null): 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: FLATPAK_NODE_GENERATOR.command,
+            args: [manager, join(isolated, basename(lockfile)), ...storeVersionArgs(pin), "-o", output],
+            target: "the offline dependency sources",
+            shouldStream: true,
+        });
+    } finally {
+        rmSync(isolated, { recursive: true, force: true, maxRetries: 5 });
+    }
+};
+
+export {
+    detectPackageManager,
+    GENERATED_SOURCES,
+    generateNodeSources,
+    installCommandFor,
+    nodeExtensionFor,
+    nodeExtensionPathFor,
+    type PackageManager,
+    pnpmPinFor,
+    resolveGitSource,
+};