@gjsify/cli 0.51.1 → 0.52.0

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

@@ -11,7 +11,8 @@
 //   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)
+//      plus x-checker-data block (inject if missing), and carry over the
+//      offline source list (see `offline sources` below)
 //   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';
@@ -21,7 +22,7 @@ import { execFile } from 'node:child_process';
 import { describeExit, spawnToCompletion } from '../../utils/spawn.js';
 import { promisify } from 'node:util';
 import { Config } from '../../config.js';
-import { readPackageJson } from './utils.js';
+import { FLATPAK_SOURCES_FILE, readPackageJson } from './utils.js';
 const execFileAsync = promisify(execFile);
 export const flatpakSyncFlathubCommand = {
     command: 'sync-flathub',
@@ -51,6 +52,12 @@ export const flatpakSyncFlathubCommand = {
             .option('branch', {
             description: 'Branch name in the flathub-repo. Default: `update-to-<version>`.',
             type: 'string',
+        })
+            .option('sources-file', {
+            description: 'Generated offline tarball list to carry into the Flathub repo and name in the manifest. ' +
+                `Default: \`${FLATPAK_SOURCES_FILE}\`. Skipped when the tag does not carry it.`,
+            type: 'string',
+            default: FLATPAK_SOURCES_FILE,
         })
             .option('source-index', {
             description: 'Index into modules[0].sources[] to update (when manifest has multiple sources). Default: first `type: git` source.',
@@ -105,13 +112,33 @@ export const flatpakSyncFlathubCommand = {
         if (!existsSync(manifestPath)) {
             throw new Error(`[gjsify flatpak sync-flathub] Flathub manifest not found at ${manifestPath} — wrong appId / wrong flathub-repo?`);
         }
+        // Read AT THE TAG, not from the working tree: the manifest is about to pin
+        // that tag, and a list taken from an edited checkout would describe a tree
+        // nobody can get. Absent is the ordinary case for an app that installs
+        // online or vendors its dependencies, so it is a skip and not an error.
+        const sourcesFile = args.sourcesFile ?? FLATPAK_SOURCES_FILE;
+        const offline = await readSourceListAtTag(cwd, version, sourcesFile, args.verbose);
+        let offlineCopied = false;
+        if (offline !== null) {
+            const dest = join(cloneDir, sourcesFile);
+            offlineCopied = !existsSync(dest) || readFileSync(dest, 'utf-8') !== offline;
+            if (offlineCopied) {
+                writeFileSync(dest, offline, 'utf-8');
+                console.log(`[gjsify flatpak sync-flathub] ${sourcesFile} copied from ${version}`);
+            }
+        }
         const original = readFileSync(manifestPath, 'utf-8');
         const updated = editManifest(original, {
             tag: version,
             commit: commitSha,
             sourceIndex: args.sourceIndex,
+            sourcesFile: offline !== null ? sourcesFile : undefined,
         });
-        if (updated === original) {
+        // NOT `updated === original` alone: the tarball list changes whenever a
+        // dependency does, so a release can need a PR with the pin unmoved. That
+        // test used to be the only one, and it would have returned "nothing to do"
+        // over a Flathub repo carrying a stale list.
+        if (updated === original && !offlineCopied) {
             console.log(`[gjsify flatpak sync-flathub] manifest already at ${version} — nothing to do.`);
             return;
         }
@@ -130,6 +157,88 @@ export const flatpakSyncFlathubCommand = {
     },
 };
 // ─── Internal helpers ────────────────────────────────────────────────────
+/**
+ * The generated source list as of `tag`, or null when the tag does not carry one.
+ *
+ * `git show <tag>:<path>` rather than reading the working tree, so the file that
+ * travels to Flathub is the one the pinned commit actually contains.
+ *
+ * WHAT COMES BACK IS CHECKED, not just whether the command succeeded. A missing
+ * path makes real `git show` exit non-zero, so the obvious version of this
+ * function looks complete — and it treats an EMPTY answer as "the file exists
+ * and is empty", which then writes an empty file into the Flathub repo and
+ * names it in the manifest. That is strictly worse than skipping: the build
+ * still cannot install, and now the manifest says it can. Caught by the
+ * sync-flathub E2E, whose git stub answers every unknown subcommand with exit 0
+ * and no output.
+ *
+ * A blank answer is a skip. Content that is not a non-empty array of sources is
+ * an ERROR, because this file has exactly one producer (`gjsify flatpak
+ * sources`) and anything else means something upstream is broken.
+ */
+async function readSourceListAtTag(cwd, tag, path, verbose) {
+    let raw;
+    try {
+        const { stdout } = await execFileAsync('git', ['show', `${tag}:${path}`], { cwd, maxBuffer: 64 * 1024 * 1024 });
+        raw = stdout;
+    }
+    catch (error) {
+        await assertGitMeantAbsent(cwd, tag, path, error);
+        if (verbose)
+            console.log(`[gjsify flatpak sync-flathub] ${path} not present at ${tag} — skipping`);
+        return null;
+    }
+    if (raw.trim() === '') {
+        if (verbose)
+            console.log(`[gjsify flatpak sync-flathub] ${path} is empty at ${tag} — skipping`);
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`[gjsify flatpak sync-flathub] ${path} at ${tag} is not JSON: ` +
+            (error instanceof Error ? error.message : String(error)));
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new Error(`[gjsify flatpak sync-flathub] ${path} at ${tag} is not a non-empty array of flatpak sources`);
+    }
+    return raw;
+}
+/**
+ * Throw unless a failed `git show <tag>:<path>` really did mean "that tag does
+ * not carry that file".
+ *
+ * MEASURED, and it is why the failure cannot be read on its own: path absent,
+ * unknown tag and not-a-git-repository are ALL exit 128, and git translates the
+ * message (`Pfad … existiert nicht in …` on a German host), so neither the
+ * status nor the text separates them. Taken for absence, a tag nobody fetched
+ * moves the pin and leaves the Flathub repo's old list in place — the failure
+ * this file exists to prevent, now silent. `--commit <sha>` is what puts it in
+ * reach: it is the one path on which nothing else resolves the tag.
+ *
+ * The tag is therefore asked about separately, and a SHA is believed rather
+ * than an exit code — the same lesson as the read above, since a `git` that
+ * answers 0 with nothing must not pass for a tag that exists.
+ */
+async function assertGitMeantAbsent(cwd, tag, path, error) {
+    const code = error?.code;
+    if (typeof code !== 'number') {
+        // Not git's verdict at all: ENOENT is no `git` on PATH, and
+        // ERR_CHILD_PROCESS_STDIO_MAXBUFFER a list past the cap set above.
+        throw new Error(`[gjsify flatpak sync-flathub] could not run \`git show ${tag}:${path}\` — ` +
+            (error instanceof Error ? error.message : String(error)));
+    }
+    // `--quiet` exits 1 rather than printing for a name it cannot resolve.
+    const sha = await execFileAsync('git', ['rev-parse', '--verify', '--quiet', `${tag}^{commit}`], { cwd })
+        .then(({ stdout }) => stdout.trim())
+        .catch(() => '');
+    if (!sha) {
+        throw new Error(`[gjsify flatpak sync-flathub] ${tag} does not resolve in ${cwd}, so whether it carries ${path} is unanswered. ` +
+            'Run `git fetch --tags`, pass --version <an existing tag>, or run from the app checkout.');
+    }
+}
 async function resolveLatestTag(cwd, verbose) {
     try {
         const { stdout } = await execFileAsync('git', ['describe', '--tags', '--abbrev=0'], { cwd });
@@ -258,14 +367,17 @@ export function editManifest(original, args) {
     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');
+    const isObject = (s) => typeof s === 'object';
+    let idx = args.sourceIndex ?? sources.findIndex((s) => isObject(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"`);
+    const entry = sources[idx];
+    if (!isObject(entry) || entry.type !== 'git') {
+        const what = isObject(entry) ? `type is "${entry.type}"` : `is the file reference "${entry}"`;
+        throw new Error(`[gjsify flatpak sync-flathub] modules[0].sources[${idx}] ${what}, expected a git source`);
     }
+    const source = entry;
     source.tag = args.tag;
     source.commit = args.commit;
     if (!source['x-checker-data']) {
@@ -275,12 +387,42 @@ export function editManifest(original, args) {
             'version-scheme': 'semantic',
         };
     }
+    // THE OFFLINE TARBALL LIST, which is the half of a Flathub bump that is easy
+    // to forget because nothing points at it. Flathub builds with the network
+    // unshared, so an app whose install reads a generated source list cannot
+    // build from the git checkout alone; the list has to live in the Flathub repo
+    // and be named here. Repointing tag and commit alone produces a manifest that
+    // looks correct and cannot build, and the error it eventually gives is
+    // whatever the app's build system says when its install fails.
+    //
+    // Measured: Learn6502 0.8.0 was the first release after its vendored
+    // dependency cache was dropped, and its Flathub build died on exactly this.
+    if (args.sourcesFile && !namesFile(sources, args.sourcesFile)) {
+        sources.push(args.sourcesFile);
+    }
     // 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' : '');
 }
+/**
+ * Is `file` already among the module's bare-string sources?
+ *
+ * Compared with `./` stripped, because flatpak-builder resolves a string source
+ * against the manifest's own directory: `./gjsify-sources.json` and
+ * `gjsify-sources.json` are one file. Compared as written, a manifest holding
+ * the dotted spelling grows a second reference and the same tarballs are
+ * spliced in twice — the duplicate `dest`/`dest-filename` pairs `gjsify flatpak
+ * sources` dedupes its own output to avoid.
+ */
+function namesFile(sources, file) {
+    const want = stripDotSlash(file);
+    return sources.some((entry) => typeof entry === 'string' && stripDotSlash(entry) === want);
+}
+function stripDotSlash(ref) {
+    return ref.replace(/^\.\//, '');
+}
 function detectIndent(json) {
     const match = json.match(/^\{\n( +)/);
     if (match)

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

@@ -1,3 +1,13 @@
+/**
+ * The generated offline tarball list, by the name both halves have to agree on.
+ *
+ * `gjsify flatpak sources` WRITES it; `gjsify flatpak sync-flathub` carries it
+ * into the Flathub repo and names it in the manifest. Each spelled the default
+ * itself, so changing one would have left the other reading a file nobody
+ * writes — and that shows up as a Flathub build which cannot install, four
+ * steps from its cause.
+ */
+export declare const FLATPAK_SOURCES_FILE = "gjsify-sources.json";
 /** Read package.json from a directory. Throws a helpful error if missing/invalid. */
 export declare function readPackageJson(dir: string): Record<string, unknown>;
 /** True if a name string looks like a reverse-DNS Flatpak app id. */

package/lib/commands/flatpak/utils.js

@@ -5,6 +5,16 @@
 // header. What is left here is what only these subcommands ask.
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+/**
+ * The generated offline tarball list, by the name both halves have to agree on.
+ *
+ * `gjsify flatpak sources` WRITES it; `gjsify flatpak sync-flathub` carries it
+ * into the Flathub repo and names it in the manifest. Each spelled the default
+ * itself, so changing one would have left the other reading a file nobody
+ * writes — and that shows up as a Flathub build which cannot install, four
+ * steps from its cause.
+ */
+export const FLATPAK_SOURCES_FILE = 'gjsify-sources.json';
 /** Read package.json from a directory. Throws a helpful error if missing/invalid. */
 export function readPackageJson(dir) {
     const path = resolve(dir, 'package.json');

package/lib/commands/index.d.ts

@@ -15,6 +15,7 @@ export { flatpakCommand } from './flatpak/index.js';
 export * from './ship.js';
 export * from './dlx.js';
 export * from './install.js';
+export * from './link.js';
 export * from './foreach.js';
 export * from './workspace.js';
 export * from './pack.js';

package/lib/commands/index.js

@@ -15,6 +15,7 @@ export { flatpakCommand } from './flatpak/index.js';
 export * from './ship.js';
 export * from './dlx.js';
 export * from './install.js';
+export * from './link.js';
 export * from './foreach.js';
 export * from './workspace.js';
 export * from './pack.js';

package/lib/commands/install.js

@@ -35,6 +35,7 @@ import { binDirOnPath, BUNDLER_ENGINE_PACKAGE, defaultGlobalLayout, hasBundlerEn
 import { resolveHostPlatform } from '../utils/platform-check.js';
 import { pruneAfterInstall } from '../utils/prune-prefix.js';
 import { addDependencyEntry, defaultRangeFromVersion, parseSpec, projectSpecsFromPackageJson, readPackageJson, writePackageJson, } from '../utils/pkg-json-edit.js';
+import { applyDevLinks, assertNoDevLinkUnderImmutable, devLinkRoot, prepareDevLinks, } from '../utils/dev-link.js';
 /**
  * Link type for the workspace↔workspace directory links.
  *
@@ -157,6 +158,12 @@ export const installCommand = {
                     '(--immutable forbids rewriting the lockfile). Drop one.');
                 return process.exit(1);
             }
+            // FAIL CLOSED before anything is resolved or written: an active `gjsify
+            // link` override would make a local development tree an input to the one
+            // install shape whose whole promise is "exactly what is committed" — CI,
+            // the Flatpak build, a release. Throws rather than exits so `index.ts`
+            // prints the message that names the override file (utils/dev-link.ts).
+            assertNoDevLinkUnderImmutable(process.cwd());
         }
         if (args.global) {
             if (!args.packages || args.packages.length === 0) {
@@ -426,6 +433,61 @@ function depKindFromArgs(args) {
         return 'optionalDependencies';
     return 'dependencies';
 }
+/**
+ * Wire the `gjsify link` development override for this prefix, and SAY SO.
+ *
+ * Called before the fetch phase for the same reason `wireWorkspaceSymlinks` is:
+ * these links point at local source and depend on no download, so writing them
+ * first means an install that dies mid-way still leaves a resolvable tree. Called
+ * again afterwards as a near no-op safety net.
+ *
+ * The announcement is not decoration. A linked tree changes what a build compiles
+ * without changing any file the consumer commits, so the one place it can be seen
+ * is the output of the command that re-applies it — this is exactly what a bare
+ * `npm link` does not do, and why the next `npm install` silently undoes it.
+ *
+ * Returns `null` when no override is present; throws when one names a checkout
+ * that is gone, is not a gjsify workspace, or is not BUILT (utils/dev-link.ts).
+ *
+ * `devLinkRoot` and not `prefix` verbatim: `assertNoDevLinkUnderImmutable` already
+ * walks up to the workspace root to decide whether an override is in play, and two
+ * answers to "which override governs this install" is one answer too many. Nothing
+ * rescued the difference either — the bare `install` path happens to delegate to
+ * the workspace root before reaching here, `install <pkg>` does not.
+ */
+function activateDevLinks(prefix, announce) {
+    const active = prepareDevLinks(devLinkRoot(prefix));
+    if (!active)
+        return null;
+    const written = applyDevLinks(active.links);
+    if (!announce)
+        return active;
+    console.log(`gjsify install: development link ACTIVE (${active.overridePath}) — ${active.links.length} ` +
+        `package(s) come from ${active.checkout}, linked rather than fetched ` +
+        `(${written.length} (re)written, ${active.links.length - written.length} already current):`);
+    const names = active.links.map((l) => l.name);
+    const shown = names.slice(0, 12);
+    console.log(`  ${shown.join(', ')}${names.length > shown.length ? `, +${names.length - shown.length} more` : ''}`);
+    console.log('  `gjsify unlink` restores the registry copies; `gjsify install --immutable` refuses while it exists.');
+    return active;
+}
+/**
+ * Re-apply the dev links after the install, and SAY SO when it changed anything.
+ *
+ * `applyDevLinks` returns what it had to (re)write, and both post-install call
+ * sites used to throw that away — so an installer that clobbered a link and got it
+ * put back looked exactly like one that never touched it. The safety net is
+ * supposed to be a no-op; the run where it is not is the one worth a line.
+ */
+function reportRewiredDevLinks(active) {
+    if (!active)
+        return;
+    const rewired = applyDevLinks(active.links);
+    if (rewired.length === 0)
+        return;
+    console.log(`gjsify install: re-applied ${rewired.length} development link(s) the install had replaced: ` +
+        `${rewired.map((l) => l.name).join(', ')}`);
+}
 async function projectInstallNative(args, signal) {
     const cwd = process.cwd();
     const pkgPath = join(cwd, 'package.json');
@@ -497,6 +559,7 @@ async function projectInstallNative(args, signal) {
     // re-acquires the same lock re-entrantly.
     const lock = await acquireInstallLock(cwd, { signal });
     try {
+        const devLinks = activateDevLinks(cwd, true);
         // Typed as NativeInstallOptions so the native-backend-only `optionalSpecs`
         // is CHECKED here instead of smuggled past an excess-property check;
         // `installPackages` forwards the object to that backend unchanged.
@@ -518,8 +581,14 @@ async function projectInstallNative(args, signal) {
                 ...optionalDependencyNames(pkg ? [pkg] : []),
                 ...(args['save-optional'] ? (args.packages ?? []).map((s) => parseSpec(s).name) : []),
             ]),
+            linkedNames: devLinks?.names,
         };
         const result = await installPackages(nativeOpts);
+        // The link survives the install — the point of reading the override at all.
+        // The return value is REPORTED, not dropped: a non-empty one means the
+        // install disturbed a link that the pre-fetch pass had already wired, which
+        // is a fact about the installer, not a routine no-op.
+        reportRewiredDevLinks(devLinks);
         // Only the `gjsify install <pkg>...` add-a-dep flow mutates the manifest;
         // the no-args refresh must not.
         if (args.packages && args.packages.length > 0 && pkg) {
@@ -650,6 +719,10 @@ async function workspaceInstallLocked(cwd, args, signal) {
         }
     }
     console.log(`gjsify install: ${workspaces.length} workspace(s), ${externalSpecs.size} external dep spec(s), ${symlinks.length} workspace symlink(s)`);
+    // A `gjsify link` override at the workspace ROOT governs the whole install, and
+    // is wired here for the same reason the shims and workspace symlinks are: before
+    // anything can fail on the network.
+    const devLinks = activateDevLinks(cwd, true);
     // EARLY, before the download/extract phase: the shims derive from workspace
     // manifests alone, while the heavy phase that follows can die mid-way (network,
     // timeout, crash). Writing them up front means a failed install can never leave
@@ -836,6 +909,7 @@ async function workspaceInstallLocked(cwd, args, signal) {
             // `types-dev/<lib>` workspace that also exists on npm and is pinned
             // transitively in the lockfile).
             workspaceNames: new Set(byName.keys()),
+            linkedNames: devLinks?.names,
             specOrigins: new Map([...specOrigins].map(([k, v]) => [k, [...v]])),
             // Aggregated over EVERY member, because the specs are: a name any member
             // declares as a plain dependency stays required.
@@ -865,6 +939,7 @@ async function workspaceInstallLocked(cwd, args, signal) {
             frozen: args.immutable,
             signal,
             workspaceNames: new Set(byName.keys()),
+            linkedNames: devLinks?.names,
             // Same aggregated answer as the root install: these specs are a SUBSET of
             // the root's, so classifying them differently would make one dep optional
             // at the root and required in a member.
@@ -874,6 +949,7 @@ async function workspaceInstallLocked(cwd, args, signal) {
     }
     // A near no-op safety net in case a later step disturbed a link.
     await wireWorkspaceSymlinks();
+    reportRewiredDevLinks(devLinks);
     // Now that the tree is materialised, refresh the shims' GJS preamble with the
     // native prebuild dirs that only became discoverable after the install (on a
     // fresh checkout `detectNativePackages` finds nothing before extraction).

package/lib/commands/link.d.ts

@@ -0,0 +1,13 @@
+import type { LeafCommand } from '../types/index.js';
+interface LinkOptions {
+    checkout: string;
+    packages?: string[];
+    'dry-run'?: boolean;
+}
+interface UnlinkOptions {
+    'dry-run'?: boolean;
+    install?: boolean;
+}
+export declare const linkCommand: LeafCommand<unknown, LinkOptions>;
+export declare const unlinkCommand: LeafCommand<unknown, UnlinkOptions>;
+export {};