@gjsify/cli 0.4.13 → 0.4.15

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,9 +147,14 @@ 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');
+        trackWrite(writeIfFresh(manifestPath, JSON.stringify(manifest, null, 2) + '\n', args.force ?? false, 'manifest'));
         const pkgName = pkg.name ?? appId;
         const scaffold = {
             appId,
@@ -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 {};

package/lib/commands/flatpak/release.js

@@ -0,0 +1,152 @@
+// `gjsify flatpak release` — orchestrate the full release-to-Flathub flow.
+//
+// One command chains the same steps a maintainer otherwise runs by hand
+// after cutting a release:
+//   1. Regenerate Flathub assets from `gjsify.flatpak` config (delegates to
+//      `gjsify flatpak init --force`)
+//   2. Run Flathub linters (delegates to `gjsify flatpak check`)
+//   3. Create + push the git tag (unless `--skip-tag`)
+//   4. Sync the per-app Flathub tracking-repo (delegates to
+//      `gjsify flatpak sync-flathub`)
+//
+// Each step shells out to the same CLI binary so the user sees identical
+// behaviour to running the sub-commands directly. The orchestrator
+// stops at the first failure and reports which step blocked, with a
+// clear command the user can re-run by hand.
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { resolve, dirname } from 'node:path';
+const execFileAsync = promisify(execFile);
+export const flatpakReleaseCommand = {
+    command: 'release <version>',
+    description: 'Cut a release end-to-end: regenerate Flathub assets, run linters, create + push the git tag, then open the Flathub PR. Each step delegates to the equivalent `gjsify flatpak <sub>` command.',
+    builder: (yargs) => {
+        return yargs
+            // yargs' built-in `--version` flag would otherwise consume the
+            // positional value.
+            .version(false)
+            .positional('version', {
+            description: 'Release tag, e.g. `v0.6.6`.',
+            type: 'string',
+            demandOption: true,
+        })
+            .option('skip-init', {
+            description: 'Skip the `flatpak init --force` regen step.',
+            type: 'boolean',
+            default: false,
+        })
+            .option('skip-check', {
+            description: 'Skip the `flatpak check` linter step.',
+            type: 'boolean',
+            default: false,
+        })
+            .option('skip-tag', {
+            description: 'Skip the `git tag` + `git push --tags` step (use when the tag was already created out-of-band).',
+            type: 'boolean',
+            default: false,
+        })
+            .option('push-tag', {
+            description: 'Push the created tag after creating it. Default: true.',
+            type: 'boolean',
+            default: true,
+        })
+            .option('flathub-repo', {
+            description: 'Flathub tracking-repo override forwarded to sync-flathub.',
+            type: 'string',
+        })
+            .option('dry-run', {
+            description: 'Print each step that would run without executing any of them.',
+            type: 'boolean',
+            default: false,
+        })
+            .option('verbose', {
+            description: 'Echo every sub-command invocation.',
+            type: 'boolean',
+            default: false,
+        });
+    },
+    handler: async (args) => {
+        const version = typeof args.version === 'string' ? args.version.trim() : '';
+        if (!version) {
+            throw new Error('[gjsify flatpak release] missing <version> positional');
+        }
+        const cliEntry = resolveCliEntry();
+        const cwd = process.cwd();
+        const steps = [];
+        if (!args.skipInit) {
+            steps.push({ name: 'init', args: [cliEntry, 'flatpak', 'init', '--force'] });
+        }
+        if (!args.skipCheck) {
+            steps.push({ name: 'check', args: [cliEntry, 'flatpak', 'check'] });
+        }
+        const syncArgs = [cliEntry, 'flatpak', 'sync-flathub', '--version', version];
+        if (args.flathubRepo)
+            syncArgs.push('--flathub-repo', args.flathubRepo);
+        if (args.verbose)
+            syncArgs.push('--verbose');
+        console.log(`[gjsify flatpak release] starting release of ${version}`);
+        if (args.dryRun) {
+            console.log('[gjsify flatpak release] --dry-run set; printing plan only:');
+            for (const s of steps)
+                console.log(`  · ${s.name}: node ${s.args.join(' ')}`);
+            if (!args.skipTag)
+                console.log(`  · tag: git tag ${version}${args.pushTag !== false ? ' && git push origin ' + version : ''}`);
+            console.log(`  · sync: node ${syncArgs.join(' ')}`);
+            return;
+        }
+        // Run init + check in sequence (must succeed before any git mutation).
+        for (const step of steps) {
+            if (args.verbose)
+                console.log(`[gjsify flatpak release] step ${step.name}: node ${step.args.join(' ')}`);
+            await runNode(step.args, cwd);
+            console.log(`[gjsify flatpak release] ${step.name} ✔`);
+        }
+        // Tag creation — only after init + check succeed so we don't end up
+        // with a tag pointing at a broken release.
+        if (!args.skipTag) {
+            if (args.verbose)
+                console.log(`[gjsify flatpak release] git tag ${version}`);
+            try {
+                await execFileAsync('git', ['tag', version], { cwd });
+                console.log(`[gjsify flatpak release] tag ${version} created`);
+            }
+            catch (err) {
+                throw new Error(`[gjsify flatpak release] git tag failed (${err.message}). ` +
+                    `If the tag already exists, re-run with --skip-tag.`);
+            }
+            if (args.pushTag !== false) {
+                if (args.verbose)
+                    console.log(`[gjsify flatpak release] git push origin ${version}`);
+                await execFileAsync('git', ['push', 'origin', version], { cwd });
+                console.log(`[gjsify flatpak release] tag pushed`);
+            }
+        }
+        // Sync flathub last.
+        if (args.verbose)
+            console.log(`[gjsify flatpak release] sync: node ${syncArgs.join(' ')}`);
+        await runNode(syncArgs, cwd);
+        console.log(`[gjsify flatpak release] ✅ release ${version} complete`);
+    },
+};
+/** Resolve a path to the gjsify CLI entry to invoke sub-commands. */
+function resolveCliEntry() {
+    // `commands/flatpak/release.ts` → compiled into
+    // `lib/commands/flatpak/release.js`. The CLI entry is `lib/index.js`.
+    const here = fileURLToPath(import.meta.url);
+    const cliRoot = resolve(dirname(here), '..', '..');
+    return resolve(cliRoot, 'index.js');
+}
+/** Spawn `node <args>` and reject on non-zero exit. */
+async function runNode(args, cwd) {
+    await new Promise((resolvePromise, reject) => {
+        const child = spawn('node', args, { cwd, stdio: 'inherit' });
+        child.on('error', reject);
+        child.on('exit', (code) => {
+            if (code === 0)
+                resolvePromise();
+            else
+                reject(new Error(`sub-command exited with code ${code}: node ${args.join(' ')}`));
+        });
+    });
+}

package/lib/commands/flatpak/sync-flathub.d.ts

@@ -0,0 +1,26 @@
+import type { Command } from '../../types/index.js';
+interface SyncFlathubOptions {
+    version?: string;
+    appId?: string;
+    flathubRepo?: string;
+    commit?: string;
+    branch?: string;
+    sourceIndex?: number;
+    pr?: boolean;
+    dryRun?: boolean;
+    verbose?: boolean;
+}
+export declare const flatpakSyncFlathubCommand: Command<unknown, SyncFlathubOptions>;
+/**
+ * Surgically edit a Flathub manifest to update the git source's `tag` +
+ * `commit` (and inject `x-checker-data` if missing). Preserves the
+ * original indent + whitespace + key ordering of the surrounding JSON
+ * by parsing through JSON.parse + re-stringifying with the detected
+ * indent.
+ */
+export declare function editManifest(original: string, args: {
+    tag: string;
+    commit: string;
+    sourceIndex?: number;
+}): string;
+export {};

package/lib/commands/flatpak/sync-flathub.js

@@ -0,0 +1,311 @@
+// `gjsify flatpak sync-flathub` — sync the per-app Flathub tracking-repo.
+//
+// Flathub distributes each app via a separate `flathub/<app-id>` repo
+// whose manifest pins a specific git tag + commit-SHA of the upstream
+// source. After cutting a new release in the source repo, the Flathub
+// repo's manifest needs to be updated to reference the new tag/commit.
+// This command automates that workflow:
+//
+//   1. Resolve appId + flathub-repo (from gjsify.flatpak config / flags)
+//   2. Resolve --version (explicit flag or `git describe --tags --abbrev=0`)
+//   3. Resolve commit SHA via `git rev-list -n 1 <version>`
+//   4. Clone (or update) the flathub tracking-repo into $XDG_CACHE_HOME
+//   5. Surgically edit the manifest: modules[].sources[].{tag,commit}
+//      plus x-checker-data block (inject if missing)
+//   6. Create a branch, commit the changes
+//   7. (unless --no-pr) push + open a PR via `gh pr create`
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { execFile, spawn } 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 flatpakSyncFlathubCommand = {
+    command: 'sync-flathub',
+    description: 'Update the per-app Flathub tracking-repo manifest to a new git tag + commit. Clones, edits, commits, optionally opens a PR.',
+    builder: (yargs) => {
+        return yargs
+            // Disable yargs' built-in `--version` (which would otherwise
+            // print the package version) so this command's `--version
+            // <tag>` flag works.
+            .version(false)
+            .option('version', {
+            description: 'Git tag to sync to. 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: `flathub/<appId>`.',
+            type: 'string',
+        })
+            .option('commit', {
+            description: 'Commit SHA to pin. Default: resolved via `git rev-list -n 1 <version>` in cwd.',
+            type: 'string',
+        })
+            .option('branch', {
+            description: 'Branch name in the flathub-repo. Default: `update-to-<version>`.',
+            type: 'string',
+        })
+            .option('source-index', {
+            description: 'Index into modules[0].sources[] to update (when manifest has multiple sources). Default: first `type: git` source.',
+            type: 'number',
+        })
+            .option('pr', {
+            description: 'After commit + push, open a PR via `gh pr create`. Pass `--no-pr` to skip and stop after push.',
+            type: 'boolean',
+            default: true,
+        })
+            .option('dry-run', {
+            description: 'Show what would be edited; touch no files, run no git commands.',
+            type: 'boolean',
+            default: false,
+        })
+            .option('verbose', {
+            description: 'Echo every git / gh invocation before running.',
+            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 sync-flathub] no app id available — pass --app-id or set gjsify.flatpak.appId.');
+        }
+        const flathubRepo = args.flathubRepo ??
+            flatpak.flathubRepo ??
+            `flathub/${appId}`;
+        const version = args.version ?? (await resolveLatestTag(cwd, args.verbose));
+        if (!version) {
+            throw new Error('[gjsify flatpak sync-flathub] no version resolved — pass --version vX.Y.Z or create a git tag locally.');
+        }
+        const commitSha = args.commit ?? (await resolveCommitForTag(cwd, version, args.verbose));
+        const branch = args.branch ?? `update-to-${normaliseBranchSegment(version)}`;
+        console.log(`[gjsify flatpak sync-flathub] appId=${appId}`);
+        console.log(`[gjsify flatpak sync-flathub] flathubRepo=${flathubRepo}`);
+        console.log(`[gjsify flatpak sync-flathub] version=${version}`);
+        console.log(`[gjsify flatpak sync-flathub] commit=${commitSha}`);
+        console.log(`[gjsify flatpak sync-flathub] branch=${branch}`);
+        if (args.dryRun) {
+            console.log(`[gjsify flatpak sync-flathub] --dry-run set; not cloning / writing / pushing.`);
+            return;
+        }
+        const cacheRoot = flathubCacheRoot();
+        const cloneDir = join(cacheRoot, flathubRepo.replace('/', '__'));
+        mkdirSync(cacheRoot, { recursive: true });
+        await ensureClone(cloneDir, flathubRepo, args.verbose);
+        const manifestPath = join(cloneDir, `${appId}.json`);
+        if (!existsSync(manifestPath)) {
+            throw new Error(`[gjsify flatpak sync-flathub] Flathub manifest not found at ${manifestPath} — wrong appId / wrong flathub-repo?`);
+        }
+        const original = readFileSync(manifestPath, 'utf-8');
+        const updated = editManifest(original, {
+            tag: version,
+            commit: commitSha,
+            sourceIndex: args.sourceIndex,
+        });
+        if (updated === original) {
+            console.log(`[gjsify flatpak sync-flathub] manifest already at ${version} — nothing to do.`);
+            return;
+        }
+        writeFileSync(manifestPath, updated, 'utf-8');
+        console.log(`[gjsify flatpak sync-flathub] manifest patched at ${manifestPath}`);
+        await gitInRepo(cloneDir, ['checkout', '-B', branch], args.verbose);
+        await gitInRepo(cloneDir, ['add', '.'], args.verbose);
+        await gitInRepo(cloneDir, ['commit', '-m', `Update to ${version}`], args.verbose);
+        if (args.pr === false) {
+            console.log(`[gjsify flatpak sync-flathub] --no-pr set; branch ${branch} committed locally in ${cloneDir}.`);
+            return;
+        }
+        await gitInRepo(cloneDir, ['push', '-u', 'origin', branch, '--force-with-lease'], args.verbose);
+        const prBody = `Auto-generated by \`gjsify flatpak sync-flathub\`.\n\n- Version: \`${version}\`\n- Commit: \`${commitSha}\`\n`;
+        await ghCreate(cloneDir, flathubRepo, branch, version, prBody, args.verbose);
+    },
+};
+// ─── Internal helpers ────────────────────────────────────────────────────
+async function resolveLatestTag(cwd, verbose) {
+    try {
+        const { stdout } = await execFileAsync('git', ['describe', '--tags', '--abbrev=0'], { cwd });
+        if (verbose)
+            console.log(`[gjsify flatpak sync-flathub] resolved latest tag → ${stdout.trim()}`);
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveCommitForTag(cwd, tag, verbose) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-list', '-n', '1', tag], { cwd });
+        const sha = stdout.trim();
+        if (!sha)
+            throw new Error(`empty rev-list output`);
+        if (verbose)
+            console.log(`[gjsify flatpak sync-flathub] resolved ${tag} → ${sha}`);
+        return sha;
+    }
+    catch (err) {
+        throw new Error(`[gjsify flatpak sync-flathub] tag ${tag} not found locally. Run \`git fetch --tags\` or pass --commit <sha>.\n` +
+            `  underlying error: ${err?.message ?? err}`);
+    }
+}
+function normaliseBranchSegment(version) {
+    return version.replace(/^v/, '').replace(/[^A-Za-z0-9._-]/g, '-');
+}
+function flathubCacheRoot() {
+    const base = process.env.XDG_CACHE_HOME || join(homedir(), '.cache');
+    return join(base, 'gjsify', 'flathub-sync');
+}
+async function ensureClone(cloneDir, flathubRepo, verbose) {
+    if (existsSync(join(cloneDir, '.git'))) {
+        if (verbose)
+            console.log(`[gjsify flatpak sync-flathub] reusing clone at ${cloneDir}`);
+        // Hard-reset to remote HEAD to clear stale state from a previous run
+        await gitInRepo(cloneDir, ['fetch', 'origin'], verbose);
+        const defaultBranch = await detectDefaultBranch(cloneDir, verbose);
+        await gitInRepo(cloneDir, ['checkout', defaultBranch], verbose);
+        await gitInRepo(cloneDir, ['reset', '--hard', `origin/${defaultBranch}`], verbose);
+        return;
+    }
+    mkdirSync(resolve(cloneDir, '..'), { recursive: true });
+    const url = `https://github.com/${flathubRepo}.git`;
+    if (verbose)
+        console.log(`[gjsify flatpak sync-flathub] git clone ${url} ${cloneDir}`);
+    try {
+        await execFileAsync('git', ['clone', url, cloneDir]);
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT') {
+            throw new Error('[gjsify flatpak sync-flathub] `git` not found. Install git from your distro (Fedora: `dnf install git`, Debian: `apt install git`).');
+        }
+        throw err;
+    }
+}
+async function detectDefaultBranch(cloneDir, verbose) {
+    // Most flathub repos use `master`; some newer ones use `main`. Probe
+    // via `git remote show` which surfaces the HEAD branch.
+    try {
+        const { stdout } = await execFileAsync('git', ['remote', 'show', 'origin'], { cwd: cloneDir });
+        const m = stdout.match(/HEAD branch: (\S+)/);
+        if (m && m[1] && m[1] !== '(unknown)') {
+            if (verbose)
+                console.log(`[gjsify flatpak sync-flathub] default branch → ${m[1]}`);
+            return m[1];
+        }
+    }
+    catch {
+        // fall through to master fallback
+    }
+    return 'master';
+}
+function gitInRepo(cwd, args, verbose) {
+    if (verbose)
+        console.log(`[gjsify flatpak sync-flathub] git ${args.join(' ')} (in ${cwd})`);
+    return new Promise((res, rej) => {
+        const child = spawn('git', args, { cwd, stdio: 'inherit' });
+        child.on('error', (err) => {
+            if (err.code === 'ENOENT') {
+                rej(new Error('[gjsify flatpak sync-flathub] `git` not found. Install it from your distro.'));
+            }
+            else {
+                rej(err);
+            }
+        });
+        child.on('exit', (code) => {
+            if (code === 0)
+                res();
+            else
+                rej(new Error(`git ${args[0]} exited ${code}`));
+        });
+    });
+}
+function ghCreate(cloneDir, flathubRepo, branch, version, body, verbose) {
+    const args = [
+        'pr',
+        'create',
+        '--repo',
+        flathubRepo,
+        '--head',
+        branch,
+        '--title',
+        `Update to ${version}`,
+        '--body',
+        body,
+    ];
+    if (verbose)
+        console.log(`[gjsify flatpak sync-flathub] gh ${args.join(' ')} (in ${cloneDir})`);
+    return new Promise((res, rej) => {
+        const child = spawn('gh', args, { cwd: cloneDir, stdio: 'inherit' });
+        child.on('error', (err) => {
+            if (err.code === 'ENOENT') {
+                rej(new Error('[gjsify flatpak sync-flathub] `gh` (GitHub CLI) not found. Install via `dnf install gh` (Fedora), `apt install gh` (Debian/Ubuntu), or `flatpak install -y flathub com.github.cli`.'));
+            }
+            else {
+                rej(err);
+            }
+        });
+        child.on('exit', (code) => {
+            if (code === 0)
+                res();
+            else
+                rej(new Error(`gh pr create exited ${code}`));
+        });
+    });
+}
+/**
+ * Surgically edit a Flathub manifest to update the git source's `tag` +
+ * `commit` (and inject `x-checker-data` if missing). Preserves the
+ * original indent + whitespace + key ordering of the surrounding JSON
+ * by parsing through JSON.parse + re-stringifying with the detected
+ * indent.
+ */
+export function editManifest(original, args) {
+    const manifest = JSON.parse(original);
+    const modules = manifest.modules ?? [];
+    if (modules.length === 0) {
+        throw new Error('[gjsify flatpak sync-flathub] manifest has no modules');
+    }
+    const mainModule = modules[0];
+    const sources = mainModule.sources ?? [];
+    if (sources.length === 0) {
+        throw new Error('[gjsify flatpak sync-flathub] modules[0] has no sources');
+    }
+    let idx = args.sourceIndex ?? sources.findIndex((s) => s.type === 'git');
+    if (idx < 0 || idx >= sources.length) {
+        throw new Error(`[gjsify flatpak sync-flathub] no git source found in modules[0].sources (use --source-index <n>)`);
+    }
+    const source = sources[idx];
+    if (source.type !== 'git') {
+        throw new Error(`[gjsify flatpak sync-flathub] modules[0].sources[${idx}].type is "${source.type}", expected "git"`);
+    }
+    source.tag = args.tag;
+    source.commit = args.commit;
+    if (!source['x-checker-data']) {
+        source['x-checker-data'] = {
+            type: 'git',
+            'tag-pattern': '^v(\\d+\\.\\d+\\.\\d+)$',
+            'version-scheme': 'semantic',
+        };
+    }
+    // Detect the original indent (2 vs 4 spaces) by inspecting the second
+    // line — Flathub manifests are all 2-space in practice, but some
+    // older ones might be 4. Preserve original convention.
+    const indent = detectIndent(original);
+    return JSON.stringify(manifest, null, indent) + (original.endsWith('\n') ? '\n' : '');
+}
+function detectIndent(json) {
+    const match = json.match(/^\{\n( +)/);
+    if (match)
+        return match[1].length;
+    return 2;
+}

package/lib/commands/format.d.ts

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