@gjsify/cli 0.3.14 → 0.3.16

package/src/commands/flatpak/build.ts

@@ -0,0 +1,225 @@
+// `gjsify flatpak build` — wrap `flatpak-builder` with sensible defaults.
+//
+// Replaces the project-local `build-flatpak.sh`-style scripts: same flag
+// shape (manifest, build-dir, install, repo, bundle), plus a `--tarball`
+// helper for Flathub submissions.
+
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import type { Command } from '../../types/index.js';
+
+interface FlatpakBuildOptions {
+    manifest?: string;
+    buildDir?: string;
+    install?: boolean;
+    repo?: string;
+    bundle?: string;
+    tarball?: string;
+    forceClean?: boolean;
+    sandbox?: boolean;
+    deleteBuildDirs?: boolean;
+    installDepsFrom?: string;
+    verbose?: boolean;
+}
+
+export const flatpakBuildCommand: Command<unknown, FlatpakBuildOptions> = {
+    command: 'build [manifest]',
+    description:
+        'Build the Flatpak via `flatpak-builder`. Wraps a typical install + export + bundle + tarball pipeline.',
+    builder: (yargs) => {
+        return yargs
+            .positional('manifest', {
+                description: 'Path to the Flatpak manifest (default: first *.json that looks like a manifest in cwd)',
+                type: 'string',
+                normalize: true,
+            })
+            .option('build-dir', {
+                description: 'flatpak-builder working directory',
+                type: 'string',
+                default: 'flatpak-build',
+                normalize: true,
+            })
+            .option('install', {
+                description: 'After build, run `flatpak-builder --user --install` to install locally',
+                type: 'boolean',
+                default: false,
+            })
+            .option('repo', {
+                description: 'Export the build into the given OSTree repo (passes `--repo=<dir>` to flatpak-builder)',
+                type: 'string',
+                normalize: true,
+            })
+            .option('bundle', {
+                description: 'After --repo export, build a single-file bundle (`flatpak build-bundle`) at this path',
+                type: 'string',
+                normalize: true,
+            })
+            .option('tarball', {
+                description: 'Create a tarball of the build dir (parity with the legacy build-flatpak.sh tarball step)',
+                type: 'string',
+                normalize: true,
+            })
+            .option('force-clean', {
+                description: 'Pass --force-clean to flatpak-builder (default true)',
+                type: 'boolean',
+                default: true,
+            })
+            .option('sandbox', {
+                description: 'Pass --sandbox to flatpak-builder (default true)',
+                type: 'boolean',
+                default: true,
+            })
+            .option('delete-build-dirs', {
+                description: 'Pass --delete-build-dirs to flatpak-builder (default true)',
+                type: 'boolean',
+                default: true,
+            })
+            .option('install-deps-from', {
+                description: 'Pass --install-deps-from to flatpak-builder (e.g. `flathub`)',
+                type: 'string',
+            })
+            .option('verbose', {
+                description: 'Print the underlying flatpak-builder invocations',
+                type: 'boolean',
+                default: false,
+            });
+    },
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const manifest = resolve(cwd, (args.manifest as string | undefined) ?? findDefaultManifest(cwd));
+        if (!existsSync(manifest)) {
+            throw new Error(`gjsify flatpak build: manifest ${manifest} not found`);
+        }
+
+        const buildDir = resolve(cwd, args.buildDir ?? 'flatpak-build');
+        const sharedFlags: string[] = [];
+        if (args.forceClean !== false) sharedFlags.push('--force-clean');
+        if (args.sandbox !== false) sharedFlags.push('--sandbox');
+        if (args.deleteBuildDirs !== false) sharedFlags.push('--delete-build-dirs');
+        if (args.installDepsFrom) sharedFlags.push(`--install-deps-from=${args.installDepsFrom}`);
+
+        // Reset the build dir so re-runs don't pick up half-stale state.
+        if (existsSync(buildDir)) rmSync(buildDir, { recursive: true, force: true });
+
+        await runFlatpakBuilder([...sharedFlags, buildDir, manifest], { verbose: args.verbose });
+
+        if (args.install) {
+            await runFlatpakBuilder(
+                ['--user', '--install', '--force-clean', buildDir, manifest],
+                { verbose: args.verbose },
+            );
+        }
+
+        if (args.repo) {
+            const repoPath = resolve(cwd, args.repo);
+            mkdirSync(dirname(repoPath), { recursive: true });
+            await runFlatpakBuilder(
+                [`--repo=${repoPath}`, '--force-clean', buildDir, manifest],
+                { verbose: args.verbose },
+            );
+        }
+
+        if (args.bundle) {
+            if (!args.repo) {
+                throw new Error(
+                    'gjsify flatpak build: --bundle requires --repo (the bundle is built from the OSTree repo).',
+                );
+            }
+            const bundlePath = resolve(cwd, args.bundle);
+            mkdirSync(dirname(bundlePath), { recursive: true });
+            const repoPath = resolve(cwd, args.repo);
+            const appId = readManifestAppId(manifest);
+            await runFlatpak(
+                ['build-bundle', repoPath, bundlePath, appId],
+                { verbose: args.verbose },
+            );
+        }
+
+        if (args.tarball) {
+            const tarballPath = resolve(cwd, args.tarball);
+            mkdirSync(dirname(tarballPath), { recursive: true });
+            await runTar(['-czf', tarballPath, '-C', buildDir, '.'], { verbose: args.verbose });
+        }
+
+        console.log(`[gjsify flatpak build] done (${buildDir})`);
+    },
+};
+
+/** Pick the first JSON file in cwd that looks like a Flatpak manifest. */
+function findDefaultManifest(cwd: string): string {
+    return scanForManifest(cwd) ?? 'flatpak.json';
+}
+
+function scanForManifest(cwd: string): string | undefined {
+    let entries: string[] = [];
+    try {
+        entries = readdirSync(cwd);
+    } catch {
+        return undefined;
+    }
+    for (const name of entries) {
+        if (!name.endsWith('.json')) continue;
+        if (name === 'package.json' || name === 'tsconfig.json' || name.startsWith('.')) continue;
+        try {
+            const json = JSON.parse(readFileSync(resolve(cwd, name), 'utf-8')) as Record<string, unknown>;
+            if (typeof json.id === 'string' && typeof json.runtime === 'string' && Array.isArray(json.modules)) {
+                return name;
+            }
+        } catch {
+            // Not JSON or unreadable — skip.
+        }
+    }
+    return undefined;
+}
+
+function readManifestAppId(manifest: string): string {
+    const raw = readFileSync(manifest, 'utf-8');
+    const json = JSON.parse(raw) as { id?: unknown };
+    if (typeof json.id !== 'string') {
+        throw new Error(`gjsify flatpak build: ${manifest} has no string "id" field`);
+    }
+    return json.id;
+}
+
+async function runFlatpakBuilder(args: string[], opts: { verbose?: boolean }) {
+    return runProc('flatpak-builder', args, opts, {
+        notFoundHint:
+            'flatpak-builder not found. Install via your distro (Fedora: `sudo dnf install flatpak-builder`).',
+    });
+}
+
+async function runFlatpak(args: string[], opts: { verbose?: boolean }) {
+    return runProc('flatpak', args, opts, {
+        notFoundHint: 'flatpak not found. Install via your distro and add Flathub: see https://flathub.org/setup.',
+    });
+}
+
+async function runTar(args: string[], opts: { verbose?: boolean }) {
+    return runProc('tar', args, opts, { notFoundHint: 'tar not found.' });
+}
+
+function runProc(
+    cmd: string,
+    args: string[],
+    opts: { verbose?: boolean },
+    extra: { notFoundHint: string },
+): Promise<void> {
+    if (opts.verbose) {
+        console.log(`[gjsify flatpak] ${cmd} ${args.join(' ')}`);
+    }
+    return new Promise((res, rej) => {
+        const child = spawn(cmd, args, { stdio: 'inherit' });
+        child.on('error', (err: NodeJS.ErrnoException) => {
+            if (err.code === 'ENOENT') {
+                rej(new Error(`gjsify flatpak: ${extra.notFoundHint}`));
+            } else {
+                rej(err);
+            }
+        });
+        child.on('exit', (code) => {
+            if (code === 0) res();
+            else rej(new Error(`gjsify flatpak: ${cmd} exited with status ${code}`));
+        });
+    });
+}

package/src/commands/flatpak/ci.ts

@@ -0,0 +1,173 @@
+// `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

@@ -0,0 +1,120 @@
+// `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

@@ -0,0 +1,53 @@
+// `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,
+};