@gjsify/cli 0.4.13 → 0.4.15

package/lib/actions/barrels-generate.d.ts

@@ -0,0 +1,31 @@
+export type BarrelExtension = 'js' | 'ts' | 'none';
+export interface BarrelsArgs {
+    /** Directories to scan. Each gets an `index.ts` re-exporting its sibling source files. */
+    paths: string[];
+    /** Import-specifier extension. `js`/`ts`/`none`. */
+    extension: BarrelExtension;
+    /** Resolve `paths` against this directory. Default: `process.cwd()`. */
+    baseDir: string;
+    /** Skip files whose names match any regex. */
+    exclude: RegExp[];
+    /** Header comment prepended to every generated file. */
+    header: string;
+    /** Omit trailing `;` on each export line. */
+    noSemicolon: boolean;
+    /** Use `'` quotes (default). When false, uses `"`. */
+    singleQuotes: boolean;
+    /** Report drift without writing. Returns drift count from generator. */
+    check: boolean;
+    /** Log each file scanned + written. */
+    verbose: boolean;
+}
+export declare const DEFAULT_BARRELS_HEADER = "// Auto-generated by `gjsify barrels` \u2014 do not edit by hand.";
+export declare const DEFAULT_BARRELS_EXCLUDES: readonly string[];
+/**
+ * Regenerate `index.ts` in every directory in `args.paths`.
+ *
+ * Returns the number of files that drifted from the canonical output —
+ * always 0 when `check` is false (drift is rewritten in-place); non-zero
+ * under `check: true` signals CI failure.
+ */
+export declare function generateBarrels(args: BarrelsArgs): Promise<number>;

package/lib/actions/barrels-generate.js

@@ -0,0 +1,78 @@
+// `gjsify barrels` action — regenerate `index.ts` barrel files for one or
+// more directories. Pure async generator, decoupled from yargs so it can
+// be unit-tested in isolation.
+//
+// Adapted from beabee-communityrm/monorepo apps/dev-cli's `generate-index`
+// action (refs/dev-cli — not vendored here): same separation of action vs.
+// command module, same `types/`-dir auto-detection that emits
+// `export type *`, same `export {};` fallback for empty directories,
+// same sorted-output principle. Rewritten for gjsify's yargs CommandModule
+// and `@gjsify/unit` test framework; no external deps. Replaces
+// `barrelsby` (unmaintained since 2022) at consumer sites.
+//
+// Original: Copyright (c) Beabee Community Repo contributors. AGPL-3.0.
+// Reimplemented for gjsify under the project's MIT license.
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, extname, join, resolve } from 'node:path';
+export const DEFAULT_BARRELS_HEADER = '// Auto-generated by `gjsify barrels` — do not edit by hand.';
+export const DEFAULT_BARRELS_EXCLUDES = [
+    '\\.test\\.',
+    '\\.spec\\.',
+    '\\.test-data\\.',
+];
+const SOURCE_FILE_RE = /\.(ts|tsx|mts|cts)$/;
+/**
+ * Regenerate `index.ts` in every directory in `args.paths`.
+ *
+ * Returns the number of files that drifted from the canonical output —
+ * always 0 when `check` is false (drift is rewritten in-place); non-zero
+ * under `check: true` signals CI failure.
+ */
+export async function generateBarrels(args) {
+    const quote = args.singleQuotes ? "'" : '"';
+    const semicolon = args.noSemicolon ? '' : ';';
+    const extSuffix = args.extension === 'none' ? '' : `.${args.extension}`;
+    let drift = 0;
+    for (const p of args.paths) {
+        const dir = resolve(args.baseDir, p);
+        const isTypesDir = basename(dir) === 'types';
+        let entries;
+        try {
+            entries = (await readdir(dir, { withFileTypes: true }))
+                .filter((e) => e.isFile())
+                .filter((e) => SOURCE_FILE_RE.test(e.name))
+                .filter((e) => e.name !== 'index.ts')
+                .filter((e) => !args.exclude.some((r) => r.test(e.name)))
+                .sort((a, b) => a.name.localeCompare(b.name));
+        }
+        catch (err) {
+            if (args.verbose)
+                console.error(`[gjsify barrels] skip ${dir}: ${err.message}`);
+            continue;
+        }
+        const lines = entries.map((e) => {
+            const stem = basename(e.name, extname(e.name));
+            const keyword = isTypesDir ? 'export type *' : 'export *';
+            return `${keyword} from ${quote}./${stem}${extSuffix}${quote}${semicolon}`;
+        });
+        const body = lines.length ? `${lines.join('\n')}\n` : 'export {};\n';
+        const out = `${args.header}\n\n${body}`;
+        const indexPath = join(dir, 'index.ts');
+        const previous = await readFile(indexPath, 'utf-8').catch(() => '');
+        if (previous === out) {
+            if (args.verbose)
+                console.log(`[gjsify barrels] up-to-date: ${indexPath}`);
+            continue;
+        }
+        if (args.check) {
+            console.error(`[gjsify barrels] drift: ${indexPath}`);
+            drift++;
+        }
+        else {
+            await writeFile(indexPath, out, 'utf-8');
+            if (args.verbose)
+                console.log(`[gjsify barrels] wrote: ${indexPath}`);
+        }
+    }
+    return drift;
+}

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/barrels.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from '../types/index.js';
+import { type BarrelExtension } from '../actions/barrels-generate.js';
+interface BarrelsOptions {
+    paths?: string[];
+    ext?: BarrelExtension;
+    baseDir?: string;
+    exclude?: string[];
+    header?: string;
+    semicolon?: boolean;
+    singleQuotes?: boolean;
+    check?: boolean;
+    verbose?: boolean;
+}
+export declare const barrelsCommand: Command<unknown, BarrelsOptions>;
+export {};

package/lib/commands/barrels.js

@@ -0,0 +1,103 @@
+// `gjsify barrels` — regenerate `index.ts` barrel files for a set of
+// directories. Drop-in replacement for `barrelsby` (unmaintained 2022+).
+//
+// Examples:
+//   gjsify barrels src/systems src/components       # regenerate two barrels
+//   gjsify barrels --check src/types                # CI guard — exit 1 on drift
+//   gjsify barrels --ext js src/utils               # NodeNext-style import-extensions
+//
+// Conventions:
+//   - A directory literally named `types/` emits `export type *` (type-only
+//     re-export) — avoids dragging value imports through type-only barrels.
+//   - An empty directory yields `export {};` so TypeScript still parses the
+//     file as a module.
+//   - Output is sorted by file name (locale-compare) — deterministic diffs.
+//   - `--check` exits non-zero on drift without writing (pre-commit / CI use).
+import { DEFAULT_BARRELS_EXCLUDES, DEFAULT_BARRELS_HEADER, generateBarrels, } from '../actions/barrels-generate.js';
+export const barrelsCommand = {
+    command: 'barrels [paths..]',
+    description: 'Regenerate `index.ts` barrel files for the given directories. Drop-in replacement for `barrelsby`.',
+    builder: (yargs) => {
+        return yargs
+            .positional('paths', {
+            description: 'Directories whose `index.ts` to (re)generate. May also be passed via `--paths`.',
+            type: 'string',
+            array: true,
+        })
+            .option('paths', {
+            alias: 'p',
+            description: 'Alternative to positional — repeatable list of directories.',
+            type: 'string',
+            array: true,
+        })
+            .option('ext', {
+            description: 'Import-specifier extension. Default: `none` (bundler-mode resolution).',
+            type: 'string',
+            choices: ['js', 'ts', 'none'],
+            default: 'none',
+        })
+            .option('base-dir', {
+            alias: 'b',
+            description: 'Resolve `paths` against this directory. Default: cwd.',
+            type: 'string',
+        })
+            .option('exclude', {
+            description: 'Regex(es) of file names to skip. Repeatable. Defaults: `\\.test\\.`, `\\.spec\\.`, `\\.test-data\\.`.',
+            type: 'string',
+            array: true,
+        })
+            .option('header', {
+            description: 'Header comment prepended to every generated file.',
+            type: 'string',
+        })
+            .option('semicolon', {
+            description: 'Emit trailing `;` on each export line. Negate with `--no-semicolon`. Default: omitted.',
+            type: 'boolean',
+            default: false,
+        })
+            .option('single-quotes', {
+            description: 'Use `\'` for import specifiers. Default: true. Pass `--no-single-quotes` for `"`.',
+            type: 'boolean',
+            default: true,
+        })
+            .option('check', {
+            description: 'Report drift without modifying files; exit non-zero if any barrel is stale.',
+            type: 'boolean',
+            default: false,
+        })
+            .option('verbose', {
+            description: 'Log each file scanned + written.',
+            type: 'boolean',
+            default: false,
+        });
+    },
+    handler: async (args) => {
+        // Both positional (`gjsify barrels src/a src/b`) and the named option
+        // (`--paths src/a --paths src/b`) land in `args.paths` since they share
+        // the same name. Yargs concatenates when both are present.
+        const paths = Array.from(new Set((args.paths ?? []).filter(Boolean)));
+        if (paths.length === 0) {
+            console.error('[gjsify barrels] no paths provided. Pass directories as positional arguments or via --paths.');
+            process.exitCode = 1;
+            return;
+        }
+        const excludePatterns = args.exclude?.length
+            ? args.exclude
+            : [...DEFAULT_BARRELS_EXCLUDES];
+        const drift = await generateBarrels({
+            paths,
+            extension: args.ext ?? 'none',
+            baseDir: args.baseDir ?? process.cwd(),
+            exclude: excludePatterns.map((src) => new RegExp(src)),
+            header: args.header ?? DEFAULT_BARRELS_HEADER,
+            noSemicolon: args.semicolon === false || args.semicolon === undefined,
+            singleQuotes: args.singleQuotes !== false,
+            check: args.check ?? false,
+            verbose: args.verbose ?? false,
+        });
+        if (args.check && drift > 0) {
+            console.error(`[gjsify barrels] ${drift} barrel file(s) drifted. Run without --check to fix.`);
+            process.exitCode = 1;
+        }
+    },
+};

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;
+    }
+}