@gjsify/cli 0.3.20 → 0.4.0

package/src/commands/flatpak/ci.ts

@@ -1,173 +0,0 @@
-// `gjsify flatpak ci` — scaffold .github/workflows/flatpak.yml in the
-// shape used by Flathub-hosted apps:
-//
-//   * upstream `flatpak/flatpak-github-actions/flatpak-builder@v6` action
-//   * `ghcr.io/flathub-infra/flatpak-github-actions:<runtime>-<version>` container
-//   * cache key keyed by commit SHA
-//
-// Idempotent: refuses to overwrite an existing workflow without `--force`.
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import type { Command, ConfigData, ConfigDataFlatpak } from '../../types/index.js';
-import { Config } from '../../config.js';
-import { defaultCiContainer, looksLikeAppId, readPackageJson, resolveRuntime } from './utils.js';
-
-interface FlatpakCiOptions {
-    manifest?: string;
-    bundle?: string;
-    runtimeImage?: string;
-    branches?: string[];
-    out?: string;
-    force?: boolean;
-    cacheKey?: string;
-    verbose?: boolean;
-}
-
-export const flatpakCiCommand: Command<unknown, FlatpakCiOptions> = {
-    command: 'ci',
-    description:
-        'Scaffold .github/workflows/flatpak.yml using the flathub-infra container + flatpak-builder@v6 action.',
-    builder: (yargs) => {
-        return yargs
-            .option('manifest', {
-                description: 'Manifest path the workflow points at (default: <app-id>.json)',
-                type: 'string',
-                normalize: true,
-            })
-            .option('bundle', {
-                description: 'Bundle filename produced by the action (default: <app-id>.flatpak)',
-                type: 'string',
-                normalize: true,
-            })
-            .option('runtime-image', {
-                description:
-                    'Container image override. Default derived from gjsify.flatpak.runtime + runtimeVersion (e.g. `ghcr.io/flathub-infra/flatpak-github-actions:gnome-50`).',
-                type: 'string',
-            })
-            .option('branches', {
-                description: 'Branches the workflow runs on push for (default: main)',
-                type: 'string',
-                array: true,
-            })
-            .option('out', {
-                description: 'Output path',
-                type: 'string',
-                default: '.github/workflows/flatpak.yml',
-                normalize: true,
-            })
-            .option('cache-key', {
-                description: 'Override the action `cache-key` (default: `flatpak-builder-${{ github.sha }}`)',
-                type: 'string',
-            })
-            .option('force', {
-                description: 'Overwrite an existing workflow file',
-                type: 'boolean',
-                default: false,
-            })
-            .option('verbose', {
-                description: 'Print resolved fields',
-                type: 'boolean',
-                default: false,
-            });
-    },
-    handler: async (args) => {
-        const cwd = process.cwd();
-        const cfg = new Config();
-        const configData = await cfg.forBuild({} as never).catch(() => ({} as ConfigData));
-        const flatpak: ConfigDataFlatpak = configData.flatpak ?? {};
-        const pkg = readPackageJson(cwd);
-
-        const appId =
-            flatpak.appId ??
-            (looksLikeAppId(pkg.name) ? (pkg.name as string) : undefined);
-        if (!appId) {
-            throw new Error(
-                'gjsify flatpak ci: no app id available. Set gjsify.flatpak.appId in package.json ' +
-                    'or rename the package to a reverse-DNS id.',
-            );
-        }
-
-        const manifest = (args.manifest as string | undefined) ?? `${appId}.json`;
-        const bundle = (args.bundle as string | undefined) ?? `${appId}.flatpak`;
-
-        const { runtime, runtimeVersion } = resolveRuntime(flatpak, {});
-        const runtimeImage =
-            (args.runtimeImage as string | undefined) ??
-            flatpak.ciContainer ??
-            defaultCiContainer(runtime, runtimeVersion);
-
-        const branches = (args.branches as string[] | undefined) ?? flatpak.ciBranches ?? ['main'];
-        const cacheKey = args.cacheKey ?? 'flatpak-builder-${{ github.sha }}';
-
-        const out = resolve(cwd, args.out ?? '.github/workflows/flatpak.yml');
-        if (existsSync(out) && !args.force) {
-            // Same content → silently skip; different content → fail with a hint.
-            const existing = readFileSync(out, 'utf-8');
-            const next = renderWorkflow({ manifest, bundle, runtimeImage, branches, cacheKey });
-            if (existing === next) {
-                console.log(`[gjsify flatpak ci] ${out} already up to date`);
-                return;
-            }
-            throw new Error(
-                `gjsify flatpak ci: ${out} exists with different content. Pass --force to overwrite.`,
-            );
-        }
-
-        const content = renderWorkflow({ manifest, bundle, runtimeImage, branches, cacheKey });
-        mkdirSync(dirname(out), { recursive: true });
-        writeFileSync(out, content, 'utf-8');
-
-        if (args.verbose) {
-            console.log(
-                `[gjsify flatpak ci] runtime-image=${runtimeImage} manifest=${manifest} bundle=${bundle}`,
-            );
-        }
-        console.log(`[gjsify flatpak ci] wrote ${out}`);
-    },
-};
-
-interface RenderInput {
-    manifest: string;
-    bundle: string;
-    runtimeImage: string;
-    branches: string[];
-    cacheKey: string;
-}
-
-/**
- * Render the workflow YAML. Format string built explicitly (no template
- * library) so the output is byte-stable for diff-based code review.
- */
-function renderWorkflow(input: RenderInput): string {
-    const branchesYaml = `[${input.branches.map((b) => JSON.stringify(b)).join(', ')}]`;
-    return `name: Flatpak
-
-on:
-  push:
-    branches: ${branchesYaml}
-  pull_request:
-    branches: ${branchesYaml}
-
-jobs:
-  flatpak:
-    name: Flatpak Build
-    runs-on: ubuntu-latest
-    container:
-      image: ${input.runtimeImage}
-      options: --privileged
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          submodules: false
-
-      - name: Build Flatpak
-        uses: flatpak/flatpak-github-actions/flatpak-builder@v6
-        with:
-          manifest-path: ${input.manifest}
-          bundle: ${input.bundle}
-          cache-key: ${input.cacheKey}
-`;
-}

package/src/commands/flatpak/deps.ts

@@ -1,120 +0,0 @@
-// `gjsify flatpak deps` — wrap `flatpak-node-generator` to convert a
-// yarn.lock / package-lock.json into the JSON sources file that the
-// Flatpak manifest references for offline `yarn install` inside the
-// build sandbox.
-//
-// flatpak-node-generator is a Python tool from
-// https://github.com/flatpak/flatpak-builder-tools — installed via
-// `pipx install flatpak-node-generator` or `pip install --user
-// flatpak-node-generator`.
-
-import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { mkdirSync } from 'node:fs';
-import type { Command } from '../../types/index.js';
-
-interface FlatpakDepsOptions {
-    lockfile?: string;
-    type?: 'yarn' | 'npm';
-    out?: string;
-    xdgLayout?: boolean;
-    nodeChromedriverFromElectron?: string;
-    electronNodeHeaders?: boolean;
-    verbose?: boolean;
-}
-
-export const flatpakDepsCommand: Command<unknown, FlatpakDepsOptions> = {
-    command: 'deps',
-    description:
-        'Generate Flatpak offline-cache sources from a yarn.lock / package-lock.json (wraps `flatpak-node-generator`).',
-    builder: (yargs) => {
-        return yargs
-            .option('lockfile', {
-                description: 'Path to lockfile (default: yarn.lock or package-lock.json in cwd)',
-                type: 'string',
-                normalize: true,
-            })
-            .option('type', {
-                description: 'Lockfile type. Default: detected from filename.',
-                choices: ['yarn', 'npm'] as const,
-            })
-            .option('out', {
-                description: 'Output JSON sources file',
-                type: 'string',
-                default: 'flatpak-node-sources.json',
-                normalize: true,
-            })
-            .option('xdg-layout', {
-                description: 'Pass --xdg-layout (recommended for Yarn Berry / PnP setups)',
-                type: 'boolean',
-                default: true,
-            })
-            .option('electron-node-headers', {
-                description: 'Pass --electron-node-headers',
-                type: 'boolean',
-                default: false,
-            })
-            .option('verbose', {
-                description: 'Print the underlying flatpak-node-generator invocation',
-                type: 'boolean',
-                default: false,
-            });
-    },
-    handler: async (args) => {
-        const cwd = process.cwd();
-        const lockfile = resolve(
-            cwd,
-            (args.lockfile as string | undefined) ?? detectLockfile(cwd),
-        );
-        if (!existsSync(lockfile)) {
-            throw new Error(
-                `gjsify flatpak deps: lockfile ${lockfile} not found (use --lockfile to override)`,
-            );
-        }
-
-        const type =
-            (args.type as 'yarn' | 'npm' | undefined) ??
-            (lockfile.endsWith('package-lock.json') ? 'npm' : 'yarn');
-
-        const out = resolve(cwd, args.out ?? 'flatpak-node-sources.json');
-        mkdirSync(dirname(out), { recursive: true });
-
-        const cmdArgs = [type, lockfile, '-o', out];
-        if (args.xdgLayout !== false) cmdArgs.push('--xdg-layout');
-        if (args.electronNodeHeaders) cmdArgs.push('--electron-node-headers');
-
-        if (args.verbose) {
-            console.log(`[gjsify flatpak deps] flatpak-node-generator ${cmdArgs.join(' ')}`);
-        }
-
-        await new Promise<void>((res, rej) => {
-            const child = spawn('flatpak-node-generator', cmdArgs, { stdio: 'inherit' });
-            child.on('error', (err: NodeJS.ErrnoException) => {
-                if (err.code === 'ENOENT') {
-                    rej(
-                        new Error(
-                            'gjsify flatpak deps: flatpak-node-generator not found. ' +
-                                'Install via `pipx install flatpak-node-generator` ' +
-                                '(see https://github.com/flatpak/flatpak-builder-tools/tree/master/node).',
-                        ),
-                    );
-                } else {
-                    rej(err);
-                }
-            });
-            child.on('exit', (code) => {
-                if (code === 0) res();
-                else rej(new Error(`gjsify flatpak deps: flatpak-node-generator exited with status ${code}`));
-            });
-        });
-
-        console.log(`[gjsify flatpak deps] wrote ${out}`);
-    },
-};
-
-function detectLockfile(cwd: string): string {
-    if (existsSync(resolve(cwd, 'yarn.lock'))) return 'yarn.lock';
-    if (existsSync(resolve(cwd, 'package-lock.json'))) return 'package-lock.json';
-    return 'yarn.lock'; // surfaces a clear "not found" later
-}

package/src/commands/flatpak/index.ts

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

package/src/commands/flatpak/init.ts

@@ -1,191 +0,0 @@
-// `gjsify flatpak init` — generate a Flatpak manifest from package.json
-// + the `gjsify.flatpak` config namespace.
-//
-// 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';
-import type { Command, ConfigData, ConfigDataFlatpak } from '../../types/index.js';
-import {
-    DEFAULT_CLI_FINISH_ARGS,
-    DEFAULT_GUI_FINISH_ARGS,
-    looksLikeAppId,
-    readPackageJson,
-    resolveRuntime,
-} from './utils.js';
-import { Config } from '../../config.js';
-
-interface FlatpakInitOptions {
-    appId?: string;
-    runtime?: string;
-    runtimeVersion?: string;
-    cliOnly?: boolean;
-    manifest?: string;
-    command?: string;
-    force?: boolean;
-    sdkExtension?: string[];
-    finishArg?: string[];
-    verbose?: boolean;
-}
-
-export const flatpakInitCommand: Command<unknown, FlatpakInitOptions> = {
-    command: 'init',
-    description:
-        'Generate a Flatpak manifest from package.json + `gjsify.flatpak` config.',
-    builder: (yargs) => {
-        return yargs
-            .option('app-id', {
-                description: 'Reverse-DNS app id (default: `gjsify.flatpak.appId` or package.json#name)',
-                type: 'string',
-            })
-            .option('runtime', {
-                description: 'Runtime family',
-                choices: ['gnome', 'freedesktop'] as const,
-            })
-            .option('runtime-version', {
-                description: 'Runtime version (default: gnome -> 50, freedesktop -> 24.08)',
-                type: 'string',
-            })
-            .option('cli-only', {
-                description: 'Strip GUI finish-args; keep `gnome` runtime so GJS is available at runtime',
-                type: 'boolean',
-                default: false,
-            })
-            .option('manifest', {
-                description: 'Output path. Default: `<app-id>.json` in cwd.',
-                type: 'string',
-                normalize: true,
-            })
-            .option('command', {
-                description: 'Binary name in /app/bin (default: app id)',
-                type: 'string',
-            })
-            .option('sdk-extension', {
-                description: 'Extra SDK extension (repeatable)',
-                type: 'string',
-                array: true,
-            })
-            .option('finish-arg', {
-                description: 'Extra finish-arg (repeatable). Override defaults entirely with multiple --finish-arg.',
-                type: 'string',
-                array: true,
-            })
-            .option('force', {
-                description: 'Overwrite an existing manifest',
-                type: 'boolean',
-                default: false,
-            })
-            .option('verbose', {
-                description: 'Print the resolved manifest fields before writing',
-                type: 'boolean',
-                default: false,
-            });
-    },
-    handler: async (args) => {
-        const cfg = new Config();
-        const configData = await cfg.forBuild({} as never).catch(() => ({} as ConfigData));
-        const flatpak: ConfigDataFlatpak = configData.flatpak ?? {};
-        const cwd = process.cwd();
-        const pkg = readPackageJson(cwd);
-
-        const appId =
-            (args.appId as string | undefined) ??
-            flatpak.appId ??
-            (looksLikeAppId(pkg.name) ? (pkg.name as string) : undefined);
-        if (!appId) {
-            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 { runtime, runtimeId, sdk, runtimeVersion } = resolveRuntime(flatpak, {
-            runtime: args.runtime,
-            runtimeVersion: args.runtimeVersion,
-        });
-
-        const sdkExtensions = mergeArrays(flatpak.sdkExtensions, args.sdkExtension);
-        const appendPath = flatpak.appendPath ?? (sdkExtensions?.length ? deriveAppendPath(sdkExtensions) : undefined);
-        const command = (args.command as string | undefined) ?? flatpak.command ?? appId;
-
-        const explicitFinishArgs = args.finishArg as string[] | undefined;
-        const cliOnly = args.cliOnly === true;
-        const finishArgs =
-            explicitFinishArgs !== undefined
-                ? explicitFinishArgs
-                : flatpak.finishArgs ??
-                  (cliOnly ? DEFAULT_CLI_FINISH_ARGS : DEFAULT_GUI_FINISH_ARGS);
-
-        const manifest: Record<string, unknown> = {
-            id: appId,
-            runtime: runtimeId,
-            'runtime-version': runtimeVersion,
-            sdk,
-        };
-        if (sdkExtensions?.length) manifest['sdk-extensions'] = sdkExtensions;
-        if (appendPath?.length) {
-            manifest['build-options'] = { 'append-path': appendPath.join(':') };
-        }
-        manifest.command = command;
-        manifest['finish-args'] = finishArgs;
-
-        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: unknown[] = [];
-        if (flatpak.extraModules?.length) modules.push(...flatpak.extraModules);
-        modules.push({
-            name: deriveModuleName(appId),
-            buildsystem: 'meson',
-            sources: [{ type: 'dir', path: '.' }],
-        });
-        manifest.modules = modules;
-
-        const out = (args.manifest as string | undefined) ?? `${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 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] command=${command} finish-args=${JSON.stringify(finishArgs)}`);
-        }
-        console.log(`[gjsify flatpak init] wrote ${outPath}`);
-    },
-};
-
-/** Concatenate two optional arrays, dropping `undefined`. */
-function mergeArrays(a: string[] | undefined, b: string[] | undefined): string[] | undefined {
-    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: string[]): string[] {
-    const out: string[] = [];
-    for (const ext of sdkExtensions) {
-        const m = /^org\.freedesktop\.Sdk\.Extension\.([A-Za-z0-9-]+)$/.exec(ext);
-        if (m) out.push(`/usr/lib/sdk/${m[1]}/bin`);
-    }
-    out.push('/app/bin');
-    return out;
-}
-
-/** Last segment of the reverse-DNS id, used as the meson-module name. */
-function deriveModuleName(appId: string): string {
-    const parts = appId.split('.');
-    return parts[parts.length - 1] || appId;
-}

package/src/commands/flatpak/utils.ts

@@ -1,76 +0,0 @@
-// Shared helpers for the `gjsify flatpak <sub>` subcommand group.
-
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import type { ConfigDataFlatpak } from '../../types/config-data.js';
-
-/**
- * Default GNOME-Platform runtime version. Bumped per release window.
- * GNOME 50 = April 2026 stable; tracked in
- * https://docs.flathub.org/docs/for-app-authors/requirements.
- */
-export const DEFAULT_GNOME_RUNTIME_VERSION = '50';
-
-/** Default Freedesktop-Platform runtime version (LTS-ish). */
-export const DEFAULT_FREEDESKTOP_RUNTIME_VERSION = '24.08';
-
-/** Permissive GUI defaults for GTK4 + Adwaita apps. */
-export const DEFAULT_GUI_FINISH_ARGS = [
-    '--device=dri',
-    '--share=ipc',
-    '--socket=fallback-x11',
-    '--socket=wayland',
-];
-
-/** Lean defaults for headless CLI tools — no display, no GPU. */
-export const DEFAULT_CLI_FINISH_ARGS: string[] = [];
-
-/** Read package.json from a directory. Throws a helpful error if missing/invalid. */
-export function readPackageJson(dir: string): Record<string, unknown> {
-    const path = resolve(dir, 'package.json');
-    let raw: string;
-    try {
-        raw = readFileSync(path, 'utf-8');
-    } catch {
-        throw new Error(`gjsify flatpak: no package.json found at ${path}`);
-    }
-    try {
-        return JSON.parse(raw) as Record<string, unknown>;
-    } catch (err) {
-        throw new Error(`gjsify flatpak: package.json at ${path} is not valid JSON: ${(err as Error).message}`);
-    }
-}
-
-/** True if a name string looks like a reverse-DNS Flatpak app id. */
-export function looksLikeAppId(value: unknown): value is string {
-    return typeof value === 'string' && /^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z][A-Za-z0-9_-]*){2,}$/.test(value);
-}
-
-/**
- * Pick the runtime + sdk + version triple from config + CLI overrides.
- * `--runtime` and `--runtime-version` flags win over config values.
- */
-export function resolveRuntime(
-    flatpak: ConfigDataFlatpak | undefined,
-    overrides: { runtime?: string; runtimeVersion?: string },
-): { runtime: 'gnome' | 'freedesktop'; runtimeId: string; sdk: string; runtimeVersion: string } {
-    const runtime = (overrides.runtime ?? flatpak?.runtime ?? 'gnome') as 'gnome' | 'freedesktop';
-    if (runtime !== 'gnome' && runtime !== 'freedesktop') {
-        throw new Error(`gjsify flatpak: unknown runtime "${runtime}" (expected "gnome" or "freedesktop")`);
-    }
-    const runtimeVersion =
-        overrides.runtimeVersion ??
-        flatpak?.runtimeVersion ??
-        (runtime === 'gnome' ? DEFAULT_GNOME_RUNTIME_VERSION : DEFAULT_FREEDESKTOP_RUNTIME_VERSION);
-
-    if (runtime === 'gnome') {
-        return { runtime, runtimeId: 'org.gnome.Platform', sdk: 'org.gnome.Sdk', runtimeVersion };
-    }
-    return { runtime, runtimeId: 'org.freedesktop.Platform', sdk: 'org.freedesktop.Sdk', runtimeVersion };
-}
-
-/** Default container image for the GitHub Actions workflow. */
-export function defaultCiContainer(runtime: 'gnome' | 'freedesktop', runtimeVersion: string): string {
-    const tag = `${runtime}-${runtimeVersion}`;
-    return `ghcr.io/flathub-infra/flatpak-github-actions:${tag}`;
-}