@gjsify/cli 0.4.12 → 0.4.14

package/lib/actions/build.d.ts

@@ -35,9 +35,19 @@ export declare class BuildAction {
      */
     private applyShebang;
     /** Application mode */
-    buildApp(app?: App): Promise<RolldownOutput[]>;
+    buildApp(app?: App, opts?: {
+        watch?: boolean;
+    }): Promise<RolldownOutput[]>;
+    /**
+     * Drive `rolldown.watch(...)`: rebuild on source change, apply the
+     * post-bundle shebang hook on each successful build, surface errors
+     * without exiting, clean up on SIGINT/SIGTERM. Resolves only when the
+     * watcher closes — keeps the CLI process alive across rebuilds.
+     */
+    private runWatchLoop;
     start(buildType?: {
         library?: boolean;
         app?: App;
+        watch?: boolean;
     }): Promise<RolldownOutput[]>;
 }

package/lib/actions/build.js

@@ -1,4 +1,4 @@
-import { runBundle, bundleToChunks } from "../bundler-pick.js";
+import { runBundle, runWatch, bundleToChunks } from "../bundler-pick.js";
 import { gjsifyPlugin, textLoaderPlugin, resolveShebangLine } from "@gjsify/rolldown-plugin-gjsify";
 import { resolveUserPlugins } from "../utils/resolve-plugin-by-name.js";
 import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals, } from "@gjsify/rolldown-plugin-gjsify/globals";
@@ -178,7 +178,7 @@ export class BuildAction {
             console.debug(`[gjsify] --shebang: wrote ${line} + chmod 0o755 to ${outfile}`);
     }
     /** Application mode */
-    async buildApp(app = "gjs") {
+    async buildApp(app = "gjs", opts = {}) {
         const { verbose, typescript, exclude, library: pkg, aliases, excludeGlobals, } = this.configData;
         const userBundler = normalizeBundlerOptions(this.configData);
         const formatRaw = userBundler.output?.format ??
@@ -281,17 +281,93 @@ export class BuildAction {
             // Rolldown doesn't understand) would crash the build.
             plugins: [...pnpPlugins, ...userPlugins, ...cfg.plugins],
         };
+        if (opts.watch) {
+            await this.runWatchLoop(finalOpts, app, outfile, verbose);
+            return [];
+        }
         const writeResult = await runBundle(finalOpts);
         if (app === "gjs" && this.configData.shebang) {
             await this.applyShebang(outfile, verbose);
         }
         return [writeResult];
     }
+    /**
+     * Drive `rolldown.watch(...)`: rebuild on source change, apply the
+     * post-bundle shebang hook on each successful build, surface errors
+     * without exiting, clean up on SIGINT/SIGTERM. Resolves only when the
+     * watcher closes — keeps the CLI process alive across rebuilds.
+     */
+    async runWatchLoop(finalOpts, app, outfile, verbose) {
+        const watcher = await runWatch(finalOpts);
+        const closed = new Promise((resolve) => {
+            watcher.on("close", () => resolve());
+        });
+        let closing = false;
+        const shutdown = async () => {
+            if (closing)
+                return;
+            closing = true;
+            console.log("\n[gjsify build --watch] stopping watcher…");
+            try {
+                await watcher.close();
+            }
+            catch (err) {
+                console.error("[gjsify build --watch] watcher close error:", err);
+            }
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+        watcher.on("event", async (event) => {
+            switch (event.code) {
+                case "START":
+                    if (verbose)
+                        console.log("[gjsify build --watch] rebuild start");
+                    break;
+                case "BUNDLE_START":
+                    console.log("[gjsify build --watch] building…");
+                    break;
+                case "BUNDLE_END":
+                    console.log(`[gjsify build --watch] built in ${event.duration}ms`);
+                    try {
+                        if (app === "gjs" && this.configData.shebang) {
+                            await this.applyShebang(outfile, verbose);
+                        }
+                    }
+                    finally {
+                        await event.result.close();
+                    }
+                    break;
+                case "END":
+                    console.log("[gjsify build --watch] waiting for changes…");
+                    break;
+                case "ERROR":
+                    console.error("[gjsify build --watch] build failed:", event.error?.message ?? event.error);
+                    if (verbose && event.error?.stack)
+                        console.error(event.error.stack);
+                    try {
+                        await event.result.close();
+                    }
+                    catch {
+                        // best-effort cleanup
+                    }
+                    break;
+            }
+        });
+        if (verbose) {
+            watcher.on("change", (id, change) => {
+                console.log(`[gjsify build --watch] ${change.event}: ${id}`);
+            });
+        }
+        await closed;
+    }
     async start(buildType = { app: "gjs" }) {
         if (buildType.library) {
+            if (buildType.watch) {
+                throw new Error("gjsify build: --watch is not supported with --library (library mode would emit watcher rebuilds for every produced format; use --app gjs|node|browser instead).");
+            }
             return await this.buildLibrary();
         }
-        return await this.buildApp(buildType.app);
+        return await this.buildApp(buildType.app, { watch: buildType.watch });
     }
 }
 async function runOneLibraryBuild(args) {

package/lib/bundler-pick.d.ts

@@ -65,6 +65,13 @@ export declare function bundleToChunks(input: {
     rolldownInput: import('rolldown').InputOptions;
     format: 'esm' | 'cjs' | 'iife';
 }): Promise<string[]>;
+/**
+ * Watch source files and rebuild on change. Only npm rolldown supports
+ * this path — `@gjsify/rolldown-native` does not surface a watcher API yet.
+ * Returns the watcher; the caller registers `event` / `close` listeners
+ * and is responsible for invoking `watcher.close()` on shutdown.
+ */
+export declare function runWatch(finalOpts: BundlerOptions): Promise<import('rolldown').RolldownWatcher>;
 /**
  * Run a bundle with the picked engine. Drop-in replacement for the
  * `rolldown(opts).write(opts.output)` flow used directly in build.ts.

package/lib/bundler-pick.js

@@ -86,6 +86,23 @@ export async function bundleToChunks(input) {
         await build.close();
     }
 }
+/**
+ * Watch source files and rebuild on change. Only npm rolldown supports
+ * this path — `@gjsify/rolldown-native` does not surface a watcher API yet.
+ * Returns the watcher; the caller registers `event` / `close` listeners
+ * and is responsible for invoking `watcher.close()` on shutdown.
+ */
+export async function runWatch(finalOpts) {
+    if (await shouldUseNative()) {
+        throw new Error('`gjsify build --watch` requires the npm `rolldown` engine. The native engine ' +
+            '(`@gjsify/rolldown-native`) does not expose a watcher API. Run the watch loop ' +
+            'under Node (`node lib/index.js build … --watch`) or set `GJSIFY_BUNDLER=npm`.');
+    }
+    const specifier = 'rolldown';
+    const mod = (await import(/* @vite-ignore */ specifier));
+    const output = finalOpts.output ?? {};
+    return mod.watch({ ...finalOpts, output });
+}
 /**
  * Run a bundle with the picked engine. Drop-in replacement for the
  * `rolldown(opts).write(opts.output)` flow used directly in build.ts.

package/lib/commands/build.js

@@ -130,6 +130,13 @@ export const buildCommand = {
             description: "Comma-separated global identifiers to remove from auto-detection results. Use for false positives from dead browser-compat code whose polyfills require unavailable native libraries (e.g. --exclude-globals fetch,XMLHttpRequest).",
             type: 'string',
             normalize: true,
+        })
+            .option('watch', {
+            alias: 'w',
+            description: "Watch source files and rebuild on change. Logs each rebuild with duration; clean SIGINT shutdown. Only valid with --app gjs|node|browser (rejected with --library). Requires the npm `rolldown` engine — run under Node, not the GJS-bundled CLI.",
+            type: 'boolean',
+            normalize: true,
+            default: false,
         });
     },
     handler: async (args) => {
@@ -139,6 +146,7 @@ export const buildCommand = {
         await action.start({
             library: args.library,
             app: args.app,
+            watch: args.watch,
         });
     }
 };

package/lib/commands/fix.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from '../types/index.js';
+interface FixOptions {
+    paths?: string[];
+    write?: boolean;
+    configPath?: string;
+    verbose?: boolean;
+}
+export declare const fixCommand: Command<unknown, FixOptions>;
+export {};

package/lib/commands/fix.js

@@ -0,0 +1,60 @@
+// `gjsify fix` — runs biome's combined `check --write` mode.
+//
+// Equivalent to biome's `check` (format + safe-lint-fix + organize-imports).
+// Default writes fixes in-place; pass `--no-write` to report-only.
+// Naming: deliberately distinct from `gjsify check` (which verifies
+// system dependencies).
+import { resolve } from 'node:path';
+import { BiomeNotFoundError, findBiomeConfig, printBiomeNotFound, runBiome, } from '../utils/biome-resolve.js';
+export const fixCommand = {
+    command: 'fix [paths..]',
+    description: 'Run Biome check --write — format + safe-lint-fix + organize-imports in one pass.',
+    builder: (yargs) => {
+        return yargs
+            .positional('paths', {
+            description: 'Files or directories to fix. Default: `.`',
+            type: 'string',
+            array: true,
+        })
+            .option('write', {
+            description: 'Apply fixes in place (default: true). Pass --no-write to report only.',
+            type: 'boolean',
+            default: true,
+        })
+            .option('config-path', {
+            description: 'Path to a biome.json. Default: walks up from cwd to find one.',
+            type: 'string',
+            normalize: true,
+        })
+            .option('verbose', {
+            description: 'Echo the resolved biome binary + args before spawning.',
+            type: 'boolean',
+            default: false,
+        });
+    },
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const paths = args.paths?.length
+            ? args.paths
+            : ['.'];
+        const biomeArgs = ['check'];
+        if (args.write !== false)
+            biomeArgs.push('--write');
+        const configPath = args.configPath ?? findBiomeConfig(cwd) ?? undefined;
+        if (configPath)
+            biomeArgs.push(`--config-path=${resolve(configPath, '..')}`);
+        biomeArgs.push(...paths);
+        try {
+            const code = await runBiome(biomeArgs, { cwd, verbose: args.verbose });
+            process.exitCode = code;
+        }
+        catch (err) {
+            if (err instanceof BiomeNotFoundError) {
+                printBiomeNotFound(err);
+                process.exitCode = 1;
+                return;
+            }
+            throw err;
+        }
+    },
+};

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

@@ -0,0 +1,12 @@
+import type { Command } from '../../types/index.js';
+interface DiffOptions {
+    version?: string;
+    appId?: string;
+    flathubRepo?: string;
+    against?: string;
+    detail?: boolean;
+    sourceIndex?: number;
+    verbose?: boolean;
+}
+export declare const flatpakDiffCommand: Command<unknown, DiffOptions>;
+export {};

package/lib/commands/flatpak/diff.js

@@ -0,0 +1,165 @@
+// `gjsify flatpak diff` — report drift between the local config + git
+// state and the per-app Flathub tracking-repo manifest.
+//
+// The most common failure mode is *version drift*: a release was cut
+// locally (a new `git tag`), but the Flathub-repo manifest still pins
+// the previous tag, so end-users on flatpak install never see the
+// release. This command surfaces that drift before
+// `gjsify flatpak sync-flathub` is needed (the symmetric command that
+// fixes it).
+//
+// Workflow:
+//   1. Resolve appId + flathub-repo (same precedence as sync-flathub)
+//   2. Fetch the Flathub manifest (or read `--against <local>`)
+//   3. Resolve the local latest git tag (`git describe --tags --abbrev=0`)
+//   4. Compare module[0].sources's `tag` + `commit` to the local state
+//   5. Exit 0 when in sync, 1 when there's drift, with a clear message
+import { existsSync, readFileSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { Config } from '../../config.js';
+import { readPackageJson } from './utils.js';
+const execFileAsync = promisify(execFile);
+export const flatpakDiffCommand = {
+    command: 'diff',
+    description: 'Compare the per-app Flathub tracking-repo manifest against the local git state and report version / commit drift.',
+    builder: (yargs) => {
+        return yargs
+            .version(false)
+            .option('version', {
+            description: 'Local version to compare against. Default: `git describe --tags --abbrev=0` in cwd.',
+            type: 'string',
+        })
+            .option('app-id', {
+            description: 'Reverse-DNS app id. Default: `gjsify.flatpak.appId`.',
+            type: 'string',
+        })
+            .option('flathub-repo', {
+            description: 'Flathub tracking-repo (owner/name). Default: `gjsify.flatpak.flathubRepo` or `flathub/<appId>`.',
+            type: 'string',
+        })
+            .option('against', {
+            description: 'Read the Flathub manifest from a local file instead of fetching it. Useful in CI or offline.',
+            type: 'string',
+        })
+            .option('detail', {
+            description: 'Also print the full Flathub manifest source entry alongside the resolved local version.',
+            type: 'boolean',
+            default: false,
+        })
+            .option('source-index', {
+            description: 'Index into modules[0].sources[] to inspect (when the manifest has multiple sources).',
+            type: 'number',
+        })
+            .option('verbose', {
+            description: 'Echo fetch URL + resolved values.',
+            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 appId = args.appId ??
+            flatpak.appId ??
+            readPackageJson(cwd).name;
+        if (!appId) {
+            throw new Error('[gjsify flatpak diff] no app id available — pass --app-id or set gjsify.flatpak.appId.');
+        }
+        const flathubRepo = args.flathubRepo ??
+            flatpak.flathubRepo ??
+            `flathub/${appId}`;
+        const localVersion = args.version ?? (await resolveLatestTag(cwd, args.verbose));
+        const remoteSource = await loadFlathubSource({ appId, flathubRepo, against: args.against, verbose: args.verbose }, args.sourceIndex);
+        const remoteTag = remoteSource?.tag;
+        const remoteCommit = remoteSource?.commit;
+        console.log(`[gjsify flatpak diff] appId=${appId}`);
+        console.log(`[gjsify flatpak diff] flathubRepo=${flathubRepo}`);
+        console.log(`[gjsify flatpak diff] flathub: tag=${remoteTag ?? '(missing)'} commit=${remoteCommit ?? '(missing)'}`);
+        console.log(`[gjsify flatpak diff] local:   tag=${localVersion ?? '(none)'}`);
+        if (args.detail && remoteSource) {
+            console.log('[gjsify flatpak diff] flathub manifest source:');
+            console.log(JSON.stringify(remoteSource, null, 2));
+        }
+        if (!localVersion) {
+            console.warn('[gjsify flatpak diff] no local git tag found — cut a release (`git tag vX.Y.Z`) ' +
+                'or pass --version vX.Y.Z to compare against an explicit value.');
+            // Still surface remote state, but exit cleanly so this isn't a fatal CI step.
+            return;
+        }
+        if (!remoteTag) {
+            console.warn('[gjsify flatpak diff] flathub manifest has no `tag` field on the inspected source.');
+            process.exit(1);
+        }
+        if (remoteTag === localVersion) {
+            console.log(`✅ in sync (${localVersion})`);
+            return;
+        }
+        console.log(`❌ drift detected — flathub=${remoteTag} vs local=${localVersion}`);
+        console.log(`   run \`gjsify flatpak sync-flathub --version ${localVersion}\` to update the Flathub manifest.`);
+        process.exit(1);
+    },
+};
+// ─── Internal helpers ────────────────────────────────────────────────────
+async function loadFlathubSource(args, sourceIndex) {
+    let raw;
+    if (args.against) {
+        if (!existsSync(args.against)) {
+            throw new Error(`[gjsify flatpak diff] --against path ${args.against} does not exist`);
+        }
+        raw = readFileSync(args.against, 'utf-8');
+    }
+    else {
+        // Try main + master raw URLs on GitHub. Flathub repos historically use
+        // master; newer ones may use main. No XDG cache: fresh fetch each run.
+        raw = await fetchFlathubManifest(args.flathubRepo, args.appId, args.verbose);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`[gjsify flatpak diff] failed to parse Flathub manifest as JSON: ${err.message}`);
+    }
+    const modules = manifest.modules ?? [];
+    const sources = modules[0]?.sources ?? [];
+    if (sources.length === 0)
+        return null;
+    const idx = sourceIndex ?? sources.findIndex((s) => s?.type === 'git');
+    if (idx < 0 || idx >= sources.length)
+        return null;
+    return sources[idx] ?? null;
+}
+async function fetchFlathubManifest(flathubRepo, appId, verbose) {
+    for (const branch of ['master', 'main']) {
+        const url = `https://raw.githubusercontent.com/${flathubRepo}/${branch}/${appId}.json`;
+        if (verbose)
+            console.log(`[gjsify flatpak diff] fetch ${url}`);
+        try {
+            const res = await fetch(url);
+            if (res.ok)
+                return await res.text();
+            if (verbose)
+                console.log(`[gjsify flatpak diff] ${branch} → HTTP ${res.status}`);
+        }
+        catch (err) {
+            if (verbose)
+                console.log(`[gjsify flatpak diff] ${branch} fetch error: ${err.message}`);
+        }
+    }
+    throw new Error(`[gjsify flatpak diff] could not fetch flathub manifest from ${flathubRepo} on master or main`);
+}
+async function resolveLatestTag(cwd, verbose) {
+    try {
+        const { stdout } = await execFileAsync('git', ['describe', '--tags', '--abbrev=0'], { cwd });
+        const tag = stdout.trim();
+        if (verbose)
+            console.log(`[gjsify flatpak diff] local latest tag → ${tag}`);
+        return tag || null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -4,5 +4,8 @@ import { flatpakBuildCommand } from './build.js';
 import { flatpakDepsCommand } from './deps.js';
 import { flatpakCiCommand } from './ci.js';
 import { flatpakCheckCommand } from './check.js';
+import { flatpakSyncFlathubCommand } from './sync-flathub.js';
+import { flatpakDiffCommand } from './diff.js';
+import { flatpakReleaseCommand } from './release.js';
 export declare const flatpakCommand: Command;
-export { flatpakInitCommand, flatpakBuildCommand, flatpakDepsCommand, flatpakCiCommand, flatpakCheckCommand, };
+export { flatpakInitCommand, flatpakBuildCommand, flatpakDepsCommand, flatpakCiCommand, flatpakCheckCommand, flatpakSyncFlathubCommand, flatpakDiffCommand, flatpakReleaseCommand, };

package/lib/commands/flatpak/index.js

@@ -1,16 +1,19 @@
 // `gjsify flatpak` — yargs subcommand-group dispatcher.
 //
-// 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.
+// Wires {init, build, deps, ci, check, sync-flathub, diff, release}.
+// 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';
+import { flatpakSyncFlathubCommand } from './sync-flathub.js';
+import { flatpakDiffCommand } from './diff.js';
+import { flatpakReleaseCommand } from './release.js';
 export const flatpakCommand = {
     command: 'flatpak <subcommand>',
-    description: 'Flatpak toolchain: init/build/deps/ci/check subcommands for shipping GJS apps and CLIs as Flatpaks.',
+    description: 'Flatpak toolchain: init/build/deps/ci/check/sync-flathub/diff/release subcommands for shipping GJS apps and CLIs as Flatpaks.',
     builder: (yargs) => {
         return yargs
             .command(flatpakInitCommand.command, flatpakInitCommand.description, flatpakInitCommand.builder, flatpakInitCommand.handler)
@@ -18,8 +21,11 @@ export const flatpakCommand = {
             .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)
+            .command(flatpakSyncFlathubCommand.command, flatpakSyncFlathubCommand.description, flatpakSyncFlathubCommand.builder, flatpakSyncFlathubCommand.handler)
+            .command(flatpakDiffCommand.command, flatpakDiffCommand.description, flatpakDiffCommand.builder, flatpakDiffCommand.handler)
+            .command(flatpakReleaseCommand.command, flatpakReleaseCommand.description, flatpakReleaseCommand.builder, flatpakReleaseCommand.handler)
             .demandCommand(1)
             .strict();
     },
 };
-export { flatpakInitCommand, flatpakBuildCommand, flatpakDepsCommand, flatpakCiCommand, flatpakCheckCommand, };
+export { flatpakInitCommand, flatpakBuildCommand, flatpakDepsCommand, flatpakCiCommand, flatpakCheckCommand, flatpakSyncFlathubCommand, flatpakDiffCommand, flatpakReleaseCommand, };

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

@@ -14,6 +14,7 @@ interface FlatpakInitOptions {
     sdkExtension?: string[];
     finishArg?: string[];
     verbose?: boolean;
+    format?: boolean;
 }
 export declare const flatpakInitCommand: Command<unknown, FlatpakInitOptions>;
 export {};

package/lib/commands/flatpak/init.js

@@ -16,6 +16,7 @@ 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';
+import { BiomeNotFoundError, hasBiomeDevDep, runBiome, } from '../../utils/biome-resolve.js';
 export const flatpakInitCommand = {
     command: 'init',
     description: 'Generate Flatpak manifest + MetaInfo XML + .desktop + flathub.json from `gjsify.flatpak` config.',
@@ -85,6 +86,12 @@ export const flatpakInitCommand = {
             description: 'Print the resolved manifest fields before writing',
             type: 'boolean',
             default: false,
+        })
+            .option('format', {
+            description: 'Run `gjsify format --write` on the generated files when `@biomejs/biome` is detected in the project. ' +
+                'Default: true. Pass --no-format to skip.',
+            type: 'boolean',
+            default: true,
         });
     },
     handler: async (args) => {
@@ -140,13 +147,18 @@ export const flatpakInitCommand = {
             sources: [{ type: 'dir', path: '.' }],
         });
         manifest.modules = modules;
+        const writtenFiles = [];
+        const trackWrite = (p) => {
+            if (p)
+                writtenFiles.push(p);
+        };
         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;
+        trackWrite(writeIfFresh(manifestPath, JSON.stringify(manifest, null, 2) + '\n', args.force ?? false, 'manifest'));
+        const pkgName = pkg.name ?? appId;
         const scaffold = {
             appId,
-            name: friendlyName(name, appId),
+            name: flatpak.name ?? friendlyName(pkgName, appId),
             command,
             kind,
             flatpak,
@@ -161,17 +173,38 @@ export const flatpakInitCommand = {
         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');
+            trackWrite(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');
+                trackWrite(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');
+            trackWrite(writeIfFresh(resolve(cwd, flathubOut), renderFlathubJson(kind), args.force ?? false, 'flathub.json'));
+        }
+        // Optional post-format: when biome is configured in the project,
+        // run `biome format --write` on the generated files so they match
+        // the project's prettier/biome style. Default behaviour (2-space
+        // JSON) already matches biome/prettier/Flathub defaults; this
+        // step harmonises edge-case fields (line endings, trailing commas
+        // in JSONC, key sort order if biome's organize-imports has rules).
+        if (writtenFiles.length > 0 && args.format !== false && hasBiomeDevDep(cwd)) {
+            try {
+                await runBiome(['format', '--write', ...writtenFiles], { cwd });
+            }
+            catch (err) {
+                if (err instanceof BiomeNotFoundError) {
+                    // Biome configured but binary missing — non-fatal warning.
+                    console.warn(`[gjsify flatpak init] post-format skipped: @biomejs/biome declared but binary not installed. ` +
+                        `Run \`gjsify install\` then re-run with --force, or pass --no-format.`);
+                }
+                else {
+                    throw err;
+                }
+            }
         }
         if (args.verbose) {
             console.log(`[gjsify flatpak init] kind=${kind} runtime=${runtimeId} ${runtimeVersion} sdk=${sdk}`);
@@ -183,11 +216,12 @@ export const flatpakInitCommand = {
 function writeIfFresh(path, content, force, label) {
     if (existsSync(path) && !force) {
         console.log(`[gjsify flatpak init] skipped ${label}: ${path} (exists; --force to overwrite)`);
-        return;
+        return null;
     }
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, content, 'utf-8');
     console.log(`[gjsify flatpak init] wrote ${label}: ${path}`);
+    return path;
 }
 function friendlyName(pkgName, appId) {
     if (pkgName.startsWith('@')) {

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

@@ -0,0 +1,13 @@
+import type { Command } from '../../types/index.js';
+interface ReleaseOptions {
+    version: string;
+    skipTag?: boolean;
+    skipCheck?: boolean;
+    skipInit?: boolean;
+    pushTag?: boolean;
+    dryRun?: boolean;
+    flathubRepo?: string;
+    verbose?: boolean;
+}
+export declare const flatpakReleaseCommand: Command<unknown, ReleaseOptions>;
+export {};