@gjsify/cli 0.4.10 → 0.4.12

package/lib/commands/flatpak/scaffold.js

@@ -0,0 +1,327 @@
+// MetaInfo XML / .desktop / flathub.json scaffolding for
+// `gjsify flatpak init`. Phase F.9.6 onwards builds the MetaInfo XML
+// directly in TypeScript instead of substituting into a static 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.
+//
+// `.desktop` and `flathub.json` keep their static templates (they're
+// flat key=value or empty-object files where substitution is fine).
+import { readFileSync } from 'node:fs';
+/**
+ * Lazy template loaders for the two artefacts that stay template-based.
+ * `static-read-inliner` matches this shape and inlines the templates
+ * into the GJS bundle at build time.
+ */
+function loadDesktopTemplate() {
+    return readFileSync(new URL('../../templates/flatpak/desktop.tmpl', import.meta.url), 'utf-8');
+}
+function loadFlathubAppTemplate() {
+    return readFileSync(new URL('../../templates/flatpak/flathub-app.json.tmpl', import.meta.url), 'utf-8');
+}
+function loadFlathubCliTemplate() {
+    return readFileSync(new URL('../../templates/flatpak/flathub-cli.json.tmpl', import.meta.url), 'utf-8');
+}
+/**
+ * Validate that the config has the minimum set of fields required for
+ * MetaInfo XML rendering. Returns the list of missing fields with
+ * actionable hints; empty list means OK.
+ */
+export function validateScaffoldInputs(inputs) {
+    const f = inputs.flatpak;
+    const missing = [];
+    if (!f.developer?.id || !f.developer?.name) {
+        missing.push({
+            field: 'gjsify.flatpak.developer',
+            hint: 'Set `gjsify.flatpak.developer = { "id": "io.github.you", "name": "Your Name" }` in package.json. The id is reverse-DNS.',
+        });
+    }
+    if (!f.summary) {
+        missing.push({
+            field: 'gjsify.flatpak.summary',
+            hint: 'One-line app summary, ≤80 chars, no trailing period. Example: "Learn 6502 assembly language".',
+        });
+    }
+    if (!f.description) {
+        missing.push({
+            field: 'gjsify.flatpak.description',
+            hint: 'Plain text (split on blank lines) or DescriptionBlock[] for rich content with bullet lists + translator hints.',
+        });
+    }
+    if (!f.license?.project) {
+        missing.push({
+            field: 'gjsify.flatpak.license.project',
+            hint: 'SPDX identifier of the project license, e.g. "MIT", "GPL-3.0-or-later".',
+        });
+    }
+    if (!f.homepageUrl) {
+        missing.push({
+            field: 'gjsify.flatpak.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). */
+export function renderDesktop(inputs) {
+    const f = inputs.flatpak;
+    const categoriesLine = (f.categories ?? ['Utility']).join(';') + ';';
+    const keywordsLine = f.keywords?.length
+        ? `Keywords=${f.keywords.join(';')};\n`
+        : '';
+    return substitute(loadDesktopTemplate(), {
+        NAME: inputs.name,
+        SUMMARY: f.summary ?? inputs.name,
+        COMMAND: inputs.command,
+        APP_ID: inputs.appId,
+        CATEGORIES_LINE: categoriesLine,
+        KEYWORDS_LINE: keywordsLine,
+    });
+}
+/** Render the flathub.json policy file. */
+export function renderFlathubJson(kind) {
+    return kind === 'cli' ? loadFlathubCliTemplate() : loadFlathubAppTemplate();
+}
+// ─── MetaInfo XML builder ────────────────────────────────────────────────
+function renderMetainfo(inputs, kind) {
+    const f = inputs.flatpak;
+    const year = new Date().getFullYear();
+    const developerName = f.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(f.license?.metadata ?? 'CC0-1.0')}</metadata_license>`);
+    lines.push(`  <project_license>${escapeXml(f.license?.project ?? '')}</project_license>`);
+    lines.push(`  <name>${escapeXml(inputs.name)}</name>`);
+    pushTranslatorHint(lines, f.summaryTranslatorHint, '  ');
+    lines.push(`  <summary>${escapeXml(f.summary ?? inputs.name)}</summary>`);
+    if (f.iconRemote) {
+        lines.push(`  <icon type="remote">${escapeXml(f.iconRemote)}</icon>`);
+    }
+    // <description>
+    lines.push('  <description>');
+    for (const blockLine of renderDescriptionBlocks(f.description ?? '', '    ')) {
+        lines.push(blockLine);
+    }
+    lines.push('  </description>');
+    // <developer>
+    if (f.developer?.id && f.developer?.name) {
+        lines.push(`  <developer id="${escapeXml(f.developer.id)}">`);
+        const translateAttr = f.developer.nameTranslatable === true ? '' : ' translate="no"';
+        lines.push(`    <name${translateAttr}>${escapeXml(f.developer.name)}</name>`);
+        if (f.developer.email) {
+            lines.push(`    <email>${escapeXml(f.developer.email)}</email>`);
+        }
+        lines.push('  </developer>');
+    }
+    if (kind === 'desktop-application') {
+        lines.push(`  <launchable type="desktop-id">${escapeXml(inputs.appId)}.desktop</launchable>`);
+    }
+    // <screenshots>
+    if (f.screenshots?.length) {
+        lines.push('  <screenshots>');
+        f.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 (f.homepageUrl)
+        lines.push(`  <url type="homepage">${escapeXml(f.homepageUrl)}</url>`);
+    if (f.bugtrackerUrl)
+        lines.push(`  <url type="bugtracker">${escapeXml(f.bugtrackerUrl)}</url>`);
+    if (f.vcsBrowserUrl)
+        lines.push(`  <url type="vcs-browser">${escapeXml(f.vcsBrowserUrl)}</url>`);
+    if (f.donationUrl)
+        lines.push(`  <url type="donation">${escapeXml(f.donationUrl)}</url>`);
+    if (f.translateUrl)
+        lines.push(`  <url type="translate">${escapeXml(f.translateUrl)}</url>`);
+    // <content_rating>
+    const cr = normaliseContentRating(f.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 (f.releases?.length) {
+        lines.push('  <releases>');
+        for (const r of f.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 (f.categories?.length) {
+        lines.push('  <categories>');
+        for (const c of f.categories)
+            lines.push(`    <category>${escapeXml(c)}</category>`);
+        lines.push('  </categories>');
+    }
+    // <keywords>
+    if (f.keywords?.length) {
+        lines.push('  <keywords>');
+        for (const k of f.keywords)
+            lines.push(`    <keyword>${escapeXml(k)}</keyword>`);
+        lines.push('  </keywords>');
+    }
+    // <branding> (apps only — Flathub ignores it on CLI)
+    if (kind === 'desktop-application' && f.branding) {
+        lines.push('  <branding>');
+        lines.push(`    <color type="primary" scheme_preference="light">${escapeXml(f.branding.accentLight)}</color>`);
+        lines.push(`    <color type="primary" scheme_preference="dark">${escapeXml(f.branding.accentDark)}</color>`);
+        lines.push('  </branding>');
+    }
+    // <kudos>
+    if (f.kudos?.length) {
+        lines.push('  <kudos>');
+        for (const k of f.kudos)
+            lines.push(`    <kudo>${escapeXml(k)}</kudo>`);
+        lines.push('  </kudos>');
+    }
+    // <provides> — always emit <binary> for both kinds; <mediatype>/<dbus> only when configured
+    const binaries = f.provides?.binaries ?? [inputs.command];
+    const mimetypes = f.provides?.mimetypes ?? [];
+    const dbus = f.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 m of mimetypes)
+            lines.push(`    <mediatype>${escapeXml(m)}</mediatype>`);
+        for (const d of dbus)
+            lines.push(`    <dbus type="${escapeXml(d.type)}">${escapeXml(d.id)}</dbus>`);
+        lines.push('  </provides>');
+    }
+    // <supports>
+    if (f.supports?.controls?.length || f.supports?.internet) {
+        lines.push('  <supports>');
+        for (const c of f.supports.controls ?? [])
+            lines.push(`    <control>${escapeXml(c)}</control>`);
+        if (f.supports.internet)
+            lines.push(`    <internet>${escapeXml(f.supports.internet)}</internet>`);
+        lines.push('  </supports>');
+    }
+    // <requires>
+    if (f.requires?.displayLengthMin || f.requires?.controls?.length || f.requires?.internet) {
+        lines.push('  <requires>');
+        if (f.requires.displayLengthMin) {
+            lines.push(`    <display_length compare="ge">${f.requires.displayLengthMin}</display_length>`);
+        }
+        for (const c of f.requires.controls ?? [])
+            lines.push(`    <control>${escapeXml(c)}</control>`);
+        if (f.requires.internet)
+            lines.push(`    <internet>${escapeXml(f.requires.internet)}</internet>`);
+        lines.push('  </requires>');
+    }
+    // <recommends>
+    if (f.recommends?.displayLengthMin || f.recommends?.controls?.length) {
+        lines.push('  <recommends>');
+        if (f.recommends.displayLengthMin) {
+            lines.push(`    <display_length compare="ge">${f.recommends.displayLengthMin}</display_length>`);
+        }
+        for (const c of f.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;
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}

package/lib/commands/index.d.ts

@@ -16,3 +16,4 @@ export * from './pack.js';
 export * from './publish.js';
 export * from './self-update.js';
 export * from './generate-installer.js';
+export * from './uninstall.js';

package/lib/commands/index.js

@@ -16,3 +16,4 @@ export * from './pack.js';
 export * from './publish.js';
 export * from './self-update.js';
 export * from './generate-installer.js';
+export * from './uninstall.js';

package/lib/commands/uninstall.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from '../types/index.js';
+interface UninstallOptions {
+    packages: string[];
+    global?: boolean;
+    'dry-run'?: boolean;
+    verbose?: boolean;
+}
+export declare const uninstallCommand: Command<any, UninstallOptions>;
+export {};

package/lib/commands/uninstall.js

@@ -0,0 +1,145 @@
+// `gjsify uninstall -g <pkg>` — symmetric inverse of `install -g`.
+//
+// Removes the installed package tree from the user-global XDG location
+// and any bin shims under `~/.local/bin/` that point into it. Mirrors
+// the layout decisions in install-global.ts:
+//
+//   ~/.local/share/gjsify/global/node_modules/<pkg>/   ← deleted
+//   ~/.local/bin/<bin>                                  ← deleted iff it
+//                                                        execs a path
+//                                                        inside the
+//                                                        removed tree
+//
+// Scope: --global only. Project-local uninstall (mirror of `npm uninstall
+// <pkg>` without -g) is a separate workstream — it needs to rewrite
+// package.json + refresh the lockfile, which install -g doesn't touch.
+import { existsSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { defaultGlobalLayout, specToPackageName } from '../utils/install-global.js';
+export const uninstallCommand = {
+    command: 'uninstall <packages..>',
+    description: 'Uninstall a previously installed package. Currently only `--global` mode is supported.',
+    builder: (yargs) => yargs
+        .positional('packages', {
+        description: 'Package(s) to uninstall (npm names, optionally with version).',
+        type: 'string',
+        array: true,
+        demandOption: true,
+    })
+        .option('global', {
+        description: 'Uninstall from the user-global XDG location (the install -g target).',
+        type: 'boolean',
+        alias: 'g',
+        default: false,
+    })
+        .option('dry-run', {
+        description: 'Show what would be removed without touching the filesystem.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('verbose', {
+        description: 'Verbose logging.',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: (args) => {
+        if (!args.global) {
+            console.error('gjsify uninstall currently only supports --global. ' +
+                'For project-local removal, edit package.json + re-run `gjsify install`.');
+            process.exit(1);
+            return;
+        }
+        const layout = defaultGlobalLayout();
+        const dryRun = args['dry-run'] ?? false;
+        const verbose = args.verbose ?? false;
+        const prefix = `gjsify uninstall${dryRun ? ' (dry-run)' : ''} --global`;
+        console.log(`${prefix}  ← ${layout.prefix}`);
+        console.log(`${' '.repeat(prefix.length)}      bins ← ${layout.binDir}`);
+        let removedAny = false;
+        for (const spec of args.packages) {
+            const pkgName = specToPackageName(spec);
+            const pkgDir = join(layout.prefix, 'node_modules', pkgName);
+            if (!existsSync(pkgDir)) {
+                console.warn(`  ✗  ${pkgName} — not installed at ${pkgDir}`);
+                continue;
+            }
+            // Find bin shims that exec into this package's tree. The shims
+            // are POSIX sh launchers written by linkGlobalBins; we identify
+            // candidates by reading the launcher script and matching the
+            // absolute path.
+            const binsToRemove = findBinShimsForPackage(layout.binDir, pkgDir, verbose);
+            if (dryRun) {
+                console.log(`  •  would remove ${pkgDir}`);
+                for (const bin of binsToRemove) {
+                    console.log(`  •  would remove ${bin}`);
+                }
+            }
+            else {
+                rmSync(pkgDir, { recursive: true, force: true });
+                console.log(`  •  removed ${pkgDir}`);
+                for (const bin of binsToRemove) {
+                    unlinkSync(bin);
+                    console.log(`  •  removed ${bin}`);
+                }
+            }
+            removedAny = true;
+        }
+        if (!removedAny) {
+            console.error('\nNo packages removed.');
+            process.exit(1);
+        }
+    },
+};
+/**
+ * Scan `binDir` for POSIX `sh` launchers whose `exec` target points into
+ * `pkgDir`. The launcher shape is fixed by `linkGlobalBins` — either:
+ *
+ *   #!/bin/sh
+ *   exec '<absolute-path>' "$@"
+ *
+ * or (for `.gjs.mjs` / `.mjs` targets):
+ *
+ *   #!/bin/sh
+ *   exec gjs -m '<absolute-path>' "$@"
+ *
+ * We parse the absolute path out of the single-quoted segment and check
+ * whether it's under `pkgDir`. Non-shim files (e.g. unrelated binaries
+ * the user installed via `npm install -g`) are skipped silently.
+ */
+function findBinShimsForPackage(binDir, pkgDir, verbose) {
+    if (!existsSync(binDir))
+        return [];
+    const matches = [];
+    let entries;
+    try {
+        entries = readdirSync(binDir);
+    }
+    catch {
+        return [];
+    }
+    for (const name of entries) {
+        const fullPath = join(binDir, name);
+        try {
+            const st = statSync(fullPath);
+            if (!st.isFile())
+                continue;
+            const content = readFileSync(fullPath, 'utf-8');
+            if (!content.startsWith('#!/bin/sh'))
+                continue;
+            // Match the first single-quoted absolute path.
+            const m = content.match(/'([^']+)'/);
+            if (!m)
+                continue;
+            const target = m[1];
+            if (target.startsWith(pkgDir + '/') || target === pkgDir) {
+                matches.push(fullPath);
+            }
+        }
+        catch (err) {
+            if (verbose) {
+                console.warn(`  ?  could not inspect ${fullPath}: ${err.message}`);
+            }
+        }
+    }
+    return matches;
+}

package/lib/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
-import { buildCommand as build, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, } from './commands/index.js';
+import { buildCommand as build, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 // `parseAsync()` instead of `.argv` so the top-level await keeps the
 // process alive until command handlers complete. Under Node this is
@@ -29,6 +29,7 @@ await yargs(hideBin(process.argv))
     .command(publish.command, publish.description, publish.builder, publish.handler)
     .command(selfUpdate.command, selfUpdate.description, selfUpdate.builder, selfUpdate.handler)
     .command(generateInstaller.command, generateInstaller.description, generateInstaller.builder, generateInstaller.handler)
+    .command(uninstall.command, uninstall.description, uninstall.builder, uninstall.handler)
     .demandCommand(1)
     .help()
     .parseAsync();

package/lib/templates/flatpak/desktop.tmpl

@@ -0,0 +1,10 @@
+[Desktop Entry]
+Name={{NAME}}
+Comment={{SUMMARY}}
+Exec={{COMMAND}}
+Icon={{APP_ID}}
+Terminal=false
+Type=Application
+Categories={{CATEGORIES_LINE}}
+{{KEYWORDS_LINE}}StartupNotify=true
+StartupWMClass={{APP_ID}}

package/lib/templates/flatpak/flathub-app.json.tmpl

@@ -0,0 +1 @@
+{}

package/lib/templates/flatpak/flathub-cli.json.tmpl

@@ -0,0 +1,3 @@
+{
+  "skip-icons-check": true
+}