@gtkx/cli 1.0.0 → 1.1.0

package/src/commands/dev.ts

@@ -1,8 +1,9 @@
 import { defineCommand } from "citty";
-import { ensureGenerated, resolveConfigWatch } from "../codegen/run-codegen.js";
+import { resolveConfigWatch } from "../codegen/run-codegen.js";
 import { type DevWatch, runDevSupervisor } from "../dev/supervisor.js";
 import { splitApplicationArgs } from "../internal/application-args.js";
-import { entryArg, resolveEntry } from "../internal/entry-arg.js";
+import { entryArg } from "../internal/entry-arg.js";
+import { prepareProject } from "../internal/prepare-project.js";
 
 const DEV_MODE = "development";
 
@@ -15,8 +16,7 @@ const dev = defineCommand({
         ...entryArg,
     },
     async run({ args }) {
-        const { cwd, entry: entryPath } = resolveEntry(args);
-        await ensureGenerated(cwd, { shouldAnnounce: true, mode: DEV_MODE });
+        const { cwd, entry: entryPath } = await prepareProject(args, DEV_MODE);
         const watch: DevWatch | undefined = await resolveConfigWatch(cwd, DEV_MODE);
         const { applicationArgs } = splitApplicationArgs(process.argv.slice(2));
         await runDevSupervisor({ entryPath, cwd, args: applicationArgs, watch });

package/src/commands/docs.ts

@@ -13,7 +13,7 @@ import { resolveOmittedProps } from "@gtkx/config/internal";
 import { info } from "@gtkx/utils";
 import { defineCommand } from "citty";
 import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { isAbsolute, relative, resolve, sep } from "node:path";
 import { cwdArg, resolveCwd } from "../internal/entry-arg.js";
 
 const docs = defineCommand({
@@ -25,7 +25,9 @@ const docs = defineCommand({
     args: {
         out: {
             type: "string",
-            description: "Output directory for the generated markdown pages, relative to the project root",
+            description:
+                "Output directory for the generated markdown pages, below the project root. It must be empty " +
+                "or hold an earlier `gtkx docs` run, whose pages are replaced",
             default: "docs/reference",
         },
         "base-path": {
@@ -35,7 +37,9 @@ const docs = defineCommand({
         },
         force: {
             type: "boolean",
-            description: "Regenerate even when the pages are up to date with the GIR libraries",
+            description:
+                "Regenerate even when the pages are up to date with the GIR libraries, the base path, " +
+                "and the element props the project configures",
             default: false,
         },
         ...cwdArg,
@@ -63,7 +67,7 @@ const docs = defineCommand({
 
         const libraries = resolveLibraries(config.libraries, girPath);
         const startedAt = Date.now();
-        const outDir = resolve(cwd, args.out);
+        const outDir = resolveOutDir(cwd, args.out);
         const builtin = await resolveDocsElements(cwd);
 
         const { isRegenerated, namespaces } = writeDocs({
@@ -91,6 +95,37 @@ const docs = defineCommand({
     },
 });
 
+const isBelow = (parent: string, child: string): boolean => {
+    const path = relative(parent, child);
+
+    return path !== "" && path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path);
+};
+
+const outDirReason = (cwd: string, out: string, outDir: string): string => {
+    if (out.trim() === "") {
+        return "it was empty, which names the project root itself";
+    }
+
+    if (outDir === cwd) {
+        return "it names the project root itself";
+    }
+
+    return `${outDir} is outside it`;
+};
+
+const resolveOutDir = (cwd: string, out: string): string => {
+    const outDir = out.trim() === "" ? cwd : resolve(cwd, out);
+
+    if (isBelow(cwd, outDir)) {
+        return outDir;
+    }
+
+    throw new Error(
+        `--out must name a directory below the project root ${cwd}, and ${outDirReason(cwd, out, outDir)}. ` +
+        "Pass a path such as --out=docs/reference.",
+    );
+};
+
 const resolveDocsElements = async (cwd: string): Promise<{ props: ElementProps; omittedProps: OmittedProps }> => {
     const { gi, reactSubexports } = resolveStore(cwd);
 

package/src/deploy/depends.ts

@@ -0,0 +1,42 @@
+import type { DeployConfig } from "./types.js";
+
+type Relations = {
+    deb: string[];
+    rpm: string[];
+};
+
+const GLES_SONAME = "libGLESv2.so.2()(64bit)";
+
+const BASE_DEPENDS: Relations = {
+    deb: ["hicolor-icon-theme", "adwaita-icon-theme", "gsettings-desktop-schemas"],
+    rpm: ["hicolor-icon-theme", "adwaita-icon-theme", "gsettings-desktop-schemas"],
+};
+
+const DEPENDS_BY_LIBRARY: Record<string, Relations> = {
+    "Adw-1": { deb: ["libadwaita-1-0"], rpm: ["libadwaita"] },
+    "Gtk-4.0": { deb: ["libgtk-4-1"], rpm: ["gtk4", GLES_SONAME] },
+    "GtkSource-5": { deb: ["libgtksourceview-5-0"], rpm: ["gtksourceview5"] },
+    "WebKit-6.0": { deb: ["libwebkitgtk-6.0-4"], rpm: ["webkitgtk6.0"] },
+};
+
+const libraryDepends = (libraries: string[]): Relations => ({
+    deb: libraries.flatMap((library) => DEPENDS_BY_LIBRARY[library]?.deb ?? []),
+    rpm: libraries.flatMap((library) => DEPENDS_BY_LIBRARY[library]?.rpm ?? []),
+});
+
+const glibcDepends = (glibcFloor: string | null): Relations =>
+    glibcFloor === null ? { deb: [], rpm: [] } : { deb: [`libc6 (>= ${glibcFloor})`], rpm: [`glibc >= ${glibcFloor}`] };
+
+const dedupe = (entries: string[]): string[] => [...new Set(entries)];
+
+const resolveDepends = (deploy: DeployConfig, libraries: string[], glibcFloor: string | null): Relations => {
+    const fromLibraries = libraryDepends(libraries);
+    const fromGlibc = glibcDepends(glibcFloor);
+
+    return {
+        deb: dedupe([...fromLibraries.deb, ...BASE_DEPENDS.deb, ...fromGlibc.deb, ...(deploy.depends?.deb ?? [])]),
+        rpm: dedupe([...fromLibraries.rpm, ...BASE_DEPENDS.rpm, ...fromGlibc.rpm, ...(deploy.depends?.rpm ?? [])]),
+    };
+};
+
+export { resolveDepends };

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