@gjsify/cli 0.3.13 → 0.3.15

package/lib/commands/flatpak/build.js

@@ -0,0 +1,187 @@
+// `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';
+export const flatpakBuildCommand = {
+    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 ?? 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 = [];
+        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) {
+    return scanForManifest(cwd) ?? 'flatpak.json';
+}
+function scanForManifest(cwd) {
+    let entries = [];
+    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'));
+            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) {
+    const raw = readFileSync(manifest, 'utf-8');
+    const json = JSON.parse(raw);
+    if (typeof json.id !== 'string') {
+        throw new Error(`gjsify flatpak build: ${manifest} has no string "id" field`);
+    }
+    return json.id;
+}
+async function runFlatpakBuilder(args, opts) {
+    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, opts) {
+    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, opts) {
+    return runProc('tar', args, opts, { notFoundHint: 'tar not found.' });
+}
+function runProc(cmd, args, opts, extra) {
+    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) => {
+            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/lib/commands/flatpak/ci.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from '../../types/index.js';
+interface FlatpakCiOptions {
+    manifest?: string;
+    bundle?: string;
+    runtimeImage?: string;
+    branches?: string[];
+    out?: string;
+    force?: boolean;
+    cacheKey?: string;
+    verbose?: boolean;
+}
+export declare const flatpakCiCommand: Command<unknown, FlatpakCiOptions>;
+export {};

package/lib/commands/flatpak/ci.js

@@ -0,0 +1,133 @@
+// `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 { Config } from '../../config.js';
+import { defaultCiContainer, looksLikeAppId, readPackageJson, resolveRuntime } from './utils.js';
+export const flatpakCiCommand = {
+    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({}).catch(() => ({}));
+        const flatpak = configData.flatpak ?? {};
+        const pkg = readPackageJson(cwd);
+        const appId = flatpak.appId ??
+            (looksLikeAppId(pkg.name) ? pkg.name : 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 ?? `${appId}.json`;
+        const bundle = args.bundle ?? `${appId}.flatpak`;
+        const { runtime, runtimeVersion } = resolveRuntime(flatpak, {});
+        const runtimeImage = args.runtimeImage ??
+            flatpak.ciContainer ??
+            defaultCiContainer(runtime, runtimeVersion);
+        const branches = args.branches ?? 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}`);
+    },
+};
+/**
+ * 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) {
+    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/lib/commands/flatpak/deps.d.ts

@@ -0,0 +1,12 @@
+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 declare const flatpakDepsCommand: Command<unknown, FlatpakDepsOptions>;
+export {};

package/lib/commands/flatpak/deps.js

@@ -0,0 +1,96 @@
+// `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';
+export const flatpakDepsCommand = {
+    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'],
+        })
+            .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 ?? detectLockfile(cwd));
+        if (!existsSync(lockfile)) {
+            throw new Error(`gjsify flatpak deps: lockfile ${lockfile} not found (use --lockfile to override)`);
+        }
+        const type = args.type ??
+            (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((res, rej) => {
+            const child = spawn('flatpak-node-generator', cmdArgs, { stdio: 'inherit' });
+            child.on('error', (err) => {
+                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) {
+    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/lib/commands/flatpak/index.d.ts

@@ -0,0 +1,7 @@
+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 declare const flatpakCommand: Command;
+export { flatpakInitCommand, flatpakBuildCommand, flatpakDepsCommand, flatpakCiCommand, };

package/lib/commands/flatpak/index.js

@@ -0,0 +1,23 @@
+// `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 { flatpakInitCommand } from './init.js';
+import { flatpakBuildCommand } from './build.js';
+import { flatpakDepsCommand } from './deps.js';
+import { flatpakCiCommand } from './ci.js';
+export const flatpakCommand = {
+    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, 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)
+            .demandCommand(1)
+            .strict();
+    },
+};
+export { flatpakInitCommand, flatpakBuildCommand, flatpakDepsCommand, flatpakCiCommand, };

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

@@ -0,0 +1,15 @@
+import type { Command } from '../../types/index.js';
+interface FlatpakInitOptions {
+    appId?: string;
+    runtime?: string;
+    runtimeVersion?: string;
+    cliOnly?: boolean;
+    manifest?: string;
+    command?: string;
+    force?: boolean;
+    sdkExtension?: string[];
+    finishArg?: string[];
+    verbose?: boolean;
+}
+export declare const flatpakInitCommand: Command<unknown, FlatpakInitOptions>;
+export {};

package/lib/commands/flatpak/init.js

@@ -0,0 +1,154 @@
+// `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 { DEFAULT_CLI_FINISH_ARGS, DEFAULT_GUI_FINISH_ARGS, looksLikeAppId, readPackageJson, resolveRuntime, } from './utils.js';
+import { Config } from '../../config.js';
+export const flatpakInitCommand = {
+    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'],
+        })
+            .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({}).catch(() => ({}));
+        const flatpak = configData.flatpak ?? {};
+        const cwd = process.cwd();
+        const pkg = readPackageJson(cwd);
+        const appId = args.appId ??
+            flatpak.appId ??
+            (looksLikeAppId(pkg.name) ? pkg.name : 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 ?? 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);
+        const manifest = {
+            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 = [];
+        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 ?? `${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, 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) {
+        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) {
+    const parts = appId.split('.');
+    return parts[parts.length - 1] || appId;
+}