@gjsify/cli 0.51.1 → 0.52.0

package/lib/cli-app.js

@@ -18,7 +18,7 @@
 import yargs from 'yargs';
 import { classifyCliFailure } from './cli-fail.js';
 import { cliVersion } from './utils/publish-headers.js';
-import { buildCommand as build, clearCommand as clear, copyCommand as copy, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, shipCommand as ship, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, onboardCommand as onboard, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, pruneCommand as prune, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, devCommand as dev, debugCommand as debug, browseCommand as browse, } from './commands/index.js';
+import { buildCommand as build, clearCommand as clear, copyCommand as copy, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, shipCommand as ship, dlxCommand as dlx, installCommand as install, linkCommand as link, unlinkCommand as unlink, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, trustCommand as trust, onboardCommand as onboard, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, pruneCommand as prune, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, storybookCommand as storybook, devCommand as dev, debugCommand as debug, browseCommand as browse, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 import { isBun, isDeno, isNode, gjsSystemVersion } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.js';
@@ -93,6 +93,8 @@ export async function runCli(argv) {
         .wrap(cli.terminalWidth())
         .command(create.command, create.description, create.builder, create.handler)
         .command(install.command, install.description, install.builder, install.handler)
+        .command(link.command, link.description, link.builder, link.handler)
+        .command(unlink.command, unlink.description, unlink.builder, unlink.handler)
         .command(build.command, build.description, build.builder, build.handler)
         .command(clear.command, clear.description, clear.builder, clear.handler)
         .command(copy.command, copy.description, copy.builder, copy.handler)

package/lib/commands/affected-classify.d.ts

@@ -1,4 +1,5 @@
 import { type Workspace } from '@gjsify/workspace';
+import type { ScriptReferrers } from './affected-script-refs.js';
 export interface ClassifyResult {
     /** Cannot decide precisely — caller should run full suite. */
     global: boolean;
@@ -13,4 +14,9 @@ export interface ClassifyResult {
     /** Diff was empty AND no triggers fired → CI can skip the whole job. */
     skipAll: boolean;
 }
-export declare function classifyAndExpand(workspaces: readonly Workspace[], changedFiles: readonly string[]): ClassifyResult;
+/**
+ * @param readersOf who reads a root `scripts/*` file. Omitted, a changed root script stays
+ *   `unmatched` and forces the full run — the behaviour before the lookup existed, and what
+ *   the command falls back to when it cannot list the tree.
+ */
+export declare function classifyAndExpand(workspaces: readonly Workspace[], changedFiles: readonly string[], readersOf?: ScriptReferrers): ClassifyResult;

package/lib/commands/affected-classify.js

@@ -49,8 +49,10 @@ const GLOBAL_TRIGGERS = [
  */
 const OTHER_WORKFLOW_INPUTS = [
     // Each sibling workflow's own definition. `main.yml` is deliberately absent: it
-    // is a GLOBAL_TRIGGER instead.
-    /^\.github\/workflows\/(deploy-docs|commitlint|release|release-cut|audit-runtimes|prebuilds|node-gi|napi|cli-cross-platform|build-ci-image|cancel-pr-runs)\.yml$/,
+    // is a GLOBAL_TRIGGER instead. The three OS-suite workflows run unfiltered on every
+    // PR, so an edit to one is measured by that run; `webview2-probe.yml` is absent on
+    // purpose, being dispatch-only — nothing would measure an edit to it on the PR.
+    /^\.github\/workflows\/(deploy-docs|commitlint|release|release-cut|audit-runtimes|prebuilds|node-gi|napi|cli-cross-platform|build-ci-image|cancel-pr-runs|macos-suites|windows-suites|gtk-os-suites)\.yml$/,
     // `prebuilds.yml`'s toolchain (#838): the QEMU-emulated build script and the
     // classifier deciding which native packages a prebuild run rebuilds. It is in
     // both of that workflow's `paths:` filters; `main.yml` builds no prebuild and
@@ -168,7 +170,51 @@ const SCRIPT_COUPLINGS = [
         why: 'tests/e2e/react-native-devtools is the only external observer of AppRegistry.runApplication',
     },
 ];
-export function classifyAndExpand(workspaces, changedFiles) {
+/** A root script whose readers can stand in for it (see `affected-script-refs.ts`). */
+const ROOT_SCRIPT = /^scripts\/[^/]+$/;
+function isResolvableScript(f) {
+    return (ROOT_SCRIPT.test(f) &&
+        !GLOBAL_TRIGGERS.some((re) => re.test(f)) &&
+        !SCRIPT_COUPLINGS.some((c) => c.match.test(f)));
+}
+/**
+ * Replace each changed root script by the files that read it, recursively through scripts
+ * that read scripts. Readers go back through IGNORE here and through GLOBAL / workspace
+ * mapping in the caller, so a reader this classifier does not model still forces the full
+ * run, and a script a GLOBAL_TRIGGER reads (`audit-runtimes.mjs`) stays in and fires it.
+ */
+function resolveRootScripts(files, readersOf) {
+    const out = new Set();
+    const queue = [];
+    for (const f of files) {
+        if (isResolvableScript(f))
+            queue.push(f);
+        else
+            out.add(f);
+    }
+    const seen = new Set();
+    while (queue.length > 0) {
+        const s = queue.shift();
+        if (seen.has(s))
+            continue;
+        seen.add(s);
+        for (const r of readersOf(s)) {
+            if (IGNORE.some((re) => re.test(r)))
+                continue;
+            if (isResolvableScript(r))
+                queue.push(r);
+            else
+                out.add(r);
+        }
+    }
+    return { files: [...out], scripts: seen.size };
+}
+/**
+ * @param readersOf who reads a root `scripts/*` file. Omitted, a changed root script stays
+ *   `unmatched` and forces the full run — the behaviour before the lookup existed, and what
+ *   the command falls back to when it cannot list the tree.
+ */
+export function classifyAndExpand(workspaces, changedFiles, readersOf) {
     const files = changedFiles.map((f) => f.replace(/\\/g, '/')).filter((f) => f.length > 0);
     if (files.length === 0) {
         return {
@@ -182,16 +228,26 @@ export function classifyAndExpand(workspaces, changedFiles) {
     }
     // Ignored files go FIRST, before the global-trigger check: ignore wins over
     // global, so `packages/infra/cli/README.md` must not force a full run.
-    const remaining = [];
+    let remaining = [];
     for (const f of files) {
         if (IGNORE.some((re) => re.test(f)))
             continue;
         remaining.push(f);
     }
+    // Every verdict below says when it was reached through a script's readers, so a
+    // surprising selection can be traced back to the lookup rather than the diff.
+    let note = '';
+    if (readersOf) {
+        const resolved = resolveRootScripts(remaining, readersOf);
+        if (resolved.scripts > 0) {
+            remaining = resolved.files;
+            note = `; ${resolved.scripts} root script(s) resolved to their readers`;
+        }
+    }
     if (remaining.length === 0) {
         return {
             global: false,
-            reason: 'ignored-only',
+            reason: 'ignored-only' + note,
             workspaces: [],
             runE2E: false,
             runIntegration: false,
@@ -204,7 +260,7 @@ export function classifyAndExpand(workspaces, changedFiles) {
             if (re.test(f)) {
                 return {
                     global: true,
-                    reason: `global-trigger ${re.source} matched ${f}`,
+                    reason: `global-trigger ${re.source} matched ${f}${note}`,
                     workspaces: workspaces.map((w) => w.name),
                     runE2E: true,
                     runIntegration: true,
@@ -254,7 +310,7 @@ export function classifyAndExpand(workspaces, changedFiles) {
     if (stillUnmatched.length > 0) {
         return {
             global: true,
-            reason: `unmatched files (${stillUnmatched.length}): ${stillUnmatched.slice(0, 3).join(', ')}${stillUnmatched.length > 3 ? '…' : ''}`,
+            reason: `unmatched files (${stillUnmatched.length}): ${stillUnmatched.slice(0, 3).join(', ')}${stillUnmatched.length > 3 ? '…' : ''}${note}`,
             workspaces: workspaces.map((w) => w.name),
             runE2E: true,
             runIntegration: true,
@@ -274,7 +330,7 @@ export function classifyAndExpand(workspaces, changedFiles) {
         const touchedIntegration = remaining.some((f) => f.startsWith('tests/integration/'));
         return {
             global: false,
-            reason: `test-only (${remaining.length} file(s) in ${only})`,
+            reason: `test-only (${remaining.length} file(s) in ${only})${note}`,
             workspaces: [only],
             // `|| couplingRunE2E`: this shortcut skips CLOSURE EXPANSION, and a
             // declared tier is not part of the closure. Dropping it here made a
@@ -323,7 +379,8 @@ export function classifyAndExpand(workspaces, changedFiles) {
     return {
         global: false,
         reason: `closure (${closure.size} ws from ${matched.size} seed(s))` +
-            (couplingSeeds.size > 0 ? `, ${couplingSeeds.size} via script-coupling` : ''),
+            (couplingSeeds.size > 0 ? `, ${couplingSeeds.size} via script-coupling` : '') +
+            note,
         workspaces: [...closure].sort(),
         runE2E,
         runIntegration,

package/lib/commands/affected-script-refs.d.ts

@@ -0,0 +1,20 @@
+/** Every file that names `scriptPath`, as repo-relative paths. */
+export type ScriptReferrers = (scriptPath: string) => readonly string[];
+/**
+ * The file-name pattern for a script: `adwaita-elements.mjs` is also read as
+ * `adwaita-elements.d.mts` (a TS import of the `.mjs` resolves to its declaration) and a
+ * `.d.mts` change is read through its `.mjs`. The leading boundary excludes `-` so
+ * `value-types.mjs` does not match `generate-value-types.mjs`.
+ */
+export declare function scriptNamePattern(scriptPath: string): RegExp;
+/**
+ * Build the reader lookup over `texts` (repo-relative path → raw content). Pure: the command
+ * feeds it `git ls-files`, the spec feeds it a fixture map.
+ */
+export declare function buildScriptReferrers(texts: ReadonlyMap<string, string>): ScriptReferrers;
+/**
+ * Every tracked text file under `rootDir`, for {@link buildScriptReferrers}. Throws when git
+ * cannot list the tree — the caller then classifies without the lookup, which is the old,
+ * conservative behaviour (a root script lands in `unmatched`).
+ */
+export declare function readTrackedTexts(rootDir: string): Map<string, string>;

package/lib/commands/affected-script-refs.js

@@ -0,0 +1,218 @@
+// SPDX-License-Identifier: MIT
+// Who READS a root `scripts/*` file — the edge the `affected` closure walk has no way to see.
+//
+// WHY THIS EXISTS. `scripts/` belongs to no workspace, so every change there used to land in
+// `unmatched` and buy a FULL `main.yml` run. Measured over the 60 PRs before #1774: 33 went
+// full for that reason alone, and most of them touched only a website or gallery gate that
+// `audit-runtimes.yml` runs and `main.yml` never opens. The full run was never wrong — it was
+// the classifier saying "I cannot tell" about a question the tree answers: a script matters to
+// `main.yml` exactly when something `main.yml` builds or runs names it.
+//
+// So a changed root script is REPLACED by the files that name it, and those go through the
+// ordinary IGNORE → GLOBAL → workspace mapping. A spec that imports it seeds its workspace; a
+// workspace build script that runs it seeds that workspace; a sibling workflow that runs it is
+// IGNOREd like the workflow itself; `.github/actions`, `tests/e2e/**` or anything else the
+// classifier does not model still forces the full run. A script that names another script
+// hands the question on (`affected-classify.ts` walks that recursively).
+//
+// THE MATCH IS DELIBERATELY LOOSE, because it may only fail towards running MORE. It is the
+// script's file name (stem plus a JS/TS extension, `.d.mts` included), not an import
+// statement: `join(root, 'scripts', 'x.mjs')` and `node scripts/x.mjs` are both reads, and a
+// parser for "is this an import" would miss the first. The price is that an error message
+// naming a script counts as a reader too — measured, that turns some script changes back
+// into full runs, which is the direction this is allowed to be wrong in. Comment lines are
+// dropped first; without that, the prose cross-references in this repository chain every
+// script to every other one and the whole mechanism collapses back into "run everything".
+//
+// TWO READERS ARE NARROWED, and each narrowing is a claim about `main.yml`'s shape:
+//   · `main.yml` itself counts only from a job that (transitively) `needs: changes`. A job
+//     that does not — `tree-checks` today — runs on every PR whatever this classifier says,
+//     so a script it runs cannot be skipped by anything decided here.
+//   · the root `package.json` counts only when the script is named outside `scripts`, or by
+//     a lifecycle/build/test entry, or by an entry another root script or a gated `main.yml`
+//     job runs. The `check:*` conveniences that only a person or a sibling workflow invokes
+//     are not `main.yml` inputs.
+//
+// NOT SEEN, stated so nobody reads this as more: a reader that builds the file name at run
+// time, and a tool that walks `scripts/` as a directory. The second shape exists
+// (`generate-status.mjs`, `check-comment-budget.mjs`) but only in jobs outside `main.yml`'s
+// gated set. Push-to-main and the nightly still run the FULL suite.
+import { spawnSync } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { join, posix } from 'node:path';
+const MAIN_WORKFLOW = '.github/workflows/main.yml';
+const ROOT_MANIFEST = 'package.json';
+/** Larger files are data (lockfile, generated corpora), never a script's reader. */
+const MAX_TEXT_BYTES = 2 * 1024 * 1024;
+/**
+ * A root package.json entry whose run is part of installing, building or testing the tree.
+ * Not `check:*`: those are single-gate conveniences (`node scripts/check-….mjs`), and the
+ * one `main.yml` does run (`check:examples`) is caught by name in the workflow instead.
+ */
+const LIFECYCLE_SCRIPT = /^(pre|post)?(install|prepare|build|test)(:|$)/;
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Comment lines out: `#` for YAML, shell, git and Docker files, `//` + block-comment lines
+ * for everything else. `#` is not stripped from JS, where a line may open with a private
+ * field.
+ */
+function stripCommentLines(path, text) {
+    const hashComments = /\.(ya?ml|sh|bash|py|toml)$|(^|\/)\.git[a-z]*$|Dockerfile$/.test(path);
+    const comment = hashComments ? /^\s*#/ : /^\s*(\/\/|\/\*|\*)/;
+    return text
+        .split('\n')
+        .filter((line) => !comment.test(line))
+        .join('\n');
+}
+/**
+ * The file-name pattern for a script: `adwaita-elements.mjs` is also read as
+ * `adwaita-elements.d.mts` (a TS import of the `.mjs` resolves to its declaration) and a
+ * `.d.mts` change is read through its `.mjs`. The leading boundary excludes `-` so
+ * `value-types.mjs` does not match `generate-value-types.mjs`.
+ */
+export function scriptNamePattern(scriptPath) {
+    // A git path, always `/`-separated whatever the host: POSIX basename, not the host's.
+    const base = posix.basename(scriptPath);
+    const js = /^(.*?)(\.d)?\.[mc]?[jt]sx?$/.exec(base);
+    const tail = js ? `${escapeRe(js[1])}(\\.d)?\\.[mc]?[jt]sx?\\b` : `${escapeRe(base)}\\b`;
+    return new RegExp(`(^|[^\\w.-])${tail}`);
+}
+/**
+ * Jobs of `main.yml` that depend, directly or through `needs:`, on the `changes` job — the
+ * ones the classifier can switch off. Comment lines are already gone: `setup`'s comments
+ * NAME `needs.changes.outputs.*`, and counting that made `tree-checks` look gated.
+ */
+function gatedJobs(lines) {
+    const needs = new Map();
+    const mentionsChanges = new Set();
+    for (const { job, text } of lines) {
+        if (!job)
+            continue;
+        if (!needs.has(job))
+            needs.set(job, []);
+        const n = /^ {4}needs:\s*\[(.*)\]/.exec(text) ?? /^ {4}needs:\s*([A-Za-z0-9_-]+)\s*$/.exec(text);
+        if (n)
+            needs.set(job, n[1]
+                .split(',')
+                .map((d) => d.trim())
+                .filter(Boolean));
+        // A block-list `needs:` is a spelling this parse does not read, so the job counts
+        // as gated: misreading one here could only ever skip less.
+        if (/needs\.changes\b/.test(text) || /^ {4}needs:\s*$/.test(text))
+            mentionsChanges.add(job);
+    }
+    const gated = new Set(['changes', ...mentionsChanges]);
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const [j, deps] of needs) {
+            if (!gated.has(j) && deps.some((d) => gated.has(d))) {
+                gated.add(j);
+                grew = true;
+            }
+        }
+    }
+    // `changes` itself runs the classifier; it is not switched off by it.
+    gated.delete('changes');
+    return gated;
+}
+function workflowLines(text) {
+    const lines = text.split('\n');
+    const out = [];
+    let job;
+    let inJobs = false;
+    for (const line of lines) {
+        if (/^jobs:\s*$/.test(line))
+            inJobs = true;
+        else if (/^\S/.test(line))
+            inJobs = false;
+        const key = inJobs ? /^ {2}([A-Za-z0-9_-]+):\s*$/.exec(line) : null;
+        if (key)
+            job = key[1];
+        if (/^\s*#/.test(line))
+            continue;
+        out.push({ job: inJobs ? job : undefined, text: line });
+    }
+    return out;
+}
+/**
+ * Build the reader lookup over `texts` (repo-relative path → raw content). Pure: the command
+ * feeds it `git ls-files`, the spec feeds it a fixture map.
+ */
+export function buildScriptReferrers(texts) {
+    const stripped = new Map();
+    for (const [path, text] of texts) {
+        if (path === MAIN_WORKFLOW || path === ROOT_MANIFEST)
+            continue;
+        stripped.set(path, stripCommentLines(path, text));
+    }
+    const workflowText = texts.get(MAIN_WORKFLOW);
+    const workflow = workflowText === undefined ? [] : workflowLines(workflowText);
+    const gated = gatedJobs(workflow);
+    // Top-level workflow keys (`env:`) reach every job, so they count as gated too.
+    const gatedWorkflowNames = (re) => workflow.some((l) => re.test(l.text) && (l.job === undefined || gated.has(l.job)));
+    let manifest;
+    const manifestText = texts.get(ROOT_MANIFEST);
+    if (manifestText !== undefined)
+        manifest = JSON.parse(manifestText);
+    const manifestReads = (re) => {
+        if (!manifest)
+            return false;
+        for (const [k, v] of Object.entries(manifest)) {
+            if (k !== 'scripts' && re.test(JSON.stringify(v)))
+                return true;
+        }
+        const scripts = manifest.scripts ?? {};
+        for (const [key, value] of Object.entries(scripts)) {
+            if (!re.test(value))
+                continue;
+            if (LIFECYCLE_SCRIPT.test(key))
+                return true;
+            const byName = new RegExp(`(^|[\\s"'])${escapeRe(key)}($|[\\s"'&;|])`);
+            if (Object.entries(scripts).some(([other, v]) => other !== key && byName.test(v)))
+                return true;
+            if (gatedWorkflowNames(byName))
+                return true;
+        }
+        return false;
+    };
+    return (scriptPath) => {
+        const re = scriptNamePattern(scriptPath);
+        const readers = [];
+        for (const [path, text] of stripped) {
+            if (path !== scriptPath && re.test(text))
+                readers.push(path);
+        }
+        if (gatedWorkflowNames(re))
+            readers.push(MAIN_WORKFLOW);
+        if (manifestReads(re))
+            readers.push(ROOT_MANIFEST);
+        return readers.sort();
+    };
+}
+/**
+ * Every tracked text file under `rootDir`, for {@link buildScriptReferrers}. Throws when git
+ * cannot list the tree — the caller then classifies without the lookup, which is the old,
+ * conservative behaviour (a root script lands in `unmatched`).
+ */
+export function readTrackedTexts(rootDir) {
+    const r = spawnSync('git', ['ls-files', '-z'], { cwd: rootDir, encoding: 'utf8' });
+    if (r.status !== 0)
+        throw new Error(`git ls-files failed (${r.status}): ${String(r.stderr).trim()}`);
+    const texts = new Map();
+    for (const path of r.stdout.split('\0')) {
+        if (!path || path.startsWith('refs/'))
+            continue;
+        const abs = join(rootDir, path);
+        // A gitlink (submodule) is listed but is a directory; a deleted-but-staged path is
+        // listed and absent. Neither can name a script.
+        const st = statSync(abs, { throwIfNoEntry: false });
+        if (!st?.isFile() || st.size > MAX_TEXT_BYTES)
+            continue;
+        const text = readFileSync(abs, 'utf8');
+        if (text.includes('\0'))
+            continue;
+        texts.set(path, text);
+    }
+    return texts;
+}

package/lib/commands/affected.js

@@ -58,6 +58,7 @@ import { appendFileSync } from 'node:fs';
 import { readStdinLines } from '../utils/stdin.js';
 import { discoverWorkspaces } from '@gjsify/workspace';
 import { classifyAndExpand } from './affected-classify.js';
+import { buildScriptReferrers, readTrackedTexts } from './affected-script-refs.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 export const affectedCommand = {
     command: 'affected',
@@ -92,15 +93,36 @@ export const affectedCommand = {
         const changedFiles = args['changed-from-stdin']
             ? readStdinLines()
             : runGitDiff(rootDir, args.base ?? 'origin/main', args.head ?? 'HEAD');
-        const result = classifyAndExpand(workspaces, changedFiles);
+        const result = classifyAndExpand(workspaces, changedFiles, scriptReadersFor(rootDir, changedFiles));
         emit(args.format, result);
     },
 };
+/**
+ * The root-script reader lookup, built only when the diff has a root script in it — reading
+ * the tree costs a second or two and most diffs do not need it. `undefined` when git cannot
+ * list the tree (a fixture without a repository): the classifier then treats a root script
+ * as it always did, as `unmatched`, which forces the full run.
+ */
+function scriptReadersFor(rootDir, changedFiles) {
+    if (!changedFiles.some((f) => /^scripts\/[^/]+$/.test(f.replace(/\\/g, '/'))))
+        return undefined;
+    try {
+        return buildScriptReferrers(readTrackedTexts(rootDir));
+    }
+    catch (err) {
+        process.stderr.write(`gjsify affected: cannot index the tree for script readers (${String(err)}); root scripts stay unmatched\n`);
+        return undefined;
+    }
+}
 function runGitDiff(cwd, base, head) {
     // `base...head` lists changed paths on `head` relative to the MERGE-BASE, which
     // matches what a GitHub PR diff shows and survives stacked PRs without picking up
     // commits from base.
-    const r = spawnSync('git', ['diff', '--name-only', `${base}...${head}`], {
+    // `--no-renames`: with rename detection on (git's default since 2.9), a pure move lists
+    // only the DESTINATION. Moving `packages/node/os/src/x.ts` to `docs/x.ts` then reads as
+    // a docs-only change and skips every suite that would have seen `@gjsify/os` break.
+    // Without detection a move is a delete plus an add, and the deleted side seeds as usual.
+    const r = spawnSync('git', ['diff', '--no-renames', '--name-only', `${base}...${head}`], {
         cwd,
         encoding: 'utf8',
     });

package/lib/commands/flatpak/diff.js

@@ -125,10 +125,16 @@ async function loadFlathubSource(args, sourceIndex) {
     const sources = modules[0]?.sources ?? [];
     if (sources.length === 0)
         return null;
-    const idx = sourceIndex ?? sources.findIndex((s) => s?.type === 'git');
+    const idx = sourceIndex ?? sources.findIndex((s) => isSourceObject(s) && s.type === 'git');
     if (idx < 0 || idx >= sources.length)
         return null;
-    return sources[idx] ?? null;
+    // A `--source-index` aimed at a file reference has no tag to compare, which
+    // the caller already reports as a manifest without one.
+    const entry = sources[idx];
+    return isSourceObject(entry) ? entry : null;
+}
+function isSourceObject(entry) {
+    return typeof entry === 'object' && entry !== null;
 }
 async function fetchFlathubManifest(flathubRepo, appId, verbose) {
     for (const branch of ['master', 'main']) {

package/lib/commands/flatpak/init.js

@@ -153,7 +153,10 @@ export const flatpakInitCommand = {
         //   `flatpak.extraModules` — prepended to the meson default.
         //                            Right shape for meson-built GTK apps
         //                            that want a few extra sibling modules
-        //                            (e.g. blueprint-compiler).
+        //                            (e.g. a GI library the runtime lacks). NOT
+        //                            blueprint-compiler: ADR 0053 clause 5 parses
+        //                            `.blp` in the bundler, so a manifest that
+        //                            builds it builds a tool nothing runs.
         const modules = [];
         if (flatpak.modules?.length) {
             modules.push(...flatpak.modules);

package/lib/commands/flatpak/sources.js

@@ -19,6 +19,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { Buffer } from 'node:buffer';
+import { FLATPAK_SOURCES_FILE } from './utils.js';
 /** Checksum algorithms flatpak-builder accepts on a `file` source. */
 const FLATPAK_ALGOS = new Set(['sha256', 'sha512']);
 /** Parse an SRI integrity (`sha512-<base64>`) into `{ algorithm, hex }`. Mirrors
@@ -219,7 +220,7 @@ export const flatpakSourcesCommand = {
             .option('out', {
             description: 'Output JSON sources file',
             type: 'string',
-            default: 'gjsify-sources.json',
+            default: FLATPAK_SOURCES_FILE,
             normalize: true,
         })
             .option('cache-root', {
@@ -277,7 +278,7 @@ export const flatpakSourcesCommand = {
         }
         // Stable order (by url) so the generated file diffs cleanly across runs.
         const sources = [...byHex.values()].sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
-        const out = resolve(cwd, args.out ?? 'gjsify-sources.json');
+        const out = resolve(cwd, args.out ?? FLATPAK_SOURCES_FILE);
         mkdirSync(dirname(out), { recursive: true });
         writeFileSync(out, JSON.stringify(sources, null, 2) + '\n');
         console.log(`[gjsify flatpak sources] wrote ${out} — ${sources.length} tarball source(s) from ${type} lockfile` +
@@ -285,7 +286,7 @@ export const flatpakSourcesCommand = {
             (skippedSri ? `, ${skippedSri} without a usable integrity skipped` : '') +
             (skippedAlgo ? `, ${skippedAlgo} non-sha256/512 skipped` : ''));
         if (args.printModule) {
-            console.error(buildModuleSnippet(args.out ?? 'gjsify-sources.json', cacheRoot));
+            console.error(buildModuleSnippet(args.out ?? FLATPAK_SOURCES_FILE, cacheRoot));
         }
     },
 };

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

@@ -1,6 +1,7 @@
 import type { Command } from '../../types/index.js';
 interface SyncFlathubOptions {
     version?: string;
+    sourcesFile?: string;
     appId?: string;
     flathubRepo?: string;
     commit?: string;
@@ -22,5 +23,6 @@ export declare function editManifest(original: string, args: {
     tag: string;
     commit: string;
     sourceIndex?: number;
+    sourcesFile?: string;
 }): string;
 export {};