@gjsify/cli 0.4.10 → 0.4.12

package/lib/commands/flatpak/check.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from '../../types/index.js';
+interface FlatpakCheckOptions {
+    manifest?: string;
+    repo?: string;
+    metainfo?: string;
+    appstream?: boolean;
+    builderLint?: boolean;
+    verbose?: boolean;
+}
+export declare const flatpakCheckCommand: Command<unknown, FlatpakCheckOptions>;
+export {};

package/lib/commands/flatpak/check.js

@@ -0,0 +1,163 @@
+// `gjsify flatpak check` — run Flathub's pre-submission linters locally.
+//
+// Wraps two tools:
+//   - `appstreamcli validate --strict <metainfo>` — MetaInfo XML
+//     correctness check
+//   - `flatpak-builder-lint manifest <manifest.json>` — manifest
+//     correctness check (and optionally `repo` for built artefacts)
+//
+// Both ship inside the `org.flatpak.Builder` flatpak. We exec them from
+// the host PATH; if missing, print an install hint pointing at
+// `flatpak install -y flathub org.flatpak.Builder`.
+import { existsSync, readdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { readPackageJson, looksLikeAppId } from './utils.js';
+import { Config } from '../../config.js';
+export const flatpakCheckCommand = {
+    command: 'check [manifest]',
+    description: 'Run Flathub pre-submission linters: appstreamcli validate + flatpak-builder-lint.',
+    builder: (yargs) => {
+        return yargs
+            .positional('manifest', {
+            description: 'Path to the Flatpak manifest. Auto-detects `<app-id>.json` if omitted.',
+            type: 'string',
+            normalize: true,
+        })
+            .option('repo', {
+            description: 'Built ostree-repo path. If given, also runs `flatpak-builder-lint repo`.',
+            type: 'string',
+            normalize: true,
+        })
+            .option('metainfo', {
+            description: 'MetaInfo XML path. Default: `data/<app-id>.metainfo.xml.in`.',
+            type: 'string',
+            normalize: true,
+        })
+            .option('appstream', {
+            description: 'Run `appstreamcli validate --strict` (default: true).',
+            type: 'boolean',
+            default: true,
+        })
+            .option('builder-lint', {
+            description: 'Run `flatpak-builder-lint manifest` (default: true).',
+            type: 'boolean',
+            default: true,
+        })
+            .option('verbose', {
+            description: 'Stream linter stdout/stderr verbatim.',
+            type: 'boolean',
+            default: false,
+        });
+    },
+    handler: async (args) => {
+        const cfg = new Config();
+        const configData = await cfg.forBuild({}).catch(() => ({}));
+        const flatpak = configData.flatpak ?? {};
+        const cwd = process.cwd();
+        const appId = resolveAppId(args.manifest, flatpak, cwd);
+        const manifestPath = resolveManifestPath(args.manifest, appId, cwd);
+        const metainfoPath = args.metainfo ?? `data/${appId ?? 'unknown'}.metainfo.xml.in`;
+        const metainfoAbs = resolve(cwd, metainfoPath);
+        let failures = 0;
+        if (args.appstream !== false) {
+            if (!existsSync(metainfoAbs)) {
+                console.warn(`[gjsify flatpak check] skipping appstreamcli — ${metainfoAbs} not found`);
+            }
+            else {
+                const ok = await runLinter('appstreamcli', ['validate', '--strict', metainfoAbs], args.verbose ?? false);
+                if (!ok)
+                    failures++;
+            }
+        }
+        if (args.builderLint !== false) {
+            if (!existsSync(manifestPath)) {
+                console.error(`[gjsify flatpak check] manifest not found: ${manifestPath}`);
+                process.exit(1);
+                return;
+            }
+            const ok = await runLinter('flatpak-builder-lint', ['manifest', manifestPath], args.verbose ?? false);
+            if (!ok)
+                failures++;
+            if (args.repo) {
+                const repoPath = resolve(cwd, args.repo);
+                const okRepo = await runLinter('flatpak-builder-lint', ['repo', repoPath], args.verbose ?? false);
+                if (!okRepo)
+                    failures++;
+            }
+        }
+        if (failures > 0) {
+            console.error(`\n[gjsify flatpak check] ${failures} check(s) failed.`);
+            process.exit(1);
+        }
+        console.log('[gjsify flatpak check] all checks passed.');
+    },
+};
+function resolveAppId(explicit, flatpak, cwd) {
+    if (flatpak.appId)
+        return flatpak.appId;
+    try {
+        const pkg = readPackageJson(cwd);
+        if (looksLikeAppId(pkg.name))
+            return pkg.name;
+    }
+    catch { /* no pkg.json */ }
+    if (explicit) {
+        // strip `.json` extension if present
+        return explicit.replace(/\.json$/, '');
+    }
+    return undefined;
+}
+function resolveManifestPath(explicit, appId, cwd) {
+    if (explicit)
+        return resolve(cwd, explicit);
+    if (appId)
+        return resolve(cwd, `${appId}.json`);
+    // Last resort: find a single *.json that looks like a manifest
+    const candidates = readdirSync(cwd).filter((f) => f.endsWith('.json') && !f.startsWith('package'));
+    if (candidates.length === 1)
+        return resolve(cwd, candidates[0]);
+    throw new Error('gjsify flatpak check: no manifest path given and could not auto-detect. ' +
+        'Pass the manifest as a positional argument.');
+}
+function runLinter(bin, args, verbose) {
+    return new Promise((resolveP) => {
+        const child = spawn(bin, args, {
+            stdio: verbose ? 'inherit' : ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        if (!verbose) {
+            child.stdout?.setEncoding('utf-8');
+            child.stderr?.setEncoding('utf-8');
+            child.stdout?.on('data', (c) => { stdout += c; });
+            child.stderr?.on('data', (c) => { stderr += c; });
+        }
+        child.on('error', (err) => {
+            const e = err;
+            if (e.code === 'ENOENT') {
+                console.error(`[gjsify flatpak check] ${bin} not found in PATH.\n` +
+                    `Install via:\n` +
+                    `  flatpak install -y flathub org.flatpak.Builder\n` +
+                    `  alias ${bin}="flatpak run --command=${bin} org.flatpak.Builder"`);
+            }
+            else {
+                console.error(`[gjsify flatpak check] ${bin} failed to spawn: ${e.message}`);
+            }
+            resolveP(false);
+        });
+        child.on('exit', (code) => {
+            const ok = code === 0;
+            const tag = ok ? 'OK' : 'FAIL';
+            console.log(`[gjsify flatpak check] ${tag}: ${bin} ${args.join(' ')}`);
+            if (!ok && !verbose) {
+                if (stdout.trim())
+                    console.log(stdout.trimEnd());
+                if (stderr.trim())
+                    console.error(stderr.trimEnd());
+            }
+            resolveP(ok);
+        });
+    });
+}
+void join;

package/lib/commands/flatpak/index.d.ts

@@ -3,5 +3,6 @@ import { flatpakInitCommand } from './init.js';
 import { flatpakBuildCommand } from './build.js';
 import { flatpakDepsCommand } from './deps.js';
 import { flatpakCiCommand } from './ci.js';
+import { flatpakCheckCommand } from './check.js';
 export declare const flatpakCommand: Command;
-export { flatpakInitCommand, flatpakBuildCommand, flatpakDepsCommand, flatpakCiCommand, };
+export { flatpakInitCommand, flatpakBuildCommand, flatpakDepsCommand, flatpakCiCommand, flatpakCheckCommand, };

package/lib/commands/flatpak/index.js

@@ -1,23 +1,25 @@
 // `gjsify flatpak` — yargs subcommand-group dispatcher.
 //
-// Wires {init, build, deps, ci}. Each subcommand is a self-contained
+// Wires {init, build, deps, ci, check}. Each subcommand is a self-contained
 // `Command<>` so it composes the same way as `gresource` / `gettext` /
 // `gsettings` at the top level.
 import { flatpakInitCommand } from './init.js';
 import { flatpakBuildCommand } from './build.js';
 import { flatpakDepsCommand } from './deps.js';
 import { flatpakCiCommand } from './ci.js';
+import { flatpakCheckCommand } from './check.js';
 export const flatpakCommand = {
     command: 'flatpak <subcommand>',
-    description: 'Flatpak toolchain: init/build/deps/ci subcommands for shipping GJS apps and CLIs as Flatpaks.',
+    description: 'Flatpak toolchain: init/build/deps/ci/check subcommands for shipping GJS apps and CLIs as Flatpaks.',
     builder: (yargs) => {
         return yargs
             .command(flatpakInitCommand.command, flatpakInitCommand.description, flatpakInitCommand.builder, flatpakInitCommand.handler)
             .command(flatpakBuildCommand.command, flatpakBuildCommand.description, flatpakBuildCommand.builder, flatpakBuildCommand.handler)
             .command(flatpakDepsCommand.command, flatpakDepsCommand.description, flatpakDepsCommand.builder, flatpakDepsCommand.handler)
             .command(flatpakCiCommand.command, flatpakCiCommand.description, flatpakCiCommand.builder, flatpakCiCommand.handler)
+            .command(flatpakCheckCommand.command, flatpakCheckCommand.description, flatpakCheckCommand.builder, flatpakCheckCommand.handler)
             .demandCommand(1)
             .strict();
     },
 };
-export { flatpakInitCommand, flatpakBuildCommand, flatpakDepsCommand, flatpakCiCommand, };
+export { flatpakInitCommand, flatpakBuildCommand, flatpakDepsCommand, flatpakCiCommand, flatpakCheckCommand, };

package/lib/commands/flatpak/init.d.ts

@@ -3,8 +3,12 @@ interface FlatpakInitOptions {
     appId?: string;
     runtime?: string;
     runtimeVersion?: string;
+    kind?: string;
     cliOnly?: boolean;
     manifest?: string;
+    metainfo?: string;
+    desktop?: string;
+    flathubJson?: string;
     command?: string;
     force?: boolean;
     sdkExtension?: string[];

package/lib/commands/flatpak/init.js

@@ -1,19 +1,24 @@
 // `gjsify flatpak init` — generate a Flatpak manifest from package.json
-// + the `gjsify.flatpak` config namespace.
+// + the `gjsify.flatpak` config namespace, plus (Phase F.9) MetaInfo XML,
+// `.desktop` (app kind only), and `flathub.json` policy stub in the same
+// invocation.
 //
 // Defaults are designed for the two real-world shapes:
-//   * GTK4 + Adwaita apps (Learn6502): `gnome` runtime, GUI finish-args
-//   * Headless CLI tools (ts-for-gir): same `gnome` runtime (GJS bundles
-//     need GLib/GIO at runtime — Freedesktop ships no GJS), but lean
-//     finish-args via `--cli-only`. Memory file
-//     `project_flatpak_runtime_choice.md` documents this trade-off.
-import { existsSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+//   * `--kind app` (default) — GTK4 + Adwaita apps (Learn6502): `gnome`
+//     runtime, GUI finish-args, desktop-application MetaInfo, .desktop +
+//     icon required.
+//   * `--kind cli` — headless CLI tools (ts-for-gir): same `gnome` runtime
+//     (GJS bundles need GLib/GIO at runtime — Freedesktop ships no GJS),
+//     but lean finish-args + console-application MetaInfo + flathub.json
+//     with `skip-icons-check`.
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 import { DEFAULT_CLI_FINISH_ARGS, DEFAULT_GUI_FINISH_ARGS, looksLikeAppId, readPackageJson, resolveRuntime, } from './utils.js';
+import { renderDesktop, renderFlathubJson, renderMetainfoApp, renderMetainfoCli, validateScaffoldInputs, } from './scaffold.js';
 import { Config } from '../../config.js';
 export const flatpakInitCommand = {
     command: 'init',
-    description: 'Generate a Flatpak manifest from package.json + `gjsify.flatpak` config.',
+    description: 'Generate Flatpak manifest + MetaInfo XML + .desktop + flathub.json from `gjsify.flatpak` config.',
     builder: (yargs) => {
         return yargs
             .option('app-id', {
@@ -27,14 +32,33 @@ export const flatpakInitCommand = {
             .option('runtime-version', {
             description: 'Runtime version (default: gnome -> 50, freedesktop -> 24.08)',
             type: 'string',
+        })
+            .option('kind', {
+            description: 'App kind: "app" (default, desktop) or "cli" (console-application MetaInfo, no .desktop)',
+            choices: ['app', 'cli'],
         })
             .option('cli-only', {
-            description: 'Strip GUI finish-args; keep `gnome` runtime so GJS is available at runtime',
+            description: '(Deprecated) Alias for `--kind cli`. Use --kind instead.',
             type: 'boolean',
             default: false,
         })
             .option('manifest', {
-            description: 'Output path. Default: `<app-id>.json` in cwd.',
+            description: 'Output path for the manifest. Default: `<app-id>.json` in cwd.',
+            type: 'string',
+            normalize: true,
+        })
+            .option('metainfo', {
+            description: 'Output path for the MetaInfo XML. Default: `data/<app-id>.metainfo.xml.in` in cwd.',
+            type: 'string',
+            normalize: true,
+        })
+            .option('desktop', {
+            description: 'Output path for the .desktop entry (app kind only). Default: `data/<app-id>.desktop.in`.',
+            type: 'string',
+            normalize: true,
+        })
+            .option('flathub-json', {
+            description: 'Output path for the flathub.json policy stub. Default: `flathub.json` in cwd.',
             type: 'string',
             normalize: true,
         })
@@ -53,7 +77,7 @@ export const flatpakInitCommand = {
             array: true,
         })
             .option('force', {
-            description: 'Overwrite an existing manifest',
+            description: 'Overwrite existing output files (manifest, metainfo, desktop, flathub.json)',
             type: 'boolean',
             default: false,
         })
@@ -76,6 +100,9 @@ export const flatpakInitCommand = {
             throw new Error('gjsify flatpak init: no app id available. Pass --app-id, set gjsify.flatpak.appId in package.json, ' +
                 'or rename the package to a reverse-DNS id like org.example.MyApp.');
         }
+        const kind = args.kind ??
+            flatpak.kind ??
+            (args.cliOnly ? 'cli' : 'app');
         const { runtime, runtimeId, sdk, runtimeVersion } = resolveRuntime(flatpak, {
             runtime: args.runtime,
             runtimeVersion: args.runtimeVersion,
@@ -84,11 +111,10 @@ export const flatpakInitCommand = {
         const appendPath = flatpak.appendPath ?? (sdkExtensions?.length ? deriveAppendPath(sdkExtensions) : undefined);
         const command = args.command ?? flatpak.command ?? appId;
         const explicitFinishArgs = args.finishArg;
-        const cliOnly = args.cliOnly === true;
         const finishArgs = explicitFinishArgs !== undefined
             ? explicitFinishArgs
             : flatpak.finishArgs ??
-                (cliOnly ? DEFAULT_CLI_FINISH_ARGS : DEFAULT_GUI_FINISH_ARGS);
+                (kind === 'cli' ? DEFAULT_CLI_FINISH_ARGS : DEFAULT_GUI_FINISH_ARGS);
         const manifest = {
             id: appId,
             runtime: runtimeId,
@@ -105,8 +131,6 @@ export const flatpakInitCommand = {
         const cleanup = flatpak.cleanup;
         if (cleanup?.length)
             manifest.cleanup = cleanup;
-        // Modules: caller-supplied `extraModules` first, then the app's own
-        // meson module pointing at the source dir.
         const modules = [];
         if (flatpak.extraModules?.length)
             modules.push(...flatpak.extraModules);
@@ -116,27 +140,71 @@ export const flatpakInitCommand = {
             sources: [{ type: 'dir', path: '.' }],
         });
         manifest.modules = modules;
-        const out = args.manifest ?? `${appId}.json`;
-        const outPath = resolve(cwd, out);
-        if (existsSync(outPath) && !args.force) {
-            throw new Error(`gjsify flatpak init: ${outPath} exists. Pass --force to overwrite.`);
+        const manifestOut = args.manifest ?? `${appId}.json`;
+        const manifestPath = resolve(cwd, manifestOut);
+        writeIfFresh(manifestPath, JSON.stringify(manifest, null, 4) + '\n', args.force ?? false, 'manifest');
+        const name = pkg.name ?? appId;
+        const scaffold = {
+            appId,
+            name: friendlyName(name, appId),
+            command,
+            kind,
+            flatpak,
+        };
+        const missing = validateScaffoldInputs(scaffold);
+        if (missing.length > 0) {
+            console.warn('[gjsify flatpak init] Manifest written, but MetaInfo / .desktop are skipped — config gaps:');
+            for (const m of missing)
+                console.warn(`  - ${m.field}: ${m.hint}`);
+            console.warn('\nFill these fields in package.json#gjsify.flatpak (or .gjsifyrc.*) and re-run with --force.');
+        }
+        else {
+            const metainfoXml = kind === 'cli' ? renderMetainfoCli(scaffold) : renderMetainfoApp(scaffold);
+            const metainfoOut = args.metainfo ?? `data/${appId}.metainfo.xml.in`;
+            writeIfFresh(resolve(cwd, metainfoOut), metainfoXml, args.force ?? false, 'metainfo');
+            if (kind === 'app') {
+                const desktopOut = args.desktop ?? `data/${appId}.desktop.in`;
+                writeIfFresh(resolve(cwd, desktopOut), renderDesktop(scaffold), args.force ?? false, 'desktop');
+                if (!flatpak.icon) {
+                    console.warn(`[gjsify flatpak init] No gjsify.flatpak.icon set. Flathub requires a scalable SVG at\n` +
+                        `  data/icons/hicolor/scalable/apps/${appId}.svg`);
+                }
+            }
+            const flathubOut = args.flathubJson ?? 'flathub.json';
+            writeIfFresh(resolve(cwd, flathubOut), renderFlathubJson(kind), args.force ?? false, 'flathub.json');
         }
-        const json = JSON.stringify(manifest, null, 4) + '\n';
-        writeFileSync(outPath, json, 'utf-8');
         if (args.verbose) {
-            console.log(`[gjsify flatpak init] runtime=${runtimeId} ${runtimeVersion} sdk=${sdk}`);
+            console.log(`[gjsify flatpak init] kind=${kind} runtime=${runtimeId} ${runtimeVersion} sdk=${sdk}`);
             console.log(`[gjsify flatpak init] command=${command} finish-args=${JSON.stringify(finishArgs)}`);
+            void runtime;
         }
-        console.log(`[gjsify flatpak init] wrote ${outPath}`);
     },
 };
-/** Concatenate two optional arrays, dropping `undefined`. */
+function writeIfFresh(path, content, force, label) {
+    if (existsSync(path) && !force) {
+        console.log(`[gjsify flatpak init] skipped ${label}: ${path} (exists; --force to overwrite)`);
+        return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content, 'utf-8');
+    console.log(`[gjsify flatpak init] wrote ${label}: ${path}`);
+}
+function friendlyName(pkgName, appId) {
+    if (pkgName.startsWith('@')) {
+        const base = pkgName.slice(pkgName.indexOf('/') + 1);
+        return base;
+    }
+    if (pkgName === appId) {
+        const segs = appId.split('.');
+        return segs[segs.length - 1] ?? appId;
+    }
+    return pkgName;
+}
 function mergeArrays(a, b) {
     if (!a?.length && !b?.length)
         return undefined;
     return [...(a ?? []), ...(b ?? [])];
 }
-/** Map known SDK extension ids to their /usr/lib/sdk/<name>/bin paths. */
 function deriveAppendPath(sdkExtensions) {
     const out = [];
     for (const ext of sdkExtensions) {
@@ -147,7 +215,6 @@ function deriveAppendPath(sdkExtensions) {
     out.push('/app/bin');
     return out;
 }
-/** Last segment of the reverse-DNS id, used as the meson-module name. */
 function deriveModuleName(appId) {
     const parts = appId.split('.');
     return parts[parts.length - 1] || appId;

package/lib/commands/flatpak/scaffold.d.ts

@@ -0,0 +1,26 @@
+import type { ConfigDataFlatpak } from '../../types/config-data.js';
+export interface ScaffoldInputs {
+    appId: string;
+    name: string;
+    command: string;
+    kind: 'app' | 'cli';
+    flatpak: ConfigDataFlatpak;
+}
+export interface MissingFieldError {
+    field: string;
+    hint: string;
+}
+/**
+ * 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 declare function validateScaffoldInputs(inputs: ScaffoldInputs): MissingFieldError[];
+/** Render the MetaInfo XML for a desktop application. */
+export declare function renderMetainfoApp(inputs: ScaffoldInputs): string;
+/** Render the MetaInfo XML for a console application. */
+export declare function renderMetainfoCli(inputs: ScaffoldInputs): string;
+/** Render the .desktop entry (app kind only). */
+export declare function renderDesktop(inputs: ScaffoldInputs): string;
+/** Render the flathub.json policy file. */
+export declare function renderFlathubJson(kind: 'app' | 'cli'): string;