@gtkx/cli 1.0.0 → 1.2.0

package/src/deploy/download.ts

@@ -0,0 +1,148 @@
+import { info, warn } from "@gtkx/utils";
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+type DigestRequest = {
+    url: string;
+    dest: string;
+    assetName: string;
+    subject: string;
+};
+
+type DownloadRequest = {
+    url: string;
+    dest: string;
+    label: string;
+    sha256: string;
+    freshSha256?: (() => Promise<string>) | undefined;
+    mode?: number | undefined;
+};
+
+const CACHE_NAMESPACE = "gtkx";
+const DIGEST_PATTERN = /^[\da-f]{64}$/;
+
+const cacheRoot = (): string => {
+    const base = process.env.XDG_CACHE_HOME;
+
+    return join(base !== undefined && base.length > 0 ? base : join(homedir(), ".cache"), CACHE_NAMESPACE);
+};
+
+const cacheDir = (segments: string[]): string => {
+    const dir = join(cacheRoot(), ...segments);
+    mkdirSync(dir, { recursive: true });
+
+    return dir;
+};
+
+const getDigest = (contents: Buffer): string => createHash("sha256").update(contents).digest("hex");
+
+const assertDigest = (url: string, contents: Buffer, expected: string): void => {
+    const actual = getDigest(contents);
+
+    if (actual !== expected) {
+        throw new Error(`Checksum mismatch for ${url}\n  expected ${expected}\n  received ${actual}`);
+    }
+};
+
+const fetchBytes = async (url: string): Promise<Buffer> => {
+    const response = await fetch(url);
+
+    if (!response.ok) {
+        throw new Error(`Cannot download ${url}: HTTP ${String(response.status)} ${response.statusText}`);
+    }
+
+    return Buffer.from(await response.arrayBuffer());
+};
+
+const fetchText = async (url: string): Promise<string> => {
+    const bytes = await fetchBytes(url);
+
+    return bytes.toString("utf8");
+};
+
+const readCachedDigest = (dest: string): string | undefined => {
+    try {
+        const cached = readFileSync(dest, "utf8").trim();
+
+        return DIGEST_PATTERN.test(cached) ? cached : undefined;
+    } catch {
+        return undefined;
+    }
+};
+
+const writeAtomically = (dest: string, contents: string): void => {
+    const staging = `${dest}.partial`;
+    writeFileSync(staging, contents);
+    renameSync(staging, dest);
+};
+
+const publishedDigest = async (request: DigestRequest): Promise<string> => {
+    const checksums = await fetchText(request.url);
+    const digest = digestFromChecksums(checksums, request.assetName, request.subject);
+
+    if (!DIGEST_PATTERN.test(digest)) {
+        throw new Error(`${request.subject} published a malformed checksum for ${request.assetName}: "${digest}"`);
+    }
+
+    writeAtomically(request.dest, digest);
+
+    return digest;
+};
+
+const cachedDigest = async (request: DigestRequest): Promise<string> => {
+    const cached = readCachedDigest(request.dest);
+
+    return cached ?? publishedDigest(request);
+};
+
+const isCacheUsable = (dest: string, sha256: string): boolean => {
+    if (!existsSync(dest)) {
+        return false;
+    }
+
+    if (getDigest(readFileSync(dest)) === sha256) {
+        return true;
+    }
+
+    warn(`Discarding the cached ${dest}: its checksum no longer matches`);
+
+    return false;
+};
+
+const downloadFile = async (request: DownloadRequest): Promise<string> => {
+    const { url, dest, label, sha256, mode } = request;
+
+    if (isCacheUsable(dest, sha256)) {
+        return dest;
+    }
+
+    info(`Downloading ${label}`);
+    const expected = request.freshSha256 === undefined ? sha256 : await request.freshSha256();
+    const contents = await fetchBytes(url);
+    assertDigest(url, contents, expected);
+    const staging = `${dest}.partial`;
+    writeFileSync(staging, contents);
+
+    if (mode !== undefined) {
+        chmodSync(staging, mode);
+    }
+
+    renameSync(staging, dest);
+
+    return dest;
+};
+
+const digestFromChecksums = (checksums: string, assetName: string, subject: string): string => {
+    const line = checksums.split("\n").find((entry) => entry.trim().endsWith(` ${assetName}`));
+    const digest = line?.trim().split(/\s+/, 1)[0];
+
+    if (digest === undefined) {
+        throw new Error(`${subject} publishes no checksum for ${assetName}`);
+    }
+
+    return digest;
+};
+
+export { cacheDir, cachedDigest, type DigestRequest, downloadFile, publishedDigest };

package/src/deploy/freedesktop/copyright.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import type { DeploySettings } from "../types.js";
+
+const FORMAT_URL = "https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/";
+const CONTINUATION_BLANK = " .";
+
+const indentLicenseBody = (body: string): string[] =>
+    body
+        .split("\n")
+        .map((line) => (line.trim().length === 0 ? CONTINUATION_BLANK : ` ${line}`));
+
+const licenseBody = (licenseFile: string | null): string[] => {
+    if (licenseFile === null) {
+        return [];
+    }
+
+    try {
+        return indentLicenseBody(readFileSync(licenseFile, "utf8").trimEnd());
+    } catch {
+        return [];
+    }
+};
+
+const headerLines = (settings: DeploySettings): string[] => [
+    `Format: ${FORMAT_URL}`,
+    `Upstream-Name: ${settings.name}`,
+    ...(settings.homepage === null ? [] : [`Source: ${settings.homepage}`]),
+];
+
+const renderCopyright = (settings: DeploySettings): string =>
+    [
+        ...headerLines(settings),
+        "",
+        "Files: *",
+        `Copyright: ${settings.copyright}`,
+        `License: ${settings.license}`,
+        ...licenseBody(settings.paths.licenseFile),
+        "",
+    ].join("\n");
+
+export { renderCopyright };

package/src/deploy/freedesktop/dbus-service.ts

@@ -0,0 +1,19 @@
+import { posix } from "node:path";
+import type { DeploySettings } from "../types.js";
+import { renderIni } from "./ini.js";
+
+const SERVICE_GROUP = "D-BUS Service";
+const SERVICE_FLAG = "--gapplication-service";
+
+const renderDbusService = (settings: DeploySettings, prefix: string): string =>
+    renderIni([
+        {
+            name: SERVICE_GROUP,
+            entries: [
+                ["Name", settings.applicationId],
+                ["Exec", `${posix.join(prefix, "bin", settings.binaryName)} ${SERVICE_FLAG}`],
+            ],
+        },
+    ]);
+
+export { renderDbusService };

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