@gjsify/cli 0.39.0 → 0.41.0

package/lib/config.js

@@ -233,6 +233,21 @@ export class Config {
             excludeGlobals: config.nodeScript?.excludeGlobals ?? config.excludeGlobals,
         };
     }
+    /**
+     * The config for a command that is NOT a build — `gjsify flatpak …`,
+     * `gjsify ship …`.
+     *
+     * They all want exactly what the loader already produces: the merged
+     * `package.json#gjsify` + config-file object, with none of `forBuild`'s
+     * build-specific defaulting. Reaching it through `forBuild({} as never)`
+     * — five copies of that line before this method existed — lies to the type
+     * system and drags a tsconfig read and bundler defaults into a command
+     * that has no bundle.
+     */
+    async forCommand(searchFrom = process.cwd()) {
+        const { config } = await this.load(searchFrom);
+        return config;
+    }
     async forBuild(cliArgs) {
         const configFile = await this.load(process.cwd());
         const configData = { ...configFile.config };

package/lib/templates/install.mjs.tmpl

@@ -188,9 +188,14 @@ function checkGjsVersion() {
     if (major < 1 || (major === 1 && minor < 86)) {
         error(`gjs ${major}.${minor} is too old — gjsify requires gjs 1.86 or newer.`);
         error('Install hints:');
-        error('  Fedora 43+:  sudo dnf install gjs');
-        error('  Debian 13+:  sudo apt install gjs');
-        error('  Arch:        sudo pacman -S gjs');
+        error('  Fedora 43+:      sudo dnf install gjs');
+        error('  Arch:            sudo pacman -S gjs');
+        // NOT "Debian 13+". Measured 2026-08-16 against tracker.debian.org: trixie
+        // (13, stable) ships 1.82.3, forky (testing) 1.88.1, sid 1.89.2 — 1.84 and
+        // 1.86 were skipped entirely. Sending a trixie user to `apt install gjs`
+        // hands them the very version this branch just rejected, from the branch
+        // that rejected it. Same fact, same wording as `utils/ship/depends.ts`.
+        error('  Debian forky/sid: sudo apt install gjs   (trixie ships 1.82.3 — too old)');
         exit(1);
     }
 }

package/lib/types/config-data.d.ts

@@ -171,6 +171,13 @@ export interface ConfigData {
      * defaults declaratively. CLI flags override these.
      */
     flatpak?: ConfigDataFlatpak;
+    /**
+     * Config for `gjsify ship` — the installable artifacts (`.deb`, `.rpm`)
+     * built from one staged payload. Metadata left unset here falls back to
+     * `gjsify.flatpak`, because both blocks describe the SAME application
+     * (ADR 0024 § 8) and no project should have to write it twice.
+     */
+    ship?: ConfigDataShip;
     /**
      * Config for `gjsify format` / `lint` / `fix`. A thin shell: oxc's own
      * `.oxfmtrc.json` / `.oxlintrc.json` are the real configuration files.
@@ -197,52 +204,14 @@ export interface ConfigDataTest {
     /** Default runtimes when `--runtime` not specified. Default: `['gjs', 'node']`. */
     runtimes?: Array<'gjs' | 'node'>;
 }
-/** Flatpak-toolchain config for the `gjsify flatpak` subcommand group. */
-export interface ConfigDataFlatpak {
-    /** Reverse-DNS app id, e.g. `eu.jumplink.Learn6502`. Defaults to `package.json#name` if it looks like a reverse-DNS id. */
-    appId?: string;
-    /**
-     * Runtime family. Default `'gnome'` — needed at runtime by GJS bundles
-     * for GLib/GObject/GIO. `'freedesktop'` is only suitable for non-gjsify
-     * CLI tools (no GJS interpreter ships in the Freedesktop runtime).
-     */
-    runtime?: 'gnome' | 'freedesktop';
-    /** Runtime/SDK version, e.g. `'50'` for GNOME or `'24.08'` for Freedesktop. */
-    runtimeVersion?: string;
-    /**
-     * Extra SDK extensions for the manifest, e.g.
-     * `['org.freedesktop.Sdk.Extension.llvm17']` for native code needing a specific
-     * toolchain. Leave empty for pure gjsify projects: the GNOME runtime already
-     * ships GJS + GLib + libsoup and `gjsify build` produces a self-contained bundle
-     * that needs no build-time Node.
-     */
-    sdkExtensions?: string[];
-    /** Path components prepended to PATH inside the build sandbox. */
-    appendPath?: string[];
-    /** The binary name to run (`/app/bin/<command>`). Defaults to `appId`. */
-    command?: string;
-    /** Finish-args (capabilities). Default depends on `runtime` + `--cli-only`. */
-    finishArgs?: string[];
-    /** Extra Flatpak modules prepended before the app's own meson/simple module (e.g. `blueprint-compiler` build). */
-    extraModules?: unknown[];
-    /**
-     * Full replacement for the manifest's `modules` array: used verbatim, with
-     * neither `extraModules` nor the meson default added. For CLI tools that ship a
-     * pre-built bundle and install via shell commands (`buildsystem: simple`).
-     */
-    modules?: unknown[];
-    /** Cleanup glob patterns applied to the final manifest, e.g. `['/include', '/lib/pkgconfig']`. */
-    cleanup?: string[];
-    /** Source-of-truth lockfile for `gjsify flatpak deps` — `yarn.lock` or `package-lock.json`. */
-    lockfile?: string;
-    /**
-     * GitHub-Actions container image override for `gjsify flatpak ci`. Default is
-     * derived from runtime + runtimeVersion, e.g. gnome+50 →
-     * `ghcr.io/flathub-infra/flatpak-github-actions:gnome-50`.
-     */
-    ciContainer?: string;
-    /** Branches the generated workflow triggers on. Default `['main']`. */
-    ciBranches?: string[];
+/**
+ * The app metadata every install format needs — AppStream MetaInfo fields plus
+ * what a freedesktop `.desktop` entry is built from. Shared on purpose: a
+ * `.deb`, an `.rpm`, a Flatpak and a macOS bundle all describe the SAME
+ * application, so this block belongs to the app rather than to whichever packer
+ * happens to read it (ADR 0024 § 8).
+ */
+export interface AppMetadata {
     /**
      * `'app'` (default) → desktop-application MetaInfo, GUI finish-args, .desktop +
      * icon required. `'cli'` → console-application MetaInfo with
@@ -394,6 +363,127 @@ export interface ConfigDataFlatpak {
         displayLengthMin?: number;
         controls?: Array<'keyboard' | 'pointing' | 'touch' | 'gamepad' | 'tablet' | 'console'>;
     };
+}
+/**
+ * `gjsify ship` configuration — the packaging half of {@link AppMetadata}.
+ *
+ * Everything here has a derived default; a project that already has a
+ * `gjsify.flatpak` block usually needs no `gjsify.ship` block at all.
+ */
+export interface ConfigDataShip extends AppMetadata {
+    /** Reverse-DNS app id. Falls back to `gjsify.flatpak.appId`, then `package.json#name`. */
+    appId?: string;
+    /**
+     * Package name and `bin/` entry. Default: `package.json#name` with the npm
+     * scope stripped, lowercased, non-alphanumerics folded to `-`.
+     */
+    binaryName?: string;
+    /** Override the upstream version. Default: `package.json#version`, normalised. */
+    version?: string;
+    /** Package revision within one upstream version (deb revision / rpm release). Default `'1'`. */
+    release?: string;
+    /** `Maintainer:` / `Packager:` as `Name <email>`. Default: `package.json#author`. */
+    maintainer?: string;
+    /** Formats to build when `--target` is not given. Default `['deb', 'rpm']`. */
+    targets?: string[];
+    /** Output root, relative to the project. Default `'ship'`. */
+    outDir?: string;
+    /**
+     * The built bundle `bin/<name>` executes. Default: `gjsify.main`, then
+     * `package.json#main`. Its whole directory is staged into `lib/<name>/`.
+     */
+    bundle?: string;
+    /** Icon file, or a directory of them. Sizes are read from the path or the filename. */
+    icon?: string;
+    /** A `*.gschema.xml` file, or a directory of them. */
+    schemas?: string;
+    /** Licence file. Default: the first of LICENSE, LICENSE.md, LICENSE.txt, COPYING. */
+    licenseFile?: string;
+    /** deb `Section:`. Default: derived from `categories`. */
+    section?: string;
+    /** rpm `Group:`. Default: derived from `categories`. */
+    group?: string;
+    /**
+     * Minimum GJS the emitted dependency asks for. Default `'1.86'` — what the
+     * bundler targets. Lower it only if the bundle genuinely runs on an older
+     * GJS: no released Debian ships 1.86, so the default makes a `.deb` that
+     * apt refuses on trixie rather than one that installs and then fails to
+     * start.
+     */
+    minGjsVersion?: string;
+    /**
+     * Runtime dependencies appended to the set derived from the bundle's
+     * `gi://` imports — the escape hatch for a namespace the table does not
+     * know, and for anything that is not a typelib at all.
+     */
+    depends?: {
+        deb?: string[];
+        rpm?: string[];
+    };
+    /**
+     * GI namespace → the package that ships its typelib, filling gaps in the
+     * built-in table (`Nautilus-3.0`, a namespace from a private library, …).
+     * A row here wins over the built-in one.
+     *
+     * This is what unblocks a namespace `gjsify ship` does not know; `depends`
+     * is for dependencies that are not typelibs at all and deliberately does
+     * not silence the unmapped-namespace failure.
+     */
+    typelibPackages?: Record<string, {
+        deb: string;
+        rpm: string;
+    }>;
+    /** Extra payload entries: prefix-relative destination → project-relative source. */
+    extraFiles?: Record<string, string>;
+    /** Arguments the launcher appends before the user's own. */
+    execArgs?: string[];
+}
+/** Flatpak-toolchain config for the `gjsify flatpak` subcommand group. */
+export interface ConfigDataFlatpak extends AppMetadata {
+    /** Reverse-DNS app id, e.g. `eu.jumplink.Learn6502`. Defaults to `package.json#name` if it looks like a reverse-DNS id. */
+    appId?: string;
+    /**
+     * Runtime family. Default `'gnome'` — needed at runtime by GJS bundles
+     * for GLib/GObject/GIO. `'freedesktop'` is only suitable for non-gjsify
+     * CLI tools (no GJS interpreter ships in the Freedesktop runtime).
+     */
+    runtime?: 'gnome' | 'freedesktop';
+    /** Runtime/SDK version, e.g. `'50'` for GNOME or `'24.08'` for Freedesktop. */
+    runtimeVersion?: string;
+    /**
+     * Extra SDK extensions for the manifest, e.g.
+     * `['org.freedesktop.Sdk.Extension.llvm17']` for native code needing a specific
+     * toolchain. Leave empty for pure gjsify projects: the GNOME runtime already
+     * ships GJS + GLib + libsoup and `gjsify build` produces a self-contained bundle
+     * that needs no build-time Node.
+     */
+    sdkExtensions?: string[];
+    /** Path components prepended to PATH inside the build sandbox. */
+    appendPath?: string[];
+    /** The binary name to run (`/app/bin/<command>`). Defaults to `appId`. */
+    command?: string;
+    /** Finish-args (capabilities). Default depends on `runtime` + `--cli-only`. */
+    finishArgs?: string[];
+    /** Extra Flatpak modules prepended before the app's own meson/simple module (e.g. `blueprint-compiler` build). */
+    extraModules?: unknown[];
+    /**
+     * Full replacement for the manifest's `modules` array: used verbatim, with
+     * neither `extraModules` nor the meson default added. For CLI tools that ship a
+     * pre-built bundle and install via shell commands (`buildsystem: simple`).
+     */
+    modules?: unknown[];
+    /** Cleanup glob patterns applied to the final manifest, e.g. `['/include', '/lib/pkgconfig']`. */
+    cleanup?: string[];
+    /** Source-of-truth lockfile for `gjsify flatpak deps` — `yarn.lock` or `package-lock.json`. */
+    lockfile?: string;
+    /**
+     * GitHub-Actions container image override for `gjsify flatpak ci`. Default is
+     * derived from runtime + runtimeVersion, e.g. gnome+50 →
+     * `ghcr.io/flathub-infra/flatpak-github-actions:gnome-50`.
+     */
+    ciContainer?: string;
+    /** Branches the generated workflow triggers on. Default `['main']`. */
+    ciBranches?: string[];
     /**
      * Flathub tracking-repo override for `gjsify flatpak sync-flathub` / `diff`.
      * Default `flathub/<appId>`; set when the upstream repo deviates.

package/lib/utils/app-metadata.d.ts

@@ -0,0 +1,51 @@
+import type { AppMetadata } from '../types/config-data.js';
+/** Everything a renderer needs that is not part of {@link AppMetadata} itself. */
+export interface AppMetadataInputs {
+    /** Reverse-DNS application id — the MetaInfo `<id>` and the icon/desktop basename. */
+    appId: string;
+    /** Human-readable display name. */
+    name: string;
+    /** The binary to launch (`Exec=`, and the default `<provides><binary>`). */
+    command: string;
+    /** `'app'` renders a desktop-application component, `'cli'` a console one. */
+    kind: 'app' | 'cli';
+    metadata: AppMetadata;
+    /**
+     * Config path the validator names in its hints, e.g. `gjsify.flatpak` or
+     * `gjsify.ship`. Both read the same fields, so the hint has to say which
+     * block the caller was actually reading.
+     */
+    configKey: string;
+    /**
+     * Year for the copyright comment. Passed in rather than read from the
+     * clock: this XML is PAYLOAD, so `new Date()` here makes the artifact's
+     * bytes depend on when it was packed — a reproducibility hole no test
+     * running inside one second can see. Defaults to the current year for
+     * callers that write the file to a source tree rather than into a package.
+     */
+    copyrightYear?: number;
+}
+export interface MissingFieldError {
+    field: string;
+    hint: string;
+}
+/**
+ * Validate that the metadata has the minimum set of fields AppStream needs.
+ * Returns the missing fields with actionable hints; an empty list means OK.
+ */
+export declare function validateAppMetadata(inputs: AppMetadataInputs): MissingFieldError[];
+/** Render the MetaInfo XML for a desktop application. */
+export declare function renderMetainfoApp(inputs: AppMetadataInputs): string;
+/** Render the MetaInfo XML for a console application. */
+export declare function renderMetainfoCli(inputs: AppMetadataInputs): string;
+/**
+ * Render the `.desktop` entry (app kind only).
+ *
+ * `Exec=` carries a field code when the app declares MIME types, because a
+ * desktop entry with `MimeType=` and no `%f`/`%u` is registered as a handler
+ * that is then launched with no argument — the file the user double-clicked is
+ * dropped on the floor, and `desktop-file-validate` says so. `x-scheme-handler/*`
+ * wins over file types: a URL handler must take `%u`.
+ */
+export declare function renderDesktopEntry(inputs: AppMetadataInputs): string;
+export declare function escapeXml(value: string): string;

package/lib/utils/app-metadata.js

@@ -0,0 +1,338 @@
+// AppStream MetaInfo XML + freedesktop `.desktop` rendering, shared by every
+// install format.
+//
+// These files describe the APPLICATION, not the container it ships in: a
+// `.deb`, an `.rpm`, a Flatpak and (later) a macOS bundle all want the same
+// `<name>`, `<summary>`, categories, keywords and icon name. They lived under
+// `commands/flatpak/` while Flatpak was the only packer; ADR 0024 § 8 moves
+// them out so `gjsify ship` reads them without importing another command.
+//
+// The MetaInfo XML is built line by line in TypeScript rather than substituted
+// into a template: the AppStream surface (description blocks, per-release rich
+// notes, translator hints, kudos, supports/requires/recommends, content_rating
+// attributes, provides) has too many optional nested sections for a
+// template+placeholder approach to stay legible. The `.desktop` entry stays
+// template-based — it is flat `key=value`.
+import { readFileSync } from 'node:fs';
+/**
+ * Lazy template loader. `static-read-inliner` matches this exact shape
+ * (`readFileSync(new URL(<literal>, import.meta.url), 'utf-8')`) and inlines
+ * the template into the GJS bundle at build time — a `join(__dirname, …)`
+ * spelling silently loses that and ENOENTs under GJS.
+ */
+function loadDesktopTemplate() {
+    return readFileSync(new URL('../templates/app/desktop.tmpl', import.meta.url), 'utf-8');
+}
+/**
+ * Validate that the metadata has the minimum set of fields AppStream needs.
+ * Returns the missing fields with actionable hints; an empty list means OK.
+ */
+export function validateAppMetadata(inputs) {
+    const m = inputs.metadata;
+    const key = inputs.configKey;
+    const missing = [];
+    if (!m.developer?.id || !m.developer?.name) {
+        missing.push({
+            field: `${key}.developer`,
+            hint: `Set \`${key}.developer = { "id": "io.github.you", "name": "Your Name" }\` in package.json. The id is reverse-DNS.`,
+        });
+    }
+    if (!m.summary) {
+        missing.push({
+            field: `${key}.summary`,
+            hint: 'One-line app summary, ≤80 chars, no trailing period. Example: "Learn 6502 assembly language".',
+        });
+    }
+    if (!m.description) {
+        missing.push({
+            field: `${key}.description`,
+            hint: 'Plain text (split on blank lines) or DescriptionBlock[] for rich content with bullet lists + translator hints.',
+        });
+    }
+    if (!m.license?.project) {
+        missing.push({
+            field: `${key}.license.project`,
+            hint: 'SPDX identifier of the project license, e.g. "MIT", "GPL-3.0-or-later".',
+        });
+    }
+    if (!m.homepageUrl) {
+        missing.push({
+            field: `${key}.homepageUrl`,
+            hint: 'Required by Flathub. Example: "https://github.com/you/your-repo".',
+        });
+    }
+    return missing;
+}
+/** Render the MetaInfo XML for a desktop application. */
+export function renderMetainfoApp(inputs) {
+    return renderMetainfo(inputs, 'desktop-application');
+}
+/** Render the MetaInfo XML for a console application. */
+export function renderMetainfoCli(inputs) {
+    return renderMetainfo(inputs, 'console-application');
+}
+/**
+ * Render the `.desktop` entry (app kind only).
+ *
+ * `Exec=` carries a field code when the app declares MIME types, because a
+ * desktop entry with `MimeType=` and no `%f`/`%u` is registered as a handler
+ * that is then launched with no argument — the file the user double-clicked is
+ * dropped on the floor, and `desktop-file-validate` says so. `x-scheme-handler/*`
+ * wins over file types: a URL handler must take `%u`.
+ */
+export function renderDesktopEntry(inputs) {
+    const m = inputs.metadata;
+    const categoriesLine = (m.categories ?? ['Utility']).join(';') + ';';
+    const keywordsLine = m.keywords?.length ? `Keywords=${m.keywords.join(';')};\n` : '';
+    // `MimeType=` is sourced from `<config>.provides.mimetypes` — the same field
+    // already populates `<mediatype>` entries in the MetaInfo XML, so callers
+    // configure both with one knob. Typical entries: `x-scheme-handler/<scheme>`
+    // for URL-scheme handlers, or `application/<mime>` for file-type handlers.
+    const mimetypes = m.provides?.mimetypes ?? [];
+    const mimetypesLine = mimetypes.length ? `MimeType=${mimetypes.join(';')};\n` : '';
+    return substitute(loadDesktopTemplate(), {
+        NAME: inputs.name,
+        SUMMARY: m.summary ?? inputs.name,
+        COMMAND: `${inputs.command}${execFieldCode(mimetypes)}`,
+        APP_ID: inputs.appId,
+        CATEGORIES_LINE: categoriesLine,
+        KEYWORDS_LINE: keywordsLine,
+        MIMETYPES_LINE: mimetypesLine,
+    });
+}
+/** The `Exec=` field code implied by the declared MIME types. */
+function execFieldCode(mimetypes) {
+    if (mimetypes.some((t) => t.startsWith('x-scheme-handler/')))
+        return ' %u';
+    if (mimetypes.length > 0)
+        return ' %f';
+    return '';
+}
+// ─── MetaInfo XML builder ────────────────────────────────────────────────
+function renderMetainfo(inputs, kind) {
+    const m = inputs.metadata;
+    const year = inputs.copyrightYear ?? new Date().getFullYear();
+    const developerName = m.developer?.name ?? '';
+    const lines = [];
+    lines.push('<?xml version="1.0" encoding="UTF-8"?>');
+    lines.push(`<!-- Copyright ${year} ${escapeXml(developerName)} -->`);
+    lines.push(`<component type="${kind}">`);
+    lines.push(`  <id>${escapeXml(inputs.appId)}</id>`);
+    lines.push(`  <metadata_license>${escapeXml(m.license?.metadata ?? 'CC0-1.0')}</metadata_license>`);
+    lines.push(`  <project_license>${escapeXml(m.license?.project ?? '')}</project_license>`);
+    lines.push(`  <name>${escapeXml(inputs.name)}</name>`);
+    pushTranslatorHint(lines, m.summaryTranslatorHint, '  ');
+    lines.push(`  <summary>${escapeXml(m.summary ?? inputs.name)}</summary>`);
+    if (m.iconRemote) {
+        lines.push(`  <icon type="remote">${escapeXml(m.iconRemote)}</icon>`);
+    }
+    // <description>
+    lines.push('  <description>');
+    for (const blockLine of renderDescriptionBlocks(m.description ?? '', '    ')) {
+        lines.push(blockLine);
+    }
+    lines.push('  </description>');
+    // <developer>
+    if (m.developer?.id && m.developer?.name) {
+        lines.push(`  <developer id="${escapeXml(m.developer.id)}">`);
+        const translateAttr = m.developer.nameTranslatable === true ? '' : ' translate="no"';
+        lines.push(`    <name${translateAttr}>${escapeXml(m.developer.name)}</name>`);
+        if (m.developer.email) {
+            lines.push(`    <email>${escapeXml(m.developer.email)}</email>`);
+        }
+        lines.push('  </developer>');
+    }
+    if (kind === 'desktop-application') {
+        lines.push(`  <launchable type="desktop-id">${escapeXml(inputs.appId)}.desktop</launchable>`);
+    }
+    // <screenshots>
+    if (m.screenshots?.length) {
+        lines.push('  <screenshots>');
+        m.screenshots.forEach((s, i) => {
+            const type = s.type ?? (i === 0 ? 'default' : undefined);
+            const typeAttr = type ? ` type="${escapeXml(type)}"` : '';
+            const envAttr = s.environment ? ` environment="${escapeXml(s.environment)}"` : '';
+            lines.push(`    <screenshot${typeAttr}${envAttr}>`);
+            lines.push(`      <image>${escapeXml(s.url)}</image>`);
+            if (s.caption) {
+                pushTranslatorHint(lines, s.captionTranslatorHint, '      ');
+                lines.push(`      <caption>${escapeXml(s.caption)}</caption>`);
+            }
+            lines.push('    </screenshot>');
+        });
+        lines.push('  </screenshots>');
+    }
+    // <url> entries
+    if (m.homepageUrl)
+        lines.push(`  <url type="homepage">${escapeXml(m.homepageUrl)}</url>`);
+    if (m.bugtrackerUrl)
+        lines.push(`  <url type="bugtracker">${escapeXml(m.bugtrackerUrl)}</url>`);
+    if (m.vcsBrowserUrl)
+        lines.push(`  <url type="vcs-browser">${escapeXml(m.vcsBrowserUrl)}</url>`);
+    if (m.donationUrl)
+        lines.push(`  <url type="donation">${escapeXml(m.donationUrl)}</url>`);
+    if (m.translateUrl)
+        lines.push(`  <url type="translate">${escapeXml(m.translateUrl)}</url>`);
+    // <content_rating>
+    const cr = normaliseContentRating(m.contentRating);
+    if (cr.attributes && Object.keys(cr.attributes).length > 0) {
+        lines.push(`  <content_rating type="${escapeXml(cr.type)}">`);
+        for (const [key, value] of Object.entries(cr.attributes)) {
+            lines.push(`    <content_attribute id="${escapeXml(key)}">${escapeXml(value)}</content_attribute>`);
+        }
+        lines.push('  </content_rating>');
+    }
+    else {
+        lines.push(`  <content_rating type="${escapeXml(cr.type)}" />`);
+    }
+    // <releases>
+    if (m.releases?.length) {
+        lines.push('  <releases>');
+        for (const r of m.releases) {
+            if (r.description === undefined) {
+                lines.push(`    <release version="${escapeXml(r.version)}" date="${escapeXml(r.date)}" />`);
+            }
+            else {
+                lines.push(`    <release version="${escapeXml(r.version)}" date="${escapeXml(r.date)}">`);
+                lines.push('      <description>');
+                for (const blockLine of renderDescriptionBlocks(r.description, '        ')) {
+                    lines.push(blockLine);
+                }
+                lines.push('      </description>');
+                lines.push('    </release>');
+            }
+        }
+        lines.push('  </releases>');
+    }
+    // <categories>
+    if (m.categories?.length) {
+        lines.push('  <categories>');
+        for (const c of m.categories)
+            lines.push(`    <category>${escapeXml(c)}</category>`);
+        lines.push('  </categories>');
+    }
+    // <keywords>
+    if (m.keywords?.length) {
+        lines.push('  <keywords>');
+        for (const k of m.keywords)
+            lines.push(`    <keyword>${escapeXml(k)}</keyword>`);
+        lines.push('  </keywords>');
+    }
+    // <branding> (apps only — Flathub ignores it on CLI)
+    if (kind === 'desktop-application' && m.branding) {
+        lines.push('  <branding>');
+        lines.push(`    <color type="primary" scheme_preference="light">${escapeXml(m.branding.accentLight)}</color>`);
+        lines.push(`    <color type="primary" scheme_preference="dark">${escapeXml(m.branding.accentDark)}</color>`);
+        lines.push('  </branding>');
+    }
+    // <kudos>
+    if (m.kudos?.length) {
+        lines.push('  <kudos>');
+        for (const k of m.kudos)
+            lines.push(`    <kudo>${escapeXml(k)}</kudo>`);
+        lines.push('  </kudos>');
+    }
+    // <provides> — always emit <binary> for both kinds; <mediatype>/<dbus> only when configured
+    const binaries = m.provides?.binaries ?? [inputs.command];
+    const mimetypes = m.provides?.mimetypes ?? [];
+    const dbus = m.provides?.dbus ?? [];
+    if (binaries.length || mimetypes.length || dbus.length) {
+        lines.push('  <provides>');
+        for (const b of binaries)
+            lines.push(`    <binary>${escapeXml(b)}</binary>`);
+        for (const t of mimetypes)
+            lines.push(`    <mediatype>${escapeXml(t)}</mediatype>`);
+        for (const d of dbus)
+            lines.push(`    <dbus type="${escapeXml(d.type)}">${escapeXml(d.id)}</dbus>`);
+        lines.push('  </provides>');
+    }
+    // <supports>
+    if (m.supports?.controls?.length || m.supports?.internet) {
+        lines.push('  <supports>');
+        for (const c of m.supports.controls ?? [])
+            lines.push(`    <control>${escapeXml(c)}</control>`);
+        if (m.supports.internet)
+            lines.push(`    <internet>${escapeXml(m.supports.internet)}</internet>`);
+        lines.push('  </supports>');
+    }
+    // <requires>
+    if (m.requires?.displayLengthMin || m.requires?.controls?.length || m.requires?.internet) {
+        lines.push('  <requires>');
+        if (m.requires.displayLengthMin) {
+            lines.push(`    <display_length compare="ge">${m.requires.displayLengthMin}</display_length>`);
+        }
+        for (const c of m.requires.controls ?? [])
+            lines.push(`    <control>${escapeXml(c)}</control>`);
+        if (m.requires.internet)
+            lines.push(`    <internet>${escapeXml(m.requires.internet)}</internet>`);
+        lines.push('  </requires>');
+    }
+    // <recommends>
+    if (m.recommends?.displayLengthMin || m.recommends?.controls?.length) {
+        lines.push('  <recommends>');
+        if (m.recommends.displayLengthMin) {
+            lines.push(`    <display_length compare="ge">${m.recommends.displayLengthMin}</display_length>`);
+        }
+        for (const c of m.recommends.controls ?? [])
+            lines.push(`    <control>${escapeXml(c)}</control>`);
+        lines.push('  </recommends>');
+    }
+    lines.push('</component>');
+    return lines.join('\n') + '\n';
+}
+// ─── Description block renderer ──────────────────────────────────────────
+function renderDescriptionBlocks(description, indent) {
+    const blocks = typeof description === 'string' ? stringToBlocks(description) : description;
+    const out = [];
+    for (const block of blocks) {
+        if ('p' in block) {
+            pushTranslatorHint(out, block.translatorHint, indent);
+            out.push(`${indent}<p>${escapeXml(block.p.trim().replace(/\s+/g, ' '))}</p>`);
+        }
+        else {
+            pushTranslatorHint(out, block.translatorHint, indent);
+            out.push(`${indent}<ul>`);
+            for (const item of block.ul) {
+                if (typeof item === 'string') {
+                    out.push(`${indent}  <li>${escapeXml(item)}</li>`);
+                }
+                else {
+                    pushTranslatorHint(out, item.translatorHint, `${indent}  `);
+                    out.push(`${indent}  <li>${escapeXml(item.item)}</li>`);
+                }
+            }
+            out.push(`${indent}</ul>`);
+        }
+    }
+    return out;
+}
+/** Auto-convert blank-line-split string into paragraph blocks. */
+function stringToBlocks(s) {
+    return s
+        .trim()
+        .split(/\n\n+/)
+        .map((para) => ({ p: para.trim().replace(/\s+/g, ' ') }));
+}
+function pushTranslatorHint(out, hint, indent) {
+    if (!hint)
+        return;
+    out.push(`${indent}<!-- TRANSLATORS: ${hint} -->`);
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────
+function normaliseContentRating(cr) {
+    if (cr === undefined)
+        return { type: 'oars-1.1' };
+    if (typeof cr === 'string')
+        return { type: cr };
+    return { type: cr.type ?? 'oars-1.1', attributes: cr.attributes };
+}
+function substitute(template, tokens) {
+    let out = template;
+    for (const [key, value] of Object.entries(tokens)) {
+        out = out.split(`{{${key}}}`).join(value);
+    }
+    return out;
+}
+export function escapeXml(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}

package/lib/utils/check-system-deps.d.ts

@@ -126,8 +126,8 @@ export declare const PACKAGE_DEPS: Record<string, string[]>;
  */
 export declare function runAllChecks(cwd: string): DepCheck[];
 /**
- * Minimal checks needed to run any GJS example (Node + GJS binaries only).
- * Used by `gjsify showcase` for examples that have no native deps.
+ * Minimal checks needed to run any GJS example (the GJS binary; Node is reported but
+ * not required). Used by `gjsify showcase` for examples that have no native deps.
  */
 export declare function runMinimalChecks(): DepCheck[];
 /**