@gtkx/cli 1.0.0-rc.4 → 1.1.0

package/src/deploy/freedesktop/desktop-entry.ts

@@ -0,0 +1,102 @@
+import type { DeployDesktopAction, DeploySettings } from "../types.js";
+import { type IniGroup, renderIni } from "./ini.js";
+
+type Entries = [string, string | string[]][];
+
+const DESKTOP_ENTRY_GROUP = "Desktop Entry";
+const EXEC_QUOTED_CHARACTERS = /["`$\\]/g;
+const EXEC_RESERVED_CHARACTERS = /[\s"'\\><~|&;$*?#()`]/;
+
+const RESERVED_KEYS = new Map([
+    ["DBusActivatable", "use `deploy.isDbusActivatable` instead"],
+    ["Version", "it names the desktop entry spec version, not the application's"],
+]);
+
+const quoteExecToken = (token: string): string => {
+    const escaped = token.replaceAll("%", "%%");
+
+    if (!EXEC_RESERVED_CHARACTERS.test(escaped)) {
+        return escaped;
+    }
+
+    const quoted = escaped.replaceAll(EXEC_QUOTED_CHARACTERS, (character) => `\\${character}`);
+
+    return `"${quoted}"`;
+};
+
+const execLine = (settings: DeploySettings): string =>
+    [
+        ...[settings.binaryName, ...settings.execArgs].map((part) => quoteExecToken(part)),
+        settings.execToken ?? "",
+    ]
+        .filter((part) => part.length > 0)
+        .join(" ");
+
+const optionalEntry = (key: string, value: string | null): Entries => (value === null ? [] : [[key, value]]);
+const listEntry = (key: string, values: string[]): Entries => (values.length === 0 ? [] : [[key, values]]);
+
+const assertNoReservedOverrides = (settings: DeploySettings): void => {
+    for (const key of Object.keys(settings.desktopEntry)) {
+        const remedy = RESERVED_KEYS.get(key);
+
+        if (remedy !== undefined) {
+            throw new Error(`Cannot set "${key}" through \`deploy.desktopEntry\`: gtkx deploy writes it, ${remedy}`);
+        }
+    }
+};
+
+const baseEntries = (settings: DeploySettings): Entries => [
+    ["Type", "Application"],
+    ["Name", settings.name],
+    ...optionalEntry("GenericName", settings.genericName),
+    ["Comment", settings.summary],
+    ["Exec", execLine(settings)],
+    ["Icon", settings.applicationId],
+    ["Terminal", "false"],
+    ...listEntry("Categories", settings.categories),
+    ...listEntry("Keywords", settings.keywords),
+    ...listEntry("MimeType", settings.mimeTypes),
+    ["StartupNotify", "true"],
+    ["StartupWMClass", settings.applicationId],
+];
+
+const actionEntries = (settings: DeploySettings): Entries =>
+    settings.desktopActions.length === 0 ? [] : [["Actions", settings.desktopActions.map((action) => action.id)]];
+
+const activationEntries = (settings: DeploySettings): Entries =>
+    settings.isDbusActivatable ? [["DBusActivatable", "true"]] : [];
+
+const actionGroup = (settings: DeploySettings, action: DeployDesktopAction): IniGroup => ({
+    name: `Desktop Action ${action.id}`,
+    entries: [
+        ["Name", action.name],
+        ["Exec", [settings.binaryName, ...action.args].map((part) => quoteExecToken(part)).join(" ")],
+        ...optionalEntry("Icon", action.icon),
+    ],
+});
+
+const mergeEntries = (entries: Entries, overrides: Entries): Entries => {
+    const merged = new Map(entries);
+
+    for (const [key, value] of overrides) {
+        merged.set(key, value);
+    }
+
+    return merged.entries().toArray();
+};
+
+const renderDesktopEntry = (settings: DeploySettings): string => {
+    assertNoReservedOverrides(settings);
+
+    const main: IniGroup = {
+        name: DESKTOP_ENTRY_GROUP,
+        entries: mergeEntries(
+            [...baseEntries(settings), ...actionEntries(settings), ...activationEntries(settings)],
+            Object.entries(settings.desktopEntry),
+        ),
+    };
+
+    return renderIni([main, ...settings.desktopActions.map((action) => actionGroup(settings, action))]);
+};
+
+export { renderDesktopEntry };

package/src/deploy/freedesktop/ini.ts

@@ -0,0 +1,39 @@
+type IniGroup = {
+    name: string;
+    entries: [string, string | string[]][];
+};
+
+const FORBIDDEN_VALUE_CHARACTERS = /[\n\r]/;
+
+const assertValue = (key: string, value: string): void => {
+    if (FORBIDDEN_VALUE_CHARACTERS.test(value)) {
+        throw new Error(`Cannot write "${key}" into a desktop entry: its value contains a line break`);
+    }
+};
+
+const escapeValue = (key: string, value: string): string => {
+    assertValue(key, value);
+
+    return value.replaceAll("\\", "\\\\");
+};
+
+const escapeListItem = (key: string, value: string): string => escapeValue(key, value).replaceAll(";", String.raw`\;`);
+
+const renderList = (key: string, values: string[]): string =>
+    values.length === 0 ? "" : `${values.map((item) => escapeListItem(key, item)).join(";")};`;
+
+const renderValue = (key: string, value: string | string[]): string =>
+    Array.isArray(value) ? renderList(key, value) : escapeValue(key, value);
+
+const renderEntry = ([key, value]: [string, string | string[]]): string => `${key}=${renderValue(key, value)}`;
+
+const renderGroup = (group: IniGroup): string[] => [
+    `[${group.name}]`,
+    ...group.entries.map((entry) => renderEntry(entry)),
+];
+
+const renderIni = (groups: IniGroup[]): string =>
+    [...groups.flatMap((group, index) => (index === 0 ? renderGroup(group) : ["", ...renderGroup(group)])), ""]
+        .join("\n");
+
+export { type IniGroup, renderIni };

package/src/deploy/freedesktop/metainfo-sections.ts

@@ -0,0 +1,116 @@
+import type { DeployRelease, DeploySettings } from "../types.js";
+import { element, text, type XmlNode } from "./xml.js";
+
+const CONTENT_RATING_TYPE = "oars-1.1";
+const DEFAULT_SCREENSHOT_TYPE = "default";
+const PRIMARY_COLOR = "primary";
+
+const developerSection = (settings: DeploySettings): XmlNode[] => {
+    const attributes = settings.developer.id === null ? {} : { id: settings.developer.id };
+
+    return [element("developer", attributes, [text("name", settings.developer.name)])];
+};
+
+const descriptionSection = (settings: DeploySettings): XmlNode[] => [
+    element("description", {}, settings.description.map((paragraph) => text("p", paragraph))),
+];
+
+const providesSection = (settings: DeploySettings): XmlNode[] => [
+    element("provides", {}, [
+        text("binary", settings.binaryName),
+        ...settings.mimeTypes.map((mimeType) => text("mediatype", mimeType)),
+    ]),
+];
+
+const listSection = (tag: string, itemTag: string, values: string[]): XmlNode[] =>
+    values.length === 0 ? [] : [element(tag, {}, values.map((value) => text(itemTag, value)))];
+
+const urlsSection = (settings: DeploySettings): XmlNode[] => {
+    const homepage = settings.homepage === null ? [] : [{ tag: "homepage", url: settings.homepage }];
+    const rest = Object.entries(settings.urls).map(([tag, url]) => ({ tag, url }));
+
+    return [...homepage, ...rest].map((entry) => ({ tag: "url", attributes: { type: entry.tag }, text: entry.url }));
+};
+
+const screenshotsSection = (settings: DeploySettings): XmlNode[] => {
+    if (settings.screenshots.length === 0) {
+        return [];
+    }
+
+    const entries = settings.screenshots.map((screenshot) =>
+        element(
+            "screenshot",
+            screenshot.isDefault ? { type: DEFAULT_SCREENSHOT_TYPE } : {},
+            [
+                text("image", screenshot.url),
+                ...(screenshot.caption === null ? [] : [text("caption", screenshot.caption)]),
+            ],
+        ));
+
+    return [element("screenshots", {}, entries)];
+};
+
+const releaseAttributes = (release: DeployRelease): Record<string, string> => ({
+    version: release.version,
+    date: release.date,
+    ...(release.type !== null && { type: release.type }),
+    ...(release.urgency !== null && { urgency: release.urgency }),
+});
+
+const releaseChildren = (release: DeployRelease): XmlNode[] => [
+    ...(release.url === null ? [] : [{ tag: "url", attributes: { type: "details" }, text: release.url }]),
+    ...(release.notes.length === 0
+        ? []
+        : [element("description", {}, release.notes.map((note) => text("p", note)))]),
+];
+
+const releasesSection = (settings: DeploySettings): XmlNode[] => {
+    if (settings.releases.length === 0) {
+        return [];
+    }
+
+    const entries = settings.releases.map((release) =>
+        element("release", releaseAttributes(release), releaseChildren(release)));
+
+    return [element("releases", {}, entries)];
+};
+
+const contentRatingSection = (settings: DeploySettings): XmlNode[] => [
+    element(
+        "content_rating",
+        { type: CONTENT_RATING_TYPE },
+        Object.entries(settings.contentRating).map(([id, intensity]) => ({
+            tag: "content_attribute",
+            attributes: { id },
+            text: intensity,
+        })),
+    ),
+];
+
+const brandingSection = (settings: DeploySettings): XmlNode[] => {
+    const branding = settings.branding;
+
+    if (branding === null) {
+        return [];
+    }
+
+    const color = (scheme: string, value: string): XmlNode => ({
+        tag: "color",
+        attributes: { type: PRIMARY_COLOR, scheme_preference: scheme },
+        text: value,
+    });
+
+    return [element("branding", {}, [color("light", branding.light), color("dark", branding.dark)])];
+};
+
+export {
+    brandingSection,
+    contentRatingSection,
+    descriptionSection,
+    developerSection,
+    listSection,
+    providesSection,
+    releasesSection,
+    screenshotsSection,
+    urlsSection,
+};

package/src/deploy/freedesktop/metainfo.ts

@@ -0,0 +1,46 @@
+import type { DeploySettings } from "../types.js";
+import {
+    brandingSection,
+    contentRatingSection,
+    descriptionSection,
+    developerSection,
+    listSection,
+    providesSection,
+    releasesSection,
+    screenshotsSection,
+    urlsSection,
+} from "./metainfo-sections.js";
+import { element, renderDocument, text, type XmlNode } from "./xml.js";
+
+const COMPONENT_TYPE = "desktop-application";
+const DESKTOP_SUFFIX = ".desktop";
+
+const launchable = (applicationId: string): XmlNode => ({
+    tag: "launchable",
+    attributes: { type: "desktop-id" },
+    text: `${applicationId}${DESKTOP_SUFFIX}`,
+});
+
+const renderMetainfo = (settings: DeploySettings): string =>
+    renderDocument(
+        element("component", { type: COMPONENT_TYPE }, [
+            text("id", settings.applicationId),
+            text("name", settings.name),
+            text("summary", settings.summary),
+            text("metadata_license", settings.metadataLicense),
+            text("project_license", settings.license),
+            ...developerSection(settings),
+            ...descriptionSection(settings),
+            launchable(settings.applicationId),
+            ...providesSection(settings),
+            ...listSection("categories", "category", settings.categories),
+            ...listSection("keywords", "keyword", settings.keywords),
+            ...urlsSection(settings),
+            ...screenshotsSection(settings),
+            ...releasesSection(settings),
+            ...contentRatingSection(settings),
+            ...brandingSection(settings),
+        ]),
+    );
+
+export { renderMetainfo };

package/src/deploy/freedesktop/mime-package.ts

@@ -0,0 +1,28 @@
+import type { DeployFileAssociation, DeploySettings } from "../types.js";
+import { element, renderDocument, text, type XmlNode } from "./xml.js";
+
+/* eslint-disable-next-line sonarjs/no-clear-text-protocols, unicorn/prefer-https --
+   An XML namespace is a fixed identifier, not a URL to fetch: shared-mime-info only recognizes this exact string. */
+const MIME_INFO_NAMESPACE = "http://www.freedesktop.org/standards/shared-mime-info";
+
+const mimeTypeNode = (association: DeployFileAssociation): XmlNode =>
+    element("mime-type", { type: association.mimeType }, [
+        ...(association.description === null ? [] : [text("comment", association.description)]),
+        { tag: "glob", attributes: { pattern: `*.${association.extension}` } },
+    ]);
+
+const renderMimePackage = (settings: DeploySettings): string | null => {
+    if (settings.fileAssociations.length === 0) {
+        return null;
+    }
+
+    return renderDocument(
+        element(
+            "mime-info",
+            { xmlns: MIME_INFO_NAMESPACE },
+            settings.fileAssociations.map((entry) => mimeTypeNode(entry)),
+        ),
+    );
+};
+
+export { renderMimePackage };

package/src/deploy/freedesktop/validate.ts

@@ -0,0 +1,124 @@
+import { resolveExecutable, sortStrings, warn } from "@gtkx/utils";
+import { spawnSync } from "node:child_process";
+
+type ToolResult = {
+    output: string;
+    status: number;
+};
+
+type MetainfoResult = {
+    subject: string;
+    output: string;
+    status: number;
+    errors: string[];
+    warnings: string[];
+    areWarningsFatal: boolean;
+};
+
+type ToolRequest = {
+    tool: string;
+    args: string[];
+    subject: string;
+};
+
+const DIAGNOSTIC = /^(?<severity>[EIPW]): \S+ (?<rule>[\w-]+)/;
+const ERROR_SEVERITY = "E";
+const WARNING_SEVERITY = "W";
+const INFO_SEVERITY = "I";
+
+const REMEDY_FOR_RULE: Record<string, string> = {
+    "component-summary-missing": "set `deploy.summary`",
+    "description-first-para-too-short": "open `deploy.description` with a paragraph longer than 80 characters",
+    "developer-info-missing": "set `deploy.developer.name`",
+    "metainfo-legacy-path": "this file is generated; report it as a gtkx bug",
+    "summary-has-dot-suffix": "drop the trailing period from `deploy.summary`",
+    "summary-too-long": "shorten `deploy.summary`",
+    "url-homepage-missing": "set `deploy.homepage`, or `homepage` in package.json",
+};
+
+const runTool = ({ tool, args, subject }: ToolRequest): ToolResult => {
+    const result = spawnSync(resolveExecutable(tool), args, { encoding: "utf8" });
+
+    if (result.error !== undefined) {
+        throw new Error(`${subject} could not be validated: ${result.error.message}`, { cause: result.error });
+    }
+
+    return { output: [result.stdout, result.stderr].join("\n").trim(), status: result.status ?? 0 };
+};
+
+const rulesIn = (output: string, severities: string[]): string[] =>
+    output
+        .split("\n")
+        .map((line) => DIAGNOSTIC.exec(line)?.groups)
+        .filter((groups) => groups !== undefined && severities.includes(groups.severity ?? ""))
+        .map((groups) => groups?.rule ?? "");
+
+const remedyLines = (rules: string[]): string[] => {
+    const remedies = sortStrings([...new Set(rules)])
+        .filter((rule) => REMEDY_FOR_RULE[rule] !== undefined)
+        .map((rule) => `  ${rule}: ${REMEDY_FOR_RULE[rule] ?? ""}`);
+
+    return remedies.length === 0 ? [] : ["", "Fix it in gtkx.config.ts:", ...remedies];
+};
+
+const invalid = (subject: string, output: string, rules: string[]): Error =>
+    new Error([`${subject} is not valid:`, output.length > 0 ? output : "no output", ...remedyLines(rules)].join("\n"));
+
+const isFatalResult = ({ status, errors, warnings, areWarningsFatal }: MetainfoResult): boolean => {
+    if (errors.length > 0) {
+        return true;
+    }
+
+    if (areWarningsFatal && warnings.length > 0) {
+        return true;
+    }
+
+    return status !== 0 && warnings.length === 0;
+};
+
+const assertNotFatal = (result: MetainfoResult): void => {
+    if (isFatalResult(result)) {
+        throw invalid(result.subject, result.output, [...result.errors, ...result.warnings]);
+    }
+};
+
+const describeRule = (rule: string): string => {
+    const remedy = REMEDY_FOR_RULE[rule];
+
+    return remedy === undefined ? rule : `${rule} — ${remedy}`;
+};
+
+const reportDiagnostics = (subject: string, rules: string[]): void => {
+    for (const rule of rules) {
+        warn(`${subject}: ${describeRule(rule)}`);
+    }
+};
+
+const validateDesktopEntry = (path: string): void => {
+    const { output, status } = runTool({
+        tool: "desktop-file-validate",
+        args: [path],
+        subject: "The desktop entry",
+    });
+
+    if (status !== 0 || output.length > 0) {
+        throw invalid("The desktop entry", output, []);
+    }
+};
+
+const validateMetainfo = (path: string, areWarningsFatal: boolean): void => {
+    const subject = "The AppStream metainfo";
+
+    const { output, status } = runTool({
+        tool: "appstreamcli",
+        args: ["validate", "--no-net", "--explain", path],
+        subject,
+    });
+
+    const errors = rulesIn(output, [ERROR_SEVERITY]);
+    const warnings = rulesIn(output, [WARNING_SEVERITY]);
+    assertNotFatal({ subject, output, status, errors, warnings, areWarningsFatal });
+    reportDiagnostics(subject, [...warnings, ...rulesIn(output, [INFO_SEVERITY])]);
+};
+
+export { validateDesktopEntry, validateMetainfo };

package/src/deploy/freedesktop/xml.ts

@@ -0,0 +1,53 @@
+type XmlNode = {
+    tag: string;
+    attributes?: Record<string, string>;
+    children?: XmlNode[];
+    text?: string;
+};
+
+const XML_DECLARATION = '<?xml version="1.0" encoding="UTF-8"?>';
+const INDENT = " ".repeat(4);
+
+const ESCAPES: Record<string, string> = {
+    '"': "&quot;",
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+};
+
+const escapeXml = (value: string): string =>
+    value.replaceAll(/["&<>]/g, (character) => ESCAPES[character] ?? character);
+
+const renderAttributes = (attributes: Record<string, string> | undefined): string =>
+    Object.entries(attributes ?? {})
+        .map(([key, value]) => ` ${key}="${escapeXml(value)}"`)
+        .join("");
+
+const element = (tag: string, attributes: Record<string, string>, children: XmlNode[]): XmlNode => ({
+    tag,
+    attributes,
+    children,
+});
+
+const text = (tag: string, value: string): XmlNode => ({ tag, text: value });
+
+const renderNode = (node: XmlNode, depth: number): string[] => {
+    const padding = INDENT.repeat(depth);
+    const open = `${padding}<${node.tag}${renderAttributes(node.attributes)}`;
+
+    if (node.text !== undefined) {
+        return [`${open}>${escapeXml(node.text)}</${node.tag}>`];
+    }
+
+    const children = node.children ?? [];
+
+    if (children.length === 0) {
+        return [`${open}/>`];
+    }
+
+    return [`${open}>`, ...children.flatMap((child) => renderNode(child, depth + 1)), `${padding}</${node.tag}>`];
+};
+
+const renderDocument = (root: XmlNode): string => [XML_DECLARATION, ...renderNode(root, 0), ""].join("\n");
+
+export { element, renderDocument, text, type XmlNode };

package/src/deploy/git.ts

@@ -0,0 +1,20 @@
+import { tryResolveExecutable } from "@gtkx/utils";
+import { execFileSync } from "node:child_process";
+
+const runGit = (root: string, args: string[]): string | null => {
+    const git = tryResolveExecutable("git");
+
+    if (git === undefined) {
+        return null;
+    }
+
+    try {
+        return execFileSync(git, args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    } catch {
+        return null;
+    }
+};
+
+const gitRemoteUrl = (root: string): string | null => runGit(root, ["remote", "get-url", "origin"]);
+
+export { gitRemoteUrl, runGit };

package/src/deploy/install-hints.ts

@@ -0,0 +1,108 @@
+import { readFileSync } from "node:fs";
+import type { PackageFamily } from "./types.js";
+
+type FamilyPackages = Partial<Record<PackageFamily, string>>;
+
+const OS_RELEASE_PATH = "/etc/os-release";
+const OS_RELEASE_LINE = /^(?<key>[A-Z_]+)=(?<value>.*)$/;
+const QUOTED = /^"(.*)"$/;
+
+const FAMILY_BY_ID: Record<string, PackageFamily> = {
+    arch: "arch",
+    debian: "debian",
+    fedora: "fedora",
+    manjaro: "arch",
+    opensuse: "suse",
+    "opensuse-leap": "suse",
+    "opensuse-tumbleweed": "suse",
+    rhel: "fedora",
+    sles: "suse",
+    suse: "suse",
+    ubuntu: "debian",
+};
+
+const INSTALL_COMMAND: Partial<Record<PackageFamily, string>> = {
+    arch: "sudo pacman -S",
+    debian: "sudo apt install",
+    fedora: "sudo dnf install",
+    suse: "sudo zypper install",
+};
+
+const PACKAGE_FOR_TOOL: Record<string, FamilyPackages> = {
+    appstreamcli: { arch: "appstream", debian: "appstream", fedora: "appstream", suse: "AppStream" },
+    "desktop-file-validate": {
+        arch: "desktop-file-utils",
+        debian: "desktop-file-utils",
+        fedora: "desktop-file-utils",
+        suse: "desktop-file-utils",
+    },
+    file: { arch: "file", debian: "file", fedora: "file", suse: "file" },
+    "flatpak-builder": {
+        arch: "flatpak-builder",
+        debian: "flatpak-builder",
+        fedora: "flatpak-builder",
+        suse: "flatpak-builder",
+    },
+    strip: { arch: "binutils", debian: "binutils", fedora: "binutils", suse: "binutils" },
+    tar: { arch: "tar", debian: "tar", fedora: "tar", suse: "tar" },
+};
+
+const EXTRA_HINTS: Record<string, string> = {
+    "flatpak-builder": "or: flatpak install --user -y flathub org.flatpak.Builder",
+    "flatpak-node-generator":
+        "pipx install git+https://github.com/flatpak/flatpak-builder-tools.git#subdirectory=node",
+};
+
+const unquote = (value: string): string => QUOTED.exec(value)?.[1] ?? value;
+
+const readOsReleaseText = (): string => {
+    try {
+        return readFileSync(OS_RELEASE_PATH, "utf8");
+    } catch {
+        return "";
+    }
+};
+
+const osReleaseEntry = (line: string): [string, string] | null => {
+    const match = OS_RELEASE_LINE.exec(line.trim());
+
+    return match?.groups ? [match.groups.key ?? "", unquote(match.groups.value ?? "")] : null;
+};
+
+const readOsRelease = (): Record<string, string> =>
+    Object.fromEntries(
+        readOsReleaseText()
+            .split("\n")
+            .map((line) => osReleaseEntry(line))
+            .filter((entry) => entry !== null),
+    );
+
+const familyForIds = (ids: string[]): PackageFamily => {
+    for (const id of ids) {
+        const family = FAMILY_BY_ID[id];
+
+        if (family !== undefined) {
+            return family;
+        }
+    }
+
+    return "unknown";
+};
+
+const detectPackageFamily = (): PackageFamily => {
+    const release = readOsRelease();
+    const like = (release.ID_LIKE ?? "").split(" ").filter((entry) => entry.length > 0);
+
+    return familyForIds([release.ID ?? "", ...like]);
+};
+
+const installHints = (tool: string, family: PackageFamily): string[] => {
+    const packageName = PACKAGE_FOR_TOOL[tool]?.[family];
+    const command = INSTALL_COMMAND[family];
+    const extra = EXTRA_HINTS[tool];
+    const install = packageName !== undefined && command !== undefined ? [`${command} ${packageName}`] : [];
+
+    return extra === undefined ? install : [...install, extra];
+};
+
+export { detectPackageFamily, installHints };